@blackcode_sa/metaestetics-api 1.15.16 → 1.15.17-staging.1

package/src/services/resource/README.md

@@ -0,0 +1,119 @@
+# Resource Service (`Api/src/services/resource/`)
+
+Server-side service for managing clinic resources and their instances. Extends `BaseService` and provides full CRUD operations backed by Firestore.
+
+## File: `resource.service.ts`
+
+### Class: `ResourceService extends BaseService`
+
+#### Constructor
+
+```typescript
+constructor(db: Firestore, auth: Auth, app: FirebaseApp)
+```
+
+Inherits Firestore, Auth, and Firebase App from `BaseService`.
+
+---
+
+### Methods
+
+#### `createResource(data: CreateResourceData): Promise<Resource>`
+
+Creates a new resource and auto-generates instances.
+
+- Validates input with `createResourceSchema` (Zod)
+- Creates the `Resource` document under `clinics/{clinicBranchId}/resources/{id}`
+- Batch-creates `N` `ResourceInstance` subdocuments (where N = `data.quantity`)
+- Each instance gets label `"{name} #{index}"` (1-based)
+- Returns the created `Resource`
+
+#### `getResource(clinicBranchId: string, resourceId: string): Promise<Resource | null>`
+
+Fetches a single resource by ID.
+
+#### `getResourcesByClinic(clinicBranchId: string): Promise<Resource[]>`
+
+Fetches all resources for a clinic branch.
+
+#### `getActiveResourcesByClinic(clinicBranchId: string): Promise<Resource[]>`
+
+Fetches only active resources (`status === 'active'`) for a clinic branch.
+
+#### `updateResource(clinicBranchId: string, resourceId: string, data: UpdateResourceData): Promise<Resource>`
+
+Updates a resource. Handles quantity changes:
+
+- **Quantity increase**: Creates new instances starting from `currentQuantity + 1`
+- **Quantity decrease**: Checks if affected instances (from the end) have future bookings. If any do, the operation is **rejected** with an error. Otherwise, instances are deactivated (status set to `inactive`).
+
+#### `deleteResource(clinicBranchId: string, resourceId: string): Promise<void>`
+
+Soft-deletes a resource by setting `status: 'inactive'`. Does not remove documents from Firestore.
+
+#### `getResourceInstances(clinicBranchId: string, resourceId: string): Promise<ResourceInstance[]>`
+
+Fetches all instances for a resource, ordered by `index`.
+
+#### `getActiveResourceInstances(clinicBranchId: string, resourceId: string): Promise<ResourceInstance[]>`
+
+Fetches only active instances (`status === 'active'`), ordered by `index`.
+
+#### `getResourceCalendarEvents(clinicBranchId, resourceId, instanceId, start, end): Promise<ResourceCalendarEvent[]>`
+
+Fetches calendar events for a specific instance within a time range. Used by the booking engine to check instance availability.
+
+#### `instanceHasFutureBookings(clinicBranchId, resourceId, instanceId): Promise<boolean>`
+
+Checks if an instance has any future booking events. Used when decreasing resource quantity to prevent deactivating instances with active bookings.
+
+---
+
+### Blocking Event Methods
+
+CRUD operations for managing blocking events on resource instance calendars. Blocking events mark an instance as unavailable for a time period (maintenance, out of order, etc.).
+
+#### `createResourceBlockingEvent(params: CreateResourceBlockingEventParams): Promise<ResourceCalendarEvent>`
+
+Creates a blocking event on an instance's calendar.
+
+- Validates input with `createResourceBlockingEventSchema` (Zod)
+- Creates document at `clinics/{clinicBranchId}/resources/{resourceId}/instances/{instanceId}/calendar/{eventId}`
+- Sets `eventType: BLOCKING`, `status: CONFIRMED`
+- Appointment-specific fields are omitted
+
+#### `updateResourceBlockingEvent(params: UpdateResourceBlockingEventParams): Promise<ResourceCalendarEvent>`
+
+Updates an existing blocking event. Only provided fields are modified.
+
+- Validates input with `updateResourceBlockingEventSchema`
+- Verifies event exists before updating
+- Returns the updated event
+
+#### `deleteResourceBlockingEvent(clinicBranchId, resourceId, instanceId, eventId): Promise<void>`
+
+Hard deletes a blocking event from the instance's calendar.
+
+- Verifies event exists before deleting
+
+#### `getResourceInstanceBlockingEvents(clinicBranchId, resourceId, instanceId): Promise<ResourceCalendarEvent[]>`
+
+Fetches all blocking events for a specific instance, ordered by start time. Filters by `eventType == "blocking"`.
+
+---
+
+### Firestore Paths
+
+| Entity | Path |
+|--------|------|
+| Resource | `clinics/{clinicBranchId}/resources/{resourceId}` |
+| Instance | `clinics/{clinicBranchId}/resources/{resourceId}/instances/{instanceId}` |
+| Calendar Event | `clinics/{clinicBranchId}/resources/{resourceId}/instances/{instanceId}/calendar/{eventId}` |
+
+---
+
+### Export
+
+`index.ts` re-exports `ResourceService` from `resource.service.ts`. The service is also exported via `Api/src/services/index.ts`.
+
+See [main Resource System README](../../../../docs/RESOURCE_SYSTEM.md) for the full system overview.

