mppx 0.6.31 → 0.8.0

package/src/mcp-sdk/client/McpClient.ts

@@ -1,196 +0,0 @@
-import type { Client } from '@modelcontextprotocol/sdk/client/index.js'
-import type { McpError } from '@modelcontextprotocol/sdk/types.js'
-
-import type * as Challenge from '../../Challenge.js'
-import * as Credential from '../../Credential.js'
-import * as Expires from '../../Expires.js'
-import * as AcceptPayment from '../../internal/AcceptPayment.js'
-import * as core_Mcp from '../../Mcp.js'
-import type * as Method from '../../Method.js'
-import type * as z from '../../zod.js'
-
-type AnyClient = Method.Client<any, any>
-
-/**
- * Result of a tool call with payment handling.
- * Extends the SDK's callTool return type with an optional payment receipt.
- */
-export type CallToolResult = Awaited<ReturnType<Client['callTool']>> & {
-  /** Payment receipt if payment was made. */
-  receipt: core_Mcp.Receipt | undefined
-}
-
-/**
- * Creates a payment-aware wrapper around an MCP SDK client.
- *
- * Similar to `Fetch.from()` for HTTP, this wraps an MCP client's `callTool`
- * method to automatically handle payment challenges.
- *
- * @example
- * ```ts
- * import { Client } from '@modelcontextprotocol/sdk/client'
- * import { McpClient, tempo } from 'mppx/mcp-sdk/client'
- * import { privateKeyToAccount } from 'viem/accounts'
- *
- * const client = new Client({ name: 'my-client', version: '1.0.0' })
- * await client.connect(transport)
- *
- * const mcp = McpClient.wrap(client, {
- *   methods: [
- *     tempo({
- *       account: privateKeyToAccount('0x...'),
- *     }),
- *   ],
- * })
- *
- * // Automatically handles payment challenges
- * const result = await mcp.callTool({ name: 'premium_tool', arguments: {} })
- * console.log(result.content, result.receipt)
- * ```
- */
-export function wrap<
-  const client extends Pick<Client, 'callTool'>,
-  const methods extends readonly Method.AnyClient[],
->(client: client, config: wrap.Config<methods>): wrap.McpClient<client, methods> {
-  const { methods } = config
-  const paymentPreferences = AcceptPayment.resolve(methods)
-
-  return {
-    ...client,
-    async callTool(params, options) {
-      const context = options?.context
-      const timeout = options?.timeout
-
-      try {
-        const result = await client.callTool(
-          params,
-          undefined,
-          timeout !== undefined ? { timeout } : undefined,
-        )
-
-        return {
-          ...result,
-          receipt: result._meta?.[core_Mcp.receiptMetaKey] as core_Mcp.Receipt | undefined,
-        }
-      } catch (error) {
-        // Check if this is a payment required error
-        if (!isPaymentRequiredError(error)) throw error
-
-        const challenges = (error.data as { challenges?: Challenge.Challenge[] })?.challenges
-        if (!challenges?.length) throw error
-
-        const selected = AcceptPayment.selectChallenge(
-          challenges,
-          methods,
-          paymentPreferences.entries,
-        )
-        if (!selected) {
-          const available = challenges.map((c) => `${c.method}.${c.intent}`).join(', ')
-          const installed = methods.map((m) => `${m.name}.${m.intent}`).join(', ')
-          throw new Error(
-            `No compatible payment method. Server offers: ${available}. Client has: ${installed}`,
-            { cause: error },
-          )
-        }
-
-        const credential = await createCredential(selected.challenge, {
-          context,
-          methods,
-        })
-        const parsed = Credential.deserialize(credential)
-
-        const retryResult = await client.callTool(
-          {
-            ...params,
-            _meta: {
-              ...params._meta,
-              [core_Mcp.credentialMetaKey]: parsed,
-            },
-          },
-          undefined,
-          timeout !== undefined ? { timeout } : undefined,
-        )
-
-        return {
-          ...retryResult,
-          receipt: retryResult._meta?.[core_Mcp.receiptMetaKey] as core_Mcp.Receipt | undefined,
-        }
-      }
-    },
-  }
-}
-
-/** Union of all context types from all methods that have context schemas. */
-type AnyContextFor<methods extends readonly AnyClient[]> = {
-  [key in keyof methods]: methods[key] extends Method.Client<any, infer context>
-    ? context extends z.ZodMiniType
-      ? z.input<context>
-      : undefined
-    : undefined
-}[number]
-
-export declare namespace wrap {
-  type Config<methods extends readonly Method.AnyClient[] = readonly Method.AnyClient[]> = {
-    /** Array of methods to use. */
-    methods: methods
-  }
-
-  type McpClient<
-    client extends Pick<Client, 'callTool'> = Pick<Client, 'callTool'>,
-    methods extends readonly AnyClient[] = readonly AnyClient[],
-  > = Omit<client, 'callTool'> & {
-    /** Call a tool with automatic payment handling. */
-    callTool: (
-      params: {
-        name: string
-        arguments?: Record<string, unknown>
-        _meta?: Record<string, unknown>
-      },
-      options?: CallToolOptions<methods>,
-    ) => Promise<CallToolResult>
-  }
-
-  type CallToolOptions<methods extends readonly AnyClient[] = readonly AnyClient[]> = {
-    /** Context to pass to the method intent's createCredential. */
-    context?: AnyContextFor<methods>
-    /** Request timeout in milliseconds. */
-    timeout?: number
-  }
-}
-
-/**
- * Checks if an error is a payment required error.
- */
-export function isPaymentRequiredError(
-  error: unknown,
-): error is McpError & { data: { challenges: Challenge.Challenge[] } } {
-  if (typeof error !== 'object' || error === null) return false
-  if (!('code' in error) || !('message' in error)) return false
-  if ((error as { code: unknown }).code !== core_Mcp.paymentRequiredCode) return false
-  const data = (error as { data?: { challenges?: unknown } }).data
-  return Array.isArray(data?.challenges) && data.challenges.length > 0
-}
-
-/** @internal */
-async function createCredential<methods extends readonly Method.AnyClient[]>(
-  challenge: Challenge.Challenge,
-  config: {
-    context?: unknown
-    methods: methods
-  },
-): Promise<string> {
-  const { context, methods } = config
-
-  const mi = methods.find((m) => m.name === challenge.method && m.intent === challenge.intent)
-  if (!mi)
-    throw new Error(
-      `No method found for "${challenge.method}.${challenge.intent}". Available: ${methods.map((m) => `${m.name}.${m.intent}`).join(', ')}`,
-    )
-
-  if (challenge.expires) Expires.assert(challenge.expires, challenge.id)
-
-  const parsedContext = mi.context && context !== undefined ? mi.context.parse(context) : undefined
-  return mi.createCredential(
-    parsedContext !== undefined ? { challenge, context: parsedContext } : ({ challenge } as never),
-  )
-}

