@od-oneapp/analytics 2026.1.1301

package/src/client/manager.ts

@@ -0,0 +1,71 @@
+/**
+ * @fileoverview Client Analytics Manager
+ *
+ * Client-side analytics manager with static provider registry. Provides
+ * factory functions for creating client analytics instances with support
+ * for multiple providers (Console, HTTP, Segment, Vercel).
+ *
+ * **Providers Supported**:
+ * - `console`: Console logging provider (development/debugging)
+ * - `http`: HTTP provider for remote ingestion (oneapp-api)
+ * - `segment`: Segment.io analytics provider
+ * - `vercel`: Vercel Analytics provider
+ *
+ * @module @od-oneapp/analytics/client/manager
+ */
+
+import { SegmentClientProvider } from '@integrations/segment/analytics-provider/client';
+import { VercelClientProvider } from '@integrations/vercel/analytics-provider/client';
+
+import { ConsoleProvider } from '../providers/console/client';
+import { HttpClientProvider } from '../providers/http/client';
+import { createAnalyticsManager } from '../shared/utils/manager';
+
+import type { AnalyticsConfig, AnalyticsManager, ProviderRegistry } from '../shared/types/types';
+
+// Static provider registry for client environments
+const CLIENT_PROVIDERS: ProviderRegistry = {
+  console: config => new ConsoleProvider(config),
+  http: config => new HttpClientProvider(config),
+  segment: config => new SegmentClientProvider(config),
+  vercel: config => new VercelClientProvider(config),
+};
+
+/**
+ * Create and initialize a client analytics instance
+ * This is the primary way to create analytics for client-side applications
+ *
+ * @example
+ * ```typescript
+ * const analytics = await createClientAnalytics({
+ *   providers: {
+ *     http: { endpoint: '/api/v1/ingest' },
+ *   },
+ * });
+ * await analytics.track('Button Clicked', { variant: 'primary' });
+ * ```
+ * @param config - Analytics configuration including providers and settings
+ * @returns Promise resolving to initialized analytics manager
+ */
+export async function createClientAnalytics(config: AnalyticsConfig): Promise<AnalyticsManager> {
+  const manager = createAnalyticsManager(config, CLIENT_PROVIDERS);
+  await manager.initialize();
+  return manager;
+}
+
+/**
+ * Create a client analytics instance without initializing
+ * Useful when you need to control initialization timing
+ *
+ * @example
+ * ```typescript
+ * const analytics = createClientAnalyticsUninitialized(config);
+ * // later inside a lazy effect
+ * await analytics.initialize();
+ * ```
+ * @param config - Analytics configuration including providers and settings
+ * @returns Uninitialized analytics manager instance
+ */
+export function createClientAnalyticsUninitialized(config: AnalyticsConfig): AnalyticsManager {
+  return createAnalyticsManager(config, CLIENT_PROVIDERS);
+}

package/src/client/next/components.tsx

