@explorins/pers-sdk-react-native 2.2.0 → 2.2.1

package/src/hooks/useTokens.ts

@@ -1,6 +1,6 @@
 import { useCallback } from 'react';
 import { usePersSDK } from '../providers/PersSDKProvider';
-import type { TokenDTO, PaginatedResponseDTO } from '@explorins/pers-sdk';
+import type { TokenDTO, TokenMetadataDTO, PaginatedResponseDTO, TokenMetadataFilterOptions, RewardsFilterOptions, StampsFilterOptions } from '@explorins/pers-sdk';
 
 /**
  * React hook for token operations in the PERS SDK
@@ -201,6 +201,102 @@ export const useTokens = () => {
     }
   }, [sdk, isInitialized]);
 
+  /**
+   * Get all token metadata with filtering and pagination
+   * 
+   * Retrieves token metadata (rewards/stamps) with server-side filtering.
+   * Use tokenType: 'ERC1155' for rewards, 'ERC721' for stamps.
+   * 
+   * @param options - Filter and pagination options
+   * @returns Promise resolving to paginated token metadata
+   * @throws Error if SDK is not initialized
+   * 
+   * @example
+   * ```typescript
+   * const { getTokenMetadata } = useTokens();
+   * const rewards = await getTokenMetadata({ 
+   *   tokenType: 'ERC1155', 
+   *   active: true,
+   *   limit: 10 
+   * });
+   * ```
+   */
+  const getTokenMetadata = useCallback(async (options?: TokenMetadataFilterOptions): Promise<PaginatedResponseDTO<TokenMetadataDTO>> => {
+    if (!isInitialized || !sdk) {
+      throw new Error('SDK not initialized. Call initialize() first.');
+    }
+    
+    try {
+      const result = await sdk.tokens.getTokenMetadata(options);
+      return result;
+    } catch (error) {
+      console.error('Failed to fetch token metadata:', error);
+      throw error;
+    }
+  }, [sdk, isInitialized]);
+
+  /**
+   * Get rewards (ERC1155 token metadata) with filtering and pagination
+   * 
+   * Convenience method for fetching reward metadata. Rewards are ERC1155 tokens
+   * that represent collectible items, vouchers, or other redeemable rewards.
+   * 
+   * @param options - Filter and pagination options
+   * @returns Promise resolving to paginated reward metadata
+   * @throws Error if SDK is not initialized
+   * 
+   * @example
+   * ```typescript
+   * const { getRewards } = useTokens();
+   * const rewards = await getRewards({ active: true, limit: 10 });
+   * console.log(`Found ${rewards.pagination.total} rewards`);
+   * ```
+   */
+  const getRewards = useCallback(async (options?: RewardsFilterOptions): Promise<PaginatedResponseDTO<TokenMetadataDTO>> => {
+    if (!isInitialized || !sdk) {
+      throw new Error('SDK not initialized. Call initialize() first.');
+    }
+    
+    try {
+      const result = await sdk.tokens.getRewards(options);
+      return result;
+    } catch (error) {
+      console.error('Failed to fetch rewards:', error);
+      throw error;
+    }
+  }, [sdk, isInitialized]);
+
+  /**
+   * Get stamps (ERC721 token metadata) with filtering and pagination
+   * 
+   * Convenience method for fetching stamp metadata. Stamps are ERC721 tokens
+   * that represent achievements, badges, or collectible status markers.
+   * 
+   * @param options - Filter and pagination options
+   * @returns Promise resolving to paginated stamp metadata
+   * @throws Error if SDK is not initialized
+   * 
+   * @example
+   * ```typescript
+   * const { getStamps } = useTokens();
+   * const stamps = await getStamps({ active: true, limit: 10 });
+   * console.log(`Found ${stamps.pagination.total} stamps`);
+   * ```
+   */
+  const getStamps = useCallback(async (options?: StampsFilterOptions): Promise<PaginatedResponseDTO<TokenMetadataDTO>> => {
+    if (!isInitialized || !sdk) {
+      throw new Error('SDK not initialized. Call initialize() first.');
+    }
+    
+    try {
+      const result = await sdk.tokens.getStamps(options);
+      return result;
+    } catch (error) {
+      console.error('Failed to fetch stamps:', error);
+      throw error;
+    }
+  }, [sdk, isInitialized]);
+
   return {
     getTokens,
     getActiveCreditToken,
@@ -208,6 +304,9 @@ export const useTokens = () => {
     getTokenTypes,
     getStatusTokens,
     getTokenByContract,
+    getTokenMetadata,
+    getRewards,
+    getStamps,
     isAvailable: isInitialized && !!sdk?.tokens,
   };
 };

