primitive-admin 1.1.0-alpha.9 → 1.1.0

package/dist/src/lib/watch.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Shared poll-based tailing helpers for `--watch` / `--follow` (#1969).
+ *
+ * Two render modes over one abortable poll loop:
+ *   - `--watch`  → periodic full-snapshot redraw (a repeated `list`/`get`).
+ *   - `--follow` → append-only tail: fetch rows after an opaque server-owned
+ *                  `resumeAfter` checkpoint each tick.
+ *
+ * The loop is endpoint-agnostic. `--follow` consumers supply a {@link FollowSource}
+ * that knows how to fetch the page after a checkpoint; `--watch` consumers supply
+ * a `snapshot()` and a renderer. The renderer is injected (there is no `json`
+ * flag in the options) so this file never decides output shape or clears the
+ * terminal — that is entirely the caller's renderer.
+ *
+ * `--follow` is near-lossless observed-version tailing: it re-emits a row when a
+ * newer version is observed, holds no per-item dedup state, and asserts only
+ * forward progress — never a total-order or exactly-once property (the
+ * underlying GSI sorts by `modifiedAt` alone and is eventually consistent). See
+ * the design in #1969.
+ *
+ * Unit-tested against fake sources (the `cli/src/lib/paginate.ts` pattern) with
+ * no server.
+ */
+/** Interval floor: reject anything below this (prevents a request storm). */
+export declare const MIN_INTERVAL_SECONDS = 1;
+/** Default poll interval when `--interval` is omitted. */
+export declare const DEFAULT_INTERVAL_SECONDS = 2;
+/**
+ * Default cap on how many pages `followLoop` drains within a single tick when a
+ * burst is larger than one page. Bounds the within-tick work and, with the
+ * non-advancing-checkpoint guard, prevents an infinite drain.
+ */
+export declare const DEFAULT_MAX_PAGES_PER_TICK = 20;
+/**
+ * Validate an `--interval` value (in seconds). Returns the interval in seconds,
+ * or throws with a clear message for a missing/NaN/sub-floor value. Command
+ * handlers call this and surface the error; the library loops take a validated
+ * `intervalMs`.
+ */
+export declare function parseIntervalSeconds(raw: string | undefined): number;
+/**
+ * Sleep for `ms`, resolving early (never rejecting) if `signal` aborts. The
+ * timer and abort listener are always cleaned up, so a resolved delay leaves no
+ * dangling timer. Used by every poll loop so Ctrl-C stops promptly between
+ * ticks.
+ */
+export declare function delay(ms: number, signal?: AbortSignal): Promise<void>;
+/** Error policy for the poll loops: keep polling, or throw out of the loop. */
+export type PollErrorPolicy = "continue" | "throw";
+export interface PollUntilOptions<T> {
+    /** Validated poll interval in milliseconds. */
+    intervalMs: number;
+    /** Abort signal (Ctrl-C at the command level). */
+    signal: AbortSignal;
+    /** What to do when `probe` throws. Default `"throw"`. */
+    onError?: PollErrorPolicy;
+    /** Called with each probed value (e.g. to report progress). */
+    onValue?: (value: T) => void;
+}
+/**
+ * Delay-then-probe until `done(value)` is true or the signal aborts. Returns
+ * the last probed value. Delay-first (not probe-first) so a caller that already
+ * holds a fresh value — the batch-status loops — keeps its "poll every N
+ * seconds" cadence with no extra immediate request.
+ */
+export declare function pollUntil<T>(probe: () => Promise<T>, done: (value: T) => boolean, options: PollUntilOptions<T>): Promise<T>;
+/** One page of follow results, carrying the opaque next checkpoint. */
+export interface FollowPage<T> {
+    items: T[];
+    /** More rows remain past this page right now (drives the within-tick drain). */
+    hasMore: boolean;
+    /** Opaque server-owned checkpoint; always present, even on an empty page. */
+    resumeAfter: string;
+}
+/**
+ * A source of follow pages. `fetchAfter(undefined)` is the bootstrap poll — it
+ * establishes the baseline checkpoint and its items are NOT emitted (tail
+ * semantics: "show me what happens from now"). `fetchAfter(<token>)` returns the
+ * bounded page after that checkpoint.
+ */
+export interface FollowSource<T> {
+    fetchAfter: (resumeAfter: string | undefined) => Promise<FollowPage<T>>;
+    /**
+     * Max pages to drain within one tick when a burst exceeds one page. Defaults
+     * to {@link DEFAULT_MAX_PAGES_PER_TICK}. The drain also stops early if the
+     * checkpoint fails to advance (non-advancing-checkpoint guard).
+     */
+    maxPagesPerTick?: number;
+}
+export interface FollowOptions<T> {
+    intervalMs: number;
+    signal: AbortSignal;
+    /** What to do when a poll throws. Default `"continue"` (keep tailing). */
+    onError?: PollErrorPolicy;
+    /** Render newly-observed rows (server-ascending; no client sort). */
+    render: (items: T[]) => void;
+}
+export interface WatchOptions<T> {
+    intervalMs: number;
+    signal: AbortSignal;
+    /** What to do when a poll throws. Default `"continue"`. */
+    onError?: PollErrorPolicy;
+    /**
+     * Render the full snapshot. The renderer owns any clearing/redraw — the loop
+     * never clears the terminal itself.
+     */
+    render: (items: T[]) => void;
+}
+/**
+ * Append-only tail. Bootstraps the baseline checkpoint (emitting nothing), then
+ * each tick drains forward while `hasMore` (bounded by `maxPagesPerTick`,
+ * stopping if the checkpoint fails to advance), rendering rows server-ascending.
+ * Holds no per-item state — the only carried state is the single opaque
+ * `resumeAfter` string.
+ */
+export declare function followLoop<T>(source: FollowSource<T>, options: FollowOptions<T>): Promise<void>;
+/**
+ * Snapshot redraw. Each tick fetches the full current snapshot and hands it to
+ * the renderer, which owns any clearing/redraw. No checkpoint, no dedup.
+ */
+export declare function watchLoop<T>(snapshot: () => Promise<T[]>, options: WatchOptions<T>): Promise<void>;

package/dist/src/lib/watch.js

@@ -0,0 +1,169 @@
+/**
+ * Shared poll-based tailing helpers for `--watch` / `--follow` (#1969).
+ *
+ * Two render modes over one abortable poll loop:
+ *   - `--watch`  → periodic full-snapshot redraw (a repeated `list`/`get`).
+ *   - `--follow` → append-only tail: fetch rows after an opaque server-owned
+ *                  `resumeAfter` checkpoint each tick.
+ *
+ * The loop is endpoint-agnostic. `--follow` consumers supply a {@link FollowSource}
+ * that knows how to fetch the page after a checkpoint; `--watch` consumers supply
+ * a `snapshot()` and a renderer. The renderer is injected (there is no `json`
+ * flag in the options) so this file never decides output shape or clears the
+ * terminal — that is entirely the caller's renderer.
+ *
+ * `--follow` is near-lossless observed-version tailing: it re-emits a row when a
+ * newer version is observed, holds no per-item dedup state, and asserts only
+ * forward progress — never a total-order or exactly-once property (the
+ * underlying GSI sorts by `modifiedAt` alone and is eventually consistent). See
+ * the design in #1969.
+ *
+ * Unit-tested against fake sources (the `cli/src/lib/paginate.ts` pattern) with
+ * no server.
+ */
+/** Interval floor: reject anything below this (prevents a request storm). */
+export const MIN_INTERVAL_SECONDS = 1;
+/** Default poll interval when `--interval` is omitted. */
+export const DEFAULT_INTERVAL_SECONDS = 2;
+/**
+ * Default cap on how many pages `followLoop` drains within a single tick when a
+ * burst is larger than one page. Bounds the within-tick work and, with the
+ * non-advancing-checkpoint guard, prevents an infinite drain.
+ */
+export const DEFAULT_MAX_PAGES_PER_TICK = 20;
+/**
+ * Validate an `--interval` value (in seconds). Returns the interval in seconds,
+ * or throws with a clear message for a missing/NaN/sub-floor value. Command
+ * handlers call this and surface the error; the library loops take a validated
+ * `intervalMs`.
+ */
+export function parseIntervalSeconds(raw) {
+    if (raw === undefined)
+        return DEFAULT_INTERVAL_SECONDS;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < MIN_INTERVAL_SECONDS) {
+        throw new Error(`--interval must be a number of seconds >= ${MIN_INTERVAL_SECONDS}`);
+    }
+    return n;
+}
+/**
+ * Sleep for `ms`, resolving early (never rejecting) if `signal` aborts. The
+ * timer and abort listener are always cleaned up, so a resolved delay leaves no
+ * dangling timer. Used by every poll loop so Ctrl-C stops promptly between
+ * ticks.
+ */
+export function delay(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve();
+            return;
+        }
+        const timer = setTimeout(() => {
+            cleanup();
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            cleanup();
+            resolve();
+        };
+        const cleanup = () => signal?.removeEventListener("abort", onAbort);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/**
+ * Delay-then-probe until `done(value)` is true or the signal aborts. Returns
+ * the last probed value. Delay-first (not probe-first) so a caller that already
+ * holds a fresh value — the batch-status loops — keeps its "poll every N
+ * seconds" cadence with no extra immediate request.
+ */
+export async function pollUntil(probe, done, options) {
+    const onError = options.onError ?? "throw";
+    let last;
+    let haveValue = false;
+    while (!options.signal.aborted) {
+        await delay(options.intervalMs, options.signal);
+        if (options.signal.aborted)
+            break;
+        try {
+            last = await probe();
+            haveValue = true;
+        }
+        catch (err) {
+            if (onError === "continue")
+                continue;
+            throw err;
+        }
+        options.onValue?.(last);
+        if (done(last))
+            return last;
+    }
+    // Aborted before `done`: return the last probed value (probe once if we never
+    // got one, so the return type holds).
+    if (!haveValue)
+        last = await probe();
+    return last;
+}
+/**
+ * Append-only tail. Bootstraps the baseline checkpoint (emitting nothing), then
+ * each tick drains forward while `hasMore` (bounded by `maxPagesPerTick`,
+ * stopping if the checkpoint fails to advance), rendering rows server-ascending.
+ * Holds no per-item state — the only carried state is the single opaque
+ * `resumeAfter` string.
+ */
+export async function followLoop(source, options) {
+    const onError = options.onError ?? "continue";
+    const maxPages = source.maxPagesPerTick ?? DEFAULT_MAX_PAGES_PER_TICK;
+    // Bootstrap: establish the baseline; do not emit its rows.
+    let resumeAfter;
+    try {
+        resumeAfter = (await source.fetchAfter(undefined)).resumeAfter;
+    }
+    catch (err) {
+        if (onError !== "continue")
+            throw err;
+        resumeAfter = ""; // fall through to polling; the next tick retries
+    }
+    while (!options.signal.aborted) {
+        try {
+            let pages = 0;
+            while (pages < maxPages && !options.signal.aborted) {
+                const page = await source.fetchAfter(resumeAfter || undefined);
+                if (page.items.length > 0)
+                    options.render(page.items);
+                const advanced = page.resumeAfter !== resumeAfter;
+                resumeAfter = page.resumeAfter;
+                pages++;
+                // Stop the within-tick drain when the burst is drained, or if the
+                // checkpoint didn't advance (guards against an endless drain).
+                if (!page.hasMore || !advanced)
+                    break;
+            }
+        }
+        catch (err) {
+            if (onError !== "continue")
+                throw err;
+            // continue: swallow and retry next tick
+        }
+        await delay(options.intervalMs, options.signal);
+    }
+}
+/**
+ * Snapshot redraw. Each tick fetches the full current snapshot and hands it to
+ * the renderer, which owns any clearing/redraw. No checkpoint, no dedup.
+ */
+export async function watchLoop(snapshot, options) {
+    const onError = options.onError ?? "continue";
+    while (!options.signal.aborted) {
+        try {
+            const items = await snapshot();
+            options.render(items);
+        }
+        catch (err) {
+            if (onError !== "continue")
+                throw err;
+        }
+        await delay(options.intervalMs, options.signal);
+    }
+}
+//# sourceMappingURL=watch.js.map

package/dist/src/lib/watch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch.js","sourceRoot":"","sources":["../../../src/lib/watch.ts"],"names":[],"mappings":"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"}

package/dist/src/lib/web-url.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The app's web counterpart, as a normalized web origin (#2982).
+ *
+ * One environment value with two jobs on the iOS side: the emailed sign-in
+ * link points at `<webUrl>/oauth/callback`, and the same origin is what an
+ * incoming universal link is trusted from. Both jobs need an ORIGIN, not just
+ * a URL that parses:
+ *
+ *   - https except loopback, the same rule the server applies to every
+ *     redirect URI (`src/auth/redirect-uri.ts`) — an origin that cannot be
+ *     allow-listed turns every sign-in request into a 400;
+ *   - no path, query or fragment: the web client derives its callback from its
+ *     own origin plus `/oauth/callback` and has no base-path mode, and the
+ *     `apple-app-site-association` component matches that exact path;
+ *   - no credentials, which have no business in a link that goes out by email.
+ *
+ * Returns the `string | true` shape `@inquirer/prompts` expects, like
+ * `validateServerUrl`, so the same function backs the flag check, the project
+ * config's field validation and any future prompt.
+ *
+ * This is the surface that EXPLAINS a rejection. The same rule is applied
+ * silently — value or nothing — by every reader that feeds `primitive.json`
+ * without going through the CLI: `normalizeWebOrigin` in `env-resolver-core.ts`
+ * (which cannot import this file; it is copied verbatim into a package that
+ * must not depend on the CLI), its bash/python3 port in the Swift template's
+ * `resolve-primitive-config.sh`, and `PrimitiveAppState.linksBaseURL` as the
+ * app's own floor. `web-url-parity` in the project-config tests pins that the
+ * two TypeScript halves accept and normalize exactly the same values.
+ */
+/**
+ * Validates a web origin. Returns `true` when valid, otherwise the message to
+ * show the user.
+ */
+export declare function validateWebUrl(value: string): string | true;
+/**
+ * The origin form of an already-validated web URL: lowercased host, explicit
+ * port kept, no trailing slash — so `https://app.example.com/` and
+ * `https://app.example.com` are stored, compared and joined identically.
+ */
+export declare function normalizeWebUrl(value: string): string;

package/dist/src/lib/web-url.js

@@ -0,0 +1,76 @@
+/**
+ * The app's web counterpart, as a normalized web origin (#2982).
+ *
+ * One environment value with two jobs on the iOS side: the emailed sign-in
+ * link points at `<webUrl>/oauth/callback`, and the same origin is what an
+ * incoming universal link is trusted from. Both jobs need an ORIGIN, not just
+ * a URL that parses:
+ *
+ *   - https except loopback, the same rule the server applies to every
+ *     redirect URI (`src/auth/redirect-uri.ts`) — an origin that cannot be
+ *     allow-listed turns every sign-in request into a 400;
+ *   - no path, query or fragment: the web client derives its callback from its
+ *     own origin plus `/oauth/callback` and has no base-path mode, and the
+ *     `apple-app-site-association` component matches that exact path;
+ *   - no credentials, which have no business in a link that goes out by email.
+ *
+ * Returns the `string | true` shape `@inquirer/prompts` expects, like
+ * `validateServerUrl`, so the same function backs the flag check, the project
+ * config's field validation and any future prompt.
+ *
+ * This is the surface that EXPLAINS a rejection. The same rule is applied
+ * silently — value or nothing — by every reader that feeds `primitive.json`
+ * without going through the CLI: `normalizeWebOrigin` in `env-resolver-core.ts`
+ * (which cannot import this file; it is copied verbatim into a package that
+ * must not depend on the CLI), its bash/python3 port in the Swift template's
+ * `resolve-primitive-config.sh`, and `PrimitiveAppState.linksBaseURL` as the
+ * app's own floor. `web-url-parity` in the project-config tests pins that the
+ * two TypeScript halves accept and normalize exactly the same values.
+ */
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1"]);
+/** The example every message ends with, so a rejection is actionable. */
+const SHAPE = "e.g. https://app.example.com (or http://localhost:5173 in dev)";
+/**
+ * Validates a web origin. Returns `true` when valid, otherwise the message to
+ * show the user.
+ */
+export function validateWebUrl(value) {
+    if (typeof value !== "string" || !value.trim()) {
+        return `Web URL cannot be empty — ${SHAPE}`;
+    }
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return `Please enter an absolute URL — ${SHAPE}`;
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+        return `Web URL must be http(s) — ${SHAPE}`;
+    }
+    if (url.protocol === "http:" && !LOOPBACK_HOSTS.has(url.hostname)) {
+        return `Web URL must use https outside localhost — the server refuses a non-loopback http redirect URI (${SHAPE})`;
+    }
+    if (url.username || url.password) {
+        return `Web URL must not carry credentials — ${SHAPE}`;
+    }
+    if (url.pathname !== "/" && url.pathname !== "") {
+        return `Web URL must be an origin with no path — the web app serves its sign-in callback on its own origin (${SHAPE})`;
+    }
+    if (url.search) {
+        return `Web URL must not carry a query — ${SHAPE}`;
+    }
+    if (url.hash) {
+        return `Web URL must not carry a fragment — ${SHAPE}`;
+    }
+    return true;
+}
+/**
+ * The origin form of an already-validated web URL: lowercased host, explicit
+ * port kept, no trailing slash — so `https://app.example.com/` and
+ * `https://app.example.com` are stored, compared and joined identically.
+ */
+export function normalizeWebUrl(value) {
+    return new URL(value).origin;
+}
+//# sourceMappingURL=web-url.js.map

