@littlebearapps/platform-admin-sdk 1.5.0 → 2.1.0

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

@@ -0,0 +1,141 @@
+/**
+ * Infrastructure API Client
+ * Client functions for fetching infrastructure data
+ */
+
+import type {
+  Service,
+  ServiceRegistryStats,
+  UptimeMonitor,
+  HealthcheckJob,
+  Alert,
+  InfrastructureStats,
+  FlipEvent,
+  ResponseTimeDataPoint,
+  ResponseTimeStats,
+} from './types';
+
+/**
+ * Fetch all services from the service registry
+ */
+export async function fetchServices(): Promise<Service[]> {
+  const response = await fetch('/api/infrastructure/services');
+  if (!response.ok) {
+    throw new Error(`Failed to fetch services: ${response.statusText}`);
+  }
+  const data = (await response.json()) as { services?: Service[] };
+  return data.services || [];
+}
+
+/**
+ * Fetch service registry statistics
+ */
+export async function fetchServiceStats(): Promise<ServiceRegistryStats> {
+  const response = await fetch('/api/infrastructure/services/stats');
+  if (!response.ok) {
+    throw new Error(`Failed to fetch service stats: ${response.statusText}`);
+  }
+  return response.json();
+}
+
+/**
+ * Fetch Gatus uptime monitors
+ */
+export async function fetchUptimeMonitors(): Promise<UptimeMonitor[]> {
+  const response = await fetch('/api/infrastructure/uptime');
+  if (!response.ok) {
+    throw new Error(`Failed to fetch uptime monitors: ${response.statusText}`);
+  }
+  const data = (await response.json()) as { monitors?: UptimeMonitor[] };
+  return data.monitors || [];
+}
+
+/**
+ * Fetch Gatus heartbeats
+ */
+export async function fetchHealthchecks(): Promise<HealthcheckJob[]> {
+  const response = await fetch('/api/infrastructure/healthchecks');
+  if (!response.ok) {
+    throw new Error(`Failed to fetch healthchecks: ${response.statusText}`);
+  }
+  const data = (await response.json()) as { checks?: HealthcheckJob[] };
+  return data.checks || [];
+}
+
+/**
+ * Flip history response from the API
+ */
+export interface FlipsResponse {
+  flips: FlipEvent[];
+  checkId: string;
+  cached: boolean;
+  flipsToday: number;
+  lastFailure: number | null;
+}
+
+/**
+ * Fetch flip history (status changes) for a specific healthcheck
+ */
+export async function fetchHealthcheckFlips(checkId: string): Promise<FlipsResponse> {
+  const response = await fetch(`/api/infrastructure/healthchecks/${checkId}/flips`);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch flips: ${response.statusText}`);
+  }
+  return response.json();
+}
+
+/**
+ * Fetch recent alerts from D1
+ */
+export async function fetchAlerts(limit: number = 20): Promise<Alert[]> {
+  const response = await fetch(`/api/infrastructure/alerts?limit=${limit}`);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch alerts: ${response.statusText}`);
+  }
+  const data = (await response.json()) as { alerts?: Alert[] };
+  return data.alerts || [];
+}
+
+/**
+ * Acknowledge an alert
+ */
+export async function acknowledgeAlert(id: string): Promise<void> {
+  const response = await fetch(`/api/infrastructure/alerts/${id}/acknowledge`, {
+    method: 'POST',
+  });
+  if (!response.ok) {
+    throw new Error(`Failed to acknowledge alert: ${response.statusText}`);
+  }
+}
+
+/**
+ * Fetch combined infrastructure statistics
+ */
+export async function fetchInfrastructureStats(): Promise<InfrastructureStats> {
+  const response = await fetch('/api/infrastructure/stats');
+  if (!response.ok) {
+    throw new Error(`Failed to fetch infrastructure stats: ${response.statusText}`);
+  }
+  return response.json();
+}
+
+/**
+ * Response times response from the API
+ */
+export interface ResponseTimesResponse {
+  dataPoints: ResponseTimeDataPoint[];
+  monitorId: string;
+  cached: boolean;
+  stats: ResponseTimeStats;
+}
+
+/**
+ * Fetch response time history for a specific Gatus monitor
+ */
+export async function fetchUptimeResponseTimes(monitorId: string): Promise<ResponseTimesResponse> {
+  const response = await fetch(`/api/infrastructure/uptime/${monitorId}/response-times`);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch response times: ${response.statusText}`);
+  }
+  return response.json();
+}

package/templates/standard/dashboard/src/lib/infrastructure/gatus.ts.hbs

@@ -0,0 +1,112 @@
+/**
+ * Gatus API Client
+ * Shared fetch + KV cache layer for Gatus self-hosted monitoring
+ * https://{{gatusUrl}}
+ */
+
+/** A single check result from Gatus */
+export interface GatusResult {
+  status: number;
+  hostname: string;
+  duration: number; // nanoseconds
+  success: boolean;
+  timestamp: string; // ISO 8601
+  errors: string[];
+  conditionResults: Array<{
+    condition: string;
+    success: boolean;
+  }>;
+}
+
+/** A status transition event (only on single-endpoint responses) */
+export interface GatusEvent {
+  type: 'START' | 'HEALTHY' | 'UNHEALTHY';
+  timestamp: string; // ISO 8601
+}
+
+/**
+ * A single endpoint status from Gatus.
+ * Bulk endpoint (/statuses) returns only results.
+ * Single endpoint (/{key}/statuses) also includes events.
+ */
+export interface GatusEndpointStatus {
+  name: string;
+  group: string;
+  key: string;
+  results: GatusResult[];
+  events?: GatusEvent[]; // Only present on single-endpoint responses
+}
+
+/** Calculate uptime % from results (success count / total count * 100) */
+export function calculateUptimeFromResults(results: GatusResult[]): number {
+  if (results.length === 0) return 0;
+  const successes = results.filter((r) => r.success).length;
+  return (successes / results.length) * 100;
+}
+
+const CACHE_KEY = 'GATUS_ALL_STATUSES';
+const CACHE_TTL = 300; // 5 minutes
+
+/**
+ * Fetch all endpoint statuses from Gatus, with KV caching.
+ * CF Access is bypassed on /api/* so no auth is needed.
+ */
+export async function fetchAllGatusStatuses(
+  gatusUrl: string,
+  kv?: KVNamespace
+): Promise<GatusEndpointStatus[]> {
+  // Check cache first
+  if (kv) {
+    const cached = await kv.get(CACHE_KEY, 'json');
+    if (cached && Array.isArray(cached)) {
+      return cached as GatusEndpointStatus[];
+    }
+  }
+
+  const response = await fetch(`${gatusUrl}/api/v1/endpoints/statuses`);
+  if (!response.ok) {
+    throw new Error(`Gatus API error: ${response.status}`);
+  }
+
+  const data = (await response.json()) as GatusEndpointStatus[];
+
+  // Cache the result
+  if (kv) {
+    await kv.put(CACHE_KEY, JSON.stringify(data), { expirationTtl: CACHE_TTL });
+  }
+
+  return data;
+}
+
+/**
+ * Fetch a single endpoint's status from Gatus, with KV caching.
+ */
+export async function fetchGatusEndpoint(
+  gatusUrl: string,
+  key: string,
+  kv?: KVNamespace
+): Promise<GatusEndpointStatus> {
+  const cacheKey = `GATUS_ENDPOINT:${key}`;
+
+  // Check cache first
+  if (kv) {
+    const cached = await kv.get(cacheKey, 'json');
+    if (cached) {
+      return cached as GatusEndpointStatus;
+    }
+  }
+
+  const response = await fetch(`${gatusUrl}/api/v1/endpoints/${key}/statuses`);
+  if (!response.ok) {
+    throw new Error(`Gatus API error for ${key}: ${response.status}`);
+  }
+
+  const data = (await response.json()) as GatusEndpointStatus;
+
+  // Cache the result
+  if (kv) {
+    await kv.put(cacheKey, JSON.stringify(data), { expirationTtl: CACHE_TTL });
+  }
+
+  return data;
+}

package/templates/standard/dashboard/src/lib/services/proxy/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Service Binding Proxy Module
+ *
+ * Exports utilities for proxying requests from Pages Functions to Workers
+ * via Cloudflare Service Bindings.
+ *
+ * @module services/proxy
+ * @created 2025-12-04
+ * @task task-159 - Implement thin proxy pattern for Brand Copilot Worker APIs
+ */
+
+export { proxyToService, proxyToServiceWithMetrics, createErrorResponse } from './proxy';
+
+export type {
+  Fetcher,
+  ProxyOptions,
+  ProxyErrorResponse,
+  ProxyErrorCode,
+  ProxyResult,
+} from './types';

package/templates/standard/dashboard/src/lib/services/proxy/proxy.ts

@@ -0,0 +1,244 @@
+/**
+ * Service Binding Proxy Utility
+ *
+ * Generic proxy function for forwarding requests from Pages Functions
+ * to Workers via service bindings. Handles error handling, retries,
+ * and observability.
+ *
+ * @module services/proxy/proxy
+ * @created 2025-12-04
+ * @task task-159 - Implement thin proxy pattern for Brand Copilot Worker APIs
+ */
+
+import type {
+  Fetcher,
+  ProxyOptions,
+  ProxyErrorResponse,
+  ProxyErrorCode,
+  ProxyResult,
+} from './types';
+
+/**
+ * Default proxy options
+ */
+const DEFAULT_OPTIONS: Required<Omit<ProxyOptions, 'onError' | 'requestId'>> = {
+  retries: 1,
+  retryDelay: 100,
+  logTiming: true,
+};
+
+/**
+ * Proxy a request to a Worker via service binding
+ *
+ * @param service - The service binding (Fetcher) to call
+ * @param request - The incoming request to proxy
+ * @param options - Optional configuration
+ * @returns The response from the Worker
+ *
+ * @example
+ * ```typescript
+ * const response = await proxyToService(
+ *   env.BRAND_COPILOT,
+ *   request,
+ *   { requestId: 'abc-123' }
+ * );
+ * ```
+ */
+export async function proxyToService(
+  service: Fetcher,
+  request: Request,
+  options?: ProxyOptions
+): Promise<Response> {
+  const result = await proxyToServiceWithMetrics(service, request, options);
+  return result.response;
+}
+
+/**
+ * Proxy a request to a Worker with full metrics
+ *
+ * @param service - The service binding (Fetcher) to call
+ * @param request - The incoming request to proxy
+ * @param options - Optional configuration
+ * @returns ProxyResult with response and metrics
+ */
+export async function proxyToServiceWithMetrics(
+  service: Fetcher,
+  request: Request,
+  options?: ProxyOptions
+): Promise<ProxyResult> {
+  const startTime = performance.now();
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  const requestId = opts.requestId ?? generateRequestId();
+
+  let lastError: Error | null = null;
+  let retriesUsed = 0;
+
+  // Create proxy request with filtered headers
+  const proxyRequest = createProxyRequest(request, requestId);
+
+  for (let attempt = 0; attempt <= opts.retries; attempt++) {
+    try {
+      const response = await service.fetch(proxyRequest.clone());
+      const duration = performance.now() - startTime;
+
+      if (opts.logTiming) {
+        logProxyRequest(request, response, duration, requestId, retriesUsed);
+      }
+
+      return {
+        response,
+        duration_ms: Math.round(duration),
+        request_id: requestId,
+        retries_used: retriesUsed,
+      };
+    } catch (error) {
+      lastError = error as Error;
+      retriesUsed = attempt + 1;
+
+      if (attempt < opts.retries) {
+        await sleep(opts.retryDelay);
+      }
+    }
+  }
+
+  // All retries exhausted
+  const duration = performance.now() - startTime;
+
+  if (opts.logTiming) {
+    console.error(
+      `[PROXY] ${request.method} ${new URL(request.url).pathname} → ERROR after ${retriesUsed} attempts (${Math.round(duration)}ms): ${lastError?.message}`
+    );
+  }
+
+  // Allow custom error handling
+  if (options?.onError) {
+    const customResponse = options.onError(lastError!);
+    if (customResponse) {
+      return {
+        response: customResponse,
+        duration_ms: Math.round(duration),
+        request_id: requestId,
+        retries_used: retriesUsed,
+      };
+    }
+  }
+
+  // Default error response
+  const errorResponse = createErrorResponse(
+    'SERVICE_UNAVAILABLE',
+    'The backend service is temporarily unavailable',
+    requestId,
+    lastError?.message
+  );
+
+  return {
+    response: errorResponse,
+    duration_ms: Math.round(duration),
+    request_id: requestId,
+    retries_used: retriesUsed,
+  };
+}
+
+/**
+ * Create a proxy request with filtered headers
+ *
+ * Service bindings ignore the hostname, so we use a dummy base URL
+ * to satisfy the Request constructor requirement for absolute URLs.
+ * We preserve the original host via X-Forwarded-* headers for OAuth flows.
+ */
+function createProxyRequest(request: Request, requestId: string): Request {
+  const url = new URL(request.url);
+  const path = url.pathname + url.search;
+
+  // Service bindings ignore hostname - use dummy base for valid URL
+  const proxyUrl = new URL(path, 'https://service.internal');
+
+  // Filter headers - remove Cloudflare-specific ones
+  const headers = new Headers();
+  request.headers.forEach((value, key) => {
+    // Skip headers that shouldn't be proxied
+    if (
+      !key.startsWith('cf-') &&
+      key !== 'host' &&
+      key !== 'x-forwarded-for' &&
+      key !== 'x-real-ip'
+    ) {
+      headers.set(key, value);
+    }
+  });
+
+  // Add request ID for correlation
+  headers.set('x-request-id', requestId);
+
+  // Preserve original host/protocol for OAuth callbacks and URL construction
+  // These headers allow the Worker to know the original request origin
+  headers.set('x-forwarded-host', url.host);
+  headers.set('x-forwarded-proto', url.protocol.replace(':', ''));
+
+  return new Request(proxyUrl.toString(), {
+    method: request.method,
+    headers,
+    body: request.body,
+    // Don't follow redirects - return them to the browser for OAuth flows
+    redirect: 'manual',
+    // @ts-expect-error - duplex is required for streaming bodies
+    duplex: 'half',
+  });
+}
+
+/**
+ * Create a standardised error response
+ */
+export function createErrorResponse(
+  code: ProxyErrorCode,
+  message: string,
+  requestId?: string,
+  details?: string
+): Response {
+  const body: ProxyErrorResponse = {
+    success: false,
+    error: message,
+    code,
+    ...(requestId && { request_id: requestId }),
+    ...(details && { details }),
+  };
+
+  return new Response(JSON.stringify(body), {
+    status: code === 'TIMEOUT' ? 504 : 503,
+    headers: {
+      'Content-Type': 'application/json',
+      ...(requestId && { 'x-request-id': requestId }),
+    },
+  });
+}
+
+/**
+ * Generate a unique request ID
+ */
+function generateRequestId(): string {
+  return crypto.randomUUID();
+}
+
+/**
+ * Log a proxy request
+ */
+function logProxyRequest(
+  request: Request,
+  response: Response,
+  durationMs: number,
+  requestId: string,
+  retries: number
+): void {
+  const url = new URL(request.url);
+  const retryInfo = retries > 0 ? ` (${retries} retries)` : '';
+  console.log(
+    `[PROXY] ${request.method} ${url.pathname} → ${response.status} (${Math.round(durationMs)}ms)${retryInfo} [${requestId.slice(0, 8)}]`
+  );
+}
+
+/**
+ * Sleep for a given number of milliseconds
+ */
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/templates/standard/dashboard/src/lib/services/proxy/types.ts

@@ -0,0 +1,81 @@
+/**
+ * Service Binding Proxy Types
+ *
+ * Type definitions for service binding proxy utilities.
+ * Used for proxying requests from Pages Functions to Workers.
+ *
+ * @module services/proxy/types
+ * @created 2025-12-04
+ * @task task-159 - Implement thin proxy pattern for Brand Copilot Worker APIs
+ */
+
+/**
+ * Cloudflare Service Binding Fetcher interface
+ * Represents a service binding that can be used to call another Worker
+ */
+export interface Fetcher {
+  fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+}
+
+/**
+ * Options for the proxy function
+ */
+export interface ProxyOptions {
+  /**
+   * Maximum number of retries on failure
+   * @default 1
+   */
+  retries?: number;
+
+  /**
+   * Delay between retries in milliseconds
+   * @default 100
+   */
+  retryDelay?: number;
+
+  /**
+   * Custom error handler - return a Response to override default error handling
+   */
+  onError?: (error: Error) => Response | null;
+
+  /**
+   * Request ID for correlation (will be generated if not provided)
+   */
+  requestId?: string;
+
+  /**
+   * Log timing information
+   * @default true
+   */
+  logTiming?: boolean;
+}
+
+/**
+ * Error response format from proxy
+ */
+export interface ProxyErrorResponse {
+  success: false;
+  error: string;
+  code: ProxyErrorCode;
+  request_id?: string;
+  details?: string;
+}
+
+/**
+ * Proxy error codes
+ */
+export type ProxyErrorCode =
+  | 'SERVICE_BINDING_ERROR'
+  | 'SERVICE_UNAVAILABLE'
+  | 'TIMEOUT'
+  | 'RETRY_EXHAUSTED';
+
+/**
+ * Result of a proxy operation
+ */
+export interface ProxyResult {
+  response: Response;
+  duration_ms: number;
+  request_id: string;
+  retries_used: number;
+}

package/templates/standard/dashboard/src/pages/api/errors/[fingerprint]/mute.ts

@@ -0,0 +1,49 @@
+import type { APIRoute } from 'astro';
+
+interface Env {
+  PLATFORM_DB?: D1Database;
+  PLATFORM_CACHE?: KVNamespace;
+}
+
+export const POST: APIRoute = async ({ locals, params }) => {
+  const env = locals.runtime?.env as Env | undefined;
+  const db = env?.PLATFORM_DB;
+  const kv = env?.PLATFORM_CACHE;
+  const fingerprint = params.fingerprint;
+
+  if (!fingerprint || !db) {
+    return new Response(JSON.stringify({ error: 'Missing fingerprint or database' }), {
+      status: 400,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  try {
+    await db
+      .prepare(
+        `UPDATE error_occurrences
+         SET labels = CASE
+           WHEN labels IS NULL THEN 'cf:muted'
+           WHEN labels NOT LIKE '%cf:muted%' THEN labels || ',cf:muted'
+           ELSE labels
+         END
+         WHERE fingerprint = ?`
+      )
+      .bind(fingerprint)
+      .run();
+
+    // Also set KV flag for error-collector to skip
+    if (kv) {
+      await kv.put(`ERROR_FINGERPRINT:${fingerprint}:MUTED`, '1', { expirationTtl: 86400 * 30 });
+    }
+
+    return new Response(JSON.stringify({ ok: true }), {
+      headers: { 'Content-Type': 'application/json' },
+    });
+  } catch {
+    return new Response(JSON.stringify({ error: 'Failed to mute error' }), {
+      status: 500,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+};

package/templates/standard/dashboard/src/pages/api/errors/[fingerprint]/resolve.ts

@@ -0,0 +1,36 @@
+import type { APIRoute } from 'astro';
+
+interface Env {
+  PLATFORM_DB?: D1Database;
+}
+
+export const POST: APIRoute = async ({ locals, params }) => {
+  const env = locals.runtime?.env as Env | undefined;
+  const db = env?.PLATFORM_DB;
+  const fingerprint = params.fingerprint;
+
+  if (!fingerprint || !db) {
+    return new Response(JSON.stringify({ error: 'Missing fingerprint or database' }), {
+      status: 400,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  try {
+    await db
+      .prepare(
+        `UPDATE error_occurrences SET status = 'resolved' WHERE fingerprint = ?`
+      )
+      .bind(fingerprint)
+      .run();
+
+    return new Response(JSON.stringify({ ok: true }), {
+      headers: { 'Content-Type': 'application/json' },
+    });
+  } catch {
+    return new Response(JSON.stringify({ error: 'Failed to resolve error' }), {
+      status: 500,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+};