@@ -0,0 +1,270 @@
+/**
+ * @fileoverview Next.js Client Components for Analytics
+ *
+ * React components for integrating analytics into Next.js applications.
+ * Provides provider components, tracked UI elements, and higher-order
+ * components for automatic event tracking.
+ *
+ * **Components**:
+ * - `AnalyticsProvider`: Provider component for App Router
+ * - `TrackedButton`: Button component with automatic click tracking
+ * - `TrackedLink`: Link component with automatic click tracking
+ * - `withViewTracking`: HOC for tracking component views
+ *
+ * **Note**: This file uses Next.js hooks. For framework-agnostic components,
+ * use the base components or accept navigation functions as parameters.
+ *
+ * @module @od-oneapp/analytics/client/next/components
+ */
+
+'use client';
+
+import { useCallback, useEffect, useRef } from 'react';
+
+import type { Route } from 'next';
+
+import { createClientObservability } from '@od-oneapp/observability/client/next';
+import { useRouter } from 'next/navigation';
+
+import { usePageTracking, useTrackEvent } from './hooks';
+import { createNextJSClientAnalytics } from './manager';
+
+import type { AnalyticsConfig, AnalyticsManager, Properties } from '../../shared/types/types';
+import type { ObservabilityClient } from '@od-oneapp/observability/client/next';
+
+// Global analytics instance
+let globalAnalytics: AnalyticsManager | null = null;
+
+// Global logger instance (from @od-oneapp/observability)
+// Using minimal interface for optional fallback error logging
+
+let logger: ObservabilityClient | null = null;
+
+/**
+ * Analytics provider component for App Router.
+ *
+ * @remarks
+ * Wraps your application and provides analytics context to all child components.
+ * Automatically initializes analytics and optionally tracks page views.
+ *
+ * @param props - Component props
+ * @param props.children - React children to wrap
+ * @param props.config - Analytics configuration
+ * @param props.autoPageTracking - Whether to automatically track page views (default: true)
+ * @param props.pageTrackingOptions - Options for page tracking
+ *
+ * @example
+ * ```tsx
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <AnalyticsProvider
+ *       config={{
+ *         providers: {
+ *           http: { options: { endpoint: process.env.NEXT_PUBLIC_ANALYTICS_ENDPOINT! } }
+ *         }
+ *       }}
+ *       autoPageTracking={true}
+ *     >
+ *       {children}
+ *     </AnalyticsProvider>
+ *   );
+ * }
+ * ```
+ */
+export function AnalyticsProvider({
+  autoPageTracking = true,
+  children,
+  config,
+  pageTrackingOptions,
+}: {
+  children: React.ReactNode;
+  config: AnalyticsConfig;
+  autoPageTracking?: boolean;
+  pageTrackingOptions?: Parameters<typeof usePageTracking>[0];
+}) {
+  // Initialize analytics
+  useEffect(() => {
+    if (!globalAnalytics) {
+      const initAnalytics = async () => {
+        try {
+          // Initialize logger if not already initialized
+          logger ??= await createClientObservability();
+
+          const instance = await createNextJSClientAnalytics(config);
+          globalAnalytics = instance;
+        } catch (error) {
+          if (logger) {
+            logger.captureException(error, {
+              message: 'Failed to initialize analytics',
+            });
+          }
+        }
+      };
+      void initAnalytics();
+    }
+  }, [config]);
+
+  // Auto page tracking
+  usePageTracking(autoPageTracking ? pageTrackingOptions : { skip: true });
+
+  return children as React.ReactElement;
+}
+
+/**
+ * Button component with automatic click tracking.
+ *
+ * @remarks
+ * Wraps a standard button element and automatically tracks click events
+ * when the button is clicked.
+ *
+ * @param props - Button props plus tracking props
+ * @param props.eventName - Name of the event to track
+ * @param props.properties - Additional properties to include in the event
+ * @param props.onClick - Optional click handler (tracking happens before this)
+ *
+ * @example
+ * ```tsx
+ * <TrackedButton
+ *   eventName="Sign Up Clicked"
+ *   properties={{ location: 'header', variant: 'primary' }}
+ *   onClick={() => router.push('/signup')}
+ * >
+ *   Sign Up
+ * </TrackedButton>
+ * ```
+ */
+export function TrackedButton({
+  children,
+  eventName,
+  onClick,
+  properties,
+  ...props
+}: React.ButtonHTMLAttributes<HTMLButtonElement> & {
+  eventName: string;
+  properties?: Properties;
+}) {
+  const track = useTrackEvent();
+
+  const handleClick = useCallback(
+    (e: React.MouseEvent<HTMLButtonElement>) => {
+      track(eventName, properties);
+      onClick?.(e);
+    },
+    [track, eventName, properties, onClick],
+  );
+
+  return (
+    <button type="button" {...props} onClick={handleClick}>
+      {children}
+    </button>
+  );
+}
+
+/**
+ * Link component with automatic click tracking.
+ *
+ * @remarks
+ * Wraps a standard anchor element and automatically tracks click events
+ * when the link is clicked. Also handles internal navigation for Next.js.
+ *
+ * @param props - Anchor props plus tracking props
+ * @param props.eventName - Name of the event to track
+ * @param props.properties - Additional properties to include in the event
+ * @param props.href - Link URL
+ * @param props.onClick - Optional click handler (tracking happens before this)
+ *
+ * @example
+ * ```tsx
+ * <TrackedLink
+ *   href="/products"
+ *   eventName="Product Link Clicked"
+ *   properties={{ linkText: 'View Products' }}
+ * >
+ *   View Products
+ * </TrackedLink>
+ * ```
+ */
+export function TrackedLink({
+  children,
+  eventName,
+  href,
+  onClick,
+  properties,
+  ...props
+}: React.AnchorHTMLAttributes<HTMLAnchorElement> & {
+  eventName: string;
+  properties?: Properties;
+}) {
+  const track = useTrackEvent();
+  const router = useRouter();
+
+  const handleClick = useCallback(
+    (e: React.MouseEvent<HTMLAnchorElement>) => {
+      // Track the event
+      const enhancedProperties = {
+        ...properties,
+        href,
+        link_text: typeof children === 'string' ? children : undefined,
+      };
+      track(eventName, enhancedProperties);
+
+      // Handle navigation
+      if (onClick) {
+        onClick(e);
+      } else if (href && !props.target && href.startsWith('/')) {
+        // Internal navigation
+        e.preventDefault();
+        router.push(href as Route);
+      }
+    },
+    [track, eventName, properties, href, onClick, router, children, props.target],
+  );
+
+  return (
+    <a {...props} href={href} onClick={handleClick}>
+      {children}
+    </a>
+  );
+}
+
+/**
+ * Higher-order component for tracking component views.
+ *
+ * @remarks
+ * Wraps a component and automatically tracks a view event when the component
+ * is first rendered. Useful for tracking page sections or feature usage.
+ *
+ * @param Component - The component to wrap
+ * @param eventName - Name of the event to track
+ * @param getProperties - Optional function to extract properties from component props
+ * @returns Wrapped component with automatic view tracking
+ *
+ * @example
+ * ```tsx
+ * const TrackedDashboard = withViewTracking(
+ *   Dashboard,
+ *   'Dashboard Viewed',
+ *   (props) => ({ userId: props.userId, plan: props.plan })
+ * );
+ * ```
+ */
+export function withViewTracking<P extends object>(
+  Component: React.ComponentType<P>,
+  eventName: string,
+  getProperties?: (props: P) => Properties,
+) {
+  return function TrackedComponent(props: P) {
+    const track = useTrackEvent();
+    const tracked = useRef(false);
+
+    useEffect(() => {
+      if (!tracked.current) {
+        tracked.current = true;
+        const properties = getProperties ? getProperties(props) : {};
+        track(eventName, properties);
+      }
+    }, [track, props]);
+
+    return <Component {...props} />;
+  };
+}

