@canister-software/consensus-cli 0.1.0-beta.4 → 0.1.0-beta.5

package/README.md

@@ -69,7 +69,7 @@ CONSENSUS_SERVER_URL=https://your-custom-node.example.com
 
 ## ProxyClient
 
-`ProxyClient(fetchWithPayment, options)` returns Express-compatible middleware that routes your outbound HTTP requests through Consensus proxy nodes, handling x402 payments automatically.
+`ProxyClient(fetchWithPayment, options)` returns a framework-agnostic proxy controller with Express-compatible middleware behavior. It routes outbound HTTP requests through Consensus proxy nodes and supports automatic spend-limit stand-down.
 
 ### ProxyClient Options
 
@@ -84,6 +84,10 @@ CONSENSUS_SERVER_URL=https://your-custom-node.example.com
 | `node_region` | `string` | — | Prefer proxy nodes in a specific geographic region. |
 | `node_domain` | `string` | — | Route through a specific node domain. |
 | `node_exclude` | `string` | — | Exclude a specific node domain from selection. |
+| `limit_usd` | `number` | — | Max proxy spend in USD (up to 6 decimals). When reached, proxying stands down to direct `fetch`. |
+| `on_limit_reached` | `(budget) => void` | — | Callback fired once when stand-down is activated. |
+
+Proxy spend tracking uses the fixed server price of `$0.0001` per paid `/proxy` request (cached hits are not charged).
 
 ### Auto Strategy (Default)
 
