@blackcode_sa/metaestetics-api 1.13.4 → 1.13.5

package/src/services/analytics/utils/stored-analytics.utils.ts

@@ -1,347 +1,347 @@
-import { Firestore, Timestamp, doc, getDoc } from 'firebase/firestore';
-import {
-  ANALYTICS_COLLECTION,
-  PRACTITIONER_ANALYTICS_SUBCOLLECTION,
-  PROCEDURE_ANALYTICS_SUBCOLLECTION,
-  CLINIC_ANALYTICS_SUBCOLLECTION,
-  DASHBOARD_ANALYTICS_SUBCOLLECTION,
-  TIME_EFFICIENCY_ANALYTICS_SUBCOLLECTION,
-  CANCELLATION_ANALYTICS_SUBCOLLECTION,
-  NO_SHOW_ANALYTICS_SUBCOLLECTION,
-  REVENUE_ANALYTICS_SUBCOLLECTION,
-  AnalyticsPeriod,
-  ReadStoredAnalyticsOptions,
-  StoredPractitionerAnalytics,
-  StoredProcedureAnalytics,
-  StoredClinicAnalytics,
-  StoredDashboardAnalytics,
-  StoredTimeEfficiencyMetrics,
-  StoredCancellationMetrics,
-  StoredNoShowMetrics,
-  StoredRevenueMetrics,
-} from '../../../types/analytics';
-import { CLINICS_COLLECTION } from '../../../types/clinic';
-
-/**
- * Checks if stored analytics data is fresh enough to use
- *
- * @param computedAt - Timestamp when analytics were computed
- * @param maxAgeHours - Maximum age in hours
- * @returns True if data is fresh enough
- */
-export function isAnalyticsDataFresh(computedAt: Timestamp, maxAgeHours: number): boolean {
-  const now = Timestamp.now();
-  const ageMs = now.toMillis() - computedAt.toMillis();
-  const ageHours = ageMs / (1000 * 60 * 60);
-  return ageHours <= maxAgeHours;
-}
-
-/**
- * Reads stored analytics document
- *
- * @param db - Firestore instance
- * @param clinicBranchId - Clinic branch ID
- * @param subcollection - Analytics subcollection name
- * @param documentId - Document ID
- * @param period - Analytics period
- * @returns Stored analytics document or null
- */
-async function readStoredAnalytics<T>(
-  db: Firestore,
-  clinicBranchId: string,
-  subcollection: string,
-  documentId: string,
-  period: AnalyticsPeriod,
-): Promise<T | null> {
-  try {
-    const docRef = doc(
-      db,
-      CLINICS_COLLECTION,
-      clinicBranchId,
-      ANALYTICS_COLLECTION,
-      subcollection,
-      period,
-      documentId,
-    );
-
-    const docSnap = await getDoc(docRef);
-    if (!docSnap.exists()) {
-      return null;
-    }
-
-    return docSnap.data() as T;
-  } catch (error) {
-    console.error(`[StoredAnalytics] Error reading ${subcollection}/${period}/${documentId}:`, error);
-    return null;
-  }
-}
-
-/**
- * Reads stored practitioner analytics
- */
-export async function readStoredPractitionerAnalytics(
-  db: Firestore,
-  clinicBranchId: string,
-  practitionerId: string,
-  options: ReadStoredAnalyticsOptions = {},
-): Promise<StoredPractitionerAnalytics | null> {
-  const { useCache = true, maxCacheAgeHours = 12, period = 'all_time' } = options;
-
-  if (!useCache) {
-    return null;
-  }
-
-  const stored = await readStoredAnalytics<StoredPractitionerAnalytics>(
-    db,
-    clinicBranchId,
-    PRACTITIONER_ANALYTICS_SUBCOLLECTION,
-    practitionerId,
-    period,
-  );
-
-  if (!stored) {
-    return null;
-  }
-
-  // Check if data is fresh enough
-  if (!isAnalyticsDataFresh(stored.metadata.computedAt, maxCacheAgeHours)) {
-    return null;
-  }
-
-  return stored;
-}
-
-/**
- * Reads stored procedure analytics
- */
-export async function readStoredProcedureAnalytics(
-  db: Firestore,
-  clinicBranchId: string,
-  procedureId: string,
-  options: ReadStoredAnalyticsOptions = {},
-): Promise<StoredProcedureAnalytics | null> {
-  const { useCache = true, maxCacheAgeHours = 12, period = 'all_time' } = options;
-
-  if (!useCache) {
-    return null;
-  }
-
-  const stored = await readStoredAnalytics<StoredProcedureAnalytics>(
-    db,
-    clinicBranchId,
-    PROCEDURE_ANALYTICS_SUBCOLLECTION,
-    procedureId,
-    period,
-  );
-
-  if (!stored) {
-    return null;
-  }
-
-  if (!isAnalyticsDataFresh(stored.metadata.computedAt, maxCacheAgeHours)) {
-    return null;
-  }
-
-  return stored;
-}
-
-/**
- * Reads stored clinic analytics
- */
-export async function readStoredClinicAnalytics(
-  db: Firestore,
-  clinicBranchId: string,
-  options: ReadStoredAnalyticsOptions = {},
-): Promise<StoredClinicAnalytics | null> {
-  const { useCache = true, maxCacheAgeHours = 12, period = 'all_time' } = options;
-
-  if (!useCache) {
-    return null;
-  }
-
-  const stored = await readStoredAnalytics<StoredClinicAnalytics>(
-    db,
-    clinicBranchId,
-    CLINIC_ANALYTICS_SUBCOLLECTION,
-    'current',
-    period,
-  );
-
-  if (!stored) {
-    return null;
-  }
-
-  if (!isAnalyticsDataFresh(stored.metadata.computedAt, maxCacheAgeHours)) {
-    return null;
-  }
-
-  return stored;
-}
-
-/**
- * Reads stored dashboard analytics
- */
-export async function readStoredDashboardAnalytics(
-  db: Firestore,
-  clinicBranchId: string,
-  options: ReadStoredAnalyticsOptions = {},
-): Promise<StoredDashboardAnalytics | null> {
-  const { useCache = true, maxCacheAgeHours = 12, period = 'all_time' } = options;
-
-  if (!useCache) {
-    return null;
-  }
-
-  const stored = await readStoredAnalytics<StoredDashboardAnalytics>(
-    db,
-    clinicBranchId,
-    DASHBOARD_ANALYTICS_SUBCOLLECTION,
-    'current',
-    period,
-  );
-
-  if (!stored) {
-    return null;
-  }
-
-  if (!isAnalyticsDataFresh(stored.metadata.computedAt, maxCacheAgeHours)) {
-    return null;
-  }
-
-  return stored;
-}
-
-/**
- * Reads stored time efficiency metrics
- */
-export async function readStoredTimeEfficiencyMetrics(
-  db: Firestore,
-  clinicBranchId: string,
-  options: ReadStoredAnalyticsOptions = {},
-): Promise<StoredTimeEfficiencyMetrics | null> {
-  const { useCache = true, maxCacheAgeHours = 12, period = 'all_time' } = options;
-
-  if (!useCache) {
-    return null;
-  }
-
-  const stored = await readStoredAnalytics<StoredTimeEfficiencyMetrics>(
-    db,
-    clinicBranchId,
-    TIME_EFFICIENCY_ANALYTICS_SUBCOLLECTION,
-    'current',
-    period,
-  );
-
-  if (!stored) {
-    return null;
-  }
-
-  if (!isAnalyticsDataFresh(stored.metadata.computedAt, maxCacheAgeHours)) {
-    return null;
-  }
-
-  return stored;
-}
-
-/**
- * Reads stored revenue metrics
- */
-export async function readStoredRevenueMetrics(
-  db: Firestore,
-  clinicBranchId: string,
-  options: ReadStoredAnalyticsOptions = {},
-): Promise<StoredRevenueMetrics | null> {
-  const { useCache = true, maxCacheAgeHours = 12, period = 'all_time' } = options;
-
-  if (!useCache) {
-    return null;
-  }
-
-  const stored = await readStoredAnalytics<StoredRevenueMetrics>(
-    db,
-    clinicBranchId,
-    REVENUE_ANALYTICS_SUBCOLLECTION,
-    'current',
-    period,
-  );
-
-  if (!stored) {
-    return null;
-  }
-
-  if (!isAnalyticsDataFresh(stored.metadata.computedAt, maxCacheAgeHours)) {
-    return null;
-  }
-
-  return stored;
-}
-
-/**
- * Reads stored cancellation metrics
- */
-export async function readStoredCancellationMetrics(
-  db: Firestore,
-  clinicBranchId: string,
-  entityType: string,
-  options: ReadStoredAnalyticsOptions = {},
-): Promise<StoredCancellationMetrics | null> {
-  const { useCache = true, maxCacheAgeHours = 12, period = 'all_time' } = options;
-
-  if (!useCache) {
-    return null;
-  }
-
-  const stored = await readStoredAnalytics<StoredCancellationMetrics>(
-    db,
-    clinicBranchId,
-    CANCELLATION_ANALYTICS_SUBCOLLECTION,
-    entityType,
-    period,
-  );
-
-  if (!stored) {
-    return null;
-  }
-
-  if (!isAnalyticsDataFresh(stored.metadata.computedAt, maxCacheAgeHours)) {
-    return null;
-  }
-
-  return stored;
-}
-
-/**
- * Reads stored no-show metrics
- */
-export async function readStoredNoShowMetrics(
-  db: Firestore,
-  clinicBranchId: string,
-  entityType: string,
-  options: ReadStoredAnalyticsOptions = {},
-): Promise<StoredNoShowMetrics | null> {
-  const { useCache = true, maxCacheAgeHours = 12, period = 'all_time' } = options;
-
-  if (!useCache) {
-    return null;
-  }
-
-  const stored = await readStoredAnalytics<StoredNoShowMetrics>(
-    db,
-    clinicBranchId,
-    NO_SHOW_ANALYTICS_SUBCOLLECTION,
-    entityType,
-    period,
-  );
-
-  if (!stored) {
-    return null;
-  }
-
-  if (!isAnalyticsDataFresh(stored.metadata.computedAt, maxCacheAgeHours)) {
-    return null;
-  }
-
-  return stored;
-}
-
+import { Firestore, Timestamp, doc, getDoc } from 'firebase/firestore';
+import {
+  ANALYTICS_COLLECTION,
+  PRACTITIONER_ANALYTICS_SUBCOLLECTION,
+  PROCEDURE_ANALYTICS_SUBCOLLECTION,
+  CLINIC_ANALYTICS_SUBCOLLECTION,
+  DASHBOARD_ANALYTICS_SUBCOLLECTION,
+  TIME_EFFICIENCY_ANALYTICS_SUBCOLLECTION,
+  CANCELLATION_ANALYTICS_SUBCOLLECTION,
+  NO_SHOW_ANALYTICS_SUBCOLLECTION,
+  REVENUE_ANALYTICS_SUBCOLLECTION,
+  AnalyticsPeriod,
+  ReadStoredAnalyticsOptions,
+  StoredPractitionerAnalytics,
+  StoredProcedureAnalytics,
+  StoredClinicAnalytics,
+  StoredDashboardAnalytics,
+  StoredTimeEfficiencyMetrics,
+  StoredCancellationMetrics,
+  StoredNoShowMetrics,
+  StoredRevenueMetrics,
+} from '../../../types/analytics';
+import { CLINICS_COLLECTION } from '../../../types/clinic';
+
+/**
+ * Checks if stored analytics data is fresh enough to use
+ *
+ * @param computedAt - Timestamp when analytics were computed
+ * @param maxAgeHours - Maximum age in hours
+ * @returns True if data is fresh enough
+ */
+export function isAnalyticsDataFresh(computedAt: Timestamp, maxAgeHours: number): boolean {
+  const now = Timestamp.now();
+  const ageMs = now.toMillis() - computedAt.toMillis();
+  const ageHours = ageMs / (1000 * 60 * 60);
+  return ageHours <= maxAgeHours;
+}
+
+/**
+ * Reads stored analytics document
+ *
+ * @param db - Firestore instance
+ * @param clinicBranchId - Clinic branch ID
+ * @param subcollection - Analytics subcollection name
+ * @param documentId - Document ID
+ * @param period - Analytics period
+ * @returns Stored analytics document or null
+ */
+async function readStoredAnalytics<T>(
+  db: Firestore,
+  clinicBranchId: string,
+  subcollection: string,
+  documentId: string,
+  period: AnalyticsPeriod,
+): Promise<T | null> {
+  try {
+    const docRef = doc(
+      db,
+      CLINICS_COLLECTION,
+      clinicBranchId,
+      ANALYTICS_COLLECTION,
+      subcollection,
+      period,
+      documentId,
+    );
+
+    const docSnap = await getDoc(docRef);
+    if (!docSnap.exists()) {
+      return null;
+    }
+
+    return docSnap.data() as T;
+  } catch (error) {
+    console.error(`[StoredAnalytics] Error reading ${subcollection}/${period}/${documentId}:`, error);
+    return null;
+  }
+}
+
+/**
+ * Reads stored practitioner analytics
+ */
+export async function readStoredPractitionerAnalytics(
+  db: Firestore,
+  clinicBranchId: string,
+  practitionerId: string,
+  options: ReadStoredAnalyticsOptions = {},
+): Promise<StoredPractitionerAnalytics | null> {
+  const { useCache = true, maxCacheAgeHours = 12, period = 'all_time' } = options;
+
+  if (!useCache) {
+    return null;
+  }
+
+  const stored = await readStoredAnalytics<StoredPractitionerAnalytics>(
+    db,
+    clinicBranchId,
+    PRACTITIONER_ANALYTICS_SUBCOLLECTION,
+    practitionerId,
+    period,
+  );
+
+  if (!stored) {
+    return null;
+  }
+
+  // Check if data is fresh enough
+  if (!isAnalyticsDataFresh(stored.metadata.computedAt, maxCacheAgeHours)) {
+    return null;
+  }
+
+  return stored;
+}
+
+/**
+ * Reads stored procedure analytics
+ */
+export async function readStoredProcedureAnalytics(
+  db: Firestore,
+  clinicBranchId: string,
+  procedureId: string,
+  options: ReadStoredAnalyticsOptions = {},
+): Promise<StoredProcedureAnalytics | null> {
+  const { useCache = true, maxCacheAgeHours = 12, period = 'all_time' } = options;
+
+  if (!useCache) {
+    return null;
+  }
+
+  const stored = await readStoredAnalytics<StoredProcedureAnalytics>(
+    db,
+    clinicBranchId,
+    PROCEDURE_ANALYTICS_SUBCOLLECTION,
+    procedureId,
+    period,
+  );
+
+  if (!stored) {
+    return null;
+  }
+
+  if (!isAnalyticsDataFresh(stored.metadata.computedAt, maxCacheAgeHours)) {
+    return null;
+  }
+
+  return stored;
+}
+
+/**
+ * Reads stored clinic analytics
+ */
+export async function readStoredClinicAnalytics(
+  db: Firestore,
+  clinicBranchId: string,
+  options: ReadStoredAnalyticsOptions = {},
+): Promise<StoredClinicAnalytics | null> {
+  const { useCache = true, maxCacheAgeHours = 12, period = 'all_time' } = options;
+
+  if (!useCache) {
+    return null;
+  }
+
+  const stored = await readStoredAnalytics<StoredClinicAnalytics>(
+    db,
+    clinicBranchId,
+    CLINIC_ANALYTICS_SUBCOLLECTION,
+    'current',
+    period,
+  );
+
+  if (!stored) {
+    return null;
+  }
+
+  if (!isAnalyticsDataFresh(stored.metadata.computedAt, maxCacheAgeHours)) {
+    return null;
+  }
+
+  return stored;
+}
+
+/**
+ * Reads stored dashboard analytics
+ */
+export async function readStoredDashboardAnalytics(
+  db: Firestore,
+  clinicBranchId: string,
+  options: ReadStoredAnalyticsOptions = {},
+): Promise<StoredDashboardAnalytics | null> {
+  const { useCache = true, maxCacheAgeHours = 12, period = 'all_time' } = options;
+
+  if (!useCache) {
+    return null;
+  }
+
+  const stored = await readStoredAnalytics<StoredDashboardAnalytics>(
+    db,
+    clinicBranchId,
+    DASHBOARD_ANALYTICS_SUBCOLLECTION,
+    'current',
+    period,
+  );
+
+  if (!stored) {
+    return null;
+  }
+
+  if (!isAnalyticsDataFresh(stored.metadata.computedAt, maxCacheAgeHours)) {
+    return null;
+  }
+
+  return stored;
+}
+
+/**
+ * Reads stored time efficiency metrics
+ */
+export async function readStoredTimeEfficiencyMetrics(
+  db: Firestore,
+  clinicBranchId: string,
+  options: ReadStoredAnalyticsOptions = {},
+): Promise<StoredTimeEfficiencyMetrics | null> {
+  const { useCache = true, maxCacheAgeHours = 12, period = 'all_time' } = options;
+
+  if (!useCache) {
+    return null;
+  }
+
+  const stored = await readStoredAnalytics<StoredTimeEfficiencyMetrics>(
+    db,
+    clinicBranchId,
+    TIME_EFFICIENCY_ANALYTICS_SUBCOLLECTION,
+    'current',
+    period,
+  );
+
+  if (!stored) {
+    return null;
+  }
+
+  if (!isAnalyticsDataFresh(stored.metadata.computedAt, maxCacheAgeHours)) {
+    return null;
+  }
+
+  return stored;
+}
+
+/**
+ * Reads stored revenue metrics
+ */
+export async function readStoredRevenueMetrics(
+  db: Firestore,
+  clinicBranchId: string,
+  options: ReadStoredAnalyticsOptions = {},
+): Promise<StoredRevenueMetrics | null> {
+  const { useCache = true, maxCacheAgeHours = 12, period = 'all_time' } = options;
+
+  if (!useCache) {
+    return null;
+  }
+
+  const stored = await readStoredAnalytics<StoredRevenueMetrics>(
+    db,
+    clinicBranchId,
+    REVENUE_ANALYTICS_SUBCOLLECTION,
+    'current',
+    period,
+  );
+
+  if (!stored) {
+    return null;
+  }
+
+  if (!isAnalyticsDataFresh(stored.metadata.computedAt, maxCacheAgeHours)) {
+    return null;
+  }
+
+  return stored;
+}
+
+/**
+ * Reads stored cancellation metrics
+ */
+export async function readStoredCancellationMetrics(
+  db: Firestore,
+  clinicBranchId: string,
+  entityType: string,
+  options: ReadStoredAnalyticsOptions = {},
+): Promise<StoredCancellationMetrics | null> {
+  const { useCache = true, maxCacheAgeHours = 12, period = 'all_time' } = options;
+
+  if (!useCache) {
+    return null;
+  }
+
+  const stored = await readStoredAnalytics<StoredCancellationMetrics>(
+    db,
+    clinicBranchId,
+    CANCELLATION_ANALYTICS_SUBCOLLECTION,
+    entityType,
+    period,
+  );
+
+  if (!stored) {
+    return null;
+  }
+
+  if (!isAnalyticsDataFresh(stored.metadata.computedAt, maxCacheAgeHours)) {
+    return null;
+  }
+
+  return stored;
+}
+
+/**
+ * Reads stored no-show metrics
+ */
+export async function readStoredNoShowMetrics(
+  db: Firestore,
+  clinicBranchId: string,
+  entityType: string,
+  options: ReadStoredAnalyticsOptions = {},
+): Promise<StoredNoShowMetrics | null> {
+  const { useCache = true, maxCacheAgeHours = 12, period = 'all_time' } = options;
+
+  if (!useCache) {
+    return null;
+  }
+
+  const stored = await readStoredAnalytics<StoredNoShowMetrics>(
+    db,
+    clinicBranchId,
+    NO_SHOW_ANALYTICS_SUBCOLLECTION,
+    entityType,
+    period,
+  );
+
+  if (!stored) {
+    return null;
+  }
+
+  if (!isAnalyticsDataFresh(stored.metadata.computedAt, maxCacheAgeHours)) {
+    return null;
+  }
+
+  return stored;
+}
+