@xtandard/webhooks 0.1.1 → 0.1.3

package/dist/types-elysia2/auth/contract.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Authentication contract. Answers: "Who is this request from?"
+ *
+ * `@xtandard/webhooks` ships `none`/`basic`/`delegated` implementations, but any
+ * object satisfying {@link AuthProvider} works — bring your own.
+ *
+ * @module
+ */
+/** An authenticated identity. */
+export interface Principal {
+    id: string;
+    email?: string;
+    name?: string;
+    roles?: string[];
+    metadata?: unknown;
+}
+/** Authenticates an incoming web-standard {@link Request}. */
+export interface AuthProvider {
+    /** Resolve the principal, or `null` if the request is unauthenticated. */
+    authenticate(request: Request): Promise<Principal | null>;
+    /**
+     * Optional: build a `Response` that prompts for credentials (e.g. a 401 with a
+     * `WWW-Authenticate` header). When omitted, the server returns a plain 401.
+     */
+    challenge?(request: Request): Response | undefined;
+}

package/dist/types-elysia2/authorization/contract.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Authorization contract. Answers: "Can this principal perform this action on
+ * this resource?"
+ *
+ * Every mutating admin API route consults the {@link AuthorizationProvider}.
+ * Ships `none`/`roles`/`delegated` implementations.
+ *
+ * @module
+ */
+import type { Principal } from "../auth/contract.ts";
+/** The full set of authorizable actions. */
+export type WebhooksAction = "application:read" | "application:create" | "application:update" | "application:delete" | "event-type:read" | "event-type:create" | "event-type:update" | "event-type:delete" | "endpoint:read" | "endpoint:create" | "endpoint:update" | "endpoint:delete" | "endpoint:rotate-secret" | "endpoint:read-secret" | "message:read" | "message:publish" | "delivery:read" | "delivery:retry" | "audit:read";
+/** The resource an action targets. */
+export type WebhooksResource = {
+    type: "application";
+    applicationKey: string;
+} | {
+    type: "event-type";
+    name: string;
+} | {
+    type: "endpoint";
+    applicationKey: string;
+    endpointId: string;
+} | {
+    type: "message";
+    applicationKey: string;
+    messageId?: string;
+} | {
+    type: "delivery";
+    applicationKey: string;
+    deliveryId?: string;
+} | {
+    type: "audit";
+    applicationKey?: string;
+};
+/** Input passed to {@link AuthorizationProvider.authorize}. */
+export interface AuthorizeInput {
+    principal: Principal | null;
+    action: WebhooksAction;
+    resource: WebhooksResource;
+    request: Request;
+}
+/** Decides whether an action is permitted. */
+export interface AuthorizationProvider {
+    authorize(input: AuthorizeInput): Promise<boolean>;
+}
+/** Actions that mutate state — blocked in readonly mode. */
+export declare const MUTATING_ACTIONS: ReadonlySet<WebhooksAction>;
+/** True if the action mutates state. */
+export declare const isMutatingAction: (action: WebhooksAction) => boolean;

package/dist/types-elysia2/canonical.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Canonical JSON serialization: object keys sorted recursively, so two values
+ * that are structurally equal produce byte-identical output regardless of key
+ * insertion order.
+ *
+ * Used for the idempotency comparison in {@link ./core.WebhooksCore.publish}:
+ * some control-plane stores canonicalize object key order on round-trip
+ * (Postgres `jsonb`, some BSON paths), so a stored payload read back may have a
+ * different key order than the freshly-published one. An order-sensitive
+ * comparison would then flag an identical re-publish as an
+ * `IdempotencyConflictError`. Comparing canonical forms fixes it uniformly,
+ * independent of the storage adapter.
+ *
+ * @module
+ */
+import type { JsonValue } from "./schema.ts";
+/**
+ * Serialize a JSON value with object keys sorted lexicographically at every
+ * depth. Arrays keep their order (order is semantic for arrays); `undefined`
+ * inside objects is dropped exactly as `JSON.stringify` would.
+ *
+ * @example
+ * ```ts
+ * canonicalStringify({ b: 1, a: 2 }) === canonicalStringify({ a: 2, b: 1 }); // true
+ * ```
+ */
+export declare function canonicalStringify(value: JsonValue): string;

