@talken/talkenkit 2.3.10 → 2.3.11

package/dist/components/ConnectOptions/ExternalWallets/shared/types.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Shared TypeScript types for ExternalWallets module
+ *
+ * @module ExternalWallets/shared/types
+ */
+import type { Adapter } from '@solana/wallet-adapter-base';
+import type { WalletConnector } from '../../../../wallets/useWalletConnectors';
+/**
+ * Common wallet data structure for rendering
+ */
+export interface WalletItem {
+    /**
+     * Unique wallet identifier (id or adapter.name)
+     */
+    id: string;
+    /**
+     * Display name
+     */
+    name: string;
+    /**
+     * Icon URL or data URI
+     */
+    iconUrl: string | (() => Promise<string>);
+    /**
+     * Icon background color (optional)
+     */
+    iconBackground?: string;
+    /**
+     * Whether wallet is ready/installed
+     */
+    ready: boolean;
+    /**
+     * Whether this is a RainbowKit connector (vs EIP-6963)
+     */
+    isRainbowKitConnector: boolean;
+    /**
+     * Wallet type (for rendering logic)
+     */
+    type: 'evm' | 'solana';
+    /**
+     * Original connector or adapter reference
+     */
+    source: WalletConnector | {
+        adapter: Adapter;
+    };
+}
+/**
+ * Solana wallet wrapper structure
+ */
+export interface SolanaWalletItem {
+    /**
+     * Solana wallet adapter
+     */
+    adapter: Adapter;
+}
+/**
+ * Props for wallet list components
+ */
+export interface BaseWalletListProps {
+    /**
+     * Recent wallet IDs for prioritization
+     */
+    recentWalletIds: string[];
+    /**
+     * Currently selected wallet ID
+     */
+    selectedWalletId?: string;
+    /**
+     * Callback when user selects a wallet
+     */
+    onWalletSelect: (wallet: WalletConnector) => void;
+    /**
+     * Compact mode for mobile
+     */
+    compact?: boolean;
+}
+/**
+ * Props for Ethereum wallet list
+ */
+export interface EthereumWalletListProps extends BaseWalletListProps {
+    /**
+     * Installed Ethereum wallet connectors
+     */
+    wallets: WalletConnector[];
+}
+/**
+ * Props for Solana wallet list
+ */
+export interface SolanaWalletListProps {
+    /**
+     * Solana wallet adapters
+     */
+    solanaWallets: SolanaWalletItem[];
+    /**
+     * Recent Solana wallet IDs
+     */
+    recentWalletIds: string[];
+    /**
+     * Currently connecting wallet name
+     */
+    connectingSolanaWallet?: string;
+    /**
+     * Connection in progress
+     */
+    isSolanaConnecting?: boolean;
+    /**
+     * Callback when user selects a Solana wallet
+     */
+    onSolanaWalletClick?: (walletName: string) => void;
+}
+/**
+ * Props for Popular wallet list
+ */
+export interface PopularWalletListProps extends BaseWalletListProps {
+    /**
+     * Current wallet list (filtered)
+     */
+    wallets: WalletConnector[];
+    /**
+     * Unfiltered wallet list for matching Popular group
+     */
+    unfilteredWallets?: WalletConnector[];
+}
+/**
+ * Wallet sorting result
+ */
+export interface SortedWallets {
+    /**
+     * Most recent wallet (if exists)
+     */
+    recent?: WalletConnector;
+    /**
+     * Remaining wallets in alphabetical order
+     */
+    others: WalletConnector[];
+}

