@od-oneapp/analytics 2026.1.1301

package/src/shared/utils/posthog-bootstrap.ts

@@ -0,0 +1,136 @@
+/**
+ * @fileoverview PostHog bootstrap utilities for Next.js server-side rendering
+ * PostHog bootstrap utilities for Next.js server-side rendering
+ * Enables consistent feature flag delivery from server to client
+ */
+
+import type { BootstrapData, PostHogCookie } from '../types/posthog-types';
+
+/**
+ * Generate a unique distinct ID (compatible with PostHog format)
+ */
+export function generateDistinctId(): string {
+  // Use a similar format to PostHog's default distinct ID generation
+  const timestamp = Date.now().toString(36);
+  const randomStr = Math.random().toString(36).slice(2, 15);
+  return `${timestamp}-${randomStr}`;
+}
+
+/**
+ * Parse PostHog cookie to extract distinct ID
+ */
+export function parsePostHogCookie(
+  cookieValue: string,
+  _projectApiKey: string,
+): PostHogCookie | null {
+  try {
+    const parsed = JSON.parse(cookieValue);
+
+    // Validate the cookie structure
+    if (parsed && typeof parsed.distinct_id === 'string') {
+      return parsed as PostHogCookie;
+    }
+
+    return null;
+  } catch {
+    // Silently fail - cookies may be malformed
+    return null;
+  }
+}
+
+/**
+ * Get PostHog cookie name for a project
+ */
+export function getPostHogCookieName(projectApiKey: string): string {
+  return `ph_${projectApiKey}_posthog`;
+}
+
+/**
+ * Extract distinct ID from cookies (Next.js compatible)
+ */
+export function getDistinctIdFromCookies(
+  cookies: any, // Next.js cookies object or cookie string
+  projectApiKey: string,
+): string | null {
+  try {
+    const cookieName = getPostHogCookieName(projectApiKey);
+
+    // Handle Next.js cookies() object
+    if (cookies && typeof cookies.get === 'function') {
+      const cookie = cookies.get(cookieName);
+      if (cookie?.value) {
+        const parsed = parsePostHogCookie(cookie.value, projectApiKey);
+        return parsed?.distinct_id ?? null;
+      }
+    }
+
+    // Handle raw cookie string
+    if (typeof cookies === 'string') {
+      const cookieMatch = cookies.match(new RegExp(`${cookieName}=([^;]+)`));
+      if (cookieMatch?.[1]) {
+        const parsed = parsePostHogCookie(decodeURIComponent(cookieMatch[1]), projectApiKey);
+        return parsed?.distinct_id ?? null;
+      }
+    }
+
+    return null;
+  } catch {
+    // Silently fail - cookies may be malformed or missing
+    return null;
+  }
+}
+
+/**
+ * Create bootstrap data for PostHog client initialization
+ */
+export function createBootstrapData(distinctId: string): BootstrapData {
+  return {
+    distinctID: distinctId,
+  };
+}
+
+/**
+ * Cached bootstrap data fetcher (React cache compatible)
+ */
+const bootstrapCache = new Map<string, { data: BootstrapData; timestamp: number }>();
+const CACHE_TTL = 30000; // 30 seconds
+
+export function getCachedBootstrapData(distinctId: string): BootstrapData | null {
+  const cached = bootstrapCache.get(distinctId);
+
+  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
+    return cached.data;
+  }
+
+  // Clean up expired entries
+  for (const [key, value] of bootstrapCache.entries()) {
+    if (Date.now() - value.timestamp >= CACHE_TTL) {
+      bootstrapCache.delete(key);
+    }
+  }
+
+  return null;
+}
+
+export function setCachedBootstrapData(distinctId: string, data: BootstrapData): void {
+  bootstrapCache.set(distinctId, {
+    data,
+    timestamp: Date.now(),
+  });
+}
+
+/**
+ * Validate bootstrap data structure
+ */
+export function validateBootstrapData(data: any): data is BootstrapData {
+  return data && typeof data === 'object' && typeof data.distinctID === 'string';
+}
+
+/**
+ * Create minimal bootstrap data when full data is unavailable
+ */
+export function createMinimalBootstrapData(distinctId?: string): BootstrapData {
+  return {
+    distinctID: distinctId ?? generateDistinctId(),
+  };
+}

