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

package/CHANGELOG.md

@@ -2,6 +2,60 @@
 
 ## Unreleased
 
+- 1.0.0-next.8. Preview on a live site, in draft mode on its production
+  domain. `preview()` takes the legacy key a site already holds (`pk_`, `sk_`
+  or unprefixed), as the API does: Capa checks the token with any key that
+  reads the project, and refuses a token made for another project. It used to
+  throw a `TypeError` for a legacy key before any request. Draft reads through
+  the SDK still take a `cap_` key only, and the legacy-key warning says so.
+- Next.js: `createPreviewRoute` and `exitPreviewRoute` take Next's `cookies`.
+  Given it, the draft cookie is re-set
+  `HttpOnly; Secure; SameSite=None; Partitioned; Path=/; Max-Age=3600`
+  (`maxAge` changes the hour), so Safari 26.2 and later send it inside the
+  editor's frame and it no longer lasts until the browser closes. Exit and a
+  bad link delete it partitioned, which is the only deletion that reaches
+  it. `redirect` is optional now: left out, each route answers with its own
+  307, marked `X-Robots-Tag: noindex, nofollow`,
+  `Referrer-Policy: no-referrer` and `Cache-Control: private, no-store`, and
+  the preview route's carries the editor's `frame-ancestors`. Given
+  `redirect`, a route calls it as before.
+- Next.js: `capaHeaders({ adminOrigins })` returns rules for `next.config`'s
+  `headers()` that send `X-Robots-Tag: noindex, nofollow` and
+  `Content-Security-Policy: frame-ancestors 'self' https://app.capacms.com`
+  on a request carrying the draft cookie or a `capa-preview`, `capa-edit` or
+  `capa-view` query, and on nothing else, so a visitor's response is
+  unchanged. Also exported: `draftHeaders`, `frameAncestors` (it throws for a
+  value that is not a bare origin), `frameDraftCookie`, `clearDraftCookie`,
+  `CAPA_ADMIN_ORIGIN`, `DRAFT_ROBOTS_TAG`, `DRAFT_COOKIE_MAX_AGE`,
+  `PREVIEW_PARAM` and `VIEW_PARAM`.
+- Next.js: `capaMiddleware` marks every edit-mode response, and every request
+  carrying `capa-edit` or `capa-view`, `X-Robots-Tag: noindex, nofollow`, and
+  `resolveEditRequest` returns that value as `robotsTag`.
+- Docs: "Add preview to a live site without changing it", the steps for a
+  site that keeps its own Capa reads, and why `editMode()` and
+  `getCapaClient()` make a static page dynamic.
+- 1.0.0-next.7. Browsers: the `/api/` and legacy clients called the platform `fetch` as a
+  method of their config, which a browser refuses ("Failed to execute 'fetch'
+  on 'Window': Illegal invocation"), so every read from a browser failed unless
+  `fetch` was passed in. The default fetch is now called through `globalThis`
+  on each request, which also picks up a fetch a framework patches in later.
+- `next` is no longer a peer dependency. No range matches every Next canary,
+  so a site on `next@16.3.0-canary.39` could not `npm install` the SDK without
+  `--legacy-peer-deps`. `@capacms/sdk/nextjs/overlay` still imports `next`,
+  which only a Next site loads.
+- Docs: the edit mark is dropped wherever an entry is serialized to the
+  browser (Pages Router props, SvelteKit and Remix loaders, Nuxt payload);
+  pass the edit flag to `capaAttrs` there. Found testing preview on nine stacks.
+- Next.js: a GraphQL read that gives neither `tags` nor `revalidate`, through
+  `getCapaClient().graphql()`, its builder or `graphql()`, is no longer kept
+  in Next's data cache. It is sent as `entries.list` and `entries.get` send
+  theirs, with no `cache` and no `next`, so a publish shows on the next render
+  whether the page reads by REST or by GraphQL. It used to be kept under
+  `capa:graphql` until a webhook revalidated it, so a site with no webhook
+  route kept serving the old answer by GraphQL while REST showed the new one.
+  A read that gives `tags` or a `revalidate` is kept as before. To keep a read
+  with no tags as it was kept, pass `revalidate: false`, which keeps it under
+  `capa:graphql` until the next publish. `tags: []` now counts as no tags.
 - 1.0.0-next.6. GraphQL, on `@capacms/sdk/next` and `@capacms/sdk/nextjs`,
   and two commands, `capa-codegen --graphql` and `capa persist`. Additive:
   every call that existed behaves as before. `graphql` is an optional peer
@@ -143,7 +197,7 @@
   as it takes a tool spec.
 
   The tool spec. `buildGraphQLQuery`, `graphqlToSelect` and `selectToGraphQL`
-  move between the spec the Explorer and `@capa/mcp` share, GraphQL text and
+  move between the spec the Explorer and `@capacms/mcp` share, GraphQL text and
   the equal REST request, written exactly as the API writes it in
   `extensions.capa.rest`: the filter as `where` JSON, and a system key a
   field shadows as `$tags`, `$createdAt` or `author.$id`. They nest at most 4

package/README.md

@@ -47,12 +47,14 @@ under Developers > Keys.
 The legacy key your site already holds works too, for every read: a `pk_`
 or `sk_` key, or an older key with no prefix, since every key but `cap_` is
 a legacy key to the API. That covers `entries`, `graphql`,
-`graphqlSchema`, `pages`, `me` and `versions`. The first client built with
-one prints a warning once per process, naming the `cap_` key to mint. Draft
-previews keep their rule and take a `cap_` key only: `preview()`,
-`draftClient`'s `draft` config, and `CAPA_DRAFT_KEY` for `getCapaClient` and
-`graphql()` throw a `TypeError` for a legacy key before any request. An
-`apiKey` that is not a string is refused where the client is built.
+`graphqlSchema`, `pages`, `me`, `versions` and `preview`: a site checks an
+editor's preview link with the key it already holds, and Capa refuses a link
+made for another project. The first client built with one prints a warning
+once per process, naming the `cap_` key to mint. Draft reads through the SDK
+keep their rule and take a `cap_` key only: `draftClient`'s `draft` config,
+and `CAPA_DRAFT_KEY` for `getCapaClient` and `graphql()`, throw a `TypeError`
+for a legacy key before any request. An `apiKey` that is not a string is
+refused where the client is built.
 
 `CAPA_API_URL` and `CAPA_KEY` are the names every Capa tool reads: the
 `/nextjs` helpers, `capa-codegen` and Capa's MCP server, so one `.env` serves
@@ -287,9 +289,10 @@ const capa = await draftClient<CapaQuery>({
 `CapaQuery` types the GraphQL builder on the client it returns, as it does
 for `createClient<CapaQuery>`; `getCapaClient<CapaQuery>` and
 `getPublishedClient<CapaQuery>` take it the same way. Without it each helper
-returns an untyped client. `getCapaClient` also keeps its GraphQL reads in
-Next's data cache, as `graphql()` does, under the `tags` and `revalidate`
-each call gives (see The typed builder).
+returns an untyped client. `getCapaClient` sends its GraphQL reads as it
+sends its REST reads, which Next does not keep, unless a call gives `tags` or
+`revalidate`; then it keeps them in Next's data cache as `graphql()` does
+(see The typed builder).
 
 ## GraphQL
 
@@ -335,8 +338,10 @@ once `capa-codegen --graphql` has read it (see Typed documents). Until then
 the call does not compile, and the error says to run it, so a document edited
 since the last run is never silently untyped.
 
-`graphql()` keeps a published read in Next's data cache, through Next's own
-`unstable_cache`, under the tags you give. `BlogIndexModels` lists the models
+Given `tags` or `revalidate`, `graphql()` keeps a published read in Next's
+data cache, through Next's own `unstable_cache`, under the tags you give.
+Given neither, it keeps nothing: the read is sent as a REST read is, and the
+page shows a publish on its next render. `BlogIndexModels` lists the models
 the query reads, which codegen writes beside its types: `articles`, and
 `authors` for `author { name }`. It changes when the query does, so a model
 the query starts reading is never left out. `tagsFor({ namespace })` makes
@@ -348,16 +353,19 @@ library, its alt text say, changes no entry, so it revalidates `capa:media`
 instead, and every read tagged by its models shows the new text. How long a
 read is kept:
 
-- With no `revalidate`, until one of its tags is revalidated. With the
-  webhook route, that is until the next publish of a model it reads.
+- With neither `tags` nor `revalidate`, not at all: every render reads the
+  API, as `entries.list` does, so a site with no webhook route still shows a
+  publish on the next request.
+- With `tags` and no `revalidate`, until one of its tags is revalidated.
+  With the webhook route, that is until the next publish of a model it reads.
 - With `revalidate: 60`, also at most 60 seconds, so a missed webhook costs
-  a minute of stale content at most. This is the only thing it adds.
-- With `revalidate: 0`, not at all: every render reads the API.
+  a minute of stale content at most.
+- With `revalidate: 0`, not at all.
 
-A read with no `tags` is tagged `capa:graphql` (`GRAPHQL_TAG`), which
-`revalidateFromWebhook` revalidates on every content change, so it is never
-stale after a publish; tag it with its models to refresh the page only when
-one of them changes.
+A read with a `revalidate` and no `tags` is tagged `capa:graphql`
+(`GRAPHQL_TAG`), which `revalidateFromWebhook` revalidates on every content
+change, so it is never stale after a publish; tag it with its models to
+refresh the page only when one of them changes.
 
 A read that answered with `errors` is never kept: a root field that timed
 out is shown once and read again on the next request. Next's fetch cache is
@@ -513,10 +521,10 @@ it is never cached. The admin host serves GraphQL by POST only and answers a
 GET as a path it does not serve; a read that did not ask for GET is then
 repeated as a POST, and that host is read by POST for five minutes. A
 `method: "GET"` read there throws "This Capa host does not serve GraphQL by
-GET." In Next.js, `graphql()` from `/nextjs` adds Next's data cache on top,
-for a published read with no errors, a POST included: kept under its `tags`
-until one is revalidated, or for `revalidate` seconds when you give it, and
-never for a draft.
+GET." In Next.js, `graphql()` from `/nextjs` adds Next's data cache on top
+when a read gives `tags` or `revalidate`, for a published read with no
+errors, a POST included: kept under its `tags` until one is revalidated, or
+for `revalidate` seconds when you give it, and never for a draft.
 
 ### The typed builder
 
@@ -557,8 +565,8 @@ document is printed when it runs, so `capa persist` never stored it, and it
 is already a GET that the API and the CDN cache. To persist a read, write it
 as a `#graphql` literal (see Persisted queries).
 
-In a Next.js server component, read through `getCapaClient`. Its reads are
-kept in Next's data cache, under the tags each call names:
+In a Next.js server component, read through `getCapaClient`. A read that
+names tags is kept in Next's data cache under them:
 
 ```tsx
 // app/blog/page.tsx
@@ -579,7 +587,8 @@ export default async function Blog() {
 `tags` and `revalidate` work as they do for `graphql()` (see In a Next.js
 server component). A read is kept until a publish of a model its tags name,
 a read with errors is never kept, and a draft or an edit-mode page is read
-uncached. `capa.graphql(document)` on the same client takes them too.
+uncached. A read with neither is not kept, as the client's REST reads are
+not. `capa.graphql(document)` on the same client takes them too.
 
 Read one field twice in one request with an alias: any other key, with
 `__aliasFor` naming the field it reads. A home page's featured and latest
@@ -1266,8 +1275,9 @@ editor sees the path without a link to open it.
 
 ### Quick start (Next.js)
 
-Set `CAPA_API_URL`, `CAPA_KEY` (`cap_live_`) and `CAPA_DRAFT_KEY` (`cap_test_`).
-Draft previews take `cap_` keys only (see Keys). Then:
+Set `CAPA_API_URL`, `CAPA_KEY` (`cap_live_`, or the legacy key your site
+holds) and `CAPA_DRAFT_KEY` (`cap_test_`). Draft reads through the SDK take a
+`cap_` key only (see Keys). Then:
 
 ```ts
 // middleware.ts
@@ -1276,13 +1286,17 @@ 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 { cookies, draftMode } from "next/headers";
 import { createPreviewRoute } from "@capacms/sdk/nextjs";
-export const GET = createPreviewRoute({ draftMode, redirect });
+export const GET = createPreviewRoute({ draftMode, cookies });
+
+// next.config.mjs
+import { capaHeaders } from "@capacms/sdk/nextjs";
+export default { async headers() { return capaHeaders(); } };
 
 // in a page: getCapaClient({ draftMode, headers }), then <h1 {...fieldAttrs(post).title}>
-// in the root layout, in edit mode: <CapaOverlay adminOrigins={[...]} /> from @capacms/sdk/nextjs/overlay
+// in the root layout: const edit = await editMode({ draftMode, headers }) from @capacms/sdk/nextjs,
+// then {edit ? <CapaOverlay adminOrigins={[...]} /> : null} from @capacms/sdk/nextjs/overlay
 ```
 
 In Capa, set the project's preview URL to your site, and editors can click
@@ -1330,6 +1344,33 @@ 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.
 
+**When the entry crosses to the browser as data, pass the flag.** The mark is
+a hidden symbol, so anything that serializes the entry drops it silently: the
+Next Pages Router's `getServerSideProps`, SvelteKit and Remix loaders, Nuxt's
+payload, or your own JSON endpoint. The page then shows the draft with no
+`data-capa-` tags, and the editor has nothing to point at. Nothing errors. Send
+the draft or edit state alongside the entry and hand it to `capaAttrs`:
+
+```tsx
+// pages/articles/[id].tsx on the Pages Router. A +page.server.ts load or
+// useAsyncData on the server hands over the flag the same way.
+import type { Entry } from "@capacms/sdk/next";
+import type { Articles } from "./capa-types";
+
+export async function getServerSideProps({ draftMode = false }) {
+  const entry = (await capa.entries.get<Articles>("articles", "entry-id"))!.data;
+  return { props: { entry, edit: draftMode } };
+}
+
+// in the component
+export default function Page({ entry, edit }: { entry: Entry<Articles>; edit: boolean }) {
+  return <h1 {...capaAttrs(entry, "title", edit)}>{entry.fields.title}</h1>;
+}
+```
+
+Or re-mark the entries where they arrive with `markEditEntries(data)` when the
+page is in edit mode. Tested on the Pages Router, SvelteKit and Nuxt.
+
 GraphQL reads are marked the same way, from `getCapaClient`, an edit-mode
 `createClient` or `graphql()` given `{ draftMode, headers }`. A node is an
 entry when it selected `id` and `model`, and `field` is the field as you
@@ -1362,6 +1403,7 @@ 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);
+  if (edit.robotsTag) response.headers.set("X-Robots-Tag", edit.robotsTag);
   return response;
 }
 ```
@@ -1415,18 +1457,124 @@ export function middleware(request: NextRequest) {
 `/api/draft` is the route handler shown under "Open a draft in your own site"
 above, reading `token` and `path`.
 
-**Cookies in a frame.** The editor frames your site from another site, and a
-browser only sends a cookie into a cross-site frame when it is
-`SameSite=None; Secure`. Next sets the draft-mode cookie that way in a
-production build. `next dev` sets it `SameSite=Lax`, so re-set it as
-`SameSite=None; Secure` in your draft route while developing (browsers accept
-`Secure` on `http://localhost`). Safari's third-party cookie blocking can still
-drop it, which is why every preview load carries a fresh token and step 3
-honours it on any page.
-
-**Let Capa frame the site.** Send
-`Content-Security-Policy: frame-ancestors 'self' https://app.capacms.com` (your
-admin origin) so the editor can frame the site and nothing else can.
+**Cookies in a frame.** The editor frames your site from another site. A
+browser sends a cookie into a cross-site frame only when it is
+`SameSite=None; Secure`, and Safari 26.2 and later only when it is
+`Partitioned` too. Next sets the draft-mode cookie with neither `Partitioned`
+nor `Max-Age`, so it is dropped in Safari's frame and, everywhere else, opens
+every draft on the site until the browser closes. Pass Next's `cookies` to
+`createPreviewRoute` and `exitPreviewRoute` and they re-set it as
+`HttpOnly; Secure; SameSite=None; Partitioned; Path=/; Max-Age=3600`, and
+delete it the same way. `maxAge` changes the hour. In your own route, call
+`frameDraftCookie(cookies)` after `enable()` and `clearDraftCookie(cookies)`
+after `disable()`. A browser that drops the cookie still gets a fresh token on
+every preview load, which step 3 honours on any page.
+
+Leave `redirect` out of both routes. Each then answers with its own 307,
+marked `X-Robots-Tag: noindex, nofollow`, `Referrer-Policy: no-referrer` (the
+token is in the URL) and `Cache-Control: private, no-store`. Next's
+`redirect()` cannot carry headers, so passing it keeps the old redirect.
+
+**Mark drafts, and let Capa frame them.** `capaHeaders()` returns rules for
+`next.config`'s `headers()` that send `X-Robots-Tag: noindex, nofollow` and
+`Content-Security-Policy: frame-ancestors 'self' https://app.capacms.com` on a
+request carrying the draft cookie or a `capa-preview`, `capa-edit` or
+`capa-view` query, and on nothing else. A visitor's response, cached or not,
+is unchanged. Pass `adminOrigins` to name another admin, such as one running
+locally, and pass the same list to `createPreviewRoute`. A browser applies
+every CSP it is sent, so if your site sends its own `frame-ancestors` or
+`X-Frame-Options`, leave them off draft responses with
+`missing: [{ type: "cookie", key: DRAFT_COOKIE }]` on that rule.
+`capaMiddleware` marks its edit-mode responses noindex too, and
+`resolveEditRequest` returns the value as `robotsTag`.
+
+### Add preview to a live site without changing it
+
+A live Next.js site that reads Capa with its own code keeps that code. Preview
+adds a branch that only draft mode switches on, and draft mode is off for
+every visitor, at build time and during ISR. Reading
+`(await draftMode()).isEnabled` leaves a static page static, so a visitor gets
+the same pages, headers and cache as before.
+
+1. **Read drafts in draft mode.** In the helper that fetches from Capa, before
+   the existing fetch, read the same URL with a draft key and no cache. The
+   data has the same shape, so every page renders unchanged.
+
+   ```ts
+   // lib/capa-draft.ts
+   import "server-only";
+   import { draftMode } from "next/headers";
+
+   export async function isDraft(): Promise<boolean> {
+     // draftMode() throws outside a request (generateStaticParams, some build steps).
+     try { return (await draftMode()).isEnabled; } catch { return false; }
+   }
+
+   // in the fetch helper, before the existing fetch, which stays as it is
+   if (await isDraft()) {
+     return fetch(`https://api.capacms.com/v2/api/${endpoint}${query}`, {
+       headers: { "x-api-key": process.env.CAPA_DRAFT_KEY! },
+       cache: "no-store",
+     }).then(parse); // the helper's existing parse
+   }
+   ```
+
+   The draft key is any key of yours whose environment is not `production`
+   (see Preview is a key, not a flag). Keep it server-only, never in a
+   `NEXT_PUBLIC_` variable, and keep the branch in a `server-only` module: a
+   helper a client component also imports would bundle it.
+
+2. **Add the preview and exit routes** with `createPreviewRoute({ draftMode,
+   cookies })` and `exitPreviewRoute({ draftMode, cookies })`, as in the Quick
+   start. Set `CAPA_API_URL` to `https://api.capacms.com` and `CAPA_KEY` to
+   the production key the site already reads with, server-only: the routes
+   check the editor's token with it.
+
+3. **Add the middleware behind a matcher**, so a visitor's request never runs
+   it. Next reads `config` from the file itself, so write the matcher out:
+
+   ```ts
+   // middleware.ts (proxy.ts on Next 16)
+   import { NextResponse } from "next/server";
+   import { capaMiddleware } from "@capacms/sdk/nextjs";
+
+   export const middleware = capaMiddleware({ NextResponse });
+   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" }] },
+     ],
+   };
+   ```
+
+4. **Add `capaHeaders()`** to `next.config`'s `headers()`, as in the Quick
+   start: drafts are marked noindex and only the Capa admin can frame them.
+
+5. **Start the overlay and tag fields in draft mode.** In the root layout:
+
+   ```tsx
+   const draft = await isDraft();
+   {draft ? <CapaOverlay adminOrigins={["https://app.capacms.com"]} /> : null}
+   ```
+
+   Tag an editable field with `{...capaAttrs({ id: entry.id }, "title", draft)}`.
+   With `draft` false it returns `{}`, so a visitor's HTML gains no
+   attribute. The field is its key in the entry, which is its namespace.
+
+6. **Route handlers that set their own `Cache-Control`** must send
+   `private, no-store` in draft mode. Otherwise a CDN keeps a draft fetched by
+   the editor's browser and serves it to everyone.
+
+Do not call `editMode()`, `getCapaClient()` or `resolveEditRequest()` from a
+static or ISR page or layout. Each reads `headers()`, which makes every route
+that calls it dynamic: the HTML stays the same, but the site loses ISR and
+renders every view. `isDraft()` above is the static-safe check. The editor's
+Published view then shows the static page without the overlay.
+
+In Capa, set the project's preview URL to the site's production origin, and
+give each model with a page a route pattern, or Preview has no link to open.
 
 ### The protocol
 

package/dist/config.d.ts

@@ -1,38 +1,3 @@
-/**
- * Client configuration, and the one thing about it that is not obvious.
- *
- * PREVIEW IS A KEY, NOT A FLAG
- * Capa gates unpublished content on the API key's `environment` column, not on
- * anything in the request:
- *
- *     // apps/api/src/routes/v2/api.ts:203
- *     const environment = req.apiKeyEnvironment || "production";
- *     const includeDrafted = environment === "production" ? false : true;
- *
- * So there is no `?preview=true` to pass, and `getContent(ns, id, {preview})`
- * CANNOT be implemented against a published key — the server would ignore it.
- * The honest surface is one client per key:
- *
- *     const capa    = createClient({ ...cfg, apiKey: PUBLISHED_KEY })
- *     const preview = createClient({ ...cfg, apiKey: PREVIEW_KEY })
- *
- * Note also that the comparison above is exact and case-sensitive against a
- * free-text column, so ANY environment that is not literally "production"
- * returns drafts — `staging`, `development`, `draft`, and equally a typo like
- * "Production".
- *
- * AND A CLIENT CANNOT FIND OUT WHICH IT HAS.
- * There is deliberately no `includesDrafts()` here, because it cannot be
- * implemented: `apiKeyEnvironment` is set in verifyApiKey.ts:57, consumed
- * internally to compute `includeDrafted`, and returned to the caller by NO
- * endpoint. /v2/schema carries only {models, relations, checksum, generatedAt}.
- *
- * So a site handed a `draft`, `staging` or `development` key serves unpublished
- * content to the public, and has no way to detect it — not at startup, not at
- * runtime, not from any response. In production-shaped data 29 of 74 keys are
- * non-production. Whatever this SDK offers, it cannot make that safe; the fix
- * is for Capa to report the key's environment on a read a client already makes.
- */
 export interface CapaConfig {
     /** Base URL of the Capa API, e.g. https://api.example.com. No trailing slash required. */
     baseUrl: string;

package/dist/config.js

@@ -1,13 +1,59 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveConfig = resolveConfig;
+/**
+ * Client configuration, and the one thing about it that is not obvious.
+ *
+ * PREVIEW IS A KEY, NOT A FLAG
+ * Capa gates unpublished content on the API key's `environment` column, not on
+ * anything in the request:
+ *
+ *     // apps/api/src/routes/v2/api.ts:203
+ *     const environment = req.apiKeyEnvironment || "production";
+ *     const includeDrafted = environment === "production" ? false : true;
+ *
+ * So there is no `?preview=true` to pass, and `getContent(ns, id, {preview})`
+ * CANNOT be implemented against a published key — the server would ignore it.
+ * The honest surface is one client per key:
+ *
+ *     const capa    = createClient({ ...cfg, apiKey: PUBLISHED_KEY })
+ *     const preview = createClient({ ...cfg, apiKey: PREVIEW_KEY })
+ *
+ * Note also that the comparison above is exact and case-sensitive against a
+ * free-text column, so ANY environment that is not literally "production"
+ * returns drafts — `staging`, `development`, `draft`, and equally a typo like
+ * "Production".
+ *
+ * AND A CLIENT CANNOT FIND OUT WHICH IT HAS.
+ * There is deliberately no `includesDrafts()` here, because it cannot be
+ * implemented: `apiKeyEnvironment` is set in verifyApiKey.ts:57, consumed
+ * internally to compute `includeDrafted`, and returned to the caller by NO
+ * endpoint. /v2/schema carries only {models, relations, checksum, generatedAt}.
+ *
+ * So a site handed a `draft`, `staging` or `development` key serves unpublished
+ * content to the public, and has no way to detect it — not at startup, not at
+ * runtime, not from any response. In production-shaped data 29 of 74 keys are
+ * non-production. Whatever this SDK offers, it cannot make that safe; the fix
+ * is for Capa to report the key's environment on a read a client already makes.
+ */
+/**
+ * The platform fetch, called through `globalThis` on every request. Storing
+ * `globalThis.fetch` and calling it as a method of the config object gives it
+ * the wrong `this`, and a browser refuses that ("Illegal invocation"). Looking
+ * it up per call also picks up a fetch a framework patches in later.
+ */
+function defaultFetch() {
+    if (typeof globalThis.fetch !== "function")
+        return undefined;
+    return ((input, init) => globalThis.fetch(input, init));
+}
 function resolveConfig(config) {
     const missing = ["baseUrl", "apiKey", "tenantId"].filter((k) => !config[k]);
     if (missing.length) {
         throw new Error(`@capacms/sdk: missing ${missing.join(", ")}. ` +
             `createClient needs baseUrl, apiKey and tenantId.`);
     }
-    const fetchImpl = config.fetch ?? globalThis.fetch;
+    const fetchImpl = config.fetch ?? defaultFetch();
     if (typeof fetchImpl !== "function") {
         throw new Error("@capacms/sdk: no fetch available. Pass one via config.fetch on older runtimes.");
     }

package/dist/next/client.d.ts

@@ -9,9 +9,9 @@ export interface CapaNextConfig {
     baseUrl: string;
     /**
      * A `cap_` key, or the legacy key a site already holds: `pk_`, `sk_`, or
-     * an older key with no prefix. A legacy key reads through every read call
-     * and warns once per process; `preview()` and draft reads take a `cap_` key
-     * only.
+     * an older key with no prefix. A legacy key reads through every read call,
+     * `preview()` included, and warns once per process; the draft clients of
+     * `@capacms/sdk/nextjs` take a `cap_` key only.
      */
     apiKey: string;
     version: string;
@@ -210,7 +210,7 @@ export interface EntriesResource {
  * One suggestion drawn from a page's own reads.
  *
  * Computed on the API, never here. Three clients want this answer (this SDK,
- * the Capa admin and `@capa/mcp`), and a second implementation of "this page
+ * the Capa admin and `@capacms/mcp`), and a second implementation of "this page
  * over-fetches" would drift from the first the moment a threshold moved.
  */
 export interface PageInsight {
@@ -387,8 +387,9 @@ export type BuilderCallOptions<O extends GraphQLCallOptions = GraphQLCallOptions
 /**
  * `client.graphql` over one way of reading a document: called with a
  * document, and `query()` printing a selection's document for it. `createClient`
- * reads straight from the API, and `getCapaClient` from `/nextjs` through
- * Next's data cache, with the same refusals.
+ * reads straight from the API, and `getCapaClient` from `/nextjs` the same way
+ * unless a call gives `tags` or `revalidate`, then through Next's data cache,
+ * with the same refusals.
  */
 export declare function graphqlClient<Q, O extends GraphQLCallOptions>(read: (document: string, variables: Record<string, unknown> | undefined, options: O | undefined) => Promise<GraphQLResult<unknown>>): GraphQLClient<Q, O>;
 export interface CapaNextClient<Q = UntypedQuery, O extends GraphQLCallOptions = GraphQLCallOptions> {
@@ -400,8 +401,8 @@ export interface CapaNextClient<Q = UntypedQuery, O extends GraphQLCallOptions =
      * Returns the claim, or NULL when the token is invalid or expired, because
      * both mean the same thing to a preview route: do not enable draft mode.
      * Every other failure throws, so a Capa outage does not look like a bad link.
-     * Needs a `cap_` key: a client built with a legacy key throws a
-     * `TypeError` here before any request.
+     * Takes any key the site holds, a legacy `pk_`, `sk_` or unprefixed key
+     * included: Capa answers a token minted for another tenant as invalid.
      */
     preview(token: string, options?: CallOptions): Promise<PreviewClaim | null>;
     me<T = Record<string, unknown>>(options?: CallOptions): Promise<T>;

package/dist/next/client.js

@@ -18,6 +18,19 @@ const typed_1 = require("./graphql/typed");
 var errors_2 = require("./errors");
 Object.defineProperty(exports, "CapaError", { enumerable: true, get: function () { return errors_2.CapaError; } });
 Object.defineProperty(exports, "isCapaError", { enumerable: true, get: function () { return errors_2.isCapaError; } });
+/**
+ * The platform fetch, called through `globalThis` on every request. Storing
+ * `globalThis.fetch` and calling it as a method of the config object gives it
+ * the wrong `this`, and a browser refuses that ("Failed to execute 'fetch' on
+ * 'Window': Illegal invocation"); Node does not care, which is why only
+ * browser reads broke. Looking it up per call also picks up a fetch a
+ * framework patches in after the client is built (Next does).
+ */
+function defaultFetch() {
+    if (typeof globalThis.fetch !== "function")
+        return undefined;
+    return ((input, init) => globalThis.fetch(input, init));
+}
 /**
  * What a `Capa-Schema` value may look like: hex, 8 to 64 characters.
  *
@@ -35,8 +48,9 @@ const BUILDER_NOT_PERSISTED = "@capacms/sdk/next: graphql.query() cannot send pe
 /**
  * `client.graphql` over one way of reading a document: called with a
  * document, and `query()` printing a selection's document for it. `createClient`
- * reads straight from the API, and `getCapaClient` from `/nextjs` through
- * Next's data cache, with the same refusals.
+ * reads straight from the API, and `getCapaClient` from `/nextjs` the same way
+ * unless a call gives `tags` or `revalidate`, then through Next's data cache,
+ * with the same refusals.
  */
 function graphqlClient(read) {
     const query = async (selection, options) => {
@@ -61,7 +75,7 @@ function resolveNextConfig(config) {
     if (value.contract !== undefined && value.contract !== 1) {
         throw new Error("@capacms/sdk/next: contract must be 1 when provided.");
     }
-    const fetchImpl = value.fetch ?? globalThis.fetch;
+    const fetchImpl = value.fetch ?? defaultFetch();
     if (typeof fetchImpl !== "function") {
         throw new Error("@capacms/sdk/next: no fetch available. Pass one via config.fetch.");
     }
@@ -487,7 +501,8 @@ function createClient(config) {
             return readSchema(options.signal);
         },
         async preview(token, options = {}) {
-            (0, key_family_1.requirePreviewKey)(resolved.apiKey);
+            // Any key the site holds, legacy included: the API checks the token
+            // belongs to the key's own tenant (see key-family.ts).
             const query = new URLSearchParams();
             query.set("token", token);
             try {

package/dist/next/field-names.js

@@ -28,7 +28,7 @@ exports.readPath = readPath;
  *
  * The API's own writer is `writeName` in `@capa/shared`. This package ships
  * with no runtime dependencies, so the rule is copied here and in
- * `@capa/mcp`, and test/fixtures/field-names.json pins all three to the same
+ * `@capacms/mcp`, and test/fixtures/field-names.json pins all three to the same
  * vectors.
  */
 const system_keys_1 = require("./system-keys");

package/dist/next/graphql/introspection.d.ts

@@ -4,7 +4,7 @@
  *
  * One request carries both the standard introspection selection and the
  * `version` root field, so a schema summary always says which platform version
- * it describes. Kept byte-stable: `@capa/mcp` sends the same text, and a
+ * it describes. Kept byte-stable: `@capacms/mcp` sends the same text, and a
  * persisted copy of it is one hash for every client.
  *
  * Deprecated arguments and input fields are asked for too, with their

package/dist/next/graphql/introspection.js

@@ -5,7 +5,7 @@
  *
  * One request carries both the standard introspection selection and the
  * `version` root field, so a schema summary always says which platform version
- * it describes. Kept byte-stable: `@capa/mcp` sends the same text, and a
+ * it describes. Kept byte-stable: `@capacms/mcp` sends the same text, and a
  * persisted copy of it is one hash for every client.
  *
  * Deprecated arguments and input fields are asked for too, with their

package/dist/next/graphql/plan.js

@@ -80,7 +80,7 @@ function didYouMean(wanted, candidates) {
 /**
  * The refusal for a model the key reads that GraphQL leaves out (N1): REST
  * serves it, so the message names that read and why, and suggests no other
- * model. `@capa/mcp` says the same, pinned by a test.
+ * model. `@capacms/mcp` says the same, pinned by a test.
  */
 function restOnlyModel(namespace, restOnly) {
     // N1 leaves models out when their type names would collide, as these
@@ -176,7 +176,7 @@ function checkSort(value, model, where) {
 // A spec written as REST writes a read (`author.name` or `author(name)` for a
 // relation's fields, `*` for every field, `-publishedAt` for a sort) is
 // refused with what to write instead, spelled out, since the same read is one
-// edit away. @capa/mcp refuses them in the same words, pinned by
+// edit away. @capacms/mcp refuses them in the same words, pinned by
 // test/fixtures/graphql-rest-forms.json.
 /** A REST sort key as a sort value: `-publishedAt` is `publishedAt_DESC`, `author.name` is `author__name_ASC`. */
 function restSortValue(value) {