@blackcode_sa/metaestetics-api 1.12.68 → 1.13.0

package/package.json

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

package/src/admin/aggregation/appointment/appointment.aggregation.service.ts

@@ -37,6 +37,7 @@ import { AppointmentMailingService } from '../../mailing/appointment/appointment
 import { Logger } from '../../logger';
 import { UserRole } from '../../../types';
 import { CalendarEventStatus } from '../../../types/calendar';
+import { NotificationType } from '../../../types/notifications';
 
 // Mailgun client will be injected via constructor
 
@@ -540,6 +541,13 @@ export class AppointmentAggregationService {
         await this.handleZonePhotosUpdate(before, after);
       }
 
+      // Handle Recommended Procedures Added
+      const recommendationsChanged = this.hasRecommendationsChanged(before, after);
+      if (recommendationsChanged) {
+        Logger.info(`[AggService] Recommended procedures changed for appointment ${after.id}`);
+        await this.handleRecommendedProceduresUpdate(before, after, patientProfile);
+      }
+
       // TODO: Handle Review Added
       // const reviewAdded = !before.reviewInfo && after.reviewInfo;
       // if (reviewAdded) { ... }
@@ -1841,4 +1849,136 @@ export class AppointmentAggregationService {
       // Don't throw - this is a side effect and shouldn't break the main update flow
     }
   }
