@routedock/routedock 0.1.1 → 0.2.0

package/src/client/MppSessionClient.ts

@@ -1,144 +0,0 @@
-/**
- * MppSessionClient — uses @stellar/mpp channel/client for off-chain
- * cumulative commitments against a pre-deployed one-way-channel contract.
- *
- * The channel is deployed and funded before the agent runs. The client
- * signs ed25519 commitments per the one-way-channel protocol — the
- * @stellar/mpp library handles the 402 challenge-response cycle.
- */
-import { Keypair } from '@stellar/stellar-sdk'
-import { stellar } from '@stellar/mpp/channel/client'
-import { Mppx } from 'mppx/client'
-import type {
-  RouteDockManifest,
-  SessionHandle,
-  SessionCloseResult,
-} from '../types.js'
-import {
-  RouteDockManifestError,
-  RouteDockSessionError,
-} from '../types.js'
-
-const MIN_REFUND_WAITING_PERIOD = 17_280
-
-export class MppSessionClient {
-  constructor(
-    private readonly keypair: Keypair,
-    private readonly network: 'testnet' | 'mainnet',
-  ) {}
-
-  async openSession(
-    url: string,
-    manifest: RouteDockManifest,
-    commitmentSecret: string,
-  ): Promise<SessionHandle> {
-    const pricing = manifest.pricing['mpp-session']
-    if (!pricing) {
-      throw new RouteDockManifestError('manifest.pricing.mpp-session missing')
-    }
-
-    const refundPeriod = pricing.refund_waiting_period_ledgers
-    if (refundPeriod < MIN_REFUND_WAITING_PERIOD) {
-      throw new RouteDockManifestError(
-        `refund_waiting_period_ledgers ${refundPeriod} < minimum ${MIN_REFUND_WAITING_PERIOD}`,
-      )
-    }
-
-    const commitmentKey = Keypair.fromSecret(commitmentSecret)
-    const channelContract = pricing.channel_contract
-    const agentPublicKey = this.keypair.publicKey()
-
-    let currentCumulative = 0n
-    let vouchersIssued = 0
-
-    const mppx = Mppx.create({
-      polyfill: false,
-      methods: [
-        stellar.channel({
-          commitmentKey,
-          sourceAccount: this.keypair.publicKey(),
-          onProgress(event) {
-            if (event.type === 'signed') {
-              currentCumulative = BigInt(event.cumulativeAmount)
-            }
-          },
-        }),
-      ],
-    })
-
-    const openTxHash = channelContract
-
-    const handle: SessionHandle = {
-      channelId: channelContract,
-      openTxHash,
-
-      async *stream(): AsyncIterable<unknown> {
-        while (true) {
-          let resp: globalThis.Response | null = null
-          for (let attempt = 0; attempt < 3; attempt++) {
-            try {
-              resp = await mppx.fetch(url)
-              if (resp.ok) break
-              resp = null
-            } catch {
-              if (attempt === 2) throw new RouteDockSessionError('Voucher request failed after 3 retries')
-              await new Promise(r => setTimeout(r, 1000 * (attempt + 1)))
-            }
-          }
-          if (!resp || !resp.ok) {
-            throw new RouteDockSessionError(`Voucher request failed: HTTP ${resp?.status ?? 'unknown'}`)
-          }
-          vouchersIssued++
-          yield await resp.json()
-        }
-      },
-
-      async close(): Promise<SessionCloseResult> {
-        const { rpc: rpcMod, Contract, nativeToScVal, TransactionBuilder, BASE_FEE } = await import('@stellar/stellar-sdk')
-        const rpcUrl = 'https://soroban-testnet.stellar.org'
-        const server = new rpcMod.Server(rpcUrl)
-        const contract = new Contract(channelContract)
-        const passphrase = 'Test SDF Network ; September 2015'
-
-        const account = await server.getAccount(agentPublicKey)
-        const simTx = new TransactionBuilder(account, { fee: BASE_FEE, networkPassphrase: passphrase })
-          .addOperation(contract.call('prepare_commitment', nativeToScVal(currentCumulative, { type: 'i128' })))
-          .setTimeout(30)
-          .build()
-        const simResult = await server.simulateTransaction(simTx)
-        if (rpcMod.Api.isSimulationError(simResult)) {
-          throw new RouteDockSessionError(`prepare_commitment simulation failed: ${simResult.error}`)
-        }
-        const commitmentBytes = (simResult as { result?: { retval?: { bytes: () => Buffer } } }).result?.retval?.bytes()
-        if (!commitmentBytes) throw new RouteDockSessionError('prepare_commitment returned no bytes')
-
-        const signature = commitmentKey.sign(Buffer.from(commitmentBytes))
-
-        const closeResp = await fetch(url, {
-          method: 'DELETE',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({
-            amount: currentCumulative.toString(),
-            signature: Buffer.from(signature).toString('hex'),
-          }),
-        })
-
-        if (!closeResp.ok) {
-          throw new RouteDockSessionError(`Channel close failed: HTTP ${closeResp.status}`)
-        }
-
-        const closeData = (await closeResp.json()) as { closeTxHash?: string }
-        const closeTxHash = closeData.closeTxHash ?? null
-
-        if (!closeTxHash) {
-          throw new RouteDockSessionError('Channel close response missing closeTxHash')
-        }
-
-        const totalPaid = (Number(currentCumulative) / 1e7).toFixed(7)
-        return { closeTxHash, totalPaid, vouchersIssued }
-      },
-    }
-
-    return handle
-  }
-}

