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

package/dist/next/key-family.d.ts

@@ -2,16 +2,18 @@
  * key-family.ts — which keys `@capacms/sdk/next` takes, and for what.
  *
  * A `cap_` key is the `/api/` key: scoped, hashed at rest, and the only kind
- * a draft preview takes, both to verify a preview token and to read drafts.
- * Every other key is legacy, which is the API's rule
- * (`apps/api/src/api-next/auth/key-format.ts`): the `pk_` and `sk_` keys, and
- * the unprefixed keys older tenants were minted, all reach `/api/` with the
- * grants their permission gives. So every read call takes them, and the first
- * client built with one warns once per process, naming the key to mint.
+ * the draft clients take to read drafts. Every other key is legacy, which is
+ * the API's rule (`apps/api/src/api-next/auth/key-format.ts`): the `pk_` and
+ * `sk_` keys, and the unprefixed keys older tenants were minted, all reach
+ * `/api/` with the grants their permission gives. So every read call takes
+ * them, `preview()` included: `GET /api/preview` asks for `instance:read`,
+ * which every legacy permission grants, and refuses a token minted for another
+ * tenant. The first client built with one warns once per process, naming the
+ * key to mint.
  *
  * The `cap_` prefix is the whole rule, case-sensitive, as on the API:
  * `CAP_live_…` is not a key Capa mints, so it is looked up as a legacy key.
- * `@capa/mcp` applies the same rule, and both packages are tested against one
+ * `@capacms/mcp` applies the same rule, and both packages are tested against one
  * vector file, `test/fixtures/key-family.json`.
  */
 export type KeyFamily = "cap" | "legacy";
@@ -19,11 +21,6 @@ export type KeyFamily = "cap" | "legacy";
 export declare function keyFamily(apiKey: unknown): KeyFamily | null;
 /** Warn about a legacy key once per process: a site builds a client per request. */
 export declare function warnLegacyKeyOnce(apiKey: string): void;
-/**
- * Throws for a legacy key: verifying a preview token takes a `cap_` key. A
- * value that is no key at all is `resolveNextConfig`'s to refuse, by name.
- */
-export declare function requirePreviewKey(apiKey: string): void;
 /**
  * Throws for a legacy key: a draft read takes a `cap_` key. `holder` names
  * where the key came from (`CAPA_DRAFT_KEY`, `the draft config`), so the

package/dist/next/key-family.js

@@ -3,22 +3,23 @@
  * key-family.ts — which keys `@capacms/sdk/next` takes, and for what.
  *
  * A `cap_` key is the `/api/` key: scoped, hashed at rest, and the only kind
- * a draft preview takes, both to verify a preview token and to read drafts.
- * Every other key is legacy, which is the API's rule
- * (`apps/api/src/api-next/auth/key-format.ts`): the `pk_` and `sk_` keys, and
- * the unprefixed keys older tenants were minted, all reach `/api/` with the
- * grants their permission gives. So every read call takes them, and the first
- * client built with one warns once per process, naming the key to mint.
+ * the draft clients take to read drafts. Every other key is legacy, which is
+ * the API's rule (`apps/api/src/api-next/auth/key-format.ts`): the `pk_` and
+ * `sk_` keys, and the unprefixed keys older tenants were minted, all reach
+ * `/api/` with the grants their permission gives. So every read call takes
+ * them, `preview()` included: `GET /api/preview` asks for `instance:read`,
+ * which every legacy permission grants, and refuses a token minted for another
+ * tenant. The first client built with one warns once per process, naming the
+ * key to mint.
  *
  * The `cap_` prefix is the whole rule, case-sensitive, as on the API:
  * `CAP_live_…` is not a key Capa mints, so it is looked up as a legacy key.
- * `@capa/mcp` applies the same rule, and both packages are tested against one
+ * `@capacms/mcp` applies the same rule, and both packages are tested against one
  * vector file, `test/fixtures/key-family.json`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.keyFamily = keyFamily;
 exports.warnLegacyKeyOnce = warnLegacyKeyOnce;
-exports.requirePreviewKey = requirePreviewKey;
 exports.requireDraftKey = requireDraftKey;
 exports.__resetKeyWarningForTests = __resetKeyWarningForTests;
 const LEGACY_PREFIX = /^(pk|sk)_/;
@@ -46,17 +47,8 @@ function warnLegacyKeyOnce(apiKey) {
     if (warned)
         return;
     warned = true;
-    console.warn(`@capacms/sdk/next: this client reads with a ${legacyKind(apiKey)}. Reads work as they do with a cap_ key. ` +
-        `Draft previews need a cap_ key: mint one ${MINT}`);
-}
-/**
- * Throws for a legacy key: verifying a preview token takes a `cap_` key. A
- * value that is no key at all is `resolveNextConfig`'s to refuse, by name.
- */
-function requirePreviewKey(apiKey) {
-    if (!isLegacy(apiKey))
-        return;
-    throw new TypeError(`@capacms/sdk/next: preview needs a cap_ key, and this client holds a ${legacyKind(apiKey)}. Mint a cap_ key ${MINT}`);
+    console.warn(`@capacms/sdk/next: this client reads with a ${legacyKind(apiKey)}. Reads and preview links work as they do with a cap_ key. ` +
+        `Draft reads need a cap_ key: mint one ${MINT}`);
 }
 /**
  * Throws for a legacy key: a draft read takes a `cap_` key. `holder` names

package/dist/nextjs/index.d.ts

@@ -13,11 +13,12 @@ export declare function withCache(fetchImpl: typeof fetch, options: CacheOptions
  */
 export declare function modelTag(namespace: string): string;
 /**
- * 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.
  */
 export declare const GRAPHQL_TAG = "capa:graphql";
 /**
@@ -110,6 +111,10 @@ export type { PreviewClaim };
  * clickable. It never switches the site to draft data.
  */
 export declare const EDIT_PARAM = "capa-edit";
