@routedock/routedock 0.1.2 → 0.3.0

package/src/schemas/routedock.schema.json

@@ -1,159 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://routedock.dev/schemas/routedock.schema.json",
-  "title": "RouteDock Manifest",
-  "description": "Discovery manifest served at /.well-known/routedock.json on every RouteDock provider endpoint",
-  "type": "object",
-  "required": [
-    "routedock",
-    "name",
-    "description",
-    "modes",
-    "network",
-    "asset",
-    "asset_contract",
-    "payee",
-    "pricing",
-    "endpoints",
-    "tags"
-  ],
-  "additionalProperties": false,
-  "properties": {
-    "routedock": {
-      "type": "string",
-      "const": "1.0",
-      "description": "Manifest schema version. Always '1.0' for this version."
-    },
-    "name": {
-      "type": "string",
-      "minLength": 1,
-      "maxLength": 120,
-      "description": "Human-readable provider name"
-    },
-    "description": {
-      "type": "string",
-      "minLength": 1,
-      "maxLength": 500,
-      "description": "Human-readable description of the provider's data or service"
-    },
-    "modes": {
-      "type": "array",
-      "minItems": 1,
-      "uniqueItems": true,
-      "items": {
-        "$ref": "#/definitions/PaymentMode"
-      },
-      "description": "Payment modes supported by this provider"
-    },
-    "network": {
-      "type": "string",
-      "enum": ["testnet", "mainnet"],
-      "description": "Stellar network this provider operates on"
-    },
-    "asset": {
-      "type": "string",
-      "description": "Asset ticker symbol (e.g. 'USDC')"
-    },
-    "asset_contract": {
-      "type": "string",
-      "description": "Stellar Asset Contract (SAC) address for the payment asset"
-    },
-    "payee": {
-      "type": "string",
-      "description": "Stellar address (G...) that receives payments"
-    },
-    "pricing": {
-      "type": "object",
-      "description": "Pricing configuration per supported payment mode",
-      "additionalProperties": false,
-      "properties": {
-        "x402": {
-          "$ref": "#/definitions/PricingConfig"
-        },
-        "mpp-charge": {
-          "$ref": "#/definitions/PricingConfig"
-        },
-        "mpp-session": {
-          "$ref": "#/definitions/SessionPricingConfig"
-        }
-      },
-      "minProperties": 1
-    },
-    "endpoints": {
-      "type": "object",
-      "description": "Map of endpoint name to HTTP method + path (e.g. { 'price': 'GET /price' })",
-      "additionalProperties": {
-        "type": "string"
-      },
-      "minProperties": 1
-    },
-    "tags": {
-      "type": "array",
-      "items": {
-        "type": "string",
-        "minLength": 1,
-        "maxLength": 64
-      },
-      "uniqueItems": true,
-      "description": "Capability tags indexed with trigram search in the provider registry"
-    }
-  },
-  "definitions": {
-    "PaymentMode": {
-      "type": "string",
-      "enum": ["x402", "mpp-charge", "mpp-session"],
-      "description": "A supported RouteDock payment mode"
-    },
-    "PricingConfig": {
-      "type": "object",
-      "description": "Per-request pricing for x402 or mpp-charge modes",
-      "required": ["amount", "per"],
-      "additionalProperties": false,
-      "properties": {
-        "amount": {
-          "type": "string",
-          "description": "Cost per request in the payment asset (decimal string, e.g. '0.001')"
-        },
-        "per": {
-          "type": "string",
-          "const": "request",
-          "description": "Billing unit — always 'request' for non-session modes"
-        },
-        "facilitator": {
-          "type": "string",
-          "description": "x402 facilitator URL (required for x402 mode). OpenZeppelin Channels endpoint."
-        }
-      }
-    },
-    "SessionPricingConfig": {
-      "type": "object",
-      "description": "Per-voucher pricing for mpp-session (one-way-channel) mode",
-      "required": ["rate", "per", "channel_contract", "min_deposit", "refund_waiting_period_ledgers"],
-      "additionalProperties": false,
-      "properties": {
-        "rate": {
-          "type": "string",
-          "description": "Cost per voucher in the payment asset (decimal string, e.g. '0.0001')"
-        },
-        "per": {
-          "type": "string",
-          "const": "voucher",
-          "description": "Billing unit — always 'voucher' for session mode"
-        },
-        "channel_contract": {
-          "type": "string",
-          "description": "Soroban contract address (C...) for the one-way-channel contract"
-        },
-        "min_deposit": {
-          "type": "string",
-          "description": "Minimum initial deposit to open a channel (decimal string)"
-        },
-        "refund_waiting_period_ledgers": {
-          "type": "integer",
-          "minimum": 1,
-          "description": "Ledgers the server has to settle before the funder can reclaim. Default: 17280 (~24h). Do not reduce in production."
-        }
-      }
-    }
-  }
-}