package/src/client/RouteDockClient.ts

@@ -1,124 +0,0 @@
-import { Keypair } from '@stellar/stellar-sdk'
-import { fetchManifest, selectMode, type ModeSelectOptions } from './ModeRouter.js'
-import { X402Client } from './x402Client.js'
-import { MppChargeClient } from './MppChargeClient.js'
-import { MppSessionClient } from './MppSessionClient.js'
-import type { PaymentResult, SessionHandle } from '../types.js'
-import {
-  RouteDockManifestError,
-  RouteDockPolicyRejectedError,
-} from '../types.js'
-
-export interface SpendCap {
-  /** Maximum total USDC spend per day (decimal string, e.g. "1.00") */
-  daily: string
-  asset: 'USDC'
-}
-
-export interface RouteDockClientConfig {
-  /** Stellar keypair or raw secret key (S...) */
-  wallet: Keypair | string
-  network: 'testnet' | 'mainnet'
-  /** Optional local daily spend cap — checked before every payment */
-  spendCap?: SpendCap
-  /** Ed25519 secret key (S...) for signing channel commitments. Required for mpp-session. */
-  commitmentSecret?: string | undefined
-}
-
-export class RouteDockClient {
-  private readonly keypair: Keypair
-  private readonly network: 'testnet' | 'mainnet'
-  private readonly spendCap: SpendCap | undefined
-  private readonly commitmentSecret: string | undefined
-
-  /** Local daily accumulator keyed by YYYY-MM-DD */
-  private dailySpend: { date: string; total: number } = { date: '', total: 0 }
-
-  private readonly x402: X402Client
-  private readonly charge: MppChargeClient
-  private readonly session: MppSessionClient
-
-  constructor(config: RouteDockClientConfig) {
-    this.keypair =
-      typeof config.wallet === 'string' ? Keypair.fromSecret(config.wallet) : config.wallet
-    this.network = config.network
-    this.spendCap = config.spendCap
-    this.commitmentSecret = config.commitmentSecret
-
-    const secretKey = this.keypair.secret()
-    this.x402 = new X402Client(secretKey, this.network)
-    this.charge = new MppChargeClient(this.keypair, this.network)
-    this.session = new MppSessionClient(this.keypair, this.network)
-  }
-
-  /**
-   * Pay for one request at `url`. Fetches manifest, selects payment mode,
-   * checks local spend cap, executes payment, returns result.
-   */
-  async pay(url: string, options?: ModeSelectOptions): Promise<PaymentResult> {
-    const baseUrl = new URL(url).origin
-    const manifest = await fetchManifest(baseUrl)
-    const mode = selectMode(manifest, options)
-
-    let result: PaymentResult
-
-    switch (mode) {
-      case 'x402':
-        result = await this.x402.pay(url, manifest)
-        break
-      case 'mpp-charge':
-        result = await this.charge.pay(url, manifest)
-        break
-      case 'mpp-session':
-        throw new RouteDockManifestError(
-          'Use client.openSession() for mpp-session mode — client.pay() only handles discrete payments',
-        )
-      default:
-        throw new RouteDockManifestError(`Unknown payment mode: ${mode as string}`)
-    }
-
-    this._checkAndRecordSpend(result.amount)
-    return result
-  }
-
-  /**
-   * Open a sustained MPP session at `url`. Verifies mpp-session is supported
-   * before opening a channel. Returns a SessionHandle for streaming + closing.
-   */
-  async openSession(url: string): Promise<SessionHandle> {
-    const baseUrl = new URL(url).origin
-    const manifest = await fetchManifest(baseUrl)
-
-    if (!manifest.modes.includes('mpp-session')) {
-      throw new RouteDockManifestError(
-        `Provider at ${baseUrl} does not support mpp-session mode`,
-      )
-    }
-
-    if (!this.commitmentSecret) {
-      throw new RouteDockManifestError(
-        'commitmentSecret is required in RouteDockClientConfig for mpp-session mode',
-      )
-    }
-
-    return this.session.openSession(url, manifest, this.commitmentSecret)
-  }
-
-  /** Check local daily cap and record the spend. Throws if cap exceeded. */
-  private _checkAndRecordSpend(amount: string): void {
-    if (!this.spendCap) return
-
-    const today = new Date().toISOString().slice(0, 10)
-    if (this.dailySpend.date !== today) {
-      this.dailySpend = { date: today, total: 0 }
-    }
-
-    const amountNum = parseFloat(amount)
-    const capNum = parseFloat(this.spendCap.daily)
-    if (this.dailySpend.total + amountNum > capNum) {
-      throw new RouteDockPolicyRejectedError('local_daily_cap_exceeded')
-    }
-
-    this.dailySpend.total += amountNum
-  }
-}

