Add tier-based scan scheduler and webhook triggers (FRE-4498)

- ScanScheduler: tier-based scheduling (BASIC=24h, PLUS=6h, PREMIUM=1h)
- WebhookHandler: HMAC-verified webhook ingestion with SCAN_TRIGGER support
- API routes: /scheduler and /webhooks endpoints under /api/v1/darkwatch
- Jobs: scheduled scan checker + webhook retry processor via BullMQ
- Schema: ScanSchedule, WebhookEvent models; ScanJob.scheduledBy field
- Types: ScheduleStatus, WebhookEventType, WebhookTriggerInput
- Tests: scheduler lifecycle + webhook signature/processing tests

Co-Authored-By: Paperclip <noreply@paperclip.ing>

packages/shared-notifications/src/services/email.service.ts

@@ -0,0 +1,96 @@
+import { Resend } from 'resend';
+import { loadNotificationConfig } from '../config/notification.config';
+import type { EmailNotification, NotificationResult } from '../types/notification.types';
+
+const config = loadNotificationConfig();
+const resend = new Resend(config.resend.apiKey);
+
+export class EmailService {
+  private static instance: EmailService;
+  private sentCount = new Map<string, number>();
+  private cleanupInterval: NodeJS.Timeout;
+
+  private constructor() {
+    this.cleanupInterval = setInterval(() => {
+      const now = Date.now();
+      for (const [key, timestamp] of this.sentCount.entries()) {
+        if (now - timestamp > 60000) {
+          this.sentCount.delete(key);
+        }
+      }
+    }, 60000);
+  }
+
+  static getInstance(): EmailService {
+    if (!EmailService.instance) {
+      EmailService.instance = new EmailService();
+    }
+    return EmailService.instance;
+  }
+
+  async send(notification: EmailNotification): Promise<NotificationResult> {
+    const rateLimitKey = `email:${notification.to}`;
+    const currentCount = this.sentCount.get(rateLimitKey) || 0;
+
+    if (currentCount >= config.rateLimits.emailPerMinute) {
+      throw new Error(`Email rate limit exceeded for ${notification.to}`);
+    }
+
+    try {
+      const { data, error } = await resend.emails.send({
+        from: notification.from || 'ShieldAI <noreply@shieldai.com>',
+        to: [notification.to],
+        subject: notification.subject,
+        html: notification.htmlBody,
+        text: notification.textBody,
+        metadata: notification.metadata,
+        attachments: notification.attachments?.map(att => ({
+          filename: att.filename,
+          data: att.content,
+          contentType: att.mimeType,
+        })),
+      });
+
+      if (error) {
+        return {
+          notificationId: `email-${Date.now()}`,
+          channel: 'email',
+          status: 'failed',
+          externalId: data?.id,
+          error: error.message,
+        };
+      }
+
+      this.sentCount.set(rateLimitKey, currentCount + 1);
+
+      return {
+        notificationId: `email-${data?.id || Date.now()}`,
+        channel: 'email',
+        status: 'sent',
+        externalId: data?.id,
+        deliveredAt: new Date(),
+      };
+    } catch (error) {
+      return {
+        notificationId: `email-${Date.now()}`,
+        channel: 'email',
+        status: 'failed',
+        error: error instanceof Error ? error.message : 'Unknown error',
+      };
+    }
+  }
+
+  async sendBatch(notifications: EmailNotification[]): Promise<NotificationResult[]> {
+    const results = await Promise.all(
+      notifications.map(n => this.send(n))
+    );
+    return results;
+  }
+
+  getRateLimitStatus(): { remaining: number; limit: number } {
+    return {
+      remaining: config.rateLimits.emailPerMinute - this.sentCount.size,
+      limit: config.rateLimits.emailPerMinute,
+    };
+  }
+}

packages/shared-notifications/src/services/notification.service.ts

