@akson/cortex-analytics-react 2.0.0 → 2.0.1

package/README.md

@@ -23,36 +23,37 @@ npm install @akson/cortex-analytics-react
 ### 1. Setup Provider
 
 ```tsx
-import React from 'react';
-import { AnalyticsProvider, type AnalyticsConfig } from '@akson/cortex-analytics-react';
-import { LEAD_GENERATION_EVENTS } from '@akson/cortex-api-shared/events';
+import React from "react";
+import {
+  AnalyticsProvider,
+  type AnalyticsConfig,
+} from "@akson/cortex-analytics-react";
+import { LEAD_GENERATION_EVENTS } from "@akson/cortex-utilities/events";
 
 const analyticsConfig: AnalyticsConfig = {
   platforms: {
     gtm: {
-      containerId: 'GTM-XXXXXXX',
+      containerId: "GTM-XXXXXXX",
       workspaceId: 40,
     },
     posthog: {
-      apiKey: 'phc_your_key',
-      host: 'https://app.posthog.com',
+      apiKey: "phc_your_key",
+      host: "https://app.posthog.com",
     },
     ga4: {
-      measurementId: 'G-XXXXXXXXXX',
+      measurementId: "G-XXXXXXXXXX",
     },
   },
   conversions: {
-    [LEAD_GENERATION_EVENTS.LEAD_FORM_SUBMITTED]: 'CONVERSION_LABEL_1',
-    [LEAD_GENERATION_EVENTS.LEAD_WHATSAPP_CONTACT]: 'CONVERSION_LABEL_2',
+    [LEAD_GENERATION_EVENTS.LEAD_FORM_SUBMITTED]: "CONVERSION_LABEL_1",
+    [LEAD_GENERATION_EVENTS.LEAD_WHATSAPP_CONTACT]: "CONVERSION_LABEL_2",
   },
-  debug: process.env.NODE_ENV === 'development',
+  debug: process.env.NODE_ENV === "development",
 };
 
 export default function App({ children }) {
   return (
-    <AnalyticsProvider config={analyticsConfig}>
-      {children}
-    </AnalyticsProvider>
+    <AnalyticsProvider config={analyticsConfig}>{children}</AnalyticsProvider>
   );
 }
 ```