package/src/client/index.ts

@@ -1,8 +0,0 @@
-// Client-only exports (no provider/Express)
-export * from '../types.js'
-export * from './RouteDockClient.js'
-export * from './ModeRouter.js'
-export * from './x402Client.js'
-export * from './MppChargeClient.js'
-export * from './MppSessionClient.js'
-export * from '../store/SessionStore.js'

package/src/client/x402Client.ts

@@ -1,84 +0,0 @@
-import { createEd25519Signer } from '@x402/stellar'
-import { ExactStellarScheme } from '@x402/stellar/exact/client'
-import { x402Client, x402HTTPClient } from '@x402/core/client'
-import {
-  decodePaymentRequiredHeader,
-  decodePaymentResponseHeader,
-  encodePaymentSignatureHeader,
-} from '@x402/core/http'
-import type { Network as X402Network } from '@x402/core/types'
-import type { RouteDockManifest, PaymentResult } from '../types.js'
-import { RouteDockManifestError } from '../types.js'
-
-type Network = 'testnet' | 'mainnet'
-
-const CAIP2: Record<Network, X402Network> = {
-  testnet: 'stellar:testnet',
-  mainnet: 'stellar:pubnet',
-}
-
-export class X402Client {
-  private readonly httpClient: x402HTTPClient
-
-  constructor(
-    private readonly secretKey: string,
-    private readonly network: Network,
-  ) {
-    const caip2 = CAIP2[network]
-    const signer = createEd25519Signer(secretKey, caip2)
-    const scheme = new ExactStellarScheme(signer)
-    const core = new x402Client()
-    core.register(caip2, scheme)
-    this.httpClient = new x402HTTPClient(core)
-  }
-
-  async pay(url: string, manifest: RouteDockManifest): Promise<PaymentResult> {
-    const pricing = manifest.pricing.x402
-    if (!pricing) {
-      throw new RouteDockManifestError('manifest.pricing.x402 missing')
-    }
-    if (!pricing.facilitator) {
-      throw new RouteDockManifestError('manifest.pricing.x402.facilitator missing')
-    }
-
-    // Initial request — expect 402. Include mode hint so middleware routes correctly.
-    const init = await fetch(url, { headers: { 'X-Preferred-Mode': 'x402' } })
-    if (init.status !== 402) {
-      const data = await init.json()
-      return { data, txHash: null, mode: 'x402', amount: pricing.amount, timestamp: Date.now() }
-    }
-
-    // Parse payment requirements from header
-    const reqHeader = init.headers.get('X-Payment-Requirements')
-    if (!reqHeader) {
-      throw new RouteDockManifestError('402 response missing X-Payment-Requirements header')
-    }
-
-    const paymentRequired = decodePaymentRequiredHeader(reqHeader)
-
-    // Build signed payment payload
-    const paymentPayload = await this.httpClient.createPaymentPayload(paymentRequired)
-    const paymentHeaders = this.httpClient.encodePaymentSignatureHeader(paymentPayload)
-
-    // Re-request with payment
-    const settled = await fetch(url, { headers: paymentHeaders })
-    if (!settled.ok) {
-      throw new RouteDockManifestError(`x402 payment failed: HTTP ${settled.status}`)
-    }
-
-    // Extract settlement tx hash from response header
-    let txHash: string | null = null
-    const responseHeader = settled.headers.get('X-Payment-Response')
-    if (responseHeader) {
-      try {
-        const settleResponse = decodePaymentResponseHeader(responseHeader)
-        txHash = (settleResponse as { transaction?: string }).transaction ?? null
-      } catch {
-        // non-fatal — some facilitators may omit the response header
-      }
-    }
-
-    const data = await settled.json()
-    return { data, txHash, mode: 'x402', amount: pricing.amount, timestamp: Date.now() }
-  }
-}

