better-ship 0.16.0 → 0.18.0

package/src/infrastructure/cloudflare/r2-errors.ts

@@ -0,0 +1,111 @@
+import { z } from 'zod'
+
+import { AppError, classifyBoundaryError, isAbortError, type FailureClassification } from '@/core'
+
+/** The storage operation that failed. */
+export type R2Operation =
+  | 'head'
+  | 'get'
+  | 'getJson'
+  | 'put'
+  | 'delete'
+  | 'list'
+  | 'createMultipartUpload'
+  | 'uploadPart'
+  | 'complete'
+  | 'abort'
+
+/** Provider diagnostics from the outer failure, without request bodies or credentials. */
+export type R2Failure = {
+  readonly code: number
+  readonly action?: string | undefined
+}
+
+const R2FailureSchema = z.object({
+  code: z.number().int().positive(),
+  action: z.string().optional(),
+})
+
+// R2 codes describe failures; the caller owns retry decisions and repeat safety.
+const classifications: ReadonlyMap<number, FailureClassification> = new Map([
+  [10001, 'transient'],
+  [10043, 'transient'],
+  [10054, 'transient'],
+  [10058, 'transient'],
+  [10013, 'transient'],
+  [10002, 'terminal'],
+  [10003, 'terminal'],
+  [10018, 'terminal'],
+  [10035, 'terminal'],
+  [10042, 'terminal'],
+  [10005, 'terminal'],
+  [10006, 'terminal'],
+  [10008, 'terminal'],
+  [10009, 'terminal'],
+  [10073, 'terminal'],
+  [10007, 'terminal'],
+  [10020, 'terminal'],
+  [100100, 'terminal'],
+  [10012, 'terminal'],
+  [10069, 'terminal'],
+  [10033, 'terminal'],
+  [10014, 'terminal'],
+  [10037, 'terminal'],
+  [10039, 'terminal'],
+  [10031, 'terminal'],
+  [10011, 'terminal'],
+  [10024, 'terminal'],
+  [10025, 'terminal'],
+  [10048, 'terminal'],
+])
+
+function extractR2Failure(cause: unknown): R2Failure | undefined {
+  if (!(cause instanceof Error)) return undefined
+  const parsed = R2FailureSchema.safeParse(cause)
+  if (parsed.success) return parsed.data
+  // Cloudflare documents the numeric suffix for bindings that omit structured fields.
+  const match = /\((\d{5,6})\)\s*$/.exec(cause.message)
+  return match?.[1] === undefined ? undefined : { code: Number(match[1]) }
+}
+
+function classifyR2Code(cause: unknown): FailureClassification | undefined {
+  const failure = extractR2Failure(cause)
+  return failure === undefined ? undefined : (classifications.get(failure.code) ?? 'unknown')
+}
+
+function classifyR2Error(cause: unknown): FailureClassification {
+  if (isAbortError(cause)) return 'terminal'
+  if (cause instanceof AppError) return cause.classification
+  return classifyBoundaryError({ cause, classifyBoundary: classifyR2Code, includeCloudflare: true })
+}
+
+/** A raw binding failure after one attempt. Classification does not establish whether a mutation committed. */
+export class R2Error extends AppError {
+  readonly _tag = 'R2Error'
+  readonly classification: FailureClassification
+  readonly operation: R2Operation
+  readonly r2?: R2Failure | undefined
+  override readonly cause: unknown
+
+  constructor(input: { operation: R2Operation; cause: unknown }) {
+    super(`R2 ${input.operation} failed`, { cause: input.cause })
+    this.operation = input.operation
+    this.cause = input.cause
+    this.r2 = extractR2Failure(input.cause)
+    this.classification = classifyR2Error(input.cause)
+  }
+}
+
+/** JSON serialization or syntax failed. Binding and body-read failures use R2Error. */
+export class R2JsonError extends AppError {
+  readonly _tag = 'R2JsonError'
+  readonly classification = 'terminal'
+  readonly operation: 'encode' | 'decode'
+  override readonly cause: unknown
+
+  constructor(input: { operation: 'encode' | 'decode'; cause: unknown }) {
+    super(`R2 JSON ${input.operation} failed`, { cause: input.cause })
+    this.operation = input.operation
+    this.cause = input.cause
+  }
+}

