@explorins/pers-sdk 1.6.4 → 1.6.6

package/dist/managers/transaction-manager.d.ts

@@ -1,62 +1,491 @@
 import { PersApiClient } from '../core/pers-api-client';
-import { TransactionSDK } from '../transaction';
+import { TransactionService } from '../transaction';
 import type { TransactionDTO, TransactionRequestDTO } from '../shared/interfaces/pers-shared-lib.interfaces';
 import type { TransactionPaginationParams } from '../transaction/models';
 /**
  * Transaction Manager - Clean, high-level interface for transaction operations
  *
- * Provides a simplified API for common transaction management tasks while maintaining
- * access to the full transaction SDK for advanced use cases.
+ * Provides a comprehensive API for loyalty transaction management including transaction
+ * creation, history tracking, reporting, and administrative oversight. Transactions
+ * are the core financial operations that track token movements, purchases, rewards,
+ * and all value exchanges within the loyalty ecosystem.
+ *
+ * @group Managers
+ * @category Transaction Management
+ *
+ * @example Basic Transaction Operations
+ * ```typescript
+ * // Create a purchase transaction
+ * const transaction = await sdk.transactions.createTransaction({
+ *   type: 'PURCHASE',
+ *   amount: 100.00,
+ *   currency: 'USD',
+ *   businessId: 'partner-store-123',
+ *   description: 'Coffee shop purchase'
+ * });
+ *
+ * // Get transaction details
+ * const details = await sdk.transactions.getTransactionById(transaction.id);
+ * console.log('Transaction:', details.description, details.status);
+ *
+ * // View transaction history
+ * const history = await sdk.transactions.getUserTransactionHistory('ALL');
+ * console.log(`Found ${history.length} transactions`);
+ * ```
+ *
+ * @example Transaction History Analysis
+ * ```typescript
+ * // Get different types of transactions
+ * const purchases = await sdk.transactions.getUserTransactionHistory('PURCHASE');
+ * const rewards = await sdk.transactions.getUserTransactionHistory('REWARD');
+ * const redemptions = await sdk.transactions.getUserTransactionHistory('REDEMPTION');
+ *
+ * console.log('Transaction Summary:');
+ * console.log(`Purchases: ${purchases.length}`);
+ * console.log(`Rewards: ${rewards.length}`);
+ * console.log(`Redemptions: ${redemptions.length}`);
+ * ```
+ *
+ * @example Administrative Reporting
+ * ```typescript
+ * // Admin: Get all tenant transactions for analysis
+ * const allTransactions = await sdk.transactions.getTenantTransactions();
+ *
+ * // Export transaction data
+ * const csvBlob = await sdk.transactions.exportTransactionsCSV();
+ * const downloadUrl = URL.createObjectURL(csvBlob);
+ * console.log('Download transaction report:', downloadUrl);
+ * ```
  */
 export declare class TransactionManager {
     private apiClient;
-    private transactionSDK;
+    private transactionService;
     constructor(apiClient: PersApiClient);
     /**
      * Get transaction by ID
      *
-     * @param transactionId - ID of the transaction
-     * @returns Promise resolving to transaction data
+     * Retrieves detailed information for a specific transaction including status,
+     * amounts, participants, token transfers, and blockchain confirmations.
+     * Provides complete transaction audit trail and verification data.
+     *
+     * @param transactionId - Unique transaction identifier
+     * @returns Promise resolving to complete transaction data
+     * @throws {PersApiError} When transaction with specified ID is not found or access denied
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const transaction = await sdk.transactions.getTransactionById('txn-abc123');
+     *
+     *   console.log('📋 Transaction Details:');
+     *   console.log('ID:', transaction.id);
+     *   console.log('Type:', transaction.type);
+     *   console.log('Status:', transaction.status);
+     *   console.log('Amount:', transaction.amount, transaction.currency);
+     *   console.log('Date:', new Date(transaction.createdAt).toLocaleString());
+     *
+     *   if (transaction.description) {
+     *     console.log('Description:', transaction.description);
+     *   }
+     *
+     *   if (transaction.business) {
+     *     console.log('Business:', transaction.business.displayName);
+     *   }
+     *
+     *   // Show token movements
+     *   if (transaction.tokenTransfers?.length) {
+     *     console.log('\n💰 Token Transfers:');
+     *     transaction.tokenTransfers.forEach(transfer => {
+     *       console.log(`${transfer.amount} ${transfer.token.symbol} ${transfer.direction}`);
+     *     });
+     *   }
+     *
+     *   // Show blockchain confirmation
+     *   if (transaction.blockchainHash) {
+     *     console.log('🔗 Blockchain:', transaction.blockchainHash);
+     *   }
+     *
+     * } catch (error) {
+     *   console.log('Transaction not found or access denied:', error.message);
+     * }
+     * ```
      */
     getTransactionById(transactionId: string): Promise<TransactionDTO>;
     /**
      * Create a new transaction
      *
-     * @param transactionData - Transaction data
-     * @returns Promise resolving to transaction response
+     * Creates a new transaction in the loyalty system, processing token transfers,
+     * applying rewards, and updating user balances. Supports various transaction
+     * types including purchases, rewards, redemptions, and transfers.
+     *
+     * @param transactionData - Transaction configuration including type, amounts, and context
+     * @returns Promise resolving to transaction creation response
+     * @throws {PersApiError} When validation fails or insufficient balance
+     *
+     * @example Purchase Transaction
+     * ```typescript
+     * try {
+     *   const purchase = await sdk.transactions.createTransaction({
+     *     type: 'PURCHASE',
+     *     amount: 25.50,
+     *     currency: 'USD',
+     *     businessId: 'coffee-shop-123',
+     *     description: 'Morning coffee and pastry',
+     *     metadata: {
+     *       items: ['Latte', 'Croissant'],
+     *       location: 'Downtown Store'
+     *     }
+     *   });
+     *
+     *   console.log('✅ Purchase completed!');
+     *   console.log('Transaction ID:', purchase.id);
+     *   console.log('Status:', purchase.status);
+     *
+     *   if (purchase.tokensEarned?.length) {
+     *     console.log('\n🎁 Loyalty rewards earned:');
+     *     purchase.tokensEarned.forEach(reward => {
+     *       console.log(`${reward.amount} ${reward.token.symbol}`);
+     *     });
+     *   }
+     *
+     * } catch (error) {
+     *   console.log('Transaction failed:', error.message);
+     * }
+     * ```
+     *
+     * @example Reward Transaction
+     * ```typescript
+     * // Create reward transaction (typically triggered by campaigns)
+     * const reward = await sdk.transactions.createTransaction({
+     *   type: 'REWARD',
+     *   businessId: 'partner-hotel-456',
+     *   description: 'Welcome bonus for new customer',
+     *   tokenRewards: [
+     *     {
+     *       tokenId: 'loyalty-points',
+     *       amount: 500
+     *     }
+     *   ]
+     * });
+     *
+     * console.log('Reward transaction created:', reward.id);
+     * ```
+     *
+     * @example Transfer Transaction
+     * ```typescript
+     * // Create token transfer between users
+     * const transfer = await sdk.transactions.createTransaction({
+     *   type: 'TRANSFER',
+     *   recipientUserId: 'user-789',
+     *   description: 'Gift to friend',
+     *   tokenTransfers: [
+     *     {
+     *       tokenId: 'loyalty-points',
+     *       amount: 100,
+     *       direction: 'OUTBOUND'
+     *     }
+     *   ]
+     * });
+     *
+     * console.log('Transfer initiated:', transfer.id);
+     * ```
      */
-    createTransaction(transactionData: TransactionRequestDTO): Promise<import("@explorins/pers-shared").TransactionRequestResponseDTO>;
+    createTransaction(transactionData: TransactionRequestDTO): Promise<import("node_modules/@explorins/pers-shared/dist/cjs/shared-lib/dto/transaction/transaction.request.dto").TransactionRequestResponseDTO>;
     /**
      * Get user's transaction history
      *
-     * @param type - Transaction type filter
+     * Retrieves transaction history for the authenticated user, filtered by
+     * transaction type. Provides chronological view of all user's loyalty
+     * activities including purchases, rewards, redemptions, and transfers.
+     *
+     * @param type - Transaction type filter ('ALL', 'PURCHASE', 'REWARD', 'REDEMPTION', 'TRANSFER', etc.)
      * @returns Promise resolving to array of user's transactions
+     *
+     * @example All Transactions
+     * ```typescript
+     * const allTransactions = await sdk.transactions.getUserTransactionHistory('ALL');
+     *
+     * console.log(`📜 Transaction History (${allTransactions.length} transactions):`);
+     *
+     * allTransactions.forEach((transaction, index) => {
+     *   const date = new Date(transaction.createdAt).toLocaleDateString();
+     *   console.log(`\n${index + 1}. ${transaction.type} - ${date}`);
+     *   console.log(`   ${transaction.description || 'No description'}`);
+     *   console.log(`   Status: ${transaction.status}`);
+     *
+     *   if (transaction.amount && transaction.currency) {
+     *     console.log(`   Amount: ${transaction.amount} ${transaction.currency}`);
+     *   }
+     *
+     *   if (transaction.business) {
+     *     console.log(`   Business: ${transaction.business.displayName}`);
+     *   }
+     * });
+     * ```
+     *
+     * @example Filtered by Type
+     * ```typescript
+     * // Get only purchase transactions
+     * const purchases = await sdk.transactions.getUserTransactionHistory('PURCHASE');
+     *
+     * let totalSpent = 0;
+     * let totalRewards = 0;
+     *
+     * purchases.forEach(purchase => {
+     *   if (purchase.amount) {
+     *     totalSpent += purchase.amount;
+     *   }
+     *
+     *   if (purchase.tokensEarned?.length) {
+     *     purchase.tokensEarned.forEach(reward => {
+     *       totalRewards += reward.amount;
+     *     });
+     *   }
+     * });
+     *
+     * console.log('💳 Purchase Summary:');
+     * console.log(`Total purchases: ${purchases.length}`);
+     * console.log(`Total spent: $${totalSpent.toFixed(2)}`);
+     * console.log(`Total rewards earned: ${totalRewards} points`);
+     * ```
+     *
+     * @example Recent Activity
+     * ```typescript
+     * const recentTransactions = await sdk.transactions.getUserTransactionHistory('ALL');
+     *
+     * // Filter to last 30 days
+     * const thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
+     * const recentActivity = recentTransactions.filter(t =>
+     *   new Date(t.createdAt) > thirtyDaysAgo
+     * );
+     *
+     * console.log(`📅 Recent Activity (${recentActivity.length} transactions in last 30 days):`);
+     *
+     * // Group by type
+     * const activityByType = recentActivity.reduce((acc, t) => {
+     *   acc[t.type] = (acc[t.type] || 0) + 1;
+     *   return acc;
+     * }, {});
+     *
+     * Object.entries(activityByType).forEach(([type, count]) => {
+     *   console.log(`${type}: ${count} transactions`);
+     * });
+     * ```
      */
     getUserTransactionHistory(type: string): Promise<TransactionDTO[]>;
     /**
      * Admin: Get all tenant transactions
      *
-     * @returns Promise resolving to array of tenant transactions
+     * Retrieves all transactions across the entire tenant/organization for
+     * comprehensive reporting and analysis. This operation requires administrator
+     * privileges and provides system-wide transaction visibility.
+     *
+     * @returns Promise resolving to array of all tenant transactions
+     * @throws {PersApiError} When not authenticated as administrator
+     *
+     * @example
+     * ```typescript
+     * // Admin operation - comprehensive transaction analysis
+     * const allTransactions = await sdk.transactions.getTenantTransactions();
+     *
+     * console.log(`📊 Tenant Transaction Overview:`);
+     * console.log(`Total transactions: ${allTransactions.length}`);
+     *
+     * // Analyze by status
+     * const statusCounts = allTransactions.reduce((acc, t) => {
+     *   acc[t.status] = (acc[t.status] || 0) + 1;
+     *   return acc;
+     * }, {});
+     *
+     * console.log('\n📈 By status:');
+     * Object.entries(statusCounts).forEach(([status, count]) => {
+     *   console.log(`${status}: ${count} transactions`);
+     * });
+     *
+     * // Analyze by type
+     * const typeCounts = allTransactions.reduce((acc, t) => {
+     *   acc[t.type] = (acc[t.type] || 0) + 1;
+     *   return acc;
+     * }, {});
+     *
+     * console.log('\n🏷️ By type:');
+     * Object.entries(typeCounts).forEach(([type, count]) => {
+     *   console.log(`${type}: ${count} transactions`);
+     * });
+     *
+     * // Calculate volume metrics
+     * const totalVolume = allTransactions.reduce((sum, t) =>
+     *   sum + (t.amount || 0), 0
+     * );
+     *
+     * const avgTransactionSize = totalVolume / allTransactions.length;
+     *
+     * console.log('\n💰 Volume metrics:');
+     * console.log(`Total volume: $${totalVolume.toFixed(2)}`);
+     * console.log(`Average transaction: $${avgTransactionSize.toFixed(2)}`);
+     *
+     * // Recent activity analysis
+     * const last24Hours = allTransactions.filter(t =>
+     *   new Date(t.createdAt) > new Date(Date.now() - 24 * 60 * 60 * 1000)
+     * );
+     *
+     * console.log(`\n⏰ Last 24 hours: ${last24Hours.length} transactions`);
+     * ```
      */
     getTenantTransactions(): Promise<TransactionDTO[]>;
     /**
      * Admin: Get paginated transactions
      *
-     * @param params - Pagination parameters
-     * @returns Promise resolving to paginated transaction results
+     * Retrieves transactions with pagination support for efficient large dataset
+     * handling. This operation requires administrator privileges and is used for
+     * detailed transaction analysis and reporting interfaces.
+     *
+     * @param params - Pagination and filtering parameters
+     * @returns Promise resolving to paginated transaction results with metadata
+     * @throws {PersApiError} When not authenticated as administrator
+     *
+     * @example Basic Pagination
+     * ```typescript
+     * // Admin operation - paginated transaction retrieval
+     * const result = await sdk.transactions.getPaginatedTransactions({
+     *   page: 1,
+     *   limit: 50,
+     *   sortBy: 'createdAt',
+     *   sortOrder: 'DESC'
+     * });
+     *
+     * console.log(`📄 Page ${result.page} of ${result.totalPages}`);
+     * console.log(`Showing ${result.data.length} of ${result.total} transactions`);
+     *
+     * result.data.forEach((transaction, index) => {
+     *   console.log(`${index + 1}. ${transaction.type} - ${transaction.status}`);
+     *   console.log(`   ${new Date(transaction.createdAt).toLocaleDateString()}`);
+     * });
+     *
+     * // Continue pagination if needed
+     * if (result.hasNextPage) {
+     *   const nextPage = await sdk.transactions.getPaginatedTransactions({
+     *     page: result.page + 1,
+     *     limit: 50
+     *   });
+     * }
+     * ```
+     *
+     * @example Filtered Pagination
+     * ```typescript
+     * // Admin operation - filter transactions by criteria
+     * const filteredResult = await sdk.transactions.getPaginatedTransactions({
+     *   page: 1,
+     *   limit: 25,
+     *   filters: {
+     *     type: 'PURCHASE',
+     *     status: 'COMPLETED',
+     *     businessId: 'partner-store-123',
+     *     dateFrom: '2024-01-01',
+     *     dateTo: '2024-12-31'
+     *   },
+     *   sortBy: 'amount',
+     *   sortOrder: 'DESC'
+     * });
+     *
+     * console.log('🔍 Filtered Results:');
+     * console.log(`Found ${filteredResult.total} matching transactions`);
+     *
+     * filteredResult.data.forEach(transaction => {
+     *   console.log(`$${transaction.amount} - ${transaction.business?.displayName}`);
+     * });
+     * ```
      */
-    getPaginatedTransactions(params: TransactionPaginationParams): Promise<import("..").TransactionPaginationResponse>;
+    getPaginatedTransactions(params: TransactionPaginationParams): Promise<import("../transaction").TransactionPaginationResponse>;
     /**
      * Admin: Export transactions as CSV
      *
-     * @returns Promise resolving to CSV blob
+     * Generates a comprehensive CSV export of all tenant transactions for
+     * external analysis, reporting, or compliance purposes. This operation
+     * requires administrator privileges and creates a downloadable file.
+     *
+     * @returns Promise resolving to CSV blob for download
+     * @throws {PersApiError} When not authenticated as administrator or export fails
+     *
+     * @example
+     * ```typescript
+     * // Admin operation - export transaction data
+     * try {
+     *   const csvBlob = await sdk.transactions.exportTransactionsCSV();
+     *
+     *   // Create download link
+     *   const downloadUrl = URL.createObjectURL(csvBlob);
+     *   const link = document.createElement('a');
+     *   link.href = downloadUrl;
+     *   link.download = `transactions-${new Date().toISOString().split('T')[0]}.csv`;
+     *
+     *   // Trigger download
+     *   document.body.appendChild(link);
+     *   link.click();
+     *   document.body.removeChild(link);
+     *
+     *   // Clean up object URL
+     *   URL.revokeObjectURL(downloadUrl);
+     *
+     *   console.log('✅ Transaction export downloaded successfully');
+     *
+     * } catch (error) {
+     *   console.log('❌ Export failed:', error.message);
+     * }
+     * ```
+     *
+     * @example Server-side Export (Node.js)
+     * ```typescript
+     * // Admin operation - server-side CSV export
+     * const csvBlob = await sdk.transactions.exportTransactionsCSV();
+     *
+     * // Convert blob to buffer for Node.js
+     * const buffer = Buffer.from(await csvBlob.arrayBuffer());
+     *
+     * // Save to file system
+     * const fs = require('fs');
+     * const filename = `transactions-export-${Date.now()}.csv`;
+     * fs.writeFileSync(filename, buffer);
+     *
+     * console.log(`Transaction data exported to ${filename}`);
+     * ```
      */
     exportTransactionsCSV(): Promise<Blob>;
     /**
-     * Get the full transaction SDK for advanced operations
+     * Get the full transaction service for advanced operations
+     *
+     * Provides access to the complete TransactionService instance for advanced
+     * transaction operations, custom analytics, blockchain interactions, and
+     * operations not covered by the high-level manager methods.
+     *
+     * @returns TransactionService instance with full API access
+     *
+     * @example Advanced Operations
+     * ```typescript
+     * const transactionService = sdk.transactions.getTransactionService();
+     *
+     * // Access advanced transaction analytics
+     * const analytics = await transactionService.getTransactionAnalytics({
+     *   timeframe: 'last-30-days',
+     *   groupBy: 'business'
+     * });
+     *
+     * // Access blockchain transaction monitoring
+     * const blockchainStatus = await transactionService.getBlockchainTransactionStatus('txn-123');
+     *
+     * // Access transaction API directly
+     * const transactionApi = transactionService.api;
+     *
+     * // Use advanced validation and verification
+     * const verification = await transactionService.verifyTransactionIntegrity('txn-456');
      *
-     * @returns TransactionSDK instance
+     * // Access real-time transaction streaming
+     * const stream = transactionService.subscribeToTransactionUpdates();
+     * stream.on('transaction', (transaction) => {
+     *   console.log('New transaction:', transaction.id);
+     * });
+     * ```
      */
-    getTransactionSDK(): TransactionSDK;
+    getTransactionService(): TransactionService;
 }
 //# sourceMappingURL=transaction-manager.d.ts.map

