better-ship 0.12.0 → 0.14.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://www.schemastore.org/package.json",
   "name": "better-ship",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Foundation for applications on Cloudflare Workers: logger, errors, message bus, infrastructure adapters, and UI primitives",
   "license": "Apache-2.0",
   "repository": {
@@ -29,9 +29,17 @@
     "./core": "./dist/core.js",
     "./http": "./dist/http.js",
     "./postgres": "./dist/postgres.js",
+    "./posthog/client": "./dist/posthog/client.js",
+    "./posthog/metrics": "./dist/posthog/metrics.js",
+    "./posthog/proxy": "./dist/posthog/proxy.js",
+    "./posthog/server": "./dist/posthog/server.js",
     "./resend": "./dist/resend.js",
+    "./sentry/client": "./dist/sentry/client.js",
+    "./sentry/server": "./dist/sentry/server.js",
+    "./sentry/vite": "./dist/sentry/vite.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 +56,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": "^4.1.11",
     "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 +85,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/analytics-service.ts

@@ -0,0 +1,21 @@
+import type { AnalyticsEventIdentity, AnalyticsEventInput, AnalyticsProperties } from '@/core'
+
+/** Product analytics without an SDK dependency, ported from Typist and Porte. */
+export interface AnalyticsService<TEvent extends AnalyticsEventInput = AnalyticsEventInput> {
+  /** Attach traits to one person. */
+  identify(distinctId: string, properties?: AnalyticsProperties): void
+  /** Merge a previous ID into this person; the application must establish that both identify the same person. */
+  alias(distinctId: string, previousDistinctId: string): void
+  /** Schedule an event for a person; returning does not confirm remote acceptance. */
+  track(event: TEvent, distinctId: string, identity?: AnalyticsEventIdentity): void
+  /** Schedule an event without creating a person profile for its distinct ID. */
+  trackAnonymous(event: TEvent, distinctId: string, identity?: AnalyticsEventIdentity): void
+}
+
+/** Reports to nobody. The composition root selects this service when analytics is disabled. */
+export const NULL_ANALYTICS: AnalyticsService = {
+  identify: () => {},
+  alias: () => {},
+  track: () => {},
+  trackAnonymous: () => {},
+}

package/src/application/index.ts

@@ -1,4 +1,17 @@
 export type { CommandHandler, EventHandler, QueryHandler } from './handlers.ts'
+export { NULL_ANALYTICS, type AnalyticsService } from './analytics-service.ts'
+export {
+  NULL_METRICS_SERVICE,
+  type MetricsService,
+  type MetricOptions,
+  type MetricAttributes,
+  type MetricAttributeValue,
+} from './metrics-service.ts'
+export type {
+  ObservabilityService,
+  ObservabilityScope,
+  ObservabilityUser,
+} from './observability-service.ts'
 export {
   RecordingEmailService,
   type IEmailService,
@@ -18,7 +31,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/metrics-service.ts

@@ -0,0 +1,28 @@
+/** A metric dimension; use a small, bounded value set and never user or request IDs. */
+export type MetricAttributeValue = string | number | boolean
+
+/** Dimensions shared by observations in one time series. */
+export type MetricAttributes = Readonly<Record<string, MetricAttributeValue>>
+
+/** Unit and dimensions for an operational measurement. */
+export interface MetricOptions {
+  readonly attributes?: MetricAttributes
+  readonly unit?: string
+}
+
+/** Operational measurements, ported from Typist's metrics-service.ts; applications own metric names. */
+export interface MetricsService<TName extends string = string> {
+  /** Add a nonnegative value to a total; the default increment is one. */
+  count(name: TName, value?: number, options?: MetricOptions): void
+  /** Record a current value. */
+  gauge(name: TName, value: number, options?: MetricOptions): void
+  /** Record one observation in a distribution. */
+  histogram(name: TName, value: number, options?: MetricOptions): void
+}
+
+/** Records nothing when the composition root disables metrics. */
+export const NULL_METRICS_SERVICE: MetricsService = {
+  count: () => {},
+  gauge: () => {},
+  histogram: () => {},
+}

package/src/application/observability-service.ts

@@ -0,0 +1,16 @@
+/** The identity an error report belongs to. */
+export interface ObservabilityUser {
+  readonly id: string
+}
+
+/** Identity within one isolated execution. */
+export interface ObservabilityScope {
+  /** Attribute reports in this scope to one person. */
+  setUser(user: ObservabilityUser): void
+}
+
+/** Error identity and isolation, ported from Porte's sentry-observability-service.ts. */
+export interface ObservabilityService extends ObservabilityScope {
+  /** Await work in its own scope so concurrent executions do not share identity. */
+  withIsolationScope<T>(callback: (scope: ObservabilityScope) => T | Promise<T>): Promise<T>
+}

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>
+}

package/src/application/outbox-retention.ts

@@ -0,0 +1,61 @@
+import type { IOutboxRetentionRepository } from './outbox-repository.ts'
+
+/** Typist's retention defaults; receipt retention must cover the application's supported replay period. */
+export type OutboxRetentionOptions = {
+  readonly publishedRetentionMs?: number
+  readonly failedRetentionMs?: number
+  readonly receiptRetentionMs?: number
+  readonly batchSize?: number
+  readonly maxBatches?: number
+}
+
+/** Deleted records per category during one bounded sweep. */
+export type OutboxRetentionResult = {
+  readonly published: number
+  readonly failed: number
+  readonly receipts: number
+}
+
+/** Bounded cleanup ported from Typist's message retention handler. The application schedules each sweep. */
+export class OutboxRetention {
+  private readonly options: Required<OutboxRetentionOptions>
+
+  constructor(
+    private readonly repository: IOutboxRetentionRepository,
+    options: OutboxRetentionOptions = {},
+  ) {
+    this.options = {
+      publishedRetentionMs: options.publishedRetentionMs ?? 86_400_000,
+      failedRetentionMs: options.failedRetentionMs ?? 30 * 86_400_000,
+      receiptRetentionMs: options.receiptRetentionMs ?? 7 * 86_400_000,
+      batchSize: options.batchSize ?? 1_000,
+      maxBatches: options.maxBatches ?? 10,
+    }
+  }
+
+  /** Calculate all cutoffs from one supplied time; propagate repository failures to the calling boundary. */
+  async sweep(at: Date): Promise<OutboxRetentionResult> {
+    const { publishedRetentionMs, failedRetentionMs, receiptRetentionMs } = this.options
+    const published = await this.deleteBatches((size) =>
+      this.repository.deletePublishedBefore(new Date(at.getTime() - publishedRetentionMs), size),
+    )
+    const failed = await this.deleteBatches((size) =>
+      this.repository.deleteFailedBefore(new Date(at.getTime() - failedRetentionMs), size),
+    )
+    const receipts = await this.deleteBatches((size) =>
+      this.repository.deleteReceiptsBefore(new Date(at.getTime() - receiptRetentionMs), size),
+    )
+    return { published, failed, receipts }
+  }
+
+  private async deleteBatches(deleteBatch: (size: number) => Promise<number>): Promise<number> {
+    let total = 0
+    for (let batch = 0; batch < this.options.maxBatches; batch += 1) {
+      // oxlint-disable-next-line no-await-in-loop -- The delete count decides whether another batch is needed.
+      const deleted = await deleteBatch(this.options.batchSize)
+      total += deleted
+      if (deleted < this.options.batchSize) break
+    }
+    return total
+  }
+}

package/src/core/analytics-event.ts

@@ -0,0 +1,37 @@
+import { z } from 'zod'
+
+/** An event name and its application-owned properties, ported from Typist's analytics/types.ts. */
+export interface AnalyticsEventInput<
+  TName extends string = string,
+  TProperties extends object = object,
+> {
+  readonly name: TName
+  readonly properties: TProperties
+}
+
+/** A value supported by analytics person properties. */
+export type AnalyticsProperty =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | readonly AnalyticsProperty[]
+  | AnalyticsProperties
+
+/** Person properties supplied by the application. */
+export interface AnalyticsProperties {
+  readonly [name: string]: AnalyticsProperty
+}
+
+/** Parse a persisted analytics event UUID; the SDK generates ordinary event UUIDs itself. */
+export const AnalyticsEventIdSchema = z.uuid().brand<'AnalyticsEventId'>()
+
+/** The identity of one analytics event across repeated application deliveries. */
+export type AnalyticsEventId = z.infer<typeof AnalyticsEventIdSchema>
+
+/** Supply both original values when replaying one event; never share them across different occurrences. */
+export interface AnalyticsEventIdentity {
+  readonly uuid: AnalyticsEventId
+  readonly timestamp: Date
+}

package/src/core/backoff.ts

@@ -21,7 +21,12 @@ export function exponentialEqualJitterMs(
   return Math.floor(halfCapMs) + spreadJitterMs(halfCapMs)
 }
 
-function exponentialDelayCapMs(baseDelayMs: number, maxDelayMs: number, attempt: number): number {
+/** Capped exponential delay for a durable retry recorded in storage. */
+export function exponentialDelayCapMs(
+  baseDelayMs: number,
+  maxDelayMs: number,
+  attempt: number,
+): number {
   if (!Number.isSafeInteger(attempt) || attempt < 1) {
     return panic('attempt must be a positive integer')
   }

package/src/core/index.ts

@@ -1,4 +1,13 @@
 export { AppError } from './app-error.ts'
+export { MissingConfigurationError } from './missing-configuration.error.ts'
+export {
+  AnalyticsEventIdSchema,
+  type AnalyticsEventId,
+  type AnalyticsEventIdentity,
+  type AnalyticsEventInput,
+  type AnalyticsProperties,
+  type AnalyticsProperty,
+} from './analytics-event.ts'
 export { EmailAddressSchema, type EmailAddress } from './email-address.ts'
 export {
   emailIdempotencyKey,
@@ -88,7 +97,7 @@ export {
   retryAfterSecondsOf,
   type BoundaryErrorClassifier,
 } from './classify-failure.ts'
-export { exponentialEqualJitterMs, spreadJitterMs } from './backoff.ts'
+export { exponentialDelayCapMs, exponentialEqualJitterMs, spreadJitterMs } from './backoff.ts'
 export {
   configureLogger,
   consoleSink,

package/src/core/missing-configuration.error.ts

@@ -0,0 +1,12 @@
+import { AppError } from './app-error.ts'
+
+/** Required configuration is absent. Ported from Porte's configuration.errors.ts. */
+export class MissingConfigurationError extends AppError {
+  readonly _tag = 'MissingConfigurationError'
+  readonly classification = 'terminal'
+
+  /** Name the missing setting without including its value. */
+  constructor(readonly key: string) {
+    super(`${key} is required`)
+  }
+}