@contractspec/lib.metering 3.7.17 → 3.7.19

package/dist/docs/metering.docblock.js

@@ -1,16 +1,5 @@
 // @bun
-// src/docs/metering.docblock.ts
-import { registerDocBlocks } from "@contractspec/lib.contracts-spec/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
+import{registerDocBlocks as f}from"@contractspec/lib.contracts-spec/docs";var h=[{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.
@@ -35,7 +24,7 @@ var meteringDocBlocks = [
 
 ## Example
 
-${"```"}ts
+\`\`\`ts
 import { meteringSchemaContribution } from '@contractspec/lib.metering';
 import { aggregateUsage } from '@contractspec/lib.metering/aggregation';
 
@@ -50,14 +39,11 @@ await aggregateUsage({
   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);
+`}];f(h);

package/dist/entities/index.js

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