ts-client-lib 0.0.7

package/entities/TSMoney.js

@@ -0,0 +1,311 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TSCurrencies = exports.TSMoney = void 0;
+var TSCurrencies_1 = require("./TSCurrencies");
+Object.defineProperty(exports, "TSCurrencies", { enumerable: true, get: function () { return TSCurrencies_1.TSCurrencies; } });
+var isInt = function (n) {
+    return Number(n) === n && n % 1 === 0;
+};
+var decimalPlaces = function (num) {
+    var match = String(num).match(/(?:\.(\d+))?(?:[eE]([+-]?\d+))?$/);
+    return !match ? 0 : Math.max(0, (match[1] ? match[1].length : 0) - (match[2] ? Number(match[2]) : 0));
+};
+var assertSameCurrency = function (left, right) {
+    if (left.currency !== right.currency) {
+        throw new Error('Different currencies');
+    }
+};
+var assertType = function (other) {
+    if (!(other instanceof TSMoney)) {
+        throw new TypeError('Instance of TSMoney required');
+    }
+};
+var assertOperand = function (operand) {
+    if (isNaN(parseFloat(String(operand))) && !isFinite(operand)) {
+        throw new TypeError('Operand must be a number');
+    }
+};
+var getCurrencyObject = function (currency) {
+    return (0, TSCurrencies_1.resolveCurrency)(currency);
+};
+var TSMoney = /** @class */ (function () {
+    /**
+     * Creates a new TSMoney instance. The created TSMoney instances is a value object thus it is immutable.
+     *
+     * @param {Number} amount
+     * @param {Object/String} currency
+     * @returns {TSMoney}
+     * @constructor
+     */
+    function TSMoney(amount, currency) {
+        if (typeof currency === 'string') {
+            currency = getCurrencyObject(currency);
+        }
+        if (typeof currency !== 'object') {
+            throw new TypeError('Invalid currency');
+        }
+        if (!isInt(amount)) {
+            throw new TypeError('Amount must be an integer');
+        }
+        this.amount = amount;
+        this.currency = currency.code;
+        Object.freeze(this);
+    }
+    TSMoney.fromInteger = function (amount, currency) {
+        if (typeof amount === 'object') {
+            if (amount.amount === undefined || amount.currency === undefined) {
+                throw new TypeError('Missing required parameters amount,currency');
+            }
+            currency = amount.currency;
+            amount = amount.amount;
+        }
+        if (!isInt(amount)) {
+            throw new TypeError('Amount must be an integer value');
+        }
+        return new TSMoney(amount, currency);
+    };
+    TSMoney.fromDecimal = function (amount, currency, rounder) {
+        if (typeof amount === 'object') {
+            if (amount.amount === undefined || amount.currency === undefined) {
+                throw new TypeError('Missing required parameters amount,currency');
+            }
+            rounder = currency;
+            currency = amount.currency;
+            amount = amount.amount;
+        }
+        if (typeof currency === 'string') {
+            currency = getCurrencyObject(currency);
+        }
+        if (typeof currency !== 'object') {
+            throw new TypeError('Invalid currency');
+        }
+        if (rounder === undefined) {
+            var decimals = decimalPlaces(amount);
+            if (decimals > currency.decimal_digits) {
+                throw new Error("The currency ".concat(currency.code, " supports only  ").concat(currency.decimal_digits, " decimal digits"));
+            }
+            rounder = Math.round;
+        }
+        else {
+            if (['round', 'floor', 'ceil'].indexOf(rounder) === -1 && typeof rounder !== 'function') {
+                throw new TypeError('Invalid parameter rounder');
+            }
+            if (typeof rounder === 'string') {
+                var mathRounders = { round: Math.round, floor: Math.floor, ceil: Math.ceil };
+                rounder = mathRounders[rounder];
+            }
+        }
+        var precisionMultiplier = Math.pow(10, currency.decimal_digits);
+        var resultAmount = amount * precisionMultiplier;
+        resultAmount = rounder(resultAmount);
+        return new TSMoney(resultAmount, currency);
+    };
+    /**
+     * Returns true if the two instances of TSMoney are equal, false otherwise.
+     *
+     * @param {TSMoney} other
+     * @returns {Boolean}
+     */
+    TSMoney.prototype.equals = function (other) {
+        assertType(other);
+        return this.amount === other.amount && this.currency === other.currency;
+    };
+    /**
+     * Adds the two objects together creating a new TSMoney instance that holds the result of the operation.
+     *
+     * @param {TSMoney} other
+     * @returns {TSMoney}
+     */
+    TSMoney.prototype.add = function (other) {
+        assertType(other);
+        assertSameCurrency(this, other);
+        return new TSMoney(this.amount + other.amount, this.currency);
+    };
+    /**
+     * Subtracts the two objects creating a new TSMoney instance that holds the result of the operation.
+     *
+     * @param {TSMoney} other
+     * @returns {TSMoney}
+     */
+    TSMoney.prototype.subtract = function (other) {
+        assertType(other);
+        assertSameCurrency(this, other);
+        return new TSMoney(this.amount - other.amount, this.currency);
+    };
+    /**
+     * Multiplies the object by the multiplier returning a new TSMoney instance that holds the result of the operation.
+     *
+     * @param {Number} multiplier
+     * @param {Function} [fn=Math.round]
+     * @returns {TSMoney}
+     */
+    TSMoney.prototype.multiply = function (multiplier, fn) {
+        if (typeof fn !== 'function') {
+            fn = Math.round;
+        }
+        assertOperand(multiplier);
+        return new TSMoney(fn(this.amount * multiplier), this.currency);
+    };
+    /**
+     * Divides the object by the multiplier returning a new TSMoney instance that holds the result of the operation.
+     *
+     * @param {Number} divisor
+     * @param {Function} [fn=Math.round]
+     * @returns {TSMoney}
+     */
+    TSMoney.prototype.divide = function (divisor, fn) {
+        if (typeof fn !== 'function') {
+            fn = Math.round;
+        }
+        assertOperand(divisor);
+        return new TSMoney(fn(this.amount / divisor), this.currency);
+    };
+    /**
+     * Allocates fund bases on the ratios provided returing an array of objects as a product of the allocation.
+     *
+     * @param {Array} other
+     * @returns {Array.TSMoney}
+     */
+    TSMoney.prototype.allocate = function (ratios) {
+        var _this = this;
+        var remainder = this.amount;
+        var results = [];
+        var total = 0;
+        ratios.forEach(function (ratio) {
+            total += ratio;
+        });
+        ratios.forEach(function (ratio) {
+            var share = Math.floor(_this.amount * ratio / total);
+            results.push(new TSMoney(share, _this.currency));
+            remainder -= share;
+        });
+        for (var i = 0; remainder > 0; i++) {
+            results[i] = new TSMoney(results[i].amount + 1, results[i].currency);
+            remainder--;
+        }
+        return results;
+    };
+    /**
+     * Compares two instances of TSMoney.
+     *
+     * @param {TSMoney} other
+     * @returns {Number}
+     */
+    TSMoney.prototype.compare = function (other) {
+        assertType(other);
+        assertSameCurrency(this, other);
+        if (this.amount === other.amount)
+            return 0;
+        if (this.amount > other.amount)
+            return 1;
+        return -1;
+    };
+    /**
+     * Checks whether the value represented by this object is greater than the other.
+     *
+     * @param {TSMoney} other
+     * @returns {boolean}
+     */
+    TSMoney.prototype.greaterThan = function (other) {
+        return 1 === this.compare(other);
+    };
+    /**
+     * Checks whether the value represented by this object is greater or equal to the other.
+     *
+     * @param {TSMoney} other
+     * @returns {boolean}
+     */
+    TSMoney.prototype.greaterThanOrEqual = function (other) {
+        return 0 <= this.compare(other);
+    };
+    /**
+     * Checks whether the value represented by this object is less than the other.
+     *
+     * @param {TSMoney} other
+     * @returns {boolean}
+     */
+    TSMoney.prototype.lessThan = function (other) {
+        return -1 === this.compare(other);
+    };
+    /**
+     * Checks whether the value represented by this object is less than or equal to the other.
+     *
+     * @param {TSMoney} other
+     * @returns {boolean}
+     */
+    TSMoney.prototype.lessThanOrEqual = function (other) {
+        return 0 >= this.compare(other);
+    };
+    /**
+     * Returns true if the amount is zero.
+     *
+     * @returns {boolean}
+     */
+    TSMoney.prototype.isZero = function () {
+        return this.amount === 0;
+    };
+    /**
+     * Returns true if the amount is positive.
+     *
+     * @returns {boolean}
+     */
+    TSMoney.prototype.isPositive = function () {
+        return this.amount > 0;
+    };
+    /**
+     * Returns true if the amount is negative.
+     *
+     * @returns {boolean}
+     */
+    TSMoney.prototype.isNegative = function () {
+        return this.amount < 0;
+    };
+    /**
+     * Returns the decimal value as a float.
+     *
+     * @returns {number}
+     */
+    TSMoney.prototype.toDecimal = function () {
+        return Number(this.toString());
+    };
+    /**
+     * Returns the decimal value as a string.
+     *
+     * @returns {string}
+     */
+    TSMoney.prototype.toString = function () {
+        var currency = getCurrencyObject(this.currency);
+        return (this.amount / Math.pow(10, currency.decimal_digits)).toFixed(currency.decimal_digits);
+    };
+    /**
+     * Returns a serialised version of the instance.
+     *
+     * @returns {{amount: number, currency: string}}
+     */
+    TSMoney.prototype.toJSON = function () {
+        return { amount: this.amount, currency: this.currency };
+    };
+    /**
+     * Returns the amount represented by this object.
+     *
+     * @returns {number}
+     */
+    TSMoney.prototype.getAmount = function () {
+        return this.amount;
+    };
+    /**
+     * Returns the currency code represented by this object.
+     */
+    TSMoney.prototype.getCurrency = function () {
+        return this.currency;
+    };
+    /**
+     * Returns the full currency object
+     */
+    TSMoney.prototype.getCurrencyInfo = function () {
+        return getCurrencyObject(this.currency);
+    };
+    return TSMoney;
+}());
+exports.TSMoney = TSMoney;
+Object.assign(TSMoney, TSCurrencies_1.TSCurrencies);

