@debros/network-ts-sdk 0.4.2 → 0.6.0

package/src/core/transport/index.ts

@@ -0,0 +1,4 @@
+export { PathBasedAuthStrategy } from "./AuthHeaderStrategy";
+export { ExponentialBackoffRetryPolicy } from "./RequestRetryPolicy";
+export { RequestLogger } from "./RequestLogger";
+export { TLSConfiguration } from "./TLSConfiguration";

package/src/core/ws.ts

@@ -1,11 +1,17 @@
 import WebSocket from "isomorphic-ws";
 import { SDKError } from "../errors";
+import { NetworkErrorCallback } from "./http";
 
 export interface WSClientConfig {
   wsURL: string;
   timeout?: number;
   authToken?: string;
   WebSocket?: typeof WebSocket;
+  /**
+   * Callback invoked on WebSocket errors.
+   * Use this to trigger gateway failover at the application layer.
+   */
+  onNetworkError?: NetworkErrorCallback;
 }
 
 export type WSMessageHandler = (data: string) => void;
@@ -23,6 +29,7 @@ export class WSClient {
   private timeout: number;
   private authToken?: string;
   private WebSocketClass: typeof WebSocket;
+  private onNetworkError?: NetworkErrorCallback;
 
   private ws?: WebSocket;
   private messageHandlers: Set<WSMessageHandler> = new Set();
@@ -36,6 +43,14 @@ export class WSClient {
     this.timeout = config.timeout ?? 30000;
     this.authToken = config.authToken;
     this.WebSocketClass = config.WebSocket ?? WebSocket;
+    this.onNetworkError = config.onNetworkError;
+  }
+
+  /**
+   * Set the network error callback
+   */
+  setOnNetworkError(callback: NetworkErrorCallback | undefined): void {
+    this.onNetworkError = callback;
   }
 
   /**
@@ -57,9 +72,19 @@ export class WSClient {
 
         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");
+
+          // Call the network error callback if configured
+          if (this.onNetworkError) {
+            this.onNetworkError(error, {
+              method: "WS",
+              path: this.wsURL,
+              isRetry: false,
+              attempt: 0,
+            });
+          }
+
+          reject(error);
         }, this.timeout);
 
         this.ws.addEventListener("open", () => {
@@ -78,6 +103,17 @@ export class WSClient {
           console.error("[WSClient] WebSocket error:", event);
           clearTimeout(timeout);
           const error = new SDKError("WebSocket error", 500, "WS_ERROR", event);
+
+          // Call the network error callback if configured
+          if (this.onNetworkError) {
+            this.onNetworkError(error, {
+              method: "WS",
+              path: this.wsURL,
+              isRetry: false,
+              attempt: 0,
+            });
+          }
+
           this.errorHandlers.forEach((handler) => handler(error));
           reject(error);
         });

package/src/db/index.ts

@@ -0,0 +1,13 @@
+export { DBClient } from "./client";
+export { QueryBuilder } from "./qb";
+export { Repository } from "./repository";
+export type {
+  Entity,
+  QueryResponse,
+  TransactionOp,
+  TransactionRequest,
+  SelectOptions,
+  FindOptions,
+  ColumnDefinition,
+} from "./types";
+export { extractTableName, extractPrimaryKey } from "./types";

package/src/functions/index.ts

@@ -0,0 +1,2 @@
+export { FunctionsClient, type FunctionsClientConfig } from "./client";
+export type { FunctionResponse, SuccessResponse } from "./types";

package/src/index.ts

@@ -1,4 +1,4 @@
-import { HttpClient, HttpClientConfig } from "./core/http";
+import { HttpClient, HttpClientConfig, NetworkErrorCallback } from "./core/http";
 import { AuthClient } from "./auth/client";
 import { DBClient } from "./db/client";
 import { PubSubClient } from "./pubsub/client";
@@ -20,6 +20,11 @@ export 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;
 }
 
 export interface Client {
@@ -38,7 +43,9 @@ export function createClient(config: ClientConfig): Client {
     timeout: config.timeout,
     maxRetries: config.maxRetries,
     retryDelayMs: config.retryDelayMs,
+    debug: config.debug,
     fetch: config.fetch,
+    onNetworkError: config.onNetworkError,
   });
 
   const auth = new AuthClient({
@@ -55,6 +62,7 @@ export function createClient(config: ClientConfig): Client {
   const pubsub = new PubSubClient(httpClient, {
     ...config.wsConfig,
     wsURL,
+    onNetworkError: config.onNetworkError,
   });
   const network = new NetworkClient(httpClient);
   const cache = new CacheClient(httpClient);
@@ -73,6 +81,7 @@ export function createClient(config: ClientConfig): Client {
 }
 
 export { HttpClient } from "./core/http";
+export type { NetworkErrorCallback, NetworkErrorContext } from "./core/http";
 export { WSClient } from "./core/ws";
 export { AuthClient } from "./auth/client";
 export { DBClient } from "./db/client";

package/src/network/index.ts

@@ -0,0 +1,7 @@
+export { NetworkClient } from "./client";
+export type {
+  PeerInfo,
+  NetworkStatus,
+  ProxyRequest,
+  ProxyResponse,
+} from "./client";

package/src/pubsub/index.ts

@@ -0,0 +1,12 @@
+export { PubSubClient, Subscription } from "./client";
+export type {
+  PubSubMessage,
+  RawEnvelope,
+  MessageHandler,
+  ErrorHandler,
+  CloseHandler,
+  PresenceMember,
+  PresenceResponse,
+  PresenceOptions,
+  SubscribeOptions,
+} from "./types";

package/src/storage/index.ts

@@ -0,0 +1,7 @@
+export { StorageClient } from "./client";
+export type {
+  StorageUploadResponse,
+  StoragePinRequest,
+  StoragePinResponse,
+  StorageStatus,
+} from "./client";

package/src/utils/codec.ts

@@ -0,0 +1,68 @@
+/**
+ * Base64 Codec for cross-platform encoding/decoding
+ * Works in both Node.js and browser environments
+ */
+export class Base64Codec {
+  /**
+   * Encode string or Uint8Array to base64
+   */
+  static encode(input: string | Uint8Array): string {
+    if (typeof input === "string") {
+      return this.encodeString(input);
+    }
+    return this.encodeBytes(input);
+  }
+
+  /**
+   * Encode string to base64
+   */
+  static encodeString(str: string): string {
+    if (this.isNode()) {
+      return Buffer.from(str).toString("base64");
+    }
+    // Browser
+    return btoa(
+      encodeURIComponent(str).replace(/%([0-9A-F]{2})/g, (match, p1) =>
+        String.fromCharCode(parseInt(p1, 16))
+      )
+    );
+  }
+
+  /**
+   * Encode Uint8Array to base64
+   */
+  static encodeBytes(bytes: Uint8Array): string {
+    if (this.isNode()) {
+      return Buffer.from(bytes).toString("base64");
+    }
+    // Browser
+    let binary = "";
+    for (let i = 0; i < bytes.length; i++) {
+      binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+  }
+
+  /**
+   * Decode base64 to string
+   */
+  static decode(b64: string): string {
+    if (this.isNode()) {
+      return Buffer.from(b64, "base64").toString("utf-8");
+    }
+    // Browser
+    const binary = atob(b64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+      bytes[i] = binary.charCodeAt(i);
+    }
+    return new TextDecoder().decode(bytes);
+  }
+
+  /**
+   * Check if running in Node.js environment
+   */
+  private static isNode(): boolean {
+    return typeof Buffer !== "undefined";
+  }
+}

package/src/utils/index.ts

@@ -0,0 +1,3 @@
+export { Base64Codec } from "./codec";
+export { retryWithBackoff, type RetryConfig } from "./retry";
+export { Platform } from "./platform";

package/src/utils/platform.ts

@@ -0,0 +1,44 @@
+/**
+ * Platform detection utilities
+ * Helps determine runtime environment (Node.js vs Browser)
+ */
+export const Platform = {
+  /**
+   * Check if running in Node.js
+   */
+  isNode: (): boolean => {
+    return typeof process !== "undefined" && !!process.versions?.node;
+  },
+
+  /**
+   * Check if running in browser
+   */
+  isBrowser: (): boolean => {
+    return typeof window !== "undefined";
+  },
+
+  /**
+   * Check if localStorage is available
+   */
+  hasLocalStorage: (): boolean => {
+    try {
+      return typeof localStorage !== "undefined" && localStorage !== null;
+    } catch {
+      return false;
+    }
+  },
+
+  /**
+   * Check if Buffer is available (Node.js)
+   */
+  hasBuffer: (): boolean => {
+    return typeof Buffer !== "undefined";
+  },
+
+  /**
+   * Check if btoa/atob are available (Browser)
+   */
+  hasBase64: (): boolean => {
+    return typeof btoa !== "undefined" && typeof atob !== "undefined";
+  },
+};

package/src/utils/retry.ts

@@ -0,0 +1,58 @@
+/**
+ * Retry configuration
+ */
+export interface RetryConfig {
+  /**
+   * Maximum number of retry attempts
+   */
+  maxAttempts: number;
+
+  /**
+   * Function to calculate backoff delay in milliseconds
+   */
+  backoffMs: (attempt: number) => number;
+
+  /**
+   * Function to determine if error should trigger retry
+   */
+  shouldRetry: (error: any) => boolean;
+}
+
+/**
+ * Retry an operation with exponential backoff
+ * @param operation - The async operation to retry
+ * @param config - Retry configuration
+ * @returns Promise resolving to operation result
+ * @throws Last error if all retries exhausted
+ */
+export async function retryWithBackoff<T>(
+  operation: () => Promise<T>,
+  config: RetryConfig
+): Promise<T> {
+  let lastError: Error | null = null;
+
+  for (let attempt = 1; attempt <= config.maxAttempts; attempt++) {
+    try {
+      return await operation();
+    } catch (error: any) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+
+      // Check if we should retry this error
+      if (!config.shouldRetry(error)) {
+        throw error;
+      }
+
+      // If this was the last attempt, throw
+      if (attempt === config.maxAttempts) {
+        throw error;
+      }
+
+      // Wait before next attempt
+      const delay = config.backoffMs(attempt);
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+  }
+
+  // Fallback (should never reach here)
+  throw lastError || new Error("Retry failed");
+}