@explorins/pers-sdk-react-native 2.1.21 → 2.1.22

package/dist/index.js

@@ -8500,6 +8500,100 @@ class TenantManager {
     clearCache() {
         this.cache.clear();
     }
+    // ==========================================
+    // IPFS OPERATIONS (Lightweight, no Web3 deps)
+    // ==========================================
+    /**
+     * Get the IPFS gateway domain from tenant config (cached)
+     *
+     * @returns Promise resolving to IPFS gateway domain (e.g., 'gateway.pinata.cloud')
+     * @example
+     * ```typescript
+     * const gateway = await sdk.tenants.getIpfsGatewayDomain();
+     * // Returns 'gateway.pinata.cloud' or tenant-specific gateway
+     * ```
+     */
+    async getIpfsGatewayDomain() {
+        return this.cache.getOrSet('ipfsGateway', async () => {
+            const config = await this.getClientConfig();
+            return config.ipfsGatewayDomain || 'gateway.pinata.cloud';
+        }, CacheTTL.LONG);
+    }
+    /**
+     * Resolve an IPFS URL to an HTTP gateway URL
+     *
+     * @param url - The URL to resolve (ipfs://, ar://, or HTTP URL)
+     * @returns Promise resolving to HTTP gateway URL
+     *
+     * @example
+     * ```typescript
+     * const httpUrl = await sdk.tenants.resolveIpfsUrl('ipfs://QmXxx...');
+     * // Returns 'https://gateway.pinata.cloud/ipfs/QmXxx...'
+     * ```
+     */
+    async resolveIpfsUrl(url) {
+        if (!url)
+            return '';
+        // Already an HTTP URL
+        if (url.startsWith('http://') || url.startsWith('https://')) {
+            return url;
+        }
+        const gateway = await this.getIpfsGatewayDomain();
+        // Handle ipfs:// protocol
+        if (url.startsWith('ipfs://')) {
+            const cid = url.replace('ipfs://', '');
+            return `https://${gateway}/ipfs/${cid}`;
+        }
+        // Handle ar:// (Arweave) protocol
+        if (url.startsWith('ar://')) {
+            const txId = url.replace('ar://', '');
+            return `https://arweave.net/${txId}`;
+        }
+        return url;
+    }
+    /**
+     * Fetch and process token metadata from IPFS/HTTP URI
+     *
+     * @param tokenUri - The token URI (ipfs://, ar://, or HTTP)
+     * @returns Promise resolving to processed metadata or null on error
+     *
+     * @example
+     * ```typescript
+     * const metadata = await sdk.tenants.fetchAndProcessMetadata('ipfs://QmXxx.../metadata.json');
+     * if (metadata) {
+     *   console.log(metadata.name, metadata.imageUrl);
+     * }
+     * ```
+     */
+    async fetchAndProcessMetadata(tokenUri) {
+        try {
+            const resolvedUri = await this.resolveIpfsUrl(tokenUri);
+            const response = await fetch(resolvedUri);
+            if (!response.ok) {
+                console.warn(`Failed to fetch metadata from ${resolvedUri}: ${response.status}`);
+                return null;
+            }
+            const rawMetadata = await response.json();
+            // Normalize the metadata - resolve image URLs
+            const imageUrl = rawMetadata.image || rawMetadata.image_url || rawMetadata.imageUrl || '';
+            const resolvedImageUrl = await this.resolveIpfsUrl(imageUrl);
+            const animationUrl = rawMetadata.animation_url || rawMetadata.animationUrl || '';
+            const resolvedAnimationUrl = animationUrl ? await this.resolveIpfsUrl(animationUrl) : undefined;
+            return {
+                name: rawMetadata.name || 'Untitled',
+                description: rawMetadata.description || '',
+                imageUrl: resolvedImageUrl,
+                animationUrl: resolvedAnimationUrl,
+                externalUrl: rawMetadata.external_url || rawMetadata.externalUrl,
+                attributes: rawMetadata.attributes,
+                ...rawMetadata // Include any additional properties
+            };
+        }
+        catch (error) {
+            console.warn(`Error fetching metadata from ${tokenUri}:`, error);
+            return null;
+        }
+    }
 }
 
 /**
@@ -40915,19 +41009,11 @@ async function getExplorerUrlByChainId(getChainData, chainId, address, type) {
  *
  * ## IPFS Resolution
  *
- * Use `sdk.web3.resolveIPFSUrl()` to resolve IPFS URLs to HTTPS:
- *
- * ```typescript
- * const httpsUrl = await sdk.web3.resolveIPFSUrl('ipfs://QmXxx.../image.png');
- * // Returns: 'https://pers.mypinata.cloud/ipfs/QmXxx.../image.png'
- * ```
- *
- * Or fetch full metadata with resolved URLs:
+ * **Note:** IPFS is chain-agnostic. Use `sdk.tenants` for IPFS operations:
  *
  * ```typescript
- * const metadata = await sdk.web3.fetchAndProcessMetadata('ipfs://QmXxx.../metadata.json');
- * // All IPFS URLs in metadata are resolved to HTTPS
- * // Returns SDK format: { imageUrl, animationUrl, externalUrl, ... }
+ * const httpsUrl = await sdk.tenants.resolveIpfsUrl('ipfs://QmXxx.../image.png');
+ * const metadata = await sdk.tenants.fetchAndProcessMetadata('ipfs://QmXxx.../metadata.json');
  * ```
  */
 class Web3Manager {
@@ -40982,48 +41068,10 @@ class Web3Manager {
      *
      * @param tokenUri - Token URI to fetch metadata from
      * @returns Promise resolving to processed metadata or null if not found
+     * @deprecated Use sdk.tenants.fetchAndProcessMetadata() instead - IPFS is chain-agnostic
      */
     async fetchAndProcessMetadata(tokenUri) {
-        return this.web3ApplicationService.fetchAndProcessMetadata(tokenUri);
-    }
-    // ==========================================
-    // IPFS OPERATIONS
-    // ==========================================
-    /**
-     * Resolve IPFS URL to HTTPS URL using tenant's configured gateway.
-     *
-     * @param url - URL to resolve (can be ipfs:// or https://)
-     * @returns Resolved HTTPS URL
-     * @throws Error if tenant's ipfsGatewayDomain is not configured
-     *
-     * @example
-     * ```typescript
-     * const imageUrl = await sdk.web3.resolveIPFSUrl('ipfs://QmXxx.../image.png');
-     * // Returns: 'https://pers.mypinata.cloud/ipfs/QmXxx.../image.png'
-     *
-     * // Non-IPFS URLs pass through unchanged
-     * const httpUrl = await sdk.web3.resolveIPFSUrl('https://example.com/image.png');
-     * // Returns: 'https://example.com/image.png'
-     * ```
-     */
-    async resolveIPFSUrl(url) {
-        return this.web3ApplicationService.resolveIPFSUrl(url);
-    }
-    /**
-     * Get IPFS gateway domain from tenant configuration.
-     * Useful for pipes that need to resolve URLs synchronously after initial fetch.
-     *
-     * @returns Gateway domain (e.g., 'pers.mypinata.cloud')
-     * @throws Error if tenant's ipfsGatewayDomain is not configured
-     *
-     * @example
-     * ```typescript
-     * const gateway = await sdk.web3.getIpfsGatewayDomain();
-     * // Use gateway for sync resolution: `https://${gateway}/ipfs/${cid}`
-     * ```
-     */
-    async getIpfsGatewayDomain() {
-        return this.web3ApplicationService.getIpfsGatewayDomain();
+        return this.tenantManager.fetchAndProcessMetadata(tokenUri);
     }
     /**
      * Get blockchain chain data by chain ID
@@ -41334,6 +41382,8 @@ const useWeb3 = () => {
      * Converts an ipfs:// URL to an HTTPS URL using the tenant's configured IPFS gateway.
      * Non-IPFS URLs are returned unchanged.
      *
+     * Note: Uses sdk.tenants for IPFS resolution (chain-agnostic).
+     *
      * @param url - IPFS URL to resolve (ipfs://...)
      * @returns Promise resolving to HTTP gateway URL
      *
@@ -41345,37 +41395,39 @@ const useWeb3 = () => {
      * ```
      */
     const resolveIPFSUrl = react.useCallback(async (url) => {
-        if (!isInitialized || !web3) {
+        if (!isInitialized || !sdk) {
             throw new Error('SDK not initialized. Call initialize() first.');
         }
         try {
-            const result = await web3.resolveIPFSUrl(url);
+            const result = await sdk.tenants.resolveIpfsUrl(url);
             return result;
         }
         catch (error) {
             console.error('Failed to resolve IPFS URL:', error);
             throw error;
         }
-    }, [web3, isInitialized]);
+    }, [sdk, isInitialized]);
     /**
      * Fetch and process token metadata from a URI
      *
+     * Note: Uses sdk.tenants for metadata fetching (chain-agnostic IPFS).
+     *
      * @param tokenUri - Token URI to fetch metadata from
      * @returns Promise resolving to processed metadata or null
      */
     const fetchAndProcessMetadata = react.useCallback(async (tokenUri) => {
-        if (!isInitialized || !web3) {
+        if (!isInitialized || !sdk) {
             throw new Error('SDK not initialized. Call initialize() first.');
         }
         try {
-            const result = await web3.fetchAndProcessMetadata(tokenUri);
+            const result = await sdk.tenants.fetchAndProcessMetadata(tokenUri);
             return result;
         }
         catch (error) {
             console.error('Failed to fetch and process metadata:', error);
             throw error;
         }
-    }, [web3, isInitialized]);
+    }, [sdk, isInitialized]);
     const getChainDataById = react.useCallback(async (chainId) => {
         if (!isInitialized || !web3) {
             throw new Error('SDK not initialized. Call initialize() first.');
@@ -44099,6 +44151,181 @@ const useRedemptions = () => {
     };
 };
 
+/**
+ * React hook for resolving media URLs (IPFS or HTTPS).
+ *
+ * Automatically handles IPFS URLs by resolving them to HTTPS via tenant's gateway.
+ * Non-IPFS URLs are returned as-is. Handles loading and error states.
+ *
+ * Uses sdk.tenants for IPFS resolution (lightweight, no Web3 deps).
+ *
+ * @param url - The URL to resolve (can be ipfs://, https://, or undefined)
+ * @returns Object with resolved URL, loading state, and error
+ *
+ * @example
+ * ```tsx
+ * function NFTImage({ metadataUri }: { metadataUri?: string }) {
+ *   const { url, isLoading } = useResolvedUrl(metadataUri);
+ *
+ *   if (isLoading) return <ActivityIndicator />;
+ *   return <Image source={{ uri: url }} />;
+ * }
+ * ```
+ */
+function useResolvedUrl(url) {
+    const { sdk, isInitialized } = usePersSDK();
+    const [resolvedUrl, setResolvedUrl] = react.useState(null);
+    const [isLoading, setIsLoading] = react.useState(false);
+    const [error, setError] = react.useState(null);
+    react.useEffect(() => {
+        if (!url || !isInitialized || !sdk) {
+            setResolvedUrl(null);
+            return;
+        }
+        // Non-IPFS URLs don't need resolution
+        if (!url.startsWith('ipfs://')) {
+            setResolvedUrl(url);
+            return;
+        }
+        setIsLoading(true);
+        setError(null);
+        sdk.tenants.resolveIpfsUrl(url)
+            .then((resolved) => {
+            setResolvedUrl(resolved);
+        })
+            .catch((err) => {
+            setError(err instanceof Error ? err.message : 'Failed to resolve URL');
+            setResolvedUrl(null);
+        })
+            .finally(() => {
+            setIsLoading(false);
+        });
+    }, [url, isInitialized, sdk]);
+    return {
+        /** Resolved HTTPS URL (or original if not IPFS) */
+        url: resolvedUrl,
+        /** Whether resolution is in progress */
+        isLoading,
+        /** Error message if resolution failed */
+        error,
+    };
+}
+/**
+ * React hook for fetching NFT/token metadata from a URI.
+ *
+ * Handles IPFS resolution automatically and returns parsed metadata
+ * with all nested IPFS URLs already resolved to HTTPS.
+ *
+ * Uses sdk.tenants for metadata fetching (lightweight, no Web3 deps).
+ *
+ * @param metadataUri - The metadata URI to fetch (can be ipfs:// or https://)
+ * @returns Object with metadata, loading state, error, and refresh function
+ *
+ * @example
+ * ```tsx
+ * function NFTDetails({ metadataUri }: { metadataUri?: string }) {
+ *   const { metadata, isLoading, error } = useMetadata(metadataUri);
+ *
+ *   if (isLoading) return <ActivityIndicator />;
+ *   if (error) return <Text>Error: {error}</Text>;
+ *   if (!metadata) return null;
+ *
+ *   return (
+ *     <View>
+ *       <Image source={{ uri: metadata.imageUrl }} />
+ *       <Text>{metadata.name}</Text>
+ *       <Text>{metadata.description}</Text>
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+function useMetadata(metadataUri) {
+    const { sdk, isInitialized } = usePersSDK();
+    const [metadata, setMetadata] = react.useState(null);
+    const [isLoading, setIsLoading] = react.useState(false);
+    const [error, setError] = react.useState(null);
+    const fetchMetadata = react.useCallback(async () => {
+        if (!metadataUri || !isInitialized || !sdk) {
+            setMetadata(null);
+            return;
+        }
+        setIsLoading(true);
+        setError(null);
+        try {
+            const result = await sdk.tenants.fetchAndProcessMetadata(metadataUri);
+            setMetadata(result);
+        }
+        catch (err) {
+            setError(err instanceof Error ? err.message : 'Failed to fetch metadata');
+            setMetadata(null);
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [metadataUri, isInitialized, sdk]);
+    react.useEffect(() => {
+        fetchMetadata();
+    }, [fetchMetadata]);
+    return {
+        /** Parsed metadata with resolved IPFS URLs (imageUrl, animationUrl, etc.) */
+        metadata,
+        /** Whether fetch is in progress */
+        isLoading,
+        /** Error message if fetch failed */
+        error,
+        /** Manually refresh metadata */
+        refresh: fetchMetadata,
+    };
+}
+/**
+ * React hook for loading transaction/token metadata.
+ *
+ * Convenience wrapper around useMetadata specifically for transaction items.
+ * Pass a transaction's metadataUri to get the NFT image, name, description, etc.
+ *
+ * @param transaction - Transaction object with optional metadataUri field
+ * @returns Object with metadata, loading state, and image URL
+ *
+ * @example
+ * ```tsx
+ * import { useTransactionMetadata } from '@explorins/pers-sdk-react-native';
+ *
+ * function TransactionItem({ tx }: { tx: TransactionDTO }) {
+ *   const { metadata, isLoading, imageUrl } = useTransactionMetadata(tx);
+ *
+ *   if (isLoading) return <ActivityIndicator />;
+ *
+ *   return (
+ *     <View>
+ *       {imageUrl && <Image source={{ uri: imageUrl }} style={{ width: 60, height: 60 }} />}
+ *       <Text>{metadata?.name || tx.type}</Text>
+ *       <Text>{tx.amount} tokens</Text>
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+function useTransactionMetadata(transaction) {
+    const { metadata, isLoading, error, refresh } = useMetadata(transaction?.metadataUri);
+    return {
+        /** Parsed metadata with resolved URLs */
+        metadata,
+        /** Whether metadata is loading */
+        isLoading,
+        /** Error message if fetch failed */
+        error,
+        /** Convenience: resolved image URL (or undefined) */
+        imageUrl: metadata?.imageUrl,
+        /** Convenience: token/NFT name (or undefined) */
+        name: metadata?.name,
+        /** Convenience: token/NFT description (or undefined) */
+        description: metadata?.description,
+        /** Manually refresh metadata */
+        refresh,
+    };
+}
+
 const usePurchases = () => {
     const { sdk, isInitialized, isAuthenticated } = usePersSDK();
     const createPaymentIntent = react.useCallback(async (amount, currency, receiptEmail, description) => {
@@ -45677,12 +45904,16 @@ exports.useCampaigns = useCampaigns;
 exports.useDonations = useDonations;
 exports.useEvents = useEvents;
 exports.useFiles = useFiles;
+exports.useIPFSUrl = useResolvedUrl;
+exports.useMetadata = useMetadata;
 exports.usePersSDK = usePersSDK;
 exports.usePurchases = usePurchases;
 exports.useRedemptions = useRedemptions;
+exports.useResolvedUrl = useResolvedUrl;
 exports.useTenants = useTenants;
 exports.useTokenBalances = useTokenBalances;
 exports.useTokens = useTokens;
+exports.useTransactionMetadata = useTransactionMetadata;
 exports.useTransactionSigner = useTransactionSigner;
 exports.useTransactions = useTransactions;
 exports.useTriggerSources = useTriggerSources;