@contractspec/lib.metering 0.0.0-canary-20260113162409

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chaman Ventures, SASU
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,198 @@
+# @contractspec/lib.metering
+
+Website: https://contractspec.io/
+
+
+Usage metering and billing core module for ContractSpec applications.
+
+## Overview
+
+This module provides a reusable metering system that can be used to track usage-based metrics across all ContractSpec applications. It supports:
+
+- **Metric Definitions**: Define what metrics to track
+- **Usage Recording**: Record usage events
+- **Aggregation**: Roll up usage into summaries
+- **Thresholds & Alerts**: Monitor usage against limits
+- **Billing Integration**: Connect usage to billing/plans
+
+## Entities
+
+### MetricDefinition
+
+Defines a trackable metric.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| id | string | Unique identifier |
+| key | string | Metric key (e.g., `api_calls`, `storage_gb`) |
+| name | string | Human-readable name |
+| description | string | Metric description |
+| unit | string | Unit of measurement |
+| aggregationType | enum | How to aggregate (count, sum, avg, max, min) |
+| resetPeriod | enum | When to reset (never, hourly, daily, monthly) |
+| orgId | string | Organization scope (null = global) |
+
+### UsageRecord
+
+Individual usage event.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| id | string | Unique identifier |
+| metricKey | string | Metric being recorded |
+| subjectType | string | Subject type (org, user, project) |
+| subjectId | string | Subject identifier |
+| quantity | decimal | Usage quantity |
+| timestamp | datetime | When usage occurred |
+| metadata | json | Additional context |
+
+### UsageSummary
+
+Pre-aggregated usage summary.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| id | string | Unique identifier |
+| metricKey | string | Metric key |
+| subjectType | string | Subject type |
+| subjectId | string | Subject identifier |
+| periodType | enum | Period type (hourly, daily, monthly) |
+| periodStart | datetime | Period start time |
+| periodEnd | datetime | Period end time |
+| totalQuantity | decimal | Aggregated quantity |
+| recordCount | int | Number of records aggregated |
+
+### UsageThreshold
+
+Threshold configuration for alerts.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| id | string | Unique identifier |
+| metricKey | string | Metric to monitor |
+| subjectType | string | Subject type |
+| subjectId | string | Subject identifier |
+| threshold | decimal | Threshold value |
+| action | enum | Action when exceeded (alert, block, none) |
+| notifyEmails | json | Email addresses to notify |
+
+## Contracts
+
+### Commands
+
+- `metric.define` - Define a new metric
+- `metric.update` - Update metric definition
+- `metric.delete` - Delete a metric
+- `usage.record` - Record a usage event
+- `usage.recordBatch` - Record multiple usage events
+- `threshold.create` - Create a usage threshold
+- `threshold.update` - Update a threshold
+- `threshold.delete` - Delete a threshold
+
+### Queries
+
+- `metric.get` - Get metric definition
+- `metric.list` - List all metrics
+- `usage.get` - Get usage for a subject
+- `usage.getSummary` - Get aggregated usage summary
+- `usage.export` - Export usage data
+- `threshold.list` - List thresholds
+
+## Events
+
+- `metric.defined` - Metric was defined
+- `usage.recorded` - Usage was recorded
+- `usage.aggregated` - Usage was aggregated into summary
+- `threshold.exceeded` - Usage exceeded a threshold
+- `threshold.approaching` - Usage approaching threshold (80%)
+
+## Usage
+
+```typescript
+import { 
+  MetricDefinitionEntity,
+  RecordUsageContract,
+  UsageAggregator 
+} from '@contractspec/lib.metering';
+
+// Define a metric
+await meteringService.defineMetric({
+  key: 'api_calls',
+  name: 'API Calls',
+  unit: 'calls',
+  aggregationType: 'COUNT',
+  resetPeriod: 'MONTHLY',
+});
+
+// Record usage
+await meteringService.recordUsage({
+  metricKey: 'api_calls',
+  subjectType: 'org',
+  subjectId: 'org-123',
+  quantity: 1,
+});
+
+// Get usage summary
+const summary = await meteringService.getUsageSummary({
+  metricKey: 'api_calls',
+  subjectType: 'org',
+  subjectId: 'org-123',
+  periodType: 'MONTHLY',
+  periodStart: new Date('2024-01-01'),
+});
+```
+
+## Aggregation
+
+The module includes an aggregation engine that periodically rolls up usage records:
+
+```typescript
+import { UsageAggregator } from '@contractspec/lib.metering/aggregation';
+
+const aggregator = new UsageAggregator({
+  storage: usageStorage,
+});
+
+// Run hourly aggregation
+await aggregator.aggregate({
+  periodType: 'HOURLY',
+  periodStart: new Date(),
+});
+```
+
+## Integration
+
+This module integrates with:
+
+- `@contractspec/lib.jobs` - Scheduled aggregation jobs
+- `@contractspec/module.notifications` - Threshold alerts
+- `@contractspec/lib.identity-rbac` - Subject resolution
+
+## Schema Contribution
+
+```typescript
+import { meteringSchemaContribution } from '@contractspec/lib.metering';
+
+export const schemaComposition = {
+  modules: [
+    meteringSchemaContribution,
+    // ... other modules
+  ],
+};
+```
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

