@blackcode_sa/metaestetics-api 1.15.16 → 1.15.17-staging.0

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

@@ -1,173 +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;
-  }>;
-}
-
+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

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

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

@@ -1,137 +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;
-}
-
+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;
+}
+