Dynamic Configuration

Configurations are grouped by namespaces (e.g., theme, home_page). You fetch a namespace and receive its values; larger payloads live in content blobs referenced by id.

Typed structures

/** Operator-supplied values ride in a typed envelope; no untyped holes. */
type ConfigValue = string | number | boolean | null | JsonObject | JsonArray;
type ConfigNamespace = Record<string, ConfigValue>;

interface ContentBlob {
  id: string;
  type: 'TEXT' | 'JSON' | 'HTML' | 'CSS' | 'FILE_METADATA'; // closed union
  data: ConfigValue;              // the payload; typed passthrough, never untyped
  metadata?: {
    fileSize?: number;            // bytes
    fileType?: string;
    fileUrl?: string;             // present on FILE_METADATA blobs
  };
}

JsonObject/JsonArray are JSON-serializable structures of the same primitive leaves; the envelope is closed: every value you receive is one of these types.

Discovering namespaces

getAllNamespaces() returns the complete catalog; a fixed, small list, so it is unpaginated by documented exception with a deterministic sort: alphabetical, identical across reads.

const namespaces = await sdk.content.getAllNamespaces();
// e.g. ['home_page', 'theme']

Fetching a namespace

const homeConfig = await sdk.content.getConfig('home_page');
// e.g. { showLiveCasino: true, welcomeText: 'Welcome!', heroSliderId: 'cnt_hero_123', layoutConfig: { columns: 3, rows: 2 } }

if (homeConfig.showLiveCasino) {
  renderLiveCasinoSection();
}

Unknown namespace → CONTENT_NAMESPACE_NOT_FOUND.

Fetching content blobs

Namespace configs reference blobs by id; fetch the blob only when needed:

const homeConfig = await sdk.content.getConfig('home_page');
const slider = await sdk.content.getContent(homeConfig.heroSliderId as string);
slider.data.forEach(banner => console.log(banner.imageUrl, banner.link));

Unknown blob → CONTENT_NOT_FOUND.

Update notifications

When the operator publishes a change to a namespace or blob, connected clients learn immediately on the real-time channel:

interface ContentUpdatedPayload {
  eventId: string;
  namespace: string;   // which namespace changed
  updatedAt: string;   // ISO-8601; the published version's timestamp
}

GIVEN a namespace or one of its referenced blobs is published by the operator
WHEN the publish lands
THEN a CONTENT_UPDATED event (carrying the namespace and updated timestamp) fires
     on the real-time channel, and clients refresh by calling clearCache() and
     re-fetching the affected namespace.

A 5-minute cache TTL backstops clients that were not connected when the event fired; stale content self-corrects within that window. See Theming, Caching & DOM Injection.

Error contract

Code	Error class	HTTP status	Trigger condition	Retryable
CONTENT_NAMESPACE_NOT_FOUND	NamespaceNotFoundError	404	Unknown namespace in getConfig	No
CONTENT_NOT_FOUND	ContentNotFoundError	404	Unknown blob id in getContent	No

Common errors are defined once in the Error Reference.