package/dist/aggregation/index.d.ts

@@ -0,0 +1,156 @@
+//#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 };
+//# sourceMappingURL=index.d.ts.map

package/dist/aggregation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/aggregation/index.ts"],"sourcesContent":[],"mappings":";;AASA;AACA;AAEA;AASA;;AAMe,KAlBH,UAAA,GAkBG,QAAA,GAAA,OAAA,GAAA,QAAA,GAAA,SAAA,GAAA,QAAA;AACF,KAlBD,eAAA,GAkBC,OAAA,GAAA,KAAA,GAAA,KAAA,GAAA,KAAA,GAAA,KAAA,GAAA,MAAA;AAAI,UAhBA,WAAA,CAgBA;EAQA,EAAA,EAAA,MAAA;EAKA,SAAA,EAAA,MAAY;EAMZ,WAAA,EAAA,MAAA;EACF,SAAA,EAAA,MAAA;EAED,QAAA,EAAA,MAAA;EAAR,SAAA,EAhCO,IAgCP;;AAK4D,UAlCjD,YAAA,CAkCiD;EAKpC,EAAA,EAAA,MAAA;EAAL,SAAA,EAAA,MAAA;EAAmC,WAAA,EAAA,MAAA;EAAR,SAAA,EAAA,MAAA;EAKlB,UAAA,EAvCpB,UAuCoB;EAAR,WAAA,EAtCX,IAsCW;EAKD,SAAA,EA1CZ,IA0CY;EAAR,aAAA,EAAA,MAAA;EAAO,WAAA,EAAA,MAAA;EAGP,WAAA,CAAA,EAAA,MAAA;EAOA,WAAA,CAAA,EAAA,MAAe;EAElB,WAAA,CAAA,EAAA,MAAA;;AAIA,UAlDG,gBAAA,CAkDH;EAAI,GAAA,EAAA,MAAA;EAKD,eAAA,EArDE,eAqDe;;AAEnB,UApDE,YAAA,CAoDF;EACF;;;EAOI,sBAAgB,CAAA,OAAA,EAAA;IAYjB,SAAA,CAAA,EAAA,MAAc;IAAO,WAAA,EAlEpB,IAkEoB;IAAkB,SAAA,EAjExC,IAiEwC;IAAa,KAAA,CAAA,EAAA,MAAA;EAAI,CAAA,CAAA,EA/DlE,OA+DkE,CA/D1D,WA+D0D,EAAA,CAAA;EAkCxD;;;EAAkD,qBAAA,CAAA,SAAA,EAAA,MAAA,EAAA,EAAA,YAAA,EA5FP,IA4FO,CAAA,EA5FA,OA4FA,CAAA,IAAA,CAAA;EAAI;AA8BtE;AAyCA;EAIuB,aAAA,CAAA,OAAA,EAlKE,IAkKF,CAlKO,YAkKP,EAAA,IAAA,CAAA,CAAA,EAlK6B,OAkK7B,CAlKqC,YAkKrC,CAAA;EAQG;;;EAAyB,SAAA,CAAA,GAAA,EAAA,MAAA,CAAA,EArKzB,OAqKyB,CArKjB,gBAqKiB,GAAA,IAAA,CAAA;EAyKtC;;;EAeI,WAAA,EAAA,EAxVA,OAwVA,CAxVQ,gBAwVR,EAAA,CAAA;;AAGH,UAxVG,kBAAA,CAwVH;EAAR;EAgB8C,OAAA,EAtWzC,YAsWyC;EAKlC;EAAL,SAAA,CAAA,EAAA,MAAA;;AACR,UAvWY,eAAA,CAuWZ;EAgCmC;EAAR,UAAA,EArYlB,UAqYkB;EAID;EAAR,WAAA,EAvYR,IAuYQ;EAIL;EAhF2B,SAAA,CAAA,EAzT/B,IAyT+B;EAAY;;;UApTxC,iBAAA;cACH;eACC;aACF;;;;UAIH;;UAGO,gBAAA;;;;;;;;;iBAYD,cAAA,OAAqB,kBAAkB,aAAa;;;;iBAkCpD,YAAA,OAAmB,kBAAkB,aAAa;;;;iBA8BlD,eAAA,OAAsB,kBAAkB;;;;;;cAyC3C,eAAA;;;uBAIU;;;;oBAQG,kBAAkB,QAAQ;;;;;;;;;;;;;;;;;cAyKvC,oBAAA,YAAgC;;;;oBAKzB;oBAIA;;;iBAMH;eACF;;MAET,QAAQ;8CAgBsC;yBAKvC,KAAK,sBACb,QAAQ;0BAgCmB,QAAQ;iBAIjB,QAAQ;kBAIb"}

