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

package/dist/index.js

@@ -3216,6 +3216,12 @@ const EntityTypes = {
     SIGNING_ACCOUNT: 'signing_account',
     API_KEY: 'api_key',
     WEBHOOK: 'webhook',
+    // Service domains
+    ANALYTICS: 'analytics',
+    CHAIN: 'chain',
+    FILE: 'file',
+    JWKS: 'jwks',
+    PROJECT: 'project',
 };
 /**
  * Error-specific domains (extends EntityTypes)
@@ -3726,6 +3732,9 @@ const CommonErrorCodes = {
     TOKEN_NOT_ACTIVE: 'TOKEN_NOT_ACTIVE',
     TOKEN_ID_REQUIRED: 'TOKEN_ID_REQUIRED',
     TOKEN_TYPE_NOT_FOUND: 'TOKEN_TYPE_NOT_FOUND',
+    TOKEN_UNIT_NOT_FOUND: 'TOKEN_UNIT_NOT_FOUND',
+    NFT_EXPIRED: 'NFT_EXPIRED',
+    NFT_BUSINESS_RESTRICTION: 'NFT_BUSINESS_RESTRICTION',
     // Wallet domain
     WALLET_MISSING_SIGNING: 'WALLET_MISSING_SIGNING',
     WALLET_NOT_FOUND: 'WALLET_NOT_FOUND',
@@ -3765,6 +3774,9 @@ const CommonErrorCodes = {
     CAMPAIGN_DAILY_LIMIT_REACHED: 'CAMPAIGN_DAILY_LIMIT_REACHED',
     CAMPAIGN_GLOBAL_LIMIT_REACHED: 'CAMPAIGN_GLOBAL_LIMIT_REACHED',
     CAMPAIGN_GLOBAL_DAILY_LIMIT_REACHED: 'CAMPAIGN_GLOBAL_DAILY_LIMIT_REACHED',
+    CAMPAIGN_NOT_FOUND: 'CAMPAIGN_NOT_FOUND',
+    GEOGRAPHIC_RESTRICTION: 'GEOGRAPHIC_RESTRICTION',
+    LOCATION_VERIFICATION_REQUIRED: 'LOCATION_VERIFICATION_REQUIRED',
     // Trigger domain
     TRIGGER_NOT_FOUND: 'TRIGGER_NOT_FOUND',
     // Trigger Source domain
@@ -3780,6 +3792,12 @@ const CommonErrorCodes = {
     EXTERNAL_SERVICE_ERROR: 'EXTERNAL_SERVICE_ERROR',
     AUTHENTICATION_REQUIRED: 'AUTHENTICATION_REQUIRED',
     AUTHORIZATION_FAILED: 'AUTHORIZATION_FAILED',
+    CONFIGURATION_MISSING: 'CONFIGURATION_MISSING',
+    // Redemption domain
+    USER_STATUS_RESTRICTED: 'USER_STATUS_RESTRICTED',
+    REDEMPTION_ALREADY_PROCESSING: 'REDEMPTION_ALREADY_PROCESSING',
+    MAX_REDEMPTION: 'MAX_REDEMPTION',
+    USER_LIMIT: 'USER_LIMIT',
     // Authentication errors
     INVALID_TOKEN: 'INVALID_TOKEN',
     TOKEN_EXPIRED: 'TOKEN_EXPIRED',
@@ -3787,6 +3805,8 @@ const CommonErrorCodes = {
     REFRESH_TOKEN_EXPIRED: 'REFRESH_TOKEN_EXPIRED',
     REFRESH_TOKEN_REVOKED: 'REFRESH_TOKEN_REVOKED',
     FIREBASE_AUTH_ERROR: 'FIREBASE_AUTH_ERROR',
+    MULTIPLE_CONTEXT_SELECTION_REQUIRED: 'MULTIPLE_CONTEXT_SELECTION_REQUIRED',
+    ADMIN_TENANT_REQUIRED: 'ADMIN_TENANT_REQUIRED',
     // Generic fallbacks
     INTERNAL_ERROR: 'INTERNAL_ERROR',
     VALIDATION_ERROR: 'VALIDATION_ERROR',
@@ -3883,12 +3903,12 @@ class ErrorUtils {
             return false;
         const err = error;
         // Check for explicit token expired indicators
-        if (err?.code === 'TOKEN_EXPIRED' || err?.errorCode === 'TOKEN_EXPIRED') {
+        if (err?.code === CommonErrorCodes.TOKEN_EXPIRED || err?.errorCode === CommonErrorCodes.TOKEN_EXPIRED) {
             return true;
         }
         // Check in response data
         const apiError = err?.response?.data || err;
-        if (apiError?.code === 'TOKEN_EXPIRED' || apiError?.errorCode === 'TOKEN_EXPIRED') {
+        if (apiError?.code === CommonErrorCodes.TOKEN_EXPIRED || apiError?.errorCode === CommonErrorCodes.TOKEN_EXPIRED) {
             return true;
         }
         // Any 401 error is treated as token expiration
@@ -3958,7 +3978,9 @@ class ErrorUtils {
             // Try extraction strategies in priority order
             const candidates = [
                 this.parseHttpClientError(error), // React Native format
-                httpError.response?.data, // Axios/fetch format
+                httpError.response && typeof httpError.response === 'object'
+                    ? httpError.response.data
+                    : undefined, // Axios/fetch format
                 httpError.error, // Angular HttpErrorResponse
                 httpError // Direct error object
             ];
@@ -3977,8 +3999,9 @@ class ErrorUtils {
      * Check if object has structured error fields from backend (StructuredError)
      */
     static hasStructuredErrorFields(obj) {
-        return obj && typeof obj === 'object' &&
-            ((obj.code && obj.category) || (obj.status && (obj.detail || obj.message || obj.title)));
+        return obj !== null && typeof obj === 'object' &&
+            (('code' in obj && 'category' in obj) ||
+                ('status' in obj && ('detail' in obj || 'message' in obj || 'title' in obj)));
     }
     /**
      * Create fallback error structure when no structured error found
@@ -3989,9 +4012,9 @@ class ErrorUtils {
             title: 'Request failed',
             message: this.getMessage(error),
             detail: this.getMessage(error),
-            code: 'REQUEST_FAILED',
+            code: CommonErrorCodes.TECHNICAL_ERROR,
             category: exports.ErrorCategory.TECHNICAL,
-            domain: 'api',
+            domain: ErrorDomains.EXTERNAL,
             retryable: this.isRetryable(error)
         };
     }
@@ -4070,7 +4093,7 @@ class PersApiError extends Error {
         this.method = method;
         this.name = 'PersApiError';
         // Use backend error details directly
-        this.code = backendError?.code || 'API_ERROR';
+        this.code = backendError?.code || CommonErrorCodes.TECHNICAL_ERROR;
         this.domain = backendError?.domain || ErrorDomains.EXTERNAL;
         this.category = backendError?.category || exports.ErrorCategory.TECHNICAL;
         this.retryable = backendError?.retryable ?? (statusCode ? statusCode >= 500 : false);
@@ -4094,7 +4117,7 @@ class AuthenticationError extends PersApiError {
 class NetworkError extends Error {
     constructor(message) {
         super(message);
-        this.code = SdkErrorCodes.NETWORK_ERROR;
+        this.code = CommonErrorCodes.EXTERNAL_SERVICE_ERROR;
         this.domain = ErrorDomains.EXTERNAL;
         this.category = exports.ErrorCategory.INFRASTRUCTURE;
         this.retryable = true;
@@ -5142,6 +5165,58 @@ class TokenApi {
         }
         return this.apiClient.get(url);
     }
+    /**
+     * Get all token metadata with filtering and pagination
+     *
+     * Useful for displaying rewards (ERC1155) or stamps (ERC721) in tables.
+     * Non-admin users always get active metadata only.
+     *
+     * @param options - Filter and pagination options
+     * @returns Paginated response with token metadata
+     *
+     * @example Get all active rewards
+     * ```typescript
+     * const rewards = await tokenApi.getTokenMetadata({
+     *   tokenType: 'ERC1155',
+     *   active: true,
+     *   limit: 10
+     * });
+     * ```
+     *
+     * @example Get stamps with search
+     * ```typescript
+     * const stamps = await tokenApi.getTokenMetadata({
+     *   tokenType: 'ERC721',
+     *   search: 'gold',
+     *   sortBy: 'name',
+     *   sortOrder: 'ASC'
+     * });
+     * ```
+     */
+    async getTokenMetadata(options) {
+        const params = buildPaginationParams(options);
+        if (options?.active !== undefined) {
+            params.set('active', String(options.active));
+        }
+        if (options?.tokenType) {
+            params.set('tokenType', options.tokenType);
+        }
+        if (options?.tokenId) {
+            params.set('tokenId', options.tokenId);
+        }
+        if (options?.search) {
+            params.set('search', options.search);
+        }
+        // Handle tags as string or array
+        if (options?.tags) {
+            const tagsArray = Array.isArray(options.tags) ? options.tags : [options.tags];
+            if (tagsArray.length > 0) {
+                params.set('tags', tagsArray.join(','));
+            }
+        }
+        const response = await this.apiClient.get(`${this.basePath}/metadata?${params.toString()}`);
+        return normalizeToPaginated(response);
+    }
     // ==========================================
     // ADMIN OPERATIONS
     // ==========================================
