@debros/network-ts-sdk 0.3.4 → 0.4.2

package/README.md

@@ -215,6 +215,55 @@ const topics = await client.pubsub.topics();
 console.log("Active topics:", topics);
 ```
 
+### Presence Support
+
+The SDK supports real-time presence tracking, allowing you to see who is currently subscribed to a topic.
+
+#### Subscribe with Presence
+
+Enable presence by providing `presence` options in `subscribe`:
+
+```typescript
+const subscription = await client.pubsub.subscribe("room.123", {
+  onMessage: (msg) => console.log("Message:", msg.data),
+  presence: {
+    enabled: true,
+    memberId: "user-alice",
+    meta: { displayName: "Alice", avatar: "URL" },
+    onJoin: (member) => {
+      console.log(`${member.memberId} joined at ${new Date(member.joinedAt)}`);
+      console.log("Meta:", member.meta);
+    },
+    onLeave: (member) => {
+      console.log(`${member.memberId} left`);
+    },
+  },
+});
+```
+
+#### Get Presence for a Topic
+
+Query current members without subscribing:
+
+```typescript
+const presence = await client.pubsub.getPresence("room.123");
+console.log(`Total members: ${presence.count}`);
+presence.members.forEach((member) => {
+  console.log(`- ${member.memberId} (joined: ${new Date(member.joinedAt)})`);
+});
+```
+
+#### Subscription Helpers
+
+Get presence information from an active subscription:
+
+```typescript
+if (subscription.hasPresence()) {
+  const members = await subscription.getPresence();
+  console.log("Current members:", members);
+}
+```
+
 ### Authentication
 
 #### Switch API Key

package/dist/index.d.ts

@@ -21,6 +21,10 @@ declare class HttpClient {
     private getAuthHeaders;
     private getAuthToken;
     getApiKey(): string | undefined;
+    /**
+     * Get the base URL
+     */
+    getBaseURL(): string;
     request<T = any>(method: "GET" | "POST" | "PUT" | "DELETE", path: string, options?: {
         body?: any;
         headers?: Record<string, string>;
@@ -290,10 +294,11 @@ type WSCloseHandler = () => void;
 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
  */
 declare class WSClient {
-    private url;
+    private wsURL;
     private timeout;
     private authToken?;
     private WebSocketClass;
@@ -304,6 +309,10 @@ declare class WSClient {
     private openHandlers;
     private isClosed;
     constructor(config: WSClientConfig);
+    /**
+     * Get the current WebSocket URL
+     */
+    get url(): string;
     /**
      * Connect to WebSocket server
      */
@@ -358,17 +367,41 @@ declare class WSClient {
     setAuthToken(token?: string): void;
 }
 
-interface Message {
+interface PubSubMessage {
     data: string;
     topic: string;
     timestamp: number;
 }
-type MessageHandler = (message: Message) => void;
+interface PresenceMember {
+    memberId: string;
+    joinedAt: number;
+    meta?: Record<string, unknown>;
+}
+interface PresenceResponse {
+    topic: string;
+    members: PresenceMember[];
+    count: number;
+}
+interface PresenceOptions {
+    enabled: boolean;
+    memberId: string;
+    meta?: Record<string, unknown>;
+    onJoin?: (member: PresenceMember) => void;
+    onLeave?: (member: PresenceMember) => void;
+}
+interface SubscribeOptions {
+    onMessage?: MessageHandler;
+    onError?: ErrorHandler;
+    onClose?: CloseHandler;
+    presence?: PresenceOptions;
+}
+type MessageHandler = (message: PubSubMessage) => void;
 type ErrorHandler = (error: Error) => void;
 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
  */
 declare class PubSubClient {
     private httpClient;
@@ -382,15 +415,15 @@ declare class PubSubClient {
      * List active topics in the current namespace
      */
     topics(): Promise<string[]>;
+    /**
+     * Get current presence for a topic without subscribing
+     */
+    getPresence(topic: string): Promise<PresenceResponse>;
     /**
      * Subscribe to a topic via WebSocket
      * Creates one WebSocket connection per topic
      */
-    subscribe(topic: string, handlers?: {
-        onMessage?: MessageHandler;
-        onError?: ErrorHandler;
-        onClose?: CloseHandler;
-    }): Promise<Subscription>;
+    subscribe(topic: string, options?: SubscribeOptions): Promise<Subscription>;
 }
 /**
  * Subscription represents an active WebSocket subscription to a topic
@@ -398,6 +431,7 @@ declare class PubSubClient {
 declare class Subscription {
     private wsClient;
     private topic;
+    private presenceOptions?;
     private messageHandlers;
     private errorHandlers;
     private closeHandlers;
@@ -405,7 +439,16 @@ declare class Subscription {
     private wsMessageHandler;
     private wsErrorHandler;
     private wsCloseHandler;
-    constructor(wsClient: WSClient, topic: string);
+    private getPresenceFn;
+    constructor(wsClient: WSClient, topic: string, presenceOptions: PresenceOptions | undefined, getPresenceFn: () => Promise<PresenceResponse>);
+    /**
+     * Get current presence (requires presence.enabled on subscribe)
+     */
+    getPresence(): Promise<PresenceMember[]>;
+    /**
+     * Check if presence is enabled for this subscription
+     */
+    hasPresence(): boolean;
     /**
      * Register message handler
      */
@@ -695,6 +738,37 @@ declare class StorageClient {
     unpin(cid: string): Promise<void>;
 }
 
+/**
+ * Functions Client
+ * Client for calling serverless functions on the Orama Network
+ */
+
+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;
+}
+declare class FunctionsClient {
+    private httpClient;
+    private gatewayURL?;
+    private namespace;
+    constructor(httpClient: HttpClient, config?: FunctionsClientConfig);
+    /**
+     * 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
+     */
+    invoke<TInput = any, TOutput = any>(functionName: string, input: TInput): Promise<TOutput>;
+}
+
 declare class SDKError extends Error {
     readonly httpStatus: number;
     readonly code: string;
@@ -710,11 +784,32 @@ declare class SDKError extends Error {
     };
 }
 
+/**
+ * Serverless Functions Types
+ * Type definitions for calling serverless functions on the Orama Network
+ */
+/**
+ * Generic response from a serverless function
+ */
+interface FunctionResponse<T = unknown> {
+    success: boolean;
+    error?: string;
+    data?: T;
+}
+/**
+ * Standard success/error response used by many functions
+ */
+interface SuccessResponse {
+    success: boolean;
+    error?: string;
+}
+
 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;
 }
 interface Client {
@@ -724,7 +819,8 @@ interface Client {
     network: NetworkClient;
     cache: CacheClient;
     storage: StorageClient;
+    functions: FunctionsClient;
 }
 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, HttpClient, LocalStorageAdapter, MemoryStorage, type Message, type MessageHandler, NetworkClient, type NetworkStatus, type PeerInfo, type ProxyRequest, type ProxyResponse, PubSubClient, QueryBuilder, type QueryResponse, Repository, SDKError, type SelectOptions, type StorageAdapter, StorageClient, type StoragePinRequest, type StoragePinResponse, type StorageStatus, type StorageUploadResponse, Subscription, 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 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

@@ -91,6 +91,12 @@ var HttpClient = class {
   getApiKey() {
     return this.apiKey;
   }
+  /**
+   * Get the base URL
+   */
+  getBaseURL() {
+    return this.baseURL;
+  }
   async request(method, path, options = {}) {
     const startTime = performance.now();
     const url = new URL(this.baseURL + path);
@@ -212,7 +218,13 @@ var HttpClient = class {
       }
       return response.text();
     } catch (error) {
-      if (error instanceof SDKError && attempt < this.maxRetries && [408, 429, 500, 502, 503, 504].includes(error.httpStatus)) {
+      const isRetryableError = error instanceof SDKError && [408, 429, 500, 502, 503, 504].includes(error.httpStatus);
+      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))
         );
@@ -798,11 +810,17 @@ var WSClient = class {
     this.closeHandlers = /* @__PURE__ */ new Set();
     this.openHandlers = /* @__PURE__ */ new Set();
     this.isClosed = false;
-    this.url = config.wsURL;
+    this.wsURL = config.wsURL;
     this.timeout = config.timeout ?? 3e4;
     this.authToken = config.authToken;
     this.WebSocketClass = config.WebSocket ?? WebSocket;
   }
+  /**
+   * Get the current WebSocket URL
+   */
+  get url() {
+    return this.wsURL;
+  }
   /**
    * Connect to WebSocket server
    */
@@ -820,7 +838,7 @@ var WSClient = class {
         }, 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();
         });
@@ -833,6 +851,7 @@ var WSClient = class {
           clearTimeout(timeout);
           const error = new SDKError("WebSocket error", 500, "WS_ERROR", event);
           this.errorHandlers.forEach((handler) => handler(error));
+          reject(error);
         });
         this.ws.addEventListener("close", () => {
           clearTimeout(timeout);
@@ -848,7 +867,7 @@ var WSClient = class {
    * Build WebSocket URL with auth token
    */
   buildWSUrl() {
-    let url = this.url;
+    let url = this.wsURL;
     if (this.authToken) {
       const separator = url.includes("?") ? "&" : "?";
       const paramName = this.authToken.startsWith("ak_") ? "api_key" : "token";
@@ -1009,14 +1028,32 @@ var PubSubClient = class {
     );
     return response.topics || [];
   }
+  /**
+   * Get current presence for a topic without subscribing
+   */
+  async getPresence(topic) {
+    const response = await this.httpClient.get(
+      `/v1/pubsub/presence?topic=${encodeURIComponent(topic)}`
+    );
+    return response;
+  }
   /**
    * Subscribe to a topic via WebSocket
    * Creates one WebSocket connection per topic
    */
-  async subscribe(topic, handlers = {}) {
+  async subscribe(topic, options = {}) {
     const wsUrl = new URL(this.wsConfig.wsURL || "ws://127.0.0.1:6001");
     wsUrl.pathname = "/v1/pubsub/ws";
     wsUrl.searchParams.set("topic", topic);
+    let presence;
+    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();
     const wsClient = new WSClient({
       ...this.wsConfig,
@@ -1024,21 +1061,26 @@ var PubSubClient = class {
       authToken
     });
     await wsClient.connect();
-    const subscription = new Subscription(wsClient, topic);
-    if (handlers.onMessage) {
-      subscription.onMessage(handlers.onMessage);
+    const subscription = new Subscription(
+      wsClient,
+      topic,
+      presence,
+      () => this.getPresence(topic)
+    );
+    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;
   }
 };
 var Subscription = class {
-  constructor(wsClient, topic) {
+  constructor(wsClient, topic, presenceOptions, getPresenceFn) {
     this.messageHandlers = /* @__PURE__ */ new Set();
     this.errorHandlers = /* @__PURE__ */ new Set();
     this.closeHandlers = /* @__PURE__ */ new Set();
@@ -1048,12 +1090,31 @@ var Subscription = class {
     this.wsCloseHandler = null;
     this.wsClient = wsClient;
     this.topic = topic;
+    this.presenceOptions = presenceOptions;
+    this.getPresenceFn = getPresenceFn;
     this.wsMessageHandler = (data) => {
       try {
         const envelope = JSON.parse(data);
         if (!envelope || typeof envelope !== "object") {
           throw new Error("Invalid envelope: not an object");
         }
+        if (envelope.type === "presence.join" || envelope.type === "presence.leave") {
+          if (!envelope.member_id) {
+            console.warn("[Subscription] Presence event missing member_id");
+            return;
+          }
+          const 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;
+        }
         if (!envelope.data || typeof envelope.data !== "string") {
           throw new Error("Invalid envelope: missing or invalid data field");
         }
@@ -1090,6 +1151,22 @@ var Subscription = class {
     };
     this.wsClient.onClose(this.wsCloseHandler);
   }
+  /**
+   * Get current presence (requires presence.enabled on subscribe)
+   */
+  async getPresence() {
+    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() {
+    return !!this.presenceOptions?.enabled;
+  }
   /**
    * Register message handler
    */
@@ -1511,6 +1588,38 @@ var StorageClient = class {
   }
 };
 
+// src/functions/client.ts
+var FunctionsClient = class {
+  constructor(httpClient, config) {
+    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(functionName, input) {
+    const url = this.gatewayURL ? `${this.gatewayURL}/v1/invoke/${this.namespace}/${functionName}` : `/v1/invoke/${this.namespace}/${functionName}`;
+    try {
+      const response = await this.httpClient.post(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)
+      );
+    }
+  }
+};
+
 // src/index.ts
 function createClient(config) {
   const httpClient = new HttpClient({
@@ -1526,7 +1635,7 @@ function createClient(config) {
     apiKey: config.apiKey,
     jwt: config.jwt
   });
-  const wsURL = config.wsConfig?.wsURL ?? config.baseURL.replace(/^http/, "ws").replace(/\/$/, "");
+  const wsURL = config.baseURL.replace(/^http/, "ws").replace(/\/$/, "");
   const db = new DBClient(httpClient);
   const pubsub = new PubSubClient(httpClient, {
     ...config.wsConfig,
@@ -1535,19 +1644,22 @@ function createClient(config) {
   const network = new NetworkClient(httpClient);
   const cache = new CacheClient(httpClient);
   const storage = new StorageClient(httpClient);
+  const functions = new FunctionsClient(httpClient, config.functionsConfig);
   return {
     auth,
     db,
     pubsub,
     network,
     cache,
-    storage
+    storage,
+    functions
   };
 }
 export {
   AuthClient,
   CacheClient,
   DBClient,
+  FunctionsClient,
   HttpClient,
   LocalStorageAdapter,
   MemoryStorage,