@blackcode_sa/metaestetics-api 1.6.4 → 1.6.6

package/dist/index.mjs

@@ -311,6 +311,7 @@ var linkedFormInfoSchema = z2.object({
   templateVersion: z2.number().int().positive("Template version must be a positive integer"),
   title: z2.string().min(MIN_STRING_LENGTH, "Form title is required"),
   isUserForm: z2.boolean(),
+  isRequired: z2.boolean().optional(),
   status: filledDocumentStatusSchema,
   path: z2.string().min(MIN_STRING_LENGTH, "Form path is required"),
   submittedAt: z2.any().refine(
@@ -340,7 +341,6 @@ var finalizedDetailsSchema = z2.object({
   notes: z2.string().max(MAX_STRING_LENGTH_LONG, "Finalization notes too long").optional()
 });
 var createAppointmentSchema = z2.object({
-  calendarEventId: z2.string().min(MIN_STRING_LENGTH, "Calendar event ID is required"),
   clinicBranchId: z2.string().min(MIN_STRING_LENGTH, "Clinic branch ID is required"),
   practitionerId: z2.string().min(MIN_STRING_LENGTH, "Practitioner ID is required"),
   patientId: z2.string().min(MIN_STRING_LENGTH, "Patient ID is required"),
@@ -377,6 +377,7 @@ var updateAppointmentSchema = z2.object({
   paymentTransactionId: z2.any().optional().nullable(),
   completedPreRequirements: z2.union([z2.array(z2.string()), z2.any()]).optional(),
   completedPostRequirements: z2.union([z2.array(z2.string()), z2.any()]).optional(),
+  linkedFormIds: z2.union([z2.array(z2.string()), z2.any()]).optional(),
   pendingUserFormsIds: z2.union([z2.array(z2.string()), z2.any()]).optional(),
   appointmentStartTime: z2.any().refine(
     (val) => val === void 0 || val instanceof Date || (val == null ? void 0 : val._seconds) !== void 0 || typeof val === "number",
@@ -7469,6 +7470,8 @@ var NotificationType = /* @__PURE__ */ ((NotificationType3) => {
   NotificationType3["APPOINTMENT_STATUS_CHANGE"] = "appointmentStatusChange";
   NotificationType3["APPOINTMENT_RESCHEDULED_PROPOSAL"] = "appointmentRescheduledProposal";
   NotificationType3["APPOINTMENT_CANCELLED"] = "appointmentCancelled";
+  NotificationType3["PRE_REQUIREMENT_INSTRUCTION_DUE"] = "preRequirementInstructionDue";
+  NotificationType3["POST_REQUIREMENT_INSTRUCTION_DUE"] = "postRequirementInstructionDue";
   NotificationType3["REQUIREMENT_INSTRUCTION_DUE"] = "requirementInstructionDue";
   NotificationType3["FORM_REMINDER"] = "formReminder";
   NotificationType3["FORM_SUBMISSION_CONFIRMATION"] = "formSubmissionConfirmation";
@@ -7690,7 +7693,8 @@ var createProcedureSchema = z20.object({
   duration: z20.number().min(1).max(480),
   // Max 8 hours
   practitionerId: z20.string().min(1),
-  clinicBranchId: z20.string().min(1)
+  clinicBranchId: z20.string().min(1),
+  photos: z20.array(z20.string()).optional()
 });
 var updateProcedureSchema = z20.object({
   name: z20.string().min(3).max(100).optional(),
@@ -7705,7 +7709,8 @@ var updateProcedureSchema = z20.object({
   subcategoryId: z20.string().optional(),
   technologyId: z20.string().optional(),
   productId: z20.string().optional(),
-  clinicBranchId: z20.string().optional()
+  clinicBranchId: z20.string().optional(),
+  photos: z20.array(z20.string()).optional()
 });
 var procedureSchema = createProcedureSchema.extend({
   id: z20.string().min(1),
@@ -7719,6 +7724,8 @@ var procedureSchema = createProcedureSchema.extend({
   // We'll validate the full product object separately
   blockingConditions: z20.array(z20.any()),
   // We'll validate blocking conditions separately
+  contraindications: z20.array(z20.any()),
+  // We'll validate contraindications separately
   treatmentBenefits: z20.array(z20.any()),
   // We'll validate treatment benefits separately
   preRequirements: z20.array(z20.any()),
@@ -7823,6 +7830,7 @@ var ProcedureService = class extends BaseService {
       technology,
       product,
       blockingConditions: technology.blockingConditions,
+      contraindications: technology.contraindications || [],
       treatmentBenefits: technology.benefits,
       preRequirements: technology.requirements.pre,
       postRequirements: technology.requirements.post,
@@ -12243,7 +12251,7 @@ import {
   arrayUnion as arrayUnion8,
   arrayRemove as arrayRemove7
 } from "firebase/firestore";
-import { getFunctions, httpsCallable } from "firebase/functions";
+import { getFunctions } from "firebase/functions";
 
 // src/services/appointment/utils/appointment.utils.ts
 import {
@@ -12266,166 +12274,6 @@ import {
 var TECHNOLOGIES_COLLECTION = "technologies";
 
 // src/services/appointment/utils/appointment.utils.ts
-async function fetchAggregatedInfoUtil(db, clinicId, practitionerId, patientId, procedureId) {
-  var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n;
-  try {
-    const [clinicDoc, practitionerDoc, patientDoc, procedureDoc] = await Promise.all([
-      getDoc28(doc26(db, CLINICS_COLLECTION, clinicId)),
-      getDoc28(doc26(db, PRACTITIONERS_COLLECTION, practitionerId)),
-      getDoc28(doc26(db, PATIENTS_COLLECTION, patientId)),
-      getDoc28(doc26(db, PROCEDURES_COLLECTION, procedureId))
-    ]);
-    if (!clinicDoc.exists()) {
-      throw new Error(`Clinic with ID ${clinicId} not found`);
-    }
-    if (!practitionerDoc.exists()) {
-      throw new Error(`Practitioner with ID ${practitionerId} not found`);
-    }
-    if (!patientDoc.exists()) {
-      throw new Error(`Patient with ID ${patientId} not found`);
-    }
-    if (!procedureDoc.exists()) {
-      throw new Error(`Procedure with ID ${procedureId} not found`);
-    }
-    const clinicData = clinicDoc.data();
-    const practitionerData = practitionerDoc.data();
-    const patientData = patientDoc.data();
-    const procedureData = procedureDoc.data();
-    const clinicInfo = {
-      id: clinicId,
-      featuredPhoto: ((_a = clinicData.featuredPhotos) == null ? void 0 : _a[0]) || "",
-      name: clinicData.name,
-      description: clinicData.description || null,
-      location: clinicData.location,
-      contactInfo: clinicData.contactInfo
-    };
-    const practitionerInfo = {
-      id: practitionerId,
-      practitionerPhoto: ((_b = practitionerData.basicInfo) == null ? void 0 : _b.profileImageUrl) || null,
-      name: `${((_c = practitionerData.basicInfo) == null ? void 0 : _c.firstName) || ""} ${((_d = practitionerData.basicInfo) == null ? void 0 : _d.lastName) || ""}`.trim(),
-      email: ((_e = practitionerData.basicInfo) == null ? void 0 : _e.email) || "",
-      phone: ((_f = practitionerData.basicInfo) == null ? void 0 : _f.phoneNumber) || null,
-      certification: practitionerData.certification
-    };
-    const patientInfo = {
-      id: patientId,
-      fullName: patientData.displayName || "",
-      email: patientData.email || "",
-      phone: patientData.phoneNumber || null,
-      dateOfBirth: patientData.dateOfBirth || Timestamp27.now(),
-      gender: patientData.gender || "other"
-    };
-    const procedureInfo = {
-      id: procedureId,
-      name: procedureData.name,
-      description: procedureData.description,
-      photo: procedureData.photo || "",
-      family: procedureData.family,
-      categoryName: ((_g = procedureData.category) == null ? void 0 : _g.name) || "",
-      subcategoryName: ((_h = procedureData.subcategory) == null ? void 0 : _h.name) || "",
-      technologyName: ((_i = procedureData.technology) == null ? void 0 : _i.name) || "",
-      brandName: ((_j = procedureData.product) == null ? void 0 : _j.brand) || "",
-      productName: ((_k = procedureData.product) == null ? void 0 : _k.name) || "",
-      price: procedureData.price || 0,
-      pricingMeasure: procedureData.pricingMeasure,
-      currency: procedureData.currency,
-      duration: procedureData.duration || 0,
-      clinicId,
-      clinicName: clinicInfo.name,
-      practitionerId,
-      practitionerName: practitionerInfo.name
-    };
-    let technologyId = "";
-    if ((_l = procedureData.technology) == null ? void 0 : _l.id) {
-      technologyId = procedureData.technology.id;
-    }
-    let blockingConditions = [];
-    let contraindications = [];
-    let preProcedureRequirements = [];
-    let postProcedureRequirements = [];
-    if (technologyId) {
-      const technologyDoc = await getDoc28(
-        doc26(db, TECHNOLOGIES_COLLECTION, technologyId)
-      );
-      if (technologyDoc.exists()) {
-        const technologyData = technologyDoc.data();
-        blockingConditions = technologyData.blockingConditions || [];
-        contraindications = technologyData.contraindications || [];
-        preProcedureRequirements = ((_m = technologyData.requirements) == null ? void 0 : _m.pre) || [];
-        postProcedureRequirements = ((_n = technologyData.requirements) == null ? void 0 : _n.post) || [];
-      }
-    } else {
-      blockingConditions = procedureData.blockingConditions || [];
-      contraindications = procedureData.contraindications || [];
-      preProcedureRequirements = procedureData.preRequirements || [];
-      postProcedureRequirements = procedureData.postRequirements || [];
-    }
-    return {
-      clinicInfo,
-      practitionerInfo,
-      patientInfo,
-      procedureInfo,
-      blockingConditions,
-      contraindications,
-      preProcedureRequirements,
-      postProcedureRequirements
-    };
-  } catch (error) {
-    console.error("Error fetching aggregated info:", error);
-    throw error;
-  }
-}
-async function createAppointmentUtil2(db, data, aggregatedInfo, generateId2) {
-  try {
-    const appointmentId = generateId2();
-    const appointment = {
-      id: appointmentId,
-      calendarEventId: data.calendarEventId,
-      clinicBranchId: data.clinicBranchId,
-      clinicInfo: aggregatedInfo.clinicInfo,
-      practitionerId: data.practitionerId,
-      practitionerInfo: aggregatedInfo.practitionerInfo,
-      patientId: data.patientId,
-      patientInfo: aggregatedInfo.patientInfo,
-      procedureId: data.procedureId,
-      procedureInfo: aggregatedInfo.procedureInfo,
-      status: data.initialStatus,
-      bookingTime: Timestamp27.now(),
-      appointmentStartTime: data.appointmentStartTime,
-      appointmentEndTime: data.appointmentEndTime,
-      patientNotes: data.patientNotes || null,
-      cost: data.cost,
-      currency: data.currency,
-      paymentStatus: data.initialPaymentStatus || "unpaid" /* UNPAID */,
-      blockingConditions: aggregatedInfo.blockingConditions,
-      contraindications: aggregatedInfo.contraindications,
-      preProcedureRequirements: aggregatedInfo.preProcedureRequirements,
-      postProcedureRequirements: aggregatedInfo.postProcedureRequirements,
-      completedPreRequirements: [],
-      completedPostRequirements: [],
-      createdAt: serverTimestamp23(),
-      updatedAt: serverTimestamp23()
-    };
-    if (data.initialStatus === "confirmed" /* CONFIRMED */) {
-      appointment.confirmationTime = Timestamp27.now();
-    }
-    await setDoc23(doc26(db, APPOINTMENTS_COLLECTION, appointmentId), appointment);
-    const calendarEventRef = doc26(db, CALENDAR_COLLECTION, data.calendarEventId);
-    await updateDoc25(calendarEventRef, {
-      appointmentId,
-      updatedAt: serverTimestamp23()
-    });
-    const now = Timestamp27.now();
-    return {
-      ...appointment,
-      createdAt: now,
-      updatedAt: now
-    };
-  } catch (error) {
-    console.error("Error creating appointment:", error);
-    throw error;
-  }
-}
 async function updateAppointmentUtil2(db, appointmentId, data) {
   try {
     const appointmentRef = doc26(db, APPOINTMENTS_COLLECTION, appointmentId);
@@ -12633,78 +12481,6 @@ var AppointmentService = class extends BaseService {
     this.filledDocumentService = filledDocumentService;
     this.functions = getFunctions(app, "europe-west6");
   }
-  /**
-   * Test method using the callable function version of getAvailableBookingSlots
-   * For development and testing purposes only - not for production use
-   *
-   * @param clinicId ID of the clinic
-   * @param practitionerId ID of the practitioner
-   * @param procedureId ID of the procedure
-   * @param startDate Start date of the time range to check
-   * @param endDate End date of the time range to check
-   * @returns Test result from the callable function
-   */
-  async testGetAvailableBookingSlots(clinicId, practitionerId, procedureId, startDate, endDate) {
-    try {
-      console.log(
-        `[APPOINTMENT_SERVICE] Testing callable function for clinic: ${clinicId}, practitioner: ${practitionerId}, procedure: ${procedureId}`
-      );
-      const getAvailableBookingSlotsCallable = httpsCallable(
-        this.functions,
-        "getAvailableBookingSlots"
-      );
-      const result = await getAvailableBookingSlotsCallable({
-        clinicId,
-        practitionerId,
-        procedureId,
-        timeframe: {
-          start: startDate.getTime(),
-          end: endDate.getTime()
-        }
-      });
-      console.log(
-        "[APPOINTMENT_SERVICE] Callable function test result:",
-        result.data
-      );
-      return result.data;
-    } catch (error) {
-      console.error(
-        "[APPOINTMENT_SERVICE] Error testing callable function:",
-        error
-      );
-      throw error;
-    }
-  }
-  /**
-   * Gets available booking slots for a specific clinic, practitioner, and procedure.
-   *
-   * @param clinicId ID of the clinic
-   * @param practitionerId ID of the practitioner
-   * @param procedureId ID of the procedure
-   * @param startDate Start date of the time range to check
-   * @param endDate End date of the time range to check
-   * @returns Array of available booking slots
-   */
-  async getAvailableBookingSlots(clinicId, practitionerId, procedureId, startDate, endDate) {
-    try {
-      console.log(
-        `[APPOINTMENT_SERVICE] Getting available booking slots for clinic: ${clinicId}, practitioner: ${practitionerId}, procedure: ${procedureId}`
-      );
-      return this.getAvailableBookingSlotsHttp(
-        clinicId,
-        practitionerId,
-        procedureId,
-        startDate,
-        endDate
-      );
-    } catch (error) {
-      console.error(
-        "[APPOINTMENT_SERVICE] Error getting available booking slots:",
-        error
-      );
-      throw error;
-    }
-  }
   /**
    * Gets available booking slots for a specific clinic, practitioner, and procedure using HTTP request.
    * This is an alternative implementation using direct HTTP request instead of callable function.
@@ -12806,34 +12582,81 @@ var AppointmentService = class extends BaseService {
     }
   }
   /**
-   * Creates a new appointment.
+   * Creates an appointment via the Cloud Function orchestrateAppointmentCreation
    *
-   * @param data Data needed to create the appointment
+   * @param data - CreateAppointmentData object
    * @returns The created appointment
    */
-  async createAppointment(data) {
+  async createAppointmentHttp(data) {
     try {
-      console.log("[APPOINTMENT_SERVICE] Creating appointment");
-      const validatedData = await createAppointmentSchema.parseAsync(data);
-      const aggregatedInfo = await fetchAggregatedInfoUtil(
-        this.db,
-        validatedData.clinicBranchId,
-        validatedData.practitionerId,
-        validatedData.patientId,
-        validatedData.procedureId
+      console.log(
+        "[APPOINTMENT_SERVICE] Creating appointment via cloud function"
       );
-      const appointment = await createAppointmentUtil2(
-        this.db,
-        validatedData,
-        aggregatedInfo,
-        this.generateId.bind(this)
+      const currentUser = this.auth.currentUser;
+      if (!currentUser) {
+        throw new Error("User must be authenticated to create an appointment");
+      }
+      const idToken = await currentUser.getIdToken();
+      const functionUrl = `https://europe-west6-metaestetics.cloudfunctions.net/bookingApi/orchestrateAppointmentCreation`;
+      const requestData = {
+        patientId: data.patientId,
+        procedureId: data.procedureId,
+        appointmentStartTime: data.appointmentStartTime.toMillis ? data.appointmentStartTime.toMillis() : new Date(data.appointmentStartTime).getTime(),
+        appointmentEndTime: data.appointmentEndTime.toMillis ? data.appointmentEndTime.toMillis() : new Date(data.appointmentEndTime).getTime(),
+        patientNotes: data.patientNotes || null
+      };
+      console.log(
+        `[APPOINTMENT_SERVICE] Making fetch request to ${functionUrl}`
       );
+      const response = await fetch(functionUrl, {
+        method: "POST",
+        mode: "cors",
+        cache: "no-cache",
+        credentials: "omit",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${idToken}`
+        },
+        redirect: "follow",
+        referrerPolicy: "no-referrer",
+        body: JSON.stringify(requestData)
+      });
       console.log(
-        `[APPOINTMENT_SERVICE] Appointment created with ID: ${appointment.id}`
+        `[APPOINTMENT_SERVICE] Received response ${response.status}: ${response.statusText}`
       );
-      return appointment;
+      if (!response.ok) {
+        const errorText = await response.text();
+        console.error(
+          `[APPOINTMENT_SERVICE] Error response details: ${errorText}`
+        );
+        throw new Error(
+          `Failed to create appointment: ${response.status} ${response.statusText} - ${errorText}`
+        );
+      }
+      const result = await response.json();
+      if (!result.success) {
+        throw new Error(result.error || "Failed to create appointment");
+      }
+      if (result.appointmentData) {
+        console.log(
+          `[APPOINTMENT_SERVICE] Appointment created with ID: ${result.appointmentId}`
+        );
+        return result.appointmentData;
+      }
+      const createdAppointment = await this.getAppointmentById(
+        result.appointmentId
+      );
+      if (!createdAppointment) {
+        throw new Error(
+          `Failed to retrieve created appointment with ID: ${result.appointmentId}`
+        );
+      }
+      return createdAppointment;
     } catch (error) {
-      console.error("[APPOINTMENT_SERVICE] Error creating appointment:", error);
+      console.error(
+        "[APPOINTMENT_SERVICE] Error creating appointment via cloud function:",
+        error
+      );
       throw error;
     }
   }
@@ -13323,38 +13146,6 @@ var AppointmentService = class extends BaseService {
     };
     return this.updateAppointment(appointmentId, updateData);
   }
-  /**
-   * Marks pre-procedure requirements as completed.
-   *
-   * @param appointmentId ID of the appointment
-   * @param requirementIds IDs of the requirements to mark as completed
-   * @returns The updated appointment
-   */
-  async completePreRequirements(appointmentId, requirementIds) {
-    console.log(
-      `[APPOINTMENT_SERVICE] Marking pre-requirements as completed for appointment: ${appointmentId}`
-    );
-    const updateData = {
-      completedPreRequirements: requirementIds
-    };
-    return this.updateAppointment(appointmentId, updateData);
-  }
-  /**
-   * Marks post-procedure requirements as completed.
-   *
-   * @param appointmentId ID of the appointment
-   * @param requirementIds IDs of the requirements to mark as completed
-   * @returns The updated appointment
-   */
-  async completePostRequirements(appointmentId, requirementIds) {
-    console.log(
-      `[APPOINTMENT_SERVICE] Marking post-requirements as completed for appointment: ${appointmentId}`
-    );
-    const updateData = {
-      completedPostRequirements: requirementIds
-    };
-    return this.updateAppointment(appointmentId, updateData);
-  }
   /**
    * Updates the internal notes of an appointment.
    *
@@ -13371,25 +13162,6 @@ var AppointmentService = class extends BaseService {
     };
     return this.updateAppointment(appointmentId, updateData);
   }
-  /**
-   * Debug helper: Get the current user's ID token for testing purposes
-   * Use this token in Postman with Authorization: Bearer TOKEN
-   */
-  async getDebugToken() {
-    try {
-      const currentUser = this.auth.currentUser;
-      if (!currentUser) {
-        console.log("[APPOINTMENT_SERVICE] No user is signed in");
-        return null;
-      }
-      const idToken = await currentUser.getIdToken();
-      console.log("[APPOINTMENT_SERVICE] Debug token:", idToken);
-      return idToken;
-    } catch (error) {
-      console.error("[APPOINTMENT_SERVICE] Error getting debug token:", error);
-      return null;
-    }
-  }
 };
 
 // src/services/patient/patientRequirements.service.ts

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@blackcode_sa/metaestetics-api",
   "private": false,
-  "version": "1.6.4",
+  "version": "1.6.6",
   "description": "Firebase authentication service with anonymous upgrade support",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",

package/src/admin/aggregation/appointment/README.md

@@ -0,0 +1,128 @@
+# Appointment Aggregation Service (`appointment.aggregation.service.ts`)
+
+This service is responsible for handling side effects and data aggregation tasks related to the lifecycle of appointments within the system. It is primarily designed to be invoked by Firestore triggers (`onCreate`, `onUpdate`, `onDelete`) for the `appointments` collection.
+
+## Core Responsibilities
+
+- Managing denormalized data links (e.g., patient-clinic, patient-practitioner).
+- Creating and updating `PatientRequirementInstance` documents based on appointment status and associated procedure requirements.
+- Orchestrating notifications (email and push) to patients, practitioners, and clinic admins at various stages of the appointment lifecycle.
+- Interfacing with other admin services like `AppointmentMailingService`, `NotificationsAdmin`, and `CalendarAdminService` (though calendar interactions are mostly TODOs).
+
+## Implemented Functionality
+
+### Constructor
+
+- Initializes with a Firestore instance and a Mailgun client.
+- Sets up instances of dependent services: `AppointmentMailingService`, `NotificationsAdmin`, `CalendarAdminService`, and `PatientRequirementsAdminService`.
+  - **Note**: `PatientRequirementsAdminService` is initialized but its methods are not (and should not be) directly called by this aggregation service for creating/managing requirement instances. That logic is correctly handled by local private methods in this service.
+
+### `handleAppointmentCreate(appointment: Appointment)`
+
+- **Patient-Clinic-Practitioner Links**: Calls `managePatientClinicPractitionerLinks` to add links.
+- **Data Fetching**: Fetches `PatientProfile`, `PatientSensitiveInfo`, `PractitionerProfile`, and `Clinic` data.
+- **Status: `CONFIRMED`**
+  - Creates pre-appointment requirement instances via `createPreAppointmentRequirementInstances()`.
+  - Sends confirmation email to patient via `appointmentMailingService.sendAppointmentConfirmedEmail()`.
+  - Sends confirmation email to practitioner via `appointmentMailingService.sendAppointmentConfirmedEmail()`.
+  - Initiates confirmed push notification to patient via `notificationsAdmin.sendAppointmentConfirmedPush()`.
+- **Status: `PENDING`**
+  - Sends appointment requested email to clinic admin via `appointmentMailingService.sendAppointmentRequestedEmailToClinic()`.
+
+### `handleAppointmentUpdate(before: Appointment, after: Appointment)`
+
+- **Data Fetching**: Fetches `PatientProfile`, `PatientSensitiveInfo`, `PractitionerProfile`, and `Clinic` data for the `after` state.
+- **Status Change: `PENDING -> CONFIRMED`**
+  - Creates pre-appointment requirement instances via `createPreAppointmentRequirementInstances(after)`.
+  - Sends confirmation email to patient.
+  - Sends confirmation email to practitioner.
+  - Initiates confirmed push notification to patient.
+- **Status Change: `Any -> CANCELLED_*` (includes `NO_SHOW`)**
+  - Updates related patient requirement instances to `CANCELLED_APPOINTMENT` via `updateRelatedPatientRequirementInstances()`.
+  - Removes patient-clinic-practitioner links via `managePatientClinicPractitionerLinks()`.
+  - Sends cancellation email to patient.
+  - Sends cancellation email to practitioner.
+- **Status Change: `Any -> COMPLETED`**
+  - Creates post-appointment requirement instances via `createPostAppointmentRequirementInstances(after)`.
+  - Sends review request email to patient.
+- **Status Change: `Any -> RESCHEDULED_BY_CLINIC`**
+  - Updates related (old) patient requirement instances to `SUPERSEDED_RESCHEDULE`.
+  - Sends reschedule proposal email to patient.
+
+### `handleAppointmentDelete(deletedAppointment: Appointment)`
+
+- Updates related patient requirement instances to `CANCELLED_APPOINTMENT`.
+- Removes patient-clinic-practitioner links.
+
+### Helper Methods
+
+- **`createPreAppointmentRequirementInstances(appointment: Appointment)`**:
+  - Creates `PatientRequirementInstance` documents for pre-appointment requirements based on `appointment.preProcedureRequirements`.
+  - Calculates due times for instructions based on `appointment.appointmentStartTime`.
+  - Sets `actionableWindow` with a placeholder value (TODO noted).
+  - Batch writes instances to Firestore.
+- **`createPostAppointmentRequirementInstances(appointment: Appointment)`**:
+  - Creates `PatientRequirementInstance` documents for post-appointment requirements based on `appointment.postProcedureRequirements`.
+  - Calculates due times for instructions based on `appointment.appointmentEndTime`.
+  - Sets `actionableWindow` with a placeholder value (TODO noted).
+  - Batch writes instances to Firestore.
+- **`updateRelatedPatientRequirementInstances(appointment: Appointment, newOverallStatus: PatientRequirementOverallStatus)`**:
+  - Queries for all `PatientRequirementInstance` documents linked to the appointment.
+  - Batch updates their `overallStatus` and `updatedAt` fields.
+- **`managePatientClinicPractitionerLinks(appointment: Appointment, action: "create" | "cancel")`**:
+  - Adds/removes the patient's ID from `patientIds` arrays on the respective clinic and practitioner documents using `FieldValue.arrayUnion` or `FieldValue.arrayRemove`.
+- **Data Fetching Helpers (`fetchPatientProfile`, `fetchPatientSensitiveInfo`, `fetchPractitionerProfile`, `fetchClinicInfo`)**:
+  - Basic methods to retrieve documents from Firestore by ID.
+
+## Pending `TODO` Items & Areas for Future Work
+
+### General / Cross-Cutting
+
+- **Type Imports for Email Data Objects**:
+  - Throughout `handleAppointmentCreate` and `handleAppointmentUpdate`, calls to the `appointmentMailingService` use `as any` for the data payload (e.g., `emailData as any`).
+  - `TODO`: Properly import `PatientProfileInfo`, `PractitionerProfileInfo`, `ClinicInfo` from a shared location (e.g., `Api/src/types/profile.ts` or `Api/src/types/index.ts`) and ensure these types are correctly used, removing the `as any` casts. This may require exporting these types if they are not already.
+- **`actionableWindow` in Requirement Instances**:
+  - In `createPreAppointmentRequirementInstances` and `createPostAppointmentRequirementInstances`, the `actionableWindow` for instructions is currently a placeholder (e.g., based on importance or a fixed value like 24 hours).
+  - `TODO`: Determine the correct logic or source for `actionableWindow` based on business requirements or template definitions.
+- **Error Handling**: Enhance error handling in various methods to potentially update appointment status to an error state or implement more sophisticated retry mechanisms if critical operations fail.
+
+### `handleAppointmentCreate(appointment: Appointment)`
+
+- **Push Notifications**:
+  - `TODO`: Implement sending appointment confirmed push to practitioner (if they have expo tokens).
+  - `TODO`: Implement sending pending appointment push notification to clinic admin (if applicable).
+
+### `handleAppointmentUpdate(before: Appointment, after: Appointment)`
+
+- **Push Notifications**:
+  - For `PENDING -> CONFIRMED`: `TODO`: Send appointment confirmed push to practitioner.
+  - For `Any -> CANCELLED_*`: `TODO`: Send cancellation push notifications to patient and practitioner.
+  - For `Any -> COMPLETED`: `TODO`: Send review request push notification to patient.
+  - For `Any -> RESCHEDULED_BY_CLINIC`: `TODO`: Send reschedule proposal push notifications to patient (and practitioner if applicable).
+- **Calendar Event Updates**:
+  - For `Any -> CANCELLED_*`: `TODO`: Update/cancel calendar event via `calendarAdminService.updateAppointmentCalendarEventStatus(after, CalendarEventStatus.CANCELED)` (or similar method).
+  - For `Any -> RESCHEDULED_BY_CLINIC`: `TODO`: Update calendar event to reflect proposed new time via `calendarAdminService`.
+- **Reschedule Logic for Requirements (`RESCHEDULED_BY_CLINIC`)**:
+  - `TODO`: Handle RESCHEDULE logic for `PatientRequirementInstance` creation/cancellation more carefully based on the specific confirmation flow of a reschedule. For instance, when are new pre-requirements created if it's just a proposal?
+- **Reschedule Notification to Practitioner (`RESCHEDULED_BY_CLINIC`)**:
+  - `TODO`: Implement sending reschedule proposal email/notification to the practitioner.
+- **Independent Time Change**:
+  - `TODO`: Fully implement logic for when `appointmentStartTime` or `appointmentEndTime` changes without an accompanying status change. This might involve updating requirements and calendar events.
+  - `Logger.warn` currently flags this scenario.
+- **Payment Status Change**:
+  - `TODO`: Implement logic for `before.paymentStatus !== after.paymentStatus`. This could involve sending payment confirmation notifications (email/push).
+- **Review Added**:
+  - `TODO`: Implement logic for when `!before.reviewInfo && after.reviewInfo`. This could involve notifying the clinic admin or practitioner.
+
+### `handleAppointmentDelete(deletedAppointment: Appointment)`
+
+- **Notifications**: `TODO`: Send cancellation/deletion notifications if appropriate (though data is gone, so context might be limited).
+- **Calendar Events**: Placeholder comment `// await this.calendarAdminService.deleteAppointmentCalendarEvents(deletedAppointment);` exists.
+  - `TODO`: Implement actual call to delete associated calendar events.
+
+### `managePatientClinicPractitionerLinks(...)`
+
+- **Robust Removal Logic**:
+  - `TODO`: For the 'cancel' action, implement more robust removal logic. Currently, it removes the patient ID regardless. It should ideally only remove the link if this was the last active/confirmed appointment connecting the patient to the practitioner/clinic.
+
+This README should serve as a good guide to the current state and future development of the `AppointmentAggregationService`.