mppx 0.8.15 → 0.8.17

package/src/client/Transport.test.ts

@@ -77,38 +77,6 @@ describe('http', () => {
     })
   })
 
-  describe('getChallenge', () => {
-    test('default', () => {
-      const transport = Transport.http()
-      const response = new Response(null, {
-        status: 402,
-        headers: {
-          'WWW-Authenticate': Challenge.serialize(challenge),
-        },
-      })
-
-      expect(transport.getChallenge(response)).toMatchObject({
-        expires: '2025-01-01T00:00:00.000Z',
-        id: expect.any(String),
-        intent: 'charge',
-        method: 'tempo',
-        realm: 'api.example.com',
-        request: {
-          amount: '1000',
-          currency: '0x20c0000000000000000000000000000000000001',
-          recipient: '0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00',
-        },
-      })
-    })
-
-    test('throws for non-402 response', () => {
-      const transport = Transport.http()
-      const response = new Response(null, { status: 200 })
-
-      expect(() => transport.getChallenge(response)).toThrow()
-    })
-  })
-
   describe('getChallenges', () => {
     test.each([
       {
@@ -188,7 +156,7 @@ describe('http', () => {
         status: 402,
         headers: headers(),
       })
-      const challenges = (await transport.getChallenges?.(response)) ?? []
+      const challenges = await transport.getChallenges(response)
 
       expect(challenges.map((entry) => entry.id)).toEqual(expectedIds)
       expect(challenges.map((entry) => entry.method)).toEqual(expectedMethods)
@@ -207,7 +175,7 @@ describe('http', () => {
         },
       })
 
-      const challenges = (await transport.getChallenges?.(response)) ?? []
+      const challenges = await transport.getChallenges(response)
 
       expect(challenges.map((entry) => entry.id)).toEqual([challenge.id])
       expect(challenges.map((entry) => entry.method)).toEqual(['tempo'])
@@ -225,9 +193,8 @@ describe('http', () => {
         },
       })
 
-      const challenges = (await transport.getChallenges?.(response)) ?? []
+      const challenges = await transport.getChallenges(response)
       expect(challenges).toEqual([])
-      expect(() => transport.getChallenge(response)).toThrow('No challenge in response.')
     })
   })
 
