@blackcode_sa/metaestetics-api 1.15.16 → 1.15.17

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/tier-enforcement.ts

@@ -14,6 +14,7 @@ import {
 import { PRACTITIONERS_COLLECTION } from '../types/practitioner/index';
 import { PROCEDURES_COLLECTION } from '../types/procedure/index';
 import { TIER_CONFIG, resolveEffectiveTier } from '../config/tiers.config';
+import { planConfigService } from './plan-config.service';
 
 export class TierLimitError extends Error {
   public readonly code = 'TIER_LIMIT_EXCEEDED';
@@ -171,10 +172,11 @@ export async function enforceProviderLimit(
   branchId: string
 ): Promise<void> {
   const { tier, billing } = await getClinicGroupTierData(db, clinicGroupId);
-  const config = TIER_CONFIG[tier];
-  if (!config) return;
+  const dynamicConfig = await planConfigService.getConfig(db);
+  const tierDef = dynamicConfig.tiers[tier] ?? TIER_CONFIG[tier];
+  if (!tierDef) return;
 
-  const baseMax = config.limits.maxProvidersPerBranch;
+  const baseMax = tierDef.limits.maxProvidersPerBranch;
   if (baseMax === -1) return;
 
   const addOns = billing?.addOns || {};
@@ -199,15 +201,17 @@ export async function enforceProcedureLimit(
   count: number = 1
 ): Promise<void> {
   const { tier, billing } = await getClinicGroupTierData(db, clinicGroupId);
-  const config = TIER_CONFIG[tier];
-  if (!config) return;
+  const dynamicConfig = await planConfigService.getConfig(db);
+  const tierDef = dynamicConfig.tiers[tier] ?? TIER_CONFIG[tier];
+  if (!tierDef) return;
 
-  const baseMax = config.limits.maxProceduresPerProvider;
+  const baseMax = tierDef.limits.maxProceduresPerProvider;
   if (baseMax === -1) return;
 
   const addOns = billing?.addOns || {};
   const procedureBlocks = addOns[branchId]?.procedureBlocks || 0;
-  const effectiveMax = baseMax + (procedureBlocks * 5);
+  const proceduresPerBlock = dynamicConfig.addons?.procedure?.proceduresPerBlock ?? 5;
+  const effectiveMax = baseMax + (procedureBlocks * proceduresPerBlock);
 
   const currentCount = await countProceduresForProvider(db, branchId, providerId);
   if (currentCount + count > effectiveMax) {
@@ -224,10 +228,11 @@ export async function enforceBranchLimit(
   clinicGroupId: string
 ): Promise<void> {
   const { tier, billing } = await getClinicGroupTierData(db, clinicGroupId);
-  const config = TIER_CONFIG[tier];
-  if (!config) return;
+  const dynamicConfig = await planConfigService.getConfig(db);
+  const tierDef = dynamicConfig.tiers[tier] ?? TIER_CONFIG[tier];
+  if (!tierDef) return;
 
-  const baseMax = config.limits.maxBranches;
+  const baseMax = tierDef.limits.maxBranches;
   if (baseMax === -1) return;
 
   const branchAddonCount = billing?.branchAddonCount || 0;

package/src/types/appointment/index.ts

@@ -7,6 +7,7 @@ import { Requirement } from '../../backoffice/types/requirement.types';
 import { FilledDocumentStatus } from '../documentation-templates';
 import type { ContraindicationDynamic, ProcedureFamily } from '../../backoffice';
 import type { MediaResource } from '../../services/media/media.service';
+import type { ResourceBookingInfo } from '../resource';
 import { string } from 'zod/v4';
 
 /**
@@ -390,6 +391,9 @@ export interface Appointment {
 
   /** NEW: Metadata for the appointment - used for area selection and photos */
   metadata?: AppointmentMetadata;
+
+  /** Resources booked for this appointment (e.g., surgery room instance, device instance) */
+  resourceBookings?: ResourceBookingInfo[];
 }
 
 /**
@@ -470,6 +474,9 @@ export interface UpdateAppointmentData {
 
   /** NEW: For updating metadata */
   metadata?: AppointmentMetadata;
+
+  /** For updating resource bookings */
+  resourceBookings?: ResourceBookingInfo[] | FieldValue;
 }
 
 /**

package/src/types/calendar/index.ts

@@ -48,6 +48,7 @@ export enum CalendarEventType {
   BLOCKING = "blocking",
   BREAK = "break",
   FREE_DAY = "free_day",
+  RESOURCE_BOOKING = "resource_booking",
   OTHER = "other",
 }
 

package/src/types/clinic/index.ts

@@ -236,6 +236,7 @@ export enum BillingTransactionType {
   SUBSCRIPTION_CANCELED = 'subscription_canceled',
   SUBSCRIPTION_REACTIVATED = 'subscription_reactivated',
   SUBSCRIPTION_DELETED = 'subscription_deleted',
+  ADDON_PURCHASED = 'addon_purchased',
 }
 
 /**

package/src/types/clinic/rbac.types.ts

@@ -1,6 +1,7 @@
 /**
  * RBAC (Role-Based Access Control) types for clinic staff management
  */
+import { Timestamp } from 'firebase/firestore';
 
 /**
  * Roles that can be assigned to clinic staff members
@@ -24,8 +25,8 @@ export interface ClinicStaffMember {
   role: ClinicRole;
   permissions: Record<string, boolean>;
   isActive: boolean;
-  createdAt?: any;
-  updatedAt?: any;
+  createdAt?: Timestamp;
+  updatedAt?: Timestamp;
 }
 
 /**

package/src/types/index.ts

@@ -37,9 +37,15 @@ export * from "./procedure";
 // Profile types
 export * from "./profile";
 
+// Resource types
+export * from "./resource";
+
 // Reviews types
 export * from "./reviews";
 
+// System config types
+export * from "./system";
+
 // Analytics types
 export * from "./analytics";