@xtandard/webhooks 0.1.0

package/dist/sqlite-Dcufk0x3.cjs

@@ -0,0 +1,78 @@
+const require_keys = require("./keys-FiKpaVHX.cjs");
+let bun_sqlite = require("bun:sqlite");
+//#region src/storage/sqlite.ts
+/**
+* SQLite storage adapter built on `bun:sqlite` — **Bun only**, zero npm deps.
+* Ideal for single-node deployments and local/dev persistence: durable, fast, and
+* file-backed (or in-memory). For multi-node runtimes prefer Redis/Postgres.
+*
+* `bun:sqlite` is marked external at build time, so this module only resolves
+* under the Bun runtime. Importing it under Node will throw — by design.
+*
+* ```ts
+* import { createSqliteStorage } from "@xtandard/webhooks/storage/sqlite";
+* const storage = createSqliteStorage({ path: "./webhooks.sqlite" });
+* ```
+*
+* @module
+*/
+var sqlite_exports = /* @__PURE__ */ require_keys.__exportAll({ createSqliteStorage: () => createSqliteStorage });
+const escapeLike = (prefix) => prefix.replace(/[\\%_]/g, (c) => `\\${c}`);
+/**
+* Create a SQLite-backed storage. Requires the Bun runtime (`bun:sqlite`).
+*
+* @example
+* ```ts
+* import { createSqliteStorage } from "@xtandard/webhooks/storage/sqlite";
+*
+* // File-backed (persists across restarts):
+* const storage = createSqliteStorage({ path: "./webhooks.sqlite" });
+*
+* // In-memory (reset each run, useful for tests):
+* // const storage = createSqliteStorage({ path: ":memory:" });
+* ```
+*/
+function createSqliteStorage(options = {}) {
+	const table = options.table ?? "xtandard_webhooks";
+	if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(table)) throw new Error(`Invalid table name: ${JSON.stringify(table)}`);
+	const ownsDb = !options.database;
+	const db = options.database ?? new bun_sqlite.Database(options.path ?? ":memory:");
+	db.run(`CREATE TABLE IF NOT EXISTS ${table} (key TEXT PRIMARY KEY, value TEXT NOT NULL)`);
+	const selectStmt = db.query(`SELECT value FROM ${table} WHERE key = ?`);
+	const upsertStmt = db.query(`INSERT INTO ${table} (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value`);
+	const deleteStmt = db.query(`DELETE FROM ${table} WHERE key = ?`);
+	const keysStmt = db.query(`SELECT key FROM ${table} WHERE key LIKE ? ESCAPE '\\'`);
+	return {
+		async getItem(key) {
+			const row = selectStmt.get(key);
+			return row ? JSON.parse(row.value) : null;
+		},
+		async setItem(key, value) {
+			upsertStmt.run(key, JSON.stringify(value));
+		},
+		async removeItem(key) {
+			deleteStmt.run(key);
+		},
+		async getKeys(prefix) {
+			return keysStmt.all(`${escapeLike(prefix)}%`).map((r) => r.key);
+		},
+		close() {
+			if (ownsDb) db.close();
+		}
+	};
+}
+//#endregion
+Object.defineProperty(exports, "createSqliteStorage", {
+	enumerable: true,
+	get: function() {
+		return createSqliteStorage;
+	}
+});
+Object.defineProperty(exports, "sqlite_exports", {
+	enumerable: true,
+	get: function() {
+		return sqlite_exports;
+	}
+});
+
+//# sourceMappingURL=sqlite-Dcufk0x3.cjs.map

