mppx 0.4.8 → 0.4.10

package/src/proxy/Proxy.test.ts

@@ -1,9 +1,10 @@
 import { Receipt } from 'mppx'
 import { Mppx as Mppx_client, tempo as tempo_client } from 'mppx/client'
 import { Mppx as Mppx_server, tempo as tempo_server } from 'mppx/server'
-import { afterEach, describe, expect, test } from 'vitest'
+import { afterEach, describe, expect, test } from 'vp/test'
 import * as Http from '~test/Http.js'
 import { accounts, asset, client } from '~test/tempo/viem.js'
+
 import * as ApiProxy from './Proxy.js'
 import * as Service from './Service.js'
 import { anthropic } from './services/anthropic.js'
@@ -64,11 +65,19 @@ function createUpstream(handler: (req: Request) => Response | Promise<Response>)
 }
 
 describe('create', () => {
-  test('behavior: GET /discover/all returns service discovery JSON', async () => {
+  test('behavior: GET /openapi.json returns discovery JSON', async () => {
     const proxy = ApiProxy.create({
+      categories: ['gateway'],
+      docs: {
+        apiReference: 'https://gateway.example.com/reference',
+        homepage: 'https://gateway.example.com',
+      },
+      title: 'My AI Gateway',
+      version: '2.0.0',
       services: [
         Service.from('api', {
           baseUrl: 'https://api.example.com',
+          categories: ['compute'],
           routes: {
             'GET /v1/models': true,
             'POST /v1/generate': mppx_server.charge({ amount: '1', description: 'Generate text' }),
@@ -83,73 +92,40 @@ describe('create', () => {
     })
     proxyServer = await Http.createServer(proxy.listener)
 
-    const res = await fetch(`${proxyServer.url}/discover/all`)
+    const res = await fetch(`${proxyServer.url}/openapi.json`)
     expect(res.status).toBe(200)
-    expect(await res.json()).toMatchInlineSnapshot(`
-      [
-        {
-          "id": "api",
-          "routes": [
-            {
-              "method": "GET",
-              "path": "/api/v1/models",
-              "pattern": "GET /api/v1/models",
-              "payment": null,
-            },
-            {
-              "method": "POST",
-              "path": "/api/v1/generate",
-              "pattern": "POST /api/v1/generate",
-              "payment": {
-                "amount": "1000000",
-                "currency": "0x20c0000000000000000000000000000000000001",
-                "decimals": 6,
-                "description": "Generate text",
-                "intent": "charge",
-                "method": "tempo",
-                "recipient": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
-              },
-            },
-            {
-              "method": "POST",
-              "path": "/api/v1/stream",
-              "pattern": "POST /api/v1/stream",
-              "payment": {
-                "amount": "1000000",
-                "currency": "0x20c0000000000000000000000000000000000001",
-                "decimals": 6,
-                "description": "Stream text",
-                "intent": "session",
-                "method": "tempo",
-                "recipient": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
-                "unitType": "token",
-              },
-            },
-          ],
-        },
-      ]
-    `)
-  })
-
-  test('behavior: GET /discover returns JSON by default', async () => {
-    const proxy = ApiProxy.create({
-      services: [
-        Service.from('api', {
-          baseUrl: 'https://api.example.com',
-          routes: {
-            'GET /v1/models': true,
-          },
-        }),
-      ],
+    expect(res.headers.get('cache-control')).toBe('public, max-age=300')
+    const body = (await res.json()) as Record<string, any>
+    expect(body.openapi).toBe('3.1.0')
+    expect(body.info).toEqual({ title: 'My AI Gateway', version: '2.0.0' })
+    expect(body['x-service-info']).toEqual({
+      categories: ['gateway'],
+      docs: {
+        apiReference: 'https://gateway.example.com/reference',
+        homepage: 'https://gateway.example.com',
+        llms: '/llms.txt',
+      },
+    })
+    expect(body.paths['/api/v1/models'].get.responses['200']).toEqual({
+      description: 'Successful response',
+    })
+    expect(body.paths['/api/v1/generate'].post['x-payment-info']).toMatchObject({
+      amount: '1000000',
+      currency: asset,
+      description: 'Generate text',
+      intent: 'charge',
+      method: 'tempo',
+    })
+    expect(body.paths['/api/v1/stream'].post['x-payment-info']).toMatchObject({
+      amount: '1000000',
+      currency: asset,
+      description: 'Stream text',
+      intent: 'session',
+      method: 'tempo',
     })
-    proxyServer = await Http.createServer(proxy.listener)
-
-    const res = await fetch(`${proxyServer.url}/discover`)
-    expect(res.status).toBe(200)
-    expect(res.headers.get('content-type')).toMatchInlineSnapshot(`"application/json"`)
   })
 
-  test('behavior: GET /discover returns llms.txt for markdown clients', async () => {
+  test('behavior: GET /llms.txt returns text docs linked to OpenAPI discovery', async () => {
     const proxy = ApiProxy.create({
       title: 'My AI Gateway',
       description: 'A paid proxy for LLM and AI services.',
@@ -185,9 +161,7 @@ describe('create', () => {
     })
     proxyServer = await Http.createServer(proxy.listener)
 
-    const res = await fetch(`${proxyServer.url}/discover`, {
-      headers: { Accept: 'text/plain' },
-    })
+    const res = await fetch(`${proxyServer.url}/llms.txt`)
     expect(res.status).toBe(200)
     expect(res.headers.get('content-type')).toBe('text/plain; charset=utf-8')
     expect(await res.text()).toMatchInlineSnapshot(`
@@ -197,20 +171,20 @@ describe('create', () => {
 
       ## Services
 
-      - [OpenAI](/discover/openai.md): Chat completions, embeddings, image generation, and audio transcription.
-      - [Anthropic](/discover/anthropic.md): Claude language models for messages and completions.
+      - OpenAI: Chat completions, embeddings, image generation, and audio transcription.
+      - Anthropic: Claude language models for messages and completions.
 
-      [See all service definitions](/discover/all.md)"
+      [OpenAPI discovery](/openapi.json)"
     `)
   })
 
-  test('behavior: GET /discover/:id returns single service', async () => {
+  test('behavior: GET /openapi.json respects basePath', async () => {
     const proxy = ApiProxy.create({
+      basePath: '/proxy',
       services: [
         Service.from('api', {
           baseUrl: 'https://api.example.com',
           routes: {
-            'GET /v1/models': true,
             'POST /v1/generate': mppx_server.charge({ amount: '1', description: 'Generate text' }),
           },
         }),
@@ -218,205 +192,16 @@ describe('create', () => {
     })
     proxyServer = await Http.createServer(proxy.listener)
 
-    const res = await fetch(`${proxyServer.url}/discover/api`)
-    expect(res.status).toBe(200)
-    expect(await res.json()).toMatchInlineSnapshot(`
-      {
-        "id": "api",
-        "routes": [
-          {
-            "method": "GET",
-            "path": "/api/v1/models",
-            "pattern": "GET /api/v1/models",
-            "payment": null,
-          },
-          {
-            "method": "POST",
-            "path": "/api/v1/generate",
-            "pattern": "POST /api/v1/generate",
-            "payment": {
-              "amount": "1000000",
-              "currency": "0x20c0000000000000000000000000000000000001",
-              "decimals": 6,
-              "description": "Generate text",
-              "intent": "charge",
-              "method": "tempo",
-              "recipient": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
-            },
-          },
-        ],
-      }
-    `)
-  })
-
-  test('behavior: GET /discover/all.md returns full markdown with routes', async () => {
-    const proxy = ApiProxy.create({
-      services: [
-        openai({
-          apiKey: 'sk-test',
-          routes: {
-            'POST /v1/chat/completions': mppx_server.charge({
-              amount: '0.05',
-              description: 'Chat completion',
-            }),
-            'GET /v1/models': true,
-          },
-        }),
-        anthropic({
-          apiKey: 'sk-ant-test',
-          routes: {
-            'POST /v1/messages': mppx_server.charge({
-              amount: '0.03',
-              description: 'Send message',
-            }),
-          },
-        }),
-      ],
-    })
-    proxyServer = await Http.createServer(proxy.listener)
-
-    const res = await fetch(`${proxyServer.url}/discover/all.md`)
-    expect(res.status).toBe(200)
-    expect(res.headers.get('content-type')).toBe('text/markdown; charset=utf-8')
-    expect(await res.text()).toMatchInlineSnapshot(`
-      "# Services
-
-      ## [OpenAI](/discover/openai.md)
-
-      Chat completions, embeddings, image generation, and audio transcription.
-
-      ### Routes
-
-      - \`POST /openai/v1/chat/completions\`: Chat completion
-        - Type: charge
-        - Price: 0.05 (50000 units, 6 decimals)
-        - Currency: 0x20c0000000000000000000000000000000000001
-        - Docs: https://context7.com/websites/platform_openai/llms.txt?topic=POST%20%2Fv1%2Fchat%2Fcompletions
-
-      - \`GET /openai/v1/models\`
-        - Type: free
-        - Docs: https://context7.com/websites/platform_openai/llms.txt?topic=GET%20%2Fv1%2Fmodels
-
-      ## [Anthropic](/discover/anthropic.md)
-
-      Claude language models for messages and completions.
-
-      ### Routes
-
-      - \`POST /anthropic/v1/messages\`: Send message
-        - Type: charge
-        - Price: 0.03 (30000 units, 6 decimals)
-        - Currency: 0x20c0000000000000000000000000000000000001
-      "
-    `)
-  })
-
-  test('behavior: GET /discover/:id.md returns markdown', async () => {
-    const proxy = ApiProxy.create({
-      services: [
-        openai({
-          apiKey: 'sk-test',
-          routes: {
-            'POST /v1/chat/completions': mppx_server.charge({
-              amount: '0.05',
-              description: 'Chat completion',
-            }),
-            'GET /v1/models': true,
-          },
-        }),
-        anthropic({
-          apiKey: 'sk-ant-test',
-          routes: {
-            'POST /v1/messages': mppx_server.charge({ amount: '0.03' }),
-          },
-        }),
-      ],
-    })
-    proxyServer = await Http.createServer(proxy.listener)
-
-    const res = await fetch(`${proxyServer.url}/discover/openai.md`)
-    expect(res.status).toBe(200)
-    expect(res.headers.get('content-type')).toBe('text/markdown; charset=utf-8')
-    expect(await res.text()).toMatchInlineSnapshot(`
-      "# OpenAI
-
-      > Documentation: https://context7.com/websites/platform_openai/llms.txt
-
-      Chat completions, embeddings, image generation, and audio transcription.
-
-      ## Routes
-
-      - \`POST /openai/v1/chat/completions\`: Chat completion
-        - Type: charge
-        - Price: 0.05 (50000 units, 6 decimals)
-        - Currency: 0x20c0000000000000000000000000000000000001
-        - Docs: https://context7.com/websites/platform_openai/llms.txt?topic=POST%20%2Fv1%2Fchat%2Fcompletions
-
-      - \`GET /openai/v1/models\`
-        - Type: free
-        - Docs: https://context7.com/websites/platform_openai/llms.txt?topic=GET%20%2Fv1%2Fmodels
-      "
-    `)
-  })
-
-  test('behavior: GET /discover/:id with Accept: text/markdown returns markdown', async () => {
-    const proxy = ApiProxy.create({
-      services: [
-        openai({
-          apiKey: 'sk-test',
-          routes: { 'GET /v1/models': true },
-        }),
-        anthropic({
-          apiKey: 'sk-ant-test',
-          routes: {
-            'POST /v1/messages': mppx_server.charge({ amount: '0.03' }),
-          },
-        }),
-      ],
-    })
-    proxyServer = await Http.createServer(proxy.listener)
-
-    const res = await fetch(`${proxyServer.url}/discover/anthropic`, {
-      headers: { Accept: 'text/markdown' },
-    })
+    const res = await fetch(`${proxyServer.url}/proxy/openapi.json`)
     expect(res.status).toBe(200)
-    expect(res.headers.get('content-type')).toBe('text/markdown; charset=utf-8')
-  })
-
-  test('behavior: GET /discover/:id without Accept returns JSON', async () => {
-    const proxy = ApiProxy.create({
-      services: [
-        openai({
-          apiKey: 'sk-test',
-          routes: { 'GET /v1/models': true },
-        }),
-        anthropic({
-          apiKey: 'sk-ant-test',
-          routes: {
-            'POST /v1/messages': mppx_server.charge({ amount: '0.03' }),
-          },
-        }),
-      ],
+    const body = (await res.json()) as Record<string, any>
+    expect(body.paths['/proxy/api/v1/generate'].post['x-payment-info']).toMatchObject({
+      amount: '1000000',
+      currency: asset,
+      description: 'Generate text',
+      intent: 'charge',
+      method: 'tempo',
     })
-    proxyServer = await Http.createServer(proxy.listener)
-
-    const res = await fetch(`${proxyServer.url}/discover/openai`)
-    expect(res.status).toBe(200)
-    expect(res.headers.get('content-type')).toMatchInlineSnapshot(`"application/json"`)
-  })
-
-  test('behavior: GET /discover/:id.md returns 404 for unknown', async () => {
-    const proxy = ApiProxy.create({ services: [] })
-    proxyServer = await Http.createServer(proxy.listener)
-    const res = await fetch(`${proxyServer.url}/discover/unknown.md`)
-    expect(res.status).toBe(404)
-  })
-
-  test('behavior: GET /discover/:id returns 404 for unknown', async () => {
-    const proxy = ApiProxy.create({ services: [] })
-    proxyServer = await Http.createServer(proxy.listener)
-    const res = await fetch(`${proxyServer.url}/discover/unknown`)
-    expect(res.status).toBe(404)
   })
 
   test('behavior: returns 404 for unknown service', async () => {

package/src/proxy/Proxy.ts

@@ -1,5 +1,8 @@
 import type * as http from 'node:http'
+
 import { createFetchProxy } from '@remix-run/fetch-proxy'
+
+import { generateProxy } from '../discovery/OpenApi.js'
 import * as Request from '../server/Request.js'
 import * as Headers from './internal/Headers.js'
 import * as Route from './internal/Route.js'
@@ -53,6 +56,24 @@ export function create(config: create.Config): Proxy {
     }),
   )
 
+  // Pre-generate static discovery responses once at startup.
+  const openApiJson = JSON.stringify(
+    generateProxy({
+      basePath: config.basePath,
+      info: {
+        title: config.title ?? 'API Proxy',
+        version: config.version ?? '1.0.0',
+      },
+      routes: buildDiscoveryRoutes(config.services),
+      serviceInfo: buildServiceInfo(config),
+    }),
+  )
+  const llmsTxt = Service.toLlmsTxt(config.services, {
+    title: config.title,
+    description: config.description,
+    openApiPath: withBasePath(config.basePath, '/openapi.json'),
+  })
+
   async function handle(request: globalThis.Request): Promise<Response> {
     const url = new URL(request.url)
 
@@ -60,68 +81,22 @@ export function create(config: create.Config): Proxy {
 
     if (!pathname) return new Response('Not Found', { status: 404 })
 
-    if (request.method === 'GET' && pathname === '/llms.txt')
-      return new Response(
-        Service.toLlmsTxt(config.services, {
-          title: config.title,
-          description: config.description,
-        }),
-        { headers: { 'Content-Type': 'text/plain; charset=utf-8' } },
-      )
-
-    if (request.method === 'GET' && pathname === '/discover.md')
-      return new Response(
-        Service.toLlmsTxt(config.services, {
-          title: config.title,
-          description: config.description,
-        }),
-        { headers: { 'Content-Type': 'text/plain; charset=utf-8' } },
-      )
-
-    if (request.method === 'GET' && (pathname === '/discover' || pathname === '/discover/')) {
-      if (wantsMarkdown(request))
-        return new Response(
-          Service.toLlmsTxt(config.services, {
-            title: config.title,
-            description: config.description,
-          }),
-          { headers: { 'Content-Type': 'text/plain; charset=utf-8' } },
-        )
-      return Response.json(config.services.map(Service.serialize))
-    }
-
     if (
       request.method === 'GET' &&
-      (pathname === '/discover/all' || pathname === '/discover/all/')
+      (pathname === '/openapi.json' || pathname === '/openapi.json/')
     ) {
-      if (wantsMarkdown(request))
-        return new Response(Service.toServicesMarkdown(config.services), {
-          headers: { 'Content-Type': 'text/markdown; charset=utf-8' },
-        })
-      return Response.json(config.services.map(Service.serialize))
-    }
-
-    if (request.method === 'GET' && pathname === '/discover/all.md')
-      return new Response(Service.toServicesMarkdown(config.services), {
-        headers: { 'Content-Type': 'text/markdown; charset=utf-8' },
+      return new Response(openApiJson, {
+        headers: {
+          'Cache-Control': 'public, max-age=300',
+          'Content-Type': 'application/json',
+        },
       })
-
-    {
-      // List service
-      const match =
-        pathname.match(/^\/discover\/([^/]+)\.md$/) ?? pathname.match(/^\/discover\/([^/]+)\/?$/)
-      if (request.method === 'GET' && match) {
-        const service = config.services.find((s) => s.id === match[1])
-        if (!service) return new Response('Not Found', { status: 404 })
-        const wantsText = pathname.endsWith('.md') || wantsMarkdown(request)
-        if (wantsText)
-          return new Response(Service.toMarkdown(service), {
-            headers: { 'Content-Type': 'text/markdown; charset=utf-8' },
-          })
-        return Response.json(Service.serialize(service))
-      }
     }
 
+    if (request.method === 'GET' && pathname === '/llms.txt')
+      return new Response(llmsTxt, {
+        headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+      })
     const parsed = Route.parse(pathname)
     if (!parsed) return new Response('Not Found', { status: 404 })
 
@@ -175,14 +150,20 @@ export declare namespace create {
   export type Config = {
     /** Base path prefix to strip before routing (e.g. `'/api/proxy'`). */
     basePath?: string | undefined
+    /** Free-form categories for root discovery metadata. */
+    categories?: string[] | undefined
     /** Short description of the proxy shown in `llms.txt`. */
     description?: string | undefined
+    /** Structured documentation links for root discovery metadata. */
+    docs?: Service.Docs | undefined
     /** Custom `fetch` implementation. Defaults to `globalThis.fetch`. */
     fetch?: typeof globalThis.fetch | undefined
     /** Services to proxy. Each service is mounted at `/{serviceId}/`. */
     services: Service.Service[]
     /** Human-readable title for the proxy shown in `llms.txt`. */
     title?: string | undefined
+    /** Version to include in the generated OpenAPI document. */
+    version?: string | undefined
   }
 }
 
@@ -228,41 +209,40 @@ async function proxyUpstream(options: proxyUpstream.Options): Promise<Response>
   return upstreamRes
 }
 
-const aiUserAgents = [
-  'GPTBot',
-  'OAI-SearchBot',
-  'ChatGPT-User',
-  'anthropic-ai',
-  'ClaudeBot',
-  'claude-web',
-  'PerplexityBot',
-  'Perplexity-User',
-  'Google-Extended',
-  'Googlebot',
-  'Bingbot',
-  'Amazonbot',
-  'Applebot',
-  'Applebot-Extended',
-  'FacebookBot',
-  'meta-externalagent',
-  'Bytespider',
-  'DuckAssistBot',
-  'cohere-ai',
-  'AI2Bot',
-  'CCBot',
-  'Diffbot',
-  'YouBot',
-  'MistralAI-User',
-  'GoogleAgent-Mariner',
-]
-
-const terminalUserAgents = ['curl', 'Wget', 'HTTPie', 'httpie-go', 'mppx', 'presto', 'xh']
-
-function wantsMarkdown(request: globalThis.Request): boolean {
-  const accept = request.headers.get('accept')
-  if (accept && (accept.includes('text/markdown') || accept.includes('text/plain'))) return true
-  const ua = request.headers.get('user-agent') ?? ''
-  if (aiUserAgents.some((agent) => ua.includes(agent))) return true
-  if (terminalUserAgents.some((agent) => ua.includes(agent))) return true
-  return false
+function buildDiscoveryRoutes(services: Service.Service[]) {
+  return services.flatMap((service) =>
+    Object.entries(service.routes).map(([pattern, endpoint]) => {
+      const tokens = pattern.trim().split(/\s+/)
+      const hasMethod = tokens.length >= 2
+      const path = hasMethod ? tokens.slice(1).join(' ') : tokens[0]
+      return {
+        method: hasMethod ? tokens[0]! : 'GET',
+        path: `/${service.id}${path}`,
+        payment: endpoint ? Service.paymentOf(endpoint) : null,
+      }
+    }),
+  )
+}
+
+function buildServiceInfo(config: create.Config): { categories?: string[]; docs?: Service.Docs } {
+  const categories =
+    config.categories ??
+    Array.from(new Set(config.services.flatMap((service) => service.categories ?? [])))
+
+  const docs = {
+    ...(config.docs ?? {}),
+    llms: config.docs?.llms ?? withBasePath(config.basePath, '/llms.txt'),
+  }
+
+  return {
+    ...(categories.length > 0 ? { categories } : {}),
+    docs,
+  }
+}
+
+function withBasePath(basePath: string | undefined, path: string) {
+  if (!basePath) return path
+  const normalized = basePath.startsWith('/') ? basePath : `/${basePath}`
+  const trimmed = normalized.endsWith('/') ? normalized.slice(0, -1) : normalized
+  return `${trimmed}${path}`
 }

package/src/proxy/Service.test.ts

@@ -1,4 +1,5 @@
-import { describe, expect, test } from 'vitest'
+import { describe, expect, test } from 'vp/test'
+
 import * as Service from './Service.js'
 
 describe('from', () => {
@@ -101,6 +102,28 @@ describe('custom', () => {
   })
 })
 
+describe('paymentOf', () => {
+  test('behavior: returns null for free passthrough endpoint', () => {
+    expect(Service.paymentOf(true)).toBeNull()
+  })
+
+  test('behavior: returns null for paid handler without _internal metadata', () => {
+    const handler: Service.IntentHandler = async () => ({
+      status: 200 as const,
+      withReceipt: <T>(r: T) => r,
+    })
+    expect(Service.paymentOf(handler)).toBeNull()
+  })
+
+  test('behavior: returns null for paid endpoint object without _internal metadata', () => {
+    const handler: Service.IntentHandler = async () => ({
+      status: 200 as const,
+      withReceipt: <T>(r: T) => r,
+    })
+    expect(Service.paymentOf({ pay: handler, options: {} })).toBeNull()
+  })
+})
+
 describe('getOptions', () => {
   test('behavior: returns options from endpoint object', () => {
     const handler: Service.IntentHandler = async () => ({