package/dist/types-elysia2/core.d.ts

@@ -0,0 +1,344 @@
+/**
+ * Admin + publish core — the operations layer the API, CLI, and dispatcher sit
+ * on top of.
+ *
+ * Owns the split between the **control plane** (CRUD on applications / event
+ * types / endpoints, browsing messages and deliveries, replay — rare,
+ * human-driven, hook-guarded, audited) and the **delivery plane** (`publish()`
+ * + the dispatcher's claim/record internals — the hot path). `publish()` never
+ * performs an HTTP call and never throws because an endpoint is down: it
+ * persists one message and fans out one pending delivery per matching enabled
+ * endpoint; the dispatcher owns all network I/O.
+ *
+ * Storage can be split: control data lives in `storage`, while deliveries +
+ * the due index live in `queueStorage` (defaults to `storage`) — e.g. control
+ * in Postgres, queue in Redis.
+ *
+ * @module
+ */
+import { type AttemptOutcome, type SignedRequest } from "./deliver.ts";
+import { type DeliveryErrorReporter, type DeliveryListener } from "./delivery-sink.ts";
+import type { DispatcherOptions } from "./dispatcher.ts";
+import type { Actor, Application, AuditEntry, Delivery, DeliveryAttempt, Endpoint, EventType, JsonValue, Message, WebhookDuration } from "./schema.ts";
+import { type WebhooksStorage } from "./storage/contract.ts";
+import type { HookErrorReporter, WebhooksHooks, WebhooksHooksInput } from "./hooks/contract.ts";
+/** Thrown by mutating operations when the core is in readonly mode. */
+export declare class ReadonlyError extends Error {
+    constructor(operation: string);
+}
+/** Thrown when a referenced application/event type/endpoint/delivery does not exist. */
+export declare class NotFoundError extends Error {
+    constructor(message: string);
+}
+/** Thrown when creating an entity whose key already exists. Maps to HTTP 409. */
+export declare class ConflictError extends Error {
+    constructor(message: string);
+}
+/** Thrown by {@link WebhooksCore.publish} when the payload exceeds the limit. Maps to 413. */
+export declare class PayloadTooLargeError extends Error {
+    constructor(size: number, limit: number);
+}
+/**
+ * Thrown by {@link WebhooksCore.publish} when an idempotency key is reused with
+ * a **different** payload (same key + same payload returns the original
+ * message instead). Maps to HTTP 409.
+ */
+export declare class IdempotencyConflictError extends Error {
+    constructor(key: string);
+}
+/**
+ * One retention rule set. When both fields are set, an item is **kept if either
+ * rule keeps it** (union of keeps — the same semantics as backup tools): pruned
+ * only when it is outside the `keepLast` most recent AND older than `maxAge`.
+ */
+export interface RetentionRule {
+    /** Keep at most the N most recent items. */
+    keepLast?: number;
+    /** Keep items newer than this age (relative to prune time). */
+    maxAge?: WebhookDuration;
+}
+/** Retention policy for {@link WebhooksCoreOptions.retention}. */
+export interface RetentionOptions {
+    /**
+     * Prune old messages, cascading their deliveries and attempts. Messages with
+     * a non-terminal delivery are never pruned (the dispatcher still needs them).
+     */
+    messages?: RetentionRule;
+    /** Prune old audit entries. */
+    audit?: RetentionRule;
+}
+/** Options for {@link createWebhooksCore}. */
+export interface WebhooksCoreOptions {
+    /** Control-plane store: applications, event types, endpoints, messages, audit. */
+    storage: WebhooksStorage;
+    /**
+     * Store for deliveries, attempts, and the due index. Defaults to `storage`.
+     * Splitting lets control data live in Postgres while the queue lives in Redis.
+     */
+    queueStorage?: WebhooksStorage;
+    /** When true, all mutating operations throw {@link ReadonlyError}. */
+    readonly?: boolean;
+    /**
+     * Control-plane hooks fired around admin mutations. Pass one hook or an array.
+     * `before` hooks run sequentially and may **throw to deny**; `after` hooks run
+     * post-commit for side effects and never fail the operation.
+     */
+    hooks?: WebhooksHooksInput;
+    /** Reporter invoked when an `after` hook throws. Defaults to `console.warn`. */
+    onHookError?: HookErrorReporter;
+    /** Fire-and-forget sink invoked for **every** delivery attempt (metrics tap). */
+    onDelivery?: DeliveryListener;
+    /** Reporter invoked when the `onDelivery` sink throws/rejects. */
+    onDeliveryError?: DeliveryErrorReporter;
+    /**
+     * Retention policy. Message pruning cascades deliveries/attempts and is
+     * non-vetoable; removed payloads are surfaced to `after` hooks
+     * (`message.pruned`, `audit.pruned`) so they can be offloaded first. Pruning
+     * runs opportunistically after publishes (off the hot path, fire-and-forget)
+     * and on demand via {@link WebhooksCore.prune}.
+     */
+    retention?: RetentionOptions;
+    /**
+     * Dispatcher configuration, carried here so panels/CLI construct dispatchers
+     * consistently. The core itself never starts one — creation is the
+     * panel/CLI's job (or yours, via `createDispatcher(core, core.options.dispatcher)`).
+     */
+    dispatcher?: DispatcherOptions;
+    /** Grace window during which a rotated-out secret keeps signing. Default `"24h"`. */
+    secretRotationGrace?: WebhookDuration;
+    /** Allow `http:` endpoint URLs beyond localhost (dev only; default `false`). */
+    allowInsecureUrls?: boolean;
+    /** Extra endpoint-URL gate; return `false` to reject (SSRF denylist etc.). */
+    urlPolicy?: (url: string) => boolean;
+    /** Max serialized payload size accepted by publish. Default `262_144` bytes. */
+    payloadLimitBytes?: number;
+    /**
+     * Whether {@link WebhooksCore.publish} requires the event type to exist in
+     * the catalog. Default `true` — a typo'd event type name would otherwise
+     * silently deliver to nobody (endpoints subscribe by exact name).
+     */
+    requireKnownEventTypes?: boolean;
+    /** Injectable clock (unix millis) for tests. Default `Date.now`. */
+    now?: () => number;
+}
+/** Per-call actor attribution for audited mutations. */
+export interface ActorOptions {
+    actor?: Actor | null;
+}
+/** Input to {@link WebhooksCore.publish}. */
+export interface PublishInput {
+    eventType: string;
+    payload: JsonValue;
+    /** ISO-8601 event-occurred time. Defaults to publish time. */
+    timestamp?: string;
+    /** Dedupe key: same key + same payload within retention returns the existing message. */
+    idempotencyKey?: string;
+}
+/** Result of {@link WebhooksCore.publish}. */
+export interface PublishResult {
+    message: Message;
+    deliveries: Delivery[];
+    /** True when an idempotency key matched and the existing message was returned. */
+    deduplicated: boolean;
+}
+/** Pagination + filters for {@link WebhooksCore.listMessages}. */
+export interface ListMessagesOptions {
+    /** Page size. Default 50, max 200. */
+    limit?: number;
+    /** Cursor: return items strictly older than the message with this id. */
+    before?: string;
+    eventType?: string;
+}
+/** Pagination + filters for {@link WebhooksCore.listDeliveries}. */
+export interface ListDeliveriesOptions {
+    status?: Delivery["status"];
+    endpointId?: string;
+    messageId?: string;
+    /** Page size. Default 50, max 200. */
+    limit?: number;
+    /** Cursor: return items strictly older than the delivery with this id. */
+    before?: string;
+}
+/** Input to the dispatcher-facing {@link WebhooksCore.claimDueDeliveries}. */
+export interface ClaimInput {
+    limit: number;
+    leaseMs: number;
+}
+/** Input to the dispatcher-facing {@link WebhooksCore.recordAttempt}. */
+export interface RecordAttemptInput {
+    delivery: Delivery;
+    outcome: AttemptOutcome;
+    trigger: DeliveryAttempt["trigger"];
+    /**
+     * When the outcome failed: the next attempt time (dispatcher computes the
+     * schedule + jitter), or `null` when the schedule is exhausted (dead-letter).
+     * Ignored for successful outcomes.
+     */
+    nextAttemptAt?: string | null;
+    /** The message's event type (for the sink event); loaded by the dispatcher anyway. */
+    eventType: string;
+}
+/** Result of {@link WebhooksCore.sendExample}. */
+export interface SendExampleResult {
+    outcome: AttemptOutcome;
+    /** The envelope body that was sent. */
+    body: string;
+    /** The synthetic message id used as `webhook-id` (not retained). */
+    messageId: string;
+}
+/** Result of {@link WebhooksCore.recoverEndpoint}. */
+export interface RecoverResult {
+    /** Ids of the failed deliveries that were re-queued. */
+    deliveryIds: string[];
+}
+/** The admin + publish core surface. */
+export interface WebhooksCore {
+    readonly options: {
+        storage: WebhooksStorage;
+        queueStorage: WebhooksStorage;
+        readonly: boolean;
+        /** Normalized hooks (always an array). */
+        hooks: WebhooksHooks[];
+        retention?: RetentionOptions;
+        dispatcher?: DispatcherOptions;
+        secretRotationGrace: WebhookDuration;
+        allowInsecureUrls: boolean;
+        urlPolicy?: (url: string) => boolean;
+        payloadLimitBytes: number;
+        requireKnownEventTypes: boolean;
+        onDelivery?: DeliveryListener;
+        onDeliveryError?: DeliveryErrorReporter;
+        now: () => number;
+    };
+    listApplications(): Promise<Application[]>;
+    createApplication(input: {
+        key: string;
+        name?: string;
+        metadata?: JsonValue;
+    }, options?: ActorOptions): Promise<Application>;
+    getApplication(applicationKey: string): Promise<Application | null>;
+    updateApplication(applicationKey: string, patch: {
+        name?: string;
+        metadata?: JsonValue;
+    }, options?: ActorOptions): Promise<Application>;
+    /** Deletes the application and **everything** under it (endpoints, messages, deliveries). */
+    deleteApplication(applicationKey: string, options?: ActorOptions): Promise<void>;
+    listEventTypes(): Promise<EventType[]>;
+    getEventType(name: string): Promise<EventType | null>;
+    upsertEventType(input: EventType, options?: ActorOptions): Promise<EventType>;
+    /**
+     * Delete an event type. Endpoints referencing it keep their subscription
+     * entry and simply stop matching new publishes of that name.
+     */
+    deleteEventType(name: string, options?: ActorOptions): Promise<void>;
+    listEndpoints(applicationKey: string): Promise<Endpoint[]>;
+    getEndpoint(applicationKey: string, endpointId: string): Promise<Endpoint | null>;
+    /** Creates the endpoint and generates its first signing secret. */
+    createEndpoint(applicationKey: string, input: {
+        url: string;
+        description?: string;
+        eventTypes?: string[];
+        headers?: Record<string, string>;
+        metadata?: JsonValue;
+        disabled?: boolean;
+    }, options?: ActorOptions): Promise<Endpoint>;
+    updateEndpoint(applicationKey: string, endpointId: string, patch: {
+        url?: string;
+        description?: string;
+        eventTypes?: string[];
+        headers?: Record<string, string>;
+        metadata?: JsonValue;
+    }, options?: ActorOptions): Promise<Endpoint>;
+    deleteEndpoint(applicationKey: string, endpointId: string, options?: ActorOptions): Promise<void>;
+    /**
+     * Mint a new current secret; the previous one keeps verifying until
+     * `secretRotationGrace` elapses. Expired grace secrets are pruned lazily.
+     */
+    rotateSecret(applicationKey: string, endpointId: string, options?: ActorOptions): Promise<Endpoint>;
+    /** The endpoint's secrets (current first). Gate behind `endpoint:read-secret`. */
+    getSecrets(applicationKey: string, endpointId: string): Promise<Endpoint["secrets"]>;
+    enableEndpoint(applicationKey: string, endpointId: string, options?: ActorOptions): Promise<Endpoint>;
+    disableEndpoint(applicationKey: string, endpointId: string, options?: ActorOptions): Promise<Endpoint>;
+    /**
+     * Persist a message and fan out one pending delivery per matching enabled
+     * endpoint. Never performs HTTP; never throws because an endpoint is down.
+     */
+    publish(applicationKey: string, input: PublishInput, options?: ActorOptions): Promise<PublishResult>;
+    listMessages(applicationKey: string, options?: ListMessagesOptions): Promise<Message[]>;
+    getMessage(applicationKey: string, messageId: string): Promise<Message | null>;
+    listDeliveries(applicationKey: string, options?: ListDeliveriesOptions): Promise<Delivery[]>;
+    getDelivery(applicationKey: string, deliveryId: string): Promise<{
+        delivery: Delivery;
+        attempts: DeliveryAttempt[];
+    } | null>;
+    /**
+     * The exact signed HTTP request this delivery would send **right now** —
+     * method, URL, all headers (including the computed `webhook-signature`), and
+     * body. The inspector view: shows what a receiver gets, without sending.
+     * Returns `null` if the delivery or its endpoint no longer exists. The
+     * `webhook-timestamp`/signature reflect the current time (they change per
+     * attempt by design); the id and body are stable.
+     */
+    previewDeliveryRequest(applicationKey: string, deliveryId: string): Promise<SignedRequest | null>;
+    /** Re-queue a dead-lettered delivery (`failed` → `pending`, due immediately). */
+    retryDelivery(applicationKey: string, deliveryId: string, options?: ActorOptions): Promise<Delivery>;
+    /** Re-queue every failed delivery for an endpoint created at/after `since`. */
+    recoverEndpoint(applicationKey: string, endpointId: string, input: {
+        since: string;
+    }, options?: ActorOptions): Promise<RecoverResult>;
+    /**
+     * Fire a one-off signed test delivery at an endpoint, synchronously, through
+     * the same wire path as real deliveries (`trigger: "test"`). The synthetic
+     * message is not retained.
+     */
+    sendExample(applicationKey: string, endpointId: string, input: {
+        eventType: string;
+        payload?: JsonValue;
+    }, options?: ActorOptions): Promise<SendExampleResult>;
+    /** Newest-first. With `applicationKey`: that app's log; without: global + all apps. */
+    listAudit(applicationKey?: string): Promise<AuditEntry[]>;
+    /** Run retention now (also runs opportunistically after publishes). */
+    prune(): Promise<void>;
+    /**
+     * Claim up to `limit` due deliveries for exclusive processing. Uses the
+     * storage's native `claimDue` when available; otherwise scans the due index
+     * with compare-and-swap claiming (plain read-modify-write when the storage
+     * has no CAS — single-dispatcher assumption, see docs/DELIVERY.md).
+     */
+    claimDueDeliveries(input: ClaimInput): Promise<Delivery[]>;
+    /** Record one attempt's outcome and advance the delivery's state machine. */
+    recordAttempt(input: RecordAttemptInput): Promise<Delivery>;
+    /**
+     * Update the endpoint's failure streak after an attempt (any success clears
+     * it) and auto-disable once the streak exceeds `failingForDays`. Returns the
+     * endpoint when it was auto-disabled by this call.
+     */
+    noteEndpointOutcome(applicationKey: string, endpointId: string, ok: boolean, policy?: {
+        failingForDays?: number;
+    } | false): Promise<Endpoint | null>;
+}
+/**
+ * Construct the core over the configured storage.
+ *
+ * @example
+ * ```ts
+ * import { createWebhooksCore } from "@xtandard/webhooks";
+ * import { createMemoryStorage } from "@xtandard/webhooks/storage/memory";
+ *
+ * const core = createWebhooksCore({ storage: createMemoryStorage() });
+ *
+ * await core.createApplication({ key: "acme" });
+ * await core.upsertEventType({ name: "invoice.paid" });
+ * const endpoint = await core.createEndpoint("acme", {
+ *   url: "https://api.acme-customer.com/webhooks",
+ *   eventTypes: ["invoice.paid"],
+ * });
+ *
+ * // The hot path — call this from your app code:
+ * await core.publish("acme", {
+ *   eventType: "invoice.paid",
+ *   payload: { invoiceId: "inv_1", amount: 4200 },
+ * });
+ * ```
+ */
+export declare function createWebhooksCore(options: WebhooksCoreOptions): WebhooksCore;