package/src/infrastructure/cloudflare/scheduled/scheduled-handler.ts

@@ -45,7 +45,7 @@ export function defineSchedules<const Schedules extends Readonly<Record<string,
     handler: (runs) => async (controller, deps) => {
       const { cron } = controller
       if (!schema.validate(cron)) {
-        logger.error('scheduled_unknown_cron', { details: { cron } })
+        logger.error('scheduled_unknown_cron', { cron })
         return
       }
       await runs[cron](deps, new Date(controller.scheduledTime))

package/src/infrastructure/http/webhook-handler.ts

@@ -25,7 +25,7 @@ export class WebhookHandler<Event> {
   }
 
   private reject(error: WebhookVerificationError): Response {
-    this.logger.warn('Webhook rejected', { reason: error.reason })
+    this.logger.warn('webhook_rejected', { reason: error.reason })
     const status =
       error.reason === 'missing_headers' || error.reason === 'invalid_signature'
         ? StatusCodes.UNAUTHORIZED

package/src/infrastructure/postgres/postgres-database-execution.ts

@@ -1,13 +1,34 @@
+import { Result } from 'better-result'
+
+import { DatabaseError } from '@/core'
+
 import { classifyPostgresError } from './classify-postgres-error.ts'
 
-/** Execute once without retries; convert recognized Postgres failures and preserve other exceptions unchanged. */
+/**
+ * Convert database failures and preserve other exceptions. The default executes once.
+ * Opt-in transient retries allow three attempts with full jitter and backoff caps of 250 ms and 500 ms.
+ */
 export async function executeDatabase<T>(
   operation: string,
   work: () => PromiseLike<T>,
+  options: { readonly retry?: 'never' | 'transient' } = {},
 ): Promise<T> {
-  try {
-    return await work()
-  } catch (cause) {
-    throw classifyPostgresError(cause, operation) ?? cause
-  }
+  const result = await Result.tryPromise(
+    {
+      try: async () => await work(),
+      catch: (cause) => classifyPostgresError(cause, operation) ?? cause,
+    },
+    {
+      retry: {
+        times: options.retry === 'transient' ? 2 : 0,
+        delayMs: 250,
+        backoff: 'exponential',
+        jitter: true,
+        shouldRetry: (error) =>
+          error instanceof DatabaseError && error.classification === 'transient',
+      },
+    },
+  )
+  if (result.isErr()) throw result.error
+  return result.value
 }

package/src/infrastructure/sentry/client.ts

@@ -27,10 +27,13 @@ export function createSentryClientOptions(options: SentryClientOptions): Sentry.
 
 /** Forward logged browser errors once, excluding TanStack navigation control flow. */
 export function createSentryLoggerErrorHook(): LoggerErrorHook {
-  return ({ error, context }) => {
+  return ({ error, userId, attributes }) => {
     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 })
+    if (userId !== undefined) {
+      Sentry.captureException(error, { extra: attributes, user: { id: userId } })
+      return
+    }
+    Sentry.captureException(error, { extra: attributes })
   }
 }
 

package/src/infrastructure/sentry/server.ts

@@ -26,12 +26,12 @@ export function createSentryOptions(options: SentryServerOptions): Sentry.Cloudf
 
 /** 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 ({ error, userId, attributes }) => {
+    if (userId !== undefined) {
+      Sentry.captureException(error, { extra: attributes, user: { id: userId } })
       return
     }
-    Sentry.captureException(error, { extra: context })
+    Sentry.captureException(error, { extra: attributes })
   }
 }
 

package/src/infrastructure/stripe/payment-service.error.ts

@@ -0,0 +1,42 @@
+import Stripe from 'stripe'
+
+import { AppError, type FailureClassification } from '@/core'
+
+/** A final Stripe request failure. The caller logs once; native details remain in cause. */
+export class PaymentServiceError extends AppError {
+  readonly _tag = 'PaymentServiceError'
+  readonly classification: FailureClassification
+
+  /** Classify the final SDK error without scheduling another payment attempt. */
+  constructor(
+    readonly operation: string,
+    cause: Stripe.errors.StripeError,
+  ) {
+    super(`Stripe request failed: ${operation}`, { cause })
+    this.classification = classifyStripeError(cause)
+  }
+}
+
+function classifyStripeError(error: Stripe.errors.StripeError): FailureClassification {
+  if (error.headers?.['stripe-should-retry'] === 'false') return 'terminal'
+  const status = error.statusCode
+  if (status !== undefined && status >= 400 && status < 500 && status !== 409 && status !== 429)
+    return 'terminal'
+  if (
+    error instanceof Stripe.errors.StripeAuthenticationError ||
+    error instanceof Stripe.errors.StripePermissionError ||
+    error instanceof Stripe.errors.StripeInvalidRequestError ||
+    error instanceof Stripe.errors.StripeIdempotencyError
+  )
+    return 'terminal'
+  if (error.headers?.['stripe-should-retry'] === 'true') return 'transient'
+  if (status === 409 || status === 429 || (status !== undefined && status >= 500))
+    return 'transient'
+  if (
+    error instanceof Stripe.errors.StripeConnectionError ||
+    error instanceof Stripe.errors.StripeAPIError ||
+    error instanceof Stripe.errors.StripeRateLimitError
+  )
+    return 'transient'
+  return 'unknown'
+}

package/src/infrastructure/stripe/payment-service.ts

@@ -0,0 +1,129 @@
+import Stripe from 'stripe'
+
+import { PaymentServiceError } from './payment-service.error.ts'
+
+/** Supply the same key and parameters when repeating one durable payment attempt. */
+export type PaymentRequestOptions = Stripe.RequestOptions &
+  Required<Pick<Stripe.RequestOptions, 'idempotencyKey'>>
+
+/** Native Checkout parameters; the service selects payment or setup mode. */
+export type CheckoutInput = Omit<Stripe.Checkout.SessionCreateParams, 'mode'>
+
+/** A saved customer method; the service confirms the payment off-session. */
+export type SavedMethodCharge = Omit<Stripe.PaymentIntentCreateParams, 'confirm' | 'off_session'> &
+  Required<Pick<Stripe.PaymentIntentCreateParams, 'customer' | 'payment_method'>>
+
+/** Native customer response, including Stripe request metadata. */
+export type CustomerResult = Awaited<ReturnType<Stripe['customers']['create']>>
+
+/** Native Checkout response. Its URL can be null; this does not confirm payment. */
+export type CheckoutResult = Awaited<ReturnType<Stripe['checkout']['sessions']['create']>>
+
+/** Native PaymentIntent response. Applications decide what each status permits. */
+export type PaymentResult = Awaited<ReturnType<Stripe['paymentIntents']['create']>>
+
+/**
+ * Stripe payment operations, with native types and stable keys for mutations.
+ * Rejects with PaymentServiceError or native StripeCardError; unexpected defects propagate.
+ */
+export interface IPaymentService {
+  /** Create a customer; the application owns persistence and reuse of the customer link. */
+  createCustomer(
+    input: Stripe.CustomerCreateParams,
+    options: PaymentRequestOptions,
+  ): Promise<CustomerResult>
+  /** Create one-time payment checkout; application fulfillment requires verified payment confirmation. */
+  createCheckout(input: CheckoutInput, options: PaymentRequestOptions): Promise<CheckoutResult>
+  /** Create checkout in setup mode. The application records consent and verifies the saved method's owner. */
+  setupPaymentMethod(input: CheckoutInput, options: PaymentRequestOptions): Promise<CheckoutResult>
+  /** Confirm a saved method off-session. Native card errors can require customer authentication. */
+  chargeSavedMethod(
+    input: SavedMethodCharge,
+    options: PaymentRequestOptions,
+  ): Promise<PaymentResult>
+  /** Retrieve an existing payment without starting another payment attempt. */
+  getPayment(
+    paymentId: string,
+    params?: Stripe.PaymentIntentRetrieveParams,
+    options?: Stripe.RequestOptions,
+  ): Promise<PaymentResult>
+}
+
+/**
+ * Ported from Typist's StripeClient request boundary; the native SDK now owns retries.
+ * Each request defaults to two SDK retries. Native request options can override retries and timeout.
+ */
+export class StripePaymentService implements IPaymentService {
+  /** Inject a native SDK instance; its transport, credentials, and API version remain caller-owned. */
+  constructor(private readonly stripe: Stripe) {}
+
+  /** Create a customer with a stable application key and preserve the native response. */
+  createCustomer(
+    input: Stripe.CustomerCreateParams,
+    options: PaymentRequestOptions,
+  ): Promise<CustomerResult> {
+    return this.request('customers.create', () =>
+      this.stripe.customers.create(input, { maxNetworkRetries: 2, ...options }),
+    )
+  }
+
+  /** Force payment mode after caller parameters; return the native Checkout Session. */
+  createCheckout(input: CheckoutInput, options: PaymentRequestOptions): Promise<CheckoutResult> {
+    return this.request('checkout.sessions.create', () =>
+      this.stripe.checkout.sessions.create(
+        { ...input, mode: 'payment' },
+        { maxNetworkRetries: 2, ...options },
+      ),
+    )
+  }
+
+  /** Force setup mode after caller parameters; this operation does not charge the customer. */
+  setupPaymentMethod(
+    input: CheckoutInput,
+    options: PaymentRequestOptions,
+  ): Promise<CheckoutResult> {
+    return this.request('checkout.sessions.create', () =>
+      this.stripe.checkout.sessions.create(
+        { ...input, mode: 'setup' },
+        { maxNetworkRetries: 2, ...options },
+      ),
+    )
+  }
+
+  /** Force confirmation and off-session use; preserve native card failures for application handling. */
+  chargeSavedMethod(
+    input: SavedMethodCharge,
+    options: PaymentRequestOptions,
+  ): Promise<PaymentResult> {
+    return this.request('paymentIntents.create', () =>
+      this.stripe.paymentIntents.create(
+        { ...input, confirm: true, off_session: true },
+        { maxNetworkRetries: 2, ...options },
+      ),
+    )
+  }
+
+  /** Preserve every native status and response field when reconciling an existing payment. */
+  getPayment(
+    paymentId: string,
+    params?: Stripe.PaymentIntentRetrieveParams,
+    options?: Stripe.RequestOptions,
+  ): Promise<PaymentResult> {
+    return this.request('paymentIntents.retrieve', () =>
+      this.stripe.paymentIntents.retrieve(paymentId, params, { maxNetworkRetries: 2, ...options }),
+    )
+  }
+
+  private async request<T>(operation: string, work: () => Promise<T>): Promise<T> {
+    try {
+      return await work()
+    } catch (cause) {
+      if (
+        !(cause instanceof Stripe.errors.StripeError) ||
+        cause instanceof Stripe.errors.StripeCardError
+      )
+        throw cause
+      throw new PaymentServiceError(operation, cause)
+    }
+  }
+}

package/src/infrastructure/stripe/payment-webhook.ts

@@ -0,0 +1,49 @@
+import Stripe from 'stripe'
+
+import {
+  WebhookVerificationError,
+  type WebhookVerification,
+  type WebhookVerifier,
+} from '../http/webhook-verification.ts'
+
+/**
+ * Authenticate raw Stripe webhook bodies with the SDK's timestamp tolerance and Web Crypto.
+ * Returns native events; application conversion owns event selection and payload validation.
+ */
+export class StripeWebhookVerifier implements WebhookVerifier<Stripe.Event> {
+  /** Supply the endpoint's signing secret. Tolerance defaults to Stripe's five-minute window. */
+  constructor(
+    private readonly stripe: Stripe,
+    private readonly signingSecret: string,
+    private readonly tolerance?: number,
+  ) {}
+
+  /** Reject signature and JSON failures. Operational failures propagate without logging. */
+  async verify(body: string, headers: Headers): Promise<WebhookVerification<Stripe.Event>> {
+    const signature = headers.get('stripe-signature')
+    if (!signature)
+      return { outcome: 'rejected', error: new WebhookVerificationError('missing_headers') }
+    try {
+      const event = await this.stripe.webhooks.constructEventAsync(
+        body,
+        signature,
+        this.signingSecret,
+        this.tolerance,
+        Stripe.createSubtleCryptoProvider(),
+      )
+      return { outcome: 'event', event }
+    } catch (cause) {
+      if (cause instanceof Stripe.errors.StripeSignatureVerificationError)
+        return {
+          outcome: 'rejected',
+          error: new WebhookVerificationError('invalid_signature', cause),
+        }
+      if (cause instanceof SyntaxError)
+        return {
+          outcome: 'rejected',
+          error: new WebhookVerificationError('invalid_payload', cause),
+        }
+      throw cause
+    }
+  }
+}

package/src/infrastructure/tanstack/resolve-failure.ts

@@ -14,11 +14,12 @@ export function resolveFailure<Entries>(
   const resolved = table.resolve(cause)
   if (resolved !== null) {
     logger.warn('handled_error', {
-      details: { tag: resolved.payload._tag, status: resolved.status },
+      tag: resolved.payload._tag,
+      status: resolved.status,
     })
     return resolved
   }
   const classification = cause instanceof AppError ? cause.classification : 'unknown'
-  logger.error('unexpected_error', { error: cause, details: { classification } })
+  logger.error('unexpected_error', { error: cause, classification })
   return table.fallback(cause)
 }

package/src/infrastructure/testing/payment-service-contract.ts

@@ -0,0 +1,91 @@
+import { deepStrictEqual, equal, rejects } from 'node:assert/strict'
+
+import Stripe from 'stripe'
+
+import type { IPaymentService } from '../stripe/payment-service.ts'
+
+/**
+ * Test a Stripe payment adapter through native fetch injection without live payments.
+ * Each case constructs a fresh SDK instance and adapter; no Vitest dependency is required.
+ */
+export function paymentServiceContract(
+  test: (name: string, run: () => Promise<void>) => void,
+  create: (stripe: Stripe) => IPaymentService,
+): void {
+  test('payment checkout selects payment mode and retains the supplied key', async () => {
+    const fixture = paymentFixture(create)
+    await fixture.service.createCheckout(
+      { customer: 'cus_contract' },
+      { idempotencyKey: 'checkout:contract' },
+    )
+    equal(fixture.requests[0]?.body.get('mode'), 'payment')
+    equal(fixture.requests[0]?.headers.get('idempotency-key'), 'checkout:contract')
+  })
+
+  test('payment method setup selects setup mode', async () => {
+    const fixture = paymentFixture(create)
+    await fixture.service.setupPaymentMethod(
+      { customer: 'cus_contract' },
+      { idempotencyKey: 'setup:contract' },
+    )
+    equal(fixture.requests[0]?.body.get('mode'), 'setup')
+  })
+
+  test('saved method payments confirm off-session', async () => {
+    const fixture = paymentFixture(create)
+    await fixture.service.chargeSavedMethod(
+      { amount: 1000, currency: 'usd', customer: 'cus_contract', payment_method: 'pm_contract' },
+      { idempotencyKey: 'charge:contract' },
+    )
+    equal(fixture.requests[0]?.body.get('confirm'), 'true')
+    equal(fixture.requests[0]?.body.get('off_session'), 'true')
+  })
+
+  test('payment reads preserve native statuses and response fields', async () => {
+    const fixture = paymentFixture(create)
+    const payment = await fixture.service.getPayment('pi_contract')
+    deepStrictEqual(
+      { id: payment.id, status: payment.status },
+      { id: 'pi_contract', status: 'requires_capture' },
+    )
+  })
+
+  test('card failures retain the native error contract', async () => {
+    const response = Response.json(
+      {
+        error: {
+          type: 'card_error',
+          code: 'authentication_required',
+          message: 'Authentication required',
+        },
+      },
+      { status: 402 },
+    )
+    const fixture = paymentFixture(create, response)
+    await rejects(
+      fixture.service.chargeSavedMethod(
+        { amount: 1000, currency: 'usd', customer: 'cus_contract', payment_method: 'pm_contract' },
+        { idempotencyKey: 'charge:contract' },
+      ),
+      Stripe.errors.StripeCardError,
+    )
+  })
+}
+
+function paymentFixture(
+  create: (stripe: Stripe) => IPaymentService,
+  response = Response.json({ id: 'pi_contract', status: 'requires_capture' }),
+) {
+  const requests: { headers: Headers; body: URLSearchParams }[] = []
+  const stripe = new Stripe('sk_test_contract', {
+    httpClient: Stripe.createFetchHttpClient(async (input, init) => {
+      const request = new Request(input, init)
+      requests.push({
+        headers: request.headers,
+        body: new URLSearchParams(new TextDecoder().decode(await request.arrayBuffer())),
+      })
+      return response.clone()
+    }),
+  })
+  return { service: create(stripe), requests }
+}