@od-oneapp/analytics 2026.1.1301

package/src/shared/emitters/index.ts

@@ -0,0 +1,66 @@
+/**
+ * @fileoverview Analytics Emitters - The Recommended Way to Track Events
+ *
+ * Emitters provide type-safe, consistent event tracking following
+ * the Segment.io specification. They are the primary pattern for
+ * analytics in this package.
+ *
+ * **Core Emitters**:
+ * - `identify()`: Identify users with traits
+ * - `track()`: Track custom events
+ * - `page()`: Track page views
+ * - `screen()`: Track screen views (mobile)
+ * - `group()`: Associate users with groups
+ * - `alias()`: Alias user IDs
+ *
+ * **Namespace Emitters**:
+ * - `ecommerce.*`: E-commerce specific events (product viewed, cart updated, etc.)
+ * - `aiSdk.*`: AI SDK v6 specific events (chat completion, tool calls, etc.)
+ *
+ * **Helper Utilities**:
+ * - `ContextBuilder`: Build consistent context across events
+ * - `PayloadBuilder`: Chain emitter creation
+ * - `EventBatch`: Batch related events with shared context
+ * - `createUserSession()`: Create a user session tracking flow
+ * - `createAnonymousSession()`: Create an anonymous user tracking flow
+ * - `withMetadata()`: Add consistent metadata to events
+ * - `withUTM()`: Add UTM parameters to events
+ *
+ * @module @od-oneapp/analytics/shared/emitters
+ */
+
+// Export core emitter functions as the primary API
+export {
+  alias,
+  group,
+  identify,
+  page,
+  screen,
+  // Main emitter functions
+  track,
+} from './emitters';
+
+// Export all emitter types
+export * from './emitter-types';
+
+// Export helper utilities for easier emitter usage
+export * from './helpers';
+
+// Export convenience builders
+export {
+  ContextBuilder,
+  EventBatch,
+  PayloadBuilder,
+  createAnonymousSession,
+  createUserSession,
+  withMetadata,
+  withUTM,
+} from './helpers';
+
+// Export ecommerce emitters as a namespace
+export * as ecommerce from './ecommerce';
+
+// Export AI SDK v6 emitters as a namespace
+export * as aiSdk from './ai';
+
+// Re-export ecommerce types for convenience

package/src/shared/index.ts

