@od-oneapp/analytics 2026.1.1301

package/src/shared/types/types.ts

@@ -0,0 +1,397 @@
+/**
+ * @fileoverview Core types for the multi-provider analytics system
+ *
+ * This module defines the core TypeScript types and interfaces for the analytics system.
+ * It includes:
+ *
+ * - **Property Types**: PropertyValue, PropertyObject, Properties, UserTraits, GroupTraits, PageProperties
+ * - **Provider Interface**: AnalyticsProvider with all standard methods
+ * - **Configuration Types**: AnalyticsConfig, ProviderConfig, TrackingOptions
+ * - **Manager Interface**: AnalyticsManager with emitter and tracking methods
+ * - **Context Types**: AnalyticsContext for request-scoped data
+ * - **Error Types**: ErrorContext for error handling
+ * - **Ecommerce Types**: EcommerceEventSpec for ecommerce events
+ *
+ * **Optimized for**: React 19 and Node.js 22+ with strict TypeScript types
+ *
+ * @module @od-oneapp/analytics/shared/types/types
+ */
+
+// Re-export base types from base-types.ts to maintain API compatibility
+export type {
+  GroupTraits,
+  PageProperties,
+  Properties,
+  PropertyObject,
+  PropertyValue,
+  UserTraits,
+} from './base-types';
+// Import base types for use in this file's interfaces
+import type { GroupTraits, PageProperties, Properties, UserTraits } from './base-types';
+// Import emitter types for the interface
+import type {
+  EmitterAliasPayload,
+  EmitterGroupPayload,
+  EmitterIdentifyPayload,
+  EmitterPagePayload,
+  EmitterPayload,
+  EmitterScreenPayload,
+  EmitterTrackPayload,
+} from '../emitters/emitter-types';
+
+// Re-export emitter types for external consumption
+export type { EmitterPayload };
+
+/**
+ * PostHog bootstrap data structure.
+ *
+ * Contains PostHog-specific initialization data including distinct ID, feature flags,
+ * and identification status. Used for server-side rendering and hydration.
+ */
+export interface PostHogBootstrap {
+  distinctID?: string;
+  isIdentifiedID?: boolean;
+  featureFlags?: Record<string, string | boolean>;
+  featureFlagPayloads?: Record<string, unknown>;
+}
+
+/**
+ * Provider configuration interface.
+ *
+ * Defines the configuration structure for analytics providers. Each provider
+ * may require different fields (apiKey, writeKey, token, etc.).
+ */
+export interface ProviderConfig {
+  // Provider-specific required fields
+  apiKey?: string | undefined;
+  measurementId?: string | undefined;
+  token?: string | undefined;
+  writeKey?: string | undefined;
+  enabled?: boolean | undefined;
+
+  // Optional configuration
+  events?: string[] | 'all' | undefined;
+  options?: Record<string, unknown> | undefined;
+}
+
+/**
+ * Analytics provider interface.
+ *
+ * All analytics providers must implement this interface for consistent behavior
+ * across the analytics system. Providers can implement optional methods based on
+ * their capabilities.
+ *
+ * **Required Methods**:
+ * - `initialize()`: Initialize the provider
+ * - `track()`: Track events
+ *
+ * **Optional Methods**:
+ * - `identify()`: Identify users
+ * - `page()`: Track page views
+ * - `screen()`: Track screen views (mobile)
+ * - `group()`: Associate users with groups
+ * - `alias()`: Alias user IDs
+ * - `setContext()`: Set global context
+ */
+export interface AnalyticsProvider {
+  readonly name: string;
+
+  /**
+   * Initialize the provider with configuration
+   */
+  initialize(config: ProviderConfig): Promise<void>;
+
+  /**
+   * Track an event with properties
+   */
+  track(event: string, properties: Properties, context?: AnalyticsContext): Promise<void>;
+
+  /**
+   * Identify a user with traits (optional)
+   */
+  identify?(userId: string, traits: UserTraits, context?: AnalyticsContext): Promise<void>;
+
+  /**
+   * Track a page view (optional)
+   */
+  page?(name: string, properties: PageProperties, context?: AnalyticsContext): Promise<void>;
+
+  /**
+   * Track a screen view - mobile equivalent of page (optional)
+   */
+  screen?(name: string, properties: PageProperties, context?: AnalyticsContext): Promise<void>;
+
+  /**
+   * Associate user with a group/organization (optional)
+   */
+  group?(groupId: string, traits: GroupTraits, context?: AnalyticsContext): Promise<void>;
+
+  /**
+   * Alias one user ID to another (optional)
+   */
+  alias?(userId: string, previousId: string, context?: AnalyticsContext): Promise<void>;
+
+  /**
+   * Set global context for all events (optional)
+   */
+  setContext?(context: AnalyticsContext): void;
+}
+
+/**
+ * Error context for error handlers.
+ *
+ * Provides context about errors that occur during analytics operations,
+ * including which provider and method failed.
+ */
+export interface ErrorContext {
+  provider: string;
+  method: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Analytics configuration interface.
+ *
+ * Defines the complete configuration structure for the analytics system.
+ * Includes provider configurations, debug settings, error handlers, and Next.js-specific options.
+ */
+export interface AnalyticsConfig {
+  /**
+   * Enable debug logging
+   */
+  debug?: boolean | undefined;
+
+  /**
+   * Next.js specific configuration
+   */
+  nextjs?:
+    | {
+        deferUntilConsent?: boolean | undefined;
+        bufferEvents?: boolean | undefined;
+        maxBufferSize?: number | undefined;
+        checkConsent?: (() => boolean | Promise<boolean>) | undefined;
+        posthog?:
+          | {
+              bootstrap?: PostHogBootstrap | undefined;
+              apiKey?: string | undefined;
+              host?: string | undefined;
+            }
+          | undefined;
+        [key: string]: unknown;
+      }
+    | undefined;
+
+  /**
+   * Error handler callback
+   */
+  onError?: ((error: unknown, context: ErrorContext) => void) | undefined;
+
+  /**
+   * Info logging callback
+   */
+  onInfo?: ((message: string) => void) | undefined;
+
+  /**
+   * Provider configurations
+   */
+  providers: Record<string, ProviderConfig>;
+}
+
+/**
+ * Options for individual tracking calls.
+ *
+ * Allows per-call customization of provider selection and context.
+ * Useful for sending events to specific providers or excluding certain providers.
+ */
+export interface TrackingOptions {
+  /**
+   * Override: add providers not in global config
+   */
+  providers?: Record<string, ProviderConfig> | undefined;
+
+  /**
+   * Use shorthand for configured providers only
+   */
+  only?: string[] | undefined;
+
+  /**
+   * Send to all except these
+   */
+  exclude?: string[] | undefined;
+
+  /**
+   * Context to merge with global context
+   */
+  context?: AnalyticsContext | undefined;
+}
+
+/**
+ * Factory function to create a provider instance.
+ *
+ * Takes provider configuration and returns an initialized provider instance.
+ */
+export type ProviderFactory = (config: ProviderConfig) => AnalyticsProvider;
+
+/**
+ * Registry mapping provider names to factory functions.
+ *
+ * Used internally to dynamically create provider instances based on configuration.
+ */
+export type ProviderRegistry = Record<string, ProviderFactory>;
+
+/**
+ * Analytics context passed with all events.
+ *
+ * Provides request-scoped or user-scoped context that is automatically
+ * included with all analytics events. Can include userId, sessionId, organizationId,
+ * environment, traits, and custom properties.
+ */
+export interface AnalyticsContext {
+  userId?: string;
+  sessionId?: string;
+  organizationId?: string;
+  environment?: string;
+  traits?: UserTraits;
+  [key: string]: unknown;
+}
+
+/**
+ * Ecommerce event specification.
+ *
+ * Defines the structure for ecommerce events. Used by the legacy `trackEcommerce()`
+ * method. New code should use `emit(ecommerce.EVENT_NAME(...))` instead.
+ *
+ * @deprecated Use `emit(ecommerce.EVENT_NAME(...))` for better type safety
+ */
+export interface EcommerceEventSpec {
+  name: string;
+  properties: Properties;
+  category?: string;
+}
+
+/**
+ * Analytics Manager interface.
+ *
+ * Main entry point for analytics tracking. Provides methods for:
+ * - Initializing providers
+ * - Tracking events (track, identify, page, screen, group, alias)
+ * - Managing context
+ * - Emitting emitter payloads (recommended approach)
+ * - Batch operations
+ *
+ * **Recommended Usage**: Use `emit()` with emitter payloads for type-safe event tracking.
+ */
+export interface AnalyticsManager {
+  /**
+   * Get current analytics context
+   */
+  getContext(): AnalyticsContext;
+
+  /**
+   * Initialize all configured providers
+   */
+  initialize(): Promise<void>;
+
+  /**
+   * Set global analytics context
+   */
+  setContext(context: AnalyticsContext): void;
+
+  /**
+   * Create a bound emitter function
+   */
+  createEmitter(): (payload: EmitterPayload) => Promise<void>;
+
+  /**
+   * Emit an emitter payload (recommended)
+   */
+  emit(payload: EmitterPayload, options?: { timeout?: number }): Promise<void>;
+
+  /**
+   * Emit multiple payloads in batch
+   */
+  emitBatch(
+    payloads: EmitterPayload[],
+    options?: { timeout?: number; concurrency?: number; failFast?: boolean },
+  ): Promise<void>;
+
+  /**
+   * Track an event
+   * Overload 1: Using emitter payload (recommended)
+   * Overload 2: Direct call with event name and properties
+   */
+  track(payload: EmitterTrackPayload): Promise<void>;
+  track(event: string, properties?: Properties, options?: TrackingOptions): Promise<void>;
+
+  /**
+   * Identify a user
+   * Overload 1: Using emitter payload (recommended)
+   * Overload 2: Direct call with user ID and traits
+   */
+  identify(payload: EmitterIdentifyPayload): Promise<void>;
+  identify(userId: string, traits?: UserTraits, options?: TrackingOptions): Promise<void>;
+
+  /**
+   * Track a page view
+   * Overload 1: Using emitter payload (recommended)
+   * Overload 2: Direct call with page name and properties
+   */
+  page(payload: EmitterPagePayload): Promise<void>;
+  page(name?: string, properties?: PageProperties, options?: TrackingOptions): Promise<void>;
+
+  /**
+   * Track a screen view (mobile equivalent of page)
+   * Overload 1: Using emitter payload (recommended)
+   * Overload 2: Direct call with screen name and properties
+   */
+  screen?(payload: EmitterScreenPayload): Promise<void>;
+  screen?(name?: string, properties?: PageProperties, options?: TrackingOptions): Promise<void>;
+
+  /**
+   * Associate user with a group
+   * Overload 1: Using emitter payload (recommended)
+   * Overload 2: Direct call with group ID and traits
+   */
+  group(payload: EmitterGroupPayload): Promise<void>;
+  group(groupId: string, traits?: GroupTraits, options?: TrackingOptions): Promise<void>;
+
+  /**
+   * Alias one user ID to another
+   * Overload 1: Using emitter payload (recommended)
+   * Overload 2: Direct call with user ID and previous ID
+   */
+  alias(payload: EmitterAliasPayload): Promise<void>;
+  alias(userId: string, previousId: string, options?: TrackingOptions): Promise<void>;
+
+  /**
+   * Get list of active provider names
+   */
+  getActiveProviders(): string[];
+
+  /**
+   * Get a specific provider instance
+   */
+  getProvider(name: string): AnalyticsProvider | undefined;
+
+  /**
+   * Reset analytics context and identity
+   */
+  reset(): void;
+
+  /**
+   * Shutdown all providers and cleanup resources
+   */
+  shutdown(): Promise<void>;
+
+  /**
+   * Process an emitter payload (legacy, use emit instead)
+   * @deprecated Use emit() for better type safety
+   */
+  processEmitterPayload(payload: EmitterPayload): Promise<void>;
+
+  /**
+   * Track an ecommerce event (legacy, use emit with ecommerce emitters)
+   * @deprecated Use emit(ecommerce.EVENT_NAME(...)) instead
+   */
+  trackEcommerce(eventSpec: EcommerceEventSpec): Promise<void>;
+}

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

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview Vercel Analytics-specific types
+ * Vercel Analytics-specific types
+ */
+
+export interface VercelConfig {
+  // Vercel Analytics doesn't require API keys for basic usage
+  // But can be configured with options
+  options?: {
+    mode?: 'auto' | 'production' | 'development';
+    debug?: boolean;
+    beforeSend?: (event: any) => any | null;
+  };
+}
+
+// Vercel Analytics has limited server-side support
+// Mainly focused on web vitals and page views on client
+
+export type VercelOptions = Record<string, any>;

package/src/shared/utils/config-client.ts

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview Client-safe configuration utilities for the analytics system
+ * Client-safe configuration utilities for the analytics system
+ *
+ * This file re-exports from the unified config module.
+ * Maintained for backwards compatibility with existing imports.
+ *
+ * @deprecated Import from './config' directly instead
+ */
+
+export {
+  PROVIDER_REQUIREMENTS,
+  createConfigBuilder,
+  getAnalyticsConfig,
+  validateConfig,
+  type AnalyticsConfigOptions,
+  type ConfigBuilder,
+  type ConfigRequirements,
+} from './config';

package/src/shared/utils/config.ts

@@ -0,0 +1,250 @@
+/**
+ * @fileoverview Configuration utilities for the analytics system
+ *
+ * This module provides configuration utilities that work in both client and server
+ * environments. It includes:
+ *
+ * - **Provider Requirements**: Required fields for each provider type
+ * - **Configuration Validation**: Validates provider configurations
+ * - **Config Builder**: Fluent API for building configurations
+ * - **Config Factory**: Environment-aware configuration factory
+ *
+ * **Usage**: Use `createConfigBuilder()` for programmatic config creation or
+ * `getAnalyticsConfig()` for environment-aware configuration.
+ *
+ * @module @od-oneapp/analytics/shared/utils/config
+ */
+
+import type { AnalyticsConfig, ProviderConfig } from '../types/types';
+
+/**
+ * Type for provider requirements mapping.
+ *
+ * Maps provider names to arrays of required configuration field names.
+ */
+export type ConfigRequirements = Record<string, string[]>;
+
+/**
+ * Provider requirements map - defines required fields for each provider.
+ *
+ * Used during configuration validation to ensure all required fields are present.
+ * Providers not listed here have no required fields.
+ */
+export const PROVIDER_REQUIREMENTS: ConfigRequirements = {
+  console: [], // No required fields
+  mixpanel: [], // Server-only provider
+  posthog: ['apiKey'],
+  segment: ['writeKey'],
+  vercel: [], // No required fields
+};
+
+/**
+ * Validates analytics configuration.
+ *
+ * Accepts `unknown` for runtime validation of potentially malformed configs.
+ * Throws descriptive errors if configuration is invalid.
+ *
+ * @param {unknown} config - Configuration object to validate
+ * @throws {Error} If configuration is invalid or missing required fields
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   validateConfig(config);
+ * } catch (error) {
+ *   console.error('Invalid config:', error.message);
+ * }
+ * ```
+ */
+export function validateConfig(config: unknown): void {
+  if (!config || typeof config !== 'object') {
+    throw new Error('Analytics config must be an object');
+  }
+
+  const typedConfig = config as AnalyticsConfig;
+
+  if (!typedConfig.providers || typeof typedConfig.providers !== 'object') {
+    throw new Error('Analytics config must have a providers object');
+  }
+
+  for (const [providerName, providerConfig] of Object.entries(typedConfig.providers)) {
+    validateProviderConfig(providerName, providerConfig);
+  }
+}
+
+/**
+ * Validates a single provider configuration.
+ *
+ * Checks that all required fields for the provider are present in the configuration.
+ *
+ * @param {string} providerName - Name of the provider to validate
+ * @param {ProviderConfig} config - Provider configuration to validate
+ * @throws {Error} If required fields are missing
+ *
+ * @internal
+ */
+function validateProviderConfig(providerName: string, config: ProviderConfig): void {
+  const requiredFields = PROVIDER_REQUIREMENTS[providerName] ?? [];
+
+  for (const field of requiredFields) {
+    if (!config[field as keyof ProviderConfig]) {
+      throw new Error(
+        `Provider '${providerName}' missing required field '${field}'. ` +
+          `Remove the provider from config or provide the required field.`,
+      );
+    }
+  }
+}
+
+/**
+ * Configuration builder interface.
+ *
+ * Provides a fluent API for building analytics configurations programmatically.
+ * Methods return `this` to enable method chaining.
+ */
+export interface ConfigBuilder {
+  addConsole(options?: Record<string, unknown>): ConfigBuilder;
+  addPostHog(apiKey: string, options?: Record<string, unknown>): ConfigBuilder;
+  addProvider(name: string, config: ProviderConfig): ConfigBuilder;
+  addSegment(writeKey: string, options?: Record<string, unknown>): ConfigBuilder;
+  addVercel(options?: Record<string, unknown>): ConfigBuilder;
+  build(): AnalyticsConfig;
+  providers: Record<string, ProviderConfig>;
+}
+
+/**
+ * Creates a fluent configuration builder.
+ *
+ * Returns a builder instance that allows chaining provider configuration methods.
+ * Call `build()` at the end to get the final configuration object.
+ *
+ * @returns {ConfigBuilder} Configuration builder instance
+ *
+ * @example
+ * ```typescript
+ * const config = createConfigBuilder()
+ *   .addPostHog('phc_xxx')
+ *   .addSegment('xxx')
+ *   .addConsole({ pretty: true })
+ *   .build();
+ * ```
+ */
+export function createConfigBuilder(): ConfigBuilder {
+  const builder: ConfigBuilder = {
+    providers: {},
+
+    addProvider(name: string, config: ProviderConfig): ConfigBuilder {
+      this.providers[name] = config;
+      return this;
+    },
+
+    addSegment(writeKey: string, options?: Record<string, unknown>): ConfigBuilder {
+      return this.addProvider('segment', { options, writeKey });
+    },
+
+    addPostHog(apiKey: string, options?: Record<string, unknown>): ConfigBuilder {
+      return this.addProvider('posthog', { apiKey, options });
+    },
+
+    addVercel(options?: Record<string, unknown>): ConfigBuilder {
+      return this.addProvider('vercel', { options });
+    },
+
+    addConsole(options?: Record<string, unknown>): ConfigBuilder {
+      return this.addProvider('console', { options });
+    },
+
+    build(): AnalyticsConfig {
+      const config = { providers: { ...this.providers } };
+      validateConfig(config);
+      return config;
+    },
+  };
+
+  return builder;
+}
+
+/**
+ * Options for client-side configuration.
+ *
+ * Allows explicit configuration values to be passed instead of reading from
+ * environment variables. Useful for client-side code where environment variables
+ * may not be available.
+ */
+export interface AnalyticsConfigOptions {
+  isDevelopment?: boolean;
+  isStaging?: boolean;
+  segmentWriteKey?: string;
+  posthogApiKey?: string;
+}
+
+/**
+ * Get analytics configuration
+ *
+ * When called with options (client-safe), uses the provided values.
+ * When called without options (server), reads from process.env.
+ *
+ * @param options - Optional configuration options for client-side usage
+ * @returns Analytics configuration object
+ *
+ * @example Server usage (reads from process.env):
+ * ```typescript
+ * const config = getAnalyticsConfig();
+ * ```
+ *
+ * @example Client usage (explicit options):
+ * ```typescript
+ * const config = getAnalyticsConfig({
+ *   isDevelopment: process.env.NODE_ENV === 'development',
+ *   posthogApiKey: process.env.NEXT_PUBLIC_POSTHOG_KEY,
+ * });
+ * ```
+ */
+export function getAnalyticsConfig(options?: AnalyticsConfigOptions): AnalyticsConfig {
+  const builder = createConfigBuilder();
+
+  // Determine environment from options or process.env
+  const isDevelopment = options?.isDevelopment ?? process.env.NODE_ENV === 'development';
+  const isStaging = options?.isStaging ?? process.env.APP_ENV === 'staging';
+
+  // Get API keys from options or process.env
+  const posthogApiKey = options?.posthogApiKey ?? process.env.POSTHOG_API_KEY;
+  const segmentWriteKey = options?.segmentWriteKey ?? process.env.SEGMENT_WRITE_KEY;
+
+  // Development - minimal providers
+  if (isDevelopment) {
+    builder.addConsole({
+      prefix: '[Dev Analytics]',
+      pretty: true,
+    });
+    return builder.build();
+  }
+
+  // Staging - selective providers
+  if (isStaging) {
+    if (posthogApiKey) {
+      builder.addPostHog(posthogApiKey);
+    }
+
+    builder.addConsole({
+      prefix: '[Staging Analytics]',
+      pretty: true,
+    });
+
+    return builder.build();
+  }
+
+  // Production - multiple providers
+  if (segmentWriteKey) {
+    builder.addSegment(segmentWriteKey);
+  }
+
+  if (posthogApiKey) {
+    builder.addPostHog(posthogApiKey);
+  }
+
+  // Add Vercel Analytics in production
+  builder.addVercel();
+
+  return builder.build();
+}