@blackcode_sa/metaestetics-api 1.4.18 → 1.5.1

package/src/services/calendar/calendar-refactored.service.ts

@@ -0,0 +1,1531 @@
+import { Auth } from "firebase/auth";
+import { Firestore, Timestamp, serverTimestamp } from "firebase/firestore";
+import { FirebaseApp } from "firebase/app";
+import { BaseService } from "../base.service";
+import {
+  CalendarEvent,
+  CalendarEventStatus,
+  CalendarEventTime,
+  CalendarEventType,
+  CalendarSyncStatus,
+  CreateCalendarEventData,
+  UpdateCalendarEventData,
+  CALENDAR_COLLECTION,
+  SyncedCalendarEvent,
+  ProcedureInfo,
+  TimeSlot,
+  CreateAppointmentParams,
+  UpdateAppointmentParams,
+} from "../../types/calendar";
+import {
+  PRACTITIONERS_COLLECTION,
+  PractitionerClinicWorkingHours,
+} from "../../types/practitioner";
+import {
+  PATIENTS_COLLECTION,
+  Gender,
+  PATIENT_SENSITIVE_INFO_COLLECTION,
+} from "../../types/patient";
+import { CLINICS_COLLECTION } from "../../types/clinic";
+import { SyncedCalendarProvider } from "../../types/calendar/synced-calendar.types";
+import {
+  ClinicInfo,
+  PatientProfileInfo,
+  PractitionerProfileInfo,
+} from "../../types/profile";
+import {
+  doc,
+  getDoc,
+  collection,
+  query,
+  where,
+  getDocs,
+  setDoc,
+  updateDoc,
+} from "firebase/firestore";
+import {
+  createAppointmentSchema,
+  updateAppointmentSchema,
+} from "../../validations/calendar.schema";
+
+// Import utility functions
+import {
+  createAppointmentUtil,
+  updateAppointmentUtil,
+  deleteAppointmentUtil,
+} from "./utils/appointment.utils";
+import { SyncedCalendarsService } from "./synced-calendars.service";
+import { Timestamp as FirestoreTimestamp } from "firebase-admin/firestore";
+
+/**
+ * Minimum appointment duration in minutes
+ */
+const MIN_APPOINTMENT_DURATION = 15;
+
+/**
+ * Refactored Calendar Service
+ * Provides streamlined calendar management with proper access control and scheduling rules
+ */
+export class CalendarServiceV2 extends BaseService {
+  private syncedCalendarsService: SyncedCalendarsService;
+
+  /**
+   * Creates a new CalendarService instance
+   * @param db - Firestore instance
+   * @param auth - Firebase Auth instance
+   * @param app - Firebase App instance
+   */
+  constructor(db: Firestore, auth: Auth, app: FirebaseApp) {
+    super(db, auth, app);
+    this.syncedCalendarsService = new SyncedCalendarsService(db, auth, app);
+  }
+
+  // #region Public API Methods
+
+  /**
+   * Creates a new appointment with proper validation and scheduling rules
+   * @param params - Appointment creation parameters
+   * @returns Created calendar event
+   */
+  async createAppointment(
+    params: CreateAppointmentParams
+  ): Promise<CalendarEvent> {
+    // Validate input parameters
+    await this.validateAppointmentParams(params);
+
+    // Check clinic working hours
+    await this.validateClinicWorkingHours(params.clinicId, params.eventTime);
+
+    // Check doctor availability
+    await this.validateDoctorAvailability(
+      params.doctorId,
+      params.eventTime,
+      params.clinicId
+    );
+
+    // Fetch profile info cards
+    const { clinicInfo, practitionerInfo, patientInfo } =
+      await this.fetchProfileInfoCards(
+        params.clinicId,
+        params.doctorId,
+        params.patientId
+      );
+
+    // Create the appointment
+    const appointmentData: Omit<
+      CreateCalendarEventData,
+      "id" | "createdAt" | "updatedAt"
+    > = {
+      clinicBranchId: params.clinicId,
+      clinicBranchInfo: clinicInfo,
+      practitionerProfileId: params.doctorId,
+      practitionerProfileInfo: practitionerInfo,
+      patientProfileId: params.patientId,
+      patientProfileInfo: patientInfo,
+      procedureId: params.procedureId,
+      eventLocation: params.eventLocation,
+      eventName: "Appointment", // TODO: Add procedure name when procedure model is available
+      eventTime: params.eventTime,
+      description: params.description || "",
+      status: CalendarEventStatus.PENDING,
+      syncStatus: CalendarSyncStatus.INTERNAL,
+      eventType: CalendarEventType.APPOINTMENT,
+    };
+
+    const appointment = await createAppointmentUtil(
+      this.db,
+      params.clinicId,
+      params.doctorId,
+      params.patientId,
+      appointmentData,
+      this.generateId.bind(this)
+    );
+
+    // Sync with external calendars if needed
+    await this.syncAppointmentWithExternalCalendars(appointment);
+
+    return appointment;
+  }
+
+  /**
+   * Updates an existing appointment
+   * @param params - Appointment update parameters
+   * @returns Updated calendar event
+   */
+  async updateAppointment(
+    params: UpdateAppointmentParams
+  ): Promise<CalendarEvent> {
+    // Validate permissions
+    await this.validateUpdatePermissions(params);
+
+    const updateData: Omit<UpdateCalendarEventData, "updatedAt"> = {
+      eventTime: params.eventTime,
+      description: params.description,
+      status: params.status,
+    };
+
+    const appointment = await updateAppointmentUtil(
+      this.db,
+      params.clinicId,
+      params.doctorId,
+      params.patientId,
+      params.appointmentId,
+      updateData
+    );
+
+    // Sync with external calendars if needed
+    await this.syncAppointmentWithExternalCalendars(appointment);
+
+    return appointment;
+  }
+
+  /**
+   * Gets available appointment slots for a doctor at a clinic
+   * @param clinicId - ID of the clinic
+   * @param doctorId - ID of the doctor
+   * @param date - Date to check availability for
+   * @returns Array of available time slots
+   */
+  async getAvailableSlots(
+    clinicId: string,
+    doctorId: string,
+    date: Date
+  ): Promise<TimeSlot[]> {
+    // Get clinic working hours
+    const workingHours = await this.getClinicWorkingHours(clinicId, date);
+
+    // Get doctor's schedule
+    const doctorSchedule = await this.getDoctorSchedule(doctorId, date);
+
+    // Get existing appointments
+    const existingAppointments = await this.getDoctorAppointments(
+      doctorId,
+      date
+    );
+
+    // Calculate available slots
+    return this.calculateAvailableSlots(
+      workingHours,
+      doctorSchedule,
+      existingAppointments
+    );
+  }
+
+  /**
+   * Confirms an appointment
+   * @param appointmentId - ID of the appointment
+   * @param clinicId - ID of the clinic
+   * @returns Confirmed calendar event
+   */
+  async confirmAppointment(
+    appointmentId: string,
+    clinicId: string
+  ): Promise<CalendarEvent> {
+    return this.updateAppointmentStatus(
+      appointmentId,
+      clinicId,
+      CalendarEventStatus.CONFIRMED
+    );
+  }
+
+  /**
+   * Rejects an appointment
+   * @param appointmentId - ID of the appointment
+   * @param clinicId - ID of the clinic
+   * @returns Rejected calendar event
+   */
+  async rejectAppointment(
+    appointmentId: string,
+    clinicId: string
+  ): Promise<CalendarEvent> {
+    return this.updateAppointmentStatus(
+      appointmentId,
+      clinicId,
+      CalendarEventStatus.REJECTED
+    );
+  }
+
+  /**
+   * Cancels an appointment
+   * @param appointmentId - ID of the appointment
+   * @param clinicId - ID of the clinic
+   * @returns Canceled calendar event
+   */
+  async cancelAppointment(
+    appointmentId: string,
+    clinicId: string
+  ): Promise<CalendarEvent> {
+    return this.updateAppointmentStatus(
+      appointmentId,
+      clinicId,
+      CalendarEventStatus.CANCELED
+    );
+  }
+
+  /**
+   * Imports events from external calendars
+   * @param entityType - Type of entity (practitioner or patient)
+   * @param entityId - ID of the entity
+   * @param startDate - Start date for fetching events
+   * @param endDate - End date for fetching events
+   * @returns Number of events imported
+   */
+  async importEventsFromExternalCalendars(
+    entityType: "doctor" | "patient",
+    entityId: string,
+    startDate: Date,
+    endDate: Date
+  ): Promise<number> {
+    // Only practitioners (doctors) should sync two-way
+    // Patients only sync outwards (from our system to external calendars)
+    if (entityType === "patient") {
+      return 0;
+    }
+
+    // For doctors, get their synced calendars
+    const syncedCalendars =
+      await this.syncedCalendarsService.getPractitionerSyncedCalendars(
+        entityId
+      );
+
+    // Filter active calendars
+    const activeCalendars = syncedCalendars.filter((cal) => cal.isActive);
+
+    if (activeCalendars.length === 0) {
+      return 0;
+    }
+
+    let importedEventsCount = 0;
+    const currentTime = Timestamp.now();
+
+    // Import from each calendar
+    for (const calendar of activeCalendars) {
+      try {
+        let externalEvents: any[] = [];
+
+        // Fetch events based on provider and entity type
+        if (calendar.provider === SyncedCalendarProvider.GOOGLE) {
+          externalEvents =
+            await this.syncedCalendarsService.fetchEventsFromPractitionerGoogleCalendar(
+              entityId,
+              calendar.id,
+              startDate,
+              endDate
+            );
+        }
+        // Add other providers as needed
+
+        // Process and import each event
+        for (const externalEvent of externalEvents) {
+          try {
+            // Convert the external event to our format
+            const convertedEvent =
+              this.syncedCalendarsService.convertGoogleEventsToPractitionerEvents(
+                entityId,
+                [externalEvent]
+              )[0];
+
+            // Skip events without valid time data
+            if (!convertedEvent.eventTime) {
+              continue;
+            }
+
+            // Create event data from external event
+            const eventData: Omit<
+              CreateCalendarEventData,
+              "id" | "createdAt" | "updatedAt"
+            > = {
+              // Ensure all required fields are set
+              eventName: convertedEvent.eventName || "External Event",
+              eventTime: convertedEvent.eventTime,
+              description: convertedEvent.description || "",
+              status: CalendarEventStatus.CONFIRMED,
+              syncStatus: CalendarSyncStatus.EXTERNAL,
+              eventType: CalendarEventType.BLOCKING,
+              practitionerProfileId: entityId,
+              syncedCalendarEventId: [
+                {
+                  eventId: externalEvent.id,
+                  syncedCalendarProvider: calendar.provider,
+                  syncedAt: currentTime,
+                },
+              ],
+            };
+
+            // Create the event in the doctor's calendar
+            const doctorEvent = await this.createDoctorBlockingEvent(
+              entityId,
+              eventData
+            );
+
+            if (doctorEvent) {
+              importedEventsCount++;
+            }
+          } catch (eventError) {
+            console.error("Error importing event:", eventError);
+            // Continue with other events even if one fails
+          }
+        }
+      } catch (calendarError) {
+        console.error(
+          `Error fetching events from calendar ${calendar.id}:`,
+          calendarError
+        );
+        // Continue with other calendars even if one fails
+      }
+    }
+
+    return importedEventsCount;
+  }
+
+  /**
+   * Creates a blocking event in a doctor's calendar
+   * @param doctorId - ID of the doctor
+   * @param eventData - Calendar event data
+   * @returns Created calendar event
+   */
+  private async createDoctorBlockingEvent(
+    doctorId: string,
+    eventData: Omit<CreateCalendarEventData, "id" | "createdAt" | "updatedAt">
+  ): Promise<CalendarEvent | null> {
+    try {
+      // Generate a unique ID for the event
+      const eventId = this.generateId();
+
+      // Create the event document reference
+      const eventRef = doc(
+        this.db,
+        PRACTITIONERS_COLLECTION,
+        doctorId,
+        CALENDAR_COLLECTION,
+        eventId
+      );
+
+      // Prepare the event data
+      const newEvent: CreateCalendarEventData = {
+        id: eventId,
+        ...eventData,
+        createdAt: serverTimestamp(),
+        updatedAt: serverTimestamp(),
+      };
+
+      // Set the document
+      await setDoc(eventRef, newEvent);
+
+      // Return the event
+      return {
+        ...newEvent,
+        createdAt: Timestamp.now(),
+        updatedAt: Timestamp.now(),
+      } as CalendarEvent;
+    } catch (error) {
+      console.error(
+        `Error creating blocking event for doctor ${doctorId}:`,
+        error
+      );
+      return null;
+    }
+  }
+
+  /**
+   * Periodically syncs events from external calendars for doctors
+   * This would be called via a scheduled Cloud Function
+   * @param lookbackDays - Number of days to look back for events
+   * @param lookforwardDays - Number of days to look forward for events
+   */
+  async synchronizeExternalCalendars(
+    lookbackDays: number = 7,
+    lookforwardDays: number = 30
+  ): Promise<void> {
+    try {
+      // Get all doctors who have active synced calendars
+      const practitionersRef = collection(this.db, PRACTITIONERS_COLLECTION);
+      const practitionersSnapshot = await getDocs(practitionersRef);
+
+      // Prepare date range
+      const startDate = new Date();
+      startDate.setDate(startDate.getDate() - lookbackDays);
+
+      const endDate = new Date();
+      endDate.setDate(endDate.getDate() + lookforwardDays);
+
+      // For each doctor, check their synced calendars
+      const syncPromises = [];
+      for (const docSnapshot of practitionersSnapshot.docs) {
+        const practitionerId = docSnapshot.id;
+
+        // Import events from external calendars
+        syncPromises.push(
+          this.importEventsFromExternalCalendars(
+            "doctor",
+            practitionerId,
+            startDate,
+            endDate
+          )
+            .then((count) => {
+              console.log(
+                `Imported ${count} events for doctor ${practitionerId}`
+              );
+            })
+            .catch((error) => {
+              console.error(
+                `Error importing events for doctor ${practitionerId}:`,
+                error
+              );
+            })
+        );
+
+        // Also update existing events that might have changed
+        syncPromises.push(
+          this.updateExistingEventsFromExternalCalendars(
+            practitionerId,
+            startDate,
+            endDate
+          )
+            .then((count) => {
+              console.log(
+                `Updated ${count} events for doctor ${practitionerId}`
+              );
+            })
+            .catch((error) => {
+              console.error(
+                `Error updating events for doctor ${practitionerId}:`,
+                error
+              );
+            })
+        );
+      }
+
+      // Wait for all sync operations to complete
+      await Promise.all(syncPromises);
+      console.log("Completed external calendar synchronization");
+    } catch (error) {
+      console.error("Error synchronizing external calendars:", error);
+    }
+  }
+
+  /**
+   * Updates existing events that were synced from external calendars
+   * @param doctorId - ID of the doctor
+   * @param startDate - Start date for fetching events
+   * @param endDate - End date for fetching events
+   * @returns Number of events updated
+   */
+  private async updateExistingEventsFromExternalCalendars(
+    doctorId: string,
+    startDate: Date,
+    endDate: Date
+  ): Promise<number> {
+    try {
+      // Get all EXTERNAL events for this doctor within the date range
+      const eventsRef = collection(
+        this.db,
+        PRACTITIONERS_COLLECTION,
+        doctorId,
+        CALENDAR_COLLECTION
+      );
+      const q = query(
+        eventsRef,
+        where("syncStatus", "==", CalendarSyncStatus.EXTERNAL),
+        where("eventTime.start", ">=", Timestamp.fromDate(startDate)),
+        where("eventTime.start", "<=", Timestamp.fromDate(endDate))
+      );
+
+      const eventsSnapshot = await getDocs(q);
+      const events = eventsSnapshot.docs.map((doc) => ({
+        id: doc.id,
+        ...doc.data(),
+      })) as CalendarEvent[];
+
+      // Get the doctor's synced calendars
+      const calendars =
+        await this.syncedCalendarsService.getPractitionerSyncedCalendars(
+          doctorId
+        );
+      const activeCalendars = calendars.filter((cal) => cal.isActive);
+
+      if (activeCalendars.length === 0 || events.length === 0) {
+        return 0;
+      }
+
+      let updatedCount = 0;
+
+      // For each external event, check if it needs updating
+      for (const event of events) {
+        // Skip events without sync IDs
+        if (!event.syncedCalendarEventId?.length) continue;
+
+        for (const syncId of event.syncedCalendarEventId) {
+          // Find the calendar for this sync ID
+          const calendar = activeCalendars.find(
+            (cal) => cal.provider === syncId.syncedCalendarProvider
+          );
+          if (!calendar) continue;
+
+          // Check if the event exists and needs updating
+          if (syncId.syncedCalendarProvider === SyncedCalendarProvider.GOOGLE) {
+            try {
+              // Fetch the external event
+              const externalEvent = await this.fetchExternalEvent(
+                doctorId,
+                calendar,
+                syncId.eventId
+              );
+
+              // If the event was found, check if it's different from our local copy
+              if (externalEvent) {
+                // Compare basic properties (time, title, description)
+                const externalStartTime = new Date(
+                  externalEvent.start.dateTime || externalEvent.start.date
+                ).getTime();
+                const externalEndTime = new Date(
+                  externalEvent.end.dateTime || externalEvent.end.date
+                ).getTime();
+                const localStartTime = event.eventTime.start.toDate().getTime();
+                const localEndTime = event.eventTime.end.toDate().getTime();
+
+                // If times or title/description have changed, update our local copy
+                if (
+                  externalStartTime !== localStartTime ||
+                  externalEndTime !== localEndTime ||
+                  externalEvent.summary !== event.eventName ||
+                  externalEvent.description !== event.description
+                ) {
+                  // Update our local copy
+                  await this.updateLocalEventFromExternal(
+                    doctorId,
+                    event.id,
+                    externalEvent
+                  );
+                  updatedCount++;
+                }
+              } else {
+                // The event was deleted in the external calendar, mark it as canceled
+                await this.updateEventStatus(
+                  doctorId,
+                  event.id,
+                  CalendarEventStatus.CANCELED
+                );
+                updatedCount++;
+              }
+            } catch (error) {
+              console.error(
+                `Error updating external event ${event.id}:`,
+                error
+              );
+            }
+          }
+        }
+      }
+
+      return updatedCount;
+    } catch (error) {
+      console.error(
+        "Error updating existing events from external calendars:",
+        error
+      );
+      return 0;
+    }
+  }
+
+  /**
+   * Fetches a single external event from Google Calendar
+   * @param doctorId - ID of the doctor
+   * @param calendar - Calendar information
+   * @param externalEventId - ID of the external event
+   * @returns External event data or null if not found
+   */
+  private async fetchExternalEvent(
+    doctorId: string,
+    calendar: any,
+    externalEventId: string
+  ): Promise<any | null> {
+    try {
+      if (calendar.provider === SyncedCalendarProvider.GOOGLE) {
+        // Refresh token if needed
+        // We're using the syncPractitionerEventsToGoogleCalendar to get the calendar with a refreshed token
+        const result =
+          await this.syncedCalendarsService.fetchEventFromPractitionerGoogleCalendar(
+            doctorId,
+            calendar.id,
+            externalEventId
+          );
+
+        return result;
+      }
+      return null;
+    } catch (error) {
+      console.error(`Error fetching external event ${externalEventId}:`, error);
+      return null;
+    }
+  }
+
+  /**
+   * Updates a local event with data from an external event
+   * @param doctorId - ID of the doctor
+   * @param eventId - ID of the local event
+   * @param externalEvent - External event data
+   */
+  private async updateLocalEventFromExternal(
+    doctorId: string,
+    eventId: string,
+    externalEvent: any
+  ): Promise<void> {
+    try {
+      // Create event time from external event
+      const startTime = new Date(
+        externalEvent.start.dateTime || externalEvent.start.date
+      );
+      const endTime = new Date(
+        externalEvent.end.dateTime || externalEvent.end.date
+      );
+
+      // Update the local event
+      const eventRef = doc(
+        this.db,
+        PRACTITIONERS_COLLECTION,
+        doctorId,
+        CALENDAR_COLLECTION,
+        eventId
+      );
+
+      await updateDoc(eventRef, {
+        eventName: externalEvent.summary || "External Event",
+        eventTime: {
+          start: Timestamp.fromDate(startTime),
+          end: Timestamp.fromDate(endTime),
+        },
+        description: externalEvent.description || "",
+        updatedAt: serverTimestamp(),
+      });
+
+      console.log(`Updated local event ${eventId} from external event`);
+    } catch (error) {
+      console.error(
+        `Error updating local event ${eventId} from external:`,
+        error
+      );
+    }
+  }
+
+  /**
+   * Updates an event's status
+   * @param doctorId - ID of the doctor
+   * @param eventId - ID of the event
+   * @param status - New status
+   */
+  private async updateEventStatus(
+    doctorId: string,
+    eventId: string,
+    status: CalendarEventStatus
+  ): Promise<void> {
+    try {
+      const eventRef = doc(
+        this.db,
+        PRACTITIONERS_COLLECTION,
+        doctorId,
+        CALENDAR_COLLECTION,
+        eventId
+      );
+
+      await updateDoc(eventRef, {
+        status,
+        updatedAt: serverTimestamp(),
+      });
+
+      console.log(`Updated event ${eventId} status to ${status}`);
+    } catch (error) {
+      console.error(`Error updating event ${eventId} status:`, error);
+    }
+  }
+
+  /**
+   * Creates a scheduled job to periodically sync external calendars
+   * Note: This would be implemented using Cloud Functions in a real application
+   * This is a sample implementation to show how it could be set up
+   * @param interval - Interval in hours
+   */
+  createScheduledSyncJob(interval: number = 3): void {
+    // This is a simplified implementation
+    // In a real application, you would use Cloud Functions with Pub/Sub
+    console.log(
+      `Setting up scheduled calendar sync job every ${interval} hours`
+    );
+
+    // Example cloud function implementation:
+    /*
+    // Using Firebase Cloud Functions (in index.ts)
+    export const syncExternalCalendars = functions.pubsub
+      .schedule('every 3 hours')
+      .onRun(async (context) => {
+        try {
+          const db = admin.firestore();
+          const auth = admin.auth();
+          const app = admin.app();
+          
+          const calendarService = new CalendarServiceV2(db, auth, app);
+          await calendarService.synchronizeExternalCalendars();
+          
+          console.log('External calendar sync completed successfully');
+          return null;
+        } catch (error) {
+          console.error('Error in calendar sync job:', error);
+          return null;
+        }
+      });
+    */
+  }
+
+  // #endregion
+
+  // #region Private Helper Methods
+
+  /**
+   * Validates appointment creation parameters
+   * @param params - Appointment parameters to validate
+   * @throws Error if validation fails
+   */
+  private async validateAppointmentParams(
+    params: CreateAppointmentParams
+  ): Promise<void> {
+    // TODO: Add custom validation logic after Zod schema validation
+    // - Check if doctor works at the clinic
+    // - Check if procedure is available at the clinic
+    // - Check if patient is eligible for the procedure
+    // - Validate time slot (15-minute increments)
+    // - Check clinic's subscription status
+    // - Check if auto-confirm is enabled
+
+    // Validate basic parameters using Zod schema
+    await createAppointmentSchema.parseAsync(params);
+  }
+
+  /**
+   * Validates if the event time falls within clinic working hours
+   * @param clinicId - ID of the clinic
+   * @param eventTime - Event time to validate
+   * @throws Error if validation fails
+   */
+  private async validateClinicWorkingHours(
+    clinicId: string,
+    eventTime: CalendarEventTime
+  ): Promise<void> {
+    // Get clinic working hours for the day
+    const startDate = eventTime.start.toDate();
+    const workingHours = await this.getClinicWorkingHours(clinicId, startDate);
+
+    if (workingHours.length === 0) {
+      throw new Error("Clinic is not open on this day");
+    }
+
+    // Find if the appointment time falls within any working hours slot
+    const startTime = startDate;
+    const endTime = eventTime.end.toDate();
+    const isWithinWorkingHours = workingHours.some((slot) => {
+      return slot.start <= startTime && slot.end >= endTime && slot.isAvailable;
+    });
+
+    if (!isWithinWorkingHours) {
+      throw new Error("Appointment time is outside clinic working hours");
+    }
+  }
+
+  /**
+   * Validates if the doctor is available during the event time
+   * @param doctorId - ID of the doctor
+   * @param eventTime - Event time to validate
+   * @param clinicId - ID of the clinic where the appointment is being booked
+   * @throws Error if validation fails
+   */
+  private async validateDoctorAvailability(
+    doctorId: string,
+    eventTime: CalendarEventTime,
+    clinicId: string
+  ): Promise<void> {
+    const startDate = eventTime.start.toDate();
+    const startTime = startDate;
+    const endTime = eventTime.end.toDate();
+
+    // Get doctor's document to check clinic-specific working hours
+    const practitionerRef = doc(this.db, PRACTITIONERS_COLLECTION, doctorId);
+    const practitionerDoc = await getDoc(practitionerRef);
+
+    if (!practitionerDoc.exists()) {
+      throw new Error(`Doctor with ID ${doctorId} not found`);
+    }
+
+    const practitioner = practitionerDoc.data();
+
+    // Check if doctor works at the specified clinic
+    if (!practitioner.clinics.includes(clinicId)) {
+      throw new Error("Doctor does not work at this clinic");
+    }
+
+    // Get doctor's clinic-specific working hours
+    const clinicWorkingHours = practitioner.clinicWorkingHours?.find(
+      (hours: PractitionerClinicWorkingHours) =>
+        hours.clinicId === clinicId && hours.isActive
+    );
+
+    if (!clinicWorkingHours) {
+      throw new Error("Doctor does not have working hours set for this clinic");
+    }
+
+    // Get the day of the week (0 = Sunday, 1 = Monday, etc.)
+    const dayOfWeek = startDate.getDay();
+    const dayKey = [
+      "sunday",
+      "monday",
+      "tuesday",
+      "wednesday",
+      "thursday",
+      "friday",
+      "saturday",
+    ][dayOfWeek];
+    const daySchedule = clinicWorkingHours.workingHours[dayKey];
+
+    if (!daySchedule) {
+      throw new Error("Doctor is not working on this day at this clinic");
+    }
+
+    // Convert working hours to Date objects for comparison
+    const [startHour, startMinute] = daySchedule.start.split(":").map(Number);
+    const [endHour, endMinute] = daySchedule.end.split(":").map(Number);
+
+    const scheduleStart = new Date(startDate);
+    scheduleStart.setHours(startHour, startMinute, 0, 0);
+
+    const scheduleEnd = new Date(startDate);
+    scheduleEnd.setHours(endHour, endMinute, 0, 0);
+
+    // Check if the appointment time is within doctor's working hours
+    if (startTime < scheduleStart || endTime > scheduleEnd) {
+      throw new Error(
+        "Appointment time is outside doctor's working hours at this clinic"
+      );
+    }
+
+    // Get existing appointments
+    const appointments = await this.getDoctorAppointments(doctorId, startDate);
+
+    // Check for overlapping appointments
+    const hasOverlap = appointments.some((appointment) => {
+      const appointmentStart = appointment.eventTime.start.toDate();
+      const appointmentEnd = appointment.eventTime.end.toDate();
+      return (
+        (startTime >= appointmentStart && startTime < appointmentEnd) ||
+        (endTime > appointmentStart && endTime <= appointmentEnd) ||
+        (startTime <= appointmentStart && endTime >= appointmentEnd)
+      );
+    });
+
+    if (hasOverlap) {
+      throw new Error("Doctor has another appointment during this time");
+    }
+  }
+
+  /**
+   * Updates appointment status
+   * @param appointmentId - ID of the appointment
+   * @param clinicId - ID of the clinic
+   * @param status - New status
+   * @returns Updated calendar event
+   */
+  private async updateAppointmentStatus(
+    appointmentId: string,
+    clinicId: string,
+    status: CalendarEventStatus
+  ): Promise<CalendarEvent> {
+    // Get the appointment
+    const appointmentRef = doc(this.db, CALENDAR_COLLECTION, appointmentId);
+    const appointmentDoc = await getDoc(appointmentRef);
+
+    if (!appointmentDoc.exists()) {
+      throw new Error(`Appointment with ID ${appointmentId} not found`);
+    }
+
+    const appointment = appointmentDoc.data() as CalendarEvent;
+
+    // Validate that the appointment belongs to the specified clinic
+    if (appointment.clinicBranchId !== clinicId) {
+      throw new Error("Appointment does not belong to the specified clinic");
+    }
+
+    // Validate the status transition
+    this.validateStatusTransition(appointment.status, status);
+
+    // Update the appointment
+    const updateParams: UpdateAppointmentParams = {
+      appointmentId,
+      clinicId,
+      doctorId: appointment.practitionerProfileId || "",
+      patientId: appointment.patientProfileId || "",
+      status,
+    };
+
+    // Validate update parameters
+    await this.validateUpdatePermissions(updateParams);
+
+    // Update the appointment
+    return this.updateAppointment(updateParams);
+  }
+
+  /**
+   * Validates status transition
+   * @param currentStatus - Current status
+   * @param newStatus - New status
+   * @throws Error if transition is invalid
+   */
+  private validateStatusTransition(
+    currentStatus: CalendarEventStatus,
+    newStatus: CalendarEventStatus
+  ): void {
+    // Define valid status transitions
+    const validTransitions: Record<CalendarEventStatus, CalendarEventStatus[]> =
+      {
+        [CalendarEventStatus.PENDING]: [
+          CalendarEventStatus.CONFIRMED,
+          CalendarEventStatus.REJECTED,
+          CalendarEventStatus.CANCELED,
+        ],
+        [CalendarEventStatus.CONFIRMED]: [
+          CalendarEventStatus.CANCELED,
+          CalendarEventStatus.COMPLETED,
+          CalendarEventStatus.RESCHEDULED,
+        ],
+        [CalendarEventStatus.REJECTED]: [],
+        [CalendarEventStatus.CANCELED]: [],
+        [CalendarEventStatus.RESCHEDULED]: [
+          CalendarEventStatus.CONFIRMED,
+          CalendarEventStatus.CANCELED,
+        ],
+        [CalendarEventStatus.COMPLETED]: [],
+      };
+
+    // Check if transition is valid
+    if (!validTransitions[currentStatus].includes(newStatus)) {
+      throw new Error(
+        `Invalid status transition from ${currentStatus} to ${newStatus}`
+      );
+    }
+  }
+
+  /**
+   * Syncs appointment with external calendars based on entity type and status
+   * @param appointment - Calendar event to sync
+   */
+  private async syncAppointmentWithExternalCalendars(
+    appointment: CalendarEvent
+  ): Promise<void> {
+    if (!appointment.practitionerProfileId || !appointment.patientProfileId) {
+      return;
+    }
+
+    try {
+      // Get synced calendars for doctor and patient (no longer sync with clinic)
+      const [doctorCalendars, patientCalendars] = await Promise.all([
+        this.syncedCalendarsService.getPractitionerSyncedCalendars(
+          appointment.practitionerProfileId
+        ),
+        this.syncedCalendarsService.getPatientSyncedCalendars(
+          appointment.patientProfileId
+        ),
+      ]);
+
+      // Filter active calendars
+      const activeDoctorCalendars = doctorCalendars.filter(
+        (cal) => cal.isActive
+      );
+      const activePatientCalendars = patientCalendars.filter(
+        (cal) => cal.isActive
+      );
+
+      // Skip if there are no active calendars
+      if (
+        activeDoctorCalendars.length === 0 &&
+        activePatientCalendars.length === 0
+      ) {
+        return;
+      }
+
+      // Only sync INTERNAL events (those created within our system)
+      if (appointment.syncStatus !== CalendarSyncStatus.INTERNAL) {
+        return;
+      }
+
+      // For doctors: Only sync CONFIRMED status events
+      if (
+        appointment.status === CalendarEventStatus.CONFIRMED &&
+        activeDoctorCalendars.length > 0
+      ) {
+        await Promise.all(
+          activeDoctorCalendars.map((calendar) =>
+            this.syncEventToExternalCalendar(appointment, calendar, "doctor")
+          )
+        );
+      }
+
+      // For patients: Sync all events EXCEPT CANCELED and REJECTED
+      if (
+        appointment.status !== CalendarEventStatus.CANCELED &&
+        appointment.status !== CalendarEventStatus.REJECTED &&
+        activePatientCalendars.length > 0
+      ) {
+        await Promise.all(
+          activePatientCalendars.map((calendar) =>
+            this.syncEventToExternalCalendar(appointment, calendar, "patient")
+          )
+        );
+      }
+    } catch (error) {
+      console.error("Error syncing with external calendars:", error);
+      // Don't throw error as this is not critical for appointment creation
+    }
+  }
+
+  /**
+   * Syncs a single event to an external calendar
+   * @param appointment - Calendar event to sync
+   * @param calendar - External calendar to sync with
+   * @param entityType - Type of entity owning the calendar
+   */
+  private async syncEventToExternalCalendar(
+    appointment: CalendarEvent,
+    calendar: any,
+    entityType: "doctor" | "patient"
+  ): Promise<void> {
+    try {
+      // Create a copy of the appointment to modify for external syncing
+      const eventToSync = { ...appointment };
+
+      // Prepare event title based on status and entity type
+      let eventTitle = appointment.eventName;
+      const clinicName = appointment.clinicBranchInfo?.name || "Clinic";
+
+      // Format title appropriately
+      if (entityType === "patient") {
+        eventTitle = `[${appointment.status}] ${eventTitle} @ ${clinicName}`;
+      } else {
+        eventTitle = `${eventTitle} - Patient: ${
+          appointment.patientProfileInfo?.fullName || "Unknown"
+        } @ ${clinicName}`;
+      }
+
+      // Update the event name for external sync
+      eventToSync.eventName = eventTitle;
+
+      // Check if this event was previously synced with this calendar
+      const existingSyncId = appointment.syncedCalendarEventId?.find(
+        (sync) => sync.syncedCalendarProvider === calendar.provider
+      )?.eventId;
+
+      // If we have a synced event ID, we should update the existing event
+      // If not, create a new event
+
+      if (calendar.provider === SyncedCalendarProvider.GOOGLE) {
+        const result =
+          await this.syncedCalendarsService.syncPractitionerEventsToGoogleCalendar(
+            entityType === "doctor"
+              ? appointment.practitionerProfileId!
+              : appointment.patientProfileId!,
+            calendar.id,
+            [eventToSync],
+            existingSyncId // Pass existing sync ID if we have one
+          );
+
+        // If sync was successful and we've created a new event (no existing sync),
+        // we should update our local event with the new sync ID
+        if (result.success && result.eventIds?.length && !existingSyncId) {
+          // Update the appointment with the new sync ID
+          const newSyncEvent: SyncedCalendarEvent = {
+            eventId: result.eventIds[0],
+            syncedCalendarProvider: calendar.provider,
+            syncedAt: Timestamp.now(),
+          };
+
+          // Update the event in the database with the new sync ID
+          await this.updateEventWithSyncId(
+            entityType === "doctor"
+              ? appointment.practitionerProfileId!
+              : appointment.patientProfileId!,
+            entityType,
+            appointment.id,
+            newSyncEvent
+          );
+        }
+      }
+    } catch (error) {
+      console.error(`Error syncing with ${entityType}'s calendar:`, error);
+      // Don't throw error as this is not critical
+    }
+  }
+
+  /**
+   * Updates an event with a new sync ID
+   * @param entityId - ID of the entity (doctor or patient)
+   * @param entityType - Type of entity
+   * @param eventId - ID of the event
+   * @param syncEvent - Sync event information
+   */
+  private async updateEventWithSyncId(
+    entityId: string,
+    entityType: "doctor" | "patient",
+    eventId: string,
+    syncEvent: SyncedCalendarEvent
+  ): Promise<void> {
+    try {
+      // Determine the collection path based on entity type
+      const collectionPath =
+        entityType === "doctor"
+          ? `${PRACTITIONERS_COLLECTION}/${entityId}/${CALENDAR_COLLECTION}`
+          : `${PATIENTS_COLLECTION}/${entityId}/${CALENDAR_COLLECTION}`;
+
+      // Get the event reference
+      const eventRef = doc(this.db, collectionPath, eventId);
+      const eventDoc = await getDoc(eventRef);
+
+      if (eventDoc.exists()) {
+        const event = eventDoc.data() as CalendarEvent;
+        const syncIds = [...(event.syncedCalendarEventId || [])];
+
+        // Check if we already have this sync ID
+        const existingSyncIndex = syncIds.findIndex(
+          (sync) =>
+            sync.syncedCalendarProvider === syncEvent.syncedCalendarProvider
+        );
+
+        if (existingSyncIndex >= 0) {
+          // Update the existing sync ID
+          syncIds[existingSyncIndex] = syncEvent;
+        } else {
+          // Add the new sync ID
+          syncIds.push(syncEvent);
+        }
+
+        // Update the event
+        await updateDoc(eventRef, {
+          syncedCalendarEventId: syncIds,
+          updatedAt: serverTimestamp(),
+        });
+
+        console.log(
+          `Updated event ${eventId} with sync ID ${syncEvent.eventId}`
+        );
+      }
+    } catch (error) {
+      console.error("Error updating event with sync ID:", error);
+    }
+  }
+
+  /**
+   * Validates update permissions and parameters
+   * @param params - Update parameters to validate
+   */
+  private async validateUpdatePermissions(
+    params: UpdateAppointmentParams
+  ): Promise<void> {
+    // TODO: Add custom validation logic after Zod schema validation
+    // - Check if user has permission to update the appointment
+    // - Check if the appointment exists
+    // - Check if the new status transition is valid
+    // - Check if the new time slot is valid
+    // - Validate against clinic's business rules
+
+    // Validate basic parameters using Zod schema
+    await updateAppointmentSchema.parseAsync(params);
+  }
+
+  /**
+   * Gets clinic working hours for a specific date
+   * @param clinicId - ID of the clinic
+   * @param date - Date to get working hours for
+   * @returns Working hours for the clinic
+   */
+  private async getClinicWorkingHours(
+    clinicId: string,
+    date: Date
+  ): Promise<TimeSlot[]> {
+    // Get clinic document
+    const clinicRef = doc(this.db, CLINICS_COLLECTION, clinicId);
+    const clinicDoc = await getDoc(clinicRef);
+
+    if (!clinicDoc.exists()) {
+      throw new Error(`Clinic with ID ${clinicId} not found`);
+    }
+
+    // TODO: Implement proper working hours retrieval from clinic data model
+    // For now, return default working hours (9 AM - 5 PM)
+    const workingHours: TimeSlot[] = [];
+    const dayOfWeek = date.getDay();
+
+    // Skip weekends (0 = Sunday, 6 = Saturday)
+    if (dayOfWeek === 0 || dayOfWeek === 6) {
+      return workingHours;
+    }
+
+    // Create working hours slot (9 AM - 5 PM)
+    const workingDate = new Date(date);
+    workingDate.setHours(9, 0, 0, 0);
+    const startTime = new Date(workingDate);
+
+    workingDate.setHours(17, 0, 0, 0);
+    const endTime = new Date(workingDate);
+
+    workingHours.push({
+      start: startTime,
+      end: endTime,
+      isAvailable: true,
+    });
+
+    return workingHours;
+  }
+
+  /**
+   * Gets doctor's schedule for a specific date
+   * @param doctorId - ID of the doctor
+   * @param date - Date to get schedule for
+   * @returns Doctor's schedule
+   */
+  private async getDoctorSchedule(
+    doctorId: string,
+    date: Date
+  ): Promise<TimeSlot[]> {
+    // Get doctor document
+    const practitionerRef = doc(this.db, PRACTITIONERS_COLLECTION, doctorId);
+    const practitionerDoc = await getDoc(practitionerRef);
+
+    if (!practitionerDoc.exists()) {
+      throw new Error(`Doctor with ID ${doctorId} not found`);
+    }
+
+    // TODO: Implement proper schedule retrieval from practitioner data model
+    // For now, return default schedule (9 AM - 5 PM)
+    const schedule: TimeSlot[] = [];
+    const dayOfWeek = date.getDay();
+
+    // Skip weekends (0 = Sunday, 6 = Saturday)
+    if (dayOfWeek === 0 || dayOfWeek === 6) {
+      return schedule;
+    }
+
+    // Create schedule slot (9 AM - 5 PM)
+    const scheduleDate = new Date(date);
+    scheduleDate.setHours(9, 0, 0, 0);
+    const startTime = new Date(scheduleDate);
+
+    scheduleDate.setHours(17, 0, 0, 0);
+    const endTime = new Date(scheduleDate);
+
+    schedule.push({
+      start: startTime,
+      end: endTime,
+      isAvailable: true,
+    });
+
+    return schedule;
+  }
+
+  /**
+   * Gets doctor's appointments for a specific date
+   * @param doctorId - ID of the doctor
+   * @param date - Date to get appointments for
+   * @returns Array of calendar events
+   */
+  private async getDoctorAppointments(
+    doctorId: string,
+    date: Date
+  ): Promise<CalendarEvent[]> {
+    // Create start and end timestamps for the day
+    const startOfDay = new Date(date);
+    startOfDay.setHours(0, 0, 0, 0);
+    const endOfDay = new Date(date);
+    endOfDay.setHours(23, 59, 59, 999);
+
+    // Query appointments for the doctor on the specified date
+    const appointmentsRef = collection(this.db, CALENDAR_COLLECTION);
+    const q = query(
+      appointmentsRef,
+      where("practitionerProfileId", "==", doctorId),
+      where("eventTime.start", ">=", Timestamp.fromDate(startOfDay)),
+      where("eventTime.start", "<=", Timestamp.fromDate(endOfDay)),
+      where("status", "in", [
+        CalendarEventStatus.CONFIRMED,
+        CalendarEventStatus.PENDING,
+      ])
+    );
+
+    const querySnapshot = await getDocs(q);
+    return querySnapshot.docs.map((doc) => doc.data() as CalendarEvent);
+  }
+
+  /**
+   * Calculates available time slots based on working hours, schedule and existing appointments
+   * @param workingHours - Clinic working hours
+   * @param doctorSchedule - Doctor's schedule
+   * @param existingAppointments - Existing appointments
+   * @returns Array of available time slots
+   */
+  private calculateAvailableSlots(
+    workingHours: TimeSlot[],
+    doctorSchedule: TimeSlot[],
+    existingAppointments: CalendarEvent[]
+  ): TimeSlot[] {
+    const availableSlots: TimeSlot[] = [];
+
+    // First, find overlapping time slots between clinic hours and doctor schedule
+    for (const workingHour of workingHours) {
+      for (const scheduleSlot of doctorSchedule) {
+        // Find overlap between working hours and doctor schedule
+        const overlapStart = new Date(
+          Math.max(workingHour.start.getTime(), scheduleSlot.start.getTime())
+        );
+        const overlapEnd = new Date(
+          Math.min(workingHour.end.getTime(), scheduleSlot.end.getTime())
+        );
+
+        // If there is an overlap and both slots are available
+        if (
+          overlapStart < overlapEnd &&
+          workingHour.isAvailable &&
+          scheduleSlot.isAvailable
+        ) {
+          // Create 15-minute slots within the overlap period
+          let slotStart = new Date(overlapStart);
+          while (slotStart < overlapEnd) {
+            const slotEnd = new Date(
+              slotStart.getTime() + MIN_APPOINTMENT_DURATION * 60 * 1000
+            );
+
+            // Check if this slot overlaps with any existing appointments
+            const hasOverlap = existingAppointments.some((appointment) => {
+              const appointmentStart = appointment.eventTime.start.toDate();
+              const appointmentEnd = appointment.eventTime.end.toDate();
+              return (
+                (slotStart >= appointmentStart && slotStart < appointmentEnd) ||
+                (slotEnd > appointmentStart && slotEnd <= appointmentEnd)
+              );
+            });
+
+            if (!hasOverlap && slotEnd <= overlapEnd) {
+              availableSlots.push({
+                start: new Date(slotStart),
+                end: new Date(slotEnd),
+                isAvailable: true,
+              });
+            }
+
+            // Move to next slot
+            slotStart = new Date(
+              slotStart.getTime() + MIN_APPOINTMENT_DURATION * 60 * 1000
+            );
+          }
+        }
+      }
+    }
+
+    return availableSlots;
+  }
+
+  /**
+   * Fetches and creates info cards for clinic, doctor, and patient profiles
+   * @param clinicId - ID of the clinic
+   * @param doctorId - ID of the doctor
+   * @param patientId - ID of the patient
+   * @returns Object containing info cards for all profiles
+   */
+  private async fetchProfileInfoCards(
+    clinicId: string,
+    doctorId: string,
+    patientId: string
+  ): Promise<{
+    clinicInfo: ClinicInfo | null;
+    practitionerInfo: PractitionerProfileInfo | null;
+    patientInfo: PatientProfileInfo | null;
+  }> {
+    try {
+      // Fetch all profiles concurrently
+      const [clinicDoc, practitionerDoc, patientDoc, patientSensitiveInfoDoc] =
+        await Promise.all([
+          getDoc(doc(this.db, CLINICS_COLLECTION, clinicId)),
+          getDoc(doc(this.db, PRACTITIONERS_COLLECTION, doctorId)),
+          getDoc(doc(this.db, PATIENTS_COLLECTION, patientId)),
+          getDoc(
+            doc(
+              this.db,
+              PATIENTS_COLLECTION,
+              patientId,
+              PATIENT_SENSITIVE_INFO_COLLECTION,
+              patientId
+            )
+          ),
+        ]);
+
+      // Create info cards
+      const clinicInfo: ClinicInfo | null = clinicDoc.exists()
+        ? {
+            id: clinicDoc.id,
+            featuredPhoto: clinicDoc.data().featuredPhoto || "",
+            name: clinicDoc.data().name,
+            description: clinicDoc.data().description || "",
+            location: clinicDoc.data().location,
+            contactInfo: clinicDoc.data().contactInfo,
+          }
+        : null;
+
+      const practitionerInfo: PractitionerProfileInfo | null =
+        practitionerDoc.exists()
+          ? {
+              id: practitionerDoc.id,
+              practitionerPhoto:
+                practitionerDoc.data().basicInfo.profileImageUrl || null,
+              name: `${practitionerDoc.data().basicInfo.firstName} ${
+                practitionerDoc.data().basicInfo.lastName
+              }`,
+              email: practitionerDoc.data().basicInfo.email,
+              phone: practitionerDoc.data().basicInfo.phoneNumber || null,
+              certification: practitionerDoc.data().certification,
+            }
+          : null;
+
+      // First try to get data from sensitive-info subcollection
+      let patientInfo: PatientProfileInfo | null = null;
+
+      if (patientSensitiveInfoDoc.exists()) {
+        const sensitiveData = patientSensitiveInfoDoc.data();
+        patientInfo = {
+          id: patientId,
+          fullName: `${sensitiveData.firstName} ${sensitiveData.lastName}`,
+          email: sensitiveData.email || "",
+          phone: sensitiveData.phoneNumber || null,
+          dateOfBirth: sensitiveData.dateOfBirth || Timestamp.now(),
+          gender: sensitiveData.gender || Gender.OTHER,
+        };
+      } else if (patientDoc.exists()) {
+        // Fall back to patient document if sensitive info not available
+        patientInfo = {
+          id: patientDoc.id,
+          fullName: patientDoc.data().displayName,
+          email: patientDoc.data().contactInfo?.email || "",
+          phone: patientDoc.data().phoneNumber || null,
+          dateOfBirth: patientDoc.data().dateOfBirth || Timestamp.now(),
+          gender: patientDoc.data().gender || Gender.OTHER,
+        };
+      }
+
+      return {
+        clinicInfo,
+        practitionerInfo,
+        patientInfo,
+      };
+    } catch (error) {
+      console.error("Error fetching profile info cards:", error);
+      return {
+        clinicInfo: null,
+        practitionerInfo: null,
+        patientInfo: null,
+      };
+    }
+  }
+
+  // #endregion
+}