mppx 0.4.9 → 0.4.11

package/src/discovery/OpenApi.ts

@@ -0,0 +1,224 @@
+import type * as Method from '../Method.js'
+import type { ServiceInfo } from './Discovery.js'
+
+export type DiscoveryHandler = ((...args: any[]) => unknown) & {
+  _internal?: {
+    _canonicalRequest: Record<string, unknown>
+    intent: string
+    name: string
+  }
+}
+
+export type LegacyRouteConfig = {
+  intent: string
+  method: string
+  options: Record<string, unknown>
+  path: string
+  requestBody?: Record<string, unknown>
+  summary?: string
+}
+
+export type HandlerRouteConfig = {
+  handler: DiscoveryHandler
+  method: string
+  path: string
+  requestBody?: Record<string, unknown>
+  summary?: string
+}
+
+export type RouteConfig = HandlerRouteConfig | LegacyRouteConfig
+
+export type GenerateConfig = {
+  info?: { title?: string; version?: string } | undefined
+  routes: RouteConfig[]
+  serviceInfo?: ServiceInfo | undefined
+}
+
+export type GenerateProxyConfig = {
+  basePath?: string | undefined
+  info?: { title?: string; version?: string } | undefined
+  routes: Array<{
+    method: string
+    path: string
+    payment: Record<string, unknown> | null
+    requestBody?: Record<string, unknown>
+    summary?: string
+  }>
+  serviceInfo?: ServiceInfo | undefined
+}
+
+type ResolvedRoute = {
+  method: string
+  path: string
+  payment: Record<string, unknown> | null
+  requestBody?: Record<string, unknown>
+  summary?: string
+}
+
+/**
+ * Generates an OpenAPI 3.1.0 discovery document from an mppx instance
+ * and route configuration.
+ */
+export function generate(
+  mppx: { methods: readonly Method.AnyServer[]; realm: string },
+  config: GenerateConfig,
+): Record<string, unknown> {
+  const methods = mppx.methods
+  const methodsByKey = new Map<string, Method.AnyServer>()
+  const intentCount: Record<string, number> = {}
+
+  for (const mi of methods) {
+    methodsByKey.set(`${mi.name}/${mi.intent}`, mi)
+    intentCount[mi.intent] = (intentCount[mi.intent] ?? 0) + 1
+  }
+  for (const mi of methods) {
+    if (intentCount[mi.intent] === 1) methodsByKey.set(mi.intent, mi)
+  }
+
+  const routes = config.routes.map((route) => resolveRoute(route, methodsByKey))
+  return createDocument({
+    info: {
+      title: config.info?.title ?? mppx.realm,
+      version: config.info?.version ?? '1.0.0',
+    },
+    routes,
+    serviceInfo: config.serviceInfo,
+  })
+}
+
+/**
+ * Generates an OpenAPI 3.1.0 discovery document for a proxy surface.
+ */
+export function generateProxy(config: GenerateProxyConfig): Record<string, unknown> {
+  const routes = config.routes.map((route) => ({
+    ...route,
+    path: withBasePath(config.basePath, route.path),
+  }))
+
+  return createDocument({
+    info: {
+      title: config.info?.title ?? 'API Proxy',
+      version: config.info?.version ?? '1.0.0',
+    },
+    routes,
+    serviceInfo: config.serviceInfo,
+  })
+}
+
+function createDocument(config: {
+  info: { title: string; version: string }
+  routes: ResolvedRoute[]
+  serviceInfo?: ServiceInfo | undefined
+}) {
+  const paths: Record<string, Record<string, unknown>> = {}
+
+  for (const route of config.routes) {
+    const method = route.method.toLowerCase()
+    const operation: Record<string, unknown> = {
+      responses: {
+        ...(route.payment ? { '402': { description: 'Payment Required' } } : {}),
+        '200': { description: 'Successful response' },
+      },
+    }
+
+    if (route.payment) operation['x-payment-info'] = route.payment
+    if (route.summary) operation.summary = route.summary
+    if (route.requestBody) operation.requestBody = route.requestBody
+
+    if (!paths[route.path]) paths[route.path] = {}
+    paths[route.path]![method] = operation
+  }
+
+  const doc: Record<string, unknown> = {
+    info: config.info,
+    openapi: '3.1.0',
+    paths,
+  }
+  if (config.serviceInfo) doc['x-service-info'] = config.serviceInfo
+  return doc
+}
+
+function resolveRoute(
+  route: RouteConfig,
+  methodsByKey: Map<string, Method.AnyServer>,
+): ResolvedRoute {
+  if ('handler' in route) {
+    const internal = route.handler._internal
+    if (!internal)
+      throw new Error(
+        `Route ${route.method.toUpperCase()} ${route.path} is missing discovery metadata`,
+      )
+    return {
+      method: route.method,
+      path: route.path,
+      payment: paymentInfoFromCanonical({
+        canonicalRequest: internal._canonicalRequest,
+        intent: internal.intent,
+        method: internal.name,
+      }),
+      ...(route.requestBody ? { requestBody: route.requestBody } : {}),
+      ...(route.summary ? { summary: route.summary } : {}),
+    }
+  }
+
+  const mi = methodsByKey.get(route.intent)
+  if (!mi) {
+    throw new Error(
+      `Unknown intent "${route.intent}" for route ${route.method.toUpperCase()} ${route.path}. Available: ${[...methodsByKey.keys()].join(', ')}`,
+    )
+  }
+
+  return {
+    method: route.method,
+    path: route.path,
+    payment: paymentInfoFromCanonical({
+      canonicalRequest: route.options,
+      intent: mi.intent,
+      method: mi.name,
+    }),
+    ...(route.requestBody ? { requestBody: route.requestBody } : {}),
+    ...(route.summary ? { summary: route.summary } : {}),
+  }
+}
+
+function paymentInfoFromCanonical(route: {
+  canonicalRequest: Record<string, unknown>
+  intent: string
+  method: string
+}) {
+  const { canonicalRequest, intent, method } = route
+  const methodDetails = (canonicalRequest.methodDetails ?? {}) as Record<string, unknown>
+
+  const amount = pickString(canonicalRequest.amount) ?? pickString(methodDetails.amount) ?? null
+  const currency = pickString(canonicalRequest.currency) ?? pickString(methodDetails.currency)
+  const description = pickString(canonicalRequest.description)
+
+  const base: Record<string, unknown> = {
+    amount,
+    ...(currency ? { currency } : {}),
+    ...(description ? { description } : {}),
+    intent,
+    method,
+  }
+
+  // Forward any extra canonical params that aren't already covered.
+  const reserved = new Set(['amount', 'currency', 'description', 'methodDetails'])
+  for (const [key, value] of Object.entries(canonicalRequest)) {
+    if (!reserved.has(key) && value !== undefined) base[key] = value
+  }
+
+  return base
+}
+
+function pickString(value: unknown) {
+  return typeof value === 'string' ? value : undefined
+}
+
+function withBasePath(basePath: string | undefined, path: string) {
+  if (!basePath) return path
+  const normalizedBasePath = basePath.startsWith('/') ? basePath : `/${basePath}`
+  const trimmedBasePath = normalizedBasePath.endsWith('/')
+    ? normalizedBasePath.slice(0, -1)
+    : normalizedBasePath
+  return `${trimmedBasePath}${path}`
+}

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' },
+      }),
+  )
+}