@debros/network-ts-sdk 0.1.5 → 0.3.1

package/README.md

@@ -122,10 +122,23 @@ const results = await client.db.transaction([
 
 ### Pub/Sub Messaging
 
+The SDK provides a robust pub/sub client with:
+
+- **Multi-subscriber support**: Multiple connections can subscribe to the same topic
+- **Namespace isolation**: Topics are scoped to your authenticated namespace
+- **Server timestamps**: Messages preserve server-side timestamps
+- **Binary-safe**: Supports both string and binary (`Uint8Array`) payloads
+- **Strict envelope validation**: Type-safe message parsing with error handling
+
 #### Publish a Message
 
 ```typescript
+// Publish a string message
 await client.pubsub.publish("notifications", "Hello, Network!");
+
+// Publish binary data
+const binaryData = new Uint8Array([1, 2, 3, 4]);
+await client.pubsub.publish("binary-topic", binaryData);
 ```
 
 #### Subscribe to Topics
@@ -133,7 +146,9 @@ await client.pubsub.publish("notifications", "Hello, Network!");
 ```typescript
 const subscription = await client.pubsub.subscribe("notifications", {
   onMessage: (msg) => {
-    console.log("Received:", msg.data);
+    console.log("Topic:", msg.topic);
+    console.log("Data:", msg.data);
+    console.log("Server timestamp:", new Date(msg.timestamp));
   },
   onError: (err) => {
     console.error("Subscription error:", err);
@@ -147,6 +162,52 @@ const subscription = await client.pubsub.subscribe("notifications", {
 subscription.close();
 ```
 
+**Message Interface:**
+
+```typescript
+interface Message {
+  data: string; // Decoded message payload (string)
+  topic: string; // Topic name
+  timestamp: number; // Server timestamp in milliseconds
+}
+```
+
+#### Debug Raw Envelopes
+
+For debugging, you can inspect raw message envelopes before decoding:
+
+```typescript
+const subscription = await client.pubsub.subscribe("notifications", {
+  onMessage: (msg) => {
+    console.log("Decoded message:", msg.data);
+  },
+  onRaw: (envelope) => {
+    console.log("Raw envelope:", envelope);
+    // { data: "base64...", timestamp: 1234567890, topic: "notifications" }
+  },
+});
+```
+
+#### Multi-Subscriber Support
+
+Multiple subscriptions to the same topic are supported. Each receives its own copy of messages:
+
+```typescript
+// First subscriber
+const sub1 = await client.pubsub.subscribe("events", {
+  onMessage: (msg) => console.log("Sub1:", msg.data),
+});
+
+// Second subscriber (both receive messages)
+const sub2 = await client.pubsub.subscribe("events", {
+  onMessage: (msg) => console.log("Sub2:", msg.data),
+});
+
+// Unsubscribe independently
+sub1.close(); // sub2 still active
+sub2.close(); // fully unsubscribed
+```
+
 #### List Topics
 
 ```typescript
@@ -211,6 +272,40 @@ peers.forEach((peer) => {
 });
 ```
 
+#### Proxy Requests Through Anyone Network
+
+Make anonymous HTTP requests through the Anyone network:
+
+```typescript
+// Simple GET request
+const response = await client.network.proxyAnon({
+  url: "https://api.example.com/data",
+  method: "GET",
+  headers: {
+    Accept: "application/json",
+  },
+});
+
+console.log(response.status_code); // 200
+console.log(response.body); // Response data as string
+console.log(response.headers); // Response headers
+
+// POST request with body
+const postResponse = await client.network.proxyAnon({
+  url: "https://api.example.com/submit",
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+  },
+  body: JSON.stringify({ key: "value" }),
+});
+
+// Parse JSON response
+const data = JSON.parse(postResponse.body);
+```
+
+**Note:** The proxy endpoint requires authentication (API key or JWT) and only works when the Anyone relay is running on the gateway server.
+
 ## Configuration
 
 ### ClientConfig

package/dist/index.d.ts

@@ -20,16 +20,29 @@ declare class HttpClient {
     setJwt(jwt?: string): void;
     private getAuthHeaders;
     private getAuthToken;
+    getApiKey(): string | undefined;
     request<T = any>(method: "GET" | "POST" | "PUT" | "DELETE", path: string, options?: {
         body?: any;
         headers?: Record<string, string>;
         query?: Record<string, string | number | boolean>;
+        timeout?: number;
     }): Promise<T>;
     private requestWithRetry;
     get<T = any>(path: string, options?: Omit<Parameters<typeof this.request>[2], "body">): Promise<T>;
     post<T = any>(path: string, body?: any, options?: Omit<Parameters<typeof this.request>[2], "body">): Promise<T>;
     put<T = any>(path: string, body?: any, options?: Omit<Parameters<typeof this.request>[2], "body">): Promise<T>;
     delete<T = any>(path: string, options?: Omit<Parameters<typeof this.request>[2], "body">): Promise<T>;
+    /**
+     * Upload a file using multipart/form-data
+     * This is a special method for file uploads that bypasses JSON serialization
+     */
+    uploadFile<T = any>(path: string, formData: FormData, options?: {
+        timeout?: number;
+    }): Promise<T>;
+    /**
+     * Get a binary response (returns Response object for streaming)
+     */
+    getBinary(path: string): Promise<Response>;
     getToken(): string | undefined;
 }
 
@@ -76,8 +89,62 @@ declare class AuthClient {
     getToken(): string | undefined;
     whoami(): Promise<WhoAmI>;
     refresh(): Promise<string>;
+    /**
+     * Logout user and clear JWT, but preserve API key
+     * Use this for user logout in apps where API key is app-level credential
+     */
+    logoutUser(): Promise<void>;
+    /**
+     * Full logout - clears both JWT and API key
+     * Use this to completely reset authentication state
+     */
     logout(): Promise<void>;
     clear(): Promise<void>;
+    /**
+     * Request a challenge nonce for wallet authentication
+     */
+    challenge(params: {
+        wallet: string;
+        purpose?: string;
+        namespace?: string;
+    }): Promise<{
+        nonce: string;
+        wallet: string;
+        namespace: string;
+        expires_at: string;
+    }>;
+    /**
+     * Verify wallet signature and get JWT token
+     */
+    verify(params: {
+        wallet: string;
+        nonce: string;
+        signature: string;
+        namespace?: string;
+        chain_type?: "ETH" | "SOL";
+    }): Promise<{
+        access_token: string;
+        refresh_token?: string;
+        subject: string;
+        namespace: string;
+        api_key?: string;
+        expires_in?: number;
+        token_type?: string;
+    }>;
+    /**
+     * Get API key for wallet (creates namespace ownership)
+     */
+    getApiKey(params: {
+        wallet: string;
+        nonce: string;
+        signature: string;
+        namespace?: string;
+        chain_type?: "ETH" | "SOL";
+    }): Promise<{
+        api_key: string;
+        namespace: string;
+        wallet: string;
+    }>;
 }
 
 declare class QueryBuilder {
@@ -214,70 +281,110 @@ declare class DBClient {
 interface WSClientConfig {
     wsURL: string;
     timeout?: number;
-    maxReconnectAttempts?: number;
-    reconnectDelayMs?: number;
-    heartbeatIntervalMs?: number;
-    authMode?: "header" | "query";
     authToken?: string;
     WebSocket?: typeof WebSocket;
 }
 type WSMessageHandler = (data: string) => void;
 type WSErrorHandler = (error: Error) => void;
 type WSCloseHandler = () => void;
+type WSOpenHandler = () => void;
+/**
+ * Simple WebSocket client with minimal abstractions
+ * No complex reconnection, no heartbeats - keep it simple
+ */
 declare class WSClient {
     private url;
     private timeout;
-    private maxReconnectAttempts;
-    private reconnectDelayMs;
-    private heartbeatIntervalMs;
-    private authMode;
     private authToken?;
     private WebSocketClass;
     private ws?;
-    private reconnectAttempts;
-    private heartbeatInterval?;
     private messageHandlers;
     private errorHandlers;
     private closeHandlers;
-    private isManuallyClosed;
+    private openHandlers;
+    private isClosed;
     constructor(config: WSClientConfig);
+    /**
+     * Connect to WebSocket server
+     */
     connect(): Promise<void>;
+    /**
+     * Build WebSocket URL with auth token
+     */
     private buildWSUrl;
-    private startHeartbeat;
-    private stopHeartbeat;
-    private attemptReconnect;
-    onMessage(handler: WSMessageHandler): () => boolean;
-    onError(handler: WSErrorHandler): () => boolean;
-    onClose(handler: WSCloseHandler): () => boolean;
+    /**
+     * Register message handler
+     */
+    onMessage(handler: WSMessageHandler): () => void;
+    /**
+     * Unregister message handler
+     */
+    offMessage(handler: WSMessageHandler): void;
+    /**
+     * Register error handler
+     */
+    onError(handler: WSErrorHandler): () => void;
+    /**
+     * Unregister error handler
+     */
+    offError(handler: WSErrorHandler): void;
+    /**
+     * Register close handler
+     */
+    onClose(handler: WSCloseHandler): () => void;
+    /**
+     * Unregister close handler
+     */
+    offClose(handler: WSCloseHandler): void;
+    /**
+     * Register open handler
+     */
+    onOpen(handler: WSOpenHandler): () => void;
+    /**
+     * Send data through WebSocket
+     */
     send(data: string): void;
+    /**
+     * Close WebSocket connection
+     */
     close(): void;
+    /**
+     * Check if WebSocket is connected
+     */
     isConnected(): boolean;
+    /**
+     * Update auth token
+     */
     setAuthToken(token?: string): void;
 }
 
 interface Message {
     data: string;
     topic: string;
-    timestamp?: number;
+    timestamp: number;
 }
 type MessageHandler = (message: Message) => 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
+ */
 declare class PubSubClient {
     private httpClient;
     private wsConfig;
     constructor(httpClient: HttpClient, wsConfig?: Partial<WSClientConfig>);
     /**
-     * Publish a message to a topic.
+     * Publish a message to a topic via HTTP
      */
     publish(topic: string, data: string | Uint8Array): Promise<void>;
     /**
-     * List active topics in the current namespace.
+     * List active topics in the current namespace
      */
     topics(): Promise<string[]>;
     /**
-     * Subscribe to a topic via WebSocket.
-     * Returns a subscription object with event handlers.
+     * Subscribe to a topic via WebSocket
+     * Creates one WebSocket connection per topic
      */
     subscribe(topic: string, handlers?: {
         onMessage?: MessageHandler;
@@ -285,17 +392,39 @@ declare class PubSubClient {
         onClose?: CloseHandler;
     }): Promise<Subscription>;
 }
+/**
+ * Subscription represents an active WebSocket subscription to a topic
+ */
 declare class Subscription {
     private wsClient;
     private topic;
     private messageHandlers;
     private errorHandlers;
     private closeHandlers;
+    private isClosed;
+    private wsMessageHandler;
+    private wsErrorHandler;
+    private wsCloseHandler;
     constructor(wsClient: WSClient, topic: string);
-    onMessage(handler: MessageHandler): () => boolean;
-    onError(handler: ErrorHandler): () => boolean;
-    onClose(handler: CloseHandler): () => boolean;
+    /**
+     * Register message handler
+     */
+    onMessage(handler: MessageHandler): () => void;
+    /**
+     * Register error handler
+     */
+    onError(handler: ErrorHandler): () => void;
+    /**
+     * Register close handler
+     */
+    onClose(handler: CloseHandler): () => void;
+    /**
+     * Close subscription and underlying WebSocket
+     */
     close(): void;
+    /**
+     * Check if subscription is active
+     */
     isConnected(): boolean;
 }
 
@@ -305,9 +434,23 @@ interface PeerInfo {
     lastSeen?: string;
 }
 interface NetworkStatus {
-    healthy: boolean;
-    peers: number;
-    uptime?: number;
+    node_id: string;
+    connected: boolean;
+    peer_count: number;
+    database_size: number;
+    uptime: number;
+}
+interface ProxyRequest {
+    url: string;
+    method: string;
+    headers?: Record<string, string>;
+    body?: string;
+}
+interface ProxyResponse {
+    status_code: number;
+    headers: Record<string, string>;
+    body: string;
+    error?: string;
 }
 declare class NetworkClient {
     private httpClient;
@@ -332,6 +475,224 @@ declare class NetworkClient {
      * Disconnect from a peer.
      */
     disconnect(peerId: string): Promise<void>;
+    /**
+     * Proxy an HTTP request through the Anyone network.
+     * Requires authentication (API key or JWT).
+     *
+     * @param request - The proxy request configuration
+     * @returns The proxied response
+     * @throws {SDKError} If the Anyone proxy is not available or the request fails
+     *
+     * @example
+     * ```ts
+     * const response = await client.network.proxyAnon({
+     *   url: 'https://api.example.com/data',
+     *   method: 'GET',
+     *   headers: {
+     *     'Accept': 'application/json'
+     *   }
+     * });
+     *
+     * console.log(response.status_code); // 200
+     * console.log(response.body); // Response data
+     * ```
+     */
+    proxyAnon(request: ProxyRequest): Promise<ProxyResponse>;
+}
+
+interface CacheGetRequest {
+    dmap: string;
+    key: string;
+}
+interface CacheGetResponse {
+    key: string;
+    value: any;
+    dmap: string;
+}
+interface CachePutRequest {
+    dmap: string;
+    key: string;
+    value: any;
+    ttl?: string;
+}
+interface CachePutResponse {
+    status: string;
+    key: string;
+    dmap: string;
+}
+interface CacheDeleteRequest {
+    dmap: string;
+    key: string;
+}
+interface CacheDeleteResponse {
+    status: string;
+    key: string;
+    dmap: string;
+}
+interface CacheMultiGetRequest {
+    dmap: string;
+    keys: string[];
+}
+interface CacheMultiGetResponse {
+    results: Array<{
+        key: string;
+        value: any;
+    }>;
+    dmap: string;
+}
+interface CacheScanRequest {
+    dmap: string;
+    match?: string;
+}
+interface CacheScanResponse {
+    keys: string[];
+    count: number;
+    dmap: string;
+}
+interface CacheHealthResponse {
+    status: string;
+    service: string;
+}
+declare class CacheClient {
+    private httpClient;
+    constructor(httpClient: HttpClient);
+    /**
+     * Check cache service health
+     */
+    health(): Promise<CacheHealthResponse>;
+    /**
+     * Get a value from cache
+     * Returns null if the key is not found (cache miss/expired), which is normal behavior
+     */
+    get(dmap: string, key: string): Promise<CacheGetResponse | null>;
+    /**
+     * Put a value into cache
+     */
+    put(dmap: string, key: string, value: any, ttl?: string): Promise<CachePutResponse>;
+    /**
+     * Delete a value from cache
+     */
+    delete(dmap: string, key: string): Promise<CacheDeleteResponse>;
+    /**
+     * Get multiple values from cache in a single request
+     * Returns a map of key -> value (or null if not found)
+     * Gracefully handles 404 errors (endpoint not implemented) by returning empty results
+     */
+    multiGet(dmap: string, keys: string[]): Promise<Map<string, any | null>>;
+    /**
+     * Scan keys in a distributed map, optionally matching a regex pattern
+     */
+    scan(dmap: string, match?: string): Promise<CacheScanResponse>;
+}
+
+interface StorageUploadResponse {
+    cid: string;
+    name: string;
+    size: number;
+}
+interface StoragePinRequest {
+    cid: string;
+    name?: string;
+}
+interface StoragePinResponse {
+    cid: string;
+    name: string;
+}
+interface StorageStatus {
+    cid: string;
+    name: string;
+    status: string;
+    replication_min: number;
+    replication_max: number;
+    replication_factor: number;
+    peers: string[];
+    error?: string;
+}
+declare class StorageClient {
+    private httpClient;
+    constructor(httpClient: HttpClient);
+    /**
+     * Upload content to IPFS and optionally pin it.
+     * Supports both File objects (browser) and Buffer/ReadableStream (Node.js).
+     *
+     * @param file - File to upload (File, Blob, or Buffer)
+     * @param name - Optional filename
+     * @param options - Optional upload options
+     * @param options.pin - Whether to pin the content (default: true). Pinning happens asynchronously on the backend.
+     * @returns Upload result with CID
+     *
+     * @example
+     * ```ts
+     * // Browser
+     * const fileInput = document.querySelector('input[type="file"]');
+     * const file = fileInput.files[0];
+     * const result = await client.storage.upload(file, file.name);
+     * console.log(result.cid);
+     *
+     * // Node.js
+     * const fs = require('fs');
+     * const fileBuffer = fs.readFileSync('image.jpg');
+     * const result = await client.storage.upload(fileBuffer, 'image.jpg', { pin: true });
+     * ```
+     */
+    upload(file: File | Blob | ArrayBuffer | Uint8Array | ReadableStream<Uint8Array>, name?: string, options?: {
+        pin?: boolean;
+    }): Promise<StorageUploadResponse>;
+    /**
+     * Pin an existing CID
+     *
+     * @param cid - Content ID to pin
+     * @param name - Optional name for the pin
+     * @returns Pin result
+     */
+    pin(cid: string, name?: string): Promise<StoragePinResponse>;
+    /**
+     * Get the pin status for a CID
+     *
+     * @param cid - Content ID to check
+     * @returns Pin status information
+     */
+    status(cid: string): Promise<StorageStatus>;
+    /**
+     * Retrieve content from IPFS by CID
+     *
+     * @param cid - Content ID to retrieve
+     * @returns ReadableStream of the content
+     *
+     * @example
+     * ```ts
+     * const stream = await client.storage.get(cid);
+     * const reader = stream.getReader();
+     * while (true) {
+     *   const { done, value } = await reader.read();
+     *   if (done) break;
+     *   // Process chunk
+     * }
+     * ```
+     */
+    get(cid: string): Promise<ReadableStream<Uint8Array>>;
+    /**
+     * Retrieve content from IPFS by CID and return the full Response object
+     * Useful when you need access to response headers (e.g., content-length)
+     *
+     * @param cid - Content ID to retrieve
+     * @returns Response object with body stream and headers
+     *
+     * @example
+     * ```ts
+     * const response = await client.storage.getBinary(cid);
+     * const contentLength = response.headers.get('content-length');
+     * const reader = response.body.getReader();
+     * // ... read stream
+     * ```
+     */
+    getBinary(cid: string): Promise<Response>;
+    /**
+     * Unpin a CID
+     *
+     * @param cid - Content ID to unpin
+     */
+    unpin(cid: string): Promise<void>;
 }
 
 declare class SDKError extends Error {
@@ -361,7 +722,9 @@ interface Client {
     db: DBClient;
     pubsub: PubSubClient;
     network: NetworkClient;
+    cache: CacheClient;
+    storage: StorageClient;
 }
 declare function createClient(config: ClientConfig): Client;
 
-export { AuthClient, type AuthConfig, 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, PubSubClient, QueryBuilder, type QueryResponse, Repository, SDKError, type SelectOptions, type StorageAdapter, 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, 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 };