mppx 0.4.9 → 0.4.10

package/src/discovery/Discovery.ts

@@ -0,0 +1,72 @@
+import * as z from '../zod.js'
+
+const uriOrPathPattern = /^([a-zA-Z][a-zA-Z\d+.-]*:\/\/\S+|\/\S*)$/
+
+function uriOrPath() {
+  return z.string().check(z.regex(uriOrPathPattern, 'Invalid URI or path'))
+}
+
+/**
+ * Schema for the `x-payment-info` OpenAPI extension on an operation.
+ *
+ * Only validates spec-defined fields when present; unknown fields are ignored.
+ * Discovery is advisory only. Runtime 402 challenges remain authoritative.
+ */
+export const PaymentInfo = z.looseObject({
+  amount: z.optional(
+    z.union([z.null(), z.string().check(z.regex(/^(0|[1-9][0-9]*)$/, 'Invalid amount'))]),
+  ),
+  currency: z.optional(z.string()),
+  description: z.optional(z.string()),
+  intent: z.optional(z.string()),
+  method: z.optional(z.string()),
+})
+export type PaymentInfo = z.infer<typeof PaymentInfo>
+
+const ServiceDocs = z.looseObject({
+  apiReference: z.optional(uriOrPath()),
+  homepage: z.optional(uriOrPath()),
+  llms: z.optional(uriOrPath()),
+})
+
+/**
+ * Schema for the `x-service-info` OpenAPI extension at the document root.
+ */
+export const ServiceInfo = z.looseObject({
+  categories: z.optional(z.array(z.string())),
+  docs: z.optional(ServiceDocs),
+})
+export type ServiceInfo = z.infer<typeof ServiceInfo>
+
+const OperationObject = z.looseObject({
+  'x-payment-info': z.optional(PaymentInfo),
+  requestBody: z.optional(z.unknown()),
+  responses: z.optional(z.record(z.string(), z.unknown())),
+  summary: z.optional(z.string()),
+})
+
+const PathItem = z.looseObject({
+  delete: z.optional(OperationObject),
+  get: z.optional(OperationObject),
+  head: z.optional(OperationObject),
+  options: z.optional(OperationObject),
+  patch: z.optional(OperationObject),
+  post: z.optional(OperationObject),
+  put: z.optional(OperationObject),
+  trace: z.optional(OperationObject),
+})
+
+/**
+ * Minimal schema for an OpenAPI discovery document annotated with
+ * `x-service-info` and per-operation `x-payment-info`.
+ */
+export const DiscoveryDocument = z.looseObject({
+  openapi: z.string(),
+  info: z.looseObject({
+    title: z.string(),
+    version: z.string(),
+  }),
+  'x-service-info': z.optional(ServiceInfo),
+  paths: z.optional(z.record(z.string(), PathItem)),
+})
+export type DiscoveryDocument = z.infer<typeof DiscoveryDocument>

package/src/discovery/OpenApi.test.ts

@@ -0,0 +1,425 @@
+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',
+  })
+}
+
+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": {
+                "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": {
+                "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": {
+                "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": {
+                "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": {
+                "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": {
+                "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": {
+                "amount": "100",
+                "intent": "subscribe",
+                "interval": "monthly",
+                "method": "tempo",
+                "recipient": "0xABC",
+              },
+            },
+          },
+        },
+      }
+    `)
+  })
+})

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}`
+}