package/src/index.ts

@@ -1,9 +0,0 @@
-// Full SDK — types, client, provider, store
-export * from './types.js'
-export * from './client/RouteDockClient.js'
-export * from './client/ModeRouter.js'
-export * from './client/x402Client.js'
-export * from './client/MppChargeClient.js'
-export * from './client/MppSessionClient.js'
-export * from './store/SessionStore.js'
-export * from './provider/routedockMiddleware.js'

package/src/provider/MppChargeHandler.ts

@@ -1,90 +0,0 @@
-import type { Request, Response, NextFunction, RequestHandler } from 'express'
-import { stellar } from '@stellar/mpp/charge/server'
-import { Mppx, Request as MppxRequest } from 'mppx/server'
-import type { RouteDockManifest } from '../types.js'
-import type { SessionStore } from '../store/SessionStore.js'
-
-type Network = 'testnet' | 'mainnet'
-
-const MPP_NETWORK: Record<Network, 'stellar:testnet' | 'stellar:pubnet'> = {
-  testnet: 'stellar:testnet',
-  mainnet: 'stellar:pubnet',
-}
-
-export interface MppChargeHandlerOptions {
-  payeeSecretKey: string
-  network: Network
-  amount: string
-  assetContract: string
-  manifest: RouteDockManifest
-  store?: SessionStore
-  onSettled?: (txHash: string, amount: string, mode: string) => Promise<void>
-}
-
-export function createMppChargeHandler(opts: MppChargeHandlerOptions): RequestHandler {
-  const networkId = MPP_NETWORK[opts.network]
-  const amountHumanReadable = opts.amount
-
-  const mppx = Mppx.create({
-    secretKey: opts.payeeSecretKey,
-    methods: [
-      stellar.charge({
-        recipient: opts.manifest.payee,
-        currency: opts.assetContract,
-        network: networkId,
-        feePayer: { envelopeSigner: opts.payeeSecretKey },
-      }),
-    ],
-  })
-
-  return async (req: Request, res: Response, next: NextFunction): Promise<void> => {
-    try {
-      const fetchReq = MppxRequest.fromNodeListener(req, res)
-      // `mppx['stellar/charge']` — method key is `name/intent`
-      const handler = (
-        mppx as unknown as {
-          'stellar/charge': (
-            opts: { amount: string; currency: string; recipient: string; description?: string },
-          ) => (input: globalThis.Request) => Promise<{ status: 402 | 200; challenge?: globalThis.Response; withReceipt?: (r: globalThis.Response) => globalThis.Response }>
-        }
-      )['stellar/charge']
-      const result = await handler({
-        amount: amountHumanReadable,
-        currency: opts.assetContract,
-        recipient: opts.manifest.payee,
-        description: opts.manifest.name,
-      })(fetchReq)
-
-      if (result.status === 402) {
-        const challenge = result.challenge!
-        res.status(402)
-        challenge.headers.forEach((v: string, k: string) => res.setHeader(k, v))
-        res.send(await challenge.text())
-        return
-      }
-
-      // status 200 — payment verified
-      const receipt = result.withReceipt!(new Response(''))
-      receipt.headers.forEach((v: string, k: string) => res.setHeader(k, v))
-
-      // Extract tx hash from receipt headers if available
-      const receiptHeader = receipt.headers.get('payment-receipt')
-      if (receiptHeader && opts.onSettled) {
-        try {
-          const parsed = JSON.parse(
-            Buffer.from(receiptHeader, 'base64').toString('utf8'),
-          ) as { reference?: string }
-          if (parsed.reference) {
-            await opts.onSettled(parsed.reference, opts.amount, 'mpp-charge')
-          }
-        } catch {
-          // non-fatal
-        }
-      }
-
-      next()
-    } catch (err) {
-      next(err)
-    }
-  }
-}

