@debros/network-ts-sdk 0.1.5 → 0.3.1

package/src/cache/client.ts

@@ -0,0 +1,203 @@
+import { HttpClient } from "../core/http";
+import { SDKError } from "../errors";
+
+export interface CacheGetRequest {
+  dmap: string;
+  key: string;
+}
+
+export interface CacheGetResponse {
+  key: string;
+  value: any;
+  dmap: string;
+}
+
+export interface CachePutRequest {
+  dmap: string;
+  key: string;
+  value: any;
+  ttl?: string; // Duration string like "1h", "30m"
+}
+
+export interface CachePutResponse {
+  status: string;
+  key: string;
+  dmap: string;
+}
+
+export interface CacheDeleteRequest {
+  dmap: string;
+  key: string;
+}
+
+export interface CacheDeleteResponse {
+  status: string;
+  key: string;
+  dmap: string;
+}
+
+export interface CacheMultiGetRequest {
+  dmap: string;
+  keys: string[];
+}
+
+export interface CacheMultiGetResponse {
+  results: Array<{
+    key: string;
+    value: any;
+  }>;
+  dmap: string;
+}
+
+export interface CacheScanRequest {
+  dmap: string;
+  match?: string; // Optional regex pattern
+}
+
+export interface CacheScanResponse {
+  keys: string[];
+  count: number;
+  dmap: string;
+}
+
+export interface CacheHealthResponse {
+  status: string;
+  service: string;
+}
+
+export class CacheClient {
+  private httpClient: HttpClient;
+
+  constructor(httpClient: HttpClient) {
+    this.httpClient = httpClient;
+  }
+
+  /**
+   * Check cache service health
+   */
+  async health(): Promise<CacheHealthResponse> {
+    return this.httpClient.get("/v1/cache/health");
+  }
+
+  /**
+   * Get a value from cache
+   * Returns null if the key is not found (cache miss/expired), which is normal behavior
+   */
+  async get(dmap: string, key: string): Promise<CacheGetResponse | null> {
+    try {
+      return await this.httpClient.post<CacheGetResponse>("/v1/cache/get", {
+        dmap,
+        key,
+      });
+    } catch (error) {
+      // Cache misses (404 or "key not found" messages) are normal behavior - return null instead of throwing
+      if (
+        error instanceof SDKError &&
+        (error.httpStatus === 404 ||
+          (error.httpStatus === 500 &&
+            error.message?.toLowerCase().includes("key not found")))
+      ) {
+        return null;
+      }
+      // Re-throw other errors (network issues, server errors, etc.)
+      throw error;
+    }
+  }
+
+  /**
+   * Put a value into cache
+   */
+  async put(
+    dmap: string,
+    key: string,
+    value: any,
+    ttl?: string
+  ): Promise<CachePutResponse> {
+    return this.httpClient.post<CachePutResponse>("/v1/cache/put", {
+      dmap,
+      key,
+      value,
+      ttl,
+    });
+  }
+
+  /**
+   * Delete a value from cache
+   */
+  async delete(dmap: string, key: string): Promise<CacheDeleteResponse> {
+    return this.httpClient.post<CacheDeleteResponse>("/v1/cache/delete", {
+      dmap,
+      key,
+    });
+  }
+
+  /**
+   * 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
+   */
+  async multiGet(
+    dmap: string,
+    keys: string[]
+  ): Promise<Map<string, any | null>> {
+    try {
+      if (keys.length === 0) {
+        return new Map();
+      }
+
+      const response = await this.httpClient.post<CacheMultiGetResponse>(
+        "/v1/cache/mget",
+        {
+          dmap,
+          keys,
+        }
+      );
+
+      // Convert array to Map
+      const resultMap = new Map<string, any | null>();
+
+      // First, mark all keys as null (cache miss)
+      keys.forEach((key) => {
+        resultMap.set(key, null);
+      });
+
+      // Then, update with found values
+      if (response.results) {
+        response.results.forEach(({ key, value }) => {
+          resultMap.set(key, value);
+        });
+      }
+
+      return resultMap;
+    } catch (error) {
+      // Handle 404 errors silently (endpoint not implemented on backend)
+      // This is expected behavior when the backend doesn't support multiGet yet
+      if (error instanceof SDKError && error.httpStatus === 404) {
+        // Return map with all nulls silently - caller can fall back to individual gets
+        const resultMap = new Map<string, any | null>();
+        keys.forEach((key) => {
+          resultMap.set(key, null);
+        });
+        return resultMap;
+      }
+
+      // Log and return empty results for other errors
+      const resultMap = new Map<string, any | null>();
+      keys.forEach((key) => {
+        resultMap.set(key, null);
+      });
+      console.error(`[CacheClient] Error in multiGet for ${dmap}:`, error);
+      return resultMap;
+    }
+  }
+
+  /**
+   * Scan keys in a distributed map, optionally matching a regex pattern
+   */
+  async scan(dmap: string, match?: string): Promise<CacheScanResponse> {
+    return this.httpClient.post<CacheScanResponse>("/v1/cache/scan", {
+      dmap,
+      match,
+    });
+  }
+}

