@lssm/lib.cost-tracking 0.0.0-canary-20251206160926

package/README.md

@@ -0,0 +1,30 @@
+# @lssm/lib.cost-tracking
+
+Cost attribution, budgeting, and optimization helpers for ContractSpec operations.
+
+## Features
+
+- Normalize DB/API/compute metrics into unified cost samples
+- Attribute costs per operation, tenant, and feature flag
+- Detect budget overruns with configurable alerts
+- Generate optimization suggestions (N+1, caching, batching)
+- Integrates with telemetry produced via `@lssm/lib.observability`
+
+## Example
+
+```ts
+import { CostTracker, defaultCostModel } from '@lssm/lib.cost-tracking';
+
+const tracker = new CostTracker({ costModel: defaultCostModel });
+
+tracker.recordSample({
+  operation: 'orders.list',
+  tenantId: 'acme',
+  dbReads: 12,
+  dbWrites: 2,
+  externalCalls: [{ provider: 'stripe', cost: 0.02 }],
+  computeMs: 150,
+});
+
+const summary = tracker.getTotals();
+```

package/dist/budget-alert-manager.d.ts

@@ -0,0 +1,22 @@
+import { OperationCostSummary, TenantBudget } from "./types.js";
+
+//#region src/budget-alert-manager.d.ts
+interface BudgetAlertManagerOptions {
+  budgets: TenantBudget[];
+  onAlert?: (payload: {
+    tenantId: string;
+    limit: number;
+    total: number;
+    summary: OperationCostSummary;
+  }) => void;
+}
+declare class BudgetAlertManager {
+  private readonly options;
+  private readonly limits;
+  private readonly spend;
+  constructor(options: BudgetAlertManagerOptions);
+  track(summary: OperationCostSummary): void;
+  getSpend(tenantId: string): number;
+}
+//#endregion
+export { BudgetAlertManager, BudgetAlertManagerOptions };

package/dist/budget-alert-manager.js

@@ -0,0 +1 @@
+var e=class{limits=new Map;spend=new Map;constructor(e){this.options=e;for(let t of e.budgets)this.limits.set(t.tenantId,t),this.spend.set(t.tenantId,0)}track(e){if(!e.tenantId)return;let t=(this.spend.get(e.tenantId)??0)+e.total;this.spend.set(e.tenantId,t);let n=this.limits.get(e.tenantId);if(!n)return;let r=n.alertThreshold??.8;t>=n.monthlyLimit*r&&this.options.onAlert?.({tenantId:e.tenantId,limit:n.monthlyLimit,total:t,summary:e})}getSpend(e){return this.spend.get(e)??0}};export{e as BudgetAlertManager};

package/dist/cost-model.d.ts

@@ -0,0 +1,14 @@
+import { CostModel, CostSample } from "./types.js";
+
+//#region src/cost-model.d.ts
+declare const defaultCostModel: CostModel;
+declare function calculateSampleCost(sample: CostSample, model: CostModel): {
+  dbReads: number;
+  dbWrites: number;
+  compute: number;
+  memory: number;
+  external: number;
+  custom: number;
+};
+//#endregion
+export { calculateSampleCost, defaultCostModel };

package/dist/cost-model.js

@@ -0,0 +1 @@
+const e={dbReadCost:2e-6,dbWriteCost:1e-5,computeMsCost:15e-8,memoryMbMsCost:2e-8};function t(e,t){let n=(e.externalCalls??[]).reduce((e,t)=>e+(t.cost??0),0);return{dbReads:(e.dbReads??0)*t.dbReadCost,dbWrites:(e.dbWrites??0)*t.dbWriteCost,compute:(e.computeMs??0)*t.computeMsCost,memory:(e.memoryMbMs??0)*t.memoryMbMsCost,external:n,custom:e.customCost??0}}export{t as calculateSampleCost,e as defaultCostModel};

package/dist/cost-tracker.d.ts

