@od-oneapp/analytics 2026.1.1301

package/src/shared/utils/validation.ts

@@ -0,0 +1,399 @@
+/**
+ * @fileoverview Validation utilities for analytics configuration
+ *
+ * This module provides comprehensive validation for analytics configurations,
+ * including provider validation, environment-specific checks, and helpful
+ * warnings for common misconfigurations.
+ *
+ * **Features**:
+ * - Configuration structure validation
+ * - Provider-specific field validation
+ * - Environment variable validation
+ * - Environment-specific warnings
+ * - Detailed error reporting
+ *
+ * @module @od-oneapp/analytics/shared/utils/validation
+ */
+
+import { logError, logInfo, logWarn } from '@repo/shared/logger';
+
+import { PROVIDER_REQUIREMENTS } from './config';
+
+import type { AnalyticsConfig, ProviderConfig } from '../types/types';
+
+/**
+ * Validation error structure.
+ *
+ * Represents a single validation error with field, message, and provider context.
+ */
+export interface ValidationError {
+  /** Field name that failed validation */
+  field: string;
+  /** Human-readable error message */
+  message: string;
+  /** Provider name (or 'global' for config-level errors) */
+  provider: string;
+}
+
+/**
+ * Validation result structure.
+ *
+ * Contains validation errors, warnings, and overall validity status.
+ */
+export interface ValidationResult {
+  /** Array of validation errors */
+  errors: ValidationError[];
+  /** Whether the configuration is valid (no errors) */
+  isValid: boolean;
+  /** Array of warning messages */
+  warnings: string[];
+}
+
+/**
+ * Comprehensive configuration validation.
+ *
+ * Validates the entire analytics configuration structure, including:
+ * - Configuration object structure
+ * - Providers object existence
+ * - Individual provider configurations
+ * - Environment-specific warnings
+ *
+ * Accepts `unknown` input for defensive validation of potentially malformed configs.
+ *
+ * @param {unknown} config - Analytics configuration to validate
+ * @returns {ValidationResult} Validation result with errors, warnings, and validity status
+ *
+ * @example
+ * ```typescript
+ * const result = validateAnalyticsConfig(config);
+ * if (!result.isValid) {
+ *   console.error('Validation errors:', result.errors);
+ * }
+ * if (result.warnings.length > 0) {
+ *   console.warn('Warnings:', result.warnings);
+ * }
+ * ```
+ */
+export function validateAnalyticsConfig(config: unknown): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: string[] = [];
+
+  // Check if config exists and is an object
+  if (!config || typeof config !== 'object') {
+    errors.push({
+      provider: 'global',
+      field: 'config',
+      message: 'Analytics configuration is required and must be an object',
+    });
+    return { isValid: false, errors, warnings };
+  }
+
+  const typedConfig = config as AnalyticsConfig;
+
+  // Check if providers object exists
+  if (!typedConfig.providers || typeof typedConfig.providers !== 'object') {
+    errors.push({
+      provider: 'global',
+      field: 'providers',
+      message: 'Providers configuration is required and must be an object',
+    });
+    return { isValid: false, errors, warnings };
+  }
+
+  // Check if at least one provider is configured
+  const providerCount = Object.keys(typedConfig.providers).length;
+  if (providerCount === 0) {
+    warnings.push('No providers configured. Analytics will not track any events.');
+  }
+
+  // Validate each provider
+  for (const [providerName, providerConfig] of Object.entries(typedConfig.providers)) {
+    const providerErrors = validateProvider(providerName, providerConfig);
+    errors.push(...providerErrors);
+  }
+
+  // Environment-specific warnings
+  const isBrowser = typeof window !== 'undefined';
+
+  // Mixpanel warning for client-side usage
+  if (isBrowser && typedConfig.providers.mixpanel) {
+    warnings.push(
+      'Mixpanel provider configured on client-side. Consider using server-side for better performance.',
+    );
+  }
+
+  if (!isBrowser && typedConfig.providers.vercel) {
+    warnings.push(
+      'Vercel Analytics has limited server-side support. Consider using client-side for better features.',
+    );
+  }
+
+  return {
+    isValid: errors.length === 0,
+    errors,
+    warnings,
+  };
+}
+
+/**
+ * Validate a single provider configuration.
+ *
+ * Checks that the provider is known and that all required fields are present.
+ *
+ * @param {string} providerName - Name of the provider to validate
+ * @param {ProviderConfig} config - Provider configuration to validate
+ * @returns {ValidationError[]} Array of validation errors (empty if valid)
+ *
+ * @example
+ * ```typescript
+ * const errors = validateProvider('posthog', { apiKey: 'phc_xxx' });
+ * if (errors.length > 0) {
+ *   console.error('Provider errors:', errors);
+ * }
+ * ```
+ */
+export function validateProvider(providerName: string, config: ProviderConfig): ValidationError[] {
+  const errors: ValidationError[] = [];
+
+  // Check if provider is known
+  const knownProviders = ['segment', 'posthog', 'vercel', 'console', 'mixpanel'];
+  if (!knownProviders.includes(providerName)) {
+    errors.push({
+      provider: providerName,
+      field: 'name',
+      message: `Unknown provider '${providerName}'. Known providers: ${knownProviders.join(', ')}`,
+    });
+    return errors;
+  }
+
+  // Check required fields
+  const requiredFields = PROVIDER_REQUIREMENTS[providerName] ?? [];
+  for (const field of requiredFields) {
+    const value = config[field as keyof ProviderConfig];
+
+    if (!value) {
+      errors.push({
+        provider: providerName,
+        field,
+        message: `Required field '${field}' is missing for provider '${providerName}'`,
+      });
+    } else if (typeof value === 'string' && value.trim() === '') {
+      errors.push({
+        provider: providerName,
+        field,
+        message: `Required field '${field}' cannot be empty for provider '${providerName}'`,
+      });
+    }
+  }
+
+  // Provider-specific validation
+  switch (providerName) {
+    case 'segment':
+      if (config.writeKey && !isValidSegmentWriteKey(config.writeKey)) {
+        errors.push({
+          provider: providerName,
+          field: 'writeKey',
+          message: 'Segment writeKey appears to be invalid format',
+        });
+      }
+      break;
+
+    case 'posthog':
+      if (config.apiKey && !isValidPostHogApiKey(config.apiKey)) {
+        errors.push({
+          provider: providerName,
+          field: 'apiKey',
+          message: 'PostHog apiKey appears to be invalid format',
+        });
+      }
+      break;
+  }
+
+  return errors;
+}
+
+/**
+ * Validate environment variables for analytics.
+ *
+ * Checks common analytics environment variables for:
+ * - Empty values
+ * - Placeholder text
+ * - Development environment warnings
+ *
+ * @returns {ValidationResult} Validation result with warnings about environment variables
+ *
+ * @example
+ * ```typescript
+ * const result = validateEnvironmentVariables();
+ * if (result.warnings.length > 0) {
+ *   console.warn('Environment warnings:', result.warnings);
+ * }
+ * ```
+ */
+export function validateEnvironmentVariables(): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: string[] = [];
+
+  // Check for common environment variables
+  const envVars = {
+    POSTHOG_API_KEY: process.env.POSTHOG_API_KEY,
+    SEGMENT_WRITE_KEY: process.env.SEGMENT_WRITE_KEY,
+  };
+
+  for (const [varName, value] of Object.entries(envVars)) {
+    if (value && typeof value === 'string') {
+      if (value.trim() === '') {
+        warnings.push(`Environment variable ${varName} is set but empty`);
+      } else if (value.includes('your-') || value.includes('paste-')) {
+        warnings.push(`Environment variable ${varName} appears to contain placeholder text`);
+      }
+    }
+  }
+
+  // Warn about development environment
+  if (
+    process.env.NODE_ENV === 'development' &&
+    !envVars.SEGMENT_WRITE_KEY &&
+    !envVars.POSTHOG_API_KEY
+  ) {
+    warnings.push(
+      'No analytics environment variables detected in development. Consider using console provider for debugging.',
+    );
+  }
+
+  return {
+    isValid: errors.length === 0,
+    errors,
+    warnings,
+  };
+}
+
+/**
+ * Validates Segment write key format.
+ *
+ * Checks that the write key matches Segment's expected format:
+ * - Exactly 32 alphanumeric characters
+ * - Not a placeholder value
+ *
+ * @param {string} writeKey - Write key to validate
+ * @returns {boolean} `true` if valid, `false` otherwise
+ *
+ * @internal
+ */
+function isValidSegmentWriteKey(writeKey: string): boolean {
+  // Segment write keys are exactly 32 characters, alphanumeric
+  if (!/^[\dA-Za-z]{32}$/.test(writeKey)) {
+    return false;
+  }
+
+  // Check for common placeholder patterns
+  const placeholders = ['your-write-key', 'paste-key-here', 'xxxxxxxx', 'example'];
+  if (placeholders.some(p => writeKey.toLowerCase().includes(p.toLowerCase()))) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Validates PostHog API key format.
+ *
+ * Checks that the API key matches PostHog's expected format:
+ * - Starts with `phc_` prefix
+ * - Followed by 43 alphanumeric/dash/underscore characters
+ * - Not a placeholder value
+ *
+ * @param {string} apiKey - API key to validate
+ * @returns {boolean} `true` if valid, `false` otherwise
+ *
+ * @internal
+ */
+function isValidPostHogApiKey(apiKey: string): boolean {
+  // PostHog keys: phc_ prefix + 43 alphanumeric/dash/underscore characters
+  if (!/^phc_[\w-]{43}$/.test(apiKey)) {
+    return false;
+  }
+
+  // Check for placeholder patterns
+  const placeholders = ['your-api-key', 'paste-key-here', 'xxxxxxxx', 'example'];
+  if (placeholders.some(p => apiKey.toLowerCase().includes(p.toLowerCase()))) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Utility to throw validation errors (for strict validation).
+ *
+ * Validates the configuration and throws an error if validation fails.
+ * Useful for ensuring configuration is valid before using analytics.
+ *
+ * @param {AnalyticsConfig} config - Analytics configuration to validate
+ * @throws {Error} If configuration validation fails
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   validateConfigOrThrow(config);
+ *   // Configuration is valid, proceed
+ * } catch (error) {
+ *   console.error('Invalid config:', error.message);
+ * }
+ * ```
+ */
+export function validateConfigOrThrow(config: AnalyticsConfig): void {
+  const result = validateAnalyticsConfig(config);
+
+  if (!result.isValid) {
+    const errorMessages = result.errors
+      .map(error => `${error.provider}.${error.field}: ${error.message}`)
+      .join('\n');
+
+    throw new Error(`Analytics configuration validation failed:\n${errorMessages}`);
+  }
+
+  // Log warnings but don't throw
+  if (result.warnings.length > 0 && config.onError) {
+    config.onError(new Error('Analytics configuration warnings'), {
+      provider: 'analytics',
+      method: 'validateConfig',
+      warnings: result.warnings,
+    });
+  }
+}
+
+/**
+ * Development helper to check configuration.
+ *
+ * Logs configuration details and validation results for debugging.
+ * Only useful in development environments.
+ *
+ * @param {AnalyticsConfig} config - Analytics configuration to debug
+ * @returns {Promise<void>} Promise that resolves when debugging is complete
+ *
+ * @example
+ * ```typescript
+ * if (process.env.NODE_ENV === 'development') {
+ *   await debugConfig(config);
+ * }
+ * ```
+ */
+export async function debugConfig(config: AnalyticsConfig): Promise<void> {
+  const result = validateAnalyticsConfig(config);
+
+  logInfo('Analytics Configuration Debug', {
+    config,
+    validationResult: result,
+  });
+
+  if (result.errors.length > 0) {
+    logError('Analytics configuration errors: Validation failed', {
+      errors: result.errors,
+    });
+  }
+
+  if (result.warnings.length > 0) {
+    logWarn('Analytics configuration warnings', { warnings: result.warnings });
+  }
+}

package/src/shared.ts

@@ -0,0 +1,155 @@
+/**
+ * @fileoverview Shared Environment Analytics Exports
+ *
+ * This module provides environment-agnostic analytics functionality for packages
+ * that can run in both client and server environments. It automatically detects
+ * the runtime environment and uses the appropriate analytics implementation.
+ *
+ * **Environment Detection**:
+ * - Detects server vs client environments
+ * - Detects Next.js vs plain Node.js/React environments
+ * - Automatically selects the correct analytics manager
+ *
+ * **Key Features**:
+ * - Single API that works in all environments
+ * - Automatic environment detection
+ * - Type-safe event tracking
+ * - Ecommerce and AI event emitters
+ *
+ * **Usage**: Use this module when you need analytics in code that runs in both
+ * client and server contexts (e.g., shared utilities, isomorphic code).
+ *
+ * @example
+ * ```typescript
+ * // In environment-agnostic code
+ * import { createAnalytics, track } from '@od-oneapp/analytics/shared';
+ *
+ * // Works in both client and server environments
+ * const analytics = await createAnalytics(config);
+ * await analytics.emit(track('Event Name', { property: 'value' }));
+ * ```
+ *
+ * @module @od-oneapp/analytics/shared
+ */
+
+// Import types for proper typing
+import type { AnalyticsConfig, AnalyticsManager } from './shared/types/types';
+
+/**
+ * Detects if code is running in a server environment.
+ *
+ * Checks for absence of `window` object and presence of `global` object.
+ *
+ * @returns {boolean} `true` if running on server, `false` if running in browser
+ *
+ * @internal
+ */
+function isServerEnvironment(): boolean {
+  return typeof window === 'undefined' && typeof global !== 'undefined';
+}
+
+/**
+ * Detects if code is running in a Next.js environment.
+ *
+ * Checks for Next.js-specific environment variables and globals.
+ *
+ * @returns {boolean} `true` if running in Next.js, `false` otherwise
+ *
+ * @internal
+ */
+function isNextJSEnvironment(): boolean {
+  // Check for Next.js-specific environment variables and globals
+  return (
+    // Next.js runtime environment variable
+    process.env.NEXT_RUNTIME !== undefined ||
+    // Next.js data global (client-side)
+    typeof (globalThis as any).__NEXT_DATA__ !== 'undefined' ||
+    // Edge runtime global
+    typeof (globalThis as any).EdgeRuntime !== 'undefined' ||
+    // Next.js process title
+    (typeof process !== 'undefined' && process.title?.includes('next')) ||
+    // Next.js in development mode
+    (typeof process !== 'undefined' &&
+      process.env.NODE_ENV === 'development' &&
+      process.env.NEXT_PUBLIC_APP_ENV !== undefined)
+  );
+}
+
+/**
+ * Creates an analytics manager appropriate for the current environment.
+ *
+ * Automatically detects the runtime environment (server/client, Next.js/plain) and
+ * creates the appropriate analytics manager instance. This allows packages to use
+ * analytics without knowing which environment they're running in.
+ *
+ * @param {AnalyticsConfig} config - Analytics configuration with provider settings
+ * @returns {Promise<AnalyticsManager>} Promise resolving to analytics manager instance
+ *
+ * @example
+ * ```typescript
+ * const analytics = await createAnalytics({
+ *   providers: {
+ *     posthog: { apiKey: process.env.POSTHOG_API_KEY }
+ *   }
+ * });
+ *
+ * await analytics.emit(track('User Action', { action: 'click' }));
+ * ```
+ */
+export async function createAnalytics(config: AnalyticsConfig): Promise<AnalyticsManager> {
+  const isServer = isServerEnvironment();
+  const isNextJS = isNextJSEnvironment();
+
+  if (isServer) {
+    if (isNextJS) {
+      const { createServerAnalytics } = await import('./server-next');
+      return createServerAnalytics(config);
+    } else {
+      const { createServerAnalytics } = await import('./server');
+      return createServerAnalytics(config);
+    }
+  } else {
+    if (isNextJS) {
+      const { createNextJSClientAnalytics } = await import('./client-next');
+      return createNextJSClientAnalytics(config);
+    } else {
+      const { createClientAnalytics } = await import('./client');
+      return createClientAnalytics(config);
+    }
+  }
+}
+
+// Re-export essential types that shared packages need
+export type {
+  AnalyticsConfig,
+  AnalyticsContext,
+  AnalyticsManager,
+  AnalyticsProvider,
+  ProviderConfig,
+  TrackingOptions,
+} from './shared/types/types';
+
+// Re-export emitters for environment-agnostic usage
+export { aiSdk as ai, alias, ecommerce, group, identify, page, track } from './shared/emitters';
+
+/**
+ * Environment information for debugging and introspection.
+ *
+ * Provides runtime information about the current environment, useful for debugging
+ * and conditional logic based on environment.
+ *
+ * @example
+ * ```typescript
+ * import { environmentInfo } from '@od-oneapp/analytics/shared';
+ *
+ * console.log('Running on server:', environmentInfo.isServer);
+ * console.log('Next.js environment:', environmentInfo.isNextJS);
+ * console.log('Runtime:', environmentInfo.runtime);
+ * ```
+ */
+export const environmentInfo = {
+  isServer: isServerEnvironment(),
+  isNextJS: isNextJSEnvironment(),
+  runtime: typeof process !== 'undefined' ? (process.env.NEXT_RUNTIME ?? 'node') : 'browser',
+  nodeEnv: typeof process !== 'undefined' ? process.env.NODE_ENV : 'production',
+};

package/src/types/index.ts

@@ -0,0 +1,62 @@
+/**
+ * @fileoverview Analytics types exports
+ *
+ * This module re-exports all analytics-related types for convenient importing.
+ * It includes:
+ *
+ * - **Core Types**: AnalyticsConfig, AnalyticsManager, AnalyticsProvider, etc.
+ * - **Emitter Types**: EmitterPayload, EmitterTrackPayload, EmitterIdentifyPayload, etc.
+ * - **Provider Types**: PostHogConfig, SegmentConfig, VercelConfig, ConsoleConfig
+ * - **Ecommerce Types**: BaseProductProperties, CartProperties, OrderProperties, etc.
+ *
+ * **Usage**: Import types from `@od-oneapp/analytics/types` for type annotations.
+ *
+ * @example
+ * ```typescript
+ * import type { AnalyticsConfig, AnalyticsManager } from '@od-oneapp/analytics/types';
+ *
+ * const config: AnalyticsConfig = {
+ *   providers: { posthog: { apiKey: '...' } }
+ * };
+ * ```
+ *
+ * @module @od-oneapp/analytics/types
+ */
+
+// Core analytics types
+export type {
+  AnalyticsConfig,
+  AnalyticsContext,
+  AnalyticsManager,
+  AnalyticsProvider,
+  ProviderConfig,
+  ProviderRegistry,
+  TrackingOptions,
+} from '../shared/types/types';
+
+// Emitter types
+export type {
+  EmitterAliasPayload,
+  EmitterContext,
+  EmitterGroupPayload,
+  EmitterIdentifyPayload,
+  EmitterOptions,
+  EmitterPagePayload,
+  EmitterPayload,
+  EmitterTrackPayload,
+} from '../shared/emitters/emitter-types';
+
+// Provider-specific types
+export type { ConsoleConfig, ConsoleOptions } from '../shared/types/console-types';
+export type { BootstrapData, PostHogConfig, PostHogOptions } from '../shared/types/posthog-types';
+export type { SegmentConfig, SegmentOptions } from '../shared/types/segment-types';
+export type { VercelConfig, VercelOptions } from '../shared/types/vercel-types';
+
+// Ecommerce types
+export type {
+  BaseProductProperties,
+  CartProperties,
+  EcommerceEventSpec,
+  ExtendedProductProperties,
+  OrderProperties,
+} from '../shared/emitters/ecommerce/types';