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

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;

package/dist/next/graphql/edit-mode.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RENAMED_TTL_MS = void 0;
+exports.renamedFields = renamedFields;
+exports.readMarked = readMarked;
+exports.__resetEditSchemaForTests = __resetEditSchemaForTests;
+/**
+ * edit-mode.ts — a GraphQL read in edit mode, marked for live preview.
+ *
+ * A client created with `editMode: true` marks what it reads, so `capaAttrs`
+ * tags it for the Capa editor (attrs.ts). In a GraphQL result an entry is an
+ * object that selected `id` and `model`. A field GraphQL renamed (N5:
+ * `hero_image` for `hero-image`, `status_field` for `status`) must still be
+ * tagged by its namespace, since the editor knows fields by namespace, and
+ * only the schema's descriptions say which fields those are.
+ *
+ * So a marked read also reads the key's type and field names
+ * (`FIELD_NAMES_QUERY`), kept for a minute per host, key and version, the
+ * same lifetime as the MCP server's copy. That read starts beside the data
+ * read, so the result waits for the slower of the two rather than for both
+ * in turn. A document that never says `model` cannot select it, so its
+ * result holds no entry and it reads no names. The data request itself is
+ * the same with or without edit mode.
+ */
+const attrs_1 = require("../attrs");
+const summary_1 = require("./summary");
+/** How long a key's renamed fields are kept before the names are read again. */
+exports.RENAMED_TTL_MS = 60_000;
+const RENAMED_LIMIT = 100;
+const renamedCache = new Map();
+/** The fields of each model that N5 renamed, from the N9 descriptions. Models with none are left out. */
+function renamedFields(names) {
+    const out = new Map();
+    for (const type of names.__schema.types) {
+        const namespace = type.kind === "OBJECT" ? (0, summary_1.modelNamespaceOf)(type.description) : null;
+        if (!namespace)
+            continue;
+        const renamed = {};
+        for (const field of type.fields ?? []) {
+            const parsed = (0, summary_1.parseFieldDescription)(field.description);
+            if (parsed && parsed.namespace !== field.name)
+                renamed[field.name] = parsed.namespace;
+        }
+        if (Object.keys(renamed).length)
+            out.set(namespace, renamed);
+    }
+    return out;
+}
+/**
+ * The renamed fields for `key` (host, key and version), from the cache or by
+ * `readNames`. A failed read is not kept, and gives none: a preview that
+ * cannot read the names still marks its entries, tagging each field by the
+ * name it was selected with, and never fails the page.
+ */
+function renamedFor(key, readNames, now) {
+    const cached = renamedCache.get(key);
+    if (cached && cached.until > now)
+        return cached.renamed;
+    if (renamedCache.size >= RENAMED_LIMIT)
+        renamedCache.clear();
+    const entry = { until: now + exports.RENAMED_TTL_MS, renamed: Promise.resolve(new Map()) };
+    entry.renamed = readNames().then(renamedFields, () => {
+        if (renamedCache.get(key) === entry)
+            renamedCache.delete(key);
+        return new Map();
+    });
+    renamedCache.set(key, entry);
+    return entry.renamed;
+}
+/** Whether a result of `document` can hold an entry: an entry selected `model`, so the document says `model`. */
+function canSelectModel(document) {
+    return /\bmodel\b/.test(document);
+}
+/**
+ * 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.
+ */
+async function readMarked(document, key, readNames, read) {
+    const result = read();
+    if (!canSelectModel(document))
+        return result;
+    const renamed = renamedFor(key, readNames, Date.now());
+    const { data } = await result;
+    if ((0, attrs_1.hasGraphQLEntry)(data)) {
+        const byModel = await renamed;
+        (0, attrs_1.markGraphQLEntries)(data, (model) => byModel.get(model));
+    }
+    return result;
+}
+/** Forget every key's renamed fields. For tests. */
+function __resetEditSchemaForTests() {
+    renamedCache.clear();
+}

