@littlebearapps/platform-admin-sdk 1.5.0 → 2.0.0

package/templates/shared/scripts/ops/backfill-monthly-rollups.ts

@@ -0,0 +1,125 @@
+#!/usr/bin/env npx tsx
+/**
+ * Monthly Rollup Backfill Script
+ *
+ * Aggregates daily_usage_rollups into monthly_usage_rollups via the D1 REST API.
+ * Queries existing daily data and rolls it up to monthly granularity.
+ *
+ * Prerequisites:
+ *   CLOUDFLARE_API_TOKEN  — API token with D1:Write permissions
+ *   CLOUDFLARE_ACCOUNT_ID — Your Cloudflare account ID
+ *   D1_DATABASE_ID        — Your platform-metrics D1 database ID
+ *
+ * Usage:
+ *   npx tsx scripts/ops/backfill-monthly-rollups.ts
+ *   npx tsx scripts/ops/backfill-monthly-rollups.ts --dry-run
+ *   npx tsx scripts/ops/backfill-monthly-rollups.ts --start 2026-01 --end 2026-03
+ *   npx tsx scripts/ops/backfill-monthly-rollups.ts --limit 12
+ */
+
+const REST_API_BASE = 'https://api.cloudflare.com/client/v4';
+
+interface Args {
+  start?: string;
+  end?: string;
+  dryRun: boolean;
+  limit: number;
+}
+
+function parseArgs(): Args {
+  const args = process.argv.slice(2);
+  const result: Args = { dryRun: false, limit: 12 };
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--start' && args[i + 1]) result.start = args[++i];
+    else if (args[i] === '--end' && args[i + 1]) result.end = args[++i];
+    else if (args[i] === '--limit' && args[i + 1]) result.limit = Number(args[++i]);
+    else if (args[i] === '--dry-run') result.dryRun = true;
+  }
+
+  if (!result.start) {
+    const d = new Date();
+    d.setMonth(d.getMonth() - 6);
+    result.start = d.toISOString().slice(0, 7);
+  }
+  if (!result.end) {
+    result.end = new Date().toISOString().slice(0, 7);
+  }
+
+  return result;
+}
+
+function getEnvOrThrow(key: string): string {
+  const val = process.env[key];
+  if (!val) throw new Error(`Missing required env var: ${key}`);
+  return val;
+}
+
+async function d1Query(accountId: string, dbId: string, token: string, sql: string, params: unknown[] = []) {
+  const res = await fetch(`${REST_API_BASE}/accounts/${accountId}/d1/database/${dbId}/query`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ sql, params }),
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`D1 query failed (${res.status}): ${text}`);
+  }
+  return res.json() as Promise<{ result: Array<{ results: unknown[] }> }>;
+}
+
+async function main() {
+  const args = parseArgs();
+  const token = getEnvOrThrow('CLOUDFLARE_API_TOKEN');
+  const accountId = getEnvOrThrow('CLOUDFLARE_ACCOUNT_ID');
+  const dbId = getEnvOrThrow('D1_DATABASE_ID');
+
+  console.log(`Backfilling monthly rollups: ${args.start} → ${args.end} (limit: ${args.limit}, dry-run: ${args.dryRun})`);
+
+  // Generate month list
+  const months: string[] = [];
+  const current = new Date(args.start + '-01');
+  const endDate = new Date(args.end + '-01');
+  while (current <= endDate && months.length < args.limit) {
+    months.push(current.toISOString().slice(0, 7));
+    current.setMonth(current.getMonth() + 1);
+  }
+
+  let inserted = 0;
+  for (const month of months) {
+    const monthStart = `${month}-01`;
+    const nextMonth = new Date(monthStart);
+    nextMonth.setMonth(nextMonth.getMonth() + 1);
+    const monthEnd = nextMonth.toISOString().slice(0, 10);
+
+    if (args.dryRun) {
+      console.log(`[DRY-RUN] Would roll up ${month}`);
+      continue;
+    }
+
+    await d1Query(accountId, dbId, token, `
+      INSERT OR REPLACE INTO monthly_usage_rollups (
+        project, snapshot_month,
+        d1_reads, d1_writes, kv_reads, kv_writes,
+        r2_reads, r2_writes, worker_requests, total_cost_usd
+      )
+      SELECT
+        project, ? as snapshot_month,
+        SUM(d1_reads), SUM(d1_writes), SUM(kv_reads), SUM(kv_writes),
+        SUM(r2_reads), SUM(r2_writes), SUM(worker_requests), SUM(total_cost_usd)
+      FROM daily_usage_rollups
+      WHERE project = 'all' AND snapshot_date >= ? AND snapshot_date < ?
+      GROUP BY project
+    `, [month, monthStart, monthEnd]);
+
+    inserted++;
+    console.log(`  Rolled up ${month} (${inserted}/${months.length})`);
+  }
+
+  console.log(`Done. Inserted ${inserted} monthly rollup rows.`);
+}
+
+main().catch((err) => {
+  console.error('Fatal error:', err);
+  process.exit(1);
+});

