@od-oneapp/analytics 2026.1.1301

package/src/providers/segment/types.ts

@@ -0,0 +1,51 @@
+/**
+ * @fileoverview Segment provider type definitions
+ *
+ * Defines TypeScript types and interfaces for Segment Analytics provider configuration.
+ * Includes browser and server-specific options.
+ *
+ * @module @repo/analytics/providers/segment/types
+ */
+
+import type { BaseProviderConfig } from '../base-provider';
+
+export interface SegmentConfig extends BaseProviderConfig {
+  writeKey: string;
+  options?: SegmentOptions | undefined;
+}
+
+interface SegmentOptions {
+  // Segment Analytics 2.0 options
+  integrations?: Record<string, any>;
+  timeout?: number;
+  retryQueue?: boolean;
+  plugins?: any[];
+
+  // Browser-specific options
+  anonymousId?: string;
+  initialPageview?: boolean;
+  cookie?: {
+    name?: string;
+    maxage?: number;
+    domain?: string;
+    path?: string;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+    secure?: boolean;
+  };
+
+  // Server-specific options
+  flushAt?: number;
+  flushInterval?: number;
+  maxEventsInBatch?: number;
+  maxRetries?: number;
+  requestTimeout?: number;
+
+  // Advanced options
+  debug?: boolean;
+  disable?: boolean;
+  disableClientPersistence?: boolean;
+  useBeacon?: boolean;
+  apiHost?: string;
+  cdnURL?: string;
+  cdnSettings?: any;
+}

package/src/providers/vercel/client.ts

@@ -0,0 +1,102 @@
+/**
+ * @fileoverview Vercel Analytics client-side (browser) provider implementation
+ *
+ * Provides client-side integration with Vercel Analytics for web analytics tracking.
+ * Supports automatic page view tracking and custom event tracking.
+ *
+ * @remarks
+ * This provider:
+ * - Uses @vercel/analytics package for client-side tracking
+ * - Supports dynamic imports to avoid SSR issues
+ * - Handles initialization and event tracking
+ * - Integrates with Vercel's analytics dashboard
+ *
+ * @module @repo/analytics/providers/vercel/client
+ */
+
+import type { VercelConfig } from './types';
+import type { AnalyticsProvider, ProviderConfig } from '../../shared/types/types';
+
+// Vercel Analytics types are handled by @vercel/analytics package
+
+export class VercelClientProvider implements AnalyticsProvider {
+  readonly name = 'vercel';
+  private config: VercelConfig;
+  private isInitialized = false;
+
+  constructor(config: ProviderConfig) {
+    this.config = {
+      options: config.options,
+    };
+  }
+
+  async initialize(): Promise<void> {
+    if (this.isInitialized) return;
+
+    try {
+      // Dynamically import Vercel Analytics
+      const { inject } = await import('@vercel/analytics');
+
+      // Initialize Vercel Analytics
+      inject(this.config.options);
+
+      this.isInitialized = true;
+    } catch {
+      throw new Error(
+        'Vercel Analytics not available. Install with: npm install @vercel/analytics',
+      );
+    }
+  }
+
+  async track(event: string, properties: any = {}): Promise<void> {
+    if (!this.isInitialized) {
+      return;
+    }
+
+    try {
+      // Import track function dynamically to avoid SSR issues
+      const { track } = await import('@vercel/analytics');
+      track(event, properties);
+    } catch {
+      // Silently fail to avoid disrupting app flow
+    }
+  }
+
+  async identify(userId: string, traits: any = {}): Promise<void> {
+    // Vercel Analytics doesn't have a native identify method
+    // We can track this as a custom event
+    await this.track('User Identified', {
+      userId,
+      ...traits,
+    });
+  }
+
+  async page(name?: string, properties: any = {}): Promise<void> {
+    // Vercel Analytics automatically tracks page views
+    // We can track additional page data as custom events if needed
+    if (name || Object.keys(properties).length > 0) {
+      await this.track('Page View', {
+        page: name,
+        ...properties,
+      });
+    }
+  }
+
+  async group(groupId: string, traits: any = {}): Promise<void> {
+    // Vercel Analytics doesn't have a native group method
+    // We can track this as a custom event
+    await this.track('Group Identified', {
+      groupId,
+      ...traits,
+    });
+  }
+
+  async alias(userId: string, previousId: string): Promise<void> {
+    // Vercel Analytics doesn't have a native alias method
+    // We can track this as a custom event
+    await this.track('User Aliased', {
+      previousId,
+      userId,
+    });
+  }
+}

