rename to core

core/notifications/application/index.ts

@@ -0,0 +1,31 @@
+/**
+ * Notifications Application Layer
+ * 
+ * Exports all use cases, queries, and ports.
+ */
+
+// Use Cases
+export * from './use-cases/SendNotificationUseCase';
+export * from './use-cases/MarkNotificationReadUseCase';
+export * from './use-cases/GetUnreadNotificationsUseCase';
+export * from './use-cases/NotificationPreferencesUseCases';
+
+// Ports
+export * from './ports/INotificationGateway';
+
+// Re-export domain types for convenience
+export type {
+  Notification,
+  NotificationProps,
+  NotificationStatus,
+  NotificationData,
+  NotificationUrgency,
+  NotificationAction,
+} from '../domain/entities/Notification';
+export type { NotificationPreference, NotificationPreferenceProps, ChannelPreference, TypePreference } from '../domain/entities/NotificationPreference';
+export type { NotificationType, NotificationChannel } from '../domain/types/NotificationTypes';
+export { getNotificationTypeTitle, getNotificationTypePriority, getChannelDisplayName, isExternalChannel, DEFAULT_ENABLED_CHANNELS, ALL_CHANNELS } from '../domain/types/NotificationTypes';
+
+// Re-export repository interfaces
+export type { INotificationRepository } from '../domain/repositories/INotificationRepository';
+export type { INotificationPreferenceRepository } from '../domain/repositories/INotificationPreferenceRepository';

core/notifications/application/ports/INotificationGateway.ts

@@ -0,0 +1,68 @@
+/**
+ * Application Port: INotificationGateway
+ * 
+ * Defines the contract for sending notifications through external channels.
+ * Implementations (adapters) handle the actual delivery mechanism.
+ */
+
+import type { Notification } from '../../domain/entities/Notification';
+import type { NotificationChannel } from '../../domain/types/NotificationTypes';
+
+export interface NotificationDeliveryResult {
+  success: boolean;
+  channel: NotificationChannel;
+  /** External message ID (e.g., Discord message ID, email ID) */
+  externalId?: string;
+  /** Error message if delivery failed */
+  error?: string;
+  /** Timestamp of delivery attempt */
+  attemptedAt: Date;
+}
+
+export interface INotificationGateway {
+  /**
+   * Send a notification through this gateway's channel
+   */
+  send(notification: Notification): Promise<NotificationDeliveryResult>;
+
+  /**
+   * Check if this gateway supports the given channel
+   */
+  supportsChannel(channel: NotificationChannel): boolean;
+
+  /**
+   * Check if the gateway is configured and ready to send
+   */
+  isConfigured(): boolean;
+
+  /**
+   * Get the channel this gateway handles
+   */
+  getChannel(): NotificationChannel;
+}
+
+/**
+ * Registry for notification gateways
+ * Allows routing notifications to the appropriate gateway based on channel
+ */
+export interface INotificationGatewayRegistry {
+  /**
+   * Register a gateway for a channel
+   */
+  register(gateway: INotificationGateway): void;
+
+  /**
+   * Get gateway for a specific channel
+   */
+  getGateway(channel: NotificationChannel): INotificationGateway | null;
+
+  /**
+   * Get all registered gateways
+   */
+  getAllGateways(): INotificationGateway[];
+
+  /**
+   * Send notification through appropriate gateway
+   */
+  send(notification: Notification): Promise<NotificationDeliveryResult>;
+}

core/notifications/application/ports/INotificationService.ts

@@ -0,0 +1,41 @@
+import type { NotificationType } from '../../domain/types/NotificationTypes';
+import type { NotificationChannel } from '../../domain/types/NotificationTypes';
+
+export interface NotificationData {
+  raceEventId?: string;
+  sessionId?: string;
+  leagueId?: string;
+  position?: number | 'DNF';
+  positionChange?: number;
+  incidents?: number;
+  provisionalRatingChange?: number;
+  finalRatingChange?: number;
+  hadPenaltiesApplied?: boolean;
+  deadline?: Date;
+  protestId?: string;
+  [key: string]: unknown;
+}
+
+export interface NotificationAction {
+  label: string;
+  type: 'primary' | 'secondary' | 'danger';
+  href?: string;
+  actionId?: string;
+}
+
+export interface SendNotificationCommand {
+  recipientId: string;
+  type: NotificationType;
+  title: string;
+  body: string;
+  channel: NotificationChannel;
+  urgency: 'silent' | 'toast' | 'modal';
+  data?: NotificationData;
+  actionUrl?: string;
+  actions?: NotificationAction[];
+  requiresResponse?: boolean;
+}
+
+export interface INotificationService {
+  sendNotification(command: SendNotificationCommand): Promise<void>;
+}

