@od-oneapp/analytics 2026.1.1301

package/src/client/next.ts

@@ -0,0 +1,144 @@
+/**
+ * @fileoverview Client-side Next.js analytics exports
+ * Client-side Next.js analytics exports
+ * Complete Next.js 15 integration for client components and browser environments
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createNextJSClientAnalytics,
+ *   usePageTracking,
+ *   useTrackEvent,
+ *   track
+ * } from '@od-oneapp/analytics/client/next';
+ *
+ * // Create Next.js optimized analytics
+ * const analytics = createNextJSClientAnalytics({
+ *   providers: { segment: { writeKey: 'xxx' } },
+ *   nextjs: { strategy: 'afterInteractive', bufferEvents: true }
+ * });
+ *
+ * // Use in client components
+ * function MyComponent() {
+ *   const trackEvent = useTrackEvent();
+ *   usePageTracking(); // Auto page tracking
+ *
+ *   return <button onClick={() => trackEvent('Button Clicked', { color: 'blue' })}>
+ *     Click me
+ *   </button>;
+ * }
+ * ```
+ */
+
+// ============================================================================
+// CORE CLIENT ANALYTICS (re-export everything from client)
+// ============================================================================
+
+// Re-export everything from client for convenience
+export * from '.';
+
+// ============================================================================
+// NEXT.JS CLIENT COMPONENTS & HOOKS
+// ============================================================================
+
+export {
+  // Context providers
+  AnalyticsProvider,
+  // Tracked components
+  TrackedButton,
+  TrackedLink,
+  useAnalytics,
+  // React hooks for client components
+  usePageTracking,
+  useTrackEvent,
+} from '../next/app-router';
+
+// Note: Export types only if they exist in the app-router module
+// Many of these types may not be implemented yet
+
+// ============================================================================
+// NEXT.JS CLIENT ANALYTICS MANAGER
+// ============================================================================
+
+export {
+  // Next.js client analytics manager
+  NextJSClientAnalyticsManager,
+  createNextJSClientAnalytics,
+  // PostHog bootstrap helpers
+  createPostHogConfigWithBootstrap,
+
+  // Script integration helpers
+  getAnalyticsScriptProps,
+} from '../next/client';
+
+export type { NextJSClientAnalyticsConfig } from '../next/client';
+
+// ============================================================================
+// NEXT.JS TYPES
+// ============================================================================
+
+// Note: Next.js types exports have been moved to avoid non-existent type errors
+// Import the actual types from their respective modules as needed
+
+// ============================================================================
+// USAGE EXAMPLES & PATTERNS
+// ============================================================================
+
+/**
+ * Example usage patterns for client-side Next.js analytics
+ *
+ * @example Basic setup in layout.tsx
+ * ```typescript
+ * 'use client';
+ * import { AnalyticsProvider, usePageTracking } from '@od-oneapp/analytics/client/next';
+ *
+ * function RootLayoutContent({ children }) {
+ *   usePageTracking(); // Auto page tracking
+ *   return <>{children}</>;
+ * }
+ *
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <AnalyticsProvider config={{
+ *       providers: {
+ *         segment: { writeKey: process.env.NEXT_PUBLIC_SEGMENT_WRITE_KEY }
+ *       }
+ *     }}>
+ *       <RootLayoutContent>{children}</RootLayoutContent>
+ *     </AnalyticsProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example Event tracking in components
+ * ```typescript
+ * 'use client';
+ * import { useTrackEvent, track } from '@od-oneapp/analytics/client/next';
+ *
+ * function MyComponent() {
+ *   const trackEvent = useTrackEvent();
+ *
+ *   const handleClick = () => {
+ *     trackEvent('Button Clicked', { location: 'hero' });
+ *   };
+ *
+ *   return <button onClick={handleClick}>Click me</button>;
+ * }
+ * ```
+ *
+ * @example Feature flags
+ * ```typescript
+ * 'use client';
+ * import { useFeatureFlag } from '@od-oneapp/analytics/client/next';
+ *
+ * function FeatureComponent() {
+ *   const showNewFeature = useFeatureFlag('new-feature');
+ *
+ *   return (
+ *     <div>
+ *       {showNewFeature ? <NewFeature /> : <OldFeature />}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */

package/src/client-next.ts