package/src/providers/vercel/index.ts

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

package/src/providers/vercel/server.ts

@@ -0,0 +1,89 @@
+/**
+ * @fileoverview Vercel Analytics server-side (Node.js) provider implementation
+ *
+ * Provides server-side integration with Vercel Analytics.
+ * Note: Vercel Analytics is primarily client-side focused.
+ * Server-side tracking is limited and mainly for custom events.
+ *
+ * @remarks
+ * This provider:
+ * - Provides minimal server-side support
+ * - Most tracking should be done client-side
+ * - Can be extended for custom server-side events
+ *
+ * @module @repo/analytics/providers/vercel/server
+ */
+
+import type { AnalyticsProvider, ProviderConfig } from '../../shared/types/types';
+
+export class VercelServerProvider implements AnalyticsProvider {
+  readonly name = 'vercel';
+  private isInitialized = false;
+  private readonly config: ProviderConfig;
+
+  constructor(config: ProviderConfig) {
+    this.config = config;
+    // Server-side Vercel Analytics is limited - most tracking happens client-side
+  }
+
+  async initialize(): Promise<void> {
+    if (this.isInitialized) return;
+
+    // Vercel Analytics doesn't require server-side initialization
+    // Just mark as initialized
+    this.isInitialized = true;
+
+    // Note: Limited server-side support. Consider using client-side tracking for better features.
+  }
+
+  async track(event: string, properties: any = {}): Promise<void> {
+    if (!this.isInitialized) {
+      return;
+    }
+
+    try {
+      // Parameters are deliberately unused until server-side tracking is implemented.
+      void event;
+      void properties;
+      void this.config;
+      // For server-side, we can use Vercel's Speed Insights API if available
+      // Server-side tracking is limited - most tracking happens client-side
+      // In production, you might want to send to Vercel's API endpoint
+      // This would require additional setup and is not part of the standard SDK
+    } catch {
+      // Silently fail to avoid disrupting app flow
+    }
+  }
+
+  async identify(userId: string, traits: any = {}): Promise<void> {
+    // Track as custom event on server
+    await this.track('User Identified', {
+      userId,
+      ...traits,
+    });
+  }
+
+  async page(name?: string, properties: any = {}): Promise<void> {
+    // Track page view on server (limited utility)
+    await this.track('Page View (Server)', {
+      page: name,
+      ...properties,
+    });
+  }
+
+  async group(groupId: string, traits: any = {}): Promise<void> {
+    // Track as custom event on server
+    await this.track('Group Identified', {
+      groupId,
+      ...traits,
+    });
+  }
+
+  async alias(userId: string, previousId: string): Promise<void> {
+    // Track as custom event on server
+    await this.track('User Aliased', {
+      previousId,
+      userId,
+    });
+  }
+}

package/src/providers/vercel/types.ts

@@ -0,0 +1,27 @@
+/**
+ * @fileoverview Vercel provider type definitions
+ *
+ * Defines TypeScript types and interfaces for Vercel Analytics provider configuration.
+ *
+ * @module @repo/analytics/providers/vercel/types
+ */
+
+export interface VercelConfig {
+  // Vercel Analytics doesn't require configuration in most cases
+  // It auto-detects the environment and deployment context
+  options?: VercelOptions | undefined;
+}
+
+interface VercelOptions {
+  // Vercel Web Analytics options
+  debug?: boolean;
+  disabled?: boolean;
+
+  // Custom event tracking options
+  beforeSend?: (event: any) => any | null;
+
+  // Advanced options
+  mode?: 'auto' | 'development' | 'production';
+  framework?: string;
+  dsn?: string;
+}