package/dist/sqlite-Dcufk0x3.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-Dcufk0x3.cjs","names":["Database"],"sources":["../src/storage/sqlite.ts"],"sourcesContent":["/**\n * SQLite storage adapter built on `bun:sqlite` — **Bun only**, zero npm deps.\n * Ideal for single-node deployments and local/dev persistence: durable, fast, and\n * file-backed (or in-memory). For multi-node runtimes prefer Redis/Postgres.\n *\n * `bun:sqlite` is marked external at build time, so this module only resolves\n * under the Bun runtime. Importing it under Node will throw — by design.\n *\n * ```ts\n * import { createSqliteStorage } from \"@xtandard/webhooks/storage/sqlite\";\n * const storage = createSqliteStorage({ path: \"./webhooks.sqlite\" });\n * ```\n *\n * @module\n */\n\nimport { Database } from \"bun:sqlite\";\nimport type { WebhooksStorage } from \"./contract.ts\";\n\n/** Options for {@link createSqliteStorage}. */\nexport interface SqliteStorageOptions {\n  /** File path for the database. Default `\":memory:\"`. Ignored when `database` is given. */\n  path?: string;\n  /** An existing `bun:sqlite` Database instance to use instead of opening one. */\n  database?: Database;\n  /** Table name (default `\"xtandard_webhooks\"`). Validated as a safe identifier. */\n  table?: string;\n}\n\n/** A {@link WebhooksStorage} backed by SQLite, plus `close()`. */\nexport interface SqliteWebhooksStorage extends WebhooksStorage {\n  /** Close the database if this adapter opened it; no-op for a borrowed instance. */\n  close(): void;\n}\n\nconst escapeLike = (prefix: string): string => prefix.replace(/[\\\\%_]/g, (c) => `\\\\${c}`);\n\n/**\n * Create a SQLite-backed storage. Requires the Bun runtime (`bun:sqlite`).\n *\n * @example\n * ```ts\n * import { createSqliteStorage } from \"@xtandard/webhooks/storage/sqlite\";\n *\n * // File-backed (persists across restarts):\n * const storage = createSqliteStorage({ path: \"./webhooks.sqlite\" });\n *\n * // In-memory (reset each run, useful for tests):\n * // const storage = createSqliteStorage({ path: \":memory:\" });\n * ```\n */\nexport function createSqliteStorage(options: SqliteStorageOptions = {}): SqliteWebhooksStorage {\n  const table = options.table ?? \"xtandard_webhooks\";\n  if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(table)) {\n    throw new Error(`Invalid table name: ${JSON.stringify(table)}`);\n  }\n\n  const ownsDb = !options.database;\n  const db = options.database ?? new Database(options.path ?? \":memory:\");\n  db.run(`CREATE TABLE IF NOT EXISTS ${table} (key TEXT PRIMARY KEY, value TEXT NOT NULL)`);\n\n  const selectStmt = db.query(`SELECT value FROM ${table} WHERE key = ?`);\n  const upsertStmt = db.query(\n    `INSERT INTO ${table} (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value`,\n  );\n  const deleteStmt = db.query(`DELETE FROM ${table} WHERE key = ?`);\n  const keysStmt = db.query(`SELECT key FROM ${table} WHERE key LIKE ? ESCAPE '\\\\'`);\n\n  return {\n    async getItem<T>(key: string): Promise<T | null> {\n      const row = selectStmt.get(key) as { value: string } | null;\n      return row ? (JSON.parse(row.value) as T) : null;\n    },\n    async setItem<T>(key: string, value: T): Promise<void> {\n      upsertStmt.run(key, JSON.stringify(value));\n    },\n    async removeItem(key: string): Promise<void> {\n      deleteStmt.run(key);\n    },\n    async getKeys(prefix: string): Promise<string[]> {\n      const rows = keysStmt.all(`${escapeLike(prefix)}%`) as Array<{ key: string }>;\n      return rows.map((r) => r.key);\n    },\n    close(): void {\n      if (ownsDb) db.close();\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAmCA,MAAM,cAAc,WAA2B,OAAO,QAAQ,YAAY,MAAM,KAAK,GAAG;;;;;;;;;;;;;;;AAgBxF,SAAgB,oBAAoB,UAAgC,CAAC,GAA0B;CAC7F,MAAM,QAAQ,QAAQ,SAAS;CAC/B,IAAI,CAAC,2BAA2B,KAAK,KAAK,GACxC,MAAM,IAAI,MAAM,uBAAuB,KAAK,UAAU,KAAK,GAAG;CAGhE,MAAM,SAAS,CAAC,QAAQ;CACxB,MAAM,KAAK,QAAQ,YAAY,IAAIA,WAAAA,SAAS,QAAQ,QAAQ,UAAU;CACtE,GAAG,IAAI,8BAA8B,MAAM,6CAA6C;CAExF,MAAM,aAAa,GAAG,MAAM,qBAAqB,MAAM,eAAe;CACtE,MAAM,aAAa,GAAG,MACpB,eAAe,MAAM,kFACvB;CACA,MAAM,aAAa,GAAG,MAAM,eAAe,MAAM,eAAe;CAChE,MAAM,WAAW,GAAG,MAAM,mBAAmB,MAAM,8BAA8B;CAEjF,OAAO;EACL,MAAM,QAAW,KAAgC;GAC/C,MAAM,MAAM,WAAW,IAAI,GAAG;GAC9B,OAAO,MAAO,KAAK,MAAM,IAAI,KAAK,IAAU;EAC9C;EACA,MAAM,QAAW,KAAa,OAAyB;GACrD,WAAW,IAAI,KAAK,KAAK,UAAU,KAAK,CAAC;EAC3C;EACA,MAAM,WAAW,KAA4B;GAC3C,WAAW,IAAI,GAAG;EACpB;EACA,MAAM,QAAQ,QAAmC;GAE/C,OADa,SAAS,IAAI,GAAG,WAAW,MAAM,EAAE,EACtC,EAAE,KAAK,MAAM,EAAE,GAAG;EAC9B;EACA,QAAc;GACZ,IAAI,QAAQ,GAAG,MAAM;EACvB;CACF;AACF"}

package/dist/table-Ce3Tzwqs.d.cts

@@ -0,0 +1,11 @@
+import { Column, Table } from "drizzle-orm";
+
+//#region src/drizzle/table.d.ts
+/** A table with the fixed `key`/`value` columns the webhooks KV store requires. */
+type DrizzleKvTable = Table & {
+  key: Column;
+  value: Column;
+};
+//#endregion
+export { DrizzleKvTable as t };
+//# sourceMappingURL=table-Ce3Tzwqs.d.cts.map

package/dist/table-Ce3Tzwqs.d.mts

@@ -0,0 +1,11 @@
+import { Column, Table } from "drizzle-orm";
+
+//#region src/drizzle/table.d.ts
+/** A table with the fixed `key`/`value` columns the webhooks KV store requires. */
+type DrizzleKvTable = Table & {
+  key: Column;
+  value: Column;
+};
+//#endregion
+export { DrizzleKvTable as t };
+//# sourceMappingURL=table-Ce3Tzwqs.d.mts.map

package/dist/testing.cjs

