better-ship 0.17.0 → 0.19.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/index.ts

@@ -1,6 +1,2 @@
-export { WebhookHandler } from './webhook-handler.ts'
-export {
-  WebhookVerificationError,
-  type WebhookVerification,
-  type WebhookVerifier,
-} from './webhook-verification.ts'
+export { WebhookHandler, type WebhookHandlerOptions } from './webhook-handler.ts'
+export { WebhookVerificationError, type WebhookVerifier } from './webhook-verification.ts'

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

@@ -4,28 +4,85 @@ import { createLogger, type Logger } from '@/core'
 
 import { WebhookVerificationError, type WebhookVerifier } from './webhook-verification.ts'
 
+/** Application policy and diagnostics for one webhook body. */
+export type WebhookHandlerOptions = {
+  readonly maxBodyBytes: number
+  readonly logger?: Pick<Logger, 'warn'>
+}
+
 /** Read raw webhook requests and acknowledge effects only after the callback completes. */
-export class WebhookHandler<Event> {
-  /** Inject provider verification and an optional logger with the application's module name. */
+export class WebhookHandler<Verified> {
+  private readonly logger: Pick<Logger, 'warn'>
+  private readonly maxBodyBytes: number
+
+  /** Inject provider verification, the application body limit, and optional diagnostics. */
   constructor(
-    private readonly verifier: WebhookVerifier<Event>,
-    private readonly logger: Pick<Logger, 'warn'> = createLogger('webhook'),
-  ) {}
+    private readonly verifier: WebhookVerifier<Verified>,
+    options: WebhookHandlerOptions,
+  ) {
+    this.logger = options.logger ?? createLogger('webhook')
+    this.maxBodyBytes = options.maxBodyBytes
+  }
 
   /**
-   * Return 401 for authentication failure, 400 for invalid content, and 200 after callback completion or an ignored event.
+   * Return 413 for large content, 401 for authentication failure, 400 for invalid content, and 200 after callback completion or an ignored event.
    * Operational and callback failures propagate to the route's error boundary without an acknowledgment.
    */
-  async handle(request: Request, onEvent: (event: Event) => Promise<void>): Promise<Response> {
-    const body = await request.text()
-    const result = await this.verifier.verify(body, request.headers)
-    if (result.outcome === 'rejected') return this.reject(result.error)
-    if (result.outcome === 'event') await onEvent(result.event)
+  async handle(
+    request: Request,
+    onVerified: (value: Verified) => Promise<void>,
+  ): Promise<Response> {
+    const body = await this.readBody(request)
+    if (body === null) return this.rejectBodyTooLarge()
+    let verified: Verified | null
+    try {
+      verified = await this.verifier.verify(body, request.headers)
+    } catch (cause) {
+      if (cause instanceof WebhookVerificationError) return this.reject(cause)
+      throw cause
+    }
+    if (verified !== null) await onVerified(verified)
     return new Response(null, { status: StatusCodes.OK })
   }
 
+  private async readBody(request: Request): Promise<string | null> {
+    const contentLength = request.headers.get('content-length')
+    if (contentLength !== null && /^\d+$/.test(contentLength)) {
+      if (Number(contentLength) > this.maxBodyBytes) return null
+    }
+    if (request.body === null) return ''
+
+    const reader = request.body.getReader()
+    const decoder = new TextDecoder()
+    let body = ''
+    let byteCount = 0
+    try {
+      while (true) {
+        const chunk = await reader.read()
+        if (chunk.done) return body + decoder.decode()
+        byteCount += chunk.value.byteLength
+        if (byteCount > this.maxBodyBytes) {
+          try {
+            await reader.cancel()
+          } catch {
+            // A cancellation failure must not replace the body-size rejection.
+          }
+          return null
+        }
+        body += decoder.decode(chunk.value, { stream: true })
+      }
+    } finally {
+      reader.releaseLock()
+    }
+  }
+
+  private rejectBodyTooLarge(): Response {
+    this.logger.warn('webhook_rejected', { reason: 'body_too_large' })
+    return new Response(null, { status: StatusCodes.REQUEST_TOO_LONG })
+  }
+
   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/http/webhook-verification.ts

@@ -14,14 +14,11 @@ export class WebhookVerificationError extends AppError {
   }
 }
 
-/** A verified event, an ignored event, or an invalid request. */
-export type WebhookVerification<Event> =
-  | { readonly outcome: 'event'; readonly event: Event }
-  | { readonly outcome: 'ignored'; readonly type: string }
-  | { readonly outcome: 'rejected'; readonly error: WebhookVerificationError }
-
 /** The provider owns signature verification, timestamp tolerance, and payload parsing. */
-export interface WebhookVerifier<Event> {
-  /** Verify the exact body before parsing it. Return invalid requests; throw operational failures. */
-  verify(body: string, headers: Headers): Promise<WebhookVerification<Event>>
+export interface WebhookVerifier<Verified> {
+  /**
+   * Verify the exact body before parsing it. Return null for an ignored webhook.
+   * @throws WebhookVerificationError when the request cannot be trusted or parsed.
+   */
+  verify(body: string, headers: Headers): Promise<Verified | null>
 }

package/src/infrastructure/resend/email-event.ts

@@ -93,50 +93,34 @@ const EventHeaderSchema = z.object({
 })
 
 /** Validate signed provider data before projecting it into the public event contract. */
-export function parseEmailEvent(
-  payload: WebhookEventPayload,
-  id: string,
-):
-  | { readonly outcome: 'event'; readonly event: EmailEvent }
-  | { readonly outcome: 'ignored'; readonly type: string }
-  | { readonly outcome: 'invalid' } {
-  const header = EventHeaderSchema.safeParse(payload)
-  if (!header.success) return { outcome: 'invalid' }
-  if (!Object.hasOwn(EMAIL_TYPES, header.data.type))
-    return { outcome: 'ignored', type: header.data.type }
-  const parsed = EmailPayloadSchema.safeParse(payload)
-  if (!parsed.success) return { outcome: 'invalid' }
-  const event = parsed.data
+export function parseEmailEvent(payload: WebhookEventPayload, id: string): EmailEvent | null {
+  const header = EventHeaderSchema.parse(payload)
+  if (!Object.hasOwn(EMAIL_TYPES, header.type)) return null
+  const event = EmailPayloadSchema.parse(payload)
   const base: EmailEventBase = {
     id,
     emailId: event.data.email_id,
     recipients: event.data.to,
     subject: event.data.subject,
     tags: event.data.tags,
-    occurredAt: header.data.created_at,
+    occurredAt: header.created_at,
   }
   switch (event.type) {
     case 'email.bounced':
       return {
-        outcome: 'event',
-        event: {
-          ...base,
-          type: event.type,
-          bounce: {
-            type: parseBounceType(event.data.bounce.type),
-            subType: event.data.bounce.subType ?? null,
-            message: event.data.bounce.message,
-          },
+        ...base,
+        type: event.type,
+        bounce: {
+          type: parseBounceType(event.data.bounce.type),
+          subType: event.data.bounce.subType ?? null,
+          message: event.data.bounce.message,
         },
       }
     case 'email.failed':
-      return {
-        outcome: 'event',
-        event: { ...base, type: event.type, reason: event.data.failed.reason },
-      }
+      return { ...base, type: event.type, reason: event.data.failed.reason }
     case 'email.clicked':
-      return { outcome: 'event', event: { ...base, type: event.type, link: event.data.click.link } }
+      return { ...base, type: event.type, link: event.data.click.link }
     default:
-      return { outcome: 'event', event: { ...base, type: event.type } }
+      return { ...base, type: event.type }
   }
 }

package/src/infrastructure/resend/resend-webhook.ts

@@ -1,11 +1,7 @@
 import type { Resend } from 'resend'
 import { z } from 'zod'
 
-import {
-  WebhookVerificationError,
-  type WebhookVerification,
-  type WebhookVerifier,
-} from '../http/webhook-verification.ts'
+import { WebhookVerificationError, type WebhookVerifier } from '../http/webhook-verification.ts'
 import { parseEmailEvent, type EmailEvent } from './email-event.ts'
 
 // Separate standardwebhooks versions have different prototypes; its error name remains the same.
@@ -35,13 +31,12 @@ export class ResendWebhook implements WebhookVerifier<EmailEvent> {
     private readonly verifier: () => Promise<ResendWebhookClient>,
   ) {}
 
-  /** Verify the raw body and Svix headers. Invalid requests return rejected; configuration and SDK defects propagate. */
-  async verify(body: string, headers: Headers): Promise<WebhookVerification<EmailEvent>> {
+  /** Verify the raw body and Svix headers. Invalid requests throw typed errors; other failures propagate. */
+  async verify(body: string, headers: Headers): Promise<EmailEvent | null> {
     const id = headers.get('svix-id')
     const timestamp = headers.get('svix-timestamp')
     const signature = headers.get('svix-signature')
-    if (!id || !timestamp || !signature)
-      return { outcome: 'rejected', error: new WebhookVerificationError('missing_headers') }
+    if (!id || !timestamp || !signature) throw new WebhookVerificationError('missing_headers')
     const client = await (this.client ??= this.verifier())
     let payload: ReturnType<ResendWebhookClient['verify']>
     try {
@@ -51,20 +46,15 @@ export class ResendWebhook implements WebhookVerifier<EmailEvent> {
         webhookSecret: this.webhookSecret,
       })
     } catch (cause) {
-      if (cause instanceof SyntaxError)
-        return {
-          outcome: 'rejected',
-          error: new WebhookVerificationError('invalid_payload', cause),
-        }
+      if (cause instanceof SyntaxError) throw new WebhookVerificationError('invalid_payload', cause)
       if (!SignatureErrorSchema.safeParse(cause).success) throw cause
-      return {
-        outcome: 'rejected',
-        error: new WebhookVerificationError('invalid_signature', cause),
-      }
+      throw new WebhookVerificationError('invalid_signature', cause)
+    }
+    try {
+      return parseEmailEvent(payload, id)
+    } catch (cause) {
+      if (cause instanceof z.ZodError) throw new WebhookVerificationError('invalid_payload', cause)
+      throw cause
     }
-    const result = parseEmailEvent(payload, id)
-    if (result.outcome === 'invalid')
-      return { outcome: 'rejected', error: new WebhookVerificationError('invalid_payload') }
-    return result
   }
 }

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