@routedock/routedock 0.1.2 → 0.3.0

package/dist/testing.d.ts

@@ -0,0 +1,114 @@
+import { RequestHandler } from 'express';
+import { P as PaymentMode } from './logger-D8_Q2ytp.js';
+import { R as RouteDockMiddlewareOptions } from './routedockMiddleware-57gUaEMf.js';
+import 'mppx';
+import './MppSessionHandler-Bq4S-JTE.js';
+
+/**
+ * Loosen a production callback's return type so a plain sync test spy works,
+ * while keeping its exact parameter list (the real adapter's signature).
+ */
+type TestCallback<F> = F extends (...args: infer A) => unknown ? (...args: A) => void | Promise<void> : never;
+/**
+ * Provider settlement callbacks under test. Same parameter list as the real
+ * `RouteDockMiddlewareOptions` callbacks — including `payer` — but they accept
+ * sync or async fns so a plain test spy works without wrapping it in a Promise.
+ */
+interface MockRoutedockCallbacks {
+    /** Called after each (synthetic) on-chain settlement. */
+    onSettled?: TestCallback<NonNullable<RouteDockMiddlewareOptions['onSettled']>>;
+    /** Called once when a synthetic session is opened (first voucher). */
+    onSessionOpen?: TestCallback<NonNullable<RouteDockMiddlewareOptions['onSessionOpen']>>;
+    /** Called for each synthetic voucher in a session (1-based index). */
+    onVoucher?: TestCallback<NonNullable<RouteDockMiddlewareOptions['onVoucher']>>;
+}
+/** Synthetic settlement values handed to the callbacks. All optional — sensible defaults per mode. */
+interface SyntheticPayment {
+    /** On-chain tx hash passed to onSettled. Default: a fixed 64-hex string. */
+    txHash?: string;
+    /** Settled amount (x402 / mpp-charge) passed to onSettled. Default: '0.001'. */
+    amount?: string;
+    /** Channel address (session modes) passed to onSessionOpen. Default: a fixed C... address. */
+    channelId?: string;
+    /** Per-voucher rate (session modes), in decimal string. Default: '0.0001'. */
+    rate?: string;
+    /** Number of vouchers to emit before close (session modes). Default: 3. */
+    voucherCount?: number;
+    /**
+     * Payer passed to onSettled (4th arg) and onSessionOpen (2nd arg). Default: a
+     * valid Stellar G... account. Pass `null` to exercise the address-unavailable
+     * path; `null` is passed through untouched (an explicit null is not replaced
+     * by the default).
+     */
+    payer?: string | null;
+}
+interface MockRoutedockOptions extends MockRoutedockCallbacks {
+    /** Payment mode the synthetic payment uses. Default: 'x402'. */
+    mode?: PaymentMode;
+    /**
+     * 'auto-pass' (default): synthesize a successful settlement, invoke the
+     * configured callbacks with synthetic data, then call the route handler.
+     * 'auto-fail': respond with `failStatus` and skip both callbacks and handler.
+     */
+    payment?: 'auto-pass' | 'auto-fail';
+    /** Override the synthetic data handed to callbacks. */
+    synthetic?: SyntheticPayment;
+    /** HTTP status used on 'auto-fail'. Default: 402. */
+    failStatus?: number;
+}
+/** Synthetic settlement record attached to `req.routedock` for assertions. */
+interface MockSettlementRecord {
+    mode: PaymentMode;
+    txHash: string;
+    amount: string;
+    channelId?: string;
+    vouchers?: Array<{
+        index: number;
+        cumulativeAmount: string;
+    }>;
+}
+/**
+ * Drive a provider's settlement callbacks with synthetic data, with no Express
+ * request involved. Useful for unit-testing an `onSettled` (e.g. a Supabase
+ * write) in complete isolation. Returns the synthetic settlement record.
+ *
+ * Honors `payment: 'auto-fail'` by invoking no callbacks and returning null.
+ */
+declare function runMockSettlement(opts: MockRoutedockOptions): Promise<MockSettlementRecord | null>;
+/**
+ * Express middleware that mocks RouteDock payment verification — the testing
+ * counterpart to `routedock()`. Drop it in front of a route to drive that
+ * route's settlement callbacks with synthetic data, without any on-chain
+ * settlement, facilitator, or wallet. Think `msw` for RouteDock providers.
+ *
+ * On `payment: 'auto-pass'` (default) it invokes the configured callbacks with
+ * synthetic data and then calls the next handler (your route). On
+ * `payment: 'auto-fail'` it responds with `failStatus` (402 by default) and
+ * skips both the callbacks and the route handler — exactly as a real payment
+ * rejection would.
+ *
+ * The synthetic settlement is attached to `req.routedock` for assertions.
+ *
+ * @example
+ * ```ts
+ * import express from 'express'
+ * import request from 'supertest'
+ * import { createMockRoutedockMiddleware } from '@routedock/routedock/testing'
+ *
+ * const onSettled = vi.fn()
+ * const app = express()
+ * app.use('/price', createMockRoutedockMiddleware({ mode: 'x402', payment: 'auto-pass', onSettled }))
+ * app.get('/price', (_req, res) => res.json({ price: '42' }))
+ *
+ * await request(app).get('/price').expect(200)
+ * expect(onSettled).toHaveBeenCalledWith(
+ *   expect.any(String),
+ *   '0.001',
+ *   'x402',
+ *   expect.any(String), // payer
+ * )
+ * ```
+ */
+declare function createMockRoutedockMiddleware(opts?: MockRoutedockOptions): RequestHandler;
+
+export { type MockRoutedockCallbacks, type MockRoutedockOptions, type MockSettlementRecord, type SyntheticPayment, createMockRoutedockMiddleware, runMockSettlement };

