@blackcode_sa/metaestetics-api 1.15.16 → 1.15.17

package/package.json

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

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

@@ -7,14 +7,16 @@ This service is responsible for handling side effects and data aggregation tasks
 - Managing denormalized data links (e.g., patient-clinic, patient-practitioner).
 - Creating and updating `PatientRequirementInstance` documents based on appointment status and associated procedure requirements.
 - Orchestrating notifications (email and push) to patients, practitioners, and clinic admins at various stages of the appointment lifecycle.
-- Interfacing with other admin services like `AppointmentMailingService`, `NotificationsAdmin`, and `CalendarAdminService` (though calendar interactions are mostly TODOs).
+- Interfacing with other admin services like `AppointmentMailingService`, `NotificationsAdmin`, `CalendarAdminService`, and `ResourceCalendarAdminService`.
+- Managing resource calendar events for appointments that have booked clinic resources (see [Resource System](../../../../../docs/RESOURCE_SYSTEM.md)).
 
 ## Implemented Functionality
 
 ### Constructor
 
 - Initializes with a Firestore instance and a Mailgun client.
-- Sets up instances of dependent services: `AppointmentMailingService`, `NotificationsAdmin`, `CalendarAdminService`, and `PatientRequirementsAdminService`.
+- Sets up instances of dependent services: `AppointmentMailingService`, `NotificationsAdmin`, `CalendarAdminService`, `ResourceCalendarAdminService`, and `PatientRequirementsAdminService`.
+  - **`ResourceCalendarAdminService`**: Manages resource calendar events (status updates, time updates, deletion) for appointments that have `resourceBookings`. See [Resource System README](../../../../../docs/RESOURCE_SYSTEM.md).
   - **Note**: `PatientRequirementsAdminService` is initialized but its methods are not (and should not be) directly called by this aggregation service for creating/managing requirement instances. That logic is correctly handled by local private methods in this service.
 
 ### `handleAppointmentCreate(appointment: Appointment)`
@@ -75,6 +77,26 @@ This service is responsible for handling side effects and data aggregation tasks
 - **Data Fetching Helpers (`fetchPatientProfile`, `fetchPatientSensitiveInfo`, `fetchPractitionerProfile`, `fetchClinicInfo`)**:
   - Basic methods to retrieve documents from Firestore by ID.
 
+## Resource Calendar Event Handling
+
+When an appointment has `resourceBookings` (i.e., the procedure required clinic resources), the aggregation service also manages resource calendar events via `ResourceCalendarAdminService`:
+
+| Appointment Transition | Resource Calendar Action |
+|---|---|
+| `PENDING → CONFIRMED` | `resourceCalendarAdmin.updateResourceBookingEventsStatus(after, CONFIRMED)` |
+| `RESCHEDULED_BY_CLINIC → CONFIRMED` | `resourceCalendarAdmin.updateResourceBookingEventsStatus(after, CONFIRMED)` |
+| `Any → CANCELLED / NO_SHOW` | `resourceCalendarAdmin.updateResourceBookingEventsStatus(after, calendarStatus)` |
+| `Any → COMPLETED` | `resourceCalendarAdmin.updateResourceBookingEventsStatus(after, COMPLETED)` |
+| `Any → RESCHEDULED_BY_CLINIC` | `resourceCalendarAdmin.updateResourceBookingEventsTime(after, newTime)` + `updateResourceBookingEventsStatus(after, PENDING)` |
+| Time change (CONFIRMED, no status change) | `resourceCalendarAdmin.updateResourceBookingEventsTime(after, newTime)` |
+| Appointment deleted | `resourceCalendarAdmin.deleteResourceBookingEvents(deletedAppointment)` |
+
+All resource operations are guarded by checking `appointment.resourceBookings` existence, so backward-compatible appointments (without resources) are unaffected.
+
+For full details on the resource system, see [Resource System README](../../../../../docs/RESOURCE_SYSTEM.md).
+
+---
+
 ## Pending `TODO` Items & Areas for Future Work
 
 ### General / Cross-Cutting