package/templates/shared/scripts/ops/validate-controls.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+/**
+ * Validate Controls Script
+ *
+ * Validates budgets.yaml configuration:
+ * - No zero or negative limits
+ * - All features have d1_write_limit
+ * - Warns on suspiciously high/low values
+ * - Checks for orphaned entries (feature keys not in services.yaml)
+ *
+ * Usage:
+ *   node scripts/ops/validate-controls.js
+ *   node scripts/ops/validate-controls.js --strict
+ */
+
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parse } from 'yaml';
+
+const ROOT = resolve(import.meta.dirname, '..', '..');
+const strict = process.argv.includes('--strict');
+
+let exitCode = 0;
+let warnings = 0;
+let errors = 0;
+
+function warn(msg) {
+  console.warn(`  WARN: ${msg}`);
+  warnings++;
+  if (strict) exitCode = 1;
+}
+
+function error(msg) {
+  console.error(`  ERROR: ${msg}`);
+  errors++;
+  exitCode = 1;
+}
+
+function normaliseBudgetValue(val) {
+  if (typeof val === 'number') return val;
+  if (typeof val === 'string') return Number(val.replace(/_/g, ''));
+  return NaN;
+}
+
+// Load budgets.yaml
+let budgets;
+try {
+  const raw = readFileSync(resolve(ROOT, 'platform/config/budgets.yaml'), 'utf-8');
+  budgets = parse(raw);
+} catch (err) {
+  console.error('Failed to load budgets.yaml:', err.message);
+  process.exit(1);
+}
+
+// Load services.yaml for cross-reference
+let services;
+try {
+  const raw = readFileSync(resolve(ROOT, 'platform/config/services.yaml'), 'utf-8');
+  services = parse(raw);
+} catch {
+  services = null;
+}
+
+console.log('Validating budgets.yaml...\n');
+
+// Validate feature budgets
+const featureBudgets = budgets?.features ?? budgets?.feature_budgets ?? {};
+const featureKeys = Object.keys(featureBudgets);
+
+console.log(`Found ${featureKeys.length} feature budget entries\n`);
+
+for (const key of featureKeys) {
+  const budget = featureBudgets[key];
+  console.log(`  Checking ${key}...`);
+
+  if (!budget || typeof budget !== 'object') {
+    error(`${key}: budget is not an object`);
+    continue;
+  }
+
+  // Check for zero limits
+  for (const [field, rawValue] of Object.entries(budget)) {
+    const value = normaliseBudgetValue(rawValue);
+    if (isNaN(value)) {
+      error(`${key}.${field}: value "${rawValue}" is not a valid number`);
+    } else if (value <= 0) {
+      error(`${key}.${field}: value is ${value} (must be positive)`);
+    } else if (value < 100 && field.includes('d1')) {
+      warn(`${key}.${field}: suspiciously low D1 limit (${value})`);
+    } else if (value > 100_000_000_000) {
+      warn(`${key}.${field}: suspiciously high limit (${value})`);
+    }
+  }
+
+  // Check for d1_write_limit
+  const hasD1Write = Object.keys(budget).some(
+    (f) => f.includes('d1') && (f.includes('write') || f.includes('written'))
+  );
+  if (!hasD1Write) {
+    warn(`${key}: no d1_write_limit or d1_rows_written field`);
+  }
+
+  // Check feature key format (project:category:feature)
+  const parts = key.split(':');
+  if (parts.length < 3) {
+    warn(`${key}: feature key should have format project:category:feature (has ${parts.length} parts)`);
+  }
+}
+
+// Cross-reference with services.yaml
+if (services) {
+  const registeredProjects = new Set();
+  const projects = services?.projects ?? [];
+  for (const p of Array.isArray(projects) ? projects : Object.keys(projects)) {
+    const name = typeof p === 'string' ? p : p?.name ?? p?.id;
+    if (name) registeredProjects.add(name);
+  }
+
+  for (const key of featureKeys) {
+    const project = key.split(':')[0];
+    if (registeredProjects.size > 0 && !registeredProjects.has(project)) {
+      warn(`${key}: project "${project}" not found in services.yaml`);
+    }
+  }
+}
+
+// Global budget check
+const globalBudget = budgets?.global ?? budgets?.global_budget;
+if (!globalBudget) {
+  warn('No global budget section found');
+} else {
+  for (const [field, rawValue] of Object.entries(globalBudget)) {
+    const value = normaliseBudgetValue(rawValue);
+    if (isNaN(value) || value <= 0) {
+      error(`global.${field}: invalid value "${rawValue}"`);
+    }
+  }
+}
+
+console.log(`\nResults: ${errors} errors, ${warnings} warnings`);
+process.exit(exitCode);

