mppx 0.4.9 → 0.4.11

package/src/client/Transport.test.ts

@@ -1,7 +1,7 @@
 import { Challenge, Credential, Mcp } from 'mppx'
 import { Transport } from 'mppx/client'
 import { Methods } from 'mppx/tempo'
-import { describe, expect, test } from 'vitest'
+import { describe, expect, test } from 'vp/test'
 
 const realm = 'api.example.com'
 const secretKey = 'test-secret-key'

package/src/client/internal/Fetch.browser.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test, vi } from 'vitest'
+import { describe, expect, test, vi } from 'vp/test'
 
 import * as Fetch from './Fetch.js'
 

package/src/client/internal/Fetch.test-d.ts

@@ -1,5 +1,5 @@
 import type { Account } from 'viem'
-import { describe, expectTypeOf, test } from 'vitest'
+import { describe, expectTypeOf, test } from 'vp/test'
 
 import { charge } from '../../tempo/client/Charge.js'
 import * as Fetch from './Fetch.js'

package/src/client/internal/Fetch.test.ts

@@ -2,7 +2,7 @@ import { Receipt } from 'mppx'
 import { tempo } from 'mppx/client'
 import { Mppx as Mppx_server, tempo as tempo_server } from 'mppx/server'
 import { createClient, defineChain } from 'viem'
-import { describe, expect, test, vi } from 'vitest'
+import { describe, expect, test, vi } from 'vp/test'
 import * as Http from '~test/Http.js'
 import { rpcUrl } from '~test/tempo/prool.js'
 import { accounts, asset, chain, client, http } from '~test/tempo/viem.js'
@@ -16,6 +16,7 @@ const server = Mppx_server.create({
   methods: [
     tempo_server({
       getClient: () => client,
+      account: accounts[0],
     }),
   ],
   realm,

package/src/discovery/Discovery.test.ts

@@ -0,0 +1,152 @@
+import { DiscoveryDocument, PaymentInfo, ServiceInfo } from './Discovery.js'
+
+describe('PaymentInfo', () => {
+  test('parses a valid charge payment info', () => {
+    const result = PaymentInfo.safeParse({
+      amount: '1000',
+      intent: 'charge',
+      method: 'tempo',
+    })
+    expect(result.success).toBe(true)
+    expect(result.data).toEqual({ amount: '1000', intent: 'charge', method: 'tempo' })
+  })
+
+  test('parses a session with null amount', () => {
+    const result = PaymentInfo.safeParse({
+      amount: null,
+      intent: 'session',
+      method: 'tempo',
+    })
+    expect(result.success).toBe(true)
+    expect(result.data?.amount).toBeNull()
+  })
+
+  test('accepts custom intents', () => {
+    const result = PaymentInfo.safeParse({
+      amount: '100',
+      intent: 'subscribe',
+      method: 'tempo',
+    })
+    expect(result.success).toBe(true)
+    expect(result.data?.intent).toBe('subscribe')
+  })
+
+  test('rejects invalid amount pattern', () => {
+    const result = PaymentInfo.safeParse({
+      amount: '01',
+      intent: 'charge',
+      method: 'tempo',
+    })
+    expect(result.success).toBe(false)
+  })
+
+  test('accepts x402 format with unknown fields', () => {
+    const result = PaymentInfo.safeParse({
+      price: '0.54',
+      pricingMode: 'fixed',
+      protocols: ['x402', 'mpp'],
+    })
+    expect(result.success).toBe(true)
+  })
+})
+
+describe('ServiceInfo', () => {
+  test('parses a full service info', () => {
+    const result = ServiceInfo.safeParse({
+      categories: ['ai', 'search'],
+      docs: {
+        apiReference: 'https://example.com/api',
+        homepage: 'https://example.com',
+        llms: 'https://example.com/llms.txt',
+      },
+    })
+    expect(result.success).toBe(true)
+    expect(result.data?.categories).toEqual(['ai', 'search'])
+  })
+
+  test('accepts relative paths for doc links', () => {
+    const result = ServiceInfo.safeParse({
+      docs: {
+        llms: '/llms.txt',
+        apiReference: '/docs/api',
+      },
+    })
+    expect(result.success).toBe(true)
+    expect(result.data?.docs?.llms).toBe('/llms.txt')
+  })
+
+  test('rejects invalid doc URIs', () => {
+    const result = ServiceInfo.safeParse({
+      docs: {
+        homepage: 'not-a-uri',
+      },
+    })
+    expect(result.success).toBe(false)
+  })
+})
+
+describe('DiscoveryDocument', () => {
+  test('parses a minimal document', () => {
+    const result = DiscoveryDocument.safeParse({
+      info: { title: 'Test', version: '1.0.0' },
+      openapi: '3.1.0',
+    })
+    expect(result.success).toBe(true)
+  })
+
+  test('parses a document with discovery extensions', () => {
+    const result = DiscoveryDocument.safeParse({
+      info: { title: 'Test', version: '1.0.0' },
+      openapi: '3.1.0',
+      paths: {
+        '/search': {
+          post: {
+            'x-payment-info': {
+              amount: '100',
+              intent: 'charge',
+              method: 'tempo',
+            },
+            responses: {
+              '200': { description: 'OK' },
+              '402': { description: 'Payment Required' },
+            },
+          },
+        },
+      },
+      'x-service-info': {
+        categories: ['search'],
+      },
+    })
+    expect(result.success).toBe(true)
+  })
+
+  test('accepts path items with summary, parameters, and extensions', () => {
+    const result = DiscoveryDocument.safeParse({
+      info: { title: 'Test', version: '1.0.0' },
+      openapi: '3.1.0',
+      paths: {
+        '/search': {
+          summary: 'Search endpoints',
+          parameters: [{ name: 'q', in: 'query' }],
+          'x-custom': 'hello',
+          post: {
+            'x-payment-info': {
+              amount: '100',
+              intent: 'charge',
+              method: 'tempo',
+            },
+            responses: { '402': { description: 'Payment Required' } },
+          },
+        },
+      },
+    })
+    expect(result.success).toBe(true)
+  })
+
+  test('rejects missing info', () => {
+    const result = DiscoveryDocument.safeParse({
+      openapi: '3.1.0',
+    })
+    expect(result.success).toBe(false)
+  })
+})

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",
+              },
+            },
+          },
+        },
+      }
+    `)
+  })
+})