@littlebearapps/platform-consumer-sdk 1.0.0

package/src/errors.ts

@@ -0,0 +1,285 @@
+/// <reference types="@cloudflare/workers-types" />
+
+/**
+ * Platform SDK Errors
+ *
+ * Error tracking and categorisation utilities for the Platform SDK.
+ * Integrates with telemetry to report errors to the platform-usage consumer.
+ *
+ * @example
+ * ```typescript
+ * import { withFeatureBudget, reportError, completeTracking } from './lib/platform-sdk';
+ *
+ * const trackedEnv = withFeatureBudget(env, 'my-app:api:users', { ctx });
+ * try {
+ *   await riskyOperation(trackedEnv);
+ * } catch (error) {
+ *   reportError(trackedEnv, error);
+ *   // Handle error...
+ * }
+ * await completeTracking(trackedEnv); // Errors included in telemetry
+ * ```
+ */
+
+import type { ErrorCategory, MetricsAccumulator } from './types';
+import { CircuitBreakerError } from './types';
+import { getTelemetryContext } from './telemetry';
+import { createLogger, type Logger } from './logging';
+import { TimeoutError } from './timeout';
+
+// =============================================================================
+// MODULE LOGGER (lazy-initialized to avoid global scope crypto calls)
+// =============================================================================
+
+let _log: Logger | null = null;
+function getLog(): Logger {
+  if (!_log) {
+    _log = createLogger({
+      worker: 'platform-sdk',
+      featureId: 'platform:sdk:errors',
+    });
+  }
+  return _log;
+}
+
+// =============================================================================
+// ERROR CATEGORISATION
+// =============================================================================
+
+/**
+ * Categorise an error based on its type and message.
+ * Uses error name, message patterns, and known error types.
+ */
+export function categoriseError(error: unknown): ErrorCategory {
+  if (error instanceof CircuitBreakerError) {
+    return 'CIRCUIT_BREAKER';
+  }
+
+  if (error instanceof TimeoutError) {
+    return 'TIMEOUT';
+  }
+
+  if (error instanceof Error) {
+    const name = error.name.toLowerCase();
+    const message = error.message.toLowerCase();
+
+    // Auth errors
+    if (
+      name.includes('auth') ||
+      name.includes('unauthorized') ||
+      name.includes('forbidden') ||
+      message.includes('unauthorized') ||
+      message.includes('forbidden') ||
+      message.includes('401') ||
+      message.includes('403')
+    ) {
+      return 'AUTH';
+    }
+
+    // Rate limit errors
+    if (
+      name.includes('ratelimit') ||
+      message.includes('rate limit') ||
+      message.includes('too many requests') ||
+      message.includes('429')
+    ) {
+      return 'RATE_LIMIT';
+    }
+
+    // Network/timeout errors
+    if (
+      name.includes('timeout') ||
+      name.includes('network') ||
+      name.includes('fetch') ||
+      message.includes('timeout') ||
+      message.includes('network') ||
+      message.includes('econnrefused') ||
+      message.includes('enotfound') ||
+      message.includes('socket hang up')
+    ) {
+      return 'NETWORK';
+    }
+
+    // Validation errors
+    if (
+      name.includes('validation') ||
+      name.includes('schema') ||
+      name.includes('parse') ||
+      message.includes('invalid') ||
+      message.includes('required') ||
+      message.includes('expected')
+    ) {
+      return 'VALIDATION';
+    }
+
+    // D1 errors
+    if (name.includes('d1') || message.includes('d1_error') || message.includes('sqlite')) {
+      return 'D1_ERROR';
+    }
+
+    // KV errors
+    if (name.includes('kv') || message.includes('kv_error') || message.includes('namespace')) {
+      return 'KV_ERROR';
+    }
+
+    // Queue errors
+    if (name.includes('queue') || message.includes('queue_error')) {
+      return 'QUEUE_ERROR';
+    }
+
+    // External API errors (by common status codes)
+    if (
+      message.includes('500') ||
+      message.includes('502') ||
+      message.includes('503') ||
+      message.includes('504')
+    ) {
+      return 'EXTERNAL_API';
+    }
+  }
+
+  return 'INTERNAL';
+}
+
+/**
+ * Extract error code from an error if available.
+ */
+export function extractErrorCode(error: unknown): string | undefined {
+  if (error && typeof error === 'object') {
+    const errorObj = error as Record<string, unknown>;
+    if (typeof errorObj.code === 'string') {
+      return errorObj.code;
+    }
+    if (typeof errorObj.errno === 'string') {
+      return errorObj.errno;
+    }
+    if (typeof errorObj.status === 'number') {
+      return `HTTP_${errorObj.status}`;
+    }
+  }
+  return undefined;
+}
+
+// =============================================================================
+// ERROR TRACKING
+// =============================================================================
+
+/**
+ * Track an error in the metrics accumulator.
+ * Used internally by proxy wrappers and reportError.
+ */
+export function trackError(metrics: MetricsAccumulator, error: unknown): void {
+  metrics.errorCount += 1;
+  metrics.lastErrorCategory = categoriseError(error);
+
+  const code = extractErrorCode(error);
+  if (code && !metrics.errorCodes.includes(code)) {
+    // Keep at most 10 unique error codes
+    if (metrics.errorCodes.length < 10) {
+      metrics.errorCodes.push(code);
+    }
+  }
+}
+
+/**
+ * Report an error for a tracked environment.
+ * Call this when you catch an error that should be included in telemetry.
+ *
+ * @param env - The tracked environment from withFeatureBudget
+ * @param error - The error to report
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await riskyOperation(trackedEnv);
+ * } catch (error) {
+ *   reportError(trackedEnv, error);
+ *   throw error; // Re-throw or handle
+ * }
+ * ```
+ */
+export function reportError(env: object, error: unknown): void {
+  const context = getTelemetryContext(env);
+  if (!context) {
+    getLog().warn('reportError called without telemetry context');
+    return;
+  }
+
+  trackError(context.metrics, error);
+}
+
+/**
+ * Report an error with explicit category and code.
+ * Use when you know the error type better than automatic categorisation.
+ *
+ * @param env - The tracked environment from withFeatureBudget
+ * @param category - Error category
+ * @param code - Optional error code
+ *
+ * @example
+ * ```typescript
+ * if (!response.ok) {
+ *   reportErrorExplicit(trackedEnv, 'EXTERNAL_API', `HTTP_${response.status}`);
+ * }
+ * ```
+ */
+export function reportErrorExplicit(env: object, category: ErrorCategory, code?: string): void {
+  const context = getTelemetryContext(env);
+  if (!context) {
+    getLog().warn('reportErrorExplicit called without telemetry context');
+    return;
+  }
+
+  context.metrics.errorCount += 1;
+  context.metrics.lastErrorCategory = category;
+
+  if (code && !context.metrics.errorCodes.includes(code)) {
+    if (context.metrics.errorCodes.length < 10) {
+      context.metrics.errorCodes.push(code);
+    }
+  }
+}
+
+/**
+ * Check if a tracked environment has recorded any errors.
+ */
+export function hasErrors(env: object): boolean {
+  const context = getTelemetryContext(env);
+  return context ? context.metrics.errorCount > 0 : false;
+}
+
+/**
+ * Get the error count for a tracked environment.
+ */
+export function getErrorCount(env: object): number {
+  const context = getTelemetryContext(env);
+  return context?.metrics.errorCount ?? 0;
+}
+
+// =============================================================================
+// ERROR WRAPPER
+// =============================================================================
+
+/**
+ * Wrap an async function to automatically track errors.
+ * Errors are tracked and then re-thrown.
+ *
+ * @param env - The tracked environment from withFeatureBudget
+ * @param fn - The async function to wrap
+ * @returns The result of the function
+ *
+ * @example
+ * ```typescript
+ * const result = await withErrorTracking(trackedEnv, async () => {
+ *   return await riskyOperation();
+ * });
+ * ```
+ */
+export async function withErrorTracking<T>(env: object, fn: () => Promise<T>): Promise<T> {
+  try {
+    return await fn();
+  } catch (error) {
+    reportError(env, error);
+    throw error;
+  }
+}

