@volcano.dev/sdk 1.2.0-nightly.22454064035.1

package/dist/index.js

@@ -0,0 +1,2912 @@
+(function (global, factory) {
+  typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports) :
+  typeof define === 'function' && define.amd ? define(['exports'], factory) :
+  (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.VolcanoAuth = {}));
+})(this, (function (exports) { 'use strict';
+
+  /**
+   * Volcano Auth SDK - Official JavaScript client for Volcano Hosting
+   *
+   * @example
+   * ```javascript
+   * import { VolcanoAuth } from '@volcano.dev/sdk';
+   *
+   * // Basic usage (uses https://api.volcano.dev by default)
+   * const volcano = new VolcanoAuth({
+   *   anonKey: 'your-anon-key'
+   * });
+   *
+   * // Or with custom API URL
+   * const volcano = new VolcanoAuth({
+   *   apiUrl: 'https://api.yourapp.com',
+   *   anonKey: 'your-anon-key'
+   * });
+   *
+   * // Sign up
+   * const { user, session } = await volcano.auth.signUp({
+   *   email: 'user@example.com',
+   *   password: 'password123'
+   * });
+   *
+   * // Sign in
+   * const { user, session } = await volcano.auth.signIn({
+   *   email: 'user@example.com',
+   *   password: 'password123'
+   * });
+   *
+   * // Invoke function
+   * const result = await volcano.functions.invoke('my-function', {
+   *   action: 'getData'
+   * });
+   * ```
+   */
+
+  // ============================================================================
+  // Constants
+  // ============================================================================
+
+  const DEFAULT_API_URL = 'https://api.volcano.dev';
+  const DEFAULT_TIMEOUT_MS = 60000; // 60 seconds
+  const DEFAULT_UPLOAD_PART_SIZE = 25 * 1024 * 1024; // 25MB
+  const DEFAULT_SESSIONS_LIMIT = 20;
+  const STORAGE_KEY_ACCESS_TOKEN = 'volcano_access_token';
+  const STORAGE_KEY_REFRESH_TOKEN = 'volcano_refresh_token';
+  const FUNCTION_HOST_LABEL_REGEX = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+  const DEFAULT_FUNCTION_NEGATIVE_RESOLVE_TTL_SECONDS = 30;
+  const GLOBAL_FUNCTION_RESOLVE_STATE_KEY = '__VOLCANO_SDK_FUNCTION_RESOLVE_STATE_V1__';
+  const DEFAULT_FUNCTION_RESOLVE_CACHE_MAX_ENTRIES = 1024;
+  const FUNCTION_RESOLVE_CACHE_PRUNE_INTERVAL_MS = 5000;
+
+  // ============================================================================
+  // Utility Functions
+  // ============================================================================
+
+  /**
+   * Detect if we're running in a browser/client-side environment.
+   */
+  function isBrowser() {
+    return typeof window !== 'undefined' && typeof window.document !== 'undefined';
+  }
+
+  /**
+   * Basic provider name sanitization - only alphanumeric and hyphens allowed
+   * This is NOT validation (backend validates), just prevents URL injection
+   * @param {string} provider - The provider name
+   * @throws {Error} If provider contains invalid characters
+   */
+  function sanitizeProvider(provider) {
+    if (!provider || typeof provider !== 'string' || !/^[a-z0-9-]+$/.test(provider)) {
+      throw new Error('Provider must be a non-empty string containing only lowercase letters, numbers, and hyphens');
+    }
+  }
+
+  /**
+   * Fetch with timeout using AbortController
+   * @param {string} url - The URL to fetch
+   * @param {RequestInit} options - Fetch options
+   * @param {number} [timeoutMs] - Timeout in milliseconds (default: 60000)
+   * @returns {Promise<Response>}
+   */
+  async function fetchWithTimeout(url, options = {}, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+    try {
+      const response = await fetch(url, {
+        ...options,
+        signal: controller.signal
+      });
+      return response;
+    } catch (error) {
+      if (error.name === 'AbortError') {
+        throw new Error(`Request timeout after ${timeoutMs}ms`);
+      }
+      throw error;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  /**
+   * Safely parse JSON from response, returns empty object on failure
+   * @param {Response} response
+   * @returns {Promise<Object>}
+   */
+  async function safeJsonParse(response) {
+    try {
+      return await response.json();
+    } catch {
+      return {};
+    }
+  }
+
+  /**
+   * Decode a base64url string to UTF-8 (JWT-safe, Node/browser compatible)
+   * @param {string} value
+   * @returns {string}
+   */
+  function decodeBase64Url(value) {
+    const normalized = value.replace(/-/g, '+').replace(/_/g, '/');
+    const padding = normalized.length % 4 === 0 ? '' : '='.repeat(4 - (normalized.length % 4));
+    const base64 = normalized + padding;
+
+    if (typeof atob === 'function') {
+      return atob(base64);
+    }
+
+    if (typeof Buffer !== 'undefined') {
+      return Buffer.from(base64, 'base64').toString('utf-8');
+    }
+
+    throw new Error('No base64 decoder available');
+  }
+
+  function getSharedRuntimeObject() {
+    if (typeof globalThis !== 'undefined') {
+      return globalThis;
+    }
+    if (typeof window !== 'undefined') {
+      return window;
+    }
+    if (typeof global !== 'undefined') {
+      return global;
+    }
+    return {};
+  }
+
+  function getSharedFunctionResolveState() {
+    const runtime = getSharedRuntimeObject();
+    if (!runtime[GLOBAL_FUNCTION_RESOLVE_STATE_KEY]) {
+      runtime[GLOBAL_FUNCTION_RESOLVE_STATE_KEY] = {
+        cache: new Map(),
+        inFlight: new Map(),
+        maxEntries: DEFAULT_FUNCTION_RESOLVE_CACHE_MAX_ENTRIES,
+        lastPruneAtMs: 0
+      };
+    }
+    return runtime[GLOBAL_FUNCTION_RESOLVE_STATE_KEY];
+  }
+
+  function pruneFunctionResolveCache(state, nowMs = Date.now(), force = false) {
+    if (!force && (nowMs - state.lastPruneAtMs) < FUNCTION_RESOLVE_CACHE_PRUNE_INTERVAL_MS) {
+      return;
+    }
+    state.lastPruneAtMs = nowMs;
+
+    for (const [key, value] of state.cache.entries()) {
+      if (!value || typeof value.expiresAt !== 'number' || value.expiresAt <= nowMs) {
+        state.cache.delete(key);
+      }
+    }
+
+    if (state.cache.size <= state.maxEntries) {
+      return;
+    }
+
+    const sortedByExpiry = Array.from(state.cache.entries())
+      .sort((a, b) => (a[1].expiresAt || 0) - (b[1].expiresAt || 0));
+    const overflowCount = state.cache.size - state.maxEntries;
+    for (let i = 0; i < overflowCount; i += 1) {
+      state.cache.delete(sortedByExpiry[i][0]);
+    }
+  }
+
+  function clearSharedFunctionResolveStateForTests() {
+    const state = getSharedFunctionResolveState();
+    state.cache.clear();
+    state.inFlight.clear();
+    state.maxEntries = DEFAULT_FUNCTION_RESOLVE_CACHE_MAX_ENTRIES;
+    state.lastPruneAtMs = 0;
+  }
+
+  function extractRequiredProjectIdFromToken(token) {
+    if (!token || typeof token !== 'string') {
+      throw new Error('No active session');
+    }
+    const parts = token.split('.');
+    if (parts.length !== 3) {
+      throw new Error('accessToken must be a JWT with project_id claim');
+    }
+    let payload;
+    try {
+      payload = JSON.parse(decodeBase64Url(parts[1]));
+    } catch {
+      throw new Error('accessToken must be a valid JWT with project_id claim');
+    }
+    if (!payload || typeof payload.project_id !== 'string' || payload.project_id.trim() === '') {
+      throw new Error('accessToken missing project_id claim');
+    }
+    return payload.project_id.trim();
+  }
+
+  function isIPv4Address(hostname) {
+    return /^(?:\d{1,3}\.){3}\d{1,3}$/.test(hostname);
+  }
+
+  function isIPv6Address(hostname) {
+    return hostname.includes(':');
+  }
+
+  function isIPAddress(hostname) {
+    return isIPv4Address(hostname) || isIPv6Address(hostname);
+  }
+
+  function sanitizeFunctionIdentifierForHost(identifier) {
+    if (!identifier || typeof identifier !== 'string') {
+      return null;
+    }
+
+    const trimmed = identifier.trim();
+    if (!trimmed) {
+      return null;
+    }
+
+    // DNS host labels are case-insensitive; preserve exact behavior by requiring lowercase.
+    if (trimmed !== trimmed.toLowerCase()) {
+      return null;
+    }
+
+    if (!FUNCTION_HOST_LABEL_REGEX.test(trimmed)) {
+      return null;
+    }
+
+    return trimmed;
+  }
+
+  function resolveFunctionInvocationBase(apiUrl) {
+    try {
+      const parsed = new URL(apiUrl);
+      const hostname = parsed.hostname.toLowerCase();
+
+      // Default mapping:
+      // api.volcano.dev -> functions.volcano.dev
+      // api.staging.volcano.dev -> functions.staging.volcano.dev
+      if (hostname === 'localhost' || isIPAddress(hostname)) {
+        return {
+          protocol: parsed.protocol,
+          port: parsed.port,
+          domain: 'functions.local.volcano.dev'
+        };
+      }
+
+      if (!hostname.startsWith('api.')) {
+        return null;
+      }
+
+      const suffix = hostname.slice(4);
+      if (!suffix || isIPAddress(suffix)) {
+        return null;
+      }
+
+      return {
+        protocol: parsed.protocol,
+        port: parsed.port,
+        domain: `functions.${suffix}`
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Fetch with auth header and refresh retry on 401
+   * @param {VolcanoAuth} volcanoAuth
+   * @param {string} url
+   * @param {RequestInit} options
+   * @returns {Promise<Response>}
+   */
+  async function fetchWithAuthRetry(volcanoAuth, url, options = {}) {
+    const doFetch = () => fetchWithTimeout(
+      url,
+      {
+        ...options,
+        headers: {
+          'Authorization': `Bearer ${volcanoAuth.accessToken}`,
+          ...options.headers
+        }
+      },
+      volcanoAuth.timeout
+    );
+
+    let response = await doFetch();
+    if (response.status === 401) {
+      const refreshed = await volcanoAuth.refreshSession();
+      if (!refreshed.error) {
+        response = await doFetch();
+      }
+    }
+
+    return response;
+  }
+
+  /**
+   * Create an error result object
+   * @param {string} message - Error message
+   * @param {Object} [extra] - Extra fields to include
+   * @returns {Object}
+   */
+  function errorResult(message, extra = {}) {
+    return { data: null, error: new Error(message), ...extra };
+  }
+
+  // ============================================================================
+  // VolcanoAuth Class
+  // ============================================================================
+
+  class VolcanoAuth {
+    constructor(config) {
+      if (!config.anonKey) {
+        throw new Error('anonKey is required. Get your anon key from project settings.');
+      }
+
+      // SECURITY: Throw hard error if service key is used client-side
+      if (config.anonKey.startsWith('sk-') && isBrowser()) {
+        throw new Error(
+          '[VOLCANO SECURITY ERROR] Service keys (sk-*) cannot be used in client-side code. ' +
+          'Service keys bypass Row Level Security and expose your database to unauthorized access. ' +
+          'Use an anon key (ak-*) for browser/client-side applications. ' +
+          'Service keys should only be used in secure server-side environments. ' +
+          'See: https://docs.volcano.hosting/security/keys'
+        );
+      }
+
+      this.apiUrl = (config.apiUrl || DEFAULT_API_URL).replace(/\/$/, ''); // Remove trailing slash
+      this.functionInvocationBase = resolveFunctionInvocationBase(this.apiUrl);
+      this.anonKey = config.anonKey;
+      this.timeout = config.timeout || DEFAULT_TIMEOUT_MS;
+      this._currentDatabaseName = null;
+      this.currentUser = null;
+      this._functionResolveState = getSharedFunctionResolveState();
+
+      // Server-side use: Allow passing accessToken directly (e.g., in Lambda functions)
+      if (config.accessToken) {
+        this.accessToken = config.accessToken;
+        this.refreshToken = config.refreshToken || null;
+      } else {
+        // Client-side use: Restore from localStorage if available
+        this.accessToken = this._getStorageItem(STORAGE_KEY_ACCESS_TOKEN);
+        this.refreshToken = this._getStorageItem(STORAGE_KEY_REFRESH_TOKEN);
+      }
+
+      // Sub-objects for organization
+      this.auth = {
+        signUp: this.signUp.bind(this),
+        signIn: this.signIn.bind(this),
+        signOut: this.signOut.bind(this),
+        getUser: this.getUser.bind(this),
+        updateUser: this.updateUser.bind(this),
+        refreshSession: this.refreshSession.bind(this),
+        onAuthStateChange: this.onAuthStateChange.bind(this),
+        user: () => this.currentUser,
+        // Anonymous user methods
+        signUpAnonymous: this.signUpAnonymous.bind(this),
+        convertAnonymous: this.convertAnonymous.bind(this),
+        // Email confirmation methods
+        confirmEmail: this.confirmEmail.bind(this),
+        resendConfirmation: this.resendConfirmation.bind(this),
+        // Password recovery methods
+        forgotPassword: this.forgotPassword.bind(this),
+        resetPassword: this.resetPassword.bind(this),
+        // Email change methods
+        requestEmailChange: this.requestEmailChange.bind(this),
+        confirmEmailChange: this.confirmEmailChange.bind(this),
+        cancelEmailChange: this.cancelEmailChange.bind(this),
+        // OAuth methods
+        signInWithOAuth: this.signInWithOAuth.bind(this),
+        signInWithGoogle: this.signInWithGoogle.bind(this),
+        signInWithGitHub: this.signInWithGitHub.bind(this),
+        signInWithMicrosoft: this.signInWithMicrosoft.bind(this),
+        signInWithApple: this.signInWithApple.bind(this),
+        linkOAuthProvider: this.linkOAuthProvider.bind(this),
+        unlinkOAuthProvider: this.unlinkOAuthProvider.bind(this),
+        getLinkedOAuthProviders: this.getLinkedOAuthProviders.bind(this),
+        refreshOAuthToken: this.refreshOAuthToken.bind(this),
+        getOAuthProviderToken: this.getOAuthProviderToken.bind(this),
+        callOAuthAPI: this.callOAuthAPI.bind(this),
+        // Session management methods
+        getSessions: this.getSessions.bind(this),
+        deleteSession: this.deleteSession.bind(this),
+        deleteAllOtherSessions: this.deleteAllOtherSessions.bind(this)
+      };
+
+      this.functions = {
+        invoke: this.invokeFunction.bind(this)
+      };
+
+      this.storage = {
+        from: this.storageBucket.bind(this)
+      };
+    }
+
+    // ========================================================================
+    // Storage Methods
+    // ========================================================================
+
+    /**
+     * Select a storage bucket to perform operations on
+     * @param {string} bucketName - The name of the bucket
+     * @returns {StorageFileApi} - Storage file API for the bucket
+     */
+    storageBucket(bucketName) {
+      return new StorageFileApi(this, bucketName);
+    }
+
+    // ========================================================================
+    // Internal Fetch Helpers
+    // ========================================================================
+
+    /**
+     * Make an authenticated request with access token
+     * @private
+     */
+    async _authFetch(path, options = {}) {
+      if (!this.accessToken) {
+        return { ok: false, status: null, error: new Error('No active session'), data: null };
+      }
+
+      return this._authFetchUrl(`${this.apiUrl}${path}`, options);
+    }
+
+    async _authFetchUrl(url, options = {}) {
+      if (!this.accessToken) {
+        return { ok: false, status: null, error: new Error('No active session'), data: null };
+      }
+
+      try {
+        const response = await fetchWithTimeout(
+          url,
+          {
+            ...options,
+            headers: {
+              'Authorization': `Bearer ${this.accessToken}`,
+              'Content-Type': 'application/json',
+              ...options.headers
+            }
+          },
+          this.timeout
+        );
+
+        const data = await safeJsonParse(response);
+
+        if (!response.ok) {
+          // Try token refresh on 401
+          if (response.status === 401 && !options._retried) {
+            const refreshed = await this.refreshSession();
+            if (!refreshed.error) {
+              return this._authFetchUrl(url, { ...options, _retried: true });
+            }
+            return { ok: false, status: response.status, error: new Error('Session expired'), data };
+          }
+          return { ok: false, status: response.status, error: new Error(data.error || 'Request failed'), data };
+        }
+
+        return { ok: true, status: response.status, data, error: null };
+      } catch (error) {
+        return { ok: false, status: null, error: error instanceof Error ? error : new Error('Request failed'), data: null };
+      }
+    }
+
+    _getFunctionInvokeUrl(functionIdentifier) {
+      const hostLabel = sanitizeFunctionIdentifierForHost(functionIdentifier);
+      if (!hostLabel) {
+        throw new Error('functionId must be DNS-safe: lowercase letters, numbers, hyphens, 1-63 chars');
+      }
+
+      if (!this.functionInvocationBase) {
+        throw new Error('apiUrl must be api.<domain> (or localhost/IP for local mode) to use DNS function invocation');
+      }
+
+      const portSegment = this.functionInvocationBase.port ? `:${this.functionInvocationBase.port}` : '';
+      return `${this.functionInvocationBase.protocol}//${hostLabel}.${this.functionInvocationBase.domain}${portSegment}/`;
+    }
+
+    _functionResolveCacheKey(functionName) {
+      const projectScope = extractRequiredProjectIdFromToken(this.accessToken);
+      const tokenScope = this.accessToken;
+      return `${this.apiUrl}|project:${projectScope}|token:${tokenScope}|${functionName}`;
+    }
+
+    _clearFunctionResolveCache(functionName) {
+      const cacheKey = this._functionResolveCacheKey(functionName);
+      this._functionResolveState.cache.delete(cacheKey);
+      this._functionResolveState.inFlight.delete(cacheKey);
+    }
+
+    async _resolveFunctionIdByName(functionName) {
+      const hostLabel = sanitizeFunctionIdentifierForHost(functionName);
+      if (!hostLabel) {
+        throw new Error('functionName must be DNS-safe: lowercase letters, numbers, hyphens, 1-63 chars');
+      }
+
+      const cacheKey = this._functionResolveCacheKey(hostLabel);
+      const now = Date.now();
+      pruneFunctionResolveCache(this._functionResolveState, now);
+      const cached = this._functionResolveState.cache.get(cacheKey);
+      if (cached && cached.expiresAt > now) {
+        if (cached.error) {
+          throw new Error(cached.error);
+        }
+        return cached.functionId;
+      }
+      if (cached) {
+        this._functionResolveState.cache.delete(cacheKey);
+      }
+
+      const inFlight = this._functionResolveState.inFlight.get(cacheKey);
+      if (inFlight) {
+        return inFlight;
+      }
+
+      const pending = (async () => {
+        const resolvePath = `/functions/resolve?name=${encodeURIComponent(hostLabel)}`;
+        const result = await this._authFetch(resolvePath, { method: 'GET' });
+        if (!result.ok) {
+          if (result.status === 404) {
+            this._functionResolveState.cache.set(cacheKey, {
+              functionId: null,
+              error: 'function not found',
+              expiresAt: Date.now() + (DEFAULT_FUNCTION_NEGATIVE_RESOLVE_TTL_SECONDS * 1000)
+            });
+            pruneFunctionResolveCache(this._functionResolveState, Date.now(), true);
+          }
+          throw result.error || new Error('Failed to resolve function');
+        }
+
+        const resolvedId = sanitizeFunctionIdentifierForHost(result.data && result.data.function_id);
+        if (!resolvedId) {
+          throw new Error('Resolve response missing valid function_id');
+        }
+
+        const ttlRaw = Number(result.data && result.data.cache_ttl_seconds);
+        if (!Number.isFinite(ttlRaw) || ttlRaw <= 0) {
+          throw new Error('Resolve response missing valid cache_ttl_seconds');
+        }
+        const ttlSeconds = ttlRaw;
+
+        this._functionResolveState.cache.set(cacheKey, {
+          functionId: resolvedId,
+          error: null,
+          expiresAt: Date.now() + (ttlSeconds * 1000)
+        });
+        pruneFunctionResolveCache(this._functionResolveState, Date.now(), true);
+        return resolvedId;
+      })();
+
+      this._functionResolveState.inFlight.set(cacheKey, pending);
+      try {
+        return await pending;
+      } finally {
+        this._functionResolveState.inFlight.delete(cacheKey);
+      }
+    }
+
+    /**
+     * Make a public request with anon key
+     * @private
+     */
+    async _anonFetch(path, options = {}) {
+      try {
+        const response = await fetchWithTimeout(
+          `${this.apiUrl}${path}`,
+          {
+            ...options,
+            headers: {
+              'Authorization': `Bearer ${this.anonKey}`,
+              'Content-Type': 'application/json',
+              ...options.headers
+            }
+          },
+          this.timeout
+        );
+
+        const data = await safeJsonParse(response);
+
+        if (!response.ok) {
+          return { ok: false, error: new Error(data.error || 'Request failed'), data };
+        }
+
+        return { ok: true, data, error: null };
+      } catch (error) {
+        return { ok: false, error: error instanceof Error ? error : new Error('Request failed'), data: null };
+      }
+    }
+
+    // ========================================================================
+    // Query Builder Methods
+    // ========================================================================
+
+    from(table) {
+      return new QueryBuilder(this, table, this._currentDatabaseName);
+    }
+
+    database(databaseName) {
+      this._currentDatabaseName = databaseName;
+      return this;
+    }
+
+    insert(table, values) {
+      return new MutationBuilder(this, table, this._currentDatabaseName, 'insert', values);
+    }
+
+    update(table, values) {
+      return new MutationBuilder(this, table, this._currentDatabaseName, 'update', values);
+    }
+
+    delete(table) {
+      return new MutationBuilder(this, table, this._currentDatabaseName, 'delete', null);
+    }
+
+    // ========================================================================
+    // Authentication Methods
+    // ========================================================================
+
+    async signUp({ email, password, metadata = {} }) {
+      const result = await this._anonFetch('/auth/signup', {
+        method: 'POST',
+        body: JSON.stringify({ email, password, user_metadata: metadata })
+      });
+
+      if (!result.ok) {
+        return { user: null, session: null, error: result.error };
+      }
+
+      this._setSession(result.data);
+      return {
+        user: result.data.user,
+        session: {
+          access_token: result.data.access_token,
+          refresh_token: result.data.refresh_token,
+          expires_in: result.data.expires_in
+        },
+        error: null
+      };
+    }
+
+    async signIn({ email, password }) {
+      const result = await this._anonFetch('/auth/signin', {
+        method: 'POST',
+        body: JSON.stringify({ email, password })
+      });
+
+      if (!result.ok) {
+        return { user: null, session: null, error: result.error };
+      }
+
+      this._setSession(result.data);
+      return {
+        user: result.data.user,
+        session: {
+          access_token: result.data.access_token,
+          refresh_token: result.data.refresh_token,
+          expires_in: result.data.expires_in
+        },
+        error: null
+      };
+    }
+
+    async signOut() {
+      if (this.refreshToken) {
+        try {
+          await this._anonFetch('/auth/logout', {
+            method: 'POST',
+            body: JSON.stringify({ refresh_token: this.refreshToken })
+          });
+        } catch (err) {
+          console.warn('[VolcanoAuth] Logout request failed:', err.message);
+        }
+      }
+      this._clearSession();
+      return { error: null };
+    }
+
+    async getUser() {
+      const result = await this._authFetch('/auth/user');
+
+      if (!result.ok) {
+        return { user: null, error: result.error };
+      }
+
+      this.currentUser = result.data.user;
+      return { user: result.data.user, error: null };
+    }
+
+    async updateUser({ password, metadata }) {
+      const result = await this._authFetch('/auth/user', {
+        method: 'PUT',
+        body: JSON.stringify({ password, user_metadata: metadata })
+      });
+
+      if (!result.ok) {
+        return { user: null, error: result.error };
+      }
+
+      this.currentUser = result.data.user;
+      return { user: result.data.user, error: null };
+    }
+
+    async refreshSession() {
+      if (!this.refreshToken) {
+        return { session: null, error: new Error('No refresh token') };
+      }
+
+      try {
+        const result = await this._anonFetch('/auth/refresh', {
+          method: 'POST',
+          body: JSON.stringify({ refresh_token: this.refreshToken })
+        });
+
+        if (!result.ok) {
+          this._clearSession();
+          return { session: null, error: result.error };
+        }
+
+        this._setSession(result.data);
+        return {
+          session: {
+            access_token: result.data.access_token,
+            refresh_token: result.data.refresh_token,
+            expires_in: result.data.expires_in
+          },
+          error: null
+        };
+      } catch (error) {
+        this._clearSession();
+        return { session: null, error: error instanceof Error ? error : new Error('Refresh failed') };
+      }
+    }
+
+    /**
+     * Register a callback for auth state changes.
+     * @param {Function} callback - Called with user object (or null) on auth state change
+     * @returns {Function} Unsubscribe function
+     */
+    onAuthStateChange(callback) {
+      if (!this._authCallbacks) {
+        this._authCallbacks = [];
+      }
+      this._authCallbacks.push(callback);
+
+      // Call immediately with current state
+      try {
+        callback(this.currentUser);
+      } catch (err) {
+        console.error('[VolcanoAuth] Error in auth state callback:', err);
+      }
+
+      return () => {
+        this._authCallbacks = this._authCallbacks.filter(cb => cb !== callback);
+      };
+    }
+
+    // ========================================================================
+    // Anonymous User Methods
+    // ========================================================================
+
+    async signUpAnonymous(metadata = {}) {
+      const result = await this._anonFetch('/auth/signup-anonymous', {
+        method: 'POST',
+        body: JSON.stringify({ user_metadata: metadata })
+      });
+
+      if (!result.ok) {
+        return { user: null, session: null, error: result.error };
+      }
+
+      this._setSession(result.data);
+      return {
+        user: result.data.user,
+        session: {
+          access_token: result.data.access_token,
+          refresh_token: result.data.refresh_token,
+          expires_in: result.data.expires_in
+        },
+        error: null
+      };
+    }
+
+    async convertAnonymous({ email, password, metadata = {} }) {
+      const result = await this._authFetch('/auth/user/convert-anonymous', {
+        method: 'POST',
+        body: JSON.stringify({ email, password, user_metadata: metadata })
+      });
+
+      if (!result.ok) {
+        return { user: null, error: result.error };
+      }
+
+      this.currentUser = result.data.user;
+      return { user: result.data.user, error: null };
+    }
+
+    // ========================================================================
+    // Email Confirmation Methods
+    // ========================================================================
+
+    async confirmEmail(token) {
+      const result = await this._anonFetch('/auth/confirm', {
+        method: 'POST',
+        body: JSON.stringify({ token })
+      });
+
+      if (!result.ok) {
+        return { message: null, error: result.error };
+      }
+      return { message: result.data.message, error: null };
+    }
+
+    async resendConfirmation(email) {
+      const result = await this._anonFetch('/auth/resend-confirmation', {
+        method: 'POST',
+        body: JSON.stringify({ email })
+      });
+
+      if (!result.ok) {
+        return { message: null, error: result.error };
+      }
+      return { message: result.data.message, error: null };
+    }
+
+    // ========================================================================
+    // Password Recovery Methods
+    // ========================================================================
+
+    async forgotPassword(email) {
+      const result = await this._anonFetch('/auth/forgot-password', {
+        method: 'POST',
+        body: JSON.stringify({ email })
+      });
+
+      if (!result.ok) {
+        return { message: null, error: result.error };
+      }
+      return { message: result.data.message, error: null };
+    }
+
+    async resetPassword({ token, newPassword }) {
+      const result = await this._anonFetch('/auth/reset-password', {
+        method: 'POST',
+        body: JSON.stringify({ token, new_password: newPassword })
+      });
+
+      if (!result.ok) {
+        return { message: null, error: result.error };
+      }
+      return { message: result.data.message, error: null };
+    }
+
+    // ========================================================================
+    // Email Change Methods
+    // ========================================================================
+
+    async requestEmailChange(newEmail) {
+      const result = await this._authFetch('/auth/user/change-email', {
+        method: 'POST',
+        body: JSON.stringify({ new_email: newEmail })
+      });
+
+      if (!result.ok) {
+        return { message: null, newEmail: null, error: result.error };
+      }
+      return {
+        message: result.data.message,
+        newEmail: result.data.new_email,
+        emailChangeToken: result.data.email_change_token,
+        error: null
+      };
+    }
+
+    async confirmEmailChange(emailChangeToken) {
+      const result = await this._authFetch('/auth/user/confirm-email-change', {
+        method: 'POST',
+        body: JSON.stringify({ email_change_token: emailChangeToken })
+      });
+
+      if (!result.ok) {
+        return { user: null, error: result.error };
+      }
+
+      this.currentUser = result.data.user;
+      return { user: result.data.user, error: null };
+    }
+
+    async cancelEmailChange() {
+      const result = await this._authFetch('/auth/user/cancel-email-change', {
+        method: 'DELETE'
+      });
+
+      if (!result.ok) {
+        return { message: null, error: result.error };
+      }
+      return { message: result.data.message, error: null };
+    }
+
+    // ========================================================================
+    // OAuth / SSO Authentication
+    // ========================================================================
+
+    signInWithOAuth(provider) {
+      sanitizeProvider(provider);
+      if (!isBrowser()) {
+        throw new Error('OAuth sign-in is only available in browser environment. Use server-side auth flow for SSR.');
+      }
+      window.location.href = `${this.apiUrl}/auth/oauth/${provider}/authorize?anon_key=${encodeURIComponent(this.anonKey)}`;
+    }
+
+    signInWithGoogle() { this.signInWithOAuth('google'); }
+    signInWithGitHub() { this.signInWithOAuth('github'); }
+    signInWithMicrosoft() { this.signInWithOAuth('microsoft'); }
+    signInWithApple() { this.signInWithOAuth('apple'); }
+
+    async linkOAuthProvider(provider) {
+      sanitizeProvider(provider);
+      const result = await this._authFetch(`/auth/oauth/${provider}/link`, {
+        method: 'POST'
+      });
+
+      if (!result.ok) {
+        return { data: null, error: result.error };
+      }
+      return { data: result.data, error: null };
+    }
+
+    async unlinkOAuthProvider(provider) {
+      sanitizeProvider(provider);
+      const result = await this._authFetch(`/auth/oauth/${provider}/unlink`, {
+        method: 'DELETE'
+      });
+
+      if (!result.ok) {
+        return { error: result.error };
+      }
+      return { error: null };
+    }
+
+    async getLinkedOAuthProviders() {
+      const result = await this._authFetch('/auth/oauth/providers');
+
+      if (!result.ok) {
+        return { providers: null, error: result.error };
+      }
+      return { providers: result.data.providers || [], error: null };
+    }
+
+    async refreshOAuthToken(provider) {
+      sanitizeProvider(provider);
+      const result = await this._authFetch(`/auth/oauth/${provider}/refresh-token`, {
+        method: 'POST'
+      });
+
+      if (!result.ok) {
+        return { message: null, provider: null, expiresIn: null, error: result.error };
+      }
+      return {
+        message: result.data.message,
+        provider: result.data.provider,
+        expiresIn: result.data.expires_in,
+        error: null
+      };
+    }
+
+    async getOAuthProviderToken(provider) {
+      sanitizeProvider(provider);
+      const result = await this._authFetch(`/auth/oauth/${provider}/token`);
+
+      if (!result.ok) {
+        return { message: null, provider: null, expiresIn: null, error: result.error };
+      }
+      return {
+        message: result.data.message,
+        provider: result.data.provider,
+        expiresIn: result.data.expires_in,
+        error: null
+      };
+    }
+
+    async callOAuthAPI(provider, { endpoint, method = 'GET', body = null }) {
+      sanitizeProvider(provider);
+      const result = await this._authFetch(`/auth/oauth/${provider}/call-api`, {
+        method: 'POST',
+        body: JSON.stringify({ endpoint, method, body })
+      });
+
+      if (!result.ok) {
+        return { data: null, error: result.error };
+      }
+      return { data: result.data.data, error: null };
+    }
+
+    // ========================================================================
+    // Session Management (User's sessions)
+    // ========================================================================
+
+    async getSessions(options = {}) {
+      const { page = 1, limit = DEFAULT_SESSIONS_LIMIT } = options;
+      const params = new URLSearchParams();
+      if (page > 1) params.set('page', page.toString());
+      if (limit !== DEFAULT_SESSIONS_LIMIT) params.set('limit', limit.toString());
+
+      const queryString = params.toString();
+      const url = `/auth/user/sessions${queryString ? '?' + queryString : ''}`;
+      const result = await this._authFetch(url);
+
+      if (!result.ok) {
+        return { sessions: null, total: 0, page: 1, limit: DEFAULT_SESSIONS_LIMIT, total_pages: 0, error: result.error };
+      }
+      return {
+        sessions: result.data.sessions,
+        total: result.data.total,
+        page: result.data.page,
+        limit: result.data.limit,
+        total_pages: result.data.total_pages,
+        error: null
+      };
+    }
+
+    async deleteSession(sessionId) {
+      const result = await this._authFetch(`/auth/user/sessions/${encodeURIComponent(sessionId)}`, {
+        method: 'DELETE'
+      });
+
+      if (!result.ok) {
+        return { error: result.error };
+      }
+      return { error: null };
+    }
+
+    async deleteAllOtherSessions() {
+      const result = await this._authFetch('/auth/user/sessions', {
+        method: 'DELETE'
+      });
+
+      if (!result.ok) {
+        return { error: result.error };
+      }
+      return { error: null };
+    }
+
+    // ========================================================================
+    // Function Invocation
+    // ========================================================================
+
+    async invokeFunction(functionName, payload = {}) {
+      if (!functionName || typeof functionName !== 'string') {
+        return { data: null, error: new Error('functionName must be a non-empty string') };
+      }
+      if (!this.accessToken) {
+        return { data: null, error: new Error('No active session') };
+      }
+      if (!this.functionInvocationBase) {
+        return { data: null, error: new Error('apiUrl must be api.<domain> (or localhost/IP for local mode) to use DNS function invocation') };
+      }
+
+      let resolvedFunctionId;
+      try {
+        resolvedFunctionId = await this._resolveFunctionIdByName(functionName.trim());
+      } catch (error) {
+        return { data: null, error: error instanceof Error ? error : new Error('Failed to resolve function') };
+      }
+
+      let invokeUrl;
+      try {
+        invokeUrl = this._getFunctionInvokeUrl(resolvedFunctionId);
+      } catch (error) {
+        return { data: null, error: error instanceof Error ? error : new Error('Invalid function identifier') };
+      }
+
+      let result = await this._authFetchUrl(invokeUrl, {
+        method: 'POST',
+        body: JSON.stringify(payload)
+      });
+
+      // Function can be deleted/recreated, making cached name->id mapping stale.
+      // On 404, invalidate and resolve once more before failing.
+      if (!result.ok && result.status === 404) {
+        this._clearFunctionResolveCache(functionName.trim());
+        try {
+          resolvedFunctionId = await this._resolveFunctionIdByName(functionName.trim());
+          invokeUrl = this._getFunctionInvokeUrl(resolvedFunctionId);
+          result = await this._authFetchUrl(invokeUrl, {
+            method: 'POST',
+            body: JSON.stringify(payload)
+          });
+        } catch (error) {
+          return { data: null, error: error instanceof Error ? error : new Error('Failed to resolve function') };
+        }
+      }
+
+      if (!result.ok) {
+        return { data: null, error: result.error };
+      }
+      return { data: result.data, error: null };
+    }
+
+    // ========================================================================
+    // Session Management (Internal)
+    // ========================================================================
+
+    _setSession(data) {
+      this.accessToken = data.access_token;
+      this.refreshToken = data.refresh_token;
+      this.currentUser = data.user;
+
+      this._setStorageItem(STORAGE_KEY_ACCESS_TOKEN, this.accessToken);
+      this._setStorageItem(STORAGE_KEY_REFRESH_TOKEN, this.refreshToken);
+
+      this._notifyAuthCallbacks(this.currentUser);
+    }
+
+    _clearSession() {
+      this.accessToken = null;
+      this.refreshToken = null;
+      this.currentUser = null;
+
+      this._removeStorageItem(STORAGE_KEY_ACCESS_TOKEN);
+      this._removeStorageItem(STORAGE_KEY_REFRESH_TOKEN);
+
+      this._notifyAuthCallbacks(null);
+    }
+
+    _notifyAuthCallbacks(user) {
+      if (this._authCallbacks) {
+        this._authCallbacks.forEach(cb => {
+          try {
+            cb(user);
+          } catch (err) {
+            console.error('[VolcanoAuth] Error in auth state callback:', err);
+          }
+        });
+      }
+    }
+
+    // ========================================================================
+    // Storage Helpers (Browser/Node.js compatible)
+    // ========================================================================
+
+    _getStorageItem(key) {
+      if (typeof localStorage !== 'undefined') {
+        return localStorage.getItem(key);
+      }
+      return null;
+    }
+
+    _setStorageItem(key, value) {
+      if (typeof localStorage !== 'undefined') {
+        localStorage.setItem(key, value);
+      }
+    }
+
+    _removeStorageItem(key) {
+      if (typeof localStorage !== 'undefined') {
+        localStorage.removeItem(key);
+      }
+    }
+
+    // ========================================================================
+    // Initialization
+    // ========================================================================
+
+    async initialize() {
+      if (this.accessToken && this.refreshToken) {
+        const { user, error } = await this.getUser();
+        return { user, error };
+      }
+      return { user: null, error: null };
+    }
+
+    /**
+     * @internal Test-only helper to ensure deterministic cache behavior in unit/integration tests.
+     */
+    static __resetFunctionResolveCacheForTests() {
+      clearSharedFunctionResolveStateForTests();
+    }
+
+    /**
+     * @internal Test-only helper for asserting global resolver cache state.
+     */
+    static __getFunctionResolveCacheMetricsForTests() {
+      const state = getSharedFunctionResolveState();
+      return {
+        cacheSize: state.cache.size,
+        inFlightSize: state.inFlight.size,
+        maxEntries: state.maxEntries
+      };
+    }
+
+    /**
+     * @internal Test-only helper for forcing resolver cache limits.
+     */
+    static __setFunctionResolveCacheMaxEntriesForTests(maxEntries) {
+      const nextMax = Number(maxEntries);
+      if (!Number.isInteger(nextMax) || nextMax < 1) {
+        throw new Error('maxEntries must be a positive integer');
+      }
+      const state = getSharedFunctionResolveState();
+      state.maxEntries = nextMax;
+      pruneFunctionResolveCache(state, Date.now(), true);
+    }
+  }
+
+  // ============================================================================
+  // Shared Filter Mixin - Used by QueryBuilder and MutationBuilder
+  // ============================================================================
+
+  const FilterMixin = {
+    eq(column, value) {
+      this.filters.push({ column, operator: 'eq', value });
+      return this;
+    },
+    neq(column, value) {
+      this.filters.push({ column, operator: 'neq', value });
+      return this;
+    },
+    gt(column, value) {
+      this.filters.push({ column, operator: 'gt', value });
+      return this;
+    },
+    gte(column, value) {
+      this.filters.push({ column, operator: 'gte', value });
+      return this;
+    },
+    lt(column, value) {
+      this.filters.push({ column, operator: 'lt', value });
+      return this;
+    },
+    lte(column, value) {
+      this.filters.push({ column, operator: 'lte', value });
+      return this;
+    },
+    like(column, pattern) {
+      this.filters.push({ column, operator: 'like', value: pattern });
+      return this;
+    },
+    ilike(column, pattern) {
+      this.filters.push({ column, operator: 'ilike', value: pattern });
+      return this;
+    },
+    is(column, value) {
+      this.filters.push({ column, operator: 'is', value });
+      return this;
+    },
+    in(column, values) {
+      this.filters.push({ column, operator: 'in', value: values });
+      return this;
+    }
+  };
+
+  // ============================================================================
+  // QueryBuilder - For SELECT operations
+  // ============================================================================
+
+  class QueryBuilder {
+    constructor(volcanoAuth, table, databaseName) {
+      this.volcanoAuth = volcanoAuth;
+      this.table = table;
+      this.databaseName = databaseName;
+      this.selectColumns = [];
+      this.filters = [];
+      this.orderClauses = [];
+      this.limitValue = null;
+      this.offsetValue = null;
+    }
+
+    select(columns) {
+      if (columns === '*') {
+        this.selectColumns = [];
+      } else if (Array.isArray(columns)) {
+        this.selectColumns = columns;
+      } else {
+        this.selectColumns = columns.split(',').map(c => c.trim());
+      }
+      return this;
+    }
+
+    order(column, options = {}) {
+      this.orderClauses.push({
+        column,
+        ascending: options.ascending !== false
+      });
+      return this;
+    }
+
+    limit(count) {
+      this.limitValue = count;
+      return this;
+    }
+
+    offset(count) {
+      this.offsetValue = count;
+      return this;
+    }
+
+    async execute() {
+      if (!this.volcanoAuth.accessToken) {
+        return errorResult('No active session. Please sign in first.', { count: 0 });
+      }
+
+      if (!this.databaseName) {
+        return errorResult('Database name not set. Use .database(databaseName) first.', { count: 0 });
+      }
+
+      const requestBody = { table: this.table };
+      if (this.selectColumns.length > 0) requestBody.select = this.selectColumns;
+      if (this.filters.length > 0) requestBody.filters = this.filters;
+      if (this.orderClauses.length > 0) requestBody.order = this.orderClauses;
+      if (this.limitValue !== null) requestBody.limit = this.limitValue;
+      if (this.offsetValue !== null) requestBody.offset = this.offsetValue;
+
+      try {
+        const response = await fetchWithAuthRetry(
+          this.volcanoAuth,
+          `${this.volcanoAuth.apiUrl}/databases/${encodeURIComponent(this.databaseName)}/query/select`,
+          {
+            method: 'POST',
+            headers: {
+              'Content-Type': 'application/json'
+            },
+            body: JSON.stringify(requestBody)
+          }
+        );
+
+        const result = await safeJsonParse(response);
+
+        if (!response.ok) {
+          return errorResult(result.error || 'Query failed', { count: 0 });
+        }
+
+        return { data: result.data, error: null, count: result.count || result.data.length };
+      } catch (error) {
+        return { data: null, error: error instanceof Error ? error : new Error('Query failed'), count: 0 };
+      }
+    }
+
+    then(resolve, reject) {
+      return this.execute().then(resolve, reject);
+    }
+  }
+
+  Object.assign(QueryBuilder.prototype, FilterMixin);
+
+  // ============================================================================
+  // MutationBuilder - Unified builder for INSERT, UPDATE, DELETE
+  // ============================================================================
+
+  class MutationBuilder {
+    constructor(volcanoAuth, table, databaseName, operation, values) {
+      this.volcanoAuth = volcanoAuth;
+      this.table = table;
+      this.databaseName = databaseName;
+      this.operation = operation;
+      this.values = values;
+      this.filters = [];
+    }
+
+    async execute() {
+      if (!this.volcanoAuth.accessToken) {
+        return errorResult('No active session. Please sign in first.');
+      }
+
+      if (!this.databaseName) {
+        return errorResult('Database name not set. Use .database(databaseName) first.');
+      }
+
+      const requestBody = { table: this.table };
+      if (this.values) requestBody.values = this.values;
+      if (this.filters.length > 0) requestBody.filters = this.filters;
+
+      try {
+        const response = await fetchWithAuthRetry(
+          this.volcanoAuth,
+          `${this.volcanoAuth.apiUrl}/databases/${encodeURIComponent(this.databaseName)}/query/${encodeURIComponent(this.operation)}`,
+          {
+            method: 'POST',
+            headers: {
+              'Content-Type': 'application/json'
+            },
+            body: JSON.stringify(requestBody)
+          }
+        );
+
+        const result = await safeJsonParse(response);
+
+        if (!response.ok) {
+          return errorResult(result.error || `${this.operation} failed`);
+        }
+
+        return { data: result.data, error: null };
+      } catch (error) {
+        return { data: null, error: error instanceof Error ? error : new Error(`${this.operation} failed`) };
+      }
+    }
+
+    then(resolve, reject) {
+      return this.execute().then(resolve, reject);
+    }
+  }
+
+  Object.assign(MutationBuilder.prototype, FilterMixin);
+
+  // ============================================================================
+  // StorageFileApi - For storage operations on a specific bucket
+  // ============================================================================
+
+  class StorageFileApi {
+    constructor(volcanoAuth, bucketName) {
+      this.volcanoAuth = volcanoAuth;
+      this.bucketName = bucketName;
+    }
+
+    /**
+     * Check if user is authenticated
+     * @private
+     */
+    _checkAuth() {
+      if (!this.volcanoAuth.accessToken) {
+        return errorResult('No active session. Please sign in first.');
+      }
+      return null;
+    }
+
+    /**
+     * Build a storage URL for the given path
+     * @private
+     */
+    _buildUrl(path) {
+      return `${this.volcanoAuth.apiUrl}/storage/${encodeURIComponent(this.bucketName)}/${this._encodePath(path)}`;
+    }
+
+    /**
+     * Encode a storage path for use in URLs
+     * @private
+     */
+    _encodePath(path) {
+      return path.split('/').map(segment => encodeURIComponent(segment)).join('/');
+    }
+
+    /**
+     * Make an authenticated storage request
+     * @private
+     */
+    async _storageRequest(url, options = {}) {
+      try {
+        const response = await fetchWithAuthRetry(this.volcanoAuth, url, options);
+
+        // For blob responses (downloads), handle separately
+        if (options.responseType === 'blob') {
+          if (!response.ok) {
+            const errorData = await safeJsonParse(response);
+            return { data: null, error: new Error(errorData.error || 'Request failed') };
+          }
+          const blob = await response.blob();
+          return { data: blob, error: null };
+        }
+
+        const data = await safeJsonParse(response);
+
+        if (!response.ok) {
+          return { data: null, error: new Error(data.error || 'Request failed') };
+        }
+
+        return { data, error: null };
+      } catch (error) {
+        return { data: null, error: error instanceof Error ? error : new Error('Request failed') };
+      }
+    }
+
+    /**
+     * Upload a file to the bucket
+     */
+    async upload(path, fileBody, options = {}) {
+      const authError = this._checkAuth();
+      if (authError) return authError;
+
+      try {
+        const formData = new FormData();
+        let file;
+
+        if (fileBody instanceof File) {
+          file = fileBody;
+        } else if (fileBody instanceof Blob) {
+          const contentType = options.contentType || 'application/octet-stream';
+          file = new File([fileBody], path.split('/').pop() || 'file', { type: contentType });
+        } else if (fileBody instanceof ArrayBuffer) {
+          const contentType = options.contentType || 'application/octet-stream';
+          file = new File([fileBody], path.split('/').pop() || 'file', { type: contentType });
+        } else {
+          return errorResult('Invalid file body type. Expected File, Blob, or ArrayBuffer.');
+        }
+
+        formData.append('file', file);
+
+        const response = await fetchWithAuthRetry(this.volcanoAuth, this._buildUrl(path), {
+          method: 'POST',
+          body: formData
+        });
+
+        const data = await safeJsonParse(response);
+
+        if (!response.ok) {
+          return errorResult(data.error || 'Upload failed');
+        }
+
+        return { data, error: null };
+      } catch (error) {
+        return { data: null, error: error instanceof Error ? error : new Error('Upload failed') };
+      }
+    }
+
+    /**
+     * Download a file from the bucket
+     */
+    async download(path, options = {}) {
+      const authError = this._checkAuth();
+      if (authError) return authError;
+
+      const headers = {};
+      if (options.range) {
+        headers['Range'] = options.range;
+      }
+
+      return this._storageRequest(this._buildUrl(path), {
+        method: 'GET',
+        headers,
+        responseType: 'blob'
+      });
+    }
+
+    /**
+     * List files in the bucket
+     */
+    async list(prefix = '', options = {}) {
+      const authError = this._checkAuth();
+      if (authError) return { ...authError, nextCursor: null };
+
+      const params = new URLSearchParams();
+      if (prefix) params.set('prefix', prefix);
+      if (options.limit) params.set('limit', String(options.limit));
+      if (options.cursor) params.set('cursor', options.cursor);
+
+      const queryString = params.toString();
+      const url = `${this.volcanoAuth.apiUrl}/storage/${encodeURIComponent(this.bucketName)}${queryString ? '?' + queryString : ''}`;
+
+      const result = await this._storageRequest(url, {
+        method: 'GET',
+        headers: { 'Content-Type': 'application/json' }
+      });
+
+      if (result.error) {
+        return { data: null, error: result.error, nextCursor: null };
+      }
+
+      return {
+        data: result.data.objects || [],
+        error: null,
+        nextCursor: result.data.next_cursor || null
+      };
+    }
+
+    /**
+     * Delete one or more files from the bucket
+     */
+    async remove(paths) {
+      const authError = this._checkAuth();
+      if (authError) return authError;
+
+      const pathList = Array.isArray(paths) ? paths : [paths];
+      const errors = [];
+      const deleted = [];
+
+      for (const path of pathList) {
+        const result = await this._storageRequest(this._buildUrl(path), {
+          method: 'DELETE'
+        });
+
+        if (result.error) {
+          errors.push({ path, error: result.error.message });
+        } else {
+          deleted.push(path);
+        }
+      }
+
+      if (errors.length > 0) {
+        return {
+          data: { deleted },
+          error: new Error(`Failed to delete ${errors.length} file(s): ${errors.map(e => e.path).join(', ')}`)
+        };
+      }
+
+      return { data: { deleted }, error: null };
+    }
+
+    /**
+     * Move/rename a file within the bucket
+     */
+    async move(fromPath, toPath) {
+      const authError = this._checkAuth();
+      if (authError) return authError;
+
+      return this._storageRequest(
+        `${this.volcanoAuth.apiUrl}/storage/${encodeURIComponent(this.bucketName)}/move`,
+        {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ from: fromPath, to: toPath })
+        }
+      );
+    }
+
+    /**
+     * Copy a file within the bucket
+     */
+    async copy(fromPath, toPath) {
+      const authError = this._checkAuth();
+      if (authError) return authError;
+
+      return this._storageRequest(
+        `${this.volcanoAuth.apiUrl}/storage/${encodeURIComponent(this.bucketName)}/copy`,
+        {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ from: fromPath, to: toPath })
+        }
+      );
+    }
+
+    /**
+     * Get the public URL for a file (only works for files with is_public=true)
+     */
+    getPublicUrl(path) {
+      try {
+        const parts = this.volcanoAuth.anonKey.split('.');
+        if (parts.length !== 3) {
+          return errorResult('Invalid anon key format');
+        }
+
+        const payload = JSON.parse(decodeBase64Url(parts[1]));
+        const projectId = payload.project_id;
+
+        if (!projectId) {
+          return errorResult('Project ID not found in anon key');
+        }
+
+        const encodedPath = this._encodePath(path);
+        const publicUrl = `${this.volcanoAuth.apiUrl}/public/${projectId}/${encodeURIComponent(this.bucketName)}/${encodedPath}`;
+        return { data: { publicUrl }, error: null };
+      } catch (error) {
+        return errorResult('Failed to parse anon key: ' + (error instanceof Error ? error.message : 'Unknown error'));
+      }
+    }
+
+    /**
+     * Update the visibility (public/private) of a file
+     */
+    async updateVisibility(path, isPublic) {
+      const authError = this._checkAuth();
+      if (authError) return authError;
+
+      return this._storageRequest(
+        `${this._buildUrl(path)}/visibility`,
+        {
+          method: 'PATCH',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ is_public: isPublic })
+        }
+      );
+    }
+
+    // ========================================================================
+    // Resumable Upload Methods
+    // ========================================================================
+
+    async createUploadSession(path, options) {
+      const authError = this._checkAuth();
+      if (authError) return authError;
+
+      if (!options || !options.totalSize) {
+        return errorResult('totalSize is required');
+      }
+
+      return this._storageRequest(this._buildUrl(path), {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          filename: path.split('/').pop() || path,
+          content_type: options.contentType || 'application/octet-stream',
+          total_size: options.totalSize,
+          part_size: options.partSize
+        })
+      });
+    }
+
+    async uploadPart(path, sessionId, partNumber, partData) {
+      const authError = this._checkAuth();
+      if (authError) return authError;
+
+      return this._storageRequest(this._buildUrl(path), {
+        method: 'PUT',
+        headers: {
+          'Content-Type': 'application/octet-stream',
+          'X-Upload-Session': sessionId,
+          'X-Part-Number': String(partNumber)
+        },
+        body: partData
+      });
+    }
+
+    async completeUploadSession(path, sessionId) {
+      const authError = this._checkAuth();
+      if (authError) return authError;
+
+      return this._storageRequest(this._buildUrl(path), {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-Upload-Session': sessionId,
+          'X-Upload-Complete': 'true'
+        },
+        body: JSON.stringify({})
+      });
+    }
+
+    async getUploadSession(path, sessionId) {
+      const authError = this._checkAuth();
+      if (authError) return authError;
+
+      return this._storageRequest(this._buildUrl(path), {
+        method: 'GET',
+        headers: { 'X-Upload-Session': sessionId }
+      });
+    }
+
+    async abortUploadSession(path, sessionId) {
+      const authError = this._checkAuth();
+      if (authError) return { error: authError.error };
+
+      const result = await this._storageRequest(this._buildUrl(path), {
+        method: 'DELETE',
+        headers: { 'X-Upload-Session': sessionId }
+      });
+
+      return { error: result.error };
+    }
+
+    /**
+     * Upload a large file using resumable upload with automatic chunking
+     */
+    async uploadResumable(path, fileBody, options = {}) {
+      const authError = this._checkAuth();
+      if (authError) return authError;
+
+      const totalSize = fileBody.size;
+      const contentType = options.contentType || (fileBody instanceof File ? fileBody.type : 'application/octet-stream') || 'application/octet-stream';
+      const partSize = options.partSize || DEFAULT_UPLOAD_PART_SIZE;
+      const onProgress = options.onProgress;
+
+      try {
+        const { data: session, error: sessionError } = await this.createUploadSession(path, {
+          totalSize,
+          contentType,
+          partSize
+        });
+
+        if (sessionError) {
+          return { data: null, error: sessionError };
+        }
+
+        const sessionId = session.session_id;
+        const totalParts = session.total_parts;
+        const actualPartSize = session.part_size;
+
+        let uploaded = 0;
+        for (let partNumber = 1; partNumber <= totalParts; partNumber++) {
+          const start = (partNumber - 1) * actualPartSize;
+          const end = Math.min(start + actualPartSize, totalSize);
+          const partData = fileBody.slice(start, end);
+
+          const { error: partError } = await this.uploadPart(path, sessionId, partNumber, partData);
+
+          if (partError) {
+            const { error: abortError } = await this.abortUploadSession(path, sessionId);
+            if (abortError) {
+              console.warn(`[Storage] Failed to abort upload session ${sessionId}:`, abortError.message);
+            }
+            return { data: null, error: partError };
+          }
+
+          uploaded = end;
+          if (onProgress) {
+            onProgress(uploaded, totalSize);
+          }
+        }
+
+        return this.completeUploadSession(path, sessionId);
+      } catch (error) {
+        return { data: null, error: error instanceof Error ? error : new Error('Resumable upload failed') };
+      }
+    }
+  }
+
+  // ============================================================================
+  // Realtime Import Note
+  // ============================================================================
+
+  // Realtime is available via separate import: import { VolcanoRealtime } from '@volcano.dev/sdk/realtime'
+  // This improves tree-shaking - centrifuge (~5.5MB) is only loaded when realtime is used
+  //
+  // To use realtime:
+  // 1. Install centrifuge: npm install centrifuge
+  // 2. Import directly: import { VolcanoRealtime } from '@volcano.dev/sdk/realtime'
+
+  /**
+   * Lazy-load the realtime module
+   * @returns {Promise<{VolcanoRealtime: any, RealtimeChannel: any}>}
+   */
+  async function loadRealtime() {
+    const module = await Promise.resolve().then(function () { return realtime; });
+    return {
+      VolcanoRealtime: module.VolcanoRealtime,
+      RealtimeChannel: module.RealtimeChannel
+    };
+  }
+
+  // ============================================================================
+  // Exports
+  // ============================================================================
+
+  // Browser global exports
+  if (typeof window !== 'undefined') {
+    window.VolcanoAuth = VolcanoAuth;
+    window.QueryBuilder = QueryBuilder;
+    window.StorageFileApi = StorageFileApi;
+    window.isBrowser = isBrowser;
+    window.loadRealtime = loadRealtime;
+  }
+
+  // CommonJS exports
+  if (typeof module !== 'undefined' && typeof module.exports !== 'undefined') {
+    module.exports = VolcanoAuth;
+    module.exports.VolcanoAuth = VolcanoAuth;
+    module.exports.default = VolcanoAuth;
+    module.exports.QueryBuilder = QueryBuilder;
+    module.exports.StorageFileApi = StorageFileApi;
+    module.exports.isBrowser = isBrowser;
+    module.exports.loadRealtime = loadRealtime;
+  }
+
+  // AMD exports
+  if (typeof define === 'function' && define.amd) {
+    define([], function() {
+      return VolcanoAuth;
+    });
+  }
+
+  /**
+   * Volcano Realtime SDK - WebSocket client for real-time messaging
+   * 
+   * This module provides real-time capabilities including:
+   * - Broadcast: Pub/sub messaging between clients
+   * - Presence: Track online users and their state
+   * - Postgres Changes: Subscribe to database INSERT/UPDATE/DELETE events
+   * 
+   * @example
+   * ```javascript
+   * import { VolcanoRealtime } from '@volcano.dev/sdk/realtime';
+   * 
+   * const realtime = new VolcanoRealtime({
+   *   apiUrl: 'https://api.yourapp.com',
+   *   anonKey: 'your-anon-key',
+   *   accessToken: 'your-access-token'
+   * });
+   * 
+   * // Connect to realtime server
+   * await realtime.connect();
+   * 
+   * // Subscribe to a broadcast channel
+   * const channel = realtime.channel('chat-room');
+   * channel.on('message', (payload) => console.log('New message:', payload));
+   * await channel.subscribe();
+   * 
+   * // Send a message
+   * channel.send({ text: 'Hello, world!' });
+   * 
+   * // Subscribe to database changes
+   * const dbChannel = realtime.channel('public:messages');
+   * dbChannel.onPostgresChanges('*', 'public', 'messages', (payload) => {
+   *   console.log('Database change:', payload);
+   * });
+   * await dbChannel.subscribe();
+   * 
+   * // Track presence
+   * const presenceChannel = realtime.channel('lobby', { type: 'presence' });
+   * presenceChannel.onPresenceSync((state) => {
+   *   console.log('Online users:', Object.keys(state));
+   * });
+   * await presenceChannel.subscribe();
+   * presenceChannel.track({ status: 'online' });
+   * ```
+   */
+
+  // Centrifuge client - dynamically imported
+  let Centrifuge = null;
+
+  /**
+   * Dynamically imports the Centrifuge client
+   */
+  async function loadCentrifuge() {
+    if (Centrifuge) return Centrifuge;
+    
+    try {
+      // Try ES module import
+      const module = await import('centrifuge');
+      Centrifuge = module.Centrifuge || module.default;
+      return Centrifuge;
+    } catch {
+      throw new Error(
+        'Centrifuge client not found. Please install it: npm install centrifuge'
+      );
+    }
+  }
+
+  // Load WebSocket for Node.js environments
+  let WebSocketImpl = null;
+  async function loadWebSocket() {
+    if (WebSocketImpl) return WebSocketImpl;
+    
+    // Check if we're in a browser environment
+    if (typeof window !== 'undefined' && window.WebSocket) {
+      WebSocketImpl = window.WebSocket;
+      return WebSocketImpl;
+    }
+    
+    // Node.js environment - try to load ws package
+    try {
+      const ws = await import('ws');
+      WebSocketImpl = ws.default || ws.WebSocket || ws;
+      return WebSocketImpl;
+    } catch {
+      throw new Error(
+        'WebSocket implementation not found. In Node.js, please install: npm install ws'
+      );
+    }
+  }
+
+  /**
+   * VolcanoRealtime - Main realtime client
+   * 
+   * Channel names use simple format: type:name (e.g., "broadcast:chat")
+   * The server automatically handles project isolation - clients never
+   * need to know about project IDs.
+   * 
+   * Authentication options:
+   * 1. User token: anonKey (required) + accessToken (user JWT)
+   * 2. Service key: anonKey (optional) + accessToken (service role key)
+   */
+  class VolcanoRealtime {
+    /**
+     * Create a new VolcanoRealtime client
+     * @param {Object} config - Configuration options
+     * @param {string} config.apiUrl - Volcano API URL
+     * @param {string} [config.anonKey] - Anon key (required for user tokens, optional for service keys)
+     * @param {string} config.accessToken - Access token (user JWT) or service role key (sk-...)
+     * @param {Function} [config.getToken] - Function to get/refresh token
+     * @param {Object} [config.volcanoClient] - VolcanoAuth client for auto-fetching lightweight notifications
+     * @param {string} [config.databaseName] - Database name for auto-fetch queries
+     * @param {Object} [config.fetchConfig] - Configuration for auto-fetch behavior
+     */
+    constructor(config) {
+      if (!config.apiUrl) throw new Error('apiUrl is required');
+      // anonKey is optional for service role keys (they contain project ID)
+      // But we need either anonKey or accessToken
+      if (config.anonKey === undefined) throw new Error('anonKey is required');
+
+      this.apiUrl = config.apiUrl.replace(/\/$/, ''); // Remove trailing slash
+      this.anonKey = config.anonKey || '';  // Allow empty string for service keys
+      this.accessToken = config.accessToken;
+      this.getToken = config.getToken;
+
+      this._client = null;
+      this._channels = new Map();
+      this._connected = false;
+      this._connectionPromise = null;
+
+      // Callbacks
+      this._onConnect = [];
+      this._onDisconnect = [];
+      this._onError = [];
+
+      // Auto-fetch support (Phase 3)
+      this._volcanoClient = config.volcanoClient || null;
+      this._fetchConfig = {
+        batchWindowMs: config.fetchConfig?.batchWindowMs || 20,
+        maxBatchSize: config.fetchConfig?.maxBatchSize || 50,
+        enabled: config.fetchConfig?.enabled !== false,
+      };
+
+      // Database name for auto-fetch queries (optional)
+      this._databaseName = config.databaseName || null;
+    }
+
+    /**
+     * Set the VolcanoAuth client for auto-fetching
+     * @param {Object} volcanoClient - VolcanoAuth client instance
+     */
+    setVolcanoClient(volcanoClient) {
+      this._volcanoClient = volcanoClient;
+    }
+
+    /**
+     * Get the configured VolcanoAuth client
+     * @returns {Object|null} The VolcanoAuth client or null
+     */
+    getVolcanoClient() {
+      return this._volcanoClient;
+    }
+
+    /**
+     * Get the fetch configuration
+     * @returns {Object} The fetch configuration
+     */
+    getFetchConfig() {
+      return { ...this._fetchConfig };
+    }
+
+    /**
+     * Set the database name for auto-fetch queries
+     * @param {string} databaseName
+     */
+    setDatabaseName(databaseName) {
+      this._databaseName = databaseName;
+    }
+
+    /**
+     * Get the configured database name
+     * @returns {string|null}
+     */
+    getDatabaseName() {
+      return this._databaseName;
+    }
+    
+    
+    /**
+     * Get the WebSocket URL for realtime connections
+     */
+    get wsUrl() {
+      const url = new URL(this.apiUrl);
+      const protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+      return `${protocol}//${url.host}/realtime/v1/websocket`;
+    }
+    
+    /**
+     * Connect to the realtime server
+     */
+    async connect() {
+      if (this._connected) return;
+      if (this._connectionPromise) return this._connectionPromise;
+      
+      this._connectionPromise = this._doConnect();
+      try {
+        await this._connectionPromise;
+      } finally {
+        this._connectionPromise = null;
+      }
+    }
+    
+    async _doConnect() {
+      const CentrifugeClient = await loadCentrifuge();
+      const WebSocket = await loadWebSocket();
+      
+      const wsUrl = `${this.wsUrl}?apikey=${encodeURIComponent(this.anonKey)}`;
+      
+      this._client = new CentrifugeClient(wsUrl, {
+        token: this.accessToken,
+        getToken: this.getToken ? async () => {
+          const token = await this.getToken();
+          this.accessToken = token;
+          return token;
+        } : undefined,
+        debug: false,
+        websocket: WebSocket,
+      });
+      
+      // Set up event handlers (store references for cleanup)
+      this._clientHandlers = {
+        connected: (ctx) => {
+          this._connected = true;
+          this._onConnect.forEach(cb => cb(ctx));
+        },
+        disconnected: (ctx) => {
+          this._connected = false;
+          this._onDisconnect.forEach(cb => cb(ctx));
+        },
+        error: (ctx) => {
+          this._onError.forEach(cb => cb(ctx));
+        },
+        publication: (ctx) => {
+          this._handleServerPublication(ctx);
+        },
+        join: (ctx) => {
+          this._handleServerJoin(ctx);
+        },
+        leave: (ctx) => {
+          this._handleServerLeave(ctx);
+        },
+        subscribed: (ctx) => {
+          this._handleServerSubscribed(ctx);
+        },
+      };
+
+      this._client.on('connected', this._clientHandlers.connected);
+      this._client.on('disconnected', this._clientHandlers.disconnected);
+      this._client.on('error', this._clientHandlers.error);
+      this._client.on('publication', this._clientHandlers.publication);
+      this._client.on('join', this._clientHandlers.join);
+      this._client.on('leave', this._clientHandlers.leave);
+      this._client.on('subscribed', this._clientHandlers.subscribed);
+      
+      // Connect and wait for connected event
+      return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+          reject(new Error('Connection timeout'));
+        }, 10000);
+        
+        const onConnected = () => {
+          clearTimeout(timeout);
+          this._client.off('connected', onConnected);
+          this._client.off('error', onError);
+          resolve();
+        };
+        
+        const onError = (ctx) => {
+          clearTimeout(timeout);
+          this._client.off('connected', onConnected);
+          this._client.off('error', onError);
+          reject(new Error(ctx.error?.message || 'Connection failed'));
+        };
+        
+        this._client.on('connected', onConnected);
+        this._client.on('error', onError);
+        this._client.connect();
+      });
+    }
+    
+    /**
+     * Disconnect from the realtime server
+     */
+    disconnect() {
+      // Unsubscribe all channels first to clean up their timers
+      for (const channel of this._channels.values()) {
+        try {
+          channel.unsubscribe();
+        } catch {
+          // Ignore errors during cleanup
+        }
+      }
+      this._channels.clear();
+
+      if (this._client) {
+        // Remove event handlers first to prevent memory leaks
+        if (this._clientHandlers) {
+          this._client.off('connected', this._clientHandlers.connected);
+          this._client.off('disconnected', this._clientHandlers.disconnected);
+          this._client.off('error', this._clientHandlers.error);
+          this._client.off('publication', this._clientHandlers.publication);
+          this._client.off('join', this._clientHandlers.join);
+          this._client.off('leave', this._clientHandlers.leave);
+          this._client.off('subscribed', this._clientHandlers.subscribed);
+          this._clientHandlers = null;
+        }
+
+        // Manually trigger disconnect callbacks
+        this._onDisconnect.forEach(cb => cb({ reason: 'manual' }));
+
+        // Disconnect the client
+        this._client.disconnect();
+        this._client = null;
+        this._connected = false;
+      }
+    }
+    
+    /**
+     * Check if connected to the realtime server
+     */
+    isConnected() {
+      return this._connected;
+    }
+    
+    /**
+     * Create or get a channel
+     * @param {string} name - Channel name
+     * @param {Object} [options] - Channel options
+     * @param {string} [options.type='broadcast'] - Channel type: 'broadcast', 'presence', 'postgres'
+     * @param {boolean} [options.autoFetch=true] - Enable auto-fetch for lightweight notifications
+     * @param {number} [options.fetchBatchWindowMs] - Batch window for fetch requests
+     * @param {number} [options.fetchMaxBatchSize] - Max batch size for fetch requests
+     */
+    channel(name, options = {}) {
+      const type = options.type || 'broadcast';
+      const fullName = this._formatChannelName(name, type);
+
+      if (this._channels.has(fullName)) {
+        return this._channels.get(fullName);
+      }
+
+      const channel = new RealtimeChannel(this, fullName, type, options);
+      this._channels.set(fullName, channel);
+      return channel;
+    }
+    
+    /**
+     * Format channel name for subscription
+     * Format: type:name
+     * 
+     * The server automatically adds the project ID prefix based on
+     * the authenticated connection. Clients never need to know about project IDs.
+     */
+    _formatChannelName(name, type) {
+      return `${type}:${name}`;
+    }
+    
+    /**
+     * Handle publications from server-side subscriptions
+     * The server uses project-prefixed channels: "projectId:type:name"
+     * We extract the type:name portion and route to the SDK channel
+     */
+    _handleServerPublication(ctx) {
+      const serverChannel = ctx.channel;
+      
+      // Server channel format: projectId:type:name
+      // We need to extract type:name to match our SDK channel
+      const parts = serverChannel.split(':');
+      if (parts.length < 3) {
+        // Not a valid server channel format, ignore
+        return;
+      }
+      
+      // Skip projectId, reconstruct type:name
+      const sdkChannel = parts.slice(1).join(':');
+      
+      // Find the SDK channel and deliver the message
+      const channel = this._channels.get(sdkChannel);
+      if (channel) {
+        channel._handlePublication(ctx);
+      }
+    }
+    
+    /**
+     * Handle join events from server-side subscriptions
+     */
+    _handleServerJoin(ctx) {
+      const serverChannel = ctx.channel;
+      const parts = serverChannel.split(':');
+      if (parts.length < 3) return;
+      
+      const sdkChannel = parts.slice(1).join(':');
+      const channel = this._channels.get(sdkChannel);
+      if (channel && channel._type === 'presence') {
+        // Update presence state
+        if (ctx.info) {
+          channel._presenceState[ctx.info.client] = ctx.info;
+        }
+        channel._triggerPresenceSync();
+        channel._triggerEvent('join', ctx.info);
+      }
+    }
+    
+    /**
+     * Handle leave events from server-side subscriptions
+     */
+    _handleServerLeave(ctx) {
+      const serverChannel = ctx.channel;
+      const parts = serverChannel.split(':');
+      if (parts.length < 3) return;
+      
+      const sdkChannel = parts.slice(1).join(':');
+      const channel = this._channels.get(sdkChannel);
+      if (channel && channel._type === 'presence') {
+        // Update presence state
+        if (ctx.info) {
+          delete channel._presenceState[ctx.info.client];
+        }
+        channel._triggerPresenceSync();
+        channel._triggerEvent('leave', ctx.info);
+      }
+    }
+    
+    /**
+     * Handle subscribed events - includes initial presence state
+     */
+    _handleServerSubscribed(ctx) {
+      const serverChannel = ctx.channel;
+      const parts = serverChannel.split(':');
+      if (parts.length < 3) return;
+      
+      const sdkChannel = parts.slice(1).join(':');
+      const channel = this._channels.get(sdkChannel);
+      
+      // For presence channels, populate initial state from subscribe response
+      if (channel && channel._type === 'presence' && ctx.data) {
+        // data contains initial presence information
+        if (ctx.data.presence) {
+          channel._presenceState = {};
+          for (const [clientId, info] of Object.entries(ctx.data.presence)) {
+            channel._presenceState[clientId] = info;
+          }
+          channel._triggerPresenceSync();
+        }
+      }
+    }
+    
+    /**
+     * Get the underlying Centrifuge client
+     */
+    getClient() {
+      return this._client;
+    }
+    
+    /**
+     * Register callback for connection events
+     */
+    onConnect(callback) {
+      this._onConnect.push(callback);
+      return () => {
+        this._onConnect = this._onConnect.filter(cb => cb !== callback);
+      };
+    }
+    
+    /**
+     * Register callback for disconnection events
+     */
+    onDisconnect(callback) {
+      this._onDisconnect.push(callback);
+      return () => {
+        this._onDisconnect = this._onDisconnect.filter(cb => cb !== callback);
+      };
+    }
+    
+    /**
+     * Register callback for error events
+     */
+    onError(callback) {
+      this._onError.push(callback);
+      return () => {
+        this._onError = this._onError.filter(cb => cb !== callback);
+      };
+    }
+    
+    /**
+     * Remove a specific channel
+     * @param {string} name - Channel name
+     * @param {string} [type='broadcast'] - Channel type
+     */
+    removeChannel(name, type = 'broadcast') {
+      const fullName = this._formatChannelName(name, type);
+      const channel = this._channels.get(fullName);
+      if (channel) {
+        channel.unsubscribe();
+        this._channels.delete(fullName);
+      }
+    }
+    
+    /**
+     * Remove all channels and listeners
+     */
+    removeAllChannels() {
+      for (const channel of this._channels.values()) {
+        channel.unsubscribe();
+      }
+      this._channels.clear();
+    }
+  }
+
+  /**
+   * RealtimeChannel - Represents a subscription to a realtime channel
+   */
+  class RealtimeChannel {
+    constructor(realtime, name, type, options) {
+      this._realtime = realtime;
+      this._name = name;
+      this._type = type;
+      this._options = options;
+      this._subscription = null;
+      this._callbacks = new Map();
+      this._presenceState = {};
+
+      // Auto-fetch support (Phase 3)
+      const parentFetchConfig = realtime.getFetchConfig();
+      this._fetchConfig = {
+        batchWindowMs: options.fetchBatchWindowMs || parentFetchConfig.batchWindowMs,
+        maxBatchSize: options.fetchMaxBatchSize || parentFetchConfig.maxBatchSize,
+        enabled: options.autoFetch !== false && parentFetchConfig.enabled,
+      };
+      this._pendingFetches = new Map(); // table -> { ids: Map<id, {resolve, reject}>, timer }
+
+      // Event handler references for cleanup
+      this._eventHandlers = {};
+      this._presenceTimeoutId = null;
+    }
+    
+    /**
+     * Get channel name
+     */
+    get name() {
+      return this._name;
+    }
+    
+    /**
+     * Subscribe to the channel
+     */
+    async subscribe() {
+      if (this._subscription) return;
+      
+      const client = this._realtime.getClient();
+      if (!client) {
+        throw new Error('Not connected to realtime server');
+      }
+      
+      this._subscription = client.newSubscription(this._name, {
+        // Enable presence for presence channels
+        presence: this._type === 'presence',
+        joinLeave: this._type === 'presence',
+        // Enable recovery for all channels
+        recover: true,
+      });
+      
+      // Set up message handler (store reference for cleanup)
+      this._eventHandlers.publication = (ctx) => {
+        const event = ctx.data?.event || 'message';
+        const callbacks = this._callbacks.get(event) || [];
+        callbacks.forEach(cb => cb(ctx.data, ctx));
+
+        // Also trigger wildcard listeners
+        const wildcardCallbacks = this._callbacks.get('*') || [];
+        wildcardCallbacks.forEach(cb => cb(ctx.data, ctx));
+      };
+      this._subscription.on('publication', this._eventHandlers.publication);
+
+      // Set up presence handlers for presence channels
+      if (this._type === 'presence') {
+        this._eventHandlers.presence = (ctx) => {
+          this._updatePresenceState(ctx);
+          this._triggerPresenceSync();
+        };
+        this._subscription.on('presence', this._eventHandlers.presence);
+
+        this._eventHandlers.join = (ctx) => {
+          this._presenceState[ctx.info.client] = ctx.info.data;
+          this._triggerPresenceSync();
+          this._triggerEvent('join', ctx.info);
+        };
+        this._subscription.on('join', this._eventHandlers.join);
+
+        this._eventHandlers.leave = (ctx) => {
+          delete this._presenceState[ctx.info.client];
+          this._triggerPresenceSync();
+          this._triggerEvent('leave', ctx.info);
+        };
+        this._subscription.on('leave', this._eventHandlers.leave);
+
+        // After subscribing, immediately fetch current presence for late joiners
+        // For server-side subscriptions, use client.presence() not subscription.presence()
+        this._eventHandlers.subscribed = async () => {
+          // Small delay to ensure subscription is fully active
+          this._presenceTimeoutId = setTimeout(async () => {
+            this._presenceTimeoutId = null;
+            try {
+              const client = this._realtime.getClient();
+              if (client && this._subscription) {
+                // Use client-level presence() for server-side subscriptions
+                const presence = await client.presence(this._name);
+
+                // Centrifuge returns presence data in `clients` field
+                if (presence && presence.clients) {
+                  this._presenceState = {};
+                  for (const [clientId, info] of Object.entries(presence.clients)) {
+                    this._presenceState[clientId] = info;
+                  }
+                  this._triggerPresenceSync();
+                }
+              }
+            } catch (err) {
+              // Ignore errors - presence might not be available yet
+            }
+          }, 150);
+        };
+        this._subscription.on('subscribed', this._eventHandlers.subscribed);
+      }
+      
+      await this._subscription.subscribe();
+    }
+    
+    /**
+     * Unsubscribe from the channel
+     */
+    unsubscribe() {
+      // Cancel pending presence fetch timeout
+      if (this._presenceTimeoutId) {
+        clearTimeout(this._presenceTimeoutId);
+        this._presenceTimeoutId = null;
+      }
+
+      // Clear all pending fetch timers to prevent memory leaks
+      if (this._pendingFetches) {
+        for (const batch of this._pendingFetches.values()) {
+          if (batch.timer) {
+            clearTimeout(batch.timer);
+          }
+          // Reject any pending promises
+          for (const { reject } of batch.ids.values()) {
+            reject(new Error('Channel unsubscribed'));
+          }
+        }
+        this._pendingFetches.clear();
+      }
+
+      if (this._subscription) {
+        // Remove event listeners before unsubscribing
+        for (const [event, handler] of Object.entries(this._eventHandlers)) {
+          try {
+            this._subscription.off(event, handler);
+          } catch {
+            // Ignore errors if listener already removed
+          }
+        }
+        this._eventHandlers = {};
+
+        this._subscription.unsubscribe();
+        // Also remove from Centrifuge client registry to allow re-subscription
+        const client = this._realtime.getClient();
+        if (client) {
+          try {
+            client.removeSubscription(this._subscription);
+          } catch {
+            // Ignore errors if subscription already removed
+          }
+        }
+        this._subscription = null;
+      }
+      this._callbacks.clear();
+      this._presenceState = {};
+    }
+    
+    /**
+     * Handle publication from server-side subscription
+     * Called by VolcanoRealtime when a message arrives on the internal channel
+     */
+    _handlePublication(ctx) {
+      const data = ctx.data;
+
+      // Check if this is a lightweight notification (Phase 3)
+      if (data?.mode === 'lightweight') {
+        this._handleLightweightNotification(data, ctx);
+        return;
+      }
+
+      // Full payload - deliver immediately
+      this._deliverPayload(data, ctx);
+    }
+
+    /**
+     * Handle a lightweight notification by auto-fetching the record data
+     * @param {Object} data - Lightweight notification data
+     * @param {Object} ctx - Publication context
+     */
+    async _handleLightweightNotification(data, ctx) {
+      const volcanoClient = this._realtime.getVolcanoClient();
+
+      // DELETE notifications may include old_record, deliver immediately
+      if (data.type === 'DELETE') {
+        // Convert lightweight DELETE to full format for backward compatibility
+        const oldRecord = data.old_record !== undefined
+          ? data.old_record
+          : (data.id !== undefined ? { id: data.id } : undefined);
+        const fullPayload = {
+          type: data.type,
+          schema: data.schema,
+          table: data.table,
+          old_record: oldRecord,
+          id: data.id,
+          timestamp: data.timestamp,
+        };
+        this._deliverPayload(fullPayload, ctx);
+        return;
+      }
+
+      // If no volcanoClient or auto-fetch disabled, deliver lightweight as-is
+      if (!volcanoClient || !this._fetchConfig.enabled) {
+        this._deliverPayload(data, ctx);
+        return;
+      }
+
+      // Auto-fetch the record for INSERT/UPDATE
+      try {
+        const record = await this._fetchRow(data.schema, data.table, data.id);
+
+        // Convert to full payload format for backward compatibility
+        const fullPayload = {
+          type: data.type,
+          schema: data.schema,
+          table: data.table,
+          record: record,
+          timestamp: data.timestamp,
+        };
+
+        this._deliverPayload(fullPayload, ctx);
+      } catch (err) {
+        // On fetch error, still deliver the lightweight notification
+        // so the client knows something changed, even if we couldn't get the data
+        console.warn(`[Realtime] Failed to fetch record for ${data.schema}.${data.table}:${data.id}:`, err.message);
+        this._deliverPayload(data, ctx);
+      }
+    }
+
+    /**
+     * Fetch a row from the database, batching requests for efficiency
+     * @param {string} schema - Schema name
+     * @param {string} table - Table name
+     * @param {*} id - Primary key value
+     * @returns {Promise<Object>} The fetched record
+     */
+    _fetchRow(schema, table, id) {
+      const tableKey = `${schema}.${table}`;
+
+      return new Promise((resolve, reject) => {
+        // Get or create pending batch for this table
+        if (!this._pendingFetches.has(tableKey)) {
+          this._pendingFetches.set(tableKey, {
+            ids: new Map(),
+            timer: null,
+            schema: schema,
+            table: table,
+          });
+        }
+
+        const batch = this._pendingFetches.get(tableKey);
+
+        // Add this ID to the batch
+        batch.ids.set(String(id), { resolve, reject });
+
+        // Check if we should flush due to size
+        if (batch.ids.size >= this._fetchConfig.maxBatchSize) {
+          this._flushFetch(schema, table);
+          return;
+        }
+
+        // Set timer for batch window if not already set
+        if (!batch.timer) {
+          batch.timer = setTimeout(() => {
+            this._flushFetch(schema, table);
+          }, this._fetchConfig.batchWindowMs);
+        }
+      });
+    }
+
+    /**
+     * Flush pending fetch requests for a table
+     * @param {string} schema - Schema name
+     * @param {string} table - Table name
+     */
+    async _flushFetch(schema, table) {
+      const tableKey = `${schema}.${table}`;
+      const batch = this._pendingFetches.get(tableKey);
+
+      if (!batch || batch.ids.size === 0) {
+        return;
+      }
+
+      // Clear timer and remove from pending
+      if (batch.timer) {
+        clearTimeout(batch.timer);
+      }
+      this._pendingFetches.delete(tableKey);
+
+      // Get all IDs to fetch
+      const idsToFetch = Array.from(batch.ids.keys());
+      const callbacks = new Map(batch.ids);
+
+      try {
+        const volcanoClient = this._realtime.getVolcanoClient();
+
+        if (!volcanoClient?.from || typeof volcanoClient.from !== 'function') {
+          throw new Error('volcanoClient.from not available');
+        }
+
+        const databaseName = this._realtime.getDatabaseName?.() || volcanoClient._currentDatabaseName || null;
+        let dbClient = volcanoClient;
+        if (databaseName) {
+          if (typeof volcanoClient.database !== 'function') {
+            throw new Error('volcanoClient.database not available');
+          }
+          dbClient = volcanoClient.database(databaseName);
+        } else if (typeof volcanoClient.database === 'function') {
+          throw new Error('Database name not set. Call volcanoClient.database(name) or pass databaseName to VolcanoRealtime.');
+        }
+
+        const tableName = schema && schema !== 'public' ? `${schema}.${table}` : table;
+
+        // Fetch all records in a single query using IN clause
+        // Assumes primary key column is 'id' - this is a common convention
+        const { data, error } = await dbClient
+          .from(tableName)
+          .select('*')
+          .in('id', idsToFetch);
+
+        if (error) {
+          // Reject all pending callbacks
+          for (const cb of callbacks.values()) {
+            cb.reject(new Error(error.message || 'Database fetch failed'));
+          }
+          return;
+        }
+
+        // Build a map of id -> record
+        const recordMap = new Map();
+        for (const record of (data || [])) {
+          recordMap.set(String(record.id), record);
+        }
+
+        // Resolve callbacks
+        for (const [id, cb] of callbacks) {
+          const record = recordMap.get(id);
+          if (record) {
+            cb.resolve(record);
+          } else {
+            // Record not found - could be RLS denial or row deleted
+            cb.reject(new Error(`Record not found or access denied: ${table}:${id}`));
+          }
+        }
+      } catch (err) {
+        // Reject all pending callbacks on error
+        for (const cb of callbacks.values()) {
+          cb.reject(err);
+        }
+      }
+    }
+
+    /**
+     * Deliver a payload to registered callbacks
+     * @param {Object} data - Payload data
+     * @param {Object} ctx - Publication context
+     */
+    _deliverPayload(data, ctx) {
+      const event = data?.event || data?.type || 'message';
+      const callbacks = this._callbacks.get(event) || [];
+      callbacks.forEach(cb => cb(data, ctx));
+
+      // Also trigger wildcard listeners
+      const wildcardCallbacks = this._callbacks.get('*') || [];
+      wildcardCallbacks.forEach(cb => cb(data, ctx));
+    }
+    
+    /**
+     * Listen for events on the channel
+     * @param {string} event - Event name or '*' for all events
+     * @param {Function} callback - Callback function
+     */
+    on(event, callback) {
+      if (!this._callbacks.has(event)) {
+        this._callbacks.set(event, []);
+      }
+      this._callbacks.get(event).push(callback);
+      
+      // Return unsubscribe function
+      return () => {
+        const callbacks = this._callbacks.get(event) || [];
+        this._callbacks.set(event, callbacks.filter(cb => cb !== callback));
+      };
+    }
+    
+    /**
+     * Send a message to the channel (broadcast only)
+     * @param {Object} data - Message data
+     */
+    async send(data) {
+      if (this._type !== 'broadcast') {
+        throw new Error('send() is only available for broadcast channels');
+      }
+      
+      if (!this._subscription) {
+        throw new Error('Channel not subscribed');
+      }
+      
+      await this._subscription.publish(data);
+    }
+    
+    /**
+     * Listen for database changes (postgres channels only)
+     * @param {string} event - Event type: 'INSERT', 'UPDATE', 'DELETE', or '*'
+     * @param {string} schema - Schema name
+     * @param {string} table - Table name
+     * @param {Function} callback - Callback function
+     */
+    onPostgresChanges(event, schema, table, callback) {
+      if (this._type !== 'postgres') {
+        throw new Error('onPostgresChanges() is only available for postgres channels');
+      }
+      
+      // Filter callback to only match the requested event type
+      return this.on('*', (data, ctx) => {
+        if (data.schema !== schema || data.table !== table) return;
+        if (event !== '*' && data.type !== event) return;
+        callback(data, ctx);
+      });
+    }
+    
+    /**
+     * Listen for presence state sync
+     * @param {Function} callback - Callback with presence state
+     */
+    onPresenceSync(callback) {
+      if (this._type !== 'presence') {
+        throw new Error('onPresenceSync() is only available for presence channels');
+      }
+      
+      return this.on('presence_sync', callback);
+    }
+    
+    /**
+     * Track this client's presence
+     * @param {Object} state - Presence state data (optional, for client-side state tracking)
+     * 
+     * Note: Presence data is automatically sent from the server based on your
+     * user metadata (from sign-up). Custom presence data should be included
+     * when creating the anonymous user.
+     */
+    async track(state = {}) {
+      if (this._type !== 'presence') {
+        throw new Error('track() is only available for presence channels');
+      }
+
+      // Store local presence state for client-side access
+      this._myPresenceState = state;
+
+      // Presence is automatically managed by Centrifuge based on subscription
+      // The connection data (from user metadata) is what other clients see
+      // Note: Custom state is stored locally for client-side access
+    }
+    
+    /**
+     * Get current presence state
+     */
+    getPresenceState() {
+      return { ...this._presenceState };
+    }
+    
+    _updatePresenceState(ctx) {
+      this._presenceState = {};
+      if (ctx.clients) {
+        for (const [clientId, info] of Object.entries(ctx.clients)) {
+          this._presenceState[clientId] = info.data;
+        }
+      }
+    }
+    
+    _triggerPresenceSync() {
+      this._triggerEvent('presence_sync', this._presenceState);
+    }
+    
+    _triggerEvent(event, data) {
+      const callbacks = this._callbacks.get(event) || [];
+      callbacks.forEach(cb => cb(data));
+    }
+  }
+
+  // Export for CommonJS
+  if (typeof module !== 'undefined' && module.exports) {
+    module.exports = { VolcanoRealtime, RealtimeChannel };
+  }
+
+  var realtime = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    RealtimeChannel: RealtimeChannel,
+    VolcanoRealtime: VolcanoRealtime
+  });
+
+  exports.QueryBuilder = QueryBuilder;
+  exports.StorageFileApi = StorageFileApi;
+  exports.VolcanoAuth = VolcanoAuth;
+  exports.default = VolcanoAuth;
+  exports.isBrowser = isBrowser;
+  exports.loadRealtime = loadRealtime;
+
+  Object.defineProperty(exports, '__esModule', { value: true });
+
+}));