package/entities/currency-amount.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Convert a **decimal** amount (e.g. dollars) to minor units using `decimal_digits` from `TSCurrencies`.
+ */
+export declare function toSmallestUnit(amount: number, currencyCode: string): number;
+/**
+ * Convert minor units to a **decimal** display amount.
+ */
+export declare function fromSmallestUnit(amount: number, currencyCode: string): number;
+/**
+ * Format **minor-unit** amounts for display (parity with former core-service `formatCurrency`).
+ * Unknown codes fall back to `amount + code`.
+ */
+export declare function formatCurrency(amountMinor: number, currencyCode: string, locale?: string): string;

package/entities/currency-amount.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toSmallestUnit = toSmallestUnit;
+exports.fromSmallestUnit = fromSmallestUnit;
+exports.formatCurrency = formatCurrency;
+var TSCurrencies_js_1 = require("./TSCurrencies.js");
+/**
+ * Convert a **decimal** amount (e.g. dollars) to minor units using `decimal_digits` from `TSCurrencies`.
+ */
+function toSmallestUnit(amount, currencyCode) {
+    var c = (0, TSCurrencies_js_1.resolveCurrency)(currencyCode);
+    return Math.round(amount * Math.pow(10, c.decimal_digits));
+}
+/**
+ * Convert minor units to a **decimal** display amount.
+ */
+function fromSmallestUnit(amount, currencyCode) {
+    var c = (0, TSCurrencies_js_1.resolveCurrency)(currencyCode);
+    return amount / Math.pow(10, c.decimal_digits);
+}
+/**
+ * Format **minor-unit** amounts for display (parity with former core-service `formatCurrency`).
+ * Unknown codes fall back to `amount + code`.
+ */
+function formatCurrency(amountMinor, currencyCode, locale) {
+    if (locale === void 0) { locale = 'en-US'; }
+    var currency = (0, TSCurrencies_js_1.tryGetCurrency)(currencyCode);
+    if (!currency)
+        return "".concat(amountMinor, " ").concat(currencyCode);
+    var displayAmount = fromSmallestUnit(amountMinor, currencyCode);
+    if ((0, TSCurrencies_js_1.isCryptoCurrencyCode)(currencyCode)) {
+        return "".concat(displayAmount.toFixed(Math.min(currency.decimal_digits, 8)), " ").concat(currency.symbol);
+    }
+    try {
+        return new Intl.NumberFormat(locale, {
+            style: 'currency',
+            currency: currencyCode
+        }).format(displayAmount);
+    }
+    catch (_a) {
+        return "".concat(currency.symbol).concat(displayAmount.toFixed(currency.decimal_digits));
+    }
+}

