@blackcode_sa/metaestetics-api 1.6.2 → 1.6.4

package/dist/admin/index.d.ts

@@ -17,6 +17,7 @@ declare enum DocumentElementType {
     TEXT_INPUT = "text_input",
     DATE_PICKER = "date_picker",
     SIGNATURE = "signature",
+    DITIGAL_SIGNATURE = "digital_signature",
     FILE_UPLOAD = "file_upload"
 }
 /**
@@ -164,6 +165,9 @@ interface DocumentTemplate {
     createdBy: string;
     elements: DocumentElement[];
     tags?: string[];
+    isUserForm?: boolean;
+    isRequired?: boolean;
+    sortingOrder?: number;
     version: number;
     isActive: boolean;
 }
@@ -1118,10 +1122,19 @@ declare enum UserRole {
  * Enumeracija koja definiše sve moguće tipove notifikacija
  */
 declare enum NotificationType {
-    PRE_REQUIREMENT = "preRequirement",
-    POST_REQUIREMENT = "postRequirement",
-    APPOINTMENT_REMINDER = "appointmentReminder",
-    APPOINTMENT_NOTIFICATION = "appointmentNotification"
+    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_INSTRUCTION_DUE = "requirementInstructionDue",// For specific pre/post care instructions
+    FORM_REMINDER = "formReminder",// Reminds user to fill a specific form
+    FORM_SUBMISSION_CONFIRMATION = "formSubmissionConfirmation",// Confirms form was submitted
+    REVIEW_REQUEST = "reviewRequest",// Request for patient review post-appointment
+    PAYMENT_DUE = "paymentDue",
+    PAYMENT_CONFIRMATION = "paymentConfirmation",
+    PAYMENT_FAILED = "paymentFailed",
+    GENERAL_MESSAGE = "generalMessage",// For general announcements or direct messages
+    ACCOUNT_NOTIFICATION = "accountNotification"
 }
 declare const NOTIFICATIONS_COLLECTION = "notifications";
 /**
@@ -1156,14 +1169,22 @@ interface BaseNotification {
     isRead: boolean;
     /** Uloga korisnika kome je namenjena notifikacija */
     userRole: UserRole;
+    appointmentId?: string;
+    patientRequirementInstanceId?: string;
+    instructionId?: string;
+    formId?: string;
+    originalRequirementId?: string;
+    transactionId?: string;
 }
 /**
  * Status notifikacije
  */
 declare enum NotificationStatus {
     PENDING = "pending",
+    PROCESSING = "processing",
     SENT = "sent",
     FAILED = "failed",
+    DELIVERED = "delivered",
     CANCELLED = "cancelled",
     PARTIAL_SUCCESS = "partialSuccess"
 }