core/notifications/application/use-cases/GetUnreadNotificationsUseCase.ts

@@ -0,0 +1,47 @@
+/**
+ * Application Use Case: GetUnreadNotificationsUseCase
+ * 
+ * Retrieves unread notifications for a recipient.
+ */
+
+import type { AsyncUseCase } from '@gridpilot/shared/application';
+import type { ILogger } from '../../../shared/src/logging/ILogger';
+import type { Notification } from '../../domain/entities/Notification';
+import type { INotificationRepository } from '../../domain/repositories/INotificationRepository';
+
+export interface UnreadNotificationsResult {
+  notifications: Notification[];
+  totalCount: number;
+}
+
+export class GetUnreadNotificationsUseCase implements AsyncUseCase<string, UnreadNotificationsResult> {
+  constructor(
+    private readonly notificationRepository: INotificationRepository,
+    private readonly logger: ILogger,
+  ) {}
+
+  async execute(recipientId: string): Promise<UnreadNotificationsResult> {
+    this.logger.debug(`Attempting to retrieve unread notifications for recipient ID: ${recipientId}`);
+    try {
+      const notifications = await this.notificationRepository.findUnreadByRecipientId(recipientId);
+      this.logger.info(`Successfully retrieved ${notifications.length} unread notifications for recipient ID: ${recipientId}`);
+      
+      if (notifications.length === 0) {
+        this.logger.warn(`No unread notifications found for recipient ID: ${recipientId}`);
+      }
+
+      return {
+        notifications,
+        totalCount: notifications.length,
+      };
+    } catch (error) {
+      this.logger.error(`Failed to retrieve unread notifications for recipient ID: ${recipientId}`, error);
+      throw error;
+    }
+  }
+}
+
+/**
+ * Additional notification query/use case types (e.g., listing or counting notifications)
+ * can be added here in the future as needed.
+ */

core/notifications/application/use-cases/MarkNotificationReadUseCase.ts

@@ -0,0 +1,101 @@
+/**
+ * Application Use Case: MarkNotificationReadUseCase
+ * 
+ * Marks a notification as read.
+ */
+
+import type { AsyncUseCase } from '@gridpilot/shared/application';
+import type { INotificationRepository } from '../../domain/repositories/INotificationRepository';
+import { NotificationDomainError } from '../../domain/errors/NotificationDomainError';
+import type { ILogger } from '../../../shared/src/logging/ILogger';
+
+export interface MarkNotificationReadCommand {
+  notificationId: string;
+  recipientId: string; // For validation
+}
+
+export class MarkNotificationReadUseCase implements AsyncUseCase<MarkNotificationReadCommand, void> {
+  constructor(
+    private readonly notificationRepository: INotificationRepository,
+    private readonly logger: ILogger,
+  ) {}
+
+  async execute(command: MarkNotificationReadCommand): Promise<void> {
+    this.logger.debug(`Attempting to mark notification ${command.notificationId} as read for recipient ${command.recipientId}`);
+    try {
+      const notification = await this.notificationRepository.findById(command.notificationId);
+      
+      if (!notification) {
+        this.logger.warn(`Notification not found for ID: ${command.notificationId}`);
+        throw new NotificationDomainError('Notification not found');
+      }
+
+      if (notification.recipientId !== command.recipientId) {
+        this.logger.warn(`Unauthorized attempt to mark notification ${command.notificationId}. Recipient ID mismatch.`);
+        throw new NotificationDomainError('Cannot mark another user\'s notification as read');
+      }
+
+      if (!notification.isUnread()) {
+        this.logger.info(`Notification ${command.notificationId} is already read. Skipping update.`);
+        return; // Already read, nothing to do
+      }
+
+      const updatedNotification = notification.markAsRead();
+      await this.notificationRepository.update(updatedNotification);
+      this.logger.info(`Notification ${command.notificationId} successfully marked as read.`);
+    } catch (error) {
+      this.logger.error(`Failed to mark notification ${command.notificationId} as read: ${error.message}`);
+      throw error;
+    }
+  }
+}
+
+/**
+ * Application Use Case: MarkAllNotificationsReadUseCase
+ * 
+ * Marks all notifications as read for a recipient.
+ */
+export class MarkAllNotificationsReadUseCase implements AsyncUseCase<string, void> {
+  constructor(
+    private readonly notificationRepository: INotificationRepository,
+  ) {}
+
+  async execute(recipientId: string): Promise<void> {
+    await this.notificationRepository.markAllAsReadByRecipientId(recipientId);
+  }
+}
+
+/**
+ * Application Use Case: DismissNotificationUseCase
+ * 
+ * Dismisses a notification.
+ */
+export interface DismissNotificationCommand {
+  notificationId: string;
+  recipientId: string;
+}
+
+export class DismissNotificationUseCase implements AsyncUseCase<DismissNotificationCommand, void> {
+  constructor(
+    private readonly notificationRepository: INotificationRepository,
+  ) {}
+
+  async execute(command: DismissNotificationCommand): Promise<void> {
+    const notification = await this.notificationRepository.findById(command.notificationId);
+    
+    if (!notification) {
+      throw new NotificationDomainError('Notification not found');
+    }
+
+    if (notification.recipientId !== command.recipientId) {
+      throw new NotificationDomainError('Cannot dismiss another user\'s notification');
+    }
+
+    if (notification.isDismissed()) {
+      return; // Already dismissed
+    }
+
+    const updatedNotification = notification.dismiss();
+    await this.notificationRepository.update(updatedNotification);
+  }
+}

