@blackcode_sa/metaestetics-api 1.5.32 → 1.5.34

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

@@ -0,0 +1,56 @@
+import { Timestamp } from "firebase/firestore";
+import { Clinic } from "../../types/clinic";
+import { Practitioner } from "../../types/practitioner";
+import { Procedure } from "../../types/procedure";
+import { CalendarEvent } from "../../types/calendar";
+
+/**
+ * Request parameters for calculating available booking slots
+ */
+export interface BookingAvailabilityRequest {
+  /** The clinic for which to calculate booking slots */
+  clinic: Clinic;
+
+  /** The practitioner for which to calculate booking slots */
+  practitioner: Practitioner;
+
+  /** The procedure for which to calculate booking slots */
+  procedure: Procedure;
+
+  /** The timeframe for which to calculate booking slots */
+  timeframe: {
+    start: Timestamp;
+    end: Timestamp;
+  };
+
+  /** Calendar events for the clinic during the specified timeframe */
+  clinicCalendarEvents: CalendarEvent[];
+
+  /** Calendar events for the practitioner during the specified timeframe */
+  practitionerCalendarEvents: CalendarEvent[];
+}
+
+/**
+ * Represents a single available booking slot
+ */
+export interface AvailableSlot {
+  /** Start time of the available booking slot */
+  start: Timestamp;
+}
+
+/**
+ * Response with available booking slots
+ */
+export interface BookingAvailabilityResponse {
+  /** Array of available booking slots */
+  availableSlots: AvailableSlot[];
+}
+
+/**
+ * Represents a time interval with start and end times
+ * Used internally for availability calculations
+ */
+export interface TimeInterval {
+  start: Timestamp;
+  end: Timestamp;
+}

package/src/admin/booking/index.ts

@@ -0,0 +1,3 @@
+export * from "./booking.types";
+export * from "./booking.calculator";
+export { BookingAdmin } from "./booking.admin";

package/src/admin/index.ts

@@ -27,6 +27,9 @@ import { PatientAggregationService } from "./aggregation/patient/patient.aggrega
 import { BaseMailingService } from "./mailing/base.mailing.service";
 import { PractitionerInviteMailingService } from "./mailing/practitionerInvite/practitionerInvite.mailing";
 
