catalist-support-agent 1.0.0

package/dist/knowledge/invoice-resolver.js

@@ -0,0 +1,267 @@
+/**
+ * Invoice Resolution Service
+ *
+ * Intelligently resolves which invoice a customer is asking about to avoid
+ * unnecessary "please provide your invoice number" responses.
+ *
+ * Resolution Priority:
+ * 1. Invoice number extracted from message/subject -> Direct lookup
+ * 2. Customer has 1 unpaid invoice -> Auto-resolve to that (high confidence)
+ * 3. Customer has 0 unpaid but has invoices -> Use most recent (medium confidence)
+ * 4. Multiple unpaid invoices, no number given -> Cannot resolve (return null)
+ */
+import { createClient } from '@supabase/supabase-js';
+import { config } from '../config.js';
+// =============================================================================
+// Invoice Number Patterns
+// =============================================================================
+/**
+ * Catalist invoice numbers are 7-digit numbers starting with 91
+ * Examples: 9107893, 9107894
+ */
+const CATALIST_INVOICE_PATTERN = /\b(91\d{5})\b/g;
+/**
+ * General invoice reference patterns
+ * Matches: "invoice #123", "INV-123", "invoice 123"
+ */
+const GENERAL_INVOICE_PATTERN = /(?:invoice|inv)[\s#:\-]*([A-Z0-9-]{4,20})/gi;
+// =============================================================================
+// Invoice Resolver Service
+// =============================================================================
+export class InvoiceResolverService {
+    supabase;
+    constructor() {
+        this.supabase = createClient(config.supabase.url, config.supabase.serviceRoleKey);
+    }
+    /**
+     * Resolve which invoice a customer is asking about
+     *
+     * @param customerId - The customer's ID (from User table)
+     * @param extractedInvoiceNumbers - Invoice numbers already extracted by entity extraction
+     * @param messageText - The message body
+     * @param subject - The email subject line (optional)
+     * @returns ResolvedInvoice if we can determine which invoice, null otherwise
+     */
+    async resolveInvoice(customerId, extractedInvoiceNumbers, messageText, subject) {
+        // Combine subject and message for invoice number extraction
+        const fullText = subject ? `${subject}\n${messageText}` : messageText;
+        // Step 1: Try to find invoice number from extracted entities or our own extraction
+        const invoiceNumbers = this.extractInvoiceNumbers(fullText, extractedInvoiceNumbers);
+        const firstInvoiceNumber = invoiceNumbers[0];
+        if (firstInvoiceNumber) {
+            // Try to look up the invoice by number
+            const invoice = await this.lookupByNumber(firstInvoiceNumber, customerId);
+            if (invoice) {
+                console.info('Invoice resolution:', {
+                    customerId,
+                    source: 'extracted_number',
+                    confidence: 'explicit',
+                    invoiceId: invoice.invoiceId,
+                    invoiceNumber: invoice.invoiceNumber,
+                });
+                return {
+                    invoice,
+                    confidence: 'explicit',
+                    source: 'extracted_number',
+                };
+            }
+            // Invoice number provided but not found or belongs to different customer
+            // Fall through to auto-resolution
+        }
+        // Step 2: Get customer's invoices for auto-resolution
+        const invoices = await this.getCustomerInvoices(customerId);
+        if (invoices.length === 0) {
+            console.info('Invoice resolution:', {
+                customerId,
+                source: 'unresolved',
+                confidence: 'none',
+                reason: 'no_invoices',
+            });
+            return null;
+        }
+        // Step 3: Filter to unpaid invoices (status = 'issued')
+        const unpaid = invoices.filter((inv) => inv.status === 'issued');
+        // Step 4: Apply resolution logic
+        if (unpaid.length === 1) {
+            const singleUnpaid = unpaid[0];
+            // Single unpaid invoice - high confidence this is what they're asking about
+            console.info('Invoice resolution:', {
+                customerId,
+                source: 'single_unpaid',
+                confidence: 'high',
+                invoiceId: singleUnpaid.invoiceId,
+                invoiceNumber: singleUnpaid.invoiceNumber,
+            });
+            return {
+                invoice: singleUnpaid,
+                confidence: 'high',
+                source: 'single_unpaid',
+            };
+        }
+        if (unpaid.length === 0) {
+            // No unpaid invoices - use the most recent one
+            const mostRecent = this.getMostRecentInvoice(invoices);
+            if (mostRecent) {
+                console.info('Invoice resolution:', {
+                    customerId,
+                    source: 'most_recent',
+                    confidence: 'medium',
+                    invoiceId: mostRecent.invoiceId,
+                    invoiceNumber: mostRecent.invoiceNumber,
+                });
+                return {
+                    invoice: mostRecent,
+                    confidence: 'medium',
+                    source: 'most_recent',
+                };
+            }
+        }
+        // Multiple unpaid invoices and no number provided - cannot resolve
+        console.info('Invoice resolution:', {
+            customerId,
+            source: 'unresolved',
+            confidence: 'none',
+            reason: 'multiple_unpaid',
+            unpaidCount: unpaid.length,
+        });
+        return null;
+    }
+    /**
+     * Extract invoice numbers from text using multiple patterns
+     */
+    extractInvoiceNumbers(text, existingNumbers) {
+        const numbers = new Set(existingNumbers ?? []);
+        // Extract Catalist-specific invoice numbers (7 digits starting with 91)
+        const catalistMatches = text.matchAll(CATALIST_INVOICE_PATTERN);
+        for (const match of catalistMatches) {
+            if (match[1]) {
+                numbers.add(match[1]);
+            }
+        }
+        // Extract general invoice references
+        const generalMatches = text.matchAll(GENERAL_INVOICE_PATTERN);
+        for (const match of generalMatches) {
+            if (match[1]) {
+                numbers.add(match[1]);
+            }
+        }
+        return Array.from(numbers);
+    }
+    /**
+     * Look up an invoice by number, verifying it belongs to the customer
+     */
+    async lookupByNumber(invoiceNumber, customerId) {
+        const { data, error } = await this.supabase
+            .from('Invoice')
+            .select(`
+        id, order_id, invoice_num, status, total, subtotal,
+        fees_total, tax_total, shipping_total, discount_total,
+        issued_at, due_at, paid_at, pdf_url, notes, user_id
+      `)
+            .eq('invoice_num', invoiceNumber)
+            .single();
+        if (error || !data) {
+            return null;
+        }
+        // Security check: verify invoice belongs to this customer
+        if (String(data.user_id) !== String(customerId)) {
+            console.warn('Invoice lookup: invoice belongs to different customer', {
+                invoiceNumber,
+                requestedBy: customerId,
+                actualOwner: data.user_id,
+            });
+            return null;
+        }
+        return this.mapToInvoiceContext(data);
+    }
+    /**
+     * Get all invoices for a customer
+     */
+    async getCustomerInvoices(customerId) {
+        const { data, error } = await this.supabase
+            .from('Invoice')
+            .select(`
+        id, order_id, invoice_num, status, total, subtotal,
+        fees_total, tax_total, shipping_total, discount_total,
+        issued_at, due_at, paid_at, pdf_url, notes
+      `)
+            .eq('user_id', customerId)
+            .order('issued_at', { ascending: false })
+            .limit(20);
+        if (error || !data) {
+            return [];
+        }
+        return data.map(this.mapToInvoiceContext);
+    }
+    /**
+     * Get the most recent invoice from a list
+     */
+    getMostRecentInvoice(invoices) {
+        if (invoices.length === 0) {
+            return null;
+        }
+        // Already sorted by issued_at descending from the query
+        const first = invoices[0];
+        return first ?? null;
+    }
+    /**
+     * Map database record to InvoiceContext
+     */
+    mapToInvoiceContext(record) {
+        return {
+            invoiceId: record.id,
+            invoiceNumber: record.invoice_num,
+            status: record.status,
+            total: Number(record.total) || 0,
+            subtotal: Number(record.subtotal) || 0,
+            feesTotal: Number(record.fees_total) || 0,
+            taxTotal: Number(record.tax_total) || 0,
+            shippingTotal: Number(record.shipping_total) || 0,
+            discountTotal: Number(record.discount_total) || 0,
+            issuedAt: record.issued_at,
+            dueAt: record.due_at,
+            paidAt: record.paid_at,
+            pdfUrl: record.pdf_url,
+            notes: record.notes,
+        };
+    }
+    /**
+     * Get count of unpaid invoices for a customer
+     * Useful for the response generation to know if clarification is needed
+     */
+    async getUnpaidInvoiceCount(customerId) {
+        const { count, error } = await this.supabase
+            .from('Invoice')
+            .select('id', { count: 'exact', head: true })
+            .eq('user_id', customerId)
+            .eq('status', 'issued');
+        if (error) {
+            return 0;
+        }
+        return count ?? 0;
+    }
+}
+// =============================================================================
+// Singleton and Utility Functions
+// =============================================================================
+let invoiceResolverService = null;
+export function getInvoiceResolverService() {
+    if (!invoiceResolverService) {
+        invoiceResolverService = new InvoiceResolverService();
+    }
+    return invoiceResolverService;
+}
+/**
+ * Resolve which invoice a customer is asking about
+ */
+export async function resolveInvoice(customerId, extractedInvoiceNumbers, messageText, subject) {
+    return getInvoiceResolverService().resolveInvoice(customerId, extractedInvoiceNumbers, messageText, subject);
+}
+/**
+ * Check if text contains invoice-related keywords
+ */
+export function isInvoiceRelatedQuery(text) {
+    const invoiceKeywords = /\b(invoice|invoices|billing|bill|payment|pay|receipt|statement)\b/i;
+    return invoiceKeywords.test(text);
+}
+//# sourceMappingURL=invoice-resolver.js.map

package/dist/knowledge/invoice-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoice-resolver.js","sourceRoot":"","sources":["../../src/knowledge/invoice-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,YAAY,EAAkB,MAAM,uBAAuB,CAAC;AACrE,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAGtC,gFAAgF;AAChF,0BAA0B;AAC1B,gFAAgF;AAEhF;;;GAGG;AACH,MAAM,wBAAwB,GAAG,gBAAgB,CAAC;AAElD;;;GAGG;AACH,MAAM,uBAAuB,GAAG,6CAA6C,CAAC;AAE9E,gFAAgF;AAChF,2BAA2B;AAC3B,gFAAgF;AAEhF,MAAM,OAAO,sBAAsB;IACzB,QAAQ,CAAiB;IAEjC;QACE,IAAI,CAAC,QAAQ,GAAG,YAAY,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;IACpF,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,cAAc,CAClB,UAAsB,EACtB,uBAA6C,EAC7C,WAAmB,EACnB,OAAgB;QAEhB,4DAA4D;QAC5D,MAAM,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,KAAK,WAAW,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC;QAEtE,mFAAmF;QACnF,MAAM,cAAc,GAAG,IAAI,CAAC,qBAAqB,CAAC,QAAQ,EAAE,uBAAuB,CAAC,CAAC;QAErF,MAAM,kBAAkB,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;QAC7C,IAAI,kBAAkB,EAAE,CAAC;YACvB,uCAAuC;YACvC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,kBAAkB,EAAE,UAAU,CAAC,CAAC;YAC1E,IAAI,OAAO,EAAE,CAAC;gBACZ,OAAO,CAAC,IAAI,CAAC,qBAAqB,EAAE;oBAClC,UAAU;oBACV,MAAM,EAAE,kBAAkB;oBAC1B,UAAU,EAAE,UAAU;oBACtB,SAAS,EAAE,OAAO,CAAC,SAAS;oBAC5B,aAAa,EAAE,OAAO,CAAC,aAAa;iBACrC,CAAC,CAAC;gBACH,OAAO;oBACL,OAAO;oBACP,UAAU,EAAE,UAAU;oBACtB,MAAM,EAAE,kBAAkB;iBAC3B,CAAC;YACJ,CAAC;YACD,yEAAyE;YACzE,kCAAkC;QACpC,CAAC;QAED,sDAAsD;QACtD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,mBAAmB,CAAC,UAAU,CAAC,CAAC;QAE5D,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO,CAAC,IAAI,CAAC,qBAAqB,EAAE;gBAClC,UAAU;gBACV,MAAM,EAAE,YAAY;gBACpB,UAAU,EAAE,MAAM;gBAClB,MAAM,EAAE,aAAa;aACtB,CAAC,CAAC;YACH,OAAO,IAAI,CAAC;QACd,CAAC;QAED,wDAAwD;QACxD,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC;QAEjE,iCAAiC;QACjC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,MAAM,YAAY,GAAG,MAAM,CAAC,CAAC,CAAE,CAAC;YAChC,4EAA4E;YAC5E,OAAO,CAAC,IAAI,CAAC,qBAAqB,EAAE;gBAClC,UAAU;gBACV,MAAM,EAAE,eAAe;gBACvB,UAAU,EAAE,MAAM;gBAClB,SAAS,EAAE,YAAY,CAAC,SAAS;gBACjC,aAAa,EAAE,YAAY,CAAC,aAAa;aAC1C,CAAC,CAAC;YACH,OAAO;gBACL,OAAO,EAAE,YAAY;gBACrB,UAAU,EAAE,MAAM;gBAClB,MAAM,EAAE,eAAe;aACxB,CAAC;QACJ,CAAC;QAED,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,+CAA+C;YAC/C,MAAM,UAAU,GAAG,IAAI,CAAC,oBAAoB,CAAC,QAAQ,CAAC,CAAC;YACvD,IAAI,UAAU,EAAE,CAAC;gBACf,OAAO,CAAC,IAAI,CAAC,qBAAqB,EAAE;oBAClC,UAAU;oBACV,MAAM,EAAE,aAAa;oBACrB,UAAU,EAAE,QAAQ;oBACpB,SAAS,EAAE,UAAU,CAAC,SAAS;oBAC/B,aAAa,EAAE,UAAU,CAAC,aAAa;iBACxC,CAAC,CAAC;gBACH,OAAO;oBACL,OAAO,EAAE,UAAU;oBACnB,UAAU,EAAE,QAAQ;oBACpB,MAAM,EAAE,aAAa;iBACtB,CAAC;YACJ,CAAC;QACH,CAAC;QAED,mEAAmE;QACnE,OAAO,CAAC,IAAI,CAAC,qBAAqB,EAAE;YAClC,UAAU;YACV,MAAM,EAAE,YAAY;YACpB,UAAU,EAAE,MAAM;YAClB,MAAM,EAAE,iBAAiB;YACzB,WAAW,EAAE,MAAM,CAAC,MAAM;SAC3B,CAAC,CAAC;QACH,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACK,qBAAqB,CAC3B,IAAY,EACZ,eAA0B;QAE1B,MAAM,OAAO,GAAG,IAAI,GAAG,CAAS,eAAe,IAAI,EAAE,CAAC,CAAC;QAEvD,wEAAwE;QACxE,MAAM,eAAe,GAAG,IAAI,CAAC,QAAQ,CAAC,wBAAwB,CAAC,CAAC;QAChE,KAAK,MAAM,KAAK,IAAI,eAAe,EAAE,CAAC;YACpC,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;gBACb,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;YACxB,CAAC;QACH,CAAC;QAED,qCAAqC;QACrC,MAAM,cAAc,GAAG,IAAI,CAAC,QAAQ,CAAC,uBAAuB,CAAC,CAAC;QAC9D,KAAK,MAAM,KAAK,IAAI,cAAc,EAAE,CAAC;YACnC,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;gBACb,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;YACxB,CAAC;QACH,CAAC;QAED,OAAO,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC7B,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,cAAc,CAC1B,aAAqB,EACrB,UAAsB;QAEtB,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,QAAQ;aACxC,IAAI,CAAC,SAAS,CAAC;aACf,MAAM,CAAC;;;;OAIP,CAAC;aACD,EAAE,CAAC,aAAa,EAAE,aAAa,CAAC;aAChC,MAAM,EAAE,CAAC;QAEZ,IAAI,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC;YACnB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,0DAA0D;QAC1D,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC;YAChD,OAAO,CAAC,IAAI,CAAC,uDAAuD,EAAE;gBACpE,aAAa;gBACb,WAAW,EAAE,UAAU;gBACvB,WAAW,EAAE,IAAI,CAAC,OAAO;aAC1B,CAAC,CAAC;YACH,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC;IACxC,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,mBAAmB,CAAC,UAAsB;QACtD,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,QAAQ;aACxC,IAAI,CAAC,SAAS,CAAC;aACf,MAAM,CAAC;;;;OAIP,CAAC;aACD,EAAE,CAAC,SAAS,EAAE,UAAU,CAAC;aACzB,KAAK,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;aACxC,KAAK,CAAC,EAAE,CAAC,CAAC;QAEb,IAAI,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC;YACnB,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;IAC5C,CAAC;IAED;;OAEG;IACK,oBAAoB,CAAC,QAA0B;QACrD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO,IAAI,CAAC;QACd,CAAC;QAED,wDAAwD;QACxD,MAAM,KAAK,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;QAC1B,OAAO,KAAK,IAAI,IAAI,CAAC;IACvB,CAAC;IAED;;OAEG;IACK,mBAAmB,CAAC,MAe3B;QACC,OAAO;YACL,SAAS,EAAE,MAAM,CAAC,EAAE;YACpB,aAAa,EAAE,MAAM,CAAC,WAAW;YACjC,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;YAChC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;YACtC,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC;YACzC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC;YACvC,aAAa,EAAE,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC;YACjD,aAAa,EAAE,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC;YACjD,QAAQ,EAAE,MAAM,CAAC,SAAS;YAC1B,KAAK,EAAE,MAAM,CAAC,MAAM;YACpB,MAAM,EAAE,MAAM,CAAC,OAAO;YACtB,MAAM,EAAE,MAAM,CAAC,OAAO;YACtB,KAAK,EAAE,MAAM,CAAC,KAAK;SACpB,CAAC;IACJ,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,qBAAqB,CAAC,UAAsB;QAChD,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,QAAQ;aACzC,IAAI,CAAC,SAAS,CAAC;aACf,MAAM,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;aAC5C,EAAE,CAAC,SAAS,EAAE,UAAU,CAAC;aACzB,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QAE1B,IAAI,KAAK,EAAE,CAAC;YACV,OAAO,CAAC,CAAC;QACX,CAAC;QAED,OAAO,KAAK,IAAI,CAAC,CAAC;IACpB,CAAC;CACF;AAED,gFAAgF;AAChF,kCAAkC;AAClC,gFAAgF;AAEhF,IAAI,sBAAsB,GAAkC,IAAI,CAAC;AAEjE,MAAM,UAAU,yBAAyB;IACvC,IAAI,CAAC,sBAAsB,EAAE,CAAC;QAC5B,sBAAsB,GAAG,IAAI,sBAAsB,EAAE,CAAC;IACxD,CAAC;IACD,OAAO,sBAAsB,CAAC;AAChC,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,UAAsB,EACtB,uBAA6C,EAC7C,WAAmB,EACnB,OAAgB;IAEhB,OAAO,yBAAyB,EAAE,CAAC,cAAc,CAC/C,UAAU,EACV,uBAAuB,EACvB,WAAW,EACX,OAAO,CACR,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,MAAM,eAAe,GAAG,oEAAoE,CAAC;IAC7F,OAAO,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACpC,CAAC"}