@@ -0,0 +1,134 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_signing = require("./signing.cjs");
+const require_core = require("./core-ZGhH6Vs2.cjs");
+const require_dispatcher = require("./dispatcher-B0xTEHt1.cjs");
+const require_memory = require("./memory-8Ef-PL5a.cjs");
+let node_http = require("node:http");
+//#region src/testing.ts
+/**
+* Testing utilities — `@xtandard/webhooks/testing`.
+*
+* Everything a host app (or this package's own suite) needs to test its
+* webhook wiring without the network or timers:
+*
+* - {@link createTestWebhooks}: an in-memory core + a **not-started** dispatcher,
+*   driven manually via `dispatcher.tick()` / {@link drainDeliveries}.
+* - {@link createTestReceiver}: a real local HTTP server that records (and,
+*   given the secret, verifies) every delivery it receives — including
+*   programmable failures to exercise the retry path.
+*
+* @module
+*/
+/**
+* An in-memory core + dispatcher for tests. The dispatcher is **not started**
+* (no timers) and defaults to an immediate three-attempt retry schedule so
+* failure paths drain in a few ticks.
+*
+* @example
+* ```ts
+* import { createTestWebhooks, drainDeliveries } from "@xtandard/webhooks/testing";
+*
+* const { core, dispatcher } = createTestWebhooks();
+* await core.createApplication({ key: "acme" });
+* // … create an endpoint, publish, then:
+* await drainDeliveries(dispatcher);
+* ```
+*/
+function createTestWebhooks(options = {}) {
+	const storage = require_memory.createMemoryStorage();
+	const { dispatcher: dispatcherOptions, ...coreOptions } = options;
+	const core = require_core.createWebhooksCore({
+		storage,
+		allowInsecureUrls: true,
+		...coreOptions,
+		dispatcher: {
+			retrySchedule: [
+				"0s",
+				"0s",
+				"0s"
+			],
+			...dispatcherOptions
+		}
+	});
+	return {
+		core,
+		storage,
+		dispatcher: require_dispatcher.createDispatcher(core)
+	};
+}
+/**
+* Start a real local HTTP server that plays the receiving side of a webhook.
+* Works under Bun and Node.
+*
+* @example
+* ```ts
+* const receiver = await createTestReceiver({ secret, failFirst: 2 });
+* await core.createEndpoint("acme", { url: receiver.url });
+* // … publish + drain; receiver.received now holds the verified envelopes.
+* await receiver.close();
+* ```
+*/
+async function createTestReceiver(options = {}) {
+	const received = [];
+	const requests = [];
+	let remainingFailures = options.failFirst ?? 0;
+	const server = (0, node_http.createServer)((req, res) => {
+		const chunks = [];
+		req.on("data", (chunk) => chunks.push(chunk));
+		req.on("end", () => {
+			(async () => {
+				const body = Buffer.concat(chunks).toString("utf8");
+				const headers = {};
+				for (const [name, value] of Object.entries(req.headers)) if (typeof value === "string") headers[name] = value;
+				requests.push({
+					headers,
+					body
+				});
+				if (remainingFailures > 0) {
+					remainingFailures--;
+					res.writeHead(options.status ?? 500, { "content-type": "text/plain" });
+					res.end("simulated failure");
+					return;
+				}
+				if (options.secret) try {
+					received.push(await require_signing.verify({
+						payload: body,
+						headers,
+						secret: options.secret
+					}));
+				} catch {
+					res.writeHead(401, { "content-type": "text/plain" });
+					res.end("invalid signature");
+					return;
+				}
+				res.writeHead(200, { "content-type": "text/plain" });
+				res.end("ok");
+			})();
+		});
+	});
+	await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+	const address = server.address();
+	if (address === null || typeof address === "string") throw new Error("Test receiver failed to bind a port");
+	return {
+		url: `http://127.0.0.1:${address.port}/webhooks`,
+		received,
+		requests,
+		close: () => new Promise((resolve, reject) => {
+			server.close((err) => err ? reject(err) : resolve());
+		})
+	};
+}
+/**
+* Tick the dispatcher until a pass makes no attempts (or `maxTicks` is hit).
+* Pair with an all-immediate retry schedule ({@link createTestWebhooks}'s
+* default) so failed deliveries are due again on the very next tick.
+*/
+async function drainDeliveries(dispatcher, maxTicks = 25) {
+	for (let i = 0; i < maxTicks; i++) if (await dispatcher.tick() === 0) return;
+}
+//#endregion
+exports.createTestReceiver = createTestReceiver;
+exports.createTestWebhooks = createTestWebhooks;
+exports.drainDeliveries = drainDeliveries;
+
+//# sourceMappingURL=testing.cjs.map