core/notifications/application/use-cases/NotificationPreferencesUseCases.ts

@@ -0,0 +1,157 @@
+/**
+ * Application Use Cases: Notification Preferences
+ * 
+ * Manages user notification preferences.
+ */
+
+import type { AsyncUseCase } from '@gridpilot/shared/application';
+import type { ILogger } from '@gridpilot/shared/logging/ILogger';
+import { NotificationPreference } from '../../domain/entities/NotificationPreference';
+import type { ChannelPreference, TypePreference } from '../../domain/entities/NotificationPreference';
+import type { INotificationPreferenceRepository } from '../../domain/repositories/INotificationPreferenceRepository';
+import type { NotificationType, NotificationChannel } from '../../domain/types/NotificationTypes';
+import { NotificationDomainError } from '../../domain/errors/NotificationDomainError';
+
+/**
+ * Query: GetNotificationPreferencesQuery
+ */
+export class GetNotificationPreferencesQuery implements AsyncUseCase<string, NotificationPreference> {
+  constructor(
+    private readonly preferenceRepository: INotificationPreferenceRepository,
+    private readonly logger: ILogger,
+  ) {}
+
+  async execute(driverId: string): Promise<NotificationPreference> {
+    this.logger.debug(`Fetching notification preferences for driver: ${driverId}`);
+    try {
+      const preferences = await this.preferenceRepository.getOrCreateDefault(driverId);
+      this.logger.info(`Successfully fetched preferences for driver: ${driverId}`);
+      return preferences;
+    } catch (error) {
+      this.logger.error(`Failed to fetch preferences for driver: ${driverId}`, error);
+      throw error;
+    }
+  }
+}
+
+/**
+ * Use Case: UpdateChannelPreferenceUseCase
+ */
+export interface UpdateChannelPreferenceCommand {
+  driverId: string;
+  channel: NotificationChannel;
+  preference: ChannelPreference;
+}
+
+export class UpdateChannelPreferenceUseCase implements AsyncUseCase<UpdateChannelPreferenceCommand, void> {
+  constructor(
+    private readonly preferenceRepository: INotificationPreferenceRepository,
+    private readonly logger: ILogger,
+  ) {}
+
+  async execute(command: UpdateChannelPreferenceCommand): Promise<void> {
+    this.logger.debug(`Updating channel preference for driver: ${command.driverId}, channel: ${command.channel}, preference: ${command.preference}`);
+    try {
+      const preferences = await this.preferenceRepository.getOrCreateDefault(command.driverId);
+      const updated = preferences.updateChannel(command.channel, command.preference);
+      await this.preferenceRepository.save(updated);
+      this.logger.info(`Successfully updated channel preference for driver: ${command.driverId}`);
+    } catch (error) {
+      this.logger.error(`Failed to update channel preference for driver: ${command.driverId}, channel: ${command.channel}`, error);
+      throw error;
+    }
+  }
+}
+
+/**
+ * Use Case: UpdateTypePreferenceUseCase
+ */
+export interface UpdateTypePreferenceCommand {
+  driverId: string;
+  type: NotificationType;
+  preference: TypePreference;
+}
+
+export class UpdateTypePreferenceUseCase implements AsyncUseCase<UpdateTypePreferenceCommand, void> {
+  constructor(
+    private readonly preferenceRepository: INotificationPreferenceRepository,
+    private readonly logger: ILogger,
+  ) {}
+
+  async execute(command: UpdateTypePreferenceCommand): Promise<void> {
+    this.logger.debug(`Updating type preference for driver: ${command.driverId}, type: ${command.type}, preference: ${command.preference}`);
+    try {
+      const preferences = await this.preferenceRepository.getOrCreateDefault(command.driverId);
+      const updated = preferences.updateTypePreference(command.type, command.preference);
+      await this.preferenceRepository.save(updated);
+      this.logger.info(`Successfully updated type preference for driver: ${command.driverId}`);
+    } catch (error) {
+      this.logger.error(`Failed to update type preference for driver: ${command.driverId}, type: ${command.type}`, error);
+      throw error;
+    }
+  }
+}
+
+/**
+ * Use Case: UpdateQuietHoursUseCase
+ */
+export interface UpdateQuietHoursCommand {
+  driverId: string;
+  startHour: number | undefined;
+  endHour: number | undefined;
+}
+
+export class UpdateQuietHoursUseCase implements AsyncUseCase<UpdateQuietHoursCommand, void> {
+  constructor(
+    private readonly preferenceRepository: INotificationPreferenceRepository,
+    private readonly logger: ILogger,
+  ) {}
+
+  async execute(command: UpdateQuietHoursCommand): Promise<void> {
+    this.logger.debug(`Updating quiet hours for driver: ${command.driverId}, startHour: ${command.startHour}, endHour: ${command.endHour}`);
+    try {
+      // Validate hours if provided
+      if (command.startHour !== undefined && (command.startHour < 0 || command.startHour > 23)) {
+        this.logger.warn(`Invalid start hour provided for driver: ${command.driverId}. startHour: ${command.startHour}`);
+        throw new NotificationDomainError('Start hour must be between 0 and 23');
+      }
+      if (command.endHour !== undefined && (command.endHour < 0 || command.endHour > 23)) {
+        this.logger.warn(`Invalid end hour provided for driver: ${command.driverId}. endHour: ${command.endHour}`);
+        throw new NotificationDomainError('End hour must be between 0 and 23');
+      }
+
+      const preferences = await this.preferenceRepository.getOrCreateDefault(command.driverId);
+      const updated = preferences.updateQuietHours(command.startHour, command.endHour);
+      await this.preferenceRepository.save(updated);
+      this.logger.info(`Successfully updated quiet hours for driver: ${command.driverId}`);
+    } catch (error) {
+      this.logger.error(`Failed to update quiet hours for driver: ${command.driverId}`, error);
+      throw error;
+    }
+  }
+}
+
+/**
+ * Use Case: SetDigestModeUseCase
+ */
+export interface SetDigestModeCommand {
+  driverId: string;
+  enabled: boolean;
+  frequencyHours?: number;
+}
+
+export class SetDigestModeUseCase implements AsyncUseCase<SetDigestModeCommand, void> {
+  constructor(
+    private readonly preferenceRepository: INotificationPreferenceRepository,
+  ) {}
+
+  async execute(command: SetDigestModeCommand): Promise<void> {
+    if (command.frequencyHours !== undefined && command.frequencyHours < 1) {
+      throw new NotificationDomainError('Digest frequency must be at least 1 hour');
+    }
+
+    const preferences = await this.preferenceRepository.getOrCreateDefault(command.driverId);
+    const updated = preferences.setDigestMode(command.enabled, command.frequencyHours);
+    await this.preferenceRepository.save(updated);
+  }
+}