@@ -0,0 +1,142 @@
+/**
+ * @fileoverview Shared Analytics Exports
+ *
+ * This module provides shared exports for both client and server environments.
+ * Contains types, utilities, and emitters that work universally across all
+ * runtime environments (Node.js, Edge, Browser).
+ *
+ * @module @od-oneapp/analytics/shared
+ */
+
+// Export all types
+export type {
+  AnalyticsConfig,
+  AnalyticsContext,
+  // Core types
+  AnalyticsProvider,
+  ProviderConfig,
+  ProviderFactory,
+  ProviderRegistry,
+  TrackingOptions,
+} from './types/types';
+
+// Export provider-specific types
+export type {
+  // Segment types
+  SegmentConfig,
+  SegmentOptions,
+} from './types/segment-types';
+
+export type {
+  BootstrapData,
+  EnhancedPostHogProvider,
+  ExperimentInfo,
+  // PostHog types
+  PostHogConfig,
+  PostHogCookie,
+  PostHogOptions,
+} from './types/posthog-types';
+
+export type {
+  // Vercel types
+  VercelConfig,
+  VercelOptions,
+} from './types/vercel-types';
+
+export type {
+  // Console types
+  ConsoleConfig,
+  ConsoleOptions,
+  LogLevel,
+} from './types/console-types';
+
+// Export emitter types
+export type {
+  AnalyticsEmitter,
+  EmitterAliasPayload,
+  EmitterBasePayload,
+  EmitterConfig,
+  EmitterContext,
+  EmitterEventProperties,
+  EmitterGroupPayload,
+  EmitterGroupTraits,
+  EmitterIdentifyPayload,
+  EmitterIntegrations,
+  EmitterOptions,
+  EmitterPagePayload,
+  EmitterPayload,
+  EmitterScreenPayload,
+  EmitterTrackPayload,
+  EmitterUserTraits,
+} from './emitters/emitter-types';
+
+// Export all emitters
+export * from './emitters';
+
+// Export utilities
+export {
+  PROVIDER_REQUIREMENTS,
+  createConfigBuilder,
+  // Configuration
+  getAnalyticsConfig,
+  validateConfig,
+} from './utils/config';
+
+export type { ConfigBuilder, ConfigRequirements } from './utils/config';
+
+// Export Node 22+ enhanced features
+export {
+  AdvancedEventBatcher,
+  Node22AnalyticsManager,
+  createNode22AnalyticsManager,
+  node22Analytics,
+} from './node22-features';
+
+export {
+  debugConfig,
+  // Validation
+  validateAnalyticsConfig,
+  validateConfigOrThrow,
+  validateProvider,
+} from './utils/validation';
+
+export type { ValidationError, ValidationResult } from './utils/validation';
+
+export {
+  // Manager
+  createAnalyticsManager,
+} from './utils/manager';
+
+export { AnalyticsManager as AnalyticsManagerClass } from './utils/manager';
+
+export {
+  createBootstrapData,
+  createMinimalBootstrapData,
+  // PostHog utilities
+  generateDistinctId,
+  getCachedBootstrapData,
+  getDistinctIdFromCookies,
+  setCachedBootstrapData,
+} from './utils/posthog-bootstrap';
+
+export {
+  createPostHogConfig,
+  // PostHog Next.js utilities
+  createPostHogServerClient,
+  getCompleteBootstrapData,
+} from './utils/posthog-next-utils';
+
+export {
+  createEmitterProcessor,
+  processAliasPayload,
+  // Emitter adapter utilities
+  processEmitterPayload,
+  processGroupPayload,
+  processIdentifyPayload,
+  processPagePayload,
+  processTrackPayload,
+  trackEcommerceEvent,
+} from './utils/emitter-adapter';
+
+// Export console provider (works in both environments)
+export { ConsoleProvider } from './providers/console-provider';

package/src/shared/ingestion/index.ts

@@ -0,0 +1,66 @@
+/**
+ * @fileoverview Event Ingestion Module
+ *
+ * Exports for the event ingestion system. Provides schemas, service, and utilities
+ * for validating and processing analytics events from external sources.
+ *
+ * @module @od-oneapp/analytics/shared/ingestion
+ */
+
+// Export schemas
+export {
+  // Base schemas
+  PropertyValueSchema,
+  PropertyObjectSchema,
+  EmitterContextSchema,
+
+  // Event type schemas
+  TrackEventSchema,
+  IdentifyEventSchema,
+  PageEventSchema,
+  ScreenEventSchema,
+  GroupEventSchema,
+  AliasEventSchema,
+  EventPayloadSchema,
+
+  // Request/response schemas
+  SingleEventRequestSchema,
+  BatchEventRequestSchema,
+  IngestionRequestSchema,
+  EventResultSchema,
+  IngestionSuccessResponseSchema,
+  IngestionErrorResponseSchema,
+  IngestionResponseSchema,
+} from './schemas';
+
+// Export types
+export type {
+  PropertyValue,
+  PropertyObject,
+  EmitterContext,
+  TrackEvent,
+  IdentifyEvent,
+  PageEvent,
+  ScreenEvent,
+  GroupEvent,
+  AliasEvent,
+  EventPayload,
+  SingleEventRequest,
+  BatchEventRequest,
+  IngestionRequest,
+  EventResult,
+  IngestionSuccessResponse,
+  IngestionErrorResponse,
+  IngestionResponse,
+} from './schemas';
+
+// Export service
+export {
+  IngestionService,
+  createIngestionService,
+  validateEventPayload,
+  validateBatchPayload,
+} from './service';
+
+// Export service types
+export type { IngestionContext, IngestionServiceConfig, IngestionMetrics } from './service';

