ton-provider-system 0.3.1 → 0.5.0

package/dist/index.cjs

@@ -2,6 +2,7 @@
 
 var zod = require('zod');
 var ton = require('@ton/ton');
+var core = require('@ton/core');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 // src/types.ts
@@ -71,6 +72,7 @@ var ProviderConfigSchema = zod.z.object({
   enabled: zod.z.boolean().default(true),
   isDynamic: zod.z.boolean().optional().default(false),
   browserCompatible: zod.z.boolean().optional(),
+  servesGetTransactions: zod.z.boolean().optional(),
   description: zod.z.string().optional()
 });
 var NetworkDefaultsSchema = zod.z.object({
@@ -219,7 +221,10 @@ function resolveProvider(id, config) {
     rps: config.rps,
     priority: config.priority,
     isDynamic: config.isDynamic || false,
-    browserCompatible: config.browserCompatible !== void 0 ? config.browserCompatible : true
+    browserCompatible: config.browserCompatible !== void 0 ? config.browserCompatible : true,
+    // Default true: a provider is assumed to serve getTransactions unless the
+    // config explicitly opts out (e.g. Chainstack/Orbs testnet liteserver proxies).
+    servesGetTransactions: config.servesGetTransactions !== false
   };
 }
 function resolveAllProviders(config) {
@@ -2553,8 +2558,10 @@ var ProviderSelector = class {
       rps: 10,
       priority: 0,
       isDynamic: false,
-      browserCompatible: true
+      browserCompatible: true,
       // Custom endpoints are assumed compatible
+      servesGetTransactions: true
+      // Custom endpoints are assumed fully capable
     };
   }
   /**
@@ -2885,26 +2892,39 @@ var _ProviderManager = class _ProviderManager {
   // ========================================================================
   /**
    * Report a successful request
+   *
+   * @param providerId - Optionally attribute the success to a SPECIFIC provider
+   *   (used by callers that drive their own candidate list, e.g.
+   *   NodeAdapter.getTransactions, where the provider used is not necessarily the
+   *   selector's current best). Defaults to the current best provider.
    */
-  reportSuccess() {
+  reportSuccess(providerId) {
     if (!this.initialized || !this.network) return;
-    const provider = this.selector.getBestProvider(this.network);
-    if (provider) {
-      this.rateLimiter.reportSuccess(provider.id);
+    const id = providerId ?? this.selector.getBestProvider(this.network)?.id;
+    if (id) {
+      this.rateLimiter.reportSuccess(id);
     }
   }
   /**
    * Report an error (triggers provider switch if needed)
+   *
+   * @param providerId - Optionally attribute the error to a SPECIFIC provider
+   *   (used by callers that drive their own candidate list, e.g.
+   *   NodeAdapter.getTransactions). Defaults to the current active/best provider.
    */
-  reportError(error) {
+  reportError(error, providerId) {
     if (!this.initialized || !this.network) return;
-    const activeProviderId = this.selector.getActiveProviderId(this.network);
     let provider = null;
-    if (activeProviderId) {
-      provider = this.registry.getProvider(activeProviderId) || null;
-    }
-    if (!provider) {
-      provider = this.selector.getBestProvider(this.network);
+    if (providerId) {
+      provider = this.registry.getProvider(providerId) || null;
+    } else {
+      const activeProviderId = this.selector.getActiveProviderId(this.network);
+      if (activeProviderId) {
+        provider = this.registry.getProvider(activeProviderId) || null;
+      }
+      if (!provider) {
+        provider = this.selector.getBestProvider(this.network);
+      }
     }
     if (!provider) {
       this.options.logger.warn(`Cannot report error: no provider available for ${this.network}`);
@@ -3034,6 +3054,21 @@ var _ProviderManager = class _ProviderManager {
     }
     return providers;
   }
+  /**
+   * Get transaction-capable providers for the current network, in selector
+   * score order (best first).
+   *
+   * Read-only: enumerates the score-ordered available providers and excludes any
+   * flagged `servesGetTransactions: false` (Chainstack/Orbs testnet liteserver
+   * proxies, which 403 on v2 getTransactions). Used by
+   * NodeAdapter.getTransactions to build its candidate set WITHOUT poisoning the
+   * incapable providers' global health — so the get-method path keeps using them.
+   * Returns [] when no capable provider is currently selectable.
+   */
+  getTransactionCapableProviders() {
+    if (!this.initialized || !this.network) return [];
+    return this.selector.getAvailableProviders(this.network).filter((p) => p.servesGetTransactions !== false);
+  }
   /**
    * Get provider health results for current network
    */
@@ -3249,6 +3284,76 @@ var NodeAdapter = class {
     };
   }
   // ========================================================================
+  // Failover-aware high-level reads
+  // ========================================================================
+  /**
+   * Get account transactions with capability-aware provider failover.
+   *
+   * Unlike `getClient().getTransactions(...)`, this builds a candidate set of the
+   * network's *transaction-capable* providers (score-ordered, best first) and
+   * loops over THAT set. Providers known not to serve the v2 `getTransactions`
+   * shape — flagged `servesGetTransactions: false` in config (Chainstack/Orbs
+   * testnet, which pass the `getMasterchainInfo` health probe but 403 on
+   * transaction reads) — are excluded UP FRONT. They are never called and never
+   * `reportError`-ed here, so their global health stays intact and the fast
+   * get-method path keeps using them (a wasted 403 would otherwise evict them).
+   *
+   * Semantics (per capable candidate, in score order):
+   *  1. Acquire a rate-limit token for THAT provider, bind a short-lived
+   *     `TonClient` to its endpoint, and call `getTransactions`.
+   *  2. On success → `reportSuccess(provider.id)` and return.
+   *  3. On a GENUINE error → `reportError(error, provider.id)` (marks THAT
+   *     provider success:false + clears the selection cache) and try the next
+   *     capable candidate.
+   *  4. When every capable candidate has been tried, re-throw the last error so
+   *     the caller's retry/dead-letter logic still triggers.
+   *  5. If there is NO capable provider at all, throw a clear error.
+   *
+   * Returns the same `Transaction[]` `TonClient.getTransactions` returns, so a
+   * consumer can swap `client.getTransactions(addr, opts)` for
+   * `adapter.getTransactions(addr, opts)` with no shape change.
+   */
+  async getTransactions(address, opts = {}, timeoutMs = 15e3) {
+    const network = this.manager.getNetwork();
+    if (!network) {
+      throw new Error("ProviderManager not initialized");
+    }
+    const addr = typeof address === "string" ? core.Address.parse(address) : address;
+    const reqOpts = { limit: opts.limit ?? 20, ...opts };
+    const candidates = this.manager.getTransactionCapableProviders();
+    if (candidates.length === 0) {
+      throw new Error(
+        `getTransactions: no transaction-capable provider for ${network}`
+      );
+    }
+    const rateLimiter = this.manager.getRateLimiter();
+    let lastError;
+    for (const provider of candidates) {
+      if (rateLimiter) {
+        await rateLimiter.acquire(provider.id, timeoutMs);
+      }
+      const endpoint = normalizeV2Endpoint(provider.endpointV2, provider);
+      const client = new ton.TonClient({ endpoint, apiKey: provider.apiKey });
+      try {
+        const result = await withTimeout(
+          client.getTransactions(addr, reqOpts),
+          timeoutMs,
+          `getTransactions(${provider.id})`
+        );
+        this.manager.reportSuccess(provider.id);
+        return result;
+      } catch (error) {
+        lastError = error;
+        this.logger.warn(
+          `getTransactions failed on ${provider.id}, failing over`,
+          { error: error?.message || String(error) }
+        );
+        this.manager.reportError(error, provider.id);
+      }
+    }
+    throw lastError || new Error(`getTransactions: all transaction-capable providers failed for ${network}`);
+  }
+  // ========================================================================
   // Direct REST API Methods
   // ========================================================================
   /**