@nuasite/cms-client 0.43.0-beta.4

package/README.md

@@ -0,0 +1,34 @@
+# @nuasite/cms-client
+
+Headless TypeScript SDK for the Nua CMS. Zero React/DOM-framework coupling — just
+a typed `fetch` client over the cms-sidecar `/cms/v1` HTTP contract plus the pure
+entry-draft form model.
+
+Build any collections UI on top of it:
+
+```ts
+import {
+	createClient,
+	draftFromEntry,
+	setDraftField,
+} from '@nuasite/cms-client'
+
+const client = createClient('/app/project/acme/session/123/cms') // host adds /cms/v1
+const collections = await client.getCollections()
+const entry = await client.getEntry('posts', 'hello-world')
+```
+
+## What's here
+
+- **`createClient(apiBase)`** → `CmsClient`: `getProject`/`getCollections`/`getEntries`/`getEntry`
+  plus mutations (`updateEntry` with `409` conflict result, `createEntry`, `deleteEntry`,
+  `renameEntry`, array item ops) and media (`listMedia`/`uploadMedia`/`deleteMedia`,
+  degrades to `501` when the sidecar has no adapter — see `isMediaUnavailable`).
+- **`CmsClientError`** — carries the sidecar error `code` (`unauthorized`/`forbidden`/`not_found`/…).
+- **Form model** — `draftFromEntry`, `draftForCreate`, `draftFromServerFrontmatter`,
+  `setDraftField`, `coerceInput`, `parseWireValue`, and `valueTo*` readers. Pure,
+  unit-testable wire ↔ native mapping for the entry editor.
+
+The structural contract (collections/fields/entries/media) is re-used 1:1 from
+[`@nuasite/cms-types`](../cms-types). The default React UI built on this SDK is
+[`@nuasite/collections-admin`](../collections-admin).

