@littlebearapps/platform-admin-sdk 1.4.2 → 2.0.0

package/templates/shared/dashboard/src/pages/api/user/identity.ts

@@ -0,0 +1,11 @@
+import type { APIRoute } from 'astro';
+
+export const GET: APIRoute = async ({ request }) => {
+  // Extract identity from CF Access JWT headers
+  const email = request.headers.get('cf-access-authenticated-user-email') ?? 'unknown';
+  const name = email.split('@')[0] ?? 'User';
+
+  return new Response(JSON.stringify({ email, name }), {
+    headers: { 'Content-Type': 'application/json', 'Cache-Control': 'max-age=3600' },
+  });
+};

package/templates/shared/dashboard/src/pages/dashboard.astro

@@ -0,0 +1,11 @@
+---
+import DashboardLayout from '../layouts/DashboardLayout.astro';
+import { MissionControl } from '../components/overview/MissionControl';
+---
+
+<DashboardLayout title="Overview">
+  <div class="max-w-7xl mx-auto">
+    <h2 class="text-xl font-bold text-gray-900 dark:text-white mb-4">Mission Control</h2>
+    <MissionControl client:load />
+  </div>
+</DashboardLayout>

package/templates/shared/dashboard/src/pages/index.astro

@@ -0,0 +1,3 @@
+---
+return Astro.redirect('/dashboard');
+---

package/templates/shared/dashboard/src/pages/resources.astro

@@ -0,0 +1,11 @@
+---
+import DashboardLayout from '../layouts/DashboardLayout.astro';
+import { ResourceTabs } from '../components/resources/ResourceTabs';
+---
+
+<DashboardLayout title="Resources">
+  <div class="max-w-7xl mx-auto">
+    <h2 class="text-xl font-bold text-gray-900 dark:text-white mb-4">Resources</h2>
+    <ResourceTabs client:load />
+  </div>
+</DashboardLayout>

package/templates/shared/dashboard/src/pages/settings/index.astro

@@ -0,0 +1,28 @@
+---
+import DashboardLayout from '../../layouts/DashboardLayout.astro';
+import { SettingsCard } from '../../components/settings/SettingsCard';
+---
+
+<DashboardLayout title="Settings">
+  <div class="max-w-3xl mx-auto space-y-4">
+    <h2 class="text-xl font-bold text-gray-900 dark:text-white mb-4">Settings</h2>
+    <SettingsCard
+      client:load
+      label="Monthly Budget"
+      description="Soft budget limit for cost alerts. Configure in budgets.yaml."
+      value="$100"
+    />
+    <SettingsCard
+      client:load
+      label="Circuit Breakers"
+      description="Automatic feature pause when budgets are exceeded."
+      value="Enabled"
+    />
+    <SettingsCard
+      client:load
+      label="Data Collection"
+      description="Hourly Cloudflare GraphQL snapshots and SDK telemetry."
+      value="Active"
+    />
+  </div>
+</DashboardLayout>

package/templates/shared/dashboard/src/pages/settings/notifications.astro

@@ -0,0 +1,34 @@
+---
+import DashboardLayout from '../../layouts/DashboardLayout.astro';
+import { SettingsCard } from '../../components/settings/SettingsCard';
+---
+
+<DashboardLayout title="Notification Settings">
+  <div class="max-w-3xl mx-auto space-y-4">
+    <h2 class="text-xl font-bold text-gray-900 dark:text-white mb-4">Notification Settings</h2>
+    <SettingsCard
+      client:load
+      label="Slack Alerts"
+      description="Send alerts to a Slack channel via webhook URL."
+      value="Not configured"
+    />
+    <SettingsCard
+      client:load
+      label="Email Alerts"
+      description="Send critical alerts via email."
+      value="Disabled"
+    />
+    <SettingsCard
+      client:load
+      label="Budget Warnings"
+      description="Notify at 70% and 90% budget thresholds."
+      value="Enabled"
+    />
+    <SettingsCard
+      client:load
+      label="Circuit Breaker Trips"
+      description="Immediate notification when a circuit breaker trips."
+      value="Enabled"
+    />
+  </div>
+</DashboardLayout>

package/templates/shared/dashboard/src/pages/settings/thresholds.astro