@@ -0,0 +1,101 @@
+/**
+ * @fileoverview Next.js client exports
+ *
+ * This module provides Next.js-specific client-side analytics functionality.
+ * It exports:
+ *
+ * - **Analytics Managers**: `createNextJSClientAnalytics()`, `createNextJSClientAnalyticsUninitialized()`
+ * - **React Hooks**: `useAnalytics()`, `usePageTracking()`, `useTrackEvent()`, `useIdentifyUser()`
+ * - **React Components**: `AnalyticsProvider`, `TrackedButton`, `TrackedLink`, `withViewTracking()`
+ * - **Emitters**: Type-safe event tracking functions
+ * - **Ecommerce Emitters**: Comprehensive ecommerce event tracking
+ * - **AI Emitters**: AI product analytics tracking
+ * - **Configuration**: Client-safe configuration utilities
+ * - **PostHog Utilities**: Bootstrap data and cookie utilities
+ *
+ * **Usage**: Import from `@od-oneapp/analytics/client/next` for Next.js client components.
+ *
+ * @module @od-oneapp/analytics/client/next
+ */
+
+'use client';
+
+// Export Next.js specific analytics manager
+export {
+  createNextJSClientAnalytics,
+  createNextJSClientAnalyticsUninitialized,
+} from './client/next/manager';
+
+// Export Next.js hooks
+export {
+  resetAnalytics,
+  useAnalytics,
+  useIdentifyUser,
+  usePageTracking,
+  useTrackEvent,
+} from './client/next/hooks';
+
+// Export Next.js components
+export {
+  AnalyticsProvider,
+  TrackedButton,
+  TrackedLink,
+  withViewTracking,
+} from './client/next/components';
+
+// 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 client-safe configuration utilities
+export {
+  PROVIDER_REQUIREMENTS,
+  createConfigBuilder,
+  getAnalyticsConfig,
+  validateConfig,
+} from './shared/utils/config-client';
+
+// Validation utilities removed - validation should happen on the server side only
+// This follows the four-file export pattern to avoid importing server-only dependencies
+
+// Export PostHog utilities
+export {
+  createBootstrapData,
+  createMinimalBootstrapData,
+  generateDistinctId,
+  getDistinctIdFromCookies,
+} from './shared/utils/posthog-bootstrap';
+
+// Export types
+export type * from './types';

package/src/client.ts

@@ -0,0 +1,89 @@
+/**
+ * @fileoverview Client exports for browser environments (non-Next.js)
+ *
+ * This module provides client-side analytics functionality for non-Next.js browser
+ * environments. It exports:
+ *
+ * - **Analytics Managers**: `createClientAnalytics()`, `createClientAnalyticsUninitialized()`
+ * - **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**: Client-safe configuration utilities
+ * - **Validation**: Client-safe validation utilities
+ * - **PostHog Utilities**: Bootstrap data and distinct ID generation
+ *
+ * **Usage**: Import from `@od-oneapp/analytics/client` for browser-only applications.
+ * For Next.js applications, use `@od-oneapp/analytics/client/next` instead.
+ *
+ * @module @od-oneapp/analytics/client
+ */
+
+// Export core client functions
+export { createClientAnalytics, createClientAnalyticsUninitialized } from './client/manager';
+
+// Export all emitters - these are the preferred way to track events
+export {
+  // Emitter utilities
+  ContextBuilder,
+  EventBatch,
+  PayloadBuilder,
+  // AI emitters namespace
+  aiSdk as ai,
+  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 client-safe configuration utilities
+export {
+  PROVIDER_REQUIREMENTS,
+  createConfigBuilder,
+  getAnalyticsConfig,
+  validateConfig,
+} from './shared/utils/config-client';
+
+// Export client-safe validation utilities
+export { validateAnalyticsConfig, validateProvider } from './shared/utils/validation-client';
+
+// Export manager utilities
+export {
+  AnalyticsManager as AnalyticsManagerClass,
+  createAnalyticsManager,
+} from './shared/utils/manager';
+
+// Export PostHog utilities
+export {
+  createBootstrapData,
+  createMinimalBootstrapData,
+  generateDistinctId,
+  getDistinctIdFromCookies,
+} from './shared/utils/posthog-bootstrap';
+
+// Export types
+export type * from './types';