ton-provider-system 0.2.1 → 0.2.4

package/dist/index.d.cts

@@ -875,7 +875,10 @@ declare class TokenBucketRateLimiter {
      */
     release(): void;
     /**
-     * Report a successful request (resets backoff)
+     * Report a successful request (gradually reduces backoff)
+     *
+     * Instead of immediately clearing backoff, we gradually reduce it to prevent
+     * immediately hitting the rate limit again after a single success.
      */
     reportSuccess(): void;
     /**
@@ -1004,6 +1007,7 @@ declare class HealthChecker {
      *
      * @param batchSize - Number of providers to test in parallel (default: 2)
      * @param batchDelayMs - Delay between batches in milliseconds (default: 500 to avoid rate limits)
+     *                       If not provided, calculates delay based on lowest RPS in batch
      */
     testProviders(providers: ResolvedProvider[], batchSize?: number, batchDelayMs?: number): Promise<ProviderHealthResult[]>;
     /**
@@ -1084,6 +1088,8 @@ interface SelectionConfig {
     freshnessWeight: number;
     /** Minimum acceptable provider status */
     minStatus: ProviderStatus[];
+    /** Cooldown period (ms) before retrying failed providers (default: 30000) */
+    retryCooldownMs: number;
 }
 /**
  * Provider Selector
@@ -1196,6 +1202,22 @@ declare class ProviderSelector {
      * 2. Health check result browserCompatible flag (if health check was performed)
      */
     private filterBrowserCompatible;
