/** * Referral program: registration resolution, deferred first-deposit commissions, admin config. */ import * as referralRepository from '../repositories/referralRepository'; import type { ReferralCommissionPayoutRow, ReferralProgramSettings } from '../repositories/referralRepository'; import { type SybilSignal } from './referralSybilService'; export declare class ReferralError extends Error { constructor(message: string); } export type ReferralEligibilityInput = { referredEmailVerified: boolean; referredIsEnabled: boolean; referredUnderSurveillance: boolean; referredRealPredictionCount: number; beneficiaryIsEnabled: boolean; beneficiaryUnderSurveillance: boolean; beneficiaryEmailVerified: boolean; beneficiaryHasDeposited: boolean; /** Prediction commissions pay immediately — skip min_referred_predictions. */ commissionSource?: ReferralCommissionPayoutRow['commission_source']; settings: Pick; }; export type ReferralEligibilityResult = { eligible: boolean; reasons: string[]; }; export declare function evaluateReferralCommissionEligibility(input: ReferralEligibilityInput): ReferralEligibilityResult; export declare function isCommissionPendingExpired(createdAt: Date, maxPendingDays: number, now?: Date): boolean; export declare function validateReferralCode(code: string): Promise<{ valid: boolean; referrerId?: string; reason?: string; }>; export declare function resolveReferrerId(referralCode?: string | null): Promise; /** * Bootstraps the referral network root during initial platform setup. * Assigns a unique referral code to the super admin and sets them as the default referrer. */ export declare function bootstrapReferralRootAtPlatformSetup(superAdminUserId: string): Promise; export declare function assertReferrerEligible(referrerId: string): Promise; /** Percent of base amount in raw units (e.g. stake or deposit). */ export declare function calcCommission(baseAmount: bigint, percent: number): bigint; /** * Creates pending multi-level referral commissions on a user's first deposit. * Pool funds are reserved immediately; bonus wallet credit happens after the hold period. */ export declare function processFirstDepositReferralCommissions(input: { userId: string; depositTransactionId: string; depositAmount: bigint; walletTypeId: number; }): Promise; export type PredictionCommissionProcessResult = { attempted: number; paid: number; paidAmountRaw: string; reviewQueued: number; skippedInsufficientPool: number; skippedOther: number; /** True when a level could not be paid due to empty pool (FIFO stop signal). */ hitInsufficientPool: boolean; }; export declare function processPredictionReferralCommissions(input: { betId: string; referredUserId: string; stakeRaw: bigint; stakeAccountKind: 'main' | 'bonus' | 'test'; walletTypeId: number; /** Terminal bet outcome; neutral/refund must not call this. */ betOutcome: 'won' | 'lost'; /** When set, only these referrer user ids are considered (regularization). */ onlyBeneficiaryIds?: string[]; /** When true, stop the level loop after the first insufficient-pool debit. */ stopOnInsufficientPool?: boolean; }): Promise; /** * Creates pending multi-level referral commissions on withdrawal. * Base = commissionable prediction gains (main account), not deposited principal. */ export declare function processWithdrawalReferralCommissions(input: { userId: string; withdrawalTransactionId: string; withdrawalAmount: bigint; walletTypeId: number; }): Promise; declare function mapReferralNetworkMember(row: referralRepository.ReferralNetworkRow, countryMap: Map): { userId: string; parentUserId: string; levelNumber: number; displayName: string; email: string | null; referralCode: string | null; countryOfResidence: string | null; countryName: string | null; registeredAt: string; firstDepositAt: string | null; emailVerified: boolean; status: 'active' | 'registered' | 'unverified'; directReferralsCount: number; realPredictionsCount: number; commissionsGeneratedRaw: string; commissionsPaidRaw: string; commissionsPendingRaw: string; }; export declare function getUserReferralDashboard(userId: string): Promise<{ referralCode: string | null; referralLink: string; directReferrals: number; bonusWithdrawable: boolean; programEnabled: boolean; commissionModes: { depositEnabled: boolean; withdrawalEnabled: boolean; predictionEnabled: boolean; }; levels: Array<{ levelNumber: number; commissionPercent: number; }>; maxNetworkDepth: number; referrer: { displayName: string; referralCode: string | null; memberSince: string; } | null; summary: { networkSize: number; totalEarnedRaw: string; paidRaw: string; pendingRaw: string; reviewRaw: string; payoutCount: number; }; network: ReturnType[]; }>; export declare function getUserReferralCommissions(userId: string, opts?: { limit?: number; offset?: number; }): Promise<{ total: number; items: { id: string; referredUserId: string; referredDisplayName: string; levelNumber: number; commissionSource: referralRepository.ReferralCommissionSource; baseAmountRaw: string; commissionAmountRaw: string; commissionPercent: number; status: referralRepository.ReferralCommissionStatus; eligibleAt: string; paidAt: string | null; createdAt: string; }[]; }>; /** * Settles pending referral commissions whose hold period has elapsed. * Returns the number of payouts paid or rejected/expired. */ export declare function processPendingReferralCommissions(limit?: number): Promise; export declare function listReferralReviewQueue(opts: { limit?: number; offset?: number; }): Promise<{ total: number; items: { id: string; beneficiaryUserId: string; referredUserId: string; levelNumber: number; depositAmount: string; commissionAmount: string; commissionPercent: number; sybilScore: number; sybilSignals: SybilSignal[]; eligibleAt: Date; createdAt: Date; }[]; }>; export declare function approveReferralCommissionReview(input: { payoutId: string; reviewerId: string; note?: string; }): Promise; export declare function rejectReferralCommissionReview(input: { payoutId: string; reviewerId: string; reason: string; }): Promise; export declare function getReferralCommissionPollIntervalMs(): number; export declare function clawbackReferralCommission(input: { payoutId: string; adminId: string; reason: string; }): Promise<{ clawbackId: string; amountClawed: string; }>; export declare function getReferralFraudDashboard(): Promise<{ settings: { maxCommissionAmountPerReferrerMonthRaw: string; maxCommissionsPerReferrerMonth: number; }; reviewQueuePreview: { id: string; beneficiaryUserId: string; referredUserId: string; commissionAmount: string; sybilScore: number; sybilSignals: SybilSignal[]; createdAt: Date; }[]; 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 | null; createdAt: Date; }>; clawbackCandidates: Array<{ id: string; beneficiaryUserId: string; referredUserId: string; commissionAmount: string; paidAt: Date | null; sybilScore: number; }>; }>; export declare function getUserReferralInfo(userId: string): Promise<{ referralCode: string | null; referralLink: string; directReferrals: number; bonusWithdrawable: boolean; }>; export declare function getProgramSettingsForAdmin(): Promise<{ settings: { 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; predictionCommissionsEnabled: boolean; minFirstDepositRaw: string; commissionWalletTypeId: number; commissionWalletCode: string; commissionWalletLabel: string; updatedAt: Date; }; levels: { levelNumber: number; commissionPercent: number; isActive: boolean; monthlyMaxAmountRaw: string; monthlyMaxCount: number; }[]; /** @deprecated Kept for older clients — always the single ledger type. */ walletTypes: { id: number; code: string; name: string; network: string; label: string; }[]; pools: { walletTypeId: number; availableBalance: string; code: string | null; name: string | null; network: string | null; label: string; }[]; }>; export {}; //# sourceMappingURL=referralService.d.ts.map