@@ -0,0 +1,39 @@
+---
+import DashboardLayout from '../../layouts/DashboardLayout.astro';
+import { SettingsCard } from '../../components/settings/SettingsCard';
+---
+
+<DashboardLayout title="Alert Thresholds">
+  <div class="max-w-3xl mx-auto space-y-4">
+    <h2 class="text-xl font-bold text-gray-900 dark:text-white mb-4">Alert Thresholds</h2>
+    <p class="text-sm text-gray-500 dark:text-gray-400 mb-4">
+      Configure when budget warnings fire. These values are defined in
+      <code class="text-xs bg-gray-100 dark:bg-gray-700 px-1 py-0.5 rounded">budgets.yaml</code>
+      and synced via <code class="text-xs bg-gray-100 dark:bg-gray-700 px-1 py-0.5 rounded">npm run sync:config</code>.
+    </p>
+    <SettingsCard
+      client:load
+      label="Warning Threshold"
+      description="Alert when feature budget usage reaches this percentage."
+      value="70%"
+    />
+    <SettingsCard
+      client:load
+      label="Critical Threshold"
+      description="Escalate alert severity at this percentage."
+      value="90%"
+    />
+    <SettingsCard
+      client:load
+      label="Circuit Breaker Trip"
+      description="Automatically pause feature at this percentage."
+      value="100%"
+    />
+    <SettingsCard
+      client:load
+      label="Anomaly Sensitivity"
+      description="Deviation percentage to flag as anomaly."
+      value="200%"
+    />
+  </div>
+</DashboardLayout>

package/templates/shared/dashboard/src/pages/settings/usage.astro

@@ -0,0 +1,28 @@
+---
+import DashboardLayout from '../../layouts/DashboardLayout.astro';
+import { SettingsCard } from '../../components/settings/SettingsCard';
+---
+
+<DashboardLayout title="Usage Settings">
+  <div class="max-w-3xl mx-auto space-y-4">
+    <h2 class="text-xl font-bold text-gray-900 dark:text-white mb-4">Usage Display Settings</h2>
+    <SettingsCard
+      client:load
+      label="Default Period"
+      description="Default time range for usage charts."
+      value="24 hours"
+    />
+    <SettingsCard
+      client:load
+      label="Cost Display"
+      description="Show costs as net (after allowances) or gross."
+      value="Net"
+    />
+    <SettingsCard
+      client:load
+      label="Data Refresh"
+      description="How often dashboard polls for new data."
+      value="60 seconds"
+    />
+  </div>
+</DashboardLayout>

package/templates/shared/dashboard/src/styles/global.css

@@ -0,0 +1,29 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer components {
+  .nav-link {
+    @apply text-gray-700 transition-colors hover:text-blue-600 dark:text-gray-300 dark:hover:text-blue-400 font-medium;
+  }
+
+  .metric-card {
+    @apply rounded-lg bg-white p-6 shadow dark:bg-gray-800;
+  }
+
+  .metric-title {
+    @apply text-sm font-medium uppercase tracking-wide text-gray-600 dark:text-gray-400;
+  }
+
+  .metric-value {
+    @apply mt-2 text-3xl font-bold text-gray-900 dark:text-white;
+  }
+
+  .alert-critical {
+    @apply rounded border-l-4 border-red-500 bg-red-50 p-4 dark:bg-red-900/20;
+  }
+
+  .alert-warning {
+    @apply rounded border-l-4 border-yellow-500 bg-yellow-50 p-4 dark:bg-yellow-900/20;
+  }
+}

package/templates/shared/dashboard/tailwind.config.mjs

@@ -0,0 +1,9 @@
+/** @type {import('tailwindcss').Config} */
+export default {
+  content: ['./src/**/*.{astro,html,js,jsx,ts,tsx}'],
+  darkMode: 'class',
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+};

package/templates/shared/dashboard/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  }
+}

package/templates/shared/dashboard/wrangler.json.hbs

