games_app/backend/dist/repositories/transactionRepository.d.ts

107 lines
4.9 KiB
TypeScript

import { PoolClient } from 'pg';
import { Transaction } from '../models';
/** Wallet activity tabs on the player UI. */
export type TransactionActivityCategory = 'deposits' | 'withdrawals' | 'transfers' | 'predictions';
/**
* Repository for blockchain transaction records.
* Persists deposits, withdrawals, and transfers with status and confirmation tracking.
*/
/**
* Inserts a new transaction record.
* @param data - Transaction fields to persist.
* @param data.userId - ID of the user who owns the transaction.
* @param data.walletTypeId - Wallet type for this transaction.
* @param data.type - Transaction kind: deposit, withdrawal, or transfer.
* @param data.amount - Amount in the smallest currency unit.
* @param data.fee - Optional fee amount (defaults to 0).
* @param data.status - Current transaction status.
* @param data.blockchainTxId - Optional on-chain transaction hash or ID.
* @param data.fromAddress - Optional sender address.
* @param data.toAddress - Optional recipient address.
* @param data.confirmations - Optional current confirmation count.
* @param data.requiredConfirmations - Optional confirmations required before completion.
* @param data.metadata - Optional additional context as key-value pairs.
* @returns The newly created transaction record.
*/
export declare function create(data: {
userId: string;
walletTypeId: number;
type: 'deposit' | 'withdrawal' | 'transfer' | 'game_stake' | 'game_payout' | 'game_refund' | 'bonus' | 'admin_adjustment';
amount: bigint;
fee?: bigint;
status: string;
blockchainTxId?: string | null;
fromAddress?: string | null;
toAddress?: string | null;
confirmations?: number | null;
requiredConfirmations?: number | null;
metadata?: Record<string, unknown> | null;
}): Promise<Transaction>;
/**
* Inserts a deposit transaction if the blockchain tx id is new (idempotent).
* Must run inside an authorized DB transaction started by the caller.
*/
export declare function insertDepositIfNew(client: PoolClient, data: {
userId: string;
walletTypeId: number;
amount: bigint;
blockchainTxId: string;
fromAddress: string;
toAddress: string;
confirmations: number;
requiredConfirmations: number;
metadata?: Record<string, unknown> | null;
}): Promise<Transaction | null>;
/**
* Updates a transaction's status and optionally its confirmations or blockchain TX ID.
* @param id - ID of the transaction to update.
* @param status - New status value.
* @param confirmations - Optional confirmation count (existing value kept if omitted).
* @param blockchainTxId - Optional blockchain TX ID (existing value kept if omitted).
* @returns Resolves when the row has been updated.
*/
export declare function updateStatus(id: string, status: string, confirmations?: number, blockchainTxId?: string): Promise<void>;
/**
* Finds a transaction by its on-chain transaction ID.
* @param blockchainTxId - Blockchain transaction hash or ID.
* @returns The matching transaction, or null if not found.
*/
export declare function findByBlockchainTxId(blockchainTxId: string): Promise<Transaction | null>;
/**
* Finds a transaction by its primary key.
* @param id - Transaction UUID.
* @returns The matching transaction, or null if not found.
*/
export declare function findById(id: string): Promise<Transaction | null>;
export declare function listCompletedDepositsToAddress(toAddress: string): Promise<Transaction[]>;
/**
* Lists a user's transactions ordered by creation time (newest first).
* @param userId - ID of the user whose transactions to fetch.
* @param limit - Maximum number of rows to return (default 50).
* @param offset - Number of rows to skip for pagination (default 0).
* @returns Array of transaction records.
*/
export declare function listByUserId(userId: string, limit?: number, offset?: number, category?: TransactionActivityCategory): Promise<Transaction[]>;
/**
* Withdrawal rows since a UTC timestamp (for daily limit checks).
* Excludes requests whose funds were returned; `failed` still holds a reservation and counts.
*/
export declare function listWithdrawalsSince(userId: string, since: Date, client?: PoolClient): Promise<Array<{
amount: string;
fee: string;
code: string;
decimals: number;
}>>;
/** Total transaction count for a user (pagination). */
export declare function countByUserId(userId: string, category?: TransactionActivityCategory): Promise<number>;
/** Mirror settled bet outcome onto the original game_stake row for Wallet Activity share UX. */
export declare function mergeGameStakeBetStatus(betId: string, betStatus: 'won' | 'lost' | 'refunded'): Promise<void>;
/**
* Attach candle_predict_bets.status onto game_stake metadata as bet_status
* so clients can label losses and show share consistently (even across pages).
*/
export declare function enrichGameStakeBetStatus<T extends {
type: string;
metadata: Record<string, unknown> | null;
}>(txs: T[]): Promise<T[]>;
//# sourceMappingURL=transactionRepository.d.ts.map