package/src/client/next/hooks.ts

@@ -0,0 +1,217 @@
+/**
+ * @fileoverview Next.js Client Hooks for Analytics
+ *
+ * React hooks for integrating analytics into Next.js applications.
+ * Provides hooks for accessing analytics instances, tracking events,
+ * and automatic page view tracking.
+ *
+ * **Hooks**:
+ * - `useAnalytics()`: Get or create analytics instance
+ * - `usePageTracking()`: Automatic page view tracking in App Router
+ * - `useTrackEvent()`: Hook for tracking events
+ * - `useIdentifyUser()`: Hook for user identification
+ * - `resetAnalytics()`: Utility to reset analytics (useful for testing)
+ *
+ * **Note**: These hooks use Next.js navigation hooks. For framework-agnostic hooks,
+ * use the base hooks from './hooks' or './manager'.
+ *
+ * @module @od-oneapp/analytics/client/next/hooks
+ */
+
+'use client';
+
+// Note: These are Next.js hooks required for App Router integration
+// Client components are already Next.js-specific, so this is acceptable
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { useParams, usePathname, useSearchParams } from 'next/navigation';
+// Type-only imports for Next.js types (compile-time only, no runtime dependency)
+
+import { createNextJSClientAnalytics } from './manager';
+
+import type { AnalyticsConfig, AnalyticsManager, TrackingOptions } from '../../shared/types/types';
+
+// Global analytics instance
+let globalAnalytics: AnalyticsManager | null = null;
+
+/**
+ * Hook to get or create analytics instance.
+ *
+ * @remarks
+ * Returns the global analytics instance, creating it if it doesn't exist
+ * and config is provided. Returns null if analytics hasn't been initialized.
+ *
+ * @param config - Optional analytics configuration (only used on first call)
+ * @returns Analytics manager instance or null if not initialized
+ *
+ * @example
+ * ```tsx
+ * const analytics = useAnalytics(config);
+ * useEffect(() => {
+ *   if (analytics) {
+ *     analytics.track('ClientReady');
+ *   }
+ * }, [analytics]);
+ * ```
+ */
+export function useAnalytics(config?: AnalyticsConfig): AnalyticsManager | null {
+  const [analytics, setAnalytics] = useState<AnalyticsManager | null>(null);
+
+  useEffect(() => {
+    if (!globalAnalytics && config) {
+      const initAnalytics = async () => {
+        try {
+          // Note: Client-side observability handled by manager
+
+          const instance = await createNextJSClientAnalytics(config);
+          globalAnalytics = instance;
+          setAnalytics(instance);
+        } catch {
+          // Failed to initialize analytics - silently continue
+          // TODO: Add proper error logging via observability package
+        }
+      };
+      void initAnalytics();
+    } else if (globalAnalytics && analytics !== globalAnalytics) {
+      // Use setTimeout to avoid synchronous setState in effect
+      setTimeout(() => {
+        setAnalytics(globalAnalytics);
+      }, 0);
+    }
+  }, [config]);
+
+  return analytics;
+}
+
+/**
+ * Hook for automatic page view tracking in App Router.
+ *
+ * @remarks
+ * Automatically tracks page views when the pathname, search params, or route
+ * params change. Prevents duplicate tracking for the same page.
+ *
+ * @param options - Page tracking options
+ * @param options.trackSearch - Whether to include search params in tracking (default: false)
+ * @param options.trackParams - Whether to include route params in tracking (default: false)
+ * @param options.properties - Additional properties to include in page events
+ * @param options.skip - Whether to skip tracking (default: false)
+ *
+ * @example
+ * ```tsx
+ * usePageTracking({ trackSearch: true, trackParams: true });
+ * ```
+ */
+export function usePageTracking(options?: {
+  trackSearch?: boolean;
+  trackParams?: boolean;
+  properties?: Record<string, any>;
+  skip?: boolean;
+}) {
+  const pathname = usePathname();
+  const searchParams = useSearchParams();
+  const params = useParams();
+  const tracked = useRef<string>('');
+
+  useEffect(() => {
+    if (options?.skip || !globalAnalytics) return;
+
+    // Create unique key for this page view
+    const searchString = options?.trackSearch ? searchParams.toString() : '';
+    const pageKey = `${pathname}${searchString}`;
+
+    // Avoid duplicate tracking
+    if (tracked.current === pageKey) return;
+    tracked.current = pageKey;
+
+    // Build properties
+    const properties: Record<string, any> = {
+      ...options?.properties,
+      url: window.location.href,
+      path: pathname,
+      referrer: document.referrer,
+      title: document.title,
+    };
+
+    if (options?.trackSearch) {
+      properties.search = searchString;
+      properties.search_params = Object.fromEntries(searchParams.entries());
+    }
+
+    if (options?.trackParams && params) {
+      properties.route_params = params;
+    }
+
+    // Track page view
+    void globalAnalytics.page(pathname, properties);
+  }, [
+    pathname,
+    searchParams,
+    params,
+    options?.skip,
+    options?.trackSearch,
+    options?.trackParams,
+    options?.properties,
+  ]);
+}
+
+/**
+ * Hook for tracking events.
+ *
+ * @remarks
+ * Returns a callback function for tracking events. The callback is stable
+ * across renders and can be safely used in event handlers.
+ *
+ * @returns Callback function for tracking events
+ *
+ * @example
+ * ```tsx
+ * const track = useTrackEvent();
+ * track('CTA Clicked', { label: 'Request Demo' });
+ * ```
+ */
+export function useTrackEvent() {
+  return useCallback((event: string, properties?: any, options?: TrackingOptions) => {
+    if (!globalAnalytics) return;
+    void globalAnalytics.track(event, properties, options);
+  }, []);
+}
+
+/**
+ * Hook for user identification.
+ *
+ * @remarks
+ * Returns a callback function for identifying users. The callback is stable
+ * across renders and can be safely used in event handlers.
+ *
+ * @returns Callback function for identifying users
+ *
+ * @example
+ * ```tsx
+ * const identify = useIdentifyUser();
+ * identify(user.id, { plan: user.plan });
+ * ```
+ */
+export function useIdentifyUser() {
+  return useCallback((userId: string, traits?: any, options?: TrackingOptions) => {
+    if (!globalAnalytics) return;
+    void globalAnalytics.identify(userId, traits, options);
+  }, []);
+}
+
+/**
+ * Utility to reset analytics (useful for testing).
+ *
+ * @remarks
+ * Clears the global analytics instance. Useful in test environments to
+ * ensure clean state between tests.
+ *
+ * @example
+ * ```typescript
+ * beforeEach(() => {
+ *   resetAnalytics();
+ * });
+ * ```
+ */
+export function resetAnalytics() {
+  globalAnalytics = null;
+}

