ts-client-lib 0.0.7

package/finance/TSKYC.js

@@ -0,0 +1,1066 @@
+"use strict";
+/**
+ * KYCEligibility - Client-Safe KYC Validation & Eligibility Checker
+ *
+ * A static class for checking KYC eligibility, limits, and requirements on client-side.
+ * No database dependencies - pure functions only.
+ *
+ * Usage:
+ * ```typescript
+ * import { KYCEligibility } from 'ts-client-lib/finance/TSKyc';
+ *
+ * // Check if user can make a transaction
+ * const result = KYCEligibility.checkTransaction(limits, {
+ *   currentTier: 'basic',
+ *   transactionType: 'withdrawal',
+ *   amount: 5000,
+ *   currency: 'EUR',
+ *   usedToday: 1000,
+ *   usedThisMonth: 10000,
+ * });
+ *
+ * if (!result.allowed) {
+ *   console.log(result.reason);
+ *   console.log(`Remaining: ${result.remaining}`);
+ * }
+ *
+ * // Get requirements for next tier
+ * const requirements = KYCEligibility.getTierRequirements('enhanced');
+ *
+ * // Check if user can access a feature
+ * const canWithdraw = KYCEligibility.canPerformAction('withdrawal', 'basic', 'standard');
+ * ```
+ */
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prevalidateKYCTransaction = exports.getRemainingLimits = exports.tierMeetsRequirement = exports.canPerformAction = exports.checkTierEligibility = exports.getTierRequirements = exports.checkKYCTransaction = exports.KYCEligibility = exports.KYC_VALIDATOR_ERROR_CODES = exports.KYC_VALIDATOR_ERRORS = void 0;
+exports.canonicalLimitKey = canonicalLimitKey;
+exports.KYC_VALIDATOR_ERRORS = {
+    UnknownKYCTier: 'MSKYCUnknownKYCTier',
+    FileTooLarge: 'MSKYCFileTooLarge',
+    FileTypeNotAllowed: 'MSKYCFileTypeNotAllowed',
+    FileExtensionNotAllowed: 'MSKYCFileExtensionNotAllowed',
+    // ─── Pre-validation rejection codes (client + server share these so i18n stays consistent) ───
+    /** KYC status is not approved or in-review (e.g. rejected/suspended/expired). */
+    KycStatusNotAllowed: 'MSKYCStatusNotAllowed',
+    /** Stored `expiresAt` is past. Distinct from `KycStatusNotAllowed` so UIs can prompt re-verification. */
+    KycExpired: 'MSKYCExpired',
+    /** Account flagged suspended at the operator/auth layer. */
+    AccountSuspended: 'MSKYCAccountSuspended',
+    /** Self-exclusion window is active. */
+    SelfExcluded: 'MSKYCSelfExcluded',
+    /** Wallet status is not 'active' (suspended/closed). */
+    WalletNotActive: 'MSKYCWalletNotActive',
+    /** Wallet balance < amount on an outflow operation. */
+    InsufficientBalance: 'MSKYCInsufficientBalance',
+    /** Operation type has no limit profile at this tier (e.g. transfer at tier 'none'). */
+    TierNotPermitted: 'MSKYCTierNotPermitted',
+    /** Amount below the per-transaction min. */
+    AmountBelowMin: 'MSKYCAmountBelowMin',
+    /** Amount above the per-transaction max (upgrade may help). */
+    AmountAboveMax: 'MSKYCAmountAboveMax',
+    /** Daily aggregate cap would be exceeded. */
+    DailyLimitExceeded: 'MSKYCDailyLimitExceeded',
+    /** Weekly aggregate cap would be exceeded. */
+    WeeklyLimitExceeded: 'MSKYCWeeklyLimitExceeded',
+    /** Monthly aggregate cap would be exceeded. */
+    MonthlyLimitExceeded: 'MSKYCMonthlyLimitExceeded',
+    /** Per-period transaction-count cap reached. */
+    TransactionCountExceeded: 'MSKYCTransactionCountExceeded',
+    /** Deposit would push wallet balance above the tier's max-balance ceiling. */
+    MaxBalanceExceeded: 'MSKYCMaxBalanceExceeded'
+};
+exports.KYC_VALIDATOR_ERROR_CODES = [
+    exports.KYC_VALIDATOR_ERRORS.UnknownKYCTier,
+    exports.KYC_VALIDATOR_ERRORS.FileTooLarge,
+    exports.KYC_VALIDATOR_ERRORS.FileTypeNotAllowed,
+    exports.KYC_VALIDATOR_ERRORS.FileExtensionNotAllowed,
+    exports.KYC_VALIDATOR_ERRORS.KycStatusNotAllowed,
+    exports.KYC_VALIDATOR_ERRORS.KycExpired,
+    exports.KYC_VALIDATOR_ERRORS.AccountSuspended,
+    exports.KYC_VALIDATOR_ERRORS.SelfExcluded,
+    exports.KYC_VALIDATOR_ERRORS.WalletNotActive,
+    exports.KYC_VALIDATOR_ERRORS.InsufficientBalance,
+    exports.KYC_VALIDATOR_ERRORS.TierNotPermitted,
+    exports.KYC_VALIDATOR_ERRORS.AmountBelowMin,
+    exports.KYC_VALIDATOR_ERRORS.AmountAboveMax,
+    exports.KYC_VALIDATOR_ERRORS.DailyLimitExceeded,
+    exports.KYC_VALIDATOR_ERRORS.WeeklyLimitExceeded,
+    exports.KYC_VALIDATOR_ERRORS.MonthlyLimitExceeded,
+    exports.KYC_VALIDATOR_ERRORS.TransactionCountExceeded,
+    exports.KYC_VALIDATOR_ERRORS.MaxBalanceExceeded
+];
+/**
+ * Map operation type → tier-limit profile key. `KYCTierLimits` stores three profiles
+ * (deposit / withdrawal / transfer); `order` reuses `deposit`. Anything else is invalid
+ * at the type level so this is exhaustive.
+ *
+ * **PXE-7** — `tierLimits[X]` MUST go through this helper. Raw `tierLimits[type]` returns
+ * undefined for `'order'` and silently bypasses tier-limit enforcement.
+ * See graphify/pre-execution/cross-product-admission-canonical.md.
+ */
+function canonicalLimitKey(t) {
+    return t === 'order' ? 'deposit' : t;
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// CONSTANTS
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Tier hierarchy (lower index = lower tier)
+ */
+var TIER_LEVELS = {
+    'none': 0,
+    'basic': 1,
+    'standard': 2,
+    'enhanced': 3,
+    'full': 4,
+    'professional': 5
+};
+/**
+ * Tier display names
+ */
+var TIER_NAMES = {
+    'none': 'Unverified',
+    'basic': 'Basic',
+    'standard': 'Standard',
+    'enhanced': 'Enhanced',
+    'full': 'Full',
+    'professional': 'Professional'
+};
+/**
+ * Tier descriptions
+ */
+var TIER_DESCRIPTIONS = {
+    'none': 'No verification completed',
+    'basic': 'Email and phone verified',
+    'standard': 'Government-issued ID verified',
+    'enhanced': 'ID and address verified',
+    'full': 'Full KYC with source of funds',
+    'professional': 'Corporate/institutional verification'
+};
+/**
+ * Default tier requirements
+ */
+var DEFAULT_TIER_REQUIREMENTS = {
+    none: {
+        tier: 'none',
+        displayName: TIER_NAMES.none,
+        description: TIER_DESCRIPTIONS.none,
+        documents: [],
+        checks: [],
+        information: []
+    },
+    basic: {
+        tier: 'basic',
+        displayName: TIER_NAMES.basic,
+        description: TIER_DESCRIPTIONS.basic,
+        documents: [],
+        checks: [
+            { id: 'aml_basic', name: 'AML Screening', type: 'aml', required: true }
+        ],
+        information: [
+            { id: 'firstName', fieldPath: 'personalInfo.firstName', displayName: 'First Name', required: true },
+            { id: 'lastName', fieldPath: 'personalInfo.lastName', displayName: 'Last Name', required: true },
+            { id: 'dob', fieldPath: 'personalInfo.dateOfBirth', displayName: 'Date of Birth', required: true },
+            { id: 'email', fieldPath: 'personalInfo.email', displayName: 'Email Address', required: true }
+        ]
+    },
+    standard: {
+        tier: 'standard',
+        displayName: TIER_NAMES.standard,
+        description: TIER_DESCRIPTIONS.standard,
+        prerequisiteTier: 'basic',
+        documents: [
+            {
+                id: 'identity',
+                name: 'Government-issued ID',
+                category: 'identity',
+                acceptedTypes: ['passport', 'national_id', 'drivers_license'],
+                required: true,
+                mustNotBeExpired: true
+            },
+            {
+                id: 'selfie',
+                name: 'Selfie Photo',
+                category: 'biometric',
+                acceptedTypes: ['selfie'],
+                required: true
+            }
+        ],
+        checks: [
+            { id: 'aml', name: 'AML Screening', type: 'aml', required: true },
+            { id: 'pep', name: 'PEP Screening', type: 'pep', required: true },
+            { id: 'liveness', name: 'Liveness Check', type: 'liveness', required: true },
+            { id: 'face_match', name: 'Face Match', type: 'face_match', required: true }
+        ],
+        information: [
+            { id: 'nationality', fieldPath: 'personalInfo.nationality', displayName: 'Nationality', required: true },
+            { id: 'residence', fieldPath: 'personalInfo.countryOfResidence', displayName: 'Country of Residence', required: true }
+        ]
+    },
+    enhanced: {
+        tier: 'enhanced',
+        displayName: TIER_NAMES.enhanced,
+        description: TIER_DESCRIPTIONS.enhanced,
+        prerequisiteTier: 'standard',
+        documents: [
+            {
+                id: 'address',
+                name: 'Proof of Address',
+                category: 'address',
+                acceptedTypes: ['utility_bill', 'bank_statement', 'tax_document', 'government_letter'],
+                required: true,
+                maxAgeDays: 90
+            }
+        ],
+        checks: [
+            { id: 'sanctions', name: 'Sanctions Screening', type: 'sanctions', required: true },
+            { id: 'address_verify', name: 'Address Verification', type: 'address_verification', required: true }
+        ],
+        information: [
+            { id: 'address', fieldPath: 'addresses', displayName: 'Residential Address', required: true }
+        ]
+    },
+    full: {
+        tier: 'full',
+        displayName: TIER_NAMES.full,
+        description: TIER_DESCRIPTIONS.full,
+        prerequisiteTier: 'enhanced',
+        documents: [
+            {
+                id: 'financial',
+                name: 'Source of Funds Documentation',
+                category: 'financial',
+                acceptedTypes: ['proof_of_income', 'tax_return', 'bank_statement', 'employment_letter'],
+                required: true
+            }
+        ],
+        checks: [],
+        information: [
+            { id: 'occupation', fieldPath: 'personalInfo.occupation', displayName: 'Occupation', required: true },
+            { id: 'sof', fieldPath: 'sourceOfFunds', displayName: 'Source of Funds', required: true }
+        ]
+    },
+    professional: {
+        tier: 'professional',
+        displayName: TIER_NAMES.professional,
+        description: TIER_DESCRIPTIONS.professional,
+        prerequisiteTier: 'enhanced',
+        documents: [
+            {
+                id: 'company_reg',
+                name: 'Company Registration Documents',
+                category: 'corporate',
+                acceptedTypes: ['company_registration', 'articles_of_incorporation'],
+                required: true
+            },
+            {
+                id: 'ubo',
+                name: 'Beneficial Owner Documentation',
+                category: 'corporate',
+                acceptedTypes: ['shareholder_register'],
+                required: true
+            }
+        ],
+        checks: [],
+        information: [
+            { id: 'company_name', fieldPath: 'businessInfo.companyName', displayName: 'Company Name', required: true },
+            { id: 'reg_number', fieldPath: 'businessInfo.registrationNumber', displayName: 'Registration Number', required: true },
+            { id: 'ubos', fieldPath: 'businessInfo.beneficialOwners', displayName: 'Beneficial Owners', required: true }
+        ]
+    }
+};
+/**
+ * Default tier limits (EUR)
+ */
+var DEFAULT_TIER_LIMITS = {
+    none: {
+        currency: 'EUR',
+        deposit: { minAmount: 10, maxAmount: 0, dailyLimit: 0, monthlyLimit: 0 },
+        withdrawal: { minAmount: 10, maxAmount: 0, dailyLimit: 0, monthlyLimit: 0 }
+    },
+    basic: {
+        currency: 'EUR',
+        deposit: { minAmount: 10, maxAmount: 1000, dailyLimit: 2000, monthlyLimit: 5000 },
+        withdrawal: { minAmount: 10, maxAmount: 500, dailyLimit: 1000, monthlyLimit: 2500 },
+        transfer: { minAmount: 10, maxAmount: 500, dailyLimit: 1000, monthlyLimit: 2500 },
+        maxBalance: 5000
+    },
+    standard: {
+        currency: 'EUR',
+        deposit: { minAmount: 10, maxAmount: 5000, dailyLimit: 10000, monthlyLimit: 25000 },
+        withdrawal: { minAmount: 10, maxAmount: 2500, dailyLimit: 5000, monthlyLimit: 15000 },
+        transfer: { minAmount: 10, maxAmount: 2500, dailyLimit: 5000, monthlyLimit: 15000 },
+        maxBalance: 50000
+    },
+    enhanced: {
+        currency: 'EUR',
+        deposit: { minAmount: 10, maxAmount: 25000, dailyLimit: 50000, monthlyLimit: 150000 },
+        withdrawal: { minAmount: 10, maxAmount: 15000, dailyLimit: 30000, monthlyLimit: 100000 },
+        transfer: { minAmount: 10, maxAmount: 15000, dailyLimit: 30000, monthlyLimit: 100000 },
+        maxBalance: 250000
+    },
+    full: {
+        currency: 'EUR',
+        deposit: { minAmount: 10, maxAmount: 100000, dailyLimit: 250000, monthlyLimit: 1000000 },
+        withdrawal: { minAmount: 10, maxAmount: 50000, dailyLimit: 150000, monthlyLimit: 500000 },
+        transfer: { minAmount: 10, maxAmount: 50000, dailyLimit: 150000, monthlyLimit: 500000 }
+    },
+    professional: {
+        currency: 'EUR',
+        deposit: { minAmount: 100, maxAmount: 1000000, dailyLimit: 5000000, monthlyLimit: 50000000 },
+        withdrawal: { minAmount: 100, maxAmount: 500000, dailyLimit: 2500000, monthlyLimit: 25000000 },
+        transfer: { minAmount: 100, maxAmount: 500000, dailyLimit: 2500000, monthlyLimit: 25000000 }
+    }
+};
+/**
+ * Minimum tier required for actions
+ */
+var DEFAULT_ACTION_TIERS = {
+    'deposit': 'basic',
+    'withdrawal': 'standard',
+    'transfer': 'standard',
+    'trade': 'standard',
+    'bet': 'basic',
+    'purchase': 'basic',
+    'claim_bonus': 'basic',
+    'crypto_withdrawal': 'enhanced',
+    'high_value_transaction': 'full',
+    'corporate_account': 'professional'
+};
+// ═══════════════════════════════════════════════════════════════════════════
+// STATIC CLASS
+// ═══════════════════════════════════════════════════════════════════════════
+var KYCEligibility = /** @class */ (function () {
+    function KYCEligibility() {
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // TIER UTILITIES
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Get numeric level for a tier (for comparisons)
+     */
+    KYCEligibility.getTierLevel = function (tier) {
+        var _a;
+        return (_a = TIER_LEVELS[tier]) !== null && _a !== void 0 ? _a : 0;
+    };
+    /**
+     * Compare two tiers. Returns negative if a < b, 0 if equal, positive if a > b
+     */
+    KYCEligibility.compareTiers = function (a, b) {
+        return this.getTierLevel(a) - this.getTierLevel(b);
+    };
+    /**
+     * Check if tier meets minimum requirement
+     */
+    KYCEligibility.tierMeetsRequirement = function (currentTier, requiredTier) {
+        return this.getTierLevel(currentTier) >= this.getTierLevel(requiredTier);
+    };
+    /**
+     * Get display name for a tier
+     */
+    KYCEligibility.getTierDisplayName = function (tier) {
+        var _a;
+        return (_a = TIER_NAMES[tier]) !== null && _a !== void 0 ? _a : tier;
+    };
+    /**
+     * Get description for a tier
+     */
+    KYCEligibility.getTierDescription = function (tier) {
+        var _a;
+        return (_a = TIER_DESCRIPTIONS[tier]) !== null && _a !== void 0 ? _a : '';
+    };
+    /**
+     * Get next tier in the hierarchy
+     */
+    KYCEligibility.getNextTier = function (currentTier) {
+        var tiers = ['none', 'basic', 'standard', 'enhanced', 'full', 'professional'];
+        var currentIndex = tiers.indexOf(currentTier);
+        if (currentIndex === -1 || currentIndex >= tiers.length - 1)
+            return null;
+        return tiers[currentIndex + 1];
+    };
+    /**
+     * Get all tiers in order
+     */
+    KYCEligibility.getAllTiers = function () {
+        return ['none', 'basic', 'standard', 'enhanced', 'full', 'professional'];
+    };
+    // ─────────────────────────────────────────────────────────────────────────
+    // TIER REQUIREMENTS
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Get requirements for a tier
+     */
+    KYCEligibility.getTierRequirements = function (tier) {
+        return DEFAULT_TIER_REQUIREMENTS[tier];
+    };
+    /**
+     * Get all requirements needed to reach a tier from current tier
+     */
+    KYCEligibility.getRequirementsToReachTier = function (currentTier, targetTier) {
+        var requirements = [];
+        var tiers = this.getAllTiers();
+        var currentIndex = tiers.indexOf(currentTier);
+        var targetIndex = tiers.indexOf(targetTier);
+        if (targetIndex <= currentIndex)
+            return [];
+        for (var i = currentIndex + 1; i <= targetIndex; i++) {
+            requirements.push(this.getTierRequirements(tiers[i]));
+        }
+        return requirements;
+    };
+    /**
+     * Check eligibility for a target tier
+     */
+    KYCEligibility.checkTierEligibility = function (targetTier, context) {
+        var requirements = this.getTierRequirements(targetTier);
+        var missingRequirements = [];
+        var completedRequirements = [];
+        this.collectTierPrerequisite(requirements, context, missingRequirements, completedRequirements);
+        this.collectTierDocuments(requirements, context, missingRequirements, completedRequirements);
+        this.collectTierVerificationChecks(requirements, context, missingRequirements, completedRequirements);
+        this.collectTierMinimumAge(requirements, context, missingRequirements, completedRequirements);
+        var total = missingRequirements.length + completedRequirements.length;
+        var progress = total > 0 ? Math.round((completedRequirements.length / total) * 100) : 0;
+        return {
+            currentTier: context.currentTier,
+            targetTier: targetTier,
+            eligible: missingRequirements.length === 0,
+            missingRequirements: missingRequirements,
+            completedRequirements: completedRequirements,
+            progress: progress
+        };
+    };
+    KYCEligibility.collectTierPrerequisite = function (requirements, context, missingRequirements, completedRequirements) {
+        if (!requirements.prerequisiteTier)
+            return;
+        if (!this.tierMeetsRequirement(context.currentTier, requirements.prerequisiteTier)) {
+            missingRequirements.push("Requires ".concat(this.getTierDisplayName(requirements.prerequisiteTier), " tier first"));
+            return;
+        }
+        completedRequirements.push("".concat(this.getTierDisplayName(requirements.prerequisiteTier), " tier"));
+    };
+    KYCEligibility.collectTierDocuments = function (requirements, context, missingRequirements, completedRequirements) {
+        for (var _i = 0, _a = requirements.documents; _i < _a.length; _i++) {
+            var doc = _a[_i];
+            if (!doc.required)
+                continue;
+            var hasDoc = (doc.category === 'identity' && Boolean(context.hasIdentityDoc)) ||
+                (doc.category === 'address' && Boolean(context.hasAddressDoc)) ||
+                (doc.category === 'financial' && Boolean(context.hasFinancialDoc));
+            if (hasDoc)
+                completedRequirements.push(doc.name);
+            else
+                missingRequirements.push(doc.name);
+        }
+    };
+    KYCEligibility.collectTierVerificationChecks = function (requirements, context, missingRequirements, completedRequirements) {
+        for (var _i = 0, _a = requirements.checks; _i < _a.length; _i++) {
+            var check = _a[_i];
+            if (!check.required)
+                continue;
+            var passed = (check.type === 'aml' && Boolean(context.amlCheckPassed)) ||
+                (check.type === 'pep' && Boolean(context.pepCheckPassed)) ||
+                (check.type === 'sanctions' && Boolean(context.sanctionsCheckPassed)) ||
+                (check.type === 'liveness' && Boolean(context.livenessCheckPassed));
+            if (passed)
+                completedRequirements.push(check.name);
+            else
+                missingRequirements.push(check.name);
+        }
+    };
+    KYCEligibility.collectTierMinimumAge = function (requirements, context, missingRequirements, completedRequirements) {
+        if (!requirements.minimumAge || context.userAge == null)
+            return;
+        if (context.userAge < requirements.minimumAge) {
+            missingRequirements.push("Minimum age ".concat(requirements.minimumAge));
+            return;
+        }
+        completedRequirements.push('Age requirement');
+    };
+    // ─────────────────────────────────────────────────────────────────────────
+    // PRE-VALIDATION — bulletproof client + server admission control
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Run the full admission gate against a single input. Pure — no I/O. Same function
+     * intended to run on the client (before submit) and on the server (in pre-transaction
+     * middleware or the wallet.order handler) for defence-in-depth.
+     *
+     * Order of checks (first failure wins; same order on client and server):
+     *
+     *   1. **Account preconditions** — suspended? self-excluded?
+     *   2. **Wallet preconditions** — status === 'active'?
+     *   3. **KYC snapshot** — status approved/in_review? expiresAt > now?
+     *   4. **Balance** (outflows only) — wallet.balance >= amount?
+     *   5. **Tier limits** — delegates to `checkTransaction` (min/max per-tx, daily/monthly
+     *      aggregate, transaction count, max-balance ceiling). Bounded `code` flows through.
+     *
+     * The client app supplies `wallet`, `account`, usage, and KYC snapshot from API
+     * responses it already has; the server supplies the same fields from its source of
+     * truth. Both sides produce identical results.
+     *
+     * Why this exists alongside `checkTransaction`: that method only handles tier-limit
+     * math and assumes a valid KYC snapshot. `prevalidate` is the high-level umbrella —
+     * checks account / wallet / status / expiry first, then delegates limits. UI code
+     * should always call `prevalidate`, never `checkTransaction` directly.
+     */
+    KYCEligibility.prevalidate = function (input) {
+        var _a, _b;
+        // 1. Account
+        var accountReject = this.preRejectAccount(input);
+        if (accountReject)
+            return accountReject;
+        // 2. Wallet status
+        var walletStatusReject = this.preRejectWalletStatus(input);
+        if (walletStatusReject)
+            return walletStatusReject;
+        // 3. KYC snapshot
+        var kycReject = this.preRejectKyc(input);
+        if (kycReject)
+            return kycReject;
+        // 4. Balance (outflow only)
+        var balanceReject = this.preRejectInsufficientBalance(input);
+        if (balanceReject)
+            return balanceReject;
+        // 5. Tier limits — delegate to checkTransaction. The bounded `code` set in each
+        //    txReject* method flows back here unchanged; we just promote remaining fields
+        //    into the KYCPrevalidationResult shape for UI consumption.
+        var limitsLadder = (_a = input.jurisdictionLimits) !== null && _a !== void 0 ? _a : DEFAULT_TIER_LIMITS;
+        var txResult = this.checkTransaction(limitsLadder, {
+            currentTier: input.currentTier,
+            kycStatus: input.kycStatus,
+            transactionType: input.operation,
+            amount: input.amount,
+            currency: input.currency,
+            usedToday: input.usedToday,
+            usedThisWeek: input.usedThisWeek,
+            usedThisMonth: input.usedThisMonth,
+            transactionsToday: input.transactionsToday,
+            transactionsThisMonth: input.transactionsThisMonth,
+            currentBalance: (_b = input.wallet) === null || _b === void 0 ? void 0 : _b.balance,
+            jurisdictionLimits: input.jurisdictionLimits
+        });
+        return __assign(__assign(__assign(__assign(__assign(__assign(__assign(__assign({ allowed: txResult.allowed }, (txResult.code ? { code: txResult.code } : {})), (txResult.reason ? { reason: txResult.reason } : {})), (txResult.details ? { details: txResult.details } : {})), (txResult.maxAllowed !== undefined ? { maxAllowed: txResult.maxAllowed } : {})), (txResult.dailyRemaining !== undefined ? { dailyRemaining: txResult.dailyRemaining } : {})), (txResult.monthlyRemaining !== undefined ? { monthlyRemaining: txResult.monthlyRemaining } : {})), (txResult.requiredTier ? { upgradeToTier: txResult.requiredTier } : {})), (txResult.upgradeMessage ? { upgradeMessage: txResult.upgradeMessage } : {}));
+    };
+    KYCEligibility.preRejectAccount = function (input) {
+        var _a, _b;
+        if ((_a = input.account) === null || _a === void 0 ? void 0 : _a.suspended) {
+            return {
+                allowed: false,
+                code: exports.KYC_VALIDATOR_ERRORS.AccountSuspended,
+                reason: 'Account is suspended'
+            };
+        }
+        if ((_b = input.account) === null || _b === void 0 ? void 0 : _b.selfExcludedUntil) {
+            var until = new Date(input.account.selfExcludedUntil);
+            var now = Date.now();
+            if (until.getTime() > now) {
+                return {
+                    allowed: false,
+                    code: exports.KYC_VALIDATOR_ERRORS.SelfExcluded,
+                    reason: "Self-exclusion active until ".concat(until.toISOString()),
+                    details: { until: until.toISOString() }
+                };
+            }
+        }
+        return null;
+    };
+    KYCEligibility.preRejectWalletStatus = function (input) {
+        var _a;
+        if (((_a = input.wallet) === null || _a === void 0 ? void 0 : _a.status) && input.wallet.status !== 'active') {
+            return {
+                allowed: false,
+                code: exports.KYC_VALIDATOR_ERRORS.WalletNotActive,
+                reason: "Wallet is ".concat(input.wallet.status),
+                details: { walletStatus: input.wallet.status }
+            };
+        }
+        return null;
+    };
+    KYCEligibility.preRejectKyc = function (input) {
+        // 'none' tier is the unverified state — the limit profile (which may be very tight)
+        // gates the check inside checkTransaction. Don't reject here purely on status.
+        if (input.currentTier !== 'none'
+            && input.kycStatus !== 'approved'
+            && input.kycStatus !== 'in_review') {
+            return {
+                allowed: false,
+                code: exports.KYC_VALIDATOR_ERRORS.KycStatusNotAllowed,
+                reason: "KYC status '".concat(input.kycStatus, "' does not allow transactions"),
+                details: { kycStatus: input.kycStatus }
+            };
+        }
+        if (input.expiresAt) {
+            var exp = new Date(input.expiresAt);
+            if (exp.getTime() < Date.now()) {
+                return {
+                    allowed: false,
+                    code: exports.KYC_VALIDATOR_ERRORS.KycExpired,
+                    reason: 'KYC verification has expired',
+                    details: { expiresAt: exp.toISOString() }
+                };
+            }
+        }
+        return null;
+    };
+    KYCEligibility.preRejectInsufficientBalance = function (input) {
+        var _a;
+        // Inflow operations don't consume wallet balance.
+        if (input.operation === 'deposit')
+            return null;
+        var balance = (_a = input.wallet) === null || _a === void 0 ? void 0 : _a.balance;
+        if (balance == null)
+            return null; // caller opted out of balance check
+        if (input.amount <= balance)
+            return null;
+        return {
+            allowed: false,
+            code: exports.KYC_VALIDATOR_ERRORS.InsufficientBalance,
+            reason: "Insufficient balance: have ".concat(balance, " ").concat(input.currency, ", need ").concat(input.amount),
+            details: { balance: balance, amount: input.amount, currency: input.currency },
+            maxAllowed: Math.max(0, balance)
+        };
+    };
+    // ─────────────────────────────────────────────────────────────────────────
+    // TRANSACTION LIMITS
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Get limits for a tier
+     */
+    KYCEligibility.getTierLimits = function (tier, customLimits) {
+        var limits = customLimits !== null && customLimits !== void 0 ? customLimits : DEFAULT_TIER_LIMITS;
+        return limits[tier];
+    };
+    /**
+     * Check if a transaction is allowed
+     */
+    KYCEligibility.checkTransaction = function (limits, context) {
+        var _a, _b;
+        var tierLimits = this.resolveTransactionTierLimits(limits, context.currentTier);
+        if (!tierLimits) {
+            return {
+                allowed: false,
+                reason: 'Unknown KYC tier',
+                code: exports.KYC_VALIDATOR_ERRORS.UnknownKYCTier,
+                details: { tier: context.currentTier }
+            };
+        }
+        var kycStatusReject = this.txRejectInvalidKycStatus(context);
+        if (kycStatusReject)
+            return kycStatusReject;
+        var opResolved = this.resolveTransactionOpLimits(tierLimits, context);
+        if (!('opLimits' in opResolved))
+            return opResolved;
+        var opLimits = opResolved.opLimits;
+        var minReject = this.txRejectBelowMinAmount(context, opLimits);
+        if (minReject)
+            return minReject;
+        var maxReject = this.txRejectAboveMaxPerTransaction(context, opLimits);
+        if (maxReject)
+            return maxReject;
+        var usedToday = (_a = context.usedToday) !== null && _a !== void 0 ? _a : 0;
+        var dailyRemaining = opLimits.dailyLimit - usedToday;
+        var dailyReject = this.txRejectExceedsDailyBudget(context, opLimits, dailyRemaining);
+        if (dailyReject)
+            return dailyReject;
+        var usedThisMonth = (_b = context.usedThisMonth) !== null && _b !== void 0 ? _b : 0;
+        var monthlyRemaining = opLimits.monthlyLimit - usedThisMonth;
+        var monthlyReject = this.txRejectExceedsMonthlyBudget(context, opLimits, monthlyRemaining);
+        if (monthlyReject)
+            return monthlyReject;
+        var weeklyReject = this.txRejectExceedsWeeklyBudget(context, opLimits);
+        if (weeklyReject)
+            return weeklyReject;
+        var txCountReject = this.txRejectDailyTransactionCount(context, opLimits);
+        if (txCountReject)
+            return txCountReject;
+        var balanceReject = this.txRejectDepositOverMaxBalance(tierLimits, context);
+        if (balanceReject)
+            return balanceReject;
+        return this.txBuildAllowedResult(context, opLimits, dailyRemaining, monthlyRemaining);
+    };
+    KYCEligibility.resolveTransactionTierLimits = function (limits, currentTier) {
+        var _a;
+        if ('deposit' in limits)
+            return limits;
+        return (_a = limits[currentTier]) !== null && _a !== void 0 ? _a : null;
+    };
+    KYCEligibility.txRejectInvalidKycStatus = function (context) {
+        if (context.kycStatus && ['approved', 'in_review'].indexOf(context.kycStatus) === -1) {
+            return {
+                allowed: false,
+                reason: "KYC status '".concat(context.kycStatus, "' does not allow transactions"),
+                code: exports.KYC_VALIDATOR_ERRORS.KycStatusNotAllowed,
+                details: { kycStatus: context.kycStatus }
+            };
+        }
+        return null;
+    };
+    KYCEligibility.resolveTransactionOpLimits = function (tierLimits, context) {
+        var _a;
+        var opType = canonicalLimitKey(context.transactionType);
+        var opLimits = tierLimits[opType];
+        if (!opLimits) {
+            return {
+                allowed: false,
+                reason: "Transaction type '".concat(context.transactionType, "' not allowed at this tier"),
+                code: exports.KYC_VALIDATOR_ERRORS.TierNotPermitted,
+                requiredTier: (_a = this.getNextTier(context.currentTier)) !== null && _a !== void 0 ? _a : undefined
+            };
+        }
+        return { opLimits: opLimits };
+    };
+    KYCEligibility.txRejectBelowMinAmount = function (context, opLimits) {
+        if (opLimits.minAmount && context.amount < opLimits.minAmount) {
+            return {
+                allowed: false,
+                reason: "Minimum amount is ".concat(opLimits.minAmount, " ").concat(context.currency),
+                code: exports.KYC_VALIDATOR_ERRORS.AmountBelowMin,
+                details: { minAmount: opLimits.minAmount, amount: context.amount, currency: context.currency },
+                maxAllowed: opLimits.minAmount
+            };
+        }
+        return null;
+    };
+    KYCEligibility.txRejectAboveMaxPerTransaction = function (context, opLimits) {
+        if (context.amount <= opLimits.maxAmount)
+            return null;
+        var requiredTier = this.findTierForAmount(context.amount, context.transactionType, context.jurisdictionLimits);
+        return {
+            allowed: false,
+            reason: "Maximum amount per transaction is ".concat(opLimits.maxAmount, " ").concat(context.currency),
+            code: exports.KYC_VALIDATOR_ERRORS.AmountAboveMax,
+            details: { maxAmount: opLimits.maxAmount, amount: context.amount, currency: context.currency },
+            maxAllowed: opLimits.maxAmount,
+            requiredTier: requiredTier !== null && requiredTier !== void 0 ? requiredTier : undefined,
+            upgradeMessage: requiredTier
+                ? "Upgrade to ".concat(this.getTierDisplayName(requiredTier), " for higher limits")
+                : undefined
+        };
+    };
+    KYCEligibility.txRejectExceedsDailyBudget = function (context, opLimits, dailyRemaining) {
+        if (context.amount <= dailyRemaining)
+            return null;
+        return {
+            allowed: false,
+            reason: "Daily limit exceeded. Remaining today: ".concat(Math.max(0, dailyRemaining), " ").concat(context.currency),
+            code: exports.KYC_VALIDATOR_ERRORS.DailyLimitExceeded,
+            details: { dailyLimit: opLimits.dailyLimit, dailyRemaining: Math.max(0, dailyRemaining), currency: context.currency },
+            remaining: Math.max(0, dailyRemaining),
+            dailyRemaining: Math.max(0, dailyRemaining),
+            maxAllowed: Math.min(opLimits.maxAmount, dailyRemaining)
+        };
+    };
+    KYCEligibility.txRejectExceedsMonthlyBudget = function (context, opLimits, monthlyRemaining) {
+        if (context.amount <= monthlyRemaining)
+            return null;
+        return {
+            allowed: false,
+            reason: "Monthly limit exceeded. Remaining this month: ".concat(Math.max(0, monthlyRemaining), " ").concat(context.currency),
+            code: exports.KYC_VALIDATOR_ERRORS.MonthlyLimitExceeded,
+            details: { monthlyLimit: opLimits.monthlyLimit, monthlyRemaining: Math.max(0, monthlyRemaining), currency: context.currency },
+            remaining: Math.max(0, monthlyRemaining),
+            monthlyRemaining: Math.max(0, monthlyRemaining),
+            maxAllowed: Math.min(opLimits.maxAmount, monthlyRemaining)
+        };
+    };
+    KYCEligibility.txRejectExceedsWeeklyBudget = function (context, opLimits) {
+        var _a;
+        if (!opLimits.weeklyLimit)
+            return null;
+        var usedThisWeek = (_a = context.usedThisWeek) !== null && _a !== void 0 ? _a : 0;
+        var weeklyRemaining = opLimits.weeklyLimit - usedThisWeek;
+        if (context.amount <= weeklyRemaining)
+            return null;
+        return {
+            allowed: false,
+            reason: "Weekly limit exceeded. Remaining this week: ".concat(Math.max(0, weeklyRemaining), " ").concat(context.currency),
+            code: exports.KYC_VALIDATOR_ERRORS.WeeklyLimitExceeded,
+            details: { weeklyLimit: opLimits.weeklyLimit, weeklyRemaining: Math.max(0, weeklyRemaining), currency: context.currency },
+            remaining: Math.max(0, weeklyRemaining),
+            maxAllowed: Math.min(opLimits.maxAmount, weeklyRemaining)
+        };
+    };
+    KYCEligibility.txRejectDailyTransactionCount = function (context, opLimits) {
+        var _a;
+        if (!opLimits.maxDailyTransactions)
+            return null;
+        var txToday = (_a = context.transactionsToday) !== null && _a !== void 0 ? _a : 0;
+        if (txToday < opLimits.maxDailyTransactions)
+            return null;
+        return {
+            allowed: false,
+            reason: "Daily transaction limit reached (".concat(opLimits.maxDailyTransactions, " transactions)"),
+            code: exports.KYC_VALIDATOR_ERRORS.TransactionCountExceeded,
+            details: { maxDailyTransactions: opLimits.maxDailyTransactions, transactionsToday: txToday }
+        };
+    };
+    KYCEligibility.txRejectDepositOverMaxBalance = function (tierLimits, context) {
+        var _a;
+        if (context.transactionType !== 'deposit' || !tierLimits.maxBalance)
+            return null;
+        var currentBalance = (_a = context.currentBalance) !== null && _a !== void 0 ? _a : 0;
+        var newBalance = currentBalance + context.amount;
+        if (newBalance <= tierLimits.maxBalance)
+            return null;
+        var maxDeposit = tierLimits.maxBalance - currentBalance;
+        return {
+            allowed: false,
+            reason: "Would exceed maximum balance of ".concat(tierLimits.maxBalance, " ").concat(context.currency),
+            code: exports.KYC_VALIDATOR_ERRORS.MaxBalanceExceeded,
+            details: { maxBalance: tierLimits.maxBalance, currentBalance: currentBalance, currency: context.currency },
+            maxAllowed: Math.max(0, maxDeposit)
+        };
+    };
+    KYCEligibility.txBuildAllowedResult = function (context, opLimits, dailyRemaining, monthlyRemaining) {
+        return {
+            allowed: true,
+            remaining: Math.min(dailyRemaining, monthlyRemaining) - context.amount,
+            dailyRemaining: dailyRemaining - context.amount,
+            monthlyRemaining: monthlyRemaining - context.amount,
+            maxAllowed: Math.min(opLimits.maxAmount, dailyRemaining, monthlyRemaining)
+        };
+    };
+    /**
+     * Get remaining limits for a user
+     */
+    KYCEligibility.getRemainingLimits = function (tier, transactionType, usage, customLimits) {
+        var _a, _b, _c;
+        var tierLimits = this.getTierLimits(tier, customLimits);
+        var opType = canonicalLimitKey(transactionType);
+        var opLimits = tierLimits[opType];
+        if (!opLimits) {
+            return { daily: 0, monthly: 0, perTransaction: 0 };
+        }
+        return {
+            daily: Math.max(0, opLimits.dailyLimit - ((_a = usage.daily) !== null && _a !== void 0 ? _a : 0)),
+            weekly: opLimits.weeklyLimit
+                ? Math.max(0, opLimits.weeklyLimit - ((_b = usage.weekly) !== null && _b !== void 0 ? _b : 0))
+                : undefined,
+            monthly: Math.max(0, opLimits.monthlyLimit - ((_c = usage.monthly) !== null && _c !== void 0 ? _c : 0)),
+            perTransaction: opLimits.maxAmount
+        };
+    };
+    /**
+     * Find the minimum tier that allows a specific amount
+     */
+    KYCEligibility.findTierForAmount = function (amount, transactionType, customLimits) {
+        var limits = customLimits !== null && customLimits !== void 0 ? customLimits : DEFAULT_TIER_LIMITS;
+        var tiers = this.getAllTiers();
+        var opType = canonicalLimitKey(transactionType);
+        for (var _i = 0, tiers_1 = tiers; _i < tiers_1.length; _i++) {
+            var tier = tiers_1[_i];
+            var tierLimits = limits[tier];
+            var opLimits = tierLimits[opType];
+            if (opLimits && opLimits.maxAmount >= amount) {
+                return tier;
+            }
+        }
+        return null;
+    };
+    // ─────────────────────────────────────────────────────────────────────────
+    // ACTION ELIGIBILITY
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Check if user can perform an action based on their tier
+     */
+    KYCEligibility.canPerformAction = function (action, currentTier, customActionTiers) {
+        var actionTiers = customActionTiers !== null && customActionTiers !== void 0 ? customActionTiers : DEFAULT_ACTION_TIERS;
+        var requiredTier = actionTiers[action];
+        if (!requiredTier) {
+            // Action not defined, allow by default
+            return { allowed: true };
+        }
+        var allowed = this.tierMeetsRequirement(currentTier, requiredTier);
+        return {
+            allowed: allowed,
+            reason: allowed ? undefined : "Requires ".concat(this.getTierDisplayName(requiredTier), " tier"),
+            requiredTier: allowed ? undefined : requiredTier
+        };
+    };
+    /**
+     * Get all actions a tier can perform
+     */
+    KYCEligibility.getAvailableActions = function (tier, customActionTiers) {
+        var actionTiers = customActionTiers !== null && customActionTiers !== void 0 ? customActionTiers : DEFAULT_ACTION_TIERS;
+        var available = [];
+        for (var _i = 0, _a = Object.keys(actionTiers); _i < _a.length; _i++) {
+            var action = _a[_i];
+            var requiredTier = actionTiers[action];
+            if (this.tierMeetsRequirement(tier, requiredTier)) {
+                available.push(action);
+            }
+        }
+        return available;
+    };
+    /**
+     * Get actions that require upgrade
+     */
+    KYCEligibility.getLockedActions = function (tier, customActionTiers) {
+        var actionTiers = customActionTiers !== null && customActionTiers !== void 0 ? customActionTiers : DEFAULT_ACTION_TIERS;
+        var locked = [];
+        for (var _i = 0, _a = Object.keys(actionTiers); _i < _a.length; _i++) {
+            var action = _a[_i];
+            var requiredTier = actionTiers[action];
+            if (!this.tierMeetsRequirement(tier, requiredTier)) {
+                locked.push({ action: action, requiredTier: requiredTier });
+            }
+        }
+        return locked;
+    };
+    // ─────────────────────────────────────────────────────────────────────────
+    // JURISDICTION RULES
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Check if a country is blocked
+     */
+    KYCEligibility.isCountryBlocked = function (country, rules) {
+        return rules.blockedCountries.indexOf(country) !== -1;
+    };
+    /**
+     * Check if a country is high risk
+     */
+    KYCEligibility.isCountryHighRisk = function (country, rules) {
+        return rules.highRiskCountries.indexOf(country) !== -1;
+    };
+    /**
+     * Check age eligibility for a jurisdiction
+     */
+    KYCEligibility.checkAgeEligibility = function (userAge, rules) {
+        if (userAge < rules.minimumAge) {
+            return {
+                eligible: false,
+                reason: "Minimum age is ".concat(rules.minimumAge, " years")
+            };
+        }
+        return { eligible: true };
+    };
+    /**
+     * Check nationality eligibility
+     */
+    KYCEligibility.checkNationalityEligibility = function (nationality, rules) {
+        var _a;
+        if (((_a = rules.restrictedNationalities) === null || _a === void 0 ? void 0 : _a.indexOf(nationality)) !== -1) {
+            return {
+                eligible: false,
+                reason: "Nationality '".concat(nationality, "' is restricted")
+            };
+        }
+        return { eligible: true };
+    };
+    // ─────────────────────────────────────────────────────────────────────────
+    // DOCUMENT VALIDATION (Client-side)
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Check if a document is expired
+     */
+    KYCEligibility.isDocumentExpired = function (expiryDate, currentDate) {
+        var now = currentDate !== null && currentDate !== void 0 ? currentDate : new Date();
+        return new Date(expiryDate) < now;
+    };
+    /**
+     * Check if a document is too old (e.g., utility bill older than 3 months)
+     */
+    KYCEligibility.isDocumentTooOld = function (issuedDate, maxAgeDays, currentDate) {
+        var now = currentDate !== null && currentDate !== void 0 ? currentDate : new Date();
+        var ageMs = now.getTime() - new Date(issuedDate).getTime();
+        var ageDays = Math.floor(ageMs / (1000 * 60 * 60 * 24));
+        return ageDays > maxAgeDays;
+    };
+    /**
+     * Validate document file (client-side pre-validation)
+     */
+    KYCEligibility.validateDocumentFile = function (file, options) {
+        var _a;
+        if (options === void 0) { options = {}; }
+        var _b = options.maxSizeMB, maxSizeMB = _b === void 0 ? 10 : _b, _c = options.allowedTypes, allowedTypes = _c === void 0 ? ['image/jpeg', 'image/png', 'application/pdf'] : _c, _d = options.allowedExtensions, allowedExtensions = _d === void 0 ? ['.jpg', '.jpeg', '.png', '.pdf'] : _d;
+        // Check file size
+        var sizeMB = file.size / (1024 * 1024);
+        if (sizeMB > maxSizeMB) {
+            return {
+                valid: false,
+                reason: "File too large. Maximum size is ".concat(maxSizeMB, "MB"),
+                code: exports.KYC_VALIDATOR_ERRORS.FileTooLarge,
+                details: { maxSizeMB: maxSizeMB, sizeMB: sizeMB }
+            };
+        }
+        // Check mime type
+        if (allowedTypes.indexOf(file.type) === -1) {
+            return {
+                valid: false,
+                reason: "File type '".concat(file.type, "' not allowed"),
+                code: exports.KYC_VALIDATOR_ERRORS.FileTypeNotAllowed,
+                details: { fileType: file.type, allowedTypes: allowedTypes }
+            };
+        }
+        // Check extension
+        var ext = '.' + ((_a = file.name.split('.').pop()) === null || _a === void 0 ? void 0 : _a.toLowerCase());
+        if (allowedExtensions.indexOf(ext) === -1) {
+            return {
+                valid: false,
+                reason: "File extension '".concat(ext, "' not allowed"),
+                code: exports.KYC_VALIDATOR_ERRORS.FileExtensionNotAllowed,
+                details: { extension: ext, allowedExtensions: allowedExtensions }
+            };
+        }
+        return { valid: true };
+    };
+    // ─────────────────────────────────────────────────────────────────────────
+    // RISK LEVEL UTILITIES
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Calculate risk level from score
+     */
+    KYCEligibility.getRiskLevelFromScore = function (score, thresholds) {
+        if (thresholds === void 0) { thresholds = { low: 30, medium: 50, high: 70 }; }
+        if (score >= thresholds.high)
+            return 'critical';
+        if (score >= thresholds.medium)
+            return 'high';
+        if (score >= thresholds.low)
+            return 'medium';
+        return 'low';
+    };
+    /**
+     * Check if enhanced due diligence is required
+     */
+    KYCEligibility.requiresEnhancedDueDiligence = function (context) {
+        // PEP always requires EDD
+        if (context.isPEP)
+            return true;
+        // High/critical risk requires EDD
+        if (context.riskLevel === 'high' || context.riskLevel === 'critical')
+            return true;
+        // High risk score requires EDD
+        if (context.riskScore && context.riskScore >= 70)
+            return true;
+        return false;
+    };
+    return KYCEligibility;
+}());
+exports.KYCEligibility = KYCEligibility;
+// ═══════════════════════════════════════════════════════════════════════════
+// CONVENIENCE EXPORTS
+// ═══════════════════════════════════════════════════════════════════════════
+exports.checkKYCTransaction = KYCEligibility.checkTransaction.bind(KYCEligibility);
+exports.getTierRequirements = KYCEligibility.getTierRequirements.bind(KYCEligibility);
+exports.checkTierEligibility = KYCEligibility.checkTierEligibility.bind(KYCEligibility);
+exports.canPerformAction = KYCEligibility.canPerformAction.bind(KYCEligibility);
+exports.tierMeetsRequirement = KYCEligibility.tierMeetsRequirement.bind(KYCEligibility);
+exports.getRemainingLimits = KYCEligibility.getRemainingLimits.bind(KYCEligibility);
+/**
+ * Top-level pre-validation helper — see {@link KYCEligibility.prevalidate}.
+ * Bulletproof client + server admission control. Pure function; no I/O.
+ */
+exports.prevalidateKYCTransaction = KYCEligibility.prevalidate.bind(KYCEligibility);