package/dist/testing.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.cjs","names":["createMemoryStorage","createWebhooksCore","createDispatcher","verify"],"sources":["../src/testing.ts"],"sourcesContent":["/**\n * Testing utilities — `@xtandard/webhooks/testing`.\n *\n * Everything a host app (or this package's own suite) needs to test its\n * webhook wiring without the network or timers:\n *\n * - {@link createTestWebhooks}: an in-memory core + a **not-started** dispatcher,\n *   driven manually via `dispatcher.tick()` / {@link drainDeliveries}.\n * - {@link createTestReceiver}: a real local HTTP server that records (and,\n *   given the secret, verifies) every delivery it receives — including\n *   programmable failures to exercise the retry path.\n *\n * @module\n */\n\nimport { createServer, type IncomingMessage, type Server, type ServerResponse } from \"node:http\";\nimport { createWebhooksCore, type WebhooksCore, type WebhooksCoreOptions } from \"./core.ts\";\nimport { createDispatcher, type Dispatcher, type DispatcherOptions } from \"./dispatcher.ts\";\nimport type { WebhookEnvelope } from \"./schema.ts\";\nimport { verify } from \"./signing.ts\";\nimport { createMemoryStorage, type MemoryWebhooksStorage } from \"./storage/memory.ts\";\n\n/** Options for {@link createTestWebhooks}. */\nexport interface TestWebhooksOptions extends Omit<WebhooksCoreOptions, \"storage\" | \"queueStorage\"> {\n  /** Dispatcher config; a fast all-immediate retry schedule is the default. */\n  dispatcher?: DispatcherOptions;\n}\n\n/** Result of {@link createTestWebhooks}. */\nexport interface TestWebhooks {\n  core: WebhooksCore;\n  storage: MemoryWebhooksStorage;\n  /** NOT started — drive it with `tick()` or {@link drainDeliveries}. */\n  dispatcher: Dispatcher;\n}\n\n/**\n * An in-memory core + dispatcher for tests. The dispatcher is **not started**\n * (no timers) and defaults to an immediate three-attempt retry schedule so\n * failure paths drain in a few ticks.\n *\n * @example\n * ```ts\n * import { createTestWebhooks, drainDeliveries } from \"@xtandard/webhooks/testing\";\n *\n * const { core, dispatcher } = createTestWebhooks();\n * await core.createApplication({ key: \"acme\" });\n * // … create an endpoint, publish, then:\n * await drainDeliveries(dispatcher);\n * ```\n */\nexport function createTestWebhooks(options: TestWebhooksOptions = {}): TestWebhooks {\n  const storage = createMemoryStorage();\n  const { dispatcher: dispatcherOptions, ...coreOptions } = options;\n  const core = createWebhooksCore({\n    storage,\n    allowInsecureUrls: true, // test receivers are local http\n    ...coreOptions,\n    dispatcher: {\n      retrySchedule: [\"0s\", \"0s\", \"0s\"],\n      ...dispatcherOptions,\n    },\n  });\n  const dispatcher = createDispatcher(core);\n  return { core, storage, dispatcher };\n}\n\n/** Options for {@link createTestReceiver}. */\nexport interface TestReceiverOptions {\n  /**\n   * When set, each request is verified against this secret and its parsed\n   * envelope lands in `received`; an invalid signature answers 401.\n   */\n  secret?: string;\n  /** Fail (with `status`) the first N requests — exercises the retry path. */\n  failFirst?: number;\n  /** The failure status used while failing. Default `500`. */\n  status?: number;\n}\n\n/** A running test receiver. */\nexport interface TestReceiver {\n  /** The local URL to register as an endpoint. */\n  url: string;\n  /** Verified envelopes (only populated when `secret` was provided). */\n  received: WebhookEnvelope[];\n  /** Every request, verified or not, in arrival order. */\n  requests: { headers: Record<string, string>; body: string }[];\n  close(): Promise<void>;\n}\n\n/**\n * Start a real local HTTP server that plays the receiving side of a webhook.\n * Works under Bun and Node.\n *\n * @example\n * ```ts\n * const receiver = await createTestReceiver({ secret, failFirst: 2 });\n * await core.createEndpoint(\"acme\", { url: receiver.url });\n * // … publish + drain; receiver.received now holds the verified envelopes.\n * await receiver.close();\n * ```\n */\nexport async function createTestReceiver(options: TestReceiverOptions = {}): Promise<TestReceiver> {\n  const received: WebhookEnvelope[] = [];\n  const requests: { headers: Record<string, string>; body: string }[] = [];\n  let remainingFailures = options.failFirst ?? 0;\n\n  const server: Server = createServer((req: IncomingMessage, res: ServerResponse) => {\n    const chunks: Buffer[] = [];\n    req.on(\"data\", (chunk: Buffer) => chunks.push(chunk));\n    req.on(\"end\", () => {\n      void (async () => {\n        const body = Buffer.concat(chunks).toString(\"utf8\");\n        const headers: Record<string, string> = {};\n        for (const [name, value] of Object.entries(req.headers)) {\n          if (typeof value === \"string\") headers[name] = value;\n        }\n        requests.push({ headers, body });\n\n        if (remainingFailures > 0) {\n          remainingFailures--;\n          res.writeHead(options.status ?? 500, { \"content-type\": \"text/plain\" });\n          res.end(\"simulated failure\");\n          return;\n        }\n\n        if (options.secret) {\n          try {\n            received.push(await verify({ payload: body, headers, secret: options.secret }));\n          } catch {\n            res.writeHead(401, { \"content-type\": \"text/plain\" });\n            res.end(\"invalid signature\");\n            return;\n          }\n        }\n        res.writeHead(200, { \"content-type\": \"text/plain\" });\n        res.end(\"ok\");\n      })();\n    });\n  });\n\n  await new Promise<void>((resolve) => server.listen(0, \"127.0.0.1\", resolve));\n  const address = server.address();\n  if (address === null || typeof address === \"string\") {\n    throw new Error(\"Test receiver failed to bind a port\");\n  }\n\n  return {\n    url: `http://127.0.0.1:${address.port}/webhooks`,\n    received,\n    requests,\n    close: () =>\n      new Promise<void>((resolve, reject) => {\n        server.close((err) => (err ? reject(err) : resolve()));\n      }),\n  };\n}\n\n/**\n * Tick the dispatcher until a pass makes no attempts (or `maxTicks` is hit).\n * Pair with an all-immediate retry schedule ({@link createTestWebhooks}'s\n * default) so failed deliveries are due again on the very next tick.\n */\nexport async function drainDeliveries(dispatcher: Dispatcher, maxTicks = 25): Promise<void> {\n  for (let i = 0; i < maxTicks; i++) {\n    if ((await dispatcher.tick()) === 0) return;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmDA,SAAgB,mBAAmB,UAA+B,CAAC,GAAiB;CAClF,MAAM,UAAUA,eAAAA,oBAAoB;CACpC,MAAM,EAAE,YAAY,mBAAmB,GAAG,gBAAgB;CAC1D,MAAM,OAAOC,aAAAA,mBAAmB;EAC9B;EACA,mBAAmB;EACnB,GAAG;EACH,YAAY;GACV,eAAe;IAAC;IAAM;IAAM;GAAI;GAChC,GAAG;EACL;CACF,CAAC;CAED,OAAO;EAAE;EAAM;EAAS,YADLC,mBAAAA,iBAAiB,IACH;CAAE;AACrC;;;;;;;;;;;;;AAsCA,eAAsB,mBAAmB,UAA+B,CAAC,GAA0B;CACjG,MAAM,WAA8B,CAAC;CACrC,MAAM,WAAgE,CAAC;CACvE,IAAI,oBAAoB,QAAQ,aAAa;CAE7C,MAAM,UAAA,GAAA,UAAA,eAA+B,KAAsB,QAAwB;EACjF,MAAM,SAAmB,CAAC;EAC1B,IAAI,GAAG,SAAS,UAAkB,OAAO,KAAK,KAAK,CAAC;EACpD,IAAI,GAAG,aAAa;GAClB,CAAM,YAAY;IAChB,MAAM,OAAO,OAAO,OAAO,MAAM,EAAE,SAAS,MAAM;IAClD,MAAM,UAAkC,CAAC;IACzC,KAAK,MAAM,CAAC,MAAM,UAAU,OAAO,QAAQ,IAAI,OAAO,GACpD,IAAI,OAAO,UAAU,UAAU,QAAQ,QAAQ;IAEjD,SAAS,KAAK;KAAE;KAAS;IAAK,CAAC;IAE/B,IAAI,oBAAoB,GAAG;KACzB;KACA,IAAI,UAAU,QAAQ,UAAU,KAAK,EAAE,gBAAgB,aAAa,CAAC;KACrE,IAAI,IAAI,mBAAmB;KAC3B;IACF;IAEA,IAAI,QAAQ,QACV,IAAI;KACF,SAAS,KAAK,MAAMC,gBAAAA,OAAO;MAAE,SAAS;MAAM;MAAS,QAAQ,QAAQ;KAAO,CAAC,CAAC;IAChF,QAAQ;KACN,IAAI,UAAU,KAAK,EAAE,gBAAgB,aAAa,CAAC;KACnD,IAAI,IAAI,mBAAmB;KAC3B;IACF;IAEF,IAAI,UAAU,KAAK,EAAE,gBAAgB,aAAa,CAAC;IACnD,IAAI,IAAI,IAAI;GACd,GAAG;EACL,CAAC;CACH,CAAC;CAED,MAAM,IAAI,SAAe,YAAY,OAAO,OAAO,GAAG,aAAa,OAAO,CAAC;CAC3E,MAAM,UAAU,OAAO,QAAQ;CAC/B,IAAI,YAAY,QAAQ,OAAO,YAAY,UACzC,MAAM,IAAI,MAAM,qCAAqC;CAGvD,OAAO;EACL,KAAK,oBAAoB,QAAQ,KAAK;EACtC;EACA;EACA,aACE,IAAI,SAAe,SAAS,WAAW;GACrC,OAAO,OAAO,QAAS,MAAM,OAAO,GAAG,IAAI,QAAQ,CAAE;EACvD,CAAC;CACL;AACF;;;;;;AAOA,eAAsB,gBAAgB,YAAwB,WAAW,IAAmB;CAC1F,KAAK,IAAI,IAAI,GAAG,IAAI,UAAU,KAC5B,IAAK,MAAM,WAAW,KAAK,MAAO,GAAG;AAEzC"}

