hydrousdb 3.2.0 → 3.5.1

package/dist/index.mjs

@@ -57,7 +57,7 @@ var HttpClient = class {
   constructor(baseUrl) {
     this.baseUrl = baseUrl.replace(/\/$/, "");
   }
-  // ─── Core request method ──────────────────────────────────────────────────
+  // ─── Core request ──────────────────────────────────────────────────────────
   async request(path, options) {
     const url = `${this.baseUrl}${path}`;
     const headers = { ...options.headers };
@@ -96,11 +96,7 @@ var HttpClient = class {
     try {
       data = await response.json();
     } catch {
-      throw new HydrousError(
-        `Failed to parse response JSON`,
-        "PARSE_ERROR",
-        response.status
-      );
+      throw new HydrousError("Failed to parse response JSON", "PARSE_ERROR", response.status);
     }
     if (!response.ok) {
       throw new HydrousError(
@@ -149,8 +145,8 @@ var HttpClient = class {
     });
   }
   /**
-   * Upload directly to a signed GCS URL (no auth headers — signed URL is self-authenticating).
-   * Supports optional progress tracking via XHR in browser environments.
+   * PUT directly to a signed GCS URL.
+   * Uses XHR in browsers for onprogress support; fetch in Node.
    */
   async putToSignedUrl(signedUrl, data, mimeType, onProgress) {
     const body = data instanceof Blob ? data : data instanceof Uint8Array ? data.buffer : data;
@@ -179,135 +175,262 @@ var HttpClient = class {
   }
 };
 
+// src/routes.ts
+var RECORDS = {
+  /** GET|POST|PATCH|DELETE|HEAD /api/:bucketKey */
+  bucket: (bucketKey) => `/api/${bucketKey}`,
+  /** POST /api/:bucketKey/batch/insert */
+  batchInsert: (bucketKey) => `/api/${bucketKey}/batch/insert`,
+  /** POST /api/:bucketKey/batch/update */
+  batchUpdate: (bucketKey) => `/api/${bucketKey}/batch/update`,
+  /** POST /api/:bucketKey/batch/delete */
+  batchDelete: (bucketKey) => `/api/${bucketKey}/batch/delete`
+};
+var ANALYTICS = {
+  /** POST /api/analytics/:bucketKey */
+  query: (bucketKey) => `/api/analytics/${bucketKey}`
+};
+var AUTH = {
+  /** POST /api/auth/signup   body: { email, password, fullName?, ...extra } */
+  signup: "/api/auth/signup",
+  /** POST /api/auth/signin   body: { email, password } */
+  signin: "/api/auth/signin",
+  /** POST /api/auth/signout  body: { sessionId, allDevices? } */
+  signout: "/api/auth/signout",
+  /** POST /api/auth/session/validate  body: { sessionId } */
+  sessionValidate: "/api/auth/session/validate",
+  /** POST /api/auth/session/refresh   body: { refreshToken } */
+  sessionRefresh: "/api/auth/session/refresh",
+  /** GET  /api/auth/user?userId=... */
+  getUser: "/api/auth/user",
+  /** GET  /api/auth/users?limit=&cursor= */
+  listUsers: "/api/auth/users",
+  /** PATCH /api/auth/user  body: { sessionId, userId, updates: {...} } */
+  updateUser: "/api/auth/user",
+  /** DELETE /api/auth/user?userId=...  body: { sessionId } */
+  deleteUser: "/api/auth/user",
+  /** DELETE /api/auth/user/hard?userId=...  body: { sessionId } */
+  hardDeleteUser: "/api/auth/user/hard",
+  /** DELETE /api/auth/users/bulk  body: { userIds, hard?, sessionId } */
+  bulkDeleteUsers: "/api/auth/users/bulk",
+  /** POST /api/auth/password/change  body: { sessionId, userId, oldPassword, newPassword } */
+  passwordChange: "/api/auth/password/change",
+  /** POST /api/auth/password/reset/request  body: { email } */
+  passwordResetRequest: "/api/auth/password/reset/request",
+  /** POST /api/auth/password/reset/confirm  body: { resetToken, newPassword } */
+  passwordResetConfirm: "/api/auth/password/reset/confirm",
+  /** POST /api/auth/email/verify/request  body: { userId } */
+  emailVerifyRequest: "/api/auth/email/verify/request",
+  /** POST /api/auth/email/verify/confirm  body: { verifyToken } */
+  emailVerifyConfirm: "/api/auth/email/verify/confirm",
+  /** POST /api/auth/account/lock    body: { sessionId, userId, duration? } */
+  accountLock: "/api/auth/account/lock",
+  /** POST /api/auth/account/unlock  body: { sessionId, userId } */
+  accountUnlock: "/api/auth/account/unlock"
+};
+var STORAGE = {
+  /** GET /storage/info  — no auth required */
+  info: "/storage/info",
+  /** GET /storage/public/:fullScopedPath  — no auth required */
+  publicFile: (fullScopedPath) => `/storage/public/${fullScopedPath}`,
+  /** POST /storage/upload-url  body: { path, mimeType, size, isPublic?, overwrite?, expiresIn? } */
+  uploadUrl: "/storage/upload-url",
+  /** POST /storage/batch-upload-urls  body: { files: [...], expiresIn? } */
+  batchUploadUrls: "/storage/batch-upload-urls",
+  /** POST /storage/confirm  body: { path, mimeType, isPublic? } */
+  confirm: "/storage/confirm",
+  /** POST /storage/batch-confirm  body: { files: [...] } */
+  batchConfirm: "/storage/batch-confirm",
+  /** POST /storage/upload  multipart/form-data: file, path, mimeType, isPublic, overwrite */
+  upload: "/storage/upload",
+  /** POST /storage/upload-raw  body: { path, content, mimeType?, isPublic?, overwrite? } */
+  uploadRaw: "/storage/upload-raw",
+  /** GET /storage/list?prefix=&limit=&cursor= */
+  list: "/storage/list",
+  /** GET /storage/download/:path  — requires X-Storage-Key */
+  download: (filePath) => `/storage/download/${filePath}`,
+  /** POST /storage/batch-download  body: { paths: [...], concurrency? } */
+  batchDownload: "/storage/batch-download",
+  /** GET /storage/metadata/:path */
+  metadata: (filePath) => `/storage/metadata/${filePath}`,
+  /** POST /storage/signed-url  body: { path, expiresIn? } */
+  signedUrl: "/storage/signed-url",
+  /** PATCH /storage/visibility  body: { path, isPublic } */
+  visibility: "/storage/visibility",
+  /** POST /storage/folder  body: { path } */
+  folder: "/storage/folder",
+  /** DELETE /storage/file  body: { path } */
+  file: "/storage/file",
+  /** DELETE /storage/folder  body: { path } */
+  folderDelete: "/storage/folder",
+  /** POST /storage/move  body: { from, to } */
+  move: "/storage/move",
+  /** POST /storage/copy  body: { from, to } */
+  copy: "/storage/copy",
+  /** GET /storage/stats */
+  stats: "/storage/stats"
+};
+
 // src/auth/client.ts
 var AuthClient = class {
-  constructor(http, authKey, bucketKey) {
+  constructor(http, authKey) {
     this.http = http;
     this.authKey = authKey;
-    this.basePath = `/auth/${bucketKey}`;
   }
   post(path, body) {
     return this.http.post(path, this.authKey, body);
   }
-  get(path, query) {
+  get(path, query, extraHeaders) {
     const qs = query && Object.keys(query).length ? "?" + new URLSearchParams(query).toString() : "";
-    return this.http.get(`${path}${qs}`, this.authKey);
+    return this.http.get(`${path}${qs}`, this.authKey, extraHeaders);
   }
   patch(path, body) {
     return this.http.patch(path, this.authKey, body);
   }
-  delete(path, body) {
-    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 }
+  // ─── Signup / Login / Logout ──────────────────────────────────────────────
+  /**
+   * Register a new user account.
+   *
+   * Server: POST /api/auth/signup
+   * Body: { email, password, fullName?, ...extraData }
+   */
   async signup(options) {
-    const result = await this.post(`${this.basePath}/signup`, 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
-      }
-    };
+    const result = await this.post(AUTH.signup, options);
+    const user = result.data;
+    return this._buildAuthResult(user, result.session);
   }
+  /**
+   * Sign in with email + password.
+   *
+   * Server: POST /api/auth/signin   (NOT /login)
+   * Body: { email, password }
+   */
   async login(options) {
-    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
-      }
-    };
+    const result = await this.post(AUTH.signin, options);
+    const user = result.data;
+    return this._buildAuthResult(user, result.session);
   }
+  /**
+   * Sign out — revoke a session (or all sessions with `allDevices: true`).
+   *
+   * Server: POST /api/auth/signout
+   * Body: { sessionId, allDevices? }
+   */
   async logout(options) {
-    await this.post(`${this.basePath}/signout`, options);
+    await this.post(AUTH.signout, options);
   }
-  async refreshSession({ refreshToken }) {
+  // ─── Session Management ───────────────────────────────────────────────────
+  /**
+   * Validate an existing session and retrieve the current user.
+   *
+   * Server: POST /api/auth/session/validate
+   * Body: { sessionId }
+   */
+  async validateSession(sessionId) {
     const result = await this.post(
-      `${this.basePath}/session/refresh`,
+      AUTH.sessionValidate,
+      { sessionId }
+    );
+    return { user: result.data, session: result.session };
+  }
+  /**
+   * Rotate a refresh token to get a new session.
+   *
+   * Server: POST /api/auth/session/refresh
+   * Body: { refreshToken }
+   */
+  async refreshSession(refreshToken) {
+    const result = await this.post(
+      AUTH.sessionRefresh,
       { refreshToken }
     );
     const s = result.session;
     return {
       sessionId: s.sessionId,
       userId: result.data?.id ?? "",
-      bucketId: this.basePath.split("/")[2],
+      bucketId: "",
       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 });
+  /**
+   * Fetch a user by ID.
+   *
+   * Server: GET /api/auth/user?userId=:userId
+   */
+  async getUser(userId) {
+    const result = await this.get(AUTH.getUser, { userId });
     return result.data;
   }
+  /**
+   * Update a user's profile fields.
+   * Regular users can only update themselves; admins can update any user.
+   *
+   * Server: PATCH /api/auth/user
+   * Body: { sessionId, userId, updates: { ...fields } }
+   */
   async updateUser(options) {
     const { sessionId, userId, updates } = options;
     const result = await this.patch(
-      `${this.basePath}/user`,
+      AUTH.updateUser,
       { sessionId, userId, updates }
     );
     return result.data;
   }
-  async deleteUser({ sessionId, userId }) {
-    await this.http.request(`${this.basePath}/user?userId=${encodeURIComponent(userId)}`, {
-      method: "DELETE",
-      body: { sessionId },
-      headers: { "X-Api-Key": this.authKey }
-    });
+  /**
+   * Soft-delete a user account.
+   * Regular users can only delete themselves; admins can delete any user.
+   *
+   * Server: DELETE /api/auth/user?userId=:userId
+   * Body: { sessionId }
+   */
+  async deleteUser(sessionId, userId) {
+    await this.http.request(
+      `${AUTH.deleteUser}?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 }
+  /**
+   * List all users (paginated). Admin only.
+   *
+   * Server: GET /api/auth/users?limit=&cursor=
+   * The sessionId is passed via the X-Session-Id header (GET body is unreliable).
+   */
   async listUsers(options) {
     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)}`,
+      `${AUTH.listUsers}?${new URLSearchParams(params)}`,
       {
         method: "GET",
         headers: { "X-Api-Key": this.authKey, "X-Session-Id": sessionId }
       }
     );
     return {
-      users: result.data ?? result.users ?? [],
+      users: result.data ?? [],
       hasMore: result.meta?.hasMore ?? result.hasMore ?? false,
       nextCursor: result.meta?.nextCursor ?? result.nextCursor ?? null
     };
   }
-  async hardDeleteUser({ sessionId, userId }) {
+  /**
+   * Permanently delete a user (hard delete — cannot be undone).
+   * Admin only. Charged at 1 HC per deletion.
+   *
+   * Server: DELETE /api/auth/user/hard?userId=:userId
+   * Body: { sessionId }
+   */
+  async hardDeleteUser(sessionId, userId) {
     await this.http.request(
-      `${this.basePath}/user/hard?userId=${encodeURIComponent(userId)}`,
+      `${AUTH.hardDeleteUser}?userId=${encodeURIComponent(userId)}`,
       {
         method: "DELETE",
         body: { sessionId },
@@ -315,54 +438,114 @@ var AuthClient = class {
       }
     );
   }
+  /**
+   * Delete multiple users at once (soft or hard). Admin only.
+   *
+   * Server: DELETE /api/auth/users/bulk
+   * Body: { userIds, hard?, sessionId }
+   */
   async bulkDeleteUsers(options) {
     const result = await this.http.request(
-      `${this.basePath}/users/bulk`,
+      AUTH.bulkDeleteUsers,
       {
         method: "DELETE",
-        body: { userIds: options.userIds, hard: options.hard ?? false, sessionId: options.sessionId },
+        body: {
+          userIds: options.userIds,
+          hard: options.hard ?? false,
+          sessionId: options.sessionId
+        },
         headers: { "X-Api-Key": this.authKey }
       }
     );
     return { succeeded: result.meta.succeeded, failed: result.meta.failed };
   }
+  /**
+   * Lock a user account for a specified duration. Admin only.
+   *
+   * Server: POST /api/auth/account/lock
+   * Body: { sessionId, userId, duration? }  — duration in ms, default 15 min
+   */
   async lockAccount(options) {
-    const result = await this.post(
-      `${this.basePath}/account/lock`,
-      options
-    );
+    const result = await this.post(AUTH.accountLock, options);
     return result.data;
   }
-  async unlockAccount({ sessionId, userId }) {
-    await this.post(`${this.basePath}/account/unlock`, { sessionId, userId });
+  /**
+   * Unlock a locked user account. Admin only.
+   *
+   * Server: POST /api/auth/account/unlock
+   * Body: { sessionId, userId }
+   */
+  async unlockAccount(sessionId, userId) {
+    await this.post(AUTH.accountUnlock, { 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 }
+  /**
+   * Change a user's password. Requires both a valid session AND the old password.
+   *
+   * Server: POST /api/auth/password/change
+   * Body: { sessionId, userId, oldPassword, newPassword }
+   */
   async changePassword(options) {
-    const { sessionId, userId, currentPassword, newPassword } = options;
-    await this.post(`${this.basePath}/password/change`, {
-      sessionId,
-      userId,
-      oldPassword: currentPassword,
-      newPassword
+    await this.post(AUTH.passwordChange, {
+      sessionId: options.sessionId,
+      userId: options.userId,
+      oldPassword: options.currentPassword,
+      // server field is `oldPassword`
+      newPassword: options.newPassword
     });
   }
-  async requestPasswordReset({ email }) {
-    await this.post(`${this.basePath}/password/reset/request`, { email });
+  /**
+   * Request a password reset email.
+   * Always returns success regardless of whether the email exists (prevents enumeration).
+   *
+   * Server: POST /api/auth/password/reset/request
+   * Body: { email }
+   */
+  async requestPasswordReset(email) {
+    await this.post(AUTH.passwordResetRequest, { email });
   }
-  async confirmPasswordReset({ resetToken, newPassword }) {
-    await this.post(`${this.basePath}/password/reset/confirm`, { resetToken, newPassword });
+  /**
+   * Confirm a password reset using the token from the reset email.
+   *
+   * Server: POST /api/auth/password/reset/confirm
+   * Body: { resetToken, newPassword }
+   */
+  async confirmPasswordReset(resetToken, newPassword) {
+    await this.post(AUTH.passwordResetConfirm, { 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 });
+  /**
+   * Request a verification email be sent to a user.
+   *
+   * Server: POST /api/auth/email/verify/request
+   * Body: { userId }
+   */
+  async requestEmailVerification(userId) {
+    await this.post(AUTH.emailVerifyRequest, { userId });
   }
-  async confirmEmailVerification({ verifyToken }) {
-    await this.post(`${this.basePath}/email/verify/confirm`, { verifyToken });
+  /**
+   * Confirm email ownership using the token from the verification email.
+   *
+   * Server: POST /api/auth/email/verify/confirm
+   * Body: { verifyToken }
+   */
+  async confirmEmailVerification(verifyToken) {
+    await this.post(AUTH.emailVerifyConfirm, { verifyToken });
+  }
+  // ─── Private helpers ──────────────────────────────────────────────────────
+  _buildAuthResult(user, session) {
+    return {
+      user,
+      session: {
+        sessionId: session.sessionId,
+        userId: user.id,
+        bucketId: "",
+        createdAt: Date.now(),
+        expiresAt: session.expiresAt,
+        refreshToken: session.refreshToken,
+        refreshExpiresAt: session.expiresAt
+      }
+    };
   }
 };
 
@@ -371,18 +554,22 @@ 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.orderBy !== void 0) params.set("sortBy", options.orderBy);
+  if (options.order !== void 0) params.set("sortOrder", 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.startAfter !== void 0) params.set("cursor", options.startAfter);
+  if (options.startAt !== void 0) params.set("cursor", options.startAt);
+  if (options.timeScope !== void 0) params.set("timeScope", options.timeScope);
   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));
+  if (options.filters && options.filters.length > 0) {
+    for (const f of options.filters) {
+      const key = f.op === "==" ? f.field : `${f.field}[${f.op}]`;
+      params.set(key, String(f.value));
+    }
+  }
   const str = params.toString();
   return str ? `?${str}` : "";
 }
@@ -404,10 +591,13 @@ function guessMimeType(filename) {
     html: "text/html",
     css: "text/css",
     js: "application/javascript",
+    ts: "application/typescript",
     json: "application/json",
     xml: "application/xml",
     zip: "application/zip",
-    csv: "text/csv"
+    csv: "text/csv",
+    xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
   };
   return map[ext ?? ""] ?? "application/octet-stream";
 }
@@ -426,15 +616,14 @@ var RecordsClient = class {
     this.http = http;
     this.bucketKey = bucketKey;
     this.apiKey = bucketSecurityKey;
-    this.basePath = `/records/${bucketKey}`;
   }
   // ─── Single Record Operations ─────────────────────────────────────────────
   /**
-   * Create a new record.
+   * Create a new record (auto-generated ID) or upsert by `customRecordId`.
    *
-   * @param data    The record fields to store.
-   * @param options Optional: queryableFields (for server-side filtering),
-   *                userEmail (audit trail), customRecordId (upsert by ID).
+   * Server: POST /api/:bucketKey
+   * Body: { values, queryableFields?, userEmail?, customRecordId? }
+   * Returns 201 for new records, 200 for upserts.
    *
    * @example
    * ```ts
@@ -450,63 +639,110 @@ var RecordsClient = class {
     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;
+    const result = await this.http.post(
+      RECORDS.bucket(this.bucketKey),
+      this.apiKey,
+      body
+    );
+    return result.data;
   }
   /**
    * Get a single record by ID.
+   *
+   * Server: GET /api/:bucketKey?recordId=:id
    */
   async get(id) {
     const result = await this.http.get(
-      `${this.basePath}/${encodeURIComponent(id)}`,
+      `${RECORDS.bucket(this.bucketKey)}?recordId=${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}/${encodeURIComponent(id)}`,
-      this.apiKey,
-      data
-    );
-    return result.data ?? result.record;
+    return result.data;
   }
   /**
-   * Partially update a record (PATCH semantics).
-   * By default merges with existing fields; set `merge: false` to replace.
+   * Partially update an existing record (PATCH semantics).
    * Supports write-filter sentinels: `{ __op: 'increment', delta: 1 }` etc.
+   *
+   * Server: PATCH /api/:bucketKey
+   * Body: { recordId, values, userEmail?, track_record_history? }
    */
   async patch(id, data, options = {}) {
-    const { merge = true } = options;
+    const { userEmail, trackHistory } = options;
+    const body = { recordId: id, values: data };
+    if (userEmail) body["userEmail"] = userEmail;
+    if (trackHistory) body["track_record_history"] = true;
     const result = await this.http.patch(
-      `${this.basePath}/${encodeURIComponent(id)}`,
+      RECORDS.bucket(this.bucketKey),
       this.apiKey,
-      { ...data, _merge: merge }
+      body
     );
-    return result.data ?? result.record;
+    return { id: result.meta?.id ?? id, updatedAt: result.meta?.updatedAt };
   }
   /**
    * Delete a record permanently.
+   *
+   * Server: DELETE /api/:bucketKey?recordId=:id
    */
   async delete(id) {
     await this.http.delete(
-      `${this.basePath}/${encodeURIComponent(id)}`,
+      `${RECORDS.bucket(this.bucketKey)}?recordId=${encodeURIComponent(id)}`,
+      this.apiKey
+    );
+  }
+  /**
+   * Check whether a record exists (HEAD request — very lightweight).
+   *
+   * Server: HEAD /api/:bucketKey?recordId=:id
+   * Returns true if the record exists, false if 404.
+   */
+  async exists(id) {
+    try {
+      await this.http.request(
+        `${RECORDS.bucket(this.bucketKey)}?recordId=${encodeURIComponent(id)}`,
+        { method: "HEAD", headers: { "X-Api-Key": this.apiKey } }
+      );
+      return true;
+    } catch (err) {
+      if (err && typeof err === "object" && "status" in err && err.status === 404) return false;
+      throw err;
+    }
+  }
+  /**
+   * Get a historical snapshot of a record at a specific generation.
+   *
+   * Server: GET /api/:bucketKey?recordId=:id&generation=:gen
+   */
+  async getVersion(id, generation) {
+    const result = await this.http.get(
+      `${RECORDS.bucket(this.bucketKey)}?recordId=${encodeURIComponent(id)}&generation=${encodeURIComponent(String(generation))}`,
+      this.apiKey
+    );
+    return result.data;
+  }
+  /**
+   * Get the version history of a record.
+   *
+   * Server: GET /api/:bucketKey?recordId=:id&showHistory=true
+   */
+  async getHistory(id) {
+    const result = await this.http.get(
+      `${RECORDS.bucket(this.bucketKey)}?recordId=${encodeURIComponent(id)}&showHistory=true`,
       this.apiKey
     );
+    return result.history ?? [];
   }
   // ─── Batch Operations ─────────────────────────────────────────────────────
   /**
-   * Create multiple records in one request (max 500).
-   * Each record can include a `_customRecordId` field for upsert behaviour.
+   * Create up to 500 records in one request.
+   * Each record may include `_customRecordId` for upsert behaviour.
+   *
+   * Server: POST /api/:bucketKey/batch/insert
+   * Body: { records, queryableFields?, userEmail? }
    *
    * @example
    * ```ts
-   * const created = await posts.batchCreate(
+   * const results = await posts.batchCreate(
    *   [{ title: 'A' }, { title: 'B' }],
-   *   { queryableFields: ['title'], userEmail: 'alice@example.com' },
+   *   { queryableFields: ['title'] },
    * );
    * ```
    */
@@ -516,29 +752,60 @@ var RecordsClient = class {
     if (queryableFields?.length) body["queryableFields"] = queryableFields;
     if (userEmail) body["userEmail"] = userEmail;
     const result = await this.http.post(
-      `${this.basePath}/batch/insert`,
+      RECORDS.batchInsert(this.bucketKey),
       this.apiKey,
       body
     );
-    return result.data ?? result.records ?? [];
+    return {
+      results: result.data ?? [],
+      errors: result.errors ?? [],
+      successful: result.meta?.successful ?? (result.data?.length ?? 0),
+      failed: result.meta?.failed ?? 0
+    };
   }
   /**
-   * Delete multiple records in one request (max 500).
+   * Update up to 500 records in one request.
+   *
+   * Server: POST /api/:bucketKey/batch/update
+   * Body: { updates: [{ recordId, values }], userEmail? }
    */
-  async batchDelete(ids) {
+  async batchUpdate(updates, userEmail) {
+    const body = { updates };
+    if (userEmail) body["userEmail"] = userEmail;
     const result = await this.http.post(
-      `${this.basePath}/batch/delete`,
+      RECORDS.batchUpdate(this.bucketKey),
       this.apiKey,
-      { recordIds: ids }
+      body
     );
     return {
-      deleted: result.data?.successful ?? result.deleted ?? 0,
-      failed: result.data?.failed ?? result.failed ?? []
+      successful: result.data?.successful ?? result.meta?.count ?? 0,
+      failed: result.data?.failed ?? []
+    };
+  }
+  /**
+   * Delete up to 500 records in one request.
+   *
+   * Server: POST /api/:bucketKey/batch/delete
+   * Body: { recordIds, userEmail? }
+   */
+  async batchDelete(ids, userEmail) {
+    const body = { recordIds: ids };
+    if (userEmail) body["userEmail"] = userEmail;
+    const result = await this.http.post(
+      RECORDS.batchDelete(this.bucketKey),
+      this.apiKey,
+      body
+    );
+    return {
+      successful: result.data?.successful ?? result.meta?.count ?? 0,
+      failed: result.data?.failed ?? []
     };
   }
   // ─── Querying ─────────────────────────────────────────────────────────────
   /**
-   * Query records with optional filters, sorting, and pagination.
+   * Query records with filters, sorting, and cursor-based pagination.
+   *
+   * Server: GET /api/:bucketKey?field=value&field[op]=value&limit=&sortBy=&sortOrder=&cursor=
    *
    * @example
    * ```ts
@@ -552,52 +819,23 @@ var RecordsClient = class {
    */
   async query(options = {}) {
     const qs = buildQueryParams(options);
-    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.apiKey,
-      { filters }
-    );
-    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}/${encodeURIComponent(id)}?showHistory=true`,
+      `${RECORDS.bucket(this.bucketKey)}${qs}`,
       this.apiKey
     );
-    return result.history;
+    return {
+      records: result.data ?? [],
+      total: result.meta?.total ?? result.total,
+      hasMore: result.meta?.hasMore ?? result.hasMore ?? false,
+      nextCursor: result.meta?.nextCursor ?? result.nextCursor ?? void 0
+    };
   }
   /**
-   * Restore a record to a previous version.
+   * Retrieve all records matching options (no filter support — use `query()` for filters).
    */
-  async restoreVersion(id, version) {
-    const result = await this.http.post(
-      `${this.basePath}/${encodeURIComponent(id)}/restore`,
-      this.apiKey,
-      { version }
-    );
-    return result.data ?? result.record;
+  async getAll(options = {}) {
+    const { records } = await this.query(options);
+    return records;
   }
 };
 
@@ -607,11 +845,11 @@ var AnalyticsClient = class {
     assertSafeName(bucketKey, "bucketKey");
     this.http = http;
     this.bucketSecurityKey = bucketSecurityKey;
-    this.basePath = `/analytics/${bucketKey}`;
+    this.bucketKey = bucketKey;
   }
   async run(query) {
     const result = await this.http.post(
-      this.basePath,
+      ANALYTICS.query(this.bucketKey),
       this.bucketSecurityKey,
       query
     );
@@ -622,7 +860,10 @@ var AnalyticsClient = class {
   async count(opts = {}) {
     return this.run({ queryType: "count", ...opts });
   }
-  /** Get value distribution for a field (e.g. how many records per status). */
+  /**
+   * Get value distribution for a field (e.g. records per status).
+   * `order` maps to `sortBy` on the wire (the server param name).
+   */
   async distribution(opts) {
     assertSafeName(opts.field, "field");
     return this.run({ queryType: "distribution", ...opts });
@@ -658,13 +899,19 @@ var AnalyticsClient = class {
     assertSafeName(opts.field, "field");
     return this.run({ queryType: "stats", ...opts });
   }
-  /** Fetch filtered records via the analytics engine (bypasses Firestore pagination). */
+  /**
+   * Fetch filtered records via the analytics engine (BigQuery).
+   * Bypasses Firestore pagination — useful for large result sets.
+   */
   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. */
+  /**
+   * Compute multiple aggregations in a single request.
+   * `metrics` must have valid `field` and `name` (used as BigQuery column aliases).
+   */
   async multiMetric(opts) {
     opts.metrics.forEach((m) => {
       assertSafeName(m.field, "metric.field");
@@ -678,7 +925,8 @@ var AnalyticsClient = class {
   }
   /**
    * Compare a metric across multiple buckets in one query.
-   * The caller's key must have read access to every bucket in `bucketKeys`.
+   * The caller's key must have read access to EVERY bucket in `bucketKeys`.
+   * System buckets (`users`, `_sys_*`) are blocked server-side.
    */
   async crossBucket(opts) {
     assertSafeName(opts.field, "field");
@@ -686,7 +934,7 @@ var AnalyticsClient = class {
     return this.run({ queryType: "crossBucket", aggregation: "sum", ...opts });
   }
   /**
-   * Raw query — use this when none of the typed helpers cover your use case.
+   * Raw query — escape hatch when the typed helpers don't cover your case.
    */
   async query(query) {
     const data = await this.run(query);
@@ -707,17 +955,19 @@ function toUploadResult(r) {
 }
 var StorageManager = class {
   constructor(http, storageKey) {
-    this.basePath = "/storage";
     this.http = http;
     this.storageKey = storageKey;
   }
   get authHeaders() {
     return { "X-Storage-Key": this.storageKey };
   }
-  // ─── Upload: Simple (server-buffered) ────────────────────────────────────
+  // ─── Upload: Server-buffered ──────────────────────────────────────────────
   /**
-   * Upload a file to storage in one step (server-buffered, up to 500 MB).
-   * For files >10 MB or when upload progress is needed, use `getUploadUrl()`.
+   * Upload a file in one step (server-buffered, up to 500 MB).
+   * For files >10 MB or when upload progress tracking is needed, use the
+   * signed URL flow: `getUploadUrl()` → `uploadToSignedUrl()` → `confirmUpload()`.
+   *
+   * Server: POST /storage/upload  (multipart/form-data)
    *
    * @example
    * ```ts
@@ -735,7 +985,7 @@ var StorageManager = class {
     formData.append("mimeType", mime);
     formData.append("isPublic", String(isPublic));
     formData.append("overwrite", String(overwrite));
-    const result = await this.http.request(`${this.basePath}/upload`, {
+    const result = await this.http.request(STORAGE.upload, {
       method: "POST",
       rawBody: formData,
       headers: this.authHeaders
@@ -743,7 +993,10 @@ var StorageManager = class {
     return toUploadResult(result);
   }
   /**
-   * Upload raw JSON or plain-text data as a file.
+   * Upload raw string or JSON data directly as a file.
+   *
+   * Server: POST /storage/upload-raw
+   * Body: { path, content, mimeType?, isPublic?, overwrite? }
    *
    * @example
    * ```ts
@@ -753,33 +1006,32 @@ var StorageManager = class {
   async uploadRaw(data, path, options = {}) {
     const { isPublic = false, overwrite = false, mimeType = "application/json" } = options;
     const content = typeof data === "string" ? data : JSON.stringify(data);
-    const result = await this.http.request(`${this.basePath}/upload-raw`, {
+    const result = await this.http.request(STORAGE.uploadRaw, {
       method: "POST",
       body: { path, content, mimeType, isPublic, overwrite },
       headers: this.authHeaders
     });
     return toUploadResult(result);
   }
-  // ─── Upload: Direct-to-GCS (recommended for large files) ─────────────────
+  // ─── Upload: Direct-to-GCS (recommended for large files / progress) ───────
   /**
-   * Step 1 — get a signed GCS URL to upload directly from the client.
-   * Supports upload progress via `uploadToSignedUrl()`.
+   * Step 1 — get a signed GCS PUT URL for direct client-to-GCS upload.
+   *
+   * Server: POST /storage/upload-url
+   * Body: { path, mimeType, size, isPublic?, overwrite?, expiresIn? }
    *
    * @example
    * ```ts
-   * const { uploadUrl, path: confirmedPath } = await storage.getUploadUrl({
-   *   path:     'videos/intro.mp4',
-   *   mimeType: 'video/mp4',
-   *   size:     file.size,
-   *   isPublic: true,
+   * const { uploadUrl, path: p } = await storage.getUploadUrl({
+   *   path: 'videos/intro.mp4', mimeType: 'video/mp4', size: file.size,
    * });
-   * await storage.uploadToSignedUrl(uploadUrl, file, 'video/mp4', pct => console.log(pct + '%'));
-   * const result = await storage.confirmUpload({ path: confirmedPath, mimeType: 'video/mp4', isPublic: true });
+   * await storage.uploadToSignedUrl(uploadUrl, file, 'video/mp4', pct => setProgress(pct));
+   * const result = await storage.confirmUpload({ path: p, mimeType: 'video/mp4' });
    * ```
    */
   async getUploadUrl(opts) {
     const { expiresInSeconds, ...rest } = opts;
-    const result = await this.http.request(`${this.basePath}/upload-url`, {
+    const result = await this.http.request(STORAGE.uploadUrl, {
       method: "POST",
       body: { isPublic: false, overwrite: false, expiresIn: expiresInSeconds ?? 900, ...rest },
       headers: this.authHeaders
@@ -793,17 +1045,20 @@ var StorageManager = class {
     };
   }
   /**
-   * Step 2 — upload data directly to a signed GCS URL.
-   * Supports progress tracking in browser environments.
+   * Step 2 — upload data directly to the signed GCS URL.
+   * Supports progress tracking in browser environments via XHR.
    */
   async uploadToSignedUrl(signedUrl, data, mimeType, onProgress) {
     await this.http.putToSignedUrl(signedUrl, data, mimeType, onProgress);
   }
   /**
-   * Step 3 — confirm a direct upload and register metadata on the server.
+   * Step 3 — confirm a direct upload and register metadata server-side.
+   *
+   * Server: POST /storage/confirm
+   * Body: { path, mimeType, isPublic? }
    */
   async confirmUpload(opts) {
-    const result = await this.http.request(`${this.basePath}/confirm`, {
+    const result = await this.http.request(STORAGE.confirm, {
       method: "POST",
       body: { isPublic: false, ...opts },
       headers: this.authHeaders
@@ -812,26 +1067,17 @@ var StorageManager = class {
   }
   // ─── Batch Upload ─────────────────────────────────────────────────────────
   /**
-   * Get signed upload URLs for multiple files at once (max 50).
-   * Server returns `{ succeeded, failed }` — only succeeded items have URLs.
+   * Get signed upload URLs for up to 50 files at once.
    *
-   * @example
-   * ```ts
-   * const { files } = await storage.getBatchUploadUrls([
-   *   { path: 'images/a.jpg', mimeType: 'image/jpeg', size: 204800 },
-   *   { path: 'images/b.jpg', mimeType: 'image/jpeg', size: 153600 },
-   * ]);
-   * for (const f of files) {
-   *   await storage.uploadToSignedUrl(f.uploadUrl, blobs[f.index], f.mimeType);
-   *   await storage.confirmUpload({ path: f.path, mimeType: f.mimeType });
-   * }
-   * ```
+   * Server: POST /storage/batch-upload-urls
+   * Body: { files: [...], expiresIn? }
    */
   async getBatchUploadUrls(files) {
-    const result = await this.http.request(
-      `${this.basePath}/batch-upload-urls`,
-      { method: "POST", body: { files }, headers: this.authHeaders }
-    );
+    const result = await this.http.request(STORAGE.batchUploadUrls, {
+      method: "POST",
+      body: { files },
+      headers: this.authHeaders
+    });
     return {
       files: result.succeeded.map((f) => ({
         index: f.index,
@@ -845,13 +1091,16 @@ var StorageManager = class {
   }
   /**
    * Confirm multiple direct uploads at once.
-   * Returns both succeeded and failed results.
+   *
+   * Server: POST /storage/batch-confirm
+   * Body: { files: [{ path, mimeType, isPublic? }] }
    */
   async batchConfirmUploads(items) {
-    const result = await this.http.request(
-      `${this.basePath}/batch-confirm`,
-      { method: "POST", body: { files: items }, headers: this.authHeaders }
-    );
+    const result = await this.http.request(STORAGE.batchConfirm, {
+      method: "POST",
+      body: { files: items },
+      headers: this.authHeaders
+    });
     return {
       succeeded: result.succeeded.map(toUploadResult),
       failed: result.failed
@@ -861,32 +1110,28 @@ var StorageManager = class {
   /**
    * Download a private file as an ArrayBuffer.
    * For public files, use the `publicUrl` directly — no SDK needed.
+   *
+   * Server: GET /storage/download/:path  (requires X-Storage-Key)
    */
   async download(path) {
     const encoded = path.split("/").map(encodeURIComponent).join("/");
-    return this.http.request(`${this.basePath}/download/${encoded}`, {
+    return this.http.request(STORAGE.download(encoded), {
       method: "GET",
       headers: this.authHeaders
     });
   }
   /**
-   * 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.
+   * Download up to 20 files at once. Returns base64-encoded content.
    *
-   * @example
-   * ```ts
-   * const { succeeded, failed } = await storage.batchDownload(['docs/a.pdf', 'docs/b.pdf']);
-   * for (const f of succeeded) {
-   *   const bytes = Buffer.from(f.content, 'base64');
-   * }
-   * ```
+   * Server: POST /storage/batch-download
+   * Body: { paths, concurrency? }
    */
-  async batchDownload(paths) {
-    const result = await this.http.request(
-      `${this.basePath}/batch-download`,
-      { method: "POST", body: { paths }, headers: this.authHeaders }
-    );
+  async batchDownload(paths, concurrency = 5) {
+    const result = await this.http.request(STORAGE.batchDownload, {
+      method: "POST",
+      body: { paths, concurrency },
+      headers: this.authHeaders
+    });
     return {
       succeeded: result.succeeded.map((f) => ({
         index: f.index,
@@ -906,7 +1151,8 @@ var StorageManager = class {
   // ─── List ─────────────────────────────────────────────────────────────────
   /**
    * List files and folders at a given path prefix.
-   * Returns separate `files` and `folders` arrays for easy consumption.
+   *
+   * Server: GET /storage/list?prefix=&limit=&cursor=
    *
    * @example
    * ```ts
@@ -920,7 +1166,7 @@ var StorageManager = class {
     if (opts.limit) params.set("limit", String(opts.limit));
     if (opts.cursor) params.set("cursor", opts.cursor);
     const qs = params.toString() ? `?${params}` : "";
-    const result = await this.http.request(`${this.basePath}/list${qs}`, {
+    const result = await this.http.request(`${STORAGE.list}${qs}`, {
       method: "GET",
       headers: this.authHeaders
     });
@@ -928,11 +1174,8 @@ var StorageManager = class {
       const files = [];
       const folders = [];
       for (const item of result.items) {
-        if (item.type === "folder") {
-          folders.push(item.path);
-        } else {
-          files.push(item);
-        }
+        if (item.type === "folder") folders.push(item.path);
+        else files.push(item);
       }
       return {
         files,
@@ -950,14 +1193,16 @@ var StorageManager = class {
   }
   // ─── Metadata ─────────────────────────────────────────────────────────────
   /**
-   * Get metadata for a file: size, MIME type, visibility, URLs.
+   * Get file metadata: size, MIME type, visibility, URLs.
+   *
+   * Server: GET /storage/metadata/:path
    */
   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 }
-    );
+    const result = await this.http.request(STORAGE.metadata(encoded), {
+      method: "GET",
+      headers: this.authHeaders
+    });
     return {
       path: result.path,
       size: result.size,
@@ -972,15 +1217,18 @@ var StorageManager = class {
   // ─── Signed URL ───────────────────────────────────────────────────────────
   /**
    * Generate a time-limited download URL for a private file.
-   * Can be shared externally without requiring an `X-Storage-Key`.
+   * Can be shared externally — no X-Storage-Key required to access.
    *
-   * > Note: Downloads via signed URLs bypass the server — download stats are NOT tracked.
+   * Note: Downloads via signed URLs bypass the server — stats are NOT tracked.
+   *
+   * Server: POST /storage/signed-url
+   * Body: { path, expiresIn? }
    *
    * @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`, {
+    const result = await this.http.request(STORAGE.signedUrl, {
       method: "POST",
       body: { path, expiresIn },
       headers: this.authHeaders
@@ -994,10 +1242,13 @@ var StorageManager = class {
   }
   // ─── Visibility ───────────────────────────────────────────────────────────
   /**
-   * Change a file's visibility between public and private after upload.
+   * Change a file's visibility between public and private.
+   *
+   * Server: PATCH /storage/visibility
+   * Body: { path, isPublic }
    */
   async setVisibility(path, isPublic) {
-    const result = await this.http.request(`${this.basePath}/visibility`, {
+    const result = await this.http.request(STORAGE.visibility, {
       method: "PATCH",
       body: { path, isPublic },
       headers: this.authHeaders
@@ -1010,53 +1261,95 @@ var StorageManager = class {
     };
   }
   // ─── Folder Operations ────────────────────────────────────────────────────
+  /**
+   * Create a folder (empty GCS object used as a prefix marker).
+   *
+   * Server: POST /storage/folder
+   * Body: { path }
+   */
   async createFolder(path) {
-    const result = await this.http.request(
-      `${this.basePath}/folder`,
-      { method: "POST", body: { path }, headers: this.authHeaders }
-    );
+    const result = await this.http.request(STORAGE.folder, {
+      method: "POST",
+      body: { path },
+      headers: this.authHeaders
+    });
     return { path: result.path };
   }
   // ─── File Operations ──────────────────────────────────────────────────────
+  /**
+   * Permanently delete a file.
+   *
+   * Server: DELETE /storage/file
+   * Body: { path }
+   */
   async deleteFile(path) {
-    await this.http.request(`${this.basePath}/file`, {
+    await this.http.request(STORAGE.file, {
       method: "DELETE",
       body: { path },
       headers: this.authHeaders
     });
   }
+  /**
+   * Recursively delete a folder and all its contents.
+   *
+   * Server: DELETE /storage/folder
+   * Body: { path }
+   */
   async deleteFolder(path) {
-    await this.http.request(`${this.basePath}/folder`, {
+    await this.http.request(STORAGE.folderDelete, {
       method: "DELETE",
       body: { path },
       headers: this.authHeaders
     });
   }
+  /**
+   * Move (rename) a file.
+   *
+   * Server: POST /storage/move
+   * Body: { from, to }
+   */
   async move(from, to) {
-    const result = await this.http.request(
-      `${this.basePath}/move`,
-      { method: "POST", body: { from, to }, headers: this.authHeaders }
-    );
+    const result = await this.http.request(STORAGE.move, {
+      method: "POST",
+      body: { from, to },
+      headers: this.authHeaders
+    });
     return { from: result.from, to: result.to };
   }
+  /**
+   * Copy a file to a new path.
+   *
+   * Server: POST /storage/copy
+   * Body: { from, to }
+   */
   async copy(from, to) {
-    const result = await this.http.request(
-      `${this.basePath}/copy`,
-      { method: "POST", body: { from, to }, headers: this.authHeaders }
-    );
+    const result = await this.http.request(STORAGE.copy, {
+      method: "POST",
+      body: { from, to },
+      headers: this.authHeaders
+    });
     return { from: result.from, to: result.to };
   }
   // ─── Stats ────────────────────────────────────────────────────────────────
+  /**
+   * Get usage statistics for this storage key.
+   *
+   * Server: GET /storage/stats
+   */
   async getStats() {
-    const result = await this.http.request(`${this.basePath}/stats`, {
+    const result = await this.http.request(STORAGE.stats, {
       method: "GET",
       headers: this.authHeaders
     });
     return result.stats;
   }
-  // ─── Info (no auth) ───────────────────────────────────────────────────────
+  /**
+   * Get server info (no auth required).
+   *
+   * Server: GET /storage/info
+   */
   async info() {
-    return this.http.request(`${this.basePath}/info`, {
+    return this.http.request(STORAGE.info, {
       method: "GET"
     });
   }
@@ -1106,7 +1399,8 @@ var ScopedStorage = class _ScopedStorage {
   }
   // ─── List ─────────────────────────────────────────────────────────────────
   /**
-   * List files within this scope. The `prefix` option is relative to the scope root.
+   * List files within this scope.
+   * The `prefix` option is relative to the scope root.
    *
    * @example
    * ```ts
@@ -1158,7 +1452,7 @@ var ScopedStorage = class _ScopedStorage {
    *
    * @example
    * ```ts
-   * const user    = storage.scope('users/alice/');
+   * const user     = storage.scope('users/alice/');
    * const userDocs = user.scope('docs/');
    * // Effective prefix: users/alice/docs/
    * ```
@@ -1172,17 +1466,16 @@ var ScopedStorage = class _ScopedStorage {
 var HydrousClient = class {
   constructor(config) {
     this._recordsCache = /* @__PURE__ */ new Map();
-    this._authCache = /* @__PURE__ */ new Map();
     this._analyticsCache = /* @__PURE__ */ new Map();
     this._storageCache = /* @__PURE__ */ new Map();
     if (!config.authKey) {
-      throw new Error("[HydrousDB] authKey is required. Get yours from https://hydrousdb.com/dashboard.");
+      throw new Error("[HydrousDB] authKey is required.");
     }
     if (!config.bucketSecurityKey) {
-      throw new Error("[HydrousDB] bucketSecurityKey is required. Get yours from https://hydrousdb.com/dashboard.");
+      throw new Error("[HydrousDB] bucketSecurityKey is required.");
     }
     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.");
+      throw new Error("[HydrousDB] storageKeys must define at least one key.");
     }
     this.http = new HttpClient(config.baseUrl ?? DEFAULT_BASE_URL);
     this.authKey_ = config.authKey;
@@ -1191,16 +1484,13 @@ var HydrousClient = class {
   }
   // ─── Records ──────────────────────────────────────────────────────────────
   /**
-   * Get a typed records client for the named bucket.
+   * Get a typed RecordsClient for a bucket.
    *
    * @example
    * ```ts
    * interface Post { title: string; published: boolean }
    * const posts = db.records<Post>('blog-posts');
-   * const post  = await posts.create(
-   *   { title: 'Hello', published: false },
-   *   { queryableFields: ['published'] },
-   * );
+   * const post  = await posts.create({ title: 'Hello', published: false });
    * ```
    */
   records(bucketKey) {
@@ -1214,28 +1504,28 @@ var HydrousClient = class {
   }
   // ─── Auth ─────────────────────────────────────────────────────────────────
   /**
-   * Get an auth client for the named user bucket.
+   * Get the AuthClient.
+   * Auth routes are NOT bucket-scoped in the URL — the bucket is determined
+   * server-side from the API key itself.
    *
    * @example
    * ```ts
-   * const auth = db.auth('app-users');
-   * const { user, session } = await auth.login({ email: '…', password: '…' });
+   * const { user, session } = await db.auth().signup({ email: 'alice@example.com', password: 'pw' });
    * ```
    */
-  auth(bucketKey) {
-    if (!this._authCache.has(bucketKey)) {
-      this._authCache.set(bucketKey, new AuthClient(this.http, this.authKey_, bucketKey));
+  auth() {
+    if (!this._authClient) {
+      this._authClient = new AuthClient(this.http, this.authKey_);
     }
-    return this._authCache.get(bucketKey);
+    return this._authClient;
   }
   // ─── Analytics ────────────────────────────────────────────────────────────
   /**
-   * Get an analytics client for the named bucket.
+   * Get an AnalyticsClient for a bucket.
    *
    * @example
    * ```ts
-   * const analytics = db.analytics('orders');
-   * const { count } = await analytics.count();
+   * const { count } = await db.analytics('orders').count();
    * ```
    */
   analytics(bucketKey) {
@@ -1249,18 +1539,19 @@ var HydrousClient = class {
   }
   // ─── Storage ──────────────────────────────────────────────────────────────
   /**
-   * Get a storage manager for the named storage key.
-   * The name must match a key defined in `storageKeys` when calling `createClient`.
+   * Get a StorageManager for a named storage key.
+   * The name must match a key in the `storageKeys` config object.
    *
-   * Attach `.scope(prefix)` to namespace all operations under a path prefix.
+   * Attach `.scope('prefix/')` to get a path-prefixed ScopedStorage.
    *
    * @example
    * ```ts
-   * const avatars  = db.storage('avatars');
-   * const userDocs = db.storage('documents').scope(`users/${userId}/`);
+   * const avatars = db.storage('avatars');
+   * const result  = await avatars.upload(file, 'alice.jpg', { isPublic: true });
    *
-   * await avatars.upload(file, `${userId}.jpg`, { isPublic: true });
-   * await userDocs.upload(pdfBuffer, 'contract.pdf');
+   * // Scoped:
+   * const userFiles = db.storage('documents').scope(`users/${userId}/`);
+   * await userFiles.upload(pdf, 'contract.pdf');
    * ```
    */
   storage(keyName) {
@@ -1286,6 +1577,6 @@ function createClient(config) {
   return new HydrousClient(config);
 }
 
-export { AnalyticsClient, AnalyticsError, AuthClient, AuthError, HydrousClient, HydrousError, NetworkError, RecordError, RecordsClient, ScopedStorage, StorageError, StorageManager, ValidationError, createClient };
+export { ANALYTICS, AUTH, AnalyticsClient, AnalyticsError, AuthClient, AuthError, DEFAULT_BASE_URL, HttpClient, HydrousClient, HydrousError, NetworkError, RECORDS, RecordError, RecordsClient, STORAGE, ScopedStorage, StorageError, StorageManager, ValidationError, createClient };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map