@capacms/sdk 1.0.0-next.0

package/dist/client.js

@@ -0,0 +1,288 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.instanceIdOf = instanceIdOf;
+exports.createClient = createClient;
+/**
+ * client.ts — the read client, plus the one thing it can write.
+ *
+ * This file used to say the SDK was read-only "because the surface it talks to
+ * is". That was true when it was written and is not any more: the agent surface
+ * (#383) put `/v2/agent/*` behind `verifyApiKey`, ADMIN_UI_OVERHAUL 0h.4b added
+ * `/v2/agent/workspaces`, and `tenant_api_keys.permission` became a real
+ * control (#4646).
+ *
+ * So `workspaces` writes, and nothing else does. A workspace is NAVIGATION —
+ * which models, entries and media folders the admin's left rail keeps in reach,
+ * in which folders — so applying one touches no record and deletes nothing. The
+ * content writes an SDK could now technically reach need a surface designed for
+ * them, not a fourth method quietly added to this object.
+ */
+const config_1 = require("./config");
+const http_1 = require("./http");
+const webhooks_1 = require("./webhooks");
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * The Capa instance id for a row.
+ *
+ * `instanceId` FIRST, and it is the answer on any current server: #4628 added
+ * it to every public read row as the last key, precisely so that one key always
+ * means the instance id.
+ *
+ * `id` is the fallback, and it is a fallback because it is not trustworthy.
+ * `GET /v2/api/:ns` builds each row as `{...instance, ...formatInstanceData(instance)}`
+ * — the model's own fields are hoisted to the top level and spread SECOND, so a
+ * field named `id` overwrites the instance's id and the real UUID is then absent
+ * from the row, not merely moved. The same happens to `title` and `tags`. In one
+ * ordinary tenant 20 of 20 models have a field named `title` and 7 of 20 have
+ * one named `id` (every shopify_* model, plus judge_me_review), so this is the
+ * common case. The UUID test is therefore kept for servers older than the fix,
+ * where it is the only thing separating an instance id from a Shopify numeric
+ * id that happens to live in a field called `id`.
+ *
+ * `null` means the server sent no usable id at all: an old server AND a
+ * shadowing model. `getContentById` cannot be reached for such a row.
+ */
+function instanceIdOf(row) {
+    const r = row;
+    if (typeof r?.instanceId === "string" && UUID_RE.test(r.instanceId))
+        return r.instanceId;
+    const id = r?.id;
+    return typeof id === "string" && UUID_RE.test(id) ? id : null;
+}
+/** Capa wraps most values as `{type, value, sortOrder}` — including `title`. */
+const unwrap = (v) => v && typeof v === "object" && !Array.isArray(v) && "value" in v
+    ? v.value
+    : v ?? null;
+function contentQuery(options = {}) {
+    const q = {
+        limit: options.limit,
+        page: options.page,
+        depth: options.depth,
+        sort: options.sort,
+    };
+    for (const [k, v] of Object.entries(options.where ?? {}))
+        q[k] = v;
+    return q;
+}
+function createClient(config) {
+    const resolved = (0, config_1.resolveConfig)(config);
+    async function listContent(namespace, options = {}) {
+        const { body, cacheTags } = await (0, http_1.getJson)(resolved, `/v2/api/${encodeURIComponent(namespace)}`, contentQuery(options));
+        const rows = body.data ?? [];
+        return { data: rows, ids: rows.map(instanceIdOf), meta: body.meta ?? {}, cacheTags };
+    }
+    return {
+        listContent,
+        async getContentById(namespace, id, options = {}) {
+            // Fail here rather than spending a request on a guaranteed 400. See
+            // instanceIdOf: for a shadowing model, the "id" on a listContent row is
+            // the model's own field and the API rejects it as invalid.
+            if (!UUID_RE.test(String(id ?? ""))) {
+                throw new Error(`@capacms/sdk: "${id}" is not a Capa instance id (they are UUIDs). ` +
+                    `If it came from a listContent row, read \`row.instanceId\` or \`Page.ids\` instead ` +
+                    `of \`row.id\`: the model "${namespace}" has a field named "id" that overwrites the ` +
+                    `instance id in that response. See #4628.`);
+            }
+            const { body } = await (0, http_1.getJson)(resolved, `/v2/api/${encodeURIComponent(namespace)}`, { ids: id, depth: options.depth, limit: 1 });
+            return (body.data ?? [])[0] ?? null;
+        },
+        /**
+         * One row matched by field values — `findOne("shopify_page", {handle})`.
+         *
+         * Deliberately NOT called `getBySlug`. Capa has no slug convention: the
+         * field is `handle` on shopify_page, `product_handle` on judge_me_review
+         * and `bloghandle` on shopify_article, and nothing marks one as the slug.
+         * Naming this `getBySlug` would imply a convention that does not exist and
+         * bake each consumer's guess into the API. A slug marker on the model is
+         * the right fix, and belongs in Capa rather than here.
+         */
+        async findOne(namespace, where, options = {}) {
+            const page = await listContent(namespace, { ...options, where, limit: 1 });
+            return page.data[0] ?? null;
+        },
+        async search(q, options = {}) {
+            const text = String(q ?? "").trim();
+            // The server answers an absent `q` with 500 carrying `Cannot read
+            // properties of undefined (reading 'trim')` — the parameter is trimmed
+            // before it is checked. #4627 made it a 400 and the public-surface freeze
+            // put the 500 back on 2026-09-20, so this guard is what a caller actually
+            // gets: a named error, at no request cost, on every server.
+            if (!text)
+                throw new Error("@capacms/sdk: search(q) requires a non-empty query.");
+            const { body } = await (0, http_1.getJson)(resolved, "/v2/api/search", {
+                q: text,
+                modelNamespace: options.namespace,
+                size: options.limit ?? 20,
+                page: options.page,
+                // The default (non-extended) branch answers {id, title} and says
+                // nothing about which model a hit belongs to, so the namespace has to
+                // be bought with a hydration round trip. #4627 briefly added it to the
+                // default row; the public-surface freeze reverted that on 2026-09-20.
+                extended: true,
+                depth: 0,
+            });
+            return (body.data ?? []).map((row) => ({
+                // instanceIdOf, not row.id. `/v2/api/search?extended=true` hoists the
+                // model's own fields exactly as `/v2/api/:ns` does, so a model with a
+                // field named `id` shadows the id here too; #4628 now sends
+                // `instanceId` on these rows as well. `null` means an old server AND a
+                // shadowing model, the same as `Page.ids`.
+                id: instanceIdOf(row),
+                namespace: row.dataModel?.namespace ?? row.modelNamespace ?? null,
+                model: row.dataModel?.modelName ?? undefined,
+                title: unwrap(row.title),
+            }));
+        },
+        /**
+         * Saved workspaces, over `/v2/agent/workspaces` (ADMIN_UI_OVERHAUL 0h.4b).
+         *
+         * `list`, `get` and `getDocument` need a `read` key. `apply` and `create`
+         * need one with `write` permission and throw `CapaError` with status 403
+         * otherwise — the API's own body, not a message invented here.
+         */
+        workspaces: {
+            async list(options = {}) {
+                const { body } = await (0, http_1.getJson)(resolved, "/v2/agent/workspaces", options.includePrivate ? { all: "true" } : {});
+                return {
+                    workspaces: body.workspaces ?? [],
+                    currentId: body.currentId ?? null,
+                    defaultId: body.defaultId ?? null,
+                };
+            },
+            /**
+             * One summary row. Served from the LIST rather than a GET /:id, because
+             * there is no such route: 0h.4 gives a workspace `/tree` and `/document`,
+             * and the summary a caller wants alongside them is the switcher row.
+             * Doing this here beats every caller hand-rolling the same filter.
+             */
+            async get(id) {
+                const { body } = await (0, http_1.getJson)(resolved, "/v2/agent/workspaces", { all: "true" });
+                return (body.workspaces ?? []).find((w) => w.id === id) ?? null;
+            },
+            async getDocument(id) {
+                const { body } = await (0, http_1.getJson)(resolved, `/v2/agent/workspaces/${encodeURIComponent(id)}/document`);
+                return body;
+            },
+            async apply(id, document, options = {}) {
+                // "merge" by default: the mode that adds and never removes. A default
+                // of "replace" would make a caller's first, smallest experiment delete
+                // the arrangement a team had built.
+                return (0, http_1.writeJson)(resolved, "PUT", `/v2/agent/workspaces/${encodeURIComponent(id)}/tree`, { ...document, mode: options.mode ?? "merge" });
+            },
+            async create(input) {
+                if (!input?.name)
+                    throw new Error("@capacms/sdk: workspaces.create needs a name.");
+                // `team`, always. Private means "visible to its creator", and an API
+                // key has no person behind it, so a private workspace made this way
+                // would be visible to nobody at all — the API refuses it for the same
+                // reason. Asked for explicitly rather than left to a server default.
+                return (0, http_1.writeJson)(resolved, "POST", "/v2/agent/workspaces", {
+                    ...input,
+                    visibility: "team",
+                });
+            },
+        },
+        /**
+         * The entry-editor layout, over `/v2/agent/models` (ADMIN_UI_OVERHAUL 0m.4).
+         *
+         * `getLayout` needs a `read` key. `setLayout` WRITES the model and needs a
+         * key whose permission is `agent` — `write` and `delete` keys do not carry
+         * `model:update`, which is the same gate every other model write asks for,
+         * and it throws `CapaError` with status 403 otherwise.
+         *
+         * `id` is the model's id OR its namespace, the same two spellings
+         * `GET /v2/models/:id` accepts, so a layout can be written for a model an
+         * agent only knows by namespace.
+         */
+        models: {
+            async getLayoutInfo(id) {
+                const { body } = await (0, http_1.getJson)(resolved, `/v2/agent/models/${encodeURIComponent(id)}`);
+                return { layout: body.layout ?? null, embedByDefault: body.embedByDefault === true };
+            },
+            async getLayout(id) {
+                // The same read, narrowed. Kept because it is the call that reads as
+                // what it does when the pass-through flag is not what you are after.
+                return (await this.getLayoutInfo(id)).layout;
+            },
+            async setLayout(id, layout) {
+                // PUT with an explicit null rather than the DELETE route: one verb, one
+                // body, and `setLayout(id, null)` reads as the reset it is.
+                const res = await (0, http_1.writeJson)(resolved, "PUT", `/v2/agent/models/${encodeURIComponent(id)}/layout`, { layout });
+                return res?.layout ?? null;
+            },
+        },
+        /**
+         * Scheduled publishes, over `/v2/agent/scheduled-actions`.
+         *
+         * This is the one content-affecting write the SDK offers, and it is offered
+         * because it is the one with a receipt: every call leaves a row that says
+         * who asked, for when, in which zone, and what happened. `instances.publish`
+         * is deliberately still absent (see the README) — scheduling is a request
+         * the ledger can show you and cancel; publishing now is not.
+         *
+         * Reads need a `read` key. Every write here needs `instance:publish`, which
+         * the `write`, `delete` and `agent` key bundles carry, and a refusal comes
+         * back as `CapaError` with the API's own body.
+         *
+         * Times: send `wallTime` ("2026-10-01T09:00", no offset) and an IANA
+         * `timezone`. The server converts and tells you what it decided in
+         * `resolved`, including a `note` when daylight saving moved the time.
+         */
+        scheduledActions: {
+            async create(input) {
+                if (!input?.action)
+                    throw new Error("@capacms/sdk: scheduledActions.create needs an action.");
+                if (!input.targets?.length)
+                    throw new Error("@capacms/sdk: scheduledActions.create needs at least one target.");
+                if (!input.wallTime || !input.timezone) {
+                    throw new Error("@capacms/sdk: scheduledActions.create needs wallTime and timezone.");
+                }
+                // An offset in wallTime is a 400 from the server. Caught here because
+                // "2026-10-01T09:00Z" is the obvious thing to try and the round trip
+                // teaches nothing the message cannot.
+                if (/[Zz]$|[+-]\d{2}:?\d{2}$/.test(input.wallTime)) {
+                    throw new Error("@capacms/sdk: wallTime carries an offset. Send a local wall clock (\"2026-10-01T09:00\") and name the zone in timezone.");
+                }
+                return (0, http_1.writeJson)(resolved, "POST", "/v2/agent/scheduled-actions", input);
+            },
+            async list(options = {}) {
+                const { body } = await (0, http_1.getJson)(resolved, "/v2/agent/scheduled-actions", {
+                    status: options.status?.length ? options.status.join(",") : undefined,
+                    targetId: options.targetId,
+                    batchId: options.batchId,
+                    from: options.from,
+                    to: options.to,
+                    page: options.page,
+                    limit: options.limit,
+                });
+                return {
+                    actions: body.actions ?? [],
+                    pagination: body.pagination ?? { total: 0, page: 1, limit: 0, totalPages: 0, hasMore: false },
+                };
+            },
+            async get(id) {
+                try {
+                    const { body } = await (0, http_1.getJson)(resolved, `/v2/agent/scheduled-actions/${encodeURIComponent(id)}`);
+                    return body ?? null;
+                }
+                catch (err) {
+                    // A 404 here means "no such action for this tenant", which is an
+                    // answer rather than a failure. Everything else is still thrown.
+                    if (err instanceof http_1.CapaError && err.status === 404)
+                        return null;
+                    throw err;
+                }
+            },
+            async reschedule(id, when) {
+                return (0, http_1.writeJson)(resolved, "PATCH", `/v2/agent/scheduled-actions/${encodeURIComponent(id)}`, when);
+            },
+            async cancel(id) {
+                return (0, http_1.writeJson)(resolved, "POST", `/v2/agent/scheduled-actions/${encodeURIComponent(id)}/cancel`, {});
+            },
+            async retry(id) {
+                return (0, http_1.writeJson)(resolved, "POST", `/v2/agent/scheduled-actions/${encodeURIComponent(id)}/retry`, {});
+            },
+        },
+        webhooks: (0, webhooks_1.createWebhooks)(resolved),
+    };
+}

