@blackcode_sa/metaestetics-api 1.12.72 → 1.13.1

package/src/types/analytics/grouped-analytics.types.ts

@@ -0,0 +1,173 @@
+import { EntityType } from './analytics.types';
+
+/**
+ * Base interface for grouped analytics results
+ * All grouped analytics share common entity identification
+ */
+export interface GroupedAnalyticsBase {
+  entityId: string;
+  entityName: string;
+  entityType: EntityType;
+}
+
+/**
+ * Review metrics for grouped analytics
+ * Note: This is a simplified version for grouped analytics.
+ * For full review analytics, see ReviewAnalyticsService.ReviewMetrics
+ */
+export interface ReviewMetrics {
+  totalReviews: number;
+  averageRating: number;
+  recommendationRate: number; // % that would recommend
+  // Comparison to overall average
+  ratingDifference?: number; // Positive = above average, negative = below
+  recommendationDifference?: number; // % difference
+}
+
+/**
+ * Grouped Revenue Metrics
+ * Revenue analytics grouped by clinic, practitioner, procedure, or patient
+ */
+export interface GroupedRevenueMetrics extends GroupedAnalyticsBase {
+  totalRevenue: number;
+  averageRevenuePerAppointment: number;
+  totalAppointments: number;
+  completedAppointments: number;
+  currency: string;
+  unpaidRevenue: number;
+  refundedRevenue: number;
+  totalTax: number;
+  totalSubtotal: number;
+  // Practitioner info when grouping by procedure
+  practitionerId?: string;
+  practitionerName?: string;
+  // Review metrics (optional)
+  reviewMetrics?: ReviewMetrics;
+}
+
+/**
+ * Grouped Product Usage Metrics
+ * Product usage analytics grouped by clinic, practitioner, procedure, or patient
+ */
+export interface GroupedProductUsageMetrics extends GroupedAnalyticsBase {
+  totalProductsUsed: number;
+  uniqueProducts: number;
+  totalProductRevenue: number;
+  totalProductQuantity: number;
+  averageProductsPerAppointment: number;
+  topProducts: Array<{
+    productId: string;
+    productName: string;
+    brandName: string;
+    totalQuantity: number;
+    totalRevenue: number;
+    usageCount: number;
+  }>;
+  // Practitioner info when grouping by procedure
+  practitionerId?: string;
+  practitionerName?: string;
+}
+
+/**
+ * Grouped Patient Retention Metrics
+ * Patient retention analytics grouped by clinic, practitioner, or procedure
+ */
+export interface GroupedPatientRetentionMetrics extends GroupedAnalyticsBase {
+  totalPatients: number;
+  newPatients: number;
+  returningPatients: number;
+  retentionRate: number; // percentage
+  averageAppointmentsPerPatient: number;
+  patientsByAppointmentCount: Array<{
+    appointmentCount: number;
+    patientCount: number;
+    percentage: number;
+  }>;
+}
+
+/**
+ * Grouped Time Efficiency Metrics
+ * Time efficiency analytics grouped by clinic, practitioner, procedure, or patient
+ */
+export interface GroupedTimeEfficiencyMetrics extends GroupedAnalyticsBase {
+  totalAppointments: number;
+  appointmentsWithActualTime: number;
+  averageBookedDuration: number; // minutes
+  averageActualDuration: number; // minutes
+  averageEfficiency: number; // percentage
+  totalOverrun: number; // minutes
+  totalUnderutilization: number; // minutes
+  averageOverrun: number; // minutes
+  averageUnderutilization: number; // minutes
+  // Practitioner info when grouping by procedure
+  practitionerId?: string;
+  practitionerName?: string;
+}
+
+/**
+ * Grouped Patient Behavior Metrics
+ * Patient behavior (no-show, cancellation) grouped by clinic, practitioner, or procedure
+ */
+export interface GroupedPatientBehaviorMetrics extends GroupedAnalyticsBase {
+  totalPatients: number;
+  patientsWithNoShows: number;
+  patientsWithCancellations: number;
+  averageNoShowRate: number; // percentage (average across patients)
+  averageCancellationRate: number; // percentage (average across patients)
+  topNoShowPatients: Array<{
+    patientId: string;
+    patientName: string;
+    noShowCount: number;
+    totalAppointments: number;
+    noShowRate: number;
+  }>;
+  topCancellationPatients: Array<{
+    patientId: string;
+    patientName: string;
+    cancellationCount: number;
+    totalAppointments: number;
+    cancellationRate: number;
+  }>;
+}
+
+/**
+ * Grouped Procedure Performance Metrics
+ * Procedure performance grouped by clinic or practitioner
+ */
+export interface GroupedProcedurePerformanceMetrics extends GroupedAnalyticsBase {
+  totalProcedures: number;
+  totalAppointments: number;
+  completedAppointments: number;
+  totalRevenue: number;
+  averageRevenuePerProcedure: number;
+  topProcedures: Array<{
+    procedureId: string;
+    procedureName: string;
+    appointmentCount: number;
+    revenue: number;
+    cancellationRate: number;
+    noShowRate: number;
+  }>;
+}
+
+/**
+ * Grouped Practitioner Performance Metrics
+ * Practitioner performance grouped by clinic
+ */
+export interface GroupedPractitionerPerformanceMetrics extends GroupedAnalyticsBase {
+  totalPractitioners: number;
+  totalAppointments: number;
+  completedAppointments: number;
+  totalRevenue: number;
+  averageRevenuePerPractitioner: number;
+  topPractitioners: Array<{
+    practitionerId: string;
+    practitionerName: string;
+    appointmentCount: number;
+    revenue: number;
+    cancellationRate: number;
+    noShowRate: number;
+    timeEfficiency: number;
+  }>;
+}
+

