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

package/dist/next/client.js

@@ -1,11 +1,36 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LAYOUT_PAGE = exports.CapaError = void 0;
-exports.isCapaError = isCapaError;
+exports.LAYOUT_PAGE = exports.isCapaError = exports.CapaError = void 0;
+exports.graphqlClient = graphqlClient;
 exports.resolveNextConfig = resolveNextConfig;
 exports.serializeSelect = serializeSelect;
 exports.createClient = createClient;
 const attrs_1 = require("./attrs");
+const errors_1 = require("./errors");
+const edit_mode_1 = require("./graphql/edit-mode");
+const key_family_1 = require("./key-family");
+const system_keys_1 = require("./system-keys");
+const field_names_1 = require("./field-names");
+const introspection_1 = require("./graphql/introspection");
+const request_1 = require("./graphql/request");
+const summary_1 = require("./graphql/summary");
+const typed_1 = require("./graphql/typed");
+var errors_2 = require("./errors");
+Object.defineProperty(exports, "CapaError", { enumerable: true, get: function () { return errors_2.CapaError; } });
+Object.defineProperty(exports, "isCapaError", { enumerable: true, get: function () { return errors_2.isCapaError; } });
+/**
+ * The platform fetch, called through `globalThis` on every request. Storing
+ * `globalThis.fetch` and calling it as a method of the config object gives it
+ * the wrong `this`, and a browser refuses that ("Failed to execute 'fetch' on
+ * 'Window': Illegal invocation"); Node does not care, which is why only
+ * browser reads broke. Looking it up per call also picks up a fetch a
+ * framework patches in after the client is built (Next does).
+ */
+function defaultFetch() {
+    if (typeof globalThis.fetch !== "function")
+        return undefined;
+    return ((input, init) => globalThis.fetch(input, init));
+}
 /**
  * What a `Capa-Schema` value may look like: hex, 8 to 64 characters.
  *
@@ -17,29 +42,24 @@ const attrs_1 = require("./attrs");
  * appears rather than as an error.
  */
 const SCHEMA_CHECKSUM = /^[a-f0-9]{8,64}$/;