package/dist/testing.js

@@ -0,0 +1,56 @@
+// src/testing/createMockRoutedockMiddleware.ts
+var DEFAULT_TX_HASH = "0000000000000000000000000000000000000000000000000000000000000000";
+var DEFAULT_CHANNEL_ID = "CCK4XOW3YKQUEZFONUTINKMSNW7SNMRQZURME5U3UP7E6WNGK7UHUCAH";
+var DEFAULT_PAYER = "GAIRCEIRCEIRCEIRCEIRCEIRCEIRCEIRCEIRCEIRCEIRCEIRCEIRCF6M";
+function format7(scaled) {
+  return (Number(scaled) / 1e7).toFixed(7);
+}
+function toScaled(decimal) {
+  const [whole, frac = ""] = decimal.split(".");
+  const fracPadded = (frac + "0000000").slice(0, 7);
+  return BigInt(whole + fracPadded);
+}
+async function runMockSettlement(opts) {
+  const mode = opts.mode ?? "x402";
+  if ((opts.payment ?? "auto-pass") === "auto-fail") return null;
+  const s = opts.synthetic ?? {};
+  const txHash = s.txHash ?? DEFAULT_TX_HASH;
+  const payer = s.payer === void 0 ? DEFAULT_PAYER : s.payer;
+  if (mode === "mpp-session" || mode === "mpp-session-ws") {
+    const channelId = s.channelId ?? DEFAULT_CHANNEL_ID;
+    const rate = toScaled(s.rate ?? "0.0001");
+    const count = s.voucherCount ?? 3;
+    if (opts.onSessionOpen) await opts.onSessionOpen(channelId, payer);
+    const vouchers = [];
+    for (let i = 1; i <= count; i++) {
+      const cumulativeAmount = format7(rate * BigInt(i));
+      vouchers.push({ index: i, cumulativeAmount });
+      if (opts.onVoucher) await opts.onVoucher(channelId, i, cumulativeAmount, "0000000000000000000000000000000000000000000000000000000000000000");
+    }
+    const totalPaid = format7(rate * BigInt(count));
+    if (opts.onSettled) await opts.onSettled(txHash, totalPaid, mode, payer);
+    return { mode, txHash, amount: totalPaid, channelId, vouchers };
+  }
+  const amount = s.amount ?? "0.001";
+  if (opts.onSettled) await opts.onSettled(txHash, amount, mode, payer);
+  return { mode, txHash, amount };
+}
+function createMockRoutedockMiddleware(opts = {}) {
+  const payment = opts.payment ?? "auto-pass";
+  const failStatus = opts.failStatus ?? 402;
+  return (req, res, next) => {
+    if (payment === "auto-fail") {
+      res.status(failStatus).json({
+        error: "payment required",
+        detail: "mock routedock middleware: payment=auto-fail"
+      });
+      return;
+    }
+    void runMockSettlement(opts).then((record) => {
+      if (record) req.routedock = record;
+      next();
+    }).catch((err) => next(err));
+  };
+}
+
+export { createMockRoutedockMiddleware, runMockSettlement };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@routedock/routedock",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "Unified payment execution layer for autonomous agents on Stellar",
   "license": "MIT",
   "repository": {
@@ -12,50 +12,170 @@
   "main": "dist/index.cjs",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "typesVersions": {
     "*": {
-      "client": ["dist/client.d.ts"],
-      "provider": ["dist/provider.d.ts"]
+      "client": [
+        "dist/client.d.ts"
+      ],
+      "provider": [
+        "dist/provider.d.ts"
+      ],
+      "react": [
+        "dist/react.d.ts"
+      ],
+      "testing": [
+        "dist/testing.d.ts"
+      ],
+      "provider/hono": [
+        "dist/provider/hono.d.ts"
+      ],
+      "provider/fastify": [
+        "dist/provider/fastify.d.ts"
+      ],
+      "schema": [
+        "dist/schema.d.ts"
+      ]
     }
   },
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
     },
     "./client": {
-      "types": "./dist/client.d.ts",
-      "import": "./dist/client.js",
-      "require": "./dist/client.cjs"
+      "import": {
+        "types": "./dist/client.d.ts",
+        "default": "./dist/client.js"
+      },
+      "require": {
+        "types": "./dist/client.d.cts",
+        "default": "./dist/client.cjs"
+      }
     },
     "./provider": {
-      "types": "./dist/provider.d.ts",
-      "import": "./dist/provider.js",
-      "require": "./dist/provider.cjs"
+      "import": {
+        "types": "./dist/provider.d.ts",
+        "default": "./dist/provider.js"
+      },
+      "require": {
+        "types": "./dist/provider.d.cts",
+        "default": "./dist/provider.cjs"
+      }
+    },
+    "./react": {
+      "import": {
+        "types": "./dist/react.d.ts",
+        "default": "./dist/react.js"
+      },
+      "require": {
+        "types": "./dist/react.d.cts",
+        "default": "./dist/react.cjs"
+      }
+    },
+    "./testing": {
+      "import": {
+        "types": "./dist/testing.d.ts",
+        "default": "./dist/testing.js"
+      },
+      "require": {
+        "types": "./dist/testing.d.cts",
+        "default": "./dist/testing.cjs"
+      }
+    },
+    "./provider/hono": {
+      "import": {
+        "types": "./dist/provider/hono.d.ts",
+        "default": "./dist/provider/hono.js"
+      },
+      "require": {
+        "types": "./dist/provider/hono.d.cts",
+        "default": "./dist/provider/hono.cjs"
+      }
+    },
+    "./provider/fastify": {
+      "import": {
+        "types": "./dist/provider/fastify.d.ts",
+        "default": "./dist/provider/fastify.js"
+      },
+      "require": {
+        "types": "./dist/provider/fastify.d.cts",
+        "default": "./dist/provider/fastify.cjs"
+      }
+    },
+    "./schema": {
+      "import": {
+        "types": "./dist/schema.d.ts",
+        "default": "./dist/schema.js"
+      },
+      "require": {
+        "types": "./dist/schema.d.cts",
+        "default": "./dist/schema.cjs"
+      }
     }
   },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit"