+
+  /**
+   * Checks if recommended procedures have changed between two appointment states
+   * @param before - The appointment state before update
+   * @param after - The appointment state after update
+   * @returns True if recommendations have changed, false otherwise
+   */
+  private hasRecommendationsChanged(before: Appointment, after: Appointment): boolean {
+    const beforeRecommendations = before.metadata?.recommendedProcedures || [];
+    const afterRecommendations = after.metadata?.recommendedProcedures || [];
+
+    // If lengths differ, there's a change
+    if (beforeRecommendations.length !== afterRecommendations.length) {
+      return true;
+    }
+
+    // Compare each recommendation (simple comparison - if any differ, return true)
+    // For simplicity, we compare by procedure ID and note
+    for (let i = 0; i < afterRecommendations.length; i++) {
+      const beforeRec = beforeRecommendations[i];
+      const afterRec = afterRecommendations[i];
+
+      if (!beforeRec || !afterRec) {
+        return true;
+      }
+
+      if (
+        beforeRec.procedure.procedureId !== afterRec.procedure.procedureId ||
+        beforeRec.note !== afterRec.note ||
+        beforeRec.timeframe.value !== afterRec.timeframe.value ||
+        beforeRec.timeframe.unit !== afterRec.timeframe.unit
+      ) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Handles recommended procedures update - creates notifications for newly added recommendations
+   * @param before - The appointment state before update
+   * @param after - The appointment state after update
+   * @param patientProfile - The patient profile (for expo tokens)
+   */
+  private async handleRecommendedProceduresUpdate(
+    before: Appointment,
+    after: Appointment,
+    patientProfile: PatientProfile | null,
+  ): Promise<void> {
+    try {
+      const beforeRecommendations = before.metadata?.recommendedProcedures || [];
+      const afterRecommendations = after.metadata?.recommendedProcedures || [];
+
+      // Find newly added recommendations
+      const newRecommendations = afterRecommendations.slice(beforeRecommendations.length);
+
+      if (newRecommendations.length === 0) {
+        Logger.info(
+          `[AggService] No new recommendations detected for appointment ${after.id}`,
+        );
+        return;
+      }
+
+      Logger.info(
+        `[AggService] Found ${newRecommendations.length} new recommendation(s) for appointment ${after.id}`,
+      );
+
+      // Create notifications for each new recommendation
+      for (let i = 0; i < newRecommendations.length; i++) {
+        const recommendation = newRecommendations[i];
+        const recommendationIndex = beforeRecommendations.length + i;
+        const recommendationId = `${after.id}:${recommendationIndex}`;
+
+        // Format timeframe for display
+        const timeframeText = `${recommendation.timeframe.value} ${recommendation.timeframe.unit}${recommendation.timeframe.value > 1 ? 's' : ''}`;
+
+        // Create notification
+        const notificationPayload: Omit<
+          any,
+          'id' | 'createdAt' | 'updatedAt' | 'status' | 'isRead'
+        > = {
+          userId: after.patientId,
+          userRole: UserRole.PATIENT,
+          notificationType: NotificationType.PROCEDURE_RECOMMENDATION,
+          notificationTime: admin.firestore.Timestamp.now(),
+          notificationTokens: patientProfile?.expoTokens || [],
+          title: 'New Procedure Recommendation',
+          body: `${after.practitionerInfo?.name || 'Your doctor'} recommended "${recommendation.procedure.procedureName}" for you. Suggested timeframe: in ${timeframeText}`,
+          appointmentId: after.id,
+          recommendationId,
+          procedureId: recommendation.procedure.procedureId,
+          procedureName: recommendation.procedure.procedureName,
+          practitionerName: after.practitionerInfo?.name || 'Unknown Practitioner',
+          clinicName: after.clinicInfo?.name || 'Unknown Clinic',
+          note: recommendation.note,
+          timeframe: recommendation.timeframe,
+        };
+
+        try {
+          const notificationId = await this.notificationsAdmin.createNotification(
+            notificationPayload as any,
+          );
+
+          Logger.info(
+            `[AggService] Created notification ${notificationId} for recommendation ${recommendationId}`,
+          );
+
+          // Send push notification immediately if patient has tokens
+          if (patientProfile?.expoTokens && patientProfile.expoTokens.length > 0) {
+            const notification = await this.notificationsAdmin.getNotification(notificationId);
+            if (notification) {
+              await this.notificationsAdmin.sendPushNotification(notification);
+              Logger.info(
+                `[AggService] Sent push notification for recommendation ${recommendationId}`,
+              );
+            }
+          }
+        } catch (error) {
+          Logger.error(
+            `[AggService] Error creating notification for recommendation ${recommendationId}:`,
+            error,
+          );
+        }
+      }
+    } catch (error) {
+      Logger.error(
+        `[AggService] Error handling recommended procedures update for appointment ${after.id}:`,
+        error,
+      );
+    }
+  }
 }

package/src/admin/analytics/analytics.admin.service.ts

@@ -0,0 +1,278 @@
+import * as admin from 'firebase-admin';
+import { AnalyticsService } from '../../services/analytics/analytics.service';
+import {
+  AnalyticsDateRange,
+  AnalyticsFilters,
+  EntityType,
+} from '../../types/analytics';
+import {
+  PractitionerAnalytics,
+  ProcedureAnalytics,
+  TimeEfficiencyMetrics,
+  CancellationMetrics,
+  NoShowMetrics,
+  RevenueMetrics,
+  ProductUsageMetrics,
+  PatientAnalytics,
+  ClinicAnalytics,
+  DashboardAnalytics,
+  GroupedRevenueMetrics,
+  GroupedProductUsageMetrics,
+  GroupedTimeEfficiencyMetrics,
+  GroupedPatientBehaviorMetrics,
+} from '../../types/analytics';
+import { Appointment } from '../../types/appointment';
+import { APPOINTMENTS_COLLECTION } from '../../types/appointment';
+
+/**
+ * Admin version of AnalyticsService that uses Firebase Admin SDK
+ * This is intended for use in Cloud Functions and server-side code
+ */
+export class AnalyticsAdminService {
+  private analyticsService: AnalyticsService;
+  private db: admin.firestore.Firestore;
+
+  /**
+   * Creates a new AnalyticsAdminService instance
+   *
+   * @param firestore - Admin Firestore instance (optional, defaults to admin.firestore())
+   */
+  constructor(firestore?: admin.firestore.Firestore) {
+    this.db = firestore || admin.firestore();
+    
+    // Create a mock Firebase App for client SDK compatibility
+    const mockApp = {
+      name: '[DEFAULT]',
+      options: {},
+      automaticDataCollectionEnabled: false,
+    } as any;
+
+    // Create mock Auth (not used by AnalyticsService)
+    const mockAuth = {} as any;
+
+    // Create AppointmentService adapter that uses admin SDK
+    const appointmentService = this.createAppointmentServiceAdapter();
+
+    // Initialize AnalyticsService with adapted dependencies
+    this.analyticsService = new AnalyticsService(
+      this.db as any, // Cast admin Firestore to client Firestore type
+      mockAuth,
+      mockApp,
+      appointmentService,
+    );
+  }
+
+  /**
+   * Creates an adapter for AppointmentService to work with admin SDK
+   */
+  private createAppointmentServiceAdapter(): any {
+    return {
+      searchAppointments: async (params: any) => {
+        // Build query using admin SDK
+        let query: admin.firestore.Query = this.db.collection(APPOINTMENTS_COLLECTION);
+
+        if (params.clinicBranchId) {
+          query = query.where('clinicBranchId', '==', params.clinicBranchId);
+        }
+        if (params.practitionerId) {
+          query = query.where('practitionerId', '==', params.practitionerId);
+        }
+        if (params.procedureId) {
+          query = query.where('procedureId', '==', params.procedureId);
+        }
+        if (params.patientId) {
+          query = query.where('patientId', '==', params.patientId);
+        }
+        if (params.startDate) {
+          const startDate = params.startDate instanceof Date 
+            ? params.startDate 
+            : params.startDate.toDate();
+          const startTimestamp = admin.firestore.Timestamp.fromDate(startDate);
+          query = query.where('appointmentStartTime', '>=', startTimestamp);
+        }
+        if (params.endDate) {
+          const endDate = params.endDate instanceof Date 
+            ? params.endDate 
+            : params.endDate.toDate();
+          const endTimestamp = admin.firestore.Timestamp.fromDate(endDate);
+          query = query.where('appointmentStartTime', '<=', endTimestamp);
+        }
+
+        const snapshot = await query.get();
+        const appointments = snapshot.docs.map(doc => ({
+          id: doc.id,
+          ...doc.data(),
+        })) as Appointment[];
+
+        return {
+          appointments,
+          total: appointments.length,
+        };
+      },
+    };
+  }
+
+  // Delegate all methods to the underlying AnalyticsService
+  // We expose them here so they can be called with admin SDK context
+
+  async getPractitionerAnalytics(
+    practitionerId: string,
+    dateRange?: AnalyticsDateRange,
+    options?: any,
+  ): Promise<PractitionerAnalytics> {
+    return this.analyticsService.getPractitionerAnalytics(practitionerId, dateRange, options);
+  }
+
+  async getProcedureAnalytics(
+    procedureId?: string,
+    dateRange?: AnalyticsDateRange,
+    options?: any,
+  ): Promise<ProcedureAnalytics | ProcedureAnalytics[]> {
+    return this.analyticsService.getProcedureAnalytics(procedureId, dateRange, options);
+  }
+
+  async getTimeEfficiencyMetrics(
+    filters?: AnalyticsFilters,
+    dateRange?: AnalyticsDateRange,
+    options?: any,
+  ): Promise<TimeEfficiencyMetrics> {
+    return this.analyticsService.getTimeEfficiencyMetrics(filters, dateRange, options);
+  }
+
+  async getTimeEfficiencyMetricsByEntity(
+    groupBy: EntityType,
+    dateRange?: AnalyticsDateRange,
+    filters?: AnalyticsFilters,
+  ): Promise<GroupedTimeEfficiencyMetrics[]> {
+    return this.analyticsService.getTimeEfficiencyMetricsByEntity(groupBy, dateRange, filters);
+  }
+
+  async getCancellationMetrics(
+    groupBy: EntityType,
+    dateRange?: AnalyticsDateRange,
+    options?: any,
+  ): Promise<CancellationMetrics | CancellationMetrics[]> {
+    return this.analyticsService.getCancellationMetrics(groupBy, dateRange, options);
+  }
+
+  async getNoShowMetrics(
+    groupBy: EntityType,
+    dateRange?: AnalyticsDateRange,
+    options?: any,
+  ): Promise<NoShowMetrics | NoShowMetrics[]> {
+    return this.analyticsService.getNoShowMetrics(groupBy, dateRange, options);
+  }
+
+  async getRevenueMetrics(
+    filters?: AnalyticsFilters,
+    dateRange?: AnalyticsDateRange,
+    options?: any,
+  ): Promise<RevenueMetrics> {
+    return this.analyticsService.getRevenueMetrics(filters, dateRange, options);
+  }
+
+  async getRevenueMetricsByEntity(
+    groupBy: EntityType,
+    dateRange?: AnalyticsDateRange,
+    filters?: AnalyticsFilters,
+  ): Promise<GroupedRevenueMetrics[]> {
+    return this.analyticsService.getRevenueMetricsByEntity(groupBy, dateRange, filters);
+  }
+
+  async getProductUsageMetrics(
+    productId?: string,
+    dateRange?: AnalyticsDateRange,
+  ): Promise<ProductUsageMetrics | ProductUsageMetrics[]> {
+    return this.analyticsService.getProductUsageMetrics(productId, dateRange);
+  }
+
+  async getProductUsageMetricsByEntity(
+    groupBy: EntityType,
+    dateRange?: AnalyticsDateRange,
+    filters?: AnalyticsFilters,
+  ): Promise<GroupedProductUsageMetrics[]> {
+    return this.analyticsService.getProductUsageMetricsByEntity(groupBy, dateRange, filters);
+  }
+
+  async getPatientAnalytics(
+    patientId?: string,
+    dateRange?: AnalyticsDateRange,
+  ): Promise<PatientAnalytics | PatientAnalytics[]> {
+    return this.analyticsService.getPatientAnalytics(patientId, dateRange);
+  }
+
+  async getPatientBehaviorMetricsByEntity(
+    groupBy: 'clinic' | 'practitioner' | 'procedure' | 'technology',
+    dateRange?: AnalyticsDateRange,
+    filters?: AnalyticsFilters,
+  ): Promise<GroupedPatientBehaviorMetrics[]> {
+    return this.analyticsService.getPatientBehaviorMetricsByEntity(groupBy, dateRange, filters);
+  }
+
+  async getClinicAnalytics(
+    clinicBranchId: string,
+    dateRange?: AnalyticsDateRange,
+  ): Promise<ClinicAnalytics | ClinicAnalytics[]> {
+    // Use getDashboardData to get clinic-level analytics
+    const dashboard = await this.analyticsService.getDashboardData(
+      { clinicBranchId },
+      dateRange,
+    );
+    
+    // Get clinic info
+    const clinicDoc = await this.db.collection('clinics').doc(clinicBranchId).get();
+    const clinicData = clinicDoc.data();
+    const clinicName = clinicData?.name || 'Unknown';
+    
+    // Convert DashboardAnalytics to ClinicAnalytics format
+    return {
+      clinicBranchId,
+      clinicName,
+      totalAppointments: dashboard.overview.totalAppointments,
+      completedAppointments: dashboard.overview.completedAppointments,
+      canceledAppointments: dashboard.overview.canceledAppointments,
+      noShowAppointments: dashboard.overview.noShowAppointments,
+      cancellationRate: dashboard.overview.cancellationRate,
+      noShowRate: dashboard.overview.noShowRate,
+      totalRevenue: dashboard.overview.totalRevenue,
+      averageRevenuePerAppointment: dashboard.overview.averageRevenuePerAppointment,
+      currency: dashboard.overview.currency,
+      practitionerCount: dashboard.overview.uniquePractitioners,
+      patientCount: dashboard.overview.uniquePatients,
+      procedureCount: dashboard.overview.uniqueProcedures,
+      topPractitioners: dashboard.practitionerMetrics.slice(0, 5).map(p => ({
+        practitionerId: p.practitionerId,
+        practitionerName: p.practitionerName,
+        appointmentCount: p.totalAppointments,
+        revenue: p.totalRevenue,
+      })),
+      topProcedures: dashboard.procedureMetrics.slice(0, 5).map(p => ({
+        procedureId: p.procedureId,
+        procedureName: p.procedureName,
+        appointmentCount: p.totalAppointments,
+        revenue: p.totalRevenue,
+      })),
+    };
+  }
+
+  async getDashboardData(
+    filters?: AnalyticsFilters,
+    dateRange?: AnalyticsDateRange,
+    options?: any,
+  ): Promise<DashboardAnalytics> {
+    return this.analyticsService.getDashboardData(filters, dateRange, options);
+  }
+
+  /**
+   * Expose fetchAppointments for direct access if needed
+   * This method is used internally by AnalyticsService
+   */
+  async fetchAppointments(
+    filters?: AnalyticsFilters,
+    dateRange?: AnalyticsDateRange,
+  ): Promise<any[]> {
+    // Access the private method via the service
+    return (this.analyticsService as any).fetchAppointments(filters, dateRange);
+  }
+}
+

package/src/admin/analytics/index.ts

@@ -0,0 +1,2 @@
+export * from './analytics.admin.service';
+

package/src/admin/index.ts

@@ -64,6 +64,7 @@ TimestampUtils.enableServerMode();
 
 // Export all services and utilities from the admin sub-modules.
 export * from './aggregation';
+export * from './analytics';
 export * from './booking';
 export * from './calendar';
 export * from './documentation-templates';
@@ -73,3 +74,8 @@ export * from './mailing';
 export * from './notifications';
 export * from './requirements';
 export * from './users';
+
+// Export analytics types for Cloud Functions
+export type * from '../types/analytics';
+export * from '../types/analytics';
+export { CLINICS_COLLECTION } from '../types/clinic';

package/src/backoffice/services/README.md

@@ -38,3 +38,20 @@ Manages administrative constants like treatment benefits and contraindications.
 - **`addContraindication(contraindication)`**: Adds a new contraindication.
 - **`updateContraindication(contraindication)`**: Updates an existing contraindication.
 - **`deleteContraindication(contraindicationId)`**: Deletes a contraindication.
+
+### `AnalyticsService` (Proposed)
+
+Comprehensive financial and analytical intelligence service for the Clinic Admin app. Provides insights about doctors, procedures, appointments, patients, products, and clinic operations.
+
+**Status**: Proposal phase - See [analytics.service.proposal.md](./analytics.service.proposal.md) for detailed design and implementation plan.
+
+**Planned Features**:
+- Practitioner performance analytics (appointments, cancellations, time efficiency, revenue)
+- Procedure analytics (popularity, profitability, product usage)
+- Appointment time analytics (booked vs actual time, efficiency metrics)
+- Cancellation & no-show analytics (by clinic, practitioner, patient, procedure)
+- Financial analytics (revenue, costs, payment status, trends)
+- Product usage analytics (usage patterns, revenue contribution)
+- Patient analytics (lifetime value, retention, appointment frequency)
+- Clinic analytics (performance metrics, comparisons)
+- Comprehensive dashboard data aggregation