package/dist/testing.d.cts

@@ -0,0 +1,80 @@
+import { _ as WebhookEnvelope } from "./schema-mo__wv4P.cjs";
+import { S as DispatcherOptions, _ as WebhooksCore, v as WebhooksCoreOptions, x as Dispatcher } from "./core-KJawHjFF.cjs";
+import { n as MemoryWebhooksStorage } from "./memory-FnMJWCmB.cjs";
+
+//#region src/testing.d.ts
+/** Options for {@link createTestWebhooks}. */
+interface TestWebhooksOptions extends Omit<WebhooksCoreOptions, "storage" | "queueStorage"> {
+  /** Dispatcher config; a fast all-immediate retry schedule is the default. */
+  dispatcher?: DispatcherOptions;
+}
+/** Result of {@link createTestWebhooks}. */
+interface TestWebhooks {
+  core: WebhooksCore;
+  storage: MemoryWebhooksStorage;
+  /** NOT started — drive it with `tick()` or {@link drainDeliveries}. */
+  dispatcher: Dispatcher;
+}
+/**
+ * An in-memory core + dispatcher for tests. The dispatcher is **not started**
+ * (no timers) and defaults to an immediate three-attempt retry schedule so
+ * failure paths drain in a few ticks.
+ *
+ * @example
+ * ```ts
+ * import { createTestWebhooks, drainDeliveries } from "@xtandard/webhooks/testing";
+ *
+ * const { core, dispatcher } = createTestWebhooks();
+ * await core.createApplication({ key: "acme" });
+ * // … create an endpoint, publish, then:
+ * await drainDeliveries(dispatcher);
+ * ```
+ */
+declare function createTestWebhooks(options?: TestWebhooksOptions): TestWebhooks;
+/** Options for {@link createTestReceiver}. */
+interface TestReceiverOptions {
+  /**
+   * When set, each request is verified against this secret and its parsed
+   * envelope lands in `received`; an invalid signature answers 401.
+   */
+  secret?: string;
+  /** Fail (with `status`) the first N requests — exercises the retry path. */
+  failFirst?: number;
+  /** The failure status used while failing. Default `500`. */
+  status?: number;
+}
+/** A running test receiver. */
+interface TestReceiver {
+  /** The local URL to register as an endpoint. */
+  url: string;
+  /** Verified envelopes (only populated when `secret` was provided). */
+  received: WebhookEnvelope[];
+  /** Every request, verified or not, in arrival order. */
+  requests: {
+    headers: Record<string, string>;
+    body: string;
+  }[];
+  close(): Promise<void>;
+}
+/**
+ * Start a real local HTTP server that plays the receiving side of a webhook.
+ * Works under Bun and Node.
+ *
+ * @example
+ * ```ts
+ * const receiver = await createTestReceiver({ secret, failFirst: 2 });
+ * await core.createEndpoint("acme", { url: receiver.url });
+ * // … publish + drain; receiver.received now holds the verified envelopes.
+ * await receiver.close();
+ * ```
+ */
+declare function createTestReceiver(options?: TestReceiverOptions): Promise<TestReceiver>;
+/**
+ * Tick the dispatcher until a pass makes no attempts (or `maxTicks` is hit).
+ * Pair with an all-immediate retry schedule ({@link createTestWebhooks}'s
+ * default) so failed deliveries are due again on the very next tick.
+ */
+declare function drainDeliveries(dispatcher: Dispatcher, maxTicks?: number): Promise<void>;
+//#endregion
+export { TestReceiver, TestReceiverOptions, TestWebhooks, TestWebhooksOptions, createTestReceiver, createTestWebhooks, drainDeliveries };
+//# sourceMappingURL=testing.d.cts.map

package/dist/testing.d.mts

