catalist-support-agent 1.0.0

package/dist/intake/twilio.js

@@ -0,0 +1,283 @@
+/**
+ * Twilio SMS Webhook Handler
+ *
+ * Receives incoming SMS messages via Twilio webhook, validates signatures,
+ * and normalizes SMS content into the standard message format.
+ */
+import { createHmac, timingSafeEqual } from 'crypto';
+import { config } from '../config.js';
+import { IntakeError, WebhookValidationError } from '../errors.js';
+import { normalizeTwilioSms, generateContentHash, validateMessageContent, scanAndAnnotateMessage, normalizePhoneNumber, } from './normalizer.js';
+// =============================================================================
+// Signature Validation
+// =============================================================================
+/**
+ * Validate Twilio webhook signature using HMAC-SHA1
+ *
+ * Twilio signs webhooks using the auth token and the full URL + params
+ */
+export function validateTwilioSignature(signature, url, params, authToken) {
+    if (!signature || !authToken) {
+        return false;
+    }
+    // Build the string to sign
+    // Twilio sorts the params alphabetically and concatenates
+    const sortedKeys = Object.keys(params).sort();
+    const paramString = sortedKeys.map((key) => `${key}${params[key]}`).join('');
+    const stringToSign = url + paramString;
+    // Generate expected signature
+    const expectedSignature = createHmac('sha1', authToken)
+        .update(stringToSign, 'utf-8')
+        .digest('base64');
+    // Timing-safe comparison
+    try {
+        const sig1 = Buffer.from(signature);
+        const sig2 = Buffer.from(expectedSignature);
+        if (sig1.length !== sig2.length) {
+            return false;
+        }
+        return timingSafeEqual(sig1, sig2);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Validate Twilio webhook request
+ */
+export function validateTwilioWebhook(signature, url, params) {
+    const authToken = config.twilio.authToken;
+    if (!authToken) {
+        // If no auth token configured, skip signature validation but check required fields
+        return !!(params.MessageSid && params.From && params.To);
+    }
+    return validateTwilioSignature(signature, url, params, authToken);
+}
+// =============================================================================
+// SMS Processing
+// =============================================================================
+/**
+ * Parse Twilio webhook body (URL-encoded)
+ */
+export function parseTwilioBody(body) {
+    const params = new URLSearchParams(body);
+    const result = {};
+    for (const [key, value] of params.entries()) {
+        result[key] = value;
+    }
+    return result;
+}
+/**
+ * Process an inbound Twilio SMS
+ */
+export async function processTwilioSms(payload) {
+    try {
+        // Normalize the SMS into standard message format
+        const message = normalizeTwilioSms(payload);
+        // Validate content exists
+        validateMessageContent(message);
+        // Generate content hash for deduplication
+        const contentHash = generateContentHash(message);
+        // Scan for forbidden terms
+        const { hasForbiddenTerms, detectedTerms } = scanAndAnnotateMessage(message);
+        return {
+            success: true,
+            message,
+            contentHash,
+            hasForbiddenTerms,
+            detectedTerms,
+        };
+    }
+    catch (error) {
+        if (error instanceof IntakeError) {
+            return {
+                success: false,
+                hasForbiddenTerms: false,
+                detectedTerms: [],
+                error: error.message,
+            };
+        }
+        return {
+            success: false,
+            hasForbiddenTerms: false,
+            detectedTerms: [],
+            error: error instanceof Error ? error.message : 'Unknown error processing SMS',
+        };
+    }
+}
+/**
+ * Full webhook handler for Twilio inbound SMS
+ */
+export async function handleTwilioInbound(rawBody, signature, webhookUrl) {
+    // Parse URL-encoded body
+    const payload = parseTwilioBody(rawBody);
+    // Convert to params object for signature validation
+    const params = {};
+    for (const [key, value] of Object.entries(payload)) {
+        if (typeof value === 'string') {
+            params[key] = value;
+        }
+    }
+    // Validate webhook signature
+    if (!validateTwilioWebhook(signature, webhookUrl, params)) {
+        throw new WebhookValidationError('sms', {
+            context: { reason: 'Invalid Twilio signature' },
+        });
+    }
+    // Process the SMS
+    return processTwilioSms(payload);
+}
+// =============================================================================
+// SMS Utilities
+// =============================================================================
+/**
+ * Check if message is a STOP/unsubscribe request
+ */
+export function isOptOutMessage(body) {
+    const normalized = body.trim().toLowerCase();
+    const optOutKeywords = [
+        'stop',
+        'unsubscribe',
+        'cancel',
+        'end',
+        'quit',
+        'optout',
+        'opt out',
+        'stopall',
+        'stop all',
+    ];
+    return optOutKeywords.includes(normalized);
+}
+/**
+ * Check if message is a help request
+ */
+export function isHelpRequest(body) {
+    const normalized = body.trim().toLowerCase();
+    const helpKeywords = ['help', 'info', 'support'];
+    return helpKeywords.includes(normalized);
+}
+/**
+ * Classify SMS message type
+ */
+export function classifySms(sms) {
+    const body = sms.Body?.trim() ?? '';
+    if (!body) {
+        return {
+            shouldProcess: false,
+            reason: 'Empty message',
+            classification: 'empty',
+        };
+    }
+    if (isOptOutMessage(body)) {
+        return {
+            shouldProcess: false,
+            reason: 'Opt-out request',
+            classification: 'opt_out',
+        };
+    }
+    if (isHelpRequest(body)) {
+        return {
+            shouldProcess: true,
+            classification: 'help',
+        };
+    }
+    return {
+        shouldProcess: true,
+        classification: 'support',
+    };
+}
+// =============================================================================
+// MMS Handling
+// =============================================================================
+/**
+ * Check if SMS includes media attachments (MMS)
+ */
+export function hasMmsAttachments(sms) {
+    const numMedia = parseInt(sms.NumMedia || '0', 10);
+    return numMedia > 0;
+}
+/**
+ * Extract MMS media URLs
+ */
+export function extractMmsMedia(sms) {
+    const numMedia = parseInt(sms.NumMedia || '0', 10);
+    const media = [];
+    for (let i = 0; i < numMedia; i++) {
+        const urlKey = `MediaUrl${i}`;
+        const typeKey = `MediaContentType${i}`;
+        const url = sms[urlKey];
+        const contentType = sms[typeKey] || 'application/octet-stream';
+        if (url) {
+            media.push({ url, contentType });
+        }
+    }
+    return media;
+}
+// =============================================================================
+// Phone Number Utilities
+// =============================================================================
+/**
+ * Extract country code from phone number
+ */
+export function extractCountryCode(phone) {
+    const normalized = normalizePhoneNumber(phone);
+    // Common country codes
+    const countryCodes = {
+        '+1': 'US/CA',
+        '+44': 'UK',
+        '+61': 'AU',
+        '+49': 'DE',
+        '+33': 'FR',
+        '+34': 'ES',
+        '+39': 'IT',
+        '+81': 'JP',
+        '+86': 'CN',
+        '+91': 'IN',
+    };
+    for (const [code, country] of Object.entries(countryCodes)) {
+        if (normalized.startsWith(code)) {
+            return country;
+        }
+    }
+    return undefined;
+}
+/**
+ * Determine if phone number is US/Canada
+ */
+export function isNorthAmericanNumber(phone) {
+    const normalized = normalizePhoneNumber(phone);
+    return normalized.startsWith('+1');
+}
+// =============================================================================
+// Response Generation for Twilio
+// =============================================================================
+/**
+ * Generate TwiML response for immediate reply
+ */
+export function generateTwimlResponse(message) {
+    if (!message) {
+        // Empty response - no auto-reply
+        return '<?xml version="1.0" encoding="UTF-8"?><Response></Response>';
+    }
+    // Escape XML entities
+    const escaped = message
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+    return `<?xml version="1.0" encoding="UTF-8"?><Response><Message>${escaped}</Message></Response>`;
+}
+/**
+ * Generate TwiML for opt-out confirmation
+ */
+export function generateOptOutResponse() {
+    return generateTwimlResponse("You've been unsubscribed from Catalist support messages. Reply HELP if you need assistance.");
+}
+/**
+ * Generate TwiML for help response
+ */
+export function generateHelpResponse() {
+    return generateTwimlResponse('Catalist Support: Reply with your question and we\'ll get back to you. For urgent matters, email support@catalist.deals');
+}
+//# sourceMappingURL=twilio.js.map

package/dist/intake/twilio.js.map

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

package/dist/knowledge/index.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Knowledge Retrieval Module
+ *
+ * Retrieves relevant context for response generation:
+ * - Customer data from clients table
+ * - Product information from catalog
+ * - Order history and status
+ * - Policy and FAQ content
+ * - Similar historical conversations
+ * - Pre-approved response templates
+ */
+import { type Config } from '../config.js';
+import type { KnowledgeContext, CustomerContext, ProductContext, OrderContext, SimilarConversation, ResponseTemplate, InboundMessage, AnalysisResult, IntentCategory, CustomerId } from '../types.js';
+export declare class KnowledgeRetrievalService {
+    private supabase;
+    private embeddingService;
+    private effectiveConfig;
+    constructor(configOverride?: Config);
+    /**
+     * Retrieve complete knowledge context for a message
+     */
+    retrieveContext(message: InboundMessage, analysis: AnalysisResult): Promise<KnowledgeContext>;
+    /**
+     * Retrieve customer data by sender identifiers
+     *
+     * Note: Uses the "User" table (not "Client") per actual Catalist schema
+     */
+    retrieveCustomerData(message: InboundMessage): Promise<CustomerContext | undefined>;
+    /**
+     * Map database User record to CustomerContext
+     */
+    private mapUserToCustomerContext;
+    /**
+     * Retrieve order history for a customer with associated Invoice data
+     *
+     * Note: Uses "PurchaseOrder" table (not "Order") per actual Catalist schema
+     * Also fetches Invoice data for each order via the Invoice table
+     */
+    retrieveOrderHistory(customerId: CustomerId, specificOrderNumbers?: string[]): Promise<OrderContext[]>;
+    /**
+     * Retrieve product information by name or SKU
+     *
+     * Note: Uses actual Catalist Catalog schema with selling_price, selling_status
+     */
+    retrieveProductInfo(productNames?: string[], productSkus?: string[]): Promise<ProductContext[]>;
+    /**
+     * Map Catalog record to ProductContext
+     *
+     * Note: Catalist uses selling_status (boolean) not quantity
+     */
+    private mapCatalogToProductContext;
+    /**
+     * Retrieve response templates/knowledge for an intent
+     *
+     * Note: Uses support_knowledge table which stores Q&A pairs
+     */
+    retrieveTemplates(intent: IntentCategory): Promise<ResponseTemplate[]>;
+    /**
+     * Retrieve similar historical conversations using semantic search
+     *
+     * Uses pgvector for embedding similarity search against gmail_knowledge_entries.
+     * Falls back to full-text search if embedding service is unavailable.
+     */
+    retrieveSimilarConversations(messageText: string, intent: IntentCategory): Promise<SimilarConversation[]>;
+    /**
+     * Map resolution indicator string to ResolutionType enum
+     */
+    private mapResolutionIndicator;
+    /**
+     * Build a summary string from question subject and text
+     */
+    private buildConversationSummary;
+}
+export declare function getKnowledgeRetrievalService(configOverride?: Config): KnowledgeRetrievalService;
+/**
+ * Retrieve knowledge context for a message
+ */
+export declare function retrieveKnowledgeContext(message: InboundMessage, analysis: AnalysisResult): Promise<KnowledgeContext>;
+/**
+ * Quick customer lookup
+ */
+export declare function lookupCustomer(message: InboundMessage): Promise<CustomerContext | undefined>;
+/**
+ * Check if knowledge context has sufficient data for autonomous response
+ */
+export declare function hassufficientContext(context: KnowledgeContext): boolean;
+/**
+ * Calculate overall context confidence
+ */
+export declare function calculateContextConfidence(context: KnowledgeContext): number;
+export { InvoiceResolverService, getInvoiceResolverService, resolveInvoice, isInvoiceRelatedQuery, } from './invoice-resolver.js';
+/**
+ * Alias for getKnowledgeRetrievalService (used by main index.ts)
+ */
+export declare const getKnowledgeService: typeof getKnowledgeRetrievalService;
+/**
+ * Alias for retrieveKnowledgeContext (used by main index.ts)
+ */
+export declare const retrieveKnowledge: typeof retrieveKnowledgeContext;
+//# sourceMappingURL=index.d.ts.map

package/dist/knowledge/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/knowledge/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAU,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AAInD,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,YAAY,EAGZ,mBAAmB,EACnB,gBAAgB,EAEhB,cAAc,EACd,cAAc,EACd,cAAc,EACd,UAAU,EACX,MAAM,aAAa,CAAC;AAOrB,qBAAa,yBAAyB;IACpC,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,gBAAgB,CAAiC;IACzD,OAAO,CAAC,eAAe,CAAS;gBAEpB,cAAc,CAAC,EAAE,MAAM;IAmBnC;;OAEG;IACG,eAAe,CACnB,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,cAAc,GACvB,OAAO,CAAC,gBAAgB,CAAC;IAsG5B;;;;OAIG;IACG,oBAAoB,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC;IAsCzF;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAoBhC;;;;;OAKG;IACG,oBAAoB,CACxB,UAAU,EAAE,UAAU,EACtB,oBAAoB,CAAC,EAAE,MAAM,EAAE,GAC9B,OAAO,CAAC,YAAY,EAAE,CAAC;IAsE1B;;;;OAIG;IACG,mBAAmB,CACvB,YAAY,CAAC,EAAE,MAAM,EAAE,EACvB,WAAW,CAAC,EAAE,MAAM,EAAE,GACrB,OAAO,CAAC,cAAc,EAAE,CAAC;IAsC5B;;;;OAIG;IACH,OAAO,CAAC,0BAA0B;IAgClC;;;;OAIG;IACG,iBAAiB,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAwC5E;;;;;OAKG;IACG,4BAA4B,CAChC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,cAAc,GACrB,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAkEjC;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAuB9B;;OAEG;IACH,OAAO,CAAC,wBAAwB;CAiBjC;AAQD,wBAAgB,4BAA4B,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,yBAAyB,CAU/F;AAED;;GAEG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,cAAc,GACvB,OAAO,CAAC,gBAAgB,CAAC,CAE3B;AAED;;GAEG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAEtC;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAUvE;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAe5E;AAMD,OAAO,EACL,sBAAsB,EACtB,yBAAyB,EACzB,cAAc,EACd,qBAAqB,GACtB,MAAM,uBAAuB,CAAC;AAM/B;;GAEG;AACH,eAAO,MAAM,mBAAmB,qCAA+B,CAAC;AAEhE;;GAEG;AACH,eAAO,MAAM,iBAAiB,iCAA2B,CAAC"}