@capacms/sdk 1.0.0-next.3 → 1.0.0-next.6

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

@@ -36,7 +36,11 @@
 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/graphql-codegen.d.ts

@@ -0,0 +1,117 @@
+/**
+ * graphql-codegen.ts — `capa-codegen --graphql` and `capa persist`, the pure half.
+ *
+ * Reads a key's schema (introspection JSON) and a project's GraphQL documents,
+ * validates every document against that schema, and writes ONE TypeScript
+ * module holding:
+ *
+ *   - the schema as types, for `createClient<CapaQuery>()` and the typed
+ *     builder (`client.graphql.query`);
+ *   - one `TypedDocument` constant per named operation, so
+ *     `client.graphql(ArticlesPageDocument, vars)` infers the result and the
+ *     variables with no cast, and beside it `<Name>Models`, the models it
+ *     reads, for its Next.js cache tags;
+ *   - for each document written as a literal (`#graphql`, `/* capa *\/` or
+ *     gql(`...`)), an entry in `CapaDocuments` keyed by its exact text, so
+ *     `client.graphql(LITERAL, vars)` infers them too, with no import;
+ *   - `capaTreeLayout`, what `toTree` reads of the schema, so a server lays a
+ *     builder result out in REST's shape without reading the schema first.
+ *
+ * The file walk and the network live in `bin/`; everything here is a function
+ * of its inputs, so it is tested without either.
+ *
+ * `graphql` (graphql-js) is loaded on first use, never at import: it is an
+ * optional peer dependency that only these commands need, and a site that
+ * only calls `client.graphql()` must not pay for it.
+ */
+import type * as GraphQLJs from "graphql";
+import type { CapaIntrospection } from "./next/graphql/introspection";
+/** graphql-js, or an error that says how to get it. */
+export declare function loadGraphQL(): typeof GraphQLJs;
+/** One GraphQL document found in a project, with where it came from. */
+export interface DocumentSource {
+    file: string;
+    /** 1-based line of the document's first character in `file`. */
+    line: number;
+    /** The document's text as the program holds it at run time: a template's escapes are applied. */
+    text: string;
+    /**
+     * True for a literal whose type is its text (`#graphql`, `/* capa *\/`,
+     * gql(`...`)): it is sent exactly as written, and codegen keys its types by
+     * that text.
+     */
+    literal?: true;
+    /** The variable a literal is assigned to (`const CARD = ...`), which another literal's `${CARD}` names. */
+    name?: string;
+    /**
+     * For a literal with `${NAME}` in it: the text around each `${}` and the
+     * names in them, resolved against the project's other literals before the
+     * literal is read. `text` holds the template with its `${NAME}`s meanwhile.
+     */
+    template?: {
+        segments: string[];
+        names: string[];
+        asConst: boolean;
+    };
+}
+/** A template codegen does not read, and why: the CLI prints each one, so none is dropped in silence. */
+export interface SkippedDocument extends DocumentSource {
+    reason: string;
+}
+/** A template's text at run time, from its source text: line ends as LF, escapes applied. */
+export declare function cookTemplate(raw: string): string;
+/**
+ * The GraphQL documents in one file: the whole file for `.graphql` and `.gql`,
+ * and elsewhere every template that is marked as one: a `#graphql` first
+ * line, a `/* capa *\/` comment before it, or `gql` as a tag or a function.
+ * One on a comment line is an example, not a document.
+ *
+ * `skipped` names every template codegen will not read that looks meant for
+ * it, with the reason: one with `${}` inside (its text is only known at run
+ * time, so it cannot be validated or hashed ahead of it), a named operation
+ * left unmarked, and `/nextjs`'s `graphql` used as a tag.
+ */
+export declare function extractDocuments(file: string, text: string): {
+    documents: DocumentSource[];
+    skipped: SkippedDocument[];
+};
+export interface CodegenProblem {
+    file: string;
+    line: number;
+    column: number;
+    message: string;
+}
+export interface GeneratedOperation {
+    name: string;
+    /** The exact text of its `<Name>Document`, and hashed for persisted queries. */
+    document: string;
+    sha256: string;
+    /** The namespaces of the models it reads, written as `<Name>Models` for its cache tags. */
+    models: string[];
+    /** For a document written as a literal: the literal's text, which is what a call with it sends, and its hash. */
+    literal?: {
+        document: string;
+        sha256: string;
+    };
+}
+export interface GraphQLCodegenResult {
+    /** The module to write. Null when a document failed. */
+    source: string | null;
+    operations: GeneratedOperation[];
+    problems: CodegenProblem[];
+    /**
+     * Each use of a deprecated field, argument, input field or enum value, with
+     * the reason the schema gives: it still works, and a later Capa-Version
+     * removes it.
+     */
+    warnings: CodegenProblem[];
+    /** Literals with a `${}` that names no literal of the project, so their text is only known at run time. */
+    skipped: SkippedDocument[];
+}
+/**
+ * The generated module for a schema and a project's documents. Problems (a
+ * syntax error, a field the key cannot read, an unnamed operation, a name used
+ * twice) are returned with their file and line, and no module is produced
+ * while any remain.
+ */
+export declare function generateGraphQLModule(introspection: CapaIntrospection, sources: DocumentSource[]): GraphQLCodegenResult;