@od-oneapp/analytics 2026.1.1301

package/src/shared/providers/console-provider.ts

@@ -0,0 +1,160 @@
+/**
+ * @fileoverview Console provider - works in both client and server environments
+ * Console provider - works in both client and server environments
+ * Useful for development and debugging
+ */
+
+import { logDebug, logWarn } from '@repo/shared/logger';
+
+import type { ConsoleConfig } from '../types/console-types';
+import type { AnalyticsProvider, ProviderConfig } from '../types/types';
+
+export class ConsoleProvider implements AnalyticsProvider {
+  readonly name = 'console';
+  private config: ConsoleConfig;
+  private isInitialized = false;
+
+  constructor(config: ProviderConfig) {
+    this.config = {
+      options: config.options
+        ? {
+            enableColors:
+              typeof config.options.enableColors === 'boolean'
+                ? config.options.enableColors
+                : false,
+            logLevel:
+              config.options.logLevel === 'debug' ||
+              config.options.logLevel === 'info' ||
+              config.options.logLevel === 'warn' ||
+              config.options.logLevel === 'error'
+                ? config.options.logLevel
+                : 'info',
+            prefix:
+              typeof config.options.prefix === 'string' ? config.options.prefix : '[Analytics]',
+            pretty: typeof config.options.pretty === 'boolean' ? config.options.pretty : true,
+          }
+        : {
+            enableColors: false,
+            logLevel: 'info',
+            prefix: '[Analytics]',
+            pretty: true,
+          },
+    };
+  }
+
+  async initialize(): Promise<void> {
+    if (this.isInitialized) return;
+
+    // Reduce noisy logs: only log in development or explicit debug
+    const isDev = process.env.NODE_ENV !== 'production';
+    const isDebug = process.env.NEXT_PUBLIC_OBSERVABILITY_DEBUG === 'true';
+    if (isDev || isDebug) {
+      this.log('Console Analytics Provider initialized', {
+        config: this.config.options,
+      });
+    }
+
+    this.isInitialized = true;
+  }
+
+  async track(event: string, properties: any = {}, _context?: any): Promise<void> {
+    if (!this.isInitialized) {
+      logWarn('Console provider not initialized', {
+        provider: 'console',
+        operation: 'track',
+        event,
+      });
+      return;
+    }
+
+    this.log('TRACK', {
+      event,
+      properties,
+      timestamp: new Date().toISOString(),
+    });
+  }
+
+  async identify(userId: string, traits: any = {}, _context?: any): Promise<void> {
+    if (!this.isInitialized) {
+      logWarn('Console provider not initialized', {
+        provider: 'console',
+        operation: 'identify',
+        userId,
+      });
+      return;
+    }
+
+    this.log('IDENTIFY', {
+      timestamp: new Date().toISOString(),
+      traits,
+      userId,
+    });
+  }
+
+  async page(name?: string, properties: any = {}, _context?: any): Promise<void> {
+    if (!this.isInitialized) {
+      logWarn('Console provider not initialized', {
+        provider: 'console',
+        operation: 'page',
+        metadata: { name },
+      });
+      return;
+    }
+
+    this.log('PAGE', {
+      name,
+      properties,
+      timestamp: new Date().toISOString(),
+    });
+  }
+
+  async group(groupId: string, traits: any = {}, _context?: any): Promise<void> {
+    if (!this.isInitialized) {
+      logWarn('Console provider not initialized', {
+        provider: 'console',
+        operation: 'group',
+        metadata: { groupId },
+      });
+      return;
+    }
+
+    this.log('GROUP', {
+      groupId,
+      timestamp: new Date().toISOString(),
+      traits,
+    });
+  }
+
+  async alias(userId: string, previousId: string, _context?: any): Promise<void> {
+    if (!this.isInitialized) {
+      logWarn('Console provider not initialized', {
+        provider: 'console',
+        operation: 'alias',
+        userId,
+        metadata: { previousId },
+      });
+      return;
+    }
+
+    this.log('ALIAS', {
+      previousId,
+      timestamp: new Date().toISOString(),
+      userId,
+    });
+  }
+
+  private log(action: string, data: any): void {
+    const { logLevel, prefix } = this.config.options ?? { logLevel: 'info', prefix: '[Analytics]' };
+
+    if (logLevel === 'error') return; // Don't log analytics in error-only mode
+
+    const message = `${prefix} ${action}`;
+
+    // Use analytics logger instead of console directly
+    logDebug(message, {
+      provider: 'console',
+      operation: action.toLowerCase(),
+      metadata: data,
+    });
+  }
+}

package/src/shared/types/base-types.ts

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview Base property types for the analytics system
+ *
+ * This module defines the foundational types that are shared between
+ * the main types module and emitter types. Extracted to prevent circular
+ * dependencies between types.ts and emitter-types.ts.
+ *
+ * @module @od-oneapp/analytics/shared/types/base-types
+ */
+
+/**
+ * Safe property value types for analytics tracking.
+ *
+ * These types ensure that only safe, serializable values are sent to analytics providers.
+ * Prevents sending functions, symbols, or other non-serializable data.
+ */
+export type PropertyValue = string | number | boolean | Date | null | undefined;
+
+/**
+ * Property object with nested structure support.
+ *
+ * Allows nested objects and arrays of property values for complex event properties.
+ */
+export interface PropertyObject {
+  [key: string]: PropertyValue | PropertyValue[] | PropertyObject;
+}
+
+/**
+ * Properties type alias for event properties.
+ *
+ * Used for track events and other analytics calls that accept properties.
+ */
+export type Properties = PropertyObject;
+
+/**
+ * User traits for identification.
+ *
+ * Used in `identify()` calls to record user attributes like email, name, etc.
+ */
+export type UserTraits = Record<string, PropertyValue | PropertyValue[]>;
+
+/**
+ * Group/organization traits.
+ *
+ * Used in `group()` calls to record organization or group attributes.
+ */
+export type GroupTraits = Record<string, PropertyValue | PropertyValue[]>;
+
+/**
+ * Page properties for page view tracking.
+ *
+ * Used in `page()` calls to record page view information like URL, referrer, etc.
+ */
+export type PageProperties = Record<string, PropertyValue | PropertyValue[] | PropertyObject>;

