mppx 0.6.19 → 0.6.21

package/src/Method.ts

@@ -130,10 +130,12 @@ export type Server<
   defaults extends ExactPartial<z.input<method['schema']['request']>> = {},
   transportOverride = undefined,
 > = method & {
+  authorize?: AuthorizeFn<method> | undefined
   defaults?: defaults | undefined
   html?: Html.Options | undefined
   request?: RequestFn<method> | undefined
   respond?: RespondFn<method> | undefined
+  stableBinding?: StableBindingFn<method> | undefined
   transport?: transportOverride | undefined
   verify: VerifyFn<method>
 }
@@ -155,6 +157,45 @@ export type RequestFn<method extends Method> = (
   options: RequestContext<method>,
 ) => MaybePromise<z.input<method['schema']['request']>>
 
+/**
+ * Optional authorization hook for a server-side method.
+ *
+ * Called after request normalization but before the 402 challenge path. This lets
+ * a server grant access based on existing application state (for example, an
+ * active subscription) without requiring a fresh `Payment` credential.
+ *
+ * **HTTP-only.** The `input` parameter is a Fetch `Request`; non-HTTP transports
+ * do not invoke this hook.
+ *
+ * Transports that require credential context for `withReceipt()` should return a
+ * `response` from this hook so adapters can short-circuit protected handlers.
+ */
+export type AuthorizeFn<method extends Method> = (parameters: {
+  challenge: Challenge.Challenge<
+    z.output<method['schema']['request']>,
+    method['intent'],
+    method['name']
+  >
+  input: globalThis.Request
+  request: z.output<method['schema']['request']>
+}) => MaybePromise<AuthorizeResult | undefined>
+
+/** Successful result returned from an {@link AuthorizeFn}. */
+export type AuthorizeResult = {
+  receipt: Receipt.Receipt
+  response?: globalThis.Response | undefined
+}
+
+/**
+ * Produces the stable request fields used to bind credentials to a route.
+ *
+ * Methods can override this to opt into additional request fields beyond the
+ * default amount/currency/recipient binding used by generic methods.
+ */
+export type StableBindingFn<method extends Method> = (
+  request: z.output<method['schema']['request']>,
+) => Record<string, unknown>
+
 /** Verification function for a single method. */
 export type VerifyFn<method extends Method> = (
   parameters: VerifyContext<method>,
@@ -251,13 +292,15 @@ export function toServer<
   method: method,
   options: toServer.Options<method, defaults, transportOverride>,
 ): Server<method, defaults, transportOverride> {
-  const { defaults, html, request, respond, transport, verify } = options
+  const { authorize, defaults, html, request, respond, stableBinding, transport, verify } = options
   return {
     ...method,
+    authorize,
     defaults,
     html,
     request,
     respond,
+    stableBinding,
     transport,
     verify,
   } as Server<method, defaults, transportOverride>
@@ -269,10 +312,12 @@ export declare namespace toServer {
     defaults extends RequestDefaults<method> = {},
     transportOverride extends Transport.AnyTransport | undefined = undefined,
   > = {
+    authorize?: AuthorizeFn<method> | undefined
     defaults?: defaults | undefined
     html?: Html.Options | undefined
     request?: RequestFn<method> | undefined
     respond?: RespondFn<method> | undefined
+    stableBinding?: StableBindingFn<method> | undefined
     transport?: transportOverride | undefined
     verify: VerifyFn<method>
   }

package/src/Receipt.ts

@@ -19,6 +19,8 @@ export const Schema = z.object({
   reference: z.string(),
   /** Optional external reference ID echoed from the credential payload. */
   externalId: z.optional(z.string()),
+  /** Optional server-issued subscription identifier for recurring payments. */
+  subscriptionId: z.optional(z.string()),
   /** Payment status. Always "success" — failures use 402 + Problem Details. */
   status: z.literal('success'),
   /** RFC 3339 settlement timestamp. */

package/src/client/Methods.ts

@@ -1,3 +1,4 @@
 export { stripe } from '../stripe/client/index.js'
+export { subscription } from '../tempo/client/Subscription.js'
 export { tempo } from '../tempo/client/index.js'
 export { session } from '../tempo/client/Session.js'

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