ts-client-lib 0.0.7

package/finance/TSKYC.d.ts

@@ -0,0 +1,563 @@
+/**
+ * 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');
+ * ```
+ */
+export declare const KYC_VALIDATOR_ERRORS: {
+    readonly UnknownKYCTier: "MSKYCUnknownKYCTier";
+    readonly FileTooLarge: "MSKYCFileTooLarge";
+    readonly FileTypeNotAllowed: "MSKYCFileTypeNotAllowed";
+    readonly FileExtensionNotAllowed: "MSKYCFileExtensionNotAllowed";
+    /** KYC status is not approved or in-review (e.g. rejected/suspended/expired). */
+    readonly KycStatusNotAllowed: "MSKYCStatusNotAllowed";
+    /** Stored `expiresAt` is past. Distinct from `KycStatusNotAllowed` so UIs can prompt re-verification. */
+    readonly KycExpired: "MSKYCExpired";
+    /** Account flagged suspended at the operator/auth layer. */
+    readonly AccountSuspended: "MSKYCAccountSuspended";
+    /** Self-exclusion window is active. */
+    readonly SelfExcluded: "MSKYCSelfExcluded";
+    /** Wallet status is not 'active' (suspended/closed). */
+    readonly WalletNotActive: "MSKYCWalletNotActive";
+    /** Wallet balance < amount on an outflow operation. */
+    readonly InsufficientBalance: "MSKYCInsufficientBalance";
+    /** Operation type has no limit profile at this tier (e.g. transfer at tier 'none'). */
+    readonly TierNotPermitted: "MSKYCTierNotPermitted";
+    /** Amount below the per-transaction min. */
+    readonly AmountBelowMin: "MSKYCAmountBelowMin";
+    /** Amount above the per-transaction max (upgrade may help). */
+    readonly AmountAboveMax: "MSKYCAmountAboveMax";
+    /** Daily aggregate cap would be exceeded. */
+    readonly DailyLimitExceeded: "MSKYCDailyLimitExceeded";
+    /** Weekly aggregate cap would be exceeded. */
+    readonly WeeklyLimitExceeded: "MSKYCWeeklyLimitExceeded";
+    /** Monthly aggregate cap would be exceeded. */
+    readonly MonthlyLimitExceeded: "MSKYCMonthlyLimitExceeded";
+    /** Per-period transaction-count cap reached. */
+    readonly TransactionCountExceeded: "MSKYCTransactionCountExceeded";
+    /** Deposit would push wallet balance above the tier's max-balance ceiling. */
+    readonly MaxBalanceExceeded: "MSKYCMaxBalanceExceeded";
+};
+export declare const KYC_VALIDATOR_ERROR_CODES: readonly string[];
+export type KYCValidatorErrorCode = (typeof KYC_VALIDATOR_ERRORS)[keyof typeof KYC_VALIDATOR_ERRORS];
+/**
+ * KYC verification tiers - ordered from lowest to highest
+ */
+export type KYCTier = 'none' | 'basic' | 'standard' | 'enhanced' | 'full' | 'professional';
+/**
+ * KYC verification status
+ */
+export type KYCStatus = 'pending' | 'in_review' | 'approved' | 'rejected' | 'expired' | 'suspended' | 'manual_review';
+/**
+ * Risk assessment levels
+ */
+export type KYCRiskLevel = 'low' | 'medium' | 'high' | 'critical';
+/**
+ * Document types for verification (platform-neutral: same union in Node services and browser clients).
+ * Add new literals here when kyc-service / atkyc / app agree on a shared label — then publish ts-client-lib.
+ */
+export type KYCDocumentType = 'passport' | 'national_id' | 'drivers_license' | 'residence_permit' | 'visa' | 'utility_bill' | 'bank_statement' | 'tax_document' | 'government_letter' | 'rental_agreement' | 'proof_of_income' | 'employment_letter' | 'tax_return' | 'investment_statement' | 'crypto_wallet_proof' | 'company_registration' | 'articles_of_incorporation' | 'shareholder_register' | 'board_resolution' | 'annual_report' | 'beneficial_owner_declaration' | 'selfie' | 'liveness_video' | 'other';
+/**
+ * Document categories
+ */
+export type KYCDocumentCategory = 'identity' | 'address' | 'financial' | 'corporate' | 'biometric';
+/**
+ * Canonical KYC transaction types — only four, mapped 1:1 to tier-limit profiles.
+ *
+ *   `deposit`    — money in (from external rail to user wallet)
+ *   `withdrawal` — money out (from user wallet to external rail)
+ *   `transfer`   — peer-to-peer / internal value movement
+ *   `order`      — ANY product debit routed through the `wallet.order` event envelope:
+ *                  sports bets, casino spins, lotto tickets, jackpot draws, oscommerce
+ *                  purchases — anything that consumes wallet balance against an order.
+ *
+ * Product-specific terminology (`'bet'`, `'purchase'`, `'trade'`) is intentionally
+ * absent: adding a new product type should NOT require a code/enum/list change.
+ * Operators define per-category overrides at the operator config layer (string-keyed
+ * `byCategory` record), feeding `event.data.category` into the lookup. Redis aggregate
+ * keys accept any string so usage tracking scales the same way without code changes.
+ *
+ * `order` reuses the `deposit` limit profile by default (see `canonicalLimitKey`).
+ * Operators wanting tighter or looser wager limits configure them as a per-category
+ * override on the operator side — the lib stays generic.
+ */
+export type KYCTransactionType = 'deposit' | 'withdrawal' | 'transfer' | 'order';
+/**
+ * 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.
+ */
+export declare function canonicalLimitKey(t: KYCTransactionType): 'deposit' | 'withdrawal' | 'transfer';
+/**
+ * Limits for a specific operation type
+ */
+export interface KYCOperationLimits {
+    minAmount?: number;
+    maxAmount: number;
+    dailyLimit: number;
+    weeklyLimit?: number;
+    monthlyLimit: number;
+    yearlyLimit?: number;
+    maxDailyTransactions?: number;
+    maxMonthlyTransactions?: number;
+}
+/**
+ * Transaction limits for a tier
+ */
+export interface KYCTierLimits {
+    currency: string;
+    deposit: KYCOperationLimits;
+    withdrawal: KYCOperationLimits;
+    transfer?: KYCOperationLimits;
+    maxBalance?: number;
+}
+/**
+ * Document requirement
+ */
+export interface KYCDocumentRequirement {
+    id: string;
+    name: string;
+    description?: string;
+    category: KYCDocumentCategory;
+    acceptedTypes: KYCDocumentType[];
+    required: boolean;
+    minCount?: number;
+    maxAgeDays?: number;
+    mustNotBeExpired?: boolean;
+}
+/**
+ * Check requirement (AML, PEP, etc.)
+ */
+export interface KYCCheckRequirement {
+    id: string;
+    name: string;
+    type: 'aml' | 'pep' | 'sanctions' | 'liveness' | 'face_match' | 'address_verification';
+    required: boolean;
+}
+/**
+ * Information field requirement
+ */
+export interface KYCInfoRequirement {
+    id: string;
+    fieldPath: string;
+    displayName: string;
+    required: boolean;
+}
+/**
+ * Complete tier requirements
+ */
+export interface KYCTierRequirements {
+    tier: KYCTier;
+    displayName: string;
+    description: string;
+    documents: KYCDocumentRequirement[];
+    checks: KYCCheckRequirement[];
+    information: KYCInfoRequirement[];
+    prerequisiteTier?: KYCTier;
+    minimumAge?: number;
+}
+/**
+ * Context for transaction checking
+ */
+export interface KYCTransactionContext {
+    currentTier: KYCTier;
+    kycStatus?: KYCStatus;
+    transactionType: KYCTransactionType;
+    amount: number;
+    currency: string;
+    usedToday?: number;
+    usedThisWeek?: number;
+    usedThisMonth?: number;
+    usedThisYear?: number;
+    transactionsToday?: number;
+    transactionsThisMonth?: number;
+    currentBalance?: number;
+    country?: string;
+    userAge?: number;
+    accountAgeDays?: number;
+    documentsExpireAt?: Date;
+    currentDate?: Date;
+    /**
+     * When set (e.g. jurisdiction from DB + defaults), used to resolve `requiredTier` when a
+     * single transaction exceeds `maxAmount` — same tier ladder as server config, not only lib defaults.
+     */
+    jurisdictionLimits?: Record<KYCTier, KYCTierLimits>;
+}
+/**
+ * Context for general KYC eligibility checking
+ */
+export interface KYCEligibilityContext {
+    userId?: string;
+    tenantId?: string;
+    currentTier: KYCTier;
+    kycStatus: KYCStatus;
+    country: string;
+    riskLevel?: KYCRiskLevel;
+    riskScore?: number;
+    hasIdentityDoc?: boolean;
+    hasAddressDoc?: boolean;
+    hasFinancialDoc?: boolean;
+    documentsExpireAt?: Date;
+    amlCheckPassed?: boolean;
+    pepCheckPassed?: boolean;
+    sanctionsCheckPassed?: boolean;
+    livenessCheckPassed?: boolean;
+    userAge?: number;
+    accountAgeDays?: number;
+    isPEP?: boolean;
+    currentDate?: Date;
+}
+/**
+ * Transaction check result
+ */
+export interface KYCTransactionResult {
+    allowed: boolean;
+    reason?: string;
+    /** Stable error code for i18n when result is sent to client */
+    code?: string;
+    /** Extra context for i18n interpolation */
+    details?: Record<string, unknown>;
+    remaining?: number;
+    dailyRemaining?: number;
+    monthlyRemaining?: number;
+    maxAllowed?: number;
+    requiredTier?: KYCTier;
+    upgradeMessage?: string;
+}
+/**
+ * Tier eligibility result
+ */
+export interface KYCTierEligibilityResult {
+    currentTier: KYCTier;
+    targetTier: KYCTier;
+    eligible: boolean;
+    missingRequirements: string[];
+    completedRequirements: string[];
+    progress: number;
+}
+/**
+ * Action eligibility result
+ */
+export interface KYCActionResult {
+    allowed: boolean;
+    reason?: string;
+    requiredTier?: KYCTier;
+    requiredStatus?: KYCStatus;
+}
+/**
+ * Jurisdiction rules for validation
+ */
+export interface KYCJurisdictionRules {
+    code: string;
+    name: string;
+    minimumAge: number;
+    blockedCountries: string[];
+    highRiskCountries: string[];
+    restrictedNationalities?: string[];
+    requiresLocalResidence?: boolean;
+    selfExclusionRequired?: boolean;
+}
+/**
+ * Wallet-side input to `prevalidate`. All fields optional; the lib only enforces what's
+ * supplied. The client app already has these from the wallet API; servers populate them
+ * from their authoritative state. Same shape on both sides.
+ */
+export interface KYCWalletInput {
+    /** 'active' | 'suspended' | 'closed' — only 'active' lets transactions proceed. */
+    status?: 'active' | 'suspended' | 'closed';
+    /**
+     * Wallet balance in the currency being transacted. Consulted ONLY for outflow
+     * operations (`withdrawal`, `transfer`, `order`) — deposits don't need a balance check.
+     */
+    balance?: number;
+}
+/**
+ * Account-side input. The auth/identity API surfaces these.
+ */
+export interface KYCAccountInput {
+    /** True if the account is administratively suspended (auth layer). */
+    suspended?: boolean;
+    /**
+     * Self-exclusion window. ISO string or Date. If `> now`, transaction is blocked
+     * with `SelfExcluded`. Responsible-gambling regulators require this gate on
+     * deposits AND wagers; we enforce it generically.
+     */
+    selfExcludedUntil?: string | Date | null;
+}
+/**
+ * Bulletproof pre-validation input — single object the caller passes containing
+ * everything the lib needs to reach the same verdict the server reaches. Pure: no
+ * Redis, no HTTP, no DB. Caller supplies data; lib decides.
+ *
+ * Client usage: disable submit buttons before the user taps, surface inline
+ * messages, suggest upgrades. Server usage: same call in pre-transaction middleware
+ * or in the wallet.order handler — defence-in-depth using one rule engine.
+ */
+export interface KYCPrevalidationInput {
+    currentTier: KYCTier;
+    kycStatus: KYCStatus;
+    /** ISO string or Date. If past, treated as `KycExpired` even when status is approved. */
+    expiresAt?: string | Date | null;
+    /**
+     * Per-jurisdiction tier ladder (operator config). When provided, the lib walks
+     * the ladder to suggest the right `upgradeToTier`; when omitted, the lib uses
+     * its built-in defaults.
+     */
+    jurisdictionLimits?: Record<KYCTier, KYCTierLimits>;
+    operation: KYCTransactionType;
+    amount: number;
+    currency: string;
+    usedToday?: number;
+    usedThisWeek?: number;
+    usedThisMonth?: number;
+    transactionsToday?: number;
+    transactionsThisMonth?: number;
+    wallet?: KYCWalletInput;
+    account?: KYCAccountInput;
+}
+/**
+ * Single-shape result the client renders into UI hints and the server returns
+ * to the gateway as a structured rejection. `code` is bounded (`KYC_VALIDATOR_ERRORS`)
+ * for stable i18n.
+ */
+export interface KYCPrevalidationResult {
+    allowed: boolean;
+    /** Bounded code from `KYC_VALIDATOR_ERRORS`. Stable across client + server. */
+    code?: KYCValidatorErrorCode;
+    reason?: string;
+    /** Structured details for i18n interpolation (limit values, remaining, etc.). */
+    details?: Record<string, unknown>;
+    /** Largest amount the user could submit right now (this operation, this currency). */
+    maxAllowed?: number;
+    /** Remaining daily budget after this transaction (if allowed). */
+    dailyRemaining?: number;
+    /** Remaining monthly budget after this transaction (if allowed). */
+    monthlyRemaining?: number;
+    upgradeToTier?: KYCTier;
+    upgradeMessage?: string;
+}
+export declare class KYCEligibility {
+    /**
+     * Get numeric level for a tier (for comparisons)
+     */
+    static getTierLevel(tier: KYCTier): number;
+    /**
+     * Compare two tiers. Returns negative if a < b, 0 if equal, positive if a > b
+     */
+    static compareTiers(a: KYCTier, b: KYCTier): number;
+    /**
+     * Check if tier meets minimum requirement
+     */
+    static tierMeetsRequirement(currentTier: KYCTier, requiredTier: KYCTier): boolean;
+    /**
+     * Get display name for a tier
+     */
+    static getTierDisplayName(tier: KYCTier): string;
+    /**
+     * Get description for a tier
+     */
+    static getTierDescription(tier: KYCTier): string;
+    /**
+     * Get next tier in the hierarchy
+     */
+    static getNextTier(currentTier: KYCTier): KYCTier | null;
+    /**
+     * Get all tiers in order
+     */
+    static getAllTiers(): KYCTier[];
+    /**
+     * Get requirements for a tier
+     */
+    static getTierRequirements(tier: KYCTier): KYCTierRequirements;
+    /**
+     * Get all requirements needed to reach a tier from current tier
+     */
+    static getRequirementsToReachTier(currentTier: KYCTier, targetTier: KYCTier): KYCTierRequirements[];
+    /**
+     * Check eligibility for a target tier
+     */
+    static checkTierEligibility(targetTier: KYCTier, context: KYCEligibilityContext): KYCTierEligibilityResult;
+    private static collectTierPrerequisite;
+    private static collectTierDocuments;
+    private static collectTierVerificationChecks;
+    private static collectTierMinimumAge;
+    /**
+     * 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.
+     */
+    static prevalidate(input: KYCPrevalidationInput): KYCPrevalidationResult;
+    private static preRejectAccount;
+    private static preRejectWalletStatus;
+    private static preRejectKyc;
+    private static preRejectInsufficientBalance;
+    /**
+     * Get limits for a tier
+     */
+    static getTierLimits(tier: KYCTier, customLimits?: Record<KYCTier, KYCTierLimits>): KYCTierLimits;
+    /**
+     * Check if a transaction is allowed
+     */
+    static checkTransaction(limits: KYCTierLimits | Record<KYCTier, KYCTierLimits>, context: KYCTransactionContext): KYCTransactionResult;
+    private static resolveTransactionTierLimits;
+    private static txRejectInvalidKycStatus;
+    private static resolveTransactionOpLimits;
+    private static txRejectBelowMinAmount;
+    private static txRejectAboveMaxPerTransaction;
+    private static txRejectExceedsDailyBudget;
+    private static txRejectExceedsMonthlyBudget;
+    private static txRejectExceedsWeeklyBudget;
+    private static txRejectDailyTransactionCount;
+    private static txRejectDepositOverMaxBalance;
+    private static txBuildAllowedResult;
+    /**
+     * Get remaining limits for a user
+     */
+    static getRemainingLimits(tier: KYCTier, transactionType: KYCTransactionType, usage: {
+        daily?: number;
+        weekly?: number;
+        monthly?: number;
+    }, customLimits?: Record<KYCTier, KYCTierLimits>): {
+        daily: number;
+        weekly?: number;
+        monthly: number;
+        perTransaction: number;
+    };
+    /**
+     * Find the minimum tier that allows a specific amount
+     */
+    static findTierForAmount(amount: number, transactionType: KYCTransactionType, customLimits?: Record<KYCTier, KYCTierLimits>): KYCTier | null;
+    /**
+     * Check if user can perform an action based on their tier
+     */
+    static canPerformAction(action: string, currentTier: KYCTier, customActionTiers?: Record<string, KYCTier>): KYCActionResult;
+    /**
+     * Get all actions a tier can perform
+     */
+    static getAvailableActions(tier: KYCTier, customActionTiers?: Record<string, KYCTier>): string[];
+    /**
+     * Get actions that require upgrade
+     */
+    static getLockedActions(tier: KYCTier, customActionTiers?: Record<string, KYCTier>): Array<{
+        action: string;
+        requiredTier: KYCTier;
+    }>;
+    /**
+     * Check if a country is blocked
+     */
+    static isCountryBlocked(country: string, rules: KYCJurisdictionRules): boolean;
+    /**
+     * Check if a country is high risk
+     */
+    static isCountryHighRisk(country: string, rules: KYCJurisdictionRules): boolean;
+    /**
+     * Check age eligibility for a jurisdiction
+     */
+    static checkAgeEligibility(userAge: number, rules: KYCJurisdictionRules): {
+        eligible: boolean;
+        reason?: string;
+    };
+    /**
+     * Check nationality eligibility
+     */
+    static checkNationalityEligibility(nationality: string, rules: KYCJurisdictionRules): {
+        eligible: boolean;
+        reason?: string;
+    };
+    /**
+     * Check if a document is expired
+     */
+    static isDocumentExpired(expiryDate: Date, currentDate?: Date): boolean;
+    /**
+     * Check if a document is too old (e.g., utility bill older than 3 months)
+     */
+    static isDocumentTooOld(issuedDate: Date, maxAgeDays: number, currentDate?: Date): boolean;
+    /**
+     * Validate document file (client-side pre-validation)
+     */
+    static validateDocumentFile(file: {
+        name: string;
+        size: number;
+        type: string;
+    }, options?: {
+        maxSizeMB?: number;
+        allowedTypes?: string[];
+        allowedExtensions?: string[];
+    }): {
+        valid: boolean;
+        reason?: string;
+        code?: string;
+        details?: Record<string, unknown>;
+    };
+    /**
+     * Calculate risk level from score
+     */
+    static getRiskLevelFromScore(score: number, thresholds?: {
+        low: number;
+        medium: number;
+        high: number;
+    }): KYCRiskLevel;
+    /**
+     * Check if enhanced due diligence is required
+     */
+    static requiresEnhancedDueDiligence(context: KYCEligibilityContext): boolean;
+}
+export declare const checkKYCTransaction: typeof KYCEligibility.checkTransaction;
+export declare const getTierRequirements: typeof KYCEligibility.getTierRequirements;
+export declare const checkTierEligibility: typeof KYCEligibility.checkTierEligibility;
+export declare const canPerformAction: typeof KYCEligibility.canPerformAction;
+export declare const tierMeetsRequirement: typeof KYCEligibility.tierMeetsRequirement;
+export declare const getRemainingLimits: typeof KYCEligibility.getRemainingLimits;
+/**
+ * Top-level pre-validation helper — see {@link KYCEligibility.prevalidate}.
+ * Bulletproof client + server admission control. Pure function; no I/O.
+ */
+export declare const prevalidateKYCTransaction: typeof KYCEligibility.prevalidate;