@operor/analytics 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,224 @@
+//#region src/types.d.ts
+/**
+ * Analytics types for Operor
+ */
+/** A single message event recorded by the analytics collector */
+interface AnalyticsEvent {
+  id?: number;
+  timestamp: number;
+  channel: string;
+  customerPhone: string;
+  customerId: string;
+  agentName: string;
+  intent: string;
+  intentConfidence: number;
+  responseTimeMs: number;
+  llmCost: number;
+  kbTopScore: number;
+  kbIsFaqMatch: boolean;
+  kbResultCount: number;
+  toolCallsCount: number;
+  toolCallsJson: string | null;
+  messageLength: number;
+  responseLength: number;
+  isNewCustomer: boolean;
+  wasEscalated: boolean;
+  conversationId: string | null;
+  promptTokens: number;
+  completionTokens: number;
+}
+/** Aggregated summary for a time range */
+interface AnalyticsSummary {
+  totalMessages: number;
+  avgPerDay: number;
+  peakDay: string | null;
+  kbAnsweredPct: number;
+  llmFallbackPct: number;
+  noAnswerPct: number;
+  avgResponseTime: number;
+  faqHitRate: number;
+  uniqueCustomers: number;
+  newCustomers: number;
+  returningCustomers: number;
+  agentBreakdown: Record<string, number>;
+  pendingReviews: number;
+}
+/** Message volume data point (for charts) */
+interface MessageVolumeData {
+  date: string;
+  count: number;
+  channel?: string;
+}
+/** Per-agent stats */
+interface AgentStatsData {
+  agentName: string;
+  messageCount: number;
+  avgResponseTimeMs: number;
+  avgConfidence: number;
+  escalationCount: number;
+  toolCallCount: number;
+}
+/** Per-customer stats */
+interface CustomerStatsData {
+  customerId: string;
+  customerPhone: string;
+  messageCount: number;
+  firstSeen: number;
+  lastSeen: number;
+  isNew: boolean;
+}
+/** Knowledge Base stats from analytics */
+interface KbStatsData {
+  totalQueries: number;
+  faqHits: number;
+  faqHitRate: number;
+  avgTopScore: number;
+  topFaqHits: Array<{
+    intent: string;
+    count: number;
+  }>;
+  topMisses: Array<{
+    intent: string;
+    count: number;
+    avgScore: number;
+  }>;
+}
+/** A conversation session (gap-based) */
+interface ConversationSession {
+  id: string;
+  customerId: string;
+  customerPhone: string;
+  channel: string;
+  agentId: string;
+  startedAt: number;
+  endedAt: number;
+  messageCount: number;
+  toolCallCount: number;
+  totalDurationMs: number;
+  totalCost: number;
+  resolved: boolean;
+  resolutionType: string | null;
+}
+/** Time range filter for queries */
+interface TimeRange {
+  from: number;
+  to: number;
+}
+/** Store interface for analytics persistence */
+interface AnalyticsStore {
+  initialize(): Promise<void>;
+  close(): Promise<void>;
+  /** Record a message event */
+  recordMessageEvent(event: AnalyticsEvent): Promise<void>;
+  /** Get or create a conversation session */
+  getOrCreateConversation(customerPhone: string, channel: string, agentName: string): Promise<string>;
+  /** Update conversation stats after a message */
+  updateConversationStats(conversationId: string, event: AnalyticsEvent): Promise<void>;
+  /** Get aggregated summary for a time range */
+  getSummary(range?: TimeRange): Promise<AnalyticsSummary>;
+  /** Get message volume over time */
+  getMessageVolume(range?: TimeRange, groupBy?: 'day' | 'hour'): Promise<MessageVolumeData[]>;
+  /** Get per-agent stats */
+  getAgentStats(range?: TimeRange): Promise<AgentStatsData[]>;
+  /** Get per-customer stats */
+  getCustomerStats(range?: TimeRange, limit?: number): Promise<CustomerStatsData[]>;
+  /** Get KB-related stats */
+  getKbStats(range?: TimeRange): Promise<KbStatsData>;
+  /** Get top FAQ hits */
+  getTopFaqHits(limit?: number, range?: TimeRange): Promise<Array<{
+    intent: string;
+    count: number;
+  }>>;
+  /** Get top misses (low KB score) */
+  getTopMisses(limit?: number, range?: TimeRange): Promise<Array<{
+    intent: string;
+    count: number;
+    avgScore: number;
+  }>>;
+}
+//#endregion
+//#region src/SQLiteAnalyticsStore.d.ts
+declare class SQLiteAnalyticsStore implements AnalyticsStore {
+  private db;
+  constructor(dbPath?: string);
+  initialize(): Promise<void>;
+  close(): Promise<void>;
+  recordMessageEvent(event: AnalyticsEvent): Promise<void>;
+  getOrCreateConversation(customerPhone: string, channel: string, agentName: string): Promise<string>;
+  updateConversationStats(conversationId: string, event: AnalyticsEvent): Promise<void>;
+  getSummary(range?: TimeRange): Promise<AnalyticsSummary>;
+  getMessageVolume(range?: TimeRange, groupBy?: 'day' | 'hour'): Promise<MessageVolumeData[]>;
+  getAgentStats(range?: TimeRange): Promise<AgentStatsData[]>;
+  getCustomerStats(range?: TimeRange, limit?: number): Promise<CustomerStatsData[]>;
+  getKbStats(range?: TimeRange): Promise<KbStatsData>;
+  getTopFaqHits(limit?: number, range?: TimeRange): Promise<Array<{
+    intent: string;
+    count: number;
+  }>>;
+  getTopMisses(limit?: number, range?: TimeRange): Promise<Array<{
+    intent: string;
+    count: number;
+    avgScore: number;
+  }>>;
+}
+//#endregion
+//#region src/InMemoryAnalyticsStore.d.ts
+/**
+ * In-memory analytics store for testing and development.
+ */
+declare class InMemoryAnalyticsStore implements AnalyticsStore {
+  private events;
+  private conversations;
+  initialize(): Promise<void>;
+  close(): Promise<void>;
+  recordMessageEvent(event: AnalyticsEvent): Promise<void>;
+  getOrCreateConversation(customerPhone: string, channel: string, agentName: string): Promise<string>;
+  updateConversationStats(conversationId: string, event: AnalyticsEvent): Promise<void>;
+  private filter;
+  getSummary(range?: TimeRange): Promise<AnalyticsSummary>;
+  getMessageVolume(range?: TimeRange, groupBy?: 'day' | 'hour'): Promise<MessageVolumeData[]>;
+  getAgentStats(range?: TimeRange): Promise<AgentStatsData[]>;
+  getCustomerStats(range?: TimeRange, limit?: number): Promise<CustomerStatsData[]>;
+  getKbStats(range?: TimeRange): Promise<KbStatsData>;
+  getTopFaqHits(limit?: number, range?: TimeRange): Promise<Array<{
+    intent: string;
+    count: number;
+  }>>;
+  getTopMisses(limit?: number, range?: TimeRange): Promise<Array<{
+    intent: string;
+    count: number;
+    avgScore: number;
+  }>>;
+}
+//#endregion
+//#region src/AnalyticsCollector.d.ts
+/** Minimal EventEmitter interface — matches eventemitter3 used by Operor */
+interface Emitter {
+  on(event: string, handler: (...args: any[]) => void): void;
+  off(event: string, handler: (...args: any[]) => void): void;
+}
+/**
+ * Listens to Operor events and persists analytics data.
+ */
+declare class AnalyticsCollector {
+  private store;
+  private debug;
+  private boundHandlers;
+  constructor(store: AnalyticsStore, options?: {
+    debug?: boolean;
+  });
+  /**
+   * Attach to an Operor instance (or any EventEmitter with the same events).
+   */
+  attach(os: Emitter): void;
+  /**
+   * Detach from an Operor instance.
+   */
+  detach(os: Emitter): void;
+  private handleProcessed;
+  private handleError;
+  private log;
+}
+//#endregion
+export { AgentStatsData, AnalyticsCollector, AnalyticsEvent, AnalyticsStore, AnalyticsSummary, ConversationSession, CustomerStatsData, InMemoryAnalyticsStore, KbStatsData, MessageVolumeData, SQLiteAnalyticsStore, TimeRange };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/types.ts","../src/SQLiteAnalyticsStore.ts","../src/InMemoryAnalyticsStore.ts","../src/AnalyticsCollector.ts"],"mappings":"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"}