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

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

@@ -0,0 +1,228 @@
+/**
+ * request.ts — one GraphQL request to `/api/graphql`, and the persisted-query
+ * dance.
+ *
+ * A request the API RAN resolves, with `errors` beside whatever `data` it
+ * could produce: once execution has started a root field that failed is null
+ * and the others still carry data (G plan D5). A request the API REFUSED as a
+ * whole throws `CapaError`. GraphQL over HTTP marks the refusal by its body,
+ * `errors` and no `data`, and sends it as a 200 on `application/json`, which
+ * is what this client asks for, or as a 4xx on
+ * `application/graphql-response+json` (decision of 2026-09-25). Both throw the
+ * same error, with the 400 the API gives every refusal it moves to a 200.
+ *
+ * A read goes as a GET whenever it fits the API's URL limit, so a production
+ * key's read is cached by the CDN and the API with no option set, and as a
+ * POST when it does not: a document is never refused for its length. A host
+ * that serves GraphQL by POST only (the admin host) answers that GET as a path
+ * it does not serve; a GET the caller did not ask for is then repeated as a
+ * POST, and that host is read by POST for a few minutes.
+ *
+ * `persisted: true` sends the document's sha256 alone, as a GET, so the
+ * response is cacheable and the document never travels. Variables too long
+ * for a GET URL go with the hash in a POST instead, which the API takes the
+ * same way but never caches. When the API has not seen that hash it answers
+ * 200 with `PersistedQueryNotFound`, and the request is repeated once as a
+ * POST carrying the document and the hash.
+ *
+ * That POST stores the document only on a host that stores documents (G plan
+ * D17) and only for a development key (spec 17, amendment 28). A production key, which
+ * is the key a site ships, is answered `persistedQuery.registered: false`: the
+ * document runs, nothing is stored, and the answer carries no error. Documents
+ * are registered at build time instead (`capa persist`), and then a production
+ * key's GET by hash hits. A hash the host declined is remembered for a few
+ * minutes, so the calls in between go straight to POST instead of paying a GET
+ * that is certain to miss; the caller sees the same result either way.
+ *
+ * The API runs 4 reads at once per project, GraphQL documents and
+ * `/api/entries` reads counted together, at most 3 of them for one client of
+ * a key, and lets 64 more per client and 256 per key wait for a slot (spec
+ * 17, amendments 81, 100 and 131); past that it answers 429 with
+ * `Retry-After`. Every request here, each leg of the dances above included,
+ * is repeated after that wait, plus up to 250 ms so a burst of callers does
+ * not return in step, up to `retries` times (3 unless set; 0 throws the first
+ * 429). A wait over 30 seconds is thrown at once rather than slept through,
+ * and the caller's `signal` ends a wait early. A 429 that is thrown carries
+ * `retryAfter`.
+ */
+import { type CapaGraphQLError } from "../errors";
+/** The API's GET limit on `/api/graphql` (path plus query string). */
+export declare const GRAPHQL_GET_URL_LIMIT = 8192;
+/** The message Apollo's persisted-query link, and this client, look for. */
+export declare const PERSISTED_QUERY_NOT_FOUND = "PersistedQueryNotFound";
+/**
+ * The status of a refused request, however it was sent. Every refusal the API
+ * answers 200 on `application/json` (parse, validation, variables, budget,
+ * planner) is a 400 in its error table and on
+ * `application/graphql-response+json`, so a `CapaError` reads the same either
+ * way. 401, 402, 403, 404, 405 and 429 keep their own statuses on both.
+ */
+export declare const REFUSED_STATUS = 400;
+/**
+ * A GraphQL document whose result and variables types are known, as emitted by
+ * `capa-codegen --graphql`. At runtime it is the document string itself; the
+ * two phantom properties exist only so `client.graphql(doc, vars)` can infer
+ * both types from it.
+ */
+export type TypedDocument<TData = Record<string, unknown>, TVariables = Record<string, unknown>> = string & {
+    readonly __capaResult?: TData;
+    readonly __capaVariables?: TVariables;
+};
+/**
+ * What follows a document in a call: its variables, then options. The
+ * variables may be left out only when the document declares no required one;
+ * a document with `$id: ID!` needs them, as Hydrogen's `storefront.query` does.
+ */
+export type VariablesThenOptions<TVariables, TOptions> = {} extends TVariables ? [variables?: NotInferred<TVariables>, options?: TOptions] : [variables: NotInferred<TVariables>, options?: TOptions];
+/**
+ * `T`, but not a place TypeScript infers `T` from: the variables' type comes
+ * from the document alone, so `undefined` passed for required variables is
+ * refused instead of widening them. (TypeScript 5.4's `NoInfer`, for older
+ * compilers too.)
+ */
+type NotInferred<T> = [T][T extends unknown ? 0 : never];
+export interface GraphQLCallOptions {
+    signal?: AbortSignal;
+    /** Which operation to run when the document holds several. */
+    operationName?: string;
+    /**
+     * Unset, a read is a `GET` whenever it fits the API's 8,192-byte URL limit,
+     * and a `POST` when it does not. A `GET` is cached by the API and the CDN for
+     * a production key; a `POST` never is. `"POST"` always sends a POST. `"GET"`
+     * sends a GET that fits and a POST that does not, as unset does, and is not
+     * repeated as a POST on a host that serves GraphQL by POST only. Ignored when
+     * `persisted` is set, which starts with a GET whenever the hash and variables
+     * fit in its URL.
+     */
+    method?: "POST" | "GET";
+    /**
+     * Send the document's hash instead of the document, as a cacheable GET. On
+     * a miss the document follows as a POST, which is stored only for a
+     * development key: register documents with `capa persist` first. See "Persisted queries" in the README.
+     */
+    persisted?: boolean;
+    /**
+     * How many times a 429 (more reads at once than the API runs and queues:
+     * 4 running per project, 3 of them per client, and 64 waiting per client or
+     * 256 per key, REST reads included) is repeated after its `Retry-After`,
+     * plus up to 250 ms. 3 unless set; 0 throws the first 429, with
+     * `retryAfter` set. A `Retry-After` over 30 seconds is always thrown.
+     */
+    retries?: number;
+}
+/** How many times a 429 is repeated unless `retries` says otherwise. */
+export declare const DEFAULT_RETRIES = 3;
+/** The longest `Retry-After` waited out; a longer one is thrown to the caller. */
+export declare const MAX_RETRY_WAIT_MS = 30000;
+/** What the API measured for this request (G plan 1.5). */
+export interface CapaGraphQLCost {
+    depth: number;
+    rootFields: number;
+    connections: number;
+    nodesBound: number;
+    /**
+     * Each `totalCount` and each filter or sort through a relation: reads of
+     * entries the answer does not hold, 500 entries each against the budget
+     * (spec 17, amendment 43).
+     */
+    scans: number;
+    nodes: number;
+    fields: number;
+}
+/**
+ * `extensions.capa`, which `/api/graphql` sends to a development key and to a
+ * request that asks for it (spec 17, amendment 119).
+ */
+export interface CapaGraphQLExtensions {
+    requestId: string;
+    version: string;
+    contract: number;
+    environment?: string;
+    cost?: CapaGraphQLCost;
+    /** The REST request each executed root field is equal to. */
+    rest?: Array<{
+        field: string;
+        url: string;
+    }>;
+    [key: string]: unknown;
+}
+/**
+ * `extensions.cost`, the query's cost as Shopify's APIs report it, in entries.
+ * There is no per-key budget, so there is no `throttleStatus`.
+ */
+export interface GraphQLQueryCost {
+    /**
+     * The most the query could cost: the entries it could return, each nested
+     * list at its `first` (100 without one), capped at 5,000, plus 500 for each
+     * of its `scans`. Not what the limit checks: read `budget.counted` for that.
+     */
+    requestedQueryCost: number;
+    /** What it did read, plus 500 for each scan that ran; never above `requestedQueryCost`. */
+    actualQueryCost: number;
+    /**
+     * The figure the 5,000-entry limit is checked against before any SQL, the
+     * one to watch: a nested list with no `first` counts 10 for each entry above
+     * it. A document is refused `query_too_complex` exactly when `counted`
+     * passes `limit`.
+     */
+    budget: {
+        counted: number;
+        limit: number;
+    };
+}
+/** One deprecated member a document used, in `extensions.deprecations` and the `Capa-Deprecated-Reason` header. */
+export interface GraphQLDeprecation {
+    /** The schema coordinate, such as `Articles._folder`. */
+    coordinate: string;
+    /** What to use instead. */
+    reason: string;
+}
+export interface GraphQLResult<TData> {
+    /** Null when no root field could be answered. */
+    data: TData | null;
+    /** Empty when the request succeeded completely. */
+    errors: CapaGraphQLError[];
+    extensions: {
+        capa?: CapaGraphQLExtensions;
+        cost?: GraphQLQueryCost;
+        /** Each deprecated member the document used, when it validated and used one. */
+        deprecations?: GraphQLDeprecation[];
+        persistedQuery?: {
+            registered: boolean;
+        };
+        [key: string]: unknown;
+    };
+    /** Parsed from `Surrogate-Key`: the tags a GET response can be purged by. */
+    cacheTags: string[];
+}
+/** What a request needs from the client's config, and nothing more. */
+export interface GraphQLTransport {
+    baseUrl: string;
+    apiKey: string;
+    version: string;
+    contract?: number;
+    schemaChecksum?: string;
+    fetchImpl: typeof fetch;
+}
+interface Payload {
+    query?: string;
+    variables?: Record<string, unknown>;
+    operationName?: string;
+    extensions?: {
+        persistedQuery: {
+            version: 1;
+            sha256Hash: string;
+        };
+    };
+}
+/** The GET form: every payload key as a query parameter, objects as JSON. */
+export declare function graphqlGetUrl(baseUrl: string, payload: Payload): string;
+/** The bytes the API counts against its GET limit (`GRAPHQL_GET_URL_LIMIT`): the path and query string. */
+export declare function graphqlGetBytes(baseUrl: string, payload: Payload): number;
+/** How long a host's `registered: false`, or its refusal of a GET, is trusted before the GET is tried again. */
+export declare const UNSTORED_TTL_MS: number;
+/** Forget every declined hash and every POST-only host. For tests. */
+export declare function __resetPersistedMemoForTests(): void;
+/** Run one document. See the file comment for what resolves and what throws. */
+export declare function runGraphQL<TData>(transport: GraphQLTransport, document: string, variables: Record<string, unknown> | undefined, options?: GraphQLCallOptions): Promise<GraphQLResult<TData>>;
+export {};

