@littlebearapps/platform-admin-sdk 1.4.2 → 1.5.0

package/templates/shared/scripts/ops/reset-budget-state.ts

@@ -0,0 +1,279 @@
+#!/usr/bin/env npx tsx
+/**
+ * Reset Budget State Script
+ *
+ * Resets circuit breaker state in KV when costs are back to safe levels.
+ * Used after cost corrections or billing anomalies to restore normal operation.
+ *
+ * Safety checks:
+ *   - Compares MTD cost against soft budget limit before allowing reset
+ *   - Costs > 1.5x soft limit require --force flag
+ *   - Dry run by default (must pass --execute to modify KV)
+ *
+ * Usage:
+ *   npx tsx scripts/ops/reset-budget-state.ts                    # Dry run (show state)
+ *   npx tsx scripts/ops/reset-budget-state.ts --execute          # Reset to 'active'
+ *   npx tsx scripts/ops/reset-budget-state.ts --execute --force  # Bypass safety check
+ *
+ * Environment Variables:
+ *   CLOUDFLARE_API_TOKEN  — API token with D1:Read and KV:Write
+ *   CLOUDFLARE_ACCOUNT_ID — Your Cloudflare account ID
+ *   D1_DATABASE_ID        — Your platform-metrics D1 database ID
+ *   KV_NAMESPACE_ID       — Your PLATFORM_CACHE KV namespace ID
+ */
+
+const REST_API_BASE = 'https://api.cloudflare.com/client/v4';
+
+// Circuit breaker KV keys to reset
+const CB_KEYS = {
+  GLOBAL_STOP: 'GLOBAL_STOP_ALL',
+} as const;
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface D1QueryResponse {
+  success: boolean;
+  errors?: Array<{ message: string }>;
+  result: Array<{ results: Record<string, unknown>[]; success: boolean }>;
+}
+
+interface CBKeyState {
+  key: string;
+  name: string;
+  currentValue: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// API helpers
+// ---------------------------------------------------------------------------
+
+async function queryD1(
+  sql: string,
+  accountId: string,
+  apiToken: string,
+  databaseId: string
+): Promise<Record<string, unknown>[]> {
+  const url = `${REST_API_BASE}/accounts/${accountId}/d1/database/${databaseId}/query`;
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${apiToken}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ sql }),
+  });
+  const body = (await response.json()) as D1QueryResponse;
+  if (!body.success) {
+    throw new Error(`D1 query failed: ${body.errors?.map((e) => e.message).join(', ') ?? 'Unknown'}`);
+  }
+  return body.result[0]?.results ?? [];
+}
+
+async function getKVKey(
+  key: string,
+  accountId: string,
+  apiToken: string,
+  namespaceId: string
+): Promise<string | null> {
+  const url = `${REST_API_BASE}/accounts/${accountId}/storage/kv/namespaces/${namespaceId}/values/${encodeURIComponent(key)}`;
+  const response = await fetch(url, { headers: { Authorization: `Bearer ${apiToken}` } });
+  if (response.status === 404) return null;
+  if (!response.ok) throw new Error(`KV read failed: ${response.status}`);
+  return await response.text();
+}
+
+async function setKVKey(
+  key: string,
+  value: string,
+  accountId: string,
+  apiToken: string,
+  namespaceId: string
+): Promise<void> {
+  const url = `${REST_API_BASE}/accounts/${accountId}/storage/kv/namespaces/${namespaceId}/values/${encodeURIComponent(key)}`;
+  const response = await fetch(url, {
+    method: 'PUT',
+    headers: { Authorization: `Bearer ${apiToken}`, 'Content-Type': 'text/plain' },
+    body: value,
+  });
+  if (!response.ok) throw new Error(`KV write failed for ${key}: ${response.status}`);
+}
+
+async function deleteKVKey(
+  key: string,
+  accountId: string,
+  apiToken: string,
+  namespaceId: string
+): Promise<void> {
+  const url = `${REST_API_BASE}/accounts/${accountId}/storage/kv/namespaces/${namespaceId}/values/${encodeURIComponent(key)}`;
+  const response = await fetch(url, {
+    method: 'DELETE',
+    headers: { Authorization: `Bearer ${apiToken}` },
+  });
+  if (!response.ok && response.status !== 404) {
+    throw new Error(`KV delete failed for ${key}: ${response.status}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Billing state + safety
+// ---------------------------------------------------------------------------
+
+async function getMtdCost(
+  accountId: string,
+  apiToken: string,
+  databaseId: string
+): Promise<{ mtdCostUsd: number; softLimitUsd: number }> {
+  // Get soft limit
+  const settingsResult = await queryD1(
+    `SELECT setting_value FROM usage_settings WHERE project = 'all' AND setting_key = 'budget_soft_limit' LIMIT 1;`,
+    accountId, apiToken, databaseId
+  );
+  const softLimitUsd = settingsResult.length > 0
+    ? parseFloat(settingsResult[0].setting_value as string)
+    : 100;
+
+  // Get MTD cost
+  const now = new Date();
+  const monthStart = `${now.getUTCFullYear()}-${String(now.getUTCMonth() + 1).padStart(2, '0')}-01`;
+  const mtdResult = await queryD1(
+    `SELECT SUM(total_cost_usd) as mtd_cost FROM daily_usage_rollups WHERE snapshot_date >= '${monthStart}';`,
+    accountId, apiToken, databaseId
+  );
+  const mtdCostUsd = mtdResult.length > 0 ? ((mtdResult[0].mtd_cost as number) ?? 0) : 0;
+
+  return { mtdCostUsd, softLimitUsd };
+}
+
+async function getCBKeyStates(
+  accountId: string,
+  apiToken: string,
+  namespaceId: string
+): Promise<CBKeyState[]> {
+  // Discover project-level CB keys from D1
+  const states: CBKeyState[] = [];
+
+  // Always check global stop
+  const globalValue = await getKVKey(CB_KEYS.GLOBAL_STOP, accountId, apiToken, namespaceId);
+  states.push({ key: CB_KEYS.GLOBAL_STOP, name: 'GLOBAL_STOP', currentValue: globalValue });
+
+  // Check common project status keys (user should extend for their projects)
+  const projectPrefixes = ['PROJECT:'];
+  for (const prefix of projectPrefixes) {
+    // KV list API to discover project keys
+    const listUrl = `${REST_API_BASE}/accounts/${accountId}/storage/kv/namespaces/${namespaceId}/keys?prefix=${encodeURIComponent(prefix)}&limit=100`;
+    try {
+      const response = await fetch(listUrl, { headers: { Authorization: `Bearer ${apiToken}` } });
+      if (response.ok) {
+        const data = (await response.json()) as { result: Array<{ name: string }> };
+        for (const key of data.result) {
+          if (key.name.endsWith(':STATUS')) {
+            const value = await getKVKey(key.name, accountId, apiToken, namespaceId);
+            states.push({ key: key.name, name: key.name, currentValue: value });
+          }
+        }
+      }
+    } catch { /* ignore — may not have list permission */ }
+  }
+
+  return states;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+  const executeMode = args.includes('--execute');
+  const forceMode = args.includes('--force');
+
+  const accountId = process.env.CLOUDFLARE_ACCOUNT_ID;
+  const apiToken = process.env.CLOUDFLARE_API_TOKEN;
+  const databaseId = process.env.D1_DATABASE_ID;
+  const namespaceId = process.env.KV_NAMESPACE_ID;
+
+  if (!apiToken || !accountId || !databaseId || !namespaceId) {
+    console.error('Error: Required environment variables:');
+    if (!apiToken) console.error('  CLOUDFLARE_API_TOKEN');
+    if (!accountId) console.error('  CLOUDFLARE_ACCOUNT_ID');
+    if (!databaseId) console.error('  D1_DATABASE_ID');
+    if (!namespaceId) console.error('  KV_NAMESPACE_ID');
+    process.exit(1);
+  }
+
+  console.log('='.repeat(80));
+  console.log('BUDGET STATE RESET');
+  console.log('='.repeat(80));
+  console.log(`Mode: ${executeMode ? 'EXECUTE (will modify KV)' : 'DRY RUN (preview only)'}`);
+  if (forceMode) console.log('Force: YES (bypassing safety checks)');
+  console.log('');
+
+  // Step 1: Check billing state
+  console.log('-'.repeat(80));
+  console.log('STEP 1: Billing State');
+  console.log('-'.repeat(80));
+  const { mtdCostUsd, softLimitUsd } = await getMtdCost(accountId, apiToken, databaseId);
+  const ratio = mtdCostUsd / softLimitUsd;
+  console.log(`Budget soft limit: $${softLimitUsd.toFixed(2)}`);
+  console.log(`MTD cost:          $${mtdCostUsd.toFixed(2)} (${(ratio * 100).toFixed(1)}%)`);
+  console.log('');
+
+  // Step 2: Safety check
+  if (ratio >= 1.5 && executeMode && !forceMode) {
+    console.log('BLOCKED: Costs exceed 1.5x soft limit. Use --force to bypass.');
+    process.exit(1);
+  }
+
+  // Step 3: Current CB state
+  console.log('-'.repeat(80));
+  console.log('STEP 2: Current Circuit Breaker State');
+  console.log('-'.repeat(80));
+  const cbStates = await getCBKeyStates(accountId, apiToken, namespaceId);
+
+  let anyNeedReset = false;
+  for (const state of cbStates) {
+    const needsReset = state.key === CB_KEYS.GLOBAL_STOP
+      ? state.currentValue !== null
+      : state.currentValue !== 'active';
+    if (needsReset) anyNeedReset = true;
+    const status = state.currentValue ?? '(not set)';
+    const resetIcon = needsReset ? '→ will reset' : '✓ OK';
+    console.log(`  ${state.name.padEnd(35)} ${status.padEnd(15)} ${resetIcon}`);
+  }
+  console.log('');
+
+  if (!anyNeedReset) {
+    console.log('All circuit breakers are already in normal state. No changes needed.');
+    return;
+  }
+
+  if (!executeMode) {
+    console.log('DRY RUN COMPLETE — run with --execute to reset circuit breakers.');
+    return;
+  }
+
+  // Step 4: Execute reset
+  console.log('-'.repeat(80));
+  console.log('STEP 3: Executing Reset');
+  console.log('-'.repeat(80));
+  for (const state of cbStates) {
+    if (state.key === CB_KEYS.GLOBAL_STOP) {
+      if (state.currentValue !== null) {
+        await deleteKVKey(state.key, accountId, apiToken, namespaceId);
+        console.log(`  ${state.key}: deleted`);
+      }
+    } else if (state.currentValue !== 'active') {
+      await setKVKey(state.key, 'active', accountId, apiToken, namespaceId);
+      console.log(`  ${state.key}: reset to 'active' (was: '${state.currentValue ?? 'null'}')`);
+    }
+  }
+
+  console.log('');
+  console.log('='.repeat(80));
+  console.log('RESET COMPLETE');
+  console.log('='.repeat(80));
+}
+
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});

package/templates/shared/scripts/ops/validate-pipeline.ts

@@ -0,0 +1,237 @@
+#!/usr/bin/env npx tsx
+/**
+ * Pipeline Validation Script
+ *
+ * Validates the end-to-end telemetry pipeline:
+ *   1. Injects a test telemetry message into the platform-telemetry queue
+ *   2. Polls Analytics Engine (up to 90s) for the test data
+ *   3. Validates all metric types land correctly
+ *   4. Validates project/feature hierarchy integrity
+ *   5. Reports KV circuit breaker state (informational)
+ *
+ * Usage:
+ *   npx tsx scripts/ops/validate-pipeline.ts
+ *
+ * Environment Variables:
+ *   CLOUDFLARE_API_TOKEN  — API token with Queue, Analytics Engine, D1 access
+ *   CLOUDFLARE_ACCOUNT_ID — Your Cloudflare account ID
+ */
+
+import type { TelemetryMessage, FeatureMetrics } from '@littlebearapps/platform-consumer-sdk';
+import { METRIC_FIELDS } from '@littlebearapps/platform-consumer-sdk';
+
+const API_TOKEN = process.env.CLOUDFLARE_API_TOKEN;
+const ACCOUNT_ID = process.env.CLOUDFLARE_ACCOUNT_ID;
+
+// Test identifiers — unique per run to avoid picking up stale data
+const TEST_RUN_ID = Math.floor(Date.now() / 1000).toString(36);
+const TEST_PROJECT = 'TEST_PROJ_VALIDATOR';
+const TEST_CATEGORY = 'validate';
+const TEST_FEATURE = `pipeline_${TEST_RUN_ID}`;
+const TEST_FEATURE_KEY = `${TEST_PROJECT}:${TEST_CATEGORY}:${TEST_FEATURE}`;
+
+// Analytics Engine dataset name (must match your wrangler config binding)
+const DATASET = '"platform-analytics"';
+const QUEUE_NAME = 'platform-telemetry';
+
+// Polling config — Analytics Engine is eventually consistent (10–30s typical, up to 90s)
+const POLL_INTERVAL_MS = 5_000;
+const POLL_TIMEOUT_MS = 90_000;
+const MAX_POLLS = Math.ceil(POLL_TIMEOUT_MS / POLL_INTERVAL_MS);
+
+// Service → metric groups for validation checklist
+const SERVICE_METRICS: Record<string, readonly string[]> = {
+  D1: ['d1Writes', 'd1Reads', 'd1RowsRead', 'd1RowsWritten'],
+  KV: ['kvReads', 'kvWrites', 'kvDeletes', 'kvLists'],
+  AI: ['aiRequests', 'aiNeurons'],
+  Vectorize: ['vectorizeQueries', 'vectorizeInserts'],
+  R2: ['r2ClassA', 'r2ClassB'],
+  'Durable Objects': ['doRequests', 'doGbSeconds'],
+  Queues: ['queueMessages'],
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// ---------------------------------------------------------------------------
+// Step 1: Inject test telemetry
+// ---------------------------------------------------------------------------
+
+async function getQueueId(queueName: string): Promise<string | null> {
+  const url = `https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/queues`;
+  const response = await fetch(url, { headers: { Authorization: `Bearer ${API_TOKEN}` } });
+  if (!response.ok) return null;
+  const data = (await response.json()) as { success: boolean; result: Array<{ queue_id: string; queue_name: string }> };
+  return data.result.find((q) => q.queue_name === queueName)?.queue_id ?? null;
+}
+
+function createTestMetrics(): FeatureMetrics {
+  return {
+    d1Writes: 5, d1Reads: 10, d1RowsRead: 100, d1RowsWritten: 25,
+    kvReads: 20, kvWrites: 2, kvDeletes: 1, kvLists: 3,
+    aiRequests: 2, aiNeurons: 100,
+    vectorizeQueries: 3, vectorizeInserts: 5,
+    doRequests: 1, doGbSeconds: 0.5,
+    r2ClassA: 1, r2ClassB: 5,
+    queueMessages: 10,
+    requests: 1, cpuMs: 50,
+  };
+}
+
+async function injectTelemetry(): Promise<{ success: boolean; timestamp: number; metrics: FeatureMetrics; error?: string }> {
+  const timestamp = Date.now();
+  const queueId = await getQueueId(QUEUE_NAME);
+  if (!queueId) return { success: false, timestamp, metrics: createTestMetrics(), error: `Queue "${QUEUE_NAME}" not found` };
+
+  console.log(`  Found queue ID: ${queueId}`);
+
+  const metrics = createTestMetrics();
+  const message: TelemetryMessage = {
+    feature_key: TEST_FEATURE_KEY,
+    project: TEST_PROJECT,
+    category: TEST_CATEGORY,
+    feature: TEST_FEATURE,
+    metrics,
+    timestamp,
+  };
+
+  const url = `https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/queues/${queueId}/messages`;
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${API_TOKEN}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ body: message, contentType: 'json' }),
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    return { success: false, timestamp, metrics, error: `HTTP ${response.status}: ${text}` };
+  }
+
+  const data = (await response.json()) as { success: boolean; errors: Array<{ message: string }> };
+  if (!data.success) return { success: false, timestamp, metrics, error: data.errors.map((e) => e.message).join(', ') };
+
+  console.log(`  Sent test message with ${Object.keys(metrics).length} metrics`);
+  return { success: true, timestamp, metrics };
+}
+
+// ---------------------------------------------------------------------------
+// Step 2: Verify in Analytics Engine
+// ---------------------------------------------------------------------------
+
+async function verifyAnalyticsEngine(expectedMetrics: FeatureMetrics): Promise<boolean> {
+  if (!API_TOKEN || !ACCOUNT_ID) return false;
+
+  const metricClauses = METRIC_FIELDS.map((field, i) => `SUM(double${i + 1}) as ${field}`).join(', ');
+  const sql = `SELECT index1 as feature_key, blob1 as project, blob2 as category, blob3 as feature, ${metricClauses}, count() as row_count FROM ${DATASET} WHERE index1 = '${TEST_FEATURE_KEY}' AND timestamp >= NOW() - INTERVAL '1' HOUR GROUP BY index1, blob1, blob2, blob3`;
+
+  for (let attempt = 1; attempt <= MAX_POLLS; attempt++) {
+    const remaining = Math.round((POLL_TIMEOUT_MS - (attempt - 1) * POLL_INTERVAL_MS) / 1000);
+    console.log(`  Polling attempt ${attempt}/${MAX_POLLS} (~${remaining}s remaining)…`);
+
+    const url = `https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/analytics_engine/sql`;
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${API_TOKEN}`, 'Content-Type': 'text/plain' },
+      body: sql,
+    });
+
+    if (response.ok) {
+      const data = (await response.json()) as { data?: Record<string, unknown>[]; rows?: number };
+      if (data.data && data.data.length > 0) {
+        const row = data.data[0];
+        console.log(`  Found data!`);
+
+        // Validate hierarchy
+        const projectOk = String(row.project ?? '') === TEST_PROJECT;
+        const categoryOk = String(row.category ?? '') === TEST_CATEGORY;
+        const featureOk = String(row.feature ?? '') === TEST_FEATURE;
+        console.log(`  Hierarchy: project=${projectOk ? 'OK' : 'FAIL'} category=${categoryOk ? 'OK' : 'FAIL'} feature=${featureOk ? 'OK' : 'FAIL'}`);
+
+        // Validate metrics by service
+        let allPassed = projectOk && categoryOk && featureOk;
+        for (const [service, metrics] of Object.entries(SERVICE_METRICS)) {
+          let serviceOk = true;
+          for (const metric of metrics) {
+            const expected = expectedMetrics[metric as keyof FeatureMetrics];
+            if (!expected) continue;
+            const actual = typeof row[metric] === 'string' ? parseFloat(row[metric] as string) : ((row[metric] as number) ?? 0);
+            if (actual < expected) { serviceOk = false; allPassed = false; }
+          }
+          const checkedMetrics = metrics.filter((m) => (expectedMetrics[m as keyof FeatureMetrics] ?? 0) > 0);
+          if (checkedMetrics.length > 0) {
+            console.log(`  ${serviceOk ? 'PASS' : 'FAIL'} ${service}`);
+          }
+        }
+
+        return allPassed;
+      }
+    }
+
+    if (attempt < MAX_POLLS) await sleep(POLL_INTERVAL_MS);
+  }
+
+  console.log(`  Timeout: no data found after ${POLL_TIMEOUT_MS / 1000}s`);
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main(): Promise<void> {
+  console.log('='.repeat(70));
+  console.log('Platform Pipeline Validation');
+  console.log('='.repeat(70));
+  console.log('');
+
+  if (!API_TOKEN || !ACCOUNT_ID) {
+    console.error('ERROR: CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID are required');
+    process.exit(1);
+  }
+
+  // Step 1
+  console.log('Step 1: Inject Telemetry Message');
+  console.log('-'.repeat(50));
+  const injectResult = await injectTelemetry();
+  if (!injectResult.success) {
+    console.error(`FAILED: ${injectResult.error}`);
+    process.exit(1);
+  }
+  console.log('');
+
+  // Step 2
+  console.log('Step 2: Verify Analytics Engine');
+  console.log('-'.repeat(50));
+  console.log('  Analytics Engine is eventually consistent — polling for up to 90s…');
+  const aeOk = await verifyAnalyticsEngine(injectResult.metrics);
+  console.log('');
+
+  // Summary
+  console.log('='.repeat(70));
+  if (aeOk) {
+    console.log('PIPELINE VALIDATION PASSED');
+    console.log(`  Queue:           ${QUEUE_NAME}`);
+    console.log(`  Analytics Engine: ${DATASET}`);
+    console.log(`  Feature Key:     ${TEST_FEATURE_KEY}`);
+  } else {
+    console.log('PIPELINE VALIDATION FAILED');
+    console.log('');
+    console.log('Troubleshooting:');
+    console.log('  1. Check if platform-usage worker is deployed');
+    console.log('  2. Verify queue consumer is processing: wrangler tail <your-usage-worker>');
+    console.log('  3. Check queue: wrangler queues list');
+    console.log('  4. Verify Analytics Engine binding in wrangler config');
+    process.exit(1);
+  }
+  console.log('='.repeat(70));
+}
+
+main().catch((error) => {
+  console.error('Unexpected error:', error);
+  process.exit(1);
+});