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

package/README.md

@@ -75,6 +75,52 @@ await capa.entries.list("articles", {
 Unknown filter operators throw a local `TypeError` before any request is sent.
 Per-call `{ signal }` is forwarded to `fetch`.
 
+### Flat responses: each related entry once
+
+By default an expanded relation is nested where you selected it, so twenty
+articles by one author carry that author twenty times. Pass `shape: "flat"` and
+every relation comes back as a `{ id, model }` reference, with each expanded
+entry once in `included`, keyed by model namespace and then id:
+
+```ts
+const select = ["title", { author: ["name"] }] as const satisfies Select<Article>;
+const flat = await capa.entries.list<Article, typeof select>("articles", {
+  select,
+  shape: "flat",
+});
+
+flat.data[0].fields.author;             // { id: "…", model: "authors" }
+flat.included.authors[authorId].fields; // { name: "Ada Vale" }, typed as Author
+```
+
+`included` is typed by the select: the union of the entry types it expands, at
+any depth. A select written as a plain string types it as
+`Record<string, unknown>`. `get` takes `shape: "flat"` the same way.
+`iterate` reads the tree shape only.
+
+`inflate` turns a flat result back into the tree result, deep-equal to what the
+same request without `shape` returns:
+
+```ts
+import { inflate } from "@capacms/sdk/next";
+
+const tree = inflate(flat); // { data, page, meta, cacheTags }, no included
+```
+
+- It walks the select the request sent. A result from this client carries it
+  (`flat.select`); for a body you fetched yourself, pass it:
+  `inflate(body, "title,author(name)")`.
+- It returns copies. The same author under twenty articles is twenty equal,
+  independent objects, as when a tree body is parsed. The input is not changed.
+- Cycles end where the select ends: `a` related to `b` related to `a` is
+  inflated to the depth you wrote and no further.
+- An entry reached by two paths holds the union of what they selected, and one
+  value per field. If two paths expand the same array relation with different
+  `limit` or `sort`, the first one wins, and `inflate` cannot tell them apart.
+  Every other request round-trips exactly.
+- In edit mode, included entries are marked, and so is every copy `inflate`
+  makes of them.
+
 ### Errors
 
 ```ts
@@ -192,6 +238,15 @@ const capa = createClient({ baseUrl, apiKey, version: "2026-10-01" });
 const posts = await capa.entries.list("articles", { page: routeOf(import.meta.url) });
 ```
 
+Send `path` beside it, the concrete path being rendered, and Capa can list the
+real URLs an entry appears on, not only the route patterns:
+
+```ts
+await capa.entries.list("articles", { page: "/blog/[slug]", path: `/blog/${slug}` });
+```
+
+`path` goes out as `Capa-Path`, only when `page` is also set.
+
 `routeOf` turns a Next route file into the page string: `/blog/[slug]`. It
 drops route groups `(marketing)`, parallel slots `@modal`, the leaf file name
 and the extension. Write the string out by hand if you prefer; `routeOf` exists
@@ -341,22 +396,86 @@ editor sees the path without a link to open it.
 
 ## Live preview
 
+### Quick start (Next.js)
+
+Set `CAPA_API_URL`, `CAPA_KEY` (`cap_live_`) and `CAPA_DRAFT_KEY` (`cap_test_`), then:
+
+```ts
+// middleware.ts
+import { NextResponse } from "next/server";
+import { capaMiddleware } from "@capacms/sdk/nextjs";
+export const middleware = capaMiddleware({ NextResponse });
+
+// app/api/capa/preview/route.ts  (and exit/route.ts with exitPreviewRoute)
+import { draftMode } from "next/headers";
+import { redirect } from "next/navigation";
+import { createPreviewRoute } from "@capacms/sdk/nextjs";
+export const GET = createPreviewRoute({ draftMode, redirect });
+
+// in a page: getCapaClient({ draftMode, headers }), then <h1 {...fieldAttrs(post).title}>
+```
+
+In Capa, set the project's preview URL to your site. Add the overlay from step 2
+below and editors can click your page. The sections below explain each piece.
+
 The Capa editor can show your site beside the form: focus a field and its spot
 on the page is outlined, click the page and the editor jumps to the field, save
 and the draft re-renders in place. It needs three things on your side. A
 complete, runnable example is `examples/sdk-demo` in this repository.
 
-### 1. Tag what an editor can click
+### 1. Turn on edit mode and tag what an editor can click
+
+Edit mode is on when Next draft mode is on, or when the request carries a
+`capa-edit` token the Capa editor's Published view sends. Work it out once per
+request and build the client with it:
+
+```ts
+// lib/capa.ts
+import { draftMode, headers } from "next/headers";
+import { createClient } from "@capacms/sdk/next";
+import { editMode } from "@capacms/sdk/nextjs";
+
+export async function capa() {
+  const draft = (await draftMode()).isEnabled;
+  return createClient({
+    baseUrl, version: "2026-10-01",
+    apiKey: draft ? process.env.CAPA_DRAFT_KEY! : process.env.CAPA_KEY!,
+    editMode: await editMode({ draftMode, headers }),
+  });
+}
+```
 
-`capaAttrs(entry, field, enabled)` from `@capacms/sdk/next` returns the two
-attributes the overlay looks for. `field` is the field's namespace, which is its
-key in `entry.fields`, and it autocompletes when the entry is typed. Pass the
-draft flag as `enabled` so a published page ships no entry ids.
+Then tag fields with `capaAttrs(entry, field)` from `@capacms/sdk/next`. `field`
+is the field's namespace, its key in `entry.fields`, and it autocompletes when
+the entry is typed. There is no flag to pass: an entry read by an edit-mode
+client carries a hidden mark (related entries too), and `capaAttrs` tags only
+marked entries. A visitor's page therefore ships no `data-capa-` attributes.
 
 ```tsx
 import { capaAttrs } from "@capacms/sdk/next";
 
-<h1 {...capaAttrs(article, "title", isDraft)}>{article.fields.title}</h1>
+<h1 {...capaAttrs(article, "title")}>{article.fields.title}</h1>
+```
+
+The mark does not survive a spread copy or being passed to a client component,
+so tag in the server component that read the entry. `capaAttrs(entry, field,
+true)` still forces the tags on and `false` forces them off.
+
+To accept `capa-edit`, verify it in middleware. The token is checked with Capa,
+any forged `x-capa-edit` header is removed, and edit-mode responses are marked
+`private, no-store`:
+
+```ts
+// middleware.ts
+import { NextResponse, type NextRequest } from "next/server";
+import { resolveEditRequest } from "@capacms/sdk/nextjs";
+
+export async function middleware(request: NextRequest) {
+  const edit = await resolveEditRequest(request, publishedClient());
+  const response = NextResponse.next({ request: { headers: edit.headers } });
+  if (edit.cacheControl) response.headers.set("Cache-Control", edit.cacheControl);
+  return response;
+}
 ```
 
 ### 2. Start the overlay in draft mode
@@ -375,7 +494,8 @@ export function CapaOverlay({ adminOrigins }: { adminOrigins: string[] }) {
 }
 ```
 
-Render it from your root layout only when `(await draftMode()).isEnabled`.
+Render it from your root layout only in edit mode
+(`await editMode({ draftMode, headers })`), so a visitor never downloads it.
 `startOverlay` returns a disposer and is safe to call twice. Outside a frame it
 does nothing at all, and inside one it only listens to a parent window at one of
 `adminOrigins`. Without `onRefresh` a save reloads the page; the scroll position

package/dist/next/attrs.d.ts

@@ -1,15 +1,25 @@
 /**
  * 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>
  *
  * `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.
+ * 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 +28,32 @@ export type CapaAttrs = {
     "data-capa-entry"?: undefined;
     "data-capa-field"?: undefined;
 };
+/** `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;
 export declare function capaAttrs<T = Record<string, unknown>>(entry: {
     id: string;
     fields?: T;
 }, field: Extract<keyof T, string>, enabled?: boolean): CapaAttrs;
+/**
+ * Typed attributes for every field of one entry (M5):
+ *
+ *   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<T = Record<string, unknown>>(entry: {
+    id: string;
+    fields?: T;
+}, enabled?: boolean): {
+    readonly [K in Extract<keyof T, string>]: CapaAttrs;
+};

package/dist/next/attrs.js

@@ -1,8 +1,71 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.CAPA_EDIT = void 0;
+exports.isEditEntry = isEditEntry;
+exports.markEditEntries = markEditEntries;
 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);
+}
+function looksLikeEntry(value) {
+    return typeof value.id === "string" && typeof value.fields === "object" && value.fields !== null;
+}
+/**
+ * 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) {
+    const seen = new Set();
+    const visit = (node) => {
+        if (typeof node !== "object" || node === null || seen.has(node))
+            return;
+        seen.add(node);
+        if (Array.isArray(node)) {
+            for (const item of node)
+                visit(item);
+            return;
+        }
+        const record = node;
+        if (looksLikeEntry(record) && Object.isExtensible(record)) {
+            Object.defineProperty(record, exports.CAPA_EDIT, {
+                value: true,
+                enumerable: false,
+                configurable: true,
+            });
+        }
+        for (const key of Object.keys(record))
+            visit(record[key]);
+    };
+    visit(value);
+    return value;
+}
+function capaAttrs(entry, field, enabled = isEditEntry(entry)) {
     if (!enabled)
         return {};
     return { "data-capa-entry": entry.id, "data-capa-field": field };
 }
+/**
+ * Typed attributes for every field of one entry (M5):
+ *
+ *   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": key } : {};
+        },
+    });
+}

package/dist/next/client.d.ts

@@ -1,4 +1,4 @@
-import type { Select } from "./select-types";
+import type { ExpandedTargets, Select } from "./select-types";
 export interface CapaNextConfig {
     baseUrl: string;
     apiKey: string;
@@ -34,6 +34,21 @@ 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()`.
+     *
+     * Changes nothing on the wire. The same request is sent either way.
+     */
+    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,6 +68,12 @@ 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;
 }
 export interface Entry<T = Record<string, unknown>> {
     id: string;
@@ -97,8 +118,17 @@ 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>>>;
+/**
+ * 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>> extends CallOptions {
     select?: Select<T> | string;
+    shape?: "tree";
     filter?: Filter;
     where?: Record<string, unknown>;
     sort?: readonly string[];
@@ -109,10 +139,36 @@ export interface ListOptions<T = Record<string, unknown>> extends CallOptions {
 }
 export interface GetOptions<T = Record<string, unknown>> extends CallOptions {
     select?: Select<T> | string;
+    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.
+ */
+export type Included<I> = Record<string, Record<string, Entry<I>>>;
+interface FlatExtras<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;
 }
+export type FlatPage<T, S = Select<T>> = Page<Entry<T>> & FlatExtras<T, S>;
+export type FlatSingle<T, S = Select<T>> = Single<Entry<T>> & FlatExtras<T, S>;
 export interface EntriesResource {
+    list<T = Record<string, unknown>, S extends Select<T> | string = Select<T>>(namespace: string, options: FlatListOptions<T, S>): Promise<FlatPage<T, S>>;
     list<T = Record<string, unknown>>(namespace: string, options?: ListOptions<T>): Promise<Page<Entry<T>>>;
+    get<T = Record<string, unknown>, S extends Select<T> | string = Select<T>>(namespace: string, id: string, options: FlatGetOptions<T, S>): Promise<FlatSingle<T, S> | null>;
     get<T = Record<string, unknown>>(namespace: string, id: string, options?: GetOptions<T>): Promise<Single<Entry<T>> | null>;
+    /** Tree only: it yields entries one at a time, which is what `included` exists to avoid. */
     iterate<T = Record<string, unknown>>(namespace: string, options?: ListOptions<T>): AsyncGenerator<Entry<T>, void, undefined>;
 }
 /**

package/dist/next/client.js

@@ -5,6 +5,7 @@ exports.isCapaError = isCapaError;
 exports.resolveNextConfig = resolveNextConfig;
 exports.serializeSelect = serializeSelect;
 exports.createClient = createClient;
+const attrs_1 = require("./attrs");
 /**
  * What a `Capa-Schema` value may look like: hex, 8 to 64 characters.
  *
@@ -60,6 +61,7 @@ function resolveNextConfig(config) {
     // Checked here as well as per call, so a bad page on the config throws where
     // the client is built rather than on whichever read happens to run first.
     resolvePage(value.page, undefined);
+    resolvePath(value.path, undefined);
     // THROWS rather than dropping, the same rule `page` follows and for the same
     // reason: the API must never 400 a running site over a telemetry header, so
     // it ignores what it cannot store, and the SDK is the place a wrong value
@@ -120,6 +122,24 @@ function resolvePage(configPage, callPage) {
     }
     return value;
 }
+/**
+ * What a `Capa-Path` value may look like: a site path, query and hash cut off.
+ * COPIED from `PAGE_PATH_PATTERN` in `apps/api/src/api-next/page-header.ts`.
+ */
+const PAGE_PATH = /^\/[^\s?#]{0,1023}$/;
+function resolvePath(configPath, callPath) {
+    const value = callPath !== undefined ? callPath : configPath;
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "string") {
+        throw new TypeError(`@capacms/sdk/next: path must be a string such as "/blog/hello".`);
+    }
+    const bare = value.split("#")[0].split("?")[0];
+    if (!PAGE_PATH.test(bare)) {
+        throw new TypeError(`@capacms/sdk/next: path must be the concrete path being rendered, such as "/blog/hello". Got ${JSON.stringify(value)}.`);
+    }
+    return bare;
+}
 const NAME = /^[A-Za-z0-9_-]+$/;
 function selectName(value, context) {
     if (typeof value !== "string" || !NAME.test(value)) {
@@ -225,10 +245,21 @@ function filterValue(operator, value) {
     }
     return String(value);
 }
+/** `shape` is sent only when it is `flat`, so a tree read's URL is the one it always was. */
+function shapeOf(options) {
+    const shape = options.shape;
+    if (shape === undefined || shape === "tree")
+        return undefined;
+    if (shape === "flat")
+        return "flat";
+    throw new TypeError(`@capacms/sdk/next: shape must be "tree" or "flat". Got ${JSON.stringify(shape)}.`);
+}
 function listQuery(options) {
     const query = new URLSearchParams();
     if (options.select !== undefined)
         query.set("select", serializeSelect(options.select));
+    if (shapeOf(options) === "flat")
+        query.set("shape", "flat");
     if (options.filter !== undefined) {
         for (const [path, operations] of Object.entries(options.filter)) {
             for (const [rawOperator, value] of Object.entries(operations)) {
@@ -294,7 +325,7 @@ function cacheTags(response) {
     return value.split(/\s+/).filter(Boolean);
 }
 function createRequester(config) {
-    return async function request(path, query = new URLSearchParams(), signal, page) {
+    return async function request(path, query = new URLSearchParams(), signal, page, pagePath) {
         const url = new URL(config.baseUrl + path);
         query.forEach((value, key) => url.searchParams.append(key, value));
         const headers = {
@@ -308,6 +339,8 @@ function createRequester(config) {
         // byte-identical requests to the ones it sent before this option existed.
         if (page !== undefined)
             headers["Capa-Page"] = page;
+        if (page !== undefined && pagePath !== undefined)
+            headers["Capa-Path"] = pagePath;
         // Same rule, and on EVERY call rather than only the entries reads: the
         // stamp describes the build, so a page whose only Capa call is `me()`
         // still reports which schema it was generated from.
@@ -327,24 +360,43 @@ function createRequester(config) {
             throw errorFromEnvelope(response.status, body, requestId);
         if (!body || typeof body !== "object")
             throw 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`.
+            const { data, included } = body;
+            (0, attrs_1.markEditEntries)(data);
+            if (included !== undefined)
+                (0, attrs_1.markEditEntries)(included);
+        }
         return { body: body, cacheTags: cacheTags(response) };
     };
 }
 function createClient(config) {
     const resolved = resolveNextConfig(config);
     const request = createRequester(resolved);
+    /**
+     * 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.
+     */
+    const withSelect = (result, options) => {
+        if (shapeOf(options) !== "flat" || options.select === undefined)
+            return result;
+        return { ...result, select: serializeSelect(options.select) };
+    };
     const entries = {
         async list(namespace, options = {}) {
-            const result = await request(`/api/entries/${encodeURIComponent(namespace)}`, listQuery(options), options.signal, resolvePage(resolved.page, options.page));
-            return { ...result.body, cacheTags: result.cacheTags };
+            const result = await request(`/api/entries/${encodeURIComponent(namespace)}`, listQuery(options), options.signal, resolvePage(resolved.page, options.page), resolvePath(resolved.path, options.path));
+            return withSelect({ ...result.body, cacheTags: result.cacheTags }, options);
         },
         async get(namespace, id, options = {}) {
             const query = new URLSearchParams();
             if (options.select !== undefined)
                 query.set("select", serializeSelect(options.select));
+            if (shapeOf(options) === "flat")
+                query.set("shape", "flat");
             try {
-                const result = await request(`/api/entries/${encodeURIComponent(namespace)}/${encodeURIComponent(id)}`, query, options.signal, resolvePage(resolved.page, options.page));
-                return { ...result.body, cacheTags: result.cacheTags };
+                const result = await request(`/api/entries/${encodeURIComponent(namespace)}/${encodeURIComponent(id)}`, query, options.signal, resolvePage(resolved.page, options.page), resolvePath(resolved.path, options.path));
+                return withSelect({ ...result.body, cacheTags: result.cacheTags }, options);
             }
             catch (error) {
                 if (error instanceof CapaError &&
@@ -357,6 +409,9 @@ function createClient(config) {
             }
         },
         async *iterate(namespace, options = {}) {
+            if (shapeOf(options) === "flat") {
+                throw new TypeError("@capacms/sdk/next: iterate reads the tree shape only. Use list with shape: \"flat\" and page.next.");
+            }
             let after = options.after;
             for (;;) {
                 const page = await entries.list(namespace, { ...options, after });
@@ -417,10 +472,10 @@ function createClient(config) {
             }
         },
         async me(options = {}) {
-            return (await request("/api/me", new URLSearchParams(), options.signal, resolvePage(resolved.page, options.page))).body;
+            return (await request("/api/me", new URLSearchParams(), options.signal, resolvePage(resolved.page, options.page), resolvePath(resolved.path, options.path))).body;
         },
         async versions(options = {}) {
-            return (await request("/api/versions", new URLSearchParams(), options.signal, resolvePage(resolved.page, options.page))).body;
+            return (await request("/api/versions", new URLSearchParams(), options.signal, resolvePage(resolved.page, options.page), resolvePath(resolved.path, options.path))).body;
         },
     };
 }

package/dist/next/index.d.ts

@@ -1,5 +1,7 @@
 export { CapaError, createClient, isCapaError, LAYOUT_PAGE, resolveNextConfig, serializeSelect, } from "./client";
-export { capaAttrs } from "./attrs";
+export { CAPA_EDIT, capaAttrs, fieldAttrs, isEditEntry, markEditEntries } from "./attrs";
+export { inflate } from "./inflate";
+export type { FlatResponse } from "./inflate";
 export type { CapaAttrs } from "./attrs";
-export type { CallOptions, CapaNextClient, CapaNextConfig, EntriesResource, Entry, Filter, FilterOperator, FilterScalar, FilterValue, GetOptions, ListOptions, Page, PageDetail, PageInfo, PageSummary, PagesListOptions, PagesResource, PreviewClaim, ResponseMeta, Single, } from "./client";
-export type { CapaRelation, CapaRelationList, RelationSelectOptions, Select, SelectItem, SelectSort, } from "./select-types";
+export type { CallOptions, CapaNextClient, CapaNextConfig, EntriesResource, Entry, Filter, FilterOperator, FlatGetOptions, FlatListOptions, FlatPage, FlatSingle, Included, FilterScalar, FilterValue, GetOptions, ListOptions, Page, PageDetail, PageInfo, PageSummary, PagesListOptions, PagesResource, PreviewClaim, ResponseMeta, ResponseShape, Single, } from "./client";
+export type { ExpandedTargets, CapaRelation, CapaRelationList, RelationSelectOptions, Select, SelectItem, SelectSort, } from "./select-types";

package/dist/next/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.capaAttrs = exports.serializeSelect = exports.resolveNextConfig = exports.LAYOUT_PAGE = exports.isCapaError = exports.createClient = exports.CapaError = void 0;
+exports.inflate = exports.markEditEntries = exports.isEditEntry = exports.fieldAttrs = exports.capaAttrs = exports.CAPA_EDIT = exports.serializeSelect = exports.resolveNextConfig = exports.LAYOUT_PAGE = exports.isCapaError = exports.createClient = exports.CapaError = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "CapaError", { enumerable: true, get: function () { return client_1.CapaError; } });
 Object.defineProperty(exports, "createClient", { enumerable: true, get: function () { return client_1.createClient; } });
@@ -9,4 +9,10 @@ Object.defineProperty(exports, "LAYOUT_PAGE", { enumerable: true, get: function
 Object.defineProperty(exports, "resolveNextConfig", { enumerable: true, get: function () { return client_1.resolveNextConfig; } });
 Object.defineProperty(exports, "serializeSelect", { enumerable: true, get: function () { return client_1.serializeSelect; } });
 var attrs_1 = require("./attrs");
+Object.defineProperty(exports, "CAPA_EDIT", { enumerable: true, get: function () { return attrs_1.CAPA_EDIT; } });
 Object.defineProperty(exports, "capaAttrs", { enumerable: true, get: function () { return attrs_1.capaAttrs; } });
+Object.defineProperty(exports, "fieldAttrs", { enumerable: true, get: function () { return attrs_1.fieldAttrs; } });
+Object.defineProperty(exports, "isEditEntry", { enumerable: true, get: function () { return attrs_1.isEditEntry; } });
+Object.defineProperty(exports, "markEditEntries", { enumerable: true, get: function () { return attrs_1.markEditEntries; } });
+var inflate_1 = require("./inflate");
+Object.defineProperty(exports, "inflate", { enumerable: true, get: function () { return inflate_1.inflate; } });

package/dist/next/inflate.d.ts

@@ -0,0 +1,33 @@
+/** The flat body, or an SDK result wrapping one. */
+export interface FlatResponse {
+    data: unknown;
+    included: Record<string, Record<string, unknown>>;
+    /** The select the request sent, when the SDK made it. */
+    select?: string;
+}
+/** One level of a select: `*` or not, and the names it wrote, in order. */
+interface Level {
+    star: boolean;
+    items: Array<{
+        name: string;
+        expand: Level | null;
+    }>;
+}
+/**
+ * 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.
+ */
+export declare function parseSelectLevels(select: string): Level;
+/**
+ * The tree shape of a flat response: `data` with every expansion nested back
+ * in, `included` and `select` removed, everything else (`page`, `meta`,
+ * `cacheTags`) carried over as it was.
+ *
+ * `select` is what the request sent; it defaults to `response.select`, which
+ * an SDK flat read fills in. A request with no select expanded nothing.
+ */
+export declare function inflate<R extends FlatResponse>(response: R, select?: string): Omit<R, "included" | "select">;
+export {};

package/dist/next/inflate.js

@@ -0,0 +1,229 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSelectLevels = parseSelectLevels;
+exports.inflate = inflate;
+/**
+ * inflate.ts — turn a `shape=flat` response back into the `shape=tree` one.
+ *
+ * A flat response carries every expanded entry once, in `included`, keyed by
+ * model namespace and then id, and every relation as a `{ id, model }`
+ * reference. `inflate` walks the SAME select the request sent and puts each
+ * referenced entry back where the tree would have nested it, holding exactly
+ * the system keys and fields that path selected. The result is deep-equal to
+ * the `shape=tree` body for the same request (amendment 16 of the api-next spec
+ * names the one exception).
+ *
+ * WHY IT NEEDS THE SELECT. An included entry holds the UNION of every path that
+ * reached it, and an entry in `data` also carries what any relation path asked
+ * of it. Only the select says which of those fields belong at which place in
+ * the tree, and which references were expanded. A result from this SDK's
+ * `shape: "flat"` read carries the select it sent (`response.select`), so
+ * `inflate(response)` is enough; for a body fetched by hand, pass the select
+ * you sent as the second argument. A request that sent no select expanded
+ * nothing, and `inflate` returns its data unchanged.
+ *
+ * COPIES, NEVER SHARED INSTANCES. Every entry in the result is a new object,
+ * and so is every value inside it: the same author reached from twenty
+ * articles comes back as twenty equal, independent objects, exactly as the
+ * tree response parses. Mutating one never changes another, the input is never
+ * modified, and `JSON.stringify` of the result cannot meet a cycle.
+ *
+ * CYCLES END WHERE THE SELECT ENDS. `a` related to `b` related to `a` is
+ * inflated to the depth the select wrote (at most four levels, the API's cap)
+ * and no further: the walk follows the select, never the references, so it
+ * 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 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.
+ */
+function parseSelectLevels(select) {
+    let pos = 0;
+    const fail = () => {
+        throw new TypeError(`@capacms/sdk/next: inflate could not read the select ${JSON.stringify(select)}.`);
+    };
+    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);
+            if (select[pos] === "(") {
+                if (token === "")
+                    fail();
+                pos += 1;
+                const inner = level();
+                if (select[pos] !== ")")
+                    fail();
+                pos += 1;
+                out.items.push({ name: token, expand: inner });
+            }
+            else if (token === "*") {
+                out.star = true;
+            }
+            else if (token.includes(":")) {
+                // A modifier: `limit:2`, `sort:-name`, `after:<cursor>`.
+            }
+            else if (token !== "") {
+                out.items.push({ name: token, expand: null });
+            }
+            else {
+                fail();
+            }
+            if (select[pos] !== ",")
+                return out;
+            pos += 1;
+        }
+    };
+    const root = level();
+    if (pos !== select.length)
+        fail();
+    return root;
+}
+// ----------------------------------------------------------------- walk ----
+function clone(value) {
+    if (Array.isArray(value))
+        return value.map(clone);
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [key, inner] of Object.entries(value))
+            out[key] = clone(inner);
+        return out;
+    }
+    return value;
+}
+function isReference(value) {
+    return (!!value &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        typeof value.id === "string" &&
+        !("fields" in value));
+}
+function resolve(index, ref) {
+    if (ref.missing)
+        return null;
+    const fromIncluded = ref.model ? index.included[ref.model]?.[ref.id] : undefined;
+    if (fromIncluded && typeof fromIncluded === "object")
+        return fromIncluded;
+    return index.data.get(ref.id) ?? null;
+}
+/**
+ * One entry as the tree holds it at a place whose select is `level`. `null`
+ * is "no select was sent", which is every key and every field, unexpanded.
+ */
+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.
+    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))
+                wanted.add(item.name);
+        }
+    }
+    const out = {};
+    for (const key of SYSTEM_KEYS) {
+        if (!(key in entry))
+            continue;
+        if (all || wanted.has(key))
+            out[key] = clone(entry[key]);
+    }
+    const expansions = new Map();
+    const names = [];
+    if (level) {
+        for (const item of level.items) {
+            if (item.expand)
+                expansions.set(item.name, item.expand);
+            if (item.name in fields && !all)
+                names.push(item.name);
+        }
+    }
+    if (all)
+        names.push(...Object.keys(fields));
+    const outFields = {};
+    for (const name of names) {
+        const expand = expansions.get(name);
+        outFields[name] = expand ? expandValue(fields[name], expand, index) : clone(fields[name]);
+    }
+    out.fields = outFields;
+    if ((0, attrs_1.isEditEntry)(entry)) {
+        Object.defineProperty(out, attrs_1.CAPA_EDIT, { value: true, enumerable: false, configurable: true });
+    }
+    return out;
+}
+/** A reference, or an array relation's `{ items, pageInfo }`, put back in place. */
+function expandValue(value, level, index) {
+    if (isReference(value)) {
+        const target = resolve(index, value);
+        return target ? project(target, level, index) : clone(value);
+    }
+    if (value && typeof value === "object" && Array.isArray(value.items)) {
+        const list = value;
+        const out = {};
+        for (const [key, inner] of Object.entries(list)) {
+            out[key] =
+                key === "items"
+                    ? list.items.map((item) => expandValue(item, level, index))
+                    : clone(inner);
+        }
+        return out;
+    }
+    return clone(value);
+}
+/**
+ * The tree shape of a flat response: `data` with every expansion nested back
+ * in, `included` and `select` removed, everything else (`page`, `meta`,
+ * `cacheTags`) carried over as it was.
+ *
+ * `select` is what the request sent; it defaults to `response.select`, which
+ * an SDK flat read fills in. A request with no select expanded nothing.
+ */
+function inflate(response, select) {
+    if (!response || typeof response !== "object" || !("included" in response)) {
+        throw new TypeError("@capacms/sdk/next: inflate takes a shape=flat response, which carries included.");
+    }
+    const text = select ?? response.select;
+    const level = text === undefined || text === null ? null : parseSelectLevels(text);
+    const rows = Array.isArray(response.data) ? response.data : [response.data];
+    const index = { included: response.included ?? {}, data: new Map() };
+    for (const row of rows) {
+        if (row && typeof row === "object" && typeof row.id === "string") {
+            index.data.set(row.id, row);
+        }
+    }
+    const inflateRow = (row) => row && typeof row === "object" ? project(row, level, index) : row;
+    const out = {};
+    for (const [key, value] of Object.entries(response)) {
+        if (key === "included" || key === "select")
+            continue;
+        if (key === "data") {
+            out.data = Array.isArray(value) ? value.map(inflateRow) : inflateRow(value);
+        }
+        else {
+            out[key] = value;
+        }
+    }
+    return out;
+}

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

@@ -36,4 +36,21 @@ export type SelectItem<T> = "*" | ScalarKeys<T> | {
 }[RelationKeys<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>>];
+type ValueTargets<R, V, D extends number> = V extends "*" ? never : V extends {
+    select: infer S;
+} ? ExpandedTargetsAt<R, S, D> : ExpandedTargetsAt<R, V, D>;
+type ExpandedTargetsAt<T, S, D extends number> = S extends ReadonlyArray<infer I> ? ItemTargets<T, I, D> : never;
+/**
+ * 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.
+ */
+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/nextjs/index.d.ts

@@ -52,3 +52,177 @@ export declare function preview(token: string, client: CapaNextClient): Promise<
 export declare function pagesFor(client: CapaNextClient): PagesResource;
 export { LAYOUT_PAGE };
 export type { PreviewClaim };
+/**
+ * The query parameter that turns edit mode on for one request without draft
+ * content: `?capa-edit=<token>`, where the token is a Capa preview token. The
+ * Capa editor's Published view sends it so the published page is still
+ * clickable. It never switches the site to draft data.
+ */
+export declare const EDIT_PARAM = "capa-edit";
+/**
+ * The request header `resolveEditRequest` sets once a `capa-edit` token has
+ * been verified, for `editMode()` to read. Any copy a browser sent is removed
+ * first, so it cannot be forged from outside.
+ */
+export declare const EDIT_HEADER = "x-capa-edit";
+/** The cookie Next's `draftMode().enable()` sets. */
+export declare const DRAFT_COOKIE = "__prerender_bypass";
+/** What every edit-mode response must send: never cached, never shared. */
+export declare const EDIT_CACHE_CONTROL = "private, no-store";
+interface HeaderReader {
+    get(name: string): string | null;
+}
+/**
+ * Whether this request renders in edit mode: Next draft mode is on, or the
+ * request carried a verified `capa-edit` token (see `resolveEditRequest`).
+ *
+ * Pass Next's own functions; this package imports nothing from `next`:
+ *
+ *   import { draftMode, headers } from "next/headers";
+ *   const edit = await editMode({ draftMode, headers });
+ *   const client = createClient({ ...config, editMode: edit });
+ *
+ * A client built with `editMode: edit` marks what it reads, and `capaAttrs`
+ * then tags those entries and only those.
+ */
+export declare function editMode(input: {
+    draftMode: () => {
+        isEnabled: boolean;
+    } | Promise<{
+        isEnabled: boolean;
+    }>;
+    headers: () => HeaderReader | Promise<HeaderReader>;
+}): Promise<boolean>;
+export interface EditRequest {
+    /** True when the page must render in edit mode. */
+    edit: boolean;
+    /** True when a `capa-edit` token was presented and Capa accepted it. */
+    verified: boolean;
+    /**
+     * The request headers to forward: `x-capa-edit` removed, then set to `1`
+     * when the token verified. Hand them to `NextResponse.next({ request: { headers } })`.
+     */
+    headers: Headers;
+    /** `EDIT_CACHE_CONTROL` in edit mode, otherwise null. Set it on the response. */
+    cacheControl: string | null;
+}
+/**
+ * The middleware half of edit mode.
+ *
+ *   export async function middleware(request: NextRequest) {
+ *     const edit = await resolveEditRequest(request, publishedClient());
+ *     const response = NextResponse.next({ request: { headers: edit.headers } });
+ *     if (edit.cacheControl) response.headers.set("Cache-Control", edit.cacheControl);
+ *     return response;
+ *   }
+ *
+ * The token is checked with Capa (`client.preview`), exactly as a preview link
+ * is: the site never holds the signing key. A bad, expired or unverifiable
+ * token means not in edit mode; it never throws, because a broken edit link
+ * must still render the public page.
+ */
+export declare function resolveEditRequest(request: {
+    url: string | URL;
+    headers: Headers;
+    cookies?: {
+        has(name: string): boolean;
+    };
+}, client: Pick<CapaNextClient, "preview">): Promise<EditRequest>;
+/** Where the env-driven helpers read their settings (M6). */
+export declare const CAPA_ENV: {
+    readonly baseUrl: "CAPA_API_URL";
+    readonly apiKey: "CAPA_KEY";
+    readonly draftKey: "CAPA_DRAFT_KEY";
+    readonly version: "CAPA_API_VERSION";
+};
+export declare const DEFAULT_API_VERSION = "2026-10-01";
+type DraftModeFn = () => {
+    isEnabled: boolean;
+    enable?: () => void;
+    disable?: () => void;
+} | Promise<{
+    isEnabled: boolean;
+    enable?: () => void;
+    disable?: () => void;
+}>;
+/** The published-key client from env: what verifying a token needs. */
+export declare function getPublishedClient(overrides?: Partial<CapaNextConfig>): CapaNextClient;
+/**
+ * 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 });
+ */
+export declare function getCapaClient(input: {
+    draftMode: DraftModeFn;
+    headers: () => HeaderReader | Promise<HeaderReader>;
+    config?: Partial<CapaNextConfig>;
+}): Promise<CapaNextClient>;
+/** Only a path on this site: never `//elsewhere.example` or a full URL. */
+export declare function safeSitePath(value: string | null | undefined): string;
+/**
+ * `app/api/capa/preview/route.ts`:
+ *
+ *   import { draftMode } from "next/headers";
+ *   import { redirect } from "next/navigation";
+ *   export const GET = createPreviewRoute({ draftMode, redirect });
+ *
+ * Checks the token with Capa (the site never holds the signing key), turns
+ * draft mode on and lands on the entry's page. A bad or expired token lands on
+ * the page without draft mode and `?preview=expired`; Capa unreachable gives
+ * `?preview=unavailable`.
+ */
+export declare function createPreviewRoute(input: {
+    draftMode: DraftModeFn;
+    redirect: (url: string) => never | void;
+    client?: () => Pick<CapaNextClient, "preview">;
+    /** Runs after draft mode is enabled, before the redirect (cookie tweaks). */
+    onEnable?: () => void | Promise<void>;
+}): (request: Request) => Promise<Response | void>;
+/** `app/api/capa/exit/route.ts`: `export const GET = exitPreviewRoute({ draftMode, redirect });` */
+export declare function exitPreviewRoute(input: {
+    draftMode: DraftModeFn;
+    redirect: (url: string) => never | void;
+}): (request: Request) => Promise<Response | void>;
+interface MiddlewareRequest {
+    url: string;
+    headers: Headers;
+    nextUrl: URL & {
+        clone(): URL;
+    };
+    cookies: {
+        getAll(): Array<{
+            name: string;
+            value: string;
+        }>;
+    };
+}
+interface NextResponseLike {
+    next(init?: {
+        request?: {
+            headers?: Headers;
+        };
+    }): {
+        headers: Headers;
+    };
+    rewrite(url: URL): unknown;
+}
+/**
+ * `middleware.ts` in one line:
+ *
+ *   import { NextResponse } from "next/server";
+ *   export const middleware = capaMiddleware({ NextResponse });
+ *
+ * - `?capa-preview=<token>` on any page goes to `previewRoute`, which turns
+ *   draft mode on and comes back;
+ * - `?capa-view=published` renders without the draft cookie, for the editor's
+ *   Published view;
+ * - `?capa-edit=<token>` turns edit mode on (ids and overlay, published data);
+ * - every edit-mode response is `private, no-store`.
+ */
+export declare function capaMiddleware(input: {
+    NextResponse: NextResponseLike;
+    previewRoute?: string;
+    client?: () => Pick<CapaNextClient, "preview">;
+}): (request: MiddlewareRequest) => Promise<unknown>;

package/dist/nextjs/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LAYOUT_PAGE = void 0;
+exports.DEFAULT_API_VERSION = exports.CAPA_ENV = exports.EDIT_CACHE_CONTROL = exports.DRAFT_COOKIE = exports.EDIT_HEADER = exports.EDIT_PARAM = exports.LAYOUT_PAGE = void 0;
 exports.withCache = withCache;
 exports.tagsFor = tagsFor;
 exports.revalidateFromWebhook = revalidateFromWebhook;
@@ -8,6 +8,14 @@ exports.draftClient = draftClient;
 exports.routeOf = routeOf;
 exports.preview = preview;
 exports.pagesFor = pagesFor;
+exports.editMode = editMode;
+exports.resolveEditRequest = resolveEditRequest;
+exports.getPublishedClient = getPublishedClient;
+exports.getCapaClient = getCapaClient;
+exports.safeSitePath = safeSitePath;
+exports.createPreviewRoute = createPreviewRoute;
+exports.exitPreviewRoute = exitPreviewRoute;
+exports.capaMiddleware = capaMiddleware;
 const next_1 = require("../next");
 Object.defineProperty(exports, "LAYOUT_PAGE", { enumerable: true, get: function () { return next_1.LAYOUT_PAGE; } });
 /** Add Next.js fetch-cache options without importing `next/*`. */
@@ -192,3 +200,217 @@ async function preview(token, client) {
 function pagesFor(client) {
     return client.pages;
 }
+// -------------------------------------------------------------- edit mode ---
+/**
+ * The query parameter that turns edit mode on for one request without draft
+ * content: `?capa-edit=<token>`, where the token is a Capa preview token. The
+ * Capa editor's Published view sends it so the published page is still
+ * clickable. It never switches the site to draft data.
+ */
+exports.EDIT_PARAM = "capa-edit";
+/**
+ * The request header `resolveEditRequest` sets once a `capa-edit` token has
+ * been verified, for `editMode()` to read. Any copy a browser sent is removed
+ * first, so it cannot be forged from outside.
+ */
+exports.EDIT_HEADER = "x-capa-edit";
+/** The cookie Next's `draftMode().enable()` sets. */
+exports.DRAFT_COOKIE = "__prerender_bypass";
+/** What every edit-mode response must send: never cached, never shared. */
+exports.EDIT_CACHE_CONTROL = "private, no-store";
+/**
+ * Whether this request renders in edit mode: Next draft mode is on, or the
+ * request carried a verified `capa-edit` token (see `resolveEditRequest`).
+ *
+ * Pass Next's own functions; this package imports nothing from `next`:
+ *
+ *   import { draftMode, headers } from "next/headers";
+ *   const edit = await editMode({ draftMode, headers });
+ *   const client = createClient({ ...config, editMode: edit });
+ *
+ * A client built with `editMode: edit` marks what it reads, and `capaAttrs`
+ * then tags those entries and only those.
+ */
+async function editMode(input) {
+    const [draft, headers] = await Promise.all([input.draftMode(), input.headers()]);
+    return draft.isEnabled === true || headers.get(exports.EDIT_HEADER) === "1";
+}
+/**
+ * The middleware half of edit mode.
+ *
+ *   export async function middleware(request: NextRequest) {
+ *     const edit = await resolveEditRequest(request, publishedClient());
+ *     const response = NextResponse.next({ request: { headers: edit.headers } });
+ *     if (edit.cacheControl) response.headers.set("Cache-Control", edit.cacheControl);
+ *     return response;
+ *   }
+ *
+ * The token is checked with Capa (`client.preview`), exactly as a preview link
+ * is: the site never holds the signing key. A bad, expired or unverifiable
+ * token means not in edit mode; it never throws, because a broken edit link
+ * must still render the public page.
+ */
+async function resolveEditRequest(request, client) {
+    const headers = new Headers(request.headers);
+    headers.delete(exports.EDIT_HEADER);
+    const token = new URL(String(request.url)).searchParams.get(exports.EDIT_PARAM);
+    let verified = false;
+    if (token) {
+        try {
+            verified = (await client.preview(token)) !== null;
+        }
+        catch {
+            verified = false;
+        }
+    }
+    if (verified)
+        headers.set(exports.EDIT_HEADER, "1");
+    const draft = request.cookies?.has(exports.DRAFT_COOKIE) ??
+        (headers.get("cookie") ?? "").split(/;\s*/).some((c) => c.startsWith(`${exports.DRAFT_COOKIE}=`));
+    const edit = verified || draft;
+    return { edit, verified, headers, cacheControl: edit ? exports.EDIT_CACHE_CONTROL : null };
+}
+// ------------------------------------------------- five-minute integration ---
+/** Where the env-driven helpers read their settings (M6). */
+exports.CAPA_ENV = {
+    baseUrl: "CAPA_API_URL",
+    apiKey: "CAPA_KEY",
+    draftKey: "CAPA_DRAFT_KEY",
+    version: "CAPA_API_VERSION",
+};
+exports.DEFAULT_API_VERSION = "2026-10-01";
+function readEnv(name) {
+    const env = globalThis.process?.env;
+    const value = env?.[name];
+    return value === undefined || value === "" ? undefined : value;
+}
+function requireEnv(name) {
+    const value = readEnv(name);
+    if (!value)
+        throw new Error(`@capacms/sdk/nextjs: ${name} is not set.`);
+    return value;
+}
+/** The published-key client from env: what verifying a token needs. */
+function getPublishedClient(overrides = {}) {
+    return (0, next_1.createClient)({
+        baseUrl: requireEnv(exports.CAPA_ENV.baseUrl),
+        apiKey: requireEnv(exports.CAPA_ENV.apiKey),
+        version: readEnv(exports.CAPA_ENV.version) ?? exports.DEFAULT_API_VERSION,
+        ...overrides,
+    });
+}
+/**
+ * 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 });
+ */
+async function getCapaClient(input) {
+    const draft = (await input.draftMode()).isEnabled === true;
+    const edit = await editMode({ draftMode: input.draftMode, headers: input.headers });
+    return (0, next_1.createClient)({
+        baseUrl: requireEnv(exports.CAPA_ENV.baseUrl),
+        apiKey: requireEnv(draft ? exports.CAPA_ENV.draftKey : exports.CAPA_ENV.apiKey),
+        version: readEnv(exports.CAPA_ENV.version) ?? exports.DEFAULT_API_VERSION,
+        editMode: edit,
+        ...input.config,
+    });
+}
+/** Only a path on this site: never `//elsewhere.example` or a full URL. */
+function safeSitePath(value) {
+    if (!value || !value.startsWith("/") || value.startsWith("//"))
+        return "/";
+    return value;
+}
+/**
+ * `app/api/capa/preview/route.ts`:
+ *
+ *   import { draftMode } from "next/headers";
+ *   import { redirect } from "next/navigation";
+ *   export const GET = createPreviewRoute({ draftMode, redirect });
+ *
+ * Checks the token with Capa (the site never holds the signing key), turns
+ * draft mode on and lands on the entry's page. A bad or expired token lands on
+ * the page without draft mode and `?preview=expired`; Capa unreachable gives
+ * `?preview=unavailable`.
+ */
+function createPreviewRoute(input) {
+    return async (request) => {
+        const url = new URL(request.url);
+        const token = url.searchParams.get("token") ?? url.searchParams.get("capa-preview") ?? "";
+        // Reached two ways: directly, or through the middleware's rewrite of a page
+        // URL carrying `?capa-preview=`, where Next may hand over the ORIGINAL URL.
+        // Then the page itself is the path.
+        const path = safeSitePath(url.searchParams.get("path") ?? (url.searchParams.has("capa-preview") ? url.pathname : null));
+        let claim = null;
+        let failed = false;
+        try {
+            claim = await (input.client ?? getPublishedClient)().preview(token);
+        }
+        catch {
+            failed = true;
+        }
+        const draft = await input.draftMode();
+        if (!claim) {
+            draft.disable?.();
+            return input.redirect(`${path}?preview=${failed ? "unavailable" : "expired"}`);
+        }
+        draft.enable?.();
+        await input.onEnable?.();
+        return input.redirect(safeSitePath(claim.path ?? path));
+    };
+}
+/** `app/api/capa/exit/route.ts`: `export const GET = exitPreviewRoute({ draftMode, redirect });` */
+function exitPreviewRoute(input) {
+    return async (request) => {
+        (await input.draftMode()).disable?.();
+        return input.redirect(safeSitePath(new URL(request.url).searchParams.get("path")));
+    };
+}
+/**
+ * `middleware.ts` in one line:
+ *
+ *   import { NextResponse } from "next/server";
+ *   export const middleware = capaMiddleware({ NextResponse });
+ *
+ * - `?capa-preview=<token>` on any page goes to `previewRoute`, which turns
+ *   draft mode on and comes back;
+ * - `?capa-view=published` renders without the draft cookie, for the editor's
+ *   Published view;
+ * - `?capa-edit=<token>` turns edit mode on (ids and overlay, published data);
+ * - every edit-mode response is `private, no-store`.
+ */
+function capaMiddleware(input) {
+    const previewRoute = input.previewRoute ?? "/api/capa/preview";
+    return async (request) => {
+        const token = request.nextUrl.searchParams.get("capa-preview");
+        if (token) {
+            const target = request.nextUrl.clone();
+            target.pathname = previewRoute;
+            target.search = "";
+            target.searchParams.set("token", token);
+            target.searchParams.set("path", request.nextUrl.pathname);
+            return input.NextResponse.rewrite(target);
+        }
+        const headers = new Headers(request.headers);
+        if (request.nextUrl.searchParams.get("capa-view") === "published") {
+            const cookies = request.cookies
+                .getAll()
+                .filter((cookie) => cookie.name !== exports.DRAFT_COOKIE)
+                .map((cookie) => `${cookie.name}=${encodeURIComponent(cookie.value)}`)
+                .join("; ");
+            if (cookies)
+                headers.set("cookie", cookies);
+            else
+                headers.delete("cookie");
+        }
+        // The client is built only when a token needs checking, so a missing env
+        // value cannot break every page of the site.
+        const edit = await resolveEditRequest({ url: request.url, headers }, { preview: (t) => (input.client ?? getPublishedClient)().preview(t) });
+        const response = input.NextResponse.next({ request: { headers: edit.headers } });
+        if (edit.cacheControl)
+            response.headers.set("Cache-Control", edit.cacheControl);
+        return response;
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capacms/sdk",
-  "version": "1.0.0-next.3",
+  "version": "1.0.0-next.4",
   "license": "UNLICENSED",
   "repository": {
     "type": "git",
@@ -71,6 +71,6 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "tsc -p tsconfig.json && node --test test/codegen.test.js test/client.test.js test/next-client.test.js test/nextjs.test.js test/webhooks.test.js test/attrs.test.js test/overlay.test.js && tsc -p test/types/tsconfig.consumer.json --noEmit"
+    "test": "tsc -p tsconfig.json && node --test test/codegen.test.js test/client.test.js test/next-client.test.js test/nextjs.test.js test/webhooks.test.js test/attrs.test.js test/overlay.test.js test/inflate.test.js && tsc -p test/types/tsconfig.consumer.json --noEmit"
   }
 }