mppx 0.6.18 → 0.6.20

package/src/middlewares/elysia.test.ts

@@ -3,7 +3,7 @@ import * as http from 'node:http'
 import { Elysia } from 'elysia'
 import { Receipt } from 'mppx'
 import { Mppx as Mppx_client, session as sessionIntent, tempo as tempo_client } from 'mppx/client'
-import { Mppx, discovery } from 'mppx/elysia'
+import { Mppx, discovery, payment } from 'mppx/elysia'
 import { tempo as tempo_server } from 'mppx/server'
 import type { Address } from 'viem'
 import { Addresses } from 'viem/tempo'
@@ -35,6 +35,36 @@ function createServer(app: Elysia<any, any, any, any, any, any, any>) {
 
 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 app = new Elysia().guard({ beforeHandle: payment(intent as any, {} as any) }, (app) =>
+      app.get('/', () => {
+        handlerRan = true
+        return { data: 'content' }
+      }),
+    )
+
+    const server = await createServer(app)
+    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/elysia.ts

@@ -64,12 +64,25 @@ export function payment<const intent extends Mppx_internal.AnyMethodFn>(
   return async ({ request, set }) => {
     const result = await intent(options)(request)
     if (result.status === 402) return result.challenge
+    const managementResponse = getManagementResponse(result)
+    if (managementResponse) return managementResponse
     const receipt = result.withReceipt(new Response())
     const header = receipt.headers.get('Payment-Receipt')
     if (header) set.headers['Payment-Receipt'] = header
   }
 }
 
+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'> & {
   path?: string
   routes?: RouteConfig[]

package/src/middlewares/express.ts

@@ -80,11 +80,7 @@ export function payment<const intent extends Mppx_internal.AnyMethodFn>(
       try {
         return (result.withReceipt as () => Response)()
       } catch (error) {
-        if (
-          error instanceof Error &&
-          error.message === 'withReceipt() requires a response argument'
-        )
-          return null
+        if (Mppx_core.isMissingReceiptResponseError(error)) return null
         throw error
       }
     })()

package/src/middlewares/hono.test.ts

@@ -2,7 +2,7 @@ import { serve } from '@hono/node-server'
 import { Hono } from 'hono'
 import { Challenge, Credential, Method, Receipt, z } from 'mppx'
 import { Mppx as Mppx_client, session as sessionIntent, tempo as tempo_client } from 'mppx/client'
-import { Mppx, discovery } from 'mppx/hono'
+import { Mppx, discovery, payment } from 'mppx/hono'
 import { tempo as tempo_server } from 'mppx/server'
 import type { Address } from 'viem'
 import { Addresses } from 'viem/tempo'
@@ -26,6 +26,35 @@ function createServer(app: Hono) {
 
 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 app = new Hono()
+    app.get('/', payment(intent as any, {} as any), (c) => {
+      handlerRan = true
+      return c.json({ data: 'content' })
+    })
+
+    const server = await createServer(app)
+    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()
+  })
+})
+
 const scopeMethod = Method.toServer(
   Method.from({
     name: 'mock',

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/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.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',
     })
 
@@ -187,4 +188,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()
+  })
 })

package/src/server/Mppx.test.ts

@@ -1,6 +1,6 @@
 import * as http from 'node:http'
 
-import { Challenge, Credential, Method, z } from 'mppx'
+import { Challenge, Credential, Errors, Method, z } from 'mppx'
 import {
   Mppx as Mppx_client,
   session as tempo_session_client,
@@ -972,7 +972,7 @@ describe('compose', () => {
     amount: '1000',
     currency: '0x0000000000000000000000000000000000000001',
     decimals: 6,
-    expires: new Date(Date.now() + 60_000).toISOString(),
+    expires: new Date(Date.now() + 60_000),
     recipient: '0x0000000000000000000000000000000000000002',
   }
 
@@ -1779,6 +1779,37 @@ describe('compose: pre-dispatch narrowing edge cases', () => {
     expect(result.status).toBe(402)
   })
 
+  test('ignores compose candidates whose stable binding throws on forged credentials', async () => {
+    const bindingMethod = Method.toServer(mockCharge, {
+      stableBinding(request) {
+        return { currency: request.currency.toLowerCase() }
+      },
+      async verify() {
+        return mockReceipt()
+      },
+    })
+    const mppx = Mppx.create({ methods: [bindingMethod], realm, secretKey })
+    const handle = mppx.compose([bindingMethod, challengeOpts])
+    const credential = Credential.from({
+      challenge: {
+        id: 'forged',
+        intent: 'charge',
+        method: 'alpha',
+        realm,
+        request: {},
+      },
+      payload: { token: 'valid' },
+    })
+
+    const result = await handle(
+      new Request('https://example.com/resource', {
+        headers: { Authorization: Credential.serialize(credential) },
+      }),
+    )
+
+    expect(result.status).toBe(402)
+  })
+
   test('single handler in compose() returns 402 and then 200', async () => {
     const mppx = Mppx.create({ methods: [alphaMethod], realm, secretKey })
     const handle = mppx.compose([alphaMethod, challengeOpts])
@@ -2605,7 +2636,15 @@ describe('withReceipt', () => {
     expect(result.status).toBe(200)
     if (result.status !== 200) throw new Error()
 
-    expect(() => result.withReceipt()).toThrow('withReceipt() requires a response argument')
+    expect(() => result.withReceipt()).toThrow(Mppx.MissingReceiptResponseError)
+  })
+
+  test('recognizes missing response sentinel across module instances', () => {
+    const error = new Error('withReceipt() requires a response argument')
+    error.name = 'MissingReceiptResponseError'
+
+    expect(Mppx.isMissingReceiptResponseError(error)).toBe(true)
+    expect(Mppx.isMissingReceiptResponseError(new Error(error.message))).toBe(false)
   })
 
   test('returns management response when respond hook returns Response', async () => {
@@ -3252,6 +3291,37 @@ describe('challenge', () => {
     expect(challenge.request.methodDetails).toEqual({ chainId: 42431 })
   })
 
+  test('request hook payment errors are normalized to 402 responses', async () => {
+    const errorMethod = Method.toServer(
+      Method.from({
+        name: 'error',
+        intent: 'charge',
+        schema: {
+          credential: { payload: z.object({ token: z.string() }) },
+          request: z.object({ amount: z.string() }),
+        },
+      }),
+      {
+        request() {
+          throw new Errors.VerificationFailedError({ reason: 'request rejected' })
+        },
+        async verify() {
+          return mockReceipt('error')
+        },
+      },
+    )
+    const mppx = Mppx.create({ methods: [errorMethod], realm, secretKey })
+
+    const result = await mppx.error.charge({ amount: '1' })(
+      new Request('https://example.com/resource'),
+    )
+
+    expect(result.status).toBe(402)
+    if (result.status !== 402) throw new Error('expected challenge')
+    const body = (await result.challenge.json()) as { detail?: string }
+    expect(body.detail).toBe('Payment verification failed: request rejected.')
+  })
+
   test('challenge produced by mppx.challenge is accepted by the 402 handler', async () => {
     const mppx = Mppx.create({
       methods: [alphaChargeServer],