@explorins/pers-sdk-react-native 2.0.1 → 2.0.2

package/dist/index.d.ts

@@ -240,10 +240,24 @@ export { initializeReactNativePolyfills } from './polyfills';
  * - Business and campaign types (BusinessDTO, CampaignDTO, etc.)
  * - API request/response types for all endpoints
  * - Error types and status enums
+ * - Utility functions for pagination, token display, etc.
  *
  * @see {@link https://github.com/eXplorins/pers-shared} - Shared library documentation
  */
 export * from '@explorins/pers-shared';
+/**
+ * Token utilities re-exported from token module
+ *
+ * @see {@link getMetadataFromTokenUnitResponse} - Get full metadata object from token unit
+ */
+export { getMetadataFromTokenUnitResponse } from '@explorins/pers-sdk/token';
+/**
+ * Shared SDK utilities re-exported from base SDK
+ *
+ * Includes helper functions for:
+ * - Pagination utilities (buildPaginationParams, extractData, etc.)
+ */
+export { buildPaginationParams, extractData, extractPagination, isPaginatedResponse, normalizeToPaginated, fetchAllPages, type PaginationOptions, type PaginationWithFilters, type ListResponse } from '@explorins/pers-sdk';
 /**
  * Re-export Web3 and blockchain-related types from base SDK
  *

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAGH,OAAO,aAAa,CAAC;AAMrB;;;;;;;;GAQG;AACH,OAAO,EACL,6BAA6B,EAC7B,KAAK,qBAAqB,EAC3B,MAAM,wCAAwC,CAAC;AAMhD;;;;;;;;;;GAUG;AACH,OAAO,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAEvE;;;;;;;;GAQG;AACH,OAAO,EACL,wBAAwB,GACzB,MAAM,uCAAuC,CAAC;AAM/C;;;GAGG;AACH,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAMvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,EACL,eAAe,EACf,UAAU,EACV,KAAK,UAAU,EACf,KAAK,cAAc,EACpB,MAAM,6BAA6B,CAAC;AAMrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0FG;AACH,OAAO,EACL,OAAO,EACP,SAAS,EACT,eAAe,EACf,oBAAoB,EACpB,aAAa,EACb,WAAW,EACX,YAAY,EACZ,cAAc,EACd,OAAO,EACP,YAAY,EACZ,UAAU,EACV,QAAQ,EACR,aAAa,EACb,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,SAAS,EACV,MAAM,SAAS,CAAC;AAGjB,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAGrF,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAM7F;;;;;;GAMG;AACH,OAAO,EACL,qBAAqB,EACtB,MAAM,sCAAsC,CAAC;AAM9C;;;;;;;;GAQG;AACH,OAAO,EACL,8BAA8B,EAC/B,MAAM,aAAa,CAAC;AAMrB;;;;;;;;;;;;;;;GAeG;AACH,cAAc,wBAAwB,CAAC;AAEvC;;;;;;;;;;;GAWG;AACH,YAAY,EACV,mBAAmB,EACnB,YAAY,EACZ,aAAa,EACb,eAAe,EACf,sBAAsB,EACvB,MAAM,0BAA0B,CAAC;AAMlC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,EACvB,mBAAmB,EACnB,sBAAsB,EACvB,MAAM,iCAAiC,CAAC;AAEzC,YAAY,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAM/E;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAGH,OAAO,aAAa,CAAC;AAMrB;;;;;;;;GAQG;AACH,OAAO,EACL,6BAA6B,EAC7B,KAAK,qBAAqB,EAC3B,MAAM,wCAAwC,CAAC;AAMhD;;;;;;;;;;GAUG;AACH,OAAO,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAEvE;;;;;;;;GAQG;AACH,OAAO,EACL,wBAAwB,GACzB,MAAM,uCAAuC,CAAC;AAM/C;;;GAGG;AACH,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAMvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,EACL,eAAe,EACf,UAAU,EACV,KAAK,UAAU,EACf,KAAK,cAAc,EACpB,MAAM,6BAA6B,CAAC;AAMrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0FG;AACH,OAAO,EACL,OAAO,EACP,SAAS,EACT,eAAe,EACf,oBAAoB,EACpB,aAAa,EACb,WAAW,EACX,YAAY,EACZ,cAAc,EACd,OAAO,EACP,YAAY,EACZ,UAAU,EACV,QAAQ,EACR,aAAa,EACb,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,SAAS,EACV,MAAM,SAAS,CAAC;AAGjB,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAGrF,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAM7F;;;;;;GAMG;AACH,OAAO,EACL,qBAAqB,EACtB,MAAM,sCAAsC,CAAC;AAM9C;;;;;;;;GAQG;AACH,OAAO,EACL,8BAA8B,EAC/B,MAAM,aAAa,CAAC;AAMrB;;;;;;;;;;;;;;;;GAgBG;AACH,cAAc,wBAAwB,CAAC;AAEvC;;;;GAIG;AACH,OAAO,EAAE,gCAAgC,EAAE,MAAM,2BAA2B,CAAC;AAE7E;;;;;GAKG;AACH,OAAO,EAEL,qBAAqB,EACrB,WAAW,EACX,iBAAiB,EACjB,mBAAmB,EACnB,oBAAoB,EACpB,aAAa,EACb,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,YAAY,EAClB,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;;;;GAWG;AACH,YAAY,EACV,mBAAmB,EACnB,YAAY,EACZ,aAAa,EACb,eAAe,EACf,sBAAsB,EACvB,MAAM,0BAA0B,CAAC;AAMlC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,EACvB,mBAAmB,EACnB,sBAAsB,EACvB,MAAM,iCAAiC,CAAC;AAEzC,YAAY,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAM/E;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/index.js

@@ -23381,6 +23381,43 @@ function isPaginatedResponse(response) {
         'data' in response &&
         'pagination' in response);
 }
+/**
+ * Extract data array from either array or paginated response
+ * Use during hybrid backend phase to safely handle both response shapes
+ *
+ * @param response - Either an array or paginated response
+ * @returns Data array
+ *
+ * @example
+ * ```typescript
+ * const response = await api.getItems(); // Could be T[] or PaginatedResponseDTO<T>
+ * const items = extractData(response);   // Always T[]
+ * ```
+ */
+function extractData(response) {
+    if (Array.isArray(response)) {
+        return response;
+    }
+    return (response?.data ?? []);
+}
+/**
+ * Extract pagination metadata (returns null for array responses)
+ *
+ * @param response - Either an array or paginated response
+ * @returns Pagination metadata or null
+ *
+ * @example
+ * ```typescript
+ * const response = await api.getItems();
+ * const pagination = extractPagination(response);
+ * if (pagination) {
+ *   console.log(`Total: ${pagination.total}`);
+ * }
+ * ```
+ */
+function extractPagination(response) {
+    return isPaginatedResponse(response) ? response.pagination : null;
+}
 /**
  * Normalize any list response to PaginatedResponseDTO format
  * Converts array responses to paginated format during hybrid backend phase
@@ -23419,6 +23456,39 @@ function normalizeToPaginated(response) {
         }
     };
 }
+/**
+ * Fetch all pages automatically (useful for infinite scroll or complete datasets)
+ *
+ * ⚠️ WARNING: Use with caution on large datasets. This will make multiple API calls
+ * and load all items into memory. Consider using pagination UI instead.
+ *
+ * @param fetchFn - Function that fetches a page (must return PaginatedResponseDTO)
+ * @param limit - Items per page (default: 50)
+ * @param maxPages - Safety limit to prevent infinite loops (default: 100)
+ * @returns All items from all pages
+ *
+ * @example
+ * ```typescript
+ * // Fetch all campaigns (use with caution!)
+ * const allCampaigns = await fetchAllPages(
+ *   (page, limit) => sdk.campaigns.getCampaigns({ page, limit }),
+ *   50,  // items per page
+ *   100  // max 100 pages (5000 items)
+ * );
+ * ```
+ */
+async function fetchAllPages(fetchFn, limit = 50, maxPages = 100) {
+    const allItems = [];
+    let page = 1;
+    let hasMore = true;
+    while (hasMore && page <= maxPages) {
+        const response = await fetchFn(page, limit);
+        allItems.push(...(response.data || []));
+        hasMore = response.pagination.hasNext;
+        page++;
+    }
+    return allItems;
+}
 
 /**
  * Platform-Agnostic User API Client
@@ -37458,6 +37528,69 @@ const useEvents = () => {
     };
 };
 
+// ==========================================
+// TOKEN UTILITY FUNCTIONS
+// ==========================================
+/**
+ * Get metadata from a token unit response
+ * Handles metadata-based tokens (ERC-1155 with metadata array)
+ *
+ * For metadata-based tokens:
+ * - Returns the metadata object from token.metadata array
+ * - Uses provided incrementalId or tokenMetadataIncrementalId from tokenUnit
+ * - Defaults to index 0 if no incrementalId specified
+ *
+ * For standard tokens (no metadata):
+ * - Returns null
+ *
+ * @param tokenUnit - The token unit from campaign or balance
+ * @param incrementalId - Optional metadata index to use (overrides tokenUnit.tokenMetadataIncrementalId)
+ * @returns Token metadata object or null
+ *
+ * @example
+ * ```typescript
+ * // Get metadata using tokenUnit's incrementalId
+ * const tokenUnit = {
+ *   tokenMetadataIncrementalId: 3,
+ *   token: {
+ *     metadata: [
+ *       { name: 'Bronze Pass', imageUrl: '...' },
+ *       { name: 'Silver Pass', imageUrl: '...' },
+ *       { name: 'Gold Pass', imageUrl: '...' }
+ *     ]
+ *   }
+ * };
+ * const metadata = getMetadataFromTokenUnitResponse(tokenUnit);
+ * // Returns: { name: 'Bronze Pass', imageUrl: '...' } (index 0 - default)
+ *
+ * // Override incrementalId
+ * const metadata2 = getMetadataFromTokenUnitResponse(tokenUnit, 2);
+ * // Returns: { name: 'Gold Pass', imageUrl: '...' } (index 2)
+ *
+ * // Standard token (no metadata)
+ * const tokenUnit2 = {
+ *   token: { symbol: 'VQP', name: 'Visit Qatar Points' }
+ * };
+ * const metadata3 = getMetadataFromTokenUnitResponse(tokenUnit2);
+ * // Returns: null
+ *
+ * // Display name with fallback
+ * const displayName = metadata?.name || tokenUnit.token?.symbol || 'Reward';
+ *
+ * // Display image
+ * const imageUrl = metadata?.imageUrl;
+ * ```
+ */
+function getMetadataFromTokenUnitResponse(tokenUnit, incrementalId) {
+    // If no metadata array exists, return null
+    if (!tokenUnit.token?.metadata || tokenUnit.token.metadata.length === 0) {
+        return null;
+    }
+    // Use provided incrementalId, or tokenUnit's incrementalId, or default to 0
+    const index = incrementalId ?? tokenUnit.tokenMetadataIncrementalId ?? 0;
+    return tokenUnit.token.metadata[index] ?? null;
+}
+
 // ============================================================================
 // SHARED HELPERS (internal)
 // ============================================================================
@@ -37770,14 +37903,21 @@ exports.buildBurnRequest = buildBurnRequest;
 exports.buildMintRequest = buildMintRequest;
 exports.buildPOSBurnRequest = buildPOSBurnRequest;
 exports.buildPOSTransferRequest = buildPOSTransferRequest;
+exports.buildPaginationParams = buildPaginationParams;
 exports.buildSubmissionRequest = buildSubmissionRequest;
 exports.buildTransferRequest = buildTransferRequest;
 exports.createReactNativeAuthProvider = createReactNativeAuthProvider;
 exports.createUserIdentifierObject = createUserIdentifierObject;
 exports.detectIdentifierType = detectIdentifierType;
+exports.extractData = extractData;
+exports.extractPagination = extractPagination;
+exports.fetchAllPages = fetchAllPages;
+exports.getMetadataFromTokenUnitResponse = getMetadataFromTokenUnitResponse;
 exports.hasMinimumRole = hasMinimumRole;
 exports.initializeReactNativePolyfills = initializeReactNativePolyfills;
+exports.isPaginatedResponse = isPaginatedResponse;
 exports.isUserIdentifierObject = isUserIdentifierObject;
+exports.normalizeToPaginated = normalizeToPaginated;
 exports.registerIdentifierType = registerIdentifierType;
 exports.testnetPrefix = testnetPrefix;
 exports.testnetShortPrefix = testnetShortPrefix;