@explorins/pers-sdk 1.6.3 → 1.6.6

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

@@ -1,44 +1,369 @@
 import { PersApiClient } from '../core/pers-api-client';
-import { PaymentSDK } from '../payment';
+import { PaymentService } from '../payment';
 import type { PaymentIntentDTO, PurchaseDTO, PurchaseTokenDTO } from '../shared/interfaces/pers-shared-lib.interfaces';
 /**
  * Purchase Manager - Clean, high-level interface for purchase operations
  *
- * Provides a simplified API for common purchase management tasks while maintaining
- * access to the full payment SDK for advanced use cases.
+ * Provides a comprehensive API for purchase and payment management including payment
+ * intent creation, purchase token handling, user purchase history, and integration
+ * with payment processors. Handles both fiat currency payments and loyalty token
+ * purchases within the ecosystem.
+ *
+ * @group Managers
+ * @category Purchase Management
+ *
+ * @example Basic Purchase Operations
+ * ```typescript
+ * // Create payment intent for fiat purchase
+ * const paymentIntent = await sdk.purchases.createPaymentIntent(
+ *   50.00,
+ *   'USD',
+ *   'customer@example.com',
+ *   'Loyalty token bundle purchase'
+ * );
+ * console.log('Payment intent created:', paymentIntent.id);
+ *
+ * // Get available purchase tokens
+ * const tokens = await sdk.purchases.getActivePurchaseTokens();
+ * console.log(`${tokens.length} token packages available`);
+ *
+ * // View purchase history
+ * const purchases = await sdk.purchases.getAllUserPurchases();
+ * console.log(`User has made ${purchases.length} purchases`);
+ * ```
+ *
+ * @example Purchase Token Discovery
+ * ```typescript
+ * // Browse available token packages
+ * const availableTokens = await sdk.purchases.getActivePurchaseTokens(true);
+ *
+ * console.log('💎 Available Token Packages:');
+ * availableTokens.forEach(token => {
+ *   console.log(`\n${token.name}`);
+ *   console.log(`Price: $${token.price} ${token.currency}`);
+ *   console.log(`Tokens: ${token.tokenAmount} ${token.tokenSymbol}`);
+ *   console.log(`Description: ${token.description}`);
+ * });
+ * ```
+ *
+ * @example Payment Processing
+ * ```typescript
+ * // Create payment for specific token package
+ * const selectedPackage = availableTokens[0];
+ * const paymentIntent = await sdk.purchases.createPaymentIntent(
+ *   selectedPackage.price,
+ *   selectedPackage.currency,
+ *   'user@example.com',
+ *   `Purchase: ${selectedPackage.name}`
+ * );
+ *
+ * // Use payment intent client secret for frontend payment processing
+ * console.log('Payment client secret:', paymentIntent.clientSecret);
+ * ```
  */
 export declare class PurchaseManager {
     private apiClient;
-    private paymentSDK;
+    private paymentService;
     constructor(apiClient: PersApiClient);
     /**
      * Create a payment intent
      *
-     * @param amount - Payment amount
-     * @param currency - Payment currency
-     * @param receiptEmail - Receipt email
-     * @param description - Payment description
-     * @returns Promise resolving to created payment intent
+     * Creates a payment intent for processing fiat currency payments through
+     * integrated payment processors (e.g., Stripe). Payment intents are used to
+     * securely handle payment processing on the frontend while maintaining
+     * server-side validation and security.
+     *
+     * @param amount - Payment amount in the specified currency's smallest unit (e.g., cents for USD)
+     * @param currency - Payment currency code (e.g., 'USD', 'EUR', 'GBP')
+     * @param receiptEmail - Email address for sending payment receipt
+     * @param description - Human-readable description of the payment
+     * @returns Promise resolving to payment intent with client secret
+     * @throws {PersApiError} When payment processing is unavailable or validation fails
+     *
+     * @example Simple Payment Intent
+     * ```typescript
+     * try {
+     *   const paymentIntent = await sdk.purchases.createPaymentIntent(
+     *     2500,  // $25.00 in cents
+     *     'USD',
+     *     'customer@example.com',
+     *     '1000 Loyalty Points Package'
+     *   );
+     *
+     *   console.log('💳 Payment Intent Created:');
+     *   console.log('ID:', paymentIntent.id);
+     *   console.log('Amount:', paymentIntent.amount / 100, paymentIntent.currency);
+     *   console.log('Status:', paymentIntent.status);
+     *   console.log('Client Secret:', paymentIntent.clientSecret);
+     *
+     *   // Use client secret in frontend payment processing
+     *   // Example with Stripe Elements:
+     *   // const { confirmPayment } = useStripe();
+     *   // await confirmPayment({
+     *   //   elements,
+     *   //   confirmParams: {
+     *   //     return_url: 'https://yourapp.com/payment-success'
+     *   //   }
+     *   // });
+     *
+     * } catch (error) {
+     *   console.log('Payment intent creation failed:', error.message);
+     * }
+     * ```
+     *
+     * @example Token Package Purchase
+     * ```typescript
+     * // Get available token packages first
+     * const packages = await sdk.purchases.getActivePurchaseTokens(true);
+     * const selectedPackage = packages.find(p => p.name === 'Starter Package');
+     *
+     * if (selectedPackage) {
+     *   const paymentIntent = await sdk.purchases.createPaymentIntent(
+     *     selectedPackage.price * 100,  // Convert to cents
+     *     selectedPackage.currency,
+     *     'user@example.com',
+     *     `Purchase: ${selectedPackage.name} - ${selectedPackage.tokenAmount} ${selectedPackage.tokenSymbol}`
+     *   );
+     *
+     *   console.log(`Payment setup for ${selectedPackage.name}`);
+     *   console.log(`Will receive: ${selectedPackage.tokenAmount} ${selectedPackage.tokenSymbol}`);
+     *   console.log(`Payment amount: $${selectedPackage.price}`);
+     *
+     *   // Store payment intent for frontend processing
+     *   localStorage.setItem('paymentIntentId', paymentIntent.id);
+     *   localStorage.setItem('expectedTokens', selectedPackage.tokenAmount.toString());
+     * }
+     * ```
+     *
+     * @example Subscription Payment
+     * ```typescript
+     * // Create payment intent for recurring subscription
+     * const subscriptionPayment = await sdk.purchases.createPaymentIntent(
+     *   999,  // $9.99/month
+     *   'USD',
+     *   'subscriber@example.com',
+     *   'Premium Loyalty Membership - Monthly'
+     * );
+     *
+     * console.log('Subscription payment intent:', subscriptionPayment.id);
+     * // Payment processor will handle recurring billing setup
+     * ```
      */
     createPaymentIntent(amount: number, currency: string, receiptEmail: string, description: string): Promise<PaymentIntentDTO>;
     /**
      * Get active purchase tokens
      *
-     * @param active - Filter by active status
-     * @returns Promise resolving to purchase tokens
+     * Retrieves available token packages that users can purchase with fiat currency.
+     * These packages represent bundles of loyalty tokens at various price points,
+     * often with bonus tokens for larger purchases.
+     *
+     * @param active - Optional filter to show only active packages (default: all packages)
+     * @returns Promise resolving to array of purchase token packages
+     *
+     * @example
+     * ```typescript
+     * const allPackages = await sdk.purchases.getActivePurchaseTokens();
+     * const activeOnly = await sdk.purchases.getActivePurchaseTokens(true);
+     *
+     * console.log('💎 Token Package Catalog:');
+     *
+     * activeOnly.forEach(package => {
+     *   console.log(`\n📦 ${package.name}`);
+     *   console.log(`💰 Price: $${package.price} ${package.currency}`);
+     *   console.log(`🪙  Tokens: ${package.tokenAmount} ${package.tokenSymbol}`);
+     *   console.log(`📝 ${package.description}`);
+     *
+     *   // Calculate value per token
+     *   const costPerToken = package.price / package.tokenAmount;
+     *   console.log(`💡 Value: $${costPerToken.toFixed(4)} per token`);
+     *
+     *   if (package.bonusTokens && package.bonusTokens > 0) {
+     *     console.log(`🎁 Bonus: +${package.bonusTokens} extra tokens`);
+     *     const totalTokens = package.tokenAmount + package.bonusTokens;
+     *     const actualCostPerToken = package.price / totalTokens;
+     *     console.log(`💡 With bonus: $${actualCostPerToken.toFixed(4)} per token`);
+     *   }
+     *
+     *   if (package.validUntil) {
+     *     console.log(`⏰ Valid until: ${new Date(package.validUntil).toLocaleDateString()}`);
+     *   }
+     * });
+     *
+     * // Find best value package
+     * const bestValue = activeOnly.reduce((best, current) => {
+     *   const currentValue = current.price / (current.tokenAmount + (current.bonusTokens || 0));
+     *   const bestValue = best.price / (best.tokenAmount + (best.bonusTokens || 0));
+     *   return currentValue < bestValue ? current : best;
+     * });
+     *
+     * console.log(`\n🌟 Best Value: ${bestValue.name}`);
+     * ```
+     *
+     * @example Filter by Currency and Price
+     * ```typescript
+     * const packages = await sdk.purchases.getActivePurchaseTokens(true);
+     *
+     * // Filter by currency
+     * const usdPackages = packages.filter(p => p.currency === 'USD');
+     * const eurPackages = packages.filter(p => p.currency === 'EUR');
+     *
+     * console.log(`USD packages: ${usdPackages.length}`);
+     * console.log(`EUR packages: ${eurPackages.length}`);
+     *
+     * // Filter by price range
+     * const budgetPackages = packages.filter(p => p.price <= 25);
+     * const premiumPackages = packages.filter(p => p.price > 100);
+     *
+     * console.log(`Budget options (≤$25): ${budgetPackages.length}`);
+     * console.log(`Premium options (>$100): ${premiumPackages.length}`);
+     *
+     * // Sort by token amount
+     * const sortedByTokens = [...packages].sort((a, b) =>
+     *   (b.tokenAmount + (b.bonusTokens || 0)) - (a.tokenAmount + (a.bonusTokens || 0))
+     * );
+     *
+     * console.log('\n🎯 Top 3 by token amount:');
+     * sortedByTokens.slice(0, 3).forEach((pkg, index) => {
+     *   const totalTokens = pkg.tokenAmount + (pkg.bonusTokens || 0);
+     *   console.log(`${index + 1}. ${pkg.name}: ${totalTokens} tokens`);
+     * });
+     * ```
      */
     getActivePurchaseTokens(active?: boolean): Promise<PurchaseTokenDTO[]>;
     /**
      * Get all user purchases
      *
-     * @returns Promise resolving to array of user's purchases
+     * Retrieves the complete purchase history for the authenticated user,
+     * including both successful and failed purchases. Provides insights into
+     * user spending patterns, token acquisition, and payment history.
+     *
+     * @returns Promise resolving to array of user's purchase records
+     *
+     * @example
+     * ```typescript
+     * const userPurchases = await sdk.purchases.getAllUserPurchases();
+     *
+     * console.log(`📜 Purchase History (${userPurchases.length} purchases):`);
+     *
+     * userPurchases.forEach((purchase, index) => {
+     *   console.log(`\n${index + 1}. Purchase #${purchase.id}`);
+     *   console.log(`📅 Date: ${new Date(purchase.createdAt).toLocaleDateString()}`);
+     *   console.log(`💰 Amount: $${purchase.amount} ${purchase.currency}`);
+     *   console.log(`📊 Status: ${purchase.status}`);
+     *
+     *   if (purchase.description) {
+     *     console.log(`📝 Description: ${purchase.description}`);
+     *   }
+     *
+     *   if (purchase.tokensReceived) {
+     *     console.log(`🪙  Tokens received: ${purchase.tokensReceived}`);
+     *   }
+     *
+     *   if (purchase.paymentMethod) {
+     *     console.log(`💳 Payment method: ${purchase.paymentMethod}`);
+     *   }
+     *
+     *   if (purchase.receiptEmail) {
+     *     console.log(`📧 Receipt sent to: ${purchase.receiptEmail}`);
+     *   }
+     * });
+     *
+     * // Calculate purchase statistics
+     * const successfulPurchases = userPurchases.filter(p => p.status === 'COMPLETED');
+     * const totalSpent = successfulPurchases.reduce((sum, p) => sum + p.amount, 0);
+     * const totalTokens = successfulPurchases.reduce((sum, p) => sum + (p.tokensReceived || 0), 0);
+     *
+     * console.log('\n📊 Purchase Statistics:');
+     * console.log(`Total purchases: ${userPurchases.length}`);
+     * console.log(`Successful purchases: ${successfulPurchases.length}`);
+     * console.log(`Total spent: $${totalSpent.toFixed(2)}`);
+     * console.log(`Total tokens acquired: ${totalTokens}`);
+     *
+     * if (totalTokens > 0) {
+     *   const avgCostPerToken = totalSpent / totalTokens;
+     *   console.log(`Average cost per token: $${avgCostPerToken.toFixed(4)}`);
+     * }
+     * ```
+     *
+     * @example Purchase Analysis
+     * ```typescript
+     * const purchases = await sdk.purchases.getAllUserPurchases();
+     *
+     * // Analyze by time period
+     * const last30Days = purchases.filter(p =>
+     *   new Date(p.createdAt) > new Date(Date.now() - 30 * 24 * 60 * 60 * 1000)
+     * );
+     *
+     * const last6Months = purchases.filter(p =>
+     *   new Date(p.createdAt) > new Date(Date.now() - 180 * 24 * 60 * 60 * 1000)
+     * );
+     *
+     * console.log('📅 Purchase Timeline:');
+     * console.log(`Last 30 days: ${last30Days.length} purchases`);
+     * console.log(`Last 6 months: ${last6Months.length} purchases`);
+     *
+     * // Analyze by status
+     * const statusCounts = purchases.reduce((acc, p) => {
+     *   acc[p.status] = (acc[p.status] || 0) + 1;
+     *   return acc;
+     * }, {});
+     *
+     * console.log('\n📊 By status:');
+     * Object.entries(statusCounts).forEach(([status, count]) => {
+     *   console.log(`${status}: ${count} purchases`);
+     * });
+     *
+     * // Find largest and most recent purchases
+     * const largestPurchase = purchases.reduce((max, current) =>
+     *   current.amount > max.amount ? current : max, purchases[0]
+     * );
+     *
+     * const mostRecent = purchases.reduce((newest, current) =>
+     *   new Date(current.createdAt) > new Date(newest.createdAt) ? current : newest, purchases[0]
+     * );
+     *
+     * if (largestPurchase) {
+     *   console.log(`\n💎 Largest purchase: $${largestPurchase.amount} on ${new Date(largestPurchase.createdAt).toLocaleDateString()}`);
+     * }
+     *
+     * if (mostRecent) {
+     *   console.log(`⏰ Most recent: $${mostRecent.amount} on ${new Date(mostRecent.createdAt).toLocaleDateString()}`);
+     * }
+     * ```
      */
     getAllUserPurchases(): Promise<PurchaseDTO[]>;
     /**
-     * Get the full purchase SDK for advanced operations
+     * Get the full purchase service for advanced operations
+     *
+     * Provides access to the complete PaymentService instance for advanced purchase
+     * operations, payment processor integrations, subscription management, and
+     * operations not covered by the high-level manager methods.
+     *
+     * @returns PaymentService instance with full API access
+     *
+     * @example Advanced Operations
+     * ```typescript
+     * const paymentService = sdk.purchases.getPurchaseService();
+     *
+     * // Access advanced payment analytics
+     * const analytics = await paymentService.getPaymentAnalytics();
+     *
+     * // Access subscription management
+     * const subscriptions = await paymentService.getUserSubscriptions();
+     *
+     * // Access payment method management
+     * const paymentMethods = await paymentService.getUserPaymentMethods();
+     *
+     * // Access payment API directly
+     * const paymentApi = paymentService.api;
+     *
+     * // Use advanced purchase validation
+     * const validation = await paymentService.validatePurchaseEligibility('token-package-123');
      *
-     * @returns PaymentSDK instance
+     * // Access payment processor webhooks
+     * const webhookHandler = paymentService.createWebhookHandler();
+     * ```
      */
-    getPurchaseSDK(): PaymentSDK;
+    getPurchaseService(): PaymentService;
 }
 //# sourceMappingURL=purchase-manager.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"purchase-manager.d.ts","sourceRoot":"","sources":["../../src/managers/purchase-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAoB,UAAU,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,KAAK,EACV,gBAAgB,EAEhB,WAAW,EAIX,gBAAgB,EACjB,MAAM,iDAAiD,CAAC;AAEzD;;;;;GAKG;AACH,qBAAa,eAAe;IAGd,OAAO,CAAC,SAAS;IAF7B,OAAO,CAAC,UAAU,CAAa;gBAEX,SAAS,EAAE,aAAa;IAI5C;;;;;;;;OAQG;IACG,mBAAmB,CACvB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,gBAAgB,CAAC;IAI5B;;;;;OAKG;IACG,uBAAuB,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAI5E;;;;OAIG;IACG,mBAAmB,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAInD;;;;OAIG;IACH,cAAc,IAAI,UAAU;CAG7B"}
+{"version":3,"file":"purchase-manager.d.ts","sourceRoot":"","sources":["../../src/managers/purchase-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAc,cAAc,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,KAAK,EACV,gBAAgB,EAEhB,WAAW,EAIX,gBAAgB,EACjB,MAAM,iDAAiD,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,qBAAa,eAAe;IAGd,OAAO,CAAC,SAAS;IAF7B,OAAO,CAAC,cAAc,CAAiB;gBAEnB,SAAS,EAAE,aAAa;IAK5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmFG;IACG,mBAAmB,CACvB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,gBAAgB,CAAC;IAI5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8EG;IACG,uBAAuB,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAI5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoGG;IACG,mBAAmB,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAInD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,kBAAkB,IAAI,cAAc;CAGrC"}