better-ship 0.16.0 → 0.18.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://www.schemastore.org/package.json",
   "name": "better-ship",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Foundation for applications on Cloudflare Workers: logger, errors, message bus, infrastructure adapters, and UI primitives",
   "license": "Apache-2.0",
   "repository": {
@@ -22,11 +22,16 @@
     "./better-auth/rate-limit": "./dist/better-auth/rate-limit.js",
     "./better-auth/secondary-storage": "./dist/better-auth/secondary-storage.js",
     "./better-auth/stripe": "./dist/better-auth/stripe.js",
+    "./billing/client": "./dist/billing/client.js",
     "./cloudflare": "./dist/cloudflare.js",
     "./cloudflare/auth-secondary-storage": "./dist/cloudflare/auth-secondary-storage.js",
     "./cloudflare/durable-object-client": "./dist/cloudflare/durable-object-client.js",
     "./cloudflare/durable-object-errors": "./dist/cloudflare/durable-object-errors.js",
+    "./cloudflare/kv-client": "./dist/cloudflare/kv-client.js",
+    "./cloudflare/kv-errors": "./dist/cloudflare/kv-errors.js",
     "./cloudflare/queue": "./dist/cloudflare/queue.js",
+    "./cloudflare/r2-client": "./dist/cloudflare/r2-client.js",
+    "./cloudflare/r2-errors": "./dist/cloudflare/r2-errors.js",
     "./cloudflare/scheduled": "./dist/cloudflare/scheduled.js",
     "./core": "./dist/core.js",
     "./http": "./dist/http.js",
@@ -39,9 +44,13 @@
     "./sentry/client": "./dist/sentry/client.js",
     "./sentry/server": "./dist/sentry/server.js",
     "./sentry/vite": "./dist/sentry/vite.js",
+    "./stripe/payment-service": "./dist/stripe/payment-service.js",
+    "./stripe/payment-service.error": "./dist/stripe/payment-service.error.js",
+    "./stripe/payment-webhook": "./dist/stripe/payment-webhook.js",
     "./tanstack": "./dist/tanstack.js",
     "./tanstack/server": "./dist/tanstack/server.js",
     "./testing/outbox-repository": "./dist/testing/outbox-repository.js",
+    "./testing/payment-service": "./dist/testing/payment-service.js",
     "./ui": "./dist/ui.js",
     "./package.json": "./package.json"
   },
@@ -52,11 +61,11 @@
     "better-result": "^3.0.1",
     "http-status-codes": "^2.3.0",
     "uuid": "^14.0.2",
-    "zod": "^4.6.2"
+    "zod": "^4.6.4"
   },
   "devDependencies": {
     "@better-auth/stripe": "^1.7.4",
-    "@cloudflare/vitest-plugin": "^1.1.7",
+    "@cloudflare/vitest-plugin": "^1.1.8",
     "@cloudflare/workers-types": "5.20260911.1",
     "@posthog/react": "^1.10.6",
     "@sentry/cloudflare": "^10.74.0",
@@ -74,7 +83,7 @@
     "drizzle-orm": "^0.45.2",
     "playwright": "^1.63.0",
     "postgres": "^3.4.9",
-    "posthog-js": "^1.430.2",
+    "posthog-js": "^1.430.3",
     "posthog-node": "^5.52.1",
     "react": "^19.3.0",
     "resend": "^6.28.0",
@@ -83,7 +92,7 @@
     "tsdown": "^0.23.0",
     "typescript": "^7.0.2",
     "vitest": "^4.1.11",
-    "wrangler": "^4.131.0"
+    "wrangler": "^4.131.1"
   },
   "peerDependencies": {
     "@better-auth/stripe": "^1.7.4",
@@ -94,7 +103,7 @@
     "@tanstack/react-start": "^1.168.52",
     "better-auth": "^1.7.4",
     "drizzle-orm": "^0.45.2",
-    "posthog-js": "^1.430.2",
+    "posthog-js": "^1.430.3",
     "posthog-node": "^5.52.1",
     "react": "^19.3.0",
     "resend": "^6.28.0",

package/src/application/outbox-relay.ts

@@ -119,7 +119,9 @@ export class OutboxRelay {
     await this.repository.deadLetter(claim, messages, reason, errorMessage)
     logger.error('outbox_messages_dead_lettered', {
       error: cause,
-      details: { claimToken: claim.token, count: messages.length, reason },
+      claimToken: claim.token,
+      count: messages.length,
+      reason,
     })
   }
 }

