hydrousdb 1.1.1 → 2.0.1

package/dist/index.mjs

@@ -1,801 +1,1291 @@
 // src/utils/errors.ts
-var HydrousError = class extends Error {
-  constructor(body, status) {
-    super(body.error);
-    this.name = "HydrousError";
+var HydrousSDKError = class extends Error {
+  constructor(message, code = "SDK_ERROR", status) {
+    super(message);
+    this.name = "HydrousSDKError";
+    this.code = code;
     this.status = status;
-    this.code = body.code;
-    this.details = body.details ?? [];
-    this.requestId = body.requestId;
   }
 };
-var HydrousNetworkError = class extends Error {
-  constructor(message, cause) {
-    super(message);
-    this.name = "HydrousNetworkError";
-    this.cause = cause;
+function toHydrousError(err) {
+  if (err instanceof HydrousSDKError) {
+    return { message: err.message, code: err.code, status: err.status };
   }
-};
-var HydrousTimeoutError = class extends Error {
-  constructor(timeoutMs) {
-    super(`Request timed out after ${timeoutMs}ms`);
-    this.name = "HydrousTimeoutError";
+  if (err instanceof Error) {
+    return { message: err.message, code: "UNKNOWN_ERROR" };
   }
-};
+  return { message: String(err), code: "UNKNOWN_ERROR" };
+}
+function isHydrousError(err) {
+  return err instanceof HydrousSDKError;
+}
 
 // src/utils/http.ts
-var DEFAULT_BASE_URL = "https://db-api-82687684612.us-central1.run.app";
-var DEFAULT_TIMEOUT = 3e4;
-var DEFAULT_RETRIES = 2;
-var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([408, 429, 500, 502, 503, 504]);
-var HttpClient = class {
-  constructor(config) {
-    this.authKey = config.authKey;
-    this.bucketKey = config.bucketKey;
-    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
-    this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
-    this.retries = config.retries ?? DEFAULT_RETRIES;
-  }
-  // ── Core request ────────────────────────────────────────────────────────────
-  async request(method, path, options) {
-    const url = this.buildUrl(path, options?.params);
-    const headers = {
-      "Content-Type": "application/json",
-      ...options?.headers
-    };
-    const init = {
-      method,
-      headers,
-      signal: this.buildSignal(options?.signal)
-    };
-    if (options?.body !== void 0) {
-      init.body = JSON.stringify(options.body);
+async function parseResponse(res) {
+  let body;
+  try {
+    body = await res.json();
+  } catch (e) {
+    if (!res.ok) {
+      throw new HydrousSDKError(`HTTP ${res.status}`, "HTTP_ERROR", res.status);
     }
-    return this.executeWithRetry(url, init, options?.raw ?? false, this.retries);
+    return void 0;
   }
-  // ── Convenience methods ──────────────────────────────────────────────────────
-  get(path, params, opts) {
-    return this.request("GET", path, { params, ...opts });
-  }
-  post(path, body, opts) {
-    return this.request("POST", path, { body, ...opts });
-  }
-  patch(path, body, opts) {
-    return this.request("PATCH", path, { body, ...opts });
-  }
-  delete(path, params, opts) {
-    return this.request("DELETE", path, { params, ...opts });
-  }
-  head(path, params, opts) {
-    return this.request("HEAD", path, { params, raw: true, ...opts });
+  if (!res.ok) {
+    const err = body;
+    throw new HydrousSDKError(
+      err.error || err.message || `HTTP ${res.status}`,
+      err.code || "HTTP_ERROR",
+      res.status
+    );
   }
-  // ── Internals ────────────────────────────────────────────────────────────────
-  buildUrl(path, params) {
-    const url = new URL(`${this.baseUrl}${path}`);
-    if (params) {
-      for (const [k, v] of Object.entries(params)) {
-        if (v !== void 0 && v !== null && v !== "") {
-          url.searchParams.set(k, String(v));
-        }
+  return body;
+}
+function buildUrl(base, path, params) {
+  const url = new URL(path, base.endsWith("/") ? base : base + "/");
+  if (params) {
+    for (const [k, v] of Object.entries(params)) {
+      if (v !== void 0 && v !== null) {
+        url.searchParams.set(k, String(v));
       }
     }
-    return url.toString();
   }
-  buildSignal(userSignal) {
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort("timeout"), this.timeout);
-    userSignal?.addEventListener("abort", () => {
-      clearTimeout(timeoutId);
-      controller.abort(userSignal.reason);
-    });
-    return controller.signal;
-  }
-  async executeWithRetry(url, init, raw, retriesLeft) {
-    try {
-      const res = await fetch(url, init);
-      if (raw) return res;
-      if (res.ok) {
-        if (res.status === 204) return void 0;
-        return await res.json();
+  return url.toString();
+}
+function mergeHeaders(defaults, overrides) {
+  return { ...defaults, ...overrides };
+}
+async function readSSEStream(response, onEvent) {
+  if (!response.body) return;
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buf = "";
+  const flush = (chunk) => {
+    var _a;
+    buf += chunk;
+    const blocks = buf.split("\n\n");
+    buf = (_a = blocks.pop()) != null ? _a : "";
+    for (const block of blocks) {
+      if (!block.trim()) continue;
+      let eventType = "message";
+      let dataLine = null;
+      for (const line of block.split("\n")) {
+        if (line.startsWith("event:")) eventType = line.slice(6).trim();
+        if (line.startsWith("data:")) dataLine = line.slice(5).trim();
       }
-      let body;
+      if (dataLine === null) continue;
       try {
-        body = await res.json();
-      } catch {
-        body = { success: false, error: `HTTP ${res.status}: ${res.statusText}` };
-      }
-      if (retriesLeft > 0 && RETRYABLE_STATUSES.has(res.status)) {
-        await sleep(500 * (this.retries - retriesLeft + 1));
-        return this.executeWithRetry(url, init, raw, retriesLeft - 1);
-      }
-      throw new HydrousError(body, res.status);
-    } catch (err) {
-      if (err instanceof HydrousError) throw err;
-      if (err instanceof Error && err.message === "timeout") {
-        throw new HydrousTimeoutError(this.timeout);
+        onEvent(eventType, JSON.parse(dataLine));
+      } catch (e) {
       }
-      if (retriesLeft > 0) {
-        await sleep(500 * (this.retries - retriesLeft + 1));
-        return this.executeWithRetry(url, init, raw, retriesLeft - 1);
-      }
-      throw new HydrousNetworkError(
-        `Network request failed: ${err instanceof Error ? err.message : String(err)}`,
-        err
-      );
     }
+  };
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    flush(decoder.decode(value, { stream: true }));
   }
-};
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+  if (buf.trim()) flush("");
 }
-
-// src/utils/query.ts
-function buildQueryParams(opts) {
-  const params = {};
-  if (opts.timeScope) params["timeScope"] = opts.timeScope;
-  if (opts.year) params["year"] = opts.year;
-  if (opts.sortOrder) params["sortOrder"] = opts.sortOrder;
-  if (opts.limit) params["limit"] = opts.limit;
-  if (opts.cursor) params["cursor"] = opts.cursor;
-  if (opts.fields) params["fields"] = opts.fields;
-  for (const filter of opts.filters ?? []) {
-    const paramKey = filter.op === "==" ? filter.field : `${filter.field}[${filter.op}]`;
-    params[paramKey] = filter.value;
-  }
-  return params;
+function xhrUpload(url, body, headers, onXhrProgress) {
+  return new Promise((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+    xhr.open("POST", url);
+    for (const [key, val] of Object.entries(headers)) {
+      xhr.setRequestHeader(key, val);
+    }
+    xhr.responseType = "text";
+    if (onXhrProgress) {
+      xhr.upload.onprogress = (e) => {
+        if (e.lengthComputable) onXhrProgress(e.loaded, e.total);
+      };
+    }
+    xhr.onload = () => {
+      var _a;
+      if (xhr.status >= 200 && xhr.status < 300) {
+        resolve(xhr.responseText);
+      } else {
+        try {
+          const d = JSON.parse(xhr.responseText);
+          reject(new HydrousSDKError((_a = d.error) != null ? _a : `HTTP ${xhr.status}`, "HTTP_ERROR", xhr.status));
+        } catch (e) {
+          reject(new HydrousSDKError(`HTTP ${xhr.status}`, "HTTP_ERROR", xhr.status));
+        }
+      }
+    };
+    xhr.onerror = () => reject(new HydrousSDKError("Network error", "NETWORK_ERROR"));
+    xhr.onabort = () => reject(new HydrousSDKError("Upload aborted", "UPLOAD_ABORTED"));
+    xhr.ontimeout = () => reject(new HydrousSDKError("Upload timed out", "UPLOAD_TIMEOUT"));
+    xhr.send(body);
+  });
 }
-function validateFilters(filters) {
-  const VALID_OPS = /* @__PURE__ */ new Set(["==", "!=", ">", "<", ">=", "<=", "contains"]);
-  if (filters.length > 3) {
-    throw new Error("HydrousDB supports a maximum of 3 filters per query.");
-  }
-  for (const f of filters) {
-    if (!VALID_OPS.has(f.op)) {
-      throw new Error(
-        `Invalid filter operator "${f.op}". Valid operators: ${[...VALID_OPS].join(", ")}`
-      );
+function parseSSEText(text, onEvent) {
+  const blocks = text.split("\n\n");
+  for (const block of blocks) {
+    if (!block.trim()) continue;
+    let eventType = "message";
+    let dataLine = null;
+    for (const line of block.split("\n")) {
+      if (line.startsWith("event:")) eventType = line.slice(6).trim();
+      if (line.startsWith("data:")) dataLine = line.slice(5).trim();
     }
-    if (!f.field || typeof f.field !== "string") {
-      throw new Error('Each filter must have a non-empty "field" string.');
+    if (dataLine === null) continue;
+    try {
+      onEvent(eventType, JSON.parse(dataLine));
+    } catch (e) {
     }
   }
 }
 
-// src/records/client.ts
-var RecordsClient = class {
-  constructor(http) {
-    this.http = http;
-  }
-  get path() {
-    return `/api/${this.http.bucketKey}`;
+// src/auth/client.ts
+var AuthClient = class {
+  constructor(config) {
+    this.session = null;
+    this.baseUrl = config.url;
+    this.headers = {
+      "Content-Type": "application/json",
+      "Authorization": `Bearer ${config.apiKey}`
+    };
   }
-  // ── GET — single record ────────────────────────────────────────────────────
+  // ─── SIGN UP ───────────────────────────────────────────────────────────────
   /**
-   * Fetch a single record by ID.
+   * Create a new user account and return a session.
    *
    * @example
-   * const { data } = await db.records.get('rec_abc123');
-   * const { data, history } = await db.records.get('rec_abc123', { showHistory: true });
+   * const { data, error } = await hydrous.auth.signUp({
+   *   email:    'user@example.com',
+   *   password: 'supersecret',
+   * });
    */
-  async get(recordId, options) {
-    const params = { recordId };
-    if (options?.showHistory) params["showHistory"] = "true";
-    return this.http.get(this.path, params, options);
+  async signUp(options) {
+    try {
+      const url = buildUrl(this.baseUrl, "auth/signup");
+      const res = await fetch(url, {
+        method: "POST",
+        headers: this.headers,
+        body: JSON.stringify(options)
+      });
+      const json = await parseResponse(res);
+      this.session = json.data;
+      return { data: json.data, error: null };
+    } catch (err) {
+      return { data: null, error: toHydrousError(err) };
+    }
   }
-  // ── GET — historical snapshot ──────────────────────────────────────────────
+  // ─── SIGN IN ───────────────────────────────────────────────────────────────
   /**
-   * Fetch a specific historical version (generation) of a record.
+   * Sign in with email and password.
    *
    * @example
-   * const { data } = await db.records.getSnapshot('rec_abc123', '1700000000000000');
+   * const { data, error } = await hydrous.auth.signIn({
+   *   email:    'user@example.com',
+   *   password: 'supersecret',
+   * });
+   * if (data) console.log('Signed in as', data.user.email);
    */
-  async getSnapshot(recordId, generation, opts) {
-    return this.http.get(this.path, { recordId, generation }, opts);
+  async signIn(options) {
+    try {
+      const url = buildUrl(this.baseUrl, "auth/signin");
+      const res = await fetch(url, {
+        method: "POST",
+        headers: this.headers,
+        body: JSON.stringify(options)
+      });
+      const json = await parseResponse(res);
+      this.session = json.data;
+      return { data: json.data, error: null };
+    } catch (err) {
+      return { data: null, error: toHydrousError(err) };
+    }
   }
-  // ── GET — collection query ─────────────────────────────────────────────────
+  // ─── SIGN OUT ──────────────────────────────────────────────────────────────
   /**
-   * Query a collection with optional filters, sorting, and pagination.
-   *
-   * @example
-   * // Simple query
-   * const { data, meta } = await db.records.query({ limit: 50, sortOrder: 'desc' });
-   *
-   * // Filtered query
-   * const { data } = await db.records.query({
-   *   filters: [{ field: 'status', op: '==', value: 'active' }],
-   *   timeScope: '7d',
-   * });
-   *
-   * // Paginated
-   * let cursor: string | null = null;
-   * do {
-   *   const result = await db.records.query({ limit: 100, cursor: cursor ?? undefined });
-   *   cursor = result.meta.nextCursor;
-   * } while (cursor);
+   * Sign out the current user and invalidate their session.
    */
-  async query(options) {
-    if (options?.filters) validateFilters(options.filters);
-    const params = buildQueryParams(options ?? {});
-    return this.http.get(this.path, params, options);
+  async signOut() {
+    try {
+      const url = buildUrl(this.baseUrl, "auth/signout");
+      const res = await fetch(url, {
+        method: "POST",
+        headers: mergeHeaders(this.headers, this._sessionHeader())
+      });
+      await parseResponse(res);
+      this.session = null;
+      return { data: void 0, error: null };
+    } catch (err) {
+      return { data: null, error: toHydrousError(err) };
+    }
+  }
+  // ─── GET USER ──────────────────────────────────────────────────────────────
+  /** Return the currently authenticated user, or null if not signed in. */
+  async getUser() {
+    try {
+      const url = buildUrl(this.baseUrl, "auth/user");
+      const res = await fetch(url, {
+        headers: mergeHeaders(this.headers, this._sessionHeader())
+      });
+      const json = await parseResponse(res);
+      return { data: json.data, error: null };
+    } catch (err) {
+      return { data: null, error: toHydrousError(err) };
+    }
   }
-  // ── POST — insert ──────────────────────────────────────────────────────────
+  // ─── REFRESH TOKEN ────────────────────────────────────────────────────────
   /**
-   * Insert a new record.
-   *
-   * @example
-   * const { data, meta } = await db.records.insert({
-   *   values: { name: 'Alice', score: 99 },
-   *   queryableFields: ['name'],
-   *   userEmail: 'alice@example.com',
-   * });
+   * Refresh the access token using the stored refresh token.
+   * Called automatically by the SDK when a 401 is received.
    */
-  async insert(payload, opts) {
-    return this.http.post(this.path, payload, opts);
+  async refreshSession() {
+    var _a;
+    if (!((_a = this.session) == null ? void 0 : _a.refreshToken)) {
+      return { data: null, error: { message: "No session", code: "NO_SESSION" } };
+    }
+    try {
+      const url = buildUrl(this.baseUrl, "auth/refresh");
+      const res = await fetch(url, {
+        method: "POST",
+        headers: this.headers,
+        body: JSON.stringify({ refreshToken: this.session.refreshToken })
+      });
+      const json = await parseResponse(res);
+      this.session = json.data;
+      return { data: json.data, error: null };
+    } catch (err) {
+      return { data: null, error: toHydrousError(err) };
+    }
   }
-  // ── PATCH — update ─────────────────────────────────────────────────────────
+  /** Return the current in-memory session (may be null). */
+  getSession() {
+    return this.session;
+  }
+  _sessionHeader() {
+    var _a;
+    return ((_a = this.session) == null ? void 0 : _a.accessToken) ? { "X-Session-Token": this.session.accessToken } : {};
+  }
+};
+
+// src/utils/query.ts
+function serialiseQuery(opts = {}) {
+  var _a;
+  const params = {};
+  if (opts.limit !== void 0) params["limit"] = String(opts.limit);
+  if (opts.offset !== void 0) params["offset"] = String(opts.offset);
+  if (opts.select && opts.select.length > 0) {
+    params["select"] = opts.select.join(",");
+  }
+  if (opts.orderBy) {
+    params["orderBy"] = opts.orderBy.field;
+    params["direction"] = (_a = opts.orderBy.direction) != null ? _a : "asc";
+  }
+  const filters = opts.where ? Array.isArray(opts.where) ? opts.where : [opts.where] : [];
+  if (filters.length > 0) {
+    params["where"] = JSON.stringify(filters);
+  }
+  return params;
+}
+function eq(field, value) {
+  return { field, operator: "eq", value };
+}
+function neq(field, value) {
+  return { field, operator: "neq", value };
+}
+function gt(field, value) {
+  return { field, operator: "gt", value };
+}
+function lt(field, value) {
+  return { field, operator: "lt", value };
+}
+function inArray(field, value) {
+  return { field, operator: "in", value };
+}
+
+// src/records/client.ts
+var RecordsClient = class {
+  constructor(config) {
+    this.baseUrl = config.url;
+    this.headers = {
+      "Content-Type": "application/json",
+      "Authorization": `Bearer ${config.apiKey}`
+    };
+  }
+  // ─── SELECT ────────────────────────────────────────────────────────────────
   /**
-   * Update an existing record.
+   * Query records from a collection.
+   *
+   * @param collection - Collection name (e.g. "users")
+   * @param options    - Filters, ordering, pagination
    *
    * @example
-   * await db.records.update({
-   *   recordId: 'rec_abc123',
-   *   values: { score: 100 },
-   *   track_record_history: true,
+   * const { data, error } = await hydrous.records.select('users', {
+   *   where:   { field: 'role', operator: 'eq', value: 'admin' },
+   *   orderBy: { field: 'createdAt', direction: 'desc' },
+   *   limit:   20,
    * });
    */
-  async update(payload, opts) {
-    return this.http.patch(this.path, payload, opts);
+  async select(collection, options = {}) {
+    try {
+      const params = serialiseQuery(options);
+      const url = buildUrl(this.baseUrl, `records/${collection}`, params);
+      const res = await fetch(url, { headers: this.headers });
+      const json = await parseResponse(res);
+      return { data: json.data, count: json.count, error: null };
+    } catch (err) {
+      return { data: [], count: 0, error: toHydrousError(err) };
+    }
   }
-  // ── DELETE ─────────────────────────────────────────────────────────────────
+  // ─── GET ONE ───────────────────────────────────────────────────────────────
   /**
-   * Delete a record permanently.
+   * Fetch a single record by its ID.
    *
    * @example
-   * await db.records.delete('rec_abc123');
+   * const { data, error } = await hydrous.records.get('users', 'user_abc123');
    */
-  async delete(recordId, opts) {
-    return this.http.delete(this.path, { recordId }, opts);
+  async get(collection, id) {
+    try {
+      const url = buildUrl(this.baseUrl, `records/${collection}/${id}`);
+      const res = await fetch(url, { headers: this.headers });
+      const json = await parseResponse(res);
+      return { data: json.data, error: null };
+    } catch (err) {
+      return { data: null, error: toHydrousError(err) };
+    }
   }
-  // ── HEAD — existence check ─────────────────────────────────────────────────
+  // ─── INSERT ────────────────────────────────────────────────────────────────
   /**
-   * Check whether a record exists without fetching its full data.
-   * Returns `null` if the record is not found.
+   * Insert one or more records into a collection.
    *
-   * @example
-   * const info = await db.records.exists('rec_abc123');
-   * if (info?.exists) console.log('found at', info.updatedAt);
-   */
-  async exists(recordId, opts) {
-    const res = await this.http.head(this.path, { recordId }, opts);
-    if (res.status === 404) return null;
-    if (!res.ok) return null;
-    return {
-      exists: true,
-      id: res.headers.get("X-Record-Id") ?? recordId,
-      createdAt: res.headers.get("X-Created-At") ?? "",
-      updatedAt: res.headers.get("X-Updated-At") ?? "",
-      sizeBytes: res.headers.get("X-Size-Bytes") ?? ""
-    };
-  }
-  // ── Batch — update ─────────────────────────────────────────────────────────
-  /**
-   * Update up to 500 records in a single request.
+   * @param collection - Collection name
+   * @param payload    - A single record object or an array of record objects
    *
    * @example
-   * await db.records.batchUpdate({
-   *   updates: [
-   *     { recordId: 'rec_1', values: { status: 'archived' } },
-   *     { recordId: 'rec_2', values: { status: 'archived' } },
-   *   ],
+   * // Single insert
+   * const { data, error } = await hydrous.records.insert('users', {
+   *   name: 'Alice', email: 'alice@example.com'
    * });
-   */
-  async batchUpdate(payload, opts) {
-    return this.http.post(
-      `${this.path}/batch/update`,
-      payload,
-      opts
-    );
-  }
-  // ── Batch — delete ─────────────────────────────────────────────────────────
-  /**
-   * Delete up to 500 records in a single request.
    *
-   * @example
-   * await db.records.batchDelete({ recordIds: ['rec_1', 'rec_2', 'rec_3'] });
+   * // Bulk insert
+   * const { data, error } = await hydrous.records.insert('users', [
+   *   { name: 'Alice' }, { name: 'Bob' }
+   * ]);
    */
-  async batchDelete(payload, opts) {
-    return this.http.post(
-      `${this.path}/batch/delete`,
-      payload,
-      opts
-    );
+  async insert(collection, payload) {
+    try {
+      const url = buildUrl(this.baseUrl, `records/${collection}`);
+      const res = await fetch(url, {
+        method: "POST",
+        headers: this.headers,
+        body: JSON.stringify(payload)
+      });
+      const json = await parseResponse(res);
+      return { data: json.data, count: json.count, error: null };
+    } catch (err) {
+      return { data: [], count: 0, error: toHydrousError(err) };
+    }
   }
-  // ── Batch — insert ─────────────────────────────────────────────────────────
+  // ─── UPDATE ────────────────────────────────────────────────────────────────
   /**
-   * Insert up to 500 records in a single request.
-   * Returns HTTP 207 (multi-status) — check `meta.failed` for partial failures.
+   * Update a record by ID.
    *
    * @example
-   * const result = await db.records.batchInsert({
-   *   records: [{ name: 'Alice' }, { name: 'Bob' }],
-   *   queryableFields: ['name'],
+   * const { data, error } = await hydrous.records.update('users', 'user_abc123', {
+   *   name: 'Alice Smith'
    * });
    */
-  async batchInsert(payload, opts) {
-    return this.http.post(
-      `${this.path}/batch/insert`,
-      payload,
-      opts
-    );
+  async update(collection, id, payload) {
+    try {
+      const url = buildUrl(this.baseUrl, `records/${collection}/${id}`);
+      const res = await fetch(url, {
+        method: "PATCH",
+        headers: this.headers,
+        body: JSON.stringify(payload)
+      });
+      const json = await parseResponse(res);
+      return { data: json.data, error: null };
+    } catch (err) {
+      return { data: null, error: toHydrousError(err) };
+    }
   }
-  // ── Helpers ────────────────────────────────────────────────────────────────
+  // ─── DELETE ────────────────────────────────────────────────────────────────
   /**
-   * Fetch ALL records matching a query, automatically following cursors.
-   * Use with care on large collections — prefer `query()` with manual pagination.
+   * Delete a record by ID.
    *
    * @example
-   * const allRecords = await db.records.queryAll({
-   *   filters: [{ field: 'type', op: '==', value: 'invoice' }],
-   * });
+   * const { error } = await hydrous.records.delete('users', 'user_abc123');
    */
-  async queryAll(options) {
-    const all = [];
-    let cursor = null;
-    do {
-      const result = await this.query(cursor ? { ...options, cursor } : { ...options });
-      all.push(...result.data);
-      cursor = result.meta.nextCursor ?? null;
-    } while (cursor);
-    return all;
+  async delete(collection, id) {
+    try {
+      const url = buildUrl(this.baseUrl, `records/${collection}/${id}`);
+      const res = await fetch(url, { method: "DELETE", headers: this.headers });
+      await parseResponse(res);
+      return { data: void 0, error: null };
+    } catch (err) {
+      return { data: null, error: toHydrousError(err) };
+    }
   }
 };
 
-// src/auth/client.ts
-var AuthClient = class {
-  constructor(http) {
-    this.http = http;
-  }
-  get path() {
-    return `/auth/${this.http.authKey}`;
+// src/analytics/client.ts
+var AnalyticsClient = class {
+  constructor(config) {
+    this.baseUrl = config.url;
+    this.headers = {
+      "Content-Type": "application/json",
+      "Authorization": `Bearer ${config.apiKey}`
+    };
   }
-  // ── Sign-up ────────────────────────────────────────────────────────────────
+  // ─── TRACK ────────────────────────────────────────────────────────────────
   /**
-   * Create a new user account. Returns the user and a session immediately.
+   * Track an analytics event.
    *
    * @example
-   * const { data, session } = await db.auth.signUp({
-   *   email: 'alice@example.com',
-   *   password: 'Str0ngP@ss!',
-   *   fullName: 'Alice Smith',
+   * await hydrous.analytics.track({
+   *   event:      'page_view',
+   *   properties: { page: '/home', referrer: 'google.com' },
+   *   userId:     'user_abc123',
    * });
-   * // Store session.sessionId and session.refreshToken in your app
    */
-  async signUp(payload, opts) {
-    return this.http.post(`${this.path}/signup`, payload, opts);
+  async track(options) {
+    var _a;
+    try {
+      const url = buildUrl(this.baseUrl, "analytics/track");
+      const res = await fetch(url, {
+        method: "POST",
+        headers: this.headers,
+        body: JSON.stringify({
+          ...options,
+          timestamp: (_a = options.timestamp) != null ? _a : Date.now()
+        })
+      });
+      await parseResponse(res);
+      return { data: void 0, error: null };
+    } catch (err) {
+      return { data: null, error: toHydrousError(err) };
+    }
   }
-  // ── Sign-in ────────────────────────────────────────────────────────────────
+  // ─── QUERY ────────────────────────────────────────────────────────────────
   /**
-   * Authenticate with email + password. Returns user data and a new session.
+   * Query recorded analytics events.
    *
    * @example
-   * const { data, session } = await db.auth.signIn({
-   *   email: 'alice@example.com',
-   *   password: 'Str0ngP@ss!',
+   * const { data } = await hydrous.analytics.query({
+   *   event: 'page_view',
+   *   from:  '2024-01-01',
+   *   to:    '2024-01-31',
+   *   limit: 100,
    * });
    */
-  async signIn(payload, opts) {
-    return this.http.post(`${this.path}/signin`, payload, opts);
+  async query(options = {}) {
+    try {
+      const params = {};
+      if (options.event) params["event"] = options.event;
+      if (options.from) params["from"] = options.from;
+      if (options.to) params["to"] = options.to;
+      if (options.limit) params["limit"] = String(options.limit);
+      if (options.groupBy) params["groupBy"] = options.groupBy;
+      const url = buildUrl(this.baseUrl, "analytics/events", params);
+      const res = await fetch(url, { headers: this.headers });
+      const json = await parseResponse(res);
+      return { data: json.data, count: json.count, error: null };
+    } catch (err) {
+      return { data: [], count: 0, error: toHydrousError(err) };
+    }
   }
-  // ── Sign-out ───────────────────────────────────────────────────────────────
+  // ─── BATCH TRACK ─────────────────────────────────────────────────────────
   /**
-   * Revoke a session (or all sessions for a user).
+   * Track multiple events in a single request (more efficient than
+   * calling `track` in a loop).
    *
    * @example
-   * // Single device
-   * await db.auth.signOut({ sessionId: 'sess_...' });
-   *
-   * // All devices
-   * await db.auth.signOut({ allDevices: true, userId: 'user_...' });
+   * await hydrous.analytics.trackBatch([
+   *   { event: 'signup',   userId: 'u1' },
+   *   { event: 'onboarded', userId: 'u1' },
+   * ]);
    */
-  async signOut(payload, opts) {
-    return this.http.post(`${this.path}/signout`, payload, opts);
+  async trackBatch(events) {
+    try {
+      const url = buildUrl(this.baseUrl, "analytics/track/batch");
+      const stamped = events.map((e) => {
+        var _a;
+        return {
+          ...e,
+          timestamp: (_a = e.timestamp) != null ? _a : Date.now()
+        };
+      });
+      const res = await fetch(url, {
+        method: "POST",
+        headers: this.headers,
+        body: JSON.stringify({ events: stamped })
+      });
+      await parseResponse(res);
+      return { data: void 0, error: null };
+    } catch (err) {
+      return { data: null, error: toHydrousError(err) };
+    }
   }
-  // ── Session: validate ──────────────────────────────────────────────────────
-  /**
-   * Validate a session token — use this on every protected request in your backend.
-   *
-   * @example
-   * try {
-   *   const { data } = await db.auth.validateSession(sessionId);
-   *   // data is the authenticated user
-   * } catch (err) {
-   *   // Session expired or invalid
-   * }
-   */
-  async validateSession(sessionId, opts) {
-    return this.http.post(`${this.path}/session/validate`, { sessionId }, opts);
+};
+
+// src/storage/client.ts
+var isBrowser = typeof window !== "undefined" && typeof XMLHttpRequest !== "undefined";
+function bucketFromKey(key) {
+  return encodeURIComponent(key);
+}
+function storageUrl(base, bucketKey, path) {
+  const bucket = bucketFromKey(bucketKey);
+  return `${base.replace(/\/$/, "")}/storage/${bucket}/${path.replace(/^\//, "")}`;
+}
+function storageHeaders(bucketKey) {
+  return { "X-Storage-Key": bucketKey };
+}
+function drainSSEProgress(rawText, onProgress) {
+  const results = [];
+  const errors = [];
+  parseSSEText(rawText, (eventType, data) => {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l;
+    const d = data;
+    if (eventType === "progress" && onProgress) {
+      onProgress({
+        index: (_a = d["index"]) != null ? _a : 0,
+        total: (_b = d["total"]) != null ? _b : 1,
+        path: (_c = d["path"]) != null ? _c : "",
+        stage: (_d = d["stage"]) != null ? _d : "uploading",
+        bytesUploaded: (_e = d["bytesUploaded"]) != null ? _e : 0,
+        totalBytes: (_f = d["totalBytes"]) != null ? _f : 0,
+        percent: (_g = d["percent"]) != null ? _g : 0,
+        bytesPerSecond: (_h = d["bytesPerSecond"]) != null ? _h : null,
+        eta: (_i = d["eta"]) != null ? _i : null,
+        result: d["result"],
+        error: d["error"],
+        code: d["code"]
+      });
+    }
+    if (eventType === "done") {
+      if (d["path"]) {
+        results.push(d);
+      } else if (Array.isArray(d["errors"])) {
+        const succeeded = (_j = d["succeeded"]) != null ? _j : [];
+        const errs = d["errors"];
+        results.push(...succeeded);
+        errors.push(...errs);
+      }
+    }
+    if (eventType === "error") {
+      errors.push({
+        path: "",
+        error: (_k = d["error"]) != null ? _k : "Unknown error",
+        code: (_l = d["code"]) != null ? _l : "UNKNOWN"
+      });
+    }
+  });
+  return { results, errors };
+}
+var StorageClient = class {
+  constructor(config) {
+    this.baseUrl = config.url;
   }
-  // ── Session: refresh ───────────────────────────────────────────────────────
+  // ══════════════════════════════════════════════════════════════════════════
+  // UPLOAD
+  // ══════════════════════════════════════════════════════════════════════════
   /**
-   * Exchange a refresh token for a new session (rotation).
-   * The old session is revoked.
+   * Upload a single file to a bucket.
    *
-   * @example
-   * const { session } = await db.auth.refreshSession(refreshToken);
-   */
-  async refreshSession(refreshToken, opts) {
-    return this.http.post(`${this.path}/session/refresh`, { refreshToken }, opts);
-  }
-  // ── User: get ──────────────────────────────────────────────────────────────
-  /**
-   * Fetch a user by their ID.
+   * The bucket key **always comes first**.
+   * Supply an `onProgress` callback to receive live upload progress including
+   * bytes transferred, speed (bytes/sec), ETA, and lifecycle stage.
    *
-   * @example
-   * const { data } = await db.auth.getUser('user_abc123');
-   */
-  async getUser(userId, opts) {
-    return this.http.get(`${this.path}/user`, { userId }, opts);
-  }
-  // ── User: list ─────────────────────────────────────────────────────────────
-  /**
-   * List users with cursor-based pagination.
+   * ### Stages fired via `onProgress`
+   * | Stage        | Meaning                                 |
+   * |-------------|------------------------------------------|
+   * | `pending`   | Queued, not yet started                 |
+   * | `compressing` | Server is compressing the file         |
+   * | `uploading` | Bytes flowing to cloud storage           |
+   * | `done`      | Confirmed written to cloud storage       |
+   * | `error`     | Something went wrong                    |
    *
-   * @example
-   * const { data, meta } = await db.auth.listUsers({ limit: 50 });
-   */
-  async listUsers(options) {
-    const params = {
-      limit: options?.limit
-    };
-    if (options?.cursor) params["cursor"] = options.cursor;
-    return this.http.get(`${this.path}/users`, params, options);
-  }
-  // ── User: update ───────────────────────────────────────────────────────────
-  /**
-   * Update user profile fields.
+   * @param bucketKey  Your storage bucket key (`ssk_…`)
+   * @param file       A `File`, `Blob`, or `Buffer` (Node)
+   * @param options    Path, overwrite flag, progress callback
    *
    * @example
-   * await db.auth.updateUser({ userId: 'user_abc', updates: { fullName: 'Bob Smith' } });
+   * const { data, error } = await hydrous.storage.upload(
+   *   'ssk_my_bucket_key',
+   *   file,
+   *   {
+   *     path:       'avatars/alice.jpg',
+   *     overwrite:  true,
+   *     onProgress: (p) => {
+   *       console.log(`${p.stage} — ${p.percent}%  ${p.bytesPerSecond} B/s  ETA ${p.eta}s`);
+   *     },
+   *   }
+   * );
    */
-  async updateUser(payload, opts) {
-    return this.http.patch(`${this.path}/user`, payload, opts);
+  async upload(bucketKey, file, options = {}) {
+    var _a, _b;
+    const { path, overwrite = false, onProgress } = options;
+    try {
+      const url = storageUrl(this.baseUrl, bucketKey, "upload");
+      const form = new FormData();
+      if (file instanceof Uint8Array) {
+        form.append("file", new Blob([file.buffer]), path != null ? path : "file");
+      } else if (file instanceof ArrayBuffer) {
+        form.append("file", new Blob([file]), path != null ? path : "file");
+      } else {
+        form.append("file", file, path != null ? path : file instanceof File ? file.name : "file");
+      }
+      if (path) form.append("path", path);
+      if (overwrite) form.append("overwrite", "true");
+      const headers = storageHeaders(bucketKey);
+      if (isBrowser) {
+        const totalBytes = file instanceof Blob ? file.size : file instanceof Uint8Array ? file.byteLength : file.byteLength;
+        const rawBody = await xhrUpload(url, form, headers, (loaded, total) => {
+          if (onProgress) {
+            onProgress({
+              index: 0,
+              total: 1,
+              path: path != null ? path : "",
+              stage: "uploading",
+              bytesUploaded: loaded,
+              totalBytes: total || totalBytes,
+              percent: Math.min(99, Math.round(loaded / (total || totalBytes) * 100)),
+              bytesPerSecond: null,
+              eta: null
+            });
+          }
+        });
+        const { results, errors } = drainSSEProgress(rawBody, onProgress);
+        if (errors.length > 0 && results.length === 0) {
+          return { data: null, error: { message: errors[0].error, code: errors[0].code } };
+        }
+        const result = (_a = results[0]) != null ? _a : null;
+        if (result && onProgress) {
+          onProgress({
+            index: 0,
+            total: 1,
+            path: result.path,
+            stage: "done",
+            bytesUploaded: totalBytes,
+            totalBytes,
+            percent: 100,
+            bytesPerSecond: null,
+            eta: 0,
+            result
+          });
+        }
+        return { data: result, error: null };
+      }
+      const res = await fetch(url, { method: "POST", headers, body: form });
+      if (!res.ok) {
+        const err = await res.json().catch(() => ({}));
+        throw new HydrousSDKError((_b = err.error) != null ? _b : `HTTP ${res.status}`, "HTTP_ERROR", res.status);
+      }
+      let finalResult = null;
+      await readSSEStream(res, (eventType, data) => {
+        var _a2, _b2, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l;
+        const d = data;
+        if (eventType === "progress" && onProgress) {
+          onProgress({
+            index: (_a2 = d["index"]) != null ? _a2 : 0,
+            total: (_b2 = d["total"]) != null ? _b2 : 1,
+            path: (_d = (_c = d["path"]) != null ? _c : path) != null ? _d : "",
+            stage: (_e = d["stage"]) != null ? _e : "uploading",
+            bytesUploaded: (_f = d["bytesUploaded"]) != null ? _f : 0,
+            totalBytes: (_g = d["totalBytes"]) != null ? _g : 0,
+            percent: (_h = d["percent"]) != null ? _h : 0,
+            bytesPerSecond: (_i = d["bytesPerSecond"]) != null ? _i : null,
+            eta: (_j = d["eta"]) != null ? _j : null,
+            result: d["result"],
+            error: d["error"]
+          });
+        }
+        if (eventType === "done") finalResult = data;
+        if (eventType === "error") {
+          throw new HydrousSDKError(
+            (_k = d["error"]) != null ? _k : "Upload failed",
+            (_l = d["code"]) != null ? _l : "UPLOAD_ERROR"
+          );
+        }
+      });
+      return { data: finalResult, error: null };
+    } catch (err) {
+      return { data: null, error: toHydrousError(err) };
+    }
   }
-  // ── User: delete ───────────────────────────────────────────────────────────
+  // ══════════════════════════════════════════════════════════════════════════
+  // UPLOAD RAW (text / JSON / binary from string)
+  // ══════════════════════════════════════════════════════════════════════════
   /**
-   * Soft-delete a user. All their sessions are revoked automatically.
+   * Upload raw text or JSON content directly — no `File` object needed.
+   * Great for saving generated content, config files, or JSON records.
    *
-   * @example
-   * await db.auth.deleteUser('user_abc123');
-   */
-  async deleteUser(userId, opts) {
-    return this.http.delete(`${this.path}/user`, { userId }, opts);
-  }
-  // ── Password: change ───────────────────────────────────────────────────────
-  /**
-   * Change password for a signed-in user (requires old password).
-   * All sessions are revoked after success.
+   * @param bucketKey  Your storage bucket key (`ssk_…`)
+   * @param path       Destination path (e.g. `"configs/settings.json"`)
+   * @param content    String content to store
+   * @param options    `mimeType`, `overwrite`, `onProgress`
    *
    * @example
-   * await db.auth.changePassword({
-   *   userId: 'user_abc',
-   *   oldPassword: 'Old@Pass1',
-   *   newPassword: 'New@Pass2',
-   * });
+   * await hydrous.storage.uploadText(
+   *   'ssk_my_bucket_key',
+   *   'reports/summary.txt',
+   *   'Hello from Hydrous!',
+   *   { mimeType: 'text/plain' }
+   * );
    */
-  async changePassword(payload, opts) {
-    return this.http.post(`${this.path}/password/change`, payload, opts);
+  async uploadText(bucketKey, path, content, options = {}) {
+    var _a;
+    const { mimeType = "text/plain", overwrite = false, onProgress } = options;
+    try {
+      const url = storageUrl(this.baseUrl, bucketKey, "upload-raw");
+      const headers = { ...storageHeaders(bucketKey), "Content-Type": "application/json" };
+      const res = await fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ path, content, mimeType, overwrite })
+      });
+      if (!res.ok) {
+        const e = await res.json().catch(() => ({}));
+        throw new HydrousSDKError((_a = e.error) != null ? _a : `HTTP ${res.status}`, "HTTP_ERROR", res.status);
+      }
+      let finalResult = null;
+      await readSSEStream(res, (eventType, data) => {
+        var _a2, _b, _c, _d, _e, _f;
+        const d = data;
+        if (eventType === "progress" && onProgress) {
+          onProgress({
+            index: 0,
+            total: 1,
+            path,
+            stage: (_a2 = d["stage"]) != null ? _a2 : "uploading",
+            bytesUploaded: (_b = d["bytesUploaded"]) != null ? _b : 0,
+            totalBytes: (_c = d["totalBytes"]) != null ? _c : 0,
+            percent: (_d = d["percent"]) != null ? _d : 0,
+            bytesPerSecond: (_e = d["bytesPerSecond"]) != null ? _e : null,
+            eta: (_f = d["eta"]) != null ? _f : null
+          });
+        }
+        if (eventType === "done") finalResult = data;
+      });
+      return { data: finalResult, error: null };
+    } catch (err) {
+      return { data: null, error: toHydrousError(err) };
+    }
   }
-  // ── Password: reset request ────────────────────────────────────────────────
+  // ══════════════════════════════════════════════════════════════════════════
+  // BATCH UPLOAD
+  // ══════════════════════════════════════════════════════════════════════════
   /**
-   * Request a password reset email.
-   * Always returns success to prevent email enumeration.
+   * Upload multiple files in one request.
    *
-   * @example
-   * await db.auth.requestPasswordReset({ email: 'alice@example.com' });
-   */
-  async requestPasswordReset(payload, opts) {
-    return this.http.post(`${this.path}/password/reset/request`, payload, opts);
-  }
-  // ── Password: reset confirm ────────────────────────────────────────────────
-  /**
-   * Confirm a password reset using the token from the reset email.
+   * `onProgress` fires for **every file individually** — the `index` field
+   * tells you which file the event belongs to (0-based, same order as `files`).
+   * All files receive a `pending` event upfront before any uploads start,
+   * so you can render all progress bars immediately.
    *
-   * @example
-   * await db.auth.confirmPasswordReset({ resetToken: 'tok_...', newPassword: 'New@Pass2' });
-   */
-  async confirmPasswordReset(payload, opts) {
-    return this.http.post(`${this.path}/password/reset/confirm`, payload, opts);
-  }
-  // ── Email: verify request ──────────────────────────────────────────────────
-  /**
-   * Send a verification email to the user.
+   * @param bucketKey  Your storage bucket key (`ssk_…`)
+   * @param files      Array of `File` objects (browser) or `{ name, data }` objects (Node)
+   * @param options    Prefix, per-file paths, overwrite, concurrency, onProgress
    *
    * @example
-   * await db.auth.requestEmailVerification({ userId: 'user_abc' });
+   * await hydrous.storage.batchUpload(
+   *   'ssk_my_bucket_key',
+   *   fileArray,
+   *   {
+   *     prefix:     'uploads/2024/',
+   *     onProgress: (p) => {
+   *       console.log(`File ${p.index}: ${p.stage} ${p.percent}%`);
+   *     },
+   *   }
+   * );
    */
-  async requestEmailVerification(payload, opts) {
-    return this.http.post(`${this.path}/email/verify/request`, payload, opts);
+  async batchUpload(bucketKey, files, options = {}) {
+    var _a;
+    const { prefix = "", paths, overwrite = false, onProgress } = options;
+    try {
+      const url = storageUrl(this.baseUrl, bucketKey, "batch-upload");
+      const form = new FormData();
+      const resolvedPaths = files.map(
+        (f, i) => {
+          var _a2;
+          return (_a2 = paths == null ? void 0 : paths[i]) != null ? _a2 : `${prefix}${f.name}`;
+        }
+      );
+      files.forEach((f) => form.append("files", f, f.name));
+      form.append("paths", JSON.stringify(resolvedPaths));
+      if (overwrite) form.append("overwrite", "true");
+      const headers = storageHeaders(bucketKey);
+      if (isBrowser) {
+        const totalBytes = files.reduce((s, f) => s + f.size, 0);
+        const rawBody = await xhrUpload(url, form, headers, (loaded, total) => {
+          if (onProgress) {
+            let cursor = 0;
+            for (let i = 0; i < files.length; i++) {
+              const share = files[i].size / (totalBytes || 1);
+              const myStart = cursor;
+              const myEnd = cursor + share;
+              const fileLoaded = Math.max(0, Math.min(
+                files[i].size,
+                (loaded / (total || totalBytes) - myStart) / share * files[i].size
+              ));
+              onProgress({
+                index: i,
+                total: files.length,
+                path: resolvedPaths[i],
+                stage: "uploading",
+                bytesUploaded: Math.round(fileLoaded),
+                totalBytes: files[i].size,
+                percent: Math.min(99, Math.round(fileLoaded / files[i].size * 100)),
+                bytesPerSecond: null,
+                eta: null
+              });
+              cursor = myEnd;
+            }
+          }
+        });
+        const { results, errors } = drainSSEProgress(rawBody, onProgress);
+        return {
+          data: {
+            succeeded: results,
+            failed: errors
+          },
+          error: null
+        };
+      }
+      const res = await fetch(url, { method: "POST", headers, body: form });
+      if (!res.ok) {
+        const e = await res.json().catch(() => ({}));
+        throw new HydrousSDKError((_a = e.error) != null ? _a : `HTTP ${res.status}`, "HTTP_ERROR", res.status);
+      }
+      const succeeded = [];
+      const failed = [];
+      await readSSEStream(res, (eventType, data) => {
+        var _a2, _b, _c, _d, _e, _f, _g, _h, _i, _j;
+        const d = data;
+        if (eventType === "progress" && onProgress) {
+          onProgress({
+            index: (_a2 = d["index"]) != null ? _a2 : 0,
+            total: (_b = d["total"]) != null ? _b : files.length,
+            path: (_c = d["path"]) != null ? _c : "",
+            stage: (_d = d["stage"]) != null ? _d : "uploading",
+            bytesUploaded: (_e = d["bytesUploaded"]) != null ? _e : 0,
+            totalBytes: (_f = d["totalBytes"]) != null ? _f : 0,
+            percent: (_g = d["percent"]) != null ? _g : 0,
+            bytesPerSecond: (_h = d["bytesPerSecond"]) != null ? _h : null,
+            eta: (_i = d["eta"]) != null ? _i : null,
+            result: d["result"],
+            error: d["error"],
+            code: d["code"]
+          });
+        }
+        if (eventType === "done" && d["succeeded"]) {
+          succeeded.push(...d["succeeded"]);
+          failed.push(...(_j = d["errors"]) != null ? _j : []);
+        }
+      });
+      return { data: { succeeded, failed }, error: null };
+    } catch (err) {
+      return { data: null, error: toHydrousError(err) };
+    }
   }
-  // ── Email: verify confirm ──────────────────────────────────────────────────
+  // ══════════════════════════════════════════════════════════════════════════
+  // DOWNLOAD
+  // ══════════════════════════════════════════════════════════════════════════
   /**
-   * Confirm email address using the token from the verification email.
+   * Download a single file and return its content as an `ArrayBuffer`.
+   *
+   * @param bucketKey  Your storage bucket key (`ssk_…`)
+   * @param filePath   Path of the file within your bucket
    *
    * @example
-   * await db.auth.confirmEmailVerification({ verifyToken: 'tok_...' });
+   * const { data, error } = await hydrous.storage.download(
+   *   'ssk_my_bucket_key',
+   *   'avatars/alice.jpg'
+   * );
+   * if (data) {
+   *   const blob = new Blob([data]);
+   *   const url  = URL.createObjectURL(blob);
+   * }
    */
-  async confirmEmailVerification(payload, opts) {
-    return this.http.post(`${this.path}/email/verify/confirm`, payload, opts);
+  async download(bucketKey, filePath) {
+    var _a;
+    try {
+      const url = storageUrl(this.baseUrl, bucketKey, `download/${filePath}`);
+      const res = await fetch(url, { headers: storageHeaders(bucketKey) });
+      if (!res.ok) {
+        const e = await res.json().catch(() => ({}));
+        throw new HydrousSDKError((_a = e.error) != null ? _a : `HTTP ${res.status}`, "HTTP_ERROR", res.status);
+      }
+      const buffer = await res.arrayBuffer();
+      return { data: buffer, error: null };
+    } catch (err) {
+      return { data: null, error: toHydrousError(err) };
+    }
   }
-  // ── Account: lock ──────────────────────────────────────────────────────────
+  // ══════════════════════════════════════════════════════════════════════════
+  // BATCH DOWNLOAD
+  // ══════════════════════════════════════════════════════════════════════════
   /**
-   * Lock a user account for a given duration (default: 15 min).
+   * Download multiple files in one request.
+   *
+   * When `autoSave: true` (browser only) each file is automatically saved
+   * to the user's Downloads folder as it arrives.
+   *
+   * @param bucketKey  Your storage bucket key (`ssk_…`)
+   * @param filePaths  Array of file paths within your bucket
+   * @param options    Concurrency, onProgress, autoSave
    *
    * @example
-   * await db.auth.lockAccount({ userId: 'user_abc', duration: 30 * 60 * 1000 });
+   * const { data } = await hydrous.storage.batchDownload(
+   *   'ssk_my_bucket_key',
+   *   ['reports/jan.pdf', 'reports/feb.pdf'],
+   *   {
+   *     onProgress: (p) => console.log(p.path, p.status),
+   *     autoSave:   true,  // triggers browser file-save dialog per file
+   *   }
+   * );
    */
-  async lockAccount(payload, opts) {
-    return this.http.post(`${this.path}/account/lock`, payload, opts);
+  async batchDownload(bucketKey, filePaths, options = {}) {
+    var _a;
+    const { concurrency = 5, onProgress, autoSave = false } = options;
+    try {
+      const url = storageUrl(this.baseUrl, bucketKey, "batch-download");
+      const res = await fetch(url, {
+        method: "POST",
+        headers: { ...storageHeaders(bucketKey), "Content-Type": "application/json" },
+        body: JSON.stringify({ paths: filePaths, concurrency })
+      });
+      if (!res.ok) {
+        const e = await res.json().catch(() => ({}));
+        throw new HydrousSDKError((_a = e.error) != null ? _a : `HTTP ${res.status}`, "HTTP_ERROR", res.status);
+      }
+      const downloadedFiles = [];
+      await readSSEStream(res, (eventType, data) => {
+        var _a2, _b, _c, _d, _e, _f, _g, _h;
+        const d = data;
+        if (eventType === "file") {
+          const base64 = d["content"];
+          const mimeType = (_a2 = d["mimeType"]) != null ? _a2 : "application/octet-stream";
+          const path = (_b = d["path"]) != null ? _b : "";
+          const size = (_c = d["size"]) != null ? _c : 0;
+          const index = (_d = d["index"]) != null ? _d : 0;
+          const binary = atob(base64);
+          const bytes = new Uint8Array(binary.length);
+          for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+          const content = bytes.buffer;
+          downloadedFiles.push({ path, content, mimeType, size });
+          if (onProgress) {
+            onProgress({
+              index,
+              total: filePaths.length,
+              path,
+              status: "success",
+              size,
+              mimeType
+            });
+          }
+          if (autoSave && isBrowser) {
+            const blob = new Blob([content], { type: mimeType });
+            const blobUrl = URL.createObjectURL(blob);
+            const a = document.createElement("a");
+            a.href = blobUrl;
+            a.download = (_e = path.split("/").pop()) != null ? _e : "download";
+            a.click();
+            setTimeout(() => URL.revokeObjectURL(blobUrl), 5e3);
+          }
+        }
+        if (eventType === "error" && onProgress) {
+          const index = (_f = d["index"]) != null ? _f : 0;
+          onProgress({
+            index,
+            total: filePaths.length,
+            path: (_g = filePaths[index]) != null ? _g : "",
+            status: "error",
+            error: (_h = d["error"]) != null ? _h : "Download failed"
+          });
+        }
+      });
+      return { data: downloadedFiles, error: null };
+    } catch (err) {
+      return { data: null, error: toHydrousError(err) };
+    }
   }
-  // ── Account: unlock ────────────────────────────────────────────────────────
+  // ══════════════════════════════════════════════════════════════════════════
+  // LIST
+  // ══════════════════════════════════════════════════════════════════════════
   /**
-   * Unlock a previously locked user account.
+   * List files and folders inside a bucket (or a folder within it).
+   *
+   * Results are paginated — use `pagination.nextCursor` to fetch the next page.
+   *
+   * @param bucketKey  Your storage bucket key (`ssk_…`)
+   * @param options    `prefix`, `limit`, `cursor`
    *
    * @example
-   * await db.auth.unlockAccount('user_abc');
+   * const { data } = await hydrous.storage.list('ssk_my_bucket_key', {
+   *   prefix: 'avatars/',
+   *   limit:  50,
+   * });
+   * for (const item of data.items) {
+   *   console.log(item.type, item.path);
+   * }
    */
-  async unlockAccount(userId, opts) {
-    return this.http.post(`${this.path}/account/unlock`, { userId }, opts);
+  async list(bucketKey, options = {}) {
+    const { prefix = "", limit = 50, cursor } = options;
+    try {
+      const params = {
+        prefix: prefix || void 0,
+        limit,
+        cursor: cursor || void 0
+      };
+      const url = buildUrl(
+        this.baseUrl,
+        `storage/${bucketFromKey(bucketKey)}/list`,
+        params
+      );
+      const res = await fetch(url, { headers: storageHeaders(bucketKey) });
+      const json = await parseResponse(res);
+      return { data: json, error: null };
+    } catch (err) {
+      return { data: null, error: toHydrousError(err) };
+    }
   }
-  // ── Helpers ────────────────────────────────────────────────────────────────
+  // ══════════════════════════════════════════════════════════════════════════
+  // METADATA
+  // ══════════════════════════════════════════════════════════════════════════
   /**
-   * Fetch all users, automatically following cursors.
+   * Get metadata for a specific file (size, MIME type, compression info, etc.)
+   *
+   * @param bucketKey  Your storage bucket key (`ssk_…`)
+   * @param filePath   Path of the file within your bucket
    *
    * @example
-   * const users = await db.auth.listAllUsers();
+   * const { data } = await hydrous.storage.metadata(
+   *   'ssk_my_bucket_key',
+   *   'avatars/alice.jpg'
+   * );
+   * console.log(data.size, data.mimeType);
    */
-  async listAllUsers(opts) {
-    const all = [];
-    let cursor = null;
-    do {
-      const result = await this.listUsers(cursor ? { cursor, ...opts } : { ...opts });
-      all.push(...result.data);
-      cursor = result.meta.nextCursor ?? null;
-    } while (cursor);
-    return all;
-  }
-};
-
-// src/analytics/client.ts
-var AnalyticsClient = class {
-  constructor(http) {
-    this.http = http;
-  }
-  get path() {
-    return `/api/analytics/${this.http.bucketKey}/${this.http.bucketKey}`;
-  }
-  // ── Raw query ─────────────────────────────────────────────────────────────
-  /**
-   * Run any analytics query with full control over the payload.
-   * Prefer the typed convenience methods below for everyday use.
-   */
-  async query(payload, opts) {
-    return this.http.post(this.path, payload, opts);
+  async metadata(bucketKey, filePath) {
+    try {
+      const url = storageUrl(this.baseUrl, bucketKey, `metadata/${filePath}`);
+      const res = await fetch(url, { headers: storageHeaders(bucketKey) });
+      const json = await parseResponse(res);
+      return { data: json.data, error: null };
+    } catch (err) {
+      return { data: null, error: toHydrousError(err) };
+    }
   }
-  // ── count ──────────────────────────────────────────────────────────────────
+  // ══════════════════════════════════════════════════════════════════════════
+  // DELETE FILE
+  // ══════════════════════════════════════════════════════════════════════════
   /**
-   * Total record count, optionally scoped to a date range.
-   * Server `queryType`: **"count"**
+   * Delete a single file.
    *
-   * @example
-   * const { data } = await db.analytics.count();
-   * console.log(data.count); // 1234
+   * @param bucketKey  Your storage bucket key (`ssk_…`)
+   * @param filePath   Path of the file to delete
    *
-   * // With date range
-   * const { data } = await db.analytics.count({
-   *   dateRange: { startDate: '2025-01-01', endDate: '2025-12-31' }
-   * });
+   * @example
+   * await hydrous.storage.deleteFile('ssk_my_bucket_key', 'avatars/old.jpg');
    */
-  async count(options) {
-    return this.query({ queryType: "count", dateRange: options?.dateRange }, options);
+  async deleteFile(bucketKey, filePath) {
+    try {
+      const url = storageUrl(this.baseUrl, bucketKey, "file");
+      const res = await fetch(url, {
+        method: "DELETE",
+        headers: { ...storageHeaders(bucketKey), "Content-Type": "application/json" },
+        body: JSON.stringify({ path: filePath })
+      });
+      await parseResponse(res);
+      return { data: void 0, error: null };
+    } catch (err) {
+      return { data: null, error: toHydrousError(err) };
+    }
   }
-  // ── distribution ───────────────────────────────────────────────────────────
+  // ══════════════════════════════════════════════════════════════════════════
+  // DELETE FOLDER
+  // ══════════════════════════════════════════════════════════════════════════
   /**
-   * Value distribution (histogram) for a field.
-   * Server `queryType`: **"distribution"**
+   * Recursively delete a folder and all of its contents.
    *
-   * @example
-   * const { data } = await db.analytics.distribution('status');
-   * // [{ value: 'active', count: 80 }, { value: 'archived', count: 20 }]
-   */
-  async distribution(field, options) {
-    return this.query({
-      queryType: "distribution",
-      field,
-      limit: options?.limit,
-      order: options?.order,
-      dateRange: options?.dateRange
-    }, options);
-  }
-  // ── sum ────────────────────────────────────────────────────────────────────
-  /**
-   * Sum a numeric field, with optional group-by.
-   * Server `queryType`: **"sum"**
+   * @param bucketKey   Your storage bucket key (`ssk_…`)
+   * @param folderPath  Folder path to delete (e.g. `"old-uploads/"`)
    *
    * @example
-   * const { data } = await db.analytics.sum('revenue', { groupBy: 'region' });
+   * await hydrous.storage.deleteFolder('ssk_my_bucket_key', 'temp/');
    */
-  async sum(field, options) {
-    return this.query({
-      queryType: "sum",
-      field,
-      groupBy: options?.groupBy,
-      limit: options?.limit,
-      dateRange: options?.dateRange
-    }, options);
-  }
-  // ── timeSeries ─────────────────────────────────────────────────────────────
+  async deleteFolder(bucketKey, folderPath) {
+    try {
+      const url = storageUrl(this.baseUrl, bucketKey, "folder");
+      const res = await fetch(url, {
+        method: "DELETE",
+        headers: { ...storageHeaders(bucketKey), "Content-Type": "application/json" },
+        body: JSON.stringify({ path: folderPath })
+      });
+      await parseResponse(res);
+      return { data: void 0, error: null };
+    } catch (err) {
+      return { data: null, error: toHydrousError(err) };
+    }
+  }
+  // ══════════════════════════════════════════════════════════════════════════
+  // CREATE FOLDER
+  // ══════════════════════════════════════════════════════════════════════════
   /**
-   * Record count grouped over time.
-   * Server `queryType`: **"timeSeries"**
+   * Create an empty folder.
    *
-   * @example
-   * const { data } = await db.analytics.timeSeries({ granularity: 'day' });
-   * // [{ date: '2025-01-01', count: 42 }, ...]
-   */
-  async timeSeries(options) {
-    return this.query({
-      queryType: "timeSeries",
-      granularity: options?.granularity,
-      dateRange: options?.dateRange
-    }, options);
-  }
-  // ── fieldTimeSeries ────────────────────────────────────────────────────────
-  /**
-   * Aggregate a numeric field over time.
-   * Server `queryType`: **"fieldTimeSeries"**
+   * @param bucketKey   Your storage bucket key (`ssk_…`)
+   * @param folderPath  Path for the new folder (e.g. `"avatars/2024/"`)
    *
    * @example
-   * const { data } = await db.analytics.fieldTimeSeries('revenue', {
-   *   granularity: 'month',
-   *   aggregation: 'sum',
-   * });
+   * await hydrous.storage.createFolder('ssk_my_bucket_key', 'avatars/2024/');
    */
-  async fieldTimeSeries(field, options) {
-    return this.query({
-      queryType: "fieldTimeSeries",
-      field,
-      aggregation: options?.aggregation,
-      granularity: options?.granularity,
-      dateRange: options?.dateRange
-    }, options);
-  }
-  // ── topN ───────────────────────────────────────────────────────────────────
+  async createFolder(bucketKey, folderPath) {
+    try {
+      const url = storageUrl(this.baseUrl, bucketKey, "folder");
+      const res = await fetch(url, {
+        method: "POST",
+        headers: { ...storageHeaders(bucketKey), "Content-Type": "application/json" },
+        body: JSON.stringify({ path: folderPath })
+      });
+      await parseResponse(res);
+      return { data: void 0, error: null };
+    } catch (err) {
+      return { data: null, error: toHydrousError(err) };
+    }
+  }
+  // ══════════════════════════════════════════════════════════════════════════
+  // MOVE
+  // ══════════════════════════════════════════════════════════════════════════
   /**
-   * Top N most frequent values for a field.
-   * Server `queryType`: **"topN"**
+   * Move (rename) a file to a new path.
    *
-   * @example
-   * const { data } = await db.analytics.topN('country', 5);
-   * // [{ label: 'US', value: 'US', count: 500 }, ...]
-   */
-  async topN(field, n = 10, options) {
-    return this.query({
-      queryType: "topN",
-      field,
-      n,
-      labelField: options?.labelField,
-      order: options?.order,
-      dateRange: options?.dateRange
-    }, options);
-  }
-  // ── stats ──────────────────────────────────────────────────────────────────
-  /**
-   * Statistical summary for a numeric field: min, max, avg, stddev, p50, p90, p99.
-   * Server `queryType`: **"stats"**
+   * @param bucketKey  Your storage bucket key (`ssk_…`)
+   * @param fromPath   Current path of the file
+   * @param toPath     New path for the file
    *
    * @example
-   * const { data } = await db.analytics.stats('score');
-   * console.log(data.avg, data.p99);
+   * await hydrous.storage.move(
+   *   'ssk_my_bucket_key',
+   *   'drafts/report.pdf',
+   *   'published/report.pdf'
+   * );
    */
-  async stats(field, options) {
-    return this.query({ queryType: "stats", field, dateRange: options?.dateRange }, options);
+  async move(bucketKey, fromPath, toPath) {
+    try {
+      const url = storageUrl(this.baseUrl, bucketKey, "move");
+      const res = await fetch(url, {
+        method: "POST",
+        headers: { ...storageHeaders(bucketKey), "Content-Type": "application/json" },
+        body: JSON.stringify({ from: fromPath, to: toPath })
+      });
+      await parseResponse(res);
+      return { data: void 0, error: null };
+    } catch (err) {
+      return { data: null, error: toHydrousError(err) };
+    }
   }
-  // ── records ────────────────────────────────────────────────────────────────
+  // ══════════════════════════════════════════════════════════════════════════
+  // COPY
+  // ══════════════════════════════════════════════════════════════════════════
   /**
-   * Filtered, paginated raw records with optional field projection.
-   * Supports filter ops: == != > < >= <= CONTAINS
-   * Server `queryType`: **"records"**
+   * Copy a file to a new path (original is kept).
    *
-   * @example
-   * const { data } = await db.analytics.records({
-   *   filters: [{ field: 'role', op: '==', value: 'admin' }],
-   *   selectFields: ['email', 'createdAt'],
-   *   limit: 25,
-   * });
-   * console.log(data.data, data.hasMore);
-   */
-  async records(options) {
-    return this.query({
-      queryType: "records",
-      filters: options?.filters,
-      selectFields: options?.selectFields,
-      limit: options?.limit,
-      offset: options?.offset,
-      orderBy: options?.orderBy,
-      order: options?.order,
-      dateRange: options?.dateRange
-    }, options);
-  }
-  // ── multiMetric ────────────────────────────────────────────────────────────
-  /**
-   * Multiple aggregations in a single BigQuery call — ideal for dashboard stat cards.
-   * Server `queryType`: **"multiMetric"**
+   * @param bucketKey  Your storage bucket key (`ssk_…`)
+   * @param fromPath   Source path
+   * @param toPath     Destination path
    *
    * @example
-   * const { data } = await db.analytics.multiMetric([
-   *   { name: 'totalRevenue', field: 'amount',  aggregation: 'sum' },
-   *   { name: 'avgScore',     field: 'score',   aggregation: 'avg' },
-   *   { name: 'userCount',    field: 'userId',  aggregation: 'count' },
-   * ]);
-   * console.log(data.totalRevenue, data.avgScore, data.userCount);
+   * await hydrous.storage.copy(
+   *   'ssk_my_bucket_key',
+   *   'templates/invoice.pdf',
+   *   'invoices/invoice-001.pdf'
+   * );
    */
-  async multiMetric(metrics, options) {
-    return this.query({
-      queryType: "multiMetric",
-      metrics,
-      dateRange: options?.dateRange
-    }, options);
-  }
-  // ── storageStats ───────────────────────────────────────────────────────────
+  async copy(bucketKey, fromPath, toPath) {
+    try {
+      const url = storageUrl(this.baseUrl, bucketKey, "copy");
+      const res = await fetch(url, {
+        method: "POST",
+        headers: { ...storageHeaders(bucketKey), "Content-Type": "application/json" },
+        body: JSON.stringify({ from: fromPath, to: toPath })
+      });
+      await parseResponse(res);
+      return { data: void 0, error: null };
+    } catch (err) {
+      return { data: null, error: toHydrousError(err) };
+    }
+  }
+  // ══════════════════════════════════════════════════════════════════════════
+  // SIGNED URL
+  // ══════════════════════════════════════════════════════════════════════════
   /**
-   * Storage statistics for the bucket — total records, bytes, avg/min/max size.
-   * Server `queryType`: **"storageStats"**
+   * Generate a time-limited public URL for a private file.
+   *
+   * @param bucketKey  Your storage bucket key (`ssk_…`)
+   * @param filePath   Path of the file
+   * @param options    `expiresIn` seconds (default: 3600)
    *
    * @example
-   * const { data } = await db.analytics.storageStats();
-   * console.log(data.totalRecords, data.totalBytes);
+   * const { data } = await hydrous.storage.signedUrl(
+   *   'ssk_my_bucket_key',
+   *   'private/contract.pdf',
+   *   { expiresIn: 300 }   // 5 minutes
+   * );
+   * console.log(data.signedUrl);  // share this URL
    */
-  async storageStats(options) {
-    return this.query({ queryType: "storageStats", dateRange: options?.dateRange }, options);
+  async signedUrl(bucketKey, filePath, options = {}) {
+    const { expiresIn = 3600 } = options;
+    try {
+      const url = storageUrl(this.baseUrl, bucketKey, "signed-url");
+      const res = await fetch(url, {
+        method: "POST",
+        headers: { ...storageHeaders(bucketKey), "Content-Type": "application/json" },
+        body: JSON.stringify({ path: filePath, expiresInSeconds: expiresIn })
+      });
+      const json = await parseResponse(res);
+      return { data: json, error: null };
+    } catch (err) {
+      return { data: null, error: toHydrousError(err) };
+    }
   }
-  // ── crossBucket ────────────────────────────────────────────────────────────
+  // ══════════════════════════════════════════════════════════════════════════
+  // STATS
+  // ══════════════════════════════════════════════════════════════════════════
   /**
-   * Compare a metric across multiple buckets in one query.
-   * Server `queryType`: **"crossBucket"**
+   * Get usage and billing statistics for this bucket key.
+   *
+   * @param bucketKey  Your storage bucket key (`ssk_…`)
    *
    * @example
-   * const { data } = await db.analytics.crossBucket({
-   *   bucketKeys:  ['sales', 'refunds', 'trials'],
-   *   field:       'amount',
-   *   aggregation: 'sum',
-   * });
+   * const { data } = await hydrous.storage.stats('ssk_my_bucket_key');
+   * console.log(`${data.totalFiles} files, ${data.totalSizeBytes} bytes stored`);
    */
-  async crossBucket(options) {
-    return this.query({
-      queryType: "crossBucket",
-      bucketKeys: options.bucketKeys,
-      field: options.field,
-      aggregation: options.aggregation,
-      dateRange: options.dateRange
-    }, options);
+  async stats(bucketKey) {
+    try {
+      const url = buildUrl(this.baseUrl, `storage/${bucketFromKey(bucketKey)}/stats`);
+      const res = await fetch(url, { headers: storageHeaders(bucketKey) });
+      const json = await parseResponse(res);
+      return { data: json.data, error: null };
+    } catch (err) {
+      return { data: null, error: toHydrousError(err) };
+    }
   }
 };
 
 // src/client.ts
 var HydrousClient = class {
   constructor(config) {
-    if (!config.authKey) throw new Error("[hydrousdb] authKey is required");
-    if (!config.bucketKey) throw new Error("[hydrousdb] bucketKey is required");
-    this.http = new HttpClient(config);
-    this.records = new RecordsClient(this.http);
-    this.auth = new AuthClient(this.http);
-    this.analytics = new AnalyticsClient(this.http);
+    if (!config.url) throw new Error("[Hydrous] config.url is required");
+    if (!config.apiKey) throw new Error("[Hydrous] config.apiKey is required");
+    this.auth = new AuthClient(config);
+    this.records = new RecordsClient(config);
+    this.analytics = new AnalyticsClient(config);
+    this.storage = new StorageClient(config);
   }
 };
+
+// src/index.ts
 function createClient(config) {
   return new HydrousClient(config);
 }
 
-export { AnalyticsClient, AuthClient, HydrousClient, HydrousError, HydrousNetworkError, HydrousTimeoutError, RecordsClient, createClient };
+export { AnalyticsClient, AuthClient, HydrousClient, HydrousSDKError, RecordsClient, StorageClient, createClient, eq, gt, inArray, isHydrousError, lt, neq };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map