mppx 0.8.15 → 0.8.18

package/src/discovery/OpenApi.test.ts

@@ -1,453 +0,0 @@
-import * as Method from '../Method.js'
-import * as Mppx from '../server/Mppx.js'
-import * as z from '../zod.js'
-import { generate } from './OpenApi.js'
-
-const charge = Method.toServer(
-  Method.from({
-    intent: 'charge',
-    name: 'tempo',
-    schema: {
-      credential: { payload: z.object({ signature: z.string() }) },
-      request: z.object({
-        amount: z.string(),
-        currency: z.string(),
-        recipient: z.string(),
-      }),
-    },
-  }),
-  {
-    verify: async () => ({
-      method: 'tempo',
-      reference: '',
-      status: 'success' as const,
-      timestamp: '',
-    }),
-  },
-)
-
-const session = Method.toServer(
-  Method.from({
-    intent: 'session',
-    name: 'tempo',
-    schema: {
-      credential: { payload: z.object({ signature: z.string() }) },
-      request: z.object({
-        amount: z.union([z.null(), z.string()]),
-        recipient: z.string(),
-      }),
-    },
-  }),
-  {
-    verify: async () => ({
-      method: 'tempo',
-      reference: '',
-      status: 'success' as const,
-      timestamp: '',
-    }),
-  },
-)
-
-const subscribe = Method.toServer(
-  Method.from({
-    intent: 'subscribe',
-    name: 'tempo',
-    schema: {
-      credential: { payload: z.object({ signature: z.string() }) },
-      request: z.object({
-        amount: z.string(),
-      }),
-    },
-  }),
-  {
-    verify: async () => ({
-      method: 'tempo',
-      reference: '',
-      status: 'success' as const,
-      timestamp: '',
-    }),
-  },
-)
-
-function createMppx<const methods extends Mppx.Methods>(methods: methods) {
-  return Mppx.create({
-    methods,
-    realm: 'test-realm',
-    secretKey: 'test-secret-key-test-secret-key-32',
-  })
-}
-
-describe('generate', () => {
-  test('generates a valid OpenAPI 3.1.0 document for legacy route config', () => {
-    const mppx = createMppx([charge])
-    const doc = generate(mppx, {
-      routes: [
-        {
-          intent: 'charge',
-          method: 'get',
-          options: { amount: '100', currency: '0xUSDC', recipient: '0x123' },
-          path: '/api/resource',
-        },
-      ],
-    })
-
-    expect(doc).toMatchInlineSnapshot(`
-      {
-        "info": {
-          "title": "test-realm",
-          "version": "1.0.0",
-        },
-        "openapi": "3.1.0",
-        "paths": {
-          "/api/resource": {
-            "get": {
-              "responses": {
-                "200": {
-                  "description": "Successful response",
-                },
-                "402": {
-                  "description": "Payment Required",
-                },
-              },
-              "x-payment-info": {
-                "offers": [
-                  {
-                    "amount": "100",
-                    "currency": "0xUSDC",
-                    "intent": "charge",
-                    "method": "tempo",
-                    "recipient": "0x123",
-                  },
-                ],
-              },
-            },
-          },
-        },
-      }
-    `)
-  })
-
-  test('supports handler-derived route config', () => {
-    const mppx = createMppx([charge])
-    const handler = mppx.charge({
-      amount: '50',
-      currency: 'usd',
-      description: 'Search credits',
-      recipient: '0x1',
-    })
-
-    const doc = generate(mppx, {
-      routes: [
-        {
-          handler,
-          method: 'post',
-          path: '/api/search',
-        },
-      ],
-    })
-
-    expect(doc).toMatchInlineSnapshot(`
-      {
-        "info": {
-          "title": "test-realm",
-          "version": "1.0.0",
-        },
-        "openapi": "3.1.0",
-        "paths": {
-          "/api/search": {
-            "post": {
-              "responses": {
-                "200": {
-                  "description": "Successful response",
-                },
-                "402": {
-                  "description": "Payment Required",
-                },
-              },
-              "x-payment-info": {
-                "offers": [
-                  {
-                    "amount": "50",
-                    "currency": "usd",
-                    "intent": "charge",
-                    "method": "tempo",
-                    "recipient": "0x1",
-                  },
-                ],
-              },
-            },
-          },
-        },
-      }
-    `)
-  })
-
-  test('handles null amount for session intent', () => {
-    const mppx = createMppx([session])
-    const doc = generate(mppx, {
-      routes: [
-        {
-          intent: 'session',
-          method: 'post',
-          options: { amount: null, recipient: '0x123' },
-          path: '/api/stream',
-        },
-      ],
-    })
-
-    expect(doc).toMatchInlineSnapshot(`
-      {
-        "info": {
-          "title": "test-realm",
-          "version": "1.0.0",
-        },
-        "openapi": "3.1.0",
-        "paths": {
-          "/api/stream": {
-            "post": {
-              "responses": {
-                "200": {
-                  "description": "Successful response",
-                },
-                "402": {
-                  "description": "Payment Required",
-                },
-              },
-              "x-payment-info": {
-                "offers": [
-                  {
-                    "amount": null,
-                    "intent": "session",
-                    "method": "tempo",
-                    "recipient": "0x123",
-                  },
-                ],
-              },
-            },
-          },
-        },
-      }
-    `)
-  })
-
-  test('includes x-service-info when provided', () => {
-    const mppx = createMppx([charge])
-    const doc = generate(mppx, {
-      routes: [],
-      serviceInfo: {
-        categories: ['ai'],
-        docs: { homepage: 'https://example.com' },
-      },
-    })
-
-    expect(doc).toMatchInlineSnapshot(`
-      {
-        "info": {
-          "title": "test-realm",
-          "version": "1.0.0",
-        },
-        "openapi": "3.1.0",
-        "paths": {},
-        "x-service-info": {
-          "categories": [
-            "ai",
-          ],
-          "docs": {
-            "homepage": "https://example.com",
-          },
-        },
-      }
-    `)
-  })
-
-  test('multi-route document with mixed intents', () => {
-    const mppx = createMppx([charge, session])
-    const doc = generate(mppx, {
-      info: { title: 'Multi-Route API', version: '2.0.0' },
-      routes: [
-        {
-          intent: 'charge',
-          method: 'post',
-          options: { amount: '500', currency: '0xUSDC', recipient: '0xABC' },
-          path: '/api/search',
-          summary: 'Search the index',
-          requestBody: {
-            content: { 'application/json': { schema: { type: 'object' } } },
-          },
-        },
-        {
-          intent: 'session',
-          method: 'post',
-          options: { amount: null, recipient: '0xABC' },
-          path: '/api/stream',
-        },
-        {
-          intent: 'charge',
-          method: 'get',
-          options: { amount: '100', currency: '0xUSDC', recipient: '0xABC' },
-          path: '/api/models',
-        },
-      ],
-      serviceInfo: {
-        categories: ['ai', 'search'],
-        docs: {
-          apiReference: 'https://example.com/api',
-          homepage: 'https://example.com',
-          llms: 'https://example.com/llms.txt',
-        },
-      },
-    })
-
-    expect(doc).toMatchInlineSnapshot(`
-      {
-        "info": {
-          "title": "Multi-Route API",
-          "version": "2.0.0",
-        },
-        "openapi": "3.1.0",
-        "paths": {
-          "/api/models": {
-            "get": {
-              "responses": {
-                "200": {
-                  "description": "Successful response",
-                },
-                "402": {
-                  "description": "Payment Required",
-                },
-              },
-              "x-payment-info": {
-                "offers": [
-                  {
-                    "amount": "100",
-                    "currency": "0xUSDC",
-                    "intent": "charge",
-                    "method": "tempo",
-                    "recipient": "0xABC",
-                  },
-                ],
-              },
-            },
-          },
-          "/api/search": {
-            "post": {
-              "requestBody": {
-                "content": {
-                  "application/json": {
-                    "schema": {
-                      "type": "object",
-                    },
-                  },
-                },
-              },
-              "responses": {
-                "200": {
-                  "description": "Successful response",
-                },
-                "402": {
-                  "description": "Payment Required",
-                },
-              },
-              "summary": "Search the index",
-              "x-payment-info": {
-                "offers": [
-                  {
-                    "amount": "500",
-                    "currency": "0xUSDC",
-                    "intent": "charge",
-                    "method": "tempo",
-                    "recipient": "0xABC",
-                  },
-                ],
-              },
-            },
-          },
-          "/api/stream": {
-            "post": {
-              "responses": {
-                "200": {
-                  "description": "Successful response",
-                },
-                "402": {
-                  "description": "Payment Required",
-                },
-              },
-              "x-payment-info": {
-                "offers": [
-                  {
-                    "amount": null,
-                    "intent": "session",
-                    "method": "tempo",
-                    "recipient": "0xABC",
-                  },
-                ],
-              },
-            },
-          },
-        },
-        "x-service-info": {
-          "categories": [
-            "ai",
-            "search",
-          ],
-          "docs": {
-            "apiReference": "https://example.com/api",
-            "homepage": "https://example.com",
-            "llms": "https://example.com/llms.txt",
-          },
-        },
-      }
-    `)
-  })
-
-  test('passes through custom intents and extra params', () => {
-    const mppx = createMppx([subscribe])
-    const doc = generate(mppx, {
-      routes: [
-        {
-          intent: 'subscribe',
-          method: 'post',
-          options: { amount: '100', interval: 'monthly', recipient: '0xABC' },
-          path: '/api/subscribe',
-          summary: 'Monthly subscription',
-        },
-      ],
-    })
-
-    expect(doc).toMatchInlineSnapshot(`
-      {
-        "info": {
-          "title": "test-realm",
-          "version": "1.0.0",
-        },
-        "openapi": "3.1.0",
-        "paths": {
-          "/api/subscribe": {
-            "post": {
-              "responses": {
-                "200": {
-                  "description": "Successful response",
-                },
-                "402": {
-                  "description": "Payment Required",
-                },
-              },
-              "summary": "Monthly subscription",
-              "x-payment-info": {
-                "offers": [
-                  {
-                    "amount": "100",
-                    "intent": "subscribe",
-                    "interval": "monthly",
-                    "method": "tempo",
-                    "recipient": "0xABC",
-                  },
-                ],
-              },
-            },
-          },
-        },
-      }
-    `)
-  })
-})

package/src/discovery/OpenApi.ts

@@ -1,224 +0,0 @@
-import type * as Method from '../Method.js'
-import { PaymentInfo, 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'] = PaymentInfo.parse(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}`
-}