@forumulate/sdk 0.4.0 → 0.5.0

package/dist/content.d.ts

@@ -0,0 +1,318 @@
+/**
+ * Content libraries (headless CMS): the management routes under
+ * `/orgs/{orgId}/content/libraries/{libraryId}/…`.
+ *
+ * Hand-written because the generated `schema.ts` is refreshed from the
+ * DEPLOYED spec, and these routes are newer than the last refresh; `typed()`
+ * covers them once it catches up. Everything is addressed by `libraryId`,
+ * never by the hidden space behind a library: that id is not part of the
+ * contract (spec 14).
+ */
+type Request = <T>(method: string, path: string, opts?: {
+    body?: unknown;
+    query?: Record<string, string | number | boolean | undefined>;
+    headers?: Record<string, string>;
+}) => Promise<T>;
+export interface ContentLibrary {
+    id: string;
+    name: string;
+    slug: string;
+    siteId: string | null;
+    settings: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+}
+export type LibraryRole = 'viewer' | 'editor' | 'manager';
+export interface LibraryMember {
+    userId: string;
+    email: string;
+    name: string;
+    role: LibraryRole | null;
+    customRoleId: string | null;
+    effect: 'ALLOW' | 'DENY';
+}
+/** A declared model change a diff cannot infer (a rename), or a removal. */
+export type ModelOp = {
+    op: 'renameField';
+    type?: string;
+    blockType?: string;
+    from: string;
+    to: string;
+} | {
+    op: 'removeField';
+    type?: string;
+    blockType?: string;
+    path: string;
+} | {
+    op: 'restoreField';
+    type?: string;
+    blockType?: string;
+    path: string;
+} | {
+    op: 'renameType';
+    from: string;
+    to: string;
+} | {
+    op: 'renameBlockType';
+    from: string;
+    to: string;
+};
+export interface ContentModel {
+    shape: Record<string, unknown>;
+    types: Record<string, unknown>;
+    version: number;
+}
+export interface ContentModelVersion {
+    version: number;
+    ops: ModelOp[];
+    createdBy: string | null;
+    createdAt: string;
+    migratedAt: string | null;
+}
+export type ModelFileFormat = 'json' | 'payload';
+export interface ModelFileIssue {
+    path: string;
+    kind: 'hook' | 'access' | 'component' | 'function' | 'lossy' | 'unsupported' | 'ignored' | 'rewritten';
+    message: string;
+}
+export interface ContentModelExport {
+    format: ModelFileFormat;
+    filename: string;
+    content: string;
+    version: number;
+    issues: ModelFileIssue[];
+}
+export interface ModelChangeLine {
+    op: 'add' | 'remove' | 'change';
+    target: 'type' | 'setting' | 'field' | 'blockType' | 'blockField';
+    type?: string;
+    blockType?: string;
+    path?: string;
+    property?: string;
+    before?: unknown;
+    after?: unknown;
+}
+export interface ContentModelImportResult {
+    changed: boolean;
+    applied: boolean;
+    diff: ModelChangeLine[];
+    storageOnly: boolean;
+    ops: ModelOp[];
+    issues: ModelFileIssue[];
+    version: number;
+}
+/** An entry as the management API answers a write: enough to address it again. */
+export interface ContentEntryRef {
+    id: string;
+    title: string;
+    slug?: string;
+    preset?: string | null;
+}
+export interface ContentAssetSummary {
+    id: string;
+    url: string;
+    filename: string;
+    contentType?: string;
+    [extra: string]: unknown;
+}
+export type DeliveryKeyKind = 'delivery' | 'publishable' | 'preview';
+export interface DeliveryKeySummary {
+    id: string;
+    name: string;
+    kind: DeliveryKeyKind;
+    prefix: string;
+    stage: 'published' | 'draft';
+    libraryId: string;
+    origins: string[] | null;
+    contentTypes: string[] | null;
+    locales: string[] | null;
+    lastUsedAt: string | null;
+    [extra: string]: unknown;
+}
+export interface IssuedDeliveryKey {
+    key: DeliveryKeySummary;
+    /** Shown once. */
+    secret: string;
+}
+export declare function contentApi(request: Request): {
+    libraries: {
+        list: (orgId: string) => Promise<{
+            libraries: ContentLibrary[];
+        }>;
+        get: (orgId: string, libraryId: string) => Promise<{
+            library: ContentLibrary;
+        }>;
+        create: (orgId: string, input: {
+            name: string;
+            slug?: string;
+            siteId?: string | null;
+            settings?: Record<string, unknown>;
+            template?: string;
+        }) => Promise<{
+            library: ContentLibrary;
+        }>;
+        update: (orgId: string, libraryId: string, input: {
+            name?: string;
+            slug?: string;
+            siteId?: string | null;
+            settings?: Record<string, unknown>;
+        }) => Promise<{
+            library: ContentLibrary;
+        }>;
+        remove: (orgId: string, libraryId: string) => Promise<{
+            ok: true;
+        }>;
+    };
+    members: {
+        list: (orgId: string, libraryId: string) => Promise<{
+            members: LibraryMember[];
+        }>;
+        put: (orgId: string, libraryId: string, input: {
+            userId: string;
+            role?: LibraryRole;
+            customRoleId?: string;
+            effect?: "ALLOW" | "DENY";
+        }) => Promise<{
+            member: LibraryMember;
+        }>;
+        remove: (orgId: string, libraryId: string, userId: string) => Promise<{
+            ok: true;
+        }>;
+    };
+    model: {
+        get: (orgId: string, libraryId: string) => Promise<{
+            model: ContentModel;
+        }>;
+        save: (orgId: string, libraryId: string, input: {
+            shape?: Record<string, unknown>;
+            types?: Record<string, unknown>;
+            ops?: ModelOp[];
+        }) => Promise<{
+            model: ContentModel;
+        }>;
+        versions: (orgId: string, libraryId: string) => Promise<{
+            versions: ContentModelVersion[];
+        }>;
+        /** The model as a file: `forumulate.content.json`, or a Payload config. */
+        export: (orgId: string, libraryId: string, format?: ModelFileFormat) => Promise<ContentModelExport>;
+        /** Push a model file: a diff always, a new version unless `dryRun` (or nothing changed). */
+        import: (orgId: string, libraryId: string, input: {
+            format: ModelFileFormat;
+            content: string;
+            dryRun?: boolean;
+            baseVersion?: number;
+            force?: boolean;
+            ops?: ModelOp[];
+        }) => Promise<ContentModelImportResult>;
+        /** The library's delivery JSON Schema (what `forumulate content types` generates from). */
+        schema: (orgId: string, libraryId: string, opts?: {
+            audience?: "public" | "preview";
+        }) => Promise<Record<string, unknown>>;
+    };
+    /**
+     * Entries by their management id. `create` takes an `Idempotency-Key` (the
+     * route requires one), so a retried import returns the entry the first call
+     * made. Later writes may carry the entry's `contentHash` as `If-Match`; an import is the only writer, so it sends none.
+     */
+    entries: {
+        create: (orgId: string, libraryId: string, input: {
+            title: string;
+            slug?: string;
+            preset: string;
+            params?: Record<string, unknown>;
+        }, idempotencyKey: string) => Promise<{
+            item: ContentEntryRef;
+            warnings?: string[];
+        }>;
+        /** Which of these `Idempotency-Key`s already made an entry, as key → entry id (an import's dry-run and its update path). */
+        lookup: (orgId: string, libraryId: string, keys: string[]) => Promise<{
+            found: Record<string, string>;
+        }>;
+        /** Rename, re-address or patch the fields (`params`) of an entry. */
+        update: (orgId: string, libraryId: string, entryId: string, input: {
+            title?: string;
+            slug?: string;
+            params?: Record<string, unknown>;
+        }) => Promise<{
+            item: ContentEntryRef;
+            warnings?: string[];
+        }>;
+        /** Write an entry's localized fields into the DRAFT of one locale's twin, making the twin first when needed. */
+        writeLocale: (orgId: string, libraryId: string, entryId: string, locale: string, fields: Record<string, unknown>) => Promise<{
+            locale: string;
+            sourceEntryId: string;
+            entryId: string;
+            created: boolean;
+        }>;
+        read: (orgId: string, libraryId: string, entryId: string) => Promise<{
+            item: ContentEntryRef & {
+                contentHash: string;
+            };
+        }>;
+        setFields: (orgId: string, libraryId: string, entryId: string, fields: Record<string, unknown>, ifMatch?: string) => Promise<{
+            fields: Record<string, unknown>;
+            warnings?: string[];
+        }>;
+        publish: (orgId: string, libraryId: string, entryId: string, ifMatch?: string) => Promise<{
+            published: boolean;
+            note?: string;
+        }>;
+    };
+    locales: {
+        list: (orgId: string, libraryId: string) => Promise<{
+            sourceLocale: string;
+            locales: {
+                code: string;
+                label: string;
+            }[];
+        }>;
+        add: (orgId: string, libraryId: string, input: {
+            code: string;
+            label: string;
+        }) => Promise<{
+            sourceLocale: string;
+            locales: {
+                code: string;
+                label: string;
+            }[];
+        }>;
+    };
+    assets: {
+        list: (orgId: string, libraryId: string, query?: {
+            search?: string;
+            limit?: number;
+        }) => Promise<{
+            assets: ContentAssetSummary[];
+        }>;
+    };
+    keys: {
+        list: (orgId: string, libraryId: string) => Promise<{
+            keys: DeliveryKeySummary[];
+        }>;
+        create: (orgId: string, libraryId: string, input: {
+            name: string;
+            kind: DeliveryKeyKind;
+            origins?: string[];
+            contentTypes?: string[];
+            locales?: string[];
+            expiresInDays?: number;
+        }) => Promise<IssuedDeliveryKey>;
+        update: (orgId: string, libraryId: string, keyId: string, input: {
+            name?: string;
+            origins?: string[] | null;
+            contentTypes?: string[] | null;
+            locales?: string[] | null;
+        }) => Promise<{
+            key: DeliveryKeySummary;
+        }>;
+        rotate: (orgId: string, libraryId: string, keyId: string, input?: {
+            graceMinutes?: number;
+        }) => Promise<IssuedDeliveryKey>;
+        revoke: (orgId: string, libraryId: string, keyId: string) => Promise<{
+            ok: true;
+        }>;
+    };
+};
+export type ContentApi = ReturnType<typeof contentApi>;
+export {};
+//# sourceMappingURL=content.d.ts.map

