@betttercms/sdk

Typed JavaScript/TypeScript client for the BetterCMS Delivery API.

Installation

npm install @betttercms/sdk
# or
pnpm add @betttercms/sdk
# or
yarn add @betttercms/sdk

Quick start

import { BetterCMS } from "@betttercms/sdk";

const client = BetterCMS.site({ workspace: "my-workspace" });

// Fetch a single page
const page = await client.getContent("home");
console.log(page.entry.title);

// List pages (paginated)
const result = await client.listContent({ page: 1, perPage: 20 });
console.log(result.items);
console.log(`Next page? ${result.hasNextPage}`);

// Iterate all pages automatically
for await (const item of client.listContentAll()) {
  console.log(item.entry.title);
}

// Collect with a limit
const top = await client.listContentAll().all({ limit: 500 });

With an API key

const client = BetterCMS.site({
  workspace: "my-workspace",
  apiKey: process.env.BETTERCMS_API_KEY,
});

TypeScript

This package is written in TypeScript and ships its own type declarations. No separate @types/ package needed. All types from @betttercms/types are re-exported.

Error handling

The SDK throws BetterCMSError on failures. Each error has a semantic code:

import { BetterCMSError, ErrorCodes } from "@betttercms/sdk";

try {
  const page = await client.getContent("does-not-exist");
} catch (err) {
  if (err instanceof BetterCMSError) {
    switch (err.code) {
      case ErrorCodes.CONTENT_NOT_FOUND:
        // 404
        break;
      case ErrorCodes.UNAUTHORIZED:
        // 401
        break;
      case ErrorCodes.FORBIDDEN:
        // 403
        break;
      case ErrorCodes.RATE_LIMITED:
        // 429
        break;
      case ErrorCodes.INTERNAL_ERROR:
        // 5xx
        break;
      case ErrorCodes.NETWORK_ERROR:
        // Network failure
        break;
    }
  }
}

API

BetterCMS.site(options)

| Option | Type | Required | Default | | --------- | ------ | -------- | -------------------------- | | workspace | string | Yes | — | | apiKey | string | No | — | | baseUrl | string | No | https://api.bettercms.ai/v1 |

Returns a BetterCMSDeliveryClient instance.

client.getContent(slug)

Fetches a single published page by slug.

const content = await client.getContent("about-us");

client.listContent(options?)

Returns a paginated result object.

const result = await client.listContent({ page: 1, perPage: 20 });
// result.items, result.hasNextPage, result.totalPages, ...

client.listContentAll(options?)

Returns an async iterator that transparently follows pagination.

for await (const item of client.listContentAll()) { ... }

// With a limit:
const items = await client.listContentAll().all({ limit: 100 });