package/dist/types/client.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Typed client over the cms-sidecar `/cms/v1` HTTP contract (reads + mutations).
+ *
+ * The host (webmaster BFF, or a local dev proxy in F7) mounts the sidecar under
+ * an `apiBase` and adds the `/cms/v1` prefix itself — so this client requests
+ * `${apiBase}/project`, `${apiBase}/collections`, etc. (never `/cms/v1/...`).
+ *
+ * The structural model (collections/entries/fields) is reused 1:1 from
+ * `@nuasite/cms-types`. The thin HTTP envelope (project model, sparse entries
+ * list, error codes, mutation bodies, conflict response) mirrors the sidecar's
+ * wire types; it is declared here because those types are not part of the
+ * `@nuasite/cms-types` contract surface.
+ */
+import type { CollectionDefinition, CollectionEntry, CollectionEntryInfo, MediaListResult, MediaUploadResult, MutationResult } from '@nuasite/cms-types';
+/** Stable error codes the sidecar exposes, each mapped to an HTTP status. */
+export type CmsErrorCode = 'not_found' | 'conflict' | 'validation' | 'parse_error' | 'io_error' | 'unsupported' | 'unauthorized';
+/** JSON body returned for every non-2xx response that is not a conflict. */
+export interface CmsApiError {
+    error: string;
+    code: CmsErrorCode;
+    sourcePath?: string;
+}
+/** A static page route discovered under `src/pages` (pathname-only). */
+export interface CmsPageEntry {
+    pathname: string;
+    title?: string;
+}
+/** Features the sidecar advertises so the UI can degrade gracefully. */
+export interface CmsCapabilities {
+    coreVersion: string;
+    features: string[];
+}
+/** `GET /project` — the whole structural model in one call. */
+export interface CmsProjectModel {
+    collections: CollectionDefinition[];
+    pages: CmsPageEntry[];
+    capabilities: CmsCapabilities;
+}
+/** `GET …/entries` — projected entries plus an opaque continuation cursor. */
+export interface CmsEntriesListResult {
+    entries: CollectionEntryInfo[];
+    cursor?: string;
+    hasMore: boolean;
+}
+/**
+ * `409` body for a `PATCH` whose `baseHash` no longer matches disk (an agent or a
+ * human wrote in between). Carries the current server version so the UI can offer
+ * "use server" vs "use ours". Mirrors the sidecar `ConflictResponse`.
+ */
+export interface CmsConflict {
+    code: 'conflict';
+    serverHash: string;
+    /** Raw (non-stringified) server frontmatter — unlike the line-keyed GET-detail shape. */
+    serverFrontmatter: Record<string, unknown>;
+    serverBody?: string;
+}
+/** `PATCH …/entries/:slug` — frontmatter keys are merged (not replaced). */
+export interface UpdateEntryInput {
+    frontmatter?: Record<string, unknown>;
+    body?: string;
+    /** Hash of the source the client edited; drives optimistic concurrency. */
+    baseHash?: string;
+}
+export interface CreateEntryInput {
+    slug: string;
+    frontmatter: Record<string, unknown>;
+    body?: string;
+    /** File extension override for data collections (e.g. 'json', 'yaml'). */
+    fileExtension?: string;
+}
+/** Context passed to media operations so uploads can be filed against an entry/field. */
+export interface MediaContext {
+    collection?: string;
+    entry?: string;
+    field?: string;
+    /** Subfolder under the media root. */
+    folder?: string;
+}
+/**
+ * Either a successful `MutationResult` or a `409` conflict the caller must
+ * resolve. Returned (not thrown) by `updateEntry` so the editor can branch
+ * without exception flow.
+ */
+export type UpdateEntryResult = {
+    status: 'ok';
+    result: MutationResult;
+} | {
+    status: 'conflict';
+    conflict: CmsConflict;
+};
+/**
+ * Thrown for any non-2xx response. Carries the parsed sidecar error code so the
+ * UI can distinguish auth failures (`unauthorized`/`forbidden`) from a missing
+ * collection/entry (`not_found`) or a generic failure.
+ */
+export declare class CmsClientError extends Error {
+    readonly status: number;
+    readonly code: CmsErrorCode | 'forbidden' | 'unknown';
+    constructor(status: number, code: CmsErrorCode | 'forbidden' | 'unknown', message: string);
+    /** Session cookie missing/expired upstream — the user must re-authenticate. */
+    get isUnauthorized(): boolean;
+    /** Authenticated but lacks access to this project. */
+    get isForbidden(): boolean;
+    get isNotFound(): boolean;
+}
+export interface GetEntriesOptions {
+    /** "slug,title" | "*" ; absent = light header (slug/title/draft/pathname). */
+    fields?: string;
+    /** Draft filter — defaults to `'false'` (published only) on the sidecar. */
+    draft?: 'true' | 'false' | 'all';
+    /** Opaque continuation cursor from a previous page's `cursor`. */
+    cursor?: string;
+    limit?: number;
+}
+export interface CmsClient {
+    getProject(): Promise<CmsProjectModel>;
+    getCollections(): Promise<CollectionDefinition[]>;
+    getEntries(collection: string, options?: GetEntriesOptions): Promise<CmsEntriesListResult>;
+    getEntry(collection: string, slug: string): Promise<CollectionEntry>;
+    /**
+     * Merge-patch an entry's frontmatter/body. Returns a discriminated result: a
+     * `409` is surfaced as `{ status: 'conflict' }` (not thrown) so the editor can
+     * open the conflict dialog. The new `baseHash` is on `result.sourceHash`.
+     */
+    updateEntry(collection: string, slug: string, input: UpdateEntryInput): Promise<UpdateEntryResult>;
+    createEntry(collection: string, input: CreateEntryInput): Promise<MutationResult>;
+    deleteEntry(collection: string, slug: string): Promise<MutationResult>;
+    renameEntry(collection: string, slug: string, to: string): Promise<MutationResult>;
+    addArrayItem(collection: string, slug: string, field: string, value: unknown, index?: number): Promise<MutationResult>;
+    removeArrayItem(collection: string, slug: string, field: string, index: number): Promise<MutationResult>;
+    listMedia(options?: {
+        folder?: string;
+        cursor?: string;
+        limit?: number;
+    }): Promise<MediaListResult>;
+    uploadMedia(file: File, context?: MediaContext): Promise<MediaUploadResult>;
+    deleteMedia(id: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+}
+/**
+ * Whether a thrown `CmsClientError` means "media is not available" — the deployed
+ * sidecar may have no media adapter wired (`501 unsupported`). The picker uses
+ * this to degrade gracefully instead of surfacing a hard error.
+ */
+export declare function isMediaUnavailable(error: unknown): boolean;
+export declare function createClient(apiBase: string): CmsClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/types/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"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"}

package/dist/types/client.js