@@ -0,0 +1,145 @@
+import { EmailService } from './email.service';
+import { SMSService } from './sms.service';
+import { PushService } from './push.service';
+import type { 
+  Notification, 
+  NotificationResult,
+  NotificationPreference,
+  DeduplicationKey 
+} from '../types/notification.types';
+
+export class NotificationService {
+  private static instance: NotificationService;
+  private emailService: EmailService;
+  private smsService: SMSService;
+  private pushService: PushService;
+  private pendingDeduplication = new Map<string, Set<string>>();
+  private preferenceCache = new Map<string, NotificationPreference>();
+
+  private constructor() {
+    this.emailService = EmailService.getInstance();
+    this.smsService = SMSService.getInstance();
+    this.pushService = PushService.getInstance();
+  }
+
+  static getInstance(): NotificationService {
+    if (!NotificationService.instance) {
+      NotificationService.instance = new NotificationService();
+    }
+    return NotificationService.instance;
+  }
+
+  async send(notification: Notification): Promise<NotificationResult> {
+    switch (notification.channel) {
+      case 'email':
+        return this.emailService.send(notification);
+      case 'sms':
+        return this.smsService.send(notification);
+      case 'push':
+        return this.pushService.send(notification);
+      default:
+        throw new Error(`Unknown notification channel: ${(notification as any).channel}`);
+    }
+  }
+
+  async sendWithDeduplication(
+    notification: Notification,
+    dedupKey: DeduplicationKey
+  ): Promise<NotificationResult> {
+    const dedupId = `${dedupKey.userId}:${dedupKey.templateId}:${dedupKey.key}`;
+    const windowSet = this.pendingDeduplication.get(dedupId);
+
+    if (windowSet && windowSet.size > 0) {
+      return {
+        notificationId: `dedup-${Date.now()}`,
+        channel: notification.channel,
+        status: 'pending',
+        error: 'Duplicate notification within deduplication window',
+      };
+    }
+
+    const result = await this.send(notification);
+
+    if (result.status === 'sent') {
+      if (!windowSet) {
+        this.pendingDeduplication.set(dedupId, new Set());
+      }
+      this.pendingDeduplication.get(dedupId)!.add(result.externalId!);
+    }
+
+    return result;
+  }
+
+  async setPreference(
+    userId: string,
+    channel: NotificationPreference['channel'],
+    enabled: boolean,
+    categories?: string[]
+  ): Promise<NotificationPreference> {
+    const preference: NotificationPreference = {
+      userId,
+      channel,
+      enabled,
+      categories: categories || [],
+      updatedAt: new Date(),
+    };
+
+    this.preferenceCache.set(`${userId}:${channel}`, preference);
+    return preference;
+  }
+
+  async getPreference(
+    userId: string,
+    channel: NotificationPreference['channel']
+  ): Promise<NotificationPreference | null> {
+    return this.preferenceCache.get(`${userId}:${channel}`) || null;
+  }
+
+  async shouldSend(
+    userId: string,
+    channel: NotificationPreference['channel'],
+    category: string
+  ): Promise<boolean> {
+    const preference = await this.getPreference(userId, channel);
+    
+    if (!preference) {
+      return true;
+    }
+
+    if (!preference.enabled) {
+      return false;
+    }
+
+    if (preference.categories.length === 0) {
+      return true;
+    }
+
+    return preference.categories.includes(category);
+  }
+
+  async sendWithPreferences(
+    notification: Notification,
+    category: string
+  ): Promise<NotificationResult | null> {
+    const userId = notification.channel === 'push' 
+      ? notification.userId 
+      : `user-${Date.now()}`;
+
+    const shouldSend = await this.shouldSend(
+      userId,
+      notification.channel,
+      category
+    );
+
+    if (!shouldSend) {
+      return {
+        notificationId: `pref-${Date.now()}`,
+        channel: notification.channel,
+        status: 'pending',
+        error: 'Notification disabled for user preference',
+      };
+    }
+
+    return this.send(notification);
+  }
+}

packages/shared-notifications/src/services/push.service.ts

