@xtandard/webhooks 0.1.0

package/dist/core-CMpnmI5Q.mjs

@@ -0,0 +1,1605 @@
+import { t as __exportAll } from "./chunk-D7D4PA-g.mjs";
+import { isTerminalDeliveryStatus } from "./schema.mjs";
+import { generateSecret, signatureHeader } from "./signing.mjs";
+import { C as messageKey, S as lastSegment, _ as eventTypeKey, a as attemptKey, b as idempotencyKey, c as byEndpointKey, d as byMessagePrefix, f as deliveriesPrefix, g as endpointsKey, h as endpointKey, i as applicationsKey, l as byEndpointPrefix, m as dueKey, n as applicationMetaKey, o as attemptsPrefix, p as deliveryKey, r as applicationPrefix, s as auditLogKey, t as RESERVED_APPLICATION_KEYS, u as byMessageKey, v as eventTypesKey, w as messagesPrefix, y as globalAuditLogKey } from "./keys-Byyj4quQ.mjs";
+import { n as isCompareAndSwap, t as hasDeliveryQueue } from "./contract-BEhDcd_5.mjs";
+import * as v from "valibot";
+//#region src/deliver.ts
+/** Default cap on how many response-body characters are kept per attempt. */
+const DEFAULT_RESPONSE_BODY_LIMIT = 4096;
+/** Default per-attempt timeout. */
+const DEFAULT_ATTEMPT_TIMEOUT_MS = 2e4;
+/**
+* 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.
+*/
+async function buildSignedRequest(input) {
+	const nowMs = input.nowMs ?? Date.now();
+	const secrets = activeSecrets(input.endpoint, nowMs);
+	if (secrets.length === 0) throw new Error(`Endpoint ${input.endpoint.id} has no unexpired signing secret`);
+	const timestamp = Math.floor(nowMs / 1e3);
+	const signature = await signatureHeader(secrets, input.messageId, timestamp, input.body);
+	const headers = {
+		...input.endpoint.headers,
+		"content-type": "application/json",
+		"webhook-id": input.messageId,
+		"webhook-timestamp": String(timestamp),
+		"webhook-signature": signature
+	};
+	if (input.userAgent) headers["user-agent"] = input.userAgent;
+	return {
+		method: "POST",
+		url: input.endpoint.url,
+		headers,
+		body: input.body
+	};
+}
+/** The endpoint's currently-signing secrets: the active one + unexpired rotation grace. */
+function activeSecrets(endpoint, nowMs) {
+	return endpoint.secrets.filter((s) => !s.expiresAt || Date.parse(s.expiresAt) > nowMs).map((s) => s.secret);
+}
+const truncate = (value, limit) => value.length > limit ? value.slice(0, limit) : value;
+/**
+* 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.)
+*/
+async function attemptDelivery(input) {
+	const nowMs = input.nowMs ?? Date.now();
+	const at = new Date(nowMs).toISOString();
+	const timeoutMs = input.timeoutMs ?? 2e4;
+	const bodyLimit = input.responseBodyLimit ?? 4096;
+	const doFetch = input.fetch ?? fetch;
+	const { headers } = await buildSignedRequest({
+		endpoint: input.endpoint,
+		messageId: input.messageId,
+		body: input.body,
+		nowMs,
+		...input.userAgent !== void 0 ? { userAgent: input.userAgent } : {}
+	});
+	const started = Date.now();
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), timeoutMs);
+	timer.unref?.();
+	try {
+		const response = await doFetch(input.endpoint.url, {
+			method: "POST",
+			headers,
+			body: input.body,
+			signal: controller.signal,
+			redirect: "manual"
+		});
+		let responseBody = "";
+		try {
+			responseBody = truncate(await response.text(), bodyLimit);
+		} catch {}
+		return {
+			ok: response.status >= 200 && response.status < 300,
+			httpStatus: response.status,
+			responseBody: responseBody || void 0,
+			durationMs: Date.now() - started,
+			at
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			error: truncate(controller.signal.aborted ? `Timed out after ${timeoutMs}ms` : error instanceof Error ? error.message : String(error), 512),
+			durationMs: Date.now() - started,
+			at
+		};
+	} finally {
+		clearTimeout(timer);
+	}
+}
+//#endregion
+//#region src/delivery-sink.ts
+/**
+* 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.
+*/
+function emitDelivery(listener, event, onError) {
+	try {
+		const result = listener(event);
+		if (result && typeof result.then === "function") result.catch((error) => onError?.(error, event));
+	} catch (error) {
+		onError?.(error, event);
+	}
+}
+//#endregion
+//#region src/duration.ts
+const UNIT_MS = {
+	ms: 1,
+	s: 1e3,
+	m: 6e4,
+	h: 36e5,
+	d: 864e5
+};
+const DURATION_RE = /^(\d+(?:\.\d+)?)(ms|s|m|h|d)$/;
+/**
+* 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
+* ```
+*/
+function durationToMs(duration) {
+	if (typeof duration === "number") {
+		if (!Number.isFinite(duration) || duration < 0) throw new Error(`Invalid duration: ${duration}`);
+		return duration;
+	}
+	const match = DURATION_RE.exec(duration.trim());
+	if (!match) throw new Error(`Invalid duration: "${duration}" (expected e.g. "5s", "30m", "2h")`);
+	return Number(match[1]) * UNIT_MS[match[2]];
+}
+/**
+* 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.
+*/
+function parseDurationList(input) {
+	return input.split(",").map((part) => part.trim()).filter((part) => part.length > 0).map((part) => {
+		const asNumber = Number(part);
+		const duration = Number.isFinite(asNumber) ? asNumber : part;
+		durationToMs(duration);
+		return duration;
+	});
+}
+//#endregion
+//#region src/id.ts
+var id_exports = /* @__PURE__ */ __exportAll({
+	idPattern: () => idPattern,
+	newId: () => newId
+});
+const ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+const ID_LENGTH = 22;
+const RANDOM_BYTES = 16;
+/** Encode 128 random bits as a fixed-length 22-char base62 string. */
+function randomBase62() {
+	const bytes = new Uint8Array(RANDOM_BYTES);
+	crypto.getRandomValues(bytes);
+	let value = 0n;
+	for (const b of bytes) value = value << 8n | BigInt(b);
+	let out = "";
+	while (value > 0n) {
+		out = ALPHABET[Number(value % 62n)] + out;
+		value /= 62n;
+	}
+	return out.padStart(ID_LENGTH, "0");
+}
+/**
+* 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_…"
+* ```
+*/
+function newId(prefix) {
+	return `${prefix}_${randomBase62()}`;
+}
+/** Regex an id of the given prefix must match. */
+function idPattern(prefix) {
+	return new RegExp(`^${prefix}_[0-9A-Za-z]{${ID_LENGTH}}$`);
+}
+//#endregion
+//#region src/version.ts
+/**
+* Package version, used for the default dispatcher `user-agent`. Bumped by the
+* release flow alongside `package.json`.
+*
+* @module
+*/
+/** The published package version. */
+const VERSION = "0.1.0";
+//#endregion
+//#region src/hooks/contract.ts
+/**
+* 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 });
+*   }
+* }
+* ```
+*/
+var HookDeniedError = class extends Error {
+	/** HTTP status the API layer should respond with. Default `403`. */
+	status;
+	constructor(message, options) {
+		super(message, options?.cause !== void 0 ? { cause: options.cause } : void 0);
+		this.name = "HookDeniedError";
+		this.status = options?.status ?? 403;
+	}
+};
+/** Normalize the `hooks` option into a flat array (empty when unset). */
+function normalizeHooks(input) {
+	if (!input) return [];
+	return Array.isArray(input) ? [...input] : [input];
+}
+/**
+* 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.
+*/
+async function runBefore(hooks, event) {
+	for (const hook of hooks) if (hook.before) await hook.before(event);
+}
+/**
+* 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.
+*/
+async function runAfter(hooks, event, onError) {
+	await Promise.all(hooks.map(async (hook) => {
+		if (!hook.after) return;
+		try {
+			await hook.after(event);
+		} catch (error) {
+			onError(error, event);
+		}
+	}));
+}
+/** Default `after`-hook error reporter: warn, but never throw. */
+const defaultHookErrorReporter = (error, event) => {
+	console.warn(`[@xtandard/webhooks] after-hook for "${event.type}" threw:`, error);
+};
+//#endregion
+//#region src/validation.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. */
+const KEY_REGEX = /^[a-zA-Z0-9._-]+$/;
+/**
+* Validate a caller-supplied string that becomes a **storage key segment**
+* (e.g. an idempotency key). Rejects anything that could escape its namespace
+* or traverse the filesystem on the file adapter: characters outside
+* {@link KEY_REGEX}, and the dot-only segments `.` / `..`. Returns the issue
+* list (empty when safe) so callers can fold it into a {@link ValidationError}.
+*/
+function validateKeySegment(value, path) {
+	if (!KEY_REGEX.test(value)) return [{
+		path,
+		message: `must match ${KEY_REGEX} (no slashes or path separators)`
+	}];
+	if (/^\.+$/.test(value)) return [{
+		path,
+		message: `"${value}" is not an allowed key`
+	}];
+	if (value.length > 256) return [{
+		path,
+		message: "must be at most 256 characters"
+	}];
+	return [];
+}
+/**
+* Header names owned by the Standard Webhooks wire contract. Endpoints may not
+* override them via static headers.
+*/
+const RESERVED_HEADERS = [
+	"webhook-id",
+	"webhook-timestamp",
+	"webhook-signature"
+];
+const jsonValueSchema = v.lazy(() => v.union([
+	v.string(),
+	v.number(),
+	v.boolean(),
+	v.null(),
+	v.array(jsonValueSchema),
+	v.record(v.string(), jsonValueSchema)
+]));
+const keySchema = v.pipe(v.string(), v.minLength(1), v.maxLength(256), v.regex(KEY_REGEX));
+const applicationSchema = v.object({
+	key: keySchema,
+	name: v.optional(v.string()),
+	metadata: v.optional(jsonValueSchema),
+	createdAt: v.optional(v.string()),
+	updatedAt: v.optional(v.string())
+});
+const eventTypeSchema = v.object({
+	name: keySchema,
+	description: v.optional(v.string()),
+	groupName: v.optional(v.string()),
+	schema: v.optional(jsonValueSchema),
+	deprecated: v.optional(v.boolean()),
+	createdAt: v.optional(v.string()),
+	updatedAt: v.optional(v.string())
+});
+const endpointSecretSchema = v.object({
+	secret: v.pipe(v.string(), v.minLength(1)),
+	createdAt: v.string(),
+	expiresAt: v.optional(v.string())
+});
+const endpointSchema = v.object({
+	id: v.optional(v.string()),
+	url: v.pipe(v.string(), v.minLength(1)),
+	description: v.optional(v.string()),
+	eventTypes: v.optional(v.array(keySchema)),
+	disabled: v.optional(v.boolean()),
+	disabledReason: v.optional(v.picklist(["manual", "auto"])),
+	headers: v.optional(v.record(v.string(), v.string())),
+	secrets: v.optional(v.array(endpointSecretSchema)),
+	metadata: v.optional(jsonValueSchema),
+	createdAt: v.optional(v.string()),
+	updatedAt: v.optional(v.string()),
+	firstFailingAt: v.optional(v.nullable(v.string()))
+});
+/** Raised by {@link assertValid} when an input fails validation. Maps to HTTP 422. */
+var ValidationError = class extends Error {
+	errors;
+	constructor(errors) {
+		super(`Validation failed:\n${errors.map((e) => `  - ${e.path}: ${e.message}`).join("\n")}`);
+		this.name = "ValidationError";
+		this.errors = errors;
+	}
+};
+/** Throw a {@link ValidationError} when `result` is invalid. */
+function assertValid(result) {
+	if (!result.valid) throw new ValidationError(result.errors);
+}
+function structuralIssues(issues, basePath) {
+	return issues.map((issue) => ({
+		path: `${basePath}.${(issue.path ?? []).map((p) => String(p.key)).join(".")}`,
+		message: issue.message
+	}));
+}
+/**
+* Validate an {@link Application}: structure + reserved-key check.
+*
+* @example
+* ```ts
+* import { validateApplication } from "@xtandard/webhooks";
+*
+* const result = validateApplication({ key: "acme" });
+* // result.valid === true
+* ```
+*/
+function validateApplication(input, basePath = "application") {
+	const parsed = v.safeParse(applicationSchema, input);
+	if (!parsed.success) return {
+		valid: false,
+		errors: structuralIssues(parsed.issues, basePath)
+	};
+	const application = parsed.output;
+	const errors = [];
+	if (RESERVED_APPLICATION_KEYS.includes(application.key)) errors.push({
+		path: `${basePath}.key`,
+		message: `"${application.key}" is a reserved application key`
+	});
+	return {
+		valid: errors.length === 0,
+		errors
+	};
+}
+/** Validate an {@link EventType}: structural only (the name regex carries the semantics). */
+function validateEventType(input, basePath = "eventType") {
+	const parsed = v.safeParse(eventTypeSchema, input);
+	if (!parsed.success) return {
+		valid: false,
+		errors: structuralIssues(parsed.issues, basePath)
+	};
+	return {
+		valid: true,
+		errors: []
+	};
+}
+const LOCAL_HOSTS = new Set([
+	"localhost",
+	"127.0.0.1",
+	"[::1]",
+	"::1"
+]);
+/**
+* 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.
+*/
+function validateEndpointUrl(url, options = {}, basePath = "endpoint.url") {
+	const errors = [];
+	let parsed;
+	try {
+		parsed = new URL(url);
+	} catch {
+		return {
+			valid: false,
+			errors: [{
+				path: basePath,
+				message: `invalid URL "${url}"`
+			}]
+		};
+	}
+	if (parsed.username || parsed.password) errors.push({
+		path: basePath,
+		message: "URL must not contain credentials"
+	});
+	if (parsed.protocol === "http:") {
+		if (!options.allowInsecureUrls && !LOCAL_HOSTS.has(parsed.hostname)) errors.push({
+			path: basePath,
+			message: "http URLs are only allowed for localhost (set allowInsecureUrls for dev)"
+		});
+	} else if (parsed.protocol !== "https:") errors.push({
+		path: basePath,
+		message: `unsupported protocol "${parsed.protocol}"`
+	});
+	if (errors.length === 0 && options.urlPolicy && !options.urlPolicy(url)) errors.push({
+		path: basePath,
+		message: "URL rejected by the configured urlPolicy"
+	});
+	return {
+		valid: errors.length === 0,
+		errors
+	};
+}
+/**
+* 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
+* ```
+*/
+function validateEndpoint(input, options = {}, basePath = "endpoint") {
+	const parsed = v.safeParse(endpointSchema, input);
+	if (!parsed.success) return {
+		valid: false,
+		errors: structuralIssues(parsed.issues, basePath)
+	};
+	const endpoint = parsed.output;
+	const errors = [];
+	errors.push(...validateEndpointUrl(endpoint.url, options, `${basePath}.url`).errors);
+	for (const name of Object.keys(endpoint.headers ?? {})) if (RESERVED_HEADERS.includes(name.toLowerCase())) errors.push({
+		path: `${basePath}.headers.${name}`,
+		message: `"${name}" is reserved by the Standard Webhooks wire contract`
+	});
+	return {
+		valid: errors.length === 0,
+		errors
+	};
+}
+//#endregion
+//#region src/core.ts
+/**
+* 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
+*/
+/** Thrown by mutating operations when the core is in readonly mode. */
+var ReadonlyError = class extends Error {
+	constructor(operation) {
+		super(`Cannot ${operation}: @xtandard/webhooks is in readonly mode.`);
+		this.name = "ReadonlyError";
+	}
+};
+/** Thrown when a referenced application/event type/endpoint/delivery does not exist. */
+var NotFoundError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "NotFoundError";
+	}
+};
+/** Thrown when creating an entity whose key already exists. Maps to HTTP 409. */
+var ConflictError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ConflictError";
+	}
+};
+/** Thrown by {@link WebhooksCore.publish} when the payload exceeds the limit. Maps to 413. */
+var PayloadTooLargeError = class extends Error {
+	constructor(size, limit) {
+		super(`Payload is ${size} bytes; the limit is ${limit} bytes.`);
+		this.name = "PayloadTooLargeError";
+	}
+};
+/**
+* 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.
+*/
+var IdempotencyConflictError = class extends Error {
+	constructor(key) {
+		super(`Idempotency key "${key}" was already used with a different payload.`);
+		this.name = "IdempotencyConflictError";
+	}
+};
+const DEFAULT_PAYLOAD_LIMIT = 262144;
+const DEFAULT_ROTATION_GRACE = "24h";
+const MAX_PAGE = 200;
+const DEFAULT_PAGE = 50;
+/**
+* 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 },
+* });
+* ```
+*/
+function createWebhooksCore(options) {
+	const storage = options.storage;
+	const queueStorage = options.queueStorage ?? options.storage;
+	const readonly = options.readonly ?? false;
+	const hooks = normalizeHooks(options.hooks);
+	const onHookError = options.onHookError ?? defaultHookErrorReporter;
+	const secretRotationGrace = options.secretRotationGrace ?? DEFAULT_ROTATION_GRACE;
+	const payloadLimitBytes = options.payloadLimitBytes ?? DEFAULT_PAYLOAD_LIMIT;
+	const requireKnownEventTypes = options.requireKnownEventTypes ?? true;
+	const now = options.now ?? Date.now;
+	const urlOptions = {
+		allowInsecureUrls: options.allowInsecureUrls ?? false,
+		...options.urlPolicy ? { urlPolicy: options.urlPolicy } : {}
+	};
+	const guard = (op) => {
+		if (readonly) throw new ReadonlyError(op);
+	};
+	const before = hooks.length ? (event) => runBefore(hooks, event) : null;
+	const after = hooks.length ? (event) => runAfter(hooks, event, onHookError) : null;
+	const nowIso = () => new Date(now()).toISOString();
+	async function indexAdd(store, key, value) {
+		const list = await store.getItem(key) ?? [];
+		if (!list.includes(value)) {
+			list.push(value);
+			await store.setItem(key, list);
+		}
+	}
+	async function indexRemove(store, key, value) {
+		const list = await store.getItem(key) ?? [];
+		const next = list.filter((v) => v !== value);
+		if (next.length !== list.length) await store.setItem(key, next);
+	}
+	async function appendAudit(entry, scope = "app") {
+		const key = scope === "global" || !entry.applicationKey ? globalAuditLogKey() : auditLogKey(entry.applicationKey);
+		const log = await storage.getItem(key) ?? [];
+		log.push({
+			at: nowIso(),
+			...entry
+		});
+		await storage.setItem(key, log);
+	}
+	async function requireApplication(applicationKey) {
+		const app = await storage.getItem(applicationMetaKey(applicationKey));
+		if (!app) throw new NotFoundError(`Application "${applicationKey}" does not exist.`);
+		return app;
+	}
+	async function requireEndpoint(applicationKey, endpointId) {
+		await requireApplication(applicationKey);
+		const endpoint = await storage.getItem(endpointKey(applicationKey, endpointId));
+		if (!endpoint) throw new NotFoundError(`Endpoint "${endpointId}" does not exist in application "${applicationKey}".`);
+		return endpoint;
+	}
+	/** Write a delivery + its due-index entry (they always move together). */
+	async function writeDeliveryWithDue(delivery, dueAtMillis) {
+		await queueStorage.setItem(deliveryKey(delivery.applicationKey, delivery.id), delivery);
+		await queueStorage.setItem(dueKey(delivery.applicationKey, dueAtMillis, delivery.id), {
+			app: delivery.applicationKey,
+			deliveryId: delivery.id
+		});
+	}
+	/** Remove the due entry a delivery currently occupies, wherever it is. */
+	async function removeDueEntry(delivery) {
+		const candidates = [];
+		if (delivery.nextAttemptAt) candidates.push(Date.parse(delivery.nextAttemptAt));
+		if (delivery.leaseUntil) candidates.push(Date.parse(delivery.leaseUntil));
+		for (const millis of candidates) if (Number.isFinite(millis)) await queueStorage.removeItem(dueKey(delivery.applicationKey, millis, delivery.id));
+	}
+	async function listAttempts(applicationKey, deliveryId) {
+		const keys = (await queueStorage.getKeys(attemptsPrefix(applicationKey, deliveryId))).sort();
+		return (await Promise.all(keys.map((k) => queueStorage.getItem(k)))).filter((a) => a !== null);
+	}
+	async function deleteDeliveryCascade(delivery) {
+		const app = delivery.applicationKey;
+		await removeDueEntry(delivery);
+		for (const k of await queueStorage.getKeys(attemptsPrefix(app, delivery.id))) await queueStorage.removeItem(k);
+		await queueStorage.removeItem(byMessageKey(app, delivery.messageId, delivery.id));
+		await queueStorage.removeItem(byEndpointKey(app, delivery.endpointId, delivery.id));
+		await queueStorage.removeItem(deliveryKey(app, delivery.id));
+	}
+	const pageSize = (limit) => Math.min(Math.max(limit ?? DEFAULT_PAGE, 1), MAX_PAGE);
+	/** newest-first sort; id tiebreak keeps pagination stable. */
+	const byCreatedAtDesc = (a, b) => {
+		const diff = Date.parse(b.createdAt ?? "") - Date.parse(a.createdAt ?? "");
+		return diff !== 0 ? diff : a.id < b.id ? 1 : -1;
+	};
+	function paginate(sorted, limit, beforeId) {
+		let start = 0;
+		if (beforeId) {
+			const idx = sorted.findIndex((item) => item.id === beforeId);
+			if (idx < 0) return [];
+			start = idx + 1;
+		}
+		return sorted.slice(start, start + pageSize(limit));
+	}
+	let pruneInFlight = null;
+	async function pruneMessagesForApp(applicationKey) {
+		const rule = options.retention?.messages;
+		if (!rule || rule.keepLast === void 0 && rule.maxAge === void 0) return;
+		const keys = await storage.getKeys(messagesPrefix(applicationKey));
+		const messages = (await Promise.all(keys.map((k) => storage.getItem(k)))).filter((m) => m !== null);
+		messages.sort(byCreatedAtDesc);
+		const maxAgeMs = rule.maxAge !== void 0 ? durationToMs(rule.maxAge) : null;
+		const cutoff = maxAgeMs !== null ? now() - maxAgeMs : null;
+		const pruned = [];
+		for (const [index, message] of messages.entries()) {
+			const keptByCount = rule.keepLast !== void 0 && index < rule.keepLast;
+			const keptByAge = cutoff !== null && Date.parse(message.createdAt) >= cutoff;
+			if (keptByCount || keptByAge) continue;
+			if (rule.keepLast === void 0 && cutoff === null) continue;
+			const deliveryIds = (await queueStorage.getKeys(byMessagePrefix(applicationKey, message.id))).map(lastSegment);
+			const deliveries = (await Promise.all(deliveryIds.map((id) => queueStorage.getItem(deliveryKey(applicationKey, id))))).filter((d) => d !== null);
+			if (deliveries.some((d) => !isTerminalDeliveryStatus(d.status))) continue;
+			for (const delivery of deliveries) await deleteDeliveryCascade(delivery);
+			if (message.idempotencyKey) await storage.removeItem(idempotencyKey(applicationKey, message.idempotencyKey));
+			await storage.removeItem(messageKey(applicationKey, message.id));
+			pruned.push(message);
+		}
+		if (pruned.length && after) await after({
+			type: "message.pruned",
+			applicationKey,
+			messages: pruned,
+			at: nowIso()
+		});
+	}
+	async function pruneAuditLog(key, applicationKey) {
+		const rule = options.retention?.audit;
+		if (!rule || rule.keepLast === void 0 && rule.maxAge === void 0) return;
+		const log = await storage.getItem(key) ?? [];
+		if (!log.length) return;
+		const maxAgeMs = rule.maxAge !== void 0 ? durationToMs(rule.maxAge) : null;
+		const cutoff = maxAgeMs !== null ? now() - maxAgeMs : null;
+		const kept = [];
+		const removed = [];
+		for (const [index, entry] of log.entries()) {
+			const fromEnd = log.length - index;
+			const keptByCount = rule.keepLast !== void 0 && fromEnd <= rule.keepLast;
+			const keptByAge = cutoff !== null && Date.parse(entry.at) >= cutoff;
+			if (keptByCount || keptByAge) kept.push(entry);
+			else removed.push(entry);
+		}
+		if (removed.length) {
+			await storage.setItem(key, kept);
+			if (after) await after({
+				type: "audit.pruned",
+				...applicationKey ? { applicationKey } : {},
+				entries: removed,
+				at: nowIso()
+			});
+		}
+	}
+	async function prunePass() {
+		const apps = await storage.getItem(applicationsKey()) ?? [];
+		for (const app of apps) {
+			await pruneMessagesForApp(app);
+			await pruneAuditLog(auditLogKey(app), app);
+		}
+		await pruneAuditLog(globalAuditLogKey());
+	}
+	/** Serialized: a call always gets a full pass over the state it observed. */
+	async function prune() {
+		while (pruneInFlight) await pruneInFlight;
+		pruneInFlight = prunePass().finally(() => {
+			pruneInFlight = null;
+		});
+		await pruneInFlight;
+	}
+	function schedulePrune() {
+		if (!options.retention) return;
+		setTimeout(() => {
+			prune().catch((error) => {
+				console.warn("[@xtandard/webhooks] retention prune failed:", error);
+			});
+		}, 0).unref?.();
+	}
+	return {
+		options: Object.freeze({
+			storage,
+			queueStorage,
+			readonly,
+			hooks,
+			...options.retention ? { retention: options.retention } : {},
+			...options.dispatcher ? { dispatcher: options.dispatcher } : {},
+			secretRotationGrace,
+			allowInsecureUrls: urlOptions.allowInsecureUrls,
+			...options.urlPolicy ? { urlPolicy: options.urlPolicy } : {},
+			payloadLimitBytes,
+			requireKnownEventTypes,
+			...options.onDelivery ? { onDelivery: options.onDelivery } : {},
+			...options.onDeliveryError ? { onDeliveryError: options.onDeliveryError } : {},
+			now
+		}),
+		async listApplications() {
+			const keys = await storage.getItem(applicationsKey()) ?? [];
+			return (await Promise.all(keys.map((k) => storage.getItem(applicationMetaKey(k))))).filter((a) => a !== null);
+		},
+		async createApplication(input, opts) {
+			guard("create application");
+			assertValid(validateApplication(input));
+			if (await storage.getItem(applicationMetaKey(input.key))) throw new ConflictError(`Application "${input.key}" already exists.`);
+			const application = {
+				key: input.key,
+				...input.name !== void 0 ? { name: input.name } : {},
+				...input.metadata !== void 0 ? { metadata: input.metadata } : {},
+				createdAt: nowIso(),
+				updatedAt: nowIso()
+			};
+			if (before) await before({
+				type: "application.create",
+				application,
+				actor: opts?.actor ?? null
+			});
+			await storage.setItem(applicationMetaKey(application.key), application);
+			await indexAdd(storage, applicationsKey(), application.key);
+			await appendAudit({
+				action: "application.create",
+				by: opts?.actor ?? null,
+				applicationKey: application.key
+			});
+			if (after) await after({
+				type: "application.created",
+				application,
+				at: nowIso()
+			});
+			return application;
+		},
+		async getApplication(applicationKey) {
+			return storage.getItem(applicationMetaKey(applicationKey));
+		},
+		async updateApplication(applicationKey, patch, opts) {
+			guard("update application");
+			const application = {
+				...await requireApplication(applicationKey),
+				...patch.name !== void 0 ? { name: patch.name } : {},
+				...patch.metadata !== void 0 ? { metadata: patch.metadata } : {},
+				updatedAt: nowIso()
+			};
+			assertValid(validateApplication(application));
+			if (before) await before({
+				type: "application.update",
+				application,
+				actor: opts?.actor ?? null
+			});
+			await storage.setItem(applicationMetaKey(applicationKey), application);
+			await appendAudit({
+				action: "application.update",
+				by: opts?.actor ?? null,
+				applicationKey
+			});
+			if (after) await after({
+				type: "application.updated",
+				application,
+				at: nowIso()
+			});
+			return application;
+		},
+		async deleteApplication(applicationKey, opts) {
+			guard("delete application");
+			const application = await requireApplication(applicationKey);
+			if (before) await before({
+				type: "application.delete",
+				applicationKey,
+				actor: opts?.actor ?? null
+			});
+			for (const key of await storage.getKeys(applicationPrefix(applicationKey))) await storage.removeItem(key);
+			if (queueStorage !== storage) for (const key of await queueStorage.getKeys(applicationPrefix(applicationKey))) await queueStorage.removeItem(key);
+			await indexRemove(storage, applicationsKey(), applicationKey);
+			await appendAudit({
+				action: "application.delete",
+				by: opts?.actor ?? null,
+				applicationKey
+			}, "global");
+			if (after) await after({
+				type: "application.deleted",
+				applicationKey,
+				application,
+				at: nowIso()
+			});
+		},
+		async listEventTypes() {
+			const names = await storage.getItem(eventTypesKey()) ?? [];
+			return (await Promise.all(names.map((n) => storage.getItem(eventTypeKey(n))))).filter((t) => t !== null).sort((a, b) => a.name.localeCompare(b.name));
+		},
+		async getEventType(name) {
+			return storage.getItem(eventTypeKey(name));
+		},
+		async upsertEventType(input, opts) {
+			guard("upsert event type");
+			assertValid(validateEventType(input));
+			const existing = await storage.getItem(eventTypeKey(input.name));
+			const eventType = {
+				...existing,
+				...input,
+				createdAt: existing?.createdAt ?? nowIso(),
+				updatedAt: nowIso()
+			};
+			if (before) await before({
+				type: "event-type.upsert",
+				eventType,
+				actor: opts?.actor ?? null
+			});
+			await storage.setItem(eventTypeKey(eventType.name), eventType);
+			await indexAdd(storage, eventTypesKey(), eventType.name);
+			await appendAudit({
+				action: existing ? "event-type.update" : "event-type.create",
+				by: opts?.actor ?? null,
+				subjectId: eventType.name
+			}, "global");
+			if (after) await after({
+				type: "event-type.upserted",
+				eventType,
+				at: nowIso()
+			});
+			return eventType;
+		},
+		async deleteEventType(name, opts) {
+			guard("delete event type");
+			const eventType = await storage.getItem(eventTypeKey(name));
+			if (!eventType) throw new NotFoundError(`Event type "${name}" does not exist.`);
+			if (before) await before({
+				type: "event-type.delete",
+				name,
+				actor: opts?.actor ?? null
+			});
+			await storage.removeItem(eventTypeKey(name));
+			await indexRemove(storage, eventTypesKey(), name);
+			await appendAudit({
+				action: "event-type.delete",
+				by: opts?.actor ?? null,
+				subjectId: name
+			}, "global");
+			if (after) await after({
+				type: "event-type.deleted",
+				name,
+				eventType,
+				at: nowIso()
+			});
+		},
+		async listEndpoints(applicationKey) {
+			await requireApplication(applicationKey);
+			const ids = await storage.getItem(endpointsKey(applicationKey)) ?? [];
+			return (await Promise.all(ids.map((id) => storage.getItem(endpointKey(applicationKey, id))))).filter((e) => e !== null);
+		},
+		async getEndpoint(applicationKey, endpointId) {
+			return storage.getItem(endpointKey(applicationKey, endpointId));
+		},
+		async createEndpoint(applicationKey, input, opts) {
+			guard("create endpoint");
+			await requireApplication(applicationKey);
+			assertValid(validateEndpoint(input, urlOptions));
+			const endpoint = {
+				id: newId("ep"),
+				url: input.url,
+				...input.description !== void 0 ? { description: input.description } : {},
+				...input.eventTypes !== void 0 ? { eventTypes: input.eventTypes } : {},
+				...input.headers !== void 0 ? { headers: input.headers } : {},
+				...input.metadata !== void 0 ? { metadata: input.metadata } : {},
+				...input.disabled ? {
+					disabled: true,
+					disabledReason: "manual"
+				} : {},
+				secrets: [{
+					secret: generateSecret(),
+					createdAt: nowIso()
+				}],
+				createdAt: nowIso(),
+				updatedAt: nowIso(),
+				firstFailingAt: null
+			};
+			if (before) await before({
+				type: "endpoint.create",
+				applicationKey,
+				endpoint,
+				actor: opts?.actor ?? null
+			});
+			await storage.setItem(endpointKey(applicationKey, endpoint.id), endpoint);
+			await indexAdd(storage, endpointsKey(applicationKey), endpoint.id);
+			await appendAudit({
+				action: "endpoint.create",
+				by: opts?.actor ?? null,
+				applicationKey,
+				subjectId: endpoint.id
+			});
+			if (after) await after({
+				type: "endpoint.created",
+				applicationKey,
+				endpoint,
+				at: nowIso()
+			});
+			return endpoint;
+		},
+		async updateEndpoint(applicationKey, endpointId, patch, opts) {
+			guard("update endpoint");
+			const endpoint = {
+				...await requireEndpoint(applicationKey, endpointId),
+				...patch.url !== void 0 ? { url: patch.url } : {},
+				...patch.description !== void 0 ? { description: patch.description } : {},
+				...patch.eventTypes !== void 0 ? { eventTypes: patch.eventTypes } : {},
+				...patch.headers !== void 0 ? { headers: patch.headers } : {},
+				...patch.metadata !== void 0 ? { metadata: patch.metadata } : {},
+				updatedAt: nowIso()
+			};
+			assertValid(validateEndpoint(endpoint, urlOptions));
+			if (before) await before({
+				type: "endpoint.update",
+				applicationKey,
+				endpoint,
+				actor: opts?.actor ?? null
+			});
+			await storage.setItem(endpointKey(applicationKey, endpointId), endpoint);
+			await appendAudit({
+				action: "endpoint.update",
+				by: opts?.actor ?? null,
+				applicationKey,
+				subjectId: endpointId
+			});
+			if (after) await after({
+				type: "endpoint.updated",
+				applicationKey,
+				endpoint,
+				at: nowIso()
+			});
+			return endpoint;
+		},
+		async deleteEndpoint(applicationKey, endpointId, opts) {
+			guard("delete endpoint");
+			const endpoint = await requireEndpoint(applicationKey, endpointId);
+			if (before) await before({
+				type: "endpoint.delete",
+				applicationKey,
+				endpointId,
+				actor: opts?.actor ?? null
+			});
+			await storage.removeItem(endpointKey(applicationKey, endpointId));
+			await indexRemove(storage, endpointsKey(applicationKey), endpointId);
+			await appendAudit({
+				action: "endpoint.delete",
+				by: opts?.actor ?? null,
+				applicationKey,
+				subjectId: endpointId
+			});
+			if (after) await after({
+				type: "endpoint.deleted",
+				applicationKey,
+				endpoint,
+				at: nowIso()
+			});
+		},
+		async rotateSecret(applicationKey, endpointId, opts) {
+			guard("rotate endpoint secret");
+			const current = await requireEndpoint(applicationKey, endpointId);
+			if (before) await before({
+				type: "endpoint.rotate-secret",
+				applicationKey,
+				endpointId,
+				actor: opts?.actor ?? null
+			});
+			const graceMs = durationToMs(secretRotationGrace);
+			const nowMs = now();
+			const [previous, ...rest] = current.secrets;
+			const secrets = [
+				{
+					secret: generateSecret(),
+					createdAt: nowIso()
+				},
+				...previous ? [{
+					...previous,
+					expiresAt: new Date(nowMs + graceMs).toISOString()
+				}] : [],
+				...rest.filter((s) => s.expiresAt && Date.parse(s.expiresAt) > nowMs)
+			];
+			const endpoint = {
+				...current,
+				secrets,
+				updatedAt: nowIso()
+			};
+			await storage.setItem(endpointKey(applicationKey, endpointId), endpoint);
+			await appendAudit({
+				action: "endpoint.rotate-secret",
+				by: opts?.actor ?? null,
+				applicationKey,
+				subjectId: endpointId
+			});
+			if (after) await after({
+				type: "endpoint.secret-rotated",
+				applicationKey,
+				endpoint,
+				at: nowIso()
+			});
+			return endpoint;
+		},
+		async getSecrets(applicationKey, endpointId) {
+			return (await requireEndpoint(applicationKey, endpointId)).secrets;
+		},
+		async enableEndpoint(applicationKey, endpointId, opts) {
+			guard("enable endpoint");
+			const current = await requireEndpoint(applicationKey, endpointId);
+			if (before) await before({
+				type: "endpoint.enable",
+				applicationKey,
+				endpointId,
+				actor: opts?.actor ?? null
+			});
+			const endpoint = {
+				...current,
+				updatedAt: nowIso(),
+				firstFailingAt: null
+			};
+			delete endpoint.disabled;
+			delete endpoint.disabledReason;
+			await storage.setItem(endpointKey(applicationKey, endpointId), endpoint);
+			await appendAudit({
+				action: "endpoint.enable",
+				by: opts?.actor ?? null,
+				applicationKey,
+				subjectId: endpointId
+			});
+			if (after) await after({
+				type: "endpoint.enabled",
+				applicationKey,
+				endpoint,
+				at: nowIso()
+			});
+			return endpoint;
+		},
+		async disableEndpoint(applicationKey, endpointId, opts) {
+			guard("disable endpoint");
+			const current = await requireEndpoint(applicationKey, endpointId);
+			if (before) await before({
+				type: "endpoint.disable",
+				applicationKey,
+				endpointId,
+				actor: opts?.actor ?? null
+			});
+			const endpoint = {
+				...current,
+				disabled: true,
+				disabledReason: "manual",
+				updatedAt: nowIso()
+			};
+			await storage.setItem(endpointKey(applicationKey, endpointId), endpoint);
+			await appendAudit({
+				action: "endpoint.disable",
+				by: opts?.actor ?? null,
+				applicationKey,
+				subjectId: endpointId
+			});
+			if (after) await after({
+				type: "endpoint.disabled",
+				applicationKey,
+				endpoint,
+				at: nowIso()
+			});
+			return endpoint;
+		},
+		async publish(applicationKey, input, opts) {
+			guard("publish message");
+			await requireApplication(applicationKey);
+			if (requireKnownEventTypes) {
+				if (!await storage.getItem(eventTypeKey(input.eventType))) throw new ValidationError([{
+					path: "message.eventType",
+					message: `unknown event type "${input.eventType}" (create it first, or set requireKnownEventTypes: false)`
+				}]);
+			}
+			const serializedPayload = JSON.stringify(input.payload);
+			if (serializedPayload === void 0) throw new ValidationError([{
+				path: "message.payload",
+				message: "payload must be JSON-serializable"
+			}]);
+			const size = new TextEncoder().encode(serializedPayload).length;
+			if (size > payloadLimitBytes) throw new PayloadTooLargeError(size, payloadLimitBytes);
+			if (input.idempotencyKey !== void 0) {
+				const issues = validateKeySegment(input.idempotencyKey, "message.idempotencyKey");
+				assertValid({
+					valid: issues.length === 0,
+					errors: issues
+				});
+			}
+			if (input.idempotencyKey) {
+				const existingId = await storage.getItem(idempotencyKey(applicationKey, input.idempotencyKey));
+				if (existingId) {
+					const existing = await storage.getItem(messageKey(applicationKey, existingId));
+					if (existing) {
+						if (JSON.stringify(existing.payload) !== serializedPayload) throw new IdempotencyConflictError(input.idempotencyKey);
+						const deliveryIds = (await queueStorage.getKeys(byMessagePrefix(applicationKey, existing.id))).map(lastSegment);
+						return {
+							message: existing,
+							deliveries: (await Promise.all(deliveryIds.map((id) => queueStorage.getItem(deliveryKey(applicationKey, id))))).filter((d) => d !== null),
+							deduplicated: true
+						};
+					}
+				}
+			}
+			if (before) await before({
+				type: "message.publish",
+				applicationKey,
+				eventType: input.eventType,
+				payload: input.payload,
+				...input.idempotencyKey !== void 0 ? { idempotencyKey: input.idempotencyKey } : {},
+				actor: opts?.actor ?? null
+			});
+			const createdAt = nowIso();
+			const timestamp = input.timestamp ?? createdAt;
+			const message = {
+				id: newId("msg"),
+				eventType: input.eventType,
+				payload: input.payload,
+				timestamp,
+				...input.idempotencyKey !== void 0 ? { idempotencyKey: input.idempotencyKey } : {},
+				envelope: JSON.stringify({
+					type: input.eventType,
+					timestamp,
+					data: input.payload
+				}),
+				createdAt
+			};
+			const ids = await storage.getItem(endpointsKey(applicationKey)) ?? [];
+			const matching = (await Promise.all(ids.map((id) => storage.getItem(endpointKey(applicationKey, id))))).filter((e) => e !== null).filter((e) => !e.disabled && (!e.eventTypes || e.eventTypes.length === 0 || e.eventTypes.includes(input.eventType)));
+			await storage.setItem(messageKey(applicationKey, message.id), message);
+			if (input.idempotencyKey) await storage.setItem(idempotencyKey(applicationKey, input.idempotencyKey), message.id);
+			const nowMs = now();
+			const deliveries = [];
+			for (const endpoint of matching) {
+				const delivery = {
+					id: newId("dlv"),
+					applicationKey,
+					messageId: message.id,
+					endpointId: endpoint.id,
+					status: "pending",
+					attemptCount: 0,
+					nextAttemptAt: createdAt,
+					leaseUntil: null,
+					createdAt,
+					updatedAt: createdAt
+				};
+				await writeDeliveryWithDue(delivery, nowMs);
+				await queueStorage.setItem(byMessageKey(applicationKey, message.id, delivery.id), 1);
+				await queueStorage.setItem(byEndpointKey(applicationKey, endpoint.id, delivery.id), 1);
+				deliveries.push(delivery);
+			}
+			if (after) await after({
+				type: "message.published",
+				applicationKey,
+				message,
+				deliveryIds: deliveries.map((d) => d.id),
+				at: nowIso()
+			});
+			schedulePrune();
+			return {
+				message,
+				deliveries,
+				deduplicated: false
+			};
+		},
+		async listMessages(applicationKey, opts = {}) {
+			await requireApplication(applicationKey);
+			const keys = await storage.getKeys(messagesPrefix(applicationKey));
+			let messages = (await Promise.all(keys.map((k) => storage.getItem(k)))).filter((m) => m !== null);
+			if (opts.eventType) messages = messages.filter((m) => m.eventType === opts.eventType);
+			messages.sort(byCreatedAtDesc);
+			return paginate(messages, opts.limit, opts.before);
+		},
+		async getMessage(applicationKey, messageId) {
+			return storage.getItem(messageKey(applicationKey, messageId));
+		},
+		async listDeliveries(applicationKey, opts = {}) {
+			await requireApplication(applicationKey);
+			let ids;
+			if (opts.messageId) ids = (await queueStorage.getKeys(byMessagePrefix(applicationKey, opts.messageId))).map(lastSegment);
+			else if (opts.endpointId) ids = (await queueStorage.getKeys(byEndpointPrefix(applicationKey, opts.endpointId))).map(lastSegment);
+			else ids = (await queueStorage.getKeys(deliveriesPrefix(applicationKey))).map(lastSegment);
+			let deliveries = (await Promise.all(ids.map((id) => queueStorage.getItem(deliveryKey(applicationKey, id))))).filter((d) => d !== null);
+			if (opts.status) deliveries = deliveries.filter((d) => d.status === opts.status);
+			if (opts.endpointId) deliveries = deliveries.filter((d) => d.endpointId === opts.endpointId);
+			if (opts.messageId) deliveries = deliveries.filter((d) => d.messageId === opts.messageId);
+			deliveries.sort(byCreatedAtDesc);
+			return paginate(deliveries, opts.limit, opts.before);
+		},
+		async getDelivery(applicationKey, deliveryId) {
+			const delivery = await queueStorage.getItem(deliveryKey(applicationKey, deliveryId));
+			if (!delivery) return null;
+			return {
+				delivery,
+				attempts: await listAttempts(applicationKey, deliveryId)
+			};
+		},
+		async previewDeliveryRequest(applicationKey, deliveryId) {
+			const delivery = await queueStorage.getItem(deliveryKey(applicationKey, deliveryId));
+			if (!delivery) return null;
+			const [message, endpoint] = await Promise.all([storage.getItem(messageKey(applicationKey, delivery.messageId)), storage.getItem(endpointKey(applicationKey, delivery.endpointId))]);
+			if (!message || !endpoint) return null;
+			return buildSignedRequest({
+				endpoint,
+				messageId: message.id,
+				body: message.envelope,
+				nowMs: now(),
+				userAgent: `xtandard-webhooks/${VERSION}`
+			});
+		},
+		async retryDelivery(applicationKey, deliveryId, opts) {
+			guard("retry delivery");
+			await requireApplication(applicationKey);
+			const current = await queueStorage.getItem(deliveryKey(applicationKey, deliveryId));
+			if (!current) throw new NotFoundError(`Delivery "${deliveryId}" does not exist.`);
+			if (current.status !== "failed") throw new ValidationError([{
+				path: "delivery.status",
+				message: `only failed (dead-letter) deliveries can be retried; this one is "${current.status}"`
+			}]);
+			if (before) await before({
+				type: "delivery.retry",
+				applicationKey,
+				deliveryId,
+				actor: opts?.actor ?? null
+			});
+			const nowMs = now();
+			const delivery = {
+				...current,
+				status: "pending",
+				nextAttemptAt: nowIso(),
+				leaseUntil: null,
+				pendingTrigger: "manual",
+				updatedAt: nowIso()
+			};
+			await writeDeliveryWithDue(delivery, nowMs);
+			await appendAudit({
+				action: "delivery.retry",
+				by: opts?.actor ?? null,
+				applicationKey,
+				subjectId: deliveryId
+			});
+			return delivery;
+		},
+		async recoverEndpoint(applicationKey, endpointId, input, opts) {
+			guard("recover endpoint");
+			await requireEndpoint(applicationKey, endpointId);
+			const sinceMs = Date.parse(input.since);
+			if (!Number.isFinite(sinceMs)) throw new ValidationError([{
+				path: "since",
+				message: `"${input.since}" is not a valid timestamp`
+			}]);
+			if (before) await before({
+				type: "endpoint.recover",
+				applicationKey,
+				endpointId,
+				since: input.since,
+				actor: opts?.actor ?? null
+			});
+			const ids = (await queueStorage.getKeys(byEndpointPrefix(applicationKey, endpointId))).map(lastSegment);
+			const nowMs = now();
+			const recovered = [];
+			for (const id of ids) {
+				const delivery = await queueStorage.getItem(deliveryKey(applicationKey, id));
+				if (!delivery || delivery.status !== "failed") continue;
+				if (Date.parse(delivery.createdAt) < sinceMs) continue;
+				await writeDeliveryWithDue({
+					...delivery,
+					status: "pending",
+					nextAttemptAt: nowIso(),
+					leaseUntil: null,
+					pendingTrigger: "manual",
+					updatedAt: nowIso()
+				}, nowMs);
+				recovered.push(id);
+			}
+			await appendAudit({
+				action: "endpoint.recover",
+				by: opts?.actor ?? null,
+				applicationKey,
+				subjectId: endpointId,
+				message: `${recovered.length} deliveries re-queued since ${input.since}`
+			});
+			return { deliveryIds: recovered };
+		},
+		async sendExample(applicationKey, endpointId, input) {
+			guard("send example delivery");
+			const endpoint = await requireEndpoint(applicationKey, endpointId);
+			const messageId = newId("msg");
+			const timestamp = nowIso();
+			const body = JSON.stringify({
+				type: input.eventType,
+				timestamp,
+				data: input.payload ?? {
+					example: true,
+					eventType: input.eventType
+				}
+			});
+			const dispatcher = options.dispatcher;
+			const outcome = await attemptDelivery({
+				endpoint,
+				messageId,
+				body,
+				...dispatcher?.timeoutMs !== void 0 ? { timeoutMs: dispatcher.timeoutMs } : {},
+				...dispatcher?.responseBodyLimit !== void 0 ? { responseBodyLimit: dispatcher.responseBodyLimit } : {},
+				...dispatcher?.fetch ? { fetch: dispatcher.fetch } : {},
+				...dispatcher?.userAgent !== void 0 ? { userAgent: dispatcher.userAgent } : {},
+				nowMs: now()
+			});
+			if (options.onDelivery) emitDelivery(options.onDelivery, {
+				applicationKey,
+				endpointId,
+				messageId,
+				deliveryId: messageId,
+				eventType: input.eventType,
+				attemptNumber: 1,
+				ok: outcome.ok,
+				terminal: true,
+				...outcome.httpStatus !== void 0 ? { httpStatus: outcome.httpStatus } : {},
+				durationMs: outcome.durationMs,
+				trigger: "test",
+				at: outcome.at
+			}, options.onDeliveryError);
+			return {
+				outcome,
+				body,
+				messageId
+			};
+		},
+		async listAudit(applicationKey) {
+			if (applicationKey) return [...await storage.getItem(auditLogKey(applicationKey)) ?? []].reverse();
+			const apps = await storage.getItem(applicationsKey()) ?? [];
+			const merged = (await Promise.all([storage.getItem(globalAuditLogKey()), ...apps.map((app) => storage.getItem(auditLogKey(app)))])).flatMap((log) => log ?? []);
+			merged.sort((a, b) => Date.parse(b.at) - Date.parse(a.at));
+			return merged;
+		},
+		prune,
+		async claimDueDeliveries(input) {
+			const nowMs = now();
+			const nowStr = new Date(nowMs).toISOString();
+			if (hasDeliveryQueue(queueStorage)) return queueStorage.claimDue({
+				now: nowStr,
+				limit: input.limit,
+				leaseMs: input.leaseMs
+			});
+			const apps = await storage.getItem(applicationsKey()) ?? [];
+			const claimed = [];
+			const cas = isCompareAndSwap(queueStorage) ? queueStorage : null;
+			for (const app of apps) {
+				if (claimed.length >= input.limit) break;
+				const dueKeys = (await queueStorage.getKeys(`whk/${app}/due/`)).sort();
+				for (const key of dueKeys) {
+					if (claimed.length >= input.limit) break;
+					const suffix = lastSegment(key);
+					const sep = suffix.indexOf("~");
+					if (sep === -1) continue;
+					const dueAt = Number(suffix.slice(0, sep));
+					if (!Number.isFinite(dueAt) || dueAt > nowMs) break;
+					const entry = await queueStorage.getItem(key);
+					if (!entry) continue;
+					const dKey = deliveryKey(entry.app, entry.deliveryId);
+					const delivery = await queueStorage.getItem(dKey);
+					if (!delivery || isTerminalDeliveryStatus(delivery.status)) {
+						await queueStorage.removeItem(key);
+						continue;
+					}
+					const leaseExpired = delivery.status === "delivering" && (!delivery.leaseUntil || Date.parse(delivery.leaseUntil) <= nowMs);
+					if (delivery.status !== "pending" && !leaseExpired) continue;
+					const next = {
+						...delivery,
+						status: "delivering",
+						leaseUntil: new Date(nowMs + input.leaseMs).toISOString(),
+						updatedAt: nowStr
+					};
+					if (cas) {
+						if (!await cas.compareAndSwap({
+							key: dKey,
+							expected: delivery,
+							next
+						})) continue;
+					} else await queueStorage.setItem(dKey, next);
+					await queueStorage.removeItem(key);
+					await queueStorage.setItem(dueKey(entry.app, nowMs + input.leaseMs, entry.deliveryId), entry);
+					claimed.push(next);
+				}
+			}
+			return claimed;
+		},
+		async recordAttempt(input) {
+			const { delivery, outcome } = input;
+			const app = delivery.applicationKey;
+			const attemptNumber = delivery.attemptCount + 1;
+			const attempt = {
+				id: newId("atp"),
+				deliveryId: delivery.id,
+				attemptNumber,
+				at: outcome.at,
+				durationMs: outcome.durationMs,
+				ok: outcome.ok,
+				...outcome.httpStatus !== void 0 ? { httpStatus: outcome.httpStatus } : {},
+				...outcome.error !== void 0 ? { error: outcome.error } : {},
+				...outcome.responseBody !== void 0 ? { responseBody: outcome.responseBody } : {},
+				trigger: input.trigger
+			};
+			await queueStorage.setItem(attemptKey(app, delivery.id, attemptNumber), attempt);
+			await removeDueEntry(delivery);
+			const base = { ...delivery };
+			delete base.pendingTrigger;
+			let next;
+			if (outcome.ok) {
+				next = {
+					...base,
+					status: "succeeded",
+					attemptCount: attemptNumber,
+					nextAttemptAt: null,
+					leaseUntil: null,
+					updatedAt: nowIso()
+				};
+				await queueStorage.setItem(deliveryKey(app, delivery.id), next);
+				if (after) await after({
+					type: "delivery.succeeded",
+					applicationKey: app,
+					delivery: next,
+					attempt,
+					at: nowIso()
+				});
+			} else if (input.nextAttemptAt) {
+				next = {
+					...base,
+					status: "pending",
+					attemptCount: attemptNumber,
+					nextAttemptAt: input.nextAttemptAt,
+					leaseUntil: null,
+					updatedAt: nowIso()
+				};
+				await writeDeliveryWithDue(next, Date.parse(input.nextAttemptAt));
+			} else {
+				next = {
+					...base,
+					status: "failed",
+					attemptCount: attemptNumber,
+					nextAttemptAt: null,
+					leaseUntil: null,
+					updatedAt: nowIso()
+				};
+				await queueStorage.setItem(deliveryKey(app, delivery.id), next);
+				if (after) await after({
+					type: "delivery.exhausted",
+					applicationKey: app,
+					delivery: next,
+					attempts: await listAttempts(app, delivery.id),
+					at: nowIso()
+				});
+			}
+			if (options.onDelivery) emitDelivery(options.onDelivery, {
+				applicationKey: app,
+				endpointId: delivery.endpointId,
+				messageId: delivery.messageId,
+				deliveryId: delivery.id,
+				eventType: input.eventType,
+				attemptNumber,
+				ok: outcome.ok,
+				terminal: isTerminalDeliveryStatus(next.status),
+				...outcome.httpStatus !== void 0 ? { httpStatus: outcome.httpStatus } : {},
+				durationMs: outcome.durationMs,
+				trigger: input.trigger,
+				at: outcome.at
+			}, options.onDeliveryError);
+			return next;
+		},
+		async noteEndpointOutcome(applicationKey, endpointId, ok, policy) {
+			const key = endpointKey(applicationKey, endpointId);
+			const failingForDays = policy === false ? void 0 : policy?.failingForDays ?? 5;
+			const plan = (current) => {
+				if (ok) {
+					if (!current.firstFailingAt) return null;
+					return {
+						next: {
+							...current,
+							firstFailingAt: null
+						},
+						disabled: false
+					};
+				}
+				const firstFailingAt = current.firstFailingAt ?? nowIso();
+				let next = {
+					...current,
+					firstFailingAt
+				};
+				const shouldDisable = failingForDays !== void 0 && !current.disabled && now() - Date.parse(firstFailingAt) > failingForDays * 864e5;
+				if (shouldDisable) next = {
+					...next,
+					disabled: true,
+					disabledReason: "auto",
+					updatedAt: nowIso()
+				};
+				return {
+					next,
+					disabled: shouldDisable
+				};
+			};
+			const cas = isCompareAndSwap(storage) ? storage : null;
+			let committed = null;
+			for (let attempt = 0; attempt < 5; attempt++) {
+				const current = await storage.getItem(key);
+				if (!current) return null;
+				const planned = plan(current);
+				if (!planned) return null;
+				if (cas) {
+					if (!await cas.compareAndSwap({
+						key,
+						expected: current,
+						next: planned.next
+					})) continue;
+				} else await storage.setItem(key, planned.next);
+				committed = planned;
+				break;
+			}
+			if (!committed) return null;
+			const updated = committed.next;
+			if (committed.disabled) {
+				await appendAudit({
+					action: "endpoint.disable",
+					applicationKey,
+					subjectId: endpointId,
+					message: `auto-disabled: failing since ${updated.firstFailingAt}`
+				});
+				if (after) await after({
+					type: "endpoint.auto-disabled",
+					applicationKey,
+					endpoint: updated,
+					at: nowIso()
+				});
+				return updated;
+			}
+			return null;
+		}
+	};
+}
+//#endregion
+export { attemptDelivery as A, newId as C, DEFAULT_ATTEMPT_TIMEOUT_MS as D, emitDelivery as E, DEFAULT_RESPONSE_BODY_LIMIT as O, id_exports as S, parseDurationList as T, normalizeHooks as _, ReadonlyError as a, VERSION as b, RESERVED_HEADERS as c, validateApplication as d, validateEndpoint as f, defaultHookErrorReporter as g, HookDeniedError as h, PayloadTooLargeError as i, buildSignedRequest as j, activeSecrets as k, ValidationError as l, validateEventType as m, IdempotencyConflictError as n, createWebhooksCore as o, validateEndpointUrl as p, NotFoundError as r, KEY_REGEX as s, ConflictError as t, assertValid as u, runAfter as v, durationToMs as w, idPattern as x, runBefore as y };
+
+//# sourceMappingURL=core-CMpnmI5Q.mjs.map