package/dist/codegen.d.ts

@@ -0,0 +1,69 @@
+/**
+ * codegen.ts — pull a tenant's generated types and write them to disk.
+ *
+ * WHY A COMMAND, AND NOT INSTALL-TIME OR BUILD-TIME
+ * Install-time generation needs credentials present at `npm install`, which
+ * breaks CI images and Docker builds. Build-time generation makes every build
+ * network-dependent and non-reproducible, and turns a Capa outage into a build
+ * outage for every customer site.
+ *
+ * So: an explicit command, with its OUTPUT COMMITTED to the consuming repo.
+ * That is also what makes the point of this whole feature work. "A model
+ * changed, so the build fails" is only useful if a human can see WHAT changed —
+ * and a committed generated file turns that into a reviewable line-level diff
+ * in a pull request instead of a wall of tsc errors with no cause attached.
+ *
+ * TWO SERVER-SIDE ROUGH EDGES, BOTH HANDLED HERE RATHER THAN PATCHED IN THE API
+ * The API is mid-port to a byte-parity bar, so changing a response on a
+ * customer-facing endpoint costs a signed exception. Neither of these is worth
+ * one, because both can be solved on this side and the fix is arguably better
+ * here anyway:
+ *
+ *   1. /v2/schema/types sets NO ETag and no Cache-Control, so it cannot be
+ *      revalidated cheaply. But /v2/schema DOES — it returns a `checksum` and
+ *      honours If-None-Match with a 304 (verified against a live tenant). That
+ *      checksum is sha256 over `{models, relations}` (routes/v2/schema.ts:190),
+ *      which is exactly what the types are generated FROM. So it is a sound
+ *      change signal for the types, and we spend one conditional request
+ *      returning 0 bytes when nothing has changed.
+ *
+ *   2. The generator orders models by `modelName` — the human display name —
+ *      while interfaces are NAMED from the namespace (`blogs_home_section` ->
+ *      `BlogsHomeSection`). So renaming a model's display name reorders the
+ *      whole file without changing a single type, producing a large diff and a
+ *      false "your types changed" signal in the exact mechanism this feature
+ *      rests on. We re-sort by interface name locally, which makes the
+ *      committed file stable under renames.
+ */
+import { type CapaConfig } from "./config";
+export interface CodegenResult {
+    /** False when the schema checksum was unchanged and nothing was fetched. */
+    changed: boolean;
+    checksum: string | null;
+    source: string | null;
+    /** Interface names present in the output, sorted. */
+    types: string[];
+}
+export interface SchemaModelField {
+    namespace: string;
+    type: string;
+    arrayType?: string | null;
+    relationRef?: string | null;
+}
+export interface SchemaModel {
+    id?: string;
+    namespace: string;
+    fields?: SchemaModelField[];
+}
+export interface SchemaForTypes {
+    models?: SchemaModel[];
+}
+/** Read the checksum a previous run stamped into the generated file. */
+export declare function readStampedChecksum(existing: string | null | undefined): string | null;
+export declare function normalizeTypes(source: string, checksum: string | null, schema?: SchemaForTypes | null): string;
+export declare function typeNames(source: string): string[];
+/**
+ * Fetch types if — and only if — the tenant's schema has changed since the
+ * checksum stamped in `existing`.
+ */
+export declare function generate(config: CapaConfig, existing?: string | null): Promise<CodegenResult>;

