Alert Model¶

Complete reference for Alert and Notification data models.

Overview¶

The Alert model represents system alerts, compliance notifications, and user-defined triggers in CalcBridge. Alerts can be configured to notify users of compliance breaches, calculation errors, threshold crossings, and other important events.

Core Models¶

Alert¶

The primary alert entity.

interface Alert {
  // Identification
  id: string;                    // UUID, primary key
  tenant_id: string;             // UUID, tenant ownership

  // Classification
  alert_type: AlertType;         // Type of alert
  category: AlertCategory;       // Alert category
  severity: AlertSeverity;       // Severity level

  // Content
  title: string;                 // Alert title
  message: string;               // Detailed message

  // Source
  source: AlertSource;           // What triggered the alert

  // Context
  workbook_id?: string;          // Related workbook
  scenario_id?: string;          // Related scenario
  test_id?: string;              // Related compliance test
  breach_id?: string;            // Related breach

  // Status
  status: AlertStatus;           // Current status

  // Acknowledgement
  acknowledged_at?: string;
  acknowledged_by?: string;
  acknowledgement_note?: string;

  // Resolution
  resolved_at?: string;
  resolved_by?: string;
  resolution_note?: string;
  auto_resolved: boolean;        // Resolved automatically

  // Notification
  notifications_sent: NotificationRecord[];

  // Timing
  triggered_at: string;          // When alert was triggered
  expires_at?: string;           // Alert expiry time

  // Metadata
  metadata: Record<string, any>; // Additional context

  // Audit
  created_at: string;
  updated_at: string;
}

AlertType¶

enum AlertType {
  // Compliance alerts
  COMPLIANCE_BREACH = "compliance_breach",
  COMPLIANCE_WARNING = "compliance_warning",
  CUSHION_CRITICAL = "cushion_critical",
  CUSHION_WARNING = "cushion_warning",

  // Calculation alerts
  CALCULATION_ERROR = "calculation_error",
  CALCULATION_TIMEOUT = "calculation_timeout",
  FORMULA_ERROR = "formula_error",

  // Data alerts
  DATA_VALIDATION_ERROR = "data_validation_error",
  DATA_IMPORT_ERROR = "data_import_error",
  DATA_SYNC_ERROR = "data_sync_error",

  // Threshold alerts
  THRESHOLD_EXCEEDED = "threshold_exceeded",
  THRESHOLD_APPROACHING = "threshold_approaching",

  // System alerts
  SYSTEM_ERROR = "system_error",
  SYSTEM_WARNING = "system_warning",
  SCHEDULED_JOB_FAILED = "scheduled_job_failed",

  // Security alerts
  SECURITY_WARNING = "security_warning",
  UNAUTHORIZED_ACCESS = "unauthorized_access",

  // Custom alerts
  CUSTOM = "custom"
}

AlertCategory¶

enum AlertCategory {
  COMPLIANCE = "compliance",
  CALCULATION = "calculation",
  DATA = "data",
  SYSTEM = "system",
  SECURITY = "security",
  CUSTOM = "custom"
}

AlertSeverity¶

enum AlertSeverity {
  CRITICAL = "critical",         // Immediate action required
  HIGH = "high",                 // Urgent attention needed
  MEDIUM = "medium",             // Should be addressed soon
  LOW = "low",                   // Informational
  INFO = "info"                  // For awareness only
}

AlertStatus¶

enum AlertStatus {
  ACTIVE = "active",             // Alert is active
  ACKNOWLEDGED = "acknowledged", // User acknowledged
  RESOLVED = "resolved",         // Issue resolved
  EXPIRED = "expired",           // Alert expired
  SNOOZED = "snoozed"            // Temporarily hidden
}

Alert Source Models¶

AlertSource¶

interface AlertSource {
  source_type: AlertSourceType;
  source_id?: string;            // ID of source entity
  source_name?: string;          // Display name

  // For compliance alerts
  test_name?: string;
  test_category?: string;

  // For calculation alerts
  cell_reference?: string;
  formula?: string;

  // For data alerts
  sheet_name?: string;
  row_number?: number;
  column?: string;
}

AlertSourceType¶