package/dist/next/graphql/filter-values.d.ts

@@ -0,0 +1,34 @@
+/**
+ * filter-values.ts — filter values as the scalar types the schema declares.
+ *
+ * GraphQL refuses a variable of the wrong type outright, while REST reads
+ * loosely: a query string carries everything as text, and a list of
+ * true/false values takes `true` or `"true"` alike (spec 17, amendment 30).
+ * GraphQL types a list's filter by its items (`BooleanListFilter`, amendment
+ * 59), so `has: "true"` sent as GraphQL is refused. Every filter a builder
+ * sends is therefore converted to the operand types its filter input declares,
+ * whichever side it was written on: `has: "true"` on a `[Boolean]` field goes
+ * as `true`, `gte: "10"` on a number as `10`. A value that cannot be converted
+ * is left as written, so the API refuses it with its own message.
+ */
+import type { GraphQLModelSummary, GraphQLSchemaSummary } from "./summary";
+/** The operand types of a system filter (`IDFilter`, `DateTimeFilter`). */
+export declare const SYSTEM_OPERANDS: Readonly<Record<string, string>>;
+/** A JSON object: a filter, or one field's operators. */
+export declare function isObject(value: unknown): value is Record<string, unknown>;
+/** One operand as the GraphQL scalar `type`, when it reads as one. */
+export declare function toScalar(type: string | undefined, value: unknown): unknown;
+/**
+ * An operator object with each operand as the type `operands` gives its
+ * operator. `listText` also reads a list operand written as comma-separated
+ * text (`in: "1,2"`), as a REST query string carries it.
+ */
+export declare function typedOperations(operations: Record<string, unknown>, operands: Readonly<Record<string, string>>, { listText }?: {
+    listText?: boolean;
+}): Record<string, unknown>;
+/**
+ * A `<Type>Filter` value with every operand converted to the type the schema
+ * declares for it: through `and`, `or` and `not`, on system keys and on every
+ * field, and one hop into a relation's target. Keys keep the order written.
+ */
+export declare function typedFilter(summary: GraphQLSchemaSummary, model: GraphQLModelSummary, filter: Record<string, unknown>): Record<string, unknown>;

