mppx 0.8.13 → 0.8.15

package/src/cli/validate/payment.ts

@@ -46,6 +46,20 @@ async function provisionAndPayTestnet(
     await Promise.all(hashes.map((hash) => waitForTransactionReceipt(client, { hash })))
     if (!silent) console.log(pc.dim(`    Using wallet: ${account.address}`))
 
+    // The faucet tx receipt can land before the RPC's balance reads are
+    // consistent with it, so poll briefly for the funded balance to appear
+    // rather than racing straight into the charge.
+    const currency = (challenge.request as Record<string, unknown>).currency
+    if (typeof currency === 'string') {
+      for (let attempt = 0; attempt < 10; attempt++) {
+        const balance = await Actions.token
+          .getBalance(client, { account: account.address, token: currency as Address })
+          .catch(() => undefined)
+        if (balance && balance.amount > 0n) break
+        await new Promise((resolve) => setTimeout(resolve, 500))
+      }
+    }
+
     const methods = [...tempoMethods({ account })]
     return { methods }
   } catch (error) {
@@ -198,7 +212,7 @@ export async function validatePaymentFlow(
         const mppx = Mppx.create({ methods: provisioned.methods, polyfill: false })
         const cred = await mppx.createCredential(fakeResp)
         results.push(check('Payment: submitted', 'ephemeral testnet wallet'))
-        return await sendAndValidateResponse(
+        await sendAndValidateResponse(
           results,
           url,
           endpoint,
@@ -210,17 +224,17 @@ export async function validatePaymentFlow(
         )
       } catch (error) {
         results.push(fail('Payment: create credential', (error as Error).message))
-        return results
       }
     } else {
       results.push(
         fail('Payment: auto-provision wallet', 'Failed to create and fund testnet wallet'),
       )
-      return results
     }
+    options.onResults?.(results)
   }
 
-  // Try each challenge method (skip testnet challenge already handled above)
+  // Try each remaining challenge method (tempo testnet already handled above),
+  // so validate exercises every payment method the server offers, same as mainnet.
   const loaded = await loadConfig().catch(() => undefined)
   const isInteractive = options.interactive
   const stripeKey = process.env.MPPX_STRIPE_SECRET_KEY ?? resolveStripeKey(verbose)

package/src/cli/validate.test.ts

@@ -707,6 +707,22 @@ describe('validate: multi-challenge', () => {
     const { output } = await serve(['validate', server.url])
     expect(output).toContain('Amount is valid integer string (Got: 1.50)')
   })
+
+  test("tempo doesn't block other testnet methods", { timeout: 15_000 }, async () => {
+    // makeChallenge() defaults to a tempo testnet challenge (chainId 42431),
+    // which takes the ephemeral-wallet fast path. That path used to return
+    // immediately, so a server offering evm/stripe alongside tempo would
+    // never have those methods exercised. It should now fall through and
+    // try them too, same as it does for tempo mainnet challenges.
+    const server = await multiChallengeServer([makeChallenge(), makeEvmChallenge()])
+    const { output } = await serve(['validate', server.url, '--outputJson', '--yes'])
+    const jsonStart = output.indexOf('{')
+    const jsonEnd = output.lastIndexOf('}')
+    const result = JSON.parse(output.slice(jsonStart, jsonEnd + 1))
+    const paymentLabels = result.endpoints[0].payment.map((r: { label: string }) => r.label)
+    expect(paymentLabels).toContain('Payment: submitted')
+    expect(paymentLabels.some((l: string) => l.includes('[evm]'))).toBe(true)
+  })
 })
 
 describe('validate: payment methods coverage', () => {

package/src/client/Mppx.test-d.ts

@@ -262,9 +262,9 @@ describe('fetch context', () => {
     type FetchInit = NonNullable<Parameters<typeof _mppx.fetch>[1]>
     type Context = NonNullable<FetchInit['context']>
 
-    // Context is a union of charge and session contexts.
-    // `account` exists on both; `autoSwap` only on charge.
+    // Context is a union of charge and session contexts; both support auto-swap.
     expectTypeOf<Context>().toHaveProperty('account')
-    expectTypeOf<Extract<Context, { autoSwap?: unknown }>>().toHaveProperty('autoSwap')
+    expectTypeOf<Context>().toHaveProperty('autoSwap')
+    expectTypeOf<Context['autoSwap']>().toEqualTypeOf<AutoSwap.resolve.Value | undefined>()
   })
 })

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

@@ -6,6 +6,7 @@ import type { MaybePromise } from '../../internal/types.js'
 import type * as Method from '../../Method.js'
 import type * as z from '../../zod.js'
 import * as Transport from '../Transport.js'
+import * as MethodChallenge from './MethodChallenge.js'
 import * as MethodResponse from './MethodResponse.js'
 
 // We tag wrappers with a global symbol so we can recognize wrappers created by mppx,
@@ -18,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,
@@ -209,6 +234,7 @@ 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++) {
@@ -228,6 +254,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
@@ -241,9 +272,60 @@ export function from<const methods extends readonly Method.AnyClient[]>(
         mi = selected.method
         if (challenge.expires) Expires.assert(challenge.expires, challenge.id)
 
+        const paymentInput = resolvePaymentRetryInput(
+          response,
+          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(
-          (overrideContext?: AnyContextFor<methods>) =>
-            resolveCredential(selectedChallenge, selected.method, overrideContext ?? context),
+          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
+            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(
           'challenge.received',
@@ -265,6 +347,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',
@@ -278,11 +365,6 @@ export function from<const methods extends readonly Method.AnyClient[]>(
           }),
         )
 
-        const paymentInput = resolvePaymentRetryInput(
-          response,
-          initialRequest.input,
-          initialRequest.input,
-        )
         response = await baseFetch(
           paymentInput,
           transport.setCredential(
@@ -294,6 +376,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(
@@ -307,7 +400,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,
@@ -325,8 +418,24 @@ 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)]
+      } 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({
@@ -875,11 +984,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

@@ -0,0 +1,35 @@
+import type * as Challenge from '../../Challenge.js'
+import type { MaybePromise } from '../../internal/types.js'
+import type * as Method from '../../Method.js'
+
+const handlers = new WeakMap<Method.AnyClient, Handler>()
+
+/** Inputs available before a client method creates a challenge credential. */
+export type HandlerParameters = {
+  challenge: Challenge.Challenge
+  context?: unknown
+  fetch: typeof globalThis.fetch
+  input: RequestInfo | URL
+}
+
+/** Internal client-method challenge hook. */
+export type Handler = (parameters: HandlerParameters) => MaybePromise<void>
+
+/** Registers an internal challenge hook without changing the public method shape. */
+export function register<const method extends Method.AnyClient>(
+  method: method,
+  handler: Handler,
+): method {
+  handlers.set(method, handler)
+  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)

package/src/server/Mppx.test-d.ts

@@ -223,6 +223,8 @@ describe('Mppx type tests', () => {
     const mppx = Mppx.create({ methods: [alphaMethod], realm, secretKey })
 
     expectTypeOf(mppx.verifyCredential).toBeFunction()
+    expectTypeOf(mppx.broadcastCredential).toBeFunction()
+    expectTypeOf(mppx.validateCredential).toBeFunction()
   })
 
   test('server events receive typed method context', () => {