@od-oneapp/analytics 2026.1.1301

package/src/shared/emitters/ai/events/streaming.ts

@@ -0,0 +1,114 @@
+/**
+ * @fileoverview Streaming-related AI SDK v6 events
+ * Streaming-related AI SDK v6 events
+ */
+
+import { trackAISDK } from '../track-ai-sdk';
+import { AI_SDK_EVENTS, type AISdkEventSpec, type StreamingSDKProperties } from '../types';
+import { cleanProperties, normalizeBaseProperties, validateRequiredProperties } from '../utils';
+
+import type { EmitterOptions, EmitterTrackPayload } from '../../emitter-types';
+
+/**
+ * Track when streaming starts
+ */
+export function streamStarted(
+  properties: StreamingSDKProperties,
+  options?: EmitterOptions,
+): EmitterTrackPayload {
+  validateRequiredProperties(properties, ['model_id', 'stream_type']);
+
+  const normalizedProps = {
+    ...normalizeBaseProperties(properties),
+    stream_type: properties.stream_type,
+  };
+
+  const eventSpec: AISdkEventSpec = {
+    name: AI_SDK_EVENTS.STREAM_STARTED,
+    category: 'ai-sdk',
+    properties: cleanProperties(normalizedProps),
+    requiredProperties: ['model_id', 'stream_type'],
+  };
+
+  return trackAISDK(eventSpec, options);
+}
+
+/**
+ * Track when a stream chunk is received
+ */
+export function streamChunkReceived(
+  properties: StreamingSDKProperties,
+  options?: EmitterOptions,
+): EmitterTrackPayload {
+  validateRequiredProperties(properties, ['model_id', 'stream_type']);
+
+  const normalizedProps = {
+    ...normalizeBaseProperties(properties),
+    stream_type: properties.stream_type,
+    chunk_index: properties.chunk_index,
+  };
+
+  const eventSpec: AISdkEventSpec = {
+    name: AI_SDK_EVENTS.STREAM_CHUNK_RECEIVED,
+    category: 'ai-sdk',
+    properties: cleanProperties(normalizedProps),
+    requiredProperties: ['model_id', 'stream_type'],
+  };
+
+  return trackAISDK(eventSpec, options);
+}
+
+/**
+ * Track when streaming completes
+ */
+export function streamCompleted(
+  properties: StreamingSDKProperties,
+  options?: EmitterOptions,
+): EmitterTrackPayload {
+  validateRequiredProperties(properties, ['model_id', 'stream_type']);
+
+  const normalizedProps = {
+    ...normalizeBaseProperties(properties),
+    stream_type: properties.stream_type,
+    chunk_count: properties.chunk_count,
+    stream_duration_ms: properties.stream_duration_ms,
+    time_to_first_chunk_ms: properties.time_to_first_chunk_ms,
+    chunks_per_second: properties.chunks_per_second,
+  };
+
+  const eventSpec: AISdkEventSpec = {
+    name: AI_SDK_EVENTS.STREAM_COMPLETED,
+    category: 'ai-sdk',
+    properties: cleanProperties(normalizedProps),
+    requiredProperties: ['model_id', 'stream_type'],
+  };
+
+  return trackAISDK(eventSpec, options);
+}
+
+/**
+ * Track when streaming fails
+ */
+export function streamFailed(
+  properties: StreamingSDKProperties & { error_message: string },
+  options?: EmitterOptions,
+): EmitterTrackPayload {
+  validateRequiredProperties(properties, ['model_id', 'stream_type', 'error_message']);
+
+  const normalizedProps = {
+    ...normalizeBaseProperties(properties),
+    stream_type: properties.stream_type,
+    error_message: properties.error_message,
+    chunk_count: properties.chunk_count,
+    stream_duration_ms: properties.stream_duration_ms,
+  };
+
+  const eventSpec: AISdkEventSpec = {
+    name: AI_SDK_EVENTS.STREAM_FAILED,
+    category: 'ai-sdk',
+    properties: cleanProperties(normalizedProps),
+    requiredProperties: ['model_id', 'stream_type', 'error_message'],
+  };
+
+  return trackAISDK(eventSpec, options);
+}

package/src/shared/emitters/ai/events/tool.ts

