@blackcode_sa/metaestetics-api 1.6.2 → 1.6.4

package/src/types/notifications/README.md

@@ -0,0 +1,77 @@
+## 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.

package/src/types/notifications/index.ts

@@ -4,10 +4,30 @@ import { UserRole } from "../";
  * Enumeracija koja definiše sve moguće tipove notifikacija
  */
 export enum NotificationType {
-  PRE_REQUIREMENT = "preRequirement",
-  POST_REQUIREMENT = "postRequirement",
-  APPOINTMENT_REMINDER = "appointmentReminder",
-  APPOINTMENT_NOTIFICATION = "appointmentNotification",
+  // --- Appointment Lifecycle & Reminders ---
+  APPOINTMENT_REMINDER = "appointmentReminder", // For upcoming appointments
+  APPOINTMENT_STATUS_CHANGE = "appointmentStatusChange", // Generic for status changes like confirmed, checked-in etc.
+  APPOINTMENT_RESCHEDULED_PROPOSAL = "appointmentRescheduledProposal", // When clinic proposes a new time
+  APPOINTMENT_CANCELLED = "appointmentCancelled", // When an appointment is cancelled
+
+  // --- Requirement-Driven Instructions ---
+  REQUIREMENT_INSTRUCTION_DUE = "requirementInstructionDue", // For specific pre/post care instructions
+
+  // --- Form Related ---
+  FORM_REMINDER = "formReminder", // Reminds user to fill a specific form
+  FORM_SUBMISSION_CONFIRMATION = "formSubmissionConfirmation", // Confirms form was submitted
+
+  // --- Patient Engagement ---
+  REVIEW_REQUEST = "reviewRequest", // Request for patient review post-appointment
+
+  // --- Payment Related (Examples) ---
+  PAYMENT_DUE = "paymentDue",
+  PAYMENT_CONFIRMATION = "paymentConfirmation",
+  PAYMENT_FAILED = "paymentFailed",
+
+  // --- General & Administrative ---
+  GENERAL_MESSAGE = "generalMessage", // For general announcements or direct messages
+  ACCOUNT_NOTIFICATION = "accountNotification", // e.g., password change, security alert
 }
 
 export const NOTIFICATIONS_COLLECTION = "notifications";
@@ -57,6 +77,16 @@ export interface BaseNotification {
 
   /** Uloga korisnika kome je namenjena notifikacija */
   userRole: UserRole;
+
+  // --- Optional Linking IDs ---
+  // These help in managing notifications and for deep-linking in the app.
+  appointmentId?: string; // Associated appointment
+  patientRequirementInstanceId?: string; // Link to PatientRequirementInstance in patient's subcollection
+  instructionId?: string; // Specific instruction ID within a PatientRequirementInstance
+  formId?: string; // Associated form (FilledDocument ID)
+  originalRequirementId?: string; // ID of the base Requirement template
+  transactionId?: string; // Associated payment transaction
+  // Add other relevant linking IDs as needed, e.g., clinicId, practitionerId if notification is for them
 }
 
 /**
@@ -64,8 +94,10 @@ export interface BaseNotification {
  */
 export enum NotificationStatus {
   PENDING = "pending",
+  PROCESSING = "processing",
   SENT = "sent",
   FAILED = "failed",
+  DELIVERED = "delivered",
   CANCELLED = "cancelled",
   PARTIAL_SUCCESS = "partialSuccess",
 }
