@xtandard/webhooks 0.1.1 → 0.1.3

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

@@ -0,0 +1,26 @@
+/**
+ * Duration parsing for {@link ./schema.WebhookDuration} config values. Zero
+ * dependencies; shared by the core (rotation grace, retention) and the
+ * dispatcher (retry schedule).
+ *
+ * @module
+ */
+import type { WebhookDuration } from "./schema.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
+ * ```
+ */
+export 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.
+ */
+export declare function parseDurationList(input: string): WebhookDuration[];

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

@@ -0,0 +1,8 @@
+/**
+ * Subpath entry for `@xtandard/webhooks/elysia2`. Re-exports the Elysia 2 adapter
+ * (plain panel + typed Eden plugin) so the bundler can map it to its own dist
+ * file.
+ *
+ * @module
+ */
+export * from "./adapters/elysia2.ts";

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

@@ -0,0 +1,203 @@
+/**
+ * Hook contracts — control-plane extensibility around admin mutations.
+ *
+ * A hook is plain JavaScript wired in at {@link ../core.createWebhooksCore}
+ * time (never authored through the UI — that would be remote code execution).
+ * Two phases, deliberately asymmetric:
+ *
+ * - **`before`** runs *before* a mutation commits. Throwing **denies** the
+ *   operation (the thrown error's message is the reason). Multiple `before`
+ *   hooks run **sequentially in declared order**; the first throw aborts and
+ *   nothing commits. This is the enforcement primitive that governance,
+ *   quotas, and publish gates build on.
+ * - **`after`** runs *after* a mutation commits. It is for side effects
+ *   (notifications, cache purges, offloading pruned payloads). An `after`
+ *   hook **must never fail the operation** — the mutation already committed —
+ *   so errors are isolated and reported via `onHookError`, not rethrown.
+ *
+ * Delivery *attempts* are deliberately not hook events (they are data-plane
+ * traffic and can be very hot); the per-attempt tap is the separate
+ * fire-and-forget {@link ../delivery-sink.DeliveryListener}. Only the terminal
+ * transitions (`delivery.succeeded`, `delivery.exhausted`) surface here.
+ *
+ * @module
+ */
+import type { Actor, Application, AuditEntry, Delivery, DeliveryAttempt, Endpoint, EventType, JsonValue, Message } from "../schema.ts";
+/**
+ * Event delivered to {@link WebhooksHooks.before} — the *proposed* mutation,
+ * before it commits. Throw from the handler to deny it.
+ */
+export type BeforeEvent = {
+    type: "application.create" | "application.update";
+    application: Application;
+    actor: Actor | null;
+} | {
+    type: "application.delete";
+    applicationKey: string;
+    actor: Actor | null;
+} | {
+    type: "event-type.upsert";
+    eventType: EventType;
+    actor: Actor | null;
+} | {
+    type: "event-type.delete";
+    name: string;
+    actor: Actor | null;
+} | {
+    type: "endpoint.create" | "endpoint.update";
+    applicationKey: string;
+    endpoint: Endpoint;
+    actor: Actor | null;
+} | {
+    type: "endpoint.delete" | "endpoint.rotate-secret" | "endpoint.disable" | "endpoint.enable";
+    applicationKey: string;
+    endpointId: string;
+    actor: Actor | null;
+} | {
+    /** The host's approval/quota gate for the publish hot path. */
+    type: "message.publish";
+    applicationKey: string;
+    eventType: string;
+    payload: JsonValue;
+    idempotencyKey?: string;
+    actor: Actor | null;
+} | {
+    type: "delivery.retry";
+    applicationKey: string;
+    deliveryId: string;
+    actor: Actor | null;
+} | {
+    type: "endpoint.recover";
+    applicationKey: string;
+    endpointId: string;
+    since: string;
+    actor: Actor | null;
+};
+/**
+ * Event delivered to {@link WebhooksHooks.after} — the *committed* mutation.
+ * Carries the resulting state in full: for destructive events this is the last
+ * chance to offload the payload before it is gone from storage.
+ */
+export type AfterEvent = {
+    type: "application.created" | "application.updated";
+    application: Application;
+    at: string;
+} | {
+    /** Carries the deleted application — everything under it is already gone. */
+    type: "application.deleted";
+    applicationKey: string;
+    application: Application;
+    at: string;
+} | {
+    type: "event-type.upserted";
+    eventType: EventType;
+    at: string;
+} | {
+    type: "event-type.deleted";
+    name: string;
+    eventType: EventType;
+    at: string;
+} | {
+    type: "endpoint.created" | "endpoint.updated" | "endpoint.deleted" | "endpoint.secret-rotated" | "endpoint.disabled" | "endpoint.enabled"
+    /** Disabled by the failure policy, not an operator (see dispatcher `autoDisable`). */
+     | "endpoint.auto-disabled";
+    applicationKey: string;
+    endpoint: Endpoint;
+    at: string;
+} | {
+    type: "message.published";
+    applicationKey: string;
+    message: Message;
+    deliveryIds: string[];
+    at: string;
+} | {
+    type: "delivery.succeeded";
+    applicationKey: string;
+    delivery: Delivery;
+    attempt: DeliveryAttempt;
+    at: string;
+} | {
+    /** Dead-letter offload point: the retry schedule is exhausted. */
+    type: "delivery.exhausted";
+    applicationKey: string;
+    delivery: Delivery;
+    attempts: DeliveryAttempt[];
+    at: string;
+} | {
+    /** Messages removed by retention. Carries the **full messages** — offload now or lose them. */
+    type: "message.pruned";
+    applicationKey: string;
+    messages: Message[];
+    at: string;
+} | {
+    /** Audit entries removed by retention (oldest-first). */
+    type: "audit.pruned";
+    applicationKey?: string;
+    entries: AuditEntry[];
+    at: string;
+};
+/** The discriminant strings of {@link BeforeEvent} / {@link AfterEvent}. */
+export type BeforeEventType = BeforeEvent["type"];
+export type AfterEventType = AfterEvent["type"];
+/**
+ * Thrown from a {@link WebhooksHooks.before} handler to **deny** a mutation with
+ * a clean HTTP status (default `403`). Any thrown error denies the mutation,
+ * but a plain `Error` maps to `500` at the API layer (treated as an unexpected
+ * bug); throw this to signal a deliberate policy rejection (`403`, or a custom
+ * `status` such as `409`/`422`).
+ *
+ * @example
+ * ```ts
+ * before(event) {
+ *   if (event.type === "message.publish" && overQuota(event.applicationKey)) {
+ *     throw new HookDeniedError("Monthly webhook quota exceeded.", { status: 429 });
+ *   }
+ * }
+ * ```
+ */
+export declare class HookDeniedError extends Error {
+    /** HTTP status the API layer should respond with. Default `403`. */
+    readonly status: number;
+    constructor(message: string, options?: {
+        status?: number;
+        cause?: unknown;
+    });
+}
+/**
+ * A control-plane hook. Implement `before`, `after`, or both. Pass one — or an
+ * array — to {@link ../core.createWebhooksCore} via `hooks`.
+ */
+export interface WebhooksHooks {
+    /**
+     * Runs before a mutation commits. **Throw to deny** (the error propagates to
+     * the caller; its message is the reason). Return/resolve to allow. Must not
+     * mutate the event payload.
+     */
+    before?(event: BeforeEvent): void | Promise<void>;
+    /**
+     * Runs after a mutation commits. For side effects only. Errors are isolated
+     * and reported via `onHookError` — they never fail the (already committed)
+     * operation.
+     */
+    after?(event: AfterEvent): void | Promise<void>;
+}
+/** Accepts a single hook, an array, or nothing. */
+export type WebhooksHooksInput = WebhooksHooks | readonly WebhooksHooks[] | undefined;
+/** Reports an error thrown by an `after` hook. */
+export type HookErrorReporter = (error: unknown, event: AfterEvent) => void;
+/** Normalize the `hooks` option into a flat array (empty when unset). */
+export declare function normalizeHooks(input: WebhooksHooksInput): WebhooksHooks[];
+/**
+ * Run every `before` hook sequentially, in order. The first hook to throw
+ * aborts: the error propagates to the caller (denying the mutation) and no
+ * later hook runs. A no-op when there are no `before` hooks.
+ */
+export declare function runBefore(hooks: WebhooksHooks[], event: BeforeEvent): Promise<void>;
+/**
+ * Run every `after` hook, isolating failures. The mutation has already
+ * committed, so a throwing hook must not fail the operation — its error is
+ * routed to `onError` and swallowed. Remaining hooks still run.
+ */
+export declare function runAfter(hooks: WebhooksHooks[], event: AfterEvent, onError: HookErrorReporter): Promise<void>;
+/** Default `after`-hook error reporter: warn, but never throw. */
+export declare const defaultHookErrorReporter: HookErrorReporter;

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

@@ -0,0 +1,24 @@
+/**
+ * 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. */
+export 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_…"
+ * ```
+ */
+export declare function newId(prefix: IdPrefix): string;
+/** Regex an id of the given prefix must match. */
+export declare function idPattern(prefix: IdPrefix): RegExp;

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