@@ -0,0 +1,80 @@
+import { _ as WebhookEnvelope } from "./schema-mo__wv4P.mjs";
+import { S as DispatcherOptions, _ as WebhooksCore, v as WebhooksCoreOptions, x as Dispatcher } from "./core-DT4ppWh8.mjs";
+import { n as MemoryWebhooksStorage } from "./memory-qIvANEs_.mjs";
+
+//#region src/testing.d.ts
+/** Options for {@link createTestWebhooks}. */
+interface TestWebhooksOptions extends Omit<WebhooksCoreOptions, "storage" | "queueStorage"> {
+  /** Dispatcher config; a fast all-immediate retry schedule is the default. */
+  dispatcher?: DispatcherOptions;
+}
+/** Result of {@link createTestWebhooks}. */
+interface TestWebhooks {
+  core: WebhooksCore;
+  storage: MemoryWebhooksStorage;
+  /** NOT started — drive it with `tick()` or {@link drainDeliveries}. */
+  dispatcher: Dispatcher;
+}
+/**
+ * An in-memory core + dispatcher for tests. The dispatcher is **not started**
+ * (no timers) and defaults to an immediate three-attempt retry schedule so
+ * failure paths drain in a few ticks.
+ *
+ * @example
+ * ```ts
+ * import { createTestWebhooks, drainDeliveries } from "@xtandard/webhooks/testing";
+ *
+ * const { core, dispatcher } = createTestWebhooks();
+ * await core.createApplication({ key: "acme" });
+ * // … create an endpoint, publish, then:
+ * await drainDeliveries(dispatcher);
+ * ```
+ */
+declare function createTestWebhooks(options?: TestWebhooksOptions): TestWebhooks;
+/** Options for {@link createTestReceiver}. */
+interface TestReceiverOptions {
+  /**
+   * When set, each request is verified against this secret and its parsed
+   * envelope lands in `received`; an invalid signature answers 401.
+   */
+  secret?: string;
+  /** Fail (with `status`) the first N requests — exercises the retry path. */
+  failFirst?: number;
+  /** The failure status used while failing. Default `500`. */
+  status?: number;
+}
+/** A running test receiver. */
+interface TestReceiver {
+  /** The local URL to register as an endpoint. */
+  url: string;
+  /** Verified envelopes (only populated when `secret` was provided). */
+  received: WebhookEnvelope[];
+  /** Every request, verified or not, in arrival order. */
+  requests: {
+    headers: Record<string, string>;
+    body: string;
+  }[];
+  close(): Promise<void>;
+}
+/**
+ * Start a real local HTTP server that plays the receiving side of a webhook.
+ * Works under Bun and Node.
+ *
+ * @example
+ * ```ts
+ * const receiver = await createTestReceiver({ secret, failFirst: 2 });
+ * await core.createEndpoint("acme", { url: receiver.url });
+ * // … publish + drain; receiver.received now holds the verified envelopes.
+ * await receiver.close();
+ * ```
+ */
+declare function createTestReceiver(options?: TestReceiverOptions): Promise<TestReceiver>;
+/**
+ * Tick the dispatcher until a pass makes no attempts (or `maxTicks` is hit).
+ * Pair with an all-immediate retry schedule ({@link createTestWebhooks}'s
+ * default) so failed deliveries are due again on the very next tick.
+ */
+declare function drainDeliveries(dispatcher: Dispatcher, maxTicks?: number): Promise<void>;
+//#endregion
+export { TestReceiver, TestReceiverOptions, TestWebhooks, TestWebhooksOptions, createTestReceiver, createTestWebhooks, drainDeliveries };
+//# sourceMappingURL=testing.d.mts.map

package/dist/testing.mjs

@@ -0,0 +1,131 @@
+import { verify } from "./signing.mjs";
+import { o as createWebhooksCore } from "./core-CMpnmI5Q.mjs";
+import { n as createDispatcher } from "./dispatcher-Coubwrka.mjs";
+import { t as createMemoryStorage } from "./memory-BMsSSwqn.mjs";
+import { createServer } from "node:http";
+//#region src/testing.ts
+/**
+* Testing utilities — `@xtandard/webhooks/testing`.
+*
+* Everything a host app (or this package's own suite) needs to test its
+* webhook wiring without the network or timers:
+*
+* - {@link createTestWebhooks}: an in-memory core + a **not-started** dispatcher,
+*   driven manually via `dispatcher.tick()` / {@link drainDeliveries}.
+* - {@link createTestReceiver}: a real local HTTP server that records (and,
+*   given the secret, verifies) every delivery it receives — including
+*   programmable failures to exercise the retry path.
+*
+* @module
+*/
+/**
+* An in-memory core + dispatcher for tests. The dispatcher is **not started**
+* (no timers) and defaults to an immediate three-attempt retry schedule so
+* failure paths drain in a few ticks.
+*
+* @example
+* ```ts
+* import { createTestWebhooks, drainDeliveries } from "@xtandard/webhooks/testing";
+*
+* const { core, dispatcher } = createTestWebhooks();
+* await core.createApplication({ key: "acme" });
+* // … create an endpoint, publish, then:
+* await drainDeliveries(dispatcher);
+* ```
+*/
+function createTestWebhooks(options = {}) {
+	const storage = createMemoryStorage();
+	const { dispatcher: dispatcherOptions, ...coreOptions } = options;
+	const core = createWebhooksCore({
+		storage,
+		allowInsecureUrls: true,
+		...coreOptions,
+		dispatcher: {
+			retrySchedule: [
+				"0s",
+				"0s",
+				"0s"
+			],
+			...dispatcherOptions
+		}
+	});
+	return {
+		core,
+		storage,
+		dispatcher: createDispatcher(core)
+	};
+}
+/**
+* Start a real local HTTP server that plays the receiving side of a webhook.
+* Works under Bun and Node.
+*
+* @example
+* ```ts
+* const receiver = await createTestReceiver({ secret, failFirst: 2 });
+* await core.createEndpoint("acme", { url: receiver.url });
+* // … publish + drain; receiver.received now holds the verified envelopes.
+* await receiver.close();
+* ```
+*/
+async function createTestReceiver(options = {}) {
+	const received = [];
+	const requests = [];
+	let remainingFailures = options.failFirst ?? 0;
+	const server = createServer((req, res) => {
+		const chunks = [];
+		req.on("data", (chunk) => chunks.push(chunk));
+		req.on("end", () => {
+			(async () => {
+				const body = Buffer.concat(chunks).toString("utf8");
+				const headers = {};
+				for (const [name, value] of Object.entries(req.headers)) if (typeof value === "string") headers[name] = value;
+				requests.push({
+					headers,
+					body
+				});
+				if (remainingFailures > 0) {
+					remainingFailures--;
+					res.writeHead(options.status ?? 500, { "content-type": "text/plain" });
+					res.end("simulated failure");
+					return;
+				}
+				if (options.secret) try {
+					received.push(await verify({
+						payload: body,
+						headers,
+						secret: options.secret
+					}));
+				} catch {
+					res.writeHead(401, { "content-type": "text/plain" });
+					res.end("invalid signature");
+					return;
+				}
+				res.writeHead(200, { "content-type": "text/plain" });
+				res.end("ok");
+			})();
+		});
+	});
+	await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+	const address = server.address();
+	if (address === null || typeof address === "string") throw new Error("Test receiver failed to bind a port");
+	return {
+		url: `http://127.0.0.1:${address.port}/webhooks`,
+		received,
+		requests,
+		close: () => new Promise((resolve, reject) => {
+			server.close((err) => err ? reject(err) : resolve());
+		})
+	};
+}
+/**
+* Tick the dispatcher until a pass makes no attempts (or `maxTicks` is hit).
+* Pair with an all-immediate retry schedule ({@link createTestWebhooks}'s
+* default) so failed deliveries are due again on the very next tick.
+*/
+async function drainDeliveries(dispatcher, maxTicks = 25) {
+	for (let i = 0; i < maxTicks; i++) if (await dispatcher.tick() === 0) return;
+}
+//#endregion
+export { createTestReceiver, createTestWebhooks, drainDeliveries };
+
+//# sourceMappingURL=testing.mjs.map

