@voltro/plugin-webhooks 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,849 @@
+import { AppContext } from '@voltro/runtime';
+import { Context } from 'effect';
+import { DataStore } from '@voltro/database';
+import { Effect } from 'effect';
+import { Schema } from 'effect';
+import { TableLike } from '@voltro/database';
+import { Workflow } from '@effect/workflow';
+import { WorkflowEngine } from '@effect/workflow/WorkflowEngine';
+import { WorkflowInstance } from '@effect/workflow/WorkflowEngine';
+
+/**
+ * Acquire one slot in EVERY scope for the window containing `now`
+ * (all-or-nothing: a partial acquisition is refunded before deferring,
+ * so a delivery blocked by the event-global limit doesn't waste its
+ * target's budget).
+ *
+ * Returns `{ acquired: true }` when the delivery may POST now, or
+ * `{ acquired: false, retryInMs }` where `retryInMs` is the time until
+ * the next window opens.
+ */
+export declare const acquireRateSlots: (store: DataStore, scopes: ReadonlyArray<RateScope>, now: number, windowMs?: number) => Promise<RateAcquireResult>;
+
+/** What `recordDeliveryOutcome` did — surfaced so the workflow can log
+ *  the auto-disable transition. */
+export declare interface AutoDisableOutcome {
+    /** The streak count AFTER this outcome was recorded. */
+    readonly consecutiveFailures: number;
+    /** True when THIS call flipped the target to `active=false`. */
+    readonly autoDisabled: boolean;
+}
+
+export declare const buildDeliverWebhookExecute: (ctx: AppContext, options?: DeliverWorkflowOptions) => (input: DeliverInput, _executionId: string) => Effect.Effect<{
+    finalStatus: "failed";
+    attempts: number;
+} | {
+    finalStatus: "deferred";
+    attempts: number;
+} | {
+    finalStatus: "succeeded";
+    attempts: number;
+}, never, WorkflowEngine | WorkflowInstance>;
+
+/**
+ * Build a `WebhooksServiceShape` that uses the in-process store
+ * directly + an injected `trigger` for delivery. The `trigger` is
+ * the seam where the framework wires the actual @effect/workflow
+ * runner (stage 4). For tests and the very first dev-mode loop we
+ * accept a simple async function that resolves when the workflow
+ * has been kicked off (NOT when it completes).
+ */
+export declare const buildWebhooksService: (ctx: AppContext, trigger: (input: {
+    readonly deliveryId: string;
+    readonly targetId: string;
+    readonly event: string;
+    readonly eventId: string;
+    readonly payloadJson: string;
+    readonly attemptEpoch?: number;
+}) => Promise<void>, options?: WebhooksServiceOptions) => WebhooksServiceShape;
+
+export declare const compareVersions: (targetVersion: number, eventVersion: number) => VersionState;
+
+/** Consume ONE slot from the (key, bucket) window. Returns `true`
+ *  when a slot was atomically claimed, `false` when the window is
+ *  full. Throws only on pathological contention (transient).
+ *
+ *  Ensure-then-CAS: the window row is created at `count: 0` via
+ *  `insertIgnore` over the deterministic PK (so the create race is
+ *  harmless — every racer converges on ONE row), and every slot claim
+ *  is a conditional increment (`count = read` in the WHERE). With a
+ *  deterministic key the billing-style "my minted id came back"
+ *  ownership check can't disambiguate concurrent creators, so the
+ *  insert path never claims a slot directly. */
+export declare const consumeRateSlot: (store: DataStore, scope: RateScope, bucket: number) => Promise<boolean>;
+
+export declare interface CustomSignatureScheme {
+    readonly _tag: 'custom';
+    readonly header: string;
+    readonly sign: (rawBody: Uint8Array, secret: string) => string;
+    readonly verify: (rawBody: Uint8Array, secret: string, signatureHeader: string) => boolean;
+}
+
+/** Default URL path for an incoming webhook when the descriptor
+ *  doesn't override. Stage 4's discovery walker uses this to
+ *  register routes. */
+export declare const defaultIncomingPath: (webhookId: string) => `/${string}`;
+
+/** Generic HMAC-SHA-256 — sensible default for new outgoing webhooks. */
+export declare const defaultOutgoingSignature: () => HmacSignatureScheme;
+
+/** Sensible default for new outgoing subscriptions: exponential, 8
+ *  attempts, 5s → 1h. Roughly: 5s, 10s, 20s, 40s, 80s, 160s, 320s,
+ *  640s. Total ~17 minutes before giving up. */
+export declare const defaultRetryPolicy: () => RetryPolicy;
+
+export declare const defineIncomingWebhook: <Body>(spec: Omit<IncomingWebhookDescriptor<Body>, "_tag">) => IncomingWebhookDescriptor<Body>;
+
+export declare const defineOutgoingEvent: <Payload>(spec: Omit<OutgoingEventDescriptor<Payload>, "_tag">) => OutgoingEventDescriptor<Payload>;
+
+export declare const defineWebhookProvider: (spec: Omit<WebhookProviderDescriptor, "_tag">) => WebhookProviderDescriptor;
+
+/**
+ * Build the workflow body. `ctx` carries the per-request store +
+ * runtime services — passed in by the framework when it registers
+ * the workflow's `.toLayer(...)`.
+ *
+ * The body's structure is intentionally LINEAR — one for-loop with
+ * activities marking each checkpoint. Activity caching means a
+ * crash mid-loop resumes at the next un-cached activity.
+ */
+declare interface DeliverInput {
+    readonly deliveryId: string;
+    readonly targetId: string;
+    readonly event: string;
+    readonly eventId: string;
+    readonly payloadJson: string;
+    readonly attemptEpoch?: number;
+}
+
+export declare const deliverWebhookWorkflow: Workflow.Workflow<"voltro.deliverWebhook", Workflow.AnyStructSchema | Schema.Struct<Schema.Struct.Fields>, Schema.Struct<{
+    finalStatus: Schema.Literal<["succeeded", "failed", "deferred"]>;
+    attempts: typeof Schema.Number;
+}>, typeof Schema.Never>;
+
+declare interface DeliverWorkflowOptions {
+    /** Discovered `defineOutgoingEvent` descriptors — the workflow reads
+     *  the emitted event's `globalRateLimit` from here. Absent events
+     *  simply have no global limit. */
+    readonly events?: ReadonlyArray<OutgoingEventDescriptor<unknown>>;
+    /** The fixed window backing "per minute" — injectable for tests
+     *  (production uses the 60s default). */
+    readonly rateWindowMs?: number;
+}
+
+/** Compact duration literal — parsed without a deps-pulling library.
+ *  Covers ms / s / m / h / d. Default seconds (no suffix). */
+export declare type DurationLiteral = `${number}${'ms' | 's' | 'm' | 'h' | 'd'}` | `${number}`;
+
+export declare interface EmitResult {
+    /** Stable id matching the row(s) the deliverWebhook workflow
+     *  writes to `_voltro_webhook_deliveries`. Use as the foreign
+     *  key when joining a domain event to its webhook deliveries. */
+    readonly eventId: string;
+    /** Per-target deliveries. Empty when no target matched the
+     *  filter. `'dispatched'` — a delivery workflow run was kicked
+     *  off; `'queued'` — the target is paused, so the delivery was
+     *  written as a `status='pending'` row that `resumeTarget`
+     *  flushes. */
+    readonly deliveries: ReadonlyArray<{
+        readonly targetId: string;
+        readonly deliveryId: string;
+        readonly status: 'dispatched' | 'queued';
+    }>;
+}
+
+export declare interface EncodedPayload {
+    readonly contentType: string;
+    readonly bytes: Uint8Array;
+}
+
+/** Re-encode the JSON-stringified payload into the target's wire
+ *  format. Throws `WebhookPayloadUnrepresentable` when the shape can't
+ *  be honestly represented in the requested format. */
+export declare const encodePayload: (format: WireFormat, payloadJson: string) => EncodedPayload;
+
+/** Aggressive policy — retry every 30s for an hour. Use for a
+ *  downstream that's expected to come back quickly. */
+export declare const fastRetryPolicy: () => RetryPolicy;
+
+export declare const generateSecret: () => string;
+
+export declare const getIdempotencyCache: () => IdempotencyCache;
+
+/** GitHub-style: `X-Hub-Signature-256: sha256=hex` (no timestamp). */
+export declare const githubSignature: () => HmacSignatureScheme;
+
+export declare type HmacAlgorithm = 'hmacSha256' | 'hmacSha1';
+
+export declare interface HmacSignatureScheme {
+    readonly _tag: 'hmac';
+    readonly algorithm: HmacAlgorithm;
+    /** Header the signature is written to / read from. Stripe uses
+     *  `Stripe-Signature`, GitHub uses `X-Hub-Signature-256`, generic
+     *  apps use `X-Webhook-Signature`. */
+    readonly header: string;
+    /** When `true`, the signed payload is `<timestamp>.<rawBody>` and
+     *  the header carries both (`t=...,v1=...`). Recipients reject
+     *  signatures whose `t` is older than `replayWindowSeconds`. */
+    readonly includeTimestamp: boolean;
+    /** Window during which a signed payload is replay-safe. Older
+     *  signatures get rejected. Default 5 minutes. Only relevant when
+     *  `includeTimestamp: true`. */
+    readonly replayWindowSeconds?: number;
+    /** Encoding the signature is rendered in. `hex` is most common;
+     *  Slack uses `hex` prefixed with `v0=`. */
+    readonly encoding?: 'hex' | 'base64';
+    /** Prefix written before the hex/base64 signature in the header
+     *  value. Slack: `v0=`. GitHub: `sha256=`. Default empty. */
+    readonly versionPrefix?: string;
+    /** Optional secret-rotation hint: a SECOND secret accepted during
+     *  verification but never used for outgoing signing. Lets you
+     *  rotate the primary secret without breaking in-flight inbound
+     *  deliveries. */
+    readonly previousSecret?: string;
+}
+
+/**
+ * In-process LRU cache for idempotency keys. Map preserves insertion
+ * order, so eviction = `entries().next().value` (the oldest key).
+ *
+ * `claim(key, ttlMs)` returns one of:
+ *   - `'fresh'`        — first time we've seen this key; handler runs.
+ *   - `'inflight'`     — another concurrent request claimed it but
+ *                        hasn't completed. Receiver should 409 / 425.
+ *   - `'duplicate'`    — already processed within TTL. Receiver
+ *                        should 200 OK (idempotent re-acknowledge).
+ *
+ * After the handler completes, call `commit(key)` to flip the
+ * 'inflight' marker to 'processed'. On handler failure, call
+ * `release(key)` to drop the inflight marker so a retry can run.
+ */
+export declare class IdempotencyCache {
+    private readonly capacity;
+    private readonly cache;
+    constructor(capacity?: number);
+    private evictExpired;
+    claim(key: string, ttlMs: number): 'fresh' | 'inflight' | 'duplicate';
+    commit(key: string): void;
+    release(key: string): void;
+    size(): number;
+    /** Test helper. */
+    clear(): void;
+}
+
+export declare interface IncomingLogRecord {
+    readonly webhookId: string;
+    readonly status: number;
+    readonly signatureOk: boolean | 'skipped';
+    readonly idempotency: 'fresh' | 'inflight' | 'duplicate' | 'skipped';
+    readonly durationMs: number;
+    readonly errorMessage?: string;
+}
+
+export declare interface IncomingRequest {
+    readonly method: string;
+    readonly path: string;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly rawBody: Uint8Array;
+}
+
+export declare interface IncomingResponse {
+    readonly status: number;
+    readonly contentType: string;
+    readonly body: string;
+    readonly headers?: Readonly<Record<string, string>>;
+}
+
+export declare interface IncomingWebhookContext<Body> {
+    /** The fully-decoded body, validated against `payload`. */
+    readonly body: Body;
+    /** Raw bytes — needed to recompute signatures. Already used by
+     *  the framework's middleware to verify the inbound signature
+     *  before this handler runs; passed along in case the user wants
+     *  to compute additional MAC's for downstream relays. */
+    readonly rawBody: Uint8Array;
+    /** Request headers (lowercased keys). The middleware has already
+     *  consumed signature / idempotency headers. */
+    readonly headers: Readonly<Record<string, string>>;
+    /** Idempotency key extracted by the middleware (provider-specific
+     *  extraction — Stripe uses `Stripe-Signature`'s `t=`, GitHub uses
+     *  `X-GitHub-Delivery`, generic uses `Idempotency-Key`). */
+    readonly idempotencyKey: string;
+    /** Workflow facade supplied by the framework runtime. Use this for
+     *  verified external incoming calls that should start or signal
+     *  durable workflows after signature + idempotency checks pass. */
+    readonly workflows?: IncomingWorkflowFacade;
+}
+
+export declare interface IncomingWebhookDescriptor<Body> {
+    readonly _tag: 'incomingWebhook';
+    readonly id: WebhookId;
+    /** URL path the framework mounts the route on. Defaults to
+     *  `/webhooks/<id>` if absent. Use a custom path for legacy
+     *  integrations (`/integrations/stripe/v1`). */
+    readonly path?: `/${string}`;
+    /** Signature scheme used to authenticate inbound requests. Reject
+     *  on mismatch with a 401. `undefined` (the default) means NO
+     *  verification — only acceptable when behind a separate trust
+     *  boundary (gateway + IP allow-list). The dashboard surfaces a
+     *  warning for unsigned incoming webhooks. */
+    readonly signature?: SignatureScheme;
+    /** Idempotency key extraction. Default `'Idempotency-Key'` header.
+     *  Provider-templates override this to match the provider's wire
+     *  format. */
+    readonly idempotency?: {
+        /** Header name OR a function that reads from headers/body. */
+        readonly from: string | ((headers: Readonly<Record<string, string>>, rawBody: Uint8Array) => string | undefined);
+        /** TTL the framework retains the key for de-dup. Default 7 days. */
+        readonly ttl?: '5m' | '1h' | '6h' | '1d' | '7d' | '30d';
+    };
+    /** Validated body schema. The framework decodes the request body
+     *  AFTER signature verification, BEFORE the handler runs. */
+    readonly payload: Schema.Schema<Body>;
+    /** Body parser — JSON by default. Stripe / GitHub send `application/json`
+     *  but other providers use `application/x-www-form-urlencoded`. */
+    readonly bodyType?: 'json' | 'form' | 'raw';
+    /** Provider preset — when set, the framework fills `signature` +
+     *  `idempotency` + `bodyType` from the provider's known shape.
+     *  Explicit fields above always win. */
+    readonly provider?: WebhookProviderDescriptor;
+    /** Typed handler. Returns void on success, throws to reject. The
+     *  HTTP status is 2xx for success, 4xx for typed validation
+     *  errors, 5xx for handler exceptions. The framework retries
+     *  5xx-classified failures via the provider's expected behavior
+     *  (most providers retry their own POST on 5xx). */
+    readonly handler: (context: IncomingWebhookContext<Body>) => Promise<void> | void;
+}
+
+export declare interface IncomingWorkflowFacade {
+    start<Payload = unknown>(workflowName: string, payload: Payload): Promise<{
+        readonly id: string;
+        readonly workflowName: string;
+        readonly executionId: string;
+        readonly status: 'running';
+    }>;
+    signal(target: {
+        readonly id?: string;
+        readonly executionId?: string;
+        readonly workflowName?: string;
+    }, signalName: string, payload?: unknown): Promise<{
+        readonly eventId: string;
+    }>;
+    update(target: {
+        readonly id?: string;
+        readonly executionId?: string;
+        readonly workflowName?: string;
+    }, updateName: string, payload?: unknown, options?: {
+        readonly timeoutMs?: number;
+        readonly pollIntervalMs?: number;
+    }): Promise<{
+        readonly eventId: string;
+        readonly updateId: string;
+        readonly completedEventId: string;
+        readonly result: unknown;
+    }>;
+}
+
+/** Type guard for file-walker discovery — every `*.webhook.tsx`
+ *  must default-export one of these. */
+export declare const isWebhookDescriptor: (value: unknown) => value is WebhookDescriptor;
+
+/** Evaluate a target's filter against a payload. Returns `true`
+ *  when the target should receive this delivery. Supports the
+ *  simple key-path form `'payload.field': value` for v1; future
+ *  versions can grow operators ({ gt, lt, in, … }). */
+export declare const matchesFilter: (filter: Readonly<Record<string, unknown>> | null, payload: unknown) => boolean;
+
+/**
+ * Build a request handler for a specific `IncomingWebhookDescriptor`.
+ * The returned function is what stage 4 mounts on the HTTP layer.
+ */
+export declare const mountIncomingWebhook: <Body>(descriptor: IncomingWebhookDescriptor<Body>, options: MountOptions) => (request: IncomingRequest) => Promise<IncomingResponse>;
+
+export declare interface MountOptions {
+    /** Resolves the per-webhook signing secret. Return `null` to
+     *  skip signature verification (a warning logs to the framework
+     *  logger; the user has explicitly opted out). */
+    readonly resolveSecret: (webhookId: string) => Promise<string | null>;
+    /** Optional idempotency cache override. Defaults to the
+     *  process-singleton LRU. Pass a custom cache for tests or for a
+     *  shared (Redis-backed) cache across processes. */
+    readonly idempotencyCache?: IdempotencyCache;
+    /** Optional structured logger — receives `{ webhookId, event,
+     *  status, durationMs, signatureOk, idempotencyResult }` per
+     *  request. Defaults to a no-op so unit tests don't print noise. */
+    readonly log?: (record: IncomingLogRecord) => void;
+    /** Optional workflow facade. Resolved lazily so host runtimes can
+     *  mount incoming routes before workflow layers finish booting. */
+    readonly resolveWorkflows?: () => IncomingWorkflowFacade | undefined;
+}
+
+/** Compute the next-retry decision given the policy + the attempt
+ *  number that just failed (1-indexed: `attempt=1` after the first
+ *  try) + optional recipient hints from the failed response. Returns
+ *  `null` when no more retries are allowed. */
+export declare const nextRetry: (policy: RetryPolicy, attempt: number, lastResponse?: {
+    readonly status?: number;
+    readonly retryAfterSeconds?: number;
+}) => RetryDecision | null;
+
+export declare interface OutgoingEventDescriptor<Payload> {
+    readonly _tag: 'outgoingEvent';
+    readonly id: WebhookId;
+    /** Human-readable summary surfaced in the dashboard's events list. */
+    readonly description?: string;
+    /** Payload schema — drives JSON-Schema export for the dashboard's
+     *  "view example" affordance and the typed `emit()` call site
+     *  (pass the descriptor itself to `emit(descriptor, payload)` to
+     *  type the payload; either way `emit` DECODES the payload against
+     *  this schema and rejects a mismatch with `WebhookPayloadInvalid`
+     *  before any delivery is created). Recipients receive
+     *  `{ event, eventId, occurredAt, payload }` with `payload`
+     *  matching this schema. */
+    readonly payload: Schema.Schema<Payload>;
+    /** Schema version. Increment when the payload shape changes in a
+     *  way subscribers must adapt to. The dashboard surfaces version
+     *  divergence per-target. New subscriptions pin to this version by
+     *  default. Default 1. */
+    readonly version?: number;
+    /** Default retry policy for new subscriptions of this event —
+     *  applied when the subscriber doesn't pass `retry` explicitly
+     *  (explicit wins, then this, then the package default). */
+    readonly defaultRetry?: RetryPolicy;
+    /** Default signing scheme for new subscriptions of this event —
+     *  applied when the subscriber doesn't pass `signing` explicitly
+     *  (explicit wins, then this, then HMAC-SHA-256 with a generated
+     *  32-byte secret). */
+    readonly defaultSigning?: SignatureScheme;
+    /** Rate-limit ceiling that ALL deliveries of this event share —
+     *  protects against a runaway emit loop. Enforced by the delivery
+     *  workflow as a fixed-window counter at the shared store (holds
+     *  across replicas); over-limit deliveries are DEFERRED to the
+     *  next window (parked as `status='pending'` rows), never dropped.
+     *  Per-target rate-limits are configured at subscribe time. */
+    readonly globalRateLimit?: {
+        readonly perMinute: number;
+    };
+}
+
+export declare const parseDuration: (literal: DurationLiteral) => number;
+
+export declare const parseTtl: (literal: keyof typeof TTL_MS | undefined) => number;
+
+/** The fixed window backing "per minute". Injectable in
+ *  `buildDeliverWebhookExecute` options for tests; production always
+ *  uses the default. */
+export declare const RATE_WINDOW_MS = 60000;
+
+export declare const RATE_WINDOW_TABLE = "_voltro_webhook_rate_windows";
+
+export declare interface RateAcquireResult {
+    readonly acquired: boolean;
+    /** When `acquired === false`: milliseconds until the next window
+     *  opens — the caller durable-sleeps this long, then re-acquires.
+     *  `0` when acquired. */
+    readonly retryInMs: number;
+}
+
+/** One rate-limit scope a delivery must hold a slot in before POSTing.
+ *  `target:<targetId>` for the per-target limit, `event:<eventId>` for
+ *  an event's global limit. */
+export declare interface RateScope {
+    readonly key: string;
+    /** Max deliveries admitted per window for this scope. */
+    readonly limit: number;
+}
+
+/**
+ * Record a terminal delivery outcome against the target's failure
+ * streak. `succeeded === true` resets the streak to 0; otherwise it
+ * CAS-increments and auto-disables when the streak reaches
+ * `autoDisableAfter` (a positive integer; null/≤0 disables the
+ * feature). `reason` is the terminal failure detail stamped onto the
+ * target when the auto-disable fires. Returns the post-write streak +
+ * whether THIS call auto-disabled.
+ */
+export declare const recordDeliveryOutcome: (store: DataStore, targetId: string, succeeded: boolean, reason: string, now?: Date) => Promise<AutoDisableOutcome>;
+
+/** Refund a slot claimed by `consumeRateSlot` — used when a later scope
+ *  in the same acquisition denies, so a deferred delivery doesn't burn
+ *  window budget it never used. */
+export declare const releaseRateSlot: (store: DataStore, key: string, bucket: number) => Promise<void>;
+
+/** Apply defaults + freeze the resolved target descriptor. Pure.
+ *
+ *  Default resolution is three-tiered: the subscriber's explicit
+ *  value wins, then the event descriptor's per-event defaults
+ *  (`defaultSigning` / `defaultRetry` / `version` from
+ *  `defineOutgoingEvent`), then the package-global defaults. */
+export declare const resolveSubscribe: (input: SubscribeInput, event?: OutgoingEventDescriptor<unknown>) => {
+    readonly id: string;
+    readonly event: string;
+    readonly url: string;
+    readonly secret: string;
+    readonly signing: SignatureScheme;
+    readonly retry: RetryPolicy;
+    readonly filter: Readonly<Record<string, unknown>> | null;
+    readonly headers: Readonly<Record<string, string>> | null;
+    readonly rateLimitPerMinute: number | null;
+    readonly active: boolean;
+    readonly format: "json" | "form" | "xml";
+    readonly autoDisableAfter: number | null;
+    readonly consecutiveFailures: number;
+    readonly autoDisabledAt: Date | null;
+    readonly autoDisableReason: string | null;
+    readonly payloadVersion: number;
+    readonly description: string | null;
+};
+
+export declare interface RetryDecision {
+    /** Milliseconds to sleep before the next attempt. */
+    readonly delayMs: number;
+    /** The strategy-computed delay before jitter was applied — surfaced
+     *  for log lines like `next attempt 1.2s (base 1.0s + jitter)`. */
+    readonly baseDelayMs: number;
+}
+
+export declare interface RetryPolicy {
+    readonly strategy: RetryStrategy;
+    /** Max total attempts including the first. After this, the
+     *  delivery is marked `failed` permanently. Default 8 attempts
+     *  with exponential gives ~8.5h of total wait before giving up. */
+    readonly maxAttempts: number;
+    /** First-retry delay. Subsequent delays derive from `strategy`. */
+    readonly initialDelay: DurationLiteral;
+    /** Cap on any single delay. Hard-stops exponential growth. */
+    readonly maxDelay: DurationLiteral;
+    /** HTTP status codes that trigger a retry. Anything outside this
+     *  list is a permanent failure (won't retry). Default covers the
+     *  conservative "transient" set: 408 / 425 / 429 / 5xx. */
+    readonly retryOn?: ReadonlyArray<number>;
+    /** When the recipient returns `Retry-After` (HTTP standard), honour
+     *  it instead of computing our own delay. Default true. */
+    readonly honourRetryAfter?: boolean;
+    /** Jitter mode applied on top of computed delay. `none` is
+     *  deterministic (useful for tests); `full` is the cheapest
+     *  thundering-herd guard for many subscribers retrying together. */
+    readonly jitter?: 'none' | 'full';
+}
+
+export declare type RetryStrategy = 'fixed' | 'linear' | 'exponential';
+
+export declare type SignatureScheme = HmacSignatureScheme | CustomSignatureScheme;
+
+export declare interface SignedPayload {
+    /** Header value to set on the outbound request. */
+    readonly headerValue: string;
+    /** Header name from the scheme. */
+    readonly headerName: string;
+    /** Timestamp embedded in the header (when `includeTimestamp`).
+     *  Surfaced so callers can log it alongside delivery records. */
+    readonly timestamp?: number;
+}
+
+/** Produce the signature header value for an outbound request. */
+export declare const signPayload: (scheme: SignatureScheme, rawBody: Uint8Array, secret: string) => SignedPayload;
+
+/** Slack-style: `X-Slack-Signature: v0=hex` with `X-Slack-Request-Timestamp` separate.
+ *  Slack's actual header layout is non-standard — the timestamp lives
+ *  in a SECOND header rather than embedded in the signature header.
+ *  We model it via a custom scheme that reads both headers in `verify`. */
+export declare const slackSignature: () => CustomSignatureScheme;
+
+/** Stripe-style: `Stripe-Signature: t=NNN,v1=hex`, 5-min replay window. */
+export declare const stripeSignature: (header?: string) => HmacSignatureScheme;
+
+export declare interface SubscribeInput {
+    readonly event: string;
+    readonly url: string;
+    /** Secret used to sign deliveries to this target. Auto-generated
+     *  when omitted (32-byte hex). The caller receives it ONCE in the
+     *  return value — store it if you want to display it again later. */
+    readonly secret?: string;
+    readonly signing?: SignatureScheme;
+    readonly retry?: RetryPolicy;
+    /** Optional predicate filter — only emits whose payload matches
+     *  this predicate fan-out to this target. The shape mirrors the
+     *  schema-builder's `Predicate` from `@voltro/database`. */
+    readonly filter?: Readonly<Record<string, unknown>>;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly rateLimitPerMinute?: number;
+    readonly format?: 'json' | 'form' | 'xml';
+    /** Auto-disable the target after this many CONSECUTIVE terminal
+     *  delivery failures (dead-letter guard). Omit / `undefined` to
+     *  leave it OFF. Must be a positive integer when set. */
+    readonly autoDisableAfter?: number;
+    readonly payloadVersion?: number;
+    readonly description?: string;
+}
+
+export declare interface SubscribeResult {
+    readonly id: string;
+    readonly event: string;
+    readonly url: string;
+    /** Secret. Surfaced ONLY at subscribe time. The dashboard's
+     *  rotate-secret UI returns the new secret here; subsequent reads
+     *  via `getTarget(id)` redact it. */
+    readonly secret: string;
+    readonly signing: SignatureScheme;
+    readonly retry: RetryPolicy;
+}
+
+export declare const TARGETS_TABLE = "_voltro_webhook_targets";
+
+export declare interface TargetSummary {
+    readonly id: string;
+    readonly event: string;
+    readonly url: string;
+    readonly active: boolean;
+    readonly rateLimitPerMinute: number | null;
+    readonly description: string | null;
+    readonly payloadVersion: number;
+    /** Auto-disable threshold (`null` = OFF). */
+    readonly autoDisableAfter: number | null;
+    /** Current consecutive terminal-failure streak. */
+    readonly consecutiveFailures: number;
+    /** When this target was auto-disabled (`null` = not auto-disabled).
+     *  A non-null value + `active:false` distinguishes an auto-disabled
+     *  target from a manually-paused one on the dashboard. */
+    readonly autoDisabledAt: string | null;
+    /** The terminal failure reason that tripped the auto-disable. */
+    readonly autoDisableReason: string | null;
+}
+
+declare const TTL_MS: Record<string, number>;
+
+/**
+ * Convenience accessor for handlers. The framework's `AppContext`
+ * types the `webhooks` slot as `unknown` to avoid a circular dep
+ * between `@voltro/runtime` and `@voltro/plugin-webhooks`; this
+ * helper performs the structural cast and throws if the plugin
+ * isn't active.
+ *
+ *     import { useWebhooks } from '@voltro/plugin-webhooks'
+ *     const execute = async (input, ctx) => {
+ *       const webhooks = useWebhooks(ctx)
+ *       await webhooks.emit('order.completed', { orderId: input.id })
+ *     }
+ */
+export declare const useWebhooks: (ctx: {
+    readonly webhooks?: unknown;
+}) => WebhooksServiceShape;
+
+export declare const useWebhooksEffect: Effect.Effect<WebhooksServiceShape, never, WebhooksService>;
+
+/** Validate subscribe input. Throws on policy violations so the
+ *  caller's catch block can surface a 422-style error. */
+export declare const validateSubscribe: (input: SubscribeInput) => void;
+
+export declare type VerifyResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+
+/** Constant-time signature verification for an incoming request.
+ *  Returns the structured result so callers can attach the
+ *  specific reason to a 401 response (helpful in dev, OK to elide
+ *  in prod). */
+export declare const verifySignature: (scheme: SignatureScheme, rawBody: Uint8Array, secret: string, receivedHeaderValue: string | undefined) => VerifyResult;
+
+/** Compare a target's pinned `payloadVersion` against the event's
+ *  current `version`. Three states:
+ *
+ *    - `current` — version match. Target sees the current shape.
+ *    - `behind`  — target.payloadVersion < event.version. The
+ *                  consumer is reading an older shape; the dashboard
+ *                  surfaces a warning + "Re-pin" affordance.
+ *    - `ahead`   — target.payloadVersion > event.version. Rare —
+ *                  usually a config error (someone re-pinned to a
+ *                  not-yet-released version). The dashboard flags
+ *                  this as a config-issue, not a normal divergence.
+ */
+export declare type VersionState = 'current' | 'behind' | 'ahead';
+
+/**
+ * Thrown by `WebhooksService.replay` when no delivery row exists for the
+ * given `deliveryId` — the row can't be re-triggered because the
+ * original payload + target are unknown.
+ */
+export declare class WebhookDeliveryNotFound extends WebhookDeliveryNotFound_base {
+}
+
+declare const WebhookDeliveryNotFound_base: Schema.TaggedErrorClass<WebhookDeliveryNotFound, "WebhookDeliveryNotFound", {
+    readonly _tag: Schema.tag<"WebhookDeliveryNotFound">;
+} & {
+    /** The delivery id that did not resolve to a row. */
+    deliveryId: typeof Schema.String;
+}>;
+
+export declare type WebhookDescriptor = OutgoingEventDescriptor<unknown> | IncomingWebhookDescriptor<unknown> | WebhookProviderDescriptor;
+
+/** Stable identifier for an event or webhook. Drives the database
+ *  primary key, the inspect endpoint URL, the dashboard listing. Use
+ *  dotted-camelCase (`order.completed`, `user.signedUp`). */
+export declare type WebhookId = string;
+
+/**
+ * Thrown by `WebhooksService.emit` when the payload does not decode
+ * against the outgoing event's declared `payload` schema (from its
+ * `defineOutgoingEvent` descriptor). The emit is rejected BEFORE any
+ * delivery row is written or workflow triggered — a schema-violating
+ * payload never reaches a subscriber.
+ */
+export declare class WebhookPayloadInvalid extends WebhookPayloadInvalid_base {
+}
+
+declare const WebhookPayloadInvalid_base: Schema.TaggedErrorClass<WebhookPayloadInvalid, "WebhookPayloadInvalid", {
+    readonly _tag: Schema.tag<"WebhookPayloadInvalid">;
+} & {
+    /** The outgoing event id the payload was emitted for. */
+    event: typeof Schema.String;
+    /** Tree-formatted schema decode issues (one line per violation). */
+    issues: typeof Schema.String;
+}>;
+
+/**
+ * Raised by the delivery workflow's wire-encoder when the target's
+ * `format` (`form` | `xml`) cannot honestly represent the payload
+ * shape — e.g. a `form` target whose payload is a bare array/scalar
+ * (form encoding is a flat key=value list with no top-level array
+ * representation), or an `xml` target whose object key is not a valid
+ * XML element name. Surfaced BEFORE any wire POST: the delivery row is
+ * written `failed` with this reason, so a mis-formatted target never
+ * silently ships JSON bytes under a wrong content-type.
+ */
+export declare class WebhookPayloadUnrepresentable extends WebhookPayloadUnrepresentable_base {
+}
+
+declare const WebhookPayloadUnrepresentable_base: Schema.TaggedErrorClass<WebhookPayloadUnrepresentable, "WebhookPayloadUnrepresentable", {
+    readonly _tag: Schema.tag<"WebhookPayloadUnrepresentable">;
+} & {
+    /** The wire format that could not represent the payload. */
+    format: Schema.Literal<["json", "form", "xml"]>;
+    /** Human-readable detail — which shape/key defeated the encoder. */
+    reason: typeof Schema.String;
+}>;
+
+/**
+ * Thrown by `WebhooksService.updateTargetPayloadVersion` when the
+ * requested version is not a positive integer.
+ */
+export declare class WebhookPayloadVersionInvalid extends WebhookPayloadVersionInvalid_base {
+}
+
+declare const WebhookPayloadVersionInvalid_base: Schema.TaggedErrorClass<WebhookPayloadVersionInvalid, "WebhookPayloadVersionInvalid", {
+    readonly _tag: Schema.tag<"WebhookPayloadVersionInvalid">;
+} & {
+    /** The rejected version value (as supplied by the caller). */
+    version: typeof Schema.Number;
+}>;
+
+export declare interface WebhookProviderDescriptor {
+    readonly _tag: 'webhookProvider';
+    readonly id: string;
+    /** Display name for the dashboard. */
+    readonly name: string;
+    readonly signature: SignatureScheme;
+    readonly idempotency: NonNullable<IncomingWebhookDescriptor<unknown>['idempotency']>;
+    readonly bodyType: 'json' | 'form' | 'raw';
+    /** Optional discriminator: provider-specific event-type extraction
+     *  (e.g. Stripe's top-level `type` field). Used by typed handlers
+     *  to narrow on payload variant. */
+    readonly eventTypeFrom?: (body: unknown) => string | undefined;
+}
+
+export declare class WebhooksService extends WebhooksService_base {
+}
+
+declare const WebhooksService_base: Context.TagClass<WebhooksService, "@voltro/webhooks/WebhooksService", WebhooksServiceShape>;
+
+export declare interface WebhooksServiceOptions {
+    /** Discovered `defineOutgoingEvent` descriptors. When present,
+     *  `subscribe` resolves the event's `defaultSigning` /
+     *  `defaultRetry` / `version` before the package-global defaults,
+     *  and `emit` decodes the payload against the event's schema. */
+    readonly events?: ReadonlyArray<OutgoingEventDescriptor<unknown>>;
+}
+
+export declare interface WebhooksServiceShape {
+    readonly subscribe: (input: SubscribeInput) => Promise<SubscribeResult>;
+    /** Emit an event to every subscribed target. Accepts the event id
+     *  OR the `defineOutgoingEvent` descriptor itself — passing the
+     *  descriptor types `payload` against its schema at the call site.
+     *  Either way, when the descriptor is known (directly or via the
+     *  discovered-events registry) the payload is DECODED against its
+     *  schema and a mismatch throws `WebhookPayloadInvalid` before any
+     *  delivery is created. */
+    readonly emit: <P>(event: string | OutgoingEventDescriptor<P>, payload: P) => Promise<EmitResult>;
+    /** Manual re-trigger for the dashboard's "Replay" button on a
+     *  failed delivery row. Re-runs the workflow at attempt 1 with
+     *  the original payload. */
+    readonly replay: (deliveryId: string) => Promise<void>;
+    /** List currently-subscribed targets for an event, or all when
+     *  `event` is omitted. The dashboard's "Targets" page consumes
+     *  this. */
+    readonly listTargets: (event?: string) => Promise<ReadonlyArray<TargetSummary>>;
+    /** Soft-disable a target without deleting the row. While paused,
+     *  emits against this target queue under
+     *  `_voltro_webhook_deliveries` with status='pending' (no POST
+     *  happens); `resumeTarget` flushes them. */
+    readonly pauseTarget: (targetId: string) => Promise<void>;
+    /** Re-enable a paused target AND flush its queued
+     *  `status='pending'` deliveries through the normal delivery
+     *  workflow, in emit order (`createdAt` ascending — millisecond
+     *  granularity) per target. */
+    readonly resumeTarget: (targetId: string) => Promise<void>;
+    /** Hard-delete a target. Its queued `status='pending'` rows are
+     *  deleted with it (nothing left to flush); an in-flight workflow
+     *  run's `fetch-target` activity sees a null row and exits
+     *  cleanly. */
+    readonly deleteTarget: (targetId: string) => Promise<void>;
+    /** Rotate the per-target signing secret. Returns the new secret
+     *  ONCE — store it client-side if you need to display it again.
+     *  In-flight retries continue with the OLD secret since signing
+     *  happens at attempt time using the row's then-current value
+     *  (acceptable: providers retry within seconds, the rotation
+     *  window is tight). */
+    readonly rotateSecret: (targetId: string) => Promise<{
+        readonly secret: string;
+    }>;
+    /** Re-pin a target's `payloadVersion` to the event's current
+     *  version. Called from the dashboard's "Re-pin" action after
+     *  the consumer has updated their handler to accept the new
+     *  payload shape. */
+    readonly updateTargetPayloadVersion: (targetId: string, version: number) => Promise<void>;
+}
+
+/**
+ * Thrown by `WebhooksService.subscribe` (via `validateSubscribe`) when
+ * the subscribe input fails a policy check — a non-http(s) URL, a secret
+ * shorter than the minimum, a degenerate retry policy, or an
+ * out-of-range rate limit. `field` names the offending input field;
+ * `reason` is the human-readable detail (carries the offending value).
+ */
+export declare class WebhookSubscribeInvalid extends WebhookSubscribeInvalid_base {
+}
+
+declare const WebhookSubscribeInvalid_base: Schema.TaggedErrorClass<WebhookSubscribeInvalid, "WebhookSubscribeInvalid", {
+    readonly _tag: Schema.tag<"WebhookSubscribeInvalid">;
+} & {
+    /** The offending subscribe-input field: `'url'` | `'event'` |
+     *  `'secret'` | `'retry'` | `'rateLimitPerMinute'`. */
+    field: typeof Schema.String;
+    /** Human-readable detail, including the offending value. */
+    reason: typeof Schema.String;
+}>;
+
+/**
+ * Return the framework-managed tables the webhooks plugin adds.
+ * Consumed by the plugin entry's `registerSchema` hook so the
+ * bootstrap migration creates the tables BEFORE any user
+ * migration runs.
+ */
+export declare const webhookTables: () => ReadonlyArray<TableLike>;
+
+export declare type WireFormat = 'json' | 'form' | 'xml';
+
+export { }