@optiqlabs/onecms-sdk

Small TypeScript client and optional React helpers for the OneCMS public Content API: GET /api/v1/projects/:projectId/... authenticated with a cms_live_ (published only) or cms_preview_ (includes drafts) API key.

It uses @optiqlabs/onecms-types to validate list/search query objects before building URLs, so query params match what the API expects.

What it does

• createOneCmsClient(config) — returns a client with methods that call fetch with Authorization: Bearer <apiKey>.
• React (optional) — OneCmsProvider, useOneCmsClient, usePlatformMeta, PostBodyHtml (HTML from the API with automatic Mermaid diagram hydration), and OneCmsMermaidBlock for rendering a single diagram from TipTap mermaid source when you build a custom JSON renderer.

It does not cover admin routes, JWT cookies, or the hosted platform password flow (/api/v1/platform/*). Those are separate from this SDK.

Install

npm install @optiqlabs/onecms-sdk @optiqlabs/onecms-types zod

react is an optional peer — install react only if you use the React exports.

Configuration

| Field | Description | | ----------- | ------------------------------------------------------------------------------------------------ | | baseUrl | API root with no trailing slash, e.g. https://cms.example.com/api/v1 | | projectId | Public project id (the stable projectId field on the project, not necessarily the Mongo _id) | | apiKey | cms_live_… or cms_preview_… key from project settings |

Preview keys can read drafts; live keys only see published posts (per server rules).

Client API

All methods throw if the response is not OK (message includes status and a short body snippet).

| Method | HTTP | Notes | | ----------------------- | -------------------------- | --------------------------------------------------------------------------------------------------- | | listPosts(query) | GET .../posts?... | Query validated with listPostsQuerySchema (page, limit, tag, sort, contentFormat, etc.) | | searchPosts(query) | GET .../posts/search?... | Validated with publicSearchQuerySchema | | getPost(slug, query?) | GET .../posts/:slug?... | Optional contentFormat (json | markdown | html), include: "author" | | listTags() | GET .../tags | | | getPlatformMeta() | GET .../platform-meta | Returns { name, projectId, theme } for themed consumer sites |

Return types are currently unknown or a narrow object for getPlatformMeta — parse/assert on your side with Zod if you need stricter typing.

Usage (vanilla TS)

import { createOneCmsClient } from "@optiqlabs/onecms-sdk";

const client = createOneCmsClient({
  baseUrl: "https://your-api.example.com/api/v1",
  projectId: "your-public-project-id",
  apiKey: process.env.CMS_LIVE_KEY!, // keep server-side in production
});

const posts = await client.listPosts({
  page: 1,
  limit: 10,
  contentFormat: "markdown",
});

const one = await client.getPost("my-post-slug", {
  contentFormat: "html",
  include: "author",
});

const meta = await client.getPlatformMeta();

Next.js and security

Prefer Server Components, Route Handlers, or server actions so the API key is never bundled for the browser. If you must pass a key client-side, assume it is public (any user can extract it from the bundle).

React provider

import { OneCmsProvider, useOneCmsClient } from "@optiqlabs/onecms-sdk";

function App() {
  return (
    <OneCmsProvider
      config={{
        baseUrl: import.meta.env.VITE_CMS_API_BASE,
        projectId: import.meta.env.VITE_CMS_PROJECT_ID,
        apiKey: import.meta.env.VITE_CMS_LIVE_KEY,
      }}
    >
      <Posts />
    </OneCmsProvider>
  );
}

useOneCmsClient() returns the same client API as createOneCmsClient.

PostBodyHtml

Renders an HTML string from getPost(..., { contentFormat: "html" }). Default wrapper class is onecms-post-body (override with className).

• mermaid (default true) — After mount, runs Mermaid on elements with class onecms-mermaid inside the body (the shape produced by OneCMS tipTapToHtml for diagram blocks). Set mermaid={false} if you only want raw HTML (no client-side diagram pass).

Use a client component (e.g. "use client" in Next.js App Router) when you rely on Mermaid hydration.

import { PostBodyHtml } from "@optiqlabs/onecms-sdk";

const html = String(post.content); // contentFormat: "html"
<PostBodyHtml html={html} />;

OneCmsMermaidBlock

Renders one diagram from a source string (e.g. TipTap JSON attrs.source on a mermaid node). Use when you consume contentFormat: "json" and map nodes yourself.

import { OneCmsMermaidBlock } from "@optiqlabs/onecms-sdk";

<OneCmsMermaidBlock source={`graph TD\n  A --> B`} />;

Sanitize or trust HTML from the CMS on the server if you expose it to untrusted pipelines.

Hosted platform site

The password-protected hosted platform UI uses cookie sessions on api/v1/platform/* and is not implemented by this SDK (which uses Bearer keys only).

Related

• @optiqlabs/onecms-types — Zod schemas for posts, queries, and domain types.
• @optiqlabs/onecms-utils — TipTap/Markdown/slug helpers for custom pipelines.

License

See the OneCMS monorepo license for this package’s terms when published from source.