package/src/types/analytics/index.ts

@@ -0,0 +1,4 @@
+export * from './analytics.types';
+export * from './stored-analytics.types';
+export * from './grouped-analytics.types';
+

package/src/types/analytics/stored-analytics.types.ts

@@ -0,0 +1,137 @@
+import { Timestamp } from 'firebase/firestore';
+import {
+  PractitionerAnalytics,
+  ProcedureAnalytics,
+  TimeEfficiencyMetrics,
+  CancellationMetrics,
+  NoShowMetrics,
+  RevenueMetrics,
+  DashboardAnalytics,
+  ClinicAnalytics,
+  AnalyticsDateRange,
+} from './analytics.types';
+
+/**
+ * Period type for analytics snapshots
+ */
+export type AnalyticsPeriod = 'daily' | 'weekly' | 'monthly' | 'yearly' | 'all_time';
+
+/**
+ * Analytics document metadata
+ */
+export interface AnalyticsMetadata {
+  clinicBranchId: string;
+  period: AnalyticsPeriod;
+  periodStart: Date;
+  periodEnd: Date;
+  computedAt: Timestamp;
+  computedBy: 'cloud_function' | 'manual';
+  version: string; // Schema version for future migrations
+}
+
+/**
+ * Stored Practitioner Analytics
+ * Stored in: clinics/{clinicBranchId}/analytics/practitioners/{practitionerId}/{period}
+ */
+export interface StoredPractitionerAnalytics extends PractitionerAnalytics {
+  metadata: AnalyticsMetadata;
+}
+
+/**
+ * Stored Procedure Analytics
+ * Stored in: clinics/{clinicBranchId}/analytics/procedures/{procedureId}/{period}
+ */
+export interface StoredProcedureAnalytics extends ProcedureAnalytics {
+  metadata: AnalyticsMetadata;
+}
+
+/**
+ * Stored Clinic Analytics
+ * Stored in: clinics/{clinicBranchId}/analytics/clinic/{period}
+ */
+export interface StoredClinicAnalytics extends ClinicAnalytics {
+  metadata: AnalyticsMetadata;
+}
+
+/**
+ * Stored Dashboard Analytics
+ * Stored in: clinics/{clinicBranchId}/analytics/dashboard/{period}
+ */
+export interface StoredDashboardAnalytics extends DashboardAnalytics {
+  metadata: AnalyticsMetadata;
+}
+
+/**
+ * Stored Time Efficiency Metrics
+ * Stored in: clinics/{clinicBranchId}/analytics/time_efficiency/{period}
+ */
+export interface StoredTimeEfficiencyMetrics extends TimeEfficiencyMetrics {
+  metadata: AnalyticsMetadata;
+}
+
+/**
+ * Stored Cancellation Metrics
+ * Stored in: clinics/{clinicBranchId}/analytics/cancellations/{entityType}/{period}
+ */
+export interface StoredCancellationMetrics extends CancellationMetrics {
+  metadata: AnalyticsMetadata;
+}
+
+/**
+ * Stored No-Show Metrics
+ * Stored in: clinics/{clinicBranchId}/analytics/no_shows/{entityType}/{period}
+ */
+export interface StoredNoShowMetrics extends NoShowMetrics {
+  metadata: AnalyticsMetadata;
+}
+
+/**
+ * Stored Revenue Metrics
+ * Stored in: clinics/{clinicBranchId}/analytics/revenue/{period}
+ */
+export interface StoredRevenueMetrics extends RevenueMetrics {
+  metadata: AnalyticsMetadata;
+}
+
+/**
+ * Collection names for stored analytics
+ */
+export const ANALYTICS_COLLECTION = 'analytics';
+export const PRACTITIONER_ANALYTICS_SUBCOLLECTION = 'practitioners';
+export const PROCEDURE_ANALYTICS_SUBCOLLECTION = 'procedures';
+export const CLINIC_ANALYTICS_SUBCOLLECTION = 'clinic';
+export const DASHBOARD_ANALYTICS_SUBCOLLECTION = 'dashboard';
+export const TIME_EFFICIENCY_ANALYTICS_SUBCOLLECTION = 'time_efficiency';
+export const CANCELLATION_ANALYTICS_SUBCOLLECTION = 'cancellations';
+export const NO_SHOW_ANALYTICS_SUBCOLLECTION = 'no_shows';
+export const REVENUE_ANALYTICS_SUBCOLLECTION = 'revenue';
+
+/**
+ * Options for reading stored analytics
+ */
+export interface ReadStoredAnalyticsOptions {
+  /**
+   * Whether to use cached/pre-computed data
+   * @default true
+   */
+  useCache?: boolean;
+  /**
+   * Maximum age of cached data in hours before recalculating
+   * @default 12
+   */
+  maxCacheAgeHours?: number;
+  /**
+   * Period to read
+   * @default 'all_time'
+   */
+  period?: AnalyticsPeriod;
+  /**
+   * Date range for the period (calculated if not provided)
+   */
+  dateRange?: AnalyticsDateRange;
+  /**
+   * Clinic branch ID (required for reading stored analytics)
+   */
+  clinicBranchId?: string;
+}
+

package/src/types/index.ts

@@ -40,5 +40,8 @@ export * from "./profile";
 // Reviews types
 export * from "./reviews";
 
+// Analytics types
+export * from "./analytics";
+
 // User types
 export * from "./user";