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

package/dist/next/inflate.js

@@ -34,39 +34,49 @@ exports.inflate = inflate;
  * cannot loop. A reference the select did not expand stays a reference.
  */
 const attrs_1 = require("./attrs");
-/** The system keys, in the order the API prints them. */
-const SYSTEM_KEYS = [
-    "id",
-    "model",
-    "status",
-    "createdAt",
-    "updatedAt",
-    "publishedAt",
-    "version",
-    "folder",
-    "tags",
-];
+const system_keys_1 = require("./system-keys");
+const field_names_1 = require("./field-names");
 const ALWAYS_KEYS = new Set(["id", "model", "status"]);
-const SYSTEM_KEY_SET = new Set(SYSTEM_KEYS);
 /**
- * The select grammar, read only as far as `inflate` needs it: names, nesting
- * and `*`. Modifiers (`limit:`, `sort:`, `after:`) decide which rows the API
- * returned, which the response already reflects, so they are skipped. The API
- * validated the select before answering, so this parser trusts its shape and
- * throws a `TypeError` only on text it cannot split at all.
+ * The select grammar, read only as far as `inflate` needs it: names, bare or
+ * quoted (`"price.usd"`, spec 17 amendment 121), nesting and `*`. Modifiers
+ * (`limit:`, `sort:`, `after:`) decide which rows the API returned, which the
+ * response already reflects, so they are skipped. The API validated the
+ * select before answering, so this parser trusts its shape and throws a
+ * `TypeError` only on text it cannot split at all.
  */
 function parseSelectLevels(select) {
     let pos = 0;
     const fail = () => {
         throw new TypeError(`@capacms/sdk/next: inflate could not read the select ${JSON.stringify(select)}.`);
     };
+    /** The quoted name at `pos`, read back, with `pos` moved past it. */
+    const quotedAt = () => {
+        const read = (0, field_names_1.readQuoted)(select, pos);
+        if (!read)
+            return fail();
+        pos = read.end;
+        return read.name;
+    };
     const level = () => {
         const out = { star: false, items: [] };
         for (;;) {
-            const start = pos;
-            while (pos < select.length && !",()".includes(select[pos]))
-                pos += 1;
-            const token = select.slice(start, pos);
+            const quoted = select[pos] === field_names_1.NAME_QUOTE;
+            let token = "";
+            if (quoted) {
+                token = quotedAt();
+            }
+            else {
+                const start = pos;
+                // A modifier's value may quote a name too: `sort:-"zip.code"`.
+                while (pos < select.length && !",()".includes(select[pos])) {
+                    if (select[pos] === field_names_1.NAME_QUOTE)
+                        quotedAt();
+                    else
+                        pos += 1;
+                }
+                token = select.slice(start, pos);
+            }
             if (select[pos] === "(") {
                 if (token === "")
                     fail();
@@ -75,16 +85,16 @@ function parseSelectLevels(select) {
                 if (select[pos] !== ")")
                     fail();
                 pos += 1;
-                out.items.push({ name: token, expand: inner });
+                out.items.push({ name: token, expand: inner, ...(quoted ? { quoted } : {}) });
             }
-            else if (token === "*") {
+            else if (!quoted && token === "*") {
                 out.star = true;
             }
-            else if (token.includes(":")) {
+            else if (!quoted && token.includes(":")) {
                 // A modifier: `limit:2`, `sort:-name`, `after:<cursor>`.
             }
-            else if (token !== "") {
-                out.items.push({ name: token, expand: null });
+            else if (quoted || token !== "") {
+                out.items.push({ name: token, expand: null, ...(quoted ? { quoted } : {}) });
             }
             else {
                 fail();
@@ -133,18 +143,22 @@ function resolve(index, ref) {
 function project(entry, level, index) {
     const fields = (entry.fields ?? {});
     const all = level === null || level.star;
-    // A name is a FIELD when the entry has a field of that name, otherwise a
-    // system key: a model field shadows a system key of the same name (spec
-    // 3.3), and a path that selected the field is exactly what put it here.
+    // `$tags` is always the system key (spec 17, amendment 29). A plain name is
+    // a FIELD when the entry has a field of that name, otherwise a system key:
+    // a model field shadows a system key of the same name (spec 3.3), and a
+    // path that selected the field is exactly what put it here.
     const wanted = new Set(ALWAYS_KEYS);
     if (level) {
         for (const item of level.items) {
-            if (!(item.name in fields) && SYSTEM_KEY_SET.has(item.name))
+            const system = (0, system_keys_1.sigilSystemKey)(item.name);
+            if (system !== null)
+                wanted.add(system);
+            else if (!item.quoted && !(item.name in fields) && (0, system_keys_1.isSystemKey)(item.name))
                 wanted.add(item.name);
         }
     }
     const out = {};
-    for (const key of SYSTEM_KEYS) {
+    for (const key of system_keys_1.SYSTEM_KEYS) {
         if (!(key in entry))
             continue;
         if (all || wanted.has(key))

package/dist/next/key-family.d.ts

@@ -0,0 +1,34 @@
+/**
+ * key-family.ts — which keys `@capacms/sdk/next` takes, and for what.
+ *
+ * A `cap_` key is the `/api/` key: scoped, hashed at rest, and the only kind
+ * a draft preview takes, both to verify a preview token and to read drafts.
+ * Every other key is legacy, which is the API's rule
+ * (`apps/api/src/api-next/auth/key-format.ts`): the `pk_` and `sk_` keys, and
+ * the unprefixed keys older tenants were minted, all reach `/api/` with the
+ * grants their permission gives. So every read call takes them, and the first
+ * client built with one warns once per process, naming the key to mint.
+ *
+ * The `cap_` prefix is the whole rule, case-sensitive, as on the API:
+ * `CAP_live_…` is not a key Capa mints, so it is looked up as a legacy key.
+ * `@capa/mcp` applies the same rule, and both packages are tested against one
+ * vector file, `test/fixtures/key-family.json`.
+ */
+export type KeyFamily = "cap" | "legacy";
+/** The family of `apiKey`, or null for a value that is no key at all: not a string, or empty. */
+export declare function keyFamily(apiKey: unknown): KeyFamily | null;
+/** Warn about a legacy key once per process: a site builds a client per request. */
+export declare function warnLegacyKeyOnce(apiKey: string): void;
+/**
+ * Throws for a legacy key: verifying a preview token takes a `cap_` key. A
+ * value that is no key at all is `resolveNextConfig`'s to refuse, by name.
+ */
+export declare function requirePreviewKey(apiKey: string): void;
+/**
+ * Throws for a legacy key: a draft read takes a `cap_` key. `holder` names
+ * where the key came from (`CAPA_DRAFT_KEY`, `the draft config`), so the
+ * message says what to change.
+ */
+export declare function requireDraftKey(apiKey: string, holder: string): void;
+/** Forget that the warning was printed. For tests. */
+export declare function __resetKeyWarningForTests(): void;

package/dist/next/key-family.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * key-family.ts — which keys `@capacms/sdk/next` takes, and for what.
+ *
+ * A `cap_` key is the `/api/` key: scoped, hashed at rest, and the only kind
+ * a draft preview takes, both to verify a preview token and to read drafts.
+ * Every other key is legacy, which is the API's rule
+ * (`apps/api/src/api-next/auth/key-format.ts`): the `pk_` and `sk_` keys, and
+ * the unprefixed keys older tenants were minted, all reach `/api/` with the
+ * grants their permission gives. So every read call takes them, and the first
+ * client built with one warns once per process, naming the key to mint.
+ *
+ * The `cap_` prefix is the whole rule, case-sensitive, as on the API:
+ * `CAP_live_…` is not a key Capa mints, so it is looked up as a legacy key.
+ * `@capa/mcp` applies the same rule, and both packages are tested against one
+ * vector file, `test/fixtures/key-family.json`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.keyFamily = keyFamily;
+exports.warnLegacyKeyOnce = warnLegacyKeyOnce;
+exports.requirePreviewKey = requirePreviewKey;
+exports.requireDraftKey = requireDraftKey;
+exports.__resetKeyWarningForTests = __resetKeyWarningForTests;
+const LEGACY_PREFIX = /^(pk|sk)_/;
+/** The family of `apiKey`, or null for a value that is no key at all: not a string, or empty. */
+function keyFamily(apiKey) {
+    if (typeof apiKey !== "string" || apiKey === "")
+        return null;
+    return apiKey.startsWith("cap_") ? "cap" : "legacy";
+}
+function isLegacy(apiKey) {
+    return keyFamily(apiKey) === "legacy";
+}
+/**
+ * How a message names a legacy key: by its `pk_` or `sk_` prefix, and an
+ * unprefixed key by that fact alone, since every other character is the secret.
+ */
+function legacyKind(apiKey) {
+    const prefix = LEGACY_PREFIX.exec(apiKey)?.[0];
+    return prefix ? `legacy ${prefix} key` : "legacy key with no pk_ or sk_ prefix";
+}
+const MINT = "in the Capa admin under Developers > Keys.";
+let warned = false;
+/** Warn about a legacy key once per process: a site builds a client per request. */
+function warnLegacyKeyOnce(apiKey) {
+    if (warned)
+        return;
+    warned = true;
+    console.warn(`@capacms/sdk/next: this client reads with a ${legacyKind(apiKey)}. Reads work as they do with a cap_ key. ` +
+        `Draft previews need a cap_ key: mint one ${MINT}`);
+}
+/**
+ * Throws for a legacy key: verifying a preview token takes a `cap_` key. A
+ * value that is no key at all is `resolveNextConfig`'s to refuse, by name.
+ */
+function requirePreviewKey(apiKey) {
+    if (!isLegacy(apiKey))
+        return;
+    throw new TypeError(`@capacms/sdk/next: preview needs a cap_ key, and this client holds a ${legacyKind(apiKey)}. Mint a cap_ key ${MINT}`);
+}
+/**
+ * Throws for a legacy key: a draft read takes a `cap_` key. `holder` names
+ * where the key came from (`CAPA_DRAFT_KEY`, `the draft config`), so the
+ * message says what to change.
+ */
+function requireDraftKey(apiKey, holder) {
+    if (!isLegacy(apiKey))
+        return;
+    throw new TypeError(`@capacms/sdk/next: draft reads need a cap_ key, and ${holder} holds a ${legacyKind(apiKey)}. Mint a development cap_ key ${MINT}`);
+}
+/** Forget that the warning was printed. For tests. */
+function __resetKeyWarningForTests() {
+    warned = false;
+}

package/dist/next/select-types.d.ts

@@ -1,3 +1,4 @@
+import type { SortableSystemKeyName, SystemKeyName } from "./system-keys";
 /** A single relation field emitted by `capa-codegen`. */
 export type CapaRelation<T> = T & {
     readonly __capaRelation: "one";
@@ -13,14 +14,38 @@ type RelationValue = {
     readonly __capaRelation: "one" | "many";
     readonly __capaRelationTarget: unknown;
 };
+/**
+ * A field type that says nothing about the field: `unknown`, as every field
+ * of an untyped client's `Record<string, unknown>` is, or `any`, as a type
+ * inferred from a select's names is. Such a field may be a relation or not.
+ */
+type Untyped<V> = 0 extends 1 & V ? true : unknown extends V ? true : false;
+type UntypedKeys<T> = {
+    [K in StringKey<T>]-?: Untyped<T[K]> extends true ? K : never;
+}[StringKey<T>];
 type RelationKeys<T> = {
-    [K in StringKey<T>]-?: NonNullable<T[K]> extends RelationValue ? K : never;
+    [K in StringKey<T>]-?: Untyped<T[K]> extends true ? never : NonNullable<T[K]> extends RelationValue ? K : never;
 }[StringKey<T>];
 type ScalarKeys<T> = Exclude<StringKey<T>, RelationKeys<T>>;
 type RelationTarget<T> = NonNullable<T> extends {
     readonly __capaRelationTarget: infer R;
 } ? R : never;
-export type SelectSort<T> = ScalarKeys<T> | `-${ScalarKeys<T>}`;
+/**
+ * A system key by its `$` name. The API reads a plain name as the model's
+ * field first, so `$tags` is how a select or sort asks for the entry's own
+ * tags beside a field called `tags` (spec 17, amendment 29).
+ */
+export type SystemKey = `$${SystemKeyName}`;
+/** A system key the API sorts by: `$id`, `$createdAt`, `$updatedAt`, `$publishedAt`. */
+export type SortableSystemKey = `$${SortableSystemKeyName}`;
+/**
+ * A field the grammar can name: every one but a namespace starting with `$`,
+ * which is a system key's spelling (spec 17, amendment 121). `select: "*"`
+ * still returns such a field. A namespace holding `.` or `,` is named as it
+ * is (`"price.usd"`), and the client writes it quoted.
+ */
+type Nameable<K extends string> = Exclude<K, `$${string}`>;
+export type SelectSort<T> = Nameable<ScalarKeys<T>> | `-${Nameable<ScalarKeys<T>>}` | SortableSystemKey | `-${SortableSystemKey}`;
 export interface RelationSelectOptions<T> {
     select: Select<T> | "*";
     limit?: number;
@@ -31,16 +56,26 @@ export interface RelationSelectOptions<T> {
 type RelationSelect<T, K extends RelationKeys<T>> = {
     [P in K]: Select<RelationTarget<T[P]>> | "*" | RelationSelectOptions<RelationTarget<T[P]>>;
 };
-export type SelectItem<T> = "*" | ScalarKeys<T> | {
-    [K in RelationKeys<T>]: RelationSelect<T, K>;
-}[RelationKeys<T>];
+/** An expansion of a field whose type says nothing (`Untyped`): its target is read untyped too. */
+type UntypedRelationSelect<K extends string> = {
+    [P in K]: Select<Record<string, unknown>> | "*" | RelationSelectOptions<Record<string, unknown>>;
+};
+/**
+ * One item of a select: `*`, a field by name (a relation named alone is read
+ * as a reference, `{ id, model }`), a system key by its `$` name, or a
+ * relation expanded into the fields its own select names. A field whose
+ * namespace starts with `$` has no name (`Nameable`).
+ */
+export type SelectItem<T> = "*" | Nameable<ScalarKeys<T>> | Nameable<RelationKeys<T>> | SystemKey | {
+    [K in Nameable<RelationKeys<T>>]: RelationSelect<T, K>;
+}[Nameable<RelationKeys<T>>] | ([UntypedKeys<T>] extends [never] ? never : UntypedRelationSelect<UntypedKeys<T>>);
 /** A typed form of the `/api/entries` `select` grammar. */
 export type Select<T> = ReadonlyArray<SelectItem<T>>;
 type Depth = [never, 0, 1, 2, 3, 4];
 /** The target types one select item expands, and everything below them. */
 type ItemTargets<T, I, D extends number> = [D] extends [never] ? never : I extends string ? never : {
     [K in Extract<keyof I, RelationKeys<T>>]: RelationTarget<T[K]> | ValueTargets<RelationTarget<T[K]>, I[K], Depth[D]>;
-}[Extract<keyof I, RelationKeys<T>>];
+}[Extract<keyof I, RelationKeys<T>>] | ([Extract<keyof I, UntypedKeys<T>>] extends [never] ? never : Record<string, unknown>);
 type ValueTargets<R, V, D extends number> = V extends "*" ? never : V extends {
     select: infer S;
 } ? ExpandedTargetsAt<R, S, D> : ExpandedTargetsAt<R, V, D>;
@@ -49,8 +84,9 @@ type ExpandedTargetsAt<T, S, D extends number> = S extends ReadonlyArray<infer I
  * Every entry type a select EXPANDS, at any depth: what `included` can hold
  * for a `shape: "flat"` read. `[{ author: ["name"] }]` on an article is
  * `Author`; a select given as a string cannot be read by the type system and is
- * `Record<string, unknown>`. Bounded at the API's four levels, so a model that
- * relates to itself does not recurse forever.
+ * `Record<string, unknown>`. Bounded one level past the 4 relations the API
+ * reads below the root entry, so a model that relates to itself does not
+ * recurse forever.
  */
 export type ExpandedTargets<T, S> = S extends string ? Record<string, unknown> : [ExpandedTargetsAt<T, S, 4>] extends [never] ? never : ExpandedTargetsAt<T, S, 4>;
 export {};

package/dist/next/system-keys.d.ts

@@ -0,0 +1,27 @@
+/**
+ * system-keys.ts — the entry's own keys, as REST names them.
+ *
+ * Every entry REST returns carries these beside `fields`, in this order. A
+ * request names one plainly (`tags`) only where the model has no field of that
+ * name, because REST reads a plain name as the field first; `$tags` always
+ * means the system key, in `select`, `where` and `sort`, and after a hop as
+ * `author.$id` (spec 17, amendment 29). REST names no field whose namespace
+ * starts with `$` (field-names.ts), so no field is ever spelled like one.
+ */
+/** The system keys, in the order the API prints them on an entry. */
+export declare const SYSTEM_KEYS: readonly ["id", "model", "status", "createdAt", "updatedAt", "publishedAt", "version", "folder", "tags"];
+export type SystemKeyName = (typeof SYSTEM_KEYS)[number];
+/**
+ * The system keys the API sorts by, as `packages/shared`'s `SORTABLE_SYSTEM_KEYS`
+ * lists them: `$tags` is a list and `$version`, `$model`, `$status` and
+ * `$folder` are refused as sort keys.
+ */
+export declare const SORTABLE_SYSTEM_KEYS: readonly ["id", "createdAt", "updatedAt", "publishedAt"];
+export type SortableSystemKeyName = (typeof SORTABLE_SYSTEM_KEYS)[number];
+export declare function isSortableSystemKey(name: string): name is SortableSystemKeyName;
+export declare const SYSTEM_KEY_SIGIL = "$";
+export declare function isSystemKey(name: string): name is SystemKeyName;
+/** Every system key by its `$` name, for a message that lists them. */
+export declare const SYSTEM_KEY_LIST: string;
+/** The system key a `$` name spells (`$tags` is `tags`), or null for any other name. */
+export declare function sigilSystemKey(name: string): SystemKeyName | null;

package/dist/next/system-keys.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * system-keys.ts — the entry's own keys, as REST names them.
+ *
+ * Every entry REST returns carries these beside `fields`, in this order. A
+ * request names one plainly (`tags`) only where the model has no field of that
+ * name, because REST reads a plain name as the field first; `$tags` always
+ * means the system key, in `select`, `where` and `sort`, and after a hop as
+ * `author.$id` (spec 17, amendment 29). REST names no field whose namespace
+ * starts with `$` (field-names.ts), so no field is ever spelled like one.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SYSTEM_KEY_LIST = exports.SYSTEM_KEY_SIGIL = exports.SORTABLE_SYSTEM_KEYS = exports.SYSTEM_KEYS = void 0;
+exports.isSortableSystemKey = isSortableSystemKey;
+exports.isSystemKey = isSystemKey;
+exports.sigilSystemKey = sigilSystemKey;
+/** The system keys, in the order the API prints them on an entry. */
+exports.SYSTEM_KEYS = ["id", "model", "status", "createdAt", "updatedAt", "publishedAt", "version", "folder", "tags"];
+/**
+ * The system keys the API sorts by, as `packages/shared`'s `SORTABLE_SYSTEM_KEYS`
+ * lists them: `$tags` is a list and `$version`, `$model`, `$status` and
+ * `$folder` are refused as sort keys.
+ */
+exports.SORTABLE_SYSTEM_KEYS = ["id", "createdAt", "updatedAt", "publishedAt"];
+const SORTABLE_SYSTEM_KEY_SET = new Set(exports.SORTABLE_SYSTEM_KEYS);
+function isSortableSystemKey(name) {
+    return SORTABLE_SYSTEM_KEY_SET.has(name);
+}
+exports.SYSTEM_KEY_SIGIL = "$";
+const SYSTEM_KEY_SET = new Set(exports.SYSTEM_KEYS);
+function isSystemKey(name) {
+    return SYSTEM_KEY_SET.has(name);
+}
+/** Every system key by its `$` name, for a message that lists them. */
+exports.SYSTEM_KEY_LIST = exports.SYSTEM_KEYS.map((key) => `${exports.SYSTEM_KEY_SIGIL}${key}`).join(", ");
+/** The system key a `$` name spells (`$tags` is `tags`), or null for any other name. */
+function sigilSystemKey(name) {
+    if (!name.startsWith(exports.SYSTEM_KEY_SIGIL))
+        return null;
+    const key = name.slice(exports.SYSTEM_KEY_SIGIL.length);
+    return isSystemKey(key) ? key : null;
+}

package/dist/nextjs/index.d.ts

@@ -1,20 +1,55 @@
-import { LAYOUT_PAGE, type CapaNextClient, type CapaNextConfig, type PagesResource, type PreviewClaim } from "../next";
+import { gql, LAYOUT_PAGE, type CapaDocumentResult, type CapaDocuments, type CapaDocumentVariables, type CapaNextClient, type CapaNextConfig, type GraphQLCallOptions, type GraphQLResult, type NotARecordedDocument, type PagesResource, type PreviewClaim, type TypedDocument, type UntypedQuery, type VariablesThenOptions } from "../next";
 export interface CacheOptions {
     tags?: string[];
     revalidate?: number | false;
 }
 /** Add Next.js fetch-cache options without importing `next/*`. */
 export declare function withCache(fetchImpl: typeof fetch, options: CacheOptions): typeof fetch;
+/**
+ * The Next.js cache tag for every read of a model, by its namespace. A GraphQL
+ * query names its models by namespace (`articles`), not by id, so this is the
+ * tag a GraphQL read is cached under, and `revalidateFromWebhook` revalidates
+ * it when an entry of that model changes.
+ */
+export declare function modelTag(namespace: string): string;
+/**
+ * The tag `graphql()` keeps a read under when it gives a `revalidate` and no
+ * `tags`, and that `revalidateFromWebhook` revalidates on every content
+ * change: such a page is never stale after a publish, at the price of
+ * refreshing on any publish. Name the models it reads with
+ * `tagsFor({ namespace })` to refresh it only when one of those changes. A
+ * read with neither `tags` nor `revalidate` is not kept at all.
+ */
+export declare const GRAPHQL_TAG = "capa:graphql";
+/**
+ * The tag `tagsFor({ namespace })` adds beside its model tags, and that
+ * `revalidateFromWebhook` revalidates on a media event: a GraphQL read shows
+ * a file's URL and alt text whichever models it names, so editing a file in
+ * the media library refreshes it.
+ */
+export declare const MEDIA_TAG = "capa:media";
+/**
+ * Next.js cache tags for a read. `model`, `entry`, `key` and `tenant` are the
+ * API's surrogate keys (`m:`, `e:`, `k:`, `t:`), by id; `namespace` is one
+ * `capa:model:<namespace>` tag per model a GraphQL query reads, which
+ * `capa-codegen --graphql` lists as `<Name>Models`, and `MEDIA_TAG`, since
+ * the query may show a file from the media library. Each pairs with
+ * `revalidateFromWebhook`.
+ */
 export declare function tagsFor(input: {
     model?: string;
     entry?: string;
     key?: string;
     tenant?: string;
+    namespace?: string | readonly string[];
 }): string[];
 export interface WebhookPayload {
+    type?: unknown;
     data?: {
         instanceId?: unknown;
         modelId?: unknown;
+        modelNamespace?: unknown;
+        namespace?: unknown;
         [key: string]: unknown;
     };
     instanceId?: unknown;
@@ -22,17 +57,34 @@ export interface WebhookPayload {
     modelId?: unknown;
     [key: string]: unknown;
 }
-/** Revalidate the concrete entry and model identities carried by a webhook. */
+/**
+ * Revalidate every tag a webhook's entry and model can be cached under: the
+ * entry (`e:`), the model by id (`m:`) and by namespace (`capa:model:`, the
+ * tag a GraphQL read uses). The namespace is `data.modelNamespace` on
+ * `instance.published`, `instance.unpublished` and `model.published`, and
+ * `data.namespace` on the other events (docs/WEBHOOKS.md). Any of those, and
+ * a `media.` event, also revalidates `GRAPHQL_TAG`, the tag of a `graphql()`
+ * read that named no tags. A `media.` event (a file's alt text, name or
+ * visibility changed, or the file went) revalidates the file's own key
+ * (`f:<fileId>`, as REST's `Surrogate-Key` names it) and `MEDIA_TAG`, which
+ * every read tagged by namespace carries, since it may show that file.
+ */
 export declare function revalidateFromWebhook(input: {
     payload: WebhookPayload;
     revalidateTag: (tag: string) => void | Promise<void>;
 }): Promise<string[]>;
-/** Select a client using server-only draft state supplied by the caller. */
-export declare function draftClient(input: {
+/**
+ * Select a client using server-only draft state supplied by the caller. Pass
+ * codegen's `CapaQuery` to type the builder, as with `createClient`:
+ * `draftClient<CapaQuery>({ ... })`. `production` may hold the legacy key a
+ * site already has; `draft` needs a `cap_` key, and a legacy one throws a
+ * `TypeError` when draft mode selects it.
+ */
+export declare function draftClient<Q = UntypedQuery>(input: {
     production: CapaNextConfig;
     draft: CapaNextConfig;
     isDraft: () => boolean | Promise<boolean>;
-}): Promise<CapaNextClient>;
+}): Promise<CapaNextClient<Q>>;
 export declare function routeOf(file: string): string;
 /**
  * Verify a preview token from a Next route handler.
@@ -50,7 +102,7 @@ export declare function preview(token: string, client: CapaNextClient): Promise<
  * this and never hold the whole client.
  */
 export declare function pagesFor(client: CapaNextClient): PagesResource;
-export { LAYOUT_PAGE };
+export { gql, LAYOUT_PAGE };
 export type { PreviewClaim };
 /**
  * The query parameter that turns edit mode on for one request without draft
@@ -128,13 +180,19 @@ export declare function resolveEditRequest(request: {
         has(name: string): boolean;
     };
 }, client: Pick<CapaNextClient, "preview">): Promise<EditRequest>;
-/** Where the env-driven helpers read their settings (M6). */
+/**
+ * Where the env-driven helpers read their settings (M6): the one pair of
+ * names the whole product uses (the MCP server, `capa-codegen`, `capa
+ * persist`, every curl example in the API docs).
+ */
 export declare const CAPA_ENV: {
     readonly baseUrl: "CAPA_API_URL";
     readonly apiKey: "CAPA_KEY";
     readonly draftKey: "CAPA_DRAFT_KEY";
     readonly version: "CAPA_API_VERSION";
 };
+/** Older names that still work, read only when the name above is unset. */
+export declare const CAPA_ENV_ALIASES: Readonly<Record<string, string>>;
 export declare const DEFAULT_API_VERSION = "2026-10-01";
 type DraftModeFn = () => {
     isEnabled: boolean;
@@ -145,20 +203,124 @@ type DraftModeFn = () => {
     enable?: () => void;
     disable?: () => void;
 }>;
-/** The published-key client from env: what verifying a token needs. */
-export declare function getPublishedClient(overrides?: Partial<CapaNextConfig>): CapaNextClient;
+/**
+ * The published-key client from env: what verifying a token needs. `overrides`
+ * win over env, and pass codegen's `CapaQuery` to type the builder:
+ * `getPublishedClient<CapaQuery>()`.
+ */
+export declare function getPublishedClient<Q = UntypedQuery>(overrides?: Partial<CapaNextConfig>): CapaNextClient<Q>;
 /**
  * The client for this request, from env: the draft key under draft mode,
  * otherwise the published key, and `editMode` worked out for you.
  *
  *   import { draftMode, headers } from "next/headers";
- *   const capa = await getCapaClient({ draftMode, headers });
+ *   const capa = await getCapaClient<CapaQuery>({ draftMode, headers });
+ *   const { data } = await capa.graphql.query(selection, { tags: tagsFor({ namespace: "articles" }) });
+ *
+ * `CapaQuery` (from `capa-codegen --graphql`) types the builder, as with
+ * `createClient`; leave it out for an untyped client. `config` wins over env.
+ *
+ * Its REST reads are sent as `createClient` sends them, which Next does not
+ * keep. Its GraphQL reads, a document or the builder, are sent the same way
+ * unless a call gives `tags` or `revalidate`, so a publish shows up on both
+ * alike. Given either, a read is kept in Next's data cache exactly as
+ * `graphql()` keeps it: a published read with no errors, never a draft or an
+ * edit-mode page.
  */
-export declare function getCapaClient(input: {
+export declare function getCapaClient<Q = UntypedQuery>(input: {
     draftMode: DraftModeFn;
     headers: () => HeaderReader | Promise<HeaderReader>;
     config?: Partial<CapaNextConfig>;
-}): Promise<CapaNextClient>;
+    /** Next's `unstable_cache`, as `graphql()` takes it. Leave it out: Next's own is loaded. */
+    unstable_cache?: UnstableCache;
+}): Promise<CapaNextClient<Q, NextCacheOptions>>;
+/** Where a GraphQL read in Next keeps its answer: Next's data cache, as `graphql()` and `getCapaClient` keep it. */
+export interface NextCacheOptions extends GraphQLCallOptions {
+    /**
+     * Next.js cache tags to keep this read under. `tagsFor({ namespace:
+     * <Name>Models })`, with the list `capa-codegen --graphql` writes beside
+     * each document, tags it with every model the query reads, which
+     * `revalidateFromWebhook` revalidates on a publish. Given a `revalidate`
+     * and no tags, the read is kept under `GRAPHQL_TAG`, which every publish
+     * revalidates. Given neither, the read is not kept: it is sent as a REST
+     * read is, on every render.
+     */
+    tags?: string[];
+    /** Seconds to cache, `false` to cache until a tag is revalidated, or 0 not to cache. */
+    revalidate?: number | false;
+}
+export interface NextGraphQLOptions extends NextCacheOptions {
+    /**
+     * Next's `draftMode` and `headers`, to work out draft and edit mode as
+     * `getCapaClient` does: drafts under draft mode, and in edit mode every
+     * entry the query reads marked for `capaAttrs`.
+     */
+    draftMode?: DraftModeFn;
+    headers?: () => HeaderReader | Promise<HeaderReader>;
+    /**
+     * Read drafts with `CAPA_DRAFT_KEY`, uncached. Worked out from `draftMode`
+     * when that is passed; set it to decide yourself.
+     */
+    draft?: boolean;
+    /** Overrides for the env-derived client (base URL, key, version, edit mode, fetch). Each one given is not read from env. */
+    config?: Partial<CapaNextConfig>;
+    /**
+     * Next's `unstable_cache`, from `next/cache`. Leave it out: `graphql()`
+     * loads Next's own. A published read given `tags` or a `revalidate` is kept
+     * in Next's data cache only when it answered with no `errors`, under `tags`
+     * for `revalidate` seconds, or with no `revalidate` until one of its tags is
+     * revalidated. Next's fetch
+     * cache is not used for it: that cache keeps any 200, and a GraphQL error
+     * is a 200 (a root field that timed out), and in Next 15 it keeps nothing
+     * without a `revalidate`, tags or not. Pass it only to supply another.
+     */
+    unstable_cache?: UnstableCache;
+}
+/**
+ * Next's `unstable_cache` (`import { unstable_cache } from "next/cache"`),
+ * typed here so this package never imports `next/*`.
+ */
+export type UnstableCache = <T extends (...args: any[]) => Promise<any>>(cb: T, keyParts?: string[], options?: {
+    revalidate?: number | false;
+    tags?: string[];
+}) => T;
+/**
+ * GraphQL in a server component, one line, from env:
+ *
+ *   import { draftMode, headers } from "next/headers";
+ *   import { graphql, tagsFor } from "@capacms/sdk/nextjs";
+ *   import { LatestModels } from "./capa-graphql";
+ *   const LATEST = `#graphql
+ *     query Latest($first: Int) { articles(first: $first) { nodes { id model title } } }
+ *   `;
+ *   const { data } = await graphql(LATEST, { first: 5 }, { draftMode, headers, tags: tagsFor({ namespace: LatestModels }) });
+ *
+ * Once `capa-codegen --graphql` has seen the literal, `data` and the
+ * variables are typed from it, as they are for a `<Name>Document` it writes,
+ * and `LatestModels` lists the models it reads.
+ *
+ * With no `tags` and no `revalidate` a read is sent as the REST reads are,
+ * and Next keeps nothing: the page shows a publish on its next render, as a
+ * page reading by REST does. Given either, a published read is kept in Next's
+ * data cache (`unstable_cache`) when it answered with no errors: under `tags`,
+ * for `revalidate` seconds, or with no `revalidate` until
+ * `revalidateFromWebhook` revalidates one of its tags on a publish. It goes
+ * as a GET, which the CDN and the API also cache for the published key; a
+ * document too long for a GET URL goes as a POST, which only Next's data
+ * cache keeps. Under draft mode the read uses `CAPA_DRAFT_KEY`, a
+ * `cap_` key, and bypasses the cache (the API answers a development key's GET
+ * `no-store`), the same split `getCapaClient` makes for REST, and in edit mode
+ * each entry that selects `id` and `model` is marked for `capaAttrs`, uncached.
+ * Outside a Next request (a script, a test) the read is simply sent.
+ *
+ * `persisted: true` sends only the hash, and pays off once the documents are
+ * stored with `capa persist`, which takes a development key: a production
+ * key never stores one. Until then a
+ * hash misses, and the client remembers the miss for five minutes and sends
+ * the document by POST meanwhile, so it costs one extra GET per five minutes.
+ */
+export declare function graphql<D extends keyof CapaDocuments>(document: D, ...rest: VariablesThenOptions<CapaDocumentVariables<D>, NextGraphQLOptions>): Promise<GraphQLResult<CapaDocumentResult<D>>>;
+export declare function graphql<TData = Record<string, unknown>, TVariables = Record<string, unknown>, D extends string = string>(document: NotARecordedDocument<D, TypedDocument<TData, TVariables> | D>, ...rest: VariablesThenOptions<TVariables, NextGraphQLOptions>): Promise<GraphQLResult<TData>>;
 /** Only a path on this site: never `//elsewhere.example` or a full URL. */
 export declare function safeSitePath(value: string | null | undefined): string;
 /**