import { PoolClient } from 'pg'; import { LedgerAccount } from '../models'; export type AccountKind = 'main' | 'bonus' | 'test'; /** * Repository for double-entry ledger accounts and balance operations. * Manages available and locked balances with transactional credit, debit, and transfer flows. */ /** * Ensures a ledger account exists for a user and wallet type, then returns it. * @param userId - ID of the account owner. * @param walletTypeId - Wallet type for the account. * @returns The ledger account record (created if it did not exist). */ export declare function getOrCreateAccount(userId: string, walletTypeId: number, accountKind?: AccountKind): Promise; /** * @deprecated Use getOrCreateAccount with accountKind. Kept for backward compatibility. */ export declare function getOrCreateMainAccount(userId: string, walletTypeId: number): Promise; export declare function getOrCreateBonusAccount(userId: string, walletTypeId: number): Promise; export declare function getOrCreateTestAccount(userId: string, walletTypeId: number): Promise; /** * Retrieves an existing ledger account without creating one. * @param userId - ID of the account owner. * @param walletTypeId - Wallet type for the account. * @returns The ledger account record, or null if it does not exist. */ export declare function getAccount(userId: string, walletTypeId: number, accountKind?: AccountKind): Promise; /** * Adds funds to an account's available balance and records a ledger entry. * Runs inside a database transaction with row-level locking. * @param accountId - ID of the ledger account to credit. * @param amount - Amount to add in the smallest currency unit. * @param type - Ledger entry type identifier. * @param referenceType - Optional reference entity type (e.g. transaction). * @param referenceId - Optional reference entity ID. * @returns Resolves when the balance and entry have been committed. * @throws Error if the account is not found. */ export declare function credit(accountId: string, amount: bigint, type: string, referenceType: string | null, referenceId: string | null): Promise; /** * Credits an account within an existing authorized transaction (caller manages COMMIT). */ export declare function creditUsingClient(client: PoolClient, accountId: string, amount: bigint, type: string, referenceType: string | null, referenceId: string | null): Promise; /** * Removes funds from an account's available balance and records a ledger entry. * Runs inside a database transaction with row-level locking. * @param accountId - ID of the ledger account to debit. * @param amount - Amount to subtract in the smallest currency unit. * @param type - Ledger entry type identifier. * @param referenceType - Optional reference entity type (e.g. transaction). * @param referenceId - Optional reference entity ID. * @returns Resolves when the balance and entry have been committed. * @throws Error if the account is not found or available balance is insufficient. */ export declare function debit(accountId: string, amount: bigint, type: string, referenceType: string | null, referenceId: string | null): Promise; /** * Moves funds from available balance to locked balance (e.g. pending withdrawal). * @param accountId - ID of the ledger account. * @param amount - Amount to lock in the smallest currency unit. * @returns Resolves when the balance transfer has been committed. * @throws Error if the account is not found or available balance is insufficient. */ export declare function lockBalance(accountId: string, amount: bigint): Promise; /** * Moves funds from locked balance back to available balance (e.g. cancelled withdrawal). * @param accountId - ID of the ledger account. * @param amount - Amount to unlock in the smallest currency unit. * @returns Resolves when the balance transfer has been committed. * @throws Error if the account is not found. */ export declare function unlockBalance(accountId: string, amount: bigint): Promise; /** * Permanently removes funds from locked balance (e.g. completed withdrawal). * @param accountId - ID of the ledger account. * @param amount - Amount to deduct from locked balance in the smallest currency unit. * @returns Resolves when the deduction has been committed. * @throws Error if the account is not found or locked balance is insufficient. */ export declare function deductLocked(accountId: string, amount: bigint): Promise; /** * Debits the sender and credits the receiver in a single atomic transaction. * Used for internal transfers between ledger accounts. * @param senderAccountId - ID of the account to debit. * @param receiverAccountId - ID of the account to credit. * @param amount - Transfer amount in the smallest currency unit. * @param referenceType - Reference entity type shared by both ledger entries. * @param referenceId - Reference entity ID shared by both ledger entries. * @param options.minRemaining - Optional floor that must remain on the sender after debit (peer transfers). * @returns Resolves when both balance updates and entries have been committed. * @throws Error if either account is not found, the sender has insufficient balance, or minRemaining would be breached. */ export declare function transferBetweenAccounts(senderAccountId: string, receiverAccountId: string, amount: bigint, referenceType: string, referenceId: string, options?: { minRemaining?: bigint; }): Promise; /** * Finalizes a withdrawal after on-chain broadcast: removes locked funds and records ledger entry. * Does not debit available again (funds were moved to locked during initiation). */ export declare function finalizeWithdrawalFromLocked(accountId: string, amount: bigint, transactionId: string): Promise; export type LedgerIntegrityRow = { id: string; user_id: string; wallet_type_id: number; available_balance: string; locked_balance: string; entries_sum: string; }; export declare function listAllAccountsForIntegrity(): Promise; export declare function listUnauthorizedEntryTypes(accountId: string, allowedTypes: string[]): Promise; //# sourceMappingURL=ledgerRepository.d.ts.map