@lssm/lib.metering 0.0.0-canary-20251217054315 → 0.0.0-canary-20251217060804

package/dist/aggregation/index.d.ts

@@ -0,0 +1,155 @@
+//#region src/aggregation/index.d.ts
+/**
+ * Usage aggregation engine.
+ *
+ * Provides periodic aggregation of usage records into summaries
+ * for efficient billing and reporting queries.
+ */
+type PeriodType = 'HOURLY' | 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'YEARLY';
+type AggregationType = 'COUNT' | 'SUM' | 'AVG' | 'MAX' | 'MIN' | 'LAST';
+interface UsageRecord {
+  id: string;
+  metricKey: string;
+  subjectType: string;
+  subjectId: string;
+  quantity: number;
+  timestamp: Date;
+}
+interface UsageSummary {
+  id: string;
+  metricKey: string;
+  subjectType: string;
+  subjectId: string;
+  periodType: PeriodType;
+  periodStart: Date;
+  periodEnd: Date;
+  totalQuantity: number;
+  recordCount: number;
+  minQuantity?: number;
+  maxQuantity?: number;
+  avgQuantity?: number;
+}
+interface MetricDefinition {
+  key: string;
+  aggregationType: AggregationType;
+}
+interface UsageStorage {
+  /**
+   * Get unaggregated records for a period.
+   */
+  getUnaggregatedRecords(options: {
+    metricKey?: string;
+    periodStart: Date;
+    periodEnd: Date;
+    limit?: number;
+  }): Promise<UsageRecord[]>;
+  /**
+   * Mark records as aggregated.
+   */
+  markRecordsAggregated(recordIds: string[], aggregatedAt: Date): Promise<void>;
+  /**
+   * Get or create a summary record.
+   */
+  upsertSummary(summary: Omit<UsageSummary, 'id'>): Promise<UsageSummary>;
+  /**
+   * Get metric definition.
+   */
+  getMetric(key: string): Promise<MetricDefinition | null>;
+  /**
+   * List all active metrics.
+   */
+  listMetrics(): Promise<MetricDefinition[]>;
+}
+interface AggregationOptions {
+  /** Storage implementation */
+  storage: UsageStorage;
+  /** Batch size for processing records */
+  batchSize?: number;
+}
+interface AggregateParams {
+  /** Period type to aggregate */
+  periodType: PeriodType;
+  /** Period start time */
+  periodStart: Date;
+  /** Period end time (optional, defaults to period boundary) */
+  periodEnd?: Date;
+  /** Specific metric to aggregate (optional, aggregates all if not specified) */
+  metricKey?: string;
+}
+interface AggregationResult {
+  periodType: PeriodType;
+  periodStart: Date;
+  periodEnd: Date;
+  recordsProcessed: number;
+  summariesCreated: number;
+  summariesUpdated: number;
+  errors: AggregationError[];
+}
+interface AggregationError {
+  metricKey: string;
+  subjectType: string;
+  subjectId: string;
+  error: string;
+}
+/**
+ * Get the start of a period for a given date.
+ */
+declare function getPeriodStart(date: Date, periodType: PeriodType): Date;
+/**
+ * Get the end of a period for a given date.
+ */
+declare function getPeriodEnd(date: Date, periodType: PeriodType): Date;
+/**
+ * Format a period key for grouping.
+ */
+declare function formatPeriodKey(date: Date, periodType: PeriodType): string;
+/**
+ * Usage aggregator.
+ *
+ * Aggregates usage records into summaries based on period type.
+ */
+declare class UsageAggregator {
+  private storage;
+  private batchSize;
+  constructor(options: AggregationOptions);
+  /**
+   * Aggregate usage records for a period.
+   */
+  aggregate(params: AggregateParams): Promise<AggregationResult>;
+  /**
+   * Group records by metric, subject, and period.
+   */
+  private groupRecords;
+  /**
+   * Aggregate a group of records into a summary.
+   */
+  private aggregateGroup;
+  /**
+   * Calculate aggregation values.
+   */
+  private calculateAggregation;
+}
+/**
+ * In-memory usage storage for testing.
+ */
+declare class InMemoryUsageStorage implements UsageStorage {
+  private records;
+  private summaries;
+  private metrics;
+  addRecord(record: UsageRecord): void;
+  addMetric(metric: MetricDefinition): void;
+  getUnaggregatedRecords(options: {
+    metricKey?: string;
+    periodStart: Date;
+    periodEnd: Date;
+    limit?: number;
+  }): Promise<UsageRecord[]>;
+  markRecordsAggregated(recordIds: string[]): Promise<void>;
+  upsertSummary(summary: Omit<UsageSummary, 'id'>): Promise<UsageSummary>;
+  getMetric(key: string): Promise<MetricDefinition | null>;
+  listMetrics(): Promise<MetricDefinition[]>;
+  getSummaries(): UsageSummary[];
+  clear(): void;
+}
+//#endregion
+export { AggregateParams, AggregationError, AggregationOptions, AggregationResult, AggregationType, InMemoryUsageStorage, MetricDefinition, PeriodType, UsageAggregator, UsageRecord, UsageStorage, UsageSummary, formatPeriodKey, getPeriodEnd, getPeriodStart };