hydrousdb 1.1.1 → 2.0.0

package/dist/analytics/index.d.mts

@@ -1,5 +1,5 @@
-import { a9 as HttpClient, c as AnalyticsQuery, V as RequestOptions, e as AnalyticsResponse, D as DateRange, C as CountResult, p as DistributionItem, a1 as SumResult, a2 as TimeSeriesPoint, r as FieldTimeSeriesPoint, a3 as TopNItem, F as FieldStatsResult, s as Filter, u as FilteredRecordsResult, M as MultiMetricItem, a0 as StorageStatsResult } from '../http-DbiqdKlw.mjs';
-export { d as AnalyticsQueryType } from '../http-DbiqdKlw.mjs';
+import { a9 as HttpClient, c as AnalyticsQuery, V as RequestOptions, e as AnalyticsResponse, D as DateRange, C as CountResult, p as DistributionItem, a1 as SumResult, a2 as TimeSeriesPoint, r as FieldTimeSeriesPoint, a3 as TopNItem, F as FieldStatsResult, s as Filter, u as FilteredRecordsResult, M as MultiMetricItem, a0 as StorageStatsResult } from '../http-DTukpdAU.mjs';
+export { d as AnalyticsQueryType } from '../http-DTukpdAU.mjs';
 
 type AnalyticsResult<T> = Omit<AnalyticsResponse, 'data'> & {
     data: T;
@@ -7,121 +7,126 @@ type AnalyticsResult<T> = Omit<AnalyticsResponse, 'data'> & {
     bucketKey: string | null;
     projectId: string;
 };
+/** Options accepted by every analytics method */
+interface BucketOptions {
+    /**
+     * The bucket to run the analytics query against.
+     * Required on all analytics calls.
+     *
+     * @example
+     * const { data } = await db.analytics.count({ bucketKey: 'orders' });
+     */
+    bucketKey: string;
+}
 declare class AnalyticsClient {
     private readonly http;
     constructor(http: HttpClient);
-    private get path();
+    /** Builds the path for a given bucket: /api/analytics/:bucketKey/:securityKey */
+    private path;
     /**
      * Run any analytics query with full control over the payload.
      * Prefer the typed convenience methods below for everyday use.
      */
-    query<T = unknown>(payload: AnalyticsQuery, opts?: RequestOptions): Promise<AnalyticsResult<T>>;
+    query<T = unknown>(payload: AnalyticsQuery, options: BucketOptions & RequestOptions): Promise<AnalyticsResult<T>>;
     /**
      * 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' },
      * });
      */
-    count(options?: {
+    count(options: {
         dateRange?: DateRange;
-    } & RequestOptions): Promise<AnalyticsResult<CountResult>>;
+    } & BucketOptions & RequestOptions): Promise<AnalyticsResult<CountResult>>;
     /**
      * 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 }]
      */
-    distribution(field: string, options?: {
+    distribution(field: string, options: {
         limit?: number;
         order?: 'asc' | 'desc';
         dateRange?: DateRange;
-    } & RequestOptions): Promise<AnalyticsResult<DistributionItem[]>>;
+    } & BucketOptions & RequestOptions): Promise<AnalyticsResult<DistributionItem[]>>;
     /**
      * 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' });
      */
-    sum(field: string, options?: {
+    sum(field: string, options: {
         groupBy?: string;
         limit?: number;
         dateRange?: DateRange;
-    } & RequestOptions): Promise<AnalyticsResult<SumResult>>;
+    } & BucketOptions & RequestOptions): Promise<AnalyticsResult<SumResult>>;
     /**
      * 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 }, ...]
      */
-    timeSeries(options?: {
+    timeSeries(options: {
         granularity?: 'hour' | 'day' | 'week' | 'month';
         dateRange?: DateRange;
-    } & RequestOptions): Promise<AnalyticsResult<TimeSeriesPoint[]>>;
+    } & BucketOptions & RequestOptions): Promise<AnalyticsResult<TimeSeriesPoint[]>>;
     /**
      * Aggregate a numeric field over time.
-     * Server `queryType`: **"fieldTimeSeries"**
      *
      * @example
      * const { data } = await db.analytics.fieldTimeSeries('revenue', {
+     *   bucketKey: 'orders',
      *   granularity: 'month',
      *   aggregation: 'sum',
      * });
      */
-    fieldTimeSeries(field: string, options?: {
+    fieldTimeSeries(field: string, options: {
         aggregation?: 'sum' | 'avg' | 'min' | 'max' | 'count';
         granularity?: 'hour' | 'day' | 'week' | 'month';
         dateRange?: DateRange;
-    } & RequestOptions): Promise<AnalyticsResult<FieldTimeSeriesPoint[]>>;
+    } & BucketOptions & RequestOptions): Promise<AnalyticsResult<FieldTimeSeriesPoint[]>>;
     /**
      * 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 }, ...]
      */
-    topN(field: string, n?: number, options?: {
+    topN(field: string, n: number | undefined, options: {
         labelField?: string;
         order?: 'asc' | 'desc';
         dateRange?: DateRange;
-    } & RequestOptions): Promise<AnalyticsResult<TopNItem[]>>;
+    } & BucketOptions & RequestOptions): Promise<AnalyticsResult<TopNItem[]>>;
     /**
      * 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);
      */
-    stats(field: string, options?: {
+    stats(field: string, options: {
         dateRange?: DateRange;
-    } & RequestOptions): Promise<AnalyticsResult<FieldStatsResult>>;
+    } & BucketOptions & RequestOptions): Promise<AnalyticsResult<FieldStatsResult>>;
     /**
      * 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);
      */
-    records(options?: {
+    records(options: {
         filters?: Filter[];
         selectFields?: string[];
         limit?: number;
@@ -129,40 +134,42 @@ declare class AnalyticsClient {
         orderBy?: string;
         order?: 'asc' | 'desc';
         dateRange?: DateRange;
-    } & RequestOptions): Promise<AnalyticsResult<FilteredRecordsResult>>;
+    } & BucketOptions & RequestOptions): Promise<AnalyticsResult<FilteredRecordsResult>>;
     /**
-     * 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);
      */
-    multiMetric(metrics: MultiMetricItem[], options?: {
+    multiMetric(metrics: MultiMetricItem[], options: {
         dateRange?: DateRange;
-    } & RequestOptions): Promise<AnalyticsResult<Record<string, number>>>;
+    } & BucketOptions & RequestOptions): Promise<AnalyticsResult<Record<string, number>>>;
     /**
-     * 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);
      */
-    storageStats(options?: {
+    storageStats(options: {
         dateRange?: DateRange;
-    } & RequestOptions): Promise<AnalyticsResult<StorageStatsResult>>;
+    } & BucketOptions & RequestOptions): Promise<AnalyticsResult<StorageStatsResult>>;
     /**
      * 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',
      * });
@@ -172,7 +179,7 @@ declare class AnalyticsClient {
         field: string;
         aggregation?: 'sum' | 'avg' | 'min' | 'max' | 'count';
         dateRange?: DateRange;
-    } & RequestOptions): Promise<AnalyticsResult<unknown>>;
+    } & BucketOptions & RequestOptions): Promise<AnalyticsResult<unknown>>;
 }
 
-export { AnalyticsClient, AnalyticsQuery, AnalyticsResponse, CountResult, DateRange, DistributionItem, FieldStatsResult, FieldTimeSeriesPoint, Filter, FilteredRecordsResult, MultiMetricItem, StorageStatsResult, SumResult, TimeSeriesPoint, TopNItem };
+export { AnalyticsClient, AnalyticsQuery, AnalyticsResponse, type BucketOptions, CountResult, DateRange, DistributionItem, FieldStatsResult, FieldTimeSeriesPoint, Filter, FilteredRecordsResult, MultiMetricItem, StorageStatsResult, SumResult, TimeSeriesPoint, TopNItem };

package/dist/analytics/index.d.ts

@@ -1,5 +1,5 @@
-import { a9 as HttpClient, c as AnalyticsQuery, V as RequestOptions, e as AnalyticsResponse, D as DateRange, C as CountResult, p as DistributionItem, a1 as SumResult, a2 as TimeSeriesPoint, r as FieldTimeSeriesPoint, a3 as TopNItem, F as FieldStatsResult, s as Filter, u as FilteredRecordsResult, M as MultiMetricItem, a0 as StorageStatsResult } from '../http-DbiqdKlw.js';
-export { d as AnalyticsQueryType } from '../http-DbiqdKlw.js';
+import { a9 as HttpClient, c as AnalyticsQuery, V as RequestOptions, e as AnalyticsResponse, D as DateRange, C as CountResult, p as DistributionItem, a1 as SumResult, a2 as TimeSeriesPoint, r as FieldTimeSeriesPoint, a3 as TopNItem, F as FieldStatsResult, s as Filter, u as FilteredRecordsResult, M as MultiMetricItem, a0 as StorageStatsResult } from '../http-DTukpdAU.js';
+export { d as AnalyticsQueryType } from '../http-DTukpdAU.js';
 
 type AnalyticsResult<T> = Omit<AnalyticsResponse, 'data'> & {
     data: T;
@@ -7,121 +7,126 @@ type AnalyticsResult<T> = Omit<AnalyticsResponse, 'data'> & {
     bucketKey: string | null;
     projectId: string;
 };
+/** Options accepted by every analytics method */
+interface BucketOptions {
+    /**
+     * The bucket to run the analytics query against.
+     * Required on all analytics calls.
+     *
+     * @example
+     * const { data } = await db.analytics.count({ bucketKey: 'orders' });
+     */
+    bucketKey: string;
+}
 declare class AnalyticsClient {
     private readonly http;
     constructor(http: HttpClient);
-    private get path();
+    /** Builds the path for a given bucket: /api/analytics/:bucketKey/:securityKey */
+    private path;
     /**
      * Run any analytics query with full control over the payload.
      * Prefer the typed convenience methods below for everyday use.
      */
-    query<T = unknown>(payload: AnalyticsQuery, opts?: RequestOptions): Promise<AnalyticsResult<T>>;
+    query<T = unknown>(payload: AnalyticsQuery, options: BucketOptions & RequestOptions): Promise<AnalyticsResult<T>>;
     /**
      * 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' },
      * });
      */
-    count(options?: {
+    count(options: {
         dateRange?: DateRange;
-    } & RequestOptions): Promise<AnalyticsResult<CountResult>>;
+    } & BucketOptions & RequestOptions): Promise<AnalyticsResult<CountResult>>;
     /**
      * 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 }]
      */
-    distribution(field: string, options?: {
+    distribution(field: string, options: {
         limit?: number;
         order?: 'asc' | 'desc';
         dateRange?: DateRange;
-    } & RequestOptions): Promise<AnalyticsResult<DistributionItem[]>>;
+    } & BucketOptions & RequestOptions): Promise<AnalyticsResult<DistributionItem[]>>;
     /**
      * 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' });
      */
-    sum(field: string, options?: {
+    sum(field: string, options: {
         groupBy?: string;
         limit?: number;
         dateRange?: DateRange;
-    } & RequestOptions): Promise<AnalyticsResult<SumResult>>;
+    } & BucketOptions & RequestOptions): Promise<AnalyticsResult<SumResult>>;
     /**
      * 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 }, ...]
      */
-    timeSeries(options?: {
+    timeSeries(options: {
         granularity?: 'hour' | 'day' | 'week' | 'month';
         dateRange?: DateRange;
-    } & RequestOptions): Promise<AnalyticsResult<TimeSeriesPoint[]>>;
+    } & BucketOptions & RequestOptions): Promise<AnalyticsResult<TimeSeriesPoint[]>>;
     /**
      * Aggregate a numeric field over time.
-     * Server `queryType`: **"fieldTimeSeries"**
      *
      * @example
      * const { data } = await db.analytics.fieldTimeSeries('revenue', {
+     *   bucketKey: 'orders',
      *   granularity: 'month',
      *   aggregation: 'sum',
      * });
      */
-    fieldTimeSeries(field: string, options?: {
+    fieldTimeSeries(field: string, options: {
         aggregation?: 'sum' | 'avg' | 'min' | 'max' | 'count';
         granularity?: 'hour' | 'day' | 'week' | 'month';
         dateRange?: DateRange;
-    } & RequestOptions): Promise<AnalyticsResult<FieldTimeSeriesPoint[]>>;
+    } & BucketOptions & RequestOptions): Promise<AnalyticsResult<FieldTimeSeriesPoint[]>>;
     /**
      * 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 }, ...]
      */
-    topN(field: string, n?: number, options?: {
+    topN(field: string, n: number | undefined, options: {
         labelField?: string;
         order?: 'asc' | 'desc';
         dateRange?: DateRange;
-    } & RequestOptions): Promise<AnalyticsResult<TopNItem[]>>;
+    } & BucketOptions & RequestOptions): Promise<AnalyticsResult<TopNItem[]>>;
     /**
      * 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);
      */
-    stats(field: string, options?: {
+    stats(field: string, options: {
         dateRange?: DateRange;
-    } & RequestOptions): Promise<AnalyticsResult<FieldStatsResult>>;
+    } & BucketOptions & RequestOptions): Promise<AnalyticsResult<FieldStatsResult>>;
     /**
      * 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);
      */
-    records(options?: {
+    records(options: {
         filters?: Filter[];
         selectFields?: string[];
         limit?: number;
@@ -129,40 +134,42 @@ declare class AnalyticsClient {
         orderBy?: string;
         order?: 'asc' | 'desc';
         dateRange?: DateRange;
-    } & RequestOptions): Promise<AnalyticsResult<FilteredRecordsResult>>;
+    } & BucketOptions & RequestOptions): Promise<AnalyticsResult<FilteredRecordsResult>>;
     /**
-     * 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);
      */
-    multiMetric(metrics: MultiMetricItem[], options?: {
+    multiMetric(metrics: MultiMetricItem[], options: {
         dateRange?: DateRange;
-    } & RequestOptions): Promise<AnalyticsResult<Record<string, number>>>;
+    } & BucketOptions & RequestOptions): Promise<AnalyticsResult<Record<string, number>>>;
     /**
-     * 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);
      */
-    storageStats(options?: {
+    storageStats(options: {
         dateRange?: DateRange;
-    } & RequestOptions): Promise<AnalyticsResult<StorageStatsResult>>;
+    } & BucketOptions & RequestOptions): Promise<AnalyticsResult<StorageStatsResult>>;
     /**
      * 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',
      * });
@@ -172,7 +179,7 @@ declare class AnalyticsClient {
         field: string;
         aggregation?: 'sum' | 'avg' | 'min' | 'max' | 'count';
         dateRange?: DateRange;
-    } & RequestOptions): Promise<AnalyticsResult<unknown>>;
+    } & BucketOptions & RequestOptions): Promise<AnalyticsResult<unknown>>;
 }
 
-export { AnalyticsClient, AnalyticsQuery, AnalyticsResponse, CountResult, DateRange, DistributionItem, FieldStatsResult, FieldTimeSeriesPoint, Filter, FilteredRecordsResult, MultiMetricItem, StorageStatsResult, SumResult, TimeSeriesPoint, TopNItem };
+export { AnalyticsClient, AnalyticsQuery, AnalyticsResponse, type BucketOptions, CountResult, DateRange, DistributionItem, FieldStatsResult, FieldTimeSeriesPoint, Filter, FilteredRecordsResult, MultiMetricItem, StorageStatsResult, SumResult, TimeSeriesPoint, TopNItem };