@@ -0,0 +1,47 @@
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "{{projectSlug}}-dashboard",
+  "pages_build_output_dir": "dist",
+  "compatibility_date": "2026-01-01",
+  "compatibility_flags": ["nodejs_compat"],
+  "upload_source_maps": true,
+  "d1_databases": [
+    {
+      "binding": "PLATFORM_DB",
+      "database_name": "YOUR_DATABASE_NAME",
+      "database_id": "YOUR_DATABASE_ID"
+    }
+  ],
+  "kv_namespaces": [
+    {
+      "binding": "PLATFORM_CACHE",
+      "id": "YOUR_PLATFORM_CACHE_KV_ID"
+    }
+  ],
+  "services": [
+    {
+      "binding": "USAGE_API",
+      "service": "{{projectSlug}}-usage"
+    }{{#if isStandard}},
+    {
+      "binding": "ERROR_COLLECTOR_API",
+      "service": "{{projectSlug}}-error-collector"
+    }{{/if}}{{#if isFull}},
+    {
+      "binding": "PATTERN_DISCOVERY_API",
+      "service": "{{projectSlug}}-pattern-discovery"
+    },
+    {
+      "binding": "NOTIFICATIONS_API",
+      "service": "{{projectSlug}}-notifications"
+    },
+    {
+      "binding": "SETTINGS_API",
+      "service": "{{projectSlug}}-settings"
+    },
+    {
+      "binding": "SEARCH_API",
+      "service": "{{projectSlug}}-search"
+    }{{/if}}
+  ]
+}

package/templates/shared/docs/architecture.md

@@ -0,0 +1,89 @@
+# Architecture Overview
+
+## System Design
+
+The platform follows a hub-and-spoke model:
+
+```
+Producer Projects (Scout, Brand Copilot, etc.)
+    │
+    ▼ SDK telemetry via Queue
+┌────────────────────────────┐
+│  platform-usage worker     │ ← Central data warehouse
+│  (cron + queue consumer)   │
+└────────────┬───────────────┘
+             │
+    ┌────────┼────────────┐
+    ▼        ▼            ▼
+  D1 DB    KV Cache   Analytics Engine
+    │        │
+    ▼        ▼
+  Dashboard (Astro SSR + CF Pages)
+```
+
+## Data Flow
+
+### Collection Pipeline
+
+1. **SDK Telemetry**: Producer projects send telemetry via `platform-telemetry` queue
+2. **External APIs**: Cron jobs query Cloudflare GraphQL, GitHub, Stripe, AI providers
+3. **Queue Consumer**: Processes messages, enforces budgets, writes to D1 + Analytics Engine
+4. **Failed messages** route to `platform-telemetry-dlq` for manual inspection
+
+### Storage Tiers
+
+| Storage | Use Case | Cost Profile |
+|---------|----------|--------------|
+| D1 | Historical data, rollups, settings | Writes: $1/M rows |
+| KV | Circuit breakers, budgets, cache | Reads: $0.50/M, Writes: $5/M |
+| Analytics Engine | High-cardinality metrics | Free tier generous |
+
+### Budget Enforcement
+
+```
+Telemetry arrives → Check feature budget → Check project budget → Check global budget
+    │                    │                      │                      │
+    │               70% → Slack warn       90% → Slack critical    100% → CB trip
+    │                                                                     │
+    └─────────────────────────────────────────────────────────────────────┘
+                              Write to D1 + Analytics Engine
+```
+
+## Worker Topology
+
+### Minimal Tier
+- **platform-usage**: Data warehouse, cron scheduler, queue consumer
+
+### Standard Tier (adds)
+- **error-collector**: Tail worker → error fingerprinting → GitHub issues
+- **platform-sentinel**: Gap detection, cost monitoring
+- **platform-mapper**: Infrastructure discovery, attribution
+
+### Full Tier (adds)
+- **pattern-discovery**: AI-assisted transient error pattern detection
+- **platform-alert-router**: Unified alert normalisation
+- **platform-notifications**: In-app notification API
+- **platform-search**: Full-text search (FTS5)
+- **platform-settings**: Settings management API
+- **platform-auditor**: SDK integration auditor + AI Judge
+
+## Dashboard Architecture
+
+Astro SSR deployed on Cloudflare Pages with:
+- Service bindings to backend workers
+- D1/KV direct bindings for read-heavy pages
+- CF Access for authentication
+- React islands for interactive components
+
+## Configuration
+
+All configuration lives in Git and syncs to runtime:
+
+```
+platform/config/
+├── services.yaml     ← Project registry, feature IDs
+├── budgets.yaml      ← Limits, thresholds, CB config
+└── observability.yaml ← Monitoring standards
+```
+
+Sync via: `npm run sync:config` → D1 tables + KV keys

package/templates/shared/docs/post-deploy-runbook.md

@@ -0,0 +1,126 @@
+# Post-Deploy Runbook
+
+## After Initial Scaffold
+
+### 1. Configure Cloudflare Resources
+
+```bash
+# Create D1 database
+direnv exec . wrangler d1 create platform-metrics
+
+# Update database IDs in all wrangler.*.jsonc files
+# (use the ID returned from the create command)
+
+# Run migrations
+direnv exec . wrangler d1 migrations apply platform-metrics --remote
+
+# Create KV namespace
+direnv exec . wrangler kv namespace create PLATFORM_CACHE
+# Update KV namespace IDs in wrangler configs
+
+# Create telemetry queue
+direnv exec . wrangler queues create platform-telemetry
+direnv exec . wrangler queues create platform-telemetry-dlq
+```
+
+### 2. Sync Configuration
+
+```bash
+# Push services.yaml + budgets.yaml to D1/KV
+npm run sync:config
+```
+
+### 3. Deploy Workers
+
+```bash
+# Deploy in order: usage first (it's the foundation)
+npm run deploy:usage
+
+# Standard tier: error collector + sentinel
+direnv exec . wrangler deploy -c wrangler.*-error-collector.jsonc
+direnv exec . wrangler deploy -c wrangler.*-sentinel.jsonc
+
+# Full tier: remaining workers
+direnv exec . wrangler deploy -c wrangler.*-pattern-discovery.jsonc
+# ... etc
+```
+
+### 4. Deploy Dashboard
+
+```bash
+cd dashboard
+npm install && npm run build
+direnv exec . npx wrangler pages deploy dist
+```
+
+### 5. Verify
+
+```bash
+# Check worker is responding
+direnv exec . wrangler tail {worker-name} --format json
+
+# Run validation
+npm run validate:pipeline
+npm run validate:controls
+
+# Check dashboard loads
+# https://your-dashboard-url.pages.dev
+```
+
+## After Code Changes
+
+### Worker Changes
+
+1. Run tests: `npm test`
+2. Run typecheck: `npm run typecheck`
+3. Check D1 migrations: any new migrations need `wrangler d1 migrations apply`
+4. Deploy affected worker(s)
+5. Watch logs for 30 seconds: `direnv exec . wrangler tail {worker} --format json`
+
+### Budget/Config Changes
+
+1. Run `npm run validate:controls --strict`
+2. Run `npm run sync:config`
+3. Verify KV keys updated correctly
+
+### Dashboard Changes
+
+1. Build locally: `cd dashboard && npm run build`
+2. Deploy: `direnv exec . npx wrangler pages deploy dist`
+3. Verify pages load, API routes return data
+
+## Backfill After Data Gaps
+
+If usage collection missed data (e.g., worker was down):
+
+```bash
+# 1. Backfill hourly data from Cloudflare GraphQL
+npm run backfill -- --start 2026-01-01 --end 2026-01-31
+
+# 2. Roll up to daily
+npm run backfill:daily -- --start 2026-01-01 --end 2026-01-31
+
+# 3. Roll up to monthly
+npm run backfill:monthly -- --start 2026-01 --end 2026-01
+
+# Always dry-run first:
+npm run backfill:daily -- --dry-run --start 2026-01-01 --end 2026-01-31
+```
+
+## Emergency: Circuit Breaker Trip
+
+If a circuit breaker trips unexpectedly:
+
+```bash
+# 1. Check what tripped
+# Dashboard → Circuit Breakers page
+
+# 2. Investigate root cause
+direnv exec . wrangler tail {worker} --format json
+
+# 3. If safe to reset
+npm run reset-cb
+
+# 4. Monitor after reset
+direnv exec . wrangler tail {worker} --format json
+```

package/templates/shared/docs/troubleshooting.md

@@ -0,0 +1,91 @@
+# Troubleshooting Guide
+
+## Common Issues
+
+### Workers Not Deploying
+
+**Symptom**: `wrangler deploy` fails or worker doesn't respond.
+
+**Check**:
+1. Verify wrangler config references correct `main` entry point
+2. Check `compatibility_date` is recent
+3. Ensure all D1 bindings use correct database IDs
+4. Run `direnv exec . wrangler whoami` to verify credentials
+
+### D1 Write Errors
+
+**Symptom**: `D1_ERROR: too many requests` or budget circuit breaker trips.
+
+**Fix**:
+1. Check `budgets.yaml` — limits may be too low for current usage
+2. Run `npm run validate:controls` to verify budget configuration
+3. Check circuit breaker state: `cb:global`, `cb:project:{name}`, `cb:feature:{id}`
+4. Reset with `npm run reset-cb` if needed
+
+### Queue Messages Stuck in DLQ
+
+**Symptom**: DLQ depth increasing, messages not processing.
+
+**Check**:
+1. View DLQ status in dashboard Health tab
+2. Check queue consumer logs: `direnv exec . wrangler tail {worker-name}`
+3. Common cause: malformed telemetry envelopes — validate with `npm run validate:schemas`
+4. Retry DLQ messages via dashboard or API
+
+### Dashboard Not Loading Data
+
+**Symptom**: Dashboard shows empty states or loading spinners.
+
+**Check**:
+1. Verify D1 database has data: `direnv exec . wrangler d1 execute platform-metrics --command "SELECT COUNT(*) FROM hourly_usage_snapshots"`
+2. Check KV cache: service registry may be stale
+3. Run `npm run sync:config` to refresh D1/KV from YAML
+4. Check CF Access — dashboard requires authentication
+
+### Budget Warnings Not Firing
+
+**Symptom**: Usage exceeds thresholds but no Slack alerts.
+
+**Check**:
+1. Verify `SLACK_WEBHOOK_URL` is set in wrangler config
+2. Check KV dedup keys: `BUDGET_WARN:{feature}` (1hr TTL)
+3. Ensure `budgets.yaml` has correct feature keys matching `services.yaml`
+4. Run `npm run validate:controls --strict` for cross-reference check
+
+### Backfill Scripts Failing
+
+**Symptom**: `backfill:daily` or `backfill:monthly` errors.
+
+**Check**:
+1. Required env vars: `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID`, `D1_DATABASE_ID`
+2. API token needs D1:Write permissions
+3. Run with `--dry-run` first to verify date ranges
+4. Rate limit: scripts include 200ms delay between queries
+
+## Diagnostic Commands
+
+```bash
+# Check worker health
+direnv exec . wrangler tail {worker-name} --format json
+
+# Verify D1 schema
+direnv exec . wrangler d1 migrations list platform-metrics --remote
+
+# Test config sync
+npm run sync:config -- --dry-run
+
+# Validate all controls
+npm run validate:controls --strict
+
+# Run schema validation
+npm run validate:schemas
+
+# Check pipeline health
+npm run validate:pipeline
+```
+
+## Getting Help
+
+1. Check the [KV Key Patterns](./kv-key-patterns.md) doc for key prefix reference
+2. Review circuit breaker states in the dashboard Circuit Breakers page
+3. Run `npm test` to verify worker logic locally

package/templates/shared/package.json.hbs

@@ -6,7 +6,20 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "sync:config": "npx tsx scripts/sync-config.ts",
-    "deploy:usage": "wrangler deploy -c wrangler.{{projectSlug}}-usage.jsonc"
+    "deploy:usage": "wrangler deploy -c wrangler.{{projectSlug}}-usage.jsonc",
+    "backfill": "npx tsx scripts/ops/backfill-cloudflare-hourly.ts",
+    "backfill:daily": "npx tsx scripts/ops/backfill-cloudflare-daily.ts",
+    "backfill:monthly": "npx tsx scripts/ops/backfill-monthly-rollups.ts",
+    "validate:controls": "node scripts/ops/validate-controls.js",
+    "reset-cb": "npx tsx scripts/ops/reset-budget-state.ts",
+    "verify": "npx tsx scripts/ops/verify-account-completeness.ts",
+    "validate:pipeline": "npx tsx scripts/ops/validate-pipeline.ts",
+    "validate:schemas": "node scripts/validate-schemas.js",
+    "test": "vitest run",
+    "deploy:auditor": "wrangler deploy -c wrangler.{{projectSlug}}-auditor.jsonc",
+    "deploy:mapper": "wrangler deploy -c wrangler.{{projectSlug}}-mapper.jsonc",
+    "deploy:test-client": "wrangler deploy -c wrangler.{{projectSlug}}-sdk-test-client.jsonc",
+    "discover:datasets": "npx tsx scripts/ops/discover-graphql-datasets.ts"
   },
   "dependencies": {
     "@littlebearapps/platform-consumer-sdk": "^{{sdkVersion}}",
@@ -14,8 +27,11 @@
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20250214.0",
+    "ajv": "^8.17.0",
+    "ajv-formats": "^3.0.0",
     "tsx": "^4.19.0",
     "typescript": "^5.7.3",
+    "vitest": "^3.0.5",
     "wrangler": "^3.100.0"
   }
 }