@insforge/sdk 1.2.0-dev.2 → 1.2.0

package/dist/index.mjs

@@ -17,9 +17,191 @@ var InsForgeError = class _InsForgeError extends Error {
   }
 };
 
+// src/lib/logger.ts
+var SENSITIVE_HEADERS = ["authorization", "x-api-key", "cookie", "set-cookie"];
+var SENSITIVE_BODY_KEYS = [
+  "password",
+  "token",
+  "accesstoken",
+  "refreshtoken",
+  "authorization",
+  "secret",
+  "apikey",
+  "api_key",
+  "email",
+  "ssn",
+  "creditcard",
+  "credit_card"
+];
+function redactHeaders(headers) {
+  const redacted = {};
+  for (const [key, value] of Object.entries(headers)) {
+    if (SENSITIVE_HEADERS.includes(key.toLowerCase())) {
+      redacted[key] = "***REDACTED***";
+    } else {
+      redacted[key] = value;
+    }
+  }
+  return redacted;
+}
+function sanitizeBody(body) {
+  if (body === null || body === void 0) return body;
+  if (typeof body === "string") {
+    try {
+      const parsed = JSON.parse(body);
+      return sanitizeBody(parsed);
+    } catch {
+      return body;
+    }
+  }
+  if (Array.isArray(body)) return body.map(sanitizeBody);
+  if (typeof body === "object") {
+    const sanitized = {};
+    for (const [key, value] of Object.entries(body)) {
+      if (SENSITIVE_BODY_KEYS.includes(key.toLowerCase().replace(/[-_]/g, ""))) {
+        sanitized[key] = "***REDACTED***";
+      } else {
+        sanitized[key] = sanitizeBody(value);
+      }
+    }
+    return sanitized;
+  }
+  return body;
+}
+function formatBody(body) {
+  if (body === void 0 || body === null) return "";
+  if (typeof body === "string") {
+    try {
+      return JSON.stringify(JSON.parse(body), null, 2);
+    } catch {
+      return body;
+    }
+  }
+  if (typeof FormData !== "undefined" && body instanceof FormData) {
+    return "[FormData]";
+  }
+  try {
+    return JSON.stringify(body, null, 2);
+  } catch {
+    return "[Unserializable body]";
+  }
+}
+var Logger = class {
+  /**
+   * Creates a new Logger instance.
+   * @param debug - Set to true to enable console logging, or pass a custom log function
+   */
+  constructor(debug) {
+    if (typeof debug === "function") {
+      this.enabled = true;
+      this.customLog = debug;
+    } else {
+      this.enabled = !!debug;
+      this.customLog = null;
+    }
+  }
+  /**
+   * Logs a debug message at the info level.
+   * @param message - The message to log
+   * @param args - Additional arguments to pass to the log function
+   */
+  log(message, ...args) {
+    if (!this.enabled) return;
+    const formatted = `[InsForge Debug] ${message}`;
+    if (this.customLog) {
+      this.customLog(formatted, ...args);
+    } else {
+      console.log(formatted, ...args);
+    }
+  }
+  /**
+   * Logs a debug message at the warning level.
+   * @param message - The message to log
+   * @param args - Additional arguments to pass to the log function
+   */
+  warn(message, ...args) {
+    if (!this.enabled) return;
+    const formatted = `[InsForge Debug] ${message}`;
+    if (this.customLog) {
+      this.customLog(formatted, ...args);
+    } else {
+      console.warn(formatted, ...args);
+    }
+  }
+  /**
+   * Logs a debug message at the error level.
+   * @param message - The message to log
+   * @param args - Additional arguments to pass to the log function
+   */
+  error(message, ...args) {
+    if (!this.enabled) return;
+    const formatted = `[InsForge Debug] ${message}`;
+    if (this.customLog) {
+      this.customLog(formatted, ...args);
+    } else {
+      console.error(formatted, ...args);
+    }
+  }
+  /**
+   * Logs an outgoing HTTP request with method, URL, headers, and body.
+   * Sensitive headers and body fields are automatically redacted.
+   * @param method - HTTP method (GET, POST, etc.)
+   * @param url - The full request URL
+   * @param headers - Request headers (sensitive values will be redacted)
+   * @param body - Request body (sensitive fields will be masked)
+   */
+  logRequest(method, url, headers, body) {
+    if (!this.enabled) return;
+    const parts = [
+      `\u2192 ${method} ${url}`
+    ];
+    if (headers && Object.keys(headers).length > 0) {
+      parts.push(`  Headers: ${JSON.stringify(redactHeaders(headers))}`);
+    }
+    const formattedBody = formatBody(sanitizeBody(body));
+    if (formattedBody) {
+      const truncated = formattedBody.length > 1e3 ? formattedBody.slice(0, 1e3) + "... [truncated]" : formattedBody;
+      parts.push(`  Body: ${truncated}`);
+    }
+    this.log(parts.join("\n"));
+  }
+  /**
+   * Logs an incoming HTTP response with method, URL, status, duration, and body.
+   * Error responses (4xx/5xx) are logged at the error level.
+   * @param method - HTTP method (GET, POST, etc.)
+   * @param url - The full request URL
+   * @param status - HTTP response status code
+   * @param durationMs - Request duration in milliseconds
+   * @param body - Response body (sensitive fields will be masked, large bodies truncated)
+   */
+  logResponse(method, url, status, durationMs, body) {
+    if (!this.enabled) return;
+    const parts = [
+      `\u2190 ${method} ${url} ${status} (${durationMs}ms)`
+    ];
+    const formattedBody = formatBody(sanitizeBody(body));
+    if (formattedBody) {
+      const truncated = formattedBody.length > 1e3 ? formattedBody.slice(0, 1e3) + "... [truncated]" : formattedBody;
+      parts.push(`  Body: ${truncated}`);
+    }
+    if (status >= 400) {
+      this.error(parts.join("\n"));
+    } else {
+      this.log(parts.join("\n"));
+    }
+  }
+};
+
 // src/lib/http-client.ts