package/src/tempo/session/ChannelStore.ts

@@ -1,308 +0,0 @@
-import type { Address, Hex } from 'viem'
-
-import type * as Store from '../../Store.js'
-import type { SignedVoucher } from './Types.js'
-
-/**
- * State for an on-chain payment channel, including per-session accounting.
- *
- * Tracks the channel's identity, on-chain balance, the highest voucher
- * the server has accepted, and the current session's spend counters.
- * A channel is created when a payer opens an escrow on-chain and persists
- * until the channel is finalized (closed/settled).
- *
- * One channel = one session. The client owns the key and can't race with
- * itself, so concurrent session support is unnecessary.
- *
- * Monotonicity invariants (enforced by update callbacks):
- * - `highestVoucherAmount` only increases
- * - `settledOnChain` only increases
- * - `deposit` reflects the latest on-chain value
- */
-export interface State {
-  /** Address authorized to sign vouchers on behalf of the payer. */
-  authorizedSigner: Address
-  /** Chain ID the channel was opened on. */
-  chainId: number
-  /** Escrow contract address the channel was opened on. */
-  escrowContract: Address
-  /** Unique identifier for this payment channel. */
-  channelId: Hex
-  /** On-chain timestamp when a force-close was requested (0n if not requested). */
-  closeRequestedAt: bigint
-  /** ISO 8601 timestamp when the channel was created. */
-  createdAt: string
-  /** Current on-chain deposit in the escrow contract. */
-  deposit: bigint
-  /** Whether the channel has been finalized (closed) on-chain. */
-  finalized: boolean
-  /** The signed voucher corresponding to `highestVoucherAmount`. */
-  highestVoucher: SignedVoucher | null
-  /** Highest cumulative voucher amount accepted by the server. */
-  highestVoucherAmount: bigint
-  /** Address of the payment recipient. */
-  payee: Address
-  /** Address of the payment sender. */
-  payer: Address
-  /** Cumulative amount settled on-chain so far. */
-  settledOnChain: bigint
-  /** Cumulative amount spent (charged) against this channel's current session. */
-  spent: bigint
-  /** Token contract address used for payments. */
-  token: Address
-  /** Number of charge operations (API requests) fulfilled in the current session. */
-  units: number
-}
-
-/**
- * Internal store interface for channel state persistence.
- *
- * ## Atomicity contract
- *
- * The `updateChannel` method uses an atomic read-modify-write callback.
- * The callback receives the current state (or `null` if none exists), and
- * returns the next state (or `null` to delete). Implementations must
- * guarantee that no concurrent mutation occurs between reading `current`
- * and writing the return value.
- *
- * Callbacks should be synchronous and deterministic. When a `ChannelStore`
- * is backed by `Store.update()`, adapters may retry them internally.
- *
- * Backends implement this via their native mechanisms:
- * - **In-memory / JS single-thread**: Synchronous callback execution
- * - **Durable Objects**: Single-threaded execution model
- * - **D1 / SQL**: Database transactions
- */
-export type ChannelStore = {
-  getChannel(channelId: Hex): Promise<State | null>
-
-  /**
-   * Atomic read-modify-write for channel state.
-   * Return `null` from `fn` to delete the channel.
-   */
-  updateChannel(channelId: Hex, fn: (current: State | null) => State | null): Promise<State | null>
-
-  /**
-   * Wait for the next update to a channel.
-   *
-   * Returns a `Promise` that resolves once `updateChannel` is called for
-   * `channelId`. Implementations should resolve immediately if the channel
-   * was updated between the call to `waitForUpdate` and the `Promise`
-   * being awaited.
-   *
-   * When not implemented, callers fall back to polling.
-   */
-  waitForUpdate?(channelId: Hex): Promise<void>
-
-  /**
-   * Atomic read-modify-write that returns the callback's `result` directly.
-   *
-   * Used by {@link deductFromChannel} to atomically compute the deduction
-   * outcome. When backed by `Store.update()`, this delegates to the store's
-   * native atomic primitive.
-   */
-  updateChannelResult?<result>(
-    channelId: Hex,
-    fn: (current: State | null) => Store.Change<State, result>,
-  ): Promise<result>
-}
-
-export type DeductResult = { ok: true; channel: State } | { ok: false; channel: State }
-
-export function normalizeChannelId(channelId: Hex): Hex {
-  return channelId.toLowerCase() as Hex
-}
-
-function normalizeState(channelId: Hex, state: State): State {
-  return state.channelId === channelId ? state : { ...state, channelId }
-}
-
-function normalizeMaybeState(channelId: Hex, state: State | null): State | null {
-  return state ? normalizeState(channelId, state) : null
-}
-
-/**
- * Atomically deduct `amount` from a channel's available balance.
- *
- * Returns `{ ok: true, channel }` if the deduction succeeded, or
- * `{ ok: false, channel }` with the unchanged state if balance is
- * insufficient. Throws if the channel does not exist.
- */
-export async function deductFromChannel(
-  store: ChannelStore,
-  channelId: Hex,
-  amount: bigint,
-): Promise<DeductResult> {
-  if (store.updateChannelResult) {
-    const result = await store.updateChannelResult<DeductResult | null>(
-      channelId,
-      (current): Store.Change<State, DeductResult | null> => {
-        if (!current) return { op: 'noop', result: null }
-        if (current.finalized)
-          return { op: 'noop', result: { ok: false, channel: current } as const }
-        if (current.closeRequestedAt !== 0n)
-          return { op: 'noop', result: { ok: false, channel: current } as const }
-        if (current.highestVoucherAmount - current.spent >= amount) {
-          const next = { ...current, spent: current.spent + amount, units: current.units + 1 }
-          return { op: 'set', value: next, result: { ok: true, channel: next } as const }
-        }
-        return { op: 'noop', result: { ok: false, channel: current } as const }
-      },
-    )
-    if (!result) throw new Error('channel not found')
-    return result
-  }
-
-  let result: DeductResult | null = null
-  const channel = await store.updateChannel(channelId, (current) => {
-    if (!current) return null
-    if (current.finalized) {
-      result = { ok: false, channel: current }
-      return current
-    }
-    if (current.closeRequestedAt !== 0n) {
-      result = { ok: false, channel: current }
-      return current
-    }
-    if (current.highestVoucherAmount - current.spent >= amount) {
-      const next = { ...current, spent: current.spent + amount, units: current.units + 1 }
-      result = { ok: true, channel: next }
-      return next
-    }
-    result = { ok: false, channel: current }
-    return current
-  })
-  if (!channel) throw new Error('channel not found')
-  return result ?? { ok: false, channel }
-}
-
-/**
- * Wraps a generic {@link Store} into the internal {@link Store}
- * interface used by server handlers and the SSE metering loop.
- *
- * Provides `waitForUpdate` notifications so the SSE `chargeOrWait` loop
- * can wake up without polling.
- *
- * ## Atomicity
- *
- * Mutations use `get` → `fn` → `set` guarded by a per-key in-process
- * mutex. This serializes concurrent `updateChannel` calls within a
- * single JS runtime but does **not** protect against races across
- * multiple processes or instances.
- *
- * Backends that need true atomicity (e.g., Durable Objects, D1)
- * should implement {@link Store} directly.
- */
-const storeCache = new WeakMap<Store.Store, ChannelStore>()
-
-export function fromStore(store: Store.Store | Store.AtomicStore): ChannelStore {
-  const cached = storeCache.get(store)
-  if (cached) return cached
-
-  const atomicUpdate = 'update' in store ? (store as Store.AtomicStore).update : undefined
-
-  const waiters = new Map<string, Set<() => void>>()
-  const locks = new Map<string, Promise<void>>()
-
-  function notify(channelId: string) {
-    const set = waiters.get(channelId)
-    if (!set) return
-    for (const resolve of set) resolve()
-    waiters.delete(channelId)
-  }
-
-  async function update(
-    channelId: Hex,
-    fn: (current: State | null) => State | null,
-  ): Promise<State | null> {
-    return updateResult(channelId, (current) => {
-      const next = fn(current)
-      if (next) return { op: 'set', value: next, result: next }
-      return { op: 'delete', result: null }
-    })
-  }
-
-  async function updateResult<result>(
-    channelId: Hex,
-    fn: (current: State | null) => Store.Change<State, result>,
-  ): Promise<result> {
-    const normalizedChannelId = normalizeChannelId(channelId)
-    let change: Store.Change<State, result> | undefined
-
-    if (atomicUpdate) {
-      const result = await atomicUpdate(normalizedChannelId, (current) => {
-        change = fn(normalizeMaybeState(normalizedChannelId, (current as State | null) ?? null))
-        if (change.op === 'set') {
-          change = {
-            ...change,
-            value: normalizeState(normalizedChannelId, change.value),
-          }
-        }
-        if (change.op !== 'set') return change
-        return { ...change, value: change.value as never }
-      })
-      if (change?.op !== 'noop') notify(normalizedChannelId)
-      return result
-    }
-
-    while (locks.has(normalizedChannelId)) await locks.get(normalizedChannelId)
-
-    let release!: () => void
-    locks.set(
-      normalizedChannelId,
-      new Promise<void>((r) => {
-        release = r
-      }),
-    )
-
-    try {
-      const current = normalizeMaybeState(
-        normalizedChannelId,
-        (await store.get(normalizedChannelId)) as State | null,
-      )
-      change = fn(current)
-      if (change.op === 'set') {
-        change = {
-          ...change,
-          value: normalizeState(normalizedChannelId, change.value),
-        }
-        await store.put(normalizedChannelId, change.value as never)
-      }
-      if (change.op === 'delete') await store.delete(normalizedChannelId)
-      if (change.op !== 'noop') notify(normalizedChannelId)
-      return change.result
-    } finally {
-      locks.delete(normalizedChannelId)
-      release()
-    }
-  }
-
-  const cs: ChannelStore = {
-    async getChannel(channelId) {
-      const normalizedChannelId = normalizeChannelId(channelId)
-      return normalizeMaybeState(
-        normalizedChannelId,
-        (await store.get(normalizedChannelId)) as State | null,
-      )
-    },
-    async updateChannel(channelId, fn) {
-      return update(channelId, fn)
-    },
-    waitForUpdate(channelId) {
-      return new Promise<void>((resolve) => {
-        const normalizedChannelId = normalizeChannelId(channelId)
-        let set = waiters.get(normalizedChannelId)
-        if (!set) {
-          set = new Set()
-          waiters.set(normalizedChannelId, set)
-        }
-        set.add(resolve)
-      })
-    },
-  }
-
-  cs.updateChannelResult = updateResult
-
-  storeCache.set(store, cs)
-  return cs
-}

