@volr/react 0.1.135 → 0.2.1

package/dist/index.d.cts

@@ -218,6 +218,27 @@ type SignRequest = {
  * Resolve to proceed, reject to cancel
  */
 type OnSignRequest = (request: SignRequest) => Promise<void>;
+/**
+ * Wallet required request types for deferred wallet creation flows.
+ *
+ * Called when the SDK needs a Volr-managed wallet provider (passkey/MPC) but
+ * the current user does not have one available yet.
+ */
+type WalletRequiredRequest = {
+    type: "transaction";
+    chainId: number;
+} | {
+    type: "message";
+} | {
+    type: "typedData";
+};
+/**
+ * Callback invoked when a wallet is required for an operation.
+ *
+ * - If you return a provider, the SDK will use it for the current operation.
+ * - If you return void/null, the SDK will throw WALLET_REQUIRED so the caller can retry.
+ */
+type OnWalletRequired = (request: WalletRequiredRequest) => Promise<WalletProviderPort | void | null>;
 
 /**
  * ERC-20 token configuration
@@ -265,7 +286,6 @@ interface VolrUser {
  * Volr configuration
  */
 type VolrConfig = {
-    defaultChainId: number;
     projectApiKey: string;
     rpcOverrides?: Record<string, string>;
     autoRecoverOnLogin?: boolean;
@@ -283,6 +303,12 @@ type VolrConfig = {
      * Used by @volr/react-ui to show sign confirmation modal.
      */
     onSignRequest?: OnSignRequest;
+    /**
+     * Callback invoked when a wallet provider is required (passkey/MPC not yet created).
+     * Used by @volr/react-ui to show "Create account in 1 second" style onboarding
+     * only when the user actually needs a wallet (payments/transactions/signing).
+     */
+    onWalletRequired?: OnWalletRequired;
 };
 /**
  * Public context value
@@ -293,7 +319,6 @@ type VolrContextValue = {
     provider: WalletProviderPort | null;
     setProvider: (provider: WalletProviderPort) => Promise<void>;
     setUser: (user: VolrUser | null) => void;
-    chainId: number;
     precheck: (input: PrecheckInput) => Promise<PrecheckQuote>;
     relay: (input: RelayInput, opts?: {
         idempotencyKey?: string;
@@ -585,6 +610,10 @@ type VolrClient = {
      * How the user signs transactions
      */
     signerType: SignerType | undefined;
+    /**
+     * Whether the user has created a Volr-managed wallet (passkey/MPC).
+     */
+    hasWallet: boolean;
     /**
      * Logout the user
      */
@@ -603,6 +632,28 @@ type VolrClient = {
  */
 declare function useVolr(): VolrClient;
 
+type SetSessionParams = {
+    accessToken: string;
+    refreshToken: string;
+};
+type OidcExchangeResult = {
+    userId: string;
+    isNewUser: boolean;
+    keyStorageType: KeyStorageType | null;
+    signerType?: SignerType | null;
+    accessToken: string;
+};
+/**
+ * BYO Auth helpers:
+ * - A) setSession: inject server-minted Volr tokens and refresh user profile.
+ * - B) exchangeOidc: exchange an OIDC idToken (JWT) for Volr tokens.
+ */
+declare function useVolrSession(): {
+    setSession: (session: SetSessionParams) => Promise<VolrUser>;
+    clearSession: () => Promise<void>;
+    exchangeOidc: (idToken: string) => Promise<OidcExchangeResult>;
+};
+
 /**
  * usePrecheck hook - Precheck transaction batch
  */
@@ -1378,6 +1429,22 @@ declare function isWebAuthnBusyError(error: unknown): boolean;
  */
 declare function isInAppBrowserNotSupportedError(error: unknown): boolean;
 
+/**
+ * Wallet-related error classes
+ */
+type WalletRequiredAction = "send_transaction" | "sign_message" | "sign_typed_data";
+/**
+ * Error thrown when a Volr-managed wallet provider is required but not available.
+ *
+ * This is expected in the deferred-wallet flow (BYO Auth + optional wallet creation).
+ */
+declare class WalletRequiredError extends Error {
+    readonly code = "WALLET_REQUIRED";
+    readonly action: WalletRequiredAction;
+    constructor(action: WalletRequiredAction, message?: string);
+}
+declare function isWalletRequiredError(error: unknown): error is WalletRequiredError;
+
 /**
  * Platform compatibility check utilities
  * Detects PRF extension support and provides guidance for cross-device authentication
@@ -1702,4 +1769,4 @@ declare function useEIP6963(): UseEIP6963Return;
  */
 declare function detectWalletConnector(provider: any, providerInfo: EIP6963ProviderInfo | null): string;
 
-export { type ApiResponse, type AuthRefreshResponseDto, type AuthResult, type BrandingData, type BuildCallOptions, type ContractAnalysisResult, DEFAULT_EXPIRES_IN_SEC, DEFAULT_MODE, type DecryptEntropyParams, type DepositAsset$1 as DepositAsset, type DepositConfig, type EIP6963AnnounceProviderEvent, type EIP6963ProviderDetail, type EIP6963ProviderInfo, type ERC20BalanceComparison, type Erc20Token$1 as Erc20Token, type EvmChainClient, type EvmClient, type EvmNamespace, InAppBrowserNotSupportedError, type KeyStorageType, type MigrationCompleteParams, type MigrationCompleteResult, type MigrationError, type MigrationMessage, type MigrationRequestParams, type MigrationRequestResult, type MigrationSeedRequest, type MigrationSeedResponse, type MpcConnectionStep, type NetworkDto, type NetworkInfo, type OnSignRequest, type PasskeyAdapterOptions, type PasskeyEnrollmentStep, PasskeyNotFoundError, type PayOptions, type PaymentContext, type PaymentError, type PaymentHandle, type PaymentHandlers, type PaymentHistoryOptions, type PaymentHistoryResult, type PaymentItem, type PaymentResult, type PaymentStatus, type PaymentToken, type PlatformCheckResult, type PrfCompatibilityResult, type PrfInputDto, PrfNotSupportedError, type RegisteredPasskeyDto, type SendBatchOverloads, type SendTxOptions, type SignRequest, type SignerType, type SiweSession, type SiweSessionStatus, type SocialProvider, type TokenBalance, type TransactionDto, type TransactionStatus, type UseEIP6963Return, type UseMpcConnectionReturn, type UsePasskeyEnrollmentReturn, type UseUserBalancesReturn, type UseVolrAuthCallbackOptions, type UseVolrAuthCallbackReturn, type UseVolrLoginReturn, type UseVolrPaymentApiReturn, type UseWithdrawReturn, UserCancelledError, type UserDto, type VolrClient, type VolrConfig, type VolrContextValue, VolrProvider, type VolrUser, type WalletDisplayInfo, type WalletStateComparison, WebAuthnBusyError, type WithdrawParams, analyzeContractForEIP7702, buildCall, buildCalls, checkPrfCompatibility, checkPrfExtensionAvailable, checkPrfSupport, compareERC20Balances, compareWalletStates, completeMigration, createGetNetworkInfo, createPasskeyAdapter, debugTransactionFailure, decryptEntropyForMigration, defaultIdempotencyKey, detectWalletConnector, diagnoseTransactionFailure, getBrowserVersion, getERC20Balance, getIOSVersion, getPasskeyAuthGuidance, getPlatformHint, getUserCredentials, getWalletState, isEIP7702Delegated, isInAppBrowser, isInAppBrowserNotSupportedError, isUserCancelledError, isWebAuthnBusyError, listenForSeedRequests, normalizeHex, normalizeHexArray, openMigrationPopup, requestMigration, requestSeedFromOpener, sendSeedToPopup, uploadBlobViaPresign, useDepositListener, useEIP6963, useInternalAuth, useMpcConnection, usePasskeyEnrollment, usePrecheck, useRelay, useUserBalances, useVolr, useVolrAuthCallback, useVolrContext, useVolrLogin, useVolrPaymentApi, useWithdraw };
+export { type ApiResponse, type AuthRefreshResponseDto, type AuthResult, type BrandingData, type BuildCallOptions, type ContractAnalysisResult, DEFAULT_EXPIRES_IN_SEC, DEFAULT_MODE, type DecryptEntropyParams, type DepositAsset$1 as DepositAsset, type DepositConfig, type EIP6963AnnounceProviderEvent, type EIP6963ProviderDetail, type EIP6963ProviderInfo, type ERC20BalanceComparison, type Erc20Token$1 as Erc20Token, type EvmChainClient, type EvmClient, type EvmNamespace, InAppBrowserNotSupportedError, type KeyStorageType, type MigrationCompleteParams, type MigrationCompleteResult, type MigrationError, type MigrationMessage, type MigrationRequestParams, type MigrationRequestResult, type MigrationSeedRequest, type MigrationSeedResponse, type MpcConnectionStep, type NetworkDto, type NetworkInfo, type OidcExchangeResult, type OnSignRequest, type OnWalletRequired, type PasskeyAdapterOptions, type PasskeyEnrollmentStep, PasskeyNotFoundError, type PayOptions, type PaymentContext, type PaymentError, type PaymentHandle, type PaymentHandlers, type PaymentHistoryOptions, type PaymentHistoryResult, type PaymentItem, type PaymentResult, type PaymentStatus, type PaymentToken, type PlatformCheckResult, type PrfCompatibilityResult, type PrfInputDto, PrfNotSupportedError, type RegisteredPasskeyDto, type SendBatchOverloads, type SendTxOptions, type SetSessionParams, type SignRequest, type SignerType, type SiweSession, type SiweSessionStatus, type SocialProvider, type TokenBalance, type TransactionDto, type TransactionStatus, type UseEIP6963Return, type UseMpcConnectionReturn, type UsePasskeyEnrollmentReturn, type UseUserBalancesReturn, type UseVolrAuthCallbackOptions, type UseVolrAuthCallbackReturn, type UseVolrLoginReturn, type UseVolrPaymentApiReturn, type UseWithdrawReturn, UserCancelledError, type UserDto, type VolrClient, type VolrConfig, type VolrContextValue, VolrProvider, type VolrUser, type WalletDisplayInfo, type WalletRequiredAction, WalletRequiredError, type WalletRequiredRequest, type WalletStateComparison, WebAuthnBusyError, type WithdrawParams, analyzeContractForEIP7702, buildCall, buildCalls, checkPrfCompatibility, checkPrfExtensionAvailable, checkPrfSupport, compareERC20Balances, compareWalletStates, completeMigration, createGetNetworkInfo, createPasskeyAdapter, debugTransactionFailure, decryptEntropyForMigration, defaultIdempotencyKey, detectWalletConnector, diagnoseTransactionFailure, getBrowserVersion, getERC20Balance, getIOSVersion, getPasskeyAuthGuidance, getPlatformHint, getUserCredentials, getWalletState, isEIP7702Delegated, isInAppBrowser, isInAppBrowserNotSupportedError, isUserCancelledError, isWalletRequiredError, isWebAuthnBusyError, listenForSeedRequests, normalizeHex, normalizeHexArray, openMigrationPopup, requestMigration, requestSeedFromOpener, sendSeedToPopup, uploadBlobViaPresign, useDepositListener, useEIP6963, useInternalAuth, useMpcConnection, usePasskeyEnrollment, usePrecheck, useRelay, useUserBalances, useVolr, useVolrAuthCallback, useVolrContext, useVolrLogin, useVolrPaymentApi, useVolrSession, useWithdraw };

package/dist/index.d.ts

@@ -218,6 +218,27 @@ type SignRequest = {
  * Resolve to proceed, reject to cancel
  */
 type OnSignRequest = (request: SignRequest) => Promise<void>;
+/**
+ * Wallet required request types for deferred wallet creation flows.
+ *
+ * Called when the SDK needs a Volr-managed wallet provider (passkey/MPC) but
+ * the current user does not have one available yet.
+ */
+type WalletRequiredRequest = {
+    type: "transaction";
+    chainId: number;
+} | {
+    type: "message";
+} | {
+    type: "typedData";
+};
+/**
+ * Callback invoked when a wallet is required for an operation.
+ *
+ * - If you return a provider, the SDK will use it for the current operation.
+ * - If you return void/null, the SDK will throw WALLET_REQUIRED so the caller can retry.
+ */
+type OnWalletRequired = (request: WalletRequiredRequest) => Promise<WalletProviderPort | void | null>;
 
 /**
  * ERC-20 token configuration
@@ -265,7 +286,6 @@ interface VolrUser {
  * Volr configuration
  */
 type VolrConfig = {
-    defaultChainId: number;
     projectApiKey: string;
     rpcOverrides?: Record<string, string>;
     autoRecoverOnLogin?: boolean;
@@ -283,6 +303,12 @@ type VolrConfig = {
      * Used by @volr/react-ui to show sign confirmation modal.
      */
     onSignRequest?: OnSignRequest;
+    /**
+     * Callback invoked when a wallet provider is required (passkey/MPC not yet created).
+     * Used by @volr/react-ui to show "Create account in 1 second" style onboarding
+     * only when the user actually needs a wallet (payments/transactions/signing).
+     */
+    onWalletRequired?: OnWalletRequired;
 };
 /**
  * Public context value
@@ -293,7 +319,6 @@ type VolrContextValue = {
     provider: WalletProviderPort | null;
     setProvider: (provider: WalletProviderPort) => Promise<void>;
     setUser: (user: VolrUser | null) => void;
-    chainId: number;
     precheck: (input: PrecheckInput) => Promise<PrecheckQuote>;
     relay: (input: RelayInput, opts?: {
         idempotencyKey?: string;
@@ -585,6 +610,10 @@ type VolrClient = {
      * How the user signs transactions
      */
     signerType: SignerType | undefined;
+    /**
+     * Whether the user has created a Volr-managed wallet (passkey/MPC).
+     */
+    hasWallet: boolean;
     /**
      * Logout the user
      */
@@ -603,6 +632,28 @@ type VolrClient = {
  */
 declare function useVolr(): VolrClient;
 
+type SetSessionParams = {
+    accessToken: string;
+    refreshToken: string;
+};
+type OidcExchangeResult = {
+    userId: string;
+    isNewUser: boolean;
+    keyStorageType: KeyStorageType | null;
+    signerType?: SignerType | null;
+    accessToken: string;
+};
+/**
+ * BYO Auth helpers:
+ * - A) setSession: inject server-minted Volr tokens and refresh user profile.
+ * - B) exchangeOidc: exchange an OIDC idToken (JWT) for Volr tokens.
+ */
+declare function useVolrSession(): {
+    setSession: (session: SetSessionParams) => Promise<VolrUser>;
+    clearSession: () => Promise<void>;
+    exchangeOidc: (idToken: string) => Promise<OidcExchangeResult>;
+};
+
 /**
  * usePrecheck hook - Precheck transaction batch
  */
@@ -1378,6 +1429,22 @@ declare function isWebAuthnBusyError(error: unknown): boolean;
  */
 declare function isInAppBrowserNotSupportedError(error: unknown): boolean;
 
+/**
+ * Wallet-related error classes
+ */
+type WalletRequiredAction = "send_transaction" | "sign_message" | "sign_typed_data";
+/**
+ * Error thrown when a Volr-managed wallet provider is required but not available.
+ *
+ * This is expected in the deferred-wallet flow (BYO Auth + optional wallet creation).
+ */
+declare class WalletRequiredError extends Error {
+    readonly code = "WALLET_REQUIRED";
+    readonly action: WalletRequiredAction;
+    constructor(action: WalletRequiredAction, message?: string);
+}
+declare function isWalletRequiredError(error: unknown): error is WalletRequiredError;
+
 /**
  * Platform compatibility check utilities
  * Detects PRF extension support and provides guidance for cross-device authentication
@@ -1702,4 +1769,4 @@ declare function useEIP6963(): UseEIP6963Return;
  */
 declare function detectWalletConnector(provider: any, providerInfo: EIP6963ProviderInfo | null): string;
 
-export { type ApiResponse, type AuthRefreshResponseDto, type AuthResult, type BrandingData, type BuildCallOptions, type ContractAnalysisResult, DEFAULT_EXPIRES_IN_SEC, DEFAULT_MODE, type DecryptEntropyParams, type DepositAsset$1 as DepositAsset, type DepositConfig, type EIP6963AnnounceProviderEvent, type EIP6963ProviderDetail, type EIP6963ProviderInfo, type ERC20BalanceComparison, type Erc20Token$1 as Erc20Token, type EvmChainClient, type EvmClient, type EvmNamespace, InAppBrowserNotSupportedError, type KeyStorageType, type MigrationCompleteParams, type MigrationCompleteResult, type MigrationError, type MigrationMessage, type MigrationRequestParams, type MigrationRequestResult, type MigrationSeedRequest, type MigrationSeedResponse, type MpcConnectionStep, type NetworkDto, type NetworkInfo, type OnSignRequest, type PasskeyAdapterOptions, type PasskeyEnrollmentStep, PasskeyNotFoundError, type PayOptions, type PaymentContext, type PaymentError, type PaymentHandle, type PaymentHandlers, type PaymentHistoryOptions, type PaymentHistoryResult, type PaymentItem, type PaymentResult, type PaymentStatus, type PaymentToken, type PlatformCheckResult, type PrfCompatibilityResult, type PrfInputDto, PrfNotSupportedError, type RegisteredPasskeyDto, type SendBatchOverloads, type SendTxOptions, type SignRequest, type SignerType, type SiweSession, type SiweSessionStatus, type SocialProvider, type TokenBalance, type TransactionDto, type TransactionStatus, type UseEIP6963Return, type UseMpcConnectionReturn, type UsePasskeyEnrollmentReturn, type UseUserBalancesReturn, type UseVolrAuthCallbackOptions, type UseVolrAuthCallbackReturn, type UseVolrLoginReturn, type UseVolrPaymentApiReturn, type UseWithdrawReturn, UserCancelledError, type UserDto, type VolrClient, type VolrConfig, type VolrContextValue, VolrProvider, type VolrUser, type WalletDisplayInfo, type WalletStateComparison, WebAuthnBusyError, type WithdrawParams, analyzeContractForEIP7702, buildCall, buildCalls, checkPrfCompatibility, checkPrfExtensionAvailable, checkPrfSupport, compareERC20Balances, compareWalletStates, completeMigration, createGetNetworkInfo, createPasskeyAdapter, debugTransactionFailure, decryptEntropyForMigration, defaultIdempotencyKey, detectWalletConnector, diagnoseTransactionFailure, getBrowserVersion, getERC20Balance, getIOSVersion, getPasskeyAuthGuidance, getPlatformHint, getUserCredentials, getWalletState, isEIP7702Delegated, isInAppBrowser, isInAppBrowserNotSupportedError, isUserCancelledError, isWebAuthnBusyError, listenForSeedRequests, normalizeHex, normalizeHexArray, openMigrationPopup, requestMigration, requestSeedFromOpener, sendSeedToPopup, uploadBlobViaPresign, useDepositListener, useEIP6963, useInternalAuth, useMpcConnection, usePasskeyEnrollment, usePrecheck, useRelay, useUserBalances, useVolr, useVolrAuthCallback, useVolrContext, useVolrLogin, useVolrPaymentApi, useWithdraw };
+export { type ApiResponse, type AuthRefreshResponseDto, type AuthResult, type BrandingData, type BuildCallOptions, type ContractAnalysisResult, DEFAULT_EXPIRES_IN_SEC, DEFAULT_MODE, type DecryptEntropyParams, type DepositAsset$1 as DepositAsset, type DepositConfig, type EIP6963AnnounceProviderEvent, type EIP6963ProviderDetail, type EIP6963ProviderInfo, type ERC20BalanceComparison, type Erc20Token$1 as Erc20Token, type EvmChainClient, type EvmClient, type EvmNamespace, InAppBrowserNotSupportedError, type KeyStorageType, type MigrationCompleteParams, type MigrationCompleteResult, type MigrationError, type MigrationMessage, type MigrationRequestParams, type MigrationRequestResult, type MigrationSeedRequest, type MigrationSeedResponse, type MpcConnectionStep, type NetworkDto, type NetworkInfo, type OidcExchangeResult, type OnSignRequest, type OnWalletRequired, type PasskeyAdapterOptions, type PasskeyEnrollmentStep, PasskeyNotFoundError, type PayOptions, type PaymentContext, type PaymentError, type PaymentHandle, type PaymentHandlers, type PaymentHistoryOptions, type PaymentHistoryResult, type PaymentItem, type PaymentResult, type PaymentStatus, type PaymentToken, type PlatformCheckResult, type PrfCompatibilityResult, type PrfInputDto, PrfNotSupportedError, type RegisteredPasskeyDto, type SendBatchOverloads, type SendTxOptions, type SetSessionParams, type SignRequest, type SignerType, type SiweSession, type SiweSessionStatus, type SocialProvider, type TokenBalance, type TransactionDto, type TransactionStatus, type UseEIP6963Return, type UseMpcConnectionReturn, type UsePasskeyEnrollmentReturn, type UseUserBalancesReturn, type UseVolrAuthCallbackOptions, type UseVolrAuthCallbackReturn, type UseVolrLoginReturn, type UseVolrPaymentApiReturn, type UseWithdrawReturn, UserCancelledError, type UserDto, type VolrClient, type VolrConfig, type VolrContextValue, VolrProvider, type VolrUser, type WalletDisplayInfo, type WalletRequiredAction, WalletRequiredError, type WalletRequiredRequest, type WalletStateComparison, WebAuthnBusyError, type WithdrawParams, analyzeContractForEIP7702, buildCall, buildCalls, checkPrfCompatibility, checkPrfExtensionAvailable, checkPrfSupport, compareERC20Balances, compareWalletStates, completeMigration, createGetNetworkInfo, createPasskeyAdapter, debugTransactionFailure, decryptEntropyForMigration, defaultIdempotencyKey, detectWalletConnector, diagnoseTransactionFailure, getBrowserVersion, getERC20Balance, getIOSVersion, getPasskeyAuthGuidance, getPlatformHint, getUserCredentials, getWalletState, isEIP7702Delegated, isInAppBrowser, isInAppBrowserNotSupportedError, isUserCancelledError, isWalletRequiredError, isWebAuthnBusyError, listenForSeedRequests, normalizeHex, normalizeHexArray, openMigrationPopup, requestMigration, requestSeedFromOpener, sendSeedToPopup, uploadBlobViaPresign, useDepositListener, useEIP6963, useInternalAuth, useMpcConnection, usePasskeyEnrollment, usePrecheck, useRelay, useUserBalances, useVolr, useVolrAuthCallback, useVolrContext, useVolrLogin, useVolrPaymentApi, useVolrSession, useWithdraw };