@littlebearapps/platform-admin-sdk 2.0.0 → 2.1.0

package/templates/shared/tests/unit/cost-calculator.test.ts

@@ -0,0 +1,141 @@
+/**
+ * Unit Tests for Cost Calculator
+ *
+ * Tests CF resource cost calculation from telemetry metrics.
+ *
+ * @module tests/unit/cost-calculator
+ * @created 2026-01-27
+ * @task Real-Time Cost Tracking for Platform SDK
+ */
+
+import { describe, expect, it } from 'vitest';
+import { calculateCFCostFromMetrics } from '../../workers/lib/usage/queue/cost-calculator';
+import type { FeatureMetrics } from '@littlebearapps/platform-consumer-sdk';
+
+describe('Cost Calculator', () => {
+  describe('calculateCFCostFromMetrics', () => {
+    it('returns zero for empty metrics', () => {
+      const metrics: FeatureMetrics = {};
+      const cost = calculateCFCostFromMetrics(metrics);
+
+      expect(cost).toBe(0);
+    });
+
+    it('calculates D1 costs correctly', () => {
+      const metrics: FeatureMetrics = {
+        d1RowsRead: 1_000_000_000, // 1 billion rows
+        d1RowsWritten: 1_000_000, // 1 million rows
+      };
+      const cost = calculateCFCostFromMetrics(metrics);
+
+      // 1B reads at $0.001/B = $0.001
+      // 1M writes at $1.00/M = $1.00
+      expect(cost).toBeCloseTo(1.001, 4);
+    });
+
+    it('calculates KV costs correctly', () => {
+      const metrics: FeatureMetrics = {
+        kvReads: 1_000_000, // 1 million reads
+        kvWrites: 100_000, // 100K writes
+        kvDeletes: 50_000, // 50K deletes
+        kvLists: 10_000, // 10K lists
+      };
+      const cost = calculateCFCostFromMetrics(metrics);
+
+      // 1M reads at $0.50/M = $0.50
+      // 100K writes at $5.00/M = $0.50
+      // 50K deletes at $5.00/M = $0.25
+      // 10K lists at $5.00/M = $0.05
+      expect(cost).toBeCloseTo(1.3, 4);
+    });
+
+    it('calculates R2 costs correctly', () => {
+      const metrics: FeatureMetrics = {
+        r2ClassA: 1_000_000, // 1 million Class A ops
+        r2ClassB: 1_000_000, // 1 million Class B ops
+      };
+      const cost = calculateCFCostFromMetrics(metrics);
+
+      // 1M Class A at $4.50/M = $4.50
+      // 1M Class B at $0.36/M = $0.36
+      expect(cost).toBeCloseTo(4.86, 4);
+    });
+
+    it('calculates Workers AI costs correctly', () => {
+      const metrics: FeatureMetrics = {
+        aiNeurons: 10_000, // 10K neurons
+      };
+      const cost = calculateCFCostFromMetrics(metrics);
+
+      // 10K neurons at $0.011/1000 = $0.11
+      expect(cost).toBeCloseTo(0.11, 4);
+    });
+
+    it('calculates DO costs correctly', () => {
+      const metrics: FeatureMetrics = {
+        doRequests: 1_000_000, // 1M requests
+        doGbSeconds: 1_000_000, // 1M GB-seconds
+      };
+      const cost = calculateCFCostFromMetrics(metrics);
+
+      // 1M requests at $0.15/M = $0.15
+      // 1M GB-seconds at $12.50/M = $12.50
+      expect(cost).toBeCloseTo(12.65, 4);
+    });
+
+    it('calculates Vectorize costs correctly', () => {
+      const metrics: FeatureMetrics = {
+        vectorizeQueries: 1_000_000, // 1M queries
+      };
+      const cost = calculateCFCostFromMetrics(metrics);
+
+      // 1M queries at $0.01/M = $0.01
+      expect(cost).toBeCloseTo(0.01, 4);
+    });
+
+    it('calculates Queues costs correctly', () => {
+      const metrics: FeatureMetrics = {
+        queueMessages: 1_000_000, // 1M messages
+      };
+      const cost = calculateCFCostFromMetrics(metrics);
+
+      // 1M messages at $0.40/M = $0.40
+      expect(cost).toBeCloseTo(0.4, 4);
+    });
+
+    it('calculates combined costs for realistic workload', () => {
+      // Simulate a Scout scanner run
+      const metrics: FeatureMetrics = {
+        d1RowsRead: 50_000, // 50K reads
+        d1RowsWritten: 500, // 500 writes
+        kvReads: 1_000, // 1K KV reads
+        kvWrites: 100, // 100 KV writes
+        aiNeurons: 5_000, // 5K neurons for AI
+        queueMessages: 50, // 50 queue messages
+      };
+      const cost = calculateCFCostFromMetrics(metrics);
+
+      // All these are small fractions of a cent
+      // D1: 50K/1B * $0.001 + 500/1M * $1 ≈ $0.0005
+      // KV: 1K/1M * $0.50 + 100/1M * $5 ≈ $0.001
+      // AI: 5K/1000 * $0.011 = $0.055
+      // Queue: 50/1M * $0.40 ≈ $0.00002
+      // Total ≈ $0.057
+      expect(cost).toBeGreaterThan(0);
+      expect(cost).toBeLessThan(0.1); // Sanity check
+    });
+
+    it('handles undefined and zero values', () => {
+      const metrics: FeatureMetrics = {
+        d1RowsRead: 0,
+        d1RowsWritten: undefined,
+        kvReads: 1_000_000,
+        // Other fields not present
+      };
+      const cost = calculateCFCostFromMetrics(metrics);
+
+      // Only KV reads should contribute
+      expect(cost).toBeCloseTo(0.5, 4);
+    });
+  });
+});

