@debros/network-ts-sdk 0.3.4 → 0.4.3

package/src/core/http.ts

@@ -1,11 +1,35 @@
 import { SDKError } from "../errors";
 
+/**
+ * Context provided to the onNetworkError callback
+ */
+export 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.
+ */
+export type NetworkErrorCallback = (
+  error: SDKError,
+  context: NetworkErrorContext
+) => void;
+
 export interface HttpClientConfig {
   baseURL: string;
   timeout?: number;
   maxRetries?: number;
   retryDelayMs?: number;
   fetch?: typeof fetch;
+  /**
+   * Callback invoked on network errors (after all retries exhausted).
+   * Use this to trigger gateway failover at the application layer.
+   */
+  onNetworkError?: NetworkErrorCallback;
 }
 
 /**
@@ -39,14 +63,23 @@ export class HttpClient {
   private fetch: typeof fetch;
   private apiKey?: string;
   private jwt?: string;
+  private onNetworkError?: NetworkErrorCallback;
 
   constructor(config: HttpClientConfig) {
     this.baseURL = config.baseURL.replace(/\/$/, "");
-    this.timeout = config.timeout ?? 60000; // Increased from 30s to 60s for pub/sub operations
+    this.timeout = config.timeout ?? 60000;
     this.maxRetries = config.maxRetries ?? 3;
     this.retryDelayMs = config.retryDelayMs ?? 1000;
     // Use provided fetch or create one with proper TLS configuration for staging certificates
     this.fetch = config.fetch ?? createFetchWithTLSConfig();
+    this.onNetworkError = config.onNetworkError;
+  }
+
+  /**
+   * Set the network error callback
+   */
+  setOnNetworkError(callback: NetworkErrorCallback | undefined): void {
+    this.onNetworkError = callback;
   }
 
   setApiKey(apiKey?: string) {
@@ -121,6 +154,13 @@ export class HttpClient {
     return this.apiKey;
   }
 
+  /**
+   * Get the base URL
+   */
+  getBaseURL(): string {
+    return this.baseURL;
+  }
+
   async request<T = any>(
     method: "GET" | "POST" | "PUT" | "DELETE",
     path: string,
@@ -251,6 +291,27 @@ export class HttpClient {
           }
         }
       }
+
+      // Call the network error callback if configured
+      // This allows the app to trigger gateway failover
+      if (this.onNetworkError) {
+        // Convert native errors (TypeError, AbortError) to SDKError for the callback
+        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);
@@ -276,22 +337,31 @@ export class HttpClient {
         throw SDKError.fromResponse(response.status, body);
       }
 
+      // Request succeeded - return response
       const contentType = response.headers.get("content-type");
       if (contentType?.includes("application/json")) {
         return response.json();
       }
       return response.text();
     } catch (error) {
-      if (
+      const isRetryableError =
         error instanceof SDKError &&
-        attempt < this.maxRetries &&
-        [408, 429, 500, 502, 503, 504].includes(error.httpStatus)
-      ) {
+        [408, 429, 500, 502, 503, 504].includes(error.httpStatus);
+
+      // Retry on same gateway for retryable HTTP errors
+      if (isRetryableError && attempt < this.maxRetries) {
+        if (typeof console !== "undefined") {
+          console.warn(
+            `[HttpClient] Retrying request (attempt ${attempt + 1}/${this.maxRetries})`
+          );
+        }
         await new Promise((resolve) =>
           setTimeout(resolve, this.retryDelayMs * (attempt + 1))
         );
         return this.requestWithRetry(url, options, attempt + 1, startTime);
       }
+
+      // All retries exhausted - throw error for app to handle
       throw error;
     }
   }
@@ -381,6 +451,25 @@ export class HttpClient {
           error
         );
       }