@@ -0,0 +1,98 @@
+/**
+ * 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. */
+export declare const ROOT = "whk";
+/**
+ * Application keys that would collide with global index keys under the shared
+ * root. Rejected by validation.
+ */
+export declare const RESERVED_APPLICATION_KEYS: readonly ["applications", "event-types", "audit-log"];
+/** Global audit log (event-type actions, which are not application-scoped). */
+export declare const globalAuditLogKey: () => string;
+/** Index key listing all known application keys. */
+export declare const applicationsKey: () => string;
+/** Metadata for a single application. */
+export declare const applicationMetaKey: (applicationKey: string) => string;
+/** Index key listing all event type names (global catalog). */
+export declare const eventTypesKey: () => string;
+/** A single event type record. */
+export declare const eventTypeKey: (name: string) => string;
+/** Index key listing an application's endpoint ids. */
+export declare const endpointsKey: (applicationKey: string) => string;
+/** A single endpoint record. */
+export declare const endpointKey: (applicationKey: string, endpointId: string) => string;
+/** Prefix under which an application's messages live. */
+export declare const messagesPrefix: (applicationKey: string) => string;
+/** A single message record. */
+export declare const messageKey: (applicationKey: string, messageId: string) => string;
+/** Maps a caller-supplied idempotency key to the message id it produced. */
+export declare const idempotencyKey: (applicationKey: string, key: string) => string;
+/** Prefix under which an application's deliveries live. */
+export declare const deliveriesPrefix: (applicationKey: string) => string;
+/** A single delivery record. */
+export declare const deliveryKey: (applicationKey: string, deliveryId: string) => string;
+/** Prefix under which one delivery's attempts live. */
+export 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.
+ */
+export declare const attemptKey: (applicationKey: string, deliveryId: string, attemptNumber: number) => string;
+/** Prefix of an application's due index (the dispatcher's work queue). */
+export declare const duePrefix: (applicationKey: string) => string;
+/** Value stored at a due-index key. */
+export 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.
+ */
+export declare const dueKey: (applicationKey: string, dueAtMillis: number, deliveryId: string) => string;
+/** Parse a due-index key back into its due-time and delivery id. */
+export declare const parseDueKey: (key: string) => {
+    dueAtMillis: number;
+    deliveryId: string;
+} | null;
+/** Prefix of the message → deliveries reverse index. */
+export declare const byMessagePrefix: (applicationKey: string, messageId: string) => string;
+/** One entry in the message → deliveries reverse index. */
+export declare const byMessageKey: (applicationKey: string, messageId: string, deliveryId: string) => string;
+/** Prefix of the endpoint → deliveries reverse index. */
+export declare const byEndpointPrefix: (applicationKey: string, endpointId: string) => string;
+/** One entry in the endpoint → deliveries reverse index. */
+export declare const byEndpointKey: (applicationKey: string, endpointId: string, deliveryId: string) => string;
+/** Append-only audit log for an application, stored as an ordered `AuditEntry[]`. */
+export declare const auditLogKey: (applicationKey: string) => string;
+/** Prefix under which everything belonging to one application lives. */
+export declare const applicationPrefix: (applicationKey: string) => string;
+/** Extract the trailing segment (endpoint id / message id / …) from a key. */
+export declare const lastSegment: (key: string) => string;

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

