@od-oneapp/analytics 2026.1.1301

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

@@ -0,0 +1,468 @@
+/**
+ * @fileoverview Utility functions for AI event tracking
+ * Utility functions for AI event tracking
+ */
+
+import type { BaseAIProperties, ModelConfigProperties, TokenUsageProperties } from './types';
+
+/**
+ * Remove undefined and null values from an object
+ */
+export function cleanProperties<T extends Record<string, any>>(props: T): Partial<T> {
+  const cleaned: Partial<T> = {};
+
+  for (const key in props) {
+    if (!Object.prototype.hasOwnProperty.call(props, key)) continue;
+    const value = props[key];
+    if (value !== undefined && value !== null) {
+      cleaned[key] = value;
+    }
+  }
+
+  return cleaned;
+}
+
+/**
+ * Validate that required properties are present
+ */
+export function validateRequiredProperties<T extends Record<string, any>>(
+  properties: T,
+  required: (keyof T)[],
+): void {
+  const missing: string[] = [];
+
+  for (const key of required) {
+    if (properties[key] === undefined || properties[key] === null) {
+      missing.push(String(key));
+    }
+  }
+
+  if (missing.length > 0) {
+    throw new Error(`Missing required properties: ${missing.join(', ')}`);
+  }
+}
+
+/**
+ * Normalize base AI operation properties
+ */
+export function normalizeBaseProperties(props: BaseAIProperties): BaseAIProperties {
+  return {
+    model_id: props.model_id,
+    agent_id: props.agent_id,
+    agent_name: props.agent_name,
+    conversation_id: props.conversation_id,
+    session_id: props.session_id,
+    user_id: props.user_id,
+    operation_id: props.operation_id,
+    model_provider: props.model_provider,
+  };
+}
+
+/**
+ * Normalize token usage properties
+ */
+export function normalizeTokenUsage(props: TokenUsageProperties): TokenUsageProperties {
+  const normalized: TokenUsageProperties = {};
+
+  if (props.input_tokens !== undefined) {
+    normalized.input_tokens = Math.max(0, props.input_tokens);
+  }
+
+  if (props.output_tokens !== undefined) {
+    normalized.output_tokens = Math.max(0, props.output_tokens);
+  }
+
+  if (props.total_tokens !== undefined) {
+    normalized.total_tokens = Math.max(0, props.total_tokens);
+  } else if (normalized.input_tokens !== undefined && normalized.output_tokens !== undefined) {
+    // Calculate total from already-normalized values (clamped to 0)
+    normalized.total_tokens = normalized.input_tokens + normalized.output_tokens;
+  }
+
+  if (props.cost !== undefined) {
+    normalized.cost = Math.max(0, props.cost);
+    normalized.cost_currency = props.cost_currency ?? 'USD';
+  }
+
+  return normalized;
+}
+
+/**
+ * Normalize model configuration properties
+ */
+export function normalizeModelConfig(props: ModelConfigProperties): ModelConfigProperties {
+  const normalized: ModelConfigProperties = {};
+
+  if (props.temperature !== undefined) {
+    normalized.temperature = Math.max(0, Math.min(2, props.temperature));
+  }
+
+  if (props.max_tokens !== undefined) {
+    normalized.max_tokens = Math.max(1, props.max_tokens);
+  }
+
+  if (props.max_output_tokens !== undefined) {
+    normalized.max_output_tokens = Math.max(1, props.max_output_tokens);
+  }
+
+  if (props.top_p !== undefined) {
+    normalized.top_p = Math.max(0, Math.min(1, props.top_p));
+  }
+
+  if (props.frequency_penalty !== undefined) {
+    normalized.frequency_penalty = Math.max(-2, Math.min(2, props.frequency_penalty));
+  }
+
+  if (props.presence_penalty !== undefined) {
+    normalized.presence_penalty = Math.max(-2, Math.min(2, props.presence_penalty));
+  }
+
+  if (props.seed !== undefined) {
+    normalized.seed = props.seed;
+  }
+
+  if (props.stop_sequences !== undefined) {
+    normalized.stop_sequences = props.stop_sequences;
+  }
+
+  return normalized;
+}
+
+/**
+ * Calculate cost based on token usage and model pricing
+ */
+export function calculateCost(
+  usage: TokenUsageProperties,
+  pricing: {
+    input_price_per_1k?: number;
+    output_price_per_1k?: number;
+  },
+): number {
+  let cost = 0;
+
+  if (usage.input_tokens && pricing.input_price_per_1k) {
+    cost += (usage.input_tokens / 1000) * pricing.input_price_per_1k;
+  }
+
+  if (usage.output_tokens && pricing.output_price_per_1k) {
+    cost += (usage.output_tokens / 1000) * pricing.output_price_per_1k;
+  }
+
+  return cost;
+}
+
+/**
+ * Extract model provider from model ID
+ */
+export function extractModelProvider(
+  modelId: string,
+): 'anthropic' | 'openai' | 'google' | 'perplexity' | 'other' {
+  const lowercaseId = modelId.toLowerCase();
+
+  if (lowercaseId.includes('claude') || lowercaseId.includes('anthropic')) {
+    return 'anthropic';
+  }
+
+  if (lowercaseId.includes('gpt') || lowercaseId.includes('openai')) {
+    return 'openai';
+  }
+
+  if (lowercaseId.includes('gemini') || lowercaseId.includes('google')) {
+    return 'google';
+  }
+
+  if (lowercaseId.includes('pplx') || lowercaseId.includes('perplexity')) {
+    return 'perplexity';
+  }
+
+  return 'other';
+}
+
+/**
+ * Generate a unique operation ID
+ */
+export function generateOperationId(prefix = 'ai'): string {
+  const timestamp = Date.now();
+  const random = Math.random().toString(36).slice(2, 9);
+  return `${prefix}_${timestamp}_${random}`;
+}
+
+/**
+ * Sanitize error message for tracking
+ */
+export function sanitizeErrorMessage(error: Error | string): string {
+  const message = typeof error === 'string' ? error : error.message;
+
+  // Remove potentially sensitive information
+  // Matches: "API key sk-xxx", "api_key: xxx", "api-keys=xxx", etc.
+  return message
+    .replaceAll(/api[\s_\-]?keys?[\s:=]+[\w-]+/gi, 'api_key=***')
+    .replaceAll(/tokens?[\s:=]+[\w-]+/gi, 'token=***')
+    .replaceAll(/passwords?[\s:=]+[\w-]+/gi, 'password=***')
+    .replaceAll(/secrets?[\s:=]+[\w-]+/gi, 'secret=***')
+    .slice(0, 500); // Limit length
+}
+
+/**
+ * Calculate metrics for completion events
+ */
+export function calculateCompletionMetrics(
+  startTime: number,
+  endTime: number,
+  tokenUsage?: TokenUsageProperties,
+): {
+  duration_ms: number;
+  tokens_per_second?: number;
+} {
+  const duration_ms = endTime - startTime;
+  const metrics: { duration_ms: number; tokens_per_second?: number } = {
+    duration_ms,
+  };
+
+  if (tokenUsage?.total_tokens && duration_ms > 0) {
+    metrics.tokens_per_second = (tokenUsage.total_tokens / duration_ms) * 1000;
+  }
+
+  return metrics;
+}
+
+/**
+ * Detect intent from chat message
+ */
+export function detectIntent(
+  message: string,
+):
+  | 'product-search'
+  | 'product-inquiry'
+  | 'product-comparison'
+  | 'cart-management'
+  | 'checkout-help'
+  | 'order-tracking'
+  | 'returns-exchanges'
+  | 'support-question'
+  | 'general-inquiry'
+  | 'complaint'
+  | 'feedback' {
+  const lowercase = message.toLowerCase();
+
+  // Order matters: more specific patterns (like order-tracking, complaint) should come
+  // before patterns with broad keywords (like product-comparison with 'or')
+  const intentPatterns = {
+    // Put order-tracking early since "order" contains "or" which could match comparison
+    'order-tracking': [
+      'track',
+      'order status',
+      'shipping',
+      'delivery',
+      'where is my',
+      'when will',
+      'my order',
+    ],
+    // Put complaint before comparison since "disappointed" could match patterns in other intents
+    complaint: ['disappointed', 'angry', 'frustrated', 'terrible', 'worst', 'complain', 'unhappy'],
+    'returns-exchanges': ['return', 'refund', 'exchange', 'cancel order', 'send back'],
+    'product-search': [
+      'looking for',
+      'search for',
+      'find',
+      'show me',
+      'need',
+      'want to buy',
+      'shopping for',
+    ],
+    'product-inquiry': [
+      'tell me about',
+      'details',
+      'specs',
+      'features',
+      'price',
+      'available',
+      'in stock',
+    ],
+    'product-comparison': [
+      'compare',
+      'difference between',
+      'which is better',
+      'vs',
+      ' or ', // Use space-bounded 'or' to avoid matching 'order', 'for', etc.
+      'better than',
+    ],
+    'cart-management': ['add to cart', 'remove from cart', 'cart', 'shopping bag', 'my items'],
+    'checkout-help': ['checkout', 'payment', 'pay', 'purchase', 'buy now', 'complete order'],
+    feedback: ['review', 'feedback', 'rate', 'experience', 'satisfied'],
+  };
+
+  for (const [intent, patterns] of Object.entries(intentPatterns)) {
+    if (patterns.some(pattern => lowercase.includes(pattern))) {
+      return intent as any;
+    }
+  }
+
+  return 'general-inquiry';
+}
+
+/**
+ * Detect sentiment from message
+ */
+export function detectSentiment(message: string): 'positive' | 'negative' | 'neutral' | 'mixed' {
+  const lowercase = message.toLowerCase();
+
+  const positiveWords = [
+    'great',
+    'love',
+    'excellent',
+    'perfect',
+    'amazing',
+    'wonderful',
+    'awesome',
+    'fantastic',
+    'helpful',
+    'thank',
+  ];
+  const negativeWords = [
+    'bad',
+    'terrible',
+    'awful',
+    'disappointed',
+    'angry',
+    'frustrated',
+    'annoyed',
+    'useless',
+    'worst',
+    'hate',
+  ];
+
+  const positiveCount = positiveWords.filter(word => lowercase.includes(word)).length;
+  const negativeCount = negativeWords.filter(word => lowercase.includes(word)).length;
+
+  if (positiveCount > 0 && negativeCount > 0) {
+    return 'mixed';
+  }
+
+  if (positiveCount > negativeCount) {
+    return 'positive';
+  }
+
+  if (negativeCount > positiveCount) {
+    return 'negative';
+  }
+
+  return 'neutral';
+}
+
+/**
+ * Truncate array to max length for tracking
+ */
+export function truncateArray<T>(arr: T[], maxLength = 10): T[] {
+  return arr.slice(0, maxLength);
+}
+
+/**
+ * Safe JSON stringify for complex objects
+ */
+export function safeStringify(obj?: unknown, maxLength = 1000): string {
+  try {
+    if (obj === undefined) return '{}';
+    const str = JSON.stringify(obj);
+    return str.length > maxLength ? `${str.slice(0, Math.max(0, maxLength))}...` : str;
+  } catch {
+    return '[Unable to stringify]';
+  }
+}
+
+/**
+ * Calculate conversation quality score
+ */
+export function calculateQualityScore(metrics: {
+  message_count: number;
+  avg_response_time_ms?: number;
+  misunderstanding_count?: number;
+  clarification_count?: number;
+  satisfaction_score?: number;
+}): number {
+  let score = 100;
+
+  // Penalize for too few messages (abandoned)
+  if (metrics.message_count < 3) {
+    score -= 20;
+  }
+
+  // Penalize for slow responses
+  if (metrics.avg_response_time_ms && metrics.avg_response_time_ms > 3000) {
+    score -= 10;
+  }
+
+  // Penalize for misunderstandings
+  if (metrics.misunderstanding_count) {
+    score -= metrics.misunderstanding_count * 5;
+  }
+
+  // Penalize for excessive clarifications
+  if (metrics.clarification_count && metrics.clarification_count > 2) {
+    score -= (metrics.clarification_count - 2) * 3;
+  }
+
+  // Boost for high satisfaction
+  if (metrics.satisfaction_score && metrics.satisfaction_score >= 4) {
+    score += 10;
+  }
+
+  return Math.max(0, Math.min(100, score));
+}
+
+/**
+ * Detect if message needs clarification
+ */
+export function needsClarification(message: string): boolean {
+  const lowercase = message.toLowerCase();
+
+  const ambiguousPatterns = [
+    'it',
+    'that one',
+    'this',
+    'them',
+    'those',
+    'something like',
+    'kind of',
+    'sort of',
+    'maybe',
+    'not sure',
+  ];
+
+  return ambiguousPatterns.some(pattern => lowercase.includes(pattern));
+}
+
+/**
+ * Extract product mentions from message
+ */
+export function extractProductMentions(message: string): string[] {
+  const mentions: string[] = [];
+
+  // Common product categories
+  const categories = [
+    'laptop',
+    'phone',
+    'tablet',
+    'watch',
+    'headphones',
+    'shoes',
+    'shirt',
+    'pants',
+    'dress',
+    'jacket',
+  ];
+
+  const lowercase = message.toLowerCase();
+  for (const category of categories) {
+    if (lowercase.includes(category)) {
+      mentions.push(category);
+    }
+  }
+
+  return mentions;
+}
+
+/**
+ * Alias for detectIntent for chatbot-specific contexts
+ */
+export const detectChatbotIntent = detectIntent;

