catalist-support-agent 1.0.0

package/dist/escalation/index.js

@@ -0,0 +1,436 @@
+/**
+ * Escalation System Module
+ *
+ * Routes conversations requiring human attention:
+ * - Forbidden terms detection
+ * - Low confidence responses
+ * - Customer complaints
+ * - Explicit human requests
+ * - N-failure tracking
+ */
+import { createClient } from '@supabase/supabase-js';
+import { config, getEscalationChannels, getSlaTarget } from '../config.js';
+import { EscalationError, AllEscalationChannelsFailedError, } from '../errors.js';
+import { createEscalationId } from '../types.js';
+// =============================================================================
+// Escalation Triggers
+// =============================================================================
+/**
+ * Determine if escalation is required based on analysis
+ */
+export function shouldEscalate(analysis) {
+    const reasons = [];
+    let trigger;
+    let severity = 'medium';
+    // CRITICAL: Forbidden terms
+    if (analysis.brandCompliance.status === 'blocked') {
+        trigger = 'forbidden_terms';
+        severity = 'high';
+        reasons.push('Forbidden terms detected in message');
+    }
+    // Complaint intent
+    if (analysis.intent.primary === 'complaint') {
+        trigger = trigger || 'complaint';
+        severity = 'high';
+        reasons.push('Customer complaint detected');
+    }
+    // Low confidence
+    if (analysis.overallConfidence < config.agent.confidenceThresholds.escalationTrigger) {
+        trigger = trigger || 'low_confidence';
+        reasons.push(`Low analysis confidence: ${Math.round(analysis.overallConfidence * 100)}%`);
+    }
+    // Critical urgency
+    if (analysis.sentiment.urgency === 'critical') {
+        trigger = trigger || 'high_urgency';
+        severity = 'critical';
+        reasons.push('Critical urgency level');
+    }
+    // Negative sentiment
+    if (analysis.sentiment.category === 'negative' && analysis.sentiment.score < -0.6) {
+        trigger = trigger || 'negative_sentiment';
+        reasons.push('Strong negative sentiment');
+    }
+    return {
+        required: trigger !== undefined,
+        trigger,
+        severity,
+        reasons,
+    };
+}
+/**
+ * Check for explicit human assistance request
+ */
+export function containsHumanRequest(text) {
+    const patterns = [
+        /speak\s+(to|with)\s+(a\s+)?(human|person|agent|representative|someone)/i,
+        /talk\s+(to|with)\s+(a\s+)?(human|person|agent|representative|someone)/i,
+        /real\s+(human|person)/i,
+        /not\s+(a\s+)?bot/i,
+        /transfer\s+me/i,
+        /escalate/i,
+        /manager/i,
+        /supervisor/i,
+    ];
+    return patterns.some((p) => p.test(text));
+}
+// =============================================================================
+// Escalation Service
+// =============================================================================
+export class EscalationService {
+    supabase;
+    constructor() {
+        this.supabase = createClient(config.supabase.url, config.supabase.serviceRoleKey);
+    }
+    /**
+     * Create and route an escalation
+     */
+    async escalate(context) {
+        // 1. Determine severity-based channels
+        const channels = getEscalationChannels(context.severity);
+        // 2. Calculate SLA target
+        const slaTargetMs = getSlaTarget(context.severity);
+        const slaTargetAt = new Date(Date.now() + slaTargetMs);
+        // 3. Create escalation record
+        const { data: escalation, error: insertError } = await this.supabase
+            .from('support_escalations')
+            .insert({
+            conversation_id: context.conversationId,
+            message_id: context.messageId,
+            customer_id: context.customerId,
+            trigger: context.trigger,
+            severity: context.severity,
+            reason: context.reason,
+            context_data: this.buildContextData(context),
+            sla_target_at: slaTargetAt.toISOString(),
+        })
+            .select('id')
+            .single();
+        if (insertError || !escalation) {
+            throw new EscalationError('Failed to create escalation record', {
+                cause: new Error(insertError?.message),
+                conversationId: context.conversationId,
+                messageId: context.messageId,
+            });
+        }
+        const escalationId = createEscalationId(escalation.id);
+        // 4. Send notifications to all channels
+        const deliveries = [];
+        const channelErrors = [];
+        for (const channel of channels) {
+            try {
+                const delivery = await this.notifyChannel(channel, escalationId, context);
+                deliveries.push(delivery);
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+                channelErrors.push({ channel, error: errorMessage });
+                deliveries.push({
+                    channel,
+                    success: false,
+                    error: errorMessage,
+                    timestamp: new Date().toISOString(),
+                });
+            }
+        }
+        // 5. Update escalation record with notification results
+        await this.supabase
+            .from('support_escalations')
+            .update({
+            notification_channels: deliveries.map((d) => ({
+                channel: d.channel,
+                sent_at: d.timestamp,
+                message_id: d.messageId,
+                success: d.success,
+                error: d.error,
+            })),
+        })
+            .eq('id', escalationId);
+        // 6. Update conversation status
+        await this.supabase
+            .from('support_conversations')
+            .update({
+            status: 'escalated',
+            is_handled_by_ai: false,
+            state_data: {
+                status: 'escalated',
+                escalatedAt: new Date().toISOString(),
+                escalationId,
+                reason: context.reason,
+            },
+        })
+            .eq('id', context.conversationId);
+        // 7. Check if all channels failed
+        const allSucceeded = deliveries.every((d) => d.success);
+        const anySucceeded = deliveries.some((d) => d.success);
+        if (!anySucceeded) {
+            // Use database fallback
+            await this.createDatabaseFallback(escalationId, context);
+            throw new AllEscalationChannelsFailedError(channelErrors, {
+                escalationId,
+                conversationId: context.conversationId,
+                messageId: context.messageId,
+            });
+        }
+        return {
+            escalationId,
+            conversationId: context.conversationId,
+            deliveries,
+            allSucceeded,
+            adminUrl: `${config.escalation.adminBaseUrl}/support/escalations/${escalationId}`,
+            createdAt: new Date().toISOString(),
+        };
+    }
+    /**
+     * Build context data for escalation record
+     */
+    buildContextData(context) {
+        return {
+            trigger: context.trigger,
+            severity: context.severity,
+            reason: context.reason,
+            analysisResult: context.analysisResult
+                ? {
+                    intent: context.analysisResult.intent,
+                    sentiment: context.analysisResult.sentiment,
+                    brandCompliance: context.analysisResult.brandCompliance,
+                    overallConfidence: context.analysisResult.overallConfidence,
+                    escalationReasons: context.analysisResult.escalationReasons,
+                }
+                : undefined,
+            attemptedResponses: context.attemptedResponses?.length ?? 0,
+            knowledgeContext: context.knowledgeContext
+                ? {
+                    hasCustomerData: !!context.knowledgeContext.customer,
+                    hasOrderData: !!(context.knowledgeContext.orders?.length ?? 0 > 0),
+                    hasProductData: !!(context.knowledgeContext.products?.length ?? 0 > 0),
+                }
+                : undefined,
+        };
+    }
+    /**
+     * Send notification via a specific channel
+     */
+    async notifyChannel(channel, escalationId, context) {
+        const timestamp = new Date().toISOString();
+        // Check if channel is configured
+        if (!this.isChannelConfigured(channel)) {
+            return {
+                channel,
+                success: false,
+                error: `Channel ${channel} not configured`,
+                timestamp,
+            };
+        }
+        // Build notification content
+        const content = this.buildNotificationContent(escalationId, context);
+        switch (channel) {
+            case 'email':
+                return this.sendEmailNotification(escalationId, context, content);
+            case 'sms':
+                return this.sendSmsNotification(escalationId, context, content);
+            case 'slack':
+                return this.sendSlackNotification(escalationId, context, content);
+            default:
+                return {
+                    channel,
+                    success: false,
+                    error: `Unknown channel: ${channel}`,
+                    timestamp,
+                };
+        }
+    }
+    /**
+     * Check if a channel is properly configured
+     */
+    isChannelConfigured(channel) {
+        switch (channel) {
+            case 'email':
+                return !!config.postmark.serverToken;
+            case 'sms':
+                return !!config.twilio.accountSid && !!config.twilio.authToken;
+            case 'slack':
+                return !!config.slack.botToken;
+            default:
+                return false;
+        }
+    }
+    /**
+     * Build notification content
+     */
+    buildNotificationContent(escalationId, context) {
+        const severityEmoji = {
+            critical: '🚨',
+            high: '⚠️',
+            medium: '📋',
+            low: 'ℹ️',
+        }[context.severity] || '📋';
+        const subject = `${severityEmoji} [${context.severity.toUpperCase()}] Support Escalation - ${context.trigger}`;
+        const body = `
+Support Escalation #${escalationId}
+${'='.repeat(40)}
+
+Severity: ${context.severity.toUpperCase()}
+Trigger: ${context.trigger}
+Reason: ${context.reason}
+
+Customer: ${context.knowledgeContext?.customer?.companyName || 'Unknown'}
+Conversation ID: ${context.conversationId}
+
+View in Admin Portal:
+${config.escalation.adminBaseUrl}/support/escalations/${escalationId}
+
+---
+This escalation requires human attention.
+    `.trim();
+        const shortBody = `${severityEmoji} Escalation: ${context.trigger}. ${context.reason}. View: ${config.escalation.adminBaseUrl}/support/escalations/${escalationId}`;
+        return { subject, body, shortBody };
+    }
+    /**
+     * Send email notification (placeholder - would use Postmark)
+     */
+    async sendEmailNotification(escalationId, context, content) {
+        // This would integrate with Postmark
+        // For now, return success (actual implementation in delivery module)
+        return {
+            channel: 'email',
+            success: true,
+            messageId: `email-${escalationId}`,
+            timestamp: new Date().toISOString(),
+        };
+    }
+    /**
+     * Send SMS notification (placeholder - would use Twilio)
+     */
+    async sendSmsNotification(escalationId, context, content) {
+        // This would integrate with Twilio
+        return {
+            channel: 'sms',
+            success: true,
+            messageId: `sms-${escalationId}`,
+            timestamp: new Date().toISOString(),
+        };
+    }
+    /**
+     * Send Slack notification (placeholder - would use Slack API)
+     */
+    async sendSlackNotification(escalationId, context, content) {
+        // This would integrate with Slack API
+        return {
+            channel: 'slack',
+            success: true,
+            messageId: `slack-${escalationId}`,
+            timestamp: new Date().toISOString(),
+        };
+    }
+    /**
+     * Create database fallback when all notification channels fail
+     */
+    async createDatabaseFallback(escalationId, context) {
+        // Mark escalation as requiring attention via database
+        await this.supabase
+            .from('support_escalations')
+            .update({
+            context_data: {
+                ...this.buildContextData(context),
+                allChannelsFailed: true,
+                requiresDatabaseFallback: true,
+                fallbackCreatedAt: new Date().toISOString(),
+            },
+        })
+            .eq('id', escalationId);
+        // Log for monitoring
+        console.error(`CRITICAL: All escalation channels failed for escalation ${escalationId}. Database fallback created.`);
+    }
+    /**
+     * Track response attempt failures
+     */
+    async trackResponseAttempt(conversationId, success, error) {
+        // Get current attempt count from conversation
+        const { data: conversation } = await this.supabase
+            .from('support_conversations')
+            .select('metadata')
+            .eq('id', conversationId)
+            .single();
+        const currentAttempts = conversation?.metadata?.responseAttempts ?? 0;
+        const newAttemptCount = currentAttempts + 1;
+        // Update attempt count
+        await this.supabase
+            .from('support_conversations')
+            .update({
+            metadata: {
+                ...conversation?.metadata,
+                responseAttempts: newAttemptCount,
+                lastAttemptSuccess: success,
+                lastAttemptError: error,
+                lastAttemptAt: new Date().toISOString(),
+            },
+        })
+            .eq('id', conversationId);
+        return {
+            shouldEscalate: !success && newAttemptCount >= config.agent.maxResponseAttempts,
+            attemptCount: newAttemptCount,
+        };
+    }
+    /**
+     * Detect human takeover (human responded in escalated conversation)
+     */
+    async detectHumanTakeover(conversationId) {
+        // Check if there are human-sent messages after escalation
+        const { data } = await this.supabase
+            .from('support_messages')
+            .select('id')
+            .eq('conversation_id', conversationId)
+            .eq('direction', 'outbound')
+            .order('created_at', { ascending: false })
+            .limit(1);
+        // If there's a recent outbound message from a human, mark as taken over
+        return (data?.length ?? 0) > 0;
+    }
+    /**
+     * Resolve an escalation
+     */
+    async resolveEscalation(escalationId, resolution) {
+        await this.supabase
+            .from('support_escalations')
+            .update({
+            response_received_at: new Date().toISOString(),
+            response_action: resolution.action,
+            resolution_notes: resolution.notes,
+            assigned_to: resolution.responderId,
+        })
+            .eq('id', escalationId);
+    }
+}
+// =============================================================================
+// Singleton and Utility Functions
+// =============================================================================
+let escalationService = null;
+export function getEscalationService() {
+    if (!escalationService) {
+        escalationService = new EscalationService();
+    }
+    return escalationService;
+}
+/**
+ * Create and route an escalation
+ */
+export async function escalateConversation(context) {
+    return getEscalationService().escalate(context);
+}
+/**
+ * Build escalation context from analysis
+ */
+export function buildEscalationContext(message, analysis, knowledge, trigger, severity, reason, attemptedResponses) {
+    return {
+        conversationId: analysis.conversationId,
+        messageId: message.id,
+        customerId: knowledge.customer?.id,
+        trigger,
+        severity,
+        reason,
+        analysisResult: analysis,
+        attemptedResponses,
+        knowledgeContext: knowledge,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/escalation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/escalation/index.ts"],"names":[],"mappings":"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"}

package/dist/extraction/deduplication.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Deduplication Module
+ *
+ * Detects duplicate Q&A pairs using content hashing and optional embedding similarity.
+ * Prevents storage of near-identical entries in the knowledge base.
+ */
+export interface DeduplicationResult {
+    isDuplicate: boolean;
+    duplicateId?: string;
+    similarity?: number;
+    method: 'hash' | 'embedding' | 'none';
+    contentHash: string;
+}
+export interface DeduplicationConfig {
+    similarityThreshold: number;
+    useEmbeddingSimilarity: boolean;
+    supabaseUrl: string;
+    supabaseServiceRoleKey: string;
+}
+export interface QAContent {
+    questionSubject?: string;
+    questionText: string;
+    responseText: string;
+}
+export declare class DeduplicationService {
+    private config;
+    private supabase;
+    private hashCache;
+    constructor(config: DeduplicationConfig);
+    /**
+     * Generate content hash for a Q&A pair
+     *
+     * Hash is based on normalized question + response text.
+     * Subject is not included as it varies more between duplicates.
+     */
+    generateContentHash(content: QAContent): string;
+    /**
+     * Check if content is a duplicate
+     */
+    checkDuplicate(content: QAContent): Promise<DeduplicationResult>;
+    /**
+     * Check for hash match in database
+     */
+    private checkHashInDatabase;
+    /**
+     * Check for similar entries using embedding similarity
+     * Note: Requires the entry to have an embedding
+     */
+    private checkEmbeddingSimilarity;
+    /**
+     * Add hash to local cache (for batch operations)
+     */
+    addToCache(contentHash: string): void;
+    /**
+     * Clear local hash cache
+     */
+    clearCache(): void;
+    /**
+     * Load existing hashes from database into cache
+     */
+    loadHashCache(limit?: number): Promise<number>;
+    /**
+     * Batch check for duplicates
+     */
+    checkBatchDuplicates(contents: QAContent[]): Promise<Map<string, DeduplicationResult>>;
+    /**
+     * Normalize text for consistent hashing
+     */
+    private normalizeText;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): {
+        size: number;
+    };
+    /**
+     * Update configuration
+     */
+    updateConfig(config: Partial<DeduplicationConfig>): void;
+}
+/**
+ * Get singleton deduplication service instance
+ */
+export declare function getDeduplicationService(): DeduplicationService;
+/**
+ * Reset the singleton (for testing)
+ */
+export declare function resetDeduplicationService(): void;
+/**
+ * Quick content hash generation
+ */
+export declare function hashContent(content: QAContent): string;
+/**
+ * Quick duplicate check
+ */
+export declare function isDuplicate(content: QAContent): Promise<boolean>;
+//# sourceMappingURL=deduplication.d.ts.map

package/dist/extraction/deduplication.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deduplication.d.ts","sourceRoot":"","sources":["../../src/extraction/deduplication.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;IACtC,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAElC,mBAAmB,EAAE,MAAM,CAAC;IAG5B,sBAAsB,EAAE,OAAO,CAAC;IAGhC,WAAW,EAAE,MAAM,CAAC;IACpB,sBAAsB,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,SAAS;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;CACtB;AAeD,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,QAAQ,CAAiB;IAGjC,OAAO,CAAC,SAAS,CAA0B;gBAE/B,MAAM,EAAE,mBAAmB;IAKvC;;;;;OAKG;IACH,mBAAmB,CAAC,OAAO,EAAE,SAAS,GAAG,MAAM;IAY/C;;OAEG;IACG,cAAc,CAAC,OAAO,EAAE,SAAS,GAAG,OAAO,CAAC,mBAAmB,CAAC;IA6CtE;;OAEG;YACW,mBAAmB;IAiBjC;;;OAGG;YACW,wBAAwB;IAUtC;;OAEG;IACH,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAIrC;;OAEG;IACH,UAAU,IAAI,IAAI;IAIlB;;OAEG;IACG,aAAa,CAAC,KAAK,GAAE,MAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IAmB3D;;OAEG;IACG,oBAAoB,CACxB,QAAQ,EAAE,SAAS,EAAE,GACpB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IAyE5C;;OAEG;IACH,OAAO,CAAC,aAAa;IASrB;;OAEG;IACH,aAAa,IAAI;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE;IAIjC;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,mBAAmB,CAAC,GAAG,IAAI;CAGzD;AAQD;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,oBAAoB,CAkB9D;AAED;;GAEG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD;AAMD;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,SAAS,GAAG,MAAM,CAEtD;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAGtE"}