@od-oneapp/analytics 2026.1.1301

package/src/shared/emitters/ai/README.md

@@ -0,0 +1,981 @@
+# AI Product Analytics Tracking
+
+Comprehensive analytics 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.
+
+## Philosophy
+
+**Track the AI product itself, not what users do with it.**
+
+This package tracks **product features** like message regeneration, conversation branching, artifact creation, and code
+generation. It does NOT track business use cases like e-commerce orders or support tickets.
+
+### Clear Separation
+
+```typescript
+// ✅ AI Product Features (this package)
+ai.MESSAGE_REGENERATED({ ... });      // User regenerated a response
+ai.BRANCH_CREATED({ ... });           // User explored alternative response
+ai.ARTIFACT_CREATED({ ... });         // System created interactive artifact
+ai.CODE_GENERATED({ ... });           // AI generated code snippet
+
+// ✅ E-commerce Behaviors (separate package)
+ecommerce.productViewed({ ... });     // User viewed a product
+ecommerce.cartUpdated({ ... });       // User added to cart
+ecommerce.checkoutStarted({ ... });   // User started checkout
+
+// ✅ You can use both together
+// Track AI features in your e-commerce chatbot
+ai.MESSAGE_SENT({ ... });             // Track the chat feature
+ecommerce.productViewed({ ... });     // Track the business action
+```
+
+## Overview
+
+This module provides **90+ standardized AI product events** that follow the same emitter-based architecture as the
+e-commerce tracking system. It integrates seamlessly with PostHog, Vercel Analytics, Segment, and other analytics
+providers.
+
+### What This Tracks
+
+- **Conversation Features**: Message regeneration, editing, branching, conversation management
+- **Content Generation**: Code generation, image generation, text summaries, translations
+- **Interactive Elements**: Artifacts (Claude-style), canvas mode, live previews
+- **Files & Attachments**: Upload, processing, referencing
+- **Context Management**: Memory, custom instructions, project context, RAG operations
+- **Collaboration**: Sharing, forking, team workspaces
+- **User Interactions**: Copy, execute, download, modify generated content
+- **System Operations**: Model selection, streaming, errors, performance
+- **Quality & Feedback**: User ratings, regenerations, stop generation
+- **Advanced Features**: Multi-step reasoning, tool usage, search & citations
+
+## Installation
+
+```bash
+# Already available in @repo/analytics
+pnpm install @repo/analytics
+```
+
+## Quick Start
+
+### Basic Conversation Tracking
+
+```typescript
+import { ai } from "@repo/analytics/shared";
+
+// Track conversation start
+ai.CONVERSATION_STARTED({
+  conversation_id: "conv_123",
+  model_id: "claude-3-5-sonnet",
+  conversation_type: "chat"
+});
+
+// Track user message
+ai.MESSAGE_SENT({
+  conversation_id: "conv_123",
+  message_id: "msg_456",
+  model_id: "claude-3-5-sonnet",
+  message_role: "user",
+  message_length: 50
+});
+
+// Track AI response
+ai.MESSAGE_RECEIVED({
+  conversation_id: "conv_123",
+  message_id: "msg_457",
+  model_id: "claude-3-5-sonnet",
+  message_role: "assistant",
+  message_length: 250,
+  response_time_ms: 850,
+  finish_reason: "stop"
+});
+```
+
+### ChatGPT-Style Features
+
+```typescript
+import { ai } from "@repo/analytics/shared";
+
+// User regenerates a response
+ai.MESSAGE_REGENERATED({
+  conversation_id: "conv_123",
+  model_id: "gpt-4",
+  original_message_id: "msg_457",
+  attempt_number: 2,
+  reason: "user-requested"
+});
+
+// User edits their message
+ai.MESSAGE_EDITED({
+  conversation_id: "conv_123",
+  model_id: "claude-3-5-sonnet",
+  message_id: "msg_456",
+  edit_type: "user-edit",
+  original_length: 50,
+  new_length: 75
+});
+
+// User creates conversation branch
+ai.BRANCH_CREATED({
+  conversation_id: "conv_123",
+  model_id: "gpt-4",
+  branch_point_message_id: "msg_457",
+  original_conversation_id: "conv_123",
+  new_conversation_id: "conv_124",
+  reason: "explore-alternative"
+});
+
+// User stops generation mid-response
+ai.STOP_GENERATION({
+  conversation_id: "conv_123",
+  model_id: "claude-3-5-sonnet",
+  message_id: "msg_458",
+  partial_length: 120,
+  stop_reason: "user-interrupted"
+});
+```
+
+### Content Generation Tracking
+
+```typescript
+import { ai } from "@repo/analytics/shared";
+
+// Code generation
+ai.CODE_GENERATED({
+  conversation_id: "conv_123",
+  model_id: "gpt-4",
+  language: "typescript",
+  code_length: 450,
+  code_type: "function",
+  has_explanation: true
+});
+
+// User copies generated code
+ai.CODE_COPIED({
+  conversation_id: "conv_123",
+  model_id: "gpt-4",
+  code_id: "code_789",
+  language: "typescript",
+  code_length: 450
+});
+
+// User executes generated code
+ai.CODE_EXECUTED({
+  conversation_id: "conv_123",
+  model_id: "gpt-4",
+  code_id: "code_789",
+  language: "typescript",
+  execution_status: "success",
+  execution_time_ms: 120
+});
+
+// Image generation
+ai.IMAGE_GENERATED({
+  conversation_id: "conv_123",
+  model_id: "dall-e-3",
+  image_type: "generated",
+  prompt_length: 80,
+  image_format: "png",
+  image_size: "1024x1024"
+});
+
+// Summary generation
+ai.SUMMARY_GENERATED({
+  conversation_id: "conv_123",
+  model_id: "claude-3-5-sonnet",
+  source_type: "document",
+  source_length: 5000,
+  summary_length: 300,
+  compression_ratio: 16.7
+});
+```
+
+### Artifacts & Canvas (Claude-Style)
+
+```typescript
+import { ai } from "@repo/analytics/shared";
+
+// Create interactive artifact
+ai.ARTIFACT_CREATED({
+  conversation_id: "conv_123",
+  model_id: "claude-3-5-sonnet",
+  artifact_id: "art_001",
+  artifact_type: "react-component",
+  action: "create",
+  language: "tsx"
+});
+
+// User edits artifact
+ai.ARTIFACT_EDITED({
+  conversation_id: "conv_123",
+  model_id: "claude-3-5-sonnet",
+  artifact_id: "art_001",
+  artifact_type: "react-component",
+  action: "edit",
+  version: 2
+});
+
+// User forks artifact
+ai.ARTIFACT_FORKED({
+  conversation_id: "conv_123",
+  model_id: "claude-3-5-sonnet",
+  artifact_id: "art_001",
+  artifact_type: "react-component",
+  action: "fork",
+  new_artifact_id: "art_002"
+});
+
+// Canvas mode
+ai.CANVAS_OPENED({
+  conversation_id: "conv_123",
+  model_id: "claude-3-5-sonnet",
+  canvas_type: "code",
+  initial_content_length: 500
+});
+
+// Live preview
+ai.LIVE_PREVIEW_TOGGLED({
+  conversation_id: "conv_123",
+  model_id: "claude-3-5-sonnet",
+  artifact_id: "art_001",
+  preview_enabled: true
+});
+```
+
+### Files & Attachments
+
+```typescript
+import { ai } from "@repo/analytics/shared";
+
+// User uploads file
+ai.FILE_UPLOADED({
+  conversation_id: "conv_123",
+  model_id: "gpt-4",
+  file_type: "pdf",
+  file_size_bytes: 1024000,
+  file_count: 1
+});
+
+// File processed successfully
+ai.FILE_PROCESSED({
+  conversation_id: "conv_123",
+  model_id: "gpt-4",
+  file_type: "pdf",
+  processing_time_ms: 2500,
+  extracted_text_length: 5000,
+  processing_status: "success"
+});
+
+// File referenced in conversation
+ai.FILE_REFERENCED({
+  conversation_id: "conv_123",
+  model_id: "gpt-4",
+  file_id: "file_123",
+  file_type: "pdf",
+  reference_context: "answer-question"
+});
+```
+
+### Context & Memory
+
+```typescript
+import { ai } from "@repo/analytics/shared";
+
+// Custom instructions updated
+ai.CUSTOM_INSTRUCTIONS_UPDATED({
+  model_id: "gpt-4",
+  user_id: "user_123",
+  instructions_length: 200,
+  has_preferences: true,
+  has_constraints: true
+});
+
+// Memory created
+ai.MEMORY_CREATED({
+  conversation_id: "conv_123",
+  model_id: "claude-3-5-sonnet",
+  memory_type: "user-preference",
+  memory_content_length: 50,
+  memory_source: "explicit"
+});
+
+// RAG query executed
+ai.RAG_QUERY_EXECUTED({
+  conversation_id: "conv_123",
+  model_id: "gpt-4",
+  query_text: "Find documentation about React hooks",
+  query_embedding_dimensions: 1536,
+  chunks_retrieved: 5,
+  retrieval_time_ms: 150,
+  retrieval_status: "success"
+});
+```
+
+### Collaboration & Sharing
+
+```typescript
+import { ai } from "@repo/analytics/shared";
+
+// Share conversation
+ai.CONVERSATION_SHARED({
+  conversation_id: "conv_123",
+  model_id: "claude-3-5-sonnet",
+  share_type: "public-link",
+  share_permissions: "view-only",
+  message_count: 15
+});
+
+// Fork conversation
+ai.CONVERSATION_FORKED({
+  conversation_id: "conv_123",
+  model_id: "gpt-4",
+  original_conversation_id: "conv_123",
+  new_conversation_id: "conv_125",
+  forked_from_message_id: "msg_460"
+});
+
+// Team workspace created
+ai.WORKSPACE_CREATED({
+  workspace_id: "ws_001",
+  model_id: "claude-3-5-sonnet",
+  workspace_type: "team",
+  member_count: 5
+});
+```
+
+## Event Categories (90+ Events)
+
+### 1. Conversation & Messaging (14 events)
+
+Core conversation lifecycle and message management.
+
+- `CONVERSATION_STARTED` - New conversation initiated
+- `CONVERSATION_RESUMED` - Existing conversation reopened
+- `CONVERSATION_ENDED` - Conversation closed or archived
+- `MESSAGE_SENT` - User sends message
+- `MESSAGE_RECEIVED` - AI responds to message
+- `MESSAGE_REGENERATED` - User requests new response
+- `MESSAGE_EDITED` - User or AI edits message
+- `MESSAGE_DELETED` - Message removed from history
+- `BRANCH_CREATED` - Alternative conversation path created
+- `BRANCH_MERGED` - Conversation branches combined
+- `STOP_GENERATION` - User stops mid-generation
+- `STREAMING_STARTED` - Response streaming begins
+- `STREAMING_CHUNK_RECEIVED` - Stream chunk delivered
+- `STREAMING_COMPLETED` - Stream finished successfully
+
+### 2. Content Generation (15 events)
+
+All types of AI-generated content.
+
+- `CODE_GENERATED` - Code snippet created
+- `CODE_EXPLAINED` - Code explanation provided
+- `CODE_DEBUGGED` - Debug suggestions offered
+- `CODE_REFACTORED` - Code improvement suggested
+- `CODE_TRANSLATED` - Code converted between languages
+- `IMAGE_GENERATED` - Image created from prompt
+- `IMAGE_EDITED` - Existing image modified
+- `TEXT_GENERATED` - General text content created
+- `SUMMARY_GENERATED` - Document/content summarized
+- `TRANSLATION_GENERATED` - Text translated
+- `COMPLETION_GENERATED` - Text completion provided
+- `REWRITE_GENERATED` - Content rewritten
+- `EMAIL_DRAFTED` - Email composition assisted
+- `DOCUMENT_CREATED` - Document generated
+- `OUTLINE_CREATED` - Content outline generated
+
+### 3. Files & Attachments (7 events)
+
+File upload, processing, and usage.
+
+- `FILE_UPLOADED` - File attached to conversation
+- `FILE_PROCESSED` - File successfully analyzed
+- `FILE_PROCESSING_FAILED` - File analysis failed
+- `FILE_DOWNLOADED` - Generated file downloaded
+- `FILE_REFERENCED` - File context used in response
+- `FILE_DELETED` - Attachment removed
+- `BATCH_FILES_PROCESSED` - Multiple files processed
+
+### 4. Search, Browse & Citations (6 events)
+
+Web search and source attribution.
+
+- `WEB_SEARCH_PERFORMED` - Internet search executed
+- `CITATION_ADDED` - Source cited in response
+- `BROWSE_SESSION_STARTED` - Web browsing initiated
+- `PAGE_CONTENT_FETCHED` - Webpage content retrieved
+- `SEARCH_RESULTS_RANKED` - Results ordered by relevance
+- `EXTERNAL_SOURCE_ACCESSED` - Outside data referenced
+
+### 5. Tools & Functions (7 events)
+
+Tool calls and function execution.
+
+- `TOOL_CALL_STARTED` - Tool execution begins
+- `TOOL_CALL_COMPLETED` - Tool finishes successfully
+- `TOOL_CALL_FAILED` - Tool execution error
+- `FUNCTION_EXECUTED` - Custom function called
+- `API_REQUEST_MADE` - External API called
+- `PLUGIN_ACTIVATED` - Extension enabled
+- `EXTENSION_USED` - Add-on functionality used
+
+### 6. Context & Memory (10 events)
+
+Context management and long-term memory.
+
+- `CONTEXT_WINDOW_UPDATED` - Active context changed
+- `MEMORY_CREATED` - New memory stored
+- `MEMORY_RETRIEVED` - Past memory recalled
+- `MEMORY_UPDATED` - Existing memory modified
+- `MEMORY_DELETED` - Memory removed
+- `CUSTOM_INSTRUCTIONS_UPDATED` - User preferences changed
+- `PROJECT_CONTEXT_LOADED` - Project-specific context applied
+- `RAG_QUERY_EXECUTED` - Vector search performed
+- `EMBEDDING_GENERATED` - Text vectorized
+- `KNOWLEDGE_BASE_QUERIED` - Internal knowledge searched
+
+### 7. User Interactions (9 events)
+
+User actions on generated content.
+
+- `CODE_COPIED` - Code copied to clipboard
+- `CODE_EXECUTED` - Code run in environment
+- `CONTENT_COPIED` - General content copied
+- `CONTENT_DOWNLOADED` - Content saved locally
+- `CONTENT_SHARED` - Content shared externally
+- `SUGGESTION_ACCEPTED` - AI suggestion applied
+- `SUGGESTION_REJECTED` - AI suggestion dismissed
+- `INLINE_EDIT_APPLIED` - Direct edit to AI content
+- `DIFF_VIEWED` - Code changes reviewed
+
+### 8. Workspace & Organization (7 events)
+
+Organization and workspace management.
+
+- `CONVERSATION_RENAMED` - Title changed
+- `CONVERSATION_ARCHIVED` - Moved to archive
+- `CONVERSATION_DELETED` - Permanently removed
+- `FOLDER_CREATED` - Organization folder made
+- `TAG_ADDED` - Conversation tagged
+- `SEARCH_PERFORMED` - Conversation history searched
+- `FILTER_APPLIED` - Conversation list filtered
+
+### 9. Collaboration & Sharing (6 events)
+
+Team features and sharing.
+
+- `CONVERSATION_SHARED` - Conversation link shared
+- `CONVERSATION_FORKED` - Copy created from original
+- `WORKSPACE_CREATED` - Team workspace initialized
+- `MEMBER_INVITED` - User added to workspace
+- `COMMENT_ADDED` - Collaboration comment posted
+- `PERMISSION_CHANGED` - Access level modified
+
+### 10. Artifacts & Canvas (7 events)
+
+Interactive artifacts and canvas mode (Claude-style).
+
+- `ARTIFACT_CREATED` - Interactive artifact generated
+- `ARTIFACT_EDITED` - Artifact modified
+- `ARTIFACT_EXECUTED` - Artifact code run
+- `ARTIFACT_PUBLISHED` - Artifact made available
+- `ARTIFACT_FORKED` - Artifact copied
+- `CANVAS_OPENED` - Canvas mode activated
+- `LIVE_PREVIEW_TOGGLED` - Real-time preview toggled
+
+### 11. Feedback & Quality (6 events)
+
+User feedback and quality signals.
+
+- `FEEDBACK_PROVIDED` - User rating submitted
+- `RESPONSE_RATED` - Response quality scored
+- `BUG_REPORTED` - Issue reported
+- `FEATURE_REQUESTED` - Enhancement suggested
+- `HARMFUL_CONTENT_FLAGGED` - Safety issue reported
+- `QUALITY_ISSUE_REPORTED` - Quality problem noted
+
+### 12. System & Performance (6 events)
+
+Technical operations and model management.
+
+- `MODEL_SWITCHED` - AI model changed
+- `SETTINGS_UPDATED` - Configuration modified
+- `ERROR_OCCURRED` - System error encountered
+- `RATE_LIMIT_HIT` - Usage limit reached
+- `TOKEN_USAGE_TRACKED` - Token consumption recorded
+- `PERFORMANCE_MEASURED` - Metrics captured
+
+## Property Types
+
+### BaseAIProperties
+
+Core properties shared across most events:
+
+```typescript
+interface BaseAIProperties {
+  conversation_id?: string; // Links events to conversation
+  message_id?: string; // Specific message identifier
+  model_id: string; // Required: AI model used
+  model_provider?: "anthropic" | "openai" | "google" | "perplexity" | "other";
+  session_id?: string; // Browser/app session
+  user_id?: string; // User identifier
+  workspace_id?: string; // Team workspace
+}
+```
+
+### TokenUsageProperties
+
+Token consumption tracking:
+
+```typescript
+interface TokenUsageProperties {
+  input_tokens?: number;
+  output_tokens?: number;
+  total_tokens?: number;
+  cost?: number;
+  cost_currency?: string; // Default: 'USD'
+}
+```
+
+### ModelConfigProperties
+
+Model configuration parameters:
+
+```typescript
+interface ModelConfigProperties {
+  temperature?: number; // 0-2
+  max_output_tokens?: number;
+  top_p?: number; // 0-1
+  frequency_penalty?: number; // -2 to 2
+  presence_penalty?: number; // -2 to 2
+  seed?: number;
+}
+```
+
+## Utility Functions
+
+### cleanProperties
+
+Remove undefined and null values:
+
+```typescript
+import { cleanProperties } from "@repo/analytics/shared";
+
+const cleaned = cleanProperties({
+  model_id: "gpt-4",
+  temperature: undefined,
+  max_tokens: null
+});
+// Result: { model_id: 'gpt-4' }
+```
+
+### validateRequiredProperties
+
+Validate required fields are present:
+
+```typescript
+import { validateRequiredProperties } from "@repo/analytics/shared";
+
+validateRequiredProperties(properties, ["model_id", "conversation_id"]);
+// Throws error if missing
+```
+
+### extractModelProvider
+
+Auto-detect provider from model ID:
+
+```typescript
+import { extractModelProvider } from "@repo/analytics/shared";
+
+const provider = extractModelProvider("claude-3-5-sonnet");
+// Result: 'anthropic'
+
+const provider2 = extractModelProvider("gpt-4-turbo");
+// Result: 'openai'
+```
+
+## Integration Examples
+
+### Next.js App Router - Chat Interface
+
+```typescript
+// app/api/chat/route.ts
+import { streamText } from "ai";
+import { openai } from "@ai-sdk/openai";
+import { ai } from "@repo/analytics/server/next";
+
+export async function POST(req: Request) {
+  const { messages, conversationId } = await req.json();
+
+  ai.MESSAGE_SENT({
+    conversation_id: conversationId,
+    model_id: "gpt-4",
+    message_role: "user",
+    message_length: messages[messages.length - 1].content.length
+  });
+
+  const result = await streamText({
+    model: openai("gpt-4"),
+    messages,
+    onFinish: ({ text, usage }) => {
+      ai.MESSAGE_RECEIVED({
+        conversation_id: conversationId,
+        model_id: "gpt-4",
+        message_role: "assistant",
+        message_length: text.length,
+        input_tokens: usage.promptTokens,
+        output_tokens: usage.completionTokens,
+        finish_reason: "stop"
+      });
+    }
+  });
+
+  return result.toAIStreamResponse();
+}
+```
+
+### React Client - Regenerate Feature
+
+```typescript
+// components/ChatMessage.tsx
+import { ai } from '@repo/analytics/client/next';
+
+export function ChatMessage({ message, conversationId, onRegenerate }) {
+  const [attemptNumber, setAttemptNumber] = useState(1);
+
+  const handleRegenerate = () => {
+    setAttemptNumber(prev => prev + 1);
+
+    ai.MESSAGE_REGENERATED({
+      conversation_id: conversationId,
+      model_id: 'gpt-4',
+      original_message_id: message.id,
+      attempt_number: attemptNumber + 1,
+      reason: 'user-requested',
+    });
+
+    onRegenerate();
+  };
+
+  return (
+    <div>
+      <p>{message.content}</p>
+      {message.role === 'assistant' && (
+        <button onClick={handleRegenerate}>
+          ↻ Regenerate
+        </button>
+      )}
+    </div>
+  );
+}
+```
+
+### Conversation Branching
+
+```typescript
+// components/MessageBranching.tsx
+import { ai } from '@repo/analytics/client/next';
+
+export function MessageBranching({ message, conversationId }) {
+  const handleCreateBranch = async () => {
+    const newConversationId = generateId();
+
+    ai.BRANCH_CREATED({
+      conversation_id: conversationId,
+      model_id: 'claude-3-5-sonnet',
+      branch_point_message_id: message.id,
+      original_conversation_id: conversationId,
+      new_conversation_id: newConversationId,
+      reason: 'explore-alternative',
+    });
+
+    // Navigate to new conversation
+    router.push(`/chat/${newConversationId}`);
+  };
+
+  return (
+    <button onClick={handleCreateBranch}>
+      🌿 Branch conversation
+    </button>
+  );
+}
+```
+
+### Code Generation with Execution
+
+```typescript
+// components/CodeBlock.tsx
+import { ai } from '@repo/analytics/client/next';
+
+export function CodeBlock({ code, language, conversationId, codeId }) {
+  const handleCopy = () => {
+    navigator.clipboard.writeText(code);
+
+    ai.CODE_COPIED({
+      conversation_id: conversationId,
+      model_id: 'gpt-4',
+      code_id: codeId,
+      language,
+      code_length: code.length,
+    });
+  };
+
+  const handleExecute = async () => {
+    const startTime = Date.now();
+
+    try {
+      const result = await executeCode(code, language);
+
+      ai.CODE_EXECUTED({
+        conversation_id: conversationId,
+        model_id: 'gpt-4',
+        code_id: codeId,
+        language,
+        execution_status: 'success',
+        execution_time_ms: Date.now() - startTime,
+      });
+    } catch (error) {
+      ai.CODE_EXECUTED({
+        conversation_id: conversationId,
+        model_id: 'gpt-4',
+        code_id: codeId,
+        language,
+        execution_status: 'error',
+        execution_time_ms: Date.now() - startTime,
+        error_message: error.message,
+      });
+    }
+  };
+
+  return (
+    <pre>
+      <code>{code}</code>
+      <button onClick={handleCopy}>Copy</button>
+      <button onClick={handleExecute}>▶ Run</button>
+    </pre>
+  );
+}
+```
+
+### Artifact Creation (Claude-Style)
+
+````typescript
+// app/api/chat/route.ts
+import { ai } from "@repo/analytics/server/next";
+
+function detectArtifact(text: string): ArtifactInfo | null {
+  // Detect if response should be an artifact
+  const hasCodeBlock = /```(\w+)/.test(text);
+  const isComponent = /export (default )?function/.test(text);
+
+  if (isComponent) {
+    return {
+      type: "react-component",
+      language: "tsx"
+    };
+  }
+  // ... more detection logic
+
+  return null;
+}
+
+export async function POST(req: Request) {
+  const result = await streamText({
+    model: anthropic("claude-3-5-sonnet"),
+    messages,
+    onFinish: ({ text }) => {
+      const artifact = detectArtifact(text);
+
+      if (artifact) {
+        const artifactId = generateId();
+
+        ai.ARTIFACT_CREATED({
+          conversation_id: conversationId,
+          model_id: "claude-3-5-sonnet",
+          artifact_id: artifactId,
+          artifact_type: artifact.type,
+          action: "create",
+          language: artifact.language
+        });
+      }
+    }
+  });
+
+  return result.toAIStreamResponse();
+}
+````
+
+## Best Practices
+
+### 1. Always Include Model ID
+
+```typescript
+// ✅ Good
+ai.MESSAGE_RECEIVED({
+  model_id: "claude-3-5-sonnet",
+  message_role: "assistant"
+});
+
+// ❌ Bad - model_id is required
+ai.MESSAGE_RECEIVED({
+  message_role: "assistant"
+});
+```
+
+### 2. Use Conversation IDs for Context
+
+```typescript
+// Track all related events with same conversation_id
+const conversationId = generateId();
+
+ai.CONVERSATION_STARTED({ conversation_id: conversationId, model_id: 'gpt-4' });
+ai.MESSAGE_SENT({ conversation_id: conversationId, model_id: 'gpt-4', ... });
+ai.MESSAGE_RECEIVED({ conversation_id: conversationId, model_id: 'gpt-4', ... });
+ai.MESSAGE_REGENERATED({ conversation_id: conversationId, model_id: 'gpt-4', ... });
+```
+
+### 3. Track User Actions on Generated Content
+
+```typescript
+// Track when users interact with AI output
+ai.CODE_GENERATED({ ... });     // AI creates code
+ai.CODE_COPIED({ ... });        // User copies it
+ai.CODE_EXECUTED({ ... });      // User runs it
+
+ai.ARTIFACT_CREATED({ ... });   // AI creates artifact
+ai.ARTIFACT_EDITED({ ... });    // User modifies it
+ai.ARTIFACT_FORKED({ ... });    // User copies it
+```
+
+### 4. Sample High-Frequency Events
+
+```typescript
+// Don't track every single chunk in a stream
+let chunkCount = 0;
+stream.on('chunk', () => {
+  chunkCount++;
+  // Sample every 10th chunk
+  if (chunkCount % 10 === 0) {
+    ai.STREAMING_CHUNK_RECEIVED({
+      model_id: 'gpt-4',
+      chunk_index: chunkCount,
+    });
+  }
+});
+
+// Always track start and complete
+ai.STREAMING_STARTED({ ... });
+ai.STREAMING_COMPLETED({ chunk_count: chunkCount, ... });
+```
+
+### 5. Track Both Success and Failure
+
+```typescript
+try {
+  const result = await generateCode(prompt);
+
+  ai.CODE_GENERATED({
+    model_id: "gpt-4",
+    language: "typescript",
+    code_length: result.length,
+    code_type: "function"
+  });
+} catch (error) {
+  ai.ERROR_OCCURRED({
+    model_id: "gpt-4",
+    error_type: "generation-failed",
+    error_message: error.message
+  });
+}
+```
+
+## Advanced Usage
+
+### Custom Context
+
+```typescript
+import { ai } from "@repo/analytics/server/next";
+
+ai.MESSAGE_RECEIVED(
+  {
+    model_id: "claude-3-5-sonnet",
+    message_role: "assistant"
+  },
+  {
+    context: {
+      app: {
+        name: "ai-chatbot",
+        version: "2.0.0"
+      },
+      feature: {
+        name: "code-generation",
+        variant: "with-artifacts"
+      }
+    }
+  }
+);
+```
+
+### Performance Tracking
+
+```typescript
+import { ai } from "@repo/analytics/client/next";
+
+const startTime = performance.now();
+
+await generateResponse();
+
+const duration = performance.now() - startTime;
+
+ai.PERFORMANCE_MEASURED({
+  model_id: "gpt-4",
+  operation_type: "message-generation",
+  duration_ms: duration,
+  performance_tier: duration < 1000 ? "fast" : duration < 3000 ? "normal" : "slow"
+});
+```
+
+## Testing
+
+```typescript
+import { describe, it, expect } from "vitest";
+import { ai } from "@repo/analytics/shared";
+
+describe("AI Product Tracking", () => {
+  it("should track message regeneration", () => {
+    const payload = ai.MESSAGE_REGENERATED({
+      conversation_id: "conv_123",
+      model_id: "gpt-4",
+      original_message_id: "msg_456",
+      attempt_number: 2,
+      reason: "user-requested"
+    });
+
+    expect(payload.type).toBe("track");
+    expect(payload.event).toBe("AI Message Regenerated");
+    expect(payload.properties?.attempt_number).toBe(2);
+  });
+
+  it("should track conversation branching", () => {
+    const payload = ai.BRANCH_CREATED({
+      conversation_id: "conv_123",
+      model_id: "claude-3-5-sonnet",
+      branch_point_message_id: "msg_457",
+      original_conversation_id: "conv_123",
+      new_conversation_id: "conv_124",
+      reason: "explore-alternative"
+    });
+
+    expect(payload.type).toBe("track");
+    expect(payload.event).toBe("AI Branch Created");
+    expect(payload.properties?.new_conversation_id).toBe("conv_124");
+  });
+});
+```
+
+## See Also
+
+- [Analytics Package README](../../../README.md)
+- [E-commerce Tracking](../ecommerce/README.md) - Separate business tracking
+- [Types Reference](./types.ts) - Complete event and property type definitions
+- [Segment.io Specification](https://segment.com/docs/connections/spec/)