mppx 0.4.8 → 0.4.10

package/src/cli/cli.ts

@@ -1,13 +1,17 @@
 import * as fs from 'node:fs'
 import { createRequire } from 'node:module'
 import * as path from 'node:path'
+
 import { Cli, Errors, z } from 'incur'
 import { Base64 } from 'ox'
 import { type Address, createClient, http } from 'viem'
 import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'
 import { tempo as tempoMainnet } from 'viem/chains'
+
 import * as Challenge from '../Challenge.js'
+import { normalizeHeaders } from '../client/internal/Fetch.js'
 import * as Mppx from '../client/Mppx.js'
+import { validate as validateDiscovery } from '../discovery/Validate.js'
 import { createDefaultStore, createKeychain, resolveAccountName } from './account.js'
 import { loadConfig, resolvePlugin } from './internal.js'
 import type { Plugin } from './plugins/plugin.js'
@@ -312,7 +316,7 @@ const cli = Cli.create('mppx', {
 
       // Send credential and get response
       const credentialHeaders = {
-        ...(init.headers as Record<string, string>),
+        ...normalizeHeaders(init.headers),
         Authorization: credential,
       }
       plugin?.prepareCredentialRequest?.({ challenge, credential, headers: credentialHeaders })
@@ -912,7 +916,168 @@ export default defineConfig({
   },
 })
 
+const discover = Cli.create('discover', {
+  description: 'Discovery tooling',
+})
+  .command('generate', {
+    description: 'Generate a static OpenAPI discovery document from a module',
+    args: z.object({
+      module: z.string().describe('Path to a module that default-exports a discovery config'),
+    }),
+    options: z.object({
+      output: z.string().optional().describe('Write output to a file instead of stdout'),
+    }),
+    alias: { output: 'o' },
+    async run(c) {
+      const modulePath = path.resolve(c.args.module)
+      if (!fs.existsSync(modulePath)) {
+        return c.error({
+          code: 'MODULE_NOT_FOUND',
+          message: `Module not found: ${modulePath}`,
+          exitCode: 1,
+        })
+      }
+
+      let mod: Record<string, unknown>
+      try {
+        mod = await import(modulePath)
+      } catch (error) {
+        return c.error({
+          code: 'MODULE_IMPORT_FAILED',
+          message: `Failed to import module: ${(error as Error).message}`,
+          exitCode: 1,
+        })
+      }
+
+      const exported = (mod.default ?? mod) as Record<string, unknown>
+
+      // If the export is already a plain OpenAPI doc (has `openapi` key), use it directly.
+      // Otherwise, expect { mppx, ...GenerateConfig } and call generate().
+      let doc: Record<string, unknown>
+      if (typeof exported.openapi === 'string') {
+        doc = exported
+      } else {
+        const { generate } = await import('../discovery/OpenApi.js')
+        const mppx = exported.mppx as { methods: readonly any[]; realm: string }
+        if (!mppx) {
+          return c.error({
+            code: 'INVALID_MODULE',
+            message:
+              'Module must default-export an OpenAPI document (with `openapi` key) or an object with `mppx` (server instance) and `routes`.',
+            exitCode: 1,
+          })
+        }
+        doc = generate(mppx, exported as any)
+      }
+
+      const json = JSON.stringify(doc, null, 2)
+      if (c.options.output) {
+        const outPath = path.resolve(c.options.output)
+        fs.writeFileSync(outPath, `${json}\n`)
+        process.stderr.write(`Wrote ${outPath}\n`)
+      } else {
+        console.log(json)
+      }
+    },
+  })
+  .command('validate', {
+    description: 'Validate an OpenAPI discovery document from a file or URL',
+    args: z.object({
+      input: z.string().describe('Path or URL to a discovery document'),
+    }),
+    async run(c) {
+      const input = c.args.input
+      let raw: string
+      if (/^https?:\/\//.test(input)) {
+        const controller = new AbortController()
+        const timeout = setTimeout(() => controller.abort(), 30_000)
+        let response: Response
+        try {
+          response = await globalThis.fetch(input, { signal: controller.signal })
+        } catch (error) {
+          clearTimeout(timeout)
+          const msg =
+            error instanceof DOMException && error.name === 'AbortError'
+              ? 'Request timed out after 30s'
+              : (error as Error).message
+          return c.error({
+            code: 'DISCOVERY_FETCH_FAILED',
+            message: `Failed to fetch discovery document: ${msg}`,
+            exitCode: 1,
+          })
+        }
+        clearTimeout(timeout)
+        if (!response.ok) {
+          return c.error({
+            code: 'DISCOVERY_FETCH_FAILED',
+            message: `Failed to fetch discovery document: HTTP ${response.status}`,
+            exitCode: 1,
+          })
+        }
+        const maxSize = 10 * 1024 * 1024 // 10 MB
+        const contentLength = response.headers.get('content-length')
+        if (contentLength && Number(contentLength) > maxSize) {
+          return c.error({
+            code: 'DISCOVERY_TOO_LARGE',
+            message: `Discovery document exceeds 10 MB limit`,
+            exitCode: 1,
+          })
+        }
+        raw = await response.text()
+        if (raw.length > maxSize) {
+          return c.error({
+            code: 'DISCOVERY_TOO_LARGE',
+            message: `Discovery document exceeds 10 MB limit`,
+            exitCode: 1,
+          })
+        }
+      } else {
+        const resolved = path.resolve(input)
+        if (!fs.existsSync(resolved)) {
+          return c.error({
+            code: 'DISCOVERY_NOT_FOUND',
+            message: `Discovery document not found: ${resolved}`,
+            exitCode: 1,
+          })
+        }
+        raw = fs.readFileSync(resolved, 'utf-8')
+      }
+
+      let doc: unknown
+      try {
+        doc = JSON.parse(raw)
+      } catch (error) {
+        return c.error({
+          code: 'DISCOVERY_INVALID_JSON',
+          message: `Invalid discovery JSON: ${(error as Error).message}`,
+          exitCode: 1,
+        })
+      }
+
+      const issues = validateDiscovery(doc)
+      for (const issue of issues) console.log(`[${issue.severity}] ${issue.path}: ${issue.message}`)
+
+      const errorCount = issues.filter((issue) => issue.severity === 'error').length
+      const warningCount = issues.filter((issue) => issue.severity === 'warning').length
+
+      if (errorCount > 0) {
+        return c.error({
+          code: 'DISCOVERY_INVALID',
+          message: `Discovery document has ${errorCount} error(s) and ${warningCount} warning(s).`,
+          exitCode: 1,
+        })
+      }
+
+      console.log(
+        warningCount > 0
+          ? `Discovery document is valid with ${warningCount} warning(s).`
+          : 'Discovery document is valid.',
+      )
+    },
+  })
+
 cli.command(account)
+cli.command(discover)
 cli.command(init)
 cli.command(sign)
 

package/src/cli/config.test.ts

@@ -1,6 +1,7 @@
 import * as fs from 'node:fs'
 import * as os from 'node:os'
 import * as path from 'node:path'
+
 import { defineConfig } from './config.js'
 import { loadConfig } from './internal.js'
 

package/src/cli/internal.ts

@@ -1,5 +1,6 @@
 import * as fs from 'node:fs'
 import * as path from 'node:path'
+
 import type * as Challenge from '../Challenge.js'
 import type * as Method from '../Method.js'
 import type { Config } from './config.js'

package/src/cli/plugins/stripe.ts

@@ -1,4 +1,5 @@
 import { Errors, z } from 'incur'
+
 import { stripe as stripeMethods } from '../../stripe/client/index.js'
 import { pc } from '../utils.js'
 import { createPlugin } from './plugin.js'

package/src/cli/plugins/tempo.ts

@@ -3,11 +3,14 @@ import * as fs from 'node:fs'
 import { createRequire } from 'node:module'
 import * as os from 'node:os'
 import * as path from 'node:path'
+
 import { Errors, z } from 'incur'
 import { Base64 } from 'ox'
 import type { Address } from 'viem'
 import { createClient, http } from 'viem'
 import { privateKeyToAccount } from 'viem/accounts'
+
+import { normalizeHeaders } from '../../client/internal/Fetch.js'
 import * as Credential from '../../Credential.js'
 import { tempo as tempoMethods } from '../../tempo/client/index.js'
 import type { SessionCredentialPayload } from '../../tempo/session/Types.js'
@@ -610,7 +613,7 @@ async function closeChannel(opts: {
   const closeRes = await globalThis.fetch(opts.fetchUrl, {
     ...opts.fetchInit,
     headers: {
-      ...(opts.fetchInit.headers as Record<string, string>),
+      ...normalizeHeaders(opts.fetchInit.headers),
       Authorization: closeCred,
     },
   })

package/src/cli/utils.ts

@@ -1,4 +1,5 @@
 import * as readline from 'node:readline'
+
 import type { Chain } from 'viem'
 import { type Address, createClient, http } from 'viem'
 import { tempo as tempoMainnet, tempoModerato } from 'viem/chains'

package/src/client/Mppx.test-d.ts

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

package/src/client/Mppx.test.ts

@@ -2,7 +2,7 @@ import { Challenge, Credential, Mcp, Method, Receipt } from 'mppx'
 import { Mppx, Transport, tempo } from 'mppx/client'
 import { Mppx as Mppx_server, tempo as tempo_server } from 'mppx/server'
 import { Methods } from 'mppx/tempo'
-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'
 

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,5 @@
-import { describe, expect, test, vi } from 'vitest'
+import { describe, expect, test, vi } from 'vp/test'
+
 import * as Fetch from './Fetch.js'
 
 const noopMethod = {

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

@@ -1,5 +1,6 @@
 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,10 +2,11 @@ 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'
+
 import * as Fetch from './Fetch.js'
 
 const realm = 'api.example.com'
@@ -15,6 +16,7 @@ const server = Mppx_server.create({
   methods: [
     tempo_server({
       getClient: () => client,
+      account: accounts[0],
     }),
   ],
   realm,

package/src/client/internal/Fetch.ts

@@ -193,7 +193,7 @@ export function restore(): void {
 }
 
 /** @internal Normalizes headers to a plain object for spreading. */
-function normalizeHeaders(headers: unknown): Record<string, string> {
+export function normalizeHeaders(headers: unknown): Record<string, string> {
   if (!headers) return {}
   if (headers instanceof Headers) {
     const result: Record<string, string> = {}

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>