mppx 0.8.9 → 0.8.12

package/src/cli/validate/discovery.test.ts

@@ -304,4 +304,132 @@ describe('extractRequestBodyFromDiscovery', () => {
     })
     expect(JSON.parse(body!)).toEqual({ model: 'gpt-4' })
   })
+
+  test('resolves $ref to components/schemas', () => {
+    const doc = {
+      paths: {
+        '/api/orders': {
+          post: {
+            requestBody: {
+              content: {
+                'application/json': {
+                  schema: { $ref: '#/components/schemas/OrderRequest' },
+                },
+              },
+            },
+          },
+        },
+      },
+      components: {
+        schemas: {
+          OrderRequest: {
+            type: 'object',
+            required: ['product', 'quantity'],
+            properties: {
+              product: { type: 'string', example: 'widget' },
+              quantity: { type: 'integer', minimum: 1 },
+            },
+          },
+        },
+      },
+    }
+    const body = extractRequestBodyFromDiscovery(doc as Record<string, unknown>, {
+      method: 'POST',
+      path: '/api/orders',
+    })
+    expect(JSON.parse(body!)).toEqual({ product: 'widget', quantity: 1 })
+  })
+
+  test('resolves nested $ref in properties', () => {
+    const doc = {
+      paths: {
+        '/api/orders': {
+          post: {
+            requestBody: {
+              content: {
+                'application/json': {
+                  schema: { $ref: '#/components/schemas/OrderRequest' },
+                },
+              },
+            },
+          },
+        },
+      },
+      components: {
+        schemas: {
+          OrderRequest: {
+            type: 'object',
+            required: ['customer'],
+            properties: {
+              customer: { $ref: '#/components/schemas/Customer' },
+            },
+          },
+          Customer: {
+            type: 'object',
+            required: ['name', 'email'],
+            properties: {
+              name: { type: 'string' },
+              email: { type: 'string', format: 'email' },
+            },
+          },
+        },
+      },
+    }
+    const body = extractRequestBodyFromDiscovery(doc as Record<string, unknown>, {
+      method: 'POST',
+      path: '/api/orders',
+    })
+    expect(JSON.parse(body!)).toEqual({ customer: { name: 'test', email: 'test@example.com' } })
+  })
+
+  test('uses first named example from examples map', () => {
+    const doc = {
+      paths: {
+        '/api/test': {
+          post: {
+            requestBody: {
+              content: {
+                'application/json': {
+                  examples: {
+                    basic: { value: { prompt: 'hello', model: 'gpt-4' } },
+                    advanced: { value: { prompt: 'complex', model: 'gpt-4', temp: 0.9 } },
+                  },
+                  schema: { type: 'object' },
+                },
+              },
+            },
+          },
+        },
+      },
+    }
+    const body = extractRequestBodyFromDiscovery(doc as Record<string, unknown>, {
+      method: 'POST',
+      path: '/api/test',
+    })
+    expect(JSON.parse(body!)).toEqual({ prompt: 'hello', model: 'gpt-4' })
+  })
+
+  test('returns undefined for unresolvable $ref', () => {
+    const doc = {
+      paths: {
+        '/api/test': {
+          post: {
+            requestBody: {
+              content: {
+                'application/json': {
+                  schema: { $ref: '#/components/schemas/DoesNotExist' },
+                },
+              },
+            },
+          },
+        },
+      },
+      components: { schemas: {} },
+    }
+    const body = extractRequestBodyFromDiscovery(doc as Record<string, unknown>, {
+      method: 'POST',
+      path: '/api/test',
+    })
+    expect(body).toBeUndefined()
+  })
 })

package/src/cli/validate/discovery.ts

