@debros/network-ts-sdk 0.3.4 → 0.4.3

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

@@ -1,11 +1,45 @@
 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;
+    /**
+     * 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,12 +49,21 @@ declare class HttpClient {
     private fetch;
     private apiKey?;
     private jwt?;
+    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;
     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>;
@@ -283,6 +326,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;
@@ -290,13 +338,15 @@ 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;
+    private onNetworkError?;
     private ws?;
     private messageHandlers;
     private errorHandlers;
@@ -304,6 +354,14 @@ 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
+     */
+    get url(): string;
     /**
      * Connect to WebSocket server
      */
@@ -358,17 +416,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 +464,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 +480,7 @@ declare class PubSubClient {
 declare class Subscription {
     private wsClient;
     private topic;
+    private presenceOptions?;
     private messageHandlers;
     private errorHandlers;
     private closeHandlers;
@@ -405,7 +488,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,27 +787,69 @@ declare class StorageClient {
     unpin(cid: string): Promise<void>;
 }
 
-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>;
-    };
+/**
+ * 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>;
+}
+
+/**
+ * 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;
+    /**
+     * Callback invoked on network errors (HTTP and WebSocket).
+     * Use this to trigger gateway failover at the application layer.
+     */
+    onNetworkError?: NetworkErrorCallback;
 }
 interface Client {
     auth: AuthClient;
@@ -724,7 +858,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 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 };