package/dist/content.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * Content libraries (headless CMS): the management routes under
+ * `/orgs/{orgId}/content/libraries/{libraryId}/…`.
+ *
+ * Hand-written because the generated `schema.ts` is refreshed from the
+ * DEPLOYED spec, and these routes are newer than the last refresh; `typed()`
+ * covers them once it catches up. Everything is addressed by `libraryId`,
+ * never by the hidden space behind a library: that id is not part of the
+ * contract (spec 14).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.contentApi = contentApi;
+function contentApi(request) {
+    const lib = (orgId, libraryId) => `/orgs/${orgId}/content/libraries/${libraryId}`;
+    return {
+        libraries: {
+            list: (orgId) => request('GET', `/orgs/${orgId}/content/libraries`),
+            get: (orgId, libraryId) => request('GET', lib(orgId, libraryId)),
+            create: (orgId, input) => request('POST', `/orgs/${orgId}/content/libraries`, { body: input }),
+            update: (orgId, libraryId, input) => request('PATCH', lib(orgId, libraryId), { body: input }),
+            remove: (orgId, libraryId) => request('DELETE', lib(orgId, libraryId)),
+        },
+        members: {
+            list: (orgId, libraryId) => request('GET', `${lib(orgId, libraryId)}/members`),
+            put: (orgId, libraryId, input) => request('POST', `${lib(orgId, libraryId)}/members`, { body: input }),
+            remove: (orgId, libraryId, userId) => request('DELETE', `${lib(orgId, libraryId)}/members/${userId}`),
+        },
+        model: {
+            get: (orgId, libraryId) => request('GET', `${lib(orgId, libraryId)}/model`),
+            save: (orgId, libraryId, input) => request('PUT', `${lib(orgId, libraryId)}/model`, { body: input }),
+            versions: (orgId, libraryId) => request('GET', `${lib(orgId, libraryId)}/model/versions`),
+            /** The model as a file: `forumulate.content.json`, or a Payload config. */
+            export: (orgId, libraryId, format = 'json') => request('GET', `${lib(orgId, libraryId)}/model/export`, { query: { format } }),
+            /** Push a model file: a diff always, a new version unless `dryRun` (or nothing changed). */
+            import: (orgId, libraryId, input) => request('POST', `${lib(orgId, libraryId)}/model/import`, { body: input }),
+            /** The library's delivery JSON Schema (what `forumulate content types` generates from). */
+            schema: (orgId, libraryId, opts = {}) => request('GET', `${lib(orgId, libraryId)}/model/schema.json`, { query: { audience: opts.audience } }),
+        },
+        /**
+         * Entries by their management id. `create` takes an `Idempotency-Key` (the
+         * route requires one), so a retried import returns the entry the first call
+         * made. Later writes may carry the entry's `contentHash` as `If-Match`; an import is the only writer, so it sends none.
+         */
+        entries: {
+            create: (orgId, libraryId, input, idempotencyKey) => request('POST', `${lib(orgId, libraryId)}/items`, {
+                body: input,
+                headers: { 'Idempotency-Key': idempotencyKey },
+            }),
+            /** Which of these `Idempotency-Key`s already made an entry, as key → entry id (an import's dry-run and its update path). */
+            lookup: (orgId, libraryId, keys) => request('POST', `${lib(orgId, libraryId)}/items/lookup`, { body: { keys } }),
+            /** Rename, re-address or patch the fields (`params`) of an entry. */
+            update: (orgId, libraryId, entryId, input) => request('PATCH', `${lib(orgId, libraryId)}/items/${entryId}`, { body: input }),
+            /** Write an entry's localized fields into the DRAFT of one locale's twin, making the twin first when needed. */
+            writeLocale: (orgId, libraryId, entryId, locale, fields) => request('PUT', `${lib(orgId, libraryId)}/entries/${entryId}/locales/${encodeURIComponent(locale)}`, { body: { fields } }),
+            read: (orgId, libraryId, entryId) => request('GET', `${lib(orgId, libraryId)}/items/${entryId}`),
+            setFields: (orgId, libraryId, entryId, fields, ifMatch) => request('PATCH', `${lib(orgId, libraryId)}/items/${entryId}/fields`, {
+                body: { fields },
+                headers: ifMatch ? { 'If-Match': `"${ifMatch}"` } : undefined,
+            }),
+            publish: (orgId, libraryId, entryId, ifMatch) => request('POST', `${lib(orgId, libraryId)}/items/${entryId}/publish`, {
+                headers: ifMatch ? { 'If-Match': `"${ifMatch}"` } : undefined,
+            }),
+        },
+        locales: {
+            list: (orgId, libraryId) => request('GET', `${lib(orgId, libraryId)}/locales`),
+            add: (orgId, libraryId, input) => request('POST', `${lib(orgId, libraryId)}/locales`, { body: input }),
+        },
+        assets: {
+            list: (orgId, libraryId, query = {}) => request('GET', `${lib(orgId, libraryId)}/assets`, { query }),
+        },
+        keys: {
+            list: (orgId, libraryId) => request('GET', `${lib(orgId, libraryId)}/keys`),
+            create: (orgId, libraryId, input) => request('POST', `${lib(orgId, libraryId)}/keys`, { body: input }),
+            update: (orgId, libraryId, keyId, input) => request('PATCH', `${lib(orgId, libraryId)}/keys/${keyId}`, { body: input }),
+            rotate: (orgId, libraryId, keyId, input = {}) => request('POST', `${lib(orgId, libraryId)}/keys/${keyId}/rotate`, { body: input }),
+            revoke: (orgId, libraryId, keyId) => request('DELETE', `${lib(orgId, libraryId)}/keys/${keyId}`),
+        },
+    };
+}
+//# sourceMappingURL=content.js.map

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from './types';
 export { verifyWebhookSignature, type VerifyWebhookInput } from './webhooks';
