@littlebearapps/platform-admin-sdk 2.0.0 → 2.1.0

package/templates/full/dashboard/src/lib/cloudflare/alerting.ts

@@ -0,0 +1,486 @@
+/**
+ * Alerting Service for Cost Spike Detection
+ *
+ * Shared alert logic for Slack and Email notifications.
+ * Used by platform-sentinel worker (task-17.20, task-17.21).
+ *
+ * @module lib/cloudflare/alerting
+ * @created 2026-01-05
+ * @task task-17.20 - Slack webhook alerts for cost spikes
+ * @task task-17.21 - Email alerts via Resend
+ */
+
+import type { ThresholdWarning, ThresholdLevel, CostBreakdown } from './costs';
+
+/**
+ * Cost spike alert data
+ */
+export interface CostSpikeAlert {
+  id: string;
+  serviceType: string;
+  resourceName: string;
+  currentCost: number;
+  previousCost: number;
+  costDeltaPct: number;
+  thresholdLevel: ThresholdLevel;
+  absoluteMax: number;
+  timestamp: string;
+}
+
+/**
+ * Alert routing result
+ */
+export interface AlertResult {
+  success: boolean;
+  channel: 'slack' | 'email';
+  alertId: string;
+  rateLimited: boolean;
+  error?: string;
+}
+
+/**
+ * Slack message blocks for cost spike alert
+ */
+export interface SlackMessage {
+  text: string;
+  blocks: SlackBlock[];
+  attachments?: SlackAttachment[];
+}
+
+interface SlackBlock {
+  type: 'section' | 'divider' | 'header' | 'context';
+  text?: {
+    type: 'mrkdwn' | 'plain_text';
+    text: string;
+  };
+  fields?: Array<{
+    type: 'mrkdwn' | 'plain_text';
+    text: string;
+  }>;
+}
+
+interface SlackAttachment {
+  color: string;
+  fields?: Array<{
+    title: string;
+    value: string;
+    short: boolean;
+  }>;
+}
+
+/**
+ * Get Slack colour for threshold level
+ */
+export function getSeverityColour(level: ThresholdLevel): string {
+  const colours: Record<ThresholdLevel, string> = {
+    critical: '#dc3545', // Red
+    high: '#fd7e14', // Orange
+    warning: '#ffc107', // Yellow
+    normal: '#28a745', // Green
+  };
+  return colours[level] || colours.warning;
+}
+
+/**
+ * Get emoji for threshold level
+ */
+export function getSeverityEmoji(level: ThresholdLevel): string {
+  const emojis: Record<ThresholdLevel, string> = {
+    critical: ':rotating_light:', // Siren
+    high: ':warning:', // Warning triangle
+    warning: ':yellow_circle:', // Yellow circle
+    normal: ':white_check_mark:', // Checkmark
+  };
+  return emojis[level] || emojis.warning;
+}
+
+/**
+ * Format currency for display
+ */
+export function formatCurrency(amount: number): string {
+  return `$${amount.toFixed(2)}`;
+}
+
+/**
+ * Format percentage for display
+ */
+export function formatPercentage(pct: number): string {
+  const sign = pct >= 0 ? '+' : '';
+  return `${sign}${pct.toFixed(1)}%`;
+}
+
+/**
+ * Generate deduplication key for an alert
+ * Format: cost-spike:{serviceType}:{resourceName}
+ */
+export function generateAlertKey(alert: CostSpikeAlert): string {
+  return `cost-spike:${alert.serviceType}:${alert.resourceName}`;
+}
+
+/**
+ * Check if an alert should be sent (rate limiting)
+ *
+ * @param key - Alert deduplication key
+ * @param kv - KV namespace for storing rate limit state
+ * @param ttlSeconds - Rate limit window (default: 1 hour)
+ * @returns true if alert should be sent, false if rate limited
+ */
+export async function shouldSendAlert(
+  key: string,
+  kv: KVNamespace,
+  ttlSeconds: number = 3600
+): Promise<boolean> {
+  const existing = await kv.get(key);
+  if (existing) {
+    return false; // Rate limited
+  }
+
+  // Mark as sent with TTL
+  await kv.put(key, new Date().toISOString(), {
+    expirationTtl: ttlSeconds,
+  });
+
+  return true;
+}
+
+/**
+ * Build Slack message for cost spike alert
+ */
+export function buildSlackMessage(alert: CostSpikeAlert): SlackMessage {
+  const emoji = getSeverityEmoji(alert.thresholdLevel);
+  const colour = getSeverityColour(alert.thresholdLevel);
+  const levelText = alert.thresholdLevel.toUpperCase();
+  const deltaText = formatPercentage(alert.costDeltaPct);
+  const isSpike = alert.costDeltaPct > 0;
+
+  const headerText = isSpike
+    ? `${emoji} Cost Spike Detected: ${alert.serviceType}`
+    : `${emoji} Cost Alert: ${alert.serviceType}`;
+
+  return {
+    text: `[${levelText}] ${alert.serviceType} cost ${deltaText} - ${formatCurrency(alert.currentCost)}`,
+    blocks: [
+      {
+        type: 'header',
+        text: {
+          type: 'plain_text',
+          text: headerText,
+        },
+      },
+      {
+        type: 'section',
+        fields: [
+          {
+            type: 'mrkdwn',
+            text: `*Service:*\n${alert.serviceType}`,
+          },
+          {
+            type: 'mrkdwn',
+            text: `*Resource:*\n${alert.resourceName}`,
+          },
+          {
+            type: 'mrkdwn',
+            text: `*Current Cost:*\n${formatCurrency(alert.currentCost)}`,
+          },
+          {
+            type: 'mrkdwn',
+            text: `*Previous Cost:*\n${formatCurrency(alert.previousCost)}`,
+          },
+          {
+            type: 'mrkdwn',
+            text: `*Change:*\n${deltaText}`,
+          },
+          {
+            type: 'mrkdwn',
+            text: `*Threshold:*\n${formatCurrency(alert.absoluteMax)} (${levelText})`,
+          },
+        ],
+      },
+      {
+        type: 'context',
+        text: {
+          type: 'mrkdwn',
+          text: `Alert ID: ${alert.id} | Time: ${new Date(alert.timestamp).toLocaleString('en-AU')}`,
+        },
+      },
+    ],
+    attachments: [
+      {
+        color: colour,
+        fields: [
+          {
+            title: 'Action Required',
+            value:
+              alert.thresholdLevel === 'critical'
+                ? 'Investigate immediately - usage significantly exceeds budget'
+                : alert.thresholdLevel === 'high'
+                  ? 'Review usage patterns and consider optimisation'
+                  : 'Monitor closely - approaching threshold',
+            short: false,
+          },
+        ],
+      },
+    ],
+  };
+}
+
+/**
+ * Build summary Slack message for multiple alerts
+ */
+export function buildSummarySlackMessage(alerts: CostSpikeAlert[]): SlackMessage {
+  const criticalCount = alerts.filter((a) => a.thresholdLevel === 'critical').length;
+  const highCount = alerts.filter((a) => a.thresholdLevel === 'high').length;
+  const warningCount = alerts.filter((a) => a.thresholdLevel === 'warning').length;
+
+  const emoji =
+    criticalCount > 0 ? ':rotating_light:' : highCount > 0 ? ':warning:' : ':yellow_circle:';
+  const totalCost = alerts.reduce((sum, a) => sum + a.currentCost, 0);
+
+  return {
+    text: `[SUMMARY] ${alerts.length} cost alerts - ${formatCurrency(totalCost)} total`,
+    blocks: [
+      {
+        type: 'header',
+        text: {
+          type: 'plain_text',
+          text: `${emoji} Cost Alert Summary: ${alerts.length} Alerts`,
+        },
+      },
+      {
+        type: 'section',
+        fields: [
+          {
+            type: 'mrkdwn',
+            text: `*Critical:* ${criticalCount}`,
+          },
+          {
+            type: 'mrkdwn',
+            text: `*High:* ${highCount}`,
+          },
+          {
+            type: 'mrkdwn',
+            text: `*Warning:* ${warningCount}`,
+          },
+          {
+            type: 'mrkdwn',
+            text: `*Total Cost:* ${formatCurrency(totalCost)}`,
+          },
+        ],
+      },
+      {
+        type: 'divider',
+      },
+      ...alerts.slice(0, 5).map(
+        (alert) =>
+          ({
+            type: 'section',
+            text: {
+              type: 'mrkdwn',
+              text: `${getSeverityEmoji(alert.thresholdLevel)} *${alert.serviceType}*: ${formatCurrency(alert.currentCost)} (${formatPercentage(alert.costDeltaPct)})`,
+            },
+          }) as SlackBlock
+      ),
+      ...(alerts.length > 5
+        ? [
+            {
+              type: 'context' as const,
+              text: {
+                type: 'mrkdwn' as const,
+                text: `_...and ${alerts.length - 5} more alerts_`,
+              },
+            },
+          ]
+        : []),
+    ],
+  };
+}
+
+/**
+ * Send alert to Slack webhook
+ */
+export async function sendSlackAlert(
+  webhookUrl: string,
+  message: SlackMessage
+): Promise<{ success: boolean; error?: string }> {
+  try {
+    const response = await fetch(webhookUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(message),
+    });
+
+    if (!response.ok) {
+      const text = await response.text();
+      return { success: false, error: `Slack webhook failed: ${response.status} ${text}` };
+    }
+
+    return { success: true };
+  } catch (error) {
+    return {
+      success: false,
+      error: `Slack webhook error: ${error instanceof Error ? error.message : 'Unknown error'}`,
+    };
+  }
+}
+
+/**
+ * Evaluate if a warning should trigger an alert
+ *
+ * @param warning - Threshold warning from analyseThresholds
+ * @param costs - Current cost breakdown
+ * @param previousCosts - Previous period cost breakdown (for delta calculation)
+ * @param absoluteMax - Maximum cost threshold
+ * @returns CostSpikeAlert if alert should be triggered, null otherwise
+ */
+export function evaluateWarning(
+  warning: ThresholdWarning,
+  costs: CostBreakdown,
+  previousCosts: CostBreakdown | null,
+  absoluteMax: number
+): CostSpikeAlert | null {
+  // Map resource name to service type key
+  const serviceKeyMap: Record<string, keyof CostBreakdown> = {
+    Workers: 'workers',
+    D1: 'd1',
+    KV: 'kv',
+    R2: 'r2',
+    'Durable Objects': 'durableObjects',
+    Vectorize: 'vectorize',
+    'AI Gateway': 'aiGateway',
+    Pages: 'pages',
+    Queues: 'queues',
+    Workflows: 'workflows',
+  };
+
+  const serviceKey = serviceKeyMap[warning.resource];
+  if (!serviceKey) return null;
+
+  const currentCost = costs[serviceKey];
+  const previousCost = previousCosts ? previousCosts[serviceKey] : 0;
+
+  // Calculate cost delta percentage
+  const costDeltaPct = previousCost > 0 ? ((currentCost - previousCost) / previousCost) * 100 : 0;
+
+  // Alert conditions (any of):
+  // 1. Cost delta > 50%
+  // 2. Threshold level is critical
+  // 3. Current cost exceeds absolute max
+  const shouldAlert =
+    costDeltaPct > 50 || warning.level === 'critical' || currentCost > absoluteMax;
+
+  if (!shouldAlert) return null;
+
+  return {
+    id: crypto.randomUUID(),
+    serviceType: warning.resource,
+    resourceName: warning.metric,
+    currentCost,
+    previousCost,
+    costDeltaPct,
+    thresholdLevel: warning.level,
+    absoluteMax,
+    timestamp: new Date().toISOString(),
+  };
+}
+
+/**
+ * Build HTML email template for cost alert
+ */
+export function buildEmailHtml(alert: CostSpikeAlert): string {
+  const levelColour = getSeverityColour(alert.thresholdLevel);
+  const levelText = alert.thresholdLevel.toUpperCase();
+  const deltaText = formatPercentage(alert.costDeltaPct);
+
+  return `
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Cost Alert: ${alert.serviceType}</title>
+</head>
+<body style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; margin: 0; padding: 20px; background-color: #f5f5f5;">
+  <div style="max-width: 600px; margin: 0 auto; background: white; border-radius: 8px; overflow: hidden; box-shadow: 0 2px 4px rgba(0,0,0,0.1);">
+    <div style="background-color: ${levelColour}; color: white; padding: 20px;">
+      <h1 style="margin: 0; font-size: 20px;">[${levelText}] Cost Alert: ${alert.serviceType}</h1>
+    </div>
+    <div style="padding: 20px;">
+      <table style="width: 100%; border-collapse: collapse;">
+        <tr>
+          <td style="padding: 10px 0; border-bottom: 1px solid #eee;"><strong>Service</strong></td>
+          <td style="padding: 10px 0; border-bottom: 1px solid #eee;">${alert.serviceType}</td>
+        </tr>
+        <tr>
+          <td style="padding: 10px 0; border-bottom: 1px solid #eee;"><strong>Resource</strong></td>
+          <td style="padding: 10px 0; border-bottom: 1px solid #eee;">${alert.resourceName}</td>
+        </tr>
+        <tr>
+          <td style="padding: 10px 0; border-bottom: 1px solid #eee;"><strong>Current Cost</strong></td>
+          <td style="padding: 10px 0; border-bottom: 1px solid #eee;">${formatCurrency(alert.currentCost)}</td>
+        </tr>
+        <tr>
+          <td style="padding: 10px 0; border-bottom: 1px solid #eee;"><strong>Previous Cost</strong></td>
+          <td style="padding: 10px 0; border-bottom: 1px solid #eee;">${formatCurrency(alert.previousCost)}</td>
+        </tr>
+        <tr>
+          <td style="padding: 10px 0; border-bottom: 1px solid #eee;"><strong>Change</strong></td>
+          <td style="padding: 10px 0; border-bottom: 1px solid #eee; color: ${alert.costDeltaPct > 0 ? '#dc3545' : '#28a745'};">${deltaText}</td>
+        </tr>
+        <tr>
+          <td style="padding: 10px 0;"><strong>Threshold</strong></td>
+          <td style="padding: 10px 0;">${formatCurrency(alert.absoluteMax)} (${levelText})</td>
+        </tr>
+      </table>
+      <div style="margin-top: 20px; padding: 15px; background: #f8f9fa; border-radius: 4px;">
+        <strong>Recommended Action:</strong>
+        <p style="margin: 10px 0 0 0; color: #666;">
+          ${
+            alert.thresholdLevel === 'critical'
+              ? 'Investigate immediately - usage significantly exceeds budget'
+              : alert.thresholdLevel === 'high'
+                ? 'Review usage patterns and consider optimisation'
+                : 'Monitor closely - approaching threshold'
+          }
+        </p>
+      </div>
+    </div>
+    <div style="background: #f8f9fa; padding: 15px 20px; font-size: 12px; color: #666;">
+      <p style="margin: 0;">Alert ID: ${alert.id}</p>
+      <p style="margin: 5px 0 0 0;">Generated: ${new Date(alert.timestamp).toLocaleString('en-AU')}</p>
+    </div>
+  </div>
+</body>
+</html>`;
+}
+
+/**
+ * Build plain text email for cost alert
+ */
+export function buildEmailText(alert: CostSpikeAlert): string {
+  const levelText = alert.thresholdLevel.toUpperCase();
+  const deltaText = formatPercentage(alert.costDeltaPct);
+
+  return `
+[${levelText}] Cost Alert: ${alert.serviceType}
+
+Service: ${alert.serviceType}
+Resource: ${alert.resourceName}
+Current Cost: ${formatCurrency(alert.currentCost)}
+Previous Cost: ${formatCurrency(alert.previousCost)}
+Change: ${deltaText}
+Threshold: ${formatCurrency(alert.absoluteMax)} (${levelText})
+
+Recommended Action:
+${
+  alert.thresholdLevel === 'critical'
+    ? 'Investigate immediately - usage significantly exceeds budget'
+    : alert.thresholdLevel === 'high'
+      ? 'Review usage patterns and consider optimisation'
+      : 'Monitor closely - approaching threshold'
+}
+
+---
+Alert ID: ${alert.id}
+Generated: ${new Date(alert.timestamp).toLocaleString('en-AU')}
+`;
+}