@od-oneapp/analytics 2026.1.1301

package/src/shared/emitters/emitters.ts

@@ -0,0 +1,292 @@
+/**
+ * @fileoverview Core analytics emitter functions following Segment.io specification
+ *
+ * This module provides type-safe emitter functions that return event payloads following
+ * the Segment.io specification. These payloads can be passed to `analytics.emit()` or
+ * `analytics.track()` for tracking.
+ *
+ * **Emitter Functions**:
+ * - `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
+ *
+ * **Benefits**:
+ * - Type-safe event tracking
+ * - Consistent with Segment.io spec
+ * - Can be composed and batched
+ * - Works with all analytics providers
+ *
+ * **Reference**: https://segment.com/docs/connections/spec/
+ *
+ * @module @od-oneapp/analytics/shared/emitters
+ */
+
+import type {
+  EmitterAliasPayload,
+  EmitterGroupPayload,
+  EmitterIdentifyPayload,
+  EmitterOptions,
+  EmitterPagePayload,
+  EmitterScreenPayload,
+  EmitterTrackPayload,
+} from './emitter-types';
+import type { GroupTraits, PageProperties, PropertyObject, UserTraits } from '../types/types';
+
+/**
+ * Identify - who is the customer?
+ *
+ * Ties a user to their actions and records traits about them. This is the core
+ * method for identifying users in your analytics system.
+ *
+ * **When to call**:
+ * - After a user first registers
+ * - After a user logs in
+ * - When a user updates their info
+ *
+ * **Reference**: https://segment.com/docs/connections/spec/identify/
+ *
+ * @param {string} userId - Unique identifier for the user in your database (required unless anonymousId is set)
+ * @param {UserTraits} [traits] - Free-form dictionary of traits about the user, like email or name
+ * @param {EmitterOptions} [options] - Optional fields like timestamp, anonymousId, context, integrations
+ * @returns {EmitterIdentifyPayload} Identify payload ready to emit
+ *
+ * @example
+ * ```typescript
+ * await analytics.emit(identify('user-123', {
+ *   email: 'user@example.com',
+ *   name: 'John Doe'
+ * }));
+ * ```
+ */
+export function identify(
+  userId: string,
+  traits?: UserTraits,
+  options?: EmitterOptions,
+): EmitterIdentifyPayload {
+  const payload: EmitterIdentifyPayload = {
+    type: 'identify',
+    userId,
+    ...(traits && { traits }),
+    ...(options?.timestamp && { timestamp: options.timestamp }),
+    ...(options?.context && { context: options.context }),
+    ...(options?.anonymousId && { anonymousId: options.anonymousId }),
+    ...(options?.integrations && { integrations: options.integrations }),
+  };
+
+  return payload;
+}
+
+/**
+ * Track - what are they doing?
+ *
+ * Records any actions your users perform, along with properties that describe the action.
+ * This is the most common method for tracking user behavior.
+ *
+ * **Reference**: https://segment.com/docs/connections/spec/track/
+ *
+ * @param {string} event - Name of the action that a user has performed (required)
+ * @param {PropertyObject} [properties] - Free-form dictionary of properties of the event, like revenue
+ * @param {EmitterOptions} [options] - Optional fields like timestamp, anonymousId, context, integrations
+ * @returns {EmitterTrackPayload} Track payload ready to emit
+ *
+ * @example
+ * ```typescript
+ * await analytics.emit(track('Button Clicked', {
+ *   buttonName: 'Sign Up',
+ *   location: 'header'
+ * }));
+ * ```
+ */
+export function track(
+  event: string,
+  properties?: PropertyObject,
+  options?: EmitterOptions,
+): EmitterTrackPayload {
+  const payload: EmitterTrackPayload = {
+    type: 'track',
+    event,
+    ...(properties && { properties }),
+    ...(options?.timestamp && { timestamp: options.timestamp }),
+    ...(options?.context && { context: options.context }),
+    ...(options?.anonymousId && { anonymousId: options.anonymousId }),
+    ...(options?.integrations && { integrations: options.integrations }),
+    ...(options?.anonymousId && { anonymousId: options.anonymousId }),
+  };
+
+  // userId should be passed through the main function params or via options
+
+  return payload;
+}
+
+/**
+ * Page - what web page are they on?
+ *
+ * Records page views on your website, along with optional properties about the page.
+ * Automatically merges category into properties if provided.
+ *
+ * **Reference**: https://segment.com/docs/connections/spec/page/
+ *
+ * @param {string} [category] - Category of the page (optional)
+ * @param {string} [name] - Name of the page (optional)
+ * @param {PageProperties} [properties] - Free-form dictionary of properties of the page, like url and referrer
+ * @param {EmitterOptions} [options] - Optional fields like timestamp, anonymousId, context, integrations
+ * @returns {EmitterPagePayload} Page payload ready to emit
+ *
+ * @example
+ * ```typescript
+ * await analytics.emit(page('Home', 'Landing', {
+ *   url: 'https://example.com',
+ *   referrer: 'https://google.com'
+ * }));
+ * ```
+ */
+export function page(
+  category?: string,
+  name?: string,
+  properties?: PageProperties,
+  options?: EmitterOptions,
+): EmitterPagePayload {
+  // Merge category into properties if provided
+  const mergedProperties = {
+    ...(properties ?? {}),
+    ...(category && { category }),
+  };
+
+  const payload: EmitterPagePayload = {
+    type: 'page',
+    ...(name && { name }),
+    ...(Object.keys(mergedProperties).length > 0 && { properties: mergedProperties }),
+    ...(options?.timestamp && { timestamp: options.timestamp }),
+    ...(options?.context && { context: options.context }),
+    ...(options?.anonymousId && { anonymousId: options.anonymousId }),
+    ...(options?.integrations && { integrations: options.integrations }),
+  };
+
+  // userId should be passed through the main function params or via options
+
+  return payload;
+}
+
+/**
+ * Screen - what app screen are they on?
+ *
+ * The mobile equivalent of page, records screen views in your mobile app.
+ * Use this for React Native, iOS, and Android applications.
+ *
+ * **Reference**: https://segment.com/docs/connections/spec/screen/
+ *
+ * @param {string} [name] - Name of the screen (optional)
+ * @param {PropertyObject} [properties] - Free-form dictionary of properties of the screen
+ * @param {EmitterOptions} [options] - Optional fields like timestamp, anonymousId, context, integrations
+ * @returns {EmitterScreenPayload} Screen payload ready to emit
+ *
+ * @example
+ * ```typescript
+ * await analytics.emit(screen('Home Screen', {
+ *   screenType: 'main',
+ *   userId: 'user-123'
+ * }));
+ * ```
+ */
+export function screen(
+  name?: string,
+  properties?: PropertyObject,
+  options?: EmitterOptions,
+): EmitterScreenPayload {
+  const payload: EmitterScreenPayload = {
+    type: 'screen',
+    ...(name && { name }),
+    ...(properties && { properties }),
+    ...(options?.timestamp && { timestamp: options.timestamp }),
+    ...(options?.context && { context: options.context }),
+    ...(options?.anonymousId && { anonymousId: options.anonymousId }),
+    ...(options?.integrations && { integrations: options.integrations }),
+  };
+
+  // userId should be passed through the main function params or via options
+
+  return payload;
+}
+
+/**
+ * Group - what account or organization are they part of?
+ *
+ * Associates an individual user with a group—a company, organization, account, project, or team.
+ * Useful for B2B applications where users belong to organizations.
+ *
+ * **Reference**: https://segment.com/docs/connections/spec/group/
+ *
+ * @param {string} groupId - Unique identifier for the group in your database (required)
+ * @param {GroupTraits} [traits] - Free-form dictionary of traits of the group, like name or industry
+ * @param {EmitterOptions} [options] - Optional fields like timestamp, anonymousId, context, integrations
+ * @returns {EmitterGroupPayload} Group payload ready to emit
+ *
+ * @example
+ * ```typescript
+ * await analytics.emit(group('org-456', {
+ *   name: 'Acme Corp',
+ *   industry: 'Technology',
+ *   plan: 'enterprise'
+ * }));
+ * ```
+ */
+export function group(
+  groupId: string,
+  traits?: GroupTraits,
+  options?: EmitterOptions,
+): EmitterGroupPayload {
+  const payload: EmitterGroupPayload = {
+    type: 'group',
+    groupId,
+    ...(traits && { traits }),
+    ...(options?.timestamp && { timestamp: options.timestamp }),
+    ...(options?.context && { context: options.context }),
+    ...(options?.anonymousId && { anonymousId: options.anonymousId }),
+    ...(options?.integrations && { integrations: options.integrations }),
+  };
+
+  // userId should be passed through the main function params or via options
+
+  return payload;
+}
+
+/**
+ * Alias - what was their past identity?
+ *
+ * Merges two user identities, effectively connecting two sets of user data in one profile.
+ * This is an advanced method that should only be used when required for downstream
+ * destination compatibility (e.g., when a user signs up after browsing anonymously).
+ *
+ * **Reference**: https://segment.com/docs/connections/spec/alias/
+ *
+ * @param {string} userId - The user's new identity, or an existing identity to merge with previousId (required)
+ * @param {string} previousId - The existing ID you've referred to the user by (required)
+ * @param {EmitterOptions} [options] - Optional fields like timestamp, context, integrations
+ * @returns {EmitterAliasPayload} Alias payload ready to emit
+ *
+ * @example
+ * ```typescript
+ * // When anonymous user signs up
+ * await analytics.emit(alias('user-123', 'anonymous-456'));
+ * ```
+ */
+export function alias(
+  userId: string,
+  previousId: string,
+  options?: EmitterOptions,
+): EmitterAliasPayload {
+  const payload: EmitterAliasPayload = {
+    type: 'alias',
+    previousId,
+    userId,
+    ...(options?.timestamp && { timestamp: options.timestamp }),
+    ...(options?.context && { context: options.context }),
+    ...(options?.anonymousId && { anonymousId: options.anonymousId }),
+    ...(options?.integrations && { integrations: options.integrations }),
+  };
+
+  return payload;
+}

