hydrousdb 2.0.0 → 2.0.3

package/dist/index.js

@@ -1,764 +1,1036 @@
 'use strict';
 
 // src/utils/errors.ts
-var HydrousError = class extends Error {
-  constructor(body, status) {
-    super(body.error);
-    this.name = "HydrousError";
+var HydrousDBError = class extends Error {
+  constructor(message, code = "SDK_ERROR", status) {
+    super(message);
+    this.name = "HydrousDBError";
+    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 HydrousDBError) {
+    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 HydrousDBError;
+}
 
 // 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.securityKey = config.securityKey;
-    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);
-    }
-    return this.executeWithRetry(url, init, options?.raw ?? false, this.retries);
+async function parseResponse(res) {
+  let body;
+  try {
+    body = await res.json();
+  } catch (e) {
+    if (!res.ok) throw new HydrousDBError(`HTTP ${res.status}`, "HTTP_ERROR", res.status);
+    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 });
+  if (!res.ok) {
+    const e = body;
+    throw new HydrousDBError(
+      e.error || e.message || `HTTP ${res.status}`,
+      e.code || "HTTP_ERROR",
+      res.status
+    );
   }
-  patch(path, body, opts) {
-    return this.request("PATCH", path, { body, ...opts });
+  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));
+    }
   }
-  delete(path, params, opts) {
-    return this.request("DELETE", path, { params, ...opts });
+  return url.toString();
+}
+function mergeHeaders(a, b) {
+  return { ...a, ...b };
+}
+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();
+      }
+      if (dataLine === null) continue;
+      try {
+        onEvent(eventType, JSON.parse(dataLine));
+      } catch (e) {
+      }
+    }
+  };
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    flush(decoder.decode(value, { stream: true }));
   }
-  head(path, params, opts) {
-    return this.request("HEAD", path, { params, raw: true, ...opts });
+  if (buf.trim()) flush("");
+}
+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 (dataLine === null) continue;
+    try {
+      onEvent(eventType, JSON.parse(dataLine));
+    } catch (e) {
+    }
   }
-  // ── 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));
+}
+function xhrUpload(url, body, headers, onProgress) {
+  return new Promise((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+    xhr.open("POST", url);
+    for (const [k, v] of Object.entries(headers)) xhr.setRequestHeader(k, v);
+    xhr.responseType = "text";
+    if (onProgress) {
+      xhr.upload.onprogress = (e) => {
+        if (e.lengthComputable) onProgress(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 HydrousDBError((_a = d.error) != null ? _a : `HTTP ${xhr.status}`, "HTTP_ERROR", xhr.status));
+        } catch (e) {
+          reject(new HydrousDBError(`HTTP ${xhr.status}`, "HTTP_ERROR", xhr.status));
         }
       }
+    };
+    xhr.onerror = () => reject(new HydrousDBError("Network error", "NETWORK_ERROR"));
+    xhr.onabort = () => reject(new HydrousDBError("Upload aborted", "UPLOAD_ABORTED"));
+    xhr.ontimeout = () => reject(new HydrousDBError("Upload timed out", "UPLOAD_TIMEOUT"));
+    xhr.send(body);
+  });
+}
+
+// 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.authKey}`
+    };
+  }
+  /** Create a new user account */
+  async signUp(options) {
+    try {
+      const res = await fetch(buildUrl(this.baseUrl, "auth/signup"), {
+        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) };
     }
-    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;
+  /** Sign in with email and password */
+  async signIn(options) {
+    try {
+      const res = await fetch(buildUrl(this.baseUrl, "auth/signin"), {
+        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) };
+    }
   }
-  async executeWithRetry(url, init, raw, retriesLeft) {
+  /** Sign out and invalidate the current session */
+  async signOut() {
     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();
-      }
-      let body;
-      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);
+      const res = await fetch(buildUrl(this.baseUrl, "auth/signout"), {
+        method: "POST",
+        headers: mergeHeaders(this.headers, this._sessionHeader())
+      });
+      await parseResponse(res);
+      this.session = null;
+      return { data: void 0, error: null };
     } catch (err) {
-      if (err instanceof HydrousError) throw err;
-      if (err instanceof Error && err.message === "timeout") {
-        throw new HydrousTimeoutError(this.timeout);
-      }
-      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
-      );
+      return { data: null, error: toHydrousError(err) };
     }
   }
