hydrousdb 2.0.3 → 3.0.0

package/dist/index.js

@@ -1,1055 +1,1632 @@
-'use strict';
-
 // src/utils/errors.ts
-var HydrousDBError = class extends Error {
-  constructor(message, code = "SDK_ERROR", status) {
+var HydrousError = class extends Error {
+  constructor(message, code, status, requestId, details) {
     super(message);
-    this.name = "HydrousDBError";
+    this.name = "HydrousError";
     this.code = code;
     this.status = status;
+    this.requestId = requestId;
+    this.details = details;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+  toString() {
+    return `HydrousError [${this.code}]: ${this.message}`;
   }
 };
-function toHydrousError(err) {
-  if (err instanceof HydrousDBError) {
-    return { message: err.message, code: err.code, status: err.status };
+var AuthError = class extends HydrousError {
+  constructor(message, code, status, requestId, details) {
+    super(message, code, status, requestId, details);
+    this.name = "AuthError";
   }
-  if (err instanceof Error) {
-    return { message: err.message, code: "UNKNOWN_ERROR" };
+};
+var RecordError = class extends HydrousError {
+  constructor(message, code, status, requestId, details) {
+    super(message, code, status, requestId, details);
+    this.name = "RecordError";
   }
-  return { message: String(err), code: "UNKNOWN_ERROR" };
-}
-function isHydrousError(err) {
-  return err instanceof HydrousDBError;
-}
-
-// src/utils/http.ts
-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;
-  }
-  if (!res.ok) {
-    const e = body;
-    throw new HydrousDBError(
-      e.error || e.message || `HTTP ${res.status}`,
-      e.code || "HTTP_ERROR",
-      res.status
-    );
+};
+var StorageError = class extends HydrousError {
+  constructor(message, code, status, requestId) {
+    super(message, code, status, requestId);
+    this.name = "StorageError";
   }
-  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));
-    }
+};
+var AnalyticsError = class extends HydrousError {
+  constructor(message, code, status, requestId) {
+    super(message, code, status, requestId);
+    this.name = "AnalyticsError";
   }
-  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 }));
+};
+var ValidationError = class extends HydrousError {
+  constructor(message, details) {
+    super(message, "VALIDATION_ERROR", 400, void 0, details);
+    this.name = "ValidationError";
   }
-  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) {
-    }
+};
+var NetworkError = class extends HydrousError {
+  constructor(message, cause) {
+    super(message, "NETWORK_ERROR");
+    this.name = "NetworkError";
+    this.cause = cause;
   }
-}
-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}`
-    };
+// src/utils/http.ts
+var DEFAULT_BASE_URL = "https://db-api-82687684612.us-central1.run.app";
+var HttpClient = class {
+  constructor(baseUrl, securityKey) {
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+    this.securityKey = securityKey;
   }
-  /** 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) };
+  async request(path, opts = {}) {
+    const {
+      method = "GET",
+      body,
+      headers = {},
+      rawBody,
+      contentType = "application/json"
+    } = opts;
+    const url = `${this.baseUrl}${path}`;
+    const reqHeaders = {
+      "X-Api-Key": this.securityKey,
+      ...headers
+    };
+    let reqBody = null;
+    if (rawBody !== void 0) {
+      reqBody = rawBody;
+      if (contentType) reqHeaders["Content-Type"] = contentType;
+    } else if (body !== void 0) {
+      reqBody = JSON.stringify(body);
+      reqHeaders["Content-Type"] = "application/json";
     }
-  }
-  /** Sign in with email and password */
-  async signIn(options) {
+    let response;
     try {
-      const res = await fetch(buildUrl(this.baseUrl, "auth/signin"), {
-        method: "POST",
-        headers: this.headers,
-        body: JSON.stringify(options)
+      response = await fetch(url, {
+        method,
+        headers: reqHeaders,
+        body: reqBody
       });
-      const json = await parseResponse(res);
-      this.session = json.data;
-      return { data: json.data, error: null };
     } catch (err) {
-      return { data: null, error: toHydrousError(err) };
+      throw new NetworkError(
+        `Network request failed: ${err instanceof Error ? err.message : String(err)}`,
+        err
+      );
     }
-  }
-  /** Sign out and invalidate the current session */
-  async signOut() {
-    try {
-      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) {
-      return { data: null, error: toHydrousError(err) };
+    const ct = response.headers.get("content-type") ?? "";
+    if (!ct.includes("application/json")) {
+      if (!response.ok) {
+        throw new HydrousError(
+          `Request failed with status ${response.status}`,
+          `HTTP_${response.status}`,
+          response.status
+        );
+      }
+      const buffer = await response.arrayBuffer();
+      return buffer;
     }
-  }
-  /** Get the currently authenticated user */
-  async getUser() {
+    let responseData;
     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" } };
+      responseData = await response.json();
+    } catch {
+      throw new HydrousError(
+        "Failed to parse server response as JSON",
+        "PARSE_ERROR",
+        response.status
+      );
     }
-    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) };
+    if (!response.ok) {
+      const errData = responseData;
+      throw new HydrousError(
+        errData["error"] ?? `Request failed with status ${response.status}`,
+        errData["code"] ?? `HTTP_${response.status}`,
+        response.status,
+        errData["requestId"],
+        errData["details"]
+      );
     }
+    return responseData;
   }
-  /** Return the current in-memory session (may be null) */
-  getSession() {
-    return this.session;
+  get(path, headers) {
+    return this.request(path, { method: "GET", headers });
   }
-  _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;
-}
-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(config) {
-    this.baseUrl = config.url;
-    this.headers = {
-      "Content-Type": "application/json",
-      "Authorization": `Bearer ${config.bucketSecurityKey}`
-    };
+  post(path, body, headers) {
+    return this.request(path, { method: "POST", body, headers });
   }
-  /** 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) };
-    }
+  put(path, body, headers) {
+    return this.request(path, { method: "PUT", body, headers });
   }
-  /** 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) };
-    }
+  patch(path, body, headers) {
+    return this.request(path, { method: "PATCH", body, headers });
   }
-  /** 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) };
-    }
+  delete(path, body, headers) {
+    return this.request(path, { method: "DELETE", body, headers });
   }
-  /** 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)
+  async putToSignedUrl(signedUrl, data, mimeType, onProgress) {
+    if (typeof XMLHttpRequest !== "undefined" && onProgress) {
+      return new Promise((resolve, reject) => {
+        const xhr = new XMLHttpRequest();
+        xhr.upload.onprogress = (e) => {
+          if (e.lengthComputable) {
+            onProgress(Math.round(e.loaded / e.total * 100));
+          }
+        };
+        xhr.onload = () => {
+          if (xhr.status >= 200 && xhr.status < 300) {
+            resolve();
+          } else {
+            reject(new Error(`Upload failed: ${xhr.status}`));
+          }
+        };
+        xhr.onerror = () => reject(new Error("Upload network error"));
+        xhr.open("PUT", signedUrl);
+        xhr.setRequestHeader("Content-Type", mimeType);
+        const payload = data instanceof Blob ? data : new Blob([data], { type: mimeType });
+        xhr.send(payload);
       });
-      const json = await parseResponse(res);
-      return { data: json.data, error: null };
-    } catch (err) {
-      return { data: null, error: toHydrousError(err) };
     }
-  }
-  /** 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) };
+    const fetchBody = data instanceof Blob ? data : new Blob([data], { type: mimeType });
+    const response = await fetch(signedUrl, {
+      method: "PUT",
+      headers: { "Content-Type": mimeType },
+      body: fetchBody
+    });
+    if (!response.ok) {
+      throw new NetworkError(`Signed URL upload failed with status ${response.status}`);
     }
   }
 };
 
-// src/analytics/client.ts
-var AnalyticsClient = class {
-  constructor(config) {
-    this.baseUrl = config.url;
-    this.headers = {
-      "Content-Type": "application/json",
-      "Authorization": `Bearer ${config.bucketSecurityKey}`
-    };
-  }
-  /** 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) };
-    }
-  }
-  /** 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) };
-    }
+// src/auth/client.ts
+var AuthClient = class {
+  constructor(http, bucketKey) {
+    this.http = http;
+    this.bucketKey = bucketKey;
+    this.basePath = `/auth/${bucketKey}`;
   }
-  /** 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) };
-    }
+  // ─── Registration & Login ─────────────────────────────────────────────────
+  /**
+   * Register a new user in this bucket.
+   *
+   * @example
+   * ```ts
+   * const { user, session } = await auth.signup({
+   *   email: 'alice@example.com',
+   *   password: 'hunter2',
+   *   fullName: 'Alice Wonderland',
+   *   // Any extra fields are stored on the user record:
+   *   plan: 'pro',
+   * });
+   * ```
+   */
+  async signup(options) {
+    const result = await this.http.post(`${this.basePath}/signup`, options);
+    return { user: result.user, session: result.session };
   }
-};
-
-// 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;
+  /**
+   * Authenticate an existing user and create a session.
+   * Sessions are valid for 24 hours; use `refreshSession` to extend.
+   *
+   * @example
+   * ```ts
+   * const { user, session } = await auth.login({
+   *   email: 'alice@example.com',
+   *   password: 'hunter2',
+   * });
+   * // Store session.sessionId safely — you'll need it for other calls.
+   * ```
+   */
+  async login(options) {
+    const result = await this.http.post(`${this.basePath}/login`, options);
+    return { user: result.user, session: result.session };
   }
-  // ══════════════════════════════════════════════════════════════════════════
-  // UPLOAD — single file
-  // ══════════════════════════════════════════════════════════════════════════
   /**
-   * Upload a single file.
+   * Invalidate a session (sign out).
    *
-   * Supply `onProgress` to receive live upload ticks including bytes
-   * transferred, speed (bytes/sec), ETA, and lifecycle stage.
+   * @example
+   * ```ts
+   * await auth.logout({ sessionId: session.sessionId });
+   * ```
+   */
+  async logout({ sessionId }) {
+    await this.http.post(`${this.basePath}/logout`, { sessionId });
+  }
+  /**
+   * Extend a session using its refresh token.
+   * Returns a new session object.
    *
-   * **Stage sequence:**
-   * `pending → compressing → uploading → done | error`
+   * @example
+   * ```ts
+   * const newSession = await auth.refreshSession({ refreshToken: session.refreshToken });
+   * ```
+   */
+  async refreshSession({ refreshToken }) {
+    const result = await this.http.post(
+      `${this.basePath}/session/refresh`,
+      { refreshToken }
+    );
+    return result.session;
+  }
+  // ─── User Profile ─────────────────────────────────────────────────────────
+  /**
+   * Fetch a user by their ID.
    *
-   * 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
+   * ```ts
+   * const user = await auth.getUser({ userId: 'usr_abc123' });
+   * ```
+   */
+  async getUser({ userId }) {
+    const result = await this.http.get(`${this.basePath}/user/${userId}`);
+    return result.user;
+  }
+  /**
+   * Update fields on a user record. Requires a valid session.
    *
    * @example
-   * 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`);
-   *   },
+   * ```ts
+   * const updated = await auth.updateUser({
+   *   sessionId: session.sessionId,
+   *   userId: user.id,
+   *   data: { fullName: 'Alice Smith', plan: 'enterprise' },
    * });
+   * ```
    */