-  },
   "dependencies": {
+    "@cfworker/json-schema": "^4.0.0",
+    "@stellar/mpp": "^0.4.0",
     "@stellar/stellar-sdk": "^14.6.1",
     "@supabase/supabase-js": "^2.47.0",
     "@x402/core": "^2.9.0",
     "@x402/stellar": "^2.9.0",
-    "@stellar/mpp": "^0.4.0",
-    "ajv": "^8.17.1",
-    "mppx": "^0.5.7"
+    "mppx": "^0.5.7",
+    "@routedock/nulth-sdk": "0.2.1"
   },
   "peerDependencies": {
-    "express": "^4.18.0"
+    "express": "^4.18.0",
+    "fastify": "^4.0.0 || ^5.0.0",
+    "hono": "^4.0.0",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    },
+    "hono": {
+      "optional": true
+    },
+    "fastify": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
   },
   "devDependencies": {
+    "@happy-dom/global-registrator": "^15.11.7",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
     "@types/express": "^4.17.21",
     "@types/node": "^20.0.0",
+    "@types/react": "^19.0.0",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "express": "^4.18.0",
+    "fastify": "^5.0.0",
+    "hono": "^4.12.23",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
     "tsup": "^8.0.0",
-    "typescript": "^5.4.5"
+    "tsx": "^4.22.3",
+    "typescript": "^5.4.5",
+    "viem": "^2.52.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --experimental-test-module-mocks --test $(find src -name '*.test.ts' -o -name '*.test.tsx' | sort)"
   }
-}
+}

package/PUBLISH_CHECKLIST.md

@@ -1,70 +0,0 @@
-# @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/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 };