better-ship 0.16.0 → 0.18.0

package/src/infrastructure/billing/client.ts

@@ -0,0 +1,173 @@
+import type { stripeClient } from '@better-auth/stripe/client'
+import type { createAuthClient } from 'better-auth/client'
+
+import { AppError, type FailureClassification } from '@/core'
+
+type AuthClient = ReturnType<
+  typeof createAuthClient<{
+    plugins: [ReturnType<typeof stripeClient<{ subscription: true }>>]
+  }>
+>
+
+/** Native Better Auth subscription operations used by the browser billing service. */
+export type SubscriptionBillingClient = Pick<
+  AuthClient['subscription'],
+  'upgrade' | 'billingPortal'
+>
+
+/** Native upgrade input. Navigation remains with the UI. */
+export type ChangePlanInput = Omit<
+  NonNullable<Parameters<SubscriptionBillingClient['upgrade']>[0]>,
+  'disableRedirect'
+>
+
+/** Native portal input. Navigation remains with the UI. */
+export type BillingPortalInput = Omit<
+  NonNullable<Parameters<SubscriptionBillingClient['billingPortal']>[0]>,
+  'disableRedirect'
+>
+
+/** Native successful subscription response, including portal or Checkout data. */
+export type ChangePlanResult = NonNullable<
+  Awaited<ReturnType<SubscriptionBillingClient['upgrade']>>['data']
+>
+
+/** Native successful portal response. */
+export type BillingPortalResult = NonNullable<
+  Awaited<ReturnType<SubscriptionBillingClient['billingPortal']>>['data']
+>
+
+/** Native Better Auth billing failure; its code remains available to application UI. */
+export type BillingApiError = NonNullable<
+  Awaited<ReturnType<SubscriptionBillingClient['upgrade']>>['error']
+>
+
+/** A Better Auth billing endpoint rejected the request. The browser boundary owns reporting. */
+export class BillingRequestError extends AppError {
+  readonly _tag = 'BillingRequestError'
+  readonly classification: FailureClassification
+  readonly code: BillingApiError['code']
+
+  /** Preserve the native code and cause without copying provider metadata. */
+  constructor(
+    readonly operation: 'subscription.upgrade' | 'subscription.billingPortal',
+    cause: BillingApiError,
+  ) {
+    super('Billing request failed', { cause })
+    this.code = cause.code
+    this.classification = cause.status === 429 || cause.status >= 500 ? 'transient' : 'terminal'
+  }
+}
+
+// oxlint-disable-next-line anti-slop/no-unknown-returns -- Generic constraint only; service methods retain each callback's exact return type.
+type BillingCallback = (this: void, ...args: never[]) => Promise<unknown>
+
+/**
+ * Supply only the capabilities the application uses. API callbacks must not depend on `this`.
+ * Their parameters, results, abort signals, and typed rejections remain application-owned.
+ */
+export type BillingOptions = {
+  readonly subscriptions?: SubscriptionBillingClient
+  readonly createTopUp?: BillingCallback
+  readonly getAttempt?: BillingCallback
+  readonly configureAutomaticTopUp?: BillingCallback
+  readonly setupPaymentMethod?: BillingCallback
+}
+
+type ConfiguredMethod<
+  Options extends BillingOptions,
+  Key extends PropertyKey,
+> = Options extends BillingOptions ? (Key extends keyof Options ? Options[Key] : undefined) : never
+type SubscriptionMethod<Options extends BillingOptions, Method> = Options extends {
+  subscriptions: SubscriptionBillingClient
+}
+  ? Method
+  : 'subscriptions' extends keyof Options
+    ? Method | undefined
+    : undefined
+type ChangePlan = (input: ChangePlanInput) => Promise<ChangePlanResult>
+type CreateBillingPortal = (input: BillingPortalInput) => Promise<BillingPortalResult>
+
+/** One browser billing API; unconfigured operations are undefined and cannot be called. */
+export interface IBillingService<Options extends BillingOptions> {
+  /** Start or change a subscription; return native data without redirecting. */
+  readonly changePlan: SubscriptionMethod<Options, ChangePlan>
+  /** Create portal access; return native data without redirecting. */
+  readonly createBillingPortal: SubscriptionMethod<Options, CreateBillingPortal>
+  /** Call the application's top-up API with its exact input and output types. */
+  readonly createTopUp: ConfiguredMethod<Options, 'createTopUp'>
+  /** Read the application's persisted attempt state. */
+  readonly getAttempt: ConfiguredMethod<Options, 'getAttempt'>
+  /** Persist automatic top-up settings through the application's API. */
+  readonly configureAutomaticTopUp: ConfiguredMethod<Options, 'configureAutomaticTopUp'>
+  /** Start payment method setup through the application's API. */
+  readonly setupPaymentMethod: ConfiguredMethod<Options, 'setupPaymentMethod'>
+}
+
+/**
+ * Ported from Typist's CheckoutService: one browser API for Better Auth and application payments.
+ * Unwraps Better Auth failures; preserves application callbacks, cancellations, and existing errors.
+ * Does not parse payloads, retry requests, log, navigate, or credit balances.
+ */
+export class BillingService<
+  const Options extends BillingOptions,
+> implements IBillingService<Options> {
+  /** Configured Better Auth upgrade operation. */
+  readonly changePlan: SubscriptionMethod<Options, ChangePlan>
+  /** Configured Better Auth portal operation. */
+  readonly createBillingPortal: SubscriptionMethod<Options, CreateBillingPortal>
+  /** Exact application checkout callback, or undefined. */
+  readonly createTopUp: ConfiguredMethod<Options, 'createTopUp'>
+  /** Exact application attempt callback, or undefined. */
+  readonly getAttempt: ConfiguredMethod<Options, 'getAttempt'>
+  /** Exact application settings callback, or undefined. */
+  readonly configureAutomaticTopUp: ConfiguredMethod<Options, 'configureAutomaticTopUp'>
+  /** Exact application setup callback, or undefined. */
+  readonly setupPaymentMethod: ConfiguredMethod<Options, 'setupPaymentMethod'>
+
+  /** Inject configured Better Auth methods and standalone application API callbacks. */
+  constructor(options: Options) {
+    const subscriptions = options.subscriptions
+    const changePlan: ChangePlan | undefined =
+      subscriptions &&
+      (async (input) => {
+        const result = await subscriptions.upgrade({
+          ...input,
+          disableRedirect: true,
+          fetchOptions: { ...input.fetchOptions, throw: false },
+        })
+        if (result.error) throw new BillingRequestError('subscription.upgrade', result.error)
+        return result.data
+      })
+    const createBillingPortal: CreateBillingPortal | undefined =
+      subscriptions &&
+      (async (input) => {
+        const result = await subscriptions.billingPortal({
+          ...input,
+          disableRedirect: true,
+          fetchOptions: { ...input.fetchOptions, throw: false },
+        })
+        if (result.error) throw new BillingRequestError('subscription.billingPortal', result.error)
+        return result.data
+      })
+    // SAFETY: Each subscription method exists exactly when the required subscriptions dependency exists.
+    this.changePlan = changePlan as SubscriptionMethod<Options, ChangePlan>
+    // SAFETY: Each subscription method exists exactly when the required subscriptions dependency exists.
+    this.createBillingPortal = createBillingPortal as SubscriptionMethod<
+      Options,
+      CreateBillingPortal
+    >
+    this.createTopUp = configuredMethod(options, 'createTopUp')
+    this.getAttempt = configuredMethod(options, 'getAttempt')
+    this.configureAutomaticTopUp = configuredMethod(options, 'configureAutomaticTopUp')
+    this.setupPaymentMethod = configuredMethod(options, 'setupPaymentMethod')
+  }
+}
+
+function configuredMethod<Options extends BillingOptions, Key extends keyof BillingOptions>(
+  options: Options,
+  key: Key,
+): ConfiguredMethod<Options, Key> {
+  // SAFETY: Optional callbacks are returned unchanged; absent keys read as undefined.
+  return options[key] as ConfiguredMethod<Options, Key>
+}

