@routedock/routedock 0.1.0

package/src/tests/smoke.test.ts

@@ -0,0 +1,228 @@
+/**
+ * Integration smoke tests for @routedock/sdk.
+ *
+ * These tests run against actual package imports to verify:
+ *   1. x402 flow against a local mock server (402 → payment → 200)
+ *   2. ModeRouter manifest fetch + validation
+ *   3. SessionStore monotonic invariant rejection
+ *
+ * Run with: pnpm --filter @routedock/sdk test
+ * No testnet RPC calls are made — all network calls are mocked via fetch interception.
+ */
+
+import * as http from 'node:http'
+import { createServer } from 'node:http'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import assert from 'node:assert/strict'
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function startTestServer(
+  handler: (req: IncomingMessage, res: ServerResponse) => void,
+): Promise<{ url: string; close: () => Promise<void> }> {
+  return new Promise((resolve) => {
+    const server = createServer(handler)
+    server.listen(0, '127.0.0.1', () => {
+      const addr = server.address() as { port: number }
+      resolve({
+        url: `http://127.0.0.1:${addr.port}`,
+        close: () => new Promise<void>((res) => server.close(() => res())),
+      })
+    })
+  })
+}
+
+// ── Test 1: ModeRouter — manifest fetch + schema validation ───────────────────
+
+{
+  const validManifest = {
+    routedock: '1.0',
+    name: 'Test Provider',
+    description: 'Smoke test provider',
+    modes: ['x402', 'mpp-charge'],
+    network: 'testnet',
+    asset: 'USDC',
+    asset_contract: 'CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA',
+    payee: 'GDHLJWBM6Z2Y4KF6Z4JAFIUUO2KAXAJ6MAIUK2XMGBQ7ZUUZ7HFPW2BK',
+    pricing: {
+      x402: { amount: '0.001', per: 'request', facilitator: 'https://channels.openzeppelin.com/x402/testnet' },
+      'mpp-charge': { amount: '0.0008', per: 'request' },
+    },
+    endpoints: { price: 'GET /price' },
+    tags: ['price', 'stellar'],
+  }
+
+  const server = await startTestServer((req, res) => {
+    if (req.url === '/.well-known/routedock.json') {
+      res.writeHead(200, { 'Content-Type': 'application/json' })
+      res.end(JSON.stringify(validManifest))
+    } else {
+      res.writeHead(404)
+      res.end()
+    }
+  })
+
+  try {
+    const { fetchManifest, selectMode } = await import('../client/ModeRouter.js')
+
+    const manifest = await fetchManifest(server.url)
+    assert.equal(manifest.routedock, '1.0', 'manifest version should be 1.0')
+    assert.equal(manifest.name, 'Test Provider', 'manifest name should match')
+    assert.ok(manifest.modes.includes('x402'), 'manifest should include x402 mode')
+
+    // Second fetch should be cached
+    const cached = await fetchManifest(server.url)
+    assert.equal(cached, manifest, 'second fetch should return cached manifest')
+
+    // Mode selection
+    const mode = selectMode(manifest)
+    assert.equal(mode, 'mpp-charge', 'mpp-charge should be preferred over x402')
+
+    const modeForced = selectMode(manifest, { sustained: true })
+    assert.equal(modeForced, 'mpp-charge', 'sustained without mpp-session falls back to mpp-charge')
+
+    console.log('✓ Test 1: ModeRouter manifest fetch + validation PASSED')
+  } finally {
+    await server.close()
+  }
+}
+
+// ── Test 2: ModeRouter — invalid manifest rejected ────────────────────────────
+
+{
+  const badManifest = { routedock: '2.0', name: 'bad' }
+
+  const server = await startTestServer((req, res) => {
+    res.writeHead(200, { 'Content-Type': 'application/json' })
+    res.end(JSON.stringify(badManifest))
+  })
+
+  try {
+    const { fetchManifest } = await import('../client/ModeRouter.js')
+    const { RouteDockManifestError: ManifestError } = await import('../types.js')
+
+    let threw = false
+    try {
+      await fetchManifest(server.url + '/bad-url')
+    } catch (err) {
+      threw = true
+      assert.ok(
+        err instanceof ManifestError,
+        `should throw RouteDockManifestError, got ${String(err)}`,
+      )
+    }
+    assert.ok(threw, 'should have thrown for invalid manifest')
+
+    console.log('✓ Test 2: Invalid manifest rejection PASSED')
+  } finally {
+    await server.close()
+  }
+}
+
+// ── Test 3: SessionStore — monotonic invariant rejection ─────────────────────
+
+{
+  // Use an in-memory store implementation to test monotonic invariant
+  // without a real Supabase connection.
+
+  const { RouteDockSessionError } = await import('../types.js')
+
+  // Build a minimal in-memory SessionStore-compatible implementation
+  const sessions = new Map<string, import('../types.js').SessionState>()
+  const memStore = {
+    async get(channelId: string) {
+      return sessions.get(channelId) ?? null
+    },
+    async upsert(channelId: string, state: import('../types.js').SessionState) {
+      const existing = sessions.get(channelId)
+      if (existing) {
+        const prev = parseFloat(existing.cumulative_amount)
+        const next = parseFloat(state.cumulative_amount)
+        if (next <= prev) {
+          throw new RouteDockSessionError(
+            `cumulative_amount must be strictly increasing: ${next} <= ${prev}`,
+          )
+        }
+      }
+      sessions.set(channelId, { ...state })
+    },
+    async close(channelId: string) {
+      const s = sessions.get(channelId)
+      if (s) sessions.set(channelId, { ...s, status: 'closed' })
+    },
+  }
+
+  const baseState: import('../types.js').SessionState = {
+    channel_id: 'test-channel-1',
+    payee: 'GPAYEE',
+    payer: 'GPAYER',
+    cumulative_amount: '0.0010000',
+    last_signature: 'sig1',
+    status: 'open',
+    opened_at: new Date().toISOString(),
+    updated_at: new Date().toISOString(),
+    settlement_tx_hash: null,
+  }
+
+  // First upsert — should succeed
+  await memStore.upsert('test-channel-1', baseState)
+
+  // Second upsert with higher amount — should succeed
+  await memStore.upsert('test-channel-1', { ...baseState, cumulative_amount: '0.0020000' })
+
+  // Third upsert with same amount — should throw
+  let threw = false
+  try {
+    await memStore.upsert('test-channel-1', { ...baseState, cumulative_amount: '0.0020000' })
+  } catch (err) {
+    threw = true
+    assert.ok(
+      err instanceof RouteDockSessionError,
+      `should throw RouteDockSessionError, got ${String(err)}`,
+    )
+  }
+  assert.ok(threw, 'equal cumulative amount should be rejected')
+
+  // Upsert with lower amount — should also throw
+  threw = false
+  try {
+    await memStore.upsert('test-channel-1', { ...baseState, cumulative_amount: '0.0010000' })
+  } catch (err) {
+    threw = true
+    assert.ok(err instanceof RouteDockSessionError)
+  }
+  assert.ok(threw, 'lower cumulative amount should be rejected')
+
+  console.log('✓ Test 3: SessionStore monotonic invariant rejection PASSED')
+}
+
+// ── Test 4: Error subclass hierarchy ─────────────────────────────────────────
+
+{
+  const {
+    RouteDockError,
+    RouteDockManifestError,
+    RouteDockNoSupportedModeError,
+    RouteDockSessionError,
+    RouteDockPolicyRejectedError,
+  } = await import('../types.js')
+
+  const errors = [
+    new RouteDockManifestError('test'),
+    new RouteDockNoSupportedModeError('test'),
+    new RouteDockSessionError('test'),
+    new RouteDockPolicyRejectedError('test'),
+  ]
+
+  for (const err of errors) {
+    assert.ok(err instanceof RouteDockError, `${err.name} should be instance of RouteDockError`)
+    assert.ok(err instanceof Error, `${err.name} should be instance of Error`)
+  }
+
+  const policyErr = new RouteDockPolicyRejectedError('local_daily_cap_exceeded')
+  assert.equal(policyErr.reason, 'local_daily_cap_exceeded')
+
+  console.log('✓ Test 4: Error subclass hierarchy PASSED')
+}
+
+console.log('\nAll smoke tests passed.')

