@conapps/cms-sdk

@conapps/cms-sdk

Typed client for the platform's Content Delivery API — the read-only side of the CMS, the one your website or app talks to. Runs in Node 18+, Nuxt (SSR + client), Vue and the browser.

npm install @conapps/cms-sdk

Before you write any code: three values

Every call needs these, and every one of them comes from the platform UI. Getting them is the whole setup — there is no key file to download and no dashboard to generate a long-lived token in.

Two endpoints work, and the bare gateway host is not one of them.

endpoint	Result
https://cms.conapps.net	✅ the delivery host — a CDN can sit in front of it, no gateway hop
https://api.conapps.net/api/v1/workspaces/<ws>/services/content-management	✅ through the gateway, same responses
https://api.conapps.net	❌ 404 on every call

Prefer the delivery host: it is what the CDN caching is built around. The gateway route is there when your network only allows one platform host, and it needs the full service prefix — the SDK appends /delivery/v1/spaces/… to whatever you give it, so the workspace id legitimately appears twice.

The third row is the trap, and it is silent: the gateway answers 404 for a path it does not route, which reads exactly like content that does not exist.

There are no CMS "delivery tokens" to create. Earlier versions of this document sent people looking for Settings → Content → Delivery Tokens; that screen does not exist and never did. Machine access on this platform is always an API integration exchanged for a short-lived token — see below.

Quick start

import { createCmsClient } from '@conapps/cms-sdk';

const cms = createCmsClient({
  endpoint:    'https://cms.conapps.net',
  workspaceId: 'ws_4a7d',
  auth: {
    issuer:       'https://auth.conapps.net/realms/platform',
    clientId:     process.env.CMS_CLIENT_ID!,
    clientSecret: process.env.CMS_CLIENT_SECRET!,
  },
  defaultLocale: 'de-DE',
});

const posts = await cms.getEntries({ contentType: 'blogPost', take: 10 });
const post  = await cms.getEntry('abc123', { include: 2 });
const found = await cms.getEntryBy('blogPost', 'slug', 'hello-world');

That is the complete setup. The SDK fetches the token, caches it, refreshes it before it expires and retries once if the server rejects it anyway.

Authentication, and the mistake everybody makes once

An access token from this platform lives about five minutes. Handing the SDK a token string therefore works exactly as long as your first test run and then fails forever, with a 401 that looks like a wrong secret:

// ✗ Works for five minutes. Then 401, in production, at 3am.
createCmsClient({ …, token: process.env.CMS_TOKEN! })

Three supported shapes, in the order you should reach for them:

// ✓ 1. Let the SDK own the token. Server-side.
createCmsClient({ …, auth: { issuer, clientId, clientSecret } })

// ✓ 2. Your own provider, if the token comes from somewhere else
//      (a secrets broker, another service, a test double).
createCmsClient({ …, token: async () => myBroker.currentCmsToken() })

// ✓ 3. A fixed string — only for a script that finishes in minutes.
createCmsClient({ …, token: 'eyJhbGciOi…' })

clientSecret is a password for the workspace. Never ship it to a browser. The browser calls your backend, your backend calls this SDK. The Nuxt example below is built that way.

You can also build the provider yourself and share one token across several clients — it is exported from this package, so there is no second package to install:

import { createTokenProvider, createCmsClient } from '@conapps/cms-sdk';

const token = createTokenProvider({ issuer, clientId, clientSecret });
const master = createCmsClient({ endpoint, workspaceId, token, environment: 'master' });
const staging = createCmsClient({ endpoint, workspaceId, token, environment: 'staging' });

When a call is rejected

CmsAuthError carries a reason that says which of the usual four causes it is, read out of the token that was just sent:

CmsAuthError: Delivery API rejected the request (403): the token is issued for
workspace ws_other, but the request addresses ws_4a7d — an API integration
belongs to exactly one workspace

Failures from the token endpoint are a PlatformAuthError and are translated the same way — invalid_client becomes a sentence about a rotated secret rather than an OAuth error code.

API

createCmsClient(opts) / new CmsClient(opts)

Methods

client.getContentTypes(): Promise<Collection<ContentType>>;   // apiIdentifier is what `contentType` wants
client.getEntries<TFields>(query?): Promise<Collection<Entry<TFields>>>;
client.getEntry<TFields>(id, query?): Promise<Entry<TFields> | null>;
client.getEntryBy<TFields>(contentType, field, value, query?): Promise<Entry<TFields> | null>;
client.getAsset(id): Promise<Asset | null>;
client.withPreview(context): CmsClient;
client.clearCache(): void;

include: number resolves linked entries and assets up to that depth — the SDK fetches each id and inlines the resolved object back into the field.

getEntryBy is a scan, and says so

