feat: implement session timeout, maintenance scheduler, notification …

[Georgechisom]

Summary

This PR implements four critical operational features to enhance the Stellar Bridge Watch platform's reliability, user experience, and incident management capabilities.

1. Session Timeout Modal (#439)

Warn users before logout with countdown timer and session extension capability.

• SessionTimeoutModal — React component for session timeout warnings
  • Countdown timer with visual feedback (minutes and seconds)
  • "Extend Session" action button
  • Auto logout fallback when timer expires
  • Accessible modal with proper ARIA labels
  • Mobile responsive design
  • Low-friction, clear messaging
  • Keyboard navigation support
  • Focus trap for accessibility

Features:

• Visual countdown timer
• One-click session extension
• Automatic logout on timeout
• Warning at 5 minutes before expiry
• Final warning at 1 minute
• Accessible to screen readers
• Mobile-friendly interface
• Prevents data loss from unexpected logouts

User Experience:

• Non-intrusive warning
• Clear call-to-action
• Progress indicator
• Smooth animations
• Keyboard accessible

---

2. Maintenance Window Scheduler (#443)

Schedule maintenance windows and suppress non-critical alerts during approved work periods.

• MaintenanceService — Manages maintenance windows
  • createWindow(window) — Creates new maintenance window
  • getActiveWindows() — Retrieves currently active windows
  • getUpcomingWindows(hours) — Gets windows starting soon
  • isInMaintenanceWindow(scope, identifier) — Checks if in maintenance
  • shouldSuppressAlert(alert) — Determines alert suppression
  • updateWindow(id, updates) — Updates existing window
  • deleteWindow(id) — Removes maintenance window
  • getWindowHistory(limit) — Retrieves historical windows

Features:

• Window creation with start/end times
• Scope control:
  • Global (all systems)
  • Bridge-specific
  • Asset-specific
  • Service-specific
• Alert suppression linkage
• Complete audit trail
• Timezone handling (UTC storage, local display)
• Overlap detection
• Automatic window expiry
• Notification before window starts
• Status tracking (scheduled, active, completed, cancelled)

Database Tables:

• maintenance_windows — Stores maintenance schedules
• Indexes for efficient querying by scope and time

API Endpoints:

• POST /api/v1/maintenance — Create maintenance window
• GET /api/v1/maintenance — List all windows
• GET /api/v1/maintenance/active — Get active windows
• GET /api/v1/maintenance/upcoming — Get upcoming windows
• GET /api/v1/maintenance/:id — Get specific window
• PUT /api/v1/maintenance/:id — Update window
• DELETE /api/v1/maintenance/:id — Delete window
• GET /api/v1/maintenance/history — Get window history
• POST /api/v1/maintenance/:id/cancel — Cancel window

---

3. Notification Template Service (#442)

Manage reusable notification templates for email, webhook, and in-app delivery.

• NotificationTemplateService — Manages notification templates
  • createTemplate(template) — Creates new template
  • getTemplate(id) — Retrieves template by ID
  • getAllTemplates(channel) — Lists templates by channel
  • updateTemplate(id, updates) — Updates existing template
  • deleteTemplate(id) — Removes template
  • previewTemplate(id, variables) — Previews with sample data
  • validateVariables(template, variables) — Validates variable usage
  • renderTemplate(id, variables) — Renders final content
  • getTemplateVersions(id) — Retrieves version history

Features:

• Template CRUD operations
• Preview support with variable substitution
• Variable validation (required vs. optional)
• Channel variants:
  • Email (subject + body)
  • Webhook (JSON payload)
  • In-app (title + message)
  • SMS (short message)
• Template versioning (auto-incremented)
• Approval flow ready (status: draft, approved, archived)
• Variable syntax: {{variable_name}}
• Default values: {{variable_name:default}}
• Conditional blocks support
• Template categories (alert, report, notification, system)

Database Tables:

• notification_templates — Stores templates
• notification_template_versions — Tracks changes

API Endpoints:

• POST /api/v1/notification-templates — Create template
• GET /api/v1/notification-templates — List templates
• GET /api/v1/notification-templates/:id — Get template
• PUT /api/v1/notification-templates/:id — Update template
• DELETE /api/v1/notification-templates/:id — Delete template
• POST /api/v1/notification-templates/:id/preview — Preview template
• GET /api/v1/notification-templates/:id/versions — Get versions
• POST /api/v1/notification-templates/:id/approve — Approve template

Template Example:

Subject: {{alert_type}} Alert for {{asset_symbol}}
Body:
Alert detected at {{timestamp}}.
Severity: {{severity}}
Current value: {{current_value}}
Threshold: {{threshold}}
Action required: {{action:No action required}}

---

4. Incident Escalation Engine (#448)

Automatically escalate unresolved incidents based on severity, duration, and routing rules.

• EscalationService — Manages incident escalation
  • createEscalationRule(rule) — Creates escalation rule
  • checkEscalations() — Checks all incidents for escalation
  • escalateIncident(incidentId) — Manually escalates incident
  • acknowledgeIncident(incidentId, acknowledgedBy) — Acknowledges incident
  • resolveIncident(incidentId, resolvedBy) — Resolves incident
  • getEscalationHistory(incidentId) — Gets escalation audit trail
  • updateEscalationRule(id, updates) — Updates rule
  • getActiveEscalations() — Lists active escalations

Features:

• Escalation timers based on severity:
  • Critical: 5 minutes
  • High: 15 minutes
  • Medium: 30 minutes
  • Low: 60 minutes
• Severity thresholds configuration
• Route changes:
  • Level 1: On-call engineer
  • Level 2: Team lead
  • Level 3: Engineering manager
  • Level 4: Director/VP
• Acknowledgement handling:
  • Stops escalation timer
  • Requires resolution within SLA
  • Tracks acknowledgement time
• Complete audit history:
  • All escalation events
  • Route changes
  • Acknowledgements
  • Resolutions
• Retry safety mechanisms:
  • Prevents duplicate escalations
  • Handles notification failures
  • Exponential backoff for retries
• Escalation policies:
  • Time-based
  • Severity-based
  • Custom routing rules

Database Tables:

• escalation_rules — Escalation policies
• escalation_history — Audit trail

API Endpoints:

• POST /api/v1/incidents/:id/escalate — Escalate incident
• POST /api/v1/incidents/:id/acknowledge — Acknowledge incident
• POST /api/v1/incidents/:id/resolve — Resolve incident
• GET /api/v1/incidents/:id/escalations — Get escalation history
• POST /api/v1/escalation-rules — Create escalation rule
• GET /api/v1/escalation-rules — List rules
• PUT /api/v1/escalation-rules/:id — Update rule
• DELETE /api/v1/escalation-rules/:id — Delete rule

Escalation Flow:

1. Incident created → Start timer
2. Timer expires → Escalate to Level 2
3. Still unacknowledged → Escalate to Level 3
4. Acknowledged → Stop escalation, start resolution timer
5. Resolved → Close incident, log metrics

---

Database Migrations

Migration 011: Maintenance Windows

• Creates maintenance_windows table
• Adds indexes for scope and time queries
• Supports timezone-aware scheduling

Migration 012: Notification Templates

• Creates notification_templates table
• Creates notification_template_versions table
• Adds indexes for channel and status

Migration 013: Incident Escalation

• Creates escalation_rules table
• Creates escalation_history table
• Adds indexes for incident and timestamp queries

---

API Documentation

Maintenance Windows

// Create maintenance window
POST /api/v1/maintenance
Body: {
  title: "Database Upgrade",
  description: "Upgrading PostgreSQL",
  scope: "global" | "bridge" | "asset" | "service",
  identifier: "bridge-usdc" (optional),
  start_time: "2024-04-15T02:00:00Z",
  end_time: "2024-04-15T04:00:00Z",
  suppress_alerts: true,
  created_by: "admin@example.com"
}

// Check if in maintenance
GET /api/v1/maintenance/check?scope=bridge&identifier=bridge-usdc
Response: { in_maintenance: boolean, window: MaintenanceWindow | null }

Notification Templates

// Create template
POST /api/v1/notification-templates
Body: {
  name: "Price Alert Template",
  channel: "email",
  category: "alert",
  subject: "{{alert_type}} for {{asset}}",
  body: "Price: {{price}}, Threshold: {{threshold}}",
  variables: ["alert_type", "asset", "price", "threshold"],
  status: "draft"
}

// Preview template
POST /api/v1/notification-templates/:id/preview
Body: {
  variables: {
    alert_type: "Price Deviation",
    asset: "USDC",
    price: "0.998",
    threshold: "0.995"
  }
}

Incident Escalation

// Escalate incident
POST /api/v1/incidents/:id/escalate
Body: { escalated_by: "system", reason: "Timeout" }

// Acknowledge incident
POST /api/v1/incidents/:id/acknowledge
Body: { acknowledged_by: "engineer@example.com", notes: "Investigating" }

---

Testing

All features include:

• Unit tests for service logic
• Integration tests for API endpoints
• Error handling tests
• Edge case coverage

Test Coverage:

• MaintenanceService: Window creation, overlap detection, alert suppression
• NotificationTemplateService: Template rendering, variable validation, versioning
• EscalationService: Timer logic, escalation rules, acknowledgement flow
• SessionTimeoutModal: Countdown, extension, logout

---

Security Considerations

• Session timeout prevents unauthorized access
• Maintenance windows require admin privileges
• Template approval workflow prevents malicious templates
• Escalation rules prevent privilege escalation
• All actions logged in audit trail
• Input validation on all endpoints
• SQL injection prevention
• XSS protection in templates

---

Performance Considerations

Maintenance Windows:

• Indexed queries for fast lookups
• Cached active windows in Redis
• Efficient overlap detection

Notification Templates:

• Template caching
• Lazy loading of versions
• Efficient variable substitution

Incident Escalation:

• Background job for escalation checks
• Batch processing of incidents
• Retry queue for failed notifications

Session Timeout:

• Client-side timer (no server polling)
• Minimal network requests
• Efficient token refresh

---

Future Enhancements

Maintenance Windows:

• Recurring maintenance schedules
• Maintenance calendar view
• Integration with change management systems
• Automatic rollback on failures

Notification Templates:

• Rich text editor
• Template marketplace
• A/B testing support
• Multi-language templates

Incident Escalation:

• Machine learning for smart routing
• Integration with PagerDuty/Opsgenie
• Escalation analytics
• Custom escalation workflows

Session Timeout:

• Configurable timeout duration
• Activity-based extension
• Multi-tab synchronization
• Remember me option

---

Breaking Changes

None. All changes are additive and backward compatible.

---

Migration Guide

1. Run database migrations:

npm run migrate --workspace=backend

2. Configure session timeout (optional):

// In your auth config
SESSION_TIMEOUT_MINUTES = 30;
SESSION_WARNING_MINUTES = 5;

3. Create default notification templates:

npm run seed:templates --workspace=backend

4. Configure escalation rules:

# Via API or admin UI
POST /api/v1/escalation-rules

---

Closes

Closes #439
Closes #443
Closes #442
Closes #448

---

Checklist

• ✅ Code follows project style guidelines
• ✅ Self-review completed
• ✅ Code commented where necessary
• ✅ Documentation updated
• ✅ No new warnings generated
• ✅ Tests added (unit + integration)
• ✅ No breaking changes
• ✅ Database migrations included
• ✅ API endpoints documented
• ✅ Security considerations addressed
• ✅ Performance optimized
• ✅ Accessibility compliant (Session Timeout Modal)

[drips-wave]

@Georgechisom Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[Georgechisom]

confict fixed, kindly merge @Mosas2000