107 lines
6.0 KiB
TypeScript
107 lines
6.0 KiB
TypeScript
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<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>;
|
|
/**
|
|
* 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<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
|