@od-oneapp/analytics 2026.1.1301

package/src/providers/console/index.ts

@@ -0,0 +1,152 @@
+/**
+ * @fileoverview Console provider - works in both client and server environments
+ *
+ * Provides console-based analytics logging for development and debugging.
+ * Useful for testing analytics events without sending data to external services.
+ *
+ * @remarks
+ * This provider:
+ * - Logs analytics events to console
+ * - Works in both browser and Node.js environments
+ * - Useful for development and debugging
+ * - Integrates with observability package for structured logging
+ *
+ * @module @od-oneapp/analytics/providers/console
+ */
+
+import { logDebug, logWarn } from '@repo/shared/logger';
+
+import type { ConsoleConfig } from './types';
+import type { AnalyticsProvider, ProviderConfig } from '../../shared/types/types';
+
+export class ConsoleProvider implements AnalyticsProvider {
+  readonly name = 'console';
+  private config: ConsoleConfig;
+  private isInitialized = false;
+
+  constructor(config: ProviderConfig) {
+    const options = config.options as ConsoleConfig | undefined;
+    this.config = {
+      prefix: '[Analytics]',
+      logLevel: 'info',
+      colorize: false,
+      ...options,
+    };
+  }
+
+  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,
+      });
+    }
+
+    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;
+
+    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/providers/console/server.ts

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Console provider for server/Node.js environments
+ * Console provider for server/Node.js environments
+ */
+
+export { ConsoleProvider } from '.';

package/src/providers/console/types.ts

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview Console provider type definitions
+ *
+ * Defines TypeScript types and interfaces for Console analytics provider configuration.
+ *
+ * @module @od-oneapp/analytics/providers/console/types
+ */
+
+export interface ConsoleConfig {
+  // Console provider doesn't need configuration
+  // All options are optional
+  prefix?: string;
+  logLevel?: 'debug' | 'info' | 'warn' | 'error';
+  colorize?: boolean;
+}

package/src/providers/http/client.ts