package/src/admin/aggregation/appointment/appointment.aggregation.service.ts

@@ -33,6 +33,7 @@ import { RequirementSourceProcedure } from '../../../types/patient/patient-requi
 import { PatientRequirementsAdminService } from '../../requirements/patient-requirements.admin.service';
 import { NotificationsAdmin } from '../../notifications/notifications.admin';
 import { CalendarAdminService } from '../../calendar/calendar.admin.service';
+import { ResourceCalendarAdminService } from '../../calendar/resource-calendar.admin';
 import { AppointmentMailingService } from '../../mailing/appointment/appointment.mailing.service';
 import { Logger } from '../../logger';
 import { UserRole } from '../../../types';
@@ -77,6 +78,7 @@ export class AppointmentAggregationService {
   private appointmentMailingService: AppointmentMailingService;
   private notificationsAdmin: NotificationsAdmin;
   private calendarAdminService: CalendarAdminService;
+  private resourceCalendarAdminService: ResourceCalendarAdminService;
   private patientRequirementsAdminService: PatientRequirementsAdminService;
 
   /**
@@ -95,6 +97,7 @@ export class AppointmentAggregationService {
     );
     this.notificationsAdmin = new NotificationsAdmin(this.db);
     this.calendarAdminService = new CalendarAdminService(this.db);
+    this.resourceCalendarAdminService = new ResourceCalendarAdminService(this.db);
     this.patientRequirementsAdminService = new PatientRequirementsAdminService(this.db);
     Logger.info('[AppointmentAggregationService] Initialized.');
   }
@@ -271,6 +274,12 @@ export class AppointmentAggregationService {
             CalendarEventStatus.CONFIRMED,
           );
 
+          // Also confirm resource calendar events
+          await this.resourceCalendarAdminService.updateResourceBookingEventsStatus(
+            after,
+            CalendarEventStatus.CONFIRMED,
+          );
+
           // Send confirmation notifications
           if (patientSensitiveInfo?.email && patientProfile) {
             Logger.info(
@@ -334,6 +343,12 @@ export class AppointmentAggregationService {
             CalendarEventStatus.CONFIRMED,
           );
 
+          // Also confirm resource calendar events
+          await this.resourceCalendarAdminService.updateResourceBookingEventsStatus(
+            after,
+            CalendarEventStatus.CONFIRMED,
+          );
+
           // Send confirmation notifications (similar to PENDING -> CONFIRMED)
           if (patientSensitiveInfo?.email && patientProfile) {
             Logger.info(
@@ -416,6 +431,12 @@ export class AppointmentAggregationService {
             calendarStatus(after.status),
           );
 
+          // Also cancel resource calendar events
+          await this.resourceCalendarAdminService.updateResourceBookingEventsStatus(
+            after,
+            calendarStatus(after.status),
+          );
+
           // Send cancellation email to Patient
           if (patientSensitiveInfo?.email && patientProfile) {
             Logger.info(
@@ -472,6 +493,12 @@ export class AppointmentAggregationService {
             CalendarEventStatus.COMPLETED,
           );
 
+          // Also complete resource calendar events
+          await this.resourceCalendarAdminService.updateResourceBookingEventsStatus(
+            after,
+            CalendarEventStatus.COMPLETED,
+          );
+
           // Send review request email to patient
           if (patientSensitiveInfo?.email && patientProfile) {
             Logger.info(
@@ -508,6 +535,16 @@ export class AppointmentAggregationService {
             CalendarEventStatus.PENDING,
           );
 
+          // Also update resource calendar events with new time and PENDING status
+          await this.resourceCalendarAdminService.updateResourceBookingEventsTime(after, {
+            start: after.appointmentStartTime,
+            end: after.appointmentEndTime,
+          });
+          await this.resourceCalendarAdminService.updateResourceBookingEventsStatus(
+            after,
+            CalendarEventStatus.PENDING,
+          );
+
           // Send reschedule proposal email to patient
           if (patientSensitiveInfo?.email && patientProfile) {
             Logger.info(
@@ -563,6 +600,12 @@ export class AppointmentAggregationService {
             start: after.appointmentStartTime,
             end: after.appointmentEndTime,
           });
+
+          // Also update resource calendar event times
+          await this.resourceCalendarAdminService.updateResourceBookingEventsTime(after, {
+            start: after.appointmentStartTime,
+            end: after.appointmentEndTime,
+          });
         } else {
           Logger.warn(
             `[AggService] Independent time change detected for ${after.id} with status ${after.status}. Review implications for requirements and calendar.`,
@@ -629,6 +672,9 @@ export class AppointmentAggregationService {
     // Delete all associated calendar events
     await this.calendarAdminService.deleteAppointmentCalendarEvents(deletedAppointment);
 
+    // Also delete resource calendar events
+    await this.resourceCalendarAdminService.deleteResourceBookingEvents(deletedAppointment);
+
     // TODO: Send cancellation/deletion notifications if appropriate (though data is gone)
   }
 

package/src/admin/booking/README.md

@@ -117,9 +117,68 @@ async orchestrateAppointmentCreation(
 
 ---
 
+---
+
+## Resource System Integration
+
+### Resource Availability in `getAvailableBookingSlots`
+
+When a procedure has `resourceRequirements`, the method performs additional steps:
+
+1. **Resource Data Fetching**: For each resource requirement on the procedure:
+   - Fetches the resource document and validates it is `active`
+   - Fetches all active instances of the resource
+   - For each instance, fetches calendar events within the timeframe (with 30-day lookback)
+   - Converts admin timestamps to client-compatible format
+
+2. **Builds `resourceCalendarEventsMap`**: A map keyed by `resourceId`, containing:
+   ```typescript
+   {
+     resourceId: string;
+     resourceName: string;
+     quantity: number;
+     instanceEvents: Record<string, ResourceCalendarEvent[]>; // keyed by instanceId
+   }
+   ```
+
+3. **Passes to Calculator**: The map is included in the `BookingAvailabilityRequest` passed to `BookingAvailabilityCalculator.calculateSlots()`.
+
+### Resource Allocation in `orchestrateAppointmentCreation`
+
+After creating practitioner/patient/clinic calendar events, if the procedure has `resourceRequirements`:
+
+1. For each requirement, iterates active instances sorted by index
+2. For each instance, queries for overlapping events with active statuses (`PENDING`, `CONFIRMED`, `CHECKED_IN`, `IN_PROGRESS`)
+3. Picks the **first free instance** (no overlapping active events)
+4. Creates a `ResourceCalendarEvent` on the instance's calendar subcollection via the batch
+5. Collects `ResourceBookingInfo` entries and adds them to the appointment document
+6. If no free instance is found, returns `{ success: false, error: "Resource {name} not available..." }`
+
+### BookingAvailabilityCalculator (`booking.calculator.ts`)
+
+**Step 5 (new)**: After subtracting practitioner busy times:
+
+- For each resource in `resourceCalendarEventsMap`:
+  - Compute each instance's availability:
+    - Subtract **blocking events** (any event with `eventType` BLOCKING/BREAK/FREE_DAY) regardless of status
+    - Subtract **active booking events** (PENDING or CONFIRMED status) — events without `eventType` fall through to this check for backward compatibility
+  - **Union** all instance availabilities (at least one must be free)
+- **Intersect** all resource availabilities together
+- Intersect with doctor availability → final availability
+
+Key private methods:
+- `applyResourceAvailability()`: Applies resource constraints to available intervals
+- `computeResourceAvailability()`: Computes union of instance availabilities for a single resource
+- `unionIntervals()`: Merges overlapping intervals from multiple instances
+
+See [Resource System README](../../../../docs/RESOURCE_SYSTEM.md) for the full algorithm detail.
+
+---
+
 ### Dependencies
 
 - **`DocumentManagerAdminService`**: Used to handle the creation and management of `FilledDocument` instances associated with appointments.
+- **`ResourceService`**: Used to fetch resources, instances, and calendar events for availability calculations and allocation.
 - **Firebase Admin SDK**: For all Firestore interactions.
-- **Various Type Definitions**: From `../../types/` for `Appointment`, `CalendarEvent`, `Procedure`, `Clinic`, `Practitioner`, `Patient`, `DocumentTemplate`, `LinkedFormInfo`, etc.
-- **`BookingAvailabilityCalculator`**: For calculating available booking slots.
+- **Various Type Definitions**: From `../../types/` for `Appointment`, `CalendarEvent`, `Procedure`, `Clinic`, `Practitioner`, `Patient`, `DocumentTemplate`, `LinkedFormInfo`, `Resource`, `ResourceInstance`, `ResourceCalendarEvent`, `ResourceBookingInfo`, etc.
+- **`BookingAvailabilityCalculator`**: For calculating available booking slots (including resource constraints).

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

@@ -65,6 +65,16 @@ import { DocumentManagerAdminService } from "../documentation-templates/document
 import { LinkedFormInfo } from "../../types/appointment";
 import { TimestampUtils } from "../../utils/TimestampUtils";
 import { Logger } from "../logger";
+import {
+  Resource,
+  ResourceInstance,
+  ResourceCalendarEvent,
+  ResourceBookingInfo,
+  ResourceStatus,
+  RESOURCES_COLLECTION,
+  RESOURCE_INSTANCES_SUBCOLLECTION,
+  RESOURCE_CALENDAR_SUBCOLLECTION,
+} from "../../types/resource";
 
 /**
  * Interface for the data required by orchestrateAppointmentCreation
@@ -214,6 +224,125 @@ export class BookingAdmin {
         count: practitionerCalendarEvents.length,
       });
 
+      // 6. Fetch resource calendar events (if procedure requires resources)
+      let resourceCalendarEventsMap:
+        | BookingAvailabilityRequest["resourceCalendarEventsMap"]
+        | undefined;
+      if (
+        procedure.resourceRequirements &&
+        procedure.resourceRequirements.length > 0
+      ) {
+        Logger.debug(
+          "[BookingAdmin] Procedure has resource requirements, fetching resource data",
+          {
+            resourceRequirementCount: procedure.resourceRequirements.length,
+            resourceIds: procedure.resourceRequirements.map(
+              (r) => r.resourceId
+            ),
+          }
+        );
+
+        resourceCalendarEventsMap = {};
+
+        for (const requirement of procedure.resourceRequirements) {
+          // Fetch resource document
+          const resourceDoc = await this.db
+            .collection(CLINICS_COLLECTION)
+            .doc(clinicId)
+            .collection(RESOURCES_COLLECTION)
+            .doc(requirement.resourceId)
+            .get();
+
+          if (!resourceDoc.exists) {
+            Logger.warn(
+              "[BookingAdmin] Required resource not found, skipping",
+              {
+                resourceId: requirement.resourceId,
+                resourceName: requirement.resourceName,
+              }
+            );
+            continue;
+          }
+
+          const resource = resourceDoc.data() as Resource;
+          if (resource.status !== ResourceStatus.ACTIVE) {
+            Logger.warn(
+              "[BookingAdmin] Required resource is not active, skipping",
+              {
+                resourceId: requirement.resourceId,
+                resourceStatus: resource.status,
+              }
+            );
+            continue;
+          }
+
+          // Fetch all active instances
+          const instancesSnapshot = await this.db
+            .collection(CLINICS_COLLECTION)
+            .doc(clinicId)
+            .collection(RESOURCES_COLLECTION)
+            .doc(requirement.resourceId)
+            .collection(RESOURCE_INSTANCES_SUBCOLLECTION)
+            .where("status", "==", ResourceStatus.ACTIVE)
+            .get();
+
+          const instanceEvents: Record<string, ResourceCalendarEvent[]> = {};
+
+          for (const instanceDoc of instancesSnapshot.docs) {
+            const instanceId = instanceDoc.id;
+
+            // Fetch calendar events for this instance in the timeframe
+            const MAX_EVENT_DURATION_MS = 30 * 24 * 60 * 60 * 1000;
+            const queryStart = admin.firestore.Timestamp.fromMillis(
+              start.toMillis() - MAX_EVENT_DURATION_MS
+            );
+
+            const eventsSnapshot = await this.db
+              .collection(CLINICS_COLLECTION)
+              .doc(clinicId)
+              .collection(RESOURCES_COLLECTION)
+              .doc(requirement.resourceId)
+              .collection(RESOURCE_INSTANCES_SUBCOLLECTION)
+              .doc(instanceId)
+              .collection(RESOURCE_CALENDAR_SUBCOLLECTION)
+              .where("eventTime.start", ">=", queryStart)
+              .where("eventTime.start", "<=", end)
+              .orderBy("eventTime.start")
+              .get();
+
+            // Post-filter for overlapping events and convert timestamps
+            const events = eventsSnapshot.docs
+              .map((doc) => ({ ...doc.data(), id: doc.id } as any))
+              .filter(
+                (event: any) =>
+                  event.eventTime.end.toMillis() > start.toMillis()
+              );
+
+            // Convert admin timestamps to client timestamps
+            instanceEvents[instanceId] = this.convertEventsTimestamps(
+              events
+            ) as unknown as ResourceCalendarEvent[];
+          }
+
+          resourceCalendarEventsMap[requirement.resourceId] = {
+            resourceId: requirement.resourceId,
+            resourceName: requirement.resourceName,
+            quantity: resource.quantity,
+            instanceEvents,
+          };
+
+          Logger.debug("[BookingAdmin] Fetched resource calendar data", {
+            resourceId: requirement.resourceId,
+            resourceName: requirement.resourceName,
+            instanceCount: instancesSnapshot.size,
+            totalEvents: Object.values(instanceEvents).reduce(
+              (sum, events) => sum + events.length,
+              0
+            ),
+          });
+        }
+      }
+
       // Since we're working with two different Timestamp implementations (admin vs client),
       // we need to convert our timestamps to the client-side format expected by the calculator
       // Create client Timestamp objects from admin Timestamp objects
@@ -234,6 +363,7 @@ export class BookingAdmin {
           practitionerCalendarEvents
         ),
         tz: clinic.location.tz || "UTC",
+        ...(resourceCalendarEventsMap && { resourceCalendarEventsMap }),
       };
 
       Logger.info("[BookingAdmin] Calling availability calculator", {
@@ -243,6 +373,9 @@ export class BookingAdmin {
         ),
         clinicEventsCount: clinicCalendarEvents.length,
         practitionerEventsCount: practitionerCalendarEvents.length,
+        resourceRequirementCount:
+          procedure.resourceRequirements?.length || 0,
+        hasResourceData: !!resourceCalendarEventsMap,
       });
 
       // Use the calculator to compute available slots
@@ -850,6 +983,129 @@ export class BookingAdmin {
         clinicCalendarEventData
       );
 
+      // --- Resource Allocation (if procedure requires resources) ---
+      let resourceBookings: ResourceBookingInfo[] = [];
+      if (
+        procedure.resourceRequirements &&
+        procedure.resourceRequirements.length > 0
+      ) {
+        console.log(
+          `[BookingAdmin] Allocating resources for appointment ${newAppointmentId}, ` +
+            `${procedure.resourceRequirements.length} resource(s) required`
+        );
+
+        for (const requirement of procedure.resourceRequirements) {
+          // Fetch all active instances of this resource, sorted by index
+          const instancesSnapshot = await this.db
+            .collection(CLINICS_COLLECTION)
+            .doc(clinicData.id)
+            .collection(RESOURCES_COLLECTION)
+            .doc(requirement.resourceId)
+            .collection(RESOURCE_INSTANCES_SUBCOLLECTION)
+            .where("status", "==", ResourceStatus.ACTIVE)
+            .orderBy("index")
+            .get();
+
+          if (instancesSnapshot.empty) {
+            return {
+              success: false,
+              error: `Resource "${requirement.resourceName}" has no active instances available.`,
+            };
+          }
+
+          let allocatedInstance: ResourceInstance | null = null;
+
+          for (const instanceDoc of instancesSnapshot.docs) {
+            const instance = {
+              ...instanceDoc.data(),
+              id: instanceDoc.id,
+            } as ResourceInstance;
+
+            // Check if this instance has overlapping active events during appointment time
+            const overlappingEventsSnapshot = await this.db
+              .collection(CLINICS_COLLECTION)
+              .doc(clinicData.id)
+              .collection(RESOURCES_COLLECTION)
+              .doc(requirement.resourceId)
+              .collection(RESOURCE_INSTANCES_SUBCOLLECTION)
+              .doc(instance.id)
+              .collection(RESOURCE_CALENDAR_SUBCOLLECTION)
+              .where("eventTime.start", "<", data.appointmentEndTime)
+              .where("status", "in", [
+                CalendarEventStatus.PENDING,
+                CalendarEventStatus.CONFIRMED,
+                CalendarEventStatus.CHECKED_IN,
+                CalendarEventStatus.IN_PROGRESS,
+              ])
+              .get();
+
+            // Post-filter: event must end after appointment start to truly overlap
+            const hasOverlap = overlappingEventsSnapshot.docs.some((doc) => {
+              const event = doc.data();
+              return (
+                event.eventTime.end.toMillis() >
+                data.appointmentStartTime.toMillis()
+              );
+            });
+
+            if (!hasOverlap) {
+              allocatedInstance = instance;
+              break;
+            }
+          }
+
+          if (!allocatedInstance) {
+            return {
+              success: false,
+              error: `Resource "${requirement.resourceName}" is not available at the selected time. All instances are booked.`,
+            };
+          }
+
+          // Create ResourceCalendarEvent on the allocated instance's calendar
+          const resourceCalendarEventRef = this.db
+            .collection(CLINICS_COLLECTION)
+            .doc(clinicData.id)
+            .collection(RESOURCES_COLLECTION)
+            .doc(requirement.resourceId)
+            .collection(RESOURCE_INSTANCES_SUBCOLLECTION)
+            .doc(allocatedInstance.id)
+            .collection(RESOURCE_CALENDAR_SUBCOLLECTION)
+            .doc();
+
+          const resourceCalendarEventData = {
+            id: resourceCalendarEventRef.id,
+            resourceId: requirement.resourceId,
+            resourceInstanceId: allocatedInstance.id,
+            clinicBranchId: clinicData.id,
+            eventType: CalendarEventType.RESOURCE_BOOKING,
+            appointmentId: newAppointmentId,
+            procedureId: procedure.id,
+            practitionerId: practitionerData.id,
+            patientId: data.patientId,
+            eventTime: eventTimeForCalendarEvents,
+            status: initialCalendarEventStatus,
+            eventName: `${procedure.name} - ${allocatedInstance.label}`,
+            createdAt: serverTimestampValue,
+            updatedAt: serverTimestampValue,
+          };
+
+          batch.set(resourceCalendarEventRef, resourceCalendarEventData);
+
+          resourceBookings.push({
+            resourceId: requirement.resourceId,
+            resourceName: requirement.resourceName,
+            resourceInstanceId: allocatedInstance.id,
+            resourceInstanceLabel: allocatedInstance.label,
+            calendarEventId: resourceCalendarEventRef.id,
+          });
+
+          console.log(
+            `[BookingAdmin] Allocated resource "${requirement.resourceName}" → ` +
+              `instance "${allocatedInstance.label}" (${allocatedInstance.id})`
+          );
+        }
+      }
+
       // --- Initialize Pending/Draft Filled Documents and get form IDs ---
       let initializedFormsInfo: LinkedFormInfo[] = [];
       let pendingUserFormTemplateIds: string[] = [];
@@ -948,6 +1204,7 @@ export class BookingAdmin {
         isRecurring: false,
         recurringAppointmentId: null,
         isArchived: false,
+        ...(resourceBookings.length > 0 && { resourceBookings }),
         createdAt: adminTsNow as any,
         updatedAt: adminTsNow as any,
       };