+  /** Get the currently authenticated user */
+  async getUser() {
+    try {
+      const res = await fetch(buildUrl(this.baseUrl, "auth/user"), {
+        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) };
+    }
+  }
+  /** Refresh the access token using the stored refresh token */
+  async refreshSession() {
+    var _a;
+    if (!((_a = this.session) == null ? void 0 : _a.refreshToken)) {
+      return { data: null, error: { message: "No active session", code: "NO_SESSION" } };
+    }
+    try {
+      const res = await fetch(buildUrl(this.baseUrl, "auth/refresh"), {
+        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) };
+    }
+  }
+  /** 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 } : {};
+  }
 };
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
 
 // src/utils/query.ts
-function buildQueryParams(opts) {
+function serialiseQuery(opts = {}) {
+  var _a;
   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;
+  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 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(", ")}`
-      );
-    }
-    if (!f.field || typeof f.field !== "string") {
-      throw new Error('Each filter must have a non-empty "field" string.');
-    }
-  }
-}
+var eq = (field, value) => ({ field, operator: "eq", value });
+var neq = (field, value) => ({ field, operator: "neq", value });
+var gt = (field, value) => ({ field, operator: "gt", value });
+var lt = (field, value) => ({ field, operator: "lt", value });
+var gte = (field, value) => ({ field, operator: "gte", value });
+var lte = (field, value) => ({ field, operator: "lte", value });
+var inArray = (field, value) => ({ field, operator: "in", value });
 
 // src/records/client.ts
 var RecordsClient = class {
-  constructor(http) {
-    this.http = http;
-  }
-  /** Builds the base path for a given bucket: /api/:bucketKey/:securityKey */
-  path(bucketKey) {
-    return `/api/${bucketKey}/${this.http.securityKey}`;
-  }
-  // ── GET — single record ────────────────────────────────────────────────────
-  /**
-   * Fetch a single record by ID.
-   *
-   * @example
-   * const { data } = await db.records.get('rec_abc123', { bucketKey: 'users' });
-   * const { data, history } = await db.records.get('rec_abc123', { bucketKey: 'users', showHistory: true });
-   */
-  async get(recordId, options) {
-    const { bucketKey, showHistory, ...rest } = options;
-    const params = { recordId };
-    if (showHistory) params["showHistory"] = "true";
-    return this.http.get(this.path(bucketKey), params, rest);
+  constructor(config) {
+    this.baseUrl = config.url;
+    this.headers = {
+      "Content-Type": "application/json",
+      "Authorization": `Bearer ${config.bucketSecurityKey}`
+    };
   }
-  // ── GET — historical snapshot ──────────────────────────────────────────────
-  /**
-   * Fetch a specific historical version (generation) of a record.
-   *
-   * @example
-   * const { data } = await db.records.getSnapshot('rec_abc123', '1700000000000000', { bucketKey: 'users' });
-   */
-  async getSnapshot(recordId, generation, options) {
-    const { bucketKey, ...rest } = options;
-    return this.http.get(this.path(bucketKey), { recordId, generation }, rest);
+  /** Query records from a collection */
+  async select(collection, options = {}) {
+    try {
+      const url = buildUrl(this.baseUrl, `records/${collection}`, serialiseQuery(options));
+      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) };
+    }
   }
