@chipi-stack/chipi-react 14.2.1 → 14.3.0

package/dist/hooks.d.mts

@@ -1,4 +1,4 @@
-import { CreateWalletParams, CreateWalletResponse, GetWalletParams, GetWalletResponse, ChainToken, GetTokenBalanceResponse, WalletType, WalletData, SessionKeyData, SessionDataResponse, CreateSessionKeyParams, SessionConfig, Call, SpendingPolicyConfig, SpendingPolicyData, MigrateWalletToPasskeyParams, UpdateWalletEncryptionParams, UpdateWalletEncryptionResponse, TransferHookInput, ApproveHookInput, GetTransactionListQuery, PaginatedResponse, Transaction, TransactionStatusResponse, CreateSkuPurchaseParams, GetSkuListQuery, Sku, CallAnyContractParams, RecordSendTransactionParams, GetTokenBalanceParams, AddSessionKeyParams, RevokeSessionKeyParams, GetSessionDataParams, ExecuteWithSessionParams, PaymentRequirement, PaymentPayload } from '@chipi-stack/types';
+import { CreateWalletParams, CreateWalletResponse, GetWalletParams, GetWalletResponse, ChainToken, GetTokenBalanceResponse, WalletType, WalletData, SessionKeyData, SessionDataResponse, CreateSessionKeyParams, SessionConfig, Call, SpendingPolicyConfig, SpendingPolicyData, MigrateWalletToPasskeyParams, UpdateWalletEncryptionParams, UpdateWalletEncryptionResponse, TransferHookInput, ApproveHookInput, GetTransactionListQuery, PaginatedResponse, Transaction, TransactionStatusResponse, SyncOnChainTransfersParams, SyncOnChainTransfersResponse, CreateSkuPurchaseParams, GetSkuListQuery, Sku, CallAnyContractParams, RecordSendTransactionParams, GetTokenBalanceParams, AddSessionKeyParams, RevokeSessionKeyParams, GetSessionDataParams, ExecuteWithSessionParams, PaymentRequirement, PaymentPayload } from '@chipi-stack/types';
 import * as _tanstack_react_query from '@tanstack/react-query';
 import { UseQueryOptions, UseQueryResult } from '@tanstack/react-query';
 
