mppx 0.8.14 → 0.8.17

package/src/server/Mppx.ts

@@ -1,6 +1,8 @@
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import { isDeepStrictEqual } from 'node:util'
 
+import * as AttestationServer from '../attestation/Server.js'
+import type * as Attestation from '../attestation/Types.js'
 import * as Challenge from '../Challenge.js'
 import * as Constants from '../Constants.js'
 import * as Credential from '../Credential.js'
@@ -8,7 +10,7 @@ import * as Errors from '../Errors.js'
 import * as Expires from '../Expires.js'
 import * as AcceptPayment from '../internal/AcceptPayment.js'
 import * as Env from '../internal/env.js'
-import type { MaybePromise } from '../internal/types.js'
+import type { DeepReadonly, MaybePromise } from '../internal/types.js'
 import * as Method from '../Method.js'
 import * as PaymentRequest from '../PaymentRequest.js'
 import type * as Receipt from '../Receipt.js'
@@ -85,6 +87,41 @@ export type ServerMethodDescriptor<
   name: method['name']
 }>
 
+/** A configured payment offer exposed to the server's `selectOffers` hook. */
+export type ServerOffer<method extends Method.Method = Method.Method> = method extends unknown
+  ? ServerOfferFor<method>
+  : never
+
+type ServerOfferFor<method extends Method.Method> = Readonly<{
+  /** Canonical wire key for the configured method. */
+  key: `${method['name']}/${method['intent']}`
+  /** Immutable method metadata for this offer. */
+  method: ServerOfferMethodDescriptor<method>
+  /** Schema-normalized request configured for this offer. */
+  request: DeepReadonly<z.output<method['schema']['request']>>
+}>
+
+/** Immutable method metadata exposed to offer-selection hooks. */
+export type ServerOfferMethodDescriptor<method extends Method.Method = Method.Method> = Readonly<{
+  /** Optional public alias used to register this server method. */
+  alias?: method extends { alias?: infer alias } ? alias : string
+  intent: method['intent']
+  name: method['name']
+}>
+
+/**
+ * Selects a subset of configured offers before payment challenges are issued.
+ *
+ * The hook must select at least one offer. Returned offers must come from the input,
+ * contain no duplicates, and preserve their original order. Offers and their
+ * normalized requests are deeply immutable. The incoming request is cloned so
+ * the hook may safely inspect its body when it has not already been consumed.
+ */
+export type SelectOffers<methods extends readonly Method.Method[]> = (
+  offers: readonly ServerOffer<methods[number]>[],
+  context: Readonly<{ request: globalThis.Request }>,
+) => MaybePromise<readonly ServerOffer<methods[number]>[]>
+
 /** Context passed to `onChallengeCreated`. */
 export type ChallengeContext<
   method extends Method.Method = Method.Method,