-  // ── GET — collection query ─────────────────────────────────────────────────
-  /**
-   * Query a collection with optional filters, sorting, and pagination.
-   *
-   * @example
-   * // Simple query
-   * const { data, meta } = await db.records.query({ bucketKey: 'orders', limit: 50 });
-   *
-   * // Filtered query
-   * const { data } = await db.records.query({
-   *   bucketKey: 'orders',
-   *   filters: [{ field: 'status', op: '==', value: 'active' }],
-   *   timeScope: '7d',
-   * });
-   *
-   * // Paginated
-   * let cursor: string | null = null;
-   * do {
-   *   const result = await db.records.query({ bucketKey: 'orders', limit: 100, cursor: cursor ?? undefined });
-   *   cursor = result.meta.nextCursor;
-   * } while (cursor);
-   */
-  async query(options) {
-    const { bucketKey, ...rest } = options;
-    if (rest.filters) validateFilters(rest.filters);
-    const params = buildQueryParams(rest);
-    return this.http.get(this.path(bucketKey), params, rest);
+  /** Fetch a single record by ID */
+  async get(collection, id) {
+    try {
+      const res = await fetch(buildUrl(this.baseUrl, `records/${collection}/${id}`), { headers: this.headers });
+      const json = await parseResponse(res);
+      return { data: json.data, error: null };
+    } catch (err) {
+      return { data: null, error: toHydrousError(err) };
+    }
   }
-  // ── POST — insert ──────────────────────────────────────────────────────────
-  /**
-   * Insert a new record into the specified bucket.
-   *
-   * @example
-   * const { data, meta } = await db.records.insert(
-   *   { values: { name: 'Alice', score: 99 }, queryableFields: ['name'] },
-   *   { bucketKey: 'users' }
-   * );
-   */
-  async insert(payload, options) {
-    const { bucketKey, ...rest } = options;
-    return this.http.post(this.path(bucketKey), payload, rest);
+  /** Insert one or more records */
+  async insert(collection, payload) {
+    try {
+      const res = await fetch(buildUrl(this.baseUrl, `records/${collection}`), {
+        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) };
+    }
   }
-  // ── PATCH — update ─────────────────────────────────────────────────────────
-  /**
-   * Update an existing record.
-   *
-   * @example
-   * await db.records.update(
-   *   { recordId: 'rec_abc123', values: { score: 100 }, track_record_history: true },
-   *   { bucketKey: 'users' }
-   * );
-   */
-  async update(payload, options) {
-    const { bucketKey, ...rest } = options;
-    return this.http.patch(this.path(bucketKey), payload, rest);
+  /** Update a record by ID */
+  async update(collection, id, payload) {
+    try {
+      const res = await fetch(buildUrl(this.baseUrl, `records/${collection}/${id}`), {
+        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) };
+    }
   }
-  // ── DELETE ─────────────────────────────────────────────────────────────────
-  /**
-   * Delete a record permanently.
-   *
-   * @example
-   * await db.records.delete('rec_abc123', { bucketKey: 'users' });
-   */
-  async delete(recordId, options) {
-    const { bucketKey, ...rest } = options;
-    return this.http.delete(this.path(bucketKey), { recordId }, rest);
+  /** Delete a record by ID */
+  async delete(collection, id) {
+    try {
+      const res = await fetch(buildUrl(this.baseUrl, `records/${collection}/${id}`), {
+        method: "DELETE",
+        headers: this.headers
+      });
+      await parseResponse(res);
+      return { data: void 0, error: null };
+    } catch (err) {
+      return { data: null, error: toHydrousError(err) };
+    }
   }
-  // ── HEAD — existence check ─────────────────────────────────────────────────
-  /**
-   * Check whether a record exists without fetching its full data.
-   * Returns `null` if the record is not found.
-   *
-   * @example
-   * const info = await db.records.exists('rec_abc123', { bucketKey: 'users' });
-   * if (info?.exists) console.log('found at', info.updatedAt);
-   */
-  async exists(recordId, options) {
-    const { bucketKey, ...rest } = options;
-    const res = await this.http.head(this.path(bucketKey), { recordId }, rest);
-    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") ?? ""
+};
+
+// src/analytics/client.ts
+var AnalyticsClient = class {
+  constructor(config) {
+    this.baseUrl = config.url;
+    this.headers = {
+      "Content-Type": "application/json",
+      "Authorization": `Bearer ${config.bucketSecurityKey}`
     };
   }
-  // ── Batch — update ─────────────────────────────────────────────────────────
-  /**
-   * Update up to 500 records in a single request.
-   *
-   * @example
-   * await db.records.batchUpdate(
-   *   { updates: [{ recordId: 'rec_1', values: { status: 'archived' } }] },
-   *   { bucketKey: 'orders' }
-   * );
-   */
-  async batchUpdate(payload, options) {
-    const { bucketKey, ...rest } = options;
-    return this.http.post(`${this.path(bucketKey)}/batch/update`, payload, rest);
-  }
-  // ── Batch — delete ─────────────────────────────────────────────────────────
-  /**
-   * Delete up to 500 records in a single request.
-   *
-   * @example
-   * await db.records.batchDelete(
-   *   { recordIds: ['rec_1', 'rec_2'] },
-   *   { bucketKey: 'orders' }
-   * );
-   */
-  async batchDelete(payload, options) {
-    const { bucketKey, ...rest } = options;
-    return this.http.post(`${this.path(bucketKey)}/batch/delete`, payload, rest);
+  /** Track a single analytics event */
+  async track(options) {
+    var _a;
+    try {
+      const res = await fetch(buildUrl(this.baseUrl, "analytics/track"), {
+        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) };
+    }
   }
-  // ── Batch — insert ─────────────────────────────────────────────────────────
-  /**
-   * Insert up to 500 records in a single request.
-   * Returns HTTP 207 (multi-status) — check `meta.failed` for partial failures.
-   *
-   * @example
-   * const result = await db.records.batchInsert(
-   *   { records: [{ name: 'Alice' }, { name: 'Bob' }], queryableFields: ['name'] },
-   *   { bucketKey: 'users' }
-   * );
-   */
-  async batchInsert(payload, options) {
-    const { bucketKey, ...rest } = options;
-    return this.http.post(`${this.path(bucketKey)}/batch/insert`, payload, rest);
+  /** Track many events in one request */
+  async trackBatch(events) {
+    try {
+      const stamped = events.map((e) => {
+        var _a;
+        return { ...e, timestamp: (_a = e.timestamp) != null ? _a : Date.now() };
+      });
+      const res = await fetch(buildUrl(this.baseUrl, "analytics/track/batch"), {
+        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) };
+    }
   }
-  // ── Helpers ────────────────────────────────────────────────────────────────
-  /**
-   * Fetch ALL records matching a query, automatically following cursors.
-   * Use with care on large collections — prefer `query()` with manual pagination.
-   *
-   * @example
-   * const allRecords = await db.records.queryAll({
-   *   bucketKey: 'orders',
-   *   filters: [{ field: 'type', op: '==', value: 'invoice' }],
-   * });
-   */
-  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;
+  /** Query recorded analytics events */
+  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) };
+    }
   }
 };
 
-// src/auth/client.ts
-var AuthClient = class {
-  constructor(http) {
-    this.http = http;
-  }
-  get path() {
-    return `/auth/${this.http.authKey}`;
-  }
-  // ── Sign-up ────────────────────────────────────────────────────────────────
-  /**
-   * Create a new user account. Returns the user and a session immediately.
-   *
-   * @example
-   * const { data, session } = await db.auth.signUp({
-   *   email: 'alice@example.com',
-   *   password: 'Str0ngP@ss!',
-   *   fullName: 'Alice Smith',
-   * });
-   * // Store session.sessionId and session.refreshToken in your app
-   */
-  async signUp(payload, opts) {
-    return this.http.post(`${this.path}/signup`, payload, opts);
-  }
-  // ── Sign-in ────────────────────────────────────────────────────────────────
-  /**
-   * Authenticate with email + password. Returns user data and a new session.
-   *
-   * @example
-   * const { data, session } = await db.auth.signIn({
-   *   email: 'alice@example.com',
-   *   password: 'Str0ngP@ss!',
-   * });
-   */
-  async signIn(payload, opts) {
-    return this.http.post(`${this.path}/signin`, payload, opts);
-  }
-  // ── Sign-out ───────────────────────────────────────────────────────────────
-  /**
-   * Revoke a session (or all sessions for a user).
-   *
-   * @example
-   * // Single device
-   * await db.auth.signOut({ sessionId: 'sess_...' });
-   *
-   * // All devices
-   * await db.auth.signOut({ allDevices: true, userId: 'user_...' });
-   */
-  async signOut(payload, opts) {
-    return this.http.post(`${this.path}/signout`, payload, opts);
+// src/storage/scoped.ts
+var isBrowser = typeof window !== "undefined" && typeof XMLHttpRequest !== "undefined";
+function storageBase(url, bucketKey) {
+  return `${url.replace(/\/$/, "")}/storage/${encodeURIComponent(bucketKey)}`;
+}
+function storageHeaders(bucketKey) {
+  return { "X-Storage-Key": bucketKey };
+}
+function jsonHeaders(bucketKey) {
+  return { "X-Storage-Key": bucketKey, "Content-Type": "application/json" };
+}
+function drainSSE(raw, onProgress) {
+  const results = [];
+  const errors = [];
+  parseSSEText(raw, (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["succeeded"])) {
+        results.push(...d["succeeded"]);
+        errors.push(...(_j = d["errors"]) != null ? _j : []);
+      }
+    }
+    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 ScopedStorageClient = class {
+  constructor(baseUrl, keyName, bucketKey) {
+    this.base = storageBase(baseUrl, bucketKey);
+    this.key = bucketKey;
+    this.keyName = keyName;
   }
-  // ── Session: validate ──────────────────────────────────────────────────────
+  // ══════════════════════════════════════════════════════════════════════════
+  // UPLOAD — single file
+  // ══════════════════════════════════════════════════════════════════════════
   /**
-   * Validate a session token — use this on every protected request in your backend.
+   * Upload a single file.
    *
-   * @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);
-  }
-  // ── Session: refresh ───────────────────────────────────────────────────────
-  /**
-   * Exchange a refresh token for a new session (rotation).
-   * The old session is revoked.
+   * Supply `onProgress` to receive live upload ticks including bytes
+   * transferred, speed (bytes/sec), ETA, and lifecycle stage.
    *
-   * @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.
+   * **Stage sequence:**
+   * `pending → compressing → uploading → done | error`
    *
-   * @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.
+   * In browsers the progress is tracked at the network level via XHR, so
+   * `percent` reflects actual bytes leaving the device.  `done` only fires
+   * after the server confirms the write to cloud storage, so 100% is real.
    *
    * @example
-   * const { data, meta } = await db.auth.listUsers({ limit: 50 });
+   * const { data, error } = await db.storage('avatars').upload(file, {
+   *   path:      'users/alice.jpg',
+   *   overwrite: true,
+   *   onProgress: (p) => {
+   *     setProgress(p.percent);              // e.g. drive a <progress> bar
+   *     setSpeed(`${p.bytesPerSecond} B/s`);
+   *     setEta(`${p.eta}s remaining`);
+   *   },
+   * });
    */
-  async listUsers(options) {
-    const params = {
-      limit: options?.limit
-    };
-    if (options?.cursor) params["cursor"] = options.cursor;
-    return this.http.get(`${this.path}/users`, params, options);
+  async upload(file, options = {}) {
+    var _a, _b;
+    const { path, overwrite = false, onProgress } = options;
+    try {
+      const url = `${this.base}/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(this.key);
+      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) => {
+          onProgress == null ? void 0 : 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 } = drainSSE(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 e = await res.json().catch(() => ({}));
+        throw new HydrousDBError((_b = e.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;
+        const d = data;
+        if (eventType === "progress" && onProgress) {
+          onProgress({
+            index: 0,
+            total: 1,
+            path: path != null ? path : "",
+            stage: (_a2 = d["stage"]) != null ? _a2 : "uploading",
+            bytesUploaded: (_b2 = d["bytesUploaded"]) != null ? _b2 : 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,
+            result: d["result"]
+          });
+        }
+        if (eventType === "done") finalResult = data;
+        if (eventType === "error") {
+          throw new HydrousDBError(
+            (_g = d["error"]) != null ? _g : "Upload failed",
+            (_h = d["code"]) != null ? _h : "UPLOAD_ERROR"
+          );
+        }
+      });
+      return { data: finalResult, error: null };
+    } catch (err) {
+      return { data: null, error: toHydrousError(err) };
+    }
   }
-  // ── User: update ───────────────────────────────────────────────────────────
+  // ══════════════════════════════════════════════════════════════════════════
+  // UPLOAD TEXT / JSON
+  // ══════════════════════════════════════════════════════════════════════════
   /**
-   * Update user profile fields.
+   * Upload raw text or JSON content directly — no File object needed.
    *
    * @example
-   * await db.auth.updateUser({ userId: 'user_abc', updates: { fullName: 'Bob Smith' } });
+   * // Save a JSON config
+   * await db.storage('configs').uploadText(
+   *   'settings/app.json',
+   *   JSON.stringify({ theme: 'dark' }),
+   *   { mimeType: 'application/json' }
+   * );
    */
-  async updateUser(payload, opts) {
-    return this.http.patch(`${this.path}/user`, payload, opts);
+  async uploadText(path, content, options = {}) {
+    var _a;
+    const { mimeType = "text/plain", overwrite = false, onProgress } = options;
+    try {
+      const res = await fetch(`${this.base}/upload-raw`, {
+        method: "POST",
+        headers: jsonHeaders(this.key),
+        body: JSON.stringify({ path, content, mimeType, overwrite })
+      });
+      if (!res.ok) {
+        const e = await res.json().catch(() => ({}));
+        throw new HydrousDBError((_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) };
+    }
   }
-  // ── User: delete ───────────────────────────────────────────────────────────
+  // ══════════════════════════════════════════════════════════════════════════
+  // BATCH UPLOAD
+  // ══════════════════════════════════════════════════════════════════════════
   /**
-   * Soft-delete a user. All their sessions are revoked automatically.
+   * Upload multiple files in one request.
    *
-   * @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.
+   * `onProgress` fires per file — use `p.index` to identify which file.
+   * All files receive a `pending` event upfront so you can render progress
+   * bars immediately before any data is sent.
    *
    * @example
-   * await db.auth.changePassword({
-   *   userId: 'user_abc',
-   *   oldPassword: 'Old@Pass1',
-   *   newPassword: 'New@Pass2',
+   * await db.storage('documents').batchUpload(files, {
+   *   prefix:     'reports/2024/',
+   *   onProgress: (p) => updateBar(p.index, p.percent),
    * });
    */
-  async changePassword(payload, opts) {
-    return this.http.post(`${this.path}/password/change`, payload, opts);
-  }
-  // ── Password: reset request ────────────────────────────────────────────────
-  /**
-   * Request a password reset email.
-   * Always returns success to prevent email enumeration.
-   *
-   * @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.
-   *
-   * @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);
+  async batchUpload(files, options = {}) {
+    var _a;
+    const { prefix = "", paths, overwrite = false, onProgress } = options;
+    try {
+      const url = `${this.base}/batch-upload`;
+      const resolvedPaths = files.map((f, i) => {
+        var _a2;
+        return (_a2 = paths == null ? void 0 : paths[i]) != null ? _a2 : `${prefix}${f.name}`;
+      });
+      const form = new FormData();
+      files.forEach((f) => form.append("files", f, f.name));
+      form.append("paths", JSON.stringify(resolvedPaths));
+      if (overwrite) form.append("overwrite", "true");
+      const headers = storageHeaders(this.key);
+      if (isBrowser) {
+        const totalBytes = files.reduce((s, f) => s + f.size, 0);
+        const rawBody = await xhrUpload(url, form, headers, (loaded, total) => {
+          if (!onProgress) return;
+          let cursor = 0;
+          for (let i = 0; i < files.length; i++) {
+            const share = files[i].size / (totalBytes || 1);
+            const fileLoaded = Math.max(0, Math.min(
+              files[i].size,
+              (loaded / (total || totalBytes) - cursor) / 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 += share;
+          }
+        });
+        const { results, errors } = drainSSE(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 HydrousDBError((_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
+          });
+        }
+        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 request ──────────────────────────────────────────────────
+  // ══════════════════════════════════════════════════════════════════════════
+  // DOWNLOAD
+  // ══════════════════════════════════════════════════════════════════════════
   /**
-   * Send a verification email to the user.
+   * Download a single file and return its content as an `ArrayBuffer`.
    *
    * @example
-   * await db.auth.requestEmailVerification({ userId: 'user_abc' });
+   * const { data } = await db.storage('avatars').download('users/alice.jpg');
+   * const blob = new Blob([data!]);
+   * img.src = URL.createObjectURL(blob);
    */
-  async requestEmailVerification(payload, opts) {
-    return this.http.post(`${this.path}/email/verify/request`, payload, opts);
+  async download(filePath) {
+    var _a;
+    try {
+      const res = await fetch(`${this.base}/download/${filePath}`, {
+        headers: storageHeaders(this.key)
+      });
+      if (!res.ok) {
+        const e = await res.json().catch(() => ({}));
+        throw new HydrousDBError((_a = e.error) != null ? _a : `HTTP ${res.status}`, "HTTP_ERROR", res.status);
+      }
+      return { data: await res.arrayBuffer(), error: null };
+    } catch (err) {
+      return { data: null, error: toHydrousError(err) };
+    }
   }
-  // ── Email: verify confirm ──────────────────────────────────────────────────
+  // ══════════════════════════════════════════════════════════════════════════
+  // BATCH DOWNLOAD
+  // ══════════════════════════════════════════════════════════════════════════
   /**
-   * Confirm email address using the token from the verification email.
+   * Download multiple files in one request.
    *
-   * @example
-   * await db.auth.confirmEmailVerification({ verifyToken: 'tok_...' });
-   */
-  async confirmEmailVerification(payload, opts) {
-    return this.http.post(`${this.path}/email/verify/confirm`, payload, opts);
-  }
-  // ── Account: lock ──────────────────────────────────────────────────────────
-  /**
-   * Lock a user account for a given duration (default: 15 min).
+   * Set `autoSave: true` (browser only) to trigger a Save dialog per file.
    *
    * @example
-   * await db.auth.lockAccount({ userId: 'user_abc', duration: 30 * 60 * 1000 });
+   * const { data } = await db.storage('reports').batchDownload(
+   *   ['jan.pdf', 'feb.pdf'],
+   *   { autoSave: true, onProgress: (p) => console.log(p.path, p.status) }
+   * );
    */
-  async lockAccount(payload, opts) {
-    return this.http.post(`${this.path}/account/lock`, payload, opts);
+  async batchDownload(filePaths, options = {}) {
+    var _a;
+    const { concurrency = 5, onProgress, autoSave = false } = options;
+    try {
+      const res = await fetch(`${this.base}/batch-download`, {
+        method: "POST",
+        headers: jsonHeaders(this.key),
+        body: JSON.stringify({ paths: filePaths, concurrency })
+      });
+      if (!res.ok) {
+        const e = await res.json().catch(() => ({}));
+        throw new HydrousDBError((_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);
+          downloadedFiles.push({ path, content: bytes.buffer, mimeType, size });
+          onProgress == null ? void 0 : onProgress({ index, total: filePaths.length, path, status: "success", size, mimeType });
+          if (autoSave && isBrowser) {
+            const blob = new Blob([bytes.buffer], { 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 (paginated).
    *
    * @example
-   * await db.auth.unlockAccount('user_abc');
+   * const { data } = await db.storage('avatars').list({ prefix: 'users/' });
+   * for (const item of data!.items) {
+   *   console.log(item.type, item.path, item.size);
+   * }
    */
-  async unlockAccount(userId, opts) {
-    return this.http.post(`${this.path}/account/unlock`, { userId }, opts);
+  async list(options = {}) {
+    const { prefix = "", limit = 50, cursor } = options;
+    try {
+      const url = buildUrl(this.base, "list", {
+        prefix: prefix || void 0,
+        limit,
+        cursor: cursor || void 0
+      });
+      const res = await fetch(url.replace(this.base + "/list", `${this.base}/list`), {
+        headers: storageHeaders(this.key)
+      });
+      const u = `${this.base}/list?${new URLSearchParams(
+        Object.entries({ prefix: prefix || "", limit: String(limit), ...cursor ? { cursor } : {} }).filter(([, v]) => v !== "")
+      ).toString()}`;
+      const r = await fetch(u, { headers: storageHeaders(this.key) });
+      const json = await parseResponse(r);
+      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 file (size, MIME type, compression, etc.)
    *
    * @example
-   * const users = await db.auth.listAllUsers();
+   * const { data: meta } = await db.storage('docs').metadata('report.pdf');
+   * console.log(meta!.size, meta!.mimeType, meta!.isCompressed);
    */
-  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;
-  }
-  /** Builds the path for a given bucket: /api/analytics/:bucketKey/:securityKey */
-  path(bucketKey) {
-    return `/api/analytics/${bucketKey}/${this.http.securityKey}`;
+  async metadata(filePath) {
+    try {
+      const res = await fetch(`${this.base}/metadata/${filePath}`, {
+        headers: storageHeaders(this.key)
+      });
+      const json = await parseResponse(res);
+      return { data: json.data, error: null };
+    } catch (err) {
+      return { data: null, error: toHydrousError(err) };
+    }
   }
-  // ── Raw query ─────────────────────────────────────────────────────────────
-  /**
-   * Run any analytics query with full control over the payload.
-   * Prefer the typed convenience methods below for everyday use.
-   */
-  async query(payload, options) {
-    const { bucketKey, ...rest } = options;
-    return this.http.post(this.path(bucketKey), payload, rest);
+  // ══════════════════════════════════════════════════════════════════════════
+  // DELETE
+  // ══════════════════════════════════════════════════════════════════════════
+  /** Delete a single file */
+  async deleteFile(filePath) {
+    try {
+      const res = await fetch(`${this.base}/file`, {
+        method: "DELETE",
+        headers: jsonHeaders(this.key),
+        body: JSON.stringify({ path: filePath })
+      });
+      await parseResponse(res);
+      return { data: void 0, error: null };
+    } catch (err) {
+      return { data: null, error: toHydrousError(err) };
+    }
   }
-  // ── count ──────────────────────────────────────────────────────────────────
-  /**
-   * Total record count, optionally scoped to a date range.
-   *
-   * @example
-   * const { data } = await db.analytics.count({ bucketKey: 'orders' });
-   * console.log(data.count);
-   *
-   * const { data } = await db.analytics.count({
-   *   bucketKey: 'orders',
-   *   dateRange: { startDate: '2025-01-01', endDate: '2025-12-31' },
-   * });
-   */
-  async count(options) {
-    const { dateRange, ...rest } = options;
-    return this.query({ queryType: "count", dateRange }, rest);
+  /** Recursively delete a folder and all its contents */
+  async deleteFolder(folderPath) {
+    try {
+      const res = await fetch(`${this.base}/folder`, {
+        method: "DELETE",
+        headers: jsonHeaders(this.key),
+        body: JSON.stringify({ path: folderPath })
+      });
+      await parseResponse(res);
+      return { data: void 0, error: null };
+    } catch (err) {
+      return { data: null, error: toHydrousError(err) };
+    }
   }
-  // ── distribution ───────────────────────────────────────────────────────────
-  /**
-   * Value distribution (histogram) for a field.
-   *
-   * @example
-   * const { data } = await db.analytics.distribution('status', { bucketKey: 'orders' });
-   * // [{ value: 'active', count: 80 }, { value: 'archived', count: 20 }]
-   */
-  async distribution(field, options) {
-    const { limit, order, dateRange, ...rest } = options;
-    return this.query({ queryType: "distribution", field, limit, order, dateRange }, rest);
+  /** Create an empty folder */
+  async createFolder(folderPath) {
+    try {
+      const res = await fetch(`${this.base}/folder`, {
+        method: "POST",
+        headers: jsonHeaders(this.key),
+        body: JSON.stringify({ path: folderPath })
+      });
+      await parseResponse(res);
+      return { data: void 0, error: null };
+    } catch (err) {
+      return { data: null, error: toHydrousError(err) };
+    }
   }
-  // ── sum ────────────────────────────────────────────────────────────────────
-  /**
-   * Sum a numeric field, with optional group-by.
-   *
-   * @example
-   * const { data } = await db.analytics.sum('revenue', { bucketKey: 'orders', groupBy: 'region' });
-   */
-  async sum(field, options) {
-    const { groupBy, limit, dateRange, ...rest } = options;
-    return this.query({ queryType: "sum", field, groupBy, limit, dateRange }, rest);
+  // ══════════════════════════════════════════════════════════════════════════
+  // MOVE & COPY
+  // ══════════════════════════════════════════════════════════════════════════
+  /** Move (rename) a file */
+  async move(fromPath, toPath) {
+    try {
+      const res = await fetch(`${this.base}/move`, {
+        method: "POST",
+        headers: jsonHeaders(this.key),
+        body: JSON.stringify({ from: fromPath, to: toPath })
+      });
+      await parseResponse(res);
+      return { data: void 0, error: null };
+    } catch (err) {
+      return { data: null, error: toHydrousError(err) };
+    }
   }
-  // ── timeSeries ─────────────────────────────────────────────────────────────
-  /**
-   * Record count grouped over time.
-   *
-   * @example
-   * const { data } = await db.analytics.timeSeries({ bucketKey: 'orders', granularity: 'day' });
-   * // [{ date: '2025-01-01', count: 42 }, ...]
-   */
-  async timeSeries(options) {
-    const { granularity, dateRange, ...rest } = options;
-    return this.query({ queryType: "timeSeries", granularity, dateRange }, rest);
+  /** Copy a file (original is kept) */
+  async copy(fromPath, toPath) {
+    try {
+      const res = await fetch(`${this.base}/copy`, {
+        method: "POST",
+        headers: jsonHeaders(this.key),
+        body: JSON.stringify({ from: fromPath, to: toPath })
+      });
+      await parseResponse(res);
+      return { data: void 0, error: null };
+    } catch (err) {
+      return { data: null, error: toHydrousError(err) };
+    }
   }
-  // ── fieldTimeSeries ────────────────────────────────────────────────────────
+  // ══════════════════════════════════════════════════════════════════════════
+  // SIGNED URL
+  // ══════════════════════════════════════════════════════════════════════════
   /**
-   * Aggregate a numeric field over time.
+   * Generate a time-limited public URL for a private file.
    *
    * @example
-   * const { data } = await db.analytics.fieldTimeSeries('revenue', {
-   *   bucketKey: 'orders',
-   *   granularity: 'month',
-   *   aggregation: 'sum',
-   * });
+   * const { data } = await db.storage('contracts').signedUrl('nda.pdf', { expiresIn: 300 });
+   * console.log(data!.signedUrl); // share this
    */
-  async fieldTimeSeries(field, options) {
-    const { aggregation, granularity, dateRange, ...rest } = options;
-    return this.query({ queryType: "fieldTimeSeries", field, aggregation, granularity, dateRange }, rest);
+  async signedUrl(filePath, options = {}) {
+    const { expiresIn = 3600 } = options;
+    try {
+      const res = await fetch(`${this.base}/signed-url`, {
+        method: "POST",
+        headers: jsonHeaders(this.key),
+        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) };
+    }
   }
-  // ── topN ───────────────────────────────────────────────────────────────────
+  // ══════════════════════════════════════════════════════════════════════════
+  // STATS
+  // ══════════════════════════════════════════════════════════════════════════
   /**
-   * Top N most frequent values for a field.
+   * Get usage and billing stats for this storage key.
    *
    * @example
-   * const { data } = await db.analytics.topN('country', 5, { bucketKey: 'users' });
-   * // [{ label: 'US', value: 'US', count: 500 }, ...]
+   * const { data } = await db.storage('main').stats();
+   * console.log(data!.totalFiles, data!.totalSizeBytes);
    */
-  async topN(field, n = 10, options) {
-    const { labelField, order, dateRange, ...rest } = options;
-    return this.query({ queryType: "topN", field, n, labelField, order, dateRange }, rest);
+  async stats() {
+    try {
+      const res = await fetch(`${this.base}/stats`, {
+        headers: storageHeaders(this.key)
+      });
+      const json = await parseResponse(res);
+      return { data: json.data, error: null };
+    } catch (err) {
+      return { data: null, error: toHydrousError(err) };
+    }
   }
-  // ── stats ──────────────────────────────────────────────────────────────────
-  /**
-   * Statistical summary for a numeric field: min, max, avg, stddev, p50, p90, p99.
-   *
-   * @example
-   * const { data } = await db.analytics.stats('score', { bucketKey: 'users' });
-   * console.log(data.avg, data.p99);
-   */
-  async stats(field, options) {
-    const { dateRange, ...rest } = options;
-    return this.query({ queryType: "stats", field, dateRange }, rest);
+};
+
+// src/storage/manager.ts
+var StorageManager = class {
+  constructor(config) {
+    this.cache = /* @__PURE__ */ new Map();
+    this.baseUrl = config.url;
+    this._keys = config.storageKeys;
   }
-  // ── records ────────────────────────────────────────────────────────────────
   /**
-   * Filtered, paginated raw records with optional field projection.
-   * Supports filter ops: == != > < >= <= CONTAINS
+   * Get a storage client scoped to a named key.
    *
-   * @example
-   * const { data } = await db.analytics.records({
-   *   bucketKey: 'users',
-   *   filters: [{ field: 'role', op: '==', value: 'admin' }],
-   *   selectFields: ['email', 'createdAt'],
-   *   limit: 25,
-   * });
-   */
-  async records(options) {
-    const { filters, selectFields, limit, offset, orderBy, order, dateRange, ...rest } = options;
-    return this.query(
-      { queryType: "records", filters, selectFields, limit, offset, orderBy, order, dateRange },
-      rest
-    );
-  }
-  // ── multiMetric ────────────────────────────────────────────────────────────
-  /**
-   * Multiple aggregations in a single call — ideal for dashboard stat cards.
+   * @param keyName - Must match a property you declared in `storageKeys`
    *
    * @example
-   * const { data } = await db.analytics.multiMetric(
-   *   [
-   *     { name: 'totalRevenue', field: 'amount', aggregation: 'sum' },
-   *     { name: 'avgScore',     field: 'score',  aggregation: 'avg' },
-   *   ],
-   *   { bucketKey: 'orders' }
-   * );
-   * console.log(data.totalRevenue, data.avgScore);
-   */
-  async multiMetric(metrics, options) {
-    const { dateRange, ...rest } = options;
-    return this.query({ queryType: "multiMetric", metrics, dateRange }, rest);
-  }
-  // ── storageStats ───────────────────────────────────────────────────────────
-  /**
-   * Storage statistics for a bucket — total records, bytes, avg/min/max size.
+   * const avatarStore   = db.storage('avatars');
+   * const documentStore = db.storage('documents');
    *
-   * @example
-   * const { data } = await db.analytics.storageStats({ bucketKey: 'orders' });
-   * console.log(data.totalRecords, data.totalBytes);
+   * await avatarStore.upload(file, { path: 'users/alice.jpg' });
+   * const list = await documentStore.list({ prefix: 'invoices/' });
    */
-  async storageStats(options) {
-    const { dateRange, ...rest } = options;
-    return this.query({ queryType: "storageStats", dateRange }, rest);
+  use(keyName) {
+    const bucketKey = this._keys[keyName];
+    if (!bucketKey) {
+      const available = Object.keys(this._keys).join(", ");
+      throw new HydrousDBError(
+        `Storage key "${keyName}" is not defined.
+Available: ${available || "(none)"}`,
+        "UNKNOWN_STORAGE_KEY"
+      );
+    }
+    if (!this.cache.has(keyName)) {
+      this.cache.set(keyName, new ScopedStorageClient(this.baseUrl, keyName, bucketKey));
+    }
+    return this.cache.get(keyName);
   }
-  // ── crossBucket ────────────────────────────────────────────────────────────
-  /**
-   * Compare a metric across multiple buckets in one query.
-   * Note: `bucketKey` here is used only for auth — the actual buckets
-   * compared are specified via `bucketKeys`.
-   *
-   * @example
-   * const { data } = await db.analytics.crossBucket({
-   *   bucketKey:   'sales-2025',   // auth bucket
-   *   bucketKeys:  ['sales-2024', 'sales-2025'],
-   *   field:       'amount',
-   *   aggregation: 'sum',
-   * });
-   */
-  async crossBucket(options) {
-    const { bucketKeys, field, aggregation, dateRange, ...rest } = options;
-    return this.query({ queryType: "crossBucket", bucketKeys, field, aggregation, dateRange }, rest);
+  /** Return the names of all configured storage keys */
+  keyNames() {
+    return Object.keys(this._keys);
   }
 };
 
 // src/client.ts
 var HydrousClient = class {
   constructor(config) {
-    if (!config.authKey) throw new Error("[hydrousdb] authKey is required");
-    if (!config.securityKey) throw new Error("[hydrousdb] securityKey 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("[HydrousDB] config.url is required");
+    if (!config.authKey) throw new Error("[HydrousDB] config.authKey is required");
+    if (!config.bucketSecurityKey) throw new Error("[HydrousDB] config.bucketSecurityKey is required");
+    if (!config.storageKeys || typeof config.storageKeys !== "object") {
+      throw new Error("[HydrousDB] config.storageKeys must be an object of named keys");
+    }
+    this.auth = new AuthClient(config);
+    this.records = new RecordsClient(config);
+    this.analytics = new AnalyticsClient(config);
+    const manager = new StorageManager(config);
+    const fn = (keyName) => manager.use(keyName);
+    fn.use = (keyName) => manager.use(keyName);
+    fn.keyNames = () => manager.keyNames();
+    this.storage = fn;
   }
 };
+
+// src/index.ts
 function createClient(config) {
   return new HydrousClient(config);
 }
@@ -766,10 +1038,18 @@ function createClient(config) {
 exports.AnalyticsClient = AnalyticsClient;
 exports.AuthClient = AuthClient;
 exports.HydrousClient = HydrousClient;
-exports.HydrousError = HydrousError;
-exports.HydrousNetworkError = HydrousNetworkError;
-exports.HydrousTimeoutError = HydrousTimeoutError;
+exports.HydrousDBError = HydrousDBError;
 exports.RecordsClient = RecordsClient;
+exports.ScopedStorageClient = ScopedStorageClient;
+exports.StorageManager = StorageManager;
 exports.createClient = createClient;
+exports.eq = eq;
+exports.gt = gt;
+exports.gte = gte;
+exports.inArray = inArray;
+exports.isHydrousError = isHydrousError;
+exports.lt = lt;
+exports.lte = lte;
+exports.neq = neq;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map