package/dist/codegen.js

@@ -0,0 +1,188 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readStampedChecksum = readStampedChecksum;
+exports.normalizeTypes = normalizeTypes;
+exports.typeNames = typeNames;
+exports.generate = generate;
+/**
+ * codegen.ts — pull a tenant's generated types and write them to disk.
+ *
+ * WHY A COMMAND, AND NOT INSTALL-TIME OR BUILD-TIME
+ * Install-time generation needs credentials present at `npm install`, which
+ * breaks CI images and Docker builds. Build-time generation makes every build
+ * network-dependent and non-reproducible, and turns a Capa outage into a build
+ * outage for every customer site.
+ *
+ * So: an explicit command, with its OUTPUT COMMITTED to the consuming repo.
+ * That is also what makes the point of this whole feature work. "A model
+ * changed, so the build fails" is only useful if a human can see WHAT changed —
+ * and a committed generated file turns that into a reviewable line-level diff
+ * in a pull request instead of a wall of tsc errors with no cause attached.
+ *
+ * TWO SERVER-SIDE ROUGH EDGES, BOTH HANDLED HERE RATHER THAN PATCHED IN THE API
+ * The API is mid-port to a byte-parity bar, so changing a response on a
+ * customer-facing endpoint costs a signed exception. Neither of these is worth
+ * one, because both can be solved on this side and the fix is arguably better
+ * here anyway:
+ *
+ *   1. /v2/schema/types sets NO ETag and no Cache-Control, so it cannot be
+ *      revalidated cheaply. But /v2/schema DOES — it returns a `checksum` and
+ *      honours If-None-Match with a 304 (verified against a live tenant). That
+ *      checksum is sha256 over `{models, relations}` (routes/v2/schema.ts:190),
+ *      which is exactly what the types are generated FROM. So it is a sound
+ *      change signal for the types, and we spend one conditional request
+ *      returning 0 bytes when nothing has changed.
+ *
+ *   2. The generator orders models by `modelName` — the human display name —
+ *      while interfaces are NAMED from the namespace (`blogs_home_section` ->
+ *      `BlogsHomeSection`). So renaming a model's display name reorders the
+ *      whole file without changing a single type, producing a large diff and a
+ *      false "your types changed" signal in the exact mechanism this feature
+ *      rests on. We re-sort by interface name locally, which makes the
+ *      committed file stable under renames.
+ */
+const config_1 = require("./config");
+const http_1 = require("./http");
+const MARKER = "// @capa-schema-checksum ";
+/**
+ * The same checksum as a VALUE, not just a comment, so a site can send it back.
+ *
+ * `MARKER` is what `--check` and the conditional request read; this is what the
+ * customer's own code imports and hands to `createClient({ schemaChecksum })`,
+ * which puts it on the wire as `Capa-Schema` and makes the `drift` insight
+ * possible. One source, two spellings, and stripping BOTH on a re-run is what
+ * keeps `normalizeTypes` idempotent.
+ */
+const CHECKSUM_CONST = "export const CAPA_SCHEMA_CHECKSUM = ";
+/** Header lines this module writes, recognised so they can be stripped on re-run. */
+const GENERATED_HEADER = new Set([
+    "// Generated by @capacms/sdk. Do not edit by hand.",
+    "// Re-run `capa-codegen` after changing a model in Capa.",
+]);
+/** Read the checksum a previous run stamped into the generated file. */
+function readStampedChecksum(existing) {
+    if (!existing)
+        return null;
+    for (const line of existing.split("\n", 20)) {
+        if (line.startsWith(MARKER))
+            return line.slice(MARKER.length).trim() || null;
+    }
+    return null;
+}
+/**
+ * Sort declarations by name so the file is stable regardless of the order the
+ * server emitted them in. The leading comment block is kept as a preamble; the
+ * shared `Capa*` helpers are kept ahead of tenant types because they are the
+ * primitives everything else refers to.
+ */
+function toPascalCase(str) {
+    return str
+        .split(/[-_]/)
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+        .join("");
+}
+function relationTarget(ref, models) {
+    const target = models.find((model) => model.id === ref || model.namespace === ref);
+    return target ? toPascalCase(target.namespace) : "unknown";
+}
+function hasRelations(schema) {
+    return !!schema?.models?.some((model) => (model.fields ?? []).some((field) => (field.type === "relation" || (field.type === "array" && field.arrayType === "relation")) && field.relationRef));
+}
+function rewriteRelationFields(block, schema) {
+    const name = (/^export interface (\w+)/.exec(block) || [])[1];
+    if (!name)
+        return block;
+    const model = schema.models.find((candidate) => toPascalCase(candidate.namespace) === name);
+    if (!model)
+        return block;
+    let out = block;
+    for (const field of model.fields ?? []) {
+        if (!field.relationRef)
+            continue;
+        const target = relationTarget(field.relationRef, schema.models);
+        const helper = field.type === "relation"
+            ? `CapaRelation<${target}>`
+            : field.type === "array" && field.arrayType === "relation"
+                ? `CapaRelationList<${target}>`
+                : null;
+        if (!helper)
+            continue;
+        const escaped = field.namespace.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        out = out.replace(new RegExp(`^(\\s*${escaped}\\??:\\s*)[^;]+;`, "m"), `$1${helper};`);
+    }
+    return out;
+}
+function relationPreamble() {
+    return [
+        'export type CapaRelation<T> = T & { readonly __capaRelation: "one"; readonly __capaRelationTarget: T };',
+        'export type CapaRelationList<T> = T[] & { readonly __capaRelation: "many"; readonly __capaRelationTarget: T };',
+        "",
+    ].join("\n");
+}
+function selectAliases(parts, schema) {
+    const names = new Set(parts.map((part) => (/^export interface (\w+)/.exec(part) || [])[1]).filter(Boolean));
+    return schema.models
+        .map((model) => toPascalCase(model.namespace))
+        .filter((name) => names.has(name))
+        .sort()
+        .map((name) => `export type ${name}Select = import("@capacms/sdk/next").Select<${name}>;`);
+}
+function normalizeTypes(source, checksum, schema) {
+    // Strip a header a previous run wrote, so normalize(normalize(x)) === normalize(x).
+    // Without this the old header is treated as preamble and a new one stacks on
+    // top of it, and the checksum marker this file is READ BACK for (--check,
+    // and the conditional request in generate) ends up duplicated.
+    const withoutHeader = source
+        .split("\n")
+        .filter((l) => !l.startsWith(MARKER) &&
+        !l.startsWith(CHECKSUM_CONST) &&
+        !GENERATED_HEADER.has(l.trim()))
+        .join("\n")
+        .replace(/^\n+/, "");
+    const parts = withoutHeader.split(/\n(?=export (?:interface|type) )/);
+    const preamble = parts.length && !/^export (?:interface|type) /.test(parts[0]) ? parts.shift() : "";
+    const nameOf = (b) => (/^export (?:interface|type) (\w+)/.exec(b) || [])[1] ?? "";
+    const byName = (a, b) => nameOf(a).localeCompare(nameOf(b));
+    const schemaWithRelations = hasRelations(schema) ? schema : null;
+    const rewritten = schemaWithRelations ? parts.map((part) => rewriteRelationFields(part, schemaWithRelations)) : parts;
+    const shared = rewritten.filter((p) => /^export (?:interface|type) Capa/.test(p)).sort(byName);
+    const rest = rewritten.filter((p) => !/^export (?:interface|type) Capa/.test(p)).sort(byName);
+    const relationHelpers = schemaWithRelations ? [relationPreamble().trimEnd()] : [];
+    const aliases = schemaWithRelations ? selectAliases(rest, schemaWithRelations) : [];
+    const head = [
+        "// Generated by @capacms/sdk. Do not edit by hand.",
+        "// Re-run `capa-codegen` after changing a model in Capa.",
+        checksum ? MARKER + checksum : null,
+        // Only when there is a checksum, the same rule the marker follows. An
+        // exported constant holding an empty string would be worse than an absent
+        // one: it would compile, reach the wire, be ignored as malformed, and
+        // leave a site looking permanently up to date.
+        checksum ? `${CHECKSUM_CONST}${JSON.stringify(checksum)};` : null,
+    ]
+        .filter(Boolean)
+        .join("\n");
+    const body = [...shared, ...relationHelpers, ...rest, ...aliases].map((b) => b.replace(/\s+$/, "")).join("\n\n");
+    const kept = preamble.trim() ? preamble.trim() + "\n\n" : "";
+    return `${head}\n\n${kept}${body}\n`;
+}
+function typeNames(source) {
+    return [...source.matchAll(/^export (?:interface|type) (\w+)/gm)].map((m) => m[1]).sort();
+}
+/**
+ * Fetch types if — and only if — the tenant's schema has changed since the
+ * checksum stamped in `existing`.
+ */
+async function generate(config, existing) {
+    const resolved = (0, config_1.resolveConfig)(config);
+    const stamped = readStampedChecksum(existing);
+    const etag = stamped ? `"${stamped}"` : null;
+    const schema = await (0, http_1.getJsonConditional)(resolved, "/v2/schema", etag);
+    if (schema === null) {
+        // 304 — the model set is byte-identical to what produced the file on disk.
+        return { changed: false, checksum: stamped, source: null, types: [] };
+    }
+    const checksum = schema.body?.checksum ?? (schema.etag ? schema.etag.replace(/"/g, "") : null);
+    const raw = await (0, http_1.getText)(resolved, "/v2/schema/types");
+    const source = normalizeTypes(raw, checksum, schema.body);
+    return { changed: source !== (existing ?? null), checksum, source, types: typeNames(source) };
+}

package/dist/config.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Client configuration, and the one thing about it that is not obvious.
+ *
+ * PREVIEW IS A KEY, NOT A FLAG
+ * Capa gates unpublished content on the API key's `environment` column, not on
+ * anything in the request:
+ *
+ *     // apps/api/src/routes/v2/api.ts:203
+ *     const environment = req.apiKeyEnvironment || "production";
+ *     const includeDrafted = environment === "production" ? false : true;
+ *
+ * So there is no `?preview=true` to pass, and `getContent(ns, id, {preview})`
+ * CANNOT be implemented against a published key — the server would ignore it.
+ * The honest surface is one client per key:
+ *
+ *     const capa    = createClient({ ...cfg, apiKey: PUBLISHED_KEY })
+ *     const preview = createClient({ ...cfg, apiKey: PREVIEW_KEY })
+ *
+ * Note also that the comparison above is exact and case-sensitive against a
+ * free-text column, so ANY environment that is not literally "production"
+ * returns drafts — `staging`, `development`, `draft`, and equally a typo like
+ * "Production".
+ *
+ * AND A CLIENT CANNOT FIND OUT WHICH IT HAS.
+ * There is deliberately no `includesDrafts()` here, because it cannot be
+ * implemented: `apiKeyEnvironment` is set in verifyApiKey.ts:57, consumed
+ * internally to compute `includeDrafted`, and returned to the caller by NO
+ * endpoint. /v2/schema carries only {models, relations, checksum, generatedAt}.
+ *
+ * So a site handed a `draft`, `staging` or `development` key serves unpublished
+ * content to the public, and has no way to detect it — not at startup, not at
+ * runtime, not from any response. In production-shaped data 29 of 74 keys are
+ * non-production. Whatever this SDK offers, it cannot make that safe; the fix
+ * is for Capa to report the key's environment on a read a client already makes.
+ */
+export interface CapaConfig {
+    /** Base URL of the Capa API, e.g. https://api.example.com. No trailing slash required. */
+    baseUrl: string;
+    /** A tenant API key. Read scope is all the SDK needs. */
+    apiKey: string;
+    /** The tenant the key belongs to. */
+    tenantId: string;
+    /**
+     * A session access token, from `POST /v2/user/login`, sent as
+     * `Authorization: Bearer`.
+     *
+     * Only `webhooks.*` uses it, and only because it has to: the webhook routes
+     * have no API key mount (publishing spec D8), so endpoints are managed by a
+     * logged-in person or not at all. Every other method on the client ignores
+     * this field and keeps using `apiKey`.
+     */
+    accessToken?: string;
+    /** Injected in tests; defaults to the global fetch. */
+    fetch?: typeof fetch;
+}
+export interface ResolvedConfig extends CapaConfig {
+    baseUrl: string;
+    fetchImpl: typeof fetch;
+}
+export declare function resolveConfig(config: CapaConfig): ResolvedConfig;

package/dist/config.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveConfig = resolveConfig;
+function resolveConfig(config) {
+    const missing = ["baseUrl", "apiKey", "tenantId"].filter((k) => !config[k]);
+    if (missing.length) {
+        throw new Error(`@capacms/sdk: missing ${missing.join(", ")}. ` +
+            `createClient needs baseUrl, apiKey and tenantId.`);
+    }
+    const fetchImpl = config.fetch ?? globalThis.fetch;
+    if (typeof fetchImpl !== "function") {
+        throw new Error("@capacms/sdk: no fetch available. Pass one via config.fetch on older runtimes.");
+    }
+    return { ...config, baseUrl: config.baseUrl.replace(/\/+$/, ""), fetchImpl };
+}