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

package/dist/next/errors.d.ts

@@ -0,0 +1,136 @@
+/**
+ * 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.
+ */
+export interface ApiErrorEnvelope {
+    error?: {
+        type?: unknown;
+        code?: unknown;
+        message?: unknown;
+        param?: unknown;
+        hint?: unknown;
+        docs?: unknown;
+    };
+    meta?: {
+        requestId?: unknown;
+    };
+}
+export declare class CapaError extends Error {
+    readonly status: number;
+    readonly type: string;
+    readonly code: string;
+    readonly param?: string;
+    readonly hint?: string;
+    readonly requestId: string;
+    readonly docs: string;
+    /**
+     * Every error of a refused GraphQL request, in order. The fields above come
+     * from the first one. Empty for a REST call.
+     */
+    readonly graphqlErrors: readonly CapaGraphQLError[];
+    /**
+     * 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.
+     */
+    readonly retryAfter?: number;
+    constructor(input: {
+        status: number;
+        type: string;
+        code: string;
+        message: string;
+        param?: string;
+        hint?: string;
+        requestId: string;
+        docs: string;
+        graphqlErrors?: readonly CapaGraphQLError[];
+        retryAfter?: number;
+    });
+}
+/**
+ * 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.
+ */
+export declare function retryAfterOf(value: string | null | undefined, now?: number): number | undefined;
+export declare function isCapaError(error: unknown): error is CapaError;
+export declare function optionalString(value: unknown): string | undefined;
+export declare function unparseable(status: number, requestId: string): CapaError;
+export declare function errorFromEnvelope(status: number, body: ApiErrorEnvelope, fallbackRequestId: string, retryAfter?: number): CapaError;
+/** One `errors[]` item as the API sends it. */
+export interface GraphQLErrorItem {
+    message: string;
+    locations?: Array<{
+        line: number;
+        column: number;
+    }>;
+    path?: Array<string | number>;
+    extensions?: {
+        code?: string;
+        type?: string;
+        param?: string;
+        hint?: string;
+        docs?: string;
+        requestId?: string;
+        [key: string]: unknown;
+    };
+}
+/**
+ * One GraphQL error: the spec's `{ message, locations, path, extensions }`,
+ * with the fields a caller acts on lifted out of `extensions`: `code` to
+ * branch on, `hint` for the fix, `docs` for the page that explains it,
+ * `param` for the argument at fault. `path` names the root field it belongs
+ * to.
+ *
+ * A plain object, not an `Error`: an `Error`'s `message` is not enumerable,
+ * so `JSON.stringify` drops it, and React sends an `Error` to a client
+ * component as a generic message in production. Only what the API sent is
+ * set, so a JSON round trip gives back an equal object. Check one with
+ * `isCapaGraphQLError`.
+ */
+export interface CapaGraphQLError {
+    readonly message: string;
+    readonly locations?: ReadonlyArray<{
+        line: number;
+        column: number;
+    }>;
+    readonly path?: ReadonlyArray<string | number>;
+    readonly extensions: Readonly<Record<string, unknown>>;
+    /** `extensions.code`, or `unknown` when the API sent none. */
+    readonly code: string;
+    readonly type?: string;
+    readonly param?: string;
+    readonly hint?: string;
+    readonly docs?: string;
+}
+/** Whether `value` is a `CapaGraphQLError`: by its shape, so one that went through JSON is one too. */
+export declare function isCapaGraphQLError(value: unknown): value is CapaGraphQLError;
+/** Turn a parsed `errors` value into typed errors, skipping anything that is not one. */
+export declare function graphqlErrorsOf(value: unknown): 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.
+ */
+export declare function errorFromGraphQLBody(status: number, body: unknown, fallbackRequestId: string, retryAfter?: number): CapaError;
+/** A `CapaError` for errors already read: the fields of the first, and all of them in `graphqlErrors`. */
+export declare function errorFromGraphQLErrors(status: number, errors: readonly CapaGraphQLError[], fallbackRequestId: string, retryAfter?: number): CapaError;
+/**
+ * `/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.
+ */
+export declare function graphqlNotServed(status: number, body: unknown, method: "GET" | "POST", fallbackRequestId: string): CapaError | null;

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
+ * `@capacms/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));
+}