package/finance/TSBonus.d.ts

@@ -0,0 +1,197 @@
+import { TSMoney } from '../entities/TSMoney';
+import { type CurrencyCode } from '../entities/TSCurrencies';
+import { type TSMoneyJSON } from './bonus-money';
+export type { TSMoneyJSON } from './bonus-money';
+export type { CurrencyCode };
+export { parseMoneyJSON, toMoneyJSON, assertCoherentMoneyFields, assertKnownCurrenciesOnTemplate, hasCurrencyCode } from './bonus-money';
+/**
+ * BonusEligibility - Client-Safe Eligibility Checker
+ *
+ * Single source of truth for bonus eligibility rules. No database dependencies – pure functions only.
+ * Use on both client and server so behaviour stays consistent and code is not duplicated.
+ *
+ * ## Server vs Client
+ *
+ * - **Client (e.g. app, scripts):** Call `BonusEligibility.check(template, context)` to show
+ *   “Eligible” / “Not eligible” and reasons, or `findBestForDeposit` / `getEligible` for UX.
+ *   Server still enforces eligibility on claim (and adds DB-only rules: already claimed, cooldown, stacking).
+ *
+ * - **Server (bonus-service):** Uses this module via `ValidatorChain`, which runs
+ *   `BonusEligibility.check()` for all client-safe rules, then server-only validators (max per user,
+ *   cooldown, already claimed, stacking, referral). See bonus-service/.../validators.ts.
+ *
+ * Usage:
+ * ```typescript
+ * import { BonusEligibility } from 'ts-client-lib/finance/TSBonus';
+ *
+ * // Check single template
+ * const result = BonusEligibility.check(template, context);
+ * if (result.eligible) {
+ *   notify(`You're eligible for ${template.name}!`);
+ * }
+ *
+ * // Check multiple templates
+ * const eligible = BonusEligibility.checkMany(templates, context);
+ * eligible.filter(r => r.eligible).forEach(r => {
+ *   notify(`Eligible: ${r.template.name}`);
+ * });
+ *
+ * // Find best bonus for deposit
+ * const best = BonusEligibility.findBestForDeposit(templates, 100, 'USD');
+ * ```
+ */
+export type BonusType = 'welcome' | 'first_deposit' | 'first_purchase' | 'first_action' | 'reload' | 'top_up' | 'referral' | 'referee' | 'commission' | 'activity' | 'milestone' | 'streak' | 'winback' | 'cashback' | 'consolation' | 'free_credit' | 'trial' | 'loyalty' | 'loyalty_points' | 'vip' | 'tier_upgrade' | 'birthday' | 'anniversary' | 'seasonal' | 'daily_login' | 'flash' | 'achievement' | 'task_completion' | 'challenge' | 'tournament' | 'leaderboard' | 'selection' | 'combo' | 'bundle' | 'promo_code' | 'special_event' | 'custom';
+export type BonusDomain = 'universal' | 'casino' | 'sports' | 'poker' | 'crypto' | 'ecommerce' | 'saas' | 'gaming' | 'fintech' | 'social';
+export type BonusValueType = 'fixed' | 'percentage' | 'tiered' | 'dynamic';
+export type BonusStatus = 'pending' | 'active' | 'in_progress' | 'requirements_met' | 'converted' | 'claimed' | 'expired' | 'cancelled' | 'forfeited' | 'locked';
+/**
+ * Minimal BonusTemplate interface for eligibility checking.
+ * Your full template may have more fields.
+ */
+export interface BonusTemplate {
+    id: string;
+    name: string;
+    code: string;
+    type: BonusType;
+    domain: BonusDomain;
+    description?: string;
+    valueType: BonusValueType;
+    value: number;
+    currency: CurrencyCode;
+    /** Optional strict transport: minor units + ISO code; must match legacy fields when set. */
+    valueMoney?: TSMoneyJSON;
+    supportedCurrencies?: CurrencyCode[];
+    maxValue?: number;
+    maxValueMoney?: TSMoneyJSON;
+    minDeposit?: number;
+    minDepositMoney?: TSMoneyJSON;
+    turnoverMultiplier: number;
+    activityContributions?: Record<string, number>;
+    validFrom: Date | string;
+    validUntil: Date | string;
+    claimDeadlineDays?: number;
+    usageDeadlineDays?: number;
+    maxUsesTotal?: number;
+    maxUsesPerUser?: number;
+    currentUsesTotal?: number;
+    eligibleTiers?: string[];
+    eligibleCountries?: string[];
+    excludedCountries?: string[];
+    minAccountAgeDays?: number;
+    requiresDeposit?: boolean;
+    requiresVerification?: boolean;
+    requiredKYCTier?: string;
+    stackable?: boolean;
+    excludedBonusTypes?: BonusType[];
+    minSelections?: number;
+    maxSelections?: number;
+    min?: number;
+    max?: number;
+    minTotal?: number;
+    maxTotal?: number;
+    minActions?: number;
+    comboMultiplier?: number;
+    eligibleCategories?: string[];
+    isActive: boolean;
+    priority?: number;
+    tags?: string[];
+}
+/**
+ * Context for eligibility checking.
+ * Populate with user's current state.
+ */
+export interface BonusEligibilityContext {
+    userId?: string;
+    tenantId?: string;
+    currency?: CurrencyCode;
+    userTier?: string;
+    country?: string;
+    kycTier?: string;
+    kycStatus?: string;
+    depositAmount?: number;
+    isFirstDeposit?: boolean;
+    isFirstPurchase?: boolean;
+    selectionCount?: number;
+    selections?: Array<{
+        id: string;
+        value?: number;
+        category?: string;
+    }>;
+    selectionsTotal?: number;
+    activityCategory?: string;
+    activityAmount?: number;
+    consecutiveDays?: number;
+    isVerified?: boolean;
+    accountAgeDays?: number;
+    currentDate?: Date;
+    metadata?: Record<string, unknown>;
+}
+export interface BonusEligibilityResult {
+    template: BonusTemplate;
+    eligible: boolean;
+    reasons: string[];
+    calculatedValue?: number;
+    /** Same calculation as `calculatedValue`, as **TSMoney** (minor units for fixed; decimal→minor for %). */
+    calculatedValueMoney?: TSMoney;
+    turnoverRequired?: number;
+    turnoverRequiredMoney?: TSMoney;
+}
+export interface BonusValidationRule {
+    name: string;
+    check: (template: BonusTemplate, context: BonusEligibilityContext) => boolean;
+    message: (template: BonusTemplate, context: BonusEligibilityContext) => string;
+}
+export declare class BonusEligibility {
+    /** Parse a date value that may be a Date, ISO string, or numeric timestamp string. */
+    private static parseDate;
+    private static readonly rules;
+    /**
+     * Check eligibility for a single bonus template.
+     */
+    static check(template: BonusTemplate, context?: BonusEligibilityContext): BonusEligibilityResult;
+    /**
+     * Check eligibility for multiple templates.
+     * Returns all results, sorted by priority (highest first).
+     */
+    static checkMany(templates: BonusTemplate[], context?: BonusEligibilityContext): BonusEligibilityResult[];
+    /**
+     * Get only eligible bonuses from a list.
+     */
+    static getEligible(templates: BonusTemplate[], context?: BonusEligibilityContext): BonusEligibilityResult[];
+    /**
+     * Find the best bonus for a deposit amount.
+     */
+    static findBestForDeposit(templates: BonusTemplate[], amount: number, currency: CurrencyCode, context?: Partial<BonusEligibilityContext>): BonusEligibilityResult | null;
+    /**
+     * Find eligible selection/combo bonuses based on selection count.
+     */
+    static findForSelections(templates: BonusTemplate[], selectionCount: number, context?: Partial<BonusEligibilityContext>): BonusEligibilityResult[];
+    /**
+     * Check if user qualifies for any bonus of a specific type.
+     */
+    static hasEligibleOfType(templates: BonusTemplate[], type: BonusType, context?: BonusEligibilityContext): BonusEligibilityResult | null;
+    /**
+     * Group eligible bonuses by type.
+     */
+    static groupByType(templates: BonusTemplate[], context?: BonusEligibilityContext): Map<BonusType, BonusEligibilityResult[]>;
+    static calculateValue(template: BonusTemplate, context: BonusEligibilityContext): number;
+    static calculateTurnover(template: BonusTemplate, context: BonusEligibilityContext): number;
+    /**
+     * Bonus value as **TSMoney**. `fixed` uses minor integer units; other value types use `fromDecimal`
+     * on the same numeric result as `calculateValue`.
+     */
+    static calculateValueMoney(template: BonusTemplate, context: BonusEligibilityContext): TSMoney;
+    static calculateTurnoverMoney(template: BonusTemplate, context: BonusEligibilityContext): TSMoney;
+    static getContributionRate(template: BonusTemplate, category: string): number;
+    static calculateTurnoverContribution(template: BonusTemplate, amount: number, category: string): number;
+    private static getTierMultiplier;
+    private static calculateDynamicValue;
+    static addRule(rule: BonusValidationRule): void;
+    static removeRule(name: string): void;
+    static getRuleNames(): string[];
+}
+export declare const checkBonusEligibility: typeof BonusEligibility.check;
+export declare const checkManyBonusEligibility: typeof BonusEligibility.checkMany;
+export declare const getEligibleBonuses: typeof BonusEligibility.getEligible;
+export declare const findBestDepositBonus: typeof BonusEligibility.findBestForDeposit;
+export declare const findSelectionBonuses: typeof BonusEligibility.findForSelections;