-class CapaError extends Error {
-    status;
-    type;
-    code;
-    param;
-    hint;
-    requestId;
-    docs;
-    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;
-    }
-}
-exports.CapaError = CapaError;
-function isCapaError(error) {
-    return error instanceof CapaError;
+const BUILDER_NOT_PERSISTED = "@capacms/sdk/next: graphql.query() cannot send persisted: true. It builds its document when it runs, " +
+    "so capa persist never stored it and every read would fall back to an uncached POST. " +
+    "Leave persisted out (a builder read is already a cached GET), or write the read as a #graphql literal and run capa persist.";
+/**
+ * `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` the same way
+ * unless a call gives `tags` or `revalidate`, then through Next's data cache,
+ * with the same refusals.
+ */
+function graphqlClient(read) {
+    const query = async (selection, options) => {
+        if (options?.persisted)
+            throw new TypeError(BUILDER_NOT_PERSISTED);
+        return read((0, typed_1.selectionToDocument)(selection, options?.operationName), undefined, options);
+    };
+    const call = (document, variables, options) => read(document, variables, options);
+    return Object.assign(call, { query });
 }
 function resolveNextConfig(config) {
     const value = (config ?? {});
@@ -48,13 +68,14 @@ function resolveNextConfig(config) {
         throw new Error(`@capacms/sdk/next: missing ${missing.join(", ")}. ` +
             "createClient needs baseUrl, apiKey and version.");
     }
-    if (!value.apiKey.startsWith("cap_")) {
-        throw new Error("@capacms/sdk/next: apiKey must start with cap_. Use the legacy @capacms/sdk client for pk_ and sk_ keys.");
+    if ((0, key_family_1.keyFamily)(value.apiKey) === null) {
+        throw new Error("@capacms/sdk/next: apiKey must be a string: a cap_ key, or the legacy key your site already holds. " +
+            "Mint a cap_ key in the Capa admin under Developers > Keys.");
     }
     if (value.contract !== undefined && value.contract !== 1) {
         throw new Error("@capacms/sdk/next: contract must be 1 when provided.");
     }
-    const fetchImpl = value.fetch ?? globalThis.fetch;
+    const fetchImpl = value.fetch ?? defaultFetch();
     if (typeof fetchImpl !== "function") {
         throw new Error("@capacms/sdk/next: no fetch available. Pass one via config.fetch.");
     }
@@ -140,12 +161,41 @@ function resolvePath(configPath, callPath) {
     }
     return bare;
 }
-const NAME = /^[A-Za-z0-9_-]+$/;
+/*
+ * The array form names each field by its namespace, as saved in the admin,
+ * and the select is written in REST's grammar: a namespace that holds a
+ * character the grammar uses goes quoted (`"price.usd"`, field-names.ts). A
+ * name starting with `$` is a system key, so no field can be named that way;
+ * select "*" returns such a field.
+ */
+/** A relation's name: a field, since a system key expands nothing. */
 function selectName(value, context) {
-    if (typeof value !== "string" || !NAME.test(value)) {
+    if (typeof value !== "string" || !(0, field_names_1.isNameable)(value)) {
         throw new TypeError(`@capacms/sdk/next: ${context} must be a field name.`);
     }
-    return value;
+    return (0, field_names_1.writeName)(value);
+}
+/**
+ * A select item: a field, or a system key by its `$` name, which means the
+ * system key even beside a field of the same plain name (spec 17, amendment 29).
+ */
+function selectItemName(value) {
+    if ((0, system_keys_1.sigilSystemKey)(value) !== null)
+        return value;
+    if ((0, field_names_1.isNameable)(value))
+        return (0, field_names_1.writeName)(value);
+    throw new TypeError(`@capacms/sdk/next: select item must be a field name, or a system key: ${system_keys_1.SYSTEM_KEY_LIST}.`);
+}
+/** One nested sort key: a field, or a system key the API sorts by, either with a leading `-`. */
+function nestedSort(value, relation) {
+    const descending = typeof value === "string" && value.startsWith("-");
+    const key = descending ? value.slice(1) : value;
+    const system = typeof key === "string" ? (0, system_keys_1.sigilSystemKey)(key) : null;
+    if (system !== null && (0, system_keys_1.isSortableSystemKey)(system))
+        return value;
+    if (typeof key === "string" && system === null && (0, field_names_1.isNameable)(key))
+        return `${descending ? "-" : ""}${(0, field_names_1.writeName)(key)}`;
+    throw new TypeError(`@capacms/sdk/next: ${relation}.sort must be one field name, or one of ${system_keys_1.SORTABLE_SYSTEM_KEYS.map((k) => `$${k}`).join(", ")}, with - to sort descending.`);
 }
 function serializeSelectItems(items) {
     if (items.length === 0)
@@ -153,7 +203,7 @@ function serializeSelectItems(items) {
     return items
         .map((item) => {
         if (typeof item === "string") {
-            return item === "*" ? item : selectName(item, "select item");
+            return item === "*" ? item : selectItemName(item);
         }
         if (!item || typeof item !== "object" || Array.isArray(item)) {
             throw new TypeError("@capacms/sdk/next: each select item must be a field name or relation object.");
@@ -162,12 +212,12 @@ function serializeSelectItems(items) {
         if (entries.length !== 1) {
             throw new TypeError("@capacms/sdk/next: a relation select object must name exactly one field.");
         }
-        const [rawName, value] = entries[0];
-        const name = selectName(rawName, "relation select key");
+        const [name, value] = entries[0];
+        const written = selectName(name, "relation select key");
         if (value === "*")
-            return `${name}(*)`;
+            return `${written}(*)`;
         if (Array.isArray(value))
-            return `${name}(${serializeSelectItems(value)})`;
+            return `${written}(${serializeSelectItems(value)})`;
         if (!value || typeof value !== "object") {
             throw new TypeError(`@capacms/sdk/next: ${name} must select fields, "*", or select options.`);
         }
@@ -192,19 +242,15 @@ function serializeSelectItems(items) {
             }
             args.push(`limit:${options.limit}`);
         }
-        if (options.sort !== undefined) {
-            if (typeof options.sort !== "string" || !/^-?[A-Za-z0-9_-]+$/.test(options.sort)) {
-                throw new TypeError(`@capacms/sdk/next: ${name}.sort must be one field name.`);
-            }
-            args.push(`sort:${options.sort}`);
-        }
+        if (options.sort !== undefined)
+            args.push(`sort:${nestedSort(options.sort, name)}`);
         if (options.after !== undefined) {
             if (typeof options.after !== "string" || options.after === "") {
                 throw new TypeError(`@capacms/sdk/next: ${name}.after must be a non-empty cursor.`);
             }
             args.push(`after:${options.after}`);
         }
-        return `${name}(${args.join(",")})`;
+        return `${written}(${args.join(",")})`;
     })
         .join(",");
 }
@@ -287,39 +333,6 @@ function listQuery(options) {
         query.set("before", options.before);
     return query;
 }
-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) {
-    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,
-    });
-}
 function cacheTags(response) {
     const value = response.headers?.get?.("Surrogate-Key") ?? "";
     return value.split(/\s+/).filter(Boolean);
@@ -354,12 +367,13 @@ function createRequester(config) {
             body = JSON.parse(text);
         }
         catch {
-            throw unparseable(response.status, requestId);
+            throw (0, errors_1.unparseable)(response.status, requestId);
+        }
+        if (!response.ok) {
+            throw (0, errors_1.errorFromEnvelope)(response.status, body, requestId, (0, errors_1.retryAfterOf)(response.headers?.get?.("Retry-After")));
         }
-        if (!response.ok)
-            throw errorFromEnvelope(response.status, body, requestId);
         if (!body || typeof body !== "object")
-            throw unparseable(response.status, requestId);
+            throw (0, errors_1.unparseable)(response.status, requestId);
         if (config.editMode === true) {
             // `included` holds a flat read's related entries, which are marked
             // exactly as they are when the tree nests them inside `data`.
@@ -373,7 +387,36 @@ function createRequester(config) {
 }
 function createClient(config) {
     const resolved = resolveNextConfig(config);
+    if ((0, key_family_1.keyFamily)(resolved.apiKey) === "legacy")
+        (0, key_family_1.warnLegacyKeyOnce)(resolved.apiKey);
     const request = createRequester(resolved);
+    // By POST: introspection is never cached (G plan D16), and the admin host
+    // serves GraphQL by POST only.
+    const readSchema = async (signal) => {
+        const result = await (0, request_1.runGraphQL)(resolved, introspection_1.INTROSPECTION_QUERY, undefined, { signal, method: "POST" });
+        const requestId = result.extensions.capa?.requestId ?? "";
+        // The API answered 200, so the status says so; the errors say what failed.
+        if (result.errors.length > 0)
+            throw (0, errors_1.errorFromGraphQLErrors)(200, result.errors, requestId);
+        if (!result.data)
+            throw (0, errors_1.unparseable)(200, requestId);
+        return (0, summary_1.summarizeIntrospection)(result.data);
+    };
+    // By POST, as the schema above: it selects only `__schema`.
+    const readFieldNames = async () => {
+        const result = await (0, request_1.runGraphQL)(resolved, introspection_1.FIELD_NAMES_QUERY, undefined, { method: "POST" });
+        if (!result.data || result.errors.length > 0)
+            throw new Error("the key's field names could not be read");
+        return result.data;
+    };
+    /** One GraphQL read; in edit mode its entries are marked for `capaAttrs`, as REST's are. */
+    const readGraphQL = (document, variables, options) => {
+        const read = () => (0, request_1.runGraphQL)(resolved, document, variables, options);
+        if (resolved.editMode !== true)
+            return read();
+        return (0, edit_mode_1.readMarked)(document, `${resolved.baseUrl}\n${resolved.apiKey}\n${resolved.version}`, readFieldNames, read);
+    };
+    const graphql = graphqlClient(readGraphQL);
     /**
      * A flat read's result carries the select it sent, so `inflate(result)`
      * needs nothing else. A tree read's result is exactly what it always was.
@@ -399,7 +442,7 @@ function createClient(config) {
                 return withSelect({ ...result.body, cacheTags: result.cacheTags }, options);
             }
             catch (error) {
-                if (error instanceof CapaError &&
+                if (error instanceof errors_1.CapaError &&
                     error.status === 404 &&
                     error.type === "not_found" &&
                     error.code === "entry_not_found") {
@@ -441,7 +484,7 @@ function createClient(config) {
                 // Same shape as `entries.get`: a page nobody has declared or read is a
                 // null, not a throw, because "is this page known to Capa" is a question
                 // a caller asks on purpose.
-                if (error instanceof CapaError &&
+                if (error instanceof errors_1.CapaError &&
                     error.status === 404 &&
                     error.code === "page_not_found") {
                     return null;
@@ -453,7 +496,12 @@ function createClient(config) {
     return {
         entries,
         pages,
+        graphql,
+        graphqlSchema(options = {}) {
+            return readSchema(options.signal);
+        },
         async preview(token, options = {}) {
+            (0, key_family_1.requirePreviewKey)(resolved.apiKey);
             const query = new URLSearchParams();
             query.set("token", token);
             try {
@@ -464,7 +512,7 @@ function createClient(config) {
                 // preview route has the same fallback for either: render the published
                 // page. Anything else (a 500, a network failure, a missing scope) is a
                 // real problem and must not be mistaken for a stale link.
-                if (error instanceof CapaError &&
+                if (error instanceof errors_1.CapaError &&
                     (error.code === "preview_token_invalid" || error.code === "preview_token_expired")) {
                     return null;
                 }

package/dist/next/entry-fields.d.ts

@@ -0,0 +1,162 @@
+/**
+ * entry-fields.ts — an entry's `fields` as `/api/entries` returns them, typed
+ * from the model and the select.
+ *
+ * A model type says what an editor stores: `capa-codegen` writes a relation as
+ * the related model (`CapaRelation<Authors>`), a relation list as a list of
+ * them, and media as the upload (`CapaImage`). A read answers in its own shape
+ * (docs/api/entries.md), and these types say which:
+ *
+ *   - a field the select names is always there, and `null` when it was never
+ *     filled, as the API writes it: optional in the model, never absent here;
+ *   - a field the select does not name is not there;
+ *   - a relation the select does not expand is a reference, `{ id, model }`,
+ *     or null when it is empty;
+ *   - an expanded relation is the related entry, with `fields` of its own, or
+ *     `{ id, model, missing: true }` when that entry was deleted, is
+ *     unpublished for a production key, or is in a model the key cannot read;
+ *   - a relation list is `{ items, pageInfo }`, expanded or not;
+ *   - media is `{ id, url, alt, type, width, height }`, never the upload's
+ *     own keys.
+ *
+ * A select the compiler can read exactly, a literal passed as its type
+ * (`list<Articles, typeof select>`), types what it names. One it cannot, a
+ * string or a value typed as `Select<T>` itself, types every field, and each
+ * relation as any of the three it may be, which the caller narrows
+ * (`"fields" in author`). An untyped model (`Record<string, unknown>`) stays
+ * untyped.
+ */
+import type { Entry } from "./client";
+import type { Select } from "./select-types";
+/** A relation a read did not expand: the entry's id, and its model's namespace, null when the key cannot read that model. */
+export interface EntryReference {
+    id: string;
+    model: string | null;
+}
+/**
+ * An expanded relation the API looked for and did not find: the entry was
+ * deleted, is unpublished for a production key, or is in a model the key
+ * cannot read.
+ */
+export interface MissingEntry extends EntryReference {
+    missing: true;
+}
+/** A relation list, expanded or not. `limit` is there when the read expanded it. */
+export interface RelationItems<E> {
+    items: E[];
+    pageInfo: {
+        limit?: number;
+        hasNext: boolean;
+        next: string | null;
+    };
+}
+/** An image, video or file as `/api/` returns it. */
+export interface EntryMedia {
+    id: string;
+    url: string | null;
+    alt: string | null;
+    type: string | null;
+    width: number | null;
+    height: number | null;
+}
+/**
+ * Levels of entries left to type: the root entry and 4 below it, the API's 5
+ * levels. A relation past the last level is typed as a reference, which is all
+ * the API returns there.
+ */
+type Depth = [never, 0, 1, 2, 3, 4];
+type Flatten<T> = {
+    [K in keyof T]: T[K];
+};
+/** A field type that says nothing: `unknown`, or `any`. */
+type Untyped<V> = 0 extends 1 & V ? true : unknown extends V ? true : false;
+type RelationBrand = {
+    readonly __capaRelation: "one" | "many";
+    readonly __capaRelationTarget: unknown;
+};
+type IsRelation<V> = Untyped<V> extends true ? false : NonNullable<V> extends RelationBrand ? true : false;
+type IsList<V> = NonNullable<V> extends {
+    readonly __capaRelation: "many";
+} ? true : false;
+type TargetOf<V> = NonNullable<V> extends {
+    readonly __capaRelationTarget: infer R;
+} ? R : never;
+/** Media as codegen types it: `CapaImage`, `CapaVideo` and `CapaFile` each have a `url`. */
+type StoredMedia = {
+    url: string;
+};
+/**
+ * A field that is no relation: as stored, or `null` when it was never filled,
+ * but media, which the read returns in its public shape.
+ */
+type ValueTree<V> = Untyped<V> extends true ? V : NonNullable<V> extends ReadonlyArray<infer M> ? [M] extends [StoredMedia] ? EntryMedia[] | null : NonNullable<V> | null : NonNullable<V> extends StoredMedia ? EntryMedia | null : NonNullable<V> | null;
+/** A relation the read did not expand. */
+type ReferenceTree<V> = IsList<V> extends true ? RelationItems<EntryReference> : EntryReference | null;
+/** A field the read names without expanding it. */
+type FieldTree<V> = IsRelation<V> extends true ? ReferenceTree<V> : ValueTree<V>;
+/** An expanded relation, its entries read with `S`, at level `D`. */
+type ExpandedTree<V, S, D extends number> = IsList<V> extends true ? RelationItems<Entry<FieldsAt<TargetOf<V>, S, D>> | MissingEntry> : Entry<FieldsAt<TargetOf<V>, S, D>> | MissingEntry | null;
+/** A relation the read may or may not have expanded, with any select, at level `D`. */
+type EitherTree<V, D extends number> = IsList<V> extends true ? RelationItems<EntryReference | MissingEntry | Entry<FieldsAt<TargetOf<V>, string, D>>> : EntryReference | MissingEntry | Entry<FieldsAt<TargetOf<V>, string, D>> | null;
+/** Every field, relations as references: a read with no select, or `*`. */
+type ReferenceFields<T> = {
+    [K in keyof T]-?: FieldTree<T[K]>;
+};
+/** Every field, each relation as whatever it may be: a select the compiler cannot read. */
+type LooseFields<T, D extends number> = {
+    [K in keyof T]-?: IsRelation<T[K]> extends true ? EitherTree<T[K], Depth[D]> : ValueTree<T[K]>;
+};
+/** The relations a select item expands, by name. */
+type ExpandedIn<I> = I extends string ? never : Extract<keyof I, string>;
+/** What the select writes for relation `K`: its list, `*`, or its options' `select`. */
+type SubSelect<I, K extends string> = I extends {
+    readonly [P in K]: infer V;
+} ? V extends {
+    readonly select: infer S;
+} ? S : V : never;
+/**
+ * The fields a literal select names, `I` being the union of its items: each
+ * named field, every field for `*`, and each expanded relation as the entries
+ * its own select reads. A system key (`$tags`) sits beside `fields`, on the entry.
+ */
+type SelectedFields<T, I, D extends number> = Flatten<{
+    [K in keyof T as K extends ExpandedIn<I> ? IsRelation<T[K]> extends true ? never : K : "*" extends I ? K : K extends I ? K : never]-?: FieldTree<T[K]>;
+} & {
+    [K in keyof T as K extends ExpandedIn<I> ? (IsRelation<T[K]> extends true ? K : never) : never]-?: ExpandedTree<T[K], SubSelect<I, K & string>, Depth[D]>;
+}>;
+type FieldsAt<T, S, D extends number> = string extends keyof T ? T : [D] extends [never] ? ReferenceFields<T> : [S] extends [undefined] ? ReferenceFields<T> : [S] extends ["*"] ? ReferenceFields<T> : S extends ReadonlyArray<infer I> ? Select<T> extends S ? LooseFields<T, D> : SelectedFields<T, I, D> : LooseFields<T, D>;
+/**
+ * `fields` of an entry of model `T` read with select `S`, as `/api/entries`
+ * returns them. Pass the select's own type for exact fields
+ * (`list<Articles, typeof select>`); without it every field is typed, and
+ * each relation as whatever it may be.
+ */
+export type EntryFields<T, S = Select<T> | string> = FieldsAt<T, S, 4>;
+/** A field of a `shape=flat` read: each relation a reference, since the entry it names is in `included`. */
+type FlatTree<V> = IsRelation<V> extends true ? IsList<V> extends true ? RelationItems<EntryReference | MissingEntry> : EntryReference | MissingEntry | null : ValueTree<V>;
+/** The fields a select names at its root: every field for none, `*`, a string or `Select<T>`. */
+type NamedKeys<T, S> = [S] extends [undefined] ? keyof T : S extends ReadonlyArray<infer I> ? Select<T> extends S ? keyof T : "*" extends I ? keyof T : Extract<keyof T, I | ExpandedIn<I>> : keyof T;
+/** `fields` of an entry in a `shape=flat` read's `data`. */
+export type FlatFields<T, S = Select<T>> = string extends keyof T ? T : {
+    [K in keyof T as K extends NamedKeys<T, S> ? K : never]-?: FlatTree<T[K]>;
+};
+/**
+ * `fields` of an entry in `included`: the union of what every path that
+ * reached it selected, so any field may be absent.
+ */
+export type IncludedFields<I> = I extends unknown ? string extends keyof I ? I : {
+    [K in keyof I]?: FlatTree<I[K]>;
+} : never;
+/**
+ * Where a flat result keeps the model and select it was read with, for
+ * `inflate` to type the tree it returns. A symbol, never a field, and never a
+ * runtime value.
+ */
+declare const flatRead: unique symbol;
+export type { flatRead };
+export interface FlatRead<T, S> {
+    readonly [flatRead]?: {
+        model: T;
+        select: S;
+    };
+}

package/dist/next/entry-fields.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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;