@stackonward/onex-cms-client

OneX HTTP adapter for the provider-neutral @stackonward/cms-client API. It owns OneX product context, preview headers, and error-envelope normalization so those protocol details do not leak into the generic client.

Install

pnpm add @stackonward/onex-cms-client

Quick start

import { createOneXCmsClient } from "@stackonward/onex-cms-client";

const cms = createOneXCmsClient({
  baseUrl: "https://platform.example.com/api/v1/cms",
  productCode: "product_alpha",
  defaultLocale: "en",
});

const article = await cms.getArticle("getting-started");

The adapter adds X-Product-Code to every request. Supplying previewToken also adds X-Preview-Token; products should keep preview tokens on trusted server boundaries.

Configuration

createOneXCmsClient accepts the generic CMS client options plus:

| Option | Required | Purpose | | -------------- | -------- | ---------------------------------------------------- | | productCode | yes | OneX product scope matching ^[a-z][a-z0-9_]{1,49}$ | | previewToken | no | Trusted preview credential sent as X-Preview-Token | | headers | no | Additional caller-owned request headers |

baseUrl, defaultLocale, timeout, and custom fetch retain the semantics defined by @stackonward/cms-client. Caller headers cannot override the OneX product or preview values supplied through the typed configuration.

For Nuxt server configuration that only needs product context headers:

import { createOneXCmsUpstreamHeaders } from "@stackonward/onex-cms-client";

const headers = createOneXCmsUpstreamHeaders("product_alpha");

Errors

oneXCmsErrorNormalizer maps the canonical OneX { error: { type, code, message } } envelope into CmsApiError. HTTP responses without that shape receive UNKNOWN_ERROR; transport failures receive NETWORK_ERROR. Status codes and original response bodies remain available for diagnostics.

Ownership and security

• Product selection is explicit through productCode; there is no global product registry.
• Preview credentials belong on a server or another trusted caller, not in public browser configuration.
• Authentication, retries, and content models remain owned by the generic CMS and API clients.

Compatibility

• Runtimes with the Fetch, Headers, URL, and AbortController web APIs
• ESM with TypeScript declarations

Related packages

• @stackonward/cms-client owns the CMS resource contract.
• @stackonward/cms-nuxt provides Nuxt routes, composables, and article media integration.

License

MIT