package/src/providers/PersSDKProvider.tsx

@@ -27,11 +27,45 @@ export type { PersConfig } from '@explorins/pers-sdk/core';
 /**
  * Context interface for PERS SDK React Native integration
  * 
+ * ## Session Restoration Behavior
+ * 
+ * Session restoration is **asynchronous**. When the app starts:
+ * 1. `isInitialized` becomes `true` when SDK is ready
+ * 2. Session restoration happens automatically
+ * 3. `isAuthenticated` and `user` update when restoration completes
+ * 
+ * **Always check `isInitialized` AND `isAuthenticated` before using `user`:**
+ * 
+ * ```tsx
+ * const { user, isInitialized, isAuthenticated } = usePersSDK();
+ * 
+ * if (!isInitialized) return <LoadingSpinner />;
+ * if (!isAuthenticated || !user) return <LoginScreen />;
+ * return <WalletContent user={user} />;
+ * ```
+ * 
+ * **Why `user` might be null on app restart:**
+ * - Access tokens expire after 1 hour (auto-refreshed if app is active)
+ * - Refresh tokens expire after 30 days (user must re-login)
+ * - Session restoration is in progress
+ * 
+ * Listen for auth events to debug:
+ * ```typescript
+ * sdk.events.subscribe((event) => {
+ *   console.log('[Auth Event]', event.type, event.details);
+ * }, { domains: ['authentication'], replay: true });
+ * ```
+ * 
+ * | Event | Meaning |
+ * |-------|---------|
+ * | `session_restored` | Tokens valid, user logged in |
+ * | `session_restoration_failed` | Tokens expired, needs re-login |
+ * 
  * @property sdk - Main SDK instance (null until initialized)
  * @property authProvider - Platform-specific auth provider
- * @property isInitialized - Whether SDK has been initialized
+ * @property isInitialized - Whether SDK has been initialized (not whether user is authenticated!)
  * @property isAuthenticated - Whether user is currently authenticated
- * @property user - Current user data (null if not authenticated)
+ * @property user - Current user data (null if not authenticated OR restoration in progress)
  */
 export interface PersSDKContext {
   // Main SDK instance

package/dist/__tests__/__mocks__/pers-sdk-core.d.ts

@@ -1,42 +0,0 @@
-/// <reference types="jest" />
-export interface PersConfig {
-    apiProjectKey?: string;
-    environment?: 'staging' | 'production';
-    captureWalletEvents?: boolean;
-    authProvider?: any;
-    dpop?: {
-        enabled?: boolean;
-        cryptoProvider?: any;
-    };
-}
-export declare const createMockEventEmitter: () => {
-    subscribe: jest.Mock<() => void, [callback: (event: any) => void, options?: any], any>;
-    emit: (event: any) => void;
-    _subscribers: {
-        callback: (event: any) => void;
-        options?: any;
-    }[];
-};
-export declare class PersSDK {
-    events: ReturnType<typeof createMockEventEmitter>;
-    auth: any;
-    users: any;
-    constructor(_httpClient: any, _config: PersConfig);
-    restoreSession: jest.Mock<any, any, any>;
-    _mockEmitEvent(event: any): void;
-}
-export declare class DefaultAuthProvider {
-    constructor(_projectKey?: string, _options?: any);
-}
-export type AuthManager = any;
-export type UserManager = any;
-export type TokenManager = any;
-export type BusinessManager = any;
-export type CampaignManager = any;
-export type RedemptionManager = any;
-export type TransactionManager = any;
-export type PurchaseManager = any;
-export type TenantManager = any;
-export type AnalyticsManager = any;
-export type DonationManager = any;
-//# sourceMappingURL=pers-sdk-core.d.ts.map

package/dist/__tests__/__mocks__/pers-sdk-core.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"pers-sdk-core.d.ts","sourceRoot":"","sources":["../../../src/__tests__/__mocks__/pers-sdk-core.ts"],"names":[],"mappings":";AAEA,MAAM,WAAW,UAAU;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,SAAS,GAAG,YAAY,CAAC;IACvC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,YAAY,CAAC,EAAE,GAAG,CAAC;IACnB,IAAI,CAAC,EAAE;QACL,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,cAAc,CAAC,EAAE,GAAG,CAAC;KACtB,CAAC;CACH;AAGD,eAAO,MAAM,sBAAsB;wDAIO,GAAG,KAAK,IAAI;kBAapC,GAAG;;kBAhBkB,CAAC,KAAK,EAAE,GAAG,KAAK,IAAI;kBAAY,GAAG;;CAyBzE,CAAC;AAGF,qBAAa,OAAO;IAClB,MAAM,EAAE,UAAU,CAAC,OAAO,sBAAsB,CAAC,CAAC;IAClD,IAAI,EAAE,GAAG,CAAC;IACV,KAAK,EAAE,GAAG,CAAC;gBAEC,WAAW,EAAE,GAAG,EAAE,OAAO,EAAE,UAAU;IAUjD,cAAc,2BAAqC;IAGnD,cAAc,CAAC,KAAK,EAAE,GAAG;CAG1B;AAGD,qBAAa,mBAAmB;gBAClB,WAAW,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,GAAG;CACjD;AAGD,MAAM,MAAM,WAAW,GAAG,GAAG,CAAC;AAC9B,MAAM,MAAM,WAAW,GAAG,GAAG,CAAC;AAC9B,MAAM,MAAM,YAAY,GAAG,GAAG,CAAC;AAC/B,MAAM,MAAM,eAAe,GAAG,GAAG,CAAC;AAClC,MAAM,MAAM,eAAe,GAAG,GAAG,CAAC;AAClC,MAAM,MAAM,iBAAiB,GAAG,GAAG,CAAC;AACpC,MAAM,MAAM,kBAAkB,GAAG,GAAG,CAAC;AACrC,MAAM,MAAM,eAAe,GAAG,GAAG,CAAC;AAClC,MAAM,MAAM,aAAa,GAAG,GAAG,CAAC;AAChC,MAAM,MAAM,gBAAgB,GAAG,GAAG,CAAC;AACnC,MAAM,MAAM,eAAe,GAAG,GAAG,CAAC"}

