@od-oneapp/analytics 2026.1.1301

package/src/next/types.d.ts

@@ -0,0 +1,220 @@
+/**
+ * @fileoverview TypeScript declarations for Next.js 15 analytics integration
+ *
+ * Provides type definitions for Next.js analytics integration, including:
+ * - Next.js request/response type augmentations
+ * - Analytics event types
+ * - Server action types
+ * - Provider props types
+ * - Hook return types
+ *
+ * @remarks
+ * Type-only imports are used to avoid contamination. Runtime Next.js
+ * dependencies should be provided via dependency injection in implementation files.
+ *
+ * @module @od-oneapp/analytics/next/types
+ */
+
+/// <reference types="react" />
+/// <reference types="next" />
+
+// Type-only import - no runtime dependency
+import type { BootstrapData } from '../shared/types/posthog-types';
+import type { AnalyticsConfig } from '../shared/types/types';
+import type { ReadonlyRequestCookies } from 'next/dist/server/web/spec-extension/adapters/request-cookies';
+
+declare module 'next/server' {
+  interface NextRequest {
+    analytics?: {
+      distinctId?: string;
+      context?: Record<string, any>;
+    };
+  }
+}
+
+declare module 'next/headers' {
+  interface ReadonlyHeaders {
+    getAnalyticsContext(): Record<string, any>;
+    getDistinctId(): string | null;
+  }
+}
+
+// Augment global types for edge runtime
+declare global {
+  namespace NodeJS {
+    interface ProcessEnv {
+      NEXT_PUBLIC_POSTHOG_HOST?: string;
+      NEXT_PUBLIC_POSTHOG_KEY?: string;
+      NEXT_PUBLIC_SEGMENT_WRITE_KEY?: string;
+      NEXT_PUBLIC_VERCEL_ANALYTICS_ID?: string;
+    }
+  }
+
+  interface Window {
+    // PostHog types
+    posthog?: any;
+
+    // Segment types
+    analytics?: any;
+
+    // Custom analytics events
+    analyticsReady?: boolean;
+    onAnalyticsReady?: (callback: () => void) => void;
+  }
+}
+
+// Server Action types
+export type ServerActionResult<T = void> = Promise<{
+  success: boolean;
+  data?: T;
+  error?: string;
+}>;
+
+// Feature flag types with proper typing
+export type TypedFeatureFlags<T extends Record<string, boolean>> = {
+  [K in keyof T]: T[K];
+};
+
+// Analytics event types
+export interface AnalyticsEvent {
+  context?: Record<string, any>;
+  name: string;
+  properties?: Record<string, any>;
+  timestamp?: string;
+}
+
+// Page view event
+export interface PageViewEvent extends AnalyticsEvent {
+  name: 'Page View';
+  properties: {
+    path: string;
+    url: string;
+    title: string;
+    referrer?: string;
+    search?: string;
+    search_params?: Record<string, string>;
+    route_params?: Record<string, string | string[]>;
+  };
+}
+
+// E-commerce event types
+export interface ProductViewEvent extends AnalyticsEvent {
+  name: 'Product Viewed';
+  properties: {
+    product_id: string;
+    product_name: string;
+    price?: number;
+    category?: string;
+    [key: string]: any;
+  };
+}
+
+export interface AddToCartEvent extends AnalyticsEvent {
+  name: 'Product Added to Cart';
+  properties: {
+    product_id: string;
+    product_name: string;
+    price?: number;
+    quantity: number;
+    [key: string]: any;
+  };
+}
+
+export interface CheckoutEvent extends AnalyticsEvent {
+  name: 'Checkout Started';
+  properties: {
+    total: number;
+    item_count: number;
+    [key: string]: any;
+  };
+}
+
+export interface PurchaseEvent extends AnalyticsEvent {
+  name: 'Order Completed';
+  properties: {
+    order_id: string;
+    total: number;
+    item_count: number;
+    [key: string]: any;
+  };
+}
+
+// Form tracking event types
+export interface FormStartEvent extends AnalyticsEvent {
+  name: 'Form Started';
+  properties: {
+    form_name: string;
+  };
+}
+
+export interface FormSubmitEvent extends AnalyticsEvent {
+  name: 'Form Submitted';
+  properties: {
+    form_name: string;
+    field_count?: number;
+  };
+}
+
+export interface FormErrorEvent extends AnalyticsEvent {
+  name: 'Form Error';
+  properties: {
+    form_name: string;
+    error_message: string;
+  };
+}
+
+// Middleware types
+export interface AnalyticsMiddlewareContext {
+  cookies: ReadonlyRequestCookies;
+  geo?: {
+    country?: string;
+    region?: string;
+    city?: string;
+  };
+  headers: Headers;
+  method: string;
+  pathname: string;
+  searchParams: URLSearchParams;
+}
+
+// React component props types
+export interface TrackedComponentProps {
+  'data-analytics-event'?: string;
+  'data-analytics-properties'?: string | Record<string, any>;
+}
+
+// Hook return types
+export interface UseAnalyticsReturn {
+  identify: (userId: string, traits?: any) => void;
+  page: (name?: string, properties?: any) => void;
+  ready: boolean;
+  track: (event: string, properties?: any) => void;
+}
+
+// Provider props types
+export interface AnalyticsProviderProps {
+  autoPageTracking?: boolean;
+  bootstrapData?: BootstrapData;
+  children: React.ReactNode;
+  config: AnalyticsConfig;
+  consentRequired?: boolean;
+  onReady?: () => void;
+  pageTrackingOptions?: {
+    trackSearch?: boolean;
+    trackParams?: boolean;
+    properties?: Record<string, any>;
+    skip?: boolean;
+  };
+}
+
+// Utility types for type-safe event tracking
+export type EventProperties<T extends AnalyticsEvent> = T extends { properties: infer P }
+  ? P
+  : never;
+
+export type EventName<T extends AnalyticsEvent> = T extends { name: infer N } ? N : never;
+
+// Helper type for creating typed track functions
+export type TypedTrackFunction<T extends AnalyticsEvent> = (
+  properties: EventProperties<T>,
+) => void | Promise<void>;