package/src/shared/utils/posthog-client-utils.ts

@@ -0,0 +1,48 @@
+/**
+ * @fileoverview Client-safe PostHog utilities for Next.js
+ * Client-safe PostHog utilities for Next.js
+ * These utilities can be safely imported in client-side code
+ */
+
+import { type BootstrapData } from '../types/posthog-types';
+
+/**
+ * PostHog provider configuration helper for Next.js
+ * This is safe to use in client-side code
+ */
+function createPostHogConfig(
+  apiKey: string,
+  options?: {
+    autocapture?: boolean;
+    bootstrap?: BootstrapData;
+    capture_pageview?: boolean;
+    debug?: boolean;
+    host?: string;
+    session_recording?: boolean;
+  },
+) {
+  return {
+    apiKey,
+    options: {
+      api_host: options?.host ?? 'https://app.posthog.com',
+      autocapture: options?.autocapture ?? true,
+      bootstrap: options?.bootstrap,
+      capture_pageview: options?.capture_pageview ?? false, // We handle manually
+      disable_session_recording: !(options?.session_recording ?? true),
+      loaded: options?.debug
+        ? (posthog: any) => {
+            // Only enable debug in development
+            if (options.debug) {
+              posthog.debug();
+            }
+          }
+        : undefined,
+      ...options,
+    },
+  };
+}
+
+/**
+ * Re-export client-safe utilities from posthog-bootstrap
+ */
+export { createPostHogConfig };

package/src/shared/utils/posthog-next-utils.ts