package/dist/types-elysia2/deliver.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The single-attempt HTTP delivery primitive: build the Standard Webhooks
+ * headers, POST the envelope, capture the outcome. Owns no retry/queue logic —
+ * the dispatcher schedules attempts and `core.sendExample` fires one-off test
+ * sends through the same code path so test deliveries are wire-identical to
+ * real ones.
+ *
+ * @module
+ */
+import type { Endpoint } from "./schema.ts";
+/** Default cap on how many response-body characters are kept per attempt. */
+export declare const DEFAULT_RESPONSE_BODY_LIMIT = 4096;
+/** Default per-attempt timeout. */
+export declare const DEFAULT_ATTEMPT_TIMEOUT_MS = 20000;
+/** Input to {@link attemptDelivery}. */
+export interface AttemptDeliveryInput {
+    endpoint: Endpoint;
+    /** The `webhook-id` header — the **message** id (stable across retries). */
+    messageId: string;
+    /** The serialized envelope body, exactly as stored at publish time. */
+    body: string;
+    /** Per-attempt timeout (AbortController). Default 20s. */
+    timeoutMs?: number;
+    /** Cap on stored response-body characters. Default 4096. */
+    responseBodyLimit?: number;
+    /** `user-agent` header value. */
+    userAgent?: string;
+    /** Injectable fetch (tests, instrumentation). Default: global fetch. */
+    fetch?: typeof fetch;
+    /** Unix millis of the attempt; defaults to `Date.now()`. */
+    nowMs?: number;
+}
+/** The observed outcome of one HTTP delivery attempt. */
+export interface AttemptOutcome {
+    ok: boolean;
+    httpStatus?: number;
+    /** Truncated error message on network error/timeout. */
+    error?: string;
+    /** Truncated response body. */
+    responseBody?: string;
+    durationMs: number;
+    /** ISO-8601 timestamp of the attempt. */
+    at: string;
+}
+/** The exact HTTP request a delivery attempt sends — the inspector's view. */
+export interface SignedRequest {
+    method: "POST";
+    url: string;
+    headers: Record<string, string>;
+    body: string;
+}
+/** Input to {@link buildSignedRequest}. */
+export interface BuildSignedRequestInput {
+    endpoint: Endpoint;
+    /** `webhook-id` — the message id (stable across retries). */
+    messageId: string;
+    /** The serialized envelope body. */
+    body: string;
+    /** `user-agent` header value. */
+    userAgent?: string;
+    /** Unix millis; defaults to `Date.now()`. Determines `webhook-timestamp`. */
+    nowMs?: number;
+}
+/**
+ * Build the exact signed request an attempt would POST — Standard Webhooks
+ * headers, all unexpired secrets signing — **without sending it**. Shared by
+ * {@link attemptDelivery} and the panel's request inspector so what you preview
+ * is byte-for-byte what a receiver gets.
+ */
+export declare function buildSignedRequest(input: BuildSignedRequestInput): Promise<SignedRequest>;
+/** The endpoint's currently-signing secrets: the active one + unexpired rotation grace. */
+export declare function activeSecrets(endpoint: Endpoint, nowMs: number): string[];
+/**
+ * Perform one signed POST to `endpoint.url`. Never throws for remote-party
+ * failures — network errors, timeouts, and non-2xx responses all come back as
+ * a failed {@link AttemptOutcome}. (It does throw on programmer error, e.g. an
+ * endpoint with no unexpired secret.)
+ */
+export declare function attemptDelivery(input: AttemptDeliveryInput): Promise<AttemptOutcome>;

