mppx 0.8.14 → 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.test.ts

@@ -10,6 +10,7 @@ import { rpcUrl } from '~test/tempo/rpc.js'
 import { accounts, asset, chain, client, http } from '~test/tempo/viem.js'
 
 import * as Fetch from './Fetch.js'
+import * as MethodChallenge from './MethodChallenge.js'
 import * as MethodResponse from './MethodResponse.js'
 
 const realm = 'api.example.com'
@@ -337,6 +338,23 @@ const noopMethod = {
   createCredential: async () => 'credential',
 } as any
 
+function trackedMethod(settlements: MethodResponse.AttemptOutcome['status'][]) {
+  const method = {
+    ...noopMethod,
+    async createCredential(parameters: object) {
+      const attempt = MethodResponse.getAttempt(parameters)
+      if (attempt)
+        attempt.settle = (outcome) => {
+          settlements.push(outcome.status)
+          return outcome.status !== 'pending'
+        }
+      return 'credential'
+    },
+  }
+  MethodChallenge.register(method, () => undefined)
+  return MethodResponse.register(method, ({ response }) => response)
+}
+
 const x402PaymentRequired = {
   accepts: [
     {
@@ -418,6 +436,30 @@ describe('Fetch.from: method responses', () => {
     expect(handle).toHaveBeenCalledWith(expect.objectContaining({ credential: 'credential' }))
     expect(paidResponse?.clone).not.toHaveBeenCalled()
   })
+
+  test.each([
+    ['a rejected paid response', () => new Response('rejected', { status: 500 }), 500, undefined],
+    ['the final payment retry', () => make402(), 402, 1],
+    [
+      'the paid request throwing',
+      () => Promise.reject(new Error('paid request failed')),
+      undefined,
+      undefined,
+    ],
+  ])('settles credential state after %s', async (_name, paidRequest, status, maxPaymentRetries) => {
+    const settlements: MethodResponse.AttemptOutcome['status'][] = []
+    let calls = 0
+    const fetch = Fetch.from({
+      fetch: async () => (++calls === 1 ? make402() : paidRequest()),
+      maxPaymentRetries,
+      methods: [trackedMethod(settlements)],
+    })
+
+    const result = fetch('https://example.com/paid')
+    if (status) expect((await result).status).toBe(status)
+    else await expect(result).rejects.toThrow('paid request failed')
+    expect(settlements).toEqual(['rejected'])
+  })
 })
 
 describe('Fetch.from: init passthrough (non-402)', () => {
@@ -1873,6 +1915,41 @@ describe('Fetch.from: 402 retry path', () => {
     ).toEqual(['credential-first', 'credential-second', 'credential-third'])
   })
 
+  test('invalidates a prepared credential across a generic challenge', async () => {
+    const firstCredential = vi.fn(async () => 'first')
+    const first = { ...noopMethod, name: 'first', createCredential: firstCredential }
+    const second = { ...noopMethod, name: 'second', createCredential: async () => 'second' }
+    MethodChallenge.register(first, () => undefined)
+    const responses = [
+      make402({ id: 'first', method: 'first' }),
+      make402({ id: 'second', method: 'second' }),
+      make402({ id: 'first', method: 'first' }),
+      new Response('OK'),
+    ]
+    const mockFetch = vi.fn(async () => responses.shift()!)
+    const fetch = Fetch.from({ fetch: mockFetch, methods: [first, second] })
+
+    expect((await fetch('https://example.com/api')).status).toBe(200)
+    expect(firstCredential).toHaveBeenCalledTimes(2)
+  })
+
+  test('invalidates a prepared credential after an explicit context', async () => {
+    const createCredential = vi.fn(async () => 'credential')
+    const method = { ...noopMethod, createCredential }
+    MethodChallenge.register(method, () => undefined)
+    let challenges = 0
+    const mockFetch = vi.fn(async () => (++challenges <= 3 ? make402() : new Response('OK')))
+    const fetch = Fetch.from({
+      fetch: mockFetch as typeof globalThis.fetch,
+      methods: [method],
+      onChallenge: async (_challenge, { createCredential: create }) =>
+        challenges === 2 ? create({ override: true } as never) : undefined,
+    })
+
+    expect((await fetch('https://example.com/api')).status).toBe(200)
+    expect(createCredential).toHaveBeenCalledTimes(3)
+  })
+
   test('caps repeated 402 retries at three', async () => {
     let callCount = 0
     const createCredential = vi.fn(async () => 'credential')

package/src/client/internal/Fetch.ts

@@ -19,9 +19,33 @@ type WrappedFetch = typeof globalThis.fetch & {
   [MPPX_FETCH_WRAPPER]?: typeof globalThis.fetch
 }
 
+/** Credential state retained between payment retries until its method settles it. */
+type PreparedCredential = {
+  /** Method-owned preparation and settlement hooks. */
+  attempt: MethodResponse.Attempt
+  /** Serialized challenge used to recognize the same retry. */
+  key?: string | undefined
+  /** Method that prepared the credential. */
+  method: Method.AnyClient
+  /** Memoized credential reused for the same retry. */
+  promise: Promise<string>
+}
+
 let originalFetch: typeof globalThis.fetch | undefined
 const eventObserverChecks = new WeakMap<object, (name: keyof ClientEventMap) => boolean>()
 
+async function settleAttempt(
+  prepared: PreparedCredential | undefined,
+  outcome: MethodResponse.AttemptOutcome,
+): Promise<boolean> {
+  const settle = prepared?.attempt.settle
+  if (!settle) return outcome.status !== 'pending'
+  prepared.attempt.settle = undefined
+  const settled = await settle(outcome)
+  if (!settled) prepared.attempt.settle = settle
+  return settled
+}
+
 export type ClientEventMap<
   methods extends readonly Method.AnyClient[] = readonly Method.AnyClient[],
   response = Response,
@@ -210,12 +234,11 @@ export function from<const methods extends readonly Method.AnyClient[]>(
     let challenge: Challenge.Challenge | undefined
     let challenges: readonly Challenge.Challenge[] | undefined
     let mi: methods[number] | undefined
+    let preparedCredential: PreparedCredential | undefined
 
     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,
@@ -229,6 +252,11 @@ export function from<const methods extends readonly Method.AnyClient[]>(
         )
         const selected = orderedCandidates[0]
         if (!selected) {
+          await settleAttempt(preparedCredential, {
+            challenges,
+            response,
+            status: 'rejected',
+          })
           // A post-payment 402 with no actionable challenge (e.g. rejected credential)
           // is the server's final answer, not a new challenge round.
           if (retry > 0) return response
@@ -247,16 +275,54 @@ export function from<const methods extends readonly Method.AnyClient[]>(
           initialRequest.input,
           initialRequest.input,
         )
+        const previousCredential = preparedCredential
+        const key = Challenge.serialize(selectedChallenge)
+        const sameAttempt =
+          previousCredential?.method === selected.method && previousCredential?.key === key
+        let canReusePrevious = false
+        if (previousCredential) {
+          const settled = await settleAttempt(previousCredential, {
+            challenges,
+            response,
+            status: sameAttempt ? 'pending' : 'rejected',
+          })
+          canReusePrevious = sameAttempt && !settled
+        }
+        preparedCredential = canReusePrevious ? previousCredential : undefined
         const createCredential = memoizeCreateCredential(
           async (overrideContext?: AnyContextFor<methods>) => {
+            if (overrideContext === undefined && canReusePrevious && previousCredential) {
+              return previousCredential.promise
+            }
+            if (canReusePrevious && previousCredential) {
+              await settleAttempt(previousCredential, { status: 'rejected' })
+              preparedCredential = undefined
+            }
+
             const credentialContext = overrideContext ?? context
-            await MethodChallenge.handle(selected.method, {
-              challenge: selectedChallenge,
-              context: credentialContext,
-              fetch: baseFetch,
-              input: paymentInput,
-            })
-            return resolveCredential(selectedChallenge, selected.method, credentialContext)
+            if (!MethodChallenge.has(selected.method))
+              return resolveCredential(selectedChallenge, selected.method, credentialContext)
+            const attempt: MethodResponse.Attempt = {
+              prepare: () =>
+                MethodChallenge.handle(selected.method, {
+                  challenge: selectedChallenge,
+                  context: credentialContext,
+                  fetch: baseFetch,
+                  input: paymentInput,
+                }),
+            }
+            const promise = attempt
+              .prepare()
+              .then(() =>
+                resolveCredential(selectedChallenge, selected.method, credentialContext, attempt),
+              )
+            preparedCredential = {
+              attempt,
+              key: overrideContext === undefined ? key : undefined,
+              method: selected.method,
+              promise,
+            }
+            return promise
           },
         )
         const eventCredential = await events.emit(
@@ -279,6 +345,11 @@ export function from<const methods extends readonly Method.AnyClient[]>(
               })
             : undefined)
         const credential = onChallengeCredential ?? (await createCredential())
+        const prepared = preparedCredential
+        if (prepared && (await prepared.promise.catch(() => undefined)) !== credential) {
+          await settleAttempt(prepared, { status: 'rejected' })
+          preparedCredential = undefined
+        }
         validateCredentialHeaderValue(credential)
         await events.emit(
           'credential.created',
@@ -303,6 +374,17 @@ export function from<const methods extends readonly Method.AnyClient[]>(
             { challenge: selectedChallenge },
           ),
         )
+        const paymentRequired = await transport.isPaymentRequired(
+          response,
+          transportRequest as never,
+        )
+        if (!paymentRequired) {
+          await settleAttempt(prepared, {
+            response,
+            status: response.ok ? 'accepted' : 'rejected',
+          })
+          preparedCredential = undefined
+        }
         // Cloning an unobserved stream would tee and buffer it indefinitely.
         if (response.ok && hasEventObservers(events, 'payment.response'))
           await events.emit(
@@ -316,7 +398,7 @@ export function from<const methods extends readonly Method.AnyClient[]>(
               response,
             }),
           )
-        if (!(await transport.isPaymentRequired(response, transportRequest as never))) {
+        if (!paymentRequired) {
           if (!response.ok) return response
           return MethodResponse.handle(selected.method, {
             challenge: selectedChallenge,
@@ -334,8 +416,22 @@ export function from<const methods extends readonly Method.AnyClient[]>(
           })
         }
       }
+      challenges = undefined
+      try {
+        challenges = await transport.getChallenges(response, transportRequest as never)
+      } catch {}
+      await settleAttempt(preparedCredential, {
+        challenges,
+        response,
+        status: 'rejected',
+      })
       return response
     } catch (error) {
+      await settleAttempt(preparedCredential, {
+        challenges,
+        response,
+        status: 'rejected',
+      })
       await events.emit(
         'payment.failed',
         createPaymentFailedPayload({
@@ -884,11 +980,13 @@ async function resolveCredential(
   challenge: Challenge.Challenge,
   mi: Method.AnyClient,
   context: unknown,
+  attempt?: MethodResponse.Attempt | undefined,
 ): Promise<string> {
   const parsedContext = mi.context && context !== undefined ? mi.context.parse(context) : undefined
-  return mi.createCredential(
-    parsedContext !== undefined ? { challenge, context: parsedContext } : ({ challenge } as never),
-  )
+  const parameters =
+    parsedContext !== undefined ? { challenge, context: parsedContext } : { challenge }
+  if (attempt) MethodResponse.attachAttempt(mi, parameters, attempt)
+  return mi.createCredential(parameters as never)
 }
 
 function resolvePaymentPreferences<methods extends readonly Method.AnyClient[]>(

package/src/client/internal/MethodChallenge.ts

@@ -24,6 +24,11 @@ export function register<const method extends Method.AnyClient>(
   return method
 }
 
+/** Returns whether a method registered pre-credential work. */
+export function has(method: Method.AnyClient): boolean {
+  return handlers.has(method)
+}
+
 /** Runs method-specific work before creating a challenge credential. */
 export function handle(method: Method.AnyClient, parameters: HandlerParameters): Promise<void> {
   return Promise.resolve(handlers.get(method)?.(parameters))

package/src/client/internal/MethodResponse.ts

@@ -3,6 +3,20 @@ import type { MaybePromise } from '../../internal/types.js'
 import type * as Method from '../../Method.js'
 
 const handlers = new WeakMap<Method.AnyClient, Handler>()
+const attempts = new WeakMap<object, Attempt>()
+
+export type AttemptOutcome = {
+  challenges?: readonly Challenge.Challenge[] | undefined
+  response?: Response | undefined
+  status: 'accepted' | 'pending' | 'rejected'
+}
+
+export type Attempt = {
+  /** Re-runs method preparation when serialized state changed before signing. */
+  prepare: () => Promise<void>
+  /** Settles state created for one credential attempt. */
+  settle?: ((outcome: AttemptOutcome) => MaybePromise<boolean>) | undefined
+}
 
 /** Inputs available when a client method handles a successful paid response. */
 export type HandlerParameters = {
@@ -33,6 +47,20 @@ export function unregister(method: Method.AnyClient): void {
   handlers.delete(method)
 }
 
+/** Adds response lifecycle state to internal credential parameters. */
+export function attachAttempt(
+  method: Method.AnyClient,
+  parameters: object,
+  attempt: Attempt,
+): void {
+  if (handlers.has(method)) attempts.set(parameters, attempt)
+}
+
+/** Reads response lifecycle state when Fetch owns this credential. */
+export function getAttempt(parameters: object): Attempt | undefined {
+  return attempts.get(parameters)
+}
+
 /** Lets the selected client method handle a successful paid response. */
 export function handle(method: Method.AnyClient, parameters: HandlerParameters): Promise<Response> {
   return Promise.resolve(handlers.get(method)?.(parameters) ?? parameters.response)