package/dist/__tests__/__mocks__/pers-sdk-core.js

@@ -1,48 +0,0 @@
-// Mock @explorins/pers-sdk/core
-// Create mock event emitter factory
-export const createMockEventEmitter = () => {
-    const subscribers = [];
-    return {
-        subscribe: jest.fn((callback, options) => {
-            subscribers.push({ callback, options });
-            // Replay immediately if requested
-            if (options?.replay) {
-                // No events to replay in mock
-            }
-            return () => {
-                const index = subscribers.findIndex(s => s.callback === callback);
-                if (index > -1)
-                    subscribers.splice(index, 1);
-            };
-        }),
-        emit: (event) => {
-            subscribers.forEach(({ callback, options }) => {
-                if (!options?.domains || options.domains.includes(event.domain)) {
-                    callback(event);
-                }
-            });
-        },
-        _subscribers: subscribers
-    };
-};
-// Mock PersSDK class
-export class PersSDK {
-    constructor(_httpClient, _config) {
-        this.restoreSession = jest.fn().mockResolvedValue(null);
-        this.events = createMockEventEmitter();
-        this.auth = {
-            ensureValidToken: jest.fn().mockResolvedValue(true)
-        };
-        this.users = {
-            getCurrentUser: jest.fn().mockResolvedValue({ id: 'user-1', email: 'test@test.com' })
-        };
-    }
-    // Helper for tests to emit events
-    _mockEmitEvent(event) {
-        this.events.emit(event);
-    }
-}
-// Mock DefaultAuthProvider
-export class DefaultAuthProvider {
-    constructor(_projectKey, _options) { }
-}

