mppx 0.6.19 → 0.6.21

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

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

@@ -669,6 +669,267 @@ describe('Fetch.from: 402 retry path', () => {
     expect(headers.Authorization).toBe('credential')
   })
 
+  test('emits client events and allows challenge handler to provide credential', async () => {
+    const events: string[] = []
+    const createCredential = vi.fn(async () => 'method-credential')
+    let callCount = 0
+    const calls: { init: RequestInit | undefined }[] = []
+    const mockFetch: typeof globalThis.fetch = async (_input, init) => {
+      calls.push({ init })
+      callCount++
+      if (callCount === 1) return make402()
+      return new Response('OK', { status: 200 })
+    }
+
+    const method = { ...noopMethod, createCredential }
+    const eventDispatcher = Fetch.createEventDispatcher<[typeof method]>()
+    eventDispatcher.on('*', (event) => {
+      events.push(`*:${event.name}`)
+    })
+    eventDispatcher.on('challenge.received', async (payload) => {
+      events.push(`challenge:${payload.challenge.id}`)
+      return 'event-credential'
+    })
+    eventDispatcher.on('credential.created', (payload) => {
+      events.push(`credential:${payload.credential}`)
+      throw new Error('observer failed')
+    })
+    eventDispatcher.on('payment.response', (payload) => {
+      events.push(`response:${payload.response.status}`)
+      throw new Error('observer failed')
+    })
+
+    const fetch = Fetch.from({
+      eventDispatcher,
+      fetch: mockFetch,
+      methods: [method],
+    })
+
+    const response = await fetch('https://example.com/api')
+
+    expect(response.status).toBe(200)
+    expect(createCredential).not.toHaveBeenCalled()
+    const retryHeaders = new Headers((calls[1]!.init as RequestInit).headers)
+    expect(retryHeaders.get('Authorization')).toBe('event-credential')
+    expect(events).toEqual([
+      'challenge:abc',
+      '*:challenge.received',
+      'credential:event-credential',
+      '*:credential.created',
+      'response:200',
+      '*:payment.response',
+    ])
+  })
+
+  test('uses the first challenge event credential', async () => {
+    const events: string[] = []
+    const createCredential = vi.fn(async () => 'method-credential')
+    const method = { ...noopMethod, createCredential }
+    let callCount = 0
+    const calls: { init: RequestInit | undefined }[] = []
+    const mockFetch: typeof globalThis.fetch = async (_input, init) => {
+      calls.push({ init })
+      callCount++
+      if (callCount === 1) return make402()
+      return new Response('OK', { status: 200 })
+    }
+    const eventDispatcher = Fetch.createEventDispatcher<[typeof method]>()
+    eventDispatcher.on('challenge.received', () => {
+      events.push('first')
+      return 'first-credential'
+    })
+    eventDispatcher.on('challenge.received', () => {
+      events.push('second')
+      return 'second-credential'
+    })
+
+    const fetch = Fetch.from({
+      eventDispatcher,
+      fetch: mockFetch,
+      methods: [method],
+    })
+
+    await fetch('https://example.com/api')
+
+    expect(createCredential).not.toHaveBeenCalled()
+    const retryHeaders = new Headers((calls[1]!.init as RequestInit).headers)
+    expect(retryHeaders.get('Authorization')).toBe('first-credential')
+    expect(events).toEqual(['first'])
+  })
+
+  test('does not emit payment.response for non-ok retry responses', async () => {
+    const events: string[] = []
+    const createCredential = vi.fn(async () => 'method-credential')
+    const method = { ...noopMethod, createCredential }
+    let callCount = 0
+    const mockFetch: typeof globalThis.fetch = async () => {
+      callCount++
+      if (callCount === 1) return make402()
+      return new Response('Internal Server Error', { status: 500 })
+    }
+    const eventDispatcher = Fetch.createEventDispatcher<[typeof method]>()
+    eventDispatcher.on('payment.response', (payload) => {
+      events.push(`response:${payload.response.status}`)
+    })
+
+    const fetch = Fetch.from({
+      eventDispatcher,
+      fetch: mockFetch,
+      methods: [method],
+    })
+
+    const response = await fetch('https://example.com/api')
+
+    expect(response.status).toBe(500)
+    expect(events).toEqual([])
+  })
+
+  test('ignores empty challenge event credentials and continues handlers', async () => {
+    const createCredential = vi.fn(async () => 'method-credential')
+    const method = { ...noopMethod, createCredential }
+    let callCount = 0
+    const calls: { init: RequestInit | undefined }[] = []
+    const mockFetch: typeof globalThis.fetch = async (_input, init) => {
+      calls.push({ init })
+      callCount++
+      if (callCount === 1) return make402()
+      return new Response('OK', { status: 200 })
+    }
+    const eventDispatcher = Fetch.createEventDispatcher<[typeof method]>()
+    eventDispatcher.on('challenge.received', () => '')
+    eventDispatcher.on('challenge.received', () => 'second-credential')
+
+    const fetch = Fetch.from({
+      eventDispatcher,
+      fetch: mockFetch,
+      methods: [method],
+    })
+
+    await fetch('https://example.com/api')
+
+    expect(createCredential).not.toHaveBeenCalled()
+    const retryHeaders = new Headers((calls[1]!.init as RequestInit).headers)
+    expect(retryHeaders.get('Authorization')).toBe('second-credential')
+  })
+
+  test('memoizes createCredential across wildcard observers and fallback', async () => {
+    const createCredential = vi.fn(async () => 'method-credential')
+    const method = { ...noopMethod, createCredential }
+    let callCount = 0
+    const mockFetch: typeof globalThis.fetch = async () => {
+      callCount++
+      if (callCount === 1) return make402()
+      return new Response('OK', { status: 200 })
+    }
+    const eventDispatcher = Fetch.createEventDispatcher<[typeof method]>()
+    eventDispatcher.on('*', async (event) => {
+      if (event.name === 'challenge.received') await event.payload.createCredential()
+    })
+
+    const fetch = Fetch.from({
+      eventDispatcher,
+      fetch: mockFetch,
+      methods: [method],
+    })
+
+    await fetch('https://example.com/api')
+
+    expect(createCredential).toHaveBeenCalledTimes(1)
+  })
+
+  test('does not expose live challenges or init headers to observers', async () => {
+    const createCredential = vi.fn(async ({ challenge }) => `amount:${challenge.request.amount}`)
+    const method = { ...noopMethod, createCredential }
+    let callCount = 0
+    const calls: { init: RequestInit | undefined }[] = []
+    const mockFetch: typeof globalThis.fetch = async (_input, init) => {
+      calls.push({ init })
+      callCount++
+      if (callCount === 1) return make402()
+      return new Response('OK', { status: 200 })
+    }
+    const eventDispatcher = Fetch.createEventDispatcher<[typeof method]>()
+    eventDispatcher.on('*', (event) => {
+      if (event.name !== 'challenge.received') return
+      try {
+        ;(event.payload.challenge.request as { amount: string }).amount = '999'
+      } catch {}
+      const headers = new Headers(event.payload.init?.headers)
+      headers.set('Authorization', 'attacker')
+      if (event.payload.init) event.payload.init.headers = headers
+    })
+
+    const fetch = Fetch.from({
+      eventDispatcher,
+      fetch: mockFetch,
+      methods: [method],
+    })
+
+    await fetch('https://example.com/api', {
+      headers: { 'X-Test': '1' },
+    })
+
+    const retryHeaders = new Headers((calls[1]!.init as RequestInit).headers)
+    expect(retryHeaders.get('Authorization')).toBe('amount:1')
+  })
+
+  test('continues dispatching observer listeners after one throws', async () => {
+    const events: string[] = []
+    const method = { ...noopMethod, createCredential: vi.fn(async () => 'credential') }
+    let callCount = 0
+    const mockFetch: typeof globalThis.fetch = async () => {
+      callCount++
+      if (callCount === 1) return make402()
+      return new Response('OK', { status: 200 })
+    }
+    const eventDispatcher = Fetch.createEventDispatcher<[typeof method]>()
+    eventDispatcher.on('credential.created', () => {
+      events.push('first')
+      throw new Error('observer failed')
+    })
+    eventDispatcher.on('credential.created', () => {
+      events.push('second')
+    })
+
+    const fetch = Fetch.from({
+      eventDispatcher,
+      fetch: mockFetch,
+      methods: [method],
+    })
+
+    await fetch('https://example.com/api')
+
+    expect(events).toEqual(['first', 'second'])
+  })
+
+  test('emits payment.failed when automatic payment handling rejects', async () => {
+    const events: string[] = []
+    const createCredential = vi.fn(async () => 'credential')
+    const mockFetch = vi.fn(async () =>
+      make402({ expires: new Date(Date.now() - 60_000).toISOString() }),
+    )
+    const method = { ...noopMethod, createCredential }
+    const eventDispatcher = Fetch.createEventDispatcher<[typeof method]>()
+    eventDispatcher.on('*', (event) => {
+      events.push(`*:${event.name}`)
+    })
+    eventDispatcher.on('payment.failed', (payload) => {
+      events.push(
+        `failed:${payload.error instanceof Errors.PaymentExpiredError}:${payload.challenge?.id}`,
+      )
+      throw new Error('observer failed')
+    })
+    const fetch = Fetch.from({
+      eventDispatcher,
+      fetch: mockFetch as typeof globalThis.fetch,
+      methods: [method],
+    })
+
+    await expect(fetch('https://example.com/api')).rejects.toThrow(Errors.PaymentExpiredError)
+    expect(createCredential).not.toHaveBeenCalled()
+    expect(events).toEqual(['failed:true:abc', '*:payment.failed'])
+  })
+
   test('preserves existing headers on retry', async () => {
     let callCount = 0
     const calls: { init: RequestInit | undefined }[] = []