package/dist/testing.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.mjs","names":[],"sources":["../src/testing.ts"],"sourcesContent":["/**\n * Testing utilities — `@xtandard/webhooks/testing`.\n *\n * Everything a host app (or this package's own suite) needs to test its\n * webhook wiring without the network or timers:\n *\n * - {@link createTestWebhooks}: an in-memory core + a **not-started** dispatcher,\n *   driven manually via `dispatcher.tick()` / {@link drainDeliveries}.\n * - {@link createTestReceiver}: a real local HTTP server that records (and,\n *   given the secret, verifies) every delivery it receives — including\n *   programmable failures to exercise the retry path.\n *\n * @module\n */\n\nimport { createServer, type IncomingMessage, type Server, type ServerResponse } from \"node:http\";\nimport { createWebhooksCore, type WebhooksCore, type WebhooksCoreOptions } from \"./core.ts\";\nimport { createDispatcher, type Dispatcher, type DispatcherOptions } from \"./dispatcher.ts\";\nimport type { WebhookEnvelope } from \"./schema.ts\";\nimport { verify } from \"./signing.ts\";\nimport { createMemoryStorage, type MemoryWebhooksStorage } from \"./storage/memory.ts\";\n\n/** Options for {@link createTestWebhooks}. */\nexport interface TestWebhooksOptions extends Omit<WebhooksCoreOptions, \"storage\" | \"queueStorage\"> {\n  /** Dispatcher config; a fast all-immediate retry schedule is the default. */\n  dispatcher?: DispatcherOptions;\n}\n\n/** Result of {@link createTestWebhooks}. */\nexport interface TestWebhooks {\n  core: WebhooksCore;\n  storage: MemoryWebhooksStorage;\n  /** NOT started — drive it with `tick()` or {@link drainDeliveries}. */\n  dispatcher: Dispatcher;\n}\n\n/**\n * An in-memory core + dispatcher for tests. The dispatcher is **not started**\n * (no timers) and defaults to an immediate three-attempt retry schedule so\n * failure paths drain in a few ticks.\n *\n * @example\n * ```ts\n * import { createTestWebhooks, drainDeliveries } from \"@xtandard/webhooks/testing\";\n *\n * const { core, dispatcher } = createTestWebhooks();\n * await core.createApplication({ key: \"acme\" });\n * // … create an endpoint, publish, then:\n * await drainDeliveries(dispatcher);\n * ```\n */\nexport function createTestWebhooks(options: TestWebhooksOptions = {}): TestWebhooks {\n  const storage = createMemoryStorage();\n  const { dispatcher: dispatcherOptions, ...coreOptions } = options;\n  const core = createWebhooksCore({\n    storage,\n    allowInsecureUrls: true, // test receivers are local http\n    ...coreOptions,\n    dispatcher: {\n      retrySchedule: [\"0s\", \"0s\", \"0s\"],\n      ...dispatcherOptions,\n    },\n  });\n  const dispatcher = createDispatcher(core);\n  return { core, storage, dispatcher };\n}\n\n/** Options for {@link createTestReceiver}. */\nexport interface TestReceiverOptions {\n  /**\n   * When set, each request is verified against this secret and its parsed\n   * envelope lands in `received`; an invalid signature answers 401.\n   */\n  secret?: string;\n  /** Fail (with `status`) the first N requests — exercises the retry path. */\n  failFirst?: number;\n  /** The failure status used while failing. Default `500`. */\n  status?: number;\n}\n\n/** A running test receiver. */\nexport interface TestReceiver {\n  /** The local URL to register as an endpoint. */\n  url: string;\n  /** Verified envelopes (only populated when `secret` was provided). */\n  received: WebhookEnvelope[];\n  /** Every request, verified or not, in arrival order. */\n  requests: { headers: Record<string, string>; body: string }[];\n  close(): Promise<void>;\n}\n\n/**\n * Start a real local HTTP server that plays the receiving side of a webhook.\n * Works under Bun and Node.\n *\n * @example\n * ```ts\n * const receiver = await createTestReceiver({ secret, failFirst: 2 });\n * await core.createEndpoint(\"acme\", { url: receiver.url });\n * // … publish + drain; receiver.received now holds the verified envelopes.\n * await receiver.close();\n * ```\n */\nexport async function createTestReceiver(options: TestReceiverOptions = {}): Promise<TestReceiver> {\n  const received: WebhookEnvelope[] = [];\n  const requests: { headers: Record<string, string>; body: string }[] = [];\n  let remainingFailures = options.failFirst ?? 0;\n\n  const server: Server = createServer((req: IncomingMessage, res: ServerResponse) => {\n    const chunks: Buffer[] = [];\n    req.on(\"data\", (chunk: Buffer) => chunks.push(chunk));\n    req.on(\"end\", () => {\n      void (async () => {\n        const body = Buffer.concat(chunks).toString(\"utf8\");\n        const headers: Record<string, string> = {};\n        for (const [name, value] of Object.entries(req.headers)) {\n          if (typeof value === \"string\") headers[name] = value;\n        }\n        requests.push({ headers, body });\n\n        if (remainingFailures > 0) {\n          remainingFailures--;\n          res.writeHead(options.status ?? 500, { \"content-type\": \"text/plain\" });\n          res.end(\"simulated failure\");\n          return;\n        }\n\n        if (options.secret) {\n          try {\n            received.push(await verify({ payload: body, headers, secret: options.secret }));\n          } catch {\n            res.writeHead(401, { \"content-type\": \"text/plain\" });\n            res.end(\"invalid signature\");\n            return;\n          }\n        }\n        res.writeHead(200, { \"content-type\": \"text/plain\" });\n        res.end(\"ok\");\n      })();\n    });\n  });\n\n  await new Promise<void>((resolve) => server.listen(0, \"127.0.0.1\", resolve));\n  const address = server.address();\n  if (address === null || typeof address === \"string\") {\n    throw new Error(\"Test receiver failed to bind a port\");\n  }\n\n  return {\n    url: `http://127.0.0.1:${address.port}/webhooks`,\n    received,\n    requests,\n    close: () =>\n      new Promise<void>((resolve, reject) => {\n        server.close((err) => (err ? reject(err) : resolve()));\n      }),\n  };\n}\n\n/**\n * Tick the dispatcher until a pass makes no attempts (or `maxTicks` is hit).\n * Pair with an all-immediate retry schedule ({@link createTestWebhooks}'s\n * default) so failed deliveries are due again on the very next tick.\n */\nexport async function drainDeliveries(dispatcher: Dispatcher, maxTicks = 25): Promise<void> {\n  for (let i = 0; i < maxTicks; i++) {\n    if ((await dispatcher.tick()) === 0) return;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmDA,SAAgB,mBAAmB,UAA+B,CAAC,GAAiB;CAClF,MAAM,UAAU,oBAAoB;CACpC,MAAM,EAAE,YAAY,mBAAmB,GAAG,gBAAgB;CAC1D,MAAM,OAAO,mBAAmB;EAC9B;EACA,mBAAmB;EACnB,GAAG;EACH,YAAY;GACV,eAAe;IAAC;IAAM;IAAM;GAAI;GAChC,GAAG;EACL;CACF,CAAC;CAED,OAAO;EAAE;EAAM;EAAS,YADL,iBAAiB,IACH;CAAE;AACrC;;;;;;;;;;;;;AAsCA,eAAsB,mBAAmB,UAA+B,CAAC,GAA0B;CACjG,MAAM,WAA8B,CAAC;CACrC,MAAM,WAAgE,CAAC;CACvE,IAAI,oBAAoB,QAAQ,aAAa;CAE7C,MAAM,SAAiB,cAAc,KAAsB,QAAwB;EACjF,MAAM,SAAmB,CAAC;EAC1B,IAAI,GAAG,SAAS,UAAkB,OAAO,KAAK,KAAK,CAAC;EACpD,IAAI,GAAG,aAAa;GAClB,CAAM,YAAY;IAChB,MAAM,OAAO,OAAO,OAAO,MAAM,EAAE,SAAS,MAAM;IAClD,MAAM,UAAkC,CAAC;IACzC,KAAK,MAAM,CAAC,MAAM,UAAU,OAAO,QAAQ,IAAI,OAAO,GACpD,IAAI,OAAO,UAAU,UAAU,QAAQ,QAAQ;IAEjD,SAAS,KAAK;KAAE;KAAS;IAAK,CAAC;IAE/B,IAAI,oBAAoB,GAAG;KACzB;KACA,IAAI,UAAU,QAAQ,UAAU,KAAK,EAAE,gBAAgB,aAAa,CAAC;KACrE,IAAI,IAAI,mBAAmB;KAC3B;IACF;IAEA,IAAI,QAAQ,QACV,IAAI;KACF,SAAS,KAAK,MAAM,OAAO;MAAE,SAAS;MAAM;MAAS,QAAQ,QAAQ;KAAO,CAAC,CAAC;IAChF,QAAQ;KACN,IAAI,UAAU,KAAK,EAAE,gBAAgB,aAAa,CAAC;KACnD,IAAI,IAAI,mBAAmB;KAC3B;IACF;IAEF,IAAI,UAAU,KAAK,EAAE,gBAAgB,aAAa,CAAC;IACnD,IAAI,IAAI,IAAI;GACd,GAAG;EACL,CAAC;CACH,CAAC;CAED,MAAM,IAAI,SAAe,YAAY,OAAO,OAAO,GAAG,aAAa,OAAO,CAAC;CAC3E,MAAM,UAAU,OAAO,QAAQ;CAC/B,IAAI,YAAY,QAAQ,OAAO,YAAY,UACzC,MAAM,IAAI,MAAM,qCAAqC;CAGvD,OAAO;EACL,KAAK,oBAAoB,QAAQ,KAAK;EACtC;EACA;EACA,aACE,IAAI,SAAe,SAAS,WAAW;GACrC,OAAO,OAAO,QAAS,MAAM,OAAO,GAAG,IAAI,QAAQ,CAAE;EACvD,CAAC;CACL;AACF;;;;;;AAOA,eAAsB,gBAAgB,YAAwB,WAAW,IAAmB;CAC1F,KAAK,IAAI,IAAI,GAAG,IAAI,UAAU,KAC5B,IAAK,MAAM,WAAW,KAAK,MAAO,GAAG;AAEzC"}