package/dist/next/graphql/filter-values.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SYSTEM_OPERANDS = void 0;
+exports.isObject = isObject;
+exports.toScalar = toScalar;
+exports.typedOperations = typedOperations;
+exports.typedFilter = typedFilter;
+/** Operators whose operand is a list. */
+const LIST_OPERATORS = new Set(["in", "nin", "hasAny", "hasAll"]);
+/** The operand types of a system filter (`IDFilter`, `DateTimeFilter`). */
+exports.SYSTEM_OPERANDS = {
+    eq: "String", ne: "String", lt: "String", lte: "String", gt: "String", gte: "String",
+    in: "String", nin: "String", exists: "Boolean", null: "Boolean",
+};
+/** Filter keys that combine filters rather than name a field. */
+const LOGIC_KEYS = new Set(["and", "or", "not"]);
+/** A JSON object: a filter, or one field's operators. */
+function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** One operand as the GraphQL scalar `type`, when it reads as one. */
+function toScalar(type, value) {
+    switch (type) {
+        case "Float":
+        case "Int":
+            return typeof value === "string" && value.trim() !== "" && Number.isFinite(Number(value)) ? Number(value) : value;
+        case "Boolean":
+            return value === "true" ? true : value === "false" ? false : value;
+        case "String":
+        case "ID":
+        case "DateTime":
+            return typeof value === "number" || typeof value === "boolean" ? String(value) : value;
+        default:
+            return value;
+    }
+}
+/** One operand of `operator` as `type`; a list operand item by item. */
+function typedOperand(operator, value, type, listText) {
+    if (value === null || value === undefined || !LIST_OPERATORS.has(operator))
+        return toScalar(type, value);
+    const items = Array.isArray(value) ? value : listText && typeof value === "string" ? value.split(",") : [value];
+    return items.map((item) => toScalar(type, item));
+}
+/**
+ * An operator object with each operand as the type `operands` gives its
+ * operator. `listText` also reads a list operand written as comma-separated
+ * text (`in: "1,2"`), as a REST query string carries it.
+ */
+function typedOperations(operations, operands, { listText = false } = {}) {
+    return Object.fromEntries(Object.entries(operations).map(([operator, value]) => [operator, typedOperand(operator, value, operands[operator], listText)]));
+}
+function targetOf(summary, namespace) {
+    return namespace === null ? undefined : summary.models.find((m) => m.namespace === namespace);
+}
+/** A relation's own operators typed, and each hop into its target typed by the target field's operands. */
+function typedRelation(operands, target, operations) {
+    const out = {};
+    for (const [name, value] of Object.entries(operations)) {
+        const hop = target?.fields.find((f) => f.name === name);
+        out[name] =
+            isObject(value) && (hop || name === "id")
+                ? typedOperations(value, hop ? hop.filterInputs ?? {} : exports.SYSTEM_OPERANDS)
+                : typedOperand(name, value, operands[name], false);
+    }
+    return out;
+}
+/**
+ * A `<Type>Filter` value with every operand converted to the type the schema
+ * declares for it: through `and`, `or` and `not`, on system keys and on every
+ * field, and one hop into a relation's target. Keys keep the order written.
+ */
+function typedFilter(summary, model, filter) {
+    const out = {};
+    for (const [key, value] of Object.entries(filter)) {
+        if (LOGIC_KEYS.has(key)) {
+            const typed = (part) => (isObject(part) ? typedFilter(summary, model, part) : part);
+            out[key] = Array.isArray(value) ? value.map(typed) : typed(value);
+            continue;
+        }
+        if (!isObject(value)) {
+            out[key] = value;
+            continue;
+        }
+        const field = model.fields.find((f) => f.name === key);
+        if (!field) {
+            out[key] = typedOperations(value, model.systemFilters.find((system) => system.name === key)?.filterInputs ?? exports.SYSTEM_OPERANDS);
+        }
+        else if (field.kind === "relation" || field.kind === "relationList") {
+            out[key] = typedRelation(field.filterInputs ?? {}, targetOf(summary, field.target), value);
+        }
+        else {
+            out[key] = typedOperations(value, field.filterInputs ?? {});
+        }
+    }
+    return out;
+}

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