package/templates/shared/tests/unit/economics.test.ts

@@ -0,0 +1,365 @@
+/**
+ * Unit Tests for BCU Cost Allocator
+ *
+ * Tests scarcity-weighted quota enforcement via Budget Consumption Units.
+ *
+ * @module tests/unit/economics
+ * @created 2026-01-23
+ * @task Intelligent Degradation for Platform Usage
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+  calculateBCU,
+  calculateBCUForResource,
+  checkBCUBudget,
+  usdToBCU,
+  bcuToUSD,
+  describeDominantResource,
+  formatBCUResult,
+  getTopContributors,
+  combineBCUResults,
+  DEFAULT_BCU_WEIGHTS,
+  type BCUResult,
+} from '../../workers/lib/economics';
+import type { FeatureMetrics } from '@littlebearapps/platform-consumer-sdk';
+
+describe('BCU Cost Allocator', () => {
+  describe('calculateBCU', () => {
+    it('returns zero for empty metrics', () => {
+      const metrics: FeatureMetrics = {};
+      const result = calculateBCU(metrics);
+
+      expect(result.total).toBe(0);
+      expect(result.dominantResource).toBeNull();
+      expect(result.dominantPercentage).toBe(0);
+    });
+
+    it('calculates BCU for single resource', () => {
+      const metrics: FeatureMetrics = { aiNeurons: 100 };
+      const result = calculateBCU(metrics);
+
+      // aiNeurons weight is 100, so 100 neurons = 10000 BCU
+      expect(result.total).toBe(10000);
+      expect(result.dominantResource).toBe('aiNeurons');
+      expect(result.dominantPercentage).toBe(100);
+      expect(result.breakdown.aiNeurons).toBe(10000);
+    });
+
+    it('calculates BCU for multiple resources', () => {
+      const metrics: FeatureMetrics = {
+        aiNeurons: 10, // 10 * 100 = 1000 BCU
+        d1RowsWritten: 100, // 100 * 10 = 1000 BCU
+        kvWrites: 1000, // 1000 * 1 = 1000 BCU
+        requests: 100000, // 100000 * 0.001 = 100 BCU
+      };
+      const result = calculateBCU(metrics);
+
+      expect(result.total).toBe(3100);
+      expect(result.breakdown.aiNeurons).toBe(1000);
+      expect(result.breakdown.d1RowsWritten).toBe(1000);
+      expect(result.breakdown.kvWrites).toBe(1000);
+      expect(result.breakdown.requests).toBe(100);
+    });
+
+    it('identifies dominant resource correctly', () => {
+      const metrics: FeatureMetrics = {
+        aiNeurons: 100, // 10000 BCU (dominant)
+        kvWrites: 100, // 100 BCU
+        requests: 1000, // 1 BCU
+      };
+      const result = calculateBCU(metrics);
+
+      expect(result.dominantResource).toBe('aiNeurons');
+      // 10000 / 10101 * 100 ≈ 99%
+      expect(result.dominantPercentage).toBeGreaterThan(98);
+    });
+
+    it('handles zero values in metrics', () => {
+      const metrics: FeatureMetrics = {
+        aiNeurons: 0,
+        kvWrites: 0,
+        requests: 100,
+      };
+      const result = calculateBCU(metrics);
+
+      expect(result.total).toBe(0.1); // 100 * 0.001
+      expect(result.breakdown.aiNeurons).toBeUndefined();
+      expect(result.breakdown.kvWrites).toBeUndefined();
+    });
+
+    it('uses custom weights when provided', () => {
+      const metrics: FeatureMetrics = { aiNeurons: 10 };
+      const customWeights = { ...DEFAULT_BCU_WEIGHTS, aiNeurons: 1000 };
+
+      const defaultResult = calculateBCU(metrics);
+      const customResult = calculateBCU(metrics, customWeights);
+
+      expect(defaultResult.total).toBe(1000); // 10 * 100
+      expect(customResult.total).toBe(10000); // 10 * 1000
+    });
+  });
+
+  describe('calculateBCUForResource', () => {
+    it('calculates BCU for specific resource type', () => {
+      expect(calculateBCUForResource('aiNeurons', 10)).toBe(1000);
+      expect(calculateBCUForResource('d1RowsWritten', 100)).toBe(1000);
+      expect(calculateBCUForResource('kvWrites', 100)).toBe(100);
+      expect(calculateBCUForResource('requests', 1000)).toBe(1);
+    });
+  });
+
+  describe('checkBCUBudget', () => {
+    it('calculates utilisation correctly', () => {
+      const state = checkBCUBudget(7000, 10000);
+
+      expect(state.currentBCU).toBe(7000);
+      expect(state.limitBCU).toBe(10000);
+      expect(state.utilisation).toBe(0.7);
+      expect(state.exceeded).toBe(false);
+    });
+
+    it('detects exceeded budget', () => {
+      const state = checkBCUBudget(12000, 10000);
+
+      expect(state.utilisation).toBe(1.2);
+      expect(state.exceeded).toBe(true);
+    });
+
+    it('handles zero budget limit', () => {
+      const state = checkBCUBudget(100, 0);
+
+      // When limit is 0, utilisation is 0 (can't divide by zero)
+      // and exceeded is true because any usage exceeds a zero limit
+      expect(state.utilisation).toBe(0);
+      expect(state.exceeded).toBe(true);
+    });
+
+    it('handles exact budget match', () => {
+      const state = checkBCUBudget(10000, 10000);
+
+      expect(state.utilisation).toBe(1);
+      expect(state.exceeded).toBe(false); // Exact match is not exceeded
+    });
+  });
+
+  describe('usdToBCU / bcuToUSD', () => {
+    it('converts USD to BCU', () => {
+      expect(usdToBCU(1)).toBe(10000);
+      expect(usdToBCU(5)).toBe(50000);
+      expect(usdToBCU(0.5)).toBe(5000);
+    });
+
+    it('converts BCU to USD', () => {
+      expect(bcuToUSD(10000)).toBe(1);
+      expect(bcuToUSD(50000)).toBe(5);
+      expect(bcuToUSD(5000)).toBe(0.5);
+    });
+
+    it('round-trips correctly', () => {
+      const original = 3.5;
+      const converted = bcuToUSD(usdToBCU(original));
+      expect(converted).toBe(original);
+    });
+  });
+
+  describe('describeDominantResource', () => {
+    it('returns human-readable descriptions', () => {
+      expect(describeDominantResource('aiNeurons')).toBe('AI compute (neurons)');
+      expect(describeDominantResource('d1RowsWritten')).toBe('D1 rows written');
+      expect(describeDominantResource('kvWrites')).toBe('KV writes');
+      expect(describeDominantResource('requests')).toBe('HTTP requests');
+    });
+
+    it('returns "none" for null', () => {
+      expect(describeDominantResource(null)).toBe('none');
+    });
+  });
+
+  describe('formatBCUResult', () => {
+    it('formats result as readable string', () => {
+      const result: BCUResult = {
+        total: 5000,
+        breakdown: { aiNeurons: 4000, kvWrites: 1000 },
+        dominantResource: 'aiNeurons',
+        dominantPercentage: 80,
+      };
+
+      const formatted = formatBCUResult(result);
+
+      expect(formatted).toContain('BCU: 5000.00');
+      expect(formatted).toContain('dominant: AI compute (neurons) (80.0%)');
+    });
+
+    it('handles null dominant resource', () => {
+      const result: BCUResult = {
+        total: 0,
+        breakdown: {},
+        dominantResource: null,
+        dominantPercentage: 0,
+      };
+
+      const formatted = formatBCUResult(result);
+      expect(formatted).toContain('dominant: none');
+    });
+  });
+
+  describe('getTopContributors', () => {
+    it('returns top N contributors sorted by BCU', () => {
+      const result: BCUResult = {
+        total: 6000,
+        breakdown: {
+          aiNeurons: 3000,
+          d1RowsWritten: 2000,
+          kvWrites: 800,
+          requests: 200,
+        },
+        dominantResource: 'aiNeurons',
+        dominantPercentage: 50,
+      };
+
+      const top = getTopContributors(result, 3);
+
+      expect(top.length).toBe(3);
+      expect(top[0].resource).toBe('aiNeurons');
+      expect(top[0].bcu).toBe(3000);
+      expect(top[0].percentage).toBe(50);
+      expect(top[1].resource).toBe('d1RowsWritten');
+      expect(top[2].resource).toBe('kvWrites');
+    });
+
+    it('handles fewer contributors than requested', () => {
+      const result: BCUResult = {
+        total: 1000,
+        breakdown: { aiNeurons: 1000 },
+        dominantResource: 'aiNeurons',
+        dominantPercentage: 100,
+      };
+
+      const top = getTopContributors(result, 5);
+      expect(top.length).toBe(1);
+    });
+  });
+
+  describe('combineBCUResults', () => {
+    it('combines multiple results correctly', () => {
+      const results: BCUResult[] = [
+        {
+          total: 1000,
+          breakdown: { aiNeurons: 1000 },
+          dominantResource: 'aiNeurons',
+          dominantPercentage: 100,
+        },
+        {
+          total: 500,
+          breakdown: { kvWrites: 500 },
+          dominantResource: 'kvWrites',
+          dominantPercentage: 100,
+        },
+        {
+          total: 200,
+          breakdown: { aiNeurons: 200 },
+          dominantResource: 'aiNeurons',
+          dominantPercentage: 100,
+        },
+      ];
+
+      const combined = combineBCUResults(results);
+
+      expect(combined.total).toBe(1700);
+      expect(combined.breakdown.aiNeurons).toBe(1200);
+      expect(combined.breakdown.kvWrites).toBe(500);
+      expect(combined.dominantResource).toBe('aiNeurons');
+    });
+
+    it('handles empty results array', () => {
+      const combined = combineBCUResults([]);
+
+      expect(combined.total).toBe(0);
+      expect(combined.dominantResource).toBeNull();
+    });
+  });
+
+  describe('Weight Ratios', () => {
+    it('AI is weighted much higher than D1 writes', () => {
+      // 1 AI neuron should cost more than 1 D1 write
+      const aiWeight = DEFAULT_BCU_WEIGHTS.aiNeurons;
+      const d1Weight = DEFAULT_BCU_WEIGHTS.d1RowsWritten;
+
+      expect(aiWeight).toBeGreaterThan(d1Weight);
+      expect(aiWeight / d1Weight).toBe(10); // AI is 10x D1 writes
+    });
+
+    it('writes are weighted higher than reads', () => {
+      expect(DEFAULT_BCU_WEIGHTS.d1RowsWritten).toBeGreaterThan(DEFAULT_BCU_WEIGHTS.d1RowsRead);
+      expect(DEFAULT_BCU_WEIGHTS.kvWrites).toBeGreaterThan(DEFAULT_BCU_WEIGHTS.kvReads);
+    });
+
+    it('requests have very low weight', () => {
+      expect(DEFAULT_BCU_WEIGHTS.requests).toBeLessThan(0.01);
+    });
+  });
+
+  describe('Real-World Scenarios', () => {
+    it('calculates typical Scout OCR invocation', () => {
+      // A typical Scout OCR invocation might:
+      // - 50 AI neurons (OCR processing)
+      // - 10 D1 writes (store results)
+      // - 5 KV writes (cache)
+      // - 1 request
+      const metrics: FeatureMetrics = {
+        aiNeurons: 50,
+        d1RowsWritten: 10,
+        kvWrites: 5,
+        requests: 1,
+      };
+
+      const result = calculateBCU(metrics);
+
+      // 50*100 + 10*10 + 5*1 + 1*0.001 = 5000 + 100 + 5 + 0.001 = 5105.001
+      expect(result.total).toBeCloseTo(5105, 0);
+      expect(result.dominantResource).toBe('aiNeurons');
+    });
+
+    it('calculates typical Brand Copilot API call', () => {
+      // A typical Brand Copilot call might:
+      // - 200 AI neurons (LLM processing)
+      // - 3 D1 writes
+      // - 10 KV reads
+      // - 2 KV writes
+      const metrics: FeatureMetrics = {
+        aiNeurons: 200,
+        d1RowsWritten: 3,
+        kvReads: 10,
+        kvWrites: 2,
+        requests: 1,
+      };
+
+      const result = calculateBCU(metrics);
+
+      // 200*100 + 3*10 + 10*0.1 + 2*1 + 1*0.001 = 20000 + 30 + 1 + 2 + 0.001 ≈ 20033
+      expect(result.total).toBeCloseTo(20033, 0);
+      expect(result.dominantResource).toBe('aiNeurons');
+      expect(result.dominantPercentage).toBeGreaterThan(99);
+    });
+
+    it('calculates read-heavy workload', () => {
+      // A read-heavy analytics query:
+      // - 0 AI neurons
+      // - 1000 D1 reads
+      // - 50 KV reads
+      // - 0 writes
+      const metrics: FeatureMetrics = {
+        d1RowsRead: 1000,
+        kvReads: 50,
+        requests: 1,
+      };
+
+      const result = calculateBCU(metrics);
+
+      // 1000*0.01 + 50*0.1 + 1*0.001 = 10 + 5 + 0.001 = 15.001
+      expect(result.total).toBeCloseTo(15, 0);
+      expect(result.dominantResource).toBe('d1RowsRead');
+    });
+  });
+});