package/dist/components/ConnectOptions/ExternalWallets/shared/utils.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Shared utilities for ExternalWallets module
+ *
+ * @module ExternalWallets/shared/utils
+ */
+import type { WalletConnector } from '../../../../wallets/useWalletConnectors';
+/**
+ * Sort wallets by recent priority
+ *
+ * Places the most recent wallet first, then sorts remaining alphabetically
+ *
+ * @param wallets - Array of wallet connectors to sort
+ * @param recentWalletIds - Array of recent wallet IDs (most recent first)
+ * @returns Sorted array with most recent first, then alphabetical
+ *
+ * @example
+ * ```typescript
+ * const wallets = [
+ *   { id: 'coinbase', name: 'Coinbase Wallet' },
+ *   { id: 'metaMask', name: 'MetaMask' },
+ *   { id: 'walletConnect', name: 'WalletConnect' },
+ * ];
+ * const sorted = sortWalletsByRecent(wallets, ['metaMask']);
+ * // Result: [MetaMask, Coinbase Wallet, WalletConnect]
+ * ```
+ */
+export declare function sortWalletsByRecent(wallets: WalletConnector[], recentWalletIds: string[]): WalletConnector[];
+/**
+ * Match Popular wallets from wagmi.ts configuration
+ *
+ * Auto-syncs with wagmi.ts Popular group, preserving order and handling
+ * EIP-6963 wallet ID changes (e.g., MetaMask via RDNS)
+ *
+ * @param unfilteredWallets - Original wallet list from wagmi.ts
+ * @param groupedWallets - Current grouped wallets (including Installed)
+ * @returns Popular wallets in wagmi.ts order
+ *
+ * @example
+ * ```typescript
+ * const popularWallets = matchPopularWallets(
+ *   unfilteredWallets,
+ *   { 'Installed': [...], 'Popular': [...] }
+ * );
+ * // Result: Wallets matching Popular group, preserving wagmi.ts order
+ * ```
+ */
+export declare function matchPopularWallets(unfilteredWallets: WalletConnector[] | undefined, groupedWallets: Record<string, WalletConnector[]>): WalletConnector[];
+/**
+ * Group wallets by groupName
+ *
+ * @param wallets - Array of wallet connectors
+ * @returns Object with groupName keys and wallet arrays
+ *
+ * @example
+ * ```typescript
+ * const grouped = groupWalletsByName(wallets);
+ * // Result: { 'Installed': [...], 'Popular': [...], 'Other': [...] }
+ * ```
+ */
+export declare function groupWalletsByName(wallets: WalletConnector[]): Record<string, WalletConnector[]>;
+/**
+ * Check if wallet is the most recent
+ *
+ * @param walletId - Wallet ID to check
+ * @param recentWalletIds - Array of recent wallet IDs
+ * @returns True if this is the most recent wallet
+ */
+export declare function isMostRecentWallet(walletId: string, recentWalletIds: string[]): boolean;

package/dist/components/ConnectOptions/PinAuth/PinAuthFlow.d.ts

@@ -0,0 +1,127 @@
+/**
+ * PinAuthFlow Component
+ *
+ * Orchestrator component for PIN authentication flows.
+ * Manages PIN creation, confirmation, and verification for ABC WaaS authentication.
+ *
+ * Responsibilities:
+ * 1. Coordinate PIN creation and confirmation modals
+ * 2. Integrate with wallet generation flow
+ * 3. Handle PIN verification for existing users
+ * 4. Display progress during wallet creation
+ * 5. Manage modal state transitions
+ *
+ * Flow Orchestration:
+ * - New User: Create PIN → Confirm PIN → Generate Wallets → Connect
+ * - Existing User: Verify PIN → Restore Wallet → Connect
+ *
+ * Integration:
+ * - Uses usePinCreation for PIN setup
+ * - Uses usePinVerification for PIN unlock
+ * - Uses useWalletGeneration for multi-chain wallet creation
+ * - Uses PinInputModal for all PIN input UI
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+/**
+ * Props for PinAuthFlow component
+ */
+export interface PinAuthFlowProps {
+    /**
+     * Email for PIN association
+     * Used to identify wallet owner
+     */
+    email: string;
+    /**
+     * Login data from ABC WaaS authentication
+     * Contains access_token, refresh_token, expires_in
+     */
+    loginData: any;
+    /**
+     * Callback when wallet creation/verification is complete
+     * Called after successful wallet generation or PIN verification
+     */
+    onComplete: () => void;
+    /**
+     * Callback to close and reset
+     * Called when user cancels PIN flow
+     */
+    onCancel: () => void;
+    /**
+     * wagmi connectors for wallet connection
+     * Used to find and connect ABC wallet connector
+     */
+    connectors: readonly any[];
+    /**
+     * wagmi connect function
+     * Used to establish wallet connection
+     */
+    connect: (args: {
+        connector: any;
+    }) => void;
+    /**
+     * Storage prefix for localStorage
+     * @default 'talkenkit_abc_'
+     */
+    storagePrefix?: string;
+}
+/**
+ * Imperative handle for external control
+ */
+export interface PinAuthFlowHandle {
+    /**
+     * Show PIN creation modal
+     * Used when new user needs to create PIN
+     */
+    showPinCreate: () => void;
+    /**
+     * Show PIN verification modal
+     * Used when existing user needs to unlock wallet
+     */
+    showPinVerify: () => void;
+}
+/**
+ * PinAuthFlow Orchestrator Component
+ *
+ * Coordinates all PIN-related authentication flows for ABC WaaS.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * <PinAuthFlow
+ *   email="user@example.com"
+ *   loginData={{ access_token: '...', refresh_token: '...', expires_in: 3600 }}
+ *   onComplete={() => {
+ *     console.log('Wallet ready!');
+ *     closeModal();
+ *   }}
+ *   onCancel={() => {
+ *     console.log('User cancelled');
+ *     resetState();
+ *   }}
+ *   connectors={connectors}
+ *   connect={connect}
+ * />
+ *
+ * // With ref for external control
+ * const pinAuthRef = useRef<PinAuthFlowHandle>(null);
+ *
+ * <PinAuthFlow
+ *   ref={pinAuthRef}
+ *   email={email}
+ *   loginData={loginData}
+ *   onComplete={handleComplete}
+ *   onCancel={handleCancel}
+ *   connectors={connectors}
+ *   connect={connect}
+ * />
+ *
+ * // Trigger PIN creation externally
+ * pinAuthRef.current?.showPinCreate();
+ * ```
+ *
+ * @param props - Component configuration
+ * @returns PinAuthFlow component
+ */
+export declare const PinAuthFlow: React.ForwardRefExoticComponent<PinAuthFlowProps & React.RefAttributes<PinAuthFlowHandle>>;

