@blackcode_sa/metaestetics-api 1.7.45 → 1.8.0

package/src/services/{auth.service.ts → auth/auth.service.ts}

@@ -38,18 +38,18 @@ import {
   Firestore,
 } from "firebase/firestore";
 import { FirebaseApp } from "firebase/app";
-import { User, UserRole, USERS_COLLECTION } from "../types";
+import { User, UserRole, USERS_COLLECTION } from "../../types";
 import { z } from "zod";
 import {
   emailSchema,
   passwordSchema,
   userRoleSchema,
-} from "../validations/schemas";
-import { AuthError, AUTH_ERRORS } from "../errors/auth.errors";
-import { FirebaseErrorCode } from "../errors/firebase.errors";
-import { FirebaseError } from "../errors/firebase.errors";
-import { BaseService } from "./base.service";
-import { UserService } from "./user.service";
+} from "../../validations/schemas";
+import { AuthError, AUTH_ERRORS } from "../../errors/auth.errors";
+import { FirebaseErrorCode } from "../../errors/firebase.errors";
+import { FirebaseError } from "../../errors/firebase.errors";
+import { BaseService } from "../base.service";
+import { UserService } from "../user/user.service";
 import { throws } from "assert";
 import {
   ClinicGroup,
@@ -62,22 +62,22 @@ import {
   SubscriptionModel,
   CLINIC_GROUPS_COLLECTION,
   ClinicAdmin,
-} from "../types/clinic";
-import { clinicAdminSignupSchema } from "../validations/clinic.schema";
-import { ClinicGroupService } from "./clinic/clinic-group.service";
-import { ClinicAdminService } from "./clinic/clinic-admin.service";
-import { ClinicService } from "./clinic/clinic.service";
+} from "../../types/clinic";
+import { clinicAdminSignupSchema } from "../../validations/clinic.schema";
+import { ClinicGroupService } from "../clinic/clinic-group.service";
+import { ClinicAdminService } from "../clinic/clinic-admin.service";
+import { ClinicService } from "../clinic/clinic.service";
 import {
   Practitioner,
   CreatePractitionerData,
   PractitionerStatus,
   PractitionerBasicInfo,
   PractitionerCertification,
-} from "../types/practitioner";
-import { PractitionerService } from "./practitioner/practitioner.service";
-import { practitionerSignupSchema } from "../validations/practitioner.schema";
-import { CertificationLevel } from "../backoffice/types/static/certification.types";
-import { MediaService } from "./media/media.service";
+} from "../../types/practitioner";
+import { PractitionerService } from "../practitioner/practitioner.service";
+import { practitionerSignupSchema } from "../../validations/practitioner.schema";
+import { CertificationLevel } from "../../backoffice/types/static/certification.types";
+import { MediaService } from "../media/media.service";
 // Import utility functions
 import {
   checkEmailExists,
@@ -86,7 +86,7 @@ import {
   handleSignupError,
   buildPractitionerData,
   validatePractitionerProfileData,
-} from "./auth/utils";
+} from "./utils";
 
 export class AuthService extends BaseService {
   private googleProvider = new GoogleAuthProvider();
@@ -110,7 +110,10 @@ export class AuthService extends BaseService {
   async signUp(
     email: string,
     password: string,
-    initialRole: UserRole = UserRole.PATIENT
+    initialRole: UserRole = UserRole.PATIENT,
+    options?: {
+      patientInviteToken?: string;
+    }
   ): Promise<User> {
     const { user: firebaseUser } = await createUserWithEmailAndPassword(
       this.auth,
@@ -118,7 +121,7 @@ export class AuthService extends BaseService {
       password
     );
 
-    return this.userService.createUser(firebaseUser, [initialRole]);
+    return this.userService.createUser(firebaseUser, [initialRole], options);
   }
 
   /**
@@ -608,14 +611,25 @@ export class AuthService extends BaseService {
    * Prijavljuje korisnika sa Google nalogom
    */
   async signInWithGoogle(
-    initialRole: UserRole = UserRole.PATIENT
+    initialRole: UserRole = UserRole.PATIENT,
+    options?: {
+      patientInviteToken?: string;
+    }
   ): Promise<User> {
     const { user: firebaseUser } = await signInWithPopup(
       this.auth,
       this.googleProvider
     );
 
-    return this.userService.getOrCreateUser(firebaseUser);
+    const existingUser = await this.userService.getUserByEmail(
+      firebaseUser.email!
+    );
+    if (existingUser) {
+      await this.userService.updateUserLoginTimestamp(existingUser.uid);
+      return existingUser;
+    }
+
+    return this.userService.createUser(firebaseUser, [initialRole], options);
   }
 
   /**

package/src/services/{auth.v2.service.ts → auth/auth.v2.service.ts}

@@ -33,18 +33,18 @@ import {
   Firestore,
 } from "firebase/firestore";
 import { FirebaseApp } from "firebase/app";
-import { User, UserRole, USERS_COLLECTION } from "../types";
+import { User, UserRole, USERS_COLLECTION } from "../../types";
 import { z } from "zod";
 import {
   emailSchema,
   passwordSchema,
   userRoleSchema,
-} from "../validations/schemas";
-import { AuthError, AUTH_ERRORS } from "../errors/auth.errors";
-import { FirebaseErrorCode } from "../errors/firebase.errors";
-import { FirebaseError } from "../errors/firebase.errors";
-import { BaseService } from "./base.service";
-import { UserService } from "./user.service";
+} from "../../validations/schemas";
+import { AuthError, AUTH_ERRORS } from "../../errors/auth.errors";
+import { FirebaseErrorCode } from "../../errors/firebase.errors";
+import { FirebaseError } from "../../errors/firebase.errors";
+import { BaseService } from "../base.service";
+import { UserService } from "../user/user.service";
 import { throws } from "assert";
 import {
   ClinicGroup,
@@ -57,22 +57,22 @@ import {
   SubscriptionModel,
   CLINIC_GROUPS_COLLECTION,
   ClinicAdmin,
-} from "../types/clinic";
-import { clinicAdminSignupSchema } from "../validations/clinic.schema";
-import { ClinicGroupService } from "./clinic/clinic-group.service";
-import { ClinicAdminService } from "./clinic/clinic-admin.service";
-import { ClinicService } from "./clinic/clinic.service";
+} from "../../types/clinic";
+import { clinicAdminSignupSchema } from "../../validations/clinic.schema";
+import { ClinicGroupService } from "../clinic/clinic-group.service";
+import { ClinicAdminService } from "../clinic/clinic-admin.service";
+import { ClinicService } from "../clinic/clinic.service";
 import {
   Practitioner,
   CreatePractitionerData,
   PractitionerStatus,
   PractitionerBasicInfo,
   PractitionerCertification,
-} from "../types/practitioner";
-import { PractitionerService } from "./practitioner/practitioner.service";
-import { practitionerSignupSchema } from "../validations/practitioner.schema";
-import { CertificationLevel } from "../backoffice/types/static/certification.types";
-import { getFirebaseFunctions } from "../config/firebase";
+} from "../../types/practitioner";
+import { PractitionerService } from "../practitioner/practitioner.service";
+import { practitionerSignupSchema } from "../../validations/practitioner.schema";
+import { CertificationLevel } from "../../backoffice/types/static/certification.types";
+import { getFirebaseFunctions } from "../../config/firebase";
 import {
   httpsCallable,
   HttpsCallableResult,

package/src/services/auth/index.ts

@@ -3,19 +3,5 @@
  * Centralized exports for all utility modules
  */
 
-// Firebase utilities
-export { checkEmailExists, cleanupFirebaseUser } from "./utils/firebase.utils";
-
-// Error handling utilities
-export {
-  handleFirebaseError,
-  handleSignupError,
-  extractErrorMessage,
-} from "./utils/error.utils";
-
-// Practitioner utilities
-export {
-  buildPractitionerData,
-  validatePractitionerProfileData,
-  isPractitionerDataComplete,
-} from "./utils/practitioner.utils";
+export * from "./utils";
+export * from "./auth.service";

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

@@ -52,7 +52,7 @@ import {
 import {
   createAppointmentSchema,
   updateAppointmentSchema,
-} from "../../validations/calendar.schema";
+} from "../../validations/appointment.schema";
 
 // Import utility functions
 import {

package/src/services/calendar/externalCalendar.service.ts

@@ -0,0 +1,178 @@
+import { Auth } from "firebase/auth";
+import { Firestore } from "firebase/firestore";
+import { FirebaseApp } from "firebase/app";
+import { BaseService } from "../base.service";
+
+/**
+ * IMPORTANT: This URL should be loaded from an environment configuration
+ * (e.g., .env file) and should point to your deployed `externalCalendarApi`
+ * Cloud Function.
+ */
+const EXTERNAL_CALENDAR_API_BASE_URL =
+  "https://europe-west6-your-project-id.cloudfunctions.net/externalCalendarApi";
+
+/**
+ * Interface for the `generateAuthUrl` endpoint response.
+ */
+interface GenerateAuthUrlResponse {
+  success: boolean;
+  authUrl?: string;
+  error?: string;
+}
+
+/**
+ * Interface for a generic API response for success/error status.
+ */
+interface ApiResponse {
+  success: boolean;
+  error?: string;
+  [key: string]: any;
+}
+
+/**
+ * Interface for the `getConnectionStatus` endpoint response.
+ */
+interface ConnectionStatusResponse {
+  success: boolean;
+  isConnected: boolean;
+  connectionDetails?: {
+    syncStatus: string;
+    calendarId?: string;
+  };
+  error?: string;
+}
+
+/**
+ * External Calendar Service
+ *
+ * This service acts as a client-side wrapper (SDK) for the `externalCalendarApi`
+ * Firebase Cloud Function. It handles making authenticated HTTP requests from the
+ * frontend applications (web, mobile) to the backend, ensuring that no sensitive
+ * logic resides on the client.
+ */
+export class ExternalCalendarService extends BaseService {
+  /**
+   * Creates a new ExternalCalendarService instance.
+   * @param db - Firestore instance.
+   * @param auth - Firebase Auth instance.
+   * @param app - Firebase App instance.
+   */
+  constructor(db: Firestore, auth: Auth, app: FirebaseApp) {
+    super(db, auth, app);
+  }
+
+  /**
+   * A private helper method to make authenticated calls to our backend API.
+   * @param endpoint - The API endpoint to call (e.g., '/generateAuthUrl').
+   * @param body - The JSON body for the request.
+   * @returns A promise that resolves to the JSON response from the API.
+   * @throws An error if the user is not authenticated or the network request fails.
+   */
+  private async callApi<T>(endpoint: string, body: object): Promise<T> {
+    if (!this.auth.currentUser) {
+      throw new Error("User not authenticated. Cannot call API.");
+    }
+
+    const idToken = await this.auth.currentUser.getIdToken();
+    const url = `${EXTERNAL_CALENDAR_API_BASE_URL}${endpoint}`;
+
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${idToken}`,
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (!response.ok) {
+      const errorBody = await response
+        .json()
+        .catch(() => ({ error: "A network error occurred." }));
+      throw new Error(
+        errorBody.error || `HTTP error! status: ${response.status}`
+      );
+    }
+
+    return response.json() as Promise<T>;
+  }
+
+  /**
+   * Requests an authorization URL from the backend to initiate the Google Calendar connection.
+   * This is the first step in the OAuth flow.
+   *
+   * @param entityType - The type of entity connecting the calendar ('practitioner', 'clinic', or 'patient').
+   * @param entityId - The unique ID of the entity.
+   * @param platform - The platform initiating the request ('web', 'ios', 'android').
+   * @returns The Google OAuth 2.0 URL to which the user should be redirected.
+   * @throws An error if the API call fails to return a valid URL.
+   */
+  async generateAuthUrl(
+    entityType: "practitioner" | "clinic" | "patient",
+    entityId: string,
+    platform: "web" | "ios" | "android"
+  ): Promise<string> {
+    const response = await this.callApi<GenerateAuthUrlResponse>(
+      "/generateAuthUrl",
+      {
+        entityType,
+        entityId,
+        platform,
+      }
+    );
+
+    if (!response.success || !response.authUrl) {
+      throw new Error(
+        response.error || "Failed to generate authentication URL."
+      );
+    }
+
+    return response.authUrl;
+  }
+
+  /**
+   * Sends a request to the backend to disconnect a Google Calendar from an entity.
+   * This will revoke the tokens and remove the sync data from Firestore.
+   *
+   * @param entityType - The type of entity to disconnect.
+   * @param entityId - The ID of the entity.
+   * @returns A promise that resolves when the operation is successful.
+   * @throws An error if the API call fails.
+   */
+  async disconnectCalendar(
+    entityType: "practitioner" | "clinic" | "patient",
+    entityId: string
+  ): Promise<void> {
+    const response = await this.callApi<ApiResponse>("/disconnect", {
+      entityType,
+      entityId,
+    });
+
+    if (!response.success) {
+      throw new Error(response.error || "Failed to disconnect calendar.");
+    }
+  }
+
+  /**
+   * Gets the connection status of an entity's Google Calendar.
+   * This is useful for UI to determine whether to show a 'Connect' or 'Disconnect' button.
+   *
+   * @param entityType - The type of entity to check.
+   * @param entityId - The ID of the entity.
+   * @returns An object containing the connection status and details.
+   */
+  async getCalendarConnectionStatus(
+    entityType: "practitioner" | "clinic" | "patient",
+    entityId: string
+  ): Promise<ConnectionStatusResponse> {
+    const response = await this.callApi<ConnectionStatusResponse>(
+      "/getConnectionStatus",
+      {
+        entityType,
+        entityId,
+      }
+    );
+
+    return response;
+  }
+}

package/src/services/calendar/index.ts

@@ -0,0 +1,5 @@
+// export * from "./calendar-refactored.service";
+// export * from "./calendar.service";
+export * from "./calendar.v3.service";
+export * from "./externalCalendar.service";
+// export * from "./synced-calendars.service";

package/src/services/clinic/index.ts

@@ -0,0 +1,4 @@
+export * from "./clinic.service";
+export * from "./clinic-admin.service";
+export * from "./clinic-group.service";
+export * from "./practitioner-invite.service";

package/src/services/index.ts

@@ -0,0 +1,14 @@
+export * from "./auth/";
+export * from "./user/";
+
+// export * from "./base.service";
+export * from "./appointment/";
+export * from "./calendar/";
+export * from "./clinic/";
+export * from "./documentation-templates/";
+export * from "./media/";
+export * from "./notifications/";
+export * from "./patient/";
+export * from "./practitioner/";
+export * from "./procedure/";
+export * from "./reviews/";

package/src/services/media/index.ts

@@ -0,0 +1 @@
+export * from "./media.service";

package/src/services/notifications/index.ts

@@ -0,0 +1 @@
+export * from "./notification.service";

package/src/services/patient/README.md

@@ -0,0 +1,48 @@
+# Patient Service
+
+This service provides a comprehensive API for managing patient-related data within the application. It handles the creation, retrieval, and updating of patient profiles, as well as their sensitive, medical, and location-based information.
+
+## Core Responsibilities
+
+- **Patient Profile Management**: Creating standard (user-linked) and manual (offline) patient profiles.
+- **Data Segregation**: Manages different aspects of patient data in separate sub-collections for enhanced security and privacy:
+  - `sensitive-info`: Personal Identifiable Information (PII) like name, DOB, and contact details.
+  - `medical-info`: Health-related data including allergies, conditions, and medications.
+  - `location-info`: Geolocation data for search and mapping features.
+- **Security**: Enforces role-based access control, ensuring that only authorized users (patients, practitioners, clinic admins) can access or modify patient data.
+
+## Key Methods
+
+### `createPatientProfile(data: CreatePatientProfileData)`
+
+- Creates a standard patient profile linked to an existing, authenticated user account via `userRef`.
+- This is the standard flow for patients registering through the application.
+
+### `createManualPatient(data: CreateManualPatientData, requester: RequesterInfo)`
+
+- Allows a `clinic_admin` to create a patient profile that is **not** linked to a user account.
+- This is designed for managing "offline" patients within the clinic's ecosystem.
+- The `isManual` flag is set to `true` on the profile.
+- The patient is automatically associated with the admin's clinic.
+
+### `getPatientProfile(patientId: string)`
+
+- Retrieves the public-facing profile of a patient.
+
+### `getSensitiveInfo(patientId: string, requesterUserId: string)`
+
+- Retrieves the sensitive PII of a patient. Access is restricted and requires proper authorization.
+
+### `getMedicalInfo(patientId:string)`
+
+- Retrieves the medical information for a patient. Access is strictly controlled based on the requester's permissions.
+
+## Data Models
+
+The main data models used by this service are:
+
+- `PatientProfile`: The core, top-level patient document.
+- `PatientSensitiveInfo`: Sub-collection for private, personal data.
+- `PatientMedicalInfo`: Sub-collection for health records.
+
+For detailed information on the data structures, see `Api/src/types/patient/index.ts`.

package/src/services/patient/To-Do.md

@@ -0,0 +1,43 @@
+# To-Do: Manual Patient Creation
+
+This document outlines the steps required to implement the manual creation of patient profiles by clinic admins. This allows clinics to manage patients who do not yet have an account in the patient application.
+
+## Phase 1: Core Implementation (No User Link)
+
+### 1. Update Data Models and Types (`types/patient/index.ts`)
+
+- [ ] Modify `PatientProfile` to make `userRef` optional.
+- [ ] Modify `CreatePatientProfileData` to make `userRef` optional.
+- [ ] Add a new field `isManual: boolean` to `PatientProfile` and `CreatePatientProfileData` to flag patients created without a user account.
+- [ ] Modify `PatientSensitiveInfo` to make `userRef` optional.
+- [ ] Modify `CreatePatientSensitiveInfoData` to make `userRef` optional.
+- [ ] Create a new type `CreateManualPatientData` that combines necessary fields from `CreatePatientProfileData` and `CreatePatientSensitiveInfoData`, but tailored for manual creation (e.g., requires `firstName`, `lastName`, `clinicId`).
+
+### 2. Update Validation Schemas (`validations/patient.schema.ts`)
+
+- [ ] Update `patientProfileSchema` to reflect that `userRef` is optional.
+- [ ] Update `createPatientProfileSchema` to make `userRef` optional and include `isManual`.
+- [ ] Update `patientSensitiveInfoSchema` to reflect that `userRef` is optional.
+- [ ] Update `createPatientSensitiveInfoSchema` to make `userRef` optional.
+- [ ] Create a new schema `createManualPatientSchema` to validate the input for the new service method.
+
+### 3. Implement New Service Method (`services/patient/patient.service.ts`)
+
+- [ ] Create a new public method: `createManualPatient(data: CreateManualPatientData, requester: RequesterInfo): Promise<PatientProfile>`.
+- [ ] The method should perform security checks to ensure the requester is a `clinic_admin`.
+- [ ] Inside the method:
+  - Generate a new `patientId`.
+  - Create a `PatientProfile` object with `isManual: true`, no `userRef`, and link it to the admin's clinic (`requester.associatedClinicId`).
+  - Create a `PatientSensitiveInfo` object with the provided patient details.
+  - Use a Firestore batch write to create both documents atomically.
+  - Return the newly created `PatientProfile`.
+
+### 4. Documentation & README
+
+- [ ] Update the `Api/docs/guides/patient-management.md` to document the new manual creation flow.
+- [ ] Create a `README.md` file in `Api/src/services/patient/` explaining the purpose of the service and its key methods, including `createManualPatient`.
+
+## Phase 2: Future Enhancements (Post-MVP)
+
+- [ ] **Claim/Merge Profile:** Implement logic for a patient to claim a manually created profile when they register for the app. This could involve an invitation flow or matching based on personal details.
+- [ ] **UI Implementation:** Develop the UI components in the Backoffice/Clinic app for clinic admins to use this new functionality.

package/src/services/patient/index.ts

@@ -0,0 +1,2 @@
+export * from "./patient.service";
+export * from "./patientRequirements.service";