games_app/backend/dist/repositories/ledgerRepository.d.ts
2026-06-29 15:01:23 +02:00

102 lines
5.7 KiB
TypeScript

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<LedgerAccount>;
/**
* @deprecated Use getOrCreateAccount with accountKind. Kept for backward compatibility.
*/
export declare function getOrCreateMainAccount(userId: string, walletTypeId: number): Promise<LedgerAccount>;
export declare function getOrCreateBonusAccount(userId: string, walletTypeId: number): Promise<LedgerAccount>;
export declare function getOrCreateTestAccount(userId: string, walletTypeId: number): Promise<LedgerAccount>;
/**
* 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<LedgerAccount | null>;
/**
* 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<void>;
/**
* 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<void>;
/**
* 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<void>;
/**
* 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<void>;
/**
* 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<void>;
/**
* 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.
* @returns Resolves when both balance updates and entries have been committed.
* @throws Error if either account is not found or the sender has insufficient balance.
*/
export declare function transferBetweenAccounts(senderAccountId: string, receiverAccountId: string, amount: bigint, referenceType: string, referenceId: string): Promise<void>;
/**
* 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<void>;
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<LedgerIntegrityRow[]>;
export declare function listUnauthorizedEntryTypes(accountId: string, allowedTypes: string[]): Promise<string[]>;
//# sourceMappingURL=ledgerRepository.d.ts.map