@contractspec/lib.cost-tracking 3.7.6 → 3.7.8

package/README.md

@@ -1,33 +1,63 @@
 # @contractspec/lib.cost-tracking
 
-Website: https://contractspec.io/
+Website: https://contractspec.io
 
+**API cost tracking and budgeting.**
 
-Cost attribution, budgeting, and optimization helpers for ContractSpec operations.
+## What It Provides
 
-## Features
+- **Layer**: lib.
+- **Consumers**: bundles.
+- Related ContractSpec packages include `@contractspec/tool.bun`, `@contractspec/tool.typescript`.
+- Related ContractSpec packages include `@contractspec/tool.bun`, `@contractspec/tool.typescript`.
 
-- 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 `@contractspec/lib.observability`
+## Installation
 
-## Example
+`npm install @contractspec/lib.cost-tracking`
 
-```ts
-import { CostTracker, defaultCostModel } from '@contractspec/lib.cost-tracking';
+or
 
-const tracker = new CostTracker({ costModel: defaultCostModel });
+`bun add @contractspec/lib.cost-tracking`
 
-tracker.recordSample({
-  operation: 'orders.list',
-  tenantId: 'acme',
-  dbReads: 12,
-  dbWrites: 2,
-  externalCalls: [{ provider: 'stripe', cost: 0.02 }],
-  computeMs: 150,
-});
+## Usage
 
-const summary = tracker.getTotals();
-```
+Import the root entrypoint from `@contractspec/lib.cost-tracking`, or choose a documented subpath when you only need one part of the package surface.
+
+## Architecture
+
+- `src/budget-alert-manager.ts` is part of the package's public or composition surface.
+- `src/cost-model.ts` is part of the package's public or composition surface.
+- `src/cost-tracker.ts` is part of the package's public or composition surface.
+- `src/index.ts` is the root public barrel and package entrypoint.
+- `src/optimization-recommender.ts` is part of the package's public or composition surface.
+- `src/types.ts` is shared public type definitions.
+
+## Public Entry Points
+
+- Export `.` resolves through `./src/index.ts`.
+
+## Local Commands
+
+- `bun run dev` — contractspec-bun-build dev
+- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
+- `bun run test` — bun test --pass-with-no-tests
+- `bun run lint` — bun lint:fix
+- `bun run lint:check` — biome check .
+- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
+- `bun run typecheck` — tsc --noEmit
+- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
+- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
+- `bun run clean` — rimraf dist .turbo
+- `bun run build:bundle` — contractspec-bun-build transpile
+- `bun run build:types` — contractspec-bun-build types
+- `bun run prebuild` — contractspec-bun-build prebuild
+
+## Recent Updates
+
+- Replace eslint+prettier by biomejs to optimize speed.
+
+## Notes
+
+- Cost calculation logic must stay deterministic — no side effects or external calls during computation.
+- Budget threshold types are shared across consumers; changes require coordination.
+- Do not introduce floating-point arithmetic where precision matters; use integer cents or a decimal library.

package/dist/browser/index.js

@@ -1,3 +1,39 @@
+// src/budget-alert-manager.ts
+class BudgetAlertManager {
+  options;
+  limits = new Map;
+  spend = new Map;
+  constructor(options) {
+    this.options = options;
+    for (const budget of options.budgets) {
+      this.limits.set(budget.tenantId, budget);
+      this.spend.set(budget.tenantId, 0);
+    }
+  }
+  track(summary) {
+    if (!summary.tenantId) {
+      return;
+    }
+    const current = (this.spend.get(summary.tenantId) ?? 0) + summary.total;
+    this.spend.set(summary.tenantId, current);
+    const budget = this.limits.get(summary.tenantId);
+    if (!budget) {
+      return;
+    }
+    const threshold = budget.alertThreshold ?? 0.8;
+    if (current >= budget.monthlyLimit * threshold) {
+      this.options.onAlert?.({
+        tenantId: summary.tenantId,
+        limit: budget.monthlyLimit,
+        total: current,
+        summary
+      });
+    }
+  }
+  getSpend(tenantId) {
+    return this.spend.get(tenantId) ?? 0;
+  }
+}
 // src/cost-model.ts
 var defaultCostModel = {
   dbReadCost: 0.000002,
@@ -74,42 +110,6 @@ class CostTracker {
     return tenantId ? `${tenantId}:${operation}` : operation;
   }
 }
