@accounter/server 0.0.8-alpha-20251102200443-d7162b8ce1dfc629b8b454df17dcec9ed005a052 → 0.0.8-alpha-20251102213150-c9d936f545d5351df0dc5326c2623266f1ad1f46

package/src/modules/charges-matcher/providers/document-aggregator.ts

@@ -0,0 +1,211 @@
+/**
+ * Document Aggregator
+ *
+ * Aggregates multiple documents from a single charge into a unified representation
+ * for matching purposes. Handles type priority filtering, business extraction,
+ * amount normalization, currency validation, date selection, and description concatenation.
+ */
+
+import { currency } from '@modules/documents/types.js';
+import { normalizeDocumentAmount, type DocumentType } from '../helpers/document-amount.helper.js';
+import { extractDocumentBusiness } from '../helpers/document-business.helper.js';
+import { AggregatedDocument } from '../types.js';
+
+/**
+ * Minimal document interface for aggregation
+ * Based on database schema from accounter_schema.documents
+ * Note: Documents use charge_id for the FK
+ */
+export interface Document {
+  id: string; // UUID
+  charge_id: string | null; // UUID (actual FK name in DB)
+  creditor_id: string | null; // UUID
+  debtor_id: string | null; // UUID
+  currency_code: currency | null; // Currency type
+  date: Date | null;
+  total_amount: number | null; // double precision in DB
+  type: DocumentType;
+  serial_number: string | null;
+  image_url: string | null;
+  file_url: string | null;
+}
+
+/**
+ * Accounting document types (used for type priority filtering)
+ */
+const INVOICE_TYPES: DocumentType[] = ['INVOICE', 'CREDIT_INVOICE'];
+const RECEIPT_TYPES: DocumentType[] = ['RECEIPT', 'INVOICE_RECEIPT'];
+
+/**
+ * Check if document type is an invoice or credit invoice
+ */
+function isInvoiceType(type: DocumentType): boolean {
+  return INVOICE_TYPES.includes(type);
+}
+
+/**
+ * Check if document type is a receipt or invoice-receipt
+ */
+function isReceiptType(type: DocumentType): boolean {
+  return RECEIPT_TYPES.includes(type);
+}
+
+/**
+ * Aggregate multiple documents into a single representation
+ *
+ * Per specification (section 4.2):
+ * 1. Filter by type priority: if both invoices AND receipts exist, use only invoices
+ * 2. Extract business ID from each document (creditor_id/debtor_id)
+ * 3. Normalize each amount based on business role and document type
+ * 4. Validate non-empty array
+ * 5. Check for mixed currencies → throw error
+ * 6. Check for multiple non-null business IDs → throw error
+ * 7. Sum all normalized amounts
+ * 8. Select latest date
+ * 9. Concatenate serial_number or file names with line breaks
+ * 10. Determine document type for result (use first after filtering)
+ *
+ * @param documents - Array of documents from a charge (use charge_id field for FK)
+ * @param adminBusinessId - Current admin business UUID for business extraction
+ * @returns Aggregated document data
+ *
+ * @throws {Error} If documents array is empty
+ * @throws {Error} If multiple different currencies exist
+ * @throws {Error} If multiple different non-null business IDs exist
+ * @throws {Error} If business extraction fails (propagates from extractDocumentBusiness)
+ * @throws {Error} If no valid date found in any document
+ *
+ * @example
+ * const aggregated = aggregateDocuments([
+ *   { total_amount: 100, currency_code: 'USD', creditor_id: 'b1', debtor_id: 'u1', type: 'INVOICE', ... },
+ *   { total_amount: 50, currency_code: 'USD', creditor_id: 'b1', debtor_id: 'u1', type: 'INVOICE', ... }
+ * ], 'u1');
+ * // Returns aggregated with normalized amounts summed
+ */
+export function aggregateDocuments(
+  documents: Document[],
+  adminBusinessId: string,
+): Omit<AggregatedDocument, 'businessIsCreditor'> {
+  // Validate non-empty input
+  if (!documents || documents.length === 0) {
+    throw new Error('Cannot aggregate documents: array is empty');
+  }
+
+  // Apply type priority filtering
+  const hasInvoices = documents.some(d => isInvoiceType(d.type));
+  const hasReceipts = documents.some(d => isReceiptType(d.type));
+
+  let filteredDocuments = documents;
+  if (hasInvoices && hasReceipts) {
+    // If both invoices and receipts exist, use only invoices
+    filteredDocuments = documents.filter(d => isInvoiceType(d.type));
+  }
+
+  // Validate we still have documents after filtering
+  if (filteredDocuments.length === 0) {
+    throw new Error('Cannot aggregate documents: no valid documents after type priority filtering');
+  }
+
+  // Extract business info and normalize amounts for each document
+  const processedDocuments = filteredDocuments.map(doc => {
+    const businessInfo = extractDocumentBusiness(doc.creditor_id, doc.debtor_id, adminBusinessId);
+    const normalizedAmount = normalizeDocumentAmount(
+      doc.total_amount ?? 0,
+      businessInfo.isBusinessCreditor,
+      doc.type,
+    );
+
+    return {
+      document: doc,
+      businessInfo,
+      normalizedAmount,
+    };
+  });
+
+  // Validate single currency
+  const currencies = new Set(
+    processedDocuments
+      .map(p => p.document.currency_code)
+      .filter((code): code is currency => code !== null && code !== undefined),
+  );
+
+  if (currencies.size === 0) {
+    throw new Error('Cannot aggregate documents: all documents have null currency_code');
+  }
+
+  if (currencies.size > 1) {
+    throw new Error(
+      `Cannot aggregate documents: multiple currencies found (${Array.from(currencies).join(', ')})`,
+    );
+  }
+
+  // Validate single non-null business ID
+  const businessIds = processedDocuments
+    .map(p => p.businessInfo.businessId)
+    .filter((id): id is string => id !== null && id !== undefined);
+
+  const uniqueBusinessIds = new Set(businessIds);
+  if (uniqueBusinessIds.size > 1) {
+    throw new Error(
+      `Cannot aggregate documents: multiple business IDs found (${Array.from(uniqueBusinessIds).join(', ')})`,
+    );
+  }
+
+  // Sum normalized amounts
+  const totalAmount = processedDocuments.reduce((sum, p) => sum + p.normalizedAmount, 0);
+
+  // Get common currency (safe since we validated single currency)
+  const currency = Array.from(currencies)[0];
+
+  // Get business ID (single non-null or null if all null)
+  const businessId = uniqueBusinessIds.size === 1 ? Array.from(uniqueBusinessIds)[0] : null;
+
+  // Get latest date
+  const dates = filteredDocuments
+    .map(d => d.date)
+    .filter((date): date is Date => date !== null && date !== undefined);
+
+  if (dates.length === 0) {
+    throw new Error('Cannot aggregate documents: all documents have null date');
+  }
+
+  const latestDate = dates.reduce((latest, d) => {
+    return d > latest ? d : latest;
+  }, dates[0]);
+
+  // Concatenate descriptions (serial numbers, file names, or IDs)
+  const descriptions = filteredDocuments
+    .map(d => {
+      // Prefer serial_number, fallback to file_url or image_url name, or document ID
+      if (d.serial_number && d.serial_number.trim() !== '') {
+        return d.serial_number.trim();
+      }
+      if (d.file_url) {
+        // Extract filename from URL
+        const fileName = d.file_url.split('/').pop() || d.file_url;
+        return fileName;
+      }
+      if (d.image_url) {
+        // Extract filename from URL
+        const fileName = d.image_url.split('/').pop() || d.image_url;
+        return fileName;
+      }
+      // Fallback to document ID
+      return `Doc-${d.id.substring(0, 8)}`;
+    })
+    .filter(desc => desc !== null && desc !== undefined && desc.trim() !== '');
+
+  const description = descriptions.length > 0 ? descriptions.join('\n') : '';
+
+  // Determine document type (use first document after filtering)
+  const type = filteredDocuments[0].type;
+
+  return {
+    amount: totalAmount,
+    currency,
+    businessId,
+    date: latestDate,
+    type,
+    description,
+  };
+}

