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

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

@@ -1,4 +1,4 @@
-import { type CapaNextClient, type CapaNextConfig, type PagesResource, type PreviewClaim } from "../next";
+import { LAYOUT_PAGE, type CapaNextClient, type CapaNextConfig, type PagesResource, type PreviewClaim } from "../next";
 export interface CacheOptions {
     tags?: string[];
     revalidate?: number | false;
@@ -50,4 +50,179 @@ export declare function preview(token: string, client: CapaNextClient): Promise<
  * this and never hold the whole client.
  */
 export declare function pagesFor(client: CapaNextClient): PagesResource;
+export { LAYOUT_PAGE };
 export 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>;