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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@explorins/pers-sdk-react-native",
-  "version": "2.1.12",
+  "version": "2.1.13",
   "description": "React Native SDK for PERS Platform - Tourism Loyalty System with Blockchain Transaction Signing and WebAuthn Authentication",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -37,7 +37,7 @@
   "author": "eXplorins",
   "license": "MIT",
   "dependencies": {
-    "@explorins/pers-sdk": "^2.1.18",
+    "@explorins/pers-sdk": "^2.1.20",
     "@explorins/pers-signer": "^1.0.33",
     "buffer": "^6.0.3",
     "ethers": "^6.15.0",
@@ -155,7 +155,7 @@
     "@ethersproject/scrypt": false
   },
   "devDependencies": {
-    "@explorins/pers-shared": "^2.1.117",
+    "@explorins/pers-shared": "^2.1.123",
     "@react-native-async-storage/async-storage": "^3.0.2",
     "@rollup/plugin-commonjs": "^25.0.7",
     "@rollup/plugin-json": "^6.1.0",

package/src/hooks/index.ts

@@ -38,7 +38,7 @@ export type {
 } from './useTokenBalances';
 
 // Export campaign-related types
-export type { CampaignClaimFilters, CampaignHook } from './useCampaigns';
+export type { CampaignClaimFilters, CampaignHook, GetCampaignsOptions } from './useCampaigns';
 
 // Export redemption-related types
 export type { RedemptionRedeemFilters, RedemptionHook } from './useRedemptions';

package/src/hooks/useCampaigns.ts

@@ -8,7 +8,8 @@ import type {
   PaginatedResponseDTO,
   CampaignClaimIncludeRelation,
   CampaignIncludeRelation,
-  SortOrder
+  SortOrder,
+  // DynamicContext
 } from '@explorins/pers-shared';
 import type { CampaignClaimFilters } from '@explorins/pers-sdk/campaign';
 
@@ -113,6 +114,63 @@ export const useCampaigns = () => {
     }
   }, [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 = useCallback(async (request: CampaignClaimRequestDTO): Promise<CampaignClaimDTO | null> => {
     if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
@@ -141,7 +199,7 @@ export 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

package/src/hooks/useRedemptions.ts

@@ -8,7 +8,9 @@ import type {
   RedemptionRedeemRequestResponseDTO,
   RedemptionTypeDTO,
   PaginatedResponseDTO,
-  RedemptionRedeemIncludeRelation
+  RedemptionRedeemIncludeRelation,
+  ProcessRecordStatus,
+  DynamicContext
 } from '@explorins/pers-shared';
 import type { RedemptionRedeemFilters } from '@explorins/pers-sdk/redemption';
 import type { PaginationOptions } from '@explorins/pers-sdk';
@@ -43,27 +45,33 @@ export 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 = useCallback(async (
+    filters?: { redemptionId?: string; status?: ProcessRecordStatus },
     options?: PaginationOptions,
     include?: RedemptionRedeemIncludeRelation[]
   ): Promise<PaginatedResponseDTO<RedemptionRedeemDTO>> => {
@@ -76,7 +84,7 @@ export const useRedemptions = () => {
     }
     
     try {
-      const result = await sdk.redemptions.getUserRedemptions(options, include);
+      const result = await sdk.redemptions.getUserRedemptions(filters, options, include);
       return result;
     } catch (error) {
       console.error('Failed to fetch user redemptions:', error);
@@ -84,7 +92,57 @@ export const useRedemptions = () => {
     }
   }, [sdk, isInitialized, isAuthenticated]);
 
-  const redeem = useCallback(async (redemptionId: string, onStatusUpdate?: OnStatusUpdateFn): Promise<RedemptionRedeemRequestResponseDTO> => {
+  /**
+   * 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 = useCallback(async (
+    redemptionId: string, 
+    options?: { context?: DynamicContext; onStatusUpdate?: OnStatusUpdateFn }
+  ): Promise<RedemptionRedeemRequestResponseDTO> => {
     if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
@@ -93,12 +151,12 @@ export const useRedemptions = () => {
     }
     
     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: SubmissionResult = await signAndSubmitTransactionWithJWT(txToken, onStatusUpdate);
+          const signingResult: SubmissionResult = await signAndSubmitTransactionWithJWT(txToken, options?.onStatusUpdate);
           if (signingResult.success) {
             // Return enhanced result with signing information
             return {

package/src/hooks/useTokenBalances.ts

@@ -95,10 +95,17 @@ export interface UseTokenBalancesResult {
  * **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;

package/src/index.ts

@@ -284,7 +284,7 @@ export type { EventsHook, PersEvent, EventHandler, EventFilter, Unsubscribe } fr
 export type { TokenBalanceWithToken, UseTokenBalancesOptions, UseTokenBalancesResult } from './hooks';
 
 // Re-export campaign types for convenience
-export type { CampaignClaimFilters, CampaignHook } from './hooks';
+export type { CampaignClaimFilters, CampaignHook, GetCampaignsOptions } from './hooks';
 
 // Re-export redemption types for convenience
 export type { RedemptionRedeemFilters, RedemptionHook } from './hooks';