mppx 0.5.11 → 0.5.13

package/src/client/Mppx.test.ts

@@ -130,7 +130,7 @@ describe('createCredential', () => {
     })
 
     await expect(mppx.createCredential(response)).rejects.toThrow(
-      'No method found for "unknown.charge". Available: tempo.charge, tempo.session',
+      'No method found for challenges: unknown.charge. Available: tempo.charge, tempo.session',
     )
   })
 
@@ -187,6 +187,135 @@ describe('createCredential', () => {
     expect(parsed.challenge.method).toBe('stripe')
   })
 
+  test('behavior: selects the preferred challenge from a multi-challenge response', async () => {
+    const stripeCharge = Method.from({
+      name: 'stripe',
+      intent: 'charge',
+      schema: {
+        credential: {
+          payload: Methods.charge.schema.credential.payload,
+        },
+        request: Methods.charge.schema.request,
+      },
+    })
+
+    const stripe = Method.toClient(stripeCharge, {
+      async createCredential({ challenge }) {
+        return Credential.serialize({
+          challenge,
+          payload: { signature: '0xstripe', type: 'transaction' },
+        })
+      },
+    })
+
+    const mppx = Mppx.create({
+      polyfill: false,
+      methods: [tempo({ account: accounts[1], getClient: () => client }), stripe],
+      paymentPreferences: ({ stripe }) => ({
+        [stripe.charge]: 0.5,
+      }),
+    })
+
+    const tempoChallenge = Challenge.fromMethod(Methods.charge, {
+      realm,
+      secretKey,
+      expires: new Date(Date.now() + 60_000).toISOString(),
+      request: {
+        amount: '1000',
+        currency: '0x1234567890123456789012345678901234567890',
+        decimals: 6,
+        recipient: '0x1234567890123456789012345678901234567890',
+      },
+    })
+    const stripeChallenge = Challenge.from({
+      id: 'stripe-challenge-id',
+      realm,
+      method: 'stripe',
+      intent: 'charge',
+      request: {
+        amount: '2000',
+        currency: '0xabcd',
+        recipient: '0xefgh',
+      },
+    })
+
+    const response = new Response(null, {
+      status: 402,
+      headers: {
+        'WWW-Authenticate': `${Challenge.serialize(stripeChallenge)}, ${Challenge.serialize(tempoChallenge)}`,
+      },
+    })
+
+    const credential = await mppx.createCredential(response)
+    const parsed = Credential.deserialize(credential)
+
+    expect(parsed.challenge.method).toBe('tempo')
+  })
+
+  test('behavior: createCredential accepts a request-local Accept-Payment override', async () => {
+    const stripeCharge = Method.from({
+      name: 'stripe',
+      intent: 'charge',
+      schema: {
+        credential: {
+          payload: Methods.charge.schema.credential.payload,
+        },
+        request: Methods.charge.schema.request,
+      },
+    })
+
+    const stripe = Method.toClient(stripeCharge, {
+      async createCredential({ challenge }) {
+        return Credential.serialize({
+          challenge,
+          payload: { signature: '0xstripe', type: 'transaction' },
+        })
+      },
+    })
+
+    const mppx = Mppx.create({
+      polyfill: false,
+      methods: [tempo({ account: accounts[1], getClient: () => client }), stripe],
+    })
+
+    const tempoChallenge = Challenge.fromMethod(Methods.charge, {
+      realm,
+      secretKey,
+      expires: new Date(Date.now() + 60_000).toISOString(),
+      request: {
+        amount: '1000',
+        currency: '0x1234567890123456789012345678901234567890',
+        decimals: 6,
+        recipient: '0x1234567890123456789012345678901234567890',
+      },
+    })
+    const stripeChallenge = Challenge.from({
+      id: 'stripe-challenge-id',
+      realm,
+      method: 'stripe',
+      intent: 'charge',
+      request: {
+        amount: '2000',
+        currency: '0xabcd',
+        recipient: '0xefgh',
+      },
+    })
+
+    const response = new Response(null, {
+      status: 402,
+      headers: {
+        'WWW-Authenticate': `${Challenge.serialize(stripeChallenge)}, ${Challenge.serialize(tempoChallenge)}`,
+      },
+    })
+
+    const credential = await mppx.createCredential(response, undefined, {
+      acceptPayment: 'stripe/charge, tempo/charge;q=0.1',
+    })
+    const parsed = Credential.deserialize(credential)
+
+    expect(parsed.challenge.method).toBe('stripe')
+  })
+
   test('behavior: passes context to createCredential', async () => {
     const mppx = Mppx.create({
       polyfill: false,

package/src/client/Mppx.ts

@@ -1,4 +1,5 @@
 import type * as Challenge from '../Challenge.js'
+import * as AcceptPayment from '../internal/AcceptPayment.js'
 import type * as Method from '../Method.js'
 import type * as z from '../zod.js'
 import * as Fetch from './internal/Fetch.js'
@@ -25,6 +26,7 @@ export type Mppx<
   createCredential: (
     response: Transport.ResponseOf<transport>,
     context?: AnyContextFor<FlattenMethods<methods>> | undefined,
+    options?: createCredential.Options | undefined,
   ) => Promise<string>
 }
 
@@ -61,11 +63,13 @@ export function create<
   const rawFetch = config.fetch ?? globalThis.fetch
 
   const methods = config.methods.flat() as unknown as FlattenMethods<methods>
+  const acceptPayment = AcceptPayment.resolve(methods, config.paymentPreferences)
 
   const resolvedOnChallenge = onChallenge as Fetch.from.Config<
     FlattenMethods<methods>
   >['onChallenge']
   const config_fetch = {
+    acceptPayment,
     ...(config.fetch && { fetch: config.fetch }),
     ...(resolvedOnChallenge && { onChallenge: resolvedOnChallenge }),
     methods,
@@ -78,15 +82,24 @@ export function create<
     rawFetch,
     methods,
     transport,
-    async createCredential(response: Transport.ResponseOf<transport>, context?: unknown) {
-      const challenge = transport.getChallenge(response as never) as Challenge.Challenge
+    async createCredential(
+      response: Transport.ResponseOf<transport>,
+      context?: unknown,
+      options?: createCredential.Options,
+    ) {
+      const challenges = transport.getChallenges
+        ? transport.getChallenges(response as never)
+        : [transport.getChallenge(response as never)]
+      const preferences = resolveChallengePreferences(acceptPayment.entries, options?.acceptPayment)
 
-      const mi = methods.find((m) => m.name === challenge.method && m.intent === challenge.intent)
-      if (!mi)
+      const selected = AcceptPayment.selectChallenge(challenges, methods, preferences)
+      if (!selected)
         throw new Error(
-          `No method found for "${challenge.method}.${challenge.intent}". Available: ${methods.map((m) => `${m.name}.${m.intent}`).join(', ')}`,
+          `No method found for challenges: ${challenges.map((challenge) => `${challenge.method}.${challenge.intent}`).join(', ')}. Available: ${methods.map((m) => `${m.name}.${m.intent}`).join(', ')}`,
         )
 
+      const { challenge, method: mi } = selected
+
       const parsedContext =
         mi.context && context !== undefined ? mi.context.parse(context) : undefined
 
@@ -99,6 +112,13 @@ export function create<
   }
 }
 
+export declare namespace createCredential {
+  type Options = {
+    /** Request-local Accept-Payment override for manual rawFetch + createCredential flows. */
+    acceptPayment?: string | readonly AcceptPayment.Entry[] | undefined
+  }
+}
+
 /**
  * Restores the original `fetch` after `create()` polyfilled it.
  *
@@ -133,6 +153,8 @@ export declare namespace create {
           },
         ) => Promise<string | undefined>)
       | undefined
+    /** Client-declared supported payment methods, keyed by typed `method/intent` strings. */
+    paymentPreferences?: AcceptPayment.Config<FlattenMethods<methods>> | undefined
     /** Array of methods to use. Accepts individual clients or tuples (e.g. from `tempo()`). */
     methods: methods
     /** Whether to polyfill `globalThis.fetch` with the payment-aware wrapper. @default true */
@@ -168,3 +190,11 @@ type FlattenMethods<methods extends Methods> = methods extends readonly [
       ? readonly [head, ...FlattenMethods<tail>]
       : never
   : readonly []
+
+function resolveChallengePreferences(
+  fallback: readonly AcceptPayment.Entry[],
+  override?: string | readonly AcceptPayment.Entry[] | undefined,
+): readonly AcceptPayment.Entry[] {
+  if (!override) return fallback
+  return typeof override === 'string' ? AcceptPayment.parse(override) : override
+}

package/src/client/Transport.test.ts

@@ -57,20 +57,18 @@ describe('http', () => {
         },
       })
 
-      expect(transport.getChallenge(response)).toMatchInlineSnapshot(`
-        {
-          "expires": "2025-01-01T00:00:00.000Z",
-          "id": "0hnrySRDqWfttlDIJpuxV4mJsRJIS7d7RjnufuonJOE",
-          "intent": "charge",
-          "method": "tempo",
-          "realm": "api.example.com",
-          "request": {
-            "amount": "1000",
-            "currency": "0x20c0000000000000000000000000000000000001",
-            "recipient": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00",
-          },
-        }
-      `)
+      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', () => {
@@ -81,6 +79,24 @@ describe('http', () => {
     })
   })
 
+  describe('getChallenges', () => {
+    test('returns all HTTP challenges', () => {
+      const transport = Transport.http()
+      const alternate = { ...challenge, id: 'alternate', method: 'stripe' as const }
+      const response = new Response(null, {
+        status: 402,
+        headers: {
+          'WWW-Authenticate': `${Challenge.serialize(challenge)}, ${Challenge.serialize(alternate)}`,
+        },
+      })
+
+      expect(transport.getChallenges?.(response).map((entry) => entry.id)).toEqual([
+        challenge.id,
+        'alternate',
+      ])
+    })
+  })
+
   describe('setCredential', () => {
     test('default', () => {
       const transport = Transport.http()
@@ -89,9 +105,7 @@ describe('http', () => {
       const result = transport.setCredential({}, serialized)
       const headers = result.headers as Headers
 
-      expect(headers.get('Authorization')).toMatchInlineSnapshot(
-        `"Payment eyJjaGFsbGVuZ2UiOnsiZXhwaXJlcyI6IjIwMjUtMDEtMDFUMDA6MDA6MDAuMDAwWiIsImlkIjoiMGhucnlTUkRxV2Z0dGxESUpwdXhWNG1Kc1JKSVM3ZDdSam51ZnVvbkpPRSIsImludGVudCI6ImNoYXJnZSIsIm1ldGhvZCI6InRlbXBvIiwicmVhbG0iOiJhcGkuZXhhbXBsZS5jb20iLCJyZXF1ZXN0IjoiZXlKaGJXOTFiblFpT2lJeE1EQXdJaXdpWTNWeWNtVnVZM2tpT2lJd2VESXdZekF3TURBd01EQXdNREF3TURBd01EQXdNREF3TURBd01EQXdNREF3TURBd01EQXdNREVpTENKeVpXTnBjR2xsYm5RaU9pSXdlRGMwTW1Rek5VTmpOall6TkVNd05UTXlPVEkxWVROaU9EUTBRbU01WlRjMU9UVm1PR1pGTURBaWZRIn0sInBheWxvYWQiOnsic2lnbmF0dXJlIjoiMHhhYmMxMjMiLCJ0eXBlIjoidHJhbnNhY3Rpb24ifX0"`,
-      )
+      expect(headers.get('Authorization')).toBe(serialized)
     })
 
     test('preserves existing headers', () => {
@@ -178,20 +192,18 @@ describe('mcp', () => {
         },
       }
 
-      expect(transport.getChallenge(response)).toMatchInlineSnapshot(`
-        {
-          "expires": "2025-01-01T00:00:00.000Z",
-          "id": "0hnrySRDqWfttlDIJpuxV4mJsRJIS7d7RjnufuonJOE",
-          "intent": "charge",
-          "method": "tempo",
-          "realm": "api.example.com",
-          "request": {
-            "amount": "1000",
-            "currency": "0x20c0000000000000000000000000000000000001",
-            "recipient": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00",
-          },
-        }
-      `)
+      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 success response', () => {
@@ -224,39 +236,60 @@ describe('mcp', () => {
     })
   })
 
+  describe('getChallenges', () => {
+    test('returns all MCP challenges', () => {
+      const transport = Transport.mcp()
+      const response: Mcp.Response = {
+        jsonrpc: '2.0',
+        id: 1,
+        error: {
+          code: Mcp.paymentRequiredCode,
+          message: 'Payment Required',
+          data: {
+            httpStatus: 402,
+            challenges: [challenge, { ...challenge, id: 'alternate', method: 'stripe' }],
+          },
+        },
+      }
+
+      expect(transport.getChallenges?.(response).map((entry) => entry.id)).toEqual([
+        challenge.id,
+        'alternate',
+      ])
+    })
+  })
+
   describe('setCredential', () => {
     test('default', () => {
       const transport = Transport.mcp()
       const serialized = Credential.serialize(credential)
 
-      expect(transport.setCredential(mcpRequest, serialized)).toMatchInlineSnapshot(`
-        {
-          "method": "tools/call",
-          "params": {
-            "_meta": {
-              "org.paymentauth/credential": {
-                "challenge": {
-                  "expires": "2025-01-01T00:00:00.000Z",
-                  "id": "0hnrySRDqWfttlDIJpuxV4mJsRJIS7d7RjnufuonJOE",
-                  "intent": "charge",
-                  "method": "tempo",
-                  "realm": "api.example.com",
-                  "request": {
-                    "amount": "1000",
-                    "currency": "0x20c0000000000000000000000000000000000001",
-                    "recipient": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00",
-                  },
-                },
-                "payload": {
-                  "signature": "0xabc123",
-                  "type": "transaction",
+      expect(transport.setCredential(mcpRequest, serialized)).toMatchObject({
+        method: 'tools/call',
+        params: {
+          _meta: {
+            'org.paymentauth/credential': {
+              challenge: {
+                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',
                 },
               },
+              payload: {
+                signature: '0xabc123',
+                type: 'transaction',
+              },
             },
-            "name": "test-tool",
           },
-        }
-      `)
+          name: 'test-tool',
+        },
+      })
     })
 
     test('preserves existing _meta', () => {

package/src/client/Transport.ts

@@ -13,6 +13,8 @@ export type Transport<in out request = unknown, in out response = unknown> = {
   name: string
   /** Checks if a response indicates payment is required. */
   isPaymentRequired: (response: response) => boolean
+  /** Extracts all challenges from a payment-required response, when the transport supports multiple offers. */
+  getChallenges?: (response: response) => Challenge.Challenge[]
   /** Extracts the challenge from a payment-required response. */
   getChallenge: (response: response) => Challenge.Challenge
   /** Attaches a credential to a request. */
@@ -64,6 +66,10 @@ export function http() {
       return response.status === 402
     },
 
+    getChallenges(response) {
+      return Challenge.fromResponseList(response)
+    },
+
     getChallenge(response) {
       return Challenge.fromResponse(response)
     },
@@ -91,6 +97,13 @@ export function mcp() {
       return 'error' in response && response.error?.code === Mcp.paymentRequiredCode
     },
 
+    getChallenges(response) {
+      if (!('error' in response) || !response.error) throw new Error('Response is not an error.')
+      const challenges = response.error.data?.challenges
+      if (!challenges?.length) throw new Error('No challenge in error response.')
+      return challenges
+    },
+
     getChallenge(response) {
       if (!('error' in response) || !response.error) throw new Error('Response is not an error.')
       const challenge = response.error.data?.challenges[0]

package/src/client/internal/Fetch.browser.test.ts

@@ -22,6 +22,10 @@ function make402() {
   })
 }
 
+function toHeaders(headers: unknown): Headers {
+  return new Headers((headers ?? {}) as HeadersInit)
+}
+
 /** Returns a fetch wrapper and the init captured from the 402 retry call. */
 function setup() {
   const calls: (RequestInit | undefined)[] = []
@@ -38,7 +42,7 @@ function setup() {
     /** Headers sent on the retry (second) request. */
     retryHeaders: async (input: RequestInfo | URL, init?: RequestInit) => {
       await fetch(input, init)
-      return (calls[1] as Record<string, unknown>)?.headers as Record<string, string>
+      return toHeaders((calls[1] as Record<string, unknown>)?.headers)
     },
   }
 }
@@ -49,9 +53,9 @@ describe('Fetch.from: browser header normalization', () => {
     const h = await retryHeaders('https://example.com', {
       headers: new Headers({ 'X-Custom': 'value', 'Content-Type': 'application/json' }),
     })
-    expect(h['x-custom']).toBe('value')
-    expect(h['content-type']).toBe('application/json')
-    expect(h.Authorization).toBe('credential')
+    expect(h.get('x-custom')).toBe('value')
+    expect(h.get('content-type')).toBe('application/json')
+    expect(h.get('authorization')).toBe('credential')
   })
 
   test('preserves header tuples', async () => {
@@ -62,9 +66,9 @@ describe('Fetch.from: browser header normalization', () => {
         ['Accept', 'application/json'],
       ],
     })
-    expect(h['X-Custom']).toBe('value')
-    expect(h.Accept).toBe('application/json')
-    expect(h.Authorization).toBe('credential')
+    expect(h.get('x-custom')).toBe('value')
+    expect(h.get('accept')).toBe('application/json')
+    expect(h.get('authorization')).toBe('credential')
   })
 
   test('replaces authorization case-insensitively', async () => {
@@ -72,22 +76,21 @@ describe('Fetch.from: browser header normalization', () => {
     const h = await retryHeaders('https://example.com', {
       headers: { authorization: 'Bearer stale', 'X-Custom': 'value' },
     })
-    expect(h.authorization).toBeUndefined()
-    expect(h.Authorization).toBe('credential')
-    expect(h['X-Custom']).toBe('value')
+    expect(h.get('authorization')).toBe('credential')
+    expect(h.get('x-custom')).toBe('value')
   })
 
   test('preserves plain object headers', async () => {
     const { retryHeaders } = setup()
     const h = await retryHeaders('https://example.com', { headers: { 'X-Custom': 'val' } })
-    expect(h['X-Custom']).toBe('val')
-    expect(h.Authorization).toBe('credential')
+    expect(h.get('x-custom')).toBe('val')
+    expect(h.get('authorization')).toBe('credential')
   })
 
   test('adds Authorization when no headers provided', async () => {
     const { retryHeaders } = setup()
     const h = await retryHeaders('https://example.com')
-    expect(h.Authorization).toBe('credential')
+    expect(h.get('authorization')).toBe('credential')
   })
 })