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

package/dist/http.js

@@ -10,7 +10,7 @@ class CapaError extends Error {
     status;
     path;
     constructor(status, path, body) {
-        super(`Capa API ${status} on ${path}${body ? ` — ${body.slice(0, 200)}` : ""}`);
+        super(`Capa API ${status} on ${path}${body ? `: ${body.slice(0, 200)}` : ""}`);
         this.name = "CapaError";
         this.status = status;
         this.path = path;

package/dist/index.d.ts

@@ -6,5 +6,5 @@ export { WEBHOOKS_NEED_ACCESS_TOKEN } from "./webhooks";
 export type { CreateWebhookEndpointInput, ListWebhookDeliveriesOptions, ResumeWebhookEndpointOptions, ResumeWebhookEndpointResult, UpdateWebhookEndpointInput, WebhookDeliveriesPage, WebhookDeliveriesResource, WebhookDelivery, WebhookDeliveryDetail, WebhookDeliveryStatus, WebhookDisabledReason, WebhookEndpoint, WebhookEndpointDetail, WebhookEndpointsResource, WebhookEndpointWithSecret, WebhookEventCatalogueEntry, WebhookEventGroup, WebhookPagination, WebhooksResource, } from "./webhooks";
 export { DEFAULT_WEBHOOK_TOLERANCE_SECONDS, parseWebhookSignatureHeader, signWebhookPayload, verifyWebhookSignature, WEBHOOK_SIGNATURE_HEADER, } from "./webhook-signature";
 export type { ParsedWebhookSignature, VerifyWebhookSignatureInput, } from "./webhook-signature";
-export { generate, normalizeTypes, readStampedChecksum, typeNames } from "./codegen";
-export type { CodegenResult } from "./codegen";
+export { generate, normalizeTypes, readStampedChecksum, restTypesFromIntrospection, typeNames } from "./codegen";
+export type { CodegenResult, RestTypesResult } from "./codegen";

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.typeNames = exports.readStampedChecksum = exports.normalizeTypes = exports.generate = exports.WEBHOOK_SIGNATURE_HEADER = exports.verifyWebhookSignature = exports.signWebhookPayload = exports.parseWebhookSignatureHeader = exports.DEFAULT_WEBHOOK_TOLERANCE_SECONDS = exports.WEBHOOKS_NEED_ACCESS_TOKEN = exports.CapaError = exports.instanceIdOf = exports.createClient = void 0;
+exports.typeNames = exports.restTypesFromIntrospection = exports.readStampedChecksum = exports.normalizeTypes = exports.generate = exports.WEBHOOK_SIGNATURE_HEADER = exports.verifyWebhookSignature = exports.signWebhookPayload = exports.parseWebhookSignatureHeader = exports.DEFAULT_WEBHOOK_TOLERANCE_SECONDS = exports.WEBHOOKS_NEED_ACCESS_TOKEN = exports.CapaError = exports.instanceIdOf = exports.createClient = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "createClient", { enumerable: true, get: function () { return client_1.createClient; } });
 Object.defineProperty(exports, "instanceIdOf", { enumerable: true, get: function () { return client_1.instanceIdOf; } });
@@ -18,4 +18,5 @@ var codegen_1 = require("./codegen");
 Object.defineProperty(exports, "generate", { enumerable: true, get: function () { return codegen_1.generate; } });
 Object.defineProperty(exports, "normalizeTypes", { enumerable: true, get: function () { return codegen_1.normalizeTypes; } });
 Object.defineProperty(exports, "readStampedChecksum", { enumerable: true, get: function () { return codegen_1.readStampedChecksum; } });
+Object.defineProperty(exports, "restTypesFromIntrospection", { enumerable: true, get: function () { return codegen_1.restTypesFromIntrospection; } });
 Object.defineProperty(exports, "typeNames", { enumerable: true, get: function () { return codegen_1.typeNames; } });

package/dist/next/attrs.d.ts

@@ -1,15 +1,31 @@
 /**
  * The attributes that make a rendered field clickable in Capa's live preview.
  *
- *   <h1 {...capaAttrs(entry, "title", isDraft)}>{entry.fields.title}</h1>
+ *   <h1 {...capaAttrs(entry, "title")}>{entry.fields.title}</h1>
+ *   <h1 {...capaAttrs(node, "title")}>{node.title}</h1>          // a GraphQL node
  *
- * `field` is the field's namespace, which is the key it has in `entry.fields`:
- * the API renders every field under its namespace, and the Capa editor tags
- * each field row with that same namespace, so one string names the field on
- * both sides of the preview frame.
+ * For a REST entry, `field` is the field's namespace, which is the key it has
+ * in `entry.fields`: the API renders every field under its namespace, and the
+ * Capa editor tags each field row with that same namespace, so one string
+ * names the field on both sides of the preview frame.
  *
- * Pass `enabled = false` outside draft mode and the element carries nothing, so
- * a published page never ships entry ids in its markup.
+ * For a GraphQL node (an object that selected `id` and `model`), `field` is
+ * the field as selected. A field GraphQL renamed (`hero_image` for
+ * `hero-image`, `status_field` for `status`) is tagged by its namespace: a
+ * client in edit mode reads the key's schema to know which those are.
+ *
+ * EDIT MODE DECIDES, NOT THE CALLER. An entry read by a client created with
+ * `editMode: true` carries a hidden edit mark (`markEditEntries`), and
+ * `capaAttrs` tags only marked entries. So a published page, read with a normal
+ * client, ships no entry ids in its markup without the site passing anything,
+ * and the same component in the Capa editor is clickable. The mark is a
+ * non-enumerable symbol: it does not show up in JSON, logs or a spread copy, and
+ * it does not survive being passed to a client component as a prop, which is
+ * the safe direction to fail in.
+ *
+ * Pass `enabled` to override: `true` tags an unmarked entry, `false` tags
+ * nothing. Sites written before edit mode passed `isDraft` here and keep
+ * working unchanged.
  */
 export type CapaAttrs = {
     "data-capa-entry": string;
@@ -18,7 +34,65 @@ export type CapaAttrs = {
     "data-capa-entry"?: undefined;
     "data-capa-field"?: undefined;
 };
-export declare function capaAttrs<T = Record<string, unknown>>(entry: {
+/** `Symbol.for`, so two copies of the SDK in one bundle agree on the mark. */
+export declare const CAPA_EDIT: unique symbol;
+/** Whether an entry was read in edit mode. */
+export declare function isEditEntry(entry: unknown): boolean;
+/**
+ * Mark every entry inside `value`, related entries included, so a click on an
+ * author inside an article opens the author. Walks arrays and plain objects,
+ * never the same object twice. Returns `value` for chaining.
+ */
+export declare function markEditEntries<T>(value: T): T;
+/**
+ * Mark every entry inside a GraphQL result's `data`: each object that
+ * selected `id` and `model`, related entries included. `renamed(model)` gives
+ * that model's fields whose GraphQL name is not their namespace, by GraphQL
+ * name, so `capaAttrs` tags those by namespace. Returns `data`.
+ */
+export declare function markGraphQLEntries<T>(data: T, renamed?: (model: string) => Readonly<Record<string, string>> | undefined): T;
+/** Whether a GraphQL result's `data` holds any entry `markGraphQLEntries` would mark. */
+export declare function hasGraphQLEntry(data: unknown): boolean;
+/** Keep `from`'s edit mark on `to`, for a copy of an entry in another shape (`toTree`). */
+export declare function carryEditMark<T extends object>(from: unknown, to: T): T;
+/** GraphQL's system fields, which name the entry rather than one of its fields. */
+type GraphQLSystemField = "id" | "model" | "status" | "createdAt" | "updatedAt" | "publishedAt" | "_version" | "_tags" | "_folder" | "__typename";
+/**
+ * The `field` `capaAttrs` takes for `E`: a key of `fields` for a REST entry;
+ * a field as selected for a GraphQL node, which selected `id` and `model`;
+ * any name for a bare `{ id }`. A GraphQL node without `model` takes none,
+ * and the compiler says why.
+ */
+export type TaggableField<E> = unknown extends FieldsOf<E> ? E extends {
+    model: string;
+} ? Exclude<Extract<keyof E, string>, GraphQLSystemField> : [Exclude<keyof E, "id">] extends [never] ? string : "select model on this node: capaAttrs tags an entry that selected id and model" : Extract<keyof NonNullable<FieldsOf<E>>, string>;
+/** A REST entry's `fields` type; `unknown` for anything without one (a GraphQL node, a bare `{ id }`). */
+type FieldsOf<E> = "fields" extends keyof E ? E["fields" & keyof E] : unknown;
+export declare function capaAttrs<E extends {
     id: string;
-    fields?: T;
-}, field: Extract<keyof T, string>, enabled?: boolean): CapaAttrs;
+}>(entry: E, field: TaggableField<E>, enabled?: boolean): CapaAttrs;
+/**
+ * The attributes for every field of `T`, one `CapaAttrs` per field name.
+ * `capa-codegen` writes `<Model>Attrs = FieldAttrs<Model>` beside each
+ * `<Model>Select`, so `const a: ArticleAttrs = fieldAttrs(entry)` fails to
+ * compile on a wrong field name (M5). `fieldAttrs` of a REST entry typed with
+ * `Model` returns exactly this type.
+ */
+export type FieldAttrs<T> = {
+    readonly [K in Extract<keyof T, string>]: CapaAttrs;
+};
+/**
+ * Typed attributes for every field of one entry (M5), or of one GraphQL node:
+ *
+ *   const a = fieldAttrs(article);
+ *   <h1 {...a.title}>…</h1>        // a.titel is a compile error
+ *
+ * Same rule as `capaAttrs`: empty unless the entry was read in edit mode, or
+ * `enabled` says otherwise.
+ */
+export declare function fieldAttrs<E extends {
+    id: string;
+}>(entry: E, enabled?: boolean): {
+    readonly [K in TaggableField<E>]: CapaAttrs;
+};
+export {};

package/dist/next/attrs.js

@@ -1,8 +1,125 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.CAPA_EDIT = void 0;
+exports.isEditEntry = isEditEntry;
+exports.markEditEntries = markEditEntries;
+exports.markGraphQLEntries = markGraphQLEntries;
+exports.hasGraphQLEntry = hasGraphQLEntry;
+exports.carryEditMark = carryEditMark;
 exports.capaAttrs = capaAttrs;
-function capaAttrs(entry, field, enabled = true) {
+exports.fieldAttrs = fieldAttrs;
+/** `Symbol.for`, so two copies of the SDK in one bundle agree on the mark. */
+exports.CAPA_EDIT = Symbol.for("capacms.edit");
+/** Whether an entry was read in edit mode. */
+function isEditEntry(entry) {
+    return (typeof entry === "object" &&
+        entry !== null &&
+        entry[exports.CAPA_EDIT] === true);
+}
+/**
+ * Where a GraphQL node read in edit mode keeps the namespaces of the fields
+ * GraphQL renamed, by GraphQL name. Hidden like the mark itself.
+ */
+const CAPA_EDIT_NAMESPACES = Symbol.for("capacms.edit.namespaces");
+/** A REST entry: an id beside `fields`. */
+function looksLikeEntry(value) {
+    return typeof value.id === "string" && typeof value.fields === "object" && value.fields !== null;
+}
+/** A GraphQL entry: the `Entry` interface's `id` and `model`, which every model type has. */
+function looksLikeGraphQLEntry(value) {
+    return typeof value.id === "string" && typeof value.model === "string";
+}
+/** Define a hidden property: absent from JSON, keys and spreads. */
+function hide(record, key, value) {
+    Object.defineProperty(record, key, { value, enumerable: false, configurable: true });
+}
+/** Visit every plain object and array inside `value` once, cycles included. */
+function eachObject(value, visit) {
+    const seen = new Set();
+    const walk = (node) => {
+        if (typeof node !== "object" || node === null || seen.has(node))
+            return;
+        seen.add(node);
+        if (Array.isArray(node)) {
+            for (const item of node)
+                walk(item);
+            return;
+        }
+        const record = node;
+        visit(record);
+        for (const key of Object.keys(record))
+            walk(record[key]);
+    };
+    walk(value);
+}
+/**
+ * Mark every entry inside `value`, related entries included, so a click on an
+ * author inside an article opens the author. Walks arrays and plain objects,
+ * never the same object twice. Returns `value` for chaining.
+ */
+function markEditEntries(value) {
+    eachObject(value, (record) => {
+        if (looksLikeEntry(record) && Object.isExtensible(record))
+            hide(record, exports.CAPA_EDIT, true);
+    });
+    return value;
+}
+/**
+ * Mark every entry inside a GraphQL result's `data`: each object that
+ * selected `id` and `model`, related entries included. `renamed(model)` gives
+ * that model's fields whose GraphQL name is not their namespace, by GraphQL
+ * name, so `capaAttrs` tags those by namespace. Returns `data`.
+ */
+function markGraphQLEntries(data, renamed = () => undefined) {
+    eachObject(data, (record) => {
+        if (!looksLikeGraphQLEntry(record) || !Object.isExtensible(record))
+            return;
+        hide(record, exports.CAPA_EDIT, true);
+        const namespaces = renamed(record.model);
+        if (namespaces)
+            hide(record, CAPA_EDIT_NAMESPACES, namespaces);
+    });
+    return data;
+}
+/** Whether a GraphQL result's `data` holds any entry `markGraphQLEntries` would mark. */
+function hasGraphQLEntry(data) {
+    let found = false;
+    eachObject(data, (record) => {
+        found ||= looksLikeGraphQLEntry(record);
+    });
+    return found;
+}
+/** Keep `from`'s edit mark on `to`, for a copy of an entry in another shape (`toTree`). */
+function carryEditMark(from, to) {
+    if (isEditEntry(from) && Object.isExtensible(to))
+        hide(to, exports.CAPA_EDIT, true);
+    return to;
+}
+/** The namespace a field of `entry` is tagged with: a renamed GraphQL field's own, else the name given. */
+function namespaceOf(entry, field) {
+    const namespaces = entry[CAPA_EDIT_NAMESPACES];
+    return namespaces?.[field] ?? field;
+}
+function capaAttrs(entry, field, enabled = isEditEntry(entry)) {
     if (!enabled)
         return {};
-    return { "data-capa-entry": entry.id, "data-capa-field": field };
+    return { "data-capa-entry": entry.id, "data-capa-field": namespaceOf(entry, field) };
+}
+/**
+ * Typed attributes for every field of one entry (M5), or of one GraphQL node:
+ *
+ *   const a = fieldAttrs(article);
+ *   <h1 {...a.title}>…</h1>        // a.titel is a compile error
+ *
+ * Same rule as `capaAttrs`: empty unless the entry was read in edit mode, or
+ * `enabled` says otherwise.
+ */
+function fieldAttrs(entry, enabled = isEditEntry(entry)) {
+    return new Proxy({}, {
+        get(_target, key) {
+            if (typeof key !== "string")
+                return undefined;
+            return enabled ? { "data-capa-entry": entry.id, "data-capa-field": namespaceOf(entry, key) } : {};
+        },
+    });
 }

package/dist/next/client.d.ts

@@ -1,6 +1,18 @@
-import type { Select } from "./select-types";
+import type { CapaDocumentResult, CapaDocuments, CapaDocumentVariables, NotARecordedDocument } from "./graphql/documents";
+import { type GraphQLCallOptions, type GraphQLResult, type TypedDocument, type VariablesThenOptions } from "./graphql/request";
+import { type GraphQLSchemaSummary } from "./graphql/summary";
+import { type ExactSelection, type QueryResult, type QuerySelection, type UntypedQuery } from "./graphql/typed";
+export { CapaError, isCapaError } from "./errors";
+import type { EntryFields, FlatFields, FlatRead, IncludedFields } from "./entry-fields";
+import type { ExpandedTargets, Select } from "./select-types";
 export interface CapaNextConfig {
     baseUrl: string;
+    /**
+     * A `cap_` key, or the legacy key a site already holds: `pk_`, `sk_`, or
+     * an older key with no prefix. A legacy key reads through every read call
+     * and warns once per process; `preview()` and draft reads take a `cap_` key
+     * only.
+     */
     apiKey: string;
     version: string;
     contract?: 1;
@@ -34,6 +46,23 @@ export interface CapaNextConfig {
      * Config only, never per call: one build has one schema.
      */
     schemaChecksum?: string;
+    /**
+     * Read in edit mode: every entry this client returns carries the hidden edit
+     * mark, so `capaAttrs` tags it for the Capa editor. Leave it off for visitors
+     * and a published page ships no entry ids. `@capacms/sdk/nextjs` works it out
+     * per request with `editMode()`.
+     *
+     * The same request is sent either way. A GraphQL read marks each object
+     * that selected `id` and `model`, and to tag a field GraphQL renamed by its
+     * namespace, it also reads the key's schema, once a minute.
+     */
+    editMode?: boolean;
+    /**
+     * The concrete path being rendered (`/blog/hello`), sent as `Capa-Path`
+     * beside `Capa-Page` (`/blog/[slug]`). Telemetry only, like `page`: it is how
+     * Capa lists every real URL an entry appears on. Usually set per call.
+     */
+    path?: string;
     /** Injected for tests, non-standard runtimes, and framework fetch wrappers. */
     fetch?: typeof fetch;
 }
@@ -53,7 +82,18 @@ export interface CallOptions {
      * writing the code.
      */
     page?: string;
+    /**
+     * The concrete path THIS read renders (`/blog/hello`). Overrides `path` on the
+     * config. Sent as `Capa-Path` only alongside a `Capa-Page`, since a path with
+     * no page says nothing Capa can group.
+     */
+    path?: string;
 }
+/**
+ * One entry as `/api/entries` returns it: the system keys, and `fields`. A read
+ * types `fields` from its model and select (`EntryFields`), so a relation is a
+ * reference or the related entry, and a relation list is `{ items, pageInfo }`.
+ */
 export interface Entry<T = Record<string, unknown>> {
     id: string;
     model: string;
@@ -97,23 +137,74 @@ export type FilterOperator = "eq" | "ne" | "in" | "nin" | "lt" | "lte" | "gt" |
 export type FilterScalar = string | number | boolean | null;
 export type FilterValue = FilterScalar | readonly FilterScalar[];
 export type Filter = Record<string, Partial<Record<FilterOperator, FilterValue>>>;
-export interface ListOptions<T = Record<string, unknown>> extends CallOptions {
-    select?: Select<T> | string;
+/**
+ * How expanded relations come back (`?shape=`). `tree`, the default, nests each
+ * one inline where it was selected. `flat` answers every relation as a
+ * `{ id, model }` reference and every expanded entry ONCE, in `included`, so
+ * twenty articles by one author carry that author once. `inflate(result)`
+ * turns a flat result back into the tree one.
+ */
+export type ResponseShape = "tree" | "flat";
+export interface ListOptions<T = Record<string, unknown>, S extends Select<T> | string = Select<T> | string> extends CallOptions {
+    select?: S;
+    shape?: "tree";
     filter?: Filter;
     where?: Record<string, unknown>;
     sort?: readonly string[];
     limit?: number;
     count?: boolean;
+    /** `page.next`: the page after it. */
     after?: string;
+    /** `page.prev`: the page before it. Or `"end"`: the last `limit` entries of the list. */
     before?: string;
 }
-export interface GetOptions<T = Record<string, unknown>> extends CallOptions {
-    select?: Select<T> | string;
+export interface GetOptions<T = Record<string, unknown>, S extends Select<T> | string = Select<T> | string> extends CallOptions {
+    select?: S;
+    shape?: "tree";
 }
+/** `list` with `shape: "flat"`. `S` is the select, which types `included`. */
+export type FlatListOptions<T, S extends Select<T> | string = Select<T>> = Omit<ListOptions<T>, "select" | "shape"> & {
+    select?: S;
+    shape: "flat";
+};
+/** `get` with `shape: "flat"`. */
+export type FlatGetOptions<T, S extends Select<T> | string = Select<T>> = Omit<GetOptions<T>, "select" | "shape"> & {
+    select?: S;
+    shape: "flat";
+};
+/**
+ * `included` of a flat read: model namespace, then entry id, then the entry.
+ * Typed by the select: the union of every entry type it expands, each field
+ * of which may be absent, and every relation in it a reference.
+ */
+export type Included<I> = Record<string, Record<string, Entry<IncludedFields<I>>>>;
+interface FlatExtras<T, S> extends FlatRead<T, S> {
+    included: Included<[ExpandedTargets<T, S>] extends [never] ? never : ExpandedTargets<T, S>>;
+    /** The select this read sent, which is what `inflate` walks. Absent when none was sent. */
+    select?: string;
+}
+/** A `shape=flat` list: every relation in `data` a reference, each expanded entry once in `included`. */
+export type FlatPage<T, S = Select<T>> = Page<Entry<FlatFields<T, S>>> & FlatExtras<T, S>;
+export type FlatSingle<T, S = Select<T>> = Single<Entry<FlatFields<T, S>>> & FlatExtras<T, S>;
+/**
+ * `T` as given, never inferred from the options: a read's model type is
+ * written (`list<Article>`), and without one the read is untyped whatever its
+ * select names. Inferred from a select's names, `T` would be `{ title: any }`,
+ * which refuses the relations the same select expands.
+ */
+type Given<T> = [T][T extends unknown ? 0 : never];
+/**
+ * Reads of `/api/entries`. `T` is the model type (`list<Articles>`), and `S`
+ * the select's own type, for `fields` typed exactly as the read returns them
+ * (`list<Articles, typeof select>`); see `EntryFields`.
+ */
 export interface EntriesResource {
-    list<T = Record<string, unknown>>(namespace: string, options?: ListOptions<T>): Promise<Page<Entry<T>>>;
-    get<T = Record<string, unknown>>(namespace: string, id: string, options?: GetOptions<T>): Promise<Single<Entry<T>> | null>;
-    iterate<T = Record<string, unknown>>(namespace: string, options?: ListOptions<T>): AsyncGenerator<Entry<T>, void, undefined>;
+    list<T = Record<string, unknown>, S extends Select<T> | string = Select<T>>(namespace: string, options: FlatListOptions<Given<T>, S>): Promise<FlatPage<T, S>>;
+    list<T = Record<string, unknown>, S extends Select<T> | string = Select<T> | string>(namespace: string, options?: ListOptions<Given<T>, S>): Promise<Page<Entry<EntryFields<T, S>>>>;
+    get<T = Record<string, unknown>, S extends Select<T> | string = Select<T>>(namespace: string, id: string, options: FlatGetOptions<Given<T>, S>): Promise<FlatSingle<T, S> | null>;
+    get<T = Record<string, unknown>, S extends Select<T> | string = Select<T> | string>(namespace: string, id: string, options?: GetOptions<Given<T>, S>): Promise<Single<Entry<EntryFields<T, S>>> | null>;
+    /** Tree only: it yields entries one at a time, which is what `included` exists to avoid. */
+    iterate<T = Record<string, unknown>, S extends Select<T> | string = Select<T> | string>(namespace: string, options?: ListOptions<Given<T>, S>): AsyncGenerator<Entry<EntryFields<T, S>>, void, undefined>;
 }
 /**
  * One suggestion drawn from a page's own reads.
@@ -252,7 +343,55 @@ export interface PreviewClaim {
     path: string | null;
     expiresAt: string;
 }
-export interface CapaNextClient {
+/**
+ * `client.graphql`: run a document, or build one from a typed selection with
+ * `client.graphql.query()`. `Q` is the `CapaQuery` type `capa-codegen
+ * --graphql` writes; without it selections and results are untyped. `O` is
+ * what a call takes: `getCapaClient` from `/nextjs` adds Next's cache `tags`
+ * and `revalidate`.
+ */
+export interface GraphQLClient<Q = UntypedQuery, O extends GraphQLCallOptions = GraphQLCallOptions> {
+    /**
+     * Run a document written as a literal (`#graphql`, `/* capa *\/` or
+     * gql(`...`)) that `capa-codegen --graphql` has checked: its text is looked
+     * up in `CapaDocuments`, so `data` and `variables` are typed with no cast.
+     *
+     * Resolves once the API ran the document, even when `errors` is not empty,
+     * because the root fields that worked still carry data. Throws `CapaError`
+     * when the API refused the request as a whole, with `graphqlErrors` holding
+     * every error it sent: `errors` and no `data`, whether sent as a 4xx or, as
+     * GraphQL over HTTP sends it on `application/json`, as a 200.
+     */
+    <D extends keyof CapaDocuments>(document: D, ...rest: VariablesThenOptions<CapaDocumentVariables<D>, O>): Promise<GraphQLResult<CapaDocumentResult<D>>>;
+    /**
+     * Run a GraphQL document. A `<Name>Document` from `capa-codegen --graphql`
+     * types `data` and `variables` by itself; for any other string, pass the
+     * data type: `capa.graphql<{ articles: ... }>(query, variables)`.
+     */
+    <TData = Record<string, unknown>, TVariables = Record<string, unknown>, D extends string = string>(document: NotARecordedDocument<D, TypedDocument<TData, TVariables> | D>, ...rest: VariablesThenOptions<TVariables, O>): Promise<GraphQLResult<TData>>;
+    /**
+     * Build the document from a selection object and run it. See "Typed
+     * builder" in the README. It takes no `persisted`: see `BuilderCallOptions`.
+     */
+    query<const S extends QuerySelection<Q>>(selection: S & ExactSelection<S, Q>, options?: BuilderCallOptions<O>): Promise<GraphQLResult<QueryResult<Q, S>>>;
+}
+/**
+ * What `graphql.query()` takes: a call's options without `persisted`. The
+ * builder prints its document when it runs, so `capa persist`, which stores
+ * the documents written in a project, never stored it, and a production key
+ * never registers one: every read would miss its hash and fall back to a POST,
+ * which is never cached. Unpersisted, a builder read is already a GET the API
+ * and the CDN cache. To persist a read, write it as a `#graphql` literal.
+ */
+export type BuilderCallOptions<O extends GraphQLCallOptions = GraphQLCallOptions> = Omit<O, "persisted">;
+/**
+ * `client.graphql` over one way of reading a document: called with a
+ * document, and `query()` printing a selection's document for it. `createClient`
+ * reads straight from the API, and `getCapaClient` from `/nextjs` through
+ * Next's data cache, with the same refusals.
+ */
+export declare function graphqlClient<Q, O extends GraphQLCallOptions>(read: (document: string, variables: Record<string, unknown> | undefined, options: O | undefined) => Promise<GraphQLResult<unknown>>): GraphQLClient<Q, O>;
+export interface CapaNextClient<Q = UntypedQuery, O extends GraphQLCallOptions = GraphQLCallOptions> {
     entries: EntriesResource;
     pages: PagesResource;
     /**
@@ -261,31 +400,22 @@ export interface CapaNextClient {
      * Returns the claim, or NULL when the token is invalid or expired, because
      * both mean the same thing to a preview route: do not enable draft mode.
      * Every other failure throws, so a Capa outage does not look like a bad link.
+     * Needs a `cap_` key: a client built with a legacy key throws a
+     * `TypeError` here before any request.
      */
     preview(token: string, options?: CallOptions): Promise<PreviewClaim | null>;
     me<T = Record<string, unknown>>(options?: CallOptions): Promise<T>;
     versions<T = Record<string, unknown>>(options?: CallOptions): Promise<T>;
+    graphql: GraphQLClient<Q, O>;
+    /**
+     * Every model this key can read over GraphQL, with its root fields, fields,
+     * filter operators and sort values, read from one introspection request.
+     * What `buildGraphQLQuery`, `graphqlToSelect` and `toTree` take.
+     */
+    graphqlSchema(options?: {
+        signal?: AbortSignal;
+    }): Promise<GraphQLSchemaSummary<Q>>;
 }
-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;
-    constructor(input: {
-        status: number;
-        type: string;
-        code: string;
-        message: string;
-        param?: string;
-        hint?: string;
-        requestId: string;
-        docs: string;
-    });
-}
-export declare function isCapaError(error: unknown): error is CapaError;
 export declare function resolveNextConfig(config: CapaNextConfig): ResolvedNextConfig;
 /**
  * The page a layout (or template) reads for: none.
@@ -304,5 +434,4 @@ export declare const LAYOUT_PAGE = "(layout)";
 type SelectInput = string | ReadonlyArray<unknown>;
 /** Serialize the SDK object form into the canonical `/api/entries` grammar. */
 export declare function serializeSelect(select: SelectInput): string;
-export declare function createClient(config: CapaNextConfig): CapaNextClient;
-export {};
+export declare function createClient<Q = UntypedQuery>(config: CapaNextConfig): CapaNextClient<Q>;