games_app/backend/dist-test-faq/services/referralService.d.ts

321 lines
11 KiB
TypeScript

/**
* 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<ReferralProgramSettings, 'referrer_must_be_verified' | 'referrer_must_have_deposited' | 'referred_must_be_verified' | 'min_referred_predictions'>;
};
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<string | null>;
/**
* 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<string>;
export declare function assertReferrerEligible(referrerId: string): Promise<void>;
/** 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<void>;
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<PredictionCommissionProcessResult>;
/**
* 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<void>;
declare function mapReferralNetworkMember(row: referralRepository.ReferralNetworkRow, countryMap: Map<string, string>): {
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<typeof mapReferralNetworkMember>[];
}>;
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<number>;
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<void>;
export declare function rejectReferralCommissionReview(input: {
payoutId: string;
reviewerId: string;
reason: string;
}): Promise<void>;
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<string, unknown> | 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