@littlebearapps/platform-admin-sdk 1.5.0 → 2.1.0

package/templates/shared/tests/unit/workers/budget-enforcement.test.ts

@@ -0,0 +1,214 @@
+/**
+ * Unit Tests for Budget Enforcement
+ *
+ * Covers:
+ * - Feature-level budget warnings at 70%/90% thresholds
+ * - Circuit breaker trip at 100%
+ * - Monthly budget tracking
+ * - Dedup via KV BUDGET_WARN: prefix
+ */
+
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
+import { createMockKV } from '../../helpers/mock-kv';
+import { MockD1Database } from '../../helpers/mock-d1';
+
+// ---------------------------------------------------------------------------
+// Module mocks — must be before imports that resolve these modules
+// ---------------------------------------------------------------------------
+
+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(),
+    }),
+  };
+});
+
+vi.mock('../../../workers/lib/circuit-breaker-middleware', () => ({
+  CB_STATUS: { CLOSED: 'active', WARNING: 'warning', OPEN: 'paused' },
+}));
+
+vi.mock('../../../workers/lib/platform-settings', () => ({
+  getPlatformSettings: vi.fn().mockResolvedValue({}),
+  getProjectSetting: vi.fn().mockResolvedValue(null),
+  DEFAULT_PLATFORM_SETTINGS: {},
+}));
+
+const mockFetch = vi.fn().mockResolvedValue(new Response('ok', { status: 200 }));
+
+import {
+  checkAndUpdateBudgetStatus,
+  checkMonthlyBudgets,
+} from '../../../workers/lib/usage/queue/budget-enforcement';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function createTestEnv(kvData: Record<string, string> = {}, slackUrl?: string) {
+  const db = new MockD1Database();
+  db.queueRunResult({ success: true });
+  db.queueRunResult({ success: true });
+
+  return {
+    env: {
+      PLATFORM_CACHE: createMockKV(kvData),
+      PLATFORM_DB: db,
+      SLACK_WEBHOOK_URL: slackUrl,
+      NOTIFICATIONS_API: undefined,
+      PLATFORM_TELEMETRY: undefined,
+      TELEMETRY_QUEUE: undefined,
+    } as unknown,
+    db,
+  };
+}
+
+// ===========================================================================
+// Section A: Feature-Level Budget Warnings
+// ===========================================================================
+
+describe('checkAndUpdateBudgetStatus', () => {
+  beforeEach(() => {
+    vi.stubGlobal('fetch', mockFetch);
+    mockFetch.mockClear();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('fires 70% warning when metric is between 70-89% of budget', async () => {
+    const { env } = createTestEnv(
+      {
+        'CONFIG:FEATURE:test:api:endpoint:BUDGET': JSON.stringify({
+          d1_rows_written: 100_000,
+        }),
+      },
+      'https://hooks.slack.com/test'
+    );
+
+    await checkAndUpdateBudgetStatus(
+      'test:api:endpoint',
+      { d1RowsWritten: 72_000 } as never,
+      env as never
+    );
+
+    const kv = (env as Record<string, unknown>).PLATFORM_CACHE as ReturnType<typeof createMockKV>;
+    expect(kv.put).toHaveBeenCalledWith(
+      'BUDGET_WARN:test:api:endpoint:d1RowsWritten:70',
+      '1',
+      { expirationTtl: 3600 }
+    );
+  });
+
+  it('fires 90% critical warning when metric >= 90% of budget', async () => {
+    const { env } = createTestEnv(
+      {
+        'CONFIG:FEATURE:test:api:endpoint:BUDGET': JSON.stringify({
+          d1_rows_written: 100_000,
+        }),
+      },
+      'https://hooks.slack.com/test'
+    );
+
+    await checkAndUpdateBudgetStatus(
+      'test:api:endpoint',
+      { d1RowsWritten: 92_000 } as never,
+      env as never
+    );
+
+    const kv = (env as Record<string, unknown>).PLATFORM_CACHE as ReturnType<typeof createMockKV>;
+    expect(kv.put).toHaveBeenCalledWith(
+      'BUDGET_WARN:test:api:endpoint:d1RowsWritten:90',
+      '1',
+      { expirationTtl: 3600 }
+    );
+  });
+
+  it('does not fire warning when metric is below 70%', async () => {
+    const { env } = createTestEnv(
+      {
+        'CONFIG:FEATURE:test:api:endpoint:BUDGET': JSON.stringify({
+          d1_rows_written: 100_000,
+        }),
+      },
+      'https://hooks.slack.com/test'
+    );
+
+    await checkAndUpdateBudgetStatus(
+      'test:api:endpoint',
+      { d1RowsWritten: 50_000 } as never,
+      env as never
+    );
+
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+
+  it('skips warning when dedup key already exists', async () => {
+    const { env } = createTestEnv(
+      {
+        'CONFIG:FEATURE:test:api:endpoint:BUDGET': JSON.stringify({
+          d1_rows_written: 100_000,
+        }),
+        'BUDGET_WARN:test:api:endpoint:d1RowsWritten:70': '1',
+      },
+      'https://hooks.slack.com/test'
+    );
+
+    await checkAndUpdateBudgetStatus(
+      'test:api:endpoint',
+      { d1RowsWritten: 75_000 } as never,
+      env as never
+    );
+
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+
+  it('does nothing when no budget config exists', async () => {
+    const { env } = createTestEnv({}, 'https://hooks.slack.com/test');
+
+    await checkAndUpdateBudgetStatus(
+      'test:api:endpoint',
+      { d1RowsWritten: 99_000 } as never,
+      env as never
+    );
+
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+});
+
+// ===========================================================================
+// Section B: Monthly Budget Tracking
+// ===========================================================================
+
+describe('checkMonthlyBudgets', () => {
+  beforeEach(() => {
+    vi.stubGlobal('fetch', mockFetch);
+    mockFetch.mockClear();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('queries daily_usage_rollups for current month', async () => {
+    const { env, db } = createTestEnv({});
+    db.queueAllResult([]);
+
+    await checkMonthlyBudgets(env as never);
+
+    expect(db.statements.some((s: string) => s.includes('daily_usage_rollups'))).toBe(true);
+  });
+
+  it('handles missing tables gracefully', async () => {
+    const { env } = createTestEnv({});
+
+    // Should not throw even with empty DB
+    await expect(checkMonthlyBudgets(env as never)).resolves.not.toThrow();
+  });
+});

package/templates/shared/vitest.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+    coverage: {
+      provider: 'v8',
+      include: ['workers/**/*.ts'],
+    },
+  },
+  resolve: {
+    alias: {
+      '@': './src',
+    },
+  },
+});

package/templates/standard/dashboard/src/components/health/CircuitBreakerEvents.tsx

@@ -0,0 +1,69 @@
+import { useState, useEffect } from 'react';
+import { EmptyState } from '../../components/ui/EmptyState';
+import { LoadingSkeleton } from '../../components/ui/LoadingSkeleton';
+
+interface CBEvent {
+  id: number;
+  feature_key: string;
+  event_type: string;
+  old_status: string;
+  new_status: string;
+  reason: string | null;
+  timestamp: string;
+}
+
+export function CircuitBreakerEvents() {
+  const [events, setEvents] = useState<CBEvent[]>([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    fetch('/api/usage/circuit-breakers')
+      .then(res => res.json())
+      .then((data: { events?: CBEvent[] }) => { setEvents(data.events ?? []); setLoading(false); })
+      .catch(() => setLoading(false));
+  }, []);
+
+  if (loading) return <LoadingSkeleton lines={3} />;
+
+  if (events.length === 0) {
+    return (
+      <div className="bg-white dark:bg-gray-800 rounded-lg border border-gray-200 dark:border-gray-700 p-4">
+        <h3 className="text-sm font-medium text-gray-500 dark:text-gray-400 uppercase tracking-wide mb-3">
+          CB Event History
+        </h3>
+        <EmptyState title="No events" description="No circuit breaker state changes recorded." />
+      </div>
+    );
+  }
+
+  return (
+    <div className="bg-white dark:bg-gray-800 rounded-lg border border-gray-200 dark:border-gray-700 p-4">
+      <h3 className="text-sm font-medium text-gray-500 dark:text-gray-400 uppercase tracking-wide mb-3">
+        CB Event History
+      </h3>
+      <div className="space-y-2">
+        {events.map(ev => (
+          <div key={ev.id} className="flex items-start gap-3 py-1.5 border-b border-gray-100 dark:border-gray-700 last:border-0">
+            <div className={`mt-1 w-2 h-2 rounded-full shrink-0 ${
+              ev.new_status === 'active' ? 'bg-green-500'
+                : ev.new_status === 'warning' ? 'bg-yellow-500'
+                : 'bg-red-500'
+            }`} />
+            <div className="min-w-0">
+              <p className="text-sm text-gray-900 dark:text-white">
+                <span className="font-medium">{ev.feature_key}</span>
+                {' '}{ev.old_status} &rarr; {ev.new_status}
+              </p>
+              {ev.reason && (
+                <p className="text-xs text-gray-500 dark:text-gray-400 truncate">{ev.reason}</p>
+              )}
+              <p className="text-xs text-gray-400 dark:text-gray-500">
+                {new Date(ev.timestamp).toLocaleString()}
+              </p>
+            </div>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}

package/templates/standard/dashboard/src/components/health/CircuitBreakerPanel.tsx

@@ -0,0 +1,97 @@
+import { useState, useEffect, useCallback } from 'react';
+import { LoadingSkeleton } from '../../components/ui/LoadingSkeleton';
+
+interface CircuitBreaker {
+  key: string;
+  feature: string;
+  status: string;
+  reason: string | null;
+  level: 'global' | 'project' | 'feature';
+}
+
+export function CircuitBreakerPanel() {
+  const [breakers, setBreakers] = useState<CircuitBreaker[]>([]);
+  const [loading, setLoading] = useState(true);
+
+  const loadBreakers = useCallback(() => {
+    fetch('/api/usage/circuit-breakers')
+      .then(res => res.json())
+      .then((data: { breakers: CircuitBreaker[] }) => {
+        const enriched = (data.breakers ?? []).map(cb => ({
+          ...cb,
+          level: (cb.key.includes(':global:') ? 'global'
+            : cb.key.includes(':project:') ? 'project'
+            : 'feature') as CircuitBreaker['level'],
+        }));
+        setBreakers(enriched);
+        setLoading(false);
+      })
+      .catch(() => setLoading(false));
+  }, []);
+
+  useEffect(() => { loadBreakers(); }, [loadBreakers]);
+
+  if (loading) return <LoadingSkeleton lines={4} />;
+
+  const grouped = {
+    global: breakers.filter(b => b.level === 'global'),
+    project: breakers.filter(b => b.level === 'project'),
+    feature: breakers.filter(b => b.level === 'feature'),
+  };
+
+  const statusBadge = (status: string) => {
+    const styles = status === 'active'
+      ? 'bg-green-100 text-green-700 dark:bg-green-900/30 dark:text-green-400'
+      : status === 'warning'
+        ? 'bg-yellow-100 text-yellow-700 dark:bg-yellow-900/30 dark:text-yellow-400'
+        : 'bg-red-100 text-red-700 dark:bg-red-900/30 dark:text-red-400';
+    return <span className={`text-xs px-2 py-0.5 rounded-full font-medium ${styles}`}>{status}</span>;
+  };
+
+  const renderGroup = (title: string, items: CircuitBreaker[]) => {
+    if (items.length === 0) return null;
+    return (
+      <div>
+        <h4 className="text-xs font-medium text-gray-500 dark:text-gray-400 uppercase tracking-wide mb-2">{title}</h4>
+        <div className="space-y-1.5">
+          {items.map(cb => (
+            <div key={cb.key} className="flex items-center justify-between py-1.5">
+              <div>
+                <span className="text-sm text-gray-900 dark:text-white">{cb.feature}</span>
+                {cb.reason && (
+                  <p className="text-xs text-gray-500 dark:text-gray-400">{cb.reason}</p>
+                )}
+              </div>
+              {statusBadge(cb.status)}
+            </div>
+          ))}
+        </div>
+      </div>
+    );
+  };
+
+  return (
+    <div className="bg-white dark:bg-gray-800 rounded-lg border border-gray-200 dark:border-gray-700 p-4">
+      <div className="flex items-center justify-between mb-4">
+        <h3 className="text-sm font-medium text-gray-500 dark:text-gray-400 uppercase tracking-wide">
+          Circuit Breakers
+        </h3>
+        <button
+          onClick={loadBreakers}
+          className="text-xs text-blue-600 dark:text-blue-400 hover:underline"
+        >
+          Refresh
+        </button>
+      </div>
+      {breakers.length === 0 ? (
+        <p className="text-sm text-gray-500 dark:text-gray-400">No circuit breakers configured.</p>
+      ) : (
+        <div className="space-y-4">
+          {renderGroup('Global', grouped.global)}
+          {renderGroup('Project', grouped.project)}
+          {renderGroup('Feature', grouped.feature)}
+        </div>
+      )}
+    </div>
+  );
+}

package/templates/standard/dashboard/src/components/health/index.ts

@@ -1,2 +1,4 @@
 export { HealthTabs } from './HealthTabs';
 export { DlqStatusCard } from './DlqStatusCard';
+export { CircuitBreakerPanel } from './CircuitBreakerPanel';
+export { CircuitBreakerEvents } from './CircuitBreakerEvents';