@debros/network-ts-sdk 0.4.3 → 0.6.0

package/package.json

@@ -1,15 +1,36 @@
 {
   "name": "@debros/network-ts-sdk",
-  "version": "0.4.3",
-  "description": "TypeScript SDK for DeBros Network Gateway",
+  "version": "0.6.0",
+  "description": "TypeScript SDK for DeBros Network Gateway - Database, PubSub, Cache, Storage, and more",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "license": "MIT",
   "author": "DeBrosOfficial",
+  "keywords": [
+    "debros",
+    "network",
+    "sdk",
+    "typescript",
+    "database",
+    "rqlite",
+    "pubsub",
+    "websocket",
+    "cache",
+    "olric",
+    "ipfs",
+    "storage",
+    "wasm",
+    "serverless",
+    "distributed",
+    "gateway"
+  ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/DeBrosOfficial/network-ts-sdk/tree/v0.0.1"
+    "url": "https://github.com/DeBrosOfficial/network-ts-sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/DeBrosOfficial/network-ts-sdk/issues"
   },
   "exports": {
     ".": {
@@ -38,9 +59,11 @@
     "@types/node": "^20.0.0",
     "@typescript-eslint/eslint-plugin": "^6.0.0",
     "@typescript-eslint/parser": "^6.0.0",
+    "@vitest/coverage-v8": "^1.0.0",
     "dotenv": "^17.2.3",
     "eslint": "^8.0.0",
     "tsup": "^8.0.0",
+    "typedoc": "^0.25.0",
     "typescript": "^5.3.0",
     "vitest": "^1.0.0"
   },

package/src/auth/index.ts

@@ -0,0 +1,3 @@
+export { AuthClient } from "./client";
+export type { AuthConfig, WhoAmI, StorageAdapter } from "./types";
+export { MemoryStorage, LocalStorageAdapter } from "./types";

package/src/cache/index.ts

@@ -0,0 +1,14 @@
+export { CacheClient } from "./client";
+export type {
+  CacheGetRequest,
+  CacheGetResponse,
+  CachePutRequest,
+  CachePutResponse,
+  CacheDeleteRequest,
+  CacheDeleteResponse,
+  CacheMultiGetRequest,
+  CacheMultiGetResponse,
+  CacheScanRequest,
+  CacheScanResponse,
+  CacheHealthResponse,
+} from "./client";

package/src/core/http.ts

@@ -25,6 +25,10 @@ export interface HttpClientConfig {
   maxRetries?: number;
   retryDelayMs?: number;
   fetch?: typeof fetch;
+  /**
+   * Enable debug logging (includes full SQL queries and args). Default: false
+   */
+  debug?: boolean;
   /**
    * Callback invoked on network errors (after all retries exhausted).
    * Use this to trigger gateway failover at the application layer.
@@ -63,6 +67,7 @@ export class HttpClient {
   private fetch: typeof fetch;
   private apiKey?: string;
   private jwt?: string;
+  private debug: boolean;
   private onNetworkError?: NetworkErrorCallback;
 
   constructor(config: HttpClientConfig) {
@@ -72,6 +77,7 @@ export class HttpClient {
     this.retryDelayMs = config.retryDelayMs ?? 1000;
     // Use provided fetch or create one with proper TLS configuration for staging certificates
     this.fetch = config.fetch ?? createFetchWithTLSConfig();
+    this.debug = config.debug ?? false;
     this.onNetworkError = config.onNetworkError;
   }
 
@@ -256,7 +262,7 @@ export class HttpClient {
         const logMessage = `[HttpClient] ${method} ${path} completed in ${duration.toFixed(
           2
         )}ms`;
-        if (queryDetails) {
+        if (queryDetails && this.debug) {
           console.log(logMessage);
           console.log(`[HttpClient]   ${queryDetails}`);
         } else {
@@ -286,7 +292,7 @@ export class HttpClient {
             2
           )}ms:`;
           console.error(errorMessage, error);
-          if (queryDetails) {
+          if (queryDetails && this.debug) {
             console.error(`[HttpClient]   ${queryDetails}`);
           }
         }

package/src/core/index.ts

@@ -0,0 +1,10 @@
+export { HttpClient, type HttpClientConfig, type NetworkErrorCallback, type NetworkErrorContext } from "./http";
+export { WSClient, type WSClientConfig } from "./ws";
+export type { IHttpTransport, RequestOptions } from "./interfaces/IHttpTransport";
+export type { IWebSocketClient } from "./interfaces/IWebSocketClient";
+export type { IAuthStrategy, RequestContext } from "./interfaces/IAuthStrategy";
+export type { IRetryPolicy } from "./interfaces/IRetryPolicy";
+export { PathBasedAuthStrategy } from "./transport/AuthHeaderStrategy";
+export { ExponentialBackoffRetryPolicy } from "./transport/RequestRetryPolicy";
+export { RequestLogger } from "./transport/RequestLogger";
+export { TLSConfiguration } from "./transport/TLSConfiguration";

package/src/core/interfaces/IAuthStrategy.ts

@@ -0,0 +1,28 @@
+/**
+ * Request context for authentication
+ */
+export interface RequestContext {
+  path: string;
+  method: string;
+}
+
+/**
+ * Authentication strategy interface
+ * Provides abstraction for different authentication header strategies
+ */
+export interface IAuthStrategy {
+  /**
+   * Get authentication headers for a request
+   */
+  getHeaders(context: RequestContext): Record<string, string>;
+
+  /**
+   * Set API key
+   */
+  setApiKey(apiKey?: string): void;
+
+  /**
+   * Set JWT token
+   */
+  setJwt(jwt?: string): void;
+}

package/src/core/interfaces/IHttpTransport.ts

@@ -0,0 +1,73 @@
+/**
+ * HTTP Request options
+ */
+export interface RequestOptions {
+  headers?: Record<string, string>;
+  query?: Record<string, string | number | boolean>;
+  timeout?: number;
+}
+
+/**
+ * HTTP Transport abstraction interface
+ * Provides a testable abstraction layer for HTTP operations
+ */
+export interface IHttpTransport {
+  /**
+   * Perform GET request
+   */
+  get<T = any>(path: string, options?: RequestOptions): Promise<T>;
+
+  /**
+   * Perform POST request
+   */
+  post<T = any>(path: string, body?: any, options?: RequestOptions): Promise<T>;
+
+  /**
+   * Perform PUT request
+   */
+  put<T = any>(path: string, body?: any, options?: RequestOptions): Promise<T>;
+
+  /**
+   * Perform DELETE request
+   */
+  delete<T = any>(path: string, options?: RequestOptions): Promise<T>;
+
+  /**
+   * Upload file using multipart/form-data
+   */
+  uploadFile<T = any>(
+    path: string,
+    formData: FormData,
+    options?: { timeout?: number }
+  ): Promise<T>;
+
+  /**
+   * Get binary response (returns Response object for streaming)
+   */
+  getBinary(path: string): Promise<Response>;
+
+  /**
+   * Get base URL
+   */
+  getBaseURL(): string;
+
+  /**
+   * Get API key
+   */
+  getApiKey(): string | undefined;
+
+  /**
+   * Get current token (JWT or API key)
+   */
+  getToken(): string | undefined;
+
+  /**
+   * Set API key for authentication
+   */
+  setApiKey(apiKey?: string): void;
+
+  /**
+   * Set JWT token for authentication
+   */
+  setJwt(jwt?: string): void;
+}

package/src/core/interfaces/IRetryPolicy.ts

@@ -0,0 +1,20 @@
+/**
+ * Retry policy interface
+ * Provides abstraction for retry logic and backoff strategies
+ */
+export interface IRetryPolicy {
+  /**
+   * Determine if request should be retried
+   */
+  shouldRetry(error: any, attempt: number): boolean;
+
+  /**
+   * Get delay before next retry attempt (in milliseconds)
+   */
+  getDelay(attempt: number): number;
+
+  /**
+   * Get maximum number of retry attempts
+   */
+  getMaxRetries(): number;
+}

package/src/core/interfaces/IWebSocketClient.ts

@@ -0,0 +1,60 @@
+/**
+ * WebSocket Client abstraction interface
+ * Provides a testable abstraction layer for WebSocket operations
+ */
+export interface IWebSocketClient {
+  /**
+   * Connect to WebSocket server
+   */
+  connect(): Promise<void>;
+
+  /**
+   * Close WebSocket connection
+   */
+  close(): void;
+
+  /**
+   * Send data through WebSocket
+   */
+  send(data: string): void;
+
+  /**
+   * Register message handler
+   */
+  onMessage(handler: (data: string) => void): void;
+
+  /**
+   * Unregister message handler
+   */
+  offMessage(handler: (data: string) => void): void;
+
+  /**
+   * Register error handler
+   */
+  onError(handler: (error: Error) => void): void;
+
+  /**
+   * Unregister error handler
+   */
+  offError(handler: (error: Error) => void): void;
+
+  /**
+   * Register close handler
+   */
+  onClose(handler: () => void): void;
+
+  /**
+   * Unregister close handler
+   */
+  offClose(handler: () => void): void;
+
+  /**
+   * Check if WebSocket is connected
+   */
+  isConnected(): boolean;
+
+  /**
+   * Get WebSocket URL
+   */
+  get url(): string;
+}

package/src/core/interfaces/index.ts

@@ -0,0 +1,4 @@
+export type { IHttpTransport, RequestOptions } from "./IHttpTransport";
+export type { IWebSocketClient } from "./IWebSocketClient";
+export type { IAuthStrategy, RequestContext } from "./IAuthStrategy";
+export type { IRetryPolicy } from "./IRetryPolicy";

package/src/core/transport/AuthHeaderStrategy.ts

@@ -0,0 +1,108 @@
+import type { IAuthStrategy, RequestContext } from "../interfaces/IAuthStrategy";
+
+/**
+ * Authentication type for different operations
+ */
+type AuthType = "api-key-only" | "api-key-preferred" | "jwt-preferred" | "both";
+
+/**
+ * Path-based authentication strategy
+ * Determines which auth credentials to use based on the request path
+ */
+export class PathBasedAuthStrategy implements IAuthStrategy {
+  private apiKey?: string;
+  private jwt?: string;
+
+  /**
+   * Mapping of path patterns to auth types
+   */
+  private readonly authRules: Array<{ pattern: string; type: AuthType }> = [
+    // Database, PubSub, Proxy, Cache: prefer API key
+    { pattern: "/v1/rqlite/", type: "api-key-only" },
+    { pattern: "/v1/pubsub/", type: "api-key-only" },
+    { pattern: "/v1/proxy/", type: "api-key-only" },
+    { pattern: "/v1/cache/", type: "api-key-only" },
+    // Auth operations: prefer API key
+    { pattern: "/v1/auth/", type: "api-key-preferred" },
+  ];
+
+  constructor(apiKey?: string, jwt?: string) {
+    this.apiKey = apiKey;
+    this.jwt = jwt;
+  }
+
+  /**
+   * Get authentication headers for a request
+   */
+  getHeaders(context: RequestContext): Record<string, string> {
+    const headers: Record<string, string> = {};
+    const authType = this.detectAuthType(context.path);
+
+    switch (authType) {
+      case "api-key-only":
+        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}`;
+        }
+        break;
+
+      case "api-key-preferred":
+        if (this.apiKey) {
+          headers["X-API-Key"] = this.apiKey;
+        }
+        if (this.jwt) {
+          headers["Authorization"] = `Bearer ${this.jwt}`;
+        }
+        break;
+
+      case "jwt-preferred":
+        if (this.jwt) {
+          headers["Authorization"] = `Bearer ${this.jwt}`;
+        }
+        if (this.apiKey) {
+          headers["X-API-Key"] = this.apiKey;
+        }
+        break;
+
+      case "both":
+        if (this.jwt) {
+          headers["Authorization"] = `Bearer ${this.jwt}`;
+        }
+        if (this.apiKey) {
+          headers["X-API-Key"] = this.apiKey;
+        }
+        break;
+    }
+
+    return headers;
+  }
+
+  /**
+   * Set API key
+   */
+  setApiKey(apiKey?: string): void {
+    this.apiKey = apiKey;
+  }
+
+  /**
+   * Set JWT token
+   */
+  setJwt(jwt?: string): void {
+    this.jwt = jwt;
+  }
+
+  /**
+   * Detect auth type based on path
+   */
+  private detectAuthType(path: string): AuthType {
+    for (const rule of this.authRules) {
+      if (path.includes(rule.pattern)) {
+        return rule.type;
+      }
+    }
+    // Default: send both if available
+    return "both";
+  }
+}

package/src/core/transport/RequestLogger.ts

@@ -0,0 +1,116 @@
+/**
+ * Request logger for debugging HTTP operations
+ */
+export class RequestLogger {
+  private readonly debug: boolean;
+
+  constructor(debug: boolean = false) {
+    this.debug = debug;
+  }
+
+  /**
+   * Log successful request
+   */
+  logSuccess(
+    method: string,
+    path: string,
+    duration: number,
+    queryDetails?: string
+  ): void {
+    if (typeof console === "undefined") return;
+
+    const logMessage = `[HttpClient] ${method} ${path} completed in ${duration.toFixed(2)}ms`;
+
+    if (queryDetails && this.debug) {
+      console.log(logMessage);
+      console.log(`[HttpClient]   ${queryDetails}`);
+    } else {
+      console.log(logMessage);
+    }
+  }
+
+  /**
+   * Log failed request
+   */
+  logError(
+    method: string,
+    path: string,
+    duration: number,
+    error: any,
+    queryDetails?: string
+  ): void {
+    if (typeof console === "undefined") return;
+
+    // Special handling for 404 on find-one (expected behavior)
+    const is404FindOne =
+      path === "/v1/rqlite/find-one" &&
+      error?.httpStatus === 404;
+
+    if (is404FindOne) {
+      console.warn(
+        `[HttpClient] ${method} ${path} returned 404 after ${duration.toFixed(2)}ms (expected for optional lookups)`
+      );
+      return;
+    }
+
+    const errorMessage = `[HttpClient] ${method} ${path} failed after ${duration.toFixed(2)}ms:`;
+    console.error(errorMessage, error);
+
+    if (queryDetails && this.debug) {
+      console.error(`[HttpClient]   ${queryDetails}`);
+    }
+  }
+
+  /**
+   * Extract query details from request for logging
+   */
+  extractQueryDetails(path: string, body?: any): string | null {
+    if (!this.debug) return null;
+
+    const isRqliteOperation = path.includes("/v1/rqlite/");
+    if (!isRqliteOperation || !body) return null;
+
+    try {
+      const parsedBody = typeof body === "string" ? JSON.parse(body) : body;
+
+      // Direct SQL query
+      if (parsedBody.sql) {
+        let details = `SQL: ${parsedBody.sql}`;
+        if (parsedBody.args && parsedBody.args.length > 0) {
+          details += ` | Args: [${parsedBody.args
+            .map((a: any) => (typeof a === "string" ? `"${a}"` : a))
+            .join(", ")}]`;
+        }
+        return details;
+      }
+
+      // Table-based query
+      if (parsedBody.table) {
+        let details = `Table: ${parsedBody.table}`;
+        if (parsedBody.criteria && Object.keys(parsedBody.criteria).length > 0) {
+          details += ` | Criteria: ${JSON.stringify(parsedBody.criteria)}`;
+        }
+        if (parsedBody.options) {
+          details += ` | Options: ${JSON.stringify(parsedBody.options)}`;
+        }
+        if (parsedBody.select) {
+          details += ` | Select: ${JSON.stringify(parsedBody.select)}`;
+        }
+        if (parsedBody.where) {
+          details += ` | Where: ${JSON.stringify(parsedBody.where)}`;
+        }
+        if (parsedBody.limit) {
+          details += ` | Limit: ${parsedBody.limit}`;
+        }
+        if (parsedBody.offset) {
+          details += ` | Offset: ${parsedBody.offset}`;
+        }
+        return details;
+      }
+    } catch {
+      // Failed to parse, ignore
+    }
+
+    return null;
+  }
+}

package/src/core/transport/RequestRetryPolicy.ts

@@ -0,0 +1,53 @@
+import type { IRetryPolicy } from "../interfaces/IRetryPolicy";
+import { SDKError } from "../../errors";
+
+/**
+ * Exponential backoff retry policy
+ * Retries failed requests with increasing delays
+ */
+export class ExponentialBackoffRetryPolicy implements IRetryPolicy {
+  private readonly maxRetries: number;
+  private readonly baseDelayMs: number;
+
+  /**
+   * HTTP status codes that should trigger a retry
+   */
+  private readonly retryableStatusCodes = [408, 429, 500, 502, 503, 504];
+
+  constructor(maxRetries: number = 3, baseDelayMs: number = 1000) {
+    this.maxRetries = maxRetries;
+    this.baseDelayMs = baseDelayMs;
+  }
+
+  /**
+   * Determine if request should be retried
+   */
+  shouldRetry(error: any, attempt: number): boolean {
+    // Don't retry if max attempts reached
+    if (attempt >= this.maxRetries) {
+      return false;
+    }
+
+    // Retry on retryable HTTP errors
+    if (error instanceof SDKError) {
+      return this.retryableStatusCodes.includes(error.httpStatus);
+    }
+
+    // Don't retry other errors
+    return false;
+  }
+
+  /**
+   * Get delay before next retry (exponential backoff)
+   */
+  getDelay(attempt: number): number {
+    return this.baseDelayMs * (attempt + 1);
+  }
+
+  /**
+   * Get maximum number of retry attempts
+   */
+  getMaxRetries(): number {
+    return this.maxRetries;
+  }
+}

package/src/core/transport/TLSConfiguration.ts

@@ -0,0 +1,53 @@
+/**
+ * TLS Configuration for development/staging environments
+ *
+ * WARNING: Only use this in development/testing environments!
+ * DO NOT disable certificate validation in production.
+ */
+export class TLSConfiguration {
+  /**
+   * Create fetch function with proper TLS configuration
+   */
+  static createFetchWithTLSConfig(): typeof fetch {
+    // Only allow insecure TLS in development
+    if (this.shouldAllowInsecure()) {
+      this.configureInsecureTLS();
+    }
+
+    return globalThis.fetch;
+  }
+
+  /**
+   * Check if insecure TLS should be allowed
+   */
+  private static shouldAllowInsecure(): boolean {
+    // Check if we're in Node.js environment
+    if (typeof process === "undefined" || !process.versions?.node) {
+      return false;
+    }
+
+    // Only allow in non-production with explicit flag
+    const isProduction = process.env.NODE_ENV === "production";
+    const allowInsecure = process.env.DEBROS_ALLOW_INSECURE_TLS === "true";
+
+    return !isProduction && allowInsecure;
+  }
+
+  /**
+   * Configure Node.js to allow insecure TLS
+   * WARNING: Only call in development!
+   */
+  private static configureInsecureTLS(): void {
+    if (typeof process !== "undefined" && process.env) {
+      // Allow self-signed/staging certificates for development
+      process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
+
+      if (typeof console !== "undefined") {
+        console.warn(
+          "[TLSConfiguration] WARNING: TLS certificate validation disabled for development. " +
+          "DO NOT use in production!"
+        );
+      }
+    }
+  }
+}

package/src/core/transport/index.ts

@@ -0,0 +1,4 @@
+export { PathBasedAuthStrategy } from "./AuthHeaderStrategy";
+export { ExponentialBackoffRetryPolicy } from "./RequestRetryPolicy";
+export { RequestLogger } from "./RequestLogger";
+export { TLSConfiguration } from "./TLSConfiguration";

package/src/db/index.ts

@@ -0,0 +1,13 @@
+export { DBClient } from "./client";
+export { QueryBuilder } from "./qb";
+export { Repository } from "./repository";
+export type {
+  Entity,
+  QueryResponse,
+  TransactionOp,
+  TransactionRequest,
+  SelectOptions,
+  FindOptions,
+  ColumnDefinition,
+} from "./types";
+export { extractTableName, extractPrimaryKey } from "./types";

package/src/functions/index.ts

@@ -0,0 +1,2 @@
+export { FunctionsClient, type FunctionsClientConfig } from "./client";
+export type { FunctionResponse, SuccessResponse } from "./types";

package/src/index.ts

@@ -43,6 +43,7 @@ export function createClient(config: ClientConfig): Client {
     timeout: config.timeout,
     maxRetries: config.maxRetries,
     retryDelayMs: config.retryDelayMs,
+    debug: config.debug,
     fetch: config.fetch,
     onNetworkError: config.onNetworkError,
   });

package/src/network/index.ts

@@ -0,0 +1,7 @@
+export { NetworkClient } from "./client";
+export type {
+  PeerInfo,
+  NetworkStatus,
+  ProxyRequest,
+  ProxyResponse,
+} from "./client";