mppx 0.4.9 → 0.4.11

package/src/middlewares/express.test.ts

@@ -1,11 +1,11 @@
 import express from 'express'
 import { Receipt } from 'mppx'
 import { Mppx as Mppx_client, session as sessionIntent, tempo as tempo_client } from 'mppx/client'
-import { Mppx, payment } from 'mppx/express'
+import { Mppx, discovery, payment } from 'mppx/express'
 import { Mppx as Mppx_server, tempo as tempo_server } from 'mppx/server'
 import type { Address } from 'viem'
 import { Addresses } from 'viem/tempo'
-import { beforeAll, describe, expect, test } from 'vitest'
+import { beforeAll, describe, expect, test } from 'vp/test'
 import { deployEscrow } from '~test/tempo/session.js'
 import { accounts, asset, client, fundAccount } from '~test/tempo/viem.js'
 
@@ -29,7 +29,7 @@ describe('charge', () => {
       tempo_server({
         getClient: () => client,
         currency: asset,
-        recipient: accounts[0].address,
+        account: accounts[0],
       }),
     ],
     secretKey,
@@ -81,6 +81,34 @@ describe('charge', () => {
 
     server.close()
   })
+
+  test('serves /openapi.json from a handler-derived route config', async () => {
+    const app = express()
+    const pay = mppx.charge({ amount: '1' })
+    app.get('/', pay, (_req, res) => {
+      res.json({ fortune: 'You will be rich' })
+    })
+    discovery(app, mppx, {
+      info: { title: 'Express API', version: '1.2.3' },
+      routes: [{ handler: pay, method: 'get', path: '/' }],
+    })
+
+    const server = await createServer(app)
+    const response = await globalThis.fetch(`${server.url}/openapi.json`)
+    expect(response.status).toBe(200)
+    expect(response.headers.get('cache-control')).toBe('public, max-age=300')
+
+    const body = (await response.json()) as Record<string, any>
+    expect(body.info).toEqual({ title: 'Express API', version: '1.2.3' })
+    expect(body.paths['/'].get['x-payment-info']).toMatchObject({
+      amount: '1000000',
+      currency: asset,
+      intent: 'charge',
+      method: 'tempo',
+    })
+
+    server.close()
+  })
 })
 
 describe('session', () => {
@@ -97,7 +125,7 @@ describe('session', () => {
       methods: [
         tempo_server.session({
           getClient: () => client,
-          recipient: accounts[0].address,
+          account: accounts[0],
           currency: asset,
           escrowContract,
         }),
@@ -123,10 +151,10 @@ describe('session', () => {
       methods: [
         tempo_server.session({
           getClient: () => client,
-          recipient: accounts[0].address,
+          account: accounts[0],
           currency: asset,
           escrowContract,
-          feePayer: accounts[0],
+          feePayer: true,
         }),
       ],
       secretKey,
@@ -165,7 +193,7 @@ describe('payment', () => {
       tempo_server({
         getClient: () => client,
         currency: asset,
-        recipient: accounts[0].address,
+        account: accounts[0],
       }),
     ],
     secretKey,

package/src/middlewares/express.ts

@@ -1,10 +1,12 @@
 import type {
+  Express,
   Request as ExpressRequest,
   Response as ExpressResponse,
   NextFunction,
   RequestHandler,
 } from 'express'
 
+import { generate, type GenerateConfig, type RouteConfig } from '../discovery/OpenApi.js'
 import * as Mppx_core from '../server/Mppx.js'
 import * as Mppx_internal from './internal/mppx.js'
 
@@ -84,3 +86,35 @@ export function payment<const intent extends Mppx_internal.AnyMethodFn>(
     next()
   }
 }
+
+export type DiscoveryConfig = Omit<GenerateConfig, 'routes'> & {
+  path?: string
+  routes?: RouteConfig[]
+}
+
+const discoveryHeaders = { 'Cache-Control': 'public, max-age=300' }
+
+/**
+ * Mounts a `GET /openapi.json` route that serves an OpenAPI discovery document.
+ */
+export function discovery(
+  app: Express,
+  mppx: { methods: readonly Mppx_internal.AnyServer[]; realm: string },
+  config: DiscoveryConfig = {},
+): void {
+  const mountPath = config.path ?? '/openapi.json'
+
+  const cached = JSON.stringify(
+    generate(mppx, {
+      ...(config.info ? { info: config.info } : {}),
+      routes: config.routes ?? [],
+      ...(config.serviceInfo ? { serviceInfo: config.serviceInfo } : {}),
+    }),
+  )
+
+  app.get(mountPath, (_req: ExpressRequest, res: ExpressResponse) => {
+    res.setHeader('Cache-Control', discoveryHeaders['Cache-Control'])
+    res.setHeader('Content-Type', 'application/json')
+    res.end(cached)
+  })
+}

package/src/middlewares/hono.test.ts

@@ -2,11 +2,11 @@ import { serve } from '@hono/node-server'
 import { Hono } from 'hono'
 import { Receipt } from 'mppx'
 import { Mppx as Mppx_client, session as sessionIntent, tempo as tempo_client } from 'mppx/client'
-import { Mppx } from 'mppx/hono'
+import { Mppx, discovery } from 'mppx/hono'
 import { tempo as tempo_server } from 'mppx/server'
 import type { Address } from 'viem'
 import { Addresses } from 'viem/tempo'
-import { beforeAll, describe, expect, test } from 'vitest'
+import { beforeAll, describe, expect, test } from 'vp/test'
 import { deployEscrow } from '~test/tempo/session.js'
 import { accounts, asset, client, fundAccount } from '~test/tempo/viem.js'
 
@@ -29,7 +29,7 @@ describe('charge', () => {
       tempo_server.charge({
         getClient: () => client,
         currency: asset,
-        recipient: accounts[0].address,
+        account: accounts[0],
       }),
     ],
     secretKey,
@@ -74,6 +74,28 @@ describe('charge', () => {
 
     server.close()
   })
+
+  test('serves /openapi.json via auto discovery', async () => {
+    const app = new Hono()
+    app.get('/', mppx.charge({ amount: '1' }), (c) => c.json({ fortune: 'You will be rich' }))
+    discovery(app, mppx, { auto: true, info: { title: 'Auto API', version: '2.0.0' } })
+
+    const server = await createServer(app)
+    const response = await globalThis.fetch(`${server.url}/openapi.json`)
+    expect(response.status).toBe(200)
+    expect(response.headers.get('cache-control')).toBe('public, max-age=300')
+
+    const body = (await response.json()) as Record<string, any>
+    expect(body.info).toEqual({ title: 'Auto API', version: '2.0.0' })
+    expect(body.paths['/'].get['x-payment-info']).toMatchObject({
+      amount: '1000000',
+      currency: asset,
+      intent: 'charge',
+      method: 'tempo',
+    })
+
+    server.close()
+  })
 })
 
 describe('session', () => {
@@ -90,7 +112,7 @@ describe('session', () => {
       methods: [
         tempo_server.session({
           getClient: () => client,
-          recipient: accounts[0].address,
+          account: accounts[0],
           currency: asset,
           escrowContract,
         }),
@@ -116,10 +138,10 @@ describe('session', () => {
       methods: [
         tempo_server.session({
           getClient: () => client,
-          recipient: accounts[0].address,
+          account: accounts[0],
           currency: asset,
           escrowContract,
-          feePayer: accounts[0],
+          feePayer: true,
         }),
       ],
       secretKey,

package/src/middlewares/hono.ts

@@ -1,5 +1,6 @@
-import type { MiddlewareHandler } from 'hono'
+import type { Hono, MiddlewareHandler } from 'hono'
 
+import { generate, type GenerateConfig, type RouteConfig } from '../discovery/OpenApi.js'
 import * as Mppx_core from '../server/Mppx.js'
 import * as Mppx_internal from './internal/mppx.js'
 
@@ -61,3 +62,74 @@ export function payment<const intent extends Mppx_internal.AnyMethodFn>(
     c.res = result.withReceipt(c.res)
   }
 }
+
+export type DiscoveryConfig = Omit<GenerateConfig, 'routes'> & {
+  auto?: boolean
+  path?: string
+  routes?: RouteConfig[]
+}
+
+const discoveryHeaders = { 'Cache-Control': 'public, max-age=300' }
+
+/**
+ * Mounts a `GET /openapi.json` route that serves an OpenAPI discovery document.
+ *
+ * When `auto` is true, routes are introspected from Hono's internal `app.routes`
+ * array. This is a **best-effort / experimental** convenience — `app.routes` is
+ * not part of Hono's stable public API and may change across versions. Prefer
+ * passing explicit `routes` for production use.
+ */
+export function discovery(
+  app: Hono<any>,
+  mppx: { methods: readonly Mppx_internal.AnyServer[]; realm: string },
+  config: DiscoveryConfig = {},
+): void {
+  const mountPath = config.path ?? '/openapi.json'
+
+  let cached: string | undefined
+
+  app.get(mountPath, (c) => {
+    if (!cached) {
+      const routes = config.routes ?? (config.auto ? introspectRoutes(app) : [])
+      const doc = generate(mppx, {
+        ...(config.info ? { info: config.info } : {}),
+        routes,
+        ...(config.serviceInfo ? { serviceInfo: config.serviceInfo } : {}),
+      })
+      cached = JSON.stringify(doc)
+    }
+
+    c.header('Cache-Control', discoveryHeaders['Cache-Control'])
+    c.header('Content-Type', 'application/json')
+    return c.body(cached)
+  })
+}
+
+function introspectRoutes(app: Hono<any>): RouteConfig[] {
+  const routes: RouteConfig[] = []
+  const appRoutes = (app as any).routes as
+    | { handler: any; method: string; path: string }[]
+    | undefined
+
+  if (!appRoutes) return routes
+
+  const seen = new Set<string>()
+
+  for (const route of appRoutes) {
+    const internal = (route.handler as { _internal?: Record<string, unknown> } | undefined)
+      ?._internal
+    if (!internal) continue
+
+    const key = `${route.method}:${route.path}:${internal.name}/${internal.intent}`
+    if (seen.has(key)) continue
+    seen.add(key)
+
+    routes.push({
+      handler: route.handler,
+      method: route.method,
+      path: route.path,
+    })
+  }
+
+  return routes
+}

package/src/middlewares/internal/mppx.test.ts

@@ -1,6 +1,6 @@
 import { Challenge, Credential, Method, z } from 'mppx'
 import { Mppx } from 'mppx/server'
-import { describe, expect, test } from 'vitest'
+import { describe, expect, test } from 'vp/test'
 
 import { wrap } from './mppx.js'
 

package/src/middlewares/internal/mppx.ts

@@ -1,13 +1,16 @@
+import type { DiscoveryHandler } from '../../discovery/OpenApi.js'
 import type * as Method from '../../Method.js'
 import type * as Mppx from '../../server/Mppx.js'
 
 export type AnyMethodFn = Mppx.AnyMethodFn
 export type AnyServer = Method.AnyServer
 
+type DiscoveryMeta = Pick<DiscoveryHandler, '_internal'>
+
 /** Recursively wraps nested handler objects one level deep. */
 type WrapNested<obj, handler> = {
   [key in keyof obj]: obj[key] extends (options: infer options) => any
-    ? (o: options) => handler
+    ? (o: options) => handler & DiscoveryMeta
     : obj[key]
 }
 
@@ -21,7 +24,7 @@ export type Wrap<mppx, handler> = {
     | 'transport'
     ? mppx[key]
     : mppx[key] extends (options: infer options) => any
-      ? (o: options) => handler
+      ? (o: options) => handler & DiscoveryMeta
       : mppx[key] extends Record<string, (options: any) => any>
         ? WrapNested<mppx[key], handler>
         : mppx[key]
@@ -43,14 +46,19 @@ export function wrap<mppx extends Mppx.Mppx<any, any>, handler>(
   for (const mi of mppx.methods as readonly Method.AnyServer[]) {
     const key = `${mi.name}/${mi.intent}`
     const methodFn = (mppx as any)[key]
-    result[key] = (options: any) => wrapper(methodFn, options)
+    const wrapWithMeta = (options: any) => {
+      const configured = methodFn(options)
+      const handler = wrapper(methodFn, options) as any
+      if (configured._internal) handler._internal = configured._internal
+      return handler
+    }
+    result[key] = wrapWithMeta
     // Also set shorthand intent key if Mppx registered it (no collision)
-    if ((mppx as any)[mi.intent]) result[mi.intent] = (options: any) => wrapper(methodFn, options)
+    if ((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>
-    ;(result[mi.name] as Record<string, unknown>)[mi.intent] = (options: any) =>
-      wrapper(methodFn, options)
+    ;(result[mi.name] as Record<string, unknown>)[mi.intent] = wrapWithMeta
   }
   return result as never
 }

package/src/middlewares/nextjs.test.ts

@@ -2,11 +2,11 @@ import * as http from 'node:http'
 
 import { Receipt } from 'mppx'
 import { Mppx as Mppx_client, session as sessionIntent, tempo as tempo_client } from 'mppx/client'
-import { Mppx } from 'mppx/nextjs'
+import { Mppx, discovery } from 'mppx/nextjs'
 import { tempo as tempo_server } from 'mppx/server'
 import type { Address } from 'viem'
 import { Addresses } from 'viem/tempo'
-import { beforeAll, describe, expect, test } from 'vitest'
+import { beforeAll, describe, expect, test } from 'vp/test'
 import { deployEscrow } from '~test/tempo/session.js'
 import { accounts, asset, client, fundAccount } from '~test/tempo/viem.js'
 
@@ -42,7 +42,7 @@ describe('charge', () => {
       tempo_server.charge({
         getClient: () => client,
         currency: asset,
-        recipient: accounts[0].address,
+        account: accounts[0],
       }),
     ],
     secretKey,
@@ -89,6 +89,31 @@ describe('charge', () => {
 
     server.close()
   })
+
+  test('serves /openapi.json from a handler-derived route config', async () => {
+    const pay = mppx.charge({ amount: '1' })
+    const server = await createServer(
+      discovery(mppx, {
+        info: { title: 'Next API', version: '3.0.0' },
+        routes: [{ handler: pay, method: 'get', path: '/' }],
+      }),
+    )
+
+    const response = await globalThis.fetch(server.url)
+    expect(response.status).toBe(200)
+    expect(response.headers.get('cache-control')).toBe('public, max-age=300')
+
+    const body = (await response.json()) as Record<string, any>
+    expect(body.info).toEqual({ title: 'Next API', version: '3.0.0' })
+    expect(body.paths['/'].get['x-payment-info']).toMatchObject({
+      amount: '1000000',
+      currency: asset,
+      intent: 'charge',
+      method: 'tempo',
+    })
+
+    server.close()
+  })
 })
 
 describe('session', () => {
@@ -105,7 +130,7 @@ describe('session', () => {
       methods: [
         tempo_server.session({
           getClient: () => client,
-          recipient: accounts[0].address,
+          account: accounts[0],
           currency: asset,
           escrowContract,
         }),
@@ -130,10 +155,10 @@ describe('session', () => {
       methods: [
         tempo_server.session({
           getClient: () => client,
-          recipient: accounts[0].address,
+          account: accounts[0],
           currency: asset,
           escrowContract,
-          feePayer: accounts[0],
+          feePayer: true,
         }),
       ],
       secretKey,

package/src/middlewares/nextjs.ts

@@ -1,3 +1,4 @@
+import { generate, type GenerateConfig, type RouteConfig } from '../discovery/OpenApi.js'
 import * as Mppx_core from '../server/Mppx.js'
 import * as Mppx_internal from './internal/mppx.js'
 
@@ -64,3 +65,30 @@ export function payment<const intent extends Mppx_internal.AnyMethodFn>(
     return result.withReceipt(response)
   }
 }
+
+export type DiscoveryConfig = Omit<GenerateConfig, 'routes'> & {
+  routes?: RouteConfig[]
+}
+
+const discoveryHeaders = { 'Cache-Control': 'public, max-age=300' }
+
+/**
+ * Creates a route handler that serves an OpenAPI discovery document.
+ */
+export function discovery(
+  mppx: { methods: readonly Mppx_internal.AnyServer[]; realm: string },
+  config: DiscoveryConfig = {},
+): RouteHandler {
+  const cached = JSON.stringify(
+    generate(mppx, {
+      ...(config.info ? { info: config.info } : {}),
+      routes: config.routes ?? [],
+      ...(config.serviceInfo ? { serviceInfo: config.serviceInfo } : {}),
+    }),
+  )
+
+  return () =>
+    new Response(cached, {
+      headers: { ...discoveryHeaders, 'Content-Type': 'application/json' },
+    })
+}