+export * from './content';
 export type { paths } from './schema';
 export type { HttpMethod, MethodsOf, OperationOf, TypedRequestInit, TypedResponse } from './typed';
 import type { paths } from './schema';
@@ -142,6 +143,174 @@ export declare class ForumulateClient {
             };
         }>;
     };
+    readonly content: {
+        libraries: {
+            list: (orgId: string) => Promise<{
+                libraries: import("./content").ContentLibrary[];
+            }>;
+            get: (orgId: string, libraryId: string) => Promise<{
+                library: import("./content").ContentLibrary;
+            }>;
+            create: (orgId: string, input: {
+                name: string;
+                slug?: string;
+                siteId?: string | null;
+                settings?: Record<string, unknown>;
+                template?: string;
+            }) => Promise<{
+                library: import("./content").ContentLibrary;
+            }>;
+            update: (orgId: string, libraryId: string, input: {
+                name?: string;
+                slug?: string;
+                siteId?: string | null;
+                settings?: Record<string, unknown>;
+            }) => Promise<{
+                library: import("./content").ContentLibrary;
+            }>;
+            remove: (orgId: string, libraryId: string) => Promise<{
+                ok: true;
+            }>;
+        };
+        members: {
+            list: (orgId: string, libraryId: string) => Promise<{
+                members: import("./content").LibraryMember[];
+            }>;
+            put: (orgId: string, libraryId: string, input: {
+                userId: string;
+                role?: import("./content").LibraryRole;
+                customRoleId?: string;
+                effect?: "ALLOW" | "DENY";
+            }) => Promise<{
+                member: import("./content").LibraryMember;
+            }>;
+            remove: (orgId: string, libraryId: string, userId: string) => Promise<{
+                ok: true;
+            }>;
+        };
+        model: {
+            get: (orgId: string, libraryId: string) => Promise<{
+                model: import("./content").ContentModel;
+            }>;
+            save: (orgId: string, libraryId: string, input: {
+                shape?: Record<string, unknown>;
+                types?: Record<string, unknown>;
+                ops?: import("./content").ModelOp[];
+            }) => Promise<{
+                model: import("./content").ContentModel;
+            }>;
+            versions: (orgId: string, libraryId: string) => Promise<{
+                versions: import("./content").ContentModelVersion[];
+            }>;
+            export: (orgId: string, libraryId: string, format?: import("./content").ModelFileFormat) => Promise<import("./content").ContentModelExport>;
+            import: (orgId: string, libraryId: string, input: {
+                format: import("./content").ModelFileFormat;
+                content: string;
+                dryRun?: boolean;
+                baseVersion?: number;
+                force?: boolean;
+                ops?: import("./content").ModelOp[];
+            }) => Promise<import("./content").ContentModelImportResult>;
+            schema: (orgId: string, libraryId: string, opts?: {
+                audience?: "public" | "preview";
+            }) => Promise<Record<string, unknown>>;
+        };
+        entries: {
+            create: (orgId: string, libraryId: string, input: {
+                title: string;
+                slug?: string;
+                preset: string;
+                params?: Record<string, unknown>;
+            }, idempotencyKey: string) => Promise<{
+                item: import("./content").ContentEntryRef;
+                warnings?: string[];
+            }>;
+            lookup: (orgId: string, libraryId: string, keys: string[]) => Promise<{
+                found: Record<string, string>;
+            }>;
+            update: (orgId: string, libraryId: string, entryId: string, input: {
+                title?: string;
+                slug?: string;
+                params?: Record<string, unknown>;
+            }) => Promise<{
+                item: import("./content").ContentEntryRef;
+                warnings?: string[];
+            }>;
+            writeLocale: (orgId: string, libraryId: string, entryId: string, locale: string, fields: Record<string, unknown>) => Promise<{
+                locale: string;
+                sourceEntryId: string;
+                entryId: string;
+                created: boolean;
+            }>;
+            read: (orgId: string, libraryId: string, entryId: string) => Promise<{
+                item: import("./content").ContentEntryRef & {
+                    contentHash: string;
+                };
+            }>;
+            setFields: (orgId: string, libraryId: string, entryId: string, fields: Record<string, unknown>, ifMatch?: string) => Promise<{
+                fields: Record<string, unknown>;
+                warnings?: string[];
+            }>;
+            publish: (orgId: string, libraryId: string, entryId: string, ifMatch?: string) => Promise<{
+                published: boolean;
+                note?: string;
+            }>;
+        };
+        locales: {
+            list: (orgId: string, libraryId: string) => Promise<{
+                sourceLocale: string;
+                locales: {
+                    code: string;
+                    label: string;
+                }[];
+            }>;
+            add: (orgId: string, libraryId: string, input: {
+                code: string;
+                label: string;
+            }) => Promise<{
+                sourceLocale: string;
+                locales: {
+                    code: string;
+                    label: string;
+                }[];
+            }>;
+        };
+        assets: {
+            list: (orgId: string, libraryId: string, query?: {
+                search?: string;
+                limit?: number;
+            }) => Promise<{
+                assets: import("./content").ContentAssetSummary[];
+            }>;
+        };
+        keys: {
+            list: (orgId: string, libraryId: string) => Promise<{
+                keys: import("./content").DeliveryKeySummary[];
+            }>;
+            create: (orgId: string, libraryId: string, input: {
+                name: string;
+                kind: import("./content").DeliveryKeyKind;
+                origins?: string[];
+                contentTypes?: string[];
+                locales?: string[];
+                expiresInDays?: number;
+            }) => Promise<import("./content").IssuedDeliveryKey>;
+            update: (orgId: string, libraryId: string, keyId: string, input: {
+                name?: string;
+                origins?: string[] | null;
+                contentTypes?: string[] | null;
+                locales?: string[] | null;
+            }) => Promise<{
+                key: import("./content").DeliveryKeySummary;
+            }>;
+            rotate: (orgId: string, libraryId: string, keyId: string, input?: {
+                graceMinutes?: number;
+            }) => Promise<import("./content").IssuedDeliveryKey>;
+            revoke: (orgId: string, libraryId: string, keyId: string) => Promise<{
+                ok: true;
+            }>;
+        };
+    };
     readonly orgs: {
         list: () => Promise<{
             orgs: Organization[];

package/dist/index.js

@@ -18,6 +18,8 @@ exports.ForumulateClient = exports.ForumulateError = exports.verifyWebhookSignat
 __exportStar(require("./types"), exports);
 var webhooks_1 = require("./webhooks");
 Object.defineProperty(exports, "verifyWebhookSignature", { enumerable: true, get: function () { return webhooks_1.verifyWebhookSignature; } });
+__exportStar(require("./content"), exports);
+const content_1 = require("./content");
 /** Thrown for any non-2xx API response. Mirrors the API's error envelope. */
 class ForumulateError extends Error {
     status;
@@ -194,6 +196,8 @@ class ForumulateClient {
             body: input,
         }),
     };
+    // ── Content libraries (headless CMS) — see ./content ───────────────────────
+    content = (0, content_1.contentApi)((method, path, opts) => this.request(method, path, opts));
     // ── Organizations ─────────────────────────────────────────────────────────
     orgs = {
         list: () => this.request('GET', '/orgs'),

package/dist/schema.d.ts

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: package/dist/schema.d.ts
-size: 35557853 bytes
-sha256: c980b7a7869774480b1b44e97a481782fc1fdbf58a91ddad38ba18cc43e39f87
+size: 41197295 bytes
+sha256: 4b7229f500f88ffae386167d2d8d14491e8afd8734cc89cde35ce316308ade7d

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forumulate/sdk",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Typed TypeScript client for the Forumulate REST API.",
   "license": "MIT",
   "homepage": "https://forumulate.com/reference",