mppx 0.0.1 → 0.1.0

package/src/tempo/client/Session.ts

@@ -0,0 +1,369 @@
+import type { Hex } from 'ox'
+import { type Address, parseUnits, type Account as viem_Account } from 'viem'
+import { tempo as tempo_chain } from 'viem/chains'
+import type * as Challenge from '../../Challenge.js'
+import * as MethodIntent from '../../MethodIntent.js'
+import * as Account from '../../viem/Account.js'
+import * as Client from '../../viem/Client.js'
+import * as z from '../../zod.js'
+import * as Intents from '../Intents.js'
+import * as defaults from '../internal/defaults.js'
+import type { StreamCredentialPayload } from '../stream/Types.js'
+import { signVoucher } from '../stream/Voucher.js'
+import {
+  type ChannelEntry,
+  createOpenPayload,
+  createVoucherPayload,
+  resolveEscrow,
+  serializeCredential,
+  tryRecoverChannel,
+} from './ChannelOps.js'
+
+export const streamContextSchema = z.object({
+  account: z.optional(z.custom<Account.getResolver.Parameters['account']>()),
+  action: z.optional(z.enum(['open', 'topUp', 'voucher', 'close'])),
+  channelId: z.optional(z.string()),
+  cumulativeAmount: z.optional(z.amount()),
+  cumulativeAmountRaw: z.optional(z.string()),
+  transaction: z.optional(z.string()),
+  authorizedSigner: z.optional(z.string()),
+  additionalDeposit: z.optional(z.amount()),
+  additionalDepositRaw: z.optional(z.string()),
+  depositRaw: z.optional(z.string()),
+})
+
+export type StreamContext = z.infer<typeof streamContextSchema>
+
+/**
+ * Creates a session payment MethodIntent plugin for use with `Mppx.create()`.
+ *
+ * Supports both auto mode (set `deposit` to manage channels automatically)
+ * and manual mode (pass `context.action` to control each step).
+ *
+ * @example
+ * ```ts
+ * // Auto mode
+ * import { Mppx, tempo } from 'mppx/client'
+ *
+ * const mppx = Mppx.create({
+ *   methods: [tempo({
+ *     account: privateKeyToAccount('0x...'),
+ *     deposit: '10',
+ *   })],
+ * })
+ *
+ * const res = await mppx.fetch('/api/chat?prompt=hello')
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Manual mode
+ * const mppx = Mppx.create({
+ *   methods: [tempo({ account })],
+ * })
+ *
+ * const credential = await mppx.createCredential(response, {
+ *   action: 'voucher',
+ *   channelId: '0x...',
+ *   cumulativeAmount: '1',
+ * })
+ * ```
+ */
+export function session(parameters: session.Parameters = {}) {
+  const { decimals = defaults.decimals } = parameters
+
+  const getClient = Client.getResolver({
+    chain: tempo_chain,
+    getClient: parameters.getClient,
+    rpcUrl: defaults.rpcUrl,
+  })
+  const getAccount = Account.getResolver({ account: parameters.account })
+
+  const maxDeposit =
+    parameters.maxDeposit !== undefined ? parseUnits(parameters.maxDeposit, decimals) : undefined
+
+  const escrowContractMap = new Map<string, Address>()
+  const channels = new Map<string, ChannelEntry>()
+  const channelIdToKey = new Map<string, string>()
+
+  function notifyUpdate(entry: ChannelEntry) {
+    parameters.onChannelUpdate?.(entry)
+  }
+
+  function channelKey(payee: Address, currency: Address, escrow: Address): string {
+    return `${payee.toLowerCase()}:${currency.toLowerCase()}:${escrow.toLowerCase()}`
+  }
+
+  function resolveEscrowCached(
+    challenge: { request: { methodDetails?: unknown } },
+    chainId: number,
+    channelId?: string,
+  ): Address {
+    if (channelId) {
+      const cached = escrowContractMap.get(channelId)
+      if (cached) return cached
+    }
+    return resolveEscrow(challenge, chainId, parameters.escrowContract)
+  }
+
+  async function autoManageCredential(
+    challenge: Challenge.Challenge,
+    account: viem_Account,
+    context?: StreamContext,
+  ): Promise<string> {
+    const md = challenge.request.methodDetails as
+      | { chainId?: number; escrowContract?: string; channelId?: string; feePayer?: boolean }
+      | undefined
+    const chainId = md?.chainId ?? 0
+    const client = await getClient({ chainId })
+    const escrowContract = resolveEscrowCached(challenge, chainId)
+    const payee = challenge.request.recipient as Address
+    const currency = challenge.request.currency as Address
+    const amount = BigInt(challenge.request.amount as string)
+
+    const suggestedDepositRaw = (challenge.request as { suggestedDeposit?: string })
+      .suggestedDeposit
+    const suggestedDeposit = suggestedDepositRaw ? BigInt(suggestedDepositRaw) : undefined
+
+    const deposit = (() => {
+      if (context?.depositRaw) return BigInt(context.depositRaw)
+      if (suggestedDeposit !== undefined && maxDeposit !== undefined)
+        return suggestedDeposit < maxDeposit ? suggestedDeposit : maxDeposit
+      if (suggestedDeposit !== undefined) return suggestedDeposit
+      if (maxDeposit !== undefined) return maxDeposit
+      if (parameters.deposit !== undefined) return parseUnits(parameters.deposit, decimals)
+      throw new Error(
+        'No deposit amount available. Set `deposit`, `maxDeposit`, or ensure the server challenge includes `suggestedDeposit`.',
+      )
+    })()
+
+    const key = channelKey(payee, currency, escrowContract)
+    let entry = channels.get(key)
+
+    if (!entry) {
+      const suggestedChannelId = (context?.channelId ?? md?.channelId) as Hex.Hex | undefined
+      if (suggestedChannelId) {
+        const recovered = await tryRecoverChannel(
+          client,
+          escrowContract,
+          suggestedChannelId,
+          chainId,
+        )
+        if (recovered) {
+          const contextCumulative = context?.cumulativeAmountRaw
+            ? BigInt(context.cumulativeAmountRaw)
+            : context?.cumulativeAmount
+              ? parseUnits(context.cumulativeAmount, decimals)
+              : undefined
+          if (contextCumulative !== undefined) recovered.cumulativeAmount = contextCumulative
+          channels.set(key, recovered)
+          channelIdToKey.set(recovered.channelId, key)
+          escrowContractMap.set(recovered.channelId, escrowContract)
+          entry = recovered
+          notifyUpdate(entry)
+        } else if (context?.channelId) {
+          throw new Error(
+            `Channel ${context.channelId} cannot be reused (closed or not found on-chain).`,
+          )
+        }
+      }
+    }
+
+    let payload: StreamCredentialPayload
+
+    if (entry?.opened) {
+      entry.cumulativeAmount += amount
+      payload = await createVoucherPayload(
+        client,
+        account,
+        entry.channelId,
+        entry.cumulativeAmount,
+        escrowContract,
+        chainId,
+        parameters.authorizedSigner,
+      )
+      notifyUpdate(entry)
+    } else {
+      const result = await createOpenPayload(client, account, {
+        authorizedSigner: parameters.authorizedSigner,
+        escrowContract,
+        payee,
+        currency,
+        deposit,
+        initialAmount: amount,
+        chainId,
+        feePayer: md?.feePayer,
+      })
+      channels.set(key, result.entry)
+      channelIdToKey.set(result.entry.channelId, key)
+      escrowContractMap.set(result.entry.channelId, escrowContract)
+      payload = result.payload
+      notifyUpdate(result.entry)
+    }
+
+    return serializeCredential(challenge, payload, chainId, account)
+  }
+
+  async function manualCredential(
+    challenge: Challenge.Challenge,
+    account: viem_Account,
+    context: StreamContext,
+  ): Promise<string> {
+    const md = challenge.request.methodDetails as
+      | { chainId?: number; escrowContract?: string; channelId?: string }
+      | undefined
+    const chainId = md?.chainId ?? 0
+    const client = await getClient({ chainId })
+
+    const action = context.action!
+    const { channelId: channelIdRaw, transaction, authorizedSigner } = context
+    const channelId = channelIdRaw as Hex.Hex
+    const cumulativeAmount = context.cumulativeAmountRaw
+      ? BigInt(context.cumulativeAmountRaw)
+      : context.cumulativeAmount
+        ? parseUnits(context.cumulativeAmount, decimals)
+        : undefined
+    const resolvedAdditionalDeposit = context.additionalDepositRaw
+      ? BigInt(context.additionalDepositRaw)
+      : context.additionalDeposit
+        ? parseUnits(context.additionalDeposit, decimals)
+        : undefined
+
+    const escrowContract = resolveEscrowCached(challenge, chainId, channelId)
+    escrowContractMap.set(channelId, escrowContract)
+
+    let payload: StreamCredentialPayload
+
+    switch (action) {
+      case 'open': {
+        if (!transaction) throw new Error('transaction required for open action')
+        if (cumulativeAmount === undefined)
+          throw new Error('cumulativeAmount required for open action')
+        const signature = await signVoucher(
+          client,
+          account,
+          { channelId, cumulativeAmount },
+          escrowContract,
+          chainId,
+          parameters.authorizedSigner,
+        )
+        payload = {
+          action: 'open',
+          type: 'transaction',
+          channelId,
+          transaction: transaction as Hex.Hex,
+          authorizedSigner: (authorizedSigner as Address) ?? account.address,
+          cumulativeAmount: cumulativeAmount.toString(),
+          signature,
+        }
+        break
+      }
+
+      case 'topUp':
+        if (!transaction) throw new Error('transaction required for topUp action')
+        if (resolvedAdditionalDeposit === undefined)
+          throw new Error('additionalDeposit required for topUp action')
+        payload = {
+          action: 'topUp',
+          type: 'transaction',
+          channelId,
+          transaction: transaction as Hex.Hex,
+          additionalDeposit: resolvedAdditionalDeposit.toString(),
+        }
+        break
+
+      case 'voucher': {
+        if (cumulativeAmount === undefined)
+          throw new Error('cumulativeAmount required for voucher action')
+        payload = await createVoucherPayload(
+          client,
+          account,
+          channelId,
+          cumulativeAmount,
+          escrowContract,
+          chainId,
+          parameters.authorizedSigner,
+        )
+        const key = channelIdToKey.get(channelId)
+        if (key) {
+          const entry = channels.get(key)
+          if (entry) {
+            entry.cumulativeAmount =
+              entry.cumulativeAmount > cumulativeAmount ? entry.cumulativeAmount : cumulativeAmount
+            notifyUpdate(entry)
+          }
+        }
+        break
+      }
+
+      case 'close': {
+        if (cumulativeAmount === undefined)
+          throw new Error('cumulativeAmount required for close action')
+        const signature = await signVoucher(
+          client,
+          account,
+          { channelId, cumulativeAmount },
+          escrowContract,
+          chainId,
+          parameters.authorizedSigner,
+        )
+        payload = {
+          action: 'close',
+          channelId,
+          cumulativeAmount: cumulativeAmount.toString(),
+          signature,
+        }
+        const closeKey = channelIdToKey.get(channelId)
+        if (closeKey) {
+          const entry = channels.get(closeKey)
+          if (entry) {
+            entry.opened = false
+            entry.cumulativeAmount =
+              entry.cumulativeAmount > cumulativeAmount ? entry.cumulativeAmount : cumulativeAmount
+            notifyUpdate(entry)
+          }
+        }
+        break
+      }
+    }
+
+    return serializeCredential(challenge, payload, chainId, account)
+  }
+
+  return MethodIntent.toClient(Intents.session, {
+    context: streamContextSchema,
+
+    async createCredential({ challenge, context }) {
+      const chainId = challenge.request.methodDetails?.chainId ?? 0
+      const client = await getClient({ chainId })
+      const account = getAccount(client, context)
+
+      if (!context?.action && (parameters.deposit !== undefined || maxDeposit !== undefined))
+        return autoManageCredential(challenge, account, context)
+
+      if (context?.action) return manualCredential(challenge, account, context)
+
+      throw new Error(
+        'No `action` in context and no `deposit` or `maxDeposit` configured. Either provide context with action/channelId/cumulativeAmount, or configure `deposit`/`maxDeposit` for auto-management.',
+      )
+    },
+  })
+}
+
+export declare namespace session {
+  type Parameters = Account.getResolver.Parameters &
+    Client.getResolver.Parameters & {
+      /** Address authorized to sign vouchers. Defaults to the account address. Use when a separate access key (e.g. secp256k1) signs vouchers while the root account funds the channel. */
+      authorizedSigner?: Address | undefined
+      /** Token decimals for parsing human-readable amounts (default: 6). */
+      decimals?: number | undefined
+      /** Initial deposit amount in human-readable units (e.g. "10" for 10 tokens). When set, the method handles the full channel lifecycle (open, voucher, cumulative tracking) automatically. */
+      deposit?: string | undefined
+      /** Escrow contract address override. Derived from challenge or defaults if not provided. */
+      escrowContract?: Address | undefined
+      /** Maximum deposit in human-readable units (e.g. "10"). Caps the server's `suggestedDeposit`. Enables auto-management like `deposit`. */
+      maxDeposit?: string | undefined
+      /** Called whenever channel state changes (open, voucher, close, recovery). */
+      onChannelUpdate?: ((entry: ChannelEntry) => void) | undefined
+    }
+}

