@accounter/server
Version:
Accounter GraphQL server
80 lines (79 loc) • 3.99 kB
TypeScript
/**
* Charges Matcher Provider
*
* Provides database-integrated charge matching functionality using the Injector pattern.
* Integrates with existing modules: charges, transactions, and documents.
*/
import { AdminContextProvider } from '../../admin-context/providers/admin-context.provider.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 { type AutoMatchChargesResult, type ChargeMatchesResult, type ChargeMatchProto } from '../types.js';
/**
* Max number of source charges scored concurrently against the shared candidate
* pool. Scoring loads client / issued-document status via DataLoaders, so an
* unbounded burst (up to 100 charges for the BY_SCORE queue) could exhaust the DB
* connection pool or spike CPU; a strictly sequential run would be needlessly slow.
*/
export declare const MATCH_SCORING_CONCURRENCY = 5;
/**
* 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 {
private adminContextProvider;
private chargesProvider;
private transactionsProvider;
private documentsProvider;
private context;
constructor(adminContextProvider: AdminContextProvider, chargesProvider: ChargesProvider, transactionsProvider: TransactionsProvider, documentsProvider: DocumentsProvider, context: GraphQLModules.ModuleContext);
/**
* Find potential matches for an unmatched charge
*
* @param chargeId - ID of the unmatched charge to find matches for
* @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): Promise<ChargeMatchesResult>;
/**
* Find potential matches for a batch of unmatched charges in a single pass.
*
* Powers the awaiting-match queue. Instead of re-querying and re-hydrating the
* candidate pool once per source charge (a heavy, quadratic pattern), it loads
* and classifies the shared candidate pool **once** for the whole batch, then
* scores every source charge against that in-memory pool. The per-source date
* window is still enforced in-memory by `findMatches`, so results are identical
* to calling `findMatchesForCharge` per charge — just far cheaper.
*
* Best-effort per charge: a source that can't be prepared or scored (already
* matched, missing data, etc.) yields an empty match list rather than failing
* the whole batch.
*
* @param chargeIds - Unmatched source charge UUIDs to evaluate
* @returns Map from source charge id to its match suggestions (unsorted)
*/
findMatchesForCharges(chargeIds: string[]): Promise<Map<string, ChargeMatchProto[]>>;
/**
* Load transactions and documents for candidate charges and classify each into
* the `TransactionCharge` / `DocumentCharge` shape the matcher consumes. Loads
* are batched via DataLoaders; matched/empty charges are dropped.
*
* @param candidateCharges - Charge rows to hydrate
* @param excludeChargeId - Optional charge id to skip (e.g. the source charge)
*/
private hydrateCandidateCharges;
/**
* 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.
*
* @returns Summary of matches made, skipped charges, and errors
*/
autoMatchCharges(): Promise<AutoMatchChargesResult>;
}