package/src/types.ts

@@ -0,0 +1,165 @@
+/**
+ * TypeScript types for the RouteDock manifest format.
+ * Derived from packages/sdk/src/schemas/routedock.schema.json (draft-07).
+ *
+ * Section 5 of ROUTEDOCK_MASTER.md is the canonical specification.
+ */
+
+export type PaymentMode = 'x402' | 'mpp-charge' | 'mpp-session'
+
+/** Per-request pricing config — used by x402 and mpp-charge modes */
+export interface PricingConfig {
+  /** Cost per request in the payment asset, e.g. "0.001" */
+  amount: string
+  per: 'request'
+  /** x402 facilitator URL (OpenZeppelin Channels). Required for x402 mode. */
+  facilitator?: string
+}
+
+/** Per-voucher pricing config — used by mpp-session (one-way-channel) mode */
+export interface SessionPricingConfig {
+  /** Cost per voucher, e.g. "0.0001" */
+  rate: string
+  per: 'voucher'
+  /** Soroban contract address (C...) for the one-way-channel contract */
+  channel_contract: string
+  /** Minimum initial deposit to open a channel, e.g. "0.10" */
+  min_deposit: string
+  /**
+   * Ledgers the server has to settle before the funder can reclaim.
+   * Default: 17280 (~24h). Do NOT reduce in production — this is a
+   * security parameter the server depends on to settle first.
+   */
+  refund_waiting_period_ledgers: number
+}
+
+/** Full RouteDock discovery manifest — served at /.well-known/routedock.json */
+export interface RouteDockManifest {
+  /** Schema version — always "1.0" */
+  routedock: '1.0'
+  /** Human-readable provider name */
+  name: string
+  /** Human-readable description of the provider's data or service */
+  description: string
+  /** Payment modes supported by this provider */
+  modes: PaymentMode[]
+  /** Stellar network this provider operates on */
+  network: 'testnet' | 'mainnet'
+  /** Asset ticker symbol, e.g. "USDC" */
+  asset: string
+  /** Stellar Asset Contract (SAC) address for the payment asset */
+  asset_contract: string
+  /** Stellar address (G...) that receives payments */
+  payee: string
+  /** Pricing configuration per supported payment mode */
+  pricing: {
+    x402?: PricingConfig
+    'mpp-charge'?: PricingConfig
+    'mpp-session'?: SessionPricingConfig
+  }
+  /** Map of endpoint name to HTTP method + path, e.g. { price: "GET /price" } */
+  endpoints: Record<string, string>
+  /** Capability tags indexed with trigram search in the provider registry */
+  tags: string[]
+}
+
+/** Result returned by client.pay() for any payment mode */
+export interface PaymentResult {
+  /** Parsed response body from the provider */
+  data: unknown
+  /** On-chain Stellar transaction hash, or null for session voucher calls */
+  txHash: string | null
+  /** Payment mode that was used for this call */
+  mode: PaymentMode
+  /** Amount paid in the payment asset (decimal string) */
+  amount: string
+  /** Unix timestamp (ms) when the payment completed */
+  timestamp: number
+}
+
+/** Result returned by session.close() */
+export interface SessionCloseResult {
+  /** On-chain transaction hash for the channel close */
+  closeTxHash: string
+  /** Total amount settled across all vouchers (decimal string) */
+  totalPaid: string
+  /** Number of vouchers issued during the session */
+  vouchersIssued: number
+}
+
+/** Handle for a live MPP session returned by client.openSession() */
+export interface SessionHandle {
+  /** Stellar channel contract address (C...) */
+  channelId: string
+  /** Transaction hash from the channel-open on-chain call */
+  openTxHash: string
+  /**
+   * Async generator of server-sent event data.
+   * Each iteration sends a voucher and yields the parsed response.
+   * UNAUDITED: uses stellar-experimental/one-way-channel contract.
+   */
+  stream(): AsyncIterable<unknown>
+  /** Close the channel on-chain with the highest signed voucher */
+  close(): Promise<SessionCloseResult>
+}
+
+/**
+ * Durable session state stored in Supabase (sessions table).
+ * cumulative_amount is a decimal string to avoid float precision loss.
+ * The monotonic invariant is enforced both here and at the DB level via trigger.
+ */
+export interface SessionState {
+  channel_id: string
+  payee: string
+  payer: string
+  /** Monotonically increasing cumulative amount — stored as string to preserve precision */
+  cumulative_amount: string
+  last_signature: string
+  status: 'open' | 'closing' | 'closed'
+  opened_at: string
+  updated_at: string
+  settlement_tx_hash: string | null
+}
+
+// ── Error hierarchy ────────────────────────────────────────────────────────────
+
+export class RouteDockError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'RouteDockError'
+  }
+}
+
+/** Manifest fetch failed, schema invalid, or required fields missing */
+export class RouteDockManifestError extends RouteDockError {
+  constructor(message: string) {
+    super(message)
+    this.name = 'RouteDockManifestError'
+  }
+}
+
+/** No payment mode in the manifest is supported by this client */
+export class RouteDockNoSupportedModeError extends RouteDockError {
+  constructor(message: string) {
+    super(message)
+    this.name = 'RouteDockNoSupportedModeError'
+  }
+}
+
+/** Session invariant violated (e.g. non-monotonic voucher amount) */
+export class RouteDockSessionError extends RouteDockError {
+  constructor(message: string) {
+    super(message)
+    this.name = 'RouteDockSessionError'
+  }
+}
+
+/** Local spend cap or on-chain policy rejected the payment */
+export class RouteDockPolicyRejectedError extends RouteDockError {
+  readonly reason: string
+  constructor(reason: string) {
+    super(`Payment rejected by policy: ${reason}`)
+    this.name = 'RouteDockPolicyRejectedError'
+    this.reason = reason
+  }
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "allowImportingTsExtensions": false,
+    "lib": ["ES2022"],
+    "target": "ES2022"
+  },
+  "include": ["src/**/*"]
+}

package/tsup.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from 'tsup'
+
+export default defineConfig({
+  entry: {
+    index: 'src/index.ts',
+    client: 'src/client/index.ts',
+    provider: 'src/provider/index.ts',
+  },
+  format: ['cjs', 'esm'],
+  dts: true,
+  clean: true,
+  splitting: false,
+  sourcemap: false,
+  treeshake: true,
+})