@@ -0,0 +1,253 @@
+/**
+ * Typed client over the cms-sidecar `/cms/v1` HTTP contract (reads + mutations).
+ *
+ * The host (webmaster BFF, or a local dev proxy in F7) mounts the sidecar under
+ * an `apiBase` and adds the `/cms/v1` prefix itself — so this client requests
+ * `${apiBase}/project`, `${apiBase}/collections`, etc. (never `/cms/v1/...`).
+ *
+ * The structural model (collections/entries/fields) is reused 1:1 from
+ * `@nuasite/cms-types`. The thin HTTP envelope (project model, sparse entries
+ * list, error codes, mutation bodies, conflict response) mirrors the sidecar's
+ * wire types; it is declared here because those types are not part of the
+ * `@nuasite/cms-types` contract surface.
+ */
+/** HTTP status the sidecar uses for an optimistic-concurrency conflict. */
+const STATUS_CONFLICT = 409;
+// ============================================================================
+// Client error
+// ============================================================================
+/**
+ * Thrown for any non-2xx response. Carries the parsed sidecar error code so the
+ * UI can distinguish auth failures (`unauthorized`/`forbidden`) from a missing
+ * collection/entry (`not_found`) or a generic failure.
+ */
+export class CmsClientError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = 'CmsClientError';
+    }
+    /** Session cookie missing/expired upstream — the user must re-authenticate. */
+    get isUnauthorized() {
+        return this.code === 'unauthorized' || this.status === 401;
+    }
+    /** Authenticated but lacks access to this project. */
+    get isForbidden() {
+        return this.code === 'forbidden' || this.status === 403;
+    }
+    get isNotFound() {
+        return this.code === 'not_found' || this.status === 404;
+    }
+}
+// ============================================================================
+// Client
+// ============================================================================
+function isApiError(value) {
+    return isRecord(value)
+        && typeof value.error === 'string'
+        && typeof value.code === 'string';
+}
+/** Narrow `unknown` to a record so property reads typecheck without casts. */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function isConflict(value) {
+    if (!isRecord(value))
+        return false;
+    return value.code === 'conflict'
+        && typeof value.serverHash === 'string'
+        && isRecord(value.serverFrontmatter);
+}
+const KNOWN_ERROR_CODES = [
+    'not_found',
+    'conflict',
+    'validation',
+    'parse_error',
+    'io_error',
+    'unsupported',
+    'unauthorized',
+];
+function isErrorCode(value) {
+    return KNOWN_ERROR_CODES.includes(value);
+}
+/**
+ * Whether a thrown `CmsClientError` means "media is not available" — the deployed
+ * sidecar may have no media adapter wired (`501 unsupported`). The picker uses
+ * this to degrade gracefully instead of surfacing a hard error.
+ */
+export function isMediaUnavailable(error) {
+    return error instanceof CmsClientError && (error.status === 501 || error.code === 'unsupported');
+}
+export function createClient(apiBase) {
+    // Normalise: drop a trailing slash so `${base}${path}` joins cleanly.
+    const base = apiBase.endsWith('/') ? apiBase.slice(0, -1) : apiBase;
+    async function request(path) {
+        const response = await fetch(`${base}${path}`, {
+            method: 'GET',
+            credentials: 'include',
+            headers: { accept: 'application/json' },
+        });
+        if (!response.ok) {
+            throw await toError(response);
+        }
+        // Successful responses are always JSON in the read-only surface.
+        const value = await response.json();
+        return value;
+    }
+    async function toError(response) {
+        // 403 is produced by the BFF (project scope), not the sidecar, so it has no
+        // sidecar `code`; `errorFromBody` surfaces it as a distinct `forbidden`.
+        const body = await response.json().catch(() => null);
+        return errorFromBody(response.status, body);
+    }
+    function errorMessageFromBody(body, fallback) {
+        if (isApiError(body))
+            return body.error;
+        if (isRecord(body)) {
+            const err = body.error;
+            if (isRecord(err) && typeof err.message === 'string')
+                return err.message;
+        }
+        return fallback;
+    }
+    /** Build a `CmsClientError` from an already-parsed body (no re-read of the stream). */
+    function errorFromBody(status, body) {
+        if (status === 403) {
+            return new CmsClientError(403, 'forbidden', errorMessageFromBody(body, 'You do not have access to this project.'));
+        }
+        if (isApiError(body) && isErrorCode(body.code)) {
+            return new CmsClientError(status, body.code, body.error);
+        }
+        if (status === 401) {
+            return new CmsClientError(401, 'unauthorized', 'Your session has expired. Please reload.');
+        }
+        return new CmsClientError(status, 'unknown', errorMessageFromBody(body, `Request failed (${status})`));
+    }
+    function mutationInit(method, body) {
+        const init = {
+            method,
+            credentials: 'include',
+            headers: { accept: 'application/json' },
+        };
+        if (body !== undefined) {
+            init.body = JSON.stringify(body);
+            init.headers = { accept: 'application/json', 'content-type': 'application/json' };
+        }
+        return init;
+    }
+    /**
+     * Send a JSON-body mutation (POST/PATCH/DELETE). Throws `CmsClientError` on any
+     * non-2xx — used by the mutations that have no conflict branch. The
+     * conflict-aware update has its own path below.
+     */
+    async function mutate(path, method, body) {
+        const response = await fetch(`${base}${path}`, mutationInit(method, body));
+        if (!response.ok)
+            throw await toError(response);
+        // Mutation responses are documented JSON; the asserted shape is trusted
+        // (`response.json()` widens to the declared `T`, mirroring `request`).
+        const value = await response.json();
+        return value;
+    }
+    function entryPath(collection, slug) {
+        return `/collections/${encodeURIComponent(collection)}/entries/${encodeURIComponent(slug)}`;
+    }
+    return {
+        getProject() {
+            return request('/project');
+        },
+        getCollections() {
+            return request('/collections');
+        },
+        getEntries(collection, options = {}) {
+            const params = new URLSearchParams();
+            if (options.fields !== undefined)
+                params.set('fields', options.fields);
+            if (options.draft !== undefined)
+                params.set('draft', options.draft);
+            if (options.cursor !== undefined)
+                params.set('cursor', options.cursor);
+            if (options.limit !== undefined)
+                params.set('limit', String(options.limit));
+            const query = params.toString();
+            const suffix = query === '' ? '' : `?${query}`;
+            return request(`/collections/${encodeURIComponent(collection)}/entries${suffix}`);
+        },
+        getEntry(collection, slug) {
+            return request(entryPath(collection, slug));
+        },
+        async updateEntry(collection, slug, input) {
+            const response = await fetch(`${base}${entryPath(collection, slug)}`, mutationInit('PATCH', input));
+            // A `409` carries the server version; parse and return it for the dialog.
+            if (response.status === STATUS_CONFLICT) {
+                const body = await response.json().catch(() => null);
+                if (isConflict(body))
+                    return { status: 'conflict', conflict: body };
+                throw errorFromBody(response.status, body);
+            }
+            if (!response.ok)
+                throw await toError(response);
+            const result = await response.json();
+            return { status: 'ok', result };
+        },
+        createEntry(collection, input) {
+            return mutate(`/collections/${encodeURIComponent(collection)}/entries`, 'POST', input);
+        },
+        deleteEntry(collection, slug) {
+            return mutate(entryPath(collection, slug), 'DELETE');
+        },
+        renameEntry(collection, slug, to) {
+            return mutate(`${entryPath(collection, slug)}/rename`, 'POST', { to });
+        },
+        addArrayItem(collection, slug, field, value, index) {
+            const body = index === undefined ? { field, value } : { field, value, index };
+            return mutate(`${entryPath(collection, slug)}/array`, 'POST', body);
+        },
+        removeArrayItem(collection, slug, field, index) {
+            return mutate(`${entryPath(collection, slug)}/array`, 'DELETE', { field, index });
+        },
+        listMedia(options = {}) {
+            const params = new URLSearchParams();
+            if (options.folder !== undefined)
+                params.set('folder', options.folder);
+            if (options.cursor !== undefined)
+                params.set('cursor', options.cursor);
+            if (options.limit !== undefined)
+                params.set('limit', String(options.limit));
+            const query = params.toString();
+            return request(`/media${query === '' ? '' : `?${query}`}`);
+        },
+        async uploadMedia(file, context = {}) {
+            // The sidecar reads upload context (collection/entry/field/folder) from the
+            // query string; the file rides in multipart form data under `file`.
+            const params = new URLSearchParams();
+            if (context.collection !== undefined)
+                params.set('collection', context.collection);
+            if (context.entry !== undefined)
+                params.set('entry', context.entry);
+            if (context.field !== undefined)
+                params.set('field', context.field);
+            if (context.folder !== undefined)
+                params.set('folder', context.folder);
+            const query = params.toString();
+            const form = new FormData();
+            form.append('file', file);
+            const response = await fetch(`${base}/media${query === '' ? '' : `?${query}`}`, {
+                method: 'POST',
+                credentials: 'include',
+                headers: { accept: 'application/json' },
+                body: form,
+            });
+            if (!response.ok)
+                throw await toError(response);
+            const result = await response.json();
+            return result;
+        },
+        deleteMedia(id) {
+            return mutate(`/media/${encodeURIComponent(id)}`, 'DELETE');
+        },
+    };
+}