-  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) };
-    }
+  async updateUser(options) {
+    const { sessionId, userId, data } = options;
+    const result = await this.http.patch(
+      `${this.basePath}/user`,
+      { sessionId, userId, ...data }
+    );
+    return result.user;
   }
-  // ══════════════════════════════════════════════════════════════════════════
-  // UPLOAD TEXT / JSON
-  // ══════════════════════════════════════════════════════════════════════════
   /**
-   * Upload raw text or JSON content directly — no File object needed.
+   * Soft-delete a user. The record is marked deleted but not removed from storage.
+   * Requires a valid session (the user can delete themselves, or an admin can delete any user).
    *
    * @example
-   * // Save a JSON config
-   * await db.storage('configs').uploadText(
-   *   'settings/app.json',
-   *   JSON.stringify({ theme: 'dark' }),
-   *   { mimeType: 'application/json' }
-   * );
+   * ```ts
+   * await auth.deleteUser({ sessionId: session.sessionId, userId: user.id });
+   * ```
    */
-  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) };
-    }
+  async deleteUser({ sessionId, userId }) {
+    await this.http.delete(`${this.basePath}/user`, { sessionId, userId });
   }
-  // ══════════════════════════════════════════════════════════════════════════
-  // BATCH UPLOAD
-  // ══════════════════════════════════════════════════════════════════════════
+  // ─── Admin Operations ─────────────────────────────────────────────────────
   /**
-   * Upload multiple files in one request.
-   *
-   * `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.
+   * List all users in the bucket. **Admin session required.**
    *
    * @example
-   * await db.storage('documents').batchUpload(files, {
-   *   prefix:     'reports/2024/',
-   *   onProgress: (p) => updateBar(p.index, p.percent),
+   * ```ts
+   * const { users, total } = await auth.listUsers({
+   *   sessionId: adminSession.sessionId,
+   *   limit: 50,
+   *   offset: 0,
    * });
+   * ```
    */
-  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) };
-    }
+  async listUsers(options) {
+    const { sessionId, limit = 50, offset = 0 } = options;
+    const result = await this.http.post(
+      `${this.basePath}/users/list`,
+      { sessionId, limit, offset }
+    );
+    return { users: result.users, total: result.total, limit: result.limit, offset: result.offset };
   }
-  // ══════════════════════════════════════════════════════════════════════════
-  // DOWNLOAD
-  // ══════════════════════════════════════════════════════════════════════════
   /**
-   * Download a single file and return its content as an `ArrayBuffer`.
+   * Permanently hard-delete a user and all their data. **Admin session required.**
+   * This action is irreversible.
    *
    * @example
-   * const { data } = await db.storage('avatars').download('users/alice.jpg');
-   * const blob = new Blob([data!]);
-   * img.src = URL.createObjectURL(blob);
+   * ```ts
+   * await auth.hardDeleteUser({ sessionId: adminSession.sessionId, userId: user.id });
+   * ```
    */
-  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) };
-    }
+  async hardDeleteUser({ sessionId, userId }) {
+    await this.http.delete(`${this.basePath}/user/hard`, { sessionId, userId });
   }
-  // ══════════════════════════════════════════════════════════════════════════
-  // BATCH DOWNLOAD
-  // ══════════════════════════════════════════════════════════════════════════
   /**
-   * Download multiple files in one request.
-   *
-   * Set `autoSave: true` (browser only) to trigger a Save dialog per file.
+   * Bulk delete multiple users. **Admin session required.**
    *
    * @example
-   * const { data } = await db.storage('reports').batchDownload(
-   *   ['jan.pdf', 'feb.pdf'],
-   *   { autoSave: true, onProgress: (p) => console.log(p.path, p.status) }
-   * );
+   * ```ts
+   * const result = await auth.bulkDeleteUsers({
+   *   sessionId: adminSession.sessionId,
+   *   userIds: ['usr_a', 'usr_b'],
+   * });
+   * ```
    */
-  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) };
-    }
+  async bulkDeleteUsers({
+    sessionId,
+    userIds
+  }) {
+    const result = await this.http.post(
+      `${this.basePath}/users/bulk-delete`,
+      { sessionId, userIds }
+    );
+    return { deleted: result.deleted, failed: result.failed };
   }
