@capacms/sdk 1.0.0-next.1 → 1.0.0-next.10

package/dist/client.js

@@ -19,6 +19,7 @@ exports.createClient = createClient;
  */
 const config_1 = require("./config");
 const http_1 = require("./http");
+const key_family_1 = require("./next/key-family");
 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;
 /**
@@ -64,7 +65,23 @@ function contentQuery(options = {}) {
         q[k] = v;
     return q;
 }
+/**
+ * `/v2` answers every `cap_` key "Invalid API key", which reads as a bad key
+ * rather than the wrong client, so one is refused here before the tenant id is
+ * asked for or anything is sent. The rule is the API's: `cap_`, case-sensitive.
+ */
+function refuseCapKey(apiKey) {
+    if ((0, key_family_1.keyFamily)(apiKey) !== "cap")
+        return;
+    throw new TypeError('@capacms/sdk: this is the legacy /v2/api client, and cap_ keys read /api/: import { createClient } from "@capacms/sdk/next".');
+}
+/**
+ * The legacy `/v2/api` client, for a legacy key (`pk_`, `sk_` or unprefixed)
+ * and its tenant's id. For `/api/`, GraphQL and `cap_` keys, import
+ * `createClient` from `@capacms/sdk/next`.
+ */
 function createClient(config) {
+    refuseCapKey(config.apiKey);
     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));

package/dist/codegen.d.ts

@@ -36,6 +36,7 @@
  *      committed file stable under renames.
  */
 import { type CapaConfig } from "./config";
