@capacms/sdk 1.0.0-next.6 → 1.0.0-next.8

package/dist/nextjs/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_API_VERSION = exports.CAPA_ENV_ALIASES = exports.CAPA_ENV = exports.EDIT_CACHE_CONTROL = exports.DRAFT_COOKIE = exports.EDIT_HEADER = exports.EDIT_PARAM = exports.LAYOUT_PAGE = exports.gql = exports.MEDIA_TAG = exports.GRAPHQL_TAG = void 0;
+exports.DRAFT_COOKIE_MAX_AGE = exports.DRAFT_ROBOTS_TAG = exports.CAPA_ADMIN_ORIGIN = exports.DEFAULT_API_VERSION = exports.CAPA_ENV_ALIASES = exports.CAPA_ENV = exports.EDIT_CACHE_CONTROL = exports.DRAFT_COOKIE = exports.EDIT_HEADER = exports.VIEW_PARAM = exports.PREVIEW_PARAM = exports.EDIT_PARAM = exports.LAYOUT_PAGE = exports.gql = exports.MEDIA_TAG = exports.GRAPHQL_TAG = void 0;
 exports.withCache = withCache;
 exports.modelTag = modelTag;
 exports.tagsFor = tagsFor;
@@ -15,6 +15,11 @@ exports.getPublishedClient = getPublishedClient;
 exports.getCapaClient = getCapaClient;
 exports.graphql = graphql;
 exports.safeSitePath = safeSitePath;
+exports.frameAncestors = frameAncestors;
+exports.draftHeaders = draftHeaders;
+exports.capaHeaders = capaHeaders;
+exports.frameDraftCookie = frameDraftCookie;
+exports.clearDraftCookie = clearDraftCookie;
 exports.createPreviewRoute = createPreviewRoute;
 exports.exitPreviewRoute = exitPreviewRoute;
 exports.capaMiddleware = capaMiddleware;
@@ -47,11 +52,12 @@ function modelTag(namespace) {
     return `capa:model:${namespace}`;
 }
 /**
- * The tag `graphql()` gives a read that names no `tags`, and that
- * `revalidateFromWebhook` revalidates on every content change: such a page is
- * never stale after a publish, at the price of refreshing on any publish.
- * Name the models it reads with `tagsFor({ namespace })` to refresh it only
- * when one of those changes.
+ * The tag `graphql()` keeps a read under when it gives a `revalidate` and no
+ * `tags`, and that `revalidateFromWebhook` revalidates on every content
+ * change: such a page is never stale after a publish, at the price of
+ * refreshing on any publish. Name the models it reads with
+ * `tagsFor({ namespace })` to refresh it only when one of those changes. A
+ * read with neither `tags` nor `revalidate` is not kept at all.
  */
 exports.GRAPHQL_TAG = "capa:graphql";
 /**
@@ -283,6 +289,10 @@ function pagesFor(client) {
  * clickable. It never switches the site to draft data.
  */
 exports.EDIT_PARAM = "capa-edit";
