@blackcode_sa/metaestetics-api 1.15.14 → 1.15.17-staging.0

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

@@ -1,712 +1,850 @@
-import { Timestamp } from "firebase/firestore";
-import { DateTime } from "luxon";
-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,
-      tz,
-    } = 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,
-      tz
-    );
-
-    // 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,
-      tz
-    );
-
-    // 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,
-      tz
-    );
-
-    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
-   * @param tz - IANA timezone of the clinic
-   * @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 },
-    tz: string
-  ): 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(),
-      tz
-    );
-
-    // 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
-   * @param tz - IANA timezone of the clinic
-   * @returns Array of time intervals representing working hours
-   */
-  private static createWorkingHoursIntervals(
-    workingHours: any,
-    startDate: Date,
-    endDate: Date,
-    tz: string
-  ): TimeInterval[] {
-    const workingIntervals: TimeInterval[] = [];
-    // FIXED: Use fromMillis instead of fromJSDate to avoid timezone reinterpretation
-    let start = DateTime.fromMillis(startDate.getTime(), { zone: tz });
-    const end = DateTime.fromMillis(endDate.getTime(), { zone: tz });
-
-    while (start <= end) {
-      const dayOfWeek = start.weekday; // 1 for Monday, 7 for Sunday
-      const dayName = [
-        "monday",
-        "tuesday",
-        "wednesday",
-        "thursday",
-        "friday",
-        "saturday",
-        "sunday",
-      ][dayOfWeek - 1];
-
-      if (dayName && workingHours[dayName]) {
-        const daySchedule = workingHours[dayName];
-        if (daySchedule) {
-          const [openHours, openMinutes] = daySchedule.open
-            .split(":")
-            .map(Number);
-          const [closeHours, closeMinutes] = daySchedule.close
-            .split(":")
-            .map(Number);
-
-          let workStart = start.set({
-            hour: openHours,
-            minute: openMinutes,
-            second: 0,
-            millisecond: 0,
-          });
-          let workEnd = start.set({
-            hour: closeHours,
-            minute: closeMinutes,
-            second: 0,
-            millisecond: 0,
-          });
-
-          if (
-            workEnd.toMillis() > startDate.getTime() &&
-            workStart.toMillis() < endDate.getTime()
-          ) {
-            // FIXED: Use fromMillis instead of fromJSDate
-            const intervalStart =
-              workStart < DateTime.fromMillis(startDate.getTime(), { zone: tz })
-                ? DateTime.fromMillis(startDate.getTime(), { zone: tz })
-                : workStart;
-            const intervalEnd =
-              workEnd > DateTime.fromMillis(endDate.getTime(), { zone: tz })
-                ? DateTime.fromMillis(endDate.getTime(), { zone: tz })
-                : workEnd;
-
-            workingIntervals.push({
-              start: Timestamp.fromMillis(intervalStart.toMillis()),
-              end: Timestamp.fromMillis(intervalEnd.toMillis()),
-            });
-
-            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 = start.set({
-                  hour: breakStartHours,
-                  minute: breakStartMinutes,
-                });
-                const breakEnd = start.set({
-                  hour: breakEndHours,
-                  minute: breakEndMinutes,
-                });
-
-                workingIntervals.splice(
-                  -1,
-                  1,
-                  ...this.subtractInterval(
-                    workingIntervals[workingIntervals.length - 1],
-                    {
-                      start: Timestamp.fromMillis(breakStart.toMillis()),
-                      end: Timestamp.fromMillis(breakEnd.toMillis()),
-                    }
-                  )
-                );
-              }
-            }
-          }
-        }
-      }
-      start = start.plus({ days: 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
-   * @param tz - IANA timezone of the clinic
-   * @returns Intervals filtered by practitioner's working hours
-   */
-  private static applyPractitionerWorkingHours(
-    intervals: TimeInterval[],
-    practitioner: any,
-    clinicId: string,
-    timeframe: { start: Timestamp; end: Timestamp },
-    tz: string
-  ): 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(),
-      tz
-    );
-
-    // 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
-   * @param tz - IANA timezone of the clinic
-   * @returns Array of time intervals representing practitioner's working hours
-   */
-  private static createPractitionerWorkingHoursIntervals(
-    workingHours: any,
-    startDate: Date,
-    endDate: Date,
-    tz: string
-  ): TimeInterval[] {
-    const workingIntervals: TimeInterval[] = [];
-    // FIXED: Use fromMillis instead of fromJSDate to avoid timezone reinterpretation
-    let start = DateTime.fromMillis(startDate.getTime(), { zone: tz });
-    const end = DateTime.fromMillis(endDate.getTime(), { zone: tz });
-
-    while (start <= end) {
-      const dayOfWeek = start.weekday;
-      const dayName = [
-        "monday",
-        "tuesday",
-        "wednesday",
-        "thursday",
-        "friday",
-        "saturday",
-        "sunday",
-      ][dayOfWeek - 1];
-
-      if (dayName && workingHours[dayName]) {
-        const daySchedule = workingHours[dayName];
-        if (daySchedule) {
-          const [startHours, startMinutes] = daySchedule.start
-            .split(":")
-            .map(Number);
-          const [endHours, endMinutes] = daySchedule.end.split(":").map(Number);
-
-          const workStart = start.set({
-            hour: startHours,
-            minute: startMinutes,
-          });
-          const workEnd = start.set({ hour: endHours, minute: endMinutes });
-
-          if (
-            workEnd.toMillis() > startDate.getTime() &&
-            workStart.toMillis() < endDate.getTime()
-          ) {
-            // FIXED: Use fromMillis instead of fromJSDate
-            const intervalStart =
-              workStart < DateTime.fromMillis(startDate.getTime(), { zone: tz })
-                ? DateTime.fromMillis(startDate.getTime(), { zone: tz })
-                : workStart;
-            const intervalEnd =
-              workEnd > DateTime.fromMillis(endDate.getTime(), { zone: tz })
-                ? DateTime.fromMillis(endDate.getTime(), { zone: tz })
-                : workEnd;
-
-            workingIntervals.push({
-              start: Timestamp.fromMillis(intervalStart.toMillis()),
-              end: Timestamp.fromMillis(intervalEnd.toMillis()),
-            });
-          }
-        }
-      }
-      start = start.plus({ days: 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
-   * @param tz - IANA timezone of the clinic
-   * @returns Array of available booking slots
-   */
-  private static generateAvailableSlots(
-    intervals: TimeInterval[],
-    intervalMinutes: number,
-    durationMinutes: number,
-    tz: string
-  ): AvailableSlot[] {
-    const slots: AvailableSlot[] = [];
-    console.log(
-      `Generating slots with ${intervalMinutes}min intervals for ${durationMinutes}min procedure in timezone ${tz}`
-    );
-
-    // Get current time in clinic timezone
-    const nowInClinicTz = DateTime.now().setZone(tz);
-    // Add minimum booking window (15 minutes from now)
-    const MINIMUM_BOOKING_WINDOW_MINUTES = 15;
-    const earliestBookableTime = nowInClinicTz.plus({ minutes: MINIMUM_BOOKING_WINDOW_MINUTES });
-    
-    console.log(
-      `Current time in ${tz}: ${nowInClinicTz.toISO()}, earliest bookable: ${earliestBookableTime.toISO()}`
-    );
-
-    // 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 IN CLINIC TIMEZONE
-      let slotStart = DateTime.fromMillis(intervalStart.getTime(), { zone: tz });
-
-      // Adjust slotStart to the nearest interval boundary if needed
-      const minutesIntoDay = slotStart.hour * 60 + slotStart.minute;
-      const minutesRemainder = minutesIntoDay % intervalMinutes;
-
-      if (minutesRemainder > 0) {
-        slotStart = slotStart.plus({
-          minutes: intervalMinutes - minutesRemainder,
-        });
-      }
-
-      // Iterate through potential start times
-      while (slotStart.toMillis() + durationMs <= intervalEnd.getTime()) {
-        // Calculate potential end time
-        const slotEnd = slotStart.plus({ minutes: durationMinutes });
-
-        // ✅ CRITICAL FIX: Filter out past slots and slots too close to now
-        const isInFuture = slotStart >= earliestBookableTime;
-
-        // Check if this slot fits entirely within one of our available intervals AND is in the future
-        if (isInFuture && this.isSlotFullyAvailable(slotStart, slotEnd, intervals, tz)) {
-          slots.push({
-            start: Timestamp.fromMillis(slotStart.toMillis()),
-          });
-        }
-
-        // Move to the next potential start time
-        slotStart = slotStart.plus({ minutes: intervalMinutes });
-      }
-    }
-
-    console.log(`Generated ${slots.length} available slots (filtered for future times with ${MINIMUM_BOOKING_WINDOW_MINUTES}min minimum window)`);
-    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
-   * @param tz - IANA timezone of the clinic
-   * @returns True if the slot is fully contained within an available interval
-   */
-  private static isSlotFullyAvailable(
-    slotStart: DateTime,
-    slotEnd: DateTime,
-    intervals: TimeInterval[],
-    tz: string
-  ): boolean {
-    // Check if the slot is fully contained in any of the available intervals
-    return intervals.some((interval) => {
-      const intervalStart = DateTime.fromMillis(interval.start.toMillis(), { zone: tz });
-      const intervalEnd = DateTime.fromMillis(interval.end.toMillis(), { zone: tz });
-
-      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;
-  }
-}
+import { Timestamp } from "firebase/firestore";
+import { DateTime } from "luxon";
+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";
+import { ResourceCalendarEvent } from "../../types/resource";
+
+/**
+ * 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,
+      tz,
+    } = 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,
+      tz
+    );
+
+    // 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,
+      tz
+    );
+
+    // Step 4: Subtract practitioner's busy times
+    availableIntervals = this.subtractPractitionerBusyTimes(
+      availableIntervals,
+      practitionerCalendarEvents
+    );
+
+    // Step 5: Apply resource availability constraints (if procedure requires resources)
+    if (request.resourceCalendarEventsMap) {
+      availableIntervals = this.applyResourceAvailability(
+        availableIntervals,
+        request.resourceCalendarEventsMap,
+        timeframe
+      );
+    }
+
+    console.log(
+      `After all filters, have ${availableIntervals.length} available intervals`
+    );
+
+    // Step 6: Generate available slots based on scheduling interval and procedure duration
+    const availableSlots = this.generateAvailableSlots(
+      availableIntervals,
+      schedulingIntervalMinutes,
+      procedureDurationMinutes,
+      tz
+    );
+
+    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
+   * @param tz - IANA timezone of the clinic
+   * @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 },
+    tz: string
+  ): 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(),
+      tz
+    );
+
+    // 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
+   * @param tz - IANA timezone of the clinic
+   * @returns Array of time intervals representing working hours
+   */
+  private static createWorkingHoursIntervals(
+    workingHours: any,
+    startDate: Date,
+    endDate: Date,
+    tz: string
+  ): TimeInterval[] {
+    const workingIntervals: TimeInterval[] = [];
+    // FIXED: Use fromMillis instead of fromJSDate to avoid timezone reinterpretation
+    let start = DateTime.fromMillis(startDate.getTime(), { zone: tz });
+    const end = DateTime.fromMillis(endDate.getTime(), { zone: tz });
+
+    while (start <= end) {
+      const dayOfWeek = start.weekday; // 1 for Monday, 7 for Sunday
+      const dayName = [
+        "monday",
+        "tuesday",
+        "wednesday",
+        "thursday",
+        "friday",
+        "saturday",
+        "sunday",
+      ][dayOfWeek - 1];
+
+      if (dayName && workingHours[dayName]) {
+        const daySchedule = workingHours[dayName];
+        if (daySchedule) {
+          const [openHours, openMinutes] = daySchedule.open
+            .split(":")
+            .map(Number);
+          const [closeHours, closeMinutes] = daySchedule.close
+            .split(":")
+            .map(Number);
+
+          let workStart = start.set({
+            hour: openHours,
+            minute: openMinutes,
+            second: 0,
+            millisecond: 0,
+          });
+          let workEnd = start.set({
+            hour: closeHours,
+            minute: closeMinutes,
+            second: 0,
+            millisecond: 0,
+          });
+
+          if (
+            workEnd.toMillis() > startDate.getTime() &&
+            workStart.toMillis() < endDate.getTime()
+          ) {
+            // FIXED: Use fromMillis instead of fromJSDate
+            const intervalStart =
+              workStart < DateTime.fromMillis(startDate.getTime(), { zone: tz })
+                ? DateTime.fromMillis(startDate.getTime(), { zone: tz })
+                : workStart;
+            const intervalEnd =
+              workEnd > DateTime.fromMillis(endDate.getTime(), { zone: tz })
+                ? DateTime.fromMillis(endDate.getTime(), { zone: tz })
+                : workEnd;
+
+            workingIntervals.push({
+              start: Timestamp.fromMillis(intervalStart.toMillis()),
+              end: Timestamp.fromMillis(intervalEnd.toMillis()),
+            });
+
+            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 = start.set({
+                  hour: breakStartHours,
+                  minute: breakStartMinutes,
+                });
+                const breakEnd = start.set({
+                  hour: breakEndHours,
+                  minute: breakEndMinutes,
+                });
+
+                workingIntervals.splice(
+                  -1,
+                  1,
+                  ...this.subtractInterval(
+                    workingIntervals[workingIntervals.length - 1],
+                    {
+                      start: Timestamp.fromMillis(breakStart.toMillis()),
+                      end: Timestamp.fromMillis(breakEnd.toMillis()),
+                    }
+                  )
+                );
+              }
+            }
+          }
+        }
+      }
+      start = start.plus({ days: 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
+   * @param tz - IANA timezone of the clinic
+   * @returns Intervals filtered by practitioner's working hours
+   */
+  private static applyPractitionerWorkingHours(
+    intervals: TimeInterval[],
+    practitioner: any,
+    clinicId: string,
+    timeframe: { start: Timestamp; end: Timestamp },
+    tz: string
+  ): 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(),
+      tz
+    );
+
+    // 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
+   * @param tz - IANA timezone of the clinic
+   * @returns Array of time intervals representing practitioner's working hours
+   */
+  private static createPractitionerWorkingHoursIntervals(
+    workingHours: any,
+    startDate: Date,
+    endDate: Date,
+    tz: string
+  ): TimeInterval[] {
+    const workingIntervals: TimeInterval[] = [];
+    // FIXED: Use fromMillis instead of fromJSDate to avoid timezone reinterpretation
+    let start = DateTime.fromMillis(startDate.getTime(), { zone: tz });
+    const end = DateTime.fromMillis(endDate.getTime(), { zone: tz });
+
+    while (start <= end) {
+      const dayOfWeek = start.weekday;
+      const dayName = [
+        "monday",
+        "tuesday",
+        "wednesday",
+        "thursday",
+        "friday",
+        "saturday",
+        "sunday",
+      ][dayOfWeek - 1];
+
+      if (dayName && workingHours[dayName]) {
+        const daySchedule = workingHours[dayName];
+        if (daySchedule) {
+          const [startHours, startMinutes] = daySchedule.start
+            .split(":")
+            .map(Number);
+          const [endHours, endMinutes] = daySchedule.end.split(":").map(Number);
+
+          const workStart = start.set({
+            hour: startHours,
+            minute: startMinutes,
+          });
+          const workEnd = start.set({ hour: endHours, minute: endMinutes });
+
+          if (
+            workEnd.toMillis() > startDate.getTime() &&
+            workStart.toMillis() < endDate.getTime()
+          ) {
+            // FIXED: Use fromMillis instead of fromJSDate
+            const intervalStart =
+              workStart < DateTime.fromMillis(startDate.getTime(), { zone: tz })
+                ? DateTime.fromMillis(startDate.getTime(), { zone: tz })
+                : workStart;
+            const intervalEnd =
+              workEnd > DateTime.fromMillis(endDate.getTime(), { zone: tz })
+                ? DateTime.fromMillis(endDate.getTime(), { zone: tz })
+                : workEnd;
+
+            workingIntervals.push({
+              start: Timestamp.fromMillis(intervalStart.toMillis()),
+              end: Timestamp.fromMillis(intervalEnd.toMillis()),
+            });
+          }
+        }
+      }
+      start = start.plus({ days: 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
+   * @param tz - IANA timezone of the clinic
+   * @returns Array of available booking slots
+   */
+  private static generateAvailableSlots(
+    intervals: TimeInterval[],
+    intervalMinutes: number,
+    durationMinutes: number,
+    tz: string
+  ): AvailableSlot[] {
+    const slots: AvailableSlot[] = [];
+    console.log(
+      `Generating slots with ${intervalMinutes}min intervals for ${durationMinutes}min procedure in timezone ${tz}`
+    );
+
+    // Get current time in clinic timezone
+    const nowInClinicTz = DateTime.now().setZone(tz);
+    // Add minimum booking window (15 minutes from now)
+    const MINIMUM_BOOKING_WINDOW_MINUTES = 15;
+    const earliestBookableTime = nowInClinicTz.plus({ minutes: MINIMUM_BOOKING_WINDOW_MINUTES });
+    
+    console.log(
+      `Current time in ${tz}: ${nowInClinicTz.toISO()}, earliest bookable: ${earliestBookableTime.toISO()}`
+    );
+
+    // 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 IN CLINIC TIMEZONE
+      let slotStart = DateTime.fromMillis(intervalStart.getTime(), { zone: tz });
+
+      // Adjust slotStart to the nearest interval boundary if needed
+      const minutesIntoDay = slotStart.hour * 60 + slotStart.minute;
+      const minutesRemainder = minutesIntoDay % intervalMinutes;
+
+      if (minutesRemainder > 0) {
+        slotStart = slotStart.plus({
+          minutes: intervalMinutes - minutesRemainder,
+        });
+      }
+
+      // Iterate through potential start times
+      while (slotStart.toMillis() + durationMs <= intervalEnd.getTime()) {
+        // Calculate potential end time
+        const slotEnd = slotStart.plus({ minutes: durationMinutes });
+
+        // ✅ CRITICAL FIX: Filter out past slots and slots too close to now
+        const isInFuture = slotStart >= earliestBookableTime;
+
+        // Check if this slot fits entirely within one of our available intervals AND is in the future
+        if (isInFuture && this.isSlotFullyAvailable(slotStart, slotEnd, intervals, tz)) {
+          slots.push({
+            start: Timestamp.fromMillis(slotStart.toMillis()),
+          });
+        }
+
+        // Move to the next potential start time
+        slotStart = slotStart.plus({ minutes: intervalMinutes });
+      }
+    }
+
+    console.log(`Generated ${slots.length} available slots (filtered for future times with ${MINIMUM_BOOKING_WINDOW_MINUTES}min minimum window)`);
+    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
+   * @param tz - IANA timezone of the clinic
+   * @returns True if the slot is fully contained within an available interval
+   */
+  private static isSlotFullyAvailable(
+    slotStart: DateTime,
+    slotEnd: DateTime,
+    intervals: TimeInterval[],
+    tz: string
+  ): boolean {
+    // Check if the slot is fully contained in any of the available intervals
+    return intervals.some((interval) => {
+      const intervalStart = DateTime.fromMillis(interval.start.toMillis(), { zone: tz });
+      const intervalEnd = DateTime.fromMillis(interval.end.toMillis(), { zone: tz });
+
+      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;
+  }
+
+  /**
+   * Apply resource availability constraints to the available intervals.
+   * For each required resource:
+   *   - Compute each instance's availability (full timeframe minus its busy events)
+   *   - Union all instance availabilities (at least one must be free)
+   * Then intersect all resource availabilities with the current doctor availability.
+   *
+   * @param intervals - Current available intervals (doctor availability)
+   * @param resourceEventsMap - Map of resource data with per-instance calendar events
+   * @param timeframe - Overall timeframe being considered
+   * @returns Intervals where doctor AND all required resources are available
+   */
+  private static applyResourceAvailability(
+    intervals: TimeInterval[],
+    resourceEventsMap: Record<
+      string,
+      {
+        resourceId: string;
+        resourceName: string;
+        quantity: number;
+        instanceEvents: Record<string, ResourceCalendarEvent[]>;
+      }
+    >,
+    timeframe: { start: Timestamp; end: Timestamp }
+  ): TimeInterval[] {
+    if (!intervals.length) return [];
+
+    const resourceIds = Object.keys(resourceEventsMap);
+    if (resourceIds.length === 0) return intervals;
+
+    console.log(
+      `Applying resource availability for ${resourceIds.length} resource(s)`
+    );
+
+    let result = intervals;
+
+    // For each required resource, compute its combined availability and intersect
+    for (const resourceId of resourceIds) {
+      const resourceData = resourceEventsMap[resourceId];
+      const resourceAvailability = this.computeResourceAvailability(
+        resourceData.instanceEvents,
+        timeframe
+      );
+
+      console.log(
+        `Resource "${resourceData.resourceName}" (qty=${resourceData.quantity}): ${resourceAvailability.length} available intervals`
+      );
+
+      // Intersect doctor availability with this resource's availability
+      result = this.intersectIntervals(result, resourceAvailability);
+
+      if (result.length === 0) {
+        console.log(
+          `No availability remaining after applying resource "${resourceData.resourceName}"`
+        );
+        return [];
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Compute combined availability for a single resource across all its instances.
+   * For each instance, subtract its busy events from the full timeframe.
+   * Then union all instance availabilities — if at least one instance is free, the resource is available.
+   *
+   * @param instanceEvents - Calendar events keyed by instanceId
+   * @param timeframe - Overall timeframe
+   * @returns Combined availability intervals for the resource
+   */
+  private static computeResourceAvailability(
+    instanceEvents: Record<string, ResourceCalendarEvent[]>,
+    timeframe: { start: Timestamp; end: Timestamp }
+  ): TimeInterval[] {
+    const instanceIds = Object.keys(instanceEvents);
+    if (instanceIds.length === 0) {
+      // No instances means the full timeframe is available (no constraints)
+      return [{ start: timeframe.start, end: timeframe.end }];
+    }
+
+    // Collect availability intervals from all instances
+    const allInstanceAvailabilities: TimeInterval[] = [];
+
+    for (const instanceId of instanceIds) {
+      const events = instanceEvents[instanceId];
+      // Start with full timeframe
+      let instanceAvailability: TimeInterval[] = [
+        { start: timeframe.start, end: timeframe.end },
+      ];
+
+      // Subtract each busy event from this instance's availability
+      for (const event of events) {
+        // Blocking events always subtract from availability regardless of status.
+        // Booking events only subtract when actively held (pending or confirmed).
+        const isBlockingEvent =
+          (event as any).eventType === CalendarEventType.BLOCKING ||
+          (event as any).eventType === CalendarEventType.BREAK ||
+          (event as any).eventType === CalendarEventType.FREE_DAY;
+
+        const isActiveBooking =
+          event.status === CalendarEventStatus.PENDING ||
+          event.status === CalendarEventStatus.CONFIRMED;
+
+        if (isBlockingEvent || isActiveBooking) {
+          const busyInterval: TimeInterval = {
+            start: event.eventTime.start,
+            end: event.eventTime.end,
+          };
+
+          const newAvailability: TimeInterval[] = [];
+          for (const interval of instanceAvailability) {
+            newAvailability.push(
+              ...this.subtractInterval(interval, busyInterval)
+            );
+          }
+          instanceAvailability = newAvailability;
+        }
+      }
+
+      // Add this instance's available intervals to the combined pool
+      allInstanceAvailabilities.push(...instanceAvailability);
+    }
+
+    // Union (merge) all instance availabilities — at least one instance being free is sufficient
+    return this.mergeOverlappingIntervals(allInstanceAvailabilities);
+  }
+}