@od-oneapp/analytics 2026.1.1301

package/src/next/rsc.tsx

@@ -0,0 +1,300 @@
+/**
+ * @fileoverview React Server Component (RSC) specific analytics utilities for Next.js 15
+ *
+ * Provides server-side analytics tracking with proper caching and data flow.
+ * Includes React Server Component integration, server actions, and PostHog bootstrap utilities.
+ *
+ * @remarks
+ * This module:
+ * - Uses React cache for request-scoped analytics instances
+ * - Provides server actions for client component integration
+ * - Supports PostHog bootstrap data generation
+ * - Extracts request context from headers
+ * - Avoids contamination by using dependency injection for Next.js runtime
+ *
+ * @module @od-oneapp/analytics/next/rsc
+ */
+
+import { cache } from 'react';
+
+import { getCompleteBootstrapData } from '../shared/utils/posthog-next-utils';
+
+import { createNextJSServerAnalytics } from './server';
+
+import type { BootstrapData } from '../shared/types/posthog-types';
+import type { AnalyticsConfig, TrackingOptions } from '../shared/types/types';
+import type { ReadonlyRequestCookies } from 'next/dist/server/web/spec-extension/adapters/request-cookies';
+
+/**
+ * Cached analytics instance for RSC
+ * Uses React cache to ensure single instance per request
+ */
+const getAnalyticsInstance = cache(async (config: AnalyticsConfig) => {
+  const analytics = createNextJSServerAnalytics(config);
+  await analytics.initialize();
+  return analytics;
+});
+
+/**
+ * Track event from React Server Components
+ * Automatically extracts request context
+ *
+ * @param headersFn - Function to get request headers (from 'next/headers')
+ */
+export async function trackServerEvent(
+  event: string,
+  properties?: Record<string, unknown>,
+  options?: TrackingOptions & { config?: AnalyticsConfig; headersFn?: () => Promise<Headers> },
+): Promise<void> {
+  const config = options?.config ?? getDefaultConfig();
+  const analytics = await getAnalyticsInstance(config);
+
+  // Extract request context
+  // Note: headersFn must be provided by the Next.js app to avoid contamination
+  if (!options?.headersFn) {
+    throw new Error(
+      'trackServerEvent requires headersFn parameter. Import and pass headers from "next/headers" in your Next.js app.',
+    );
+  }
+  const requestHeaders = await options.headersFn();
+  const userAgent = requestHeaders.get('user-agent') ?? undefined;
+  const referer = requestHeaders.get('referer') ?? undefined;
+
+  const enhancedProperties = {
+    ...properties,
+    server_side: true,
+    referer,
+    timestamp: new Date().toISOString(),
+    user_agent: userAgent,
+  };
+
+  await analytics.track(event, enhancedProperties, options);
+}
+
+/**
+ * Identify user from React Server Components
+ */
+export async function identifyServerUser(
+  userId: string,
+  traits?: any,
+  options?: TrackingOptions & { config?: AnalyticsConfig },
+): Promise<void> {
+  const config = options?.config ?? getDefaultConfig();
+  const analytics = await getAnalyticsInstance(config);
+
+  const enhancedTraits = {
+    ...traits,
+    identified_at: new Date().toISOString(),
+    identified_from: 'server',
+  };
+
+  await analytics.identify(userId, enhancedTraits, options);
+}
+
+/**
+ * Track page view from React Server Components
+ *
+ * @param headersFn - Function to get request headers (from 'next/headers')
+ */
+export async function trackServerPageView(
+  pathname: string,
+  properties?: any,
+  options?: TrackingOptions & { config?: AnalyticsConfig; headersFn?: () => Promise<Headers> },
+): Promise<void> {
+  const config = options?.config ?? getDefaultConfig();
+  const analytics = await getAnalyticsInstance(config);
+
+  // Note: headersFn must be provided by the Next.js app to avoid contamination
+  if (!options?.headersFn) {
+    throw new Error(
+      'trackServerPageView requires headersFn parameter. Import and pass headers from "next/headers" in your Next.js app.',
+    );
+  }
+  const requestHeaders = await options.headersFn();
+  const userAgent = requestHeaders.get('user-agent') ?? undefined;
+  const referer = requestHeaders.get('referer') ?? undefined;
+
+  const enhancedProperties = {
+    ...properties,
+    path: pathname,
+    referer,
+    server_rendered: true,
+    timestamp: new Date().toISOString(),
+    user_agent: userAgent,
+  };
+
+  await analytics.page(pathname, enhancedProperties, options);
+}
+
+/**
+ * Get PostHog bootstrap data for server components
+ * Includes distinct ID extraction and feature flag fetching
+ *
+ * @param cookiesFn - Function to get cookies (from 'next/headers')
+ */
+export function createGetServerBootstrapData(cookiesFn: () => any) {
+  return cache(
+    async (
+      apiKey: string,
+      options?: {
+        host?: string;
+        timeout?: number;
+      },
+    ): Promise<BootstrapData> => {
+      const cookieStore = cookiesFn();
+      return await getCompleteBootstrapData(cookieStore, apiKey, options);
+    },
+  );
+}
+
+/**
+ * Get PostHog bootstrap data (requires cookiesFn to be provided)
+ * Use createGetServerBootstrapData with cookies from 'next/headers' in your Next.js app
+ */
+export const getServerBootstrapData = (cookiesFn: () => ReadonlyRequestCookies) => {
+  return cache(
+    async (
+      apiKey: string,
+      options?: {
+        host?: string;
+        timeout?: number;
+      },
+    ): Promise<BootstrapData> => {
+      const cookieStore = cookiesFn();
+      return await getCompleteBootstrapData(cookieStore, apiKey, options);
+    },
+  );
+};
+
+/**
+ * Analytics provider for React Server Components
+ * Use in server component layouts to provide analytics to children
+ */
+export async function ServerAnalyticsProvider({
+  children,
+  config,
+  posthogApiKey,
+}: {
+  children: React.ReactNode;
+  config?: AnalyticsConfig;
+  posthogApiKey?: string;
+}): Promise<React.ReactElement> {
+  // Initialize analytics on the server
+  if (config) {
+    await getAnalyticsInstance(config);
+  }
+
+  // Get bootstrap data if PostHog is configured
+  // Note: getServerBootstrapData requires a cookiesFn to be provided
+  // This is intentionally left as a placeholder for implementation
+  if (posthogApiKey) {
+    // TODO: Implement bootstrap data fetching with proper cookies function
+    // const { cookies } = await import('next/headers');
+    // const bootstrapDataFn = getServerBootstrapData(cookies);
+    // await bootstrapDataFn(posthogApiKey);
+    void posthogApiKey; // Prevent unused variable warning
+  }
+
+  // Return children with any necessary context
+  // Note: In RSC, we can't use React context, but we can pass data via props
+  return children as React.ReactElement;
+}
+
+/**
+ * Higher-order component for tracking page views in server components
+ */
+export function withServerPageTracking<P extends object>(
+  Component: React.ComponentType<P>,
+  pageName?: string,
+) {
+  return async function TrackedServerComponent(props: P) {
+    // Get pathname from props or use provided name
+    const pathname = pageName ?? (props as any).params?.pathname ?? 'unknown';
+
+    // Track page view
+    await trackServerPageView(pathname, {
+      component: Component.name,
+      props: Object.keys(props as any),
+    });
+
+    return <Component {...props} />;
+  };
+}
+
+/**
+ * Get default analytics configuration
+ * Can be customized via environment variables
+ */
+function getDefaultConfig(): AnalyticsConfig {
+  const config: AnalyticsConfig = {
+    providers: {},
+  };
+
+  // Add providers based on environment variables
+  if (process.env.NEXT_PUBLIC_POSTHOG_KEY) {
+    config.providers.posthog = {
+      apiKey: process.env.NEXT_PUBLIC_POSTHOG_KEY,
+      options: {
+        api_host: process.env.NEXT_PUBLIC_POSTHOG_HOST,
+      },
+    };
+  }
+
+  if (process.env.NEXT_PUBLIC_SEGMENT_WRITE_KEY) {
+    config.providers.segment = {
+      writeKey: process.env.NEXT_PUBLIC_SEGMENT_WRITE_KEY,
+    };
+  }
+
+  // Add console provider in development
+  if (process.env.NODE_ENV === 'development') {
+    config.providers.console = {
+      options: {
+        prefix: '[RSC Analytics]',
+        pretty: true,
+      },
+    };
+  }
+
+  return config;
+}
+
+/**
+ * Server action for tracking events
+ * Can be called from client components
+ */
+export async function trackEventAction(
+  event: string,
+  properties?: any,
+): Promise<{ success: boolean }> {
+  'use server';
+
+  try {
+    await trackServerEvent(event, properties);
+    return { success: true };
+  } catch {
+    return { success: false };
+  }
+}
+
+/**
+ * Server action for identifying users
+ * Can be called from client components
+ */
+export async function identifyUserAction(
+  userId: string,
+  traits?: any,
+): Promise<{ success: boolean }> {
+  'use server';
+
+  try {
+    await identifyServerUser(userId, traits);
+    return { success: true };
+  } catch {
+    return { success: false };
+  }
+}
+
+// Re-export types for convenience
+export type { BootstrapData } from '../shared/types/posthog-types';
+export type { AnalyticsConfig, TrackingOptions } from '../shared/types/types';