core/notifications/application/use-cases/SendNotificationUseCase.ts

@@ -0,0 +1,142 @@
+/**
+ * Application Use Case: SendNotificationUseCase
+ * 
+ * Sends a notification to a recipient through the appropriate channels
+ * based on their preferences.
+ */
+
+import { v4 as uuid } from 'uuid';
+import type { AsyncUseCase } from '@gridpilot/shared/application';
+import type { ILogger } from '../../../shared/src/logging/ILogger';
+import { Notification } from '../../domain/entities/Notification';
+import type { NotificationData } from '../../domain/entities/Notification';
+import type { INotificationRepository } from '../../domain/repositories/INotificationRepository';
+import type { INotificationPreferenceRepository } from '../../domain/repositories/INotificationPreferenceRepository';
+import type { INotificationGatewayRegistry, NotificationDeliveryResult } from '../ports/INotificationGateway';
+import type { NotificationType, NotificationChannel } from '../../domain/types/NotificationTypes';
+
+export interface SendNotificationCommand {
+  recipientId: string;
+  type: NotificationType;
+  title: string;
+  body: string;
+  data?: NotificationData;
+  actionUrl?: string;
+  /** How urgently to display this notification (default: 'silent') */
+  urgency?: 'silent' | 'toast' | 'modal';
+  /** Whether this notification requires a response before dismissal */
+  requiresResponse?: boolean;
+  /** Action buttons for modal notifications */
+  actions?: Array<{
+    label: string;
+    type: 'primary' | 'secondary' | 'danger';
+    href?: string;
+    actionId?: string;
+  }>;
+  /** Override channels (skip preference check) */
+  forceChannels?: NotificationChannel[];
+}
+
+export interface SendNotificationResult {
+  /** The created notification */
+  notification: Notification;
+  /** Delivery results for each channel */
+  deliveryResults: NotificationDeliveryResult[];
+}
+
+export class SendNotificationUseCase implements AsyncUseCase<SendNotificationCommand, SendNotificationResult> {
+  constructor(
+    private readonly notificationRepository: INotificationRepository,
+    private readonly preferenceRepository: INotificationPreferenceRepository,
+    private readonly gatewayRegistry: INotificationGatewayRegistry,
+    private readonly logger: ILogger,
+  ) {
+    this.logger.debug('SendNotificationUseCase initialized.');
+  }
+
+  async execute(command: SendNotificationCommand): Promise<SendNotificationResult> {
+    this.logger.debug('Executing SendNotificationUseCase', { command });
+    try {
+      // Get recipient's preferences
+      this.logger.debug('Checking notification preferences.', { type: command.type, recipientId: command.recipientId });
+      const preferences = await this.preferenceRepository.getOrCreateDefault(command.recipientId);
+
+    // Check if this notification type is enabled
+    if (!preferences.isTypeEnabled(command.type)) {
+      // User has disabled this type - create but don't deliver
+      const notification = Notification.create({
+        id: uuid(),
+        recipientId: command.recipientId,
+        type: command.type,
+        title: command.title,
+        body: command.body,
+        channel: 'in_app',
+        status: 'dismissed', // Auto-dismiss since user doesn't want these
+        ...(command.data ? { data: command.data } : {}),
+        ...(command.actionUrl ? { actionUrl: command.actionUrl } : {}),
+      });
+
+      await this.notificationRepository.create(notification);
+
+      return {
+        notification,
+        deliveryResults: [],
+      };
+    }
+
+    // Determine which channels to use
+    const channels = command.forceChannels ?? preferences.getEnabledChannelsForType(command.type);
+
+    // Check quiet hours (skip external channels during quiet hours)
+    const effectiveChannels = preferences.isInQuietHours()
+      ? channels.filter(ch => ch === 'in_app')
+      : channels;
+
+    // Ensure at least in_app is used
+    if (!effectiveChannels.includes('in_app')) {
+      effectiveChannels.unshift('in_app');
+    }
+
+    const deliveryResults: NotificationDeliveryResult[] = [];
+    let primaryNotification: Notification | null = null;
+
+    // Send through each channel
+    for (const channel of effectiveChannels) {
+      const notification = Notification.create({
+        id: uuid(),
+        recipientId: command.recipientId,
+        type: command.type,
+        title: command.title,
+        body: command.body,
+        channel,
+        ...(command.urgency ? { urgency: command.urgency } : {}),
+        ...(command.data ? { data: command.data } : {}),
+        ...(command.actionUrl ? { actionUrl: command.actionUrl } : {}),
+        ...(command.actions ? { actions: command.actions } : {}),
+        ...(command.requiresResponse !== undefined
+          ? { requiresResponse: command.requiresResponse }
+          : {}),
+      });
+
+      // Save to repository (in_app channel) or attempt delivery (external channels)
+      if (channel === 'in_app') {
+        await this.notificationRepository.create(notification);
+        primaryNotification = notification;
+        deliveryResults.push({
+          success: true,
+          channel,
+          attemptedAt: new Date(),
+        });
+      } else {
+        // Attempt external delivery
+        const result = await this.gatewayRegistry.send(notification);
+        deliveryResults.push(result);
+      }
+    }
+
+    return {
+      notification: primaryNotification!,
+      deliveryResults,
+    };
+  }
+}