@littlebearapps/platform-admin-sdk 2.0.0 → 2.1.0

package/templates/standard/dashboard/src/components/usage/unified/FeatureBudgets.tsx

@@ -0,0 +1,472 @@
+/**
+ * FeatureBudgets Component (React)
+ *
+ * React version of the Feature Budgets table for the unified dashboard.
+ * Displays feature-level usage metrics and circuit breaker status.
+ */
+
+import { useState, useEffect, useCallback, useRef } from 'react';
+import { RefreshCw, AlertTriangle, CheckCircle, XCircle, Clock } from 'lucide-react';
+import { clsx } from 'clsx';
+import { Sparkline } from './Sparkline';
+import { fetchWithDedup } from '../../../lib/usage/fetchWithDedup';
+
+interface FeatureMetrics {
+  d1Writes: number;
+  d1Reads: number;
+  kvReads: number;
+  kvWrites: number;
+  doRequests: number;
+  doGbSeconds: number;
+  r2ClassA: number;
+  r2ClassB: number;
+  aiNeurons: number;
+  queueMessages: number;
+  requests: number;
+  cpuMs: number;
+}
+
+interface FeatureCircuitBreaker {
+  enabled: boolean;
+  disabledReason?: string;
+  disabledAt?: string;
+  autoResetAt?: string;
+}
+
+interface FeatureData {
+  featureKey: string;
+  project: string;
+  category: string;
+  feature: string;
+  metrics: FeatureMetrics;
+  circuitBreaker: FeatureCircuitBreaker;
+  lastHeartbeat?: string;
+  healthStatus?: string;
+}
+
+interface HistoryDataPoint {
+  date: string;
+  requests: number;
+  d1Writes: number;
+  kvReads: number;
+  kvWrites: number;
+}
+
+type HistoryByFeature = Record<string, HistoryDataPoint[]>;
+
+interface Budgets {
+  _defaults: Record<string, { hourly: number; daily?: number }>;
+  features: Record<string, Record<string, { hourly: number; daily?: number }>>;
+}
+
+function formatNumber(n: number): string {
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+  if (n >= 1_000) return `${(n / 1_000).toFixed(1)}K`;
+  return n.toFixed(0);
+}
+
+function getBudgetPct(value: number, limit: number): number {
+  if (limit <= 0) return 0;
+  return (value / limit) * 100;
+}
+
+function getPctClass(pct: number): string {
+  if (pct >= 90) return 'text-rose-400';
+  if (pct >= 70) return 'text-amber-400';
+  return 'text-gray-500 dark:text-slate-500';
+}
+
+/**
+ * Heartbeat Indicator - shows last seen timestamp with freshness status
+ */
+function HeartbeatIndicator({ lastHeartbeat }: { lastHeartbeat?: string }) {
+  if (!lastHeartbeat) {
+    return (
+      <div className="flex items-center justify-center gap-1" title="No heartbeat received">
+        <Clock className="w-3 h-3 text-gray-400 dark:text-slate-600" />
+        <span className="text-[10px] font-mono text-gray-400 dark:text-slate-600">—</span>
+      </div>
+    );
+  }
+
+  const lastSeenDate = new Date(lastHeartbeat);
+  const now = new Date();
+  const diffMs = now.getTime() - lastSeenDate.getTime();
+  const diffMins = Math.floor(diffMs / 60000);
+  const diffHours = Math.floor(diffMs / 3600000);
+
+  // Determine freshness: < 10min = fresh, < 1hr = recent, < 24hr = stale, > 24hr = dead
+  let status: 'fresh' | 'recent' | 'stale' | 'dead';
+  let label: string;
+
+  if (diffMins < 10) {
+    status = 'fresh';
+    label = diffMins <= 1 ? 'now' : `${diffMins}m`;
+  } else if (diffMins < 60) {
+    status = 'recent';
+    label = `${diffMins}m`;
+  } else if (diffHours < 24) {
+    status = 'stale';
+    label = `${diffHours}h`;
+  } else {
+    status = 'dead';
+    const diffDays = Math.floor(diffHours / 24);
+    label = `${diffDays}d`;
+  }
+
+  const statusColors = {
+    fresh: 'text-emerald-400',
+    recent: 'text-amber-400',
+    stale: 'text-orange-400',
+    dead: 'text-rose-400',
+  };
+
+  const dotColors = {
+    fresh: 'bg-emerald-500',
+    recent: 'bg-amber-500',
+    stale: 'bg-orange-500',
+    dead: 'bg-rose-500',
+  };
+
+  return (
+    <div
+      className="flex items-center justify-center gap-1"
+      title={`Last heartbeat: ${lastSeenDate.toLocaleString()}`}
+    >
+      <span className={clsx('w-1.5 h-1.5 rounded-full', dotColors[status])} />
+      <span className={clsx('text-[10px] font-mono', statusColors[status])}>{label}</span>
+    </div>
+  );
+}
+
+export function FeatureBudgets() {
+  const [features, setFeatures] = useState<FeatureData[]>([]);
+  const [history, setHistory] = useState<HistoryByFeature>({});
+  const [budgets, setBudgets] = useState<Budgets | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [lastUpdated, setLastUpdated] = useState<Date | null>(null);
+
+  // Refs to track state for conditional fetching without creating dependency cycles
+  const budgetsRef = useRef(budgets);
+  const historyRef = useRef(history);
+
+  // Keep refs in sync with state
+  useEffect(() => {
+    budgetsRef.current = budgets;
+  }, [budgets]);
+
+  useEffect(() => {
+    historyRef.current = history;
+  }, [history]);
+
+  const fetchData = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+
+    try {
+      // Use refs for conditional checks to avoid dependency cycle
+      const shouldFetchBudgets = !budgetsRef.current;
+      const shouldFetchHistory = Object.keys(historyRef.current).length === 0;
+
+      // Fetch features, budgets, and history in parallel with deduplication
+      const [featuresData, budgetsData, historyData] = await Promise.all([
+        fetchWithDedup<{ success: boolean; features?: FeatureData[]; error?: string }>(
+          '/api/usage/features'
+        ),
+        shouldFetchBudgets
+          ? fetchWithDedup<{ success: boolean; budgets?: Budgets }>(
+              '/api/usage/features/budgets',
+              {},
+              30000 // Cache budgets for 30s (they don't change often)
+            )
+          : Promise.resolve(null),
+        shouldFetchHistory
+          ? fetchWithDedup<{ success: boolean; features?: HistoryByFeature }>(
+              '/api/usage/features/history?days=7',
+              {},
+              30000 // Cache history for 30s
+            )
+          : Promise.resolve(null),
+      ]);
+
+      if (budgetsData?.success) {
+        setBudgets(budgetsData.budgets || null);
+      }
+
+      if (historyData?.success && historyData.features) {
+        setHistory(historyData.features);
+      }
+
+      if (featuresData.success) {
+        setFeatures(featuresData.features || []);
+        setLastUpdated(new Date());
+      } else {
+        throw new Error(featuresData.error || 'Failed to fetch features');
+      }
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Unknown error');
+    } finally {
+      setLoading(false);
+    }
+  }, []); // No state dependencies - uses refs for conditional checks
+
+  useEffect(() => {
+    fetchData();
+    // Refresh every 60 seconds
+    const interval = setInterval(fetchData, 60_000);
+    return () => clearInterval(interval);
+  }, [fetchData]);
+
+  const handleToggle = async (featureKey: string, currentEnabled: boolean) => {
+    const action = currentEnabled ? 'disable' : 'enable';
+    const confirmed = window.confirm(
+      `${action.charAt(0).toUpperCase() + action.slice(1)} feature "${featureKey}"?`
+    );
+    if (!confirmed) return;
+
+    try {
+      const response = await fetch('/api/usage/features/circuit-breakers', {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          featureKey,
+          enabled: !currentEnabled,
+        }),
+        credentials: 'include',
+      });
+
+      const result = await response.json();
+
+      if (result.success) {
+        await fetchData();
+      } else {
+        window.alert(`Failed to ${action}: ${result.error || 'Unknown error'}`);
+      }
+    } catch (_err) {
+      window.alert(`Failed to ${action} feature`);
+    }
+  };
+
+  const defaults = budgets?._defaults ?? {
+    d1Writes: { hourly: 10000 },
+    kvReads: { hourly: 50000 },
+    kvWrites: { hourly: 5000 },
+  };
+
+  if (loading && features.length === 0) {
+    return (
+      <div className="bg-gray-50 dark:bg-slate-900/50 border border-gray-200 dark:border-slate-800 rounded-sm p-6">
+        <div className="flex items-center justify-center gap-2 text-gray-600 dark:text-slate-400">
+          <RefreshCw className="w-4 h-4 animate-spin" />
+          <span className="text-sm">Loading feature budgets...</span>
+        </div>
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div className="bg-gray-50 dark:bg-slate-900/50 border border-gray-200 dark:border-slate-800 rounded-sm p-6">
+        <div className="flex items-center gap-2 text-rose-400">
+          <AlertTriangle className="w-4 h-4" />
+          <span className="text-sm">{error}</span>
+        </div>
+        <button
+          type="button"
+          onClick={fetchData}
+          className="mt-3 px-3 py-1.5 bg-gray-100 dark:bg-slate-800 hover:bg-gray-200 dark:hover:bg-slate-700 text-gray-700 dark:text-slate-300 text-xs font-mono rounded-sm"
+        >
+          Retry
+        </button>
+      </div>
+    );
+  }
+
+  return (
+    <div className="bg-gray-50 dark:bg-slate-900/50 border border-gray-200 dark:border-slate-800 rounded-sm">
+      {/* Header */}
+      <div className="flex items-center justify-between p-4 border-b border-gray-200 dark:border-slate-800">
+        <div className="flex items-center gap-3">
+          <h3 className="text-sm font-semibold text-gray-900 dark:text-slate-200">
+            Feature Budgets
+          </h3>
+          <span className="text-xs text-gray-500 dark:text-slate-500 bg-gray-100 dark:bg-slate-800 px-2 py-0.5 rounded">
+            {features.length} feature{features.length !== 1 ? 's' : ''}
+          </span>
+        </div>
+        <button
+          type="button"
+          onClick={fetchData}
+          disabled={loading}
+          className="p-1.5 hover:bg-gray-100 dark:hover:bg-slate-800 rounded-sm transition-colors"
+          title="Refresh"
+        >
+          <RefreshCw
+            className={clsx('w-4 h-4 text-gray-600 dark:text-slate-400', loading && 'animate-spin')}
+          />
+        </button>
+      </div>
+
+      {/* Empty State */}
+      {features.length === 0 && (
+        <div className="p-8 text-center">
+          <div className="text-3xl mb-3">📊</div>
+          <h4 className="text-sm font-semibold text-gray-900 dark:text-slate-200 mb-1">
+            No feature telemetry yet
+          </h4>
+          <p className="text-xs text-gray-500 dark:text-slate-500 max-w-xs mx-auto">
+            Feature usage data will appear once projects start reporting telemetry using the{' '}
+            <code className="bg-gray-100 dark:bg-slate-800 px-1 py-0.5 rounded text-xs">
+              withFeatureBudget()
+            </code>{' '}
+            wrapper.
+          </p>
+        </div>
+      )}
+
+      {/* Table */}
+      {features.length > 0 && (
+        <div className="overflow-x-auto">
+          <table className="w-full text-xs">
+            <thead>
+              <tr className="border-b border-gray-200 dark:border-slate-800">
+                <th className="text-left px-4 py-2 text-gray-500 dark:text-slate-500 font-semibold uppercase tracking-wider">
+                  Feature
+                </th>
+                <th className="text-left px-4 py-2 text-gray-500 dark:text-slate-500 font-semibold uppercase tracking-wider">
+                  Project
+                </th>
+                <th className="text-right px-4 py-2 text-gray-500 dark:text-slate-500 font-semibold uppercase tracking-wider">
+                  D1 Writes
+                </th>
+                <th className="text-right px-4 py-2 text-gray-500 dark:text-slate-500 font-semibold uppercase tracking-wider">
+                  KV Ops
+                </th>
+                <th className="text-right px-4 py-2 text-gray-500 dark:text-slate-500 font-semibold uppercase tracking-wider">
+                  Requests
+                </th>
+                <th className="text-center px-4 py-2 text-gray-500 dark:text-slate-500 font-semibold uppercase tracking-wider">
+                  7d Trend
+                </th>
+                <th className="text-center px-4 py-2 text-gray-500 dark:text-slate-500 font-semibold uppercase tracking-wider">
+                  Heartbeat
+                </th>
+                <th className="text-center px-4 py-2 text-gray-500 dark:text-slate-500 font-semibold uppercase tracking-wider">
+                  Status
+                </th>
+                <th className="text-center px-4 py-2 text-gray-500 dark:text-slate-500 font-semibold uppercase tracking-wider">
+                  Action
+                </th>
+              </tr>
+            </thead>
+            <tbody>
+              {features.map((f) => {
+                const d1WritesPct = getBudgetPct(
+                  f.metrics.d1Writes,
+                  defaults.d1Writes?.hourly ?? 10000
+                );
+                const kvOps = f.metrics.kvReads + f.metrics.kvWrites;
+                const kvLimit =
+                  (defaults.kvReads?.hourly ?? 50000) + (defaults.kvWrites?.hourly ?? 5000);
+                const kvOpsPct = getBudgetPct(kvOps, kvLimit);
+                const historyData = history[f.featureKey] || [];
+                const trendData = historyData.map(
+                  (d) => d.requests || d.d1Writes + d.kvReads + d.kvWrites
+                );
+
+                return (
+                  <tr
+                    key={f.featureKey}
+                    className="border-b border-gray-200/50 dark:border-slate-800/50 hover:bg-gray-100/30 dark:hover:bg-slate-800/30"
+                  >
+                    <td className="px-4 py-3">
+                      <div>
+                        <span className="text-gray-800 dark:text-slate-200 font-medium">
+                          {f.feature}
+                        </span>
+                        <span className="block text-gray-500 dark:text-slate-500 text-[10px]">
+                          {f.category}
+                        </span>
+                      </div>
+                    </td>
+                    <td className="px-4 py-3 text-gray-600 dark:text-slate-400">{f.project}</td>
+                    <td className="px-4 py-3 text-right font-mono">
+                      <span className="text-gray-800 dark:text-slate-200">
+                        {formatNumber(f.metrics.d1Writes)}
+                      </span>
+                      <span className={clsx('block text-[10px]', getPctClass(d1WritesPct))}>
+                        {d1WritesPct.toFixed(0)}%
+                      </span>
+                    </td>
+                    <td className="px-4 py-3 text-right font-mono">
+                      <span className="text-gray-800 dark:text-slate-200">
+                        {formatNumber(kvOps)}
+                      </span>
+                      <span className={clsx('block text-[10px]', getPctClass(kvOpsPct))}>
+                        {kvOpsPct.toFixed(0)}%
+                      </span>
+                    </td>
+                    <td className="px-4 py-3 text-right font-mono text-gray-800 dark:text-slate-200">
+                      {formatNumber(f.metrics.requests)}
+                    </td>
+                    <td className="px-4 py-3">
+                      <div className="flex justify-center">
+                        {trendData.length > 0 ? (
+                          <Sparkline data={trendData} width={60} height={20} color="#3b82f6" />
+                        ) : (
+                          <span className="text-gray-400 dark:text-slate-600">—</span>
+                        )}
+                      </div>
+                    </td>
+                    <td className="px-4 py-3">
+                      <HeartbeatIndicator lastHeartbeat={f.lastHeartbeat} />
+                    </td>
+                    <td className="px-4 py-3 text-center">
+                      <span
+                        className={clsx(
+                          'inline-flex items-center gap-1 px-2 py-0.5 rounded text-[10px] font-semibold uppercase',
+                          f.circuitBreaker.enabled
+                            ? 'bg-emerald-500/20 text-emerald-400'
+                            : 'bg-rose-500/20 text-rose-400'
+                        )}
+                      >
+                        {f.circuitBreaker.enabled ? (
+                          <CheckCircle className="w-3 h-3" />
+                        ) : (
+                          <XCircle className="w-3 h-3" />
+                        )}
+                        {f.circuitBreaker.enabled ? 'Active' : 'Disabled'}
+                      </span>
+                    </td>
+                    <td className="px-4 py-3 text-center">
+                      <button
+                        type="button"
+                        onClick={() => handleToggle(f.featureKey, f.circuitBreaker.enabled)}
+                        className={clsx(
+                          'px-2 py-1 text-[10px] font-semibold uppercase rounded transition-colors',
+                          f.circuitBreaker.enabled
+                            ? 'bg-rose-500/20 text-rose-400 hover:bg-rose-500/30'
+                            : 'bg-emerald-500/20 text-emerald-400 hover:bg-emerald-500/30'
+                        )}
+                      >
+                        {f.circuitBreaker.enabled ? 'Disable' : 'Enable'}
+                      </button>
+                    </td>
+                  </tr>
+                );
+              })}
+            </tbody>
+          </table>
+        </div>
+      )}
+
+      {/* Footer */}
+      <div className="px-4 py-2 border-t border-gray-200 dark:border-slate-800 text-[10px] text-gray-500 dark:text-slate-500">
+        Last updated: {lastUpdated ? lastUpdated.toLocaleTimeString() : '--'}
+      </div>
+    </div>
+  );
+}
+
+export default FeatureBudgets;