+var RETRYABLE_STATUS_CODES = /* @__PURE__ */ new Set([500, 502, 503, 504]);
+var IDEMPOTENT_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD", "PUT", "DELETE", "OPTIONS"]);
 var HttpClient = class {
-  constructor(config) {
+  /**
+   * Creates a new HttpClient instance.
+   * @param config - SDK configuration including baseUrl, timeout, retry settings, and fetch implementation.
+   * @param logger - Optional logger instance for request/response debugging.
+   */
+  constructor(config, logger) {
     this.userToken = null;
     this.baseUrl = config.baseUrl || "http://localhost:7130";
     this.fetch = config.fetch || (globalThis.fetch ? globalThis.fetch.bind(globalThis) : void 0);
@@ -27,12 +209,20 @@ var HttpClient = class {
     this.defaultHeaders = {
       ...config.headers
     };
+    this.logger = logger || new Logger(false);
+    this.timeout = config.timeout ?? 3e4;
+    this.retryCount = config.retryCount ?? 3;
+    this.retryDelay = config.retryDelay ?? 500;
     if (!this.fetch) {
       throw new Error(
         "Fetch is not available. Please provide a fetch implementation in the config."
       );
     }
   }
+  /**
+   * Builds a full URL from a path and optional query parameters.
+   * Normalizes PostgREST select parameters for proper syntax.
+   */
   buildUrl(path, params) {
     const url = new URL(path, this.baseUrl);
     if (params) {
@@ -48,9 +238,36 @@ var HttpClient = class {
     }
     return url.toString();
   }
+  /** Checks if an HTTP status code is eligible for retry (5xx server errors). */
+  isRetryableStatus(status) {
+    return RETRYABLE_STATUS_CODES.has(status);
+  }
+  /**
+   * Computes the delay before the next retry using exponential backoff with jitter.
+   * @param attempt - The current retry attempt number (1-based).
+   * @returns Delay in milliseconds.
+   */
+  computeRetryDelay(attempt) {
+    const base = this.retryDelay * Math.pow(2, attempt - 1);
+    const jitter = base * (0.85 + Math.random() * 0.3);
+    return Math.round(jitter);
+  }
+  /**
+   * Performs an HTTP request with automatic retry and timeout handling.
+   * Retries on network errors and 5xx server errors with exponential backoff.
+   * Client errors (4xx) and timeouts are thrown immediately without retry.
+   * @param method - HTTP method (GET, POST, PUT, PATCH, DELETE).
+   * @param path - API path relative to the base URL.
+   * @param options - Optional request configuration including headers, body, and query params.
+   * @returns Parsed response data.
+   * @throws {InsForgeError} On timeout, network failure, or HTTP error responses.
+   */
   async request(method, path, options = {}) {
-    const { params, headers = {}, body, ...fetchOptions } = options;
+    const { params, headers = {}, body, signal: callerSignal, ...fetchOptions } = options;
     const url = this.buildUrl(path, params);
+    const startTime = Date.now();
+    const canRetry = IDEMPOTENT_METHODS.has(method.toUpperCase()) || options.idempotent === true;
+    const maxAttempts = canRetry ? this.retryCount : 0;
     const requestHeaders = {
       ...this.defaultHeaders
     };
@@ -69,62 +286,175 @@ var HttpClient = class {
         processedBody = JSON.stringify(body);
       }
     }
-    Object.assign(requestHeaders, headers);
-    const response = await this.fetch(url, {
-      method,
-      headers: requestHeaders,
-      body: processedBody,
-      ...fetchOptions
-    });
-    if (response.status === 204) {
-      return void 0;
-    }
-    let data;
-    const contentType = response.headers.get("content-type");
-    if (contentType?.includes("json")) {
-      data = await response.json();
+    if (headers instanceof Headers) {
+      headers.forEach((value, key) => {
+        requestHeaders[key] = value;
+      });
+    } else if (Array.isArray(headers)) {
+      headers.forEach(([key, value]) => {
+        requestHeaders[key] = value;
+      });
     } else {
-      data = await response.text();
+      Object.assign(requestHeaders, headers);
     }
-    if (!response.ok) {
-      if (data && typeof data === "object" && "error" in data) {
-        if (!data.statusCode && !data.status) {
-          data.statusCode = response.status;
+    this.logger.logRequest(method, url, requestHeaders, processedBody);
+    let lastError;
+    for (let attempt = 0; attempt <= maxAttempts; attempt++) {
+      if (attempt > 0) {
+        const delay = this.computeRetryDelay(attempt);
+        this.logger.warn(`Retry ${attempt}/${maxAttempts} for ${method} ${url} in ${delay}ms`);
+        if (callerSignal?.aborted) throw callerSignal.reason;
+        await new Promise((resolve, reject) => {
+          const onAbort = () => {
+            clearTimeout(timer2);
+            reject(callerSignal.reason);
+          };
+          const timer2 = setTimeout(() => {
+            if (callerSignal) callerSignal.removeEventListener("abort", onAbort);
+            resolve();
+          }, delay);
+          if (callerSignal) {
+            callerSignal.addEventListener("abort", onAbort, { once: true });
+          }
+        });
+      }
+      let controller;
+      let timer;
+      if (this.timeout > 0 || callerSignal) {
+        controller = new AbortController();
+        if (this.timeout > 0) {
+          timer = setTimeout(() => controller.abort(), this.timeout);
         }
-        const error = InsForgeError.fromApiError(data);
-        Object.keys(data).forEach((key) => {
-          if (key !== "error" && key !== "message" && key !== "statusCode") {
-            error[key] = data[key];
+        if (callerSignal) {
+          if (callerSignal.aborted) {
+            controller.abort(callerSignal.reason);
+          } else {
+            const onCallerAbort = () => controller.abort(callerSignal.reason);
+            callerSignal.addEventListener("abort", onCallerAbort, { once: true });
+            controller.signal.addEventListener("abort", () => {
+              callerSignal.removeEventListener("abort", onCallerAbort);
+            }, { once: true });
           }
+        }
+      }
+      try {
+        const response = await this.fetch(url, {
+          method,
+          headers: requestHeaders,
+          body: processedBody,
+          ...fetchOptions,
+          ...controller ? { signal: controller.signal } : {}
         });
-        throw error;
+        if (this.isRetryableStatus(response.status) && attempt < maxAttempts) {
+          if (timer !== void 0) clearTimeout(timer);
+          await response.body?.cancel();
+          lastError = new InsForgeError(
+            `Server error: ${response.status} ${response.statusText}`,
+            response.status,
+            "SERVER_ERROR"
+          );
+          continue;
+        }
+        if (response.status === 204) {
+          if (timer !== void 0) clearTimeout(timer);
+          return void 0;
+        }
+        let data;
+        const contentType = response.headers.get("content-type");
+        try {
+          if (contentType?.includes("json")) {
+            data = await response.json();
+          } else {
+            data = await response.text();
+          }
+        } catch (parseErr) {
+          if (timer !== void 0) clearTimeout(timer);
+          throw new InsForgeError(
+            `Failed to parse response body: ${parseErr?.message || "Unknown error"}`,
+            response.status,
+            response.ok ? "PARSE_ERROR" : "REQUEST_FAILED"
+          );
+        }
+        if (timer !== void 0) clearTimeout(timer);
+        if (!response.ok) {
+          this.logger.logResponse(method, url, response.status, Date.now() - startTime, data);
+          if (data && typeof data === "object" && "error" in data) {
+            if (!data.statusCode && !data.status) {
+              data.statusCode = response.status;
+            }
+            const error = InsForgeError.fromApiError(data);
+            Object.keys(data).forEach((key) => {
+              if (key !== "error" && key !== "message" && key !== "statusCode") {
+                error[key] = data[key];
+              }
+            });
+            throw error;
+          }
+          throw new InsForgeError(
+            `Request failed: ${response.statusText}`,
+            response.status,
+            "REQUEST_FAILED"
+          );
+        }
+        this.logger.logResponse(method, url, response.status, Date.now() - startTime, data);
+        return data;
+      } catch (err) {
+        if (timer !== void 0) clearTimeout(timer);
+        if (err?.name === "AbortError") {
+          if (controller && controller.signal.aborted && this.timeout > 0 && !callerSignal?.aborted) {
+            throw new InsForgeError(
+              `Request timed out after ${this.timeout}ms`,
+              408,
+              "REQUEST_TIMEOUT"
+            );
+          }
+          throw err;
+        }
+        if (err instanceof InsForgeError) {
+          throw err;
+        }
+        if (attempt < maxAttempts) {
+          lastError = err;
+          continue;
+        }
+        throw new InsForgeError(
+          `Network request failed: ${err?.message || "Unknown error"}`,
+          0,
+          "NETWORK_ERROR"
+        );
       }
-      throw new InsForgeError(
-        `Request failed: ${response.statusText}`,
-        response.status,
-        "REQUEST_FAILED"
-      );
     }
-    return data;
+    throw lastError || new InsForgeError(
+      "Request failed after all retry attempts",
+      0,
+      "NETWORK_ERROR"
+    );
   }
+  /** Performs a GET request. */
   get(path, options) {
     return this.request("GET", path, options);
   }
+  /** Performs a POST request with an optional JSON body. */
   post(path, body, options) {
     return this.request("POST", path, { ...options, body });
   }
+  /** Performs a PUT request with an optional JSON body. */
   put(path, body, options) {
     return this.request("PUT", path, { ...options, body });
   }
+  /** Performs a PATCH request with an optional JSON body. */
   patch(path, body, options) {
     return this.request("PATCH", path, { ...options, body });
   }
+  /** Performs a DELETE request. */
   delete(path, options) {
     return this.request("DELETE", path, options);
   }
+  /** Sets or clears the user authentication token for subsequent requests. */
   setAuthToken(token) {
     this.userToken = token;
   }
+  /** Returns the current default headers including the authorization header if set. */
   getHeaders() {
     const headers = { ...this.defaultHeaders };
     const authToken = this.userToken || this.anonKey;
@@ -1739,7 +2069,8 @@ var Emails = class {
 // src/client.ts
 var InsForgeClient = class {
   constructor(config = {}) {
-    this.http = new HttpClient(config);
+    const logger = new Logger(config.debug);
+    this.http = new HttpClient(config, logger);
     this.tokenManager = new TokenManager();
     if (config.edgeFunctionToken) {
       this.http.setAuthToken(config.edgeFunctionToken);
@@ -1791,6 +2122,7 @@ export {
   HttpClient,
   InsForgeClient,
   InsForgeError,
+  Logger,
   Realtime,
   Storage,
   StorageBucket,