@plyaz/types 1.11.3 → 1.12.0

package/dist/payments/transaction/types.d.ts

@@ -0,0 +1,120 @@
+import type { CURRENCY } from '../currency';
+/**
+ * Core money interface for handling monetary values throughout the system.
+ * All monetary amounts are stored in the smallest currency unit to avoid
+ * floating-point precision issues.
+ *
+ * Design Principles:
+ * - Always store amounts in smallest currency unit (cents, satoshis, wei)
+ * - Include currency information with every amount
+ * - Support display formatting for user interfaces
+ * - Track exchange rates for converted amounts
+ */
+export interface Money {
+    /**
+     * Amount in smallest currency unit (e.g., cents for USD, satoshis for BTC)
+     * Using integer values prevents floating-point precision issues
+     */
+    amount: number;
+    /**
+     * Currency code following ISO 4217 standard for fiat currencies
+     * and custom codes for cryptocurrencies (BTC, ETH, etc.)
+     */
+    currency: CURRENCY;
+    /**
+     * Human-readable formatted amount for display purposes
+     * Example: "$50.00", "€45.50", "0.001 BTC"
+     */
+    displayAmount?: string;
+    /**
+     * Exchange rate used if this amount was converted from another currency
+     * Useful for tracking conversions and fees
+     */
+    exchangeRate?: number;
+    /**
+     * Original currency if this amount was converted
+     * Helps with audit trails and reconciliation
+     */
+    originalCurrency?: CURRENCY;
+    /**
+     * Timestamp when exchange rate was calculated
+     * Important for cryptocurrency and volatile currency exchanges
+     */
+    exchangeRateTimestamp?: Date;
+}
+/**
+ * Comprehensive fee breakdown interface providing transparency
+ * into all costs associated with a payment transaction.
+ *
+ * Business Requirements:
+ * - Full transparency of all fees charged
+ * - Support for various fee types across providers
+ * - Regulatory compliance for fee disclosure
+ */
+export interface FeeBreakdown {
+    /** Payment processor fee (Stripe, PayPal, etc.) */
+    processingFee: Money;
+    /** Platform fee taken by Plyaz */
+    platformFee: Money;
+    /** Additional fee for international/cross-border transactions */
+    crossBorderFee?: Money;
+    /** Fee for currency conversion if applicable */
+    currencyConversionFee?: Money;
+    /** Network fee for blockchain transactions */
+    networkFee?: Money;
+    /** Gas fee for smart contract interactions */
+    gasFee?: Money;
+    /** Fee for instant/expedited processing */
+    expediteFee?: Money;
+    /** Risk assessment fee for high-risk transactions */
+    riskFee?: Money;
+    /** Regulatory compliance fee (where applicable) */
+    complianceFee?: Money;
+    /** Total of all fees combined */
+    total: Money;
+    /**
+     * Fee calculation metadata for audit and debugging
+     * Includes rate information and calculation details
+     */
+    calculationMetadata?: {
+        processingRate?: number;
+        platformRate?: number;
+        crossBorderRate?: number;
+        conversionRate?: number;
+        calculatedAt: Date;
+        ruleVersion?: string;
+    };
+}
+/**
+ * Payment limits interface defining constraints on transaction amounts
+ * and frequencies to support compliance and risk management.
+ */
+export interface PaymentLimits {
+    /** Minimum transaction amount per payment method */
+    minimumAmount: Money;
+    /** Maximum transaction amount per payment method */
+    maximumAmount: Money;
+    /** Maximum daily transaction volume per user */
+    dailyLimit?: Money;
+    /** Maximum weekly transaction volume per user */
+    weeklyLimit?: Money;
+    /** Maximum monthly transaction volume per user */
+    monthlyLimit?: Money;
+    /** Maximum annual transaction volume per user */
+    annualLimit?: Money;
+    /** Maximum number of transactions per day */
+    dailyTransactionLimit?: number;
+    /** Maximum number of transactions per hour */
+    hourlyTransactionLimit?: number;
+    /** Cooling-off period between large transactions (minutes) */
+    coolingOffPeriod?: number;
+    /** Velocity check configuration */
+    velocityLimits?: {
+        /** Maximum amount in specified time window */
+        maxAmount: Money;
+        /** Time window in minutes */
+        timeWindowMinutes: number;
+        /** Number of transactions allowed in window */
+        maxTransactions: number;
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plyaz/types",
-  "version": "1.11.3",
+  "version": "1.12.0",
   "author": "Redeemer Pace",
   "license": "ISC",
   "description": "Provides shared TypeScript types and schema utilities for validation and parsing in the @playz ecosystem.",
@@ -165,6 +165,11 @@
       "import": "./dist/web3/index.js",
       "require": "./dist/web3/index.cjs"
     },
+    "./payments": {
+      "types": "./dist/payments/index.d.ts",
+      "import": "./dist/payments/index.js",
+      "require": "./dist/payments/index.cjs"
+    },
     "./package.json": "./package.json"
   },
   "files": [