enum AlertSourceType {
  COMPLIANCE_TEST = "compliance_test",
  COMPLIANCE_EXECUTION = "compliance_execution",
  CALCULATION_JOB = "calculation_job",
  WORKBOOK = "workbook",
  SCENARIO = "scenario",
  IMPORT_JOB = "import_job",
  SCHEDULED_TASK = "scheduled_task",
  SYSTEM = "system",
  USER_RULE = "user_rule"
}

Alert Rule Models¶

AlertRule¶

User-defined alert configuration.

interface AlertRule {
  // Identification
  id: string;
  tenant_id: string;

  // Metadata
  name: string;                  // Rule name
  description?: string;

  // Status
  enabled: boolean;

  // Trigger condition
  trigger: AlertTrigger;

  // Alert configuration
  alert_config: AlertConfig;

  // Notification configuration
  notification_config: NotificationConfig;

  // Cooldown
  cooldown_minutes: number;      // Minimum time between alerts
  last_triggered_at?: string;

  // Audit
  created_at: string;
  updated_at: string;
  created_by: string;
}

AlertTrigger¶

interface AlertTrigger {
  trigger_type: TriggerType;

  // Condition
  condition: TriggerCondition;

  // Scope
  scope: TriggerScope;
}

enum TriggerType {
  COMPLIANCE_BREACH = "compliance_breach",
  COMPLIANCE_WARNING = "compliance_warning",
  CUSHION_THRESHOLD = "cushion_threshold",
  VALUE_THRESHOLD = "value_threshold",
  VALUE_CHANGE = "value_change",
  CALCULATION_ERROR = "calculation_error",
  DATA_CHANGE = "data_change",
  SCHEDULE = "schedule"
}

TriggerCondition¶

interface TriggerCondition {
  // For threshold triggers
  operator?: ComparisonOperator;
  threshold?: number;

  // For change triggers
  change_type?: "absolute" | "percentage";
  change_threshold?: number;

  // For compliance triggers
  severity_filter?: AlertSeverity[];
  category_filter?: string[];

  // For scheduled triggers
  schedule?: ScheduleExpression;
}

enum ComparisonOperator {
  EQUALS = "eq",
  NOT_EQUALS = "ne",
  GREATER_THAN = "gt",
  GREATER_EQUAL = "gte",
  LESS_THAN = "lt",
  LESS_EQUAL = "lte",
  BETWEEN = "between"
}

TriggerScope¶

interface TriggerScope {
  // Workbook scope
  workbook_ids?: string[];       // Specific workbooks
  all_workbooks?: boolean;       // All workbooks

  // Test scope (for compliance)
  test_ids?: string[];           // Specific tests
  test_categories?: string[];    // Test categories

  // Cell scope (for calculations)
  sheet_names?: string[];
  cell_ranges?: string[];
}

AlertConfig¶

interface AlertConfig {
  severity: AlertSeverity;
  title_template: string;        // Template with variables
  message_template: string;      // Template with variables

  // Auto-resolution
  auto_resolve: boolean;
  auto_resolve_when?: string;    // Condition for auto-resolve

  // Expiry
  expires_after_hours?: number;

  // Grouping
  group_similar: boolean;        // Group similar alerts
  group_window_minutes?: number;
}

Notification Models¶

NotificationConfig¶

interface NotificationConfig {
  // Channels
  channels: NotificationChannel[];

  // Recipients
  recipients: NotificationRecipient[];

  // Timing
  immediate: boolean;            // Send immediately
  digest_frequency?: DigestFrequency;  // For digest mode

  // Quiet hours
  respect_quiet_hours: boolean;
  quiet_hours?: QuietHours;

  // Escalation
  escalation?: EscalationConfig;
}

NotificationChannel¶

enum NotificationChannel {
  EMAIL = "email",
  IN_APP = "in_app",
  WEBHOOK = "webhook",
  SLACK = "slack",
  TEAMS = "teams",
  PAGERDUTY = "pagerduty"
}

NotificationRecipient¶

interface NotificationRecipient {
  type: "user" | "email" | "group" | "webhook";
  value: string;                 // User ID, email, group ID, or URL
  name?: string;                 // Display name
  channels?: NotificationChannel[];  // Override channels
}

DigestFrequency¶

