@plyaz/types 1.11.4 → 1.12.1

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.4",
+  "version": "1.12.1",
   "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": [

package/dist/auth/config/types.d.ts

@@ -1,67 +0,0 @@
-import type { UserContext, AuthCredentials } from '../types';
-/**
- * @plyaz/auth/providers/base/auth-service-provider.interface
- * The contract for all external authentication service adapters (Supabase, Internal DB, etc.).
- * This ensures our strategies remain vendor-agnostic.
- */
-export interface AuthServiceProvider {
-    /**
-     * Synchronizes an external user ID (e.g., from Clerk or Web3) with the internal RLS database.
-     * This method ensures the user exists internally and issues an RLS token.
-     * * @param externalId The unique ID from the external provider (e.g., Clerk's 'sub').
-     * @param email The user's primary email address.
-     * @returns An object containing the internal UserContext and the RLS JWT.
-     */
-    syncUserFromExternalToken(externalId: string, email: string): Promise<{
-        user: UserContext;
-        supabaseRlsToken: string;
-    }>;
-    /** Handles traditional login via email/password (used as a fallback or if Clerk is bypassed). */
-    authenticate(credentials: AuthCredentials): Promise<UserContext>;
-    /** Registers a new user with the provider. */
-    register(credentials: AuthCredentials): Promise<UserContext>;
-    /** Retrieves basic user profile information by internal ID. */
-    getUserById(userId: string): Promise<UserContext | null>;
-    /** Requests a password reset (only relevant for traditional auth flows). */
-    requestPasswordReset(email: string): Promise<void>;
-}
-/**
- * The contract for all external OAuth authentication providers (Google, GitHub, etc.).
- * This interface ensures our strategies remain vendor-agnostic and defines
- * the core functionality required to authenticate with an OAuth service.
- */
-export interface OAuthProvider {
-    /**
-     * Generates the URL to redirect the user to for authentication.
-     * This URL will typically include a client ID, redirect URI, and scopes.
-     * @param redirectUrl The URL to which the user will be redirected after authentication.
-     * @returns The full URL for the OAuth login page.
-     */
-    getRedirectUrl(redirectUrl: string): string;
-    /**
-     * Exchanges an authorization code for an access token and user information.
-     * This method is called after the user has successfully authenticated with the provider.
-     * @param code The authorization code received from the OAuth provider.
-     * @returns A promise that resolves to the user's details and a refresh token.
-     */
-    exchangeCodeForToken(code: string): Promise<{
-        accessToken: string;
-        refreshToken: string;
-        expiresIn: number;
-        user: {
-            providerId: string;
-            email: string;
-            name?: string;
-            profileImageUrl?: string;
-        };
-    }>;
-    /**
-     * (Optional) Refreshes an access token using a refresh token.
-     * @param refreshToken The refresh token provided by the provider.
-     * @returns A new access token and its expiration time.
-     */
-    refreshToken?(refreshToken: string): Promise<{
-        accessToken: string;
-        expiresIn: number;
-    }>;
-}