@blackcode_sa/metaestetics-api 1.5.32 → 1.5.33

package/src/admin/booking/booking.calculator.ts

@@ -0,0 +1,686 @@
+import { Timestamp } from "firebase/firestore";
+import {
+  BookingAvailabilityRequest,
+  BookingAvailabilityResponse,
+  AvailableSlot,
+  TimeInterval,
+} from "./booking.types";
+import {
+  CalendarEvent,
+  CalendarEventStatus,
+  CalendarEventType,
+} from "../../types/calendar";
+import { PractitionerClinicWorkingHours } from "../../types/practitioner";
+import { Clinic } from "../../types/clinic";
+
+/**
+ * Calculator for determining available booking slots
+ * This class handles the complex logic of determining when appointments can be scheduled
+ * based on clinic working hours, practitioner availability, and existing calendar events.
+ */
+export class BookingAvailabilityCalculator {
+  /** Default scheduling interval in minutes if not specified by the clinic */
+  private static readonly DEFAULT_INTERVAL_MINUTES = 15;
+
+  /**
+   * Calculate available booking slots based on the provided data
+   *
+   * @param request - The request containing all necessary data for calculation
+   * @returns Response with available booking slots
+   */
+  public static calculateSlots(
+    request: BookingAvailabilityRequest
+  ): BookingAvailabilityResponse {
+    // Extract necessary data from the request
+    const {
+      clinic,
+      practitioner,
+      procedure,
+      timeframe,
+      clinicCalendarEvents,
+      practitionerCalendarEvents,
+    } = request;
+
+    // Get scheduling interval (default to 15 minutes if not specified)
+    const schedulingIntervalMinutes =
+      (clinic as any).schedulingInterval || this.DEFAULT_INTERVAL_MINUTES;
+
+    // Get procedure duration in minutes
+    const procedureDurationMinutes = procedure.duration;
+
+    console.log(
+      `Calculating slots with interval: ${schedulingIntervalMinutes}min and procedure duration: ${procedureDurationMinutes}min`
+    );
+
+    // Start with the full timeframe as initially available
+    let availableIntervals: TimeInterval[] = [
+      { start: timeframe.start, end: timeframe.end },
+    ];
+
+    // Step 1: Apply clinic working hours
+    availableIntervals = this.applyClinicWorkingHours(
+      availableIntervals,
+      clinic.workingHours,
+      timeframe
+    );
+
+    // Step 2: Subtract clinic blocking events
+    availableIntervals = this.subtractBlockingEvents(
+      availableIntervals,
+      clinicCalendarEvents
+    );
+
+    // Step 3: Apply practitioner's working hours for this clinic
+    availableIntervals = this.applyPractitionerWorkingHours(
+      availableIntervals,
+      practitioner,
+      clinic.id,
+      timeframe
+    );
+
+    // Step 4: Subtract practitioner's busy times
+    availableIntervals = this.subtractPractitionerBusyTimes(
+      availableIntervals,
+      practitionerCalendarEvents
+    );
+
+    console.log(
+      `After all filters, have ${availableIntervals.length} available intervals`
+    );
+
+    // Step 5: Generate available slots based on scheduling interval and procedure duration
+    const availableSlots = this.generateAvailableSlots(
+      availableIntervals,
+      schedulingIntervalMinutes,
+      procedureDurationMinutes
+    );
+
+    return { availableSlots };
+  }
+
+  /**
+   * Apply clinic working hours to available intervals
+   *
+   * @param intervals - Current available intervals
+   * @param workingHours - Clinic working hours
+   * @param timeframe - Overall timeframe being considered
+   * @returns Intervals filtered by clinic working hours
+   */
+  private static applyClinicWorkingHours(
+    intervals: TimeInterval[],
+    workingHours: any, // Using 'any' for now since we're working with the existing type structure
+    timeframe: { start: Timestamp; end: Timestamp }
+  ): TimeInterval[] {
+    if (!intervals.length) return [];
+    console.log(
+      `Applying clinic working hours to ${intervals.length} intervals`
+    );
+
+    // Create working intervals for each day in the timeframe based on clinic's working hours
+    const workingIntervals = this.createWorkingHoursIntervals(
+      workingHours,
+      timeframe.start.toDate(),
+      timeframe.end.toDate()
+    );
+
+    // Intersect the available intervals with working hours intervals
+    return this.intersectIntervals(intervals, workingIntervals);
+  }
+
+  /**
+   * Create time intervals for working hours across multiple days
+   *
+   * @param workingHours - Working hours definition
+   * @param startDate - Start date of the overall timeframe
+   * @param endDate - End date of the overall timeframe
+   * @returns Array of time intervals representing working hours
+   */
+  private static createWorkingHoursIntervals(
+    workingHours: any,
+    startDate: Date,
+    endDate: Date
+  ): TimeInterval[] {
+    const workingIntervals: TimeInterval[] = [];
+
+    // Clone the start date to avoid modifying the original
+    const currentDate = new Date(startDate);
+
+    // Reset time to start of day
+    currentDate.setHours(0, 0, 0, 0);
+
+    // Create a map of day names to day numbers (0 = Sunday, 1 = Monday, etc.)
+    const dayNameToNumber: { [key: string]: number } = {
+      sunday: 0,
+      monday: 1,
+      tuesday: 2,
+      wednesday: 3,
+      thursday: 4,
+      friday: 5,
+      saturday: 6,
+    };
+
+    // Iterate through each day in the timeframe
+    while (currentDate <= endDate) {
+      const dayOfWeek = currentDate.getDay();
+      const dayName = Object.keys(dayNameToNumber).find(
+        (key) => dayNameToNumber[key] === dayOfWeek
+      );
+
+      if (dayName && workingHours[dayName]) {
+        const daySchedule = workingHours[dayName];
+
+        if (daySchedule) {
+          // Parse open and close times
+          const [openHours, openMinutes] = daySchedule.open
+            .split(":")
+            .map(Number);
+          const [closeHours, closeMinutes] = daySchedule.close
+            .split(":")
+            .map(Number);
+
+          // Create start and end times for this working day
+          const workStart = new Date(currentDate);
+          workStart.setHours(openHours, openMinutes, 0, 0);
+
+          const workEnd = new Date(currentDate);
+          workEnd.setHours(closeHours, closeMinutes, 0, 0);
+
+          // Only add if the working hours are within our timeframe
+          if (workEnd > startDate && workStart < endDate) {
+            // Adjust interval to be within our overall timeframe
+            const intervalStart = workStart < startDate ? startDate : workStart;
+            const intervalEnd = workEnd > endDate ? endDate : workEnd;
+
+            workingIntervals.push({
+              start: Timestamp.fromDate(intervalStart),
+              end: Timestamp.fromDate(intervalEnd),
+            });
+
+            // Handle breaks if they exist
+            if (daySchedule.breaks && daySchedule.breaks.length > 0) {
+              for (const breakTime of daySchedule.breaks) {
+                const [breakStartHours, breakStartMinutes] = breakTime.start
+                  .split(":")
+                  .map(Number);
+                const [breakEndHours, breakEndMinutes] = breakTime.end
+                  .split(":")
+                  .map(Number);
+
+                const breakStart = new Date(currentDate);
+                breakStart.setHours(breakStartHours, breakStartMinutes, 0, 0);
+
+                const breakEnd = new Date(currentDate);
+                breakEnd.setHours(breakEndHours, breakEndMinutes, 0, 0);
+
+                // Subtract this break from our working intervals
+                workingIntervals.splice(
+                  -1,
+                  1,
+                  ...this.subtractInterval(
+                    workingIntervals[workingIntervals.length - 1],
+                    {
+                      start: Timestamp.fromDate(breakStart),
+                      end: Timestamp.fromDate(breakEnd),
+                    }
+                  )
+                );
+              }
+            }
+          }
+        }
+      }
+
+      // Move to the next day
+      currentDate.setDate(currentDate.getDate() + 1);
+    }
+
+    return workingIntervals;
+  }
+
+  /**
+   * Subtract blocking events from available intervals
+   *
+   * @param intervals - Current available intervals
+   * @param events - Calendar events to subtract
+   * @returns Available intervals after removing blocking events
+   */
+  private static subtractBlockingEvents(
+    intervals: TimeInterval[],
+    events: CalendarEvent[]
+  ): TimeInterval[] {
+    if (!intervals.length) return [];
+    console.log(`Subtracting ${events.length} blocking events`);
+
+    // Filter only blocking-type events
+    const blockingEvents = events.filter(
+      (event) =>
+        event.eventType === CalendarEventType.BLOCKING ||
+        event.eventType === CalendarEventType.BREAK ||
+        event.eventType === CalendarEventType.FREE_DAY
+    );
+
+    let result = [...intervals];
+
+    // For each blocking event, subtract its time from the available intervals
+    for (const event of blockingEvents) {
+      const { start, end } = event.eventTime;
+      const blockingInterval = { start, end };
+
+      // Create a new result array by subtracting the blocking interval from each available interval
+      const newResult: TimeInterval[] = [];
+
+      for (const interval of result) {
+        const remainingIntervals = this.subtractInterval(
+          interval,
+          blockingInterval
+        );
+        newResult.push(...remainingIntervals);
+      }
+
+      result = newResult;
+    }
+
+    return result;
+  }
+
+  /**
+   * Apply practitioner's specific working hours for the given clinic
+   *
+   * @param intervals - Current available intervals
+   * @param practitioner - Practitioner object
+   * @param clinicId - ID of the clinic
+   * @param timeframe - Overall timeframe being considered
+   * @returns Intervals filtered by practitioner's working hours
+   */
+  private static applyPractitionerWorkingHours(
+    intervals: TimeInterval[],
+    practitioner: any,
+    clinicId: string,
+    timeframe: { start: Timestamp; end: Timestamp }
+  ): TimeInterval[] {
+    if (!intervals.length) return [];
+    console.log(`Applying practitioner working hours for clinic ${clinicId}`);
+
+    // Find practitioner's working hours for this specific clinic
+    const clinicWorkingHours = practitioner.clinicWorkingHours.find(
+      (hours: PractitionerClinicWorkingHours) =>
+        hours.clinicId === clinicId && hours.isActive
+    );
+
+    // If no specific working hours are found, practitioner isn't available at this clinic
+    if (!clinicWorkingHours) {
+      console.log(
+        `No working hours found for practitioner at clinic ${clinicId}`
+      );
+      return [];
+    }
+
+    // Create working intervals for each day in the timeframe based on practitioner's working hours
+    const workingIntervals = this.createPractitionerWorkingHoursIntervals(
+      clinicWorkingHours.workingHours,
+      timeframe.start.toDate(),
+      timeframe.end.toDate()
+    );
+
+    // Intersect the available intervals with practitioner's working hours intervals
+    return this.intersectIntervals(intervals, workingIntervals);
+  }
+
+  /**
+   * Create time intervals for practitioner's working hours across multiple days
+   *
+   * @param workingHours - Practitioner's working hours definition
+   * @param startDate - Start date of the overall timeframe
+   * @param endDate - End date of the overall timeframe
+   * @returns Array of time intervals representing practitioner's working hours
+   */
+  private static createPractitionerWorkingHoursIntervals(
+    workingHours: any,
+    startDate: Date,
+    endDate: Date
+  ): TimeInterval[] {
+    const workingIntervals: TimeInterval[] = [];
+
+    // Clone the start date to avoid modifying the original
+    const currentDate = new Date(startDate);
+
+    // Reset time to start of day
+    currentDate.setHours(0, 0, 0, 0);
+
+    // Create a map of day names to day numbers (0 = Sunday, 1 = Monday, etc.)
+    const dayNameToNumber: { [key: string]: number } = {
+      sunday: 0,
+      monday: 1,
+      tuesday: 2,
+      wednesday: 3,
+      thursday: 4,
+      friday: 5,
+      saturday: 6,
+    };
+
+    // Iterate through each day in the timeframe
+    while (currentDate <= endDate) {
+      const dayOfWeek = currentDate.getDay();
+      const dayName = Object.keys(dayNameToNumber).find(
+        (key) => dayNameToNumber[key] === dayOfWeek
+      );
+
+      if (dayName && workingHours[dayName]) {
+        const daySchedule = workingHours[dayName];
+
+        if (daySchedule) {
+          // Parse start and end times
+          const [startHours, startMinutes] = daySchedule.start
+            .split(":")
+            .map(Number);
+          const [endHours, endMinutes] = daySchedule.end.split(":").map(Number);
+
+          // Create start and end times for this working day
+          const workStart = new Date(currentDate);
+          workStart.setHours(startHours, startMinutes, 0, 0);
+
+          const workEnd = new Date(currentDate);
+          workEnd.setHours(endHours, endMinutes, 0, 0);
+
+          // Only add if the working hours are within our timeframe
+          if (workEnd > startDate && workStart < endDate) {
+            // Adjust interval to be within our overall timeframe
+            const intervalStart = workStart < startDate ? startDate : workStart;
+            const intervalEnd = workEnd > endDate ? endDate : workEnd;
+
+            workingIntervals.push({
+              start: Timestamp.fromDate(intervalStart),
+              end: Timestamp.fromDate(intervalEnd),
+            });
+          }
+        }
+      }
+
+      // Move to the next day
+      currentDate.setDate(currentDate.getDate() + 1);
+    }
+
+    return workingIntervals;
+  }
+
+  /**
+   * Subtract practitioner's busy times from available intervals
+   *
+   * @param intervals - Current available intervals
+   * @param events - Practitioner's calendar events
+   * @returns Available intervals after removing busy times
+   */
+  private static subtractPractitionerBusyTimes(
+    intervals: TimeInterval[],
+    events: CalendarEvent[]
+  ): TimeInterval[] {
+    if (!intervals.length) return [];
+    console.log(`Subtracting ${events.length} practitioner events`);
+
+    // Filter events that make the practitioner busy (pending, confirmed, blocking)
+    const busyEvents = events.filter(
+      (event) =>
+        // Include all blocking events
+        event.eventType === CalendarEventType.BLOCKING ||
+        event.eventType === CalendarEventType.BREAK ||
+        event.eventType === CalendarEventType.FREE_DAY ||
+        // Include appointments that are pending, confirmed, or rescheduled
+        (event.eventType === CalendarEventType.APPOINTMENT &&
+          (event.status === CalendarEventStatus.PENDING ||
+            event.status === CalendarEventStatus.CONFIRMED ||
+            event.status === CalendarEventStatus.RESCHEDULED))
+    );
+
+    let result = [...intervals];
+
+    // For each busy event, subtract its time from the available intervals
+    for (const event of busyEvents) {
+      const { start, end } = event.eventTime;
+      const busyInterval = { start, end };
+
+      // Create a new result array by subtracting the busy interval from each available interval
+      const newResult: TimeInterval[] = [];
+
+      for (const interval of result) {
+        const remainingIntervals = this.subtractInterval(
+          interval,
+          busyInterval
+        );
+        newResult.push(...remainingIntervals);
+      }
+
+      result = newResult;
+    }
+
+    return result;
+  }
+
+  /**
+   * Generate available booking slots based on the final available intervals
+   *
+   * @param intervals - Final available intervals
+   * @param intervalMinutes - Scheduling interval in minutes
+   * @param durationMinutes - Procedure duration in minutes
+   * @returns Array of available booking slots
+   */
+  private static generateAvailableSlots(
+    intervals: TimeInterval[],
+    intervalMinutes: number,
+    durationMinutes: number
+  ): AvailableSlot[] {
+    const slots: AvailableSlot[] = [];
+    console.log(
+      `Generating slots with ${intervalMinutes}min intervals for ${durationMinutes}min procedure`
+    );
+
+    // Convert duration to milliseconds
+    const durationMs = durationMinutes * 60 * 1000;
+    // Convert interval to milliseconds
+    const intervalMs = intervalMinutes * 60 * 1000;
+
+    // For each available interval
+    for (const interval of intervals) {
+      // Convert timestamps to JS Date objects for easier manipulation
+      const intervalStart = interval.start.toDate();
+      const intervalEnd = interval.end.toDate();
+
+      // Start at the beginning of the interval
+      let slotStart = new Date(intervalStart);
+
+      // Adjust slotStart to the nearest interval boundary if needed
+      const minutesIntoDay = slotStart.getHours() * 60 + slotStart.getMinutes();
+      const minutesRemainder = minutesIntoDay % intervalMinutes;
+
+      if (minutesRemainder > 0) {
+        slotStart.setMinutes(
+          slotStart.getMinutes() + (intervalMinutes - minutesRemainder)
+        );
+      }
+
+      // Iterate through potential start times
+      while (slotStart.getTime() + durationMs <= intervalEnd.getTime()) {
+        // Calculate potential end time
+        const slotEnd = new Date(slotStart.getTime() + durationMs);
+
+        // Check if this slot fits entirely within one of our available intervals
+        if (this.isSlotFullyAvailable(slotStart, slotEnd, intervals)) {
+          slots.push({
+            start: Timestamp.fromDate(slotStart),
+          });
+        }
+
+        // Move to the next potential start time
+        slotStart = new Date(slotStart.getTime() + intervalMs);
+      }
+    }
+
+    console.log(`Generated ${slots.length} available slots`);
+    return slots;
+  }
+
+  /**
+   * Check if a time slot is fully available within the given intervals
+   *
+   * @param slotStart - Start time of the slot
+   * @param slotEnd - End time of the slot
+   * @param intervals - Available intervals
+   * @returns True if the slot is fully contained within an available interval
+   */
+  private static isSlotFullyAvailable(
+    slotStart: Date,
+    slotEnd: Date,
+    intervals: TimeInterval[]
+  ): boolean {
+    // Check if the slot is fully contained in any of the available intervals
+    return intervals.some((interval) => {
+      const intervalStart = interval.start.toDate();
+      const intervalEnd = interval.end.toDate();
+
+      return slotStart >= intervalStart && slotEnd <= intervalEnd;
+    });
+  }
+
+  /**
+   * Intersect two sets of time intervals
+   *
+   * @param intervalsA - First set of intervals
+   * @param intervalsB - Second set of intervals
+   * @returns Intersection of the two sets of intervals
+   */
+  private static intersectIntervals(
+    intervalsA: TimeInterval[],
+    intervalsB: TimeInterval[]
+  ): TimeInterval[] {
+    const result: TimeInterval[] = [];
+
+    // For each pair of intervals, find their intersection
+    for (const intervalA of intervalsA) {
+      for (const intervalB of intervalsB) {
+        // Find the later of the two start times
+        const intersectionStart =
+          intervalA.start.toMillis() > intervalB.start.toMillis()
+            ? intervalA.start
+            : intervalB.start;
+
+        // Find the earlier of the two end times
+        const intersectionEnd =
+          intervalA.end.toMillis() < intervalB.end.toMillis()
+            ? intervalA.end
+            : intervalB.end;
+
+        // If there is a valid intersection, add it to the result
+        if (intersectionStart.toMillis() < intersectionEnd.toMillis()) {
+          result.push({
+            start: intersectionStart,
+            end: intersectionEnd,
+          });
+        }
+      }
+    }
+
+    return this.mergeOverlappingIntervals(result);
+  }
+
+  /**
+   * Subtract one interval from another, potentially resulting in 0, 1, or 2 intervals
+   *
+   * @param interval - Interval to subtract from
+   * @param subtrahend - Interval to subtract
+   * @returns Array of remaining intervals after subtraction
+   */
+  private static subtractInterval(
+    interval: TimeInterval,
+    subtrahend: TimeInterval
+  ): TimeInterval[] {
+    // Case 1: No overlap - return the original interval
+    if (
+      interval.end.toMillis() <= subtrahend.start.toMillis() ||
+      interval.start.toMillis() >= subtrahend.end.toMillis()
+    ) {
+      return [interval];
+    }
+
+    // Case 2: Subtrahend covers the entire interval - return empty array
+    if (
+      subtrahend.start.toMillis() <= interval.start.toMillis() &&
+      subtrahend.end.toMillis() >= interval.end.toMillis()
+    ) {
+      return [];
+    }
+
+    // Case 3: Subtrahend splits the interval - return two intervals
+    if (
+      subtrahend.start.toMillis() > interval.start.toMillis() &&
+      subtrahend.end.toMillis() < interval.end.toMillis()
+    ) {
+      return [
+        {
+          start: interval.start,
+          end: subtrahend.start,
+        },
+        {
+          start: subtrahend.end,
+          end: interval.end,
+        },
+      ];
+    }
+
+    // Case 4: Subtrahend overlaps only the start - return the remaining end portion
+    if (
+      subtrahend.start.toMillis() <= interval.start.toMillis() &&
+      subtrahend.end.toMillis() > interval.start.toMillis()
+    ) {
+      return [
+        {
+          start: subtrahend.end,
+          end: interval.end,
+        },
+      ];
+    }
+
+    // Case 5: Subtrahend overlaps only the end - return the remaining start portion
+    return [
+      {
+        start: interval.start,
+        end: subtrahend.start,
+      },
+    ];
+  }
+
+  /**
+   * Merge overlapping intervals to simplify the result
+   *
+   * @param intervals - Intervals to merge
+   * @returns Merged intervals
+   */
+  private static mergeOverlappingIntervals(
+    intervals: TimeInterval[]
+  ): TimeInterval[] {
+    if (intervals.length <= 1) return intervals;
+
+    // Sort intervals by start time
+    const sorted = [...intervals].sort(
+      (a, b) => a.start.toMillis() - b.start.toMillis()
+    );
+
+    const result: TimeInterval[] = [sorted[0]];
+
+    for (let i = 1; i < sorted.length; i++) {
+      const current = sorted[i];
+      const lastResult = result[result.length - 1];
+
+      // If current interval overlaps with the last result interval, merge them
+      if (current.start.toMillis() <= lastResult.end.toMillis()) {
+        // Update the end time of the last result to be the maximum of the two end times
+        if (current.end.toMillis() > lastResult.end.toMillis()) {
+          lastResult.end = current.end;
+        }
+      } else {
+        // No overlap, add the current interval to the result
+        result.push(current);
+      }
+    }
+
+    return result;
+  }
+}