@@ -0,0 +1,21 @@
+import { CostModel, CostSample, OperationCostSummary } from "./types.js";
+
+//#region src/cost-tracker.d.ts
+interface CostTrackerOptions {
+  costModel?: CostModel;
+  onSampleRecorded?: (sample: CostSample, total: number) => void;
+}
+declare class CostTracker {
+  private readonly options;
+  private readonly totals;
+  private readonly costModel;
+  constructor(options?: CostTrackerOptions);
+  recordSample(sample: CostSample): OperationCostSummary;
+  getTotals(filter?: {
+    tenantId?: string;
+  }): OperationCostSummary[];
+  reset(): void;
+  private buildKey;
+}
+//#endregion
+export { CostTracker, CostTrackerOptions };

package/dist/cost-tracker.js

@@ -0,0 +1 @@
+import{calculateSampleCost as e,defaultCostModel as t}from"./cost-model.js";var n=class{totals=new Map;costModel;constructor(e={}){this.options=e,this.costModel=e.costModel??t}recordSample(t){let n=e(t,this.costModel),r=n.dbReads+n.dbWrites+n.compute+n.memory+n.external+n.custom,i=this.buildKey(t.operation,t.tenantId),a=this.totals.get(i),o=a?{...a,total:a.total+r,breakdown:{dbReads:a.breakdown.dbReads+n.dbReads,dbWrites:a.breakdown.dbWrites+n.dbWrites,compute:a.breakdown.compute+n.compute,memory:a.breakdown.memory+n.memory,external:a.breakdown.external+n.external,custom:a.breakdown.custom+n.custom},samples:a.samples+1}:{operation:t.operation,tenantId:t.tenantId,total:r,breakdown:{dbReads:n.dbReads,dbWrites:n.dbWrites,compute:n.compute,memory:n.memory,external:n.external,custom:n.custom},samples:1};return this.totals.set(i,o),this.options.onSampleRecorded?.(t,r),o}getTotals(e){let t=Array.from(this.totals.values());return e?.tenantId?t.filter(t=>t.tenantId===e.tenantId):t}reset(){this.totals.clear()}buildKey(e,t){return t?`${t}:${e}`:e}};export{n as CostTracker};

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { BudgetAlert, CostModel, CostSample, ExternalCallCost, OperationCostSummary, OptimizationSuggestion, TenantBudget } from "./types.js";
+import { calculateSampleCost, defaultCostModel } from "./cost-model.js";
+import { CostTracker, CostTrackerOptions } from "./cost-tracker.js";
+import { BudgetAlertManager, BudgetAlertManagerOptions } from "./budget-alert-manager.js";
+import { OptimizationRecommender } from "./optimization-recommender.js";
+export { BudgetAlert, BudgetAlertManager, BudgetAlertManagerOptions, CostModel, CostSample, CostTracker, CostTrackerOptions, ExternalCallCost, OperationCostSummary, OptimizationRecommender, OptimizationSuggestion, TenantBudget, calculateSampleCost, defaultCostModel };

package/dist/index.js

@@ -0,0 +1 @@
+import{calculateSampleCost as e,defaultCostModel as t}from"./cost-model.js";import{CostTracker as n}from"./cost-tracker.js";import{BudgetAlertManager as r}from"./budget-alert-manager.js";import{OptimizationRecommender as i}from"./optimization-recommender.js";export{r as BudgetAlertManager,n as CostTracker,i as OptimizationRecommender,e as calculateSampleCost,t as defaultCostModel};

package/dist/optimization-recommender.d.ts

@@ -0,0 +1,8 @@
+import { OperationCostSummary, OptimizationSuggestion } from "./types.js";
+
+//#region src/optimization-recommender.d.ts
+declare class OptimizationRecommender {
+  generate(summary: OperationCostSummary): OptimizationSuggestion[];
+}
+//#endregion
+export { OptimizationRecommender };

package/dist/optimization-recommender.js

