mppx 0.4.9 → 0.4.10

package/src/discovery/Validate.test.ts

@@ -0,0 +1,188 @@
+import { validate } from './Validate.js'
+
+function makeDoc(overrides: Record<string, unknown> = {}) {
+  return {
+    info: { title: 'Test', version: '1.0.0' },
+    openapi: '3.1.0',
+    paths: {
+      '/search': {
+        post: {
+          'x-payment-info': {
+            amount: '100',
+            intent: 'charge',
+            method: 'tempo',
+          },
+          requestBody: {
+            content: { 'application/json': { schema: { type: 'object' } } },
+          },
+          responses: {
+            '200': { description: 'OK' },
+            '402': { description: 'Payment Required' },
+          },
+        },
+      },
+    },
+    ...overrides,
+  }
+}
+
+describe('validate', () => {
+  test('returns no errors for a valid document', () => {
+    const errors = validate(makeDoc())
+    expect(errors.filter((error) => error.severity === 'error')).toHaveLength(0)
+  })
+
+  test('returns error for missing 402 response', () => {
+    const errors = validate(
+      makeDoc({
+        paths: {
+          '/search': {
+            post: {
+              'x-payment-info': {
+                amount: '100',
+                intent: 'charge',
+                method: 'tempo',
+              },
+              requestBody: {},
+              responses: {
+                '200': { description: 'OK' },
+              },
+            },
+          },
+        },
+      }),
+    )
+
+    expect(errors.find((error) => error.severity === 'error')?.message).toContain('402')
+  })
+
+  test('returns warning for missing requestBody', () => {
+    const errors = validate(
+      makeDoc({
+        paths: {
+          '/search': {
+            post: {
+              'x-payment-info': {
+                amount: '100',
+                intent: 'charge',
+                method: 'tempo',
+              },
+              responses: {
+                '200': { description: 'OK' },
+                '402': { description: 'Payment Required' },
+              },
+            },
+          },
+        },
+      }),
+    )
+
+    expect(errors.find((error) => error.severity === 'warning')?.message).toContain('requestBody')
+  })
+
+  test('returns structural errors for invalid top-level document', () => {
+    const errors = validate({ openapi: '3.1.0' })
+    expect(errors.length).toBeGreaterThan(0)
+    expect(errors[0]!.severity).toBe('error')
+  })
+
+  test('returns errors for invalid extension values', () => {
+    const errors = validate(
+      makeDoc({
+        'x-service-info': {
+          docs: { homepage: 'not-a-uri' },
+        },
+        paths: {
+          '/search': {
+            post: {
+              'x-payment-info': {
+                amount: '01',
+                intent: 'subscribe',
+                method: 'tempo',
+              },
+              responses: {
+                '402': { description: 'Payment Required' },
+              },
+            },
+          },
+        },
+      }),
+    )
+
+    expect(errors.some((error) => error.severity === 'error')).toBe(true)
+  })
+
+  test('ignores path-item-level fields like summary and parameters', () => {
+    const errors = validate(
+      makeDoc({
+        paths: {
+          '/search': {
+            summary: 'Search endpoints',
+            parameters: [{ name: 'q', in: 'query' }],
+            'x-custom': 'value',
+            post: {
+              'x-payment-info': {
+                amount: '100',
+                intent: 'charge',
+                method: 'tempo',
+              },
+              requestBody: {
+                content: { 'application/json': { schema: { type: 'object' } } },
+              },
+              responses: {
+                '200': { description: 'OK' },
+                '402': { description: 'Payment Required' },
+              },
+            },
+          },
+        },
+      }),
+    )
+
+    expect(errors.filter((e) => e.severity === 'error')).toHaveLength(0)
+  })
+
+  test('validates proxy-generated docs with relative llms path', () => {
+    const errors = validate({
+      info: { title: 'API Proxy', version: '1.0.0' },
+      openapi: '3.1.0',
+      paths: {},
+      'x-service-info': {
+        categories: ['gateway'],
+        docs: {
+          apiReference: 'https://example.com/api',
+          homepage: 'https://example.com',
+          llms: '/llms.txt',
+        },
+      },
+    })
+
+    expect(errors.filter((e) => e.severity === 'error')).toHaveLength(0)
+  })
+
+  test('accepts x-payment-info with unknown fields', () => {
+    const errors = validate({
+      info: { title: 'Test', version: '1.0.0' },
+      openapi: '3.1.0',
+      paths: {
+        '/api/call': {
+          post: {
+            'x-payment-info': {
+              price: '0.54',
+              pricingMode: 'fixed',
+              protocols: ['x402', 'mpp'],
+            },
+            requestBody: {
+              content: { 'application/json': { schema: { type: 'object' } } },
+            },
+            responses: {
+              '200': { description: 'OK' },
+              '402': { description: 'Payment Required' },
+            },
+          },
+        },
+      },
+    })
+    expect(errors.filter((e) => e.severity === 'error')).toHaveLength(0)
+  })
+})

package/src/discovery/Validate.ts