package/dist/next/graphql/request.js

@@ -0,0 +1,283 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UNSTORED_TTL_MS = exports.MAX_RETRY_WAIT_MS = exports.DEFAULT_RETRIES = exports.REFUSED_STATUS = exports.PERSISTED_QUERY_NOT_FOUND = exports.GRAPHQL_GET_URL_LIMIT = void 0;
+exports.graphqlGetUrl = graphqlGetUrl;
+exports.graphqlGetBytes = graphqlGetBytes;
+exports.__resetPersistedMemoForTests = __resetPersistedMemoForTests;
+exports.runGraphQL = runGraphQL;
+/**
+ * request.ts — one GraphQL request to `/api/graphql`, and the persisted-query
+ * dance.
+ *
+ * A request the API RAN resolves, with `errors` beside whatever `data` it
+ * could produce: once execution has started a root field that failed is null
+ * and the others still carry data (G plan D5). A request the API REFUSED as a
+ * whole throws `CapaError`. GraphQL over HTTP marks the refusal by its body,
+ * `errors` and no `data`, and sends it as a 200 on `application/json`, which
+ * is what this client asks for, or as a 4xx on
+ * `application/graphql-response+json` (decision of 2026-09-25). Both throw the
+ * same error, with the 400 the API gives every refusal it moves to a 200.
+ *
+ * A read goes as a GET whenever it fits the API's URL limit, so a production
+ * key's read is cached by the CDN and the API with no option set, and as a
+ * POST when it does not: a document is never refused for its length. A host
+ * that serves GraphQL by POST only (the admin host) answers that GET as a path
+ * it does not serve; a GET the caller did not ask for is then repeated as a
+ * POST, and that host is read by POST for a few minutes.
+ *
+ * `persisted: true` sends the document's sha256 alone, as a GET, so the
+ * response is cacheable and the document never travels. Variables too long
+ * for a GET URL go with the hash in a POST instead, which the API takes the
+ * same way but never caches. When the API has not seen that hash it answers
+ * 200 with `PersistedQueryNotFound`, and the request is repeated once as a
+ * POST carrying the document and the hash.
+ *
+ * That POST stores the document only on a host that stores documents (G plan
+ * D17) and only for a development key (spec 17, amendment 28). A production key, which
+ * is the key a site ships, is answered `persistedQuery.registered: false`: the
+ * document runs, nothing is stored, and the answer carries no error. Documents
+ * are registered at build time instead (`capa persist`), and then a production
+ * key's GET by hash hits. A hash the host declined is remembered for a few
+ * minutes, so the calls in between go straight to POST instead of paying a GET
+ * that is certain to miss; the caller sees the same result either way.
+ *
+ * The API runs 4 reads at once per project, GraphQL documents and
+ * `/api/entries` reads counted together, at most 3 of them for one client of
+ * a key, and lets 64 more per client and 256 per key wait for a slot (spec
+ * 17, amendments 81, 100 and 131); past that it answers 429 with
+ * `Retry-After`. Every request here, each leg of the dances above included,
+ * is repeated after that wait, plus up to 250 ms so a burst of callers does
+ * not return in step, up to `retries` times (3 unless set; 0 throws the first
+ * 429). A wait over 30 seconds is thrown at once rather than slept through,
+ * and the caller's `signal` ends a wait early. A 429 that is thrown carries
+ * `retryAfter`.
+ */
+const errors_1 = require("../errors");
+const sha256_1 = require("./sha256");
+/** The API's GET limit on `/api/graphql` (path plus query string). */
+exports.GRAPHQL_GET_URL_LIMIT = 8192;
+/** The message Apollo's persisted-query link, and this client, look for. */
+exports.PERSISTED_QUERY_NOT_FOUND = "PersistedQueryNotFound";
+/**
+ * The status of a refused request, however it was sent. Every refusal the API
+ * answers 200 on `application/json` (parse, validation, variables, budget,
+ * planner) is a 400 in its error table and on
+ * `application/graphql-response+json`, so a `CapaError` reads the same either
+ * way. 401, 402, 403, 404, 405 and 429 keep their own statuses on both.
+ */
+exports.REFUSED_STATUS = 400;
+/** How many times a 429 is repeated unless `retries` says otherwise. */
+exports.DEFAULT_RETRIES = 3;
+/** The longest `Retry-After` waited out; a longer one is thrown to the caller. */
+exports.MAX_RETRY_WAIT_MS = 30_000;
+/** Added to each wait, at random, so callers throttled together do not return together. */
+const RETRY_JITTER_MS = 250;
+function headersFor(transport, withBody) {
+    const headers = {
+        Accept: "application/json",
+        "x-api-key": transport.apiKey,
+        "Capa-Version": transport.version,
+    };
+    if (withBody)
+        headers["Content-Type"] = "application/json";
+    if (transport.contract !== undefined)
+        headers["Capa-Contract"] = String(transport.contract);
+    if (transport.schemaChecksum !== undefined)
+        headers["Capa-Schema"] = transport.schemaChecksum;
+    return headers;
+}
+/** The GET form: every payload key as a query parameter, objects as JSON. */
+function graphqlGetUrl(baseUrl, payload) {
+    const url = new URL(`${baseUrl}/api/graphql`);
+    if (payload.query !== undefined)
+        url.searchParams.set("query", payload.query);
+    if (payload.variables !== undefined)
+        url.searchParams.set("variables", JSON.stringify(payload.variables));
+    if (payload.operationName !== undefined)
+        url.searchParams.set("operationName", payload.operationName);
+    if (payload.extensions !== undefined)
+        url.searchParams.set("extensions", JSON.stringify(payload.extensions));
+    return url.toString();
+}
+/** The bytes the API counts against its GET limit (`GRAPHQL_GET_URL_LIMIT`): the path and query string. */
+function graphqlGetBytes(baseUrl, payload) {
+    return graphqlGetUrl(baseUrl, payload).length - baseUrl.length;
+}
+/** GraphQL over HTTP: a refused request has `errors` and no `data` entry; a body with `data`, null included, ran. */
+function refusedWhole(body, errors) {
+    return errors.length > 0 && !Object.prototype.hasOwnProperty.call(body, "data");
+}
+/** Resolves after `ms`, or rejects with the signal's reason once it aborts. */
+function pause(ms, signal) {
+    if (signal?.aborted)
+        return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal?.reason);
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/**
+ * `sendOnce`, repeated after each 429's `Retry-After` (1 second when it sent
+ * none) up to `call.retries` times. See the file comment.
+ */
+async function send(transport, wanted, payload, call) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await sendOnce(transport, wanted, payload, call.signal);
+        }
+        catch (error) {
+            if (!(error instanceof errors_1.CapaError) || error.status !== 429 || attempt >= call.retries)
+                throw error;
+            const wait = (error.retryAfter ?? 1) * 1000;
+            if (wait > exports.MAX_RETRY_WAIT_MS)
+                throw error;
+            await pause(wait + Math.random() * RETRY_JITTER_MS, call.signal);
+        }
+    }
+}
+/**
+ * One request by `wanted`, except that a GET too long for the API's URL limit
+ * goes as a POST. See the file comment for what resolves and what throws.
+ */
+async function sendOnce(transport, wanted, payload, signal) {
+    const method = wanted === "GET" && graphqlGetBytes(transport.baseUrl, payload) > exports.GRAPHQL_GET_URL_LIMIT ? "POST" : wanted;
+    const url = method === "GET" ? graphqlGetUrl(transport.baseUrl, payload) : `${transport.baseUrl}/api/graphql`;
+    const response = await transport.fetchImpl(url, {
+        method,
+        headers: headersFor(transport, method === "POST"),
+        body: method === "POST" ? JSON.stringify(payload) : undefined,
+        signal,
+    });
+    const requestId = response.headers?.get?.("X-Request-Id") ?? "";
+    const text = await response.text();
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        throw (0, errors_1.unparseable)(response.status, requestId);
+    }
+    if (response.status !== 200) {
+        throw ((0, errors_1.graphqlNotServed)(response.status, body, method, requestId) ??
+            (0, errors_1.errorFromGraphQLBody)(response.status, body, requestId, (0, errors_1.retryAfterOf)(response.headers?.get?.("Retry-After"))));
+    }
+    if (!body || typeof body !== "object")
+        throw (0, errors_1.unparseable)(response.status, requestId);
+    const object = body;
+    const errors = (0, errors_1.graphqlErrorsOf)(object.errors);
+    // PersistedQueryNotFound is a refusal too, and the one that asks for the
+    // document rather than failing: `runGraphQL` answers it with a POST.
+    if (refusedWhole(object, errors) && !persistedQueryMissing(errors)) {
+        throw (0, errors_1.errorFromGraphQLBody)(exports.REFUSED_STATUS, body, requestId);
+    }
+    const tags = response.headers?.get?.("Surrogate-Key") ?? "";
+    return {
+        data: (object.data ?? null),
+        errors,
+        extensions: object.extensions && typeof object.extensions === "object"
+            ? object.extensions
+            : {},
+        cacheTags: tags.split(/\s+/).filter(Boolean),
+    };
+}
+/** How long a host's `registered: false`, or its refusal of a GET, is trusted before the GET is tried again. */
+exports.UNSTORED_TTL_MS = 5 * 60_000;
+/** Keys remembered for `UNSTORED_TTL_MS`, at most a thousand, so a long-lived process cannot grow them without end. */
+class Remembered {
+    until = new Map();
+    has(key, now) {
+        const until = this.until.get(key);
+        if (until === undefined)
+            return false;
+        if (until > now)
+            return true;
+        this.until.delete(key);
+        return false;
+    }
+    add(key, now) {
+        if (this.until.size >= 1000)
+            this.until.clear();
+        this.until.set(key, now + exports.UNSTORED_TTL_MS);
+    }
+    clear() {
+        this.until.clear();
+    }
+}
+/** Hashes a host declined to store, per host and key. */
+const unstored = new Remembered();
+/** Hosts that answered a GET as a path they do not serve. */
+const postOnly = new Remembered();
+function unstoredKey(transport, hash) {
+    return `${transport.baseUrl}\n${transport.apiKey}\n${hash}`;
+}
+/** Forget every declined hash and every POST-only host. For tests. */
+function __resetPersistedMemoForTests() {
+    unstored.clear();
+    postOnly.clear();
+}
+function persistedQueryMissing(errors) {
+    return errors.some((error) => error.code === "persisted_query_not_found" || error.message === exports.PERSISTED_QUERY_NOT_FOUND);
+}
+/** `graphqlNotServed`'s answer to a GET: this host serves no GraphQL by GET. */
+function getNotServed(error) {
+    return error instanceof errors_1.CapaError && error.status === 404 && error.code === "route_not_found";
+}
+/**
+ * A document with its text: by the method asked for, else by GET, repeated
+ * once as a POST where the host serves GraphQL by POST only.
+ */
+async function read(transport, payload, method, call) {
+    if (method !== undefined)
+        return send(transport, method, payload, call);
+    if (postOnly.has(transport.baseUrl, Date.now()))
+        return send(transport, "POST", payload, call);
+    try {
+        return await send(transport, "GET", payload, call);
+    }
+    catch (error) {
+        if (!getNotServed(error))
+            throw error;
+        postOnly.add(transport.baseUrl, Date.now());
+        return send(transport, "POST", payload, call);
+    }
+}
+function checkInput(document, variables) {
+    if (typeof document !== "string" || document.trim() === "") {
+        throw new TypeError("@capacms/sdk/next: graphql needs a document: a non-empty GraphQL string.");
+    }
+    if (variables !== undefined && (variables === null || typeof variables !== "object" || Array.isArray(variables))) {
+        throw new TypeError("@capacms/sdk/next: graphql variables must be an object keyed by variable name.");
+    }
+}
+/** Run one document. See the file comment for what resolves and what throws. */
+async function runGraphQL(transport, document, variables, options = {}) {
+    checkInput(document, variables);
+    const retries = options.retries ?? exports.DEFAULT_RETRIES;
+    if (!Number.isInteger(retries) || retries < 0) {
+        throw new TypeError("@capacms/sdk/next: graphql retries must be a whole number, 0 or more.");
+    }
+    const call = { signal: options.signal, retries };
+    const base = { variables, operationName: options.operationName };
+    if (!options.persisted)
+        return read(transport, { query: document, ...base }, options.method, call);
+    const sha256Hash = await (0, sha256_1.sha256Hex)(document);
+    const extensions = { persistedQuery: { version: 1, sha256Hash } };
+    const post = { query: document, ...base, extensions };
+    const key = unstoredKey(transport, sha256Hash);
+    if (unstored.has(key, Date.now()))
+        return send(transport, "POST", post, call);
+    const first = await send(transport, "GET", { ...base, extensions }, call);
+    if (!persistedQueryMissing(first.errors))
+        return first;
+    const second = await send(transport, "POST", post, call);
+    if (second.extensions.persistedQuery?.registered === false)
+        unstored.add(key, Date.now());
+    return second;
+}

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

