@insforge/sdk 1.2.0-dev.1 → 1.2.0

package/dist/index.d.mts

@@ -45,6 +45,35 @@ interface InsForgeConfig {
      * Custom headers to include with every request
      */
     headers?: Record<string, string>;
+    /**
+     * Enable debug logging for HTTP requests and responses.
+     * When true, request/response details are logged to the console.
+     * Can also be a custom log function for advanced use cases.
+     * @default false
+     */
+    debug?: boolean | ((message: string, ...args: any[]) => void);
+    /**
+     * Request timeout in milliseconds.
+     * Requests that exceed this duration will be aborted.
+     * Set to 0 to disable timeout.
+     * @default 30000
+     */
+    timeout?: number;
+    /**
+     * Maximum number of retry attempts for failed requests.
+     * Retries are triggered on network errors and server errors (5xx).
+     * Client errors (4xx) are never retried.
+     * Set to 0 to disable retries.
+     * @default 3
+     */
+    retryCount?: number;
+    /**
+     * Initial delay in milliseconds before the first retry.
+     * The delay doubles with each subsequent attempt (exponential backoff)
+     * with ±15% jitter to prevent thundering herd.
+     * @default 500
+     */
+    retryDelay?: number;
 }
 interface AuthSession {
     user: UserSchema;
@@ -65,24 +94,132 @@ declare class InsForgeError extends Error {
     static fromApiError(apiError: ApiError): InsForgeError;
 }
 
+type LogFunction = (message: string, ...args: any[]) => void;
+/**
+ * Debug logger for the InsForge SDK.
+ * Logs HTTP request/response details with automatic redaction of sensitive data.
+ *
+ * @example
+ * ```typescript
+ * // Enable via SDK config
+ * const client = new InsForgeClient({ debug: true });
+ *
+ * // Or with a custom log function
+ * const client = new InsForgeClient({
+ *   debug: (msg) => myLogger.info(msg)
+ * });
+ * ```
+ */
+declare class Logger {
+    /** Whether debug logging is currently enabled */
+    enabled: boolean;
+    private customLog;
+    /**
+     * Creates a new Logger instance.
+     * @param debug - Set to true to enable console logging, or pass a custom log function
+     */
+    constructor(debug?: boolean | LogFunction);
+    /**
+     * 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: string, ...args: any[]): void;
+    /**
+     * 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: string, ...args: any[]): void;
+    /**
+     * 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: string, ...args: any[]): void;
+    /**
+     * 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: string, url: string, headers?: Record<string, string>, body?: any): void;
+    /**
+     * 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: string, url: string, status: number, durationMs: number, body?: any): void;
+}
+
 interface RequestOptions extends RequestInit {
     params?: Record<string, string>;
+    /** Allow retrying non-idempotent requests (POST, PATCH). Off by default to prevent duplicate writes. */
+    idempotent?: boolean;
 }
+/**
+ * HTTP client with built-in retry, timeout, and exponential backoff support.
+ * Handles authentication, request serialization, and error normalization.
+ */
 declare class HttpClient {
     readonly baseUrl: string;
     readonly fetch: typeof fetch;
     private defaultHeaders;
     private anonKey;
     private userToken;
-    constructor(config: InsForgeConfig);
+    private logger;
+    private timeout;
+    private retryCount;
+    private retryDelay;
+    /**
+     * 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: InsForgeConfig, logger?: Logger);
+    /**
+     * Builds a full URL from a path and optional query parameters.
+     * Normalizes PostgREST select parameters for proper syntax.
+     */
     private buildUrl;
+    /** Checks if an HTTP status code is eligible for retry (5xx server errors). */
+    private isRetryableStatus;
+    /**
+     * 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.
+     */
+    private computeRetryDelay;
+    /**
+     * 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.
+     */
     request<T>(method: string, path: string, options?: RequestOptions): Promise<T>;
+    /** Performs a GET request. */
     get<T>(path: string, options?: RequestOptions): Promise<T>;
+    /** Performs a POST request with an optional JSON body. */
     post<T>(path: string, body?: any, options?: RequestOptions): Promise<T>;
+    /** Performs a PUT request with an optional JSON body. */
     put<T>(path: string, body?: any, options?: RequestOptions): Promise<T>;
+    /** Performs a PATCH request with an optional JSON body. */
     patch<T>(path: string, body?: any, options?: RequestOptions): Promise<T>;
+    /** Performs a DELETE request. */
     delete<T>(path: string, options?: RequestOptions): Promise<T>;
+    /** Sets or clears the user authentication token for subsequent requests. */
     setAuthToken(token: string | null): void;
+    /** Returns the current default headers including the authorization header if set. */
     getHeaders(): Record<string, string>;
 }
 
@@ -870,6 +1007,12 @@ declare class Emails {
  * const { data, error } = await client.functions.invoke('my-function', {
  *   body: { message: 'Hello from SDK' }
  * });
+ *
+ * // Enable debug logging
+ * const debugClient = new InsForgeClient({
+ *   baseUrl: 'http://localhost:7130',
+ *   debug: true
+ * });
  * ```
  */
 declare class InsForgeClient {
@@ -903,4 +1046,4 @@ declare class InsForgeClient {
 
 declare function createClient(config: InsForgeConfig): InsForgeClient;
 
-export { AI, type ApiError, Auth, type AuthSession, type InsForgeConfig as ClientOptions, type ConnectionState, Database, Emails, type EventCallback, type FunctionInvokeOptions, Functions, HttpClient, InsForgeClient, type InsForgeConfig, InsForgeError, Realtime, Storage, StorageBucket, type StorageResponse, TokenManager, createClient, InsForgeClient as default };
+export { AI, type ApiError, Auth, type AuthSession, type InsForgeConfig as ClientOptions, type ConnectionState, Database, Emails, type EventCallback, type FunctionInvokeOptions, Functions, HttpClient, InsForgeClient, type InsForgeConfig, InsForgeError, Logger, Realtime, Storage, StorageBucket, type StorageResponse, TokenManager, createClient, InsForgeClient as default };

package/dist/index.d.ts

@@ -45,6 +45,35 @@ interface InsForgeConfig {
      * Custom headers to include with every request
      */
     headers?: Record<string, string>;
+    /**
+     * Enable debug logging for HTTP requests and responses.
+     * When true, request/response details are logged to the console.
+     * Can also be a custom log function for advanced use cases.
+     * @default false
+     */
+    debug?: boolean | ((message: string, ...args: any[]) => void);
+    /**
+     * Request timeout in milliseconds.
+     * Requests that exceed this duration will be aborted.
+     * Set to 0 to disable timeout.
+     * @default 30000
+     */
+    timeout?: number;
+    /**
+     * Maximum number of retry attempts for failed requests.
+     * Retries are triggered on network errors and server errors (5xx).
+     * Client errors (4xx) are never retried.
+     * Set to 0 to disable retries.
+     * @default 3
+     */
+    retryCount?: number;
+    /**
+     * Initial delay in milliseconds before the first retry.
+     * The delay doubles with each subsequent attempt (exponential backoff)
+     * with ±15% jitter to prevent thundering herd.
+     * @default 500
+     */
+    retryDelay?: number;
 }
 interface AuthSession {
     user: UserSchema;
@@ -65,24 +94,132 @@ declare class InsForgeError extends Error {
     static fromApiError(apiError: ApiError): InsForgeError;
 }
 
+type LogFunction = (message: string, ...args: any[]) => void;
+/**
+ * Debug logger for the InsForge SDK.
+ * Logs HTTP request/response details with automatic redaction of sensitive data.
+ *
+ * @example
+ * ```typescript
+ * // Enable via SDK config
+ * const client = new InsForgeClient({ debug: true });
+ *
+ * // Or with a custom log function
+ * const client = new InsForgeClient({
+ *   debug: (msg) => myLogger.info(msg)
+ * });
+ * ```
+ */
+declare class Logger {
+    /** Whether debug logging is currently enabled */
+    enabled: boolean;
+    private customLog;
+    /**
+     * Creates a new Logger instance.
+     * @param debug - Set to true to enable console logging, or pass a custom log function
+     */
+    constructor(debug?: boolean | LogFunction);
+    /**
+     * 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: string, ...args: any[]): void;
+    /**
+     * 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: string, ...args: any[]): void;
+    /**
+     * 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: string, ...args: any[]): void;
+    /**
+     * 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: string, url: string, headers?: Record<string, string>, body?: any): void;
+    /**
+     * 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: string, url: string, status: number, durationMs: number, body?: any): void;
+}
+
 interface RequestOptions extends RequestInit {
     params?: Record<string, string>;
+    /** Allow retrying non-idempotent requests (POST, PATCH). Off by default to prevent duplicate writes. */
+    idempotent?: boolean;
 }
+/**
+ * HTTP client with built-in retry, timeout, and exponential backoff support.
+ * Handles authentication, request serialization, and error normalization.
+ */
 declare class HttpClient {
     readonly baseUrl: string;
     readonly fetch: typeof fetch;
     private defaultHeaders;
     private anonKey;
     private userToken;
-    constructor(config: InsForgeConfig);
+    private logger;
+    private timeout;
+    private retryCount;
+    private retryDelay;
+    /**
+     * 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: InsForgeConfig, logger?: Logger);
+    /**
+     * Builds a full URL from a path and optional query parameters.
+     * Normalizes PostgREST select parameters for proper syntax.
+     */
     private buildUrl;
+    /** Checks if an HTTP status code is eligible for retry (5xx server errors). */
+    private isRetryableStatus;
+    /**
+     * 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.
+     */
+    private computeRetryDelay;
+    /**
+     * 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.
+     */
     request<T>(method: string, path: string, options?: RequestOptions): Promise<T>;
+    /** Performs a GET request. */
     get<T>(path: string, options?: RequestOptions): Promise<T>;
+    /** Performs a POST request with an optional JSON body. */
     post<T>(path: string, body?: any, options?: RequestOptions): Promise<T>;
+    /** Performs a PUT request with an optional JSON body. */
     put<T>(path: string, body?: any, options?: RequestOptions): Promise<T>;
+    /** Performs a PATCH request with an optional JSON body. */
     patch<T>(path: string, body?: any, options?: RequestOptions): Promise<T>;
+    /** Performs a DELETE request. */
     delete<T>(path: string, options?: RequestOptions): Promise<T>;
+    /** Sets or clears the user authentication token for subsequent requests. */
     setAuthToken(token: string | null): void;
+    /** Returns the current default headers including the authorization header if set. */
     getHeaders(): Record<string, string>;
 }
 
@@ -870,6 +1007,12 @@ declare class Emails {
  * const { data, error } = await client.functions.invoke('my-function', {
  *   body: { message: 'Hello from SDK' }
  * });
+ *
+ * // Enable debug logging
+ * const debugClient = new InsForgeClient({
+ *   baseUrl: 'http://localhost:7130',
+ *   debug: true
+ * });
  * ```
  */
 declare class InsForgeClient {
@@ -903,4 +1046,4 @@ declare class InsForgeClient {
 
 declare function createClient(config: InsForgeConfig): InsForgeClient;
 
-export { AI, type ApiError, Auth, type AuthSession, type InsForgeConfig as ClientOptions, type ConnectionState, Database, Emails, type EventCallback, type FunctionInvokeOptions, Functions, HttpClient, InsForgeClient, type InsForgeConfig, InsForgeError, Realtime, Storage, StorageBucket, type StorageResponse, TokenManager, createClient, InsForgeClient as default };
+export { AI, type ApiError, Auth, type AuthSession, type InsForgeConfig as ClientOptions, type ConnectionState, Database, Emails, type EventCallback, type FunctionInvokeOptions, Functions, HttpClient, InsForgeClient, type InsForgeConfig, InsForgeError, Logger, Realtime, Storage, StorageBucket, type StorageResponse, TokenManager, createClient, InsForgeClient as default };