@littlebearapps/platform-consumer-sdk 1.0.0

package/src/do-heartbeat.ts

@@ -0,0 +1,249 @@
+/// <reference types="@cloudflare/workers-types" />
+
+/**
+ * Platform SDK - Durable Object Heartbeat Mixin
+ *
+ * Provides alarm-based health monitoring for Durable Objects.
+ * Uses the Alarms API to send periodic heartbeats to the platform telemetry queue.
+ *
+ * @example
+ * ```typescript
+ * import { withHeartbeat } from '../lib/platform-sdk';
+ *
+ * export class MyDurableObject extends withHeartbeat(DurableObject, {
+ *   featureKey: 'scout:do:triage-workflow',
+ *   intervalMs: 5 * 60 * 1000, // 5 minutes
+ * }) {
+ *   // Existing implementation unchanged
+ * }
+ * ```
+ */
+
+import type { TelemetryMessage } from './types';
+import { createLogger, type Logger } from './logging';
+
+// =============================================================================
+// 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:do-heartbeat',
+    });
+  }
+  return _log;
+}
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+/**
+ * Configuration for the heartbeat mixin.
+ */
+export interface HeartbeatConfig {
+  /** Feature key in format 'project:category:feature' */
+  featureKey: string;
+  /** Heartbeat interval in milliseconds. Default: 5 minutes */
+  intervalMs?: number;
+  /** Whether heartbeats are enabled. Default: true */
+  enabled?: boolean;
+}
+
+/**
+ * Required environment bindings for heartbeat functionality.
+ */
+export interface HeartbeatEnv {
+  /** Queue for telemetry messages */
+  PLATFORM_TELEMETRY: Queue<TelemetryMessage>;
+}
+
+/**
+ * Base class type for Durable Objects.
+ * Uses rest parameters for TypeScript mixin compatibility.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type DOClass = new (...args: any[]) => DurableObject;
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+/** Default heartbeat interval: 5 minutes */
+const DEFAULT_INTERVAL_MS = 5 * 60 * 1000;
+
+// =============================================================================
+// MIXIN
+// =============================================================================
+
+/**
+ * Parse a feature key into its component parts.
+ */
+function parseFeatureKey(featureKey: string): {
+  project: string;
+  category: string;
+  feature: string;
+} {
+  const parts = featureKey.split(':');
+  if (parts.length !== 3) {
+    throw new Error(
+      `Invalid featureKey format: "${featureKey}". Expected "project:category:feature"`
+    );
+  }
+  return {
+    project: parts[0],
+    category: parts[1],
+    feature: parts[2],
+  };
+}
+
+/**
+ * Mixin that adds heartbeat functionality to a Durable Object.
+ *
+ * Uses the Cloudflare Alarms API to schedule periodic heartbeats.
+ * Heartbeats are sent to the PLATFORM_TELEMETRY queue with `is_heartbeat: true`.
+ *
+ * The mixin:
+ * 1. Schedules the first heartbeat on construction
+ * 2. Sends a heartbeat message when the alarm fires
+ * 3. Reschedules the next heartbeat
+ * 4. Calls the parent's alarm() method if it exists
+ *
+ * @param Base - The base Durable Object class to extend
+ * @param config - Heartbeat configuration
+ * @returns Extended class with heartbeat functionality
+ *
+ * @example
+ * ```typescript
+ * export class ScoutTriageWorkflow extends withHeartbeat(DurableObject, {
+ *   featureKey: 'scout:do:triage-workflow',
+ *   intervalMs: 5 * 60 * 1000,
+ * }) {
+ *   async fetch(request: Request): Promise<Response> {
+ *     // Your existing implementation
+ *   }
+ * }
+ * ```
+ */
+export function withHeartbeat<TBase extends DOClass>(Base: TBase, config: HeartbeatConfig): TBase {
+  const { featureKey, intervalMs = DEFAULT_INTERVAL_MS, enabled = true } = config;
+
+  // Validate feature key format early
+  const { project, category, feature } = parseFeatureKey(featureKey);
+
+  return class extends Base {
+    // Store parsed config for use in methods
+    protected readonly _heartbeatConfig = {
+      featureKey,
+      project,
+      category,
+      feature,
+      intervalMs,
+      enabled,
+    };
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    constructor(...args: any[]) {
+      super(...args);
+
+      // Schedule first heartbeat if enabled
+      // args[0] is the DurableObjectState
+      if (this._heartbeatConfig.enabled) {
+        void this._scheduleNextHeartbeat(args[0] as DurableObjectState);
+      }
+    }
+
+    /**
+     * Handle alarm events.
+     * Sends heartbeat, reschedules next alarm, and calls parent alarm if present.
+     */
+    async alarm(): Promise<void> {
+      const state = (this as unknown as { state: DurableObjectState }).state;
+      const env = (this as unknown as { env: HeartbeatEnv }).env;
+
+      if (this._heartbeatConfig.enabled) {
+        // Send heartbeat to telemetry queue
+        await this._sendHeartbeat(env);
+
+        // Schedule next heartbeat
+        await this._scheduleNextHeartbeat(state);
+      }
+
+      // Call parent alarm() if it exists
+      // Note: In TypeScript, we need to check if the parent class has an alarm method
+      const parentAlarm = Object.getPrototypeOf(Object.getPrototypeOf(this)).alarm;
+      if (typeof parentAlarm === 'function' && parentAlarm !== this.alarm) {
+        await parentAlarm.call(this);
+      }
+    }
+
+    /**
+     * Schedule the next heartbeat alarm.
+     */
+    protected async _scheduleNextHeartbeat(state: DurableObjectState): Promise<void> {
+      try {
+        const nextAlarmTime = Date.now() + this._heartbeatConfig.intervalMs;
+        await state.storage.setAlarm(nextAlarmTime);
+        getLog().debug('Heartbeat scheduled', {
+          featureKey: this._heartbeatConfig.featureKey,
+          scheduledAt: new Date(nextAlarmTime).toISOString(),
+        });
+      } catch (error) {
+        getLog().error('Failed to schedule heartbeat', error, {
+          featureKey: this._heartbeatConfig.featureKey,
+        });
+      }
+    }
+
+    /**
+     * Send a heartbeat message to the telemetry queue.
+     */
+    protected async _sendHeartbeat(env: HeartbeatEnv): Promise<void> {
+      if (!env.PLATFORM_TELEMETRY) {
+        getLog().warn('No PLATFORM_TELEMETRY queue binding, heartbeat not sent', undefined, {
+          featureKey: this._heartbeatConfig.featureKey,
+        });
+        return;
+      }
+
+      const heartbeatMessage: TelemetryMessage = {
+        feature_key: this._heartbeatConfig.featureKey,
+        project: this._heartbeatConfig.project,
+        category: this._heartbeatConfig.category,
+        feature: this._heartbeatConfig.feature,
+        metrics: {},
+        timestamp: Date.now(),
+        is_heartbeat: true,
+      };
+
+      try {
+        await env.PLATFORM_TELEMETRY.send(heartbeatMessage);
+        getLog().debug('Heartbeat sent', { featureKey: this._heartbeatConfig.featureKey });
+      } catch (error) {
+        // Fail open - log error but don't throw
+        getLog().error('Failed to send heartbeat', error, {
+          featureKey: this._heartbeatConfig.featureKey,
+        });
+      }
+    }
+
+    /**
+     * Manually trigger a heartbeat (for testing or on-demand health checks).
+     */
+    async sendHeartbeatNow(): Promise<void> {
+      const env = (this as unknown as { env: HeartbeatEnv }).env;
+      await this._sendHeartbeat(env);
+    }
+
+    /**
+     * Manually reschedule the next heartbeat (for testing or recovery).
+     */
+    async rescheduleHeartbeat(): Promise<void> {
+      const state = (this as unknown as { state: DurableObjectState }).state;
+      await this._scheduleNextHeartbeat(state);
+    }
+  } as TBase;
+}