@@ -0,0 +1,69 @@
+/**
+ * Portal tokens — the credential behind the embeddable consumer portal.
+ *
+ * A portal token is a compact HMAC-signed grant scoping its bearer to exactly
+ * **one application** for a limited time. The host mints tokens server-side
+ * with {@link createPortalToken} (the portal secret never reaches a browser)
+ * and hands them to its frontend; the panel handler verifies them with
+ * {@link verifyPortalToken} and force-scopes authorization to the token's
+ * application (see the `portal` panel option).
+ *
+ * Wire format:
+ *
+ * ```txt
+ * whpt_<base64url(JSON { app, exp })>.<base64url(HMAC-SHA256(secret, payloadPart))>
+ * ```
+ *
+ * Zero dependencies (Web Crypto only). Unlike Standard Webhooks signing
+ * secrets, the portal secret is an **arbitrary string** — it is fed to the
+ * HMAC as raw UTF-8 bytes, not base64-decoded.
+ *
+ * @module
+ */
+import type { WebhookDuration } from "./schema.ts";
+/** Prefix of every portal token. */
+export 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.
+ */
+export declare class PortalTokenError extends Error {
+    constructor(message: string);
+}
+/** Options for {@link createPortalToken}. */
+export 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} />.
+ * ```
+ */
+export 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);
+ * ```
+ */
+export declare function verifyPortalToken(secret: string, token: string): Promise<{
+    applicationKey: string;
+}>;

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

