ton-provider-system 0.1.0 → 0.1.2

package/dist/index.cjs

@@ -3,6 +3,7 @@
 var zod = require('zod');
 var ton = require('@ton/ton');
 
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 // src/types.ts
 var TimeoutError = class extends Error {
   constructor(operation, timeoutMs, message) {
@@ -199,7 +200,10 @@ function resolveProvider(id, config) {
     console.warn(`[ConfigParser] Provider ${id} has no valid endpoints after resolution`);
     return null;
   }
-  const apiKey = config.apiKeyEnvVar ? getEnvVar(config.apiKeyEnvVar) : void 0;
+  let apiKey = config.apiKeyEnvVar ? getEnvVar(config.apiKeyEnvVar) : void 0;
+  if (!apiKey && config.keyEnvVar && config.type === "onfinality") {
+    apiKey = getEnvVar(config.keyEnvVar);
+  }
   return {
     id,
     name: config.name,
@@ -250,13 +254,24 @@ function getDefaultProvidersForNetwork(config, network) {
 async function loadBuiltinConfig() {
   const fs = await import('fs').then((m) => m.promises);
   const path = await import('path');
+  const { fileURLToPath } = await import('url');
+  const getDirname = () => {
+    try {
+      if ((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href))) {
+        return path.dirname(fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href))));
+      }
+    } catch {
+    }
+    return process.cwd();
+  };
+  const dirname = getDirname();
   const possiblePaths = [
     // When running from project root (e.g., ts-node scripts/...)
     path.resolve(process.cwd(), "provider_system", RPC_CONFIG_FILENAME),
     // When running from provider_system folder
     path.resolve(process.cwd(), RPC_CONFIG_FILENAME),
-    // Relative to this file (CommonJS style)
-    path.resolve(__dirname, "..", RPC_CONFIG_FILENAME)
+    // Relative to this file (ESM style)
+    path.resolve(dirname, "..", RPC_CONFIG_FILENAME)
   ];
   for (const configPath of possiblePaths) {
     try {
@@ -549,12 +564,63 @@ function normalizeV2Endpoint(endpoint) {
   if (normalized.toLowerCase().endsWith("/jsonrpc")) {
     return normalized;
   }
+  if (normalized.includes("gateway.tatum.io")) {
+    try {
+      const url = new URL(normalized);
+      if (!url.pathname || url.pathname === "/") {
+        return normalized + "/jsonRPC";
+      }
+      if (!url.pathname.toLowerCase().endsWith("/jsonrpc")) {
+        return normalized + "/jsonRPC";
+      }
+    } catch {
+      return normalized + "/jsonRPC";
+    }
+  }
+  if (normalized.includes("onfinality.io")) {
+    try {
+      const url = new URL(normalized);
+      const baseUrl = normalized.split("?")[0];
+      if (!url.pathname || url.pathname === "/") {
+        const apikey = url.searchParams.get("apikey");
+        if (apikey && apikey !== "{key}" && apikey.length > 0) {
+          return baseUrl.replace(/\/?$/, "/rpc");
+        }
+        return baseUrl.replace(/\/?$/, "/public");
+      }
+      if (url.pathname === "/rpc" || url.pathname === "/public") {
+        return baseUrl;
+      }
+      return baseUrl;
+    } catch {
+      if (normalized.includes("{key}")) {
+        return normalized.split("?")[0].replace(/\/?$/, "/public");
+      }
+      if (!normalized.includes("/rpc") && !normalized.includes("/public")) {
+        return normalized.split("?")[0] + "/public";
+      }
+      return normalized.split("?")[0];
+    }
+  }
   if (normalized.endsWith("/api/v2")) {
     return normalized + "/jsonRPC";
   }
   if (normalized.endsWith("/api/v3")) {
     return normalized.replace("/api/v3", "/api/v2/jsonRPC");
   }
+  if (normalized.includes("quiknode.pro") || normalized.includes("getblock.io")) {
+    try {
+      const url = new URL(normalized);
+      if (!url.pathname || url.pathname === "/") {
+        return normalized + "/jsonRPC";
+      }
+      if (!url.pathname.toLowerCase().endsWith("/jsonrpc")) {
+        return normalized + "/jsonRPC";
+      }
+    } catch {
+      return normalized + "/jsonRPC";
+    }
+  }
   try {
     const url = new URL(normalized);
     if (!url.pathname || url.pathname === "/") {
@@ -582,7 +648,7 @@ function toV2Base(endpoint) {
   return normalized;
 }
 function toV3Base(endpoint) {
-  let normalized = toV2Base(endpoint);
+  const normalized = toV2Base(endpoint);
   return normalized.replace("/api/v2", "/api/v3");
 }
 function getBaseUrl(endpoint) {
@@ -682,11 +748,19 @@ var DEFAULT_CONFIG = {
   degradedLatencyMs: 3e3
 };
 var HealthChecker = class {
-  constructor(config, logger) {
+  constructor(config, logger, rateLimiter) {
     this.results = /* @__PURE__ */ new Map();
     this.highestSeqno = /* @__PURE__ */ new Map();
+    this.rateLimiter = null;
     this.config = { ...DEFAULT_CONFIG, ...config };
     this.logger = logger || consoleLogger2;
+    this.rateLimiter = rateLimiter || null;
+  }
+  /**
+   * Set rate limiter (can be set after construction)
+   */
+  setRateLimiter(rateLimiter) {
+    this.rateLimiter = rateLimiter;
   }
   /**
    * Test a single provider's health
@@ -706,15 +780,42 @@ var HealthChecker = class {
     };
     this.results.set(key, testingResult);
     try {
+      if (this.rateLimiter) {
+        const acquired = await this.rateLimiter.acquire(provider.id, this.config.timeoutMs);
+        if (!acquired) {
+          throw new Error("Rate limit timeout - unable to acquire token for health check");
+        }
+      }
       const endpoint = await this.getEndpoint(provider);
       if (!endpoint) {
         throw new Error("No valid endpoint available");
       }
-      const normalizedEndpoint = normalizeV2Endpoint(endpoint);
-      const info = await this.callGetMasterchainInfo(normalizedEndpoint);
+      if (provider.type === "tatum" && !provider.apiKey) {
+        throw new Error("Tatum provider requires API key (set TATUM_API_KEY_TESTNET or TATUM_API_KEY_MAINNET)");
+      }
+      let normalizedEndpoint = this.normalizeEndpointForProvider(provider, endpoint);
+      if (provider.type === "onfinality") {
+        this.logger.debug(`OnFinality endpoint: ${endpoint} -> ${normalizedEndpoint}, API key: ${provider.apiKey ? "set" : "not set"}`);
+      }
+      let info;
+      try {
+        info = await this.callGetMasterchainInfo(normalizedEndpoint, provider);
+      } catch (error) {
+        if (provider.type === "onfinality" && normalizedEndpoint.includes("/rpc") && provider.apiKey && error.message?.includes("backend error")) {
+          this.logger.debug(`OnFinality /rpc failed, retrying with /public endpoint`);
+          const publicEndpoint = normalizedEndpoint.replace("/rpc", "/public");
+          info = await this.callGetMasterchainInfo(publicEndpoint, { ...provider, apiKey: void 0 });
+        } else {
+          throw error;
+        }
+      }
       const endTime = performance.now();
       const latencyMs = Math.round(endTime - startTime);
-      const seqno = info.last?.seqno || 0;
+      const infoWithLast = info;
+      const seqno = infoWithLast.last?.seqno;
+      if (!seqno || seqno <= 0 || !Number.isInteger(seqno)) {
+        throw new Error("Invalid seqno in response (must be positive integer)");
+      }
       const currentHighest = this.highestSeqno.get(provider.network) || 0;
       if (seqno > currentHighest) {
         this.highestSeqno.set(provider.network, seqno);
@@ -748,11 +849,14 @@ var HealthChecker = class {
       const errorMsg = error.message || String(error) || "Unknown error";
       const is429 = errorMsg.includes("429") || errorMsg.toLowerCase().includes("rate limit");
       const is404 = errorMsg.includes("404") || errorMsg.toLowerCase().includes("not found");
+      const is503 = errorMsg.includes("503") || errorMsg.toLowerCase().includes("service unavailable");
+      const is502 = errorMsg.includes("502") || errorMsg.toLowerCase().includes("bad gateway");
       const isTimeout = error.name === "AbortError" || errorMsg.includes("timeout");
+      const isOnFinalityBackendError = provider.type === "onfinality" && (errorMsg.includes("Backend error") || errorMsg.includes("backend error"));
       let status = "offline";
       if (is429) {
         status = "degraded";
-      } else if (is404) {
+      } else if (is404 || is503 || is502 || isOnFinalityBackendError) {
         status = "offline";
       } else if (isTimeout) {
         status = "offline";
@@ -775,8 +879,11 @@ var HealthChecker = class {
   }
   /**
    * Test multiple providers in parallel with staggered batches
+   * 
+   * @param batchSize - Number of providers to test in parallel (default: 2)
+   * @param batchDelayMs - Delay between batches in milliseconds (default: 500 to avoid rate limits)
    */
-  async testProviders(providers, batchSize = 2, batchDelayMs = 300) {
+  async testProviders(providers, batchSize = 2, batchDelayMs = 500) {
     const results = [];
     for (let i = 0; i < providers.length; i += batchSize) {
       const batch = providers.slice(i, i + batchSize);
@@ -890,15 +997,37 @@ var HealthChecker = class {
     return provider.endpointV2 || provider.endpointV3 || null;
   }
   /**
-   * Call getMasterchainInfo API
+   * Normalize endpoint for provider-specific requirements
+   * 
+   * Note: normalizeV2Endpoint now handles all provider-specific cases correctly,
+   * including Tatum (/jsonRPC), OnFinality (/public or /rpc), QuickNode, and GetBlock.
+   */
+  normalizeEndpointForProvider(provider, endpoint) {
+    if (provider.type === "tatum" && endpoint.includes("api.tatum.io/v3/blockchain/node")) {
+      const network = provider.network === "testnet" ? "testnet" : "mainnet";
+      endpoint = `https://ton-${network}.gateway.tatum.io`;
+    }
+    return normalizeV2Endpoint(endpoint);
+  }
+  /**
+   * Call getMasterchainInfo API with provider-specific handling
    */
-  async callGetMasterchainInfo(endpoint) {
+  async callGetMasterchainInfo(endpoint, provider) {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.config.timeoutMs);
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (provider.type === "tatum" && provider.apiKey) {
+      headers["x-api-key"] = provider.apiKey;
+    }
+    if (provider.type === "onfinality" && provider.apiKey) {
+      headers["apikey"] = provider.apiKey;
+    }
     try {
       const response = await fetch(endpoint, {
         method: "POST",
-        headers: { "Content-Type": "application/json" },
+        headers,
         body: JSON.stringify({
           id: "1",
           jsonrpc: "2.0",
@@ -908,20 +1037,63 @@ var HealthChecker = class {
         signal: controller.signal
       });
       clearTimeout(timeoutId);
+      const contentType = response.headers.get("content-type") || "";
+      let text = null;
+      let data;
+      if (!contentType.includes("application/json")) {
+        text = await response.text();
+        this.logger.debug(`${provider.type} non-JSON response (${contentType}): ${text.substring(0, 200)}`);
+        if (provider.type === "onfinality" && text.includes("Backend error")) {
+          throw new Error(`OnFinality backend error: ${text}`);
+        }
+        throw new Error(`Invalid response type: expected JSON, got ${contentType}. Response: ${text.substring(0, 100)}`);
+      }
       if (!response.ok) {
-        throw new Error(`HTTP ${response.status}`);
+        try {
+          data = await response.json();
+          const errorObj = data;
+          const errorMsg = typeof errorObj.error === "string" ? errorObj.error : errorObj.error?.message || `HTTP ${response.status}`;
+          throw new Error(errorMsg);
+        } catch {
+          throw new Error(`HTTP ${response.status}`);
+        }
       }
-      const data = await response.json();
-      if (data && typeof data === "object" && "ok" in data) {
-        if (!data.ok) {
-          throw new Error(data.error || "API returned ok=false");
+      data = await response.json();
+      let info;
+      if (data && typeof data === "object") {
+        const dataObj = data;
+        if ("ok" in dataObj) {
+          if (!dataObj.ok) {
+            const error = dataObj.error;
+            throw new Error(error || "API returned ok=false");
+          }
+          const result = dataObj.result;
+          info = result || dataObj;
+        } else if ("result" in dataObj) {
+          info = dataObj.result;
+        } else if ("last" in dataObj || "@type" in dataObj) {
+          info = dataObj;
+        } else if ("error" in dataObj) {
+          const errorObj = dataObj.error;
+          const errorMsg = typeof errorObj === "string" ? errorObj : errorObj?.message || errorObj?.code || String(errorObj);
+          throw new Error(`API error: ${errorMsg}`);
+        } else {
+          throw new Error(`Unknown response format from ${provider.type}`);
         }
-        return data.result || data;
+      } else {
+        throw new Error(`Invalid response type: ${typeof data}`);
       }
-      if (data.result) {
-        return data.result;
+      if (!info || typeof info !== "object") {
+        this.logger.debug(`Invalid response structure from ${provider.type}: ${JSON.stringify(data)}`);
+        throw new Error("Invalid response structure");
       }
-      return data;
+      const infoObj = info;
+      const seqno = infoObj.last?.seqno;
+      if (seqno === void 0 || seqno === null || seqno <= 0 || !Number.isInteger(seqno)) {
+        this.logger.debug(`Invalid seqno from ${provider.type}:`, { seqno, info });
+        throw new Error(`Invalid seqno: ${seqno} (must be positive integer)`);
+      }
+      return info;
     } catch (error) {
       clearTimeout(timeoutId);
       throw error;
@@ -931,8 +1103,8 @@ var HealthChecker = class {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }
 };
-function createHealthChecker(config, logger) {
-  return new HealthChecker(config, logger);
+function createHealthChecker(config, logger, rateLimiter) {
+  return new HealthChecker(config, logger, rateLimiter);
 }
 
 // src/utils/timeout.ts
@@ -1404,7 +1576,7 @@ var ProviderSelector = class {
     if (cachedBestId) {
       const cached = this.registry.getProvider(cachedBestId);
       const health = this.healthChecker.getResult(cachedBestId, network);
-      if (cached && health && this.config.minStatus.includes(health.status)) {
+      if (cached && health && health.success !== false && this.config.minStatus.includes(health.status)) {
         return cached;
       }
     }
@@ -1425,17 +1597,39 @@ var ProviderSelector = class {
     })).filter((item) => item.score > 0).sort((a, b) => b.score - a.score);
     if (scored.length === 0) {
       const defaults = this.registry.getDefaultOrderForNetwork(network);
-      if (defaults.length > 0) {
-        this.logger.warn(`No healthy providers for ${network}, using first default`);
-        return defaults[0];
+      for (const defaultProvider of defaults) {
+        const health = this.healthChecker.getResult(defaultProvider.id, network);
+        if (!health || health.status === "untested" || health.success === true) {
+          this.logger.warn(
+            `No healthy providers for ${network}, using default: ${defaultProvider.id}`
+          );
+          return defaultProvider;
+        }
+      }
+      for (const provider of providers) {
+        const health = this.healthChecker.getResult(provider.id, network);
+        if (!health || health.status === "untested") {
+          this.logger.warn(
+            `No tested healthy providers for ${network}, using untested: ${provider.id}`
+          );
+          return provider;
+        }
       }
-      return providers[0];
+      this.logger.error(`No available providers for ${network} (all tested and failed)`);
+      return null;
     }
     const best = scored[0].provider;
-    this.bestProviderByNetwork.set(network, best.id);
-    this.logger.debug(
-      `Best provider for ${network}: ${best.id} (score: ${scored[0].score.toFixed(2)})`
-    );
+    const bestHealth = this.healthChecker.getResult(best.id, network);
+    if (bestHealth && bestHealth.success === true) {
+      this.bestProviderByNetwork.set(network, best.id);
+      this.logger.debug(
+        `Best provider for ${network}: ${best.id} (score: ${scored[0].score.toFixed(2)})`
+      );
+    } else {
+      this.logger.debug(
+        `Best provider for ${network}: ${best.id} (score: ${scored[0].score.toFixed(2)}, untested)`
+      );
+    }
     return best;
   }
   /**
@@ -1471,7 +1665,7 @@ var ProviderSelector = class {
   scoreProvider(provider, network) {
     const health = this.healthChecker.getResult(provider.id, network);
     if (!health || health.status === "untested") {
-      return 0.1 * (1 / (provider.priority + 1));
+      return 0.01 * (1 / (provider.priority + 1));
     }
     if (health.success === false) {
       return 0;
@@ -1701,28 +1895,29 @@ var _ProviderManager = class _ProviderManager {
     const config = await loadConfig();
     const mergedConfig = mergeWithDefaults(config);
     this.registry = new ProviderRegistry(mergedConfig, this.options.logger);
+    this.rateLimiter = createRateLimiterManager(this.options.logger);
+    for (const provider of this.registry.getAllProviders()) {
+      const config2 = getRateLimitForType(provider.type);
+      this.rateLimiter.setConfig(provider.id, {
+        ...config2,
+        rps: provider.rps,
+        minDelayMs: Math.ceil(1e3 / provider.rps)
+      });
+    }
     this.healthChecker = createHealthChecker(
       {
         timeoutMs: this.options.requestTimeoutMs,
         maxBlocksBehind: this.options.maxBlocksBehind
       },
-      this.options.logger
+      this.options.logger,
+      this.rateLimiter
     );
-    this.rateLimiter = createRateLimiterManager(this.options.logger);
     this.selector = createSelector(
       this.registry,
       this.healthChecker,
       void 0,
       this.options.logger
     );
-    for (const provider of this.registry.getAllProviders()) {
-      const config2 = getRateLimitForType(provider.type);
-      this.rateLimiter.setConfig(provider.id, {
-        ...config2,
-        rps: provider.rps,
-        minDelayMs: Math.ceil(1e3 / provider.rps)
-      });
-    }
     this.initialized = true;
     this.notifyListeners();
     if (testProviders) {
@@ -2112,6 +2307,17 @@ var NodeAdapter = class {
    * Get TonClient instance
    *
    * Creates a new client if endpoint changed, otherwise returns cached.
+   * 
+   * NOTE: Direct TonClient calls bypass rate limiting. For rate-limited operations,
+   * use adapter methods (getAddressState, runGetMethod, etc.) or wrap your calls
+   * with rate limit token acquisition.
+   * 
+   * Example with rate limiting:
+   * ```typescript
+   * const endpoint = await adapter.manager.getEndpointWithRateLimit();
+   * // Make your TonClient call
+   * adapter.manager.reportSuccess(); // or reportError() on failure
+   * ```
    */
   async getClient() {
     const endpoint = await this.manager.getEndpoint();
@@ -2137,6 +2343,19 @@ var NodeAdapter = class {
     this.logger.debug(`Created TonClient for ${network}`, { endpoint });
     return client;
   }
+  /**
+   * Get TonClient with rate limiting applied
+   * 
+   * Acquires a rate limit token before returning the client.
+   * Use this when you need to ensure rate limiting is respected.
+   * 
+   * Note: This only acquires ONE token. For multiple operations,
+   * you should acquire tokens before each operation or use adapter methods.
+   */
+  async getClientWithRateLimit(timeoutMs) {
+    await this.manager.getEndpointWithRateLimit(timeoutMs);
+    return this.getClient();
+  }
   /**
    * Reset client cache (forces new client creation)
    */
@@ -2322,6 +2541,22 @@ async function getTonClient(manager) {
   const adapter = new NodeAdapter(manager);
   return adapter.getClient();
 }
+async function getTonClientWithRateLimit(manager) {
+  const adapter = new NodeAdapter(manager);
+  const client = await adapter.getClient();
+  const withRateLimit = async (fn) => {
+    await manager.getEndpointWithRateLimit();
+    try {
+      const result = await fn();
+      manager.reportSuccess();
+      return result;
+    } catch (error) {
+      manager.reportError(error);
+      throw error;
+    }
+  };
+  return { client, withRateLimit };
+}
 async function getTonClientForNetwork(network, configPath) {
   const manager = ProviderManager.getInstance({ configPath });
   if (!manager.isInitialized() || manager.getNetwork() !== network) {
@@ -2660,6 +2895,7 @@ exports.getProvidersForNetwork = getProvidersForNetwork;
 exports.getRateLimitForType = getRateLimitForType;
 exports.getTonClient = getTonClient;
 exports.getTonClientForNetwork = getTonClientForNetwork;
+exports.getTonClientWithRateLimit = getTonClientWithRateLimit;
 exports.isApiVersion = isApiVersion;
 exports.isChainstackUrl = isChainstackUrl;
 exports.isNetwork = isNetwork;