@@ -0,0 +1,282 @@
+/**
+ * @fileoverview Next.js specific utilities for PostHog integration
+ * Next.js specific utilities for PostHog integration
+ * Provides seamless server-side rendering and client hydration
+ */
+
+import {
+  createBootstrapData,
+  createMinimalBootstrapData,
+  generateDistinctId,
+  getCachedBootstrapData,
+  getDistinctIdFromCookies,
+  setCachedBootstrapData,
+} from './posthog-bootstrap';
+
+// Dynamic import of React cache for Next.js compatibility
+import type { BootstrapData } from '../types/posthog-types';
+
+type CacheFunction = <T extends (...args: any[]) => any>(fn: T) => T;
+
+let cache: CacheFunction;
+try {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports, prefer-destructuring
+  cache = require('react').cache;
+} catch {
+  // Fallback for non-React environments
+  cache = <T extends (...args: any[]) => any>(fn: T): T => fn;
+}
+
+/**
+ * Create a PostHog client for server-side operations
+ */
+async function createPostHogServerClient(
+  apiKey: string,
+  options?: {
+    host?: string | undefined;
+    timeout?: number | undefined;
+    flushAt?: number | undefined;
+    flushInterval?: number | undefined;
+  },
+) {
+  if (typeof window !== 'undefined') {
+    throw new TypeError('createPostHogServerClient should only be called on the server');
+  }
+
+  try {
+    const { PostHog } = await import('posthog-node');
+
+    return new PostHog(apiKey, {
+      flushAt: options?.flushAt ?? 1,
+      flushInterval: options?.flushInterval ?? 0,
+      host: options?.host ?? 'https://app.posthog.com',
+      ...(options?.timeout !== undefined && { timeout: options.timeout }),
+    });
+  } catch {
+    throw new Error('PostHog Node.js SDK not available. Install with: npm install posthog-node');
+  }
+}
+
+/**
+ * Get or generate distinct ID for server-side operations
+ * Uses React cache to ensure consistent ID across server renders
+ */
+const getOrGenerateDistinctId = cache(
+  async (
+    cookies: { get: (name: string) => { value: string } | undefined },
+    apiKey: string,
+  ): Promise<string> => {
+    // Try to get from cookies first
+    const existingId = getDistinctIdFromCookies(cookies, apiKey);
+    if (existingId) {
+      return existingId;
+    }
+
+    // Generate new ID
+    return generateDistinctId();
+  },
+);
+
+/**
+ * Fetch PostHog bootstrap data on the server
+ * Uses React cache to prevent duplicate requests
+ */
+const getPostHogBootstrapData = cache(
+  async (
+    apiKey: string,
+    distinctId: string,
+    options?: {
+      host?: string | undefined;
+      timeout?: number | undefined;
+    },
+  ): Promise<BootstrapData> => {
+    // Check cache first
+    const cached = getCachedBootstrapData(distinctId);
+    if (cached) {
+      return cached;
+    }
+
+    try {
+      const client = await createPostHogServerClient(apiKey, {
+        host: options?.host,
+        // Add timeout for server-side requests
+        timeout: options?.timeout ?? 5000,
+      });
+
+      // Cleanup
+      await client.shutdown();
+
+      const bootstrapData = createBootstrapData(distinctId);
+
+      // Cache the result
+      setCachedBootstrapData(distinctId, bootstrapData);
+
+      return bootstrapData;
+    } catch {
+      // Return minimal data on error
+      const minimalData = createMinimalBootstrapData(distinctId);
+      setCachedBootstrapData(distinctId, minimalData);
+      return minimalData;
+    }
+  },
+);
+
+/**
+ * Complete bootstrap data fetcher for Next.js apps
+ * Handles cookies, distinct ID generation, and flag fetching
+ */
+const getCompleteBootstrapData = cache(
+  async (
+    cookies: { get: (name: string) => { value: string } | undefined },
+    apiKey: string,
+    options?: {
+      host?: string | undefined;
+      timeout?: number | undefined;
+      fallbackToGenerated?: boolean | undefined;
+    },
+  ): Promise<BootstrapData> => {
+    try {
+      // Get or generate distinct ID
+      const distinctId = await getOrGenerateDistinctId(cookies, apiKey);
+
+      // Fetch bootstrap data
+      return await getPostHogBootstrapData(apiKey, distinctId, options);
+    } catch (error) {
+      if (options?.fallbackToGenerated !== false) {
+        // Fallback to generated ID with empty flags
+        const fallbackId = generateDistinctId();
+        return createMinimalBootstrapData(fallbackId);
+      }
+
+      throw error;
+    }
+  },
+);
+
+/**
+ * React Suspense-compatible PostHog bootstrap fetcher
+ */
+function createPostHogSuspenseData(
+  cookies: { get: (name: string) => { value: string } | undefined },
+  apiKey: string,
+  options?: {
+    host?: string | undefined;
+    timeout?: number | undefined;
+  },
+) {
+  let status = 'pending';
+  let result: BootstrapData;
+  let error: unknown;
+
+  const suspender = (async () => {
+    try {
+      const data = await getCompleteBootstrapData(cookies, apiKey, options);
+      status = 'fulfilled';
+      result = data;
+      return data;
+    } catch (err) {
+      status = 'rejected';
+      error = err;
+      throw err;
+    }
+  })();
+
+  return {
+    read() {
+      if (status === 'pending') {
+        throw suspender;
+      } else if (status === 'rejected') {
+        throw error;
+      }
+      return result;
+    },
+  };
+}
+
+/**
+ * PostHog provider configuration helper for Next.js
+ */
+function createPostHogConfig(
+  apiKey: string,
+  options?: {
+    host?: string | undefined;
+    autocapture?: boolean | undefined;
+    capture_pageview?: boolean | undefined;
+    session_recording?: boolean | undefined;
+    bootstrap?: BootstrapData | undefined;
+    debug?: boolean | undefined;
+  },
+) {
+  return {
+    apiKey,
+    options: {
+      api_host: options?.host ?? 'https://app.posthog.com',
+      autocapture: options?.autocapture ?? true,
+      bootstrap: options?.bootstrap,
+      capture_pageview: options?.capture_pageview ?? false, // We handle manually
+      disable_session_recording: !(options?.session_recording ?? true),
+      loaded: options?.debug
+        ? (posthog: { debug: () => void }) => {
+            // Only enable debug in development
+            if (options.debug) {
+              posthog.debug();
+            }
+          }
+        : undefined,
+      ...options,
+    },
+  };
+}
+
+/**
+ * Middleware helper for PostHog tracking
+ */
+function _createPostHogMiddleware(apiKey: string) {
+  return async (
+    request: {
+      headers?: {
+        get?: (name: string) => string | null;
+        [key: string]: string | undefined | ((name: string) => string | null);
+      };
+      ip?: string;
+      cookies?: { get: (name: string) => { value: string } | undefined };
+    },
+    _response?: unknown,
+  ) => {
+    try {
+      // Extract user info from request
+      const userAgent = request.headers?.get?.('user-agent') ?? request.headers?.['user-agent'];
+      const referer = request.headers?.get?.('referer') ?? request.headers?.['referer'];
+      const ip = request.ip ?? request.headers?.get?.('x-forwarded-for') ?? 'unknown';
+
+      // Get distinct ID from cookies
+      const { cookies } = request;
+      const distinctId = getDistinctIdFromCookies(cookies, apiKey) ?? generateDistinctId();
+
+      // Create tracking context
+      return {
+        distinctId,
+        ip,
+        referer,
+        timestamp: new Date().toISOString(),
+        userAgent,
+      };
+    } catch {
+      return null;
+    }
+  };
+}
+
+/**
+ * Export commonly used utilities
+ */
+export {
+  createPostHogConfig,
+  // eslint-disable-next-line no-used-underscore-vars/no-used-underscore-vars
+  _createPostHogMiddleware as createPostHogMiddleware,
+  createPostHogServerClient,
+  createPostHogSuspenseData,
+  getCompleteBootstrapData,
+  getOrGenerateDistinctId,
+  getPostHogBootstrapData,
+};

