# JavaScript SDK

> Learn how to generate images and PDFs with the bannerify-js package.

Canonical: https://bannerify.co/docs/sdk/js/overview

`bannerify-js` is the Bannerify client for JavaScript and TypeScript. It has types for every option and returns errors as values, so a failed request does not throw.

## Install

<Tabs>
  <Tab title="npm">
    ```bash
    npm install bannerify-js
    ```
  </Tab>
  <Tab title="pnpm">
    ```bash
    pnpm add bannerify-js
    ```
  </Tab>
  <Tab title="yarn">
    ```bash
    yarn add bannerify-js
    ```
  </Tab>
  <Tab title="bun">
    ```bash
    bun add bannerify-js
    ```
  </Tab>
</Tabs>

## Create a client

You need an API key. Create one on the **API Keys** page of the dashboard and keep it on the server.

```ts
import { Bannerify } from "bannerify-js"

const bannerify = new Bannerify(process.env.BANNERIFY_API_KEY!)
```

`createClient(apiKey)` returns the same client.

## Generate an image

```ts
import { writeFile } from "node:fs/promises"

const { result, error } = await bannerify.createImage("tpl_xxx", {
  modifications: [{ name: "headline", text: "Summer sale" }],
})

if (error) throw new Error(error.message)

await writeFile("banner.png", Buffer.from(result))
```

`result` is an `ArrayBuffer` that holds the image bytes.

## Methods

| Method | Result | Use it to |
| --- | --- | --- |
| `createImage` | `ArrayBuffer` | Get the image bytes |
| `createPdf` | `ArrayBuffer` | Get a PDF |
| `createStoredImage` | URL string | Get a hosted image URL |
| `renderVideo` (Beta) | Async iterator of events | Render a video and follow its progress |
| `renderAndWaitVideo` (Beta) | URL string | Render a video and get its MP4 URL |
| `createVideo` (Beta) | Video id | Start a video and get its id at once |
| `getVideo` (Beta) | Video status and URL | Read a video again by its id |
| `watchVideo` (Beta) | Async iterator of events | Follow a video again by its id |
| `generateImageSignedUrl` | URL string | Build a link that renders when someone opens it |

[Create images and PDFs](https://bannerify.co/docs/sdk/js/apis/create-image) covers the first three, [Render videos](https://bannerify.co/docs/sdk/js/apis/render-video) covers the video methods, and [Signed URL](https://bannerify.co/docs/sdk/js/apis/signed-url) covers the last one.

## Handle errors

Every method except `generateImageSignedUrl` returns an object with either `result` or `error`. TypeScript narrows the type after you check `error`.

```ts
const { result, error } = await bannerify.createImage("tpl_xxx")

if (error) throw new Error(`${error.code}: ${error.message}`)

console.log(result.byteLength)
```

An `error` has four fields: `code`, `message`, `docs`, and `requestId`. `docs` links to the page for that code. Send `requestId` to support when you need help with a request.

The SDK adds two codes of its own. `INVALID_FORMAT` means the image format is not `png`, `jpeg`, or `webp`. `TIMEOUT_ERROR` means the request ran past the timeout. A failure that does not come from the API, such as a lost connection, throws.

`generateImageSignedUrl` returns a string and throws when the format is not supported.

## Options

```ts
const bannerify = new Bannerify(process.env.BANNERIFY_API_KEY!, {
  timeout: 30_000,
})
```

| Option | Default | Description |
| --- | --- | --- |
| `timeout` | `60000` | Request timeout in milliseconds |
| `baseUrl` | `https://api.bannerify.co/v1` | The API base URL |
| `fetch` | The global `fetch` | A custom `fetch`, for tests or a proxy |

## Related

- [Previous: SDKs](https://bannerify.co/docs/sdk/overview)
- [Next: Create images and PDFs in JavaScript](https://bannerify.co/docs/sdk/js/apis/create-image)
- [Documentation index](https://bannerify.co/docs/llms.txt)