package/src/provider/MppSessionHandler.ts

@@ -1,157 +0,0 @@
-import type { Request, Response, NextFunction, RequestHandler } from 'express'
-import { Keypair } from '@stellar/stellar-sdk'
-import { stellar, close as channelClose, Store } from '@stellar/mpp/channel/server'
-import { Mppx, Request as MppxRequest } from 'mppx/server'
-import type { RouteDockManifest } from '../types.js'
-
-type Network = 'testnet' | 'mainnet'
-
-const MPP_NETWORK: Record<Network, 'stellar:testnet' | 'stellar:pubnet'> = {
-  testnet: 'stellar:testnet',
-  mainnet: 'stellar:pubnet',
-}
-
-export interface MppSessionHandlerOptions {
-  payeeSecretKey: string
-  network: Network
-  channelContract: string
-  rate: string
-  assetContract: string
-  manifest: RouteDockManifest
-  commitmentPublicKey: string
-  onSettled?: (txHash: string, totalPaid: string, mode: string) => Promise<void>
-  onSessionOpen?: (channelId: string) => Promise<void>
-  onVoucher?: (voucherIndex: number, cumulativeAmount: string) => Promise<void>
-}
-
-export function createMppSessionHandler(opts: MppSessionHandlerOptions): RequestHandler {
-  const networkId = MPP_NETWORK[opts.network]
-  const rateHuman = opts.rate
-  const payeeKeypair = Keypair.fromSecret(opts.payeeSecretKey)
-  const cumulativeKey = `stellar:channel:cumulative:${opts.channelContract}`
-
-  const innerStore = Store.memory()
-
-  let lastCumulativeAmount = 0n
-  let voucherCount = 0
-  let sessionOpened = false
-
-  const wrappedStore: ReturnType<typeof Store.memory> = {
-    async get(key: string) { return innerStore.get(key) },
-    async put(key: string, value: unknown) {
-      await innerStore.put(key, value)
-      if (key === cumulativeKey && value && typeof value === 'object' && 'amount' in (value as Record<string, unknown>)) {
-        lastCumulativeAmount = BigInt((value as { amount: string }).amount)
-        voucherCount++
-
-        if (!sessionOpened) {
-          sessionOpened = true
-          if (opts.onSessionOpen) {
-            await opts.onSessionOpen(opts.channelContract)
-          }
-        }
-
-        if (opts.onVoucher) {
-          const humanAmount = (Number(lastCumulativeAmount) / 1e7).toFixed(7)
-          await opts.onVoucher(voucherCount, humanAmount)
-        }
-      }
-    },
-    async delete(key: string) { return innerStore.delete(key) },
-  }
-
-  const mppx = Mppx.create({
-    secretKey: opts.payeeSecretKey,
-    methods: [
-      stellar.channel({
-        channel: opts.channelContract,
-        commitmentKey: opts.commitmentPublicKey,
-        network: networkId,
-        store: wrappedStore,
-        sourceAccount: payeeKeypair.publicKey(),
-        feePayer: { envelopeSigner: payeeKeypair },
-      }),
-    ],
-  })
-
-  // Track the last signature from the authorization header
-  let lastSignatureHex = ''
-
-  return async (req: Request, res: Response, next: NextFunction): Promise<void> => {
-    try {
-      if (req.method === 'DELETE') {
-        const body = req.body as { amount?: string; signature?: string } | undefined
-        const closeAmount = body?.amount ? BigInt(body.amount) : lastCumulativeAmount
-        const closeSig = body?.signature ?? lastSignatureHex
-
-        if (closeAmount > 0n && closeSig) {
-          const closeTxHash = await channelClose({
-            channel: opts.channelContract,
-            amount: closeAmount,
-            signature: Buffer.from(closeSig, 'hex'),
-            feePayer: { envelopeSigner: payeeKeypair },
-            network: networkId,
-          })
-
-          if (opts.onSettled) {
-            const totalPaid = (Number(lastCumulativeAmount) / 1e7).toFixed(7)
-            await opts.onSettled(closeTxHash, totalPaid, 'mpp-session')
-          }
-
-          res.json({ closeTxHash })
-        } else {
-          res.json({ closeTxHash: null, message: 'no vouchers received' })
-        }
-
-        sessionOpened = false
-        voucherCount = 0
-        lastCumulativeAmount = 0n
-        return
-      }
-
-      // Extract the signature from the authorization header before passing to mppx
-      const authHeader = req.headers['authorization']
-      if (typeof authHeader === 'string' && authHeader.startsWith('Payment ')) {
-        try {
-          const credB64 = authHeader.replace(/^Payment\s+/, '').split(',').find(p => p.trim().startsWith('credential='))
-          if (credB64) {
-            const credJson = Buffer.from(credB64.split('=').slice(1).join('=').replace(/^"|"$/g, ''), 'base64').toString('utf8')
-            const cred = JSON.parse(credJson) as { payload?: { signature?: string } }
-            if (cred.payload?.signature) {
-              lastSignatureHex = cred.payload.signature
-            }
-          }
-        } catch {
-          // non-fatal — signature extraction is best-effort
-        }
-      }
-
-      const fetchReq = MppxRequest.fromNodeListener(req, res)
-
-      const result = await (mppx as unknown as {
-        channel: (o: { amount: string; description?: string }) =>
-          (r: globalThis.Request) => Promise<{
-            status: number
-            challenge?: globalThis.Response
-            withReceipt?: (r: globalThis.Response) => globalThis.Response
-          }>
-      }).channel({
-        amount: rateHuman,
-        description: opts.manifest.name,
-      })(fetchReq)
-
-      if (result.status === 402) {
-        const challenge = result.challenge!
-        res.status(402)
-        challenge.headers.forEach((v: string, k: string) => res.setHeader(k, v))
-        const body = await challenge.text()
-        res.send(body)
-        return
-      }
-
-      next()
-    } catch (err) {
-      next(err)
-    }
-  }
-}

package/src/provider/index.ts

@@ -1,7 +0,0 @@
-// Provider-only exports (Express middleware + handlers)
-export * from '../types.js'
-export * from './routedockMiddleware.js'
-export * from './x402Handler.js'
-export * from './MppChargeHandler.js'
-export * from './MppSessionHandler.js'
-export * from '../store/SessionStore.js'