better-ship 0.12.0 → 0.14.0

package/src/infrastructure/posthog/server.ts

@@ -0,0 +1,107 @@
+import { PostHog, type PostHogOptions } from 'posthog-node'
+
+import type { AnalyticsService } from '@/application'
+import {
+  MissingConfigurationError,
+  type AnalyticsEventIdentity,
+  type AnalyticsEventInput,
+  type AnalyticsProperties,
+} from '@/core'
+
+import { PostHogMetricsService } from './metrics.ts'
+
+/** Deployment values and SDK options; the runtime owns delivery promises. */
+export interface PostHogAnalyticsConfig {
+  readonly apiKey: string
+  readonly environment: string
+  readonly source: string
+  readonly waitUntil: (promise: Promise<unknown>) => void
+  readonly options?: Omit<
+    PostHogOptions,
+    'waitUntil' | 'flushAt' | 'flushInterval' | 'metrics' | 'disabled'
+  > & {
+    readonly metrics?: Omit<NonNullable<PostHogOptions['metrics']>, 'serviceName' | 'environment'>
+  }
+}
+
+/** Worker analytics ported from Typist; disabled applications select Porte's NULL_ANALYTICS instead. */
+export class PostHogAnalyticsService implements AnalyticsService {
+  /** Metrics share this service's SDK client and delivery lifetime. */
+  readonly metrics: PostHogMetricsService
+
+  private constructor(
+    /** Raw SDK access for integrations such as PostHog AI tracing. */
+    readonly posthog: PostHog,
+    private readonly waitUntil: (promise: Promise<unknown>) => void,
+  ) {
+    this.metrics = new PostHogMetricsService(posthog, waitUntil)
+  }
+
+  /** Construct once per Worker invocation; a blank key throws MissingConfigurationError. */
+  static create(config: PostHogAnalyticsConfig): PostHogAnalyticsService {
+    const apiKey = config.apiKey.trim()
+    if (apiKey.length === 0) throw new MissingConfigurationError('POSTHOG_API_KEY')
+    const client = new PostHog(apiKey, {
+      host: 'https://us.i.posthog.com',
+      ...config.options,
+      flushAt: 1,
+      flushInterval: 0,
+      waitUntil: config.waitUntil,
+      metrics: {
+        ...config.options?.metrics,
+        environment: config.environment,
+        serviceName: config.source,
+      },
+    })
+    // The SDK applies in-memory super properties synchronously before this promise resolves.
+    void client.register({ environment: config.environment, source: config.source })
+    return new PostHogAnalyticsService(client, config.waitUntil)
+  }
+
+  /** Schedule person properties; the SDK's waitUntil option protects queued delivery. */
+  identify(distinctId: string, properties?: AnalyticsProperties): void {
+    const payload: Parameters<PostHog['identify']>[0] = { distinctId }
+    if (properties !== undefined) payload.properties = properties
+    this.posthog.identify(payload)
+  }
+
+  /** Schedule an irreversible person merge; only alias IDs the application proves belong to one person. */
+  alias(distinctId: string, previousDistinctId: string): void {
+    this.waitUntil(this.posthog.aliasImmediate({ distinctId, alias: previousDistinctId }))
+  }
+
+  /** Schedule an event; omit identity for SDK-generated UUID and capture time. */
+  track(event: AnalyticsEventInput, distinctId: string, identity?: AnalyticsEventIdentity): void {
+    this.capture(event, distinctId, 'person', identity)
+  }
+
+  /** Schedule an event without creating a person profile for an attempt or resource ID. */
+  trackAnonymous(
+    event: AnalyticsEventInput,
+    distinctId: string,
+    identity?: AnalyticsEventIdentity,
+  ): void {
+    this.capture(event, distinctId, 'anonymous', identity)
+  }
+
+  private capture(
+    event: AnalyticsEventInput,
+    distinctId: string,
+    profile: 'person' | 'anonymous',
+    identity?: AnalyticsEventIdentity,
+  ): void {
+    const properties = { ...event.properties }
+    const payload: Parameters<PostHog['captureImmediate']>[0] = {
+      distinctId,
+      event: event.name,
+      properties,
+    }
+    if (profile === 'anonymous')
+      payload.properties = { ...properties, $process_person_profile: false }
+    if (identity !== undefined) {
+      payload.uuid = identity.uuid
+      payload.timestamp = identity.timestamp
+    }
+    this.waitUntil(this.posthog.captureImmediate(payload))
+  }
+}