@@ -74,7 +106,7 @@ export enum NotificationStatus {
  * Notifikacija za pre-requirement
  */
 export interface PreRequirementNotification extends BaseNotification {
-  notificationType: NotificationType.PRE_REQUIREMENT;
+  notificationType: NotificationType.REQUIREMENT_INSTRUCTION_DUE;
   /** ID tretmana za koji je vezan pre-requirement */
   treatmentId: string;
   /** Lista pre-requirements koji treba da se ispune */
@@ -87,7 +119,7 @@ export interface PreRequirementNotification extends BaseNotification {
  * Notifikacija za post-requirement
  */
 export interface PostRequirementNotification extends BaseNotification {
-  notificationType: NotificationType.POST_REQUIREMENT;
+  notificationType: NotificationType.REQUIREMENT_INSTRUCTION_DUE;
   /** ID tretmana za koji je vezan post-requirement */
   treatmentId: string;
   /** Lista post-requirements koji treba da se ispune */
@@ -97,33 +129,120 @@ export interface PostRequirementNotification extends BaseNotification {
 }
 
 /**
- * Notifikacija za podsetnik o zakazanom terminu
+ * Notification for a specific instruction from a PatientRequirementInstance.
+ * Example: "Do not eat 2 hours before your [Procedure Name] appointment."
+ */
+export interface RequirementInstructionDueNotification
+  extends BaseNotification {
+  notificationType: NotificationType.REQUIREMENT_INSTRUCTION_DUE;
+  appointmentId: string; // Mandatory
+  patientRequirementInstanceId: string; // Mandatory
+  instructionId: string; // Mandatory
+  // The 'body' will contain the specific instruction text.
+  // 'title' could be "Upcoming: [Requirement Name]" or similar.
+}
+
+/**
+ * Notification reminding about an upcoming appointment.
+ * Example: "Reminder: Your appointment for [Procedure Name] is at [Time] today."
  */
 export interface AppointmentReminderNotification extends BaseNotification {
   notificationType: NotificationType.APPOINTMENT_REMINDER;
-  /** ID zakazanog termina */
-  appointmentId: string;
-  /** Vreme termina */
-  appointmentTime: Timestamp;
-  /** Tip tretmana */
-  treatmentType: string;
-  /** Ime doktora */
-  doctorName: string;
+  appointmentId: string; // Mandatory
+  appointmentTime: Timestamp; // For easy access to construct message body
+  procedureName?: string;
+  practitionerName?: string;
+  clinicName?: string;
+}
+
+/**
+ * Notification about a change in appointment status (e.g., confirmed, checked-in).
+ * Excludes cancellations and reschedule proposals, which have their own types.
+ * Example: "Your appointment for [Procedure Name] has been Confirmed."
+ */
+export interface AppointmentStatusChangeNotification extends BaseNotification {
+  notificationType: NotificationType.APPOINTMENT_STATUS_CHANGE;
+  appointmentId: string; // Mandatory
+  newStatus: string; // The new AppointmentStatus (e.g., "CONFIRMED", "CHECKED_IN")
+  previousStatus?: string;
+  procedureName?: string;
+}
+
+/**
+ * Notification informing the patient that the clinic has proposed a new time for their appointment.
+ * Example: "Action Required: [Clinic Name] has proposed a new time for your [Procedure Name] appointment."
+ */
+export interface AppointmentRescheduledProposalNotification
+  extends BaseNotification {
+  notificationType: NotificationType.APPOINTMENT_RESCHEDULED_PROPOSAL;
+  appointmentId: string; // Mandatory
+  newProposedStartTime: Timestamp;
+  newProposedEndTime: Timestamp;
+  procedureName?: string;
+  // May include a deep link to confirm/reject reschedule.
 }
 
 /**
- * Notifikacija o promeni statusa termina
+ * Notification informing about a cancelled appointment.
+ * Example: "Your appointment for [Procedure Name] on [Date] has been cancelled."
  */
-export interface AppointmentNotification extends BaseNotification {
-  notificationType: NotificationType.APPOINTMENT_NOTIFICATION;
-  /** ID zakazanog termina */
-  appointmentId: string;
-  /** Novi status termina */
-  appointmentStatus: string;
-  /** Prethodni status termina */
-  previousStatus: string;
-  /** Razlog promene (opciono) */
-  reason?: string;
+export interface AppointmentCancelledNotification extends BaseNotification {
+  notificationType: NotificationType.APPOINTMENT_CANCELLED;
+  appointmentId: string; // Mandatory
+  reason?: string; // Reason for cancellation
+  cancelledByRole?: UserRole; // Who initiated the cancellation (PATIENT, CLINIC_ADMIN, etc.)
+  procedureName?: string;
+}
+
+/**
+ * Notification reminding a user to fill a specific form.
+ * Example: "Reminder: Please complete the '[Form Name]' form for your upcoming appointment."
+ */
+export interface FormReminderNotification extends BaseNotification {
+  notificationType: NotificationType.FORM_REMINDER;
+  appointmentId: string; // Associated appointment for which the form is required
+  formId: string; // The ID of the FilledDocument instance
+  formName: string; // Display name of the form
+  formDeadline?: Timestamp; // Optional: When the form is due
+}
+
+/**
+ * Notification confirming a form submission.
+ * Example: "Thank you! Your '[Form Name]' form has been submitted successfully."
+ */
+export interface FormSubmissionConfirmationNotification
+  extends BaseNotification {
+  notificationType: NotificationType.FORM_SUBMISSION_CONFIRMATION;
+  appointmentId?: string; // Optional, if form is tied to an appointment
+  formId: string;
+  formName: string;
+}
+
+/**
+ * Notification requesting a patient to leave a review after an appointment.
+ * Example: "Hope you had a great experience! Would you like to share your feedback for your visit on [Date]?"
+ */
+export interface ReviewRequestNotification extends BaseNotification {
+  notificationType: NotificationType.REVIEW_REQUEST;
+  appointmentId: string; // The completed appointment for which review is requested
+  practitionerName?: string;
+  procedureName?: string;
+}
+
+/**
+ * Generic notification for direct messages or announcements.
+ */
+export interface GeneralMessageNotification extends BaseNotification {
+  notificationType: NotificationType.GENERAL_MESSAGE;
+  // Could have senderId, conversationId etc. if it's for a chat-like feature
+}
+
+// Example Payment Notification (can be expanded)
+export interface PaymentConfirmationNotification extends BaseNotification {
+  notificationType: NotificationType.PAYMENT_CONFIRMATION;
+  transactionId: string;
+  appointmentId?: string;
+  amount: string; // e.g., "€50.00"
 }
 
 /**
@@ -132,5 +251,13 @@ export interface AppointmentNotification extends BaseNotification {
 export type Notification =
   | PreRequirementNotification
   | PostRequirementNotification
+  | RequirementInstructionDueNotification
   | AppointmentReminderNotification
-  | AppointmentNotification;
+  | AppointmentStatusChangeNotification
+  | AppointmentRescheduledProposalNotification
+  | AppointmentCancelledNotification
+  | FormReminderNotification
+  | FormSubmissionConfirmationNotification
+  | ReviewRequestNotification
+  | GeneralMessageNotification
+  | PaymentConfirmationNotification;

package/src/types/patient/index.ts

@@ -237,3 +237,9 @@ export interface PatientProfileComplete {
   patientMedicalInfo?: PatientMedicalInfo;
   patientLocationInfo?: PatientLocationInfo;
 }
+
+// Create a type that combines patientProfile and patientSensitiveInfo, this will be used in the doctor's app only
+export interface PatientProfileForDoctor {
+  patientProfile?: PatientProfile;
+  patientSensitiveInfo?: PatientSensitiveInfo;
+}

package/src/types/patient/patient-requirements.ts

@@ -0,0 +1,81 @@
+import { Timestamp } from "firebase/firestore";
+import {
+  RequirementType,
+  RequirementImportance,
+  TimeFrame,
+} from "../../backoffice/types/requirement.types";
+
+/**
+ * Defines the status of a specific instruction within a PatientRequirementInstance.
+ * This helps track each actionable item for the patient.
+ */
+export enum PatientInstructionStatus {
+  PENDING_NOTIFICATION = "pendingNotification", // Notification is scheduled but not yet due/sent
+  ACTION_DUE = "actionDue", // The time for this instruction/notification has arrived
+  ACTION_TAKEN = "actionTaken", // Patient has acknowledged or completed this specific instruction
+  MISSED = "missed", // The due time for this instruction passed without action
+  CANCELLED = "cancelled", // This specific instruction was cancelled (e.g., requirement changed)
+  SKIPPED = "skipped", // This specific instruction was skipped (e.g., patient did not want to do it)
+}
+
+/**
+ * Represents a single, timed instruction or notification point derived from a Requirement's timeframe.
+ */
+export interface PatientRequirementInstruction {
+  instructionId: string; // Unique ID for this specific instruction (e.g., originalRequirementId + notifyAtIndex)
+  instructionText: string; // The specific text for this instruction (e.g., "Do not drink water")
+
+  dueTime: Timestamp; // When this instruction is due, or when the notification for it should be sent
+  actionableWindow: number; // The number of hours before the due time that the instruction is actionable (e.g., 24 hours), after this it will marked as missed if not completed
+  status: PatientInstructionStatus;
+
+  originalNotifyAtValue: number; // The original 'notifyAt' value from Requirement.timeframe.notifyAt (e.g. 2 for 2 hours before)
+  originalTimeframeUnit: TimeFrame["unit"]; // e.g. 'hours' or 'days'
+
+  notificationId?: string; // ID of the notification created for this instruction
+  actionTakenAt?: Timestamp; // When the patient marked this specific instruction as actioned
+  updatedAt: Timestamp; // Last update to this instruction's status/details
+}
+
+/**
+ * Defines the overall status of a PatientRequirementInstance.
+ */
+export enum PatientRequirementOverallStatus {
+  ACTIVE = "active", // Requirement instance is active, instructions are pending or due.
+  ALL_INSTRUCTIONS_MET = "allInstructionsMet", // All instructions actioned/completed by the patient.
+  PARTIALLY_COMPLETED = "partiallyCompleted", // Some instructions met, some missed or pending.
+  FAILED = "failed", // The patient failed to complete the requirement on time and above treashold of 60%
+  CANCELLED_APPOINTMENT = "cancelledAppointment", // Entire requirement instance cancelled due to appointment cancellation.
+  SUPERSEDED_RESCHEDULE = "supersededReschedule", // This instance was replaced by a new one due to appointment reschedule.
+  FAILED_TO_PROCESS = "failedToProcess", // An error occurred during its creation or initial processing.
+}
+
+/**
+ * Represents an instance of a backoffice Requirement, tailored to a specific patient and appointment.
+ * This document lives in the patient's subcollection: `patients/{patientId}/patientRequirements/{instanceId}`.
+ */
+export interface PatientRequirementInstance {
+  id: string; // Firestore document ID
+  patientId: string;
+  appointmentId: string;
+
+  originalRequirementId: string; // ID of the base Requirement from `backoffice_requirements`
+  requirementType: RequirementType; // 'pre' or 'post', copied from original
+  requirementName: string; // Copied from original (for display)
+  requirementDescription: string; // Copied from original (overall description)
+  requirementImportance: RequirementImportance; // Copied from original
+
+  overallStatus: PatientRequirementOverallStatus; // Overall status of this requirement instance
+
+  // Contains each specific timed instruction derived from the Requirement's timeframe.notifyAt
+  instructions: PatientRequirementInstruction[];
+
+  // Timestamps for the instance itself
+  createdAt: Timestamp;
+  updatedAt: Timestamp;
+}
+
+/**
+ * Firestore subcollection name for patient requirement instances.
+ */
+export const PATIENT_REQUIREMENTS_SUBCOLLECTION_NAME = "patientRequirements";