@operor/analytics 0.1.0

package/src/InMemoryAnalyticsStore.ts

@@ -0,0 +1,250 @@
+import type {
+  AnalyticsStore,
+  AnalyticsEvent,
+  AnalyticsSummary,
+  MessageVolumeData,
+  AgentStatsData,
+  CustomerStatsData,
+  KbStatsData,
+  TimeRange,
+} from './types.js';
+
+const SESSION_GAP_MS = 30 * 60 * 1000;
+
+/**
+ * In-memory analytics store for testing and development.
+ */
+export class InMemoryAnalyticsStore implements AnalyticsStore {
+  private events: AnalyticsEvent[] = [];
+  private conversations = new Map<string, {
+    id: string;
+    customerId: string;
+    customerPhone: string;
+    channel: string;
+    agentId: string;
+    startedAt: number;
+    endedAt: number;
+    messageCount: number;
+    toolCallCount: number;
+    totalCost: number;
+  }>();
+
+  async initialize(): Promise<void> {}
+  async close(): Promise<void> {}
+
+  async recordMessageEvent(event: AnalyticsEvent): Promise<void> {
+    this.events.push({ ...event });
+  }
+
+  async getOrCreateConversation(
+    customerPhone: string,
+    channel: string,
+    agentName: string,
+  ): Promise<string> {
+    const now = Date.now();
+    const cutoff = now - SESSION_GAP_MS;
+
+    for (const conv of this.conversations.values()) {
+      if (
+        conv.customerPhone === customerPhone &&
+        conv.channel === channel &&
+        conv.agentId === agentName &&
+        conv.endedAt > cutoff
+      ) {
+        return conv.id;
+      }
+    }
+
+    const id = crypto.randomUUID();
+    this.conversations.set(id, {
+      id,
+      customerId: '',
+      customerPhone,
+      channel,
+      agentId: agentName,
+      startedAt: now,
+      endedAt: now,
+      messageCount: 0,
+      toolCallCount: 0,
+      totalCost: 0,
+    });
+    return id;
+  }
+
+  async updateConversationStats(
+    conversationId: string,
+    event: AnalyticsEvent,
+  ): Promise<void> {
+    const conv = this.conversations.get(conversationId);
+    if (!conv) return;
+    if (!conv.customerId) conv.customerId = event.customerId;
+    conv.endedAt = event.timestamp;
+    conv.messageCount += 1;
+    conv.toolCallCount += event.toolCallsCount;
+    conv.totalCost += event.llmCost;
+  }
+
+  private filter(range?: TimeRange): AnalyticsEvent[] {
+    if (!range) return this.events;
+    return this.events.filter(e => e.timestamp >= range.from && e.timestamp <= range.to);
+  }
+
+  async getSummary(range?: TimeRange): Promise<AnalyticsSummary> {
+    const events = this.filter(range);
+    const total = events.length;
+    if (total === 0) {
+      return {
+        totalMessages: 0, avgPerDay: 0, peakDay: null,
+        kbAnsweredPct: 0, llmFallbackPct: 0, noAnswerPct: 0,
+        avgResponseTime: 0, faqHitRate: 0, uniqueCustomers: 0,
+        newCustomers: 0, returningCustomers: 0, agentBreakdown: {},
+        pendingReviews: 0,
+      };
+    }
+
+    const customers = new Set(events.map(e => e.customerPhone));
+    const newCust = events.filter(e => e.isNewCustomer).length;
+    const faqHits = events.filter(e => e.kbIsFaqMatch).length;
+    const kbAnswered = events.filter(e => e.kbTopScore >= 0.7).length;
+    const noAnswer = events.filter(e => e.kbTopScore < 0.3).length;
+    const avgResp = events.reduce((s, e) => s + e.responseTimeMs, 0) / total;
+
+    // Peak day
+    const dayCounts = new Map<string, number>();
+    for (const e of events) {
+      const day = new Date(e.timestamp).toISOString().slice(0, 10);
+      dayCounts.set(day, (dayCounts.get(day) || 0) + 1);
+    }
+    let peakDay: string | null = null;
+    let peakCount = 0;
+    for (const [day, cnt] of dayCounts) {
+      if (cnt > peakCount) { peakDay = day; peakCount = cnt; }
+    }
+
+    // Agent breakdown
+    const agentBreakdown: Record<string, number> = {};
+    for (const e of events) {
+      agentBreakdown[e.agentName] = (agentBreakdown[e.agentName] || 0) + 1;
+    }
+
+    const days = dayCounts.size || 1;
+
+    return {
+      totalMessages: total,
+      avgPerDay: total / days,
+      peakDay,
+      kbAnsweredPct: (kbAnswered / total) * 100,
+      llmFallbackPct: ((total - kbAnswered) / total) * 100,
+      noAnswerPct: (noAnswer / total) * 100,
+      avgResponseTime: avgResp,
+      faqHitRate: (faqHits / total) * 100,
+      uniqueCustomers: customers.size,
+      newCustomers: newCust,
+      returningCustomers: customers.size - newCust,
+      agentBreakdown,
+      pendingReviews: 0,
+    };
+  }
+
+  async getMessageVolume(range?: TimeRange, groupBy: 'day' | 'hour' = 'day'): Promise<MessageVolumeData[]> {
+    const events = this.filter(range);
+    const buckets = new Map<string, number>();
+    for (const e of events) {
+      const d = new Date(e.timestamp);
+      const key = groupBy === 'hour'
+        ? d.toISOString().slice(0, 13) + ':00'
+        : d.toISOString().slice(0, 10);
+      buckets.set(key, (buckets.get(key) || 0) + 1);
+    }
+    return [...buckets.entries()]
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([date, count]) => ({ date, count }));
+  }
+
+  async getAgentStats(range?: TimeRange): Promise<AgentStatsData[]> {
+    const events = this.filter(range);
+    const map = new Map<string, { count: number; respTime: number; conf: number; esc: number; tools: number }>();
+    for (const e of events) {
+      const s = map.get(e.agentName) || { count: 0, respTime: 0, conf: 0, esc: 0, tools: 0 };
+      s.count++;
+      s.respTime += e.responseTimeMs;
+      s.conf += e.intentConfidence;
+      s.esc += e.wasEscalated ? 1 : 0;
+      s.tools += e.toolCallsCount;
+      map.set(e.agentName, s);
+    }
+    return [...map.entries()].map(([name, s]) => ({
+      agentName: name,
+      messageCount: s.count,
+      avgResponseTimeMs: s.count > 0 ? s.respTime / s.count : 0,
+      avgConfidence: s.count > 0 ? s.conf / s.count : 0,
+      escalationCount: s.esc,
+      toolCallCount: s.tools,
+    }));
+  }
+
+  async getCustomerStats(range?: TimeRange, limit = 50): Promise<CustomerStatsData[]> {
+    const events = this.filter(range);
+    const map = new Map<string, { id: string; count: number; first: number; last: number; isNew: boolean }>();
+    for (const e of events) {
+      const s = map.get(e.customerPhone) || { id: e.customerId, count: 0, first: e.timestamp, last: e.timestamp, isNew: false };
+      s.count++;
+      if (e.timestamp < s.first) s.first = e.timestamp;
+      if (e.timestamp > s.last) s.last = e.timestamp;
+      if (e.isNewCustomer) s.isNew = true;
+      map.set(e.customerPhone, s);
+    }
+    return [...map.entries()]
+      .sort(([, a], [, b]) => b.count - a.count)
+      .slice(0, limit)
+      .map(([phone, s]) => ({
+        customerId: s.id,
+        customerPhone: phone,
+        messageCount: s.count,
+        firstSeen: s.first,
+        lastSeen: s.last,
+        isNew: s.isNew,
+      }));
+  }
+
+  async getKbStats(range?: TimeRange): Promise<KbStatsData> {
+    const events = this.filter(range);
+    const total = events.length;
+    const faqHits = events.filter(e => e.kbIsFaqMatch).length;
+    const avgScore = total > 0 ? events.reduce((s, e) => s + e.kbTopScore, 0) / total : 0;
+
+    return {
+      totalQueries: total,
+      faqHits,
+      faqHitRate: total > 0 ? (faqHits / total) * 100 : 0,
+      avgTopScore: avgScore,
+      topFaqHits: await this.getTopFaqHits(10, range),
+      topMisses: await this.getTopMisses(10, range),
+    };
+  }
+
+  async getTopFaqHits(limit = 10, range?: TimeRange): Promise<Array<{ intent: string; count: number }>> {
+    const events = this.filter(range).filter(e => e.kbIsFaqMatch);
+    const map = new Map<string, number>();
+    for (const e of events) map.set(e.intent, (map.get(e.intent) || 0) + 1);
+    return [...map.entries()]
+      .sort(([, a], [, b]) => b - a)
+      .slice(0, limit)
+      .map(([intent, count]) => ({ intent, count }));
+  }
+
+  async getTopMisses(limit = 10, range?: TimeRange): Promise<Array<{ intent: string; count: number; avgScore: number }>> {
+    const events = this.filter(range).filter(e => e.kbTopScore < 0.5 && e.kbTopScore > 0);
+    const map = new Map<string, { count: number; totalScore: number }>();
+    for (const e of events) {
+      const s = map.get(e.intent) || { count: 0, totalScore: 0 };
+      s.count++;
+      s.totalScore += e.kbTopScore;
+      map.set(e.intent, s);
+    }
+    return [...map.entries()]
+      .sort(([, a], [, b]) => b.count - a.count)
+      .slice(0, limit)
+      .map(([intent, s]) => ({ intent, count: s.count, avgScore: s.totalScore / s.count }));
+  }
+}