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

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

@@ -0,0 +1,133 @@
+/**
+ * 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 { findMatches } from './single-match.provider.js';
+/**
+ * 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, allCandidates, userId) {
+    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;
+    let candidatesForMatching;
+    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, charge2) {
+    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)
+}
+//# sourceMappingURL=auto-match.provider.js.map

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

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

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

@@ -0,0 +1,38 @@
+/**
+ * Charges Matcher Provider
+ *
+ * Provides database-integrated charge matching functionality using the Injector pattern.
+ * Integrates with existing modules: charges, transactions, and documents.
+ */
+import { type AutoMatchChargesResult, type ChargeMatchesResult } from '../types.js';
+/**
+ * Charges Matcher Provider
+ *
+ * Provides high-level charge matching operations with database integration.
+ * Uses the Injector pattern to access existing providers from other modules.
+ */
+export declare 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
+     */
+    findMatchesForCharge(chargeId: string, context: GraphQLModules.AppContext): Promise<ChargeMatchesResult>;
+    /**
+     * 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
+     */
+    autoMatchCharges(context: GraphQLModules.AppContext): Promise<AutoMatchChargesResult>;
+}

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

@@ -0,0 +1,248 @@
+/**
+ * Charges Matcher Provider
+ *
+ * Provides database-integrated charge matching functionality using the Injector pattern.
+ * Integrates with existing modules: charges, transactions, and documents.
+ */
+import { __decorate } from "tslib";
+import { Injectable, Scope } from 'graphql-modules';
+import { mergeChargesExecutor } from '../../charges/helpers/merge-charges.hepler.js';
+import { ChargesProvider } from '../../charges/providers/charges.provider.js';
+import { DocumentsProvider } from '../../documents/providers/documents.provider.js';
+import { TransactionsProvider } from '../../transactions/providers/transactions.provider.js';
+import { dateToTimelessDateString } from '../../../shared/helpers/index.js';
+import { validateChargeIsUnmatched } from '../helpers/charge-validator.helper.js';
+import { ChargeType, } from '../types.js';
+import { determineMergeDirection, processChargeForAutoMatch } from './auto-match.provider.js';
+import { aggregateDocuments } from './document-aggregator.js';
+import { findMatches } 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.
+ */
+let ChargesMatcherProvider = 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, context) {
+        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));
+        const sourceDocuments = (await documentsProvider.getDocumentsByChargeIdLoader.load(chargeId));
+        // 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;
+        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 = [];
+        for (const candidate of candidateCharges) {
+            // Skip the source charge itself
+            if (candidate.id === chargeId) {
+                continue;
+            }
+            const candidateTransactions = (await transactionsProvider.transactionsByChargeIDLoader.load(candidate.id));
+            const candidateDocuments = (await documentsProvider.getDocumentsByChargeIdLoader.load(candidate.id));
+            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;
+        if (hasTransactions) {
+            sourceChargeData = {
+                chargeId,
+                transactions: sourceTransactions,
+            };
+        }
+        else {
+            sourceChargeData = {
+                chargeId,
+                documents: sourceDocuments,
+            };
+        }
+        // Step 8: Call core findMatches function
+        const matches = 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) {
+        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 = [];
+        const mergedChargeIds = new Set(); // Track merged charges to exclude from processing
+        for (const charge of allCharges) {
+            const transactions = (await transactionsProvider.transactionsByChargeIDLoader.load(charge.id));
+            const documents = (await documentsProvider.getDocumentsByChargeIdLoader.load(charge.id));
+            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 = {
+            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;
+    }
+};
+ChargesMatcherProvider = __decorate([
+    Injectable({
+        scope: Scope.Operation,
+    })
+], ChargesMatcherProvider);
+export { ChargesMatcherProvider };
+//# sourceMappingURL=charges-matcher.provider.js.map

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

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

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

@@ -0,0 +1,61 @@
+/**
+ * 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 '../../documents/types.js';
+import { type DocumentType } from '../helpers/document-amount.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;
+    charge_id: string | null;
+    creditor_id: string | null;
+    debtor_id: string | null;
+    currency_code: currency | null;
+    date: Date | null;
+    total_amount: number | null;
+    type: DocumentType;
+    serial_number: string | null;
+    image_url: string | null;
+    file_url: string | null;
+}
+/**
+ * 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 declare function aggregateDocuments(documents: Document[], adminBusinessId: string): Omit<AggregatedDocument, 'businessIsCreditor'>;

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

@@ -0,0 +1,153 @@
+/**
+ * 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 { normalizeDocumentAmount } from '../helpers/document-amount.helper.js';
+import { extractDocumentBusiness } from '../helpers/document-business.helper.js';
+/**
+ * Accounting document types (used for type priority filtering)
+ */
+const INVOICE_TYPES = ['INVOICE', 'CREDIT_INVOICE'];
+const RECEIPT_TYPES = ['RECEIPT', 'INVOICE_RECEIPT'];
+/**
+ * Check if document type is an invoice or credit invoice
+ */
+function isInvoiceType(type) {
+    return INVOICE_TYPES.includes(type);
+}
+/**
+ * Check if document type is a receipt or invoice-receipt
+ */
+function isReceiptType(type) {
+    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, adminBusinessId) {
+    // 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 !== 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 !== 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 !== 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,
+    };
+}
+//# sourceMappingURL=document-aggregator.js.map