@blackcode_sa/metaestetics-api 1.7.23 → 1.7.24

package/package.json

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

package/src/index.ts

@@ -25,6 +25,7 @@ export { ProcedureService } from "./services/procedure/procedure.service";
 export { ClinicService } from "./services/clinic/clinic.service";
 export { ClinicAdminService } from "./services/clinic/clinic-admin.service";
 export { ClinicGroupService } from "./services/clinic/clinic-group.service";
+export { PractitionerInviteService } from "./services/clinic/practitioner-invite.service";
 export {
   DocumentationTemplateService,
   FilledDocumentService,
@@ -197,17 +198,24 @@ export type {
   CreateDefaultClinicGroupData,
   ClinicGroupSetupData,
   ClinicBranchSetupData,
+  PractitionerInvite,
+  CreatePractitionerInviteData,
+  UpdatePractitionerInviteData,
+  PractitionerInviteFilters,
+  ProposedWorkingHours,
 } from "./types/clinic";
 export {
   CLINICS_COLLECTION,
   CLINIC_GROUPS_COLLECTION,
   CLINIC_ADMINS_COLLECTION,
+  PRACTITIONER_INVITES_COLLECTION,
   PracticeType,
   Language,
   ClinicTag,
   ClinicPhotoTag,
   AdminTokenStatus,
   SubscriptionModel,
+  PractitionerInviteStatus,
 } from "./types/clinic";
 
 // Profile info types

package/src/services/clinic/README.md

@@ -85,3 +85,120 @@ Initializes the service with Firestore, Auth, App instances, and required depend
 - **`photos.utils.ts`**: Firebase Storage interactions (`uploadPhoto`, `uploadMultiplePhotos`, `deletePhoto`).
 - **`admin.utils.ts`**: Helpers for clinic admin interactions (used by `ClinicAdminService`).
 - **`search.utils.ts`**: Geo-radius search logic (`findClinicsInRadius`).
+
+# Clinic Services
+
+This directory contains services related to clinic operations.
+
+## Services
+
+### ClinicService
+
+Handles clinic CRUD operations, searching, and management.
+
+### ClinicGroupService
+
+Manages clinic groups and their operations.
+
+### ClinicAdminService
+
+Handles clinic administrator operations.
+
+### PractitionerInviteService
+
+Manages the practitioner invitation system for clinics.
+
+## PractitionerInviteService
+
+The `PractitionerInviteService` handles the complete flow of inviting practitioners to join clinics.
+
+### Flow
+
+1. Clinic searches for active practitioners by name or email (using existing practitioner search services)
+2. Clinic creates an invite request with proposed working hours
+3. Practitioner receives the invite and can accept or reject it
+4. Admins can cancel pending invites if needed
+5. Connection between practitioner and clinic is handled by aggregation side-effects
+
+### Methods
+
+#### Core Invite Methods
+
+- `createInviteAdmin(practitionerId, clinicId, proposedWorkingHours, invitedBy, message?)` - Create a new invite
+- `acceptInviteDoctor(inviteId)` - Doctor accepts an invite
+- `rejectInviteDoctor(inviteId, rejectionReason?)` - Doctor rejects an invite
+- `cancelInviteAdmin(inviteId, cancelReason?)` - Admin cancels a pending invite
+
+#### Retrieval Methods
+
+- `getAllInvitesDoctor(practitionerId, statusFilter?)` - Get all invites for a practitioner
+- `getAllInvitesClinic(clinicId, statusFilter?)` - Get all invites for a clinic
+- `getInviteById(inviteId)` - Get a specific invite
+- `getInvitesWithFilters(filters)` - Advanced filtering
+
+#### Admin Methods
+
+- `deleteInvite(inviteId)` - Delete an invite (admin only)
+
+### Status Filtering
+
+All retrieval methods support filtering by invite status:
+
+- `PENDING` - Invite has been sent but not responded to
+- `ACCEPTED` - Practitioner has accepted the invite
+- `REJECTED` - Practitioner has rejected the invite
+- `CANCELLED` - Admin has cancelled the invite
+
+### Usage Example
+
+```typescript
+// Create service instance
+const practitionerInviteService = new PractitionerInviteService(db, auth, app);
+
+// Create an invite
+const invite = await practitionerInviteService.createInviteAdmin(
+  "practitioner123",
+  "clinic456",
+  proposedHours,
+  "admin789",
+  "We'd love to have you join our team!"
+);
+
+// Get clinic's invites
+const clinicInvites = await practitionerInviteService.getAllInvitesClinic(
+  "clinic456",
+  [PractitionerInviteStatus.PENDING]
+);
+
+// Doctor accepts invite
+const acceptedInvite = await practitionerInviteService.acceptInviteDoctor(
+  invite.id
+);
+
+// Admin cancels pending invite
+const cancelledInvite = await practitionerInviteService.cancelInviteAdmin(
+  invite.id,
+  "Position no longer available"
+);
+```
+
+### Data Structure
+
+The service uses existing aggregation types from the profile module:
+
+- `PractitionerProfileInfo` - Complete practitioner information including certification
+- `ClinicInfo` - Complete clinic information including location and contact details
+
+### Error Handling
+
+All methods include proper error handling and logging. Common errors:
+
+- Practitioner/Clinic not found
+- Duplicate pending invites
+- Invalid status transitions (only pending invites can be accepted/rejected/cancelled)
+- Permission issues
+
+### Firestore Collections
+
+- Collection: `practitioner-invites`
+- Documents contain complete invite information with embedded practitioner and clinic details

package/src/services/clinic/practitioner-invite.service.ts

@@ -0,0 +1,519 @@
+import {
+  collection,
+  doc,
+  getDoc,
+  getDocs,
+  query,
+  where,
+  updateDoc,
+  setDoc,
+  deleteDoc,
+  Timestamp,
+  serverTimestamp,
+  QueryConstraint,
+  orderBy,
+  limit,
+  and,
+  or,
+} from "firebase/firestore";
+import { BaseService } from "../base.service";
+import {
+  PractitionerInvite,
+  CreatePractitionerInviteData,
+  UpdatePractitionerInviteData,
+  PractitionerInviteFilters,
+  PractitionerInviteStatus,
+  PRACTITIONER_INVITES_COLLECTION,
+} from "../../types/clinic/practitioner-invite.types";
+import { ClinicInfo, PractitionerProfileInfo } from "../../types/profile";
+import {
+  PRACTITIONERS_COLLECTION,
+  Practitioner,
+} from "../../types/practitioner";
+import { CLINICS_COLLECTION, Clinic } from "../../types/clinic";
+import { Auth } from "firebase/auth";
+import { Firestore } from "firebase/firestore";
+import { FirebaseApp } from "firebase/app";
+
+export class PractitionerInviteService extends BaseService {
+  constructor(db: Firestore, auth: Auth, app: FirebaseApp) {
+    super(db, auth, app);
+  }
+
+  /**
+   * Creates a new practitioner invite
+   * @param practitionerId - Practitioner ID
+   * @param clinicId - Clinic ID
+   * @param proposedWorkingHours - Proposed working hours
+   * @param invitedBy - Admin ID who creates the invite
+   * @param message - Optional message
+   * @returns Created invite
+   */
+  async createInviteAdmin(
+    practitionerId: string,
+    clinicId: string,
+    proposedWorkingHours: any,
+    invitedBy: string,
+    message?: string
+  ): Promise<PractitionerInvite> {
+    try {
+      const inviteId = this.generateId();
+
+      // Fetch practitioner and clinic information
+      const [practitioner, clinic] = await Promise.all([
+        this.getPractitionerById(practitionerId),
+        this.getClinicById(clinicId),
+      ]);
+
+      if (!practitioner) {
+        throw new Error(`Practitioner with ID ${practitionerId} not found`);
+      }
+
+      if (!clinic) {
+        throw new Error(`Clinic with ID ${clinicId} not found`);
+      }
+
+      // Check if there's already a pending invite for this practitioner-clinic pair
+      const existingInvite = await this.findExistingInvite(
+        practitionerId,
+        clinicId
+      );
+      if (
+        existingInvite &&
+        existingInvite.status === PractitionerInviteStatus.PENDING
+      ) {
+        throw new Error(
+          "There's already a pending invite for this practitioner at this clinic"
+        );
+      }
+
+      // Build practitioner info using existing aggregation type
+      const practitionerInfo: PractitionerProfileInfo = {
+        id: practitioner.id,
+        practitionerPhoto:
+          typeof practitioner.basicInfo.profileImageUrl === "string"
+            ? practitioner.basicInfo.profileImageUrl
+            : null,
+        name: `${practitioner.basicInfo.firstName} ${practitioner.basicInfo.lastName}`,
+        email: practitioner.basicInfo.email,
+        phone: practitioner.basicInfo.phoneNumber || null,
+        certification: practitioner.certification,
+      };
+
+      // Build clinic info using existing aggregation type
+      const clinicInfo: ClinicInfo = {
+        id: clinic.id,
+        featuredPhoto:
+          typeof clinic.coverPhoto === "string" ? clinic.coverPhoto : "",
+        name: clinic.name,
+        description: clinic.description || null,
+        location: clinic.location,
+        contactInfo: clinic.contactInfo,
+      };
+
+      const inviteData: CreatePractitionerInviteData = {
+        practitionerId,
+        clinicId,
+        practitionerInfo,
+        clinicInfo,
+        proposedWorkingHours,
+        invitedBy,
+        message: message || null,
+        status: PractitionerInviteStatus.PENDING,
+      };
+
+      const now = Timestamp.now();
+      const invite: PractitionerInvite = {
+        id: inviteId,
+        ...inviteData,
+        status: PractitionerInviteStatus.PENDING,
+        createdAt: now,
+        updatedAt: now,
+        acceptedAt: null,
+        rejectedAt: null,
+        cancelledAt: null,
+      };
+
+      const docRef = doc(this.db, PRACTITIONER_INVITES_COLLECTION, inviteId);
+      await setDoc(docRef, invite);
+
+      return invite;
+    } catch (error) {
+      console.error(
+        "[PractitionerInviteService] Error creating invite:",
+        error
+      );
+      throw error;
+    }
+  }
+
+  /**
+   * Gets all invites for a specific doctor/practitioner
+   * @param practitionerId - Practitioner ID
+   * @param statusFilter - Optional status filter
+   * @returns Array of invites
+   */
+  async getAllInvitesDoctor(
+    practitionerId: string,
+    statusFilter?: PractitionerInviteStatus[]
+  ): Promise<PractitionerInvite[]> {
+    try {
+      const constraints: QueryConstraint[] = [
+        where("practitionerId", "==", practitionerId),
+        orderBy("createdAt", "desc"),
+      ];
+
+      if (statusFilter && statusFilter.length > 0) {
+        constraints.push(where("status", "in", statusFilter));
+      }
+
+      const q = query(
+        collection(this.db, PRACTITIONER_INVITES_COLLECTION),
+        ...constraints
+      );
+
+      const querySnapshot = await getDocs(q);
+      return querySnapshot.docs.map((doc) => doc.data() as PractitionerInvite);
+    } catch (error) {
+      console.error(
+        "[PractitionerInviteService] Error getting doctor invites:",
+        error
+      );
+      throw error;
+    }
+  }
+
+  /**
+   * Gets all invites for a specific clinic
+   * @param clinicId - Clinic ID
+   * @param statusFilter - Optional status filter
+   * @returns Array of invites
+   */
+  async getAllInvitesClinic(
+    clinicId: string,
+    statusFilter?: PractitionerInviteStatus[]
+  ): Promise<PractitionerInvite[]> {
+    try {
+      const constraints: QueryConstraint[] = [
+        where("clinicId", "==", clinicId),
+        orderBy("createdAt", "desc"),
+      ];
+
+      if (statusFilter && statusFilter.length > 0) {
+        constraints.push(where("status", "in", statusFilter));
+      }
+
+      const q = query(
+        collection(this.db, PRACTITIONER_INVITES_COLLECTION),
+        ...constraints
+      );
+
+      const querySnapshot = await getDocs(q);
+      return querySnapshot.docs.map((doc) => doc.data() as PractitionerInvite);
+    } catch (error) {
+      console.error(
+        "[PractitionerInviteService] Error getting clinic invites:",
+        error
+      );
+      throw error;
+    }
+  }
+
+  /**
+   * Doctor accepts an invite
+   * @param inviteId - Invite ID
+   * @returns Updated invite
+   */
+  async acceptInviteDoctor(inviteId: string): Promise<PractitionerInvite> {
+    try {
+      const invite = await this.getInviteById(inviteId);
+      if (!invite) {
+        throw new Error(`Invite with ID ${inviteId} not found`);
+      }
+
+      if (invite.status !== PractitionerInviteStatus.PENDING) {
+        throw new Error("Only pending invites can be accepted");
+      }
+
+      const updateData = {
+        status: PractitionerInviteStatus.ACCEPTED,
+        acceptedAt: Timestamp.now(),
+        updatedAt: serverTimestamp(),
+      };
+
+      const docRef = doc(this.db, PRACTITIONER_INVITES_COLLECTION, inviteId);
+      await updateDoc(docRef, updateData);
+
+      // Return updated invite
+      return (await this.getInviteById(inviteId)) as PractitionerInvite;
+    } catch (error) {
+      console.error(
+        "[PractitionerInviteService] Error accepting invite:",
+        error
+      );
+      throw error;
+    }
+  }
+
+  /**
+   * Doctor rejects an invite
+   * @param inviteId - Invite ID
+   * @param rejectionReason - Optional reason for rejection
+   * @returns Updated invite
+   */
+  async rejectInviteDoctor(
+    inviteId: string,
+    rejectionReason?: string
+  ): Promise<PractitionerInvite> {
+    try {
+      const invite = await this.getInviteById(inviteId);
+      if (!invite) {
+        throw new Error(`Invite with ID ${inviteId} not found`);
+      }
+
+      if (invite.status !== PractitionerInviteStatus.PENDING) {
+        throw new Error("Only pending invites can be rejected");
+      }
+
+      const updateData = {
+        status: PractitionerInviteStatus.REJECTED,
+        rejectionReason: rejectionReason || null,
+        rejectedAt: Timestamp.now(),
+        updatedAt: serverTimestamp(),
+      };
+
+      const docRef = doc(this.db, PRACTITIONER_INVITES_COLLECTION, inviteId);
+      await updateDoc(docRef, updateData);
+
+      // Return updated invite
+      return (await this.getInviteById(inviteId)) as PractitionerInvite;
+    } catch (error) {
+      console.error(
+        "[PractitionerInviteService] Error rejecting invite:",
+        error
+      );
+      throw error;
+    }
+  }
+
+  /**
+   * Admin cancels an invite
+   * @param inviteId - Invite ID
+   * @param cancelReason - Optional reason for cancellation
+   * @returns Updated invite
+   */
+  async cancelInviteAdmin(
+    inviteId: string,
+    cancelReason?: string
+  ): Promise<PractitionerInvite> {
+    try {
+      const invite = await this.getInviteById(inviteId);
+      if (!invite) {
+        throw new Error(`Invite with ID ${inviteId} not found`);
+      }
+
+      if (invite.status !== PractitionerInviteStatus.PENDING) {
+        throw new Error("Only pending invites can be cancelled");
+      }
+
+      const updateData = {
+        status: PractitionerInviteStatus.CANCELLED,
+        cancelReason: cancelReason || null,
+        cancelledAt: Timestamp.now(),
+        updatedAt: serverTimestamp(),
+      };
+
+      const docRef = doc(this.db, PRACTITIONER_INVITES_COLLECTION, inviteId);
+      await updateDoc(docRef, updateData);
+
+      // Return updated invite
+      return (await this.getInviteById(inviteId)) as PractitionerInvite;
+    } catch (error) {
+      console.error(
+        "[PractitionerInviteService] Error cancelling invite:",
+        error
+      );
+      throw error;
+    }
+  }
+
+  /**
+   * Gets an invite by ID
+   * @param inviteId - Invite ID
+   * @returns Invite or null if not found
+   */
+  async getInviteById(inviteId: string): Promise<PractitionerInvite | null> {
+    try {
+      const docRef = doc(this.db, PRACTITIONER_INVITES_COLLECTION, inviteId);
+      const docSnap = await getDoc(docRef);
+
+      if (docSnap.exists()) {
+        return docSnap.data() as PractitionerInvite;
+      }
+      return null;
+    } catch (error) {
+      console.error(
+        "[PractitionerInviteService] Error getting invite by ID:",
+        error
+      );
+      throw error;
+    }
+  }
+
+  /**
+   * Gets invites with advanced filtering options
+   * @param filters - Filter options
+   * @returns Array of filtered invites
+   */
+  async getInvitesWithFilters(
+    filters: PractitionerInviteFilters
+  ): Promise<PractitionerInvite[]> {
+    try {
+      const constraints: QueryConstraint[] = [];
+
+      // Add filters
+      if (filters.practitionerId) {
+        constraints.push(where("practitionerId", "==", filters.practitionerId));
+      }
+      if (filters.clinicId) {
+        constraints.push(where("clinicId", "==", filters.clinicId));
+      }
+      if (filters.invitedBy) {
+        constraints.push(where("invitedBy", "==", filters.invitedBy));
+      }
+      if (filters.status && filters.status.length > 0) {
+        constraints.push(where("status", "in", filters.status));
+      }
+
+      // Add ordering
+      const orderField = filters.orderBy || "createdAt";
+      const orderDirection = filters.orderDirection || "desc";
+      constraints.push(orderBy(orderField, orderDirection));
+
+      // Add limit
+      if (filters.limit) {
+        constraints.push(limit(filters.limit));
+      }
+
+      const q = query(
+        collection(this.db, PRACTITIONER_INVITES_COLLECTION),
+        ...constraints
+      );
+
+      const querySnapshot = await getDocs(q);
+      let invites = querySnapshot.docs.map(
+        (doc) => doc.data() as PractitionerInvite
+      );
+
+      // Apply date filters (client-side filtering due to Firestore limitations)
+      if (filters.fromDate) {
+        invites = invites.filter(
+          (invite) => invite.createdAt >= filters.fromDate!
+        );
+      }
+      if (filters.toDate) {
+        invites = invites.filter(
+          (invite) => invite.createdAt <= filters.toDate!
+        );
+      }
+
+      return invites;
+    } catch (error) {
+      console.error(
+        "[PractitionerInviteService] Error getting invites with filters:",
+        error
+      );
+      throw error;
+    }
+  }
+
+  /**
+   * Deletes an invite (admin only)
+   * @param inviteId - Invite ID
+   */
+  async deleteInvite(inviteId: string): Promise<void> {
+    try {
+      const docRef = doc(this.db, PRACTITIONER_INVITES_COLLECTION, inviteId);
+      await deleteDoc(docRef);
+    } catch (error) {
+      console.error(
+        "[PractitionerInviteService] Error deleting invite:",
+        error
+      );
+      throw error;
+    }
+  }
+
+  // Private helper methods
+
+  /**
+   * Gets practitioner by ID
+   * @param practitionerId - Practitioner ID
+   * @returns Practitioner or null
+   */
+  private async getPractitionerById(
+    practitionerId: string
+  ): Promise<Practitioner | null> {
+    try {
+      const docRef = doc(this.db, PRACTITIONERS_COLLECTION, practitionerId);
+      const docSnap = await getDoc(docRef);
+      return docSnap.exists() ? (docSnap.data() as Practitioner) : null;
+    } catch (error) {
+      console.error(
+        "[PractitionerInviteService] Error getting practitioner:",
+        error
+      );
+      return null;
+    }
+  }
+
+  /**
+   * Gets clinic by ID
+   * @param clinicId - Clinic ID
+   * @returns Clinic or null
+   */
+  private async getClinicById(clinicId: string): Promise<Clinic | null> {
+    try {
+      const docRef = doc(this.db, CLINICS_COLLECTION, clinicId);
+      const docSnap = await getDoc(docRef);
+      return docSnap.exists() ? (docSnap.data() as Clinic) : null;
+    } catch (error) {
+      console.error("[PractitionerInviteService] Error getting clinic:", error);
+      return null;
+    }
+  }
+
+  /**
+   * Finds existing invite between practitioner and clinic
+   * @param practitionerId - Practitioner ID
+   * @param clinicId - Clinic ID
+   * @returns Existing invite or null
+   */
+  private async findExistingInvite(
+    practitionerId: string,
+    clinicId: string
+  ): Promise<PractitionerInvite | null> {
+    try {
+      const q = query(
+        collection(this.db, PRACTITIONER_INVITES_COLLECTION),
+        where("practitionerId", "==", practitionerId),
+        where("clinicId", "==", clinicId),
+        orderBy("createdAt", "desc"),
+        limit(1)
+      );
+
+      const querySnapshot = await getDocs(q);
+      if (querySnapshot.empty) {
+        return null;
+      }
+
+      return querySnapshot.docs[0].data() as PractitionerInvite;
+    } catch (error) {
+      console.error(
+        "[PractitionerInviteService] Error finding existing invite:",
+        error
+      );
+      return null;
+    }
+  }
+}

package/src/types/clinic/index.ts

@@ -400,3 +400,6 @@ export interface ClinicBranchSetupData {
 export interface ClinicTags {
   tags: ClinicTag[];
 }
+
+// Export practitioner invite types
+export * from "./practitioner-invite.types";