package/templates/shared/tests/contract/validate-schemas.test.ts

@@ -0,0 +1,130 @@
+/**
+ * Contract Tests for JSON Schemas
+ *
+ * Validates telemetry envelope + error report schemas against fixtures.
+ * Ensures contracts remain valid as schemas evolve.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+function loadJson(relativePath: string): unknown {
+  const fullPath = resolve(__dirname, '..', '..', relativePath);
+  return JSON.parse(readFileSync(fullPath, 'utf-8'));
+}
+
+// ===========================================================================
+// Envelope Schema
+// ===========================================================================
+
+describe('telemetry envelope schema', () => {
+  const schema = loadJson('contracts/schemas/envelope.v1.schema.json') as {
+    required?: string[];
+    properties?: Record<string, unknown>;
+  };
+
+  it('has required version 1 schema structure', () => {
+    expect(schema).toBeDefined();
+    expect(schema.required).toBeDefined();
+    expect(Array.isArray(schema.required)).toBe(true);
+  });
+
+  it('requires core fields', () => {
+    const required = schema.required ?? [];
+    expect(required).toContain('version');
+    expect(required).toContain('project');
+    expect(required).toContain('feature');
+  });
+
+  it('defines resource_usage properties', () => {
+    const props = schema.properties ?? {};
+    expect(props.resource_usage).toBeDefined();
+  });
+});
+
+// ===========================================================================
+// Valid Fixture
+// ===========================================================================
+
+describe('valid telemetry envelope fixture', () => {
+  const fixture = loadJson('tests/fixtures/telemetry-envelope-valid.json') as Record<string, unknown>;
+
+  it('has version 1', () => {
+    expect(fixture.version).toBe(1);
+  });
+
+  it('has valid project and feature format', () => {
+    expect(typeof fixture.project).toBe('string');
+    expect(typeof fixture.feature).toBe('string');
+    const feature = fixture.feature as string;
+    expect(feature.split(':').length).toBeGreaterThanOrEqual(3);
+  });
+
+  it('has resource_usage with numeric values', () => {
+    const usage = fixture.resource_usage as Record<string, unknown>;
+    expect(usage).toBeDefined();
+    expect(typeof usage.d1_reads).toBe('number');
+    expect(typeof usage.d1_writes).toBe('number');
+    expect(usage.d1_reads).toBeGreaterThanOrEqual(0);
+    expect(usage.d1_writes).toBeGreaterThanOrEqual(0);
+  });
+
+  it('has valid handler_type', () => {
+    expect(['fetch', 'scheduled', 'queue', 'alarm', 'tail']).toContain(fixture.handler_type);
+  });
+
+  it('has valid outcome', () => {
+    expect(['ok', 'error', 'exception', 'canceled']).toContain(fixture.outcome);
+  });
+});
+
+// ===========================================================================
+// Invalid Fixture
+// ===========================================================================
+
+describe('invalid telemetry envelope fixture', () => {
+  const fixture = loadJson('tests/fixtures/telemetry-envelope-invalid.json') as Record<string, unknown>;
+
+  it('has wrong version', () => {
+    expect(fixture.version).not.toBe(1);
+  });
+
+  it('has empty project', () => {
+    expect(fixture.project).toBe('');
+  });
+
+  it('has malformed feature ID (missing colons)', () => {
+    const feature = fixture.feature as string;
+    expect(feature.split(':').length).toBeLessThan(3);
+  });
+
+  it('has invalid resource_usage values', () => {
+    const usage = fixture.resource_usage as Record<string, unknown>;
+    const hasInvalid = Object.values(usage).some(
+      (v) => typeof v !== 'number' || v < 0
+    );
+    expect(hasInvalid).toBe(true);
+  });
+});
+
+// ===========================================================================
+// Error Report Schema
+// ===========================================================================
+
+describe('error report schema', () => {
+  const schema = loadJson('contracts/schemas/error_report.v1.schema.json') as {
+    required?: string[];
+    properties?: Record<string, unknown>;
+  };
+
+  it('has required schema structure', () => {
+    expect(schema).toBeDefined();
+    expect(schema.required).toBeDefined();
+  });
+
+  it('requires error identification fields', () => {
+    const required = schema.required ?? [];
+    expect(required.length).toBeGreaterThan(0);
+  });
+});

package/templates/shared/tests/fixtures/telemetry-envelope-invalid.json

@@ -0,0 +1,9 @@
+{
+  "version": 99,
+  "project": "",
+  "feature": "missing-colon-format",
+  "resource_usage": {
+    "d1_reads": -1,
+    "d1_writes": "not-a-number"
+  }
+}

package/templates/shared/tests/fixtures/telemetry-envelope-valid.json

@@ -0,0 +1,27 @@
+{
+  "version": 1,
+  "timestamp": "2026-03-05T00:00:00Z",
+  "sdk_version": "1.4.0",
+  "project": "test-project",
+  "feature": "test-project:api:endpoint",
+  "handler_type": "fetch",
+  "outcome": "ok",
+  "duration_ms": 42,
+  "resource_usage": {
+    "d1_reads": 10,
+    "d1_writes": 2,
+    "kv_reads": 5,
+    "kv_writes": 1,
+    "r2_reads": 0,
+    "r2_writes": 0,
+    "ai_requests": 0,
+    "vectorize_reads": 0,
+    "queue_messages": 0,
+    "do_requests": 0,
+    "worker_subrequests": 0
+  },
+  "metadata": {
+    "worker_name": "test-worker",
+    "environment": "production"
+  }
+}

package/templates/shared/tests/helpers/mock-d1.ts

@@ -0,0 +1,61 @@
+import { vi } from 'vitest';
+
+interface D1RunResult {
+  success: boolean;
+  results?: unknown[];
+  meta?: Record<string, unknown>;
+}
+
+export class MockD1Database {
+  private runResults: D1RunResult[] = [];
+  private allResults: Array<{ results: unknown[] }> = [];
+  private firstResults: Array<unknown | null> = [];
+  statements: string[] = [];
+  bindings: unknown[][] = [];
+
+  queueRunResult(result: D1RunResult): void {
+    this.runResults.push(result);
+  }
+
+  queueAllResult(results: unknown[]): void {
+    this.allResults.push({ results });
+  }
+
+  queueFirstResult(result: unknown | null): void {
+    this.firstResults.push(result);
+  }
+
+  prepare(sql: string) {
+    this.statements.push(sql);
+    const self = this;
+    let boundValues: unknown[] = [];
+
+    const stmt = {
+      bind(...args: unknown[]) {
+        boundValues = args;
+        self.bindings.push(args);
+        return stmt;
+      },
+      run: vi.fn(async () => {
+        return self.runResults.shift() ?? { success: true, results: [] };
+      }),
+      all: vi.fn(async () => {
+        return self.allResults.shift() ?? { results: [] };
+      }),
+      first: vi.fn(async () => {
+        return self.firstResults.shift() ?? null;
+      }),
+    };
+
+    return stmt;
+  }
+
+  async batch(statements: unknown[]): Promise<D1RunResult[]> {
+    return statements.map(() => this.runResults.shift() ?? { success: true, results: [] });
+  }
+
+  async exec(sql: string): Promise<D1RunResult> {
+    this.statements.push(sql);
+    return { success: true };
+  }
+}

package/templates/shared/tests/helpers/mock-kv.ts

@@ -0,0 +1,37 @@
+import { vi } from 'vitest';
+
+export interface MockKV {
+  get: ReturnType<typeof vi.fn>;
+  put: ReturnType<typeof vi.fn>;
+  delete: ReturnType<typeof vi.fn>;
+  list: ReturnType<typeof vi.fn>;
+  _store: Map<string, string>;
+}
+
+export function createMockKV(initialData: Record<string, string> = {}): MockKV {
+  const store = new Map<string, string>(Object.entries(initialData));
+  return {
+    get: vi.fn((key: string, type?: string) => {
+      const raw = store.get(key) ?? null;
+      if (raw === null) return Promise.resolve(null);
+      if (type === 'json') return Promise.resolve(JSON.parse(raw));
+      return Promise.resolve(raw);
+    }),
+    put: vi.fn((key: string, value: string, _opts?: unknown) => {
+      store.set(key, typeof value === 'string' ? value : JSON.stringify(value));
+      return Promise.resolve();
+    }),
+    delete: vi.fn((key: string) => {
+      store.delete(key);
+      return Promise.resolve();
+    }),
+    list: vi.fn((opts: { prefix?: string; limit?: number } = {}) => {
+      const keys = [...store.keys()]
+        .filter((k) => !opts.prefix || k.startsWith(opts.prefix))
+        .slice(0, opts.limit ?? 1000)
+        .map((name) => ({ name }));
+      return Promise.resolve({ keys, list_complete: true });
+    }),
+    _store: store,
+  };
+}

package/templates/shared/tests/unit/workers/batch-persistence.test.ts

@@ -0,0 +1,133 @@
+/**
+ * Unit Tests for Batch Resource Snapshot Persistence
+ *
+ * Tests the batch D1 insert logic in persistResourceUsageSnapshots():
+ * - Rows are batched in groups of 25
+ * - Fallback to individual inserts on batch failure
+ * - SQL uses ON CONFLICT DO UPDATE
+ */
+
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+import { MockD1Database } from '../../helpers/mock-d1';
+
+// ---------------------------------------------------------------------------
+// Module mocks
+// ---------------------------------------------------------------------------
+
+vi.mock('@littlebearapps/platform-consumer-sdk', async (importOriginal) => {
+  const actual = await importOriginal();
+  return {
+    ...actual,
+    createLoggerFromEnv: () => ({
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+      debug: vi.fn(),
+    }),
+  };
+});
+
+import { persistResourceUsageSnapshots } from '../../../workers/lib/usage/scheduled/data-collection';
+
+// ---------------------------------------------------------------------------
+// BatchCapturingD1 — extends MockD1Database to track batch() calls
+// ---------------------------------------------------------------------------
+
+class BatchCapturingD1 extends MockD1Database {
+  batchCalls: unknown[][] = [];
+  batchShouldFail = false;
+  private batchFailCount = 0;
+  private batchFailMax = Infinity;
+
+  failBatchTimes(n: number): void {
+    this.batchShouldFail = true;
+    this.batchFailMax = n;
+    this.batchFailCount = 0;
+  }
+
+  async batch(statements: unknown[]): Promise<unknown[]> {
+    this.batchCalls.push([...statements]);
+    if (this.batchShouldFail && this.batchFailCount < this.batchFailMax) {
+      this.batchFailCount++;
+      throw new Error('Simulated batch failure');
+    }
+    return statements.map(() => ({ success: true, results: [] }));
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Fixture factory
+// ---------------------------------------------------------------------------
+
+function makeWorkerEntry(name: string) {
+  return {
+    scriptName: name,
+    requests: 100,
+    errors: 0,
+    cpuTimeMs: 50,
+    duration50thMs: 1,
+    duration99thMs: 5,
+  };
+}
+
+function makeUsageData(workerCount: number) {
+  return {
+    workers: Array.from({ length: workerCount }, (_, i) => makeWorkerEntry(`worker-${i}`)),
+    d1: { reads: 1000, writes: 100 },
+    kv: { reads: 500, writes: 50 },
+    r2: { reads: 10, writes: 2, storage: 1024 },
+  };
+}
+
+// ===========================================================================
+// Tests
+// ===========================================================================
+
+describe('persistResourceUsageSnapshots', () => {
+  it('batches rows in groups of 25', async () => {
+    const db = new BatchCapturingD1();
+    const usageData = makeUsageData(30);
+
+    await persistResourceUsageSnapshots(db as never, usageData as never, 'all');
+
+    // Should have called batch at least once
+    expect(db.batchCalls.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it('falls back to individual inserts on batch failure', async () => {
+    const db = new BatchCapturingD1();
+    db.failBatchTimes(1);
+    // Queue individual run results for fallback
+    for (let i = 0; i < 30; i++) {
+      db.queueRunResult({ success: true });
+    }
+
+    const usageData = makeUsageData(5);
+
+    await expect(
+      persistResourceUsageSnapshots(db as never, usageData as never, 'all')
+    ).resolves.not.toThrow();
+  });
+
+  it('handles empty usage data', async () => {
+    const db = new BatchCapturingD1();
+    const usageData = makeUsageData(0);
+
+    await persistResourceUsageSnapshots(db as never, usageData as never, 'all');
+
+    // Should not fail with empty data
+    expect(db.batchCalls.length).toBe(0);
+  });
+
+  it('uses ON CONFLICT in SQL statements', async () => {
+    const db = new BatchCapturingD1();
+    const usageData = makeUsageData(1);
+
+    await persistResourceUsageSnapshots(db as never, usageData as never, 'all');
+
+    const hasConflict = db.statements.some((s: string) =>
+      s.toUpperCase().includes('ON CONFLICT')
+    );
+    expect(hasConflict).toBe(true);
+  });
+});