package/dist/aggregation/index.js

@@ -0,0 +1,274 @@
+//#region src/aggregation/index.ts
+/**
+* Get the start of a period for a given date.
+*/
+function getPeriodStart(date, periodType) {
+	const d = new Date(date);
+	switch (periodType) {
+		case "HOURLY":
+			d.setMinutes(0, 0, 0);
+			return d;
+		case "DAILY":
+			d.setHours(0, 0, 0, 0);
+			return d;
+		case "WEEKLY": {
+			d.setHours(0, 0, 0, 0);
+			const day = d.getDay();
+			d.setDate(d.getDate() - day);
+			return d;
+		}
+		case "MONTHLY":
+			d.setHours(0, 0, 0, 0);
+			d.setDate(1);
+			return d;
+		case "YEARLY":
+			d.setHours(0, 0, 0, 0);
+			d.setMonth(0, 1);
+			return d;
+	}
+}
+/**
+* Get the end of a period for a given date.
+*/
+function getPeriodEnd(date, periodType) {
+	const start = getPeriodStart(date, periodType);
+	switch (periodType) {
+		case "HOURLY": return new Date(start.getTime() + 3600 * 1e3);
+		case "DAILY": return new Date(start.getTime() + 1440 * 60 * 1e3);
+		case "WEEKLY": return new Date(start.getTime() + 10080 * 60 * 1e3);
+		case "MONTHLY": {
+			const end = new Date(start);
+			end.setMonth(end.getMonth() + 1);
+			return end;
+		}
+		case "YEARLY": {
+			const end = new Date(start);
+			end.setFullYear(end.getFullYear() + 1);
+			return end;
+		}
+	}
+}
+/**
+* Format a period key for grouping.
+*/
+function formatPeriodKey(date, periodType) {
+	const start = getPeriodStart(date, periodType);
+	const year = start.getFullYear();
+	const month = String(start.getMonth() + 1).padStart(2, "0");
+	const day = String(start.getDate()).padStart(2, "0");
+	const hour = String(start.getHours()).padStart(2, "0");
+	switch (periodType) {
+		case "HOURLY": return `${year}-${month}-${day}T${hour}`;
+		case "DAILY": return `${year}-${month}-${day}`;
+		case "WEEKLY": return `${year}-W${getWeekNumber(start)}`;
+		case "MONTHLY": return `${year}-${month}`;
+		case "YEARLY": return `${year}`;
+	}
+}
+function getWeekNumber(date) {
+	const d = new Date(Date.UTC(date.getFullYear(), date.getMonth(), date.getDate()));
+	const dayNum = d.getUTCDay() || 7;
+	d.setUTCDate(d.getUTCDate() + 4 - dayNum);
+	const yearStart = new Date(Date.UTC(d.getUTCFullYear(), 0, 1));
+	const weekNum = Math.ceil(((d.getTime() - yearStart.getTime()) / 864e5 + 1) / 7);
+	return String(weekNum).padStart(2, "0");
+}
+/**
+* Usage aggregator.
+*
+* Aggregates usage records into summaries based on period type.
+*/
+var UsageAggregator = class {
+	storage;
+	batchSize;
+	constructor(options) {
+		this.storage = options.storage;
+		this.batchSize = options.batchSize || 1e3;
+	}
+	/**
+	* Aggregate usage records for a period.
+	*/
+	async aggregate(params) {
+		const { periodType, periodStart, metricKey } = params;
+		const periodEnd = params.periodEnd || getPeriodEnd(periodStart, periodType);
+		const result = {
+			periodType,
+			periodStart,
+			periodEnd,
+			recordsProcessed: 0,
+			summariesCreated: 0,
+			summariesUpdated: 0,
+			errors: []
+		};
+		const records = await this.storage.getUnaggregatedRecords({
+			metricKey,
+			periodStart,
+			periodEnd,
+			limit: this.batchSize
+		});
+		if (records.length === 0) return result;
+		const groups = this.groupRecords(records, periodType);
+		for (const [groupKey, groupRecords] of groups.entries()) try {
+			await this.aggregateGroup(groupKey, groupRecords, periodType, result);
+		} catch (error) {
+			const [metricKey$1, subjectType, subjectId] = groupKey.split("::");
+			result.errors.push({
+				metricKey: metricKey$1 ?? "unknown",
+				subjectType: subjectType ?? "unknown",
+				subjectId: subjectId ?? "unknown",
+				error: error instanceof Error ? error.message : String(error)
+			});
+		}
+		const recordIds = records.map((r) => r.id);
+		await this.storage.markRecordsAggregated(recordIds, /* @__PURE__ */ new Date());
+		result.recordsProcessed = records.length;
+		return result;
+	}
+	/**
+	* Group records by metric, subject, and period.
+	*/
+	groupRecords(records, periodType) {
+		const groups = /* @__PURE__ */ new Map();
+		for (const record of records) {
+			const periodKey = formatPeriodKey(record.timestamp, periodType);
+			const groupKey = `${record.metricKey}::${record.subjectType}::${record.subjectId}::${periodKey}`;
+			const existing = groups.get(groupKey) || [];
+			existing.push(record);
+			groups.set(groupKey, existing);
+		}
+		return groups;
+	}
+	/**
+	* Aggregate a group of records into a summary.
+	*/
+	async aggregateGroup(groupKey, records, periodType, result) {
+		const [metricKey, subjectType, subjectId] = groupKey.split("::");
+		if (!metricKey || !subjectType || !subjectId || records.length === 0) return;
+		const firstRecord = records[0];
+		if (!firstRecord) return;
+		const periodStart = getPeriodStart(firstRecord.timestamp, periodType);
+		const periodEnd = getPeriodEnd(firstRecord.timestamp, periodType);
+		const aggregationType = (await this.storage.getMetric(metricKey))?.aggregationType || "SUM";
+		const quantities = records.map((r) => r.quantity);
+		const aggregated = this.calculateAggregation(quantities, aggregationType);
+		await this.storage.upsertSummary({
+			metricKey,
+			subjectType,
+			subjectId,
+			periodType,
+			periodStart,
+			periodEnd,
+			totalQuantity: aggregated.total,
+			recordCount: records.length,
+			minQuantity: aggregated.min,
+			maxQuantity: aggregated.max,
+			avgQuantity: aggregated.avg
+		});
+		result.summariesCreated++;
+	}
+	/**
+	* Calculate aggregation values.
+	*/
+	calculateAggregation(quantities, aggregationType) {
+		if (quantities.length === 0) return {
+			total: 0,
+			min: 0,
+			max: 0,
+			avg: 0
+		};
+		const min = Math.min(...quantities);
+		const max = Math.max(...quantities);
+		const sum = quantities.reduce((a, b) => a + b, 0);
+		const avg = sum / quantities.length;
+		const count = quantities.length;
+		let total;
+		switch (aggregationType) {
+			case "COUNT":
+				total = count;
+				break;
+			case "SUM":
+				total = sum;
+				break;
+			case "AVG":
+				total = avg;
+				break;
+			case "MAX":
+				total = max;
+				break;
+			case "MIN":
+				total = min;
+				break;
+			case "LAST":
+				total = quantities[quantities.length - 1] ?? 0;
+				break;
+			default: total = sum;
+		}
+		return {
+			total,
+			min,
+			max,
+			avg
+		};
+	}
+};
+/**
+* In-memory usage storage for testing.
+*/
+var InMemoryUsageStorage = class {
+	records = [];
+	summaries = /* @__PURE__ */ new Map();
+	metrics = /* @__PURE__ */ new Map();
+	addRecord(record) {
+		this.records.push(record);
+	}
+	addMetric(metric) {
+		this.metrics.set(metric.key, metric);
+	}
+	async getUnaggregatedRecords(options) {
+		let records = this.records.filter((r) => {
+			const inPeriod = r.timestamp >= options.periodStart && r.timestamp < options.periodEnd;
+			const matchesMetric = !options.metricKey || r.metricKey === options.metricKey;
+			return inPeriod && matchesMetric;
+		});
+		if (options.limit) records = records.slice(0, options.limit);
+		return records;
+	}
+	async markRecordsAggregated(recordIds) {
+		this.records = this.records.filter((r) => !recordIds.includes(r.id));
+	}
+	async upsertSummary(summary) {
+		const key = `${summary.metricKey}::${summary.subjectType}::${summary.subjectId}::${summary.periodType}::${summary.periodStart.toISOString()}`;
+		const existing = this.summaries.get(key);
+		if (existing) {
+			existing.totalQuantity += summary.totalQuantity;
+			existing.recordCount += summary.recordCount;
+			if (summary.minQuantity !== void 0) existing.minQuantity = Math.min(existing.minQuantity ?? Infinity, summary.minQuantity);
+			if (summary.maxQuantity !== void 0) existing.maxQuantity = Math.max(existing.maxQuantity ?? -Infinity, summary.maxQuantity);
+			return existing;
+		}
+		const newSummary = {
+			id: `summary-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+			...summary
+		};
+		this.summaries.set(key, newSummary);
+		return newSummary;
+	}
+	async getMetric(key) {
+		return this.metrics.get(key) || null;
+	}
+	async listMetrics() {
+		return Array.from(this.metrics.values());
+	}
+	getSummaries() {
+		return Array.from(this.summaries.values());
+	}
+	clear() {
+		this.records = [];
+		this.summaries.clear();
+		this.metrics.clear();
+	}
+};
+
+//#endregion
+export { InMemoryUsageStorage, UsageAggregator, formatPeriodKey, getPeriodEnd, getPeriodStart };
+//# sourceMappingURL=index.js.map

package/dist/aggregation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["metricKey"],"sources":["../../src/aggregation/index.ts"],"sourcesContent":["/**\n * Usage aggregation engine.\n *\n * Provides periodic aggregation of usage records into summaries\n * for efficient billing and reporting queries.\n */\n\n// ============ Types ============\n\nexport type PeriodType = 'HOURLY' | 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'YEARLY';\nexport type AggregationType = 'COUNT' | 'SUM' | 'AVG' | 'MAX' | 'MIN' | 'LAST';\n\nexport interface UsageRecord {\n  id: string;\n  metricKey: string;\n  subjectType: string;\n  subjectId: string;\n  quantity: number;\n  timestamp: Date;\n}\n\nexport interface UsageSummary {\n  id: string;\n  metricKey: string;\n  subjectType: string;\n  subjectId: string;\n  periodType: PeriodType;\n  periodStart: Date;\n  periodEnd: Date;\n  totalQuantity: number;\n  recordCount: number;\n  minQuantity?: number;\n  maxQuantity?: number;\n  avgQuantity?: number;\n}\n\nexport interface MetricDefinition {\n  key: string;\n  aggregationType: AggregationType;\n}\n\nexport interface UsageStorage {\n  /**\n   * Get unaggregated records for a period.\n   */\n  getUnaggregatedRecords(options: {\n    metricKey?: string;\n    periodStart: Date;\n    periodEnd: Date;\n    limit?: number;\n  }): Promise<UsageRecord[]>;\n\n  /**\n   * Mark records as aggregated.\n   */\n  markRecordsAggregated(recordIds: string[], aggregatedAt: Date): Promise<void>;\n\n  /**\n   * Get or create a summary record.\n   */\n  upsertSummary(summary: Omit<UsageSummary, 'id'>): Promise<UsageSummary>;\n\n  /**\n   * Get metric definition.\n   */\n  getMetric(key: string): Promise<MetricDefinition | null>;\n\n  /**\n   * List all active metrics.\n   */\n  listMetrics(): Promise<MetricDefinition[]>;\n}\n\nexport interface AggregationOptions {\n  /** Storage implementation */\n  storage: UsageStorage;\n  /** Batch size for processing records */\n  batchSize?: number;\n}\n\nexport interface AggregateParams {\n  /** Period type to aggregate */\n  periodType: PeriodType;\n  /** Period start time */\n  periodStart: Date;\n  /** Period end time (optional, defaults to period boundary) */\n  periodEnd?: Date;\n  /** Specific metric to aggregate (optional, aggregates all if not specified) */\n  metricKey?: string;\n}\n\nexport interface AggregationResult {\n  periodType: PeriodType;\n  periodStart: Date;\n  periodEnd: Date;\n  recordsProcessed: number;\n  summariesCreated: number;\n  summariesUpdated: number;\n  errors: AggregationError[];\n}\n\nexport interface AggregationError {\n  metricKey: string;\n  subjectType: string;\n  subjectId: string;\n  error: string;\n}\n\n// ============ Period Helpers ============\n\n/**\n * Get the start of a period for a given date.\n */\nexport function getPeriodStart(date: Date, periodType: PeriodType): Date {\n  const d = new Date(date);\n\n  switch (periodType) {\n    case 'HOURLY':\n      d.setMinutes(0, 0, 0);\n      return d;\n\n    case 'DAILY':\n      d.setHours(0, 0, 0, 0);\n      return d;\n\n    case 'WEEKLY': {\n      d.setHours(0, 0, 0, 0);\n      const day = d.getDay();\n      d.setDate(d.getDate() - day);\n      return d;\n    }\n\n    case 'MONTHLY':\n      d.setHours(0, 0, 0, 0);\n      d.setDate(1);\n      return d;\n\n    case 'YEARLY':\n      d.setHours(0, 0, 0, 0);\n      d.setMonth(0, 1);\n      return d;\n  }\n}\n\n/**\n * Get the end of a period for a given date.\n */\nexport function getPeriodEnd(date: Date, periodType: PeriodType): Date {\n  const start = getPeriodStart(date, periodType);\n\n  switch (periodType) {\n    case 'HOURLY':\n      return new Date(start.getTime() + 60 * 60 * 1000);\n\n    case 'DAILY':\n      return new Date(start.getTime() + 24 * 60 * 60 * 1000);\n\n    case 'WEEKLY':\n      return new Date(start.getTime() + 7 * 24 * 60 * 60 * 1000);\n\n    case 'MONTHLY': {\n      const end = new Date(start);\n      end.setMonth(end.getMonth() + 1);\n      return end;\n    }\n\n    case 'YEARLY': {\n      const end = new Date(start);\n      end.setFullYear(end.getFullYear() + 1);\n      return end;\n    }\n  }\n}\n\n/**\n * Format a period key for grouping.\n */\nexport function formatPeriodKey(date: Date, periodType: PeriodType): string {\n  const start = getPeriodStart(date, periodType);\n  const year = start.getFullYear();\n  const month = String(start.getMonth() + 1).padStart(2, '0');\n  const day = String(start.getDate()).padStart(2, '0');\n  const hour = String(start.getHours()).padStart(2, '0');\n\n  switch (periodType) {\n    case 'HOURLY':\n      return `${year}-${month}-${day}T${hour}`;\n    case 'DAILY':\n      return `${year}-${month}-${day}`;\n    case 'WEEKLY':\n      return `${year}-W${getWeekNumber(start)}`;\n    case 'MONTHLY':\n      return `${year}-${month}`;\n    case 'YEARLY':\n      return `${year}`;\n  }\n}\n\nfunction getWeekNumber(date: Date): string {\n  const d = new Date(\n    Date.UTC(date.getFullYear(), date.getMonth(), date.getDate())\n  );\n  const dayNum = d.getUTCDay() || 7;\n  d.setUTCDate(d.getUTCDate() + 4 - dayNum);\n  const yearStart = new Date(Date.UTC(d.getUTCFullYear(), 0, 1));\n  const weekNum = Math.ceil(\n    ((d.getTime() - yearStart.getTime()) / 86400000 + 1) / 7\n  );\n  return String(weekNum).padStart(2, '0');\n}\n\n// ============ Aggregator ============\n\n/**\n * Usage aggregator.\n *\n * Aggregates usage records into summaries based on period type.\n */\nexport class UsageAggregator {\n  private storage: UsageStorage;\n  private batchSize: number;\n\n  constructor(options: AggregationOptions) {\n    this.storage = options.storage;\n    this.batchSize = options.batchSize || 1000;\n  }\n\n  /**\n   * Aggregate usage records for a period.\n   */\n  async aggregate(params: AggregateParams): Promise<AggregationResult> {\n    const { periodType, periodStart, metricKey } = params;\n    const periodEnd = params.periodEnd || getPeriodEnd(periodStart, periodType);\n\n    const result: AggregationResult = {\n      periodType,\n      periodStart,\n      periodEnd,\n      recordsProcessed: 0,\n      summariesCreated: 0,\n      summariesUpdated: 0,\n      errors: [],\n    };\n\n    // Get records to aggregate\n    const records = await this.storage.getUnaggregatedRecords({\n      metricKey,\n      periodStart,\n      periodEnd,\n      limit: this.batchSize,\n    });\n\n    if (records.length === 0) {\n      return result;\n    }\n\n    // Group records by metric, subject, and period\n    const groups = this.groupRecords(records, periodType);\n\n    // Process each group\n    for (const [groupKey, groupRecords] of groups.entries()) {\n      try {\n        await this.aggregateGroup(groupKey, groupRecords, periodType, result);\n      } catch (error) {\n        const [metricKey, subjectType, subjectId] = groupKey.split('::');\n        result.errors.push({\n          metricKey: metricKey ?? 'unknown',\n          subjectType: subjectType ?? 'unknown',\n          subjectId: subjectId ?? 'unknown',\n          error: error instanceof Error ? error.message : String(error),\n        });\n      }\n    }\n\n    // Mark records as aggregated\n    const recordIds = records.map((r) => r.id);\n    await this.storage.markRecordsAggregated(recordIds, new Date());\n    result.recordsProcessed = records.length;\n\n    return result;\n  }\n\n  /**\n   * Group records by metric, subject, and period.\n   */\n  private groupRecords(\n    records: UsageRecord[],\n    periodType: PeriodType\n  ): Map<string, UsageRecord[]> {\n    const groups = new Map<string, UsageRecord[]>();\n\n    for (const record of records) {\n      const periodKey = formatPeriodKey(record.timestamp, periodType);\n      const groupKey = `${record.metricKey}::${record.subjectType}::${record.subjectId}::${periodKey}`;\n\n      const existing = groups.get(groupKey) || [];\n      existing.push(record);\n      groups.set(groupKey, existing);\n    }\n\n    return groups;\n  }\n\n  /**\n   * Aggregate a group of records into a summary.\n   */\n  private async aggregateGroup(\n    groupKey: string,\n    records: UsageRecord[],\n    periodType: PeriodType,\n    result: AggregationResult\n  ): Promise<void> {\n    const [metricKey, subjectType, subjectId] = groupKey.split('::');\n\n    if (!metricKey || !subjectType || !subjectId || records.length === 0) {\n      return;\n    }\n\n    const firstRecord = records[0];\n    if (!firstRecord) return;\n    const periodStart = getPeriodStart(firstRecord.timestamp, periodType);\n    const periodEnd = getPeriodEnd(firstRecord.timestamp, periodType);\n\n    // Get metric definition for aggregation type\n    const metric = await this.storage.getMetric(metricKey);\n    const aggregationType = metric?.aggregationType || 'SUM';\n\n    // Calculate aggregated values\n    const quantities = records.map((r) => r.quantity);\n    const aggregated = this.calculateAggregation(quantities, aggregationType);\n\n    // Create or update summary\n    await this.storage.upsertSummary({\n      metricKey,\n      subjectType,\n      subjectId,\n      periodType,\n      periodStart,\n      periodEnd,\n      totalQuantity: aggregated.total,\n      recordCount: records.length,\n      minQuantity: aggregated.min,\n      maxQuantity: aggregated.max,\n      avgQuantity: aggregated.avg,\n    });\n\n    result.summariesCreated++;\n  }\n\n  /**\n   * Calculate aggregation values.\n   */\n  private calculateAggregation(\n    quantities: number[],\n    aggregationType: AggregationType\n  ): { total: number; min: number; max: number; avg: number } {\n    if (quantities.length === 0) {\n      return { total: 0, min: 0, max: 0, avg: 0 };\n    }\n\n    const min = Math.min(...quantities);\n    const max = Math.max(...quantities);\n    const sum = quantities.reduce((a, b) => a + b, 0);\n    const avg = sum / quantities.length;\n    const count = quantities.length;\n\n    let total: number;\n    switch (aggregationType) {\n      case 'COUNT':\n        total = count;\n        break;\n      case 'SUM':\n        total = sum;\n        break;\n      case 'AVG':\n        total = avg;\n        break;\n      case 'MAX':\n        total = max;\n        break;\n      case 'MIN':\n        total = min;\n        break;\n      case 'LAST':\n        total = quantities[quantities.length - 1] ?? 0;\n        break;\n      default:\n        total = sum;\n    }\n\n    return { total, min, max, avg };\n  }\n}\n\n// ============ In-Memory Storage ============\n\n/**\n * In-memory usage storage for testing.\n */\nexport class InMemoryUsageStorage implements UsageStorage {\n  private records: UsageRecord[] = [];\n  private summaries = new Map<string, UsageSummary>();\n  private metrics = new Map<string, MetricDefinition>();\n\n  addRecord(record: UsageRecord): void {\n    this.records.push(record);\n  }\n\n  addMetric(metric: MetricDefinition): void {\n    this.metrics.set(metric.key, metric);\n  }\n\n  async getUnaggregatedRecords(options: {\n    metricKey?: string;\n    periodStart: Date;\n    periodEnd: Date;\n    limit?: number;\n  }): Promise<UsageRecord[]> {\n    let records = this.records.filter((r) => {\n      const inPeriod =\n        r.timestamp >= options.periodStart && r.timestamp < options.periodEnd;\n      const matchesMetric =\n        !options.metricKey || r.metricKey === options.metricKey;\n      return inPeriod && matchesMetric;\n    });\n\n    if (options.limit) {\n      records = records.slice(0, options.limit);\n    }\n\n    return records;\n  }\n\n  async markRecordsAggregated(recordIds: string[]): Promise<void> {\n    this.records = this.records.filter((r) => !recordIds.includes(r.id));\n  }\n\n  async upsertSummary(\n    summary: Omit<UsageSummary, 'id'>\n  ): Promise<UsageSummary> {\n    const key = `${summary.metricKey}::${summary.subjectType}::${summary.subjectId}::${summary.periodType}::${summary.periodStart.toISOString()}`;\n\n    const existing = this.summaries.get(key);\n    if (existing) {\n      // Update existing summary\n      existing.totalQuantity += summary.totalQuantity;\n      existing.recordCount += summary.recordCount;\n      if (summary.minQuantity !== undefined) {\n        existing.minQuantity = Math.min(\n          existing.minQuantity ?? Infinity,\n          summary.minQuantity\n        );\n      }\n      if (summary.maxQuantity !== undefined) {\n        existing.maxQuantity = Math.max(\n          existing.maxQuantity ?? -Infinity,\n          summary.maxQuantity\n        );\n      }\n      return existing;\n    }\n\n    // Create new summary\n    const newSummary: UsageSummary = {\n      id: `summary-${Date.now()}-${Math.random().toString(36).slice(2)}`,\n      ...summary,\n    };\n    this.summaries.set(key, newSummary);\n    return newSummary;\n  }\n\n  async getMetric(key: string): Promise<MetricDefinition | null> {\n    return this.metrics.get(key) || null;\n  }\n\n  async listMetrics(): Promise<MetricDefinition[]> {\n    return Array.from(this.metrics.values());\n  }\n\n  getSummaries(): UsageSummary[] {\n    return Array.from(this.summaries.values());\n  }\n\n  clear(): void {\n    this.records = [];\n    this.summaries.clear();\n    this.metrics.clear();\n  }\n}\n"],"mappings":"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"}