@xtandard/webhooks 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,368 @@
+import { _ as WebhookEnvelope, a as AuditEntry, c as DeliveryStatus, d as EndpointSecret, f as EventType, g as WebhookDuration, h as SCHEMA_VERSION, i as AuditAction, l as Endpoint, m as Message, n as Application, o as Delivery, p as JsonValue, r as AttemptTrigger, s as DeliveryAttempt, t as Actor, u as EndpointDisabledReason, v as isTerminalDeliveryStatus } from "./schema-mo__wv4P.cjs";
+import { A as BuildSignedRequestInput, C as createDispatcher, D as emitDelivery, E as DeliveryListener, F as attemptDelivery, I as buildSignedRequest, M as DEFAULT_RESPONSE_BODY_LIMIT, N as SignedRequest, O as AttemptDeliveryInput, P as activeSecrets, S as DispatcherOptions, T as DeliveryEvent, _ as WebhooksCore, a as ListDeliveriesOptions, b as DEFAULT_RETRY_SCHEDULE, c as PayloadTooLargeError, d as ReadonlyError, f as RecordAttemptInput, g as SendExampleResult, h as RetentionRule, i as IdempotencyConflictError, j as DEFAULT_ATTEMPT_TIMEOUT_MS, k as AttemptOutcome, l as PublishInput, m as RetentionOptions, n as ClaimInput, o as ListMessagesOptions, p as RecoverResult, r as ConflictError, s as NotFoundError, t as ActorOptions, u as PublishResult, v as WebhooksCoreOptions, w as DeliveryErrorReporter, x as Dispatcher, y as createWebhooksCore } from "./core-KJawHjFF.cjs";
+import { a as WatchableWebhooksStorage, c as isCompareAndSwap, d as requirePeer, i as TransactionalWebhooksStorage, l as isTransactional, n as DeliveryQueueStorage, o as WebhooksStorage, r as StorageChangeEvent, s as hasDeliveryQueue, t as CompareAndSwapWebhooksStorage, u as isWatchable } from "./contract-8h-Azxa5.cjs";
+import { a as HookDeniedError, c as WebhooksHooksInput, d as runAfter, f as runBefore, i as BeforeEventType, l as defaultHookErrorReporter, n as AfterEventType, o as HookErrorReporter, r as BeforeEvent, s as WebhooksHooks, t as AfterEvent, u as normalizeHooks } from "./contract-Bnb3fgRJ.cjs";
+import { n as Principal, t as AuthProvider } from "./contract-lETlIuXo.cjs";
+import { a as WebhooksResource, i as WebhooksAction, n as AuthorizeInput, o as isMutatingAction, r as MUTATING_ACTIONS, t as AuthorizationProvider } from "./contract-CiPskNvS.cjs";
+import { a as WebhooksPortalOptions, i as DEFAULT_PORTAL_ACTIONS, n as WebhooksPanelOptions, o as WebhooksCorsOptions, r as createFetchHandler, t as CreateFetchHandlerResult } from "./create-fetch-handler-Dlkhustu.cjs";
+import { SECRET_PREFIX, VerifyInput, WebhookVerificationError, generateSecret, sign, signatureHeader, verify } from "./signing.cjs";
+
+//#region \0rolldown/runtime.js
+//#endregion
+//#region src/version.d.ts
+/**
+ * Package version, used for the default dispatcher `user-agent`. Bumped by the
+ * release flow alongside `package.json`.
+ *
+ * @module
+ */
+/** The published package version. */
+declare const VERSION = "0.1.0";
+declare namespace keys_d_exports {
+  export { DueEntry, RESERVED_APPLICATION_KEYS, ROOT, applicationMetaKey, applicationPrefix, applicationsKey, attemptKey, attemptsPrefix, auditLogKey, byEndpointKey, byEndpointPrefix, byMessageKey, byMessagePrefix, deliveriesPrefix, deliveryKey, dueKey, duePrefix, endpointKey, endpointsKey, eventTypeKey, eventTypesKey, globalAuditLogKey, idempotencyKey, lastSegment, messageKey, messagesPrefix, parseDueKey };
+}
+/**
+ * Storage key layout for `@xtandard/webhooks`.
+ *
+ * Keys are namespaced by application so a single storage backend can host the
+ * whole control plane. Pure string helpers — no dependencies.
+ *
+ * ```txt
+ * whk/applications                                 -> string[] index
+ * whk/{app}/metadata                               -> Application
+ * whk/event-types                                  -> string[] index (global)
+ * whk/event-types/{name}                           -> EventType
+ * whk/{app}/endpoints                              -> string[] index
+ * whk/{app}/endpoints/{id}                         -> Endpoint
+ * whk/{app}/messages/{id}                          -> Message
+ * whk/{app}/idempotency/{key}                      -> message id
+ * whk/{app}/deliveries/{id}                        -> Delivery
+ * whk/{app}/attempts/{deliveryId}/{n}              -> DeliveryAttempt (n zero-padded)
+ * whk/{app}/due/{dueAtMillis}~{deliveryId}         -> DueEntry (13-digit zero-padded millis)
+ * whk/{app}/by-message/{messageId}/{deliveryId}    -> 1 (reverse index)
+ * whk/{app}/by-endpoint/{endpointId}/{deliveryId}  -> 1 (reverse index)
+ * whk/{app}/audit-log                              -> AuditEntry[] (single ordered array)
+ * ```
+ *
+ * The due index is the dispatcher's generic work queue: 13-digit zero-padded
+ * milliseconds make lexicographic key order chronological, so a sorted
+ * `getKeys(duePrefix(app))` scan yields deliveries in due order.
+ *
+ * @module
+ */
+/** Root namespace segment for all keys. */
+declare const ROOT = "whk";
+/**
+ * Application keys that would collide with global index keys under the shared
+ * root. Rejected by validation.
+ */
+declare const RESERVED_APPLICATION_KEYS: readonly ["applications", "event-types", "audit-log"];
+/** Global audit log (event-type actions, which are not application-scoped). */
+declare const globalAuditLogKey: () => string;
+/** Index key listing all known application keys. */
+declare const applicationsKey: () => string;
+/** Metadata for a single application. */
+declare const applicationMetaKey: (applicationKey: string) => string;
+/** Index key listing all event type names (global catalog). */
+declare const eventTypesKey: () => string;
+/** A single event type record. */
+declare const eventTypeKey: (name: string) => string;
+/** Index key listing an application's endpoint ids. */
+declare const endpointsKey: (applicationKey: string) => string;
+/** A single endpoint record. */
+declare const endpointKey: (applicationKey: string, endpointId: string) => string;
+/** Prefix under which an application's messages live. */
+declare const messagesPrefix: (applicationKey: string) => string;
+/** A single message record. */
+declare const messageKey: (applicationKey: string, messageId: string) => string;
+/** Maps a caller-supplied idempotency key to the message id it produced. */
+declare const idempotencyKey: (applicationKey: string, key: string) => string;
+/** Prefix under which an application's deliveries live. */
+declare const deliveriesPrefix: (applicationKey: string) => string;
+/** A single delivery record. */
+declare const deliveryKey: (applicationKey: string, deliveryId: string) => string;
+/** Prefix under which one delivery's attempts live. */
+declare const attemptsPrefix: (applicationKey: string, deliveryId: string) => string;
+/**
+ * A single attempt record. The attempt number is zero-padded to four digits so
+ * lexicographic key order equals attempt order.
+ */
+declare const attemptKey: (applicationKey: string, deliveryId: string, attemptNumber: number) => string;
+/** Prefix of an application's due index (the dispatcher's work queue). */
+declare const duePrefix: (applicationKey: string) => string;
+/** Value stored at a due-index key. */
+interface DueEntry {
+  app: string;
+  deliveryId: string;
+}
+/**
+ * A due-index entry: 13-digit zero-padded epoch milliseconds, then the delivery
+ * id, `~`-separated. Sorting keys lexicographically sorts entries chronologically.
+ */
+declare const dueKey: (applicationKey: string, dueAtMillis: number, deliveryId: string) => string;
+/** Parse a due-index key back into its due-time and delivery id. */
+declare const parseDueKey: (key: string) => {
+  dueAtMillis: number;
+  deliveryId: string;
+} | null;
+/** Prefix of the message → deliveries reverse index. */
+declare const byMessagePrefix: (applicationKey: string, messageId: string) => string;
+/** One entry in the message → deliveries reverse index. */
+declare const byMessageKey: (applicationKey: string, messageId: string, deliveryId: string) => string;
+/** Prefix of the endpoint → deliveries reverse index. */
+declare const byEndpointPrefix: (applicationKey: string, endpointId: string) => string;
+/** One entry in the endpoint → deliveries reverse index. */
+declare const byEndpointKey: (applicationKey: string, endpointId: string, deliveryId: string) => string;
+/** Append-only audit log for an application, stored as an ordered `AuditEntry[]`. */
+declare const auditLogKey: (applicationKey: string) => string;
+/** Prefix under which everything belonging to one application lives. */
+declare const applicationPrefix: (applicationKey: string) => string;
+/** Extract the trailing segment (endpoint id / message id / …) from a key. */
+declare const lastSegment: (key: string) => string;
+//#endregion
+//#region src/id.d.ts
+/**
+ * Entity id generation: `{prefix}_{22-char base62}`. Zero dependencies — base62
+ * over `crypto.getRandomValues`, no ULID. 22 base62 characters encode ~131 bits;
+ * ids are generated from 16 random bytes (128 bits) and left-padded to a fixed
+ * length so ids are uniform and lexicographically well-behaved.
+ *
+ * @module
+ */
+/** Prefixes for the four generated entity id kinds. */
+type IdPrefix = "msg" | "ep" | "dlv" | "atp";
+/**
+ * Generate a new entity id, e.g. `newId("msg")` → `"msg_0uK9…"` (22-char base62
+ * suffix).
+ *
+ * @example
+ * ```ts
+ * import { newId } from "@xtandard/webhooks";
+ *
+ * const id = newId("ep"); // "ep_…"
+ * ```
+ */
+declare function newId(prefix: IdPrefix): string;
+/** Regex an id of the given prefix must match. */
+declare function idPattern(prefix: IdPrefix): RegExp;
+//#endregion
+//#region src/duration.d.ts
+/**
+ * Convert a {@link WebhookDuration} (`5000`, `"5s"`, `"30m"`, `"2h"`, `"5d"`)
+ * to milliseconds. Throws on malformed strings or negative numbers.
+ *
+ * @example
+ * ```ts
+ * import { durationToMs } from "@xtandard/webhooks";
+ *
+ * durationToMs("5m"); // 300000
+ * durationToMs(250); // 250
+ * ```
+ */
+declare function durationToMs(duration: WebhookDuration): number;
+/**
+ * Parse a comma-separated duration list (the `RETRY_SCHEDULE` env var format,
+ * e.g. `"0s,5s,5m,30m,2h,5h,10h"`) into a {@link WebhookDuration} array.
+ */
+declare function parseDurationList(input: string): WebhookDuration[];
+//#endregion
+//#region src/storage/watch.d.ts
+/**
+ * A change source. Called with a `notify` callback — wire your source to invoke
+ * it (optionally with the changed key) on every change — and return an
+ * unsubscribe function (sync or async).
+ */
+type WatchSubscribe = (notify: (key?: string) => void) => (() => void | Promise<void>) | Promise<() => void | Promise<void>>;
+/**
+ * Wrap a storage so it implements {@link WatchableWebhooksStorage} using
+ * `subscribe` as the change source. The wrapper delegates all reads/writes to
+ * `storage` and only adds `watch`; keys not under the watched `prefix` are
+ * filtered out. A notification without a key is delivered as a change to the
+ * prefix itself (enough to trigger a refresh).
+ */
+declare function withWatch<S extends WebhooksStorage>(storage: S, subscribe: WatchSubscribe): S & WatchableWebhooksStorage;
+/**
+ * A dedicated notification client for {@link pgListenNotify} — satisfied by a
+ * `pg` `Client`. `Pool` won't do (it rotates connections); use a `Client` you
+ * `connect()`.
+ */
+interface PgNotificationClient {
+  query(sql: string): Promise<unknown>;
+  on(event: "notification", listener: (msg: {
+    channel: string;
+    payload?: string;
+  }) => void): void;
+  removeListener(event: "notification", listener: (msg: {
+    channel: string;
+    payload?: string;
+  }) => void): void;
+}
+/**
+ * A {@link WatchSubscribe} backed by Postgres `LISTEN`/`NOTIFY`. Pair with
+ * {@link withWatch} for the postgres or drizzle-over-pg adapters. Your migration
+ * owns the trigger that `pg_notify`s `channel` with the changed key as payload;
+ * this only `LISTEN`s.
+ *
+ * @example
+ * ```ts
+ * import { Client } from "pg";
+ * const listener = new Client({ connectionString: process.env.DATABASE_URL });
+ * await listener.connect();
+ * const storage = withWatch(base, pgListenNotify(listener, "xtandard_webhooks"));
+ * ```
+ */
+declare function pgListenNotify(client: PgNotificationClient, channel?: string): WatchSubscribe;
+//#endregion
+//#region src/validation.d.ts
+/**
+ * Runtime validation for control-plane inputs, built on `valibot`.
+ *
+ * This is the **admin path** only — `publish()` performs its own minimal
+ * checks and the wire/receiver path never imports this module, so `valibot`
+ * stays off the hot paths. Validation combines structural parsing (valibot)
+ * with semantic checks (URL policy, reserved header names, reserved keys).
+ *
+ * @module
+ */
+/** Allowed characters for application keys and event type names. */
+declare const KEY_REGEX: RegExp;
+/**
+ * Header names owned by the Standard Webhooks wire contract. Endpoints may not
+ * override them via static headers.
+ */
+declare const RESERVED_HEADERS: readonly ["webhook-id", "webhook-timestamp", "webhook-signature"];
+/** A single validation problem with a dotted path into the offending data. */
+interface ValidationIssue {
+  path: string;
+  message: string;
+}
+/** Result of the `validate*` functions. */
+interface ValidationResult {
+  valid: boolean;
+  errors: ValidationIssue[];
+}
+/** Raised by {@link assertValid} when an input fails validation. Maps to HTTP 422. */
+declare class ValidationError extends Error {
+  readonly errors: ValidationIssue[];
+  constructor(errors: ValidationIssue[]);
+}
+/** Throw a {@link ValidationError} when `result` is invalid. */
+declare function assertValid(result: ValidationResult): void;
+/**
+ * Validate an {@link Application}: structure + reserved-key check.
+ *
+ * @example
+ * ```ts
+ * import { validateApplication } from "@xtandard/webhooks";
+ *
+ * const result = validateApplication({ key: "acme" });
+ * // result.valid === true
+ * ```
+ */
+declare function validateApplication(input: unknown, basePath?: string): ValidationResult;
+/** Validate an {@link EventType}: structural only (the name regex carries the semantics). */
+declare function validateEventType(input: unknown, basePath?: string): ValidationResult;
+/** Options that relax/extend the endpoint URL policy. */
+interface UrlPolicyOptions {
+  /** Allow `http:` for non-localhost hosts (dev only; default `false`). */
+  allowInsecureUrls?: boolean;
+  /** Extra host-supplied gate; return `false` to reject (e.g. an SSRF denylist). */
+  urlPolicy?: (url: string) => boolean;
+}
+/**
+ * Validate an endpoint destination URL: parseable, `https:` (or `http:` for
+ * localhost, or anywhere when `allowInsecureUrls`), no embedded credentials,
+ * and passing the host's optional `urlPolicy` gate.
+ */
+declare function validateEndpointUrl(url: string, options?: UrlPolicyOptions, basePath?: string): ValidationResult;
+/**
+ * Validate an {@link Endpoint} input: structure, URL policy, and static-header
+ * restrictions (the Standard Webhooks headers are reserved).
+ *
+ * @example
+ * ```ts
+ * import { validateEndpoint } from "@xtandard/webhooks";
+ *
+ * const result = validateEndpoint({ url: "https://api.example.com/hooks" });
+ * // result.valid === true
+ * ```
+ */
+declare function validateEndpoint(input: unknown, options?: UrlPolicyOptions, basePath?: string): ValidationResult;
+//#endregion
+//#region src/portal.d.ts
+/** Prefix of every portal token. */
+declare const PORTAL_TOKEN_PREFIX = "whpt_";
+/**
+ * Thrown by {@link verifyPortalToken} for any invalid token — malformed,
+ * bad signature, or expired. Maps to HTTP 401 at the API layer.
+ */
+declare class PortalTokenError extends Error {
+  constructor(message: string);
+}
+/** Options for {@link createPortalToken}. */
+interface PortalTokenOptions {
+  /** Token lifetime. Default `"7d"`. */
+  expiresIn?: WebhookDuration;
+}
+/**
+ * Mint a portal token granting access to `applicationKey` until `expiresIn`
+ * elapses (default 7 days). Call this **server-side** — anyone holding the
+ * portal secret can mint tokens for any application.
+ *
+ * @example
+ * ```ts
+ * import { createPortalToken } from "@xtandard/webhooks";
+ *
+ * // In the host app's session-guarded route:
+ * const token = await createPortalToken(process.env.PORTAL_SECRET!, "acme", {
+ *   expiresIn: "1h",
+ * });
+ * // Hand `token` to the frontend for <WebhooksPortal token={token} />.
+ * ```
+ */
+declare function createPortalToken(secret: string, applicationKey: string, options?: PortalTokenOptions): Promise<string>;
+/**
+ * Verify a portal token: format, signature (constant time), then expiry.
+ * Returns the granted application key on success; throws
+ * {@link PortalTokenError} otherwise.
+ *
+ * @example
+ * ```ts
+ * import { verifyPortalToken } from "@xtandard/webhooks";
+ *
+ * const { applicationKey } = await verifyPortalToken(secret, token);
+ * ```
+ */
+declare function verifyPortalToken(secret: string, token: string): Promise<{
+  applicationKey: string;
+}>;
+//#endregion
+//#region src/server/openapi.d.ts
+/**
+ * OpenAPI 3.1 description of the admin JSON API.
+ *
+ * Exposed two ways, mirroring the flags panel:
+ *  - served at `GET {basePath}/api/openapi.json` for standalone tools (Scalar,
+ *    Swagger UI, Postman, codegen);
+ *  - returned by `createFetchHandler(...).openapi()` so you can MERGE it into
+ *    your host app's OpenAPI document (e.g. Elysia `@elysiajs/openapi`
+ *    `references`, or Hono's OpenAPI).
+ *
+ * Hand-authored — no generation dependency (flags precedent).
+ *
+ * @module
+ */
+/** Options for {@link buildOpenApiDocument}. */
+interface OpenApiOptions {
+  /** Mount prefix used in the `servers` url (e.g. `"/webhooks"`). */
+  basePath?: string;
+  /** Document title. */
+  title?: string;
+  /** Document version (defaults to the package's API version). */
+  version?: string;
+}
+/** Build the OpenAPI 3.1 document for the admin API. Pure — safe to call anywhere. */
+declare function buildOpenApiDocument(options?: OpenApiOptions): Record<string, unknown>;
+//#endregion
+export { Actor, ActorOptions, type AfterEvent, type AfterEventType, Application, type AttemptDeliveryInput, type AttemptOutcome, AttemptTrigger, AuditAction, AuditEntry, type AuthProvider, type AuthorizationProvider, type AuthorizeInput, type BeforeEvent, type BeforeEventType, type BuildSignedRequestInput, ClaimInput, type CompareAndSwapWebhooksStorage, ConflictError, type CreateFetchHandlerResult, DEFAULT_ATTEMPT_TIMEOUT_MS, DEFAULT_PORTAL_ACTIONS, DEFAULT_RESPONSE_BODY_LIMIT, DEFAULT_RETRY_SCHEDULE, Delivery, DeliveryAttempt, type DeliveryErrorReporter, type DeliveryEvent, type DeliveryListener, type DeliveryQueueStorage, DeliveryStatus, type Dispatcher, type DispatcherOptions, Endpoint, EndpointDisabledReason, EndpointSecret, EventType, HookDeniedError, type HookErrorReporter, type IdPrefix, IdempotencyConflictError, JsonValue, KEY_REGEX, ListDeliveriesOptions, ListMessagesOptions, MUTATING_ACTIONS, Message, NotFoundError, type OpenApiOptions, PORTAL_TOKEN_PREFIX, PayloadTooLargeError, type PgNotificationClient, PortalTokenError, type PortalTokenOptions, type Principal, PublishInput, PublishResult, RESERVED_HEADERS, ReadonlyError, RecordAttemptInput, RecoverResult, RetentionOptions, RetentionRule, SCHEMA_VERSION, SECRET_PREFIX, SendExampleResult, type SignedRequest, type StorageChangeEvent, type TransactionalWebhooksStorage, type UrlPolicyOptions, VERSION, ValidationError, type ValidationIssue, type ValidationResult, type VerifyInput, type WatchSubscribe, type WatchableWebhooksStorage, WebhookDuration, WebhookEnvelope, WebhookVerificationError, type WebhooksAction, WebhooksCore, WebhooksCoreOptions, type WebhooksCorsOptions, type WebhooksHooks, type WebhooksHooksInput, type WebhooksPanelOptions, type WebhooksPortalOptions, type WebhooksResource, type WebhooksStorage, activeSecrets, assertValid, attemptDelivery, buildOpenApiDocument, buildSignedRequest, createDispatcher, createFetchHandler, createPortalToken, createWebhooksCore, defaultHookErrorReporter, durationToMs, emitDelivery, generateSecret, hasDeliveryQueue, idPattern, isCompareAndSwap, isMutatingAction, isTerminalDeliveryStatus, isTransactional, isWatchable, keys_d_exports as keys, newId, normalizeHooks, parseDurationList, pgListenNotify, requirePeer, runAfter, runBefore, sign, signatureHeader, validateApplication, validateEndpoint, validateEndpointUrl, validateEventType, verify, verifyPortalToken, withWatch };
+//# sourceMappingURL=index.d.cts.map