@sequence0/sdk 0.1.0 → 1.0.1

package/dist/utils/http.js

@@ -2,30 +2,242 @@
 /**
  * Lightweight HTTP client for Sequence0 agent node REST API
  *
- * Uses native fetch — works in Node.js 18+ and all modern browsers.
+ * Uses native fetch -- works in Node.js 18+ and all modern browsers.
+ * Includes client-side rate limiting, automatic retries with exponential
+ * backoff, request/response debug logging, response validation, and
+ * a per-host circuit breaker to fail fast on unreachable agents.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HttpClient = void 0;
+exports.HttpClient = exports.CircuitBreaker = exports.CircuitBreakerError = void 0;
 const errors_1 = require("./errors");
+const rate_limiter_1 = require("./rate-limiter");
+const logger_1 = require("./logger");
+/**
+ * Thrown when a request is rejected because the circuit breaker is OPEN.
+ * The caller should select a different agent or wait for the cooldown.
+ */
+class CircuitBreakerError extends errors_1.Sequence0Error {
+    constructor(host, timeUntilHalfOpen) {
+        super(`Circuit breaker OPEN for ${host} — requests rejected for ${Math.ceil(timeUntilHalfOpen / 1000)}s`, 'CIRCUIT_OPEN');
+        this.host = host;
+        this.timeUntilHalfOpen = timeUntilHalfOpen;
+        this.name = 'CircuitBreakerError';
+    }
+}
+exports.CircuitBreakerError = CircuitBreakerError;
+/**
+ * Per-host circuit breaker.
+ *
+ * States:
+ *   CLOSED   — normal operation, requests pass through
+ *   OPEN     — failing, requests are rejected immediately
+ *   HALF_OPEN — testing recovery, one request is allowed through
+ *
+ * Transitions:
+ *   CLOSED   → OPEN      after `failureThreshold` consecutive failures
+ *   OPEN     → HALF_OPEN after `cooldownMs` elapses
+ *   HALF_OPEN → CLOSED   on first success
+ *   HALF_OPEN → OPEN     on first failure
+ */
+class CircuitBreaker {
+    constructor(options = {}) {
+        this.states = new Map();
+        this.failureCounts = new Map();
+        this.lastFailureTimes = new Map();
+        this.failureThreshold = options.failureThreshold ?? 3;
+        this.cooldownMs = options.cooldownMs ?? 30000;
+    }
+    /**
+     * Check whether a request to the given host is allowed.
+     * Throws CircuitBreakerError if the circuit is OPEN and cooldown has not elapsed.
+     */
+    allowRequest(host) {
+        const state = this.getState(host);
+        if (state === 'CLOSED' || state === 'HALF_OPEN') {
+            return; // Request allowed
+        }
+        // OPEN — check if cooldown has elapsed → transition to HALF_OPEN
+        const lastFailure = this.lastFailureTimes.get(host) ?? 0;
+        const elapsed = Date.now() - lastFailure;
+        if (elapsed >= this.cooldownMs) {
+            this.states.set(host, 'HALF_OPEN');
+            return; // Allow one probe request
+        }
+        throw new CircuitBreakerError(host, this.cooldownMs - elapsed);
+    }
+    /**
+     * Record a successful request. Resets the circuit to CLOSED.
+     */
+    recordSuccess(host) {
+        this.states.set(host, 'CLOSED');
+        this.failureCounts.set(host, 0);
+    }
+    /**
+     * Record a failed request. Increments failure count and may trip the circuit.
+     */
+    recordFailure(host) {
+        const state = this.getState(host);
+        if (state === 'HALF_OPEN') {
+            // HALF_OPEN → OPEN on first failure
+            this.states.set(host, 'OPEN');
+            this.lastFailureTimes.set(host, Date.now());
+            return;
+        }
+        // CLOSED — increment failure count
+        const count = (this.failureCounts.get(host) ?? 0) + 1;
+        this.failureCounts.set(host, count);
+        this.lastFailureTimes.set(host, Date.now());
+        if (count >= this.failureThreshold) {
+            this.states.set(host, 'OPEN');
+        }
+    }
+    /**
+     * Get the current state for a host (defaults to CLOSED).
+     */
+    getState(host) {
+        return this.states.get(host) ?? 'CLOSED';
+    }
+    /**
+     * Reset the circuit breaker for a specific host.
+     */
+    reset(host) {
+        this.states.delete(host);
+        this.failureCounts.delete(host);
+        this.lastFailureTimes.delete(host);
+    }
+    /**
+     * Reset all circuit breakers.
+     */
+    resetAll() {
+        this.states.clear();
+        this.failureCounts.clear();
+        this.lastFailureTimes.clear();
+    }
+}
+exports.CircuitBreaker = CircuitBreaker;
+// ── Keep-Alive ────────────────────────────────────────────────────
+/** Default keep-alive timeout in ms */
+const KEEP_ALIVE_TIMEOUT_MS = 30000;
+/** HTTP status codes that are safe to retry */
+const RETRYABLE_STATUS_CODES = new Set([408, 429, 500, 502, 503, 504]);
 class HttpClient {
     constructor(options) {
         this.baseUrl = options.baseUrl.replace(/\/$/, '');
         this.timeout = options.timeout || 30000;
+        this.maxRetries = options.maxRetries ?? 3;
+        // Extract host from baseUrl for circuit breaker keying
+        try {
+            const parsed = new URL(this.baseUrl);
+            this.host = parsed.host;
+        }
+        catch {
+            this.host = this.baseUrl;
+        }
+        // Build headers with keep-alive support
+        const keepAlive = options.keepAlive !== false; // default: true
+        const keepAliveTimeout = Math.floor((options.keepAliveTimeout ?? KEEP_ALIVE_TIMEOUT_MS) / 1000);
         this.headers = {
             'Content-Type': 'application/json',
+            ...(keepAlive
+                ? {
+                    Connection: 'keep-alive',
+                    'Keep-Alive': `timeout=${keepAliveTimeout}`,
+                }
+                : {}),
             ...options.headers,
         };
+        // Set up rate limiter (enabled by default)
+        if (options.rateLimiter === false) {
+            this.rateLimiter = null;
+        }
+        else {
+            this.rateLimiter = new rate_limiter_1.RateLimiter(options.rateLimiter || {});
+        }
+        // Set up logger
+        if (options.logger) {
+            this.logger = options.logger;
+        }
+        else if (options.debug) {
+            this.logger = new logger_1.DebugLogger(true);
+        }
+        else {
+            this.logger = new logger_1.NullLogger();
+        }
+        // Circuit breaker (optional, shared instance recommended)
+        this.circuitBreaker = options.circuitBreaker ?? null;
     }
     async get(path) {
-        return this.request('GET', path);
+        return this.requestWithRetry('GET', path);
     }
     async post(path, body) {
-        return this.request('POST', path, body);
+        return this.requestWithRetry('POST', path, body);
+    }
+    /**
+     * Destroy internal resources (rate limiter timers, etc.)
+     */
+    destroy() {
+        if (this.rateLimiter) {
+            this.rateLimiter.destroy();
+        }
+    }
+    /**
+     * Request with circuit breaker check, automatic retries, and exponential backoff.
+     */
+    async requestWithRetry(method, path, body) {
+        // Check circuit breaker before attempting any requests
+        if (this.circuitBreaker) {
+            this.circuitBreaker.allowRequest(this.host);
+        }
+        let lastError = null;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            try {
+                const result = await this.request(method, path, body, attempt);
+                // Record success with circuit breaker
+                if (this.circuitBreaker) {
+                    this.circuitBreaker.recordSuccess(this.host);
+                }
+                return result;
+            }
+            catch (error) {
+                lastError = error;
+                // Don't retry on non-retryable errors
+                if (error instanceof errors_1.NetworkError && error.statusCode) {
+                    if (!RETRYABLE_STATUS_CODES.has(error.statusCode)) {
+                        throw error;
+                    }
+                }
+                // Don't retry on the last attempt
+                if (attempt >= this.maxRetries) {
+                    break;
+                }
+                // Exponential backoff: 200ms, 400ms, 800ms, ...
+                const delay = Math.min(200 * Math.pow(2, attempt), 5000);
+                this.logger.warn(`Retrying ${method} ${path} (attempt ${attempt + 1}/${this.maxRetries})`, {
+                    delay,
+                    error: lastError.message,
+                });
+                await sleep(delay);
+            }
+        }
+        // All retries exhausted — record failure with circuit breaker
+        if (this.circuitBreaker) {
+            this.circuitBreaker.recordFailure(this.host);
+        }
+        throw lastError;
     }