+import type { CapaIntrospection } from "./next/graphql/introspection";
 export interface CodegenResult {
     /** False when the schema checksum was unchanged and nothing was fetched. */
     changed: boolean;
@@ -49,6 +50,8 @@ export interface SchemaModelField {
     type: string;
     arrayType?: string | null;
     relationRef?: string | null;
+    enumValues?: string[] | null;
+    required?: boolean | null;
 }
 export interface SchemaModel {
     id?: string;
@@ -60,6 +63,23 @@ export interface SchemaForTypes {
 }
 /** Read the checksum a previous run stamped into the generated file. */
 export declare function readStampedChecksum(existing: string | null | undefined): string | null;
+/**
+ * The interface name for a name `/v2/schema/types` wrote. That route prints
+ * the PascalCase of the namespace whatever it holds, which is not always an
+ * identifier (`2024Events`, `Blog.posts`), and it is frozen legacy, so the
+ * file is made to parse here. The rule is GraphQL's (N1): every character
+ * outside [0-9A-Za-z] dropped and `_` before a leading digit, so
+ * `2024_events` is `_2024Events` in REST types and GraphQL types alike.
+ */
+export declare function interfaceName(written: string): string;
+/**
+ * Each model's interface name, by namespace. Two namespaces can give one
+ * PascalCase name (`twin_a` and `twin-a` are both `TwinA`), as can a model and
+ * another's `Select` or `Attrs` alias, or a shared declaration, and a module
+ * cannot declare an alias twice. Every model caught in such a collision is
+ * named by `namespaceInterface` instead, whatever order the models come in.
+ */
+export declare function modelInterfaceNames(models: readonly SchemaModel[]): Map<string, string>;
 export declare function normalizeTypes(source: string, checksum: string | null, schema?: SchemaForTypes | null): string;
 export declare function typeNames(source: string): string[];
 /**
@@ -67,3 +87,38 @@ export declare function typeNames(source: string): string[];
  * checksum stamped in `existing`.
  */
 export declare function generate(config: CapaConfig, existing?: string | null): Promise<CodegenResult>;
+/**
+ * `/v2/schema/types`'s type map and preamble, so a `cap_` key, which `/v2`
+ * does not take, gets the interfaces a legacy key gets. Copied from
+ * `apps/api/src/routes/v2/schema.ts`, which is frozen legacy; a test holds the
+ * two equal.
+ */
+export declare const LEGACY_TYPE_MAP: Readonly<Record<string, string>>;
+export declare const LEGACY_PREAMBLE = "export interface CapaImage {\n  url: string;\n  alt?: string;\n  width?: number;\n  height?: number;\n  filesize?: number;\n  filename?: string;\n}\n\nexport interface CapaVideo {\n  url: string;\n  thumbnail?: string;\n  duration?: number;\n  width?: number;\n  height?: number;\n  filesize?: number;\n  filename?: string;\n}\n\nexport interface CapaFile {\n  url: string;\n  filename: string;\n  filesize?: number;\n  type?: string;\n}\n\nexport interface CapaInstance<T = Record<string, unknown>> {\n  id: string;\n  title?: string;\n  slug?: string;\n  data: T;\n  status: 'draft' | 'published';\n  createdAt: string;\n  updatedAt: string;\n  publishedAt?: string;\n}\n\n";
+export interface RestTypesResult {
+    source: string;
+    /** Interface names present in the output, sorted. */
+    types: string[];
+    /**
+     * Models the key reads that the GraphQL schema leaves out, since their type
+     * names would collide (N1). The schema says nothing of their fields, so no
+     * interface is written for them.
+     */
+    restOnly: string[];
+}
+/**
+ * The REST model interfaces for a key's GraphQL schema: what
+ * `/v2/schema/types` and `/v2/schema` give a legacy key, for a `cap_` key.
+ * The model namespaces, field namespaces, Capa types and relation targets
+ * come from the schema's descriptions (N9), so the interfaces are keyed as
+ * REST reads them (`open-time`), not as GraphQL renames them (`open_time`).
+ *
+ * The text is written as the legacy route writes it and goes through
+ * `normalizeTypes`, the one place that turns that text into a module. Three
+ * things GraphQL does not say are written as it can: every field is optional,
+ * since the schema has no required flag; an enum is `string`, since it lists
+ * no values; and a field GraphQL leaves out (its description's `Not exposed:`
+ * line) is `unknown`. No checksum is stamped: `CAPA_SCHEMA_CHECKSUM` is the
+ * `/v2/schema` checksum, which a `cap_` key cannot read.
+ */
+export declare function restTypesFromIntrospection(introspection: CapaIntrospection): RestTypesResult;

package/dist/codegen.js

@@ -1,9 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.LEGACY_PREAMBLE = exports.LEGACY_TYPE_MAP = void 0;
 exports.readStampedChecksum = readStampedChecksum;
+exports.interfaceName = interfaceName;
+exports.modelInterfaceNames = modelInterfaceNames;
 exports.normalizeTypes = normalizeTypes;
 exports.typeNames = typeNames;
 exports.generate = generate;
+exports.restTypesFromIntrospection = restTypesFromIntrospection;
 /**
  * codegen.ts — pull a tenant's generated types and write them to disk.
  *
@@ -43,6 +47,7 @@ exports.generate = generate;
  */
 const config_1 = require("./config");
 const http_1 = require("./http");
+const summary_1 = require("./next/graphql/summary");
 const MARKER = "// @capa-schema-checksum ";
 /**
  * The same checksum as a VALUE, not just a comment, so a site can send it back.
@@ -69,48 +74,174 @@ function readStampedChecksum(existing) {
     }
     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.
- */
+/** PascalCase of a namespace, as `/v2/schema/types` names a model's interface. */
 function toPascalCase(str) {
     return str
         .split(/[-_]/)
         .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
         .join("");
 }
-function relationTarget(ref, models) {
+/** A TypeScript identifier: what an interface name must be, and a property key may be written bare. */
+const IDENTIFIER = /^[A-Za-z_$][0-9A-Za-z_$]*$/;
+/** A model interface's first line, as `/v2/schema/types` writes it. */
+const INTERFACE_HEADER = /^export interface (.+) \{$/;
+/** A property of a model interface, `  name?: type;`, the name written verbatim, or quoted by an earlier run. */
+const PROPERTY = /^(\s+)(.+?)(\?)?: (.+);$/;
+/**
+ * The interface name for a name `/v2/schema/types` wrote. That route prints
+ * the PascalCase of the namespace whatever it holds, which is not always an
+ * identifier (`2024Events`, `Blog.posts`), and it is frozen legacy, so the
+ * file is made to parse here. The rule is GraphQL's (N1): every character
+ * outside [0-9A-Za-z] dropped and `_` before a leading digit, so
+ * `2024_events` is `_2024Events` in REST types and GraphQL types alike.
+ */
+function interfaceName(written) {
+    if (IDENTIFIER.test(written))
+        return written;
+    const letters = written.replace(/[^0-9A-Za-z]/g, "") || "_";
+    return /^[0-9]/.test(letters) ? `_${letters}` : letters;
+}
+/** The interface a model's entries are typed with, before `modelInterfaceNames` settles collisions. */
+function modelInterface(namespace) {
+    return interfaceName(toPascalCase(namespace));
+}
+/** Declarations every generated file holds beside the models (`LEGACY_PREAMBLE`, `relationPreamble`). */
+const SHARED_NAMES = ["CapaImage", "CapaVideo", "CapaFile", "CapaInstance", "CapaRelation", "CapaRelationList"];
+/**
+ * A model's interface named from its whole namespace: `Model_` and the
+ * namespace with each character outside [0-9A-Za-z_] written `$` and its hex
+ * code, so `twin-a` is `Model_twin$2da`. No two namespaces give the same one.
+ */
+function namespaceInterface(namespace) {
+    return `Model_${[...namespace].map((ch) => (/[0-9A-Za-z_]/.test(ch) ? ch : `$${ch.codePointAt(0).toString(16)}`)).join("")}`;
+}
+/**
+ * Each model's interface name, by namespace. Two namespaces can give one
+ * PascalCase name (`twin_a` and `twin-a` are both `TwinA`), as can a model and
+ * another's `Select` or `Attrs` alias, or a shared declaration, and a module
+ * cannot declare an alias twice. Every model caught in such a collision is
+ * named by `namespaceInterface` instead, whatever order the models come in.
+ */
+function modelInterfaceNames(models) {
+    const claims = new Map(SHARED_NAMES.map((name) => [name, new Set([""])]));
+    for (const { namespace } of models) {
+        const base = modelInterface(namespace);
+        for (const name of [base, `${base}Select`, `${base}Attrs`]) {
+            if (!claims.has(name))
+                claims.set(name, new Set());
+            claims.get(name).add(namespace);
+        }
+    }
+    const collided = new Set([...claims.values()].filter((owners) => owners.size > 1).flatMap((owners) => [...owners]));
+    return new Map(models.map(({ namespace }) => [namespace, collided.has(namespace) ? namespaceInterface(namespace) : modelInterface(namespace)]));
+}
+/** A field namespace as a property key: bare when it is an identifier, quoted otherwise (`"am/pm_indicator"`). */
+function propertyKey(namespace) {
+    return IDENTIFIER.test(namespace) ? namespace : JSON.stringify(namespace);
+}
+/** The namespace a property key names: a key an earlier run quoted is read back. */
+function keyNamespace(key) {
+    if (!/^".*"$/.test(key))
+        return key;
+    try {
+        const parsed = JSON.parse(key);
+        return typeof parsed === "string" ? parsed : key;
+    }
+    catch {
+        return key;
+    }
+}
+/**
+ * An enum value as a TypeScript string literal. Single quotes, as
+ * `/v2/schema/types` writes it, so a value with nothing to escape keeps its
+ * bytes; that route writes `it's` and `a\b` unescaped, which does not parse or
+ * reads another value.
+ */
+function enumLiteral(value) {
+    return `'${value.replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/\n/g, "\\n")}'`;
+}
+function relationTarget(ref, models, names) {
     const target = models.find((model) => model.id === ref || model.namespace === ref);
-    return target ? toPascalCase(target.namespace) : "unknown";
+    return target ? names.get(target.namespace) ?? modelInterface(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)
+/**
+ * A field's type from the schema, where the schema says more than the text:
+ * a relation as its branded helper (only when the schema has relations, so a
+ * schema without keeps its bytes), and an enum's values escaped. Null to keep
+ * the type the text wrote.
+ */
+function schemaFieldType(field, models, relations, names) {
+    if (relations && field.relationRef) {
+        const target = relationTarget(field.relationRef, models, names);
+        if (field.type === "relation")
+            return `CapaRelation<${target}>`;
+        if (field.type === "array" && field.arrayType === "relation")
+            return `CapaRelationList<${target}>`;
+    }
+    if (field.type === "enum" && field.enumValues?.length)
+        return field.enumValues.map(enumLiteral).join(" | ");
+    return null;
+}
+/** A union of single-quoted string literals that parses: each quote and backslash inside escaped. */
+const LITERAL_UNION = /^'(?:[^'\\\n]|\\.)*'(?: \| '(?:[^'\\\n]|\\.)*')*$/;
+/**
+ * A type as the text wrote it, made to parse without the schema: a model
+ * interface it names (`2024Events`, `2024Events[]`) renamed as its declaration
+ * was, and an enum whose values the text cannot carry (`'it's fine'`) a
+ * `string`, since only the schema holds the values.
+ */
+function writtenType(written, renamed) {
+    if (written.startsWith("'"))
+        return LITERAL_UNION.test(written) ? written : "string";
+    const [, name, list = ""] = /^(.+?)((?:\[\])?)$/.exec(written) ?? [];
+    return name !== undefined && renamed.has(name) ? `${renamed.get(name)}${list}` : written;
+}
+/**
+ * One model interface made to parse and typed from the schema: named `name`,
+ * every key that is not an identifier quoted, relations and enums as
+ * `schemaFieldType` says.
+ */
+function rewriteModelBlock(block, model, name, module) {
+    const lines = block.split("\n");
+    lines[0] = `export interface ${name} {`;
+    for (let i = 1; i < lines.length; i += 1) {
+        const property = PROPERTY.exec(lines[i]);
+        if (!property)
             continue;
-        const escaped = field.namespace.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-        out = out.replace(new RegExp(`^(\\s*${escaped}\\??:\\s*)[^;]+;`, "m"), `$1${helper};`);
+        const [, indent, key, optional = "", written] = property;
+        const namespace = keyNamespace(key);
+        const field = model?.fields?.find((candidate) => candidate.namespace === namespace);
+        const type = (field && schemaFieldType(field, module.models, module.relations, module.names)) ?? writtenType(written, module.renamed);
+        lines[i] = `${indent}${propertyKey(namespace)}${optional}: ${type};`;
+    }
+    return lines.join("\n");
+}
+/** A field's type as `/v2/schema/types` writes it from the schema: a relation as its interface, anything unmapped `unknown`. */
+function legacySchemaType(field, module) {
+    const scalar = (type) => exports.LEGACY_TYPE_MAP[type ?? ""] ?? "unknown";
+    const target = () => (field.relationRef ? relationTarget(field.relationRef, module.models, module.names) : "unknown");
+    if (field.type === "relation" && field.relationRef)
+        return target();
+    if (field.type === "array" && field.arrayType)
+        return `${field.arrayType === "relation" && field.relationRef ? target() : scalar(field.arrayType)}[]`;
+    return scalar(field.type);
+}
+/**
+ * A model's interface written from the schema alone, as `/v2/schema/types`
+ * writes one. For models that route names alike (`TwinA` twice), whose text
+ * cannot say which block is which model.
+ */
+function schemaModelBlock(model, module) {
+    const lines = [`export interface ${module.names.get(model.namespace)} {`];
+    for (const field of model.fields ?? []) {
+        const type = schemaFieldType(field, module.models, module.relations, module.names) ?? legacySchemaType(field, module);
+        lines.push(`  ${propertyKey(field.namespace)}${field.required ? "" : "?"}: ${type};`);
     }
-    return out;
+    lines.push("}");
+    return lines.join("\n");
 }
 function relationPreamble() {
     return [
@@ -119,13 +250,18 @@ function relationPreamble() {
         "",
     ].join("\n");
 }
-function selectAliases(parts, schema) {
-    const names = new Set(parts.map((part) => (/^export interface (\w+)/.exec(part) || [])[1]).filter(Boolean));
+function selectAliases(parts, schema, modelNames) {
+    const names = new Set(parts.map((part) => (/^export interface ([\w$]+)/.exec(part) || [])[1]).filter(Boolean));
     return schema.models
-        .map((model) => toPascalCase(model.namespace))
+        .map((model) => modelNames.get(model.namespace) ?? modelInterface(model.namespace))
         .filter((name) => names.has(name))
         .sort()
-        .map((name) => `export type ${name}Select = import("@capacms/sdk/next").Select<${name}>;`);
+        .flatMap((name) => [
+        `export type ${name}Select = import("@capacms/sdk/next").Select<${name}>;`,
+        // M5: fieldAttrs(entry) typed per model, so a wrong field name fails
+        // to compile, as in `const a: ArticleAttrs = fieldAttrs(entry)`.
+        `export type ${name}Attrs = import("@capacms/sdk/next").FieldAttrs<${name}>;`,
+    ]);
 }
 function normalizeTypes(source, checksum, schema) {
     // Strip a header a previous run wrote, so normalize(normalize(x)) === normalize(x).
@@ -141,14 +277,49 @@ function normalizeTypes(source, checksum, schema) {
         .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 nameOf = (b) => (/^export (?:interface|type) ([\w$]+)/.exec(b) || [])[1] ?? "";
     const byName = (a, b) => nameOf(a).localeCompare(nameOf(b));
+    const isShared = (b) => SHARED_NAMES.includes(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 models = schema?.models ?? [];
+    const names = modelInterfaceNames(models);
+    // The models each block's header can mean: the route writes a model's
+    // PascalCase name, an earlier run its settled name.
+    const candidates = (written) => {
+        const name = interfaceName(written);
+        return models.filter((model) => modelInterface(model.namespace) === name || names.get(model.namespace) === name);
+    };
+    const renamed = new Map();
+    for (const part of parts) {
+        const written = isShared(part) ? undefined : INTERFACE_HEADER.exec(part.split("\n", 1)[0])?.[1];
+        if (written === undefined)
+            continue;
+        const found = candidates(written);
+        const name = found.length === 1 ? names.get(found[0].namespace) : interfaceName(written);
+        if (found.length <= 1 && name !== written)
+            renamed.set(written, name);
+    }
+    const module = { models, names, relations: schemaWithRelations !== null, renamed };
+    const rewritten = [];
+    const fromSchema = new Set();
+    for (const part of parts) {
+        const header = isShared(part) ? null : INTERFACE_HEADER.exec(part.split("\n", 1)[0]);
+        if (!header) {
+            rewritten.push(part);
+            continue;
+        }
+        const found = candidates(header[1]);
+        if (found.length > 1)
+            found.forEach((model) => fromSchema.add(model));
+        else
+            rewritten.push(rewriteModelBlock(part, found[0], found.length ? names.get(found[0].namespace) : interfaceName(header[1]), module));
+    }
+    for (const model of fromSchema)
+        rewritten.push(schemaModelBlock(model, module));
+    const shared = rewritten.filter(isShared).sort(byName);
+    const rest = rewritten.filter((p) => !isShared(p)).sort(byName);
     const relationHelpers = schemaWithRelations ? [relationPreamble().trimEnd()] : [];
-    const aliases = schemaWithRelations ? selectAliases(rest, schemaWithRelations) : [];
+    const aliases = schemaWithRelations ? selectAliases(rest, schemaWithRelations, names) : [];
     const head = [
         "// Generated by @capacms/sdk. Do not edit by hand.",
         "// Re-run `capa-codegen` after changing a model in Capa.",
@@ -166,7 +337,7 @@ function normalizeTypes(source, checksum, schema) {
     return `${head}\n\n${kept}${body}\n`;
 }
 function typeNames(source) {
-    return [...source.matchAll(/^export (?:interface|type) (\w+)/gm)].map((m) => m[1]).sort();
+    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
@@ -186,3 +357,113 @@ async function generate(config, existing) {
     const source = normalizeTypes(raw, checksum, schema.body);
     return { changed: source !== (existing ?? null), checksum, source, types: typeNames(source) };
 }
+// ------------------------------------------- from a key's GraphQL schema ---
+/**
+ * `/v2/schema/types`'s type map and preamble, so a `cap_` key, which `/v2`
+ * does not take, gets the interfaces a legacy key gets. Copied from
+ * `apps/api/src/routes/v2/schema.ts`, which is frozen legacy; a test holds the
+ * two equal.
+ */
+exports.LEGACY_TYPE_MAP = {
+    string: "string",
+    markdown: "string",
+    html: "string",
+    code: "string",
+    color: "string",
+    number: "number",
+    true_false: "boolean",
+    date: "string",
+    image: "CapaImage",
+    video: "CapaVideo",
+    file: "CapaFile",
+    json: "Record<string, unknown>",
+    rich_text: "string",
+};
+exports.LEGACY_PREAMBLE = `export interface CapaImage {
+  url: string;
+  alt?: string;
+  width?: number;
+  height?: number;
+  filesize?: number;
+  filename?: string;
+}
+
+export interface CapaVideo {
+  url: string;
+  thumbnail?: string;
+  duration?: number;
+  width?: number;
+  height?: number;
+  filesize?: number;
+  filename?: string;
+}
+
+export interface CapaFile {
+  url: string;
+  filename: string;
+  filesize?: number;
+  type?: string;
+}
+
+export interface CapaInstance<T = Record<string, unknown>> {
+  id: string;
+  title?: string;
+  slug?: string;
+  data: T;
+  status: 'draft' | 'published';
+  createdAt: string;
+  updatedAt: string;
+  publishedAt?: string;
+}
+
+`;
+/** A field's type as `/v2/schema/types` writes it, from what GraphQL says of it. */
+function legacyFieldType(field) {
+    // GraphQL types an enum as String, and lists its values for people only.
+    const scalar = (type) => (type === "enum" ? "string" : exports.LEGACY_TYPE_MAP[type ?? ""] ?? "unknown");
+    const target = field.target === null ? "unknown" : toPascalCase(field.target);
+    if (field.capaType === "relation")
+        return target;
+    if (field.capaType === "array")
+        return `${field.arrayType === "relation" ? target : scalar(field.arrayType)}[]`;
+    return scalar(field.capaType);
+}
+/**
+ * The REST model interfaces for a key's GraphQL schema: what
+ * `/v2/schema/types` and `/v2/schema` give a legacy key, for a `cap_` key.
+ * The model namespaces, field namespaces, Capa types and relation targets
+ * come from the schema's descriptions (N9), so the interfaces are keyed as
+ * REST reads them (`open-time`), not as GraphQL renames them (`open_time`).
+ *
+ * The text is written as the legacy route writes it and goes through
+ * `normalizeTypes`, the one place that turns that text into a module. Three
+ * things GraphQL does not say are written as it can: every field is optional,
+ * since the schema has no required flag; an enum is `string`, since it lists
+ * no values; and a field GraphQL leaves out (its description's `Not exposed:`
+ * line) is `unknown`. No checksum is stamped: `CAPA_SCHEMA_CHECKSUM` is the
+ * `/v2/schema` checksum, which a `cap_` key cannot read.
+ */
+function restTypesFromIntrospection(introspection) {
+    const summary = (0, summary_1.summarizeIntrospection)(introspection);
+    let text = `// Auto-generated Capa CMS types\n\n${exports.LEGACY_PREAMBLE}`;
+    const models = [];
+    for (const model of summary.models) {
+        text += `export interface ${toPascalCase(model.namespace)} {\n`;
+        for (const field of model.fields)
+            text += `  ${field.namespace}?: ${legacyFieldType(field)};\n`;
+        for (const namespace of model.notExposed)
+            text += `  ${namespace}?: unknown;\n`;
+        text += "}\n\n";
+        models.push({
+            namespace: model.namespace,
+            fields: model.fields.map((field) => ({
+                namespace: field.namespace,
+                type: field.capaType,
+                arrayType: field.arrayType,
+                relationRef: field.target,
+            })),
+        });
+    }
+    const source = normalizeTypes(text, null, { models });
+    return { source, types: typeNames(source), restOnly: summary.restOnly };
+}

package/dist/config.d.ts

@@ -1,42 +1,11 @@
-/**
- * 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. */
+    /**
+     * A legacy tenant API key: `pk_`, `sk_` or unprefixed. Read scope is all the
+     * client needs. A `cap_` key reads `/api/`, with `createClient` from
+     * `@capacms/sdk/next`, and is refused here.
+     */
     apiKey: string;
     /** The tenant the key belongs to. */
     tenantId: string;

package/dist/config.js

@@ -1,13 +1,59 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveConfig = resolveConfig;
+/**
+ * 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.
+ */
+/**
+ * The platform fetch, called through `globalThis` on every request. Storing
+ * `globalThis.fetch` and calling it as a method of the config object gives it
+ * the wrong `this`, and a browser refuses that ("Illegal invocation"). Looking
+ * it up per call also picks up a fetch a framework patches in later.
+ */
+function defaultFetch() {
+    if (typeof globalThis.fetch !== "function")
+        return undefined;
+    return ((input, init) => globalThis.fetch(input, init));
+}
 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;
+    const fetchImpl = config.fetch ?? defaultFetch();
     if (typeof fetchImpl !== "function") {
         throw new Error("@capacms/sdk: no fetch available. Pass one via config.fetch on older runtimes.");
     }