-  // ══════════════════════════════════════════════════════════════════════════
-  // LIST
-  // ══════════════════════════════════════════════════════════════════════════
   /**
-   * List files and folders (paginated).
+   * Lock a user account, preventing login. **Admin session required.**
+   *
+   * @param options.duration Lock duration in milliseconds. Defaults to 15 minutes.
    *
    * @example
-   * const { data } = await db.storage('avatars').list({ prefix: 'users/' });
-   * for (const item of data!.items) {
-   *   console.log(item.type, item.path, item.size);
-   * }
+   * ```ts
+   * await auth.lockAccount({
+   *   sessionId: adminSession.sessionId,
+   *   userId: user.id,
+   *   duration: 60 * 60 * 1000, // 1 hour
+   * });
+   * ```
    */
-  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) };
-    }
+  async lockAccount({
+    sessionId,
+    userId,
+    duration
+  }) {
+    const result = await this.http.post(`${this.basePath}/account/lock`, { sessionId, userId, duration });
+    return result.data;
   }
-  // ══════════════════════════════════════════════════════════════════════════
-  // METADATA
-  // ══════════════════════════════════════════════════════════════════════════
   /**
-   * Get metadata for a file (size, MIME type, compression, etc.)
+   * Unlock a previously locked user account. **Admin session required.**
    *
    * @example
-   * const { data: meta } = await db.storage('docs').metadata('report.pdf');
-   * console.log(meta!.size, meta!.mimeType, meta!.isCompressed);
+   * ```ts
+   * await auth.unlockAccount({ sessionId: adminSession.sessionId, userId: user.id });
+   * ```
    */
-  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) };
-    }
-  }
-  // ══════════════════════════════════════════════════════════════════════════
-  // 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) };
-    }
-  }
-  /** 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) };
-    }
-  }
-  /** 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) };
-    }
-  }
-  // ══════════════════════════════════════════════════════════════════════════
-  // 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) };
-    }
-  }
-  /** 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) };
-    }
+  async unlockAccount({
+    sessionId,
+    userId
+  }) {
+    await this.http.post(`${this.basePath}/account/unlock`, { sessionId, userId });
   }
-  // ══════════════════════════════════════════════════════════════════════════
-  // SIGNED URL
-  // ══════════════════════════════════════════════════════════════════════════
+  // ─── Password Management ──────────────────────────────────────────────────
   /**
-   * Generate a time-limited public URL for a private file.
+   * Change a user's password. The user must supply their current password.
    *
    * @example
-   * const { data } = await db.storage('contracts').signedUrl('nda.pdf', { expiresIn: 300 });
-   * console.log(data!.signedUrl); // share this
+   * ```ts
+   * await auth.changePassword({
+   *   sessionId: session.sessionId,
+   *   userId: user.id,
+   *   currentPassword: 'hunter2',
+   *   newPassword: 'correcthorsebatterystaple',
+   * });
+   * ```
    */
-  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) };
-    }
+  async changePassword(options) {
+    await this.http.post(`${this.basePath}/password/change`, options);
   }
-  // ══════════════════════════════════════════════════════════════════════════
-  // STATS
-  // ══════════════════════════════════════════════════════════════════════════
   /**
-   * Get usage and billing stats for this storage key.
+   * Request a password reset email for a user.
+   * Always returns success to prevent user enumeration.
    *
    * @example
-   * const { data } = await db.storage('main').stats();
-   * console.log(data!.totalFiles, data!.totalSizeBytes);
+   * ```ts
+   * await auth.requestPasswordReset({ email: 'alice@example.com' });
+   * ```
    */