@@ -0,0 +1,93 @@
+/**
+ * @fileoverview Tool-related AI SDK v6 events
+ * Tool-related AI SDK v6 events
+ */
+
+import { trackAISDK } from '../track-ai-sdk';
+import { AI_SDK_EVENTS, type AISdkEventSpec, type ToolCallSDKProperties } from '../types';
+import { cleanProperties, normalizeBaseProperties, validateRequiredProperties } from '../utils';
+
+import type { EmitterOptions, EmitterTrackPayload } from '../../emitter-types';
+
+/**
+ * Track when a tool call starts
+ */
+export function toolCallStarted(
+  properties: ToolCallSDKProperties,
+  options?: EmitterOptions,
+): EmitterTrackPayload {
+  validateRequiredProperties(properties, ['model_id', 'tool_name']);
+
+  const normalizedProps = {
+    ...normalizeBaseProperties(properties),
+    tool_name: properties.tool_name,
+    tool_type: properties.tool_type,
+    input_size: properties.input_size,
+  };
+
+  const eventSpec: AISdkEventSpec = {
+    name: AI_SDK_EVENTS.TOOL_CALL_STARTED,
+    category: 'ai-sdk',
+    properties: cleanProperties(normalizedProps),
+    requiredProperties: ['model_id', 'tool_name'],
+  };
+
+  return trackAISDK(eventSpec, options);
+}
+
+/**
+ * Track when a tool call completes successfully
+ */
+export function toolCallCompleted(
+  properties: ToolCallSDKProperties,
+  options?: EmitterOptions,
+): EmitterTrackPayload {
+  validateRequiredProperties(properties, ['model_id', 'tool_name', 'result_status']);
+
+  const normalizedProps = {
+    ...normalizeBaseProperties(properties),
+    tool_name: properties.tool_name,
+    tool_type: properties.tool_type,
+    result_status: properties.result_status,
+    execution_time_ms: properties.execution_time_ms,
+    input_size: properties.input_size,
+    output_size: properties.output_size,
+  };
+
+  const eventSpec: AISdkEventSpec = {
+    name: AI_SDK_EVENTS.TOOL_CALL_COMPLETED,
+    category: 'ai-sdk',
+    properties: cleanProperties(normalizedProps),
+    requiredProperties: ['model_id', 'tool_name', 'result_status'],
+  };
+
+  return trackAISDK(eventSpec, options);
+}
+
+/**
+ * Track when a tool call fails
+ */
+export function toolCallFailed(
+  properties: ToolCallSDKProperties & { error_message: string },
+  options?: EmitterOptions,
+): EmitterTrackPayload {
+  validateRequiredProperties(properties, ['model_id', 'tool_name', 'error_message']);
+
+  const normalizedProps = {
+    ...normalizeBaseProperties(properties),
+    tool_name: properties.tool_name,
+    tool_type: properties.tool_type,
+    result_status: 'error' as const,
+    error_message: properties.error_message,
+    execution_time_ms: properties.execution_time_ms,
+  };
+
+  const eventSpec: AISdkEventSpec = {
+    name: AI_SDK_EVENTS.TOOL_CALL_FAILED,
+    category: 'ai-sdk',
+    properties: cleanProperties(normalizedProps),
+    requiredProperties: ['model_id', 'tool_name', 'error_message'],
+  };
+
+  return trackAISDK(eventSpec, options);
+}

package/src/shared/emitters/ai/index.ts

@@ -0,0 +1,69 @@
+/**
+ * @fileoverview AI Product Analytics
+ *
+ * Comprehensive tracking for AI product features like ChatGPT, Claude, and GitHub Copilot.
+ * Track how users interact with your AI-powered chat interface, code generation tools,
+ * and collaborative AI features.
+ *
+ * **90+ Events Covering**:
+ * - **Conversation & Messaging**: Message regeneration, branching, editing
+ * - **Content Generation**: Code, images, summaries, translations
+ * - **Artifacts & Canvas**: Interactive artifacts (Claude-style)
+ * - **Files & Attachments**: Upload, processing, referencing
+ * - **Context & Memory**: Custom instructions, RAG, memory
+ * - **Collaboration**: Sharing, forking, team workspaces
+ * - **User Interactions**: Copy, execute, download, modify
+ * - **Workspace**: Organization, search, tags
+ * - **Feedback & Quality**: Ratings, bug reports, quality issues
+ * - **System & Performance**: Model selection, errors, performance
+ * - **Tools & Functions**: Tool calls, plugins, extensions
+ * - **Search & Citations**: Web search, citations, browsing
+ *
+ * **Usage**: Import event functions and use with `analytics.emit()`:
+ * ```typescript
+ * import { ai } from '@od-oneapp/analytics/shared';
+ * await analytics.emit(ai.messageSent({ messageId: 'msg-123' }));
+ * ```
+ *
+ * @module @od-oneapp/analytics/shared/emitters/ai
+ */
+
+// Export all types
+export * from './types';
+
+// Export utilities
+export * from './utils';
+
+// Export tracking functionality
+export * from './track-ai';
+export * from './track-ai-sdk';
+
+// Re-export event constants for convenience
+export { AI_EVENTS, AI_SDK_EVENTS } from './types';
+
+// Export AI product feature events
+// Organized by product capability for easy discoverability
+
+// Core conversation features (ChatGPT/Claude-style)
+export * from './events/conversation';
+
+// Content generation (code, images, text)
+export * from './events/content-generation';
+
+// Interactive artifacts & canvas (Claude-style)
+export * from './events/artifacts';
+
+// All additional product features
+export * from './events/product-features';
+
+// =============================================================================
+// AI SDK V6 EVENTS
+// =============================================================================
+// Export AI SDK v6 event tracking functions
+
+export * from './events/agent';
+export * from './events/chat';
+export * from './events/chatbot-ecommerce';
+export * from './events/completion';
+export * from './events/streaming';
+export * from './events/tool';