package/templates/standard/dashboard/src/lib/errors/api.ts

@@ -0,0 +1,84 @@
+/**
+ * Error Collector API Client
+ */
+
+import type { ErrorOccurrence, ErrorListResponse, ErrorStats, ErrorFilter } from './types';
+
+const BASE_URL = '/api/errors';
+
+/**
+ * List errors with optional filtering
+ */
+export async function listErrors(filter: ErrorFilter = {}): Promise<ErrorListResponse> {
+  const params = new URLSearchParams();
+
+  if (filter.script) params.set('script', filter.script);
+  if (filter.priority) params.set('priority', filter.priority);
+  if (filter.status) params.set('status', filter.status);
+  if (filter.project) params.set('project', filter.project);
+  if (filter.error_type) params.set('error_type', filter.error_type);
+  if (filter.date_from) params.set('date_from', filter.date_from);
+  if (filter.date_to) params.set('date_to', filter.date_to);
+  if (filter.limit) params.set('limit', String(filter.limit));
+  if (filter.offset) params.set('offset', String(filter.offset));
+
+  const response = await fetch(`${BASE_URL}?${params.toString()}`);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch errors: ${response.statusText}`);
+  }
+  return response.json();
+}
+
+/**
+ * Get error statistics for dashboard overview
+ */
+export async function getErrorStats(): Promise<ErrorStats> {
+  const response = await fetch(`${BASE_URL}/stats`);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch error stats: ${response.statusText}`);
+  }
+  return response.json();
+}
+
+/**
+ * Get single error by fingerprint
+ */
+export async function getError(fingerprint: string): Promise<ErrorOccurrence> {
+  const response = await fetch(`${BASE_URL}/${fingerprint}`);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch error: ${response.statusText}`);
+  }
+  return response.json();
+}
+
+/**
+ * Mute an error (add cf:muted label to GitHub issue)
+ */
+export async function muteError(
+  fingerprint: string
+): Promise<{ success: boolean; message: string }> {
+  const response = await fetch(`${BASE_URL}/${fingerprint}/mute`, {
+    method: 'POST',
+  });
+  if (!response.ok) {
+    const data = await response.json();
+    throw new Error(data.error || 'Failed to mute error');
+  }
+  return response.json();
+}
+
+/**
+ * Resolve an error manually
+ */
+export async function resolveError(
+  fingerprint: string
+): Promise<{ success: boolean; message: string }> {
+  const response = await fetch(`${BASE_URL}/${fingerprint}/resolve`, {
+    method: 'POST',
+  });
+  if (!response.ok) {
+    const data = await response.json();
+    throw new Error(data.error || 'Failed to resolve error');
+  }
+  return response.json();
+}

package/templates/standard/dashboard/src/lib/errors/types.ts

@@ -0,0 +1,75 @@
+/**
+ * Error Collector Dashboard Types
+ */
+
+export type ErrorType = 'exception' | 'cpu_limit' | 'memory_limit' | 'soft_error' | 'warning';
+export type Priority = 'P0' | 'P1' | 'P2' | 'P3' | 'P4';
+export type ErrorStatus = 'open' | 'resolved' | 'wont_fix' | 'pending_digest' | 'digested';
+
+export interface ErrorOccurrence {
+  id: string;
+  fingerprint: string;
+  script_name: string;
+  project: string;
+  error_type: ErrorType;
+  priority: Priority;
+  github_issue_number?: number;
+  github_issue_url?: string;
+  github_repo: string;
+  status: ErrorStatus;
+  resolved_at?: number;
+  resolved_by?: string;
+  first_seen_at: number;
+  last_seen_at: number;
+  occurrence_count: number;
+  last_request_url?: string;
+  last_request_method?: string;
+  last_colo?: string;
+  last_country?: string;
+  last_cf_ray?: string;
+  last_exception_name?: string;
+  last_exception_message?: string;
+  last_logs_json?: string;
+  normalized_message?: string;
+  error_category?: string;
+}
+
+export interface ErrorListResponse {
+  errors: ErrorOccurrence[];
+  total: number;
+  limit: number;
+  offset: number;
+}
+
+export interface ErrorStats {
+  byPriority: Record<string, number>;
+  byStatus: Record<string, number>;
+  byType: Record<string, number>;
+  byProject: Record<string, number>;
+  byTransientCategory: Record<string, number>;
+  recentCount: number;
+  todayOccurrences: number;
+  totalOpen: number;
+}
+
+export type ErrorSortColumn =
+  | 'priority'
+  | 'script_name'
+  | 'status'
+  | 'occurrence_count'
+  | 'last_seen_at';
+export type SortOrder = 'asc' | 'desc';
+
+export interface ErrorFilter {
+  script?: string;
+  priority?: Priority;
+  status?: ErrorStatus;
+  project?: string;
+  error_type?: ErrorType;
+  date_from?: string;
+  date_to?: string;
+  limit?: number;
+  offset?: number;
+  sort_by?: ErrorSortColumn;
+  sort_order?: SortOrder;
+}