@contractspec/lib.metering 1.57.0 → 1.58.0

package/dist/metering.capability.d.ts

@@ -1,8 +1,3 @@
-import * as _contractspec_lib_contracts0 from "@contractspec/lib.contracts";
-
-//#region src/metering.capability.d.ts
-declare const MeteringCapability: _contractspec_lib_contracts0.CapabilitySpec;
-declare const ThresholdsCapability: _contractspec_lib_contracts0.CapabilitySpec;
-//#endregion
-export { MeteringCapability, ThresholdsCapability };
+export declare const MeteringCapability: import("@contractspec/lib.contracts").CapabilitySpec;
+export declare const ThresholdsCapability: import("@contractspec/lib.contracts").CapabilitySpec;
 //# sourceMappingURL=metering.capability.d.ts.map

package/dist/metering.capability.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metering.capability.d.ts","names":[],"sources":["../src/metering.capability.ts"],"mappings":";;;cAEa,kBAAA,EAUX,4BAAA,CAV6B,cAAA;AAAA,cAYlB,oBAAA,EAUX,4BAAA,CAV+B,cAAA"}
+{"version":3,"file":"metering.capability.d.ts","sourceRoot":"","sources":["../src/metering.capability.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,kBAAkB,sDAU7B,CAAC;AAEH,eAAO,MAAM,oBAAoB,sDAU/B,CAAC"}

package/dist/metering.capability.js

@@ -1,33 +1,29 @@
-import { StabilityEnum, defineCapability } from "@contractspec/lib.contracts";
-
-//#region src/metering.capability.ts
-const MeteringCapability = defineCapability({ meta: {
-	key: "metering",
-	version: "1.0.0",
-	kind: "api",
-	stability: StabilityEnum.Experimental,
-	description: "Usage metering and tracking",
-	owners: ["@platform.finance"],
-	tags: [
-		"metering",
-		"usage",
-		"billing"
-	]
-} });
-const ThresholdsCapability = defineCapability({ meta: {
-	key: "thresholds",
-	version: "1.0.0",
-	kind: "api",
-	stability: StabilityEnum.Experimental,
-	description: "Usage threshold alerts and limits",
-	owners: ["@platform.finance"],
-	tags: [
-		"thresholds",
-		"limits",
-		"metering"
-	]
-} });
-
-//#endregion
-export { MeteringCapability, ThresholdsCapability };
-//# sourceMappingURL=metering.capability.js.map
+// @bun
+// src/metering.capability.ts
+import { defineCapability, StabilityEnum } from "@contractspec/lib.contracts";
+var MeteringCapability = defineCapability({
+  meta: {
+    key: "metering",
+    version: "1.0.0",
+    kind: "api",
+    stability: StabilityEnum.Experimental,
+    description: "Usage metering and tracking",
+    owners: ["@platform.finance"],
+    tags: ["metering", "usage", "billing"]
+  }
+});
+var ThresholdsCapability = defineCapability({
+  meta: {
+    key: "thresholds",
+    version: "1.0.0",
+    kind: "api",
+    stability: StabilityEnum.Experimental,
+    description: "Usage threshold alerts and limits",
+    owners: ["@platform.finance"],
+    tags: ["thresholds", "limits", "metering"]
+  }
+});
+export {
+  ThresholdsCapability,
+  MeteringCapability
+};

package/dist/metering.feature.d.ts

@@ -1,11 +1,6 @@
-import * as _contractspec_lib_contracts0 from "@contractspec/lib.contracts";
-
-//#region src/metering.feature.d.ts
 /**
  * Metering feature module that bundles usage tracking,
  * metrics definitions, and billing capabilities.
  */
-declare const MeteringFeature: _contractspec_lib_contracts0.FeatureModuleSpec;
-//#endregion
-export { MeteringFeature };
+export declare const MeteringFeature: import("@contractspec/lib.contracts").FeatureModuleSpec;
 //# sourceMappingURL=metering.feature.d.ts.map

package/dist/metering.feature.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metering.feature.d.ts","names":[],"sources":["../src/metering.feature.ts"],"mappings":";;;;;;AAWA;cAAa,eAAA,EAgEX,4BAAA,CAhE0B,iBAAA"}
+{"version":3,"file":"metering.feature.d.ts","sourceRoot":"","sources":["../src/metering.feature.ts"],"names":[],"mappings":"AAOA;;;GAGG;AACH,eAAO,MAAM,eAAe,yDAgE1B,CAAC"}

package/dist/metering.feature.js

@@ -1,134 +1,53 @@
+// @bun
+// src/metering.feature.ts
 import { defineFeature } from "@contractspec/lib.contracts";
-
-//#region src/metering.feature.ts
-/**
-* Metering Feature Module Specification
-*
-* Defines the feature module for usage metering and threshold management.
-*/
-/**
-* Metering feature module that bundles usage tracking,
-* metrics definitions, and billing capabilities.
-*/
-const MeteringFeature = defineFeature({
-	meta: {
-		key: "metrics",
-		version: "1.0.0",
-		title: "Usage Metering",
-		description: "Usage metering, metric definitions, and threshold alerting",
-		domain: "platform",
-		owners: ["@platform.metering"],
-		tags: [
-			"metering",
-			"usage",
-			"billing",
-			"thresholds"
-		],
-		stability: "stable"
-	},
-	operations: [
-		{
-			key: "metric.define",
-			version: "1.0.0"
-		},
-		{
-			key: "metric.update",
-			version: "1.0.0"
-		},
-		{
-			key: "metric.delete",
-			version: "1.0.0"
-		},
-		{
-			key: "metric.get",
-			version: "1.0.0"
-		},
-		{
-			key: "metric.list",
-			version: "1.0.0"
-		},
-		{
-			key: "usage.record",
-			version: "1.0.0"
-		},
-		{
-			key: "usage.recordBatch",
-			version: "1.0.0"
-		},
-		{
-			key: "usage.get",
-			version: "1.0.0"
-		},
-		{
-			key: "usage.getSummary",
-			version: "1.0.0"
-		},
-		{
-			key: "threshold.create",
-			version: "1.0.0"
-		},
-		{
-			key: "threshold.update",
-			version: "1.0.0"
-		},
-		{
-			key: "threshold.delete",
-			version: "1.0.0"
-		},
-		{
-			key: "threshold.list",
-			version: "1.0.0"
-		}
-	],
-	events: [
-		{
-			key: "metric.defined",
-			version: "1.0.0"
-		},
-		{
-			key: "metric.updated",
-			version: "1.0.0"
-		},
-		{
-			key: "usage.recorded",
-			version: "1.0.0"
-		},
-		{
-			key: "usage.batch_recorded",
-			version: "1.0.0"
-		},
-		{
-			key: "usage.aggregated",
-			version: "1.0.0"
-		},
-		{
-			key: "threshold.created",
-			version: "1.0.0"
-		},
-		{
-			key: "threshold.exceeded",
-			version: "1.0.0"
-		},
-		{
-			key: "threshold.approaching",
-			version: "1.0.0"
-		}
-	],
-	presentations: [],
-	opToPresentation: [],
-	presentationsTargets: [],
-	capabilities: {
-		provides: [{
-			key: "metering",
-			version: "1.0.0"
-		}, {
-			key: "thresholds",
-			version: "1.0.0"
-		}],
-		requires: []
-	}
+var MeteringFeature = defineFeature({
+  meta: {
+    key: "metrics",
+    version: "1.0.0",
+    title: "Usage Metering",
+    description: "Usage metering, metric definitions, and threshold alerting",
+    domain: "platform",
+    owners: ["@platform.metering"],
+    tags: ["metering", "usage", "billing", "thresholds"],
+    stability: "stable"
+  },
+  operations: [
+    { key: "metric.define", version: "1.0.0" },
+    { key: "metric.update", version: "1.0.0" },
+    { key: "metric.delete", version: "1.0.0" },
+    { key: "metric.get", version: "1.0.0" },
+    { key: "metric.list", version: "1.0.0" },
+    { key: "usage.record", version: "1.0.0" },
+    { key: "usage.recordBatch", version: "1.0.0" },
+    { key: "usage.get", version: "1.0.0" },
+    { key: "usage.getSummary", version: "1.0.0" },
+    { key: "threshold.create", version: "1.0.0" },
+    { key: "threshold.update", version: "1.0.0" },
+    { key: "threshold.delete", version: "1.0.0" },
+    { key: "threshold.list", version: "1.0.0" }
+  ],
+  events: [
+    { key: "metric.defined", version: "1.0.0" },
+    { key: "metric.updated", version: "1.0.0" },
+    { key: "usage.recorded", version: "1.0.0" },
+    { key: "usage.batch_recorded", version: "1.0.0" },
+    { key: "usage.aggregated", version: "1.0.0" },
+    { key: "threshold.created", version: "1.0.0" },
+    { key: "threshold.exceeded", version: "1.0.0" },
+    { key: "threshold.approaching", version: "1.0.0" }
+  ],
+  presentations: [],
+  opToPresentation: [],
+  presentationsTargets: [],
+  capabilities: {
+    provides: [
+      { key: "metering", version: "1.0.0" },
+      { key: "thresholds", version: "1.0.0" }
+    ],
+    requires: []
+  }
 });
-
-//#endregion
-export { MeteringFeature };
-//# sourceMappingURL=metering.feature.js.map
+export {
+  MeteringFeature
+};

package/dist/node/aggregation/index.js

@@ -0,0 +1,265 @@
+// src/aggregation/index.ts
+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;
+  }
+}
+function getPeriodEnd(date, periodType) {
+  const start = getPeriodStart(date, periodType);
+  switch (periodType) {
+    case "HOURLY":
+      return new Date(start.getTime() + 60 * 60 * 1000);
+    case "DAILY":
+      return new Date(start.getTime() + 24 * 60 * 60 * 1000);
+    case "WEEKLY":
+      return new Date(start.getTime() + 7 * 24 * 60 * 60 * 1000);
+    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;
+    }
+  }
+}
+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()) / 86400000 + 1) / 7);
+  return String(weekNum).padStart(2, "0");
+}
+
+class UsageAggregator {
+  storage;
+  batchSize;
+  constructor(options) {
+    this.storage = options.storage;
+    this.batchSize = options.batchSize || 1000;
+  }
+  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 [metricKey2, subjectType, subjectId] = groupKey.split("::");
+        result.errors.push({
+          metricKey: metricKey2 ?? "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, new Date);
+    result.recordsProcessed = records.length;
+    return result;
+  }
+  groupRecords(records, periodType) {
+    const groups = 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;
+  }
+  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 metric = await this.storage.getMetric(metricKey);
+    const aggregationType = metric?.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++;
+  }
+  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 };
+  }
+}
+
+class InMemoryUsageStorage {
+  records = [];
+  summaries = new Map;
+  metrics = 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 !== undefined) {
+        existing.minQuantity = Math.min(existing.minQuantity ?? Infinity, summary.minQuantity);
+      }
+      if (summary.maxQuantity !== undefined) {
+        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();
+  }
+}
+export {
+  getPeriodStart,
+  getPeriodEnd,
+  formatPeriodKey,
+  UsageAggregator,
+  InMemoryUsageStorage
+};