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

package/dist/providers/PersSDKProvider.d.ts

@@ -5,11 +5,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 {
     sdk: PersSDK | null;

package/dist/providers/PersSDKProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PersSDKProvider.d.ts","sourceRoot":"","sources":["../../src/providers/PersSDKProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAuC,SAAS,EAA2C,MAAM,OAAO,CAAC;AAEvH,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAIpF,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAkB3D,YAAY,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAE3D;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAE7B,GAAG,EAAE,OAAO,GAAG,IAAI,CAAC;IAGpB,YAAY,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAGzC,aAAa,EAAE,OAAO,CAAC;IACvB,eAAe,EAAE,OAAO,CAAC;IACzB,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,CAAC;IAGhC,UAAU,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,sBAAsB,EAAE,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,EAAE,eAAe,EAAE,OAAO,KAAK,IAAI,CAAC;IAC5F,eAAe,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,cAAc,EAAE,MAAM,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;CAC/C;AAKD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,eAAe,EAAE,KAAK,CAAC,EAAE,CAAC;IACrC,QAAQ,EAAE,SAAS,CAAC;IACpB,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB,CA6NA,CAAC;AAGF,eAAO,MAAM,UAAU,QAAO,cAQ7B,CAAC"}
+{"version":3,"file":"PersSDKProvider.d.ts","sourceRoot":"","sources":["../../src/providers/PersSDKProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAuC,SAAS,EAA2C,MAAM,OAAO,CAAC;AAEvH,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAIpF,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAkB3D,YAAY,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,MAAM,WAAW,cAAc;IAE7B,GAAG,EAAE,OAAO,GAAG,IAAI,CAAC;IAGpB,YAAY,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAGzC,aAAa,EAAE,OAAO,CAAC;IACvB,eAAe,EAAE,OAAO,CAAC;IACzB,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,CAAC;IAGhC,UAAU,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,sBAAsB,EAAE,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,EAAE,eAAe,EAAE,OAAO,KAAK,IAAI,CAAC;IAC5F,eAAe,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,cAAc,EAAE,MAAM,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;CAC/C;AAKD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,eAAe,EAAE,KAAK,CAAC,EAAE,CAAC;IACrC,QAAQ,EAAE,SAAS,CAAC;IACpB,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB,CA6NA,CAAC;AAGF,eAAO,MAAM,UAAU,QAAO,cAQ7B,CAAC"}

package/package.json

@@ -1,199 +1,199 @@
-{
-  "name": "@explorins/pers-sdk-react-native",
-  "version": "2.2.0",
-  "description": "React Native SDK for PERS Platform - Tourism Loyalty System with Blockchain Transaction Signing and WebAuthn Authentication",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "scripts": {
-    "build": "tsc && rollup -c --bundleConfigAsCjs",
-    "build:watch": "rollup -c --bundleConfigAsCjs --watch",
-    "dev": "tsc --watch",
-    "clean": "rimraf dist",
-    "docs": "typedoc",
-    "docs:dev": "typedoc --watch",
-    "docs:json": "typedoc --json docs/api.json",
-    "docs:serve": "npx http-server docs -p 8080",
-    "prepublishOnly": "npm run clean && npm run build",
-    "publish-version": "npm run clean && npm run build && npm version patch && npm publish",
-    "publish-with-docs": "npm run clean && npm run build && npm run docs && npm version patch && npm publish",
-    "yalc:publish": "npm version patch --no-git-tag-version && npm run build && yalc publish",
-    "yalc:push": "npm version patch --no-git-tag-version && npm run build && yalc push"
-  },
-  "keywords": [
-    "pers",
-    "sdk",
-    "react-native",
-    "tourism",
-    "loyalty",
-    "blockchain",
-    "web3",
-    "webauthn",
-    "transaction-signing",
-    "rewards",
-    "authentication",
-    "biometrics",
-    "secure-storage"
-  ],
-  "author": "eXplorins",
-  "license": "MIT",
-  "dependencies": {
-    "@explorins/pers-sdk": "^2.1.33",
-    "@explorins/pers-signer": "^1.0.34",
-    "buffer": "^6.0.3",
-    "ethers": "^6.15.0",
-    "react-native-url-polyfill": "^2.0.0"
-  },
-  "browser": {
-    "crypto": false,
-    "url": false,
-    "http": false,
-    "https": false,
-    "zlib": false,
-    "stream": false,
-    "assert": false,
-    "path": false,
-    "fs": false,
-    "os": false,
-    "readable-stream": false,
-    "util": false,
-    "events": false,
-    "net": false,
-    "tls": false,
-    "child_process": false,
-    "pngjs": false,
-    "pngjs/lib/bitmapper": false,
-    "pngjs/lib/parser-async": false,
-    "pngjs/lib/parser-sync": false,
-    "./bitmapper": false,
-    "hash-base": false,
-    "@ethereumjs/common": false,
-    "@ethereumjs/tx": false,
-    "@ethereumjs/util": false,
-    "stream-browserify": false,
-    "crypto-browserify": false,
-    "inherits": false,
-    "safe-buffer": false,
-    "string_decoder": false,
-    "process-nextick-args": false,
-    "isarray": false,
-    "core-util-is": false,
-    "util-deprecate": false,
-    "ethereum-cryptography": false,
-    "keccak": false,
-    "secp256k1": false,
-    "scrypt-js": false,
-    "bech32": false,
-    "ws": false,
-    "xhr2-cookies": false,
-    "aes-js": false,
-    "@ethersproject/sha2": false,
-    "@ethersproject/pbkdf2": false,
-    "@ethersproject/scrypt": false
-  },
-  "peerDependencies": {
-    "@react-native-async-storage/async-storage": ">=1.15.0",
-    "react": ">=16.8.0",
-    "react-native": ">=0.60.0",
-    "react-native-get-random-values": ">=1.8.0",
-    "react-native-keychain": ">=8.0.0",
-    "react-native-passkey": ">=3.0.0",
-    "react-native-quick-crypto": ">=0.7.5"
-  },
-  "peerDependenciesMeta": {
-    "@react-native-async-storage/async-storage": {
-      "optional": false
-    },
-    "react-native-get-random-values": {
-      "optional": false
-    },
-    "react-native-keychain": {
-      "optional": true
-    },
-    "react-native-passkey": {
-      "optional": true
-    },
-    "react-native-quick-crypto": {
-      "optional": false
-    },
-    "react-native-url-polyfill": {
-      "optional": true
-    },
-    "react-native-polyfill-globals": {
-      "optional": true
-    },
-    "web-streams-polyfill": {
-      "optional": true
-    }
-  },
-  "overrides": {
-    "readable-stream": false,
-    "@ethereumjs/common": false,
-    "@ethereumjs/util": false,
-    "@ethereumjs/rlp": false,
-    "@ethereumjs/tx": false,
-    "stream": false,
-    "util": false,
-    "events": false,
-    "crypto": false,
-    "fs": false,
-    "path": false,
-    "os": false,
-    "net": false,
-    "tls": false,
-    "child_process": false,
-    "hash-base": false,
-    "inherits": false,
-    "safe-buffer": false,
-    "string_decoder": false,
-    "process-nextick-args": false,
-    "isarray": false,
-    "core-util-is": false,
-    "util-deprecate": false,
-    "ethereum-cryptography": false,
-    "keccak": false,
-    "secp256k1": false,
-    "scrypt-js": false,
-    "bech32": false,
-    "ws": false,
-    "xhr2-cookies": false,
-    "aes-js": false,
-    "@ethersproject/sha2": false,
-    "@ethersproject/pbkdf2": false,
-    "@ethersproject/scrypt": false
-  },
-  "devDependencies": {
-    "@explorins/pers-shared": "^2.1.128",
-    "@react-native-async-storage/async-storage": "^3.0.2",
-    "@rollup/plugin-commonjs": "^25.0.7",
-    "@rollup/plugin-json": "^6.1.0",
-    "@rollup/plugin-node-resolve": "^15.2.3",
-    "@testing-library/dom": "^10.4.1",
-    "@testing-library/jest-dom": "^6.9.1",
-    "@testing-library/react": "^16.3.2",
-    "@types/jest": "^30.0.0",
-    "@types/react": "^19.1.1",
-    "@types/react-native": "^0.72.8",
-    "jest": "^30.3.0",
-    "jest-environment-jsdom": "^30.3.0",
-    "react": "^19.2.5",
-    "react-dom": "^19.2.5",
-    "react-native": "^0.85.3",
-    "rimraf": "^5.0.0",
-    "rollup": "^4.0.0",
-    "rollup-plugin-typescript2": "^0.36.0",
-    "ts-jest": "^29.4.9",
-    "typedoc": "^0.25.13",
-    "typedoc-plugin-markdown": "^3.17.1",
-    "typescript": "^5.2.0"
-  },
-  "files": [
-    "dist/**/*",
-    "src/**/*",
-    "README.md"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/eXplorins/pers-sdk.git",
-    "directory": "packages/pers-sdk-react-native"
-  }
-}
+{
+  "name": "@explorins/pers-sdk-react-native",
+  "version": "2.2.1",
+  "description": "React Native SDK for PERS Platform - Tourism Loyalty System with Blockchain Transaction Signing and WebAuthn Authentication",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc && rollup -c --bundleConfigAsCjs",
+    "build:watch": "rollup -c --bundleConfigAsCjs --watch",
+    "dev": "tsc --watch",
+    "clean": "rimraf dist",
+    "docs": "typedoc",
+    "docs:dev": "typedoc --watch",
+    "docs:json": "typedoc --json docs/api.json",
+    "docs:serve": "npx http-server docs -p 8080",
+    "prepublishOnly": "npm run clean && npm run build",
+    "publish-version": "npm run clean && npm run build && npm version patch && npm publish",
+    "publish-with-docs": "npm run clean && npm run build && npm run docs && npm version patch && npm publish",
+    "yalc:publish": "npm version patch --no-git-tag-version && npm run build && yalc publish",
+    "yalc:push": "npm version patch --no-git-tag-version && npm run build && yalc push"
+  },
+  "keywords": [
+    "pers",
+    "sdk",
+    "react-native",
+    "tourism",
+    "loyalty",
+    "blockchain",
+    "web3",
+    "webauthn",
+    "transaction-signing",
+    "rewards",
+    "authentication",
+    "biometrics",
+    "secure-storage"
+  ],
+  "author": "eXplorins",
+  "license": "MIT",
+  "dependencies": {
+    "@explorins/pers-sdk": "^2.1.37",
+    "@explorins/pers-signer": "^1.0.34",
+    "buffer": "^6.0.3",
+    "ethers": "^6.15.0",
+    "react-native-url-polyfill": "^2.0.0"
+  },
+  "browser": {
+    "crypto": false,
+    "url": false,
+    "http": false,
+    "https": false,
+    "zlib": false,
+    "stream": false,
+    "assert": false,
+    "path": false,
+    "fs": false,
+    "os": false,
+    "readable-stream": false,
+    "util": false,
+    "events": false,
+    "net": false,
+    "tls": false,
+    "child_process": false,
+    "pngjs": false,
+    "pngjs/lib/bitmapper": false,
+    "pngjs/lib/parser-async": false,
+    "pngjs/lib/parser-sync": false,
+    "./bitmapper": false,
+    "hash-base": false,
+    "@ethereumjs/common": false,
+    "@ethereumjs/tx": false,
+    "@ethereumjs/util": false,
+    "stream-browserify": false,
+    "crypto-browserify": false,
+    "inherits": false,
+    "safe-buffer": false,
+    "string_decoder": false,
+    "process-nextick-args": false,
+    "isarray": false,
+    "core-util-is": false,
+    "util-deprecate": false,
+    "ethereum-cryptography": false,
+    "keccak": false,
+    "secp256k1": false,
+    "scrypt-js": false,
+    "bech32": false,
+    "ws": false,
+    "xhr2-cookies": false,
+    "aes-js": false,
+    "@ethersproject/sha2": false,
+    "@ethersproject/pbkdf2": false,
+    "@ethersproject/scrypt": false
+  },
+  "peerDependencies": {
+    "@react-native-async-storage/async-storage": ">=1.15.0",
+    "react": ">=16.8.0",
+    "react-native": ">=0.60.0",
+    "react-native-get-random-values": ">=1.8.0",
+    "react-native-keychain": ">=8.0.0",
+    "react-native-passkey": ">=3.0.0",
+    "react-native-quick-crypto": ">=0.7.5"
+  },
+  "peerDependenciesMeta": {
+    "@react-native-async-storage/async-storage": {
+      "optional": false
+    },
+    "react-native-get-random-values": {
+      "optional": false
+    },
+    "react-native-keychain": {
+      "optional": true
+    },
+    "react-native-passkey": {
+      "optional": true
+    },
+    "react-native-quick-crypto": {
+      "optional": false
+    },
+    "react-native-url-polyfill": {
+      "optional": true
+    },
+    "react-native-polyfill-globals": {
+      "optional": true
+    },
+    "web-streams-polyfill": {
+      "optional": true
+    }
+  },
+  "overrides": {
+    "readable-stream": false,
+    "@ethereumjs/common": false,
+    "@ethereumjs/util": false,
+    "@ethereumjs/rlp": false,
+    "@ethereumjs/tx": false,
+    "stream": false,
+    "util": false,
+    "events": false,
+    "crypto": false,
+    "fs": false,
+    "path": false,
+    "os": false,
+    "net": false,
+    "tls": false,
+    "child_process": false,
+    "hash-base": false,
+    "inherits": false,
+    "safe-buffer": false,
+    "string_decoder": false,
+    "process-nextick-args": false,
+    "isarray": false,
+    "core-util-is": false,
+    "util-deprecate": false,
+    "ethereum-cryptography": false,
+    "keccak": false,
+    "secp256k1": false,
+    "scrypt-js": false,
+    "bech32": false,
+    "ws": false,
+    "xhr2-cookies": false,
+    "aes-js": false,
+    "@ethersproject/sha2": false,
+    "@ethersproject/pbkdf2": false,
+    "@ethersproject/scrypt": false
+  },
+  "devDependencies": {
+    "@explorins/pers-shared": "^2.1.128",
+    "@react-native-async-storage/async-storage": "^3.0.2",
+    "@rollup/plugin-commonjs": "^25.0.7",
+    "@rollup/plugin-json": "^6.1.0",
+    "@rollup/plugin-node-resolve": "^15.2.3",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/jest": "^30.0.0",
+    "@types/react": "^19.1.1",
+    "@types/react-native": "^0.72.8",
+    "jest": "^30.3.0",
+    "jest-environment-jsdom": "^30.3.0",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "react-native": "^0.85.3",
+    "rimraf": "^5.0.0",
+    "rollup": "^4.0.0",
+    "rollup-plugin-typescript2": "^0.36.0",
+    "ts-jest": "^29.4.9",
+    "typedoc": "^0.25.13",
+    "typedoc-plugin-markdown": "^3.17.1",
+    "typescript": "^5.2.0"
+  },
+  "files": [
+    "dist/**/*",
+    "src/**/*",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eXplorins/pers-sdk.git",
+    "directory": "packages/pers-sdk-react-native"
+  }
+}

package/src/hooks/useRedemptions.ts

@@ -164,6 +164,25 @@ export 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.
@@ -172,11 +191,21 @@ export 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)
@@ -207,6 +236,8 @@ export const useRedemptions = () => {
    *   }
    * });
    * ```
+   * 
+   * @see {@link useTransactions.createTransaction | createTransaction()} for direct transfers without redemption flow
    */
   const redeem = useCallback(async (
     redemptionId: string, 
@@ -368,8 +399,47 @@ export const useRedemptions = () => {
     }
   }, [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 = useCallback(async (
+    id: string,
+    include?: RedemptionIncludeRelation[]
+  ): Promise<RedemptionDTO> => {
+    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,

package/src/hooks/useTokenBalances.ts

@@ -10,9 +10,42 @@ import type { TokenBalance, TokenBalanceRequest } from '@explorins/pers-sdk/web3
  * This composite type combines blockchain balance data with token metadata,
  * making it easy to display token information in UI components without
  * needing to join data from multiple sources.
+ * 
+ * ## CRITICAL: Token ID for Transactions
+ * 
+ * For ERC721 (stamps) and ERC1155 (rewards), use `tokenBalance.tokenId` as the
+ * `contractTokenId` when creating transactions. This is the **on-chain token ID**
+ * assigned by the blockchain, NOT the metadata definition ID.
+ * 
+ * | Token Type | tokenId meaning | Example |
+ * |------------|-----------------|---------|
+ * | ERC20      | `null` or `""`  | N/A (fungible points) |
+ * | ERC721     | NFT instance ID | `"46"` (on-chain ID) |
+ * | ERC1155    | Token type ID   | `"16"` (semi-fungible type) |
+ * 
+ * @example Correct usage for token burn transaction
+ * ```typescript
+ * const stampBalance = tokenBalances.find(b => b.token.type === 'ERC721');
+ * 
+ * const request = buildPOSBurnRequest({
+ *   amount: 1,
+ *   contractAddress: stampBalance.token.contractAddress,
+ *   contractTokenId: stampBalance.tokenBalance.tokenId, // ✅ Correct
+ *   chainId: stampBalance.token.chainId,
+ *   userId: userId,
+ *   businessId: businessId
+ * });
+ * ```
+ * 
+ * @see {@link https://docs.explorins.com/pers-sdk/troubleshooting#stamp-voucher-transaction-fails | Troubleshooting: Stamp Transaction Fails}
  */
 export interface TokenBalanceWithToken {
-  /** The balance data from blockchain */
+  /** 
+   * The balance data from blockchain
+   * 
+   * **Important:** For NFT operations, use `tokenBalance.tokenId` as the `contractTokenId`
+   * in transaction requests. This is the actual on-chain ID, not the metadata definition.
+   */
   tokenBalance: TokenBalance;
   /** The token definition (contract, symbol, metadata, etc.) */
   token: TokenDTO;