## Notification Types (`index.ts`)

This file defines the core data structures and enumerations for handling all types of notifications within the MetaTest_v2 system. These types are crucial for ensuring consistency and providing clear contracts for how notification data is stored in Firestore, processed by Cloud Functions, and potentially interpreted by client applications.

### Core Concepts

1.  **`NotificationType` (Enum):**

    - A comprehensive enumeration that categorizes every possible notification sent by the system.
    - Examples: `APPOINTMENT_REMINDER`, `REQUIREMENT_INSTRUCTION_DUE`, `FORM_SUBMISSION_CONFIRMATION`, `PAYMENT_CONFIRMATION`.
    - **Usage:** This enum is used as a discriminator in the `Notification` union type, allowing for type-safe handling of different notification structures.

2.  **`BaseNotification` (Interface):**

    - Defines the common properties shared by all notification types.
    - Includes essential fields like `id`, `userId`, `userRole`, `notificationType`, `notificationTime` (when it should be sent/processed), `title`, `body`, `status`, `isRead`, timestamps (`createdAt`, `updatedAt`, `sentAt`), and various optional linking IDs (`appointmentId`, `patientRequirementInstanceId`, etc.).
    - **Usage:** Specific notification interfaces extend `BaseNotification` to inherit these common fields and add their own type-specific data.

3.  **`NotificationStatus` (Enum):**

    - Defines the lifecycle states of a notification document (e.g., `PENDING`, `PROCESSING`, `SENT`, `FAILED`, `CANCELLED`).
    - **Usage:** Tracks the progress of a notification from creation to sending or cancellation.

4.  **Specific Notification Interfaces (e.g., `RequirementInstructionDueNotification`, `AppointmentReminderNotification`):**

    - Each interface extends `BaseNotification` and defines properties unique to that particular `NotificationType`.
    - They typically make certain linking IDs (like `appointmentId`) mandatory if the notification contextually requires them.
    - **Example `RequirementInstructionDueNotification`:**
      - `notificationType: NotificationType.REQUIREMENT_INSTRUCTION_DUE`
      - `appointmentId: string` (Mandatory link to the appointment)
      - `patientRequirementInstanceId: string` (Mandatory link to the patient-specific requirement instance)
      - `instructionId: string` (Mandatory link to the specific instruction within that instance)
      - The `body` of this notification will contain the actual instruction text (e.g., "Do not eat for 8 hours before your procedure.").
    - **Usage:** These provide strongly-typed structures for creating, storing, and processing each kind of notification.

5.  **`Notification` (Union Type):**
    - A TypeScript union of all specific notification interfaces (`RequirementInstructionDueNotification | AppointmentReminderNotification | ...`).
    - **Usage:** Allows functions and services to handle various notification types polymorphically while still enabling type narrowing based on the `notificationType` property.

### How to Use These Types

- **Creating Notifications:**

  - When a system event occurs (e.g., appointment confirmed, requirement instruction due), a Cloud Function or service will construct a notification object conforming to one of the specific notification interfaces.
  - The `notificationType` must be set correctly.
  - The `notificationTime` should be set to when the notification should be processed (e.g., `Timestamp.now()` for immediate notifications, or a future `Timestamp` for scheduled ones).
  - Relevant linking IDs (`appointmentId`, `patientRequirementInstanceId`, etc.) must be populated to maintain context and enable lifecycle management.
  - The `title` and `body` should be generated with user-friendly content.
  - This notification object is then typically saved to the `notifications` collection in Firestore (its path defined by `NOTIFICATIONS_COLLECTION`).

- **Processing Notifications (e.g., by a sending Cloud Function):**

  - A scheduled Cloud Function (e.g., `processPendingNotifications`) queries the `notifications` collection for documents with `status: NotificationStatus.PENDING` and `notificationTime <= now()`.
  - For each retrieved document (which can be cast to the `Notification` union type):
    - The function can use a `switch` statement or `if/else if` chain on `notification.notificationType` to handle any type-specific logic before sending (though often the `title` and `body` are pre-formatted).
    - The `notificationTokens`, `title`, `body`, and any relevant `data` (for deep linking, derived from linking IDs) are used to construct the push notification message (e.g., `ExpoPushMessage`).
    - The notification's `status` in Firestore is updated (e.g., to `SENT` or `FAILED`).

- **Managing Notification Lifecycles (e.g., Cancellation/Reschedule):**

  - When an event like an appointment cancellation occurs, Cloud Functions will query the `notifications` collection using relevant linking IDs (e.g., `appointmentId`) and `status: NotificationStatus.PENDING`.
  - Found notifications can then have their `status` updated to `NotificationStatus.CANCELLED`.
  - For reschedules, pending notifications might be cancelled and new ones created, or their `notificationTime` might be updated (this logic is handled by higher-level services/functions that use these types).

- **Client Application Usage (Indirect):**
  - Client applications (mobile/web) receive push notifications via services like Expo or FCM.
  - The `data` payload within the received push notification (not directly defined in these Firestore types, but constructed by the sending function) should contain necessary information for deep linking (e.g., `appointmentId`, `screenToOpen`).
  - The client might also fetch a list of notification history from Firestore (e.g., for an in-app notification center), where these types would define the structure of the fetched data.

### Key Considerations

- **Linking IDs:** Proper use of `appointmentId`, `patientRequirementInstanceId`, `instructionId`, etc., is critical for correctly associating notifications with their sources and managing their lifecycle (e.g., cancelling all pending notifications for a cancelled appointment).
- **Clarity of `title` and `body`:** These should be user-friendly and provide actionable information.
- **Deep Linking:** While not defined in these Firestore types, the data sent in the actual push message payload should enable effective deep linking into the relevant parts of the application.
- **Evolution:** As new notification scenarios arise, new `NotificationType` enum members and corresponding specific interfaces should be added, and the main `Notification` union type updated.

This structured approach to notification types ensures scalability, maintainability, and type safety throughout the notification system.
