mppx 0.6.19 → 0.6.20

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/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()
+  })
 })