package/dist/types-elysia2/delivery-sink.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Delivery sink — a **delivery-plane** observation tap, fired once per attempt.
+ * Deliberately separate from the admin-plane {@link ./hooks/contract.WebhooksHooks}
+ * (`before`/`after` around control-plane mutations):
+ *
+ * - **Different plane.** Admin hooks live around rare, human-driven mutations
+ *   (endpoints, event types, replay). Attempts happen inside the dispatcher,
+ *   potentially thousands per minute.
+ * - **Hot path.** The sink is **fire-and-forget**: invoked *after* the attempt
+ *   is recorded, never awaited, and its errors never propagate into the
+ *   delivery loop.
+ *
+ * It exists to feed metrics/observability pipelines — Prometheus counters,
+ * per-endpoint success dashboards, usage-based stale-endpoint detection —
+ * without a stats engine. The `after` hooks only see **terminal** transitions
+ * (`delivery.succeeded` / `delivery.exhausted`); the sink sees every attempt.
+ *
+ * @module
+ */
+import type { AttemptTrigger } from "./schema.ts";
+/** One recorded delivery attempt, delivered to a {@link DeliveryListener}. */
+export interface DeliveryEvent {
+    applicationKey: string;
+    endpointId: string;
+    messageId: string;
+    deliveryId: string;
+    /** The message's event type name. */
+    eventType: string;
+    /** 1-based attempt ordinal within the delivery. */
+    attemptNumber: number;
+    /** True when the receiver answered 2xx. */
+    ok: boolean;
+    /** True when this attempt drove the delivery to a terminal state. */
+    terminal: boolean;
+    /** HTTP status code; absent on network error/timeout. */
+    httpStatus?: number;
+    /** Wall-clock duration of the HTTP round trip. */
+    durationMs: number;
+    /** What initiated the attempt. */
+    trigger: AttemptTrigger;
+    /** ISO-8601 timestamp of the attempt. */
+    at: string;
+}
+/**
+ * A fire-and-forget observer of delivery attempts. Return value (including a
+ * Promise) is ignored by the caller; throwing / rejecting never affects the
+ * delivery — failures are routed to the configured error reporter.
+ */
+export type DeliveryListener = (event: DeliveryEvent) => void | Promise<void>;
+/** Reports an error thrown/rejected by a {@link DeliveryListener}. */
+export type DeliveryErrorReporter = (error: unknown, event: DeliveryEvent) => void;
+/**
+ * Invoke `listener` safely off the delivery path: synchronous throws are caught
+ * and a returned Promise's rejection is handled, so a broken sink can never
+ * fail (or slow, since it is not awaited) a delivery.
+ */
+export declare function emitDelivery(listener: DeliveryListener, event: DeliveryEvent, onError?: DeliveryErrorReporter): void;

