@capacms/sdk 1.0.0-next.0

package/dist/nextjs/index.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withCache = withCache;
+exports.tagsFor = tagsFor;
+exports.revalidateFromWebhook = revalidateFromWebhook;
+exports.draftClient = draftClient;
+exports.routeOf = routeOf;
+exports.preview = preview;
+exports.pagesFor = pagesFor;
+const next_1 = require("../next");
+/** Add Next.js fetch-cache options without importing `next/*`. */
+function withCache(fetchImpl, options) {
+    return (async (input, init = {}) => {
+        const previous = init.next ?? {};
+        const tags = [...new Set([...(previous.tags ?? []), ...(options.tags ?? [])])];
+        const next = { ...previous };
+        if (tags.length > 0)
+            next.tags = tags;
+        if (options.revalidate !== undefined)
+            next.revalidate = options.revalidate;
+        return fetchImpl(input, { ...init, next });
+    });
+}
+function tagsFor(input) {
+    const tags = [];
+    if (input.model)
+        tags.push(`m:${input.model}`);
+    if (input.entry)
+        tags.push(`e:${input.entry}`);
+    if (input.key)
+        tags.push(`k:${input.key}`);
+    if (input.tenant)
+        tags.push(`t:${input.tenant}`);
+    return tags;
+}
+/** Revalidate the concrete entry and model identities carried by a webhook. */
+async function revalidateFromWebhook(input) {
+    const data = input.payload?.data ?? input.payload;
+    const tags = [];
+    const entryId = data?.instanceId ?? data?.entryId;
+    if (typeof entryId === "string" && entryId)
+        tags.push(`e:${entryId}`);
+    if (typeof data?.modelId === "string" && data.modelId)
+        tags.push(`m:${data.modelId}`);
+    const unique = [...new Set(tags)];
+    for (const tag of unique)
+        await input.revalidateTag(tag);
+    return unique;
+}
+/** Select a client using server-only draft state supplied by the caller. */
+async function draftClient(input) {
+    return (0, next_1.createClient)((await input.isDraft()) ? input.draft : input.production);
+}
+// ------------------------------------------------------------------ pages ---
+/**
+ * The page a Next.js route file renders, as a Capa page identity.
+ *
+ * `routeOf(import.meta.url)` in a route, or `routeOf(__filename)`, turns the
+ * file's own path into the string to send as `Capa-Page`. Writing the route out
+ * by hand works too; this exists so that moving a folder cannot silently split
+ * one page's telemetry into two.
+ *
+ *   /abs/app/blog/[slug]/page.tsx            -> /blog/[slug]
+ *   src/app/(marketing)/pricing/page.tsx     -> /pricing
+ *   pages/blog/[slug].tsx                    -> /blog/[slug]
+ *   app/page.tsx                             -> /
+ *
+ * WHAT IS DROPPED, and why each one:
+ *
+ *   everything before `app/` or `pages/`  the route starts at the router root,
+ *                                         so an absolute path and a relative
+ *                                         one give the same answer
+ *   route groups `(marketing)`            Next does not put them in the URL
+ *   parallel slots `@modal`               the same
+ *   the `(.)` intercept marker            an intercepting route at the SAME
+ *                                         level renders the segment beside it
+ *   `page.*`, `layout.*`, `route.*`,      leaf files, not segments
+ *   `default.*`, `template.*`
+ *   `index` in the pages router           the folder IS the route
+ *   the extension                         never in a URL
+ *
+ * THROWS rather than guessing in three cases, because a page identity that is
+ * quietly wrong is worse than one that is missing: a path with no `app/` or
+ * `pages/` directory in it; a file inside a private `_folder`, which Next does
+ * not route at all; and a `(..)` or `(...)` intercepting route, whose URL is a
+ * segment somewhere ABOVE the file and is not derivable from the path. In each
+ * case the message says to pass the page string yourself.
+ */
+const ROUTER_ROOTS = new Set(["app", "pages"]);
+const LEAF_FILES = new Set(["page", "layout", "route", "default", "template"]);
+/** `(..)photo`, `(..)(..)photo`, `(...)photo`: the URL is not here. */
+const OUTER_INTERCEPT = /^(\(\.\.\.\)|(\(\.\.\))+)/;
+function routeOf(file) {
+    if (typeof file !== "string" || file === "") {
+        throw new TypeError("@capacms/sdk/nextjs: routeOf needs a file path.");
+    }
+    // `import.meta.url` is a file: URL, and a Windows path uses backslashes.
+    const withoutScheme = file.startsWith("file://") ? file.slice("file://".length) : file;
+    const normalised = withoutScheme.replace(/\\/g, "/").split("?")[0];
+    const parts = normalised.split("/").filter((part) => part !== "" && part !== ".");
+    // The LAST router root wins, so a project with its own `app/` inside
+    // `packages/site/app/...` resolves against the one nearest the route.
+    let rootIndex = -1;
+    for (let i = parts.length - 1; i >= 0; i--) {
+        if (ROUTER_ROOTS.has(parts[i])) {
+            rootIndex = i;
+            break;
+        }
+    }
+    if (rootIndex === -1) {
+        throw new TypeError(`@capacms/sdk/nextjs: ${file} is not inside an app/ or pages/ directory, so it names no route. Pass the page string yourself.`);
+    }
+    const segments = [];
+    for (let i = rootIndex + 1; i < parts.length; i++) {
+        const isLast = i === parts.length - 1;
+        let part = parts[i];
+        if (isLast) {
+            const dot = part.lastIndexOf(".");
+            if (dot > 0)
+                part = part.slice(0, dot);
+            if (LEAF_FILES.has(part))
+                continue;
+            // The pages router: `pages/blog/index.tsx` is `/blog`.
+            if (part === "index")
+                continue;
+        }
+        if (part.startsWith("_")) {
+            throw new TypeError(`@capacms/sdk/nextjs: ${file} is inside the private folder ${part}, which Next does not route. Pass the page string yourself.`);
+        }
+        if (OUTER_INTERCEPT.test(part)) {
+            throw new TypeError(`@capacms/sdk/nextjs: ${file} intercepts a route above it (${part}), so its URL is not in its path. Pass the page string yourself.`);
+        }
+        // Route groups and parallel slots are organisation, not URL.
+        if (part.startsWith("(") && part.endsWith(")"))
+            continue;
+        if (part.startsWith("@"))
+            continue;
+        // `(.)photo` intercepts the sibling `photo`, so the marker goes and the
+        // name stays.
+        if (part.startsWith("(.)"))
+            part = part.slice("(.)".length);
+        segments.push(part);
+    }
+    return segments.length === 0 ? "/" : `/${segments.join("/")}`;
+}
+/**
+ * Verify a preview token from a Next route handler.
+ *
+ * A thin pass-through to `client.preview`, here so that a preview route reads
+ * as one import from `@capacms/sdk/nextjs` alongside the rest of the Next
+ * helpers. Null means "do not enable draft mode".
+ */
+async function preview(token, client) {
+    return client.preview(token);
+}
+/**
+ * The page list, as a standalone value.
+ *
+ * `pagesFor(client)` is `client.pages` and exists for symmetry with the other
+ * helpers in this module: a build script that only wants the page list can take
+ * this and never hold the whole client.
+ */
+function pagesFor(client) {
+    return client.pages;
+}

