@debros/network-ts-sdk 0.3.2 → 0.4.2

package/src/core/ws.ts

@@ -15,10 +15,11 @@ 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;
@@ -31,12 +32,19 @@ 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;
   }
 
+  /**
+   * Get the current WebSocket URL
+   */
+  get url(): string {
+    return this.wsURL;
+  }
+
   /**
    * Connect to WebSocket server
    */
@@ -56,7 +64,7 @@ export class WSClient {
 
         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();
         });
@@ -71,6 +79,7 @@ export class WSClient {
           clearTimeout(timeout);
           const error = new SDKError("WebSocket error", 500, "WS_ERROR", event);
           this.errorHandlers.forEach((handler) => handler(error));
+          reject(error);
         });
 
         this.ws.addEventListener("close", () => {
@@ -88,7 +97,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

@@ -5,6 +5,7 @@ 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,7 +17,8 @@ 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;
 }
 
@@ -27,6 +29,7 @@ export interface Client {
   network: NetworkClient;
   cache: CacheClient;
   storage: StorageClient;
+  functions: FunctionsClient;
 }
 
 export function createClient(config: ClientConfig): Client {
@@ -45,10 +48,8 @@ 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, {
@@ -58,6 +59,7 @@ export function createClient(config: ClientConfig): Client {
   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,6 +68,7 @@ export function createClient(config: ClientConfig): Client {
     network,
     cache,
     storage,
+    functions,
   };
 }
 
@@ -79,16 +82,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 +122,5 @@ export type {
   StoragePinResponse,
   StorageStatus,
 } from "./storage/client";
+export type { FunctionsClientConfig } from "./functions/client";
+export type * from "./functions/types";

package/src/pubsub/client.ts

@@ -1,17 +1,16 @@
 import { HttpClient } from "../core/http";
 import { WSClient, WSClientConfig } from "../core/ws";
-
-export interface Message {
-  data: string;
-  topic: string;
-  timestamp: number;
-}
-
-export interface RawEnvelope {
-  data: string; // base64-encoded
-  timestamp: number;
-  topic: string;
-}
+import {
+  PubSubMessage,
+  RawEnvelope,
+  MessageHandler,
+  ErrorHandler,
+  CloseHandler,
+  SubscribeOptions,
+  PresenceResponse,
+  PresenceMember,
+  PresenceOptions,
+} from "./types";
 
 // Cross-platform base64 encoding/decoding utilities
 function base64Encode(str: string): string {
@@ -54,13 +53,9 @@ function base64Decode(b64: string): string {
   throw new Error("No base64 decoding method available");
 }
 
-export type MessageHandler = (message: Message) => void;
-export type ErrorHandler = (error: Error) => void;
-export type CloseHandler = () => void;
-
 /**
  * Simple PubSub client - one WebSocket connection per topic
- * No connection pooling, no reference counting - keep it simple
+ * Gateway failover is handled at the application layer
  */
 export class PubSubClient {
   private httpClient: HttpClient;
@@ -104,23 +99,40 @@ export class PubSubClient {
     return response.topics || [];
   }
 
+  /**
+   * Get current presence for a topic without subscribing
+   */
+  async getPresence(topic: string): Promise<PresenceResponse> {
+    const response = await this.httpClient.get<PresenceResponse>(
+      `/v1/pubsub/presence?topic=${encodeURIComponent(topic)}`
+    );
+    return response;
+  }
+
   /**
    * Subscribe to a topic via WebSocket
    * Creates one WebSocket connection per topic
    */
   async subscribe(
     topic: string,
-    handlers: {
-      onMessage?: MessageHandler;
-      onError?: ErrorHandler;
-      onClose?: CloseHandler;
-    } = {}
+    options: SubscribeOptions = {}
   ): Promise<Subscription> {
     // Build WebSocket URL for this topic
     const wsUrl = new URL(this.wsConfig.wsURL || "ws://127.0.0.1:6001");
     wsUrl.pathname = "/v1/pubsub/ws";
     wsUrl.searchParams.set("topic", topic);
 
+    // Handle presence options
+    let presence: PresenceOptions | undefined;
+    if (options.presence?.enabled) {
+      presence = options.presence;
+      wsUrl.searchParams.set("presence", "true");
+      wsUrl.searchParams.set("member_id", presence.memberId);
+      if (presence.meta) {
+        wsUrl.searchParams.set("member_meta", JSON.stringify(presence.meta));
+      }
+    }
+
     const authToken = this.httpClient.getApiKey() ?? this.httpClient.getToken();
 
     // Create WebSocket client
@@ -133,16 +145,18 @@ export class PubSubClient {
     await wsClient.connect();
 
     // Create subscription wrapper
-    const subscription = new Subscription(wsClient, topic);
+    const subscription = new Subscription(wsClient, topic, presence, () =>
+      this.getPresence(topic)
+    );
 
-    if (handlers.onMessage) {
-      subscription.onMessage(handlers.onMessage);
+    if (options.onMessage) {
+      subscription.onMessage(options.onMessage);
     }
-    if (handlers.onError) {
-      subscription.onError(handlers.onError);
+    if (options.onError) {
+      subscription.onError(options.onError);
     }
-    if (handlers.onClose) {
-      subscription.onClose(handlers.onClose);
+    if (options.onClose) {
+      subscription.onClose(options.onClose);
     }
 
     return subscription;
@@ -155,6 +169,7 @@ export class PubSubClient {
 export class Subscription {
   private wsClient: WSClient;
   private topic: string;
+  private presenceOptions?: PresenceOptions;
   private messageHandlers: Set<MessageHandler> = new Set();
   private errorHandlers: Set<ErrorHandler> = new Set();
   private closeHandlers: Set<CloseHandler> = new Set();
@@ -162,10 +177,18 @@ export class Subscription {
   private wsMessageHandler: ((data: string) => void) | null = null;
   private wsErrorHandler: ((error: Error) => void) | null = null;
   private wsCloseHandler: (() => void) | null = null;
+  private getPresenceFn: () => Promise<PresenceResponse>;
 
-  constructor(wsClient: WSClient, topic: string) {
+  constructor(
+    wsClient: WSClient,
+    topic: string,
+    presenceOptions: PresenceOptions | undefined,
+    getPresenceFn: () => Promise<PresenceResponse>
+  ) {
     this.wsClient = wsClient;
     this.topic = topic;
+    this.presenceOptions = presenceOptions;
+    this.getPresenceFn = getPresenceFn;
 
     // Register message handler
     this.wsMessageHandler = (data) => {
@@ -177,6 +200,37 @@ export class Subscription {
         if (!envelope || typeof envelope !== "object") {
           throw new Error("Invalid envelope: not an object");
         }
+
+        // Handle presence events
+        if (
+          envelope.type === "presence.join" ||
+          envelope.type === "presence.leave"
+        ) {
+          if (!envelope.member_id) {
+            console.warn("[Subscription] Presence event missing member_id");
+            return;
+          }
+
+          const presenceMember: PresenceMember = {
+            memberId: envelope.member_id,
+            joinedAt: envelope.timestamp,
+            meta: envelope.meta,
+          };
+
+          if (
+            envelope.type === "presence.join" &&
+            this.presenceOptions?.onJoin
+          ) {
+            this.presenceOptions.onJoin(presenceMember);
+          } else if (
+            envelope.type === "presence.leave" &&
+            this.presenceOptions?.onLeave
+          ) {
+            this.presenceOptions.onLeave(presenceMember);
+          }
+          return; // Don't call regular onMessage for presence events
+        }
+
         if (!envelope.data || typeof envelope.data !== "string") {
           throw new Error("Invalid envelope: missing or invalid data field");
         }
@@ -192,7 +246,7 @@ export class Subscription {
         // Decode base64 data
         const messageData = base64Decode(envelope.data);
 
-        const message: Message = {
+        const message: PubSubMessage = {
           topic: envelope.topic,
           data: messageData,
           timestamp: envelope.timestamp,
@@ -223,6 +277,25 @@ export class Subscription {
     this.wsClient.onClose(this.wsCloseHandler);
   }
 
+  /**
+   * Get current presence (requires presence.enabled on subscribe)
+   */
+  async getPresence(): Promise<PresenceMember[]> {
+    if (!this.presenceOptions?.enabled) {
+      throw new Error("Presence is not enabled for this subscription");
+    }
+
+    const response = await this.getPresenceFn();
+    return response.members;
+  }
+
+  /**
+   * Check if presence is enabled for this subscription
+   */
+  hasPresence(): boolean {
+    return !!this.presenceOptions?.enabled;
+  }
+
   /**
    * Register message handler
    */

package/src/pubsub/types.ts

@@ -0,0 +1,46 @@
+export interface PubSubMessage {
+  data: string;
+  topic: string;
+  timestamp: number;
+}
+
+export interface RawEnvelope {
+  type?: string;
+  data: string; // base64-encoded
+  timestamp: number;
+  topic: string;
+  member_id?: string;
+  meta?: Record<string, unknown>;
+}
+
+export interface PresenceMember {
+  memberId: string;
+  joinedAt: number;
+  meta?: Record<string, unknown>;
+}
+
+export interface PresenceResponse {
+  topic: string;
+  members: PresenceMember[];
+  count: number;
+}
+
+export interface PresenceOptions {
+  enabled: boolean;
+  memberId: string;
+  meta?: Record<string, unknown>;
+  onJoin?: (member: PresenceMember) => void;
+  onLeave?: (member: PresenceMember) => void;
+}
+
+export interface SubscribeOptions {
+  onMessage?: MessageHandler;
+  onError?: ErrorHandler;
+  onClose?: CloseHandler;
+  presence?: PresenceOptions;
+}
+
+export type MessageHandler = (message: PubSubMessage) => void;
+export type ErrorHandler = (error: Error) => void;
+export type CloseHandler = () => void;
+