@@ -0,0 +1,112 @@
+import admin from 'firebase-admin';
+import { loadNotificationConfig } from '../config/notification.config';
+import type { PushNotification, NotificationResult } from '../types/notification.types';
+
+const config = loadNotificationConfig();
+
+let fcmApp: admin.app.App | null = null;
+
+function getFCMApp(): admin.app.App {
+  if (!fcmApp) {
+    fcmApp = admin.initializeApp({
+      credential: admin.credential.cert({
+        projectId: config.fcm.projectId,
+        clientEmail: config.fcm.clientEmail,
+        privateKey: config.fcm.privateKey.replace(/\\n/g, '\n'),
+      }),
+    });
+  }
+  return fcmApp;
+}
+
+export class PushService {
+  private static instance: PushService;
+  private sentCount = new Map<string, number>();
+  private cleanupInterval: NodeJS.Timeout;
+
+  private constructor() {
+    this.cleanupInterval = setInterval(() => {
+      const now = Date.now();
+      for (const [key, timestamp] of this.sentCount.entries()) {
+        if (now - timestamp > 60000) {
+          this.sentCount.delete(key);
+        }
+      }
+    }, 60000);
+  }
+
+  static getInstance(): PushService {
+    if (!PushService.instance) {
+      PushService.instance = new PushService();
+    }
+    return PushService.instance;
+  }
+
+  async send(notification: PushNotification): Promise<NotificationResult> {
+    const rateLimitKey = `push:${notification.userId}`;
+    const currentCount = this.sentCount.get(rateLimitKey) || 0;
+
+    if (currentCount >= config.rateLimits.pushPerMinute) {
+      throw new Error(`Push rate limit exceeded for user ${notification.userId}`);
+    }
+
+    try {
+      const fcmApp = getFCMApp();
+      const messaging = admin.messaging(fcmApp);
+
+      const message: admin.messaging.Message = {
+        notification: {
+          title: notification.title,
+          body: notification.body,
+        },
+        data: notification.data ? 
+          Object.fromEntries(
+            Object.entries(notification.data).map(([k, v]) => [k, String(v)])
+          ) : undefined,
+        token: notification.userId,
+        apns: {
+          payload: {
+            aps: {
+              badge: notification.badge,
+              sound: notification.sound || 'default',
+              category: notification.category,
+            },
+          },
+        },
+      };
+
+      const response = await messaging.send(message);
+
+      this.sentCount.set(rateLimitKey, currentCount + 1);
+
+      return {
+        notificationId: `push-${response}`,
+        channel: 'push',
+        status: 'sent',
+        externalId: response,
+        deliveredAt: new Date(),
+      };
+    } catch (error) {
+      return {
+        notificationId: `push-${Date.now()}`,
+        channel: 'push',
+        status: 'failed',
+        error: error instanceof Error ? error.message : 'Unknown error',
+      };
+    }
+  }
+
+  async sendBatch(notifications: PushNotification[]): Promise<NotificationResult[]> {
+    const results = await Promise.all(
+      notifications.map(n => this.send(n))
+    );
+    return results;
+  }
+
+  getRateLimitStatus(): { remaining: number; limit: number } {
+    return {
+      remaining: config.rateLimits.pushPerMinute - this.sentCount.size,
+      limit: config.rateLimits.pushPerMinute,
+    };
+  }
+}

packages/shared-notifications/src/services/sms.service.ts

@@ -0,0 +1,82 @@
+import twilio from 'twilio';
+import { loadNotificationConfig } from '../config/notification.config';
+import type { SMSNotification, NotificationResult } from '../types/notification.types';
+
+const config = loadNotificationConfig();
+const twilioClient = twilio(
+  config.twilio.accountSid,
+  config.twilio.authToken
+);
+
+export class SMSService {
+  private static instance: SMSService;
+  private sentCount = new Map<string, number>();
+  private cleanupInterval: NodeJS.Timeout;
+
+  private constructor() {
+    this.cleanupInterval = setInterval(() => {
+      const now = Date.now();
+      for (const [key, timestamp] of this.sentCount.entries()) {
+        if (now - timestamp > 60000) {
+          this.sentCount.delete(key);
+        }
+      }
+    }, 60000);
+  }
+
+  static getInstance(): SMSService {
+    if (!SMSService.instance) {
+      SMSService.instance = new SMSService();
+    }
+    return SMSService.instance;
+  }
+
+  async send(notification: SMSNotification): Promise<NotificationResult> {
+    const rateLimitKey = `sms:${notification.to}`;
+    const currentCount = this.sentCount.get(rateLimitKey) || 0;
+
+    if (currentCount >= config.rateLimits.smsPerMinute) {
+      throw new Error(`SMS rate limit exceeded for ${notification.to}`);
+    }
+
+    try {
+      const message = await twilioClient.messages.create({
+        body: notification.body,
+        from: notification.from || config.twilio.messagingServiceSid,
+        to: notification.to,
+        metadata: notification.metadata,
+      });
+
+      this.sentCount.set(rateLimitKey, currentCount + 1);
+
+      return {
+        notificationId: `sms-${message.sid}`,
+        channel: 'sms',
+        status: 'sent',
+        externalId: message.sid,
+        deliveredAt: new Date(),
+      };
+    } catch (error) {
+      return {
+        notificationId: `sms-${Date.now()}`,
+        channel: 'sms',
+        status: 'failed',
+        error: error instanceof Error ? error.message : 'Unknown error',
+      };
+    }
+  }
+
+  async sendBatch(notifications: SMSNotification[]): Promise<NotificationResult[]> {
+    const results = await Promise.all(
+      notifications.map(n => this.send(n))
+    );
+    return results;
+  }
+
+  getRateLimitStatus(): { remaining: number; limit: number } {
+    return {
+      remaining: config.rateLimits.smsPerMinute - this.sentCount.size,
+      limit: config.rateLimits.smsPerMinute,
+    };
+  }
+}