@petacms/sdk

Official JavaScript / TypeScript SDK for PetaCMS — a drop-in CMS overlay for existing websites.

Install

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

Quick start

import { createClient } from '@petacms/sdk';

const peta = createClient({ siteId: 'site_01HK3Y5R6YVZJXA0B1C2D3E4F5' });

const { posts } = await peta.listPosts({ limit: 10 });
for (const post of posts) {
  console.log(post.title, post.publishedAt);
}

const detail = await peta.getPost('hello-world');
console.log(detail.bodyHtml);

Runtimes

• Node.js 18+
• Modern browsers (pass as a <script type="module"> if needed)
• Cloudflare Workers, Vercel Edge, Deno, Bun — anywhere fetch is available.

The SDK is zero-dependency and fully tree-shakeable.

API

createClient(options)

| Option | Type | Required | Description | | ---------- | ---------------------- | -------- | -------------------------------------------------------------------------- | | siteId | string | ✓ | The site ID you see in the PetaCMS dashboard. | | baseUrl | string | | CDN base URL. Defaults to https://cdn.peta-cms.com. | | fetch | typeof fetch | | Custom fetch implementation (useful for bound fetchers in edge runtimes). | | timeoutMs| number | | Per-request timeout. Defaults to 10_000. | | headers | Record<string,string>| | Default headers sent on every request. |

Methods

• listPosts({ limit?, offset? }): Promise<ListPostsResult> — list published posts newest first.
• getPost(slug): Promise<PostDetail> — fetch a single post by slug.
• listCategories(): Promise<CategoryRecord[]> — list site categories.
• getSnippet(key): Promise<SnippetRecord | null> — fetch a snippet; returns null on 404.

Error handling

Failed requests throw a PetaCmsError instance with .status (HTTP status) and .code (server-provided error code when available).

import { PetaCmsError } from '@petacms/sdk';

try {
  await peta.getPost('missing');
} catch (e) {
  if (e instanceof PetaCmsError && e.status === 404) {
    // handle not-found
  } else {
    throw e;
  }
}

License

Apache-2.0 © MOVON