@od-oneapp/analytics 2026.1.1301

package/src/shared/utils/emitter-adapter.ts

@@ -0,0 +1,212 @@
+/**
+ * @fileoverview Adapter functions to convert emitter payloads to analytics method calls
+ * Adapter functions to convert emitter payloads to analytics method calls
+ * This bridges the gap between the Segment.io spec emitters and the analytics manager
+ */
+
+import type {
+  EmitterAliasPayload,
+  EmitterGroupPayload,
+  EmitterIdentifyPayload,
+  EmitterPagePayload,
+  EmitterPayload,
+  EmitterScreenPayload,
+  EmitterTrackPayload,
+} from '../emitters/emitter-types';
+import type { AnalyticsManager } from '../types/types';
+
+/**
+ * Routes any emitter payload to the matching analytics manager method.
+ *
+ * This function is deliberately small so that Codex/OpenAI powered tooling can
+ * inspect a single switch statement and understand how each analytics verb maps
+ * to the strongly typed helper below.
+ *
+ * @deprecated Use `analytics.emit(payload)` instead for simpler API usage.
+ * This function remains available for compatibility and advanced use cases.
+ *
+ * @example Preferred approach:
+ * ```typescript
+ * await analytics.emit(track('Button Clicked', { color: 'blue' }));
+ * ```
+ *
+ * @param analytics - The analytics manager implementation (client or server)
+ * @param payload - Any emitter payload created by the Segment-style helpers
+ * @throws Error when the payload type is unknown, protecting against silent drops
+ */
+export async function processEmitterPayload(
+  analytics: AnalyticsManager,
+  payload: EmitterPayload,
+): Promise<void> {
+  switch (payload.type) {
+    case 'identify':
+      return processIdentifyPayload(analytics, payload);
+    case 'track':
+      return processTrackPayload(analytics, payload);
+    case 'page':
+      return processPagePayload(analytics, payload);
+    case 'screen':
+      return processScreenPayload(analytics, payload);
+    case 'group':
+      return processGroupPayload(analytics, payload);
+    case 'alias':
+      return processAliasPayload(analytics, payload);
+    default: {
+      // Runtime safety for unknown payload types (e.g., from untyped JavaScript code)
+      const unknownPayload = payload as { type: string };
+      throw new Error(`Unknown emitter payload type: ${unknownPayload.type}`);
+    }
+  }
+}
+
+/**
+ * Pipes an identify payload into `analytics.identify`, preserving context.
+ *
+ * @param analytics - Active analytics manager
+ * @param payload - Identify payload produced by the emitter factory
+ */
+export async function processIdentifyPayload(
+  analytics: AnalyticsManager,
+  payload: EmitterIdentifyPayload,
+): Promise<void> {
+  const { traits, userId, ...options } = payload;
+
+  // Convert emitter options to tracking options
+  const trackingOptions = {
+    context: options.context,
+    // Add other options as needed
+  };
+
+  await analytics.identify(userId, traits, trackingOptions);
+}
+
+/**
+ * Pipes a track payload into `analytics.track`, preserving context metadata.
+ *
+ * @param analytics - Active analytics manager
+ * @param payload - Track payload produced by the emitter factory
+ */
+export async function processTrackPayload(
+  analytics: AnalyticsManager,
+  payload: EmitterTrackPayload,
+): Promise<void> {
+  const { event, properties, ...options } = payload;
+
+  const trackingOptions = {
+    context: options.context,
+  };
+
+  await analytics.track(event, properties, trackingOptions);
+}
+
+/**
+ * Pipes a page payload into `analytics.page`.
+ *
+ * @param analytics - Active analytics manager
+ * @param payload - Page payload produced by the emitter factory
+ */
+export async function processPagePayload(
+  analytics: AnalyticsManager,
+  payload: EmitterPagePayload,
+): Promise<void> {
+  const { name, properties, ...options } = payload;
+
+  const trackingOptions = {
+    context: options.context,
+  };
+
+  await analytics.page(name, properties, trackingOptions);
+}
+
+/**
+ * Pipes a screen payload into `analytics.screen` (mobile equivalent of page).
+ *
+ * @param analytics - Active analytics manager
+ * @param payload - Screen payload produced by the emitter factory
+ */
+export async function processScreenPayload(
+  analytics: AnalyticsManager,
+  payload: EmitterScreenPayload,
+): Promise<void> {
+  const { name, properties, ...options } = payload;
+
+  const trackingOptions = {
+    context: options.context,
+  };
+
+  await analytics.screen?.(name, properties, trackingOptions);
+}
+
+/**
+ * Pipes a group payload into `analytics.group`.
+ *
+ * @param analytics - Active analytics manager
+ * @param payload - Group payload produced by the emitter factory
+ */
+export async function processGroupPayload(
+  analytics: AnalyticsManager,
+  payload: EmitterGroupPayload,
+): Promise<void> {
+  const { groupId, traits, ...options } = payload;
+
+  const trackingOptions = {
+    context: options.context,
+  };
+
+  await analytics.group(groupId, traits, trackingOptions);
+}
+
+/**
+ * Pipes an alias payload into `analytics.alias`.
+ *
+ * @param analytics - Active analytics manager
+ * @param payload - Alias payload produced by the emitter factory
+ */
+export async function processAliasPayload(
+  analytics: AnalyticsManager,
+  payload: EmitterAliasPayload,
+): Promise<void> {
+  const { previousId, userId, ...options } = payload;
+
+  const trackingOptions = {
+    context: options.context,
+  };
+
+  await analytics.alias(userId, previousId ?? '', trackingOptions);
+}
+
+/**
+ * Creates a pre-bound emitter processor for repeated usage.
+ *
+ * @example
+ * ```ts
+ * const processor = createEmitterProcessor(analytics);
+ * queue.forEach(processor);
+ * ```
+ *
+ * @param analytics - Active analytics manager
+ * @returns Function that accepts any emitter payload and routes it correctly
+ */
+export function createEmitterProcessor(analytics: AnalyticsManager) {
+  return (payload: EmitterPayload) => processEmitterPayload(analytics, payload);
+}
+
+/**
+ * Minimal helper for wiring ecommerce event specs into analytics.track.
+ *
+ * @deprecated Use `analytics.emit(ecommerce.EVENT_NAME(...))` instead.
+ *
+ * @example Preferred approach:
+ * ```typescript
+ * await analytics.emit(ecommerce.productViewed({ product_id: '123' }));
+ * ```
+ *
+ * @param analytics - Active analytics manager
+ * @param eventSpec - Object that contains the `name` and `properties` fields
+ */
+export async function trackEcommerceEvent(
+  analytics: AnalyticsManager,
+  eventSpec: { name: string; properties: Record<string, any> },
+): Promise<void> {
+  await analytics.track(eventSpec.name, eventSpec.properties);
+}

