feat: update useAuthenticate and useAccount to include mutation args (#…

…592)

packages/alchemy/src/react/hooks/useAccount.ts

@@ -12,10 +12,15 @@ import {
   defaultAccountState,
   type SupportedAccount,
   type SupportedAccountTypes,
+  type SupportedAccounts,
 } from "../../config/index.js";
 import { useAlchemyAccountContext } from "../context.js";
+import type { BaseHookMutationArgs } from "../types.js";
 import { useSignerStatus } from "./useSignerStatus.js";
 
+export type UseAccountMutationArgs<TAccount extends SupportedAccountTypes> =
+  BaseHookMutationArgs<SupportedAccount<TAccount> | SupportedAccounts, void>;
+
 export type UseAccountResult<TAccount extends SupportedAccountTypes> = {
   account?: SupportedAccount<TAccount>;
   isLoadingAccount: boolean;
@@ -24,37 +29,34 @@ export type UseAccountResult<TAccount extends SupportedAccountTypes> = {
 export type UseAccountProps<TAccount extends SupportedAccountTypes> =
   GetAccountParams<TAccount> & {
     skipCreate?: boolean;
-  };
+  } & UseAccountMutationArgs<TAccount>;
 
 export function useAccount<TAccount extends SupportedAccountTypes>(
   params: UseAccountProps<TAccount>
 ): UseAccountResult<TAccount> {
+  const { type, accountParams, skipCreate, ...mutationArgs } = params;
   const { config, queryClient } = useAlchemyAccountContext();
   const status = useSignerStatus();
   const account = useSyncExternalStore(
-    watchAccount(params.type, config),
+    watchAccount(type, config),
     () => getAccount(params, config),
     defaultAccountState<TAccount>
   );
 
   const { mutate, isPending } = useMutation(
     {
       mutationFn: async () => account?.account ?? createAccount(params, config),
-      mutationKey: ["createAccount", params.type],
+      mutationKey: ["createAccount", type],
+      ...mutationArgs,
     },
     queryClient
   );
 
   useEffect(() => {
-    if (
-      !params.skipCreate &&
-      status.isConnected &&
-      !account?.account &&
-      !isPending
-    ) {
+    if (!skipCreate && status.isConnected && !account?.account && !isPending) {
       mutate();
     }
-  }, [account, isPending, mutate, params.skipCreate, status]);
+  }, [account, isPending, mutate, skipCreate, status]);
 
   return {
     account: account.status === "READY" ? account?.account : undefined,

packages/alchemy/src/react/hooks/useAuthenticate.ts

@@ -5,15 +5,23 @@ import { ClientOnlyPropertyError } from "../../config/errors.js";
 import type { User } from "../../signer/index.js";
 import type { AuthParams } from "../../signer/signer.js";
 import { useAlchemyAccountContext } from "../context.js";
+import type { BaseHookMutationArgs } from "../types.js";
 import { useSigner } from "./useSigner.js";
 
+export type UseAuthenticateMutationArgs = BaseHookMutationArgs<
+  User,
+  AuthParams
+>;
+
 export type UseAuthenticateResult = {
   authenticate: UseMutateFunction<User, Error, AuthParams, unknown>;
   isPending: boolean;
   error: Error | null;
 };
 
-export function useAuthenticate(): UseAuthenticateResult {
+export function useAuthenticate(
+  mutationArgs?: UseAuthenticateMutationArgs
+): UseAuthenticateResult {
   const { queryClient } = useAlchemyAccountContext();
   const signer = useSigner();
 
@@ -30,6 +38,7 @@ export function useAuthenticate(): UseAuthenticateResult {
 
         return signer.authenticate(authParams);
       },
+      ...mutationArgs,
     },
     queryClient
   );

site/react/useAccount.md

@@ -66,6 +66,10 @@ An optional param object based on the `type` property passed in above. It allows
 
 An optional param that allows you to avoid creating a new instance of the account. This is useful if you know your account has already been created and cached locally.
 
+### ...mutationArgs
+
+ <!--@include: ./BaseHookMutationArgs.md-->
+
 ## Return Type
 
 ```ts

site/react/useAuthenticate.md

@@ -32,6 +32,10 @@ import { useAuthenticate } from "@alchemy/aa-alchemy/react";
 
 <<< @/snippets/react/login.tsx
 
+## Params
+
+<!--@include: ./BaseHookMutationArgs.md-->
+
 ## Return Type
 
 ```ts

site/snippets/getting-started/setup-app/providers.tsx

@@ -9,7 +9,7 @@ import { PropsWithChildren, Suspense } from "react";
 export const Providers = (props: PropsWithChildren) => {
   const queryClient = new QueryClient();
   const config = createConfig({
-    rpcUrl: "/api/rpc",
+    rpcUrl: "/api/rpc", // this will proxy requests through the app's backend via NextJS routing to hide the Alchemy API key
     chain: arbitrumSepolia,
   });
 

site/snippets/react/login.tsx

@@ -3,7 +3,14 @@ import { useState } from "react";
 
 export function Login() {
   const [email, setEmail] = useState("");
-  const { authenticate, isPending } = useAuthenticate();
+  const { authenticate, isPending } = useAuthenticate({
+    onSuccess: (user) => {
+      // [optional] Do something with the user info
+    },
+    onError: (error) => {
+      // [optional] Do something with the error
+    },
+  });
 
   return (
     <div>

site/snippets/react/useAccount.tsx

@@ -5,6 +5,13 @@ export function ComponentUsingAccount() {
   const { isLoadingAccount, account } = useAccount({
     type: "LightAccount", // alternatively pass in "MultiOwnerModularAccount",
     accountParams: {}, // optional param for overriding any account specific properties
+    skipCreate: false, // optional param to skip creating the account
+    onSuccess: (account) => {
+      // [optional] Do something with the account
+    },
+    onError: (error) => {
+      // [optional] Do something with the error
+    },
   });
 
   if (isLoadingAccount || !account) {