package/src/shared/types/console-types.ts

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview Console provider types
+ * Console provider types
+ */
+
+export interface ConsoleConfig {
+  options?:
+    | {
+        prefix?: string | undefined;
+        enableColors?: boolean | undefined;
+        logLevel?: 'debug' | 'info' | 'warn' | 'error' | undefined;
+        pretty?: boolean | undefined;
+      }
+    | undefined;
+}
+
+export type ConsoleOptions = Record<string, any>;
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';

package/src/shared/types/posthog-types.ts

@@ -0,0 +1,131 @@
+/**
+ * @fileoverview PostHog-specific types
+ * PostHog-specific types
+ */
+
+export interface PostHogConfig {
+  apiKey: string;
+  options?: {
+    // Core configuration (existing)
+    api_host?: string;
+    ui_host?: string;
+    autocapture?: boolean;
+    capture_pageview?: boolean;
+    capture_pageleave?: boolean;
+    disable_session_recording?: boolean;
+    cross_subdomain_cookie?: boolean;
+    persistence?: 'localStorage' | 'cookie' | 'memory' | 'localStorage+cookie';
+    persistence_name?: string;
+    loaded?: (posthog: any) => void;
+
+    // Privacy & GDPR compliance (NEW SECTION)
+    person_profiles?: 'always' | 'never' | 'identified_only';
+    opt_in_site_apps?: boolean;
+    respect_dnt?: boolean;
+
+    // Performance optimizations (NEW)
+    uuid_version?: 'v4' | 'v7';
+    request_batching?: boolean;
+    batch_flush_interval_ms?: number;
+
+    // Session recording configuration (NEW SECTION)
+    session_recording?: {
+      maskAllInputs?: boolean;
+      maskInputOptions?: {
+        color?: boolean;
+        date?: boolean;
+        'datetime-local'?: boolean;
+        email?: boolean;
+        month?: boolean;
+        number?: boolean;
+        password?: boolean;
+        range?: boolean;
+        search?: boolean;
+        tel?: boolean;
+        text?: boolean;
+        time?: boolean;
+        url?: boolean;
+        week?: boolean;
+      };
+      recordCrossOriginIframes?: boolean;
+      recordCanvas?: boolean;
+      maskTextSelector?: string;
+      blockSelector?: string;
+      sampling?: {
+        minimumDurationMs?: number;
+        sampleRate?: number;
+      };
+    };
+
+    // Event processing hooks (NEW)
+    before_send?: (event: any) => any | null;
+    sanitize_properties?: (properties: any, event: string) => any;
+
+    // Debug and development (NEW)
+    debug?: boolean;
+    advanced_disable_decide?: boolean;
+
+    // Server-side specific options
+    flushAt?: number;
+    flushInterval?: number;
+
+    // Next.js specific options
+    fetch_options?: {
+      cache?: RequestCache;
+      next?: {
+        revalidate?: number;
+        tags?: string[];
+      };
+    };
+
+    // Bootstrap options
+    bootstrap?: BootstrapData;
+  };
+}
+
+export interface ExperimentInfo {
+  key: string;
+  payload?: Record<string, any>;
+  variant?: string | boolean;
+}
+
+/**
+ * Bootstrap data for server-side rendering
+ */
+export interface BootstrapData {
+  distinctID: string;
+}
+
+/**
+ * PostHog cookie structure
+ */
+export interface PostHogCookie {
+  $sesid?: [number, string, number];
+  $session_id?: string;
+  $window_id?: string;
+  distinct_id: string;
+}
+
+/**
+ * Enhanced PostHog provider interface
+ */
+export interface EnhancedPostHogProvider {
+  alias(userId: string, previousId: string): Promise<void>;
+  group(groupId: string, traits?: any): Promise<void>;
+  identify(userId: string, traits?: any): Promise<void>;
+  page(name?: string, properties?: any): Promise<void>;
+  // Standard analytics methods
+  track(event: string, properties?: any): Promise<void>;
+
+  // Experiment methods
+  getActiveExperiments(userId?: string): Promise<ExperimentInfo[]>;
+
+  // Bootstrap methods (server-side)
+  getBootstrapData(distinctId: string): Promise<BootstrapData>;
+
+  // Utility methods
+  reset(): void;
+  shutdown(): Promise<void>;
+}
+
+export type PostHogOptions = Record<string, any>;

package/src/shared/types/segment-types.ts

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview Segment-specific types
+ * Segment-specific types
+ */
+
+export interface SegmentConfig {
+  options?: {
+    integrations?: Record<string, any>;
+    context?: Record<string, any>;
+    anonymousId?: string;
+  };
+  writeKey: string;
+}
+
+export type SegmentOptions = Record<string, any>;