package/src/features.ts

@@ -0,0 +1,149 @@
+/**
+ * Platform Feature IDs
+ *
+ * Defines all feature identifiers for Platform's own workers.
+ * Format: 'platform:<category>:<feature>'
+ *
+ * Categories:
+ * - ingest: Data ingestion workers (GitHub, Stripe, Logger)
+ * - connector: External service connectors (Stripe, Ads, GA4, Plausible)
+ * - monitor: Monitoring workers (Alert Router, Cost Spike, Observer, GitHub)
+ * - discovery: Discovery workers (Topology)
+ * - test: Test workers (Ingest, Query, Healthcheck)
+ */
+
+import type { FeatureId } from './types';
+
+// =============================================================================
+// INGEST FEATURES (3)
+// Workers that ingest data from external sources
+// =============================================================================
+
+/** GitHub webhook ingestion (issues, PRs, deployments) */
+export const INGEST_GITHUB: FeatureId = 'platform:ingest:github';
+
+/** Stripe webhook ingestion (payments, subscriptions) */
+export const INGEST_STRIPE: FeatureId = 'platform:ingest:stripe';
+
+/** Log ingestion from external sources */
+export const INGEST_LOGGER: FeatureId = 'platform:ingest:logger';
+
+// =============================================================================
+// CONNECTOR FEATURES (4)
+// Workers that connect to external analytics services
+// =============================================================================
+
+/** Stripe connector for billing data */
+export const CONNECTOR_STRIPE: FeatureId = 'platform:connector:stripe';
+
+/** Google Ads connector for ad performance data */
+export const CONNECTOR_ADS: FeatureId = 'platform:connector:ads';
+
+/** Google Analytics 4 connector */
+export const CONNECTOR_GA4: FeatureId = 'platform:connector:ga4';
+
+/** Plausible Analytics connector */
+export const CONNECTOR_PLAUSIBLE: FeatureId = 'platform:connector:plausible';
+
+// =============================================================================
+// MONITOR FEATURES (4)
+// Workers that monitor system health and costs
+// =============================================================================
+
+/** Alert router - routes alerts to Slack, creates GitHub issues */
+export const MONITOR_ALERT_ROUTER: FeatureId = 'platform:monitor:alert-router';
+
+/** Cost spike alerter - detects cost anomalies */
+export const MONITOR_COST_SPIKE: FeatureId = 'platform:monitor:cost-spike';
+
+/** Platform observer - watches GitHub webhooks for circuit breaker state */
+export const MONITOR_OBSERVER: FeatureId = 'platform:monitor:observer';
+
+/** GitHub monitor - monitors GitHub API events */
+export const MONITOR_GITHUB: FeatureId = 'platform:monitor:github';
+
+/** SDK integration auditor - weekly triangulation audits */
+export const MONITOR_AUDITOR: FeatureId = 'platform:monitor:auditor';
+
+/** Pattern discovery - AI-assisted transient error pattern detection */
+export const MONITOR_PATTERN_DISCOVERY: FeatureId = 'platform:monitor:pattern-discovery';
+
+// =============================================================================
+// DISCOVERY FEATURES (1)
+// Workers that discover infrastructure topology
+// =============================================================================
+
+/** Topology discovery - discovers services, health, deployments */
+export const DISCOVERY_TOPOLOGY: FeatureId = 'platform:discovery:topology';
+
+// =============================================================================
+// TEST FEATURES (3)
+// Workers used for testing Platform SDK and infrastructure
+// Note: test-client is already integrated with 'test-client:validation:sdk-test'
+// =============================================================================
+
+/** Test ingest worker */
+export const TEST_INGEST: FeatureId = 'platform:test:ingest';
+
+/** Test query worker */
+export const TEST_QUERY: FeatureId = 'platform:test:query';
+
+/** Test healthcheck worker */
+export const TEST_HEALTHCHECK: FeatureId = 'platform:test:healthcheck';
+
+// =============================================================================
+// HEARTBEAT FEATURE
+// Used for health checks across all Platform workers
+// =============================================================================
+
+/** Generic heartbeat/health check feature */
+export const HEARTBEAT_HEALTH: FeatureId = 'platform:heartbeat:health';
+
+// =============================================================================
+// EMAIL FEATURES
+// Email system health monitoring
+// =============================================================================
+
+/** Email system health check - per-brand validation */
+export const EMAIL_HEALTHCHECK: FeatureId = 'platform:email:healthcheck';
+
+// =============================================================================
+// ALL FEATURES (for budgets.yaml generation)
+// =============================================================================
+
+export const PLATFORM_FEATURES = {
+  // Ingest
+  INGEST_GITHUB,
+  INGEST_STRIPE,
+  INGEST_LOGGER,
+  // Connectors
+  CONNECTOR_STRIPE,
+  CONNECTOR_ADS,
+  CONNECTOR_GA4,
+  CONNECTOR_PLAUSIBLE,
+  // Monitors
+  MONITOR_ALERT_ROUTER,
+  MONITOR_COST_SPIKE,
+  MONITOR_OBSERVER,
+  MONITOR_GITHUB,
+  MONITOR_AUDITOR,
+  MONITOR_PATTERN_DISCOVERY,
+  // Discovery
+  DISCOVERY_TOPOLOGY,
+  // Test
+  TEST_INGEST,
+  TEST_QUERY,
+  TEST_HEALTHCHECK,
+  // Heartbeat
+  HEARTBEAT_HEALTH,
+  // Email
+  EMAIL_HEALTHCHECK,
+} as const;
+
+/**
+ * Get all Platform feature IDs as an array.
+ * Useful for iterating over all features.
+ */
+export function getAllPlatformFeatures(): FeatureId[] {
+  return Object.values(PLATFORM_FEATURES);
+}

package/src/heartbeat.ts

@@ -0,0 +1,27 @@
+/**
+ * Gatus external endpoint heartbeat helper.
+ *
+ * All Platform cron workers call this on success/failure to push
+ * heartbeat status to the self-hosted Gatus instance at
+ * status.littlebearapps.com.
+ *
+ * Gatus external endpoints accept:
+ *   POST {url}?success=true|false
+ *   Authorization: Bearer {token}
+ *
+ * @see docs/quickrefs/monitoring.md
+ */
+export function pingHeartbeat(
+  ctx: ExecutionContext,
+  url: string | undefined,
+  token: string | undefined,
+  success: boolean
+): void {
+  if (!url || !token) return;
+  ctx.waitUntil(
+    fetch(`${url}?success=${success}`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${token}` },
+    }).catch(() => {})
+  );
+}