@explorins/pers-sdk-react-native 2.2.0-beta.1 → 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/dist/providers/PersSDKProvider.js

@@ -102,7 +102,7 @@ export const PersSDKProvider = ({ children, config }) => {
                         setIsAuthenticated(true);
                     }
                 }
-                if (event.type === 'logout_success' || event.type === 'session_restoration_failed' || event.code === 'AUTH_FAILED') {
+                if (event.type === 'logout_success' || event.type === 'session_restoration_failed') {
                     setUser(null);
                     setIsAuthenticated(false);
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@explorins/pers-sdk-react-native",
-  "version": "2.2.0-beta.1",
+  "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",
@@ -37,7 +37,7 @@
   "author": "eXplorins",
   "license": "MIT",
   "dependencies": {
-    "@explorins/pers-sdk": "^2.1.32",
+    "@explorins/pers-sdk": "^2.1.37",
     "@explorins/pers-signer": "^1.0.34",
     "buffer": "^6.0.3",
     "ethers": "^6.15.0",
@@ -167,11 +167,21 @@
     "@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"

package/src/__tests__/PersSDKProvider.test.tsx

@@ -0,0 +1,420 @@
+import React from 'react';
+import { render, act, waitFor } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { PersSDKProvider, usePersSDK, PersSDKContext } from '../providers/PersSDKProvider';
+
+// Store SDK instances for event emission
+let mockSdkInstance: any = null;
+
+// Mock the SDK core module BEFORE any imports use it
+jest.mock('@explorins/pers-sdk/core', () => {
+  const createMockEventEmitter = () => {
+    const subscribers: Array<{ callback: (event: any) => void; options?: any }> = [];
+    
+    return {
+      subscribe: jest.fn((callback: (event: any) => void, options?: any) => {
+        subscribers.push({ callback, options });
+        return () => {
+          const index = subscribers.findIndex(s => s.callback === callback);
+          if (index > -1) subscribers.splice(index, 1);
+        };
+      }),
+      emit: (event: any) => {
+        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: React.FC<{ onContext: (ctx: PersSDKContext) => void }> = ({ onContext }) => {
+  const context = usePersSDK();
+  React.useEffect(() => {
+    onContext(context);
+  }, [context, onContext]);
+  return <div data-testid="consumer">Consumer</div>;
+};
+
+// Helper to emit events on the mock SDK
+const emitAuthEvent = (type: string, details: any = {}) => {
+  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: PersSDKContext | null = null;
+      
+      render(
+        <PersSDKProvider>
+          <TestConsumer onContext={(ctx) => { capturedContext = ctx; }} />
+        </PersSDKProvider>
+      );
+
+      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: PersSDKContext | null = null;
+      
+      render(
+        <PersSDKProvider config={{ apiProjectKey: 'test-project' }}>
+          <TestConsumer onContext={(ctx) => { capturedContext = ctx; }} />
+        </PersSDKProvider>
+      );
+
+      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: PersSDKContext | null = null;
+      
+      render(
+        <PersSDKProvider config={{ apiProjectKey: 'test-project' }}>
+          <TestConsumer onContext={(ctx) => { capturedContext = ctx; }} />
+        </PersSDKProvider>
+      );
+
+      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: PersSDKContext | null = null;
+      const mockUser = { id: 'user-123', email: 'test@example.com' };
+      
+      render(
+        <PersSDKProvider config={{ apiProjectKey: 'test-project' }}>
+          <TestConsumer onContext={(ctx) => { capturedContext = ctx; }} />
+        </PersSDKProvider>
+      );
+
+      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: PersSDKContext | null = null;
+      const mockUser = { id: 'user-456', email: 'login@example.com' };
+      
+      render(
+        <PersSDKProvider config={{ apiProjectKey: 'test-project' }}>
+          <TestConsumer onContext={(ctx) => { capturedContext = ctx; }} />
+        </PersSDKProvider>
+      );
+
+      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: PersSDKContext | null = null;
+      const mockUser = { id: 'user-789', email: 'logout@example.com' };
+      
+      render(
+        <PersSDKProvider config={{ apiProjectKey: 'test-project' }}>
+          <TestConsumer onContext={(ctx) => { capturedContext = ctx; }} />
+        </PersSDKProvider>
+      );
+
+      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: PersSDKContext | null = null;
+      
+      render(
+        <PersSDKProvider config={{ apiProjectKey: 'test-project' }}>
+          <TestConsumer onContext={(ctx) => { capturedContext = ctx; }} />
+        </PersSDKProvider>
+      );
+
+      await waitFor(() => {
+        expect(capturedContext?.sdk).not.toBeNull();
+      });
+
+      // Set initial authenticated state
+      await act(async () => {
+        capturedContext!.setAuthenticationState({ id: 'temp-user' } as any, 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: PersSDKContext | null = null;
+      const mockUser = { id: 'user-stay', email: 'stay@example.com' };
+      
+      render(
+        <PersSDKProvider config={{ apiProjectKey: 'test-project' }}>
+          <TestConsumer onContext={(ctx) => { capturedContext = ctx; }} />
+        </PersSDKProvider>
+      );
+
+      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(<TestComponent />)).toThrow(
+        'usePersSDK must be used within a PersSDKProvider'
+      );
+
+      spy.mockRestore();
+    });
+  });
+
+  describe('context methods', () => {
+    it('should allow manual authentication state updates', async () => {
+      let capturedContext: PersSDKContext | null = null;
+      const mockUser = { id: 'manual-user', email: 'manual@example.com' };
+      
+      render(
+        <PersSDKProvider config={{ apiProjectKey: 'test-project' }}>
+          <TestConsumer onContext={(ctx) => { capturedContext = ctx; }} />
+        </PersSDKProvider>
+      );
+
+      await waitFor(() => {
+        expect(capturedContext?.isInitialized).toBe(true);
+      });
+
+      await act(async () => {
+        capturedContext!.setAuthenticationState(mockUser as any, true);
+      });
+
+      await waitFor(() => {
+        expect(capturedContext?.isAuthenticated).toBe(true);
+        expect(capturedContext?.user).toEqual(mockUser);
+      });
+    });
+
+    it('should refresh user data from SDK', async () => {
+      let capturedContext: PersSDKContext | null = null;
+      
+      render(
+        <PersSDKProvider config={{ apiProjectKey: 'test-project' }}>
+          <TestConsumer onContext={(ctx) => { capturedContext = ctx; }} />
+        </PersSDKProvider>
+      );
+
+      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: PersSDKContext | null = null;
+      
+      render(
+        <PersSDKProvider>
+          <TestConsumer onContext={(ctx) => { capturedContext = ctx; }} />
+        </PersSDKProvider>
+      );
+
+      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: PersSDKContext | null = null;
+      
+      render(
+        <PersSDKProvider>
+          <TestConsumer onContext={(ctx) => { capturedContext = ctx; }} />
+        </PersSDKProvider>
+      );
+
+      await waitFor(() => {
+        expect(capturedContext).not.toBeNull();
+      });
+
+      await expect(capturedContext!.restoreSession()).rejects.toThrow(
+        'SDK not initialized'
+      );
+    });
+  });
+});

package/src/__tests__/setup.ts

@@ -0,0 +1,40 @@
+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/src/hooks/useRedemptions.ts

@@ -14,7 +14,7 @@ import type {
   DynamicContext,
   SortOrder
 } from '@explorins/pers-sdk';
-import type { RedemptionRedeemFilters, RedemptionFilterOptions } from '@explorins/pers-sdk/redemption';
+import type { RedemptionRedeemFilters } from '@explorins/pers-sdk/redemption';
 import type { PaginationOptions } from '@explorins/pers-sdk';
 
 // Re-export for consumers
@@ -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,