@littlebearapps/platform-admin-sdk 2.0.0 → 2.2.0

package/templates/shared/dashboard/src/components/usage/types.ts

@@ -0,0 +1,283 @@
+/**
+ * Usage Dashboard Shared Types
+ *
+ * Centralised type definitions for usage dashboard components.
+ * Part of task-17 (Enhanced Cloudflare Usage Dashboard).
+ */
+
+export type ResourceType =
+  | 'worker'
+  | 'd1'
+  | 'kv'
+  | 'r2'
+  | 'vectorize'
+  | 'pages'
+  | 'queues'
+  | 'workflows'
+  | 'do'
+  | 'ai-gateway';
+
+export type ResourceStatus = 'healthy' | 'warning' | 'high' | 'critical';
+
+export type SortDirection = 'asc' | 'desc';
+
+export type CompareMode = 'none' | 'lastMonth' | 'custom';
+
+export interface UnifiedResource {
+  id: string;
+  name: string;
+  type: ResourceType;
+  project: string;
+  /** GitHub repository URL for the project (if available) */
+  repoUrl?: string | null;
+  usage: {
+    value: number;
+    unit: string;
+    formatted: string;
+  };
+  /** Percentage of monthly limit used (0-100+) */
+  limitPct?: number | null;
+  costCurrent: number;
+  costPrior: number;
+  costDelta: number;
+  costDeltaPct: number | 'NEW' | null;
+  status: ResourceStatus;
+}
+
+export interface SparklinePoint {
+  date: string;
+  value: number;
+}
+
+export interface DateRange {
+  startDate: string;
+  endDate: string;
+}
+
+export interface FilterState {
+  period: '24h' | '7d' | '30d';
+  project: 'all' | 'brand-copilot' | 'scout' | 'platform';
+  compareMode: CompareMode;
+  customDateRange?: DateRange;
+  serviceTypes: ResourceType[];
+  searchQuery: string;
+  onlyChanged: boolean;
+  nonZeroCost: boolean;
+}
+
+export interface SortState {
+  column: string;
+  direction: SortDirection;
+}
+
+// Resource type metadata
+export const RESOURCE_TYPE_ICONS: Record<ResourceType, string> = {
+  worker: '⚡',
+  d1: '🗄️',
+  kv: '🔑',
+  r2: '📦',
+  vectorize: '🧮',
+  pages: '📄',
+  queues: '📬',
+  workflows: '🔄',
+  do: '🔗',
+  'ai-gateway': '🤖',
+};
+
+export const RESOURCE_TYPE_LABELS: Record<ResourceType, string> = {
+  worker: 'Worker',
+  d1: 'D1',
+  kv: 'KV',
+  r2: 'R2',
+  vectorize: 'Vectorize',
+  pages: 'Pages',
+  queues: 'Queues',
+  workflows: 'Workflows',
+  do: 'Durable Objects',
+  'ai-gateway': 'AI Gateway',
+};
+
+export const STATUS_COLOURS: Record<ResourceStatus, string> = {
+  healthy: '#10B981',
+  warning: '#F59E0B',
+  high: '#F97316',
+  critical: '#EF4444',
+};
+
+// Utility functions
+export function formatCurrency(amount: number): string {
+  if (amount === 0) return '$0.00';
+  if (amount < 0.01) return '< $0.01';
+  return `$${amount.toFixed(2)}`;
+}
+
+export function formatDeltaPct(pct: number | 'NEW' | null): string {
+  if (pct === 'NEW') return 'NEW';
+  if (pct === null) return '—';
+  if (pct === 0) return '0%';
+  const sign = pct > 0 ? '+' : '';
+  return `${sign}${pct.toFixed(1)}%`;
+}
+
+export function getDeltaClass(pct: number | 'NEW' | null): string {
+  if (pct === 'NEW') return 'delta-new';
+  if (pct === null || pct === 0) return 'delta-neutral';
+  return pct > 0 ? 'delta-up' : 'delta-down';
+}
+
+export function formatLimitPct(pct: number | null | undefined): string {
+  if (pct === null || pct === undefined) return '—';
+  if (pct === 0) return '0%';
+  if (pct >= 100) return `${pct.toFixed(0)}%`;
+  if (pct >= 10) return `${pct.toFixed(0)}%`;
+  return `${pct.toFixed(1)}%`;
+}
+
+export function getLimitPctClass(pct: number | null | undefined): string {
+  if (pct === null || pct === undefined) return 'limit-neutral';
+  if (pct >= 90) return 'limit-critical';
+  if (pct >= 75) return 'limit-high';
+  if (pct >= 50) return 'limit-warning';
+  return 'limit-ok';
+}
+
+// ============================================================================
+// Usage Overview Types (task-usage-redesign)
+// ============================================================================
+
+/**
+ * Provider type for usage metrics
+ */
+export type UsageProvider = 'cloudflare' | 'github';
+
+/**
+ * Utilization status based on percentage thresholds
+ */
+export type UtilizationStatus = 'ok' | 'warning' | 'critical' | 'overage';
+
+/**
+ * Normalized resource metric for cross-provider comparison
+ */
+export interface ResourceMetric {
+  id: string;
+  label: string;
+  provider: UsageProvider;
+  current: number;
+  limit: number | null; // null if unlimited
+  unit: string;
+  percentage: number;
+  costEstimate: number;
+  status: UtilizationStatus;
+  overage: number; // Amount over limit (0 if under)
+  overageCost: number; // Cost of overage
+}
+
+/**
+ * Per-project usage breakdown with service-level detail
+ */
+export interface ProjectServiceBreakdown {
+  projectId: string;
+  projectName: string;
+  services: ResourceMetric[];
+  totalCost: number;
+  totalUtilization: number; // Weighted average or max
+  circuitBreakerStatus: 'active' | 'inactive' | 'triggered';
+}
+
+/**
+ * Global health summary for a provider
+ */
+export interface ProviderHealth {
+  provider: UsageProvider;
+  percentage: number;
+  warnings: number; // Count of services in warning/critical status
+  status: UtilizationStatus;
+}
+
+/**
+ * GitHub repository usage breakdown
+ */
+export interface RepoUsage {
+  repoName: string;
+  actionsMinutes: number;
+  actionsMinutesPct: number;
+  storageBytes: number;
+}
+
+/**
+ * Complete dashboard data response
+ */
+export interface UsageOverviewData {
+  timestamp: string;
+  period: {
+    start: string;
+    end: string;
+  };
+  health: {
+    cloudflare: ProviderHealth;
+    github: ProviderHealth;
+  };
+  burnRate: {
+    mtdCost: number;
+    projectedMonthlyCost: number;
+    dailyBurnRate: number;
+    vsLastMonthPct: number;
+    budget: number | null;
+  };
+  cloudflareServices: ResourceMetric[];
+  githubServices: ResourceMetric[];
+  projectBreakdowns: ProjectServiceBreakdown[];
+  githubRepos: RepoUsage[];
+}
+
+/**
+ * Calculate utilization status from percentage
+ */
+export function getUtilizationStatus(percentage: number): UtilizationStatus {
+  if (percentage >= 100) return 'overage';
+  if (percentage >= 90) return 'critical';
+  if (percentage >= 70) return 'warning';
+  return 'ok';
+}
+
+/**
+ * Status colours for utilization bars
+ */
+export const UTILIZATION_COLOURS: Record<UtilizationStatus, string> = {
+  ok: '#22c55e', // green-500
+  warning: '#eab308', // yellow-500
+  critical: '#ef4444', // red-500
+  overage: '#dc2626', // red-600
+};
+
+/**
+ * Format large numbers with K/M/B suffixes
+ */
+export function formatLargeNumber(num: number): string {
+  if (num >= 1_000_000_000) {
+    return `${(num / 1_000_000_000).toFixed(1)}B`;
+  }
+  if (num >= 1_000_000) {
+    return `${(num / 1_000_000).toFixed(1)}M`;
+  }
+  if (num >= 1_000) {
+    return `${(num / 1_000).toFixed(1)}K`;
+  }
+  return num.toFixed(0);
+}
+
+/**
+ * Format bytes to human readable (GB, MB, etc.)
+ */
+export function formatBytes(bytes: number): string {
+  if (bytes >= 1_000_000_000) {
+    return `${(bytes / 1_000_000_000).toFixed(2)} GB`;
+  }
+  if (bytes >= 1_000_000) {
+    return `${(bytes / 1_000_000).toFixed(2)} MB`;
+  }
+  if (bytes >= 1_000) {
+    return `${(bytes / 1_000).toFixed(2)} KB`;
+  }
+  return `${bytes} B`;
+}