@@ -7,7 +7,35 @@ type CreateWalletInput = {
     bearerToken: string;
 };
 /**
- * Hook for creating a new wallet
+ * Hook for creating a new wallet.
+ *
+ * Supports dual-key wrapping: when `usePasskey: true` AND `encryptKey` (PIN) provided,
+ * the private key is encrypted twice — once with the passkey-derived key (primary) and
+ * once with the PIN (backup). If passkey fails later, PIN recovers the wallet.
+ *
+ * @example
+ * ```tsx
+ * // Passkey + PIN (recommended)
+ * await createWalletAsync({
+ *   params: {
+ *     encryptKey: pin,        // PIN backup
+ *     externalUserId: userId,
+ *     chain: Chain.STARKNET,
+ *     usePasskey: true,       // Creates passkey + dual encryption
+ *   },
+ *   bearerToken,
+ * });
+ *
+ * // PIN only (backward compatible)
+ * await createWalletAsync({
+ *   params: {
+ *     encryptKey: pin,
+ *     externalUserId: userId,
+ *     chain: Chain.STARKNET,
+ *   },
+ *   bearerToken,
+ * });
+ * ```
  */
 declare function useCreateWallet(): {
     createWallet: (input: CreateWalletInput) => void;
@@ -498,9 +526,36 @@ type TransferInput = {
     bearerToken: string;
 };
 /**
- * Hook for transferring tokens
+ * Configuration for useTransfer hook.
  */
-declare function useTransfer(): {
+interface UseTransferConfig {
+    /**
+     * Callback to prompt user for PIN when passkey fails.
+     * Should show a PIN input dialog and return the PIN, or null to cancel.
+     * Only called when usePasskey: true and passkey auth fails.
+     */
+    onPinRequired?: () => Promise<string | null>;
+}
+/**
+ * Hook for transferring tokens.
+ *
+ * When `usePasskey: true`:
+ * 1. Tries passkey authentication first
+ * 2. If passkey fails and wallet has `encryptedPrivateKeyBackup`:
+ *    calls `onPinRequired` to get PIN, uses PIN to decrypt backup
+ * 3. If no backup or no `onPinRequired`, throws
+ *
+ * @example
+ * ```tsx
+ * const { transferAsync } = useTransfer({
+ *   onPinRequired: async () => {
+ *     // Show PIN dialog, return PIN or null to cancel
+ *     return await showPinDialog();
+ *   },
+ * });
+ * ```
+ */
+declare function useTransfer(config?: UseTransferConfig): {
     transfer: (input: TransferInput) => void;
     transferAsync: (input: TransferInput) => Promise<string>;
     data: string | undefined;
@@ -1068,6 +1123,39 @@ declare function useGetTransactionStatus(input?: GetTransactionStatusInput): {
     promise: Promise<TransactionStatusResponse>;
 };
 
+type SyncOnChainInput = SyncOnChainTransfersParams & {
+    bearerToken: string;
+};
+/**
+ * Hook for syncing on-chain transfers from Voyager into the DB.
+ *
+ * Discovers transactions not made through the SDK (e.g., external USDC receives
+ * from Argent X or other wallets). After sync, useGetTransactionList returns
+ * the newly discovered transactions automatically.
+ *
+ * @example
+ * ```tsx
+ * const { syncTransfers, data, isLoading } = useSyncOnChainTransfers();
+ *
+ * // Sync on-chain transfers for a wallet
+ * const result = await syncTransfersAsync({
+ *   walletAddress: wallet.publicKey,
+ *   bearerToken: await getToken(),
+ * });
+ * console.log(`Synced ${result.synced} new transfers`);
+ * ```
+ */
+declare function useSyncOnChainTransfers(): {
+    syncTransfers: (input: SyncOnChainInput) => void;
+    syncTransfersAsync: (input: SyncOnChainInput) => Promise<SyncOnChainTransfersResponse>;
+    data: SyncOnChainTransfersResponse | undefined;
+    isLoading: boolean;
+    isError: boolean;
+    error: Error | null;
+    isSuccess: boolean;
+    reset: () => void;
+};
+
 type PurchaseSkuInput = {
     params: CreateSkuPurchaseParams;
     bearerToken: string;
@@ -2101,4 +2189,4 @@ interface UseX402PaymentReturn {
  */
 declare function useX402Payment(config: UseX402PaymentConfig): UseX402PaymentReturn;
 
-export { type ChipiWalletData, type SessionState, type SessionWallet, type UseChipiSessionConfig, type UseChipiSessionReturn, type UseChipiWalletConfig, type UseChipiWalletReturn, type UseX402PaymentConfig, type UseX402PaymentReturn, useAddSessionKeyToContract, useApprove, useCallAnyContract, useChipiSession, useChipiWallet, useCreateSessionKey, useCreateWallet, useExecuteWithSession, useGetSessionData, useGetSku, useGetSkuList, useGetSkuPurchase, useGetTokenBalance, useGetTransaction, useGetTransactionList, useGetTransactionStatus, useGetWallet, useMigrateWalletToPasskey, usePurchaseSku, useRecordSendTransaction, useRevokeSessionKey, useTransfer, useUpdateWalletEncryption, useX402Payment };
+export { type ChipiWalletData, type SessionState, type SessionWallet, type UseChipiSessionConfig, type UseChipiSessionReturn, type UseChipiWalletConfig, type UseChipiWalletReturn, type UseTransferConfig, type UseX402PaymentConfig, type UseX402PaymentReturn, useAddSessionKeyToContract, useApprove, useCallAnyContract, useChipiSession, useChipiWallet, useCreateSessionKey, useCreateWallet, useExecuteWithSession, useGetSessionData, useGetSku, useGetSkuList, useGetSkuPurchase, useGetTokenBalance, useGetTransaction, useGetTransactionList, useGetTransactionStatus, useGetWallet, useMigrateWalletToPasskey, usePurchaseSku, useRecordSendTransaction, useRevokeSessionKey, useSyncOnChainTransfers, useTransfer, useUpdateWalletEncryption, useX402Payment };

package/dist/hooks.d.ts

@@ -1,4 +1,4 @@
-import { CreateWalletParams, CreateWalletResponse, GetWalletParams, GetWalletResponse, ChainToken, GetTokenBalanceResponse, WalletType, WalletData, SessionKeyData, SessionDataResponse, CreateSessionKeyParams, SessionConfig, Call, SpendingPolicyConfig, SpendingPolicyData, MigrateWalletToPasskeyParams, UpdateWalletEncryptionParams, UpdateWalletEncryptionResponse, TransferHookInput, ApproveHookInput, GetTransactionListQuery, PaginatedResponse, Transaction, TransactionStatusResponse, CreateSkuPurchaseParams, GetSkuListQuery, Sku, CallAnyContractParams, RecordSendTransactionParams, GetTokenBalanceParams, AddSessionKeyParams, RevokeSessionKeyParams, GetSessionDataParams, ExecuteWithSessionParams, PaymentRequirement, PaymentPayload } from '@chipi-stack/types';
+import { CreateWalletParams, CreateWalletResponse, GetWalletParams, GetWalletResponse, ChainToken, GetTokenBalanceResponse, WalletType, WalletData, SessionKeyData, SessionDataResponse, CreateSessionKeyParams, SessionConfig, Call, SpendingPolicyConfig, SpendingPolicyData, MigrateWalletToPasskeyParams, UpdateWalletEncryptionParams, UpdateWalletEncryptionResponse, TransferHookInput, ApproveHookInput, GetTransactionListQuery, PaginatedResponse, Transaction, TransactionStatusResponse, SyncOnChainTransfersParams, SyncOnChainTransfersResponse, CreateSkuPurchaseParams, GetSkuListQuery, Sku, CallAnyContractParams, RecordSendTransactionParams, GetTokenBalanceParams, AddSessionKeyParams, RevokeSessionKeyParams, GetSessionDataParams, ExecuteWithSessionParams, PaymentRequirement, PaymentPayload } from '@chipi-stack/types';
 import * as _tanstack_react_query from '@tanstack/react-query';
 import { UseQueryOptions, UseQueryResult } from '@tanstack/react-query';
 
@@ -7,7 +7,35 @@ type CreateWalletInput = {
     bearerToken: string;
 };
 /**
- * Hook for creating a new wallet
+ * Hook for creating a new wallet.
+ *
+ * Supports dual-key wrapping: when `usePasskey: true` AND `encryptKey` (PIN) provided,
+ * the private key is encrypted twice — once with the passkey-derived key (primary) and
+ * once with the PIN (backup). If passkey fails later, PIN recovers the wallet.
+ *
+ * @example
+ * ```tsx
+ * // Passkey + PIN (recommended)
+ * await createWalletAsync({
+ *   params: {
+ *     encryptKey: pin,        // PIN backup
+ *     externalUserId: userId,
+ *     chain: Chain.STARKNET,
+ *     usePasskey: true,       // Creates passkey + dual encryption
+ *   },
+ *   bearerToken,
+ * });
+ *
+ * // PIN only (backward compatible)
+ * await createWalletAsync({
+ *   params: {
+ *     encryptKey: pin,
+ *     externalUserId: userId,
+ *     chain: Chain.STARKNET,
+ *   },
+ *   bearerToken,
+ * });
+ * ```
  */
 declare function useCreateWallet(): {
     createWallet: (input: CreateWalletInput) => void;
@@ -498,9 +526,36 @@ type TransferInput = {
     bearerToken: string;
 };
 /**
- * Hook for transferring tokens
+ * Configuration for useTransfer hook.
  */
-declare function useTransfer(): {
+interface UseTransferConfig {
+    /**
+     * Callback to prompt user for PIN when passkey fails.
+     * Should show a PIN input dialog and return the PIN, or null to cancel.
+     * Only called when usePasskey: true and passkey auth fails.
+     */
+    onPinRequired?: () => Promise<string | null>;
+}
+/**
+ * Hook for transferring tokens.
+ *
+ * When `usePasskey: true`:
+ * 1. Tries passkey authentication first
+ * 2. If passkey fails and wallet has `encryptedPrivateKeyBackup`:
+ *    calls `onPinRequired` to get PIN, uses PIN to decrypt backup
+ * 3. If no backup or no `onPinRequired`, throws
+ *
+ * @example
+ * ```tsx
+ * const { transferAsync } = useTransfer({
+ *   onPinRequired: async () => {
+ *     // Show PIN dialog, return PIN or null to cancel
+ *     return await showPinDialog();
+ *   },
+ * });
+ * ```
+ */
+declare function useTransfer(config?: UseTransferConfig): {
     transfer: (input: TransferInput) => void;
     transferAsync: (input: TransferInput) => Promise<string>;
     data: string | undefined;
@@ -1068,6 +1123,39 @@ declare function useGetTransactionStatus(input?: GetTransactionStatusInput): {
     promise: Promise<TransactionStatusResponse>;
 };
 
+type SyncOnChainInput = SyncOnChainTransfersParams & {
+    bearerToken: string;
+};
+/**
+ * Hook for syncing on-chain transfers from Voyager into the DB.
+ *
+ * Discovers transactions not made through the SDK (e.g., external USDC receives
+ * from Argent X or other wallets). After sync, useGetTransactionList returns
+ * the newly discovered transactions automatically.
+ *
+ * @example
+ * ```tsx
+ * const { syncTransfers, data, isLoading } = useSyncOnChainTransfers();
+ *
+ * // Sync on-chain transfers for a wallet
+ * const result = await syncTransfersAsync({
+ *   walletAddress: wallet.publicKey,
+ *   bearerToken: await getToken(),
+ * });
+ * console.log(`Synced ${result.synced} new transfers`);
+ * ```
+ */
+declare function useSyncOnChainTransfers(): {
+    syncTransfers: (input: SyncOnChainInput) => void;
+    syncTransfersAsync: (input: SyncOnChainInput) => Promise<SyncOnChainTransfersResponse>;
+    data: SyncOnChainTransfersResponse | undefined;
+    isLoading: boolean;
+    isError: boolean;
+    error: Error | null;
+    isSuccess: boolean;
+    reset: () => void;
+};
+
 type PurchaseSkuInput = {
     params: CreateSkuPurchaseParams;
     bearerToken: string;
@@ -2101,4 +2189,4 @@ interface UseX402PaymentReturn {
  */
 declare function useX402Payment(config: UseX402PaymentConfig): UseX402PaymentReturn;
 
-export { type ChipiWalletData, type SessionState, type SessionWallet, type UseChipiSessionConfig, type UseChipiSessionReturn, type UseChipiWalletConfig, type UseChipiWalletReturn, type UseX402PaymentConfig, type UseX402PaymentReturn, useAddSessionKeyToContract, useApprove, useCallAnyContract, useChipiSession, useChipiWallet, useCreateSessionKey, useCreateWallet, useExecuteWithSession, useGetSessionData, useGetSku, useGetSkuList, useGetSkuPurchase, useGetTokenBalance, useGetTransaction, useGetTransactionList, useGetTransactionStatus, useGetWallet, useMigrateWalletToPasskey, usePurchaseSku, useRecordSendTransaction, useRevokeSessionKey, useTransfer, useUpdateWalletEncryption, useX402Payment };
+export { type ChipiWalletData, type SessionState, type SessionWallet, type UseChipiSessionConfig, type UseChipiSessionReturn, type UseChipiWalletConfig, type UseChipiWalletReturn, type UseTransferConfig, type UseX402PaymentConfig, type UseX402PaymentReturn, useAddSessionKeyToContract, useApprove, useCallAnyContract, useChipiSession, useChipiWallet, useCreateSessionKey, useCreateWallet, useExecuteWithSession, useGetSessionData, useGetSku, useGetSkuList, useGetSkuPurchase, useGetTokenBalance, useGetTransaction, useGetTransactionList, useGetTransactionStatus, useGetWallet, useMigrateWalletToPasskey, usePurchaseSku, useRecordSendTransaction, useRevokeSessionKey, useSyncOnChainTransfers, useTransfer, useUpdateWalletEncryption, useX402Payment };

package/dist/hooks.js

@@ -23,6 +23,10 @@ function useCreateWallet() {
   const mutation = reactQuery.useMutation({
     mutationFn: async (input) => {
       let encryptKey = input.params.encryptKey;
+      let encryptKeyBackup;
+      let credentialId;
+      let prfSupported;
+      let authMethod;
       if (input.params.usePasskey) {
         if (!input.params.externalUserId) {
           throw new Error("externalUserId is required when using passkey");
@@ -31,15 +35,25 @@ function useCreateWallet() {
           const passkeyResult = await chipiPasskey.createWalletPasskey(
             input.params.externalUserId,
             input.params.externalUserId
-            // Using externalUserId as userName
           );
-          encryptKey = passkeyResult.encryptKey;
+          credentialId = passkeyResult.credentialId;
+          prfSupported = passkeyResult.prfSupported;
+          if (encryptKey) {
+            encryptKeyBackup = encryptKey;
+            encryptKey = passkeyResult.encryptKey;
+            authMethod = "passkey+pin";
+          } else {
+            encryptKey = passkeyResult.encryptKey;
+            authMethod = "passkey";
+          }
         } catch (error) {
           if (error instanceof Error) {
             throw new Error(`Passkey creation failed: ${error.message}`);
           }
           throw new Error("Failed to create passkey for wallet");
         }
+      } else {
+        authMethod = encryptKey ? "pin" : void 0;
       }
       if (!encryptKey) {
         throw new Error("encryptKey is required when usePasskey is false");
@@ -47,7 +61,12 @@ function useCreateWallet() {
       return chipiSDK.createWallet({
         params: {
           ...input.params,
-          encryptKey
+          encryptKey,
+          encryptKeyBackup,
+          authMethod,
+          credentialId,
+          prfSupported,
+          deviceType: "web"
         },
         bearerToken: input.bearerToken
       });
@@ -647,31 +666,40 @@ function useUpdateWalletEncryption() {
     reset: mutation.reset
   };
 }
-function useTransfer() {
+function useTransfer(config) {
   const { chipiSDK, passkeyAdapter } = useChipiContext();
   const mutation = reactQuery.useMutation({
     mutationFn: async (input) => {
       let encryptKey = input.params.encryptKey;
+      let walletForTransfer = input.params.wallet;
       if (input.params.usePasskey) {
         if (!input.params.externalUserId) {
           throw new Error("externalUserId is required when usePasskey is true");
         }
-        try {
-          const key = await passkeyAdapter.getWalletEncryptKey({
-            externalUserId: input.params.externalUserId
-          });
-          if (!key) {
-            throw new Error("Passkey authentication was cancelled");
-          }
-          encryptKey = key;
-        } catch (error) {
-          if (error instanceof DOMException && error.name === "NotAllowedError") {
-            throw new Error("Passkey authentication was cancelled by the user");
-          }
-          if (error instanceof Error) {
-            throw error;
+        const passkeyKey = await passkeyAdapter.getWalletEncryptKey({
+          externalUserId: input.params.externalUserId
+        });
+        if (passkeyKey) {
+          encryptKey = passkeyKey;
+        } else {
+          const wallet = input.params.wallet;
+          if (wallet.encryptedPrivateKeyBackup && config?.onPinRequired) {
+            const pin = await config.onPinRequired();
+            if (!pin) {
+              throw new Error("Transfer cancelled \u2014 PIN required as passkey fallback");
+            }
+            encryptKey = pin;
+            walletForTransfer = {
+              ...wallet,
+              encryptedPrivateKey: wallet.encryptedPrivateKeyBackup
+            };
+          } else if (wallet.encryptedPrivateKeyBackup) {
+            throw new Error(
+              "Passkey authentication failed. Provide an onPinRequired callback to use PIN backup."
+            );
+          } else {
+            throw new Error("Passkey authentication failed and no PIN backup available.");
           }
-          throw new Error("Failed to authenticate with passkey");
         }
       }
       if (!encryptKey) {
@@ -685,6 +713,7 @@ function useTransfer() {
       return chipiSDK.transfer({
         params: {
           ...transferParams,
+          wallet: walletForTransfer,
           amount: String(transferParams.amount),
           encryptKey
         },
@@ -907,6 +936,31 @@ function useGetTransactionStatus(input) {
     fetchTransactionStatus
   };
 }
+function useSyncOnChainTransfers() {
+  const { chipiSDK } = useChipiContext();
+  const queryClient = reactQuery.useQueryClient();
+  const mutation = reactQuery.useMutation({
+    mutationFn: async (input) => {
+      const { bearerToken, ...params } = input;
+      return chipiSDK.transactions.syncOnChainTransfers(params, bearerToken);
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({
+        predicate: (query) => query.queryKey[0] === "transaction-list"
+      });
+    }
+  });
+  return {
+    syncTransfers: mutation.mutate,
+    syncTransfersAsync: mutation.mutateAsync,
+    data: mutation.data,
+    isLoading: mutation.isPending,
+    isError: mutation.isError,
+    error: mutation.error,
+    isSuccess: mutation.isSuccess,
+    reset: mutation.reset
+  };
+}
 function usePurchaseSku() {
   const { chipiSDK } = useChipiContext();
   const mutation = reactQuery.useMutation({
@@ -1519,6 +1573,7 @@ exports.useMigrateWalletToPasskey = useMigrateWalletToPasskey;
 exports.usePurchaseSku = usePurchaseSku;
 exports.useRecordSendTransaction = useRecordSendTransaction;
 exports.useRevokeSessionKey = useRevokeSessionKey;
+exports.useSyncOnChainTransfers = useSyncOnChainTransfers;
 exports.useTransfer = useTransfer;
 exports.useUpdateWalletEncryption = useUpdateWalletEncryption;
 exports.useX402Payment = useX402Payment;