@contractspec/lib.metering 1.56.1 → 1.58.0

package/dist/browser/docs/metering.docblock.js

@@ -0,0 +1,62 @@
+// src/docs/metering.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+var meteringDocBlocks = [
+  {
+    id: "docs.metering.usage",
+    title: "Usage Metering & Billing Core",
+    summary: "Reusable usage/metering layer with metric definitions, usage ingestion, aggregation, thresholds, and alerts for billing or quotas.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/metering/usage",
+    tags: ["metering", "usage", "billing", "quotas"],
+    body: `## Capabilities
+
+- **Entities**: MetricDefinition, UsageRecord, UsageSummary, UsageThreshold, UsageAlert.
+- **Contracts**: define/list metrics; record usage (batch + idempotent); retrieve usage by subject; manage thresholds and alerts.
+- **Aggregation**: hourly/daily/weekly/monthly rollups with SUM/COUNT/AVG/MIN/MAX/LAST strategies.
+- **Events**: usage.recorded, usage.aggregated, threshold.exceeded (see events export).
+
+## Usage
+
+1) Compose schema
+- Add \`meteringSchemaContribution\` to your schema composition.
+
+2) Register contracts/events
+- Import from \`@contractspec/lib.metering\` into your spec registry.
+
+3) Ingest usage
+- Use \`recordUsage\` contract (see contracts export) from application services whenever a billable/important action happens (e.g., agent run, API call).
+
+4) Aggregate + thresholds
+- Run scheduled jobs using \`aggregateUsage\` helper to roll up summaries.
+- Configure \`UsageThreshold\` to emit alerts or blocking actions; pipe alerts into Notifications/Audit.
+- Use \`PosthogMeteringReader\` to backfill or validate usage from PostHog events.
+
+## Example
+
+${"```"}ts
+import { meteringSchemaContribution } from '@contractspec/lib.metering';
+import { aggregateUsage } from '@contractspec/lib.metering/aggregation';
+
+// schema composition
+const schema = {
+  modules: [meteringSchemaContribution],
+};
+
+// aggregation job
+await aggregateUsage({
+  metrics: metricRepository,
+  usage: usageRepository,
+  period: 'DAILY',
+});
+${"```"},
+
+## Guardrails
+
+- Keep metric keys stable; store quantities as decimals for currency/units.
+- Use idempotency keys for external ingestion; avoid PII in metric metadata.
+- Scope by org/user for multi-tenant isolation; emit audit + analytics events on changes.
+`
+  }
+];
+registerDocBlocks(meteringDocBlocks);

package/dist/browser/entities/index.js

@@ -0,0 +1,350 @@
+// src/entities/index.ts
+import {
+  defineEntity,
+  defineEntityEnum,
+  field,
+  index
+} from "@contractspec/lib.schema";
+var AggregationTypeEnum = defineEntityEnum({
+  name: "AggregationType",
+  values: ["COUNT", "SUM", "AVG", "MAX", "MIN", "LAST"],
+  schema: "lssm_metering",
+  description: "How to aggregate metric values."
+});
+var ResetPeriodEnum = defineEntityEnum({
+  name: "ResetPeriod",
+  values: ["NEVER", "HOURLY", "DAILY", "WEEKLY", "MONTHLY", "YEARLY"],
+  schema: "lssm_metering",
+  description: "When to reset metric counters."
+});
+var PeriodTypeEnum = defineEntityEnum({
+  name: "PeriodType",
+  values: ["HOURLY", "DAILY", "WEEKLY", "MONTHLY", "YEARLY"],
+  schema: "lssm_metering",
+  description: "Time period for aggregation."
+});
+var ThresholdActionEnum = defineEntityEnum({
+  name: "ThresholdAction",
+  values: ["NONE", "ALERT", "WARN", "BLOCK", "DOWNGRADE"],
+  schema: "lssm_metering",
+  description: "Action to take when threshold is exceeded."
+});
+var MetricDefinitionEntity = defineEntity({
+  name: "MetricDefinition",
+  description: "Definition of a usage metric.",
+  schema: "lssm_metering",
+  map: "metric_definition",
+  fields: {
+    id: field.id({ description: "Unique identifier" }),
+    key: field.string({
+      isUnique: true,
+      description: "Metric key (e.g., api_calls, storage_gb)"
+    }),
+    name: field.string({ description: "Human-readable name" }),
+    description: field.string({
+      isOptional: true,
+      description: "Metric description"
+    }),
+    unit: field.string({
+      description: "Unit of measurement (calls, bytes, etc.)"
+    }),
+    aggregationType: field.enum("AggregationType", {
+      default: "SUM",
+      description: "How to aggregate values"
+    }),
+    resetPeriod: field.enum("ResetPeriod", {
+      default: "MONTHLY",
+      description: "When to reset counters"
+    }),
+    precision: field.int({ default: 2, description: "Decimal precision" }),
+    orgId: field.string({
+      isOptional: true,
+      description: "Organization scope (null = global metric)"
+    }),
+    category: field.string({
+      isOptional: true,
+      description: "Category for grouping"
+    }),
+    displayOrder: field.int({ default: 0, description: "Order for display" }),
+    metadata: field.json({
+      isOptional: true,
+      description: "Additional metadata"
+    }),
+    isActive: field.boolean({
+      default: true,
+      description: "Whether metric is active"
+    }),
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt(),
+    usageRecords: field.hasMany("UsageRecord"),
+    usageSummaries: field.hasMany("UsageSummary"),
+    thresholds: field.hasMany("UsageThreshold")
+  },
+  indexes: [
+    index.on(["orgId", "key"]),
+    index.on(["category"]),
+    index.on(["isActive"])
+  ],
+  enums: [AggregationTypeEnum, ResetPeriodEnum]
+});
+var UsageRecordEntity = defineEntity({
+  name: "UsageRecord",
+  description: "A single usage event.",
+  schema: "lssm_metering",
+  map: "usage_record",
+  fields: {
+    id: field.id({ description: "Unique identifier" }),
+    metricKey: field.string({ description: "Metric being recorded" }),
+    metricId: field.string({
+      isOptional: true,
+      description: "Metric ID (for FK)"
+    }),
+    subjectType: field.string({
+      description: "Subject type (org, user, project)"
+    }),
+    subjectId: field.string({ description: "Subject identifier" }),
+    quantity: field.decimal({ description: "Usage quantity" }),
+    source: field.string({
+      isOptional: true,
+      description: "Source of usage (endpoint, feature, etc.)"
+    }),
+    resourceId: field.string({
+      isOptional: true,
+      description: "Related resource ID"
+    }),
+    resourceType: field.string({
+      isOptional: true,
+      description: "Related resource type"
+    }),
+    metadata: field.json({
+      isOptional: true,
+      description: "Additional context"
+    }),
+    idempotencyKey: field.string({
+      isOptional: true,
+      description: "Idempotency key for deduplication"
+    }),
+    timestamp: field.dateTime({ description: "When usage occurred" }),
+    createdAt: field.createdAt(),
+    aggregated: field.boolean({
+      default: false,
+      description: "Whether included in summary"
+    }),
+    aggregatedAt: field.dateTime({
+      isOptional: true,
+      description: "When aggregated"
+    })
+  },
+  indexes: [
+    index.on(["metricKey", "subjectType", "subjectId", "timestamp"]),
+    index.on(["subjectType", "subjectId", "timestamp"]),
+    index.on(["timestamp"]),
+    index.on(["aggregated", "timestamp"]),
+    index.unique(["idempotencyKey"], { name: "usage_record_idempotency" })
+  ]
+});
+var UsageSummaryEntity = defineEntity({
+  name: "UsageSummary",
+  description: "Pre-aggregated usage summary.",
+  schema: "lssm_metering",
+  map: "usage_summary",
+  fields: {
+    id: field.id({ description: "Unique identifier" }),
+    metricKey: field.string({ description: "Metric key" }),
+    metricId: field.string({
+      isOptional: true,
+      description: "Metric ID (for FK)"
+    }),
+    subjectType: field.string({ description: "Subject type" }),
+    subjectId: field.string({ description: "Subject identifier" }),
+    periodType: field.enum("PeriodType", { description: "Period type" }),
+    periodStart: field.dateTime({ description: "Period start time" }),
+    periodEnd: field.dateTime({ description: "Period end time" }),
+    totalQuantity: field.decimal({ description: "Total/aggregated quantity" }),
+    recordCount: field.int({
+      default: 0,
+      description: "Number of records aggregated"
+    }),
+    minQuantity: field.decimal({
+      isOptional: true,
+      description: "Minimum value"
+    }),
+    maxQuantity: field.decimal({
+      isOptional: true,
+      description: "Maximum value"
+    }),
+    avgQuantity: field.decimal({
+      isOptional: true,
+      description: "Average value"
+    }),
+    metadata: field.json({
+      isOptional: true,
+      description: "Additional metadata"
+    }),
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt()
+  },
+  indexes: [
+    index.unique(["metricKey", "subjectType", "subjectId", "periodType", "periodStart"], { name: "usage_summary_unique" }),
+    index.on(["subjectType", "subjectId", "periodType", "periodStart"]),
+    index.on(["metricKey", "periodType", "periodStart"])
+  ],
+  enums: [PeriodTypeEnum]
+});
+var UsageThresholdEntity = defineEntity({
+  name: "UsageThreshold",
+  description: "Usage threshold configuration.",
+  schema: "lssm_metering",
+  map: "usage_threshold",
+  fields: {
+    id: field.id({ description: "Unique identifier" }),
+    metricKey: field.string({ description: "Metric to monitor" }),
+    metricId: field.string({
+      isOptional: true,
+      description: "Metric ID (for FK)"
+    }),
+    subjectType: field.string({
+      isOptional: true,
+      description: "Subject type"
+    }),
+    subjectId: field.string({
+      isOptional: true,
+      description: "Subject identifier"
+    }),
+    name: field.string({ description: "Threshold name" }),
+    threshold: field.decimal({ description: "Threshold value" }),
+    warnThreshold: field.decimal({
+      isOptional: true,
+      description: "Warning threshold (e.g., 80%)"
+    }),
+    periodType: field.enum("PeriodType", {
+      default: "MONTHLY",
+      description: "Period to evaluate"
+    }),
+    action: field.enum("ThresholdAction", {
+      default: "ALERT",
+      description: "Action when exceeded"
+    }),
+    notifyEmails: field.json({
+      isOptional: true,
+      description: "Email addresses to notify"
+    }),
+    notifyWebhook: field.string({
+      isOptional: true,
+      description: "Webhook URL to call"
+    }),
+    currentValue: field.decimal({
+      default: 0,
+      description: "Current usage value"
+    }),
+    lastCheckedAt: field.dateTime({
+      isOptional: true,
+      description: "Last threshold check"
+    }),
+    lastExceededAt: field.dateTime({
+      isOptional: true,
+      description: "Last time threshold was exceeded"
+    }),
+    isActive: field.boolean({
+      default: true,
+      description: "Whether threshold is active"
+    }),
+    metadata: field.json({
+      isOptional: true,
+      description: "Additional metadata"
+    }),
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt()
+  },
+  indexes: [
+    index.on(["metricKey"]),
+    index.on(["subjectType", "subjectId"]),
+    index.on(["isActive", "metricKey"])
+  ],
+  enums: [ThresholdActionEnum]
+});
+var UsageAlertEntity = defineEntity({
+  name: "UsageAlert",
+  description: "Alert generated when threshold is exceeded.",
+  schema: "lssm_metering",
+  map: "usage_alert",
+  fields: {
+    id: field.id({ description: "Unique identifier" }),
+    thresholdId: field.foreignKey({
+      description: "Threshold that triggered alert"
+    }),
+    metricKey: field.string({ description: "Metric key" }),
+    subjectType: field.string({
+      isOptional: true,
+      description: "Subject type"
+    }),
+    subjectId: field.string({
+      isOptional: true,
+      description: "Subject identifier"
+    }),
+    alertType: field.string({ description: "Alert type (warn, exceed, etc.)" }),
+    threshold: field.decimal({ description: "Threshold value" }),
+    actualValue: field.decimal({ description: "Actual usage value" }),
+    percentageUsed: field.decimal({
+      description: "Percentage of threshold used"
+    }),
+    status: field.string({
+      default: '"pending"',
+      description: "Alert status (pending, acknowledged, resolved)"
+    }),
+    acknowledgedBy: field.string({
+      isOptional: true,
+      description: "User who acknowledged"
+    }),
+    acknowledgedAt: field.dateTime({
+      isOptional: true,
+      description: "When acknowledged"
+    }),
+    resolvedAt: field.dateTime({
+      isOptional: true,
+      description: "When resolved"
+    }),
+    notificationsSent: field.json({
+      isOptional: true,
+      description: "Notifications sent"
+    }),
+    triggeredAt: field.dateTime({ description: "When alert was triggered" }),
+    createdAt: field.createdAt(),
+    thresholdRelation: field.belongsTo("UsageThreshold", ["thresholdId"], ["id"], { onDelete: "Cascade" })
+  },
+  indexes: [
+    index.on(["thresholdId", "status"]),
+    index.on(["metricKey", "triggeredAt"]),
+    index.on(["status", "triggeredAt"])
+  ]
+});
+var meteringEntities = [
+  MetricDefinitionEntity,
+  UsageRecordEntity,
+  UsageSummaryEntity,
+  UsageThresholdEntity,
+  UsageAlertEntity
+];
+var meteringSchemaContribution = {
+  moduleId: "@contractspec/lib.metering",
+  entities: meteringEntities,
+  enums: [
+    AggregationTypeEnum,
+    ResetPeriodEnum,
+    PeriodTypeEnum,
+    ThresholdActionEnum
+  ]
+};
+export {
+  meteringSchemaContribution,
+  meteringEntities,
+  UsageThresholdEntity,
+  UsageSummaryEntity,
+  UsageRecordEntity,
+  UsageAlertEntity,
+  ThresholdActionEnum,
+  ResetPeriodEnum,
+  PeriodTypeEnum,
+  MetricDefinitionEntity,
+  AggregationTypeEnum
+};

package/dist/browser/events.js

@@ -0,0 +1,228 @@
+// src/events.ts
+import { ScalarTypeEnum, defineSchemaModel } from "@contractspec/lib.schema";
+import { defineEvent } from "@contractspec/lib.contracts";
+var MetricDefinedPayload = defineSchemaModel({
+  name: "MetricDefinedEventPayload",
+  description: "Payload when a metric is defined",
+  fields: {
+    metricId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    key: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    unit: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    aggregationType: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false
+    },
+    orgId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    createdBy: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var MetricUpdatedPayload = defineSchemaModel({
+  name: "MetricUpdatedEventPayload",
+  description: "Payload when a metric is updated",
+  fields: {
+    metricId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    key: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    changes: { type: ScalarTypeEnum.JSON(), isOptional: false },
+    updatedBy: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    updatedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var UsageRecordedPayload = defineSchemaModel({
+  name: "UsageRecordedEventPayload",
+  description: "Payload when usage is recorded",
+  fields: {
+    recordId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    metricKey: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    subjectType: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    subjectId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    quantity: { type: ScalarTypeEnum.Float_unsecure(), isOptional: false },
+    source: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    timestamp: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var UsageBatchRecordedPayload = defineSchemaModel({
+  name: "UsageBatchRecordedEventPayload",
+  description: "Payload when a batch of usage is recorded",
+  fields: {
+    recordCount: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    metricKeys: { type: ScalarTypeEnum.JSON(), isOptional: false },
+    totalQuantity: { type: ScalarTypeEnum.Float_unsecure(), isOptional: false },
+    timestamp: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var UsageAggregatedPayload = defineSchemaModel({
+  name: "UsageAggregatedEventPayload",
+  description: "Payload when usage is aggregated",
+  fields: {
+    summaryId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    metricKey: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    subjectType: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    subjectId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    periodType: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    periodStart: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    periodEnd: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    totalQuantity: { type: ScalarTypeEnum.Float_unsecure(), isOptional: false },
+    recordCount: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    aggregatedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var ThresholdCreatedPayload = defineSchemaModel({
+  name: "ThresholdCreatedEventPayload",
+  description: "Payload when a threshold is created",
+  fields: {
+    thresholdId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    metricKey: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    subjectType: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    subjectId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    threshold: { type: ScalarTypeEnum.Float_unsecure(), isOptional: false },
+    action: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var ThresholdExceededPayload = defineSchemaModel({
+  name: "ThresholdExceededEventPayload",
+  description: "Payload when a threshold is exceeded",
+  fields: {
+    alertId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    thresholdId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    metricKey: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    subjectType: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    subjectId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    threshold: { type: ScalarTypeEnum.Float_unsecure(), isOptional: false },
+    actualValue: { type: ScalarTypeEnum.Float_unsecure(), isOptional: false },
+    percentageUsed: {
+      type: ScalarTypeEnum.Float_unsecure(),
+      isOptional: false
+    },
+    action: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    triggeredAt: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var ThresholdApproachingPayload = defineSchemaModel({
+  name: "ThresholdApproachingEventPayload",
+  description: "Payload when usage is approaching a threshold",
+  fields: {
+    thresholdId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    metricKey: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    subjectType: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    subjectId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    threshold: { type: ScalarTypeEnum.Float_unsecure(), isOptional: false },
+    currentValue: { type: ScalarTypeEnum.Float_unsecure(), isOptional: false },
+    percentageUsed: {
+      type: ScalarTypeEnum.Float_unsecure(),
+      isOptional: false
+    },
+    triggeredAt: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var MetricDefinedEvent = defineEvent({
+  meta: {
+    key: "metric.defined",
+    version: "1.0.0",
+    description: "A metric has been defined.",
+    stability: "stable",
+    owners: ["@platform.metering"],
+    tags: ["metering", "metric"]
+  },
+  payload: MetricDefinedPayload
+});
+var MetricUpdatedEvent = defineEvent({
+  meta: {
+    key: "metric.updated",
+    version: "1.0.0",
+    description: "A metric has been updated.",
+    stability: "stable",
+    owners: ["@platform.metering"],
+    tags: ["metering", "metric"]
+  },
+  payload: MetricUpdatedPayload
+});
+var UsageRecordedEvent = defineEvent({
+  meta: {
+    key: "usage.recorded",
+    version: "1.0.0",
+    description: "Usage has been recorded.",
+    stability: "stable",
+    owners: ["@platform.metering"],
+    tags: ["metering", "usage"]
+  },
+  payload: UsageRecordedPayload
+});
+var UsageBatchRecordedEvent = defineEvent({
+  meta: {
+    key: "usage.batch_recorded",
+    version: "1.0.0",
+    description: "A batch of usage has been recorded.",
+    stability: "stable",
+    owners: ["@platform.metering"],
+    tags: ["metering", "usage"]
+  },
+  payload: UsageBatchRecordedPayload
+});
+var UsageAggregatedEvent = defineEvent({
+  meta: {
+    key: "usage.aggregated",
+    version: "1.0.0",
+    description: "Usage has been aggregated into a summary.",
+    stability: "stable",
+    owners: ["@platform.metering"],
+    tags: ["metering", "usage"]
+  },
+  payload: UsageAggregatedPayload
+});
+var ThresholdCreatedEvent = defineEvent({
+  meta: {
+    key: "threshold.created",
+    version: "1.0.0",
+    description: "A usage threshold has been created.",
+    stability: "stable",
+    owners: ["@platform.metering"],
+    tags: ["metering", "threshold"]
+  },
+  payload: ThresholdCreatedPayload
+});
+var ThresholdExceededEvent = defineEvent({
+  meta: {
+    key: "threshold.exceeded",
+    version: "1.0.0",
+    description: "Usage has exceeded a threshold.",
+    stability: "stable",
+    owners: ["@platform.metering"],
+    tags: ["metering", "threshold"]
+  },
+  payload: ThresholdExceededPayload
+});
+var ThresholdApproachingEvent = defineEvent({
+  meta: {
+    key: "threshold.approaching",
+    version: "1.0.0",
+    description: "Usage is approaching a threshold.",
+    stability: "stable",
+    owners: ["@platform.metering"],
+    tags: ["metering", "threshold"]
+  },
+  payload: ThresholdApproachingPayload
+});
+var MeteringEvents = {
+  MetricDefinedEvent,
+  MetricUpdatedEvent,
+  UsageRecordedEvent,
+  UsageBatchRecordedEvent,
+  UsageAggregatedEvent,
+  ThresholdCreatedEvent,
+  ThresholdExceededEvent,
+  ThresholdApproachingEvent
+};
+export {
+  UsageRecordedEvent,
+  UsageBatchRecordedEvent,
+  UsageAggregatedEvent,
+  ThresholdExceededEvent,
+  ThresholdCreatedEvent,
+  ThresholdApproachingEvent,
+  MetricUpdatedEvent,
+  MetricDefinedEvent,
+  MeteringEvents
+};