@umituz/web-dashboard 3.2.2 → 4.0.0

package/src/domains/analytics/hooks/useAnalytics.ts

@@ -1,178 +1,183 @@
 /**
- * useAnalytics Hook
+ * useAnalytics
  *
- * Core analytics hook for fetching and managing analytics data
+ * Pure state + side-effect container. Mock data, commented-out
+ * fetch calls, and Math.random()-driven time series are gone.
+ * All persistence is delegated to the injected `apiClient`.
  */
 
-import { useState, useCallback, useEffect } from "react";
+import { useState, useCallback, useEffect, useMemo, useRef } from "react";
 import type {
   KPIs,
   TimeSeriesData,
-  ChartConfig,
   DateRangeValue,
   AnalyticsExportOptions,
 } from "../types/analytics";
-import { createKPI } from "../utils/analytics";
 
-interface UseAnalyticsOptions {
-  /** Analytics API base URL */
-  apiUrl?: string;
-  /** Initial date range */
+/**
+ * API client contract. Replace `loadAnalytics` with a real fetch wrapper
+ * and `exportAnalytics` with a server-side exporter.
+ */
+export interface AnalyticsApiClient {
+  loadAnalytics: (range: DateRangeValue) => Promise<AnalyticsDataPayload>;
+  exportAnalytics: (payload: AnalyticsDataPayload, options: AnalyticsExportOptions) => Promise<Blob>;
+}
+
+export interface AnalyticsDataPayload {
+  kpis: KPIs;
+  timeSeries: TimeSeriesData[];
+}
+
+export interface UseAnalyticsOptions {
   initialDateRange?: DateRangeValue;
   /** Auto-refresh interval in ms (0 to disable) */
   refreshInterval?: number;
+  apiClient: AnalyticsApiClient;
 }
 
-interface AnalyticsData {
-  /** KPI metrics */
+export interface UseAnalyticsReturn {
   kpis: KPIs;
-  /** Time series data */
   timeSeries: TimeSeriesData[];
-  /** Loading state */
   isLoading: boolean;
-  /** Error state */
   error: string | null;
+  dateRange: DateRangeValue;
+  updateDateRange: (range: DateRangeValue) => void;
+  refresh: () => Promise<void>;
+  exportData: (options: AnalyticsExportOptions) => Promise<void>;
 }
 
-/**
- * useAnalytics hook
- *
- * Manages analytics data fetching and state
- *
- * @param options - Hook options
- * @returns Analytics data and actions
- */
-export function useAnalytics(options: UseAnalyticsOptions = {}) {
-  const { apiUrl = "/api/analytics", initialDateRange, refreshInterval = 0 } = options;
+const DEFAULT_RANGE_DAYS = 30;
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
 
-  // State
-  const [dateRange, setDateRange] = useState<DateRangeValue>(
-    initialDateRange || {
-      from: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString().split("T")[0],
-      to: new Date().toISOString().split("T")[0],
-      preset: "Last 30 Days",
-    }
-  );
-  const [data, setData] = useState<AnalyticsData>({
-    kpis: {
-      downloads: { current: 0, previous: 0, growth: 0 },
-      engagement: { current: 0, previous: 0, growth: 0 },
-      users: { current: 0, previous: 0, growth: 0 },
-      revenue: { current: 0, previous: 0, growth: 0 },
-      retention: { current: 0, previous: 0, growth: 0 },
-    },
-    timeSeries: [],
-    isLoading: false,
-    error: null,
-  });
+const buildDefaultRange = (): DateRangeValue => {
+  const today = new Date();
+  const start = new Date(Date.now() - DEFAULT_RANGE_DAYS * MS_PER_DAY);
+  return {
+    from: start.toISOString().split("T")[0] as string,
+    to: today.toISOString().split("T")[0] as string,
+  };
+};
 
-  // Fetch analytics data
-  const fetchAnalytics = useCallback(async () => {
-    setData((prev) => ({ ...prev, isLoading: true, error: null }));
+const EMPTY_KPIS: KPIs = {
+  downloads: { current: 0, previous: 0, growth: 0 },
+  engagement: { current: 0, previous: 0, growth: 0 },
+  users: { current: 0, previous: 0, growth: 0 },
+  revenue: { current: 0, previous: 0, growth: 0 },
+  retention: { current: 0, previous: 0, growth: 0 },
+};
 
-    try {
-      // In production, call your analytics API
-      // const response = await fetch(`${apiUrl}?from=${dateRange.from}&to=${dateRange.to}`);
-      // const result = await response.json();
-
-      // Mock data for demo
-      const mockKPIs: KPIs = {
-        downloads: { current: 1250, previous: 1100, growth: 13.6 },
-        engagement: { current: 68.5, previous: 65.2, growth: 5.1 },
-        users: { current: 4500, previous: 4200, growth: 7.1 },
-        revenue: { current: 8950, previous: 7800, growth: 14.7 },
-        retention: { current: 72.3, previous: 69.8, growth: 3.6 },
-      };
-
-      const mockTimeSeries: TimeSeriesData[] = Array.from({ length: 30 }, (_, i) => {
-        const date = new Date();
-        date.setDate(date.getDate() - (29 - i));
-        return {
-          date: date.toISOString().split("T")[0],
-          downloads: Math.floor(1000 + Math.random() * 500),
-          engagement: 60 + Math.random() * 20,
-          revenue: Math.floor(7000 + Math.random() * 3000),
-          users: Math.floor(4000 + Math.random() * 1000),
-          retention: 65 + Math.random() * 15,
-        };
-      });
-
-      setData({
-        kpis: mockKPIs,
-        timeSeries: mockTimeSeries,
-        isLoading: false,
-        error: null,
-      });
-    } catch (err) {
-      const errorMessage = err instanceof Error ? err.message : "Failed to fetch analytics";
-      setData((prev) => ({
-        ...prev,
-        isLoading: false,
-        error: errorMessage,
-      }));
-    }
-  }, [apiUrl, dateRange]);
+const toErrorMessage = (err: unknown, fallback: string): string =>
+  err instanceof Error && err.message ? err.message : fallback;
 
-  // Update date range
-  const updateDateRange = useCallback((newDateRange: DateRangeValue) => {
-    setDateRange(newDateRange);
-  }, []);
+const toError = (err: unknown, fallback: string): Error =>
+  err instanceof Error ? err : new Error(fallback);
+
+export function useAnalytics(options: UseAnalyticsOptions): UseAnalyticsReturn {
+  const { initialDateRange, refreshInterval = 0, apiClient } = options;
 
-  // Export analytics data
-  const exportData = useCallback(async (options: AnalyticsExportOptions) => {
+  const [dateRange, setDateRange] = useState<DateRangeValue>(
+    initialDateRange ?? buildDefaultRange(),
+  );
+  const [kpis, setKpis] = useState<KPIs>(EMPTY_KPIS);
+  const [timeSeries, setTimeSeries] = useState<TimeSeriesData[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  /**
+   * Refs track the latest request so an in-flight call can't be
+   * overridden by a slower one (e.g. user changes the range while
+   * the previous fetch is still resolving).
+   */
+  const requestIdRef = useRef(0);
+
+  const refresh = useCallback(async () => {
+    const requestId = ++requestIdRef.current;
+    setIsLoading(true);
+    setError(null);
     try {
-      // In production, implement export API call
-      const exportData = {
-        dateRange,
-        kpis: data.kpis,
-        timeSeries: data.timeSeries,
-        format: options.format,
-      };
-
-      console.log("Exporting analytics:", exportData);
-
-      // Mock export
-      const blob = new Blob([JSON.stringify(exportData, null, 2)], {
-        type: options.format === "json" ? "application/json" : "text/plain",
-      });
-
-      const url = URL.createObjectURL(blob);
-      const link = document.createElement("a");
-      link.href = url;
-      link.download = options.filename || `analytics-${dateRange.from}-${dateRange.to}.${options.format}`;
-      document.body.appendChild(link);
-      link.click();
-      document.body.removeChild(link);
-      URL.revokeObjectURL(url);
+      const payload = await apiClient.loadAnalytics(dateRange);
+      if (requestIdRef.current === requestId) {
+        setKpis(payload.kpis);
+        setTimeSeries(payload.timeSeries);
+      }
     } catch (err) {
-      console.error("Export failed:", err);
-      throw err;
+      if (requestIdRef.current === requestId) {
+        setError(toErrorMessage(err, 'Failed to fetch analytics'));
+      }
+    } finally {
+      if (requestIdRef.current === requestId) {
+        setIsLoading(false);
+      }
     }
-  }, [dateRange, data]);
+  }, [apiClient, dateRange]);
 
-  // Refresh data
-  const refresh = useCallback(() => {
-    fetchAnalytics();
-  }, [fetchAnalytics]);
+  const updateDateRange = useCallback((range: DateRangeValue) => {
+    setDateRange(range);
+  }, []);
+
+  const exportData = useCallback(
+    async (exportOptions: AnalyticsExportOptions) => {
+      const payload: AnalyticsDataPayload = { kpis, timeSeries };
+      try {
+        const blob = await apiClient.exportAnalytics(payload, exportOptions);
+
+        const url = URL.createObjectURL(blob);
+        const link = document.createElement("a");
+        link.href = url;
+        link.download =
+          exportOptions.filename ?? `analytics-${dateRange.from}-${dateRange.to}.${exportOptions.format}`;
+        document.body.appendChild(link);
+        link.click();
+        document.body.removeChild(link);
+        URL.revokeObjectURL(url);
+      } catch (err) {
+        // Surface through the same error state as fetch failures and re-throw
+        // so callers that trigger the export programmatically can react.
+        setError(toErrorMessage(err, 'Failed to export analytics'));
+        throw toError(err, 'Failed to export analytics');
+      }
+    },
+    [apiClient, dateRange.from, dateRange.to, kpis, timeSeries],
+  );
 
-  // Fetch on mount and date range change
   useEffect(() => {
-    fetchAnalytics();
-  }, [fetchAnalytics]);
+    refresh();
+  }, [refresh]);
 
-  // Auto-refresh
   useEffect(() => {
     if (refreshInterval > 0) {
-      const interval = setInterval(fetchAnalytics, refreshInterval);
-      return () => clearInterval(interval);
+      const id = setInterval(refresh, refreshInterval);
+      return () => clearInterval(id);
     }
-  }, [fetchAnalytics, refreshInterval]);
+    return undefined;
+  }, [refresh, refreshInterval]);
+
+  return useMemo(
+    () => ({
+      kpis,
+      timeSeries,
+      isLoading,
+      error,
+      dateRange,
+      updateDateRange,
+      refresh,
+      exportData,
+    }),
+    [kpis, timeSeries, isLoading, error, dateRange, updateDateRange, refresh, exportData],
+  );
+}
 