package/src/shared/emitters/ecommerce/events/cart-checkout.ts

@@ -0,0 +1,106 @@
+/**
+ * @fileoverview Cart and checkout-related ecommerce events
+ * Cart and checkout-related ecommerce events
+ */
+
+import { trackEcommerce } from '../track-ecommerce';
+import {
+  type CartAbandonmentProperties,
+  type CartProperties,
+  type CartUpdateProperties,
+  type CheckoutProgressProperties,
+  ECOMMERCE_EVENTS,
+  type EcommerceEventSpec,
+} from '../types';
+import {
+  cleanProperties,
+  normalizeProductProperties,
+  normalizeProducts,
+  validateRequiredProperties,
+} from '../utils';
+
+import type { EmitterOptions, EmitterTrackPayload } from '../../emitter-types';
+
+/**
+ * Track cart updates (add, remove, update) with a single event
+ */
+export function cartUpdated(
+  properties: CartUpdateProperties,
+  options?: EmitterOptions,
+): EmitterTrackPayload {
+  const { cart_id, action, cart_total, product, quantity_change } = properties;
+  const normalizedProduct = normalizeProductProperties(product);
+
+  validateRequiredProperties(properties, ['action']);
+  validateRequiredProperties(normalizedProduct, ['product_id']);
+
+  const eventSpec: EcommerceEventSpec = {
+    name: ECOMMERCE_EVENTS.CART_UPDATED,
+    category: 'ecommerce',
+    properties: cleanProperties({
+      action,
+      ...normalizedProduct,
+      cart_id,
+      cart_total,
+      quantity_change,
+    }),
+    requiredProperties: ['action', 'product_id'],
+  };
+
+  return trackEcommerce(eventSpec, options);
+}
+
+/**
+ * Track when a user views their shopping cart
+ */
+export function cartViewed(properties: CartProperties): EcommerceEventSpec<CartProperties> {
+  const normalizedProps: CartProperties = {
+    cart_id: properties.cart_id,
+    products: properties.products ? normalizeProducts(properties.products) : undefined,
+  };
+
+  return {
+    name: ECOMMERCE_EVENTS.CART_VIEWED,
+    category: 'ecommerce',
+    properties: cleanProperties(normalizedProps),
+    requiredProperties: [],
+  };
+}
+
+/**
+ * Track when a cart is abandoned
+ */
+export function cartAbandoned(properties: CartAbandonmentProperties): EcommerceEventSpec {
+  validateRequiredProperties(properties, ['cart_id', 'cart_value']);
+
+  const normalizedProps = {
+    ...properties,
+    products: normalizeProducts(properties.products),
+  };
+
+  return {
+    name: ECOMMERCE_EVENTS.CART_ABANDONED,
+    category: 'ecommerce',
+    properties: cleanProperties(normalizedProps),
+    requiredProperties: ['cart_id', 'cart_value'],
+  };
+}
+
+/**
+ * Track checkout progression with a single event
+ */
+export function checkoutProgressed(properties: CheckoutProgressProperties): EcommerceEventSpec {
+  validateRequiredProperties(properties, ['step', 'step_name', 'action']);
+
+  const normalizedProps = {
+    ...properties,
+    products: properties.products ? normalizeProducts(properties.products) : undefined,
+  };
+
+  return {
+    name: ECOMMERCE_EVENTS.CHECKOUT_PROGRESSED,
+    category: 'ecommerce',
+    properties: cleanProperties(normalizedProps),
+    requiredProperties: ['step', 'step_name', 'action'],
+  };
+}

