@capacms/sdk 1.0.0-next.0

package/README.md

@@ -0,0 +1,678 @@
+# @capacms/sdk
+
+## The `/api/` client (`@capacms/sdk/next`)
+
+Install the SDK from the `next` dist tag:
+
+```sh
+pnpm add @capacms/sdk@next
+```
+
+Create one client per key and pin the platform version in code:
+
+```ts
+import { createClient, CapaError } from "@capacms/sdk/next";
+
+const capa = createClient({
+  baseUrl: process.env.CAPA_BASE_URL!,
+  apiKey: process.env.CAPA_API_KEY!,       // cap_live_... or cap_test_...
+  version: "2026-10-01",
+  contract: 1,
+});
+```
+
+The `/api/` client sends `x-api-key`, `Capa-Version`, optional
+`Capa-Contract`, and `Accept: application/json`. It never sends
+`X-Tenant-Key`; the tenant comes from the `cap_` key.
+
+### Entries
+
+```ts
+const page = await capa.entries.list("articles", {
+  select: [
+    "title",
+    "views",
+    { author: ["name"] },
+    { coauthors: { select: ["name"], limit: 5, sort: "-name" } },
+  ],
+  filter: {
+    views: { gte: 10 },
+    "author.name": { eq: "Ada Vale" },
+  },
+  sort: ["-views"],
+  limit: 25,
+  count: true,
+});
+
+for await (const entry of capa.entries.iterate("articles", { select: ["title"] })) {
+  console.log(entry.fields.title);
+}
+
+const one = await capa.entries.get("articles", "entry-id", {
+  select: ["title", { author: "*" }],
+});
+```
+
+`select` may be the grammar string from `docs/api/entries.md` or the object
+form above. Lists return `{ data, page, meta, cacheTags }`; singles return
+`{ data, meta, cacheTags }`. `cacheTags` is parsed from the `Surrogate-Key`
+header. `get()` returns `null` for `404 entry_not_found` and throws every other
+error.
+
+Filters use the `/api/` operators:
+
+```ts
+await capa.entries.list("articles", {
+  filter: {
+    id: { in: ["a", "b"] },
+    views: { gte: 10 },
+    tags: { hasAny: ["news", "launch"] },
+  },
+  where: { or: [{ featured: { eq: true } }, { views: { gt: 100 } }] },
+});
+```
+
+Unknown filter operators throw a local `TypeError` before any request is sent.
+Per-call `{ signal }` is forwarded to `fetch`.
+
+### Errors
+
+```ts
+try {
+  await capa.entries.list("articles", { limit: 500 });
+} catch (error) {
+  if (error instanceof CapaError) {
+    console.log(error.status, error.code, error.param, error.hint, error.requestId);
+  }
+}
+```
+
+`CapaError` carries `{ status, type, code, message, param, hint, requestId,
+docs }`. A non-JSON response is reported as `code: "unparseable_response"`.
+
+### Next.js helpers (`@capacms/sdk/nextjs`)
+
+```ts
+import { createClient } from "@capacms/sdk/next";
+import { withCache, tagsFor } from "@capacms/sdk/nextjs";
+
+const fetchWithCache = withCache(fetch, {
+  tags: tagsFor({ model: articleModelId }),
+  revalidate: 60,
+});
+
+const capa = createClient({ baseUrl, apiKey, version: "2026-10-01", fetch: fetchWithCache });
+```
+
+`withCache` merges `{ next: { tags, revalidate } }` into every fetch call.
+`tagsFor` builds Capa surrogate keys: `m:`, `e:`, `k:`, and `t:`.
+
+Webhook revalidation pairs with the existing signature verifier:
+
+```ts
+// app/api/capa/route.ts
+import { revalidateTag } from "next/cache";
+import { revalidateFromWebhook } from "@capacms/sdk/nextjs";
+import { verifyWebhookSignature } from "@capacms/sdk";
+
+export async function POST(request: Request) {
+  const raw = await request.text();
+  const ok = await verifyWebhookSignature({
+    payload: raw,
+    header: request.headers.get("capa-signature") ?? "",
+    secret: process.env.CAPA_WEBHOOK_SECRET!,
+  });
+  if (!ok) return new Response("bad signature", { status: 400 });
+
+  await revalidateFromWebhook({
+    payload: JSON.parse(raw),
+    revalidateTag,
+  });
+
+  return new Response("ok");
+}
+```
+
+`draftClient` is server-only. Pass Next's draft state in from the caller so the
+SDK never imports `next/*`:
+
+```ts
+import { draftMode } from "next/headers";
+import { draftClient } from "@capacms/sdk/nextjs";
+
+const capa = await draftClient({
+  production,
+  draft,
+  isDraft: async () => (await draftMode()).isEnabled,
+});
+```
+
+## Typed select and codegen
+
+`Select<T>` is exported from `@capacms/sdk/next`. `capa-codegen` keeps the legacy
+`/v2/schema/types` shape for schemas without relations. When a schema has
+relations, codegen wraps them in branded helpers:
+
+```ts
+export type CapaRelation<T> = T & { readonly __capaRelation: "one"; readonly __capaRelationTarget: T };
+export type CapaRelationList<T> = T[] & { readonly __capaRelation: "many"; readonly __capaRelationTarget: T };
+
+export interface Article {
+  title?: string;
+  author?: CapaRelation<Author>;
+  coauthors?: CapaRelationList<Author>;
+}
+
+export type ArticleSelect = import("@capacms/sdk/next").Select<Article>;
+```
+
+Those brands let TypeScript tell scalar fields from relation fields, so misspelled
+fields and invalid nested selects fail in consumer typechecks.
+
+## Pages and preview
+
+Capa can tell you which of **your** pages read which entries, and it can open a
+draft in your own site. Both are opt in and both live on `@capacms/sdk/next` and
+`@capacms/sdk/nextjs`.
+
+### Tell Capa which page a read is for
+
+Set `page` and every read sends a `Capa-Page` header. Capa records it and
+answers exactly as it would have without it: same body, same `ETag`, same cache
+key. Nothing about your site changes except that Capa can now answer "what
+breaks if I unpublish this?".
+
+```ts
+import { createClient } from "@capacms/sdk/next";
+import { routeOf } from "@capacms/sdk/nextjs";
+
+const capa = createClient({ baseUrl, apiKey, version: "2026-10-01" });
+
+// In app/blog/[slug]/page.tsx
+const posts = await capa.entries.list("articles", { page: routeOf(import.meta.url) });
+```
+
+`routeOf` turns a Next route file into the page string: `/blog/[slug]`. It
+drops route groups `(marketing)`, parallel slots `@modal`, the leaf file name
+and the extension. Write the string out by hand if you prefer; `routeOf` exists
+so that moving a folder cannot silently split one page's telemetry in two. Set
+`page` on the config instead when a client serves exactly one page; a value on
+the call wins over one on the config.
+
+A malformed value throws a `TypeError`. Capa itself ignores a header it cannot
+store, because a mangled page identity must never take a blog down, so the SDK
+is the place a typo surfaces.
+
+### Read the page list
+
+```ts
+const { data: pages } = await capa.pages.list();
+// [{ id: "/blog/[slug]", kind: "both", models: [...], reads30d: 812, ... }]
+
+const appearsOn = await capa.pages.list({ entry: "entry-id" });
+// only the pages that read that entry, each with entryReads
+```
+
+A page is `declared` when a model carries a route for it, `observed` when a read
+arrived carrying it as `Capa-Page`, and `both` when a correctly wired site has
+done both. `capa.pages.get("/blog/[slug]")` adds the entries the page reads, the
+queries it makes and a per-day read count, and returns `null` for a page Capa
+has never heard of.
+
+### Tell Capa which schema you built against
+
+Pass `CAPA_SCHEMA_CHECKSUM` from your generated types and every read sends a
+`Capa-Schema` header:
+
+```ts
+import { CAPA_SCHEMA_CHECKSUM } from "./capa-types";
+
+const capa = createClient({
+  baseUrl,
+  apiKey,
+  version: "2026-10-01",
+  schemaChecksum: CAPA_SCHEMA_CHECKSUM,
+});
+```
+
+`capa-codegen` writes that constant into the generated file on every run, so it
+is always the schema the committed types describe. It buys one thing nothing
+else can work out: whether your deployed site was built against the models the
+project has now. A site that has never been rebuilt keeps sending perfectly
+valid requests, so without the stamp a stale build is invisible, and with it the
+page detail says "the site was generated from an older schema" and tells you to
+re-run `capa-codegen`.
+
+Telemetry only, like `page`: it does not change a response, a cache key or an
+`ETag`, and Capa ignores a value it cannot parse. A bad value throws a
+`TypeError` where the client is built, because a stamp dropped in silence looks
+exactly like a site that is up to date.
+
+### Read the suggestions
+
+`capa.pages.get(page)` carries an `insights` array: suggestions drawn from that
+page's own reads, computed by Capa so that this SDK, the Capa admin and
+`@capa/mcp` all read one answer.
+
+```ts
+const detail = await capa.pages.get("/blog/[slug]");
+for (const insight of detail?.data.insights ?? []) {
+  console.log(insight.severity, insight.title, insight.evidence);
+  if (insight.rewrite?.select) console.log("try select=" + insight.rewrite.select);
+}
+```
+
+| kind | what it found |
+|---|---|
+| `overfetch` | the page sends no `select` on a wide model or one with relations |
+| `fanout` | the page reads one model an entry at a time instead of filtering |
+| `cache` | most of the page's reads miss or bypass the edge |
+| `drift` | the `Capa-Schema` the page sent is not the project's current one |
+| `unused` | entries no page reads, on `pages.list()` under `meta.insights` |
+
+Each one carries `title` (one sentence), `detail` (why it matters), `evidence`
+(every number the rule used, so you can check the claim) and, where there is
+one, `rewrite` with a canonical `select`, a set of query parameters or a whole
+URL you can paste.
+
+Every `queries[]` row on the detail also carries `selection`, the parsed
+Selection IR for its `select`, or `selectionError` when the stored `select` no
+longer parses against the model's current schema. That second case is usually
+not a bug: it is a query naming a field the project has since removed.
+
+`unused` insights live on the LIST rather than on a page, because "no page reads
+this" is a claim about every page at once. They are in `meta.insights` on
+`capa.pages.list()`.
+
+### Open a draft in your own site
+
+An editor presses Preview in Capa and gets a link to **your** site carrying a
+signed token. Your site asks Capa whether the token is good, enables draft mode
+and redirects to the page. The token is short lived and names one entry.
+
+```ts
+// app/api/preview/route.ts
+import { draftMode } from "next/headers";
+import { redirect } from "next/navigation";
+import { createClient } from "@capacms/sdk/next";
+import { preview } from "@capacms/sdk/nextjs";
+
+export async function GET(request: Request) {
+  const token = new URL(request.url).searchParams.get("capa-preview") ?? "";
+  const claim = await preview(token, createClient({ baseUrl, apiKey, version }));
+  if (!claim) return new Response("Invalid or expired preview link", { status: 401 });
+  (await draftMode()).enable();
+  redirect(claim.path ?? "/");
+}
+```
+
+`preview` returns `null` for an invalid or an expired token, because a preview
+route does the same thing for both: do not enable draft mode. Anything else
+throws, so a Capa outage is never mistaken for a stale link. `claim.path` is
+resolved fresh on every call rather than baked into the token, so fixing a route
+or a slug takes effect immediately; it is `null` when the model has no route, and
+your own routing is the fallback.
+
+Draft mode still needs a draft key. `draftClient` selects one:
+
+```ts
+const capa = await draftClient({
+  production: { baseUrl, apiKey: PUBLISHED_KEY, version },
+  draft: { baseUrl, apiKey: PREVIEW_KEY, version },
+  isDraft: async () => (await draftMode()).isEnabled,
+});
+```
+
+Set the preview base URL for your project in Capa (Settings), otherwise the
+editor sees the path without a link to open it.
+
+## Not yet
+
+`--select-from-depth`, `capa convert-url`, `capa persist`, GraphQL, and `/api/`
+writes are not in this release.
+
+## The legacy `/v2/api` client
+
+A read client for Capa, plus two arrangement writes (`workspaces`,
+`models.setLayout`) and `capa-codegen`, a command that pulls a tenant's
+generated TypeScript so content is typed at the call site.
+
+```ts
+import { createClient } from "@capacms/sdk";
+import type { BlogPost } from "./capa-types";        // written by capa-codegen
+
+const capa = createClient({
+  baseUrl: process.env.CAPA_BASE_URL!,
+  apiKey: process.env.CAPA_API_KEY!,
+  tenantId: process.env.CAPA_TENANT_ID!,
+});
+
+const page = await capa.listContent<BlogPost>("blog_post", { limit: 10 });
+const one  = await capa.findOne<BlogPost>("blog_post", { handle: "hello" });
+```
+
+## Codegen
+
+```
+CAPA_BASE_URL=... CAPA_API_KEY=... CAPA_TENANT_ID=... capa-codegen --out src/capa-types.ts
+```
+
+Exit codes: `0` wrote or already current, `1` failed, `2` `--check` found a diff.
+`--check` is the CI mode — it fails when the committed file is stale.
+
+**Commit the output.** Not generated at install (needs credentials during
+`npm install`, which breaks CI images and Docker builds) and not at build time
+(makes every build network-dependent, and a Capa outage a build outage). A
+committed file is also what makes the feature useful: "a model changed, so the
+build fails" only helps if a human can see *what* changed, and a committed file
+turns that into a reviewable diff instead of a wall of `tsc` errors.
+
+Re-running when nothing changed costs **one conditional request returning 0
+bytes** — see below.
+
+## Three server-side rough edges, handled here
+
+The API is mid-port to a byte-parity bar, so changing a customer-facing response
+costs a signed exception. None of these is worth one, because each can be
+handled on this side.
+
+**1. `/v2/schema/types` has no ETag,** so it cannot be revalidated. `/v2/schema`
+*does* — it returns a `checksum` and honours `If-None-Match` with a 304, and that
+checksum is `sha256({models, relations})`, exactly what the types are generated
+from. So codegen gates on it and fetches types only when the schema moved.
+
+**2. The generator orders models by display name,** while interfaces are *named*
+from the namespace (`blogs_home_section` → `BlogsHomeSection`). Renaming a
+model's display name therefore reorders the whole file without changing a single
+type — a false "your types changed" in the exact mechanism this feature rests
+on. `normalizeTypes` re-sorts by interface name, so the committed file is stable
+under renames.
+
+**3. A model field named `id` overwrites the instance id** (#4628). Rows are
+built as `{...instance, ...formatInstanceData(instance)}` (`routes/v2/api.ts`).
+Hoisted fields are spread second, so `id`, `title` and `tags` are overwritten.
+In one ordinary tenant, 20 of 20 models shadow `title` and 7 of 20 shadow `id`.
+
+A server-side fix for this shipped briefly as #4628 (`instanceId` appended to
+every public row) and was reverted on 2026-09-20 under the public-surface
+freeze: `/v2/api`, `/v3/api`, the `/v1` public reads and `/files` answer the
+bytes the legacy API answers, and a row key that resolves the shadowing is
+planned for the next API version. **So a row from today's server carries no
+`instanceId`, and `row.id` may be a content value.**
+
+The client already handles both: `instanceIdOf` prefers `instanceId` when a row
+has one and falls back to `id` when that is a UUID, so nothing here changes when
+the next version starts sending it.
+
+So **read `Page.ids`, not `row.id`**:
+
+```ts
+const page = await capa.listContent("shopify_page");
+page.ids[0]        // the instance UUID when the row has one to give
+page.data[0].id    // the model's OWN id field whenever one exists
+```
+
+`Page.ids` is `string | null` per row: `null` means the model shadows `id` and
+the server sent nothing else to read it from, which is the state of every server
+today. `getContentById` throws on a non-UUID rather than spending a request on a
+guaranteed 400.
+
+`search()` is the same story. `/v2/api/search?extended=true` hoists fields the
+same way, so `SearchHit.id` is read through the same `instanceIdOf` and has the
+same `string | null` type.
+
+## Preview is a key, not a flag
+
+Capa gates unpublished content on the API key's `environment` column, not on
+anything in the request (`routes/v2/api.ts:203`). There is no `?preview=true`, so
+preview is a second client:
+
+```ts
+const capa    = createClient({ ...cfg, apiKey: PUBLISHED_KEY });
+const preview = createClient({ ...cfg, apiKey: PREVIEW_KEY });
+```
+
+The comparison is exact and case-sensitive against a free-text column, so **any**
+environment that is not literally `production` returns drafts — including a typo
+like `Production`. And a client cannot find out which it holds: `apiKeyEnvironment`
+is consumed internally and returned by no endpoint, so a site handed a `draft`
+key serves unpublished content publicly with no way to detect it.
+
+## Not included
+
+**Caching.** Every framework does it differently and owning it means
+reimplementing all of them badly. Plain `fetch` returning plain data lets Next's
+fetch cache and React Router loaders work natively. What the host cannot know is
+which surrogate keys a response carries, so those are surfaced as
+`Page.cacheTags` for CDN purging.
+
+**`getBySlug`.** Capa has no slug convention — the field is `handle` on
+`shopify_page`, `product_handle` on `judge_me_review`, `bloghandle` on
+`shopify_article`, and nothing marks one as *the* slug. `findOne(ns, {handle})`
+is explicit instead. A slug marker belongs on the model, in Capa.
+
+**Content writes.** `/v2/agent/model-instances` exists and an API key reaches
+it, so an SDK that can silently publish a draft is now technically possible.
+That wants a deliberate surface of its own rather than another method quietly
+added to the client, so it is absent rather than half-built. The one exception
+is `scheduledActions`, below, and the exception is narrow on purpose: a schedule
+is a request that leaves a row you can read, show and cancel. Publishing *now*
+leaves the caller holding the only copy of what happened.
+
+This section used to say the SDK could not write at all, because `verifyApiKey`
+guarded five route files carrying 15 GETs and no write verb. That stopped being
+true with the agent surface (`#383`) and `tenant_api_keys.permission` becoming a
+real control (`#4646`). Two things write today, and both touch arrangement
+rather than content:
+
+```ts
+await capa.workspaces.apply(id, { tree });        // the admin rail (0h, 0t)
+await capa.models.setLayout(id, layout);          // the entry editor (0m)
+await capa.models.setLayout(id, null);            // back to the linear editor
+```
+
+Reading has two shapes. `models.getLayout(id)` is the document or null;
+`models.getLayoutInfo(id)` is the same read with the model's `embedByDefault`
+beside it, which is what decides a relation field with no `display` on its
+layout node (section 0m.8, and it applies in linear mode too):
+
+```ts
+const { layout, embedByDefault } = await capa.models.getLayoutInfo(id);
+```
+
+A workspace `tree` is a flat `WorkspaceDocNode[]` since 0t: one list of folders
+the customer named, each holding any mix of `{model}`, `{instance}`,
+`{media_folder}` and further folders. The 0h shape, `{ model, content, media }`,
+is still accepted for one release and lands in folders called Models, Content
+and Media.
+
+`workspaces.*` needs a key with `write`; `models.setLayout` needs one with
+`agent`, because it writes a MODEL and that is the gate every other model write
+asks for. `models.getLayout` needs only `read`. A refused document comes back as
+`CapaError` carrying the API's own `{ error, path }`, where `path` names the
+node to fix. `apps/api/LAYOUT.md` has the rules and a worked example.
+
+## Scheduling a publish
+
+```ts
+const { batchId, resolved, actions, replaced } = await capa.scheduledActions.create({
+  action: "publish",                                   // or "unpublish"
+  targets: [{ type: "instance", id: instanceId }],     // 1 to 500
+  wallTime: "2026-10-01T09:00",                        // local clock, NO offset
+  timezone: "America/New_York",                        // IANA name
+});
+```
+
+**Instance targets only, from a key.** A `{ type: "model" }` target needs the
+`model:publish` permission, and no API key bundle carries it in phase 1, so the
+server answers 403 whatever the key. Scheduling a schema publish is an admin
+session job until a bundle grants it.
+
+**Send a wall clock and a zone, not an instant.** `wallTime` carrying a `Z` or a
+`+02:00` is refused, here and by the server, because the two together are the
+only way to say "9am local, whatever the offset turns out to be". The server
+converts and reports what it decided in `resolved`:
+
+```ts
+resolved.runAt            // "2026-10-01T13:00:00.000Z"
+resolved.runAtInTimezone  // "2026-10-01T09:00:00-04:00"
+resolved.note             // null, or a sentence about daylight saving
+```
+
+`resolved.note` is the one field worth showing a person verbatim. A wall time
+that does not exist (the spring gap) resolves forward and a wall time that
+happens twice (the autumn overlap) takes the earlier offset, and the note says
+which happened: `02:30 does not exist on 8 Mar 2026 in America/New_York,
+publishing at 03:30 EDT`.
+
+`replaced` holds the ids of actions that were cancelled to make room. A target
+may have one active publish and one active unpublish at a time, so scheduling a
+second publish for the same entry replaces the first rather than queueing it.
+
+**`versionId` is optional and you usually want it absent.** With no version
+pinned, the action publishes the latest draft at fire time, which is what an
+editor who fixes a typo on Tuesday expects of a schedule made on Monday.
+
+The rest of the resource:
+
+```ts
+await capa.scheduledActions.list({ status: ["pending", "running"], limit: 50 });
+await capa.scheduledActions.list({ targetId: instanceId });
+await capa.scheduledActions.get(id);                   // null when there is none
+await capa.scheduledActions.reschedule(id, { wallTime, timezone });  // + resolved
+await capa.scheduledActions.cancel(id);
+await capa.scheduledActions.retry(id);                 // a NEW row, see below
+```
+
+`retry` does not reopen the failed action. It creates a new `pending` one with
+`retryOfId` pointing at the original, so what failed stays readable. Expect two
+rows and read the newer one.
+
+Statuses are `pending`, `running`, `done`, `failed`, `dead`, `cancelled`. Only
+`pending` can be rescheduled or cancelled: a `running` action is being executed
+right now and `cancel` answers 409 `already_running`. `resultVersionId` on a
+`done` row is the version that went live.
+
+Reading needs a `read` key; every write here needs `instance:publish`, which the
+`write`, `delete` and `agent` bundles carry. A refusal is a `CapaError` with the
+API's own `{ error, code }`. The operator's side of all of this, including what
+to do when an action fails at 3am, is `docs/PUBLISHING.md`.
+
+## Webhooks
+
+Two halves that do not need each other. The verifier is clientless, so a
+receiver imports one function and nothing else. The resource manages endpoints,
+and it is the only thing in this SDK that needs a session token rather than an
+API key.
+
+### Verifying a delivery
+
+```ts
+import { verifyWebhookSignature } from "@capacms/sdk";
+
+export async function POST(request: Request) {
+  const body = await request.text();                 // the RAW body, see below
+  const ok = await verifyWebhookSignature({
+    payload: body,
+    header: request.headers.get("capa-signature") ?? "",
+    secret: process.env.CAPA_WEBHOOK_SECRET!,
+  });
+  if (!ok) return new Response("bad signature", { status: 400 });
+
+  const event = JSON.parse(body);
+  // event.id is stable across retries and redeliveries: store it and ignore
+  // one you have already handled.
+  return new Response("ok");
+}
+```
+
+**The payload must be the bytes that arrived.** The signature covers
+`"<t>.<body>"`, and a body that has been through `JSON.parse` and
+`JSON.stringify` again is a different string. Express needs
+`express.raw({ type: "application/json" })`, Fastify needs a raw-body parser on
+the route, Next's app router gives you `await request.text()`. A `Buffer` or
+`Uint8Array` can be passed straight in.
+
+`verifyWebhookSignature` is `async` because it uses WebCrypto rather than
+`node:crypto`, which is what lets it run unchanged in Node, Bun, Deno,
+Cloudflare Workers, Vercel's edge runtime and a browser. It returns `false`
+rather than throwing for every bad input: a malformed header, a missing secret,
+a timestamp outside the tolerance (5 minutes by default, `toleranceSeconds` to
+change it), or a body that does not match.
+
+During the 24 hours after a rotation Capa sends two `v1=` entries, the new
+secret first. Either one verifies, so a receiver can be updated any time inside
+that window without dropping a request.
+
+### Managing endpoints
+
+```ts
+const capa = createClient({
+  baseUrl: process.env.CAPA_BASE_URL!,
+  apiKey: process.env.CAPA_API_KEY!,
+  tenantId: process.env.CAPA_TENANT_ID!,
+  accessToken: sessionJwt,                 // from POST /v2/user/login
+});
+
+const { secret, ...endpoint } = await capa.webhooks.endpoints.create({
+  name: "Site rebuild",
+  url: "https://example.com/hooks/capa",
+  events: ["instance.published", "instance.unpublished", "instance.deleted"],
+});
+// `secret` is here ONCE. Store it now.
+```
+
+`createClient` still needs `apiKey` and `tenantId` to construct at all, so a
+script that only ever calls `webhooks.*` has to pass something non-empty for
+both. Any placeholder will do, because no webhook call reads either one.
+
+**The tenant comes from the session, not from `tenantId`.** These routes read
+the current tenant off the logged-in user's token, so the `tenantId` you passed
+to `createClient` is ignored for every `webhooks.*` call: a client built with one
+`tenantId` operates on whatever tenant that user is currently on.
+
+**`accessToken`, not `apiKey`.** The webhook routes have no API key mount at
+all (publishing spec D8): a key that can add an endpoint can forward every
+content change in the tenant to a URL of its choosing, and a key is a string in
+a config file nobody rotates. So these routes want a logged-in person, and every
+`webhooks.*` method throws `@capacms/sdk: webhooks need accessToken; API keys
+cannot manage endpoints.` before sending anything when the token is absent.
+
+The rest of the resource:
+
+```ts
+await capa.webhooks.events();                            // the catalogue, grouped
+await capa.webhooks.endpoints.list();
+await capa.webhooks.endpoints.get(id);                   // null when there is none
+await capa.webhooks.endpoints.update(id, { events });    // headers REPLACE the map
+await capa.webhooks.endpoints.delete(id);
+await capa.webhooks.endpoints.pause(id);                 // cancels what is queued
+await capa.webhooks.endpoints.resume(id);                // enables, and COUNTS the gap
+await capa.webhooks.endpoints.resume(id, { backfill: true, since });
+await capa.webhooks.endpoints.revealSecret(id);          // audited, every time
+await capa.webhooks.endpoints.rotateSecret(id);          // old secret lives 24h
+await capa.webhooks.endpoints.test(id);                  // one webhook.test event
+await capa.webhooks.endpoints.deliveries(id, { status: ["failed"], page: 1 });
+await capa.webhooks.endpoints.redeliverFailed(id, { since });
+await capa.webhooks.deliveries.get(deliveryId);          // with both bodies
+await capa.webhooks.deliveries.redeliver(deliveryId);    // same event id
+```
+
+`test` answers `{ eventId }`, and that value is an **opaque request id**: the
+event that actually arrives carries a different `id` (`evt_` plus the outbox row
+id), so there is nothing to correlate on. Read `deliveries(id)` and take the
+newest `webhook.test` row to see what the test did.
+
+`resume` without `backfill` is deliberately a two-step: it enables the endpoint
+and tells you how many events it missed, so you can show a person
+`Redeliver everything since 14 Sep, 2:10 PM (312 events)` and let them decide.
+Call it again with `{ backfill: true, since }` if they say yes.
+
+Reads need `webhook:read`, writes need the `webhook:*` write actions, and
+`revealSecret` needs `secret:reveal`, which no role bundle holds: it is an owner
+or an explicit override, and every call leaves an audit row whether it was
+allowed or denied. A server without `CAPA_SECRET_KEY` set answers `503` with
+code `webhooks_not_configured` to every write while reads keep working.
+
+The operator's side of all of this, including the retry ladder, auto-pause, the
+SSRF rules and how to run a receiver locally, is `docs/WEBHOOKS.md`.