@routedock/routedock 0.1.1 → 0.2.0

package/dist/SessionStore-CCVO0PHM.d.cts

@@ -1,152 +0,0 @@
-import { SupabaseClient } from '@supabase/supabase-js';
-
-/**
- * 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.
- */
-type PaymentMode = 'x402' | 'mpp-charge' | 'mpp-session';
-/** Per-request pricing config — used by x402 and mpp-charge modes */
-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 */
-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 */
-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 */
-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() */
-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() */
-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.
- */
-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;
-}
-declare class RouteDockError extends Error {
-    constructor(message: string);
-}
-/** Manifest fetch failed, schema invalid, or required fields missing */
-declare class RouteDockManifestError extends RouteDockError {
-    constructor(message: string);
-}
-/** No payment mode in the manifest is supported by this client */
-declare class RouteDockNoSupportedModeError extends RouteDockError {
-    constructor(message: string);
-}
-/** Session invariant violated (e.g. non-monotonic voucher amount) */
-declare class RouteDockSessionError extends RouteDockError {
-    constructor(message: string);
-}
-/** Local spend cap or on-chain policy rejected the payment */
-declare class RouteDockPolicyRejectedError extends RouteDockError {
-    readonly reason: string;
-    constructor(reason: string);
-}
-
-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>;
-}
-declare class SupabaseSessionStore implements SessionStore {
-    private readonly supabase;
-    constructor(supabase: SupabaseClient);
-    get(channelId: string): Promise<SessionState | null>;
-    upsert(channelId: string, state: SessionState): Promise<void>;
-    close(channelId: string): Promise<void>;
-}
-
-export { type PaymentMode as P, RouteDockError as R, type SessionCloseResult as S, type PaymentResult as a, type PricingConfig as b, type RouteDockManifest as c, RouteDockManifestError as d, RouteDockNoSupportedModeError as e, RouteDockPolicyRejectedError as f, RouteDockSessionError as g, type SessionHandle as h, type SessionPricingConfig as i, type SessionState as j, type SessionStore as k, SupabaseSessionStore as l };

package/dist/SessionStore-CCVO0PHM.d.ts

@@ -1,152 +0,0 @@
-import { SupabaseClient } from '@supabase/supabase-js';
-
-/**
- * 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.
- */
-type PaymentMode = 'x402' | 'mpp-charge' | 'mpp-session';
-/** Per-request pricing config — used by x402 and mpp-charge modes */
-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 */
-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 */
-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 */
-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() */
-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() */
-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.
- */
-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;
-}
-declare class RouteDockError extends Error {
-    constructor(message: string);
-}
-/** Manifest fetch failed, schema invalid, or required fields missing */
-declare class RouteDockManifestError extends RouteDockError {
-    constructor(message: string);
-}
-/** No payment mode in the manifest is supported by this client */
-declare class RouteDockNoSupportedModeError extends RouteDockError {
-    constructor(message: string);
-}
-/** Session invariant violated (e.g. non-monotonic voucher amount) */
-declare class RouteDockSessionError extends RouteDockError {
-    constructor(message: string);
-}
-/** Local spend cap or on-chain policy rejected the payment */
-declare class RouteDockPolicyRejectedError extends RouteDockError {
-    readonly reason: string;
-    constructor(reason: string);
-}
-
-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>;
-}
-declare class SupabaseSessionStore implements SessionStore {
-    private readonly supabase;
-    constructor(supabase: SupabaseClient);
-    get(channelId: string): Promise<SessionState | null>;
-    upsert(channelId: string, state: SessionState): Promise<void>;
-    close(channelId: string): Promise<void>;
-}
-
-export { type PaymentMode as P, RouteDockError as R, type SessionCloseResult as S, type PaymentResult as a, type PricingConfig as b, type RouteDockManifest as c, RouteDockManifestError as d, RouteDockNoSupportedModeError as e, RouteDockPolicyRejectedError as f, RouteDockSessionError as g, type SessionHandle as h, type SessionPricingConfig as i, type SessionState as j, type SessionStore as k, SupabaseSessionStore as l };

package/dist/routedockMiddleware-B7WTB3LT.d.cts