@@ -147,6 +151,26 @@ const response = await req.consensus.fetch(
 );
 ```
 
+### Framework-Agnostic Usage
+
+Use `runWithPath()` to scope interception in any server framework and `createFetch()` for explicit route-scoped fetch:
+
+```ts
+const proxy = ProxyClient(fetchWithPayment, {
+  mode: "exclusive",
+  routes: ["/api"],
+  limit_usd: 1.25,
+});
+
+await proxy.runWithPath("/api", async () => {
+  const response = await fetch("https://api.example.com/data");
+  console.log(await response.json());
+});
+
+const apiFetch = proxy.createFetch("/api");
+const directFetch = proxy.createFetch("/health");
+```
+
 ---
 
 ## SocketClient
@@ -160,8 +184,12 @@ const response = await req.consensus.fetch(
 | `openTimeoutMs` | `number` | `12000` | Milliseconds to wait for the WebSocket connection to open before timing out. |
 | `reconnectIntervalMs` | `number` | `2000` | Milliseconds between automatic reconnection attempts. |
 | `defaults` | `ConsensusSocketTokenParams` | — | Default token parameters applied to every `requestToken()` call unless overridden. |
+| `limit_usd` | `number` | — | Max WebSocket spend in USD (up to 6 decimals). If next token quote exceeds remaining budget, token request is blocked. |
+| `on_limit_reached` | `(budget) => void` | — | Callback fired once when the WebSocket spend limit is reached. |
 | `webSocketFactory` | `constructor` | auto-detected | Custom WebSocket constructor (browser `WebSocket` or `ws` for Node.js). Auto-detected if not provided. |
 
+WebSocket spend checks use a local quote from the known pricing model (`model`, `minutes`, `megabytes`) before token purchase, so there is no additional price-check round trip.
+
 ### Billing Models
 
 Token requests accept a `model` parameter to control how your session is billed:

package/dist/proxy-client.js

@@ -1,7 +1,11 @@
 import { AsyncLocalStorage } from "async_hooks";
 const DEFAULT_SERVER_URL = process.env.CONSENSUS_SERVER_URL || "https://consensus.canister.software";
+const USD_SCALE = 1_000_000;
+const PROXY_PAID_REQUEST_COST_USD = 0.0001;
 class ProxyClientError extends Error {
+    /** HTTP status from proxy response when available. */
     status;
+    /** Parsed proxy error payload when available. */
     data;
 }
 const proxyFetchContext = new AsyncLocalStorage();
@@ -81,6 +85,22 @@ function parseMaybeJson(text) {
         return text;
     }
 }
+function parseUsdToMicros(value, fieldName) {
+    if (typeof value === "undefined" || value === null)
+        return null;
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+        throw new TypeError(`${fieldName} must be a non-negative number`);
+    }
+    const micros = Math.round(value * USD_SCALE);
+    const normalized = micros / USD_SCALE;
+    if (Math.abs(normalized - value) > 1e-9) {
+        throw new TypeError(`${fieldName} supports at most 6 decimal places`);
+    }
+    return micros;
+}
+function microsToUsd(micros) {
+    return Number((micros / USD_SCALE).toFixed(6));
+}
 function normalizeBody(body, headers) {
     if (typeof body === "undefined" || body === null)
         return undefined;
@@ -116,6 +136,20 @@ function normalizeBody(body, headers) {
     }
     throw new Error(`Unsupported request body type: ${typeof body}`);
 }
+function bodyToInit(body, headers) {
+    const normalized = normalizeBody(body, headers);
+    if (typeof normalized === "undefined")
+        return undefined;
+    if (typeof normalized === "string")
+        return normalized;
+    if (typeof normalized === "object" &&
+        normalized !== null &&
+        !(normalized instanceof ArrayBuffer) &&
+        !ArrayBuffer.isView(normalized)) {
+        return JSON.stringify(normalized);
+    }
+    return normalized;
+}
 async function buildProxyPayload(input, init = {}, controlHeaders) {
     let targetUrl;
     let method = "GET";
@@ -181,9 +215,7 @@ function toFetchResponse(proxyResult, requestUrl) {
         : typeof payload === "string"
             ? payload
             : JSON.stringify(payload);
-    if (payload !== null &&
-        typeof payload === "object" &&
-        !headers.has("content-type")) {
+    if (payload !== null && typeof payload === "object" && !headers.has("content-type")) {
         headers.set("content-type", "application/json");
     }
     const response = new Response(body, {
@@ -202,6 +234,20 @@ function toFetchResponse(proxyResult, requestUrl) {
     });
     return response;
 }
+function responseHeadersToRecord(headers) {
+    const record = {};
+    headers.forEach((value, key) => {
+        record[key] = value;
+    });
+    return record;
+}
+function isLikelyPaidProxyResponse(proxyResult) {
+    const meta = proxyResult.meta;
+    if (meta && typeof meta === "object" && "cached" in meta) {
+        return meta.cached !== true;
+    }
+    return true;
+}
 function ensureInterceptorInstalled() {
     if (interceptorInstalled)
         return;
@@ -235,6 +281,60 @@ export function ProxyClient(fetchWithPayment, options = {}) {
     const serverUrl = trimTrailingSlash(DEFAULT_SERVER_URL);
     const proxyEndpoint = `${serverUrl}/proxy`;
     const baseControlHeaders = controlHeadersFromOptions(options);
+    const limitMicros = parseUsdToMicros(options.limit_usd, "limit_usd");
+    const requestCostMicros = parseUsdToMicros(PROXY_PAID_REQUEST_COST_USD, "proxy_request_cost_usd") ?? 0;
+    let spentMicros = 0;
+    let limitCallbackFired = false;
+    function computeStandDownState() {
+        if (limitMicros === null)
+            return false;
+        if (spentMicros >= limitMicros)
+            return true;
+        if (requestCostMicros <= 0)
+            return false;
+        return spentMicros + requestCostMicros > limitMicros;
+    }
+    function getBudget() {
+        const remainingMicros = limitMicros === null ? null : Math.max(0, limitMicros - spentMicros);
+        return {
+            limit_usd: limitMicros === null ? null : microsToUsd(limitMicros),
+            request_cost_usd: microsToUsd(requestCostMicros),
+            spent_usd: microsToUsd(spentMicros),
+            remaining_usd: remainingMicros === null ? null : microsToUsd(remainingMicros),
+            exhausted: computeStandDownState(),
+        };
+    }
+    function isStandDown() {
+        const exhausted = computeStandDownState();
+        if (exhausted &&
+            !limitCallbackFired &&
+            typeof options.on_limit_reached === "function") {
+            limitCallbackFired = true;
+            options.on_limit_reached(getBudget());
+        }
+        return exhausted;
+    }
+    function incrementSpend(proxyResult) {
+        if (requestCostMicros <= 0)
+            return;
+        if (!isLikelyPaidProxyResponse(proxyResult))
+            return;
+        spentMicros += requestCostMicros;
+        if (limitMicros !== null && spentMicros > limitMicros)
+            spentMicros = limitMicros;
+        isStandDown();
+    }
+    function resetBudget() {
+        spentMicros = 0;
+        limitCallbackFired = false;
+    }
+    async function passthroughFetchOrThrow(input, init) {
+        const directFetch = currentPassthroughFetch();
+        if (!directFetch) {
+            throw new ProxyClientError("Global fetch is unavailable; cannot bypass proxy while in stand-down mode.");
+        }
+        return directFetch(input, init);
+    }
     async function requestProxy(payload) {
         const response = await fetchWithPayment(proxyEndpoint, {
             method: "POST",
@@ -254,38 +354,99 @@ export function ProxyClient(fetchWithPayment, options = {}) {
         }
         return toProxyResult(response, parsed);
     }
+    async function requestDirectFromPayload(payload, reason) {
+        const targetUrl = String(payload.target_url || "").trim();
+        if (!targetUrl) {
+            throw new ProxyClientError("target_url is required when proxy is in stand-down mode");
+        }
+        const method = String(payload.method || "GET").toUpperCase();
+        const headers = normalizeHeaders(payload.headers);
+        const init = {
+            method,
+            headers,
+        };
+        if (!["GET", "HEAD"].includes(method) && typeof payload.body !== "undefined") {
+            const convertedBody = bodyToInit(payload.body, headers);
+            if (typeof convertedBody !== "undefined")
+                init.body = convertedBody;
+        }
+        const response = await passthroughFetchOrThrow(targetUrl, init);
+        const raw = await response.text();
+        const parsed = parseMaybeJson(raw);
+        return {
+            status: response.status,
+            statusText: response.statusText || "",
+            headers: responseHeadersToRecord(response.headers),
+            data: parsed,
+            meta: { bypassed: true, reason },
+        };
+    }
     async function proxiedFetch(input, init = {}, perRequestOptions = {}) {
+        if (isStandDown()) {
+            return passthroughFetchOrThrow(input, init);
+        }
         const controlHeaders = {
             ...baseControlHeaders,
             ...controlHeadersFromOptions(perRequestOptions),
         };
         const payload = await buildProxyPayload(input, init, controlHeaders);
         const proxyResult = await requestProxy(payload);
+        incrementSpend(proxyResult);
         const requestUrl = typeof Request !== "undefined" && input instanceof Request ? input.url : String(input);
         return toFetchResponse(proxyResult, requestUrl);
     }
     async function proxiedRequest(payload = {}, perRequestOptions = {}) {
+        if (isStandDown()) {
+            return requestDirectFromPayload(payload, "limit_reached");
+        }
         const controlHeaders = {
             ...baseControlHeaders,
             ...controlHeadersFromOptions(perRequestOptions),
             ...normalizeHeaders(payload.headers),
         };
-        return requestProxy({
+        const proxyResult = await requestProxy({
             target_url: String(payload.target_url || ""),
             method: String(payload.method || "GET").toUpperCase(),
             headers: controlHeaders,
             ...(typeof payload.body !== "undefined" ? { body: payload.body } : {}),
         });
+        incrementSpend(proxyResult);
+        return proxyResult;
+    }
+    function createFetch(pathname = "/") {
+        return (input, init) => {
+            if (!shouldProxyPath(pathname, options)) {
+                return passthroughFetchOrThrow(input, init);
+            }
+            return proxiedFetch(input, init);
+        };
+    }
+    async function runWithPath(pathname, run) {
+        if (typeof run !== "function") {
+            throw new TypeError("runWithPath requires a callback function");
+        }
+        ensureInterceptorInstalled();
+        const shouldProxy = shouldProxyPath(pathname, options);
+        return new Promise((resolve, reject) => {
+            proxyFetchContext.run({ proxyFetch: shouldProxy ? proxiedFetch : null }, () => {
+                Promise.resolve()
+                    .then(run)
+                    .then(resolve, reject);
+            });
+        });
     }
-    return (req, _res, next) => {
+    const middleware = ((req, _res, next) => {
         const routePath = req?.path || req?.url || "/";
-        const shouldProxy = shouldProxyPath(routePath, options);
+        const shouldProxy = shouldProxyPath(routePath, options) && !isStandDown();
         req.consensus = {
             strategy,
             shouldProxy,
             fetch: proxiedFetch,
             request: proxiedRequest,
             passthroughFetch: currentPassthroughFetch(),
+            createFetch,
+            getBudget,
+            isStandDown,
         };
         if (strategy !== "auto") {
             next();
@@ -293,5 +454,13 @@ export function ProxyClient(fetchWithPayment, options = {}) {
         }
         ensureInterceptorInstalled();
         proxyFetchContext.run({ proxyFetch: shouldProxy ? proxiedFetch : null }, () => next());
-    };
+    });
+    middleware.fetch = proxiedFetch;
+    middleware.request = proxiedRequest;
+    middleware.runWithPath = runWithPath;
+    middleware.createFetch = createFetch;
+    middleware.getBudget = getBudget;
+    middleware.resetBudget = resetBudget;
+    middleware.isStandDown = isStandDown;
+    return middleware;
 }

package/dist/socket-client.js

@@ -1,8 +1,31 @@
 const DEFAULT_SERVER_URL = process.env.CONSENSUS_SERVER_URL || "https://consensus.canister.software";
+const USD_SCALE = 1_000_000;
+const PRICING_PRESETS = {
+    TIME: {
+        model: "time",
+        pricePerMinute: 0.001,
+        pricePerMB: 0,
+    },
+    DATA: {
+        model: "data",
+        pricePerMinute: 0,
+        pricePerMB: 0.00012,
+    },
+    HYBRID: {
+        model: "hybrid",
+        pricePerMinute: 0.0005,
+        pricePerMB: 0.0001,
+    },
+};
 class SocketClientError extends Error {
+    /** HTTP status from token endpoint when available. */
     status;
+    /** Parsed server error payload when available. */
     data;
 }
+/** Thrown when requested token cost exceeds remaining websocket budget. */
+class SocketBudgetLimitError extends SocketClientError {
+}
 function trimTrailingSlash(value) {
     return String(value || "").replace(/\/+$/, "");
 }
@@ -16,6 +39,32 @@ function parseMaybeJson(text) {
         return text;
     }
 }
+function parseUsdToMicros(value, fieldName) {
+    if (typeof value === "undefined" || value === null)
+        return null;
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+        throw new TypeError(`${fieldName} must be a non-negative number`);
+    }
+    const micros = Math.round(value * USD_SCALE);
+    const normalized = micros / USD_SCALE;
+    if (Math.abs(normalized - value) > 1e-9) {
+        throw new TypeError(`${fieldName} supports at most 6 decimal places`);
+    }
+    return micros;
+}
+function microsToUsd(micros) {
+    return Number((micros / USD_SCALE).toFixed(6));
+}
+function calculateSessionCost(pricing, minutes, megabytes) {
+    let cost = 0;
+    if (pricing.model === "time" || pricing.model === "hybrid") {
+        cost += (minutes || 0) * pricing.pricePerMinute;
+    }
+    if (pricing.model === "data" || pricing.model === "hybrid") {
+        cost += (megabytes || 0) * pricing.pricePerMB;
+    }
+    return cost;
+}
 function normalizeTokenParams(defaults, params) {
     const merged = {
         model: params?.model ?? defaults?.model ?? "hybrid",
@@ -104,10 +153,73 @@ export function SocketClient(fetchWithPayment, options = {}) {
     const baseUrl = trimTrailingSlash(DEFAULT_SERVER_URL);
     const openTimeoutMs = options.openTimeoutMs ?? 12_000;
     const reconnectIntervalMs = options.reconnectIntervalMs ?? 2_000;
+    const limitMicros = parseUsdToMicros(options.limit_usd, "limit_usd");
     let lastTokenParams;
+    let spentMicros = 0;
+    let limitCallbackFired = false;
+    let lastQuoteMicros = 0;
+    function computeStandDownState(nextCostMicros = 0) {
+        if (limitMicros === null)
+            return false;
+        if (spentMicros >= limitMicros)
+            return true;
+        return spentMicros + nextCostMicros > limitMicros;
+    }
+    function getBudget() {
+        const remainingMicros = limitMicros === null ? null : Math.max(0, limitMicros - spentMicros);
+        return {
+            limit_usd: limitMicros === null ? null : microsToUsd(limitMicros),
+            spent_usd: microsToUsd(spentMicros),
+            remaining_usd: remainingMicros === null ? null : microsToUsd(remainingMicros),
+            exhausted: computeStandDownState(),
+            last_quote_usd: microsToUsd(lastQuoteMicros),
+        };
+    }
+    function isStandDown() {
+        const exhausted = computeStandDownState();
+        if (exhausted &&
+            !limitCallbackFired &&
+            typeof options.on_limit_reached === "function") {
+            limitCallbackFired = true;
+            options.on_limit_reached(getBudget());
+        }
+        return exhausted;
+    }
+    function ensureBudgetFor(quotedCostMicros) {
+        if (!computeStandDownState(quotedCostMicros))
+            return;
+        isStandDown();
+        throw new SocketBudgetLimitError("WebSocket budget limit reached; token request blocked");
+    }
+    function incrementSpend(quotedCostMicros) {
+        if (quotedCostMicros <= 0)
+            return;
+        spentMicros += quotedCostMicros;
+        if (limitMicros !== null && spentMicros > limitMicros)
+            spentMicros = limitMicros;
+        isStandDown();
+    }
+    function resetBudget() {
+        spentMicros = 0;
+        limitCallbackFired = false;
+        lastQuoteMicros = 0;
+    }
+    function quoteTokenCostMicros(params) {
+        const pricingKey = params.model === "time" ? "TIME" : params.model === "data" ? "DATA" : "HYBRID";
+        const pricing = PRICING_PRESETS[pricingKey];
+        const usd = calculateSessionCost(pricing, params.minutes, params.megabytes);
+        return parseUsdToMicros(usd, "session_cost_usd") ?? 0;
+    }
     async function requestTokenInternal(params) {
         const normalized = normalizeTokenParams(options.defaults, params);
         lastTokenParams = normalized;
+        const quotedCostMicros = quoteTokenCostMicros({
+            model: normalized.model,
+            minutes: normalized.minutes,
+            megabytes: normalized.megabytes,
+        });
+        lastQuoteMicros = quotedCostMicros;
+        ensureBudgetFor(quotedCostMicros);
         const query = new URLSearchParams({
             model: normalized.model,
             minutes: String(normalized.minutes),
@@ -132,6 +244,7 @@ export function SocketClient(fetchWithPayment, options = {}) {
         if (!auth?.connect_url || !auth?.token) {
             throw new SocketClientError("Invalid token response: missing token/connect_url");
         }
+        incrementSpend(quotedCostMicros);
         return {
             token: String(auth.token),
             connect_url: String(auth.connect_url),
@@ -251,6 +364,10 @@ export function SocketClient(fetchWithPayment, options = {}) {
                     catch (error) {
                         callbacks?.onError?.(error);
                         emit("error", error);
+                        if (error instanceof SocketBudgetLimitError) {
+                            state.reconnecting = false;
+                            return;
+                        }
                         if (!state.closedByCaller) {
                             reconnectTimer = setTimeout(async () => {
                                 if (!state.closedByCaller) {
@@ -265,6 +382,9 @@ export function SocketClient(fetchWithPayment, options = {}) {
                                     catch (retryError) {
                                         callbacks?.onError?.(retryError);
                                         emit("error", retryError);
+                                        if (retryError instanceof SocketBudgetLimitError) {
+                                            state.reconnecting = false;
+                                        }
                                     }
                                 }
                             }, reconnectIntervalMs);
@@ -313,5 +433,8 @@ export function SocketClient(fetchWithPayment, options = {}) {
     return {
         requestToken,
         connect,
+        getBudget,
+        resetBudget,
+        isStandDown,
     };
 }

package/index.d.ts

@@ -1,13 +1,100 @@
 export interface ProxyClientOptions {
+  /**
+   * Route filtering behavior for inbound server paths.
+   * - "inclusive": proxy everything except `routes`
+   * - "exclusive": proxy only `routes`
+   */
   mode?: "inclusive" | "exclusive";
+  /**
+   * Path rules used with `mode`, for example `["/health", "/metrics"]`.
+   * Query params are ignored; matching is based on path only.
+   */
   routes?: string[];
+  /**
+   * Path matcher behavior for `routes`.
+   * - false (default): exact path only (`/route` does not match `/route/subroute`)
+   * - true: include subroutes (`/route` matches `/route/*`)
+   */
   matchSubroutes?: boolean;
