@lssm/lib.metering 0.0.0-canary-20251217083314 → 1.41.1

package/dist/docs/index.js

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

package/dist/docs/metering.docblock.js

@@ -1,21 +1,4 @@
-import { registerDocBlocks } from "../contracts/dist/docs/registry.js";
-import "../contracts/dist/docs/index.js";
-
-//#region src/docs/metering.docblock.ts
-registerDocBlocks([{
-	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
+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.
@@ -61,7 +44,4 @@ await aggregateUsage({
 - 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.
-`
-}]);
-
-//#endregion
+`}]);

package/dist/entities/index.js

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