@@ -0,0 +1 @@
+var e=class{generate(e){let t=[],n=e.total/e.samples;return e.breakdown.dbReads/e.samples>1e3&&t.push({operation:e.operation,tenantId:e.tenantId,category:`n_plus_one`,message:`High average DB read count detected. Consider batching queries or adding pagination.`,evidence:{avgReads:e.breakdown.dbReads/e.samples}}),e.breakdown.compute/e.total>.6&&t.push({operation:e.operation,tenantId:e.tenantId,category:`batching`,message:`Compute dominates cost. Investigate hot loops or move heavy logic to background jobs.`,evidence:{computeShare:e.breakdown.compute/e.total}}),e.breakdown.external>n*.5&&t.push({operation:e.operation,tenantId:e.tenantId,category:`external`,message:`External provider spend is high. Reuse results or enable caching.`,evidence:{externalCost:e.breakdown.external}}),e.breakdown.memory>e.breakdown.compute*1.2&&t.push({operation:e.operation,tenantId:e.tenantId,category:`caching`,message:`Memory utilization suggests cached payloads linger. Tune TTL or stream responses.`,evidence:{memoryCost:e.breakdown.memory}}),t}};export{e as OptimizationRecommender};

package/dist/types.d.ts

@@ -0,0 +1,62 @@
+//#region src/types.d.ts
+interface ExternalCallCost {
+  provider: string;
+  cost?: number;
+  durationMs?: number;
+  requestCount?: number;
+}
+interface CostSample {
+  operation: string;
+  tenantId?: string;
+  environment?: 'dev' | 'staging' | 'prod';
+  dbReads?: number;
+  dbWrites?: number;
+  computeMs?: number;
+  memoryMbMs?: number;
+  externalCalls?: ExternalCallCost[];
+  customCost?: number;
+  timestamp?: Date;
+  metadata?: Record<string, unknown>;
+}
+interface CostModel {
+  dbReadCost: number;
+  dbWriteCost: number;
+  computeMsCost: number;
+  memoryMbMsCost: number;
+}
+interface OperationCostSummary {
+  operation: string;
+  tenantId?: string;
+  total: number;
+  breakdown: {
+    dbReads: number;
+    dbWrites: number;
+    compute: number;
+    memory: number;
+    external: number;
+    custom: number;
+  };
+  samples: number;
+}
+interface TenantBudget {
+  tenantId: string;
+  monthlyLimit: number;
+  currency?: string;
+  alertThreshold?: number;
+  currentSpend?: number;
+}
+interface OptimizationSuggestion {
+  operation: string;
+  tenantId?: string;
+  category: 'n_plus_one' | 'caching' | 'batching' | 'external';
+  message: string;
+  evidence: Record<string, unknown>;
+}
+interface BudgetAlert {
+  tenantId: string;
+  limit: number;
+  actual: number;
+  triggeredAt: Date;
+}
+//#endregion
+export { BudgetAlert, CostModel, CostSample, ExternalCallCost, OperationCostSummary, OptimizationSuggestion, TenantBudget };

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@lssm/lib.cost-tracking",
+  "version": "0.0.0-canary-20251206160926",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
+    "build": "bun build:bundle && bun build:types",
+    "build:bundle": "tsdown",
+    "build:types": "tsc --noEmit",
+    "dev": "bun build:bundle --watch",
+    "clean": "rimraf dist .turbo",
+    "lint": "bun lint:fix",
+    "lint:fix": "eslint src --fix",
+    "lint:check": "eslint src",
+    "test": "bun run"
+  },
+  "peerDependencies": {
+    "@lssm/lib.observability": "workspace:*"
+  },
+  "devDependencies": {
+    "@lssm/tool.tsdown": "workspace:*",
+    "@lssm/tool.typescript": "workspace:*",
+    "tsdown": "^0.17.0",
+    "typescript": "^5.9.3"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./*": "./*"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}