package/dist/types/form-model.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Pure draft model + field coercion for the entry editor (cms-headless F3.2).
+ *
+ * The sidecar speaks two slightly different frontmatter shapes:
+ *  - `GET …/entries/:slug` returns `frontmatter: Record<string, { value: string; line: number }>`,
+ *    where `value` is already stringified (objects/arrays are JSON).
+ *  - `PATCH …` accepts `frontmatter?: Record<string, unknown>` of *native* values (merged), and a
+ *    `409` `serverFrontmatter` is likewise native (not stringified).
+ *
+ * The editor works on a single native draft (`EntryDraft`): `frontmatter` is a
+ * `Record<string, unknown>` of native JS values keyed by field name, plus the
+ * markdown `body`. This module converts to/from the wire and coerces raw input
+ * (form strings) into the native value a `FieldType` expects. Keeping it pure
+ * (no React/DOM) makes the mapping unit-testable.
+ */
+import type { CollectionEntry, FieldDefinition, FieldType } from '@nuasite/cms-types';
+/** The editor's in-memory state: native frontmatter values + the markdown body. */
+export interface EntryDraft {
+    frontmatter: Record<string, unknown>;
+    body: string;
+}
+/**
+ * Parse one stringified frontmatter `value` (from `GET …/entries/:slug`) into the
+ * native value a field of `type` expects. Structural types (object/array) and
+ * unknowns fall back to a best-effort `JSON.parse`; scalars are coerced per type.
+ */
+export declare function parseWireValue(type: FieldType, raw: string): unknown;
+/**
+ * Build a native draft from a loaded entry, driven by the collection's fields.
+ * Frontmatter keys present on the entry but absent from the inferred schema are
+ * preserved verbatim (as raw strings) so a save never silently drops them.
+ */
+export declare function draftFromEntry(entry: CollectionEntry, fields: FieldDefinition[]): EntryDraft;
+/**
+ * Build a fresh draft for a create form from the collection's fields, seeding
+ * each field with its `defaultValue` (when present) or a type-appropriate blank.
+ */
+export declare function draftForCreate(fields: FieldDefinition[]): EntryDraft;
+/** A type-appropriate empty value used to seed create forms. */
+export declare function blankValue(type: FieldType): unknown;
+/**
+ * Adopt a server-provided native frontmatter map (from a `409` `serverFrontmatter`)
+ * into a draft, re-coercing per field where a definition exists.
+ */
+export declare function draftFromServerFrontmatter(serverFrontmatter: Record<string, unknown>, serverBody: string | undefined, fields: FieldDefinition[]): EntryDraft;
+/**
+ * Coerce a raw form-control string into the native value a field expects. Used by
+ * the widgets, whose `<input>` values are always strings.
+ */
+export declare function coerceInput(type: FieldType, raw: string): unknown;
+/** Render a native value back to a string for a text/number/date/select control. */
+export declare function valueToInput(value: unknown): string;
+/** Read a value as a boolean for toggle widgets, tolerating string encodings. */
+export declare function valueToBoolean(value: unknown): boolean;
+/** Read a value as an array of items for repeater widgets. */
+export declare function valueToArray(value: unknown): unknown[];
+/** Read a value as an object for nested-group widgets. */
+export declare function valueToObject(value: unknown): Record<string, unknown>;
+/** Immutably set a top-level frontmatter key in a draft. */
+export declare function setDraftField(draft: EntryDraft, name: string, value: unknown): EntryDraft;
+//# sourceMappingURL=form-model.d.ts.map

package/dist/types/form-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-model.d.ts","sourceRoot":"","sources":["../../src/form-model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAErF,mFAAmF;AACnF,MAAM,WAAW,UAAU;IAC1B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACpC,IAAI,EAAE,MAAM,CAAA;CACZ;AAMD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAgBpE;AAcD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,eAAe,EAAE,GAAG,UAAU,CAQ5F;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,UAAU,CAWpE;AAED,gEAAgE;AAChE,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAWnD;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CACzC,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1C,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,MAAM,EAAE,eAAe,EAAE,GACvB,UAAU,CAUZ;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAkBjE;AAED,oFAAoF;AACpF,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAKnD;AAED,iFAAiF;AACjF,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAItD;AAED,8DAA8D;AAC9D,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,EAAE,CAEtD;AAED,0DAA0D;AAC1D,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAErE;AAED,4DAA4D;AAC5D,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,UAAU,CAEzF"}