package/src/server/index.ts

@@ -0,0 +1,103 @@
+/**
+ * @fileoverview Server-side analytics exports
+ * Server-side analytics exports
+ * Complete analytics solution for server/Node.js environments
+ *
+ * @example
+ * ```typescript
+ * import { createServerAnalytics, track, ecommerce } from '@od-oneapp/analytics/server';
+ *
+ * const analytics = await createServerAnalytics({
+ *   providers: {
+ *     segment: { writeKey: 'xxx' },
+ *     http: { endpoint: 'https://api.example.com/ingest' }
+ *   }
+ * });
+ *
+ * // Preferred: Use emitters
+ * await analytics.emit(track('API Called', { endpoint: '/users' }));
+ * await analytics.emit(ecommerce.orderCompleted({ order_id: '123' }));
+ * ```
+ */
+
+import { SegmentServerProvider } from '@integrations/segment/analytics-provider/server';
+import { VercelServerProvider } from '@integrations/vercel/analytics-provider/server';
+
+import { ConsoleProvider } from '../providers/console/server';
+import { HttpServerProvider } from '../providers/http/server';
+import { createAnalyticsManager } from '../shared/utils/manager';
+
+import type { AnalyticsConfig, AnalyticsManager, ProviderRegistry } from '../shared/types/types';
+
+// Server-specific provider registry
+const SERVER_PROVIDERS: ProviderRegistry = {
+  console: config => new ConsoleProvider(config),
+  http: config => new HttpServerProvider(config),
+  segment: config => new SegmentServerProvider(config),
+  vercel: config => new VercelServerProvider(config),
+};
+
+// ============================================================================
+// CORE ANALYTICS FUNCTIONS
+// ============================================================================
+
+/**
+ * Create and initialize a server analytics instance
+ * This is the primary way to create analytics for server-side applications
+ */
+export async function createServerAnalytics(config: AnalyticsConfig): Promise<AnalyticsManager> {
+  const manager = createAnalyticsManager(config, SERVER_PROVIDERS);
+  await manager.initialize();
+  return manager;
+}
+
+/**
+ * Create a server analytics instance without initializing
+ * Useful when you need to control initialization timing
+ *
+ * @deprecated This function is currently unused but kept for potential future use
+ */
+// function _createServerAnalyticsUninitialized(config: AnalyticsConfig): AnalyticsManager {
+//   return createAnalyticsManager(config, SERVER_PROVIDERS);
+// }
+
+// ============================================================================
+// EMITTERS - PRIMARY INTERFACE
+// ============================================================================
+
+// Export all core emitters - these are the preferred way to track events
+export {} from '../shared/emitters';
+
+// ============================================================================
+// ADAPTER UTILITIES
+// ============================================================================
+
+export {} from '../shared/utils/emitter-adapter';
+
+// ============================================================================
+// TYPES
+// ============================================================================
+
+// Core analytics types;
+
+// Emitter types;
+
+// Provider-specific types;
+
+// Ecommerce types;
+
+// ============================================================================
+// CONFIGURATION UTILITIES
+// ============================================================================
+
+// ============================================================================
+// VALIDATION UTILITIES
+// ============================================================================
+
+// ============================================================================
+// ADVANCED UTILITIES
+// ============================================================================
+
+// Manager utilities
+
+// Export Node 22+ enhanced features for server-side use

package/src/server/manager.ts

