@blackcode_sa/metaestetics-api 1.5.28 → 1.5.30

package/src/services/clinic/utils/clinic.utils.ts

@@ -13,22 +13,26 @@ import {
   QueryConstraint,
   addDoc,
   writeBatch,
+  limit,
+  startAfter,
 } from "firebase/firestore";
 import {
   Clinic,
   CreateClinicData,
   CLINICS_COLLECTION,
-  ClinicReview,
   ClinicTag,
   ClinicGroup,
   ClinicBranchSetupData,
   ClinicLocation,
 } from "../../../types/clinic";
-import { geohashForLocation } from "geofire-common";
+import {
+  geohashForLocation,
+  distanceBetween,
+  geohashQueryBounds,
+} from "geofire-common";
 import {
   clinicSchema,
   createClinicSchema,
-  clinicReviewSchema,
 } from "../../../validations/clinic.schema";
 import { z } from "zod";
 import { FirebaseApp } from "firebase/app";
@@ -273,11 +277,18 @@ export async function createClinic(
     photosWithTags: processedPhotosWithTags,
     doctors: [],
     doctorsInfo: [],
-    services: [],
-    servicesInfo: [],
-    reviews: [],
-    reviewsInfo: [],
-    rating: { average: 0, count: 0 },
+    procedures: [],
+    proceduresInfo: [],
+    reviewInfo: {
+      totalReviews: 0,
+      averageRating: 0,
+      cleanliness: 0,
+      facilities: 0,
+      staffFriendliness: 0,
+      waitingTime: 0,
+      accessibility: 0,
+      recommendationPercentage: 0,
+    },
     admins: [creatorAdminId],
     createdAt: now,
     updatedAt: now,
@@ -818,8 +829,6 @@ export async function getAllClinics(
 
     // If pagination is specified and greater than 0, limit the query
     if (pagination && pagination > 0) {
-      const { limit, startAfter } = require("firebase/firestore");
-
       if (lastDoc) {
         clinicsQuery = query(
           clinicsCollection,
@@ -860,141 +869,81 @@ export async function getAllClinics(
  * @param rangeInKm - The range in kilometers to search within
  * @param pagination - Optional number of clinics per page (0 or undefined returns all)
  * @param lastDoc - Optional last document for pagination (if continuing from a previous page)
- * @param filters - Optional filters to apply to the search (isActive, tags, etc.)
- * @returns Array of clinics within range and the last document for pagination
+ * @returns Array of clinics with distance information and the last document for pagination
  */
 export async function getAllClinicsInRange(
   db: Firestore,
   center: { latitude: number; longitude: number },
   rangeInKm: number,
   pagination?: number,
-  lastDoc?: any,
-  filters?: {
-    isActive?: boolean;
-    tags?: ClinicTag[];
-  }
+  lastDoc?: any
 ): Promise<{ clinics: (Clinic & { distance: number })[]; lastDoc: any }> {
-  try {
-    const { distanceBetween } = require("geofire-common");
-    const centerLat = center.latitude;
-    const centerLng = center.longitude;
+  const bounds = geohashQueryBounds(
+    [center.latitude, center.longitude],
+    rangeInKm * 1000
+  );
 
-    // We'll need to get all clinics and filter them by distance
-    const clinicsCollection = collection(db, CLINICS_COLLECTION);
-    let clinicsQuery = query(clinicsCollection);
+  const matchingClinics: (Clinic & { distance: number })[] = [];
+  let lastDocSnapshot = null;
 
-    // Add active filter if specified
-    if (filters?.isActive !== undefined) {
-      clinicsQuery = query(
-        clinicsCollection,
-        where("isActive", "==", filters.isActive)
-      );
-    }
+  for (const b of bounds) {
+    const constraints: QueryConstraint[] = [
+      where("location.geohash", ">=", b[0]),
+      where("location.geohash", "<=", b[1]),
+      where("isActive", "==", true),
+    ];
 
-    const querySnapshot = await getDocs(clinicsQuery);
-    console.log(
-      `[CLINIC_UTILS] Found ${querySnapshot.docs.length} total clinics to filter by distance`
-    );
+    const q = query(collection(db, CLINICS_COLLECTION), ...constraints);
+    const querySnapshot = await getDocs(q);
 
-    // Filter the results by distance
-    const filteredDocs = [];
     for (const doc of querySnapshot.docs) {
       const clinic = doc.data() as Clinic;
-
-      // Skip clinics without proper location data
-      if (
-        !clinic.location ||
-        !clinic.location.latitude ||
-        !clinic.location.longitude
-      ) {
-        continue;
-      }
-
-      // Calculate distance
-      const distanceInM = distanceBetween(
-        [centerLat, centerLng],
+      const distance = distanceBetween(
+        [center.latitude, center.longitude],
         [clinic.location.latitude, clinic.location.longitude]
       );
 
-      // Convert to km and check if within range
-      const distanceInKm = distanceInM / 1000;
-      if (distanceInKm <= rangeInKm) {
-        // If tags filter exists, apply it
-        if (filters?.tags && filters.tags.length > 0) {
-          const hasAllTags = filters.tags.every((filterTag) =>
-            clinic.tags.some(
-              (clinicTag) =>
-                (filterTag as any).id === (clinicTag as any).id ||
-                (filterTag as any).name === (clinicTag as any).name
-            )
-          );
+      // Convert to kilometers
+      const distanceInKm = distance / 1000;
 
-          if (hasAllTags) {
-            // Add distance to clinic object for reference
-            filteredDocs.push({
-              doc,
-              distance: distanceInKm,
-            });
-          }
-        } else {
-          // Add distance to clinic object for reference
-          filteredDocs.push({
-            doc,
-            distance: distanceInKm,
-          });
-        }
+      if (distanceInKm <= rangeInKm) {
+        matchingClinics.push({
+          ...clinic,
+          distance: distanceInKm,
+        });
       }
     }
+  }
 
-    console.log(
-      `[CLINIC_UTILS] Filtered to ${filteredDocs.length} clinics within ${rangeInKm}km`
-    );
-
-    // Sort results by distance
-    filteredDocs.sort((a, b) => a.distance - b.distance);
-
-    // Apply pagination if needed
-    let paginatedDocs = filteredDocs;
-    let lastVisible = null;
+  // Sort by distance
+  matchingClinics.sort((a, b) => a.distance - b.distance);
 
-    if (pagination && pagination > 0) {
-      // If we have a lastDoc, find its index in our sorted results
-      let startIndex = 0;
-      if (lastDoc) {
-        const lastDocIndex = filteredDocs.findIndex(
-          (item) => item.doc.id === lastDoc.id
-        );
-        if (lastDocIndex !== -1) {
-          startIndex = lastDocIndex + 1;
-        }
+  if (pagination && pagination > 0) {
+    // Paginate results
+    let result = matchingClinics;
+    if (lastDoc && matchingClinics.length > 0) {
+      const lastIndex = matchingClinics.findIndex(
+        (clinic) => clinic.id === lastDoc.id
+      );
+      if (lastIndex !== -1) {
+        result = matchingClinics.slice(lastIndex + 1);
       }
-
-      // Get the paginated subset
-      paginatedDocs = filteredDocs.slice(startIndex, startIndex + pagination);
-
-      // Set the last document for the next pagination
-      lastVisible =
-        paginatedDocs.length > 0
-          ? paginatedDocs[paginatedDocs.length - 1].doc
-          : null;
     }
 
-    // Map to Clinic objects with distance information
-    const clinics = paginatedDocs.map((item) => {
-      const data = item.doc.data() as Clinic;
-      return {
-        ...data,
-        id: item.doc.id,
-        distance: item.distance, // Include distance in response
-      } as Clinic & { distance: number };
-    });
+    const paginatedClinics = result.slice(0, pagination);
+    const newLastDoc =
+      paginatedClinics.length > 0
+        ? paginatedClinics[paginatedClinics.length - 1]
+        : null;
 
     return {
-      clinics,
-      lastDoc: lastVisible,
+      clinics: paginatedClinics,
+      lastDoc: newLastDoc,
     };
-  } catch (error) {
-    console.error("[CLINIC_UTILS] Error getting clinics in range:", error);
-    throw error;
   }
+
+  return {
+    clinics: matchingClinics,
+    lastDoc: null,
+  };
 }

package/src/services/clinic/utils/filter.utils.d.ts

@@ -0,0 +1,23 @@
+import { Firestore } from "firebase/firestore";
+import { Clinic, ClinicTag } from "../../../types/clinic";
+
+export function getClinicsByFilters(
+  db: Firestore,
+  filters: {
+    center?: { latitude: number; longitude: number };
+    radiusInKm?: number;
+    tags?: ClinicTag[];
+    procedureFamily?: string;
+    procedureCategory?: string;
+    procedureSubcategory?: string;
+    procedureTechnology?: string;
+    minRating?: number;
+    maxRating?: number;
+    pagination?: number;
+    lastDoc?: any;
+    isActive?: boolean;
+  }
+): Promise<{
+  clinics: (Clinic & { distance?: number })[];
+  lastDoc: any;
+}>;

package/src/services/clinic/utils/filter.utils.ts

@@ -0,0 +1,264 @@
+import {
+  collection,
+  query,
+  where,
+  getDocs,
+  Firestore,
+  QueryConstraint,
+  startAfter,
+  limit,
+  documentId,
+  orderBy,
+} from "firebase/firestore";
+import { Clinic, ClinicTag, CLINICS_COLLECTION } from "../../../types/clinic";
+import { geohashQueryBounds, distanceBetween } from "geofire-common";
+
+/**
+ * Get clinics based on multiple filtering criteria
+ *
+ * @param db - Firestore database instance
+ * @param filters - Various filters to apply
+ * @returns Filtered clinics and the last document for pagination
+ */
+export async function getClinicsByFilters(
+  db: Firestore,
+  filters: {
+    center?: { latitude: number; longitude: number };
+    radiusInKm?: number;
+    tags?: ClinicTag[];
+    procedureFamily?: string;
+    procedureCategory?: string;
+    procedureSubcategory?: string;
+    procedureTechnology?: string;
+    minRating?: number;
+    maxRating?: number;
+    pagination?: number;
+    lastDoc?: any;
+    isActive?: boolean;
+  }
+): Promise<{
+  clinics: (Clinic & { distance?: number })[];
+  lastDoc: any;
+}> {
+  console.log(
+    "[FILTER_UTILS] Starting clinic filtering with criteria:",
+    filters
+  );
+
+  // Determine if we're doing a geo query or a regular query
+  const isGeoQuery =
+    filters.center && filters.radiusInKm && filters.radiusInKm > 0;
+
+  // Initialize base constraints
+  const constraints: QueryConstraint[] = [];
+
+  // Add active status filter (default to active if not specified)
+  if (filters.isActive !== undefined) {
+    constraints.push(where("isActive", "==", filters.isActive));
+  } else {
+    constraints.push(where("isActive", "==", true));
+  }
+
+  // Add tag filtering if specified
+  if (filters.tags && filters.tags.length > 0) {
+    // Note: We can only use array-contains-any once per query, so we're selecting one tag
+    // for the query and we'll filter the remaining tags in memory
+    constraints.push(where("tags", "array-contains", filters.tags[0]));
+  }
+
+  // Hierarchical procedure filter - only apply the most specific one provided
+  // Order of specificity: technology > subcategory > category > family
+  if (filters.procedureTechnology) {
+    constraints.push(
+      where("servicesInfo.technology", "==", filters.procedureTechnology)
+    );
+  } else if (filters.procedureSubcategory) {
+    constraints.push(
+      where("servicesInfo.subCategory", "==", filters.procedureSubcategory)
+    );
+  } else if (filters.procedureCategory) {
+    constraints.push(
+      where("servicesInfo.category", "==", filters.procedureCategory)
+    );
+  } else if (filters.procedureFamily) {
+    constraints.push(
+      where("servicesInfo.procedureFamily", "==", filters.procedureFamily)
+    );
+  }
+
+  // Add pagination if specified
+  if (filters.pagination && filters.pagination > 0 && filters.lastDoc) {
+    constraints.push(startAfter(filters.lastDoc));
+    constraints.push(limit(filters.pagination));
+  } else if (filters.pagination && filters.pagination > 0) {
+    constraints.push(limit(filters.pagination));
+  }
+
+  // Add ordering to make pagination consistent
+  constraints.push(orderBy(documentId()));
+
+  let clinicsResult: (Clinic & { distance?: number })[] = [];
+  let lastVisibleDoc = null;
+
+  // For geo queries, we need a different approach
+  if (isGeoQuery) {
+    const center = filters.center!;
+    const radiusInKm = filters.radiusInKm!;
+
+    // Get the geohash query bounds
+    const bounds = geohashQueryBounds(
+      [center.latitude, center.longitude],
+      radiusInKm * 1000 // Convert to meters
+    );
+
+    // Collect matching clinics from all bounds
+    const matchingClinics: (Clinic & { distance: number })[] = [];
+
+    // Execute queries for each bound
+    for (const bound of bounds) {
+      // Create a geo query for this bound
+      const geoConstraints = [
+        ...constraints,
+        where("location.geohash", ">=", bound[0]),
+        where("location.geohash", "<=", bound[1]),
+      ];
+
+      const q = query(collection(db, CLINICS_COLLECTION), ...geoConstraints);
+      const querySnapshot = await getDocs(q);
+
+      console.log(
+        `[FILTER_UTILS] Found ${querySnapshot.docs.length} clinics in geo bound`
+      );
+
+      // Process results and filter by actual distance
+      for (const doc of querySnapshot.docs) {
+        const clinic = { ...doc.data(), id: doc.id } as Clinic;
+
+        // Calculate actual distance
+        const distance = distanceBetween(
+          [center.latitude, center.longitude],
+          [clinic.location.latitude, clinic.location.longitude]
+        );
+
+        // Convert to kilometers
+        const distanceInKm = distance / 1000;
+
+        // Check if within radius
+        if (distanceInKm <= radiusInKm) {
+          // Add distance to clinic object
+          matchingClinics.push({
+            ...clinic,
+            distance: distanceInKm,
+          });
+        }
+      }
+    }
+
+    // Apply additional filters that couldn't be applied in the query
+    let filteredClinics = matchingClinics;
+
+    // Filter by multiple tags if more than one tag was specified
+    if (filters.tags && filters.tags.length > 1) {
+      filteredClinics = filteredClinics.filter((clinic) => {
+        // Check if clinic has all specified tags
+        return filters.tags!.every((tag) => clinic.tags.includes(tag));
+      });
+    }
+
+    // Filter by rating
+    if (filters.minRating !== undefined) {
+      filteredClinics = filteredClinics.filter(
+        (clinic) => clinic.reviewInfo.averageRating >= filters.minRating!
+      );
+    }
+
+    if (filters.maxRating !== undefined) {
+      filteredClinics = filteredClinics.filter(
+        (clinic) => clinic.reviewInfo.averageRating <= filters.maxRating!
+      );
+    }
+
+    // Sort by distance
+    filteredClinics.sort((a, b) => a.distance - b.distance);
+
+    // Apply pagination after all filters have been applied
+    if (filters.pagination && filters.pagination > 0) {
+      // If we have a lastDoc, find its index
+      let startIndex = 0;
+      if (filters.lastDoc) {
+        const lastDocIndex = filteredClinics.findIndex(
+          (clinic) => clinic.id === filters.lastDoc.id
+        );
+        if (lastDocIndex !== -1) {
+          startIndex = lastDocIndex + 1;
+        }
+      }
+
+      // Get paginated subset
+      const paginatedClinics = filteredClinics.slice(
+        startIndex,
+        startIndex + filters.pagination
+      );
+
+      // Set last document for next pagination
+      lastVisibleDoc =
+        paginatedClinics.length > 0
+          ? paginatedClinics[paginatedClinics.length - 1]
+          : null;
+
+      clinicsResult = paginatedClinics;
+    } else {
+      clinicsResult = filteredClinics;
+    }
+  } else {
+    // For non-geo queries, execute a single query with all constraints
+    const q = query(collection(db, CLINICS_COLLECTION), ...constraints);
+    const querySnapshot = await getDocs(q);
+
+    console.log(
+      `[FILTER_UTILS] Found ${querySnapshot.docs.length} clinics with regular query`
+    );
+
+    // Convert docs to clinics
+    const clinics = querySnapshot.docs.map((doc) => {
+      return { ...doc.data(), id: doc.id } as Clinic;
+    });
+
+    // Apply filters that couldn't be applied in the query
+    let filteredClinics = clinics;
+
+    // Filter by multiple tags if more than one tag was specified
+    if (filters.tags && filters.tags.length > 1) {
+      filteredClinics = filteredClinics.filter((clinic) => {
+        // Check if clinic has all specified tags
+        return filters.tags!.every((tag) => clinic.tags.includes(tag));
+      });
+    }
+
+    // Filter by rating
+    if (filters.minRating !== undefined) {
+      filteredClinics = filteredClinics.filter(
+        (clinic) => clinic.reviewInfo.averageRating >= filters.minRating!
+      );
+    }
+
+    if (filters.maxRating !== undefined) {
+      filteredClinics = filteredClinics.filter(
+        (clinic) => clinic.reviewInfo.averageRating <= filters.maxRating!
+      );
+    }
+
+    // Set last document for pagination
+    lastVisibleDoc =
+      querySnapshot.docs.length > 0
+        ? querySnapshot.docs[querySnapshot.docs.length - 1]
+        : null;
+
+    clinicsResult = filteredClinics;
+  }
+
+  return {
+    clinics: clinicsResult,
+    lastDoc: lastVisibleDoc,
+  };
+}

package/src/services/practitioner/README.md

@@ -0,0 +1,145 @@
+# Practitioner Service
+
+This service manages practitioner (doctor, therapist, etc.) data within the Firestore database. It handles practitioner profiles, draft profiles, registration tokens, and associations with clinics.
+
+**Note:** Data aggregation into related entities (Clinics, Procedures) is handled by Cloud Functions triggered by Firestore events.
+
+## `PractitionerService` Class
+
+Extends `BaseService`.
+
+### Constructor
+
+```typescript
+constructor(
+  db: Firestore,
+  auth: Auth,
+  app: FirebaseApp,
+  clinicService?: ClinicService // Optional dependency injection
+)
+```
+
+Initializes the service with Firestore, Auth, App instances. Optionally accepts a `ClinicService` instance for operations requiring clinic data (like draft creation or token validation).
+
+### Methods
+
+- **`createPractitioner(data: CreatePractitionerData): Promise<Practitioner>`**
+
+  - Creates a new, fully active practitioner profile.
+  - Validates data using `createPractitionerSchema`.
+  - Generates a unique ID using `this.generateId()`.
+  - Initializes default review info.
+  - Sets default values for `isActive` (true), `isVerified` (false), and `status` (ACTIVE).
+  - Saves the practitioner document.
+  - **Aggregation Note:** Adding practitioner info to associated `Clinics` is handled by Cloud Functions.
+
+- **`createDraftPractitioner(data: CreateDraftPractitionerData, createdBy: string, clinicId: string): Promise<{ practitioner: Practitioner; token: PractitionerToken }>`**
+
+  - Creates a draft practitioner profile (status `DRAFT`) not yet linked to a user (`userRef` is empty). Typically used by clinic admins.
+  - Validates data using `createDraftPractitionerSchema`.
+  - Verifies that the specified `clinicId` exists.
+  - Associates the practitioner with the specified `clinicId` (and potentially others in `data.clinics`).
+  - Sets `isActive` and `isVerified` to `false` by default.
+  - Saves the draft practitioner document.
+  - Automatically creates a registration token (`PractitionerToken`) for this draft profile.
+  - Returns both the created draft practitioner and the registration token.
+
+- **`createPractitionerToken(data: CreatePractitionerTokenData, createdBy: string): Promise<PractitionerToken>`**
+
+  - Creates a registration token for an existing `DRAFT` practitioner.
+  - Validates input data using `createPractitionerTokenSchema`.
+  - Ensures the practitioner exists, is in `DRAFT` status, and belongs to the specified `clinicId`.
+  - Generates a unique, short, uppercase token string.
+  - Sets a default expiration of 7 days if not provided.
+  - Saves the token in the `register_tokens` subcollection of the practitioner document.
+
+- **`getPractitionerActiveTokens(practitionerId: string): Promise<PractitionerToken[]>`**
+
+  - Retrieves all `ACTIVE` and non-expired registration tokens for a specific practitioner.
+
+- **`validateToken(tokenString: string): Promise<PractitionerToken | null>`**
+
+  - Finds an `ACTIVE`, non-expired token matching the `tokenString` across _all_ practitioners' `register_tokens` subcollections. Returns the token object or `null`.
+
+- **`markTokenAsUsed(tokenId: string, practitionerId: string, userId: string): Promise<void>`**
+
+  - Updates a specific token's status to `USED` and records who used it (`userId`) and when.
+
+- **`getPractitioner(practitionerId: string): Promise<Practitioner | null>`**
+
+  - Retrieves a single practitioner document by its ID.
+
+- **`getPractitionerByUserRef(userRef: string): Promise<Practitioner | null>`**
+
+  - Finds and retrieves a practitioner document based on the linked user ID (`userRef`).
+
+- **`getPractitionersByClinic(clinicId: string): Promise<Practitioner[]>`**
+
+  - Retrieves all `ACTIVE` practitioners associated with a specific `clinicId`.
+
+- **`getAllPractitionersByClinic(clinicId: string): Promise<Practitioner[]>`**
+
+  - Retrieves all `ACTIVE` practitioners (regardless of status like DRAFT) associated with a `clinicId`.
+
+- **`getDraftPractitionersByClinic(clinicId: string): Promise<Practitioner[]>`**
+
+  - Retrieves all practitioners with `DRAFT` status associated with a specific `clinicId`.
+
+- **`updatePractitioner(practitionerId: string, data: UpdatePractitionerData): Promise<Practitioner>`**
+
+  - Updates an existing practitioner document with partial data.
+  - Sets the `updatedAt` timestamp.
+  - **Aggregation Note:** Updates to aggregated data in `Clinics` and `Procedures` are handled by Cloud Functions.
+
+- **`addClinic(practitionerId: string, clinicId: string): Promise<void>`**
+
+  - Adds a `clinicId` to the practitioner's `clinics` array.
+  - Prevents duplicates.
+  - **Aggregation Note:** Updating the clinic's `doctors`/`doctorsInfo` is handled by Cloud Functions.
+
+- **`removeClinic(practitionerId: string, clinicId: string): Promise<void>`**
+
+  - Removes a `clinicId` from the practitioner's `clinics` array.
+  - **Aggregation Note:** Updating the clinic's `doctors`/`doctorsInfo` is handled by Cloud Functions.
+
+- **`deactivatePractitioner(practitionerId: string): Promise<void>`**
+
+  - Sets the practitioner's `isActive` flag to `false` using `updatePractitioner`.
+  - **Aggregation Note:** Related updates are handled by Cloud Functions.
+
+- **`activatePractitioner(practitionerId: string): Promise<void>`**
+
+  - Sets the practitioner's `isActive` flag to `true` using `updatePractitioner`.
+  - **Aggregation Note:** Related updates are handled by Cloud Functions.
+
+- **`deletePractitioner(practitionerId: string): Promise<void>`**
+
+  - Permanently deletes a practitioner document.
+  - **Aggregation Note:** Removal of associated data from `Clinics`, `Procedures`, etc., is handled by Cloud Functions.
+
+- **`validateTokenAndClaimProfile(tokenString: string, userId: string): Promise<Practitioner | null>`**
+
+  - Orchestrates the process of a user claiming a draft profile:
+    1.  Validates the `tokenString` using `validateToken`.
+    2.  Retrieves the associated `DRAFT` practitioner.
+    3.  Checks if the user (`userId`) already has a profile.
+    4.  Updates the practitioner's `userRef` to the `userId` and status to `ACTIVE` using `updatePractitioner`.
+    5.  Marks the token as `USED` using `markTokenAsUsed`.
+    6.  Returns the now-claimed practitioner profile.
+
+- **`getAllPractitioners(options?: { pagination?: number; lastDoc?: any; includeDraftPractitioners?: boolean }): Promise<{ practitioners: Practitioner[]; lastDoc: any }>`**
+
+  - Retrieves a list of practitioners, ordered by name.
+  - Supports pagination (`pagination`, `lastDoc`).
+  - Optionally includes `DRAFT` practitioners.
+
+- **`getPractitionersByFilters(filters: { ... }): Promise<{ practitioners: Practitioner[]; lastDoc: any }>`**
+  - Retrieves practitioners based on complex filter criteria:
+    - Name (first/last)
+    - Certifications, Specialties
+    - Procedures (Family, Category, Subcategory, Technology)
+    - Location/Radius - Filters based on associated clinics
+    - Rating (`reviewInfo.averageRating`)
+  - Combines Firestore queries with in-memory filtering for non-indexed fields.
+  - Supports pagination.
+  - Optionally includes `DRAFT` practitioners.