@@ -227,9 +264,7 @@ export type Mppx<
        * })
        * ```
        */
-      compose(
-        ...entries: ComposeEntry<FlattenMethods<methods>>[]
-      ): (input: Request) => Promise<MethodFn.Response<Transport.Http>>
+      compose(...entries: ComposeEntry<FlattenMethods<methods>>[]): ComposedHandler
     }
   : {}) &
   Handlers<FlattenMethods<methods>, transport> & {
@@ -339,22 +374,37 @@ type IsUniqueIntent<methods extends readonly Method.AnyServer[], intent extends
       : never
     : never
 
-/** Only includes shorthand intent keys when the intent is unique across methods. */
-type UniqueIntentHandlers<
+/** Shorthand intent handlers. Single-method intents get direct handlers;
+ *  multi-method intents get an implicit compose wrapper. */
+type IntentHandlers<
   methods extends readonly Method.AnyServer[],
   transport extends Transport.AnyTransport,
 > = {
-  [method_name in methods[number]['intent'] as IsUniqueIntent<methods, method_name> extends true
-    ? method_name extends ReservedKey
-      ? never
-      : method_name
-    : never]: MethodFn<
-    Extract<methods[number], { intent: method_name }>,
-    EffectiveTransportOf<Extract<methods[number], { intent: method_name }>, transport>,
-    NonNullable<Extract<methods[number], { intent: method_name }>['defaults']>
-  > &
-    MethodExtensions<Extract<methods[number], { intent: method_name }>>
-}
+  [intent in methods[number]['intent'] as intent extends ReservedKey
+    ? never
+    : intent]: IsUniqueIntent<methods, intent> extends true
+    ? MethodFn<
+        Extract<methods[number], { intent: intent }>,
+        EffectiveTransportOf<Extract<methods[number], { intent: intent }>, transport>,
+        NonNullable<Extract<methods[number], { intent: intent }>['defaults']>
+      > &
+        MethodExtensions<Extract<methods[number], { intent: intent }>>
+    : MultiMethodFn<Extract<methods[number], { intent: intent }>, transport>
+}
+
+/** Handler for an intent with multiple methods - takes the intersection of all methods' options. */
+type MultiMethodFn<methods extends Method.AnyServer, transport extends Transport.AnyTransport> = (
+  options: UnionToIntersection<MultiMethodFnDistribute<methods>>,
+) => (input: Transport.InputOf<transport>) => Promise<MethodFn.Response<transport>>
+
+type MultiMethodFnDistribute<M> =
+  M extends Method.Server<infer method, infer defaults, any, any, any>
+    ? MethodFn.Options<method, NonNullable<defaults>>
+    : never
+
+type UnionToIntersection<U> = (U extends any ? (x: U) => void : never) extends (x: infer I) => void
+  ? I
+  : never
 
 /** Nested handlers: `mppx.tempo.charge(...)`, grouped by method name then intent. */
 type PublicAlias<method extends Method.AnyServer> = method extends {
@@ -399,7 +449,7 @@ type Handlers<
     NonNullable<mi['defaults']>
   > &
     MethodExtensions<mi>
-} & UniqueIntentHandlers<methods, transport> &
+} & IntentHandlers<methods, transport> &
   NestedHandlers<methods, transport> & {
     [mi in methods[number] as PublicAlias<mi> extends string
       ? `${mi['name']}/${PublicAlias<mi>}`
@@ -451,7 +501,9 @@ export function create<
   const transport extends Transport.AnyTransport = Transport.Http,
 >(config: create.Config<methods, transport>): Mppx<methods, transport> {
   const {
+    attestation,
     realm = Env.get('realm'),
+    selectOffers,
     secretKey = Env.get('secretKey'),
     transport = Transport.http() as transport,
   } = config
@@ -465,17 +517,32 @@ export function create<
 
   const methods = config.methods.flat() as unknown as FlattenMethods<methods>
   const serverEvents = createServerEventDispatcher<FlattenMethods<methods>, transport>()
+  const verifyAttestation = attestation
+    ? createAttestationGuard(attestation as Attestation.VerifierMap)
+    : undefined
 
   const handlers: Record<string, unknown> = {}
   const intentCount: Record<string, number> = {}
 
   for (const mi of methods) {
     intentCount[mi.intent] = (intentCount[mi.intent] ?? 0) + 1
+    if (mi.onPaymentSuccess) {
+      serverEvents.on('payment.success', (async (ctx: PaymentSuccessContext) => {
+        if (ctx.method.name === mi.name && ctx.method.intent === mi.intent) {
+          await mi.onPaymentSuccess({
+            input: ctx.input,
+            receipt: ctx.receipt,
+            request: ctx.request,
+          })
+        }
+      }) as never)
+    }
   }
   assertNoReservedMppxKeys(methods as readonly Method.AnyServer[])
 
   for (const mi of methods) {
     const fn = createMethodFn({
+      ...(verifyAttestation && { attest: verifyAttestation }),
       authorize: mi.authorize as never,
       defaults: mi.defaults,
       method: mi,
@@ -498,9 +565,32 @@ export function create<
     if (aliasKey) handlers[aliasKey] = fn
   }
 
-  // Also set shorthand intent key when there's no collision
+  // Set shorthand intent key: single method gets direct handler,
+  // multiple methods get an implicit compose wrapper.
+  const processedIntents = new Set<string>()
   for (const mi of methods) {
-    if (intentCount[mi.intent] === 1) handlers[mi.intent] = handlers[`${mi.name}/${mi.intent}`]
+    if (processedIntents.has(mi.intent)) continue
+    processedIntents.add(mi.intent)
+
+    if (intentCount[mi.intent] === 1) {
+      handlers[mi.intent] = handlers[`${mi.name}/${mi.intent}`]
+    } else {
+      const intentMethods = (methods as readonly Method.AnyServer[]).filter(
+        (m) => m.intent === mi.intent,
+      )
+      handlers[mi.intent] = (options: Record<string, unknown>) => {
+        const configured = intentMethods.map((m) => {
+          const key = `${m.name}/${m.intent}`
+          const handlerFn = handlers[key] as AnyMethodFn
+          return handlerFn(options)
+        })
+        return composeHandlers(
+          configured as ConfiguredHandler[],
+          undefined,
+          selectOffers as SelectOffers<readonly Method.AnyServer[]> | undefined,
+        )
+      }
+    }
   }
 
   // Build nested handlers: mppx.tempo.charge(...)
@@ -539,7 +629,7 @@ export function create<
     const methodCandidates = (methods as readonly Method.AnyServer[]).filter(
       (m) => m.name === credMethod && m.intent === credIntent,
     )
-    const mi = Method.selectServerMethod(methodCandidates, credential.challenge)
+    const mi = methodCandidates[0]
     const eventMethod =
       mi ?? ({ intent: credIntent, name: credMethod } satisfies ServerMethodDescriptor)
 
@@ -806,7 +896,11 @@ export function create<
         throw new Error(`No handler for "${key}". Is this method in your methods array?`)
       return handlerFn(options)
     })
-    return compose(...(configured as ConfiguredHandler[]))
+    return composeHandlers(
+      configured as ConfiguredHandler[],
+      undefined,
+      selectOffers as SelectOffers<readonly Method.AnyServer[]> | undefined,
+    )
   }
 
   function onChallengeCreated(
@@ -858,12 +952,18 @@ export declare namespace create {
     methods extends Methods = Methods,
     transport extends Transport.AnyTransport = Transport.Http,
   > = {
+    /** Request-attestation verifiers required before handling an HTTP payment request. */
+    attestation?: transport extends Transport.Http ? Attestation.VerifierMap | undefined : never
     /** Array of configured methods. @example [tempo()] */
     methods: methods
     /** Server realm (e.g., hostname). Resolution order: explicit value > env vars (`MPP_REALM`, `FLY_APP_NAME`, `VERCEL_URL`, etc.) > request URL hostname > `"MPP Payment"`. */
     realm?: string | undefined
     /** Secret key for HMAC-bound challenge IDs for stateless verification. Must be at least 32 bytes. Auto-detected from `MPP_SECRET_KEY` environment variable. */
     secretKey?: string | undefined
+    /** Selects a subset of composed HTTP offers before challenges are issued. Successfully matched credential dispatch bypasses this hook. */
+    selectOffers?: transport extends Transport.Http
+      ? SelectOffers<FlattenMethods<methods>> | undefined
+      : never
     /** Transport to use. @default Transport.http() */
     transport?: transport | undefined
   }
@@ -879,6 +979,7 @@ function createMethodFn<
 // biome-ignore lint/correctness/noUnusedVariables: _
 function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.ReturnType {
   const {
+    attest,
     authorize,
     defaults,
     events,
@@ -897,7 +998,7 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
   return (options) => {
     const { description, meta, scope, ...rest } = options
     const staticMeta = Scope.merge({ meta, scope })
-    const internal: ConfiguredHandler['_internal'] = {
+    const internal = {
       ...method,
       ...defaults,
       ...options,
@@ -907,9 +1008,21 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
       html: method.html,
       _canonicalRequest: PaymentRequest.fromMethod(method, { ...defaults, ...rest }),
       _stableBinding: stableBinding as never,
-    }
+    } as unknown as ConfiguredHandler['_internal']
+    Object.defineProperty(internal, '_method', { value: method })
 
     const handler = async (input: Transport.InputOf): Promise<MethodFn.Response> => {
+      if (attest && input instanceof globalThis.Request) {
+        const response = await attest(input)
+        if (response)
+          return {
+            status: 200,
+            withReceipt() {
+              return response
+            },
+          } as MethodFn.Response
+      }
+
       if (method.html && isServiceWorkerRequest(input))
         return {
           status: 402,
@@ -1454,6 +1567,7 @@ declare namespace createMethodFn {
     transport extends Transport.AnyTransport = Transport.Http,
     defaults extends Record<string, unknown> = Record<string, unknown>,
   > = {
+    attest?: (request: globalThis.Request) => Promise<globalThis.Response | undefined>
     authorize?: Method.AuthorizeFn<method>
     defaults?: defaults
     method: method
@@ -1477,6 +1591,39 @@ declare namespace createMethodFn {
   > = MethodFn<method, transport, defaults>
 }
 
+function createAttestationGuard(verifiers: Attestation.VerifierMap) {
+  const entries = Object.entries(verifiers)
+  if (entries.length === 0)
+    throw new TypeError('Mppx server attestation must configure at least one verifier.')
+
+  const cache = new WeakMap<globalThis.Request, Promise<globalThis.Response | undefined>>()
+  return (request: globalThis.Request): Promise<globalThis.Response | undefined> => {
+    const cached = cache.get(request)
+    if (cached) return cached
+
+    const verification = AttestationServer.verify(request, verifiers).then((outcomes) => {
+      for (const [name, outcome] of Object.entries(outcomes))
+        if (outcome.status === 'invalid')
+          return new globalThis.Response(
+            `Request attestation "${name}" is invalid: ${outcome.reason}`,
+            { status: 401 },
+          )
+
+      for (const [name, outcome] of Object.entries(outcomes)) {
+        if (outcome.status === 'verified') continue
+        const reason =
+          outcome.status === 'unverified'
+            ? `Request attestation "${name}" could not be verified: ${outcome.reason}`
+            : `Request attestation "${name}" is required.`
+        return new globalThis.Response(reason, { status: 403 })
+      }
+      return undefined
+    })
+    cache.set(request, verification)
+    return verification
+  }
+}
+
 type ServerEventDispatcher<
   methods extends readonly Method.Method[],
   transport extends Transport.AnyTransport,
@@ -2169,6 +2316,8 @@ declare namespace MethodFn {
 /** A configured handler — the return value of e.g. `mppx.charge({ ... })`. @internal */
 type ConfiguredHandler = ((input: Request) => Promise<MethodFn.Response<Transport.Http>>) & {
   _internal: {
+    _method: Method.AnyServer
+    description?: string | undefined
     name: string
     intent: string
     html: Html.Options | undefined
@@ -2179,6 +2328,16 @@ type ConfiguredHandler = ((input: Request) => Promise<MethodFn.Response<Transpor
   }
 }
 
+type ComposedHandler = ((input: Request) => Promise<MethodFn.Response<Transport.Http>>) & {
+  _internal?: {
+    offers: readonly ConfiguredHandler['_internal'][]
+  }
+}
+
+type HandlerDiscoveryMetadata =
+  | ConfiguredHandler['_internal']
+  | NonNullable<ComposedHandler['_internal']>
+
 const paymentAuthChallengeHeader = Constants.Headers.wwwAuthenticate
 
 const challengeHeaderMerges = [
@@ -2252,9 +2411,7 @@ type ComposeEntry<methods extends readonly Method.AnyServer[]> =
  */
 type ComposeHtmlOptions = Html.Config
 
-export function compose(
-  ...args: readonly unknown[]
-): (input: Request) => Promise<MethodFn.Response<Transport.Http>> {
+export function compose(...args: readonly unknown[]): ComposedHandler {
   // Extract optional html options from last argument
   const last = args[args.length - 1]
   const composeOptions: Html.Options | undefined =
@@ -2277,9 +2434,28 @@ export function compose(
     input: Request,
   ) => Promise<MethodFn.Response<Transport.Http>>)[]
 
+  return composeHandlers(handlers, composeOptions)
+}
+
+function composeHandlers(
+  handlers: readonly ((input: Request) => Promise<MethodFn.Response<Transport.Http>>)[],
+  composeOptions?: Html.Options,
+  selectOffers?: SelectOffers<readonly Method.AnyServer[]>,
+): (input: Request) => Promise<MethodFn.Response<Transport.Http>> {
   if (handlers.length === 0) throw new Error('compose() requires at least one handler')
 
-  return async (input: Request) => {
+  const offerSelector = selectOffers
+  const offerEntries = handlers.map((handler) => {
+    const internal = (handler as ConfiguredHandler)._internal
+    const offer =
+      internal && !isComposedHandlerMetadata(internal) ? createServerOffer(internal) : undefined
+    const method = internal && !isComposedHandlerMetadata(internal) ? internal._method : undefined
+    return { handler, method, offer }
+  })
+  const hasOfferPolicy =
+    offerSelector !== undefined || offerEntries.some(({ method }) => method?.canOffer !== undefined)
+
+  const composed: ComposedHandler = async (input: Request) => {
     // Serve service worker for html-enabled compose
     if (new URL(input.url).searchParams.has(Html.params.serviceWorker)) {
       const hasHtml = handlers.some((h) => (h as ConfiguredHandler)._internal?.html)
@@ -2314,45 +2490,53 @@ export function compose(
         const credReq = credential.challenge.request as Record<string, unknown>
 
         // Filter by name+intent, then narrow by comparing stable request fields
-        // from the echoed challenge against each handler's canonical request.
+        // from the echoed challenge against each handler's configured offers.
         // Uses the schema-parsed canonical form (not raw options) so that
         // transformed fields (e.g. amount with decimals) match correctly.
         // Also checks inside methodDetails for fields moved there by transforms.
-        const candidates = handlers.filter((h) => {
-          try {
-            const internal = (h as ConfiguredHandler)._internal
-            if (!internal || internal.name !== credMethod || internal.intent !== credIntent)
+        const candidates = handlers.filter((handler) =>
+          getConfiguredOffers(handler).some((internal) => {
+            try {
+              if (internal.name !== credMethod || internal.intent !== credIntent) return false
+              const mismatch = internal._stableBinding
+                ? getRequestBindingMismatch(
+                    getStableBinding(internal._canonicalRequest, internal._stableBinding),
+                    getStableBinding(credReq, internal._stableBinding),
+                  )
+                : getPinnedRequestBindingMismatch(internal._canonicalRequest, credReq)
+              return !mismatch && opaqueValuesMatch(internal.meta, credential.challenge.meta)
+            } catch {
               return false
-            const mismatch = internal._stableBinding
-              ? getRequestBindingMismatch(
-                  getStableBinding(internal._canonicalRequest, internal._stableBinding),
-                  getStableBinding(credReq, internal._stableBinding),
-                )
-              : getPinnedRequestBindingMismatch(internal._canonicalRequest, credReq)
-            return !mismatch && opaqueValuesMatch(internal.meta, credential.challenge.meta)
-          } catch {
-            return false
-          }
-        })
+            }
+          }),
+        )
 
         const match =
           candidates[0] ??
-          handlers.find((h) => {
-            const meta = (h as ConfiguredHandler)._internal
-            return meta?.name === credMethod && meta?.intent === credIntent
-          })
+          handlers.find((handler) =>
+            getConfiguredOffers(handler).some(
+              (internal) => internal.name === credMethod && internal.intent === credIntent,
+            ),
+          )
         if (match) return match(input)
       }
 
-      // Payment credential present but no matching handler — dispatch to first
-      // handler which will reject with an appropriate error (invalid challenge, etc.).
-      return handlers[0]!(input)
+      // Unrecognized or malformed credentials still use the currently eligible
+      // offer set before the first handler issues its rejection challenge.
     }
 
+    const selectedHandlers = hasOfferPolicy
+      ? await selectOfferHandlers({
+          entries: offerEntries,
+          input,
+          selectOffers: offerSelector,
+        })
+      : handlers
+
     // No credential — evaluate handlers sequentially so authorize()/renewal hooks
     // can safely claim the request without racing each other.
     const results: MethodFn.Response<Transport.Http>[] = []
-    for (const handler of handlers) {
+    for (const handler of selectedHandlers) {
       const result = await handler(input)
       if (result.status === 200) return result
       results.push(result)
@@ -2365,7 +2549,7 @@ export function compose(
         result: Extract<MethodFn.Response<Transport.Http>, { status: 402 }>
       }[] = []
 
-      for (let i = 0; i < handlers.length; i++) {
+      for (let i = 0; i < selectedHandlers.length; i++) {
         const result = results[i]
         if (result?.status !== 402) continue
 
@@ -2374,7 +2558,7 @@ export function compose(
         if (!wwwAuth) continue
 
         entries.push({
-          handler: handlers[i] as ConfiguredHandler,
+          handler: selectedHandlers[i] as ConfiguredHandler,
           challenge: Challenge.deserialize(wwwAuth),
           result,
         })
@@ -2501,6 +2685,118 @@ export function compose(
       challenge: new Response(body, { status: 402, headers: mergedHeaders }),
     }
   }
+
+  const offers = handlers.flatMap(getConfiguredOffers)
+  if (offers.length > 0) composed._internal = { offers }
+  return composed
+}
+
+/** Returns the flattened configured offers accepted by a handler. */
+function getConfiguredOffers(
+  handler: ConfiguredHandler | ComposedHandler,
+): readonly ConfiguredHandler['_internal'][] {
+  const internal = handler._internal
+  if (!internal) return []
+  if (isComposedHandlerMetadata(internal)) return internal.offers
+  return [internal]
+}
+
+function isComposedHandlerMetadata(
+  internal: HandlerDiscoveryMetadata,
+): internal is NonNullable<ComposedHandler['_internal']> {
+  return 'offers' in internal && !('_canonicalRequest' in internal)
+}
+
+function createServerOffer(internal: ConfiguredHandler['_internal']): ServerOffer {
+  return Object.freeze({
+    key: `${internal.name}/${internal.intent}`,
+    method: Object.freeze({
+      ...(internal._method.alias ? { alias: internal._method.alias } : {}),
+      intent: internal.intent,
+      name: internal.name,
+    }),
+    request: immutableSnapshot(internal._canonicalRequest),
+  }) as ServerOffer
+}
+
+/** Applies and validates the server-level offer selection policy. */
+async function selectOfferHandlers(parameters: {
+  entries: readonly {
+    handler: (input: Request) => Promise<MethodFn.Response<Transport.Http>>
+    method: Method.AnyServer | undefined
+    offer: ServerOffer | undefined
+  }[]
+  input: Request
+  selectOffers: SelectOffers<readonly Method.AnyServer[]> | undefined
+}) {
+  const { entries, input, selectOffers } = parameters
+  const eligibleEntries: (typeof entries)[number][] = []
+  for (const entry of entries) {
+    const canOffer = entry.method?.canOffer
+    if (canOffer) {
+      const approved = await canOffer({
+        input: cloneOfferInput(input),
+        request: entry.offer!.request,
+      })
+      if (typeof approved !== 'boolean') throw new Error('canOffer() must return a boolean')
+      if (!approved) continue
+    }
+    eligibleEntries.push(entry)
+  }
+
+  if (eligibleEntries.length === 0)
+    throw new Error('No payment offers are available for this request')
+  if (!selectOffers) return eligibleEntries.map(({ handler }) => handler)
+
+  const offers = eligibleEntries.map(({ offer }) => {
+    if (!offer) throw new Error('selectOffers() can only select configured payment offers')
+    return offer
+  })
+  const selected = await selectOffers(
+    Object.freeze(offers),
+    Object.freeze({ request: cloneOfferInput(input) }),
+  )
+
+  if (!Array.isArray(selected)) throw new Error('selectOffers() must return an array of offers')
+  if (selected.length === 0) throw new Error('selectOffers() must select at least one offer')
+
+  let previousIndex = -1
+  const selectedHandlers = selected.map((offer) => {
+    const index = offers.indexOf(offer)
+    if (index === -1) throw new Error('selectOffers() must return only offers from its input array')
+    if (index <= previousIndex)
+      throw new Error('selectOffers() must preserve offer order and must not return duplicates')
+    previousIndex = index
+    return eligibleEntries[index]!.handler
+  })
+
+  return selectedHandlers
+}
+
+/** Clones a request for offer hooks, falling back to a bodyless metadata copy. */
+function cloneOfferInput(input: Request): Request {
+  try {
+    return input.clone()
+  } catch {
+    return new globalThis.Request(input.url, {
+      headers: new Headers(input.headers),
+      method: input.method,
+      signal: input.signal,
+    })
+  }
+}
+
+/** Clones and recursively freezes protocol data exposed to offer hooks. */
+function immutableSnapshot<value>(value: value): DeepReadonly<value> {
+  return deepFreeze(structuredClone(value))
+}
+
+function deepFreeze<value>(value: value): DeepReadonly<value> {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value))
+    return value as DeepReadonly<value>
+
+  for (const nested of Object.values(value)) deepFreeze(nested)
+  return Object.freeze(value) as DeepReadonly<value>
 }
 
 type ChallengeHeaderMerge = {

package/src/stripe/internal/constants.ts

@@ -4,4 +4,4 @@
  * Required for `shared_payment_granted_token` (SPTs are in private preview).
  * Bump this when upgrading to a newer Stripe API version.
  */
-export const stripePreviewVersion = '2026-02-25.preview'
+export const stripePreviewVersion = '2026-07-29.preview'

package/src/stripe/internal/types.ts

@@ -14,6 +14,7 @@ export type StripeClient = {
       lastResponse?: { headers?: Record<string, string> }
     }>
   }
+  rawRequest?(method: string, path: string, params?: any, options?: any): Promise<any>
 }
 
 /**

package/src/stripe/server/Charge.test-d.ts

@@ -1,5 +1,5 @@
 import { Mppx, stripe } from 'mppx/server'
-import { test } from 'vp/test'
+import { expectTypeOf, test } from 'vp/test'
 
 import type { StripeClient } from '../internal/types.js'
 import type { charge as StripeCharge } from './Charge.js'
@@ -7,6 +7,21 @@ import type { charge as StripeCharge } from './Charge.js'
 const client = {} as StripeClient
 const secretKey = 'test-secret-key-test-secret-key-32'
 
+test('accepts a typed constructor canOffer policy', () => {
+  stripe.charge({
+    client,
+    canOffer({ input, request }) {
+      expectTypeOf(input).toEqualTypeOf<Request>()
+      expectTypeOf(request.amount).toEqualTypeOf<string>()
+      expectTypeOf(request.currency).toEqualTypeOf<string>()
+      expectTypeOf(request.methodDetails.networkId).toEqualTypeOf<string>()
+      return request.amount !== '0'
+    },
+    networkId: 'internal',
+    paymentMethodTypes: ['card'],
+  })
+})
+
 test('requires request fields not configured as Stripe defaults', () => {
   const server = Mppx.create({
     methods: [