@@ -77,10 +77,19 @@ export function extractRequestBodyFromDiscovery(
 
   if (jsonContent.example) return JSON.stringify(jsonContent.example)
 
-  const schema = jsonContent.schema as Record<string, unknown> | undefined
+  if (jsonContent.examples && typeof jsonContent.examples === 'object') {
+    const first = Object.values(jsonContent.examples as Record<string, unknown>)[0] as
+      | Record<string, unknown>
+      | undefined
+    if (first?.value) return JSON.stringify(first.value)
+  }
+
+  let schema = jsonContent.schema as Record<string, unknown> | undefined
+  const seen = new Set<string>()
+  schema = resolveRef(schema, doc, seen)
   if (!schema || schema.type !== 'object') return undefined
 
-  const result = generateValueFromSchema(schema)
+  const result = generateValueFromSchema(schema, doc, seen)
   if (result && typeof result === 'object' && Object.keys(result as object).length > 0) {
     return JSON.stringify(result)
   }
@@ -149,34 +158,60 @@ function substitutePathParams(path: string, params: PathParameter[]): string {
   })
 }
 
-function generateValueFromSchema(schema: Record<string, unknown>): unknown {
-  if (schema.const !== undefined) return schema.const
-  if (schema.example !== undefined) return schema.example
-  if (schema.default !== undefined) return schema.default
+// Dereferences a JSON Schema $ref (e.g. "#/components/schemas/Foo") against the root doc.
+function resolveRef(
+  schema: Record<string, unknown> | undefined,
+  doc: Record<string, unknown>,
+  seen?: Set<string>,
+): Record<string, unknown> | undefined {
+  if (!schema || typeof schema.$ref !== 'string') return schema
+  if (seen?.has(schema.$ref)) return undefined
+  const path = schema.$ref.replace(/^#\//, '').split('/')
+  let resolved: unknown = doc
+  for (const segment of path) {
+    if (resolved && typeof resolved === 'object') resolved = (resolved as any)[segment]
+    else return undefined
+  }
+  return resolved as Record<string, unknown> | undefined
+}
 
-  switch (schema.type) {
+// Generates a plausible value for a JSON Schema node (required fields only for objects).
+function generateValueFromSchema(
+  schema: Record<string, unknown>,
+  doc: Record<string, unknown>,
+  seen?: Set<string>,
+): unknown {
+  const resolved = resolveRef(schema, doc, seen) ?? schema
+  if (resolved.const !== undefined) return resolved.const
+  if (resolved.example !== undefined) return resolved.example
+  if (resolved.default !== undefined) return resolved.default
+
+  switch (resolved.type) {
     case 'string': {
-      if (schema.enum && Array.isArray(schema.enum)) return schema.enum[0]
-      if (schema.format === 'email') return 'test@example.com'
-      if (schema.format === 'uuid') return '00000000-0000-0000-0000-000000000000'
-      if (schema.format === 'uri' || schema.format === 'url') return 'https://example.com'
+      if (resolved.enum && Array.isArray(resolved.enum)) return resolved.enum[0]
+      if (resolved.format === 'email') return 'test@example.com'
+      if (resolved.format === 'uuid') return '00000000-0000-0000-0000-000000000000'
+      if (resolved.format === 'uri' || resolved.format === 'url') return 'https://example.com'
+      if (resolved.format === 'date') return '2026-01-01'
+      if (resolved.pattern === '^\\d{5}(?:-\\d{4})?$') return '10001'
+      if (resolved.pattern === '^[A-Z]{2}$') return 'US'
       return 'test'
     }
     case 'number':
     case 'integer':
-      return (schema.minimum as number) ?? 1
+      return (resolved.minimum as number) ?? 1
     case 'boolean':
       return true
     case 'array':
       return []
     case 'object': {
-      const properties = schema.properties as Record<string, Record<string, unknown>> | undefined
+      const properties = resolved.properties as Record<string, Record<string, unknown>> | undefined
       if (!properties) return {}
-      const required = (schema.required as string[]) || []
+      const required = (resolved.required as string[]) || []
       const obj: Record<string, unknown> = {}
       for (const key of required) {
         const prop = properties[key]
-        if (prop) obj[key] = generateValueFromSchema(prop)
+        if (prop) obj[key] = generateValueFromSchema(prop, doc, seen)
       }
       return obj
     }

package/src/cli/validate/helpers.ts

@@ -154,3 +154,13 @@ export function resolveBodyForEndpoint(
   } catch {}
   return rawBody
 }
+
+export function parseHeaders(raw: string[] | undefined): Record<string, string> {
+  if (!raw) return {}
+  const headers: Record<string, string> = {}
+  for (const h of raw) {
+    const idx = h.indexOf(':')
+    if (idx > 0) headers[h.slice(0, idx).trim().toLowerCase()] = h.slice(idx + 1).trim()
+  }
+  return headers
+}

package/src/cli/validate/index.ts

@@ -19,12 +19,14 @@ const validate = Cli.create('validate', {
         'Request body. With --endpoint, used directly. In discovery mode, JSON with / keys is a per-path mapping.',
       ),
     query: z.array(z.string()).optional().describe('Query parameter (key=value, repeatable)'),
+    header: z.array(z.string()).optional().describe('Request header (key:value, repeatable)'),
     verbose: z.number().default(0).meta({ count: true }).describe('Verbosity level'),
     yes: z.boolean().default(false).describe('Auto-approve mainnet payments'),
     outputJson: z.boolean().default(false).describe('Output results as JSON'),
   }),
   alias: {
     endpoint: 'e',
+    header: 'H',
     verbose: 'v',
     yes: 'y',
     outputJson: 'j',
@@ -37,6 +39,7 @@ const validate = Cli.create('validate', {
         endpoint: c.options.endpoint,
         body: c.options.body,
         query: c.options.query,
+        headers: c.options.header,
         verbose: c.options.verbose > 0,
         yes: c.options.yes,
         interactive: false,
@@ -66,6 +69,7 @@ const validate = Cli.create('validate', {
       endpoint: c.options.endpoint,
       body: c.options.body,
       query: c.options.query,
+      headers: c.options.header,
       verbose: c.options.verbose > 0,
       yes: c.options.yes,
       interactive: !!process.stdin.isTTY,

package/src/cli/validate/payment.ts

@@ -26,6 +26,7 @@ import {
   fetchWithTimeout,
   formatBytes,
   isValidIntegerAmount,
+  parseHeaders,
   skip,
   warn,
 } from './helpers.js'
@@ -129,6 +130,7 @@ export async function validatePaymentFlow(
   options: {
     body?: string | undefined
     query?: string[] | undefined
+    extraHeaders?: string[] | undefined
     yes?: boolean | undefined
     silent?: boolean | undefined
     interactive?: boolean | undefined
@@ -137,7 +139,7 @@ export async function validatePaymentFlow(
 ): Promise<CheckResult[]> {
   const results: CheckResult[] = []
   const url = buildUrl(baseUrl, endpoint, options.query)
-  const fetchHeaders: Record<string, string> = {}
+  const fetchHeaders: Record<string, string> = parseHeaders(options.extraHeaders)
   let fetchBody: string | undefined
   if (options.body) {
     fetchBody = options.body
@@ -293,6 +295,7 @@ type PaymentContext = {
   options: {
     body?: string | undefined
     query?: string[] | undefined
+    extraHeaders?: string[] | undefined
     yes?: boolean | undefined
     silent?: boolean | undefined
     interactive?: boolean | undefined

package/src/cli/validate.test.ts

@@ -1,12 +1,32 @@
 import type * as http from 'node:http'
 
-import { afterEach, describe, expect, test } from 'vp/test'
+import { afterEach, describe, expect, test, vi } from 'vp/test'
 import * as Http from '~test/Http.js'
 
 import * as Challenge from '../Challenge.js'
 import * as Constants from '../Constants.js'
 import * as Receipt from '../Receipt.js'
-import validate from './validate/index.js'
+
+// Keep CLI orchestration tests independent of the public Tempo RPC and faucet.
+vi.doMock('viem/tempo', async () => {
+  const actual = await vi.importActual<typeof import('viem/tempo')>('viem/tempo')
+  return {
+    ...actual,
+    Actions: {
+      ...actual.Actions,
+      faucet: { ...actual.Actions.faucet, fund: vi.fn(async () => []) },
+    },
+  }
+})
+
+vi.doMock('viem/actions', async () => {
+  const actual = await vi.importActual<typeof import('viem/actions')>('viem/actions')
+  return {
+    ...actual,
+    prepareTransactionRequest: vi.fn(async () => ({})),
+    signTransaction: vi.fn(async () => '0xdeadbeef'),
+  }
+})
 
 // Auto-cleanup for test servers
 const servers: Http.TestServer[] = []
@@ -22,6 +42,7 @@ async function testServer(handler: http.RequestListener) {
 }
 
 async function serve(argv: string[]) {
+  const { default: validate } = await import('./validate/index.js')
   let output = ''
   let exitCode: number | undefined
   const origLog = console.log

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

@@ -19,7 +19,9 @@ describe('Mppx', () => {
   test('exports low-level session method and explicit managed session helper', () => {
     expectTypeOf(session({ account: {} as Account })).toMatchTypeOf<Method.AnyClient>()
     expectTypeOf(session.manager({ account: {} as Account })).toHaveProperty('fetch')
-    expectTypeOf(sessionManager({ account: {} as Account })).toHaveProperty('fetch')
+    expectTypeOf(
+      sessionManager({ account: {} as Account, resolveAccount: ({ account }) => account }),
+    ).toHaveProperty('fetch')
     expectTypeOf(sessionMethod({ account: {} as Account })).toMatchTypeOf<Method.AnyClient>()
     expectTypeOf(tempo.session({ account: {} as Account })).toMatchTypeOf<Method.AnyClient>()
     expectTypeOf(tempo.session.manager({ account: {} as Account })).toHaveProperty('fetch')

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

@@ -10,6 +10,7 @@ import { rpcUrl } from '~test/tempo/rpc.js'
 import { accounts, asset, chain, client, http } from '~test/tempo/viem.js'
 
 import * as Fetch from './Fetch.js'
+import * as MethodResponse from './MethodResponse.js'
 
 const realm = 'api.example.com'
 const secretKey = 'test-secret-key-test-secret-key-32'
@@ -391,6 +392,34 @@ function encodeRawPaymentRequiredHeader(value: unknown): string {
   return Base64.fromString(JSON.stringify(value))
 }
 
+describe('Fetch.from: method responses', () => {
+  test('handles successful paid responses without touching free responses', async () => {
+    const method = { ...noopMethod }
+    const handle = vi.fn(
+      async ({ response }: MethodResponse.HandlerParameters) =>
+        new Response(`handled:${await response.text()}`, response),
+    )
+    MethodResponse.register(method, handle)
+
+    let paidResponse: Response | undefined
+    const mockFetch: typeof globalThis.fetch = async (input, init) => {
+      if (input.toString().endsWith('/free')) return new Response('free')
+      if (!new Headers(init?.headers).has('Authorization')) return make402()
+      paidResponse = new Response('paid')
+      vi.spyOn(paidResponse, 'clone')
+      return paidResponse
+    }
+    const fetch = Fetch.from({ fetch: mockFetch, methods: [method] })
+
+    expect(await (await fetch('https://example.com/free')).text()).toBe('free')
+    expect(handle).not.toHaveBeenCalled()
+    expect(await (await fetch('https://example.com/paid')).text()).toBe('handled:paid')
+    expect(handle).toHaveBeenCalledOnce()
+    expect(handle).toHaveBeenCalledWith(expect.objectContaining({ credential: 'credential' }))
+    expect(paidResponse?.clone).not.toHaveBeenCalled()
+  })
+})
+
 describe('Fetch.from: init passthrough (non-402)', () => {
   test('preserves init object identity while adding Accept-Payment', async () => {
     const receivedInits: (RequestInit | undefined)[] = []

package/src/client/internal/Fetch.ts

@@ -6,6 +6,7 @@ import type { MaybePromise } from '../../internal/types.js'
 import type * as Method from '../../Method.js'
 import type * as z from '../../zod.js'
 import * as Transport from '../Transport.js'
+import * as MethodResponse from './MethodResponse.js'
 
 // We tag wrappers with a global symbol so we can recognize wrappers created by mppx,
 // even across multiple module instances/bundles. This lets restore() avoid clobbering
@@ -18,6 +19,7 @@ type WrappedFetch = typeof globalThis.fetch & {
 }
 
 let originalFetch: typeof globalThis.fetch | undefined
+const eventObserverChecks = new WeakMap<object, (name: keyof ClientEventMap) => boolean>()
 
 export type ClientEventMap<
   methods extends readonly Method.AnyClient[] = readonly Method.AnyClient[],
@@ -174,7 +176,11 @@ export function from<const methods extends readonly Method.AnyClient[]>(
   // which can duplicate retries and make restore semantics fragile.
   const baseFetch = unwrapFetch(fetch)
 
-  const wrappedFetch = async (input: RequestInfo | URL, init?: from.RequestInit<methods>) => {
+  const request = async (
+    input: RequestInfo | URL,
+    init: from.RequestInit<methods> | undefined,
+    canRefetch: boolean,
+  ): Promise<Response> => {
     const callerHeaders = getCallerHeaders(input, init?.headers)
     const hasExplicitAcceptPayment = callerHeaders.has(Constants.Headers.acceptPayment)
     const paymentPreferences = resolvePaymentPreferences(callerHeaders, resolvedAcceptPayment)
@@ -272,8 +278,13 @@ export function from<const methods extends readonly Method.AnyClient[]>(
           }),
         )
 
+        const paymentInput = resolvePaymentRetryInput(
+          response,
+          initialRequest.input,
+          initialRequest.input,
+        )
         response = await baseFetch(
-          resolvePaymentRetryInput(response, initialRequest.input, initialRequest.input),
+          paymentInput,
           transport.setCredential(
             {
               ...fetchInit,
@@ -283,7 +294,8 @@ export function from<const methods extends readonly Method.AnyClient[]>(
             { challenge: selectedChallenge },
           ),
         )
-        if (response.ok)
+        // Cloning an unobserved stream would tee and buffer it indefinitely.
+        if (response.ok && hasEventObservers(events, 'payment.response'))
           await events.emit(
             'payment.response',
             createPaymentResponsePayload({
@@ -295,8 +307,23 @@ export function from<const methods extends readonly Method.AnyClient[]>(
               response,
             }),
           )
-        if (!(await transport.isPaymentRequired(response, transportRequest as never)))
-          return response
+        if (!(await transport.isPaymentRequired(response, transportRequest as never))) {
+          if (!response.ok) return response
+          return MethodResponse.handle(selected.method, {
+            challenge: selectedChallenge,
+            credential,
+            fetch: baseFetch,
+            headers: initialRequest.headers,
+            input: paymentInput,
+            ...(canRefetch
+              ? {
+                  refetch: () => request(cloneRequestInput(initialRequest.input), init, false),
+                }
+              : {}),
+            response,
+            signal: resolveRequestSignal(input, init),
+          })
+        }
       }
       return response
     } catch (error) {
@@ -315,6 +342,8 @@ export function from<const methods extends readonly Method.AnyClient[]>(
       throw error
     }
   }
+  const wrappedFetch = (input: RequestInfo | URL, init?: from.RequestInit<methods>) =>
+    request(input, init, true)
 
   // Record the wrapped target so future polyfill() / restore() calls can detect origin
   // and safely unwrap only mppx-installed wrappers.
@@ -491,7 +520,7 @@ export function createEventDispatcher<
     }
   }
 
-  return {
+  const dispatcher: ClientEventDispatcher<methods, response> = {
     async emit(name, payload) {
       switch (name) {
         case 'challenge.received': {
@@ -525,6 +554,15 @@ export function createEventDispatcher<
     },
     on,
   }
+  eventObserverChecks.set(
+    dispatcher,
+    (name) => handlers[name as keyof typeof handlers].size > 0 || handlers['*'].size > 0,
+  )
+  return dispatcher
+}
+
+function hasEventObservers(dispatcher: ClientEventDispatcher, name: keyof ClientEventMap): boolean {
+  return eventObserverChecks.get(dispatcher)?.(name) ?? true
 }
 
 async function emitChallengeReceived<methods extends readonly Method.AnyClient[], response>(
@@ -812,6 +850,13 @@ function cloneRequestInput(input: RequestInfo | URL): RequestInfo | URL {
   }
 }
 
+function resolveRequestSignal(
+  input: RequestInfo | URL,
+  init: RequestInit | undefined,
+): AbortSignal | undefined {
+  return init?.signal ?? (input instanceof Request ? input.signal : undefined)
+}
+
 /** @internal */
 function isWrappedFetch(fetch: typeof globalThis.fetch): fetch is WrappedFetch {
   return Boolean((fetch as WrappedFetch)[MPPX_FETCH_WRAPPER])

package/src/client/internal/MethodResponse.ts

@@ -0,0 +1,39 @@
+import type * as Challenge from '../../Challenge.js'
+import type { MaybePromise } from '../../internal/types.js'
+import type * as Method from '../../Method.js'
+
+const handlers = new WeakMap<Method.AnyClient, Handler>()
+
+/** Inputs available when a client method handles a successful paid response. */
+export type HandlerParameters = {
+  challenge: Challenge.Challenge
+  credential: string
+  fetch: typeof globalThis.fetch
+  headers: Headers
+  input: RequestInfo | URL
+  refetch?: (() => Promise<Response>) | undefined
+  response: Response
+  signal?: AbortSignal | undefined
+}
+
+/** Internal client-method response adapter. */
+export type Handler = (parameters: HandlerParameters) => MaybePromise<Response>
+
+/** Registers an internal response adapter without changing the public method shape. */
+export function register<const method extends Method.AnyClient>(
+  method: method,
+  handler: Handler,
+): method {
+  handlers.set(method, handler)
+  return method
+}
+
+/** Removes response handling from a method whose caller owns the response lifecycle. */
+export function unregister(method: Method.AnyClient): void {
+  handlers.delete(method)
+}
+
+/** Lets the selected client method handle a successful paid response. */
+export function handle(method: Method.AnyClient, parameters: HandlerParameters): Promise<Response> {
+  return Promise.resolve(handlers.get(method)?.(parameters) ?? parameters.response)
+}

package/src/tempo/PublicExports.test-d.ts

@@ -1,3 +1,4 @@
+import { tempo as serverTempo } from 'mppx/server'
 import { expectTypeOf, test } from 'vp/test'
 
 import type {
@@ -22,6 +23,7 @@ import type { SessionTransition as MachineSessionTransition } from './session/cl
 import type { ChannelTransactionOptions } from './session/precompile/Chain.js'
 import type { RawAmountString } from './session/precompile/index.js'
 import type { SettlementSchedule as SessionSettlementSchedule } from './session/server/index.js'
+import type { SessionController } from './session/server/Sse.js'
 
 test('tempo session public barrels expose manager and schedule interfaces', () => {
   expectTypeOf(Tempo.Session).toBeObject()
@@ -43,6 +45,8 @@ test('tempo session public barrels expose manager and schedule interfaces', () =
     units?: number | undefined
   }>()
   expectTypeOf<RawAmountString>().toEqualTypeOf<string>()
+  expectTypeOf<serverTempo.Sse.SessionController>().toEqualTypeOf<SessionController>()
+  expectTypeOf<Tempo.Session.Server.Sse.SessionController>().toEqualTypeOf<SessionController>()
   expectTypeOf<ActiveSessionState['status']>().toEqualTypeOf<'active'>()
   expectTypeOf<VoucherNeededSessionState['status']>().toEqualTypeOf<'voucherNeeded'>()
   expectTypeOf<ClosedSessionState['status']>().toEqualTypeOf<'closed'>()
@@ -83,6 +87,7 @@ test('tempo session public barrel hides internal session drivers', () => {
   expectTypeOf<SessionPublic>().not.toHaveProperty('settle')
   expectTypeOf<SessionClientPublic>().not.toHaveProperty('ChannelOps')
   expectTypeOf<SessionClientPublic>().not.toHaveProperty('Chain')
+  expectTypeOf<SessionClientPublic>().not.toHaveProperty('driveSseResponse')
   expectTypeOf<SessionServerPublic>().not.toHaveProperty('ChannelOps')
   expectTypeOf<SessionServerPublic>().not.toHaveProperty('Chain')
 })