mppx 0.4.9 → 0.4.10

package/src/middlewares/internal/mppx.ts

@@ -1,13 +1,16 @@
+import type { DiscoveryHandler } from '../../discovery/OpenApi.js'
 import type * as Method from '../../Method.js'
 import type * as Mppx from '../../server/Mppx.js'
 
 export type AnyMethodFn = Mppx.AnyMethodFn
 export type AnyServer = Method.AnyServer
 
+type DiscoveryMeta = Pick<DiscoveryHandler, '_internal'>
+
 /** Recursively wraps nested handler objects one level deep. */
 type WrapNested<obj, handler> = {
   [key in keyof obj]: obj[key] extends (options: infer options) => any
-    ? (o: options) => handler
+    ? (o: options) => handler & DiscoveryMeta
     : obj[key]
 }
 
@@ -21,7 +24,7 @@ export type Wrap<mppx, handler> = {
     | 'transport'
     ? mppx[key]
     : mppx[key] extends (options: infer options) => any
-      ? (o: options) => handler
+      ? (o: options) => handler & DiscoveryMeta
       : mppx[key] extends Record<string, (options: any) => any>
         ? WrapNested<mppx[key], handler>
         : mppx[key]
@@ -43,14 +46,19 @@ export function wrap<mppx extends Mppx.Mppx<any, any>, handler>(
   for (const mi of mppx.methods as readonly Method.AnyServer[]) {
     const key = `${mi.name}/${mi.intent}`
     const methodFn = (mppx as any)[key]
-    result[key] = (options: any) => wrapper(methodFn, options)
+    const wrapWithMeta = (options: any) => {
+      const configured = methodFn(options)
+      const handler = wrapper(methodFn, options) as any
+      if (configured._internal) handler._internal = configured._internal
+      return handler
+    }
+    result[key] = wrapWithMeta
     // Also set shorthand intent key if Mppx registered it (no collision)
-    if ((mppx as any)[mi.intent]) result[mi.intent] = (options: any) => wrapper(methodFn, options)
+    if ((mppx as any)[mi.intent]) result[mi.intent] = wrapWithMeta
     // Build nested handlers: wrapped.tempo.charge(...)
     if (!result[mi.name] || typeof result[mi.name] !== 'object')
       result[mi.name] = {} as Record<string, unknown>
-    ;(result[mi.name] as Record<string, unknown>)[mi.intent] = (options: any) =>
-      wrapper(methodFn, options)
+    ;(result[mi.name] as Record<string, unknown>)[mi.intent] = wrapWithMeta
   }
   return result as never
 }

package/src/middlewares/nextjs.test.ts

@@ -2,11 +2,11 @@ import * as http from 'node:http'
 
 import { Receipt } from 'mppx'
 import { Mppx as Mppx_client, session as sessionIntent, tempo as tempo_client } from 'mppx/client'
-import { Mppx } from 'mppx/nextjs'
+import { Mppx, discovery } from 'mppx/nextjs'
 import { 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'
 
@@ -42,7 +42,7 @@ describe('charge', () => {
       tempo_server.charge({
         getClient: () => client,
         currency: asset,
-        recipient: accounts[0].address,
+        account: accounts[0],
       }),
     ],
     secretKey,
@@ -89,6 +89,31 @@ describe('charge', () => {
 
     server.close()
   })
+
+  test('serves /openapi.json from a handler-derived route config', async () => {
+    const pay = mppx.charge({ amount: '1' })
+    const server = await createServer(
+      discovery(mppx, {
+        info: { title: 'Next API', version: '3.0.0' },
+        routes: [{ handler: pay, method: 'get', path: '/' }],
+      }),
+    )
+
+    const response = await globalThis.fetch(server.url)
+    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: 'Next API', version: '3.0.0' })
+    expect(body.paths['/'].get['x-payment-info']).toMatchObject({
+      amount: '1000000',
+      currency: asset,
+      intent: 'charge',
+      method: 'tempo',
+    })
+
+    server.close()
+  })
 })
 
 describe('session', () => {
@@ -105,7 +130,7 @@ describe('session', () => {
       methods: [
         tempo_server.session({
           getClient: () => client,
-          recipient: accounts[0].address,
+          account: accounts[0],
           currency: asset,
           escrowContract,
         }),
@@ -130,10 +155,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,

package/src/middlewares/nextjs.ts

@@ -1,3 +1,4 @@
+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'
 
@@ -64,3 +65,30 @@ export function payment<const intent extends Mppx_internal.AnyMethodFn>(
     return result.withReceipt(response)
   }
 }
+
+export type DiscoveryConfig = Omit<GenerateConfig, 'routes'> & {
+  routes?: RouteConfig[]
+}
+
+const discoveryHeaders = { 'Cache-Control': 'public, max-age=300' }
+
+/**
+ * Creates a route handler that serves an OpenAPI discovery document.
+ */
+export function discovery(
+  mppx: { methods: readonly Mppx_internal.AnyServer[]; realm: string },
+  config: DiscoveryConfig = {},
+): RouteHandler {
+  const cached = JSON.stringify(
+    generate(mppx, {
+      ...(config.info ? { info: config.info } : {}),
+      routes: config.routes ?? [],
+      ...(config.serviceInfo ? { serviceInfo: config.serviceInfo } : {}),
+    }),
+  )
+
+  return () =>
+    new Response(cached, {
+      headers: { ...discoveryHeaders, 'Content-Type': 'application/json' },
+    })
+}

package/src/proxy/Proxy.test.ts

@@ -1,7 +1,7 @@
 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'
 
@@ -65,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' }),
@@ -84,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.',
@@ -186,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(`
@@ -198,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' }),
           },
         }),
@@ -219,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`)
+    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')
-    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' },
-    })
-    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 () => {