@@ -0,0 +1,229 @@
+/**
+ * Core type definitions for `@xtandard/webhooks`.
+ *
+ * This module is **types only** — no runtime code beyond tiny guards and the
+ * schema-version constant, no dependencies. It is safe to import from the
+ * publish hot path and the receiver. Runtime validation (which pulls in
+ * `valibot`) lives in {@link ./validation}.
+ *
+ * @module
+ */
+/** JSON-serializable value, used for payloads, metadata, and event-type schemas. */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * A duration for configuration options: either milliseconds as a number, or a
+ * human-friendly string such as `"5s"`, `"30m"`, `"2h"`, `"5d"`. Parsed by
+ * {@link ./duration.durationToMs}.
+ */
+export type WebhookDuration = number | `${number}${"ms" | "s" | "m" | "h" | "d"}`;
+/** Identity captured on audit records and passed by callers of audited mutations. */
+export interface Actor {
+    id: string;
+    email?: string;
+    name?: string;
+}
+/** Current schema version for stored records. */
+export declare const SCHEMA_VERSION: 1;
+/**
+ * An application is the unit of tenancy — typically one of *your* customers.
+ * Endpoints, messages, and deliveries are all scoped to an application, and a
+ * portal token grants access to exactly one application.
+ */
+export interface Application {
+    /** Unique key. Allowed characters: `a-z A-Z 0-9 . _ -`. */
+    key: string;
+    /** Optional human-friendly name shown in the UI. */
+    name?: string;
+    /** Arbitrary host-defined metadata. */
+    metadata?: JsonValue;
+    /** ISO-8601 creation timestamp, server-stamped. */
+    createdAt?: string;
+    /** ISO-8601 last-update timestamp, server-stamped. */
+    updatedAt?: string;
+}
+/**
+ * A named kind of event in the **global** catalog (shared by all applications),
+ * e.g. `"invoice.paid"`. Endpoints subscribe to event types by name.
+ */
+export interface EventType {
+    /** Unique dot-delimited name, e.g. `"invoice.paid"`. Allowed: `a-z A-Z 0-9 . _ -`. */
+    name: string;
+    /** Optional description shown in the UI and the public catalog. */
+    description?: string;
+    /** Optional UI grouping label (e.g. `"Billing"`). Purely presentational. */
+    groupName?: string;
+    /**
+     * Optional JSON Schema describing the payload. Documentation by default;
+     * enforced only when the core is configured with a `payloadValidator`.
+     */
+    schema?: JsonValue;
+    /** Deprecated event types are flagged in the UI but still deliverable. */
+    deprecated?: boolean;
+    /** ISO-8601 creation timestamp, server-stamped. */
+    createdAt?: string;
+    /** ISO-8601 last-update timestamp, server-stamped. */
+    updatedAt?: string;
+}
+/**
+ * A signing secret attached to an endpoint. Secrets are `whsec_` + base64 per
+ * the Standard Webhooks spec. Rotation keeps the previous secret verifiable
+ * until `expiresAt` (the grace window); expired secrets are pruned lazily.
+ */
+export interface EndpointSecret {
+    /** `"whsec_"` + base64-encoded random key material. */
+    secret: string;
+    /** ISO-8601 creation timestamp. */
+    createdAt: string;
+    /** Set when superseded by rotation; the secret stops signing after this instant. */
+    expiresAt?: string;
+}
+/** Why an endpoint is disabled: by an operator, or by the auto-disable policy. */
+export type EndpointDisabledReason = "manual" | "auto";
+/**
+ * A customer-registered URL that receives deliveries for one application.
+ */
+export interface Endpoint {
+    /** `"ep_"` + 22-char base62, server-generated. */
+    id: string;
+    /** Destination URL. `https` is enforced by default (`allowInsecureUrls` for dev). */
+    url: string;
+    /** Optional description shown in the UI. */
+    description?: string;
+    /**
+     * Event type names this endpoint subscribes to. Empty or absent = receives
+     * **all** event types.
+     */
+    eventTypes?: string[];
+    /** Disabled endpoints receive no deliveries (pending ones are held, not failed). */
+    disabled?: boolean;
+    /** Who/what disabled it — an operator (`"manual"`) or the failure policy (`"auto"`). */
+    disabledReason?: EndpointDisabledReason;
+    /** Static extra headers merged into every delivery request. */
+    headers?: Record<string, string>;
+    /** Signing secrets. `[0]` is current; extras are still-verifiable rotation grace. */
+    secrets: EndpointSecret[];
+    /** Arbitrary host-defined metadata. */
+    metadata?: JsonValue;
+    /** ISO-8601 creation timestamp, server-stamped. */
+    createdAt?: string;
+    /** ISO-8601 last-update timestamp, server-stamped. */
+    updatedAt?: string;
+    /**
+     * Start of the current unbroken failure streak (any successful delivery
+     * clears it). Drives the auto-disable policy.
+     */
+    firstFailingAt?: string | null;
+}
+/**
+ * A published event for one application. The message is the receiver-facing
+ * unit: its id is the `webhook-id` header (stable across retries — receivers
+ * dedupe on it), and its payload is the `data` of the wire envelope.
+ */
+export interface Message {
+    /** `"msg_"` + 22-char base62, server-generated. Sent as `webhook-id`. */
+    id: string;
+    /** Event type name (usually from the global catalog). */
+    eventType: string;
+    /** The `data` of the wire envelope. */
+    payload: JsonValue;
+    /** ISO-8601 event-occurred time (defaults to publish time). Sent in the envelope. */
+    timestamp: string;
+    /** Optional caller-supplied dedupe key; same key within retention returns the same message. */
+    idempotencyKey?: string;
+    /**
+     * The wire envelope serialized **once at publish time** so the signed bytes
+     * are identical across every retry of every delivery.
+     */
+    envelope: string;
+    /** ISO-8601 creation timestamp, server-stamped. */
+    createdAt: string;
+}
+/**
+ * Delivery lifecycle. `"failed"` means the retry schedule is exhausted — the
+ * dead-letter state. A manual retry moves a failed delivery back to `"pending"`.
+ */
+export type DeliveryStatus = "pending" | "delivering" | "succeeded" | "failed";
+/** Guard: has this delivery reached a terminal state? */
+export declare function isTerminalDeliveryStatus(status: DeliveryStatus): boolean;
+/**
+ * One message × one endpoint. Created at publish time (fan-out) and driven to
+ * a terminal state by the dispatcher.
+ */
+export interface Delivery {
+    /** `"dlv_"` + 22-char base62, server-generated. */
+    id: string;
+    /** The application this delivery belongs to (deliveries cross the dispatcher denormalized). */
+    applicationKey: string;
+    messageId: string;
+    endpointId: string;
+    status: DeliveryStatus;
+    /** Number of attempts made so far. */
+    attemptCount: number;
+    /** When the next attempt is due. `null` once terminal. */
+    nextAttemptAt?: string | null;
+    /** Dispatcher claim expiry; an expired lease makes the delivery reclaimable. */
+    leaseUntil?: string | null;
+    /**
+     * How the *next* attempt should be recorded: set to `"manual"` by
+     * retry/recover so the resulting attempt is attributed correctly, then
+     * cleared. Absent = `"schedule"`.
+     */
+    pendingTrigger?: AttemptTrigger;
+    /** ISO-8601 creation timestamp. */
+    createdAt: string;
+    /** ISO-8601 last-transition timestamp. */
+    updatedAt: string;
+}
+/** What initiated a delivery attempt. */
+export type AttemptTrigger = "schedule" | "manual" | "test";
+/** The recorded outcome of a single HTTP delivery attempt. */
+export interface DeliveryAttempt {
+    /** `"atp_"` + 22-char base62, server-generated. */
+    id: string;
+    deliveryId: string;
+    /** 1-based attempt ordinal within the delivery. */
+    attemptNumber: number;
+    /** ISO-8601 timestamp of the attempt. */
+    at: string;
+    /** Wall-clock duration of the HTTP round trip. */
+    durationMs: number;
+    /** True when the receiver answered 2xx. */
+    ok: boolean;
+    /** HTTP status code; absent on network error or timeout. */
+    httpStatus?: number;
+    /** Truncated error message on network error/timeout. */
+    error?: string;
+    /** Truncated response body (default cap 4096 chars). */
+    responseBody?: string;
+    /** What initiated this attempt. */
+    trigger: AttemptTrigger;
+}
+/** Actions recorded in the control-plane audit log. */
+export type AuditAction = "application.create" | "application.update" | "application.delete" | "event-type.create" | "event-type.update" | "event-type.delete" | "endpoint.create" | "endpoint.update" | "endpoint.delete" | "endpoint.rotate-secret" | "endpoint.disable" | "endpoint.enable" | "delivery.retry" | "endpoint.recover";
+/**
+ * A single control-plane audit record. Publishes are deliberately *not*
+ * audited — they are data-plane traffic, and the message log is their record.
+ */
+export interface AuditEntry {
+    action: AuditAction;
+    /** ISO-8601 timestamp. */
+    at: string;
+    by?: Actor | null;
+    /** The application the action was scoped to (absent for global event types). */
+    applicationKey?: string;
+    /** Endpoint id / event type name / delivery id the action targeted. */
+    subjectId?: string;
+    message?: string;
+}
+/**
+ * The wire envelope receivers get — the Standard Webhooks recommended shape.
+ * `type` is the event type name, `timestamp` the event-occurred time, and
+ * `data` the published payload.
+ */
+export interface WebhookEnvelope {
+    type: string;
+    timestamp: string;
+    data: JsonValue;
+}

package/dist/types-elysia2/server/base-path.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Base-path helpers. The panel can be mounted under any prefix (`/webhooks`,
+ * `/admin/webhooks`, ...). These normalize the configured base path and strip it
+ * from incoming request paths so routing is prefix-agnostic.
+ *
+ * @module
+ */
+/** Normalize a base path to either `""` (root) or `/segment` with no trailing slash. */
+export declare function normalizeBasePath(basePath: string | undefined): string;
+/**
+ * Strip the (normalized) base path from a pathname. Returns a path that always
+ * starts with `/`. If the pathname does not start with the base path it is
+ * returned unchanged (the host framework may already have stripped the mount).
+ */
+export declare function stripBasePath(pathname: string, basePath: string): string;