package/src/infrastructure/sentry/client.ts

@@ -0,0 +1,55 @@
+import * as Sentry from '@sentry/tanstackstart-react'
+import { isNotFound, isRedirect } from '@tanstack/react-router'
+
+import { setLoggerErrorHook, type LoggerErrorHook } from '@/core'
+
+/** Application settings use Sentry's names; enablement and environment belong to the application. */
+export type SentryClientOptions = Sentry.BrowserOptions & {
+  readonly dsn: string
+  readonly environment: string
+  readonly enabled: boolean
+}
+
+/** Privacy defaults from Porte and browser noise filtering from Typist; explicit SDK options take precedence. */
+export function createSentryClientOptions(options: SentryClientOptions): Sentry.BrowserOptions {
+  return {
+    enableLogs: true,
+    ignoreErrors: [/Failed to execute '(insertBefore|removeChild)' on 'Node'/],
+    ...options,
+    dataCollection: {
+      userInfo: false,
+      httpBodies: [],
+      ...options.dataCollection,
+      genAI: { inputs: false, outputs: false, ...options.dataCollection?.genAI },
+    },
+  }
+}
+
+/** Forward logged browser errors once, excluding TanStack navigation control flow. */
+export function createSentryLoggerErrorHook(): LoggerErrorHook {
+  return ({ error, context }) => {
+    if (isNotFound(error) || isRedirect(error)) return
+    const captured = error instanceof Error ? error : new Error('Logger received a non-Error value')
+    Sentry.captureException(captured, { extra: context })
+  }
+}
+
+/** Initialize once in the browser entrypoint before hydration; server imports have no side effects. */
+export function initializeSentry(options: SentryClientOptions): ReturnType<typeof Sentry.init> {
+  const client = Sentry.init(createSentryClientOptions(options))
+  setLoggerErrorHook(createSentryLoggerErrorHook())
+  return client
+}
+
+/** Attach tracing once after creating the browser router, as Porte does in getRouter. */
+export function instrumentSentryRouter(
+  router: Parameters<typeof Sentry.tanstackRouterBrowserTracingIntegration>[0],
+): void {
+  if (router.isServer) return
+  Sentry.addIntegration(Sentry.tanstackRouterBrowserTracingIntegration(router))
+}
+
+/** The SDK error boundary; the application supplies its fallback component. */
+export const ErrorBoundary: typeof Sentry.ErrorBoundary = Sentry.ErrorBoundary
+
+export { Sentry }

package/src/infrastructure/sentry/server.ts

@@ -0,0 +1,51 @@
+import * as Sentry from '@sentry/cloudflare'
+
+import type { ObservabilityScope, ObservabilityService, ObservabilityUser } from '@/application'
+import type { LoggerErrorHook } from '@/core'
+
+/** Application-owned deployment settings with the full Cloudflare SDK option contract. */
+export type SentryServerOptions = Sentry.CloudflareOptions & {
+  readonly dsn: string
+  readonly environment: string
+  readonly enabled: boolean
+}
+
+/** Options for Workers, Durable Objects, and Workflows, ported from Typist and Porte. */
+export function createSentryOptions(options: SentryServerOptions): Sentry.CloudflareOptions {
+  return {
+    enableLogs: true,
+    ...options,
+    dataCollection: {
+      userInfo: false,
+      httpBodies: [],
+      ...options.dataCollection,
+      genAI: { inputs: false, outputs: false, ...options.dataCollection?.genAI },
+    },
+  }
+}
+
+/** Register with setLoggerErrorHook once at startup; an explicit user applies only to this report. */
+export function createSentryLoggerErrorHook(): LoggerErrorHook {
+  return ({ error, distinctId, context }) => {
+    if (distinctId !== undefined) {
+      Sentry.captureException(error, { extra: context, user: { id: distinctId } })
+      return
+    }
+    Sentry.captureException(error, { extra: context })
+  }
+}
+
+/** Identity and scope adapter from Typist and Porte; call inside Sentry's instrumented runtime. */
+export class SentryObservabilityService implements ObservabilityService {
+  /** Attribute subsequent reports in the current isolation scope. */
+  setUser(user: ObservabilityUser): void {
+    Sentry.setUser(user)
+  }
+
+  /** Await work in a separate scope for each queue message or concurrent operation. */
+  async withIsolationScope<T>(callback: (scope: ObservabilityScope) => T | Promise<T>): Promise<T> {
+    return await Sentry.withIsolationScope(callback)
+  }
+}
+
+export { Sentry }