package/src/shared/emitters/ecommerce/events/coupon.ts

@@ -0,0 +1,49 @@
+/**
+ * @fileoverview Coupon-related ecommerce events
+ * Coupon-related ecommerce events
+ */
+
+import { type CouponProperties, ECOMMERCE_EVENTS, type EcommerceEventSpec } from '../types';
+import { cleanProperties } from '../utils';
+
+/**
+ * Track when a coupon is successfully applied
+ */
+export function couponApplied(properties: CouponProperties): EcommerceEventSpec<CouponProperties> {
+  const normalizedProps: CouponProperties = {
+    cart_id: properties.cart_id,
+    coupon_id: properties.coupon_id,
+    order_id: properties.order_id,
+    coupon_name: properties.coupon_name,
+    discount: properties.discount,
+    reason: properties.reason,
+  };
+
+  return {
+    name: ECOMMERCE_EVENTS.COUPON_APPLIED,
+    category: 'ecommerce',
+    properties: cleanProperties(normalizedProps),
+    requiredProperties: [],
+  };
+}
+
+/**
+ * Track when a coupon is removed
+ */
+export function couponRemoved(properties: CouponProperties): EcommerceEventSpec<CouponProperties> {
+  const normalizedProps: CouponProperties = {
+    cart_id: properties.cart_id,
+    coupon_id: properties.coupon_id,
+    order_id: properties.order_id,
+    coupon_name: properties.coupon_name,
+    discount: properties.discount,
+    reason: properties.reason,
+  };
+
+  return {
+    name: ECOMMERCE_EVENTS.COUPON_REMOVED,
+    category: 'ecommerce',
+    properties: cleanProperties(normalizedProps),
+    requiredProperties: [],
+  };
+}

