mppx 0.6.19 → 0.6.21

package/src/middlewares/hono.ts

@@ -63,11 +63,24 @@ export function payment<const intent extends Mppx_internal.AnyMethodFn>(
         : c.req.raw
     const result = await intent(options)(request)
     if (result.status === 402) return result.challenge
+    const managementResponse = getManagementResponse(result)
+    if (managementResponse) return managementResponse
     await next()
     c.res = result.withReceipt(c.res)
   }
 }
 
+function getManagementResponse(result: { withReceipt: (response?: Response) => Response }) {
+  try {
+    return result.withReceipt()
+  } catch (error) {
+    if (Mppx_core.isMissingReceiptResponseError(error)) {
+      return null
+    }
+    throw error
+  }
+}
+
 export type DiscoveryConfig = Omit<GenerateConfig, 'routes'> & {
   auto?: boolean
   path?: string

package/src/middlewares/internal/mppx.ts

@@ -1,5 +1,6 @@
 import type { DiscoveryHandler } from '../../discovery/OpenApi.js'
 import type * as Method from '../../Method.js'
+import { reservedMppxKeys } from '../../server/Mppx.js'
 import type * as Mppx from '../../server/Mppx.js'
 
 export type AnyMethodFn = Mppx.AnyMethodFn
@@ -17,11 +18,8 @@ type WrapNested<obj, handler> = {
 export type Wrap<mppx, handler> = {
   // `compose` is omitted — it returns a raw HTTP handler, not a
   // middleware-shaped result. Use `Mppx.compose()` static instead.
-  // `methods`, `realm`, `transport` are data properties — not handlers.
-  [key in keyof mppx as key extends 'compose' ? never : key]: key extends
-    | 'methods'
-    | 'realm'
-    | 'transport'
+  // Reserved Mppx keys are copied through unchanged, not wrapped as handlers.
+  [key in keyof mppx as key extends 'compose' ? never : key]: key extends Mppx.ReservedKey
     ? mppx[key]
     : mppx[key] extends (options: infer options) => any
       ? (o: options) => handler & DiscoveryMeta
@@ -54,7 +52,8 @@ export function wrap<mppx extends Mppx.Mppx<any, any>, handler>(
     }
     result[key] = wrapWithMeta
     // Also set shorthand intent key if Mppx registered it (no collision)
-    if ((mppx as any)[mi.intent]) result[mi.intent] = wrapWithMeta
+    if (!reservedMppxKeys.has(mi.intent) && (mppx as any)[mi.intent])
+      result[mi.intent] = wrapWithMeta
     // Build nested handlers: wrapped.tempo.charge(...)
     if (!result[mi.name] || typeof result[mi.name] !== 'object')
       result[mi.name] = {} as Record<string, unknown>

package/src/middlewares/nextjs.test.ts

@@ -2,7 +2,7 @@ import * as http from 'node:http'
 
 import { Challenge, Credential, Receipt } from 'mppx'
 import { Mppx as Mppx_client, session as sessionIntent, tempo as tempo_client } from 'mppx/client'
-import { Mppx, discovery } from 'mppx/nextjs'
+import { Mppx, discovery, payment } from 'mppx/nextjs'
 import { tempo as tempo_server } from 'mppx/server'
 import type { Address } from 'viem'
 import { Addresses } from 'viem/tempo'
@@ -34,6 +34,33 @@ function createServer(handler: (request: Request) => Promise<Response> | Respons
 
 const secretKey = 'test-secret-key'
 
+describe('payment', () => {
+  test('short-circuits management responses', async () => {
+    let handlerRan = false
+    const intent = () => async () => ({
+      status: 200 as const,
+      withReceipt: () =>
+        new Response(null, {
+          headers: { 'Payment-Receipt': 'management-receipt' },
+          status: 204,
+        }),
+    })
+    const handler = payment(intent as any, {} as any, () => {
+      handlerRan = true
+      return Response.json({ data: 'content' })
+    })
+
+    const server = await createServer(handler)
+    const response = await globalThis.fetch(server.url)
+    expect(response.status).toBe(204)
+    expect(response.headers.get('Payment-Receipt')).toBe('management-receipt')
+    expect(await response.text()).toBe('')
+    expect(handlerRan).toBe(false)
+
+    server.close()
+  })
+})
+
 function createChargeHarness(feePayer: boolean) {
   const mppx = Mppx.create({
     methods: [

package/src/middlewares/nextjs.ts

@@ -61,11 +61,24 @@ export function payment<const intent extends Mppx_internal.AnyMethodFn>(
   return async (request) => {
     const result = await intent(options)(request)
     if (result.status === 402) return result.challenge
+    const managementResponse = getManagementResponse(result)
+    if (managementResponse) return managementResponse
     const response = await handler(request)
     return result.withReceipt(response)
   }
 }
 
+function getManagementResponse(result: { withReceipt: (response?: Response) => Response }) {
+  try {
+    return result.withReceipt()
+  } catch (error) {
+    if (Mppx_core.isMissingReceiptResponseError(error)) {
+      return null
+    }
+    throw error
+  }
+}
+
 export type DiscoveryConfig = Omit<GenerateConfig, 'routes'> & {
   routes?: RouteConfig[]
 }

package/src/proxy/Proxy.test.ts

@@ -111,6 +111,75 @@ function createUpstream(handler: (req: Request) => Response | Promise<Response>)
 }
 
 describe('create', () => {
+  test('behavior: paid routes emit mppx server events', async () => {
+    const events: string[] = []
+    upstream = await createUpstream(() => Response.json({ data: 'ok' }))
+
+    const method = Method.from({
+      name: 'mock',
+      intent: 'charge',
+      schema: {
+        credential: { payload: z.object({ token: z.string() }) },
+        request: z.object({ amount: z.string() }),
+      },
+    })
+    const handler = Mppx_server.create({
+      methods: [
+        Method.toServer(method, {
+          async verify() {
+            return Receipt.from({
+              method: 'mock',
+              status: 'success',
+              timestamp: new Date().toISOString(),
+              reference: 'proxy-reference',
+            })
+          },
+        }),
+      ],
+      realm: 'api.example.com',
+      secretKey,
+    })
+    handler.onChallengeCreated((context) => {
+      events.push(`challenge:${context.error?.name}`)
+    })
+    handler.onPaymentSuccess((context) => {
+      events.push(`payment:${context.receipt.reference}`)
+    })
+    handler.onPaymentFailed((context) => {
+      events.push(`failed:${context.error.name}`)
+    })
+    const proxy = ApiProxy.create({
+      services: [
+        Service.from('api', {
+          baseUrl: upstream.url,
+          routes: {
+            'GET /v1/data': handler['mock/charge']({ amount: '1' }),
+          },
+        }),
+      ],
+    })
+    proxyServer = await Http.createServer(proxy.listener)
+
+    const challengeResponse = await fetch(`${proxyServer.url}/api/v1/data`)
+    expect(challengeResponse.status).toBe(402)
+
+    const challenge = Challenge.fromResponse(challengeResponse)
+    const authorization = Credential.serialize(
+      Credential.from({
+        challenge,
+        payload: { token: 'ok' },
+      }),
+    )
+    const paid = await fetch(`${proxyServer.url}/api/v1/data`, {
+      headers: { Authorization: authorization },
+    })
+
+    expect(paid.status).toBe(200)
+    expect(paid.headers.get('Payment-Receipt')).toBeTruthy()
+    expect(await paid.json()).toEqual({ data: 'ok' })
+    expect(events).toEqual(['challenge:PaymentRequiredError', 'payment:proxy-reference'])
+  })
+
   test('behavior: GET /openapi.json returns discovery JSON', async () => {
     const proxy = ApiProxy.create({
       categories: ['gateway'],

package/src/proxy/Proxy.ts

@@ -3,6 +3,7 @@ import type * as http from 'node:http'
 import * as Credential from '../Credential.js'
 import { generateProxy } from '../discovery/OpenApi.js'
 import * as Scope from '../server/internal/scope.js'
+import * as Mppx from '../server/Mppx.js'
 import * as Request from '../server/Request.js'
 import * as Headers from './internal/Headers.js'
 import * as Route from './internal/Route.js'
@@ -146,11 +147,7 @@ export function create(config: create.Config): Proxy {
       try {
         return (result.withReceipt as () => Response)()
       } catch (error) {
-        if (
-          error instanceof Error &&
-          error.message === 'withReceipt() requires a response argument'
-        )
-          return null
+        if (Mppx.isMissingReceiptResponseError(error)) return null
         throw error
       }
     })()

package/src/proxy/Service.test.ts

@@ -122,6 +122,40 @@ describe('paymentOf', () => {
     })
     expect(Service.paymentOf({ pay: handler, options: {} })).toBeNull()
   })
+
+  test('behavior: strips function internals from payment metadata', () => {
+    const handler = Object.assign(
+      async () => ({
+        status: 200 as const,
+        withReceipt: <T>(r: T) => r,
+      }),
+      {
+        _internal: {
+          _canonicalRequest: () => ({}),
+          _stableBinding: () => ({}),
+          amount: '1',
+          authorize: () => undefined,
+          decimals: 6,
+          defaults: {},
+          intent: 'charge',
+          name: 'mock',
+          request: () => ({}),
+          respond: () => undefined,
+          schema: {},
+          stableBinding: () => ({}),
+          transport: {},
+          verify: () => undefined,
+        },
+      },
+    )
+
+    expect(Service.paymentOf(handler as never)).toEqual({
+      amount: '1000000',
+      decimals: 6,
+      intent: 'charge',
+      method: 'mock',
+    })
+  })
 })
 
 describe('getOptions', () => {

package/src/proxy/Service.ts

@@ -216,6 +216,13 @@ export function paymentOf(endpoint: Endpoint): Record<string, unknown> | null {
     defaults: _,
     schema: _s,
     _canonicalRequest,
+    _stableBinding: _sb,
+    authorize: _a,
+    request: _r,
+    respond: _re,
+    stableBinding: _st,
+    transport: _t,
+    verify: _v,
     ...rest
   } = handler._internal as Record<string, unknown>
   const amount = (() => {

package/src/server/Mppx.authorize.test.ts

@@ -0,0 +1,210 @@
+import { Challenge, Credential, Method, z } from 'mppx'
+import { Mppx } from 'mppx/server'
+import { describe, expect, test } from 'vp/test'
+import * as Http from '~test/Http.js'
+
+const realm = 'api.example.com'
+const secretKey = 'test-secret-key'
+
+function successReceipt(method = 'mock') {
+  return {
+    method,
+    reference: 'ref-1',
+    status: 'success',
+    timestamp: '2025-01-01T00:00:00.000Z',
+  } as const
+}
+
+describe('authorize hook', () => {
+  test('grants access without a Payment credential', async () => {
+    const method = Method.toServer(
+      Method.from({
+        name: 'mock',
+        intent: 'subscription',
+        schema: {
+          credential: { payload: z.object({ token: z.string() }) },
+          request: z.object({ amount: z.string() }),
+        },
+      }),
+      {
+        async authorize() {
+          return { receipt: successReceipt() }
+        },
+        async verify() {
+          return successReceipt()
+        },
+      },
+    )
+
+    const handler = Mppx.create({ methods: [method], realm, secretKey })
+    const result = await handler['mock/subscription']({ amount: '1' })(
+      new Request('https://example.com/resource'),
+    )
+
+    expect(result.status).toBe(200)
+    if (result.status !== 200) throw new Error('expected authorize success')
+
+    const response = result.withReceipt(new Response('OK'))
+    expect(response.headers.get('Payment-Receipt')).toBeTruthy()
+  })
+
+  test('toNodeListener forwards authorize management responses', async () => {
+    const method = Method.toServer(
+      Method.from({
+        name: 'mock',
+        intent: 'subscription',
+        schema: {
+          credential: { payload: z.object({ token: z.string() }) },
+          request: z.object({ amount: z.string() }),
+        },
+      }),
+      {
+        async authorize() {
+          return {
+            receipt: successReceipt(),
+            response: new Response('retry later', {
+              headers: { 'Retry-After': '1' },
+              status: 409,
+            }),
+          }
+        },
+        async verify() {
+          return successReceipt()
+        },
+      },
+    )
+
+    const handler = Mppx.create({ methods: [method], realm, secretKey })
+    const server = await Http.createServer(async (req, res) => {
+      const result = await Mppx.toNodeListener(handler['mock/subscription']({ amount: '1' }))(
+        req,
+        res,
+      )
+      if (result.status === 402) return
+      res.end('OK')
+    })
+
+    const response = await fetch(server.url)
+    expect(response.status).toBe(409)
+    expect(response.headers.get('Retry-After')).toBe('1')
+    expect(response.headers.get('Payment-Receipt')).toBeTruthy()
+    expect(await response.text()).toBe('retry later')
+
+    server.close()
+  })
+
+  test('compose evaluates authorize hooks sequentially on no-credential requests', async () => {
+    const calls: string[] = []
+    const createMethod = (
+      name: 'alpha' | 'beta',
+      authorizeResult?: ReturnType<typeof successReceipt>,
+    ) =>
+      Method.toServer(
+        Method.from({
+          name,
+          intent: 'charge',
+          schema: {
+            credential: { payload: z.object({ token: z.string() }) },
+            request: z.object({ amount: z.string() }),
+          },
+        }),
+        {
+          async authorize() {
+            calls.push(`${name}:start`)
+            await new Promise((resolve) => setTimeout(resolve, 0))
+            calls.push(`${name}:end`)
+            return authorizeResult ? { receipt: authorizeResult } : undefined
+          },
+          async verify() {
+            return successReceipt(name)
+          },
+        },
+      )
+
+    const alpha = createMethod('alpha')
+    const beta = createMethod('beta', successReceipt('beta'))
+    const handler = Mppx.create({ methods: [alpha, beta], realm, secretKey })
+
+    const result = await handler.compose(
+      [alpha, { amount: '1' }],
+      [beta, { amount: '1' }],
+    )(new Request('https://example.com/resource'))
+
+    expect(result.status).toBe(200)
+    expect(calls).toEqual(['alpha:start', 'alpha:end', 'beta:start', 'beta:end'])
+  })
+
+  test('stableBinding can reject mismatched subscription routes', async () => {
+    const method = Method.toServer(
+      Method.from({
+        name: 'mock',
+        intent: 'subscription',
+        schema: {
+          credential: { payload: z.object({ token: z.string() }) },
+          request: z.object({
+            amount: z.string(),
+            chainId: z.optional(z.number()),
+            currency: z.string(),
+            periodCount: z.string(),
+            periodUnit: z.enum(['day', 'week']),
+            recipient: z.string(),
+            subscriptionExpires: z.string(),
+          }),
+        },
+      }),
+      {
+        stableBinding(request) {
+          return {
+            amount: request.amount,
+            chainId: request.chainId,
+            currency: request.currency,
+            periodCount: request.periodCount,
+            periodUnit: request.periodUnit,
+            recipient: request.recipient,
+            subscriptionExpires: request.subscriptionExpires,
+          }
+        },
+        async verify() {
+          return successReceipt()
+        },
+      },
+    )
+
+    const handler = Mppx.create({ methods: [method], realm, secretKey })
+    const first = await handler['mock/subscription']({
+      amount: '1',
+      currency: 'usd',
+      periodCount: '30',
+      periodUnit: 'day',
+      recipient: 'alice',
+      subscriptionExpires: '2026-01-01T00:00:00Z',
+    })(new Request('https://example.com/cheap'))
+
+    expect(first.status).toBe(402)
+    if (first.status !== 402) throw new Error('expected challenge')
+
+    const credential = Credential.from({
+      challenge: Challenge.fromResponse(first.challenge),
+      payload: { token: 'ok' },
+    })
+
+    const second = await handler['mock/subscription']({
+      amount: '1',
+      currency: 'usd',
+      periodCount: '60',
+      periodUnit: 'day',
+      recipient: 'alice',
+      subscriptionExpires: '2026-01-01T00:00:00Z',
+    })(
+      new Request('https://example.com/expensive', {
+        headers: { Authorization: Credential.serialize(credential) },
+      }),
+    )
+
+    expect(second.status).toBe(402)
+    if (second.status !== 402) throw new Error('expected mismatch challenge')
+
+    const body = (await second.challenge.json()) as { detail: string }
+    expect(body.detail).toContain('periodCount')
+  })
+})

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

@@ -1,5 +1,5 @@
 import { Method, z } from 'mppx'
-import { Mppx } from 'mppx/server'
+import { Mppx, tempo } from 'mppx/server'
 import { assertType, describe, expectTypeOf, test } from 'vp/test'
 
 const mockChargeA = Method.from({
@@ -151,6 +151,7 @@ describe('Mppx type tests', () => {
       amount: '100',
       currency: '0x01',
       decimals: 6,
+      expires: new Date('2026-01-01T00:00:00Z'),
       recipient: '0x02',
     })
 
@@ -170,6 +171,56 @@ describe('Mppx type tests', () => {
     expectTypeOf(mppx.verifyCredential).toBeFunction()
   })
 
+  test('server events receive typed method context', () => {
+    const mppx = Mppx.create({
+      methods: [alphaMethod],
+      realm,
+      secretKey,
+    })
+
+    mppx.on('payment.success', (context) => {
+      expectTypeOf(context.challenge.method).toEqualTypeOf<'alpha'>()
+      expectTypeOf(context.credential?.payload.token).toEqualTypeOf<string | undefined>()
+    })
+    mppx.on('challenge.created', (context) => {
+      expectTypeOf(context.method.name).toEqualTypeOf<'alpha'>()
+      expectTypeOf(context.error).toMatchTypeOf<Error | undefined>()
+    })
+    mppx.on('payment.failed', (context) => {
+      expectTypeOf(context.error).toMatchTypeOf<Error>()
+      expectTypeOf(context.credential).toMatchTypeOf<unknown>()
+    })
+    mppx.on('*', (event) => {
+      expectTypeOf(event.name).toMatchTypeOf<
+        'challenge.created' | 'payment.failed' | 'payment.success'
+      >()
+      if (event.name === 'payment.failed') expectTypeOf(event.payload.error).toMatchTypeOf<Error>()
+      if (event.name === 'challenge.created')
+        expectTypeOf(event.payload.error).toMatchTypeOf<Error | undefined>()
+      if (event.name === 'payment.success')
+        expectTypeOf(event.payload.receipt.status).toEqualTypeOf<'success'>()
+    })
+    mppx.onChallengeCreated((context) => {
+      expectTypeOf(context.input).toEqualTypeOf<Request | undefined>()
+      expectTypeOf(context.method.name).toEqualTypeOf<'alpha'>()
+      expectTypeOf(context.request.amount).toEqualTypeOf<string>()
+      expectTypeOf(context.error).toMatchTypeOf<Error | undefined>()
+    })
+    mppx.onPaymentSuccess((context) => {
+      expectTypeOf(context.challenge.method).toEqualTypeOf<'alpha'>()
+      expectTypeOf(context.credential?.payload.token).toEqualTypeOf<string | undefined>()
+      expectTypeOf(context.envelope?.challenge.intent).toEqualTypeOf<'charge' | undefined>()
+      expectTypeOf(context.receipt.status).toEqualTypeOf<'success'>()
+      expectTypeOf(context.request.recipient).toEqualTypeOf<string>()
+    })
+    mppx.onPaymentFailed((context) => {
+      expectTypeOf(context.credential).toMatchTypeOf<unknown>()
+      expectTypeOf(context.error).toMatchTypeOf<Error>()
+      expectTypeOf(context.method.intent).toEqualTypeOf<'charge'>()
+      expectTypeOf(context.request.currency).toEqualTypeOf<string>()
+    })
+  })
+
   test('handler options and verifyCredential accept scope', () => {
     const mppx = Mppx.create({ methods: [alphaMethod], realm, secretKey })
 
@@ -187,4 +238,25 @@ describe('Mppx type tests', () => {
       Promise<unknown>
     >()
   })
+
+  test('tempo subscription accepts ergonomic date and period inputs', () => {
+    const method = tempo.subscription({
+      amount: '10',
+      currency: '0x20c0000000000000000000000000000000000001',
+      periodCount: 1,
+      periodUnit: 'day',
+      recipient: '0x1234567890abcdef1234567890abcdef12345678',
+      resolve: async () => ({ key: 'user-1:plan:pro' }),
+      subscriptionExpires: new Date('2026-01-01T00:00:00Z'),
+    })
+    const mppx = Mppx.create({ methods: [method], realm, secretKey })
+
+    expectTypeOf(
+      mppx.tempo.subscription({
+        expires: new Date('2026-01-01T00:00:00Z'),
+        periodCount: 1n,
+        subscriptionExpires: new Date('2026-01-01T00:00:00Z'),
+      }),
+    ).toBeFunction()
+  })
 })