package/src/tempo/session/Receipt.test.ts

@@ -1,89 +0,0 @@
-import type { Hex } from 'viem'
-import { describe, expect, test } from 'vp/test'
-
-import {
-  createSessionReceipt,
-  deserializeSessionReceipt,
-  serializeSessionReceipt,
-} from './Receipt.js'
-
-const channelId = '0x0000000000000000000000000000000000000000000000000000000000000001' as Hex
-
-describe('Receipt', () => {
-  test('createSessionReceipt', () => {
-    const receipt = createSessionReceipt({
-      challengeId: 'test-challenge-id',
-      channelId,
-      acceptedCumulative: 5000000n,
-      spent: 3000000n,
-      units: 42,
-    })
-
-    expect(receipt.method).toBe('tempo')
-    expect(receipt.intent).toBe('session')
-    expect(receipt.status).toBe('success')
-    expect(receipt.reference).toBe(channelId)
-    expect(receipt.challengeId).toBe('test-challenge-id')
-    expect(receipt.channelId).toBe(channelId)
-    expect(receipt.acceptedCumulative).toBe('5000000')
-    expect(receipt.spent).toBe('3000000')
-    expect(receipt.units).toBe(42)
-    expect(receipt.timestamp).toBeTruthy()
-    expect(receipt.txHash).toBeUndefined()
-  })
-
-  test('createSessionReceipt with txHash', () => {
-    const txHash = '0xabcdef' as Hex
-    const receipt = createSessionReceipt({
-      challengeId: 'test-challenge-id',
-      channelId,
-      acceptedCumulative: 5000000n,
-      spent: 3000000n,
-      txHash,
-    })
-
-    expect(receipt.txHash).toBe(txHash)
-    expect(receipt.units).toBeUndefined()
-  })
-
-  test('createSessionReceipt omits optional fields when undefined', () => {
-    const receipt = createSessionReceipt({
-      challengeId: 'test-challenge-id',
-      channelId,
-      acceptedCumulative: 1000n,
-      spent: 0n,
-    })
-
-    expect('units' in receipt).toBe(false)
-    expect('txHash' in receipt).toBe(false)
-  })
-
-  test('serialize and deserialize round-trip', () => {
-    const receipt = createSessionReceipt({
-      challengeId: 'test-challenge-id',
-      channelId,
-      acceptedCumulative: 5000000n,
-      spent: 3000000n,
-      units: 42,
-    })
-
-    const encoded = serializeSessionReceipt(receipt)
-    expect(typeof encoded).toBe('string')
-
-    const decoded = deserializeSessionReceipt(encoded)
-    expect(decoded).toEqual(receipt)
-  })
-
-  test('serialize produces base64url without padding', () => {
-    const receipt = createSessionReceipt({
-      challengeId: 'test-challenge-id',
-      channelId,
-      acceptedCumulative: 1n,
-      spent: 0n,
-    })
-
-    const encoded = serializeSessionReceipt(receipt)
-    // base64url uses - and _ instead of + and /, no = padding
-    expect(encoded).not.toMatch(/[+/=]/)
-  })
-})

