mppx 0.8.17 → 0.8.18

package/src/discovery/OpenApi.ts

@@ -1,192 +0,0 @@
-import type * as Method from '../Method.js'
-import * as PaymentRequest from '../PaymentRequest.js'
-import { PaymentInfo, type ServiceInfo } from './Discovery.js'
-import * as Metadata from './internal/Metadata.js'
-
-/** Payment handler carrying metadata used to generate discovery documents. */
-export type DiscoveryHandler = ((...args: any[]) => unknown) & {
-  _internal?: Metadata.Metadata
-}
-
-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'] = PaymentInfo.parse(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: {
-        offers: Metadata.offers(internal).map(Metadata.paymentOffer),
-      },
-      ...(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(', ')}`,
-    )
-  }
-
-  const { description, ...options } = route.options
-  const metadata: Metadata.Offer = {
-    _canonicalRequest: PaymentRequest.fromMethod(mi, options as never),
-    ...(typeof description === 'string' ? { description } : {}),
-    intent: mi.intent,
-    name: mi.name,
-  }
-
-  return {
-    method: route.method,
-    path: route.path,
-    payment: Metadata.paymentOffer(metadata),
-    ...(route.requestBody ? { requestBody: route.requestBody } : {}),
-    ...(route.summary ? { summary: route.summary } : {}),
-  }
-}
-
-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}`
-}

package/src/discovery/Validate.test.ts