@@ -0,0 +1,62 @@
+/**
+ * @fileoverview Server analytics manager with static provider registry
+ * Server analytics manager with static provider registry
+ */
+
+import { SegmentServerProvider } from '@integrations/segment/analytics-provider/server';
+import { VercelServerProvider } from '@integrations/vercel/analytics-provider/server';
+
+import { ConsoleProvider } from '../providers/console/server';
+import { HttpServerProvider } from '../providers/http/server';
+import { createAnalyticsManager } from '../shared/utils/manager';
+
+import type { AnalyticsConfig, AnalyticsManager, ProviderRegistry } from '../shared/types/types';
+
+// Static provider registry for server environments
+const SERVER_PROVIDERS: ProviderRegistry = {
+  console: config => new ConsoleProvider(config),
+  http: config => new HttpServerProvider(config),
+  segment: config => new SegmentServerProvider(config),
+  vercel: config => new VercelServerProvider(config),
+};
+
+/**
+ * Create and initialize a server analytics instance
+ * This is the primary way to create analytics for server-side applications
+ *
+ * @example
+ * ```typescript
+ * const analytics = await createServerAnalytics({
+ *   providers: {
+ *     segment: { writeKey: process.env.SEGMENT_KEY! },
+ *   },
+ * });
+ * await analytics.page('/admin', { title: 'Admin Dashboard' });
+ * ```
+ * @param config - Analytics configuration including providers and settings
+ * @returns Promise resolving to initialized analytics manager
+ */
+export async function createServerAnalytics(config: AnalyticsConfig): Promise<AnalyticsManager> {
+  const manager = createAnalyticsManager(config, SERVER_PROVIDERS);
+  await manager.initialize();
+  return manager;
+}
+
+/**
+ * Create a server analytics instance without initializing
+ * Useful when you need to control initialization timing
+ *
+ * @example
+ * ```typescript
+ * const analytics = createServerAnalyticsUninitialized(config);
+ * if (shouldEmit) {
+ *   await analytics.initialize();
+ *   await analytics.track('CRON Completed');
+ * }
+ * ```
+ * @param config - Analytics configuration including providers and settings
+ * @returns Uninitialized analytics manager instance
+ */
+export function createServerAnalyticsUninitialized(config: AnalyticsConfig): AnalyticsManager {
+  return createAnalyticsManager(config, SERVER_PROVIDERS);
+}

package/src/server/next.ts