package/src/infrastructure/sentry/vite.ts

@@ -0,0 +1,17 @@
+import {
+  sentryTanstackStart as sentryPlugin,
+  type SentryTanstackStartOptions,
+} from '@sentry/tanstackstart-react/vite'
+
+/** Sentry's Vite options; the SDK creates the tunnel route and sets the browser tunnel URL. */
+export type SentryViteOptions = SentryTanstackStartOptions
+
+/**
+ * Add after tanstackStart() in Vite. The SDK enables a same-origin tunnel by default here.
+ * Set tunnelRoute.allowedDsns when the browser and Worker use different Sentry projects.
+ */
+export function sentryTanstackStart(
+  options: SentryViteOptions = {},
+): ReturnType<typeof sentryPlugin> {
+  return sentryPlugin({ ...options, tunnelRoute: options.tunnelRoute ?? true })
+}

package/src/infrastructure/testing/outbox-repository-contract.ts

@@ -0,0 +1,228 @@
+import { deepStrictEqual, equal, notEqual, ok } from 'node:assert/strict'
+
+import type { IOutboxRepository } from '@/application'
+import type { DomainEvent } from '@/core'
+
+/** 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 function outboxRepositoryContract(
+  test: (name: string, run: () => Promise<void>) => void,
+  create: () => Promise<OutboxRepositoryContractFixture>,
+): void {
+  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() + 60_000)
+    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: new Date(f.now().getTime() - 1_000) }])
+    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 claims = await Promise.all([f.repository.claimPending(1), f.repository.claimPending(1)])
+    const ids = claims.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(60_000)
+    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(60_000)
+      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,
+      ]),
+      [
+        [1000, null],
+        [4000, null],
+        [60000, 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 = new Date(f.now().getTime() - 1000)
+      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 = new Date(f.now().getTime() - 1000)
+    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'],
+    )
+  })
+}

package/dist/application-CIxo_BpK.js

@@ -1,160 +0,0 @@
-import { E as DatabaseError, Q as AppError, T as unreachable, a as createLogger } from "./core-DG_cC8YT.js";
-import { panic } from "better-result";
-
-//#region src/application/email-service.ts
-/** Records every send for a test. Provider ids count up as `recorded-1`, `recorded-2`. */
-var RecordingEmailService = class {
-	/** Sends in call order, including repeated idempotency keys. */
-	sent = [];
-	/** Record the send before returning its provider id. */
-	async sendEmail(email) {
-		this.sent.push(email);
-		return { providerId: `recorded-${this.sent.length}` };
-	}
-};
-
-//#endregion
-//#region src/application/record-email-event.ts
-/**
-* Record a bounce or a complaint for every recipient inside the command's unit of work.
-* The command id is the provider's event id, so a redelivered webhook is `MessageAlreadyProcessedError`.
-*/
-async function recordEmailEvent(command, deps) {
-	await deps.uow.run(command.id, async ({ emailDeliverability }) => {
-		for (const address of command.recipients) if (command.event.type === "bounced") await emailDeliverability.recordBounce(address, {
-			type: command.event.bounceType,
-			subType: command.event.bounceSubType
-		});
-		else await emailDeliverability.recordComplaint(address);
-	});
-}
-
-//#endregion
-//#region src/application/message-already-processed.error.ts
-/** The message's effects already committed. A caller can skip duplicate delivery without repeating those effects. */
-var MessageAlreadyProcessedError = class MessageAlreadyProcessedError extends AppError {
-	messageId;
-	_tag = "MessageAlreadyProcessedError";
-	classification = "terminal";
-	constructor(messageId, options) {
-		super(`message ${messageId} already processed`, options);
-		this.messageId = messageId;
-	}
-	/** Recognize only the processed-message primary key; preserve other failures unchanged at the call site. */
-	static from(cause, messageId) {
-		if (cause instanceof MessageAlreadyProcessedError) return cause;
-		if (!(cause instanceof DatabaseError)) return void 0;
-		const details = cause.details;
-		if (!(details.database === "d1" ? details.kind === "unique" && details.table === "processed_messages" && details.column === "message_id" : details.code === "23505" && details.table_name === "processed_messages" && details.constraint_name === "processed_messages_pkey")) return void 0;
-		return new MessageAlreadyProcessedError(messageId, { cause });
-	}
-};
-
-//#endregion
-//#region src/application/message-bus.ts
-const logger = createLogger("message-bus");
-/**
-* Routes one message to its slot. The bus opens no transaction and keeps no outbox:
-* a handler that writes opens the unit of work itself.
-*/
-var MessageBus = class {
-	deps;
-	registry;
-	constructor(deps, registry) {
-		this.deps = deps;
-		this.registry = registry;
-	}
-	/** Resolves to the handler's own value for a command or query, and to void for an event. */
-	async handle(message) {
-		return await this.dispatch(message);
-	}
-	dispatch(message) {
-		if (message.type === "command") return this.handleCommand(message);
-		if (message.type === "query") return this.handleQuery(message);
-		if (message.type === "event") return this.handleEvent(message);
-		return unreachable(message);
-	}
-	handleCommand(command) {
-		const handler = this.registry.commands[command.name];
-		if (handler === void 0) return panic(`No handler for command ${command.name}`);
-		logger.debug("handling_command", {
-			name: command.name,
-			id: command.id
-		});
-		return handler(command, this.deps);
-	}
-	handleQuery(query) {
-		const handler = this.registry.queries[query.name];
-		if (handler === void 0) return panic(`No handler for query ${query.name}`);
-		return handler(query, this.deps);
-	}
-	/**
-	* Every subscriber runs to completion. One failure is rethrown as is. Several are thrown as
-	* one `AggregateError`. A `MessageAlreadyProcessedError` means that subscriber already committed on
-	* an earlier delivery, so it counts as delivered.
-	*/
-	async handleEvent(event) {
-		const subscriptions = this.registry.events[event.name] ?? [];
-		const outcomes = await Promise.allSettled(subscriptions.map((subscription) => subscription(event, this.deps)));
-		const failures = [];
-		for (const [subscriber, outcome] of outcomes.entries()) {
-			if (outcome.status === "fulfilled") continue;
-			if (outcome.reason instanceof MessageAlreadyProcessedError) {
-				logger.info("duplicate_subscriber_ignored", {
-					event: event.name,
-					id: event.id,
-					subscriber
-				});
-				continue;
-			}
-			failures.push(outcome.reason);
-		}
-		if (failures.length === 1) throw failures[0];
-		if (failures.length > 1) throw new AggregateError(failures, `${event.name}: ${failures.length} subscribers failed`);
-	}
-};
-
-//#endregion
-//#region src/application/unit-of-work.ts
-/** The unit of work: the boundary, the repositories, the events. Every database call is a port. */
-var UnitOfWork = class {
-	deps;
-	constructor(deps) {
-		this.deps = deps;
-	}
-	async run(messageId, work) {
-		const { transaction, messageStore, createRepositories, eventCollector, relay } = this.deps;
-		let written = 0;
-		let value;
-		try {
-			value = await transaction.transaction(async (tx) => {
-				const store = messageStore(tx);
-				await store.claim(messageId);
-				const result = await work(createRepositories(tx));
-				const pending = eventCollector.collect();
-				await store.persistEvents(pending);
-				written = pending.length;
-				return result;
-			});
-		} catch (error) {
-			throw MessageAlreadyProcessedError.from(error, messageId) ?? error;
-		}
-		if (written > 0) relay.wake();
-		return value;
-	}
-};
-
-//#endregion
-//#region src/application/unit-of-work.errors.ts
-/** A boundary was opened inside another. One message, one atomic scope. */
-var UnitOfWorkAlreadyActiveError = class extends AppError {
-	_tag = "UnitOfWorkAlreadyActiveError";
-	classification = "terminal";
-	constructor() {
-		super("a unit of work is already active");
-	}
-};
-
-//#endregion
-export { recordEmailEvent as a, MessageAlreadyProcessedError as i, UnitOfWork as n, RecordingEmailService as o, MessageBus as r, UnitOfWorkAlreadyActiveError as t };
-//# sourceMappingURL=application-CIxo_BpK.js.map

