318 lines
11 KiB
TypeScript
318 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;
|
|
updatedAt: Date;
|
|
};
|
|
levels: {
|
|
levelNumber: number;
|
|
commissionPercent: number;
|
|
isActive: boolean;
|
|
monthlyMaxAmountRaw: string;
|
|
monthlyMaxCount: number;
|
|
}[];
|
|
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
|