hydrousdb 1.1.1 → 2.0.0

package/dist/index.mjs

@@ -31,7 +31,7 @@ var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([408, 429, 500, 502, 503, 504])
 var HttpClient = class {
   constructor(config) {
     this.authKey = config.authKey;
-    this.bucketKey = config.bucketKey;
+    this.securityKey = config.securityKey;
     this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
     this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
     this.retries = config.retries ?? DEFAULT_RETRIES;
@@ -166,31 +166,34 @@ var RecordsClient = class {
   constructor(http) {
     this.http = http;
   }
-  get path() {
-    return `/api/${this.http.bucketKey}`;
+  /** Builds the base path for a given bucket: /api/:bucketKey/:securityKey */
+  path(bucketKey) {
+    return `/api/${bucketKey}/${this.http.securityKey}`;
   }
   // ── 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 });
+   * const { data } = await db.records.get('rec_abc123', { bucketKey: 'users' });
+   * const { data, history } = await db.records.get('rec_abc123', { bucketKey: 'users', showHistory: true });
    */
   async get(recordId, options) {
+    const { bucketKey, showHistory, ...rest } = options;
     const params = { recordId };
-    if (options?.showHistory) params["showHistory"] = "true";
-    return this.http.get(this.path, params, options);
+    if (showHistory) params["showHistory"] = "true";
+    return this.http.get(this.path(bucketKey), params, rest);
   }
   // ── GET — historical snapshot ──────────────────────────────────────────────
   /**
    * Fetch a specific historical version (generation) of a record.
    *
    * @example
-   * const { data } = await db.records.getSnapshot('rec_abc123', '1700000000000000');
+   * const { data } = await db.records.getSnapshot('rec_abc123', '1700000000000000', { bucketKey: 'users' });
    */
-  async getSnapshot(recordId, generation, opts) {
-    return this.http.get(this.path, { recordId, generation }, opts);
+  async getSnapshot(recordId, generation, options) {
+    const { bucketKey, ...rest } = options;
+    return this.http.get(this.path(bucketKey), { recordId, generation }, rest);
   }
   // ── GET — collection query ─────────────────────────────────────────────────
   /**
@@ -198,10 +201,11 @@ var RecordsClient = class {
    *
    * @example
    * // Simple query
-   * const { data, meta } = await db.records.query({ limit: 50, sortOrder: 'desc' });
+   * const { data, meta } = await db.records.query({ bucketKey: 'orders', limit: 50 });
    *
    * // Filtered query
    * const { data } = await db.records.query({
+   *   bucketKey: 'orders',
    *   filters: [{ field: 'status', op: '==', value: 'active' }],
    *   timeScope: '7d',
    * });
@@ -209,52 +213,54 @@ var RecordsClient = class {
    * // Paginated
    * let cursor: string | null = null;
    * do {
-   *   const result = await db.records.query({ limit: 100, cursor: cursor ?? undefined });
+   *   const result = await db.records.query({ bucketKey: 'orders', 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);
+    const { bucketKey, ...rest } = options;
+    if (rest.filters) validateFilters(rest.filters);
+    const params = buildQueryParams(rest);
+    return this.http.get(this.path(bucketKey), params, rest);
   }
   // ── POST — insert ──────────────────────────────────────────────────────────
   /**
-   * Insert a new record.
+   * Insert a new record into the specified bucket.
    *
    * @example
-   * const { data, meta } = await db.records.insert({
-   *   values: { name: 'Alice', score: 99 },
-   *   queryableFields: ['name'],
-   *   userEmail: 'alice@example.com',
-   * });
+   * const { data, meta } = await db.records.insert(
+   *   { values: { name: 'Alice', score: 99 }, queryableFields: ['name'] },
+   *   { bucketKey: 'users' }
+   * );
    */
-  async insert(payload, opts) {
-    return this.http.post(this.path, payload, opts);
+  async insert(payload, options) {
+    const { bucketKey, ...rest } = options;
+    return this.http.post(this.path(bucketKey), payload, rest);
   }
   // ── PATCH — update ─────────────────────────────────────────────────────────
   /**
    * Update an existing record.
    *
    * @example
-   * await db.records.update({
-   *   recordId: 'rec_abc123',
-   *   values: { score: 100 },
-   *   track_record_history: true,
-   * });
+   * await db.records.update(
+   *   { recordId: 'rec_abc123', values: { score: 100 }, track_record_history: true },
+   *   { bucketKey: 'users' }
+   * );
    */
-  async update(payload, opts) {
-    return this.http.patch(this.path, payload, opts);
+  async update(payload, options) {
+    const { bucketKey, ...rest } = options;
+    return this.http.patch(this.path(bucketKey), payload, rest);
   }
   // ── DELETE ─────────────────────────────────────────────────────────────────
   /**
    * Delete a record permanently.
    *
    * @example
-   * await db.records.delete('rec_abc123');
+   * await db.records.delete('rec_abc123', { bucketKey: 'users' });
    */
-  async delete(recordId, opts) {
-    return this.http.delete(this.path, { recordId }, opts);
+  async delete(recordId, options) {
+    const { bucketKey, ...rest } = options;
+    return this.http.delete(this.path(bucketKey), { recordId }, rest);
   }
   // ── HEAD — existence check ─────────────────────────────────────────────────
   /**
@@ -262,11 +268,12 @@ var RecordsClient = class {
    * Returns `null` if the record is not found.
    *
    * @example
-   * const info = await db.records.exists('rec_abc123');
+   * const info = await db.records.exists('rec_abc123', { bucketKey: 'users' });
    * if (info?.exists) console.log('found at', info.updatedAt);
    */
-  async exists(recordId, opts) {
-    const res = await this.http.head(this.path, { recordId }, opts);
+  async exists(recordId, options) {
+    const { bucketKey, ...rest } = options;
+    const res = await this.http.head(this.path(bucketKey), { recordId }, rest);
     if (res.status === 404) return null;
     if (!res.ok) return null;
     return {
@@ -282,33 +289,28 @@ var RecordsClient = class {
    * 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' } },
-   *   ],
-   * });
+   * await db.records.batchUpdate(
+   *   { updates: [{ recordId: 'rec_1', values: { status: 'archived' } }] },
+   *   { bucketKey: 'orders' }
+   * );
    */
-  async batchUpdate(payload, opts) {
-    return this.http.post(
-      `${this.path}/batch/update`,
-      payload,
-      opts
-    );
+  async batchUpdate(payload, options) {
+    const { bucketKey, ...rest } = options;
+    return this.http.post(`${this.path(bucketKey)}/batch/update`, payload, rest);
   }
   // ── Batch — delete ─────────────────────────────────────────────────────────
   /**
    * Delete up to 500 records in a single request.
    *
    * @example
-   * await db.records.batchDelete({ recordIds: ['rec_1', 'rec_2', 'rec_3'] });
+   * await db.records.batchDelete(
+   *   { recordIds: ['rec_1', 'rec_2'] },
+   *   { bucketKey: 'orders' }
+   * );
    */
-  async batchDelete(payload, opts) {
-    return this.http.post(
-      `${this.path}/batch/delete`,
-      payload,
-      opts
-    );
+  async batchDelete(payload, options) {
+    const { bucketKey, ...rest } = options;
+    return this.http.post(`${this.path(bucketKey)}/batch/delete`, payload, rest);
   }
   // ── Batch — insert ─────────────────────────────────────────────────────────
   /**
@@ -316,17 +318,14 @@ var RecordsClient = class {
    * 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'],
-   * });
+   * const result = await db.records.batchInsert(
+   *   { records: [{ name: 'Alice' }, { name: 'Bob' }], queryableFields: ['name'] },
+   *   { bucketKey: 'users' }
+   * );
    */
-  async batchInsert(payload, opts) {
-    return this.http.post(
-      `${this.path}/batch/insert`,
-      payload,
-      opts
-    );
+  async batchInsert(payload, options) {
+    const { bucketKey, ...rest } = options;
+    return this.http.post(`${this.path(bucketKey)}/batch/insert`, payload, rest);
   }
   // ── Helpers ────────────────────────────────────────────────────────────────
   /**
@@ -335,6 +334,7 @@ var RecordsClient = class {
    *
    * @example
    * const allRecords = await db.records.queryAll({
+   *   bucketKey: 'orders',
    *   filters: [{ field: 'type', op: '==', value: 'invoice' }],
    * });
    */
@@ -342,7 +342,9 @@ var RecordsClient = class {
     const all = [];
     let cursor = null;
     do {
-      const result = await this.query(cursor ? { ...options, cursor } : { ...options });
+      const result = await this.query(
+        cursor ? { ...options, cursor } : { ...options }
+      );
       all.push(...result.data);
       cursor = result.meta.nextCursor ?? null;
     } while (cursor);
@@ -570,214 +572,177 @@ var AnalyticsClient = class {
   constructor(http) {
     this.http = http;
   }
-  get path() {
-    return `/api/analytics/${this.http.bucketKey}/${this.http.bucketKey}`;
+  /** Builds the path for a given bucket: /api/analytics/:bucketKey/:securityKey */
+  path(bucketKey) {
+    return `/api/analytics/${bucketKey}/${this.http.securityKey}`;
   }
   // ── 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);
+  async query(payload, options) {
+    const { bucketKey, ...rest } = options;
+    return this.http.post(this.path(bucketKey), payload, rest);
   }
   // ── 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
+   * const { data } = await db.analytics.count({ bucketKey: 'orders' });
+   * console.log(data.count);
    *
-   * // With date range
    * const { data } = await db.analytics.count({
-   *   dateRange: { startDate: '2025-01-01', endDate: '2025-12-31' }
+   *   bucketKey: 'orders',
+   *   dateRange: { startDate: '2025-01-01', endDate: '2025-12-31' },
    * });
    */
   async count(options) {
-    return this.query({ queryType: "count", dateRange: options?.dateRange }, options);
+    const { dateRange, ...rest } = options;
+    return this.query({ queryType: "count", dateRange }, rest);
   }
   // ── distribution ───────────────────────────────────────────────────────────
   /**
    * Value distribution (histogram) for a field.
-   * Server `queryType`: **"distribution"**
    *
    * @example
-   * const { data } = await db.analytics.distribution('status');
+   * const { data } = await db.analytics.distribution('status', { bucketKey: 'orders' });
    * // [{ 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);
+    const { limit, order, dateRange, ...rest } = options;
+    return this.query({ queryType: "distribution", field, limit, order, dateRange }, rest);
   }
   // ── sum ────────────────────────────────────────────────────────────────────
   /**
    * Sum a numeric field, with optional group-by.
-   * Server `queryType`: **"sum"**
    *
    * @example
-   * const { data } = await db.analytics.sum('revenue', { groupBy: 'region' });
+   * const { data } = await db.analytics.sum('revenue', { bucketKey: 'orders', groupBy: 'region' });
    */
   async sum(field, options) {
-    return this.query({
-      queryType: "sum",
-      field,
-      groupBy: options?.groupBy,
-      limit: options?.limit,
-      dateRange: options?.dateRange
-    }, options);
+    const { groupBy, limit, dateRange, ...rest } = options;
+    return this.query({ queryType: "sum", field, groupBy, limit, dateRange }, rest);
   }
   // ── timeSeries ─────────────────────────────────────────────────────────────
   /**
    * Record count grouped over time.
-   * Server `queryType`: **"timeSeries"**
    *
    * @example
-   * const { data } = await db.analytics.timeSeries({ granularity: 'day' });
+   * const { data } = await db.analytics.timeSeries({ bucketKey: 'orders', granularity: 'day' });
    * // [{ date: '2025-01-01', count: 42 }, ...]
    */
   async timeSeries(options) {
-    return this.query({
-      queryType: "timeSeries",
-      granularity: options?.granularity,
-      dateRange: options?.dateRange
-    }, options);
+    const { granularity, dateRange, ...rest } = options;
+    return this.query({ queryType: "timeSeries", granularity, dateRange }, rest);
   }
   // ── fieldTimeSeries ────────────────────────────────────────────────────────
   /**
    * Aggregate a numeric field over time.
-   * Server `queryType`: **"fieldTimeSeries"**
    *
    * @example
    * const { data } = await db.analytics.fieldTimeSeries('revenue', {
+   *   bucketKey: 'orders',
    *   granularity: 'month',
    *   aggregation: 'sum',
    * });
    */
   async fieldTimeSeries(field, options) {
-    return this.query({
-      queryType: "fieldTimeSeries",
-      field,
-      aggregation: options?.aggregation,
-      granularity: options?.granularity,
-      dateRange: options?.dateRange
-    }, options);
+    const { aggregation, granularity, dateRange, ...rest } = options;
+    return this.query({ queryType: "fieldTimeSeries", field, aggregation, granularity, dateRange }, rest);
   }
   // ── topN ───────────────────────────────────────────────────────────────────
   /**
    * Top N most frequent values for a field.
-   * Server `queryType`: **"topN"**
    *
    * @example
-   * const { data } = await db.analytics.topN('country', 5);
+   * const { data } = await db.analytics.topN('country', 5, { bucketKey: 'users' });
    * // [{ 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);
+    const { labelField, order, dateRange, ...rest } = options;
+    return this.query({ queryType: "topN", field, n, labelField, order, dateRange }, rest);
   }
   // ── 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');
+   * const { data } = await db.analytics.stats('score', { bucketKey: 'users' });
    * console.log(data.avg, data.p99);
    */
   async stats(field, options) {
-    return this.query({ queryType: "stats", field, dateRange: options?.dateRange }, options);
+    const { dateRange, ...rest } = options;
+    return this.query({ queryType: "stats", field, dateRange }, rest);
   }
   // ── records ────────────────────────────────────────────────────────────────
   /**
    * Filtered, paginated raw records with optional field projection.
    * Supports filter ops: == != > < >= <= CONTAINS
-   * Server `queryType`: **"records"**
    *
    * @example
    * const { data } = await db.analytics.records({
+   *   bucketKey: 'users',
    *   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);
+    const { filters, selectFields, limit, offset, orderBy, order, dateRange, ...rest } = options;
+    return this.query(
+      { queryType: "records", filters, selectFields, limit, offset, orderBy, order, dateRange },
+      rest
+    );
   }
   // ── multiMetric ────────────────────────────────────────────────────────────
   /**
-   * Multiple aggregations in a single BigQuery call — ideal for dashboard stat cards.
-   * Server `queryType`: **"multiMetric"**
+   * Multiple aggregations in a single call — ideal for dashboard stat cards.
    *
    * @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);
+   * const { data } = await db.analytics.multiMetric(
+   *   [
+   *     { name: 'totalRevenue', field: 'amount', aggregation: 'sum' },
+   *     { name: 'avgScore',     field: 'score',  aggregation: 'avg' },
+   *   ],
+   *   { bucketKey: 'orders' }
+   * );
+   * console.log(data.totalRevenue, data.avgScore);
    */
   async multiMetric(metrics, options) {
-    return this.query({
-      queryType: "multiMetric",
-      metrics,
-      dateRange: options?.dateRange
-    }, options);
+    const { dateRange, ...rest } = options;
+    return this.query({ queryType: "multiMetric", metrics, dateRange }, rest);
   }
   // ── storageStats ───────────────────────────────────────────────────────────
   /**
-   * Storage statistics for the bucket — total records, bytes, avg/min/max size.
-   * Server `queryType`: **"storageStats"**
+   * Storage statistics for a bucket — total records, bytes, avg/min/max size.
    *
    * @example
-   * const { data } = await db.analytics.storageStats();
+   * const { data } = await db.analytics.storageStats({ bucketKey: 'orders' });
    * console.log(data.totalRecords, data.totalBytes);
    */
   async storageStats(options) {
-    return this.query({ queryType: "storageStats", dateRange: options?.dateRange }, options);
+    const { dateRange, ...rest } = options;
+    return this.query({ queryType: "storageStats", dateRange }, rest);
   }
   // ── crossBucket ────────────────────────────────────────────────────────────
   /**
    * Compare a metric across multiple buckets in one query.
-   * Server `queryType`: **"crossBucket"**
+   * Note: `bucketKey` here is used only for auth — the actual buckets
+   * compared are specified via `bucketKeys`.
    *
    * @example
    * const { data } = await db.analytics.crossBucket({
-   *   bucketKeys:  ['sales', 'refunds', 'trials'],
+   *   bucketKey:   'sales-2025',   // auth bucket
+   *   bucketKeys:  ['sales-2024', 'sales-2025'],
    *   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);
+    const { bucketKeys, field, aggregation, dateRange, ...rest } = options;
+    return this.query({ queryType: "crossBucket", bucketKeys, field, aggregation, dateRange }, rest);
   }
 };
 
@@ -785,7 +750,7 @@ var AnalyticsClient = class {
 var HydrousClient = class {
   constructor(config) {
     if (!config.authKey) throw new Error("[hydrousdb] authKey is required");
-    if (!config.bucketKey) throw new Error("[hydrousdb] bucketKey is required");
+    if (!config.securityKey) throw new Error("[hydrousdb] securityKey is required");
     this.http = new HttpClient(config);
     this.records = new RecordsClient(this.http);
     this.auth = new AuthClient(this.http);