@@ -5251,6 +5326,40 @@ class TokenService {
     async getTokenByContractAddress(contractAddress, contractTokenId) {
         return this.tokenApi.getTokenByContractAddress(contractAddress, contractTokenId);
     }
+    /**
+     * Get all token metadata with filtering and pagination
+     *
+     * Useful for displaying rewards (ERC1155) or stamps (ERC721) in tables.
+     * Non-admin users always get active metadata only.
+     *
+     * @param options - Filter and pagination options
+     * @returns Paginated response with token metadata
+     */
+    async getTokenMetadata(options) {
+        return this.tokenApi.getTokenMetadata(options);
+    }
+    /**
+     * Get rewards (ERC1155 token metadata) with filtering and pagination
+     *
+     * Convenience method for fetching reward metadata.
+     *
+     * @param options - Filter and pagination options (tokenType is set automatically)
+     * @returns Paginated response with reward metadata
+     */
+    async getRewards(options) {
+        return this.tokenApi.getTokenMetadata({ ...options, tokenType: NativeTokenTypes.ERC1155 });
+    }
+    /**
+     * Get stamps (ERC721 token metadata) with filtering and pagination
+     *
+     * Convenience method for fetching stamp metadata.
+     *
+     * @param options - Filter and pagination options (tokenType is set automatically)
+     * @returns Paginated response with stamp metadata
+     */
+    async getStamps(options) {
+        return this.tokenApi.getTokenMetadata({ ...options, tokenType: NativeTokenTypes.ERC721 });
+    }
     // ==========================================
     // ADMIN OPERATIONS
     // ==========================================
@@ -5377,7 +5486,7 @@ class BusinessApi {
     /**
      * Get all businesses with role-based filtering and pagination
      *
-     * Endpoint: GET /businesses?active={boolean}&sanitize={mode}&page={number}&limit={number}
+     * Endpoint: GET /businesses?active={boolean}&sanitize={mode}&page={number}&limit={number}&businessTypeId={number}
      * Auth: @ApiSecurity('projectKey') (enhanced with role-based filtering)
      *
      * Note:
@@ -5400,8 +5509,11 @@ class BusinessApi {
      * });
      *
      * // Filter by tag(s)
-     * const tagged = await businessApi.getBusinesses({ tag: 'restaurant' });
-     * const multiTag = await businessApi.getBusinesses({ tag: ['restaurant', 'cafe'] });
+     * const tagged = await businessApi.getBusinesses({ tags: 'restaurant' });
+     * const multiTag = await businessApi.getBusinesses({ tags: ['restaurant', 'cafe'] });
+     *
+     * // Filter by business type
+     * const hotels = await businessApi.getBusinesses({ businessTypeId: 1 });
      * ```
      */
     async getBusinesses(options) {
@@ -5421,6 +5533,9 @@ class BusinessApi {
         if (options?.sanitize) {
             params.set('sanitize', options.sanitize);
         }
+        if (options?.businessTypeId !== undefined) {
+            params.set('businessTypeId', String(options.businessTypeId));
+        }
         const response = await this.apiClient.get(`${this.basePath}?${params.toString()}`);
         return normalizeToPaginated(response);
     }
@@ -5767,20 +5882,16 @@ class BusinessService {
         return this.businessApi.getBusinessByAccount(accountAddress);
     }
     /**
-     * Get businesses by type (client-side filtering)
-     * @deprecated Consider implementing server-side filtering for better performance
+     * Get businesses by type (server-side filtering)
+     * Uses the businessTypeId parameter for efficient server-side filtering.
      */
     async getBusinessesByType(typeId, options) {
-        const response = await this.getActiveBusinesses(options);
-        const filtered = response.data.filter((business) => business.businessType && business.businessType.id === parseInt(typeId));
-        return {
-            data: filtered,
-            pagination: {
-                ...response.pagination,
-                total: filtered.length,
-                pages: Math.ceil(filtered.length / (response.pagination.limit || 20))
-            }
-        };
+        const businessTypeId = parseInt(typeId, 10);
+        return this.businessApi.getBusinesses({
+            ...options,
+            businessTypeId,
+            active: options?.active ?? true // Default to active businesses
+        });
     }
     // ==========================================
     // ADMIN OPERATIONS
@@ -7019,6 +7130,14 @@ class RedemptionService {
     async getRedemptions(options) {
         return this.redemptionApi.getRedemptions(options);
     }
+    /**
+     * Get a specific redemption by ID
+     * @param id - Redemption UUID
+     * @param include - Optional relations to include: 'redeemCount'
+     */
+    async getRedemptionById(id, include) {
+        return this.redemptionApi.getRedemptionById(id, include);
+    }
     /**
      * Convenience: Get active redemptions (public)
      */
@@ -9575,13 +9694,17 @@ class AuthService {
      * Returns true for:
      * - Known fatal error codes (REFRESH_TOKEN_EXPIRED, TOKEN_REVOKED, etc.)
      * - Fatal error codes in error messages (wrapped errors)
-     * - 401/403 HTTP status codes
      *
-     * Returns false for (retryable errors):
+     * Returns false for (retryable/recoverable):
      * - Network errors
      * - Timeouts
      * - 5xx server errors
      * - TOKEN_EXPIRED (normal refresh trigger)
+     * - Raw 401/403 without fatal code (should try refresh first)
+     *
+     * NOTE: We intentionally DO NOT treat raw 401/403 status as fatal.
+     * The HTTP client handles 401 by attempting token refresh first.
+     * Only if refresh fails WITH a fatal code do we logout.
      */
     isDefinitiveAuthFailure(error) {
         if (!error)
@@ -9596,11 +9719,12 @@ class AuthService {
         if (isFatalAuthErrorInMessage(errorMessage)) {
             return true;
         }
-        // Check HTTP status if available
-        const status = errorAny?.status || errorAny?.response?.status;
-        if (status === 401 || status === 403) {
-            return true;
-        }
+        // NOTE: We intentionally DO NOT check HTTP status codes here.
+        // A raw 401/403 without a fatal error code should trigger a refresh attempt,
+        // not an immediate logout. The HTTP client (pers-api-client.ts) handles this:
+        // 1. 401 received → try refresh token
+        // 2. Refresh succeeds → retry original request
+        // 3. Refresh fails with fatal CODE → then logout
         // Everything else is considered retryable
         return false;
     }
@@ -9684,12 +9808,17 @@ class AuthService {
             const contextClaims = refreshToken ? decodeJwtPayload(refreshToken) : null;
             // Re-authenticate using provider token based on auth type
             // Pass the context from the previous session to avoid MULTIPLE_CONTEXT_SELECTION_REQUIRED
+            // Note: In AuthJWTPayload, when accountType=BUSINESS, sub contains the businessId
             switch (authType) {
                 case exports.AccountOwnerType.USER:
                     await this.loginUser(providerToken);
                     break;
                 case exports.AccountOwnerType.BUSINESS:
-                    await this.loginBusiness(providerToken, contextClaims?.businessId ? { businessId: contextClaims.businessId } : undefined);
+                    // For BUSINESS auth, sub contains the businessId when accountType is BUSINESS
+                    const businessId = contextClaims?.accountType === exports.AccountOwnerType.BUSINESS
+                        ? contextClaims.sub
+                        : undefined;
+                    await this.loginBusiness(providerToken, businessId ? { businessId } : undefined);
                     break;
                 case exports.AccountOwnerType.TENANT:
                     await this.loginTenantAdmin(providerToken, contextClaims?.tenantId ? { tenantId: contextClaims.tenantId } : undefined);
@@ -10457,17 +10586,16 @@ class DPoPManager {
      * Generate a short fingerprint of the public key for debugging
      * This helps identify if the same key is being used across operations
      */
-    getPublicKeyFingerprint(publicKey) {
-        try {
-            // Use the 'x' coordinate of the EC key as a fingerprint
-            const x = publicKey.x || '';
-            const y = publicKey.y || '';
-            return `${x.substring(0, 8)}...${y.substring(0, 4)}`;
-        }
-        catch {
-            return 'unknown';
-        }
-    }
+    /* private getPublicKeyFingerprint(publicKey: JsonWebKey): string {
+      try {
+        // Use the 'x' coordinate of the EC key as a fingerprint
+        const x = publicKey.x || '';
+        const y = publicKey.y || '';
+        return `${x.substring(0, 8)}...${y.substring(0, 4)}`;
+      } catch {
+        return 'unknown';
+      }
+    } */
     /**
      * Clears DPoP keys (e.g. on logout)
      */
@@ -10716,7 +10844,7 @@ class DefaultAuthProvider {
 /** SDK package name */
 const SDK_NAME = "@explorins/pers-sdk";
 /** SDK version - injected from package.json at build time */
-const SDK_VERSION = "2.1.33";
+const SDK_VERSION = "2.1.37";
 /** Full SDK identifier for headers */
 const SDK_USER_AGENT = `${SDK_NAME}/${SDK_VERSION}`;
 
@@ -10927,9 +11055,9 @@ class PersApiClient {
         }); */
         this._events?.emitError({
             domain: errorDetails.domain || 'external',
-            type: errorDetails.code || 'API_ERROR',
-            userMessage: errorDetails.message || errorMessage, // Event system uses userMessage for display
-            code: errorDetails.code,
+            type: 'api_error', // Event type discriminator (fixed value)
+            userMessage: errorDetails.message || errorMessage,
+            code: errorDetails.code, // Actual error code from backend
             details: {
                 endpoint,
                 method,
@@ -12565,6 +12693,107 @@ class TokenManager {
     async getTokenByContract(contractAddress, contractTokenId = null) {
         return this.tokenService.getTokenByContractAddress(contractAddress, contractTokenId);
     }
+    /**
+     * Get all token metadata with filtering and pagination
+     *
+     * Retrieves token metadata (rewards/stamps) with server-side filtering and pagination.
+     * Useful for displaying rewards (ERC1155) or stamps (ERC721) in admin tables.
+     * Non-admin users always get active metadata only.
+     *
+     * @param options - Filter and pagination options
+     * @returns Promise resolving to paginated token metadata
+     *
+     * @example Get paginated rewards
+     * ```typescript
+     * const rewards = await sdk.tokens.getTokenMetadata({
+     *   tokenType: 'ERC1155',
+     *   active: true,
+     *   page: 1,
+     *   limit: 10,
+     *   sortBy: 'name',
+     *   sortOrder: 'ASC'
+     * });
+     *
+     * console.log(`Page 1 of ${rewards.pagination.pages}`);
+     * rewards.data.forEach(r => console.log(r.name));
+     * ```
+     *
+     * @example Get stamps with search
+     * ```typescript
+     * const stamps = await sdk.tokens.getTokenMetadata({
+     *   tokenType: 'ERC721',
+     *   search: 'gold',
+     *   limit: 25
+     * });
+     * ```
+     */
+    async getTokenMetadata(options) {
+        return this.tokenService.getTokenMetadata(options);
+    }
+    /**
+     * 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 (tokenType is set automatically)
+     * @returns Promise resolving to paginated reward metadata
+     *
+     * @example Get active rewards
+     * ```typescript
+     * const rewards = await sdk.tokens.getRewards({
+     *   active: true,
+     *   limit: 10
+     * });
+     *
+     * console.log(`Found ${rewards.pagination.total} rewards`);
+     * rewards.data.forEach(r => console.log(`${r.name}: ${r.description}`));
+     * ```
+     *
+     * @example Search rewards
+     * ```typescript
+     * const discountRewards = await sdk.tokens.getRewards({
+     *   search: 'discount',
+     *   sortBy: 'name',
+     *   sortOrder: 'ASC'
+     * });
+     * ```
+     */
+    async getRewards(options) {
+        return this.tokenService.getRewards(options);
+    }
+    /**
+     * 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 (tokenType is set automatically)
+     * @returns Promise resolving to paginated stamp metadata
+     *
+     * @example Get active stamps
+     * ```typescript
+     * const stamps = await sdk.tokens.getStamps({
+     *   active: true,
+     *   limit: 10
+     * });
+     *
+     * console.log(`Found ${stamps.pagination.total} stamps`);
+     * stamps.data.forEach(s => console.log(`${s.name}: ${s.description}`));
+     * ```
+     *
+     * @example Filter stamps by tags
+     * ```typescript
+     * const goldStamps = await sdk.tokens.getStamps({
+     *   tags: ['gold', 'premium'],
+     *   sortBy: 'createdAt',
+     *   sortOrder: 'DESC'
+     * });
+     * ```
+     */
+    async getStamps(options) {
+        return this.tokenService.getStamps(options);
+    }
     /**
      * Admin: Create new token
      *
@@ -14469,6 +14698,52 @@ class RedemptionManager {
     async getRedemptions(options) {
         return this.redemptionService.getRedemptions(options);
     }
+    /**
+     * Get a specific redemption by ID
+     *
+     * Retrieves detailed information about a specific redemption offer.
+     * Useful when you already have the redemption ID and need full details.
+     *
+     * @param id - Redemption UUID
+     * @param include - Optional relations to include: 'redeemCount'
+     * @returns Promise resolving to the redemption
+     *
+     * @example Basic usage
+     * ```typescript
+     * const redemption = await sdk.redemptions.getRedemptionById('7baf4d39-0bd6-45ca-9c66-8c0d655767c3');
+     * console.log(redemption.name);
+     * console.log(redemption.description);
+     * ```
+     *
+     * @example With redeem count
+     * ```typescript
+     * const redemption = await sdk.redemptions.getRedemptionById(
+     *   'redemption-123',
+     *   ['redeemCount']
+     * );
+     * console.log(`${redemption.name} has been redeemed ${redemption.redeemCount} times`);
+     * ```
+     *
+     * @example Get redemption details for display
+     * ```typescript
+     * const redemption = await sdk.redemptions.getRedemptionById(id);
+     *
+     * console.log('Redemption Details:');
+     * console.log(`Name: ${redemption.name}`);
+     * console.log(`Description: ${redemption.description}`);
+     * console.log(`Active: ${redemption.isActive}`);
+     *
+     * if (redemption.tokenUnits?.length) {
+     *   console.log('Cost:');
+     *   redemption.tokenUnits.forEach(unit => {
+     *     console.log(`  ${unit.amount} ${unit.token.symbol}`);
+     *   });
+     * }
+     * ```
+     */
+    async getRedemptionById(id, include) {
+        return this.redemptionService.getRedemptionById(id, include);
+    }
     /**
      * Get available redemption types
      *
@@ -21157,6 +21432,99 @@ const useTokens = () => {
             throw error;
         }
     }, [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 = react.useCallback(async (options) => {
+        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 = react.useCallback(async (options) => {
+        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 = react.useCallback(async (options) => {
+        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,
@@ -21164,6 +21532,9 @@ const useTokens = () => {
         getTokenTypes,
         getStatusTokens,
         getTokenByContract,
+        getTokenMetadata,
+        getRewards,
+        getStamps,
         isAvailable: isInitialized && !!sdk?.tokens,
     };
 };
@@ -44400,6 +44771,25 @@ const useRedemptions = () => {
     /**
      * Redeem a redemption offer with optional dynamic context
      *
+     * ## When to use `redeem()` vs `createTransaction()`
+     *
+     * | Use Case | Method | Auto-Signs |
+     * |----------|--------|------------|
+     * | **Voucher redemption** | `redeem()` | ✅ Yes |
+     * | **Reward redemption** | `redeem()` | ✅ Yes |
+     * | **Direct token transfer** | `createTransaction()` | ⚠️ Depends |
+     * | **POS burn with QR** | `buildPOSBurnRequest()` | ❌ Manual |
+     *
+     * **Use `redeem()` for voucher/reward redemptions.** It automatically:
+     * 1. Creates redemption record
+     * 2. Triggers passkey/biometric prompt
+     * 3. Signs the transaction
+     * 4. Submits to blockchain
+     * 5. Returns result with `transactionHash`
+     *
+     * **No admin approval required** - The "PENDING" state is brief (seconds).
+     * The user's passkey signature IS the approval.
+     *
      * Supports dynamic context for personalized NFT generation when the redemption
      * issues ERC721 tokens. Context can include validity dates, AI prompt placeholders,
      * and custom metadata.
@@ -44408,11 +44798,21 @@ const useRedemptions = () => {
      * @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
+     * @returns Promise resolving to redemption result with `transactionHash` on success
      *
-     * @example Basic redemption
+     * @example Basic redemption (most common)
      * ```typescript
-     * const result = await redeem('redemption-123');
+     * const { redeem } = useRedemptions();
+     *
+     * const result = await redeem('redemption-123', {
+     *   onStatusUpdate: (status, message) => {
+     *     console.log(`Status: ${status} - ${message}`);
+     *   }
+     * });
+     *
+     * if (result.transactionHash) {
+     *   console.log('Redemption complete!', result.transactionHash);
+     * }
      * ```
      *
      * @example Redemption with dynamic context (personalized NFT)
@@ -44443,6 +44843,8 @@ const useRedemptions = () => {
      *   }
      * });
      * ```
+     *
+     * @see {@link useTransactions.createTransaction | createTransaction()} for direct transfers without redemption flow
      */
     const redeem = react.useCallback(async (redemptionId, options) => {
         if (!isInitialized || !sdk) {
@@ -44592,8 +44994,43 @@ const useRedemptions = () => {
             throw error;
         }
     }, [sdk, isInitialized]);
+    /**
+     * Get a specific redemption by ID
+     *
+     * Retrieves detailed information about a specific redemption offer.
+     *
+     * @param id - Redemption UUID
+     * @param include - Optional relations to include: 'redeemCount'
+     * @returns Promise resolving to the redemption
+     *
+     * @example Basic usage
+     * ```typescript
+     * const redemption = await getRedemptionById('7baf4d39-0bd6-45ca-9c66-8c0d655767c3');
+     * console.log(redemption.name);
+     * ```
+     *
+     * @example With redeem count
+     * ```typescript
+     * const redemption = await getRedemptionById('redemption-123', ['redeemCount']);
+     * console.log(`${redemption.name} has been redeemed ${redemption.redeemCount} times`);
+     * ```
+     */
+    const getRedemptionById = react.useCallback(async (id, include) => {
+        if (!isInitialized || !sdk) {
+            throw new Error('SDK not initialized. Call initialize() first.');
+        }
+        try {
+            const result = await sdk.redemptions.getRedemptionById(id, include);
+            return result;
+        }
+        catch (error) {
+            console.error('Failed to fetch redemption by ID:', error);
+            throw error;
+        }
+    }, [sdk, isInitialized]);
     return {
         getRedemptions,
+        getRedemptionById,
         getUserRedemptions,
         redeem,
         getRedemptionTypes,