@privy-io/react-auth 1.34.1-beta.3 → 1.34.1-beta.5

package/dist/index.d.ts

@@ -462,15 +462,11 @@ interface BaseConnectedWallet {
     /** The first time this wallet was connected without break. */
     connectedAt: number;
     /**
-     * @experimental **Experimental**: This property is {@link https://docs.privy.io/guide/guides/experimental-features subject to change at any time}.
-     *
      * The wallet client where this key-pair is stored.
      * e.g. metamask, rainbow, coinbase_wallet, etc.
      */
     walletClientType: WalletClientType;
     /**
-     * @experimental **Experimental**: This property is {@link https://docs.privy.io/guide/guides/experimental-features subject to change at any time}.
-     *
      * The connector used to initiate the connection with the wallet client.
      * e.g. injected, wallet_connect, coinbase_wallet, etc.
      */
@@ -501,9 +497,9 @@ interface BaseConnectedWallet {
     /**
      * @experimental **Experimental**: This property is {@link https://docs.privy.io/guide/guides/experimental-features subject to change at any time}.
      *
-     * Disconnect method does not work on all connector types and will no-op if
-     * an incompatible connector is used (metamask and phantom do not support
-     * programmatic disconnects)
+     * Not all wallet clients support programmatic disconnects (e.g. MetaMask, Phantom).
+     * In kind, if the wallet's client does not support programmatic disconnects,
+     * this method will no-op.
      */
     disconnect: () => void;
 }
@@ -672,6 +668,7 @@ type PrivyServerConfig = {
     customApiUrl?: string | null;
     walletConnectCloudProjectId?: string | null;
     embeddedWalletConfig: EmbeddedWalletsConfig;
+    captchaEnabled?: boolean;
     /** May be deprecated from the server config in a future release */
     logoUrl?: string;
     /** May be deprecated from the server config in a future release */
@@ -722,6 +719,7 @@ type PrivyClientConfig = {
         privacyPolicyUrl?: string | null;
     };
     walletConnectCloudProjectId?: string;
+    captchaEnabled?: boolean;
     /** All embedded wallets configuration */
     embeddedWallets?: {
         /**
@@ -848,11 +846,11 @@ type ContractUIOptions = {
     /**
      * URL with more information about the smart contract.
      */
-    url: string;
+    url?: string;
     /**
      * Name of smart contract being called.
      */
-    name: string;
+    name?: string;
     /**
      * URL for an image to show in the Send Transaction screen.
      */
@@ -1128,6 +1126,8 @@ interface PrivyInterface {
      * You may use this token to authorize requests sent from your frontend, and can validate it in your backend against your app's Privy verification key.
      *
      * This will automatically attempt to refresh the session if the token is expired or about to expire.
+     *
+     * @returns Promise for the user's access token as a string if they are authenticated, null if they are unauthenticated.
      */
     getAccessToken: () => Promise<string | null>;
     /**
@@ -1164,35 +1164,59 @@ interface PrivyInterface {
     walletConnectors: ConnectorManager | null;
     /**
      * Unlink an email account from a user, by passing the email address. Note that you can only unlink an email account if the user has at least one other account.
+     *
+     * @param address {string} email address to be unlinked
+     * @returns Promise for the {@link User} object after the provided email has been unlinked
      */
     unlinkEmail: (address: string) => Promise<User>;
     /**
      * Unlink a phone account from a user, by passing the phone number. Note that you can only unlink a phone account if the user has at least one other account.
+     *
+     * @param phoneNumber {string} phone number to be unlinked
+     * @returns Promise for the {@link User} object after the provided phone number has been unlinked
      */
     unlinkPhone: (phoneNumber: string) => Promise<User>;
     /**
      * Unlink a wallet account from a user, by passing the public address. Note that you can only unlink a wallet account if the user has at least one other account.
      * If the unlinked wallet was the active one, and more wallets are linked to the user, then we attempt to make the most recently linked wallet active.
+     *
+     * @param address {string} wallet address to be unlinked
+     * @returns Promise for the {@link User} object after the provided wallet has been unlinked
      */
     unlinkWallet: (address: string) => Promise<User>;
     /**
      * Unlink a Google social account from a user, by passing the google subject ID. Note that you can only unlink a social account if the user has at least one other account.
+     *
+     * @param subject {string} google account's subject ID
+     * @returns Promise for the {@link User} object after the provided Google account has been unlinked
      */
     unlinkGoogle: (subject: string) => Promise<User>;
     /**
      * Unlink a Twitter social account from a user, by passing the twitter subject ID. Note that you can only unlink a social account if the user has at least one other account.
+     *
+     * @param subject {string} twitter account's subject ID
+     * @returns Promise for the {@link User} object after the provided Twitter account has been unlinked
      */
     unlinkTwitter: (subject: string) => Promise<User>;
     /**
      * Unlink a Discord social account from a user, by passing the discord subject ID. Note that you can only unlink a social account if the user has at least one other account.
+     *
+     * @param subject {string} discord account's subject ID
+     * @returns Promise for the {@link User} object after the provided Discord account has been unlinked
      */
     unlinkDiscord: (subject: string) => Promise<User>;
     /**
      * Unlink a Github social account from a user, by passing the github subject ID. Note that you can only unlink a social account if the user has at least one other account.
+     *
+     * @param subject {string} github account's subject ID
+     * @returns Promise for the {@link User} object after the provided Github account has been unlinked
      */
     unlinkGithub: (subject: string) => Promise<User>;
     /**
      * Unlink a Apple social account from a user, by passing the apple subject ID. Note that you can only unlink a social account if the user has at least one other account.
+     *
+     * @param subject {string} apple account's subject ID
+     * @returns Promise for the {@link User} object after the provided Apple account has been unlinked
      */
     unlinkApple: (subject: string) => Promise<User>;
     /**
@@ -1209,28 +1233,62 @@ interface PrivyInterface {
      */
     forkSession: () => Promise<string>;
     /**
-     * @experimental **Experimental**: This feature is {@link https://docs.privy.io/guide/guides/experimental-features subject to change at any time}.
+     * Creates an embedded wallet for the current user.
+     *
+     * This method will error if the user already has an embedded wallet or if they
+     * exit in the middle of the flow.
      *
-     * Prompts a user to create an Ethereum wallet through Privy.
+     * If the `config.embeddedWallets.requireUserPasscodeOnCreate` property is set to true,
+     * this will prompt the user to enter a passcode to secure the recovery share of their
+     * embedded wallet.
      *
-     * This function will fail if the user has already created a wallet through Privy,
-     * as Privy currently only supports creating one wallet per user.
+     * Otherwise (the default), Privy will secure the recovery share, and the embedded wallet
+     * will be created without showing any UIs to the user.
      *
-     * This requires a user to enter a recovery pin that can later be used to recover the
-     * wallet or port it across devices.
+     * @returns Promise for the {@link Wallet} object for the newly created embedded wallet
      */
     createWallet: () => Promise<Wallet>;
     /**
-     * @experimental **Experimental**: This feature is {@link https://docs.privy.io/guide/guides/experimental-features subject to change at any time}.
+     * Prompts a user to sign a message using their embedded wallet using EIP-191's `personal_sign`
+     * method (0x45).
      *
-     * Prompts a user to sign a message using their Privy wallet.
+     * This method will error if the user is not authenticated or does not have an embedded wallet.
      *
-     * The resulting signature is an EIP-191 personal_sign signature (0x45).
+     * If the `config.embeddedWallets.noPromptOnSignature` property is set to true, the signature will
+     * be computed without prompting the user. Otherwise (the default), Privy will show the user a modal
+     * to prompt them for a signature. This can be customized via the {@link SignMessageModalUIOptions}.
      *
-     * This function currently has a precondition that the user has a Privy wallet. It will fail otherwise.
+     * @param message {string} message to be signed
+     * @param uiOptions {@link SignMessageModalUIOptions} (optional) UI options to customize the signature prompt modal
+     * @returns Promise for the signature as a string
      */
     signMessage: (message: string, uiOptions?: SignMessageModalUIOptions) => Promise<string>;
+    /**
+     * Prompts a user to send a transaction using their embedded wallet.
+     *
+     * This method will error if the user is not authenticated or does not have an embedded wallet.
+     *
+     * If no `chainId` is specified as part of the {@link UnsignedTransactionRequest}, Privy will default
+     * to the embedded wallet's current chain ID.
+     *
+     * If the `config.embeddedWallets.noPromptOnSignature` property is set to true, the wallet will
+     * attempt to send the transaction without prompting the user. Otherwise (the default), Privy
+     * will show the user a modal to have them confirm the transaction. This can be customized via
+     * the {@link SendTransactionModalUIOptions}.
+     *
+     * @param data {@link UnsignedTransactionRequest} transaction to be sent
+     * @param uiOptions {@link SendTransactionModalUIOptions} (optional) UI options to customize the transaction request modal
+     * @returns Promise for the transaction's {@link TransactionReceipt}
+     */
     sendTransaction: (data: UnsignedTransactionRequest, uiOptions?: SendTransactionModalUIOptions) => Promise<TransactionReceipt>;
+    /**
+     * Shows the user a Privy modal, from which they can copy their embedded wallet's private
+     * key for easy export to another wallet client (e.g. MetaMask). The private key is loaded
+     * on an iframe running on a separate domain from your app, meaning your app cannot access it.
+     *
+     * This method will error if the user is not authenticated or does not have an embedded wallet.
+     * @returns Promise that resolves once the user exits the modal
+     */
     exportWallet: () => Promise<void>;
 }
 /**
@@ -1506,16 +1564,15 @@ type PrivyEvents = {
          *   this will run after the user successfully authenticates _and_ creates their wallet (if applicable).
          * - If a user is already authenticated, this will run immediately and the `wasAlreadyAuthenticated` flag will be set to `true`.
          *
-         * @param user {User} - the `user` oject corresponding to the authenticated user
-         * @param isNewUser {boolean} - boolean flag indicating if this is the user's first time logging in to your app
+         * @param user {@link User} the `user` oject corresponding to the authenticated user
+         * @param isNewUser {boolean} boolean flag indicating if this is the user's first time logging in to your app
          * @param wasAlreadyAuthenticated {boolean} - boolean flag indicating whether the user entered the application already authenticated
-         *
          */
         onComplete?: (user: User, isNewUser: boolean, wasAlreadyAuthenticated: boolean) => void;
         /**
          * Callback that will execute in the case of a non-successful login.
          *
-         * @param error {PrivyErrorCode} - the corresponding error code
+         * @param error {@link PrivyErrorCode} - the corresponding error code
          *
          */
         onError?: CallbackError;
@@ -1531,20 +1588,27 @@ type PrivyEvents = {
          * Callback that will execute once a successful `connectWallet` completes.
          * This will not run in the case of a wallet-based authentication flow.
          *
-         * @param wallet {BaseConnectedWallet}- the `wallet` object correspending to the connection
-         *
+         * @param wallet {@link BaseConnectedWallet} the `wallet` object correspending to the connection
          */
         onSuccess?: (wallet: BaseConnectedWallet) => void;
         /**
          * Callback that will execute in the case of a non-successful wallet connection.
          *
-         * @param error {PrivyErrorCode} - the corresponding error code
-         *
+         * @param error {@link PrivyErrorCode} - the corresponding error code
          */
         onError?: CallbackError;
     };
 };
 
+/**
+ * Use this hook to log the user in, and to attach callbacks
+ * for successful `login`s, already-`authenticated` users, and
+ * `login` errors.
+ *
+ * @param callbacks.onComplete {@link PrivyEvents} callback to execute for already- or newly-`authenticated` users
+ * @param callbacks.onError {@link PrivyEvents} callback to execute if there is an error during `login`.
+ * @returns login - opens the Privy modal and prompts the user to login
+ */
 declare function useLogin(callbacks?: PrivyEvents['login']): {
     /**
      * Opens the Privy login modal and prompts the user to login.
@@ -1552,6 +1616,12 @@ declare function useLogin(callbacks?: PrivyEvents['login']): {
     login: () => void;
 };
 
+/**
+ * Use this hook to log the user out, and to attach a callback after a successful logout.
+ *
+ * @param callbacks.onSuccess {@link PrivyEvents} callback to execute when a user successfully logs out.
+ * @returns logout - logs the user out and clears their authentication state.
+ */
 declare function useLogout(callbacks?: PrivyEvents['logout']): {
     /**
      * Log the current user out and clears their authentication state. `authenticated` will become false, `user` will become null, and the Privy Auth tokens will be deleted from the browser's local storage.
@@ -1559,6 +1629,15 @@ declare function useLogout(callbacks?: PrivyEvents['logout']): {
     logout: () => Promise<void>;
 };
 
+/**
+ * Use this hook to connect the user's external wallet, and to attach
+ * callbacks after a user succesfully connects their wallet, or if there
+ * is an error during the connection attempt.
+ *
+ * @param callbacks.onSuccess {@link PrivyEvents} callback to execute when a user successfully connects their wallet
+ * @param callbacks.onError {@link PrivyEvents} callback to execute when a user attempts to connect their wallet, but there is an error
+ * @returns connectWallet - opens the Privy modal and prompts the user to connect an external wallet
+ */
 declare function useConnectWallet(callbacks?: PrivyEvents['connectWallet']): {
     /**
      * Opens the Privy modal and prompts the user to connect a wallet.
@@ -1613,4 +1692,4 @@ type Chain = {
 
 declare const SUPPORTED_CHAINS: readonly [Chain, Chain, Chain, Chain, Chain, Chain, Chain, Chain, Chain, Chain, Chain, Chain, Chain, Chain, Chain, Chain, Chain, Chain, Chain];
 
-export { Apple, AppleOAuthWithMetadata, AsExternalProvider, ConnectedWallet, ConnectorManager, ContractUIOptions, Discord, DiscordOAuthWithMetadata, EIP1193Provider, Email, EmailWithMetadata, Github, GithubOAuthWithMetadata, Google, GoogleOAuthWithMetadata, Phone, PhoneWithMetadata, PrivyClient, PrivyClientConfig, PrivyInterface, PrivyProvider, PrivyProviderProps, PrivyProxyProvider, Quantity, SUPPORTED_CHAINS, SendTransactionModalUIOptions, SignMessageModalUIOptions, TransactionLog, TransactionReceipt, TransactionUIOptions, Twitter, TwitterOAuthWithMetadata, UnsignedTransactionRequest, UseWalletsInterface, User, VERSION, Wallet, WalletConnector, WalletWithMetadata, getAccessToken, useConnectWallet, useLogin, useLogout, usePrivy, useWallets };
+export { Apple, AppleOAuthWithMetadata, AsExternalProvider, CallbackError, ConnectedWallet, ConnectorManager, ContractUIOptions, Discord, DiscordOAuthWithMetadata, EIP1193Provider, Email, EmailWithMetadata, Github, GithubOAuthWithMetadata, Google, GoogleOAuthWithMetadata, Phone, PhoneWithMetadata, PrivyClient, PrivyClientConfig, PrivyEvents, PrivyInterface, PrivyProvider, PrivyProviderProps, PrivyProxyProvider, Quantity, SUPPORTED_CHAINS, SendTransactionModalUIOptions, SignMessageModalUIOptions, TransactionLog, TransactionReceipt, TransactionUIOptions, Twitter, TwitterOAuthWithMetadata, UnsignedTransactionRequest, UseWalletsInterface, User, VERSION, Wallet, WalletConnector, WalletWithMetadata, getAccessToken, useConnectWallet, useLogin, useLogout, usePrivy, useWallets };