@@ -1,305 +0,0 @@
-import { validate } from './Validate.js'
-
-function makeDoc(overrides: Record<string, unknown> = {}) {
-  return {
-    info: { title: 'Test', version: '1.0.0' },
-    openapi: '3.1.0',
-    paths: {
-      '/search': {
-        post: {
-          'x-payment-info': {
-            amount: '100',
-            intent: 'charge',
-            method: 'tempo',
-          },
-          requestBody: {
-            content: { 'application/json': { schema: { type: 'object' } } },
-          },
-          responses: {
-            '200': { description: 'OK' },
-            '402': { description: 'Payment Required' },
-          },
-        },
-      },
-    },
-    ...overrides,
-  }
-}
-
-describe('validate', () => {
-  test('returns no errors for a valid document', () => {
-    const errors = validate(makeDoc())
-    expect(errors.filter((error) => error.severity === 'error')).toHaveLength(0)
-  })
-
-  test('accepts offers-based x-payment-info', () => {
-    const errors = validate(
-      makeDoc({
-        paths: {
-          '/search': {
-            post: {
-              'x-payment-info': {
-                offers: [{ amount: '100', intent: 'charge', method: 'tempo' }],
-              },
-              requestBody: {
-                content: { 'application/json': { schema: { type: 'object' } } },
-              },
-              responses: {
-                '200': { description: 'OK' },
-                '402': { description: 'Payment Required' },
-              },
-            },
-          },
-        },
-      }),
-    )
-
-    expect(errors.filter((error) => error.severity === 'error')).toHaveLength(0)
-  })
-
-  test('returns error for missing 402 response', () => {
-    const errors = validate(
-      makeDoc({
-        paths: {
-          '/search': {
-            post: {
-              'x-payment-info': {
-                amount: '100',
-                intent: 'charge',
-                method: 'tempo',
-              },
-              requestBody: {},
-              responses: {
-                '200': { description: 'OK' },
-              },
-            },
-          },
-        },
-      }),
-    )
-
-    expect(errors.find((error) => error.severity === 'error')?.message).toContain('402')
-  })
-
-  test('returns warning for missing requestBody', () => {
-    const errors = validate(
-      makeDoc({
-        paths: {
-          '/search': {
-            post: {
-              'x-payment-info': {
-                amount: '100',
-                intent: 'charge',
-                method: 'tempo',
-              },
-              responses: {
-                '200': { description: 'OK' },
-                '402': { description: 'Payment Required' },
-              },
-            },
-          },
-        },
-      }),
-    )
-
-    expect(errors.find((error) => error.severity === 'warning')?.message).toContain('requestBody')
-  })
-
-  test('returns structural errors for invalid top-level document', () => {
-    const errors = validate({ openapi: '3.1.0' })
-    expect(errors.length).toBeGreaterThan(0)
-    expect(errors[0]!.severity).toBe('error')
-  })
-
-  test('returns errors for invalid extension values', () => {
-    const errors = validate(
-      makeDoc({
-        'x-service-info': {
-          docs: { homepage: 'not-a-uri' },
-        },
-        paths: {
-          '/search': {
-            post: {
-              'x-payment-info': {
-                amount: '01',
-                intent: 'subscribe',
-                method: 'tempo',
-              },
-              responses: {
-                '402': { description: 'Payment Required' },
-              },
-            },
-          },
-        },
-      }),
-    )
-
-    expect(errors.some((error) => error.severity === 'error')).toBe(true)
-  })
-
-  test('returns errors for mixed shorthand and offers shapes', () => {
-    const errors = validate(
-      makeDoc({
-        paths: {
-          '/search': {
-            post: {
-              'x-payment-info': {
-                amount: '100',
-                offers: [{ amount: '100', intent: 'charge', method: 'tempo' }],
-              },
-              requestBody: {
-                content: { 'application/json': { schema: { type: 'object' } } },
-              },
-              responses: {
-                '200': { description: 'OK' },
-                '402': { description: 'Payment Required' },
-              },
-            },
-          },
-        },
-      }),
-    )
-
-    expect(errors).toContainEqual(
-      expect.objectContaining({
-        message: 'Cannot mix offers with flat payment info fields',
-        path: 'paths./search.post.x-payment-info',
-        severity: 'error',
-      }),
-    )
-  })
-
-  test('returns errors for empty offers arrays', () => {
-    const errors = validate(
-      makeDoc({
-        paths: {
-          '/search': {
-            post: {
-              'x-payment-info': {
-                offers: [],
-              },
-              requestBody: {
-                content: { 'application/json': { schema: { type: 'object' } } },
-              },
-              responses: {
-                '200': { description: 'OK' },
-                '402': { description: 'Payment Required' },
-              },
-            },
-          },
-        },
-      }),
-    )
-
-    expect(errors).toContainEqual(
-      expect.objectContaining({
-        path: 'paths./search.post.x-payment-info.offers',
-        severity: 'error',
-      }),
-    )
-  })
-
-  test('returns errors for malformed offers', () => {
-    const errors = validate(
-      makeDoc({
-        paths: {
-          '/search': {
-            post: {
-              'x-payment-info': {
-                offers: [{ amount: '01', intent: 'charge', method: 'tempo' }],
-              },
-              requestBody: {
-                content: { 'application/json': { schema: { type: 'object' } } },
-              },
-              responses: {
-                '200': { description: 'OK' },
-                '402': { description: 'Payment Required' },
-              },
-            },
-          },
-        },
-      }),
-    )
-
-    expect(errors).toContainEqual(
-      expect.objectContaining({
-        path: 'paths./search.post.x-payment-info.offers.0.amount',
-        severity: 'error',
-      }),
-    )
-  })
-
-  test('ignores path-item-level fields like summary and parameters', () => {
-    const errors = validate(
-      makeDoc({
-        paths: {
-          '/search': {
-            summary: 'Search endpoints',
-            parameters: [{ name: 'q', in: 'query' }],
-            'x-custom': 'value',
-            post: {
-              'x-payment-info': {
-                amount: '100',
-                intent: 'charge',
-                method: 'tempo',
-              },
-              requestBody: {
-                content: { 'application/json': { schema: { type: 'object' } } },
-              },
-              responses: {
-                '200': { description: 'OK' },
-                '402': { description: 'Payment Required' },
-              },
-            },
-          },
-        },
-      }),
-    )
-
-    expect(errors.filter((e) => e.severity === 'error')).toHaveLength(0)
-  })
-
-  test('validates proxy-generated docs with relative llms path', () => {
-    const errors = validate({
-      info: { title: 'API Proxy', version: '1.0.0' },
-      openapi: '3.1.0',
-      paths: {},
-      'x-service-info': {
-        categories: ['gateway'],
-        docs: {
-          apiReference: 'https://example.com/api',
-          homepage: 'https://example.com',
-          llms: '/llms.txt',
-        },
-      },
-    })
-
-    expect(errors.filter((e) => e.severity === 'error')).toHaveLength(0)
-  })
-
-  test('accepts x-payment-info with unknown fields', () => {
-    const errors = validate({
-      info: { title: 'Test', version: '1.0.0' },
-      openapi: '3.1.0',
-      paths: {
-        '/api/call': {
-          post: {
-            'x-payment-info': {
-              price: '0.54',
-              pricingMode: 'fixed',
-              protocols: ['x402', 'mpp'],
-            },
-            requestBody: {
-              content: { 'application/json': { schema: { type: 'object' } } },
-            },
-            responses: {
-              '200': { description: 'OK' },
-              '402': { description: 'Payment Required' },
-            },
-          },
-        },
-      },
-    })
-    expect(errors.filter((e) => e.severity === 'error')).toHaveLength(0)
-  })
-})

