@explorins/pers-sdk-react-native 2.2.0-beta.1 → 2.2.1

package/README.md

@@ -1127,11 +1127,19 @@ All documentation is available on GitHub:
 | Guide | Description |
 |-------|-------------|
 | [Quick Setup Guide](https://github.com/eXplorins/pers-sdk/blob/main/packages/pers-sdk-react-native/docs/QUICK_SETUP_GUIDE.md) | Android + Passkey setup in one page |
+| [**Troubleshooting**](https://github.com/eXplorins/pers-sdk/blob/main/packages/pers-sdk-react-native/docs/TROUBLESHOOTING.md) | **Common issues & solutions** |
 | [Passkey Setup](https://github.com/eXplorins/pers-sdk/blob/main/packages/pers-sdk-react-native/REACT_NATIVE_PASSKEY_SETUP.md) | WebAuthn/Passkey configuration |
 | [Android Compatibility](https://github.com/eXplorins/pers-sdk/blob/main/packages/pers-sdk-react-native/docs/ANDROID_COMPATIBILITY_FAQ.md) | New Architecture troubleshooting |
 | [Auth State Handling](https://github.com/eXplorins/pers-sdk/blob/main/packages/pers-sdk-react-native/docs/AUTH_STATE_HANDLING.md) | Session management patterns |
 | [Changelog](https://github.com/eXplorins/pers-sdk/blob/main/packages/pers-sdk-react-native/CHANGELOG.md) | Version history |
 
+### Quick Reference: Common Issues
+
+- **User is null after restart?** → Session restoration is async. [See solution](./docs/TROUBLESHOOTING.md#1-sdkuser-is-null-after-app-restart)
+- **Stamp transaction fails?** → Use `tokenBalance.tokenId`, not metadata ID. [See solution](./docs/TROUBLESHOOTING.md#3-stamp-erc721-voucher-transaction-fails)
+- **Which wallet to use?** → Match by `token.chainId`, never use `wallets[0]`. [See solution](./docs/TROUBLESHOOTING.md#6-which-wallet-to-use-multiple-wallets)
+- **Passkey "NotConfigured"?** → Device needs Google Play Services. [See solution](./docs/TROUBLESHOOTING.md#2-passkey-notconfigured-error-on-android)
+
 ---
 
 ## Contributing

package/dist/__tests__/PersSDKProvider.test.d.ts

@@ -0,0 +1,2 @@
+import '@testing-library/jest-dom';
+//# sourceMappingURL=PersSDKProvider.test.d.ts.map

package/dist/__tests__/PersSDKProvider.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PersSDKProvider.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/PersSDKProvider.test.tsx"],"names":[],"mappings":"AAEA,OAAO,2BAA2B,CAAC"}

package/dist/__tests__/PersSDKProvider.test.js

@@ -0,0 +1,290 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import React from 'react';
+import { render, act, waitFor } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { PersSDKProvider, usePersSDK } from '../providers/PersSDKProvider';
+// Store SDK instances for event emission
+let mockSdkInstance = null;
+// Mock the SDK core module BEFORE any imports use it
+jest.mock('@explorins/pers-sdk/core', () => {
+    const createMockEventEmitter = () => {
+        const subscribers = [];
+        return {
+            subscribe: jest.fn((callback, options) => {
+                subscribers.push({ callback, options });
+                return () => {
+                    const index = subscribers.findIndex(s => s.callback === callback);
+                    if (index > -1)
+                        subscribers.splice(index, 1);
+                };
+            }),
+            emit: (event) => {
+                subscribers.forEach(({ callback, options }) => {
+                    if (!options?.domains || options.domains.includes(event.domain)) {
+                        callback(event);
+                    }
+                });
+            },
+            _subscribers: subscribers
+        };
+    };
+    const MockPersSDK = jest.fn().mockImplementation(() => {
+        const events = createMockEventEmitter();
+        mockSdkInstance = {
+            events,
+            auth: {
+                ensureValidToken: jest.fn().mockResolvedValue(true)
+            },
+            users: {
+                getCurrentUser: jest.fn().mockResolvedValue({ id: 'refreshed-user', email: 'refreshed@test.com' })
+            },
+            restoreSession: jest.fn().mockResolvedValue(null)
+        };
+        return mockSdkInstance;
+    });
+    return {
+        PersSDK: MockPersSDK,
+        DefaultAuthProvider: jest.fn().mockImplementation(() => ({
+            getToken: jest.fn().mockResolvedValue('mock-token')
+        }))
+    };
+});
+// Mock platform-specific providers
+jest.mock('../providers/react-native-http-client', () => ({
+    ReactNativeHttpClient: jest.fn().mockImplementation(() => ({}))
+}));
+jest.mock('../providers/react-native-auth-provider', () => ({
+    createReactNativeAuthProvider: jest.fn().mockReturnValue({
+        getToken: jest.fn().mockResolvedValue('mock-token')
+    })
+}));
+jest.mock('../providers/rn-dpop-provider', () => ({
+    ReactNativeDPoPProvider: jest.fn().mockImplementation(() => ({}))
+}));
+// Helper component to access context
+const TestConsumer = ({ onContext }) => {
+    const context = usePersSDK();
+    React.useEffect(() => {
+        onContext(context);
+    }, [context, onContext]);
+    return _jsx("div", { "data-testid": "consumer", children: "Consumer" });
+};
+// Helper to emit events on the mock SDK
+const emitAuthEvent = (type, details = {}) => {
+    if (mockSdkInstance?.events) {
+        mockSdkInstance.events.emit({
+            type,
+            domain: 'authentication',
+            details
+        });
+    }
+};
+describe('PersSDKProvider', () => {
+    beforeEach(() => {
+        jest.clearAllMocks();
+        mockSdkInstance = null;
+    });
+    describe('initialization', () => {
+        it('should initialize with null SDK when no config provided', async () => {
+            let capturedContext = null;
+            render(_jsx(PersSDKProvider, { children: _jsx(TestConsumer, { onContext: (ctx) => { capturedContext = ctx; } }) }));
+            await waitFor(() => {
+                expect(capturedContext).not.toBeNull();
+            });
+            expect(capturedContext.sdk).toBeNull();
+            expect(capturedContext.isInitialized).toBe(false);
+            expect(capturedContext.isAuthenticated).toBe(false);
+            expect(capturedContext.user).toBeNull();
+        });
+        it('should auto-initialize when config is provided', async () => {
+            let capturedContext = null;
+            render(_jsx(PersSDKProvider, { config: { apiProjectKey: 'test-project' }, children: _jsx(TestConsumer, { onContext: (ctx) => { capturedContext = ctx; } }) }));
+            await waitFor(() => {
+                expect(capturedContext?.isInitialized).toBe(true);
+            });
+            expect(capturedContext.sdk).not.toBeNull();
+        });
+        it('should prevent multiple initializations', async () => {
+            const { PersSDK } = require('@explorins/pers-sdk/core');
+            let capturedContext = null;
+            render(_jsx(PersSDKProvider, { config: { apiProjectKey: 'test-project' }, children: _jsx(TestConsumer, { onContext: (ctx) => { capturedContext = ctx; } }) }));
+            await waitFor(() => {
+                expect(capturedContext?.isInitialized).toBe(true);
+            });
+            // Try to initialize again - should be ignored
+            await act(async () => {
+                await capturedContext.initialize({ apiProjectKey: 'different-project' });
+            });
+            // Should only have been called once
+            expect(PersSDK).toHaveBeenCalledTimes(1);
+        });
+    });
+    describe('event handling', () => {
+        it('should set user on session_restored event', async () => {
+            let capturedContext = null;
+            const mockUser = { id: 'user-123', email: 'test@example.com' };
+            render(_jsx(PersSDKProvider, { config: { apiProjectKey: 'test-project' }, children: _jsx(TestConsumer, { onContext: (ctx) => { capturedContext = ctx; } }) }));
+            await waitFor(() => {
+                expect(capturedContext?.sdk).not.toBeNull();
+            });
+            // Emit session_restored event
+            await act(async () => {
+                emitAuthEvent('session_restored', { user: mockUser });
+            });
+            await waitFor(() => {
+                expect(capturedContext?.isAuthenticated).toBe(true);
+                expect(capturedContext?.user).toEqual(mockUser);
+            });
+        });
+        it('should set user on login_success event', async () => {
+            let capturedContext = null;
+            const mockUser = { id: 'user-456', email: 'login@example.com' };
+            render(_jsx(PersSDKProvider, { config: { apiProjectKey: 'test-project' }, children: _jsx(TestConsumer, { onContext: (ctx) => { capturedContext = ctx; } }) }));
+            await waitFor(() => {
+                expect(capturedContext?.sdk).not.toBeNull();
+            });
+            await act(async () => {
+                emitAuthEvent('login_success', { user: mockUser });
+            });
+            await waitFor(() => {
+                expect(capturedContext?.isAuthenticated).toBe(true);
+                expect(capturedContext?.user).toEqual(mockUser);
+            });
+        });
+        it('should clear user on logout_success event', async () => {
+            let capturedContext = null;
+            const mockUser = { id: 'user-789', email: 'logout@example.com' };
+            render(_jsx(PersSDKProvider, { config: { apiProjectKey: 'test-project' }, children: _jsx(TestConsumer, { onContext: (ctx) => { capturedContext = ctx; } }) }));
+            await waitFor(() => {
+                expect(capturedContext?.sdk).not.toBeNull();
+            });
+            // First, log in
+            await act(async () => {
+                emitAuthEvent('login_success', { user: mockUser });
+            });
+            await waitFor(() => {
+                expect(capturedContext?.isAuthenticated).toBe(true);
+            });
+            // Then logout
+            await act(async () => {
+                emitAuthEvent('logout_success', {});
+            });
+            await waitFor(() => {
+                expect(capturedContext?.isAuthenticated).toBe(false);
+                expect(capturedContext?.user).toBeNull();
+            });
+        });
+        it('should clear user on session_restoration_failed event', async () => {
+            let capturedContext = null;
+            render(_jsx(PersSDKProvider, { config: { apiProjectKey: 'test-project' }, children: _jsx(TestConsumer, { onContext: (ctx) => { capturedContext = ctx; } }) }));
+            await waitFor(() => {
+                expect(capturedContext?.sdk).not.toBeNull();
+            });
+            // Set initial authenticated state
+            await act(async () => {
+                capturedContext.setAuthenticationState({ id: 'temp-user' }, true);
+            });
+            await waitFor(() => {
+                expect(capturedContext?.isAuthenticated).toBe(true);
+            });
+            // Emit session_restoration_failed
+            await act(async () => {
+                emitAuthEvent('session_restoration_failed', { error: 'Token expired' });
+            });
+            await waitFor(() => {
+                expect(capturedContext?.isAuthenticated).toBe(false);
+                expect(capturedContext?.user).toBeNull();
+            });
+        });
+        it('should NOT respond to AUTH_FAILED code (dead code was removed)', async () => {
+            // This test verifies that we no longer check for event.code === 'AUTH_FAILED'
+            // which was dead code that never triggered
+            let capturedContext = null;
+            const mockUser = { id: 'user-stay', email: 'stay@example.com' };
+            render(_jsx(PersSDKProvider, { config: { apiProjectKey: 'test-project' }, children: _jsx(TestConsumer, { onContext: (ctx) => { capturedContext = ctx; } }) }));
+            await waitFor(() => {
+                expect(capturedContext?.sdk).not.toBeNull();
+            });
+            // Log in first
+            await act(async () => {
+                emitAuthEvent('login_success', { user: mockUser });
+            });
+            await waitFor(() => {
+                expect(capturedContext?.isAuthenticated).toBe(true);
+            });
+            // Emit an event with code: 'AUTH_FAILED' - this should NOT clear user
+            // because we removed the dead code that checked for this
+            await act(async () => {
+                if (mockSdkInstance?.events) {
+                    mockSdkInstance.events.emit({
+                        type: 'some_other_event',
+                        code: 'AUTH_FAILED', // This was the dead code path we removed
+                        domain: 'authentication',
+                        details: {}
+                    });
+                }
+            });
+            // User should STILL be authenticated - the code: 'AUTH_FAILED' check is gone
+            expect(capturedContext.isAuthenticated).toBe(true);
+            expect(capturedContext.user).toEqual(mockUser);
+        });
+    });
+    describe('usePersSDK hook', () => {
+        it('should throw error when used outside provider', () => {
+            // Suppress the expected error
+            const spy = jest.spyOn(console, 'error').mockImplementation(() => { });
+            const TestComponent = () => {
+                usePersSDK();
+                return null;
+            };
+            expect(() => render(_jsx(TestComponent, {}))).toThrow('usePersSDK must be used within a PersSDKProvider');
+            spy.mockRestore();
+        });
+    });
+    describe('context methods', () => {
+        it('should allow manual authentication state updates', async () => {
+            let capturedContext = null;
+            const mockUser = { id: 'manual-user', email: 'manual@example.com' };
+            render(_jsx(PersSDKProvider, { config: { apiProjectKey: 'test-project' }, children: _jsx(TestConsumer, { onContext: (ctx) => { capturedContext = ctx; } }) }));
+            await waitFor(() => {
+                expect(capturedContext?.isInitialized).toBe(true);
+            });
+            await act(async () => {
+                capturedContext.setAuthenticationState(mockUser, true);
+            });
+            await waitFor(() => {
+                expect(capturedContext?.isAuthenticated).toBe(true);
+                expect(capturedContext?.user).toEqual(mockUser);
+            });
+        });
+        it('should refresh user data from SDK', async () => {
+            let capturedContext = null;
+            render(_jsx(PersSDKProvider, { config: { apiProjectKey: 'test-project' }, children: _jsx(TestConsumer, { onContext: (ctx) => { capturedContext = ctx; } }) }));
+            await waitFor(() => {
+                expect(capturedContext?.isInitialized).toBe(true);
+            });
+            await act(async () => {
+                await capturedContext.refreshUserData();
+            });
+            await waitFor(() => {
+                expect(capturedContext?.user).toEqual({ id: 'refreshed-user', email: 'refreshed@test.com' });
+            });
+        });
+        it('should throw error when refreshUserData called before init', async () => {
+            let capturedContext = null;
+            render(_jsx(PersSDKProvider, { children: _jsx(TestConsumer, { onContext: (ctx) => { capturedContext = ctx; } }) }));
+            await waitFor(() => {
+                expect(capturedContext).not.toBeNull();
+            });
+            await expect(capturedContext.refreshUserData()).rejects.toThrow('SDK not initialized');
+        });
+        it('should throw error when restoreSession called before init', async () => {
+            let capturedContext = null;
+            render(_jsx(PersSDKProvider, { children: _jsx(TestConsumer, { onContext: (ctx) => { capturedContext = ctx; } }) }));
+            await waitFor(() => {
+                expect(capturedContext).not.toBeNull();
+            });
+            await expect(capturedContext.restoreSession()).rejects.toThrow('SDK not initialized');
+        });
+    });
+});

package/dist/__tests__/setup.d.ts

@@ -0,0 +1,2 @@
+import '@testing-library/jest-dom';
+//# sourceMappingURL=setup.d.ts.map

package/dist/__tests__/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/__tests__/setup.ts"],"names":[],"mappings":"AAAA,OAAO,2BAA2B,CAAC"}

package/dist/__tests__/setup.js

@@ -0,0 +1,35 @@
+import '@testing-library/jest-dom';
+// Mock React Native modules
+jest.mock('react-native', () => ({
+    Platform: {
+        OS: 'ios',
+        select: jest.fn((obj) => obj.ios || obj.default)
+    },
+    AppState: {
+        addEventListener: jest.fn(() => ({
+            remove: jest.fn()
+        })),
+        currentState: 'active'
+    }
+}));
+// Mock AsyncStorage
+jest.mock('@react-native-async-storage/async-storage', () => ({
+    default: {
+        getItem: jest.fn(),
+        setItem: jest.fn(),
+        removeItem: jest.fn(),
+        clear: jest.fn(),
+        getAllKeys: jest.fn(() => Promise.resolve([]))
+    }
+}));
+// Silence console errors in tests unless explicitly needed
+const originalConsoleError = console.error;
+const originalConsoleWarn = console.warn;
+beforeAll(() => {
+    console.error = jest.fn();
+    console.warn = jest.fn();
+});
+afterAll(() => {
+    console.error = originalConsoleError;
+    console.warn = originalConsoleWarn;
+});

package/dist/hooks/useRedemptions.d.ts

@@ -30,6 +30,7 @@ export interface GetRedemptionsOptions {
 }
 export declare const useRedemptions: () => {
     getRedemptions: (options?: GetRedemptionsOptions) => Promise<PaginatedResponseDTO<RedemptionDTO>>;
+    getRedemptionById: (id: string, include?: RedemptionIncludeRelation[]) => Promise<RedemptionDTO>;
     getUserRedemptions: (filters?: {
         redemptionId?: string;
         status?: ProcessRecordStatus;

package/dist/hooks/useRedemptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useRedemptions.d.ts","sourceRoot":"","sources":["../../src/hooks/useRedemptions.ts"],"names":[],"mappings":"AAEA,OAAO,EAA0C,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAClG,OAAO,KAAK,EACV,0BAA0B,EAC1B,aAAa,EACb,mBAAmB,EACnB,kCAAkC,EAClC,iBAAiB,EACjB,oBAAoB,EACpB,+BAA+B,EAC/B,yBAAyB,EACzB,mBAAmB,EACnB,cAAc,EACd,SAAS,EACV,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,uBAAuB,EAA2B,MAAM,gCAAgC,CAAC;AACvG,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAG7D,YAAY,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAEvG;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,oFAAoF;IACpF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACzB,wDAAwD;IACxD,SAAS,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IAC1B,uDAAuD;IACvD,OAAO,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IACxB,0CAA0C;IAC1C,OAAO,CAAC,EAAE,yBAAyB,EAAE,CAAC;IACtC,8BAA8B;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uBAAuB;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uBAAuB;IACvB,MAAM,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,WAAW,CAAC;IAC5C,qBAAqB;IACrB,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED,eAAO,MAAM,cAAc;+BAqD2B,qBAAqB,KAAG,QAAQ,qBAAqB,aAAa,CAAC,CAAC;mCAyC5G;QAAE,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,mBAAmB,CAAA;KAAE,YACvD,iBAAiB,YACjB,+BAA+B,EAAE,KAC1C,QAAQ,qBAAqB,mBAAmB,CAAC,CAAC;2BAkErC,MAAM,YACV;QAAE,OAAO,CAAC,EAAE,cAAc,CAAC;QAAC,cAAc,CAAC,EAAE,gBAAgB,CAAA;KAAE,KACxE,QAAQ,kCAAkC,CAAC;8BAmHG,QAAQ,qBAAqB,iBAAiB,CAAC,CAAC;qCA9BrF,uBAAuB,YACvB,+BAA+B,EAAE,KAC1C,QAAQ,qBAAqB,mBAAmB,CAAC,CAAC;uCAcO,0BAA0B,KAAG,QAAQ,aAAa,CAAC;qCA4BrD,MAAM,kBAAkB,0BAA0B,KAAG,QAAQ,aAAa,CAAC;2CAcrE,MAAM,KAAG,QAAQ,aAAa,CAAC;;;;CA4BhG,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC"}
+{"version":3,"file":"useRedemptions.d.ts","sourceRoot":"","sources":["../../src/hooks/useRedemptions.ts"],"names":[],"mappings":"AAEA,OAAO,EAA0C,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAClG,OAAO,KAAK,EACV,0BAA0B,EAC1B,aAAa,EACb,mBAAmB,EACnB,kCAAkC,EAClC,iBAAiB,EACjB,oBAAoB,EACpB,+BAA+B,EAC/B,yBAAyB,EACzB,mBAAmB,EACnB,cAAc,EACd,SAAS,EACV,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAC9E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAG7D,YAAY,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAEvG;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,oFAAoF;IACpF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACzB,wDAAwD;IACxD,SAAS,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IAC1B,uDAAuD;IACvD,OAAO,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IACxB,0CAA0C;IAC1C,OAAO,CAAC,EAAE,yBAAyB,EAAE,CAAC;IACtC,8BAA8B;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uBAAuB;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uBAAuB;IACvB,MAAM,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,WAAW,CAAC;IAC5C,qBAAqB;IACrB,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED,eAAO,MAAM,cAAc;+BAqD2B,qBAAqB,KAAG,QAAQ,qBAAqB,aAAa,CAAC,CAAC;4BAkUlH,MAAM,YACA,yBAAyB,EAAE,KACpC,QAAQ,aAAa,CAAC;mCA3Rb;QAAE,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,mBAAmB,CAAA;KAAE,YACvD,iBAAiB,YACjB,+BAA+B,EAAE,KAC1C,QAAQ,qBAAqB,mBAAmB,CAAC,CAAC;2BAiGrC,MAAM,YACV;QAAE,OAAO,CAAC,EAAE,cAAc,CAAC;QAAC,cAAc,CAAC,EAAE,gBAAgB,CAAA;KAAE,KACxE,QAAQ,kCAAkC,CAAC;8BAmHG,QAAQ,qBAAqB,iBAAiB,CAAC,CAAC;qCA9BrF,uBAAuB,YACvB,+BAA+B,EAAE,KAC1C,QAAQ,qBAAqB,mBAAmB,CAAC,CAAC;uCAcO,0BAA0B,KAAG,QAAQ,aAAa,CAAC;qCA4BrD,MAAM,kBAAkB,0BAA0B,KAAG,QAAQ,aAAa,CAAC;2CAcrE,MAAM,KAAG,QAAQ,aAAa,CAAC;;;;CAmEhG,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC"}

package/dist/hooks/useRedemptions.js

@@ -112,6 +112,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.
@@ -120,11 +139,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)
@@ -155,6 +184,8 @@ export const useRedemptions = () => {
      *   }
      * });
      * ```
+     *
+     * @see {@link useTransactions.createTransaction | createTransaction()} for direct transfers without redemption flow
      */
     const redeem = useCallback(async (redemptionId, options) => {
         if (!isInitialized || !sdk) {
@@ -304,8 +335,43 @@ export 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 = 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,

package/dist/hooks/useTokenBalances.d.ts

@@ -6,9 +6,42 @@ import type { TokenBalance } 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;

package/dist/hooks/useTokenBalances.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useTokenBalances.d.ts","sourceRoot":"","sources":["../../src/hooks/useTokenBalances.ts"],"names":[],"mappings":"AAGA,OAAO,EAAoB,KAAK,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACtE,OAAO,KAAK,EAAE,YAAY,EAAuB,MAAM,0BAA0B,CAAC;AAElF;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,uCAAuC;IACvC,YAAY,EAAE,YAAY,CAAC;IAC3B,8DAA8D;IAC9D,KAAK,EAAE,QAAQ,CAAC;IAChB,8EAA8E;IAC9E,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,eAAe,CAAC,EAAE,QAAQ,EAAE,CAAC;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,0DAA0D;IAC1D,aAAa,EAAE,qBAAqB,EAAE,CAAC;IACvC,6CAA6C;IAC7C,SAAS,EAAE,OAAO,CAAC;IACnB,sCAAsC;IACtC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,uCAAuC;IACvC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,sFAAsF;IACtF,WAAW,EAAE,OAAO,CAAC;IACrB,0CAA0C;IAC1C,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8FG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,sBAAsB,CAqLzF"}
+{"version":3,"file":"useTokenBalances.d.ts","sourceRoot":"","sources":["../../src/hooks/useTokenBalances.ts"],"names":[],"mappings":"AAGA,OAAO,EAAoB,KAAK,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACtE,OAAO,KAAK,EAAE,YAAY,EAAuB,MAAM,0BAA0B,CAAC;AAElF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;OAKG;IACH,YAAY,EAAE,YAAY,CAAC;IAC3B,8DAA8D;IAC9D,KAAK,EAAE,QAAQ,CAAC;IAChB,8EAA8E;IAC9E,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,eAAe,CAAC,EAAE,QAAQ,EAAE,CAAC;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,0DAA0D;IAC1D,aAAa,EAAE,qBAAqB,EAAE,CAAC;IACvC,6CAA6C;IAC7C,SAAS,EAAE,OAAO,CAAC;IACnB,sCAAsC;IACtC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,uCAAuC;IACvC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,sFAAsF;IACtF,WAAW,EAAE,OAAO,CAAC;IACrB,0CAA0C;IAC1C,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8FG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,sBAAsB,CAqLzF"}

package/dist/hooks/useTokens.d.ts

@@ -1,4 +1,4 @@
-import type { TokenDTO, PaginatedResponseDTO } from '@explorins/pers-sdk';
+import type { TokenDTO, TokenMetadataDTO, PaginatedResponseDTO } from '@explorins/pers-sdk';
 /**
  * React hook for token operations in the PERS SDK
  *
@@ -34,6 +34,9 @@ export declare const useTokens: () => {
     getTokenTypes: () => Promise<any>;
     getStatusTokens: () => Promise<PaginatedResponseDTO<TokenDTO>>;
     getTokenByContract: (contractAddress: string, contractTokenId?: string | null) => Promise<TokenDTO>;
+    getTokenMetadata: (options?: any) => Promise<PaginatedResponseDTO<TokenMetadataDTO>>;
+    getRewards: (options?: any) => Promise<PaginatedResponseDTO<TokenMetadataDTO>>;
+    getStamps: (options?: any) => Promise<PaginatedResponseDTO<TokenMetadataDTO>>;
     isAvailable: boolean;
 };
 export type TokenHook = ReturnType<typeof useTokens>;

package/dist/hooks/useTokens.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useTokens.d.ts","sourceRoot":"","sources":["../../src/hooks/useTokens.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,SAAS;qBAoBoB,QAAQ,qBAAqB,QAAQ,CAAC,CAAC;gCA2B5B,QAAQ,QAAQ,CAAC;2BA2BtB,QAAQ,qBAAqB,QAAQ,CAAC,CAAC;yBA2BzC,QAAQ,GAAG,CAAC;2BA2BV,QAAQ,qBAAqB,QAAQ,CAAC,CAAC;0CA6BtB,MAAM,oBAAoB,MAAM,GAAG,IAAI,KAAG,QAAQ,QAAQ,CAAC;;CAuB3H,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC"}
+{"version":3,"file":"useTokens.d.ts","sourceRoot":"","sources":["../../src/hooks/useTokens.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,oBAAoB,EAAyE,MAAM,qBAAqB,CAAC;AAEnK;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,SAAS;qBAoBoB,QAAQ,qBAAqB,QAAQ,CAAC,CAAC;gCA2B5B,QAAQ,QAAQ,CAAC;2BA2BtB,QAAQ,qBAAqB,QAAQ,CAAC,CAAC;yBA2BzC,QAAQ,GAAG,CAAC;2BA2BV,QAAQ,qBAAqB,QAAQ,CAAC,CAAC;0CA6BtB,MAAM,oBAAoB,MAAM,GAAG,IAAI,KAAG,QAAQ,QAAQ,CAAC;yCAkCvC,QAAQ,qBAAqB,gBAAgB,CAAC,CAAC;mCA+B3D,QAAQ,qBAAqB,gBAAgB,CAAC,CAAC;kCA+BjD,QAAQ,qBAAqB,gBAAgB,CAAC,CAAC;;CA0BrH,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC"}