better-ship 0.17.0 → 0.18.0

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

@@ -0,0 +1,162 @@
+import { AppError, isAbortError } from '@/core'
+
+import { R2Error, R2JsonError, type R2Operation } from './r2-errors.ts'
+
+/** Values accepted by the R2 binding. */
+export type R2Value = Parameters<R2Bucket['put']>[1]
+
+/** Missing objects, failed conditions, and returned bodies are distinct outcomes. */
+export type R2GetResult =
+  | { status: 'missing' }
+  | { status: 'precondition-failed'; object: R2Object }
+  | { status: 'found'; object: R2ObjectBody }
+
+/** A failed condition does not establish whether an earlier attempt committed. */
+export type R2PutResult = { status: 'precondition-failed' } | { status: 'stored'; object: R2Object }
+
+/** Untrusted JSON data, with absence separate from a stored null. The application supplies its schema. */
+export type R2JsonResult = { status: 'missing' } | { status: 'found'; value: unknown }
+
+/**
+ * R2 access with one attempt per operation and typed failures. Inject the bucket at the composition root.
+ * Callers own retries, stream replay, and recovery. The client does not log or buffer streamed uploads.
+ */
+export class R2Client {
+  constructor(private readonly bucket: R2Bucket) {}
+
+  /** Read native metadata, or return null when the object does not exist. */
+  head(key: string): Promise<R2Object | null> {
+    return callR2('head', () => this.bucket.head(key))
+  }
+
+  /** Return a native body without consuming it. The consumer owns later body-read failures. */
+  async get(key: string, options?: R2GetOptions): Promise<R2GetResult> {
+    const object = await callR2('get', () => this.bucket.get(key, options))
+    if (object === null) return { status: 'missing' }
+    if (!('body' in object)) return { status: 'precondition-failed', object }
+    return { status: 'found', object }
+  }
+
+  /** Buffer one stored JSON body. Read failures throw R2Error; invalid JSON throws R2JsonError. */
+  async getJson(key: string): Promise<R2JsonResult> {
+    const text = await callR2('getJson', async () => {
+      const object = await this.bucket.get(key)
+      return object === null ? null : await object.text()
+    })
+    if (text === null) return { status: 'missing' }
+    try {
+      return { status: 'found', value: JSON.parse(text) }
+    } catch (cause) {
+      throw new R2JsonError({ operation: 'decode', cause })
+    }
+  }
+
+  /** Write once, including conditional writes. Pass streams directly to the binding. */
+  async put(key: string, body: R2Value, options?: R2PutOptions): Promise<R2PutResult> {
+    const object = await callR2('put', () => this.bucket.put(key, body, options))
+    return object === null ? { status: 'precondition-failed' } : { status: 'stored', object }
+  }
+
+  /** Serialize once and default the content type to application/json without changing caller options. */
+  async putJson(
+    key: string,
+    // oxlint-disable-next-line anti-slop/no-unknown-parameters -- This serialization boundary accepts any value and rejects values without a JSON representation.
+    value: unknown,
+    options?: R2PutOptions,
+  ): Promise<R2PutResult> {
+    let text: string | undefined
+    try {
+      text = JSON.stringify(value)
+    } catch (cause) {
+      throw new R2JsonError({ operation: 'encode', cause })
+    }
+    if (text === undefined) throw new R2JsonError({ operation: 'encode', cause: undefined })
+    return this.put(key, text, { ...options, httpMetadata: jsonMetadata(options?.httpMetadata) })
+  }
+
+  /** Delete keys in one binding call. Missing keys succeed; R2 enforces its batch limit. */
+  delete(keys: string | string[]): Promise<void> {
+    return callR2('delete', () => this.bucket.delete(keys))
+  }
+
+  /** Return one native page with the requested metadata, cursor, and delimiter results. */
+  list(options?: R2ListOptions): Promise<R2Objects> {
+    return callR2('list', () => this.bucket.list(options))
+  }
+
+  /** Create once. A failed response can leave an upload whose ID the caller never received. */
+  async createMultipartUpload(
+    key: string,
+    options?: R2MultipartOptions,
+  ): Promise<R2MultipartClient> {
+    const upload = await callR2('createMultipartUpload', () =>
+      this.bucket.createMultipartUpload(key, options),
+    )
+    return new R2MultipartClient(upload)
+  }
+
+  /** Construct a handle without I/O. Each subsequent operation checks whether the upload exists. */
+  resumeMultipartUpload(key: string, uploadId: string): R2MultipartClient {
+    return new R2MultipartClient(this.bucket.resumeMultipartUpload(key, uploadId))
+  }
+}
+
+/** An upload handle that binds its key and ID once. Every operation makes one attempt. */
+export class R2MultipartClient {
+  constructor(private readonly upload: R2MultipartUpload) {}
+
+  /** The destination object key. */
+  get key(): string {
+    return this.upload.key
+  }
+
+  /** The provider ID to persist when the application needs to resume this upload. */
+  get uploadId(): string {
+    return this.upload.uploadId
+  }
+
+  /** Upload one part without buffering or replaying its body. */
+  uploadPart(
+    partNumber: number,
+    body: Exclude<R2Value, null>,
+    options?: R2UploadPartOptions,
+  ): Promise<R2UploadedPart> {
+    return callR2('uploadPart', () => this.upload.uploadPart(partNumber, body, options))
+  }
+
+  /** Sort a copy of the parts and return native metadata after completion. Callers own uncertain outcomes. */
+  complete(parts: ReadonlyArray<R2UploadedPart>): Promise<R2Object> {
+    return callR2('complete', () =>
+      this.upload.complete([...parts].sort((a, b) => a.partNumber - b.partNumber)),
+    )
+  }
+
+  /** Ensure no active upload remains. NoSuchUpload succeeds; a completed object remains intact. */
+  async abort(): Promise<void> {
+    try {
+      await callR2('abort', () => this.upload.abort())
+    } catch (cause) {
+      if (cause instanceof R2Error && cause.operation === 'abort' && cause.r2?.code === 10024)
+        return
+      throw cause
+    }
+  }
+}
+
+async function callR2<T>(operation: R2Operation, work: () => Promise<T>): Promise<T> {
+  try {
+    return await work()
+  } catch (cause) {
+    if (isAbortError(cause) || cause instanceof AppError) throw cause
+    throw new R2Error({ operation, cause })
+  }
+}
+
+function jsonMetadata(metadata: R2HTTPMetadata | Headers | undefined): R2HTTPMetadata | Headers {
+  if (metadata instanceof Headers) {
+    const headers = new Headers(metadata)
+    if (!headers.has('content-type')) headers.set('content-type', 'application/json')
+    return headers
+  }
+  return { ...metadata, contentType: metadata?.contentType ?? 'application/json' }
+}

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