# TypeScript SDK

> Install the Brix TypeScript SDK from brixsignage.com and call the API with typed methods. Runs in Node, Deno, Bun, browsers and Cloudflare Workers.

Source: https://brixsignage.com/developers/sdk/

The Brix TypeScript SDK is a typed client for the [REST API](/developers/api/). It has one method for each operation in the [OpenAPI spec](https://api.brixsignage.com/v1/openapi.json), with request and response types. It has no runtime dependencies and uses the platform `fetch`, so it runs in Node 18 or later, Deno, Bun, browsers and Cloudflare Workers.

The package name is `@brixsignage/sdk`. Brix hosts it on brixsignage.com. It is not on the npm registry.

## Install

```bash
npm install https://brixsignage.com/sdk/latest.tgz
```

pnpm and yarn take the same URL:

```bash
pnpm add https://brixsignage.com/sdk/latest.tgz
yarn add @brixsignage/sdk@https://brixsignage.com/sdk/latest.tgz
```

`latest.tgz` is always the newest version. To pin a version, install its own file, for example `https://brixsignage.com/sdk/brix-sdk-0.1.0.tgz`. The list of versions, with a SHA-256 checksum and the npm integrity hash for each file, is at [brixsignage.com/sdk/manifest.json](https://brixsignage.com/sdk/manifest.json).

### Without a package manager

Deno, a browser page or a Worker can import the ES module directly:

```ts
import { BrixClient } from "https://brixsignage.com/sdk/v1/index.js";
```

`/sdk/v1/index.js` is the newest version. `/sdk/<version>/index.js` is a fixed version. The type declarations are next to the module (`index.d.ts`), and Deno finds them without extra setup.

Do not put an API key in code that runs in a browser. Anyone who opens the page can read it. Call the API from a server or a Worker.

## Create a client

You need an API key. See [Quickstart](/developers/quickstart/#1-create-an-api-key) to make one.

```ts
import { BrixClient } from "@brixsignage/sdk";

const brix = new BrixClient({ token: process.env.BRIX_API_KEY! });
```

| Option | Default | What it does |
| --- | --- | --- |
| `token` | none | Your API key (`ak_...`). Sent as `Authorization: Bearer <key>`. |
| `baseUrl` | `https://api.brixsignage.com` | The API origin. |
| `timeoutInSeconds` | 60 | Time limit for each request. |
| `maxRetries` | 2 | Retries for a 408, 429, 502, 503 or 504 response, with backoff. |
| `fetch` | global `fetch` | A different `fetch` implementation. |
| `headers` | none | Extra headers on every request. |

## Example: list screens and assign a playlist

This script prints your screens, then makes the first screen play the first playlist by default. Save it as `brix.ts` and run it with `BRIX_API_KEY=ak_... npx tsx brix.ts`.

```ts
import { BrixClient, BrixError } from "@brixsignage/sdk";

const brix = new BrixClient({ token: process.env.BRIX_API_KEY! });

async function main() {
  // 1. Who am I? The key's workspace and permissions.
  const { data: me } = await brix.me.getMe();
  console.log("workspace:", me.workspace.name);

  // 2. List screens (up to 50; pass nextCursor as cursor for the next page).
  const { data: screens, nextCursor } = await brix.screens.listScreens({ limit: 50 });
  for (const screen of screens) console.log(screen.id, screen.name, screen.status);
  if (nextCursor) console.log("more screens after", nextCursor);

  // 3. Pick a playlist.
  const { data: playlists } = await brix.playlists.listPlaylists();
  const screen = screens[0];
  const playlist = playlists[0];
  if (!screen || !playlist) return;

  // 4. Assign it: the screen plays this playlist by default from now on.
  await brix.screens.assignContent({ id: screen.id, contentKind: "playlist", contentId: playlist.id });
  console.log(`assigned ${playlist.name} to ${screen.name}`);
}

main().catch((err) => {
  if (err instanceof BrixError) {
    console.error(`Brix API error ${err.statusCode}:`, err.body);
    process.exit(1);
  }
  throw err;
});
```

The key needs `screen.view`, `screen.edit` and `playlist.view`. `contentKind` is one of `playlist`, `schedule`, `layout`, `creative`, `signage`, `app` or `media`. Send `contentKind: null` to clear the assignment. For many screens at once, use `brix.screens.bulkAssignContent({ screenIds, contentKind, contentId })`.

## Example: cast content for one hour

A cast is a timed takeover. The screens go back to their normal content when it ends.

```ts
const { data: cast } = await brix.casts.castContent({
  contentKind: "playlist",
  contentId: "pl_...",
  scopeKind: "screens",
  screenIds: ["scr_..."],
  expiresAt: new Date(Date.now() + 60 * 60_000).toISOString(),
});

// End it early:
await brix.casts.endCast({ id: cast.id });
```

Always send `scopeKind`. If you leave it out, the cast goes to every screen the key can reach. The key needs `screen.cast`.

## Errors

A response with a 4xx or 5xx status throws `BrixError`. It has `statusCode` and `body` (the API's `{ "error", "message" }` object). A request that runs past `timeoutInSeconds` throws `BrixTimeoutError`. See [Errors and rate limits](/developers/errors-and-rate-limits/) for each error code.

## Types

Every request and response type is in the `Brix` namespace:

```ts
import { Brix } from "@brixsignage/sdk";

const request: Brix.CastContentRequest = { contentKind: "media", contentId: "med_...", scopeKind: "all" };
```

The type declarations do not need `@types/node`. They type-check under `strict` in a browser, Deno, Bun or Workers project with only the DOM and ES2022 libraries. File uploads take a `Blob`, `File`, `ReadableStream`, `Uint8Array` or `ArrayBuffer`. In Node they also take a `Buffer` or a stream from `fs.createReadStream`.

## Find a method

Methods are grouped by resource, the same groups as the [API reference](/developers/api/): `brix.screens`, `brix.playlists`, `brix.media`, `brix.schedules`, `brix.casts` and so on. The method name is the operation's `operationId` in the OpenAPI spec. For example, `GET /v1/screens` is `listScreens` and `POST /v1/screens/{id}/assign` is `assignContent`.

For an endpoint without a method, `brix.fetch(path, init)` sends a request with the same key, retries and timeout.

## Versions and checksums

The SDK is generated from the public OpenAPI spec, so it follows the API. Version numbers use semver. A published version never changes. [manifest.json](https://brixsignage.com/sdk/manifest.json) lists each version with:

- `tarball.url`, `tarball.sha256` and `tarball.integrity` (the npm `sha512-` hash)
- `esm.url` and `types.url`, with their SHA-256
- `gitCommit`: the source commit it was built from
- `specSha256`: the OpenAPI document it was generated from

To check a download:

```bash
curl -sO https://brixsignage.com/sdk/brix-sdk-0.1.0.tgz
shasum -a 256 brix-sdk-0.1.0.tgz
```