@formecms/sdk

TypeScript SDK for Forme CMS — typed HTTP client for the Management and Delivery APIs.

Installation

pnpm add @formecms/sdk
# or
npm install @formecms/sdk

Quick start

import { createClient } from "@formecms/sdk";

// Read Key → DeliveryClient (published content)
const delivery = createClient({
  baseUrl: "https://delivery.forme.sh",
  apiKey: "ce_read_YOUR_KEY_HERE",
});

const entries = await delivery.entries.list({ limit: 10 });
if (entries.ok) {
  console.log(entries.data.items);
}

// Secret Key → ManagementClient (create, update, publish)
const mgmt = createClient({
  baseUrl: "https://management.forme.sh",
  apiKey: "ce_secret_YOUR_KEY_HERE",
});

const model = await mgmt.contentModels.create({
  apiId: "BlogPost",
  name: "Blog Post",
  type: "page",
  fields: [
    { apiId: "title", name: "Title", type: "shortText", required: true, localized: true },
    { apiId: "body", name: "Body", type: "richText", localized: true },
  ],
});

The SDK auto-detects your key type: ce_secret_ keys return a ManagementClient, ce_read_ keys return a DeliveryClient.

Documentation

• SDK Guide — full API reference with examples
• Quickstart — go from zero to published content in 15 minutes
• API Reference — REST API details

Versioning policy

The SDK is pre-1.0. Our version-bump policy differs from strict post-1.0 semver:

• Patch bump (0.Y.Z → 0.Y.Z+1) — default choice. Use for all additive, backwards-compatible changes, including substantial new feature surface (new namespaces, new methods, new optional parameters, new types). Most epic-sized feature adds land as patch bumps.
• Minor bump (0.Y.0 → 0.(Y+1).0) — reserved for breaking changes: removing or renaming an exported symbol, changing a method signature in a breaking way, dropping a supported runtime, or a semantic change in an existing method's behavior that consumers must react to.
• Major bump (1.0.0) — when we declare API stability. Not yet.

Both @formecms/sdk (TypeScript) and formecms/sdk-swift (Swift) follow this same policy and track the same version number. See docs/04-engineering/workflow.md §8.1.

When publishing, pass the chosen version to the workflow:

gh workflow run "Publish SDK" --field version=0.1.2

License

MIT