package/templates/shared/dashboard/src/components/usage/unified/AlertBanner.tsx

@@ -0,0 +1,172 @@
+/**
+ * AlertBanner Component
+ *
+ * Displays critical alerts for services approaching or exceeding limits.
+ * Dismissible alerts are stored in localStorage.
+ * Supports collapse/expand for managing alert visibility.
+ */
+
+import { useState, useMemo } from 'react';
+import { AlertTriangle, X, ChevronDown, ChevronUp, ChevronsUpDown } from 'lucide-react';
+import { clsx } from 'clsx';
+import type { ServiceUtilisation, BurnRateData } from './types';
+
+interface AlertBannerProps {
+  services: ServiceUtilisation[];
+  burnRate: BurnRateData | null;
+  onDismiss: (alertId: string) => void;
+  dismissedAlerts: Set<string>;
+}
+
+interface AlertItem {
+  id: string;
+  type: 'budget' | 'service';
+  title: string;
+  detail: string;
+}
+
+export function AlertBanner({ services, burnRate, onDismiss, dismissedAlerts }: AlertBannerProps) {
+  // Collapsed state - which alerts are collapsed (show title only)
+  const [collapsed, setCollapsed] = useState<Set<string>>(new Set());
+  // All alerts collapsed state for the header toggle
+  const [allCollapsed, setAllCollapsed] = useState(false);
+
+  // Filter to critical/overage alerts that haven't been dismissed
+  const criticalAlerts = services
+    .filter((s) => s.status === 'critical' || s.status === 'overage')
+    .filter((s) => !dismissedAlerts.has(s.id));
+
+  // Check for budget alert
+  const showBudgetAlert = burnRate?.status === 'red' && !dismissedAlerts.has('budget');
+
+  // Build unified alert list for count
+  const alerts = useMemo(() => {
+    const list: AlertItem[] = [];
+
+    if (showBudgetAlert && burnRate) {
+      list.push({
+        id: 'budget',
+        type: 'budget',
+        title: 'BUDGET ALERT: Projected spend exceeds target',
+        detail: `Projected: $${burnRate.projectedMonthlyCost.toFixed(2)} | Daily burn: $${burnRate.dailyBurnRate.toFixed(2)}/day | ${burnRate.daysRemaining} days remaining`,
+      });
+    }
+
+    for (const alert of criticalAlerts) {
+      list.push({
+        id: alert.id,
+        type: 'service',
+        title: `CRITICAL: ${alert.label} at ${alert.percentage.toFixed(0)}% of limit`,
+        detail: `Current: ${alert.current.toLocaleString()} ${alert.unit} / Limit: ${alert.limit.toLocaleString()} ${alert.unit}${alert.costEstimate > 0 ? ` | Est. cost: $${alert.costEstimate.toFixed(2)}` : ''}`,
+      });
+    }
+
+    return list;
+  }, [showBudgetAlert, burnRate, criticalAlerts]);
+
+  if (alerts.length === 0) {
+    return null;
+  }
+
+  const toggleCollapse = (id: string) => {
+    setCollapsed((prev) => {
+      const next = new Set(prev);
+      if (next.has(id)) {
+        next.delete(id);
+      } else {
+        next.add(id);
+      }
+      return next;
+    });
+  };
+
+  const toggleAll = () => {
+    if (allCollapsed) {
+      // Expand all
+      setCollapsed(new Set());
+      setAllCollapsed(false);
+    } else {
+      // Collapse all
+      setCollapsed(new Set(alerts.map((a) => a.id)));
+      setAllCollapsed(true);
+    }
+  };
+
+  return (
+    <div className="mb-6">
+      {/* Alert Header with count and collapse toggle */}
+      <div className="flex items-center justify-between mb-2">
+        <div className="flex items-center gap-2">
+          <AlertTriangle className="w-4 h-4 text-rose-400" />
+          <span className="text-xs font-semibold text-rose-300 uppercase tracking-wider">
+            {alerts.length} Active Alert{alerts.length !== 1 ? 's' : ''}
+          </span>
+        </div>
+        <button
+          type="button"
+          onClick={toggleAll}
+          className="flex items-center gap-1 text-xs text-gray-600 dark:text-slate-400 hover:text-gray-700 dark:hover:text-slate-300 transition-colors px-2 py-1 rounded hover:bg-gray-100 dark:hover:bg-slate-800"
+        >
+          <ChevronsUpDown className="w-3 h-3" />
+          {allCollapsed ? 'Expand All' : 'Collapse All'}
+        </button>
+      </div>
+
+      {/* Alerts List */}
+      <div className="space-y-2">
+        {alerts.map((alert) => {
+          const isCollapsed = collapsed.has(alert.id);
+
+          return (
+            <div
+              key={alert.id}
+              className="bg-rose-500/10 border border-rose-500/30 rounded-sm overflow-hidden transition-all"
+            >
+              {/* Alert Header Row - always visible */}
+              <div className="p-3 flex items-center gap-3">
+                <button
+                  type="button"
+                  onClick={() => toggleCollapse(alert.id)}
+                  className="text-rose-400 hover:text-rose-300 p-1 rounded hover:bg-rose-500/20 transition-colors"
+                  aria-label={isCollapsed ? 'Expand alert' : 'Collapse alert'}
+                >
+                  {isCollapsed ? (
+                    <ChevronDown className="w-4 h-4" />
+                  ) : (
+                    <ChevronUp className="w-4 h-4" />
+                  )}
+                </button>
+                <AlertTriangle className="w-4 h-4 text-rose-400 flex-shrink-0" />
+                <span className="text-rose-200 font-semibold text-sm flex-1 truncate">
+                  {alert.title}
+                </span>
+                <button
+                  type="button"
+                  onClick={() => onDismiss(alert.id)}
+                  className="text-rose-400 hover:text-rose-300 p-1 rounded hover:bg-rose-500/20 transition-colors"
+                  aria-label="Dismiss alert"
+                >
+                  <X className="w-4 h-4" />
+                </button>
+              </div>
+
+              {/* Alert Details - collapsible */}
+              <div
+                className={clsx(
+                  'overflow-hidden transition-all duration-200 ease-in-out',
+                  isCollapsed ? 'max-h-0' : 'max-h-24'
+                )}
+              >
+                <div className="px-4 pb-3 pl-12">
+                  <p className="text-rose-300/80 text-xs font-mono">{alert.detail}</p>
+                </div>
+              </div>
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+}
+
+export default AlertBanner;