-  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) };
-    }
-  }
-};
-
-// src/storage/manager.ts
-var StorageManager = class {
-  constructor(config) {
-    this.cache = /* @__PURE__ */ new Map();
-    this.baseUrl = config.url;
-    this._keys = config.storageKeys;
+  async requestPasswordReset({ email }) {
+    await this.http.post(`${this.basePath}/password/reset/request`, { email });
   }
   /**
-   * Get a storage client scoped to a named key.
-   *
-   * @param keyName - Must match a property you declared in `storageKeys`
+   * Complete a password reset using the token from the reset email.
    *
    * @example
-   * const avatarStore   = db.storage('avatars');
-   * const documentStore = db.storage('documents');
+   * ```ts
+   * await auth.confirmPasswordReset({
+   *   resetToken: 'tok_from_email',
+   *   newPassword: 'correcthorsebatterystaple',
+   * });
+   * ```
+   */
+  async confirmPasswordReset({
+    resetToken,
+    newPassword
+  }) {
+    await this.http.post(`${this.basePath}/password/reset/confirm`, {
+      resetToken,
+      newPassword
+    });
+  }
+  // ─── Email Verification ───────────────────────────────────────────────────
+  /**
+   * Send (or resend) an email verification message to a user.
    *
-   * await avatarStore.upload(file, { path: 'users/alice.jpg' });
-   * const list = await documentStore.list({ prefix: 'invoices/' });
+   * @example
+   * ```ts
+   * await auth.requestEmailVerification({ userId: user.id });
+   * ```
    */
-  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);
+  async requestEmailVerification({ userId }) {
+    await this.http.post(`${this.basePath}/email/verify/request`, { userId });
   }
-  /** Return the names of all configured storage keys */
-  keyNames() {
-    return Object.keys(this._keys);
+  /**
+   * Confirm an email address using the token from the verification email.
+   *
+   * @example
+   * ```ts
+   * await auth.confirmEmailVerification({ verifyToken: 'tok_from_email' });
+   * ```
+   */
+  async confirmEmailVerification({ verifyToken }) {
+    await this.http.post(`${this.basePath}/email/verify/confirm`, { verifyToken });
   }
 };
 
-// src/client.ts
-var HydrousClient = class {
-  constructor(config) {
-    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/utils/query.ts
+function buildQueryParams(options = {}) {
+  const params = new URLSearchParams();
+  if (options.limit !== void 0) params.set("limit", String(options.limit));
+  if (options.offset !== void 0) params.set("offset", String(options.offset));
+  if (options.orderBy !== void 0) params.set("orderBy", options.orderBy);
+  if (options.order !== void 0) params.set("order", options.order);
+  if (options.fields !== void 0) params.set("fields", options.fields);
+  if (options.startAfter !== void 0) params.set("startAfter", options.startAfter);
+  if (options.startAt !== void 0) params.set("startAt", options.startAt);
+  if (options.endAt !== void 0) params.set("endAt", options.endAt);
+  if (options.dateRange?.start !== void 0)
+    params.set("startDate", new Date(options.dateRange.start).toISOString().split("T")[0]);
+  if (options.dateRange?.end !== void 0)
+    params.set("endDate", new Date(options.dateRange.end).toISOString().split("T")[0]);
+  if (options.filters && options.filters.length > 0) {
+    params.set("filters", JSON.stringify(options.filters));
   }
-};
-
-// src/index.ts
+  const str = params.toString();
+  return str ? `?${str}` : "";
+}
+function guessMimeType(filename) {
+  const ext = filename.split(".").pop()?.toLowerCase();
+  const map = {
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    png: "image/png",
+    gif: "image/gif",
+    webp: "image/webp",
+    svg: "image/svg+xml",
+    pdf: "application/pdf",
+    mp4: "video/mp4",
+    webm: "video/webm",
+    mp3: "audio/mpeg",
+    wav: "audio/wav",
+    txt: "text/plain",
+    html: "text/html",
+    css: "text/css",
+    js: "application/javascript",
+    json: "application/json",
+    xml: "application/xml",
+    zip: "application/zip",
+    csv: "text/csv"
+  };
+  return map[ext ?? ""] ?? "application/octet-stream";
+}
+function assertSafeName(name, label = "name") {
+  if (!/^[a-zA-Z_][a-zA-Z0-9_.\-]{0,200}$/.test(name)) {
+    throw new Error(
+      `Invalid ${label} "${name}". Must start with a letter or underscore and contain only letters, numbers, underscores, dots, or hyphens.`
+    );
+  }
+}
+
+// src/records/client.ts
+var RecordsClient = class {
+  constructor(http, bucketKey) {
+    assertSafeName(bucketKey, "bucketKey");
+    this.http = http;
+    this.bucketKey = bucketKey;
+    this.basePath = `/records/${bucketKey}`;
+  }
+  // ─── Single Record Operations ─────────────────────────────────────────────
+  /**
+   * Create a new record.
+   *
+   * @example
+   * ```ts
+   * const user = await records.create({
+   *   name: 'Alice',
+   *   email: 'alice@example.com',
+   *   score: 100,
+   * });
+   * console.log(user.id); // "rec_xxxxxxxx"
+   * ```
+   */
+  async create(data) {
+    const result = await this.http.post(this.basePath, data);
+    return result.record ?? result.data;
+  }
+  /**
+   * Fetch a single record by ID.
+   *
+   * @example
+   * ```ts
+   * const post = await records.get('rec_abc123');
+   * ```
+   */
+  async get(id) {
+    const result = await this.http.get(`${this.basePath}/${id}`);
+    return result.record ?? result.data;
+  }
+  /**
+   * Overwrite a record entirely (full replace).
+   *
+   * @example
+   * ```ts
+   * const updated = await records.set('rec_abc123', {
+   *   name: 'Alice Updated',
+   *   email: 'alice2@example.com',
+   * });
+   * ```
+   */
+  async set(id, data) {
+    const result = await this.http.put(`${this.basePath}/${id}`, data);
+    return result.record ?? result.data;
+  }
+  /**
+   * Partially update a record (merge by default).
+   *
+   * @example
+   * ```ts
+   * // Merge: only the provided fields are updated
+   * const updated = await records.patch('rec_abc123', { score: 200 });
+   *
+   * // Replace: equivalent to set()
+   * const replaced = await records.patch('rec_abc123', { score: 200 }, { merge: false });
+   * ```
+   */
+  async patch(id, data, options = {}) {
+    const { merge = true } = options;
+    const result = await this.http.patch(
+      `${this.basePath}/${id}`,
+      { ...data, _merge: merge }
+    );
+    return result.record ?? result.data;
+  }
+  /**
+   * Delete a record permanently.
+   *
+   * @example
+   * ```ts
+   * await records.delete('rec_abc123');
+   * ```
+   */
+  async delete(id) {
+    await this.http.delete(`${this.basePath}/${id}`);
+  }
+  // ─── Batch Operations ─────────────────────────────────────────────────────
+  /**
+   * Create multiple records in one request.
+   *
+   * @example
+   * ```ts
+   * const created = await records.batchCreate([
+   *   { name: 'Alice', score: 100 },
+   *   { name: 'Bob',   score: 200 },
+   * ]);
+   * ```
+   */
+  async batchCreate(items) {
+    const result = await this.http.post(
+      `${this.basePath}/batch`,
+      { records: items }
+    );
+    return result.records;
+  }
+  /**
+   * Delete multiple records by ID in one request.
+   *
+   * @example
+   * ```ts
+   * await records.batchDelete(['rec_a', 'rec_b', 'rec_c']);
+   * ```
+   */
+  async batchDelete(ids) {
+    const result = await this.http.post(`${this.basePath}/batch/delete`, { ids });
+    return { deleted: result.deleted, failed: result.failed };
+  }
+  // ─── Querying ─────────────────────────────────────────────────────────────
+  /**
+   * Query records with optional filters, sorting, and pagination.
+   *
+   * @example
+   * ```ts
+   * // Simple query
+   * const { records } = await posts.query({ limit: 10 });
+   *
+   * // Filtered query with cursor pagination
+   * const page1 = await posts.query({
+   *   filters: [
+   *     { field: 'status',    op: '==', value: 'published' },
+   *     { field: 'views',     op: '>',  value: 1000 },
+   *   ],
+   *   orderBy: 'createdAt',
+   *   order: 'desc',
+   *   limit: 20,
+   * });
+   *
+   * const page2 = await posts.query({
+   *   filters: [{ field: 'status', op: '==', value: 'published' }],
+   *   limit: 20,
+   *   startAfter: page1.nextCursor,
+   * });
+   * ```
+   */
+  async query(options = {}) {
+    const qs = buildQueryParams(options);
+    const result = await this.http.get(`${this.basePath}${qs}`);
+    return {
+      records: result.records,
+      total: result.total,
+      hasMore: result.hasMore,
+      nextCursor: result.nextCursor
+    };
+  }
+  /**
+   * Convenience alias: get all records up to `limit` (default 100).
+   *
+   * @example
+   * ```ts
+   * const allPosts = await posts.getAll({ limit: 500 });
+   * ```
+   */
+  async getAll(options = {}) {
+    const { records } = await this.query(options);
+    return records;
+  }
+  /**
+   * Count records matching optional filters.
+   *
+   * @example
+   * ```ts
+   * const total = await posts.count([{ field: 'status', op: '==', value: 'published' }]);
+   * ```
+   */
+  async count(filters = []) {
+    const result = await this.http.post(
+      `${this.basePath}/count`,
+      { filters }
+    );
+    return result.count;
+  }
+  // ─── Version History ──────────────────────────────────────────────────────
+  /**
+   * Retrieve the full version history of a record.
+   * Each write creates a new version stored in GCS.
+   *
+   * @example
+   * ```ts
+   * const history = await records.getHistory('rec_abc123');
+   * console.log(history[0].data); // latest version
+   * ```
+   */
+  async getHistory(id) {
+    const result = await this.http.get(`${this.basePath}/${id}/history`);
+    return result.history;
+  }
+  /**
+   * Restore a record to a specific historical version.
+   *
+   * @example
+   * ```ts
+   * const history = await records.getHistory('rec_abc123');
+   * const restored = await records.restoreVersion('rec_abc123', history[2].version);
+   * ```
+   */
+  async restoreVersion(id, version) {
+    const result = await this.http.post(
+      `${this.basePath}/${id}/restore`,
+      { version }
+    );
+    return result.record ?? result.data;
+  }
+};
+
+// src/analytics/client.ts
+var AnalyticsClient = class {
+  constructor(http, bucketKey) {
+    assertSafeName(bucketKey, "bucketKey");
+    this.http = http;
+    this.bucketKey = bucketKey;
+    this.basePath = `/analytics/${bucketKey}`;
+  }
+  /** Internal dispatcher — all queries POST to the same endpoint. */
+  async run(query) {
+    const result = await this.http.post(this.basePath, query);
+    return result.data;
+  }
+  // ─── Count ────────────────────────────────────────────────────────────────
+  /**
+   * Count the total number of records in the bucket, with optional date filter.
+   *
+   * @example
+   * ```ts
+   * const { count } = await analytics.count();
+   * // → { count: 4821 }
+   *
+   * // Count only this month's records
+   * const { count } = await analytics.count({
+   *   dateRange: { start: new Date('2025-01-01').getTime(), end: Date.now() },
+   * });
+   * ```
+   */
+  async count(opts = {}) {
+    return this.run({ queryType: "count", ...opts });
+  }
+  // ─── Distribution ─────────────────────────────────────────────────────────
+  /**
+   * Count how many records have each unique value for a given field.
+   * Great for pie charts and bar charts.
+   *
+   * @example
+   * ```ts
+   * const rows = await analytics.distribution({
+   *   field: 'status',
+   *   limit: 10,
+   *   order: 'desc',
+   * });
+   * // → [{ value: 'completed', count: 312 }, { value: 'pending', count: 88 }, ...]
+   * ```
+   */
+  async distribution(opts) {
+    assertSafeName(opts.field, "field");
+    return this.run({ queryType: "distribution", ...opts });
+  }
+  // ─── Sum ──────────────────────────────────────────────────────────────────
+  /**
+   * Sum a numeric field, optionally grouped by another field.
+   *
+   * @example
+   * ```ts
+   * // Total revenue
+   * const rows = await analytics.sum({ field: 'amount' });
+   * // → [{ sum: 198432.50 }]
+   *
+   * // Revenue by country
+   * const rows = await analytics.sum({ field: 'amount', groupBy: 'country', limit: 10 });
+   * // → [{ group: 'US', sum: 120000 }, { group: 'UK', sum: 45000 }, ...]
+   * ```
+   */
+  async sum(opts) {
+    assertSafeName(opts.field, "field");
+    if (opts.groupBy) assertSafeName(opts.groupBy, "groupBy");
+    return this.run({ queryType: "sum", ...opts });
+  }
+  // ─── Time Series ──────────────────────────────────────────────────────────
+  /**
+   * Count records created over time, grouped by a time granularity.
+   * Perfect for line charts and activity graphs.
+   *
+   * @example
+   * ```ts
+   * const rows = await analytics.timeSeries({
+   *   granularity: 'day',
+   *   dateRange: { start: Date.now() - 7 * 86400000, end: Date.now() },
+   * });
+   * // → [{ date: '2025-06-01', count: 42 }, { date: '2025-06-02', count: 67 }, ...]
+   * ```
+   */
+  async timeSeries(opts = {}) {
+    return this.run({ queryType: "timeSeries", granularity: "day", ...opts });
+  }
+  // ─── Field Time Series ────────────────────────────────────────────────────
+  /**
+   * Aggregate a numeric field over time (e.g. daily revenue, hourly signups).
+   *
+   * @example
+   * ```ts
+   * const rows = await analytics.fieldTimeSeries({
+   *   field: 'amount',
+   *   aggregation: 'sum',
+   *   granularity: 'week',
+   * });
+   * // → [{ date: '2025-W22', value: 14230.50 }, ...]
+   * ```
+   */
+  async fieldTimeSeries(opts) {
+    assertSafeName(opts.field, "field");
+    return this.run({
+      queryType: "fieldTimeSeries",
+      aggregation: "sum",
+      granularity: "day",
+      ...opts
+    });
+  }
+  // ─── Top N ────────────────────────────────────────────────────────────────
+  /**
+   * Get the top N values by frequency for a field.
+   * Optionally pair with a `labelField` for human-readable labels.
+   *
+   * @example
+   * ```ts
+   * // Top 5 most purchased products
+   * const rows = await analytics.topN({
+   *   field: 'productId',
+   *   labelField: 'productName',
+   *   n: 5,
+   * });
+   * // → [{ value: 'prod_123', label: 'Widget Pro', count: 892 }, ...]
+   * ```
+   */
+  async topN(opts) {
+    assertSafeName(opts.field, "field");
+    if (opts.labelField) assertSafeName(opts.labelField, "labelField");
+    return this.run({ queryType: "topN", n: 10, order: "desc", ...opts });
+  }
+  // ─── Field Stats ──────────────────────────────────────────────────────────
+  /**
+   * Get statistical summary (min, max, avg, sum, count, stddev) for a numeric field.
+   *
+   * @example
+   * ```ts
+   * const stats = await analytics.stats({ field: 'orderValue' });
+   * // → { min: 4.99, max: 9999.99, avg: 87.23, sum: 420948.27, count: 4823, stddev: 143.2 }
+   * ```
+   */
+  async stats(opts) {
+    assertSafeName(opts.field, "field");
+    return this.run({ queryType: "stats", ...opts });
+  }
+  // ─── Filtered Records ─────────────────────────────────────────────────────
+  /**
+   * Query raw records with filters, field selection, and pagination.
+   * This is the analytics version of `records.query()` but powered by BigQuery.
+   *
+   * @example
+   * ```ts
+   * const { records } = await analytics.records({
+   *   filters: [{ field: 'status', op: '==', value: 'refunded' }],
+   *   selectFields: ['orderId', 'amount', 'createdAt'],
+   *   limit: 50,
+   *   orderBy: 'amount',
+   *   order: 'desc',
+   * });
+   * ```
+   */
+  async records(opts = {}) {
+    if (opts.orderBy) assertSafeName(opts.orderBy, "orderBy");
+    if (opts.selectFields) opts.selectFields.forEach((f) => assertSafeName(f, "selectField"));
+    return this.run({ queryType: "records", limit: 100, order: "desc", ...opts });
+  }
+  // ─── Multi Metric ─────────────────────────────────────────────────────────
+  /**
+   * Calculate multiple aggregations in a single query.
+   * Ideal for dashboards that need several numbers at once.
+   *
+   * @example
+   * ```ts
+   * const result = await analytics.multiMetric({
+   *   metrics: [
+   *     { field: 'amount',   name: 'totalRevenue', aggregation: 'sum' },
+   *     { field: 'amount',   name: 'avgOrderValue', aggregation: 'avg' },
+   *     { field: 'userId',   name: 'uniqueCustomers', aggregation: 'count' },
+   *   ],
+   * });
+   * // → { totalRevenue: 198432.50, avgOrderValue: 87.23, uniqueCustomers: 2275 }
+   * ```
+   */
+  async multiMetric(opts) {
+    opts.metrics.forEach((m) => {
+      assertSafeName(m.field, "metric.field");
+      assertSafeName(m.name, "metric.name");
+    });
+    return this.run({ queryType: "multiMetric", ...opts });
+  }
+  // ─── Storage Stats ────────────────────────────────────────────────────────
+  /**
+   * Get storage statistics for this bucket: record counts, byte sizes.
+   *
+   * @example
+   * ```ts
+   * const stats = await analytics.storageStats();
+   * // → { totalRecords: 4821, totalBytes: 48293820, avgBytes: 10015, ... }
+   * ```
+   */
+  async storageStats(opts = {}) {
+    return this.run({ queryType: "storageStats", ...opts });
+  }
+  // ─── Cross-Bucket Comparison ──────────────────────────────────────────────
+  /**
+   * Compare the same field aggregation across multiple buckets in one query.
+   * Your security key must have read access to ALL listed buckets.
+   *
+   * @example
+   * ```ts
+   * const rows = await analytics.crossBucket({
+   *   bucketKeys: ['orders-us', 'orders-eu', 'orders-apac'],
+   *   field: 'amount',
+   *   aggregation: 'sum',
+   * });
+   * // → [
+   * //   { bucket: 'orders-us',   value: 120000 },
+   * //   { bucket: 'orders-eu',   value: 45000 },
+   * //   { bucket: 'orders-apac', value: 33000 },
+   * // ]
+   * ```
+   */
+  async crossBucket(opts) {
+    assertSafeName(opts.field, "field");
+    opts.bucketKeys.forEach((k) => assertSafeName(k, "bucketKey"));
+    return this.run({ queryType: "crossBucket", aggregation: "sum", ...opts });
+  }
+  // ─── Raw Query ────────────────────────────────────────────────────────────
+  /**
+   * Send a raw analytics query object. Use this when you need full control
+   * over the query shape or want to use a queryType not covered by the helpers.
+   *
+   * @example
+   * ```ts
+   * const result = await analytics.query({
+   *   queryType: 'topN',
+   *   field: 'category',
+   *   n: 3,
+   *   order: 'asc',
+   * });
+   * ```
+   */
+  async query(query) {
+    const data = await this.run(query);
+    return { queryType: query.queryType, data };
+  }
+};
+
+// src/storage/manager.ts
+var StorageManager = class {
+  constructor(http, storageKey) {
+    this.basePath = "/storage";
+    this.http = http;
+    this.storageKey = storageKey;
+  }
+  /** Headers for all storage requests — uses X-Storage-Key, not X-Api-Key. */
+  get authHeaders() {
+    return { "X-Storage-Key": this.storageKey };
+  }
+  // ─── Upload: Simple (server-buffered) ────────────────────────────────────
+  /**
+   * Upload a file to storage in one step (server-buffered, up to 500 MB).
+   * For files >10 MB or when you need upload progress, use `getUploadUrl()` instead.
+   *
+   * @param data     File data as a Blob, Buffer, Uint8Array, or ArrayBuffer.
+   * @param path     Destination path in your storage (e.g. `"avatars/alice.jpg"`).
+   * @param options  Upload options: isPublic, overwrite, mimeType.
+   *
+   * @example
+   * ```ts
+   * // Upload a public avatar
+   * const result = await storage.upload(file, 'avatars/alice.jpg', { isPublic: true });
+   * console.log(result.publicUrl); // → https://...
+   *
+   * // Upload a private document
+   * const result = await storage.upload(pdfBuffer, 'docs/contract.pdf');
+   * console.log(result.downloadUrl); // → /storage/download/docs/contract.pdf
+   * ```
+   */
+  async upload(data, path, options = {}) {
+    const { isPublic = false, overwrite = false, mimeType } = options;
+    const mime = mimeType ?? guessMimeType(path);
+    const formData = new FormData();
+    const blob = data instanceof Blob ? data : new Blob([data], { type: mime });
+    formData.append("file", blob, path.split("/").pop() ?? "file");
+    formData.append("path", path);
+    formData.append("mimeType", mime);
+    formData.append("isPublic", String(isPublic));
+    formData.append("overwrite", String(overwrite));
+    const result = await this.http.request(`${this.basePath}/upload`, {
+      method: "POST",
+      rawBody: formData,
+      headers: this.authHeaders
+    });
+    return {
+      path: result.path,
+      mimeType: result.mimeType,
+      size: result.size,
+      isPublic: result.isPublic,
+      publicUrl: result.publicUrl,
+      downloadUrl: result.downloadUrl
+    };
+  }
+  /**
+   * Upload raw JSON or plain text data as a file.
+   *
+   * @example
+   * ```ts
+   * const result = await storage.uploadRaw(
+   *   { config: { theme: 'dark' } },
+   *   'settings/user-config.json',
+   *   { isPublic: false },
+   * );
+   * ```
+   */
+  async uploadRaw(data, path, options = {}) {
+    const { isPublic = false, overwrite = false, mimeType = "application/json" } = options;
+    const body = typeof data === "string" ? data : JSON.stringify(data);
+    const result = await this.http.request(`${this.basePath}/upload-raw`, {
+      method: "POST",
+      body: { path, data: body, mimeType, isPublic, overwrite },
+      headers: this.authHeaders
+    });
+    return {
+      path: result.path,
+      mimeType: result.mimeType,
+      size: result.size,
+      isPublic: result.isPublic,
+      publicUrl: result.publicUrl,
+      downloadUrl: result.downloadUrl
+    };
+  }
+  // ─── Upload: Direct-to-GCS (recommended for large files) ─────────────────
+  /**
+   * Step 1 of the recommended upload flow.
+   * Get a signed URL to upload directly to GCS from the client (supports progress).
+   *
+   * @example
+   * ```ts
+   * const { uploadUrl, path: confirmedPath } = await storage.getUploadUrl({
+   *   path: 'videos/intro.mp4',
+   *   mimeType: 'video/mp4',
+   *   size: file.size,
+   *   isPublic: true,
+   * });
+   *
+   * // Upload using XHR for progress tracking
+   * await storage.uploadToSignedUrl(uploadUrl, file, 'video/mp4', (pct) => {
+   *   console.log(`${pct}% uploaded`);
+   * });
+   *
+   * // Step 3: confirm
+   * const result = await storage.confirmUpload({ path: confirmedPath, mimeType: 'video/mp4', isPublic: true });
+   * ```
+   */
+  async getUploadUrl(opts) {
+    const result = await this.http.request(`${this.basePath}/upload-url`, {
+      method: "POST",
+      body: { isPublic: false, overwrite: false, expiresInSeconds: 900, ...opts },
+      headers: this.authHeaders
+    });
+    return result;
+  }
+  /**
+   * Upload data directly to a signed GCS URL (no auth headers needed).
+   * Optionally tracks progress via a callback.
+   *
+   * @param signedUrl  The URL returned by `getUploadUrl()`.
+   * @param data       File data.
+   * @param mimeType   Must match what was used in `getUploadUrl()`.
+   * @param onProgress Optional callback called with 0–100 progress percentage.
+   */
+  async uploadToSignedUrl(signedUrl, data, mimeType, onProgress) {
+    await this.http.putToSignedUrl(signedUrl, data, mimeType, onProgress);
+  }
+  /**
+   * Step 3 of the recommended upload flow.
+   * Confirm a direct upload and register metadata on the server.
+   *
+   * @example
+   * ```ts
+   * const result = await storage.confirmUpload({
+   *   path: 'videos/intro.mp4',
+   *   mimeType: 'video/mp4',
+   *   isPublic: true,
+   * });
+   * console.log(result.publicUrl);
+   * ```
+   */
+  async confirmUpload(opts) {
+    const result = await this.http.request(`${this.basePath}/confirm`, {
+      method: "POST",
+      body: { isPublic: false, ...opts },
+      headers: this.authHeaders
+    });
+    return {
+      path: result.path,
+      mimeType: result.mimeType,
+      size: result.size,
+      isPublic: result.isPublic,
+      publicUrl: result.publicUrl,
+      downloadUrl: result.downloadUrl
+    };
+  }
+  // ─── Batch Upload ─────────────────────────────────────────────────────────
+  /**
+   * Get signed upload URLs for multiple files at once.
+   *
+   * @example
+   * ```ts
+   * const { files } = await storage.getBatchUploadUrls([
+   *   { path: 'images/photo1.jpg', mimeType: 'image/jpeg', size: 204800 },
+   *   { path: 'images/photo2.jpg', mimeType: 'image/jpeg', size: 153600 },
+   * ]);
+   *
+   * // Upload each file and confirm
+   * for (const f of files) {
+   *   await storage.uploadToSignedUrl(f.uploadUrl, blobs[f.index], f.mimeType);
+   *   await storage.confirmUpload({ path: f.path, mimeType: f.mimeType });
+   * }
+   * ```
+   */
+  async getBatchUploadUrls(files) {
+    const result = await this.http.request(
+      `${this.basePath}/batch-upload-urls`,
+      { method: "POST", body: { files }, headers: this.authHeaders }
+    );
+    return { files: result.files };
+  }
+  /**
+   * Confirm multiple direct uploads at once.
+   */
+  async batchConfirmUploads(items) {
+    const result = await this.http.request(
+      `${this.basePath}/batch-confirm`,
+      { method: "POST", body: { files: items }, headers: this.authHeaders }
+    );
+    return result.files.map((r) => ({
+      path: r.path,
+      mimeType: r.mimeType,
+      size: r.size,
+      isPublic: r.isPublic,
+      publicUrl: r.publicUrl,
+      downloadUrl: r.downloadUrl
+    }));
+  }
+  // ─── Download ─────────────────────────────────────────────────────────────
+  /**
+   * Download a private file as an ArrayBuffer.
+   * For public files, use the `publicUrl` directly — no SDK needed.
+   *
+   * @example
+   * ```ts
+   * const buffer = await storage.download('docs/contract.pdf');
+   * const blob = new Blob([buffer], { type: 'application/pdf' });
+   * // Open in browser:
+   * window.open(URL.createObjectURL(blob));
+   * ```
+   */
+  async download(path) {
+    const encoded = path.split("/").map(encodeURIComponent).join("/");
+    return this.http.request(`${this.basePath}/download/${encoded}`, {
+      method: "GET",
+      headers: this.authHeaders
+    });
+  }
+  /**
+   * Download multiple files at once, returned as a JSON map of `{ path: base64 }`.
+   *
+   * @example
+   * ```ts
+   * const files = await storage.batchDownload(['docs/a.pdf', 'docs/b.pdf']);
+   * ```
+   */
+  async batchDownload(paths) {
+    const result = await this.http.request(
+      `${this.basePath}/batch-download`,
+      { method: "POST", body: { paths }, headers: this.authHeaders }
+    );
+    return result.files;
+  }
+  // ─── List ─────────────────────────────────────────────────────────────────
+  /**
+   * List files and folders at a given path prefix.
+   *
+   * @example
+   * ```ts
+   * // List everything in the root
+   * const { files, folders } = await storage.list();
+   *
+   * // List a specific folder
+   * const { files, folders, hasMore, nextCursor } = await storage.list({
+   *   prefix: 'avatars/',
+   *   limit: 20,
+   * });
+   *
+   * // Next page
+   * const page2 = await storage.list({ prefix: 'avatars/', cursor: nextCursor });
+   * ```
+   */
+  async list(opts = {}) {
+    const params = new URLSearchParams();
+    if (opts.prefix) params.set("prefix", opts.prefix);
+    if (opts.limit) params.set("limit", String(opts.limit));
+    if (opts.cursor) params.set("cursor", opts.cursor);
+    if (opts.recursive) params.set("recursive", "true");
+    const qs = params.toString() ? `?${params}` : "";
+    const result = await this.http.request(`${this.basePath}/list${qs}`, {
+      method: "GET",
+      headers: this.authHeaders
+    });
+    return {
+      files: result.files,
+      folders: result.folders,
+      hasMore: result.hasMore,
+      nextCursor: result.nextCursor
+    };
+  }
+  // ─── Metadata ─────────────────────────────────────────────────────────────
+  /**
+   * Get metadata for a file (size, MIME type, visibility, URLs).
+   *
+   * @example
+   * ```ts
+   * const meta = await storage.getMetadata('avatars/alice.jpg');
+   * console.log(meta.size, meta.isPublic, meta.publicUrl);
+   * ```
+   */
+  async getMetadata(path) {
+    const encoded = path.split("/").map(encodeURIComponent).join("/");
+    const result = await this.http.request(
+      `${this.basePath}/metadata/${encoded}`,
+      { method: "GET", headers: this.authHeaders }
+    );
+    return {
+      path: result.path,
+      size: result.size,
+      mimeType: result.mimeType,
+      isPublic: result.isPublic,
+      publicUrl: result.publicUrl,
+      downloadUrl: result.downloadUrl,
+      createdAt: result.createdAt,
+      updatedAt: result.updatedAt
+    };
+  }
+  // ─── Signed URL (time-limited share) ─────────────────────────────────────
+  /**
+   * Generate a time-limited download URL for a private file.
+   * The URL can be shared externally without requiring an `X-Storage-Key`.
+   *
+   * > **Note:** Downloads via signed URLs bypass the server, so download stats
+   * > are NOT tracked. Use `downloadUrl` for tracked downloads.
+   *
+   * @param path       Path to the file.
+   * @param expiresIn  URL lifetime in seconds (default 3600 = 1 hour).
+   *
+   * @example
+   * ```ts
+   * const { signedUrl, expiresAt } = await storage.getSignedUrl('docs/invoice.pdf', 1800);
+   * // Share signedUrl with the recipient — it expires in 30 minutes.
+   * ```
+   */
+  async getSignedUrl(path, expiresIn = 3600) {
+    const result = await this.http.request(`${this.basePath}/signed-url`, {
+      method: "POST",
+      body: { path, expiresIn },
+      headers: this.authHeaders
+    });
+    return {
+      signedUrl: result.signedUrl,
+      expiresAt: result.expiresAt,
+      expiresIn: result.expiresIn,
+      path: result.path
+    };
+  }
+  // ─── Visibility ───────────────────────────────────────────────────────────
+  /**
+   * Change a file's visibility between public and private after upload.
+   *
+   * @example
+   * ```ts
+   * // Make a file public
+   * const result = await storage.setVisibility('avatars/alice.jpg', true);
+   * console.log(result.publicUrl); // CDN URL
+   *
+   * // Make a file private
+   * const result = await storage.setVisibility('avatars/alice.jpg', false);
+   * console.log(result.downloadUrl); // Auth-required URL
+   * ```
+   */
+  async setVisibility(path, isPublic) {
+    const result = await this.http.request(`${this.basePath}/visibility`, {
+      method: "PATCH",
+      body: { path, isPublic },
+      headers: this.authHeaders
+    });
+    return {
+      path: result.path,
+      isPublic: result.isPublic,
+      publicUrl: result.publicUrl,
+      downloadUrl: result.downloadUrl
+    };
+  }
+  // ─── Folder Operations ────────────────────────────────────────────────────
+  /**
+   * Create a folder (a GCS prefix placeholder).
+   *
+   * @example
+   * ```ts
+   * await storage.createFolder('uploads/2025/');
+   * ```
+   */
+  async createFolder(path) {
+    const result = await this.http.request(
+      `${this.basePath}/folder`,
+      { method: "POST", body: { path }, headers: this.authHeaders }
+    );
+    return { path: result.path };
+  }
+  // ─── File Operations ──────────────────────────────────────────────────────
+  /**
+   * Delete a single file.
+   *
+   * @example
+   * ```ts
+   * await storage.deleteFile('avatars/old-avatar.jpg');
+   * ```
+   */
+  async deleteFile(path) {
+    await this.http.request(`${this.basePath}/file`, {
+      method: "DELETE",
+      body: { path },
+      headers: this.authHeaders
+    });
+  }
+  /**
+   * Delete a folder and all its contents recursively.
+   *
+   * @example
+   * ```ts
+   * await storage.deleteFolder('temp/');
+   * ```
+   */
+  async deleteFolder(path) {
+    await this.http.request(`${this.basePath}/folder`, {
+      method: "DELETE",
+      body: { path },
+      headers: this.authHeaders
+    });
+  }
+  /**
+   * Move or rename a file.
+   *
+   * @example
+   * ```ts
+   * // Rename
+   * await storage.move('docs/draft.pdf', 'docs/final.pdf');
+   * // Move to a different folder
+   * await storage.move('inbox/report.xlsx', 'archive/2025/report.xlsx');
+   * ```
+   */
+  async move(from, to) {
+    const result = await this.http.request(
+      `${this.basePath}/move`,
+      { method: "POST", body: { from, to }, headers: this.authHeaders }
+    );
+    return { from: result.from, to: result.to };
+  }
+  /**
+   * Copy a file to a new path.
+   *
+   * @example
+   * ```ts
+   * await storage.copy('templates/base.html', 'sites/my-site/index.html');
+   * ```
+   */
+  async copy(from, to) {
+    const result = await this.http.request(
+      `${this.basePath}/copy`,
+      { method: "POST", body: { from, to }, headers: this.authHeaders }
+    );
+    return { from: result.from, to: result.to };
+  }
+  // ─── Stats ────────────────────────────────────────────────────────────────
+  /**
+   * Get storage statistics for your key: total files, bytes, operation counts.
+   *
+   * @example
+   * ```ts
+   * const stats = await storage.getStats();
+   * console.log(`${stats.totalFiles} files, ${(stats.totalBytes / 1e6).toFixed(1)} MB`);
+   * ```
+   */
+  async getStats() {
+    const result = await this.http.request(`${this.basePath}/stats`, {
+      method: "GET",
+      headers: this.authHeaders
+    });
+    return result.stats;
+  }
+  // ─── Info (no auth) ───────────────────────────────────────────────────────
+  /**
+   * Ping the storage service. No authentication required.
+   *
+   * @example
+   * ```ts
+   * const info = await storage.info();
+   * // → { ok: true, storageRoot: 'hydrous-storage' }
+   * ```
+   */
+  async info() {
+    return this.http.get(`${this.basePath}/info`);
+  }
+};
+
+// src/storage/scoped.ts
+var ScopedStorage = class _ScopedStorage {
+  constructor(manager, prefix) {
+    this.manager = manager;
+    this.prefix = prefix.replace(/\/+$/, "") + "/";
+  }
+  scopedPath(userPath) {
+    return `${this.prefix}${userPath.replace(/^\/+/, "")}`;
+  }
+  /** Upload a file within the scoped folder. */
+  upload(data, path, options) {
+    return this.manager.upload(data, this.scopedPath(path), options);
+  }
+  /** Upload raw JSON or text within the scoped folder. */
+  uploadRaw(data, path, options) {
+    return this.manager.uploadRaw(data, this.scopedPath(path), options);
+  }
+  /** Get a signed upload URL for a file within the scoped folder. */
+  getUploadUrl(opts) {
+    return this.manager.getUploadUrl({ ...opts, path: this.scopedPath(opts.path) });
+  }
+  /** Upload data directly to a signed GCS URL with optional progress tracking. */
+  uploadToSignedUrl(signedUrl, data, mimeType, onProgress) {
+    return this.manager.uploadToSignedUrl(signedUrl, data, mimeType, onProgress);
+  }
+  /** Confirm a direct upload within the scoped folder. */
+  confirmUpload(opts) {
+    return this.manager.confirmUpload({ ...opts, path: this.scopedPath(opts.path) });
+  }
+  /** Download a file within the scoped folder. */
+  download(path) {
+    return this.manager.download(this.scopedPath(path));
+  }
+  /** List files within the scoped folder. */
+  list(opts = {}) {
+    return this.manager.list({ ...opts, prefix: this.scopedPath(opts.prefix ?? "") });
+  }
+  /** Get metadata for a file within the scoped folder. */
+  getMetadata(path) {
+    return this.manager.getMetadata(this.scopedPath(path));
+  }
+  /** Get a time-limited signed URL for a file within the scoped folder. */
+  getSignedUrl(path, expiresIn) {
+    return this.manager.getSignedUrl(this.scopedPath(path), expiresIn);
+  }
+  /** Change visibility of a file within the scoped folder. */
+  setVisibility(path, isPublic) {
+    return this.manager.setVisibility(this.scopedPath(path), isPublic);
+  }
+  /** Delete a file within the scoped folder. */
+  deleteFile(path) {
+    return this.manager.deleteFile(this.scopedPath(path));
+  }
+  /** Delete a sub-folder within the scoped folder. */
+  deleteFolder(path) {
+    return this.manager.deleteFolder(this.scopedPath(path));
+  }
+  /** Move a file within the scoped folder. */
+  move(from, to) {
+    return this.manager.move(this.scopedPath(from), this.scopedPath(to));
+  }
+  /** Copy a file within the scoped folder. */
+  copy(from, to) {
+    return this.manager.copy(this.scopedPath(from), this.scopedPath(to));
+  }
+  /** Create a sub-folder within the scoped folder. */
+  createFolder(path) {
+    return this.manager.createFolder(this.scopedPath(path));
+  }
+  /**
+   * Create a further-scoped instance nested within this scope.
+   *
+   * @example
+   * ```ts
+   * const uploads = db.storage.scope('user-uploads');
+   * const images  = uploads.scope('images'); // → "user-uploads/images/"
+   * ```
+   */
+  scope(subPrefix) {
+    return new _ScopedStorage(this.manager, this.scopedPath(subPrefix));
+  }
+};
+
+// src/client.ts
+var HydrousClient = class {
+  constructor(config) {
+    this._storage = null;
+    this._recordsCache = /* @__PURE__ */ new Map();
+    this._authCache = /* @__PURE__ */ new Map();
+    this._analyticsCache = /* @__PURE__ */ new Map();
+    if (!config.securityKey) {
+      throw new Error(
+        "[HydrousDB] securityKey is required. Get yours from https://hydrousdb.com/dashboard."
+      );
+    }
+    const baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
+    this.http = new HttpClient(baseUrl, config.securityKey);
+    this._storageKey = config.securityKey;
+  }
+  // ─── Records ─────────────────────────────────────────────────────────────
+  /**
+   * Get a typed records client for the given bucket.
+   *
+   * The generic type parameter `T` describes the shape of records in this
+   * bucket. Leave it unset for a generic `Record<string, unknown>` shape.
+   *
+   * @param bucketKey  The name of your bucket (must match what you created in the dashboard).
+   *
+   * @example
+   * ```ts
+   * interface Post { title: string; body: string; published: boolean }
+   * const posts = db.records<Post>('blog-posts');
+   *
+   * const post = await posts.create({ title: 'Hello', body: '...', published: false });
+   * // post.id, post.createdAt, post.updatedAt are added automatically
+   * ```
+   */
+  records(bucketKey) {
+    if (!this._recordsCache.has(bucketKey)) {
+      this._recordsCache.set(bucketKey, new RecordsClient(this.http, bucketKey));
+    }
+    return this._recordsCache.get(bucketKey);
+  }
+  // ─── Auth ─────────────────────────────────────────────────────────────────
+  /**
+   * Get an auth client for the given user bucket.
+   *
+   * @param bucketKey  The name of your user bucket (e.g. `"app-users"`).
+   *
+   * @example
+   * ```ts
+   * const auth = db.auth('app-users');
+   * const { user, session } = await auth.login({ email: '...', password: '...' });
+   * ```
+   */
+  auth(bucketKey) {
+    if (!this._authCache.has(bucketKey)) {
+      this._authCache.set(bucketKey, new AuthClient(this.http, bucketKey));
+    }
+    return this._authCache.get(bucketKey);
+  }
+  // ─── Analytics ────────────────────────────────────────────────────────────
+  /**
+   * Get an analytics client for the given bucket.
+   *
+   * @param bucketKey  The name of the bucket to analyse.
+   *
+   * @example
+   * ```ts
+   * const analytics = db.analytics('orders');
+   * const { count } = await analytics.count();
+   * ```
+   */
+  analytics(bucketKey) {
+    if (!this._analyticsCache.has(bucketKey)) {
+      this._analyticsCache.set(bucketKey, new AnalyticsClient(this.http, bucketKey));
+    }
+    return this._analyticsCache.get(bucketKey);
+  }
+  // ─── Storage ──────────────────────────────────────────────────────────────
+  /**
+   * The storage manager for uploading, downloading, listing, and managing files.
+   *
+   * Scoped to your project — you can never access another project's files.
+   *
+   * @example
+   * ```ts
+   * // Upload a file
+   * const result = await db.storage.upload(file, 'images/photo.jpg', { isPublic: true });
+   *
+   * // Scope to a folder
+   * const avatars = db.storage.scope('user-avatars');
+   * await avatars.upload(blob, `${userId}.jpg`, { isPublic: true });
+   * ```
+   */
+  get storage() {
+    if (!this._storage) {
+      this._storage = new StorageManager(this.http, this._storageKey);
+    }
+    const mgr = this._storage;
+    const extended = mgr;
+    if (!extended.scope) {
+      extended.scope = (prefix) => new ScopedStorage(mgr, prefix);
+    }
+    return extended;
+  }
+};
 function createClient(config) {
   return new HydrousClient(config);
 }
 
-exports.AnalyticsClient = AnalyticsClient;
-exports.AuthClient = AuthClient;
-exports.HydrousClient = HydrousClient;
-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;
+export { AnalyticsClient, AnalyticsError, AuthClient, AuthError, HydrousClient, HydrousError, NetworkError, RecordError, RecordsClient, ScopedStorage, StorageError, StorageManager, ValidationError, createClient };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map