@debros/network-ts-sdk 0.1.4 → 0.2.5

package/README.md

@@ -1,4 +1,4 @@
-# @network/sdk - TypeScript SDK for DeBros Network
+# @debros/network-ts-sdk - TypeScript SDK for DeBros Network
 
 A modern, isomorphic TypeScript SDK for the DeBros Network gateway. Works seamlessly in both Node.js and browser environments with support for database operations, pub/sub messaging, and network management.
 
@@ -14,7 +14,7 @@ A modern, isomorphic TypeScript SDK for the DeBros Network gateway. Works seamle
 ## Installation
 
 ```bash
-npm install @network/network-ts-sdk
+npm install @debros/network-ts-sdk
 ```
 
 ## Quick Start
@@ -22,7 +22,7 @@ npm install @network/network-ts-sdk
 ### Initialize the Client
 
 ```typescript
-import { createClient } from "@network/sdk";
+import { createClient } from "@debros/network-ts-sdk";
 
 const client = createClient({
   baseURL: "http://localhost:6001",
@@ -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
@@ -234,7 +329,7 @@ interface ClientConfig {
 By default, credentials are stored in memory. For browser apps, use localStorage:
 
 ```typescript
-import { createClient, LocalStorageAdapter } from "@network/sdk";
+import { createClient, LocalStorageAdapter } from "@debros/network-ts-sdk";
 
 const client = createClient({
   baseURL: "http://localhost:6001",
@@ -248,7 +343,7 @@ const client = createClient({
 The SDK throws `SDKError` for all errors:
 
 ```typescript
-import { SDKError } from "@network/sdk";
+import { SDKError } from "@debros/network-ts-sdk";
 
 try {
   await client.db.query("SELECT * FROM nonexistent");
@@ -268,7 +363,7 @@ The SDK works in browsers with minimal setup:
 
 ```typescript
 // Browser example
-import { createClient } from "@network/sdk";
+import { createClient } from "@debros/network-ts-sdk";
 
 const client = createClient({
   baseURL: "https://gateway.example.com",

package/dist/index.d.ts

@@ -20,10 +20,12 @@ 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>;
@@ -76,8 +78,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 +270,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 +381,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 +423,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 +464,29 @@ 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>;
 }
 
 declare class SDKError extends Error {
@@ -364,4 +519,4 @@ interface Client {
 }
 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, 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, Subscription, type TransactionOp, type TransactionRequest, WSClient, type WhoAmI, createClient, extractPrimaryKey, extractTableName };