package/dist/types-elysia2/dispatcher.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The delivery engine. Polls the due index, claims deliveries (lease-based,
+ * multi-instance safe when storage supports CAS or the `deliveryQueue`
+ * capability), performs the signed HTTP attempts, and drives each delivery's
+ * state machine through the retry schedule into success or dead-letter.
+ *
+ * Runs in-process: the panel starts one by default, a split worker runs one
+ * via the CLI (`xtandard-webhooks dispatch`), and tests drive {@link Dispatcher.tick}
+ * manually. All timers are `unref()`ed so a dispatcher never keeps a process
+ * alive on its own. Semantics are **at-least-once**: a crashed process loses
+ * nothing (leases expire, the next tick reclaims); receivers dedupe on
+ * `webhook-id`.
+ *
+ * @module
+ */
+import type { WebhooksCore } from "./core.ts";
+import type { WebhookDuration } from "./schema.ts";
+/** Options for {@link createDispatcher} (also accepted on panels and the core). */
+export interface DispatcherOptions {
+    /** How often to poll for due deliveries. Default `1000`. */
+    pollIntervalMs?: number;
+    /** Max deliveries claimed per tick. Default `20`. */
+    batchSize?: number;
+    /** Max in-flight HTTP attempts. Default `8`. */
+    concurrency?: number;
+    /** Per-attempt timeout (AbortController). Default `20_000`. */
+    timeoutMs?: number;
+    /** Claim lease duration; an expired lease makes a claim reclaimable. Default `60_000`. */
+    leaseMs?: number;
+    /**
+     * Delay before attempt N+1 after attempt N fails (index 0 = the initial
+     * attempt's delay). Exhausting the schedule dead-letters the delivery.
+     * Default `["0s", "5s", "5m", "30m", "2h", "5h", "10h"]` (Svix-compatible).
+     */
+    retrySchedule?: WebhookDuration[];
+    /**
+     * Auto-disable endpoints whose every attempt has failed for this many
+     * consecutive days. `false` disables the policy. Default `{ failingForDays: 5 }`.
+     */
+    autoDisable?: {
+        failingForDays?: number;
+    } | false;
+    /** Cap on stored response-body characters per attempt. Default `4096`. */
+    responseBodyLimit?: number;
+    /** Injectable fetch (tests, instrumentation). Default: global fetch. */
+    fetch?: typeof fetch;
+    /** `user-agent` header. Default `"xtandard-webhooks/<version>"`. */
+    userAgent?: string;
+}
+/** The delivery engine handle. */
+export interface Dispatcher {
+    /** Begin polling. Idempotent. */
+    start(): void;
+    /** Stop polling and wait for in-flight attempts to finish. */
+    stop(): Promise<void>;
+    /**
+     * Run one manual pass: claim due deliveries, attempt them, record outcomes.
+     * Returns the number of attempts made — the unit-test surface (tests never
+     * assert on timers).
+     */
+    tick(): Promise<number>;
+    readonly running: boolean;
+}
+/** The default retry schedule (Svix-compatible). */
+export declare const DEFAULT_RETRY_SCHEDULE: WebhookDuration[];
+/**
+ * Create a dispatcher over a core. Not started — call
+ * {@link Dispatcher.start}, or drive {@link Dispatcher.tick} manually.
+ *
+ * @example
+ * ```ts
+ * import { createWebhooksCore, createDispatcher } from "@xtandard/webhooks";
+ * import { createMemoryStorage } from "@xtandard/webhooks/storage/memory";
+ *
+ * const core = createWebhooksCore({ storage: createMemoryStorage() });
+ * const dispatcher = createDispatcher(core);
+ * dispatcher.start();
+ * ```
+ */
+export declare function createDispatcher(core: WebhooksCore, options?: DispatcherOptions): Dispatcher;