@@ -0,0 +1,89 @@
+/**
+ * introspection.ts — the introspection query this package sends, and the part
+ * of the answer it reads.
+ *
+ * One request carries both the standard introspection selection and the
+ * `version` root field, so a schema summary always says which platform version
+ * it describes. Kept byte-stable: `@capacms/mcp` sends the same text, and a
+ * persisted copy of it is one hash for every client.
+ *
+ * Deprecated arguments and input fields are asked for too, with their
+ * reasons: graphql-js leaves them out otherwise, and a document using one
+ * would then fail codegen as unknown the day Capa deprecates it, long before
+ * a later Capa-Version removes it.
+ */
+export declare const INTROSPECTION_QUERY = "query CapaIntrospection {\n  version\n  __schema {\n    queryType { name }\n    types { ...FullType }\n  }\n}\n\nfragment FullType on __Type {\n  kind\n  name\n  description\n  fields(includeDeprecated: true) {\n    name\n    description\n    args(includeDeprecated: true) { ...InputValue }\n    type { ...TypeRef }\n    isDeprecated\n    deprecationReason\n  }\n  inputFields(includeDeprecated: true) { ...InputValue }\n  interfaces { ...TypeRef }\n  enumValues(includeDeprecated: true) { name description isDeprecated deprecationReason }\n  possibleTypes { ...TypeRef }\n}\n\nfragment InputValue on __InputValue {\n  name\n  description\n  type { ...TypeRef }\n  defaultValue\n  isDeprecated\n  deprecationReason\n}\n\nfragment TypeRef on __Type {\n  kind\n  name\n  ofType { kind name ofType { kind name ofType { kind name ofType { kind name } } } }\n}";
+/**
+ * The part of the schema edit mode reads (`edit-mode.ts`): each type's name
+ * and description, and each field's name and description, which is all that
+ * says which GraphQL name is which Capa namespace (N9), and none of the
+ * arguments, input types and enum values that make up most of
+ * `INTROSPECTION_QUERY`'s answer. It selects the schema and nothing else, so
+ * the API answers a repeat from its memo of that answer.
+ */
+export declare const FIELD_NAMES_QUERY = "query CapaFieldNames {\n  __schema {\n    types {\n      kind\n      name\n      description\n      fields(includeDeprecated: true) { name description }\n    }\n  }\n}";
+/** `data` of a `CapaFieldNames` response. */
+export interface CapaFieldNames {
+    __schema: {
+        types: Array<{
+            kind: string;
+            name: string;
+            description?: string | null;
+            fields?: Array<{
+                name: string;
+                description?: string | null;
+            }> | null;
+        }>;
+    };
+}
+export interface IntrospectionTypeRef {
+    kind: string;
+    name: string | null;
+    ofType?: IntrospectionTypeRef | null;
+}
+export interface IntrospectionInputValue {
+    name: string;
+    description?: string | null;
+    type: IntrospectionTypeRef;
+    defaultValue?: string | null;
+    isDeprecated?: boolean;
+    deprecationReason?: string | null;
+}
+export interface IntrospectionField {
+    name: string;
+    description?: string | null;
+    args: IntrospectionInputValue[];
+    type: IntrospectionTypeRef;
+    isDeprecated?: boolean;
+    deprecationReason?: string | null;
+}
+export interface IntrospectionType {
+    kind: string;
+    name: string;
+    description?: string | null;
+    fields?: IntrospectionField[] | null;
+    inputFields?: IntrospectionInputValue[] | null;
+    enumValues?: Array<{
+        name: string;
+        description?: string | null;
+        isDeprecated?: boolean;
+        deprecationReason?: string | null;
+    }> | null;
+    interfaces?: IntrospectionTypeRef[] | null;
+    possibleTypes?: IntrospectionTypeRef[] | null;
+}
+/** `data` of a `CapaIntrospection` response. */
+export interface CapaIntrospection {
+    version?: string;
+    __schema: {
+        queryType: {
+            name: string;
+        };
+        types: IntrospectionType[];
+    };
+}
+/** The named type under any `NON_NULL` and `LIST` wrappers. */
+export declare function namedType(ref: IntrospectionTypeRef): string;
+/** The type as SDL writes it: `[Authors!]!`. */
+export declare function printTypeRef(ref: IntrospectionTypeRef): string;
+export declare function isListType(ref: IntrospectionTypeRef): boolean;