+
+      // Call the network error callback if configured
+      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);
@@ -409,17 +498,33 @@ export class HttpClient {
       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;
+
+      // Call the network error callback if configured
+      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;
     }
   }

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;
@@ -15,13 +21,15 @@ export type WSOpenHandler = () => void;
 
 /**
  * Simple WebSocket client with minimal abstractions
- * No complex reconnection, no heartbeats - keep it simple
+ * No complex reconnection, no failover - keep it simple
+ * Gateway failover is handled at the application layer
  */
 export class WSClient {
-  private url: string;
+  private wsURL: string;
   private timeout: number;
   private authToken?: string;
   private WebSocketClass: typeof WebSocket;
+  private onNetworkError?: NetworkErrorCallback;
 
   private ws?: WebSocket;
   private messageHandlers: Set<WSMessageHandler> = new Set();
@@ -31,10 +39,25 @@ export class WSClient {
   private isClosed = false;
 
   constructor(config: WSClientConfig) {
-    this.url = config.wsURL;
+    this.wsURL = config.wsURL;
     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;
+  }
+
+  /**
+   * Get the current WebSocket URL
+   */
+  get url(): string {
+    return this.wsURL;
   }
 
   /**
@@ -49,14 +72,24 @@ 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", () => {
           clearTimeout(timeout);
-          console.log("[WSClient] Connected to", this.url);
+          console.log("[WSClient] Connected to", this.wsURL);
           this.openHandlers.forEach((handler) => handler());
           resolve();
         });
@@ -70,7 +103,19 @@ 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);
         });
 
         this.ws.addEventListener("close", () => {
@@ -88,7 +133,7 @@ export class WSClient {
    * Build WebSocket URL with auth token
    */
   private buildWSUrl(): string {
-    let url = this.url;
+    let url = this.wsURL;
 
     if (this.authToken) {
       const separator = url.includes("?") ? "&" : "?";

package/src/functions/client.ts

@@ -0,0 +1,62 @@
+/**
+ * Functions Client
+ * Client for calling serverless functions on the Orama Network
+ */
+
+import { HttpClient } from "../core/http";
+import { SDKError } from "../errors";
+
+export interface FunctionsClientConfig {
+  /**
+   * Base URL for the functions gateway
+   * Defaults to using the same baseURL as the HTTP client
+   */
+  gatewayURL?: string;
+  
+  /**
+   * Namespace for the functions
+   */
+  namespace: string;
+}
+
+export class FunctionsClient {
+  private httpClient: HttpClient;
+  private gatewayURL?: string;
+  private namespace: string;
+
+  constructor(httpClient: HttpClient, config?: FunctionsClientConfig) {
+    this.httpClient = httpClient;
+    this.gatewayURL = config?.gatewayURL;
+    this.namespace = config?.namespace ?? "default";
+  }
+
+  /**
+   * Invoke a serverless function by name
+   * 
+   * @param functionName - Name of the function to invoke
+   * @param input - Input payload for the function
+   * @returns The function response
+   */
+  async invoke<TInput = any, TOutput = any>(
+    functionName: string,
+    input: TInput
+  ): Promise<TOutput> {
+    const url = this.gatewayURL
+      ? `${this.gatewayURL}/v1/invoke/${this.namespace}/${functionName}`
+      : `/v1/invoke/${this.namespace}/${functionName}`;
+
+    try {
+      const response = await this.httpClient.post<TOutput>(url, input);
+      return response;
+    } catch (error) {
+      if (error instanceof SDKError) {
+        throw error;
+      }
+      throw new SDKError(
+        `Function ${functionName} failed`,
+        500,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  }
+}

package/src/functions/types.ts

@@ -0,0 +1,21 @@
+/**
+ * Serverless Functions Types
+ * Type definitions for calling serverless functions on the Orama Network
+ */
+
+/**
+ * Generic response from a serverless function
+ */
+export interface FunctionResponse<T = unknown> {
+  success: boolean;
+  error?: string;
+  data?: T;
+}
+
+/**
+ * Standard success/error response used by many functions
+ */
+export interface SuccessResponse {
+  success: boolean;
+  error?: string;
+}

package/src/index.ts

@@ -1,10 +1,11 @@
-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";
 import { NetworkClient } from "./network/client";
 import { CacheClient } from "./cache/client";
 import { StorageClient } from "./storage/client";
+import { FunctionsClient, FunctionsClientConfig } from "./functions/client";
 import { WSClientConfig } from "./core/ws";
 import {
   StorageAdapter,
@@ -16,8 +17,14 @@ export interface ClientConfig extends Omit<HttpClientConfig, "fetch"> {
   apiKey?: string;
   jwt?: string;
   storage?: StorageAdapter;
-  wsConfig?: Partial<WSClientConfig>;
+  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 {
@@ -27,6 +34,7 @@ export interface Client {
   network: NetworkClient;
   cache: CacheClient;
   storage: StorageClient;
+  functions: FunctionsClient;
 }
 
 export function createClient(config: ClientConfig): Client {
@@ -36,6 +44,7 @@ export function createClient(config: ClientConfig): Client {
     maxRetries: config.maxRetries,
     retryDelayMs: config.retryDelayMs,
     fetch: config.fetch,
+    onNetworkError: config.onNetworkError,
   });
 
   const auth = new AuthClient({
@@ -45,19 +54,19 @@ export function createClient(config: ClientConfig): Client {
     jwt: config.jwt,
   });
 
-  // Derive WebSocket URL from baseURL if not explicitly provided
-  const wsURL =
-    config.wsConfig?.wsURL ??
-    config.baseURL.replace(/^http/, "ws").replace(/\/$/, "");
+  // Derive WebSocket URL from baseURL
+  const wsURL = config.baseURL.replace(/^http/, "ws").replace(/\/$/, "");
 
   const db = new DBClient(httpClient);
   const pubsub = new PubSubClient(httpClient, {
     ...config.wsConfig,
     wsURL,
+    onNetworkError: config.onNetworkError,
   });
   const network = new NetworkClient(httpClient);
   const cache = new CacheClient(httpClient);
   const storage = new StorageClient(httpClient);
+  const functions = new FunctionsClient(httpClient, config.functionsConfig);
 
   return {
     auth,
@@ -66,10 +75,12 @@ export function createClient(config: ClientConfig): Client {
     network,
     cache,
     storage,
+    functions,
   };
 }
 
 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";
@@ -79,16 +90,21 @@ export { PubSubClient, Subscription } from "./pubsub/client";
 export { NetworkClient } from "./network/client";
 export { CacheClient } from "./cache/client";
 export { StorageClient } from "./storage/client";
+export { FunctionsClient } from "./functions/client";
 export { SDKError } from "./errors";
 export { MemoryStorage, LocalStorageAdapter } from "./auth/types";
 export type { StorageAdapter, AuthConfig, WhoAmI } from "./auth/types";
 export type * from "./db/types";
 export type {
-  Message,
   MessageHandler,
   ErrorHandler,
   CloseHandler,
-} from "./pubsub/client";
+  PresenceMember,
+  PresenceResponse,
+  PresenceOptions,
+  SubscribeOptions,
+} from "./pubsub/types";
+export { type PubSubMessage } from "./pubsub/types";
 export type {
   PeerInfo,
   NetworkStatus,
@@ -114,3 +130,5 @@ export type {
   StoragePinResponse,
   StorageStatus,
 } from "./storage/client";
+export type { FunctionsClientConfig } from "./functions/client";
+export type * from "./functions/types";