package/src/client/next/manager.ts

@@ -0,0 +1,141 @@
+/**
+ * @fileoverview Next.js Client Analytics Manager
+ *
+ * Next.js client analytics manager with truly dynamic provider loading.
+ * Only imports providers that are actually configured to avoid webpack
+ * bundling unused dependencies, reducing bundle size.
+ *
+ * **Features**:
+ * - Dynamic provider loading (only configured providers are bundled)
+ * - Code splitting via webpack chunks
+ * - Lazy initialization support
+ * - Next.js App Router optimized
+ *
+ * @module @od-oneapp/analytics/client/next/manager
+ */
+
+// Simple console fallback - observability integration can be added later
+import { createAnalyticsManager } from '../../shared/utils/manager';
+
+import type { AnalyticsConfig, AnalyticsManager, ProviderRegistry } from '../../shared/types/types';
+const logWarn = (_message: string, _context?: any) => {
+  // No-op to avoid console warnings in production
+  // TODO: Add proper error logging via observability package
+};
+
+/**
+ * Create a Next.js client analytics instance with runtime provider loading
+ * Only imports providers that are actually configured to avoid webpack bundling unused dependencies
+ *
+ * @example
+ * ```typescript
+ * const analytics = await createNextJSClientAnalytics({
+ *   providers: { posthog: { apiKey: process.env.NEXT_PUBLIC_POSTHOG_KEY! } },
+ * });
+ * await analytics.track('Dashboard Viewed');
+ * ```
+ */
+export async function createNextJSClientAnalytics(
+  config: AnalyticsConfig,
+): Promise<AnalyticsManager> {
+  const CLIENT_PROVIDERS: ProviderRegistry = {};
+
+  // Get configured providers
+  const configuredProviders = Object.keys(config.providers);
+
+  // Only import configured providers using truly dynamic imports
+  const providerPromises = configuredProviders.map(async providerName => {
+    switch (providerName) {
+      case 'console': {
+        const module = await import(
+          /* webpackChunkName: "analytics-console" */ '../../providers/console/client'
+        );
+        CLIENT_PROVIDERS.console = config => new module.ConsoleProvider(config);
+        break;
+      }
+      case 'posthog': {
+        const module = await import(
+          /* webpackChunkName: "analytics-posthog" */ '../../providers/posthog/client'
+        );
+        CLIENT_PROVIDERS.posthog = config => new module.PostHogClientProvider(config);
+        break;
+      }
+      case 'segment': {
+        const module = await import(
+          /* webpackChunkName: "analytics-segment" */ '../../providers/segment/client'
+        );
+        CLIENT_PROVIDERS.segment = config => new module.SegmentClientProvider(config);
+        break;
+      }
+      case 'vercel': {
+        const module = await import(
+          /* webpackChunkName: "analytics-vercel" */ '../../providers/vercel/client'
+        );
+        CLIENT_PROVIDERS.vercel = config => new module.VercelClientProvider(config);
+        break;
+      }
+      default:
+        // Skip unknown providers
+        logWarn('Unknown analytics provider:', { providerName });
+        break;
+    }
+  });
+
+  // Wait for all configured providers to load
+  await Promise.all(providerPromises);
+
+  const manager = createAnalyticsManager(config, CLIENT_PROVIDERS);
+  await manager.initialize();
+  return manager;
+}
+
+/**
+ * Create a Next.js client analytics instance without initializing
+ *
+ * @example
+ * ```typescript
+ * const analytics = await createNextJSClientAnalyticsUninitialized(config);
+ * // run setup before first event
+ * await analytics.initialize();
+ * ```
+ */
+export async function createNextJSClientAnalyticsUninitialized(
+  config: AnalyticsConfig,
+): Promise<AnalyticsManager> {
+  const CLIENT_PROVIDERS: ProviderRegistry = {};
+
+  // Get configured providers
+  const configuredProviders = Object.keys(config.providers);
+
+  // Dynamically import only configured providers
+  for (const providerName of configuredProviders) {
+    switch (providerName) {
+      case 'console': {
+        const { ConsoleProvider } = await import('../../providers/console/client');
+        CLIENT_PROVIDERS.console = config => new ConsoleProvider(config);
+        break;
+      }
+      case 'posthog': {
+        const { PostHogClientProvider } = await import('../../providers/posthog/client');
+        CLIENT_PROVIDERS.posthog = config => new PostHogClientProvider(config);
+        break;
+      }
+      case 'segment': {
+        const { SegmentClientProvider } = await import('../../providers/segment/client');
+        CLIENT_PROVIDERS.segment = config => new SegmentClientProvider(config);
+        break;
+      }
+      case 'vercel': {
+        const { VercelClientProvider } = await import('../../providers/vercel/client');
+        CLIENT_PROVIDERS.vercel = config => new VercelClientProvider(config);
+        break;
+      }
+      default:
+        // Skip unknown providers
+        logWarn('Unknown analytics provider:', { providerName });
+        break;
+    }
+  }
+
+  return createAnalyticsManager(config, CLIENT_PROVIDERS);
+}