@relayer-cms/sdk

Typed Delivery SDK for Relayer — published content, draft preview, populate, filter, and search.

npm i @relayer-cms/sdk

Quickstart

import { createRelayerClient } from "@relayer-cms/sdk";

const client = createRelayerClient({
  baseUrl: process.env.RELAYER_URL!,
  bearerToken: process.env.RELAYER_DELIVERY_TOKEN,
  previewSecret: process.env.PREVIEW_SECRET,
});

const page = await client.listDocuments("article", {
  locale: "en-US",
  search: "hello",
  populate: ["cover", "author"],
  depth: 1,
});

const post = await client.getByRoute("article", "my-slug", {
  locale: "en-US",
  status: "draft", // requires previewSecret; get/by-route only
  populate: ["author"],
});

Form submissions (server / BFF only)

// app/api/contact/route.ts — runs on your server, never in the browser
const client = createRelayerClient({
  baseUrl: process.env.RELAYER_URL!,
  bearerToken: process.env.RELAYER_SUBMIT_TOKEN!, // cms_del_… with the `create` scope
});

const { documentId } = await client.submitDocument("contact_form", {
  locale: "en-US", // optional
  data: { name, email, message }, // non-private fields only
});

submitDocument posts to POST /v1/delivery/content-types/:uid/submissions. The entry is saved as a draft (never published) and cannot be read back through Delivery. The content type must have form submissions enabled.

Upload a file, then submit (BFF)

const uploaded = await client.uploadAsset(fileBlob, "resume.pdf");
await client.submitDocument("job_application", {
  locale: "en-US",
  data: { name, resume: uploaded.id },
});

uploadAsset posts multipart to POST /v1/delivery/assets (Public asset, create-scoped token). Put the returned id on media fields. Lean Delivery still returns UUIDs; use populate for { id, url, … } (Private/deleted → url: null on published).

Server / BFF only. Do not put a token with the create scope in browser code. Add your own rate limiting and bot protection (e.g. captcha) in the BFF route before calling Relayer.

Next.js helpers

import { createRelayerClientForNext } from "@relayer-cms/sdk/next";

const client = createRelayerClientForNext({
  baseUrl: process.env.RELAYER_URL!,
  draft: true,
  tags: ["route:article:my-slug"],
  previewSecret: process.env.PREVIEW_SECRET,
});

Notes

• Wire API stays under /v1/delivery/* (token prefixes cms_del_ unchanged).
• List is published-only — draft applies to getDocument / getByRoute only.
• Fields marked private in the schema are never returned by Delivery.
• Use RELAYER_URL / RELAYER_DELIVERY_TOKEN.

See docs/CONNECT_SITE.md for preview, webhooks, and populate recipes.

Publish

Package versions are explicit SemVer. The cd-npm.yml release workflow publishes verified artifacts under @relayer-cms through trusted publishing.

See docs/NPM_PUBLISHING.md (trusted publishing/OIDC).