package/dist/components/ConnectOptions/PinAuth/hooks/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * PinAuth Hooks
+ *
+ * Custom hooks for PIN-based authentication flows.
+ *
+ * @packageDocumentation
+ */
+export { usePinCreation, type UsePinCreationProps, type UsePinCreationReturn, } from './usePinCreation';
+export { usePinVerification, type UsePinVerificationProps, type UsePinVerificationReturn, type ProgressStep, type ProgressStatus, } from './usePinVerification';
+export { useWalletGeneration, type UseWalletGenerationProps, type UseWalletGenerationReturn, type WalletGenerationProgress, } from './useWalletGeneration';

package/dist/components/ConnectOptions/PinAuth/hooks/usePinCreation.d.ts

@@ -0,0 +1,92 @@
+/**
+ * usePinCreation Hook
+ *
+ * Manages PIN creation and confirmation flow for ABC WaaS authentication.
+ *
+ * Flow:
+ * 1. User creates PIN � handlePinCreate
+ * 2. Trigger confirmation modal
+ * 3. User confirms PIN � handlePinConfirm
+ * 4. Hash PIN � Callback with hashed PIN
+ *
+ * Security:
+ * - Stores PIN temporarily in memory only
+ * - Validates PIN match before confirmation
+ * - Hashes PIN with SHA-256 before storage
+ * - Clears plain text PIN immediately after use
+ *
+ * @packageDocumentation
+ */
+/**
+ * Props for usePinCreation hook
+ */
+export interface UsePinCreationProps {
+    /**
+     * Callback when PIN is confirmed and ready for wallet generation
+     * @param pinHash - SHA-256 hash of the confirmed PIN
+     */
+    onPinConfirmed: (pinHash: string) => Promise<void>;
+    /**
+     * Optional callback to show confirmation modal
+     * Called after PIN creation to trigger confirmation UI
+     */
+    onShowConfirmModal?: () => void;
+}
+/**
+ * Return value from usePinCreation hook
+ */
+export interface UsePinCreationReturn {
+    /** Created PIN (stored temporarily for confirmation) */
+    pin: string;
+    /** Confirmed PIN (for validation) */
+    confirmPin: string;
+    /** Error message if PIN confirmation fails */
+    error: string;
+    /** Loading state during PIN confirmation */
+    isCreating: boolean;
+    /**
+     * Handle PIN creation
+     * @param pin - Plain text PIN from user input
+     */
+    handlePinCreate: (pin: string) => Promise<void>;
+    /**
+     * Handle PIN confirmation
+     * @param confirmPin - Confirmed PIN from user input
+     * @throws Error if PIN confirmation fails
+     */
+    handlePinConfirm: (confirmPin: string) => Promise<void>;
+    /**
+     * Reset PIN state
+     * Clears all PIN data and errors
+     */
+    resetPin: () => void;
+}
+/**
+ * Hook for managing PIN creation and confirmation flow
+ *
+ * @example
+ * ```typescript
+ * const pinCreation = usePinCreation({
+ *   onPinConfirmed: async (pinHash) => {
+ *     await generateWallet(pinHash);
+ *   },
+ *   onShowConfirmModal: () => {
+ *     setIsPinConfirmModalOpen(true);
+ *   }
+ * });
+ *
+ * // In PIN creation modal
+ * <PinInput onSubmit={pinCreation.handlePinCreate} />
+ *
+ * // In PIN confirmation modal
+ * <PinInput
+ *   onSubmit={pinCreation.handlePinConfirm}
+ *   error={pinCreation.error}
+ *   isLoading={pinCreation.isCreating}
+ * />
+ * ```
+ *
+ * @param props - Configuration options
+ * @returns PIN creation state and handlers
+ */
+export declare function usePinCreation(props: UsePinCreationProps): UsePinCreationReturn;