enum DigestFrequency {
  HOURLY = "hourly",
  DAILY = "daily",
  WEEKLY = "weekly"
}

QuietHours¶

interface QuietHours {
  enabled: boolean;
  start_time: string;            // HH:MM
  end_time: string;              // HH:MM
  timezone: string;              // IANA timezone
  days: number[];                // 0-6 (Sunday-Saturday)

  // Exceptions
  critical_override: boolean;    // Send critical during quiet
}

EscalationConfig¶

interface EscalationConfig {
  enabled: boolean;

  // Escalation levels
  levels: EscalationLevel[];
}

interface EscalationLevel {
  delay_minutes: number;         // Time before escalation
  recipients: NotificationRecipient[];
  condition?: string;            // Escalate if condition met
}

NotificationRecord¶

Record of a sent notification.

interface NotificationRecord {
  id: string;
  alert_id: string;

  // Channel
  channel: NotificationChannel;
  recipient: string;

  // Status
  status: NotificationStatus;

  // Timing
  sent_at?: string;
  delivered_at?: string;
  read_at?: string;

  // Error
  error_message?: string;
  retry_count: number;
}

enum NotificationStatus {
  PENDING = "pending",
  SENT = "sent",
  DELIVERED = "delivered",
  READ = "read",
  FAILED = "failed"
}

Request/Response Models¶

CreateAlertRuleRequest¶

interface CreateAlertRuleRequest {
  name: string;
  description?: string;
  enabled?: boolean;             // Default: true

  trigger: AlertTrigger;
  alert_config: AlertConfig;
  notification_config: NotificationConfig;

  cooldown_minutes?: number;     // Default: 60
}

UpdateAlertRuleRequest¶

interface UpdateAlertRuleRequest {
  name?: string;
  description?: string;
  enabled?: boolean;

  trigger?: Partial<AlertTrigger>;
  alert_config?: Partial<AlertConfig>;
  notification_config?: Partial<NotificationConfig>;

  cooldown_minutes?: number;
}

AcknowledgeAlertRequest¶

interface AcknowledgeAlertRequest {
  note?: string;                 // Acknowledgement note
  snooze_until?: string;         // Snooze until time
}

ResolveAlertRequest¶

interface ResolveAlertRequest {
  note?: string;                 // Resolution note
  resolution_type?: ResolutionType;
}

enum ResolutionType {
  FIXED = "fixed",               // Issue was fixed
  FALSE_POSITIVE = "false_positive",
  DUPLICATE = "duplicate",
  WONT_FIX = "wont_fix",
  BY_DESIGN = "by_design"
}

AlertResponse¶

interface AlertResponse {
  id: string;
  alert_type: AlertType;
  category: AlertCategory;
  severity: AlertSeverity;

  title: string;
  message: string;

  status: AlertStatus;

  source: AlertSource;

  workbook_id?: string;
  workbook_name?: string;

  triggered_at: string;
  acknowledged_at?: string;
  resolved_at?: string;

  metadata: Record<string, any>;
}

AlertDetailResponse¶

Full alert details.

interface AlertDetailResponse extends AlertResponse {
  acknowledged_by?: UserSummary;
  acknowledgement_note?: string;

  resolved_by?: UserSummary;
  resolution_note?: string;
  auto_resolved: boolean;

  notifications_sent: NotificationRecord[];

  // Related alerts
  related_alerts?: AlertResponse[];

  // History
  history: AlertHistoryEntry[];
}

interface AlertHistoryEntry {
  action: string;
  performed_by?: string;
  performed_at: string;
  details?: string;
}

AlertListResponse¶

interface AlertListResponse {
  items: AlertResponse[];
  total: number;
  page: number;
  page_size: number;

  // Aggregations
  by_severity: Record<AlertSeverity, number>;
  by_status: Record<AlertStatus, number>;
  by_category: Record<AlertCategory, number>;

  // Unacknowledged counts
  unacknowledged_critical: number;
  unacknowledged_high: number;
}

AlertRuleResponse¶

interface AlertRuleResponse {
  id: string;
  name: string;
  description?: string;
  enabled: boolean;

  trigger: AlertTrigger;
  severity: AlertSeverity;