package/src/modules/charges-matcher/providers/match-scorer.provider.ts

@@ -0,0 +1,154 @@
+import type { document_type } from '@modules/documents/types.js';
+import { calculateAmountConfidence } from '../helpers/amount-confidence.helper.js';
+import { calculateBusinessConfidence } from '../helpers/business-confidence.helper.js';
+import { calculateCurrencyConfidence } from '../helpers/currency-confidence.helper.js';
+import { calculateDateConfidence } from '../helpers/date-confidence.helper.js';
+import { calculateOverallConfidence } from '../helpers/overall-confidence.helper.js';
+import type {
+  AggregatedDocument,
+  AggregatedTransaction,
+  ConfidenceScores,
+  DocumentCharge,
+  MatchScore,
+  TransactionCharge,
+} from '../types.js';
+import { aggregateDocuments } from './document-aggregator.js';
+import { aggregateTransactions } from './transaction-aggregator.js';
+
+/**
+ * Select appropriate transaction date based on document type
+ * Per specification:
+ * - INVOICE/CREDIT_INVOICE: Use event_date
+ * - RECEIPT/INVOICE_RECEIPT: Use debit_date (debit_timestamp or debit_date)
+ * - OTHER/PROFORMA/UNPROCESSED: Calculate both and use better score
+ *
+ * @param transaction - Aggregated transaction data
+ * @param documentType - Document type being matched
+ * @returns The date to use for matching
+ */
+export function selectTransactionDate(
+  transaction: AggregatedTransaction,
+  documentType: document_type,
+): Date {
+  switch (documentType) {
+    case 'INVOICE':
+    case 'CREDIT_INVOICE':
+    case 'RECEIPT':
+    case 'INVOICE_RECEIPT':
+      // For invoices, use event_date
+      return transaction.date;
+
+    case 'OTHER':
+    case 'PROFORMA':
+    case 'UNPROCESSED':
+      // For flexible types, use event_date as default
+      // (caller should calculate both and use better score)
+      return transaction.date;
+
+    default:
+      // Fallback to event_date for unknown types
+      return transaction.date;
+  }
+}
+
+/**
+ * Score a potential match between transaction charge and document charge
+ * Aggregates data from both charges and calculates confidence score
+ *
+ * @param txCharge - Transaction charge to match
+ * @param docCharge - Document charge candidate
+ * @param userId - Current user UUID for business extraction
+ * @returns Match score with confidence and component breakdown
+ * @throws Error if aggregation fails (mixed currencies, multiple businesses, etc.)
+ */
+export function scoreMatch(
+  txCharge: TransactionCharge,
+  docCharge: DocumentCharge,
+  userId: string,
+): MatchScore {
+  // Aggregate transaction data
+  const aggregatedTransaction = aggregateTransactions(txCharge.transactions);
+
+  // Aggregate document data (includes business extraction and amount normalization)
+  const aggregatedDocument = aggregateDocuments(docCharge.documents, userId);
+
+  // // For flexible document types, try both dates and use the better score
+  // if (
+  //   aggregatedDocument.type === 'OTHER' ||
+  //   aggregatedDocument.type === 'PROFORMA' ||
+  //   aggregatedDocument.type === 'UNPROCESSED'
+  // ) {
+  //   // Calculate score with event_date
+  //   const scoreWithEventDate = calculateScoreWithDate(
+  //     aggregatedTransaction,
+  //     aggregatedDocument,
+  //     aggregatedTransaction.date,
+  //     docCharge.chargeId,
+  //   );
+
+  //   // Calculate score with debit_date (if available)
+  //   if (aggregatedTransaction.debitDate) {
+  //     const scoreWithDebitDate = calculateScoreWithDate(
+  //       aggregatedTransaction,
+  //       aggregatedDocument,
+  //       aggregatedTransaction.debitDate,
+  //       docCharge.chargeId,
+  //     );
+
+  //     // Return the better score
+  //     return scoreWithEventDate.confidenceScore > scoreWithDebitDate.confidenceScore
+  //       ? scoreWithEventDate
+  //       : scoreWithDebitDate;
+  //   }
+
+  //   return scoreWithEventDate;
+  // }
+
+  // For specific document types, use the appropriate date
+  const transactionDate = selectTransactionDate(aggregatedTransaction, aggregatedDocument.type);
+
+  return calculateScoreWithDate(
+    aggregatedTransaction,
+    aggregatedDocument,
+    transactionDate,
+    docCharge.chargeId,
+  );
+}
+
+/**
+ * Helper function to calculate match score with a specific transaction date
+ * @param transaction - Aggregated transaction
+ * @param document - Aggregated document
+ * @param transactionDate - Date to use from transaction
+ * @param chargeId - Document charge ID
+ * @returns Match score
+ */
+function calculateScoreWithDate(
+  transaction: Omit<AggregatedTransaction, 'debitDate'>,
+  document: Omit<AggregatedDocument, 'businessIsCreditor'>,
+  transactionDate: Date,
+  chargeId: string,
+): MatchScore {
+  // Calculate individual confidence scores
+  const amountScore = calculateAmountConfidence(transaction.amount, document.amount);
+  const currencyScore = calculateCurrencyConfidence(transaction.currency, document.currency);
+  const businessScore = calculateBusinessConfidence(transaction.businessId, document.businessId);
+  const dateScore = calculateDateConfidence(transactionDate, document.date);
+
+  // Create components object
+  const components: ConfidenceScores = {
+    amount: amountScore,
+    currency: currencyScore,
+    business: businessScore,
+    date: dateScore,
+  };
+
+  // Calculate overall confidence
+  const confidenceScore = calculateOverallConfidence(components);
+
+  return {
+    chargeId,
+    confidenceScore,
+    components,
+  };
+}