package/src/providers/base-provider.ts

@@ -0,0 +1,419 @@
+/**
+ * @fileoverview Base Analytics Provider
+ *
+ * Abstract base class that implements common provider patterns:
+ * - Initialization state management
+ * - Safe method execution with error handling
+ * - Consistent interface implementation
+ * - Error handling and logging
+ *
+ * **Provider Development**: Providers should extend this class and implement
+ * the abstract methods (`doInitialize`, `doTrack`, `doIdentify`, etc.).
+ *
+ * **Benefits**:
+ * - Consistent error handling across all providers
+ * - Initialization state management
+ * - Safe method execution (checks initialization before calling)
+ * - Error callbacks for logging/reporting
+ *
+ * @module @od-oneapp/analytics/providers/base-provider
+ */
+
+import type {
+  AnalyticsContext,
+  AnalyticsProvider,
+  GroupTraits,
+  PageProperties,
+  Properties,
+  ProviderConfig,
+  UserTraits,
+} from '../shared/types/types';
+
+/**
+ * Error handler type for provider operations.
+ *
+ * Called when an error occurs during provider operations. Receives the error
+ * and context about which provider and method failed.
+ *
+ * @param {unknown} error - The error that occurred
+ * @param {object} context - Context about the error (provider name, method name, metadata)
+ */
+export type ProviderErrorHandler = (
+  error: unknown,
+  context: {
+    provider: string;
+    method: string;
+    [key: string]: unknown;
+  },
+) => void;
+
+/**
+ * Base configuration for all providers.
+ *
+ * Common configuration options that all providers support.
+ */
+export interface BaseProviderConfig {
+  /** Error handler callback */
+  onError?: ProviderErrorHandler;
+  /** Enable debug mode */
+  debug?: boolean;
+}
+
+/**
+ * Abstract base class for analytics providers
+ *
+ * @example
+ * ```typescript
+ * class MyProvider extends BaseAnalyticsProvider<MyConfig> {
+ *   readonly name = 'my-provider';
+ *
+ *   protected async doInitialize(): Promise<void> {
+ *     // Load SDK and set up client
+ *   }
+ *
+ *   protected async doTrack(event: string, properties: Properties): Promise<void> {
+ *     // Call SDK track method
+ *   }
+ *
+ *   // ... implement other abstract methods
+ * }
+ * ```
+ */
+export abstract class BaseAnalyticsProvider<
+  TConfig extends BaseProviderConfig = BaseProviderConfig,
+> implements AnalyticsProvider {
+  /** Provider name used for identification and logging */
+  abstract readonly name: string;
+
+  /** Provider-specific configuration */
+  protected config: TConfig;
+
+  /** Whether the provider has been initialized */
+  protected isInitialized = false;
+
+  /** Error handler for logging/reporting errors */
+  protected onError?: ProviderErrorHandler | undefined;
+
+  constructor(config: ProviderConfig, defaultConfig: Partial<TConfig> = {}) {
+    this.config = {
+      ...defaultConfig,
+      ...config,
+      ...(config.options as Partial<TConfig>),
+    } as TConfig;
+    this.onError = this.config.onError ?? undefined;
+  }
+
+  /**
+   * Initialize the provider.
+   *
+   * This is called by the analytics manager before any tracking calls.
+   * Calls the abstract `doInitialize()` method and handles errors.
+   *
+   * @param {ProviderConfig} [config] - Optional provider configuration
+   * @returns {Promise<void>} Promise that resolves when initialization is complete
+   * @throws {Error} If initialization fails
+   */
+  async initialize(config?: ProviderConfig): Promise<void> {
+    if (this.isInitialized) return;
+
+    try {
+      await this.doInitialize(config);
+      this.isInitialized = true;
+    } catch (error) {
+      this.handleError(error, 'initialize');
+      throw error; // Re-throw to let manager know initialization failed
+    }
+  }
+
+  /**
+   * Track an event.
+   *
+   * Validates that the provider is initialized, then calls the abstract
+   * `doTrack()` method. Handles errors gracefully without throwing.
+   *
+   * @param {string} event - Event name
+   * @param {Properties} [properties] - Event properties
+   * @param {AnalyticsContext} [context] - Analytics context
+   * @returns {Promise<void>} Promise that resolves when tracking is complete
+   */
+  async track(
+    event: string,
+    properties: Properties = {},
+    context?: AnalyticsContext,
+  ): Promise<void> {
+    if (!this.isInitialized) {
+      this.handleError(new Error('Provider not initialized'), 'track', { event });
+      return;
+    }
+
+    try {
+      await this.doTrack(event, properties, context);
+    } catch (error) {
+      this.handleError(error, 'track', { event, properties });
+    }
+  }
+
+  /**
+   * Identify a user.
+   *
+   * Validates that the provider is initialized, then calls the abstract
+   * `doIdentify()` method. Handles errors gracefully without throwing.
+   *
+   * @param {string} userId - User identifier
+   * @param {UserTraits} [traits] - User traits
+   * @param {AnalyticsContext} [context] - Analytics context
+   * @returns {Promise<void>} Promise that resolves when identification is complete
+   */
+  async identify(
+    userId: string,
+    traits: UserTraits = {},
+    context?: AnalyticsContext,
+  ): Promise<void> {
+    if (!this.isInitialized) {
+      this.handleError(new Error('Provider not initialized'), 'identify', { userId });
+      return;
+    }
+
+    try {
+      await this.doIdentify(userId, traits, context);
+    } catch (error) {
+      this.handleError(error, 'identify', { userId });
+    }
+  }
+
+  /**
+   * Track a page view.
+   *
+   * Validates that the provider is initialized, then calls the abstract
+   * `doPage()` method. Handles errors gracefully.
+   *
+   * @param {string} [name] - Page name
+   * @param {PageProperties} [properties] - Page properties
+   * @param {AnalyticsContext} [context] - Analytics context
+   * @returns {Promise<void>} Promise that resolves when page tracking is complete
+   */
+  async page(
+    name?: string,
+    properties: PageProperties = {},
+    context?: AnalyticsContext,
+  ): Promise<void> {
+    if (!this.isInitialized) {
+      this.handleError(new Error('Provider not initialized'), 'page', { name });
+      return;
+    }
+
+    try {
+      await this.doPage(name, properties, context);
+    } catch (error) {
+      this.handleError(error, 'page', { name });
+    }
+  }
+
+  /**
+   * Associate user with a group.
+   *
+   * Validates that the provider is initialized, then calls the abstract
+   * `doGroup()` method. Handles errors gracefully.
+   *
+   * @param {string} groupId - Group identifier
+   * @param {GroupTraits} [traits] - Group traits
+   * @param {AnalyticsContext} [context] - Analytics context
+   * @returns {Promise<void>} Promise that resolves when group association is complete
+   */
+  async group(
+    groupId: string,
+    traits: GroupTraits = {},
+    context?: AnalyticsContext,
+  ): Promise<void> {
+    if (!this.isInitialized) {
+      this.handleError(new Error('Provider not initialized'), 'group', { groupId });
+      return;
+    }
+
+    try {
+      await this.doGroup(groupId, traits, context);
+    } catch (error) {
+      this.handleError(error, 'group', { groupId });
+    }
+  }
+
+  /**
+   * Alias one user ID to another.
+   *
+   * Validates that the provider is initialized, then calls the abstract
+   * `doAlias()` method. Handles errors gracefully.
+   *
+   * @param {string} userId - New user identifier
+   * @param {string} previousId - Previous user identifier
+   * @param {AnalyticsContext} [context] - Analytics context
+   * @returns {Promise<void>} Promise that resolves when aliasing is complete
+   */
+  async alias(userId: string, previousId: string, context?: AnalyticsContext): Promise<void> {
+    if (!this.isInitialized) {
+      this.handleError(new Error('Provider not initialized'), 'alias', { userId, previousId });
+      return;
+    }
+
+    try {
+      await this.doAlias(userId, previousId, context);
+    } catch (error) {
+      this.handleError(error, 'alias', { userId, previousId });
+    }
+  }
+
+  /**
+   * Set global context for the provider
+   */
+  setContext?(context: AnalyticsContext): void;
+
+  /**
+   * Handle errors consistently across all methods.
+   *
+   * Calls the error handler callback if configured. Errors are swallowed
+   * in production to not disrupt app flow, but logged via callback.
+   *
+   * @param {unknown} error - The error that occurred
+   * @param {string} method - Method name where error occurred
+   * @param {Record<string, unknown>} [metadata] - Additional error metadata
+   *
+   * @internal
+   */
+  protected handleError(error: unknown, method: string, metadata?: Record<string, unknown>): void {
+    if (this.onError) {
+      this.onError(error, {
+        provider: this.name,
+        method,
+        ...metadata,
+      });
+    }
+    // In production, errors are swallowed to not disrupt app flow
+    // Logging happens via onError callback if provided
+  }
+
+  /**
+   * Check if provider is ready to accept tracking calls.
+   *
+   * @returns {boolean} `true` if provider is initialized and ready, `false` otherwise
+   */
+  isReady(): boolean {
+    return this.isInitialized;
+  }
+
+  // ============================================================================
+  // ABSTRACT METHODS - Must be implemented by subclasses
+  // ============================================================================
+
+  /**
+   * Perform provider-specific initialization.
+   *
+   * Called by `initialize()` after checking `isInitialized` flag.
+   * Subclasses must implement this to perform actual provider initialization.
+   *
+   * @param {ProviderConfig} [config] - Optional provider configuration
+   * @returns {Promise<void>} Promise that resolves when initialization is complete
+   *
+   * @protected
+   * @abstract
+   */
+  protected abstract doInitialize(config?: ProviderConfig): Promise<void>;
+
+  /**
+   * Perform provider-specific track call.
+   *
+   * Called by `track()` after validation. Subclasses must implement this
+   * to perform actual event tracking.
+   *
+   * @param {string} event - Event name
+   * @param {Properties} properties - Event properties
+   * @param {AnalyticsContext} [context] - Analytics context
+   * @returns {Promise<void>} Promise that resolves when tracking is complete
+   *
+   * @protected
+   * @abstract
+   */
+  protected abstract doTrack(
+    event: string,
+    properties: Properties,
+    context?: AnalyticsContext,
+  ): Promise<void>;
+
+  /**
+   * Perform provider-specific identify call.
+   *
+   * Called by `identify()` after validation. Subclasses must implement this
+   * to perform actual user identification.
+   *
+   * @param {string} userId - User identifier
+   * @param {UserTraits} traits - User traits
+   * @param {AnalyticsContext} [context] - Analytics context
+   * @returns {Promise<void>} Promise that resolves when identification is complete
+   *
+   * @protected
+   * @abstract
+   */
+  protected abstract doIdentify(
+    userId: string,
+    traits: UserTraits,
+    context?: AnalyticsContext,
+  ): Promise<void>;
+
+  /**
+   * Perform provider-specific page call.
+   *
+   * Called by `page()` after validation. Subclasses must implement this
+   * to perform actual page view tracking.
+   *
+   * @param {string | undefined} name - Page name
+   * @param {PageProperties} properties - Page properties
+   * @param {AnalyticsContext} [context] - Analytics context
+   * @returns {Promise<void>} Promise that resolves when page tracking is complete
+   *
+   * @protected
+   * @abstract
+   */
+  protected abstract doPage(
+    name: string | undefined,
+    properties: PageProperties,
+    context?: AnalyticsContext,
+  ): Promise<void>;
+
+  /**
+   * Perform provider-specific group call.
+   *
+   * Called by `group()` after validation. Subclasses must implement this
+   * to perform actual group association.
+   *
+   * @param {string} groupId - Group identifier
+   * @param {GroupTraits} traits - Group traits
+   * @param {AnalyticsContext} [context] - Analytics context
+   * @returns {Promise<void>} Promise that resolves when group association is complete
+   *
+   * @protected
+   * @abstract
+   */
+  protected abstract doGroup(
+    groupId: string,
+    traits: GroupTraits,
+    context?: AnalyticsContext,
+  ): Promise<void>;
+
+  /**
+   * Perform provider-specific alias call.
+   *
+   * Called by `alias()` after validation. Subclasses must implement this
+   * to perform actual user ID aliasing.
+   *
+   * @param {string} userId - New user identifier
+   * @param {string} previousId - Previous user identifier
+   * @param {AnalyticsContext} [context] - Analytics context
+   * @returns {Promise<void>} Promise that resolves when aliasing is complete
+   *
+   * @protected
+   * @abstract
+   */
+  protected abstract doAlias(
+    userId: string,
+    previousId: string,
+    context?: AnalyticsContext,
+  ): Promise<void>;
+}

package/src/providers/console/client.ts

@@ -0,0 +1,10 @@
+/**
+ * @fileoverview Console provider for client/browser environments
+ *
+ * Provides console-based analytics logging for development and debugging.
+ * Useful for testing analytics events without sending data to external services.
+ *
+ * @module @od-oneapp/analytics/providers/console/client
+ */
+
+export { ConsoleProvider } from '.';