package/src/core/console-log-sink.ts

@@ -0,0 +1,65 @@
+import type { LogEntry, LogFields, LogFormat, LogLevel, LogSink } from './logger.ts'
+
+const METHOD = {
+  DEBUG: 'debug',
+  INFO: 'info',
+  WARN: 'warn',
+  ERROR: 'error',
+} as const satisfies Record<LogLevel, 'debug' | 'info' | 'warn' | 'error'>
+
+const ESC = String.fromCharCode(27)
+const RESET = `${ESC}[0m`
+const LEVEL_COLOR = {
+  DEBUG: `${ESC}[2;36m`,
+  INFO: `${ESC}[34m`,
+  WARN: `${ESC}[33m`,
+  ERROR: `${ESC}[1;31m`,
+} satisfies Record<LogLevel, string>
+
+let format: LogFormat = 'json'
+
+export function setConsoleLogFormat(value: LogFormat): void {
+  format = value
+}
+
+function contextOf(entry: LogEntry): LogFields | undefined {
+  const context = { ...entry.attributes }
+  if (entry.userId !== undefined) context.userId = entry.userId
+  return Object.keys(context).length === 0 ? undefined : context
+}
+
+function jsonEntry(entry: LogEntry): LogEntry {
+  if (!(entry.error instanceof Error)) return entry
+  const error = { name: entry.error.name, message: entry.error.message, stack: entry.error.stack }
+  return { ...entry, error }
+}
+
+/** Write one structured record or one readable development entry to `console`. */
+export const consoleSink: LogSink = (entry) => {
+  const write = console[METHOD[entry.level]]
+  if (format === 'json') {
+    write(jsonEntry(entry))
+    return
+  }
+
+  const context = contextOf(entry)
+  const values = context === undefined ? [] : [context]
+  const errors = entry.error === undefined ? [] : [entry.error]
+  if (format === 'pretty-browser') {
+    write(
+      `%c${entry.timestamp}%c [${entry.level}] %c[${entry.module}]%c ${entry.event}`,
+      'color: #737373',
+      '',
+      'color: #2563eb',
+      '',
+      ...values,
+      ...errors,
+    )
+    return
+  }
+  write(
+    `${ESC}[90m${entry.timestamp}${RESET} ${LEVEL_COLOR[entry.level]}[${entry.level}]${RESET} ${ESC}[34m[${entry.module}]${RESET} ${entry.event}`,
+    ...values,
+    ...errors,
+  )
+}

package/src/core/index.ts

@@ -104,20 +104,17 @@ export {
   configureLogger,
   consoleSink,
   createLogger,
-  Logger,
   LogLevel,
   setLoggerErrorHook,
   setLogSink,
   type ErrorCaptureEntry,
-  type ErrorLogContext,
   type LogEntry,
   type LogFields,
   type LogFormat,
-  type LoggerConfig,
+  type Logger,
   type LoggerErrorHook,
   type LoggerSettings,
   type LogSink,
   type LogThreshold,
   type LogValue,
-  type SerializedError,
 } from './logger.ts'

package/src/core/logger.ts

@@ -1,28 +1,19 @@
-/**
- * Module-scoped logging for every host.
- *
- * A logger emits one plain-data entry per log. The default sink hands it to `console` as an
- * entry object for a log service or as a colored line for a person, selected at startup.
- */
+import { consoleSink, setConsoleLogFormat } from './console-log-sink.ts'
 
-/** A value a log entry may carry. Errors enter only through `Logger.error`. */
+/** One JSON-compatible value in a normal log field. */
 export type LogValue =
   | string
   | number
   | boolean
   | null
-  | undefined
-  | ReadonlyArray<LogValue>
-  | LogFields
+  | readonly LogValue[]
+  | { readonly [key: string]: LogValue }
 