@@ -60,8 +61,11 @@ export default function App({ children }) {
 ### 2. Use Analytics Hooks
 
 ```tsx
-import React from 'react';
-import { useAnalytics, LEAD_GENERATION_EVENTS } from '@akson/cortex-analytics-react';
+import React from "react";
+import {
+  useAnalytics,
+  LEAD_GENERATION_EVENTS,
+} from "@akson/cortex-analytics-react";
 
 export function ContactForm() {
   const analytics = useAnalytics();
@@ -69,97 +73,99 @@ export function ContactForm() {
   const handleSubmit = (formData: any) => {
     // Track standardized lead event
     analytics.track(LEAD_GENERATION_EVENTS.LEAD_FORM_SUBMITTED, {
-      form_type: 'contact',
-      source: 'header',
+      form_type: "contact",
+      source: "header",
       lead_score: 100,
     });
   };
 
-  return (
-    <form onSubmit={handleSubmit}>
-      {/* Your form */}
-    </form>
-  );
+  return <form onSubmit={handleSubmit}>{/* Your form */}</form>;
 }
 ```
 
 ## Available Hooks
 
 ### `useAnalytics()`
+
 Core analytics hook with full tracking capabilities.
 
 ```tsx
-import { useAnalytics } from '@akson/cortex-analytics-react';
+import { useAnalytics } from "@akson/cortex-analytics-react";
 
 function Component() {
   const analytics = useAnalytics();
-  
+
   // Basic tracking
-  analytics.track('custom_event', { property: 'value' });
-  analytics.trackPageView('/page', 'Page Title');
-  analytics.trackInteraction('button', 'click', 'header_cta');
-  
+  analytics.track("custom_event", { property: "value" });
+  analytics.trackPageView("/page", "Page Title");
+  analytics.trackInteraction("button", "click", "header_cta");
+
   // User identification
-  analytics.identify('user123', { email: 'user@example.com' });
-  analytics.sendUserData({ email: 'user@example.com', phone: '+1234567890' });
-  
+  analytics.identify("user123", { email: "user@example.com" });
+  analytics.sendUserData({ email: "user@example.com", phone: "+1234567890" });
+
   // Session utilities
   const sessionId = analytics.getSessionId();
   const funnelPath = analytics.getFunnelPath();
   const timeInFunnel = analytics.getTimeInFunnel();
-  
+
   return <div>...</div>;
 }
 ```
 
 ### `useFunnelTracking()`
+
 Specialized hook for funnel analysis.
 
 ```tsx
-import { useFunnelTracking } from '@akson/cortex-analytics-react';
+import { useFunnelTracking } from "@akson/cortex-analytics-react";
 
 function OrderForm() {
   const funnel = useFunnelTracking();
-  
+
   const handleStepComplete = (step: string) => {
     funnel.trackStage(step, {
       completion_time: 30,
-      source: 'organic',
+      source: "organic",
     });
   };
-  
+
   const handleAbandonment = () => {
-    funnel.trackAbandonment('step_2', 'form_error');
+    funnel.trackAbandonment("step_2", "form_error");
   };
-  
+
   const handleConversion = () => {
-    funnel.trackConversion('order', 149.90, {
-      product_type: 'custom_badge',
-      currency: 'CHF',
+    funnel.trackConversion("order", 149.9, {
+      product_type: "custom_badge",
+      currency: "CHF",
     });
   };
-  
+
   return <div>...</div>;
 }
 ```
 
 ### `useLeadTracking()`
+
 Hook for lead generation scenarios.
 
 ```tsx
-import { useLeadTracking, LEAD_GENERATION_EVENTS } from '@akson/cortex-analytics-react';
+import {
+  useLeadTracking,
+  LEAD_GENERATION_EVENTS,
+} from "@akson/cortex-analytics-react";
 
 function LeadCapture() {
   const lead = useLeadTracking();
-  
+
   const handleFormSubmit = (userData: any) => {
     // Track the lead event
     lead.trackLead(LEAD_GENERATION_EVENTS.LEAD_FORM_SUBMITTED, {
       lead_score: 100,
-      source: 'landing_page',
-      form_type: 'quote_request',
+      source: "landing_page",
+      form_type: "quote_request",
     });
-    
+
     // Send user data for enhanced conversions
     lead.sendUserData({
       email: userData.email,
@@ -167,33 +173,37 @@ function LeadCapture() {
       firstName: userData.firstName,
     });
   };
-  
+
   return <div>...</div>;
 }
 ```
 
 ### `useEcommerceTracking()`
+
 Hook for e-commerce events.
 
 ```tsx
-import { useEcommerceTracking, ECOMMERCE_EVENTS } from '@akson/cortex-analytics-react';
+import {
+  useEcommerceTracking,
+  ECOMMERCE_EVENTS,
+} from "@akson/cortex-analytics-react";
 
 function ProductPage() {
   const ecommerce = useEcommerceTracking();
-  
+
   const handlePurchase = (orderData: any) => {
     ecommerce.trackEcommerce(ECOMMERCE_EVENTS.PURCHASE, {
       value: orderData.total,
-      currency: 'CHF',
+      currency: "CHF",
       transaction_id: orderData.id,
-      items: orderData.items.map(item => ({
+      items: orderData.items.map((item) => ({
         item_name: item.name,
         price: item.price,
         quantity: item.quantity,
       })),
     });
   };
-  
+
   return <div>...</div>;
 }
 ```
@@ -243,24 +253,27 @@ interface FunnelConfig {
 
 ## Standardized Events
 
-The package uses standardized events from `@akson/cortex-api-shared`:
+The package uses standardized events from `@akson/cortex-utilities`:
 
 ```typescript
-import { LEAD_GENERATION_EVENTS, ECOMMERCE_EVENTS } from '@akson/cortex-analytics-react';
+import {
+  LEAD_GENERATION_EVENTS,
+  ECOMMERCE_EVENTS,
+} from "@akson/cortex-analytics-react";
 
 // Lead generation events (scored 1-100)
-LEAD_GENERATION_EVENTS.LEAD_PAGE_VIEW           // Score: 5
-LEAD_GENERATION_EVENTS.LEAD_CONTENT_VIEW        // Score: 15
-LEAD_GENERATION_EVENTS.LEAD_INQUIRY_STARTED     // Score: 40
-LEAD_GENERATION_EVENTS.LEAD_CONTACT_INFO        // Score: 60
-LEAD_GENERATION_EVENTS.LEAD_WHATSAPP_CONTACT    // Score: 85
-LEAD_GENERATION_EVENTS.LEAD_FORM_SUBMITTED      // Score: 100
+LEAD_GENERATION_EVENTS.LEAD_PAGE_VIEW; // Score: 5
+LEAD_GENERATION_EVENTS.LEAD_CONTENT_VIEW; // Score: 15
+LEAD_GENERATION_EVENTS.LEAD_INQUIRY_STARTED; // Score: 40
+LEAD_GENERATION_EVENTS.LEAD_CONTACT_INFO; // Score: 60
+LEAD_GENERATION_EVENTS.LEAD_WHATSAPP_CONTACT; // Score: 85
+LEAD_GENERATION_EVENTS.LEAD_FORM_SUBMITTED; // Score: 100
 
 // E-commerce events (with monetary values)
-ECOMMERCE_EVENTS.VIEW_ITEM        // Product views
-ECOMMERCE_EVENTS.ADD_TO_CART      // Cart additions  
-ECOMMERCE_EVENTS.BEGIN_CHECKOUT   // Checkout started
-ECOMMERCE_EVENTS.PURCHASE         // Completed transactions
+ECOMMERCE_EVENTS.VIEW_ITEM; // Product views
+ECOMMERCE_EVENTS.ADD_TO_CART; // Cart additions
+ECOMMERCE_EVENTS.BEGIN_CHECKOUT; // Checkout started
+ECOMMERCE_EVENTS.PURCHASE; // Completed transactions
 ```
 
 ## Migration from Landing Analytics
@@ -269,16 +282,19 @@ If migrating from the landing page analytics system:
 
 ```tsx
 // OLD: Landing-specific analytics
-import { Analytics, FUNNEL_STAGES } from '@/app/lib/analytics';
+import { Analytics, FUNNEL_STAGES } from "@/app/lib/analytics";
 
 // NEW: @akson/cortex-analytics-react
-import { useAnalytics, LEAD_GENERATION_EVENTS } from '@akson/cortex-analytics-react';
+import {
+  useAnalytics,
+  LEAD_GENERATION_EVENTS,
+} from "@akson/cortex-analytics-react";
 
 function Component() {
   const analytics = useAnalytics();
-  
+
   // OLD: Analytics.trackStage(FUNNEL_STAGES.FORM_SUBMITTED)
-  // NEW: 
+  // NEW:
   analytics.track(LEAD_GENERATION_EVENTS.LEAD_FORM_SUBMITTED, {
     lead_score: 100,
   });
@@ -317,14 +333,16 @@ The package follows a layered architecture:
 ## Dependencies
 
 ### Peer Dependencies
+
 - `react ^18.0.0`
 - `react-dom ^18.0.0`
 
 ### Dependencies
-- `@akson/cortex-api-shared` - Standardized event definitions
-- `@akson/cortex-api-gtm` - GTM API client
-- `@akson/cortex-api-posthog` - PostHog API client
+
+- `@akson/cortex-utilities` - Standardized event definitions
+- `@akson/cortex-gtm` - GTM API client
+- `@akson/cortex-posthog` - PostHog API client
 
 ## License
 
-MIT
+MIT

package/dist/index.d.mts

@@ -0,0 +1,304 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+export { ECOMMERCE_EVENTS, LEAD_GENERATION_EVENTS, LEAD_SCORES } from '@akson/cortex-utilities';
+
+/**
+ * @akson/cortex-analytics-react - Type Definitions
+ * Reusable types for analytics tracking across React applications
+ */
+
+/**
+ * Analytics configuration for projects
+ */
+interface AnalyticsConfig {
+    platforms: {
+        gtm?: {
+            containerId: string;
+            workspaceId?: number;
+            publicId?: string;
+        };
+        posthog?: {
+            apiKey: string;
+            host?: string;
+        };
+        ga4?: {
+            measurementId: string;
+        };
+        googleAds?: {
+            accountId: string;
+        };
+        meta?: {
+            pixelId: string;
+        };
+    };
+    conversions?: Record<string, string>;
+    funnel?: FunnelConfig;
+    debug?: boolean;
+    enableEnhancedConversions?: boolean;
+}
+/**
+ * Funnel configuration
+ */
+interface FunnelConfig {
+    stages?: Record<string, string[]>;
+    scoring?: (stage: string) => number;
+    abandonmentTracking?: boolean;
+    sessionTimeout?: number;
+}
+/**
+ * Event data for tracking
+ */
+interface EventData {
+    [key: string]: any;
+    event_category?: string;
+    event_label?: string;
+    event_value?: number;
+    standardized_event?: boolean;
+    timestamp?: string;
+    sessionId?: string;
+}
+/**
+ * Lead event data
+ */
+interface LeadEventData extends EventData {
+    lead_score: number;
+    funnel_stage?: string;
+    contact_method?: string;
+    source?: string;
+    language?: string;
+    device?: "mobile" | "desktop" | "tablet";
+}
+/**
+ * E-commerce event data
+ */
+interface EcommerceEventData extends EventData {
+    value: number;
+    currency: string;
+    transaction_id?: string;
+    items?: Array<{
+        item_id?: string;
+        item_name: string;
+        price: number;
+        quantity?: number;
+    }>;
+}
+/**
+ * Funnel stage data
+ */
+interface FunnelStageData {
+    stage: string;
+    previousStage?: string;
+    timeOnStage?: number;
+    totalTimeInFunnel?: number;
+    experimentVariants?: Record<string, string>;
+    formData?: FormData;
+    scrollData?: ScrollData;
+    performanceData?: PerformanceData;
+    source?: string;
+    language?: string;
+    device?: "mobile" | "desktop" | "tablet";
+    sessionId?: string;
+    userAgent?: string;
+    viewport?: string;
+    screenResolution?: string;
+}
+/**
+ * Form tracking data
+ */
+interface FormData {
+    step?: number;
+    stepName?: string;
+    fieldsCompleted?: number;
+    totalFields?: number;
+    completionPercentage?: number;
+    filledFields?: string[];
+    emptyFields?: string[];
+}
+/**
+ * Scroll tracking data
+ */
+interface ScrollData {
+    maxScrollPercent?: number;
+    timeToMaxScroll?: number;
+}
+/**
+ * Performance tracking data
+ */
+interface PerformanceData {
+    pageLoadTime?: number;
+    timeToInteraction?: number;
+    dns?: number;
+    tcp?: number;
+    ttfb?: number;
+}
+/**
+ * User data for enhanced conversions
+ */
+interface UserData {
+    email?: string;
+    phone?: string;
+    firstName?: string;
+    lastName?: string;
+    street?: string;
+    city?: string;
+    postalCode?: string;
+    country?: string;
+}
+/**
+ * Analytics context value
+ */
+interface AnalyticsContextValue {
+    config: AnalyticsConfig;
+    isReady: boolean;
+    track: (event: string, properties?: EventData) => void;
+    trackPageView: (pagePath: string, pageTitle?: string) => void;
+    trackInteraction: (category: string, action: string, label?: string, value?: number) => void;
+    trackLead: (event: string, data?: Partial<LeadEventData>) => void;
+    trackEcommerce: (event: string, data: Partial<EcommerceEventData>) => void;
+    trackFunnelStage: (stage: string, data?: Partial<FunnelStageData>) => void;
+    trackFunnelAbandonment: (lastStage: string, reason?: string, data?: Record<string, any>) => void;
+    trackFunnelConversion: (type: string, value?: number, data?: Record<string, any>) => void;
+    trackExperiment: (experimentName: string, variant: string, userId?: string) => void;
+    trackFeatureFlag: (flagName: string, value: boolean | string, userId?: string) => void;
+    identify: (userId: string, traits?: Record<string, any>) => void;
+    sendUserData: (userData: UserData) => void;
+    getSessionId: () => string;
+    getFunnelPath: () => string[];
+    getTimeInFunnel: () => number;
+    clearSession: () => void;
+}
+/**
+ * Storage utility functions
+ */
+interface StorageUtils {
+    safeGetStorage: (storageType: "localStorage" | "sessionStorage", key: string) => string | null;
+    safeSetStorage: (storageType: "localStorage" | "sessionStorage", key: string, value: string) => void;
+    safeRemoveStorage: (storageType: "localStorage" | "sessionStorage", key: string) => void;
+}
+/**
+ * Platform adapters interface
+ */
+interface PlatformAdapter {
+    isReady(): boolean;
+    track(event: string, properties?: Record<string, any>): void;
+    identify?(userId: string, traits?: Record<string, any>): void;
+    reset?(): void;
+}
+/**
+ * GTM adapter interface
+ */
+interface GTMAdapter extends PlatformAdapter {
+    dataLayer: any[];
+}
+/**
+ * PostHog adapter interface
+ */
+interface PostHogAdapter extends PlatformAdapter {
+    posthog: any;
+}
+
+declare const AnalyticsContext: React.Context<AnalyticsContextValue | null>;
+interface AnalyticsProviderProps {
+    config: AnalyticsConfig;
+    children: React.ReactNode;
+}
+declare function AnalyticsProvider({ config, children, }: AnalyticsProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Hook to access analytics functionality
+ * @throws Error if used outside of AnalyticsProvider
+ */
+declare function useAnalytics(): AnalyticsContextValue;
+/**
+ * Hook for simplified tracking
+ */
+declare function useTrack(): {
+    track: (event: string, properties?: EventData) => void;
+    isReady: boolean;
+};
+/**
+ * Hook for funnel tracking
+ */
+declare function useFunnelTracking(): {
+    trackStage: (stage: string, data?: Partial<FunnelStageData>) => void;
+    trackAbandonment: (lastStage: string, reason?: string, data?: Record<string, any>) => void;
+    trackConversion: (type: string, value?: number, data?: Record<string, any>) => void;
+    getFunnelPath: () => string[];
+    getTimeInFunnel: () => number;
+    clearSession: () => void;
+    isReady: boolean;
+};
+/**
+ * Hook for lead tracking
+ */
+declare function useLeadTracking(): {
+    trackLead: (event: string, data?: Partial<LeadEventData>) => void;
+    sendUserData: (userData: UserData) => void;
+    isReady: boolean;
+};
+/**
+ * Hook for e-commerce tracking
+ */
+declare function useEcommerceTracking(): {
+    trackEcommerce: (event: string, data: Partial<EcommerceEventData>) => void;
+    isReady: boolean;
+};
+/**
+ * Hook for experiment tracking
+ */
+declare function useExperimentTracking(): {
+    trackExperiment: (experimentName: string, variant: string, userId?: string) => void;
+    trackFeatureFlag: (flagName: string, value: boolean | string, userId?: string) => void;
+    isReady: boolean;
+};
+
+/**
+ * Get or create session ID
+ */
+declare function getSessionId(): string;
+/**
+ * Get funnel path
+ */
+declare function getFunnelPath(): string[];
+/**
+ * Get time in funnel (seconds)
+ */
+declare function getTimeInFunnel(): number;
+/**
+ * Clear session data
+ */
+declare function clearSession(): void;
+/**
+ * Get device type based on viewport
+ */
+declare function getDeviceType(): 'mobile' | 'desktop' | 'tablet';
+/**
+ * Get performance data
+ */
+declare function getPerformanceData(): {
+    pageLoadTime: number;
+    timeToInteraction: number;
+    dns: number;
+    tcp: number;
+    ttfb: number;
+} | undefined;
+
+/**
+ * Safe storage utilities for browser environments
+ * Handles storage access errors gracefully
+ */
+
+/**
+ * Safely get value from storage
+ */
+declare const safeGetStorage: StorageUtils['safeGetStorage'];
+/**
+ * Safely set value in storage
+ */
+declare const safeSetStorage: StorageUtils['safeSetStorage'];
+/**
+ * Safely remove value from storage
+ */
+declare const safeRemoveStorage: StorageUtils['safeRemoveStorage'];
+
+export { type AnalyticsConfig, AnalyticsContext, type AnalyticsContextValue, AnalyticsProvider, type EcommerceEventData, type EventData, type FormData, type FunnelConfig, type FunnelStageData, type GTMAdapter, type LeadEventData, type PerformanceData, type PlatformAdapter, type PostHogAdapter, type ScrollData, type UserData, clearSession, getDeviceType, getFunnelPath, getPerformanceData, getSessionId, getTimeInFunnel, safeGetStorage, safeRemoveStorage, safeSetStorage, useAnalytics, useEcommerceTracking, useExperimentTracking, useFunnelTracking, useLeadTracking, useTrack };