@capacms/sdk 1.0.0-next.2 → 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
@@ -199,6 +254,19 @@ so that moving a folder cannot silently split one page's telemetry in two. Set
 `page` on the config instead when a client serves exactly one page; a value on
 the call wins over one on the config.
 
+A layout is not a page. `app/layout.tsx` (and any nested `layout.*` or
+`template.*`) renders around every page below it, and Next does not tell it
+which one, so its reads cannot be charged to the page being rendered. `routeOf`
+returns `"(layout)"` for these files, exported as `LAYOUT_PAGE`, and a read that
+names it sends no `Capa-Page` header at all, even when the client was created
+with a `page`. So a Site singleton or a nav read in your root layout is simply
+not attributed, instead of making `/` look as if it read everything:
+
+```ts
+// In app/layout.tsx: same call as in a page, and no page is recorded.
+const site = await capa.entries.list("site", { page: routeOf(import.meta.url) });
+```
+
 A malformed value throws a `TypeError`. Capa itself ignores a header it cannot
 store, because a mangled page identity must never take a blog down, so the SDK
 is the place a typo surfaces.
@@ -328,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
@@ -362,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>;
 }
 /**
@@ -287,6 +343,20 @@ export declare class CapaError extends Error {
 }
 export declare function isCapaError(error: unknown): error is CapaError;
 export declare function resolveNextConfig(config: CapaNextConfig): ResolvedNextConfig;
+/**
+ * The page a layout (or template) reads for: none.
+ *
+ * A root layout renders around every page on the site, so charging its reads
+ * to `/`, the route its file sits at, made the home page look as if it read
+ * every Site singleton and nav on the site. `routeOf` returns this for a
+ * `layout.*` or `template.*` file, and a read that names it sends NO
+ * `Capa-Page` at all, even when the client was built with a `page`.
+ *
+ * Not sent as a value, because the API would drop it anyway: it is not a
+ * `PAGE_ID`, and the API ignores what it cannot store. Staying absent keeps a
+ * layout read byte-identical to one from a client that never named a page.
+ */
+export declare const LAYOUT_PAGE = "(layout)";
 type SelectInput = string | ReadonlyArray<unknown>;
 /** Serialize the SDK object form into the canonical `/api/entries` grammar. */
 export declare function serializeSelect(select: SelectInput): string;

package/dist/next/client.js

@@ -1,10 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CapaError = void 0;
+exports.LAYOUT_PAGE = exports.CapaError = void 0;
 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
@@ -85,6 +87,20 @@ function resolveNextConfig(config) {
  * quietly stops arriving rather than as an error.
  */
 const PAGE_ID = /^\/[A-Za-z0-9._\-[\]/]{0,199}$/;
+/**
+ * The page a layout (or template) reads for: none.
+ *
+ * A root layout renders around every page on the site, so charging its reads
+ * to `/`, the route its file sits at, made the home page look as if it read
+ * every Site singleton and nav on the site. `routeOf` returns this for a
+ * `layout.*` or `template.*` file, and a read that names it sends NO
+ * `Capa-Page` at all, even when the client was built with a `page`.
+ *
+ * Not sent as a value, because the API would drop it anyway: it is not a
+ * `PAGE_ID`, and the API ignores what it cannot store. Staying absent keeps a
+ * layout read byte-identical to one from a client that never named a page.
+ */
+exports.LAYOUT_PAGE = "(layout)";
 /**
  * The page for one call: the call's own value, else the client's, else none.
  *
@@ -97,11 +113,33 @@ function resolvePage(configPage, callPage) {
     const value = callPage !== undefined ? callPage : configPage;
     if (value === undefined || value === null)
         return undefined;
+    // A layout's read, named on purpose: no header, and the config's page does
+    // not stand in for it either.
+    if (value === exports.LAYOUT_PAGE)
+        return undefined;
     if (typeof value !== "string" || !PAGE_ID.test(value)) {
         throw new TypeError(`@capacms/sdk/next: page must be a path such as "/blog/[slug]" or "/blog/hello". Got ${JSON.stringify(value)}.`);
     }
     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)) {
@@ -207,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)) {
@@ -276,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 = {
@@ -290,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.
@@ -309,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 &&
@@ -339,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 });
@@ -399,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, resolveNextConfig, serializeSelect, } from "./client";
-export { capaAttrs } from "./attrs";
+export { CapaError, createClient, isCapaError, LAYOUT_PAGE, resolveNextConfig, serializeSelect, } from "./client";
+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,11 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.capaAttrs = exports.serializeSelect = exports.resolveNextConfig = 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; } });
 Object.defineProperty(exports, "isCapaError", { enumerable: true, get: function () { return client_1.isCapaError; } });
+Object.defineProperty(exports, "LAYOUT_PAGE", { enumerable: true, get: function () { return client_1.LAYOUT_PAGE; } });
 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; } });