  notification_channels: NotificationChannel[];
  recipient_count: number;

  cooldown_minutes: number;
  last_triggered_at?: string;
  trigger_count: number;         // Total triggers

  created_at: string;
  created_by: string;
}

AlertSummaryResponse¶

Dashboard summary of alerts.

interface AlertSummaryResponse {
  // Active alerts
  active_total: number;
  active_critical: number;
  active_high: number;
  active_medium: number;
  active_low: number;

  // Unacknowledged
  unacknowledged_total: number;
  oldest_unacknowledged?: AlertResponse;

  // Recent activity
  alerts_last_24h: number;
  alerts_last_7d: number;

  // By category
  by_category: Array<{
    category: AlertCategory;
    active: number;
    resolved_today: number;
  }>;

  // Recent alerts
  recent_critical: AlertResponse[];
}

Webhook Models¶

WebhookConfig¶

Configuration for webhook notifications.

interface WebhookConfig {
  id: string;
  tenant_id: string;

  name: string;
  url: string;                   // Webhook URL

  // Authentication
  auth_type: WebhookAuthType;
  auth_config?: WebhookAuthConfig;

  // Request configuration
  method: "POST" | "PUT";
  headers?: Record<string, string>;

  // Payload
  payload_template?: string;     // Custom payload template

  // Retry
  retry_count: number;
  retry_delay_seconds: number;

  // Status
  enabled: boolean;
  last_called_at?: string;
  last_status?: number;          // HTTP status code

  // Audit
  created_at: string;
  updated_at: string;
}

enum WebhookAuthType {
  NONE = "none",
  BASIC = "basic",
  BEARER = "bearer",
  API_KEY = "api_key",
  HMAC = "hmac"
}

interface WebhookAuthConfig {
  // For basic auth
  username?: string;
  password?: string;

  // For bearer/api_key
  token?: string;
  header_name?: string;          // For api_key

  // For HMAC
  secret?: string;
  algorithm?: string;            // sha256, sha512
}

WebhookPayload¶

Default webhook payload structure.

interface WebhookPayload {
  event_type: string;
  timestamp: string;

  alert: {
    id: string;
    type: AlertType;
    severity: AlertSeverity;
    title: string;
    message: string;
    triggered_at: string;
  };

  source: AlertSource;

  tenant: {
    id: string;
    name: string;
  };

  metadata: Record<string, any>;
}

Example Usage¶

Creating an Alert Rule¶

import requests

# Create a rule for critical compliance breaches
response = requests.post(
    "https://api.calcbridge.io/api/v1/alerts/rules",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "name": "Critical Compliance Breach Alert",
        "description": "Alert when any critical compliance test fails",
        "trigger": {
            "trigger_type": "compliance_breach",
            "condition": {
                "severity_filter": ["critical"]
            },
            "scope": {
                "all_workbooks": True
            }
        },
        "alert_config": {
            "severity": "critical",
            "title_template": "BREACH: {{test_name}}",
            "message_template": "Test '{{test_name}}' failed with value {{value}} (threshold: {{threshold}})",
            "auto_resolve": True
        },
        "notification_config": {
            "channels": ["email", "slack"],
            "recipients": [
                {"type": "email", "value": "compliance@company.com"},
                {"type": "group", "value": "compliance-team"}
            ],
            "immediate": True,
            "escalation": {
                "enabled": True,
                "levels": [
                    {
                        "delay_minutes": 30,
                        "recipients": [
                            {"type": "email", "value": "manager@company.com"}
                        ]
                    }
                ]
            }
        },
        "cooldown_minutes": 15
    }
)

rule = response.json()
print(f"Created rule: {rule['id']}")

Acknowledging an Alert¶

response = requests.post(
    f"https://api.calcbridge.io/api/v1/alerts/{alert_id}/acknowledge",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "note": "Investigating the breach, will resolve within 2 hours"
    }
)

Getting Alert Summary¶

response = requests.get(
    "https://api.calcbridge.io/api/v1/alerts/summary",
    headers={"Authorization": f"Bearer {token}"}
)

summary = response.json()
print(f"Active Critical: {summary['active_critical']}")
print(f"Unacknowledged: {summary['unacknowledged_total']}")