package/src/services/resource/index.ts

@@ -0,0 +1 @@
+export * from "./resource.service";

package/src/services/resource/resource.service.ts

@@ -0,0 +1,555 @@
+import {
+  collection,
+  doc,
+  getDoc,
+  getDocs,
+  setDoc,
+  deleteDoc,
+  query,
+  where,
+  orderBy,
+  writeBatch,
+  updateDoc,
+  serverTimestamp,
+  Timestamp,
+} from "firebase/firestore";
+import { BaseService } from "../base.service";
+import {
+  Resource,
+  ResourceInstance,
+  ResourceCalendarEvent,
+  ResourceStatus,
+  CreateResourceData,
+  UpdateResourceData,
+  CreateResourceBlockingEventParams,
+  UpdateResourceBlockingEventParams,
+  RESOURCES_COLLECTION,
+  RESOURCE_INSTANCES_SUBCOLLECTION,
+  RESOURCE_CALENDAR_SUBCOLLECTION,
+} from "../../types/resource";
+import { CalendarEventType, CalendarEventStatus } from "../../types/calendar";
+import {
+  createResourceBlockingEventSchema,
+  updateResourceBlockingEventSchema,
+} from "../../validations/resource.schema";
+
+/**
+ * Service for managing clinic resources and their instances.
+ * Resources are stored as subcollections under clinics:
+ *   clinics/{clinicId}/resources/{resourceId}
+ *   clinics/{clinicId}/resources/{resourceId}/instances/{instanceId}
+ *   clinics/{clinicId}/resources/{resourceId}/instances/{instanceId}/calendar/{eventId}
+ */
+export class ResourceService extends BaseService {
+  /**
+   * Gets reference to a clinic's resources collection
+   */
+  private getResourcesRef(clinicBranchId: string) {
+    return collection(this.db, "clinics", clinicBranchId, RESOURCES_COLLECTION);
+  }
+
+  /**
+   * Gets reference to a specific resource document
+   */
+  private getResourceDocRef(clinicBranchId: string, resourceId: string) {
+    return doc(
+      this.db,
+      "clinics",
+      clinicBranchId,
+      RESOURCES_COLLECTION,
+      resourceId
+    );
+  }
+
+  /**
+   * Gets reference to a resource's instances subcollection
+   */
+  private getInstancesRef(clinicBranchId: string, resourceId: string) {
+    return collection(
+      this.db,
+      "clinics",
+      clinicBranchId,
+      RESOURCES_COLLECTION,
+      resourceId,
+      RESOURCE_INSTANCES_SUBCOLLECTION
+    );
+  }
+
+  /**
+   * Gets reference to an instance's calendar subcollection
+   */
+  private getInstanceCalendarRef(
+    clinicBranchId: string,
+    resourceId: string,
+    instanceId: string
+  ) {
+    return collection(
+      this.db,
+      "clinics",
+      clinicBranchId,
+      RESOURCES_COLLECTION,
+      resourceId,
+      RESOURCE_INSTANCES_SUBCOLLECTION,
+      instanceId,
+      RESOURCE_CALENDAR_SUBCOLLECTION
+    );
+  }
+
+  /**
+   * Creates a new resource with its instances.
+   * Creates the resource document and N instance subdocuments in a single batch.
+   */
+  async createResource(data: CreateResourceData): Promise<Resource> {
+    const batch = writeBatch(this.db);
+
+    const resourceRef = doc(this.getResourcesRef(data.clinicBranchId));
+    const resourceId = resourceRef.id;
+
+    const now = serverTimestamp();
+
+    const resourceData: Omit<Resource, "createdAt" | "updatedAt"> & {
+      createdAt: any;
+      updatedAt: any;
+    } = {
+      id: resourceId,
+      clinicBranchId: data.clinicBranchId,
+      name: data.name,
+      nameLower: data.name.toLowerCase(),
+      category: data.category,
+      description: data.description || undefined,
+      quantity: data.quantity,
+      status: ResourceStatus.ACTIVE,
+      linkedProcedureIds: [],
+      createdAt: now,
+      updatedAt: now,
+    };
+
+    batch.set(resourceRef, resourceData);
+
+    // Create instance subdocuments
+    for (let i = 1; i <= data.quantity; i++) {
+      const instanceRef = doc(
+        this.getInstancesRef(data.clinicBranchId, resourceId)
+      );
+      const instanceData: Omit<ResourceInstance, "createdAt" | "updatedAt"> & {
+        createdAt: any;
+        updatedAt: any;
+      } = {
+        id: instanceRef.id,
+        resourceId,
+        clinicBranchId: data.clinicBranchId,
+        label: `${data.name} #${i}`,
+        index: i,
+        status: ResourceStatus.ACTIVE,
+        createdAt: now,
+        updatedAt: now,
+      };
+      batch.set(instanceRef, instanceData);
+    }
+
+    await batch.commit();
+
+    // Fetch and return the created resource
+    const created = await this.getResource(data.clinicBranchId, resourceId);
+    if (!created) throw new Error("Failed to read created resource");
+    return created;
+  }
+
+  /**
+   * Gets a single resource by ID
+   */
+  async getResource(
+    clinicBranchId: string,
+    resourceId: string
+  ): Promise<Resource | null> {
+    const docRef = this.getResourceDocRef(clinicBranchId, resourceId);
+    const docSnap = await getDoc(docRef);
+    if (!docSnap.exists()) return null;
+    return { id: docSnap.id, ...docSnap.data() } as Resource;
+  }
+
+  /**
+   * Gets all resources for a clinic branch
+   */
+  async getResourcesByClinic(clinicBranchId: string): Promise<Resource[]> {
+    const q = query(
+      this.getResourcesRef(clinicBranchId),
+      orderBy("nameLower")
+    );
+    const snapshot = await getDocs(q);
+    return snapshot.docs.map(
+      (d) => ({ id: d.id, ...d.data() } as Resource)
+    );
+  }
+
+  /**
+   * Gets all active resources for a clinic branch
+   */
+  async getActiveResourcesByClinic(
+    clinicBranchId: string
+  ): Promise<Resource[]> {
+    const q = query(
+      this.getResourcesRef(clinicBranchId),
+      where("status", "==", ResourceStatus.ACTIVE),
+      orderBy("nameLower")
+    );
+    const snapshot = await getDocs(q);
+    return snapshot.docs.map(
+      (d) => ({ id: d.id, ...d.data() } as Resource)
+    );
+  }
+
+  /**
+   * Updates a resource. Handles quantity changes:
+   * - Increasing quantity: creates new instances
+   * - Decreasing quantity: blocked if affected instances have future bookings
+   */
+  async updateResource(
+    clinicBranchId: string,
+    resourceId: string,
+    data: UpdateResourceData
+  ): Promise<Resource> {
+    const existing = await this.getResource(clinicBranchId, resourceId);
+    if (!existing) throw new Error(`Resource ${resourceId} not found`);
+
+    const updateData: Record<string, any> = {
+      updatedAt: serverTimestamp(),
+    };
+
+    if (data.name !== undefined) {
+      updateData.name = data.name;
+      updateData.nameLower = data.name.toLowerCase();
+    }
+    if (data.category !== undefined) updateData.category = data.category;
+    if (data.description !== undefined)
+      updateData.description = data.description;
+    if (data.status !== undefined) updateData.status = data.status;
+
+    // Handle quantity change
+    if (data.quantity !== undefined && data.quantity !== existing.quantity) {
+      if (data.quantity > existing.quantity) {
+        // Add new instances
+        const batch = writeBatch(this.db);
+        const now = serverTimestamp();
+        const resourceName = data.name || existing.name;
+
+        for (let i = existing.quantity + 1; i <= data.quantity; i++) {
+          const instanceRef = doc(
+            this.getInstancesRef(clinicBranchId, resourceId)
+          );
+          const instanceData: Omit<
+            ResourceInstance,
+            "createdAt" | "updatedAt"
+          > & { createdAt: any; updatedAt: any } = {
+            id: instanceRef.id,
+            resourceId,
+            clinicBranchId,
+            label: `${resourceName} #${i}`,
+            index: i,
+            status: ResourceStatus.ACTIVE,
+            createdAt: now,
+            updatedAt: now,
+          };
+          batch.set(instanceRef, instanceData);
+        }
+
+        updateData.quantity = data.quantity;
+
+        // Update resource doc in the batch too
+        const resourceDocRef = this.getResourceDocRef(
+          clinicBranchId,
+          resourceId
+        );
+        batch.update(resourceDocRef, updateData);
+        await batch.commit();
+
+        const updated = await this.getResource(clinicBranchId, resourceId);
+        if (!updated) throw new Error("Failed to read updated resource");
+        return updated;
+      } else {
+        // Decreasing quantity - check for future bookings on affected instances
+        const instances = await this.getResourceInstances(
+          clinicBranchId,
+          resourceId
+        );
+        const instancesToRemove = instances
+          .filter((inst) => inst.index > data.quantity!)
+          .filter((inst) => inst.status === ResourceStatus.ACTIVE);
+
+        for (const instance of instancesToRemove) {
+          const hasFutureBookings = await this.instanceHasFutureBookings(
+            clinicBranchId,
+            resourceId,
+            instance.id
+          );
+          if (hasFutureBookings) {
+            throw new Error(
+              `Cannot reduce quantity: instance "${instance.label}" has future bookings. Cancel those bookings first.`
+            );
+          }
+        }
+
+        // Safe to deactivate instances
+        const batch = writeBatch(this.db);
+        for (const instance of instancesToRemove) {
+          const instanceRef = doc(
+            this.getInstancesRef(clinicBranchId, resourceId),
+            instance.id
+          );
+          batch.update(instanceRef, {
+            status: ResourceStatus.INACTIVE,
+            updatedAt: serverTimestamp(),
+          });
+        }
+
+        updateData.quantity = data.quantity;
+        const resourceDocRef = this.getResourceDocRef(
+          clinicBranchId,
+          resourceId
+        );
+        batch.update(resourceDocRef, updateData);
+        await batch.commit();
+
+        const updated = await this.getResource(clinicBranchId, resourceId);
+        if (!updated) throw new Error("Failed to read updated resource");
+        return updated;
+      }
+    }
+
+    // Simple update (no quantity change)
+    const resourceDocRef = this.getResourceDocRef(clinicBranchId, resourceId);
+    await updateDoc(resourceDocRef, updateData);
+
+    const updated = await this.getResource(clinicBranchId, resourceId);
+    if (!updated) throw new Error("Failed to read updated resource");
+    return updated;
+  }
+
+  /**
+   * Soft deletes a resource by setting status to INACTIVE
+   */
+  async deleteResource(
+    clinicBranchId: string,
+    resourceId: string
+  ): Promise<void> {
+    await this.updateResource(clinicBranchId, resourceId, {
+      status: ResourceStatus.INACTIVE,
+    });
+  }
+
+  /**
+   * Gets all instances for a resource
+   */
+  async getResourceInstances(
+    clinicBranchId: string,
+    resourceId: string
+  ): Promise<ResourceInstance[]> {
+    const q = query(
+      this.getInstancesRef(clinicBranchId, resourceId),
+      orderBy("index")
+    );
+    const snapshot = await getDocs(q);
+    return snapshot.docs.map(
+      (d) => ({ id: d.id, ...d.data() } as ResourceInstance)
+    );
+  }
+
+  /**
+   * Gets active instances for a resource
+   */
+  async getActiveResourceInstances(
+    clinicBranchId: string,
+    resourceId: string
+  ): Promise<ResourceInstance[]> {
+    const q = query(
+      this.getInstancesRef(clinicBranchId, resourceId),
+      where("status", "==", ResourceStatus.ACTIVE),
+      orderBy("index")
+    );
+    const snapshot = await getDocs(q);
+    return snapshot.docs.map(
+      (d) => ({ id: d.id, ...d.data() } as ResourceInstance)
+    );
+  }
+
+  /**
+   * Gets calendar events for a specific resource instance within a time range
+   */
+  async getResourceCalendarEvents(
+    clinicBranchId: string,
+    resourceId: string,
+    instanceId: string,
+    start: Timestamp,
+    end: Timestamp
+  ): Promise<ResourceCalendarEvent[]> {
+    const calendarRef = this.getInstanceCalendarRef(
+      clinicBranchId,
+      resourceId,
+      instanceId
+    );
+    const q = query(
+      calendarRef,
+      where("eventTime.start", ">=", start),
+      where("eventTime.start", "<=", end),
+      orderBy("eventTime.start")
+    );
+    const snapshot = await getDocs(q);
+    return snapshot.docs.map(
+      (d) => ({ id: d.id, ...d.data() } as ResourceCalendarEvent)
+    );
+  }
+
+  /**
+   * Checks if a resource instance has any future active bookings
+   */
+  private async instanceHasFutureBookings(
+    clinicBranchId: string,
+    resourceId: string,
+    instanceId: string
+  ): Promise<boolean> {
+    const now = Timestamp.now();
+    const calendarRef = this.getInstanceCalendarRef(
+      clinicBranchId,
+      resourceId,
+      instanceId
+    );
+    const q = query(
+      calendarRef,
+      where("eventTime.start", ">=", now),
+      where("status", "in", ["pending", "confirmed"])
+    );
+    const snapshot = await getDocs(q);
+    return !snapshot.empty;
+  }
+
+  // --- Resource Instance Blocking Events ---
+
+  /**
+   * Creates a blocking event on a resource instance's calendar.
+   * Blocking events prevent the instance from being booked during the specified time.
+   */
+  async createResourceBlockingEvent(
+    params: CreateResourceBlockingEventParams
+  ): Promise<ResourceCalendarEvent> {
+    createResourceBlockingEventSchema.parse(params);
+
+    const calendarRef = this.getInstanceCalendarRef(
+      params.clinicBranchId,
+      params.resourceId,
+      params.resourceInstanceId
+    );
+    const eventRef = doc(calendarRef);
+    const now = serverTimestamp();
+
+    const eventData = {
+      id: eventRef.id,
+      resourceId: params.resourceId,
+      resourceInstanceId: params.resourceInstanceId,
+      clinicBranchId: params.clinicBranchId,
+      eventType: CalendarEventType.BLOCKING,
+      eventName: params.eventName,
+      eventTime: params.eventTime,
+      status: CalendarEventStatus.CONFIRMED,
+      description: params.description || "",
+      createdAt: now,
+      updatedAt: now,
+    };
+
+    await setDoc(eventRef, eventData);
+
+    return {
+      ...eventData,
+      createdAt: Timestamp.now(),
+      updatedAt: Timestamp.now(),
+    } as ResourceCalendarEvent;
+  }
+
+  /**
+   * Updates an existing blocking event on a resource instance's calendar.
+   * Only provided fields are updated.
+   */
+  async updateResourceBlockingEvent(
+    params: UpdateResourceBlockingEventParams
+  ): Promise<ResourceCalendarEvent> {
+    updateResourceBlockingEventSchema.parse(params);
+
+    const calendarRef = this.getInstanceCalendarRef(
+      params.clinicBranchId,
+      params.resourceId,
+      params.resourceInstanceId
+    );
+    const eventRef = doc(calendarRef, params.eventId);
+
+    const eventSnap = await getDoc(eventRef);
+    if (!eventSnap.exists()) {
+      throw new Error(`Blocking event ${params.eventId} not found`);
+    }
+
+    const updateData: Record<string, any> = {
+      updatedAt: serverTimestamp(),
+    };
+
+    if (params.eventName !== undefined) {
+      updateData.eventName = params.eventName;
+    }
+    if (params.eventTime !== undefined) {
+      updateData.eventTime = params.eventTime;
+    }
+    if (params.description !== undefined) {
+      updateData.description = params.description;
+    }
+
+    await updateDoc(eventRef, updateData);
+
+    const updatedSnap = await getDoc(eventRef);
+    return { id: updatedSnap.id, ...updatedSnap.data() } as ResourceCalendarEvent;
+  }
+
+  /**
+   * Deletes a blocking event from a resource instance's calendar (hard delete).
+   */
+  async deleteResourceBlockingEvent(
+    clinicBranchId: string,
+    resourceId: string,
+    instanceId: string,
+    eventId: string
+  ): Promise<void> {
+    const calendarRef = this.getInstanceCalendarRef(
+      clinicBranchId,
+      resourceId,
+      instanceId
+    );
+    const eventRef = doc(calendarRef, eventId);
+
+    const eventSnap = await getDoc(eventRef);
+    if (!eventSnap.exists()) {
+      throw new Error(`Blocking event ${eventId} not found`);
+    }
+
+    await deleteDoc(eventRef);
+  }
+
+  /**
+   * Gets all blocking events for a resource instance, ordered by start time.
+   */
+  async getResourceInstanceBlockingEvents(
+    clinicBranchId: string,
+    resourceId: string,
+    instanceId: string
+  ): Promise<ResourceCalendarEvent[]> {
+    const calendarRef = this.getInstanceCalendarRef(
+      clinicBranchId,
+      resourceId,
+      instanceId
+    );
+    const q = query(
+      calendarRef,
+      where("eventType", "==", CalendarEventType.BLOCKING),
+      orderBy("eventTime.start")
+    );
+    const snapshot = await getDocs(q);
+    return snapshot.docs.map(
+      (d) => ({ id: d.id, ...d.data() } as ResourceCalendarEvent)
+    );
+  }
+}

package/src/services/reviews/index.ts

@@ -1 +1 @@
-export * from "./reviews.service";
+export * from "./reviews.service";