@operor/analytics 0.1.0

package/src/InMemoryAnalyticsStore.test.ts

@@ -0,0 +1,495 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { InMemoryAnalyticsStore } from './InMemoryAnalyticsStore.js';
+import type { AnalyticsEvent, TimeRange } from './types.js';
+
+function makeEvent(overrides: Partial<AnalyticsEvent> = {}): AnalyticsEvent {
+  return {
+    timestamp: Date.now(),
+    channel: 'whatsapp',
+    customerPhone: '+1234567890',
+    customerId: 'cust_1',
+    agentName: 'support',
+    intent: 'order_status',
+    intentConfidence: 0.95,
+    responseTimeMs: 450,
+    llmCost: 0.002,
+    kbTopScore: 0.85,
+    kbIsFaqMatch: true,
+    kbResultCount: 3,
+    toolCallsCount: 0,
+    toolCallsJson: null,
+    messageLength: 30,
+    responseLength: 120,
+    isNewCustomer: false,
+    wasEscalated: false,
+    conversationId: null,
+    promptTokens: 100,
+    completionTokens: 50,
+    ...overrides,
+  };
+}
+
+describe('InMemoryAnalyticsStore', () => {
+  let store: InMemoryAnalyticsStore;
+
+  beforeEach(async () => {
+    store = new InMemoryAnalyticsStore();
+    await store.initialize();
+  });
+
+  // --- CRUD / recordMessageEvent ---
+
+  describe('recordMessageEvent', () => {
+    it('records a single event and reflects in summary', async () => {
+      await store.recordMessageEvent(makeEvent());
+      const summary = await store.getSummary();
+      expect(summary.totalMessages).toBe(1);
+    });
+
+    it('records multiple events', async () => {
+      await store.recordMessageEvent(makeEvent());
+      await store.recordMessageEvent(makeEvent({ customerPhone: '+999' }));
+      await store.recordMessageEvent(makeEvent({ agentName: 'billing' }));
+      const summary = await store.getSummary();
+      expect(summary.totalMessages).toBe(3);
+    });
+
+    it('stores event data without mutation', async () => {
+      const event = makeEvent({ intent: 'refund' });
+      await store.recordMessageEvent(event);
+      // Mutate original — store should be unaffected
+      event.intent = 'MUTATED';
+      const kb = await store.getKbStats();
+      expect(kb.totalQueries).toBe(1);
+    });
+  });
+
+  // --- Conversation sessions ---
+
+  describe('getOrCreateConversation', () => {
+    it('creates a new conversation', async () => {
+      const id = await store.getOrCreateConversation('+1234567890', 'whatsapp', 'support');
+      expect(id).toBeTruthy();
+      expect(typeof id).toBe('string');
+    });
+
+    it('returns same conversation within session gap', async () => {
+      const id1 = await store.getOrCreateConversation('+1234567890', 'whatsapp', 'support');
+      const id2 = await store.getOrCreateConversation('+1234567890', 'whatsapp', 'support');
+      expect(id2).toBe(id1);
+    });
+
+    it('creates new conversation for different customer', async () => {
+      const id1 = await store.getOrCreateConversation('+1234567890', 'whatsapp', 'support');
+      const id2 = await store.getOrCreateConversation('+9999999999', 'whatsapp', 'support');
+      expect(id2).not.toBe(id1);
+    });
+
+    it('creates new conversation for different channel', async () => {
+      const id1 = await store.getOrCreateConversation('+1234567890', 'whatsapp', 'support');
+      const id2 = await store.getOrCreateConversation('+1234567890', 'telegram', 'support');
+      expect(id2).not.toBe(id1);
+    });
+
+    it('creates new conversation for different agent', async () => {
+      const id1 = await store.getOrCreateConversation('+1234567890', 'whatsapp', 'support');
+      const id2 = await store.getOrCreateConversation('+1234567890', 'whatsapp', 'billing');
+      expect(id2).not.toBe(id1);
+    });
+  });
+
+  describe('updateConversationStats', () => {
+    it('updates conversation after message event', async () => {
+      const convId = await store.getOrCreateConversation('+1234567890', 'whatsapp', 'support');
+      const event = makeEvent({ conversationId: convId, toolCallsCount: 2, llmCost: 0.01 });
+      await store.updateConversationStats(convId, event);
+      // No crash — stats updated internally
+    });
+
+    it('handles non-existent conversation gracefully', async () => {
+      const event = makeEvent();
+      // Should not throw
+      await store.updateConversationStats('non-existent-id', event);
+    });
+  });
+
+  // --- getSummary ---
+
+  describe('getSummary', () => {
+    it('returns zeros for empty store', async () => {
+      const summary = await store.getSummary();
+      expect(summary.totalMessages).toBe(0);
+      expect(summary.avgPerDay).toBe(0);
+      expect(summary.peakDay).toBeNull();
+      expect(summary.uniqueCustomers).toBe(0);
+      expect(summary.newCustomers).toBe(0);
+      expect(summary.returningCustomers).toBe(0);
+      expect(summary.kbAnsweredPct).toBe(0);
+      expect(summary.faqHitRate).toBe(0);
+      expect(summary.avgResponseTime).toBe(0);
+      expect(summary.pendingReviews).toBe(0);
+    });
+
+    it('counts unique customers', async () => {
+      await store.recordMessageEvent(makeEvent({ customerPhone: '+1' }));
+      await store.recordMessageEvent(makeEvent({ customerPhone: '+1' }));
+      await store.recordMessageEvent(makeEvent({ customerPhone: '+2' }));
+      const summary = await store.getSummary();
+      expect(summary.uniqueCustomers).toBe(2);
+    });
+
+    it('counts new vs returning customers', async () => {
+      await store.recordMessageEvent(makeEvent({ customerPhone: '+1', isNewCustomer: true }));
+      await store.recordMessageEvent(makeEvent({ customerPhone: '+2', isNewCustomer: false }));
+      const summary = await store.getSummary();
+      expect(summary.newCustomers).toBe(1);
+      expect(summary.returningCustomers).toBe(1);
+    });
+
+    it('calculates KB answered percentage', async () => {
+      await store.recordMessageEvent(makeEvent({ kbTopScore: 0.9 }));
+      await store.recordMessageEvent(makeEvent({ kbTopScore: 0.8 }));
+      await store.recordMessageEvent(makeEvent({ kbTopScore: 0.2 }));
+      const summary = await store.getSummary();
+      // 2 out of 3 have kbTopScore >= 0.7
+      expect(summary.kbAnsweredPct).toBeCloseTo(66.67, 0);
+    });
+
+    it('calculates no-answer percentage', async () => {
+      await store.recordMessageEvent(makeEvent({ kbTopScore: 0.1 }));
+      await store.recordMessageEvent(makeEvent({ kbTopScore: 0.9 }));
+      const summary = await store.getSummary();
+      // 1 out of 2 has kbTopScore < 0.3
+      expect(summary.noAnswerPct).toBe(50);
+    });
+
+    it('calculates FAQ hit rate', async () => {
+      await store.recordMessageEvent(makeEvent({ kbIsFaqMatch: true }));
+      await store.recordMessageEvent(makeEvent({ kbIsFaqMatch: false }));
+      const summary = await store.getSummary();
+      expect(summary.faqHitRate).toBe(50);
+    });
+
+    it('calculates average response time', async () => {
+      await store.recordMessageEvent(makeEvent({ responseTimeMs: 200 }));
+      await store.recordMessageEvent(makeEvent({ responseTimeMs: 400 }));
+      const summary = await store.getSummary();
+      expect(summary.avgResponseTime).toBe(300);
+    });
+
+    it('builds agent breakdown', async () => {
+      await store.recordMessageEvent(makeEvent({ agentName: 'support' }));
+      await store.recordMessageEvent(makeEvent({ agentName: 'support' }));
+      await store.recordMessageEvent(makeEvent({ agentName: 'billing' }));
+      const summary = await store.getSummary();
+      expect(summary.agentBreakdown).toEqual({ support: 2, billing: 1 });
+    });
+
+    it('identifies peak day', async () => {
+      const day1 = new Date('2026-01-15T10:00:00Z').getTime();
+      const day2 = new Date('2026-01-16T10:00:00Z').getTime();
+      await store.recordMessageEvent(makeEvent({ timestamp: day1 }));
+      await store.recordMessageEvent(makeEvent({ timestamp: day2 }));
+      await store.recordMessageEvent(makeEvent({ timestamp: day2 }));
+      const summary = await store.getSummary();
+      expect(summary.peakDay).toBe('2026-01-16');
+    });
+
+    it('calculates avgPerDay correctly', async () => {
+      const day1 = new Date('2026-01-15T10:00:00Z').getTime();
+      const day2 = new Date('2026-01-16T10:00:00Z').getTime();
+      await store.recordMessageEvent(makeEvent({ timestamp: day1 }));
+      await store.recordMessageEvent(makeEvent({ timestamp: day1 }));
+      await store.recordMessageEvent(makeEvent({ timestamp: day2 }));
+      const summary = await store.getSummary();
+      // 3 messages over 2 days
+      expect(summary.avgPerDay).toBe(1.5);
+    });
+
+    it('filters by time range', async () => {
+      const t1 = new Date('2026-01-10T10:00:00Z').getTime();
+      const t2 = new Date('2026-01-15T10:00:00Z').getTime();
+      const t3 = new Date('2026-01-20T10:00:00Z').getTime();
+      await store.recordMessageEvent(makeEvent({ timestamp: t1 }));
+      await store.recordMessageEvent(makeEvent({ timestamp: t2 }));
+      await store.recordMessageEvent(makeEvent({ timestamp: t3 }));
+
+      const range: TimeRange = { from: t2 - 1000, to: t2 + 1000 };
+      const summary = await store.getSummary(range);
+      expect(summary.totalMessages).toBe(1);
+    });
+  });
+
+  // --- getMessageVolume ---
+
+  describe('getMessageVolume', () => {
+    it('returns empty array for empty store', async () => {
+      const volume = await store.getMessageVolume();
+      expect(volume).toEqual([]);
+    });
+
+    it('groups by day', async () => {
+      const day1 = new Date('2026-01-15T10:00:00Z').getTime();
+      const day1b = new Date('2026-01-15T14:00:00Z').getTime();
+      const day2 = new Date('2026-01-16T10:00:00Z').getTime();
+      await store.recordMessageEvent(makeEvent({ timestamp: day1 }));
+      await store.recordMessageEvent(makeEvent({ timestamp: day1b }));
+      await store.recordMessageEvent(makeEvent({ timestamp: day2 }));
+
+      const volume = await store.getMessageVolume(undefined, 'day');
+      expect(volume).toHaveLength(2);
+      expect(volume[0].count).toBe(2);
+      expect(volume[1].count).toBe(1);
+    });
+
+    it('groups by hour', async () => {
+      const h1 = new Date('2026-01-15T10:15:00Z').getTime();
+      const h1b = new Date('2026-01-15T10:45:00Z').getTime();
+      const h2 = new Date('2026-01-15T11:15:00Z').getTime();
+      await store.recordMessageEvent(makeEvent({ timestamp: h1 }));
+      await store.recordMessageEvent(makeEvent({ timestamp: h1b }));
+      await store.recordMessageEvent(makeEvent({ timestamp: h2 }));
+
+      const volume = await store.getMessageVolume(undefined, 'hour');
+      expect(volume).toHaveLength(2);
+      // First hour bucket has 2 messages
+      expect(volume[0].count).toBe(2);
+    });
+
+    it('respects time range filter', async () => {
+      const t1 = new Date('2026-01-10T10:00:00Z').getTime();
+      const t2 = new Date('2026-01-15T10:00:00Z').getTime();
+      await store.recordMessageEvent(makeEvent({ timestamp: t1 }));
+      await store.recordMessageEvent(makeEvent({ timestamp: t2 }));
+
+      const range: TimeRange = { from: t2 - 1000, to: t2 + 1000 };
+      const volume = await store.getMessageVolume(range);
+      expect(volume).toHaveLength(1);
+    });
+
+    it('returns sorted by date', async () => {
+      const t2 = new Date('2026-01-16T10:00:00Z').getTime();
+      const t1 = new Date('2026-01-15T10:00:00Z').getTime();
+      // Insert out of order
+      await store.recordMessageEvent(makeEvent({ timestamp: t2 }));
+      await store.recordMessageEvent(makeEvent({ timestamp: t1 }));
+
+      const volume = await store.getMessageVolume();
+      expect(volume[0].date < volume[1].date).toBe(true);
+    });
+  });
+
+  // --- getAgentStats ---
+
+  describe('getAgentStats', () => {
+    it('returns empty array for empty store', async () => {
+      const stats = await store.getAgentStats();
+      expect(stats).toEqual([]);
+    });
+
+    it('aggregates per agent', async () => {
+      await store.recordMessageEvent(makeEvent({ agentName: 'support', responseTimeMs: 200, intentConfidence: 0.9 }));
+      await store.recordMessageEvent(makeEvent({ agentName: 'support', responseTimeMs: 400, intentConfidence: 0.8 }));
+      await store.recordMessageEvent(makeEvent({ agentName: 'billing', responseTimeMs: 300, intentConfidence: 0.7 }));
+
+      const stats = await store.getAgentStats();
+      expect(stats).toHaveLength(2);
+
+      const support = stats.find(s => s.agentName === 'support')!;
+      expect(support.messageCount).toBe(2);
+      expect(support.avgResponseTimeMs).toBe(300);
+      expect(support.avgConfidence).toBeCloseTo(0.85);
+    });
+
+    it('counts escalations per agent', async () => {
+      await store.recordMessageEvent(makeEvent({ agentName: 'support', wasEscalated: true }));
+      await store.recordMessageEvent(makeEvent({ agentName: 'support', wasEscalated: false }));
+      const stats = await store.getAgentStats();
+      const support = stats.find(s => s.agentName === 'support')!;
+      expect(support.escalationCount).toBe(1);
+    });
+
+    it('sums tool calls per agent', async () => {
+      await store.recordMessageEvent(makeEvent({ agentName: 'support', toolCallsCount: 3 }));
+      await store.recordMessageEvent(makeEvent({ agentName: 'support', toolCallsCount: 2 }));
+      const stats = await store.getAgentStats();
+      const support = stats.find(s => s.agentName === 'support')!;
+      expect(support.toolCallCount).toBe(5);
+    });
+
+    it('respects time range', async () => {
+      const t1 = new Date('2026-01-10T10:00:00Z').getTime();
+      const t2 = new Date('2026-01-20T10:00:00Z').getTime();
+      await store.recordMessageEvent(makeEvent({ timestamp: t1, agentName: 'support' }));
+      await store.recordMessageEvent(makeEvent({ timestamp: t2, agentName: 'billing' }));
+
+      const range: TimeRange = { from: t2 - 1000, to: t2 + 1000 };
+      const stats = await store.getAgentStats(range);
+      expect(stats).toHaveLength(1);
+      expect(stats[0].agentName).toBe('billing');
+    });
+  });
+
+  // --- getCustomerStats ---
+
+  describe('getCustomerStats', () => {
+    it('returns empty array for empty store', async () => {
+      const stats = await store.getCustomerStats();
+      expect(stats).toEqual([]);
+    });
+
+    it('aggregates per customer', async () => {
+      const t1 = new Date('2026-01-15T10:00:00Z').getTime();
+      const t2 = new Date('2026-01-15T14:00:00Z').getTime();
+      await store.recordMessageEvent(makeEvent({ customerPhone: '+1', customerId: 'c1', timestamp: t1 }));
+      await store.recordMessageEvent(makeEvent({ customerPhone: '+1', customerId: 'c1', timestamp: t2 }));
+      await store.recordMessageEvent(makeEvent({ customerPhone: '+2', customerId: 'c2', timestamp: t1 }));
+
+      const stats = await store.getCustomerStats();
+      expect(stats).toHaveLength(2);
+      // Sorted by message count desc
+      expect(stats[0].customerPhone).toBe('+1');
+      expect(stats[0].messageCount).toBe(2);
+      expect(stats[0].firstSeen).toBe(t1);
+      expect(stats[0].lastSeen).toBe(t2);
+    });
+
+    it('respects limit', async () => {
+      await store.recordMessageEvent(makeEvent({ customerPhone: '+1' }));
+      await store.recordMessageEvent(makeEvent({ customerPhone: '+2' }));
+      await store.recordMessageEvent(makeEvent({ customerPhone: '+3' }));
+
+      const stats = await store.getCustomerStats(undefined, 2);
+      expect(stats).toHaveLength(2);
+    });
+
+    it('tracks isNew flag', async () => {
+      await store.recordMessageEvent(makeEvent({ customerPhone: '+1', isNewCustomer: true }));
+      await store.recordMessageEvent(makeEvent({ customerPhone: '+1', isNewCustomer: false }));
+      const stats = await store.getCustomerStats();
+      // isNew should be true if any event had isNewCustomer=true
+      expect(stats[0].isNew).toBe(true);
+    });
+  });
+
+  // --- getKbStats ---
+
+  describe('getKbStats', () => {
+    it('returns zeros for empty store', async () => {
+      const kb = await store.getKbStats();
+      expect(kb.totalQueries).toBe(0);
+      expect(kb.faqHits).toBe(0);
+      expect(kb.faqHitRate).toBe(0);
+      expect(kb.avgTopScore).toBe(0);
+      expect(kb.topFaqHits).toEqual([]);
+      expect(kb.topMisses).toEqual([]);
+    });
+
+    it('calculates FAQ hit rate', async () => {
+      await store.recordMessageEvent(makeEvent({ kbIsFaqMatch: true, kbTopScore: 0.9 }));
+      await store.recordMessageEvent(makeEvent({ kbIsFaqMatch: true, kbTopScore: 0.85 }));
+      await store.recordMessageEvent(makeEvent({ kbIsFaqMatch: false, kbTopScore: 0.4 }));
+
+      const kb = await store.getKbStats();
+      expect(kb.totalQueries).toBe(3);
+      expect(kb.faqHits).toBe(2);
+      expect(kb.faqHitRate).toBeCloseTo(66.67, 0);
+    });
+
+    it('calculates average top score', async () => {
+      await store.recordMessageEvent(makeEvent({ kbTopScore: 0.8 }));
+      await store.recordMessageEvent(makeEvent({ kbTopScore: 0.6 }));
+      const kb = await store.getKbStats();
+      expect(kb.avgTopScore).toBeCloseTo(0.7);
+    });
+  });
+
+  // --- getTopFaqHits ---
+
+  describe('getTopFaqHits', () => {
+    it('returns empty for no FAQ matches', async () => {
+      await store.recordMessageEvent(makeEvent({ kbIsFaqMatch: false }));
+      const hits = await store.getTopFaqHits();
+      expect(hits).toEqual([]);
+    });
+
+    it('groups by intent and sorts by count', async () => {
+      await store.recordMessageEvent(makeEvent({ kbIsFaqMatch: true, intent: 'hours' }));
+      await store.recordMessageEvent(makeEvent({ kbIsFaqMatch: true, intent: 'hours' }));
+      await store.recordMessageEvent(makeEvent({ kbIsFaqMatch: true, intent: 'returns' }));
+
+      const hits = await store.getTopFaqHits();
+      expect(hits[0]).toEqual({ intent: 'hours', count: 2 });
+      expect(hits[1]).toEqual({ intent: 'returns', count: 1 });
+    });
+
+    it('respects limit', async () => {
+      await store.recordMessageEvent(makeEvent({ kbIsFaqMatch: true, intent: 'a' }));
+      await store.recordMessageEvent(makeEvent({ kbIsFaqMatch: true, intent: 'b' }));
+      await store.recordMessageEvent(makeEvent({ kbIsFaqMatch: true, intent: 'c' }));
+
+      const hits = await store.getTopFaqHits(2);
+      expect(hits).toHaveLength(2);
+    });
+  });
+
+  // --- getTopMisses ---
+
+  describe('getTopMisses', () => {
+    it('returns empty when no low-score events', async () => {
+      await store.recordMessageEvent(makeEvent({ kbTopScore: 0.9 }));
+      const misses = await store.getTopMisses();
+      expect(misses).toEqual([]);
+    });
+
+    it('captures low-score events (< 0.5 and > 0)', async () => {
+      await store.recordMessageEvent(makeEvent({ kbTopScore: 0.3, intent: 'unknown_q' }));
+      await store.recordMessageEvent(makeEvent({ kbTopScore: 0.2, intent: 'unknown_q' }));
+      await store.recordMessageEvent(makeEvent({ kbTopScore: 0.4, intent: 'other_q' }));
+
+      const misses = await store.getTopMisses();
+      expect(misses).toHaveLength(2);
+      expect(misses[0].intent).toBe('unknown_q');
+      expect(misses[0].count).toBe(2);
+      expect(misses[0].avgScore).toBeCloseTo(0.25);
+    });
+
+    it('excludes zero-score events', async () => {
+      await store.recordMessageEvent(makeEvent({ kbTopScore: 0, intent: 'no_kb' }));
+      const misses = await store.getTopMisses();
+      expect(misses).toEqual([]);
+    });
+
+    it('excludes high-score events', async () => {
+      await store.recordMessageEvent(makeEvent({ kbTopScore: 0.8, intent: 'good' }));
+      const misses = await store.getTopMisses();
+      expect(misses).toEqual([]);
+    });
+  });
+
+  // --- Edge cases ---
+
+  describe('edge cases', () => {
+    it('handles single message correctly', async () => {
+      await store.recordMessageEvent(makeEvent());
+      const summary = await store.getSummary();
+      expect(summary.totalMessages).toBe(1);
+      expect(summary.avgPerDay).toBe(1);
+    });
+
+    it('handles multiple agents with same customer', async () => {
+      await store.recordMessageEvent(makeEvent({ agentName: 'support', customerPhone: '+1' }));
+      await store.recordMessageEvent(makeEvent({ agentName: 'billing', customerPhone: '+1' }));
+      const summary = await store.getSummary();
+      expect(summary.uniqueCustomers).toBe(1);
+      expect(summary.agentBreakdown).toEqual({ support: 1, billing: 1 });
+    });
+
+    it('initialize and close are no-ops', async () => {
+      const s = new InMemoryAnalyticsStore();
+      await s.initialize();
+      await s.close();
+      // Should not throw
+    });
+  });
+});