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

package/dist/server/src/modules/charges-matcher/providers/document-aggregator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-aggregator.js","sourceRoot":"","sources":["../../../../../../src/modules/charges-matcher/providers/document-aggregator.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,25 @@
+import type { document_type } from '../../documents/types.js';
+import type { AggregatedTransaction, DocumentCharge, MatchScore, TransactionCharge } from '../types.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 declare function selectTransactionDate(transaction: AggregatedTransaction, documentType: document_type): 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 declare function scoreMatch(txCharge: TransactionCharge, docCharge: DocumentCharge, userId: string): MatchScore;

package/dist/server/src/modules/charges-matcher/providers/match-scorer.provider.js

@@ -0,0 +1,114 @@
+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 { 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, documentType) {
+    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, docCharge, userId) {
+    // 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, document, transactionDate, chargeId) {
+    // 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 = {
+        amount: amountScore,
+        currency: currencyScore,
+        business: businessScore,
+        date: dateScore,
+    };
+    // Calculate overall confidence
+    const confidenceScore = calculateOverallConfidence(components);
+    return {
+        chargeId,
+        confidenceScore,
+        components,
+    };
+}
+//# sourceMappingURL=match-scorer.provider.js.map

package/dist/server/src/modules/charges-matcher/providers/match-scorer.provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"match-scorer.provider.js","sourceRoot":"","sources":["../../../../../../src/modules/charges-matcher/providers/match-scorer.provider.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,39 @@
+/**
+ * Single-Match Provider
+ *
+ * Implements the core single-match logic for finding potential charge matches.
+ * This is a pure function implementation without database dependencies.
+ */
+import type { DocumentCharge, TransactionCharge } from '../types.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;
+}
+/**
+ * Options for findMatches function
+ */
+export interface FindMatchesOptions {
+    maxMatches?: number;
+    dateWindowMonths?: number;
+}
+/**
+ * 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 declare function findMatches(sourceCharge: TransactionCharge | DocumentCharge, candidateCharges: Array<TransactionCharge | DocumentCharge>, userId: string, options?: FindMatchesOptions): MatchResult[];

package/dist/server/src/modules/charges-matcher/providers/single-match.provider.js

@@ -0,0 +1,189 @@
+/**
+ * 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 { aggregateDocuments } from './document-aggregator.js';
+import { scoreMatch } from './match-scorer.provider.js';
+import { aggregateTransactions } from './transaction-aggregator.js';
+/**
+ * Type guard: check if charge is TransactionCharge
+ */
+function isTransactionCharge(charge) {
+    return 'transactions' in charge && charge.transactions.length > 0;
+}
+/**
+ * Type guard: check if charge is DocumentCharge
+ */
+function isDocumentCharge(charge) {
+    return 'documents' in charge && charge.documents.length > 0;
+}
+/**
+ * Validate that source charge is unmatched (has only one type)
+ */
+function validateUnmatchedCharge(charge) {
+    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, userId) {
+    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, docCharge) {
+    // 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, candidateCharges, userId, options) {
+    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;
+    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;
+        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 = [];
+    for (const candidate of windowFilteredCandidates) {
+        try {
+            let matchScore;
+            let txCharge;
+            let docCharge;
+            if (isSourceTransaction) {
+                txCharge = sourceCharge;
+                docCharge = candidate;
+                matchScore = scoreMatch(txCharge, docCharge, userId);
+            }
+            else {
+                txCharge = candidate;
+                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);
+}
+//# sourceMappingURL=single-match.provider.js.map

package/dist/server/src/modules/charges-matcher/providers/single-match.provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"single-match.provider.js","sourceRoot":"","sources":["../../../../../../src/modules/charges-matcher/providers/single-match.provider.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AAE3E,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAyBpE;;GAEG;AACH,SAAS,mBAAmB,CAC1B,MAA0C;IAE1C,OAAO,cAAc,IAAI,MAAM,IAAI,MAAM,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC;AACpE,CAAC;AAED;;GAEG;AACH,SAAS,gBAAgB,CAAC,MAA0C;IAClE,OAAO,WAAW,IAAI,MAAM,IAAI,MAAM,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;AAC9D,CAAC;AAED;;GAEG;AACH,SAAS,uBAAuB,CAAC,MAA0C;IACzE,MAAM,KAAK,GAAG,cAAc,IAAI,MAAM,IAAI,MAAM,CAAC,YAAY,IAAI,MAAM,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC;IAChG,MAAM,OAAO,GAAG,WAAW,IAAI,MAAM,IAAI,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;IAEzF,IAAI,KAAK,IAAI,OAAO,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CACb,iBAAiB,MAAM,CAAC,QAAQ,gEAAgE,CACjG,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,KAAK,IAAI,CAAC,OAAO,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,iBAAiB,MAAM,CAAC,QAAQ,mCAAmC,CAAC,CAAC;IACvF,CAAC;AACH,CAAC;AAED;;GAEG;AACH,SAAS,yBAAyB,CAChC,MAA0C,EAC1C,MAAc;IAEd,IAAI,CAAC;QACH,IAAI,mBAAmB,CAAC,MAAM,CAAC,EAAE,CAAC;YAChC,qBAAqB,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;QAC7C,CAAC;aAAM,CAAC;YACN,kBAAkB,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,iBAAiB,MAAM,CAAC,QAAQ,uBAAuB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAChH,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,sBAAsB,CAAC,QAA2B,EAAE,SAAyB;IACpF,sCAAsC;IACtC,MAAM,cAAc,GAAG,QAAQ,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,EAAE,EAAE,EAAE;QACnE,OAAO,EAAE,CAAC,UAAU,GAAG,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC;IAC7D,CAAC,EAAE,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;IAExC,2BAA2B;IAC3B,MAAM,aAAa,GAAG,SAAS,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,GAAG,EAAE,EAAE;QAC/D,IAAI,CAAC,GAAG,CAAC,IAAI;YAAE,OAAO,MAAM,CAAC;QAC7B,OAAO,GAAG,CAAC,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC;IAC/C,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAK,CAAC,CAAC;IAEjC,2BAA2B;IAC3B,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,cAAc,CAAC,OAAO,EAAE,GAAG,aAAa,CAAC,OAAO,EAAE,CAAC,CAAC;IAC5E,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;AACpD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CACzB,YAAgD,EAChD,gBAA2D,EAC3D,MAAc,EACd,OAA4B;IAE5B,MAAM,UAAU,GAAG,OAAO,EAAE,UAAU,IAAI,CAAC,CAAC;IAC5C,MAAM,gBAAgB,GAAG,OAAO,EAAE,gBAAgB,IAAI,EAAE,CAAC;IAEzD,8CAA8C;IAC9C,uBAAuB,CAAC,YAAY,CAAC,CAAC;IAEtC,6CAA6C;IAC7C,yBAAyB,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IAEhD,4EAA4E;IAC5E,MAAM,mBAAmB,GAAG,mBAAmB,CAAC,YAAY,CAAC,CAAC;IAC9D,MAAM,uBAAuB,GAAG,gBAAgB,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE;QAClE,IAAI,mBAAmB,EAAE,CAAC;YACxB,OAAO,gBAAgB,CAAC,SAAS,CAAC,CAAC;QACrC,CAAC;QACD,OAAO,mBAAmB,CAAC,SAAS,CAAC,CAAC;IACxC,CAAC,CAAC,CAAC;IAEH,+CAA+C;IAC/C,IAAI,UAAgB,CAAC;IACrB,IAAI,mBAAmB,EAAE,CAAC;QACxB,4CAA4C;QAC5C,UAAU,GAAG,YAAY,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,EAAE,EAAE,EAAE;YAC7D,OAAO,EAAE,CAAC,UAAU,GAAG,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC;QAC7D,CAAC,EAAE,YAAY,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;IAC9C,CAAC;SAAM,CAAC;QACN,iCAAiC;QACjC,UAAU,GAAG,YAAY,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,GAAG,EAAE,EAAE;YACzD,IAAI,CAAC,GAAG,CAAC,IAAI;gBAAE,OAAO,MAAM,CAAC;YAC7B,OAAO,GAAG,CAAC,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC;QAC/C,CAAC,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAK,CAAC,CAAC;IACtC,CAAC;IAED,2CAA2C;IAC3C,MAAM,wBAAwB,GAAG,uBAAuB,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE;QAC1E,IAAI,aAAmB,CAAC;QAExB,IAAI,mBAAmB,CAAC,SAAS,CAAC,EAAE,CAAC;YACnC,aAAa,GAAG,SAAS,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,EAAE,EAAE,EAAE;gBAC7D,OAAO,EAAE,CAAC,UAAU,GAAG,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC;YAC7D,CAAC,EAAE,SAAS,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;QAC3C,CAAC;aAAM,CAAC;YACN,aAAa,GAAG,SAAS,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,GAAG,EAAE,EAAE;gBACzD,IAAI,CAAC,GAAG,CAAC,IAAI;oBAAE,OAAO,MAAM,CAAC;gBAC7B,OAAO,GAAG,CAAC,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC;YAC/C,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAK,CAAC,CAAC;QACnC,CAAC;QAED,OAAO,kBAAkB,CAAC,UAAU,EAAE,aAAa,EAAE,gBAAgB,CAAC,CAAC;IACzE,CAAC,CAAC,CAAC;IAEH,yDAAyD;IACzD,6EAA6E;IAC7E,2CAA2C;IAE3C,gDAAgD;IAChD,MAAM,mBAAmB,GAAG,wBAAwB,CAAC,IAAI,CACvD,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,YAAY,CAAC,QAAQ,CAC1C,CAAC;IACF,IAAI,mBAAmB,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CACb,oBAAoB,mBAAmB,CAAC,QAAQ,mCAAmC,CACpF,CAAC;IACJ,CAAC;IAED,yCAAyC;IACzC,MAAM,gBAAgB,GAElB,EAAE,CAAC;IAEP,KAAK,MAAM,SAAS,IAAI,wBAAwB,EAAE,CAAC;QACjD,IAAI,CAAC;YACH,IAAI,UAAsB,CAAC;YAC3B,IAAI,QAA2B,CAAC;YAChC,IAAI,SAAyB,CAAC;YAE9B,IAAI,mBAAmB,EAAE,CAAC;gBACxB,QAAQ,GAAG,YAAY,CAAC;gBACxB,SAAS,GAAG,SAA2B,CAAC;gBACxC,UAAU,GAAG,UAAU,CAAC,QAAQ,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;YACvD,CAAC;iBAAM,CAAC;gBACN,QAAQ,GAAG,SAA8B,CAAC;gBAC1C,SAAS,GAAG,YAAY,CAAC;gBACzB,UAAU,GAAG,UAAU,CAAC,QAAQ,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;YACvD,CAAC;YAED,4CAA4C;YAC5C,MAAM,aAAa,GAAG,sBAAsB,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;YAElE,gBAAgB,CAAC,IAAI,CAAC;gBACpB,QAAQ,EAAE,SAAS,CAAC,QAAQ;gBAC5B,eAAe,EAAE,UAAU,CAAC,eAAe;gBAC3C,UAAU,EAAE,UAAU,CAAC,UAAU;gBACjC,aAAa;gBACb,SAAS,EAAE,QAAQ;gBACnB,UAAU,EAAE,SAAS;aACtB,CAAC,CAAC;QACL,CAAC;QAAC,MAAM,CAAC;YACP,2EAA2E;YAC3E,mEAAmE;YACnE,SAAS;QACX,CAAC;IACH,CAAC;IAED,wFAAwF;IACxF,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QAC7B,yCAAyC;QACzC,IAAI,CAAC,CAAC,eAAe,KAAK,CAAC,CAAC,eAAe,EAAE,CAAC;YAC5C,OAAO,CAAC,CAAC,eAAe,GAAG,CAAC,CAAC,eAAe,CAAC;QAC/C,CAAC;QAED,6DAA6D;QAC7D,OAAO,CAAC,CAAC,CAAC,aAAa,IAAI,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,aAAa,IAAI,QAAQ,CAAC,CAAC;IACvE,CAAC,CAAC,CAAC;IAEH,gCAAgC;IAChC,MAAM,UAAU,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;IAEzD,4BAA4B;IAC5B,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,EAAE,UAAU,EAAE,GAAG,KAAK,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC;AACxE,CAAC"}

package/dist/server/src/modules/charges-matcher/providers/transaction-aggregator.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Transaction Aggregator
+ *
+ * Aggregates multiple transactions from a single charge into a unified representation
+ * for matching purposes. Handles fee exclusion, currency validation, business ID
+ * validation, amount summation, date selection, and description concatenation.
+ */
+import type { currency } from '../../documents/types';
+import type { AggregatedTransaction } from '../types.js';
+/**
+ * Minimal transaction interface for aggregation
+ * Based on database schema from accounter_schema.transactions
+ */
+export interface Transaction {
+    id: string;
+    charge_id: string;
+    amount: string;
+    currency: currency;
+    business_id: string | null;
+    event_date: Date;
+    debit_date: Date | null;
+    debit_timestamp: Date | null;
+    source_description: string | null;
+    is_fee: boolean | null;
+}
+/**
+ * Aggregate multiple transactions into a single representation
+ *
+ * Per specification (section 4.2):
+ * 1. Exclude transactions where is_fee = true
+ * 2. If multiple currencies exist: throw error
+ * 3. If multiple non-null business IDs exist: throw error
+ * 4. Amount: sum of all amounts
+ * 5. Currency: the common currency
+ * 6. Business ID: the single non-null business ID (or null if all null)
+ * 7. Date: earliest event_date
+ * 8. Description: concatenate all source_description values with line breaks
+ *
+ * @param transactions - Array of transactions from a charge
+ * @returns Aggregated transaction data
+ *
+ * @throws {Error} If transactions array is empty
+ * @throws {Error} If no non-fee transactions exist after filtering
+ * @throws {Error} If multiple different currencies exist
+ * @throws {Error} If multiple different non-null business IDs exist
+ *
+ * @example
+ * const aggregated = aggregateTransactions([
+ *   { amount: 100, currency: 'USD', business_id: 'b1', event_date: new Date('2024-01-15'), ... },
+ *   { amount: 50, currency: 'USD', business_id: 'b1', event_date: new Date('2024-01-20'), ... }
+ * ]);
+ * // Returns: { amount: 150, currency: 'USD', businessId: 'b1', date: Date('2024-01-15'), ... }
+ */
+export declare function aggregateTransactions(transactions: Transaction[]): AggregatedTransaction;

package/dist/server/src/modules/charges-matcher/providers/transaction-aggregator.js

@@ -0,0 +1,93 @@
+/**
+ * Transaction Aggregator
+ *
+ * Aggregates multiple transactions from a single charge into a unified representation
+ * for matching purposes. Handles fee exclusion, currency validation, business ID
+ * validation, amount summation, date selection, and description concatenation.
+ */
+/**
+ * Aggregate multiple transactions into a single representation
+ *
+ * Per specification (section 4.2):
+ * 1. Exclude transactions where is_fee = true
+ * 2. If multiple currencies exist: throw error
+ * 3. If multiple non-null business IDs exist: throw error
+ * 4. Amount: sum of all amounts
+ * 5. Currency: the common currency
+ * 6. Business ID: the single non-null business ID (or null if all null)
+ * 7. Date: earliest event_date
+ * 8. Description: concatenate all source_description values with line breaks
+ *
+ * @param transactions - Array of transactions from a charge
+ * @returns Aggregated transaction data
+ *
+ * @throws {Error} If transactions array is empty
+ * @throws {Error} If no non-fee transactions exist after filtering
+ * @throws {Error} If multiple different currencies exist
+ * @throws {Error} If multiple different non-null business IDs exist
+ *
+ * @example
+ * const aggregated = aggregateTransactions([
+ *   { amount: 100, currency: 'USD', business_id: 'b1', event_date: new Date('2024-01-15'), ... },
+ *   { amount: 50, currency: 'USD', business_id: 'b1', event_date: new Date('2024-01-20'), ... }
+ * ]);
+ * // Returns: { amount: 150, currency: 'USD', businessId: 'b1', date: Date('2024-01-15'), ... }
+ */
+export function aggregateTransactions(transactions) {
+    // Validate non-empty input
+    if (!transactions || transactions.length === 0) {
+        throw new Error('Cannot aggregate transactions: array is empty');
+    }
+    // Filter out fee transactions
+    const nonFeeTransactions = transactions.filter(t => t.is_fee !== true);
+    // Validate we have transactions after filtering
+    if (nonFeeTransactions.length === 0) {
+        throw new Error('Cannot aggregate transactions: all transactions are marked as fees');
+    }
+    // Validate single currency
+    const currencies = new Set(nonFeeTransactions.map(t => t.currency));
+    if (currencies.size > 1) {
+        throw new Error(`Cannot aggregate transactions: multiple currencies found (${Array.from(currencies).join(', ')})`);
+    }
+    // Validate single non-null business ID
+    const businessIds = nonFeeTransactions
+        .map(t => t.business_id)
+        .filter((id) => id !== null && id !== undefined);
+    const uniqueBusinessIds = new Set(businessIds);
+    if (uniqueBusinessIds.size > 1) {
+        throw new Error(`Cannot aggregate transactions: multiple business IDs found (${Array.from(uniqueBusinessIds).join(', ')})`);
+    }
+    // Sum amounts
+    const totalAmount = nonFeeTransactions.reduce((sum, t) => sum + Number(t.amount), 0);
+    // Get common currency (safe since we validated single currency)
+    const currency = nonFeeTransactions[0].currency;
+    // Get business ID (single non-null or null if all null)
+    const businessId = uniqueBusinessIds.size === 1 ? Array.from(uniqueBusinessIds)[0] : null;
+    // Get earliest event_date
+    const earliestDate = nonFeeTransactions.reduce((earliest, t) => {
+        return t.event_date < earliest ? t.event_date : earliest;
+    }, nonFeeTransactions[0].event_date);
+    // Get earliest debit_date
+    const earliestDebitDate = nonFeeTransactions.reduce((earliest, t) => {
+        const debitDate = t.debit_timestamp ?? t.debit_date;
+        if (debitDate === null)
+            return earliest;
+        if (earliest === null)
+            return debitDate;
+        return debitDate < earliest ? debitDate : earliest;
+    }, null);
+    // Concatenate descriptions with line breaks, filtering out nulls
+    const descriptions = nonFeeTransactions
+        .map(t => t.source_description)
+        .filter((desc) => desc !== null && desc !== undefined && desc.trim() !== '');
+    const description = descriptions.length > 0 ? descriptions.join('\n') : '';
+    return {
+        amount: totalAmount,
+        currency,
+        businessId,
+        date: earliestDate,
+        description,
+        debitDate: earliestDebitDate,
+    };
+}
+//# sourceMappingURL=transaction-aggregator.js.map

package/dist/server/src/modules/charges-matcher/providers/transaction-aggregator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction-aggregator.js","sourceRoot":"","sources":["../../../../../../src/modules/charges-matcher/providers/transaction-aggregator.ts"],"names":[],"mappings":"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"}

package/dist/server/src/modules/charges-matcher/resolvers/auto-match-charges.resolver.d.ts

@@ -0,0 +1,2 @@
+import type { ChargesMatcherModule } from '../types.js';
+export declare const autoMatchChargesResolver: ChargesMatcherModule.Resolvers;

package/dist/server/src/modules/charges-matcher/resolvers/auto-match-charges.resolver.js

@@ -0,0 +1,22 @@
+import { GraphQLError } from 'graphql';
+import { ChargesMatcherProvider } from '../providers/charges-matcher.provider.js';
+export const autoMatchChargesResolver = {
+    Mutation: {
+        autoMatchCharges: async (_, __, context) => {
+            try {
+                const result = await context.injector.get(ChargesMatcherProvider).autoMatchCharges(context);
+                return result;
+            }
+            catch (e) {
+                if (e instanceof GraphQLError) {
+                    throw e;
+                }
+                const message = e?.message ??
+                    e?.errors.map(e => e.message).toString() ??
+                    'Unknown error';
+                throw new GraphQLError(message);
+            }
+        },
+    },
+};
+//# sourceMappingURL=auto-match-charges.resolver.js.map

package/dist/server/src/modules/charges-matcher/resolvers/auto-match-charges.resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-match-charges.resolver.js","sourceRoot":"","sources":["../../../../../../src/modules/charges-matcher/resolvers/auto-match-charges.resolver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,sBAAsB,EAAE,MAAM,0CAA0C,CAAC;AAGlF,MAAM,CAAC,MAAM,wBAAwB,GAAmC;IACtE,QAAQ,EAAE;QACR,gBAAgB,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE;YACzC,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;gBAC5F,OAAO,MAAM,CAAC;YAChB,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,IAAI,CAAC,YAAY,YAAY,EAAE,CAAC;oBAC9B,MAAM,CAAC,CAAC;gBACV,CAAC;gBACD,MAAM,OAAO,GACV,CAAW,EAAE,OAAO;oBACpB,CAAyB,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE;oBACjE,eAAe,CAAC;gBAClB,MAAM,IAAI,YAAY,CAAC,OAAO,CAAC,CAAC;YAClC,CAAC;QACH,CAAC;KACF;CACF,CAAC"}

package/dist/server/src/modules/charges-matcher/resolvers/find-charge-matches.resolver.d.ts

@@ -0,0 +1,2 @@
+import type { ChargesMatcherModule } from '../types.js';
+export declare const findChargeMatchesResolver: ChargesMatcherModule.Resolvers;

package/dist/server/src/modules/charges-matcher/resolvers/find-charge-matches.resolver.js

@@ -0,0 +1,24 @@
+import { GraphQLError } from 'graphql';
+import { ChargesMatcherProvider } from '../providers/charges-matcher.provider.js';
+export const findChargeMatchesResolver = {
+    Query: {
+        findChargeMatches: async (_, { chargeId }, context) => {
+            try {
+                const result = await context.injector
+                    .get(ChargesMatcherProvider)
+                    .findMatchesForCharge(chargeId, context);
+                return result;
+            }
+            catch (e) {
+                if (e instanceof GraphQLError) {
+                    throw e;
+                }
+                const message = e?.message ??
+                    e?.errors.map(e => e.message).toString() ??
+                    'Unknown error';
+                throw new GraphQLError(message);
+            }
+        },
+    },
+};
+//# sourceMappingURL=find-charge-matches.resolver.js.map

package/dist/server/src/modules/charges-matcher/resolvers/find-charge-matches.resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-charge-matches.resolver.js","sourceRoot":"","sources":["../../../../../../src/modules/charges-matcher/resolvers/find-charge-matches.resolver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,sBAAsB,EAAE,MAAM,0CAA0C,CAAC;AAGlF,MAAM,CAAC,MAAM,yBAAyB,GAAmC;IACvE,KAAK,EAAE;QACL,iBAAiB,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,QAAQ,EAAE,EAAE,OAAO,EAAE,EAAE;YACpD,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,QAAQ;qBAClC,GAAG,CAAC,sBAAsB,CAAC;qBAC3B,oBAAoB,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;gBAC3C,OAAO,MAAM,CAAC;YAChB,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,IAAI,CAAC,YAAY,YAAY,EAAE,CAAC;oBAC9B,MAAM,CAAC,CAAC;gBACV,CAAC;gBACD,MAAM,OAAO,GACV,CAAW,EAAE,OAAO;oBACpB,CAAyB,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE;oBACjE,eAAe,CAAC;gBAClB,MAAM,IAAI,YAAY,CAAC,OAAO,CAAC,CAAC;YAClC,CAAC;QACH,CAAC;KACF;CACF,CAAC"}

package/dist/server/src/modules/charges-matcher/resolvers/index.d.ts

@@ -0,0 +1,2 @@
+import type { ChargesMatcherModule } from '../types.js';
+export declare const chargesMatcherResolvers: ChargesMatcherModule.Resolvers;

package/dist/server/src/modules/charges-matcher/resolvers/index.js

@@ -0,0 +1,11 @@
+import { autoMatchChargesResolver } from './auto-match-charges.resolver.js';
+import { findChargeMatchesResolver } from './find-charge-matches.resolver.js';
+export const chargesMatcherResolvers = {
+    Query: {
+        ...findChargeMatchesResolver.Query,
+    },
+    Mutation: {
+        ...autoMatchChargesResolver.Mutation,
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/server/src/modules/charges-matcher/resolvers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../src/modules/charges-matcher/resolvers/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAE9E,MAAM,CAAC,MAAM,uBAAuB,GAAmC;IACrE,KAAK,EAAE;QACL,GAAG,yBAAyB,CAAC,KAAK;KACnC;IACD,QAAQ,EAAE;QACR,GAAG,wBAAwB,CAAC,QAAQ;KACrC;CACF,CAAC"}

package/dist/server/src/modules/charges-matcher/typeDefs/charges-matcher.graphql.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("graphql").DocumentNode;
+export default _default;