@littlebearapps/platform-admin-sdk 2.0.0 → 2.1.0

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

package/templates/shared/dashboard/src/lib/cloudflare/index.ts.hbs

@@ -0,0 +1,120 @@
+/**
+ * Cloudflare Observability Library
+ *
+ * Provides unified access to Cloudflare metrics, costs, and analytics.
+ *
+ * @module cloudflare
+ */
+
+// Cost calculator and types
+export {
+  CF_PRICING,
+  CF_FREE_LIMITS,
+  PROJECT_PATTERNS,
+  DEFAULT_ALERT_THRESHOLDS,
+  identifyProject,
+  calculateMonthlyCosts,
+  calculateProjectCosts,
+  calculateDailyCosts,
+  getThresholdLevel,
+  analyseThresholds,
+  mergeThresholds,
+  formatNumber,
+  formatCurrency,
+  type CostBreakdown,
+  type ProjectCostBreakdown,
+  type DailyUsageMetrics,
+  type ThresholdLevel,
+  type ThresholdWarning,
+  type ThresholdAnalysis,
+  type AlertServiceType,
+  type ServiceThreshold,
+  type AlertThresholds,
+} from './costs';
+
+// D1 helpers
+export { getSystemHealth, type ProjectHealthMap, type HealthCheckRecord } from './d1';
+
+// Analytics Engine client
+export {
+  queryAnalyticsEngine,
+  selectFromAnalytics,
+  AnalyticsEngineError,
+  type AnalyticsEngineConfig,
+  type QueryResult,
+  type AnalyticsEngineErrorCode,
+  type AnalyticsEngineResponse,
+} from './analytics';
+
+{{#if isFull}}
+// GraphQL client and types (Full tier)
+export {
+  CloudflareGraphQL,
+  type TimePeriod,
+  type DateRange,
+  type CustomDateRangeParams,
+  type CompareMode,
+  type WorkersMetrics,
+  type D1Metrics,
+  type KVMetrics,
+  type R2Metrics,
+  type DOMetrics,
+  type VectorizeInfo,
+  type AIGatewayMetrics,
+  type PagesMetrics,
+  type SparklinePoint,
+  type SparklineData,
+  type WorkersErrorBreakdown,
+  type QueuesMetrics,
+  type CacheAnalytics,
+  type PeriodComparison,
+  type AccountUsage,
+  type EnhancedAccountUsage,
+  type WorkersAIMetrics,
+  type WorkersAISummary,
+  type AIGatewaySummary,
+  type DailyCostBreakdown,
+  type DailyCostData,
+  type CloudflareSubscription,
+  type WorkersPaidPlanInclusions,
+  type CloudflareBillingProfile,
+  type CloudflareAccountSubscriptions,
+} from './graphql';
+
+// Alerting service and types
+export {
+  getSeverityColour,
+  getSeverityEmoji,
+  formatPercentage,
+  generateAlertKey,
+  shouldSendAlert,
+  buildSlackMessage,
+  buildSummarySlackMessage,
+  sendSlackAlert,
+  evaluateWarning,
+  buildEmailHtml,
+  buildEmailText,
+  type CostSpikeAlert,
+  type AlertResult,
+  type SlackMessage,
+} from './alerting';
+
+// Project registry - D1-backed resource-to-project mapping
+export {
+  getProjects,
+  getProject,
+  identifyProjectFromRegistry,
+  getProjectResources,
+  getProjectResourcesByType,
+  getResourceCountsByProject,
+  getResourceCountByType,
+  upsertResourceMapping,
+  deleteResourceMapping,
+  createProject,
+  updateProjectStatus,
+  clearRegistryCache,
+  type Project,
+  type ResourceMapping,
+  type ResourceType,
+} from './project-registry';
+{{/if}}

package/templates/shared/dashboard/src/lib/infrastructure/types.ts

@@ -0,0 +1,116 @@
+/**
+ * Infrastructure Types
+ * TypeScript types for infrastructure monitoring dashboard
+ */
+
+export type ServiceStatus = 'deployed' | 'development' | 'deprecated' | 'paused';
+export type ServiceType = 'worker' | 'vps-app' | 'd1' | 'kv' | 'r2' | 'vectorize' | 'queue';
+export type MonitorStatus = 'up' | 'down' | 'paused' | 'unknown';
+export type HealthcheckStatus = 'up' | 'down' | 'grace' | 'paused' | 'new';
+
+export interface Service {
+  id: string;
+  name: string;
+  type: ServiceType;
+  status: ServiceStatus;
+  project: string;
+  scriptName?: string;
+  schedule?: string | null;
+  lastDeployed?: number | null;
+  endpoint?: string;
+}
+
+export interface ServiceRegistryStats {
+  total: number;
+  byStatus: Record<ServiceStatus, number>;
+  byType: Record<ServiceType, number>;
+  byProject: Record<string, number>;
+}
+
+export interface UptimeMonitor {
+  id: string;
+  name: string;
+  url: string;
+  status: MonitorStatus;
+  uptimeRatio: number; // Last 7 days (from Gatus)
+  responseTime: number; // Latest ms
+  lastCheckAt: number;
+  createdAt: number;
+}
+
+export interface HealthcheckJob {
+  id: string;
+  name: string;
+  slug: string;
+  status: HealthcheckStatus;
+  lastPing: number | null;
+  nextPing: number | null;
+  period: number; // seconds
+  grace: number; // seconds
+  nPings: number;
+  tags: string[];
+  // Optional flip summary (populated by enhanced API)
+  recentFlips?: FlipEvent[];
+  flipsToday?: number;
+  lastFailure?: number | null;
+}
+
+/**
+ * A flip represents a status change (up→down or down→up)
+ * Retrieved from Gatus events API
+ */
+export interface FlipEvent {
+  timestamp: number; // Unix timestamp
+  up: boolean; // true = went up, false = went down
+}
+
+/**
+ * A response time data point from Gatus
+ */
+export interface ResponseTimeDataPoint {
+  timestamp: number; // Unix timestamp
+  value: number; // Response time in ms
+}
+
+/**
+ * Response time stats summary
+ */
+export interface ResponseTimeStats {
+  avg: number;
+  min: number;
+  max: number;
+  trend: 'improving' | 'stable' | 'degrading';
+}
+
+export interface Alert {
+  id: string;
+  type: string;
+  severity: 'info' | 'warning' | 'critical';
+  source: string;
+  message: string;
+  createdAt: number;
+  acknowledgedAt: number | null;
+  resolvedAt: number | null;
+  metadata?: Record<string, unknown>;
+}
+
+export interface InfrastructureStats {
+  services: ServiceRegistryStats;
+  monitors: {
+    total: number;
+    up: number;
+    down: number;
+    averageUptime: number;
+  };
+  healthchecks: {
+    total: number;
+    up: number;
+    down: number;
+    grace: number;
+  };
+  alerts: {
+    total: number;
+    unacknowledged: number;
+    critical: number;
+  };
+}

package/templates/shared/dashboard/src/lib/usage/fetchWithDedup.ts

@@ -0,0 +1,101 @@
+/**
+ * Fetch with Request Deduplication
+ *
+ * Prevents duplicate API calls by:
+ * 1. Deduplicating concurrent requests to the same URL
+ * 2. Caching responses for a short TTL
+ *
+ * This is used by the unified dashboard components to prevent
+ * multiple components from making redundant API calls.
+ */
+
+interface CacheEntry<T> {
+  data: T;
+  expiresAt: number;
+}
+
+// In-flight request tracking (prevents concurrent duplicate requests)
+const pendingRequests = new Map<string, Promise<Response>>();
+
+// Response cache with TTL
+const responseCache = new Map<string, CacheEntry<unknown>>();
+
+// Default cache TTL: 5 seconds (short enough to stay fresh, long enough to dedupe)
+const DEFAULT_CACHE_TTL = 5000;
+
+/**
+ * Fetch with automatic request deduplication and short-term caching
+ */
+export async function fetchWithDedup<T>(
+  url: string,
+  options: RequestInit = {},
+  cacheTtl: number = DEFAULT_CACHE_TTL
+): Promise<T> {
+  const cacheKey = `${options.method || 'GET'}:${url}`;
+
+  // Check response cache first
+  const cached = responseCache.get(cacheKey);
+  if (cached && Date.now() < cached.expiresAt) {
+    return cached.data as T;
+  }
+
+  // Check for in-flight request
+  const pending = pendingRequests.get(cacheKey);
+  if (pending) {
+    const response = await pending;
+    const data = await response.clone().json();
+    return data as T;
+  }
+
+  // Create new request
+  const request = fetch(url, {
+    credentials: 'include',
+    ...options,
+  });
+
+  pendingRequests.set(cacheKey, request);
+
+  try {
+    const response = await request;
+    pendingRequests.delete(cacheKey);
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}`);
+    }
+
+    const data = await response.json();
+
+    // Cache the response
+    responseCache.set(cacheKey, {
+      data,
+      expiresAt: Date.now() + cacheTtl,
+    });
+
+    return data as T;
+  } catch (error) {
+    pendingRequests.delete(cacheKey);
+    throw error;
+  }
+}
+
+/**
+ * Clear the response cache (useful for forced refresh)
+ */
+export function clearFetchCache(urlPattern?: string): void {
+  if (urlPattern) {
+    for (const key of responseCache.keys()) {
+      if (key.includes(urlPattern)) {
+        responseCache.delete(key);
+      }
+    }
+  } else {
+    responseCache.clear();
+  }
+}
+
+/**
+ * Check if a URL is currently being fetched
+ */
+export function isFetching(url: string): boolean {
+  return pendingRequests.has(`GET:${url}`);
+}

package/templates/shared/dashboard/src/lib/usage/index.ts.hbs

@@ -0,0 +1,12 @@
+/**
+ * Usage Library Exports
+ *
+ * Centralised exports for usage-related configuration and utilities.
+ */
+
+export * from './fetchWithDedup';
+
+{{#if isFull}}
+export * from './allowance-config';
+export * from './providers';
+{{/if}}