package/src/dynamic-patterns.ts

@@ -0,0 +1,273 @@
+/// <reference types="@cloudflare/workers-types" />
+
+/**
+ * Dynamic Patterns
+ *
+ * AI-discovered transient error patterns loaded from KV at runtime.
+ * Separate from static patterns (patterns.ts) because these require KV I/O.
+ *
+ * Pattern lifecycle: pending -> shadow -> ready for review -> approved -> KV cache -> runtime
+ *
+ * Supports a constrained DSL with 4 types: contains, startsWith, statusCode, regex.
+ * Regex patterns have a 200-char safety limit to prevent ReDoS.
+ *
+ * Multi-account utilities (exportDynamicPatterns/importDynamicPatterns) enable
+ * cross-account pattern sync via sync-config or platform-agent.
+ *
+ * @example
+ * ```typescript
+ * import { loadDynamicPatterns, classifyWithDynamicPatterns } from '@littlebearapps/platform-consumer-sdk/dynamic-patterns';
+ *
+ * const patterns = await loadDynamicPatterns(env.PLATFORM_CACHE);
+ * const result = classifyWithDynamicPatterns('Custom error message', patterns);
+ * if (result) {
+ *   console.log(`Dynamic match: ${result.category} (${result.patternId})`);
+ * }
+ * ```
+ */
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+/** Dynamic pattern rule from pattern-discovery system */
+export interface DynamicPatternRule {
+  type: 'contains' | 'startsWith' | 'statusCode' | 'regex';
+  value: string;
+  category: string;
+  scope: string;
+  id?: string;
+}
+
+/** Compiled pattern ready for classification */
+export interface CompiledPattern {
+  test: (message: string) => boolean;
+  category: string;
+  id?: string;
+}
+
+/** Classification result from dynamic pattern matching */
+export interface ClassificationResult {
+  category: string;
+  source: 'dynamic';
+  patternId?: string;
+}
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+/** KV key for approved dynamic patterns — useful for sync-config and multi-account */
+export const DYNAMIC_PATTERNS_KV_KEY = 'PATTERNS:DYNAMIC:APPROVED';
+
+// =============================================================================
+// COMPILATION
+// =============================================================================
+
+/**
+ * Compile a single dynamic pattern rule to a test function.
+ * Uses the constrained DSL to ensure safety (no arbitrary regex execution).
+ *
+ * @returns Compiled pattern or null if compilation fails
+ */
+function compileDynamicPattern(rule: DynamicPatternRule): CompiledPattern | null {
+  try {
+    switch (rule.type) {
+      case 'contains': {
+        const tokens = rule.value.toLowerCase().split(/\s+/);
+        return {
+          test: (msg: string) => {
+            const lowerMsg = msg.toLowerCase();
+            return tokens.every((token) => lowerMsg.includes(token));
+          },
+          category: rule.category,
+          id: rule.id,
+        };
+      }
+      case 'startsWith': {
+        const prefix = rule.value.toLowerCase();
+        return {
+          test: (msg: string) => msg.toLowerCase().startsWith(prefix),
+          category: rule.category,
+          id: rule.id,
+        };
+      }
+      case 'statusCode': {
+        const code = rule.value;
+        const pattern = new RegExp(`\\b${code}\\b`);
+        return {
+          test: (msg: string) => pattern.test(msg),
+          category: rule.category,
+          id: rule.id,
+        };
+      }
+      case 'regex': {
+        // Add safety limit to prevent ReDoS
+        if (rule.value.length > 200) {
+          console.warn(`Skipping overly long regex pattern: ${rule.category}`);
+          return null;
+        }
+        const pattern = new RegExp(rule.value, 'i');
+        return {
+          test: (msg: string) => pattern.test(msg),
+          category: rule.category,
+          id: rule.id,
+        };
+      }
+      default:
+        return null;
+    }
+  } catch (error) {
+    console.warn(`Failed to compile pattern for ${rule.category}:`, error);
+    return null;
+  }
+}
+
+/**
+ * Compile an array of dynamic pattern rules into test functions.
+ * Invalid rules are silently dropped (logged via console.warn).
+ *
+ * @param rules - Array of dynamic pattern rules from D1/KV
+ * @returns Array of compiled patterns ready for classification
+ */
+export function compileDynamicPatterns(rules: DynamicPatternRule[]): CompiledPattern[] {
+  const compiled: CompiledPattern[] = [];
+  for (const rule of rules) {
+    const pattern = compileDynamicPattern(rule);
+    if (pattern) {
+      compiled.push(pattern);
+    }
+  }
+  return compiled;
+}
+
+// =============================================================================
+// IN-MEMORY CACHE
+// =============================================================================
+
+let dynamicPatternsCache: CompiledPattern[] | null = null;
+let dynamicPatternsCacheTime = 0;
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+// =============================================================================
+// LOADING
+// =============================================================================
+
+/**
+ * Load dynamic patterns from KV and compile them.
+ * Uses in-memory cache (5-minute TTL) to avoid repeated KV reads within worker lifetime.
+ *
+ * @param kv - KV namespace containing approved patterns
+ * @returns Compiled patterns ready for classification
+ */
+export async function loadDynamicPatterns(kv: KVNamespace): Promise<CompiledPattern[]> {
+  const now = Date.now();
+  if (dynamicPatternsCache && now - dynamicPatternsCacheTime < CACHE_TTL_MS) {
+    return dynamicPatternsCache;
+  }
+
+  try {
+    const cached = await kv.get(DYNAMIC_PATTERNS_KV_KEY);
+    if (!cached) {
+      dynamicPatternsCache = [];
+      dynamicPatternsCacheTime = now;
+      return [];
+    }
+
+    const rules = JSON.parse(cached) as DynamicPatternRule[];
+    const compiled = compileDynamicPatterns(rules);
+
+    dynamicPatternsCache = compiled;
+    dynamicPatternsCacheTime = now;
+    return compiled;
+  } catch (error) {
+    console.error('Failed to load dynamic patterns:', error);
+    return dynamicPatternsCache || [];
+  }
+}
+
+/**
+ * Clear the in-memory dynamic patterns cache.
+ * Call after pattern updates or for testing.
+ */
+export function clearDynamicPatternsCache(): void {
+  dynamicPatternsCache = null;
+  dynamicPatternsCacheTime = 0;
+}
+
+// =============================================================================
+// CLASSIFICATION
+// =============================================================================
+
+/**
+ * Classify an error message using dynamic patterns only.
+ * For combined static + dynamic classification, use classifyErrorWithSource() in fingerprint.ts.
+ *
+ * @param message - Error message to classify
+ * @param patterns - Pre-loaded compiled dynamic patterns
+ * @returns Classification result or null if no match
+ */
+export function classifyWithDynamicPatterns(
+  message: string,
+  patterns: CompiledPattern[]
+): ClassificationResult | null {
+  for (const compiled of patterns) {
+    if (compiled.test(message)) {
+      return {
+        category: compiled.category,
+        source: 'dynamic',
+        patternId: compiled.id,
+      };
+    }
+  }
+  return null;
+}
+
+// =============================================================================
+// MULTI-ACCOUNT UTILITIES
+// =============================================================================
+
+/**
+ * Export raw dynamic patterns from KV for cross-account transfer.
+ * Returns the JSON string as-is (no compilation) for writing to another KV.
+ *
+ * @param kv - Source KV namespace with approved patterns
+ * @returns Raw JSON string or null if no patterns are cached
+ */
+export async function exportDynamicPatterns(kv: KVNamespace): Promise<string | null> {
+  return await kv.get(DYNAMIC_PATTERNS_KV_KEY);
+}
+
+/**
+ * Import dynamic patterns into a KV namespace.
+ * Validates structure AND compiles each rule as a safety gate:
+ * - Checks required fields (type, value, category)
+ * - Compiles to verify regex validity + applies 200-char limit for regex type
+ * - Silently drops rules that fail compilation (matches loadDynamicPatterns behaviour)
+ *
+ * TTL matches pattern-discovery's 7-day safety net.
+ *
+ * @param kv - Target KV namespace
+ * @param patternsJson - Raw JSON string from exportDynamicPatterns()
+ * @returns Count of imported and dropped rules
+ */
+export async function importDynamicPatterns(
+  kv: KVNamespace,
+  patternsJson: string
+): Promise<{ imported: number; dropped: number }> {
+  const rules = JSON.parse(patternsJson) as DynamicPatternRule[];
+
+  // Structural validation
+  const validTypes = new Set(['contains', 'startsWith', 'statusCode', 'regex']);
+  const structurallyValid = rules.filter(
+    (r) => r.type && r.value && r.category && validTypes.has(r.type)
+  );
+
+  // Compilation gate: verify each rule compiles (catches invalid regex, ReDoS-length limit)
+  const compilable = structurallyValid.filter((r) => compileDynamicPatterns([r]).length > 0);
+
+  await kv.put(DYNAMIC_PATTERNS_KV_KEY, JSON.stringify(compilable), { expirationTtl: 604800 });
+  clearDynamicPatternsCache();
+
+  return { imported: compilable.length, dropped: rules.length - compilable.length };
+}