package/src/core/http.ts

@@ -19,7 +19,7 @@ export class HttpClient {
 
   constructor(config: HttpClientConfig) {
     this.baseURL = config.baseURL.replace(/\/$/, "");
-    this.timeout = config.timeout ?? 30000;
+    this.timeout = config.timeout ?? 60000; // Increased from 30s to 60s for pub/sub operations
     this.maxRetries = config.maxRetries ?? 3;
     this.retryDelayMs = config.retryDelayMs ?? 1000;
     this.fetch = config.fetch ?? globalThis.fetch;
@@ -27,20 +27,64 @@ export class HttpClient {
 
   setApiKey(apiKey?: string) {
     this.apiKey = apiKey;
-    this.jwt = undefined;
+    // Don't clear JWT - allow both to coexist
   }
 
   setJwt(jwt?: string) {
     this.jwt = jwt;
-    this.apiKey = undefined;
+    // Don't clear API key - allow both to coexist
+    if (typeof console !== "undefined") {
+      console.log(
+        "[HttpClient] JWT set:",
+        !!jwt,
+        "API key still present:",
+        !!this.apiKey
+      );
+    }
   }
 
-  private getAuthHeaders(): Record<string, string> {
+  private getAuthHeaders(path: string): Record<string, string> {
     const headers: Record<string, string> = {};
-    if (this.jwt) {
-      headers["Authorization"] = `Bearer ${this.jwt}`;
-    } else if (this.apiKey) {
-      headers["X-API-Key"] = this.apiKey;
+
+    // For database, pubsub, proxy, and cache operations, ONLY use API key to avoid JWT user context
+    // interfering with namespace-level authorization
+    const isDbOperation = path.includes("/v1/rqlite/");
+    const isPubSubOperation = path.includes("/v1/pubsub/");
+    const isProxyOperation = path.includes("/v1/proxy/");
+    const isCacheOperation = path.includes("/v1/cache/");
+
+    // For auth operations, prefer API key over JWT to ensure proper authentication
+    const isAuthOperation = path.includes("/v1/auth/");
+
+    if (
+      isDbOperation ||
+      isPubSubOperation ||
+      isProxyOperation ||
+      isCacheOperation
+    ) {
+      // For database/pubsub/proxy/cache operations: use only API key (preferred for namespace operations)
+      if (this.apiKey) {
+        headers["X-API-Key"] = this.apiKey;
+      } else if (this.jwt) {
+        // Fallback to JWT if no API key
+        headers["Authorization"] = `Bearer ${this.jwt}`;
+      }
+    } else if (isAuthOperation) {
+      // For auth operations: prefer API key over JWT (auth endpoints should use explicit API key)
+      if (this.apiKey) {
+        headers["X-API-Key"] = this.apiKey;
+      }
+      if (this.jwt) {
+        headers["Authorization"] = `Bearer ${this.jwt}`;
+      }
+    } else {
+      // For other operations: send both JWT and API key
+      if (this.jwt) {
+        headers["Authorization"] = `Bearer ${this.jwt}`;
+      }
+      if (this.apiKey) {
+        headers["X-API-Key"] = this.apiKey;
+      }
     }
     return headers;
   }
@@ -49,6 +93,10 @@ export class HttpClient {
     return this.jwt || this.apiKey;
   }
 
+  getApiKey(): string | undefined {
+    return this.apiKey;
+  }
+
   async request<T = any>(
     method: "GET" | "POST" | "PUT" | "DELETE",
     path: string,
@@ -56,8 +104,10 @@ export class HttpClient {
       body?: any;
       headers?: Record<string, string>;
       query?: Record<string, string | number | boolean>;
+      timeout?: number; // Per-request timeout override
     } = {}
   ): Promise<T> {
+    const startTime = performance.now(); // Track request start time
     const url = new URL(this.baseURL + path);
     if (options.query) {
       Object.entries(options.query).forEach(([key, value]) => {
@@ -67,27 +117,114 @@ export class HttpClient {
 
     const headers: Record<string, string> = {
       "Content-Type": "application/json",
-      ...this.getAuthHeaders(),
+      ...this.getAuthHeaders(path),
       ...options.headers,
     };
 
+    const controller = new AbortController();
+    const requestTimeout = options.timeout ?? this.timeout; // Use override or default
+    const timeoutId = setTimeout(() => controller.abort(), requestTimeout);
+
     const fetchOptions: RequestInit = {
       method,
       headers,
-      signal: AbortSignal.timeout(this.timeout),
+      signal: controller.signal,
     };
 
     if (options.body !== undefined) {
       fetchOptions.body = JSON.stringify(options.body);
     }
 
-    return this.requestWithRetry(url.toString(), fetchOptions);
+    try {
+      const result = await this.requestWithRetry(
+        url.toString(),
+        fetchOptions,
+        0,
+        startTime
+      );
+      const duration = performance.now() - startTime;
+      if (typeof console !== "undefined") {
+        console.log(
+          `[HttpClient] ${method} ${path} completed in ${duration.toFixed(2)}ms`
+        );
+      }
+      return result;
+    } catch (error) {
+      const duration = performance.now() - startTime;
+      if (typeof console !== "undefined") {
+        // Cache "key not found" (404 or error message) is expected behavior - don't log as error
+        const isCacheGetNotFound =
+          path === "/v1/cache/get" &&
+          error instanceof SDKError &&
+          (error.httpStatus === 404 ||
+            (error.httpStatus === 500 &&
+              error.message?.toLowerCase().includes("key not found")));
+
+        // "Not found" (404) for blocked_users is expected behavior - don't log as error
+        // This happens when checking if users are blocked (most users aren't blocked)
+        const isBlockedUsersNotFound =
+          path === "/v1/rqlite/find-one" &&
+          error instanceof SDKError &&
+          error.httpStatus === 404 &&
+          options.body &&
+          (() => {
+            try {
+              const body =
+                typeof options.body === "string"
+                  ? JSON.parse(options.body)
+                  : options.body;
+              return body.table === "blocked_users";
+            } catch {
+              return false;
+            }
+          })();
+
+        // "Not found" (404) for conversation_participants is expected behavior - don't log as error
+        // This happens when checking if a user is a participant (e.g., on first group join)
+        const isConversationParticipantNotFound =
+          path === "/v1/rqlite/find-one" &&
+          error instanceof SDKError &&
+          error.httpStatus === 404 &&
+          options.body &&
+          (() => {
+            try {
+              const body =
+                typeof options.body === "string"
+                  ? JSON.parse(options.body)
+                  : options.body;
+              return body.table === "conversation_participants";
+            } catch {
+              return false;
+            }
+          })();
+
+        if (
+          isCacheGetNotFound ||
+          isBlockedUsersNotFound ||
+          isConversationParticipantNotFound
+        ) {
+          // Log cache miss, non-blocked status, or non-participant status as debug/info, not error
+          // These are expected behaviors
+        } else {
+          console.error(
+            `[HttpClient] ${method} ${path} failed after ${duration.toFixed(
+              2
+            )}ms:`,
+            error
+          );
+        }
+      }
+      throw error;
+    } finally {
+      clearTimeout(timeoutId);
+    }
   }
 
   private async requestWithRetry(
     url: string,
     options: RequestInit,
-    attempt: number = 0
+    attempt: number = 0,
+    startTime?: number // Track start time for timing across retries
   ): Promise<any> {
     try {
       const response = await this.fetch(url, options);
@@ -116,7 +253,7 @@ export class HttpClient {
         await new Promise((resolve) =>
           setTimeout(resolve, this.retryDelayMs * (attempt + 1))
         );
-        return this.requestWithRetry(url, options, attempt + 1);
+        return this.requestWithRetry(url, options, attempt + 1, startTime);
       }
       throw error;
     }
@@ -152,6 +289,104 @@ export class HttpClient {
     return this.request<T>("DELETE", path, options);
   }
 
+  /**
+   * Upload a file using multipart/form-data
+   * This is a special method for file uploads that bypasses JSON serialization
+   */
+  async uploadFile<T = any>(
+    path: string,
+    formData: FormData,
+    options?: {
+      timeout?: number;
+    }
+  ): Promise<T> {
+    const startTime = performance.now(); // Track upload start time
+    const url = new URL(this.baseURL + path);
+    const headers: Record<string, string> = {
+      ...this.getAuthHeaders(path),
+      // Don't set Content-Type - browser will set it with boundary
+    };
+
+    const controller = new AbortController();
+    const requestTimeout = options?.timeout ?? this.timeout * 5; // 5x timeout for uploads
+    const timeoutId = setTimeout(() => controller.abort(), requestTimeout);
+
+    const fetchOptions: RequestInit = {
+      method: "POST",
+      headers,
+      body: formData,
+      signal: controller.signal,
+    };
+
+    try {
+      const result = await this.requestWithRetry(
+        url.toString(),
+        fetchOptions,
+        0,
+        startTime
+      );
+      const duration = performance.now() - startTime;
+      if (typeof console !== "undefined") {
+        console.log(
+          `[HttpClient] POST ${path} (upload) completed in ${duration.toFixed(
+            2
+          )}ms`
+        );
+      }
+      return result;
+    } catch (error) {
+      const duration = performance.now() - startTime;
+      if (typeof console !== "undefined") {
+        console.error(
+          `[HttpClient] POST ${path} (upload) failed after ${duration.toFixed(
+            2
+          )}ms:`,
+          error
+        );
+      }
+      throw error;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  /**
+   * Get a binary response (returns Response object for streaming)
+   */
+  async getBinary(path: string): Promise<Response> {
+    const url = new URL(this.baseURL + path);
+    const headers: Record<string, string> = {
+      ...this.getAuthHeaders(path),
+    };
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout * 5); // 5x timeout for downloads
+
+    const fetchOptions: RequestInit = {
+      method: "GET",
+      headers,
+      signal: controller.signal,
+    };
+
+    try {
+      const response = await this.fetch(url.toString(), fetchOptions);
+      if (!response.ok) {
+        clearTimeout(timeoutId);
+        const error = await response.json().catch(() => ({
+          error: response.statusText,
+        }));
+        throw SDKError.fromResponse(response.status, error);
+      }
+      return response;
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof SDKError) {
+        throw error;
+      }
+      throw error;
+    }
+  }
+
   getToken(): string | undefined {
     return this.getAuthToken();
   }