@od-oneapp/analytics 2026.1.1301

package/src/providers/http/server.ts

@@ -0,0 +1,396 @@
+/**
+ * @fileoverview HTTP provider for server/Node.js environments
+ *
+ * Provides HTTP-based analytics event sending for server-side applications.
+ * Sends events to a remote ingestion endpoint (e.g., oneapp-api/ingest).
+ *
+ * Features:
+ * - Event batching for efficiency
+ * - Automatic flush on interval or batch size
+ * - Retry with exponential backoff
+ * - Graceful shutdown with final flush
+ *
+ * @module @od-oneapp/analytics/providers/http/server
+ */
+
+import { logDebug, logError, logWarn } 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;
+
+/**
+ * HTTP Analytics Provider for server 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 HttpServerProvider({
+ *   options: {
+ *     endpoint: 'https://api.oneapp.dev/v1/ingest',
+ *     apiKey: process.env.ANALYTICS_API_KEY,
+ *   },
+ * });
+ * await provider.initialize();
+ * await provider.track('Button Clicked', { button: 'signup' });
+ * await provider.flush(); // Send queued events
+ * ```
+ */
+export class HttpServerProvider 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.generateAnonymousId();
+  }
+
+  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);
+
+      // Unref the timer so it doesn't prevent Node.js from exiting
+      if (typeof this.flushTimer.unref === 'function') {
+        this.flushTimer.unref();
+      }
+    }
+
+    if (this.config.debug) {
+      logDebug('HTTP Analytics Provider initialized', {
+        provider: 'http',
+        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) {
+      logWarn('HTTP provider not initialized', { provider: 'http', 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) {
+      logWarn('HTTP provider not initialized', { provider: 'http', 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) {
+      logWarn('HTTP provider not initialized', { provider: 'http', 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) {
+      logWarn('HTTP provider not initialized', { provider: 'http', 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) {
+      logWarn('HTTP provider not initialized', {
+        provider: 'http',
+        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 or when batch size is reached.
+   */
+  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);
+      logError('Failed to flush events, re-queued for retry', {
+        provider: 'http',
+        eventCount: events.length,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    } finally {
+      this.isFlushing = false;
+    }
+  }
+
+  /**
+   * Shutdown the provider gracefully.
+   * Flushes remaining events and stops the flush timer.
+   */
+  async shutdown(): Promise<void> {
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+
+    // Final flush
+    await this.flush();
+    this.isInitialized = false;
+  }
+
+  /**
+   * Get the current queue length (for testing/monitoring).
+   */
+  getQueueLength(): number {
+    return this.queue.length;
+  }
+
+  // ============================================================================
+  // Private Methods
+  // ============================================================================
+
+  private enqueue(event: QueuedEvent): void {
+    this.queue.push(event);
+
+    if (this.config.debug) {
+      logDebug('Event queued', {
+        provider: 'http',
+        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) {
+            logDebug('Batch sent successfully', {
+              provider: 'http',
+              accepted: response.accepted,
+              rejected: response.rejected,
+            });
+          }
+          return;
+        }
+
+        // Request succeeded but ingestion failed
+        logWarn('Batch partially rejected', {
+          provider: 'http',
+          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) {
+            logDebug('Retrying batch send', {
+              provider: 'http',
+              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,
+      });
+
+      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 generateAnonymousId(): string {
+    // Use crypto.randomUUID if available (Node 19+), otherwise fallback
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+      return crypto.randomUUID();
+    }
+
+    // Fallback for older Node versions
+    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));
+  }
+}

package/src/providers/http/types.ts

@@ -0,0 +1,135 @@
+/**
+ * @fileoverview HTTP provider type definitions
+ *
+ * Defines TypeScript types and interfaces for HTTP Analytics provider configuration.
+ * This provider sends events to a remote analytics endpoint (e.g., oneapp-api/ingest).
+ *
+ * @module @od-oneapp/analytics/providers/http/types
+ */
+
+/**
+ * Configuration for the HTTP analytics provider.
+ *
+ * @example
+ * ```typescript
+ * const config: HttpProviderConfig = {
+ *   endpoint: 'https://api.oneapp.dev/v1/ingest',
+ *   apiKey: process.env.ANALYTICS_API_KEY,
+ *   batchSize: 10,
+ *   flushInterval: 5000,
+ * };
+ * ```
+ */
+export interface HttpProviderConfig {
+  /**
+   * The URL of the analytics ingestion endpoint.
+   * Must be a valid HTTPS URL in production.
+   *
+   * @example 'https://api.oneapp.dev/v1/ingest'
+   */
+  endpoint: string;
+
+  /**
+   * API key for authentication.
+   * Sent as X-API-Key header.
+   * Optional if the endpoint is configured for open mode.
+   */
+  apiKey?: string;
+
+  /**
+   * Number of events to batch before sending.
+   * Events are queued until this threshold is reached or flushInterval expires.
+   *
+   * @default 10
+   */
+  batchSize?: number;
+
+  /**
+   * Interval in milliseconds to auto-flush queued events.
+   * Set to 0 to disable auto-flush (manual flush only).
+   *
+   * @default 5000
+   */
+  flushInterval?: number;
+
+  /**
+   * Request timeout in milliseconds.
+   *
+   * @default 10000
+   */
+  timeout?: number;
+
+  /**
+   * Number of retry attempts on failed requests.
+   * Uses exponential backoff between retries.
+   *
+   * @default 3
+   */
+  retries?: number;
+
+  /**
+   * Additional headers to include in requests.
+   * Note: X-API-Key and Content-Type are set automatically.
+   */
+  headers?: Record<string, string>;
+
+  /**
+   * Enable debug logging for HTTP requests.
+   *
+   * @default false
+   */
+  debug?: boolean;
+
+  /**
+   * User ID to include with all events.
+   * Can be set after initialization via identify().
+   */
+  userId?: string;
+
+  /**
+   * Anonymous ID for unidentified users.
+   * Auto-generated if not provided.
+   */
+  anonymousId?: string;
+}
+
+/**
+ * Internal event queue item structure.
+ * @internal
+ */
+export interface QueuedEvent {
+  type: 'track' | 'identify' | 'page' | 'screen' | 'group' | 'alias';
+  timestamp: string;
+  userId?: string;
+  anonymousId?: string;
+  // Track events
+  event?: string;
+  properties?: Record<string, unknown>;
+  // Identify events
+  traits?: Record<string, unknown>;
+  // Page/screen events
+  name?: string;
+  category?: string;
+  // Group events
+  groupId?: string;
+  // Alias events
+  previousId?: string;
+}
+
+/**
+ * Response from the ingestion endpoint.
+ */
+export interface IngestionResponse {
+  success: boolean;
+  accepted?: number;
+  rejected?: number;
+  results?: Array<{
+    id: string;
+    type: string;
+    status: 'accepted' | 'rejected';
+    error?: string;
+  }>;
+  receivedAt?: string;
+  error?: string;
+  code?: string;
+}