hydrousdb 1.1.0

package/dist/index.js

@@ -0,0 +1,810 @@
+'use strict';
+
+// src/utils/errors.ts
+var HydrousError = class extends Error {
+  constructor(body, status) {
+    super(body.error);
+    this.name = "HydrousError";
+    this.status = status;
+    this.code = body.code;
+    this.details = body.details ?? [];
+    this.requestId = body.requestId;
+  }
+};
+var HydrousNetworkError = class extends Error {
+  constructor(message, cause) {
+    super(message);
+    this.name = "HydrousNetworkError";
+    this.cause = cause;
+  }
+};
+var HydrousTimeoutError = class extends Error {
+  constructor(timeoutMs) {
+    super(`Request timed out after ${timeoutMs}ms`);
+    this.name = "HydrousTimeoutError";
+  }
+};
+
+// src/utils/http.ts
+var DEFAULT_BASE_URL = "https://db-api-82687684612.us-central1.run.app";
+var DEFAULT_TIMEOUT = 3e4;
+var DEFAULT_RETRIES = 2;
+var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([408, 429, 500, 502, 503, 504]);
+var HttpClient = class {
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.bucketKey = config.bucketKey;
+    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+    this.retries = config.retries ?? DEFAULT_RETRIES;
+  }
+  // ── Core request ────────────────────────────────────────────────────────────
+  async request(method, path, options) {
+    const url = this.buildUrl(path, options?.params);
+    const headers = {
+      "Content-Type": "application/json",
+      ...options?.headers
+    };
+    const init = {
+      method,
+      headers,
+      signal: this.buildSignal(options?.signal)
+    };
+    if (options?.body !== void 0) {
+      init.body = JSON.stringify(options.body);
+    }
+    return this.executeWithRetry(url, init, options?.raw ?? false, this.retries);
+  }
+  // ── Convenience methods ──────────────────────────────────────────────────────
+  get(path, params, opts) {
+    return this.request("GET", path, { params, ...opts });
+  }
+  post(path, body, opts) {
+    return this.request("POST", path, { body, ...opts });
+  }
+  patch(path, body, opts) {
+    return this.request("PATCH", path, { body, ...opts });
+  }
+  delete(path, params, opts) {
+    return this.request("DELETE", path, { params, ...opts });
+  }
+  head(path, params, opts) {
+    return this.request("HEAD", path, { params, raw: true, ...opts });
+  }
+  // ── Internals ────────────────────────────────────────────────────────────────
+  buildUrl(path, params) {
+    const url = new URL(`${this.baseUrl}${path}`);
+    if (params) {
+      for (const [k, v] of Object.entries(params)) {
+        if (v !== void 0 && v !== null && v !== "") {
+          url.searchParams.set(k, String(v));
+        }
+      }
+    }
+    return url.toString();
+  }
+  buildSignal(userSignal) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort("timeout"), this.timeout);
+    userSignal?.addEventListener("abort", () => {
+      clearTimeout(timeoutId);
+      controller.abort(userSignal.reason);
+    });
+    return controller.signal;
+  }
+  async executeWithRetry(url, init, raw, retriesLeft) {
+    try {
+      const res = await fetch(url, init);
+      if (raw) return res;
+      if (res.ok) {
+        if (res.status === 204) return void 0;
+        return await res.json();
+      }
+      let body;
+      try {
+        body = await res.json();
+      } catch {
+        body = { success: false, error: `HTTP ${res.status}: ${res.statusText}` };
+      }
+      if (retriesLeft > 0 && RETRYABLE_STATUSES.has(res.status)) {
+        await sleep(500 * (this.retries - retriesLeft + 1));
+        return this.executeWithRetry(url, init, raw, retriesLeft - 1);
+      }
+      throw new HydrousError(body, res.status);
+    } catch (err) {
+      if (err instanceof HydrousError) throw err;
+      if (err instanceof Error && err.message === "timeout") {
+        throw new HydrousTimeoutError(this.timeout);
+      }
+      if (retriesLeft > 0) {
+        await sleep(500 * (this.retries - retriesLeft + 1));
+        return this.executeWithRetry(url, init, raw, retriesLeft - 1);
+      }
+      throw new HydrousNetworkError(
+        `Network request failed: ${err instanceof Error ? err.message : String(err)}`,
+        err
+      );
+    }
+  }
+};
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/utils/query.ts
+function buildQueryParams(opts) {
+  const params = {};
+  if (opts.timeScope) params["timeScope"] = opts.timeScope;
+  if (opts.year) params["year"] = opts.year;
+  if (opts.sortOrder) params["sortOrder"] = opts.sortOrder;
+  if (opts.limit) params["limit"] = opts.limit;
+  if (opts.cursor) params["cursor"] = opts.cursor;
+  if (opts.fields) params["fields"] = opts.fields;
+  for (const filter of opts.filters ?? []) {
+    const paramKey = filter.op === "==" ? filter.field : `${filter.field}[${filter.op}]`;
+    params[paramKey] = filter.value;
+  }
+  return params;
+}
+function validateFilters(filters) {
+  const VALID_OPS = /* @__PURE__ */ new Set(["==", "!=", ">", "<", ">=", "<=", "contains"]);
+  if (filters.length > 3) {
+    throw new Error("HydrousDB supports a maximum of 3 filters per query.");
+  }
+  for (const f of filters) {
+    if (!VALID_OPS.has(f.op)) {
+      throw new Error(
+        `Invalid filter operator "${f.op}". Valid operators: ${[...VALID_OPS].join(", ")}`
+      );
+    }
+    if (!f.field || typeof f.field !== "string") {
+      throw new Error('Each filter must have a non-empty "field" string.');
+    }
+  }
+}
+
+// src/records/client.ts
+var RecordsClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  get path() {
+    return `/api/${this.http.bucketKey}`;
+  }
+  // ── GET — single record ────────────────────────────────────────────────────
+  /**
+   * Fetch a single record by ID.
+   *
+   * @example
+   * const { data } = await db.records.get('rec_abc123');
+   * const { data, history } = await db.records.get('rec_abc123', { showHistory: true });
+   */
+  async get(recordId, options) {
+    const params = { recordId };
+    if (options?.showHistory) params["showHistory"] = "true";
+    return this.http.get(this.path, params, options);
+  }
+  // ── GET — historical snapshot ──────────────────────────────────────────────
+  /**
+   * Fetch a specific historical version (generation) of a record.
+   *
+   * @example
+   * const { data } = await db.records.getSnapshot('rec_abc123', '1700000000000000');
+   */
+  async getSnapshot(recordId, generation, opts) {
+    return this.http.get(this.path, { recordId, generation }, opts);
+  }
+  // ── GET — collection query ─────────────────────────────────────────────────
+  /**
+   * Query a collection with optional filters, sorting, and pagination.
+   *
+   * @example
+   * // Simple query
+   * const { data, meta } = await db.records.query({ limit: 50, sortOrder: 'desc' });
+   *
+   * // Filtered query
+   * const { data } = await db.records.query({
+   *   filters: [{ field: 'status', op: '==', value: 'active' }],
+   *   timeScope: '7d',
+   * });
+   *
+   * // Paginated
+   * let cursor: string | null = null;
+   * do {
+   *   const result = await db.records.query({ limit: 100, cursor: cursor ?? undefined });
+   *   cursor = result.meta.nextCursor;
+   * } while (cursor);
+   */
+  async query(options) {
+    if (options?.filters) validateFilters(options.filters);
+    const params = buildQueryParams(options ?? {});
+    return this.http.get(this.path, params, options);
+  }
+  // ── POST — insert ──────────────────────────────────────────────────────────
+  /**
+   * Insert a new record.
+   *
+   * @example
+   * const { data, meta } = await db.records.insert({
+   *   values: { name: 'Alice', score: 99 },
+   *   queryableFields: ['name'],
+   *   userEmail: 'alice@example.com',
+   * });
+   */
+  async insert(payload, opts) {
+    return this.http.post(this.path, payload, opts);
+  }
+  // ── PATCH — update ─────────────────────────────────────────────────────────
+  /**
+   * Update an existing record.
+   *
+   * @example
+   * await db.records.update({
+   *   recordId: 'rec_abc123',
+   *   values: { score: 100 },
+   *   track_record_history: true,
+   * });
+   */
+  async update(payload, opts) {
+    return this.http.patch(this.path, payload, opts);
+  }
+  // ── DELETE ─────────────────────────────────────────────────────────────────
+  /**
+   * Delete a record permanently.
+   *
+   * @example
+   * await db.records.delete('rec_abc123');
+   */
+  async delete(recordId, opts) {
+    return this.http.delete(this.path, { recordId }, opts);
+  }
+  // ── HEAD — existence check ─────────────────────────────────────────────────
+  /**
+   * Check whether a record exists without fetching its full data.
+   * Returns `null` if the record is not found.
+   *
+   * @example
+   * const info = await db.records.exists('rec_abc123');
+   * if (info?.exists) console.log('found at', info.updatedAt);
+   */
+  async exists(recordId, opts) {
+    const res = await this.http.head(this.path, { recordId }, opts);
+    if (res.status === 404) return null;
+    if (!res.ok) return null;
+    return {
+      exists: true,
+      id: res.headers.get("X-Record-Id") ?? recordId,
+      createdAt: res.headers.get("X-Created-At") ?? "",
+      updatedAt: res.headers.get("X-Updated-At") ?? "",
+      sizeBytes: res.headers.get("X-Size-Bytes") ?? ""
+    };
+  }
+  // ── Batch — update ─────────────────────────────────────────────────────────
+  /**
+   * Update up to 500 records in a single request.
+   *
+   * @example
+   * await db.records.batchUpdate({
+   *   updates: [
+   *     { recordId: 'rec_1', values: { status: 'archived' } },
+   *     { recordId: 'rec_2', values: { status: 'archived' } },
+   *   ],
+   * });
+   */
+  async batchUpdate(payload, opts) {
+    return this.http.post(
+      `${this.path}/batch/update`,
+      payload,
+      opts
+    );
+  }
+  // ── Batch — delete ─────────────────────────────────────────────────────────
+  /**
+   * Delete up to 500 records in a single request.
+   *
+   * @example
+   * await db.records.batchDelete({ recordIds: ['rec_1', 'rec_2', 'rec_3'] });
+   */
+  async batchDelete(payload, opts) {
+    return this.http.post(
+      `${this.path}/batch/delete`,
+      payload,
+      opts
+    );
+  }
+  // ── Batch — insert ─────────────────────────────────────────────────────────
+  /**
+   * Insert up to 500 records in a single request.
+   * Returns HTTP 207 (multi-status) — check `meta.failed` for partial failures.
+   *
+   * @example
+   * const result = await db.records.batchInsert({
+   *   records: [{ name: 'Alice' }, { name: 'Bob' }],
+   *   queryableFields: ['name'],
+   * });
+   */
+  async batchInsert(payload, opts) {
+    return this.http.post(
+      `${this.path}/batch/insert`,
+      payload,
+      opts
+    );
+  }
+  // ── Helpers ────────────────────────────────────────────────────────────────
+  /**
+   * Fetch ALL records matching a query, automatically following cursors.
+   * Use with care on large collections — prefer `query()` with manual pagination.
+   *
+   * @example
+   * const allRecords = await db.records.queryAll({
+   *   filters: [{ field: 'type', op: '==', value: 'invoice' }],
+   * });
+   */
+  async queryAll(options) {
+    const all = [];
+    let cursor = null;
+    do {
+      const result = await this.query(cursor ? { ...options, cursor } : { ...options });
+      all.push(...result.data);
+      cursor = result.meta.nextCursor ?? null;
+    } while (cursor);
+    return all;
+  }
+};
+
+// src/auth/client.ts
+var AuthClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  get path() {
+    return `/auth/${this.http.bucketKey}`;
+  }
+  // ── Sign-up ────────────────────────────────────────────────────────────────
+  /**
+   * Create a new user account. Returns the user and a session immediately.
+   *
+   * @example
+   * const { data, session } = await db.auth.signUp({
+   *   email: 'alice@example.com',
+   *   password: 'Str0ngP@ss!',
+   *   fullName: 'Alice Smith',
+   * });
+   * // Store session.sessionId and session.refreshToken in your app
+   */
+  async signUp(payload, opts) {
+    return this.http.post(`${this.path}/signup`, payload, opts);
+  }
+  // ── Sign-in ────────────────────────────────────────────────────────────────
+  /**
+   * Authenticate with email + password. Returns user data and a new session.
+   *
+   * @example
+   * const { data, session } = await db.auth.signIn({
+   *   email: 'alice@example.com',
+   *   password: 'Str0ngP@ss!',
+   * });
+   */
+  async signIn(payload, opts) {
+    return this.http.post(`${this.path}/signin`, payload, opts);
+  }
+  // ── Sign-out ───────────────────────────────────────────────────────────────
+  /**
+   * Revoke a session (or all sessions for a user).
+   *
+   * @example
+   * // Single device
+   * await db.auth.signOut({ sessionId: 'sess_...' });
+   *
+   * // All devices
+   * await db.auth.signOut({ allDevices: true, userId: 'user_...' });
+   */
+  async signOut(payload, opts) {
+    return this.http.post(`${this.path}/signout`, payload, opts);
+  }
+  // ── Session: validate ──────────────────────────────────────────────────────
+  /**
+   * Validate a session token — use this on every protected request in your backend.
+   *
+   * @example
+   * try {
+   *   const { data } = await db.auth.validateSession(sessionId);
+   *   // data is the authenticated user
+   * } catch (err) {
+   *   // Session expired or invalid
+   * }
+   */
+  async validateSession(sessionId, opts) {
+    return this.http.post(`${this.path}/session/validate`, { sessionId }, opts);
+  }
+  // ── Session: refresh ───────────────────────────────────────────────────────
+  /**
+   * Exchange a refresh token for a new session (rotation).
+   * The old session is revoked.
+   *
+   * @example
+   * const { session } = await db.auth.refreshSession(refreshToken);
+   */
+  async refreshSession(refreshToken, opts) {
+    return this.http.post(`${this.path}/session/refresh`, { refreshToken }, opts);
+  }
+  // ── User: get ──────────────────────────────────────────────────────────────
+  /**
+   * Fetch a user by their ID.
+   *
+   * @example
+   * const { data } = await db.auth.getUser('user_abc123');
+   */
+  async getUser(userId, opts) {
+    return this.http.get(`${this.path}/user`, { userId }, opts);
+  }
+  // ── User: list ─────────────────────────────────────────────────────────────
+  /**
+   * List users with cursor-based pagination.
+   *
+   * @example
+   * const { data, meta } = await db.auth.listUsers({ limit: 50 });
+   */
+  async listUsers(options) {
+    const params = {
+      limit: options?.limit
+    };
+    if (options?.cursor) params["cursor"] = options.cursor;
+    return this.http.get(`${this.path}/users`, params, options);
+  }
+  // ── User: update ───────────────────────────────────────────────────────────
+  /**
+   * Update user profile fields.
+   *
+   * @example
+   * await db.auth.updateUser({ userId: 'user_abc', updates: { fullName: 'Bob Smith' } });
+   */
+  async updateUser(payload, opts) {
+    return this.http.patch(`${this.path}/user`, payload, opts);
+  }
+  // ── User: delete ───────────────────────────────────────────────────────────
+  /**
+   * Soft-delete a user. All their sessions are revoked automatically.
+   *
+   * @example
+   * await db.auth.deleteUser('user_abc123');
+   */
+  async deleteUser(userId, opts) {
+    return this.http.delete(`${this.path}/user`, { userId }, opts);
+  }
+  // ── Password: change ───────────────────────────────────────────────────────
+  /**
+   * Change password for a signed-in user (requires old password).
+   * All sessions are revoked after success.
+   *
+   * @example
+   * await db.auth.changePassword({
+   *   userId: 'user_abc',
+   *   oldPassword: 'Old@Pass1',
+   *   newPassword: 'New@Pass2',
+   * });
+   */
+  async changePassword(payload, opts) {
+    return this.http.post(`${this.path}/password/change`, payload, opts);
+  }
+  // ── Password: reset request ────────────────────────────────────────────────
+  /**
+   * Request a password reset email.
+   * Always returns success to prevent email enumeration.
+   *
+   * @example
+   * await db.auth.requestPasswordReset({ email: 'alice@example.com' });
+   */
+  async requestPasswordReset(payload, opts) {
+    return this.http.post(`${this.path}/password/reset/request`, payload, opts);
+  }
+  // ── Password: reset confirm ────────────────────────────────────────────────
+  /**
+   * Confirm a password reset using the token from the reset email.
+   *
+   * @example
+   * await db.auth.confirmPasswordReset({ resetToken: 'tok_...', newPassword: 'New@Pass2' });
+   */
+  async confirmPasswordReset(payload, opts) {
+    return this.http.post(`${this.path}/password/reset/confirm`, payload, opts);
+  }
+  // ── Email: verify request ──────────────────────────────────────────────────
+  /**
+   * Send a verification email to the user.
+   *
+   * @example
+   * await db.auth.requestEmailVerification({ userId: 'user_abc' });
+   */
+  async requestEmailVerification(payload, opts) {
+    return this.http.post(`${this.path}/email/verify/request`, payload, opts);
+  }
+  // ── Email: verify confirm ──────────────────────────────────────────────────
+  /**
+   * Confirm email address using the token from the verification email.
+   *
+   * @example
+   * await db.auth.confirmEmailVerification({ verifyToken: 'tok_...' });
+   */
+  async confirmEmailVerification(payload, opts) {
+    return this.http.post(`${this.path}/email/verify/confirm`, payload, opts);
+  }
+  // ── Account: lock ──────────────────────────────────────────────────────────
+  /**
+   * Lock a user account for a given duration (default: 15 min).
+   *
+   * @example
+   * await db.auth.lockAccount({ userId: 'user_abc', duration: 30 * 60 * 1000 });
+   */
+  async lockAccount(payload, opts) {
+    return this.http.post(`${this.path}/account/lock`, payload, opts);
+  }
+  // ── Account: unlock ────────────────────────────────────────────────────────
+  /**
+   * Unlock a previously locked user account.
+   *
+   * @example
+   * await db.auth.unlockAccount('user_abc');
+   */
+  async unlockAccount(userId, opts) {
+    return this.http.post(`${this.path}/account/unlock`, { userId }, opts);
+  }
+  // ── Helpers ────────────────────────────────────────────────────────────────
+  /**
+   * Fetch all users, automatically following cursors.
+   *
+   * @example
+   * const users = await db.auth.listAllUsers();
+   */
+  async listAllUsers(opts) {
+    const all = [];
+    let cursor = null;
+    do {
+      const result = await this.listUsers(cursor ? { cursor, ...opts } : { ...opts });
+      all.push(...result.data);
+      cursor = result.meta.nextCursor ?? null;
+    } while (cursor);
+    return all;
+  }
+};
+
+// src/analytics/client.ts
+var AnalyticsClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  get path() {
+    return `/api/analytics/${this.http.bucketKey}/${this.http.bucketKey}`;
+  }
+  // ── Raw query ─────────────────────────────────────────────────────────────
+  /**
+   * Run any analytics query with full control over the payload.
+   * Prefer the typed convenience methods below for everyday use.
+   */
+  async query(payload, opts) {
+    return this.http.post(this.path, payload, opts);
+  }
+  // ── count ──────────────────────────────────────────────────────────────────
+  /**
+   * Total record count, optionally scoped to a date range.
+   * Server `queryType`: **"count"**
+   *
+   * @example
+   * const { data } = await db.analytics.count();
+   * console.log(data.count); // 1234
+   *
+   * // With date range
+   * const { data } = await db.analytics.count({
+   *   dateRange: { startDate: '2025-01-01', endDate: '2025-12-31' }
+   * });
+   */
+  async count(options) {
+    return this.query({ queryType: "count", dateRange: options?.dateRange }, options);
+  }
+  // ── distribution ───────────────────────────────────────────────────────────
+  /**
+   * Value distribution (histogram) for a field.
+   * Server `queryType`: **"distribution"**
+   *
+   * @example
+   * const { data } = await db.analytics.distribution('status');
+   * // [{ value: 'active', count: 80 }, { value: 'archived', count: 20 }]
+   */
+  async distribution(field, options) {
+    return this.query({
+      queryType: "distribution",
+      field,
+      limit: options?.limit,
+      order: options?.order,
+      dateRange: options?.dateRange
+    }, options);
+  }
+  // ── sum ────────────────────────────────────────────────────────────────────
+  /**
+   * Sum a numeric field, with optional group-by.
+   * Server `queryType`: **"sum"**
+   *
+   * @example
+   * const { data } = await db.analytics.sum('revenue', { groupBy: 'region' });
+   */
+  async sum(field, options) {
+    return this.query({
+      queryType: "sum",
+      field,
+      groupBy: options?.groupBy,
+      limit: options?.limit,
+      dateRange: options?.dateRange
+    }, options);
+  }
+  // ── timeSeries ─────────────────────────────────────────────────────────────
+  /**
+   * Record count grouped over time.
+   * Server `queryType`: **"timeSeries"**
+   *
+   * @example
+   * const { data } = await db.analytics.timeSeries({ granularity: 'day' });
+   * // [{ date: '2025-01-01', count: 42 }, ...]
+   */
+  async timeSeries(options) {
+    return this.query({
+      queryType: "timeSeries",
+      granularity: options?.granularity,
+      dateRange: options?.dateRange
+    }, options);
+  }
+  // ── fieldTimeSeries ────────────────────────────────────────────────────────
+  /**
+   * Aggregate a numeric field over time.
+   * Server `queryType`: **"fieldTimeSeries"**
+   *
+   * @example
+   * const { data } = await db.analytics.fieldTimeSeries('revenue', {
+   *   granularity: 'month',
+   *   aggregation: 'sum',
+   * });
+   */
+  async fieldTimeSeries(field, options) {
+    return this.query({
+      queryType: "fieldTimeSeries",
+      field,
+      aggregation: options?.aggregation,
+      granularity: options?.granularity,
+      dateRange: options?.dateRange
+    }, options);
+  }
+  // ── topN ───────────────────────────────────────────────────────────────────
+  /**
+   * Top N most frequent values for a field.
+   * Server `queryType`: **"topN"**
+   *
+   * @example
+   * const { data } = await db.analytics.topN('country', 5);
+   * // [{ label: 'US', value: 'US', count: 500 }, ...]
+   */
+  async topN(field, n = 10, options) {
+    return this.query({
+      queryType: "topN",
+      field,
+      n,
+      labelField: options?.labelField,
+      order: options?.order,
+      dateRange: options?.dateRange
+    }, options);
+  }
+  // ── stats ──────────────────────────────────────────────────────────────────
+  /**
+   * Statistical summary for a numeric field: min, max, avg, stddev, p50, p90, p99.
+   * Server `queryType`: **"stats"**
+   *
+   * @example
+   * const { data } = await db.analytics.stats('score');
+   * console.log(data.avg, data.p99);
+   */
+  async stats(field, options) {
+    return this.query({ queryType: "stats", field, dateRange: options?.dateRange }, options);
+  }
+  // ── records ────────────────────────────────────────────────────────────────
+  /**
+   * Filtered, paginated raw records with optional field projection.
+   * Supports filter ops: == != > < >= <= CONTAINS
+   * Server `queryType`: **"records"**
+   *
+   * @example
+   * const { data } = await db.analytics.records({
+   *   filters: [{ field: 'role', op: '==', value: 'admin' }],
+   *   selectFields: ['email', 'createdAt'],
+   *   limit: 25,
+   * });
+   * console.log(data.data, data.hasMore);
+   */
+  async records(options) {
+    return this.query({
+      queryType: "records",
+      filters: options?.filters,
+      selectFields: options?.selectFields,
+      limit: options?.limit,
+      offset: options?.offset,
+      orderBy: options?.orderBy,
+      order: options?.order,
+      dateRange: options?.dateRange
+    }, options);
+  }
+  // ── multiMetric ────────────────────────────────────────────────────────────
+  /**
+   * Multiple aggregations in a single BigQuery call — ideal for dashboard stat cards.
+   * Server `queryType`: **"multiMetric"**
+   *
+   * @example
+   * const { data } = await db.analytics.multiMetric([
+   *   { name: 'totalRevenue', field: 'amount',  aggregation: 'sum' },
+   *   { name: 'avgScore',     field: 'score',   aggregation: 'avg' },
+   *   { name: 'userCount',    field: 'userId',  aggregation: 'count' },
+   * ]);
+   * console.log(data.totalRevenue, data.avgScore, data.userCount);
+   */
+  async multiMetric(metrics, options) {
+    return this.query({
+      queryType: "multiMetric",
+      metrics,
+      dateRange: options?.dateRange
+    }, options);
+  }
+  // ── storageStats ───────────────────────────────────────────────────────────
+  /**
+   * Storage statistics for the bucket — total records, bytes, avg/min/max size.
+   * Server `queryType`: **"storageStats"**
+   *
+   * @example
+   * const { data } = await db.analytics.storageStats();
+   * console.log(data.totalRecords, data.totalBytes);
+   */
+  async storageStats(options) {
+    return this.query({ queryType: "storageStats", dateRange: options?.dateRange }, options);
+  }
+  // ── crossBucket ────────────────────────────────────────────────────────────
+  /**
+   * Compare a metric across multiple buckets in one query.
+   * Server `queryType`: **"crossBucket"**
+   *
+   * @example
+   * const { data } = await db.analytics.crossBucket({
+   *   bucketKeys:  ['sales', 'refunds', 'trials'],
+   *   field:       'amount',
+   *   aggregation: 'sum',
+   * });
+   */
+  async crossBucket(options) {
+    return this.query({
+      queryType: "crossBucket",
+      bucketKeys: options.bucketKeys,
+      field: options.field,
+      aggregation: options.aggregation,
+      dateRange: options.dateRange
+    }, options);
+  }
+};
+
+// src/client.ts
+var HydrousClient = class {
+  constructor(config) {
+    if (!config.apiKey) throw new Error("[hydrousdb] apiKey is required");
+    if (!config.bucketKey) throw new Error("[hydrousdb] bucketKey is required");
+    this.http = new HttpClient(config);
+    this.records = new RecordsClient(this.http);
+    this.auth = new AuthClient(this.http);
+    this.analytics = new AnalyticsClient(this.http);
+  }
+};
+function createClient(config) {
+  return new HydrousClient(config);
+}
+
+exports.AnalyticsClient = AnalyticsClient;
+exports.AuthClient = AuthClient;
+exports.HydrousClient = HydrousClient;
+exports.HydrousError = HydrousError;
+exports.HydrousNetworkError = HydrousNetworkError;
+exports.HydrousTimeoutError = HydrousTimeoutError;
+exports.RecordsClient = RecordsClient;
+exports.createClient = createClient;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map