+// Import booking services
+import { BookingAdmin } from "./booking/booking.admin";
+
 // Re-export types
 export type {
   Notification,
@@ -69,6 +72,12 @@ export {
 // Export mailing services
 export { BaseMailingService, PractitionerInviteMailingService };
 
+// Export booking services
+export { BookingAdmin };
+
+// Also export booking types
+export * from "./booking/booking.types";
+
 /**
  * Main entry point for the Admin module.
  * This module contains services and utilities intended for administrative tasks,

package/src/services/appointment/appointment.service.ts

@@ -0,0 +1,603 @@
+import {
+  Firestore,
+  Timestamp,
+  DocumentSnapshot,
+  serverTimestamp,
+} from "firebase/firestore";
+import { Auth } from "firebase/auth";
+import { FirebaseApp } from "firebase/app";
+import { BaseService } from "../base.service";
+import {
+  Appointment,
+  AppointmentStatus,
+  CreateAppointmentData,
+  UpdateAppointmentData,
+  SearchAppointmentsParams,
+  PaymentStatus,
+} from "../../types/appointment";
+import {
+  createAppointmentSchema,
+  updateAppointmentSchema,
+  searchAppointmentsSchema,
+} from "../../validations/appointment.schema";
+
+// Import other services needed (dependency injection pattern)
+import { CalendarServiceV2 } from "../calendar/calendar-refactored.service";
+import { PatientService } from "../patient/patient.service";
+import { PractitionerService } from "../practitioner/practitioner.service";
+import { ClinicService } from "../clinic/clinic.service";
+
+// Import utility functions
+import {
+  fetchAggregatedInfoUtil,
+  createAppointmentUtil,
+  updateAppointmentUtil,
+  getAppointmentByIdUtil,
+  searchAppointmentsUtil,
+} from "./utils/appointment.utils";
+
+/**
+ * AppointmentService is responsible for managing appointments,
+ * including creating, updating, retrieving, and searching appointments.
+ * It serves as the main entry point for working with appointment data.
+ */
+export class AppointmentService extends BaseService {
+  private calendarService: CalendarServiceV2;
+  private patientService: PatientService;
+  private practitionerService: PractitionerService;
+  private clinicService: ClinicService;
+
+  /**
+   * Creates a new AppointmentService instance.
+   *
+   * @param db Firestore instance
+   * @param auth Firebase Auth instance
+   * @param app Firebase App instance
+   * @param calendarService Calendar service instance
+   * @param patientService Patient service instance
+   * @param practitionerService Practitioner service instance
+   * @param clinicService Clinic service instance
+   */
+  constructor(
+    db: Firestore,
+    auth: Auth,
+    app: FirebaseApp,
+    calendarService: CalendarServiceV2,
+    patientService: PatientService,
+    practitionerService: PractitionerService,
+    clinicService: ClinicService
+  ) {
+    super(db, auth, app);
+    this.calendarService = calendarService;
+    this.patientService = patientService;
+    this.practitionerService = practitionerService;
+    this.clinicService = clinicService;
+  }
+
+  /**
+   * Creates a new appointment.
+   *
+   * @param data Data needed to create the appointment
+   * @returns The created appointment
+   */
+  async createAppointment(data: CreateAppointmentData): Promise<Appointment> {
+    try {
+      console.log("[APPOINTMENT_SERVICE] Creating appointment");
+
+      // Validate input data
+      const validatedData = await createAppointmentSchema.parseAsync(data);
+
+      // Fetch all required aggregated information
+      const aggregatedInfo = await fetchAggregatedInfoUtil(
+        this.db,
+        validatedData.clinicBranchId,
+        validatedData.practitionerId,
+        validatedData.patientId,
+        validatedData.procedureId
+      );
+
+      // Create the appointment using the utility function
+      const appointment = await createAppointmentUtil(
+        this.db,
+        validatedData as CreateAppointmentData,
+        aggregatedInfo,
+        this.generateId.bind(this)
+      );
+
+      console.log(
+        `[APPOINTMENT_SERVICE] Appointment created with ID: ${appointment.id}`
+      );
+
+      return appointment;
+    } catch (error) {
+      console.error("[APPOINTMENT_SERVICE] Error creating appointment:", error);
+      throw error;
+    }
+  }
+
+  /**
+   * Gets an appointment by ID.
+   *
+   * @param appointmentId ID of the appointment to retrieve
+   * @returns The appointment or null if not found
+   */
+  async getAppointmentById(appointmentId: string): Promise<Appointment | null> {
+    try {
+      console.log(
+        `[APPOINTMENT_SERVICE] Getting appointment with ID: ${appointmentId}`
+      );
+
+      const appointment = await getAppointmentByIdUtil(this.db, appointmentId);
+
+      console.log(
+        `[APPOINTMENT_SERVICE] Appointment ${appointmentId} ${
+          appointment ? "found" : "not found"
+        }`
+      );
+
+      return appointment;
+    } catch (error) {
+      console.error(
+        `[APPOINTMENT_SERVICE] Error getting appointment ${appointmentId}:`,
+        error
+      );
+      throw error;
+    }
+  }
+
+  /**
+   * Updates an existing appointment.
+   *
+   * @param appointmentId ID of the appointment to update
+   * @param data Update data for the appointment
+   * @returns The updated appointment
+   */
+  async updateAppointment(
+    appointmentId: string,
+    data: UpdateAppointmentData
+  ): Promise<Appointment> {
+    try {
+      console.log(
+        `[APPOINTMENT_SERVICE] Updating appointment with ID: ${appointmentId}`
+      );
+
+      // Validate input data
+      const validatedData = await updateAppointmentSchema.parseAsync(data);
+
+      // Update the appointment using the utility function
+      const updatedAppointment = await updateAppointmentUtil(
+        this.db,
+        appointmentId,
+        validatedData
+      );
+
+      console.log(
+        `[APPOINTMENT_SERVICE] Appointment ${appointmentId} updated successfully`
+      );
+
+      return updatedAppointment;
+    } catch (error) {
+      console.error(
+        `[APPOINTMENT_SERVICE] Error updating appointment ${appointmentId}:`,
+        error
+      );
+      throw error;
+    }
+  }
+
+  /**
+   * Searches for appointments based on various criteria.
+   *
+   * @param params Search parameters
+   * @returns Found appointments and the last document for pagination
+   */
+  async searchAppointments(params: SearchAppointmentsParams): Promise<{
+    appointments: Appointment[];
+    lastDoc: DocumentSnapshot | null;
+  }> {
+    try {
+      console.log(
+        "[APPOINTMENT_SERVICE] Searching appointments with params:",
+        params
+      );
+
+      // Validate search parameters
+      await searchAppointmentsSchema.parseAsync(params);
+
+      // Search for appointments using the utility function
+      const result = await searchAppointmentsUtil(this.db, params);
+
+      console.log(
+        `[APPOINTMENT_SERVICE] Found ${result.appointments.length} appointments`
+      );
+
+      return result;
+    } catch (error) {
+      console.error(
+        "[APPOINTMENT_SERVICE] Error searching appointments:",
+        error
+      );
+      throw error;
+    }
+  }
+
+  /**
+   * Gets appointments for a specific patient.
+   *
+   * @param patientId ID of the patient
+   * @param options Optional parameters for filtering and pagination
+   * @returns Found appointments and the last document for pagination
+   */
+  async getPatientAppointments(
+    patientId: string,
+    options?: {
+      startDate?: Date;
+      endDate?: Date;
+      status?: AppointmentStatus | AppointmentStatus[];
+      limit?: number;
+      startAfter?: DocumentSnapshot;
+    }
+  ): Promise<{
+    appointments: Appointment[];
+    lastDoc: DocumentSnapshot | null;
+  }> {
+    console.log(
+      `[APPOINTMENT_SERVICE] Getting appointments for patient: ${patientId}`
+    );
+
+    const searchParams: SearchAppointmentsParams = {
+      patientId,
+      startDate: options?.startDate,
+      endDate: options?.endDate,
+      status: options?.status,
+      limit: options?.limit,
+      startAfter: options?.startAfter,
+    };
+
+    return this.searchAppointments(searchParams);
+  }
+
+  /**
+   * Gets appointments for a specific practitioner.
+   *
+   * @param practitionerId ID of the practitioner
+   * @param options Optional parameters for filtering and pagination
+   * @returns Found appointments and the last document for pagination
+   */
+  async getPractitionerAppointments(
+    practitionerId: string,
+    options?: {
+      startDate?: Date;
+      endDate?: Date;
+      status?: AppointmentStatus | AppointmentStatus[];
+      limit?: number;
+      startAfter?: DocumentSnapshot;
+    }
+  ): Promise<{
+    appointments: Appointment[];
+    lastDoc: DocumentSnapshot | null;
+  }> {
+    console.log(
+      `[APPOINTMENT_SERVICE] Getting appointments for practitioner: ${practitionerId}`
+    );
+
+    const searchParams: SearchAppointmentsParams = {
+      practitionerId,
+      startDate: options?.startDate,
+      endDate: options?.endDate,
+      status: options?.status,
+      limit: options?.limit,
+      startAfter: options?.startAfter,
+    };
+
+    return this.searchAppointments(searchParams);
+  }
+
+  /**
+   * Gets appointments for a specific clinic.
+   *
+   * @param clinicBranchId ID of the clinic branch
+   * @param options Optional parameters for filtering and pagination
+   * @returns Found appointments and the last document for pagination
+   */
+  async getClinicAppointments(
+    clinicBranchId: string,
+    options?: {
+      practitionerId?: string;
+      startDate?: Date;
+      endDate?: Date;
+      status?: AppointmentStatus | AppointmentStatus[];
+      limit?: number;
+      startAfter?: DocumentSnapshot;
+    }
+  ): Promise<{
+    appointments: Appointment[];
+    lastDoc: DocumentSnapshot | null;
+  }> {
+    console.log(
+      `[APPOINTMENT_SERVICE] Getting appointments for clinic: ${clinicBranchId}`
+    );
+
+    const searchParams: SearchAppointmentsParams = {
+      clinicBranchId,
+      practitionerId: options?.practitionerId,
+      startDate: options?.startDate,
+      endDate: options?.endDate,
+      status: options?.status,
+      limit: options?.limit,
+      startAfter: options?.startAfter,
+    };
+
+    return this.searchAppointments(searchParams);
+  }
+
+  /**
+   * Updates the status of an appointment.
+   *
+   * @param appointmentId ID of the appointment
+   * @param newStatus New status to set
+   * @param cancellationReason Required if canceling the appointment
+   * @param canceledBy Required if canceling the appointment
+   * @returns The updated appointment
+   */
+  async updateAppointmentStatus(
+    appointmentId: string,
+    newStatus: AppointmentStatus,
+    cancellationReason?: string,
+    canceledBy?: "patient" | "clinic" | "practitioner" | "system"
+  ): Promise<Appointment> {
+    console.log(
+      `[APPOINTMENT_SERVICE] Updating status of appointment ${appointmentId} to ${newStatus}`
+    );
+
+    // Create update data based on the new status
+    const updateData: UpdateAppointmentData = { status: newStatus };
+
+    // Add cancellation details if applicable
+    if (
+      newStatus === AppointmentStatus.CANCELED_CLINIC ||
+      newStatus === AppointmentStatus.CANCELED_PATIENT
+    ) {
+      if (!cancellationReason) {
+        throw new Error(
+          "Cancellation reason is required when canceling an appointment"
+        );
+      }
+      if (!canceledBy) {
+        throw new Error(
+          "Canceled by is required when canceling an appointment"
+        );
+      }
+
+      updateData.cancellationReason = cancellationReason;
+      updateData.canceledBy = canceledBy;
+    }
+
+    // Add confirmation time if confirming
+    if (newStatus === AppointmentStatus.CONFIRMED) {
+      updateData.confirmationTime = Timestamp.now();
+    }
+
+    return this.updateAppointment(appointmentId, updateData);
+  }
+
+  /**
+   * Confirms an appointment.
+   *
+   * @param appointmentId ID of the appointment to confirm
+   * @returns The confirmed appointment
+   */
+  async confirmAppointment(appointmentId: string): Promise<Appointment> {
+    console.log(
+      `[APPOINTMENT_SERVICE] Confirming appointment: ${appointmentId}`
+    );
+    return this.updateAppointmentStatus(
+      appointmentId,
+      AppointmentStatus.CONFIRMED
+    );
+  }
+
+  /**
+   * Cancels an appointment from the clinic side.
+   *
+   * @param appointmentId ID of the appointment to cancel
+   * @param reason Reason for cancellation
+   * @returns The canceled appointment
+   */
+  async cancelAppointmentByClinic(
+    appointmentId: string,
+    reason: string
+  ): Promise<Appointment> {
+    console.log(
+      `[APPOINTMENT_SERVICE] Canceling appointment by clinic: ${appointmentId}`
+    );
+    return this.updateAppointmentStatus(
+      appointmentId,
+      AppointmentStatus.CANCELED_CLINIC,
+      reason,
+      "clinic"
+    );
+  }
+
+  /**
+   * Cancels an appointment from the patient side.
+   *
+   * @param appointmentId ID of the appointment to cancel
+   * @param reason Reason for cancellation
+   * @returns The canceled appointment
+   */
+  async cancelAppointmentByPatient(
+    appointmentId: string,
+    reason: string
+  ): Promise<Appointment> {
+    console.log(
+      `[APPOINTMENT_SERVICE] Canceling appointment by patient: ${appointmentId}`
+    );
+    return this.updateAppointmentStatus(
+      appointmentId,
+      AppointmentStatus.CANCELED_PATIENT,
+      reason,
+      "patient"
+    );
+  }
+
+  /**
+   * Marks an appointment as checked in.
+   *
+   * @param appointmentId ID of the appointment
+   * @returns The updated appointment
+   */
+  async checkInAppointment(appointmentId: string): Promise<Appointment> {
+    console.log(
+      `[APPOINTMENT_SERVICE] Checking in appointment: ${appointmentId}`
+    );
+    return this.updateAppointmentStatus(
+      appointmentId,
+      AppointmentStatus.CHECKED_IN
+    );
+  }
+
+  /**
+   * Marks an appointment as in progress.
+   *
+   * @param appointmentId ID of the appointment
+   * @returns The updated appointment
+   */
+  async startAppointment(appointmentId: string): Promise<Appointment> {
+    console.log(`[APPOINTMENT_SERVICE] Starting appointment: ${appointmentId}`);
+    return this.updateAppointmentStatus(
+      appointmentId,
+      AppointmentStatus.IN_PROGRESS
+    );
+  }
+
+  /**
+   * Marks an appointment as completed.
+   *
+   * @param appointmentId ID of the appointment
+   * @param actualDurationMinutes Actual duration of the appointment in minutes
+   * @returns The updated appointment
+   */
+  async completeAppointment(
+    appointmentId: string,
+    actualDurationMinutes?: number
+  ): Promise<Appointment> {
+    console.log(
+      `[APPOINTMENT_SERVICE] Completing appointment: ${appointmentId}`
+    );
+
+    const updateData: UpdateAppointmentData = {
+      status: AppointmentStatus.COMPLETED,
+      actualDurationMinutes,
+    };
+
+    return this.updateAppointment(appointmentId, updateData);
+  }
+
+  /**
+   * Marks an appointment as no-show.
+   *
+   * @param appointmentId ID of the appointment
+   * @returns The updated appointment
+   */
+  async markNoShow(appointmentId: string): Promise<Appointment> {
+    console.log(
+      `[APPOINTMENT_SERVICE] Marking appointment as no-show: ${appointmentId}`
+    );
+    return this.updateAppointmentStatus(
+      appointmentId,
+      AppointmentStatus.NO_SHOW
+    );
+  }
+
+  /**
+   * Updates the payment status of an appointment.
+   *
+   * @param appointmentId ID of the appointment
+   * @param paymentStatus New payment status
+   * @param paymentTransactionId Optional transaction ID for the payment
+   * @returns The updated appointment
+   */
+  async updatePaymentStatus(
+    appointmentId: string,
+    paymentStatus: PaymentStatus,
+    paymentTransactionId?: string
+  ): Promise<Appointment> {
+    console.log(
+      `[APPOINTMENT_SERVICE] Updating payment status of appointment ${appointmentId} to ${paymentStatus}`
+    );
+
+    const updateData: UpdateAppointmentData = {
+      paymentStatus,
+      paymentTransactionId: paymentTransactionId || null,
+    };
+
+    return this.updateAppointment(appointmentId, updateData);
+  }
+
+  /**
+   * Marks pre-procedure requirements as completed.
+   *
+   * @param appointmentId ID of the appointment
+   * @param requirementIds IDs of the requirements to mark as completed
+   * @returns The updated appointment
+   */
+  async completePreRequirements(
+    appointmentId: string,
+    requirementIds: string[]
+  ): Promise<Appointment> {
+    console.log(
+      `[APPOINTMENT_SERVICE] Marking pre-requirements as completed for appointment: ${appointmentId}`
+    );
+
+    const updateData: UpdateAppointmentData = {
+      completedPreRequirements: requirementIds,
+    };
+
+    return this.updateAppointment(appointmentId, updateData);
+  }
+
+  /**
+   * Marks post-procedure requirements as completed.
+   *
+   * @param appointmentId ID of the appointment
+   * @param requirementIds IDs of the requirements to mark as completed
+   * @returns The updated appointment
+   */
+  async completePostRequirements(
+    appointmentId: string,
+    requirementIds: string[]
+  ): Promise<Appointment> {
+    console.log(
+      `[APPOINTMENT_SERVICE] Marking post-requirements as completed for appointment: ${appointmentId}`
+    );
+
+    const updateData: UpdateAppointmentData = {
+      completedPostRequirements: requirementIds,
+    };
+
+    return this.updateAppointment(appointmentId, updateData);
+  }
+
+  /**
+   * Updates the internal notes of an appointment.
+   *
+   * @param appointmentId ID of the appointment
+   * @param notes Updated internal notes
+   * @returns The updated appointment
+   */
+  async updateInternalNotes(
+    appointmentId: string,
+    notes: string | null
+  ): Promise<Appointment> {
+    console.log(
+      `[APPOINTMENT_SERVICE] Updating internal notes for appointment: ${appointmentId}`
+    );
+
+    const updateData: UpdateAppointmentData = {
+      internalNotes: notes,
+    };
+
+    return this.updateAppointment(appointmentId, updateData);
+  }
+}

package/src/services/appointment/index.ts

@@ -0,0 +1,2 @@
+export { AppointmentService } from "./appointment.service";
+export * from "../../types/appointment";