hydrousdb 3.0.0 → 3.0.2

package/dist/index.cjs

@@ -49,28 +49,36 @@ var NetworkError = class extends HydrousError {
   constructor(message, cause) {
     super(message, "NETWORK_ERROR");
     this.name = "NetworkError";
-    this.cause = cause;
+    if (cause) this.cause = cause;
   }
 };
 
 // src/utils/http.ts
 var DEFAULT_BASE_URL = "https://db-api-82687684612.us-central1.run.app";
 var HttpClient = class {
-  constructor(baseUrl, securityKey) {
+  constructor(baseUrl) {
     this.baseUrl = baseUrl.replace(/\/$/, "");
-    this.securityKey = securityKey;
   }
-  async request(path, opts = {}) {
+  async request(path, apiKeyOrOpts, opts = {}) {
+    let apiKey;
+    let resolvedOpts;
+    if (typeof apiKeyOrOpts === "string") {
+      apiKey = apiKeyOrOpts;
+      resolvedOpts = opts;
+    } else {
+      apiKey = void 0;
+      resolvedOpts = apiKeyOrOpts ?? opts;
+    }
     const {
       method = "GET",
       body,
       headers = {},
       rawBody,
       contentType = "application/json"
-    } = opts;
+    } = resolvedOpts;
     const url = `${this.baseUrl}${path}`;
     const reqHeaders = {
-      "X-Api-Key": this.securityKey,
+      ...apiKey ? { "X-Api-Key": apiKey } : {},
       ...headers
     };
     let reqBody = null;
@@ -128,25 +136,26 @@ var HttpClient = class {
     }
     return responseData;
   }
-  get(path, headers) {
-    return this.request(path, { method: "GET", headers });
+  get(path, apiKey, headers) {
+    return this.request(path, apiKey, { method: "GET", headers });
   }
-  post(path, body, headers) {
-    return this.request(path, { method: "POST", body, headers });
+  post(path, apiKey, body, headers) {
+    return this.request(path, apiKey, { method: "POST", body, headers });
   }
-  put(path, body, headers) {
-    return this.request(path, { method: "PUT", body, headers });
+  put(path, apiKey, body, headers) {
+    return this.request(path, apiKey, { method: "PUT", body, headers });
   }
-  patch(path, body, headers) {
-    return this.request(path, { method: "PATCH", body, headers });
+  patch(path, apiKey, body, headers) {
+    return this.request(path, apiKey, { method: "PATCH", body, headers });
   }
-  delete(path, body, headers) {
-    return this.request(path, { method: "DELETE", body, headers });
+  delete(path, apiKey, body, headers) {
+    return this.request(path, apiKey, { method: "DELETE", body, headers });
   }
   async putToSignedUrl(signedUrl, data, mimeType, onProgress) {
-    if (typeof XMLHttpRequest !== "undefined" && onProgress) {
+    const XHR = typeof globalThis["XMLHttpRequest"] !== "undefined" ? globalThis["XMLHttpRequest"] : void 0;
+    if (XHR && onProgress) {
       return new Promise((resolve, reject) => {
-        const xhr = new XMLHttpRequest();
+        const xhr = new XHR();
         xhr.upload.onprogress = (e) => {
           if (e.lengthComputable) {
             onProgress(Math.round(e.loaded / e.total * 100));
@@ -180,280 +189,97 @@ var HttpClient = class {
 
 // src/auth/client.ts
 var AuthClient = class {
-  constructor(http, bucketKey) {
+  constructor(http, authKey, bucketKey) {
     this.http = http;
-    this.bucketKey = bucketKey;
+    this.authKey = authKey;
     this.basePath = `/auth/${bucketKey}`;
   }
+  post(path, body) {
+    return this.http.post(path, this.authKey, body);
+  }
+  get(path) {
+    return this.http.get(path, this.authKey);
+  }
+  patch(path, body) {
+    return this.http.patch(path, this.authKey, body);
+  }
+  delete(path, body) {
+    return this.http.delete(path, this.authKey, body);
+  }
   // ─── Registration & Login ─────────────────────────────────────────────────
-  /**
-   * Register a new user in this bucket.
-   *
-   * @example
-   * ```ts
-   * const { user, session } = await auth.signup({
-   *   email: 'alice@example.com',
-   *   password: 'hunter2',
-   *   fullName: 'Alice Wonderland',
-   *   // Any extra fields are stored on the user record:
-   *   plan: 'pro',
-   * });
-   * ```
-   */
   async signup(options) {
-    const result = await this.http.post(`${this.basePath}/signup`, options);
+    const result = await this.post(`${this.basePath}/signup`, options);
     return { user: result.user, session: result.session };
   }
-  /**
-   * Authenticate an existing user and create a session.
-   * Sessions are valid for 24 hours; use `refreshSession` to extend.
-   *
-   * @example
-   * ```ts
-   * const { user, session } = await auth.login({
-   *   email: 'alice@example.com',
-   *   password: 'hunter2',
-   * });
-   * // Store session.sessionId safely — you'll need it for other calls.
-   * ```
-   */
   async login(options) {
-    const result = await this.http.post(`${this.basePath}/login`, options);
+    const result = await this.post(`${this.basePath}/login`, options);
     return { user: result.user, session: result.session };
   }
-  /**
-   * Invalidate a session (sign out).
-   *
-   * @example
-   * ```ts
-   * await auth.logout({ sessionId: session.sessionId });
-   * ```
-   */
   async logout({ sessionId }) {
-    await this.http.post(`${this.basePath}/logout`, { sessionId });
+    await this.post(`${this.basePath}/logout`, { sessionId });
   }
-  /**
-   * Extend a session using its refresh token.
-   * Returns a new session object.
-   *
-   * @example
-   * ```ts
-   * const newSession = await auth.refreshSession({ refreshToken: session.refreshToken });
-   * ```
-   */
   async refreshSession({ refreshToken }) {
-    const result = await this.http.post(
-      `${this.basePath}/session/refresh`,
-      { refreshToken }
-    );
+    const result = await this.post(`${this.basePath}/session/refresh`, { refreshToken });
     return result.session;
   }
   // ─── User Profile ─────────────────────────────────────────────────────────
-  /**
-   * Fetch a user by their ID.
-   *
-   * @example
-   * ```ts
-   * const user = await auth.getUser({ userId: 'usr_abc123' });
-   * ```
-   */
   async getUser({ userId }) {
-    const result = await this.http.get(`${this.basePath}/user/${userId}`);
+    const result = await this.get(`${this.basePath}/user/${userId}`);
     return result.user;
   }
-  /**
-   * Update fields on a user record. Requires a valid session.
-   *
-   * @example
-   * ```ts
-   * const updated = await auth.updateUser({
-   *   sessionId: session.sessionId,
-   *   userId: user.id,
-   *   data: { fullName: 'Alice Smith', plan: 'enterprise' },
-   * });
-   * ```
-   */
   async updateUser(options) {
     const { sessionId, userId, data } = options;
-    const result = await this.http.patch(
-      `${this.basePath}/user`,
-      { sessionId, userId, ...data }
-    );
+    const result = await this.patch(`${this.basePath}/user`, { sessionId, userId, ...data });
     return result.user;
   }
-  /**
-   * Soft-delete a user. The record is marked deleted but not removed from storage.
-   * Requires a valid session (the user can delete themselves, or an admin can delete any user).
-   *
-   * @example
-   * ```ts
-   * await auth.deleteUser({ sessionId: session.sessionId, userId: user.id });
-   * ```
-   */
   async deleteUser({ sessionId, userId }) {
-    await this.http.delete(`${this.basePath}/user`, { sessionId, userId });
+    await this.delete(`${this.basePath}/user`, { sessionId, userId });
   }
   // ─── Admin Operations ─────────────────────────────────────────────────────
-  /**
-   * List all users in the bucket. **Admin session required.**
-   *
-   * @example
-   * ```ts
-   * const { users, total } = await auth.listUsers({
-   *   sessionId: adminSession.sessionId,
-   *   limit: 50,
-   *   offset: 0,
-   * });
-   * ```
-   */
   async listUsers(options) {
     const { sessionId, limit = 50, offset = 0 } = options;
-    const result = await this.http.post(
+    const result = await this.post(
       `${this.basePath}/users/list`,
       { sessionId, limit, offset }
     );
     return { users: result.users, total: result.total, limit: result.limit, offset: result.offset };
   }
-  /**
-   * Permanently hard-delete a user and all their data. **Admin session required.**
-   * This action is irreversible.
-   *
-   * @example
-   * ```ts
-   * await auth.hardDeleteUser({ sessionId: adminSession.sessionId, userId: user.id });
-   * ```
-   */
   async hardDeleteUser({ sessionId, userId }) {
-    await this.http.delete(`${this.basePath}/user/hard`, { sessionId, userId });
+    await this.delete(`${this.basePath}/user/hard`, { sessionId, userId });
   }
-  /**
-   * Bulk delete multiple users. **Admin session required.**
-   *
-   * @example
-   * ```ts
-   * const result = await auth.bulkDeleteUsers({
-   *   sessionId: adminSession.sessionId,
-   *   userIds: ['usr_a', 'usr_b'],
-   * });
-   * ```
-   */
-  async bulkDeleteUsers({
-    sessionId,
-    userIds
-  }) {
-    const result = await this.http.post(
+  async bulkDeleteUsers({ sessionId, userIds }) {
+    const result = await this.post(
       `${this.basePath}/users/bulk-delete`,
       { sessionId, userIds }
     );
     return { deleted: result.deleted, failed: result.failed };
   }
-  /**
-   * Lock a user account, preventing login. **Admin session required.**
-   *
-   * @param options.duration Lock duration in milliseconds. Defaults to 15 minutes.
-   *
-   * @example
-   * ```ts
-   * await auth.lockAccount({
-   *   sessionId: adminSession.sessionId,
-   *   userId: user.id,
-   *   duration: 60 * 60 * 1000, // 1 hour
-   * });
-   * ```
-   */
-  async lockAccount({
-    sessionId,
-    userId,
-    duration
-  }) {
-    const result = await this.http.post(`${this.basePath}/account/lock`, { sessionId, userId, duration });
+  async lockAccount({ sessionId, userId, duration }) {
+    const result = await this.post(
+      `${this.basePath}/account/lock`,
+      { sessionId, userId, duration }
+    );
     return result.data;
   }
-  /**
-   * Unlock a previously locked user account. **Admin session required.**
-   *
-   * @example
-   * ```ts
-   * await auth.unlockAccount({ sessionId: adminSession.sessionId, userId: user.id });
-   * ```
-   */
-  async unlockAccount({
-    sessionId,
-    userId
-  }) {
-    await this.http.post(`${this.basePath}/account/unlock`, { sessionId, userId });
+  async unlockAccount({ sessionId, userId }) {
+    await this.post(`${this.basePath}/account/unlock`, { sessionId, userId });
   }
   // ─── Password Management ──────────────────────────────────────────────────
-  /**
-   * Change a user's password. The user must supply their current password.
-   *
-   * @example
-   * ```ts
-   * await auth.changePassword({
-   *   sessionId: session.sessionId,
-   *   userId: user.id,
-   *   currentPassword: 'hunter2',
-   *   newPassword: 'correcthorsebatterystaple',
-   * });
-   * ```
-   */
   async changePassword(options) {
-    await this.http.post(`${this.basePath}/password/change`, options);
+    await this.post(`${this.basePath}/password/change`, options);
   }
-  /**
-   * Request a password reset email for a user.
-   * Always returns success to prevent user enumeration.
-   *
-   * @example
-   * ```ts
-   * await auth.requestPasswordReset({ email: 'alice@example.com' });
-   * ```
-   */
   async requestPasswordReset({ email }) {
-    await this.http.post(`${this.basePath}/password/reset/request`, { email });
+    await this.post(`${this.basePath}/password/reset/request`, { email });
   }
-  /**
-   * Complete a password reset using the token from the reset email.
-   *
-   * @example
-   * ```ts
-   * await auth.confirmPasswordReset({
-   *   resetToken: 'tok_from_email',
-   *   newPassword: 'correcthorsebatterystaple',
-   * });
-   * ```
-   */
-  async confirmPasswordReset({
-    resetToken,
-    newPassword
-  }) {
-    await this.http.post(`${this.basePath}/password/reset/confirm`, {
-      resetToken,
-      newPassword
-    });
+  async confirmPasswordReset({ resetToken, newPassword }) {
+    await this.post(`${this.basePath}/password/reset/confirm`, { resetToken, newPassword });
   }
   // ─── Email Verification ───────────────────────────────────────────────────
-  /**
-   * Send (or resend) an email verification message to a user.
-   *
-   * @example
-   * ```ts
-   * await auth.requestEmailVerification({ userId: user.id });
-   * ```
-   */
   async requestEmailVerification({ userId }) {
-    await this.http.post(`${this.basePath}/email/verify/request`, { userId });
+    await this.post(`${this.basePath}/email/verify/request`, { userId });
   }
-  /**
-   * Confirm an email address using the token from the verification email.
-   *
-   * @example
-   * ```ts
-   * await auth.confirmEmailVerification({ verifyToken: 'tok_from_email' });
-   * ```
-   */
   async confirmEmailVerification({ verifyToken }) {
-    await this.http.post(`${this.basePath}/email/verify/confirm`, { verifyToken });
+    await this.post(`${this.basePath}/email/verify/confirm`, { verifyToken });
   }
 };
 
@@ -513,149 +339,62 @@ function assertSafeName(name, label = "name") {
 
 // src/records/client.ts
 var RecordsClient = class {
-  constructor(http, bucketKey) {
+  constructor(http, bucketSecurityKey, bucketKey) {
     assertSafeName(bucketKey, "bucketKey");
     this.http = http;
     this.bucketKey = bucketKey;
+    this.bucketKey_ = bucketSecurityKey;
     this.basePath = `/records/${bucketKey}`;
   }
+  get key() {
+    return this.bucketKey_;
+  }
   // ─── Single Record Operations ─────────────────────────────────────────────
-  /**
-   * Create a new record.
-   *
-   * @example
-   * ```ts
-   * const user = await records.create({
-   *   name: 'Alice',
-   *   email: 'alice@example.com',
-   *   score: 100,
-   * });
-   * console.log(user.id); // "rec_xxxxxxxx"
-   * ```
-   */
   async create(data) {
-    const result = await this.http.post(this.basePath, data);
+    const result = await this.http.post(this.basePath, this.key, data);
     return result.record ?? result.data;
   }
-  /**
-   * Fetch a single record by ID.
-   *
-   * @example
-   * ```ts
-   * const post = await records.get('rec_abc123');
-   * ```
-   */
   async get(id) {
-    const result = await this.http.get(`${this.basePath}/${id}`);
+    const result = await this.http.get(`${this.basePath}/${id}`, this.key);
     return result.record ?? result.data;
   }
-  /**
-   * Overwrite a record entirely (full replace).
-   *
-   * @example
-   * ```ts
-   * const updated = await records.set('rec_abc123', {
-   *   name: 'Alice Updated',
-   *   email: 'alice2@example.com',
-   * });
-   * ```
-   */
   async set(id, data) {
-    const result = await this.http.put(`${this.basePath}/${id}`, data);
+    const result = await this.http.put(`${this.basePath}/${id}`, this.key, data);
     return result.record ?? result.data;
   }
-  /**
-   * Partially update a record (merge by default).
-   *
-   * @example
-   * ```ts
-   * // Merge: only the provided fields are updated
-   * const updated = await records.patch('rec_abc123', { score: 200 });
-   *
-   * // Replace: equivalent to set()
-   * const replaced = await records.patch('rec_abc123', { score: 200 }, { merge: false });
-   * ```
-   */
   async patch(id, data, options = {}) {
     const { merge = true } = options;
     const result = await this.http.patch(
       `${this.basePath}/${id}`,
+      this.key,
       { ...data, _merge: merge }
     );
     return result.record ?? result.data;
   }
-  /**
-   * Delete a record permanently.
-   *
-   * @example
-   * ```ts
-   * await records.delete('rec_abc123');
-   * ```
-   */
   async delete(id) {
-    await this.http.delete(`${this.basePath}/${id}`);
+    await this.http.delete(`${this.basePath}/${id}`, this.key);
   }
   // ─── Batch Operations ─────────────────────────────────────────────────────
-  /**
-   * Create multiple records in one request.
-   *
-   * @example
-   * ```ts
-   * const created = await records.batchCreate([
-   *   { name: 'Alice', score: 100 },
-   *   { name: 'Bob',   score: 200 },
-   * ]);
-   * ```
-   */
   async batchCreate(items) {
     const result = await this.http.post(
       `${this.basePath}/batch`,
+      this.key,
       { records: items }
     );
     return result.records;
   }
-  /**
-   * Delete multiple records by ID in one request.
-   *
-   * @example
-   * ```ts
-   * await records.batchDelete(['rec_a', 'rec_b', 'rec_c']);
-   * ```
-   */
   async batchDelete(ids) {
-    const result = await this.http.post(`${this.basePath}/batch/delete`, { ids });
+    const result = await this.http.post(
+      `${this.basePath}/batch/delete`,
+      this.key,
+      { ids }
+    );
     return { deleted: result.deleted, failed: result.failed };
   }
   // ─── Querying ─────────────────────────────────────────────────────────────
-  /**
-   * Query records with optional filters, sorting, and pagination.
-   *
-   * @example
-   * ```ts
-   * // Simple query
-   * const { records } = await posts.query({ limit: 10 });
-   *
-   * // Filtered query with cursor pagination
-   * const page1 = await posts.query({
-   *   filters: [
-   *     { field: 'status',    op: '==', value: 'published' },
-   *     { field: 'views',     op: '>',  value: 1000 },
-   *   ],
-   *   orderBy: 'createdAt',
-   *   order: 'desc',
-   *   limit: 20,
-   * });
-   *
-   * const page2 = await posts.query({
-   *   filters: [{ field: 'status', op: '==', value: 'published' }],
-   *   limit: 20,
-   *   startAfter: page1.nextCursor,
-   * });
-   * ```
-   */
   async query(options = {}) {
     const qs = buildQueryParams(options);
-    const result = await this.http.get(`${this.basePath}${qs}`);
+    const result = await this.http.get(`${this.basePath}${qs}`, this.key);
     return {
       records: result.records,
       total: result.total,
@@ -663,60 +402,27 @@ var RecordsClient = class {
       nextCursor: result.nextCursor
     };
   }
-  /**
-   * Convenience alias: get all records up to `limit` (default 100).
-   *
-   * @example
-   * ```ts
-   * const allPosts = await posts.getAll({ limit: 500 });
-   * ```
-   */
   async getAll(options = {}) {
     const { records } = await this.query(options);
     return records;
   }
-  /**
-   * Count records matching optional filters.
-   *
-   * @example
-   * ```ts
-   * const total = await posts.count([{ field: 'status', op: '==', value: 'published' }]);
-   * ```
-   */
   async count(filters = []) {
     const result = await this.http.post(
       `${this.basePath}/count`,
+      this.key,
       { filters }
     );
     return result.count;
   }
   // ─── Version History ──────────────────────────────────────────────────────
-  /**
-   * Retrieve the full version history of a record.
-   * Each write creates a new version stored in GCS.
-   *
-   * @example
-   * ```ts
-   * const history = await records.getHistory('rec_abc123');
-   * console.log(history[0].data); // latest version
-   * ```
-   */
   async getHistory(id) {
-    const result = await this.http.get(`${this.basePath}/${id}/history`);
+    const result = await this.http.get(`${this.basePath}/${id}/history`, this.key);
     return result.history;
   }
-  /**
-   * Restore a record to a specific historical version.
-   *
-   * @example
-   * ```ts
-   * const history = await records.getHistory('rec_abc123');
-   * const restored = await records.restoreVersion('rec_abc123', history[2].version);
-   * ```
-   */
   async restoreVersion(id, version) {
     const result = await this.http.post(
       `${this.basePath}/${id}/restore`,
+      this.key,
       { version }
     );
     return result.record ?? result.data;
@@ -725,187 +431,53 @@ var RecordsClient = class {
 
 // src/analytics/client.ts
 var AnalyticsClient = class {
-  constructor(http, bucketKey) {
+  constructor(http, bucketSecurityKey, bucketKey) {
     assertSafeName(bucketKey, "bucketKey");
     this.http = http;
-    this.bucketKey = bucketKey;
+    this.bucketSecurityKey = bucketSecurityKey;
     this.basePath = `/analytics/${bucketKey}`;
   }
-  /** Internal dispatcher — all queries POST to the same endpoint. */
   async run(query) {
-    const result = await this.http.post(this.basePath, query);
+    const result = await this.http.post(
+      this.basePath,
+      this.bucketSecurityKey,
+      query
+    );
     return result.data;
   }
-  // ─── Count ────────────────────────────────────────────────────────────────
-  /**
-   * Count the total number of records in the bucket, with optional date filter.
-   *
-   * @example
-   * ```ts
-   * const { count } = await analytics.count();
-   * // → { count: 4821 }
-   *
-   * // Count only this month's records
-   * const { count } = await analytics.count({
-   *   dateRange: { start: new Date('2025-01-01').getTime(), end: Date.now() },
-   * });
-   * ```
-   */
   async count(opts = {}) {
     return this.run({ queryType: "count", ...opts });
   }
-  // ─── Distribution ─────────────────────────────────────────────────────────
-  /**
-   * Count how many records have each unique value for a given field.
-   * Great for pie charts and bar charts.
-   *
-   * @example
-   * ```ts
-   * const rows = await analytics.distribution({
-   *   field: 'status',
-   *   limit: 10,
-   *   order: 'desc',
-   * });
-   * // → [{ value: 'completed', count: 312 }, { value: 'pending', count: 88 }, ...]
-   * ```
-   */
   async distribution(opts) {
     assertSafeName(opts.field, "field");
     return this.run({ queryType: "distribution", ...opts });
   }
-  // ─── Sum ──────────────────────────────────────────────────────────────────
-  /**
-   * Sum a numeric field, optionally grouped by another field.
-   *
-   * @example
-   * ```ts
-   * // Total revenue
-   * const rows = await analytics.sum({ field: 'amount' });
-   * // → [{ sum: 198432.50 }]
-   *
-   * // Revenue by country
-   * const rows = await analytics.sum({ field: 'amount', groupBy: 'country', limit: 10 });
-   * // → [{ group: 'US', sum: 120000 }, { group: 'UK', sum: 45000 }, ...]
-   * ```
-   */
   async sum(opts) {
     assertSafeName(opts.field, "field");
     if (opts.groupBy) assertSafeName(opts.groupBy, "groupBy");
     return this.run({ queryType: "sum", ...opts });
   }
-  // ─── Time Series ──────────────────────────────────────────────────────────
-  /**
-   * Count records created over time, grouped by a time granularity.
-   * Perfect for line charts and activity graphs.
-   *
-   * @example
-   * ```ts
-   * const rows = await analytics.timeSeries({
-   *   granularity: 'day',
-   *   dateRange: { start: Date.now() - 7 * 86400000, end: Date.now() },
-   * });
-   * // → [{ date: '2025-06-01', count: 42 }, { date: '2025-06-02', count: 67 }, ...]
-   * ```
-   */
   async timeSeries(opts = {}) {
     return this.run({ queryType: "timeSeries", granularity: "day", ...opts });
   }
-  // ─── Field Time Series ────────────────────────────────────────────────────
-  /**
-   * Aggregate a numeric field over time (e.g. daily revenue, hourly signups).
-   *
-   * @example
-   * ```ts
-   * const rows = await analytics.fieldTimeSeries({
-   *   field: 'amount',
-   *   aggregation: 'sum',
-   *   granularity: 'week',
-   * });
-   * // → [{ date: '2025-W22', value: 14230.50 }, ...]
-   * ```
-   */
   async fieldTimeSeries(opts) {
     assertSafeName(opts.field, "field");
-    return this.run({
-      queryType: "fieldTimeSeries",
-      aggregation: "sum",
-      granularity: "day",
-      ...opts
-    });
+    return this.run({ queryType: "fieldTimeSeries", aggregation: "sum", granularity: "day", ...opts });
   }
-  // ─── Top N ────────────────────────────────────────────────────────────────
-  /**
-   * Get the top N values by frequency for a field.
-   * Optionally pair with a `labelField` for human-readable labels.
-   *
-   * @example
-   * ```ts
-   * // Top 5 most purchased products
-   * const rows = await analytics.topN({
-   *   field: 'productId',
-   *   labelField: 'productName',
-   *   n: 5,
-   * });
-   * // → [{ value: 'prod_123', label: 'Widget Pro', count: 892 }, ...]
-   * ```
-   */
   async topN(opts) {
     assertSafeName(opts.field, "field");
     if (opts.labelField) assertSafeName(opts.labelField, "labelField");
     return this.run({ queryType: "topN", n: 10, order: "desc", ...opts });
   }
-  // ─── Field Stats ──────────────────────────────────────────────────────────
-  /**
-   * Get statistical summary (min, max, avg, sum, count, stddev) for a numeric field.
-   *
-   * @example
-   * ```ts
-   * const stats = await analytics.stats({ field: 'orderValue' });
-   * // → { min: 4.99, max: 9999.99, avg: 87.23, sum: 420948.27, count: 4823, stddev: 143.2 }
-   * ```
-   */
   async stats(opts) {
     assertSafeName(opts.field, "field");
     return this.run({ queryType: "stats", ...opts });
   }
-  // ─── Filtered Records ─────────────────────────────────────────────────────
-  /**
-   * Query raw records with filters, field selection, and pagination.
-   * This is the analytics version of `records.query()` but powered by BigQuery.
-   *
-   * @example
-   * ```ts
-   * const { records } = await analytics.records({
-   *   filters: [{ field: 'status', op: '==', value: 'refunded' }],
-   *   selectFields: ['orderId', 'amount', 'createdAt'],
-   *   limit: 50,
-   *   orderBy: 'amount',
-   *   order: 'desc',
-   * });
-   * ```
-   */
   async records(opts = {}) {
     if (opts.orderBy) assertSafeName(opts.orderBy, "orderBy");
     if (opts.selectFields) opts.selectFields.forEach((f) => assertSafeName(f, "selectField"));
     return this.run({ queryType: "records", limit: 100, order: "desc", ...opts });
   }
-  // ─── Multi Metric ─────────────────────────────────────────────────────────
-  /**
-   * Calculate multiple aggregations in a single query.
-   * Ideal for dashboards that need several numbers at once.
-   *
-   * @example
-   * ```ts
-   * const result = await analytics.multiMetric({
-   *   metrics: [
-   *     { field: 'amount',   name: 'totalRevenue', aggregation: 'sum' },
-   *     { field: 'amount',   name: 'avgOrderValue', aggregation: 'avg' },
-   *     { field: 'userId',   name: 'uniqueCustomers', aggregation: 'count' },
-   *   ],
-   * });
-   * // → { totalRevenue: 198432.50, avgOrderValue: 87.23, uniqueCustomers: 2275 }
-   * ```
-   */
   async multiMetric(opts) {
     opts.metrics.forEach((m) => {
       assertSafeName(m.field, "metric.field");
@@ -913,58 +485,14 @@ var AnalyticsClient = class {
     });
     return this.run({ queryType: "multiMetric", ...opts });
   }
-  // ─── Storage Stats ────────────────────────────────────────────────────────
-  /**
-   * Get storage statistics for this bucket: record counts, byte sizes.
-   *
-   * @example
-   * ```ts
-   * const stats = await analytics.storageStats();
-   * // → { totalRecords: 4821, totalBytes: 48293820, avgBytes: 10015, ... }
-   * ```
-   */
   async storageStats(opts = {}) {
     return this.run({ queryType: "storageStats", ...opts });
   }
-  // ─── Cross-Bucket Comparison ──────────────────────────────────────────────
-  /**
-   * Compare the same field aggregation across multiple buckets in one query.
-   * Your security key must have read access to ALL listed buckets.
-   *
-   * @example
-   * ```ts
-   * const rows = await analytics.crossBucket({
-   *   bucketKeys: ['orders-us', 'orders-eu', 'orders-apac'],
-   *   field: 'amount',
-   *   aggregation: 'sum',
-   * });
-   * // → [
-   * //   { bucket: 'orders-us',   value: 120000 },
-   * //   { bucket: 'orders-eu',   value: 45000 },
-   * //   { bucket: 'orders-apac', value: 33000 },
-   * // ]
-   * ```
-   */
   async crossBucket(opts) {
     assertSafeName(opts.field, "field");
     opts.bucketKeys.forEach((k) => assertSafeName(k, "bucketKey"));
     return this.run({ queryType: "crossBucket", aggregation: "sum", ...opts });
   }
-  // ─── Raw Query ────────────────────────────────────────────────────────────
-  /**
-   * Send a raw analytics query object. Use this when you need full control
-   * over the query shape or want to use a queryType not covered by the helpers.
-   *
-   * @example
-   * ```ts
-   * const result = await analytics.query({
-   *   queryType: 'topN',
-   *   field: 'category',
-   *   n: 3,
-   *   order: 'asc',
-   * });
-   * ```
-   */
   async query(query) {
     const data = await this.run(query);
     return { queryType: query.queryType, data };
@@ -1459,10 +987,6 @@ var ScopedStorage = class _ScopedStorage {
   getUploadUrl(opts) {
     return this.manager.getUploadUrl({ ...opts, path: this.scopedPath(opts.path) });
   }
-  /** Upload data directly to a signed GCS URL with optional progress tracking. */
-  uploadToSignedUrl(signedUrl, data, mimeType, onProgress) {
-    return this.manager.uploadToSignedUrl(signedUrl, data, mimeType, onProgress);
-  }
   /** Confirm a direct upload within the scoped folder. */
   confirmUpload(opts) {
     return this.manager.confirmUpload({ ...opts, path: this.scopedPath(opts.path) });
@@ -1471,9 +995,16 @@ var ScopedStorage = class _ScopedStorage {
   download(path) {
     return this.manager.download(this.scopedPath(path));
   }
-  /** List files within the scoped folder. */
+  /**
+   * List files within the scoped folder.
+   * `prefix` in options is relative to the scope.
+   */
   list(opts = {}) {
-    return this.manager.list({ ...opts, prefix: this.scopedPath(opts.prefix ?? "") });
+    const scopedOpts = {
+      ...opts,
+      prefix: this.scopedPath(opts.prefix ?? "")
+    };
+    return this.manager.list(scopedOpts);
   }
   /** Get metadata for a file within the scoped folder. */
   getMetadata(path) {
@@ -1513,7 +1044,7 @@ var ScopedStorage = class _ScopedStorage {
    * @example
    * ```ts
    * const uploads = db.storage.scope('user-uploads');
-   * const images  = uploads.scope('images'); // → "user-uploads/images/"
+   * const images = uploads.scope('images');   // → "user-uploads/images/"
    * ```
    */
   scope(subPrefix) {
@@ -1524,66 +1055,67 @@ var ScopedStorage = class _ScopedStorage {
 // src/client.ts
 var HydrousClient = class {
   constructor(config) {
-    this._storage = null;
     this._recordsCache = /* @__PURE__ */ new Map();
     this._authCache = /* @__PURE__ */ new Map();
     this._analyticsCache = /* @__PURE__ */ new Map();
-    if (!config.securityKey) {
-      throw new Error(
-        "[HydrousDB] securityKey is required. Get yours from https://hydrousdb.com/dashboard."
-      );
+    this._storageCache = /* @__PURE__ */ new Map();
+    if (!config.authKey) {
+      throw new Error("[HydrousDB] authKey is required. Get yours from https://hydrousdb.com/dashboard.");
+    }
+    if (!config.bucketSecurityKey) {
+      throw new Error("[HydrousDB] bucketSecurityKey is required. Get yours from https://hydrousdb.com/dashboard.");
+    }
+    if (!config.storageKeys || Object.keys(config.storageKeys).length === 0) {
+      throw new Error("[HydrousDB] storageKeys is required. Define at least one storage key from https://hydrousdb.com/dashboard.");
     }
     const baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
-    this.http = new HttpClient(baseUrl, config.securityKey);
-    this._storageKey = config.securityKey;
+    this.http = new HttpClient(baseUrl);
+    this.authKey_ = config.authKey;
+    this.bucketSecurityKey_ = config.bucketSecurityKey;
+    this.storageKeys_ = config.storageKeys;
   }
   // ─── Records ─────────────────────────────────────────────────────────────
   /**
-   * Get a typed records client for the given bucket.
-   *
-   * The generic type parameter `T` describes the shape of records in this
-   * bucket. Leave it unset for a generic `Record<string, unknown>` shape.
-   *
-   * @param bucketKey  The name of your bucket (must match what you created in the dashboard).
+   * Get a typed records client for the named bucket.
+   * Uses your `bucketSecurityKey` automatically.
    *
    * @example
    * ```ts
-   * interface Post { title: string; body: string; published: boolean }
+   * interface Post { title: string; published: boolean }
    * const posts = db.records<Post>('blog-posts');
-   *
-   * const post = await posts.create({ title: 'Hello', body: '...', published: false });
-   * // post.id, post.createdAt, post.updatedAt are added automatically
+   * const post = await posts.create({ title: 'Hello', published: false });
    * ```
    */
   records(bucketKey) {
     if (!this._recordsCache.has(bucketKey)) {
-      this._recordsCache.set(bucketKey, new RecordsClient(this.http, bucketKey));
+      this._recordsCache.set(
+        bucketKey,
+        new RecordsClient(this.http, this.bucketSecurityKey_, bucketKey)
+      );
     }
     return this._recordsCache.get(bucketKey);
   }
   // ─── Auth ─────────────────────────────────────────────────────────────────
   /**
-   * Get an auth client for the given user bucket.
-   *
-   * @param bucketKey  The name of your user bucket (e.g. `"app-users"`).
+   * Get an auth client for the named user bucket.
+   * Uses your `authKey` automatically.
    *
    * @example
    * ```ts
    * const auth = db.auth('app-users');
-   * const { user, session } = await auth.login({ email: '...', password: '...' });
+   * const { user, session } = await auth.login({ email: '…', password: '…' });
    * ```
    */
   auth(bucketKey) {
     if (!this._authCache.has(bucketKey)) {
-      this._authCache.set(bucketKey, new AuthClient(this.http, bucketKey));
+      this._authCache.set(bucketKey, new AuthClient(this.http, this.authKey_, bucketKey));
     }
     return this._authCache.get(bucketKey);
   }
   // ─── Analytics ────────────────────────────────────────────────────────────
   /**
-   * Get an analytics client for the given bucket.
-   *
-   * @param bucketKey  The name of the bucket to analyse.
+   * Get an analytics client for the named bucket.
+   * Uses your `bucketSecurityKey` automatically.
    *
    * @example
    * ```ts
@@ -1593,31 +1125,46 @@ var HydrousClient = class {
    */
   analytics(bucketKey) {
     if (!this._analyticsCache.has(bucketKey)) {
-      this._analyticsCache.set(bucketKey, new AnalyticsClient(this.http, bucketKey));
+      this._analyticsCache.set(
+        bucketKey,
+        new AnalyticsClient(this.http, this.bucketSecurityKey_, bucketKey)
+      );
     }
     return this._analyticsCache.get(bucketKey);
   }
   // ─── Storage ──────────────────────────────────────────────────────────────
   /**
-   * The storage manager for uploading, downloading, listing, and managing files.
+   * Get a storage manager for the named storage key.
+   * The name must match a key you defined in `storageKeys` when calling `createClient`.
+   * Uses the corresponding `ssk_…` key automatically via `X-Storage-Key` header.
    *
-   * Scoped to your project — you can never access another project's files.
+   * @param keyName  The name of the storage key (e.g. `"avatars"`, `"documents"`, `"main"`).
    *
    * @example
    * ```ts
-   * // Upload a file
-   * const result = await db.storage.upload(file, 'images/photo.jpg', { isPublic: true });
+   * const avatars   = db.storage('avatars');
+   * const documents = db.storage('documents');
    *
-   * // Scope to a folder
-   * const avatars = db.storage.scope('user-avatars');
-   * await avatars.upload(blob, `${userId}.jpg`, { isPublic: true });
+   * // Upload to avatars bucket
+   * await avatars.upload(file, `${userId}.jpg`, { isPublic: true });
+   *
+   * // Scope to a sub-folder
+   * const userDocs = db.storage('documents').scope(`users/${userId}`);
+   * await userDocs.upload(pdfBuffer, 'contract.pdf');
    * ```
    */
-  get storage() {
-    if (!this._storage) {
-      this._storage = new StorageManager(this.http, this._storageKey);
+  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._storage;
+    const mgr = this._storageCache.get(keyName);
     const extended = mgr;
     if (!extended.scope) {
       extended.scope = (prefix) => new ScopedStorage(mgr, prefix);