hydrousdb 3.0.1 → 3.2.0

package/dist/index.cjs

@@ -49,7 +49,7 @@ var NetworkError = class extends HydrousError {
   constructor(message, cause) {
     super(message, "NETWORK_ERROR");
     this.name = "NetworkError";
-    if (cause) this.cause = cause;
+    if (cause !== void 0) this.cause = cause;
   }
 };
 
@@ -59,42 +59,23 @@ var HttpClient = class {
   constructor(baseUrl) {
     this.baseUrl = baseUrl.replace(/\/$/, "");
   }
-  async request(path, apiKeyOrOpts, opts = {}) {
-    let apiKey;
-    let resolvedOpts;
-    if (typeof apiKeyOrOpts === "string") {
-      apiKey = apiKeyOrOpts;
-      resolvedOpts = opts;
-    } else {
-      apiKey = void 0;
-      resolvedOpts = apiKeyOrOpts ?? opts;
-    }
-    const {
-      method = "GET",
-      body,
-      headers = {},
-      rawBody,
-      contentType = "application/json"
-    } = resolvedOpts;
+  // ─── Core request method ──────────────────────────────────────────────────
+  async request(path, options) {
     const url = `${this.baseUrl}${path}`;
-    const reqHeaders = {
-      ...apiKey ? { "X-Api-Key": apiKey } : {},
-      ...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";
+    const headers = { ...options.headers };
+    let body;
+    if (options.rawBody !== void 0) {
+      body = options.rawBody;
+    } else if (options.body !== void 0) {
+      headers["Content-Type"] = "application/json";
+      body = JSON.stringify(options.body);
     }
     let response;
     try {
       response = await fetch(url, {
-        method,
-        headers: reqHeaders,
-        body: reqBody
+        method: options.method,
+        headers,
+        body
       });
     } catch (err) {
       throw new NetworkError(
@@ -102,87 +83,100 @@ var HttpClient = class {
         err
       );
     }
-    const ct = response.headers.get("content-type") ?? "";
-    if (!ct.includes("application/json")) {
+    const contentType = response.headers.get("content-type") ?? "";
+    if (!contentType.includes("application/json")) {
       if (!response.ok) {
         throw new HydrousError(
           `Request failed with status ${response.status}`,
-          `HTTP_${response.status}`,
+          "REQUEST_FAILED",
           response.status
         );
       }
-      const buffer = await response.arrayBuffer();
-      return buffer;
+      return response.arrayBuffer();
     }
-    let responseData;
+    let data;
     try {
-      responseData = await response.json();
+      data = await response.json();
     } catch {
       throw new HydrousError(
-        "Failed to parse server response as JSON",
+        `Failed to parse response JSON`,
         "PARSE_ERROR",
         response.status
       );
     }
     if (!response.ok) {
-      const errData = responseData;
       throw new HydrousError(
-        errData["error"] ?? `Request failed with status ${response.status}`,
-        errData["code"] ?? `HTTP_${response.status}`,
+        data["error"] || data["message"] || `Request failed with status ${response.status}`,
+        data["code"] || "REQUEST_FAILED",
         response.status,
-        errData["requestId"],
-        errData["details"]
+        data["requestId"],
+        data["details"]
       );
     }
-    return responseData;
+    return data;
   }
-  get(path, apiKey, headers) {
-    return this.request(path, apiKey, { method: "GET", headers });
+  // ─── Convenience wrappers ─────────────────────────────────────────────────
+  get(path, apiKey, extraHeaders) {
+    return this.request(path, {
+      method: "GET",
+      headers: apiKey ? { "X-Api-Key": apiKey, ...extraHeaders } : { ...extraHeaders }
+    });
   }
-  post(path, apiKey, body, headers) {
-    return this.request(path, apiKey, { method: "POST", body, headers });
+  post(path, apiKey, body) {
+    return this.request(path, {
+      method: "POST",
+      body,
+      headers: { "X-Api-Key": apiKey }
+    });
   }
-  put(path, apiKey, body, headers) {
-    return this.request(path, apiKey, { method: "PUT", body, headers });
+  put(path, apiKey, body) {
+    return this.request(path, {
+      method: "PUT",
+      body,
+      headers: { "X-Api-Key": apiKey }
+    });
   }
-  patch(path, apiKey, body, headers) {
-    return this.request(path, apiKey, { method: "PATCH", body, headers });
+  patch(path, apiKey, body) {
+    return this.request(path, {
+      method: "PATCH",
+      body,
+      headers: { "X-Api-Key": apiKey }
+    });
   }
-  delete(path, apiKey, body, headers) {
-    return this.request(path, apiKey, { method: "DELETE", body, headers });
+  delete(path, apiKey, body) {
+    return this.request(path, {
+      method: "DELETE",
+      body,
+      headers: { "X-Api-Key": apiKey }
+    });
   }
+  /**
+   * Upload directly to a signed GCS URL (no auth headers — signed URL is self-authenticating).
+   * Supports optional progress tracking via XHR in browser environments.
+   */
   async putToSignedUrl(signedUrl, data, mimeType, onProgress) {
-    const XHR = typeof globalThis["XMLHttpRequest"] !== "undefined" ? globalThis["XMLHttpRequest"] : void 0;
-    if (XHR && onProgress) {
-      return new Promise((resolve, reject) => {
-        const xhr = new XHR();
+    const body = data instanceof Blob ? data : data instanceof Uint8Array ? data.buffer : data;
+    if (typeof XMLHttpRequest !== "undefined" && typeof onProgress === "function") {
+      await new Promise((resolve, reject) => {
+        const xhr = new XMLHttpRequest();
         xhr.upload.onprogress = (e) => {
-          if (e.lengthComputable) {
-            onProgress(Math.round(e.loaded / e.total * 100));
-          }
+          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.onload = () => xhr.status >= 200 && xhr.status < 300 ? resolve() : reject(new Error(`GCS upload failed: ${xhr.status}`));
+        xhr.onerror = () => reject(new Error("GCS 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);
+        xhr.send(body);
       });
-    }
-    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}`);
+    } else {
+      const res = await fetch(signedUrl, {
+        method: "PUT",
+        headers: { "Content-Type": mimeType },
+        body
+      });
+      if (!res.ok) {
+        throw new HydrousError(`GCS upload failed: ${res.status}`, "GCS_UPLOAD_FAILED", res.status);
+      }
     }
   }
 };
@@ -197,8 +191,9 @@ var AuthClient = class {
   post(path, body) {
     return this.http.post(path, this.authKey, body);
   }
-  get(path) {
-    return this.http.get(path, this.authKey);
+  get(path, query) {
+    const qs = query && Object.keys(query).length ? "?" + new URLSearchParams(query).toString() : "";
+    return this.http.get(`${path}${qs}`, this.authKey);
   }
   patch(path, body) {
     return this.http.patch(path, this.authKey, body);
@@ -207,57 +202,136 @@ var AuthClient = class {
     return this.http.delete(path, this.authKey, body);
   }
   // ─── Registration & Login ─────────────────────────────────────────────────
+  // Server: POST /auth/:bucket/signup  → { user, session }
+  // Server: POST /auth/:bucket/signin  → { user, session }
+  // Server: POST /auth/:bucket/signout → { success, message }
   async signup(options) {
     const result = await this.post(`${this.basePath}/signup`, options);
-    return { user: result.user, session: result.session };
+    const user = result.user ?? result.data;
+    return {
+      user,
+      session: {
+        sessionId: result.session.sessionId,
+        userId: user.id,
+        bucketId: this.basePath.split("/")[2],
+        createdAt: Date.now(),
+        expiresAt: result.session.expiresAt,
+        refreshToken: result.session.refreshToken,
+        refreshExpiresAt: result.session.expiresAt
+      }
+    };
   }
   async login(options) {
-    const result = await this.post(`${this.basePath}/login`, options);
-    return { user: result.user, session: result.session };
+    const result = await this.post(`${this.basePath}/signin`, options);
+    const user = result.user ?? result.data;
+    return {
+      user,
+      session: {
+        sessionId: result.session.sessionId,
+        userId: user.id,
+        bucketId: this.basePath.split("/")[2],
+        createdAt: Date.now(),
+        expiresAt: result.session.expiresAt,
+        refreshToken: result.session.refreshToken,
+        refreshExpiresAt: result.session.expiresAt
+      }
+    };
   }
-  async logout({ sessionId }) {
-    await this.post(`${this.basePath}/logout`, { sessionId });
+  async logout(options) {
+    await this.post(`${this.basePath}/signout`, options);
   }
   async refreshSession({ refreshToken }) {
-    const result = await this.post(`${this.basePath}/session/refresh`, { refreshToken });
-    return result.session;
+    const result = await this.post(
+      `${this.basePath}/session/refresh`,
+      { refreshToken }
+    );
+    const s = result.session;
+    return {
+      sessionId: s.sessionId,
+      userId: result.data?.id ?? "",
+      bucketId: this.basePath.split("/")[2],
+      createdAt: Date.now(),
+      expiresAt: s.expiresAt,
+      refreshToken: s.refreshToken,
+      refreshExpiresAt: s.expiresAt
+    };
+  }
+  async validateSession({ sessionId }) {
+    const result = await this.post(
+      `${this.basePath}/session/validate`,
+      { sessionId }
+    );
+    return { user: result.data, session: result.session };
   }
   // ─── User Profile ─────────────────────────────────────────────────────────
+  // Server: GET  /auth/:bucket/user?userId=...    → { success, data: UserRecord }
+  // Server: PATCH /auth/:bucket/user  body: { sessionId, userId, updates: {...} }
+  // Server: DELETE /auth/:bucket/user?userId=...  header/body: sessionId
   async getUser({ userId }) {
-    const result = await this.get(`${this.basePath}/user/${userId}`);
-    return result.user;
+    const result = await this.get(`${this.basePath}/user`, { userId });
+    return result.data;
   }
   async updateUser(options) {
-    const { sessionId, userId, data } = options;
-    const result = await this.patch(`${this.basePath}/user`, { sessionId, userId, ...data });
-    return result.user;
+    const { sessionId, userId, updates } = options;
+    const result = await this.patch(
+      `${this.basePath}/user`,
+      { sessionId, userId, updates }
+    );
+    return result.data;
   }
   async deleteUser({ sessionId, userId }) {
-    await this.delete(`${this.basePath}/user`, { sessionId, userId });
+    await this.http.request(`${this.basePath}/user?userId=${encodeURIComponent(userId)}`, {
+      method: "DELETE",
+      body: { sessionId },
+      headers: { "X-Api-Key": this.authKey }
+    });
   }
   // ─── Admin Operations ─────────────────────────────────────────────────────
+  // Server: GET  /auth/:bucket/users?limit=&cursor=   → { data: UserRecord[], meta: { hasMore, nextCursor } }
+  // Server: DELETE /auth/:bucket/users/bulk  body: { userIds, hard?, sessionId }
+  // Server: DELETE /auth/:bucket/user/hard?userId=... body: { sessionId }
   async listUsers(options) {
-    const { sessionId, limit = 50, offset = 0 } = options;
-    const result = await this.post(
-      `${this.basePath}/users/list`,
-      { sessionId, limit, offset }
+    const { sessionId, limit = 50, cursor } = options;
+    const params = { limit: String(limit) };
+    if (cursor) params["cursor"] = cursor;
+    const result = await this.http.request(
+      `${this.basePath}/users?${new URLSearchParams(params)}`,
+      {
+        method: "GET",
+        headers: { "X-Api-Key": this.authKey, "X-Session-Id": sessionId }
+      }
     );
-    return { users: result.users, total: result.total, limit: result.limit, offset: result.offset };
+    return {
+      users: result.data ?? result.users ?? [],
+      hasMore: result.meta?.hasMore ?? result.hasMore ?? false,
+      nextCursor: result.meta?.nextCursor ?? result.nextCursor ?? null
+    };
   }
   async hardDeleteUser({ sessionId, userId }) {
-    await this.delete(`${this.basePath}/user/hard`, { sessionId, userId });
+    await this.http.request(
+      `${this.basePath}/user/hard?userId=${encodeURIComponent(userId)}`,
+      {
+        method: "DELETE",
+        body: { sessionId },
+        headers: { "X-Api-Key": this.authKey }
+      }
+    );
   }
-  async bulkDeleteUsers({ sessionId, userIds }) {
-    const result = await this.post(
-      `${this.basePath}/users/bulk-delete`,
-      { sessionId, userIds }
+  async bulkDeleteUsers(options) {
+    const result = await this.http.request(
+      `${this.basePath}/users/bulk`,
+      {
+        method: "DELETE",
+        body: { userIds: options.userIds, hard: options.hard ?? false, sessionId: options.sessionId },
+        headers: { "X-Api-Key": this.authKey }
+      }
     );
-    return { deleted: result.deleted, failed: result.failed };
+    return { succeeded: result.meta.succeeded, failed: result.meta.failed };
   }
-  async lockAccount({ sessionId, userId, duration }) {
+  async lockAccount(options) {
     const result = await this.post(
       `${this.basePath}/account/lock`,
-      { sessionId, userId, duration }
+      options
     );
     return result.data;
   }
@@ -265,8 +339,17 @@ var AuthClient = class {
     await this.post(`${this.basePath}/account/unlock`, { sessionId, userId });
   }
   // ─── Password Management ──────────────────────────────────────────────────
+  // Server: POST /auth/:bucket/password/change        body: { sessionId, userId, oldPassword, newPassword }
+  // Server: POST /auth/:bucket/password/reset/request body: { email }
+  // Server: POST /auth/:bucket/password/reset/confirm body: { resetToken, newPassword }
   async changePassword(options) {
-    await this.post(`${this.basePath}/password/change`, options);
+    const { sessionId, userId, currentPassword, newPassword } = options;
+    await this.post(`${this.basePath}/password/change`, {
+      sessionId,
+      userId,
+      oldPassword: currentPassword,
+      newPassword
+    });
   }
   async requestPasswordReset({ email }) {
     await this.post(`${this.basePath}/password/reset/request`, { email });
@@ -275,6 +358,8 @@ var AuthClient = class {
     await this.post(`${this.basePath}/password/reset/confirm`, { resetToken, newPassword });
   }
   // ─── Email Verification ───────────────────────────────────────────────────
+  // Server: POST /auth/:bucket/email/verify/request  body: { userId }
+  // Server: POST /auth/:bucket/email/verify/confirm  body: { verifyToken }
   async requestEmailVerification({ userId }) {
     await this.post(`${this.basePath}/email/verify/request`, { userId });
   }
@@ -298,9 +383,8 @@ function buildQueryParams(options = {}) {
     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) {
+  if (options.filters && options.filters.length > 0)
     params.set("filters", JSON.stringify(options.filters));
-  }
   const str = params.toString();
   return str ? `?${str}` : "";
 }
@@ -343,89 +427,179 @@ var RecordsClient = class {
     assertSafeName(bucketKey, "bucketKey");
     this.http = http;
     this.bucketKey = bucketKey;
-    this.bucketKey_ = bucketSecurityKey;
+    this.apiKey = bucketSecurityKey;
     this.basePath = `/records/${bucketKey}`;
   }
-  get key() {
-    return this.bucketKey_;
-  }
   // ─── Single Record Operations ─────────────────────────────────────────────
-  async create(data) {
-    const result = await this.http.post(this.basePath, this.key, data);
-    return result.record ?? result.data;
+  /**
+   * Create a new record.
+   *
+   * @param data    The record fields to store.
+   * @param options Optional: queryableFields (for server-side filtering),
+   *                userEmail (audit trail), customRecordId (upsert by ID).
+   *
+   * @example
+   * ```ts
+   * const post = await posts.create(
+   *   { title: 'Hello', status: 'draft', authorId: 'u1' },
+   *   { queryableFields: ['status', 'authorId'], userEmail: 'alice@example.com' },
+   * );
+   * ```
+   */
+  async create(data, options = {}) {
+    const { queryableFields, userEmail, customRecordId } = options;
+    const body = { values: data };
+    if (queryableFields?.length) body["queryableFields"] = queryableFields;
+    if (userEmail) body["userEmail"] = userEmail;
+    if (customRecordId) body["customRecordId"] = customRecordId;
+    const result = await this.http.post(this.basePath, this.apiKey, body);
+    return result.data ?? result.record;
   }
+  /**
+   * Get a single record by ID.
+   */
   async get(id) {
-    const result = await this.http.get(`${this.basePath}/${id}`, this.key);
-    return result.record ?? result.data;
+    const result = await this.http.get(
+      `${this.basePath}/${encodeURIComponent(id)}`,
+      this.apiKey
+    );
+    return result.data ?? result.record;
   }
+  /**
+   * Fully replace a record (PUT semantics).
+   */
   async set(id, data) {
-    const result = await this.http.put(`${this.basePath}/${id}`, this.key, data);
-    return result.record ?? result.data;
+    const result = await this.http.put(
+      `${this.basePath}/${encodeURIComponent(id)}`,
+      this.apiKey,
+      data
+    );
+    return result.data ?? result.record;
   }
+  /**
+   * Partially update a record (PATCH semantics).
+   * By default merges with existing fields; set `merge: false` to replace.
+   * Supports write-filter sentinels: `{ __op: 'increment', delta: 1 }` etc.
+   */
   async patch(id, data, options = {}) {
     const { merge = true } = options;
     const result = await this.http.patch(
-      `${this.basePath}/${id}`,
-      this.key,
+      `${this.basePath}/${encodeURIComponent(id)}`,
+      this.apiKey,
       { ...data, _merge: merge }
     );
-    return result.record ?? result.data;
+    return result.data ?? result.record;
   }
+  /**
+   * Delete a record permanently.
+   */
   async delete(id) {
-    await this.http.delete(`${this.basePath}/${id}`, this.key);
+    await this.http.delete(
+      `${this.basePath}/${encodeURIComponent(id)}`,
+      this.apiKey
+    );
   }
   // ─── Batch Operations ─────────────────────────────────────────────────────
-  async batchCreate(items) {
+  /**
+   * Create multiple records in one request (max 500).
+   * Each record can include a `_customRecordId` field for upsert behaviour.
+   *
+   * @example
+   * ```ts
+   * const created = await posts.batchCreate(
+   *   [{ title: 'A' }, { title: 'B' }],
+   *   { queryableFields: ['title'], userEmail: 'alice@example.com' },
+   * );
+   * ```
+   */
+  async batchCreate(items, options = {}) {
+    const { queryableFields, userEmail } = options;
+    const body = { records: items };
+    if (queryableFields?.length) body["queryableFields"] = queryableFields;
+    if (userEmail) body["userEmail"] = userEmail;
     const result = await this.http.post(
-      `${this.basePath}/batch`,
-      this.key,
-      { records: items }
+      `${this.basePath}/batch/insert`,
+      this.apiKey,
+      body
     );
-    return result.records;
+    return result.data ?? result.records ?? [];
   }
+  /**
+   * Delete multiple records in one request (max 500).
+   */
   async batchDelete(ids) {
     const result = await this.http.post(
       `${this.basePath}/batch/delete`,
-      this.key,
-      { ids }
+      this.apiKey,
+      { recordIds: ids }
     );
-    return { deleted: result.deleted, failed: result.failed };
+    return {
+      deleted: result.data?.successful ?? result.deleted ?? 0,
+      failed: result.data?.failed ?? result.failed ?? []
+    };
   }
   // ─── Querying ─────────────────────────────────────────────────────────────
+  /**
+   * Query records with optional filters, sorting, and pagination.
+   *
+   * @example
+   * ```ts
+   * const { records, hasMore, nextCursor } = await posts.query({
+   *   filters: [{ field: 'status', op: '==', value: 'published' }],
+   *   orderBy: 'createdAt',
+   *   order:   'desc',
+   *   limit:   20,
+   * });
+   * ```
+   */
   async query(options = {}) {
     const qs = buildQueryParams(options);
-    const result = await this.http.get(`${this.basePath}${qs}`, this.key);
-    return {
-      records: result.records,
-      total: result.total,
-      hasMore: result.hasMore,
-      nextCursor: result.nextCursor
-    };
+    const result = await this.http.get(`${this.basePath}${qs}`, this.apiKey);
+    const records = result.data ?? result.records ?? [];
+    const hasMore = result.meta?.hasMore ?? result.hasMore ?? false;
+    const total = result.meta?.total ?? result.total;
+    const nextCursor = result.meta?.nextCursor ?? result.nextCursor ?? void 0;
+    return { records, total, hasMore, nextCursor: nextCursor ?? void 0 };
   }
+  /**
+   * Get all records matching the given options (no filter support — use `query()` for filters).
+   */
   async getAll(options = {}) {
     const { records } = await this.query(options);
     return records;
   }
+  /**
+   * Count records matching the given filters.
+   */
   async count(filters = []) {
     const result = await this.http.post(
       `${this.basePath}/count`,
-      this.key,
+      this.apiKey,
       { filters }
     );
-    return result.count;
+    return result.data?.count ?? result.count ?? 0;
   }
   // ─── Version History ──────────────────────────────────────────────────────
+  /**
+   * Get the version history of a record.
+   */
   async getHistory(id) {
-    const result = await this.http.get(`${this.basePath}/${id}/history`, this.key);
+    const result = await this.http.get(
+      `${this.basePath}/${encodeURIComponent(id)}?showHistory=true`,
+      this.apiKey
+    );
     return result.history;
   }
+  /**
+   * Restore a record to a previous version.
+   */
   async restoreVersion(id, version) {
     const result = await this.http.post(
-      `${this.basePath}/${id}/restore`,
-      this.key,
+      `${this.basePath}/${encodeURIComponent(id)}/restore`,
+      this.apiKey,
       { version }
     );
-    return result.record ?? result.data;
+    return result.data ?? result.record;
   }
 };
 
@@ -445,39 +619,54 @@ var AnalyticsClient = class {
     );
     return result.data;
   }
+  // ─── Query methods ────────────────────────────────────────────────────────
+  /** Count all records, optionally within a date range. */
   async count(opts = {}) {
     return this.run({ queryType: "count", ...opts });
   }
+  /** Get value distribution for a field (e.g. how many records per status). */
   async distribution(opts) {
     assertSafeName(opts.field, "field");
     return this.run({ queryType: "distribution", ...opts });
   }
+  /** Sum a numeric field, optionally grouped by another field. */
   async sum(opts) {
     assertSafeName(opts.field, "field");
     if (opts.groupBy) assertSafeName(opts.groupBy, "groupBy");
     return this.run({ queryType: "sum", ...opts });
   }
+  /** Count of records over time, bucketed by granularity. */
   async timeSeries(opts = {}) {
     return this.run({ queryType: "timeSeries", granularity: "day", ...opts });
   }
+  /** Aggregate a numeric field over time. */
   async fieldTimeSeries(opts) {
     assertSafeName(opts.field, "field");
-    return this.run({ queryType: "fieldTimeSeries", aggregation: "sum", granularity: "day", ...opts });
+    return this.run({
+      queryType: "fieldTimeSeries",
+      aggregation: "sum",
+      granularity: "day",
+      ...opts
+    });
   }
+  /** Top N values for a field by count. */
   async topN(opts) {
     assertSafeName(opts.field, "field");
     if (opts.labelField) assertSafeName(opts.labelField, "labelField");
     return this.run({ queryType: "topN", n: 10, order: "desc", ...opts });
   }
+  /** Statistical summary (min, max, avg, sum, count, stddev) for a numeric field. */
   async stats(opts) {
     assertSafeName(opts.field, "field");
     return this.run({ queryType: "stats", ...opts });
   }
+  /** Fetch filtered records via the analytics engine (bypasses Firestore pagination). */
   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 });
   }
+  /** Compute multiple aggregations in a single request. */
   async multiMetric(opts) {
     opts.metrics.forEach((m) => {
       assertSafeName(m.field, "metric.field");
@@ -485,14 +674,22 @@ var AnalyticsClient = class {
     });
     return this.run({ queryType: "multiMetric", ...opts });
   }
+  /** Storage usage stats for the bucket (record count, bytes, avg/min/max size). */
   async storageStats(opts = {}) {
     return this.run({ queryType: "storageStats", ...opts });
   }
+  /**
+   * Compare a metric across multiple buckets in one query.
+   * The caller's key must have read access to every bucket in `bucketKeys`.
+   */
   async crossBucket(opts) {
     assertSafeName(opts.field, "field");
     opts.bucketKeys.forEach((k) => assertSafeName(k, "bucketKey"));
     return this.run({ queryType: "crossBucket", aggregation: "sum", ...opts });
   }
+  /**
+   * Raw query — use this when none of the typed helpers cover your use case.
+   */
   async query(query) {
     const data = await this.run(query);
     return { queryType: query.queryType, data };
@@ -500,34 +697,34 @@ var AnalyticsClient = class {
 };
 
 // src/storage/manager.ts
+function toUploadResult(r) {
+  return {
+    path: r.path,
+    mimeType: r.mimeType,
+    size: r.size,
+    isPublic: r.isPublic,
+    publicUrl: r.publicUrl,
+    downloadUrl: r.downloadUrl
+  };
+}
 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.
+   * For files >10 MB or when upload progress is needed, use `getUploadUrl()`.
    *
    * @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
+   * console.log(result.publicUrl);
    * ```
    */
   async upload(data, path, options = {}) {
@@ -545,100 +742,67 @@ var StorageManager = class {
       rawBody: formData,
       headers: this.authHeaders
     });
-    return {
-      path: result.path,
-      mimeType: result.mimeType,
-      size: result.size,
-      isPublic: result.isPublic,
-      publicUrl: result.publicUrl,
-      downloadUrl: result.downloadUrl
-    };
+    return toUploadResult(result);
   }
   /**
-   * Upload raw JSON or plain text data as a file.
+   * 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 },
-   * );
+   * await storage.uploadRaw({ theme: 'dark' }, 'settings/config.json');
    * ```
    */
   async uploadRaw(data, path, options = {}) {
     const { isPublic = false, overwrite = false, mimeType = "application/json" } = options;
-    const body = typeof data === "string" ? data : JSON.stringify(data);
+    const content = 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 },
+      body: { path, content, 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
-    };
+    return toUploadResult(result);
   }
   // ─── 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).
+   * Step 1 — get a signed GCS URL to upload directly from the client.
+   * Supports upload progress via `uploadToSignedUrl()`.
    *
    * @example
    * ```ts
    * const { uploadUrl, path: confirmedPath } = await storage.getUploadUrl({
-   *   path: 'videos/intro.mp4',
+   *   path:     'videos/intro.mp4',
    *   mimeType: 'video/mp4',
-   *   size: file.size,
+   *   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
+   * await storage.uploadToSignedUrl(uploadUrl, file, 'video/mp4', pct => console.log(pct + '%'));
    * const result = await storage.confirmUpload({ path: confirmedPath, mimeType: 'video/mp4', isPublic: true });
    * ```
    */
   async getUploadUrl(opts) {
+    const { expiresInSeconds, ...rest } = opts;
     const result = await this.http.request(`${this.basePath}/upload-url`, {
       method: "POST",
-      body: { isPublic: false, overwrite: false, expiresInSeconds: 900, ...opts },
+      body: { isPublic: false, overwrite: false, expiresIn: expiresInSeconds ?? 900, ...rest },
       headers: this.authHeaders
     });
-    return result;
+    return {
+      uploadUrl: result.uploadUrl,
+      path: result.path,
+      mimeType: result.mimeType,
+      expiresAt: result.expiresAt,
+      expiresIn: result.expiresIn
+    };
   }
   /**
-   * 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.
+   * Step 2 — upload data directly to a signed GCS URL.
+   * Supports progress tracking in browser environments.
    */
   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);
-   * ```
+   * Step 3 — confirm a direct upload and register metadata on the server.
    */
   async confirmUpload(opts) {
     const result = await this.http.request(`${this.basePath}/confirm`, {
@@ -646,27 +810,19 @@ var StorageManager = class {
       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
-    };
+    return toUploadResult(result);
   }
   // ─── Batch Upload ─────────────────────────────────────────────────────────
   /**
-   * Get signed upload URLs for multiple files at once.
+   * Get signed upload URLs for multiple files at once (max 50).
+   * Server returns `{ succeeded, failed }` — only succeeded items have URLs.
    *
    * @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 },
+   *   { path: 'images/a.jpg', mimeType: 'image/jpeg', size: 204800 },
+   *   { path: 'images/b.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 });
@@ -678,37 +834,35 @@ var StorageManager = class {
       `${this.basePath}/batch-upload-urls`,
       { method: "POST", body: { files }, headers: this.authHeaders }
     );
-    return { files: result.files };
+    return {
+      files: result.succeeded.map((f) => ({
+        index: f.index,
+        uploadUrl: f.uploadUrl,
+        path: f.path,
+        mimeType: f.mimeType,
+        expiresAt: f.expiresAt,
+        expiresIn: f.expiresIn
+      }))
+    };
   }
   /**
    * Confirm multiple direct uploads at once.
+   * Returns both succeeded and failed results.
    */
   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
-    }));
+    return {
+      succeeded: result.succeeded.map(toUploadResult),
+      failed: result.failed
+    };
   }
   // ─── 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("/");
@@ -718,11 +872,16 @@ var StorageManager = class {
     });
   }
   /**
-   * Download multiple files at once, returned as a JSON map of `{ path: base64 }`.
+   * Download multiple files at once (max 20).
+   * Returns a structured result with succeeded and failed items.
+   * Each succeeded item includes the file content as a base64 string.
    *
    * @example
    * ```ts
-   * const files = await storage.batchDownload(['docs/a.pdf', 'docs/b.pdf']);
+   * const { succeeded, failed } = await storage.batchDownload(['docs/a.pdf', 'docs/b.pdf']);
+   * for (const f of succeeded) {
+   *   const bytes = Buffer.from(f.content, 'base64');
+   * }
    * ```
    */
   async batchDownload(paths) {
@@ -730,24 +889,30 @@ var StorageManager = class {
       `${this.basePath}/batch-download`,
       { method: "POST", body: { paths }, headers: this.authHeaders }
     );
-    return result.files;
+    return {
+      succeeded: result.succeeded.map((f) => ({
+        index: f.index,
+        path: f.path,
+        mimeType: f.mimeType,
+        size: f.size,
+        content: f.content
+      })),
+      failed: result.failed.map((f) => ({
+        index: f.index,
+        path: f.path,
+        error: f.error,
+        code: f.code
+      }))
+    };
   }
   // ─── List ─────────────────────────────────────────────────────────────────
   /**
    * List files and folders at a given path prefix.
+   * Returns separate `files` and `folders` arrays for easy consumption.
    *
    * @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 { files, folders, hasMore, nextCursor } = await storage.list({ prefix: 'avatars/', limit: 20 });
    * const page2 = await storage.list({ prefix: 'avatars/', cursor: nextCursor });
    * ```
    */
@@ -756,28 +921,38 @@ var StorageManager = class {
     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
     });
+    if (result.items !== void 0) {
+      const files = [];
+      const folders = [];
+      for (const item of result.items) {
+        if (item.type === "folder") {
+          folders.push(item.path);
+        } else {
+          files.push(item);
+        }
+      }
+      return {
+        files,
+        folders,
+        hasMore: result.pagination?.hasMore ?? false,
+        nextCursor: result.pagination?.nextCursor ?? void 0
+      };
+    }
     return {
-      files: result.files,
-      folders: result.folders,
-      hasMore: result.hasMore,
-      nextCursor: result.nextCursor
+      files: result.files ?? [],
+      folders: result.folders ?? [],
+      hasMore: result.hasMore ?? false,
+      nextCursor: result.nextCursor ?? void 0
     };
   }
   // ─── 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);
-   * ```
+   * Get metadata for a file: size, MIME type, visibility, URLs.
    */
   async getMetadata(path) {
     const encoded = path.split("/").map(encodeURIComponent).join("/");
@@ -796,22 +971,15 @@ var StorageManager = class {
       updatedAt: result.updatedAt
     };
   }
-  // ─── Signed URL (time-limited share) ─────────────────────────────────────
+  // ─── Signed URL ───────────────────────────────────────────────────────────
   /**
    * 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.
+   * Can be shared externally without requiring an `X-Storage-Key`.
    *
-   * @param path       Path to the file.
-   * @param expiresIn  URL lifetime in seconds (default 3600 = 1 hour).
+   * > Note: Downloads via signed URLs bypass the server — download stats are NOT tracked.
    *
-   * @example
-   * ```ts
-   * const { signedUrl, expiresAt } = await storage.getSignedUrl('docs/invoice.pdf', 1800);
-   * // Share signedUrl with the recipient — it expires in 30 minutes.
-   * ```
+   * @param path      File path.
+   * @param expiresIn URL lifetime in seconds (default 3600 = 1 hour).
    */
   async getSignedUrl(path, expiresIn = 3600) {
     const result = await this.http.request(`${this.basePath}/signed-url`, {
@@ -829,17 +997,6 @@ var StorageManager = class {
   // ─── 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`, {
@@ -855,14 +1012,6 @@ var StorageManager = class {
     };
   }
   // ─── 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`,
@@ -871,14 +1020,6 @@ var StorageManager = class {
     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",
@@ -886,14 +1027,6 @@ var StorageManager = class {
       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",
@@ -901,17 +1034,6 @@ var StorageManager = class {
       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`,
@@ -919,14 +1041,6 @@ var StorageManager = class {
     );
     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`,
@@ -935,15 +1049,6 @@ var StorageManager = class {
     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",
@@ -952,17 +1057,10 @@ var StorageManager = class {
     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`);
+    return this.http.request(`${this.basePath}/info`, {
+      method: "GET"
+    });
   }
 };
 
@@ -970,85 +1068,105 @@ var StorageManager = class {
 var ScopedStorage = class _ScopedStorage {
   constructor(manager, prefix) {
     this.manager = manager;
-    this.prefix = prefix.replace(/\/+$/, "") + "/";
+    this.prefix = prefix.endsWith("/") ? prefix : `${prefix}/`;
   }
-  scopedPath(userPath) {
-    return `${this.prefix}${userPath.replace(/^\/+/, "")}`;
+  p(path) {
+    return `${this.prefix}${path.replace(/^\/+/, "")}`;
   }
-  /** Upload a file within the scoped folder. */
-  upload(data, path, options) {
-    return this.manager.upload(data, this.scopedPath(path), options);
+  // ─── Upload ───────────────────────────────────────────────────────────────
+  async upload(data, path, options = {}) {
+    return this.manager.upload(data, this.p(path), options);
   }
-  /** Upload raw JSON or text within the scoped folder. */
-  uploadRaw(data, path, options) {
-    return this.manager.uploadRaw(data, this.scopedPath(path), options);
+  async uploadRaw(data, path, options = {}) {
+    return this.manager.uploadRaw(data, this.p(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) });
+  async getUploadUrl(opts) {
+    return this.manager.getUploadUrl({ ...opts, path: this.p(opts.path) });
   }
-  /** Confirm a direct upload within the scoped folder. */
-  confirmUpload(opts) {
-    return this.manager.confirmUpload({ ...opts, path: this.scopedPath(opts.path) });
+  async uploadToSignedUrl(signedUrl, data, mimeType, onProgress) {
+    return this.manager.uploadToSignedUrl(signedUrl, data, mimeType, onProgress);
   }
-  /** Download a file within the scoped folder. */
-  download(path) {
-    return this.manager.download(this.scopedPath(path));
+  async confirmUpload(opts) {
+    return this.manager.confirmUpload({ ...opts, path: this.p(opts.path) });
   }
+  async getBatchUploadUrls(files) {
+    return this.manager.getBatchUploadUrls(
+      files.map((f) => ({ ...f, path: this.p(f.path) }))
+    );
+  }
+  async batchConfirmUploads(items) {
+    return this.manager.batchConfirmUploads(
+      items.map((i) => ({ ...i, path: this.p(i.path) }))
+    );
+  }
+  // ─── Download ─────────────────────────────────────────────────────────────
+  async download(path) {
+    return this.manager.download(this.p(path));
+  }
+  async batchDownload(paths) {
+    return this.manager.batchDownload(paths.map((p) => this.p(p)));
+  }
+  // ─── List ─────────────────────────────────────────────────────────────────
   /**
-   * List files within the scoped folder.
-   * `prefix` in options is relative to the scope.
+   * List files within this scope. The `prefix` option is relative to the scope root.
+   *
+   * @example
+   * ```ts
+   * const userDocs = storage.scope('users/alice/');
+   * // Lists users/alice/docs/
+   * const { files } = await userDocs.list({ prefix: 'docs/' });
+   * ```
    */
-  list(opts = {}) {
-    const scopedOpts = {
+  async list(opts = {}) {
+    return this.manager.list({
       ...opts,
-      prefix: this.scopedPath(opts.prefix ?? "")
-    };
-    return this.manager.list(scopedOpts);
+      prefix: this.p(opts.prefix ?? "")
+    });
+  }
+  // ─── Metadata & URLs ──────────────────────────────────────────────────────
+  async getMetadata(path) {
+    return this.manager.getMetadata(this.p(path));
   }
-  /** Get metadata for a file within the scoped folder. */
-  getMetadata(path) {
-    return this.manager.getMetadata(this.scopedPath(path));
+  async getSignedUrl(path, expiresIn = 3600) {
+    return this.manager.getSignedUrl(this.p(path), expiresIn);
   }
-  /** Get a time-limited signed URL for a file within the scoped folder. */
-  getSignedUrl(path, expiresIn) {
-    return this.manager.getSignedUrl(this.scopedPath(path), expiresIn);
+  async setVisibility(path, isPublic) {
+    return this.manager.setVisibility(this.p(path), isPublic);
   }
-  /** Change visibility of a file within the scoped folder. */
-  setVisibility(path, isPublic) {
-    return this.manager.setVisibility(this.scopedPath(path), isPublic);
+  // ─── Folder Operations ────────────────────────────────────────────────────
+  async createFolder(path) {
+    return this.manager.createFolder(this.p(path));
   }
-  /** Delete a file within the scoped folder. */
-  deleteFile(path) {
-    return this.manager.deleteFile(this.scopedPath(path));
+  // ─── File Operations ──────────────────────────────────────────────────────
+  async deleteFile(path) {
+    return this.manager.deleteFile(this.p(path));
   }
-  /** Delete a sub-folder within the scoped folder. */
-  deleteFolder(path) {
-    return this.manager.deleteFolder(this.scopedPath(path));
+  async deleteFolder(path) {
+    return this.manager.deleteFolder(this.p(path));
   }
-  /** Move a file within the scoped folder. */
-  move(from, to) {
-    return this.manager.move(this.scopedPath(from), this.scopedPath(to));
+  async move(from, to) {
+    return this.manager.move(this.p(from), this.p(to));
   }
-  /** Copy a file within the scoped folder. */
-  copy(from, to) {
-    return this.manager.copy(this.scopedPath(from), this.scopedPath(to));
+  async copy(from, to) {
+    return this.manager.copy(this.p(from), this.p(to));
   }
-  /** Create a sub-folder within the scoped folder. */
-  createFolder(path) {
-    return this.manager.createFolder(this.scopedPath(path));
+  // ─── Stats ────────────────────────────────────────────────────────────────
+  async getStats() {
+    return this.manager.getStats();
   }
+  // ─── Nesting ──────────────────────────────────────────────────────────────
   /**
-   * Create a further-scoped instance nested within this scope.
+   * Create a deeper scope within this one.
    *
    * @example
    * ```ts
-   * const uploads = db.storage.scope('user-uploads');
-   * const images = uploads.scope('images');   // → "user-uploads/images/"
+   * const user    = storage.scope('users/alice/');
+   * const userDocs = user.scope('docs/');
+   * // Effective prefix: users/alice/docs/
    * ```
    */
   scope(subPrefix) {
-    return new _ScopedStorage(this.manager, this.scopedPath(subPrefix));
+    return new _ScopedStorage(this.manager, this.p(subPrefix));
   }
 };
 
@@ -1068,22 +1186,23 @@ var HydrousClient = class {
     if (!config.storageKeys || Object.keys(config.storageKeys).length === 0) {
       throw new Error("[HydrousDB] storageKeys is required. Define at least one storage key from https://hydrousdb.com/dashboard.");
     }
-    const baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
-    this.http = new HttpClient(baseUrl);
+    this.http = new HttpClient(config.baseUrl ?? DEFAULT_BASE_URL);
     this.authKey_ = config.authKey;
     this.bucketSecurityKey_ = config.bucketSecurityKey;
     this.storageKeys_ = config.storageKeys;
   }
-  // ─── Records ─────────────────────────────────────────────────────────────
+  // ─── Records ──────────────────────────────────────────────────────────────
   /**
    * Get a typed records client for the named bucket.
-   * Uses your `bucketSecurityKey` automatically.
    *
    * @example
    * ```ts
    * interface Post { title: string; published: boolean }
    * const posts = db.records<Post>('blog-posts');
-   * const post = await posts.create({ title: 'Hello', published: false });
+   * const post  = await posts.create(
+   *   { title: 'Hello', published: false },
+   *   { queryableFields: ['published'] },
+   * );
    * ```
    */
   records(bucketKey) {
@@ -1098,7 +1217,6 @@ var HydrousClient = class {
   // ─── Auth ─────────────────────────────────────────────────────────────────
   /**
    * Get an auth client for the named user bucket.
-   * Uses your `authKey` automatically.
    *
    * @example
    * ```ts
@@ -1115,7 +1233,6 @@ var HydrousClient = class {
   // ─── Analytics ────────────────────────────────────────────────────────────
   /**
    * Get an analytics client for the named bucket.
-   * Uses your `bucketSecurityKey` automatically.
    *
    * @example
    * ```ts
@@ -1135,21 +1252,16 @@ var HydrousClient = class {
   // ─── Storage ──────────────────────────────────────────────────────────────
   /**
    * Get a storage manager for the named storage key.
-   * The name must match a key you defined in `storageKeys` when calling `createClient`.
-   * Uses the corresponding `ssk_…` key automatically via `X-Storage-Key` header.
+   * The name must match a key defined in `storageKeys` when calling `createClient`.
    *
-   * @param keyName  The name of the storage key (e.g. `"avatars"`, `"documents"`, `"main"`).
+   * Attach `.scope(prefix)` to namespace all operations under a path prefix.
    *
    * @example
    * ```ts
-   * const avatars   = db.storage('avatars');
-   * const documents = db.storage('documents');
+   * const avatars  = db.storage('avatars');
+   * const userDocs = db.storage('documents').scope(`users/${userId}/`);
    *
-   * // Upload to avatars bucket
    * await avatars.upload(file, `${userId}.jpg`, { isPublic: true });
-   *
-   * // Scope to a sub-folder
-   * const userDocs = db.storage('documents').scope(`users/${userId}`);
    * await userDocs.upload(pdfBuffer, 'contract.pdf');
    * ```
    */