package/dist/webhook-signature.d.ts

@@ -0,0 +1,88 @@
+/**
+ * webhook-signature.ts — verifying a Capa webhook, with no client and no key.
+ *
+ * This is the one thing in the SDK a receiver needs before it has anything
+ * else. It takes the raw request body, the `Capa-Signature` header and the
+ * endpoint's secret, and answers a boolean. It does not construct a client, it
+ * does not read configuration and it makes no network call, so it can be
+ * imported into a route handler that has nothing but the request in hand.
+ *
+ * WEBCRYPTO, NOT `node:crypto`, AND THAT IS WHY IT IS ASYNC.
+ * `globalThis.crypto.subtle` exists in Node 18+, Bun, Deno, Cloudflare Workers,
+ * Vercel's edge runtime and every browser. `node:crypto` exists in exactly one
+ * of those, and a bare `import crypto from "node:crypto"` at the top of a file
+ * that a bundler pulls into an edge or browser build breaks the build outright
+ * rather than at the call. WebCrypto's HMAC is promise-based, so this function
+ * is `async`. That is the whole reason, and it is worth the `await`.
+ *
+ * THE BODY MUST BE THE BYTES THAT ARRIVED.
+ * The signature covers `"<t>.<body>"` where `<body>` is the exact request body
+ * Capa sent. A body that has been through `JSON.parse` and `JSON.stringify`
+ * again is a different string (key order, whitespace, unicode escapes) and will
+ * not verify. In Express use `express.raw({ type: "application/json" })`, in
+ * Fastify add a raw-body parser for the route, in Next's app router use
+ * `await request.text()`. Pass the `Uint8Array` or `Buffer` straight in when
+ * you have one: this function signs the bytes you give it without a round trip
+ * through a string.
+ */
+/** The header Capa signs with. */
+export declare const WEBHOOK_SIGNATURE_HEADER = "Capa-Signature";
+/** Five minutes, the tolerance in the publishing spec (4.4). */
+export declare const DEFAULT_WEBHOOK_TOLERANCE_SECONDS = 300;
+export interface VerifyWebhookSignatureInput {
+    /**
+     * The exact request body. A string is encoded as UTF-8; a `Uint8Array` or
+     * `Buffer` is signed as given.
+     */
+    payload: string | Uint8Array;
+    /** The `Capa-Signature` header value, `t=<unix>,v1=<hex>[,v1=<hex>]`. */
+    header: string;
+    /** The endpoint's secret, `whsec_…`, including the prefix. */
+    secret: string;
+    /**
+     * How far `t` may be from now, in seconds, in either direction. Always
+     * enforced: `0` means the timestamp must be the current second, not that the
+     * check is skipped.
+     */
+    toleranceSeconds?: number;
+    /** Injected in tests. Unix seconds, or a Date. Defaults to the clock. */
+    now?: number | Date;
+}
+export interface ParsedWebhookSignature {
+    /** Unix seconds the sender signed at. */
+    t: number;
+    /** Every `v1=` entry, newest first, in header order. */
+    v1: string[];
+}
+/**
+ * Split a `Capa-Signature` header. `null` when it carries no usable `t` or no
+ * `v1` at all, which is the same thing as "do not trust this request".
+ */
+export declare function parseWebhookSignatureHeader(header: string): ParsedWebhookSignature | null;
+/** The lowercase hex HMAC-SHA256 of `"<t>.<payload>"` under `secret`. */
+export declare function signWebhookPayload(payload: string | Uint8Array, secret: string, t: number): Promise<string>;
+/**
+ * Is this request really from Capa, and recent?
+ *
+ * ```ts
+ * import { verifyWebhookSignature } from "@capacms/sdk";
+ *
+ * const body = await request.text();
+ * 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 });
+ * ```
+ *
+ * `true` only when the header parses, `t` is inside the tolerance, and at least
+ * one `v1` entry equals the HMAC of `"<t>.<payload>"` under `secret`. During
+ * the 24 hours after a rotation Capa sends TWO `v1` entries, the new secret
+ * first, so a receiver that has only ever seen one of the two still verifies
+ * and you can change the stored secret whenever you like inside that window.
+ *
+ * Every `v1` is compared even after one matches, so the answer takes the same
+ * time whichever entry was the right one.
+ */
+export declare function verifyWebhookSignature(input: VerifyWebhookSignatureInput): Promise<boolean>;

