@volcano.dev/sdk 1.2.0-nightly.22454064035.1

package/dist/index.esm.js

@@ -0,0 +1,2897 @@
+/**
+ * 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
+});
+
+export { QueryBuilder, StorageFileApi, VolcanoAuth, VolcanoAuth as default, isBrowser, loadRealtime };