+/** The query parameter a Capa preview link carries: `?capa-preview=<token>`. */
+exports.PREVIEW_PARAM = "capa-preview";
+/** The query parameter of the editor's Published view: `?capa-view=published`. */
+exports.VIEW_PARAM = "capa-view";
 /**
  * The request header `resolveEditRequest` sets once a `capa-edit` token has
  * been verified, for `editMode()` to read. Any copy a browser sent is removed
@@ -321,6 +331,7 @@ function verifiedEdit(headers) {
  *     const edit = await resolveEditRequest(request, publishedClient());
  *     const response = NextResponse.next({ request: { headers: edit.headers } });
  *     if (edit.cacheControl) response.headers.set("Cache-Control", edit.cacheControl);
+ *     if (edit.robotsTag) response.headers.set("X-Robots-Tag", edit.robotsTag);
  *     return response;
  *   }
  *
@@ -347,7 +358,13 @@ async function resolveEditRequest(request, client) {
     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 };
+    return {
+        edit,
+        verified,
+        headers,
+        cacheControl: edit ? exports.EDIT_CACHE_CONTROL : null,
+        robotsTag: edit ? exports.DRAFT_ROBOTS_TAG : null,
+    };
 }
 // ------------------------------------------------- five-minute integration ---
 /**
@@ -423,10 +440,12 @@ function getPublishedClient(overrides = {}) {
  * `CapaQuery` (from `capa-codegen --graphql`) types the builder, as with
  * `createClient`; leave it out for an untyped client. `config` wins over env.
  *
- * Its GraphQL reads, a document or the builder, are kept in Next's data cache
- * exactly as `graphql()` keeps them, each under the `tags` and `revalidate`
- * it is called with: a published read with no errors, never a draft or an
- * edit-mode page. Its REST reads are sent as `createClient` sends them.
+ * Its REST reads are sent as `createClient` sends them, which Next does not
+ * keep. Its GraphQL reads, a document or the builder, are sent the same way
+ * unless a call gives `tags` or `revalidate`, so a publish shows up on both
+ * alike. Given either, a read is kept in Next's data cache exactly as
+ * `graphql()` keeps it: a published read with no errors, never a draft or an
+ * edit-mode page.
  */
 async function getCapaClient(input) {
     const draft = (await input.draftMode()).isEnabled === true;
@@ -493,13 +512,33 @@ async function graphql(document, variables, options = {}) {
     return readInNext(read, document, variables, call, { tags, revalidate });
 }
 /**
- * One GraphQL read in Next, for `graphql()` and `getCapaClient`. Next's data
- * cache holds only a published read with no errors, and the fetch under it is
- * never cached. A draft, an edit-mode read (its entries carry marks a cached
- * copy would lose) and `revalidate: 0` are not cached.
+ * Whether a read said anything about Next's cache: tags to keep it under, or a
+ * `revalidate`. One that said neither is sent as the REST reads are, so a
+ * publish shows up on both the same way.
+ */
+function namesCaching({ tags, revalidate }) {
+    return (tags !== undefined && tags.length > 0) || revalidate !== undefined;
+}
+/**
+ * One GraphQL read in Next, for `graphql()` and `getCapaClient`.
+ *
+ * With no `tags` and no `revalidate` it is sent exactly as `entries.list` and
+ * `entries.get` send theirs: a plain fetch with no `cache` and no `next`, which
+ * Next does not keep, so the page shows a publish on its next render whether
+ * it reads by REST or by GraphQL. Given `tags` or a `revalidate`, Next's data
+ * cache holds a published read with no errors, and the fetch under it is never
+ * cached. A draft, an edit-mode read (its entries carry marks a cached copy
+ * would lose) and `revalidate: 0` are not cached.
  */
-async function readInNext(read, document, variables, call, { tags, revalidate }) {
+async function readInNext(read, document, variables, call, options) {
     const { draft, edit, settings, given } = read;
+    if (!draft && !edit && !namesCaching(options)) {
+        return (0, next_1.createClient)({ editMode: false, ...settings }).graphql(document, variables, call);
+    }
+    // `tags: []` names no tag, so the read is kept under `GRAPHQL_TAG` like one
+    // with no tags: kept under none, nothing could ever revalidate it.
+    const tags = options.tags && options.tags.length > 0 ? options.tags : undefined;
+    const revalidate = options.revalidate;
     const baseFetch = settings.fetch ?? globalThis.fetch;
     const cache = given ?? nextUnstableCache();
     if (cache && !draft) {
@@ -547,26 +586,166 @@ function safeSitePath(value) {
         return "/";
     return value;
 }
+// -------------------------------------------------------- draft responses ---
+/** The Capa admin's origin: what frames a draft in the editor, unless a site names another. */
+exports.CAPA_ADMIN_ORIGIN = "https://app.capacms.com";
+/** `X-Robots-Tag` on every draft and edit-mode response: a draft is never indexed, nor its links followed. */
+exports.DRAFT_ROBOTS_TAG = "noindex, nofollow";
+/** How long the draft cookie lasts, in seconds: one hour, as a preview token does. */
+exports.DRAFT_COOKIE_MAX_AGE = 3600;
+/**
+ * `frame-ancestors 'self' <origins>`, the CSP directive that lets the Capa
+ * editor frame a draft and nothing else frame it. Each origin is a scheme and
+ * a host, with a port when it has one, and is written as the URL parser
+ * normalises it, so no `;` or quote can reach the policy. Anything else, a
+ * path or a query included, throws a `TypeError`.
+ */
+function frameAncestors(adminOrigins = [exports.CAPA_ADMIN_ORIGIN]) {
+    const origins = new Set();
+    for (const value of adminOrigins)
+        origins.add(originOf(value));
+    return ["frame-ancestors 'self'", ...origins].join(" ");
+}
+function originOf(value) {
+    let url = null;
+    try {
+        url = typeof value === "string" ? new URL(value) : null;
+    }
+    catch {
+        url = null;
+    }
+    const bare = url !== null &&
+        (url.protocol === "https:" || url.protocol === "http:") &&
+        url.pathname === "/" &&
+        url.search === "" &&
+        url.hash === "" &&
+        url.username === "" &&
+        url.password === "";
+    if (!bare) {
+        throw new TypeError(`@capacms/sdk/nextjs: ${JSON.stringify(value)} is not an origin. Pass a scheme and a host, such as ${exports.CAPA_ADMIN_ORIGIN}.`);
+    }
+    return url.origin;
+}
+/**
+ * The headers every draft response carries: `X-Robots-Tag: noindex, nofollow`,
+ * and `Content-Security-Policy: frame-ancestors 'self' https://app.capacms.com`
+ * (or the `adminOrigins` given). Throws for an origin that is not one.
+ */
+function draftHeaders(options = {}) {
+    return {
+        "X-Robots-Tag": exports.DRAFT_ROBOTS_TAG,
+        "Content-Security-Policy": frameAncestors(options.adminOrigins),
+    };
+}
+/**
+ * Rules for `next.config`'s `headers()` that send `draftHeaders` on draft
+ * responses only:
+ *
+ *   // next.config.mjs
+ *   import { capaHeaders } from "@capacms/sdk/nextjs";
+ *   export default { async headers() { return [...capaHeaders()]; } };
+ *
+ * A rule matches a request carrying the draft cookie, or a `capa-preview`,
+ * `capa-edit` or `capa-view` query. A visitor's request carries none of
+ * them, so its response, cached or not, is exactly what it was. Next checks
+ * the cookie by name, not by value, so a forged cookie only adds these
+ * headers to the forger's own response.
+ *
+ * A site that sends its own `frame-ancestors` or `X-Frame-Options` must leave
+ * them off draft responses (`missing: [{ type: "cookie", key: DRAFT_COOKIE }]`
+ * on its rule): a browser applies every CSP it is sent, so the strictest wins.
+ */
+function capaHeaders(options = {}) {
+    const headers = () => Object.entries(draftHeaders(options)).map(([key, value]) => ({ key, value }));
+    const conditions = [
+        { type: "cookie", key: exports.DRAFT_COOKIE },
+        { type: "query", key: exports.PREVIEW_PARAM },
+        { type: "query", key: exports.EDIT_PARAM },
+        { type: "query", key: exports.VIEW_PARAM },
+    ];
+    return conditions.map((condition) => ({ source: "/:path*", has: [condition], headers: headers() }));
+}
+/** The attributes a draft cookie needs to be sent inside the Capa editor's cross-site frame. */
+const FRAMED = { path: "/", httpOnly: true, secure: true, sameSite: "none", partitioned: true };
+function draftCookieMaxAge(maxAge = exports.DRAFT_COOKIE_MAX_AGE) {
+    if (typeof maxAge !== "number" || !Number.isInteger(maxAge) || maxAge <= 0) {
+        throw new TypeError(`@capacms/sdk/nextjs: maxAge must be a whole number of seconds above 0, and got ${String(maxAge)}.`);
+    }
+    return maxAge;
+}
+/**
+ * Re-set the cookie `draftMode().enable()` just set, so the Capa editor can
+ * use it: `HttpOnly; Secure; SameSite=None; Partitioned; Path=/` and
+ * `Max-Age` one hour (`maxAge` seconds). Next sets it with no `Max-Age`, so
+ * it unlocks every draft on the site until the browser closes, and without
+ * `Partitioned`, which Safari 26.2 and later need to send a cookie into a
+ * cross-site frame. Call it after `enable()`, in the same route handler.
+ * Resolves false, and sets nothing, when there is no draft cookie to re-set.
+ */
+async function frameDraftCookie(cookies, options = {}) {
+    const maxAge = draftCookieMaxAge(options.maxAge);
+    const jar = await cookies();
+    const current = jar.get(exports.DRAFT_COOKIE);
+    if (!current?.value)
+        return false;
+    jar.set({ name: exports.DRAFT_COOKIE, value: current.value, ...FRAMED, maxAge });
+    return true;
+}
+/**
+ * Delete the draft cookie `frameDraftCookie` set. A partitioned cookie is
+ * deleted only by a `Set-Cookie` that is partitioned too, which
+ * `draftMode().disable()` is not. Call it after `disable()`; it replaces
+ * `disable()`'s own deletion, since a response sets one cookie per name. A
+ * draft cookie set without `Partitioned`, before a site used
+ * `frameDraftCookie`, ends when the browser closes, as it always did.
+ */
+async function clearDraftCookie(cookies) {
+    (await cookies()).set({ name: exports.DRAFT_COOKIE, value: "", ...FRAMED, expires: new Date(0) });
+}
+/**
+ * The preview and exit routes' own redirect. Next's `redirect()` throws and
+ * answers for the route, so it cannot carry headers; this one is a plain
+ * `Response`, to which Next appends every cookie the route set. It sets no
+ * cookie itself: Next keeps one per name, and the response's own would win.
+ */
+function routeRedirect(location, headers) {
+    return new Response(null, {
+        status: 307,
+        headers: { Location: location, "Cache-Control": exports.EDIT_CACHE_CONTROL, "Referrer-Policy": "no-referrer", ...headers },
+    });
+}
 /**
  * `app/api/capa/preview/route.ts`:
  *
- *   import { draftMode } from "next/headers";
- *   import { redirect } from "next/navigation";
- *   export const GET = createPreviewRoute({ draftMode, redirect });
+ *   import { cookies, draftMode } from "next/headers";
+ *   export const GET = createPreviewRoute({ draftMode, cookies });
  *
  * 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`.
+ * `?preview=unavailable`. The token is checked with any key the site holds,
+ * its legacy key included (`getPublishedClient`, from `CAPA_KEY`).
+ *
+ * Given `cookies`, the draft cookie is re-set by `frameDraftCookie`: one hour,
+ * and sent inside the editor's frame. With no `redirect`, the route answers
+ * with its own 307, marked `X-Robots-Tag: noindex, nofollow`,
+ * `Referrer-Policy: no-referrer` (the token is in the URL),
+ * `Cache-Control: private, no-store` and the editor's `frame-ancestors`.
+ * Given Next's `redirect`, it is called instead, as before, and the redirect
+ * carries none of those.
  */
 function createPreviewRoute(input) {
+    // Checked here, so a bad origin or maxAge fails where the route is built.
+    const headers = draftHeaders({ adminOrigins: input.adminOrigins });
+    const maxAge = draftCookieMaxAge(input.maxAge);
+    const go = (location) => input.redirect ? input.redirect(location) : routeRedirect(location, headers);
     return async (request) => {
         const url = new URL(request.url);
-        const token = url.searchParams.get("token") ?? url.searchParams.get("capa-preview") ?? "";
+        const token = url.searchParams.get("token") ?? url.searchParams.get(exports.PREVIEW_PARAM) ?? "";
         // 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));
+        const path = safeSitePath(url.searchParams.get("path") ?? (url.searchParams.has(exports.PREVIEW_PARAM) ? url.pathname : null));
         let claim = null;
         let failed = false;
         try {
@@ -578,18 +757,36 @@ function createPreviewRoute(input) {
         const draft = await input.draftMode();
         if (!claim) {
             draft.disable?.();
-            return input.redirect(`${path}?preview=${failed ? "unavailable" : "expired"}`);
+            if (input.cookies)
+                await clearDraftCookie(input.cookies);
+            return go(`${path}?preview=${failed ? "unavailable" : "expired"}`);
         }
         draft.enable?.();
+        if (input.cookies)
+            await frameDraftCookie(input.cookies, { maxAge });
         await input.onEnable?.();
-        return input.redirect(safeSitePath(claim.path ?? path));
+        return go(safeSitePath(claim.path ?? path));
     };
 }
-/** `app/api/capa/exit/route.ts`: `export const GET = exitPreviewRoute({ draftMode, redirect });` */
+/**
+ * `app/api/capa/exit/route.ts`:
+ *
+ *   import { cookies, draftMode } from "next/headers";
+ *   export const GET = exitPreviewRoute({ draftMode, cookies });
+ *
+ * Turns draft mode off and lands on `?path=`. Given `cookies`, the framed
+ * cookie `createPreviewRoute` set is deleted too. With no `redirect`, the route
+ * answers with its own 307, marked noindex and never cached.
+ */
 function exitPreviewRoute(input) {
     return async (request) => {
         (await input.draftMode()).disable?.();
-        return input.redirect(safeSitePath(new URL(request.url).searchParams.get("path")));
+        if (input.cookies)
+            await clearDraftCookie(input.cookies);
+        const location = safeSitePath(new URL(request.url).searchParams.get("path"));
+        if (input.redirect)
+            return input.redirect(location);
+        return routeRedirect(location, { "X-Robots-Tag": exports.DRAFT_ROBOTS_TAG });
     };
 }
 /**
@@ -603,12 +800,25 @@ function exitPreviewRoute(input) {
  * - `?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`.
+ * - every edit-mode response is `private, no-store`, and it and every request
+ *   carrying `capa-edit` or `capa-view` is `X-Robots-Tag: noindex, nofollow`.
+ *
+ * Give it a `matcher` so a visitor's request never runs it (Next reads
+ * `config` from the file itself, so it is written out there):
+ *
+ *   export const config = {
+ *     matcher: [
+ *       { source: "/:path*", has: [{ type: "query", key: "capa-preview" }] },
+ *       { source: "/:path*", has: [{ type: "query", key: "capa-edit" }] },
+ *       { source: "/:path*", has: [{ type: "query", key: "capa-view" }] },
+ *       { source: "/:path*", has: [{ type: "cookie", key: "__prerender_bypass" }] },
+ *     ],
+ *   };
  */
 function capaMiddleware(input) {
     const previewRoute = input.previewRoute ?? "/api/capa/preview";
     return async (request) => {
-        const token = request.nextUrl.searchParams.get("capa-preview");
+        const token = request.nextUrl.searchParams.get(exports.PREVIEW_PARAM);
         if (token) {
             const target = request.nextUrl.clone();
             target.pathname = previewRoute;
@@ -618,7 +828,7 @@ function capaMiddleware(input) {
             return input.NextResponse.rewrite(target);
         }
         const headers = new Headers(request.headers);
-        if (request.nextUrl.searchParams.get("capa-view") === "published") {
+        if (request.nextUrl.searchParams.get(exports.VIEW_PARAM) === "published") {
             const cookies = request.cookies
                 .getAll()
                 .filter((cookie) => cookie.name !== exports.DRAFT_COOKIE)
@@ -635,6 +845,11 @@ function capaMiddleware(input) {
         const response = input.NextResponse.next({ request: { headers: edit.headers } });
         if (edit.cacheControl)
             response.headers.set("Cache-Control", edit.cacheControl);
+        // A capa- link is the editor's, verified or not, and never a page to index.
+        const capaLink = request.nextUrl.searchParams.has(exports.EDIT_PARAM) || request.nextUrl.searchParams.has(exports.VIEW_PARAM);
+        const robots = edit.robotsTag ?? (capaLink ? exports.DRAFT_ROBOTS_TAG : null);
+        if (robots)
+            response.headers.set("X-Robots-Tag", robots);
         return response;
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capacms/sdk",
-  "version": "1.0.0-next.6",
+  "version": "1.0.0-next.8",
   "description": "The TypeScript SDK for Capa's content API: REST and GraphQL reads typed from your models, Next.js caching and live preview, and codegen.",
   "license": "UNLICENSED",
   "homepage": "https://docs.capacms.com/api",
@@ -68,16 +68,12 @@
   },
   "peerDependencies": {
     "graphql": "^16.9.0",
-    "next": ">=14",
     "react": ">=18"
   },
   "peerDependenciesMeta": {
     "graphql": {
       "optional": true
     },
-    "next": {
-      "optional": true
-    },
     "react": {
       "optional": true
     }
@@ -93,6 +89,6 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "tsc -p tsconfig.json && node --test test/comments.test.js 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 test/field-names.test.js test/next-graphql.test.js test/graphql-codegen.test.js test/graphql-contract.test.js test/readme-snippets.test.js test/nextjs-app.test.js test/package-json.test.js test/changelog.test.js test/published-docs.test.js test/builder-messages.test.js && tsc -p test/types/tsconfig.consumer.json --noEmit && tsc -p test/types/tsconfig.nonstrict.json --noEmit"
+    "test": "tsc -p tsconfig.json && node --test test/comments.test.js 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 test/field-names.test.js test/next-graphql.test.js test/graphql-codegen.test.js test/graphql-contract.test.js test/readme-snippets.test.js test/nextjs-app.test.js test/nextjs-preview-app.test.js test/package-json.test.js test/changelog.test.js test/published-docs.test.js test/builder-messages.test.js && tsc -p test/types/tsconfig.consumer.json --noEmit && tsc -p test/types/tsconfig.nonstrict.json --noEmit && tsc -p test/types/tsconfig.next.json --noEmit"
   }
 }