-/** Named log values. */
-export type LogFields = { readonly [key: string]: LogValue }
+/** Flat fields for one log call. Only `error` can contain an arbitrary value. */
+// oxlint-disable-next-line anti-slop/no-unsafe-dictionary-type -- A logger accepts caller-owned fields at its public boundary.
+export type LogFields = Readonly<Record<string, unknown>>
 
-/**
- * The supported log severity levels, in ascending order.
- *
- * A const object, not an enum, so a parsed environment value typed `'INFO'` is a `LogLevel`.
- */
+/** Supported log levels in ascending order. */
 export const LogLevel = {
   DEBUG: 'DEBUG',
   INFO: 'INFO',
@@ -31,303 +22,111 @@ export const LogLevel = {
 } as const
 export type LogLevel = (typeof LogLevel)[keyof typeof LogLevel]
 
-/** An error as plain data, including diagnostics, causes, and aggregate members. */
-export type SerializedError = {
-  readonly name: string
-  readonly message: string
-  readonly stack?: string
-  readonly fields?: LogFields
-  readonly cause?: SerializedError
-  readonly errors?: ReadonlyArray<SerializedError>
+/** The minimum emitted level, or `OFF` for no console output. */
+export type LogThreshold = LogLevel | 'OFF'
+
+/** Explicit output formats for production, browser development, and terminal development. */
+export type LogFormat = 'json' | 'pretty-browser' | 'pretty-terminal'
+
+/** Process-wide logger settings supplied at startup. */
+export interface LoggerSettings {
+  readonly level?: LogThreshold
+  readonly format?: LogFormat
 }
 
-/** One log, as the sink receives it. Plain data, safe to stringify. */
+/** One structured record sent to a log sink. */
 export type LogEntry = {
   readonly timestamp: string
   readonly level: LogLevel
   readonly module: string
-  readonly message: string
-  readonly details: LogFields
+  readonly event: string
+  // oxlint-disable-next-line anti-slop/no-unsafe-dictionary-type -- The entry keeps caller-owned fields for its sink.
+  readonly attributes: LogFields
   readonly userId?: string
-  /** Present on `Logger.error` entries that carried an error. */
-  readonly error?: SerializedError
-}
-
-/** The context an error log carries. */
-export type ErrorLogContext = {
   readonly error?: unknown
-  readonly userId?: string
-  readonly details?: LogFields
-}
-
-/** What a logger lets through: a level and everything above it, or nothing. */
-export type LogThreshold = LogLevel | 'OFF'
-
-/** Overrides the application settings for one logger. */
-export interface LoggerConfig {
-  readonly level?: LogThreshold
-}
-
-/** `json` writes the entry object. `pretty` writes one readable line for a person. */
-export type LogFormat = 'json' | 'pretty'
-
-/**
- * The application settings, set once at the composition root.
- *
- * An omitted field keeps its default. An explicit `undefined` is a compile error, so the root
- * parses an environment value before passing it. The logger reads no environment itself.
- */
-export interface LoggerSettings extends LoggerConfig {
-  readonly format?: LogFormat
-}
-
-// The production server setting, so a root that never configures still logs safely.
-const DEFAULT_SETTINGS: Required<LoggerSettings> = {
-  level: LogLevel.INFO,
-  format: 'json',
-}
-
-// The application configures once at startup; loggers can exist before startup completes.
-let settings = DEFAULT_SETTINGS
-
-/**
- * Set application settings, including for existing loggers. Per-logger overrides take priority.
- * Call at startup, never per request. An omitted field resets to INFO and JSON output.
- */
-export function configureLogger(config: LoggerSettings): void {
-  settings = {
-    level: config.level ?? DEFAULT_SETTINGS.level,
-    format: config.format ?? DEFAULT_SETTINGS.format,
-  }
 }
 
-/** The error data sent to the configured error hook. */
+/** The original error and fields sent to an error service. */
 export interface ErrorCaptureEntry {
   readonly error: unknown
-  readonly distinctId: string | undefined
-  readonly context: LogFields
+  readonly userId: string | undefined
+  // oxlint-disable-next-line anti-slop/no-unsafe-dictionary-type -- Sentry accepts the caller-owned fields as extra context.
+  readonly attributes: LogFields
 }
 
-/** A function that forwards one logged error to an error service. */
+/** A function that forwards one error to an error service. */
 export type LoggerErrorHook = (entry: ErrorCaptureEntry) => void
 
-/** Where every log entry goes. */
+/** A destination for structured log records. */
 export type LogSink = (entry: LogEntry) => void
 
-let errorHook: LoggerErrorHook | null = null
-
-/**
- * Register the function that receives each logged error.
- *
- * Set once at the process entry point. A later call replaces the earlier hook.
- */
-export function setLoggerErrorHook(fn: LoggerErrorHook): void {
-  errorHook = fn
+/** The common flat logger API for all levels. */
+export interface Logger {
+  debug(event: string, fields?: LogFields): void
+  info(event: string, fields?: LogFields): void
+  warn(event: string, fields?: LogFields): void
+  error(event: string, fields?: LogFields): void
 }
 
-// One console method per level, so a host that filters by method can tell them apart.
-const CONSOLE_METHOD = {
-  [LogLevel.DEBUG]: 'debug',
-  [LogLevel.INFO]: 'info',
-  [LogLevel.WARN]: 'warn',
-  [LogLevel.ERROR]: 'error',
-} as const satisfies Record<LogLevel, 'debug' | 'info' | 'warn' | 'error'>
-
-// Built from the code point so no raw control character sits in the source.
-const ESC = String.fromCharCode(27)
-const ANSI_RESET = `${ESC}[0m`
-const ANSI_GRAY = `${ESC}[90m`
-const ANSI_BLUE = `${ESC}[34m`
-
-// Severity reads at a glance: quiet levels stay dim, and an error is the only bold line.
-const LEVEL_ANSI = {
-  DEBUG: `${ESC}[2;36m`,
-  INFO: ANSI_BLUE,
-  WARN: `${ESC}[33m`,
-  ERROR: `${ESC}[1;31m`,
-} satisfies Record<LogLevel, string>
+const LEVELS = Object.values(LogLevel)
+let threshold: LogThreshold = LogLevel.INFO
+let logSink: LogSink = consoleSink
+let errorHook: LoggerErrorHook | null = null
 
-function prettyLine(entry: LogEntry): string {
-  // Node prints debug and info exactly like log, so the level must be in the text too.
-  const level = `[${entry.level}]`
-  const module = `[${entry.module}]`
-  // A browser console colors by method on its own; a terminal needs ANSI to do the same.
-  if ('window' in globalThis) return `${entry.timestamp} ${level} ${module} ${entry.message}`
-  const timestamp = `${ANSI_GRAY}${entry.timestamp}${ANSI_RESET}`
-  const coloredLevel = `${LEVEL_ANSI[entry.level]}${level}${ANSI_RESET}`
-  const coloredModule = `${ANSI_BLUE}${module}${ANSI_RESET}`
-  return `${timestamp} ${coloredLevel} ${coloredModule} ${entry.message}`
+/** Set the process-wide level and output format. Omitted fields restore production defaults. */
+export function configureLogger(settings: LoggerSettings): void {
+  threshold = settings.level ?? LogLevel.INFO
+  setConsoleLogFormat(settings.format ?? 'json')
 }
 
-/**
- * JSON format writes the entry object. Pretty format writes one line, then the details,
- * the error, and the stack as separate console arguments.
- */
-export const consoleSink: LogSink = (entry) => {
-  // Resolved per call, so a console replaced after import still receives the output.
-  const write = console[CONSOLE_METHOD[entry.level]]
-  if (settings.format === 'json') {
-    write(entry)
-    return
-  }
-  const line = prettyLine(entry)
-  const fields =
-    entry.userId === undefined ? entry.details : { ...entry.details, userId: entry.userId }
-  const details = Object.keys(fields).length === 0 ? [] : [fields]
-  if (entry.error === undefined) {
-    write(line, ...details)
-    return
-  }
-  // A stack inside an object prints as one quoted string; as its own argument it prints as lines.
-  const { stack, ...error } = entry.error
-  if (stack === undefined) write(line, ...details, error)
-  else write(line, ...details, error, `\n${stack}`)
+/** Set the process-wide log destination. */
+export function setLogSink(sink: LogSink): void {
+  logSink = sink
 }
 
-let logSink: LogSink = consoleSink
-
-/**
- * Send every log entry somewhere other than `console`.
- *
- * Set once at the process entry point, never per module. A logger is created
- * by name and nothing else, so its destination is a fact about the process.
- */
-export function setLogSink(fn: LogSink): void {
-  logSink = fn
+/** Set or clear the process-wide error service hook. */
+export function setLoggerErrorHook(hook: LoggerErrorHook | null): void {
+  errorHook = hook
 }
 
-const LOG_LEVELS = Object.values(LogLevel)
-const MAX_ERROR_DEPTH = 3
-
-/**
- * Diagnostics worth keeping off an error, named one by one.
- *
- * An allowlist rather than every own property: an error raised by a library we
- * do not control may hang a request or a user payload off itself, and a log is
- * the wrong place to discover that. `_tag` and `classification` are what every `AppError`
- * declares. `remote` and the three flags after it are the ones workerd sets itself.
- */
-const KEPT_ERROR_FIELDS = [
-  '_tag',
-  'classification',
-  'code',
-  'operation',
-  'status',
-  'statusCode',
-  'remote',
-  'retryable',
-  'overloaded',
-  'durableObjectReset',
-] as const
-
-type ErrorDiagnostics = Error & { readonly [K in (typeof KEPT_ERROR_FIELDS)[number]]?: LogValue }
-
-type MutableSerializedError = { -readonly [K in keyof SerializedError]: SerializedError[K] }
-
-const serializeError = (error: Error, depth = 0): SerializedError => {
-  if (depth > MAX_ERROR_DEPTH) return { name: 'Error', message: '[error nesting truncated]' }
-
-  // Every field is optional, so an `Error` is already one of these.
-  const carrier: ErrorDiagnostics = error
-  const kept = KEPT_ERROR_FIELDS.filter((key) => carrier[key] !== undefined)
-  const serialized: MutableSerializedError = { name: error.name, message: error.message }
-  if (error.stack !== undefined) serialized.stack = error.stack
-  if (kept.length > 0)
-    serialized.fields = Object.fromEntries(kept.map((key) => [key, carrier[key]]))
-  if (error.cause instanceof Error) serialized.cause = serializeError(error.cause, depth + 1)
-  else if (error.cause !== undefined)
-    serialized.cause = { name: 'Error', message: '[non-error cause]' }
-  if (error instanceof AggregateError) {
-    // oxlint-disable-next-line anti-slop/no-unknown-parameters -- AggregateError accepts arbitrary values; instanceof Error validates each member.
-    serialized.errors = error.errors.map((failure: unknown) =>
-      failure instanceof Error
-        ? serializeError(failure, depth + 1)
-        : { name: 'NonError', message: '[non-error aggregate member]' },
-    )
-  }
-  return serialized
+/* oxlint-disable anti-slop/no-runtime-typeof -- The logger validates its reserved userId field. */
+function splitFields(fields: LogFields): ErrorCaptureEntry {
+  const { error, userId, ...attributes } = fields
+  return { error, userId: typeof userId === 'string' ? userId : undefined, attributes }
 }
-
-/** Write module-scoped logs with application defaults and optional overrides. */
-export class Logger {
-  private readonly config: LoggerConfig
-
-  /** Create a logger for one module. */
-  constructor(
-    private readonly module: string,
-    overrideConfig?: LoggerConfig,
-  ) {
-    this.config = { ...overrideConfig }
-  }
-
-  private log(
-    level: LogLevel,
-    message: string,
-    details: LogFields,
-    error?: SerializedError,
-    userId?: string,
-  ): void {
-    const threshold = this.config.level ?? settings.level
-    if (threshold === 'OFF') return
-    if (LOG_LEVELS.indexOf(level) < LOG_LEVELS.indexOf(threshold)) return
-
-    let entry: LogEntry = {
-      timestamp: new Date().toISOString(),
-      level,
-      module: this.module,
-      message,
-      details,
-    }
-    if (userId !== undefined) entry = { ...entry, userId }
-    logSink(error === undefined ? entry : { ...entry, error })
-  }
-
-  /** Write a debug log. */
-  debug(message: string, details: LogFields = {}): void {
-    this.log(LogLevel.DEBUG, message, details)
-  }
-
-  /** Write an information log. */
-  info(message: string, details: LogFields = {}): void {
-    this.log(LogLevel.INFO, message, details)
-  }
-
-  /** Write a warning log. */
-  warn(message: string, details: LogFields = {}): void {
-    this.log(LogLevel.WARN, message, details)
+/* oxlint-enable anti-slop/no-runtime-typeof */
+
+function writeLog(module: string, level: LogLevel, event: string, fields: LogFields): void {
+  if (threshold === 'OFF' || LEVELS.indexOf(level) < LEVELS.indexOf(threshold)) return
+
+  const { error, userId, attributes } = splitFields(fields)
+  let entry: LogEntry = { timestamp: new Date().toISOString(), level, module, event, attributes }
+  if (userId !== undefined) entry = { ...entry, userId }
+  if (error !== undefined) entry = { ...entry, error }
+  try {
+    logSink(entry)
+  } catch {
+    // A diagnostic failure must not change application control flow.
   }
+}
 
-  /**
-   * Write an error log and send the error to the configured hook.
-   *
-   * The details say which call this was, and the error says what went wrong
-   * inside it. Both the entry and the error hook receive the supplied user ID.
-   */
-  error(message: string, context: ErrorLogContext = {}): void {
-    const details = context.details ?? {}
-    const thrown = context.error
-    let error: SerializedError | undefined
-    if (thrown instanceof Error) {
-      error = serializeError(thrown)
-    } else if (thrown !== undefined) {
-      // Not an `Error`, so there is no name or stack to keep, only its JSON form.
-      let json: string
+/** Create a logger for one module. */
+export function createLogger(module: string): Logger {
+  return {
+    debug: (event, fields = {}) => writeLog(module, LogLevel.DEBUG, event, fields),
+    info: (event, fields = {}) => writeLog(module, LogLevel.INFO, event, fields),
+    warn: (event, fields = {}) => writeLog(module, LogLevel.WARN, event, fields),
+    error: (event, fields = {}) => {
+      writeLog(module, LogLevel.ERROR, event, fields)
+      const capture = splitFields(fields)
+      if (errorHook === null || capture.error === undefined) return
       try {
-        json = JSON.stringify(thrown)
+        errorHook(capture)
       } catch {
-        json = '[non-serializable error]'
+        // An error service failure must not change application control flow.
       }
-      error = { name: 'NonError', message: json }
-    }
-    this.log(LogLevel.ERROR, message, details, error, context.userId)
-
-    if (errorHook !== null && thrown !== undefined) {
-      errorHook({ error: thrown, distinctId: context.userId, context: details })
-    }
+    },
   }
 }
 
-/** Create a logger for one module. */
-export function createLogger(module: string, config?: LoggerConfig): Logger {
-  return new Logger(module, config)
-}
+export { consoleSink }

package/src/infrastructure/better-auth/apple-client-secret.ts

@@ -56,7 +56,7 @@ export function generateAppleClientSecret(config: AppleKeyConfig): string {
   } catch (error) {
     if (!appleKeyFailureLogged) {
       appleKeyFailureLogged = true
-      logger.error('apple_private_key_invalid', { error, details: { keyId: config.appleKeyId } })
+      logger.error('apple_private_key_invalid', { error, keyId: config.appleKeyId })
     }
     return ''
   }

package/src/infrastructure/better-auth/rate-limit.ts

@@ -103,7 +103,9 @@ export function createAuthRateLimitStorage(
         if (failureMode === 'block') throw new AuthRateLimitError(cause)
         logger.error('rate_limit_binding_failed', {
           error: cause,
-          details: { window: rule.window, max: rule.max, failureMode },
+          window: rule.window,
+          max: rule.max,
+          failureMode,
         })
         return { allowed: true, retryAfter: null }
       }