package/src/shared/utils/posthog-server-utils.ts

@@ -0,0 +1,210 @@
+/**
+ * @fileoverview Server-only PostHog utilities for Next.js
+ * Server-only PostHog utilities for Next.js
+ * These utilities should only be imported in server-side code
+ */
+
+// Dynamic import of React cache for Next.js compatibility
+import { type BootstrapData } from '../types/posthog-types';
+
+import {
+  createBootstrapData,
+  createMinimalBootstrapData,
+  generateDistinctId,
+  getCachedBootstrapData,
+  getDistinctIdFromCookies,
+  setCachedBootstrapData,
+} from './posthog-bootstrap';
+
+let cache: any;
+try {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports, prefer-destructuring
+  cache = require('react').cache;
+} catch {
+  // Fallback for non-React environments
+  cache = <T extends (...args: any[]) => any>(fn: T): T => fn;
+}
+
+/**
+ * Create a PostHog client for server-side operations
+ */
+async function createPostHogServerClient(apiKey: string, options?: any) {
+  try {
+    const { PostHog } = await import('posthog-node');
+
+    return new PostHog(apiKey, {
+      flushAt: 1,
+      flushInterval: 0,
+      host: 'https://app.posthog.com',
+      ...options,
+    });
+  } catch {
+    throw new Error('PostHog Node.js SDK not available. Install with: npm install posthog-node');
+  }
+}
+
+/**
+ * Get or generate distinct ID for server-side operations
+ * Uses React cache to ensure consistent ID across server renders
+ */
+const getOrGenerateDistinctId = cache(async (cookies: any, apiKey: string): Promise<string> => {
+  // Try to get from cookies first
+  const existingId = getDistinctIdFromCookies(cookies, apiKey);
+  if (existingId) {
+    return existingId;
+  }
+
+  // Generate new ID
+  return generateDistinctId();
+});
+
+/**
+ * Fetch PostHog bootstrap data on the server
+ * Uses React cache to prevent duplicate requests
+ */
+const getPostHogBootstrapData = cache(
+  async (
+    apiKey: string,
+    distinctId: string,
+    options?: {
+      host?: string;
+      timeout?: number;
+    },
+  ): Promise<BootstrapData> => {
+    // Check cache first
+    const cached = getCachedBootstrapData(distinctId);
+    if (cached) {
+      return cached;
+    }
+
+    try {
+      const client = await createPostHogServerClient(apiKey, {
+        host: options?.host,
+        // Add timeout for server-side requests
+        timeout: options?.timeout ?? 5000,
+      });
+
+      // Cleanup
+      await client.shutdown();
+
+      const bootstrapData = createBootstrapData(distinctId);
+
+      // Cache the result
+      setCachedBootstrapData(distinctId, bootstrapData);
+
+      return bootstrapData;
+    } catch {
+      // Return minimal data on error
+      const minimalData = createMinimalBootstrapData(distinctId);
+      setCachedBootstrapData(distinctId, minimalData);
+      return minimalData;
+    }
+  },
+);
+
+/**
+ * Complete bootstrap data fetcher for Next.js apps
+ * Handles cookies, distinct ID generation, and flag fetching
+ */
+const getCompleteBootstrapData = cache(
+  async (
+    cookies: any,
+    apiKey: string,
+    options?: {
+      fallbackToGenerated?: boolean;
+      host?: string;
+      timeout?: number;
+    },
+  ): Promise<BootstrapData> => {
+    try {
+      // Get or generate distinct ID
+      const distinctId = await getOrGenerateDistinctId(cookies, apiKey);
+
+      // Fetch bootstrap data
+      return await getPostHogBootstrapData(apiKey, distinctId, options);
+    } catch (error: any) {
+      if (options?.fallbackToGenerated !== false) {
+        // Fallback to generated ID with empty flags
+        const fallbackId = generateDistinctId();
+        return createMinimalBootstrapData(fallbackId);
+      }
+
+      throw error;
+    }
+  },
+);
+
+// Commented out as currently unused but kept for potential future use
+// /**
+//  * Middleware helper for PostHog tracking
+//  */
+// function _createPostHogMiddleware(apiKey: string) {
+//   return async (request: any, _response?: any) => {
+//     try {
+//       // Extract user info from request
+//       const userAgent = request.headers?.get?.('user-agent') ?? request.headers?.['user-agent'];
+//       const referer = request.headers?.get?.('referer') ?? request.headers?.['referer'];
+//       const ip = request.ip ?? request.headers?.get?.('x-forwarded-for') ?? 'unknown';
+
+//       // Get distinct ID from cookies
+//       const { cookies } = request;
+//       const distinctId = getDistinctIdFromCookies(cookies, apiKey) ?? generateDistinctId();
+
+//       // Create tracking context
+//       return {
+//         distinctId,
+//         ip,
+//         referer,
+//         timestamp: new Date().toISOString(),
+//         userAgent,
+//       };
+//     } catch {
+//       return null;
+//     }
+//   };
+// }
+
+// /**
+//  * React Suspense-compatible PostHog bootstrap fetcher
+//  */
+// function _createPostHogSuspenseData(
+//   cookies: any,
+//   apiKey: string,
+//   options?: {
+//     host?: string;
+//     timeout?: number;
+//   },
+// ) {
+//   let status = 'pending';
+//   let result: BootstrapData;
+//   let error: any;
+
+//   // eslint-disable-next-line promise/prefer-await-to-then
+//   const suspender = getCompleteBootstrapData(cookies, apiKey, options).then(
+//     // eslint-disable-next-line promise/always-return
+//     (data: any) => {
+//       status = 'fulfilled';
+//       result = data;
+//     },
+//     (err: any) => {
+//       status = 'rejected';
+//       error = err;
+//     },
+//   );
+
+//   return {
+//     read() {
+//       if (status === 'pending') {
+//         throw suspender;
+//       } else if (status === 'rejected') {
+//         throw error;
+//       }
+//       return result;
+//     },
+//   };
+// }
+
+/**
+ * Export commonly used utilities (server-safe only)
+ */
+export { getCompleteBootstrapData };