mppx 0.4.8 → 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,5 @@
-import { describe, expect, test } from 'vitest'
+import { describe, expect, test } from 'vp/test'
+
 import { constantTimeEqual } from './constantTimeEqual.js'
 
 describe('constantTimeEqual', () => {

package/src/internal/types.ts

@@ -256,9 +256,7 @@ export type LastInUnion<U> =
 
 /** @internal */
 export type UnionToIntersection<union> = (
-  union extends unknown
-    ? (arg: union) => 0
-    : never
+  union extends unknown ? (arg: union) => 0 : never
 ) extends (arg: infer i) => 0
   ? i
   : never

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

@@ -1,7 +1,8 @@
 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'
 
 describe('McpClient.wrap', () => {

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

@@ -6,8 +6,9 @@ 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'
 import * as McpClient from './McpClient.js'
 

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

@@ -1,5 +1,6 @@
 import type { Client } from '@modelcontextprotocol/sdk/client/index.js'
 import type { McpError } from '@modelcontextprotocol/sdk/types.js'
+
 import type * as Challenge from '../../Challenge.js'
 import * as Credential from '../../Credential.js'
 import * as core_Mcp from '../../Mcp.js'
@@ -84,6 +85,7 @@ export function wrap<
           const installed = methods.map((m) => `${m.name}.${m.intent}`).join(', ')
           throw new Error(
             `No compatible payment method. Server offers: ${available}. Client has: ${installed}`,
+            { cause: error },
           )
         }
 

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

@@ -1,4 +1,5 @@
-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'
 import { VerificationFailedError } from '../../Errors.js'

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

@@ -1,4 +1,5 @@
 import type { CallToolResult, McpError } from '@modelcontextprotocol/sdk/types.js'
+
 import type * as Credential from '../../Credential.js'
 import * as core_Mcp from '../../Mcp.js'
 import * as Transport from '../../server/Transport.js'

package/src/middlewares/elysia.test.ts

@@ -1,10 +1,11 @@
 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>) {
@@ -86,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,4 +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'
 
@@ -67,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 } from 'mppx/express'
-import { tempo as tempo_server } from 'mppx/server'
+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,
@@ -158,3 +186,63 @@ describe('session', () => {
     server.close()
   })
 })
+
+describe('payment', () => {
+  const mppx = Mppx_server.create({
+    methods: [
+      tempo_server({
+        getClient: () => client,
+        currency: asset,
+        account: accounts[0],
+      }),
+    ],
+    secretKey,
+  })
+
+  const { fetch } = Mppx_client.create({
+    polyfill: false,
+    methods: [
+      tempo_client({
+        account: accounts[1],
+        getClient: () => client,
+      }),
+    ],
+  })
+
+  test('returns 402 when no credential', async () => {
+    const app = express()
+    app.get('/', payment(mppx.charge, { amount: '1' }), (_req, res) => {
+      res.json({ fortune: 'You will be rich' })
+    })
+
+    const server = await createServer(app)
+    const response = await globalThis.fetch(server.url)
+    expect(response.status).toBe(402)
+    expect(response.headers.get('WWW-Authenticate')).toContain('Payment')
+
+    server.close()
+  })
+
+  test('returns 200 with receipt on valid payment', async () => {
+    const app = express()
+    app.get('/', payment(mppx.charge, { amount: '1' }), (_req, res) => {
+      res.json({ fortune: 'You will be rich' })
+    })
+
+    const server = await createServer(app)
+    const response = await fetch(server.url)
+    expect(response.status).toBe(200)
+
+    const body = await response.json()
+    expect(body).toEqual({ fortune: 'You will be rich' })
+
+    const receiptHeader = response.headers.get('Payment-Receipt')
+    expect(receiptHeader).toBeTruthy()
+
+    const receipt = Receipt.fromResponse(response)
+    expect(receipt.status).toBe('success')
+    expect(receipt.method).toBe('tempo')
+
+    server.close()
+  })
+})

package/src/middlewares/express.ts

@@ -1,11 +1,13 @@
 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 Request from '../server/Request.js'
 import * as Mppx_internal from './internal/mppx.js'
 
 export * from '../server/Methods.js'
@@ -60,7 +62,11 @@ export function payment<const intent extends Mppx_internal.AnyMethodFn>(
   options: intent extends (options: infer options) => any ? options : never,
 ): RequestHandler {
   return async (req: ExpressRequest, res: ExpressResponse, next: NextFunction) => {
-    const result = await intent(options)(Request.fromNodeListener(req, res))
+    const request = new Request(`${req.protocol}://${req.hostname}${req.originalUrl}`, {
+      method: req.method,
+      headers: req.headers as Record<string, string>,
+    })
+    const result = await intent(options)(request)
 
     if (result.status === 402) {
       const challenge = result.challenge as Response
@@ -80,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)
+  })
+}