+  /**
+   * Interception strategy.
+   * - "auto": globally intercepts `fetch` for route-matched request scope
+   * - "manual": does not intercept global `fetch`; use `req.consensus.fetch` / `request`
+   */
   strategy?: "auto" | "manual";
+  /**
+   * Cache time-to-live in seconds for proxy responses.
+   * Sent as `x-cache-ttl`; controls how long deduped responses can be reused.
+   */
   cache_ttl?: number;
+  /**
+   * Enables verbose proxy response payload.
+   * When true, proxy responses include `meta` with fields like:
+   * `cached`, `dedupe_key`, `processing_ms`, and `timestamp`.
+   */
   verbose?: boolean;
+  /**
+   * Preferred proxy region, for example `"us-east"`.
+   * Sent as `x-node-region`.
+   */
   node_region?: string;
+  /**
+   * Force routing through a specific node domain, for example:
+   * `"nodexyz.consensus.canister.software"`.
+   * Sent as `x-node-domain`.
+   */
   node_domain?: string;
+  /**
+   * Exclude a specific node/domain from routing.
+   * Sent as `x-node-exclude`.
+   */
   node_exclude?: string;
+  /**
+   * Max proxy spend in USD (up to 6 decimals).
+   * Once exhausted, ProxyClient stands down and uses direct fetch.
+   */
+  limit_usd?: number;
+  /** Called once when proxy budget is exhausted and stand-down activates. */
+  on_limit_reached?: (budget: ProxyBudgetSnapshot) => void;
+}
+
+export interface ProxyBudgetSnapshot {
+  /** Configured max spend in USD, or null when no limit is configured. */
+  limit_usd: number | null;
+  /** Fixed server proxy charge per paid request. */
+  request_cost_usd: number;
+  /** Total spent so far in USD. */
+  spent_usd: number;
+  /** Remaining budget in USD, or null when unlimited. */
+  remaining_usd: number | null;
+  /** True when budget guard has disabled further proxying. */
+  exhausted: boolean;
+}
+
+export interface ProxyResponseShape {
+  /** HTTP status code returned by proxy response. */
+  status: number;
+  /** HTTP reason phrase from proxy response. */
+  statusText: string;
+  /** Response headers from the target/proxy response. */
+  headers: Record<string, string>;
+  /** Parsed payload body (JSON/object/string) returned by proxy. */
+  data: unknown;
+  /**
+   * Verbose metadata returned when `verbose` is enabled.
+   * Common fields:
+   * - `cached`: whether response came from proxy cache
+   * - `dedupe_key`: deduplication key used by proxy
+   * - `processing_ms`: end-to-end proxy processing duration
+   * - `timestamp`: ISO timestamp generated by proxy
+   */
+  meta: {
+    cached?: boolean;
+    dedupe_key?: string;
+    processing_ms?: number;
+    timestamp?: string;
+    [key: string]: unknown;
+  } | null;
 }
 
 export interface ProxyClientRequestContext {
@@ -27,23 +114,43 @@ export interface ProxyClientRequestContext {
         body?: unknown;
       },
       perRequestOptions?: Partial<ProxyClientOptions>
-    ) => Promise<{
-      status: number;
-      statusText: string;
-      headers: Record<string, string>;
-      data: unknown;
-      meta: unknown;
-    }>;
+    ) => Promise<ProxyResponseShape>;
     passthroughFetch?: ((input: RequestInfo | URL, init?: RequestInit) => Promise<Response>) | null;