package/src/modules/charges-matcher/providers/single-match.provider.ts

@@ -0,0 +1,252 @@
+/**
+ * Single-Match Provider
+ *
+ * Implements the core single-match logic for finding potential charge matches.
+ * This is a pure function implementation without database dependencies.
+ */
+
+import { isWithinDateWindow } from '../helpers/candidate-filter.helper.js';
+import type { DocumentCharge, MatchScore, TransactionCharge } from '../types.js';
+import { aggregateDocuments } from './document-aggregator.js';
+import { scoreMatch } from './match-scorer.provider.js';
+import { aggregateTransactions } from './transaction-aggregator.js';
+
+/**
+ * Match result with score and metadata
+ */
+export interface MatchResult {
+  chargeId: string;
+  confidenceScore: number;
+  components: {
+    amount: number;
+    currency: number;
+    business: number;
+    date: number;
+  };
+  dateProximity?: number; // Days between earliest tx date and latest doc date (for tie-breaking)
+}
+
+/**
+ * Options for findMatches function
+ */
+export interface FindMatchesOptions {
+  maxMatches?: number; // Default 5
+  dateWindowMonths?: number; // Default 12
+}
+
+/**
+ * Type guard: check if charge is TransactionCharge
+ */
+function isTransactionCharge(
+  charge: TransactionCharge | DocumentCharge,
+): charge is TransactionCharge {
+  return 'transactions' in charge && charge.transactions.length > 0;
+}
+
+/**
+ * Type guard: check if charge is DocumentCharge
+ */
+function isDocumentCharge(charge: TransactionCharge | DocumentCharge): charge is DocumentCharge {
+  return 'documents' in charge && charge.documents.length > 0;
+}
+
+/**
+ * Validate that source charge is unmatched (has only one type)
+ */
+function validateUnmatchedCharge(charge: TransactionCharge | DocumentCharge): void {
+  const hasTx = 'transactions' in charge && charge.transactions && charge.transactions.length > 0;
+  const hasDocs = 'documents' in charge && charge.documents && charge.documents.length > 0;
+
+  if (hasTx && hasDocs) {
+    throw new Error(
+      `Source charge ${charge.chargeId} is already matched (contains both transactions and documents)`,
+    );
+  }
+
+  if (!hasTx && !hasDocs) {
+    throw new Error(`Source charge ${charge.chargeId} has no transactions or documents`);
+  }
+}
+
+/**
+ * Validate that source charge can be aggregated successfully
+ */
+function validateSourceAggregation(
+  charge: TransactionCharge | DocumentCharge,
+  userId: string,
+): void {
+  try {
+    if (isTransactionCharge(charge)) {
+      aggregateTransactions(charge.transactions);
+    } else {
+      aggregateDocuments(charge.documents, userId);
+    }
+  } catch (error) {
+    throw new Error(
+      `Source charge ${charge.chargeId} failed validation: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}
+
+/**
+ * Calculate date proximity between transaction and document charges
+ * Used for tie-breaking when confidence scores are equal
+ *
+ * @param txCharge - Transaction charge
+ * @param docCharge - Document charge
+ * @returns Number of days between earliest transaction date and latest document date
+ */
+function calculateDateProximity(txCharge: TransactionCharge, docCharge: DocumentCharge): number {
+  // Get earliest transaction event_date
+  const earliestTxDate = txCharge.transactions.reduce((earliest, tx) => {
+    return tx.event_date < earliest ? tx.event_date : earliest;
+  }, txCharge.transactions[0].event_date);
+
+  // Get latest document date
+  const latestDocDate = docCharge.documents.reduce((latest, doc) => {
+    if (!doc.date) return latest;
+    return doc.date > latest ? doc.date : latest;
+  }, docCharge.documents[0].date!);
+
+  // Calculate day difference
+  const diffMs = Math.abs(earliestTxDate.getTime() - latestDocDate.getTime());
+  return Math.floor(diffMs / (1000 * 60 * 60 * 24));
+}
+
+/**
+ * Find top matches for an unmatched charge
+ *
+ * @param sourceCharge - The unmatched charge (transactions OR documents)
+ * @param candidateCharges - All potential match candidates
+ * @param userId - Current user ID
+ * @param options - Optional configuration (maxMatches, dateWindowMonths)
+ * @returns Top matches sorted by confidence
+ * @throws Error if source charge is matched or has validation issues
+ */
+export function findMatches(
+  sourceCharge: TransactionCharge | DocumentCharge,
+  candidateCharges: Array<TransactionCharge | DocumentCharge>,
+  userId: string,
+  options?: FindMatchesOptions,
+): MatchResult[] {
+  const maxMatches = options?.maxMatches ?? 5;
+  const dateWindowMonths = options?.dateWindowMonths ?? 12;
+
+  // Step 1: Validate source charge is unmatched
+  validateUnmatchedCharge(sourceCharge);
+
+  // Step 2: Validate source charge aggregation
+  validateSourceAggregation(sourceCharge, userId);
+
+  // Step 3: Determine source type and filter candidates by complementary type
+  const isSourceTransaction = isTransactionCharge(sourceCharge);
+  const complementaryCandidates = candidateCharges.filter(candidate => {
+    if (isSourceTransaction) {
+      return isDocumentCharge(candidate);
+    }
+    return isTransactionCharge(candidate);
+  });
+
+  // Step 4: Get source date for window filtering
+  let sourceDate: Date;
+  if (isSourceTransaction) {
+    // Use earliest event_date from transactions
+    sourceDate = sourceCharge.transactions.reduce((earliest, tx) => {
+      return tx.event_date < earliest ? tx.event_date : earliest;
+    }, sourceCharge.transactions[0].event_date);
+  } else {
+    // Use latest date from documents
+    sourceDate = sourceCharge.documents.reduce((latest, doc) => {
+      if (!doc.date) return latest;
+      return doc.date > latest ? doc.date : latest;
+    }, sourceCharge.documents[0].date!);
+  }
+
+  // Step 5: Filter candidates by date window
+  const windowFilteredCandidates = complementaryCandidates.filter(candidate => {
+    let candidateDate: Date;
+
+    if (isTransactionCharge(candidate)) {
+      candidateDate = candidate.transactions.reduce((earliest, tx) => {
+        return tx.event_date < earliest ? tx.event_date : earliest;
+      }, candidate.transactions[0].event_date);
+    } else {
+      candidateDate = candidate.documents.reduce((latest, doc) => {
+        if (!doc.date) return latest;
+        return doc.date > latest ? doc.date : latest;
+      }, candidate.documents[0].date!);
+    }
+
+    return isWithinDateWindow(sourceDate, candidateDate, dateWindowMonths);
+  });
+
+  // Step 6: Filter candidates using candidate filter logic
+  // Note: Additional filtering (is_fee, null checks) is handled by aggregators
+  // which will throw errors for invalid data
+
+  // Step 7: Exclude candidates with same chargeId
+  const sameChargeCandidate = windowFilteredCandidates.find(
+    c => c.chargeId === sourceCharge.chargeId,
+  );
+  if (sameChargeCandidate) {
+    throw new Error(
+      `Candidate charge ${sameChargeCandidate.chargeId} has the same ID as source charge`,
+    );
+  }
+
+  // Step 8: Score all remaining candidates
+  const scoredCandidates: Array<
+    MatchResult & { _txCharge?: TransactionCharge; _docCharge?: DocumentCharge }
+  > = [];
+
+  for (const candidate of windowFilteredCandidates) {
+    try {
+      let matchScore: MatchScore;
+      let txCharge: TransactionCharge;
+      let docCharge: DocumentCharge;
+
+      if (isSourceTransaction) {
+        txCharge = sourceCharge;
+        docCharge = candidate as DocumentCharge;
+        matchScore = scoreMatch(txCharge, docCharge, userId);
+      } else {
+        txCharge = candidate as TransactionCharge;
+        docCharge = sourceCharge;
+        matchScore = scoreMatch(txCharge, docCharge, userId);
+      }
+
+      // Calculate date proximity for tie-breaking
+      const dateProximity = calculateDateProximity(txCharge, docCharge);
+
+      scoredCandidates.push({
+        chargeId: candidate.chargeId,
+        confidenceScore: matchScore.confidenceScore,
+        components: matchScore.components,
+        dateProximity,
+        _txCharge: txCharge,
+        _docCharge: docCharge,
+      });
+    } catch {
+      // Skip candidates that fail scoring (e.g., mixed currencies, invalid data)
+      // This is expected behavior - not all candidates will be scoreable
+      continue;
+    }
+  }
+
+  // Step 9: Sort by confidence descending, then by date proximity ascending (tie-breaker)
+  scoredCandidates.sort((a, b) => {
+    // Primary: confidence score (descending)
+    if (a.confidenceScore !== b.confidenceScore) {
+      return b.confidenceScore - a.confidenceScore;
+    }
+
+    // Tie-breaker: date proximity (ascending - closer dates win)
+    return (a.dateProximity ?? Infinity) - (b.dateProximity ?? Infinity);
+  });
+
+  // Step 10: Return top N matches
+  const topMatches = scoredCandidates.slice(0, maxMatches);
+
+  // Clean up temporary fields
+  return topMatches.map(({ _txCharge, _docCharge, ...match }) => match);
+}