+    /**
+     * Check if an error is retryable (temporary) or permanent
+     *
+     * Permanent errors (never retry):
+     * - 404 (Not Found) - endpoint doesn't exist
+     * - 401 (Unauthorized) - invalid API key
+     * - Invalid API key errors
+     *
+     * Retryable errors (can retry after cooldown):
+     * - 503 (Service Unavailable) - temporary server issue
+     * - 502 (Bad Gateway) - temporary gateway issue
+     * - Timeout errors - network issues
+     * - Network errors - connection issues
+     * - 429 (Rate Limit) - temporary rate limit (handled separately)
+     */
+    private isRetryableError;
 }
 /**
  * Create a provider selector
@@ -1554,18 +1576,26 @@ declare class BrowserAdapter {
     getEndpointWithRateLimit(timeoutMs?: number): Promise<string>;
     /**
      * Make a JSON-RPC call to the TON API
+     *
+     * Note: Uses rate limiting to prevent 429 errors.
      */
     jsonRpc<T = unknown>(method: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<T>;
     /**
      * Get address state
+     *
+     * Note: Uses rate limiting to prevent 429 errors.
      */
     getAddressState(address: string, timeoutMs?: number): Promise<'uninit' | 'active' | 'frozen'>;
     /**
      * Get address balance
+     *
+     * Note: Uses rate limiting to prevent 429 errors.
      */
     getAddressBalance(address: string, timeoutMs?: number): Promise<bigint>;
     /**
      * Get address information
+     *
+     * Note: Uses rate limiting to prevent 429 errors.
      */
     getAddressInfo(address: string, timeoutMs?: number): Promise<{
         state: 'uninit' | 'active' | 'frozen';
@@ -1575,6 +1605,8 @@ declare class BrowserAdapter {
     }>;
     /**
      * Run get method
+     *
+     * Note: Uses rate limiting to prevent 429 errors.
      */
     runGetMethod(address: string, method: string, stack?: unknown[], timeoutMs?: number): Promise<{
         exit_code: number;
@@ -1912,7 +1944,10 @@ declare class TatumProvider extends BaseProvider {
  * Documentation: https://documentation.onfinality.io/support/ton
  *
  * Endpoint format: https://ton-{network}.api.onfinality.io/public or /rpc
- * API key: Optional, in apikey header (preferred) or query params
+ * API key: Required for /rpc endpoint, passed as query parameter ?apikey=YOUR_API_KEY
+ *
+ * IMPORTANT: OnFinality uses query parameters for API key authentication, NOT headers.
+ * The API key must be included in the URL as ?apikey=YOUR_API_KEY
  */
 
 declare class OnFinalityProvider extends BaseProvider {

package/dist/index.d.ts

@@ -875,7 +875,10 @@ declare class TokenBucketRateLimiter {
      */
     release(): void;
     /**
-     * Report a successful request (resets backoff)
+     * Report a successful request (gradually reduces backoff)
+     *
+     * Instead of immediately clearing backoff, we gradually reduce it to prevent
+     * immediately hitting the rate limit again after a single success.
      */
     reportSuccess(): void;
     /**
@@ -1004,6 +1007,7 @@ declare class HealthChecker {
      *
      * @param batchSize - Number of providers to test in parallel (default: 2)
      * @param batchDelayMs - Delay between batches in milliseconds (default: 500 to avoid rate limits)
+     *                       If not provided, calculates delay based on lowest RPS in batch
      */
     testProviders(providers: ResolvedProvider[], batchSize?: number, batchDelayMs?: number): Promise<ProviderHealthResult[]>;
     /**
@@ -1084,6 +1088,8 @@ interface SelectionConfig {
     freshnessWeight: number;
     /** Minimum acceptable provider status */
     minStatus: ProviderStatus[];
+    /** Cooldown period (ms) before retrying failed providers (default: 30000) */
+    retryCooldownMs: number;
 }
 /**
  * Provider Selector
@@ -1196,6 +1202,22 @@ declare class ProviderSelector {
      * 2. Health check result browserCompatible flag (if health check was performed)
      */
     private filterBrowserCompatible;
+    /**
+     * Check if an error is retryable (temporary) or permanent
+     *
+     * Permanent errors (never retry):
+     * - 404 (Not Found) - endpoint doesn't exist
+     * - 401 (Unauthorized) - invalid API key
+     * - Invalid API key errors
+     *
+     * Retryable errors (can retry after cooldown):
+     * - 503 (Service Unavailable) - temporary server issue
+     * - 502 (Bad Gateway) - temporary gateway issue
+     * - Timeout errors - network issues
+     * - Network errors - connection issues
+     * - 429 (Rate Limit) - temporary rate limit (handled separately)
+     */
+    private isRetryableError;
 }
 /**
  * Create a provider selector
@@ -1554,18 +1576,26 @@ declare class BrowserAdapter {
     getEndpointWithRateLimit(timeoutMs?: number): Promise<string>;
     /**
      * Make a JSON-RPC call to the TON API
+     *
+     * Note: Uses rate limiting to prevent 429 errors.
      */
     jsonRpc<T = unknown>(method: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<T>;
     /**
      * Get address state
+     *
+     * Note: Uses rate limiting to prevent 429 errors.
      */
     getAddressState(address: string, timeoutMs?: number): Promise<'uninit' | 'active' | 'frozen'>;
     /**
      * Get address balance
+     *
+     * Note: Uses rate limiting to prevent 429 errors.
      */
     getAddressBalance(address: string, timeoutMs?: number): Promise<bigint>;
     /**
      * Get address information
+     *
+     * Note: Uses rate limiting to prevent 429 errors.
      */
     getAddressInfo(address: string, timeoutMs?: number): Promise<{
         state: 'uninit' | 'active' | 'frozen';
@@ -1575,6 +1605,8 @@ declare class BrowserAdapter {
     }>;
     /**
      * Run get method
+     *
+     * Note: Uses rate limiting to prevent 429 errors.
      */
     runGetMethod(address: string, method: string, stack?: unknown[], timeoutMs?: number): Promise<{
         exit_code: number;
@@ -1912,7 +1944,10 @@ declare class TatumProvider extends BaseProvider {
  * Documentation: https://documentation.onfinality.io/support/ton
  *
  * Endpoint format: https://ton-{network}.api.onfinality.io/public or /rpc
- * API key: Optional, in apikey header (preferred) or query params
+ * API key: Required for /rpc endpoint, passed as query parameter ?apikey=YOUR_API_KEY
+ *
+ * IMPORTANT: OnFinality uses query parameters for API key authentication, NOT headers.
+ * The API key must be included in the URL as ?apikey=YOUR_API_KEY
  */
 
 declare class OnFinalityProvider extends BaseProvider {