better-ship 0.11.0 → 0.13.0

package/dist/testing/outbox-repository.d.ts

@@ -0,0 +1,44 @@
+import { G as DomainEvent } from "../index-B5O6mNjZ.js";
+import { A as IOutboxRepository } from "../index-DG4jkwad.js";
+//#region src/infrastructure/testing/outbox-repository-contract.d.ts
+/** Stored fields observed by the adapter contract, independent of a database library. */
+export type OutboxContractRow = {
+  readonly id: string;
+  readonly payload: DomainEvent;
+  readonly createdAt: Date;
+  readonly availableAt: Date;
+  readonly attempts: number;
+  readonly claimToken: string | null;
+  readonly claimExpiresAt: Date | null;
+  readonly publishedAt: Date | null;
+  readonly failedAt: Date | null;
+  readonly lastError: string | null;
+};
+/** Fixture input for one stored row; omitted fields use fresh, due defaults. */
+export type OutboxContractSeed = {
+  readonly id: string;
+} & Partial<Omit<OutboxContractRow, 'id' | 'payload'>>;
+/**
+ * An isolated database fixture. Configure a 60-second lease, 1-second base delay, and 60-second cap.
+ * The clock starts at a whole second. Each test receives fresh tables and an independent clock.
+ */
+export interface OutboxRepositoryContractFixture {
+  readonly repository: IOutboxRepository;
+  now(this: void): Date;
+  advance(ms: number): void;
+  seed(rows: ReadonlyArray<OutboxContractSeed>): Promise<void>;
+  /** Return rows ordered by id. */
+  rows(): Promise<ReadonlyArray<OutboxContractRow>>;
+  seedReceipts(rows: ReadonlyArray<{
+    readonly messageId: string;
+    readonly processedAt: Date;
+  }>): Promise<void>;
+  receipts(): Promise<ReadonlyArray<{
+    readonly messageId: string;
+    readonly processedAt: Date;
+  }>>;
+}
+/** Register the shared repository contract with an isolated fixture per test; run tests serially if they share a database. */
+export declare function outboxRepositoryContract(test: (name: string, run: () => Promise<void>) => void, create: () => Promise<OutboxRepositoryContractFixture>): void;
+//#endregion
+//# sourceMappingURL=outbox-repository.d.ts.map

package/dist/testing/outbox-repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox-repository.d.ts","names":[],"sources":["../../src/infrastructure/testing/outbox-repository-contract.ts"],"mappings":";;;;YAMY;WACD;WACA,SAAS;WACT,WAAW;WACX,aAAa;WACb;WACA;WACA,gBAAgB;WAChB,aAAa;WACb,UAAU;WACV;;;YAIC;WAAgC;IAAe,QACzD,KAAK;;;;;iBAOU;WACN,YAAY;EACrB,IAAI,aAAa;EACjB,QAAQ;EACR,KAAK,MAAM,cAAc,sBAAsB;;EAE/C,QAAQ,QAAQ,cAAc;EAC9B,aACE,MAAM;aAAyB;aAA4B,aAAa;OACvE;EACH,YAAY,QAAQ;aAAyB;aAA4B,aAAa;;;;wBAIxE,yBACd,OAAO,cAAc,WAAW,wBAChC,cAAc,QAAQ"}

package/dist/testing/outbox-repository.js

