hydrousdb 3.0.2 → 3.5.0

package/dist/index.mjs

@@ -0,0 +1,1581 @@
+// src/utils/errors.ts
+var HydrousError = class extends Error {
+  constructor(message, code, status, requestId, details) {
+    super(message);
+    this.name = "HydrousError";
+    this.code = code;
+    this.status = status;
+    this.requestId = requestId;
+    this.details = details;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+  toString() {
+    return `HydrousError [${this.code}]: ${this.message}`;
+  }
+};
+var AuthError = class extends HydrousError {
+  constructor(message, code, status, requestId, details) {
+    super(message, code, status, requestId, details);
+    this.name = "AuthError";
+  }
+};
+var RecordError = class extends HydrousError {
+  constructor(message, code, status, requestId, details) {
+    super(message, code, status, requestId, details);
+    this.name = "RecordError";
+  }
+};
+var StorageError = class extends HydrousError {
+  constructor(message, code, status, requestId) {
+    super(message, code, status, requestId);
+    this.name = "StorageError";
+  }
+};
+var AnalyticsError = class extends HydrousError {
+  constructor(message, code, status, requestId) {
+    super(message, code, status, requestId);
+    this.name = "AnalyticsError";
+  }
+};
+var ValidationError = class extends HydrousError {
+  constructor(message, details) {
+    super(message, "VALIDATION_ERROR", 400, void 0, details);
+    this.name = "ValidationError";
+  }
+};
+var NetworkError = class extends HydrousError {
+  constructor(message, cause) {
+    super(message, "NETWORK_ERROR");
+    this.name = "NetworkError";
+    if (cause !== void 0) this.cause = cause;
+  }
+};
+
+// src/utils/http.ts
+var DEFAULT_BASE_URL = "https://db-api-82687684612.us-central1.run.app";
+var HttpClient = class {
+  constructor(baseUrl) {
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+  }
+  // ─── Core request ──────────────────────────────────────────────────────────
+  async request(path, options) {
+    const url = `${this.baseUrl}${path}`;
+    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: options.method,
+        headers,
+        body
+      });
+    } catch (err) {
+      throw new NetworkError(
+        `Network request failed: ${err instanceof Error ? err.message : String(err)}`,
+        err
+      );
+    }
+    const contentType = response.headers.get("content-type") ?? "";
+    if (!contentType.includes("application/json")) {
+      if (!response.ok) {
+        throw new HydrousError(
+          `Request failed with status ${response.status}`,
+          "REQUEST_FAILED",
+          response.status
+        );
+      }
+      return response.arrayBuffer();
+    }
+    let data;
+    try {
+      data = await response.json();
+    } catch {
+      throw new HydrousError("Failed to parse response JSON", "PARSE_ERROR", response.status);
+    }
+    if (!response.ok) {
+      throw new HydrousError(
+        data["error"] || data["message"] || `Request failed with status ${response.status}`,
+        data["code"] || "REQUEST_FAILED",
+        response.status,
+        data["requestId"],
+        data["details"]
+      );
+    }
+    return data;
+  }
+  // ─── Convenience wrappers ─────────────────────────────────────────────────
+  get(path, apiKey, extraHeaders) {
+    return this.request(path, {
+      method: "GET",
+      headers: apiKey ? { "X-Api-Key": apiKey, ...extraHeaders } : { ...extraHeaders }
+    });
+  }
+  post(path, apiKey, body) {
+    return this.request(path, {
+      method: "POST",
+      body,
+      headers: { "X-Api-Key": apiKey }
+    });
+  }
+  put(path, apiKey, body) {
+    return this.request(path, {
+      method: "PUT",
+      body,
+      headers: { "X-Api-Key": apiKey }
+    });
+  }
+  patch(path, apiKey, body) {
+    return this.request(path, {
+      method: "PATCH",
+      body,
+      headers: { "X-Api-Key": apiKey }
+    });
+  }
+  delete(path, apiKey, body) {
+    return this.request(path, {
+      method: "DELETE",
+      body,
+      headers: { "X-Api-Key": apiKey }
+    });
+  }
+  /**
+   * 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;
+    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));
+        };
+        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);
+        xhr.send(body);
+      });
+    } 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);
+      }
+    }
+  }
+};
+
+// 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) {
+    this.http = http;
+    this.authKey = authKey;
+  }
+  post(path, body) {
+    return this.http.post(path, this.authKey, body);
+  }
+  get(path, query, extraHeaders) {
+    const qs = query && Object.keys(query).length ? "?" + new URLSearchParams(query).toString() : "";
+    return this.http.get(`${path}${qs}`, this.authKey, extraHeaders);
+  }
+  patch(path, body) {
+    return this.http.patch(path, this.authKey, body);
+  }
+  // ─── 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(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(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(AUTH.signout, options);
+  }
+  // ─── 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(
+      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: "",
+      createdAt: Date.now(),
+      expiresAt: s.expiresAt,
+      refreshToken: s.refreshToken,
+      refreshExpiresAt: s.expiresAt
+    };
+  }
+  // ─── User Profile ─────────────────────────────────────────────────────────
+  /**
+   * 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(
+      AUTH.updateUser,
+      { sessionId, userId, updates }
+    );
+    return result.data;
+  }
+  /**
+   * 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 ─────────────────────────────────────────────────────
+  /**
+   * 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(
+      `${AUTH.listUsers}?${new URLSearchParams(params)}`,
+      {
+        method: "GET",
+        headers: { "X-Api-Key": this.authKey, "X-Session-Id": sessionId }
+      }
+    );
+    return {
+      users: result.data ?? [],
+      hasMore: result.meta?.hasMore ?? result.hasMore ?? false,
+      nextCursor: result.meta?.nextCursor ?? result.nextCursor ?? null
+    };
+  }
+  /**
+   * 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(
+      `${AUTH.hardDeleteUser}?userId=${encodeURIComponent(userId)}`,
+      {
+        method: "DELETE",
+        body: { sessionId },
+        headers: { "X-Api-Key": this.authKey }
+      }
+    );
+  }
+  /**
+   * 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(
+      AUTH.bulkDeleteUsers,
+      {
+        method: "DELETE",
+        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(AUTH.accountLock, options);
+    return result.data;
+  }
+  /**
+   * 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 ──────────────────────────────────────────────────
+  /**
+   * 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) {
+    await this.post(AUTH.passwordChange, {
+      sessionId: options.sessionId,
+      userId: options.userId,
+      oldPassword: options.currentPassword,
+      // server field is `oldPassword`
+      newPassword: options.newPassword
+    });
+  }
+  /**
+   * 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 });
+  }
+  /**
+   * 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 ───────────────────────────────────────────────────
+  /**
+   * 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 });
+  }
+  /**
+   * 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
+      }
+    };
+  }
+};
+
+// src/utils/query.ts
+function buildQueryParams(options = {}) {
+  const params = new URLSearchParams();
+  if (options.limit !== void 0) params.set("limit", String(options.limit));
+  if (options.offset !== void 0) params.set("offset", String(options.offset));
+  if (options.orderBy !== void 0) params.set("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("cursor", options.startAfter);
+  if (options.startAt !== void 0) params.set("cursor", options.startAt);
+  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) {
+    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}` : "";
+}
+function guessMimeType(filename) {
+  const ext = filename.split(".").pop()?.toLowerCase();
+  const map = {
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    png: "image/png",
+    gif: "image/gif",
+    webp: "image/webp",
+    svg: "image/svg+xml",
+    pdf: "application/pdf",
+    mp4: "video/mp4",
+    webm: "video/webm",
+    mp3: "audio/mpeg",
+    wav: "audio/wav",
+    txt: "text/plain",
+    html: "text/html",
+    css: "text/css",
+    js: "application/javascript",
+    ts: "application/typescript",
+    json: "application/json",
+    xml: "application/xml",
+    zip: "application/zip",
+    csv: "text/csv",
+    xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+  };
+  return map[ext ?? ""] ?? "application/octet-stream";
+}
+function assertSafeName(name, label = "name") {
+  if (!/^[a-zA-Z_][a-zA-Z0-9_.\-]{0,200}$/.test(name)) {
+    throw new Error(
+      `Invalid ${label} "${name}". Must start with a letter or underscore and contain only letters, numbers, underscores, dots, or hyphens.`
+    );
+  }
+}
+
+// src/records/client.ts
+var RecordsClient = class {
+  constructor(http, bucketSecurityKey, bucketKey) {
+    assertSafeName(bucketKey, "bucketKey");
+    this.http = http;
+    this.bucketKey = bucketKey;
+    this.apiKey = bucketSecurityKey;
+  }
+  // ─── Single Record Operations ─────────────────────────────────────────────
+  /**
+   * Create a new record (auto-generated ID) or upsert by `customRecordId`.
+   *
+   * Server: POST /api/:bucketKey
+   * Body: { values, queryableFields?, userEmail?, customRecordId? }
+   * Returns 201 for new records, 200 for upserts.
+   *
+   * @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(
+      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(
+      `${RECORDS.bucket(this.bucketKey)}?recordId=${encodeURIComponent(id)}`,
+      this.apiKey
+    );
+    return result.data;
+  }
+  /**
+   * 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 { 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(
+      RECORDS.bucket(this.bucketKey),
+      this.apiKey,
+      body
+    );
+    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(
+      `${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 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 results = await posts.batchCreate(
+   *   [{ title: 'A' }, { title: 'B' }],
+   *   { queryableFields: ['title'] },
+   * );
+   * ```
+   */
+  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(
+      RECORDS.batchInsert(this.bucketKey),
+      this.apiKey,
+      body
+    );
+    return {
+      results: result.data ?? [],
+      errors: result.errors ?? [],
+      successful: result.meta?.successful ?? (result.data?.length ?? 0),
+      failed: result.meta?.failed ?? 0
+    };
+  }
+  /**
+   * Update up to 500 records in one request.
+   *
+   * Server: POST /api/:bucketKey/batch/update
+   * Body: { updates: [{ recordId, values }], userEmail? }
+   */
+  async batchUpdate(updates, userEmail) {
+    const body = { updates };
+    if (userEmail) body["userEmail"] = userEmail;
+    const result = await this.http.post(
+      RECORDS.batchUpdate(this.bucketKey),
+      this.apiKey,
+      body
+    );
+    return {
+      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 filters, sorting, and cursor-based pagination.
+   *
+   * Server: GET /api/:bucketKey?field=value&field[op]=value&limit=&sortBy=&sortOrder=&cursor=
+   *
+   * @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(
+      `${RECORDS.bucket(this.bucketKey)}${qs}`,
+      this.apiKey
+    );
+    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
+    };
+  }
+  /**
+   * Retrieve all records matching options (no filter support — use `query()` for filters).
+   */
+  async getAll(options = {}) {
+    const { records } = await this.query(options);
+    return records;
+  }
+};
+
+// src/analytics/client.ts
+var AnalyticsClient = class {
+  constructor(http, bucketSecurityKey, bucketKey) {
+    assertSafeName(bucketKey, "bucketKey");
+    this.http = http;
+    this.bucketSecurityKey = bucketSecurityKey;
+    this.bucketKey = bucketKey;
+  }
+  async run(query) {
+    const result = await this.http.post(
+      ANALYTICS.query(this.bucketKey),
+      this.bucketSecurityKey,
+      query
+    );
+    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. 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 });
+  }
+  /** 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
+    });
+  }
+  /** 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 (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.
+   * `metrics` must have valid `field` and `name` (used as BigQuery column aliases).
+   */
+  async multiMetric(opts) {
+    opts.metrics.forEach((m) => {
+      assertSafeName(m.field, "metric.field");
+      assertSafeName(m.name, "metric.name");
+    });
+    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`.
+   * System buckets (`users`, `_sys_*`) are blocked server-side.
+   */
+  async crossBucket(opts) {
+    assertSafeName(opts.field, "field");
+    opts.bucketKeys.forEach((k) => assertSafeName(k, "bucketKey"));
+    return this.run({ queryType: "crossBucket", aggregation: "sum", ...opts });
+  }
+  /**
+   * Raw query — escape hatch when the typed helpers don't cover your case.
+   */
+  async query(query) {
+    const data = await this.run(query);
+    return { queryType: query.queryType, data };
+  }
+};
+
+// 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.http = http;
+    this.storageKey = storageKey;
+  }
+  get authHeaders() {
+    return { "X-Storage-Key": this.storageKey };
+  }
+  // ─── Upload: Server-buffered ──────────────────────────────────────────────
+  /**
+   * 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
+   * const result = await storage.upload(file, 'avatars/alice.jpg', { isPublic: true });
+   * console.log(result.publicUrl);
+   * ```
+   */
+  async upload(data, path, options = {}) {
+    const { isPublic = false, overwrite = false, mimeType } = options;
+    const mime = mimeType ?? guessMimeType(path);
+    const formData = new FormData();
+    const blob = data instanceof Blob ? data : new Blob([data], { type: mime });
+    formData.append("file", blob, path.split("/").pop() ?? "file");
+    formData.append("path", path);
+    formData.append("mimeType", mime);
+    formData.append("isPublic", String(isPublic));
+    formData.append("overwrite", String(overwrite));
+    const result = await this.http.request(STORAGE.upload, {
+      method: "POST",
+      rawBody: formData,
+      headers: this.authHeaders
+    });
+    return toUploadResult(result);
+  }
+  /**
+   * Upload raw string or JSON data directly as a file.
+   *
+   * Server: POST /storage/upload-raw
+   * Body: { path, content, mimeType?, isPublic?, overwrite? }
+   *
+   * @example
+   * ```ts
+   * await storage.uploadRaw({ theme: 'dark' }, 'settings/config.json');
+   * ```
+   */
+  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(STORAGE.uploadRaw, {
+      method: "POST",
+      body: { path, content, mimeType, isPublic, overwrite },
+      headers: this.authHeaders
+    });
+    return toUploadResult(result);
+  }
+  // ─── Upload: Direct-to-GCS (recommended for large files / progress) ───────
+  /**
+   * 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: p } = await storage.getUploadUrl({
+   *   path: 'videos/intro.mp4', mimeType: 'video/mp4', size: file.size,
+   * });
+   * 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(STORAGE.uploadUrl, {
+      method: "POST",
+      body: { isPublic: false, overwrite: false, expiresIn: expiresInSeconds ?? 900, ...rest },
+      headers: this.authHeaders
+    });
+    return {
+      uploadUrl: result.uploadUrl,
+      path: result.path,
+      mimeType: result.mimeType,
+      expiresAt: result.expiresAt,
+      expiresIn: result.expiresIn
+    };
+  }
+  /**
+   * 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 server-side.
+   *
+   * Server: POST /storage/confirm
+   * Body: { path, mimeType, isPublic? }
+   */
+  async confirmUpload(opts) {
+    const result = await this.http.request(STORAGE.confirm, {
+      method: "POST",
+      body: { isPublic: false, ...opts },
+      headers: this.authHeaders
+    });
+    return toUploadResult(result);
+  }
+  // ─── Batch Upload ─────────────────────────────────────────────────────────
+  /**
+   * Get signed upload URLs for up to 50 files at once.
+   *
+   * Server: POST /storage/batch-upload-urls
+   * Body: { files: [...], expiresIn? }
+   */
+  async getBatchUploadUrls(files) {
+    const result = await this.http.request(STORAGE.batchUploadUrls, {
+      method: "POST",
+      body: { files },
+      headers: this.authHeaders
+    });
+    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.
+   *
+   * Server: POST /storage/batch-confirm
+   * Body: { files: [{ path, mimeType, isPublic? }] }
+   */
+  async batchConfirmUploads(items) {
+    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
+    };
+  }
+  // ─── Download ─────────────────────────────────────────────────────────────
+  /**
+   * 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(STORAGE.download(encoded), {
+      method: "GET",
+      headers: this.authHeaders
+    });
+  }
+  /**
+   * Download up to 20 files at once. Returns base64-encoded content.
+   *
+   * Server: POST /storage/batch-download
+   * Body: { paths, concurrency? }
+   */
+  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,
+        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.
+   *
+   * Server: GET /storage/list?prefix=&limit=&cursor=
+   *
+   * @example
+   * ```ts
+   * const { files, folders, hasMore, nextCursor } = await storage.list({ prefix: 'avatars/', limit: 20 });
+   * const page2 = await storage.list({ prefix: 'avatars/', cursor: nextCursor });
+   * ```
+   */
+  async list(opts = {}) {
+    const params = new URLSearchParams();
+    if (opts.prefix) params.set("prefix", opts.prefix);
+    if (opts.limit) params.set("limit", String(opts.limit));
+    if (opts.cursor) params.set("cursor", opts.cursor);
+    const qs = params.toString() ? `?${params}` : "";
+    const result = await this.http.request(`${STORAGE.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 ?? false,
+      nextCursor: result.nextCursor ?? void 0
+    };
+  }
+  // ─── Metadata ─────────────────────────────────────────────────────────────
+  /**
+   * 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(STORAGE.metadata(encoded), {
+      method: "GET",
+      headers: this.authHeaders
+    });
+    return {
+      path: result.path,
+      size: result.size,
+      mimeType: result.mimeType,
+      isPublic: result.isPublic,
+      publicUrl: result.publicUrl,
+      downloadUrl: result.downloadUrl,
+      createdAt: result.createdAt,
+      updatedAt: result.updatedAt
+    };
+  }
+  // ─── Signed URL ───────────────────────────────────────────────────────────
+  /**
+   * Generate a time-limited download URL for a private file.
+   * Can be shared externally — no X-Storage-Key required to access.
+   *
+   * 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(STORAGE.signedUrl, {
+      method: "POST",
+      body: { path, expiresIn },
+      headers: this.authHeaders
+    });
+    return {
+      signedUrl: result.signedUrl,
+      expiresAt: result.expiresAt,
+      expiresIn: result.expiresIn,
+      path: result.path
+    };
+  }
+  // ─── Visibility ───────────────────────────────────────────────────────────
+  /**
+   * Change a file's visibility between public and private.
+   *
+   * Server: PATCH /storage/visibility
+   * Body: { path, isPublic }
+   */
+  async setVisibility(path, isPublic) {
+    const result = await this.http.request(STORAGE.visibility, {
+      method: "PATCH",
+      body: { path, isPublic },
+      headers: this.authHeaders
+    });
+    return {
+      path: result.path,
+      isPublic: result.isPublic,
+      publicUrl: result.publicUrl,
+      downloadUrl: result.downloadUrl
+    };
+  }
+  // ─── Folder Operations ────────────────────────────────────────────────────
+  /**
+   * Create a folder (empty GCS object used as a prefix marker).
+   *
+   * Server: POST /storage/folder
+   * Body: { path }
+   */
+  async createFolder(path) {
+    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(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(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(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(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(STORAGE.stats, {
+      method: "GET",
+      headers: this.authHeaders
+    });
+    return result.stats;
+  }
+  /**
+   * Get server info (no auth required).
+   *
+   * Server: GET /storage/info
+   */
+  async info() {
+    return this.http.request(STORAGE.info, {
+      method: "GET"
+    });
+  }
+};
+
+// src/storage/scoped.ts
+var ScopedStorage = class _ScopedStorage {
+  constructor(manager, prefix) {
+    this.manager = manager;
+    this.prefix = prefix.endsWith("/") ? prefix : `${prefix}/`;
+  }
+  p(path) {
+    return `${this.prefix}${path.replace(/^\/+/, "")}`;
+  }
+  // ─── Upload ───────────────────────────────────────────────────────────────
+  async upload(data, path, options = {}) {
+    return this.manager.upload(data, this.p(path), options);
+  }
+  async uploadRaw(data, path, options = {}) {
+    return this.manager.uploadRaw(data, this.p(path), options);
+  }
+  async getUploadUrl(opts) {
+    return this.manager.getUploadUrl({ ...opts, path: this.p(opts.path) });
+  }
+  async uploadToSignedUrl(signedUrl, data, mimeType, onProgress) {
+    return this.manager.uploadToSignedUrl(signedUrl, data, mimeType, onProgress);
+  }
+  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 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/' });
+   * ```
+   */
+  async list(opts = {}) {
+    return this.manager.list({
+      ...opts,
+      prefix: this.p(opts.prefix ?? "")
+    });
+  }
+  // ─── Metadata & URLs ──────────────────────────────────────────────────────
+  async getMetadata(path) {
+    return this.manager.getMetadata(this.p(path));
+  }
+  async getSignedUrl(path, expiresIn = 3600) {
+    return this.manager.getSignedUrl(this.p(path), expiresIn);
+  }
+  async setVisibility(path, isPublic) {
+    return this.manager.setVisibility(this.p(path), isPublic);
+  }
+  // ─── Folder Operations ────────────────────────────────────────────────────
+  async createFolder(path) {
+    return this.manager.createFolder(this.p(path));
+  }
+  // ─── File Operations ──────────────────────────────────────────────────────
+  async deleteFile(path) {
+    return this.manager.deleteFile(this.p(path));
+  }
+  async deleteFolder(path) {
+    return this.manager.deleteFolder(this.p(path));
+  }
+  async move(from, to) {
+    return this.manager.move(this.p(from), this.p(to));
+  }
+  async copy(from, to) {
+    return this.manager.copy(this.p(from), this.p(to));
+  }
+  // ─── Stats ────────────────────────────────────────────────────────────────
+  async getStats() {
+    return this.manager.getStats();
+  }
+  // ─── Nesting ──────────────────────────────────────────────────────────────
+  /**
+   * Create a deeper scope within this one.
+   *
+   * @example
+   * ```ts
+   * const user     = storage.scope('users/alice/');
+   * const userDocs = user.scope('docs/');
+   * // Effective prefix: users/alice/docs/
+   * ```
+   */
+  scope(subPrefix) {
+    return new _ScopedStorage(this.manager, this.p(subPrefix));
+  }
+};
+
+// src/client.ts
+var HydrousClient = class {
+  constructor(config) {
+    this._recordsCache = /* @__PURE__ */ new Map();
+    this._analyticsCache = /* @__PURE__ */ new Map();
+    this._storageCache = /* @__PURE__ */ new Map();
+    if (!config.authKey) {
+      throw new Error("[HydrousDB] authKey is required.");
+    }
+    if (!config.bucketSecurityKey) {
+      throw new Error("[HydrousDB] bucketSecurityKey is required.");
+    }
+    if (!config.storageKeys || Object.keys(config.storageKeys).length === 0) {
+      throw new Error("[HydrousDB] storageKeys must define at least one key.");
+    }
+    this.http = new HttpClient(config.baseUrl ?? DEFAULT_BASE_URL);
+    this.authKey_ = config.authKey;
+    this.bucketSecurityKey_ = config.bucketSecurityKey;
+    this.storageKeys_ = config.storageKeys;
+  }
+  // ─── Records ──────────────────────────────────────────────────────────────
+  /**
+   * 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 });
+   * ```
+   */
+  records(bucketKey) {
+    if (!this._recordsCache.has(bucketKey)) {
+      this._recordsCache.set(
+        bucketKey,
+        new RecordsClient(this.http, this.bucketSecurityKey_, bucketKey)
+      );
+    }
+    return this._recordsCache.get(bucketKey);
+  }
+  // ─── Auth ─────────────────────────────────────────────────────────────────
+  /**
+   * 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 { user, session } = await db.auth().signup({ email: 'alice@example.com', password: 'pw' });
+   * ```
+   */
+  auth() {
+    if (!this._authClient) {
+      this._authClient = new AuthClient(this.http, this.authKey_);
+    }
+    return this._authClient;
+  }
+  // ─── Analytics ────────────────────────────────────────────────────────────
+  /**
+   * Get an AnalyticsClient for a bucket.
+   *
+   * @example
+   * ```ts
+   * const { count } = await db.analytics('orders').count();
+   * ```
+   */
+  analytics(bucketKey) {
+    if (!this._analyticsCache.has(bucketKey)) {
+      this._analyticsCache.set(
+        bucketKey,
+        new AnalyticsClient(this.http, this.bucketSecurityKey_, bucketKey)
+      );
+    }
+    return this._analyticsCache.get(bucketKey);
+  }
+  // ─── Storage ──────────────────────────────────────────────────────────────
+  /**
+   * Get a StorageManager for a named storage key.
+   * The name must match a key in the `storageKeys` config object.
+   *
+   * Attach `.scope('prefix/')` to get a path-prefixed ScopedStorage.
+   *
+   * @example
+   * ```ts
+   * const avatars = db.storage('avatars');
+   * const result  = await avatars.upload(file, 'alice.jpg', { isPublic: true });
+   *
+   * // Scoped:
+   * const userFiles = db.storage('documents').scope(`users/${userId}/`);
+   * await userFiles.upload(pdf, 'contract.pdf');
+   * ```
+   */
+  storage(keyName) {
+    const ssk = this.storageKeys_[keyName];
+    if (!ssk) {
+      const available = Object.keys(this.storageKeys_).join(", ");
+      throw new Error(
+        `[HydrousDB] Unknown storage key name "${keyName}". Available keys: ${available}. Add it to storageKeys in your createClient() config.`
+      );
+    }
+    if (!this._storageCache.has(keyName)) {
+      this._storageCache.set(keyName, new StorageManager(this.http, ssk));
+    }
+    const mgr = this._storageCache.get(keyName);
+    const extended = mgr;
+    if (!extended.scope) {
+      extended.scope = (prefix) => new ScopedStorage(mgr, prefix);
+    }
+    return extended;
+  }
+};
+function createClient(config) {
+  return new HydrousClient(config);
+}
+
+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