@operor/analytics 0.1.0

package/src/SQLiteAnalyticsStore.test.ts

@@ -0,0 +1,554 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { SQLiteAnalyticsStore } from './SQLiteAnalyticsStore.js';
+import type { AnalyticsEvent, TimeRange } from './types.js';
+import { mkdtempSync, rmSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+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('SQLiteAnalyticsStore', () => {
+  let store: SQLiteAnalyticsStore;
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'analytics-test-'));
+    store = new SQLiteAnalyticsStore(join(tmpDir, 'test.db'));
+    await store.initialize();
+  });
+
+  afterEach(async () => {
+    await store.close();
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  // --- Schema / initialize ---
+
+  describe('initialize', () => {
+    it('creates tables without error', async () => {
+      // Already initialized in beforeEach — just verify it works
+      const summary = await store.getSummary();
+      expect(summary.totalMessages).toBe(0);
+    });
+
+    it('is idempotent (can be called twice)', async () => {
+      await store.initialize();
+      const summary = await store.getSummary();
+      expect(summary.totalMessages).toBe(0);
+    });
+  });
+
+  // --- recordMessageEvent ---
+
+  describe('recordMessageEvent', () => {
+    it('inserts a single event', async () => {
+      await store.recordMessageEvent(makeEvent());
+      const summary = await store.getSummary();
+      expect(summary.totalMessages).toBe(1);
+    });
+
+    it('inserts 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 boolean fields as integers', async () => {
+      await store.recordMessageEvent(makeEvent({ kbIsFaqMatch: true, isNewCustomer: true, wasEscalated: true }));
+      const summary = await store.getSummary();
+      expect(summary.faqHitRate).toBe(100);
+      expect(summary.newCustomers).toBe(1);
+    });
+
+    it('handles null toolCallsJson', async () => {
+      await store.recordMessageEvent(makeEvent({ toolCallsJson: null }));
+      const summary = await store.getSummary();
+      expect(summary.totalMessages).toBe(1);
+    });
+
+    it('handles non-null toolCallsJson', async () => {
+      await store.recordMessageEvent(makeEvent({
+        toolCallsCount: 2,
+        toolCallsJson: JSON.stringify([{ name: 'get_order', params: {} }]),
+      }));
+      const summary = await store.getSummary();
+      expect(summary.totalMessages).toBe(1);
+    });
+  });
+
+  // --- Conversation sessions (30-min gap) ---
+
+  describe('getOrCreateConversation', () => {
+    it('creates a new conversation', async () => {
+      const id = await store.getOrCreateConversation('+1234567890', 'whatsapp', 'support');
+      expect(id).toBeTruthy();
+      expect(typeof id).toBe('string');
+      expect(id.length).toBe(36); // UUID format
+    });
+
+    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 message count and cost', async () => {
+      const convId = await store.getOrCreateConversation('+1234567890', 'whatsapp', 'support');
+      const event = makeEvent({ conversationId: convId, toolCallsCount: 2, llmCost: 0.01 });
+      await store.updateConversationStats(convId, event);
+      // Verify by creating another event — conversation should still be active
+      const convId2 = await store.getOrCreateConversation('+1234567890', 'whatsapp', 'support');
+      expect(convId2).toBe(convId);
+    });
+
+    it('sets customer_id on first update', async () => {
+      const convId = await store.getOrCreateConversation('+1234567890', 'whatsapp', 'support');
+      const event = makeEvent({ customerId: 'cust_42', conversationId: convId });
+      await store.updateConversationStats(convId, event);
+      // No crash — customer_id set internally
+    });
+  });
+
+  // --- getSummary ---
+
+  describe('getSummary', () => {
+    it('returns zeros for empty database', 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.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 customers', async () => {
+      await store.recordMessageEvent(makeEvent({ isNewCustomer: true }));
+      await store.recordMessageEvent(makeEvent({ isNewCustomer: false }));
+      const summary = await store.getSummary();
+      expect(summary.newCustomers).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();
+      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();
+      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('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 database', 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);
+      // First day has 2 messages
+      const totalCount = volume.reduce((s, v) => s + v.count, 0);
+      expect(totalCount).toBe(3);
+    });
+
+    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);
+    });
+
+    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();
+      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);
+    });
+
+    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 }));
+      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);
+    });
+  });
+
+  // --- getAgentStats ---
+
+  describe('getAgentStats', () => {
+    it('returns empty array for empty database', 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', 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', 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 database', 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();
+      expect(stats[0].isNew).toBe(true);
+    });
+  });
+
+  // --- getKbStats ---
+
+  describe('getKbStats', () => {
+    it('returns zeros for empty database', 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 stats', async () => {
+      await store.recordMessageEvent(makeEvent({ kbIsFaqMatch: true, kbTopScore: 0.9, intent: 'hours' }));
+      await store.recordMessageEvent(makeEvent({ kbIsFaqMatch: true, kbTopScore: 0.85, intent: 'hours' }));
+      await store.recordMessageEvent(makeEvent({ kbIsFaqMatch: false, kbTopScore: 0.4, intent: 'unknown' }));
+
+      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);
+    });
+
+    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, kbIsFaqMatch: true, intent: 'old' }));
+      await store.recordMessageEvent(makeEvent({ timestamp: t2, kbIsFaqMatch: true, intent: 'new' }));
+
+      const range: TimeRange = { from: t2 - 1000, to: t2 + 1000 };
+      const hits = await store.getTopFaqHits(10, range);
+      expect(hits).toHaveLength(1);
+      expect(hits[0].intent).toBe('new');
+    });
+  });
+
+  // --- 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', 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 (>= 0.5)', async () => {
+      await store.recordMessageEvent(makeEvent({ kbTopScore: 0.5, intent: 'borderline' }));
+      await store.recordMessageEvent(makeEvent({ kbTopScore: 0.8, intent: 'good' }));
+      const misses = await store.getTopMisses();
+      expect(misses).toEqual([]);
+    });
+
+    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, kbTopScore: 0.3, intent: 'old_miss' }));
+      await store.recordMessageEvent(makeEvent({ timestamp: t2, kbTopScore: 0.3, intent: 'new_miss' }));
+
+      const range: TimeRange = { from: t2 - 1000, to: t2 + 1000 };
+      const misses = await store.getTopMisses(10, range);
+      expect(misses).toHaveLength(1);
+      expect(misses[0].intent).toBe('new_miss');
+    });
+  });
+
+  // --- 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('handles large batch of events', async () => {
+      for (let i = 0; i < 100; i++) {
+        await store.recordMessageEvent(makeEvent({
+          customerPhone: `+${i % 10}`,
+          agentName: i % 3 === 0 ? 'support' : 'billing',
+          kbTopScore: Math.random(),
+          kbIsFaqMatch: Math.random() > 0.5,
+        }));
+      }
+      const summary = await store.getSummary();
+      expect(summary.totalMessages).toBe(100);
+      expect(summary.uniqueCustomers).toBe(10);
+    });
+
+    it('handles events with zero response time', async () => {
+      await store.recordMessageEvent(makeEvent({ responseTimeMs: 0 }));
+      const summary = await store.getSummary();
+      expect(summary.avgResponseTime).toBe(0);
+    });
+
+    it('handles events with zero cost', async () => {
+      await store.recordMessageEvent(makeEvent({ llmCost: 0 }));
+      const summary = await store.getSummary();
+      expect(summary.totalMessages).toBe(1);
+    });
+  });
+});