@xtandard/webhooks 0.1.0

package/dist/core-DT4ppWh8.d.mts

@@ -0,0 +1,502 @@
+import { a as AuditEntry, f as EventType, g as WebhookDuration, l as Endpoint, m as Message, n as Application, o as Delivery, p as JsonValue, r as AttemptTrigger, s as DeliveryAttempt, t as Actor } from "./schema-mo__wv4P.mjs";
+import { o as WebhooksStorage } from "./contract-DhQ4JjGG.mjs";
+import { c as WebhooksHooksInput, o as HookErrorReporter, s as WebhooksHooks } from "./contract-T1kcZNdG.mjs";
+
+//#region src/deliver.d.ts
+/** Default cap on how many response-body characters are kept per attempt. */
+declare const DEFAULT_RESPONSE_BODY_LIMIT = 4096;
+/** Default per-attempt timeout. */
+declare const DEFAULT_ATTEMPT_TIMEOUT_MS = 20000;
+/** Input to {@link attemptDelivery}. */
+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. */
+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. */
+interface SignedRequest {
+  method: "POST";
+  url: string;
+  headers: Record<string, string>;
+  body: string;
+}
+/** Input to {@link buildSignedRequest}. */
+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.
+ */
+declare function buildSignedRequest(input: BuildSignedRequestInput): Promise<SignedRequest>;
+/** The endpoint's currently-signing secrets: the active one + unexpired rotation grace. */
+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.)
+ */
+declare function attemptDelivery(input: AttemptDeliveryInput): Promise<AttemptOutcome>;
+//#endregion
+//#region src/delivery-sink.d.ts
+/** One recorded delivery attempt, delivered to a {@link DeliveryListener}. */
+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.
+ */
+type DeliveryListener = (event: DeliveryEvent) => void | Promise<void>;
+/** Reports an error thrown/rejected by a {@link DeliveryListener}. */
+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.
+ */
+declare function emitDelivery(listener: DeliveryListener, event: DeliveryEvent, onError?: DeliveryErrorReporter): void;
+//#endregion
+//#region src/dispatcher.d.ts
+/** Options for {@link createDispatcher} (also accepted on panels and the core). */
+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. */
+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). */
+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();
+ * ```
+ */
+declare function createDispatcher(core: WebhooksCore, options?: DispatcherOptions): Dispatcher;
+//#endregion
+//#region src/core.d.ts
+/** Thrown by mutating operations when the core is in readonly mode. */
+declare class ReadonlyError extends Error {
+  constructor(operation: string);
+}
+/** Thrown when a referenced application/event type/endpoint/delivery does not exist. */
+declare class NotFoundError extends Error {
+  constructor(message: string);
+}
+/** Thrown when creating an entity whose key already exists. Maps to HTTP 409. */
+declare class ConflictError extends Error {
+  constructor(message: string);
+}
+/** Thrown by {@link WebhooksCore.publish} when the payload exceeds the limit. Maps to 413. */
+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.
+ */
+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`.
+ */
+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}. */
+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}. */
+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. */
+interface ActorOptions {
+  actor?: Actor | null;
+}
+/** Input to {@link WebhooksCore.publish}. */
+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}. */
+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}. */
+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}. */
+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}. */
+interface ClaimInput {
+  limit: number;
+  leaseMs: number;
+}
+/** Input to the dispatcher-facing {@link WebhooksCore.recordAttempt}. */
+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}. */
+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}. */
+interface RecoverResult {
+  /** Ids of the failed deliveries that were re-queued. */
+  deliveryIds: string[];
+}
+/** The admin + publish core surface. */
+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 },
+ * });
+ * ```
+ */
+declare function createWebhooksCore(options: WebhooksCoreOptions): WebhooksCore;
+//#endregion
+export { BuildSignedRequestInput as A, createDispatcher as C, emitDelivery as D, DeliveryListener as E, attemptDelivery as F, buildSignedRequest as I, DEFAULT_RESPONSE_BODY_LIMIT as M, SignedRequest as N, AttemptDeliveryInput as O, activeSecrets as P, DispatcherOptions as S, DeliveryEvent as T, WebhooksCore as _, ListDeliveriesOptions as a, DEFAULT_RETRY_SCHEDULE as b, PayloadTooLargeError as c, ReadonlyError as d, RecordAttemptInput as f, SendExampleResult as g, RetentionRule as h, IdempotencyConflictError as i, DEFAULT_ATTEMPT_TIMEOUT_MS as j, AttemptOutcome as k, PublishInput as l, RetentionOptions as m, ClaimInput as n, ListMessagesOptions as o, RecoverResult as p, ConflictError as r, NotFoundError as s, ActorOptions as t, PublishResult as u, WebhooksCoreOptions as v, DeliveryErrorReporter as w, Dispatcher as x, createWebhooksCore as y };
+//# sourceMappingURL=core-DT4ppWh8.d.mts.map