@@ -1,53 +0,0 @@
-import { RequestHandler } from 'express';
-import { P as PaymentMode, c as RouteDockManifest } from './SessionStore-CCVO0PHM.cjs';
-
-interface RouteDockMiddlewareOptions {
-    modes: PaymentMode[];
-    pricing: {
-        x402?: string;
-        'mpp-charge'?: string;
-        'mpp-session'?: {
-            rate: string;
-            channelContract: string;
-        };
-    };
-    asset: string;
-    /** Stellar Asset Contract address for the payment asset */
-    assetContract: string;
-    payee: string;
-    network: 'testnet' | 'mainnet';
-    /** Private key (S...) of the server/payee account */
-    payeeSecretKey: string;
-    /** Required for x402 mode */
-    facilitatorApiKey?: string;
-    /** Required for mpp-session mode — ed25519 public key (G...) for verifying commitments */
-    commitmentPublicKey?: string;
-    /** Full RouteDock manifest — served at /.well-known/routedock.json */
-    manifest: RouteDockManifest;
-    /** Called after each successful on-chain settlement */
-    onSettled?: (txHash: string, amount: string, mode: string) => Promise<void>;
-    /** Called when a new mpp-session is opened (first voucher received) */
-    onSessionOpen?: (channelId: string) => Promise<void>;
-    /** Called after each verified voucher in an mpp-session */
-    onVoucher?: (voucherIndex: number, cumulativeAmount: string) => Promise<void>;
-}
-/**
- * Express middleware factory for RouteDock provider endpoints.
- *
- * Automatically serves /.well-known/routedock.json and enforces payment
- * verification for all three modes (x402, mpp-charge, mpp-session).
- *
- * @example
- * ```ts
- * import { routedock } from '@routedock/sdk/provider'
- *
- * app.use('/price', routedock({
- *   modes: ['x402', 'mpp-charge'],
- *   pricing: { x402: '0.001', 'mpp-charge': '0.0008' },
- *   ...
- * }))
- * ```
- */
-declare function routedock(opts: RouteDockMiddlewareOptions): RequestHandler;
-
-export { type RouteDockMiddlewareOptions as R, routedock as r };

package/dist/routedockMiddleware-DRgdrycG.d.ts

@@ -1,53 +0,0 @@
-import { RequestHandler } from 'express';
-import { P as PaymentMode, c as RouteDockManifest } from './SessionStore-CCVO0PHM.js';
-
-interface RouteDockMiddlewareOptions {
-    modes: PaymentMode[];
-    pricing: {
-        x402?: string;
-        'mpp-charge'?: string;
-        'mpp-session'?: {
-            rate: string;
-            channelContract: string;
-        };
-    };
-    asset: string;
-    /** Stellar Asset Contract address for the payment asset */
-    assetContract: string;
-    payee: string;
-    network: 'testnet' | 'mainnet';
-    /** Private key (S...) of the server/payee account */
-    payeeSecretKey: string;
-    /** Required for x402 mode */
-    facilitatorApiKey?: string;
-    /** Required for mpp-session mode — ed25519 public key (G...) for verifying commitments */
-    commitmentPublicKey?: string;
-    /** Full RouteDock manifest — served at /.well-known/routedock.json */
-    manifest: RouteDockManifest;
-    /** Called after each successful on-chain settlement */
-    onSettled?: (txHash: string, amount: string, mode: string) => Promise<void>;
-    /** Called when a new mpp-session is opened (first voucher received) */
-    onSessionOpen?: (channelId: string) => Promise<void>;
-    /** Called after each verified voucher in an mpp-session */
-    onVoucher?: (voucherIndex: number, cumulativeAmount: string) => Promise<void>;
-}
-/**
- * Express middleware factory for RouteDock provider endpoints.
- *
- * Automatically serves /.well-known/routedock.json and enforces payment
- * verification for all three modes (x402, mpp-charge, mpp-session).
- *
- * @example
- * ```ts
- * import { routedock } from '@routedock/sdk/provider'
- *
- * app.use('/price', routedock({
- *   modes: ['x402', 'mpp-charge'],
- *   pricing: { x402: '0.001', 'mpp-charge': '0.0008' },
- *   ...
- * }))
- * ```
- */
-declare function routedock(opts: RouteDockMiddlewareOptions): RequestHandler;
-
-export { type RouteDockMiddlewareOptions as R, routedock as r };

package/src/client/ModeRouter.ts