package/dist/application-CIxo_BpK.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"application-CIxo_BpK.js","names":[],"sources":["../src/application/email-service.ts","../src/application/record-email-event.ts","../src/application/message-already-processed.error.ts","../src/application/message-bus.ts","../src/application/unit-of-work.ts","../src/application/unit-of-work.errors.ts"],"sourcesContent":["import type { EmailIdempotencyKey } from '@/core'\n\n/** A media type such as `application/pdf`. */\nexport type MimeType = `${string}/${string}`\n\n/** A file to attach. Binary content is bytes; the adapter encodes it for the provider. */\nexport type EmailAttachment = {\n  readonly filename: string\n  readonly content: string | Uint8Array\n  /** Optional MIME metadata; Resend accepts filename and content without it. */\n  readonly contentType?: MimeType\n}\n\n/**\n * One transactional email. Resend accepts 50 recipients, 75 tags with ASCII names and values,\n * and 40 MB of attachments after base64. Sources: https://resend.com/docs/api-reference/emails/send-email\n * and https://resend.com/docs/dashboard/emails/tags\n */\nexport type OutboundEmail = {\n  /** Override the default for this email, for example \"Display Name <address@domain.com>\". */\n  readonly from?: string\n  readonly to: string | readonly string[]\n  readonly subject: string\n  readonly html: string\n  /** The stable identity of this send. Resend deduplicates it for 24 hours. */\n  readonly idempotencyKey: EmailIdempotencyKey\n  /** Resend generates plain text from html when omitted. An empty string disables that generation. */\n  readonly text?: string\n  readonly replyTo?: string\n  /** Labels the provider stores with the email and returns on every delivery event. */\n  readonly tags?: Readonly<Record<string, string>>\n  readonly attachments?: readonly EmailAttachment[]\n}\n\n/** The provider accepted the email and assigned its id. */\nexport type EmailAccepted = { readonly providerId: string }\n\n/**\n * The adapter supplies the default sender and maps provider errors. Each email can override the sender.\n * A provider rejection throws `EmailServiceError`; unexpected SDK rejections propagate unchanged.\n */\nexport interface IEmailService {\n  /** Resolve after provider acceptance; this does not confirm delivery to the recipient. */\n  sendEmail(email: OutboundEmail): Promise<EmailAccepted>\n}\n\n/** Records every send for a test. Provider ids count up as `recorded-1`, `recorded-2`. */\nexport class RecordingEmailService implements IEmailService {\n  /** Sends in call order, including repeated idempotency keys. */\n  readonly sent: OutboundEmail[] = []\n\n  /** Record the send before returning its provider id. */\n  async sendEmail(email: OutboundEmail): Promise<EmailAccepted> {\n    this.sent.push(email)\n    return { providerId: `recorded-${this.sent.length}` }\n  }\n}\n","import type { BounceType, DomainCommand, EmailAddress, RecordEmailEventPayload } from '@/core'\n\nimport type { IUnitOfWork } from './unit-of-work.ts'\n\n/** What a bounce records for one address. */\nexport type EmailBounceRecord = {\n  readonly type: BounceType\n  readonly subType: string | null\n}\n\n/**\n * The application's deliverability state per address. An implementation keeps the higher bounce\n * severity with `shouldUpdateBounce`, and treats an unknown address as nothing to record.\n */\nexport interface IEmailDeliverabilityStore {\n  /** Keep the higher severity atomically. Equal severity permits replacement; the store owns timestamp ordering. */\n  recordBounce(address: EmailAddress, bounce: EmailBounceRecord): Promise<void>\n  /** Record a complaint without clearing existing suppression state. */\n  recordComplaint(address: EmailAddress): Promise<void>\n}\n\n/** The repositories the handler needs from the unit of work. */\nexport type RecordEmailEventRepos = { readonly emailDeliverability: IEmailDeliverabilityStore }\n\n/** The container slice the handler reads. */\nexport type RecordEmailEventDeps = { readonly uow: IUnitOfWork<RecordEmailEventRepos> }\n\n/** The command, under whatever name the application registered the payload. */\nexport type RecordEmailEventCommand = DomainCommand & RecordEmailEventPayload\n\n/**\n * Record a bounce or a complaint for every recipient inside the command's unit of work.\n * The command id is the provider's event id, so a redelivered webhook is `MessageAlreadyProcessedError`.\n */\nexport async function recordEmailEvent(\n  command: RecordEmailEventCommand,\n  deps: RecordEmailEventDeps,\n): Promise<void> {\n  await deps.uow.run(command.id, async ({ emailDeliverability }) => {\n    for (const address of command.recipients) {\n      if (command.event.type === 'bounced') {\n        // oxlint-disable-next-line no-await-in-loop -- Finish each transaction write before starting another; a failure must leave no pending writes.\n        await emailDeliverability.recordBounce(address, {\n          type: command.event.bounceType,\n          subType: command.event.bounceSubType,\n        })\n      } else {\n        // oxlint-disable-next-line no-await-in-loop -- A rejected write must stop the transaction before another write starts.\n        await emailDeliverability.recordComplaint(address)\n      }\n    }\n  })\n}\n","import { AppError, DatabaseError, type MessageId } from '@/core'\n\n/** The message's effects already committed. A caller can skip duplicate delivery without repeating those effects. */\nexport class MessageAlreadyProcessedError extends AppError {\n  readonly _tag = 'MessageAlreadyProcessedError'\n  readonly classification = 'terminal'\n\n  constructor(\n    readonly messageId: MessageId,\n    options?: { readonly cause: unknown },\n  ) {\n    super(`message ${messageId} already processed`, options)\n  }\n\n  /** Recognize only the processed-message primary key; preserve other failures unchanged at the call site. */\n  static from(cause: unknown, messageId: MessageId): MessageAlreadyProcessedError | undefined {\n    if (cause instanceof MessageAlreadyProcessedError) return cause\n    if (!(cause instanceof DatabaseError)) return undefined\n    const details = cause.details\n    const duplicate =\n      details.database === 'd1'\n        ? details.kind === 'unique' &&\n          details.table === 'processed_messages' &&\n          details.column === 'message_id'\n        : details.code === '23505' &&\n          details.table_name === 'processed_messages' &&\n          details.constraint_name === 'processed_messages_pkey'\n    if (!duplicate) return undefined\n    return new MessageAlreadyProcessedError(messageId, { cause })\n  }\n}\n","import { panic } from 'better-result'\n\nimport {\n  createLogger,\n  unreachable,\n  type DomainCommand,\n  type DomainEvent,\n  type DomainMessage,\n  type DomainQuery,\n} from '@/core'\n\nimport { MessageAlreadyProcessedError } from './message-already-processed.error.ts'\nimport type { Handlers, MessageResult, RegistryMessage } from './registry.ts'\n\nconst logger = createLogger('message-bus')\n\n/** The port an entrypoint dispatches through. `AppDeps` names this as `IMessageBus<typeof registry>`. */\nexport interface IMessageBus<TRegistry extends Handlers<never>> {\n  handle<TMessage extends DomainMessage & RegistryMessage<TRegistry>>(\n    message: TMessage,\n  ): Promise<MessageResult<TMessage, TRegistry>>\n}\n\n/**\n * Routes one message to its slot. The bus opens no transaction and keeps no outbox:\n * a handler that writes opens the unit of work itself.\n */\nexport class MessageBus<Deps, TRegistry extends Handlers<Deps>> implements IMessageBus<TRegistry> {\n  constructor(\n    private readonly deps: Deps,\n    private readonly registry: TRegistry,\n  ) {}\n\n  /** Resolves to the handler's own value for a command or query, and to void for an event. */\n  async handle<TMessage extends DomainMessage & RegistryMessage<TRegistry>>(\n    message: TMessage,\n  ): Promise<MessageResult<TMessage, TRegistry>> {\n    // SAFETY: the slot for this name is what `MessageResult` names, and dispatch returns its value.\n    return (await this.dispatch(message)) as MessageResult<TMessage, TRegistry>\n  }\n\n  // oxlint-disable-next-line anti-slop/no-unknown-returns -- one table holds every slot's value; `handle` names it.\n  private dispatch(message: DomainMessage): Promise<unknown> {\n    if (message.type === 'command') return this.handleCommand(message)\n    if (message.type === 'query') return this.handleQuery(message)\n    if (message.type === 'event') return this.handleEvent(message)\n    // A message parsed at a boundary cannot reach here; one that does must not resolve silently.\n    return unreachable(message)\n  }\n\n  // oxlint-disable-next-line anti-slop/no-unknown-returns -- see dispatch.\n  private handleCommand(command: DomainCommand): Promise<unknown> {\n    // `satisfies` proved the registry complete, so a missing slot is a broken registry object.\n    const handler = this.registry.commands[command.name]\n    if (handler === undefined) return panic(`No handler for command ${command.name}`)\n    logger.debug('handling_command', { name: command.name, id: command.id })\n    return handler(command, this.deps)\n  }\n\n  // oxlint-disable-next-line anti-slop/no-unknown-returns -- see dispatch.\n  private handleQuery(query: DomainQuery): Promise<unknown> {\n    const handler = this.registry.queries[query.name]\n    if (handler === undefined) return panic(`No handler for query ${query.name}`)\n    return handler(query, this.deps)\n  }\n\n  /**\n   * Every subscriber runs to completion. One failure is rethrown as is. Several are thrown as\n   * one `AggregateError`. A `MessageAlreadyProcessedError` means that subscriber already committed on\n   * an earlier delivery, so it counts as delivered.\n   */\n  private async handleEvent(event: DomainEvent): Promise<void> {\n    const subscriptions = this.registry.events[event.name] ?? []\n    const outcomes = await Promise.allSettled(\n      subscriptions.map((subscription) => subscription(event, this.deps)),\n    )\n    const failures: unknown[] = []\n    for (const [subscriber, outcome] of outcomes.entries()) {\n      if (outcome.status === 'fulfilled') continue\n      if (outcome.reason instanceof MessageAlreadyProcessedError) {\n        // The bus swallows this error, so this line is the only record that the skip happened.\n        logger.info('duplicate_subscriber_ignored', { event: event.name, id: event.id, subscriber })\n        continue\n      }\n      failures.push(outcome.reason)\n    }\n    if (failures.length === 1) throw failures[0]\n    if (failures.length > 1) {\n      throw new AggregateError(failures, `${event.name}: ${failures.length} subscribers failed`)\n    }\n  }\n}\n","import type { MessageId } from '@/core'\n\nimport type { IEventCollector } from './event-collector.ts'\nimport { MessageAlreadyProcessedError } from './message-already-processed.error.ts'\nimport type { IMessageStore } from './message-store.ts'\nimport type { IOutboxRelay } from './outbox-relay.ts'\nimport type { ITransaction } from './transaction.ts'\n\n/**\n * Commits the processed-message record, repository writes, and emitted events together before resolving.\n * An existing record rejects with `MessageAlreadyProcessedError`; external effects must run through the outbox after commit.\n * Nested calls reject with `UnitOfWorkAlreadyActiveError`; independent concurrent calls are allowed.\n */\nexport interface IUnitOfWork<Repos> {\n  run<T>(messageId: MessageId, work: (repos: Repos) => Promise<T>): Promise<T>\n}\n\nexport type UnitOfWorkDeps<Tx, Repos> = {\n  readonly transaction: ITransaction<Tx>\n  /** The processed-messages and outbox repository for this transaction. */\n  readonly messageStore: (tx: Tx) => IMessageStore\n  /** Repositories participate in the current transaction. */\n  readonly createRepositories: (tx: Tx) => Repos\n  readonly eventCollector: IEventCollector\n  readonly relay: IOutboxRelay\n}\n\n/** The unit of work: the boundary, the repositories, the events. Every database call is a port. */\nexport class UnitOfWork<Tx, Repos> implements IUnitOfWork<Repos> {\n  constructor(private readonly deps: UnitOfWorkDeps<Tx, Repos>) {}\n\n  async run<T>(messageId: MessageId, work: (repos: Repos) => Promise<T>): Promise<T> {\n    const { transaction, messageStore, createRepositories, eventCollector, relay } = this.deps\n    let written = 0\n\n    let value: T\n    try {\n      value = await transaction.transaction(async (tx) => {\n        const store = messageStore(tx)\n        await store.claim(messageId)\n        const repos = createRepositories(tx)\n        const result = await work(repos)\n        const pending = eventCollector.collect()\n        await store.persistEvents(pending)\n        written = pending.length\n        return result\n      })\n    } catch (error) {\n      throw MessageAlreadyProcessedError.from(error, messageId) ?? error\n    }\n\n    if (written > 0) relay.wake()\n    return value\n  }\n}\n","import { AppError } from '@/core'\n\n/** A boundary was opened inside another. One message, one atomic scope. */\nexport class UnitOfWorkAlreadyActiveError extends AppError {\n  readonly _tag = 'UnitOfWorkAlreadyActiveError'\n  readonly classification = 'terminal'\n\n  constructor() {\n    super('a unit of work is already active')\n  }\n}\n"],"mappings":"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"}