package/dist/src/lib/web-url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-url.js","sourceRoot":"","sources":["../../../src/lib/web-url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC;AAE3D,yEAAyE;AACzE,MAAM,KAAK,GAAG,gEAAgE,CAAC;AAE/E;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QAC/C,OAAO,6BAA6B,KAAK,EAAE,CAAC;IAC9C,CAAC;IACD,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,kCAAkC,KAAK,EAAE,CAAC;IACnD,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QAC1D,OAAO,6BAA6B,KAAK,EAAE,CAAC;IAC9C,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QAClE,OAAO,mGAAmG,KAAK,GAAG,CAAC;IACrH,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;QACjC,OAAO,wCAAwC,KAAK,EAAE,CAAC;IACzD,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,KAAK,GAAG,IAAI,GAAG,CAAC,QAAQ,KAAK,EAAE,EAAE,CAAC;QAChD,OAAO,uGAAuG,KAAK,GAAG,CAAC;IACzH,CAAC;IACD,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;QACf,OAAO,oCAAoC,KAAK,EAAE,CAAC;IACrD,CAAC;IACD,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;QACb,OAAO,uCAAuC,KAAK,EAAE,CAAC;IACxD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC;AAC/B,CAAC"}

package/dist/src/lib/webhook-deliver.d.ts

