@insforge/sdk 1.2.3 → 1.2.5-dev.0

package/dist/index.mjs

@@ -0,0 +1,2322 @@
+// src/types.ts
+var InsForgeError = class _InsForgeError extends Error {
+  constructor(message, statusCode, error, nextActions) {
+    super(message);
+    this.name = "InsForgeError";
+    this.statusCode = statusCode;
+    this.error = error;
+    this.nextActions = nextActions;
+  }
+  static fromApiError(apiError) {
+    return new _InsForgeError(
+      apiError.message,
+      apiError.statusCode,
+      apiError.error,
+      apiError.nextActions
+    );
+  }
+};
+
+// 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/token-manager.ts
+var CSRF_TOKEN_COOKIE = "insforge_csrf_token";
+function getCsrfToken() {
+  if (typeof document === "undefined") return null;
+  const match = document.cookie.split(";").find((c) => c.trim().startsWith(`${CSRF_TOKEN_COOKIE}=`));
+  if (!match) return null;
+  return match.split("=")[1] || null;
+}
+function setCsrfToken(token) {
+  if (typeof document === "undefined") return;
+  const maxAge = 7 * 24 * 60 * 60;
+  const secure = typeof window !== "undefined" && window.location.protocol === "https:" ? "; Secure" : "";
+  document.cookie = `${CSRF_TOKEN_COOKIE}=${encodeURIComponent(token)}; path=/; max-age=${maxAge}; SameSite=Lax${secure}`;
+}
+function clearCsrfToken() {
+  if (typeof document === "undefined") return;
+  const secure = typeof window !== "undefined" && window.location.protocol === "https:" ? "; Secure" : "";
+  document.cookie = `${CSRF_TOKEN_COOKIE}=; path=/; max-age=0; SameSite=Lax${secure}`;
+}
+var TokenManager = class {
+  constructor() {
+    // In-memory storage
+    this.accessToken = null;
+    this.user = null;
+    // Callback for token changes (used by realtime to reconnect with new token)
+    this.onTokenChange = null;
+  }
+  /**
+   * Save session in memory
+   */
+  saveSession(session) {
+    const tokenChanged = session.accessToken !== this.accessToken;
+    this.accessToken = session.accessToken;
+    this.user = session.user;
+    if (tokenChanged && this.onTokenChange) {
+      this.onTokenChange();
+    }
+  }
+  /**
+   * Get current session
+   */
+  getSession() {
+    if (!this.accessToken || !this.user) return null;
+    return {
+      accessToken: this.accessToken,
+      user: this.user
+    };
+  }
+  /**
+   * Get access token
+   */
+  getAccessToken() {
+    return this.accessToken;
+  }
+  /**
+   * Set access token
+   */
+  setAccessToken(token) {
+    const tokenChanged = token !== this.accessToken;
+    this.accessToken = token;
+    if (tokenChanged && this.onTokenChange) {
+      this.onTokenChange();
+    }
+  }
+  /**
+   * Get user
+   */
+  getUser() {
+    return this.user;
+  }
+  /**
+   * Set user
+   */
+  setUser(user) {
+    this.user = user;
+  }
+  /**
+   * Clear in-memory session
+   */
+  clearSession() {
+    const hadToken = this.accessToken !== null;
+    this.accessToken = null;
+    this.user = null;
+    if (hadToken && this.onTokenChange) {
+      this.onTokenChange();
+    }
+  }
+};
+
+// 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"]);
+function serializeBody(method, body, headers) {
+  if (body === void 0) return void 0;
+  if (method === "GET" || method === "HEAD") return void 0;
+  if (typeof FormData !== "undefined" && body instanceof FormData) {
+    return body;
+  }
+  headers["Content-Type"] = "application/json;charset=UTF-8";
+  return JSON.stringify(body);
+}
+async function parseResponse(response) {
+  if (response.status === 204) 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) {
+    throw new InsForgeError(
+      `Failed to parse response body: ${parseErr?.message || "Unknown error"}`,
+      response.status,
+      response.ok ? "PARSE_ERROR" : "REQUEST_FAILED"
+    );
+  }
+  if (!response.ok) {
+    if (data && typeof data === "object" && "error" in data) {
+      data.statusCode ?? (data.statusCode = data.status ?? 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"
+    );
+  }
+  return data;
+}
+var HttpClient = class {
+  /**
+   * Creates a new HttpClient instance.
+   * @param config - SDK configuration including baseUrl, timeout, retry settings, and fetch implementation.
+   * @param tokenManager - Token manager for session persistence.
+   * @param logger - Optional logger instance for request/response debugging.
+   */
+  constructor(config, tokenManager, logger) {
+    this.userToken = null;
+    this.autoRefreshToken = true;
+    this.isRefreshing = false;
+    this.refreshPromise = null;
+    this.refreshToken = null;
+    this.baseUrl = config.baseUrl || "http://localhost:7130";
+    this.autoRefreshToken = config.autoRefreshToken ?? true;
+    this.fetch = config.fetch || (globalThis.fetch ? globalThis.fetch.bind(globalThis) : void 0);
+    this.anonKey = config.anonKey;
+    this.defaultHeaders = {
+      ...config.headers
+    };
+    this.tokenManager = tokenManager ?? new TokenManager();
+    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) {
+      Object.entries(params).forEach(([key, value]) => {
+        if (key === "select") {
+          let normalizedValue = value.replace(/\s+/g, " ").trim();
+          normalizedValue = normalizedValue.replace(/\s*\(\s*/g, "(").replace(/\s*\)\s*/g, ")").replace(/\(\s+/g, "(").replace(/\s+\)/g, ")").replace(/,\s+(?=[^()]*\))/g, ",");
+          url.searchParams.append(key, normalizedValue);
+        } else {
+          url.searchParams.append(key, value);
+        }
+      });
+    }
+    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 handleRequest(method, path, 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
+    };
+    const authToken = this.userToken || this.anonKey;
+    if (authToken) {
+      requestHeaders["Authorization"] = `Bearer ${authToken}`;
+    }
+    const processedBody = serializeBody(method, body, requestHeaders);
+    if (headers instanceof Headers) {
+      headers.forEach((value, key) => {
+        requestHeaders[key] = value;
+      });
+    } else if (Array.isArray(headers)) {
+      headers.forEach(([key, value]) => {
+        requestHeaders[key] = value;
+      });
+    } else {
+      Object.assign(requestHeaders, headers);
+    }
+    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);
+        }
+        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 } : {}
+        });
+        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;
+        }
+        let data;
+        try {
+          data = await parseResponse(response);
+        } catch (err) {
+          if (timer !== void 0) clearTimeout(timer);
+          if (err instanceof InsForgeError) {
+            this.logger.logResponse(
+              method,
+              url,
+              err.statusCode || response.status,
+              Date.now() - startTime,
+              err
+            );
+          }
+          throw err;
+        }
+        if (timer !== void 0) clearTimeout(timer);
+        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 lastError || new InsForgeError(
+      "Request failed after all retry attempts",
+      0,
+      "NETWORK_ERROR"
+    );
+  }
+  async request(method, path, options = {}) {
+    try {
+      return await this.handleRequest(method, path, { ...options });
+    } catch (error) {
+      if (error instanceof InsForgeError && error.statusCode === 401 && error.error === "INVALID_TOKEN" && this.autoRefreshToken) {
+        try {
+          const newTokenData = await this.handleTokenRefresh();
+          this.setAuthToken(newTokenData.accessToken);
+          this.tokenManager.saveSession(newTokenData);
+          if (newTokenData.csrfToken) {
+            setCsrfToken(newTokenData.csrfToken);
+          }
+          if (newTokenData.refreshToken) {
+            this.setRefreshToken(newTokenData.refreshToken);
+          }
+          return await this.handleRequest(method, path, { ...options });
+        } catch (error2) {
+          this.tokenManager.clearSession();
+          this.userToken = null;
+          this.refreshToken = null;
+          clearCsrfToken();
+          throw error2;
+        }
+      }
+      throw 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;
+  }
+  setRefreshToken(token) {
+    this.refreshToken = token;
+  }
+  /** Returns the current default headers including the authorization header if set. */
+  getHeaders() {
+    const headers = { ...this.defaultHeaders };
+    const authToken = this.userToken || this.anonKey;
+    if (authToken) {
+      headers["Authorization"] = `Bearer ${authToken}`;
+    }
+    return headers;
+  }
+  async handleTokenRefresh() {
+    if (this.isRefreshing) {
+      return this.refreshPromise;
+    }
+    this.isRefreshing = true;
+    this.refreshPromise = (async () => {
+      try {
+        const csrfToken = getCsrfToken();
+        const body = this.refreshToken ? { refreshToken: this.refreshToken } : void 0;
+        const response = await this.handleRequest(
+          "POST",
+          "/api/auth/sessions/current",
+          {
+            body,
+            headers: csrfToken ? { "X-CSRF-Token": csrfToken } : {},
+            credentials: "include"
+          }
+        );
+        return response;
+      } finally {
+        this.isRefreshing = false;
+        this.refreshPromise = null;
+      }
+    })();
+    return this.refreshPromise;
+  }
+};
+
+// src/modules/auth/helpers.ts
+var PKCE_VERIFIER_KEY = "insforge_pkce_verifier";
+function base64UrlEncode(buffer) {
+  const base64 = btoa(String.fromCharCode(...buffer));
+  return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function generateCodeVerifier() {
+  const array = new Uint8Array(32);
+  crypto.getRandomValues(array);
+  return base64UrlEncode(array);
+}
+async function generateCodeChallenge(verifier) {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(verifier);
+  const hash = await crypto.subtle.digest("SHA-256", data);
+  return base64UrlEncode(new Uint8Array(hash));
+}
+function storePkceVerifier(verifier) {
+  if (typeof sessionStorage !== "undefined") {
+    sessionStorage.setItem(PKCE_VERIFIER_KEY, verifier);
+  }
+}
+function retrievePkceVerifier() {
+  if (typeof sessionStorage === "undefined") {
+    return null;
+  }
+  const verifier = sessionStorage.getItem(PKCE_VERIFIER_KEY);
+  if (verifier) {
+    sessionStorage.removeItem(PKCE_VERIFIER_KEY);
+  }
+  return verifier;
+}
+function wrapError(error, fallbackMessage) {
+  if (error instanceof InsForgeError) {
+    return { data: null, error };
+  }
+  return {
+    data: null,
+    error: new InsForgeError(
+      error instanceof Error ? error.message : fallbackMessage,
+      500,
+      "UNEXPECTED_ERROR"
+    )
+  };
+}
+function cleanUrlParams(...params) {
+  if (typeof window === "undefined") {
+    return;
+  }
+  const url = new URL(window.location.href);
+  params.forEach((p) => url.searchParams.delete(p));
+  window.history.replaceState({}, document.title, url.toString());
+}
+
+// src/modules/auth/auth.ts
+import { oAuthProvidersSchema } from "@insforge/shared-schemas";
+var Auth = class {
+  constructor(http, tokenManager, options = {}) {
+    this.http = http;
+    this.tokenManager = tokenManager;
+    this.options = options;
+    this.authCallbackHandled = this.detectAuthCallback();
+  }
+  isServerMode() {
+    return !!this.options.isServerMode;
+  }
+  /**
+   * Save session from API response
+   * Handles token storage, CSRF token, and HTTP auth header
+   */
+  saveSessionFromResponse(response) {
+    if (!response.accessToken || !response.user) {
+      return false;
+    }
+    const session = {
+      accessToken: response.accessToken,
+      user: response.user
+    };
+    if (!this.isServerMode() && response.csrfToken) {
+      setCsrfToken(response.csrfToken);
+    }
+    if (!this.isServerMode()) {
+      this.tokenManager.saveSession(session);
+    }
+    this.http.setAuthToken(response.accessToken);
+    this.http.setRefreshToken(response.refreshToken ?? null);
+    return true;
+  }
+  // ============================================================================
+  // OAuth Callback Detection (runs on initialization)
+  // ============================================================================
+  /**
+   * Detect and handle OAuth callback parameters in URL
+   * Supports PKCE flow (insforge_code)
+   */
+  async detectAuthCallback() {
+    if (this.isServerMode() || typeof window === "undefined") return;
+    try {
+      const params = new URLSearchParams(window.location.search);
+      const error = params.get("error");
+      if (error) {
+        cleanUrlParams("error");
+        console.debug("OAuth callback error:", error);
+        return;
+      }
+      const code = params.get("insforge_code");
+      if (code) {
+        cleanUrlParams("insforge_code");
+        const { error: exchangeError } = await this.exchangeOAuthCode(code);
+        if (exchangeError) {
+          console.debug("OAuth code exchange failed:", exchangeError.message);
+        }
+        return;
+      }
+    } catch (error) {
+      console.debug("OAuth callback detection skipped:", error);
+    }
+  }
+  // ============================================================================
+  // Sign Up / Sign In / Sign Out
+  // ============================================================================
+  async signUp(request) {
+    try {
+      const response = await this.http.post(
+        this.isServerMode() ? "/api/auth/users?client_type=mobile" : "/api/auth/users",
+        request,
+        { credentials: "include" }
+      );
+      if (response.accessToken && response.user) {
+        this.saveSessionFromResponse(response);
+      }
+      if (response.refreshToken) {
+        this.http.setRefreshToken(response.refreshToken);
+      }
+      return { data: response, error: null };
+    } catch (error) {
+      return wrapError(error, "An unexpected error occurred during sign up");
+    }
+  }
+  async signInWithPassword(request) {
+    try {
+      const response = await this.http.post(
+        this.isServerMode() ? "/api/auth/sessions?client_type=mobile" : "/api/auth/sessions",
+        request,
+        { credentials: "include" }
+      );
+      this.saveSessionFromResponse(response);
+      if (response.refreshToken) {
+        this.http.setRefreshToken(response.refreshToken);
+      }
+      return { data: response, error: null };
+    } catch (error) {
+      return wrapError(error, "An unexpected error occurred during sign in");
+    }
+  }
+  async signOut() {
+    try {
+      try {
+        await this.http.post(
+          this.isServerMode() ? "/api/auth/logout?client_type=mobile" : "/api/auth/logout",
+          void 0,
+          { credentials: "include" }
+        );
+      } catch {
+      }
+      this.tokenManager.clearSession();
+      this.http.setAuthToken(null);
+      this.http.setRefreshToken(null);
+      if (!this.isServerMode()) {
+        clearCsrfToken();
+      }
+      return { error: null };
+    } catch {
+      return {
+        error: new InsForgeError("Failed to sign out", 500, "SIGNOUT_ERROR")
+      };
+    }
+  }
+  // ============================================================================
+  // OAuth Authentication
+  // ============================================================================
+  /**
+   * Sign in with OAuth provider using PKCE flow
+   */
+  async signInWithOAuth(options) {
+    try {
+      const { provider, redirectTo, skipBrowserRedirect } = options;
+      const providerKey = encodeURIComponent(provider.toLowerCase());
+      const codeVerifier = generateCodeVerifier();
+      const codeChallenge = await generateCodeChallenge(codeVerifier);
+      storePkceVerifier(codeVerifier);
+      const params = { code_challenge: codeChallenge };
+      if (redirectTo) params.redirect_uri = redirectTo;
+      const isBuiltInProvider = oAuthProvidersSchema.options.includes(
+        providerKey
+      );
+      const oauthPath = isBuiltInProvider ? `/api/auth/oauth/${providerKey}` : `/api/auth/oauth/custom/${providerKey}`;
+      const response = await this.http.get(oauthPath, {
+        params
+      });
+      if (!this.isServerMode() && typeof window !== "undefined" && !skipBrowserRedirect) {
+        window.location.href = response.authUrl;
+        return { data: {}, error: null };
+      }
+      return {
+        data: { url: response.authUrl, provider: providerKey, codeVerifier },
+        error: null
+      };
+    } catch (error) {
+      if (error instanceof InsForgeError) {
+        return { data: {}, error };
+      }
+      return {
+        data: {},
+        error: new InsForgeError(
+          "An unexpected error occurred during OAuth initialization",
+          500,
+          "UNEXPECTED_ERROR"
+        )
+      };
+    }
+  }
+  /**
+   * Exchange OAuth authorization code for tokens (PKCE flow)
+   * Called automatically on initialization when insforge_code is in URL
+   */
+  async exchangeOAuthCode(code, codeVerifier) {
+    try {
+      const verifier = codeVerifier ?? retrievePkceVerifier();
+      if (!verifier) {
+        return {
+          data: null,
+          error: new InsForgeError(
+            "PKCE code verifier not found. Ensure signInWithOAuth was called in the same browser session.",
+            400,
+            "PKCE_VERIFIER_MISSING"
+          )
+        };
+      }
+      const request = {
+        code,
+        code_verifier: verifier
+      };
+      const response = await this.http.post(
+        this.isServerMode() ? "/api/auth/oauth/exchange?client_type=mobile" : "/api/auth/oauth/exchange",
+        request,
+        { credentials: "include" }
+      );
+      this.saveSessionFromResponse(response);
+      return {
+        data: response,
+        error: null
+      };
+    } catch (error) {
+      return wrapError(
+        error,
+        "An unexpected error occurred during OAuth code exchange"
+      );
+    }
+  }
+  /**
+   * Sign in with an ID token from a native SDK (Google One Tap, etc.)
+   * Use this for native mobile apps or Google One Tap on web.
+   *
+   * @param credentials.provider - The identity provider (currently only 'google' is supported)
+   * @param credentials.token - The ID token from the native SDK
+   */
+  async signInWithIdToken(credentials) {
+    try {
+      const { provider, token } = credentials;
+      const response = await this.http.post(
+        "/api/auth/id-token?client_type=mobile",
+        { provider, token },
+        { credentials: "include" }
+      );
+      this.saveSessionFromResponse(response);
+      if (response.refreshToken) {
+        this.http.setRefreshToken(response.refreshToken);
+      }
+      return {
+        data: response,
+        error: null
+      };
+    } catch (error) {
+      return wrapError(
+        error,
+        "An unexpected error occurred during ID token sign in"
+      );
+    }
+  }
+  // ============================================================================
+  // Session Management
+  // ============================================================================
+  /**
+   * Refresh the current auth session.
+   *
+   * Browser mode:
+   * - Uses httpOnly refresh cookie and optional CSRF header.
+   *
+   * Server mode (`isServerMode: true`):
+   * - Uses mobile auth flow and requires `refreshToken` in request body.
+   */
+  async refreshSession(options) {
+    try {
+      if (this.isServerMode() && !options?.refreshToken) {
+        return {
+          data: null,
+          error: new InsForgeError(
+            "refreshToken is required when refreshing session in server mode",
+            400,
+            "REFRESH_TOKEN_REQUIRED"
+          )
+        };
+      }
+      const csrfToken = !this.isServerMode() ? getCsrfToken() : null;
+      const response = await this.http.post(
+        this.isServerMode() ? "/api/auth/refresh?client_type=mobile" : "/api/auth/refresh",
+        this.isServerMode() ? { refresh_token: options?.refreshToken } : void 0,
+        {
+          headers: csrfToken ? { "X-CSRF-Token": csrfToken } : {},
+          credentials: "include"
+        }
+      );
+      if (response.accessToken) {
+        this.saveSessionFromResponse(response);
+      }
+      return { data: response, error: null };
+    } catch (error) {
+      return wrapError(
+        error,
+        "An unexpected error occurred during session refresh"
+      );
+    }
+  }
+  /**
+   * Get current user, automatically waits for pending OAuth callback
+   */
+  async getCurrentUser() {
+    await this.authCallbackHandled;
+    try {
+      if (this.isServerMode()) {
+        const accessToken = this.tokenManager.getAccessToken();
+        if (!accessToken) return { data: { user: null }, error: null };
+        this.http.setAuthToken(accessToken);
+        const response = await this.http.get(
+          "/api/auth/sessions/current"
+        );
+        const user = response.user ?? null;
+        return { data: { user }, error: null };
+      }
+      const session = this.tokenManager.getSession();
+      if (session) {
+        this.http.setAuthToken(session.accessToken);
+        return { data: { user: session.user }, error: null };
+      }
+      if (typeof window !== "undefined") {
+        const { data: refreshed, error: refreshError } = await this.refreshSession();
+        if (refreshError) {
+          return { data: { user: null }, error: refreshError };
+        }
+        if (refreshed?.accessToken) {
+          return { data: { user: refreshed.user ?? null }, error: null };
+        }
+      }
+      return { data: { user: null }, error: null };
+    } catch (error) {
+      if (error instanceof InsForgeError) {
+        return { data: { user: null }, error };
+      }
+      return {
+        data: { user: null },
+        error: new InsForgeError(
+          "An unexpected error occurred while getting user",
+          500,
+          "UNEXPECTED_ERROR"
+        )
+      };
+    }
+  }
+  // ============================================================================
+  // Profile Management
+  // ============================================================================
+  async getProfile(userId) {
+    try {
+      const response = await this.http.get(
+        `/api/auth/profiles/${userId}`
+      );
+      return { data: response, error: null };
+    } catch (error) {
+      return wrapError(
+        error,
+        "An unexpected error occurred while fetching user profile"
+      );
+    }
+  }
+  async setProfile(profile) {
+    try {
+      const response = await this.http.patch(
+        "/api/auth/profiles/current",
+        {
+          profile
+        }
+      );
+      const currentUser = this.tokenManager.getUser();
+      if (!this.isServerMode() && currentUser && response.profile !== void 0) {
+        this.tokenManager.setUser({
+          ...currentUser,
+          profile: response.profile
+        });
+      }
+      return { data: response, error: null };
+    } catch (error) {
+      return wrapError(
+        error,
+        "An unexpected error occurred while updating user profile"
+      );
+    }
+  }
+  // ============================================================================
+  // Email Verification
+  // ============================================================================
+  async resendVerificationEmail(request) {
+    try {
+      const response = await this.http.post("/api/auth/email/send-verification", request);
+      return { data: response, error: null };
+    } catch (error) {
+      return wrapError(
+        error,
+        "An unexpected error occurred while sending verification email"
+      );
+    }
+  }
+  async verifyEmail(request) {
+    try {
+      const response = await this.http.post(
+        this.isServerMode() ? "/api/auth/email/verify?client_type=mobile" : "/api/auth/email/verify",
+        request,
+        { credentials: "include" }
+      );
+      this.saveSessionFromResponse(response);
+      if (response.refreshToken) {
+        this.http.setRefreshToken(response.refreshToken);
+      }
+      return { data: response, error: null };
+    } catch (error) {
+      return wrapError(
+        error,
+        "An unexpected error occurred while verifying email"
+      );
+    }
+  }
+  // ============================================================================
+  // Password Reset
+  // ============================================================================
+  async sendResetPasswordEmail(request) {
+    try {
+      const response = await this.http.post("/api/auth/email/send-reset-password", request);
+      return { data: response, error: null };
+    } catch (error) {
+      return wrapError(
+        error,
+        "An unexpected error occurred while sending password reset email"
+      );
+    }
+  }
+  async exchangeResetPasswordToken(request) {
+    try {
+      const response = await this.http.post(
+        "/api/auth/email/exchange-reset-password-token",
+        request
+      );
+      return { data: response, error: null };
+    } catch (error) {
+      return wrapError(
+        error,
+        "An unexpected error occurred while verifying reset code"
+      );
+    }
+  }
+  async resetPassword(request) {
+    try {
+      const response = await this.http.post(
+        "/api/auth/email/reset-password",
+        request
+      );
+      return { data: response, error: null };
+    } catch (error) {
+      return wrapError(
+        error,
+        "An unexpected error occurred while resetting password"
+      );
+    }
+  }
+  // ============================================================================
+  // Configuration
+  // ============================================================================
+  async getPublicAuthConfig() {
+    try {
+      const response = await this.http.get(
+        "/api/auth/public-config"
+      );
+      return { data: response, error: null };
+    } catch (error) {
+      return wrapError(
+        error,
+        "An unexpected error occurred while fetching auth configuration"
+      );
+    }
+  }
+};
+
+// src/modules/database-postgrest.ts
+import { PostgrestClient } from "@supabase/postgrest-js";
+function createInsForgePostgrestFetch(httpClient, tokenManager) {
+  return async (input, init) => {
+    const url = typeof input === "string" ? input : input.toString();
+    const urlObj = new URL(url);
+    const pathname = urlObj.pathname.slice(1);
+    const rpcMatch = pathname.match(/^rpc\/(.+)$/);
+    const endpoint = rpcMatch ? `/api/database/rpc/${rpcMatch[1]}` : `/api/database/records/${pathname}`;
+    const insforgeUrl = `${httpClient.baseUrl}${endpoint}${urlObj.search}`;
+    const token = tokenManager.getAccessToken();
+    const httpHeaders = httpClient.getHeaders();
+    const authToken = token || httpHeaders["Authorization"]?.replace("Bearer ", "");
+    const headers = new Headers(init?.headers);
+    if (authToken && !headers.has("Authorization")) {
+      headers.set("Authorization", `Bearer ${authToken}`);
+    }
+    const response = await fetch(insforgeUrl, {
+      ...init,
+      headers
+    });
+    return response;
+  };
+}
+var Database = class {
+  constructor(httpClient, tokenManager) {
+    this.postgrest = new PostgrestClient("http://dummy", {
+      fetch: createInsForgePostgrestFetch(httpClient, tokenManager),
+      headers: {}
+    });
+  }
+  /**
+   * Create a query builder for a table
+   * 
+   * @example
+   * // Basic query
+   * const { data, error } = await client.database
+   *   .from('posts')
+   *   .select('*')
+   *   .eq('user_id', userId);
+   * 
+   * // With count (Supabase style!)
+   * const { data, error, count } = await client.database
+   *   .from('posts')
+   *   .select('*', { count: 'exact' })
+   *   .range(0, 9);
+   * 
+   * // Just get count, no data
+   * const { count } = await client.database
+   *   .from('posts')
+   *   .select('*', { count: 'exact', head: true });
+   * 
+   * // Complex queries with OR
+   * const { data } = await client.database
+   *   .from('posts')
+   *   .select('*, users!inner(*)')
+   *   .or('status.eq.active,status.eq.pending');
+   * 
+   * // All features work:
+   * - Nested selects
+   * - Foreign key expansion  
+   * - OR/AND/NOT conditions
+   * - Count with head
+   * - Range pagination
+   * - Upserts
+   */
+  from(table) {
+    return this.postgrest.from(table);
+  }
+  /**
+   * Call a PostgreSQL function (RPC)
+   *
+   * @example
+   * // Call a function with parameters
+   * const { data, error } = await client.database
+   *   .rpc('get_user_stats', { user_id: 123 });
+   *
+   * // Call a function with no parameters
+   * const { data, error } = await client.database
+   *   .rpc('get_all_active_users');
+   *
+   * // With options (head, count, get)
+   * const { data, count } = await client.database
+   *   .rpc('search_posts', { query: 'hello' }, { count: 'exact' });
+   */
+  rpc(fn, args, options) {
+    return this.postgrest.rpc(fn, args, options);
+  }
+};
+
+// src/modules/storage.ts
+var StorageBucket = class {
+  constructor(bucketName, http) {
+    this.bucketName = bucketName;
+    this.http = http;
+  }
+  /**
+   * Upload a file with a specific key
+   * Uses the upload strategy from backend (direct or presigned)
+   * @param path - The object key/path
+   * @param file - File or Blob to upload
+   */
+  async upload(path, file) {
+    try {
+      const strategyResponse = await this.http.post(
+        `/api/storage/buckets/${this.bucketName}/upload-strategy`,
+        {
+          filename: path,
+          contentType: file.type || "application/octet-stream",
+          size: file.size
+        }
+      );
+      if (strategyResponse.method === "presigned") {
+        return await this.uploadWithPresignedUrl(strategyResponse, file);
+      }
+      if (strategyResponse.method === "direct") {
+        const formData = new FormData();
+        formData.append("file", file);
+        const response = await this.http.request(
+          "PUT",
+          `/api/storage/buckets/${this.bucketName}/objects/${encodeURIComponent(path)}`,
+          {
+            body: formData,
+            headers: {
+              // Don't set Content-Type, let browser set multipart boundary
+            }
+          }
+        );
+        return { data: response, error: null };
+      }
+      throw new InsForgeError(
+        `Unsupported upload method: ${strategyResponse.method}`,
+        500,
+        "STORAGE_ERROR"
+      );
+    } catch (error) {
+      return {
+        data: null,
+        error: error instanceof InsForgeError ? error : new InsForgeError(
+          "Upload failed",
+          500,
+          "STORAGE_ERROR"
+        )
+      };
+    }
+  }
+  /**
+   * Upload a file with auto-generated key
+   * Uses the upload strategy from backend (direct or presigned)
+   * @param file - File or Blob to upload
+   */
+  async uploadAuto(file) {
+    try {
+      const filename = file instanceof File ? file.name : "file";
+      const strategyResponse = await this.http.post(
+        `/api/storage/buckets/${this.bucketName}/upload-strategy`,
+        {
+          filename,
+          contentType: file.type || "application/octet-stream",
+          size: file.size
+        }
+      );
+      if (strategyResponse.method === "presigned") {
+        return await this.uploadWithPresignedUrl(strategyResponse, file);
+      }
+      if (strategyResponse.method === "direct") {
+        const formData = new FormData();
+        formData.append("file", file);
+        const response = await this.http.request(
+          "POST",
+          `/api/storage/buckets/${this.bucketName}/objects`,
+          {
+            body: formData,
+            headers: {
+              // Don't set Content-Type, let browser set multipart boundary
+            }
+          }
+        );
+        return { data: response, error: null };
+      }
+      throw new InsForgeError(
+        `Unsupported upload method: ${strategyResponse.method}`,
+        500,
+        "STORAGE_ERROR"
+      );
+    } catch (error) {
+      return {
+        data: null,
+        error: error instanceof InsForgeError ? error : new InsForgeError(
+          "Upload failed",
+          500,
+          "STORAGE_ERROR"
+        )
+      };
+    }
+  }
+  /**
+   * Internal method to handle presigned URL uploads
+   */
+  async uploadWithPresignedUrl(strategy, file) {
+    try {
+      const formData = new FormData();
+      if (strategy.fields) {
+        Object.entries(strategy.fields).forEach(([key, value]) => {
+          formData.append(key, value);
+        });
+      }
+      formData.append("file", file);
+      const uploadResponse = await fetch(strategy.uploadUrl, {
+        method: "POST",
+        body: formData
+      });
+      if (!uploadResponse.ok) {
+        throw new InsForgeError(
+          `Upload to storage failed: ${uploadResponse.statusText}`,
+          uploadResponse.status,
+          "STORAGE_ERROR"
+        );
+      }
+      if (strategy.confirmRequired && strategy.confirmUrl) {
+        const confirmResponse = await this.http.post(
+          strategy.confirmUrl,
+          {
+            size: file.size,
+            contentType: file.type || "application/octet-stream"
+          }
+        );
+        return { data: confirmResponse, error: null };
+      }
+      return {
+        data: {
+          key: strategy.key,
+          bucket: this.bucketName,
+          size: file.size,
+          mimeType: file.type || "application/octet-stream",
+          uploadedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          url: this.getPublicUrl(strategy.key)
+        },
+        error: null
+      };
+    } catch (error) {
+      throw error instanceof InsForgeError ? error : new InsForgeError(
+        "Presigned upload failed",
+        500,
+        "STORAGE_ERROR"
+      );
+    }
+  }
+  /**
+   * Download a file
+   * Uses the download strategy from backend (direct or presigned)
+   * @param path - The object key/path
+   * Returns the file as a Blob
+   */
+  async download(path) {
+    try {
+      const strategyResponse = await this.http.post(
+        `/api/storage/buckets/${this.bucketName}/objects/${encodeURIComponent(path)}/download-strategy`,
+        { expiresIn: 3600 }
+      );
+      const downloadUrl = strategyResponse.url;
+      const headers = {};
+      if (strategyResponse.method === "direct") {
+        Object.assign(headers, this.http.getHeaders());
+      }
+      const response = await fetch(downloadUrl, {
+        method: "GET",
+        headers
+      });
+      if (!response.ok) {
+        try {
+          const error = await response.json();
+          throw InsForgeError.fromApiError(error);
+        } catch {
+          throw new InsForgeError(
+            `Download failed: ${response.statusText}`,
+            response.status,
+            "STORAGE_ERROR"
+          );
+        }
+      }
+      const blob = await response.blob();
+      return { data: blob, error: null };
+    } catch (error) {
+      return {
+        data: null,
+        error: error instanceof InsForgeError ? error : new InsForgeError(
+          "Download failed",
+          500,
+          "STORAGE_ERROR"
+        )
+      };
+    }
+  }
+  /**
+   * Get public URL for a file
+   * @param path - The object key/path
+   */
+  getPublicUrl(path) {
+    return `${this.http.baseUrl}/api/storage/buckets/${this.bucketName}/objects/${encodeURIComponent(path)}`;
+  }
+  /**
+   * List objects in the bucket
+   * @param prefix - Filter by key prefix
+   * @param search - Search in file names
+   * @param limit - Maximum number of results (default: 100, max: 1000)
+   * @param offset - Number of results to skip
+   */
+  async list(options) {
+    try {
+      const params = {};
+      if (options?.prefix) params.prefix = options.prefix;
+      if (options?.search) params.search = options.search;
+      if (options?.limit) params.limit = options.limit.toString();
+      if (options?.offset) params.offset = options.offset.toString();
+      const response = await this.http.get(
+        `/api/storage/buckets/${this.bucketName}/objects`,
+        { params }
+      );
+      return { data: response, error: null };
+    } catch (error) {
+      return {
+        data: null,
+        error: error instanceof InsForgeError ? error : new InsForgeError(
+          "List failed",
+          500,
+          "STORAGE_ERROR"
+        )
+      };
+    }
+  }
+  /**
+   * Delete a file
+   * @param path - The object key/path
+   */
+  async remove(path) {
+    try {
+      const response = await this.http.delete(
+        `/api/storage/buckets/${this.bucketName}/objects/${encodeURIComponent(path)}`
+      );
+      return { data: response, error: null };
+    } catch (error) {
+      return {
+        data: null,
+        error: error instanceof InsForgeError ? error : new InsForgeError(
+          "Delete failed",
+          500,
+          "STORAGE_ERROR"
+        )
+      };
+    }
+  }
+};
+var Storage = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Get a bucket instance for operations
+   * @param bucketName - Name of the bucket
+   */
+  from(bucketName) {
+    return new StorageBucket(bucketName, this.http);
+  }
+};
+
+// src/modules/ai.ts
+var AI = class {
+  constructor(http) {
+    this.http = http;
+    this.chat = new Chat(http);
+    this.images = new Images(http);
+    this.embeddings = new Embeddings(http);
+  }
+};
+var Chat = class {
+  constructor(http) {
+    this.completions = new ChatCompletions(http);
+  }
+};
+var ChatCompletions = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Create a chat completion - OpenAI-like response format
+   *
+   * @example
+   * ```typescript
+   * // Non-streaming
+   * const completion = await client.ai.chat.completions.create({
+   *   model: 'gpt-4',
+   *   messages: [{ role: 'user', content: 'Hello!' }]
+   * });
+   * console.log(completion.choices[0].message.content);
+   *
+   * // With images (OpenAI-compatible format)
+   * const response = await client.ai.chat.completions.create({
+   *   model: 'gpt-4-vision',
+   *   messages: [{
+   *     role: 'user',
+   *     content: [
+   *       { type: 'text', text: 'What is in this image?' },
+   *       { type: 'image_url', image_url: { url: 'https://example.com/image.jpg' } }
+   *     ]
+   *   }]
+   * });
+   *
+   * // With PDF files
+   * const pdfResponse = await client.ai.chat.completions.create({
+   *   model: 'anthropic/claude-3.5-sonnet',
+   *   messages: [{
+   *     role: 'user',
+   *     content: [
+   *       { type: 'text', text: 'Summarize this document' },
+   *       { type: 'file', file: { filename: 'doc.pdf', file_data: 'https://example.com/doc.pdf' } }
+   *     ]
+   *   }],
+   *   fileParser: { enabled: true, pdf: { engine: 'mistral-ocr' } }
+   * });
+   *
+   * // With web search
+   * const searchResponse = await client.ai.chat.completions.create({
+   *   model: 'openai/gpt-4',
+   *   messages: [{ role: 'user', content: 'What are the latest news about AI?' }],
+   *   webSearch: { enabled: true, maxResults: 5 }
+   * });
+   * // Access citations from response.choices[0].message.annotations
+   *
+   * // With thinking/reasoning mode (Anthropic models)
+   * const thinkingResponse = await client.ai.chat.completions.create({
+   *   model: 'anthropic/claude-3.5-sonnet',
+   *   messages: [{ role: 'user', content: 'Solve this complex math problem...' }],
+   *   thinking: true
+   * });
+   *
+   * // Streaming - returns async iterable
+   * const stream = await client.ai.chat.completions.create({
+   *   model: 'gpt-4',
+   *   messages: [{ role: 'user', content: 'Tell me a story' }],
+   *   stream: true
+   * });
+   *
+   * for await (const chunk of stream) {
+   *   if (chunk.choices[0]?.delta?.content) {
+   *     process.stdout.write(chunk.choices[0].delta.content);
+   *   }
+   * }
+   * ```
+   */
+  async create(params) {
+    const backendParams = {
+      model: params.model,
+      messages: params.messages,
+      temperature: params.temperature,
+      maxTokens: params.maxTokens,
+      topP: params.topP,
+      stream: params.stream,
+      // New plugin options
+      webSearch: params.webSearch,
+      fileParser: params.fileParser,
+      thinking: params.thinking,
+      // Tool calling options
+      tools: params.tools,
+      toolChoice: params.toolChoice,
+      parallelToolCalls: params.parallelToolCalls
+    };
+    if (params.stream) {
+      const headers = this.http.getHeaders();
+      headers["Content-Type"] = "application/json";
+      const response2 = await this.http.fetch(
+        `${this.http.baseUrl}/api/ai/chat/completion`,
+        {
+          method: "POST",
+          headers,
+          body: JSON.stringify(backendParams)
+        }
+      );
+      if (!response2.ok) {
+        const error = await response2.json();
+        throw new Error(error.error || "Stream request failed");
+      }
+      return this.parseSSEStream(response2, params.model);
+    }
+    const response = await this.http.post(
+      "/api/ai/chat/completion",
+      backendParams
+    );
+    const content = response.text || "";
+    return {
+      id: `chatcmpl-${Date.now()}`,
+      object: "chat.completion",
+      created: Math.floor(Date.now() / 1e3),
+      model: response.metadata?.model,
+      choices: [
+        {
+          index: 0,
+          message: {
+            role: "assistant",
+            content,
+            // Include tool_calls if present (from tool calling)
+            ...response.tool_calls?.length && { tool_calls: response.tool_calls },
+            // Include annotations if present (from web search or file parsing)
+            ...response.annotations?.length && { annotations: response.annotations }
+          },
+          finish_reason: response.tool_calls?.length ? "tool_calls" : "stop"
+        }
+      ],
+      usage: response.metadata?.usage || {
+        prompt_tokens: 0,
+        completion_tokens: 0,
+        total_tokens: 0
+      }
+    };
+  }
+  /**
+   * Parse SSE stream into async iterable of OpenAI-like chunks
+   */
+  async *parseSSEStream(response, model) {
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() || "";
+        for (const line of lines) {
+          if (line.startsWith("data: ")) {
+            const dataStr = line.slice(6).trim();
+            if (dataStr) {
+              try {
+                const data = JSON.parse(dataStr);
+                if (data.chunk || data.content) {
+                  yield {
+                    id: `chatcmpl-${Date.now()}`,
+                    object: "chat.completion.chunk",
+                    created: Math.floor(Date.now() / 1e3),
+                    model,
+                    choices: [
+                      {
+                        index: 0,
+                        delta: {
+                          content: data.chunk || data.content
+                        },
+                        finish_reason: null
+                      }
+                    ]
+                  };
+                }
+                if (data.tool_calls?.length) {
+                  yield {
+                    id: `chatcmpl-${Date.now()}`,
+                    object: "chat.completion.chunk",
+                    created: Math.floor(Date.now() / 1e3),
+                    model,
+                    choices: [
+                      {
+                        index: 0,
+                        delta: {
+                          tool_calls: data.tool_calls
+                        },
+                        finish_reason: "tool_calls"
+                      }
+                    ]
+                  };
+                }
+                if (data.done) {
+                  reader.releaseLock();
+                  return;
+                }
+              } catch (e) {
+                console.warn("Failed to parse SSE data:", dataStr);
+              }
+            }
+          }
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+};
+var Embeddings = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Create embeddings for text input - OpenAI-like response format
+   *
+   * @example
+   * ```typescript
+   * // Single text input
+   * const response = await client.ai.embeddings.create({
+   *   model: 'openai/text-embedding-3-small',
+   *   input: 'Hello world'
+   * });
+   * console.log(response.data[0].embedding); // number[]
+   *
+   * // Multiple text inputs
+   * const response = await client.ai.embeddings.create({
+   *   model: 'openai/text-embedding-3-small',
+   *   input: ['Hello world', 'Goodbye world']
+   * });
+   * response.data.forEach((item, i) => {
+   *   console.log(`Embedding ${i}:`, item.embedding.slice(0, 5)); // First 5 dimensions
+   * });
+   *
+   * // With custom dimensions (if supported by model)
+   * const response = await client.ai.embeddings.create({
+   *   model: 'openai/text-embedding-3-small',
+   *   input: 'Hello world',
+   *   dimensions: 256
+   * });
+   *
+   * // With base64 encoding format
+   * const response = await client.ai.embeddings.create({
+   *   model: 'openai/text-embedding-3-small',
+   *   input: 'Hello world',
+   *   encoding_format: 'base64'
+   * });
+   * ```
+   */
+  async create(params) {
+    const response = await this.http.post(
+      "/api/ai/embeddings",
+      params
+    );
+    return {
+      object: response.object,
+      data: response.data,
+      model: response.metadata?.model,
+      usage: response.metadata?.usage ? {
+        prompt_tokens: response.metadata.usage.promptTokens || 0,
+        total_tokens: response.metadata.usage.totalTokens || 0
+      } : {
+        prompt_tokens: 0,
+        total_tokens: 0
+      }
+    };
+  }
+};
+var Images = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Generate images - OpenAI-like response format
+   *
+   * @example
+   * ```typescript
+   * // Text-to-image
+   * const response = await client.ai.images.generate({
+   *   model: 'dall-e-3',
+   *   prompt: 'A sunset over mountains',
+   * });
+   * console.log(response.images[0].url);
+   *
+   * // Image-to-image (with input images)
+   * const response = await client.ai.images.generate({
+   *   model: 'stable-diffusion-xl',
+   *   prompt: 'Transform this into a watercolor painting',
+   *   images: [
+   *     { url: 'https://example.com/input.jpg' },
+   *     // or base64-encoded Data URI:
+   *     { url: 'data:image/jpeg;base64,/9j/4AAQ...' }
+   *   ]
+   * });
+   * ```
+   */
+  async generate(params) {
+    const response = await this.http.post(
+      "/api/ai/image/generation",
+      params
+    );
+    let data = [];
+    if (response.images && response.images.length > 0) {
+      data = response.images.map((img) => ({
+        b64_json: img.imageUrl.replace(/^data:image\/\w+;base64,/, ""),
+        content: response.text
+      }));
+    } else if (response.text) {
+      data = [{ content: response.text }];
+    }
+    return {
+      created: Math.floor(Date.now() / 1e3),
+      data,
+      ...response.metadata?.usage && {
+        usage: {
+          total_tokens: response.metadata.usage.totalTokens || 0,
+          input_tokens: response.metadata.usage.promptTokens || 0,
+          output_tokens: response.metadata.usage.completionTokens || 0
+        }
+      }
+    };
+  }
+};
+
+// src/modules/functions.ts
+var Functions = class _Functions {
+  constructor(http, functionsUrl) {
+    this.http = http;
+    this.functionsUrl = functionsUrl || _Functions.deriveSubhostingUrl(http.baseUrl);
+  }
+  /**
+   * Derive the subhosting URL from the base URL.
+   * Base URL pattern: https://{appKey}.{region}.insforge.app
+   * Functions URL:    https://{appKey}.functions.insforge.app
+   * Only applies to .insforge.app domains.
+   */
+  static deriveSubhostingUrl(baseUrl) {
+    try {
+      const { hostname } = new URL(baseUrl);
+      if (!hostname.endsWith(".insforge.app")) return void 0;
+      const appKey = hostname.split(".")[0];
+      return `https://${appKey}.functions.insforge.app`;
+    } catch {
+      return void 0;
+    }
+  }
+  /**
+   * Build a Request for in-process dispatch. The host is a non-routable
+   * placeholder; the router only reads pathname.
+   */
+  buildInProcessRequest(slug, method, body, callerHeaders) {
+    const url = new URL("/" + slug, "http://insforge.local").toString();
+    const headers = { ...this.http.getHeaders() };
+    const reqBody = serializeBody(method, body, headers);
+    Object.assign(headers, callerHeaders);
+    return new Request(url, {
+      method,
+      headers,
+      body: reqBody
+    });
+  }
+  /**
+   * Invoke an Edge Function.
+   *
+   * Dispatch order:
+   * 1. If `globalThis.__insforge_dispatch__` is present, call it in-process.
+   *    This avoids Deno Subhosting's 508 Loop Detected when one bundled
+   *    function invokes another inside the same deployment.
+   * 2. Otherwise, try the configured subhosting URL.
+   * 3. On 404 from subhosting, fall back to the proxy path.
+   *
+   * @param slug The function slug to invoke
+   * @param options Request options
+   */
+  async invoke(slug, options = {}) {
+    const { method = "POST", body, headers = {} } = options;
+    const dispatch = globalThis.__insforge_dispatch__;
+    const localFunctionsUrl = _Functions.deriveSubhostingUrl(this.http.baseUrl);
+    if (typeof dispatch === "function" && !!localFunctionsUrl && this.functionsUrl === localFunctionsUrl) {
+      try {
+        const req = this.buildInProcessRequest(slug, method, body, headers);
+        const res = await dispatch(req);
+        const data = await parseResponse(res);
+        return { data, error: null };
+      } catch (error) {
+        if (error instanceof Error && error.name === "AbortError") throw error;
+        return {
+          data: null,
+          error: error instanceof InsForgeError ? error : new InsForgeError(
+            error instanceof Error ? error.message : "Function invocation failed",
+            500,
+            "FUNCTION_ERROR"
+          )
+        };
+      }
+    }
+    if (this.functionsUrl) {
+      try {
+        const data = await this.http.request(method, `${this.functionsUrl}/${slug}`, {
+          body,
+          headers
+        });
+        return { data, error: null };
+      } catch (error) {
+        if (error instanceof Error && error.name === "AbortError") throw error;
+        if (error instanceof InsForgeError && error.statusCode === 404) {
+        } else {
+          return {
+            data: null,
+            error: error instanceof InsForgeError ? error : new InsForgeError(
+              error instanceof Error ? error.message : "Function invocation failed",
+              500,
+              "FUNCTION_ERROR"
+            )
+          };
+        }
+      }
+    }
+    try {
+      const path = `/functions/${slug}`;
+      const data = await this.http.request(method, path, { body, headers });
+      return { data, error: null };
+    } catch (error) {
+      if (error instanceof Error && error.name === "AbortError") throw error;
+      return {
+        data: null,
+        error: error instanceof InsForgeError ? error : new InsForgeError(
+          error instanceof Error ? error.message : "Function invocation failed",
+          500,
+          "FUNCTION_ERROR"
+        )
+      };
+    }
+  }
+};
+
+// src/modules/realtime.ts
+import { io } from "socket.io-client";
+var CONNECT_TIMEOUT = 1e4;
+var Realtime = class {
+  constructor(baseUrl, tokenManager, anonKey) {
+    this.socket = null;
+    this.connectPromise = null;
+    this.subscribedChannels = /* @__PURE__ */ new Set();
+    this.eventListeners = /* @__PURE__ */ new Map();
+    this.baseUrl = baseUrl;
+    this.tokenManager = tokenManager;
+    this.anonKey = anonKey;
+    this.tokenManager.onTokenChange = () => this.onTokenChange();
+  }
+  notifyListeners(event, payload) {
+    const listeners = this.eventListeners.get(event);
+    if (!listeners) return;
+    for (const cb of listeners) {
+      try {
+        cb(payload);
+      } catch (err) {
+        console.error(`Error in ${event} callback:`, err);
+      }
+    }
+  }
+  /**
+   * Connect to the realtime server
+   * @returns Promise that resolves when connected
+   */
+  connect() {
+    if (this.socket?.connected) {
+      return Promise.resolve();
+    }
+    if (this.connectPromise) {
+      return this.connectPromise;
+    }
+    this.connectPromise = new Promise((resolve, reject) => {
+      const token = this.tokenManager.getAccessToken() ?? this.anonKey;
+      this.socket = io(this.baseUrl, {
+        transports: ["websocket"],
+        auth: token ? { token } : void 0
+      });
+      let initialConnection = true;
+      let timeoutId = null;
+      const cleanup = () => {
+        if (timeoutId) {
+          clearTimeout(timeoutId);
+          timeoutId = null;
+        }
+      };
+      timeoutId = setTimeout(() => {
+        if (initialConnection) {
+          initialConnection = false;
+          this.connectPromise = null;
+          this.socket?.disconnect();
+          this.socket = null;
+          reject(new Error(`Connection timeout after ${CONNECT_TIMEOUT}ms`));
+        }
+      }, CONNECT_TIMEOUT);
+      this.socket.on("connect", () => {
+        cleanup();
+        for (const channel of this.subscribedChannels) {
+          this.socket.emit("realtime:subscribe", { channel });
+        }
+        this.notifyListeners("connect");
+        if (initialConnection) {
+          initialConnection = false;
+          this.connectPromise = null;
+          resolve();
+        }
+      });
+      this.socket.on("connect_error", (error) => {
+        cleanup();
+        this.notifyListeners("connect_error", error);
+        if (initialConnection) {
+          initialConnection = false;
+          this.connectPromise = null;
+          reject(error);
+        }
+      });
+      this.socket.on("disconnect", (reason) => {
+        this.notifyListeners("disconnect", reason);
+      });
+      this.socket.on("realtime:error", (error) => {
+        this.notifyListeners("error", error);
+      });
+      this.socket.onAny((event, message) => {
+        if (event === "realtime:error") return;
+        this.notifyListeners(event, message);
+      });
+    });
+    return this.connectPromise;
+  }
+  /**
+   * Disconnect from the realtime server
+   */
+  disconnect() {
+    if (this.socket) {
+      this.socket.disconnect();
+      this.socket = null;
+    }
+    this.subscribedChannels.clear();
+  }
+  /**
+   * Handle token changes (e.g., after auth refresh)
+   * Updates socket auth so reconnects use the new token
+   * If connected, triggers reconnect to apply new token immediately
+   */
+  onTokenChange() {
+    const token = this.tokenManager.getAccessToken() ?? this.anonKey;
+    if (this.socket) {
+      this.socket.auth = token ? { token } : {};
+    }
+    if (this.socket && (this.socket.connected || this.connectPromise)) {
+      this.socket.disconnect();
+      this.socket.connect();
+    }
+  }
+  /**
+   * Check if connected to the realtime server
+   */
+  get isConnected() {
+    return this.socket?.connected ?? false;
+  }
+  /**
+   * Get the current connection state
+   */
+  get connectionState() {
+    if (!this.socket) return "disconnected";
+    if (this.socket.connected) return "connected";
+    return "connecting";
+  }
+  /**
+   * Get the socket ID (if connected)
+   */
+  get socketId() {
+    return this.socket?.id;
+  }
+  /**
+   * Subscribe to a channel
+   *
+   * Automatically connects if not already connected.
+   *
+   * @param channel - Channel name (e.g., 'orders:123', 'broadcast')
+   * @returns Promise with the subscription response
+   */
+  async subscribe(channel) {
+    if (this.subscribedChannels.has(channel)) {
+      return { ok: true, channel };
+    }
+    if (!this.socket?.connected) {
+      try {
+        await this.connect();
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Connection failed";
+        return { ok: false, channel, error: { code: "CONNECTION_FAILED", message } };
+      }
+    }
+    return new Promise((resolve) => {
+      this.socket.emit("realtime:subscribe", { channel }, (response) => {
+        if (response.ok) {
+          this.subscribedChannels.add(channel);
+        }
+        resolve(response);
+      });
+    });
+  }
+  /**
+   * Unsubscribe from a channel (fire-and-forget)
+   *
+   * @param channel - Channel name to unsubscribe from
+   */
+  unsubscribe(channel) {
+    this.subscribedChannels.delete(channel);
+    if (this.socket?.connected) {
+      this.socket.emit("realtime:unsubscribe", { channel });
+    }
+  }
+  /**
+   * Publish a message to a channel
+   *
+   * @param channel - Channel name
+   * @param event - Event name
+   * @param payload - Message payload
+   */
+  async publish(channel, event, payload) {
+    if (!this.socket?.connected) {
+      throw new Error("Not connected to realtime server. Call connect() first.");
+    }
+    this.socket.emit("realtime:publish", { channel, event, payload });
+  }
+  /**
+   * Listen for events
+   *
+   * Reserved event names:
+   * - 'connect' - Fired when connected to the server
+   * - 'connect_error' - Fired when connection fails (payload: Error)
+   * - 'disconnect' - Fired when disconnected (payload: reason string)
+   * - 'error' - Fired when a realtime error occurs (payload: RealtimeErrorPayload)
+   *
+   * All other events receive a `SocketMessage` payload with metadata.
+   *
+   * @param event - Event name to listen for
+   * @param callback - Callback function when event is received
+   */
+  on(event, callback) {
+    if (!this.eventListeners.has(event)) {
+      this.eventListeners.set(event, /* @__PURE__ */ new Set());
+    }
+    this.eventListeners.get(event).add(callback);
+  }
+  /**
+   * Remove a listener for a specific event
+   *
+   * @param event - Event name
+   * @param callback - The callback function to remove
+   */
+  off(event, callback) {
+    const listeners = this.eventListeners.get(event);
+    if (listeners) {
+      listeners.delete(callback);
+      if (listeners.size === 0) {
+        this.eventListeners.delete(event);
+      }
+    }
+  }
+  /**
+   * Listen for an event only once, then automatically remove the listener
+   *
+   * @param event - Event name to listen for
+   * @param callback - Callback function when event is received
+   */
+  once(event, callback) {
+    const wrapper = (payload) => {
+      this.off(event, wrapper);
+      callback(payload);
+    };
+    this.on(event, wrapper);
+  }
+  /**
+   * Get all currently subscribed channels
+   *
+   * @returns Array of channel names
+   */
+  getSubscribedChannels() {
+    return Array.from(this.subscribedChannels);
+  }
+};
+
+// src/modules/email.ts
+var Emails = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Send a custom HTML email
+   * @param options Email options including recipients, subject, and HTML content
+   */
+  async send(options) {
+    try {
+      const data = await this.http.post(
+        "/api/email/send-raw",
+        options
+      );
+      return { data, error: null };
+    } catch (error) {
+      if (error instanceof Error && error.name === "AbortError") throw error;
+      return {
+        data: null,
+        error: error instanceof InsForgeError ? error : new InsForgeError(
+          error instanceof Error ? error.message : "Email send failed",
+          500,
+          "EMAIL_ERROR"
+        )
+      };
+    }
+  }
+};
+
+// src/client.ts
+var InsForgeClient = class {
+  constructor(config = {}) {
+    const logger = new Logger(config.debug);
+    this.tokenManager = new TokenManager();
+    this.http = new HttpClient(config, this.tokenManager, logger);
+    if (config.edgeFunctionToken) {
+      this.http.setAuthToken(config.edgeFunctionToken);
+      this.tokenManager.setAccessToken(config.edgeFunctionToken);
+    }
+    this.auth = new Auth(this.http, this.tokenManager, {
+      isServerMode: config.isServerMode ?? false
+    });
+    this.database = new Database(this.http, this.tokenManager);
+    this.storage = new Storage(this.http);
+    this.ai = new AI(this.http);
+    this.functions = new Functions(this.http, config.functionsUrl);
+    this.realtime = new Realtime(
+      this.http.baseUrl,
+      this.tokenManager,
+      config.anonKey
+    );
+    this.emails = new Emails(this.http);
+  }
+  /**
+   * Get the underlying HTTP client for custom requests
+   *
+   * @example
+   * ```typescript
+   * const httpClient = client.getHttpClient();
+   * const customData = await httpClient.get('/api/custom-endpoint');
+   * ```
+   */
+  getHttpClient() {
+    return this.http;
+  }
+  /**
+   * Future modules will be added here:
+   * - database: Database operations
+   * - storage: File storage operations
+   * - functions: Serverless functions
+   * - tables: Table management
+   * - metadata: Backend metadata
+   */
+};
+
+// src/index.ts
+function createClient(config) {
+  return new InsForgeClient(config);
+}
+var index_default = InsForgeClient;
+export {
+  AI,
+  Auth,
+  Database,
+  Emails,
+  Functions,
+  HttpClient,
+  InsForgeClient,
+  InsForgeError,
+  Logger,
+  Realtime,
+  Storage,
+  StorageBucket,
+  TokenManager,
+  createClient,
+  index_default as default
+};
+//# sourceMappingURL=index.mjs.map