package/src/shared/emitters/ecommerce/events/engagement.ts

@@ -0,0 +1,61 @@
+/**
+ * @fileoverview Customer engagement events for ecommerce
+ * Customer engagement events for ecommerce
+ * Track user interactions that indicate interest but aren't direct purchases
+ */
+
+import { type BaseProductProperties, ECOMMERCE_EVENTS, type EcommerceEventSpec } from '../types';
+import { cleanProperties, normalizeProductProperties, validateRequiredProperties } from '../utils';
+
+/**
+ * Track when a user sets a price alert for a product
+ */
+export function priceAlertSet(
+  properties: BaseProductProperties & {
+    threshold_price: number;
+    notification_method?: 'email' | 'sms' | 'push';
+    currency?: string;
+  },
+): EcommerceEventSpec {
+  const { currency, notification_method, threshold_price, ...productProps } = properties;
+  const normalizedProduct = normalizeProductProperties(productProps);
+  validateRequiredProperties(normalizedProduct, ['product_id']);
+  validateRequiredProperties({ threshold_price }, ['threshold_price']);
+
+  return {
+    name: ECOMMERCE_EVENTS.PRICE_ALERT_SET,
+    category: 'ecommerce',
+    properties: cleanProperties({
+      ...normalizedProduct,
+      action_type: 'price_alert',
+      currency,
+      notification_method,
+      threshold_price,
+    }),
+    requiredProperties: ['product_id', 'threshold_price'],
+  };
+}
+
+/**
+ * Track when a user requests notification for out-of-stock items
+ */
+export function backInStockRequested(
+  properties: BaseProductProperties & {
+    notification_method?: 'email' | 'sms' | 'push';
+  },
+): EcommerceEventSpec {
+  const { notification_method, ...productProps } = properties;
+  const normalizedProduct = normalizeProductProperties(productProps);
+  validateRequiredProperties(normalizedProduct, ['product_id']);
+
+  return {
+    name: ECOMMERCE_EVENTS.BACK_IN_STOCK_REQUESTED,
+    category: 'ecommerce',
+    properties: cleanProperties({
+      ...normalizedProduct,
+      action_type: 'back_in_stock',
+      notification_method,
+    }),
+    requiredProperties: ['product_id'],
+  };
+}