@explorins/pers-sdk 1.6.40 → 1.6.41

package/README.md

@@ -427,6 +427,117 @@ const statusTokens = await sdk.tokens.getStatusTokens();
 const token = await sdk.tokens.getTokenByContract('0x123...', 'token-id');
 ```
 
+### User Token Balances (On-Chain)
+
+> **Important Architecture Note:** The PERS backend stores **token definitions** (contract addresses, ABIs, metadata), but does **NOT** store user token balances. User balances are queried directly from the blockchain via RPC calls using `sdk.web3.*` methods.
+
+**Data Flow:**
+1. `sdk.tokens.*` → Get token definitions (contract address, ABI, chainId) from PERS backend
+2. `sdk.auth.getCurrentUser()` → Get user's wallet address
+3. `sdk.web3.*` → Query blockchain directly for user's token balance
+
+#### Points Balance (ERC-20)
+
+```typescript
+// Step 1: Get the credit token definition from PERS backend
+const creditToken = await sdk.tokens.getActiveCreditToken();
+
+// Step 2: Get user's wallet address
+const user = await sdk.auth.getCurrentUser();
+const walletAddress = user.wallets?.[0]?.address;
+
+// Step 3: Query blockchain directly for balance
+const balance = await sdk.web3.getTokenBalance({
+  accountAddress: walletAddress,
+  contractAddress: creditToken.contractAddress,
+  abi: creditToken.abi,  // Raw ABI from backend works directly
+  chainId: creditToken.chainId,
+  tokenId: ''  // Empty for ERC-20
+});
+
+console.log('Points balance:', balance.balance);
+console.log('Has balance:', balance.hasBalance);
+```
+
+#### Stamps Collection (ERC-721 / ERC-1155)
+
+```typescript
+// Step 1: Get status token definitions (stamps/achievements)
+const statusTokens = await sdk.tokens.getStatusTokens();
+
+// Step 2: Get user's wallet address  
+const user = await sdk.auth.getCurrentUser();
+const walletAddress = user.wallets?.[0]?.address;
+
+// Step 3: Query blockchain for user's stamp collection
+for (const stampToken of statusTokens) {
+  const collection = await sdk.web3.getTokenCollection({
+    accountAddress: walletAddress,
+    contractAddress: stampToken.contractAddress,
+    abi: stampToken.abi,  // Raw ABI from backend works directly
+    chainId: stampToken.chainId,
+    maxTokens: 50  // Optional: limit results
+  });
+
+  // Filter to tokens with balance > 0
+  const ownedStamps = collection.tokens.filter(t => t.hasBalance && t.balance > 0);
+  
+  console.log(`Stamps from ${stampToken.symbol}:`, ownedStamps.length);
+  
+  // Each stamp includes metadata (name, description, image, etc.)
+  for (const stamp of ownedStamps) {
+    console.log(`- Token #${stamp.tokenId}: ${stamp.metadata?.name}`);
+    console.log(`  Image: ${stamp.metadata?.imageUrl}`);
+  }
+}
+```
+
+#### Complete Example: Load All User Balances
+
+```typescript
+async function loadUserTokenBalances(sdk: PersSDK) {
+  // Get user wallet
+  const user = await sdk.auth.getCurrentUser();
+  const walletAddress = user.wallets?.[0]?.address;
+  if (!walletAddress) throw new Error('User has no wallet');
+
+  // Get all token definitions
+  const [creditToken, statusTokens, rewardTokens] = await Promise.all([
+    sdk.tokens.getActiveCreditToken(),
+    sdk.tokens.getStatusTokens(),
+    sdk.tokens.getRewardTokens()
+  ]);
+
+  // Query ERC-20 balance (Points)
+  const pointsBalance = creditToken ? await sdk.web3.getTokenBalance({
+    accountAddress: walletAddress,
+    contractAddress: creditToken.contractAddress,
+    abi: creditToken.abi,
+    chainId: creditToken.chainId,
+    tokenId: ''
+  }) : null;
+
+  // Query ERC-721/ERC-1155 collections (Stamps, Rewards)
+  const allNftTokens = [...(statusTokens || []), ...(rewardTokens || [])];
+  const collections = await Promise.all(
+    allNftTokens.map(token => 
+      sdk.web3.getTokenCollection({
+        accountAddress: walletAddress,
+        contractAddress: token.contractAddress,
+        abi: token.abi,
+        chainId: token.chainId,
+        maxTokens: 100
+      }).catch(() => null)  // Handle individual failures gracefully
+    )
+  );
+
+  return {
+    points: pointsBalance,
+    stamps: collections.filter(Boolean)
+  };
+}
+```
+
 ### Purchase/Payment Processing
 
 ```typescript

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@explorins/pers-sdk",
-  "version": "1.6.40",
+  "version": "1.6.41",
   "description": "Platform-agnostic SDK for PERS (Phygital Experience Rewards System) - Core business logic and API integration",
   "type": "module",
   "main": "./dist/index.cjs",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@explorins/pers-sdk",
-  "version": "1.6.40",
+  "version": "1.6.41",
   "description": "Platform-agnostic SDK for PERS (Phygital Experience Rewards System) - Core business logic and API integration",
   "type": "module",
   "main": "./dist/index.cjs",