package/src/infrastructure/cloudflare/d1-database-execution.ts

@@ -1,13 +1,34 @@
+import { Result } from 'better-result'
+
+import { DatabaseError } from '@/core'
+
 import { classifyD1Error } from './classify-d1-error.ts'
 
-/** Execute once without retries; convert recognized D1 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 classifyD1Error(cause, operation) ?? cause
-  }
+  const result = await Result.tryPromise(
+    {
+      try: async () => await work(),
+      catch: (cause) => classifyD1Error(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/cloudflare/kv-client.ts

@@ -0,0 +1,79 @@
+import { Result } from 'better-result'
+
+import { exponentialDelayCapMs, spreadJitterMs } from '@/core'
+
+import { decideKVRetry, isKVPutRateLimitError, KVError } from './kv-errors.ts'
+
+/** Text storage bridge with the same TTL behavior as KVClient. */
+export type KVSecondaryStorage = {
+  get: (key: string) => Promise<string | null>
+  set: (key: string, value: string, ttl?: number) => Promise<void>
+  delete: (key: string) => Promise<void>
+}
+
+type KVOperation = 'get' | 'put' | 'delete'
+
+/** KV access with Typist's automatic transient retries and final KVError conversion. */
+export class KVClient {
+  constructor(private readonly kv: KVNamespace) {}
+
+  /** Read text, or return null when the key does not exist. */
+  async get(key: string): Promise<string | null> {
+    return await this.run('get', key, async () => this.kv.get(key))
+  }
+
+  /** Read JSON without schema validation; the caller supplies its stored type. */
+  async getJson<T>(key: string): Promise<T | null> {
+    return await this.run('get', key, async () => this.kv.get<T>(key, 'json'))
+  }
+
+  /** Write text; positive TTL values pass to KV in seconds, and other TTL values omit expiration. */
+  async put(key: string, value: string, options?: { ttl?: number | undefined }): Promise<void> {
+    const kvOptions: KVNamespacePutOptions = {}
+    if (options?.ttl !== undefined && options.ttl > 0) {
+      kvOptions.expirationTtl = options.ttl
+    }
+    await this.run('put', key, async () => this.kv.put(key, value, kvOptions))
+  }
+
+  /** Serialize once before writing; serialization failures retain their original error. */
+  async putJson(
+    key: string,
+    // oxlint-disable-next-line anti-slop/no-unknown-parameters -- Preserve the approved JSON serialization boundary and Typist's public signature.
+    value: unknown,
+    options?: { ttl?: number | undefined },
+  ): Promise<void> {
+    await this.put(key, JSON.stringify(value), options)
+  }
+
+  /** Delete a key; a missing key succeeds, and transient failures retry automatically. */
+  async delete(key: string): Promise<void> {
+    await this.run('delete', key, async () => this.kv.delete(key))
+  }
+
+  /** Expose Typist's three-method secondary storage bridge without changing KV semantics. */
+  asSecondaryStorage(): KVSecondaryStorage {
+    return {
+      get: (key) => this.get(key),
+      set: (key, value, ttl) => this.put(key, value, { ttl }),
+      delete: (key) => this.delete(key),
+    }
+  }
+
+  private async run<T>(operation: KVOperation, key: string, work: () => Promise<T>): Promise<T> {
+    const result = await Result.tryPromise(
+      { try: work, catch: (cause) => cause },
+      {
+        retry: {
+          times: 2,
+          shouldRetry: (cause) => decideKVRetry(cause).retry,
+          delayMs: (cause, { attempt }) =>
+            (isKVPutRateLimitError(cause) ? 1_000 : 0) +
+            spreadJitterMs(exponentialDelayCapMs(25, 3_000, attempt)),
+        },
+      },
+    )
+    if (result.isOk()) return result.value
+    throw new KVError({ operation, key, cause: result.error })
+  }
+}

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