@@ -0,0 +1,66 @@
+/**
+ * rest.ts — the same read as a REST request, and back.
+ *
+ * `/api/graphql` runs every root field as the equivalent `/api/entries`
+ * request (G plan D2), so a query spec has exactly one REST twin. These two
+ * helpers write it down in each direction, so `select` and GraphQL stay
+ * interchangeable in code: `specToSelect` for "show me the REST URL of this
+ * query" (public as `graphqlToSelect`, which also takes a builder selection),
+ * `selectToGraphQL` for "port this REST read to GraphQL".
+ *
+ * Names cross the boundary through the schema summary, because GraphQL and
+ * REST name a few things differently: a field renamed by N5 (`tags_field`,
+ * `price_usd`), a relation hop (`author__name_ASC` against `author.name`), the
+ * system fields the schema prefixes with `_`, a system key a field of the
+ * model shadows, which REST writes with `$` (`$tags`, `$createdAt`,
+ * `author.$id`), and a namespace holding a character REST's grammars use,
+ * which REST writes quoted (`"price.usd"`, field-names.ts).
+ */
+import { type GraphQLQuerySpec } from "./plan";
+import type { GraphQLModelSummary, GraphQLSchemaSummary } from "./summary";
+export interface RestRequest {
+    /** `/api/entries/articles` or `/api/entries/articles/{id}`. */
+    path: string;
+    /** The `select` grammar string. */
+    select: string;
+    /** Query parameters in the order the API prints them. */
+    params: Array<[string, string]>;
+    /** `path` plus the query string, readable: commas and colons left bare. */
+    url: string;
+}
+/**
+ * A GraphQL filter input as the REST `where` object, key for key what the API
+ * prints in `extensions.capa.rest`: namespaces for field names, written as
+ * REST writes them, a hop as a dotted path after the relation's own
+ * operators, keys in the order the
+ * filter input type declares them, and null members dropped (GraphQL reads a
+ * null as "no condition").
+ */
+export declare function restWhere(summary: GraphQLSchemaSummary, model: GraphQLModelSummary, filter: Record<string, unknown>): Record<string, unknown>;
+/**
+ * The REST request a query spec is equal to, written the way the API writes
+ * it in `extensions.capa.rest`: the filter as `where` JSON, the root's default
+ * page size left out, a relation list's `first` written as `limit:` whenever
+ * the spec gives it, parameters in the API's order. Public as
+ * `graphqlToSelect`, in selection.ts.
+ */
+export declare function specToSelect(summary: GraphQLSchemaSummary, spec: GraphQLQuerySpec): RestRequest;
+/** The REST read options `selectToGraphQL` understands, as `entries.list` takes them. */
+export interface RestReadOptions {
+    /** A single-entry read. */
+    id?: string;
+    filter?: Record<string, Record<string, unknown>>;
+    where?: Record<string, unknown>;
+    sort?: readonly string[];
+    limit?: number;
+    count?: boolean;
+    after?: string;
+    before?: string;
+}
+/**
+ * The query spec a REST read is equal to. Pass it to `buildGraphQLQuery`.
+ *
+ *   selectToGraphQL(schema, "articles", "title,author(name)", { sort: ["-views"], limit: 5 })
+ *   // { model: "articles", fields: ["title", { field: "author", fields: ["name"] }], sort: ["views_DESC"], first: 5 }
+ */
+export declare function selectToGraphQL(summary: GraphQLSchemaSummary, namespace: string, select?: string, options?: RestReadOptions): GraphQLQuerySpec;