package/src/shared/emitters/ai/track-ai-sdk.ts

@@ -0,0 +1,74 @@
+/**
+ * @fileoverview AI SDK v6 tracking wrapper that integrates with the core emitter system
+ * AI SDK v6 tracking wrapper that integrates with the core emitter system
+ *
+ * Provides tracking for AI SDK v6 operations including:
+ * - Agent execution
+ * - Completions and text generation
+ * - Tool calls and function calling
+ * - Streaming responses
+ * - Chat sessions
+ * - E-commerce chatbot interactions
+ */
+
+import { track } from '../emitters';
+
+import type { EmitterOptions, EmitterTrackPayload } from '../emitter-types';
+
+/**
+ * AI SDK event specification
+ */
+export interface AISdkEventSpec {
+  /** Event name following AI SDK v6 naming conventions */
+  name: string;
+  /** Event category (always 'ai-sdk' for AI SDK events) */
+  category: 'ai-sdk';
+  /** Event properties */
+  properties: Record<string, any>;
+  /** Required property names for validation */
+  requiredProperties?: string[];
+}
+
+/**
+ * Convert an AI SDK event specification to a track payload
+ *
+ * @param eventSpec - The AI SDK event specification
+ * @param options - Optional emitter options
+ * @returns Track payload ready to be sent to analytics providers
+ */
+export function trackAISDK(
+  eventSpec: AISdkEventSpec,
+  options?: EmitterOptions,
+): EmitterTrackPayload {
+  // Add AI SDK-specific context to options
+  const enrichedOptions: EmitterOptions = {
+    ...options,
+    context: {
+      ...options?.context,
+      // Add AI SDK-specific context
+      traits: {
+        ...options?.context?.traits,
+        event_category: eventSpec.category,
+      },
+    },
+  };
+
+  // Return the track payload with the event name and properties
+  return track(eventSpec.name, eventSpec.properties, enrichedOptions);
+}
+
+/**
+ * Helper to create a tracking function for a specific AI SDK event
+ * This allows for cleaner usage in applications
+ *
+ * @param eventFactory - Function that creates an event spec from properties
+ * @returns Tracking function for the specific event
+ */
+export function createAISDKTracker<T extends Record<string, any>>(
+  eventFactory: (properties: T) => AISdkEventSpec,
+) {
+  return (properties: T, options?: EmitterOptions): EmitterTrackPayload => {
+    const eventSpec = eventFactory(properties);
+    return trackAISDK(eventSpec, options);
+  };
+}

package/src/shared/emitters/ai/track-ai.ts

@@ -0,0 +1,50 @@
+/**
+ * @fileoverview AI tracking wrapper that integrates with the core emitter system
+ * AI tracking wrapper that integrates with the core emitter system
+ */
+
+import { track } from '../emitters';
+
+import type { EmitterOptions, EmitterTrackPayload } from '../emitter-types';
+import type { AIEventSpec } from './types';
+
+/**
+ * Convert an AI event specification to a track payload
+ *
+ * @param eventSpec - The AI event specification
+ * @param options - Optional emitter options
+ * @returns Track payload ready to be sent to analytics providers
+ */
+export function trackAI(eventSpec: AIEventSpec, options?: EmitterOptions): EmitterTrackPayload {
+  // Add AI-specific context to options
+  const enrichedOptions: EmitterOptions = {
+    ...options,
+    context: {
+      ...options?.context,
+      // Add AI-specific context
+      ...(eventSpec.category && {
+        // Store category as a custom field since EmitterContext doesn't have category
+        traits: {
+          ...options?.context?.traits,
+          event_category: eventSpec.category,
+        },
+      }),
+    },
+  };
+
+  // Return the track payload with the event name and properties
+  return track(eventSpec.name, eventSpec.properties, enrichedOptions);
+}
+
+/**
+ * Helper to create a tracking function for a specific AI event
+ * This allows for cleaner usage in applications
+ */
+export function createAITracker<T extends Record<string, any>>(
+  eventFactory: (properties: T) => AIEventSpec,
+) {
+  return (properties: T, options?: EmitterOptions): EmitterTrackPayload => {
+    const eventSpec = eventFactory(properties);
+    return trackAI(eventSpec, options);
+  };
+}