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

package/dist/nextjs/index.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+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;
@@ -7,7 +8,16 @@ 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/*`. */
 function withCache(fetchImpl, options) {
     return (async (input, init = {}) => {
@@ -64,6 +74,16 @@ async function draftClient(input) {
  *   src/app/(marketing)/pricing/page.tsx     -> /pricing
  *   pages/blog/[slug].tsx                    -> /blog/[slug]
  *   app/page.tsx                             -> /
+ *   app/layout.tsx, app/blog/template.tsx    -> (layout)
+ *
+ * A LAYOUT IS NOT A PAGE. `layout.*` and `template.*` render around every page
+ * below them, and a layout is not told which one: Next hands it no pathname.
+ * So its reads cannot be charged to the page being rendered, and charging them
+ * to the route its own file sits at is wrong: a root layout's Site singleton
+ * and nav would all be recorded as reads of `/`. `routeOf` returns
+ * `LAYOUT_PAGE` (`"(layout)"`) for these files instead, and a read that names
+ * it sends no `Capa-Page` at all. Pass `routeOf(import.meta.url)` from a layout
+ * exactly as from a page and it does the right thing.
  *
  * WHAT IS DROPPED, and why each one:
  *
@@ -74,8 +94,7 @@ async function draftClient(input) {
  *   parallel slots `@modal`               the same
  *   the `(.)` intercept marker            an intercepting route at the SAME
  *                                         level renders the segment beside it
- *   `page.*`, `layout.*`, `route.*`,      leaf files, not segments
- *   `default.*`, `template.*`
+ *   `page.*`, `route.*`, `default.*`      leaf files, not segments
  *   `index` in the pages router           the folder IS the route
  *   the extension                         never in a URL
  *
@@ -87,7 +106,9 @@ async function draftClient(input) {
  * case the message says to pass the page string yourself.
  */
 const ROUTER_ROOTS = new Set(["app", "pages"]);
-const LEAF_FILES = new Set(["page", "layout", "route", "default", "template"]);
+const LEAF_FILES = new Set(["page", "route", "default"]);
+/** Files that render around many routes, so they name none. */
+const LAYOUT_FILES = new Set(["layout", "template"]);
 /** `(..)photo`, `(..)(..)photo`, `(...)photo`: the URL is not here. */
 const OUTER_INTERCEPT = /^(\(\.\.\.\)|(\(\.\.\))+)/;
 function routeOf(file) {
@@ -131,6 +152,9 @@ function routeOf(file) {
             const dot = part.lastIndexOf(".");
             if (dot > 0)
                 part = part.slice(0, dot);
+            // Only in the app router: `pages/layout.tsx` is a page at `/layout`.
+            if (parts[rootIndex] === "app" && LAYOUT_FILES.has(part))
+                return next_1.LAYOUT_PAGE;
             if (LEAF_FILES.has(part))
                 continue;
             // The pages router: `pages/blog/index.tsx` is `/blog`.
@@ -176,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.2",
+  "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"
   }
 }