mppx 0.6.20 → 0.6.21

package/dist/tempo/server/internal/html.gen.js.map

@@ -1 +1 @@
-{"version":3,"file":"html.gen.js","sourceRoot":"","sources":["../../../../src/tempo/server/internal/html.gen.ts"],"names":[],"mappings":"AAAA,2BAA2B;AAC3B,MAAM,CAAC,MAAM,IAAI,GAAG,w4keAAw4ke,CAAA"}
+{"version":3,"file":"html.gen.js","sourceRoot":"","sources":["../../../../src/tempo/server/internal/html.gen.ts"],"names":[],"mappings":"AAAA,2BAA2B;AAC3B,MAAM,CAAC,MAAM,IAAI,GAAG,s+teAAs+te,CAAA"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mppx",
   "type": "module",
-  "version": "0.6.20",
+  "version": "0.6.21",
   "main": "./dist/index.js",
   "license": "MIT",
   "files": [

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

@@ -1,13 +1,17 @@
 import type { Account } from 'viem'
 import { describe, expectTypeOf, test } from 'vp/test'
 
+import * as Challenge from '../Challenge.js'
+import type * as Mcp from '../Mcp.js'
 import * as Method from '../Method.js'
 import { charge } from '../tempo/client/Charge.js'
 import { tempo } from '../tempo/client/Methods.js'
 import type * as AutoSwap from '../tempo/internal/auto-swap.js'
 import * as Methods from '../tempo/Methods.js'
 import * as z from '../zod.js'
+import * as Fetch from './internal/Fetch.js'
 import * as Mppx from './Mppx.js'
+import * as Transport from './Transport.js'
 
 describe('Mppx', () => {
   test('has methods array', () => {
@@ -63,6 +67,57 @@ describe('create.Config', () => {
 
     expectTypeOf(mppx.fetch).toBeFunction()
   })
+
+  test('client events expose typed payloads', () => {
+    const method = charge()
+    const mppx = Mppx.create({
+      methods: [method],
+    })
+
+    const unsubscribe = mppx.on('payment.response', (payload) => {
+      expectTypeOf(payload.response).toEqualTypeOf<Response>()
+    })
+    expectTypeOf(unsubscribe).toEqualTypeOf<Fetch.Unsubscribe>()
+
+    mppx.on('*', (event) => {
+      if (event.name === 'credential.created')
+        expectTypeOf(event.payload.credential).toEqualTypeOf<string>()
+      if (event.name === 'payment.response')
+        expectTypeOf(event.payload.response).toEqualTypeOf<Response>()
+    })
+    mppx.onChallengeReceived((payload) => {
+      expectTypeOf(payload.challenge.id).toEqualTypeOf<string>()
+      expectTypeOf(payload.challenges).toEqualTypeOf<readonly Challenge.Challenge[]>()
+      expectTypeOf(payload.method.intent).toEqualTypeOf<'charge'>()
+      expectTypeOf(payload.createCredential({ account: {} as Account })).toEqualTypeOf<
+        Promise<string>
+      >()
+      return payload.createCredential({ account: {} as Account })
+    })
+    mppx.onCredentialCreated((payload) => {
+      expectTypeOf(payload.credential).toEqualTypeOf<string>()
+      expectTypeOf(payload.method.intent).toEqualTypeOf<'charge'>()
+    })
+    mppx.onPaymentFailed((payload) => {
+      expectTypeOf(payload.error).toEqualTypeOf<unknown>()
+      expectTypeOf(payload.challenge).toEqualTypeOf<Challenge.Challenge | undefined>()
+    })
+    mppx.onPaymentResponse((payload) => {
+      expectTypeOf(payload.response).toEqualTypeOf<Response>()
+      expectTypeOf(payload.credential).toEqualTypeOf<string>()
+    })
+  })
+
+  test('client events use transport response types', () => {
+    const mppx = Mppx.create({
+      methods: [tempo({ account: {} as Account })],
+      transport: Transport.mcp(),
+    })
+
+    mppx.onChallengeReceived((payload) => {
+      expectTypeOf(payload.response).toMatchTypeOf<Response | Mcp.Response>()
+    })
+  })
 })
 
 describe('Method.toClient', () => {

package/src/client/Mppx.test.ts

@@ -108,11 +108,143 @@ describe('createCredential', () => {
     expect(parsed.challenge.method).toBe('tempo')
   })
 
+  test('behavior: createCredential emits client events and supports runtime handlers', async () => {
+    const events: string[] = []
+    const createCredential = vi.fn(async ({ challenge }) =>
+      Credential.serialize({
+        challenge,
+        payload: { signature: '0xsignature', type: 'transaction' },
+      }),
+    )
+    const method = Method.toClient(Methods.charge, { createCredential })
+    const mppx = Mppx.create({
+      polyfill: false,
+      methods: [method],
+    })
+    mppx.onCredentialCreated((payload) => {
+      events.push(`credential:${payload.credential.startsWith('Payment ')}`)
+    })
+    const offCredential = mppx.onCredentialCreated(() => {
+      events.push('removed')
+    })
+    const offChallenge = mppx.onChallengeReceived((payload) => {
+      events.push(`runtime:${payload.method.intent}`)
+      return payload.createCredential()
+    })
+    mppx.on('*', (event) => {
+      events.push(`*:${event.name}`)
+    })
+    offCredential()
+
+    const challenge = Challenge.fromMethod(Methods.charge, {
+      realm,
+      secretKey,
+      expires: new Date(Date.now() + 60_000).toISOString(),
+      request: {
+        amount: '1000',
+        currency: '0x1234567890123456789012345678901234567890',
+        decimals: 6,
+        recipient: '0x1234567890123456789012345678901234567890',
+      },
+    })
+    const response = new Response(null, {
+      status: 402,
+      headers: {
+        'WWW-Authenticate': Challenge.serialize(challenge),
+      },
+    })
+
+    const credential = await mppx.createCredential(response)
+    offChallenge()
+
+    expect(credential).toMatch(/^Payment /)
+    expect(createCredential).toHaveBeenCalledTimes(1)
+    expect(events).toEqual([
+      'runtime:charge',
+      '*:challenge.received',
+      'credential:true',
+      '*:credential.created',
+    ])
+  })
+
+  test('behavior: createCredential memoizes event helper calls', async () => {
+    const createCredential = vi.fn(async ({ challenge }) =>
+      Credential.serialize({
+        challenge,
+        payload: { signature: '0xsignature', type: 'transaction' },
+      }),
+    )
+    const method = Method.toClient(Methods.charge, { createCredential })
+    const mppx = Mppx.create({
+      polyfill: false,
+      methods: [method],
+    })
+    mppx.on('*', async (event) => {
+      if (event.name === 'challenge.received') await event.payload.createCredential()
+    })
+
+    const challenge = Challenge.fromMethod(Methods.charge, {
+      realm,
+      secretKey,
+      expires: new Date(Date.now() + 60_000).toISOString(),
+      request: {
+        amount: '1000',
+        currency: '0x1234567890123456789012345678901234567890',
+        decimals: 6,
+        recipient: '0x1234567890123456789012345678901234567890',
+      },
+    })
+    const response = new Response(null, {
+      status: 402,
+      headers: {
+        'WWW-Authenticate': Challenge.serialize(challenge),
+      },
+    })
+
+    await mppx.createCredential(response)
+
+    expect(createCredential).toHaveBeenCalledTimes(1)
+  })
+
+  test('behavior: createCredential validates event credentials', async () => {
+    const mppx = Mppx.create({
+      polyfill: false,
+      methods: [tempo({ account: accounts[1], getClient: () => client })],
+    })
+    mppx.onChallengeReceived(() => 'Payment invalid\r\nX-Injected: true')
+
+    const challenge = Challenge.fromMethod(Methods.charge, {
+      realm,
+      secretKey,
+      expires: new Date(Date.now() + 60_000).toISOString(),
+      request: {
+        amount: '1000',
+        currency: '0x1234567890123456789012345678901234567890',
+        decimals: 6,
+        recipient: '0x1234567890123456789012345678901234567890',
+      },
+    })
+    const response = new Response(null, {
+      status: 402,
+      headers: {
+        'WWW-Authenticate': Challenge.serialize(challenge),
+      },
+    })
+
+    await expect(mppx.createCredential(response)).rejects.toThrow('illegal newline')
+  })
+
   test('behavior: throws when method not found', async () => {
+    const events: string[] = []
     const mppx = Mppx.create({
       polyfill: false,
       methods: [tempo({ account: accounts[1], getClient: () => client })],
     })
+    mppx.onPaymentFailed((payload) => {
+      events.push(
+        `failed:${payload.challenge === undefined}:${payload.challenges?.length}:${payload.error instanceof Error}`,
+      )
+    })
 
     const challenge = Challenge.from({
       id: 'test-id',
@@ -132,6 +264,7 @@ describe('createCredential', () => {
     await expect(mppx.createCredential(response)).rejects.toThrow(
       'No method found for challenges: unknown.charge. Available: tempo.charge, tempo.session',
     )
+    expect(events).toEqual(['failed:true:1:true'])
   })
 
   test('behavior: rejects expired challenges before creating credential', async () => {
@@ -451,6 +584,54 @@ describe('createCredential', () => {
     expect((parsed.payload as { type: string }).type).toBe('transaction')
     expect(parsed.challenge.method).toBe('tempo')
   })
+
+  test('behavior: mcp transport event responses are not cast to DOM Response', async () => {
+    const method = Method.toClient(Methods.charge, {
+      async createCredential({ challenge }) {
+        return Credential.serialize({
+          challenge,
+          payload: { signature: '0xsignature', type: 'transaction' },
+        })
+      },
+    })
+    const mppx = Mppx.create({
+      polyfill: false,
+      methods: [method],
+      transport: Transport.mcp(),
+    })
+
+    const challenge = Challenge.fromMethod(Methods.charge, {
+      realm,
+      secretKey,
+      expires: new Date(Date.now() + 60_000).toISOString(),
+      request: {
+        amount: '1000',
+        currency: '0x1234567890123456789012345678901234567890',
+        decimals: 6,
+        recipient: '0x1234567890123456789012345678901234567890',
+      },
+    })
+    const mcpResponse: Mcp.Response = {
+      jsonrpc: '2.0',
+      id: 1,
+      error: {
+        code: Mcp.paymentRequiredCode,
+        message: 'Payment Required',
+        data: {
+          httpStatus: 402,
+          challenges: [challenge],
+        },
+      },
+    }
+    const seen: unknown[] = []
+    mppx.onChallengeReceived((event) => {
+      seen.push(event.response)
+    })
+
+    await mppx.createCredential(mcpResponse)
+
+    expect(seen).toEqual([mcpResponse])
+  })
 })
 
 const server = Mppx_server.create({

package/src/client/Mppx.ts

@@ -7,6 +7,9 @@ import * as Fetch from './internal/Fetch.js'
 import * as Transport from './Transport.js'
 
 export type Methods = readonly (Method.AnyClient | readonly Method.AnyClient[])[]
+type EventResponseOf<transport extends Transport.Transport> =
+  | Response
+  | Transport.ResponseOf<transport>
 
 /**
  * Client-side payment handler.
@@ -29,6 +32,43 @@ export type Mppx<
     context?: AnyContextFor<FlattenMethods<methods>> | undefined,
     options?: createCredential.Options | undefined,
   ) => Promise<string>
+  /** Register a client event handler by canonical event name. */
+  on<name extends Fetch.ClientEventName<FlattenMethods<methods>, EventResponseOf<transport>>>(
+    name: name,
+    handler: Fetch.ClientEventHandler<FlattenMethods<methods>, name, EventResponseOf<transport>>,
+  ): Fetch.Unsubscribe
+  /** Register a handler for received payment challenges. */
+  onChallengeReceived(
+    handler: Fetch.ClientEventHandler<
+      FlattenMethods<methods>,
+      'challenge.received',
+      EventResponseOf<transport>
+    >,
+  ): Fetch.Unsubscribe
+  /** Register a handler for created credentials. */
+  onCredentialCreated(
+    handler: Fetch.ClientEventHandler<
+      FlattenMethods<methods>,
+      'credential.created',
+      EventResponseOf<transport>
+    >,
+  ): Fetch.Unsubscribe
+  /** Register a handler for failed automatic payment handling. */
+  onPaymentFailed(
+    handler: Fetch.ClientEventHandler<
+      FlattenMethods<methods>,
+      'payment.failed',
+      EventResponseOf<transport>
+    >,
+  ): Fetch.Unsubscribe
+  /** Register a handler for payment retry responses. */
+  onPaymentResponse(
+    handler: Fetch.ClientEventHandler<
+      FlattenMethods<methods>,
+      'payment.response',
+      EventResponseOf<transport>
+    >,
+  ): Fetch.Unsubscribe
 }
 
 /**
@@ -71,6 +111,7 @@ 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 events = Fetch.createEventDispatcher<FlattenMethods<methods>, EventResponseOf<transport>>()
 
   const resolvedOnChallenge = onChallenge as Fetch.from.Config<
     FlattenMethods<methods>
@@ -79,17 +120,64 @@ export function create<
     acceptPayment,
     acceptPaymentPolicy,
     ...(config.fetch && { fetch: config.fetch }),
+    eventDispatcher: events,
     ...(resolvedOnChallenge && { onChallenge: resolvedOnChallenge }),
     methods,
   } satisfies Fetch.from.Config<FlattenMethods<methods>>
   const fetch = Fetch.from<FlattenMethods<methods>>(config_fetch)
 
   if (polyfill) Fetch.polyfill(config_fetch)
+
+  function onChallengeReceived(
+    handler: Fetch.ClientEventHandler<
+      FlattenMethods<methods>,
+      'challenge.received',
+      EventResponseOf<transport>
+    >,
+  ) {
+    return events.on('challenge.received', handler)
+  }
+
+  function onCredentialCreated(
+    handler: Fetch.ClientEventHandler<
+      FlattenMethods<methods>,
+      'credential.created',
+      EventResponseOf<transport>
+    >,
+  ) {
+    return events.on('credential.created', handler)
+  }
+
+  function onPaymentFailed(
+    handler: Fetch.ClientEventHandler<
+      FlattenMethods<methods>,
+      'payment.failed',
+      EventResponseOf<transport>
+    >,
+  ) {
+    return events.on('payment.failed', handler)
+  }
+
+  function onPaymentResponse(
+    handler: Fetch.ClientEventHandler<
+      FlattenMethods<methods>,
+      'payment.response',
+      EventResponseOf<transport>
+    >,
+  ) {
+    return events.on('payment.response', handler)
+  }
+
   return {
     fetch,
     rawFetch,
     methods,
     transport,
+    on: events.on,
+    onChallengeReceived,
+    onCredentialCreated,
+    onPaymentFailed,
+    onPaymentResponse,
     async createCredential(
       response: Transport.ResponseOf<transport>,
       context?: unknown,
@@ -100,23 +188,59 @@ export function create<
         : [transport.getChallenge(response as never)]
       const preferences = resolveChallengePreferences(acceptPayment.entries, options?.acceptPayment)
 
-      const selected = AcceptPayment.selectChallenge(challenges, methods, preferences)
-      if (!selected)
-        throw new Error(
-          `No method found for challenges: ${challenges.map((challenge) => `${challenge.method}.${challenge.intent}`).join(', ')}. Available: ${methods.map((m) => `${m.name}.${m.intent}`).join(', ')}`,
-        )
+      let challenge: Challenge.Challenge | undefined
+      let mi: FlattenMethods<methods>[number] | undefined
+      try {
+        const selected = AcceptPayment.selectChallenge(challenges, methods, preferences)
+        if (!selected)
+          throw new Error(
+            `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
-      if (challenge.expires) Expires.assert(challenge.expires, challenge.id)
+        const selectedChallenge = selected.challenge
+        challenge = selectedChallenge
+        mi = selected.method as FlattenMethods<methods>[number]
+        if (challenge.expires) Expires.assert(challenge.expires, challenge.id)
 
-      const parsedContext =
-        mi.context && context !== undefined ? mi.context.parse(context) : undefined
-
-      return mi.createCredential(
-        parsedContext !== undefined
-          ? { challenge, context: parsedContext }
-          : ({ challenge } as never),
-      )
+        const createCredential = memoizeCreateCredential(
+          (overrideContext?: AnyContextFor<FlattenMethods<methods>>) =>
+            createCredentialForMethod(selectedChallenge, mi!, overrideContext ?? context),
+        )
+        const eventCredential = await events.emit(
+          'challenge.received',
+          createChallengeReceivedPayload({
+            challenge: selectedChallenge,
+            challenges,
+            createCredential,
+            method: mi,
+            response,
+          }),
+        )
+        const credential = eventCredential ?? (await createCredential())
+        Fetch.validateCredentialHeaderValue(credential)
+        await events.emit(
+          'credential.created',
+          createCredentialCreatedPayload({
+            challenge: selectedChallenge,
+            credential,
+            method: mi,
+            response,
+          }),
+        )
+        return credential
+      } catch (error) {
+        await events.emit(
+          'payment.failed',
+          createPaymentFailedPayload({
+            challenge,
+            challenges,
+            error,
+            method: mi,
+            response,
+          }),
+        )
+        throw error
+      }
     },
   }
 }
@@ -155,7 +279,7 @@ export declare namespace create {
     acceptPaymentPolicy?: Fetch.from.Config['acceptPaymentPolicy'] | undefined
     /** Custom fetch function to wrap. Defaults to `globalThis.fetch`. */
     fetch?: typeof globalThis.fetch
-    /** Called when a 402 challenge is received, before credential creation. */
+    /** Called when a 402 challenge is received and no event handler supplies a credential. */
     onChallenge?:
       | ((
           challenge: Challenge.Challenge,
@@ -187,6 +311,103 @@ type AnyContextFor<methods extends readonly Method.AnyClient[]> = {
     : undefined
 }[number]
 
+function memoizeCreateCredential<methods extends readonly Method.AnyClient[]>(
+  createCredential: (context?: AnyContextFor<methods>) => Promise<string>,
+) {
+  let promise: Promise<string> | undefined
+  return (context?: AnyContextFor<methods>) => {
+    promise ??= createCredential(context)
+    return promise
+  }
+}
+
+function createChallengeReceivedPayload<
+  methods extends readonly Method.AnyClient[],
+  response,
+>(parameters: {
+  challenge: Challenge.Challenge
+  challenges: readonly Challenge.Challenge[]
+  createCredential: (context?: AnyContextFor<methods>) => Promise<string>
+  method: methods[number]
+  response: response
+}): Fetch.ChallengeReceivedPayload<methods, response> {
+  return Object.freeze({
+    challenge: snapshotValue(parameters.challenge),
+    challenges: parameters.challenges.map((challenge) => snapshotValue(challenge)),
+    createCredential: parameters.createCredential,
+    method: snapshotMethod(parameters.method),
+    response: snapshotResponse(parameters.response),
+  }) as never
+}
+
+function createCredentialCreatedPayload<
+  methods extends readonly Method.AnyClient[],
+  response,
+>(parameters: {
+  challenge: Challenge.Challenge
+  credential: string
+  method: methods[number]
+  response: response
+}): Fetch.CredentialCreatedPayload<methods, response> {
+  return Object.freeze({
+    challenge: snapshotValue(parameters.challenge),
+    credential: parameters.credential,
+    method: snapshotMethod(parameters.method),
+    response: snapshotResponse(parameters.response),
+  }) as never
+}
+
+function createPaymentFailedPayload<
+  methods extends readonly Method.AnyClient[],
+  response,
+>(parameters: {
+  challenge?: Challenge.Challenge | undefined
+  challenges?: readonly Challenge.Challenge[] | undefined
+  error: unknown
+  method?: methods[number] | undefined
+  response: response
+}): Fetch.PaymentFailedPayload<methods, response> {
+  return Object.freeze({
+    ...(parameters.challenge ? { challenge: snapshotValue(parameters.challenge) } : {}),
+    ...(parameters.challenges
+      ? { challenges: parameters.challenges.map((challenge) => snapshotValue(challenge)) }
+      : {}),
+    error: parameters.error,
+    ...(parameters.method ? { method: snapshotMethod(parameters.method) } : {}),
+    response: snapshotResponse(parameters.response),
+  }) as never
+}
+
+function snapshotMethod<method extends Method.AnyClient>(method: method): method {
+  return freezeSnapshot(Object.assign({}, method)) as method
+}
+
+function snapshotResponse<response>(response: response): response {
+  if (response instanceof Response) return response.clone() as response
+  return snapshotValue(response)
+}
+
+function snapshotValue<value>(value: value): value {
+  try {
+    return deepFreeze(structuredClone(value))
+  } catch {
+    return freezeSnapshot(value)
+  }
+}
+
+function deepFreeze<value>(value: value): value {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value
+  Object.freeze(value)
+  for (const child of Object.values(value as Record<string, unknown>)) deepFreeze(child)
+  return value
+}
+
+function freezeSnapshot<value>(value: value): value {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value
+  Object.freeze(value)
+  return value
+}
+
 /**
  * Flattens a methods config tuple, preserving positional types.
  * @internal
@@ -209,3 +430,14 @@ function resolveChallengePreferences(
   if (!override) return fallback
   return typeof override === 'string' ? AcceptPayment.parse(override) : override
 }
+
+async function createCredentialForMethod(
+  challenge: Challenge.Challenge,
+  mi: Method.AnyClient,
+  context: unknown,
+): Promise<string> {
+  const parsedContext = mi.context && context !== undefined ? mi.context.parse(context) : undefined
+  return mi.createCredential(
+    parsedContext !== undefined ? { challenge, context: parsedContext } : ({ challenge } as never),
+  )
+}

package/src/client/internal/Fetch.test-d.ts

@@ -1,6 +1,7 @@
 import type { Account } from 'viem'
 import { describe, expectTypeOf, test } from 'vp/test'
 
+import * as Challenge from '../../Challenge.js'
 import { charge } from '../../tempo/client/Charge.js'
 import * as Fetch from './Fetch.js'
 
@@ -44,6 +45,36 @@ describe('Fetch.from', () => {
       body: JSON.stringify({ foo: 'bar' }),
     })
   })
+
+  test('behavior: events infer payload types from methods', () => {
+    const method = charge()
+    const dispatcher = Fetch.createEventDispatcher<[typeof method]>()
+    dispatcher.on('*', (event) => {
+      if (event.name === 'challenge.received')
+        expectTypeOf(event.payload.challenge).toEqualTypeOf<Challenge.Challenge>()
+    })
+    dispatcher.on('challenge.received', (payload) => {
+      expectTypeOf(payload.method.intent).toEqualTypeOf<'charge'>()
+      return payload.createCredential({ account: {} as Account })
+    })
+    dispatcher.on('credential.created', (payload) => {
+      expectTypeOf(payload.method.intent).toEqualTypeOf<'charge'>()
+      expectTypeOf(payload.credential).toEqualTypeOf<string>()
+    })
+    dispatcher.on('payment.failed', (payload) => {
+      expectTypeOf(payload.error).toEqualTypeOf<unknown>()
+    })
+    dispatcher.on('payment.response', (payload) => {
+      expectTypeOf(payload.response).toEqualTypeOf<Response>()
+    })
+
+    const fetch = Fetch.from({
+      eventDispatcher: dispatcher,
+      methods: [method],
+    })
+
+    expectTypeOf(fetch).toBeFunction()
+  })
 })
 
 describe('Fetch.from.RequestInit', () => {