package/src/store/SessionStore.ts

@@ -1,90 +0,0 @@
-import type { SupabaseClient } from '@supabase/supabase-js'
-import type { SessionState } from '../types.js'
-import { RouteDockSessionError } from '../types.js'
-
-// ── Interface ──────────────────────────────────────────────────────────────────
-
-export interface SessionStore {
-  get(channelId: string): Promise<SessionState | null>
-  /** Enforce monotonic invariant at application level before writing */
-  upsert(channelId: string, state: SessionState): Promise<void>
-  close(channelId: string): Promise<void>
-}
-
-// ── Supabase implementation ────────────────────────────────────────────────────
-
-export class SupabaseSessionStore implements SessionStore {
-  constructor(private readonly supabase: SupabaseClient) {}
-
-  async get(channelId: string): Promise<SessionState | null> {
-    const { data, error } = await this.supabase
-      .from('sessions')
-      .select('*')
-      .eq('channel_id', channelId)
-      .maybeSingle()
-
-    if (error) throw new RouteDockSessionError(`SessionStore.get failed: ${error.message}`)
-    if (!data) return null
-
-    return {
-      channel_id: data.channel_id as string,
-      payee: data.payee as string,
-      payer: data.payer as string,
-      cumulative_amount: String(data.cumulative_amount),
-      last_signature: data.last_signature as string,
-      status: data.status as SessionState['status'],
-      opened_at: data.opened_at as string,
-      updated_at: data.updated_at as string,
-      settlement_tx_hash: data.settlement_tx_hash as string | null,
-    }
-  }
-
-  async upsert(channelId: string, state: SessionState): Promise<void> {
-    // Application-level monotonic invariant check — catches non-increasing
-    // amounts before hitting the DB trigger, giving a typed error.
-    const existing = await this.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}`,
-        )
-      }
-    }
-
-    const { error } = await this.supabase.from('sessions').upsert(
-      {
-        channel_id: state.channel_id,
-        payee: state.payee,
-        payer: state.payer,
-        cumulative_amount: state.cumulative_amount,
-        last_signature: state.last_signature,
-        status: state.status,
-        opened_at: state.opened_at,
-        updated_at: new Date().toISOString(),
-        settlement_tx_hash: state.settlement_tx_hash,
-      },
-      { onConflict: 'channel_id' },
-    )
-
-    if (error) {
-      // DB trigger will raise 'cumulative_amount must be strictly increasing'
-      if (error.message.includes('strictly increasing')) {
-        throw new RouteDockSessionError(
-          `cumulative_amount must be strictly increasing (DB): ${error.message}`,
-        )
-      }
-      throw new RouteDockSessionError(`SessionStore.upsert failed: ${error.message}`)
-    }
-  }
-
-  async close(channelId: string): Promise<void> {
-    const { error } = await this.supabase
-      .from('sessions')
-      .update({ status: 'closed', updated_at: new Date().toISOString() })
-      .eq('channel_id', channelId)
-
-    if (error) throw new RouteDockSessionError(`SessionStore.close failed: ${error.message}`)
-  }
-}

package/src/tests/smoke.test.ts

@@ -1,228 +0,0 @@
-/**
- * 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

@@ -1,165 +0,0 @@
-/**
- * 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

@@ -1,14 +0,0 @@
-{
-  "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

@@ -1,15 +0,0 @@
-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,
-})