+    createFetch?: (pathname?: string) => (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+    getBudget?: () => ProxyBudgetSnapshot;
+    isStandDown?: () => boolean;
   };
   [key: string]: unknown;
 }
 
-export type ProxyClientMiddleware = (
+export interface ProxyClientRuntime {
+  fetch(
+    input: RequestInfo | URL,
+    init?: RequestInit,
+    perRequestOptions?: Partial<ProxyClientOptions>
+  ): Promise<Response>;
+  request(
+    payload: {
+      target_url?: string;
+      method?: string;
+      headers?: Record<string, string>;
+      body?: unknown;
+    },
+    perRequestOptions?: Partial<ProxyClientOptions>
+  ): Promise<ProxyResponseShape>;
+  runWithPath<T>(pathname: string, run: () => T | Promise<T>): Promise<T>;
+  createFetch(pathname?: string): (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+  getBudget(): ProxyBudgetSnapshot;
+  resetBudget(): void;
+  isStandDown(): boolean;
+}
+
+export type ProxyClientMiddleware = ((
   req: ProxyClientRequestContext,
   res: unknown,
   next: (err?: unknown) => void
-) => void;
+) => void) &
+  ProxyClientRuntime;
 
 export declare function ProxyClient(
   fetchWithPayment: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>,
@@ -53,11 +160,17 @@ export declare function ProxyClient(
 export type ConsensusSocketModel = "hybrid" | "time" | "data";
 
 export interface ConsensusSocketTokenParams {
+  /** Billing model for session pricing. */
   model?: ConsensusSocketModel;
+  /** Session duration to purchase (integer minutes, >= 0). */
   minutes?: number;
+  /** Session data amount to purchase (integer MB, >= 0). */
   megabytes?: number;
+  /** Optional preferred node region for token/session routing (e.g. `"us-east"`). */
   nodeRegion?: string;
+  /** Optional hard route to a specific node domain (e.g. `"nodexyz.consensus.canister.software"`). */
   nodeDomain?: string;
+  /** Optional node/domain to exclude from routing. */
   nodeExclude?: string;
 }
 
@@ -101,10 +214,31 @@ export interface ConsensusSocketSession {
 }
 
 export interface ConsensusSocketClientOptions {
+  /** Custom WebSocket constructor; auto-detected when omitted. */
   webSocketFactory?: new (...args: unknown[]) => unknown;
+  /** Max time to wait for websocket open before failing (ms). */
   openTimeoutMs?: number;
+  /** Fixed reconnect delay (ms). */
   reconnectIntervalMs?: number;
+  /** Default token params merged into each requestToken call. */
   defaults?: ConsensusSocketTokenParams;
+  /** Max websocket spend in USD (up to 6 decimals) before token requests are blocked. */
+  limit_usd?: number;
+  /** Called once when websocket budget is exhausted. */
+  on_limit_reached?: (budget: ConsensusSocketBudgetSnapshot) => void;
+}
+
+export interface ConsensusSocketBudgetSnapshot {
+  /** Configured max spend in USD, or null when no limit is configured. */
+  limit_usd: number | null;
+  /** Total spent so far in USD. */
+  spent_usd: number;
+  /** Remaining budget in USD, or null when unlimited. */
+  remaining_usd: number | null;
+  /** True when budget guard blocks further token purchases. */
+  exhausted: boolean;
+  /** Last locally quoted token/session price in USD. */
+  last_quote_usd: number;
 }
 
 export interface ConsensusSocketClient {
@@ -126,6 +260,9 @@ export interface ConsensusSocketClient {
     callbacks: ConsensusSocketCallbacks | undefined,
     options: { safe: true }
   ): Promise<ConsensusSocketSafeResult<ConsensusSocketSession>>;
+  getBudget(): ConsensusSocketBudgetSnapshot;
+  resetBudget(): void;
+  isStandDown(): boolean;
 }
 
 export declare function SocketClient(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canister-software/consensus-cli",
-  "version": "0.1.0-beta.4",
+  "version": "0.1.0-beta.5",
   "description": "Consensus SDK for interacting with the Consensus protocol",
   "type": "module",
   "main": "./dist/index.js",