@lssm/lib.metering 0.0.0-canary-20251210171026 → 0.0.0-canary-20251212210835

package/README.md

@@ -162,7 +162,7 @@ await aggregator.aggregate({
 This module integrates with:
 
 - `@lssm/lib.jobs` - Scheduled aggregation jobs
-- `@lssm/modules.notifications` - Threshold alerts
+- `@lssm/module.notifications` - Threshold alerts
 - `@lssm/lib.identity-rbac` - Subject resolution
 
 ## Schema Contribution

package/dist/docs/index.js

@@ -0,0 +1 @@
+import"./metering.docblock.js";

package/dist/docs/metering.docblock.js

@@ -0,0 +1,47 @@
+import{registerDocBlocks as e}from"@lssm/lib.contracts/docs";e([{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 \`@lssm/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.
+
+## Example
+
+\`\`\`ts
+import { meteringSchemaContribution } from '@lssm/lib.metering';
+import { aggregateUsage } from '@lssm/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.
+`}]);

package/dist/index.js

@@ -1 +1 @@
-import{MeteringEvents as e,MetricDefinedEvent as t,MetricUpdatedEvent as n,ThresholdApproachingEvent as r,ThresholdCreatedEvent as i,ThresholdExceededEvent as a,UsageAggregatedEvent as o,UsageBatchRecordedEvent as s,UsageRecordedEvent as c}from"./events.js";import{AggregationTypeEnum as l,MetricDefinitionEntity as u,PeriodTypeEnum as d,ResetPeriodEnum as f,ThresholdActionEnum as p,UsageAlertEntity as m,UsageRecordEntity as h,UsageSummaryEntity as g,UsageThresholdEntity as _,meteringEntities as v,meteringSchemaContribution as y}from"./entities/index.js";import{CreateThresholdContract as b,DefineMetricContract as x,DeleteMetricContract as S,DeleteThresholdContract as C,GetMetricContract as w,GetUsageContract as T,GetUsageSummaryContract as E,ListMetricsContract as D,ListThresholdsContract as O,MetricDefinitionModel as k,RecordBatchUsageContract as A,RecordUsageContract as j,UpdateMetricContract as M,UpdateThresholdContract as N,UsageRecordModel as P,UsageSummaryModel as F,UsageThresholdModel as I}from"./contracts/index.js";import{InMemoryUsageStorage as L,UsageAggregator as R,formatPeriodKey as z,getPeriodEnd as B,getPeriodStart as V}from"./aggregation/index.js";export{l as AggregationTypeEnum,b as CreateThresholdContract,x as DefineMetricContract,S as DeleteMetricContract,C as DeleteThresholdContract,w as GetMetricContract,T as GetUsageContract,E as GetUsageSummaryContract,L as InMemoryUsageStorage,D as ListMetricsContract,O as ListThresholdsContract,e as MeteringEvents,t as MetricDefinedEvent,u as MetricDefinitionEntity,k as MetricDefinitionModel,n as MetricUpdatedEvent,d as PeriodTypeEnum,A as RecordBatchUsageContract,j as RecordUsageContract,f as ResetPeriodEnum,p as ThresholdActionEnum,r as ThresholdApproachingEvent,i as ThresholdCreatedEvent,a as ThresholdExceededEvent,M as UpdateMetricContract,N as UpdateThresholdContract,o as UsageAggregatedEvent,R as UsageAggregator,m as UsageAlertEntity,s as UsageBatchRecordedEvent,h as UsageRecordEntity,P as UsageRecordModel,c as UsageRecordedEvent,g as UsageSummaryEntity,F as UsageSummaryModel,_ as UsageThresholdEntity,I as UsageThresholdModel,z as formatPeriodKey,B as getPeriodEnd,V as getPeriodStart,v as meteringEntities,y as meteringSchemaContribution};
+import{MeteringEvents as e,MetricDefinedEvent as t,MetricUpdatedEvent as n,ThresholdApproachingEvent as r,ThresholdCreatedEvent as i,ThresholdExceededEvent as a,UsageAggregatedEvent as o,UsageBatchRecordedEvent as s,UsageRecordedEvent as c}from"./events.js";import{AggregationTypeEnum as l,MetricDefinitionEntity as u,PeriodTypeEnum as d,ResetPeriodEnum as f,ThresholdActionEnum as p,UsageAlertEntity as m,UsageRecordEntity as h,UsageSummaryEntity as g,UsageThresholdEntity as _,meteringEntities as v,meteringSchemaContribution as y}from"./entities/index.js";import{CreateThresholdContract as b,DefineMetricContract as x,DeleteMetricContract as S,DeleteThresholdContract as C,GetMetricContract as w,GetUsageContract as T,GetUsageSummaryContract as E,ListMetricsContract as D,ListThresholdsContract as O,MetricDefinitionModel as k,RecordBatchUsageContract as A,RecordUsageContract as j,UpdateMetricContract as M,UpdateThresholdContract as N,UsageRecordModel as P,UsageSummaryModel as F,UsageThresholdModel as I}from"./contracts/index.js";import{InMemoryUsageStorage as L,UsageAggregator as R,formatPeriodKey as z,getPeriodEnd as B,getPeriodStart as V}from"./aggregation/index.js";import"./docs/index.js";export{l as AggregationTypeEnum,b as CreateThresholdContract,x as DefineMetricContract,S as DeleteMetricContract,C as DeleteThresholdContract,w as GetMetricContract,T as GetUsageContract,E as GetUsageSummaryContract,L as InMemoryUsageStorage,D as ListMetricsContract,O as ListThresholdsContract,e as MeteringEvents,t as MetricDefinedEvent,u as MetricDefinitionEntity,k as MetricDefinitionModel,n as MetricUpdatedEvent,d as PeriodTypeEnum,A as RecordBatchUsageContract,j as RecordUsageContract,f as ResetPeriodEnum,p as ThresholdActionEnum,r as ThresholdApproachingEvent,i as ThresholdCreatedEvent,a as ThresholdExceededEvent,M as UpdateMetricContract,N as UpdateThresholdContract,o as UsageAggregatedEvent,R as UsageAggregator,m as UsageAlertEntity,s as UsageBatchRecordedEvent,h as UsageRecordEntity,P as UsageRecordModel,c as UsageRecordedEvent,g as UsageSummaryEntity,F as UsageSummaryModel,_ as UsageThresholdEntity,I as UsageThresholdModel,z as formatPeriodKey,B as getPeriodEnd,V as getPeriodStart,v as meteringEntities,y as meteringSchemaContribution};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lssm/lib.metering",
-  "version": "0.0.0-canary-20251210171026",
+  "version": "0.0.0-canary-20251212210835",
   "description": "Usage metering and billing core module for ContractSpec applications",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -30,6 +30,8 @@
     ".": "./src/index.ts",
     "./aggregation": "./src/aggregation/index.ts",
     "./contracts": "./src/contracts/index.ts",
+    "./docs": "./src/docs/index.ts",
+    "./docs/metering.docblock": "./src/docs/metering.docblock.ts",
     "./entities": "./src/entities/index.ts",
     "./events": "./src/events.ts",
     "./*": "./*"
@@ -45,6 +47,8 @@
       ".": "./dist/index.js",
       "./aggregation": "./dist/aggregation/index.js",
       "./contracts": "./dist/contracts/index.js",
+      "./docs": "./dist/docs/index.js",
+      "./docs/metering.docblock": "./dist/docs/metering.docblock.js",
       "./entities": "./dist/entities/index.js",
       "./events": "./dist/events.js",
       "./*": "./*"