package/src/discovery/Validate.ts

@@ -1,77 +0,0 @@
-import { DiscoveryDocument, PaymentInfo } from './Discovery.js'
-
-export type ValidationError = {
-  message: string
-  path: string
-  severity: 'error' | 'warning'
-}
-
-/**
- * Validates a discovery document structurally and semantically.
- */
-export function validate(doc: unknown): ValidationError[] {
-  const errors: ValidationError[] = []
-
-  const result = DiscoveryDocument.safeParse(doc)
-  if (!result.success) {
-    for (const issue of result.error.issues) {
-      errors.push({
-        message: issue.message,
-        path: issue.path.map(String).join('.') || '(root)',
-        severity: 'error',
-      })
-    }
-    return errors
-  }
-
-  const parsed = result.data
-  const paths = parsed.paths
-  if (!paths) return errors
-
-  for (const [pathKey, pathItem] of Object.entries(paths)) {
-    for (const [method, operation] of Object.entries(pathItem as Record<string, unknown>)) {
-      if (!operation || typeof operation !== 'object' || Array.isArray(operation)) continue
-      const op = operation as Record<string, unknown>
-
-      const opPath = `paths.${pathKey}.${method}`
-      const rawPaymentInfo = op['x-payment-info']
-      if (!rawPaymentInfo) continue
-
-      const paymentResult = PaymentInfo.safeParse(rawPaymentInfo)
-      if (!paymentResult.success) {
-        for (const issue of paymentResult.error.issues) {
-          const issuePath = issue.path.length > 0 ? `.${issue.path.map(String).join('.')}` : ''
-          errors.push({
-            message: issue.message,
-            path: `${opPath}.x-payment-info${issuePath}`,
-            severity: 'error',
-          })
-        }
-        continue
-      }
-
-      const responses = op.responses as Record<string, unknown> | undefined
-      if (!responses || !('402' in responses)) {
-        errors.push({
-          message: 'Operation with x-payment-info MUST have a 402 response',
-          path: `${opPath}.responses`,
-          severity: 'error',
-        })
-      }
-
-      const methodUpper = method.toUpperCase()
-      if (
-        !op.requestBody &&
-        (methodUpper === 'POST' || methodUpper === 'PUT' || methodUpper === 'PATCH')
-      ) {
-        errors.push({
-          message: 'Operation with x-payment-info has no requestBody',
-          path: opPath,
-          severity: 'warning',
-        })
-      }
-    }
-  }
-
-  return errors
-}

package/src/discovery/index.ts

@@ -1,3 +0,0 @@
-export * from './Discovery.js'
-export * from './OpenApi.js'
-export * from './Validate.js'

package/src/discovery/internal/Metadata.ts