package/dist/next/graphql/introspection.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * introspection.ts — the introspection query this package sends, and the part
+ * of the answer it reads.
+ *
+ * One request carries both the standard introspection selection and the
+ * `version` root field, so a schema summary always says which platform version
+ * it describes. Kept byte-stable: `@capacms/mcp` sends the same text, and a
+ * persisted copy of it is one hash for every client.
+ *
+ * Deprecated arguments and input fields are asked for too, with their
+ * reasons: graphql-js leaves them out otherwise, and a document using one
+ * would then fail codegen as unknown the day Capa deprecates it, long before
+ * a later Capa-Version removes it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FIELD_NAMES_QUERY = exports.INTROSPECTION_QUERY = void 0;
+exports.namedType = namedType;
+exports.printTypeRef = printTypeRef;
+exports.isListType = isListType;
+exports.INTROSPECTION_QUERY = `query CapaIntrospection {
+  version
+  __schema {
+    queryType { name }
+    types { ...FullType }
+  }
+}
+
+fragment FullType on __Type {
+  kind
+  name
+  description
+  fields(includeDeprecated: true) {
+    name
+    description
+    args(includeDeprecated: true) { ...InputValue }
+    type { ...TypeRef }
+    isDeprecated
+    deprecationReason
+  }
+  inputFields(includeDeprecated: true) { ...InputValue }
+  interfaces { ...TypeRef }
+  enumValues(includeDeprecated: true) { name description isDeprecated deprecationReason }
+  possibleTypes { ...TypeRef }
+}
+
+fragment InputValue on __InputValue {
+  name
+  description
+  type { ...TypeRef }
+  defaultValue
+  isDeprecated
+  deprecationReason
+}
+
+fragment TypeRef on __Type {
+  kind
+  name
+  ofType { kind name ofType { kind name ofType { kind name ofType { kind name } } } }
+}`;
+/**
+ * The part of the schema edit mode reads (`edit-mode.ts`): each type's name
+ * and description, and each field's name and description, which is all that
+ * says which GraphQL name is which Capa namespace (N9), and none of the
+ * arguments, input types and enum values that make up most of
+ * `INTROSPECTION_QUERY`'s answer. It selects the schema and nothing else, so
+ * the API answers a repeat from its memo of that answer.
+ */
+exports.FIELD_NAMES_QUERY = `query CapaFieldNames {
+  __schema {
+    types {
+      kind
+      name
+      description
+      fields(includeDeprecated: true) { name description }
+    }
+  }
+}`;
+/** The named type under any `NON_NULL` and `LIST` wrappers. */
+function namedType(ref) {
+    let current = ref;
+    while (current && current.name === null)
+        current = current.ofType;
+    return current?.name ?? "";
+}
+/** The type as SDL writes it: `[Authors!]!`. */
+function printTypeRef(ref) {
+    if (ref.kind === "NON_NULL" && ref.ofType)
+        return `${printTypeRef(ref.ofType)}!`;
+    if (ref.kind === "LIST" && ref.ofType)
+        return `[${printTypeRef(ref.ofType)}]`;
+    return ref.name ?? "";
+}
+function isListType(ref) {
+    let current = ref;
+    while (current) {
+        if (current.kind === "LIST")
+            return true;
+        current = current.ofType;
+    }
+    return false;
+}

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