@@ -0,0 +1,206 @@
+import { deepStrictEqual, equal, notEqual, ok } from "node:assert/strict";
+
+//#region src/infrastructure/testing/outbox-repository-contract.ts
+/** Register the shared repository contract with an isolated fixture per test; run tests serially if they share a database. */
+function outboxRepositoryContract(test, create) {
+	test("claims due rows with one token and incremented attempts", async () => {
+		const f = await create();
+		await f.seed([{ id: "a" }, {
+			id: "b",
+			attempts: 3
+		}]);
+		const claim = await f.repository.claimPending(50);
+		deepStrictEqual(claim.messages.map((row) => row.attempts), [1, 4]);
+		ok(claim.token.length > 0);
+		deepStrictEqual((await f.rows()).map((row) => row.claimToken), [claim.token, claim.token]);
+	});
+	test("skips terminal, future, and leased rows", async () => {
+		const f = await create();
+		const future = new Date(f.now().getTime() + 6e4);
+		await f.seed([
+			{
+				id: "published",
+				publishedAt: f.now()
+			},
+			{
+				id: "failed",
+				failedAt: f.now()
+			},
+			{
+				id: "future",
+				availableAt: future
+			},
+			{
+				id: "leased",
+				claimToken: "old",
+				claimExpiresAt: future
+			},
+			{ id: "due" }
+		]);
+		const claim = await f.repository.claimPending(50);
+		deepStrictEqual(claim.messages.map((row) => row.payload.id), ["due"]);
+	});
+	test("limits a claim and takes the oldest due row first", async () => {
+		const f = await create();
+		await f.seed([{ id: "new" }, {
+			id: "old",
+			availableAt: /* @__PURE__ */ new Date(f.now().getTime() - 1e3)
+		}]);
+		const claim = await f.repository.claimPending(1);
+		deepStrictEqual(claim.messages.map((row) => row.payload.id), ["old"]);
+	});
+	test("concurrent claims never share a row", async () => {
+		const f = await create();
+		await f.seed([{ id: "a" }, { id: "b" }]);
+		const ids = (await Promise.all([f.repository.claimPending(1), f.repository.claimPending(1)])).flatMap((claim) => claim.messages.map((row) => row.payload.id));
+		equal(ids.length, 2);
+		equal(new Set(ids).size, 2);
+	});
+	test("reclaims an expired lease and increments attempts again", async () => {
+		const f = await create();
+		await f.seed([{ id: "a" }]);
+		const first = await f.repository.claimPending(1);
+		f.advance(6e4);
+		const second = await f.repository.claimPending(1);
+		notEqual(first.token, second.token);
+		deepStrictEqual(second.messages.map((row) => row.attempts), [2]);
+	});
+	for (const operation of [
+		"publish",
+		"release",
+		"fail"
+	]) test(`a stale claim cannot ${operation} a row`, async () => {
+		const f = await create();
+		await f.seed([{ id: "a" }]);
+		const old = await f.repository.claimPending(1);
+		f.advance(6e4);
+		await f.repository.claimPending(1);
+		const before = await f.rows();
+		if (operation === "publish") await f.repository.markPublished(old, old.messages);
+		if (operation === "release") await f.repository.releaseClaim(old, old.messages);
+		if (operation === "fail") await f.repository.deadLetter(old, old.messages, "terminal", "denied");
+		deepStrictEqual(await f.rows(), before);
+	});
+	test("publishes only the supplied subset and clears its lease", async () => {
+		const f = await create();
+		await f.seed([{ id: "a" }, { id: "b" }]);
+		const claim = await f.repository.claimPending(50);
+		await f.repository.markPublished(claim, claim.messages.slice(0, 1));
+		deepStrictEqual((await f.rows()).map((row) => ({
+			publishedAt: row.publishedAt,
+			token: row.claimToken
+		})), [{
+			publishedAt: f.now(),
+			token: null
+		}, {
+			publishedAt: null,
+			token: claim.token
+		}]);
+	});
+	test("releases only the supplied subset with per-row capped backoff", async () => {
+		const f = await create();
+		await f.seed([
+			{ id: "a" },
+			{
+				id: "b",
+				attempts: 2
+			},
+			{
+				id: "c",
+				attempts: 8
+			},
+			{ id: "d" }
+		]);
+		const claim = await f.repository.claimPending(50);
+		await f.repository.releaseClaim(claim, claim.messages.slice(0, 3));
+		deepStrictEqual((await f.rows()).map((row) => [row.availableAt.getTime() - f.now().getTime(), row.claimToken]), [
+			[1e3, null],
+			[4e3, null],
+			[6e4, null],
+			[0, claim.token]
+		]);
+	});
+	test("dead-letters only the supplied subset and keeps its payload", async () => {
+		const f = await create();
+		await f.seed([{ id: "a" }, { id: "b" }]);
+		const claim = await f.repository.claimPending(50);
+		await f.repository.deadLetter(claim, claim.messages.slice(0, 1), "oversized", "too large");
+		deepStrictEqual((await f.rows()).map((row) => [
+			row.payload.id,
+			row.lastError,
+			row.claimToken
+		]), [[
+			"a",
+			"oversized: too large",
+			null
+		], [
+			"b",
+			null,
+			claim.token
+		]]);
+	});
+	for (const operation of [
+		"publish",
+		"release",
+		"fail"
+	]) test(`settles a 120-row claim through ${operation}`, async () => {
+		const f = await create();
+		await f.seed(Array.from({ length: 120 }, (_, i) => ({ id: String(i) })));
+		const claim = await f.repository.claimPending(120);
+		equal(claim.messages.length, 120);
+		if (operation === "publish") await f.repository.markPublished(claim, claim.messages);
+		if (operation === "release") await f.repository.releaseClaim(claim, claim.messages);
+		if (operation === "fail") await f.repository.deadLetter(claim, claim.messages, "terminal", "denied");
+		ok((await f.rows()).every((row) => row.claimToken === null));
+	});
+	for (const category of ["published", "failed"]) test(`deletes only old ${category} events within the batch limit`, async () => {
+		const f = await create();
+		const old = /* @__PURE__ */ new Date(f.now().getTime() - 1e3);
+		const dates = category === "published" ? { publishedAt: old } : { failedAt: old };
+		const atCutoff = category === "published" ? { publishedAt: f.now() } : { failedAt: f.now() };
+		await f.seed([
+			{
+				id: "old-a",
+				...dates
+			},
+			{
+				id: "old-b",
+				...dates
+			},
+			{
+				id: "cutoff",
+				...atCutoff
+			},
+			{ id: "pending" }
+		]);
+		const remove = category === "published" ? f.repository.deletePublishedBefore.bind(f.repository) : f.repository.deleteFailedBefore.bind(f.repository);
+		equal(await remove(f.now(), 1), 1);
+		equal(await remove(f.now(), 50), 1);
+		deepStrictEqual((await f.rows()).map((row) => row.id), ["cutoff", "pending"]);
+	});
+	test("deletes only old receipts within the batch limit", async () => {
+		const f = await create();
+		const old = /* @__PURE__ */ new Date(f.now().getTime() - 1e3);
+		await f.seedReceipts([
+			{
+				messageId: "old-a",
+				processedAt: old
+			},
+			{
+				messageId: "old-b",
+				processedAt: old
+			},
+			{
+				messageId: "cutoff",
+				processedAt: f.now()
+			}
+		]);
+		equal(await f.repository.deleteReceiptsBefore(f.now(), 1), 1);
+		equal(await f.repository.deleteReceiptsBefore(f.now(), 50), 1);
+		deepStrictEqual((await f.receipts()).map((row) => row.messageId), ["cutoff"]);
+	});
+}
+
+//#endregion
+export { outboxRepositoryContract };
+//# sourceMappingURL=outbox-repository.js.map