@@ -0,0 +1,157 @@
+import {
+  AppError,
+  isCloudflareOverloadedError,
+  isCloudflareRetryableError,
+  isTransientTransportError,
+  type FailureClassification,
+} from '@/core'
+
+/** KV operations recognized in binding error messages. */
+export type KVOperation = 'get' | 'put' | 'delete' | 'list'
+
+/** KV failure kinds retained from Typist's binding tests. */
+export type KVErrorKind =
+  | 'invalid_key'
+  | 'key_too_large'
+  | 'invalid_expiration_ttl'
+  | 'invalid_expiration'
+  | 'invalid_cache_ttl'
+  | 'invalid_list_limit'
+  | 'value_too_large'
+  | 'client_error'
+  | 'rate_limited'
+  | 'server_error'
+
+/** Evidence extracted from a KV error and its causes. */
+export interface KVErrorMeta {
+  kind: KVErrorKind
+  message: string
+  status?: number | undefined
+  operation?: Uppercase<KVOperation> | undefined
+}
+
+/** Extract Typist's verified KV message formats, including nested causes. */
+export function extractKVMeta(cause: unknown): KVErrorMeta | undefined {
+  const message = getDeepErrorMessage(cause)
+  if (!message) return undefined
+  const statusMatch = message.match(/\bKV\s+(GET|PUT|DELETE|LIST)\s+failed:\s+(\d{3})\b/)
+  // SAFETY: The regular expression permits only uppercase KV operation names in this capture.
+  const operation = statusMatch?.[1] as Uppercase<KVOperation> | undefined
+  const status = statusMatch ? Number(statusMatch[2]) : undefined
+
+  if (/Key name cannot be empty/i.test(message)) {
+    return { kind: 'invalid_key', message, status, operation }
+  }
+  if (/exceeds key length limit/i.test(message)) {
+    return { kind: 'key_too_large', message, status, operation }
+  }
+  if (/Invalid expiration_ttl/i.test(message)) {
+    return { kind: 'invalid_expiration_ttl', message, status, operation }
+  }
+  if (/Invalid expiration of/i.test(message)) {
+    return { kind: 'invalid_expiration', message, status, operation }
+  }
+  if (/Invalid cache_ttl/i.test(message)) {
+    return { kind: 'invalid_cache_ttl', message, status, operation }
+  }
+  if (/Invalid key_count_limit/i.test(message)) {
+    return { kind: 'invalid_list_limit', message, status, operation }
+  }
+  if (/value.*(too large|exceeds)|exceeds.*value/i.test(message)) {
+    return { kind: 'value_too_large', message, status, operation }
+  }
+  if (status === 429) return { kind: 'rate_limited', message, status, operation }
+  if (status !== undefined && status >= 500) {
+    return { kind: 'server_error', message, status, operation }
+  }
+  if (status !== undefined && status >= 400) {
+    return { kind: 'client_error', message, status, operation }
+  }
+  return undefined
+}
+
+/** Identify recognized KV failures that another attempt cannot resolve. */
+export function isTerminalKVError(cause: unknown): boolean {
+  const meta = extractKVMeta(cause)
+  if (!meta) return false
+  if (meta.kind === 'rate_limited' || meta.kind === 'server_error') return false
+  if (meta.status === 408) return false
+  return true
+}
+
+/** Identify a PUT rate limit that requires at least one second before retrying. */
+export function isKVPutRateLimitError(cause: unknown): boolean {
+  const meta = extractKVMeta(cause)
+  return meta?.operation === 'PUT' && meta.kind === 'rate_limited'
+}
+
+/** Identify PUT rate limits, server failures, and request timeouts. */
+export function isTransientKVError(cause: unknown): boolean {
+  const meta = extractKVMeta(cause)
+  if (!meta) return false
+  return isKVPutRateLimitError(cause) || meta.kind === 'server_error' || meta.status === 408
+}
+
+/** Apply Typist's KV, overload, platform, and transport checks in their original order. */
+export function isRetryableKVError(cause: unknown): boolean {
+  if (isTerminalKVError(cause)) return false
+  if (isTransientKVError(cause)) return true
+  if (isCloudflareOverloadedError(cause)) return false
+  return isCloudflareRetryableError(cause) || isTransientTransportError(cause)
+}
+
+/** Return the existing retry decision and minimum delay in milliseconds. */
+export function decideKVRetry(
+  cause: unknown,
+): { retry: false } | { retry: true; retryAfterMs: number } {
+  if (!isRetryableKVError(cause)) return { retry: false }
+  return { retry: true, retryAfterMs: isKVPutRateLimitError(cause) ? 1_000 : 0 }
+}
+
+/** A final KV failure with Typist's diagnostics and Better Ship's error classification. */
+export class KVError extends AppError {
+  readonly _tag = 'KVError'
+  readonly classification: FailureClassification
+  retryable: boolean
+  readonly operation: KVOperation
+  readonly key?: string | undefined
+  override readonly cause: unknown
+  readonly kv?: KVErrorMeta | undefined
+  readonly context: {
+    operation: KVOperation
+    key?: string | undefined
+    kv?: KVErrorMeta | undefined
+  }
+
+  constructor(args: { operation: KVOperation; key?: string | undefined; cause: unknown }) {
+    const kv = extractKVMeta(args.cause)
+    const causeMessage = getDeepErrorMessage(args.cause) || String(args.cause)
+    const keyContext = args.key === undefined ? '' : ` for key "${args.key}"`
+    super(`KV ${args.operation} failed${keyContext}: ${causeMessage}`, { cause: args.cause })
+    this.operation = args.operation
+    this.key = args.key
+    this.cause = args.cause
+    this.kv = kv
+    this.context = { operation: args.operation, key: args.key, kv }
+    this.retryable = isRetryableKVError(args.cause)
+    this.classification = isTerminalKVError(args.cause)
+      ? 'terminal'
+      : this.retryable
+        ? 'transient'
+        : 'unknown'
+  }
+}
+
+// oxlint-disable anti-slop/no-runtime-typeof -- Preserve Typist's primitive messages and nested causes at the raw binding boundary.
+function getDeepErrorMessage(cause: unknown): string {
+  if (typeof cause === 'string') return cause
+  if (cause === null || cause === undefined) return ''
+  if (typeof cause === 'number' || typeof cause === 'boolean' || typeof cause === 'bigint') {
+    return String(cause)
+  }
+  if (typeof cause !== 'object') return ''
+  const message = 'message' in cause && typeof cause.message === 'string' ? cause.message : ''
+  const causeMessage = 'cause' in cause ? getDeepErrorMessage(cause.cause) : ''
+  return `${message} ${causeMessage}`.trim()
+}
+// oxlint-enable anti-slop/no-runtime-typeof