@@ -0,0 +1,115 @@
+import { type GraphQLFieldSummary, type GraphQLModelSummary, type GraphQLSchemaSummary } from "./summary";
+/** One selected field: a name, or a relation or media field with its own fields. */
+/**
+ * A relation list's sort: one value of the target's sort enum, e.g.
+ * `name_ASC`, or a list of that one value, the root's shape.
+ */
+export type GraphQLFieldSpecSort = string | readonly [string];
+export type GraphQLFieldSpec = string | {
+    field: string;
+    fields?: GraphQLFieldSpec[];
+    /** Array relations only: how many related entries, 1 to 200 (default 100). */
+    first?: number;
+    /** Array relations only: see `GraphQLFieldSpecSort`. */
+    sort?: GraphQLFieldSpecSort;
+    /**
+     * Array relations in a read of one entry only: the list's `endCursor`,
+     * to read on after it. A cursor names one entry's list, so a list read
+     * refuses it, as the API does.
+     */
+    after?: string;
+};
+export interface GraphQLQuerySpec {
+    /** Namespace (`articles`) or GraphQL type name (`Articles`). */
+    model: string;
+    /** `list`, or `single`, which needs `id`. The default is `single` when `id` is given, else `list`. */
+    mode?: "list" | "single";
+    /** The entry's UUID: reads that one entry. Refused beside `mode: "list"`. */
+    id?: string;
+    /** Omit for every non-relation field, single relations as `{ id }`, media as `{ id url alt }`. */
+    fields?: GraphQLFieldSpec[];
+    /**
+     * How many entries, 1 to 200 (default 25), as REST's `limit`. Beside
+     * `before` they are the entries just before that cursor, which GraphQL
+     * writes as `last`, so the query sends `last`.
+     */
+    first?: number;
+    /** An `endCursor`: the page after it. */
+    after?: string;
+    /**
+     * A `startCursor` to page back from: the `first` entries just before it.
+     * Or `"end"`, REST's `before=end`: the last `first` entries of the list,
+     * which GraphQL reads as `last` with no `before` (spec 17, amendment 132).
+     */
+    before?: string;
+    /** Up to 3 values of the model's sort enum, e.g. `["views_DESC"]`, or one alone, `"views_DESC"`. */
+    sort?: string | readonly string[];
+    /**
+     * The model's filter input, e.g. `{ views: { gte: 10 } }`. Each value is sent
+     * as the type the input declares: `{ views: { gte: "10" } }` goes as `10`,
+     * and `{ a_bool: { has: "true" } }` on a list of true/false values as `true`,
+     * which its `BooleanListFilter` takes.
+     */
+    filter?: Record<string, unknown>;
+    totalCount?: boolean;
+    operationName?: string;
+}
+/** REST's `before=end`: the last entries of the list, read back from its end (spec 17, amendment 132). */
+export declare const END_OF_LIST = "end";
+/** REST's and GraphQL's root page size when none is given. */
+export declare const LIST_DEFAULT = 25;
+export declare class CapaBuildError extends Error {
+    /** The closest real names, nearest first. */
+    readonly didYouMean: string[];
+    /** Every name that would have been accepted. */
+    readonly available: string[];
+    constructor(message: string, didYouMean?: string[], available?: string[]);
+}
+/** The system fields every model type has (N6), in schema order. */
+export declare const SYSTEM_FIELDS: readonly ["id", "model", "status", "createdAt", "updatedAt", "publishedAt", "_version", "_tags", "_folder"];
+export declare const MEDIA_FIELDS: readonly ["id", "url", "alt", "type", "width", "height"];
+/**
+ * Relations a query may nest below its root entry. The API reads 5 levels of
+ * entries per root field and counts the root's own as the first, so 4
+ * relations below it (spec 17, amendment 78).
+ */
+export declare const MAX_RELATION_DEPTH = 4;
+export interface PlannedField {
+    /** GraphQL name. */
+    name: string;
+    /** The customer field, or null for a system field or a media subfield. */
+    field: GraphQLFieldSummary | null;
+    /** Relation, relation list and media fields carry what they select. */
+    children?: PlannedField[];
+    /** The target model of an expanded relation. */
+    target?: GraphQLModelSummary;
+    first?: number;
+    sort?: string;
+    after?: string;
+}
+export interface PlannedQuery {
+    model: GraphQLModelSummary;
+    mode: "list" | "single";
+    id?: string;
+    fields: PlannedField[];
+    first?: number;
+    after?: string;
+    before?: string;
+    sort?: string[];
+    filter?: Record<string, unknown>;
+    totalCount: boolean;
+    operationName: string;
+    summary: GraphQLSchemaSummary;
+}
+/** Names within two edits of `wanted`, nearest first then by name, at most three. */
+export declare function didYouMean(wanted: string, candidates: readonly string[]): string[];
+/**
+ * A model by namespace or type name, then by any of those or its display name
+ * ignoring case (`Writers`, `scalar specimens`). An unknown name is refused
+ * with the nearest models, each by namespace, whichever of its names was near.
+ */
+export declare function findModel(summary: GraphQLSchemaSummary, wanted: string): GraphQLModelSummary;
+/** Whether `key` under `field`'s filter is a hop into a field of the related model rather than an operator. */
+export declare function isHop(field: GraphQLFieldSummary, key: string): boolean;
+/** Resolve and check a spec. Throws `CapaBuildError`. */
+export declare function planQuery(summary: GraphQLSchemaSummary, spec: GraphQLQuerySpec): PlannedQuery;