package/src/tempo/session/Receipt.ts

@@ -1,46 +0,0 @@
-import { Base64 } from 'ox'
-import type { Hex } from 'viem'
-
-import type { SessionReceipt } from './Types.js'
-
-/**
- * Create a session receipt.
- */
-export function createSessionReceipt(params: {
-  challengeId: string
-  channelId: Hex
-  acceptedCumulative: bigint
-  spent: bigint
-  units?: number | undefined
-  txHash?: Hex | undefined
-}): SessionReceipt {
-  return {
-    method: 'tempo',
-    intent: 'session',
-    status: 'success',
-    timestamp: new Date().toISOString(),
-    reference: params.channelId,
-    challengeId: params.challengeId,
-    channelId: params.channelId,
-    acceptedCumulative: params.acceptedCumulative.toString(),
-    spent: params.spent.toString(),
-    ...(params.units !== undefined && { units: params.units }),
-    ...(params.txHash !== undefined && { txHash: params.txHash }),
-  }
-}
-
-/**
- * Serialize a session receipt to the Payment-Receipt header format.
- */
-export function serializeSessionReceipt(receipt: SessionReceipt): string {
-  const json = JSON.stringify(receipt)
-  return Base64.fromString(json, { pad: false, url: true })
-}
-
-/**
- * Deserialize a Payment-Receipt header value to a session receipt.
- */
-export function deserializeSessionReceipt(encoded: string): SessionReceipt {
-  const json = Base64.toString(encoded)
-  return JSON.parse(json) as SessionReceipt
-}