@debros/network-ts-sdk 0.4.2 → 0.6.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) [year] [fullname]
+Copyright (c) 2026 DeBrosOfficial
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -367,6 +367,7 @@ interface ClientConfig {
   timeout?: number; // Request timeout in ms (default: 30000)
   maxRetries?: number; // Max retry attempts (default: 3)
   retryDelayMs?: number; // Delay between retries (default: 1000)
+  debug?: boolean; // Enable debug logging with full SQL queries (default: false)
   storage?: StorageAdapter; // For persisting JWT/API key (default: MemoryStorage)
   wsConfig?: Partial<WSClientConfig>; // WebSocket configuration
   fetch?: typeof fetch; // Custom fetch implementation

package/dist/index.d.ts

@@ -1,11 +1,49 @@
 import WebSocket from 'isomorphic-ws';
 
+declare class SDKError extends Error {
+    readonly httpStatus: number;
+    readonly code: string;
+    readonly details: Record<string, any>;
+    constructor(message: string, httpStatus?: number, code?: string, details?: Record<string, any>);
+    static fromResponse(status: number, body: any, message?: string): SDKError;
+    toJSON(): {
+        name: string;
+        message: string;
+        httpStatus: number;
+        code: string;
+        details: Record<string, any>;
+    };
+}
+
+/**
+ * Context provided to the onNetworkError callback
+ */
+interface NetworkErrorContext {
+    method: "GET" | "POST" | "PUT" | "DELETE" | "WS";
+    path: string;
+    isRetry: boolean;
+    attempt: number;
+}
+/**
+ * Callback invoked when a network error occurs.
+ * Use this to trigger gateway failover or other error handling.
+ */
+type NetworkErrorCallback = (error: SDKError, context: NetworkErrorContext) => void;
 interface HttpClientConfig {
     baseURL: string;
     timeout?: number;
     maxRetries?: number;
     retryDelayMs?: number;
     fetch?: typeof fetch;
+    /**
+     * Enable debug logging (includes full SQL queries and args). Default: false
+     */
+    debug?: boolean;
+    /**
+     * Callback invoked on network errors (after all retries exhausted).
+     * Use this to trigger gateway failover at the application layer.
+     */
+    onNetworkError?: NetworkErrorCallback;
 }
 declare class HttpClient {
     private baseURL;
@@ -15,7 +53,13 @@ declare class HttpClient {
     private fetch;
     private apiKey?;
     private jwt?;
+    private debug;
+    private onNetworkError?;
     constructor(config: HttpClientConfig);
+    /**
+     * Set the network error callback
+     */
+    setOnNetworkError(callback: NetworkErrorCallback | undefined): void;
     setApiKey(apiKey?: string): void;
     setJwt(jwt?: string): void;
     private getAuthHeaders;
@@ -287,6 +331,11 @@ interface WSClientConfig {
     timeout?: number;
     authToken?: string;
     WebSocket?: typeof WebSocket;
+    /**
+     * Callback invoked on WebSocket errors.
+     * Use this to trigger gateway failover at the application layer.
+     */
+    onNetworkError?: NetworkErrorCallback;
 }
 type WSMessageHandler = (data: string) => void;
 type WSErrorHandler = (error: Error) => void;
@@ -302,6 +351,7 @@ declare class WSClient {
     private timeout;
     private authToken?;
     private WebSocketClass;
+    private onNetworkError?;
     private ws?;
     private messageHandlers;
     private errorHandlers;
@@ -309,6 +359,10 @@ declare class WSClient {
     private openHandlers;
     private isClosed;
     constructor(config: WSClientConfig);
+    /**
+     * Set the network error callback
+     */
+    setOnNetworkError(callback: NetworkErrorCallback | undefined): void;
     /**
      * Get the current WebSocket URL
      */
@@ -769,21 +823,6 @@ declare class FunctionsClient {
     invoke<TInput = any, TOutput = any>(functionName: string, input: TInput): Promise<TOutput>;
 }
 
-declare class SDKError extends Error {
-    readonly httpStatus: number;
-    readonly code: string;
-    readonly details: Record<string, any>;
-    constructor(message: string, httpStatus?: number, code?: string, details?: Record<string, any>);
-    static fromResponse(status: number, body: any, message?: string): SDKError;
-    toJSON(): {
-        name: string;
-        message: string;
-        httpStatus: number;
-        code: string;
-        details: Record<string, any>;
-    };
-}
-
 /**
  * Serverless Functions Types
  * Type definitions for calling serverless functions on the Orama Network
@@ -811,6 +850,11 @@ interface ClientConfig extends Omit<HttpClientConfig, "fetch"> {
     wsConfig?: Partial<Omit<WSClientConfig, "wsURL">>;
     functionsConfig?: FunctionsClientConfig;
     fetch?: typeof fetch;
+    /**
+     * Callback invoked on network errors (HTTP and WebSocket).
+     * Use this to trigger gateway failover at the application layer.
+     */
+    onNetworkError?: NetworkErrorCallback;
 }
 interface Client {
     auth: AuthClient;
@@ -823,4 +867,4 @@ interface Client {
 }
 declare function createClient(config: ClientConfig): Client;
 
-export { AuthClient, type AuthConfig, CacheClient, type CacheDeleteRequest, type CacheDeleteResponse, type CacheGetRequest, type CacheGetResponse, type CacheHealthResponse, type CacheMultiGetRequest, type CacheMultiGetResponse, type CachePutRequest, type CachePutResponse, type CacheScanRequest, type CacheScanResponse, type Client, type ClientConfig, type CloseHandler, type ColumnDefinition, DBClient, type Entity, type ErrorHandler, type FindOptions, type FunctionResponse, FunctionsClient, type FunctionsClientConfig, HttpClient, LocalStorageAdapter, MemoryStorage, type MessageHandler, NetworkClient, type NetworkStatus, type PeerInfo, type PresenceMember, type PresenceOptions, type PresenceResponse, type ProxyRequest, type ProxyResponse, PubSubClient, type PubSubMessage, QueryBuilder, type QueryResponse, Repository, SDKError, type SelectOptions, type StorageAdapter, StorageClient, type StoragePinRequest, type StoragePinResponse, type StorageStatus, type StorageUploadResponse, type SubscribeOptions, Subscription, type SuccessResponse, type TransactionOp, type TransactionRequest, WSClient, type WhoAmI, createClient, extractPrimaryKey, extractTableName };
+export { AuthClient, type AuthConfig, CacheClient, type CacheDeleteRequest, type CacheDeleteResponse, type CacheGetRequest, type CacheGetResponse, type CacheHealthResponse, type CacheMultiGetRequest, type CacheMultiGetResponse, type CachePutRequest, type CachePutResponse, type CacheScanRequest, type CacheScanResponse, type Client, type ClientConfig, type CloseHandler, type ColumnDefinition, DBClient, type Entity, type ErrorHandler, type FindOptions, type FunctionResponse, FunctionsClient, type FunctionsClientConfig, HttpClient, LocalStorageAdapter, MemoryStorage, type MessageHandler, NetworkClient, type NetworkErrorCallback, type NetworkErrorContext, type NetworkStatus, type PeerInfo, type PresenceMember, type PresenceOptions, type PresenceResponse, type ProxyRequest, type ProxyResponse, PubSubClient, type PubSubMessage, QueryBuilder, type QueryResponse, Repository, SDKError, type SelectOptions, type StorageAdapter, StorageClient, type StoragePinRequest, type StoragePinResponse, type StorageStatus, type StorageUploadResponse, type SubscribeOptions, Subscription, type SuccessResponse, type TransactionOp, type TransactionRequest, WSClient, type WhoAmI, createClient, extractPrimaryKey, extractTableName };

package/dist/index.js

@@ -40,6 +40,14 @@ var HttpClient = class {
     this.maxRetries = config.maxRetries ?? 3;
     this.retryDelayMs = config.retryDelayMs ?? 1e3;
     this.fetch = config.fetch ?? createFetchWithTLSConfig();
+    this.debug = config.debug ?? false;
+    this.onNetworkError = config.onNetworkError;
+  }
+  /**
+   * Set the network error callback
+   */
+  setOnNetworkError(callback) {
+    this.onNetworkError = callback;
   }
   setApiKey(apiKey) {
     this.apiKey = apiKey;
@@ -167,7 +175,7 @@ var HttpClient = class {
         const logMessage = `[HttpClient] ${method} ${path} completed in ${duration.toFixed(
           2
         )}ms`;
-        if (queryDetails) {
+        if (queryDetails && this.debug) {
           console.log(logMessage);
           console.log(`[HttpClient]   ${queryDetails}`);
         } else {
@@ -190,11 +198,26 @@ var HttpClient = class {
             2
           )}ms:`;
           console.error(errorMessage, error);
-          if (queryDetails) {
+          if (queryDetails && this.debug) {
             console.error(`[HttpClient]   ${queryDetails}`);
           }
         }
       }
+      if (this.onNetworkError) {
+        const sdkError = error instanceof SDKError ? error : new SDKError(
+          error instanceof Error ? error.message : String(error),
+          0,
+          // httpStatus 0 indicates network-level failure
+          "NETWORK_ERROR"
+        );
+        this.onNetworkError(sdkError, {
+          method,
+          path,
+          isRetry: false,
+          attempt: this.maxRetries
+          // All retries exhausted
+        });
+      }
       throw error;
     } finally {
       clearTimeout(timeoutId);
@@ -291,6 +314,19 @@ var HttpClient = class {
           error
         );
       }
+      if (this.onNetworkError) {
+        const sdkError = error instanceof SDKError ? error : new SDKError(
+          error instanceof Error ? error.message : String(error),
+          0,
+          "NETWORK_ERROR"
+        );
+        this.onNetworkError(sdkError, {
+          method: "POST",
+          path,
+          isRetry: false,
+          attempt: this.maxRetries
+        });
+      }
       throw error;
     } finally {
       clearTimeout(timeoutId);
@@ -315,16 +351,26 @@ var HttpClient = class {
       const response = await this.fetch(url.toString(), fetchOptions);
       if (!response.ok) {
         clearTimeout(timeoutId);
-        const error = await response.json().catch(() => ({
+        const errorBody = await response.json().catch(() => ({
           error: response.statusText
         }));
-        throw SDKError.fromResponse(response.status, error);
+        throw SDKError.fromResponse(response.status, errorBody);
       }
       return response;
     } catch (error) {
       clearTimeout(timeoutId);
-      if (error instanceof SDKError) {
-        throw error;
+      if (this.onNetworkError) {
+        const sdkError = error instanceof SDKError ? error : new SDKError(
+          error instanceof Error ? error.message : String(error),
+          0,
+          "NETWORK_ERROR"
+        );
+        this.onNetworkError(sdkError, {
+          method: "GET",
+          path,
+          isRetry: false,
+          attempt: 0
+        });
       }
       throw error;
     }
@@ -814,6 +860,13 @@ var WSClient = class {
     this.timeout = config.timeout ?? 3e4;
     this.authToken = config.authToken;
     this.WebSocketClass = config.WebSocket ?? WebSocket;
+    this.onNetworkError = config.onNetworkError;
+  }
+  /**
+   * Set the network error callback
+   */
+  setOnNetworkError(callback) {
+    this.onNetworkError = callback;
   }
   /**
    * Get the current WebSocket URL
@@ -832,9 +885,16 @@ var WSClient = class {
         this.isClosed = false;
         const timeout = setTimeout(() => {
           this.ws?.close();
-          reject(
-            new SDKError("WebSocket connection timeout", 408, "WS_TIMEOUT")
-          );
+          const error = new SDKError("WebSocket connection timeout", 408, "WS_TIMEOUT");
+          if (this.onNetworkError) {
+            this.onNetworkError(error, {
+              method: "WS",
+              path: this.wsURL,
+              isRetry: false,
+              attempt: 0
+            });
+          }
+          reject(error);
         }, this.timeout);
         this.ws.addEventListener("open", () => {
           clearTimeout(timeout);
@@ -850,6 +910,14 @@ var WSClient = class {
           console.error("[WSClient] WebSocket error:", event);
           clearTimeout(timeout);
           const error = new SDKError("WebSocket error", 500, "WS_ERROR", event);
+          if (this.onNetworkError) {
+            this.onNetworkError(error, {
+              method: "WS",
+              path: this.wsURL,
+              isRetry: false,
+              attempt: 0
+            });
+          }
           this.errorHandlers.forEach((handler) => handler(error));
           reject(error);
         });
@@ -1627,7 +1695,9 @@ function createClient(config) {
     timeout: config.timeout,
     maxRetries: config.maxRetries,
     retryDelayMs: config.retryDelayMs,
-    fetch: config.fetch
+    debug: config.debug,
+    fetch: config.fetch,
+    onNetworkError: config.onNetworkError
   });
   const auth = new AuthClient({
     httpClient,
@@ -1639,7 +1709,8 @@ function createClient(config) {
   const db = new DBClient(httpClient);
   const pubsub = new PubSubClient(httpClient, {
     ...config.wsConfig,
-    wsURL
+    wsURL,
+    onNetworkError: config.onNetworkError
   });
   const network = new NetworkClient(httpClient);
   const cache = new CacheClient(httpClient);