package/dist/webhook-signature.js

@@ -0,0 +1,161 @@
+"use strict";
+/**
+ * webhook-signature.ts — verifying a Capa webhook, with no client and no key.
+ *
+ * This is the one thing in the SDK a receiver needs before it has anything
+ * else. It takes the raw request body, the `Capa-Signature` header and the
+ * endpoint's secret, and answers a boolean. It does not construct a client, it
+ * does not read configuration and it makes no network call, so it can be
+ * imported into a route handler that has nothing but the request in hand.
+ *
+ * WEBCRYPTO, NOT `node:crypto`, AND THAT IS WHY IT IS ASYNC.
+ * `globalThis.crypto.subtle` exists in Node 18+, Bun, Deno, Cloudflare Workers,
+ * Vercel's edge runtime and every browser. `node:crypto` exists in exactly one
+ * of those, and a bare `import crypto from "node:crypto"` at the top of a file
+ * that a bundler pulls into an edge or browser build breaks the build outright
+ * rather than at the call. WebCrypto's HMAC is promise-based, so this function
+ * is `async`. That is the whole reason, and it is worth the `await`.
+ *
+ * THE BODY MUST BE THE BYTES THAT ARRIVED.
+ * The signature covers `"<t>.<body>"` where `<body>` is the exact request body
+ * Capa sent. A body that has been through `JSON.parse` and `JSON.stringify`
+ * again is a different string (key order, whitespace, unicode escapes) and will
+ * not verify. In Express use `express.raw({ type: "application/json" })`, in
+ * Fastify add a raw-body parser for the route, in Next's app router use
+ * `await request.text()`. Pass the `Uint8Array` or `Buffer` straight in when
+ * you have one: this function signs the bytes you give it without a round trip
+ * through a string.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_WEBHOOK_TOLERANCE_SECONDS = exports.WEBHOOK_SIGNATURE_HEADER = void 0;
+exports.parseWebhookSignatureHeader = parseWebhookSignatureHeader;
+exports.signWebhookPayload = signWebhookPayload;
+exports.verifyWebhookSignature = verifyWebhookSignature;
+/** The header Capa signs with. */
+exports.WEBHOOK_SIGNATURE_HEADER = "Capa-Signature";
+/** Five minutes, the tolerance in the publishing spec (4.4). */
+exports.DEFAULT_WEBHOOK_TOLERANCE_SECONDS = 300;
+/**
+ * Split a `Capa-Signature` header. `null` when it carries no usable `t` or no
+ * `v1` at all, which is the same thing as "do not trust this request".
+ */
+function parseWebhookSignatureHeader(header) {
+    if (typeof header !== "string" || !header)
+        return null;
+    let t = null;
+    const v1 = [];
+    for (const part of header.split(",")) {
+        const eq = part.indexOf("=");
+        if (eq < 1)
+            continue;
+        const key = part.slice(0, eq).trim();
+        const value = part.slice(eq + 1).trim();
+        if (key === "t") {
+            // The first `t` wins. A header with two is malformed, and picking the
+            // last one would let an attacker append a fresh timestamp to a replay.
+            if (t === null && /^\d+$/.test(value))
+                t = Number(value);
+        }
+        else if (key === "v1") {
+            if (value)
+                v1.push(value);
+        }
+    }
+    if (t === null || !v1.length)
+        return null;
+    return { t, v1 };
+}
+/** The bytes that get signed: `"<t>."` followed by the body. */
+function signedPayloadBytes(t, payload) {
+    const prefix = new TextEncoder().encode(`${t}.`);
+    const body = typeof payload === "string" ? new TextEncoder().encode(payload) : payload;
+    const out = new Uint8Array(prefix.length + body.length);
+    out.set(prefix, 0);
+    out.set(body, prefix.length);
+    return out;
+}
+function toHex(buffer) {
+    const bytes = new Uint8Array(buffer);
+    let hex = "";
+    for (let i = 0; i < bytes.length; i++)
+        hex += bytes[i].toString(16).padStart(2, "0");
+    return hex;
+}
+/**
+ * Constant time over the digest's own length.
+ *
+ * Both sides are a fixed-length lowercase hex SHA-256 digest, so a length
+ * mismatch is a malformed header rather than a near miss and leaks nothing
+ * worth having.
+ */
+function timingSafeEqualHex(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+function subtle() {
+    const c = globalThis.crypto;
+    if (!c?.subtle) {
+        throw new Error("@capacms/sdk: verifyWebhookSignature needs WebCrypto (globalThis.crypto.subtle). " +
+            "It is present in Node 18+, Bun, Deno, Workers and browsers. On an older Node, " +
+            "run with --experimental-global-webcrypto or upgrade.");
+    }
+    return c.subtle;
+}
+/** The lowercase hex HMAC-SHA256 of `"<t>.<payload>"` under `secret`. */
+async function signWebhookPayload(payload, secret, t) {
+    const key = await subtle().importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    return toHex(await subtle().sign("HMAC", key, signedPayloadBytes(t, payload)));
+}
+/**
+ * Is this request really from Capa, and recent?
+ *
+ * ```ts
+ * import { verifyWebhookSignature } from "@capacms/sdk";
+ *
+ * const body = await request.text();
+ * 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 });
+ * ```
+ *
+ * `true` only when the header parses, `t` is inside the tolerance, and at least
+ * one `v1` entry equals the HMAC of `"<t>.<payload>"` under `secret`. During
+ * the 24 hours after a rotation Capa sends TWO `v1` entries, the new secret
+ * first, so a receiver that has only ever seen one of the two still verifies
+ * and you can change the stored secret whenever you like inside that window.
+ *
+ * Every `v1` is compared even after one matches, so the answer takes the same
+ * time whichever entry was the right one.
+ */
+async function verifyWebhookSignature(input) {
+    const { payload, header, secret } = input ?? {};
+    if (typeof secret !== "string" || !secret)
+        return false;
+    if (payload === undefined || payload === null)
+        return false;
+    const parsed = parseWebhookSignatureHeader(header);
+    if (!parsed)
+        return false;
+    const tolerance = typeof input.toleranceSeconds === "number" && Number.isFinite(input.toleranceSeconds)
+        ? Math.abs(input.toleranceSeconds)
+        : exports.DEFAULT_WEBHOOK_TOLERANCE_SECONDS;
+    const nowSeconds = input.now instanceof Date
+        ? Math.floor(input.now.getTime() / 1000)
+        : typeof input.now === "number"
+            ? Math.floor(input.now)
+            : Math.floor(Date.now() / 1000);
+    if (Math.abs(nowSeconds - parsed.t) > tolerance)
+        return false;
+    const expected = await signWebhookPayload(payload, secret, parsed.t);
+    let ok = false;
+    for (const candidate of parsed.v1)
+        ok = timingSafeEqualHex(candidate, expected) || ok;
+    return ok;
+}

package/dist/webhooks.d.ts

@@ -0,0 +1,244 @@
+/**
+ * webhooks.ts — managing endpoints and reading deliveries.
+ *
+ * WHY THIS ONE RESOURCE NEEDS A SESSION TOKEN
+ * Every other method on the client is an API key call. These are not, and the
+ * reason is a deliberate decision rather than an oversight: publishing spec D8
+ * says webhook endpoints have no agent mount and no API key bundle, because a
+ * key that can add an endpoint can quietly forward every content change in the
+ * tenant to a URL of its choosing, and a key is a string in a config file that
+ * nobody rotates. So `/v2/webhooks/*` is session-only: `authenticate`,
+ * `validateTenant`, `webhook:read` or `webhook:*` on a real person.
+ *
+ * The SDK therefore takes an `accessToken` (from `POST /v2/user/login`) and
+ * refuses locally when it is absent, rather than sending an `x-api-key` the
+ * route will never look at and returning the 401 that follows.
+ *
+ * READING IS THE COMMON CASE. Most callers want `deliveries()` and
+ * `deliveries.get()` to build a "why did my site not update" screen of their
+ * own. Those still need the token, because the route does.
+ */
+import type { ResolvedConfig } from "./config";
+/** `disabledReason` on an endpoint: who or what switched it off. */
+export type WebhookDisabledReason = "paused" | "failing" | "ssrf_refused";
+/**
+ * An endpoint as every route returns it.
+ *
+ * `headers` are MASKED here (`"••••ab"`). The stored value is sent to your URL
+ * in full; the API never reads one back out. `secretPrefix` is the first 10
+ * characters of the secret (`"whsec_3f9a"`), which is enough to tell two
+ * endpoints apart in a log and useless to anyone who finds it.
+ */
+export interface WebhookEndpoint {
+    id: string;
+    tenantId: string;
+    name: string;
+    url: string;
+    description: string | null;
+    secretPrefix: string;
+    /** Exact types, or `"<resource>.*"` wildcards. */
+    events: string[];
+    enabled: boolean;
+    /** Sends the published entry in `data` on `instance.published`. */
+    includeData: boolean;
+    headers: Record<string, string>;
+    consecutiveFailures: number;
+    /** When the current failing streak started. Cleared by any success. */
+    failingSince: string | null;
+    lastDeliveryAt: string | null;
+    /**
+     * The HTTP status as a string when the endpoint answered at all (`"200"`,
+     * `"301"`, `"500"`), or `"timeout"` / `"network"` when it did not. An SSRF
+     * refusal is recorded in `disabledReason`, not here, so a refused endpoint
+     * still shows whatever its last real answer was.
+     */
+    lastDeliveryStatus: string | null;
+    disabledAt: string | null;
+    disabledReason: WebhookDisabledReason | null;
+    createdBy: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * What `create` and `rotateSecret` answer with. The ONLY two responses that
+ * ever carry `secret`; every later read carries `secretPrefix` alone, and the
+ * full value comes back only from `revealSecret`, which is audited.
+ */
+export interface WebhookEndpointWithSecret extends WebhookEndpoint {
+    secret: string;
+    /** Set by `rotateSecret`: the old secret keeps signing until this instant. */
+    previousSecretExpiresAt?: string | null;
+}
+/** `get` adds the count the endpoint page puts on its Redeliver button. */
+export interface WebhookEndpointDetail extends WebhookEndpoint {
+    failedDeliveries: number;
+}
+export type WebhookDeliveryStatus = "pending" | "succeeded" | "failed" | "exhausted" | "cancelled";
+/**
+ * One attempt at one endpoint for one event.
+ *
+ * `eventId` is the same on a redelivery as on the original, and it is what goes
+ * out as `Idempotency-Key`, so a receiver that stores it can recognise a repeat
+ * without comparing bodies. `redeliveredFromId` points at the delivery this one
+ * was made from, and is `null` on an original.
+ */
+export interface WebhookDelivery {
+    id: string;
+    tenantId: string;
+    endpointId: string;
+    eventId: string;
+    eventType: string;
+    status: WebhookDeliveryStatus;
+    attempts: number;
+    /** Always 6. The ladder is 1m, 5m, 30m, 2h, 6h after failures 1 to 5. */
+    maxAttempts: number;
+    /**
+     * Non-null only on a `pending` row that has already failed at least once. It
+     * is `null` everywhere else, including on a succeeded row, whose stored
+     * column would otherwise read as "another attempt is coming".
+     */
+    nextAttemptAt: string | null;
+    lastAttemptAt: string | null;
+    responseStatus: number | null;
+    responseMs: number | null;
+    /**
+     * `"timeout"`, `"network"`, `"redirect"`, `"ssrf_refused"`,
+     * `"endpoint_disabled"`, `"invalid_url"` (terminal: the stored URL no longer
+     * parses) or `"secret_unavailable"` (also terminal: the endpoint row carries
+     * no usable signing secret, so no retry could ever sign it — fix the
+     * endpoint and redeliver). An ordinary non-2xx answer leaves this null,
+     * because `responseStatus` says it all.
+     *
+     * A secret that could not be DECRYPTED right now — `CAPA_SECRET_KEY`
+     * mid-change — is the other case and never reaches this column: the delivery
+     * is released unattempted and stays `pending`.
+     */
+    error: string | null;
+    redeliveredFromId: string | null;
+    createdAt: string;
+    completedAt: string | null;
+}
+/** The single-delivery read, which adds the bodies the list leaves out. */
+export interface WebhookDeliveryDetail extends WebhookDelivery {
+    /** The exact bytes that were signed and sent. */
+    requestBody: string;
+    /** The first 4 KB of what came back, or `null`. */
+    responseBody: string | null;
+}
+export type WebhookEventGroup = "Content" | "Models" | "Media" | "Publishing" | "Test";
+/** One row of `webhooks.events()`: what to show in a subscription picker. */
+export interface WebhookEventCatalogueEntry {
+    group: WebhookEventGroup;
+    type: string;
+    description: string;
+    sample: Record<string, unknown>;
+    /** Checked when a person adds an endpoint and changes nothing. */
+    defaultChecked: boolean;
+}
+export interface WebhookPagination {
+    total: number;
+    page: number;
+    limit: number;
+    totalPages: number;
+    hasMore: boolean;
+}
+export interface WebhookDeliveriesPage {
+    deliveries: WebhookDelivery[];
+    pagination: WebhookPagination;
+}
+export interface CreateWebhookEndpointInput {
+    name: string;
+    /** `https://…`. `http://` only for localhost, and only outside production. */
+    url: string;
+    description?: string;
+    /** At least one. Exact types or `"<resource>.*"`. */
+    events: string[];
+    includeData?: boolean;
+    /** At most 10. Sent with every request; they cannot override a `Capa-*` header. */
+    headers?: Record<string, string>;
+}
+/**
+ * A patch. `headers` REPLACES the whole map, so send the ones you want kept.
+ * A value left at its mask (`"••••ab"`) keeps the stored value, which is how
+ * the admin can round-trip a form it was never shown the real values for.
+ */
+export type UpdateWebhookEndpointInput = Partial<CreateWebhookEndpointInput>;
+export interface ResumeWebhookEndpointOptions {
+    /**
+     * `false` (the default) enables the endpoint and COUNTS what it missed
+     * without queueing any of it, so a caller can offer the number to a person
+     * first. `true` enables it and queues the same set.
+     */
+    backfill?: boolean;
+    /** ISO. Defaults to the instant the endpoint was disabled. */
+    since?: string;
+}
+export interface ResumeWebhookEndpointResult {
+    endpoint: WebhookEndpoint;
+    backfill: {
+        since: string | null;
+        /** How many events match, whether or not they were queued. */
+        count: number;
+        /** How many deliveries were actually created. `0` without `backfill: true`. */
+        inserted: number;
+    };
+}
+export interface ListWebhookDeliveriesOptions {
+    status?: WebhookDeliveryStatus[];
+    eventType?: string;
+    page?: number;
+    /** Default 50, max 200. */
+    limit?: number;
+}
+export interface WebhooksResource {
+    /** The event catalogue: every type, grouped, with a sample payload. */
+    events(): Promise<WebhookEventCatalogueEntry[]>;
+    endpoints: WebhookEndpointsResource;
+    deliveries: WebhookDeliveriesResource;
+}
+export interface WebhookEndpointsResource {
+    list(): Promise<WebhookEndpoint[]>;
+    /** The response carries `secret` once and never again. Store it now. */
+    create(input: CreateWebhookEndpointInput): Promise<WebhookEndpointWithSecret>;
+    /** `null` when no such endpoint belongs to this tenant. */
+    get(id: string): Promise<WebhookEndpointDetail | null>;
+    update(id: string, patch: UpdateWebhookEndpointInput): Promise<WebhookEndpoint>;
+    delete(id: string): Promise<boolean>;
+    /** Stops delivery and cancels everything already queued for it. */
+    pause(id: string): Promise<WebhookEndpoint>;
+    resume(id: string, options?: ResumeWebhookEndpointOptions): Promise<ResumeWebhookEndpointResult>;
+    /** Audited on the server, every time, including the refusals. */
+    revealSecret(id: string): Promise<{
+        secret: string;
+        secretPrefix: string;
+    }>;
+    /** The old secret keeps signing for 24 hours. See `WEBHOOKS.md`. */
+    rotateSecret(id: string): Promise<WebhookEndpointWithSecret>;
+    /**
+     * Queues one `webhook.test` event for this endpoint alone.
+     *
+     * The returned `eventId` is an OPAQUE request id, not the id of the event
+     * that gets delivered. The envelope's `id`, the `Capa-Event-Id` header and
+     * the delivery row's `eventId` are all `evt_` plus the outbox row's uuid,
+     * which is a different string, so this value correlates with nothing. To find
+     * what the test produced, read `deliveries(id)` and take the newest
+     * `webhook.test` row.
+     */
+    test(id: string): Promise<{
+        eventId: string;
+    }>;
+    deliveries(id: string, options?: ListWebhookDeliveriesOptions): Promise<WebhookDeliveriesPage>;
+    redeliverFailed(id: string, options?: {
+        since?: string;
+    }): Promise<{
+        created: number;
+    }>;
+}
+export interface WebhookDeliveriesResource {
+    /** `null` on a miss. Carries `requestBody` and `responseBody`. */
+    get(id: string): Promise<WebhookDeliveryDetail | null>;
+    /** A NEW delivery with the same `eventId`, pointing back at this one. */
+    redeliver(id: string): Promise<WebhookDelivery>;
+}
+export declare const WEBHOOKS_NEED_ACCESS_TOKEN = "@capacms/sdk: webhooks need accessToken; API keys cannot manage endpoints.";
+export declare function createWebhooks(resolved: ResolvedConfig): WebhooksResource;