+/** The query parameter a Capa preview link carries: `?capa-preview=<token>`. */
+export declare const PREVIEW_PARAM = "capa-preview";
+/** The query parameter of the editor's Published view: `?capa-view=published`. */
+export declare const 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
@@ -156,6 +161,8 @@ export interface EditRequest {
     headers: Headers;
     /** `EDIT_CACHE_CONTROL` in edit mode, otherwise null. Set it on the response. */
     cacheControl: string | null;
+    /** `DRAFT_ROBOTS_TAG` in edit mode, otherwise null. Set it on the response as `X-Robots-Tag`. */
+    robotsTag: string | null;
 }
 /**
  * The middleware half of edit mode.
@@ -164,6 +171,7 @@ export interface EditRequest {
  *     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;
  *   }
  *
@@ -219,10 +227,12 @@ export declare function getPublishedClient<Q = UntypedQuery>(overrides?: Partial
  * `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.
  */
 export declare function getCapaClient<Q = UntypedQuery>(input: {
     draftMode: DraftModeFn;
@@ -234,14 +244,16 @@ export declare function getCapaClient<Q = UntypedQuery>(input: {
 /** Where a GraphQL read in Next keeps its answer: Next's data cache, as `graphql()` and `getCapaClient` keep it. */
 export interface NextCacheOptions extends GraphQLCallOptions {
     /**
-     * Next.js cache tags for this read. `tagsFor({ namespace: <Name>Models })`,
-     * with the list `capa-codegen --graphql` writes beside each document, tags
-     * it with every model the query reads, which `revalidateFromWebhook`
-     * revalidates on a publish. Without tags the read is tagged `GRAPHQL_TAG`,
-     * which every publish revalidates.
+     * Next.js cache tags to keep this read under. `tagsFor({ namespace:
+     * <Name>Models })`, with the list `capa-codegen --graphql` writes beside
+     * each document, tags it with every model the query reads, which
+     * `revalidateFromWebhook` revalidates on a publish. Given a `revalidate`
+     * and no tags, the read is kept under `GRAPHQL_TAG`, which every publish
+     * revalidates. Given neither, the read is not kept: it is sent as a REST
+     * read is, on every render.
      */
     tags?: string[];
-    /** Seconds to cache, or `false` to cache until a tag is revalidated. */
+    /** Seconds to cache, `false` to cache until a tag is revalidated, or 0 not to cache. */
     revalidate?: number | false;
 }
 export interface NextGraphQLOptions extends NextCacheOptions {
@@ -261,9 +273,10 @@ export interface NextGraphQLOptions extends NextCacheOptions {
     config?: Partial<CapaNextConfig>;
     /**
      * Next's `unstable_cache`, from `next/cache`. Leave it out: `graphql()`
-     * loads Next's own. A published read is kept in Next's data cache only when
-     * it answered with no `errors`, under `tags` for `revalidate` seconds, or
-     * with no `revalidate` until one of its tags is revalidated. Next's fetch
+     * loads Next's own. A published read given `tags` or a `revalidate` is kept
+     * in Next's data cache only when it answered with no `errors`, under `tags`
+     * for `revalidate` seconds, or with no `revalidate` until one of its tags is
+     * revalidated. Next's fetch
      * cache is not used for it: that cache keeps any 200, and a GraphQL error
      * is a 200 (a root field that timed out), and in Next 15 it keeps nothing
      * without a `revalidate`, tags or not. Pass it only to supply another.
@@ -293,12 +306,15 @@ export type UnstableCache = <T extends (...args: any[]) => Promise<any>>(cb: T,
  * variables are typed from it, as they are for a `<Name>Document` it writes,
  * and `LatestModels` lists the models it reads.
  *
- * A published read is kept in Next's data cache (`unstable_cache`) when it
- * answered with no errors: under `tags`, for `revalidate` seconds, or with no
- * `revalidate` until `revalidateFromWebhook` revalidates one of its tags on a
- * publish. It goes as a GET, which the CDN and the API also cache for the
- * published key; a document too long for a GET URL goes as a POST, which only
- * Next's data cache keeps. Under draft mode the read uses `CAPA_DRAFT_KEY`, a
+ * With no `tags` and no `revalidate` a read is sent as the REST reads are,
+ * and Next keeps nothing: the page shows a publish on its next render, as a
+ * page reading by REST does. Given either, a published read is kept in Next's
+ * data cache (`unstable_cache`) when it answered with no errors: under `tags`,
+ * for `revalidate` seconds, or with no `revalidate` until
+ * `revalidateFromWebhook` revalidates one of its tags on a publish. It goes
+ * as a GET, which the CDN and the API also cache for the published key; a
+ * document too long for a GET URL goes as a POST, which only Next's data
+ * cache keeps. Under draft mode the read uses `CAPA_DRAFT_KEY`, a
  * `cap_` key, and bypasses the cache (the API answers a development key's GET
  * `no-store`), the same split `getCapaClient` makes for REST, and in edit mode
  * each entry that selects `id` and `model` is marked for `capaAttrs`, uncached.
@@ -314,29 +330,149 @@ export declare function graphql<D extends keyof CapaDocuments>(document: D, ...r
 export declare function graphql<TData = Record<string, unknown>, TVariables = Record<string, unknown>, D extends string = string>(document: NotARecordedDocument<D, TypedDocument<TData, TVariables> | D>, ...rest: VariablesThenOptions<TVariables, NextGraphQLOptions>): Promise<GraphQLResult<TData>>;
 /** Only a path on this site: never `//elsewhere.example` or a full URL. */
 export declare function safeSitePath(value: string | null | undefined): string;
+/** The Capa admin's origin: what frames a draft in the editor, unless a site names another. */
+export declare const 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. */
+export declare const DRAFT_ROBOTS_TAG = "noindex, nofollow";
+/** How long the draft cookie lasts, in seconds: one hour, as a preview token does. */
+export declare const 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`.
+ */
+export declare function frameAncestors(adminOrigins?: readonly string[]): string;
+/**
+ * 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.
+ */
+export declare function draftHeaders(options?: {
+    adminOrigins?: readonly string[];
+}): Record<string, string>;
+/** One rule of `next.config`'s `headers()`, in the shape Next takes. */
+export interface NextHeaderRule {
+    source: string;
+    has: Array<{
+        type: "cookie" | "query";
+        key: string;
+    }>;
+    headers: Array<{
+        key: string;
+        value: string;
+    }>;
+}
+/**
+ * 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.
+ */
+export declare function capaHeaders(options?: {
+    adminOrigins?: readonly string[];
+}): NextHeaderRule[];
+/** The part of Next's `cookies()` store (`next/headers`) the draft-cookie helpers use. */
+export interface DraftCookieJar {
+    get(name: string): {
+        value: string;
+    } | undefined;
+    set(cookie: {
+        name: string;
+        value: string;
+        path: string;
+        httpOnly: boolean;
+        secure: boolean;
+        sameSite: "none";
+        partitioned: boolean;
+        maxAge?: number;
+        expires?: Date;
+    }): unknown;
+}
+/** Next's `cookies` from `next/headers`, or anything shaped like it. */
+export type CookiesFn = () => DraftCookieJar | Promise<DraftCookieJar>;
+/**
+ * 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.
+ */
+export declare function frameDraftCookie(cookies: CookiesFn, options?: {
+    maxAge?: number;
+}): Promise<boolean>;
+/**
+ * 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.
+ */
+export declare function clearDraftCookie(cookies: CookiesFn): Promise<void>;
 /**
  * `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.
  */
 export declare function createPreviewRoute(input: {
     draftMode: DraftModeFn;
-    redirect: (url: string) => never | void;
+    /** Next's `cookies`. Given, the draft cookie lasts `maxAge` seconds and works in the editor's frame. */
+    cookies?: CookiesFn;
+    /** Next's `redirect`. Leave it out for a redirect that carries the draft headers. */
+    redirect?: (url: string) => never | void;
     client?: () => Pick<CapaNextClient, "preview">;
-    /** Runs after draft mode is enabled, before the redirect (cookie tweaks). */
+    /** Runs after draft mode is enabled and the cookie re-set, before the redirect (cookie tweaks). */
     onEnable?: () => void | Promise<void>;
+    /** The origins allowed to frame a draft. `[CAPA_ADMIN_ORIGIN]` when left out. */
+    adminOrigins?: readonly string[];
+    /** Seconds the draft cookie lasts, given `cookies`. `DRAFT_COOKIE_MAX_AGE` (one hour) when left out. */
+    maxAge?: number;
 }): (request: Request) => Promise<Response | void>;
-/** `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.
+ */
 export declare function exitPreviewRoute(input: {
     draftMode: DraftModeFn;
-    redirect: (url: string) => never | void;
+    cookies?: CookiesFn;
+    redirect?: (url: string) => never | void;
 }): (request: Request) => Promise<Response | void>;
 interface MiddlewareRequest {
     url: string;
@@ -372,7 +508,20 @@ interface NextResponseLike {
  * - `?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" }] },
+ *     ],
+ *   };
  */
 export declare function capaMiddleware(input: {
     NextResponse: NextResponseLike;