package/src/shared/emitters/helpers.ts

@@ -0,0 +1,419 @@
+/**
+ * @fileoverview Helper Functions for Analytics Emitters
+ *
+ * These utilities make it easier to use the emitter-first approach for analytics.
+ * Provides builders, batch processing, session management, and convenience
+ * functions for common tracking patterns.
+ *
+ * **Builders**:
+ * - `ContextBuilder`: Build consistent context across events
+ * - `PayloadBuilder`: Chain emitter creation with shared options
+ * - `EventBatch`: Batch related events with shared context
+ *
+ * **Session Management**:
+ * - `createUserSession()`: Create a user session tracking flow
+ * - `createAnonymousSession()`: Create an anonymous user tracking flow
+ *
+ * **Convenience Functions**:
+ * - `withMetadata()`: Add consistent metadata to events
+ * - `withUTM()`: Add UTM parameters to events
+ * - Type guards: `isTrackPayload()`, `isIdentifyPayload()`, etc.
+ *
+ * @module @od-oneapp/analytics/shared/emitters/helpers
+ */
+
+import { alias, group, identify, page, track } from './emitters';
+
+import type {
+  EmitterAliasPayload,
+  EmitterContext,
+  EmitterGroupPayload,
+  EmitterIdentifyPayload,
+  EmitterOptions,
+  EmitterPagePayload,
+  EmitterPayload,
+  EmitterTrackPayload,
+} from './emitter-types';
+
+/**
+ * Builder for creating consistent context across analytics events.
+ *
+ * @remarks
+ * Use this builder to create a reusable context object that can be applied
+ * to multiple events. This ensures consistency and reduces repetition.
+ *
+ * @example
+ * ```typescript
+ * const context = new ContextBuilder()
+ *   .setUser('user-123', { plan: 'pro' })
+ *   .setOrganization('org-456')
+ *   .setPage({ path: '/dashboard', title: 'Dashboard' })
+ *   .build();
+ *
+ * await analytics.emit(track('Button Clicked', {}, { context }));
+ * ```
+ */
+export class ContextBuilder {
+  private context: EmitterContext = {};
+
+  constructor(initialContext?: Partial<EmitterContext>) {
+    if (initialContext) {
+      this.context = { ...initialContext };
+    }
+  }
+
+  setUser(_userId: string, traits?: Record<string, any>): this {
+    this.context.traits = { ...this.context.traits, ...traits };
+    return this;
+  }
+
+  setOrganization(groupId: string): this {
+    this.context.groupId = groupId;
+    return this;
+  }
+
+  setPage(pageInfo: { path?: string; url?: string; title?: string; referrer?: string }): this {
+    this.context.page = { ...this.context.page, ...pageInfo };
+    return this;
+  }
+
+  setCampaign(utmParams: Record<string, string>): this {
+    this.context.campaign = { ...this.context.campaign, ...utmParams };
+    return this;
+  }
+
+  setDevice(deviceInfo: Record<string, any>): this {
+    this.context.device = { ...this.context.device, ...deviceInfo };
+    return this;
+  }
+
+  build(): EmitterContext {
+    return { ...this.context };
+  }
+}
+
+/**
+ * Builder for chaining emitter creation with shared options.
+ *
+ * @remarks
+ * Use this builder to create multiple events with shared options like
+ * timestamp, anonymousId, or integrations. This is useful when tracking
+ * multiple related events in a single flow.
+ *
+ * @example
+ * ```typescript
+ * const builder = new PayloadBuilder(context)
+ *   .withTimestamp(new Date())
+ *   .withAnonymousId('anon-123');
+ *
+ * await analytics.emit(builder.track('Event 1', {}));
+ * await analytics.emit(builder.track('Event 2', {}));
+ * ```
+ */
+export class PayloadBuilder {
+  private options: EmitterOptions = {};
+
+  constructor(context?: EmitterContext) {
+    if (context) {
+      this.options.context = context;
+    }
+  }
+
+  withTimestamp(timestamp: Date | string): this {
+    this.options.timestamp = timestamp;
+    return this;
+  }
+
+  withAnonymousId(anonymousId: string): this {
+    this.options.anonymousId = anonymousId;
+    return this;
+  }
+
+  withIntegrations(integrations: Record<string, boolean | Record<string, any>>): this {
+    this.options.integrations = integrations;
+    return this;
+  }
+
+  track(event: string, properties?: Record<string, any>): EmitterTrackPayload {
+    return track(event, properties, this.options);
+  }
+
+  identify(userId: string, traits?: Record<string, any>): EmitterIdentifyPayload {
+    return identify(userId, traits, this.options);
+  }
+
+  page(name?: string, properties?: Record<string, any>): EmitterPagePayload {
+    return page(undefined, name, properties, this.options);
+  }
+
+  group(groupId: string, traits?: Record<string, any>): EmitterGroupPayload {
+    return group(groupId, traits, this.options);
+  }
+
+  alias(userId: string, previousId: string): EmitterAliasPayload {
+    return alias(userId, previousId, this.options);
+  }
+}
+
+/**
+ * Batch processor for related events with shared context.
+ *
+ * @remarks
+ * Use this class to collect multiple events and emit them together with
+ * a shared context. This is useful for tracking user flows or multi-step
+ * processes where events should be grouped together.
+ *
+ * @example
+ * ```typescript
+ * const batch = new EventBatch(context)
+ *   .addTrack('Step 1 Completed', { step: 1 })
+ *   .addTrack('Step 2 Completed', { step: 2 })
+ *   .addTrack('Flow Completed', { totalSteps: 2 });
+ *
+ * for (const event of batch.getEvents()) {
+ *   await analytics.emit(event);
+ * }
+ * ```
+ */
+export class EventBatch {
+  private events: EmitterPayload[] = [];
+  private sharedContext: EmitterContext;
+
+  constructor(context?: EmitterContext) {
+    this.sharedContext = context ?? {};
+  }
+
+  add(payload: EmitterPayload): this {
+    // Merge shared context with payload context
+    const enrichedPayload = {
+      ...payload,
+      context: { ...this.sharedContext, ...payload.context },
+    };
+    this.events.push(enrichedPayload);
+    return this;
+  }
+
+  addTrack(event: string, properties?: Record<string, any>): this {
+    return this.add(track(event, properties, { context: this.sharedContext }));
+  }
+
+  addIdentify(userId: string, traits?: Record<string, any>): this {
+    return this.add(identify(userId, traits, { context: this.sharedContext }));
+  }
+
+  addPage(name?: string, properties?: Record<string, any>): this {
+    return this.add(page(undefined, name, properties, { context: this.sharedContext }));
+  }
+
+  addGroup(groupId: string, traits?: Record<string, any>): this {
+    return this.add(group(groupId, traits, { context: this.sharedContext }));
+  }
+
+  getEvents(): EmitterPayload[] {
+    return [...this.events];
+  }
+
+  clear(): void {
+    this.events = [];
+  }
+}
+
+/**
+ * Creates a user session tracking flow with pre-configured context.
+ *
+ * @remarks
+ * This helper creates a session object with methods for tracking events
+ * within a specific user session. All events will include the sessionId
+ * and user context automatically.
+ *
+ * @param userId - Unique identifier for the user
+ * @param sessionId - Unique identifier for the session
+ * @returns Session object with `identify`, `track`, `page`, and `group` methods
+ *
+ * @example
+ * ```typescript
+ * const session = createUserSession('user-123', 'session-456');
+ * await analytics.emit(session.track('Button Clicked', { button: 'signup' }));
+ * await analytics.emit(session.page('Dashboard'));
+ * ```
+ */
+export function createUserSession(userId: string, sessionId: string) {
+  const context = new ContextBuilder().setUser(userId).build();
+
+  return {
+    // Identify the user
+    identify: (traits?: Record<string, any>) =>
+      identify(userId, { ...traits, sessionId }, { context }),
+
+    // Track an event in this session
+    track: (event: string, properties?: Record<string, any>) =>
+      track(event, { ...properties, sessionId }, { context }),
+
+    // Track a page view in this session
+    page: (name?: string, properties?: Record<string, any>) =>
+      page(undefined, name, { ...properties, sessionId }, { context }),
+
+    // Associate with a group
+    group: (groupId: string, traits?: Record<string, any>) =>
+      group(groupId, { ...traits, sessionId }, { context }),
+  };
+}
+
+/**
+ * Creates an anonymous user tracking flow.
+ *
+ * @remarks
+ * This helper creates a session object for tracking anonymous users before
+ * they are identified. When the user signs up or logs in, use the `alias`
+ * method to link their anonymous activity to their user ID.
+ *
+ * @param anonymousId - Unique identifier for the anonymous user
+ * @returns Session object with `track`, `page`, `identify`, and `alias` methods
+ *
+ * @example
+ * ```typescript
+ * const anonymousSession = createAnonymousSession('anon-123');
+ * await analytics.emit(anonymousSession.track('Page Viewed', { page: 'home' }));
+ *
+ * // Later, when user signs up
+ * await analytics.emit(anonymousSession.alias('user-123'));
+ * await analytics.emit(anonymousSession.identify('user-123', { email: 'user@example.com' }));
+ * ```
+ */
+export function createAnonymousSession(anonymousId: string) {
+  const options: EmitterOptions = { anonymousId };
+
+  return {
+    // Track an event
+    track: (event: string, properties?: Record<string, any>) => track(event, properties, options),
+
+    // Track a page view
+    page: (name?: string, properties?: Record<string, any>) =>
+      page(undefined, name, properties, options),
+
+    // Convert to identified user
+    identify: (userId: string, traits?: Record<string, any>) => identify(userId, traits, options),
+
+    // Alias when user signs up
+    alias: (userId: string) => alias(userId, anonymousId, options),
+  };
+}
+
+/**
+ * Type guard to check if a payload is a track event.
+ *
+ * @param payload - The payload to check
+ * @returns True if the payload is a track event
+ */
+export const isTrackPayload = (payload: EmitterPayload): payload is EmitterTrackPayload =>
+  payload.type === 'track';
+
+/**
+ * Type guard to check if a payload is an identify event.
+ *
+ * @param payload - The payload to check
+ * @returns True if the payload is an identify event
+ */
+export const isIdentifyPayload = (payload: EmitterPayload): payload is EmitterIdentifyPayload =>
+  payload.type === 'identify';
+
+/**
+ * Type guard to check if a payload is a page event.
+ *
+ * @param payload - The payload to check
+ * @returns True if the payload is a page event
+ */
+export const isPagePayload = (payload: EmitterPayload): payload is EmitterPagePayload =>
+  payload.type === 'page';
+
+/**
+ * Type guard to check if a payload is a group event.
+ *
+ * @param payload - The payload to check
+ * @returns True if the payload is a group event
+ */
+export const isGroupPayload = (payload: EmitterPayload): payload is EmitterGroupPayload =>
+  payload.type === 'group';
+
+/**
+ * Type guard to check if a payload is an alias event.
+ *
+ * @param payload - The payload to check
+ * @returns True if the payload is an alias event
+ */
+export const isAliasPayload = (payload: EmitterPayload): payload is EmitterAliasPayload =>
+  payload.type === 'alias';
+
+/**
+ * Adds consistent metadata to an analytics event payload.
+ *
+ * @remarks
+ * This helper enriches an event payload with metadata that will be included
+ * in the event's context.app object. Useful for tracking version, source,
+ * or other application-level metadata.
+ *
+ * @param payload - The event payload to enrich
+ * @param metadata - Metadata to add (version, source, or custom properties)
+ * @returns The enriched payload with metadata in context.app
+ *
+ * @example
+ * ```typescript
+ * const event = track('Button Clicked', { button: 'signup' });
+ * const enriched = withMetadata(event, { version: '1.0.0', source: 'webapp' });
+ * await analytics.emit(enriched);
+ * ```
+ */
+export function withMetadata<T extends EmitterPayload>(
+  payload: T,
+  metadata: { version?: string; source?: string; [key: string]: unknown },
+): T {
+  return {
+    ...payload,
+    context: {
+      ...payload.context,
+      app: {
+        ...payload.context?.app,
+        ...metadata,
+      },
+    },
+  };
+}
+
+/**
+ * Adds UTM parameters to an analytics event payload.
+ *
+ * @remarks
+ * This helper enriches an event payload with UTM campaign parameters that
+ * will be included in the event's context.campaign object. Useful for
+ * tracking marketing campaign attribution.
+ *
+ * @param payload - The event payload to enrich
+ * @param utm - UTM parameters (source, medium, campaign, term, content)
+ * @returns The enriched payload with UTM parameters in context.campaign
+ *
+ * @example
+ * ```typescript
+ * const event = track('Signup Started', {});
+ * const enriched = withUTM(event, {
+ *   source: 'google',
+ *   medium: 'cpc',
+ *   campaign: 'summer-sale'
+ * });
+ * await analytics.emit(enriched);
+ * ```
+ */
+export function withUTM<T extends EmitterPayload>(
+  payload: T,
+  utm: { source?: string; medium?: string; campaign?: string; term?: string; content?: string },
+): T {
+  return {
+    ...payload,
+    context: {
+      ...payload.context,
+      campaign: {
+        ...payload.context?.campaign,
+        ...utm,
+      },
+    },
+  };
+}