The Delivery API has no server-side filter on arbitrary fields. getEntryBy therefore pages through the content type and compares locally:

await cms.getEntryBy('blogPost', 'slug', 'hello-world')            // walks all pages
await cms.getEntryBy('blogPost', 'slug', 'x', { maxScan: 1000 })   // throws past 1000

Cheap for a few hundred entries, a real cost for thousands. On a hot path, keep your own slug → id map and use getEntry.

Until 0.3.0 this helper read a single page of 100 and returned null for everything after it. A site launched fine and began 404ing its older posts months later, with nothing in any log. It now walks to the end, and throws at maxScan rather than answering null to a question it did not finish asking.

Typed fields

interface BlogPost {
  title: string;
  slug: string;
  body: string;
  coverImage?: { id: string; url?: string; fileName: string };
}

const post = await cms.getEntry<BlogPost>('abc123', { include: 1 });
post?.fields.title; // string

Errors

import {
  CmsError, CmsAuthError, CmsNotFoundError, CmsScanLimitError, PlatformAuthError,
} from '@conapps/cms-sdk';

Everything this SDK throws extends CmsError. One catch on the base class is complete.

status is the HTTP status — 0 when there was no response: the request never left (scan limit) or never arrived (connection, token endpoint).

PlatformAuthError stays exported for callers who use createTokenProvider directly; when the client fetches the token, it arrives wrapped as CmsTokenError.

Preview

withPreview(context) returns a second client that reads the same space with an editor's context — the draft revision, a chosen instant, a chosen audience. Preview tickets are verified with @conapps/cms-preview; this package only carries the resulting context into the query.

const ticket = await previewHandler.read(cookieHeader)   // @conapps/cms-preview
const client = ticket ? cms.withPreview(ticket.context) : cms

const posts = await client.getEntries({ contentType: 'blogPost' })

A separate instance, not a flag: the public client keeps its cache and its published view, so a preview can never write a draft into an entry the public path reads back. The preview client cannot cache — cacheTtlMs is forced to 0, because the cache key is the URL and two contexts differing only in a forgotten parameter would share an entry.

?preview=true needs a token carrying content-management:preview. Put that scope on a separate API integration, never on the public one: with it on the public client one bug makes drafts public, and without it the Delivery API silently ignores the parameter.

audience: [] and an absent audience are different requests — the first simulates a visitor nothing is known about (restricted content is withheld, as in public), the second does not narrow by audience at all.

Vue / Nuxt

// main.ts (Vue)
import { createCmsClient } from '@conapps/cms-sdk';
import { cmsPlugin } from '@conapps/cms-sdk/vue';

app.use(cmsPlugin, createCmsClient({ endpoint, workspaceId, token }));

<script setup lang="ts">
import { useEntries } from '@conapps/cms-sdk/vue';

const { data, pending, error } = useEntries({ contentType: 'blogPost', take: 5 });
</script>

Nuxt: the client stays on the server

// server/utils/cms.ts — one client, one token, all server routes
import { createCmsClient, type CmsClient } from '@conapps/cms-sdk';

let cms: CmsClient | undefined;

export function getCms(): CmsClient {
  cms ??= createCmsClient({
    endpoint:    process.env.CMS_ENDPOINT!,       // https://cms.conapps.net
    workspaceId: process.env.CMS_WORKSPACE_ID!,
    auth: {
      issuer:       process.env.KEYCLOAK_ISSUER!, // https://auth.conapps.net/realms/platform
      clientId:     process.env.CMS_CLIENT_ID!,
      clientSecret: process.env.CMS_CLIENT_SECRET!,
    },
    environment: process.env.CMS_ENVIRONMENT ?? 'master',
    cacheTtlMs: 15_000,
    fetch: $fetch as unknown as typeof fetch,
  });
  return cms;
}

// server/api/posts.get.ts — the browser never sees the secret
export default defineEventHandler(async () => {
  const { items } = await getCms().getEntries({ contentType: 'blogPost' });
  return items;
});

Put CMS_CLIENT_SECRET in the server runtime config only. Anything under runtimeConfig.public is shipped to the browser.

A complete working example lives under ../examples/nuxt-demo.

Troubleshooting

Build & test

npm install
npm run build              # tsup → dist/{index,vue}.{js,cjs,d.ts}
npm test                   # vitest — 92 unit tests
npx vitest run --coverage  # ≥ 98% line coverage on src/

The suite covers the HTTP client (URL composition, locale defaulting, paging, encoding, all error mappings, in-memory cache TTL + invalidation, asset URL decoration, single-level + array + recursive link resolution, broken-link tolerance), the token provider (caching, skew, single-flight, invalidation, every OAuth rejection, blank-credential guards), the 401 refresh-and-retry path, and every Vue composable.