@blackcode_sa/metaestetics-api 1.6.3 → 1.6.4

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/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";