@accounter/server 0.0.8-alpha-20251102200443-d7162b8ce1dfc629b8b454df17dcec9ed005a052 → 0.0.8-alpha-20251103003648-f6467c8cb9c739ec4439c260bccc7325f6a761ae

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

@@ -0,0 +1,176 @@
+/**
+ * Auto-Match Provider
+ *
+ * Implements the core auto-match logic for processing all unmatched charges
+ * and automatically merging charges with high-confidence matches (≥0.95).
+ */
+
+import type { ChargeWithData, DocumentCharge, TransactionCharge } from '../types.js';
+import { findMatches, type MatchResult } from './single-match.provider.js';
+
+/**
+ * Result of processing a single charge for auto-matching
+ */
+export interface ProcessChargeResult {
+  /** Match result if a valid match was found, null otherwise */
+  match: MatchResult | null;
+  /** Status of the processing */
+  status: 'matched' | 'skipped' | 'no-match';
+  /** Reason for the status (useful for debugging/logging) */
+  reason?: string;
+}
+
+/**
+ * Process a single unmatched charge and find best match
+ *
+ * This function uses findMatches() from single-match provider with NO date window
+ * restriction, then filters for high-confidence matches (≥0.95 threshold).
+ *
+ * @param sourceCharge - Unmatched charge to process (must have only transactions OR only documents)
+ * @param allCandidates - All candidate charges to search (complementary type to source)
+ * @param userId - Current user ID for business extraction
+ * @returns Processing result with match status
+ *
+ * @throws Error if sourceCharge is already matched (has both transactions and documents)
+ * @throws Error if sourceCharge has no transactions or documents
+ * @throws Error if any validation fails (propagated from findMatches)
+ */
+export function processChargeForAutoMatch(
+  sourceCharge: ChargeWithData,
+  allCandidates: ChargeWithData[],
+  userId: string,
+): ProcessChargeResult {
+  const AUTO_MATCH_THRESHOLD = 0.95;
+
+  // Prepare source charge for findMatches
+  const hasTransactions = sourceCharge.transactions && sourceCharge.transactions.length > 0;
+  const hasDocuments = sourceCharge.documents && sourceCharge.documents.length > 0;
+
+  let sourceForMatching: TransactionCharge | DocumentCharge;
+  let candidatesForMatching: (TransactionCharge | DocumentCharge)[];
+
+  if (hasTransactions && !hasDocuments) {
+    // Transaction charge - convert to TransactionCharge format
+    sourceForMatching = {
+      chargeId: sourceCharge.chargeId,
+      transactions: sourceCharge.transactions,
+    };
+    // Filter candidates to only document charges
+    candidatesForMatching = allCandidates
+      .filter(
+        c =>
+          c.documents && c.documents.length > 0 && (!c.transactions || c.transactions.length === 0),
+      )
+      .map(c => ({
+        chargeId: c.chargeId,
+        documents: c.documents,
+      }));
+  } else if (hasDocuments && !hasTransactions) {
+    // Document charge - convert to DocumentCharge format
+    sourceForMatching = {
+      chargeId: sourceCharge.chargeId,
+      documents: sourceCharge.documents,
+    };
+    // Filter candidates to only transaction charges
+    candidatesForMatching = allCandidates
+      .filter(
+        c =>
+          c.transactions && c.transactions.length > 0 && (!c.documents || c.documents.length === 0),
+      )
+      .map(c => ({
+        chargeId: c.chargeId,
+        transactions: c.transactions,
+      }));
+  } else {
+    // Invalid charge state
+    if (hasTransactions && hasDocuments) {
+      throw new Error(
+        `Charge ${sourceCharge.chargeId} is already matched (has both transactions and documents)`,
+      );
+    }
+    throw new Error(`Charge ${sourceCharge.chargeId} has no transactions or documents`);
+  }
+
+  // Find all matches with no date window restriction
+  const allMatches = findMatches(sourceForMatching, candidatesForMatching, userId, {
+    dateWindowMonths: undefined, // No date restriction for auto-match
+    maxMatches: undefined, // Get all matches, we'll filter by threshold
+  });
+
+  // Filter for high-confidence matches (≥0.95)
+  const highConfidenceMatches = allMatches.filter(
+    match => match.confidenceScore >= AUTO_MATCH_THRESHOLD,
+  );
+
+  // Determine result based on number of high-confidence matches
+  if (highConfidenceMatches.length === 0) {
+    return {
+      match: null,
+      status: 'no-match',
+      reason:
+        allMatches.length > 0
+          ? `Best match has confidence ${allMatches[0].confidenceScore.toFixed(2)}, below threshold ${AUTO_MATCH_THRESHOLD}`
+          : 'No candidates found',
+    };
+  }
+
+  if (highConfidenceMatches.length === 1) {
+    return {
+      match: highConfidenceMatches[0],
+      status: 'matched',
+      reason: `Single high-confidence match found (${highConfidenceMatches[0].confidenceScore.toFixed(2)})`,
+    };
+  }
+
+  // Multiple high-confidence matches - ambiguous
+  return {
+    match: null,
+    status: 'skipped',
+    reason: `${highConfidenceMatches.length} high-confidence matches found (ambiguous)`,
+  };
+}
+
+/**
+ * Determine merge direction for two charges
+ *
+ * The merge direction follows these rules:
+ * 1. If one charge is matched (has both transactions and documents), keep the matched one
+ * 2. If both are unmatched, keep the one with transactions (transaction charge is the "anchor")
+ * 3. If neither has transactions, keep the first one (arbitrary but consistent)
+ *
+ * @param charge1 - First charge
+ * @param charge2 - Second charge
+ * @returns [source, target] tuple where source will be merged INTO target (source is deleted)
+ */
+export function determineMergeDirection(
+  charge1: ChargeWithData,
+  charge2: ChargeWithData,
+): [ChargeWithData, ChargeWithData] {
+  const charge1HasTransactions = charge1.transactions && charge1.transactions.length > 0;
+  const charge1HasDocuments = charge1.documents && charge1.documents.length > 0;
+  const charge2HasTransactions = charge2.transactions && charge2.transactions.length > 0;
+  const charge2HasDocuments = charge2.documents && charge2.documents.length > 0;
+
+  const charge1IsMatched = charge1HasTransactions && charge1HasDocuments;
+  const charge2IsMatched = charge2HasTransactions && charge2HasDocuments;
+
+  // Rule 1: If one is matched, keep the matched one
+  if (charge1IsMatched && !charge2IsMatched) {
+    return [charge2, charge1]; // Merge charge2 INTO charge1 (keep charge1)
+  }
+  if (charge2IsMatched && !charge1IsMatched) {
+    return [charge1, charge2]; // Merge charge1 INTO charge2 (keep charge2)
+  }
+
+  // Rule 2: Both unmatched - keep the one with transactions
+  if (charge1HasTransactions && !charge2HasTransactions) {
+    return [charge2, charge1]; // Merge charge2 INTO charge1 (keep transaction charge)
+  }
+  if (charge2HasTransactions && !charge1HasTransactions) {
+    return [charge1, charge2]; // Merge charge1 INTO charge2 (keep transaction charge)
+  }
+
+  // Rule 3: Neither has transactions (both are document-only) or both have transactions
+  // Keep charge1 (arbitrary but consistent)
+  return [charge2, charge1]; // Merge charge2 INTO charge1 (keep charge1)
+}

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