@@ -1171,7 +1192,7 @@ declare enum NotificationStatus {
  * Notifikacija za pre-requirement
  */
 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 */
@@ -1183,7 +1204,7 @@ interface PreRequirementNotification extends BaseNotification {
  * Notifikacija za post-requirement
  */
 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 */
@@ -1192,37 +1213,108 @@ interface PostRequirementNotification extends BaseNotification {
     deadline: Timestamp;
 }
 /**
- * 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."
+ */
+interface RequirementInstructionDueNotification extends BaseNotification {
+    notificationType: NotificationType.REQUIREMENT_INSTRUCTION_DUE;
+    appointmentId: string;
+    patientRequirementInstanceId: string;
+    instructionId: string;
+}
+/**
+ * Notification reminding about an upcoming appointment.
+ * Example: "Reminder: Your appointment for [Procedure Name] is at [Time] today."
  */
 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;
+    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."
+ */
+interface AppointmentStatusChangeNotification extends BaseNotification {
+    notificationType: NotificationType.APPOINTMENT_STATUS_CHANGE;
+    appointmentId: string;
+    newStatus: string;
+    previousStatus?: string;
+    procedureName?: string;
 }
 /**
- * Notifikacija o promeni statusa termina
+ * 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."
  */
-interface AppointmentNotification extends BaseNotification {
-    notificationType: NotificationType.APPOINTMENT_NOTIFICATION;
-    /** ID zakazanog termina */
+interface AppointmentRescheduledProposalNotification extends BaseNotification {
+    notificationType: NotificationType.APPOINTMENT_RESCHEDULED_PROPOSAL;
+    appointmentId: string;
+    newProposedStartTime: Timestamp;
+    newProposedEndTime: Timestamp;
+    procedureName?: string;
+}
+/**
+ * Notification informing about a cancelled appointment.
+ * Example: "Your appointment for [Procedure Name] on [Date] has been cancelled."
+ */
+interface AppointmentCancelledNotification extends BaseNotification {
+    notificationType: NotificationType.APPOINTMENT_CANCELLED;
     appointmentId: string;
-    /** Novi status termina */
-    appointmentStatus: string;
-    /** Prethodni status termina */
-    previousStatus: string;
-    /** Razlog promene (opciono) */
     reason?: string;
+    cancelledByRole?: UserRole;
+    procedureName?: string;
+}
+/**
+ * Notification reminding a user to fill a specific form.
+ * Example: "Reminder: Please complete the '[Form Name]' form for your upcoming appointment."
+ */
+interface FormReminderNotification extends BaseNotification {
+    notificationType: NotificationType.FORM_REMINDER;
+    appointmentId: string;
+    formId: string;
+    formName: string;
+    formDeadline?: Timestamp;
+}
+/**
+ * Notification confirming a form submission.
+ * Example: "Thank you! Your '[Form Name]' form has been submitted successfully."
+ */
+interface FormSubmissionConfirmationNotification extends BaseNotification {
+    notificationType: NotificationType.FORM_SUBMISSION_CONFIRMATION;
+    appointmentId?: string;
+    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]?"
+ */
+interface ReviewRequestNotification extends BaseNotification {
+    notificationType: NotificationType.REVIEW_REQUEST;
+    appointmentId: string;
+    practitionerName?: string;
+    procedureName?: string;
+}
+/**
+ * Generic notification for direct messages or announcements.
+ */
+interface GeneralMessageNotification extends BaseNotification {
+    notificationType: NotificationType.GENERAL_MESSAGE;
+}
+interface PaymentConfirmationNotification extends BaseNotification {
+    notificationType: NotificationType.PAYMENT_CONFIRMATION;
+    transactionId: string;
+    appointmentId?: string;
+    amount: string;
 }
 /**
  * Unija svih tipova notifikacija
  */
-type Notification = PreRequirementNotification | PostRequirementNotification | AppointmentReminderNotification | AppointmentNotification;
+type Notification = PreRequirementNotification | PostRequirementNotification | RequirementInstructionDueNotification | AppointmentReminderNotification | AppointmentStatusChangeNotification | AppointmentRescheduledProposalNotification | AppointmentCancelledNotification | FormReminderNotification | FormSubmissionConfirmationNotification | ReviewRequestNotification | GeneralMessageNotification | PaymentConfirmationNotification;
 
 declare class NotificationsAdmin {
     private expo;
@@ -1243,7 +1335,7 @@ declare class NotificationsAdmin {
     /**
      * Ažurira status notifikacije
      */
-    private updateNotificationStatus;
+    updateNotificationStatus(notificationId: string, status: NotificationStatus, error?: string): Promise<void>;
     /**
      * Šalje notifikaciju kroz Expo servis sa boljim error handlingom
      */
@@ -1686,6 +1778,117 @@ declare class BookingAdmin {
     private getPractitionerCalendarEvents;
 }
 
+/**
+ * Defines the status of a specific instruction within a PatientRequirementInstance.
+ * This helps track each actionable item for the patient.
+ */
+declare 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"
+}
+/**
+ * Represents a single, timed instruction or notification point derived from a Requirement's timeframe.
+ */
+interface PatientRequirementInstruction {
+    instructionId: string;
+    instructionText: string;
+    dueTime: Timestamp;
+    actionableWindow: number;
+    status: PatientInstructionStatus;
+    originalNotifyAtValue: number;
+    originalTimeframeUnit: TimeFrame["unit"];
+    notificationId?: string;
+    actionTakenAt?: Timestamp;
+    updatedAt: Timestamp;
+}
+/**
+ * Defines the overall status of a PatientRequirementInstance.
+ */
+declare 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"
+}
+/**
+ * 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}`.
+ */
+interface PatientRequirementInstance {
+    id: string;
+    patientId: string;
+    appointmentId: string;
+    originalRequirementId: string;
+    requirementType: RequirementType;
+    requirementName: string;
+    requirementDescription: string;
+    requirementImportance: RequirementImportance;
+    overallStatus: PatientRequirementOverallStatus;
+    instructions: PatientRequirementInstruction[];
+    createdAt: Timestamp;
+    updatedAt: Timestamp;
+}
+/**
+ * Firestore subcollection name for patient requirement instances.
+ */
+declare const PATIENT_REQUIREMENTS_SUBCOLLECTION_NAME = "patientRequirements";
+
+/**
+ * @class PatientRequirementsAdminService
+ * @description Handles administrative tasks for patient requirement instances, primarily managing associated notifications.
+ * This service is intended to be used by Cloud Functions triggered by changes to PatientRequirementInstance documents.
+ */
+declare class PatientRequirementsAdminService {
+    private db;
+    private notificationsAdmin;
+    constructor(firestore?: admin.firestore.Firestore);
+    /**
+     * Processes a newly created or updated PatientRequirementInstance to schedule notifications for its instructions.
+     * It will also cancel pre-existing notifications if due times have changed significantly.
+     *
+     * @param patientId - The ID of the patient.
+     * @param instance - The PatientRequirementInstance data (either new or updated).
+     * @param previousInstanceData - Optional. The previous state of the instance data if it's an update.
+     *                                 Used to determine if notifications need to be cancelled/rescheduled.
+     * @returns {Promise<void>} A promise that resolves when processing is complete.
+     */
+    processRequirementInstanceAndScheduleNotifications(patientId: string, instance: PatientRequirementInstance, previousInstanceData?: PatientRequirementInstance): Promise<void>;
+    /**
+     * Cancels all PENDING notifications associated with a specific PatientRequirementInstance.
+     * Typically called when the instance itself is deleted or its overall status becomes CANCELLED.
+     *
+     * @param instance - The PatientRequirementInstance.
+     * @returns {Promise<void>}
+     */
+    cancelAllNotificationsForInstance(instance: PatientRequirementInstance): Promise<void>;
+    /**
+     * (Optional - For a cron job)
+     * Scans for instructions that are past their due time but not yet actioned, and updates their status to MISSED.
+     * This would typically be called by a scheduled Cloud Function.
+     *
+     * @param patientId - The ID of the patient.
+     * @param instanceId - The ID of the PatientRequirementInstance.
+     * @returns {Promise<void>}
+     */
+    updateMissedInstructions(patientId: string, instanceId: string): Promise<void>;
+    /**
+     * Calculates and updates the overallStatus of a PatientRequirementInstance
+     * based on the statuses of its individual instructions.
+     *
+     * @param patientId - The ID of the patient.
+     * @param instanceId - The ID of the PatientRequirementInstance to update.
+     * @returns {Promise<void>} A promise that resolves when processing is complete.
+     */
+    updateOverallInstanceStatus(patientId: string, instanceId: string): Promise<void>;
+}
+
 /**
  * Request parameters for calculating available booking slots
  */
@@ -1729,4 +1932,4 @@ interface TimeInterval {
     end: Timestamp;
 }
 
-export { type AppointmentNotification, type AppointmentReminderNotification, type AvailableSlot, BaseMailingService, type BaseNotification, BookingAdmin, type BookingAvailabilityRequest, type BookingAvailabilityResponse, type Clinic, ClinicAggregationService, type ClinicInfo, type ClinicLocation, type DoctorInfo, NOTIFICATIONS_COLLECTION, type Notification, NotificationStatus, NotificationType, NotificationsAdmin, type PatientProfile as Patient, PatientAggregationService, type PostRequirementNotification, type Practitioner, PractitionerAggregationService, PractitionerInviteMailingService, type PractitionerToken, PractitionerTokenStatus, type PreRequirementNotification, type Procedure, ProcedureAggregationService, type ProcedureSummaryInfo, type TimeInterval, UserRole };
+export { type AppointmentReminderNotification, type AvailableSlot, BaseMailingService, type BaseNotification, BookingAdmin, type BookingAvailabilityRequest, type BookingAvailabilityResponse, type Clinic, ClinicAggregationService, type ClinicInfo, type ClinicLocation, type DoctorInfo, NOTIFICATIONS_COLLECTION, type Notification, NotificationStatus, NotificationType, NotificationsAdmin, PATIENT_REQUIREMENTS_SUBCOLLECTION_NAME, type PatientProfile as Patient, PatientAggregationService, PatientInstructionStatus, type PatientRequirementInstance, type PatientRequirementInstruction, PatientRequirementOverallStatus, PatientRequirementsAdminService, type PostRequirementNotification, type Practitioner, PractitionerAggregationService, PractitionerInviteMailingService, type PractitionerToken, PractitionerTokenStatus, type PreRequirementNotification, type Procedure, ProcedureAggregationService, type ProcedureSummaryInfo, type TimeInterval, UserRole };