# `useEmailAuth`

Handle email/password authentication: sign in, sign up, password reset, and email verification.

## Usage

```tsx
import { useEmailAuth } from '@openfort/react';

function LoginForm() {
  const { signInEmail, signUpEmail, isLoading } = useEmailAuth();

  const handleLogin = async (email: string, password: string) => {
    const { error, user, requiresEmailVerification } = await signInEmail({ email, password });
    if (requiresEmailVerification) {
      // Show a message asking the user to verify their email.
    }
  };

  return null;
}
```

## Return type

```ts
type UseEmailAuthReturn = {
  signInEmail(options: SignInEmailOptions): Promise<EmailAuthResult>
  signUpEmail(options: SignUpEmailOptions): Promise<EmailAuthResult>
  verifyEmail(options: VerifyEmailOptions): Promise<EmailVerificationResult>
  linkEmail(options: LinkEmailOptions): Promise<EmailAuthResult>
  requestResetPassword(options: RequestResetPasswordOptions): Promise<EmailAuthResult>
  resetPassword(options: ResetPasswordOptions): Promise<EmailAuthResult>
  reset(): void
  requiresEmailVerification: boolean
  isAwaitingInput: boolean
  isLoading: boolean
  isError: boolean
  isSuccess: boolean
  error?: OpenfortError | null
}

type EmailAuthResult = {
  user?: User
  wallet?: UserWallet
  requiresEmailVerification?: boolean
  error?: OpenfortError
}
```

## Hook options

Configure default behavior when initializing the hook.

```ts
type UseEmailHookOptions = {
  // Default redirect URL for email verification.
  emailVerificationRedirectTo?: string
  // Log out the user if wallet recovery fails. Defaults to true.
  logoutOnError?: boolean
  // Automatically recover the wallet after authentication. Defaults to true.
  recoverWalletAutomatically?: boolean
  onSuccess?: (data: EmailAuthResult | EmailVerificationResult) => void
  onError?: (error: OpenfortError) => void
}
```

## Parameters

### signInEmail

```ts
type SignInEmailOptions = {
  email: string
  password: string
  emailVerificationRedirectTo?: string
  // Overrides the hook-level default.
  logoutOnError?: boolean
  // Overrides the hook-level default.
  recoverWalletAutomatically?: boolean
  onSuccess?: (data: EmailAuthResult) => void
  onError?: (error: OpenfortError) => void
}
```

### signUpEmail

```ts
type SignUpEmailOptions = {
  email: string
  password: string
  name?: string
  emailVerificationRedirectTo?: string
  // Overrides the hook-level default.
  logoutOnError?: boolean
  // Overrides the hook-level default.
  recoverWalletAutomatically?: boolean
  onSuccess?: (data: EmailAuthResult) => void
  onError?: (error: OpenfortError) => void
}
```

### verifyEmail

```ts
type VerifyEmailOptions = {
  email: string
  // Verification code from the email.
  state: string
  onSuccess?: (data: EmailVerificationResult) => void
  onError?: (error: OpenfortError) => void
}
```

### linkEmail

Link an email to an existing account. A verification email will be sent to the provided email address.

```ts
type LinkEmailOptions = {
  email: string
  emailVerificationRedirectTo?: string
  onSuccess?: (data: EmailAuthResult) => void
  onError?: (error: OpenfortError) => void
}
```

### requestResetPassword

```ts
type RequestResetPasswordOptions = {
  email: string
  emailVerificationRedirectTo?: string
  onSuccess?: (data: EmailAuthResult) => void
  onError?: (error: OpenfortError) => void
}
```

### resetPassword

```ts
type ResetPasswordOptions = {
  email: string
  password: string
  // Reset code from the email.
  state: string
  onSuccess?: (data: EmailAuthResult) => void
  onError?: (error: OpenfortError) => void
}
```