wip

packages/notifications/domain/entities/Notification.ts

@@ -1,6 +1,6 @@
 /**
  * Domain Entity: Notification
- * 
+ *
  * Represents a notification sent to a user.
  * Immutable entity with factory methods and domain validation.
  */
@@ -8,7 +8,15 @@
 import type { NotificationType } from '../value-objects/NotificationType';
 import type { NotificationChannel } from '../value-objects/NotificationChannel';
 
-export type NotificationStatus = 'unread' | 'read' | 'dismissed';
+export type NotificationStatus = 'unread' | 'read' | 'dismissed' | 'action_required';
+
+/**
+ * Notification urgency determines how the notification is displayed
+ * - silent: Only appears in notification center (default)
+ * - toast: Shows a temporary toast notification
+ * - modal: Shows a blocking modal that requires user action (cannot be ignored)
+ */
+export type NotificationUrgency = 'silent' | 'toast' | 'modal';
 
 export interface NotificationData {
   /** Reference to related protest */
@@ -29,6 +37,20 @@ export interface NotificationData {
   [key: string]: unknown;
 }
 
+/**
+ * Configuration for action buttons shown on modal notifications
+ */
+export interface NotificationAction {
+  /** Button label */
+  label: string;
+  /** Action type - determines styling */
+  type: 'primary' | 'secondary' | 'danger';
+  /** URL to navigate to when clicked */
+  href?: string;
+  /** Custom action identifier (for handling in code) */
+  actionId?: string;
+}
+
 export interface NotificationProps {
   id: string;
   /** Driver who receives this notification */
@@ -43,22 +65,31 @@ export interface NotificationProps {
   channel: NotificationChannel;
   /** Current status */
   status: NotificationStatus;
+  /** How urgently to display this notification */
+  urgency: NotificationUrgency;
   /** Structured data for linking/context */
   data?: NotificationData;
-  /** Optional action URL */
+  /** Optional action URL (for simple click-through) */
   actionUrl?: string;
+  /** Action buttons for modal notifications */
+  actions?: NotificationAction[];
+  /** Whether this notification requires a response before it can be dismissed */
+  requiresResponse?: boolean;
   /** When the notification was created */
   createdAt: Date;
   /** When the notification was read (if applicable) */
   readAt?: Date;
+  /** When the notification was responded to (for action_required status) */
+  respondedAt?: Date;
 }
 
 export class Notification {
   private constructor(private readonly props: NotificationProps) {}
 
-  static create(props: Omit<NotificationProps, 'status' | 'createdAt'> & { 
+  static create(props: Omit<NotificationProps, 'status' | 'createdAt' | 'urgency'> & {
     status?: NotificationStatus;
     createdAt?: Date;
+    urgency?: NotificationUrgency;
   }): Notification {
     if (!props.id) throw new Error('Notification ID is required');
     if (!props.recipientId) throw new Error('Recipient ID is required');
@@ -67,9 +98,13 @@ export class Notification {
     if (!props.body?.trim()) throw new Error('Notification body is required');
     if (!props.channel) throw new Error('Notification channel is required');
 
+    // Modal notifications that require response start with action_required status
+    const defaultStatus = props.requiresResponse ? 'action_required' : 'unread';
+
     return new Notification({
       ...props,
-      status: props.status ?? 'unread',
+      status: props.status ?? defaultStatus,
+      urgency: props.urgency ?? 'silent',
       createdAt: props.createdAt ?? new Date(),
     });
   }
@@ -81,10 +116,14 @@ export class Notification {
   get body(): string { return this.props.body; }
   get channel(): NotificationChannel { return this.props.channel; }
   get status(): NotificationStatus { return this.props.status; }
+  get urgency(): NotificationUrgency { return this.props.urgency; }
   get data(): NotificationData | undefined { return this.props.data ? { ...this.props.data } : undefined; }
   get actionUrl(): string | undefined { return this.props.actionUrl; }
+  get actions(): NotificationAction[] | undefined { return this.props.actions ? [...this.props.actions] : undefined; }
+  get requiresResponse(): boolean { return this.props.requiresResponse ?? false; }
   get createdAt(): Date { return this.props.createdAt; }
   get readAt(): Date | undefined { return this.props.readAt; }
+  get respondedAt(): Date | undefined { return this.props.respondedAt; }
 
   isUnread(): boolean {
     return this.props.status === 'unread';
@@ -98,6 +137,29 @@ export class Notification {
     return this.props.status === 'dismissed';
   }
 
+  isActionRequired(): boolean {
+    return this.props.status === 'action_required';
+  }
+
+  isSilent(): boolean {
+    return this.props.urgency === 'silent';
+  }
+
+  isToast(): boolean {
+    return this.props.urgency === 'toast';
+  }
+
+  isModal(): boolean {
+    return this.props.urgency === 'modal';
+  }
+
+  /**
+   * Check if this notification can be dismissed without responding
+   */
+  canDismiss(): boolean {
+    return !this.props.requiresResponse || this.props.status !== 'action_required';
+  }
+
   /**
    * Mark the notification as read
    */
@@ -112,6 +174,19 @@ export class Notification {
     });
   }
 
+  /**
+   * Mark that the user has responded to an action_required notification
+   */
+  markAsResponded(actionId?: string): Notification {
+    return new Notification({
+      ...this.props,
+      status: 'read',
+      readAt: this.props.readAt ?? new Date(),
+      respondedAt: new Date(),
+      data: actionId ? { ...this.props.data, responseActionId: actionId } : this.props.data,
+    });
+  }
+
   /**
    * Dismiss the notification
    */
@@ -119,6 +194,10 @@ export class Notification {
     if (this.props.status === 'dismissed') {
       return this; // Already dismissed
     }
+    // Cannot dismiss action_required notifications without responding
+    if (this.props.requiresResponse && this.props.status === 'action_required') {
+      throw new Error('Cannot dismiss notification that requires response');
+    }
     return new Notification({
       ...this.props,
       status: 'dismissed',