package/dist/testing/outbox-repository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox-repository.js","names":[],"sources":["../../src/infrastructure/testing/outbox-repository-contract.ts"],"sourcesContent":["import { deepStrictEqual, equal, notEqual, ok } from 'node:assert/strict'\n\nimport type { IOutboxRepository } from '@/application'\nimport type { DomainEvent } from '@/core'\n\n/** Stored fields observed by the adapter contract, independent of a database library. */\nexport type OutboxContractRow = {\n  readonly id: string\n  readonly payload: DomainEvent\n  readonly createdAt: Date\n  readonly availableAt: Date\n  readonly attempts: number\n  readonly claimToken: string | null\n  readonly claimExpiresAt: Date | null\n  readonly publishedAt: Date | null\n  readonly failedAt: Date | null\n  readonly lastError: string | null\n}\n\n/** Fixture input for one stored row; omitted fields use fresh, due defaults. */\nexport type OutboxContractSeed = { readonly id: string } & Partial<\n  Omit<OutboxContractRow, 'id' | 'payload'>\n>\n\n/**\n * An isolated database fixture. Configure a 60-second lease, 1-second base delay, and 60-second cap.\n * The clock starts at a whole second. Each test receives fresh tables and an independent clock.\n */\nexport interface OutboxRepositoryContractFixture {\n  readonly repository: IOutboxRepository\n  now(this: void): Date\n  advance(ms: number): void\n  seed(rows: ReadonlyArray<OutboxContractSeed>): Promise<void>\n  /** Return rows ordered by id. */\n  rows(): Promise<ReadonlyArray<OutboxContractRow>>\n  seedReceipts(\n    rows: ReadonlyArray<{ readonly messageId: string; readonly processedAt: Date }>,\n  ): Promise<void>\n  receipts(): Promise<ReadonlyArray<{ readonly messageId: string; readonly processedAt: Date }>>\n}\n\n/** Register the shared repository contract with an isolated fixture per test; run tests serially if they share a database. */\nexport function outboxRepositoryContract(\n  test: (name: string, run: () => Promise<void>) => void,\n  create: () => Promise<OutboxRepositoryContractFixture>,\n): void {\n  test('claims due rows with one token and incremented attempts', async () => {\n    const f = await create()\n    await f.seed([{ id: 'a' }, { id: 'b', attempts: 3 }])\n    const claim = await f.repository.claimPending(50)\n    deepStrictEqual(\n      claim.messages.map((row) => row.attempts),\n      [1, 4],\n    )\n    ok(claim.token.length > 0)\n    deepStrictEqual(\n      (await f.rows()).map((row) => row.claimToken),\n      [claim.token, claim.token],\n    )\n  })\n\n  test('skips terminal, future, and leased rows', async () => {\n    const f = await create()\n    const future = new Date(f.now().getTime() + 60_000)\n    await f.seed([\n      { id: 'published', publishedAt: f.now() },\n      { id: 'failed', failedAt: f.now() },\n      { id: 'future', availableAt: future },\n      { id: 'leased', claimToken: 'old', claimExpiresAt: future },\n      { id: 'due' },\n    ])\n    const claim = await f.repository.claimPending(50)\n    deepStrictEqual(\n      claim.messages.map((row) => row.payload.id),\n      ['due'],\n    )\n  })\n\n  test('limits a claim and takes the oldest due row first', async () => {\n    const f = await create()\n    await f.seed([{ id: 'new' }, { id: 'old', availableAt: new Date(f.now().getTime() - 1_000) }])\n    const claim = await f.repository.claimPending(1)\n    deepStrictEqual(\n      claim.messages.map((row) => row.payload.id),\n      ['old'],\n    )\n  })\n\n  test('concurrent claims never share a row', async () => {\n    const f = await create()\n    await f.seed([{ id: 'a' }, { id: 'b' }])\n    const claims = await Promise.all([f.repository.claimPending(1), f.repository.claimPending(1)])\n    const ids = claims.flatMap((claim) => claim.messages.map((row) => row.payload.id))\n    equal(ids.length, 2)\n    equal(new Set(ids).size, 2)\n  })\n\n  test('reclaims an expired lease and increments attempts again', async () => {\n    const f = await create()\n    await f.seed([{ id: 'a' }])\n    const first = await f.repository.claimPending(1)\n    f.advance(60_000)\n    const second = await f.repository.claimPending(1)\n    notEqual(first.token, second.token)\n    deepStrictEqual(\n      second.messages.map((row) => row.attempts),\n      [2],\n    )\n  })\n\n  for (const operation of ['publish', 'release', 'fail']) {\n    test(`a stale claim cannot ${operation} a row`, async () => {\n      const f = await create()\n      await f.seed([{ id: 'a' }])\n      const old = await f.repository.claimPending(1)\n      f.advance(60_000)\n      await f.repository.claimPending(1)\n      const before = await f.rows()\n      if (operation === 'publish') await f.repository.markPublished(old, old.messages)\n      if (operation === 'release') await f.repository.releaseClaim(old, old.messages)\n      if (operation === 'fail')\n        await f.repository.deadLetter(old, old.messages, 'terminal', 'denied')\n      deepStrictEqual(await f.rows(), before)\n    })\n  }\n\n  test('publishes only the supplied subset and clears its lease', async () => {\n    const f = await create()\n    await f.seed([{ id: 'a' }, { id: 'b' }])\n    const claim = await f.repository.claimPending(50)\n    await f.repository.markPublished(claim, claim.messages.slice(0, 1))\n    deepStrictEqual(\n      (await f.rows()).map((row) => ({ publishedAt: row.publishedAt, token: row.claimToken })),\n      [\n        { publishedAt: f.now(), token: null },\n        { publishedAt: null, token: claim.token },\n      ],\n    )\n  })\n\n  test('releases only the supplied subset with per-row capped backoff', async () => {\n    const f = await create()\n    await f.seed([{ id: 'a' }, { id: 'b', attempts: 2 }, { id: 'c', attempts: 8 }, { id: 'd' }])\n    const claim = await f.repository.claimPending(50)\n    await f.repository.releaseClaim(claim, claim.messages.slice(0, 3))\n    deepStrictEqual(\n      (await f.rows()).map((row) => [\n        row.availableAt.getTime() - f.now().getTime(),\n        row.claimToken,\n      ]),\n      [\n        [1000, null],\n        [4000, null],\n        [60000, null],\n        [0, claim.token],\n      ],\n    )\n  })\n\n  test('dead-letters only the supplied subset and keeps its payload', async () => {\n    const f = await create()\n    await f.seed([{ id: 'a' }, { id: 'b' }])\n    const claim = await f.repository.claimPending(50)\n    await f.repository.deadLetter(claim, claim.messages.slice(0, 1), 'oversized', 'too large')\n    deepStrictEqual(\n      (await f.rows()).map((row) => [row.payload.id, row.lastError, row.claimToken]),\n      [\n        ['a', 'oversized: too large', null],\n        ['b', null, claim.token],\n      ],\n    )\n  })\n\n  for (const operation of ['publish', 'release', 'fail']) {\n    test(`settles a 120-row claim through ${operation}`, async () => {\n      const f = await create()\n      await f.seed(Array.from({ length: 120 }, (_, i) => ({ id: String(i) })))\n      const claim = await f.repository.claimPending(120)\n      equal(claim.messages.length, 120)\n      if (operation === 'publish') await f.repository.markPublished(claim, claim.messages)\n      if (operation === 'release') await f.repository.releaseClaim(claim, claim.messages)\n      if (operation === 'fail')\n        await f.repository.deadLetter(claim, claim.messages, 'terminal', 'denied')\n      ok((await f.rows()).every((row) => row.claimToken === null))\n    })\n  }\n\n  for (const category of ['published', 'failed']) {\n    test(`deletes only old ${category} events within the batch limit`, async () => {\n      const f = await create()\n      const old = new Date(f.now().getTime() - 1000)\n      const dates = category === 'published' ? { publishedAt: old } : { failedAt: old }\n      const atCutoff = category === 'published' ? { publishedAt: f.now() } : { failedAt: f.now() }\n      await f.seed([\n        { id: 'old-a', ...dates },\n        { id: 'old-b', ...dates },\n        { id: 'cutoff', ...atCutoff },\n        { id: 'pending' },\n      ])\n      const remove =\n        category === 'published'\n          ? f.repository.deletePublishedBefore.bind(f.repository)\n          : f.repository.deleteFailedBefore.bind(f.repository)\n      equal(await remove(f.now(), 1), 1)\n      equal(await remove(f.now(), 50), 1)\n      deepStrictEqual(\n        (await f.rows()).map((row) => row.id),\n        ['cutoff', 'pending'],\n      )\n    })\n  }\n\n  test('deletes only old receipts within the batch limit', async () => {\n    const f = await create()\n    const old = new Date(f.now().getTime() - 1000)\n    await f.seedReceipts([\n      { messageId: 'old-a', processedAt: old },\n      { messageId: 'old-b', processedAt: old },\n      { messageId: 'cutoff', processedAt: f.now() },\n    ])\n    equal(await f.repository.deleteReceiptsBefore(f.now(), 1), 1)\n    equal(await f.repository.deleteReceiptsBefore(f.now(), 50), 1)\n    deepStrictEqual(\n      (await f.receipts()).map((row) => row.messageId),\n      ['cutoff'],\n    )\n  })\n}\n"],"mappings":"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"}

