primitive-admin 1.0.63 → 1.0.64

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>;