@od-oneapp/analytics 2026.1.1301

package/src/shared/emitters/emitter-types.ts

@@ -0,0 +1,974 @@
+/**
+ * @fileoverview Type Definitions for Analytics Emitters
+ *
+ * Comprehensive type definitions for analytics emitters based on the Segment.io
+ * specification. These types ensure type-safe event tracking across all analytics
+ * providers.
+ *
+ * **Core Types**:
+ * - `EmitterContext`: Contextual information about the environment
+ * - `EmitterOptions`: Options that can be passed to any analytics method
+ * - `EmitterPayload`: Union type for all event payloads
+ * - `EmitterConfig`: Configuration for analytics emitters
+ * - `AnalyticsEmitter`: Interface that all analytics providers should implement
+ *
+ * **Payload Types**:
+ * - `EmitterIdentifyPayload`: Identify user events
+ * - `EmitterTrackPayload`: Custom event tracking
+ * - `EmitterPagePayload`: Page view tracking
+ * - `EmitterScreenPayload`: Screen view tracking (mobile)
+ * - `EmitterGroupPayload`: Group association events
+ * - `EmitterAliasPayload`: User ID aliasing events
+ *
+ * **Reference**: https://segment.com/docs/connections/spec/common/
+ *
+ * @module @od-oneapp/analytics/shared/emitters/emitter-types
+ */
+
+import type { GroupTraits, Properties, PropertyValue, UserTraits } from '../types/base-types';
+
+/**
+ * Common context object that provides additional information about the environment.
+ *
+ * @remarks
+ * Context is automatically collected and attached to all events. You can also
+ * manually provide context when creating events. This ensures consistent
+ * metadata across all analytics events.
+ *
+ * @example
+ * ```typescript
+ * const context: EmitterContext = {
+ *   app: { name: 'MyApp', version: '1.0.0' },
+ *   page: { path: '/dashboard', title: 'Dashboard' },
+ *   campaign: { source: 'google', medium: 'cpc' }
+ * };
+ * ```
+ */
+export interface EmitterContext {
+  /**
+   * Whether a user is active (usually used to flag an identify call to just update traits).
+   */
+  active?: boolean;
+
+  /**
+   * Dictionary of information about the current application.
+   */
+  app?: {
+    /** Application name */
+    name?: string;
+    /** Application version */
+    version?: string;
+    /** Build number or identifier */
+    build?: string;
+    /** Application namespace */
+    namespace?: string;
+  };
+
+  /**
+   * Dictionary of information about the campaign that resulted in the API call.
+   * Includes UTM parameters and other campaign metadata.
+   */
+  campaign?: {
+    /** Campaign name */
+    name?: string;
+    /** Campaign source (e.g., 'google', 'facebook') */
+    source?: string;
+    /** Campaign medium (e.g., 'cpc', 'email') */
+    medium?: string;
+    /** Campaign term (for paid search) */
+    term?: string;
+    /** Campaign content (for A/B testing) */
+    content?: string;
+    /** Any other custom UTM parameters */
+    [key: string]: string | undefined;
+  };
+
+  /**
+   * Dictionary of information about the device.
+   */
+  device?: {
+    /** Device identifier */
+    id?: string;
+    /** Advertising ID (mobile) */
+    advertisingId?: string;
+    /** Whether ad tracking is enabled */
+    adTrackingEnabled?: boolean;
+    /** Device manufacturer */
+    manufacturer?: string;
+    /** Device model */
+    model?: string;
+    /** Device name */
+    name?: string;
+    /** Device type (e.g., 'mobile', 'desktop') */
+    type?: string;
+    /** Device version */
+    version?: string;
+    /** Push notification token */
+    token?: string;
+  };
+
+  /**
+   * Current user's IP address.
+   */
+  ip?: string;
+
+  /**
+   * Dictionary of information about the library making the requests.
+   */
+  library?: {
+    /** Library name */
+    name: string;
+    /** Library version */
+    version: string;
+  };
+
+  /**
+   * Locale string for the current user (e.g., 'en-US').
+   */
+  locale?: string;
+
+  /**
+   * Dictionary of information about the current network connection.
+   */
+  network?: {
+    /** Whether Bluetooth is enabled */
+    bluetooth?: boolean;
+    /** Network carrier name */
+    carrier?: string;
+    /** Whether using cellular connection */
+    cellular?: boolean;
+    /** Whether using WiFi connection */
+    wifi?: boolean;
+  };
+
+  /**
+   * Dictionary of information about the operating system.
+   */
+  os?: {
+    /** OS name (e.g., 'iOS', 'Android', 'Windows') */
+    name?: string;
+    /** OS version */
+    version?: string;
+  };
+
+  /**
+   * Dictionary of information about the current page in the browser.
+   */
+  page?: {
+    /** Page path */
+    path?: string;
+    /** Referrer URL */
+    referrer?: string;
+    /** Query string */
+    search?: string;
+    /** Page title */
+    title?: string;
+    /** Full page URL */
+    url?: string;
+  };
+
+  /**
+   * Dictionary of information about the way the user was referred.
+   */
+  referrer?: {
+    /** Referrer ID */
+    id?: string;
+    /** Referrer type */
+    type?: string;
+    /** Referrer name */
+    name?: string;
+    /** Referrer URL */
+    url?: string;
+    /** Referrer link */
+    link?: string;
+  };
+
+  /**
+   * Dictionary of information about the device's screen.
+   */
+  screen?: {
+    /** Screen density (DPI) */
+    density?: number;
+    /** Screen height in pixels */
+    height?: number;
+    /** Screen width in pixels */
+    width?: number;
+  };
+
+  /**
+   * Timezone as tzdata string (e.g., 'America/New_York').
+   */
+  timezone?: string;
+
+  /**
+   * Group/Account ID (useful in B2B use cases).
+   */
+  groupId?: string;
+
+  /**
+   * Dictionary of traits of the current user.
+   */
+  traits?: UserTraits;
+
+  /**
+   * User agent of the device making the request.
+   */
+  userAgent?: string;
+
+  /**
+   * User agent data from Client Hints API.
+   */
+  userAgentData?: {
+    /** Browser brands */
+    brands?: {
+      brand: string;
+      version: string;
+    }[];
+    /** Whether device is mobile */
+    mobile?: boolean;
+    /** Platform name */
+    platform?: string;
+    /** Architecture bitness */
+    bitness?: string;
+    /** Device model */
+    model?: string;
+    /** Platform version */
+    platformVersion?: string;
+    /** Full user agent version */
+    uaFullVersion?: string;
+    /** Full version list */
+    fullVersionList?: {
+      brand: string;
+      version: string;
+    }[];
+    /** Whether running in WOW64 mode */
+    wow64?: boolean;
+  };
+
+  /**
+   * Where the request originated from: 'server', 'browser', or 'mobile'.
+   */
+  channel?: string;
+
+  /**
+   * Location context (less commonly used).
+   */
+  location?: {
+    /** City name */
+    city?: string;
+    /** Country code */
+    country?: string;
+    /** Latitude */
+    latitude?: number;
+    /** Longitude */
+    longitude?: number;
+    /** Region/state */
+    region?: string;
+    /** Movement speed */
+    speed?: number;
+  };
+
+  /**
+   * Allow additional custom properties.
+   */
+  [key: string]: unknown;
+}
+
+/**
+ * Integration configuration value.
+ *
+ * @remarks
+ * Can be a boolean to enable/disable, or an object with specific settings
+ * for the integration.
+ */
+export type IntegrationConfig = boolean | Record<string, PropertyValue | PropertyValue[]>;
+
+/**
+ * Options that can be passed to any analytics method.
+ *
+ * @remarks
+ * These options allow you to customize event behavior, including context,
+ * integrations, timestamps, and callbacks.
+ *
+ * @example
+ * ```typescript
+ * const options: EmitterOptions = {
+ *   anonymousId: 'anon-123',
+ *   context: { page: { path: '/dashboard' } },
+ *   integrations: { All: true, Mixpanel: false },
+ *   timestamp: new Date()
+ * };
+ * ```
+ */
+export interface EmitterOptions {
+  /**
+   * Anonymous ID if user is not identified.
+   */
+  anonymousId?: string;
+  /**
+   * Callback function (client-side only).
+   * Called after the event is sent.
+   */
+  callback?: (...args: unknown[]) => void;
+  /**
+   * Context information to attach to the event.
+   */
+  context?: EmitterContext;
+  /**
+   * Integration specific options.
+   * Controls which destinations receive the event.
+   */
+  integrations?: Record<string, IntegrationConfig>;
+  /**
+   * Timestamp when the event occurred.
+   * Defaults to current time if not provided.
+   */
+  timestamp?: Date | string;
+}
+
+/**
+ * Integrations configuration (destination control).
+ *
+ * @remarks
+ * Controls which analytics destinations receive events. Use `All: false` to
+ * disable all destinations by default, then enable specific ones.
+ *
+ * @example
+ * ```typescript
+ * const integrations: EmitterIntegrations = {
+ *   All: false,
+ *   Mixpanel: true,
+ *   GoogleAnalytics: { customOption: 'value' }
+ * };
+ * ```
+ */
+export interface EmitterIntegrations {
+  /**
+   * Individual destination settings.
+   */
+  [destination: string]: IntegrationConfig | undefined;
+  /**
+   * Special key that applies when no specific destination key is found.
+   */
+  All?: boolean;
+}
+
+/**
+ * Base payload that all events extend from (Common Fields).
+ *
+ * @remarks
+ * All analytics events share these common fields. Specific event types
+ * extend this interface with their own fields.
+ */
+export interface EmitterBasePayload {
+  /**
+   * Type of message, corresponding to the API method.
+   */
+  type: 'identify' | 'track' | 'page' | 'screen' | 'group' | 'alias';
+
+  /**
+   * Anonymous ID if user is not identified.
+   */
+  anonymousId?: string;
+  /**
+   * User ID (at least one of userId or anonymousId required).
+   */
+  userId?: string;
+
+  /**
+   * Original timestamp when the event occurred (before any processing).
+   */
+  originalTimestamp?: Date | string;
+  /**
+   * Timestamp when the event was received by the server.
+   */
+  receivedAt?: Date | string;
+  /**
+   * Timestamp when the event was sent to destinations.
+   */
+  sentAt?: Date | string;
+  /**
+   * Timestamp when the event occurred.
+   */
+  timestamp?: Date | string;
+
+  /**
+   * Context and control fields.
+   */
+  context?: EmitterContext;
+  /**
+   * Integration-specific options.
+   */
+  integrations?: EmitterIntegrations;
+
+  /**
+   * System fields (set by Segment or analytics providers).
+   */
+  messageId?: string;
+  /**
+   * Protocol version.
+   */
+  version?: number;
+}
+
+/**
+ * Payload for identify events.
+ *
+ * @remarks
+ * Ties a user to their actions and records traits about them.
+ *
+ * @example
+ * ```typescript
+ * const payload: EmitterIdentifyPayload = {
+ *   type: 'identify',
+ *   userId: 'user-123',
+ *   traits: { email: 'user@example.com', name: 'John Doe' }
+ * };
+ * ```
+ */
+export interface EmitterIdentifyPayload extends EmitterBasePayload {
+  /**
+   * Free-form dictionary of traits about the user.
+   */
+  traits?: UserTraits;
+  type: 'identify';
+  userId: string;
+}
+
+/**
+ * Payload for track events.
+ *
+ * @remarks
+ * Records any actions your users perform, along with properties that describe the action.
+ *
+ * @example
+ * ```typescript
+ * const payload: EmitterTrackPayload = {
+ *   type: 'track',
+ *   event: 'Button Clicked',
+ *   properties: { buttonName: 'Sign Up', location: 'header' }
+ * };
+ * ```
+ */
+export interface EmitterTrackPayload extends EmitterBasePayload {
+  /**
+   * Name of the action that a user has performed.
+   */
+  event: string;
+  /**
+   * Free-form dictionary of properties of the event.
+   */
+  properties?: Properties;
+  type: 'track';
+}
+
+/**
+ * Payload for page events.
+ *
+ * @remarks
+ * Records whenever a user views a page of your website.
+ *
+ * @example
+ * ```typescript
+ * const payload: EmitterPagePayload = {
+ *   type: 'page',
+ *   name: 'Dashboard',
+ *   properties: { path: '/dashboard', title: 'Dashboard' }
+ * };
+ * ```
+ */
+export interface EmitterPagePayload extends EmitterBasePayload {
+  /**
+   * Category of the page (optional).
+   */
+  category?: string;
+  /**
+   * Name of the page.
+   */
+  name?: string;
+  /**
+   * Free-form dictionary of properties of the page.
+   */
+  properties?: Properties;
+  type: 'page';
+}
+
+/**
+ * Payload for screen events.
+ *
+ * @remarks
+ * Records whenever a user views a screen in your mobile app.
+ *
+ * @example
+ * ```typescript
+ * const payload: EmitterScreenPayload = {
+ *   type: 'screen',
+ *   name: 'Home',
+ *   properties: { screenClass: 'HomeScreen' }
+ * };
+ * ```
+ */
+export interface EmitterScreenPayload extends EmitterBasePayload {
+  /**
+   * Name of the screen.
+   */
+  name?: string;
+  /**
+   * Free-form dictionary of properties of the screen.
+   */
+  properties?: Properties;
+  type: 'screen';
+}
+
+/**
+ * Payload for group events.
+ *
+ * @remarks
+ * Associates an identified user with a group.
+ *
+ * @example
+ * ```typescript
+ * const payload: EmitterGroupPayload = {
+ *   type: 'group',
+ *   groupId: 'org-456',
+ *   traits: { name: 'Acme Corp', industry: 'Technology' }
+ * };
+ * ```
+ */
+export interface EmitterGroupPayload extends EmitterBasePayload {
+  /**
+   * Unique identifier for the group.
+   */
+  groupId: string;
+  /**
+   * Free-form dictionary of traits about the group.
+   */
+  traits?: GroupTraits;
+  type: 'group';
+}
+
+/**
+ * Payload for alias events.
+ *
+ * @remarks
+ * Associates one identity with another. Useful when a user signs up or logs in.
+ *
+ * @example
+ * ```typescript
+ * const payload: EmitterAliasPayload = {
+ *   type: 'alias',
+ *   userId: 'user-123',
+ *   previousId: 'anon-456'
+ * };
+ * ```
+ */
+export interface EmitterAliasPayload extends EmitterBasePayload {
+  /**
+   * The previous ID of the user (usually the anonymousId).
+   */
+  previousId: string;
+  type: 'alias';
+  userId: string;
+}
+
+/**
+ * Union type for all possible payloads.
+ *
+ * @remarks
+ * Use this type when you need to handle any analytics event payload.
+ */
+export type EmitterPayload =
+  | EmitterIdentifyPayload
+  | EmitterTrackPayload
+  | EmitterPagePayload
+  | EmitterScreenPayload
+  | EmitterGroupPayload
+  | EmitterAliasPayload;
+
+/**
+ * Common traits that are recognized by many analytics destinations.
+ *
+ * @remarks
+ * These traits are commonly used across analytics platforms. You can also
+ * include custom traits as needed.
+ *
+ * @example
+ * ```typescript
+ * const traits: EmitterUserTraits = {
+ *   email: 'user@example.com',
+ *   name: 'John Doe',
+ *   company: { name: 'Acme Corp', industry: 'Technology' }
+ * };
+ * ```
+ */
+export interface EmitterUserTraits {
+  /** User's email address */
+  email?: string;
+  /** User's first name */
+  firstName?: string;
+  /** User's last name */
+  lastName?: string;
+  /** User's full name */
+  name?: string;
+  /** User's phone number */
+  phone?: string;
+  /** User's username */
+  username?: string;
+
+  /** User's age */
+  age?: number;
+  /** User's birthday */
+  birthday?: Date | string;
+  /** User's gender */
+  gender?: string;
+
+  /** User's address */
+  address?: {
+    /** Street address */
+    street?: string;
+    /** City */
+    city?: string;
+    /** State or province */
+    state?: string;
+    /** Postal or ZIP code */
+    postalCode?: string;
+    /** Country */
+    country?: string;
+  };
+
+  /** User's company information */
+  company?: {
+    /** Company name */
+    name?: string;
+    /** Company ID */
+    id?: string;
+    /** Industry */
+    industry?: string;
+    /** Number of employees */
+    employee_count?: number;
+    /** Company plan */
+    plan?: string;
+  };
+
+  /** User's avatar URL */
+  avatar?: string;
+  /** When the user was created */
+  createdAt?: Date | string;
+  /** User description */
+  description?: string;
+  /** User ID */
+  id?: string;
+  /** User's website */
+  website?: string;
+
+  /**
+   * Custom traits (strongly typed).
+   * Can include any additional properties as needed.
+   */
+  [key: string]:
+    | PropertyValue
+    | PropertyValue[]
+    | EmitterUserTraits['address']
+    | EmitterUserTraits['company']
+    | undefined;
+}
+
+/**
+ * Product information in an ecommerce event.
+ *
+ * @remarks
+ * Used in e-commerce tracking events like "Product Viewed", "Product Added",
+ * "Order Completed", etc.
+ *
+ * @example
+ * ```typescript
+ * const product: EmitterProduct = {
+ *   id: 'prod-123',
+ *   name: 'Widget',
+ *   price: 29.99,
+ *   quantity: 2,
+ *   category: 'Electronics',
+ *   brand: 'Acme'
+ * };
+ * ```
+ */
+export interface EmitterProduct {
+  /** Product ID */
+  id?: string;
+  /** Product name */
+  name?: string;
+  /** Product price */
+  price?: number;
+  /** Product quantity */
+  quantity?: number;
+  /** Product category */
+  category?: string;
+  /** Product brand */
+  brand?: string;
+  /** Product variant */
+  variant?: string;
+  /**
+   * Custom product properties.
+   * Can include any additional properties as needed.
+   */
+  [key: string]: PropertyValue | PropertyValue[] | undefined;
+}
+
+/**
+ * Common properties for track events.
+ *
+ * @remarks
+ * These properties are commonly used across analytics platforms for
+ * e-commerce, content, and search tracking.
+ *
+ * @example
+ * ```typescript
+ * const properties: EmitterEventProperties = {
+ *   revenue: 29.99,
+ *   currency: 'USD',
+ *   products: [{ id: 'prod-123', name: 'Widget', price: 29.99 }]
+ * };
+ * ```
+ */
+export interface EmitterEventProperties {
+  /** Currency code (e.g., 'USD', 'EUR') */
+  currency?: string;
+  /** Revenue amount */
+  revenue?: number;
+  /** Event value */
+  value?: number;
+
+  /** Array of products (for e-commerce events) */
+  products?: EmitterProduct[];
+
+  /** Event category */
+  category?: string;
+  /** Event description */
+  description?: string;
+  /** Event title */
+  title?: string;
+
+  /** Search query */
+  query?: string;
+
+  /** Recipient (for sharing events) */
+  recipient?: string;
+  /** Share method (for sharing events) */
+  share_via?: string;
+
+  /**
+   * Custom properties (strongly typed).
+   * Can include any additional properties as needed.
+   */
+  [key: string]: PropertyValue | PropertyValue[] | EmitterProduct[] | undefined;
+}
+
+/**
+ * Common group traits.
+ *
+ * @remarks
+ * These traits are commonly used when associating users with groups or organizations.
+ *
+ * @example
+ * ```typescript
+ * const traits: EmitterGroupTraits = {
+ *   name: 'Acme Corp',
+ *   industry: 'Technology',
+ *   employees: 100,
+ *   plan: 'enterprise'
+ * };
+ * ```
+ */
+export interface EmitterGroupTraits {
+  /** Group avatar URL */
+  avatar?: string;
+  /** When the group was created */
+  createdAt?: Date | string;
+  /** Group description */
+  description?: string;
+  /** Number of employees */
+  employees?: number;
+  /** Industry */
+  industry?: string;
+  /** Group name */
+  name?: string;
+  /** Group plan */
+  plan?: string;
+  /** Group website */
+  website?: string;
+
+  /**
+   * Custom traits (strongly typed).
+   * Can include any additional properties as needed.
+   */
+  [key: string]: PropertyValue | PropertyValue[] | undefined;
+}
+
+/**
+ * Emitter interface that all analytics providers should implement.
+ *
+ * @remarks
+ * This interface defines the contract for analytics providers. All providers
+ * must implement these methods to ensure consistent behavior across the
+ * analytics system.
+ *
+ * @example
+ * ```typescript
+ * class MyProvider implements AnalyticsEmitter {
+ *   async track(event: string, properties?: Properties, options?: EmitterOptions) {
+ *     // Send event to analytics service
+ *   }
+ *   // ... implement other methods
+ * }
+ * ```
+ */
+export interface AnalyticsEmitter {
+  /**
+   * Alias one identity with another.
+   *
+   * @param userId - The new user ID
+   * @param previousId - The previous user ID (usually anonymousId)
+   * @param options - Optional event options
+   * @param callback - Optional callback (client-side only)
+   */
+  alias(
+    userId: string,
+    previousId?: string,
+    options?: EmitterOptions,
+    callback?: (...args: unknown[]) => void,
+  ): void | Promise<void>;
+  /**
+   * Associate an identified user with a group.
+   *
+   * @param groupId - Unique identifier for the group
+   * @param traits - Free-form dictionary of traits about the group
+   * @param options - Optional event options
+   * @param callback - Optional callback (client-side only)
+   */
+  group(
+    groupId: string,
+    traits?: GroupTraits,
+    options?: EmitterOptions,
+    callback?: (...args: unknown[]) => void,
+  ): void | Promise<void>;
+  /**
+   * Identify a user and record traits about them.
+   *
+   * @param userId - Unique identifier for the user
+   * @param traits - Free-form dictionary of traits about the user
+   * @param options - Optional event options
+   * @param callback - Optional callback (client-side only)
+   */
+  identify(
+    userId: string,
+    traits?: UserTraits,
+    options?: EmitterOptions,
+    callback?: (...args: unknown[]) => void,
+  ): void | Promise<void>;
+  /**
+   * Record a page view.
+   *
+   * @param category - Category of the page (optional)
+   * @param name - Name of the page (optional)
+   * @param properties - Free-form dictionary of properties of the page
+   * @param options - Optional event options
+   * @param callback - Optional callback (client-side only)
+   */
+  page(
+    category?: string,
+    name?: string,
+    properties?: Properties,
+    options?: EmitterOptions,
+    callback?: (...args: unknown[]) => void,
+  ): void | Promise<void>;
+  /**
+   * Record a screen view (mobile apps).
+   *
+   * @param name - Name of the screen
+   * @param properties - Free-form dictionary of properties of the screen
+   * @param options - Optional event options
+   * @param callback - Optional callback (client-side only)
+   */
+  screen(
+    name?: string,
+    properties?: Properties,
+    options?: EmitterOptions,
+    callback?: (...args: unknown[]) => void,
+  ): void | Promise<void>;
+  /**
+   * Record an action a user performed.
+   *
+   * @param event - Name of the action
+   * @param properties - Free-form dictionary of properties of the event
+   * @param options - Optional event options
+   * @param callback - Optional callback (client-side only)
+   */
+  track(
+    event: string,
+    properties?: Properties,
+    options?: EmitterOptions,
+    callback?: (...args: unknown[]) => void,
+  ): void | Promise<void>;
+}
+
+/**
+ * Configuration for analytics emitters.
+ *
+ * @remarks
+ * This configuration object allows you to customize emitter behavior,
+ * including batching, debugging, and default context.
+ *
+ * @example
+ * ```typescript
+ * const config: EmitterConfig = {
+ *   apiKey: 'your-api-key',
+ *   batching: true,
+ *   batchSize: 20,
+ *   flushInterval: 5000,
+ *   debug: true,
+ *   defaultContext: { app: { name: 'MyApp' } }
+ * };
+ * ```
+ */
+export interface EmitterConfig {
+  /**
+   * API key or write key for the analytics service.
+   */
+  apiKey?: string;
+  /**
+   * Whether to batch events before sending.
+   */
+  batching?: boolean;
+  /**
+   * Maximum number of events to batch before flushing.
+   */
+  batchSize?: number;
+  /**
+   * Whether to enable debug logging.
+   */
+  debug?: boolean;
+  /**
+   * Default context to include with all events.
+   */
+  defaultContext?: Partial<EmitterContext>;
+  /**
+   * Custom endpoint for sending events.
+   */
+  endpoint?: string;
+  /**
+   * Time to wait before flushing batch (milliseconds).
+   */
+  flushInterval?: number;
+  /**
+   * Default integrations settings.
+   */
+  integrations?: Record<string, IntegrationConfig>;
+  /**
+   * Whether to track clicks automatically.
+   */
+  trackClicks?: boolean;
+  /**
+   * Whether to track page views automatically.
+   */
+  trackPages?: boolean;
+}