JavaScript / TypeScript SDK

The @castbrick/js package is the official SDK for JavaScript and TypeScript. It works in Node.js 18+, Next.js, SvelteKit, Vite, Bun, and Deno — any environment that supports the native fetch API.

Installation

npm install @castbrick/js

Initialization

import { CastBrick } from "@castbrick/js";

const cb = new CastBrick({ apiKey: process.env.CASTBRICK_API_KEY! });

Get your API key from the CastBrick dashboard.

For a different environment (staging, local):

const cb = new CastBrick({
  apiKey: process.env.CASTBRICK_API_KEY!,
  baseUrl: "http://localhost:5000",
});

SMS

Send an SMS

const result = await cb.sms.send({
  recipients: ["+244923000000", "+244912000000"],
  content: "Your verification code is 1234",
});

console.log(result.messageId, result.recipientCount);
// { messageId: "...", recipientCount: 2 }

Use a Sender ID

await cb.sms.send({
  recipients: ["+244923000000"],
  content: "Hello from MyApp!",
  senderId: "MyApp",
});

Send to a Contact List

await cb.sms.send({
  recipients: [],
  content: "Weekend promo — 50% off!",
  contactListId: "your-list-id",
});

Schedule for later

await cb.sms.send({
  recipients: ["+244923000000"],
  content: "This message is scheduled.",
  scheduledAt: "2026-04-01T09:00:00Z",
});

List messages

const { items, totalCount } = await cb.sms.list(1, 20);

Get a message

const message = await cb.sms.get("message-id");
console.log(message.status); // "queued" | "sent" | "delivered" | "failed"

Cancel a scheduled SMS

await cb.sms.cancelScheduled("message-id");

Contacts

List contacts

const { items } = await cb.contacts.list(1, 20);

// with search
const { items } = await cb.contacts.list(1, 20, "João");

Create contacts

Accepts comma or newline-separated phone numbers:

await cb.contacts.create({
  phoneNumbers: "+244923000000, +244912000000",
});

Delete a contact

await cb.contacts.delete("contact-id");

Contact Lists

// List all contact lists
const { items } = await cb.contacts.listLists();

// Create a list
const list = await cb.contacts.createList("VIP Customers");

// Add a contact to a list
await cb.contacts.addToList(list.id, "contact-id");

// Remove a contact from a list
await cb.contacts.removeFromList(list.id, "contact-id");

Broadcasts

A broadcast sends the same message to a large audience.

Create and send

const id = await cb.broadcasts.create({
  name: "April Promo",
  message: "50% off this weekend!",
  contactListId: "your-list-id",
  senderId: "MyApp",
});

await cb.broadcasts.send(id);

Schedule a broadcast

const id = await cb.broadcasts.create({
  name: "Scheduled Promo",
  message: "Sale starts tomorrow!",
  contactListId: "your-list-id",
});

await cb.broadcasts.update(id, {
  name: "Scheduled Promo",
  message: "Sale starts tomorrow!",
  scheduleAt: "2026-04-05T08:00:00Z",
});

await cb.broadcasts.send(id);

Other operations

const { items } = await cb.broadcasts.list();
const broadcast = await cb.broadcasts.get(id);
await cb.broadcasts.cancel(id);
await cb.broadcasts.duplicate(id);
await cb.broadcasts.delete(id);

Error Handling

All API errors throw a CastBrickApiError with a status (HTTP code) and a message.

import { CastBrick, CastBrickApiError } from "@castbrick/js";

try {
  await cb.sms.send({ recipients: ["+244923000000"], content: "Hello!" });
} catch (err) {
  if (err instanceof CastBrickApiError) {
    console.error(`${err.status}: ${err.message}`);
    // 401 → invalid or revoked API key
    // 402 → insufficient credits
    // 422 → validation error
  }
}

TypeScript

The SDK is fully typed. All request and response types are exported:

import type {
  SendSmsRequest,
  SendSmsResponse,
  Contact,
  ContactList,
  Broadcast,
  PagedResult,
} from "@castbrick/js";

Requirements

Environment	Minimum version
Node.js	18+
Next.js	13+
SvelteKit	any
Bun	any
Deno	any
Browser	Chrome 95+ / Firefox 98+ / Safari 16+

JavaScript / TypeScript SDK

On this page