package/dist/components/ConnectOptions/PinAuth/hooks/usePinVerification.d.ts

@@ -0,0 +1,114 @@
+/**
+ * usePinVerification Hook
+ *
+ * Manages PIN verification and wallet restoration flow for ABC WaaS authentication.
+ *
+ * Flow:
+ * 1. User enters PIN -> handlePinVerify
+ * 2. Hash PIN and verify against stored hash
+ * 3. Decrypt stored tokens with PIN
+ * 4. Check token expiration
+ * 5. Restore wallet state from localStorage
+ * 6. Generate missing wallets if needed (recovery scenario)
+ * 7. Callback with restored auth state
+ *
+ * Security:
+ * - Verifies PIN by decrypting stored data (not by comparing hashes)
+ * - Validates access token expiration
+ * - Clears expired sessions automatically
+ * - Re-encrypts sensitive data with PIN
+ *
+ * @packageDocumentation
+ */
+/**
+ * Progress step status
+ */
+export type ProgressStatus = 'pending' | 'active' | 'completed';
+/**
+ * Progress step for wallet restoration
+ */
+export interface ProgressStep {
+    /** Step description */
+    label: string;
+    /** Current status */
+    status: ProgressStatus;
+}
+/**
+ * Props for usePinVerification hook
+ */
+export interface UsePinVerificationProps {
+    /**
+     * Email for PIN verification
+     * Used to validate wallet ownership
+     */
+    email: string;
+    /**
+     * Callback when PIN is verified and wallet is restored
+     * Called after successful verification and wallet restoration
+     */
+    onVerified: () => void;
+    /**
+     * Optional callback when session is expired
+     * Called when access token is expired and user needs to re-login
+     */
+    onSessionExpired?: () => void;
+    /**
+     * Storage prefix for localStorage keys
+     * @default 'talkenkit_abc_'
+     */
+    storagePrefix?: string;
+}
+/**
+ * Return value from usePinVerification hook
+ */
+export interface UsePinVerificationReturn {
+    /** Loading state during PIN verification */
+    isVerifying: boolean;
+    /** Error message if PIN verification fails */
+    error: string;
+    /** Progress steps for wallet restoration */
+    progress: ProgressStep[];
+    /**
+     * Handle PIN verification
+     * @param pin - Plain text PIN from user input
+     * @throws Error if PIN verification fails
+     */
+    handlePinVerify: (pin: string) => Promise<void>;
+    /**
+     * Reset verification state
+     * Clears errors and resets progress
+     */
+    resetVerification: () => void;
+}
+/**
+ * Hook for managing PIN verification and wallet restoration flow
+ *
+ * @example
+ * ```typescript
+ * const pinVerification = usePinVerification({
+ *   email: 'user@example.com',
+ *   onVerified: () => {
+ *     console.log('Wallet unlocked!');
+ *     connectWallet();
+ *   },
+ *   onSessionExpired: () => {
+ *     console.log('Session expired, re-login required');
+ *     showLoginScreen();
+ *   }
+ * });
+ *
+ * // In PIN unlock modal
+ * <PinInput
+ *   onSubmit={pinVerification.handlePinVerify}
+ *   error={pinVerification.error}
+ *   isLoading={pinVerification.isVerifying}
+ * />
+ *
+ * // Show progress
+ * <ProgressIndicator steps={pinVerification.progress} />
+ * ```
+ *
+ * @param props - Configuration options
+ * @returns PIN verification state and handlers
+ */
+export declare function usePinVerification(props: UsePinVerificationProps): UsePinVerificationReturn;

