@routedock/routedock 0.1.0

package/PUBLISH_CHECKLIST.md

@@ -0,0 +1,70 @@
+# @routedock/sdk Publish Checklist
+
+Complete every step in order. Do not skip.
+
+## Pre-publish
+
+- [ ] **1. Build dist/**
+  ```bash
+  cd packages/sdk
+  pnpm build
+  ```
+  Verify: `dist/index.js`, `dist/index.cjs`, `dist/client.js`, `dist/client.cjs`, `dist/provider.js`, `dist/provider.cjs`, and all `.d.ts` files exist.
+
+- [ ] **2. Typecheck**
+  ```bash
+  pnpm typecheck
+  ```
+  Must exit with 0 errors.
+
+- [ ] **3. Smoke tests**
+  ```bash
+  pnpm test
+  ```
+  All 4 smoke tests must pass.
+
+- [ ] **4. Confirm no secrets in pack**
+  ```bash
+  npm pack --dry-run
+  ```
+  Scan the file list: no `.env`, no `*.pem`, no files containing `SECRET` in the name.
+
+- [ ] **5. Update `repository.url`**
+  In `packages/sdk/package.json`, replace `YOUR_ORG` with the actual GitHub org/user.
+
+## Publish
+
+- [ ] **6. Login to npm**
+  ```bash
+  npm login
+  ```
+  Verify you are logged in as the correct user: `npm whoami`
+
+- [ ] **7. Publish**
+  ```bash
+  cd packages/sdk
+  pnpm publish --access public
+  ```
+  The `--access public` flag is required for scoped packages (`@routedock/sdk`) to be publicly accessible.
+
+## Post-publish Verification
+
+- [ ] **8. Verify on npm registry**
+  ```bash
+  npm show @routedock/sdk
+  ```
+  Confirms: version 0.1.0, correct description, MIT license.
+
+- [ ] **9. Test install in a clean directory**
+  ```bash
+  mkdir /tmp/test-install && cd /tmp/test-install
+  npm init -y
+  npm install @routedock/sdk
+  node -e "const { RouteDockClient } = require('@routedock/sdk'); console.log('ok')"
+  ```
+
+- [ ] **10. Add npm badge to README.md**
+  Once published, update the root README with the live npm badge:
+  ```markdown
+  ![npm](https://img.shields.io/npm/v/@routedock/sdk)
+  ```

package/README.md

@@ -0,0 +1,88 @@
+# @routedock/sdk
+
+Unified payment execution layer for autonomous agents on Stellar. One SDK for x402, MPP charge, and MPP session — mode selected automatically from the provider's `routedock.json` manifest.
+
+## Install
+
+```bash
+npm install @routedock/sdk
+# or
+pnpm add @routedock/sdk
+```
+
+## Agent Usage
+
+```ts
+import { RouteDockClient } from '@routedock/sdk/client'
+import { Keypair } from '@stellar/stellar-sdk'
+
+const client = new RouteDockClient({
+  wallet: Keypair.fromSecret(process.env.AGENT_SECRET),
+  network: 'testnet',
+  spendCap: { daily: '1.00', asset: 'USDC' }, // optional local guard
+})
+
+// Single call — SDK reads manifest, picks mode automatically
+const result = await client.pay('https://provider.railway.app/price')
+// result.data   — response body
+// result.txHash — settlement hash (or null for session vouchers)
+// result.mode   — 'x402' | 'mpp-charge' | 'mpp-session'
+
+// Sustained streaming access
+const session = await client.openSession('https://provider.railway.app/stream/orderbook')
+for await (const update of session.stream()) {
+  console.log(update)
+  if (done) break
+}
+await session.close() // triggers on-chain settlement
+```
+
+## Provider Usage
+
+```ts
+import express from 'express'
+import { routedock, SupabaseSessionStore } from '@routedock/sdk/provider'
+import { createClient } from '@supabase/supabase-js'
+
+const app = express()
+
+// Price endpoint — x402 + MPP charge
+app.use('/price', routedock({
+  modes: ['x402', 'mpp-charge'],
+  pricing: { x402: '0.001', 'mpp-charge': '0.0008' },
+  asset: 'USDC',
+  payee: process.env.STELLAR_PAYEE_ADDRESS,
+  network: process.env.STELLAR_NETWORK as 'testnet' | 'mainnet',
+  facilitatorApiKey: process.env.OPENZEPPELIN_API_KEY,
+}))
+
+// Stream endpoint — MPP session only
+const store = new SupabaseSessionStore(createClient(process.env.SUPABASE_URL, process.env.SUPABASE_SERVICE_KEY))
+app.use('/stream/orderbook', routedock({
+  modes: ['mpp-session'],
+  pricing: { 'mpp-session': { rate: '0.0001', channelContract: process.env.CHANNEL_CONTRACT_ID } },
+  asset: 'USDC',
+  payee: process.env.STELLAR_PAYEE_ADDRESS,
+  network: process.env.STELLAR_NETWORK as 'testnet' | 'mainnet',
+  store,
+}))
+```
+
+## Mode Selection Logic
+
+The `ModeRouter` uses this decision tree (deterministic, no randomness):
+
+1. If `{ sustained: true }` passed AND manifest supports `mpp-session` → session
+2. Else if manifest supports `mpp-charge` AND network is Stellar → MPP charge (lower fees)
+3. Else if manifest supports `x402` → x402 with OZ facilitator
+4. Else throw `RouteDockNoSupportedModeError`
+
+Override with `{ forceMode: 'x402' }` to bypass auto-selection.
+
+## Security
+
+The `one-way-channel` Soroban contract wrapped by `MppSessionClient` is **unaudited** (`stellar-experimental/one-way-channel`). Safe defaults are enforced: 17280 ledger refund window, durable `SupabaseSessionStore` with monotonic invariant. Production use should await a formal audit.
+
+## License
+
+MIT

package/dist/SessionStore-CCVO0PHM.d.cts

@@ -0,0 +1,152 @@
+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

@@ -0,0 +1,152 @@
+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 };