-  return {
-    ...data,
-    dateRange,
-    updateDateRange,
-    refresh,
-    exportData,
+/**
+ * Convenience factory: returns a stub client that throws. Useful
+ * in Storybook / tests; the consumer must wire a real client
+ * before the hook is useful in production.
+ */
+export const createStubAnalyticsApiClient = (
+  overrides?: Partial<AnalyticsApiClient>,
+): AnalyticsApiClient => {
+  const notConfigured: AnalyticsApiClient = {
+    loadAnalytics: () => Promise.reject(new Error('AnalyticsApiClient not configured')),
+    exportAnalytics: () => Promise.reject(new Error('AnalyticsApiClient not configured')),
   };
-}
+  return { ...notConfigured, ...overrides };
+};

package/src/domains/analytics/index.ts

@@ -15,6 +15,13 @@ export {
 // Hooks
 export {
   useAnalytics,
+  createStubAnalyticsApiClient,
+} from "./hooks";
+export type {
+  AnalyticsApiClient,
+  AnalyticsDataPayload,
+  UseAnalyticsOptions,
+  UseAnalyticsReturn,
 } from "./hooks";
 
 // Utils
@@ -37,6 +44,7 @@ export {
   roundTo,
   generateColor,
   generateChartColors,
+  ANALYTICS_KEYS,
 } from "./utils";
 
 // Types
@@ -55,6 +63,9 @@ export type {
   MetricCardProps,
   AnalyticsCardProps,
   AnalyticsLayoutProps,
+  AnalyticsPeriod,
+  AnalyticsConfig,
+  MetricConfig,
   DateRangePreset,
   DateRangeValue,
   ExportFormat,

package/src/domains/analytics/services/AnalyticsEngineService.ts

@@ -60,22 +60,49 @@ export interface ActivityItem {
 }
 
 /**
- * Analytics Engine Service
- *
- * Singleton service for advanced analytics calculations
+ * Numeric metric keys supported by segment aggregation.
+ * Constrained to a string union to avoid `any` lookups at runtime.
  */
-export class AnalyticsEngineService {
-  private static instance: AnalyticsEngineService;
+type NumericUserMetric =
+  | 'session_duration'
+  | 'pages_per_session'
+  | 'bounce_rate'
+  | 'lifetime_value'
+  | 'last_login_days';
+
+const isUserMetric = (key: string): key is NumericUserMetric =>
+  [
+    'session_duration',
+    'pages_per_session',
+    'bounce_rate',
+    'lifetime_value',
+    'last_login_days',
+  ].includes(key);
 
-  private constructor() {}
+/**
+ * Safe numeric accessor for a UserData field.
+ * Returns 0 when the field is missing or not a number, instead of forcing a cast.
+ */
+const getNumericMetric = (user: UserData, key: NumericUserMetric): number => {
+  const value = user[key];
+  return typeof value === 'number' ? value : 0;
+};
 
-  public static getInstance(): AnalyticsEngineService {
-    if (!AnalyticsEngineService.instance) {
-      AnalyticsEngineService.instance = new AnalyticsEngineService();
-    }
-    return AnalyticsEngineService.instance;
-  }
+/**
+ * Segmentation thresholds (in days since last login).
+ */
+const SEGMENT_THRESHOLDS = {
+  activeDays: 7,
+  moderateDays: 30,
+} as const;
 
+/**
+ * Analytics Engine Service
+ *
+ * Pure-functional service for advanced analytics calculations.
+ * Stateless and testable: instantiate with `new AnalyticsEngineService()`.
+ */
+export class AnalyticsEngineService {
   /**
    * Calculate cohort retention analysis
    *
@@ -103,9 +130,13 @@ export class AnalyticsEngineService {
       const retention: number[] = [];
       for (let month = 0; month < 12; month++) {
         const activeUsersCount = users.filter((user) => {
-          if (!user.last_activity) return false;
-          const signupDate = new Date(user.signup_date!);
-          const targetDate = new Date(signupDate.getFullYear(), signupDate.getMonth() + month, 1);
+          if (!user.last_activity || !user.signup_date) return false;
+          const signupDate = new Date(user.signup_date);
+          const targetDate = new Date(
+            signupDate.getFullYear(),
+            signupDate.getMonth() + month,
+            1,
+          );
           return new Date(user.last_activity) >= targetDate;
         }).length;
 
@@ -116,7 +147,9 @@ export class AnalyticsEngineService {
         cohort,
         size: users.length,
         retention,
-        averageRetention: retention.reduce((a, b) => a + b, 0) / retention.length,
+        averageRetention: retention.length === 0
+          ? 0
+          : retention.reduce((a, b) => a + b, 0) / retention.length,
       });
     });
 
@@ -143,7 +176,7 @@ export class AnalyticsEngineService {
       const path = paths.get(pathKey);
       if (path) {
         path.count++;
-        path.value += conversion.value || 0;
+        path.value += conversion.value ?? 0;
         totalConversions++;
       }
     });
@@ -154,7 +187,9 @@ export class AnalyticsEngineService {
         conversions: path.count,
         value: path.value,
         abandonmentRate:
-          totalConversions > 0 ? ((totalConversions - path.count) / totalConversions) * 100 : 0,
+          totalConversions > 0
+            ? ((totalConversions - path.count) / totalConversions) * 100
+            : 0,
       }))
       .sort((a, b) => b.conversions - a.conversions);
   }
@@ -169,15 +204,16 @@ export class AnalyticsEngineService {
   public calculateFunnel(data: FunnelItem[], steps: string[]): FunnelData {
     let previousCount = data.length;
     const funnelSteps = steps.map((step, index) => {
-      const stepCount = data.filter((item) => item[step]).length;
+      const stepCount = data.filter((item) => Boolean(item[step])).length;
       const conversionRate =
         index === 0 ? 100 : previousCount > 0 ? (stepCount / previousCount) * 100 : 0;
       previousCount = stepCount;
 
-      const stepData = data.filter((item) => item[step]);
+      const stepData = data.filter((item) => Boolean(item[step]));
       const avgTime =
         stepData.length > 0
-          ? stepData.reduce((sum, item) => sum + (item.time_spent || 0), 0) / stepData.length
+          ? stepData.reduce((sum, item) => sum + (item.time_spent ?? 0), 0) /
+            stepData.length
           : 0;
 
       return {
@@ -193,7 +229,7 @@ export class AnalyticsEngineService {
       title: 'Conversion Funnel',
       steps: funnelSteps,
       totalUsers: data.length,
-      finalConversion: funnelSteps[funnelSteps.length - 1]?.conversionRate || 0,
+      finalConversion: funnelSteps[funnelSteps.length - 1]?.conversionRate ?? 0,
     };
   }
 
@@ -201,17 +237,19 @@ export class AnalyticsEngineService {
    * Generate activity heatmap
    *
    * @param data - Activity data with timestamps
-   * @returns Heatmap data by day and hour
+   * @returns Heatmap data by day and hour (Monday-first)
    */
   public generateActivityHeatmap(data: ActivityItem[]): HeatmapData[] {
     const heatmap: HeatmapData[] = [];
-    const days = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'];
+    const days = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'] as const;
 
     for (let day = 0; day < 7; day++) {
       for (let hour = 0; hour < 24; hour++) {
         const count = data.filter((item) => {
           const d = new Date(item.timestamp);
-          return d.getDay() === day && d.getHours() === hour;
+          // getDay() is Sunday-based (0=Sun..6=Sat); convert to Monday-first index
+          const mondayFirst = (d.getDay() + 6) % 7;
+          return mondayFirst === day && d.getHours() === hour;
         }).length;
 
         heatmap.push({ day: days[day], hour, value: count });
@@ -230,39 +268,46 @@ export class AnalyticsEngineService {
     const defineSegment = (
       name: string,
       filter: (u: UserData) => boolean,
-      chars: string[]
+      chars: string[],
     ) => {
       const users = data.filter(filter);
-      const avg = (field: string) =>
-        users.length === 0
-          ? 0
-          : users.reduce((s, i) => s + ((i as any)[field] || 0), 0) / users.length;
+      const safeAvg = (field: string): number => {
+        if (users.length === 0) return 0;
+        if (!isUserMetric(field)) return 0;
+        return users.reduce((sum, user) => sum + getNumericMetric(user, field), 0) /
+          users.length;
+      };
 
       return {
         name,
         count: users.length,
-        percentage: (users.length / data.length) * 100,
+        percentage: data.length === 0 ? 0 : (users.length / data.length) * 100,
         characteristics: chars,
         behavior: {
-          avgSessionDuration: avg('session_duration'),
-          pagesPerSession: avg('pages_per_session'),
-          bounceRate: avg('bounce_rate'),
+          avgSessionDuration: safeAvg('session_duration'),
+          pagesPerSession: safeAvg('pages_per_session'),
+          bounceRate: safeAvg('bounce_rate'),
         },
       };
     };
 
     return [
-      defineSegment('Active', (u) => u.last_login_days! <= 7, [
-        'Recent login',
-        'High engagement',
-      ]),
-      defineSegment('Moderate', (u) => u.last_login_days! > 7 && u.last_login_days! <= 30, [
-        'Occasional login',
-      ]),
-      defineSegment('Inactive', (u) => u.last_login_days! > 30, [
-        'Churn risk',
-        'Low activity',
-      ]),
+      defineSegment('Active', (u) => {
+        const days = u.last_login_days;
+        return typeof days === 'number' && days <= SEGMENT_THRESHOLDS.activeDays;
+      }, ['Recent login', 'High engagement']),
+      defineSegment('Moderate', (u) => {
+        const days = u.last_login_days;
+        return (
+          typeof days === 'number' &&
+          days > SEGMENT_THRESHOLDS.activeDays &&
+          days <= SEGMENT_THRESHOLDS.moderateDays
+        );
+      }, ['Occasional login']),
+      defineSegment('Inactive', (u) => {
+        const days = u.last_login_days;
+        return typeof days === 'number' && days > SEGMENT_THRESHOLDS.moderateDays;
+      }, ['Churn risk', 'Low activity']),
     ];
   }
 
@@ -275,10 +320,11 @@ export class AnalyticsEngineService {
    */
   public predictUserBehavior(
     user: UserData,
-    historicalData: UserData[]
+    historicalData: UserData[],
   ): UserBehaviorPrediction {
     const similarUsers = historicalData.filter(
-      (u) => Math.abs((u.age || 0) - (user.age || 0)) < 5 && u.location === user.location
+      (u) =>
+        Math.abs((u.age ?? 0) - (user.age ?? 0)) < 5 && u.location === user.location,
     );
 
     if (similarUsers.length === 0) {
@@ -291,17 +337,18 @@ export class AnalyticsEngineService {
     }
 
     const churnCount = similarUsers.filter((u) => u.churned).length;
-    const totalLTV = similarUsers.reduce((s, u) => s + (u.lifetime_value || 0), 0);
+    const totalLTV = similarUsers.reduce((s, u) => s + (u.lifetime_value ?? 0), 0);
 
-    // Predict next action based on frequency in similar users
-    const actions = similarUsers.map((u) => u.last_action).filter(Boolean) as string[];
-    const actionCounts = actions.reduce((c: Record<string, number>, a) => {
-      c[a] = (c[a] || 0) + 1;
+    const actions = similarUsers
+      .map((u) => u.last_action)
+      .filter((action): action is string => Boolean(action));
+    const actionCounts = actions.reduce<Record<string, number>>((c, a) => {
+      c[a] = (c[a] ?? 0) + 1;
       return c;
     }, {});
     const nextAction = Object.keys(actionCounts).reduce(
       (a, b) => (actionCounts[a] > actionCounts[b] ? a : b),
-      'unknown'
+      'unknown',
     );
 
     return {
@@ -314,6 +361,7 @@ export class AnalyticsEngineService {
 }
 
 /**
- * Singleton instance
+ * Default instance for convenience.
+ * The class is also exported so consumers can instantiate a fresh one for tests.
  */
-export const analyticsEngineService = AnalyticsEngineService.getInstance();
+export const analyticsEngineService = new AnalyticsEngineService();