@capacms/sdk 1.0.0-next.4 → 1.0.0-next.7

package/dist/next/errors.js

@@ -0,0 +1,214 @@
+"use strict";
+/**
+ * errors.ts — what a failed `/api/` call throws.
+ *
+ * `CapaError` is one refusal of the whole request: the REST envelope's
+ * `{ error }`, or a GraphQL response with `errors` and no `data`, whatever
+ * its status. `CapaGraphQLError` is one entry of a GraphQL `errors` array. A
+ * GraphQL request the API ran resolves with those in `errors` rather than
+ * throwing, because its `data` carries the root fields that did succeed. They
+ * are returned, not thrown, so they are plain objects: a result goes through
+ * `Response.json` or into a client component's props with every field kept.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CapaError = void 0;
+exports.retryAfterOf = retryAfterOf;
+exports.isCapaError = isCapaError;
+exports.optionalString = optionalString;
+exports.unparseable = unparseable;
+exports.errorFromEnvelope = errorFromEnvelope;
+exports.isCapaGraphQLError = isCapaGraphQLError;
+exports.graphqlErrorsOf = graphqlErrorsOf;
+exports.errorFromGraphQLBody = errorFromGraphQLBody;
+exports.errorFromGraphQLErrors = errorFromGraphQLErrors;
+exports.graphqlNotServed = graphqlNotServed;
+class CapaError extends Error {
+    status;
+    type;
+    code;
+    param;
+    hint;
+    requestId;
+    docs;
+    /**
+     * Every error of a refused GraphQL request, in order. The fields above come
+     * from the first one. Empty for a REST call.
+     */
+    graphqlErrors;
+    /**
+     * Seconds the API asked the caller to wait before trying again, from a 429's
+     * `Retry-After` (seconds or an HTTP date). Undefined when it sent none.
+     */
+    retryAfter;
+    constructor(input) {
+        super(input.message);
+        this.name = "CapaError";
+        this.status = input.status;
+        this.type = input.type;
+        this.code = input.code;
+        this.param = input.param;
+        this.hint = input.hint;
+        this.requestId = input.requestId;
+        this.docs = input.docs;
+        this.graphqlErrors = input.graphqlErrors ?? [];
+        if (input.retryAfter !== undefined)
+            this.retryAfter = input.retryAfter;
+    }
+}
+exports.CapaError = CapaError;
+/**
+ * A `Retry-After` header in seconds: delta-seconds as sent, an HTTP date as
+ * the whole seconds from `now` until it (0 once it has passed). Undefined when
+ * the header is absent or neither.
+ */
+function retryAfterOf(value, now = Date.now()) {
+    if (value === null || value === undefined)
+        return undefined;
+    const text = value.trim();
+    if (/^\d+$/.test(text))
+        return Number(text);
+    const at = Date.parse(text);
+    if (Number.isNaN(at))
+        return undefined;
+    return Math.max(0, Math.ceil((at - now) / 1000));
+}
+function isCapaError(error) {
+    return error instanceof CapaError;
+}
+function optionalString(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function unparseable(status, requestId) {
+    return new CapaError({
+        status,
+        type: "api_error",
+        code: "unparseable_response",
+        message: "Capa returned a response that was not a valid /api/ JSON envelope.",
+        requestId,
+        docs: "",
+    });
+}
+function errorFromEnvelope(status, body, fallbackRequestId, retryAfter) {
+    const detail = body.error;
+    if (!detail ||
+        typeof detail.type !== "string" ||
+        typeof detail.code !== "string" ||
+        typeof detail.message !== "string" ||
+        typeof detail.docs !== "string") {
+        return unparseable(status, fallbackRequestId);
+    }
+    return new CapaError({
+        status,
+        type: detail.type,
+        code: detail.code,
+        message: detail.message,
+        param: optionalString(detail.param),
+        hint: optionalString(detail.hint),
+        requestId: optionalString(body.meta?.requestId) ?? fallbackRequestId,
+        docs: detail.docs,
+        retryAfter,
+    });
+}
+/** The string values of `keys` in `from`, leaving out each one that is absent or not a string. */
+function stringsOf(from, keys) {
+    const out = {};
+    for (const key of keys) {
+        const value = optionalString(from[key]);
+        if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
+}
+function capaGraphQLError(item) {
+    const extensions = item.extensions && typeof item.extensions === "object" ? item.extensions : {};
+    return {
+        message: item.message,
+        ...(Array.isArray(item.locations) ? { locations: item.locations } : {}),
+        ...(Array.isArray(item.path) ? { path: item.path } : {}),
+        extensions,
+        code: optionalString(extensions.code) ?? "unknown",
+        ...stringsOf(extensions, ["type", "param", "hint", "docs"]),
+    };
+}
+/** Whether `value` is a `CapaGraphQLError`: by its shape, so one that went through JSON is one too. */
+function isCapaGraphQLError(value) {
+    if (!value || typeof value !== "object" || value instanceof Error)
+        return false;
+    const error = value;
+    return (typeof error.message === "string" &&
+        typeof error.code === "string" &&
+        !!error.extensions &&
+        typeof error.extensions === "object" &&
+        !Array.isArray(error.extensions));
+}
+/** Turn a parsed `errors` value into typed errors, skipping anything that is not one. */
+function graphqlErrorsOf(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .filter((item) => !!item && typeof item === "object" && typeof item.message === "string")
+        .map(capaGraphQLError);
+}
+/**
+ * A GraphQL request the API refused as a whole: a status other than 200, or
+ * a 200 with `errors` and no `data`, passed in as the refusal's `status`. The
+ * `CapaError` fields come from the first error, and `graphqlErrors` holds all
+ * of them. A body in the REST envelope shape, which a proxy or an older API
+ * can send, is read as one.
+ */
+function errorFromGraphQLBody(status, body, fallbackRequestId, retryAfter) {
+    const object = body && typeof body === "object" ? body : {};
+    const errors = graphqlErrorsOf(object.errors);
+    if (errors.length === 0)
+        return errorFromEnvelope(status, object, fallbackRequestId, retryAfter);
+    return errorFromGraphQLErrors(status, errors, fallbackRequestId, retryAfter);
+}
+/** A `CapaError` for errors already read: the fields of the first, and all of them in `graphqlErrors`. */
+function errorFromGraphQLErrors(status, errors, fallbackRequestId, retryAfter) {
+    const [first] = errors;
+    return new CapaError({
+        status,
+        type: first.type ?? "api_error",
+        code: first.code,
+        message: first.message,
+        param: first.param,
+        hint: first.hint,
+        requestId: optionalString(first.extensions.requestId) ?? fallbackRequestId,
+        docs: first.docs ?? "",
+        graphqlErrors: errors,
+        retryAfter,
+    });
+}
+/**
+ * `/api/graphql` answered as a path the API does not serve: a POST
+ * `405 mutations_not_enabled`, a GET `404 route_not_found`, in the REST
+ * envelope. `CAPA_API_GRAPHQL=off` does that, and so does the admin host for a
+ * GET, since it serves GraphQL by POST only. The GraphQL handler never answers
+ * in that envelope (a real mutation's refusal is `{ errors }`), so the
+ * envelope is what tells "GraphQL is not here" from "this document was
+ * refused", and a query is never told it tried to write. Null for any other
+ * answer.
+ */
+function graphqlNotServed(status, body, method, fallbackRequestId) {
+    if (status !== 404 && status !== 405)
+        return null;
+    const object = body && typeof body === "object" ? body : {};
+    if (Array.isArray(object.errors))
+        return null;
+    const refusal = errorFromEnvelope(status, object, fallbackRequestId);
+    if (refusal.code !== "mutations_not_enabled" && refusal.code !== "route_not_found")
+        return null;
+    const byGet = method === "GET";
+    return new CapaError({
+        status,
+        type: refusal.type,
+        code: refusal.code,
+        message: byGet ? "This Capa host does not serve GraphQL by GET." : "This Capa deployment does not serve GraphQL.",
+        hint: byGet
+            ? "GraphQL is switched off here (CAPA_API_GRAPHQL=off), or this is the admin host, which serves GraphQL by POST only. " +
+                'Send it by POST (method: "POST", without persisted); if that is refused too, read with client.entries.list or client.entries.get.'
+            : "GraphQL is switched off here (CAPA_API_GRAPHQL=off). Read the same content with client.entries.list or client.entries.get until it is back on.",
+        requestId: refusal.requestId,
+        docs: refusal.docs,
+    });
+}

package/dist/next/field-names.d.ts

@@ -0,0 +1,37 @@
+export declare const NAME_QUOTE = "\"";
+/** Whether REST can name a field namespace at all: every one but an empty one or one starting with `$`. */
+export declare function isNameable(namespace: string): boolean;
+/** A namespace as every REST grammar writes it: bare where it can be, quoted otherwise. */
+export declare function writeName(namespace: string): string;
+/** One segment of a sort or filter path: a system key (`$id`) keeps its sigil, a namespace is written by `writeName`. */
+export declare function writePathSegment(segment: string): string;
+/** A path (`["at.place", "zip.code"]`) as sort and where write it: `"at.place"."zip.code"`. */
+export declare function writePath(path: readonly string[]): string;
+/** The quoted name opening at `text[pos]`, and the index just past its closing quote; null when it never closes. */
+export declare function readQuoted(text: string, pos: number): {
+    name: string;
+    end: number;
+} | null;
+/** A name as written, read back: `"price.usd"` is `price.usd`, a bare name is itself. Null for a quote that does not close the name. */
+export declare function readName(text: string): string | null;
+/**
+ * `text` split on `separator` wherever it stands outside a quoted name and,
+ * unless `nested` is false, outside parentheses: a select level is split on
+ * its commas outside both, a list of names on its commas outside quotes.
+ * Null when a quote never closes.
+ */
+export declare function splitOutside(text: string, separator: string, { nested }?: {
+    nested?: boolean | undefined;
+}): string[] | null;
+/** One segment of a sort or filter path, read back, and whether it was quoted: a quoted one is always a field. */
+export interface NameSegment {
+    name: string;
+    quoted: boolean;
+}
+/**
+ * A sort or filter path's segments, split on the dots outside quotes, each
+ * read back (`"at.place"."zip.code"` is `at.place` then `zip.code`). A bare
+ * segment is everything up to the next dot, as the API reads it. Null when a
+ * quote never closes or runs into something other than a dot.
+ */
+export declare function readPath(text: string): NameSegment[] | null;

package/dist/next/field-names.js

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NAME_QUOTE = void 0;
+exports.isNameable = isNameable;
+exports.writeName = writeName;
+exports.writePathSegment = writePathSegment;
+exports.writePath = writePath;
+exports.readQuoted = readQuoted;
+exports.readName = readName;
+exports.splitOutside = splitOutside;
+exports.readPath = readPath;
+/**
+ * field-names.ts — how REST's `select`, `sort` and `where` write a field
+ * namespace, and how they read one back (spec 17, amendment 121).
+ *
+ * A namespace is whatever the admin saved, so any character can be in one:
+ * `am/pm_indicator`, `price.usd`, `a,b`. All three grammars write it the same
+ * way:
+ * - BARE when none of its characters means something in any of them and it
+ *   starts with neither `$` (a system key) nor `-` (a descending sort):
+ *   `title`, `open-time`, `am/pm_indicator`.
+ * - QUOTED otherwise, a quote inside doubled: `"price.usd"`, `"a,b"`,
+ *   `"say ""hi"""`. A quoted name is always a field, never a system key, a
+ *   relation hop or a modifier.
+ *
+ * A namespace that starts with `$` cannot be named at all, since `$tags` is
+ * the system key; `select=*` still returns it.
+ *
+ * The API's own writer is `writeName` in `@capa/shared`. This package ships
+ * with no runtime dependencies, so the rule is copied here and in
+ * `@capa/mcp`, and test/fixtures/field-names.json pins all three to the same
+ * vectors.
+ */
+const system_keys_1 = require("./system-keys");
+exports.NAME_QUOTE = '"';
+/** Characters that mean something in `select`, `sort` or a filter path. */
+const MEANINGFUL = new Set([",", "(", ")", ":", ".", exports.NAME_QUOTE, "*", "[", "]"]);
+/** Whether a character can stand in a bare name. */
+function isNameChar(ch) {
+    return !MEANINGFUL.has(ch) && !/\s/.test(ch);
+}
+/** Whether REST can name a field namespace at all: every one but an empty one or one starting with `$`. */
+function isNameable(namespace) {
+    return namespace !== "" && !namespace.startsWith(system_keys_1.SYSTEM_KEY_SIGIL);
+}
+/** A namespace as every REST grammar writes it: bare where it can be, quoted otherwise. */
+function writeName(namespace) {
+    const bare = isNameable(namespace) && !namespace.startsWith("-") && [...namespace].every(isNameChar);
+    if (bare)
+        return namespace;
+    return `${exports.NAME_QUOTE}${namespace.split(exports.NAME_QUOTE).join(exports.NAME_QUOTE + exports.NAME_QUOTE)}${exports.NAME_QUOTE}`;
+}
+/** One segment of a sort or filter path: a system key (`$id`) keeps its sigil, a namespace is written by `writeName`. */
+function writePathSegment(segment) {
+    return segment.startsWith(system_keys_1.SYSTEM_KEY_SIGIL) ? segment : writeName(segment);
+}
+/** A path (`["at.place", "zip.code"]`) as sort and where write it: `"at.place"."zip.code"`. */
+function writePath(path) {
+    return path.map(writePathSegment).join(".");
+}
+/** The quoted name opening at `text[pos]`, and the index just past its closing quote; null when it never closes. */
+function readQuoted(text, pos) {
+    let name = "";
+    let i = pos + 1;
+    while (i < text.length) {
+        if (text[i] === exports.NAME_QUOTE) {
+            if (text[i + 1] !== exports.NAME_QUOTE)
+                return { name, end: i + 1 };
+            name += exports.NAME_QUOTE;
+            i += 2;
+            continue;
+        }
+        name += text[i];
+        i += 1;
+    }
+    return null;
+}
+/** A name as written, read back: `"price.usd"` is `price.usd`, a bare name is itself. Null for a quote that does not close the name. */
+function readName(text) {
+    if (!text.startsWith(exports.NAME_QUOTE))
+        return text;
+    const quoted = readQuoted(text, 0);
+    return quoted && quoted.end === text.length ? quoted.name : null;
+}
+/**
+ * `text` split on `separator` wherever it stands outside a quoted name and,
+ * unless `nested` is false, outside parentheses: a select level is split on
+ * its commas outside both, a list of names on its commas outside quotes.
+ * Null when a quote never closes.
+ */
+function splitOutside(text, separator, { nested = true } = {}) {
+    const parts = [];
+    let depth = 0;
+    let start = 0;
+    let i = 0;
+    while (i < text.length) {
+        const ch = text[i];
+        if (ch === exports.NAME_QUOTE) {
+            const quoted = readQuoted(text, i);
+            if (!quoted)
+                return null;
+            i = quoted.end;
+            continue;
+        }
+        if (nested && ch === "(")
+            depth += 1;
+        else if (nested && ch === ")")
+            depth -= 1;
+        else if (ch === separator && depth === 0) {
+            parts.push(text.slice(start, i));
+            start = i + 1;
+        }
+        i += 1;
+    }
+    parts.push(text.slice(start));
+    return parts;
+}
+/**
+ * A sort or filter path's segments, split on the dots outside quotes, each
+ * read back (`"at.place"."zip.code"` is `at.place` then `zip.code`). A bare
+ * segment is everything up to the next dot, as the API reads it. Null when a
+ * quote never closes or runs into something other than a dot.
+ */
+function readPath(text) {
+    const segments = [];
+    let i = 0;
+    for (;;) {
+        if (text[i] === exports.NAME_QUOTE) {
+            const quoted = readQuoted(text, i);
+            if (!quoted || (quoted.end < text.length && text[quoted.end] !== "."))
+                return null;
+            segments.push({ name: quoted.name, quoted: true });
+            i = quoted.end;
+        }
+        else {
+            const dot = text.indexOf(".", i);
+            const end = dot === -1 ? text.length : dot;
+            segments.push({ name: text.slice(i, end), quoted: false });
+            i = end;
+        }
+        if (i >= text.length)
+            return segments;
+        i += 1;
+    }
+}

package/dist/next/graphql/build.d.ts

@@ -0,0 +1,27 @@
+/**
+ * build.ts — a query spec as GraphQL text, in the one format every Capa
+ * builder emits (G plan 1.3): two-space indent, `id` first in every entry,
+ * variables only for the arguments given, and inline literal arguments on a
+ * nested array relation, its cursor included. The Explorer, the MCP server and this SDK are pinned
+ * to the same output by `test/fixtures/graphql-vectors.json`.
+ */
+import { type GraphQLQuerySpec, type PlannedQuery } from "./plan";
+import type { GraphQLSchemaSummary } from "./summary";
+export interface BuiltGraphQLQuery {
+    query: string;
+    variables: Record<string, unknown>;
+    operationName: string;
+}
+/** Print a checked plan. */
+export declare function printGraphQL(plan: PlannedQuery): BuiltGraphQLQuery;
+/**
+ * Build a GraphQL query from a spec, checked against the key's schema.
+ *
+ *   const schema = await capa.graphqlSchema();
+ *   const { query, variables } = buildGraphQLQuery(schema, { model: "articles", fields: ["title"], first: 5 });
+ *   const { data } = await capa.graphql(query, variables);
+ *
+ * Throws `CapaBuildError`, with `didYouMean`, for a model, field or sort value
+ * the key's schema does not have.
+ */
+export declare function buildGraphQLQuery(summary: GraphQLSchemaSummary, spec: GraphQLQuerySpec): BuiltGraphQLQuery;

package/dist/next/graphql/build.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.printGraphQL = printGraphQL;
+exports.buildGraphQLQuery = buildGraphQLQuery;
+/**
+ * build.ts — a query spec as GraphQL text, in the one format every Capa
+ * builder emits (G plan 1.3): two-space indent, `id` first in every entry,
+ * variables only for the arguments given, and inline literal arguments on a
+ * nested array relation, its cursor included. The Explorer, the MCP server and this SDK are pinned
+ * to the same output by `test/fixtures/graphql-vectors.json`.
+ */
+const plan_1 = require("./plan");
+const INDENT = "  ";
+function printFields(fields, depth) {
+    const pad = INDENT.repeat(depth);
+    const lines = [];
+    for (const field of fields) {
+        if (!field.children) {
+            lines.push(`${pad}${field.name}`);
+        }
+        else if (field.field?.kind === "relationList") {
+            const args = [];
+            if (field.first !== undefined)
+                args.push(`first: ${field.first}`);
+            if (field.sort !== undefined)
+                args.push(`sort: ${field.sort}`);
+            if (field.after !== undefined)
+                args.push(`after: ${JSON.stringify(field.after)}`);
+            lines.push(`${pad}${field.name}${args.length ? `(${args.join(", ")})` : ""} {`);
+            lines.push(`${pad}${INDENT}nodes {`);
+            lines.push(...printFields(field.children, depth + 2));
+            lines.push(`${pad}${INDENT}}`);
+            lines.push(`${pad}}`);
+        }
+        else {
+            lines.push(`${pad}${field.name} {`);
+            lines.push(...printFields(field.children, depth + 1));
+            lines.push(`${pad}}`);
+        }
+    }
+    return lines;
+}
+/** Print a checked plan. */
+function printGraphQL(plan) {
+    const { model } = plan;
+    const variables = {};
+    const declared = [];
+    const passed = [];
+    const argument = (name, type, value) => {
+        if (value === undefined)
+            return;
+        variables[name] = value;
+        declared.push(`$${name}: ${type}`);
+        passed.push(`${name}: $${name}`);
+    };
+    argument("id", "ID!", plan.id);
+    // REST's limit beside before is GraphQL's last beside before, the entries
+    // just before the cursor; the API refuses first there (spec 17, amendment 55).
+    // REST's before=end is last with no before, the end of the list (amendment 132).
+    const fromEnd = plan.before === plan_1.END_OF_LIST;
+    argument(plan.before === undefined ? "first" : "last", "Int", fromEnd ? plan.first ?? plan_1.LIST_DEFAULT : plan.first);
+    argument("after", "String", plan.after);
+    if (!fromEnd)
+        argument("before", "String", plan.before);
+    argument("sort", `[${model.sortType}!]`, plan.sort);
+    argument("filter", model.filterType, plan.filter);
+    const root = plan.mode === "single" ? model.singleField : model.listField;
+    const lines = [`query ${plan.operationName}${declared.length ? `(${declared.join(", ")})` : ""} {`];
+    lines.push(`${INDENT}${root}${passed.length ? `(${passed.join(", ")})` : ""} {`);
+    if (plan.mode === "single") {
+        lines.push(...printFields(plan.fields, 2));
+    }
+    else {
+        lines.push(`${INDENT.repeat(2)}nodes {`);
+        lines.push(...printFields(plan.fields, 3));
+        lines.push(`${INDENT.repeat(2)}}`);
+        // A page read backward pages on back from its startCursor, as REST's page.prev.
+        const back = plan.before === undefined ? [] : [`${INDENT.repeat(3)}hasPreviousPage`, `${INDENT.repeat(3)}startCursor`];
+        lines.push(`${INDENT.repeat(2)}pageInfo {`, `${INDENT.repeat(3)}hasNextPage`, `${INDENT.repeat(3)}endCursor`, ...back, `${INDENT.repeat(2)}}`);
+        if (plan.totalCount)
+            lines.push(`${INDENT.repeat(2)}totalCount`);
+    }
+    lines.push(`${INDENT}}`, "}");
+    return { query: lines.join("\n"), variables, operationName: plan.operationName };
+}
+/**
+ * Build a GraphQL query from a spec, checked against the key's schema.
+ *
+ *   const schema = await capa.graphqlSchema();
+ *   const { query, variables } = buildGraphQLQuery(schema, { model: "articles", fields: ["title"], first: 5 });
+ *   const { data } = await capa.graphql(query, variables);
+ *
+ * Throws `CapaBuildError`, with `didYouMean`, for a model, field or sort value
+ * the key's schema does not have.
+ */
+function buildGraphQLQuery(summary, spec) {
+    return printGraphQL((0, plan_1.planQuery)(summary, spec));
+}

package/dist/next/graphql/documents.d.ts

@@ -0,0 +1,67 @@
+/**
+ * documents.ts — GraphQL documents written as literals, typed by their text.
+ *
+ * A document written in a project as a literal keeps its exact text as its
+ * type, in any of three forms:
+ *
+ *   const LATEST = `#graphql
+ *     query Latest($first: Int) { articles(first: $first) { nodes { title } } }
+ *   `;
+ *   const ONE = /* capa *\/ `query One($id: ID!) { article(id: $id) { title } }`;
+ *   const VERSION = gql(`query Version { version }`);
+ *
+ * `capa-codegen --graphql` finds each one, checks it against the key's schema,
+ * and adds an entry to `CapaDocuments` keyed by that text, holding its result
+ * and variables types. `client.graphql(LATEST)` and `graphql(LATEST)` from
+ * `/nextjs` look the text up, so `data` and `variables` are typed with no cast
+ * and no import from the generated file, the way Hydrogen types
+ * `storefront.query`.
+ *
+ * `gql` used as a tag (gql`query ...`) returns a plain string: TypeScript
+ * gives a tagged template no literal type. Codegen still checks it and exports
+ * a typed `<Name>Document` for it.
+ */
+/**
+ * The documents written as literals in your project, by their exact text.
+ * Empty here: the module `capa-codegen --graphql` writes adds to it with
+ * `declare module "@capacms/sdk/next"`, so keep that file inside your
+ * tsconfig's `include`.
+ */
+export interface CapaDocuments {
+}
+/** The result type codegen recorded for a literal document. */
+export type CapaDocumentResult<D> = D extends keyof CapaDocuments ? CapaDocuments[D] extends {
+    result: infer R;
+} ? R : never : never;
+/** The variables type codegen recorded for a literal document. */
+export type CapaDocumentVariables<D> = D extends keyof CapaDocuments ? CapaDocuments[D] extends {
+    variables: infer V;
+} ? V : never : never;
+/**
+ * What a call with a `#graphql` literal that `capa-codegen --graphql` has not
+ * seen takes instead of the literal, so the call fails to compile with the
+ * fix in the message rather than going untyped.
+ */
+export type RunCapaCodegen = "This #graphql document is not in CapaDocuments yet: run capa-codegen --graphql (or keep capa-codegen --graphql --watch running) to type its data and variables.";
+/**
+ * `T`, unless `D` is a document codegen recorded, or a `#graphql` literal it
+ * has not. A recorded document is typed by its record, so the untyped
+ * signature refuses it: otherwise wrong variables would compile through it. A
+ * `#graphql` literal codegen has not seen (new, or edited since the last run)
+ * is `RunCapaCodegen`, so it does not compile until codegen has read it.
+ * Text built at run time is a plain `string` and stays untyped, and so does a
+ * call that names its data type, `capa.graphql<Data>(text)`.
+ */
+export type NotARecordedDocument<D, T> = D extends keyof CapaDocuments ? never : string extends D ? T : D extends `${string}#graphql${string}` ? RunCapaCodegen : T;
+/**
+ * A GraphQL document, returned as written.
+ *
+ * Called with a literal, gql(`query ...`), it returns the literal with its
+ * exact text as its type, which is what `client.graphql` looks up once
+ * `capa-codegen --graphql` has seen it. Used as a tag, gql`query ...`, it
+ * returns a plain string; import the `<Name>Document` codegen writes for its
+ * types. Values interpolated into a tag are joined in as text, and codegen
+ * skips such a document, since its text is only known at run time.
+ */
+export declare function gql<T extends string>(document: T): T;
+export declare function gql(strings: TemplateStringsArray, ...values: ReadonlyArray<string | number>): string;

package/dist/next/graphql/documents.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * documents.ts — GraphQL documents written as literals, typed by their text.
+ *
+ * A document written in a project as a literal keeps its exact text as its
+ * type, in any of three forms:
+ *
+ *   const LATEST = `#graphql
+ *     query Latest($first: Int) { articles(first: $first) { nodes { title } } }
+ *   `;
+ *   const ONE = /* capa *\/ `query One($id: ID!) { article(id: $id) { title } }`;
+ *   const VERSION = gql(`query Version { version }`);
+ *
+ * `capa-codegen --graphql` finds each one, checks it against the key's schema,
+ * and adds an entry to `CapaDocuments` keyed by that text, holding its result
+ * and variables types. `client.graphql(LATEST)` and `graphql(LATEST)` from
+ * `/nextjs` look the text up, so `data` and `variables` are typed with no cast
+ * and no import from the generated file, the way Hydrogen types
+ * `storefront.query`.
+ *
+ * `gql` used as a tag (gql`query ...`) returns a plain string: TypeScript
+ * gives a tagged template no literal type. Codegen still checks it and exports
+ * a typed `<Name>Document` for it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gql = gql;
+function gql(document, ...values) {
+    if (typeof document === "string")
+        return document;
+    let text = document[0];
+    values.forEach((value, i) => {
+        text += String(value) + document[i + 1];
+    });
+    return text;
+}

package/dist/next/graphql/edit-mode.d.ts

@@ -0,0 +1,16 @@
+import type { CapaFieldNames } from "./introspection";
+/** How long a key's renamed fields are kept before the names are read again. */
+export declare const RENAMED_TTL_MS = 60000;
+/** Per model namespace, its fields whose GraphQL name is not their namespace, by GraphQL name. */
+export type RenamedFields = ReadonlyMap<string, Readonly<Record<string, string>>>;
+/** The fields of each model that N5 renamed, from the N9 descriptions. Models with none are left out. */
+export declare function renamedFields(names: CapaFieldNames): RenamedFields;
+/**
+ * Run `read` in edit mode: the key's renamed fields are read beside it (or
+ * come from the cache), and its result's entries are marked once both are in.
+ */
+export declare function readMarked<R extends {
+    data: unknown;
+}>(document: string, key: string, readNames: () => Promise<CapaFieldNames>, read: () => Promise<R>): Promise<R>;
+/** Forget every key's renamed fields. For tests. */
+export declare function __resetEditSchemaForTests(): void;