feat: add client payment events (#441)

* feat: add client payment events

* refactor: use rettime for client events

* refactor: remove client event config

* fix: harden client event dispatch

Author: brendanjryan

.changeset/client-events.md

@@ -0,0 +1,5 @@
+---
+'mppx': patch
+---
+
+Added typed client payment events for challenge handling, credential creation, payment responses, and failures.

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', () => {

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({