package/src/shared/utils/manager.test.ts

@@ -0,0 +1,36 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import * as Manager from './manager';
+
+describe('analytics/utils/manager - stateful behaviors', () => {
+  let mgr: any;
+  beforeEach(() => {
+    mgr = (Manager as any).createManager
+      ? (Manager as any).createManager()
+      : (Manager as any).Manager?.create?.();
+  });
+
+  it('registers/unregisters emitters safely', () => {
+    if (!mgr) return;
+    const emitterA = vi.fn();
+    const emitterB = vi.fn();
+    mgr.register(emitterA);
+    mgr.register(emitterB);
+    mgr.emit({ type: 'test', payload: { a: 1 } });
+    expect(emitterA).toHaveBeenCalledTimes(1);
+    expect(emitterB).toHaveBeenCalledTimes(1);
+    mgr.unregister(emitterA);
+    mgr.emit({ type: 'test', payload: { a: 2 } });
+    expect(emitterA).toHaveBeenCalledTimes(1);
+    expect(emitterB).toHaveBeenCalledTimes(2);
+  });
+
+  it('handles invalid events gracefully', () => {
+    if (!mgr) return;
+    const emitter = vi.fn();
+    mgr.register(emitter);
+    mgr.emit(null as any);
+    mgr.emit(undefined as any);
+    expect(emitter).toHaveBeenCalledTimes(0);
+  });
+});