@@ -0,0 +1,210 @@
+/**
+ * @fileoverview Server-side Next.js analytics exports
+ * Server-side Next.js analytics exports
+ * Complete Next.js 15 integration for server components, API routes, and middleware
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createNextJSServerAnalytics,
+ *   trackServerEvent,
+ *   getServerFeatureFlag,
+ *   createAnalyticsMiddleware
+ * } from '@od-oneapp/analytics/server/next';
+ *
+ * // Server component
+ * export default async function Page() {
+ *   await trackServerEvent('Page Viewed', { path: '/home' });
+ *   return <div>Page content</div>;
+ * }
+ *
+ * // Middleware
+ * export const middleware = createAnalyticsMiddleware({
+ *   providers: { segment: { writeKey: process.env.SEGMENT_WRITE_KEY } }
+ * });
+ * ```
+ */
+
+// ============================================================================
+// CORE SERVER ANALYTICS (re-export everything from server)
+// ============================================================================
+
+// Re-export everything from server for convenience
+export * from '.';
+
+// ============================================================================
+// REACT SERVER COMPONENTS
+// ============================================================================
+
+export {
+  // Context management for RSCs
+  ServerAnalyticsProvider,
+  getServerBootstrapData,
+  identifyServerUser,
+  identifyUserAction,
+  // Server Actions support
+  trackEventAction,
+  // Server component tracking functions
+  trackServerEvent,
+  trackServerPageView,
+  withServerPageTracking,
+} from '../next/rsc';
+
+// ============================================================================
+// NEXT.JS SERVER ANALYTICS MANAGER
+// ============================================================================
+
+export {
+  // Next.js server analytics manager
+  NextJSServerAnalyticsManager,
+  createNextJSServerAnalytics,
+  createNextJSServerAnalyticsWithBootstrap,
+} from '../next/server';
+
+export type { NextJSServerAnalyticsConfig } from '../next/server';
+
+// ============================================================================
+// POSTHOG SERVER-SIDE BOOTSTRAP
+// ============================================================================
+
+export { getPostHogBootstrapDataOnServer } from '../next/server';
+
+// Additional PostHog utilities
+export {
+  // PostHog Next.js utilities
+  createPostHogConfig,
+  createPostHogMiddleware,
+  createPostHogServerClient,
+  createPostHogSuspenseData,
+  getCompleteBootstrapData,
+  getOrGenerateDistinctId,
+  getPostHogBootstrapData,
+} from '../shared/utils/posthog-next-utils';
+
+// ============================================================================
+// MIDDLEWARE INTEGRATION
+// ============================================================================
+
+export {
+  // Analytics middleware for edge runtime
+  createAnalyticsMiddleware,
+} from '../next/middleware';
+
+export type {
+  // Middleware types
+  AnalyticsMiddlewareConfig,
+} from '../next/middleware';
+
+// ============================================================================
+// NEXT.JS TYPES
+// ============================================================================
+
+export type {
+  AddToCartEvent,
+  // Next.js specific types that actually exist
+  AnalyticsEvent,
+  AnalyticsMiddlewareContext,
+  AnalyticsProviderProps,
+  CheckoutEvent,
+  EventName,
+  EventProperties,
+  FormErrorEvent,
+  FormStartEvent,
+  FormSubmitEvent,
+  PageViewEvent,
+  ProductViewEvent,
+  PurchaseEvent,
+  TrackedComponentProps,
+  TypedTrackFunction,
+  UseAnalyticsReturn,
+} from '../next/types';
+
+// ============================================================================
+// USAGE EXAMPLES & PATTERNS
+// ============================================================================
+
+/**
+ * Example usage patterns for server-side Next.js analytics
+ *
+ * @example Server component tracking
+ * ```typescript
+ * import { trackServerEvent, getServerFeatureFlag } from '@od-oneapp/analytics/server/next';
+ * import { cookies } from 'next/headers';
+ *
+ * export default async function HomePage() {
+ *   // Track page view
+ *   await trackServerEvent('Page Viewed', {
+ *     path: '/home',
+ *     title: 'Home Page'
+ *   });
+ *
+ *   // Check feature flag
+ *   const showBeta = await getServerFeatureFlag('beta-feature', cookies());
+ *
+ *   return (
+ *     <div>
+ *       <h1>Welcome</h1>
+ *       {showBeta && <BetaFeature />}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example API route tracking
+ * ```typescript
+ * import { createServerAnalytics, track } from '@od-oneapp/analytics/server/next';
+ *
+ * const analytics = await createServerAnalytics({
+ *   providers: {
+ *     segment: { writeKey: process.env.SEGMENT_WRITE_KEY }
+ *   }
+ * });
+ *
+ * export async function POST(request: Request) {
+ *   await analytics.emit(track('API Called', {
+ *     endpoint: '/api/users',
+ *     method: 'POST'
+ *   }));
+ *
+ *   // Handle request...
+ * }
+ * ```
+ *
+ * @example Server Actions
+ * ```typescript
+ * 'use server';
+ * import { trackServerAction } from '@od-oneapp/analytics/server/next';
+ *
+ * export async function submitForm(formData: FormData) {
+ *   await trackServerAction('Form Submitted', {
+ *     form_id: 'contact',
+ *     email: formData.get('email')
+ *   });
+ *
+ *   // Process form...
+ * }
+ * ```
+ *
+ * @example Middleware setup
+ * ```typescript
+ * // middleware.ts
+ * import { createAnalyticsMiddleware } from '@od-oneapp/analytics/server/next';
+ *
+ * export const middleware = createAnalyticsMiddleware({
+ *   providers: {
+ *     segment: { writeKey: process.env.SEGMENT_WRITE_KEY }
+ *   },
+ *   matchers: ['/api/*', '/app/*'],
+ *   exclude: ['/api/health'],
+ *   extractUserId: (request) => request.headers.get('x-user-id'),
+ *   extractContext: (request) => ({
+ *     ip: request.ip,
+ *     country: request.geo?.country
+ *   })
+ * });
+ *
+ * export const config = {
+ *   matcher: ['/((?!_next/static|favicon.ico).*)']
+ * };
+ * ```
+ */