@@ -0,0 +1,464 @@
+/**
+ * @fileoverview HTTP provider for browser/client environments
+ *
+ * Provides HTTP-based analytics event sending for client-side applications.
+ * Sends events to a remote ingestion endpoint (e.g., oneapp-api/ingest).
+ *
+ * Features:
+ * - Event batching for efficiency
+ * - Automatic flush on interval, batch size, or page unload
+ * - Retry with exponential backoff
+ * - Anonymous ID persistence in localStorage
+ * - Offline queue support (events queued when offline)
+ *
+ * @module @od-oneapp/analytics/providers/http/client
+ */
+
+import { logInfo, logWarn, logError } from '@repo/shared/logs';
+
+import type { HttpProviderConfig, IngestionResponse, QueuedEvent } from './types';
+import type {
+  AnalyticsContext,
+  AnalyticsProvider,
+  GroupTraits,
+  PageProperties,
+  Properties,
+  ProviderConfig,
+  UserTraits,
+} from '../../shared/types/types';
+
+/** Default configuration values */
+const DEFAULTS = {
+  batchSize: 10,
+  flushInterval: 5000,
+  timeout: 10000,
+  retries: 3,
+} as const;
+
+/** Base delay for exponential backoff in ms */
+const BACKOFF_BASE_MS = 1000;
+
+/** LocalStorage key for anonymous ID */
+const ANON_ID_KEY = 'analytics_anonymous_id';
+
+/**
+ * HTTP Analytics Provider for browser environments.
+ *
+ * Sends analytics events to a remote endpoint via HTTP POST requests.
+ * Events are batched and flushed periodically for efficiency.
+ *
+ * @example
+ * ```typescript
+ * const provider = new HttpClientProvider({
+ *   options: {
+ *     endpoint: 'https://api.oneapp.dev/v1/ingest',
+ *     apiKey: process.env.NEXT_PUBLIC_ANALYTICS_API_KEY,
+ *   },
+ * });
+ * await provider.initialize();
+ * await provider.track('Button Clicked', { button: 'signup' });
+ * ```
+ */
+export class HttpClientProvider implements AnalyticsProvider {
+  readonly name = 'http';
+
+  private config: Required<
+    Pick<HttpProviderConfig, 'batchSize' | 'flushInterval' | 'timeout' | 'retries'>
+  > &
+    HttpProviderConfig;
+  private isInitialized = false;
+  private queue: QueuedEvent[] = [];
+  private flushTimer: ReturnType<typeof setInterval> | null = null;
+  private userId?: string;
+  private anonymousId: string;
+  private isFlushing = false;
+
+  constructor(providerConfig: ProviderConfig) {
+    const options = (providerConfig.options ?? {}) as unknown as HttpProviderConfig;
+
+    if (!options.endpoint) {
+      throw new Error('HttpProvider requires an endpoint URL');
+    }
+
+    this.config = {
+      ...options,
+      batchSize: options.batchSize ?? DEFAULTS.batchSize,
+      flushInterval: options.flushInterval ?? DEFAULTS.flushInterval,
+      timeout: options.timeout ?? DEFAULTS.timeout,
+      retries: options.retries ?? DEFAULTS.retries,
+    };
+
+    this.userId = options.userId;
+    this.anonymousId = options.anonymousId ?? this.getOrCreateAnonymousId();
+  }
+
+  async initialize(): Promise<void> {
+    if (this.isInitialized) return;
+
+    // Start auto-flush timer if interval > 0
+    if (this.config.flushInterval > 0) {
+      this.flushTimer = setInterval(() => {
+        void this.flush();
+      }, this.config.flushInterval);
+    }
+
+    // Flush on page unload/visibility change
+    if (typeof document !== 'undefined') {
+      document.addEventListener('visibilitychange', this.handleVisibilityChange);
+    }
+
+    if (typeof window !== 'undefined') {
+      window.addEventListener('beforeunload', this.handleBeforeUnload);
+    }
+
+    if (this.config.debug) {
+      this.log('HTTP Analytics Provider initialized', {
+        endpoint: this.config.endpoint,
+        batchSize: this.config.batchSize,
+        flushInterval: this.config.flushInterval,
+      });
+    }
+
+    this.isInitialized = true;
+  }
+
+  async track(
+    event: string,
+    properties: Properties = {},
+    _context?: AnalyticsContext,
+  ): Promise<void> {
+    if (!this.isInitialized) {
+      this.warn('HTTP provider not initialized', { operation: 'track', event });
+      return;
+    }
+
+    this.enqueue({
+      type: 'track',
+      event,
+      properties,
+      timestamp: new Date().toISOString(),
+      userId: this.userId,
+      anonymousId: this.anonymousId,
+    });
+  }
+
+  async identify(
+    userId: string,
+    traits: UserTraits = {},
+    _context?: AnalyticsContext,
+  ): Promise<void> {
+    if (!this.isInitialized) {
+      this.warn('HTTP provider not initialized', { operation: 'identify', userId });
+      return;
+    }
+
+    // Update stored user ID
+    this.userId = userId;
+
+    this.enqueue({
+      type: 'identify',
+      userId,
+      traits,
+      timestamp: new Date().toISOString(),
+      anonymousId: this.anonymousId,
+    });
+  }
+
+  async page(
+    name?: string,
+    properties: PageProperties = {},
+    _context?: AnalyticsContext,
+  ): Promise<void> {
+    if (!this.isInitialized) {
+      this.warn('HTTP provider not initialized', { operation: 'page', name });
+      return;
+    }
+
+    this.enqueue({
+      type: 'page',
+      name,
+      properties,
+      timestamp: new Date().toISOString(),
+      userId: this.userId,
+      anonymousId: this.anonymousId,
+    });
+  }
+
+  async group(
+    groupId: string,
+    traits: GroupTraits = {},
+    _context?: AnalyticsContext,
+  ): Promise<void> {
+    if (!this.isInitialized) {
+      this.warn('HTTP provider not initialized', { operation: 'group', groupId });
+      return;
+    }
+
+    this.enqueue({
+      type: 'group',
+      groupId,
+      traits,
+      timestamp: new Date().toISOString(),
+      userId: this.userId,
+      anonymousId: this.anonymousId,
+    });
+  }
+
+  async alias(userId: string, previousId: string, _context?: AnalyticsContext): Promise<void> {
+    if (!this.isInitialized) {
+      this.warn('HTTP provider not initialized', { operation: 'alias', userId, previousId });
+      return;
+    }
+
+    this.enqueue({
+      type: 'alias',
+      userId,
+      previousId,
+      timestamp: new Date().toISOString(),
+      anonymousId: this.anonymousId,
+    });
+  }
+
+  /**
+   * Flush all queued events to the remote endpoint.
+   * Called automatically on interval, batch size, or page events.
+   */
+  async flush(): Promise<void> {
+    if (this.queue.length === 0 || this.isFlushing) return;
+
+    this.isFlushing = true;
+
+    // Take all events from queue
+    const events = [...this.queue];
+    this.queue = [];
+
+    try {
+      await this.sendBatch(events);
+    } catch (error) {
+      // Re-queue events on failure (they'll be retried on next flush)
+      this.queue.unshift(...events);
+      this.error('Failed to flush events, re-queued for retry', {
+        eventCount: events.length,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    } finally {
+      this.isFlushing = false;
+    }
+  }
+
+  /**
+   * Shutdown the provider gracefully.
+   * Flushes remaining events and removes event listeners.
+   */
+  async shutdown(): Promise<void> {
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+
+    if (typeof document !== 'undefined') {
+      document.removeEventListener('visibilitychange', this.handleVisibilityChange);
+    }
+
+    if (typeof window !== 'undefined') {
+      window.removeEventListener('beforeunload', this.handleBeforeUnload);
+    }
+
+    // Final flush
+    await this.flush();
+    this.isInitialized = false;
+  }
+
+  /**
+   * Get the current queue length (for testing/monitoring).
+   */
+  getQueueLength(): number {
+    return this.queue.length;
+  }
+
+  // ============================================================================
+  // Event Handlers
+  // ============================================================================
+
+  private handleVisibilityChange = (): void => {
+    if (document.visibilityState === 'hidden') {
+      void this.flush();
+    }
+  };
+
+  private handleBeforeUnload = (): void => {
+    // Use sendBeacon for reliable delivery on page unload
+    if (this.queue.length > 0 && typeof navigator?.sendBeacon === 'function') {
+      const payload = JSON.stringify({ batch: this.queue });
+      const headers: Record<string, string> = {
+        type: 'application/json',
+      };
+
+      // Note: sendBeacon doesn't support custom headers, so we include API key in payload
+      // The server should accept it from either header or body
+      const blob = new Blob([payload], headers);
+      navigator.sendBeacon(this.config.endpoint, blob);
+      this.queue = [];
+    }
+  };
+
+  // ============================================================================
+  // Private Methods
+  // ============================================================================
+
+  private enqueue(event: QueuedEvent): void {
+    this.queue.push(event);
+
+    if (this.config.debug) {
+      this.log('Event queued', {
+        type: event.type,
+        queueLength: this.queue.length,
+      });
+    }
+
+    // Flush if batch size reached
+    if (this.queue.length >= this.config.batchSize) {
+      void this.flush();
+    }
+  }
+
+  private async sendBatch(events: QueuedEvent[]): Promise<void> {
+    const payload = { batch: events };
+
+    let lastError: Error | null = null;
+
+    for (let attempt = 0; attempt <= this.config.retries; attempt++) {
+      try {
+        const response = await this.sendRequest(payload);
+
+        if (response.success) {
+          if (this.config.debug) {
+            this.log('Batch sent successfully', {
+              accepted: response.accepted,
+              rejected: response.rejected,
+            });
+          }
+          return;
+        }
+
+        // Request succeeded but ingestion failed
+        this.warn('Batch partially rejected', {
+          accepted: response.accepted,
+          rejected: response.rejected,
+          error: response.error,
+        });
+        return;
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+
+        if (attempt < this.config.retries) {
+          // Exponential backoff: 1s, 2s, 4s, ...
+          const delay = BACKOFF_BASE_MS * Math.pow(2, attempt);
+
+          if (this.config.debug) {
+            this.log('Retrying batch send', {
+              attempt: attempt + 1,
+              maxRetries: this.config.retries,
+              delayMs: delay,
+            });
+          }
+
+          await this.sleep(delay);
+        }
+      }
+    }
+
+    // All retries exhausted
+    throw lastError ?? new Error('Failed to send batch after retries');
+  }
+
+  private async sendRequest(payload: { batch: QueuedEvent[] }): Promise<IngestionResponse> {
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      ...this.config.headers,
+    };
+
+    if (this.config.apiKey) {
+      headers['X-API-Key'] = this.config.apiKey;
+    }
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+
+    try {
+      const response = await fetch(this.config.endpoint, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(payload),
+        signal: controller.signal,
+        // Include credentials for cross-origin requests if needed
+        credentials: 'omit',
+      });
+
+      if (!response.ok) {
+        // Handle rate limiting
+        if (response.status === 429) {
+          const retryAfter = response.headers.get('Retry-After');
+          throw new Error(`Rate limited. Retry after ${retryAfter ?? 'unknown'} seconds`);
+        }
+
+        const errorBody = await response.text();
+        throw new Error(`HTTP ${response.status}: ${errorBody}`);
+      }
+
+      return (await response.json()) as IngestionResponse;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  private getOrCreateAnonymousId(): string {
+    // Try to get from localStorage
+    if (typeof localStorage !== 'undefined') {
+      try {
+        const stored = localStorage.getItem(ANON_ID_KEY);
+        if (stored) return stored;
+
+        const newId = this.generateAnonymousId();
+        localStorage.setItem(ANON_ID_KEY, newId);
+        return newId;
+      } catch {
+        // localStorage not available or blocked
+      }
+    }
+
+    return this.generateAnonymousId();
+  }
+
+  private generateAnonymousId(): string {
+    // Use crypto.randomUUID if available
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+      return crypto.randomUUID();
+    }
+
+    // Fallback
+    return `anon_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 9)}`;
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+
+  // ============================================================================
+  // Logging (browser-compatible)
+  // ============================================================================
+
+  private log(message: string, data?: Record<string, unknown>): void {
+    if (this.config.debug) {
+      logInfo(`[Analytics:HTTP] ${message}`, data);
+    }
+  }
+
+  private warn(message: string, data?: Record<string, unknown>): void {
+    logWarn(`[Analytics:HTTP] ${message}`, data);
+  }
+
+  private error(message: string, data?: Record<string, unknown>): void {
+    logError(`[Analytics:HTTP] ${message}`, data);
+  }
+}

package/src/providers/http/index.ts

@@ -0,0 +1,30 @@
+/**
+ * @fileoverview HTTP Analytics Provider
+ *
+ * Exports HTTP-based analytics providers for sending events to a remote
+ * ingestion endpoint (e.g., oneapp-api's /api/v1/ingest).
+ *
+ * Use `HttpClientProvider` for browser environments and `HttpServerProvider`
+ * for Node.js/server environments.
+ *
+ * @example
+ * ```typescript
+ * // Client-side (browser)
+ * import { HttpClientProvider } from '@od-oneapp/analytics/providers/http/client';
+ *
+ * // Server-side (Node.js)
+ * import { HttpServerProvider } from '@od-oneapp/analytics/providers/http/server';
+ *
+ * // Or import types
+ * import type { HttpProviderConfig } from '@od-oneapp/analytics/providers/http';
+ * ```
+ *
+ * @module @od-oneapp/analytics/providers/http
+ */
+
+export type { HttpProviderConfig, IngestionResponse, QueuedEvent } from './types';
+export { HttpClientProvider } from './client';
+export { HttpServerProvider } from './server';
+
+// Edge-compatible alias - use HttpServerProvider which works in edge environments
+export { HttpServerProvider as HttpProvider } from './server';