/** * Core Receipt Matcher: pure matching utility functions extracted from the * receipt-ocr extension so they can be reused by the document matching engine. * * These are pure functions with no Supabase or extension dependencies. */ // Matching configuration (re-exported for consumers) export const DATE_TOLERANCE_DAYS = 3 export const AMOUNT_TOLERANCE_PERCENT = 0.05 export const MIN_MATCH_CONFIDENCE = 0.4 /** * Normalize a merchant name for comparison. * Removes special characters, Swedish company suffixes, and extra whitespace. */ export function normalizeMerchantName(name: string): string { return name .toLowerCase() .replace(/[^\w\såäöé]/g, '') // Remove special chars except Swedish letters .replace(/\b(ab|hb|kb|ek|för|stiftelse)\b/g, '') // Remove company suffixes .replace(/\s+/g, ' ') .trim() } /** * Calculate Levenshtein (edit) distance between two strings. */ export function levenshteinDistance(str1: string, str2: string): number { const m = str1.length const n = str2.length const dp: number[][] = Array(m + 1) .fill(null) .map(() => Array(n + 1).fill(0)) for (let i = 0; i <= m; i++) dp[i][0] = i for (let j = 0; j <= n; j++) dp[0][j] = j for (let i = 1; i <= m; i++) { for (let j = 1; j <= n; j++) { const cost = str1[i - 1] === str2[j - 1] ? 0 : 1 dp[i][j] = Math.min( dp[i - 1][j] + 1, // deletion dp[i][j - 1] + 1, // insertion dp[i - 1][j - 1] + cost // substitution ) } } return dp[m][n] } /** * Calculate merchant name similarity using Levenshtein distance and word overlap. * Returns a value between 0 (no match) and 1 (exact match). */ export function calculateMerchantSimilarity(name1: string, name2: string): number { if (!name1 || !name2) return 0 const n1 = normalizeMerchantName(name1) const n2 = normalizeMerchantName(name2) // Exact match if (n1 === n2) return 1 // One contains the other if (n1.includes(n2) || n2.includes(n1)) return 0.9 // Word overlap const words1 = n1.split(/\s+/) const words2 = n2.split(/\s+/) const commonWords = words1.filter((w) => words2.includes(w)) if (commonWords.length > 0) { const overlapScore = commonWords.length / Math.max(words1.length, words2.length) if (overlapScore >= 0.5) return 0.7 + overlapScore * 0.2 } // Levenshtein similarity const distance = levenshteinDistance(n1, n2) const maxLength = Math.max(n1.length, n2.length) return 1 - distance / maxLength } /** * Compute the relative amount variance between a bank transaction and an * underlag (receipt/invoice) total, currency-aware. Feeds the `amountVariance` * argument of calculateMatchConfidence. * * Returns `null` when the amounts cannot be compared: either there is no * underlag total, or the two are in different currencies and the underlag has * no SEK value (no FX rate). A null result is the signal for * calculateMatchConfidence to drop the amount weight entirely instead of * comparing raw magnitudes across currencies: that cross-currency raw compare * is exactly what made a 750 EUR receipt falsely match a 750 SEK transaction. * * Magnitudes are compared (Math.abs) because a bank expense row is negative * while an underlag total is positive. * * @param receiptTotal underlag total in its own currency (sign-agnostic) * @param receiptCurrency underlag currency, e.g. 'EUR' * @param receiptSek underlag total converted to SEK, or null if unknown * @param txAmount transaction amount in its own currency (sign-agnostic) * @param txCurrency transaction currency, e.g. 'SEK' * @param txSek transaction amount in SEK (equals txAmount for SEK rows) */ export function amountVarianceForMatch( receiptTotal: number | null, receiptCurrency: string, receiptSek: number | null, txAmount: number, txCurrency: string, txSek: number, ): number | null { if (receiptTotal == null) return null const absTotal = Math.abs(receiptTotal) if (absTotal === 0) return null // Same currency → compare raw magnitudes (most reliable, needs no rate). if (txCurrency.toUpperCase() === receiptCurrency.toUpperCase()) { return Math.abs(Math.abs(txAmount) - absTotal) / absTotal } // Different currencies → compare in SEK, but only with an SEK value for both. if (receiptSek != null && Math.abs(receiptSek) > 0) { return Math.abs(Math.abs(txSek) - Math.abs(receiptSek)) / Math.abs(receiptSek) } // Cross-currency with no rate → not comparable. return null } /** * Calculate a weighted match confidence score from date, amount, and merchant signals. * Weights: amount 40%, merchant 35%, date 25%. * * When merchant similarity is 0, the merchant weight is excluded from the * total weight so the confidence is normalized across the active signals only. * * `amountVariance` may be `null` when the candidate and the underlag are in * different currencies and no FX rate was available to normalise them. In that * case the amount signal is dropped entirely (same treatment as a missing * merchant) rather than comparing raw magnitudes across currencies: that is * what made a 750 EUR receipt falsely match a 750 SEK transaction. */ export function calculateMatchConfidence( dateVariance: number, amountVariance: number | null, merchantSimilarity: number, dateTolerance: number = DATE_TOLERANCE_DAYS, amountTolerance: number = AMOUNT_TOLERANCE_PERCENT ): { confidence: number; matchReasons: string[] } { const matchReasons: string[] = [] let totalWeight = 0 let weightedScore = 0 // Date score (weight: 25%) const dateScore = Math.max(0, 1 - dateVariance / dateTolerance) if (dateScore >= 0.8) { matchReasons.push(dateVariance === 0 ? 'Exakt datum' : `Datum ±${Math.round(dateVariance)} dagar`) } weightedScore += dateScore * 0.25 totalWeight += 0.25 // Amount score (weight: 40%): only counted when the amounts are comparable // (same currency, or both normalisable to SEK). if (amountVariance != null) { const amountScore = Math.max(0, 1 - amountVariance / amountTolerance) if (amountVariance < 0.01) { matchReasons.push('Exakt belopp') } else if (amountVariance < amountTolerance) { matchReasons.push(`Belopp ±${Math.round(amountVariance * 100)}%`) } weightedScore += amountScore * 0.4 totalWeight += 0.4 } // Merchant score (weight: 35%): only counted when there's data if (merchantSimilarity > 0) { if (merchantSimilarity >= 0.9) { matchReasons.push('Handlare matchar') } else if (merchantSimilarity >= 0.6) { matchReasons.push('Trolig handlarmatch') } weightedScore += merchantSimilarity * 0.35 totalWeight += 0.35 } const confidence = totalWeight > 0 ? weightedScore / totalWeight : 0 return { confidence: Math.round(confidence * 100) / 100, matchReasons, } }