package/dist/{webhook-verification-BQ9qZnVK.js → webhook-verification-CeXUJXVP.js}

@@ -1,4 +1,4 @@
-import { Q as AppError } from "./core-DG_cC8YT.js";
+import { $ as AppError } from "./core-BiqdOMwU.js";
 
 //#region src/infrastructure/http/webhook-verification.ts
 /** A webhook cannot be trusted or parsed. The HTTP handler logs the rejection once. */
@@ -15,4 +15,4 @@ var WebhookVerificationError = class extends AppError {
 
 //#endregion
 export { WebhookVerificationError as t };
-//# sourceMappingURL=webhook-verification-BQ9qZnVK.js.map
+//# sourceMappingURL=webhook-verification-CeXUJXVP.js.map

package/dist/{webhook-verification-BQ9qZnVK.js.map → webhook-verification-CeXUJXVP.js.map}

@@ -1 +1 @@
-{"version":3,"file":"webhook-verification-BQ9qZnVK.js","names":[],"sources":["../src/infrastructure/http/webhook-verification.ts"],"sourcesContent":["import { AppError } from '@/core'\n\n/** A webhook cannot be trusted or parsed. The HTTP handler logs the rejection once. */\nexport class WebhookVerificationError extends AppError {\n  readonly _tag = 'WebhookVerificationError'\n  readonly classification = 'terminal'\n\n  /** Keep secrets and payload details out of the public message. */\n  constructor(\n    readonly reason: 'missing_headers' | 'invalid_signature' | 'invalid_payload',\n    cause?: unknown,\n  ) {\n    super(`Webhook rejected: ${reason}`, { cause })\n  }\n}\n\n/** A verified event, an ignored event, or an invalid request. */\nexport type WebhookVerification<Event> =\n  | { readonly outcome: 'event'; readonly event: Event }\n  | { readonly outcome: 'ignored'; readonly type: string }\n  | { readonly outcome: 'rejected'; readonly error: WebhookVerificationError }\n\n/** The provider owns signature verification, timestamp tolerance, and payload parsing. */\nexport interface WebhookVerifier<Event> {\n  /** Verify the exact body before parsing it. Return invalid requests; throw operational failures. */\n  verify(body: string, headers: Headers): Promise<WebhookVerification<Event>>\n}\n"],"mappings":";;;;AAGA,IAAa,2BAAb,cAA8C,SAAS;CAM1C;CALX,AAAS,OAAO;CAChB,AAAS,iBAAiB;;CAG1B,YACE,AAAS,QACT,OACA;EACA,MAAM,qBAAqB,UAAU,EAAE,MAAM,CAAC;EAHrC;CAIX;AACF"}
+{"version":3,"file":"webhook-verification-CeXUJXVP.js","names":[],"sources":["../src/infrastructure/http/webhook-verification.ts"],"sourcesContent":["import { AppError } from '@/core'\n\n/** A webhook cannot be trusted or parsed. The HTTP handler logs the rejection once. */\nexport class WebhookVerificationError extends AppError {\n  readonly _tag = 'WebhookVerificationError'\n  readonly classification = 'terminal'\n\n  /** Keep secrets and payload details out of the public message. */\n  constructor(\n    readonly reason: 'missing_headers' | 'invalid_signature' | 'invalid_payload',\n    cause?: unknown,\n  ) {\n    super(`Webhook rejected: ${reason}`, { cause })\n  }\n}\n\n/** A verified event, an ignored event, or an invalid request. */\nexport type WebhookVerification<Event> =\n  | { readonly outcome: 'event'; readonly event: Event }\n  | { readonly outcome: 'ignored'; readonly type: string }\n  | { readonly outcome: 'rejected'; readonly error: WebhookVerificationError }\n\n/** The provider owns signature verification, timestamp tolerance, and payload parsing. */\nexport interface WebhookVerifier<Event> {\n  /** Verify the exact body before parsing it. Return invalid requests; throw operational failures. */\n  verify(body: string, headers: Headers): Promise<WebhookVerification<Event>>\n}\n"],"mappings":";;;;AAGA,IAAa,2BAAb,cAA8C,SAAS;CAM1C;CALX,AAAS,OAAO;CAChB,AAAS,iBAAiB;;CAG1B,YACE,AAAS,QACT,OACA;EACA,MAAM,qBAAqB,UAAU,EAAE,MAAM,CAAC;EAHrC;CAIX;AACF"}

package/dist/{webhook-verification-sZtwTI5n.d.ts → webhook-verification-CyBoERFz.d.ts}

@@ -1,4 +1,4 @@
-import { Ut as AppError } from "./index-Bl0K1RQW.js";
+import { Wt as AppError } from "./index-B5O6mNjZ.js";
 //#region src/infrastructure/http/webhook-verification.d.ts
 /** A webhook cannot be trusted or parsed. The HTTP handler logs the rejection once. */
 declare class WebhookVerificationError extends AppError {
@@ -26,4 +26,4 @@ interface WebhookVerifier<Event> {
 }
 //#endregion
 export { WebhookVerificationError as n, WebhookVerifier as r, WebhookVerification as t };
-//# sourceMappingURL=webhook-verification-sZtwTI5n.d.ts.map
+//# sourceMappingURL=webhook-verification-CyBoERFz.d.ts.map

package/dist/{webhook-verification-sZtwTI5n.d.ts.map → webhook-verification-CyBoERFz.d.ts.map}

@@ -1 +1 @@
-{"version":3,"file":"webhook-verification-sZtwTI5n.d.ts","names":[],"sources":["../src/infrastructure/http/webhook-verification.ts"],"mappings":";;;cAGa,iCAAiC;WAMjC;WALF;WACA;;EAGT,YACW,qEACT;;;KAOQ,oBAAoB;WACjB;WAA2B,OAAO;;WAClC;WAA6B;;WAC7B;WAA8B,OAAO;;;UAGnC,gBAAgB;;EAE/B,OAAO,cAAc,SAAS,UAAU,QAAQ,oBAAoB"}
+{"version":3,"file":"webhook-verification-CyBoERFz.d.ts","names":[],"sources":["../src/infrastructure/http/webhook-verification.ts"],"mappings":";;;cAGa,iCAAiC;WAMjC;WALF;WACA;;EAGT,YACW,qEACT;;;KAOQ,oBAAoB;WACjB;WAA2B,OAAO;;WAClC;WAA6B;;WAC7B;WAA8B,OAAO;;;UAGnC,gBAAgB;;EAE/B,OAAO,cAAc,SAAS,UAAU,QAAQ,oBAAoB"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://www.schemastore.org/package.json",
   "name": "better-ship",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Foundation for applications on Cloudflare Workers: logger, errors, message bus, infrastructure adapters, and UI primitives",
   "license": "Apache-2.0",
   "repository": {
@@ -32,6 +32,7 @@
     "./resend": "./dist/resend.js",
     "./tanstack": "./dist/tanstack.js",
     "./tanstack/server": "./dist/tanstack/server.js",
+    "./testing/outbox-repository": "./dist/testing/outbox-repository.js",
     "./ui": "./dist/ui.js",
     "./package.json": "./package.json"
   },
@@ -48,16 +49,25 @@
     "@better-auth/stripe": "^1.7.4",
     "@cloudflare/vitest-plugin": "^1.1.7",
     "@cloudflare/workers-types": "5.20260911.1",
+    "@posthog/react": "^1.10.6",
+    "@sentry/cloudflare": "^10.74.0",
+    "@sentry/tanstackstart-react": "^10.74.0",
     "@tanstack/react-router": "^1.170.35",
     "@tanstack/react-start": "^1.168.52",
     "@tanstack/start-client-core": "^1.170.29",
     "@tanstack/start-storage-context": "^1.167.31",
     "@types/node": "^26.5.1",
+    "@types/react": "^19.3.0",
+    "@vitest/browser-playwright": "^5.0.0",
     "auth": "^1.7.4",
     "better-auth": "^1.7.4",
     "drizzle-kit": "^0.31.10",
     "drizzle-orm": "^0.45.2",
+    "playwright": "^1.63.0",
     "postgres": "^3.4.9",
+    "posthog-js": "^1.430.2",
+    "posthog-node": "^5.52.1",
+    "react": "^19.3.0",
     "resend": "^6.28.0",
     "standardwebhooks": "^1.1.1",
     "stripe": "^22.6.2",
@@ -68,14 +78,38 @@
   },
   "peerDependencies": {
     "@better-auth/stripe": "^1.7.4",
+    "@posthog/react": "^1.10.6",
+    "@sentry/cloudflare": "^10.74.0",
+    "@sentry/tanstackstart-react": "^10.74.0",
     "@tanstack/react-router": "^1.170.35",
     "@tanstack/react-start": "^1.168.52",
     "better-auth": "^1.7.4",
     "drizzle-orm": "^0.45.2",
+    "posthog-js": "^1.430.2",
+    "posthog-node": "^5.52.1",
+    "react": "^19.3.0",
     "resend": "^6.28.0",
     "stripe": "^22.6.2"
   },
   "peerDependenciesMeta": {
+    "@sentry/cloudflare": {
+      "optional": true
+    },
+    "@sentry/tanstackstart-react": {
+      "optional": true
+    },
+    "posthog-node": {
+      "optional": true
+    },
+    "posthog-js": {
+      "optional": true
+    },
+    "@posthog/react": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
     "resend": {
       "optional": true
     },

package/src/application/email-service.ts

@@ -17,6 +17,8 @@ export type EmailAttachment = {
  * and https://resend.com/docs/dashboard/emails/tags
  */
 export type OutboundEmail = {
+  /** Override the default for this email, for example "Display Name <address@domain.com>". */
+  readonly from?: string
   readonly to: string | readonly string[]
   readonly subject: string
   readonly html: string
@@ -34,7 +36,7 @@ export type OutboundEmail = {
 export type EmailAccepted = { readonly providerId: string }
 
 /**
- * The port a handler sends through. The adapter owns the sender address and the provider error mapping.
+ * The adapter supplies the default sender and maps provider errors. Each email can override the sender.
  * A provider rejection throws `EmailServiceError`; unexpected SDK rejections propagate unchanged.
  */
 export interface IEmailService {

package/src/application/index.ts

@@ -18,7 +18,24 @@ export {
 export type { IMessageStore } from './message-store.ts'
 export type { DomainCommand, DomainEvent, DomainMessage, DomainQuery, MessageId } from '@/core'
 export { MessageBus, type IMessageBus } from './message-bus.ts'
-export type { IOutboxRelay } from './outbox-relay.ts'
+export {
+  OutboxRelay,
+  type IOutboxRelay,
+  type IOutboxPublisher,
+  type OutboxRelayOptions,
+} from './outbox-relay.ts'
+export type {
+  OutboxClaim,
+  OutboxMessage,
+  DeadLetterReason,
+  IOutboxRepository,
+  IOutboxRetentionRepository,
+} from './outbox-repository.ts'
+export {
+  OutboxRetention,
+  type OutboxRetentionOptions,
+  type OutboxRetentionResult,
+} from './outbox-retention.ts'
 export type {
   CommandRegistry,
   EventRegistry,

package/src/application/outbox-relay.ts

@@ -1,3 +1,12 @@
+import { classifyFailure, createLogger, type DomainEvent } from '@/core'
+
+import type {
+  DeadLetterReason,
+  IOutboxRepository,
+  OutboxClaim,
+  OutboxMessage,
+} from './outbox-repository.ts'
+
 /**
  * Delivers committed outbox rows. The unit of work only wakes it after a commit that wrote
  * events; the app decides what a wake is: `waitUntil`, a Durable Object alarm, nothing.
@@ -6,3 +15,111 @@
 export interface IOutboxRelay {
   wake(): void
 }
+
+/** The publisher sends valid events and returns oversized events. QueueClient satisfies this port directly. */
+export interface IOutboxPublisher {
+  /** Resolves after queue acceptance; a rejected batch may already have sent some events. */
+  sendBatchPartial(messages: ReadonlyArray<DomainEvent>): Promise<ReadonlyArray<DomainEvent>>
+}
+
+/** Optional limits for one relay; durable attempts exclude the publisher's immediate retries. */
+export type OutboxRelayOptions = {
+  readonly batchSize?: number
+  readonly maxBatches?: number
+  readonly maxAttempts?: number
+}
+
+const logger = createLogger('outbox-relay')
+
+/**
+ * Publishes committed events with bounded durable retries. Ported from Typist's relay with per-row exhaustion.
+ * Send failures are recorded; repository failures propagate to the wake or scheduled boundary.
+ */
+export class OutboxRelay {
+  private readonly options: Required<OutboxRelayOptions>
+
+  constructor(
+    private readonly publisher: IOutboxPublisher,
+    private readonly repository: IOutboxRepository,
+    options: OutboxRelayOptions = {},
+  ) {
+    this.options = {
+      batchSize: options.batchSize ?? 50,
+      maxBatches: options.maxBatches ?? 10,
+      maxAttempts: options.maxAttempts ?? 10,
+    }
+  }
+
+  /** Return the claimed count, including released and dead-lettered rows. Zero means no due rows. */
+  async flush(): Promise<number> {
+    const claim = await this.repository.claimPending(this.options.batchSize)
+    const exhausted = claim.messages.filter((row) => row.attempts > this.options.maxAttempts)
+    await this.deadLetter(claim, exhausted, 'exhausted', 'Claim attempt limit exceeded')
+    const pending = claim.messages.filter((row) => row.attempts <= this.options.maxAttempts)
+    if (pending.length === 0) return claim.messages.length
+
+    let oversized: ReadonlyArray<DomainEvent>
+    try {
+      oversized = await this.publisher.sendBatchPartial(pending.map((row) => row.payload))
+    } catch (error) {
+      await this.handleSendFailure(claim, pending, error)
+      return claim.messages.length
+    }
+
+    const oversizedIds = new Set(oversized.map((event) => event.id))
+    await this.deadLetter(
+      claim,
+      pending.filter((row) => oversizedIds.has(row.payload.id)),
+      'oversized',
+      'Exceeds queue message size limit',
+    )
+    const sent = pending.filter((row) => !oversizedIds.has(row.payload.id))
+    if (sent.length > 0) await this.repository.markPublished(claim, sent)
+    return claim.messages.length
+  }
+
+  /** Drain until an empty claim or the batch limit; return the total claimed count. */
+  async drain(): Promise<number> {
+    let total = 0
+    for (let batch = 0; batch < this.options.maxBatches; batch += 1) {
+      // oxlint-disable-next-line no-await-in-loop -- An empty claim must stop the drain before another claim starts.
+      const claimed = await this.flush()
+      total += claimed
+      if (claimed === 0) break
+    }
+    return total
+  }
+
+  private async handleSendFailure(
+    claim: OutboxClaim,
+    pending: ReadonlyArray<OutboxMessage>,
+    cause: unknown,
+  ): Promise<void> {
+    const classification = classifyFailure(cause)
+    const message =
+      cause instanceof Error ? cause.message : 'Publisher rejected with a non-error value'
+    if (classification === 'terminal') {
+      await this.deadLetter(claim, pending, 'terminal', message, cause)
+      return
+    }
+    const exhausted = pending.filter((row) => row.attempts >= this.options.maxAttempts)
+    await this.deadLetter(claim, exhausted, 'exhausted', message, cause)
+    const retry = pending.filter((row) => row.attempts < this.options.maxAttempts)
+    if (retry.length > 0) await this.repository.releaseClaim(claim, retry)
+  }
+
+  private async deadLetter(
+    claim: OutboxClaim,
+    messages: ReadonlyArray<OutboxMessage>,
+    reason: DeadLetterReason,
+    errorMessage: string,
+    cause?: unknown,
+  ): Promise<void> {
+    if (messages.length === 0) return
+    await this.repository.deadLetter(claim, messages, reason, errorMessage)
+    logger.error('outbox_messages_dead_lettered', {
+      error: cause,
+      details: { claimToken: claim.token, count: messages.length, reason },
+    })
+  }
+}

package/src/application/outbox-repository.ts

@@ -0,0 +1,46 @@
+import type { DomainEvent } from '@/core'
+
+/** A claimed event and its durable attempt count. The payload id identifies the outbox row. */
+export type OutboxMessage = {
+  readonly payload: DomainEvent
+  readonly attempts: number
+}
+
+/** One lease shared by the rows returned from a single atomic claim. */
+export type OutboxClaim = {
+  readonly token: string
+  readonly messages: ReadonlyArray<OutboxMessage>
+}
+
+/** Why an event remains in the outbox without further automatic delivery. */
+export type DeadLetterReason = 'oversized' | 'terminal' | 'exhausted'
+
+/** Bounded retention operations on committed records, outside the unit of work. */
+export interface IOutboxRetentionRepository {
+  /** Delete published events strictly older than the cutoff. */
+  deletePublishedBefore(cutoff: Date, batchSize: number): Promise<number>
+  /** Delete failed events strictly older than the cutoff. */
+  deleteFailedBefore(cutoff: Date, batchSize: number): Promise<number>
+  /** Delete duplicate-protection receipts strictly older than the cutoff. */
+  deleteReceiptsBefore(cutoff: Date, batchSize: number): Promise<number>
+}
+
+/**
+ * Claims and settles committed events on the plain database connection. Never retry these calls locally.
+ * Each settlement affects only the supplied rows that still hold the claim token.
+ */
+export interface IOutboxRepository extends IOutboxRetentionRepository {
+  /** Atomically lease due rows and increment their attempts, including claims after an expired lease. */
+  claimPending(batchSize: number): Promise<OutboxClaim>
+  /** Record queue acceptance and clear the lease. */
+  markPublished(claim: OutboxClaim, messages: ReadonlyArray<OutboxMessage>): Promise<void>
+  /** Clear the lease and delay each row according to its own attempt count. */
+  releaseClaim(claim: OutboxClaim, messages: ReadonlyArray<OutboxMessage>): Promise<void>
+  /** Stop automatic delivery while retaining the payload and a readable failure reason. */
+  deadLetter(
+    claim: OutboxClaim,
+    messages: ReadonlyArray<OutboxMessage>,
+    reason: DeadLetterReason,
+    errorMessage: string,
+  ): Promise<void>
+}