@@ -0,0 +1,76 @@
+import { DiscoveryDocument, PaymentInfo } from './Discovery.js'
+
+export type ValidationError = {
+  message: string
+  path: string
+  severity: 'error' | 'warning'
+}
+
+/**
+ * Validates a discovery document structurally and semantically.
+ */
+export function validate(doc: unknown): ValidationError[] {
+  const errors: ValidationError[] = []
+
+  const result = DiscoveryDocument.safeParse(doc)
+  if (!result.success) {
+    for (const issue of result.error.issues) {
+      errors.push({
+        message: issue.message,
+        path: issue.path.map(String).join('.') || '(root)',
+        severity: 'error',
+      })
+    }
+    return errors
+  }
+
+  const parsed = result.data
+  const paths = parsed.paths
+  if (!paths) return errors
+
+  for (const [pathKey, pathItem] of Object.entries(paths)) {
+    for (const [method, operation] of Object.entries(pathItem as Record<string, unknown>)) {
+      if (!operation || typeof operation !== 'object' || Array.isArray(operation)) continue
+      const op = operation as Record<string, unknown>
+
+      const opPath = `paths.${pathKey}.${method}`
+      const rawPaymentInfo = op['x-payment-info']
+      if (!rawPaymentInfo) continue
+
+      const paymentResult = PaymentInfo.safeParse(rawPaymentInfo)
+      if (!paymentResult.success) {
+        for (const issue of paymentResult.error.issues) {
+          errors.push({
+            message: issue.message,
+            path: `${opPath}.x-payment-info.${issue.path.map(String).join('.')}`,
+            severity: 'error',
+          })
+        }
+        continue
+      }
+
+      const responses = op.responses as Record<string, unknown> | undefined
+      if (!responses || !('402' in responses)) {
+        errors.push({
+          message: 'Operation with x-payment-info MUST have a 402 response',
+          path: `${opPath}.responses`,
+          severity: 'error',
+        })
+      }
+
+      const methodUpper = method.toUpperCase()
+      if (
+        !op.requestBody &&
+        (methodUpper === 'POST' || methodUpper === 'PUT' || methodUpper === 'PATCH')
+      ) {
+        errors.push({
+          message: 'Operation with x-payment-info has no requestBody',
+          path: opPath,
+          severity: 'warning',
+        })
+      }
+    }
+  }
+
+  return errors
+}

package/src/discovery/index.ts

@@ -0,0 +1,3 @@
+export * from './Discovery.js'
+export * from './OpenApi.js'
+export * from './Validate.js'

package/src/internal/constantTimeEqual.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test } from 'vitest'
+import { describe, expect, test } from 'vp/test'
 
 import { constantTimeEqual } from './constantTimeEqual.js'
 

package/src/mcp-sdk/client/McpClient.test-d.ts

@@ -1,7 +1,7 @@
 import type { Client } from '@modelcontextprotocol/sdk/client/index.js'
 import { tempo } from 'mppx/client'
 import type { Account } from 'viem'
-import { describe, expectTypeOf, test } from 'vitest'
+import { describe, expectTypeOf, test } from 'vp/test'
 
 import * as McpClient from './McpClient.js'
 

package/src/mcp-sdk/client/McpClient.test.ts

@@ -6,7 +6,7 @@ import { Challenge, Mcp as core_Mcp } from 'mppx'
 import { tempo as tempo_client } from 'mppx/client'
 import { Mppx as Mppx_server, tempo as tempo_server } from 'mppx/server'
 import { createClient } from 'viem'
-import { afterEach, beforeEach, describe, expect, test } from 'vitest'
+import { afterEach, beforeEach, describe, expect, test } from 'vp/test'
 import { accounts, asset, chain, http, client as testClient } from '~test/tempo/viem.js'
 
 import * as McpServer_transport from '../server/Transport.js'

package/src/mcp-sdk/server/Transport.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test } from 'vitest'
+import { describe, expect, test } from 'vp/test'
 
 import type { Challenge } from '../../Challenge.js'
 import type { Credential } from '../../Credential.js'

package/src/middlewares/elysia.test.ts

@@ -3,9 +3,9 @@ import * as http from 'node:http'
 import { Elysia } from 'elysia'
 import { Receipt } from 'mppx'
 import { Mppx as Mppx_client, tempo as tempo_client } from 'mppx/client'
-import { Mppx } from 'mppx/elysia'
+import { Mppx, discovery } from 'mppx/elysia'
 import { tempo as tempo_server } from 'mppx/server'
-import { describe, expect, test } from 'vitest'
+import { describe, expect, test } from 'vp/test'
 import { accounts, asset, client } from '~test/tempo/viem.js'
 
 function createServer(app: Elysia<any, any, any, any, any, any, any>) {
@@ -87,4 +87,29 @@ describe('charge', () => {
 
     server.close()
   })
+
+  test('serves /openapi.json from discovery plugin', async () => {
+    const app = new Elysia().use(
+      discovery(mppx, {
+        info: { title: 'Elysia API', version: '1.0.0' },
+        routes: [{ handler: mppx.charge({ amount: '1' }), 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: 'Elysia API', version: '1.0.0' })
+    expect(body.paths['/'].get['x-payment-info']).toMatchObject({
+      amount: '1000000',
+      currency: asset,
+      intent: 'charge',
+      method: 'tempo',
+    })
+
+    server.close()
+  })
 })

package/src/middlewares/elysia.ts

@@ -1,5 +1,6 @@
-import type { Context } from 'elysia'
+import { Elysia, type Context } from 'elysia'
 
+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'
 
@@ -68,3 +69,36 @@ export function payment<const intent extends Mppx_internal.AnyMethodFn>(
     if (header) set.headers['Payment-Receipt'] = header
   }
 }
+
+export type DiscoveryConfig = Omit<GenerateConfig, 'routes'> & {
+  path?: string
+  routes?: RouteConfig[]
+}
+
+const discoveryHeaders = { 'Cache-Control': 'public, max-age=300' }
+
+/**
+ * Returns an Elysia plugin that serves an OpenAPI discovery document.
+ */
+export function discovery(
+  mppx: { methods: readonly Mppx_internal.AnyServer[]; realm: string },
+  config: DiscoveryConfig = {},
+) {
+  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 } : {}),
+    }),
+  )
+
+  return new Elysia().get(
+    mountPath,
+    () =>
+      new Response(cached, {
+        headers: { ...discoveryHeaders, 'Content-Type': 'application/json' },
+      }),
+  )
+}

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'