-    async request(method, path, body) {
+    async request(method, path, body, attempt = 0) {
+        // Acquire rate limiter token before making the request
+        if (this.rateLimiter) {
+            await this.rateLimiter.acquire();
+        }
         const url = `${this.baseUrl}${path}`;
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), this.timeout);
+        const startTime = Date.now();
+        this.logger.debug(`${method} ${path}`, {
+            attempt,
+            ...(body && typeof body === 'object' ? { body_keys: Object.keys(body) } : {}),
+        });
         try {
             const response = await fetch(url, {
                 method,
@@ -33,6 +245,7 @@ class HttpClient {
                 body: body ? JSON.stringify(body) : undefined,
                 signal: controller.signal,
             });
+            const latency = Date.now() - startTime;
             if (!response.ok) {
                 const errorBody = await response.text().catch(() => '');
                 let errorMessage;
@@ -43,16 +256,32 @@ class HttpClient {
                 catch {
                     errorMessage = errorBody || `HTTP ${response.status}`;
                 }
+                this.logger.warn(`${method} ${path} -> ${response.status}`, {
+                    latency,
+                    status: response.status,
+                    error: errorMessage,
+                });
                 throw new errors_1.NetworkError(`${method} ${path} failed: ${errorMessage}`, response.status);
             }
-            return (await response.json());
+            const responseData = await response.json();
+            this.logger.debug(`${method} ${path} -> ${response.status}`, {
+                latency,
+                status: response.status,
+            });
+            return responseData;
         }
         catch (error) {
+            const latency = Date.now() - startTime;
             if (error instanceof errors_1.NetworkError)
                 throw error;
             if (error.name === 'AbortError') {
+                this.logger.warn(`${method} ${path} -> TIMEOUT`, { latency });
                 throw new errors_1.TimeoutError(`Request to ${path} timed out after ${this.timeout}ms`);
             }
+            this.logger.warn(`${method} ${path} -> NETWORK_ERROR`, {
+                latency,
+                error: error.message,
+            });
             throw new errors_1.NetworkError(`Failed to connect to ${url}: ${error.message}`);
         }
         finally {
@@ -61,4 +290,7 @@ class HttpClient {
     }
 }
 exports.HttpClient = HttpClient;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 //# sourceMappingURL=http.js.map

package/dist/utils/http.js.map

@@ -1 +1 @@
-{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/utils/http.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAEH,qCAAsD;AAWtD,MAAa,UAAU;IAKnB,YAAY,OAAoB;QAC5B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAClD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,KAAM,CAAC;QACzC,IAAI,CAAC,OAAO,GAAG;YACX,cAAc,EAAE,kBAAkB;YAClC,GAAG,OAAO,CAAC,OAAO;SACrB,CAAC;IACN,CAAC;IAED,KAAK,CAAC,GAAG,CAAI,IAAY;QACrB,OAAO,IAAI,CAAC,OAAO,CAAI,KAAK,EAAE,IAAI,CAAC,CAAC;IACxC,CAAC;IAED,KAAK,CAAC,IAAI,CAAI,IAAY,EAAE,IAAc;QACtC,OAAO,IAAI,CAAC,OAAO,CAAI,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAC/C,CAAC;IAEO,KAAK,CAAC,OAAO,CAAI,MAAc,EAAE,IAAY,EAAE,IAAc;QACjE,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE,CAAC;QACrC,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAEjE,IAAI,CAAC;YACD,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;gBAC9B,MAAM;gBACN,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;gBAC7C,MAAM,EAAE,UAAU,CAAC,MAAM;aAC5B,CAAC,CAAC;YAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACf,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;gBACxD,IAAI,YAAoB,CAAC;gBACzB,IAAI,CAAC;oBACD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;oBACrC,YAAY,GAAG,MAAM,CAAC,KAAK,IAAI,SAAS,CAAC;gBAC7C,CAAC;gBAAC,MAAM,CAAC;oBACL,YAAY,GAAG,SAAS,IAAI,QAAQ,QAAQ,CAAC,MAAM,EAAE,CAAC;gBAC1D,CAAC;gBACD,MAAM,IAAI,qBAAY,CAClB,GAAG,MAAM,IAAI,IAAI,YAAY,YAAY,EAAE,EAC3C,QAAQ,CAAC,MAAM,CAClB,CAAC;YACN,CAAC;YAED,OAAO,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAM,CAAC;QACxC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,IAAI,KAAK,YAAY,qBAAY;gBAAE,MAAM,KAAK,CAAC;YAC/C,IAAK,KAAe,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;gBACzC,MAAM,IAAI,qBAAY,CAAC,cAAc,IAAI,oBAAoB,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC;YACnF,CAAC;YACD,MAAM,IAAI,qBAAY,CAAC,wBAAwB,GAAG,KAAM,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;QACvF,CAAC;gBAAS,CAAC;YACP,YAAY,CAAC,KAAK,CAAC,CAAC;QACxB,CAAC;IACL,CAAC;CACJ;AA7DD,gCA6DC"}
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/utils/http.ts"],"names":[],"mappings":"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"}

package/dist/utils/logger.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Debug Logger for Sequence0 SDK
+ *
+ * Optional logging that never exposes sensitive data:
+ * - Private keys are never logged
+ * - Wallet addresses are masked: 0x1234...abcd
+ * - Full signatures are never logged
+ * - Only method, endpoint, status code, and latency are logged
+ */
+export interface Logger {
+    debug(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+}
+/**
+ * Mask an address for safe debug logging.
+ * "0x1234567890abcdef..." -> "0x1234...cdef"
+ */
+export declare function maskAddress(address: string): string;
+/**
+ * Mask sensitive fields in an object for safe logging.
+ * Returns a new object — never mutates the original.
+ */
+export declare function maskSensitive(data: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Default console-based debug logger.
+ * Only logs when debug mode is enabled.
+ */
+export declare class DebugLogger implements Logger {
+    private enabled;
+    private prefix;
+    constructor(enabled?: boolean, prefix?: string);
+    debug(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+}
+/** No-op logger that suppresses all output */
+export declare class NullLogger implements Logger {
+    debug(): void;
+    warn(): void;
+    error(): void;
+}
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,MAAM;IACnB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC7D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAChE;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAanD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAkDpF;AAED;;;GAGG;AACH,qBAAa,WAAY,YAAW,MAAM;IACtC,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,MAAM,CAAS;gBAEX,OAAO,UAAQ,EAAE,MAAM,SAAgB;IAKnD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAU5D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAU3D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;CAS/D;AAED,8CAA8C;AAC9C,qBAAa,UAAW,YAAW,MAAM;IACrC,KAAK,IAAI,IAAI;IACb,IAAI,IAAI,IAAI;IACZ,KAAK,IAAI,IAAI;CAChB"}

package/dist/utils/logger.js

@@ -0,0 +1,129 @@
+"use strict";
+/**
+ * Debug Logger for Sequence0 SDK
+ *
+ * Optional logging that never exposes sensitive data:
+ * - Private keys are never logged
+ * - Wallet addresses are masked: 0x1234...abcd
+ * - Full signatures are never logged
+ * - Only method, endpoint, status code, and latency are logged
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NullLogger = exports.DebugLogger = void 0;
+exports.maskAddress = maskAddress;
+exports.maskSensitive = maskSensitive;
+/**
+ * Mask an address for safe debug logging.
+ * "0x1234567890abcdef..." -> "0x1234...cdef"
+ */
+function maskAddress(address) {
+    if (!address || address.length < 10)
+        return '***';
+    if (address.startsWith('0x') && address.length >= 12) {
+        return `${address.slice(0, 6)}...${address.slice(-4)}`;
+    }
+    // Non-EVM addresses
+    if (address.length >= 12) {
+        return `${address.slice(0, 6)}...${address.slice(-4)}`;
+    }
+    return '***';
+}
+/**
+ * Mask sensitive fields in an object for safe logging.
+ * Returns a new object — never mutates the original.
+ */
+function maskSensitive(data) {
+    const masked = {};
+    for (const [key, value] of Object.entries(data)) {
+        const lowerKey = key.toLowerCase();
+        // Never log these
+        if (lowerKey.includes('privatekey') ||
+            lowerKey.includes('private_key') ||
+            lowerKey.includes('secret') ||
+            lowerKey.includes('mnemonic') ||
+            lowerKey.includes('seed') ||
+            lowerKey === 'apikey' ||
+            lowerKey === 'api_key') {
+            masked[key] = '[REDACTED]';
+            continue;
+        }
+        // Mask signatures (show only prefix)
+        if (lowerKey === 'signature' || lowerKey === 'sig') {
+            if (typeof value === 'string' && value.length > 16) {
+                masked[key] = `${value.slice(0, 10)}...[${value.length} chars]`;
+            }
+            else {
+                masked[key] = value;
+            }
+            continue;
+        }
+        // Mask addresses
+        if (lowerKey === 'address' || lowerKey === 'from' || lowerKey === 'to') {
+            if (typeof value === 'string') {
+                masked[key] = maskAddress(value);
+            }
+            else {
+                masked[key] = value;
+            }
+            continue;
+        }
+        // Recursively mask nested objects
+        if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+            masked[key] = maskSensitive(value);
+            continue;
+        }
+        masked[key] = value;
+    }
+    return masked;
+}
+/**
+ * Default console-based debug logger.
+ * Only logs when debug mode is enabled.
+ */
+class DebugLogger {
+    constructor(enabled = false, prefix = '[Sequence0]') {
+        this.enabled = enabled;
+        this.prefix = prefix;
+    }
+    debug(message, meta) {
+        if (!this.enabled)
+            return;
+        const safe = meta ? maskSensitive(meta) : undefined;
+        if (safe) {
+            console.debug(`${this.prefix} ${message}`, safe);
+        }
+        else {
+            console.debug(`${this.prefix} ${message}`);
+        }
+    }
+    warn(message, meta) {
+        if (!this.enabled)
+            return;
+        const safe = meta ? maskSensitive(meta) : undefined;
+        if (safe) {
+            console.warn(`${this.prefix} ${message}`, safe);
+        }
+        else {
+            console.warn(`${this.prefix} ${message}`);
+        }
+    }
+    error(message, meta) {
+        // Errors are always logged, even if debug is off
+        const safe = meta ? maskSensitive(meta) : undefined;
+        if (safe) {
+            console.error(`${this.prefix} ${message}`, safe);
+        }
+        else {
+            console.error(`${this.prefix} ${message}`);
+        }
+    }
+}
+exports.DebugLogger = DebugLogger;
+/** No-op logger that suppresses all output */
+class NullLogger {
+    debug() { }
+    warn() { }
+    error() { }
+}
+exports.NullLogger = NullLogger;
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"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"}

package/dist/utils/rate-limiter.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Client-Side Rate Limiter (Token Bucket)
+ *
+ * Prevents clients from exceeding the server's rate limit (100 req/s on mainnet)
+ * by throttling outgoing requests. Excess requests are queued rather
+ * than rejected, so callers never see a rate-limit error from the SDK.
+ */
+export interface RateLimiterOptions {
+    /** Maximum requests per second (default: 25, under server's 100/s mainnet limit) */
+    maxRequestsPerSecond?: number;
+    /** Maximum queued requests before rejecting (default: 100) */
+    maxQueueSize?: number;
+}
+export declare class RateLimiter {
+    private tokens;
+    private maxTokens;
+    private refillRate;
+    private lastRefill;
+    private queue;
+    private maxQueueSize;
+    private drainTimer;
+    constructor(options?: RateLimiterOptions);
+    /**
+     * Acquire a token before making a request.
+     * Resolves immediately if tokens are available, otherwise queues.
+     */
+    acquire(): Promise<void>;
+    /**
+     * Get current state for debugging.
+     */
+    get state(): {
+        tokens: number;
+        queued: number;
+    };
+    /**
+     * Cancel all queued requests and stop the drain timer.
+     */
+    destroy(): void;
+    private refill;
+    private scheduleDrain;
+    private drain;
+}
+//# sourceMappingURL=rate-limiter.d.ts.map

package/dist/utils/rate-limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../../src/utils/rate-limiter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,kBAAkB;IAC/B,oFAAoF;IACpF,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;CACzB;AAOD,qBAAa,WAAW;IACpB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,KAAK,CAAoB;IACjC,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,UAAU,CAA8C;gBAEpD,OAAO,GAAE,kBAAuB;IAS5C;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAsB9B;;OAEG;IACH,IAAI,KAAK,IAAI;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAM9C;IAED;;OAEG;IACH,OAAO,IAAI,IAAI;IAcf,OAAO,CAAC,MAAM;IASd,OAAO,CAAC,aAAa;IAYrB,OAAO,CAAC,KAAK;CAchB"}

package/dist/utils/rate-limiter.js

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * Client-Side Rate Limiter (Token Bucket)
+ *
+ * Prevents clients from exceeding the server's rate limit (100 req/s on mainnet)
+ * by throttling outgoing requests. Excess requests are queued rather
+ * than rejected, so callers never see a rate-limit error from the SDK.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RateLimiter = void 0;
+class RateLimiter {
+    constructor(options = {}) {
+        this.queue = [];
+        this.drainTimer = null;
+        const rps = options.maxRequestsPerSecond ?? 25;
+        this.maxTokens = rps;
+        this.tokens = rps;
+        this.refillRate = rps / 1000; // tokens per ms
+        this.lastRefill = Date.now();
+        this.maxQueueSize = options.maxQueueSize ?? 100;
+    }
+    /**
+     * Acquire a token before making a request.
+     * Resolves immediately if tokens are available, otherwise queues.
+     */
+    async acquire() {
+        this.refill();
+        if (this.tokens >= 1) {
+            this.tokens -= 1;
+            return;
+        }
+        // No tokens available — queue the request
+        if (this.queue.length >= this.maxQueueSize) {
+            throw new Error(`Rate limiter queue full (${this.maxQueueSize} pending requests). ` +
+                'Reduce request rate or increase maxQueueSize.');
+        }
+        return new Promise((resolve, reject) => {
+            this.queue.push({ resolve, reject });
+            this.scheduleDrain();
+        });
+    }
+    /**
+     * Get current state for debugging.
+     */
+    get state() {
+        this.refill();
+        return {
+            tokens: Math.floor(this.tokens),
+            queued: this.queue.length,
+        };
+    }
+    /**
+     * Cancel all queued requests and stop the drain timer.
+     */
+    destroy() {
+        if (this.drainTimer) {
+            clearTimeout(this.drainTimer);
+            this.drainTimer = null;
+        }
+        const err = new Error('Rate limiter destroyed');
+        for (const entry of this.queue) {
+            entry.reject(err);
+        }
+        this.queue = [];
+    }
+    // ── Internals ──
+    refill() {
+        const now = Date.now();
+        const elapsed = now - this.lastRefill;
+        if (elapsed <= 0)
+            return;
+        this.tokens = Math.min(this.maxTokens, this.tokens + elapsed * this.refillRate);
+        this.lastRefill = now;
+    }
+    scheduleDrain() {
+        if (this.drainTimer)
+            return;
+        // Check every ~1/rps interval (e.g. 40ms for 25 rps)
+        const intervalMs = Math.max(1, Math.ceil(1000 / this.maxTokens));
+        this.drainTimer = setTimeout(() => {
+            this.drainTimer = null;
+            this.drain();
+        }, intervalMs);
+    }
+    drain() {
+        this.refill();
+        while (this.queue.length > 0 && this.tokens >= 1) {
+            this.tokens -= 1;
+            const entry = this.queue.shift();
+            entry.resolve();
+        }
+        // If there are still queued requests, schedule another drain
+        if (this.queue.length > 0) {
+            this.scheduleDrain();
+        }
+    }
+}
+exports.RateLimiter = RateLimiter;
+//# sourceMappingURL=rate-limiter.js.map

package/dist/utils/rate-limiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.js","sourceRoot":"","sources":["../../src/utils/rate-limiter.ts"],"names":[],"mappings":"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"}