@littlebearapps/platform-admin-sdk 2.0.0 → 2.2.0

package/templates/shared/dashboard/src/components/usage/usage-colors.ts

@@ -0,0 +1,292 @@
+/**
+ * Usage Dashboard Color System
+ *
+ * Consistent, accessible color palette for resource types.
+ * Part of task-18: Usage Dashboard Interactive Chart & Table Enhancement
+ *
+ * Each resource type has light and dark mode variants optimised for:
+ * - WCAG 2.1 AA contrast on backgrounds
+ * - Visual distinction between resource types
+ * - Consistency with the existing design token system
+ */
+
+/**
+ * Resource type identifiers matching DailyCostBreakdown keys
+ */
+export type ResourceType =
+  | 'workers'
+  | 'd1'
+  | 'kv'
+  | 'r2'
+  | 'vectorize'
+  | 'aiGateway'
+  | 'durableObjects'
+  | 'workersAI'
+  | 'queues';
+
+/**
+ * Theme-aware color definition
+ */
+export interface ResourceColor {
+  light: {
+    fill: string;
+    fillHover: string;
+    text: string;
+  };
+  dark: {
+    fill: string;
+    fillHover: string;
+    text: string;
+  };
+}
+
+/**
+ * Resource display metadata
+ */
+export interface ResourceInfo {
+  key: ResourceType;
+  label: string;
+  shortLabel: string;
+  color: ResourceColor;
+}
+
+/**
+ * Color palette for each resource type
+ *
+ * Colours chosen for:
+ * - High contrast in both light and dark modes
+ * - Distinct hues for easy differentiation
+ * - Consistent saturation and brightness levels
+ */
+export const RESOURCE_COLORS: Record<ResourceType, ResourceColor> = {
+  workers: {
+    light: {
+      fill: '#f59e0b', // amber-500
+      fillHover: '#d97706', // amber-600
+      text: '#92400e', // amber-800
+    },
+    dark: {
+      fill: '#fbbf24', // amber-400
+      fillHover: '#f59e0b', // amber-500
+      text: '#fcd34d', // amber-300
+    },
+  },
+  d1: {
+    light: {
+      fill: '#3b82f6', // blue-500
+      fillHover: '#2563eb', // blue-600
+      text: '#1e40af', // blue-800
+    },
+    dark: {
+      fill: '#60a5fa', // blue-400
+      fillHover: '#3b82f6', // blue-500
+      text: '#93c5fd', // blue-300
+    },
+  },
+  kv: {
+    light: {
+      fill: '#10b981', // emerald-500
+      fillHover: '#059669', // emerald-600
+      text: '#065f46', // emerald-800
+    },
+    dark: {
+      fill: '#34d399', // emerald-400
+      fillHover: '#10b981', // emerald-500
+      text: '#6ee7b7', // emerald-300
+    },
+  },
+  r2: {
+    light: {
+      fill: '#8b5cf6', // violet-500
+      fillHover: '#7c3aed', // violet-600
+      text: '#5b21b6', // violet-800
+    },
+    dark: {
+      fill: '#a78bfa', // violet-400
+      fillHover: '#8b5cf6', // violet-500
+      text: '#c4b5fd', // violet-300
+    },
+  },
+  vectorize: {
+    light: {
+      fill: '#ec4899', // pink-500
+      fillHover: '#db2777', // pink-600
+      text: '#9d174d', // pink-800
+    },
+    dark: {
+      fill: '#f472b6', // pink-400
+      fillHover: '#ec4899', // pink-500
+      text: '#f9a8d4', // pink-300
+    },
+  },
+  aiGateway: {
+    light: {
+      fill: '#06b6d4', // cyan-500
+      fillHover: '#0891b2', // cyan-600
+      text: '#155e75', // cyan-800
+    },
+    dark: {
+      fill: '#22d3ee', // cyan-400
+      fillHover: '#06b6d4', // cyan-500
+      text: '#67e8f9', // cyan-300
+    },
+  },
+  durableObjects: {
+    light: {
+      fill: '#f97316', // orange-500
+      fillHover: '#ea580c', // orange-600
+      text: '#9a3412', // orange-800
+    },
+    dark: {
+      fill: '#fb923c', // orange-400
+      fillHover: '#f97316', // orange-500
+      text: '#fdba74', // orange-300
+    },
+  },
+  workersAI: {
+    light: {
+      fill: '#6366f1', // indigo-500
+      fillHover: '#4f46e5', // indigo-600
+      text: '#3730a3', // indigo-800
+    },
+    dark: {
+      fill: '#818cf8', // indigo-400
+      fillHover: '#6366f1', // indigo-500
+      text: '#a5b4fc', // indigo-300
+    },
+  },
+  queues: {
+    light: {
+      fill: '#14b8a6', // teal-500
+      fillHover: '#0d9488', // teal-600
+      text: '#115e59', // teal-800
+    },
+    dark: {
+      fill: '#2dd4bf', // teal-400
+      fillHover: '#14b8a6', // teal-500
+      text: '#5eead4', // teal-300
+    },
+  },
+};
+
+/**
+ * Resource display information
+ */
+export const RESOURCE_INFO: ResourceInfo[] = [
+  {
+    key: 'workers',
+    label: 'Workers',
+    shortLabel: 'WK',
+    color: RESOURCE_COLORS.workers,
+  },
+  {
+    key: 'd1',
+    label: 'D1 Database',
+    shortLabel: 'D1',
+    color: RESOURCE_COLORS.d1,
+  },
+  {
+    key: 'kv',
+    label: 'KV Storage',
+    shortLabel: 'KV',
+    color: RESOURCE_COLORS.kv,
+  },
+  {
+    key: 'r2',
+    label: 'R2 Storage',
+    shortLabel: 'R2',
+    color: RESOURCE_COLORS.r2,
+  },
+  {
+    key: 'vectorize',
+    label: 'Vectorize',
+    shortLabel: 'VZ',
+    color: RESOURCE_COLORS.vectorize,
+  },
+  {
+    key: 'aiGateway',
+    label: 'AI Gateway',
+    shortLabel: 'AI',
+    color: RESOURCE_COLORS.aiGateway,
+  },
+  {
+    key: 'durableObjects',
+    label: 'Durable Objects',
+    shortLabel: 'DO',
+    color: RESOURCE_COLORS.durableObjects,
+  },
+  {
+    key: 'workersAI',
+    label: 'Workers AI',
+    shortLabel: 'AI',
+    color: RESOURCE_COLORS.workersAI,
+  },
+  {
+    key: 'queues',
+    label: 'Queues',
+    shortLabel: 'Q',
+    color: RESOURCE_COLORS.queues,
+  },
+];
+
+/**
+ * Get Chart.js compatible color arrays for a given theme
+ */
+export function getChartColors(theme: 'light' | 'dark'): {
+  backgroundColor: string[];
+  borderColor: string[];
+  hoverBackgroundColor: string[];
+} {
+  const fills = RESOURCE_INFO.map((r) => r.color[theme].fill);
+  const hovers = RESOURCE_INFO.map((r) => r.color[theme].fillHover);
+
+  return {
+    backgroundColor: fills,
+    borderColor: fills.map((c) => c + 'cc'), // Add some transparency for border
+    hoverBackgroundColor: hovers,
+  };
+}
+
+/**
+ * Get color for a specific resource type
+ */
+export function getResourceColor(
+  resourceType: ResourceType,
+  theme: 'light' | 'dark'
+): ResourceColor['light'] | ResourceColor['dark'] {
+  return RESOURCE_COLORS[resourceType][theme];
+}
+
+/**
+ * Get resource info by key
+ */
+export function getResourceInfo(resourceType: ResourceType): ResourceInfo | undefined {
+  return RESOURCE_INFO.find((r) => r.key === resourceType);
+}
+
+/**
+ * CSS custom properties for resource colours (for injection into stylesheets)
+ */
+export function generateResourceColorCSS(): string {
+  const lines: string[] = [':root {'];
+
+  for (const [key, color] of Object.entries(RESOURCE_COLORS)) {
+    lines.push(`  --usage-resource-${key}: ${color.light.fill};`);
+    lines.push(`  --usage-resource-${key}-hover: ${color.light.fillHover};`);
+    lines.push(`  --usage-resource-${key}-text: ${color.light.text};`);
+  }
+
+  lines.push('}');
+  lines.push('');
+  lines.push('[data-theme="dark"] {');
+
+  for (const [key, color] of Object.entries(RESOURCE_COLORS)) {
+    lines.push(`  --usage-resource-${key}: ${color.dark.fill};`);
+    lines.push(`  --usage-resource-${key}-hover: ${color.dark.fillHover};`);
+    lines.push(`  --usage-resource-${key}-text: ${color.dark.text};`);
+  }
+
+  lines.push('}');
+
+  return lines.join('\n');
+}

