@fenaura/sdk 0.2.0

package/js/fenaura-client.js

@@ -0,0 +1,1665 @@
+/**
+ * Fenaura Client SDK
+ * 
+ * A lightweight JavaScript client for Fenaura that provides direct database access,
+ * authentication, and storage operations from the browser.
+ * 
+ * Usage:
+ *   import { createClient } from '@fenaura/client'
+ *   const db = createClient('https://your-fenaura-url.com', 'your-project-slug')
+ * 
+ *   // Database
+ *   const { data } = await db.from('users').select('*')
+ *   await db.from('users').insert({ name: 'John' })
+ * 
+ *   // Auth
+ *   await db.auth.signUp({ email: 'john@example.com', password: 'secret' })
+ *   await db.auth.signIn({ email: 'john@example.com', password: 'secret' })
+ * 
+ *   // Storage
+ *   await db.storage.from('avatars').upload('user1.jpg', file)
+ *
+ *   // Storage with client-side compression (images shrink, text gzips —
+ *   *   fewer bytes leave the device over the same chunked upload)
+ *   await db.storage.from('avatars').upload('user1.jpg', file, {
+ *     compress: { mode: 'auto', maxWidth: 1920, quality: 0.8, format: 'webp' },
+ *   })
+ *   // Or compress standalone: const r = await compressFile(file, { mode: 'image' })
+ */
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+/**
+ * @typedef {Object} ClientOptions
+ * @property {string} [schema] - Database schema to use
+ * @property {number} [timeout] - Request timeout in milliseconds (default: 30000)
+ */
+
+/**
+ * @typedef {Object} QueryResult
+ * @property {string} status - 'success' or 'error'
+ * @property {any} data - The returned data
+ * @property {any} [error] - Error details if status is 'error'
+ * @property {number} [count] - Total count if count was requested
+ * @property {string} request_id - Unique request identifier
+ */
+
+/**
+ * @typedef {Object} Filter
+ * @property {string} [column] - Column name
+ * @property {string} [op] - Operator (eq, neq, gt, gte, lt, lte, like, ilike, in, is, contains, containedBy, overlaps, textSearch)
+ * @property {any} [value] - Filter value
+ * @property {Filter} [filter] - Inner filter for 'not' operator
+ * @property {Filter[]} [filters] - Array of filters for 'or' operator
+ */
+
+/**
+ * @typedef {Object} Order
+ * @property {string} column - Column to order by
+ * @property {boolean} [ascending] - Sort direction (default: true)
+ */
+
+// ─── Proxy helpers ───────────────────────────────────────────────────────────
+function isProxyBase(url) { return typeof url === 'string' && url.startsWith('/'); }
+function buildFetchOpts(url, apiKey, body, signal) {
+  const isProxy = isProxyBase(url);
+  const fetchUrl = `${url}/api/v1/data/${apiKey}`;
+  const headers = { 'Content-Type': 'application/json' };
+  if (!isProxy) {
+    const tok = getSessionToken();
+    if (!tok) {
+      try { console.warn('[fenaura] direct (non-proxy) mode without setSession(token): requests will 401. Call fenaura.setSession(token) or use createClient(\'/fenaura\', id).'); } catch { /* ignore */ }
+    }
+    headers['Authorization'] = `Bearer ${tok}`;
+  }
+  const opts = { method: 'POST', headers, body: JSON.stringify(body), signal };
+  if (isProxy) opts.credentials = 'include';
+  return { fetchUrl, opts };
+}
+
+// ─── Validation Helpers ──────────────────────────────────────────────────────
+
+const TABLE_NAME_REGEX = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+const COLUMN_NAME_REGEX = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+
+function isPathSafe(path) {
+  // B14: mirror the server's validate_rel_path (Rust blob-store): relative,
+  // ≤512 chars, ≤16 segments, per-segment charset [A-Za-z0-9._\- space],
+  // no empties/./.. /controls, no .meta.json suffix, no backslashes.
+  if (typeof path !== 'string' || !path || path.length > 512) return false;
+  if (path.startsWith('/') || path.endsWith('/') || path.includes('\\')) return false;
+  let decoded = path;
+  try { decoded = decodeURIComponent(path); } catch { return false; }
+  if (/^(.*%2f.*|.*%5c.*)$/i.test(path)) return false;
+  const segs = decoded.split('/');
+  if (segs.length > 16) return false;
+  for (const s of segs) {
+    if (!s || s.length > 128 || s === '.' || s === '..') return false;
+    if (s.endsWith('.meta.json')) return false;
+    if (!/^[A-Za-z0-9._\- ]+$/.test(s)) return false;
+    // eslint-disable-next-line no-control-regex
+    if (/[\x00-\x1f\x7f]/.test(s)) return false;
+  }
+  return true;
+}
+
+// Per-segment URL-encoding for object URLs (spaces etc. break otherwise).
+function encodePath(path) {
+  return String(path).split('/').map((s) => encodeURIComponent(s)).join('/');
+}
+
+const SQL_KEYWORDS = new Set([
+  'SELECT', 'INSERT', 'UPDATE', 'DELETE', 'DROP', 'CREATE', 'ALTER',
+  'TRUNCATE', 'REVOKE', 'GRANT', 'EXECUTE', 'UNION', 'INTERSECT',
+  'EXCEPT', 'WHERE', 'HAVING', 'GROUP', 'ORDER', 'BY', 'LIMIT',
+  'OFFSET', 'FETCH', 'NEXT', 'ROWS', 'ONLY', 'FOR', 'UPDATE',
+  'LOCK', 'IN', 'EXISTS', 'BETWEEN', 'LIKE', 'ILIKE', 'SIMILAR',
+  'REGEXP', 'RLIKE', 'AND', 'OR', 'NOT', 'NULL', 'IS', 'TRUE',
+  'FALSE', 'CHECK', 'DEFAULT', 'CONSTRAINT', 'PRIMARY', 'FOREIGN',
+  'KEY', 'UNIQUE', 'INDEX', 'TABLE', 'SCHEMA', 'DATABASE', 'VIEW',
+  'FUNCTION', 'TRIGGER', 'PROCEDURE', 'LANGUAGE', 'EXTENSION',
+  'WITH', 'RECURSIVE', 'CTE', 'MATERIALIZED', 'REFRESH', 'CONCURRENTLY',
+  'COPY', 'VACUUM', 'ANALYZE', 'REINDEX', 'CLUSTER', 'COMMENT',
+  'DO', 'BEGIN', 'COMMIT', 'ROLLBACK', 'SAVEPOINT', 'RELEASE',
+  'START', 'TRANSACTION', 'ISOLATION', 'LEVEL', 'READ', 'WRITE',
+  'COMMITTED', 'UNCOMMITTED', 'REPEATABLE', 'SERIALIZABLE', 'SNAPSHOT',
+]);
+
+function validateTableName(name) {
+  if (!name || name.length > 63) {
+    throw new Error('Invalid table name');
+  }
+  if (!TABLE_NAME_REGEX.test(name)) {
+    throw new Error('Invalid table name');
+  }
+  if (SQL_KEYWORDS.has(name.toUpperCase())) {
+    throw new Error('Reserved keyword');
+  }
+}
+
+function validateColumnName(name) {
+  if (name === '*') {
+    throw new Error('Wildcard not allowed');
+  }
+  if (!name || name.length > 63) {
+    throw new Error('Invalid column name');
+  }
+  if (!COLUMN_NAME_REGEX.test(name)) {
+    throw new Error('Invalid column name');
+  }
+  if (SQL_KEYWORDS.has(name.toUpperCase())) {
+    throw new Error('Reserved keyword');
+  }
+}
+
+function validateColumns(columns) {
+  if (columns === '*') {
+    return;
+  }
+  const cols = columns.split(',').map(c => c.trim());
+  for (const col of cols) {
+    if (col.includes('(') || col.includes(')') || col.includes(';')) {
+      throw new Error('Invalid column expression');
+    }
+    validateColumnName(col);
+  }
+}
+
+function validateFilterValue(value) {
+  if (value === null || value === undefined) {
+    return;
+  }
+  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+    return;
+  }
+  if (Array.isArray(value)) {
+    if (value.length > 100) {
+      throw new Error('Filter array too large (max 100)');
+    }
+    value.forEach(validateFilterValue);
+    return;
+  }
+  throw new Error('Invalid filter value type');
+}
+
+function validateData(data) {
+  if (Array.isArray(data)) {
+    if (data.length === 0) {
+      throw new Error('Data array must not be empty');
+    }
+    for (const item of data) {
+      if (typeof item !== 'object' || item === null || Array.isArray(item)) {
+        throw new Error('Each item in data array must be an object');
+      }
+      validateDataObject(item);
+    }
+    return;
+  }
+  if (typeof data !== 'object' || data === null) {
+    throw new Error('Data must be an object or array');
+  }
+  validateDataObject(data);
+}
+
+function validateDataObject(obj, depth = 0) {
+  if (depth > 10) {
+    throw new Error('Data too deeply nested');
+  }
+  const FORBIDDEN_KEYS = ['__proto__', 'constructor', 'prototype'];
+  for (const key of Object.keys(obj)) {
+    if (FORBIDDEN_KEYS.includes(key)) {
+      throw new Error(`Reserved key: ${key}`);
+    }
+    if (key.length > 63) {
+      throw new Error('Column name too long');
+    }
+    if (key.includes('.') || key.includes('[') || key.includes(']')) {
+      throw new Error('Invalid key characters');
+    }
+    const value = obj[key];
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+      validateDataObject(value, depth + 1);
+    } else if (Array.isArray(value)) {
+      if (value.length > 1000) {
+        throw new Error('Array too large');
+      }
+      for (const item of value) {
+        if (typeof item === 'object' && item !== null && !Array.isArray(item)) {
+          validateDataObject(item, depth + 1);
+        }
+      }
+    }
+  }
+}
+
+function validateFilter(filter, depth = 0) {
+  if (depth > 3) {
+    throw new Error('Filter too deeply nested');
+  }
+
+  if (!filter.op) {
+    throw new Error('Missing filter operator');
+  }
+
+  const ALLOWED_FILTER_OPS = [
+    'eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'like', 'ilike',
+    'in', 'is', 'contains', 'containedBy', 'overlaps', 'textSearch',
+    'not', 'or',
+  ];
+
+  if (!ALLOWED_FILTER_OPS.includes(filter.op)) {
+    throw new Error('Unknown filter operator');
+  }
+
+  if (filter.op === 'not') {
+    if (!filter.filter) {
+      throw new Error('Missing inner filter');
+    }
+    validateFilter(filter.filter, depth + 1);
+  } else if (filter.op === 'or') {
+    if (!filter.filters || !Array.isArray(filter.filters)) {
+      throw new Error('Missing filter array');
+    }
+    for (const f of filter.filters) {
+      validateFilter(f, depth + 1);
+    }
+  } else {
+    if (filter.column) {
+      validateColumnName(filter.column);
+    }
+    if (filter.value !== undefined) {
+      validateFilterValue(filter.value);
+    }
+  }
+}
+
+// ─── Query Builder ───────────────────────────────────────────────────────────
+
+class QueryBuilder {
+  /**
+   * @param {string} url - Fenaura server URL
+   * @param {string} apiKey - Project slug
+   * @param {string} table - Table name
+   * @param {ClientOptions} [options] - Client options
+   */
+  constructor(url, apiKey, table, options = {}) {
+    validateTableName(table);
+    this._url = url;
+    this._apiKey = apiKey;
+    this._table = table;
+    this._schema = options.schema;
+    this._timeout = options.timeout || 30000;
+    this._filters = [];
+    this._order = null;
+    this._limit = null;
+    this._offset = null;
+    this._columns = '*';
+    this._countMode = null;
+    this._single = false;
+    this._updateData = null;
+    this._op = 'select';
+  }
+
+  /**
+   * Select columns to retrieve
+   * @param {string} [columns='*'] - Comma-separated column names
+   * @returns {QueryBuilder}
+   */
+  select(columns = '*') {
+    validateColumns(columns);
+    this._columns = columns;
+    this._op = 'select';
+    return this;
+  }
+
+  /**
+   * Insert data
+   * @param {Object} data - Data to insert
+   * @returns {Promise<QueryResult>}
+   */
+  insert(data) {
+    validateData(data);
+    this._op = 'insert';
+    this._updateData = data;
+    return this._execute();
+  }
+
+  /**
+   * Update data
+   * @param {Object} data - Data to update
+   * @returns {QueryBuilder}
+   */
+  update(data) {
+    validateData(data);
+    this._op = 'update';
+    this._updateData = data;
+    return this;
+  }
+
+  /**
+   * Upsert data (insert or update) — single object only (D18: arrays are
+   * rejected 400 server-side; bulk upsert is insert-then-update instead).
+   * @param {Object} data - Data to upsert
+   * @returns {Promise<QueryResult>}
+   */
+  upsert(data) {
+    if (Array.isArray(data)) {
+      throw new Error('upsert takes a single object (arrays are rejected by the server)');
+    }
+    validateData(data);
+    this._op = 'upsert';
+    this._updateData = data;
+    return this._execute();
+  }
+
+  /**
+   * Delete data
+   * @returns {QueryBuilder}
+   */
+  delete() {
+    this._op = 'delete';
+    return this;
+  }
+
+  // ─── Filter Methods ──────────────────────────────────────────────────────
+
+  /**
+   * Filter: column equals value
+   * @param {string} column - Column name
+   * @param {any} value - Value to match
+   * @returns {QueryBuilder}
+   */
+  eq(column, value) {
+    return this._addFilter('eq', column, value);
+  }
+
+  /**
+   * Filter: column not equals value
+   * @param {string} column - Column name
+   * @param {any} value - Value to exclude
+   * @returns {QueryBuilder}
+   */
+  neq(column, value) {
+    return this._addFilter('neq', column, value);
+  }
+
+  /**
+   * Filter: column greater than value
+   * @param {string} column - Column name
+   * @param {any} value - Value to compare
+   * @returns {QueryBuilder}
+   */
+  gt(column, value) {
+    return this._addFilter('gt', column, value);
+  }
+
+  /**
+   * Filter: column greater than or equal to value
+   * @param {string} column - Column name
+   * @param {any} value - Value to compare
+   * @returns {QueryBuilder}
+   */
+  gte(column, value) {
+    return this._addFilter('gte', column, value);
+  }
+
+  /**
+   * Filter: column less than value
+   * @param {string} column - Column name
+   * @param {any} value - Value to compare
+   * @returns {QueryBuilder}
+   */
+  lt(column, value) {
+    return this._addFilter('lt', column, value);
+  }
+
+  /**
+   * Filter: column less than or equal to value
+   * @param {string} column - Column name
+   * @param {any} value - Value to compare
+   * @returns {QueryBuilder}
+   */
+  lte(column, value) {
+    return this._addFilter('lte', column, value);
+  }
+
+  /**
+   * Filter: column LIKE pattern
+   * @param {string} column - Column name
+   * @param {string} pattern - LIKE pattern
+   * @returns {QueryBuilder}
+   */
+  like(column, pattern) {
+    return this._addFilter('like', column, pattern);
+  }
+
+  /**
+   * Filter: column ILIKE pattern (case-insensitive)
+   * @param {string} column - Column name
+   * @param {string} pattern - ILIKE pattern
+   * @returns {QueryBuilder}
+   */
+  ilike(column, pattern) {
+    return this._addFilter('ilike', column, pattern);
+  }
+
+  /**
+   * Filter: column IN values
+   * @param {string} column - Column name
+   * @param {any[]} values - Array of values
+   * @returns {QueryBuilder}
+   */
+  in(column, values) {
+    return this._addFilter('in', column, values);
+  }
+
+  /**
+   * Filter: column IS value (use for null checks)
+   * @param {string} column - Column name
+   * @param {null} value - null
+   * @returns {QueryBuilder}
+   */
+  is(column, value) {
+    return this._addFilter('is', column, value);
+  }
+
+  /**
+   * Filter: column contains value (jsonb)
+   * @param {string} column - Column name
+   * @param {any} value - Value to check
+   * @returns {QueryBuilder}
+   */
+  contains(column, value) {
+    return this._addFilter('contains', column, value);
+  }
+
+  /**
+   * Filter: column contained by value (jsonb)
+   * @param {string} column - Column name
+   * @param {any} value - Value to check
+   * @returns {QueryBuilder}
+   */
+  containedBy(column, value) {
+    return this._addFilter('containedBy', column, value);
+  }
+
+  /**
+   * Filter: column overlaps value (array)
+   * @param {string} column - Column name
+   * @param {any} value - Value to check
+   * @returns {QueryBuilder}
+   */
+  overlaps(column, value) {
+    return this._addFilter('overlaps', column, value);
+  }
+
+  /**
+   * Filter: full-text search
+   * @param {string} column - Column name
+   * @param {string} query - Search query
+   * @returns {QueryBuilder}
+   */
+  textSearch(column, query) {
+    return this._addFilter('textSearch', column, query);
+  }
+
+  /**
+   * Negate a filter
+   * @param {Filter} filter - Filter to negate
+   * @returns {QueryBuilder}
+   */
+  not(filter) {
+    validateFilter(filter);
+    this._filters.push({ op: 'not', filter });
+    return this;
+  }
+
+  /**
+   * OR multiple filters
+   * @param {Filter[]} filters - Array of filters
+   * @returns {QueryBuilder}
+   */
+  or(filters) {
+    for (const f of filters) {
+      validateFilter(f);
+    }
+    this._filters.push({ op: 'or', filters });
+    return this;
+  }
+
+  // ─── Modifiers ──────────────────────────────────────────────────────────
+
+  /**
+   * Order results by column
+   * @param {string} column - Column name
+   * @param {Object} [options] - Options
+   * @param {boolean} [options.ascending=true] - Sort direction
+   * @returns {QueryBuilder}
+   */
+  order(column, options = {}) {
+    validateColumnName(column);
+    this._order = { column, ascending: options.ascending !== false };
+    return this;
+  }
+
+  /**
+   * Limit results
+   * @param {number} count - Maximum number of rows
+   * @returns {QueryBuilder}
+   */
+  limit(count) {
+    if (!Number.isInteger(count) || count < 1 || count > 1000) {
+      throw new Error('Limit must be between 1 and 1000');
+    }
+    this._limit = count;
+    return this;
+  }
+
+  /**
+   * Offset results
+   * @param {number} count - Number of rows to skip
+   * @returns {QueryBuilder}
+   */
+  offset(count) {
+    if (!Number.isInteger(count) || count < 0) {
+      throw new Error('Offset must be non-negative');
+    }
+    this._offset = count;
+    return this;
+  }
+
+  /**
+   * Return single row
+   * @returns {Promise<Object|null>}
+   */
+  single() {
+    this._single = true;
+    this._limit = 1;
+    return this._execute().then(r => r.data);
+  }
+
+  /**
+   * Return single row or null
+   * @returns {Promise<Object|null>}
+   */
+  maybeSingle() {
+    this._single = true;
+    this._limit = 1;
+    return this._execute().then(r => r.data);
+  }
+
+  /**
+   * Request count
+   * @param {'exact'|'planned'|'estimated'} [mode='exact'] - Count mode
+   * @returns {QueryBuilder}
+   */
+  count(mode = 'exact') {
+    this._countMode = mode;
+    return this;
+  }
+
+  /**
+   * Set returning columns
+   * @param {string} columns - Comma-separated column names
+   * @returns {QueryBuilder}
+   */
+  returning(columns) {
+    this._returning = columns;
+    return this;
+  }
+
+  /**
+   * Execute a select / update / delete chain and return the full result.
+   * `insert`, `upsert`, `single` and `maybeSingle` already execute on their
+   * own; this terminal covers the rest. The builder is also thenable, so
+   * `await fenaura.from('t').select('*').eq('id', 1)` works directly
+   * (Supabase-style).
+   * @returns {Promise<QueryResult>}
+   */
+  execute() {
+    return this._execute();
+  }
+
+  then(onFulfilled, onRejected) {
+    return this._execute().then(onFulfilled, onRejected);
+  }
+
+  catch(onRejected) {
+    return this._execute().catch(onRejected);
+  }
+
+  finally(onFinally) {
+    return this._execute().finally(onFinally);
+  }
+
+  // ─── Private Methods ────────────────────────────────────────────────────
+
+  _addFilter(op, column, value) {
+    validateColumnName(column);
+    validateFilterValue(value);
+    this._filters.push({ column, op, value });
+    return this;
+  }
+
+  async _execute() {
+    const body = {
+      op: this._op,
+      table: this._table,
+      columns: this._columns,
+      filters: this._filters,
+    };
+
+    if (this._order) {
+      body.order = this._order;
+    }
+    if (this._limit !== null) {
+      body.limit = this._limit;
+    }
+    if (this._offset !== null) {
+      body.offset = this._offset;
+    }
+    if (this._countMode) {
+      body.count = this._countMode;
+    }
+    if (this._single) {
+      body.single = true;
+    }
+    if (this._returning) {
+      body.returning = this._returning;
+    }
+    if (this._updateData) {
+      body.data = this._updateData;
+    }
+
+    const url = `${this._url}/api/v1/data/${this._apiKey}`;
+    
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this._timeout);
+
+    try {
+      const { fetchUrl, opts } = buildFetchOpts(this._url, this._apiKey, body, controller.signal);
+      const response = await fetch(fetchUrl, opts);
+
+      const result = await response.json();
+      return result;
+    } catch (error) {
+      if (error.name === 'AbortError') {
+        return {
+          status: 'error',
+          error: { code: 'TIMEOUT', message: 'Request timed out' },
+          request_id: '',
+        };
+      }
+      return {
+        status: 'error',
+        error: { code: 'NETWORK_ERROR', message: error.message },
+        request_id: '',
+      };
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+}
+
+// ─── Auth Client ─────────────────────────────────────────────────────────────
+
+// browser:false → ask the server for the raw token in the JSON body instead
+// of a Set-Cookie (plan §12). Non-web clients / backends store or forward it
+// themselves. Server side: Rust should_return_token (X-Fenaura-Return-Token).
+function tokenHeaders(options = {}) {
+  if (options && options.browser === false) return { 'X-Fenaura-Return-Token': 'json' };
+  return {};
+}
+
+class AuthClient {
+  /**
+   * @param {string} url - Fenaura server URL
+   * @param {string} apiKey - Project slug
+   */
+  constructor(url, apiKey) {
+    this._url = url;
+    this._apiKey = apiKey;
+    this._listeners = new Map();
+  }
+
+  /**
+   * Sign up with email and password
+   * @param {Object} params
+   * @param {string} params.email - Email address
+   * @param {string} params.password - Password
+   * @param {Object} [options] - { browser=true } — browser:false returns the raw
+   *   token in `data.token` (no cookie set) for non-web clients / backends.
+   *   Store or forward it yourself. WARNING: a raw token in JS memory or
+   *   localStorage is readable by any script on the page — prefer the cookie
+   *   flow in browsers, and never use browser:false on shared machines.
+   * @returns {Promise<QueryResult>}
+   */
+  async signUp({ email, password }, options = {}) {
+    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+      return { data: null, error: { message: 'Invalid email format' } };
+    }
+    if (password.length < 8) {
+      return { data: null, error: { message: 'Password must be at least 8 characters' } };
+    }
+    return this._authRequest('/api/v1/auth/dp/registration', { email, password, project_id: this._apiKey }, 'POST', tokenHeaders(options));
+  }
+
+  /**
+   * Sign in with email and password
+   * @param {Object} params
+   * @param {string} params.email - Email address
+   * @param {string} params.password - Password
+   * @param {Object} [options] - { browser=true } — browser:false returns the raw
+   *   token in `data.token` (no cookie set) for non-web clients / backends.
+   * @returns {Promise<QueryResult>}
+   */
+  async signIn({ email, password }, options = {}) {
+    return this._authRequest('/api/v1/auth/dp/login', { email, password, project_id: this._apiKey }, 'POST', tokenHeaders(options));
+  }
+
+  /**
+   * Sign out
+   * @returns {Promise<QueryResult>}
+   */
+  async signOut() {
+    return this._authRequest('/api/v1/auth/dp/logout', { project_id: this._apiKey });
+  }
+
+  /**
+   * Get current session
+   * @returns {Promise<QueryResult>}
+   */
+  async getSession() {
+    return this._authRequest('/api/v1/auth/dp/whoami', null, 'GET');
+  }
+
+  /**
+   * Get current user
+   * @returns {Promise<QueryResult>}
+   */
+  async getUser() {
+    return this._authRequest('/api/v1/auth/dp/whoami', null, 'GET');
+  }
+
+  /**
+   * Sign in with OAuth provider (Supabase-shaped, Fenaura transport).
+   * Web (default): redirects the browser to the provider; session returns as
+   * HttpOnly fenaura_eusid_* cookie (+ one-time ?code= for exchange).
+   * Non-web ({ browser:false }): no navigation — returns { data:{url} };
+   * open the URL in a system browser, then call exchangeCodeForSession(code)
+   * with the ?code= your redirect_to (deep link) receives.
+   * @param {string} provider - google|github|microsoft|apple|facebook|twitter|discord|linkedin|spotify|slack|gitlab|twitch
+   * @param {Object} [options] - { redirectTo, scopes, queryParams, skipBrowserRedirect, browser=true }
+   * @returns {Promise<QueryResult>} { data: { url, provider }, error }
+   */
+  async signInWithOAuth(provider, options = {}) {
+    const OAUTH_PROVIDERS = ['google', 'github', 'microsoft', 'apple', 'facebook', 'twitter', 'discord', 'linkedin', 'spotify', 'slack', 'gitlab', 'twitch'];
+    if (!OAUTH_PROVIDERS.includes(provider)) {
+      return { data: null, error: { message: `Unknown provider: ${provider}` } };
+    }
+    const { redirectTo, scopes, queryParams = {}, skipBrowserRedirect = false, browser = true } = options;
+    // Reserved keys are stripped server-side (`qp` JSON blob); SDK passes through.
+    const q = new URLSearchParams({ project_id: this._apiKey });
+    if (redirectTo) q.set('redirect_to', redirectTo);
+    if (scopes) q.set('scopes', scopes);
+    if (queryParams && Object.keys(queryParams).length > 0) {
+      // Global AJV removeAdditional strips unknown query keys (server.ts) —
+      // send extras as one JSON blob `qp`, server filters reserved keys.
+      q.set('qp', JSON.stringify(queryParams));
+    }
+    const url = `${this._url}/api/v1/oauth/${provider}?${q.toString()}`;
+    if (skipBrowserRedirect || browser === false) return { data: { url, provider }, error: null };
+    if (typeof window !== 'undefined' && window.location) {
+      window.location.assign(url);
+    }
+    return { data: { url, provider }, error: null };
+  }
+
+  /**
+   * Exchange a one-time OAuth ?code= for the session (plan §12).
+   * Web via /fenaura proxy: ALSO sets the first-party HttpOnly cookie.
+   * Non-web / backend: use `data.token` — store or forward it yourself
+   * (e.g. your backend sets it as a cookie for YOUR end users).
+   * Codes are single-use, 60s TTL; replay → INVALID_CODE.
+   * @param {string} code - one-time code from the callback redirect (?code=)
+   * @returns {Promise<QueryResult>} { data: { token, project_id }, error }
+   */
+  async exchangeCodeForSession(code) {
+    if (!code || typeof code !== 'string') {
+      return { data: null, error: { message: 'Code is required' } };
+    }
+    return this._authRequest('/api/v1/auth/oauth/exchange', { code: code.trim() });
+  }
+
+  /**
+   * Send a signup verification code (projects with verification required).
+   * Route 1b of the verification flow: signup (route 1) creates the account
+   * without a session; this sends the code; submitVerificationCode (route 2)
+   * completes sign-in. Signup auto-sends, so call this only for resends.
+   * @param {Object} params - { email }
+   * @returns {Promise<QueryResult>} { data: { code_sent, email }, error }
+   */
+  async sendVerificationCode({ email }) {
+    return this._authRequest('/api/v1/auth/dp/send-code', { email, project_id: this._apiKey });
+  }
+
+  /**
+   * Submit a signup verification code (route 2 of 2).
+   * On success mints the FIRST session (cookie, or raw token with browser:false).
+   * @param {Object} params - { email, code }
+   * @param {Object} [options] - { browser=true }
+   * @returns {Promise<QueryResult>}
+   */
+  async submitVerificationCode({ email, code }, options = {}) {
+    return this._authRequest('/api/v1/auth/dp/verify-code', { email, code, project_id: this._apiKey }, 'POST', tokenHeaders(options));
+  }
+
+  /**
+   * Send a password-reset code (account must exist; unknown addresses get a
+   * generic success without email — anti-enumeration).
+   * @param {Object} params - { email }
+   * @returns {Promise<QueryResult>} { data: { code_sent, email }, error }
+   */
+  async sendPasswordReset({ email }) {
+    return this._authRequest('/api/v1/auth/dp/send-code', { email, project_id: this._apiKey, type: 'password_reset' });
+  }
+
+  /**
+   * Finish a password reset: consumes the code, sets the new password, kills
+   * all other sessions, mints a fresh session for this device.
+   * @param {Object} params - { email, code, newPassword }
+   * @param {Object} [options] - { browser=true }
+   * @returns {Promise<QueryResult>}
+   */
+  async confirmPasswordReset({ email, code, newPassword }, options = {}) {
+    return this._authRequest('/api/v1/auth/dp/reset-password', { email, code, new_password: newPassword, project_id: this._apiKey }, 'POST', tokenHeaders(options));
+  }
+
+  /**
+   * Send a magic-link (OTP) code — passwordless sign-in for existing accounts.
+   * @param {Object} params - { email }
+   * @returns {Promise<QueryResult>} { data: { code_sent, email }, error }
+   */
+  async sendMagicLink({ email }) {
+    return this._authRequest('/api/v1/auth/dp/send-code', { email, project_id: this._apiKey, type: 'magic_link' });
+  }
+
+  /**
+   * Verify a magic-link code → session (no password needed).
+   * @param {Object} params - { email, code }
+   * @param {Object} [options] - { browser=true }
+   * @returns {Promise<QueryResult>}
+   */
+  async verifyMagicCode({ email, code }, options = {}) {
+    return this._authRequest('/api/v1/auth/dp/verify-code', { email, code, project_id: this._apiKey, type: 'magic_link' }, 'POST', tokenHeaders(options));
+  }
+
+  /**
+   * Handle OAuth callback page (/auth/callback on your app).
+   * Server already set the session cookie; just read the user.
+   * @returns {Promise<QueryResult>} { data: { user }, error }
+   */
+  async handleOAuthCallback() {
+    if (typeof window !== 'undefined') {
+      const sp = new URLSearchParams(window.location.search);
+      const err = sp.get('error');
+      // Hygiene (plan §18): one-time codes must not linger in history/logs.
+      if (sp.has('code')) {
+        try {
+          sp.delete('code');
+          const qs = sp.toString();
+          window.history.replaceState(null, '', window.location.pathname + (qs ? `?${qs}` : '') + window.location.hash);
+        } catch { /* ignore */ }
+      }
+      if (err) {
+        return { data: null, error: { message: err, hint: sp.get('detail') || sp.get('error_description') } };
+      }
+    }
+    return this._authRequest('/api/v1/auth/dp/whoami', null, 'GET');
+  }
+
+  /**
+   * Listen for auth state changes
+   * @param {Function} callback - Callback function
+   * @returns {Object} Subscription object
+   */
+  onAuthStateChange(callback) {
+    const id = Math.random().toString(36).slice(2);
+    if (!this._listeners.has('auth')) {
+      this._listeners.set('auth', new Set());
+    }
+    this._listeners.get('auth').add(callback);
+    return {
+      data: {
+        subscription: {
+          unsubscribe: () => {
+            this._listeners.get('auth')?.delete(callback);
+          },
+        },
+      },
+    };
+  }
+
+  async _authRequest(path, body, method = 'POST', extraHeaders = {}) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 30000);
+    try {
+      const isProxy = isProxyBase(this._url);
+      const fetchUrl = `${this._url}${path}`;
+      const headers = { 'Content-Type': 'application/json', ...extraHeaders };
+      if (!isProxy) {
+    const tok = getSessionToken();
+    if (!tok) {
+      try { console.warn('[fenaura] direct (non-proxy) mode without setSession(token): requests will 401. Call fenaura.setSession(token) or use createClient(\'/fenaura\', id).'); } catch { /* ignore */ }
+    }
+    headers['Authorization'] = `Bearer ${tok}`;
+  }
+      const opts = { method, headers, signal: controller.signal, ...(isProxy ? { credentials: 'include' } : {}) };
+      if (body && method !== 'GET') opts.body = JSON.stringify(body);
+      const response = await fetch(fetchUrl, opts);
+      const result = await response.json().catch(() => ({}));
+      // Normalize to { data, error } shape: data endpoint nests error, auth endpoint uses top-level code/message
+      if (result.status === 'error' || result.code) {
+        const err = result.error || (result.code ? { code: result.code, message: result.message, hint: result.hint } : null);
+        return { data: result.data ?? null, error: err || { message: result.message || 'Request failed' }, status: 'error', request_id: result.request_id || '' };
+      }
+      if (response.ok) {
+        return { data: result.data ?? result, error: null, status: result.status || 'success', request_id: result.request_id || '' };
+      }
+      // HTTP error but no status field
+      return { data: null, error: { code: result.code || 'REQUEST_FAILED', message: result.message || `HTTP ${response.status}` }, status: 'error', request_id: result.request_id || '' };
+    } catch (error) {
+      if (error.name === 'AbortError') {
+        return { status: 'error', data: null, error: { code: 'TIMEOUT', message: 'Request timed out' }, request_id: '' };
+      }
+      return { status: 'error', data: null, error: { code: 'NETWORK_ERROR', message: error.message }, request_id: '' };
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  // legacy data-op path (kept for rpc/storage fallback, not used by auth)
+  async _request(op, data) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 30000);
+    try {
+      const { fetchUrl, opts } = buildFetchOpts(this._url, this._apiKey, { op, data }, controller.signal);
+      const response = await fetch(fetchUrl, opts);
+      const result = await response.json();
+      return result;
+    } catch (error) {
+      if (error.name === 'AbortError') {
+        return { status: 'error', error: { code: 'TIMEOUT', message: 'Request timed out' }, request_id: '' };
+      }
+      return { status: 'error', error: { code: 'NETWORK_ERROR', message: error.message }, request_id: '' };
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+}
+
+// ─── Storage Client ──────────────────────────────────────────────────────────
+
+class StorageClient {
+  /**
+   * @param {string} url - Fenaura server URL
+   * @param {string} apiKey - Project slug
+   */
+  constructor(url, apiKey) {
+    this._url = url;
+    this._apiKey = apiKey;
+  }
+
+  /**
+   * Reference a storage bucket
+   * @param {string} bucket - Bucket name
+   * @returns {Object} Bucket operations
+   */
+  from(bucket) {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(bucket)) {
+      throw new Error('Invalid bucket name');
+    }
+
+    return {
+      /**
+       * Upload a file in 1 MiB chunks, with live backend progress.
+       * Flow: init → PUT each chunk (server answers received/total per
+       * chunk) → complete (server assembles + sniffs content). A failed
+       * chunk is retried alone — never the whole file.
+       * @param {string} path - File path
+       * @param {File|Blob} file - File to upload
+       * @param {Object} [options] - Upload options
+       * @param {string} [options.contentType] - Override MIME type (default: compressed output type, else file.type)
+       * @param {number} [options.maxSize] - Client-side cap applied AFTER compression (default 50 MiB)
+       * @param {boolean|Object} [options.compress] - true or CompressOptions
+       *   ({mode,maxWidth,maxHeight,quality,format,lossless,force,signal}).
+       *   Runs fully on-device before any byte is sent: images →
+       *   canvas resize/re-encode, other files → gzip. The smaller bytes are
+       *   what get chunked/uploaded; success data carries
+       *   `compression:{mode,original_size,compressed_size}` when applied.
+       * @param {function} [options.onProgress] - ({sentBytes,totalBytes,chunksDone,chunksTotal,index}) per acked chunk
+       * @param {AbortSignal} [options.signal] - Abort the upload
+       * @returns {Promise<QueryResult>}
+       */
+      upload: async (path, file, options = {}) => {
+        if (!isPathSafe(path)) {
+          throw new Error('Invalid path: directory traversal not allowed');
+        }
+        // 0. compress — on-device; only the smaller bytes leave the device
+        let source = file;
+        let compression = null;
+        if (options.compress !== undefined && options.compress !== false && options.compress !== null) {
+          const res = await compressFile(file, options.compress === true ? {} : options.compress);
+          source = res.file;
+          if (res.compressed) {
+            compression = { mode: res.mode, original_size: res.originalSize, compressed_size: res.compressedSize };
+          }
+        }
+        const maxSize = options.maxSize || 50 * 1024 * 1024;
+        if (source.size > maxSize) {
+          throw new Error(`File too large: max ${maxSize} bytes`);
+        }
+        if (!source.size) {
+          throw new Error('Cannot upload an empty file');
+        }
+        const isProxy = isProxyBase(this._url);
+        const authHeaders = isProxy ? {} : { 'Authorization': `Bearer ${getSessionToken()}` };
+        const creds = isProxy ? { credentials: 'include' } : {};
+        const fail = (code, message, request_id = '') => ({ status: 'error', data: null, error: { code, message }, request_id });
+
+        // 1. init — server validates name/type/size and hands back an upload id
+        const initRes = await fetch(`${this._url}/api/v1/blob/${this._apiKey}/init`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json', ...authHeaders },
+          body: JSON.stringify({
+            bucket,
+            path,
+            content_type: options.contentType || source.type || 'application/octet-stream',
+            size: source.size,
+          }),
+          signal: options.signal,
+          ...creds,
+        });
+        const init = await initRes.json().catch(() => ({}));
+        if (init.status === 'error' || init.code || !init.data?.upload_id) {
+          return fail(init.code || 'INIT_FAILED', init.message || `Init failed (HTTP ${initRes.status})`, init.request_id);
+        }
+        const { upload_id, chunk_size, chunks_total } = init.data;
+        const ping = (index, sentBytes) => {
+          if (typeof options.onProgress === 'function') {
+            try {
+              options.onProgress({ sentBytes, totalBytes: source.size, chunksDone: index + 1, chunksTotal: chunks_total, index });
+            } catch { /* listener errors must never break the upload */ }
+          }
+        };
+
+        // 2. chunks — sequential 1 MiB PUTs; each response is the progress event
+        for (let i = 0; i < chunks_total; i++) {
+          const start = i * chunk_size;
+          const end = Math.min(start + chunk_size, source.size);
+          let attempt = 0;
+          for (;;) {
+            const put = await fetch(`${this._url}/api/v1/blob/${this._apiKey}/chunk/${upload_id}/${i}`, {
+              method: 'PUT',
+              headers: { 'Content-Type': 'application/octet-stream', ...authHeaders },
+              body: source.slice(start, end),
+              signal: options.signal,
+              ...creds,
+            });
+            const r = await put.json().catch(() => ({}));
+            if (r.status === 'error' || r.code) {
+              // Retry a failed chunk twice before giving up (server kept the rest).
+              if (++attempt < 3 && put.status >= 500) continue;
+              return fail(r.code || 'CHUNK_FAILED', r.message || `Chunk ${i} failed (HTTP ${put.status})`, r.request_id);
+            }
+            ping(i, r.data?.received_bytes ?? end);
+            break;
+          }
+        }
+
+        // 3. complete — server assembles, verifies size + content, stores
+        const doneRes = await fetch(`${this._url}/api/v1/blob/${this._apiKey}/complete/${upload_id}`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json', ...authHeaders },
+          body: '{}',
+          signal: options.signal,
+          ...creds,
+        });
+        const done = await doneRes.json().catch(() => ({}));
+        if (done.status === 'error' || done.code) {
+          return fail(done.code || 'COMPLETE_FAILED', done.message || `Complete failed (HTTP ${doneRes.status})`, done.request_id);
+        }
+        ping(chunks_total - 1, source.size);
+        if (compression) {
+          return { status: 'success', data: { ...done.data, compression }, error: null, request_id: done.request_id || '' };
+        }
+        return { status: 'success', data: done.data, error: null, request_id: done.request_id || '' };
+      },
+
+      /**
+       * Download a file's bytes.
+       * @param {string} path - File path
+       * @returns {Promise<QueryResult & { data: Blob }>}
+       */
+      download: async (path) => {
+        if (!isPathSafe(path)) {
+          throw new Error('Invalid path: directory traversal not allowed');
+        }
+        try {
+          const isProxy = isProxyBase(this._url);
+          const response = await fetch(`${this._url}/api/v1/blob/${this._apiKey}/${bucket}/${encodePath(path)}`, {
+            ...(isProxy
+              ? { credentials: 'include' }
+              : { headers: { 'Authorization': `Bearer ${getSessionToken()}` } }),
+          });
+          if (!response.ok) {
+            const err = await response.json().catch(() => ({}));
+            return { status: 'error', data: null, error: { code: err.code || 'DOWNLOAD_FAILED', message: err.message || `HTTP ${response.status}` }, request_id: err.request_id || '' };
+          }
+          return { status: 'success', data: await response.blob(), error: null, request_id: '' };
+        } catch (error) {
+          return { status: 'error', data: null, error: { code: 'NETWORK_ERROR', message: error.message }, request_id: '' };
+        }
+      },
+
+      /**
+       * List files
+       * @param {string} [path=''] - Directory path
+       * @param {Object} [options] - List options
+       * @returns {Promise<QueryResult>}
+       */
+      list: async (path = '', options = {}) => {
+        if (!isPathSafe(path)) {
+          throw new Error('Invalid path: directory traversal not allowed');
+        }
+        return this._request({
+          op: 'storage.list',
+          bucket,
+          path,
+          options: { limit: options.limit || 100, offset: options.offset || 0 },
+        });
+      },
+
+      /**
+       * Remove files
+       * @param {string[]} paths - Array of file paths
+       * @returns {Promise<QueryResult>}
+       */
+      remove: async (paths) => {
+        for (const p of paths) {
+          if (!isPathSafe(p)) {
+            throw new Error('Invalid path: directory traversal not allowed');
+          }
+        }
+        return this._request({ op: 'storage.remove', bucket, paths });
+      },
+
+      /**
+       * Same-origin session URL (B15: NOT public despite the name — the GET
+       * still requires the caller's session cookie; outsiders get 401. For
+       * sharing with outsiders use createSignedUrl, which mints a real
+       * HMAC-signed expiring link server-side).
+       * @param {string} path - File path
+       * @returns {string} Session-authenticated object URL (segments encoded)
+       */
+      getPublicUrl: (path) => {
+        if (!isPathSafe(path)) {
+          throw new Error('Invalid path: directory traversal not allowed');
+        }
+        return `${this._url}/api/v1/blob/${this._apiKey}/${bucket}/${encodePath(path)}`;
+      },
+
+      /**
+       * Create a signed URL
+       * @param {string} path - File path
+       * @param {number} [expiresIn=3600] - Expiration in seconds
+       * @returns {Promise<QueryResult>}
+       */
+      createSignedUrl: async (path, expiresIn = 3600) => {
+        if (!isPathSafe(path)) {
+          throw new Error('Invalid path: directory traversal not allowed');
+        }
+        const safeExpiry = Math.min(expiresIn, 7 * 24 * 60 * 60);
+        return this._request({
+          op: 'storage.getSignedUrl',
+          bucket,
+          path,
+          expires_in: safeExpiry,
+        });
+      },
+    };
+  }
+
+  async _request(body) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 60000);
+
+    try {
+      const { fetchUrl, opts } = buildFetchOpts(this._url, this._apiKey, body, controller.signal);
+      const response = await fetch(fetchUrl, opts);
+
+      const result = await response.json();
+      return result;
+    } catch (error) {
+      if (error.name === 'AbortError') {
+        return {
+          status: 'error',
+          error: { code: 'TIMEOUT', message: 'Request timed out' },
+          request_id: '',
+        };
+      }
+      return {
+        status: 'error',
+        error: { code: 'NETWORK_ERROR', message: error.message },
+        request_id: '',
+      };
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+}
+
+// ─── Compression (client-side, pre-upload) ───────────────────────────────────
+// Zero-dependency: Canvas 2D for images, native CompressionStream for generic
+// files. Everything runs on the user's device so fewer bytes hit the network.
+// Confirmed platform facts (researched 2026-09):
+// - CompressionStream gzip/deflate: Baseline, all browsers since May 2023.
+// - canvas.toBlob: PNG guaranteed; jpeg/webp widely supported BUT Safari may
+//   silently fall back to PNG when webp encode is missing — so we NEVER trust
+//   the requested mime; the reported contentType is always out.type.
+// - Video transcode (360p) needs WebCodecs + a muxer lib (WebCodecs emits raw
+//   packets, not a playable file) — intentionally NOT in core; see Phase 2.
+
+const COMPRESS_MODES = new Set(['auto', 'image', 'gzip', 'deflate', 'deflate-raw', 'none']);
+const COMPRESS_IMAGE_FORMATS = new Set(['original', 'webp', 'jpeg', 'jpg', 'png']);
+const COMPRESS_MAX_DIM = 8192; // sanity cap per side (px)
+const COMPRESS_MAX_BYTES = 500 * 1024 * 1024; // 500 MB in/out cap (memory safety)
+
+function canCompressImage() {
+  return typeof createImageBitmap === 'function'
+    && typeof document !== 'undefined'
+    && typeof document.createElement === 'function';
+}
+
+function canGzip() {
+  if (typeof CompressionStream === 'function') return true;
+  return typeof globalThis !== 'undefined' && typeof globalThis.CompressionStream === 'function';
+}
+
+function getCompressionStream(format) {
+  const CS = typeof CompressionStream === 'function' ? CompressionStream : globalThis.CompressionStream;
+  return new CS(format);
+}
+
+/**
+ * Which compression backends exist in this environment.
+ * @returns {{image: boolean, gzip: boolean}}
+ */
+function supportsCompression() {
+  return { image: canCompressImage(), gzip: canGzip() };
+}
+
+function normalizeCompressOptions(input) {
+  if (input === true) input = { mode: 'auto' };
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw new Error('Invalid compress options: pass true or an options object');
+  }
+  const o = {
+    mode: 'auto',
+    maxWidth: 1920,
+    maxHeight: 1920,
+    quality: 0.8,
+    format: 'original',
+    lossless: false,
+    force: false,
+    signal: undefined,
+    ...input,
+  };
+  if (!COMPRESS_MODES.has(o.mode)) {
+    throw new Error(`Unknown compress mode: ${o.mode} (auto|image|gzip|deflate|deflate-raw|none)`);
+  }
+  for (const k of ['maxWidth', 'maxHeight']) {
+    if (!Number.isInteger(o[k]) || o[k] < 1 || o[k] > COMPRESS_MAX_DIM) {
+      throw new Error(`Invalid ${k}: integer 1-${COMPRESS_MAX_DIM}`);
+    }
+  }
+  if (typeof o.quality !== 'number' || !(o.quality > 0) || o.quality > 1) {
+    throw new Error('Invalid quality: number in (0, 1]');
+  }
+  const fmt = String(o.format || 'original').toLowerCase();
+  if (!COMPRESS_IMAGE_FORMATS.has(fmt)) {
+    throw new Error(`Unknown image format: ${o.format} (original|webp|jpeg|png)`);
+  }
+  o.format = fmt === 'jpg' ? 'jpeg' : fmt;
+  o.lossless = o.lossless === true;
+  o.force = o.force === true;
+  if (o.signal !== undefined && o.signal !== null && typeof o.signal.aborted !== 'boolean') {
+    throw new Error('Invalid signal: pass an AbortSignal');
+  }
+  return o;
+}
+
+function throwIfAborted(signal) {
+  if (signal && signal.aborted) {
+    const e = new Error('Compression aborted');
+    e.name = 'AbortError';
+    throw e;
+  }
+}
+
+function requireBlob(file) {
+  if (!file || typeof file.size !== 'number' || typeof file.slice !== 'function') {
+    throw new Error('compressFile needs a File or Blob');
+  }
+}
+
+// Image path: decode → scale-to-fit (aspect preserved, never upscale) →
+// re-encode. Lossless (`lossless:true`) forces PNG. JPEG gets a white
+// backdrop (no alpha channel). Anti-corruption: decode/encode failures throw
+// and the caller keeps the original — we never return partial bytes.
+async function compressImageBlob(blob, o) {
+  if (!canCompressImage()) {
+    throw new Error('Image compression needs a browser (canvas/createImageBitmap unavailable)');
+  }
+  throwIfAborted(o.signal);
+  let bitmap;
+  try {
+    bitmap = await createImageBitmap(blob);
+  } catch {
+    throw new Error('Could not decode image (unsupported or corrupt file — original kept)');
+  }
+  try {
+    throwIfAborted(o.signal);
+    const scale = Math.min(1, o.maxWidth / bitmap.width, o.maxHeight / bitmap.height);
+    const w = Math.max(1, Math.round(bitmap.width * scale));
+    const h = Math.max(1, Math.round(bitmap.height * scale));
+    const canvas = document.createElement('canvas');
+    canvas.width = w;
+    canvas.height = h;
+    const ctx = canvas.getContext('2d');
+    if (!ctx) throw new Error('Canvas 2D unavailable — original kept');
+    let mime;
+    if (o.lossless) mime = 'image/png';
+    else if (o.format === 'original') mime = (blob.type && blob.type.startsWith('image/')) ? blob.type : 'image/jpeg';
+    else mime = `image/${o.format}`;
+    if (mime === 'image/jpeg') {
+      ctx.fillStyle = '#ffffff';
+      ctx.fillRect(0, 0, w, h);
+    }
+    ctx.drawImage(bitmap, 0, 0, w, h);
+    throwIfAborted(o.signal);
+    const q = (o.lossless || mime === 'image/png') ? undefined : o.quality;
+    const out = await new Promise((resolve, reject) => {
+      try {
+        canvas.toBlob(b => (b ? resolve(b) : reject(new Error('Image encode failed — original kept'))), mime, q);
+      } catch (err) {
+        reject(err);
+      }
+    });
+    canvas.width = 0;
+    canvas.height = 0;
+    return out;
+  } finally {
+    try { bitmap.close && bitmap.close(); } catch { /* noop */ }
+  }
+}
+
+// Generic lossless path: stream through native CompressionStream and collect.
+// Manual reader (no Response dependency) with an output cap for memory safety.
+async function compressGzipBlob(blob, format, signal) {
+  if (!canGzip()) {
+    throw new Error('Gzip compression needs CompressionStream (modern browser or Node 18+)');
+  }
+  if (typeof blob.stream !== 'function') {
+    throw new Error('This file cannot be streamed for compression');
+  }
+  throwIfAborted(signal);
+  const stream = blob.stream().pipeThrough(getCompressionStream(format));
+  const reader = stream.getReader();
+  const chunks = [];
+  let total = 0;
+  for (;;) {
+    throwIfAborted(signal);
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > COMPRESS_MAX_BYTES) {
+      try { await reader.cancel(); } catch { /* noop */ }
+      throw new Error('Compressed output exceeds 500 MB cap — original kept');
+    }
+    chunks.push(value);
+  }
+  const merged = new Uint8Array(total);
+  let off = 0;
+  for (const c of chunks) {
+    merged.set(c, off);
+    off += c.byteLength;
+  }
+  const out = new Blob([merged], { type: 'application/gzip' });
+  if (!out.size) throw new Error('Compression produced empty output — original kept');
+  return out;
+}
+
+/**
+ * Compress a file client-side before upload.
+ *
+ * Modes:
+ * - 'auto' (default): images → canvas resize/re-encode, everything else →
+ *   gzip. Degrades gracefully (image w/o canvas falls through to gzip).
+ * - 'image': images only. Params: maxWidth/maxHeight (default 1920, aspect
+ *   preserved, never upscales), quality (0,1] default 0.8 (jpeg/webp only),
+ *   format original|webp|jpeg|png, lossless:true forces PNG.
+ * - 'gzip'|'deflate'|'deflate-raw': lossless, any file type. Output is
+ *   `application/gzip` — decompress after download.
+ * - 'none': passthrough (no-op, still validates).
+ *
+ * Never corrupts: any decode/encode/stream failure throws and the original
+ * Blob is untouched. Unless `force:true`, an output >= input returns the
+ * original with `compressed:false`.
+ *
+ * @param {File|Blob} file - File to compress
+ * @param {Object|boolean} [options] - true = defaults, or CompressOptions
+ * @param {string} [options.mode='auto']
+ * @param {number} [options.maxWidth=1920] - integer 1-8192
+ * @param {number} [options.maxHeight=1920] - integer 1-8192
+ * @param {number} [options.quality=0.8] - (0,1], lossy formats only
+ * @param {string} [options.format='original'] - original|webp|jpeg|png
+ * @param {boolean} [options.lossless=false] - force lossless PNG (images)
+ * @param {boolean} [options.force=false] - keep output even if larger
+ * @param {AbortSignal} [options.signal] - abort compression
+ * @returns {Promise<{file: Blob, compressed: boolean, mode: string, originalSize: number, compressedSize: number, contentType: string}>}
+ */
+export async function compressFile(file, options = {}) {
+  const o = normalizeCompressOptions(options);
+  requireBlob(file);
+  if (file.size === 0) throw new Error('Cannot compress an empty file');
+  if (file.size > COMPRESS_MAX_BYTES) throw new Error('File too large to compress (max 500 MB)');
+  if (o.mode === 'none') {
+    return { file, compressed: false, mode: 'none', originalSize: file.size, compressedSize: file.size, contentType: file.type || 'application/octet-stream' };
+  }
+  const isImage = typeof file.type === 'string' && file.type.startsWith('image/');
+  let out = file;
+  let applied = 'none';
+  if (o.mode === 'auto') {
+    if (isImage && canCompressImage()) {
+      out = await compressImageBlob(file, o);
+      applied = 'image';
+    } else if (canGzip()) {
+      out = await compressGzipBlob(file, 'gzip', o.signal);
+      applied = 'gzip';
+    } else {
+      throw new Error('No compression available in this environment');
+    }
+  } else if (o.mode === 'image') {
+    if (!isImage) throw new Error('Image mode needs an image/* file');
+    out = await compressImageBlob(file, o);
+    applied = 'image';
+  } else {
+    out = await compressGzipBlob(file, o.mode, o.signal);
+    applied = o.mode;
+  }
+  // Trust the bytes, not the request: Safari may fall back to PNG for webp.
+  const contentType = out.type || (applied === 'image' ? (file.type || 'application/octet-stream') : 'application/gzip');
+  if (!o.force && out.size >= file.size) {
+    return { file, compressed: false, mode: 'none', originalSize: file.size, compressedSize: file.size, contentType: file.type || 'application/octet-stream' };
+  }
+  const typed = out.type ? out : new Blob([out], { type: contentType });
+  return { file: typed, compressed: true, mode: applied, originalSize: file.size, compressedSize: typed.size, contentType };
+}
+
+compressFile.supports = supportsCompression;
+
+// ─── Session Management ──────────────────────────────────────────────────────
+
+let _sessionToken = null;
+
+function getSessionToken() {
+  return _sessionToken;
+}
+
+function setSessionToken(token) {
+  _sessionToken = token;
+}
+
+// ─── Main Export ─────────────────────────────────────────────────────────────
+
+/**
+ * Create a Fenaura client
+ * @param {string} url - Fenaura server URL or proxy path (e.g. '/fenaura' after `npx @fenaura/sdk init` for cookies, or 'https://api.fenaura.com' for direct Bearer)
+ * @param {string} apiKey - Project slug or ID
+ * @param {import('./fenaura-client.d.ts').ClientOptions} [options] - Client options { schema, timeout, proxy }
+ * @returns {import('./fenaura-client.d.ts').FenauraClient} Fenaura client (fenaura.from, fenaura.auth, fenaura.storage)
+ */
+export function createClient(url, apiKey, options = {}) {
+  // PARANOIA: Validate inputs
+  if (!url || typeof url !== 'string') {
+    throw new Error('URL is required');
+  }
+  if (!apiKey || typeof apiKey !== 'string') {
+    throw new Error('Project slug is required');
+  }
+  // Validate URL format (allow proxy path like '/fenaura')
+  if (!url.startsWith('/')) {
+    try {
+      new URL(url);
+    } catch {
+      throw new Error('Invalid URL format');
+    }
+  }
+  // Validate project slug
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(apiKey)) {
+    throw new Error('Invalid project slug');
+  }
+
+  return {
+    /**
+     * Query a table
+     * @param {string} table - Table name
+     * @returns {QueryBuilder}
+     */
+    from: (table) => new QueryBuilder(url, apiKey, table, options),
+
+    /**
+     * Switch schema
+     * @param {string} schema - Schema name
+     * @returns {Object} Client with schema set
+     */
+    schema: (schema) => createClient(url, apiKey, { ...options, schema }),
+
+    /**
+     * Call a Postgres function
+     * @param {string} fn - Function name
+     * @param {Object} [args] - Function arguments
+     * @param {Object} [options] - RPC options
+     * @returns {Promise<QueryResult>}
+     */
+    rpc: async (fn, args = {}, options = {}) => {
+      validateTableName(fn);
+      const body = {
+        op: 'rpc',
+        function: fn,
+        args,
+        ...options,
+      };
+
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), options.timeout || 30000);
+
+      try {
+        const isProxy = isProxyBase(url);
+        const fetchUrl = `${url}/api/v1/data/${apiKey}`;
+        const headers = { 'Content-Type': 'application/json' };
+        if (!isProxy) {
+    const tok = getSessionToken();
+    if (!tok) {
+      try { console.warn('[fenaura] direct (non-proxy) mode without setSession(token): requests will 401. Call fenaura.setSession(token) or use createClient(\'/fenaura\', id).'); } catch { /* ignore */ }
+    }
+    headers['Authorization'] = `Bearer ${tok}`;
+  }
+        const response = await fetch(fetchUrl, {
+          method: 'POST',
+          headers,
+          body: JSON.stringify(body),
+          signal: controller.signal,
+          ...(isProxy ? { credentials: 'include' } : {}),
+        });
+
+        const result = await response.json();
+        return result;
+      } catch (error) {
+        if (error.name === 'AbortError') {
+          return {
+            status: 'error',
+            error: { code: 'TIMEOUT', message: 'Request timed out' },
+            request_id: '',
+          };
+        }
+        return {
+          status: 'error',
+          error: { code: 'NETWORK_ERROR', message: error.message },
+          request_id: '',
+        };
+      } finally {
+        clearTimeout(timeoutId);
+      }
+    },
+
+    /**
+     * Auth client
+     */
+    auth: new AuthClient(url, apiKey),
+
+    /**
+     * Storage client
+     */
+    storage: new StorageClient(url, apiKey),
+
+    /**
+     * Channel (placeholder for future realtime support)
+     */
+    channel: (name) => {
+      throw new Error('Realtime not yet supported');
+    },
+
+    /**
+     * Set session token
+     * @param {string} token - Session token
+     */
+    setSession: (token) => setSessionToken(token),
+
+    /**
+     * Get session token
+     * @returns {string|null}
+     */
+    getSession: () => getSessionToken(),
+  };
+}
+
+// ─── UMD Export ──────────────────────────────────────────────────────────────
+
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = { createClient, compressFile };
+}
+if (typeof window !== 'undefined') {
+  window.FenauraClient = { createClient, compressFile };
+}