@littlebearapps/platform-admin-sdk 2.1.0 → 2.3.0

package/templates/shared/dashboard/src/components/usage/state/usageStore.ts

@@ -0,0 +1,376 @@
+/**
+ * Usage Dashboard State Store
+ *
+ * Centralised nanostores for reactive state management.
+ * Part of task-19: Usage Dashboard Refactor Phase 1 - Foundation
+ *
+ * @example
+ * ```ts
+ * import { $period, $dailyData, $totalCost } from './usageStore';
+ *
+ * // Read current value
+ * console.log($period.get()); // '30d'
+ *
+ * // Subscribe to changes
+ * $dailyData.subscribe(data => console.log('Data updated:', data.length));
+ *
+ * // Set value
+ * $period.set('7d');
+ * ```
+ */
+
+import { atom, map, computed } from 'nanostores';
+import type { DailyCostBreakdown } from '../../../lib/cloudflare/graphql';
+
+// ============================================================================
+// Period Selection
+// ============================================================================
+
+/**
+ * Available time periods for filtering
+ */
+export type Period = '24h' | '7d' | '30d' | 'custom';
+
+/**
+ * Current period selection
+ * @default '30d'
+ */
+export const $period = atom<Period>('30d');
+
+// ============================================================================
+// Project Filter
+// ============================================================================
+
+/**
+ * Current project filter
+ * @default 'all'
+ */
+export const $project = atom<string>('all');
+
+// ============================================================================
+// Custom Date Range
+// ============================================================================
+
+/**
+ * Custom date range (used when period === 'custom')
+ */
+export const $customDateRange = map<{ start: string; end: string }>({
+  start: '',
+  end: '',
+});
+
+// ============================================================================
+// Timezone
+// ============================================================================
+
+/**
+ * Timezone for date formatting
+ * @default 'Australia/Melbourne'
+ */
+export const $timezone = atom<string>('Australia/Melbourne');
+
+// ============================================================================
+// Daily Cost Data
+// ============================================================================
+
+/**
+ * Daily cost breakdown data from API
+ */
+export const $dailyData = atom<DailyCostBreakdown[]>([]);
+
+// ============================================================================
+// Loading State
+// ============================================================================
+
+/**
+ * Whether data is currently being fetched
+ */
+export const $isLoading = atom<boolean>(false);
+
+/**
+ * Whether any day in the current data has legacy/inflated values (rollupVersion=1)
+ * Legacy data was aggregated using SUM() on cumulative hourly values, resulting in ~15x inflated costs.
+ * Accurate data (rollupVersion=2) uses MAX() aggregation.
+ */
+export const $hasLegacyData = atom<boolean>(false);
+
+// ============================================================================
+// Selection State
+// ============================================================================
+
+/**
+ * Currently selected date (from chart click)
+ * @default null
+ */
+export const $selectedDate = atom<string | null>(null);
+
+// ============================================================================
+// Computed Values
+// ============================================================================
+
+/**
+ * Total cost across all days
+ */
+export const $totalCost = computed($dailyData, (data) => data.reduce((sum, d) => sum + d.total, 0));
+
+/**
+ * Date range display string formatted for Melbourne timezone
+ */
+export const $dateRangeDisplay = computed([$dailyData, $timezone], (data, tz) => {
+  if (data.length === 0) return '';
+
+  const first = data[0].date;
+  const last = data[data.length - 1].date;
+
+  const opts: Intl.DateTimeFormatOptions = {
+    timeZone: tz,
+    day: 'numeric',
+    month: 'short',
+  };
+
+  const startStr = new Date(first).toLocaleDateString('en-AU', opts);
+  const endStr = new Date(last).toLocaleDateString('en-AU', opts);
+
+  return `${startStr} - ${endStr}`;
+});
+
+/**
+ * Number of days in current data
+ */
+export const $dayCount = computed($dailyData, (data) => data.length);
+
+// ============================================================================
+// GitHub Usage Data
+// ============================================================================
+
+/**
+ * GitHub usage data from the utilization endpoint
+ */
+export interface GitHubUsageData {
+  mtdUsage: {
+    actionsMinutes: number;
+    actionsMinutesIncluded: number;
+    actionsMinutesUsagePct: number;
+    actionsStorageGbHours: number;
+    actionsStorageGbIncluded: number;
+    ghecUserMonths: number;
+    ghasCodeSecuritySeats: number;
+    ghasSecretProtectionSeats: number;
+    totalCost: number;
+  };
+  plan: {
+    name: string;
+    filledSeats: number;
+    totalSeats: number;
+  };
+  lastUpdated: string | null;
+  isStale: boolean;
+}
+
+/**
+ * GitHub usage data store (separate from period-filtered Cloudflare data)
+ * This data is fetched once and doesn't change with period selection.
+ */
+export const $githubUsage = atom<GitHubUsageData | null>(null);
+
+/**
+ * Average daily cost
+ */
+export const $averageDailyCost = computed($dailyData, (data) => {
+  if (data.length === 0) return 0;
+  const total = data.reduce((sum, d) => sum + d.total, 0);
+  return total / data.length;
+});
+
+/**
+ * Cost breakdown by resource type (totals)
+ */
+export const $resourceTotals = computed($dailyData, (data) => {
+  const totals = {
+    workers: 0,
+    d1: 0,
+    kv: 0,
+    r2: 0,
+    vectorize: 0,
+    aiGateway: 0,
+    durableObjects: 0,
+    workersAI: 0,
+    queues: 0,
+  };
+
+  for (const day of data) {
+    totals.workers += day.workers;
+    totals.d1 += day.d1;
+    totals.kv += day.kv;
+    totals.r2 += day.r2;
+    totals.vectorize += day.vectorize;
+    totals.aiGateway += day.aiGateway;
+    totals.durableObjects += day.durableObjects;
+    totals.workersAI += day.workersAI;
+    totals.queues += day.queues;
+  }
+
+  return totals;
+});
+
+/**
+ * Top spender - service type with highest cost in the period
+ */
+export interface TopSpenderData {
+  /** Service type name */
+  service: string;
+  /** Display label */
+  label: string;
+  /** Total cost for this service */
+  cost: number;
+  /** Percentage of total cost */
+  percentageOfTotal: number;
+}
+
+const SERVICE_LABELS: Record<string, string> = {
+  workers: 'Workers',
+  d1: 'D1 Database',
+  kv: 'KV Storage',
+  r2: 'R2 Storage',
+  vectorize: 'Vectorize',
+  aiGateway: 'AI Gateway',
+  durableObjects: 'Durable Objects',
+  workersAI: 'Workers AI',
+  queues: 'Queues',
+};
+
+export const $topSpender = computed($resourceTotals, (totals): TopSpenderData | null => {
+  const entries = Object.entries(totals).filter(([_, cost]) => cost > 0);
+  if (entries.length === 0) return null;
+
+  const totalCost = entries.reduce((sum, [_, cost]) => sum + cost, 0);
+  const [topService, topCost] = entries.reduce(
+    (max, entry) => (entry[1] > max[1] ? entry : max),
+    entries[0]
+  );
+
+  return {
+    service: topService,
+    label: SERVICE_LABELS[topService] || topService,
+    cost: topCost,
+    percentageOfTotal: totalCost > 0 ? (topCost / totalCost) * 100 : 0,
+  };
+});
+
+// ============================================================================
+// Projects & Allowances (from /api/usage/projects)
+// ============================================================================
+
+/**
+ * Service allowance definition
+ */
+export interface AllowanceInfo {
+  limit: number;
+  unit: string;
+}
+
+/**
+ * Allowances object from API
+ */
+export interface AllowancesData {
+  workers: AllowanceInfo;
+  d1_writes: AllowanceInfo;
+  kv_writes: AllowanceInfo;
+  r2_storage: AllowanceInfo;
+  durableObjects: AllowanceInfo;
+  vectorize: AllowanceInfo;
+  github_actions_minutes: AllowanceInfo;
+}
+
+/**
+ * Projected cost calculation
+ */
+export interface ProjectedCost {
+  /** Current month-to-date cost in USD */
+  currentCost: number;
+  /** Number of days elapsed this month */
+  daysPassed: number;
+  /** Total days in the current month */
+  daysInMonth: number;
+  /** Projected end-of-month cost based on current burn rate */
+  projectedMonthlyCost: number;
+}
+
+/**
+ * Project from D1 registry with resource count
+ */
+export interface ProjectData {
+  projectId: string;
+  displayName: string;
+  description: string | null;
+  color: string | null;
+  icon: string | null;
+  owner: string | null;
+  repoPath: string | null;
+  status: 'active' | 'archived' | 'development';
+  primaryResource: string | null;
+  customLimit: number | null;
+  /** Full GitHub repository URL */
+  repoUrl: string | null;
+  /** GitHub repository identifier */
+  githubRepoId: string | null;
+  /** Number of CF resources mapped to this project */
+  resourceCount: number;
+}
+
+/**
+ * Projects list store (from /api/usage/projects)
+ */
+export const $projects = atom<ProjectData[]>([]);
+
+/**
+ * Service allowances store
+ */
+export const $allowances = atom<AllowancesData | null>(null);
+
+/**
+ * Projected cost store
+ */
+export const $projectedCost = atom<ProjectedCost | null>(null);
+
+/**
+ * Projects loading state
+ */
+export const $projectsLoading = atom<boolean>(false);
+
+// ============================================================================
+// Filter State (for resource table)
+// ============================================================================
+
+/**
+ * Resource table filter state (search, type filter, toggles)
+ */
+export interface ResourceFilterState {
+  /** Search query string */
+  search: string;
+  /** Resource type filter ('all' or specific type) */
+  typeFilter: string;
+  /** Show only resources with cost changes */
+  showOnlyChanged: boolean;
+  /** Show only resources with non-zero cost */
+  showNonZeroCost: boolean;
+}
+
+/**
+ * Resource filter state store
+ */
+export const $resourceFilters = map<ResourceFilterState>({
+  search: '',
+  typeFilter: 'all',
+  showOnlyChanged: false,
+  showNonZeroCost: false,
+});
+
+// ============================================================================
+// Error State
+// ============================================================================
+
+/**
+ * Error message store (null when no error)
+ */
+export const $error = atom<string | null>(null);

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`;
+}