@od-oneapp/analytics 2026.1.1301

package/src/providers/posthog/server.ts

@@ -0,0 +1,329 @@
+/**
+ * @fileoverview PostHog server-side (Node.js) provider implementation
+ *
+ * Provides server-side integration with PostHog Analytics including feature flags support.
+ * Supports full PostHog tracking including capture, identify, group, alias, and feature flags.
+ *
+ * @remarks
+ * This provider:
+ * - Uses PostHog Node.js SDK for server-side tracking
+ * - Supports feature flags and experiments
+ * - Optimized for Next.js server components
+ * - Integrates with PostHog's API endpoint
+ *
+ * @module @repo/analytics/providers/posthog/server
+ */
+
+import type {
+  BootstrapData,
+  EnhancedPostHogProvider,
+  ExperimentInfo,
+  PostHogConfig,
+} from './types';
+import type { AnalyticsProvider, ProviderConfig } from '../../shared/types/types';
+
+export class PostHogServerProvider implements AnalyticsProvider, Partial<EnhancedPostHogProvider> {
+  readonly name = 'posthog';
+  private config: PostHogConfig;
+  private client: any = null;
+  private isInitialized = false;
+
+  constructor(config: ProviderConfig) {
+    if (!config.apiKey) {
+      throw new Error('PostHog apiKey is required');
+    }
+
+    this.config = {
+      apiKey: config.apiKey,
+      options: {
+        // Server-side optimizations for Next.js
+        flushAt: 1,
+        flushInterval: 0,
+        ...config.options,
+      },
+    };
+  }
+
+  async initialize(): Promise<void> {
+    if (this.isInitialized) return;
+
+    try {
+      // Dynamically import PostHog Node.js SDK
+      const { PostHog } = await import('posthog-node');
+
+      // Extract client-side only options that don't apply to server
+      const {
+        api_host: _api_host,
+        autocapture: _autocapture,
+        bootstrap: _bootstrap,
+        capture_pageview: _capture_pageview,
+        cross_subdomain_cookie: _cross_subdomain_cookie,
+        disable_session_recording: _disable_session_recording,
+        fetch_options: _fetch_options,
+        loaded: _loaded,
+        persistence: _persistence,
+        ui_host: _ui_host,
+        ...serverOptions
+      } = this.config.options ?? {};
+
+      this.client = new PostHog(this.config.apiKey, {
+        host: 'https://app.posthog.com',
+        ...serverOptions,
+      });
+
+      this.isInitialized = true;
+    } catch {
+      throw new Error('PostHog Node.js SDK not available. Install with: npm install posthog-node');
+    }
+  }
+
+  async track(event: string, properties: any = {}): Promise<void> {
+    if (!this.isInitialized || !this.client) {
+      return;
+    }
+
+    try {
+      this.client.capture({
+        distinctId: properties.userId ?? properties.distinctId ?? 'anonymous',
+        event,
+        properties,
+      });
+    } catch {
+      // Silently fail to avoid disrupting app flow
+    }
+  }
+
+  async identify(userId: string, traits: any = {}): Promise<void> {
+    if (!this.isInitialized || !this.client) {
+      return;
+    }
+
+    try {
+      this.client.identify({
+        distinctId: userId,
+        properties: traits,
+      });
+    } catch {
+      // Silently fail to avoid disrupting app flow
+    }
+  }
+
+  async page(name?: string, properties: any = {}): Promise<void> {
+    if (!this.isInitialized || !this.client) {
+      return;
+    }
+
+    try {
+      this.client.capture({
+        distinctId: properties.userId ?? properties.distinctId ?? 'anonymous',
+        event: '$pageview',
+        properties: {
+          $current_url: properties.url,
+          $title: name,
+          ...properties,
+        },
+      });
+    } catch {
+      // Silently fail to avoid disrupting app flow
+    }
+  }
+
+  async group(groupId: string, traits: any = {}): Promise<void> {
+    if (!this.isInitialized || !this.client) {
+      return;
+    }
+
+    try {
+      this.client.groupIdentify({
+        groupKey: groupId,
+        groupType: 'company',
+        properties: traits,
+      });
+    } catch {
+      // Silently fail to avoid disrupting app flow
+    }
+  }
+
+  async alias(userId: string, previousId: string): Promise<void> {
+    if (!this.isInitialized || !this.client) {
+      return;
+    }
+
+    try {
+      this.client.alias({
+        alias: previousId,
+        distinctId: userId,
+      });
+    } catch {
+      // Silently fail to avoid disrupting app flow
+    }
+  }
+
+  // Feature Flag Methods (Server-Side)
+  async getAllFlags(userId: string): Promise<Record<string, any>> {
+    if (!this.isInitialized || !this.client) {
+      return {};
+    }
+
+    if (!userId) {
+      return {};
+    }
+
+    try {
+      const flags = await this.client.getAllFlags(userId);
+      return flags ?? {};
+    } catch {
+      return {};
+    }
+  }
+
+  async getFeatureFlag(flag: string, userId: string): Promise<any> {
+    if (!this.isInitialized || !this.client) {
+      return false;
+    }
+
+    if (!userId) {
+      return false;
+    }
+
+    try {
+      return await this.client.getFeatureFlag(flag, userId);
+    } catch {
+      return false;
+    }
+  }
+
+  async isFeatureEnabled(flag: string, userId: string): Promise<boolean> {
+    if (!this.isInitialized || !this.client) {
+      return false;
+    }
+
+    if (!userId) {
+      return false;
+    }
+
+    try {
+      const flagValue = await this.client.isFeatureEnabled(flag, userId);
+      return Boolean(flagValue);
+    } catch {
+      return false;
+    }
+  }
+
+  async getFeatureFlagPayload(flag: string, userId?: string): Promise<any | null> {
+    if (!this.isInitialized || !this.client) {
+      return null;
+    }
+
+    if (!userId) {
+      return null;
+    }
+
+    try {
+      const payload = await this.client.getFeatureFlagPayload(flag, userId);
+      return payload ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  async getActiveExperiments(userId: string): Promise<ExperimentInfo[]> {
+    if (!this.isInitialized || !this.client) {
+      return [];
+    }
+
+    if (!userId) {
+      return [];
+    }
+
+    try {
+      const flags = await this.getAllFlags(userId);
+      const experiments: ExperimentInfo[] = [];
+
+      for (const [key, variant] of Object.entries(flags)) {
+        if (variant !== false) {
+          const payload = await this.getFeatureFlagPayload(key, userId);
+          experiments.push({
+            key,
+            payload: payload ?? undefined,
+            variant: typeof variant === 'object' ? JSON.stringify(variant) : String(variant),
+          });
+        }
+      }
+
+      return experiments;
+    } catch {
+      return [];
+    }
+  }
+
+  // Bootstrap method - primary use case for server-side
+  async getBootstrapData(distinctId: string): Promise<BootstrapData> {
+    if (!this.isInitialized || !this.client) {
+      return { distinctID: distinctId };
+    }
+
+    try {
+      // Get all flags for the user
+      const featureFlags = await this.getAllFlags(distinctId);
+
+      // Get payloads for flags that have them
+      const featureFlagPayloads: Record<string, any> = {};
+
+      for (const [flagKey, flagValue] of Object.entries(featureFlags)) {
+        if (flagValue !== false) {
+          try {
+            const payload = await this.getFeatureFlagPayload(flagKey, distinctId);
+            if (payload) {
+              featureFlagPayloads[flagKey] = payload;
+            }
+          } catch {
+            // Continue if individual payload fetch fails - silently ignore
+          }
+        }
+      }
+
+      return {
+        distinctID: distinctId,
+      };
+    } catch {
+      return { distinctID: distinctId };
+    }
+  }
+
+  // Utility Methods
+  reset(): void {
+    // Server-side reset doesn't make sense in the same way as client-side
+    // But we can provide a method for consistency
+  }
+
+  async shutdown(): Promise<void> {
+    if (!this.isInitialized || !this.client) {
+      return;
+    }
+
+    try {
+      await this.client.shutdown();
+    } catch {
+      // Silently fail
+    }
+  }
+
+  // Server-specific helper methods
+  async forceFlush(): Promise<void> {
+    if (!this.isInitialized || !this.client) {
+      return;
+    }
+
+    try {
+      await this.client.flush();
+    } catch {
+      // Silently fail
+    }
+  }
+
+  // Get the PostHog client for advanced usage
+  getClient(): any {
+    return this.client;
+  }
+}

package/src/providers/posthog/types.ts

@@ -0,0 +1,104 @@
+/**
+ * @fileoverview PostHog provider type definitions
+ *
+ * Defines TypeScript types and interfaces for PostHog Analytics provider configuration.
+ * Includes feature flags, experiments, and bootstrap data types.
+ *
+ * @module @repo/analytics/providers/posthog/types
+ */
+
+export interface PostHogConfig {
+  apiKey: string;
+  options?: PostHogOptions | undefined;
+}
+
+interface PostHogOptions {
+  host?: string;
+  autocapture?: boolean;
+  capture_pageview?: boolean;
+  capture_pageleave?: boolean;
+  session_recording?: boolean;
+  debug?: boolean;
+  bootstrap?: BootstrapData;
+  person_profiles?: 'always' | 'never' | 'identified_only';
+  api?: {
+    host?: string;
+  };
+  ui?: {
+    host?: string;
+  };
+  feature_flag_request_timeout_ms?: number;
+  advanced_disable_decide?: boolean;
+  disable_surveys?: boolean;
+  disable_toolbar?: boolean;
+  disable_session_recording?: boolean;
+  property_blacklist?: string[];
+  sanitize_properties?: (properties: any, event: string) => any;
+  request_headers?: Record<string, string>;
+  respect_dnt?: boolean;
+  opt_out_capturing_by_default?: boolean;
+  opt_out_persistence_by_default?: boolean;
+  opt_out_useragent_filter?: boolean;
+  cross_subdomain_cookie?: boolean;
+  persistence?: 'localStorage' | 'cookie' | 'memory' | 'localStorage+cookie';
+  persistence_name?: string;
+  cookie_name?: string;
+  loaded?: (posthog: any) => void;
+  on_xhr_error?: (failedRequest: XMLHttpRequest) => void;
+  mask_all_element_attributes?: boolean;
+  mask_all_text?: boolean;
+  advanced_disable_feature_flags?: boolean;
+  advanced_disable_feature_flags_on_first_load?: boolean;
+  advanced_disable_toolbar_metrics?: boolean;
+  segment?: any;
+  name?: string;
+
+  // Server-specific options
+  flushAt?: number;
+  flushInterval?: number;
+  api_host?: string;
+  ui_host?: string;
+  fetch_options?: any;
+}
+
+export interface BootstrapData {
+  distinctID?: string;
+  isIdentifiedID?: boolean;
+  featureFlags?: Record<string, any>;
+  featureFlagPayloads?: Record<string, any>;
+  sessionRecording?: {
+    endpoint?: string;
+  };
+  surveys?: any[];
+  toolbarParams?: Record<string, any>;
+}
+
+export interface ExperimentInfo {
+  key: string;
+  variant: string | boolean;
+  payload?: any;
+}
+
+export interface EnhancedPostHogProvider {
+  // Feature flag methods
+  isFeatureEnabled(flag: string, userId?: string): Promise<boolean>;
+  getFeatureFlag(flag: string, userId?: string): Promise<any>;
+  getFeatureFlagPayload(flag: string): any;
+  reloadFeatureFlags(): Promise<void>;
+  getAllFlags(userId?: string): Promise<Record<string, any>>;
+
+  // Experiment methods
+  getActiveExperiments(userId?: string): Promise<ExperimentInfo[]>;
+
+  // Bootstrap methods
+  getBootstrapData(distinctId: string): Promise<BootstrapData>;
+
+  // Session methods
+  startSessionRecording(): void;
+  stopSessionRecording(): void;
+
+  // Advanced methods
+  reset(): void;
+  register(properties: Record<string, any>): void;
+  unregister(property: string): void;
+}

package/src/providers/segment/client.ts

@@ -0,0 +1,113 @@
+/**
+ * @fileoverview Segment client-side (browser) provider implementation
+ *
+ * Provides client-side integration with Segment Analytics using @segment/analytics-next.
+ * Supports full Segment.io spec tracking including track, identify, page, group, and alias.
+ *
+ * @remarks
+ * This provider:
+ * - Uses @segment/analytics-next for browser tracking
+ * - Supports dynamic imports to avoid SSR issues
+ * - Handles initialization and event tracking
+ * - Integrates with Segment's CDN and API
+ *
+ * @module @repo/analytics/providers/segment/client
+ */
+
+import { BaseAnalyticsProvider } from '../base-provider';
+
+import type { SegmentConfig } from './types';
+import type {
+  AnalyticsContext,
+  GroupTraits,
+  PageProperties,
+  Properties,
+  ProviderConfig,
+  UserTraits,
+} from '../../shared/types/types';
+
+// Type for AnalyticsBrowser instance
+interface AnalyticsBrowserInstance {
+  track: (event: string, properties?: Properties) => Promise<unknown>;
+  identify: (userId: string, traits?: UserTraits) => Promise<unknown>;
+  page: (name?: string, properties?: PageProperties) => Promise<unknown>;
+  group: (groupId: string, traits?: GroupTraits) => Promise<unknown>;
+  alias: (userId: string, previousId: string) => Promise<unknown>;
+}
+
+export class SegmentClientProvider extends BaseAnalyticsProvider<SegmentConfig> {
+  readonly name = 'segment';
+  private analytics: AnalyticsBrowserInstance | null = null;
+
+  constructor(config: ProviderConfig) {
+    super(config);
+
+    if (!config.writeKey) {
+      throw new Error('Segment writeKey is required');
+    }
+
+    this.config = {
+      options: config.options as Record<string, unknown>,
+      writeKey: config.writeKey,
+    };
+  }
+
+  protected async doInitialize(): Promise<void> {
+    // Dynamically import Segment Analytics Next
+    const { AnalyticsBrowser } = await import(
+      /* webpackChunkName: "segment-analytics-browser" */
+      '@segment/analytics-next'
+    );
+
+    // Initialize Analytics Browser
+    this.analytics = AnalyticsBrowser.load({
+      writeKey: this.config.writeKey,
+      ...this.config.options,
+    }) as unknown as AnalyticsBrowserInstance;
+  }
+
+  protected async doTrack(
+    event: string,
+    properties: Properties,
+    _context?: AnalyticsContext,
+  ): Promise<void> {
+    if (!this.analytics) return;
+    await this.analytics.track(event, properties);
+  }
+
+  protected async doIdentify(
+    userId: string,
+    traits: UserTraits,
+    _context?: AnalyticsContext,
+  ): Promise<void> {
+    if (!this.analytics) return;
+    await this.analytics.identify(userId, traits);
+  }
+
+  protected async doPage(
+    name: string | undefined,
+    properties: PageProperties,
+    _context?: AnalyticsContext,
+  ): Promise<void> {
+    if (!this.analytics) return;
+    await this.analytics.page(name, properties);
+  }
+
+  protected async doGroup(
+    groupId: string,
+    traits: GroupTraits,
+    _context?: AnalyticsContext,
+  ): Promise<void> {
+    if (!this.analytics) return;
+    await this.analytics.group(groupId, traits);
+  }
+
+  protected async doAlias(
+    userId: string,
+    previousId: string,
+    _context?: AnalyticsContext,
+  ): Promise<void> {
+    if (!this.analytics) return;
+    await this.analytics.alias(userId, previousId);
+  }
+}

package/src/providers/segment/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview Segment provider shared logic and exports
+ *
+ * Barrel export file for Segment Analytics provider implementations and types.
+ *
+ * @module @repo/analytics/providers/segment
+ */
+
+// Export provider implementations
+// Export types
+export type * from './types';

package/src/providers/segment/server.ts

@@ -0,0 +1,115 @@
+/**
+ * @fileoverview Segment server-side (Node.js) provider implementation
+ *
+ * Provides server-side integration with Segment Analytics using @segment/analytics-next.
+ * Note: analytics-next supports universal runtime environments including Node.js.
+ *
+ * @remarks
+ * This provider:
+ * - Uses @segment/analytics-next for server-side tracking
+ * - Supports Node.js runtime with flushAt: 1 for immediate sending
+ * - Handles initialization and event tracking
+ * - Integrates with Segment's API endpoint
+ *
+ * @module @repo/analytics/providers/segment/server
+ */
+
+import { BaseAnalyticsProvider } from '../base-provider';
+
+import type { SegmentConfig } from './types';
+import type {
+  AnalyticsContext,
+  GroupTraits,
+  PageProperties,
+  Properties,
+  ProviderConfig,
+  UserTraits,
+} from '../../shared/types/types';
+
+// Type for Analytics server instance
+interface AnalyticsServerInstance {
+  track: (params: { event: string; properties?: Properties }) => Promise<unknown>;
+  identify: (params: { userId: string; traits?: UserTraits }) => Promise<unknown>;
+  page: (params: { name?: string; properties?: PageProperties }) => Promise<unknown>;
+  group: (params: { groupId: string; traits?: GroupTraits }) => Promise<unknown>;
+  alias: (params: { userId: string; previousId: string }) => Promise<unknown>;
+}
+
+export class SegmentServerProvider extends BaseAnalyticsProvider<SegmentConfig> {
+  readonly name = 'segment';
+  private analytics: AnalyticsServerInstance | null = null;
+
+  constructor(config: ProviderConfig) {
+    super(config);
+
+    if (!config.writeKey) {
+      throw new Error('Segment writeKey is required');
+    }
+
+    this.config = {
+      options: config.options as Record<string, unknown>,
+      writeKey: config.writeKey,
+    };
+  }
+
+  protected async doInitialize(): Promise<void> {
+    // Dynamically import Segment Analytics Next
+    // analytics-next supports Node.js runtime with flushAt: 1 for server environments
+    const { Analytics } = await import(
+      /* webpackChunkName: "segment-analytics" */
+      '@segment/analytics-next'
+    );
+
+    this.analytics = new Analytics({
+      writeKey: this.config.writeKey,
+      // Note: flushAt is not supported in @segment/analytics-next
+      // Server-side events are sent immediately by default
+      ...this.config.options,
+    }) as unknown as AnalyticsServerInstance;
+  }
+
+  protected async doTrack(
+    event: string,
+    properties: Properties,
+    _context?: AnalyticsContext,
+  ): Promise<void> {
+    if (!this.analytics) return;
+    await this.analytics.track({ event, properties });
+  }
+
+  protected async doIdentify(
+    userId: string,
+    traits: UserTraits,
+    _context?: AnalyticsContext,
+  ): Promise<void> {
+    if (!this.analytics) return;
+    await this.analytics.identify({ userId, traits });
+  }
+
+  protected async doPage(
+    name: string | undefined,
+    properties: PageProperties,
+    _context?: AnalyticsContext,
+  ): Promise<void> {
+    if (!this.analytics) return;
+    await this.analytics.page({ ...(name && { name }), properties });
+  }
+
+  protected async doGroup(
+    groupId: string,
+    traits: GroupTraits,
+    _context?: AnalyticsContext,
+  ): Promise<void> {
+    if (!this.analytics) return;
+    await this.analytics.group({ groupId, traits });
+  }
+
+  protected async doAlias(
+    userId: string,
+    previousId: string,
+    _context?: AnalyticsContext,
+  ): Promise<void> {
+    if (!this.analytics) return;
+    await this.analytics.alias({ userId, previousId });
+  }
+}