@@ -1,51 +0,0 @@
-/** Metadata retained by one explicitly configured payment handler. */
-export type Offer = {
-  _canonicalRequest: Record<string, unknown>
-  description?: string | undefined
-  intent: string
-  name: string
-}
-
-/** Metadata retained by a single or composed payment handler. */
-export type Metadata = Offer | { offers: readonly Offer[] }
-
-/** Returns every explicitly configured offer from discovery metadata. */
-export function offers(metadata: Metadata): readonly Offer[] {
-  if (isComposed(metadata)) return metadata.offers
-  return [metadata]
-}
-
-/** Converts configured handler metadata into a discovery payment offer. */
-export function paymentOffer(metadata: Offer): Record<string, unknown> {
-  const { _canonicalRequest: request, intent, name: method } = metadata
-  const methodDetails = (request.methodDetails ?? {}) as Record<string, unknown>
-
-  const amount = pickString(request.amount) ?? pickString(methodDetails.amount) ?? null
-  const currency = pickString(request.currency) ?? pickString(methodDetails.currency)
-  const description = pickString(metadata.description) ?? pickString(request.description)
-
-  const offer: Record<string, unknown> = {
-    amount,
-    ...(currency ? { currency } : {}),
-    ...(description ? { description } : {}),
-    intent,
-    method,
-  }
-
-  // Preserve extension fields emitted by method request schemas.
-  const reserved = new Set(['amount', 'currency', 'description', 'methodDetails'])
-  for (const [key, value] of Object.entries(request)) {
-    if (!reserved.has(key) && value !== undefined) offer[key] = value
-  }
-
-  return offer
-}
-
-/** Returns whether metadata represents a composed handler. */
-export function isComposed(metadata: Metadata): metadata is Extract<Metadata, { offers: unknown }> {
-  return 'offers' in metadata && !('_canonicalRequest' in metadata)
-}
-
-function pickString(value: unknown) {
-  return typeof value === 'string' ? value : undefined
-}

package/src/env.d.ts

@@ -1,12 +0,0 @@
-/// <reference types="vite/client" />
-
-interface ImportMetaEnv {
-  readonly MODE: 'test' | 'production'
-  readonly VITE_TEMPO_NETWORK: 'localnet' | 'moderato' | 'devnet'
-  readonly VITE_HTTP_LOG: 'true' | 'false'
-  readonly VITE_RPC_CREDENTIALS: string
-}
-
-interface ImportMeta {
-  readonly env: ImportMetaEnv
-}

package/src/evm/Assets.ts

@@ -1 +0,0 @@
-export * from '../x402/Assets.js'

package/src/evm/Chains.ts

@@ -1,11 +0,0 @@
-/** Base mainnet EVM chain ID. */
-export const base = 8453
-
-/** Base Sepolia testnet EVM chain ID. */
-export const baseSepolia = 84532
-
-/** Celo mainnet EVM chain ID. */
-export const celo = 42220
-
-/** Celo Sepolia testnet EVM chain ID. */
-export const celoSepolia = 11142220

package/src/evm/Methods.ts

@@ -1,44 +0,0 @@
-import { getAddress, parseUnits } from 'viem'
-
-import * as Method from '../Method.js'
-import * as z from '../zod.js'
-import * as Types from './Types.js'
-
-/** Native Payment-auth EVM charge method. */
-export const charge = Method.from({
-  name: Types.paymentMethod,
-  intent: Types.chargeIntent,
-  schema: {
-    credential: {
-      payload: Types.ChargePayloadSchema,
-    },
-    request: z.pipe(
-      Types.ChargeRequestInputSchema,
-      z.transform(
-        ({
-          amount,
-          chainId,
-          credentialTypes = ['authorization'],
-          currency,
-          decimals,
-          permit2Address,
-          recipient,
-          splits,
-          ...request
-        }) => ({
-          ...request,
-          amount: parseUnits(amount, decimals).toString(),
-          currency: getAddress(currency),
-          methodDetails: {
-            chainId,
-            credentialTypes,
-            decimals,
-            ...(permit2Address ? { permit2Address: getAddress(permit2Address) } : {}),
-            ...(splits ? { splits } : {}),
-          },
-          recipient: getAddress(recipient),
-        }),
-      ),
-    ),
-  },
-})