package/src/infrastructure/cloudflare/queue/queue-consumer.ts

@@ -65,7 +65,8 @@ export class QueueConsumer<TMessage extends QueueMessage> {
       if (body === null) {
         // An unparseable body cannot succeed on retry, so park it for inspection.
         logger.error('invalid_message_format', {
-          details: { attempt: message.attempts, queueMessageId: message.id },
+          attempt: message.attempts,
+          queueMessageId: message.id,
         })
         await this.parkPoison(message)
         return
@@ -76,7 +77,7 @@ export class QueueConsumer<TMessage extends QueueMessage> {
         await this.bus.handle(body)
       })
       message.ack()
-      logger.debug(`queue_message_processed:${body.name}`, { name: body.name })
+      logger.debug('queue_message_processed', { name: body.name })
     } catch (cause) {
       this.handleFailure(message, parsed, cause)
     }
@@ -117,12 +118,10 @@ export class QueueConsumer<TMessage extends QueueMessage> {
     if (decision.action === 'ack') {
       logger.error('message_discarded', {
         error: cause,
-        details: {
-          name: parsed?.name,
-          messageId: parsed?.id,
-          queueMessageId: message.id,
-          attempt: message.attempts,
-        },
+        name: parsed?.name,
+        messageId: parsed?.id,
+        queueMessageId: message.id,
+        attempt: message.attempts,
       })
       message.ack()
       return
@@ -137,7 +136,7 @@ export class QueueConsumer<TMessage extends QueueMessage> {
       delaySeconds: decision.delaySeconds,
     }
     if (decision.classification === 'unknown' && message.attempts === 1) {
-      logger.error('queue_unknown_failure', { error: cause, details: context })
+      logger.error('queue_unknown_failure', { error: cause, ...context })
     } else {
       logger.debug('redelivery_requested', context)
     }

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