@@ -0,0 +1,322 @@
+/**
+ * Charges Matcher Provider
+ *
+ * Provides database-integrated charge matching functionality using the Injector pattern.
+ * Integrates with existing modules: charges, transactions, and documents.
+ */
+
+import { Injectable, Scope } from 'graphql-modules';
+import { mergeChargesExecutor } from '@modules/charges/helpers/merge-charges.hepler.js';
+import { ChargesProvider } from '@modules/charges/providers/charges.provider.js';
+import { DocumentsProvider } from '@modules/documents/providers/documents.provider.js';
+import { TransactionsProvider } from '@modules/transactions/providers/transactions.provider.js';
+import { dateToTimelessDateString } from '@shared/helpers';
+import { validateChargeIsUnmatched } from '../helpers/charge-validator.helper.js';
+import {
+  ChargeType,
+  type AutoMatchChargesResult,
+  type ChargeMatchesResult,
+  type ChargeWithData,
+  type Document,
+  type DocumentCharge,
+  type Transaction,
+  type TransactionCharge,
+} from '../types.js';
+import { determineMergeDirection, processChargeForAutoMatch } from './auto-match.provider.js';
+import { aggregateDocuments } from './document-aggregator.js';
+import { findMatches, type MatchResult } from './single-match.provider.js';
+import { aggregateTransactions } from './transaction-aggregator.js';
+
+/**
+ * Charges Matcher Provider
+ *
+ * Provides high-level charge matching operations with database integration.
+ * Uses the Injector pattern to access existing providers from other modules.
+ */
+@Injectable({
+  scope: Scope.Operation,
+})
+export class ChargesMatcherProvider {
+  /**
+   * Find potential matches for an unmatched charge
+   *
+   * @param chargeId - ID of the unmatched charge to find matches for
+   * @param injector - GraphQL modules injector for provider access
+   * @returns Top 5 matches ordered by confidence score
+   * @throws Error if charge not found
+   * @throws Error if charge is already matched
+   * @throws Error if charge data is invalid
+   */
+  async findMatchesForCharge(
+    chargeId: string,
+    context: GraphQLModules.AppContext,
+  ): Promise<ChargeMatchesResult> {
+    const {
+      adminContext: { defaultAdminBusinessId: adminBusinessId },
+      injector,
+    } = context;
+    // Get current user ID from context
+    if (!adminBusinessId) {
+      throw new Error('Admin business not found in context');
+    }
+
+    // Get providers from injector
+    const chargesProvider = injector.get(ChargesProvider);
+    const transactionsProvider = injector.get(TransactionsProvider);
+    const documentsProvider = injector.get(DocumentsProvider);
+
+    // Step 1: Load source charge data
+    const sourceCharge = await chargesProvider.getChargeByIdLoader.load(chargeId);
+    if (sourceCharge instanceof Error) {
+      throw new Error(`Source charge not found: ${chargeId}`);
+    }
+
+    // Step 2: Load transactions and documents for source charge
+    const sourceTransactions = (await transactionsProvider.transactionsByChargeIDLoader.load(
+      chargeId,
+    )) as Transaction[];
+    const sourceDocuments = (await documentsProvider.getDocumentsByChargeIdLoader.load(
+      chargeId,
+    )) as Document[];
+
+    // Step 3: Validate source charge is unmatched
+    const sourceChargeWithData = {
+      ...sourceCharge,
+      transactions: sourceTransactions,
+      documents: sourceDocuments,
+    };
+    validateChargeIsUnmatched(sourceChargeWithData);
+
+    // Step 4: Determine reference date and date window from source charge
+    let referenceDate: Date;
+    const hasTransactions = sourceTransactions && sourceTransactions.length > 0;
+    if (hasTransactions) {
+      // Use earliest transaction event_date
+      const aggregated = aggregateTransactions(sourceTransactions);
+      referenceDate = aggregated.date;
+    } else {
+      // Use latest document date
+      const aggregated = aggregateDocuments(sourceDocuments, adminBusinessId);
+      referenceDate = aggregated.date;
+    }
+
+    // Step 5: Load candidate charges from database
+    // Use 12-month window centered on reference date
+    const windowStart = new Date(referenceDate);
+    windowStart.setMonth(windowStart.getMonth() - 12);
+    const windowEnd = new Date(referenceDate);
+    windowEnd.setMonth(windowEnd.getMonth() + 12);
+
+    const candidateCharges = await chargesProvider.getChargesByFilters({
+      ownerIds: [adminBusinessId],
+      fromAnyDate: dateToTimelessDateString(windowStart),
+      toAnyDate: dateToTimelessDateString(windowEnd),
+    });
+
+    // Step 6: Load transactions and documents for all candidate charges
+    const candidateChargesWithData: Array<TransactionCharge | DocumentCharge> = [];
+
+    for (const candidate of candidateCharges) {
+      // Skip the source charge itself
+      if (candidate.id === chargeId) {
+        continue;
+      }
+
+      const candidateTransactions = (await transactionsProvider.transactionsByChargeIDLoader.load(
+        candidate.id,
+      )) as Transaction[];
+      const candidateDocuments = (await documentsProvider.getDocumentsByChargeIdLoader.load(
+        candidate.id,
+      )) as Document[];
+
+      const hasTxs = candidateTransactions && candidateTransactions.length > 0;
+      const hasDocs = candidateDocuments && candidateDocuments.length > 0;
+
+      // Only include unmatched charges (not both types)
+      if (hasTxs && !hasDocs) {
+        candidateChargesWithData.push({
+          chargeId: candidate.id,
+          transactions: candidateTransactions,
+        });
+      } else if (hasDocs && !hasTxs) {
+        candidateChargesWithData.push({
+          chargeId: candidate.id,
+          documents: candidateDocuments,
+        });
+      }
+      // Skip matched charges (have both) and empty charges (have neither)
+    }
+
+    // Step 7: Build source charge object for findMatches
+    let sourceChargeData: TransactionCharge | DocumentCharge;
+    if (hasTransactions) {
+      sourceChargeData = {
+        chargeId,
+        transactions: sourceTransactions,
+      };
+    } else {
+      sourceChargeData = {
+        chargeId,
+        documents: sourceDocuments,
+      };
+    }
+
+    // Step 8: Call core findMatches function
+    const matches: MatchResult[] = findMatches(
+      sourceChargeData,
+      candidateChargesWithData,
+      adminBusinessId,
+      {
+        maxMatches: 5,
+        dateWindowMonths: 12,
+      },
+    );
+
+    // Step 9: Format and return result
+    return {
+      matches: matches.map(match => ({
+        chargeId: match.chargeId,
+        confidenceScore: match.confidenceScore,
+      })),
+    };
+  }
+
+  /**
+   * Auto-match all unmatched charges
+   *
+   * Automatically merges charges that have a single high-confidence match (≥0.95).
+   * Skips charges with multiple high-confidence matches (ambiguous).
+   * Processes all unmatched charges and returns a summary of actions taken.
+   *
+   * @param injector - GraphQL modules injector for provider access
+   * @param context - GraphQL context with user information
+   * @returns Summary of matches made, skipped charges, and errors
+   */
+  async autoMatchCharges(context: GraphQLModules.AppContext): Promise<AutoMatchChargesResult> {
+    const {
+      adminContext: { defaultAdminBusinessId: adminBusinessId },
+      injector,
+    } = context;
+    // Get current user ID from context
+    if (!adminBusinessId) {
+      throw new Error('Admin business not found in context');
+    }
+
+    // Get providers from injector
+    const chargesProvider = injector.get(ChargesProvider);
+    const transactionsProvider = injector.get(TransactionsProvider);
+    const documentsProvider = injector.get(DocumentsProvider);
+
+    // Step 1: Load all charges for this user
+    const allCharges = await chargesProvider.getChargesByFilters({
+      ownerIds: [adminBusinessId],
+    });
+
+    // Step 2: Load transactions and documents for all charges
+    const chargesWithData: ChargeWithData[] = [];
+    const mergedChargeIds = new Set<string>(); // Track merged charges to exclude from processing
+
+    for (const charge of allCharges) {
+      const transactions = (await transactionsProvider.transactionsByChargeIDLoader.load(
+        charge.id,
+      )) as Transaction[];
+      const documents = (await documentsProvider.getDocumentsByChargeIdLoader.load(
+        charge.id,
+      )) as Document[];
+
+      chargesWithData.push({
+        chargeId: charge.id,
+        ownerId: charge.owner_id ?? adminBusinessId,
+        type: ChargeType.TRANSACTION_ONLY, // Will be determined by processChargeForAutoMatch
+        transactions: transactions || [],
+        documents: documents || [],
+      });
+    }
+
+    // Step 3: Filter to get only unmatched charges
+    const unmatchedCharges = chargesWithData.filter(charge => {
+      const hasTx = charge.transactions && charge.transactions.length > 0;
+      const hasDocs = charge.documents && charge.documents.length > 0;
+      return (hasTx && !hasDocs) || (!hasTx && hasDocs);
+    });
+
+    // Step 4: Process each unmatched charge
+    const result: AutoMatchChargesResult = {
+      totalMatches: 0,
+      mergedCharges: [],
+      skippedCharges: [],
+      errors: [],
+    };
+
+    for (const sourceCharge of unmatchedCharges) {
+      // Skip if this charge was already merged in this run
+      if (mergedChargeIds.has(sourceCharge.chargeId)) {
+        continue;
+      }
+
+      try {
+        // Get candidates (exclude already merged charges)
+        const candidates = chargesWithData.filter(
+          c => c.chargeId !== sourceCharge.chargeId && !mergedChargeIds.has(c.chargeId),
+        );
+
+        // Process this charge for auto-match
+        const processResult = processChargeForAutoMatch(sourceCharge, candidates, adminBusinessId);
+
+        if (processResult.status === 'matched' && processResult.match) {
+          // Found a single high-confidence match - execute merge
+          const matchedChargeId = processResult.match.chargeId;
+          const matchedCharge = chargesWithData.find(c => c.chargeId === matchedChargeId);
+
+          if (!matchedCharge) {
+            result.errors.push(
+              `Matched charge ${matchedChargeId} not found in charge pool for ${sourceCharge.chargeId}`,
+            );
+            continue;
+          }
+
+          // Determine merge direction
+          const [sourceToMerge, targetToKeep] = determineMergeDirection(
+            sourceCharge,
+            matchedCharge,
+          );
+
+          try {
+            // Execute merge via existing merge functionality
+            await mergeChargesExecutor([sourceToMerge.chargeId], targetToKeep.chargeId, injector);
+
+            // Track successful merge
+            result.totalMatches++;
+            result.mergedCharges.push({
+              chargeId: sourceToMerge.chargeId,
+              confidenceScore: processResult.match.confidenceScore,
+            });
+
+            // Mark both charges as processed (merged away charge and kept charge)
+            mergedChargeIds.add(sourceToMerge.chargeId);
+            mergedChargeIds.add(targetToKeep.chargeId); // Don't process the kept charge again
+          } catch (mergeError) {
+            result.errors.push(
+              `Failed to merge ${sourceToMerge.chargeId} into ${targetToKeep.chargeId}: ${
+                mergeError instanceof Error ? mergeError.message : String(mergeError)
+              }`,
+            );
+          }
+        } else if (processResult.status === 'skipped') {
+          // Multiple high-confidence matches - ambiguous
+          result.skippedCharges.push(sourceCharge.chargeId);
+        }
+        // status === 'no-match': do nothing, silently skip
+      } catch (error) {
+        // Capture error but continue processing other charges
+        result.errors.push(
+          `Error processing charge ${sourceCharge.chargeId}: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        );
+      }
+    }
+
+    return result;
+  }
+}