@@ -265,7 +232,7 @@ describe('http', () => {
 
     test('writes x402 credentials for x402 challenges from the same transport', () => {
       const transport = Transport.http()
-      const [x402Challenge] = transport.getChallenges!(
+      const [x402Challenge] = transport.getChallenges(
         new Response(null, {
           status: 402,
           headers: {
@@ -306,7 +273,7 @@ describe('http', () => {
         method: 'POST',
         body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: {} }),
       } satisfies RequestInit
-      const [nativeChallenge] = transport.getChallenges!(
+      const [nativeChallenge] = transport.getChallenges(
         new Response(null, {
           status: 402,
           headers: { 'WWW-Authenticate': Challenge.serialize(challenge) },
@@ -326,7 +293,7 @@ describe('http', () => {
     test('marks x402 challenges with the brand the evm charge client reads', async () => {
       // Provenance guard: `evm/client/Charge.ts` recognizes x402 challenges via the same
       // brand the x402 adapter stamps. If the marking site drifts, EVM x402 charges misroute.
-      const [x402Challenge] = await Transport.http().getChallenges!(
+      const [x402Challenge] = await Transport.http().getChallenges(
         new Response(null, {
           status: 402,
           headers: {
@@ -339,7 +306,7 @@ describe('http', () => {
 
     test('removes stale credential headers before setting the retry credential', async () => {
       const transport = Transport.http()
-      const [x402Challenge] = await transport.getChallenges!(
+      const [x402Challenge] = await transport.getChallenges(
         new Response(null, {
           status: 402,
           headers: {
@@ -497,16 +464,16 @@ describe('http (MCP-over-HTTP)', () => {
     expect(await Transport.http().isPaymentRequired(ok, jsonRpcRequest)).toBe(false)
   })
   test('getChallenges extracts the MCP challenge (via the mcp protocol)', async () => {
-    const challenges = await Transport.http().getChallenges!(sseBody(), jsonRpcRequest)
+    const challenges = await Transport.http().getChallenges(sseBody(), jsonRpcRequest)
     expect(challenges.map((entry) => entry.id)).toEqual([challenge.id])
   })
   test('getChallenges extracts an MCP result metadata challenge', async () => {
-    const challenges = await Transport.http().getChallenges!(jsonResultBody(), jsonRpcRequest)
+    const challenges = await Transport.http().getChallenges(jsonResultBody(), jsonRpcRequest)
     expect(challenges.map((entry) => entry.id)).toEqual([challenge.id])
   })
   test('setCredential routes the MCP challenge into the JSON-RPC _meta', async () => {
     const transport = Transport.http()
-    const [mcpChallenge] = await transport.getChallenges!(sseBody(), jsonRpcRequest)
+    const [mcpChallenge] = await transport.getChallenges(sseBody(), jsonRpcRequest)
     const result = transport.setCredential(jsonRpcRequest, Credential.serialize(credential), {
       challenge: mcpChallenge,
     }) as RequestInit
@@ -593,7 +560,7 @@ describe('mcp', () => {
     const transport = Transport.mcp()
 
     expect(await transport.isPaymentRequired(mcpResponse)).toBe(true)
-    expect((await transport.getChallenges?.(mcpResponse))?.map((entry) => entry.id)).toEqual([
+    expect((await transport.getChallenges(mcpResponse)).map((entry) => entry.id)).toEqual([
       challenge.id,
     ])
   })
@@ -602,7 +569,7 @@ describe('mcp', () => {
     const transport = Transport.mcp()
 
     expect(await transport.isPaymentRequired(mcpResult)).toBe(true)
-    expect((await transport.getChallenges?.(mcpResult))?.map((entry) => entry.id)).toEqual([
+    expect((await transport.getChallenges(mcpResult)).map((entry) => entry.id)).toEqual([
       challenge.id,
     ])
   })

package/src/client/Transport.ts

@@ -21,16 +21,11 @@ export type Transport<in out request = unknown, in out response = unknown> = {
    * body reads) and be async (to read a response body).
    */
   isPaymentRequired: (response: response, request?: request) => boolean | Promise<boolean>
-  /** Extracts all challenges from a payment-required response, when the transport supports multiple offers. */
-  getChallenges?: (
+  /** Extracts all challenges from a payment-required response. */
+  getChallenges: (
     response: response,
     request?: request,
   ) => Challenge.Challenge[] | Promise<Challenge.Challenge[]>
-  /** Extracts the challenge from a payment-required response. */
-  getChallenge: (
-    response: response,
-    request?: request,
-  ) => Challenge.Challenge | Promise<Challenge.Challenge>
   /** Attaches a credential to a request. */
   setCredential: (
     request: request,
@@ -65,7 +60,7 @@ export type RequestOf<transport extends Transport> =
  * const custom = Transport.from({
  *   name: 'custom',
  *   isPaymentRequired(response) { ... },
- *   getChallenge(response) { ... },
+ *   getChallenges(response) { ... },
  *   setCredential(request, credential) { ... },
  * })
  * ```
@@ -125,16 +120,6 @@ export function http(): Transport<RequestInit, Response> {
       return collect(response, request)
     },
 
-    getChallenge(response, request) {
-      const pick = (challenges: Challenge.Challenge[]): Challenge.Challenge => {
-        const challenge = challenges[0]
-        if (!challenge) throw new Error('No challenge in response.')
-        return challenge
-      }
-      const challenges = collect(response, request)
-      return challenges instanceof Promise ? challenges.then(pick) : pick(challenges)
-    },
-
     setCredential(request, credential, options) {
       const protocol = options?.challenge ? protocolForChallenge.get(options.challenge) : undefined
       const fallback = protocols[0]
@@ -168,12 +153,6 @@ export function mcp() {
       return mcpPaymentRequiredChallenges(response)
     },
 
-    getChallenge(response) {
-      const challenge = mcpPaymentRequiredChallenges(response)[0]
-      if (!challenge) throw new Error('No challenge in response.')
-      return challenge
-    },
-
     setCredential(request, credential) {
       const parsed = Credential.deserialize(credential)
       return {

package/src/client/internal/Fetch.ts

@@ -238,9 +238,7 @@ export function from<const methods extends readonly Method.AnyClient[]>(
 
     try {
       for (let retry = 0; retry < maxPaymentRetries; retry++) {
-        challenges = transport.getChallenges
-          ? await transport.getChallenges(response, transportRequest as never)
-          : [await transport.getChallenge(response, transportRequest as never)]
+        challenges = await transport.getChallenges(response, transportRequest as never)
 
         const candidates = AcceptPayment.selectChallengeCandidates(
           challenges,
@@ -420,9 +418,7 @@ export function from<const methods extends readonly Method.AnyClient[]>(
       }
       challenges = undefined
       try {
-        challenges = transport.getChallenges
-          ? await transport.getChallenges(response, transportRequest as never)
-          : [await transport.getChallenge(response, transportRequest as never)]
+        challenges = await transport.getChallenges(response, transportRequest as never)
       } catch {}
       await settleAttempt(preparedCredential, {
         challenges,

package/src/discovery/OpenApi.test.ts

@@ -1,3 +1,4 @@
+import * as Challenge from '../Challenge.js'
 import * as Method from '../Method.js'
 import * as Mppx from '../server/Mppx.js'
 import * as z from '../zod.js'
@@ -56,6 +57,8 @@ const subscribe = Method.toServer(
       credential: { payload: z.object({ signature: z.string() }) },
       request: z.object({
         amount: z.string(),
+        interval: z.string(),
+        recipient: z.string(),
       }),
     },
   }),
@@ -69,6 +72,38 @@ const subscribe = Method.toServer(
   },
 )
 
+const transformedCharge = Method.toServer(
+  Method.from({
+    intent: 'charge',
+    name: 'transformed',
+    schema: {
+      credential: { payload: z.object({ signature: z.string() }) },
+      request: z.pipe(
+        z.object({
+          amount: z.string(),
+          asset: z.string(),
+          decimals: z.number(),
+          recipient: z.string(),
+        }),
+        z.transform(({ amount, asset, decimals, recipient }) => ({
+          amount: String(Number(amount) * 10 ** decimals),
+          currency: asset,
+          methodDetails: { decimals },
+          recipient,
+        })),
+      ),
+    },
+  }),
+  {
+    verify: async () => ({
+      method: 'transformed',
+      reference: '',
+      status: 'success' as const,
+      timestamp: '',
+    }),
+  },
+)
+
 function createMppx<const methods extends Mppx.Methods>(methods: methods) {
   return Mppx.create({
     methods,
@@ -169,6 +204,7 @@ describe('generate', () => {
                   {
                     "amount": "50",
                     "currency": "usd",
+                    "description": "Search credits",
                     "intent": "charge",
                     "method": "tempo",
                     "recipient": "0x1",
@@ -182,6 +218,140 @@ describe('generate', () => {
     `)
   })
 
+  test('matches handler discovery to its canonical runtime challenge', async () => {
+    const mppx = createMppx([transformedCharge])
+    const handler = mppx.charge({
+      amount: '2',
+      asset: '0xUSDC',
+      decimals: 6,
+      description: 'Canonical price',
+      recipient: '0x1',
+    })
+
+    const doc = generate(mppx, {
+      routes: [{ handler, method: 'post', path: '/api/resource' }],
+    }) as any
+    const result = await handler(new Request('https://example.com/api/resource'))
+    if (result.status !== 402) throw new Error('Expected payment challenge')
+    const challenge = Challenge.fromResponse(result.challenge)
+
+    expect(doc.paths['/api/resource'].post['x-payment-info'].offers[0]).toEqual({
+      amount: challenge.request.amount,
+      currency: challenge.request.currency,
+      description: challenge.description,
+      intent: challenge.intent,
+      method: challenge.method,
+      recipient: challenge.request.recipient,
+    })
+  })
+
+  test('applies method schema transforms to legacy route discovery', () => {
+    const mppx = createMppx([transformedCharge])
+    const doc = generate(mppx, {
+      routes: [
+        {
+          intent: 'charge',
+          method: 'post',
+          options: {
+            amount: '2',
+            asset: '0xUSDC',
+            decimals: 6,
+            description: 'Canonical price',
+            recipient: '0x1',
+          },
+          path: '/api/resource',
+        },
+      ],
+    }) as any
+
+    expect(doc.paths['/api/resource'].post['x-payment-info'].offers[0]).toEqual({
+      amount: '2000000',
+      currency: '0xUSDC',
+      description: 'Canonical price',
+      intent: 'charge',
+      method: 'transformed',
+      recipient: '0x1',
+    })
+  })
+
+  test('derives only explicitly composed payment offers from a handler', () => {
+    const mppx = createMppx([charge, session])
+    const handler = mppx.compose(
+      ['tempo/charge', { amount: '50', currency: '0xUSDC', description: 'USDC', recipient: '0x1' }],
+      [
+        'tempo/charge',
+        { amount: '50', currency: '0xNANOUSD', description: 'NANOUSD', recipient: '0x1' },
+      ],
+    )
+
+    const doc = generate(mppx, {
+      routes: [{ handler, method: 'post', path: '/api/search' }],
+    }) as any
+
+    expect(doc.paths['/api/search'].post['x-payment-info'].offers).toEqual([
+      {
+        amount: '50',
+        currency: '0xUSDC',
+        description: 'USDC',
+        intent: 'charge',
+        method: 'tempo',
+        recipient: '0x1',
+      },
+      {
+        amount: '50',
+        currency: '0xNANOUSD',
+        description: 'NANOUSD',
+        intent: 'charge',
+        method: 'tempo',
+        recipient: '0x1',
+      },
+    ])
+  })
+
+  test('keeps nested composed discovery in runtime challenge order', async () => {
+    const mppx = createMppx([charge])
+    const handler = Mppx.compose(
+      mppx.charge({
+        amount: '1',
+        currency: '0xUSDC',
+        description: 'USDC',
+        recipient: '0x1',
+      }),
+      Mppx.compose(
+        mppx.charge({
+          amount: '2',
+          currency: '0xNANOUSD',
+          description: 'NANOUSD',
+          recipient: '0x1',
+        }),
+        mppx.charge({
+          amount: '3',
+          currency: 'usd',
+          description: 'Card',
+          recipient: '0x1',
+        }),
+      ),
+    )
+
+    const doc = generate(mppx, {
+      routes: [{ handler, method: 'post', path: '/api/search' }],
+    }) as any
+    const result = await handler(new Request('https://example.com/api/search'))
+    if (result.status !== 402) throw new Error('Expected payment challenge')
+
+    const discovered = doc.paths['/api/search'].post['x-payment-info'].offers
+    const challenged = Challenge.fromResponseList(result.challenge).map((challenge) => ({
+      amount: challenge.request.amount,
+      currency: challenge.request.currency,
+      description: challenge.description,
+      intent: challenge.intent,
+      method: challenge.method,
+      recipient: challenge.request.recipient,
+    }))
+
+    expect(discovered).toEqual(challenged)
+  })
+
   test('handles null amount for session intent', () => {
     const mppx = createMppx([session])
     const doc = generate(mppx, {

package/src/discovery/OpenApi.ts

@@ -1,12 +1,11 @@
 import type * as Method from '../Method.js'
+import * as PaymentRequest from '../PaymentRequest.js'
 import { PaymentInfo, type ServiceInfo } from './Discovery.js'
+import * as Metadata from './internal/Metadata.js'
 
+/** Payment handler carrying metadata used to generate discovery documents. */
 export type DiscoveryHandler = ((...args: any[]) => unknown) & {
-  _internal?: {
-    _canonicalRequest: Record<string, unknown>
-    intent: string
-    name: string
-  }
+  _internal?: Metadata.Metadata
 }
 
 export type LegacyRouteConfig = {
@@ -151,11 +150,9 @@ function resolveRoute(
     return {
       method: route.method,
       path: route.path,
-      payment: paymentInfoFromCanonical({
-        canonicalRequest: internal._canonicalRequest,
-        intent: internal.intent,
-        method: internal.name,
-      }),
+      payment: {
+        offers: Metadata.offers(internal).map(Metadata.paymentOffer),
+      },
       ...(route.requestBody ? { requestBody: route.requestBody } : {}),
       ...(route.summary ? { summary: route.summary } : {}),
     }
@@ -168,52 +165,23 @@ function resolveRoute(
     )
   }
 
+  const { description, ...options } = route.options
+  const metadata: Metadata.Offer = {
+    _canonicalRequest: PaymentRequest.fromMethod(mi, options as never),
+    ...(typeof description === 'string' ? { description } : {}),
+    intent: mi.intent,
+    name: mi.name,
+  }
+
   return {
     method: route.method,
     path: route.path,
-    payment: paymentInfoFromCanonical({
-      canonicalRequest: route.options,
-      intent: mi.intent,
-      method: mi.name,
-    }),
+    payment: Metadata.paymentOffer(metadata),
     ...(route.requestBody ? { requestBody: route.requestBody } : {}),
     ...(route.summary ? { summary: route.summary } : {}),
   }
 }
 
-function paymentInfoFromCanonical(route: {
-  canonicalRequest: Record<string, unknown>
-  intent: string
-  method: string
-}) {
-  const { canonicalRequest, intent, method } = route
-  const methodDetails = (canonicalRequest.methodDetails ?? {}) as Record<string, unknown>
-
-  const amount = pickString(canonicalRequest.amount) ?? pickString(methodDetails.amount) ?? null
-  const currency = pickString(canonicalRequest.currency) ?? pickString(methodDetails.currency)
-  const description = pickString(canonicalRequest.description)
-
-  const base: Record<string, unknown> = {
-    amount,
-    ...(currency ? { currency } : {}),
-    ...(description ? { description } : {}),
-    intent,
-    method,
-  }
-
-  // Forward any extra canonical params that aren't already covered.
-  const reserved = new Set(['amount', 'currency', 'description', 'methodDetails'])
-  for (const [key, value] of Object.entries(canonicalRequest)) {
-    if (!reserved.has(key) && value !== undefined) base[key] = value
-  }
-
-  return base
-}
-
-function pickString(value: unknown) {
-  return typeof value === 'string' ? value : undefined
-}
-
 function withBasePath(basePath: string | undefined, path: string) {
   if (!basePath) return path
   const normalizedBasePath = basePath.startsWith('/') ? basePath : `/${basePath}`

package/src/discovery/internal/Metadata.ts

@@ -0,0 +1,51 @@
+/** Metadata retained by one explicitly configured payment handler. */
+export type Offer = {
+  _canonicalRequest: Record<string, unknown>
+  description?: string | undefined
+  intent: string
+  name: string
+}
+
+/** Metadata retained by a single or composed payment handler. */
+export type Metadata = Offer | { offers: readonly Offer[] }
+
+/** Returns every explicitly configured offer from discovery metadata. */
+export function offers(metadata: Metadata): readonly Offer[] {
+  if (isComposed(metadata)) return metadata.offers
+  return [metadata]
+}
+
+/** Converts configured handler metadata into a discovery payment offer. */
+export function paymentOffer(metadata: Offer): Record<string, unknown> {
+  const { _canonicalRequest: request, intent, name: method } = metadata
+  const methodDetails = (request.methodDetails ?? {}) as Record<string, unknown>
+
+  const amount = pickString(request.amount) ?? pickString(methodDetails.amount) ?? null
+  const currency = pickString(request.currency) ?? pickString(methodDetails.currency)
+  const description = pickString(metadata.description) ?? pickString(request.description)
+
+  const offer: Record<string, unknown> = {
+    amount,
+    ...(currency ? { currency } : {}),
+    ...(description ? { description } : {}),
+    intent,
+    method,
+  }
+
+  // Preserve extension fields emitted by method request schemas.
+  const reserved = new Set(['amount', 'currency', 'description', 'methodDetails'])
+  for (const [key, value] of Object.entries(request)) {
+    if (!reserved.has(key) && value !== undefined) offer[key] = value
+  }
+
+  return offer
+}
+
+/** Returns whether metadata represents a composed handler. */
+export function isComposed(metadata: Metadata): metadata is Extract<Metadata, { offers: unknown }> {
+  return 'offers' in metadata && !('_canonicalRequest' in metadata)
+}
+
+function pickString(value: unknown) {
+  return typeof value === 'string' ? value : undefined
+}

package/src/evm/server/Charge.ts

@@ -24,6 +24,8 @@ export function charge(parameters: charge.NativeConfig): Method.AnyServer {
   const transport = httpTransport(paths)
 
   return Method.toServer<typeof Methods.charge, charge.Defaults, typeof transport>(Methods.charge, {
+    canOffer: parameters.canOffer,
+    onPaymentSuccess: parameters.onPaymentSuccess,
     defaults: {
       chainId: config.chainId,
       currency: config.currency,
@@ -107,7 +109,10 @@ export declare namespace charge {
   type Parameters = NativeConfig
   type Native = Method.Server<typeof Methods.charge, Defaults>
 
-  type NativeConfig = BaseConfig & CurrencyConfig & RecipientConfig
+  type NativeConfig = BaseConfig &
+    CurrencyConfig &
+    RecipientConfig &
+    Method.ComposableHooks<typeof Methods.charge>
 
   type BaseConfig = {
     /** EIP-3009 token domain metadata. Required for raw addresses and viem tokens; inferred for known assets. */

package/src/internal/AcceptPayment.test.ts

@@ -226,21 +226,21 @@ describe('AcceptPayment', () => {
   test('selectChallengeCandidates supports duplicate method keys with challenge predicates', () => {
     const challenges = [
       {
-        id: 'v2',
+        id: 'primary',
         intent: 'session',
         method: 'tempo',
         realm: 'test',
-        request: { methodDetails: { sessionProtocol: 'v2' } },
+        request: { methodDetails: { sessionProtocol: 'primary' } },
       },
       {
-        id: 'v1',
+        id: 'fallback',
         intent: 'session',
         method: 'tempo',
         realm: 'test',
-        request: { methodDetails: { sessionProtocol: 'v1' } },
+        request: { methodDetails: { sessionProtocol: 'fallback' } },
       },
       {
-        id: 'old-server',
+        id: 'unmarked',
         intent: 'session',
         method: 'tempo',
         realm: 'test',
@@ -257,7 +257,7 @@ describe('AcceptPayment', () => {
           challenge: AcceptPayment.ChallengeCandidate['challenge']
         }) =>
           (challenge.request.methodDetails as { sessionProtocol?: string } | undefined)
-            ?.sessionProtocol === 'v2',
+            ?.sessionProtocol === 'primary',
       },
       {
         name: 'tempo',
@@ -270,7 +270,7 @@ describe('AcceptPayment', () => {
           const sessionProtocol = (
             challenge.request.methodDetails as { sessionProtocol?: string } | undefined
           )?.sessionProtocol
-          return sessionProtocol === undefined || sessionProtocol === 'v1'
+          return sessionProtocol === undefined || sessionProtocol === 'fallback'
         },
       },
     ] as const
@@ -281,7 +281,11 @@ describe('AcceptPayment', () => {
       AcceptPayment.parse('tempo/session'),
     )
 
-    expect(candidates.map(({ challenge }) => challenge.id)).toEqual(['v2', 'v1', 'old-server'])
+    expect(candidates.map(({ challenge }) => challenge.id)).toEqual([
+      'primary',
+      'fallback',
+      'unmarked',
+    ])
   })
 
   test('selectChallenge honors a specific opt-out over a broader wildcard', () => {

package/src/internal/types.ts

@@ -2,6 +2,15 @@
 // https://twitter.com/mattpocockuk/status/1622730173446557697?s=20&t=NdpAcmEFXY01xkqU3KO0Mg
 export type Compute<type> = { [key in keyof type]: type[key] } & unknown
 
+/** Recursively makes every property of a value readonly. */
+export type DeepReadonly<type> = type extends (...args: infer _arguments) => infer _return
+  ? type
+  : type extends readonly unknown[]
+    ? { readonly [key in keyof type]: DeepReadonly<type[key]> }
+    : type extends object
+      ? { readonly [key in keyof type]: DeepReadonly<type[key]> }
+      : type
+
 declare const symbol: unique symbol
 
 /**