@explorins/pers-sdk-react-native 2.1.12 → 2.1.14-beta.0

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);
 
@@ -5924,6 +5938,8 @@ class CampaignApi {
             params.push(`tag=${encodeURIComponent(options.tag)}`);
         if (options?.businessId)
             params.push(`businessId=${encodeURIComponent(options.businessId)}`);
+        if (options?.search)
+            params.push(`search=${encodeURIComponent(options.search)}`);
         if (options?.sortBy)
             params.push(`sortBy=${options.sortBy}`);
         if (options?.sortOrder)
@@ -6290,7 +6306,9 @@ class CampaignService {
     /**
      * Get campaigns with pagination support
      * Intelligent access: Public gets active only, Business gets own campaigns, Admin gets all
-     * @param options.active - Filter by active status
+     * @param options.active - Filter by active status (Admin only)
+     * @param options.tag - Filter by tag
+     * @param options.search - Free text search across name, description, and tags (case-insensitive)
      * @param options.businessId - Filter by business engagement
      * @param options.page - Page number (1-based, default: 1)
      * @param options.limit - Items per page (default: 50)
@@ -6466,15 +6484,23 @@ class RedemptionApi {
      * - Public users: Get active redemptions only
      * - Admin users: Get all redemptions with optional filtering
      *
-     * @param options - Filter and pagination options (active, adminAccess, page, limit, sortBy, sortOrder)
+     * @param options - Filter and pagination options (active, search, adminAccess, page, limit, sortBy, sortOrder)
      * @returns Paginated response with redemptions
      */
     async getRedemptions(options) {
-        const params = buildPaginationParams(options);
-        if (options?.active !== undefined) {
-            params.append('active', String(options.active));
-        }
-        const response = await this.apiClient.get(`${this.basePath}?${params.toString()}`);
+        const params = [];
+        // Always include pagination params to ensure paginated response
+        params.push(`page=${options?.page || 1}`);
+        params.push(`limit=${options?.limit || 50}`);
+        if (options?.active !== undefined)
+            params.push(`active=${options.active}`);
+        if (options?.search)
+            params.push(`search=${encodeURIComponent(options.search)}`);
+        if (options?.sortBy)
+            params.push(`sortBy=${options.sortBy}`);
+        if (options?.sortOrder)
+            params.push(`sortOrder=${options.sortOrder}`);
+        const response = await this.apiClient.get(`${this.basePath}?${params.join('&')}`);
         return normalizeToPaginated(response);
     }
     /**
@@ -6516,12 +6542,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 +6556,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 +6571,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 +6588,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 +6618,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)
@@ -6699,7 +6729,12 @@ class RedemptionService {
     /**
      * UNIFIED: Get redemptions with intelligent access control and pagination
      * @param options.active - Filter by active status
+     * @param options.search - Free text search across name, description, tags (case-insensitive)
      * @param options.adminAccess - Force admin access
+     * @param options.page - Page number (1-indexed)
+     * @param options.limit - Results per page
+     * @param options.sortBy - Field to sort by ('name' | 'createdAt')
+     * @param options.sortOrder - Sort direction ('ASC' | 'DESC')
      */
     async getRedemptions(options) {
         return this.redemptionApi.getRedemptions(options);
@@ -6720,35 +6755,43 @@ 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
     // ==========================================
     /**
-     * Convenience: Get redemptions as admin
+     * Convenience: Get redemptions as admin with filtering and search
+     * @param options - Filter options (active, search, pagination)
      */
-    async getRedemptionsAsAdmin(active, options) {
-        return this.redemptionApi.getRedemptions({ active, adminAccess: true, ...options });
+    async getRedemptionsAsAdmin(options) {
+        return this.redemptionApi.getRedemptions({ ...options, adminAccess: true });
     }
     /**
      * ADMIN: Create redemption
@@ -7281,7 +7324,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 +7335,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 +7369,8 @@ function buildMintRequest(data) {
                 accountAddress: data.recipientAccountAddress
             })
         },
-        ...(data.engagedBusinessId && { engagedBusinessId: data.engagedBusinessId })
+        ...(data.engagedBusinessId && { engagedBusinessId: data.engagedBusinessId }),
+        ...(data.context && { context: data.context })
     };
 }
 /**
@@ -11843,7 +11908,7 @@ class BusinessManager {
  *
  * // Get specific campaign details
  * const campaign = await sdk.campaigns.getCampaignById('summer-promo-2024');
- * console.log('Campaign:', campaign.title);
+ * console.log('Campaign:', campaign.name);
  *
  * // User claims campaign reward
  * const claim = await sdk.campaigns.claimCampaign({
@@ -11859,7 +11924,7 @@ class BusinessManager {
  *
  * console.log('My Campaign Claims:');
  * userClaims.forEach(claim => {
- *   console.log(`- ${claim.campaign.title}`);
+ *   console.log(`- ${claim.campaign.name}`);
  *   console.log(`  Rewards: ${claim.rewards?.length || 0} tokens`);
  *   console.log(`  Date: ${claim.claimedAt}`);
  * });
@@ -11875,7 +11940,7 @@ class BusinessManager {
  * ```typescript
  * // Admin: Create seasonal campaign
  * const newCampaign = await sdk.campaigns.createCampaign({
- *   title: 'Holiday Rewards',
+ *   name: 'Holiday Rewards',
  *   description: 'Special holiday loyalty bonuses',
  *   startDate: '2024-12-01',
  *   endDate: '2024-12-31',
@@ -11914,7 +11979,7 @@ class CampaignManager {
      *   const campaign = await sdk.campaigns.getCampaignById('summer-promo-2024');
      *
      *   console.log('Campaign Details:');
-     *   console.log('Title:', campaign.title);
+     *   console.log('Name:', campaign.name);
      *   console.log('Description:', campaign.description);
      *   console.log('Active:', campaign.isActive);
      *   console.log('Period:', `${campaign.startDate} to ${campaign.endDate}`);
@@ -12028,7 +12093,7 @@ class CampaignManager {
      * console.log(`Campaign History (${userClaims.length} claims):`);
      *
      * userClaims.forEach((claim, index) => {
-     *   console.log(`\n${index + 1}. ${claim.campaign.title}`);
+     *   console.log(`\n${index + 1}. ${claim.campaign.name}`);
      *   console.log(`   Claimed: ${new Date(claim.claimedAt).toLocaleDateString()}`);
      *   console.log(`   Business: ${claim.business?.displayName || 'N/A'}`);
      *
@@ -12058,7 +12123,7 @@ class CampaignManager {
      * Returns campaigns with pagination metadata for efficient data loading.
      * Intelligent access: Public gets active only, Business gets own campaigns, Admin gets all.
      *
-     * @param options - Pagination and filter options (page, limit, sortBy, sortOrder, active, businessId, include)
+     * @param options - Pagination and filter options (page, limit, sortBy, sortOrder, active, tag, search, businessId, include)
      * @returns Promise resolving to paginated campaigns with metadata
      *
      * @example
@@ -12075,6 +12140,19 @@ class CampaignManager {
      *   limit: 20
      * });
      *
+     * // Search campaigns by name or description
+     * const searchResults = await sdk.campaigns.getCampaigns({
+     *   search: 'summer rewards',
+     *   page: 1,
+     *   limit: 20
+     * });
+     *
+     * // Filter by tag
+     * const taggedCampaigns = await sdk.campaigns.getCampaigns({
+     *   tag: 'seasonal',
+     *   active: true
+     * });
+     *
      * // Get active campaigns sorted by creation date
      * const activeCampaigns = await sdk.campaigns.getCampaigns({
      *   active: true,
@@ -12108,7 +12186,7 @@ class CampaignManager {
      * ```typescript
      * // Admin operation - create seasonal campaign
      * const campaign = await sdk.campaigns.createCampaign({
-     *   title: 'Summer Travel Rewards',
+     *   name: 'Summer Travel Rewards',
      *   description: 'Earn bonus points for summer bookings',
      *   startDate: '2024-06-01T00:00:00Z',
      *   endDate: '2024-08-31T23:59:59Z',
@@ -12117,7 +12195,7 @@ class CampaignManager {
      *   campaignType: 'SEASONAL'
      * });
      *
-     * console.log('Campaign created:', campaign.title);
+     * console.log('Campaign created:', campaign.name);
      * console.log('Campaign ID:', campaign.id);
      *
      * // Set up campaign rewards
@@ -12147,13 +12225,13 @@ class CampaignManager {
      * ```typescript
      * // Admin operation - extend campaign duration
      * const updated = await sdk.campaigns.updateCampaign('summer-2024', {
-     *   title: 'Extended Summer Travel Rewards',
+     *   name: 'Extended Summer Travel Rewards',
      *   description: 'Earn bonus points for summer and early fall bookings',
      *   endDate: '2024-09-30T23:59:59Z',  // Extended end date
      *   isActive: true
      * });
      *
-     * console.log('Campaign updated:', updated.title);
+     * console.log('Campaign updated:', updated.name);
      * console.log('New end date:', updated.endDate);
      * ```
      */
@@ -12618,7 +12696,7 @@ class CampaignManager {
      * console.log(`Total campaigns claimed: ${userClaims.length}`);
      *
      * userClaims.forEach((claim, index) => {
-     *   console.log(`\n${index + 1}. ${claim.campaign.title}`);
+     *   console.log(`\n${index + 1}. ${claim.campaign.name}`);
      *   console.log(`   Date: ${claim.claimedAt}`);
      *   console.log(`   Business: ${claim.business?.displayName || 'Direct'}`);
      *   console.log(`   Rewards: ${claim.rewards?.length || 0} items`);
@@ -12655,8 +12733,8 @@ class CampaignManager {
      *
      * // Analyze claims by campaign
      * const claimsByCampaign = businessClaims.reduce((acc, claim) => {
-     *   const title = claim.campaign.title;
-     *   acc[title] = (acc[title] || 0) + 1;
+     *   const campaignName = claim.campaign.name;
+     *   acc[campaignName] = (acc[campaignName] || 0) + 1;
      *   return acc;
      * }, {});
      *
@@ -12860,6 +12938,7 @@ class RedemptionManager {
      *
      * @param options - Optional filters and pagination:
      *   - `active`: Filter by active status (true/false). Admins only - regular users always see active offers
+     *   - `search`: Free text search across name, description, tags (case-insensitive)
      *   - Pagination options: `page`, `limit`, `sortBy`, `sortOrder`
      * @returns Promise resolving to paginated redemption offers
      *
@@ -12872,9 +12951,9 @@ class RedemptionManager {
      * console.log(`Showing ${offers.length} of ${pagination.total} offers`);
      *
      * offers.forEach(offer => {
-     *   console.log(`\n${offer.title}`);
+     *   console.log(`\n${offer.name}`);
      *   console.log(`${offer.description}`);
-     *   console.log(`Type: ${offer.redemptionType?.name || 'General'}`);
+     *   console.log(`Type: ${offer.type?.name || 'General'}`);
      *
      *   if (offer.tokenUnits?.length) {
      *     console.log('Cost:');
@@ -12897,6 +12976,23 @@ class RedemptionManager {
      * console.log(`\n${affordableOffers.length} offers within your budget`);
      * ```
      *
+     * @example Search Redemptions
+     * ```typescript
+     * // Search by text (matches name, description, tags)
+     * const { data: coffeeOffers } = await sdk.redemptions.getRedemptions({
+     *   search: 'coffee'
+     * });
+     *
+     * console.log(`Found ${coffeeOffers.length} coffee-related offers`);
+     *
+     * // Search with sorting
+     * const { data: sortedResults } = await sdk.redemptions.getRedemptions({
+     *   search: 'discount',
+     *   sortBy: 'name',
+     *   sortOrder: 'ASC'
+     * });
+     * ```
+     *
      * @example Admin - Manage All Redemptions
      * ```typescript
      * // Admins can see all redemptions and filter by status
@@ -12909,14 +13005,11 @@ class RedemptionManager {
      * console.log(`Active offers: ${activeOnly.length}`);
      * console.log(`Inactive offers: ${inactiveOnly.length}`);
      *
-     * // Analyze by type
-     * const offersByType = allRedemptions.reduce((acc, offer) => {
-     *   const type = offer.redemptionType?.name || 'Unspecified';
-     *   acc[type] = (acc[type] || 0) + 1;
-     *   return acc;
-     * }, {});
-     *
-     * console.log('\nBy type:', offersByType);
+     * // Search inactive redemptions
+     * const { data: inactiveVouchers } = await sdk.redemptions.getRedemptions({
+     *   active: false,
+     *   search: 'voucher'
+     * });
      * ```
      *
      * @example Pagination
@@ -12987,7 +13080,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 +13133,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 +13180,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;
     }
@@ -13084,9 +13209,9 @@ class RedemptionManager {
      * console.log(`Redemption History (${userRedemptions.length} of ${pagination.total} items):`);
      *
      * userRedemptions.forEach((redemption, index) => {
-     *   console.log(`\n${index + 1}. ${redemption.redemption.title}`);
+     *   console.log(`\n${index + 1}. ${redemption.redemption.name}`);
      *   console.log(`   Date: ${new Date(redemption.redeemedAt).toLocaleDateString()}`);
-     *   console.log(`   Type: ${redemption.redemption.redemptionType?.name || 'General'}`);
+     *   console.log(`   Type: ${redemption.redemption.type?.name || 'General'}`);
      *
      *   if (redemption.voucherCode) {
      *     console.log(`   Voucher: ${redemption.voucherCode}`);
@@ -13127,9 +13252,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
@@ -13195,7 +13330,7 @@ class RedemptionManager {
      * ```typescript
      * // Admin operation - create discount redemption
      * const newRedemption = await sdk.redemptions.createRedemption({
-     *   title: '20% Off Weekend Stay',
+     *   name: '20% Off Weekend Stay',
      *   description: 'Get 20% off your next weekend booking at partner hotels',
      *   redemptionTypeId: 'discount-type-id',
      *   isActive: true,
@@ -13204,7 +13339,7 @@ class RedemptionManager {
      *   validUntil: '2024-08-31T23:59:59Z'
      * });
      *
-     * console.log('New redemption created:', newRedemption.title);
+     * console.log('New redemption created:', newRedemption.name);
      * console.log('Redemption ID:', newRedemption.id);
      *
      * // Set redemption cost
@@ -13236,13 +13371,13 @@ class RedemptionManager {
      * ```typescript
      * // Admin operation - update redemption details
      * const updated = await sdk.redemptions.updateRedemption('weekend-discount', {
-     *   title: '25% Off Weekend Stay - Extended!',
+     *   name: '25% Off Weekend Stay - Extended!',
      *   description: 'Enhanced discount - now 25% off weekend bookings',
      *   availableQuantity: 150,  // Increased availability
      *   validUntil: '2024-09-30T23:59:59Z'  // Extended validity
      * });
      *
-     * console.log('Redemption updated:', updated.title);
+     * console.log('Redemption updated:', updated.name);
      * console.log('New quantity available:', updated.availableQuantity);
      * ```
      */
@@ -17541,7 +17676,9 @@ class PersSDK {
             }
         }
         try {
-            // Fetch user data to validate tokens and restore session
+            // Ensure token is valid (refresh if expired) before fetching user
+            await this.auth.ensureValidToken();
+            // Fetch user data to restore session
             const userData = await this.auth.getCurrentUser();
             // Emit event through proper event emitter
             this._events.emitSuccess({
@@ -18401,21 +18538,45 @@ function createReactNativeAuthProvider(projectKey, config = {}) {
     });
 }
 
-// Conditionally require quick-crypto for Native platforms only
-let crypto$1;
-if (reactNative.Platform.OS !== 'web') {
+// Lazy-loaded crypto module - initialized on first use to avoid native module timing issues
+let _crypto = null;
+let _cryptoInitialized = false;
+/**
+ * Lazily load the crypto module.
+ *
+ * Supports customer pre-initialization via global.__QuickCrypto for environments
+ * where native module timing is unpredictable (e.g., certain React Native setups).
+ *
+ * @returns The crypto module or null if unavailable
+ */
+function getCrypto() {
+    if (_cryptoInitialized) {
+        return _crypto;
+    }
+    _cryptoInitialized = true;
+    if (reactNative.Platform.OS === 'web') {
+        // On Web, we shouldn't be using this provider (Core SDK has WebDPoPProvider)
+        _crypto = {
+            generateKeyPair: () => { throw new Error('ReactNativeDPoPProvider not supported on Web'); },
+            randomUUID: () => globalThis.crypto?.randomUUID?.() || `${Date.now()}-${Math.random()}`
+        };
+        return _crypto;
+    }
+    // Check for customer pre-initialized global (for native module timing issues)
+    if (typeof global !== 'undefined' && global.__QuickCrypto) {
+        _crypto = global.__QuickCrypto;
+        return _crypto;
+    }
+    // Standard lazy load
     try {
-        crypto$1 = require('react-native-quick-crypto').default || require('react-native-quick-crypto');
+        _crypto = require('react-native-quick-crypto').default || require('react-native-quick-crypto');
     }
     catch (e) {
-        console.warn('ReactNativeDPoPProvider: Failed to load react-native-quick-crypto', e);
+        console.warn('ReactNativeDPoPProvider: Failed to load react-native-quick-crypto.', e);
+        console.warn('Tip: If you encounter timing issues, pre-initialize in index.js: global.__QuickCrypto = require("react-native-quick-crypto")');
+        _crypto = null;
     }
-}
-else {
-    // on Web, we shouldn't be using this provider anyway (Core SDK has WebDPoPProvider)
-    crypto$1 = {
-        generateKeyPair: () => { throw new Error('ReactNativeDPoPProvider not supported on Web'); }
-    };
+    return _crypto;
 }
 class ReactNativeDPoPProvider {
     /**
@@ -18425,13 +18586,17 @@ class ReactNativeDPoPProvider {
      * Falls back to Node.js crypto API on iOS if needed.
      */
     async generateKeyPair(options) {
+        const crypto = getCrypto();
+        if (!crypto) {
+            throw new Error('Crypto module not available. Install react-native-quick-crypto or pre-initialize global.__QuickCrypto');
+        }
         // Try WebCrypto API first (works on both iOS and Android)
-        if (crypto$1.subtle) {
+        if (crypto.subtle) {
             try {
-                const keyPair = await crypto$1.subtle.generateKey({ name: 'ECDSA', namedCurve: 'P-256' }, true, // extractable - required for JWK export
+                const keyPair = await crypto.subtle.generateKey({ name: 'ECDSA', namedCurve: 'P-256' }, true, // extractable - required for JWK export
                 ['sign', 'verify']);
-                const publicKeyJwk = await crypto$1.subtle.exportKey('jwk', keyPair.publicKey);
-                const privateKeyJwk = await crypto$1.subtle.exportKey('jwk', keyPair.privateKey);
+                const publicKeyJwk = await crypto.subtle.exportKey('jwk', keyPair.publicKey);
+                const privateKeyJwk = await crypto.subtle.exportKey('jwk', keyPair.privateKey);
                 return {
                     publicKey: publicKeyJwk,
                     privateKey: privateKeyJwk
@@ -18443,7 +18608,7 @@ class ReactNativeDPoPProvider {
         }
         // Fallback: Node.js crypto API (works on iOS)
         return new Promise((resolve, reject) => {
-            crypto$1.generateKeyPair('ec', { namedCurve: 'P-256' }, (err, publicKey, privateKey) => {
+            crypto.generateKeyPair('ec', { namedCurve: 'P-256' }, (err, publicKey, privateKey) => {
                 if (err)
                     return reject(err);
                 try {
@@ -18458,6 +18623,10 @@ class ReactNativeDPoPProvider {
         });
     }
     async signProof(payload, keyPair) {
+        const crypto = getCrypto();
+        if (!crypto) {
+            throw new Error('Crypto module not available for signing');
+        }
         // 1. Construct Header
         const header = {
             typ: 'dpop+jwt',
@@ -18468,17 +18637,17 @@ class ReactNativeDPoPProvider {
         const finalPayload = {
             ...payload,
             iat: payload.iat || Math.floor(Date.now() / 1000),
-            jti: payload.jti || crypto$1.randomUUID()
+            jti: payload.jti || (crypto.randomUUID?.() || `${Date.now()}-${Math.random()}`)
         };
         // 3. Encode
         const b64Header = this.base64Url(JSON.stringify(header));
         const b64Payload = this.base64Url(JSON.stringify(finalPayload));
         const signingInput = `${b64Header}.${b64Payload}`;
         // 4. Sign - try WebCrypto first, fallback to Node.js crypto
-        if (crypto$1.subtle) {
+        if (crypto.subtle) {
             try {
-                const privateKey = await crypto$1.subtle.importKey('jwk', keyPair.privateKey, { name: 'ECDSA', namedCurve: 'P-256' }, false, ['sign']);
-                const signatureBuffer = await crypto$1.subtle.sign({ name: 'ECDSA', hash: 'SHA-256' }, privateKey, buffer.Buffer.from(signingInput));
+                const privateKey = await crypto.subtle.importKey('jwk', keyPair.privateKey, { name: 'ECDSA', namedCurve: 'P-256' }, false, ['sign']);
+                const signatureBuffer = await crypto.subtle.sign({ name: 'ECDSA', hash: 'SHA-256' }, privateKey, buffer.Buffer.from(signingInput));
                 // WebCrypto returns signature in IEEE P1363 format (r || s), which is what we need for JWT
                 return `${signingInput}.${this.base64UrlBuffer(buffer.Buffer.from(signatureBuffer))}`;
             }
@@ -18487,24 +18656,28 @@ class ReactNativeDPoPProvider {
             }
         }
         // Fallback: Node.js crypto API
-        const sign = crypto$1.createSign('SHA256');
+        const sign = crypto.createSign('SHA256');
         sign.update(signingInput);
-        const privateKeyObj = crypto$1.createPrivateKey({ key: keyPair.privateKey, format: 'jwk' });
+        const privateKeyObj = crypto.createPrivateKey({ key: keyPair.privateKey, format: 'jwk' });
         const signature = sign.sign(privateKeyObj);
         return `${signingInput}.${this.base64UrlBuffer(signature)}`;
     }
     async hashAccessToken(accessToken) {
+        const crypto = getCrypto();
+        if (!crypto) {
+            throw new Error('Crypto module not available for hashing');
+        }
         // Try WebCrypto first
-        if (crypto$1.subtle) {
+        if (crypto.subtle) {
             try {
-                const hashBuffer = await crypto$1.subtle.digest('SHA-256', buffer.Buffer.from(accessToken));
+                const hashBuffer = await crypto.subtle.digest('SHA-256', buffer.Buffer.from(accessToken));
                 return this.base64UrlBuffer(buffer.Buffer.from(hashBuffer));
             }
             catch (err) {
                 // Fallback to Node.js crypto
             }
         }
-        const hash = crypto$1.createHash('sha256').update(accessToken).digest();
+        const hash = crypto.createHash('sha256').update(accessToken).digest();
         return this.base64UrlBuffer(hash);
     }
     // --- Helpers ---
@@ -40125,10 +40298,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;
@@ -40383,15 +40563,41 @@ const SigningStatus = {
     EXPIRED: 'expired'
 };
 
-// Dynamic import the signer SDK to avoid build issues with static dependencies
-let createPersSignerSDK = null;
-try {
-    const signerModule = require('@explorins/pers-signer/react-native');
-    createPersSignerSDK = signerModule.createPersSignerSDK;
-}
-catch (error) {
-    console.warn('[useTransactionSigner] PERS Signer SDK not available:', error.message);
-    console.warn('[useTransactionSigner] Real blockchain signing will not be available');
+// Lazy-loaded signer SDK factory - initialized on first use to avoid native module timing issues
+let _createPersSignerSDK = null;
+let _signerInitAttempted = false;
+/**
+ * Lazily load the PERS Signer SDK.
+ *
+ * Supports customer pre-initialization via global.__PersSigner for environments
+ * where native module timing is unpredictable (e.g., certain React Native setups).
+ *
+ * @returns The createPersSignerSDK function or null if unavailable
+ */
+function getSignerSDKFactory() {
+    if (_signerInitAttempted) {
+        // Already tried - return cached result (could be null if failed)
+        return _createPersSignerSDK;
+    }
+    _signerInitAttempted = true;
+    // Check for customer pre-initialized global (for native module timing issues)
+    if (typeof global !== 'undefined' && global.__PersSigner?.createPersSignerSDK) {
+        _createPersSignerSDK = global.__PersSigner.createPersSignerSDK;
+        return _createPersSignerSDK;
+    }
+    // Standard lazy load
+    try {
+        const signerModule = require('@explorins/pers-signer/react-native');
+        _createPersSignerSDK = signerModule.createPersSignerSDK;
+        return _createPersSignerSDK;
+    }
+    catch (error) {
+        console.warn('[useTransactionSigner] PERS Signer SDK not available:', error.message);
+        console.warn('[useTransactionSigner] Real blockchain signing will not be available');
+        console.warn('[useTransactionSigner] Tip: If timing issues, pre-initialize in index.js: global.__PersSigner = require("@explorins/pers-signer/react-native")');
+        _createPersSignerSDK = null; // Mark as unavailable
+        return null;
+    }
 }
 // Constants - TODO: Move to environment config later
 const DEFAULT_ETHERS_PROVIDER = "https://sepolia.infura.io/v3/2781b4b5242343d5b0954c98f287b29e";
@@ -40581,6 +40787,7 @@ const useTransactionSigner = () => {
     // Auto-initialize signer SDK when PERS SDK is ready
     react.useEffect(() => {
         const initializeSignerSDK = async () => {
+            const createPersSignerSDK = getSignerSDKFactory();
             if (!createPersSignerSDK) {
                 console.warn('[useTransactionSigner] Signer SDK not available');
                 return;
@@ -40695,7 +40902,7 @@ const useTransactionSigner = () => {
         if (!isSignerInitialized || !signerSDKRef.current) {
             throw new Error('Transaction signer not initialized');
         }
-        if (!createPersSignerSDK) {
+        if (!getSignerSDKFactory()) {
             throw new Error('PERS Signer SDK not available. Blockchain signing is not supported.');
         }
         // Create status callback wrapper that updates both hook state and calls user callback
@@ -40839,7 +41046,7 @@ const useTransactionSigner = () => {
          * );
          * ```
          */
-        isSignerAvailable: isSignerInitialized && !!createPersSignerSDK,
+        isSignerAvailable: isSignerInitialized && !!getSignerSDKFactory(),
         /**
          * Current signing status for UI feedback
          *
@@ -41408,6 +41615,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 +41699,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
@@ -41677,6 +41941,35 @@ const useRedemptions = () => {
      * **Administrators:** Can see all redemptions and filter by active/inactive status
      *
      * The backend enforces permission-based filtering automatically.
+     *
+     * @param options - Filter and pagination options
+     * @param options.active - Filter by active status (Admin only)
+     * @param options.search - Free text search across name, description, tags
+     * @param options.page - Page number (1-indexed)
+     * @param options.limit - Results per page
+     * @param options.sortBy - Field to sort by ('name' | 'createdAt')
+     * @param options.sortOrder - Sort direction ('ASC' | 'DESC')
+     *
+     * @example Basic usage
+     * ```typescript
+     * const { data: offers } = await getRedemptions();
+     * ```
+     *
+     * @example Search redemptions
+     * ```typescript
+     * const { data: coffeeOffers } = await getRedemptions({ search: 'coffee' });
+     * ```
+     *
+     * @example With pagination and sorting
+     * ```typescript
+     * const { data, pagination } = await getRedemptions({
+     *   search: 'discount',
+     *   page: 1,
+     *   limit: 10,
+     *   sortBy: 'name',
+     *   sortOrder: 'ASC'
+     * });
+     * ```
      */
     const getRedemptions = react.useCallback(async (options) => {
         if (!isInitialized || !sdk) {
@@ -41692,27 +41985,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 +42019,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 +42027,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 +42082,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 {