@od-oneapp/analytics 2026.1.1301

package/src/server-edge.ts

@@ -0,0 +1,442 @@
+/**
+ * @fileoverview Edge Runtime Analytics Module
+ *
+ * Provides edge-compatible analytics for Next.js middleware and edge API routes.
+ * Uses Web APIs and HTTP-based implementations compatible with edge runtime.
+ *
+ * **Supported Features**:
+ * - Basic event tracking (track, identify, page, group, alias)
+ * - Console provider (uses console API)
+ * - PostHog provider (HTTP-based, no SDK dependency)
+ * - Emitter pattern support via `emit()`
+ *
+ * **Limitations (Edge Runtime Constraints)**:
+ * - No Node.js APIs (fs, crypto, etc.)
+ * - No native modules or SDK dependencies
+ * - No event deduplication (no LRU cache)
+ * - No rate limiting (100 req/s limit not enforced)
+ * - No batch processing optimization
+ * - No performance metrics tracking
+ * - No feature flags (PostHog flags require server SDK)
+ * - Context is per-request only (not persisted)
+ *
+ * **For full analytics features**, use `@od-oneapp/analytics/server` in Node.js environments.
+ *
+ * **Usage**: Import from `@od-oneapp/analytics/server/edge` for Next.js middleware and edge API routes.
+ *
+ * @example
+ * ```typescript
+ * // In Next.js middleware
+ * import { createServerAnalytics, track } from '@od-oneapp/analytics/server/edge';
+ *
+ * export async function middleware(request: NextRequest) {
+ *   const analytics = await createServerAnalytics({
+ *     providers: {
+ *       posthog: { apiKey: process.env.POSTHOG_API_KEY }
+ *     }
+ *   });
+ *
+ *   await analytics.emit(track('Middleware Hit', { path: request.nextUrl.pathname }));
+ *   return NextResponse.next();
+ * }
+ * ```
+ *
+ * @module @od-oneapp/analytics/server/edge
+ */
+
+import { env } from '../env';
+
+import type {
+  EmitterAliasPayload,
+  EmitterGroupPayload,
+  EmitterIdentifyPayload,
+  EmitterPagePayload,
+  EmitterPayload,
+  EmitterTrackPayload,
+} from './shared/emitters/emitter-types';
+import type {
+  AnalyticsConfig,
+  AnalyticsContext,
+  AnalyticsManager,
+  AnalyticsProvider,
+  GroupTraits,
+  PageProperties,
+  Properties,
+  UserTraits,
+} from './shared/types/types';
+
+// Type aliases for clarity
+type IdentifyTraits = UserTraits;
+type TrackProperties = Properties;
+
+// Re-export types for consumers
+export type * from './shared/emitters/emitter-types';
+export type * from './shared/types/types';
+
+// Re-export emitter utilities
+export { createEmitterProcessor } from './shared/utils/emitter-adapter';
+
+// Re-export core emitters for edge usage
+export { alias, group, identify, page, track } from './shared/emitters';
+
+const defaultConfig: AnalyticsConfig = { providers: {} };
+
+/**
+ * Creates an edge-compatible analytics manager.
+ *
+ * This is a simplified implementation optimized for edge runtime constraints.
+ * It provides basic analytics functionality without Node.js-specific features.
+ *
+ * **Supported Providers**:
+ * - Console (always available)
+ * - PostHog (HTTP-based, requires API key)
+ *
+ * **Not Supported in Edge**:
+ * - Segment SDK (requires Node.js)
+ * - Vercel Analytics SDK (requires Node.js)
+ * - Rate limiting
+ * - Event deduplication
+ * - Batch processing optimization
+ *
+ * @param {AnalyticsConfig} [config] - Analytics configuration with provider settings
+ * @returns {Promise<AnalyticsManager>} Promise resolving to AnalyticsManager instance
+ *
+ * @example
+ * ```typescript
+ * const analytics = await createServerAnalytics({
+ *   providers: {
+ *     posthog: { apiKey: process.env.POSTHOG_API_KEY }
+ *   }
+ * });
+ *
+ * await analytics.track('Event Name', { property: 'value' });
+ * ```
+ */
+export async function createServerAnalytics(
+  config: AnalyticsConfig = defaultConfig,
+): Promise<AnalyticsManager> {
+  const providers: AnalyticsProvider[] = [];
+  let context: AnalyticsContext = {};
+
+  // Initialize Console provider (edge-compatible)
+  if (config.providers.console) {
+    const { ConsoleProvider } = await import('./providers/console');
+    const consoleProvider = new ConsoleProvider(config.providers.console);
+    await consoleProvider.initialize();
+    providers.push(consoleProvider);
+  }
+
+  // Initialize PostHog HTTP provider (edge-compatible)
+  if (config.providers.posthog?.apiKey) {
+    const posthogProvider = createPostHogEdgeProvider(config);
+    providers.push(posthogProvider);
+  }
+
+  // Process emitter payload by type
+  const processPayload = async (payload: EmitterPayload): Promise<void> => {
+    switch (payload.type) {
+      case 'track': {
+        const p = payload;
+        await Promise.allSettled(
+          providers.map(provider =>
+            provider.track(p.event, p.properties ?? {}, { ...context, ...p.context }),
+          ),
+        );
+        break;
+      }
+      case 'identify': {
+        const p = payload;
+        await Promise.allSettled(
+          providers.map(provider =>
+            provider.identify?.(p.userId, p.traits ?? {}, { ...context, ...p.context }),
+          ),
+        );
+        break;
+      }
+      case 'page': {
+        const p = payload;
+        await Promise.allSettled(
+          providers.map(provider =>
+            provider.page?.(p.name ?? '', p.properties ?? {}, { ...context, ...p.context }),
+          ),
+        );
+        break;
+      }
+      case 'screen': {
+        const p = payload;
+        await Promise.allSettled(
+          providers.map(provider =>
+            provider.screen?.(p.name ?? '', p.properties ?? {}, { ...context, ...p.context }),
+          ),
+        );
+        break;
+      }
+      case 'group': {
+        const p = payload;
+        await Promise.allSettled(
+          providers.map(provider =>
+            provider.group?.(p.groupId, p.traits ?? {}, { ...context, ...p.context }),
+          ),
+        );
+        break;
+      }
+      case 'alias': {
+        const p = payload;
+        await Promise.allSettled(
+          providers.map(provider =>
+            provider.alias?.(p.userId, p.previousId, { ...context, ...p.context }),
+          ),
+        );
+        break;
+      }
+    }
+  };
+
+  // Create emitter function at outer scope (within createServerAnalytics)
+  function createEmitterFunction(payload: EmitterPayload): Promise<void> {
+    return processPayload(payload);
+  }
+
+  // Return edge-compatible analytics manager
+  const manager: AnalyticsManager = {
+    getContext: () => ({ ...context }),
+
+    initialize: async () => {
+      // Providers already initialized above
+    },
+
+    setContext: (newContext: AnalyticsContext) => {
+      context = { ...context, ...newContext };
+    },
+
+    createEmitter: () => createEmitterFunction,
+
+    emit: async (payload: EmitterPayload) => {
+      await processPayload(payload);
+    },
+
+    emitBatch: async (payloads: EmitterPayload[]) => {
+      // Process sequentially in edge (no concurrency optimization)
+      for (const payload of payloads) {
+        await processPayload(payload);
+      }
+    },
+
+    // Overloaded track method
+    track: async (eventOrPayload: string | EmitterTrackPayload, properties?: Properties) => {
+      if (typeof eventOrPayload === 'object') {
+        await processPayload(eventOrPayload);
+      } else if (typeof eventOrPayload === 'string') {
+        await Promise.allSettled(
+          providers.map(p => p.track(eventOrPayload, properties ?? {}, context)),
+        );
+      }
+    },
+
+    // Overloaded identify method
+    identify: async (userIdOrPayload: string | EmitterIdentifyPayload, traits?: IdentifyTraits) => {
+      if (typeof userIdOrPayload === 'object') {
+        await processPayload(userIdOrPayload);
+      } else if (typeof userIdOrPayload === 'string') {
+        await Promise.allSettled(
+          providers.map(p => p.identify?.(userIdOrPayload, traits ?? {}, context)),
+        );
+      }
+    },
+
+    // Overloaded page method
+    page: async (nameOrPayload?: string | EmitterPagePayload, properties?: PageProperties) => {
+      if (typeof nameOrPayload === 'object') {
+        await processPayload(nameOrPayload);
+      } else {
+        const pageName = typeof nameOrPayload === 'string' ? nameOrPayload : '';
+        await Promise.allSettled(providers.map(p => p.page?.(pageName, properties ?? {}, context)));
+      }
+    },
+
+    // Overloaded group method
+    group: async (groupIdOrPayload: string | EmitterGroupPayload, traits?: GroupTraits) => {
+      if (typeof groupIdOrPayload === 'object') {
+        await processPayload(groupIdOrPayload);
+      } else if (typeof groupIdOrPayload === 'string') {
+        await Promise.allSettled(
+          providers.map(p => p.group?.(groupIdOrPayload, traits ?? {}, context)),
+        );
+      }
+    },
+
+    // Overloaded alias method
+    alias: async (userIdOrPayload: string | EmitterAliasPayload, previousId?: string) => {
+      if (typeof userIdOrPayload === 'object') {
+        await processPayload(userIdOrPayload);
+      } else if (typeof userIdOrPayload === 'string' && previousId) {
+        await Promise.allSettled(
+          providers.map(p => p.alias?.(userIdOrPayload, previousId, context)),
+        );
+      }
+    },
+
+    getActiveProviders: () => providers.map(p => p.name),
+    getProvider: (name: string) => providers.find(p => p.name === name),
+
+    reset: () => {
+      context = {};
+    },
+
+    shutdown: async () => {
+      // In edge, we don't have complex shutdown logic usually
+      providers.length = 0;
+    },
+
+    // Deprecated methods (no-ops with warning)
+    processEmitterPayload: async (payload: EmitterPayload) => {
+      await processPayload(payload);
+    },
+    trackEcommerce: async () => {
+      if (config.debug && config.onInfo) {
+        config.onInfo('trackEcommerce is deprecated, use emit(ecommerce.EVENT_NAME(...))');
+      }
+    },
+  };
+
+  return manager;
+}
+
+/**
+ * Creates a PostHog provider that uses HTTP API (edge-compatible).
+ *
+ * This provider uses PostHog's HTTP capture API instead of the Node.js SDK,
+ * making it compatible with edge runtime constraints.
+ *
+ * **Features**:
+ * - HTTP-based event tracking
+ * - 5-second timeout per request
+ * - Error handling via config callbacks
+ * - Supports all standard analytics methods (track, identify, page, group, alias)
+ *
+ * @param {AnalyticsConfig} config - Analytics configuration
+ * @returns {AnalyticsProvider} PostHog provider instance
+ *
+ * @throws {Error} If PostHog API key is not provided
+ *
+ * @internal
+ */
+function createPostHogEdgeProvider(config: AnalyticsConfig): AnalyticsProvider {
+  const posthogConfig = config.providers?.posthog;
+  if (!posthogConfig?.apiKey) {
+    throw new Error('PostHog apiKey is required');
+  }
+
+  const posthogHost =
+    (posthogConfig.options as { api_host?: string } | undefined)?.api_host ??
+    env.POSTHOG_HOST ??
+    'https://app.posthog.com';
+  const posthogUrl = `${posthogHost}/capture/`;
+  const { apiKey } = posthogConfig;
+  const timeout = 5000;
+
+  // Safe fetch with timeout and error handling
+  const safeFetch = async (body: Record<string, unknown>, method: string): Promise<void> => {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+    try {
+      const response = await fetch(posthogUrl, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+
+      if (!response.ok && config.onError) {
+        config.onError(
+          new Error(`PostHog ${method} failed: ${response.status} ${response.statusText}`),
+          { provider: 'posthog-edge', method, status: response.status },
+        );
+      }
+    } catch (error) {
+      if (config.onError) {
+        config.onError(error instanceof Error ? error : new Error('Unknown error'), {
+          provider: 'posthog-edge',
+          method,
+        });
+      }
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  };
+
+  return {
+    name: 'posthog-edge',
+
+    async initialize() {
+      // No initialization needed for HTTP-based PostHog
+    },
+
+    async track(event: string, properties?: TrackProperties, context?: AnalyticsContext) {
+      const distinctId = context?.userId ?? properties?.distinctId ?? 'anonymous';
+      await safeFetch(
+        {
+          api_key: apiKey,
+          event,
+          distinct_id: distinctId,
+          properties: { ...properties, ...context },
+          timestamp: new Date().toISOString(),
+        },
+        'track',
+      );
+    },
+
+    async identify(userId: string, traits?: IdentifyTraits) {
+      await safeFetch(
+        {
+          api_key: apiKey,
+          event: '$identify',
+          distinct_id: userId,
+          properties: { $set: traits },
+        },
+        'identify',
+      );
+    },
+
+    async page(name?: string, properties?: PageProperties, context?: AnalyticsContext) {
+      const distinctId = context?.userId ?? 'anonymous';
+      await safeFetch(
+        {
+          api_key: apiKey,
+          event: '$pageview',
+          distinct_id: distinctId,
+          properties: { $current_url: properties?.url, $title: name, ...properties },
+        },
+        'page',
+      );
+    },
+
+    async group(groupId: string, traits?: GroupTraits, context?: AnalyticsContext) {
+      const distinctId = context?.userId ?? 'anonymous';
+      await safeFetch(
+        {
+          api_key: apiKey,
+          event: '$groupidentify',
+          distinct_id: distinctId,
+          properties: { $group_type: 'company', $group_key: groupId, $group_set: traits },
+        },
+        'group',
+      );
+    },
+
+    async alias(userId: string, previousId: string) {
+      await safeFetch(
+        {
+          api_key: apiKey,
+          event: '$create_alias',
+          properties: { distinct_id: userId, alias: previousId },
+        },
+        'alias',
+      );
+    },
+  };
+}
+
+// Export edge-compatible configuration utilities
+export { getAnalyticsConfig } from './shared/utils/config';

package/src/server-next.ts

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview Next.js server exports
+ *
+ * This module provides Next.js-specific server-side analytics functionality.
+ * It exports:
+ *
+ * - **Server Analytics**: All server exports from `./server`
+ * - **Middleware**: Framework-agnostic analytics middleware utilities
+ * - **Types**: Analytics middleware types and configurations
+ *
+ * **Middleware Usage**: For Next.js middleware, use the framework-agnostic middleware
+ * from `./next/middleware` and provide Next.js-specific adapters in your Next.js app.
+ *
+ * **Usage**: Import from `@od-oneapp/analytics/server/next` for Next.js server components,
+ * API routes, and server actions.
+ *
+ * @module @od-oneapp/analytics/server/next
+ */
+
+// Re-export everything from server
+export * from './server';
+
+// Export framework-agnostic middleware (use with Next.js adapters in app)
+export {
+  composeMiddleware,
+  conditionalAnalyticsMiddleware,
+  createAnalyticsMiddleware,
+  createAnalyticsMiddlewareConfig,
+  getAnalyticsContextFromHeaders,
+  getDistinctIdFromHeaders,
+} from './next/middleware';
+export type {
+  AnalyticsMiddlewareConfig,
+  MiddlewareRequest,
+  MiddlewareResponse,
+} from './next/middleware';
+
+// Export types
+export type * from './types';

package/src/server.ts

@@ -0,0 +1,106 @@
+/**
+ * @fileoverview Server exports for Node.js environments (non-Next.js)
+ *
+ * This module provides server-side analytics functionality for non-Next.js Node.js
+ * environments. It exports:
+ *
+ * - **Analytics Managers**: `createServerAnalytics()`, `createServerAnalyticsUninitialized()`
+ * - **Emitters**: Type-safe event tracking functions (track, identify, page, screen, group, alias)
+ * - **Ecommerce Emitters**: Comprehensive ecommerce event tracking
+ * - **AI Emitters**: AI product analytics tracking
+ * - **Emitter Utilities**: ContextBuilder, EventBatch, PayloadBuilder
+ * - **Adapter Utilities**: Emitter processing and ecommerce event tracking
+ * - **Configuration**: Full configuration utilities with validation
+ * - **Validation**: Server-side validation utilities including `validateConfigOrThrow()`
+ * - **PostHog Utilities**: Bootstrap data and distinct ID generation
+ *
+ * **Usage**: Import from `@od-oneapp/analytics/server` for Node.js server applications.
+ * For Next.js applications, use `@od-oneapp/analytics/server/next` instead.
+ *
+ * @module @od-oneapp/analytics/server
+ */
+
+// Export core server functions
+export { createServerAnalytics, createServerAnalyticsUninitialized } from './server/manager';
+
+// Export all emitters - these are the preferred way to track events
+export {
+  // Emitter utilities
+  ContextBuilder,
+  EventBatch,
+  PayloadBuilder,
+  alias,
+  createAnonymousSession,
+  createUserSession,
+  // Ecommerce emitters namespace
+  ecommerce,
+  group,
+  // Core Segment.io spec emitters
+  identify,
+  isAliasPayload,
+  isGroupPayload,
+  isIdentifyPayload,
+  isPagePayload,
+  // Type guards
+  isTrackPayload,
+  page,
+  screen,
+  track,
+  withMetadata,
+  withUTM,
+} from './shared/emitters';
+
+// Export adapter utilities
+export {
+  createEmitterProcessor,
+  // Emitter processing utilities
+  processEmitterPayload,
+  trackEcommerceEvent,
+} from './shared/utils/emitter-adapter';
+
+// Export configuration utilities
+export {
+  PROVIDER_REQUIREMENTS,
+  createConfigBuilder,
+  getAnalyticsConfig,
+  validateConfig,
+} from './shared/utils/config';
+
+// Export validation utilities
+export {
+  debugConfig,
+  validateAnalyticsConfig,
+  validateConfigOrThrow,
+  validateProvider,
+} from './shared/utils/validation';
+
+// Export manager utilities
+export {
+  AnalyticsManager as AnalyticsManagerClass,
+  createAnalyticsManager,
+} from './shared/utils/manager';
+
+// Export PostHog utilities
+export {
+  createBootstrapData,
+  createMinimalBootstrapData,
+  generateDistinctId,
+} from './shared/utils/posthog-bootstrap';
+
+// Export ingestion service
+export {
+  createIngestionService,
+  IngestionService,
+  validateEventPayload,
+  validateBatchPayload,
+} from './shared/ingestion';
+export type {
+  IngestionContext,
+  IngestionServiceConfig,
+  IngestionMetrics,
+  IngestionSuccessResponse,
+  IngestionErrorResponse,
+} from './shared/ingestion';
+
+// Export types
+export type * from './types';