@@ -0,0 +1,209 @@
+/**
+ * Deliver a signed preview through a webhook's real receive path (#3321).
+ *
+ * `primitive webhooks test --deliver` adds no server dispatch surface. It
+ * composes two capabilities that already exist:
+ *
+ *   1. the admin-gated preview `POST /admin/api/apps/{appId}/webhooks/{id}/test`,
+ *      which signs a payload with the same rule the receiver verifies with, and
+ *   2. the public receive endpoint `POST /app/{appId}/webhook/{webhookKey}`,
+ *      the unauthenticated path a provider posts to.
+ *
+ * So the delivery is a real delivery: the body cap, the availability check, the
+ * IP allowlist, signature verification, handshake rules, deduplication, the run
+ * row and the delivery log all run exactly as they do for a provider. Nobody
+ * gains authority they did not have — only someone who can already administer
+ * the app can obtain a signature — and nothing bypasses verification, because
+ * the signature is checked for real at the receive endpoint.
+ *
+ * ── What this module owes the caller ──────────────────────────────────────
+ *
+ * An honest report. The receive endpoint answers `{received: true}` and
+ * discloses nothing else (it must not: it is unauthenticated), so "did the
+ * function actually run?" is answered from the delivery log and the runs
+ * surface, and only positive evidence may be reported as a dispatch:
+ *
+ *   - **Correlation is one rule.** A delivery-log row NEWER than a baseline
+ *     snapshot taken before the POST, whose `dedupKey` equals the one the
+ *     preview returned. That key hashes the whole signed payload including its
+ *     timestamp prefix, so it is unique to this request rather than a
+ *     heuristic; the baseline is what keeps a replay of the same signed bytes
+ *     from being attributed here. There is no body-hash fallback: identical
+ *     bodies collide, and attributing another request's row is worse than
+ *     declining to.
+ *   - **The key names dispatched deliveries only.** The receiver writes
+ *     `dedupKey` on an `accepted` row that really dispatched and OMITS it
+ *     everywhere else — on a handshake row, a duplicate, a rejection, a 202
+ *     non-dispatch, and on the `accepted` row of a delivery whose target was
+ *     not found (`webhook-receiver.ts`, `logEvent`). That omission is what
+ *     keeps the `eventsByDedupKey` index holding exactly the deliveries that
+ *     may suppress a later one, so it is load-bearing, not incidental. The
+ *     consequence here: a delivery the receiver did not dispatch has no row
+ *     this correlator can reach, and is reported as unconfirmed — with what
+ *     the absence of the key means — rather than named from a row.
+ *   - **A run is confirmed, not assumed.** An `accepted` row names a run id
+ *     before the run finishes, and the legacy workflow branch keeps its
+ *     `accepted` row and its HTTP 200 even when the launch is skipped or
+ *     throws. So the named run is looked up on the authenticated runs surface
+ *     before dispatch is claimed.
+ *   - **Everything else is named for what it was** — a suppressed replay, a
+ *     410/403/401 refusal, each of which the receive endpoint reports for
+ *     itself — or reported as "dispatch unconfirmed", which is where a
+ *     handshake short-circuit (it can legally answer 200 `{received:true}`
+ *     before any dispatch) and a 202 non-dispatch land, since neither records
+ *     a correlatable row. Only a confirmed dispatch exits `0`.
+ */
+export type DeliverOutcome = "dispatched" | "refused" | "unconfirmed";
+export interface WebhookPreview {
+    success?: boolean;
+    payload?: unknown;
+    rawBody: string;
+    signatureHeaders: Record<string, string>;
+    verificationScheme: string;
+    timestamp?: number;
+    /** #3321 — the receive path's key; absent on a pre-upgrade server. */
+    webhookKey?: string | null;
+    /** #3321 — the owning server function, or null for a standalone webhook. */
+    functionId?: string | null;
+    /** #3321 — the correlator; null for scheme `none`. */
+    dedupKey?: string | null;
+}
+export interface WebhookEventRow {
+    eventId: string;
+    status?: string | null;
+    httpStatus?: number | null;
+    rejectionReason?: string | null;
+    dedupKey?: string | null;
+    workflowRunId?: string | null;
+    workflowRunKey?: string | null;
+    createdAt?: string | null;
+    [key: string]: unknown;
+}
+export interface EventPage {
+    items: WebhookEventRow[];
+    nextCursor?: string | null;
+}
+export interface RunPage {
+    items: any[];
+    nextCursor?: string | null;
+}
+/**
+ * The admin reads and the one admin write this flow needs.
+ *
+ * `ApiClient` satisfies it as written; the live api test implements the same
+ * five methods over the test context's authenticated client, which is what lets
+ * this module be proven end to end against a real server.
+ */
+export interface WebhookDeliverClient {
+    testWebhook(appId: string, webhookId: string, payload?: any): Promise<any>;
+    listWebhookEvents(appId: string, webhookId: string, params?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<EventPage>;
+    getWebhook(appId: string, webhookId: string): Promise<any>;
+    listFunctionRuns(appId: string, functionId: string, params?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<RunPage>;
+    listWorkflowRuns(appId: string, workflowId: string, params?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<RunPage>;
+}
+export type FetchLike = (url: string, init: any) => Promise<any>;
+export interface DeliverInput {
+    appId: string;
+    webhookId: string;
+    /** The payload to sign, passed to the preview endpoint unchanged. */
+    payload?: any;
+    /** The API base URL — the receive endpoint lives under it. */
+    serverUrl: string;
+}
+export interface DeliverDeps {
+    client: WebhookDeliverClient;
+    fetchImpl?: FetchLike;
+    sleep?: (ms: number) => Promise<void>;
+    /** Called with the side-effect notice, before anything is delivered. */
+    onBeforeDeliver?: (notice: string[]) => void;
+    /** Bounds, overridable for tests. */
+    pollAttempts?: number;
+    pollIntervalMs?: number;
+    pageCap?: number;
+    pageLimit?: number;
+    runPageCap?: number;
+    runPageLimit?: number;
+    timeoutMs?: number;
+}
+export interface DeliveryAttempt {
+    url: string;
+    /** True once the request left the CLI, whatever came back. */
+    sent: boolean;
+    status: number | null;
+    body: any;
+    duplicate: boolean;
+    /** Why no response was observed, when none was. */
+    error: string | null;
+}
+export interface RunConfirmation {
+    runId: string | null;
+    confirmed: boolean;
+    surface: "function" | "workflow" | null;
+    reason: string | null;
+}
+export interface DeliverResult {
+    outcome: DeliverOutcome;
+    /** One sentence naming what happened. */
+    headline: string;
+    /** Further lines worth printing — remediation, inspection hints. */
+    details: string[];
+    /** The side-effect announcement, printed before the delivery. */
+    notice: string[];
+    preview: WebhookPreview | null;
+    refusal: {
+        message: string;
+        code: string | null;
+    } | null;
+    delivery: DeliveryAttempt | null;
+    event: WebhookEventRow | null;
+    run: RunConfirmation | null;
+}
+/** ~5 attempts over ~4 s: the accepted row is written before execution ends. */
+export declare const DELIVER_POLL_ATTEMPTS = 5;
+export declare const DELIVER_POLL_INTERVAL_MS = 800;
+/** Cursor pages walked per attempt, so a busy log cannot outrun the poll. */
+export declare const DELIVER_PAGE_CAP = 10;
+export declare const DELIVER_PAGE_LIMIT = 25;
+/** The same bound on the runs surface, where runs start while this one waits. */
+export declare const DELIVER_RUN_PAGE_CAP = 5;
+export declare const DELIVER_RUN_PAGE_LIMIT = 50;
+/** Comfortably above the sync-function ceiling. */
+export declare const DELIVER_TIMEOUT_MS = 60000;
+/**
+ * What the user is told before a delivery happens, in the terminal rather than
+ * only in the guide: a diagnostic that mutates the app has to say so where the
+ * user is looking (criterion 4).
+ */
+export declare function deliveryNotice(scheme: string): string[];
+/**
+ * The one correlation rule: the newest row above `baselineEventId` whose
+ * `dedupKey` equals this preview's.
+ *
+ * The walk is newest-first and follows `nextCursor`, stopping at the baseline
+ * row (every row below it predates this delivery) or at `pageCap`. A null
+ * baseline means the log was empty when the snapshot was taken, so every row
+ * walked is a candidate.
+ */
+export declare function findDeliveryEvent(input: {
+    client: WebhookDeliverClient;
+    appId: string;
+    webhookId: string;
+    dedupKey: string;
+    baselineEventId: string | null;
+    pageCap?: number;
+    pageLimit?: number;
+}): Promise<WebhookEventRow | null>;
+/**
+ * Preview, deliver, correlate, confirm — the whole flow, as one result a caller
+ * renders however it likes.
+ */
+export declare function deliverWebhookTest(input: DeliverInput, deps: DeliverDeps): Promise<DeliverResult>;