@explorins/pers-sdk-react-native 2.1.12 → 2.1.13

package/dist/index.js

@@ -2882,12 +2882,21 @@ exports.SignedUrlType = void 0;
  * Token Validity Type Enum
  *
  * Defines how token expiry is calculated:
+ *
+ * Static types (computed at issuance from template):
  * - FIXED_DATE: Uses expiryDate directly as absolute expiration
  * - DAYS_FROM_ISSUANCE: Computes expiry as issuance date + validityDuration days
  * - HOURS_FROM_ISSUANCE: Computes expiry as issuance date + validityDuration hours
  * - MONTHS_FROM_ISSUANCE: Computes expiry as issuance date + validityDuration months
  * - END_OF_MONTH: Token expires at end of the month when issued
  * - END_OF_YEAR: Token expires at end of the year when issued
+ *
+ * Trigger-based types (computed from runtime context):
+ * - TRIGGER_DATE: Uses date from context.validityDate (e.g., hotel check-out date)
+ * - TRIGGER_DATE_RANGE: Uses context.validityEndDate directly (for explicit start/end scenarios)
+ * - DAYS_FROM_TRIGGER: Computes expiry as context.validityDate + duration days
+ *                      Duration from context.validityDuration OR template.validityDuration
+ * - HOURS_FROM_TRIGGER: Same as above but hours
  */
 const TokenValidityTypes = {
     FIXED_DATE: 'fixed_date',
@@ -2896,6 +2905,11 @@ const TokenValidityTypes = {
     MONTHS_FROM_ISSUANCE: 'months_from_issuance',
     END_OF_MONTH: 'end_of_month',
     END_OF_YEAR: 'end_of_year',
+    // Trigger-based types - require context at runtime
+    TRIGGER_DATE: 'trigger_date',
+    TRIGGER_DATE_RANGE: 'trigger_date_range',
+    DAYS_FROM_TRIGGER: 'days_from_trigger',
+    HOURS_FROM_TRIGGER: 'hours_from_trigger',
 };
 const TOKEN_VALIDITY_TYPE_VALUES = Object.values(TokenValidityTypes);
 
@@ -6516,12 +6530,11 @@ class RedemptionApi {
      * - USER: Direct user redemption processing
      * - ADMIN: Can process redemptions for any account type
      * - BUSINESS: Process redemptions for customers
+     *
+     * @param request - Redemption request with optional context for dynamic NFT generation
      */
-    async redeemRedemption(redemptionId) {
-        const body = {
-            redemptionId: redemptionId,
-        };
-        return this.apiClient.post(this.basePath + '/redeems', body);
+    async redeemRedemption(request) {
+        return this.apiClient.post(this.basePath + '/redeems', request);
     }
     // ==========================================
     // REDEMPTION REDEEMS QUERIES (NEW ENDPOINTS)
@@ -6531,10 +6544,10 @@ class RedemptionApi {
      *
      * Role-based access with unified filtering:
      * - Users: See only their own redeems (userId/businessId filters ignored)
-     * - Admins: Can filter by userId, businessId, or redemptionId
+     * - Admins: Can filter by userId, businessId, redemptionId, or status
      *
-     * @param filters - Filter and pagination options (redemptionId, userId, businessId, myRedeems, page, limit, sortBy, sortOrder)
-     * @param include - Optional relations to include (redemption, user, business)
+     * @param filters - Filter and pagination options (redemptionId, userId, businessId, status, myRedeems, page, limit, sortBy, sortOrder)
+     * @param include - Optional relations to include (redemption, user, business, transactions)
      * @returns Paginated response with redemption redeems
      */
     async getRedemptionRedeems(filters, include) {
@@ -6546,6 +6559,9 @@ class RedemptionApi {
             if (filters?.redemptionId) {
                 params.append('redemptionId', filters.redemptionId);
             }
+            if (filters?.status) {
+                params.append('status', filters.status);
+            }
             // Add include parameter
             if (include && include.length > 0) {
                 include.forEach(relation => params.append('include', relation));
@@ -6560,6 +6576,8 @@ class RedemptionApi {
             params.append('userId', filters.userId);
         if (filters?.businessId)
             params.append('businessId', filters.businessId);
+        if (filters?.status)
+            params.append('status', filters.status);
         // Add include parameter
         if (include && include.length > 0) {
             include.forEach(relation => params.append('include', relation));
@@ -6588,13 +6606,13 @@ class RedemptionApi {
      * UNIFIED: Get user redemption history
      *
      * Uses convenience endpoint /redemption-redeems/me with optional filtering
-     * @param redemptionId - Optional filter by specific redemption
+     * @param filters - Optional filters (redemptionId, status)
      * @param options - Pagination options (page, limit, sortBy, sortOrder)
-     * @param include - Optional relations to include (redemption, user, business)
+     * @param include - Optional relations to include (redemption, user, business, transactions)
      * @returns Paginated response with user's redemption redeems
      */
-    async getUserRedeems(redemptionId, options, include) {
-        return this.getRedemptionRedeems({ myRedeems: true, redemptionId, ...options }, include);
+    async getUserRedeems(filters, options, include) {
+        return this.getRedemptionRedeems({ myRedeems: true, ...filters, ...options }, include);
     }
     // ==========================================
     // ADMIN OPERATIONS (Tenant Admin JWT)
@@ -6720,26 +6738,33 @@ class RedemptionService {
     // AUTHENTICATED OPERATIONS
     // ==========================================
     /**
-     * AUTH: Redeem a redemption
+     * AUTH: Redeem a redemption with optional dynamic context
+     *
+     * @param request - Redemption request (can be just redemptionId string or full request with context)
      */
-    async redeemRedemption(redemptionId) {
-        return this.redemptionApi.redeemRedemption(redemptionId);
+    async redeemRedemption(request) {
+        // Support both simple string and full request object
+        const requestBody = typeof request === 'string'
+            ? { redemptionId: request }
+            : request;
+        return this.redemptionApi.redeemRedemption(requestBody);
     }
     /**
      * UNIFIED: Get redemption redeems with filtering and pagination
-     * @param filters - Filter options
-     * @param include - Optional relations to include (redemption, user, business)
+     * @param filters - Filter options (redemptionId, userId, businessId, status, myRedeems)
+     * @param include - Optional relations to include (redemption, user, business, transactions)
      */
     async getRedemptionRedeems(filters, include) {
         return this.redemptionApi.getRedemptionRedeems(filters, include);
     }
     /**
-     * Convenience: Get user redemptions with pagination
+     * Convenience: Get user redemptions with pagination and filtering
+     * @param filters - Optional filters (redemptionId, status)
      * @param options - Pagination options
-     * @param include - Optional relations to include (redemption, user, business)
+     * @param include - Optional relations to include (redemption, user, business, transactions)
      */
-    async getUserRedeems(options, include) {
-        return this.redemptionApi.getUserRedeems(undefined, options, include);
+    async getUserRedeems(filters, options, include) {
+        return this.redemptionApi.getUserRedeems(filters, options, include);
     }
     // ==========================================
     // ADMIN OPERATIONS
@@ -7281,7 +7306,7 @@ function buildAccountSelector(data) {
  * 🎯 Build a MINT transaction request (admin/business endpoint)
  * Creates tokens and assigns them to a recipient account
  *
- * @example
+ * @example Basic Mint
  * ```typescript
  * const request = buildMintRequest({
  *   amount: 100,
@@ -7292,6 +7317,27 @@ function buildAccountSelector(data) {
  *   engagedBusinessId: 'business-456' // optional: for tracking which business triggered the mint
  * });
  * ```
+ *
+ * @example ERC721 Mint with Dynamic Context
+ * ```typescript
+ * const request = buildMintRequest({
+ *   amount: 1,
+ *   contractAddress: '0x...',
+ *   contractTokenId: '123', // TokenMetadata ID
+ *   chainId: 137,
+ *   recipientAccountId: 'user-123',
+ *   recipientAccountType: AccountOwnerType.USER,
+ *   context: {
+ *     // Validity control
+ *     validityDate: '2026-04-15T14:00:00Z',
+ *     validityEndDate: '2026-04-20T11:00:00Z',
+ *     // AI prompt placeholders (available as {{context.xxx}})
+ *     guestName: 'John Doe',
+ *     roomNumber: '305',
+ *     awardReason: 'Employee of the Month'
+ *   }
+ * });
+ * ```
  */
 function buildMintRequest(data) {
     return {
@@ -7305,7 +7351,8 @@ function buildMintRequest(data) {
                 accountAddress: data.recipientAccountAddress
             })
         },
-        ...(data.engagedBusinessId && { engagedBusinessId: data.engagedBusinessId })
+        ...(data.engagedBusinessId && { engagedBusinessId: data.engagedBusinessId }),
+        ...(data.context && { context: data.context })
     };
 }
 /**
@@ -12987,7 +13034,12 @@ class RedemptionManager {
      * redemption confirmation details. Creates a permanent redemption record
      * and may generate voucher codes or instructions.
      *
+     * Supports dynamic context for personalized NFT generation when the redemption
+     * issues ERC721 tokens. Context can include validity dates, AI prompt placeholders,
+     * and custom metadata.
+     *
      * @param redemptionId - ID of the redemption offer to redeem
+     * @param context - Optional dynamic context for NFT personalization (validity dates, AI prompts)
      * @returns Promise resolving to redemption result with confirmation details
      * @throws {PersApiError} When redemption is not available or user lacks required tokens
      *
@@ -13035,6 +13087,30 @@ class RedemptionManager {
      * }
      * ```
      *
+     * @example Redemption with Dynamic Context (Personalized NFT)
+     * ```typescript
+     * // Event ticket with dynamic validity and personalization
+     * const result = await sdk.redemptions.redeem('event-ticket-123', {
+     *   // Validity - token valid for event duration + 2 hours
+     *   validityDate: new Date().toISOString(),
+     *   validityDuration: 8,  // 8 hours
+     *
+     *   // AI prompt context - available as {{context.xxx}} in prompts
+     *   attendeeName: 'John Doe',
+     *   ticketTier: 'VIP',
+     *   seatSection: 'A12',
+     * });
+     *
+     * // Hotel stay NFT with check-in/check-out dates
+     * const hotelResult = await sdk.redemptions.redeem('hotel-nft-456', {
+     *   validityDate: '2026-04-15T14:00:00Z',      // Check-in
+     *   validityEndDate: '2026-04-20T11:00:00Z',   // Check-out
+     *   guestName: 'Jane Smith',
+     *   roomNumber: '305',
+     *   roomType: 'Suite',
+     * });
+     * ```
+     *
      * @example Redemption with Pre-Validation
      * ```typescript
      * // Get offer details first
@@ -13058,13 +13134,16 @@ class RedemptionManager {
      * }
      * ```
      */
-    async redeem(redemptionId) {
-        const result = await this.redemptionService.redeemRedemption(redemptionId);
+    async redeem(redemptionId, context) {
+        const request = context
+            ? { redemptionId, context }
+            : { redemptionId };
+        const result = await this.redemptionService.redeemRedemption(request);
         this.events?.emitSuccess({
             domain: 'redemption',
             type: 'redeem_success',
             userMessage: 'Reward redeemed successfully',
-            details: { redemptionId }
+            details: { redemptionId, hasContext: !!context }
         });
         return result;
     }
@@ -13127,9 +13206,19 @@ class RedemptionManager {
      *   console.log(`${type}: ${count} redemptions`);
      * });
      * ```
+     *
+     * @example Filter by Status
+     * ```typescript
+     * import { ProcessRecordStatus } from '@explorins/pers-sdk';
+     *
+     * // Get only completed redemptions
+     * const { data: completed } = await sdk.redemptions.getUserRedemptions(
+     *   { status: ProcessRecordStatus.COMPLETED }
+     * );
+     * ```
      */
-    async getUserRedemptions(options, include) {
-        return this.redemptionService.getUserRedeems(options, include);
+    async getUserRedemptions(filters, options, include) {
+        return this.redemptionService.getUserRedeems(filters, options, include);
     }
     /**
      * Admin: Get all redemption redeems with filtering and enriched data
@@ -40125,10 +40214,17 @@ const useWeb3 = () => {
  * **Basic Usage:**
  * ```typescript
  * import { useTokenBalances, useTokens, usePersSDK } from '@explorins/pers-sdk-react-native';
+ * import { useState, useEffect } from 'react';
  *
  * function TokenBalancesScreen() {
  *   const { user } = usePersSDK();
- *   const { availableTokens } = useTokens();
+ *   const { getTokens } = useTokens();
+ *   const [availableTokens, setAvailableTokens] = useState([]);
+ *
+ *   // Load tokens on mount
+ *   useEffect(() => {
+ *     getTokens().then(result => setAvailableTokens(result.data));
+ *   }, []);
  *
  *   // App explicitly selects which wallet to use
  *   const walletAddress = user?.wallets?.[0]?.address;
@@ -41408,6 +41504,63 @@ const useCampaigns = () => {
             throw error;
         }
     }, [sdk, isInitialized]);
+    /**
+     * Claim a campaign reward with optional dynamic context
+     *
+     * Triggers a campaign claim for the authenticated user. The campaign must be active
+     * and the user must meet all eligibility requirements. Supports dynamic context for
+     * personalized NFT generation when the campaign issues ERC721 tokens.
+     *
+     * @param request - Campaign claim request with optional context
+     * @param request.campaignId - ID of the campaign to claim (optional if using triggerSourceId)
+     * @param request.triggerSourceId - ID of trigger source (QR, NFC, etc.)
+     * @param request.context - Dynamic context for NFT personalization
+     * @param request.metadata - Additional metadata for the claim
+     * @param request.latitude - User's latitude for geo-validated claims
+     * @param request.longitude - User's longitude for geo-validated claims
+     * @returns Promise resolving to campaign claim result
+     *
+     * @example Basic campaign claim
+     * ```typescript
+     * const claim = await claimCampaign({
+     *   triggerSourceId: 'qr-code-123',
+     * });
+     * ```
+     *
+     * @example Campaign claim with dynamic context (personalized NFT)
+     * ```typescript
+     * import { DynamicContext } from '@explorins/pers-sdk-react-native';
+     *
+     * const context: DynamicContext = {
+     *   // Validity - token valid for 30 days
+     *   validityDate: new Date().toISOString(),
+     *   validityDuration: 30,
+     *
+     *   // AI prompt context - available as {{context.xxx}} in prompts
+     *   visitorName: 'John Doe',
+     *   visitLocation: 'Grand Hotel Lobby',
+     *   membershipTier: 'Gold',
+     * };
+     *
+     * const claim = await claimCampaign({
+     *   triggerSourceId: 'hotel-checkin-qr',
+     *   context,
+     * });
+     * ```
+     *
+     * @example Geo-validated claim with context
+     * ```typescript
+     * const claim = await claimCampaign({
+     *   triggerSourceId: 'museum-entrance-nfc',
+     *   latitude: 48.8606,
+     *   longitude: 2.3376,
+     *   context: {
+     *     visitorType: 'Adult',
+     *     ticketCategory: 'General Admission',
+     *   }
+     * });
+     * ```
+     */
     const claimCampaign = react.useCallback(async (request) => {
         if (!isInitialized || !sdk) {
             throw new Error('SDK not initialized. Call initialize() first.');
@@ -41435,7 +41588,7 @@ const useCampaigns = () => {
      * // Get user's claims with campaign details
      * const { data: claims } = await getUserClaims({ include: ['campaign', 'business'] });
      * claims.forEach(claim => {
-     *   console.log('Campaign:', claim.included?.campaign?.title);
+     *   console.log('Campaign:', claim.included?.campaign?.name);
      * });
      *
      * // With pagination
@@ -41692,27 +41845,32 @@ const useRedemptions = () => {
         }
     }, [sdk, isInitialized]);
     /**
-     * Get user's redemption history with optional pagination and include relations
+     * Get user's redemption history with optional filters, pagination and include relations
      *
+     * @param filters - Optional filters (redemptionId, status)
      * @param options - Pagination options (page, limit, sortBy, sortOrder)
-     * @param include - Relations to include: 'redemption', 'user', 'business'
+     * @param include - Relations to include: 'redemption', 'user', 'business', 'transactions'
      * @returns Promise resolving to paginated redemption history
      *
      * @example
      * ```typescript
      * // Get first page of user redemptions
-     * const { data: redeems, pagination } = await getUserRedemptions({ page: 1, limit: 10 });
+     * const { data: redeems, pagination } = await getUserRedemptions({}, { page: 1, limit: 10 });
      * console.log(`Page ${pagination.page} of ${pagination.pages}`);
      *
+     * // Get only completed redemptions
+     * import { ProcessRecordStatus } from '@explorins/pers-shared';
+     * const { data: completed } = await getUserRedemptions({ status: ProcessRecordStatus.COMPLETED });
+     *
      * // Get user redemptions with full redemption details
-     * const { data: redeems } = await getUserRedemptions({}, ['redemption', 'business']);
+     * const { data: redeems } = await getUserRedemptions({}, {}, ['redemption', 'business']);
      * redeems.forEach(redeem => {
-     *   console.log('Redemption:', redeem.included?.redemption?.title);
+     *   console.log('Redemption:', redeem.included?.redemption?.name);
      *   console.log('Business:', redeem.included?.business?.displayName);
      * });
      * ```
      */
-    const getUserRedemptions = react.useCallback(async (options, include) => {
+    const getUserRedemptions = react.useCallback(async (filters, options, include) => {
         if (!isInitialized || !sdk) {
             throw new Error('SDK not initialized. Call initialize() first.');
         }
@@ -41721,7 +41879,7 @@ const useRedemptions = () => {
             return { data: [], pagination: { page: 1, limit: 0, total: 0, pages: 0, hasNext: false, hasPrev: false } };
         }
         try {
-            const result = await sdk.redemptions.getUserRedemptions(options, include);
+            const result = await sdk.redemptions.getUserRedemptions(filters, options, include);
             return result;
         }
         catch (error) {
@@ -41729,7 +41887,54 @@ const useRedemptions = () => {
             throw error;
         }
     }, [sdk, isInitialized, isAuthenticated]);
-    const redeem = react.useCallback(async (redemptionId, onStatusUpdate) => {
+    /**
+     * Redeem a redemption offer with optional dynamic context
+     *
+     * Supports dynamic context for personalized NFT generation when the redemption
+     * issues ERC721 tokens. Context can include validity dates, AI prompt placeholders,
+     * and custom metadata.
+     *
+     * @param redemptionId - ID of the redemption to redeem
+     * @param options - Optional settings
+     * @param options.context - Dynamic context for NFT personalization (validity dates, AI prompts)
+     * @param options.onStatusUpdate - Callback for transaction signing status updates
+     * @returns Promise resolving to redemption result
+     *
+     * @example Basic redemption
+     * ```typescript
+     * const result = await redeem('redemption-123');
+     * ```
+     *
+     * @example Redemption with dynamic context (personalized NFT)
+     * ```typescript
+     * const result = await redeem('event-ticket-123', {
+     *   context: {
+     *     // Validity - token valid for event duration
+     *     validityDate: new Date().toISOString(),
+     *     validityDuration: 8,  // 8 hours
+     *
+     *     // AI prompt context - available as {{context.xxx}} in prompts
+     *     attendeeName: 'John Doe',
+     *     ticketTier: 'VIP',
+     *     seatSection: 'A12',
+     *   }
+     * });
+     * ```
+     *
+     * @example Hotel stay NFT with check-in/check-out dates
+     * ```typescript
+     * const result = await redeem('hotel-nft-456', {
+     *   context: {
+     *     validityDate: '2026-04-15T14:00:00Z',      // Check-in
+     *     validityEndDate: '2026-04-20T11:00:00Z',   // Check-out
+     *     guestName: 'Jane Smith',
+     *     roomNumber: '305',
+     *     roomType: 'Suite',
+     *   }
+     * });
+     * ```
+     */
+    const redeem = react.useCallback(async (redemptionId, options) => {
         if (!isInitialized || !sdk) {
             throw new Error('SDK not initialized. Call initialize() first.');
         }
@@ -41737,11 +41942,11 @@ const useRedemptions = () => {
             throw new Error('SDK not authenticated. redeem requires authentication.');
         }
         try {
-            const result = await sdk.redemptions.redeem(redemptionId);
+            const result = await sdk.redemptions.redeem(redemptionId, options?.context);
             const txToken = result.senderTransaction?.actionable?.authToken;
             if (txToken && isSignerAvailable) {
                 try {
-                    const signingResult = await signAndSubmitTransactionWithJWT(txToken, onStatusUpdate);
+                    const signingResult = await signAndSubmitTransactionWithJWT(txToken, options?.onStatusUpdate);
                     if (signingResult.success) {
                         // Return enhanced result with signing information
                         return {