-// src/budget-alert-manager.ts
-class BudgetAlertManager {
-  options;
-  limits = new Map;
-  spend = new Map;
-  constructor(options) {
-    this.options = options;
-    for (const budget of options.budgets) {
-      this.limits.set(budget.tenantId, budget);
-      this.spend.set(budget.tenantId, 0);
-    }
-  }
-  track(summary) {
-    if (!summary.tenantId) {
-      return;
-    }
-    const current = (this.spend.get(summary.tenantId) ?? 0) + summary.total;
-    this.spend.set(summary.tenantId, current);
-    const budget = this.limits.get(summary.tenantId);
-    if (!budget) {
-      return;
-    }
-    const threshold = budget.alertThreshold ?? 0.8;
-    if (current >= budget.monthlyLimit * threshold) {
-      this.options.onAlert?.({
-        tenantId: summary.tenantId,
-        limit: budget.monthlyLimit,
-        total: current,
-        summary
-      });
-    }
-  }
-  getSpend(tenantId) {
-    return this.spend.get(tenantId) ?? 0;
-  }
-}
 // src/optimization-recommender.ts
 class OptimizationRecommender {
   generate(summary) {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export * from './types';
+export * from './budget-alert-manager';
 export * from './cost-model';
 export * from './cost-tracker';
-export * from './budget-alert-manager';
 export * from './optimization-recommender';
+export * from './types';

package/dist/index.js

@@ -1,4 +1,40 @@
 // @bun
+// src/budget-alert-manager.ts
+class BudgetAlertManager {
+  options;
+  limits = new Map;
+  spend = new Map;
+  constructor(options) {
+    this.options = options;
+    for (const budget of options.budgets) {
+      this.limits.set(budget.tenantId, budget);
+      this.spend.set(budget.tenantId, 0);
+    }
+  }
+  track(summary) {
+    if (!summary.tenantId) {
+      return;
+    }
+    const current = (this.spend.get(summary.tenantId) ?? 0) + summary.total;
+    this.spend.set(summary.tenantId, current);
+    const budget = this.limits.get(summary.tenantId);
+    if (!budget) {
+      return;
+    }
+    const threshold = budget.alertThreshold ?? 0.8;
+    if (current >= budget.monthlyLimit * threshold) {
+      this.options.onAlert?.({
+        tenantId: summary.tenantId,
+        limit: budget.monthlyLimit,
+        total: current,
+        summary
+      });
+    }
+  }
+  getSpend(tenantId) {
+    return this.spend.get(tenantId) ?? 0;
+  }
+}
 // src/cost-model.ts
 var defaultCostModel = {
   dbReadCost: 0.000002,
@@ -75,42 +111,6 @@ class CostTracker {
     return tenantId ? `${tenantId}:${operation}` : operation;
   }
 }
-// src/budget-alert-manager.ts
-class BudgetAlertManager {
-  options;
-  limits = new Map;
-  spend = new Map;
-  constructor(options) {
-    this.options = options;
-    for (const budget of options.budgets) {
-      this.limits.set(budget.tenantId, budget);
-      this.spend.set(budget.tenantId, 0);
-    }
-  }
-  track(summary) {
-    if (!summary.tenantId) {
-      return;
-    }
-    const current = (this.spend.get(summary.tenantId) ?? 0) + summary.total;
-    this.spend.set(summary.tenantId, current);
-    const budget = this.limits.get(summary.tenantId);
-    if (!budget) {
-      return;
-    }
-    const threshold = budget.alertThreshold ?? 0.8;
-    if (current >= budget.monthlyLimit * threshold) {
-      this.options.onAlert?.({
-        tenantId: summary.tenantId,
-        limit: budget.monthlyLimit,
-        total: current,
-        summary
-      });
-    }
-  }
-  getSpend(tenantId) {
-    return this.spend.get(tenantId) ?? 0;
-  }
-}
 // src/optimization-recommender.ts
 class OptimizationRecommender {
   generate(summary) {

package/dist/node/index.js

@@ -1,3 +1,39 @@
+// src/budget-alert-manager.ts
+class BudgetAlertManager {
+  options;
+  limits = new Map;
+  spend = new Map;
+  constructor(options) {
+    this.options = options;
+    for (const budget of options.budgets) {
+      this.limits.set(budget.tenantId, budget);
+      this.spend.set(budget.tenantId, 0);
+    }
+  }
+  track(summary) {
+    if (!summary.tenantId) {
+      return;
+    }
+    const current = (this.spend.get(summary.tenantId) ?? 0) + summary.total;
+    this.spend.set(summary.tenantId, current);
+    const budget = this.limits.get(summary.tenantId);
+    if (!budget) {
+      return;
+    }
+    const threshold = budget.alertThreshold ?? 0.8;
+    if (current >= budget.monthlyLimit * threshold) {
+      this.options.onAlert?.({
+        tenantId: summary.tenantId,
+        limit: budget.monthlyLimit,
+        total: current,
+        summary
+      });
+    }
+  }
+  getSpend(tenantId) {
+    return this.spend.get(tenantId) ?? 0;
+  }
+}
 // src/cost-model.ts
 var defaultCostModel = {
   dbReadCost: 0.000002,
@@ -74,42 +110,6 @@ class CostTracker {
     return tenantId ? `${tenantId}:${operation}` : operation;
   }
 }
-// src/budget-alert-manager.ts
-class BudgetAlertManager {
-  options;
-  limits = new Map;
-  spend = new Map;
-  constructor(options) {
-    this.options = options;
-    for (const budget of options.budgets) {
-      this.limits.set(budget.tenantId, budget);
-      this.spend.set(budget.tenantId, 0);
-    }
-  }
-  track(summary) {
-    if (!summary.tenantId) {
-      return;
-    }
-    const current = (this.spend.get(summary.tenantId) ?? 0) + summary.total;
-    this.spend.set(summary.tenantId, current);
-    const budget = this.limits.get(summary.tenantId);
-    if (!budget) {
-      return;
-    }
-    const threshold = budget.alertThreshold ?? 0.8;
-    if (current >= budget.monthlyLimit * threshold) {
-      this.options.onAlert?.({
-        tenantId: summary.tenantId,
-        limit: budget.monthlyLimit,
-        total: current,
-        summary
-      });
-    }
-  }
-  getSpend(tenantId) {
-    return this.spend.get(tenantId) ?? 0;
-  }
-}
 // src/optimization-recommender.ts
 class OptimizationRecommender {
   generate(summary) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractspec/lib.cost-tracking",
-  "version": "3.7.6",
+  "version": "3.7.8",
   "description": "API cost tracking and budgeting",
   "keywords": [
     "contractspec",
@@ -25,16 +25,16 @@
     "dev": "contractspec-bun-build dev",
     "clean": "rimraf dist .turbo",
     "lint": "bun lint:fix",
-    "lint:fix": "eslint src --fix",
-    "lint:check": "eslint src",
+    "lint:fix": "biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .",
+    "lint:check": "biome check .",
     "test": "bun test --pass-with-no-tests",
     "prebuild": "contractspec-bun-build prebuild",
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "@contractspec/tool.typescript": "3.7.6",
+    "@contractspec/tool.typescript": "3.7.8",
     "typescript": "^5.9.3",
-    "@contractspec/tool.bun": "3.7.6"
+    "@contractspec/tool.bun": "3.7.8"
   },
   "exports": {
     ".": {