@debros/network-ts-sdk 0.2.5 → 0.3.2

package/src/core/http.ts

@@ -28,14 +28,6 @@ export class HttpClient {
   setApiKey(apiKey?: string) {
     this.apiKey = apiKey;
     // Don't clear JWT - allow both to coexist
-    if (typeof console !== "undefined") {
-      console.log(
-        "[HttpClient] API key set:",
-        !!apiKey,
-        "JWT still present:",
-        !!this.jwt
-      );
-    }
   }
 
   setJwt(jwt?: string) {
@@ -54,22 +46,39 @@ export class HttpClient {
   private getAuthHeaders(path: string): Record<string, string> {
     const headers: Record<string, string> = {};
 
-    // For database, pubsub, and proxy operations, ONLY use API key to avoid JWT user context
+    // 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) {
-      // For database/pubsub/proxy operations: use only API key (preferred for namespace operations)
+    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 auth/other operations: send both JWT and API key
+      // For other operations: send both JWT and API key
       if (this.jwt) {
         headers["Authorization"] = `Bearer ${this.jwt}`;
       }
@@ -98,6 +107,7 @@ export class HttpClient {
       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]) => {
@@ -111,27 +121,6 @@ export class HttpClient {
       ...options.headers,
     };
 
-    // Debug: Log headers being sent
-    if (
-      typeof console !== "undefined" &&
-      (path.includes("/db/") ||
-        path.includes("/query") ||
-        path.includes("/auth/") ||
-        path.includes("/pubsub/") ||
-        path.includes("/proxy/"))
-    ) {
-      console.log("[HttpClient] Request headers for", path, {
-        hasAuth: !!headers["Authorization"],
-        hasApiKey: !!headers["X-API-Key"],
-        authPrefix: headers["Authorization"]
-          ? headers["Authorization"].substring(0, 20)
-          : "none",
-        apiKeyPrefix: headers["X-API-Key"]
-          ? headers["X-API-Key"].substring(0, 20)
-          : "none",
-      });
-    }
-
     const controller = new AbortController();
     const requestTimeout = options.timeout ?? this.timeout; // Use override or default
     const timeoutId = setTimeout(() => controller.abort(), requestTimeout);
@@ -146,8 +135,99 @@ export class HttpClient {
       fetchOptions.body = JSON.stringify(options.body);
     }
 
+    // Extract and log SQL query details for rqlite operations
+    const isRqliteOperation = path.includes("/v1/rqlite/");
+    let queryDetails: string | null = null;
+    if (isRqliteOperation && options.body) {
+      try {
+        const body =
+          typeof options.body === "string"
+            ? JSON.parse(options.body)
+            : options.body;
+
+        if (body.sql) {
+          // Direct SQL query (query/exec endpoints)
+          queryDetails = `SQL: ${body.sql}`;
+          if (body.args && body.args.length > 0) {
+            queryDetails += ` | Args: [${body.args
+              .map((a: any) => (typeof a === "string" ? `"${a}"` : a))
+              .join(", ")}]`;
+          }
+        } else if (body.table) {
+          // Table-based query (find/find-one/select endpoints)
+          queryDetails = `Table: ${body.table}`;
+          if (body.criteria && Object.keys(body.criteria).length > 0) {
+            queryDetails += ` | Criteria: ${JSON.stringify(body.criteria)}`;
+          }
+          if (body.options) {
+            queryDetails += ` | Options: ${JSON.stringify(body.options)}`;
+          }
+          if (body.select) {
+            queryDetails += ` | Select: ${JSON.stringify(body.select)}`;
+          }
+          if (body.where) {
+            queryDetails += ` | Where: ${JSON.stringify(body.where)}`;
+          }
+          if (body.limit) {
+            queryDetails += ` | Limit: ${body.limit}`;
+          }
+          if (body.offset) {
+            queryDetails += ` | Offset: ${body.offset}`;
+          }
+        }
+      } catch (e) {
+        // Failed to parse body, ignore
+      }
+    }
+
     try {
-      return await this.requestWithRetry(url.toString(), fetchOptions);
+      const result = await this.requestWithRetry(
+        url.toString(),
+        fetchOptions,
+        0,
+        startTime
+      );
+      const duration = performance.now() - startTime;
+      if (typeof console !== "undefined") {
+        const logMessage = `[HttpClient] ${method} ${path} completed in ${duration.toFixed(
+          2
+        )}ms`;
+        if (queryDetails) {
+          console.log(logMessage);
+          console.log(`[HttpClient]   ${queryDetails}`);
+        } else {
+          console.log(logMessage);
+        }
+      }
+      return result;
+    } catch (error) {
+      const duration = performance.now() - startTime;
+      if (typeof console !== "undefined") {
+        // For 404 errors on find-one calls, log at warn level (not error) since "not found" is expected
+        // Application layer handles these cases in try-catch blocks
+        const is404FindOne =
+          path === "/v1/rqlite/find-one" &&
+          error instanceof SDKError &&
+          error.httpStatus === 404;
+
+        if (is404FindOne) {
+          // Log as warning for visibility, but not as error since it's expected behavior
+          console.warn(
+            `[HttpClient] ${method} ${path} returned 404 after ${duration.toFixed(
+              2
+            )}ms (expected for optional lookups)`
+          );
+        } else {
+          const errorMessage = `[HttpClient] ${method} ${path} failed after ${duration.toFixed(
+            2
+          )}ms:`;
+          console.error(errorMessage, error);
+          if (queryDetails) {
+            console.error(`[HttpClient]   ${queryDetails}`);
+          }
+        }
+      }
+      throw error;
     } finally {
       clearTimeout(timeoutId);
     }
@@ -156,7 +236,8 @@ export class HttpClient {
   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);
@@ -185,7 +266,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;
     }
@@ -221,6 +302,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();
   }

package/src/db/repository.ts

@@ -98,7 +98,9 @@ export class Repository<T extends Record<string, any>> {
   private buildInsertSql(entity: T): string {
     const columns = Object.keys(entity).filter((k) => entity[k] !== undefined);
     const placeholders = columns.map(() => "?").join(", ");
-    return `INSERT INTO ${this.tableName} (${columns.join(", ")}) VALUES (${placeholders})`;
+    return `INSERT INTO ${this.tableName} (${columns.join(
+      ", "
+    )}) VALUES (${placeholders})`;
   }
 
   private buildInsertArgs(entity: T): any[] {
@@ -111,7 +113,9 @@ export class Repository<T extends Record<string, any>> {
     const columns = Object.keys(entity)
       .filter((k) => entity[k] !== undefined && k !== this.primaryKey)
       .map((k) => `${k} = ?`);
-    return `UPDATE ${this.tableName} SET ${columns.join(", ")} WHERE ${this.primaryKey} = ?`;
+    return `UPDATE ${this.tableName} SET ${columns.join(", ")} WHERE ${
+      this.primaryKey
+    } = ?`;
   }
 
   private buildUpdateArgs(entity: T): any[] {

package/src/index.ts

@@ -3,6 +3,8 @@ import { AuthClient } from "./auth/client";
 import { DBClient } from "./db/client";
 import { PubSubClient } from "./pubsub/client";
 import { NetworkClient } from "./network/client";
+import { CacheClient } from "./cache/client";
+import { StorageClient } from "./storage/client";
 import { WSClientConfig } from "./core/ws";
 import {
   StorageAdapter,
@@ -23,6 +25,8 @@ export interface Client {
   db: DBClient;
   pubsub: PubSubClient;
   network: NetworkClient;
+  cache: CacheClient;
+  storage: StorageClient;
 }
 
 export function createClient(config: ClientConfig): Client {
@@ -52,16 +56,19 @@ export function createClient(config: ClientConfig): Client {
     wsURL,
   });
   const network = new NetworkClient(httpClient);
+  const cache = new CacheClient(httpClient);
+  const storage = new StorageClient(httpClient);
 
   return {
     auth,
     db,
     pubsub,
     network,
+    cache,
+    storage,
   };
 }
 
-// Re-exports
 export { HttpClient } from "./core/http";
 export { WSClient } from "./core/ws";
 export { AuthClient } from "./auth/client";
@@ -70,6 +77,8 @@ export { QueryBuilder } from "./db/qb";
 export { Repository } from "./db/repository";
 export { PubSubClient, Subscription } from "./pubsub/client";
 export { NetworkClient } from "./network/client";
+export { CacheClient } from "./cache/client";
+export { StorageClient } from "./storage/client";
 export { SDKError } from "./errors";
 export { MemoryStorage, LocalStorageAdapter } from "./auth/types";
 export type { StorageAdapter, AuthConfig, WhoAmI } from "./auth/types";
@@ -86,3 +95,22 @@ export type {
   ProxyRequest,
   ProxyResponse,
 } from "./network/client";
+export type {
+  CacheGetRequest,
+  CacheGetResponse,
+  CachePutRequest,
+  CachePutResponse,
+  CacheDeleteRequest,
+  CacheDeleteResponse,
+  CacheMultiGetRequest,
+  CacheMultiGetResponse,
+  CacheScanRequest,
+  CacheScanResponse,
+  CacheHealthResponse,
+} from "./cache/client";
+export type {
+  StorageUploadResponse,
+  StoragePinRequest,
+  StoragePinResponse,
+  StorageStatus,
+} from "./storage/client";

package/src/storage/client.ts

@@ -0,0 +1,270 @@
+import { HttpClient } from "../core/http";
+
+export interface StorageUploadResponse {
+  cid: string;
+  name: string;
+  size: number;
+}
+
+export interface StoragePinRequest {
+  cid: string;
+  name?: string;
+}
+
+export interface StoragePinResponse {
+  cid: string;
+  name: string;
+}
+
+export interface StorageStatus {
+  cid: string;
+  name: string;
+  status: string; // "pinned", "pinning", "queued", "unpinned", "error"
+  replication_min: number;
+  replication_max: number;
+  replication_factor: number;
+  peers: string[];
+  error?: string;
+}
+
+export class StorageClient {
+  private httpClient: HttpClient;
+
+  constructor(httpClient: HttpClient) {
+    this.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 });
+   * ```
+   */
+  async upload(
+    file: File | Blob | ArrayBuffer | Uint8Array | ReadableStream<Uint8Array>,
+    name?: string,
+    options?: {
+      pin?: boolean;
+    }
+  ): Promise<StorageUploadResponse> {
+    // Create FormData for multipart upload
+    const formData = new FormData();
+
+    // Handle different input types
+    if (file instanceof File) {
+      formData.append("file", file);
+    } else if (file instanceof Blob) {
+      formData.append("file", file, name);
+    } else if (file instanceof ArrayBuffer) {
+      const blob = new Blob([file]);
+      formData.append("file", blob, name);
+    } else if (file instanceof Uint8Array) {
+      // Convert Uint8Array to ArrayBuffer for Blob constructor
+      const buffer = file.buffer.slice(
+        file.byteOffset,
+        file.byteOffset + file.byteLength
+      ) as ArrayBuffer;
+      const blob = new Blob([buffer], { type: "application/octet-stream" });
+      formData.append("file", blob, name);
+    } else if (file instanceof ReadableStream) {
+      // For ReadableStream, we need to read it into a blob first
+      // This is a limitation - in practice, pass File/Blob/Buffer
+      const chunks: ArrayBuffer[] = [];
+      const reader = file.getReader();
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        const buffer = value.buffer.slice(
+          value.byteOffset,
+          value.byteOffset + value.byteLength
+        ) as ArrayBuffer;
+        chunks.push(buffer);
+      }
+      const blob = new Blob(chunks);
+      formData.append("file", blob, name);
+    } else {
+      throw new Error(
+        "Unsupported file type. Use File, Blob, ArrayBuffer, Uint8Array, or ReadableStream."
+      );
+    }
+
+    // Add pin flag (default: true)
+    const shouldPin = options?.pin !== false; // Default to true
+    formData.append("pin", shouldPin ? "true" : "false");
+
+    return this.httpClient.uploadFile<StorageUploadResponse>(
+      "/v1/storage/upload",
+      formData,
+      { timeout: 300000 } // 5 minute timeout for large files
+    );
+  }
+
+  /**
+   * Pin an existing CID
+   *
+   * @param cid - Content ID to pin
+   * @param name - Optional name for the pin
+   * @returns Pin result
+   */
+  async pin(cid: string, name?: string): Promise<StoragePinResponse> {
+    return this.httpClient.post<StoragePinResponse>("/v1/storage/pin", {
+      cid,
+      name,
+    });
+  }
+
+  /**
+   * Get the pin status for a CID
+   *
+   * @param cid - Content ID to check
+   * @returns Pin status information
+   */
+  async status(cid: string): Promise<StorageStatus> {
+    return this.httpClient.get<StorageStatus>(`/v1/storage/status/${cid}`);
+  }
+
+  /**
+   * 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
+   * }
+   * ```
+   */
+  async get(cid: string): Promise<ReadableStream<Uint8Array>> {
+    // Retry logic for content retrieval - content may not be immediately available
+    // after upload due to eventual consistency in IPFS Cluster
+    // IPFS Cluster pins can take 2-3+ seconds to complete across all nodes
+    const maxAttempts = 8;
+    let lastError: Error | null = null;
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        const response = await this.httpClient.getBinary(
+          `/v1/storage/get/${cid}`
+        );
+
+        if (!response.body) {
+          throw new Error("Response body is null");
+        }
+
+        return response.body;
+      } catch (error: any) {
+        lastError = error;
+
+        // Check if this is a 404 error (content not found)
+        const isNotFound =
+          error?.httpStatus === 404 ||
+          error?.message?.includes("not found") ||
+          error?.message?.includes("404");
+
+        // If it's not a 404 error, or this is the last attempt, give up
+        if (!isNotFound || attempt === maxAttempts) {
+          throw error;
+        }
+
+        // Wait before retrying (exponential backoff: 400ms, 800ms, 1200ms, etc.)
+        // This gives up to ~12 seconds total wait time, covering typical pin completion
+        const backoffMs = attempt * 2500;
+        await new Promise((resolve) => setTimeout(resolve, backoffMs));
+      }
+    }
+
+    // This should never be reached, but TypeScript needs it
+    throw lastError || new Error("Failed to retrieve content");
+  }
+
+  /**
+   * 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
+   * ```
+   */
+  async getBinary(cid: string): Promise<Response> {
+    // Retry logic for content retrieval - content may not be immediately available
+    // after upload due to eventual consistency in IPFS Cluster
+    // IPFS Cluster pins can take 2-3+ seconds to complete across all nodes
+    const maxAttempts = 8;
+    let lastError: Error | null = null;
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        const response = await this.httpClient.getBinary(
+          `/v1/storage/get/${cid}`
+        );
+
+        if (!response) {
+          throw new Error("Response is null");
+        }
+
+        return response;
+      } catch (error: any) {
+        lastError = error;
+
+        // Check if this is a 404 error (content not found)
+        const isNotFound =
+          error?.httpStatus === 404 ||
+          error?.message?.includes("not found") ||
+          error?.message?.includes("404");
+
+        // If it's not a 404 error, or this is the last attempt, give up
+        if (!isNotFound || attempt === maxAttempts) {
+          throw error;
+        }
+
+        // Wait before retrying (exponential backoff: 400ms, 800ms, 1200ms, etc.)
+        // This gives up to ~12 seconds total wait time, covering typical pin completion
+        const backoffMs = attempt * 2500;
+        await new Promise((resolve) => setTimeout(resolve, backoffMs));
+      }
+    }
+
+    // This should never be reached, but TypeScript needs it
+    throw lastError || new Error("Failed to retrieve content");
+  }
+
+  /**
+   * Unpin a CID
+   *
+   * @param cid - Content ID to unpin
+   */
+  async unpin(cid: string): Promise<void> {
+    await this.httpClient.delete(`/v1/storage/unpin/${cid}`);
+  }
+}