@@ -1,104 +0,0 @@
-import Ajv from 'ajv'
-import type { RouteDockManifest, PaymentMode } from '../types.js'
-import { RouteDockManifestError, RouteDockNoSupportedModeError } from '../types.js'
-import schema from '../schemas/routedock.schema.json' assert { type: 'json' }
-
-const ajv = new Ajv()
-const validateManifest = ajv.compile(schema)
-
-interface CacheEntry {
-  manifest: RouteDockManifest
-  fetchedAt: number
-}
-
-const CACHE_TTL_MS = 60_000
-
-/** In-memory manifest cache keyed by base URL. */
-const manifestCache = new Map<string, CacheEntry>()
-
-export interface ModeSelectOptions {
-  /** Force mpp-session if the provider supports it */
-  sustained?: boolean
-  session?: boolean
-  /**
-   * Override mode selection and use this specific mode.
-   * Throws RouteDockNoSupportedModeError if the provider does not support it.
-   */
-  forceMode?: PaymentMode
-}
-
-/** Fetch, validate, and cache a RouteDock manifest from `baseUrl`. */
-export async function fetchManifest(baseUrl: string): Promise<RouteDockManifest> {
-  const cached = manifestCache.get(baseUrl)
-  if (cached && Date.now() - cached.fetchedAt < CACHE_TTL_MS) {
-    return cached.manifest
-  }
-
-  const url = baseUrl.replace(/\/$/, '') + '/.well-known/routedock.json'
-  let raw: unknown
-  try {
-    const resp = await fetch(url)
-    if (!resp.ok) {
-      throw new RouteDockManifestError(`Manifest fetch failed: HTTP ${resp.status} from ${url}`)
-    }
-    raw = await resp.json()
-  } catch (err) {
-    if (err instanceof RouteDockManifestError) throw err
-    throw new RouteDockManifestError(`Manifest fetch error: ${String(err)}`)
-  }
-
-  if (!validateManifest(raw)) {
-    const msgs = ajv.errorsText(validateManifest.errors)
-    throw new RouteDockManifestError(`Invalid manifest at ${url}: ${msgs}`)
-  }
-
-  const manifest = raw as unknown as RouteDockManifest
-  manifestCache.set(baseUrl, { manifest, fetchedAt: Date.now() })
-  return manifest
-}
-
-/**
- * Deterministic mode selection per Section 6.3 of ROUTEDOCK_MASTER.md:
- * 1. If { sustained | session } AND manifest supports mpp-session → mpp-session
- * 2. Else if manifest supports mpp-charge AND network is Stellar → mpp-charge
- * 3. Else if manifest supports x402 → x402
- * 4. Else throw RouteDockNoSupportedModeError
- */
-export function selectMode(
-  manifest: RouteDockManifest,
-  options: ModeSelectOptions = {},
-): PaymentMode {
-  const modes = manifest.modes
-
-  if (options.forceMode) {
-    if (!modes.includes(options.forceMode)) {
-      throw new RouteDockNoSupportedModeError(
-        `Provider does not support forced mode: ${options.forceMode} (available: ${modes.join(', ')})`,
-      )
-    }
-    console.log(`[RouteDock] ${manifest.name} → ${options.forceMode} (forced)`)
-    return options.forceMode
-  }
-
-  if ((options.sustained || options.session) && modes.includes('mpp-session')) {
-    const mode: PaymentMode = 'mpp-session'
-    console.log(`[RouteDock] ${manifest.name} → ${mode}`)
-    return mode
-  }
-
-  if (modes.includes('mpp-charge')) {
-    const mode: PaymentMode = 'mpp-charge'
-    console.log(`[RouteDock] ${manifest.name} → ${mode}`)
-    return mode
-  }
-
-  if (modes.includes('x402')) {
-    const mode: PaymentMode = 'x402'
-    console.log(`[RouteDock] ${manifest.name} → ${mode}`)
-    return mode
-  }
-
-  throw new RouteDockNoSupportedModeError(
-    `No supported payment mode found in manifest (modes: ${modes.join(', ')})`,
-  )
-}

package/src/client/MppChargeClient.ts

@@ -1,44 +0,0 @@
-import { Keypair } from '@stellar/stellar-sdk'
-import { stellar } from '@stellar/mpp/charge/client'
-import { Mppx } from 'mppx/client'
-import type { RouteDockManifest, PaymentResult } from '../types.js'
-import { RouteDockManifestError } from '../types.js'
-
-export class MppChargeClient {
-  constructor(
-    private readonly keypair: Keypair,
-    private readonly network: 'testnet' | 'mainnet',
-  ) {}
-
-  async pay(url: string, manifest: RouteDockManifest): Promise<PaymentResult> {
-    const pricing = manifest.pricing['mpp-charge']
-    if (!pricing) {
-      throw new RouteDockManifestError('manifest.pricing.mpp-charge missing')
-    }
-
-    let txHash: string | null = null
-
-    const mppx = Mppx.create({
-      polyfill: false,
-      methods: [
-        stellar.charge({
-          keypair: this.keypair,
-          mode: 'pull',
-          onProgress(event) {
-            if (event.type === 'paid') {
-              txHash = event.hash
-            }
-          },
-        }),
-      ],
-    })
-
-    const response = await mppx.fetch(url)
-    if (!response.ok) {
-      throw new RouteDockManifestError(`MPP charge failed: HTTP ${response.status}`)
-    }
-
-    const data = await response.json()
-    return { data, txHash, mode: 'mpp-charge', amount: pricing.amount, timestamp: Date.now() }
-  }
-}