package/dist/components/ConnectOptions/PinAuth/hooks/useWalletGeneration.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Wallet generation progress step
+ * Tracks the status of each wallet generation stage
+ */
+export interface WalletGenerationProgress {
+    /** Human-readable label for the step */
+    label: string;
+    /** Current status of the step */
+    status: 'pending' | 'active' | 'completed';
+}
+/**
+ * Hook return value for wallet generation
+ */
+export interface UseWalletGenerationReturn {
+    /** Whether wallet generation is in progress */
+    isGenerating: boolean;
+    /** Current progress steps for UI display */
+    progress: WalletGenerationProgress[];
+    /** Current status message */
+    statusMessage: string;
+    /** Function to start wallet generation process */
+    generateWallets: (params: {
+        hashedPin: string;
+        email: string;
+        loginData: any;
+    }) => Promise<void>;
+}
+/**
+ * Hook props for wallet generation configuration
+ */
+export interface UseWalletGenerationProps {
+    /** wagmi connectors for ABC wallet connection */
+    connectors: readonly any[];
+    /** wagmi connect function */
+    connect: (args: {
+        connector: any;
+    }) => void;
+    /** Callback when wallet generation completes successfully */
+    onSuccess: () => void;
+    /** Storage prefix for localStorage keys */
+    storagePrefix?: string;
+}
+/**
+ * Custom hook for multi-chain wallet generation (EVM, Solana, Bitcoin)
+ *
+ * Handles the complete wallet generation flow:
+ * 1. EVM wallet generation via ABC WaaS /wapi/v2/mpc/wallets
+ * 2. EVM public key retrieval via /wapi/v2/mpc/wallets/info
+ * 3. Solana wallet generation via /v3/wallet/generate (with 409 recovery fallback)
+ * 4. Solana address retrieval via /wapi/v2/solana/wallet/getAddress
+ * 5. Bitcoin address generation via /wapi/v2/btc/address (derived from EVM pubkey)
+ * 6. Progress tracking for all 4 steps
+ * 7. localStorage persistence (auth_state, wallet, tokens, etc.)
+ * 8. PIN hash storage
+ * 9. wagmi connector connection
+ *
+ * @param props - Configuration for wallet generation
+ * @returns Hook state and functions for wallet generation
+ *
+ * @example
+ * ```typescript
+ * const walletGeneration = useWalletGeneration({
+ *   connectors,
+ *   connect,
+ *   onSuccess: () => {
+ *     // Close modals, reset state
+ *     onClose();
+ *   },
+ *   storagePrefix: 'talkenkit_abc_',
+ * });
+ *
+ * // Display progress
+ * <ProgressSteps steps={walletGeneration.progress} />
+ * <StatusMessage>{walletGeneration.statusMessage}</StatusMessage>
+ *
+ * // Trigger generation
+ * await walletGeneration.generateWallets({
+ *   hashedPin,
+ *   email: 'user@example.com',
+ *   loginData: { access_token, refresh_token, expires_in }
+ * });
+ * ```
+ *
+ * @remarks
+ * - EVM wallet uses secp256k1 curve (Ethereum standard)
+ * - Solana wallet uses Ed25519 curve (Solana standard)
+ * - Bitcoin wallet derives address from EVM public key (same curve)
+ * - All wallets share the same PIN hash for encryption
+ * - Wallet data encrypted with PIN-based AES-256-GCM
+ * - Progress updates occur before each major step
+ * - Errors are logged and re-thrown for caller to handle
+ */
+export declare function useWalletGeneration(props: UseWalletGenerationProps): UseWalletGenerationReturn;

package/dist/components/ConnectOptions/PinAuth/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * PinAuth Module Exports
+ *
+ * Centralized exports for PIN authentication components and hooks.
+ *
+ * Components:
+ * - PinAuthFlow: Orchestrator for all PIN authentication flows
+ *
+ * Hooks:
+ * - usePinCreation: PIN creation and confirmation logic
+ * - usePinVerification: PIN unlock and verification logic
+ * - useWalletGeneration: Multi-chain wallet generation
+ *
+ * @packageDocumentation
+ */
+export { PinAuthFlow } from './PinAuthFlow';
+export type { PinAuthFlowProps, PinAuthFlowHandle } from './PinAuthFlow';
+export { usePinCreation } from './hooks/usePinCreation';
+export type { UsePinCreationProps, UsePinCreationReturn, } from './hooks/usePinCreation';
+export { usePinVerification } from './hooks/usePinVerification';
+export type { UsePinVerificationProps, UsePinVerificationReturn, ProgressStep, ProgressStatus, } from './hooks/usePinVerification';
+export { useWalletGeneration } from './hooks/useWalletGeneration';
+export type { UseWalletGenerationProps, UseWalletGenerationReturn, WalletGenerationProgress, } from './hooks/useWalletGeneration';