@od-oneapp/analytics 2026.1.1301

package/src/examples/ai-sdk-patterns.ts

@@ -0,0 +1,583 @@
+/**
+ * @fileoverview AI SDK v6 Analytics Tracking Patterns
+ * AI SDK v6 Analytics Tracking Patterns
+ *
+ * Comprehensive examples demonstrating how to track AI SDK v6 operations
+ * for agents, completions, tools, streaming, and e-commerce chatbots.
+ */
+
+import { useId } from 'react';
+
+import { logWarn } from '@repo/shared/logger';
+/**
+ * NOTE: These imports require optional peer dependencies:
+ * - @repo/ai/generation (AI SDK generation utilities)
+ * - @repo/ai/ui/react (AI SDK React hooks)
+ * - ai (Vercel AI SDK)
+ *
+ * Install them with: pnpm add ai @ai-sdk/openai
+ */
+
+// Commented out for type safety - uncomment when dependencies are installed
+// import { Chat } from '@repo/ai/generation';
+// import { useChat } from '@repo/ai/ui/react';
+
+import { aiSdk } from '../shared/emitters';
+import {
+  agentExecutionCompleted,
+  agentExecutionFailed,
+  agentExecutionStarted,
+  AI_SDK_EVENTS,
+  calculateCost,
+  generateOperationId,
+  trackAISDK,
+} from '../shared/emitters/ai';
+
+// Commented out for type safety - uncomment when dependencies are installed
+// import type { Agent } from 'ai';
+
+// Placeholder types for example code
+type Agent = any;
+
+// Placeholder useChat hook - replace with actual import when AI SDK is installed
+const useChat = (_options: any) => ({
+  send: (_text: string) => {},
+  messages: [],
+  isLoading: false,
+});
+
+// =============================================================================
+// Pattern 1: Basic Agent Execution Tracking
+// =============================================================================
+
+export async function basicAgentTracking(agent: Agent, prompt: string) {
+  const agentId = 'customer-support-agent';
+  const startTime = Date.now();
+
+  try {
+    // Track agent start
+    agentExecutionStarted({
+      model_id: 'claude-3-5-sonnet',
+      agent_id: agentId,
+      agent_name: 'Customer Support Agent',
+    });
+
+    // Execute agent
+    const result = await agent.generate({ prompt });
+
+    // Track successful completion
+    agentExecutionCompleted({
+      model_id: 'claude-3-5-sonnet',
+      agent_id: agentId,
+      status: 'completed',
+      completion_type: 'text',
+      total_duration_ms: Date.now() - startTime,
+      input_tokens: result.usage?.inputTokens,
+      output_tokens: result.usage?.outputTokens,
+      step_count: result.steps?.length,
+    });
+
+    return result;
+  } catch (error: any) {
+    // Track failure
+    agentExecutionFailed({
+      model_id: 'claude-3-5-sonnet',
+      agent_id: agentId,
+      error_message: error.message,
+      total_duration_ms: Date.now() - startTime,
+      completion_type: 'text',
+    });
+
+    throw error;
+  }
+}
+
+// =============================================================================
+// Pattern 2: Chat Session Tracking with Messages
+// =============================================================================
+
+export class TrackedChatSession {
+  private sessionId: string;
+  private messageCount = 0;
+  private totalTokens = 0;
+  private sessionStartTime: number;
+
+  constructor(sessionId: string) {
+    this.sessionId = sessionId;
+    this.sessionStartTime = Date.now();
+
+    // Track session start
+    aiSdk.chatSessionStarted({
+      model_id: 'gpt-4-turbo',
+      session_id: sessionId,
+      session_type: 'chat',
+    });
+  }
+
+  async sendMessage(content: string, userId?: string) {
+    this.messageCount++;
+
+    // Track user message
+    aiSdk.chatMessageSent({
+      model_id: 'gpt-4-turbo',
+      session_id: this.sessionId,
+      user_id: userId,
+      message_role: 'user',
+      message_length: content.length,
+      message_index: this.messageCount,
+    });
+
+    const startTime = Date.now();
+    // Placeholder - replace with actual Chat.create when AI SDK is installed
+    const result: any = await Promise.resolve({
+      text: '',
+      finishReason: 'stop',
+      usage: { totalTokens: 0 },
+    });
+
+    // Track assistant response
+    aiSdk.chatMessageReceived({
+      model_id: 'gpt-4-turbo',
+      session_id: this.sessionId,
+      message_role: 'assistant',
+      message_length: result.text?.length,
+      message_index: this.messageCount + 1,
+      response_time_ms: Date.now() - startTime,
+      finish_reason: result.finishReason,
+    });
+
+    this.messageCount++;
+    if (result.usage?.totalTokens) {
+      this.totalTokens += result.usage.totalTokens;
+    }
+
+    return result;
+  }
+
+  endSession(reason?: 'user-ended' | 'timeout' | 'error') {
+    aiSdk.chatSessionEnded({
+      model_id: 'gpt-4-turbo',
+      session_id: this.sessionId,
+      duration_ms: Date.now() - this.sessionStartTime,
+      message_count: this.messageCount,
+      total_tokens: this.totalTokens,
+      session_end_reason: reason ?? 'user-ended',
+    });
+  }
+}
+
+// =============================================================================
+// Pattern 3: Tool Execution Tracking with Metrics
+/**
+ * Wraps a tool invocation with analytics tracking for start, success, and failure events.
+ *
+ * @param toolName - The name of the tool being invoked
+ * @param modelId - The model identifier associated with the tool call
+ * @param execute - An async function that performs the tool operation; its resolved value is returned
+ * @returns The resolved value from `execute`
+ * @throws Any error thrown by `execute` after emitting a failure tracking event
+ */
+
+export async function trackToolExecution<T>(
+  toolName: string,
+  modelId: string,
+  execute: () => Promise<T>,
+): Promise<T> {
+  const startTime = Date.now();
+  const operationId = generateOperationId('tool');
+
+  try {
+    // Track tool start
+    aiSdk.toolCallStarted({
+      model_id: modelId,
+      operation_id: operationId,
+      tool_name: toolName,
+      tool_type: 'custom',
+    });
+
+    const result = await execute();
+
+    // Track successful completion
+    aiSdk.toolCallCompleted({
+      model_id: modelId,
+      operation_id: operationId,
+      tool_name: toolName,
+      tool_type: 'custom',
+      result_status: 'success',
+      execution_time_ms: Date.now() - startTime,
+      output_size: JSON.stringify(result).length,
+    });
+
+    return result;
+  } catch (error: any) {
+    // Track failure
+    aiSdk.toolCallFailed({
+      model_id: modelId,
+      operation_id: operationId,
+      tool_name: toolName,
+      tool_type: 'custom',
+      error_message: error.message,
+      execution_time_ms: Date.now() - startTime,
+    });
+
+    throw error;
+  }
+}
+
+// =============================================================================
+// Pattern 4: Streaming with Chunk Sampling
+// =============================================================================
+
+export async function trackStreamingCompletion(_messages: any[]) {
+  const operationId = generateOperationId('stream');
+  const startTime = Date.now();
+  let chunkCount = 0;
+  let firstChunkTime: number | undefined;
+
+  try {
+    // Track stream start
+    aiSdk.streamStarted({
+      model_id: 'claude-3-5-sonnet',
+      operation_id: operationId,
+      stream_type: 'text',
+    });
+
+    // Placeholder - replace with actual Chat.stream when AI SDK is installed
+    const result: any = { textStream: null };
+
+    // Process stream
+    if (result.textStream) {
+      const reader = result.textStream.getReader();
+
+      while (true) {
+        const { done } = await reader.read();
+        if (done) break;
+
+        chunkCount++;
+
+        // Record first chunk time
+        firstChunkTime ??= Date.now();
+
+        // Sample every 10th chunk to avoid overwhelming analytics
+        if (chunkCount % 10 === 0) {
+          aiSdk.streamChunkReceived({
+            model_id: 'claude-3-5-sonnet',
+            operation_id: operationId,
+            stream_type: 'text',
+            chunk_index: chunkCount,
+          });
+        }
+      }
+    }
+
+    const duration = Date.now() - startTime;
+
+    // Track successful completion
+    aiSdk.streamCompleted({
+      model_id: 'claude-3-5-sonnet',
+      operation_id: operationId,
+      stream_type: 'text',
+      chunk_count: chunkCount,
+      stream_duration_ms: duration,
+      time_to_first_chunk_ms: firstChunkTime ? firstChunkTime - startTime : undefined,
+      chunks_per_second: duration > 0 ? (chunkCount / duration) * 1000 : undefined,
+    });
+
+    return result;
+  } catch (error: any) {
+    aiSdk.streamFailed({
+      model_id: 'claude-3-5-sonnet',
+      operation_id: operationId,
+      stream_type: 'text',
+      error_message: error.message,
+      chunk_count: chunkCount,
+      stream_duration_ms: Date.now() - startTime,
+    });
+
+    throw error;
+  }
+}
+
+// =============================================================================
+// Pattern 5: E-commerce Chatbot Intent Detection
+/**
+ * Handles an incoming chatbot message, routes it by detected intent, emits analytics events, and returns the appropriate response payload.
+ *
+ * @param message - The raw user message to analyze and act on
+ * @param conversationId - Identifier for the chat conversation used in analytics events
+ * @param userId - Identifier for the user sending the message
+ * @returns An object describing the action taken:
+ * - `{ type: 'product-recommendations', products }` when a product search is detected
+ * - `{ type: 'cart-update', cart }` when cart management is detected
+ * - `{ type: 'order-status', order }` when order tracking is detected
+ * - `{ type: 'general', response: string }` for fallback/general responses
+ */
+
+export async function handleChatbotMessage(
+  message: string,
+  conversationId: string,
+  userId: string,
+) {
+  // Track intent detection (auto-detected from message)
+  aiSdk.chatbotIntentDetected({
+    model_id: 'gpt-4',
+    conversation_id: conversationId,
+    user_id: userId,
+    message,
+  });
+
+  // Process based on detected intent
+  const intent = message.toLowerCase();
+
+  if (intent.includes('laptop') || intent.includes('search')) {
+    // Product search scenario
+    const products = await searchProducts(message);
+
+    // Track product recommendations
+    aiSdk.chatbotProductRecommended({
+      model_id: 'gpt-4',
+      conversation_id: conversationId,
+      user_id: userId,
+      product_ids: products.map(p => p.id),
+      product_count: products.length,
+      intent_detected: 'product-search',
+    });
+
+    return { type: 'product-recommendations', products };
+  } else if (intent.includes('cart') || intent.includes('add')) {
+    // Cart assistance scenario
+    const cart = await getCart(userId);
+
+    aiSdk.chatbotCartAssisted({
+      model_id: 'gpt-4',
+      conversation_id: conversationId,
+      user_id: userId,
+      cart_id: cart.id,
+      cart_value: cart.total,
+      product_count: cart.items.length,
+      product_ids: cart.items.map(i => i.productId),
+      intent_detected: 'cart-management',
+    });
+
+    return { type: 'cart-update', cart };
+  } else if (intent.includes('order') || intent.includes('track')) {
+    // Order tracking scenario
+    const orders = await getUserOrders(userId);
+    const latestOrder = orders[0];
+
+    if (latestOrder) {
+      aiSdk.chatbotOrderAssisted({
+        model_id: 'gpt-4',
+        conversation_id: conversationId,
+        user_id: userId,
+        order_id: latestOrder.id,
+        intent_detected: 'order-tracking',
+      });
+
+      return { type: 'order-status', order: latestOrder };
+    }
+  }
+
+  return { type: 'general', response: 'How can I help you?' };
+}
+
+// =============================================================================
+// Pattern 6: Cost Tracking with Budget Monitoring
+// =============================================================================
+
+export class CostTracker {
+  private totalCost = 0;
+  private budget: number;
+
+  constructor(dailyBudget: number) {
+    this.budget = dailyBudget;
+  }
+
+  async trackCompletion(
+    modelId: string,
+    usage: { input_tokens: number; output_tokens: number },
+    pricing: { input_price_per_1k: number; output_price_per_1k: number },
+  ) {
+    // Calculate cost
+    const cost = calculateCost(usage, pricing);
+    this.totalCost += cost;
+
+    // Track cost
+    trackAISDK({
+      name: AI_SDK_EVENTS.TOKEN_USAGE_TRACKED,
+      category: 'ai-sdk',
+      properties: {
+        model_id: modelId,
+        input_tokens: usage.input_tokens,
+        output_tokens: usage.output_tokens,
+        total_tokens: usage.input_tokens + usage.output_tokens,
+        cost,
+        cost_currency: 'USD',
+        cost_breakdown: {
+          input_cost: (usage.input_tokens / 1000) * pricing.input_price_per_1k,
+          output_cost: (usage.output_tokens / 1000) * pricing.output_price_per_1k,
+        },
+      },
+    });
+
+    // Check budget
+    if (this.totalCost > this.budget) {
+      logWarn(`Budget exceeded! Total: $${this.totalCost}, Budget: $${this.budget}`, {
+        totalCost: this.totalCost,
+        budget: this.budget,
+      });
+    }
+
+    return cost;
+  }
+
+  getRemainingBudget(): number {
+    return Math.max(0, this.budget - this.totalCost);
+  }
+}
+
+// =============================================================================
+// Pattern 7: React Component with Tracking
+/**
+ * React component that wraps a chat UI with analytics hooks to emit tracking events for user messages, assistant responses, and chat errors.
+ *
+ * @param userId - The identifier of the current user used in emitted tracking events
+ * @returns A React element representing the chat interface (placeholder implementation)
+ */
+
+export function ChatInterfaceWithTracking({ userId }: { userId: string }) {
+  // Example component - conversationId would typically come from props or context
+  const conversationId = useId();
+
+  const chat = useChat({
+    api: '/api/chat',
+    id: conversationId,
+
+    onFinish: (message: { content: string }) => {
+      // Track assistant message
+      aiSdk.chatMessageReceived({
+        model_id: 'claude-3-5-sonnet',
+        conversation_id: conversationId,
+        user_id: userId,
+        message_role: 'assistant',
+        message_length: message.content.length,
+        finish_reason: 'stop',
+      });
+    },
+
+    onError: (error: Error) => {
+      // Track error
+      agentExecutionFailed({
+        model_id: 'claude-3-5-sonnet',
+        conversation_id: conversationId,
+        error_message: error.message,
+        completion_type: 'chat',
+      });
+    },
+  });
+
+  // In a real implementation, you would use chat.send() to send messages
+  // Void expression to satisfy unused variable check
+  void chat;
+
+  return null; // Component implementation
+}
+
+// =============================================================================
+// Pattern 8: Multi-Step Agent with Step Tracking
+/**
+ * Execute a multi-step agent prompt while emitting analytics events for start, per-step progress, completion, and failures.
+ *
+ * Emits lifecycle events that record operation id, step counts, duration, stop reason, and token usage.
+ *
+ * @param agent - The Agent instance to run the multi-step generation with
+ * @param prompt - The prompt string to pass to the agent
+ * @returns The agent's generation result object (may include `steps` and `usage` information)
+ * @throws Propagates any error thrown by the agent after emitting a failure analytics event
+ */
+
+export async function trackMultiStepAgent(agent: Agent, prompt: string) {
+  const operationId = generateOperationId('multi-step');
+  const startTime = Date.now();
+  let stepCount = 0;
+
+  try {
+    trackAISDK({
+      name: AI_SDK_EVENTS.MULTI_STEP_STARTED,
+      category: 'ai-sdk',
+      properties: {
+        model_id: 'claude-3-5-sonnet',
+        operation_id: operationId,
+        step_count: 0,
+      },
+    });
+
+    const result = await agent.generate({ prompt });
+
+    stepCount = result.steps?.length ?? 0;
+
+    // Track each step progression
+    result.steps?.forEach((_step: any, index: number) => {
+      trackAISDK({
+        name: AI_SDK_EVENTS.MULTI_STEP_PROGRESSED,
+        category: 'ai-sdk',
+        properties: {
+          model_id: 'claude-3-5-sonnet',
+          operation_id: operationId,
+          step_count: index + 1,
+        },
+      });
+    });
+
+    trackAISDK({
+      name: AI_SDK_EVENTS.MULTI_STEP_COMPLETED,
+      category: 'ai-sdk',
+      properties: {
+        model_id: 'claude-3-5-sonnet',
+        operation_id: operationId,
+        step_count: stepCount,
+        total_duration_ms: Date.now() - startTime,
+        stop_reason: 'condition-met',
+        input_tokens: result.usage?.inputTokens,
+        output_tokens: result.usage?.outputTokens,
+      },
+    });
+
+    return result;
+  } catch (error: any) {
+    agentExecutionFailed({
+      model_id: 'claude-3-5-sonnet',
+      operation_id: operationId,
+      error_message: error.message,
+      completion_type: 'multi-step',
+      step_count: stepCount,
+      total_duration_ms: Date.now() - startTime,
+    });
+
+    throw error;
+  }
+}
+
+// =============================================================================
+// Helper Functions (Mocked for Examples)
+// =============================================================================
+
+async function searchProducts(_query: string): Promise<{ id: string }[]> {
+  return [{ id: 'prod_1' }, { id: 'prod_2' }];
+}
+
+async function getCart(_userId: string): Promise<{
+  id: string;
+  total: number;
+  items: { productId: string }[];
+}> {
+  return {
+    id: 'cart_123',
+    total: 299.99,
+    items: [{ productId: 'prod_1' }],
+  };
+}
+
+async function getUserOrders(_userId: string): Promise<{ id: string }[]> {
+  return [{ id: 'order_123' }];
+}