package/src/next/server.ts

@@ -0,0 +1,253 @@
+/**
+ * @fileoverview Next.js server-side analytics implementation
+ *
+ * Provides server-side analytics functionality for Next.js applications.
+ * Includes PostHog bootstrap data generation and server-side event tracking.
+ *
+ * @remarks
+ * This implementation is optimized for Next.js server components and API routes:
+ * - Supports PostHog bootstrap data generation
+ * - Extracts distinct IDs from cookies
+ * - Handles server-side event tracking
+ * - Integrates with Next.js server actions
+ *
+ * @module @od-oneapp/analytics/next/server
+ */
+
+import { type AnalyticsManager } from '../shared/utils/manager';
+import { createPostHogConfig, getCompleteBootstrapData } from '../shared/utils/posthog-next-utils';
+
+import type { BootstrapData } from '../shared/types/posthog-types';
+import type { AnalyticsConfig, TrackingOptions } from '../shared/types/types';
+
+export interface NextJSServerAnalyticsConfig extends AnalyticsConfig {
+  nextjs?:
+    | {
+        // Enable debug mode
+        debug?: boolean | undefined;
+
+        // PostHog specific options
+        posthog?:
+          | {
+              // Cookies for distinct ID extraction
+              cookies?: any;
+
+              // API key for server-side operations
+              apiKey?: string | undefined;
+
+              // Host override
+              host?: string | undefined;
+
+              // Request timeout for server calls
+              timeout?: number | undefined;
+            }
+          | undefined;
+      }
+    | undefined;
+}
+
+export class NextJSServerAnalyticsManager {
+  private manager: AnalyticsManager | null = null;
+  private config: NextJSServerAnalyticsConfig;
+  private isInitialized = false;
+
+  constructor(config: NextJSServerAnalyticsConfig) {
+    this.config = config;
+  }
+
+  /**
+   * Initialize analytics for server-side usage
+   */
+  async initialize(): Promise<void> {
+    if (this.isInitialized) return;
+
+    try {
+      // Dynamically import server providers
+      const { createAnalyticsManager } = await import('../shared/utils/manager');
+      const { SegmentServerProvider } = await import('../providers/segment/server');
+      const { PostHogServerProvider } = await import('../providers/posthog/server');
+      const { VercelServerProvider } = await import('../providers/vercel/server');
+      const { ConsoleProvider } = await import('../providers/console/server');
+
+      const SERVER_PROVIDERS = {
+        console: (config: any) => new ConsoleProvider(config),
+        posthog: (config: any) => new PostHogServerProvider(config),
+        segment: (config: any) => new SegmentServerProvider(config),
+        vercel: (config: any) => new VercelServerProvider(config),
+      };
+
+      this.manager = createAnalyticsManager(this.config, SERVER_PROVIDERS);
+      await this.manager.initialize();
+      this.isInitialized = true;
+
+      // Server analytics initialized successfully
+    } catch {
+      // Failed to initialize server analytics
+    }
+  }
+
+  /**
+   * Track an event
+   */
+  async track(event: string, properties?: any, options?: TrackingOptions): Promise<void> {
+    if (!this.isInitialized) {
+      await this.initialize();
+    }
+
+    if (this.manager) {
+      await this.manager.track(event, properties, options);
+    }
+  }
+
+  /**
+   * Identify a user
+   */
+  async identify(userId: string, traits?: any, options?: TrackingOptions): Promise<void> {
+    if (!this.isInitialized) {
+      await this.initialize();
+    }
+
+    if (this.manager) {
+      await this.manager.identify(userId, traits, options);
+    }
+  }
+
+  /**
+   * Track a page view
+   */
+  async page(name?: string, properties?: any, options?: TrackingOptions): Promise<void> {
+    if (!this.isInitialized) {
+      await this.initialize();
+    }
+
+    if (this.manager) {
+      await this.manager.page(name, properties, options);
+    }
+  }
+
+  /**
+   * Track a group
+   */
+  async group(groupId: string, traits?: any, options?: TrackingOptions): Promise<void> {
+    if (!this.isInitialized) {
+      await this.initialize();
+    }
+
+    if (this.manager) {
+      await this.manager.group(groupId, traits, options);
+    }
+  }
+
+  /**
+   * Alias a user
+   */
+  async alias(userId: string, previousId: string, options?: TrackingOptions): Promise<void> {
+    if (!this.isInitialized) {
+      await this.initialize();
+    }
+
+    if (this.manager) {
+      await this.manager.alias(userId, previousId, options);
+    }
+  }
+
+  /**
+   * Get initialization status
+   */
+  getStatus() {
+    return {
+      activeProviders: this.manager?.getActiveProviders() ?? [],
+      isInitialized: this.isInitialized,
+    };
+  }
+}
+
+/**
+ * Create a Next.js optimized analytics instance for server
+ *
+ * @example
+ * ```typescript
+ * const analytics = createNextJSServerAnalytics({
+ *   providers: { segment: { writeKey: process.env.SEGMENT_KEY! } },
+ * });
+ * await analytics.initialize();
+ * ```
+ */
+export function createNextJSServerAnalytics(
+  config: NextJSServerAnalyticsConfig,
+): NextJSServerAnalyticsManager {
+  return new NextJSServerAnalyticsManager(config);
+}
+
+/**
+ * Get PostHog bootstrap data for server-side rendering
+ *
+ * @example
+ * ```typescript
+ * const bootstrap = await getPostHogBootstrapDataOnServer(cookies(), apiKey);
+ * ```
+ */
+export async function getPostHogBootstrapDataOnServer(
+  cookies: any,
+  apiKey: string,
+  options?: {
+    host?: string;
+    timeout?: number;
+  },
+): Promise<BootstrapData> {
+  return await getCompleteBootstrapData(cookies, apiKey, options);
+}
+
+/**
+ * Enhanced analytics manager with PostHog bootstrap for SSR
+ *
+ * @example
+ * ```typescript
+ * const { analytics, bootstrapData } =
+ *   await createNextJSServerAnalyticsWithBootstrap(cookies(), apiKey);
+ * const config = createPostHogConfigWithBootstrap(apiKey, bootstrapData);
+ * ```
+ */
+export async function createNextJSServerAnalyticsWithBootstrap(
+  cookies: any,
+  apiKey: string,
+  options?: {
+    host?: string;
+    timeout?: number;
+    providers?: Record<string, any>;
+    nextjs?: Omit<NextJSServerAnalyticsConfig['nextjs'], 'posthog'>;
+  },
+): Promise<{
+  analytics: NextJSServerAnalyticsManager;
+  bootstrapData: BootstrapData;
+}> {
+  // Get bootstrap data
+  const bootstrapData = await getCompleteBootstrapData(cookies, apiKey, {
+    host: options?.host,
+    timeout: options?.timeout,
+  });
+
+  // Create config with server-side settings
+  const config: NextJSServerAnalyticsConfig = {
+    providers: {
+      posthog: createPostHogConfig(apiKey, {
+        host: options?.host,
+      }),
+      ...options?.providers,
+    },
+    nextjs: {
+      ...options?.nextjs,
+      posthog: {
+        apiKey,
+        cookies,
+        host: options?.host,
+        timeout: options?.timeout,
+      },
+    },
+  };
+
+  const analytics = new NextJSServerAnalyticsManager(config);
+  await analytics.initialize();
+
+  return { analytics, bootstrapData };
+}