package/dist/__tests__/__mocks__/pers-shared.d.ts

@@ -1,15 +0,0 @@
-export interface UserDTO {
-    id: string;
-    email?: string;
-    firstName?: string;
-    lastName?: string;
-    walletAddress?: string;
-    createdAt?: string;
-    updatedAt?: string;
-}
-export interface AdminDTO {
-    id: string;
-    email?: string;
-    role?: string;
-}
-//# sourceMappingURL=pers-shared.d.ts.map

package/dist/__tests__/__mocks__/pers-shared.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"pers-shared.d.ts","sourceRoot":"","sources":["../../../src/__tests__/__mocks__/pers-shared.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf"}

package/dist/__tests__/__mocks__/pers-shared.js

@@ -1,2 +0,0 @@
-// Mock @explorins/pers-shared
-export {};

package/src/__tests__/__mocks__/pers-sdk-core.ts

@@ -1,83 +0,0 @@
-// Mock @explorins/pers-sdk/core
-
-export interface PersConfig {
-  apiProjectKey?: string;
-  environment?: 'staging' | 'production';
-  captureWalletEvents?: boolean;
-  authProvider?: any;
-  dpop?: {
-    enabled?: boolean;
-    cryptoProvider?: any;
-  };
-}
-
-// Create mock event emitter factory
-export const createMockEventEmitter = () => {
-  const subscribers: Array<{ callback: (event: any) => void; options?: any }> = [];
-  
-  return {
-    subscribe: jest.fn((callback: (event: any) => void, options?: any) => {
-      subscribers.push({ callback, options });
-      
-      // Replay immediately if requested
-      if (options?.replay) {
-        // No events to replay in mock
-      }
-      
-      return () => {
-        const index = subscribers.findIndex(s => s.callback === callback);
-        if (index > -1) subscribers.splice(index, 1);
-      };
-    }),
-    emit: (event: any) => {
-      subscribers.forEach(({ callback, options }) => {
-        if (!options?.domains || options.domains.includes(event.domain)) {
-          callback(event);
-        }
-      });
-    },
-    _subscribers: subscribers
-  };
-};
-
-// Mock PersSDK class
-export class PersSDK {
-  events: ReturnType<typeof createMockEventEmitter>;
-  auth: any;
-  users: any;
-  
-  constructor(_httpClient: any, _config: PersConfig) {
-    this.events = createMockEventEmitter();
-    this.auth = {
-      ensureValidToken: jest.fn().mockResolvedValue(true)
-    };
-    this.users = {
-      getCurrentUser: jest.fn().mockResolvedValue({ id: 'user-1', email: 'test@test.com' })
-    };
-  }
-  
-  restoreSession = jest.fn().mockResolvedValue(null);
-  
-  // Helper for tests to emit events
-  _mockEmitEvent(event: any) {
-    this.events.emit(event);
-  }
-}
-
-// Mock DefaultAuthProvider
-export class DefaultAuthProvider {
-  constructor(_projectKey?: string, _options?: any) {}
-}
-
-// Mock manager types
-export type AuthManager = any;
-export type UserManager = any;
-export type TokenManager = any;
-export type BusinessManager = any;
-export type CampaignManager = any;
-export type RedemptionManager = any;
-export type TransactionManager = any;
-export type PurchaseManager = any;
-export type TenantManager = any;
-export type AnalyticsManager = any;
-export type DonationManager = any;

package/src/__tests__/__mocks__/pers-shared.ts

@@ -1,17 +0,0 @@
-// Mock @explorins/pers-shared
-
-export interface UserDTO {
-  id: string;
-  email?: string;
-  firstName?: string;
-  lastName?: string;
-  walletAddress?: string;
-  createdAt?: string;
-  updatedAt?: string;
-}
-
-export interface AdminDTO {
-  id: string;
-  email?: string;
-  role?: string;
-}