package/templates/shared/dashboard/src/lib/cloudflare/analytics.ts

@@ -0,0 +1,310 @@
+/**
+ * Analytics Engine Client Library
+ *
+ * Provides a reusable client for querying Cloudflare Analytics Engine
+ * via the SQL API. Includes retry logic, error handling, and type-safe
+ * column mapping.
+ *
+ * Note: In the dashboard context, prefer using the proxy to platform-usage
+ * worker (/api/usage/query) rather than direct Analytics Engine calls.
+ * This client is provided for potential future direct queries.
+ *
+ * @module lib/cloudflare/analytics
+ * @created 2026-01-20
+ */
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+/**
+ * Analytics Engine configuration for direct queries
+ */
+export interface AnalyticsEngineConfig {
+  accountId: string;
+  apiToken: string;
+}
+
+/**
+ * Analytics Engine SQL API response structure
+ */
+interface AnalyticsEngineResponse {
+  // Direct format (SQL API)
+  meta?: Array<{ name: string; type: string }>;
+  data?: unknown[];
+  rows?: number;
+  rows_before_limit_at_least?: number;
+
+  // Wrapped format (REST API)
+  success?: boolean;
+  errors?: Array<{ code: number; message: string }>;
+  result?: {
+    data: unknown[];
+    meta: Array<{ name: string; type: string }>;
+    rows: number;
+    rows_before_limit_at_least: number;
+  };
+}
+
+/**
+ * Query result with metadata
+ */
+export interface QueryResult<T> {
+  data: T[];
+  meta: {
+    columns: string[];
+    rowCount: number;
+    queryTimeMs: number;
+  };
+}
+
+/**
+ * Error types from Analytics Engine
+ */
+export type AnalyticsEngineErrorCode =
+  | 'RATE_LIMITED'
+  | 'SERVER_ERROR'
+  | 'INVALID_QUERY'
+  | 'UNAUTHORIZED'
+  | 'DATASET_NOT_FOUND'
+  | 'UNKNOWN';
+
+/**
+ * Analytics Engine error with additional context
+ */
+export class AnalyticsEngineError extends Error {
+  constructor(
+    message: string,
+    public readonly code: AnalyticsEngineErrorCode,
+    public readonly statusCode?: number
+  ) {
+    super(message);
+    this.name = 'AnalyticsEngineError';
+  }
+}
+
+// =============================================================================
+// HELPERS
+// =============================================================================
+
+/**
+ * Sleep for a given number of milliseconds
+ */
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Map HTTP status code to error code
+ */
+function statusToErrorCode(status: number): AnalyticsEngineErrorCode {
+  if (status === 429) return 'RATE_LIMITED';
+  if (status === 401 || status === 403) return 'UNAUTHORIZED';
+  if (status >= 500) return 'SERVER_ERROR';
+  if (status === 400) return 'INVALID_QUERY';
+  return 'UNKNOWN';
+}
+
+// =============================================================================
+// CLIENT
+// =============================================================================
+
+/**
+ * Query Analytics Engine via the SQL API with retry logic.
+ *
+ * @param config Analytics Engine configuration
+ * @param sql SQL query to execute
+ * @param retries Maximum number of retries (default: 3)
+ * @returns Query results with metadata
+ *
+ * @example
+ * ```typescript
+ * const result = await queryAnalyticsEngine<MyRow>(
+ *   { accountId: '...', apiToken: '...' },
+ *   'SELECT blob1 as project, SUM(double1) as total FROM "platform-analytics" GROUP BY blob1'
+ * );
+ * console.log(result.data); // [{ project: 'scout', total: 100 }, ...]
+ * ```
+ */
+export async function queryAnalyticsEngine<T>(
+  config: AnalyticsEngineConfig,
+  sql: string,
+  retries = 3
+): Promise<QueryResult<T>> {
+  const startTime = Date.now();
+  const url = `https://api.cloudflare.com/client/v4/accounts/${config.accountId}/analytics_engine/sql`;
+
+  let lastError: Error | null = null;
+
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${config.apiToken}`,
+          'Content-Type': 'text/plain',
+        },
+        body: sql,
+      });
+
+      // Handle rate limiting with retry
+      if (response.status === 429 && attempt < retries) {
+        const retryAfter = response.headers.get('Retry-After');
+        const delayMs = retryAfter
+          ? parseInt(retryAfter, 10) * 1000
+          : Math.min(1000 * Math.pow(2, attempt), 10000);
+        await sleep(delayMs);
+        continue;
+      }
+
+      // Handle server errors with retry
+      if (response.status >= 500 && attempt < retries) {
+        await sleep(Math.min(1000 * Math.pow(2, attempt), 10000));
+        continue;
+      }
+
+      // Parse response
+      const rawText = await response.text();
+      let data: AnalyticsEngineResponse;
+
+      try {
+        data = JSON.parse(rawText) as AnalyticsEngineResponse;
+      } catch {
+        throw new AnalyticsEngineError(
+          `Invalid JSON response: ${rawText.slice(0, 200)}`,
+          'UNKNOWN',
+          response.status
+        );
+      }
+
+      // Check for error response
+      if (!response.ok) {
+        const errorCode = statusToErrorCode(response.status);
+        const errorMessage = data.errors?.map((e) => e.message).join(', ') ?? rawText.slice(0, 200);
+
+        // Handle dataset not found (empty schema)
+        if (errorMessage.includes('unable to find type of column')) {
+          throw new AnalyticsEngineError(
+            'Dataset has no data yet',
+            'DATASET_NOT_FOUND',
+            response.status
+          );
+        }
+
+        throw new AnalyticsEngineError(errorMessage, errorCode, response.status);
+      }
+
+      // Handle both response formats:
+      // 1. Direct format: { meta, data, rows }
+      // 2. Wrapped format: { success, result: { meta, data, rows } }
+      const meta = data.meta ?? data.result?.meta;
+      const resultData = data.data ?? data.result?.data;
+
+      if (!meta || !resultData) {
+        throw new AnalyticsEngineError(
+          `Response missing expected fields: ${JSON.stringify(Object.keys(data))}`,
+          'UNKNOWN',
+          response.status
+        );
+      }
+
+      // Map the result data to typed objects using column metadata
+      // Analytics Engine can return data in two formats:
+      // 1. Array of arrays: [[val1, val2], [val1, val2]] - needs column mapping
+      // 2. Array of objects: [{col1: val1, col2: val2}, ...] - already in object format
+      const columns = meta.map((m) => m.name);
+
+      const mappedData = resultData.map((row) => {
+        // If row is already an object (not an array), return it directly
+        if (row !== null && typeof row === 'object' && !Array.isArray(row)) {
+          return row as T;
+        }
+
+        // Row is an array - map using column metadata
+        const rowArray = row as unknown[];
+        const obj: Record<string, unknown> = {};
+        columns.forEach((col, i) => {
+          obj[col] = rowArray[i];
+        });
+        return obj as T;
+      });
+
+      return {
+        data: mappedData,
+        meta: {
+          columns,
+          rowCount: mappedData.length,
+          queryTimeMs: Date.now() - startTime,
+        },
+      };
+    } catch (error) {
+      lastError = error as Error;
+
+      // Don't retry on non-retryable errors
+      if (error instanceof AnalyticsEngineError) {
+        if (error.code !== 'RATE_LIMITED' && error.code !== 'SERVER_ERROR') {
+          throw error;
+        }
+      }
+
+      // Wait before retry
+      if (attempt < retries) {
+        await sleep(Math.min(1000 * Math.pow(2, attempt), 10000));
+      }
+    }
+  }
+
+  // All retries exhausted
+  throw lastError ?? new AnalyticsEngineError('Query failed after all retries', 'UNKNOWN');
+}
+
+/**
+ * Execute a simple SELECT query and return raw results.
+ * Convenience wrapper around queryAnalyticsEngine.
+ *
+ * @param config Analytics Engine configuration
+ * @param tableName Table/dataset name
+ * @param options Query options
+ * @returns Query results
+ */
+export async function selectFromAnalytics<T>(
+  config: AnalyticsEngineConfig,
+  tableName: string,
+  options: {
+    columns?: string[];
+    where?: string;
+    groupBy?: string[];
+    orderBy?: string;
+    limit?: number;
+  } = {}
+): Promise<T[]> {
+  const { columns = ['*'], where, groupBy, orderBy, limit } = options;
+
+  // Build SQL query
+  let sql = `SELECT ${columns.join(', ')} FROM "${tableName}"`;
+
+  if (where) {
+    sql += ` WHERE ${where}`;
+  }
+
+  if (groupBy && groupBy.length > 0) {
+    sql += ` GROUP BY ${groupBy.join(', ')}`;
+  }
+
+  if (orderBy) {
+    sql += ` ORDER BY ${orderBy}`;
+  }
+
+  if (limit) {
+    sql += ` LIMIT ${limit}`;
+  }
+
+  const result = await queryAnalyticsEngine<T>(config, sql);
+  return result.data;
+}
+
+// =============================================================================
+// EXPORTS
+// =============================================================================
+
+export type { AnalyticsEngineResponse };

package/templates/shared/dashboard/src/lib/cloudflare/d1.ts

@@ -0,0 +1,55 @@
+/**
+ * D1 Database Helpers
+ * Query system_health_checks for heartbeat data
+ */
+
+import type { D1Database } from '@cloudflare/workers-types';
+
+export interface HealthCheckRecord {
+  project_id: string;
+  last_heartbeat: number; // Unix timestamp (seconds)
+  status: string;
+}
+
+export type ProjectHealthMap = Record<
+  string,
+  {
+    lastHeartbeat: string; // ISO string
+    status: string;
+  }
+>;
+
+/**
+ * Get latest heartbeat per project from system_health_checks
+ * Aggregates by project_id (takes MAX last_heartbeat across all features)
+ */
+export async function getSystemHealth(db: D1Database): Promise<ProjectHealthMap> {
+  try {
+    const result = await db
+      .prepare(
+        `
+        SELECT
+          project_id,
+          MAX(last_heartbeat) as last_heartbeat,
+          status
+        FROM system_health_checks
+        GROUP BY project_id
+      `
+      )
+      .all<HealthCheckRecord>();
+
+    const healthMap: ProjectHealthMap = {};
+
+    for (const row of result.results ?? []) {
+      healthMap[row.project_id] = {
+        lastHeartbeat: new Date(row.last_heartbeat * 1000).toISOString(),
+        status: row.status,
+      };
+    }
+
+    return healthMap;
+  } catch (error) {
+    console.error('[D1] Error querying system_health_checks:', error);
+    return {}; // Graceful degradation
+  }
+}