games_app/backend/dist/repositories/referralRepository.d.ts
2026-07-07 15:03:17 +02:00

314 lines
11 KiB
TypeScript

import type { SybilSignal } from '../services/referralSybilService';
export type ReferralCommissionStatus = 'pending' | 'review' | 'paid' | 'rejected' | 'expired' | 'clawed_back';
export type ReferralProgramSettings = {
id: number;
enabled: boolean;
default_referrer_user_id: string | null;
bonus_withdrawable: boolean;
referrer_must_be_verified: boolean;
referrer_must_have_deposited: boolean;
referred_must_be_verified: boolean;
commission_hold_days: number;
min_referred_predictions: number;
commission_max_pending_days: number;
sybil_detection_enabled: boolean;
sybil_review_threshold: number;
sybil_block_threshold: number;
max_referrals_per_day: number;
max_commission_amount_per_referrer_month_raw: string;
max_commissions_per_referrer_month: number;
slack_alerts_enabled: boolean;
deposit_commissions_enabled: boolean;
withdrawal_commissions_enabled: boolean;
min_first_deposit_raw: string;
commission_wallet_type_id: number;
updated_at: Date;
};
export type ReferralLevel = {
level_number: number;
commission_percent: string;
is_active: boolean;
monthly_max_amount_raw: string;
monthly_max_count: number;
created_at: Date;
updated_at: Date;
};
export type ReferralCommissionSource = 'deposit' | 'withdrawal';
export type ReferralCommissionPayoutRow = {
id: string;
beneficiary_user_id: string;
referred_user_id: string;
level_number: number;
commission_source: ReferralCommissionSource;
first_deposit_transaction_id: string | null;
withdrawal_transaction_id: string | null;
deposit_amount: string;
commission_percent: string;
commission_amount: string;
wallet_type_id: number;
status: ReferralCommissionStatus;
eligible_at: Date;
paid_at: Date | null;
rejection_reason: string | null;
sybil_score: number;
sybil_signals: SybilSignal[] | null;
reviewed_by: string | null;
reviewed_at: Date | null;
review_note: string | null;
created_at: Date;
updated_at: Date;
};
export declare function getSettings(): Promise<ReferralProgramSettings>;
export declare function updateSettings(input: Partial<{
enabled: boolean;
defaultReferrerUserId: string | null;
bonusWithdrawable: boolean;
referrerMustBeVerified: boolean;
referrerMustHaveDeposited: boolean;
referredMustBeVerified: boolean;
commissionHoldDays: number;
minReferredPredictions: number;
commissionMaxPendingDays: number;
sybilDetectionEnabled: boolean;
sybilReviewThreshold: number;
sybilBlockThreshold: number;
maxReferralsPerDay: number;
maxCommissionAmountPerReferrerMonthRaw: string;
maxCommissionsPerReferrerMonth: number;
slackAlertsEnabled: boolean;
depositCommissionsEnabled: boolean;
withdrawalCommissionsEnabled: boolean;
minFirstDepositRaw: string;
commissionWalletTypeId: number;
}>): Promise<ReferralProgramSettings>;
export declare function listLevels(): Promise<ReferralLevel[]>;
export declare function getLevelByNumber(levelNumber: number): Promise<ReferralLevel | null>;
export declare function upsertLevel(levelNumber: number, commissionPercent: number, isActive?: boolean, monthlyMaxAmountRaw?: string, monthlyMaxCount?: number): Promise<void>;
export declare function deleteLevel(levelNumber: number): Promise<void>;
export declare function findUserByReferralCode(code: string): Promise<{
id: string;
email_verified: boolean;
} | null>;
export declare function generateUniqueReferralCode(): Promise<string>;
/**
* Returns the user's referral code, or null if none is assigned.
*/
export declare function getUserReferralCode(userId: string): Promise<string | null>;
/**
* Ensures the user has a unique referral code, generating one when missing.
*/
export declare function ensureUserReferralCode(userId: string): Promise<string>;
export declare function recordCommissionPayout(input: {
beneficiaryUserId: string;
referredUserId: string;
levelNumber: number;
commissionSource?: ReferralCommissionSource;
firstDepositTransactionId?: string | null;
withdrawalTransactionId?: string | null;
baseAmount: bigint;
commissionPercent: number;
commissionAmount: bigint;
walletTypeId: number;
status: ReferralCommissionStatus;
eligibleAt: Date;
sybilScore?: number;
sybilSignals?: SybilSignal[];
}): Promise<string>;
export declare function findCommissionPayoutById(payoutId: string): Promise<ReferralCommissionPayoutRow | null>;
export declare function listPendingCommissionsDue(limit: number): Promise<ReferralCommissionPayoutRow[]>;
export declare function listReviewQueue(opts: {
limit?: number;
offset?: number;
}): Promise<{
items: ReferralCommissionPayoutRow[];
total: number;
}>;
export declare function markCommissionPaid(payoutId: string, fromStatuses?: ReferralCommissionStatus[]): Promise<boolean>;
export declare function moveCommissionToReview(payoutId: string, sybilScore: number, sybilSignals: SybilSignal[]): Promise<boolean>;
export declare function rejectCommissionPayout(payoutId: string, status: 'rejected' | 'expired', reason: string, fromStatuses?: ReferralCommissionStatus[]): Promise<boolean>;
export declare function recordCommissionReviewDecision(input: {
payoutId: string;
reviewerId: string;
approved: boolean;
note?: string;
}): Promise<boolean>;
export declare function countReferredUserRealPredictions(userId: string): Promise<number>;
export declare function beneficiaryHasCompletedDeposit(userId: string): Promise<boolean>;
export declare function getReferralChain(userId: string, maxLevels: number): Promise<Array<{
userId: string;
level: number;
}>>;
export declare function countDirectReferrals(userId: string): Promise<number>;
export declare function getMainAccountPredictionNetProfit(userId: string): Promise<bigint>;
export declare function getWithdrawalGainsAlreadyCommissioned(referredUserId: string): Promise<bigint>;
export declare function getReferrerProfile(userId: string): Promise<{
userId: string;
referralCode: string | null;
firstName: string | null;
lastName: string | null;
createdAt: Date;
} | null>;
export type ReferralNetworkRow = {
user_id: string;
parent_user_id: string;
level_number: number;
referral_code: string | null;
first_name: string | null;
last_name: string | null;
created_at: Date;
first_deposit_at: Date | null;
email_verified: boolean;
country_of_residence: string | null;
direct_referrals_count: string;
real_predictions_count: string;
commissions_generated_raw: string;
commissions_paid_raw: string;
commissions_pending_raw: string;
};
export declare function getReferralDownline(rootUserId: string, maxDepth: number): Promise<ReferralNetworkRow[]>;
export declare function getBeneficiaryCommissionSummary(beneficiaryUserId: string): Promise<{
totalEarnedRaw: bigint;
paidRaw: bigint;
pendingRaw: bigint;
reviewRaw: bigint;
networkSize: number;
payoutCount: number;
}>;
export declare function listBeneficiaryCommissions(beneficiaryUserId: string, opts?: {
limit?: number;
offset?: number;
}): Promise<{
total: number;
items: Array<{
id: string;
referredUserId: string;
referredDisplayName: string;
levelNumber: number;
commissionSource: ReferralCommissionSource;
baseAmount: string;
commissionAmount: string;
commissionPercent: string;
status: ReferralCommissionStatus;
eligibleAt: Date;
paidAt: Date | null;
createdAt: Date;
}>;
}>;
export declare function formatUserDisplayName(firstName: string | null, lastName: string | null, userId: string): string;
export declare function getAdminStats(): Promise<{
usersByCountry: Array<{
country: string;
count: number;
}>;
usersByNationality: Array<{
nationality: string;
count: number;
}>;
referralSummary: {
totalReferred: number;
totalCommissionsPaid: string;
payoutCount: number;
pendingCommissions: string;
pendingCount: number;
reviewCommissions: string;
reviewCount: number;
};
topReferrers: Array<{
userId: string;
referralCode: string | null;
directReferrals: number;
totalEarned: string;
}>;
}>;
export declare function getBeneficiaryMonthlyCommissionStats(beneficiaryUserId: string, levelNumber?: number): Promise<{
reservedAmount: bigint;
reservedCount: number;
paidAmount: bigint;
paidCount: number;
}>;
export declare function markCommissionClawedBack(payoutId: string): Promise<boolean>;
export declare function recordCommissionClawback(input: {
payoutId: string;
beneficiaryUserId: string;
amount: bigint;
reason: string;
clawedBy: string;
}): Promise<string>;
export declare function listRecentClawbacks(limit?: number): Promise<Array<{
id: string;
payout_id: string;
beneficiary_user_id: string;
amount: string;
reason: string;
clawed_by: string;
created_at: Date;
}>>;
export declare function listClawbacksForExport(opts?: {
from?: Date;
to?: Date;
limit?: number;
}): Promise<Array<{
id: string;
payout_id: string;
beneficiary_user_id: string;
referred_user_id: string;
level_number: number;
payout_commission_amount: string;
amount: string;
reason: string;
clawed_by: string;
created_at: Date;
payout_status: string;
}>>;
export declare function getFraudDashboardData(): Promise<{
summary: {
pendingCount: number;
pendingAmount: string;
reviewCount: number;
reviewAmount: string;
paidThisMonthCount: number;
paidThisMonthAmount: string;
clawedBackThisMonthCount: number;
clawedBackThisMonthAmount: string;
blockedThisMonthCount: number;
capBlockedThisMonthCount: number;
};
sybilSignalBreakdown: Array<{
signal: string;
count: number;
}>;
highRiskReferrers: Array<{
userId: string;
referralCode: string | null;
avgSybilScore: number;
reviewCount: number;
paidThisMonthAmount: string;
reservedThisMonthAmount: string;
inactiveReferrals: number;
}>;
recentClawbacks: Array<{
id: string;
payoutId: string;
beneficiaryUserId: string;
amount: string;
reason: string;
clawedBy: string;
createdAt: Date;
}>;
recentCapBlocks: Array<{
userId: string | null;
action: string;
resourceId: string | null;
metadata: Record<string, unknown> | null;
createdAt: Date;
}>;
clawbackCandidates: Array<{
id: string;
beneficiaryUserId: string;
referredUserId: string;
commissionAmount: string;
paidAt: Date | null;
sybilScore: number;
}>;
}>;
//# sourceMappingURL=referralRepository.d.ts.map