package/dist/managers/transaction-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transaction-manager.d.ts","sourceRoot":"","sources":["../../src/managers/transaction-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAwB,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,KAAK,EACV,cAAc,EACd,qBAAqB,EACtB,MAAM,iDAAiD,CAAC;AACzD,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AAEzE;;;;;GAKG;AACH,qBAAa,kBAAkB;IAGjB,OAAO,CAAC,SAAS;IAF7B,OAAO,CAAC,cAAc,CAAiB;gBAEnB,SAAS,EAAE,aAAa;IAI5C;;;;;OAKG;IACG,kBAAkB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAIxE;;;;;OAKG;IACG,iBAAiB,CAAC,eAAe,EAAE,qBAAqB;IAI9D;;;;;OAKG;IACG,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAIxE;;;;OAIG;IACG,qBAAqB,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAIxD;;;;;OAKG;IACG,wBAAwB,CAAC,MAAM,EAAE,2BAA2B;IAIlE;;;;OAIG;IACG,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5C;;;;OAIG;IACH,iBAAiB,IAAI,cAAc;CAGpC"}
+{"version":3,"file":"transaction-manager.d.ts","sourceRoot":"","sources":["../../src/managers/transaction-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAkB,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,KAAK,EACV,cAAc,EACd,qBAAqB,EACtB,MAAM,iDAAiD,CAAC;AACzD,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,qBAAa,kBAAkB;IAGjB,OAAO,CAAC,SAAS;IAF7B,OAAO,CAAC,kBAAkB,CAAqB;gBAE3B,SAAS,EAAE,aAAa;IAK5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgDG;IACG,kBAAkB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAIxE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8EG;IACG,iBAAiB,CAAC,eAAe,EAAE,qBAAqB;IAI9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgFG;IACG,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAIxE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0DG;IACG,qBAAqB,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAIxD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8DG;IACG,wBAAwB,CAAC,MAAM,EAAE,2BAA2B;IAIlE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoDG;IACG,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACH,qBAAqB,IAAI,kBAAkB;CAG5C"}