package/src/tempo/client/SessionManager.test.ts

@@ -0,0 +1,223 @@
+import type { Hex } from 'viem'
+import { describe, expect, test, vi } from 'vitest'
+import * as Challenge from '../../Challenge.js'
+import { formatNeedVoucherEvent, parseEvent } from '../stream/Sse.js'
+import type { NeedVoucherEvent, StreamReceipt } from '../stream/Types.js'
+import { sessionManager } from './SessionManager.js'
+
+const channelId = '0x0000000000000000000000000000000000000000000000000000000000000001' as Hex
+const challengeId = 'test-challenge-1'
+const realm = 'test.example.com'
+
+function makeChallenge(overrides: Record<string, unknown> = {}): Challenge.Challenge {
+  return Challenge.from({
+    id: challengeId,
+    realm,
+    method: 'tempo',
+    intent: 'session',
+    request: {
+      amount: '1000000',
+      currency: '0x20c0000000000000000000000000000000000001',
+      recipient: '0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00',
+      decimals: 6,
+      methodDetails: {
+        escrowContract: '0x9d136eEa063eDE5418A6BC7bEafF009bBb6CFa70',
+        chainId: 4217,
+      },
+      ...overrides,
+    },
+  })
+}
+
+function make402Response(challenge?: Challenge.Challenge): Response {
+  const c = challenge ?? makeChallenge()
+  return new Response(null, {
+    status: 402,
+    headers: { 'WWW-Authenticate': Challenge.serialize(c) },
+  })
+}
+
+function makeOkResponse(body?: string): Response {
+  return new Response(body ?? 'ok', { status: 200 })
+}
+
+function makeSseResponse(events: string[]): Response {
+  const body = events.join('')
+  return new Response(body, {
+    status: 200,
+    headers: { 'Content-Type': 'text/event-stream' },
+  })
+}
+
+describe('Session', () => {
+  describe('parseEvent round-trip via SSE', () => {
+    test('parses message events from SSE stream', () => {
+      const raw = 'event: message\ndata: hello world\n\n'
+      const event = parseEvent(raw)
+      expect(event).toEqual({ type: 'message', data: 'hello world' })
+    })
+
+    test('parses payment-need-voucher events', () => {
+      const params: NeedVoucherEvent = {
+        channelId,
+        requiredCumulative: '6000000',
+        acceptedCumulative: '5000000',
+        deposit: '10000000',
+      }
+      const raw = formatNeedVoucherEvent(params)
+      const event = parseEvent(raw)
+      expect(event).toEqual({ type: 'payment-need-voucher', data: params })
+    })
+  })
+
+  describe('session creation', () => {
+    test('creates session with initial state', () => {
+      const s = sessionManager({
+        account: '0x0000000000000000000000000000000000000001',
+        maxDeposit: '10',
+      })
+
+      expect(s.channelId).toBeUndefined()
+      expect(s.cumulative).toBe(0n)
+      expect(s.opened).toBe(false)
+    })
+  })
+
+  describe('.fetch()', () => {
+    test('passes through non-402 responses', async () => {
+      const mockFetch = vi.fn().mockResolvedValue(makeOkResponse('hello'))
+
+      const s = sessionManager({
+        account: '0x0000000000000000000000000000000000000001',
+        fetch: mockFetch as typeof globalThis.fetch,
+      })
+
+      const res = await s.fetch('https://api.example.com/data')
+      expect(res.status).toBe(200)
+      expect(await res.text()).toBe('hello')
+      expect(mockFetch).toHaveBeenCalledOnce()
+    })
+
+    test('throws on 402 without maxDeposit or open channel', async () => {
+      const mockFetch = vi.fn().mockResolvedValue(make402Response())
+
+      const s = sessionManager({
+        account: '0x0000000000000000000000000000000000000001',
+        fetch: mockFetch as typeof globalThis.fetch,
+      })
+
+      await expect(s.fetch('https://api.example.com/data')).rejects.toThrow(
+        'no `deposit` or `maxDeposit` configured',
+      )
+    })
+  })
+
+  describe('.open()', () => {
+    test('throws when no challenge is available', async () => {
+      const s = sessionManager({
+        account: '0x0000000000000000000000000000000000000001',
+        maxDeposit: '10',
+      })
+
+      await expect(s.open()).rejects.toThrow('No challenge available')
+    })
+  })
+
+  describe('.sse() event parsing', () => {
+    test('yields only message data from SSE stream', async () => {
+      const events = [
+        'event: message\ndata: chunk1\n\n',
+        'event: message\ndata: chunk2\n\n',
+        `event: payment-receipt\ndata: ${JSON.stringify({
+          method: 'tempo',
+          intent: 'session',
+          status: 'success',
+          timestamp: '2025-01-01T00:00:00.000Z',
+          reference: channelId,
+          challengeId,
+          channelId,
+          acceptedCumulative: '2000000',
+          spent: '2000000',
+          units: 2,
+        } satisfies StreamReceipt)}\n\n`,
+      ]
+
+      let callCount = 0
+      const mockFetch = vi.fn().mockImplementation(() => {
+        callCount++
+        if (callCount === 1) return Promise.resolve(makeSseResponse(events))
+        return Promise.resolve(makeOkResponse())
+      })
+
+      const s = sessionManager({
+        account: '0x0000000000000000000000000000000000000001',
+        fetch: mockFetch as typeof globalThis.fetch,
+      })
+
+      // Manually set channel state to skip auto-open flow
+      ;(s as any).__test_setChannel?.()
+
+      const receiptCb = vi.fn()
+      const iterable = await s.sse('https://api.example.com/stream', {
+        onReceipt: receiptCb,
+      })
+
+      const messages: string[] = []
+      for await (const msg of iterable) {
+        messages.push(msg)
+      }
+
+      expect(messages).toEqual(['chunk1', 'chunk2'])
+      expect(receiptCb).toHaveBeenCalledOnce()
+      expect(receiptCb.mock.calls[0]![0].units).toBe(2)
+    })
+  })
+
+  describe('error handling', () => {
+    test('.sse() silently skips payment-need-voucher when no channel open', async () => {
+      const needVoucher: NeedVoucherEvent = {
+        channelId,
+        requiredCumulative: '2000000',
+        acceptedCumulative: '1000000',
+        deposit: '10000000',
+      }
+
+      const events = [
+        'event: message\ndata: chunk1\n\n',
+        formatNeedVoucherEvent(needVoucher),
+        'event: message\ndata: chunk2\n\n',
+      ]
+
+      const mockFetch = vi.fn().mockResolvedValue(makeSseResponse(events))
+
+      const s = sessionManager({
+        account: '0x0000000000000000000000000000000000000001',
+        fetch: mockFetch as typeof globalThis.fetch,
+      })
+
+      const iterable = await s.sse('https://api.example.com/stream')
+
+      const messages: string[] = []
+      for await (const msg of iterable) {
+        messages.push(msg)
+      }
+
+      expect(messages).toEqual(['chunk1', 'chunk2'])
+      expect(mockFetch).toHaveBeenCalledOnce()
+    })
+  })
+
+  describe('.close()', () => {
+    test('is no-op when not opened', async () => {
+      const mockFetch = vi.fn()
+
+      const s = sessionManager({
+        account: '0x0000000000000000000000000000000000000001',
+        fetch: mockFetch as typeof globalThis.fetch,
+      })
+
+      await s.close()
+      expect(mockFetch).not.toHaveBeenCalled()
+    })
+  })
+})