@blackcode_sa/metaestetics-api 1.5.16 → 1.5.18

package/package.json

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

package/src/index.ts

@@ -96,6 +96,8 @@ export type {
   UpdateMedicationData,
   Allergy,
   PatientProfileComplete,
+  SearchPatientsParams,
+  RequesterInfo,
 } from "./types/patient";
 export {
   Gender,
@@ -208,6 +210,9 @@ export {
   CalendarEventStatus,
   CalendarEventType,
   CalendarSyncStatus,
+  SearchLocationEnum,
+  DateRange,
+  SearchCalendarEventsParams,
   CALENDAR_COLLECTION,
 } from "./types/calendar";
 

package/src/services/calendar/calendar-refactored.service.ts

@@ -16,6 +16,9 @@ import {
   TimeSlot,
   CreateAppointmentParams,
   UpdateAppointmentParams,
+  SearchCalendarEventsParams,
+  SearchLocationEnum,
+  DateRange,
 } from "../../types/calendar";
 import {
   PRACTITIONERS_COLLECTION,
@@ -42,6 +45,9 @@ import {
   getDocs,
   setDoc,
   updateDoc,
+  QueryConstraint,
+  CollectionReference,
+  DocumentData,
 } from "firebase/firestore";
 import {
   createAppointmentSchema,
@@ -54,6 +60,7 @@ import {
   updateAppointmentUtil,
   deleteAppointmentUtil,
 } from "./utils/appointment.utils";
+import { searchCalendarEventsUtil } from "./utils/calendar-event.utils";
 import { SyncedCalendarsService } from "./synced-calendars.service";
 import { Timestamp as FirestoreTimestamp } from "firebase-admin/firestore";
 
@@ -776,6 +783,146 @@ export class CalendarServiceV2 extends BaseService {
     */
   }
 
+  /**
+   * Searches for calendar events based on specified criteria.
+   *
+   * @param {SearchCalendarEventsParams} params - The search parameters.
+   * @param {SearchLocationEnum} params.searchLocation - The primary location to search (practitioner, patient, or clinic).
+   * @param {string} params.entityId - The ID of the entity (practitioner, patient, or clinic) to search within/for.
+   * @param {string} [params.clinicId] - Optional clinic ID to filter by.
+   * @param {string} [params.practitionerId] - Optional practitioner ID to filter by.
+   * @param {string} [params.patientId] - Optional patient ID to filter by.
+   * @param {string} [params.procedureId] - Optional procedure ID to filter by.
+   * @param {DateRange} [params.dateRange] - Optional date range to filter by (event start time).
+   * @param {CalendarEventStatus} [params.eventStatus] - Optional event status to filter by.
+   * @param {CalendarEventType} [params.eventType] - Optional event type to filter by.
+   * @returns {Promise<CalendarEvent[]>} A promise that resolves to an array of matching calendar events.
+   * @throws {Error} If the search location requires an entity ID that is not provided.
+   */
+  async searchCalendarEvents(
+    params: SearchCalendarEventsParams
+  ): Promise<CalendarEvent[]> {
+    // Use the utility function to perform the search
+    return searchCalendarEventsUtil(this.db, params);
+  }
+
+  /**
+   * Gets a doctor's upcoming appointments for a specific date range
+   *
+   * @param {string} doctorId - ID of the practitioner
+   * @param {Date} startDate - Start date of the range
+   * @param {Date} endDate - End date of the range
+   * @param {CalendarEventStatus} [status] - Optional status filter (defaults to CONFIRMED)
+   * @returns {Promise<CalendarEvent[]>} A promise that resolves to an array of appointments
+   */
+  async getPractitionerUpcomingAppointments(
+    doctorId: string,
+    startDate: Date,
+    endDate: Date,
+    status: CalendarEventStatus = CalendarEventStatus.CONFIRMED
+  ): Promise<CalendarEvent[]> {
+    // Create a date range for the query
+    const dateRange: DateRange = {
+      start: Timestamp.fromDate(startDate),
+      end: Timestamp.fromDate(endDate),
+    };
+
+    // Create the search parameters
+    const searchParams: SearchCalendarEventsParams = {
+      searchLocation: SearchLocationEnum.PRACTITIONER,
+      entityId: doctorId,
+      dateRange,
+      eventStatus: status,
+      eventType: CalendarEventType.APPOINTMENT,
+    };
+
+    // Search for the appointments
+    return this.searchCalendarEvents(searchParams);
+  }
+
+  /**
+   * Gets a patient's appointments for a specific date range
+   *
+   * @param {string} patientId - ID of the patient
+   * @param {Date} startDate - Start date of the range
+   * @param {Date} endDate - End date of the range
+   * @param {CalendarEventStatus} [status] - Optional status filter (defaults to all non-canceled appointments)
+   * @returns {Promise<CalendarEvent[]>} A promise that resolves to an array of appointments
+   */
+  async getPatientAppointments(
+    patientId: string,
+    startDate: Date,
+    endDate: Date,
+    status?: CalendarEventStatus
+  ): Promise<CalendarEvent[]> {
+    // Create a date range for the query
+    const dateRange: DateRange = {
+      start: Timestamp.fromDate(startDate),
+      end: Timestamp.fromDate(endDate),
+    };
+
+    // Create the search parameters
+    const searchParams: SearchCalendarEventsParams = {
+      searchLocation: SearchLocationEnum.PATIENT,
+      entityId: patientId,
+      dateRange,
+      eventType: CalendarEventType.APPOINTMENT,
+    };
+
+    // Add status filter if provided
+    if (status) {
+      searchParams.eventStatus = status;
+    }
+
+    // Search for the appointments
+    return this.searchCalendarEvents(searchParams);
+  }
+
+  /**
+   * Gets all appointments for a clinic within a specific date range
+   *
+   * @param {string} clinicId - ID of the clinic
+   * @param {Date} startDate - Start date of the range
+   * @param {Date} endDate - End date of the range
+   * @param {string} [doctorId] - Optional doctor ID to filter by
+   * @param {CalendarEventStatus} [status] - Optional status filter
+   * @returns {Promise<CalendarEvent[]>} A promise that resolves to an array of appointments
+   */
+  async getClinicAppointments(
+    clinicId: string,
+    startDate: Date,
+    endDate: Date,
+    doctorId?: string,
+    status?: CalendarEventStatus
+  ): Promise<CalendarEvent[]> {
+    // Create a date range for the query
+    const dateRange: DateRange = {
+      start: Timestamp.fromDate(startDate),
+      end: Timestamp.fromDate(endDate),
+    };
+
+    // Create the search parameters
+    const searchParams: SearchCalendarEventsParams = {
+      searchLocation: SearchLocationEnum.CLINIC,
+      entityId: clinicId,
+      dateRange,
+      eventType: CalendarEventType.APPOINTMENT,
+    };
+
+    // Add doctor filter if provided
+    if (doctorId) {
+      searchParams.practitionerId = doctorId;
+    }
+
+    // Add status filter if provided
+    if (status) {
+      searchParams.eventStatus = status;
+    }
+
+    // Search for the appointments
+    return this.searchCalendarEvents(searchParams);
+  }
+
   // #endregion
 
   // #region Private Helper Methods

package/src/services/calendar/utils/calendar-event.utils.ts

@@ -24,6 +24,8 @@ import {
   CreateCalendarEventData,
   UpdateCalendarEventData,
   CALENDAR_COLLECTION,
+  SearchCalendarEventsParams,
+  SearchLocationEnum,
 } from "../../../types/calendar";
 import { PRACTITIONERS_COLLECTION } from "../../../types/practitioner";
 import { PATIENTS_COLLECTION } from "../../../types/patient";
@@ -508,3 +510,137 @@ export async function deleteClinicCalendarEventUtil(
   );
   await deleteDoc(eventRef);
 }
+
+/**
+ * Searches for calendar events based on specified criteria
+ * @param db - Firestore instance
+ * @param params - Search parameters
+ * @param params.searchLocation - The primary location to search (practitioner, patient, or clinic)
+ * @param params.entityId - The ID of the entity (practitioner, patient, or clinic) to search within/for
+ * @param params.clinicId - Optional clinic ID to filter by
+ * @param params.practitionerId - Optional practitioner ID to filter by
+ * @param params.patientId - Optional patient ID to filter by
+ * @param params.procedureId - Optional procedure ID to filter by
+ * @param params.dateRange - Optional date range to filter by (event start time)
+ * @param params.eventStatus - Optional event status to filter by
+ * @param params.eventType - Optional event type to filter by
+ * @returns Promise resolving to an array of matching calendar events
+ */
+export async function searchCalendarEventsUtil(
+  db: Firestore,
+  params: SearchCalendarEventsParams
+): Promise<CalendarEvent[]> {
+  const { searchLocation, entityId, ...filters } = params;
+
+  let baseCollectionPath: string;
+  const constraints: QueryConstraint[] = [];
+
+  // Determine the base collection and apply initial filter based on searchLocation
+  switch (searchLocation) {
+    case SearchLocationEnum.PRACTITIONER:
+      if (!entityId) {
+        throw new Error(
+          "Practitioner ID (entityId) is required when searching practitioner calendar."
+        );
+      }
+      baseCollectionPath = `${PRACTITIONERS_COLLECTION}/${entityId}/${CALENDAR_COLLECTION}`;
+      // If practitionerId filter is provided, it must match the entityId for this search location
+      if (filters.practitionerId && filters.practitionerId !== entityId) {
+        console.warn(
+          `Provided practitionerId filter (${filters.practitionerId}) does not match search entityId (${entityId}). Returning empty results.`
+        );
+        return [];
+      }
+      // Ensure we don't add a redundant filter if the caller also specified it
+      filters.practitionerId = undefined;
+      break;
+
+    case SearchLocationEnum.PATIENT:
+      if (!entityId) {
+        throw new Error(
+          "Patient ID (entityId) is required when searching patient calendar."
+        );
+      }
+      baseCollectionPath = `${PATIENTS_COLLECTION}/${entityId}/${CALENDAR_COLLECTION}`;
+      // If patientId filter is provided, it must match the entityId for this search location
+      if (filters.patientId && filters.patientId !== entityId) {
+        console.warn(
+          `Provided patientId filter (${filters.patientId}) does not match search entityId (${entityId}). Returning empty results.`
+        );
+        return [];
+      }
+      // Ensure we don't add a redundant filter if the caller also specified it
+      filters.patientId = undefined;
+      break;
+
+    case SearchLocationEnum.CLINIC:
+      if (!entityId) {
+        throw new Error(
+          "Clinic ID (entityId) is required when searching clinic-related events."
+        );
+      }
+      // Search the root CALENDAR_COLLECTION for events associated with the clinic
+      baseCollectionPath = CALENDAR_COLLECTION;
+      constraints.push(where("clinicBranchId", "==", entityId));
+      // If clinicId filter is provided, it must match the entityId for this search location
+      if (filters.clinicId && filters.clinicId !== entityId) {
+        console.warn(
+          `Provided clinicId filter (${filters.clinicId}) does not match search entityId (${entityId}). Returning empty results.`
+        );
+        return [];
+      }
+      // Ensure we don't add a redundant filter if the caller also specified it
+      filters.clinicId = undefined; // Already handled by the base query
+      break;
+
+    default:
+      throw new Error(`Invalid search location: ${searchLocation}`);
+  }
+
+  const collectionRef = collection(db, baseCollectionPath);
+
+  // Apply optional filters
+  if (filters.clinicId) {
+    constraints.push(where("clinicBranchId", "==", filters.clinicId));
+  }
+  if (filters.practitionerId) {
+    constraints.push(
+      where("practitionerProfileId", "==", filters.practitionerId)
+    );
+  }
+  if (filters.patientId) {
+    constraints.push(where("patientProfileId", "==", filters.patientId));
+  }
+  if (filters.procedureId) {
+    constraints.push(where("procedureId", "==", filters.procedureId));
+  }
+  if (filters.eventStatus) {
+    constraints.push(where("status", "==", filters.eventStatus));
+  }
+  if (filters.eventType) {
+    constraints.push(where("eventType", "==", filters.eventType));
+  }
+  if (filters.dateRange) {
+    // Firestore requires range filters on the same field
+    constraints.push(where("eventTime.start", ">=", filters.dateRange.start));
+    constraints.push(where("eventTime.start", "<=", filters.dateRange.end));
+    // Note: You might need to order by eventTime.start for range filters to work efficiently
+    // constraints.push(orderBy("eventTime.start"));
+  }
+
+  // Build and execute the query
+  try {
+    const finalQuery = query(collectionRef, ...constraints);
+    const querySnapshot = await getDocs(finalQuery);
+
+    const events = querySnapshot.docs.map(
+      (doc) => ({ id: doc.id, ...doc.data() } as CalendarEvent)
+    );
+
+    return events;
+  } catch (error) {
+    console.error("Error searching calendar events:", error);
+    // Depending on requirements, you might want to return an empty array or re-throw
+    return [];
+  }
+}

package/src/services/calendar/utils/index.ts

@@ -1,8 +1,8 @@
-// Export all calendar event utilities
+// Export core calendar utilities
 export * from "./calendar-event.utils";
-
-// Export all synced calendar utilities
 export * from "./synced-calendar.utils";
-
-// Export all Google Calendar utilities
 export * from "./google-calendar.utils";
+export * from "./appointment.utils";
+
+// Note: Other utility files (clinic.utils.ts, patient.utils.ts, practitioner.utils.ts, docs.utils.ts)
+// should be imported directly where needed to avoid naming conflicts