package/src/shared/ingestion/schemas.ts

@@ -0,0 +1,386 @@
+/**
+ * @fileoverview Event Ingestion Schemas and Validation
+ *
+ * Defines Zod schemas for validating event ingestion payloads. These schemas
+ * ensure type-safe, secure event ingestion with proper validation.
+ *
+ * **Key Features**:
+ * - CloudEvents-style fields for future interoperability
+ * - Support for single events and batched arrays
+ * - Strict validation of required fields
+ * - Typed extensions per event category
+ *
+ * @module @od-oneapp/analytics/shared/ingestion/schemas
+ */
+
+import { z } from 'zod';
+
+// =============================================================================
+// Base Schemas
+// =============================================================================
+
+/**
+ * Property value schema - safe, serializable values only.
+ */
+export const PropertyValueSchema = z.union([
+  z.string(),
+  z.number(),
+  z.boolean(),
+  z.null(),
+  z.date(), // Accept Date objects only; ISO strings are already handled as strings
+]);
+
+/**
+ * Property object schema with nested structure support.
+ */
+export const PropertyObjectSchema: z.ZodType<Record<string, unknown>> = z.record(
+  z.string(),
+  z.lazy(() =>
+    z.union([PropertyValueSchema, z.array(PropertyValueSchema), z.record(z.string(), z.unknown())]),
+  ),
+);
+
+/**
+ * Emitter context schema - contextual information about the environment.
+ */
+export const EmitterContextSchema = z
+  .object({
+    /** Application information */
+    app: z
+      .object({
+        name: z.string().optional(),
+        version: z.string().optional(),
+        build: z.string().optional(),
+        namespace: z.string().optional(),
+      })
+      .optional(),
+
+    /** Campaign/UTM information */
+    campaign: z
+      .object({
+        name: z.string().optional(),
+        source: z.string().optional(),
+        medium: z.string().optional(),
+        term: z.string().optional(),
+        content: z.string().optional(),
+      })
+      .passthrough()
+      .optional(),
+
+    /** Device information */
+    device: z
+      .object({
+        id: z.string().optional(),
+        manufacturer: z.string().optional(),
+        model: z.string().optional(),
+        name: z.string().optional(),
+        type: z.string().optional(),
+        version: z.string().optional(),
+      })
+      .optional(),
+
+    /** User's IP address */
+    ip: z.string().optional(),
+
+    /** Library making the request */
+    library: z
+      .object({
+        name: z.string(),
+        version: z.string(),
+      })
+      .optional(),
+
+    /** User's locale (e.g., 'en-US') */
+    locale: z.string().optional(),
+
+    /** Network information */
+    network: z
+      .object({
+        bluetooth: z.boolean().optional(),
+        carrier: z.string().optional(),
+        cellular: z.boolean().optional(),
+        wifi: z.boolean().optional(),
+      })
+      .optional(),
+
+    /** OS information */
+    os: z
+      .object({
+        name: z.string().optional(),
+        version: z.string().optional(),
+      })
+      .optional(),
+
+    /** Page information */
+    page: z
+      .object({
+        path: z.string().optional(),
+        // Use permissive string validation for referrer/url since real-world values
+        // may be malformed, truncated, or non-standard (e.g., data: URIs, about:blank)
+        referrer: z.string().optional(),
+        search: z.string().optional(),
+        title: z.string().optional(),
+        url: z.string().optional(),
+      })
+      .optional(),
+
+    /** Screen information */
+    screen: z
+      .object({
+        density: z.number().optional(),
+        height: z.number().int().positive().optional(),
+        width: z.number().int().positive().optional(),
+      })
+      .optional(),
+
+    /** User's timezone (tzdata string) */
+    timezone: z.string().optional(),
+
+    /** Group/account ID */
+    groupId: z.string().optional(),
+
+    /** User agent string */
+    userAgent: z.string().optional(),
+
+    /** Channel where request originated */
+    channel: z.enum(['server', 'browser', 'mobile', 'api']).optional(),
+
+    /** Location context */
+    location: z
+      .object({
+        city: z.string().optional(),
+        country: z.string().optional(),
+        latitude: z.number().optional(),
+        longitude: z.number().optional(),
+        region: z.string().optional(),
+      })
+      .optional(),
+  })
+  .passthrough();
+
+// =============================================================================
+// Event Type Schemas
+// =============================================================================
+
+/**
+ * Base payload schema - common fields for all event types.
+ */
+const BasePayloadSchema = z
+  .object({
+    /** Anonymous ID if user is not identified */
+    anonymousId: z.string().max(255).optional(),
+
+    /** User ID (at least one of userId or anonymousId required) */
+    userId: z.string().max(255).optional(),
+
+    /** Timestamp when the event occurred */
+    timestamp: z.union([z.string().datetime(), z.date()]).optional(),
+
+    /** Original timestamp before processing */
+    originalTimestamp: z.union([z.string().datetime(), z.date()]).optional(),
+
+    /** Context and control fields */
+    context: EmitterContextSchema.optional(),
+
+    /** Message ID for deduplication */
+    messageId: z.string().uuid().optional(),
+  })
+  .refine(data => Boolean(data.anonymousId) || Boolean(data.userId), {
+    message: 'Either anonymousId or userId must be provided',
+  });
+
+/**
+ * Track event payload schema.
+ * Uses safeExtend() because BasePayloadSchema has refinements (Zod v4 requirement).
+ */
+export const TrackEventSchema = BasePayloadSchema.safeExtend({
+  type: z.literal('track'),
+  event: z.string().min(1).max(255),
+  properties: PropertyObjectSchema.optional(),
+});
+
+/**
+ * Identify event payload schema.
+ * Uses safeExtend() because BasePayloadSchema has refinements (Zod v4 requirement).
+ */
+export const IdentifyEventSchema = BasePayloadSchema.safeExtend({
+  type: z.literal('identify'),
+  userId: z.string().min(1).max(255),
+  traits: PropertyObjectSchema.optional(),
+});
+
+/**
+ * Page event payload schema.
+ * Uses safeExtend() because BasePayloadSchema has refinements (Zod v4 requirement).
+ */
+export const PageEventSchema = BasePayloadSchema.safeExtend({
+  type: z.literal('page'),
+  name: z.string().max(255).optional(),
+  category: z.string().max(255).optional(),
+  properties: PropertyObjectSchema.optional(),
+});
+
+/**
+ * Screen event payload schema.
+ * Uses safeExtend() because BasePayloadSchema has refinements (Zod v4 requirement).
+ */
+export const ScreenEventSchema = BasePayloadSchema.safeExtend({
+  type: z.literal('screen'),
+  name: z.string().max(255).optional(),
+  category: z.string().max(255).optional(),
+  properties: PropertyObjectSchema.optional(),
+});
+
+/**
+ * Group event payload schema.
+ * Uses safeExtend() because BasePayloadSchema has refinements (Zod v4 requirement).
+ */
+export const GroupEventSchema = BasePayloadSchema.safeExtend({
+  type: z.literal('group'),
+  groupId: z.string().min(1).max(255),
+  traits: PropertyObjectSchema.optional(),
+});
+
+/**
+ * Alias event payload schema.
+ * Uses safeExtend() because BasePayloadSchema has refinements (Zod v4 requirement).
+ */
+export const AliasEventSchema = BasePayloadSchema.safeExtend({
+  type: z.literal('alias'),
+  userId: z.string().min(1).max(255),
+  previousId: z.string().min(1).max(255),
+});
+
+/**
+ * Union of all event payload schemas.
+ */
+export const EventPayloadSchema = z.discriminatedUnion('type', [
+  TrackEventSchema,
+  IdentifyEventSchema,
+  PageEventSchema,
+  ScreenEventSchema,
+  GroupEventSchema,
+  AliasEventSchema,
+]);
+
+// =============================================================================
+// Ingestion Request Schemas
+// =============================================================================
+
+/**
+ * Single event ingestion request schema.
+ */
+export const SingleEventRequestSchema = EventPayloadSchema;
+
+/**
+ * Batch event ingestion request schema.
+ *
+ * The batch size limit is enforced at the service level via `maxBatchSize` config
+ * (default: 100) rather than in the schema, allowing for flexible configuration.
+ */
+export const BatchEventRequestSchema = z.object({
+  batch: z.array(EventPayloadSchema).min(1),
+});
+
+/**
+ * Combined ingestion request schema - accepts single event or batch.
+ */
+export const IngestionRequestSchema = z.union([BatchEventRequestSchema, SingleEventRequestSchema]);
+
+// =============================================================================
+// Ingestion Response Schemas
+// =============================================================================
+
+/**
+ * Event processing result.
+ */
+export const EventResultSchema = z.object({
+  /** Server-generated event ID */
+  id: z.string().uuid(),
+
+  /** Original message ID if provided */
+  messageId: z.string().uuid().optional(),
+
+  /** Event type */
+  type: z.enum(['track', 'identify', 'page', 'screen', 'group', 'alias']),
+
+  /** Processing status */
+  status: z.enum(['accepted', 'rejected']),
+
+  /** Error message if rejected */
+  error: z.string().optional(),
+});
+
+/**
+ * Successful ingestion response schema.
+ */
+export const IngestionSuccessResponseSchema = z.object({
+  /** Whether the request was successful */
+  success: z.literal(true),
+
+  /** Number of events accepted */
+  accepted: z.number().int().nonnegative(),
+
+  /** Number of events rejected */
+  rejected: z.number().int().nonnegative(),
+
+  /** Per-event results */
+  results: z.array(EventResultSchema),
+
+  /** Server timestamp when events were received */
+  receivedAt: z.string().datetime(),
+});
+
+/**
+ * Error response schema.
+ */
+export const IngestionErrorResponseSchema = z.object({
+  /** Whether the request was successful */
+  success: z.literal(false),
+
+  /** Error code */
+  code: z.string(),
+
+  /** Error message */
+  error: z.string(),
+
+  /** Field-level validation errors */
+  fieldErrors: z
+    .array(
+      z.object({
+        path: z.array(z.union([z.string(), z.number()])),
+        message: z.string(),
+      }),
+    )
+    .optional(),
+});
+
+/**
+ * Combined response schema.
+ */
+export const IngestionResponseSchema = z.union([
+  IngestionSuccessResponseSchema,
+  IngestionErrorResponseSchema,
+]);
+
+// =============================================================================
+// Type Exports
+// =============================================================================
+
+export type PropertyValue = z.infer<typeof PropertyValueSchema>;
+export type PropertyObject = z.infer<typeof PropertyObjectSchema>;
+export type EmitterContext = z.infer<typeof EmitterContextSchema>;
+export type TrackEvent = z.infer<typeof TrackEventSchema>;
+export type IdentifyEvent = z.infer<typeof IdentifyEventSchema>;
+export type PageEvent = z.infer<typeof PageEventSchema>;
+export type ScreenEvent = z.infer<typeof ScreenEventSchema>;
+export type GroupEvent = z.infer<typeof GroupEventSchema>;
+export type AliasEvent = z.infer<typeof AliasEventSchema>;
+export type EventPayload = z.infer<typeof EventPayloadSchema>;
+export type SingleEventRequest = z.infer<typeof SingleEventRequestSchema>;
+export type BatchEventRequest = z.infer<typeof BatchEventRequestSchema>;
+export type IngestionRequest = z.infer<typeof IngestionRequestSchema>;
+export type EventResult = z.infer<typeof EventResultSchema>;
+export type IngestionSuccessResponse = z.infer<typeof IngestionSuccessResponseSchema>;
+export type IngestionErrorResponse = z.infer<typeof IngestionErrorResponseSchema>;
+export type IngestionResponse = z.infer<typeof IngestionResponseSchema>;