### Install and Setup ClerkProvider

Source: https://context7.com/ronasit/clerk-react-native-hooks/llms.txt

Install the package and its peer dependencies. Wrap your root layout with ClerkProvider, providing your publishable key.

```bash
npm install @ronas-it/clerk-react-native-hooks @clerk/expo @clerk/types expo-web-browser expo-auth-session expo-secure-store
```

```tsx
import { ClerkProvider } from '@clerk/expo';
import { Slot } from 'expo-router';

export default function RootLayout() {
  return (
    <ClerkProvider publishableKey={process.env.EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY!}>
      <Slot />
    </ClerkProvider>
  );
}
```

--------------------------------

### Install Dependencies

Source: https://github.com/ronasit/clerk-react-native-hooks/blob/main/CONTRIBUTING.md

Run this command to install project dependencies after cloning the repository.

```bash
npm install
```

--------------------------------

### Sign-up with Email/Password

Source: https://github.com/ronasit/clerk-react-native-hooks/blob/main/README.md

Initiate a sign-up flow using email and password. This example demonstrates capturing user details and handling the sign-up process, potentially leading to an OTP verification step.

```ts
const { startSignUp, isLoading } = useAuthWithIdentifier('emailAddress', 'otp');

const onSignUp = async (values: { emailAddress: string; password: string; firstName: string; lastName: string }) => {
  const { isSuccess, error } = await startSignUp({
    identifier: values.emailAddress,
    password: values.password,
    firstName: values.firstName,
    lastName: values.lastName,
  });

  if (isSuccess) {
    // go to the email OTP step
  }

  if (error) {
    showToast(error?.longMessage);
  }
};
```

--------------------------------

### Sign-in with Email and Password

Source: https://github.com/ronasit/clerk-react-native-hooks/blob/main/README.md

Perform a sign-in operation using email and password. This example shows how to call `startSignIn` and handle potential success or error responses, including the option to use a custom JWT template.

```ts
const { startSignIn, isLoading } = useAuthWithIdentifier('emailAddress', 'password');

const onSignIn = async (values: { emailAddress: string; password: string }) => {
  const { isSuccess, error } = await startSignIn({
    identifier: values.emailAddress,
    password: values.password,
    tokenTemplate: 'your_jwt_template',
  });

  if (isSuccess) {
    // handle success
  }

  if (error) {
    showToast(error?.longMessage);
  }
};
```

--------------------------------

### Handle Second Factor Authentication with useAuthWithIdentifier and useOtpVerification

Source: https://github.com/ronasit/clerk-react-native-hooks/blob/main/README.md

This snippet demonstrates how to handle scenarios where a second factor of authentication is required after a successful password sign-in. It uses `useAuthWithIdentifier` to start the sign-in process and `useOtpVerification` to manage the OTP code.

```typescript
const { startSignIn } = useAuthWithIdentifier('emailAddress', 'password');
const { sendOtpCode, verifyCode } = useOtpVerification('email_code');

const result = await startSignIn({ identifier, password, tokenTemplate });

if (!result.isSuccess && result.status === 'needs_second_factor') {
  await sendOtpCode({ isSecondFactor: true });
  // await verifyCode({ code, isSecondFactor: true, tokenTemplate })
}
```

--------------------------------

### Install Clerk React Native Hooks and Dependencies

Source: https://github.com/ronasit/clerk-react-native-hooks/blob/main/README.md

Install the necessary packages for Clerk authentication in your Expo project. Ensure your React, React Native, and Clerk/Expo versions are compatible.

```sh
npm install @ronas-it/clerk-react-native-hooks @clerk/expo @clerk/types expo-web-browser expo-auth-session expo-secure-store
```

--------------------------------

### useResetPassword

Source: https://github.com/ronasit/clerk-react-native-hooks/blob/main/README.md

Facilitates the password reset flow using email or phone OTP. It guides through starting the reset, verifying the code, and finally resetting the password.

```APIDOC
## useResetPassword

Password reset via email or phone OTP for the forgot-password flow.

Use the same `method` (`'emailAddress'` or `'phoneNumber'`) on `useResetPassword` for each step. To **resend** the reset code, call `startResetPassword` again with the **same** `identifier`.

1. `startResetPassword({ identifier })` — sends the reset code (`isCodeSending`); use the same call again to resend.
2. `verifyCode({ code })` — verifies the code (`isVerifying`).
3. `resetPassword({ password, tokenTemplate? })` — applies the new password and finishes sign-in (`isResetting`).

#### Example

```ts
// 1 — request code
const { startResetPassword, isCodeSending } = useResetPassword({ method: 'emailAddress' });

const onRequestCode = async (email: string) => {
  const { isSuccess, error } = await startResetPassword({ identifier: email });
  // if isSuccess → go to code step; keep `email` for resend
};
```

```ts
// 2 — submit code
const { verifyCode, isVerifying } = useResetPassword({ method: 'emailAddress' });

const onSubmitCode = async (code: string) => {
  const { isSuccess, error } = await verifyCode({ code });
  // if isSuccess → go to new-password step
};
```

```ts
// Resend — same as step 1: startResetPassword({ identifier }) again
const { startResetPassword, isCodeSending } = useResetPassword({ method: 'emailAddress' });

const onResendCode = (email: string) => {
  startResetPassword({ identifier: email });
};
```

```ts
// 3 — new password
const { resetPassword, isResetting } = useResetPassword({ method: 'emailAddress' });

const onSetNewPassword = async (password: string) => {
  const { isSuccess, sessionToken, error } = await resetPassword({
    password,
    tokenTemplate: 'your_jwt_template', // optional
  });
  // if isSuccess → handle success
};
```

For SMS, use `{ method: 'phoneNumber' }` and pass the phone number as `identifier`.
```

--------------------------------

### Sign-up with Email/Password and Separate OTP Verification

Source: https://github.com/ronasit/clerk-react-native-hooks/blob/main/README.md

This flow uses `useAuthWithIdentifier` for initial sign-up with email and password, then `useOtpVerification` to handle the subsequent OTP verification step.

```ts
const { startSignUp, isLoading } = useAuthWithIdentifier('emailAddress', 'password');
const { sendOtpCode } = useOtpVerification('email_code');

await startSignUp({ identifier: values.emailAddress, password: values.password });
await sendOtpCode({ isSignUp: true });
```

--------------------------------

### useClerkResources

Source: https://github.com/ronasit/clerk-react-native-hooks/blob/main/README.md

Returns core Clerk resources such as signUp, signIn, and signOut functionality.

```APIDOC
## useClerkResources

### Description
Returns core Clerk resources used by the higher-level hooks.

### Returns
- `signUp` — [SignUp](https://clerk.com/docs/expo/reference/objects/sign-in-future)
- `signIn` — [SignIn](https://clerk.com/docs/expo/reference/objects/sign-in-future)
- `signOut` — signs out the current user
```

--------------------------------

### SSO Authentication with useAuthWithSSO

Source: https://github.com/ronasit/clerk-react-native-hooks/blob/main/README.md

Integrates Single Sign-On (SSO) using various strategies like OAuth. Requires `strategy`, `redirectUrl`, and optionally a `tokenTemplate`. The `startSSOFlow` function initiates the SSO process.

```typescript
import * as AuthSession from 'expo-auth-session';

const { startSSOFlow, isLoading } = useAuthWithSSO();

const onGooglePress = async () => {
  const { isSuccess, error } = await startSSOFlow({
    strategy: 'oauth_google',
    redirectUrl: AuthSession.makeRedirectUri({ path: navigationConfig.auth.signUp }),
    tokenTemplate: 'your_jwt_template', // optional
  });

  if (isSuccess) {
    // handle success
  }

  if (error) {
    showToast(error?.longMessage);
  }
};
```

--------------------------------

### Sign-in or Sign-up with Email/Phone OTP

Source: https://github.com/ronasit/clerk-react-native-hooks/blob/main/README.md

Use this hook for flows where sign-in and sign-up share a single identifier (email or phone). It supports the `signUpIfMissing` option to send OTP even if the account doesn't exist. The first screen initiates the sign-in/sign-up process, and the second screen handles OTP verification.

```typescript
const { startSignIn, isLoading } = useAuthWithIdentifier('emailAddress', 'otp');

const onContinue = async (email: string) => {
  const { error, isSuccess } = await startSignIn({ identifier: email, signUpIfMissing: true });

  if (isSuccess) {
    // go to OTP step (same hook instance keeps signIn / signUp resources)
  }

  if (error) {
    showToast(error?.longMessage);
  }
};
```

```typescript
const { verifyCode, isVerifying } = useAuthWithIdentifier('emailAddress', 'otp');

const onVerify = async (code: string) => {
  const { sessionToken, error, isSuccess, signUp } = await verifyCode({
    code,
    tokenTemplate: 'your_jwt_template',
  });

  if (isSuccess) {
    // handle success
  }

  if (error) {
    showToast(error?.longMessage);
  }
};
```

--------------------------------

### useAuthWithIdentifier (Sign-in/Sign-up with OTP)

Source: https://github.com/ronasit/clerk-react-native-hooks/blob/main/README.md

Handles sign-in and sign-up flows using an email or phone number and an OTP. It supports the `signUpIfMissing` option to allow verification even if the user account doesn't exist yet.

```APIDOC
## useAuthWithIdentifier (Sign-in/Sign-up with OTP)

### Description
Use this hook when sign-in and sign-up share one identifier (email or phone). It facilitates Clerk’s `signUpIfMissing` flow so verification runs even if the account does not exist yet.

### First Screen - Start Sign In

```ts
const { startSignIn, isLoading } = useAuthWithIdentifier('emailAddress', 'otp');

const onContinue = async (email: string) => {
  const { error, isSuccess } = await startSignIn({ identifier: email, signUpIfMissing: true });

  if (isSuccess) {
    // go to OTP step (same hook instance keeps signIn / signUp resources)
  }

  if (error) {
    showToast(error?.longMessage);
  }
};
```

### OTP Screen - Verify Code

```ts
const { verifyCode, isVerifying } = useAuthWithIdentifier('emailAddress', 'otp');

const onVerify = async (code: string) => {
  const { sessionToken, error, isSuccess, signUp } = await verifyCode({
    code,
    tokenTemplate: 'your_jwt_template'
  });

  if (isSuccess) {
    // handle success
  }

  if (error) {
    showToast(error?.longMessage);
  }
};
```

### Notes
On the code screen, `useOtpVerification` can be used for resend/verify. Use `isSignUp: false` for `sendOtpCode` and `verifyCode` on this path to maintain correct transfer behavior.
```

--------------------------------

### Unified Sign-in/Sign-up with OTP using useAuthWithIdentifier

Source: https://context7.com/ronasit/clerk-react-native-hooks/llms.txt

Provides a single identifier field for both sign-in and sign-up with OTP. The startSignIn function can be used with `signUpIfMissing: true` to send OTP even if no account exists.

```tsx
import { useAuthWithIdentifier } from '@ronas-it/clerk-react-native-hooks';

// --- Sign-in-or-up (single identifier field) ---
function UnifiedAuthScreen() {
  const { startSignIn, verifyCode, isLoading, isVerifying } = useAuthWithIdentifier('emailAddress', 'otp');

  const onContinue = async (email: string) => {
    // signUpIfMissing: Clerk sends OTP even if no account exists yet
    const { isSuccess, error } = await startSignIn({ identifier: email, signUpIfMissing: true });
    if (!isSuccess) Alert.alert('Error', String(error));
  };

  const onVerify = async (code: string) => {
    const { isSuccess, sessionToken, signUp, error } = await verifyCode({ code });
    if (isSuccess) {
      const isNewUser = !!signUp?.createdUserId;
      console.log(isNewUser ? 'New user registered' : 'Existing user signed in', sessionToken);
    }
    if (error) Alert.alert('Error', String(error));
  };
}
```

--------------------------------

### Passwordless Sign-up and Sign-in with OTP

Source: https://github.com/ronasit/clerk-react-native-hooks/blob/main/README.md

Use `useAuthWithIdentifier` for passwordless authentication via email or phone OTP. Handles both new user sign-up and existing user sign-in flows.

```ts
const { startSignUp, startSignIn, verifyCode } = useAuthWithIdentifier('emailAddress', 'otp');
// useAuthWithIdentifier('phoneNumber', 'otp') for SMS

await startSignUp({ identifier }); // new user
await verifyCode({ code, isSignUp: true, tokenTemplate });

await startSignIn({ identifier }); // existing user
await verifyCode({ code, tokenTemplate });
```

```ts
const { verifyCode, sendOtpCode } = useOtpVerification('email_code'); // SMS: useOtpVerification('phone_code')
await sendOtpCode({ isSignUp: true });
await verifyCode({ code, isSignUp: true, tokenTemplate });
```

--------------------------------

### Configure ClerkProvider in RootLayout

Source: https://github.com/ronasit/clerk-react-native-hooks/blob/main/README.md

Wrap your root layout with ClerkProvider from @clerk/expo and provide your Clerk publishable key. This sets up the Clerk context for your application.

```tsx
import { ClerkProvider } from '@clerk/expo';
import { Slot } from 'expo-router';

export default function RootLayout() {
  return (
    <ClerkProvider publishableKey={publishableKey}>
      <Slot />
    </ClerkProvider>
  );
}
```

--------------------------------

### Push Changes and Tags

Source: https://github.com/ronasit/clerk-react-native-hooks/blob/main/CONTRIBUTING.md

After bumping the version, push the commit and the newly created tag to the remote repository.

```bash
git push && git push --tags
```

--------------------------------

### useAuthWithSSO

Source: https://context7.com/ronasit/clerk-react-native-hooks/llms.txt

Initiates an OAuth SSO flow (Google, GitHub, Apple, etc.) using expo-auth-session and expo-web-browser. Returns a sessionToken on success.

```APIDOC
## `useAuthWithSSO` — Social / OAuth Sign-In

Initiates an OAuth SSO flow (Google, GitHub, Apple, etc.) using `expo-auth-session` and `expo-web-browser`. Returns a `sessionToken` on success.

### Usage

```tsx
import * as AuthSession from 'expo-auth-session';
import { useAuthWithSSO } from '@ronas-it/clerk-react-native-hooks';

function SocialAuthButtons() {
  const { startSSOFlow, isLoading } = useAuthWithSSO();

  const signInWith = async (provider: 'oauth_google' | 'oauth_github' | 'oauth_apple') => {
    const { isSuccess, sessionToken, error } = await startSSOFlow({
      strategy: provider,
      redirectUrl: AuthSession.makeRedirectUri({ path: '/auth/callback' }),
      tokenTemplate: 'my_jwt_template', // optional
    });

    if (isSuccess) console.log('SSO token:', sessionToken);
    if (error) Alert.alert('SSO Error', String(error));
  };

  return (
    <View>
      <Button title="Continue with Google" onPress={() => signInWith('oauth_google')} disabled={isLoading} />
      <Button title="Continue with GitHub" onPress={() => signInWith('oauth_github')} disabled={isLoading} />
      <Button title="Continue with Apple"  onPress={() => signInWith('oauth_apple')}  disabled={isLoading} />
    </View>
  );
}
```

### Parameters

`useAuthWithSSO` returns an object with the following properties:

- **startSSOFlow**: A function to initiate the SSO flow. Accepts an object with:
  - **strategy** (string): The SSO provider. e.g., `'oauth_google'`, `'oauth_github'`, `'oauth_apple'`.
  - **redirectUrl** (string): The URL to redirect to after authentication.
  - **tokenTemplate** (string, optional): A template for the JWT.
- **isLoading**: A boolean indicating if the SSO flow is in progress.
```

--------------------------------

### Password-based Sign-in with useAuthWithIdentifier

Source: https://context7.com/ronasit/clerk-react-native-hooks/llms.txt

Handles email sign-in using a password. The startSignIn function accepts identifier, password, and an optional tokenTemplate.

```tsx
import { useAuthWithIdentifier } from '@ronas-it/clerk-react-native-hooks';

// --- Password-based sign-in ---
function SignInScreen() {
  const { startSignIn, isLoading } = useAuthWithIdentifier('emailAddress', 'password');

  const onSubmit = async (email: string, password: string) => {
    const { isSuccess, sessionToken, error } = await startSignIn({
      identifier: email,
      password,
      tokenTemplate: 'my_jwt_template',
    });
    if (isSuccess) console.log('Signed in, token:', sessionToken);
    if (error) Alert.alert('Error', error?.longMessage);
  };

  return <LoginForm onSubmit={onSubmit} loading={isLoading} />;
}
```

--------------------------------

### Run Code Checks

Source: https://github.com/ronasit/clerk-react-native-hooks/blob/main/CONTRIBUTING.md

Execute these commands to manually run code style and correctness checks before committing.

```bash
lint
```

```bash
format
```

--------------------------------

### useAuthWithIdentifier

Source: https://github.com/ronasit/clerk-react-native-hooks/blob/main/README.md

Facilitates signing up or signing in using an identifier (email, phone, username) with either OTP or password verification.

```APIDOC
## useAuthWithIdentifier

### Description
Sign up or sign in with an identifier (`emailAddress`, `phoneNumber`, or `username`) using either OTP or password.

### Parameters
- `method` — `'emailAddress'`, `'phoneNumber'`, or `'username'`
- `verifyBy` — `'otp'` or `'password'`

### Returns
- `startSignUp`, `startSignIn`, `isLoading`
- For email/phone + OTP: `verifyCode`, `isVerifying` (`verifyCode` takes `code`, optional `tokenTemplate`; set `isSignUp: true` only on the sign-up path, omit for sign-in)
- For OTP **sign-in** only: `startSignIn` accepts optional `signUpIfMissing` (see Clerk: [Sign-in-or-up with `signUpIfMissing`](https://clerk.com/docs/guides/development/custom-flows/authentication/sign-in-or-up#sign-in-or-up-with-sign-up-if-missing))

### Examples
#### Passwordless sign-up and sign-in:

```ts
const { startSignUp, startSignIn, verifyCode } = useAuthWithIdentifier('emailAddress', 'otp');
// useAuthWithIdentifier('phoneNumber', 'otp') for SMS

await startSignUp({ identifier }); // new user
await verifyCode({ code, isSignUp: true, tokenTemplate });

await startSignIn({ identifier }); // existing user
await verifyCode({ code, tokenTemplate });
```

#### Password-based sign-up and sign-in:

```ts
// Sign-up: password + profile — OTP screen next (code is sent inside startSignUp when verifyBy is 'otp')
const { startSignUp, isLoading } = useAuthWithIdentifier('emailAddress', 'otp');

const onSignUp = async (values: { emailAddress: string; password: string; firstName: string; lastName: string }) => {
  const { isSuccess, error } = await startSignUp({
    identifier: values.emailAddress,
    password: values.password,
    firstName: values.firstName,
    lastName: values.lastName,
  });

  if (isSuccess) {
    // go to the email OTP step
  }

  if (error) {
    showToast(error?.longMessage);
  }
};
```

```ts
// Same flow but verifyBy: 'password' — send/verify OTP with useOtpVerification (not inside startSignUp)
const { startSignUp, isLoading } = useAuthWithIdentifier('emailAddress', 'password');
const { sendOtpCode } = useOtpVerification('email_code');

await startSignUp({ identifier: values.emailAddress, password: values.password });
await sendOtpCode({ isSignUp: true });
```

```ts
// Sign-in: email and password
const { startSignIn, isLoading } = useAuthWithIdentifier('emailAddress', 'password');

const onSignIn = async (values: { emailAddress: string; password: string }) => {
  const { isSuccess, error } = await startSignIn({
    identifier: values.emailAddress,
    password: values.password,
    tokenTemplate: 'your_jwt_template',
  });

  if (isSuccess) {
    // handle success
  }

  if (error) {
    showToast(error?.longMessage);
  }
};
```
```

--------------------------------

### useOtpVerification

Source: https://github.com/ronasit/clerk-react-native-hooks/blob/main/README.md

Provides lower-level OTP (One-Time Password) send and verify functionality for sign-in and sign-up flows. It can be configured for email or phone codes.

```APIDOC
## useOtpVerification

Lower-level OTP send/verify for sign-in and sign-up.

- First argument — `'email_code'` or `'phone_code'`: fixed for the hook instance (same as email vs phone in `useAuthWithIdentifier`).

`sendOtpCode` asks Clerk to deliver a code (first send or resend). `verifyCode` submits the code, activates the session, and optionally returns a JWT. Pass `isSignUp: true` only for sign-up; omit for sign-in (default).

- `sendOtpCode` — `{ isSignUp?, isSecondFactor? }` (both optional; sign-in and 2FA omit `isSignUp` or set `false`)
- `verifyCode` — `{ code, isSignUp?, tokenTemplate?, isSecondFactor? }`
- `isVerifying` — true while `verifyCode` is running

#### Example

```ts
const { verifyCode, isVerifying, sendOtpCode } = useOtpVerification('email_code');

const sendOrResendCode = () => {
  sendOtpCode({ isSignUp: true });
};

const onSubmitCode = async (code: string) => {
  const { isSuccess, error, sessionToken } = await verifyCode({
    code,
    isSignUp: true,
    tokenTemplate: 'your_jwt_template', // optional
  });

  if (isSuccess) {
    // handle success
  }
};
```

For SMS, use `useOtpVerification('phone_code')`. For sign-in OTP, omit `isSignUp` in both `sendOtpCode` and `verifyCode`.
```

--------------------------------

### Use OTP Verification: Send and Verify Email Code

Source: https://github.com/ronasit/clerk-react-native-hooks/blob/main/README.md

Handles sending and verifying OTP codes for email. `sendOtpCode` can be used for initial send or resend. `verifyCode` submits the code and activates the session.

```typescript
const { verifyCode, isVerifying, sendOtpCode } = useOtpVerification('email_code');

const sendOrResendCode = () => {
  sendOtpCode({ isSignUp: true });
};

const onSubmitCode = async (code: string) => {
  const { isSuccess, error, sessionToken } = await verifyCode({
    code,
    isSignUp: true,
    tokenTemplate: 'your_jwt_template', // optional
  });

  if (isSuccess) {
    // handle success
  }
};
```

--------------------------------

### Import Clerk React Native Hooks

Source: https://github.com/ronasit/clerk-react-native-hooks/blob/main/README.md

Import the specific hooks you need from the @ronas-it/clerk-react-native-hooks library to manage authentication flows.

```ts
import { useAuthWithIdentifier, useOtpVerification, useClerkResources } from '@ronas-it/clerk-react-native-hooks';
import type { OtpStrategy } from '@ronas-it/clerk-react-native-hooks';
```

--------------------------------

### Use Reset Password: Set New Password

Source: https://github.com/ronasit/clerk-react-native-hooks/blob/main/README.md

Applies the new password after successful OTP verification. This step also finishes the sign-in process and can optionally return a JWT.

```typescript
// 3 — new password
const { resetPassword, isResetting } = useResetPassword({ method: 'emailAddress' });

const onSetNewPassword = async (password: string) => {
  const { isSuccess, sessionToken, error } = await resetPassword({
    password,
    tokenTemplate: 'your_jwt_template', // optional
  });
  // if isSuccess → handle success
};
```

--------------------------------

### Passwordless Email OTP Sign-up with useAuthWithIdentifier

Source: https://context7.com/ronasit/clerk-react-native-hooks/llms.txt

Handles email sign-up using OTP. Requires useOtpVerification for code verification. The verifyCode function accepts an optional tokenTemplate.

```tsx
import { useAuthWithIdentifier, useOtpVerification } from '@ronas-it/clerk-react-native-hooks';

// --- Passwordless email OTP sign-up ---
function SignUpScreen() {
  const { startSignUp, isLoading } = useAuthWithIdentifier('emailAddress', 'otp');
  const { verifyCode, sendOtpCode, isVerifying } = useOtpVerification('email_code');
  const [step, setStep] = React.useState<'email' | 'otp'>('email');

  const onSubmitEmail = async (email: string) => {
    const { isSuccess, error } = await startSignUp({ identifier: email });
    if (isSuccess) setStep('otp');
    if (error) console.error(error);
  };

  const onSubmitCode = async (code: string) => {
    const { isSuccess, sessionToken, error } = await verifyCode({
      code,
      isSignUp: true,
      tokenTemplate: 'my_jwt_template', // optional
    });
    if (isSuccess) console.log('Session token:', sessionToken);
    if (error) console.error(error);
  };

  return step === 'email'
    ? <EmailInput onSubmit={onSubmitEmail} loading={isLoading} />
    : <OtpInput onSubmit={onSubmitCode} onResend={() => sendOtpCode({ isSignUp: true })} loading={isVerifying} />; 
}
```

--------------------------------

### useAuthWithSSO

Source: https://github.com/ronasit/clerk-react-native-hooks/blob/main/README.md

Hook for Single Sign-On (SSO) flows, allowing users to authenticate using third-party identity providers.

```APIDOC
## useAuthWithSSO

### Description
Hook for [SSO](https://clerk.com/docs/references/expo/use-sso) flows.

### Methods
- `startSSOFlow` — Accepts `strategy`, `redirectUrl`, and an optional `tokenTemplate`.
- `isLoading` — Boolean indicating if the SSO flow is in progress.

### Example

```ts
import * as AuthSession from 'expo-auth-session';

const { startSSOFlow, isLoading } = useAuthWithSSO();

const onGooglePress = async () => {
  const { isSuccess, error } = await startSSOFlow({
    strategy: 'oauth_google',
    redirectUrl: AuthSession.makeRedirectUri({ path: navigationConfig.auth.signUp }),
    tokenTemplate: 'your_jwt_template', // optional
  });

  if (isSuccess) {
    // handle success
  }

  if (error) {
    showToast(error?.longMessage);
  }
};
```

### Notes
Use another [OAuthStrategy](https://clerk.com/docs/references/javascript/types/oauth#oauth-provider-strategy-values) (e.g., `oauth_github`) similarly.
```

--------------------------------

### useOtpVerification

Source: https://github.com/ronasit/clerk-react-native-hooks/blob/main/README.md

Handles OTP verification for email or phone channels, including sending and verifying codes.

```APIDOC
## useOtpVerification

### Description
Handles OTP verification for email or phone channels.

### Parameters
- `channel` — `'email_code'` or `'phone_code'`

### Returns
- `verifyCode` — Function to verify the OTP code. Takes `code`, optional `isSignUp` (boolean, set to `true` for sign-up), and optional `tokenTemplate`.
- `sendOtpCode` — Function to resend the OTP code. Takes optional `isSignUp` (boolean, set to `true` for sign-up).

### Examples

```ts
// useOtpVerification — same channel as email/phone: pass 'email_code' or 'phone_code' once; sendOtpCode = resend
const { verifyCode, sendOtpCode } = useOtpVerification('email_code'); // SMS: useOtpVerification('phone_code')
await sendOtpCode({ isSignUp: true });
await verifyCode({ code, isSignUp: true, tokenTemplate });
```

`tokenTemplate` (optional) is the **name** of a [JWT template](https://clerk.com/docs/guides/sessions/jwt-templates) from the Clerk Dashboard. When set, Clerk issues a JWT built from that template so you control which claims are included. Omit it if you only need the default session token.
```

--------------------------------

### Use Reset Password: Submit Reset Code

Source: https://github.com/ronasit/clerk-react-native-hooks/blob/main/README.md

Verifies the OTP code received for password reset. After successful verification, the user can proceed to set a new password.

```typescript
// 2 — submit code
const { verifyCode, isVerifying } = useResetPassword({ method: 'emailAddress' });

const onSubmitCode = async (code: string) => {
  const { isSuccess, error } = await verifyCode({ code });
  // if isSuccess → go to new-password step
};
```

--------------------------------

### Add Email or Phone to Signed-In User with useAddIdentifier

Source: https://context7.com/ronasit/clerk-react-native-hooks/llms.txt

Links a new email address or phone number to the currently authenticated user's account and initiates OTP verification. Call `createIdentifier` again with the same value to resend the code.

```tsx
import { useAddIdentifier } from '@ronas-it/clerk-react-native-hooks';

function AddEmailScreen() {
  const { createIdentifier, verifyCode, isCreating, isVerifying } = useAddIdentifier('email');
  // For phone: useAddIdentifier('phone')
  const [email, setEmail] = React.useState('');

  const onSave = async (newEmail: string) => {
    setEmail(newEmail);
    const { isSuccess, error } = await createIdentifier({ identifier: newEmail });
    if (isSuccess) console.log('Code sent to', newEmail);
    if (error) Alert.alert('Error', String(error));
  };

  const onVerify = async (code: string) => {
    const { isSuccess, error } = await verifyCode({ code, identifier: email });
    if (isSuccess) console.log('Email verified and added');
    if (error) Alert.alert('Invalid code', String(error));
  };

  const onResend = () => createIdentifier({ identifier: email });

  return (
    <>
      <EmailInput onSubmit={onSave} loading={isCreating} />
      <OtpInput onSubmit={onVerify} onResend={onResend} loading={isVerifying} />
    </>
  );
}
```

--------------------------------

### Implement Second Factor Authentication Flow

Source: https://context7.com/ronasit/clerk-react-native-hooks/llms.txt

Handle scenarios where Clerk requires a second factor after password sign-in. This involves using `useAuthWithIdentifier` to initiate sign-in, detecting the `needs_second_factor` status, and then using `useOtpVerification` to send and verify OTP codes.

```tsx
import { useAuthWithIdentifier, useOtpVerification } from '@ronas-it/clerk-react-native-hooks';

function SecureSignInScreen() {
  const { startSignIn, isLoading } = useAuthWithIdentifier('emailAddress', 'password');
  const { sendOtpCode, verifyCode, isVerifying } = useOtpVerification('email_code');
  const [needsMfa, setNeedsMfa] = React.useState(false);

  const onSignIn = async (email: string, password: string) => {
    const result = await startSignIn({ identifier: email, password, tokenTemplate: 'my_jwt_template' });

    if (result.isSuccess) {
      console.log('Signed in:', result.sessionToken);
    } else if (result.status === 'needs_second_factor') {
      await sendOtpCode({ isSecondFactor: true });
      setNeedsMfa(true);
    } else {
      Alert.alert('Sign-in failed', String(result.error));
    }
  };

  const onVerifyMfa = async (code: string) => {
    const { isSuccess, sessionToken, error } = await verifyCode({
      code,
      isSecondFactor: true,
      tokenTemplate: 'my_jwt_template',
    });
    if (isSuccess) console.log('MFA verified, token:', sessionToken);
    if (error) Alert.alert('Invalid code', String(error));
  };

  return needsMfa
    ? <OtpInput onSubmit={onVerifyMfa} loading={isVerifying} />
    : <LoginForm onSubmit={onSignIn} loading={isLoading} />;
}
```

--------------------------------

### Bump Version for Release

Source: https://github.com/ronasit/clerk-react-native-hooks/blob/main/CONTRIBUTING.md

Use this npm command to update the version number in package.json and automatically create a Git commit and tag. Choose 'patch', 'minor', or 'major' based on the type of changes.

```bash
npm version {patch|minor|major}
```

--------------------------------

### Access Core Clerk Resources with useClerkResources

Source: https://context7.com/ronasit/clerk-react-native-hooks/llms.txt

Use this hook to access the raw signIn, signUp, and signOut resources from @clerk/expo. It's useful for custom authentication flows.

```tsx
import { useClerkResources } from '@ronas-it/clerk-react-native-hooks';

function SignOutButton() {
  const { signOut } = useClerkResources();

  return (
    <Button title="Sign Out" onPress={() => signOut()} />
  );
}
```

--------------------------------

### Ticket-Based Authentication with useAuthWithTicket

Source: https://github.com/ronasit/clerk-react-native-hooks/blob/main/README.md

Enables authentication using a ticket obtained from your backend. Your backend must first issue a sign-in token from Clerk. The `startAuthorization` function then uses this ticket for authentication.

```typescript
const { startAuthorization, isLoading } = useAuthWithTicket();

const signInWithBackendTicket = async () => {
  const { ticket } = await yourApi.issueClerkSignInToken(); // server calls Clerk, returns the token to the client

  const { error, isSuccess } = await startAuthorization({
    ticket,
    tokenTemplate: 'your_jwt_template', // optional
  });

  if (isSuccess) {
    // handle success
  }

  if (error) {
    showToast(error?.longMessage);
  }
};
```

--------------------------------

### useAuthWithTicket

Source: https://context7.com/ronasit/clerk-react-native-hooks/llms.txt

Authenticates a user with a one-time sign-in token issued by your backend via the Clerk Backend API. Useful for "magic link" flows or programmatic sign-ins initiated server-side.

```APIDOC
## `useAuthWithTicket` — Backend Ticket Authentication

Authenticates a user with a one-time sign-in token issued by your backend via the Clerk Backend API. Useful for "magic link" flows or programmatic sign-ins initiated server-side.

### Usage

```tsx
import { useAuthWithTicket } from '@ronas-it/clerk-react-native-hooks';

function AutoSignInScreen() {
  const { startAuthorization, isLoading } = useAuthWithTicket();

  const signInWithBackendTicket = async () => {
    // Your server calls Clerk Backend API to create a sign-in token and returns it
    const { ticket } = await yourApi.issueClerkSignInToken();

    const { isSuccess, sessionToken, error } = await startAuthorization({
      ticket,
      tokenTemplate: 'my_jwt_template', // optional
    });

    if (isSuccess) console.log('Authenticated via ticket, token:', sessionToken);
    if (error) Alert.alert('Auth Error', String(error));
  };

  React.useEffect(() => { signInWithBackendTicket(); }, []);

  return isLoading ? <ActivityIndicator /> : null;
}
```

### Parameters

`useAuthWithTicket` returns an object with the following properties:

- **startAuthorization**: A function to initiate the authentication process with a backend ticket. Accepts an object with:
  - **ticket** (string): The one-time sign-in token issued by the Clerk Backend API.
  - **tokenTemplate** (string, optional): A template for the JWT.
- **isLoading**: A boolean indicating if the authentication process is in progress.
```

--------------------------------

### Replace Primary Email or Phone with useUpdateIdentifier

Source: https://context7.com/ronasit/clerk-react-native-hooks/llms.txt

Extends `useAddIdentifier` to replace a user's **primary** email or phone. After `verifyCode` succeeds, the new identifier becomes primary and the old one is automatically removed.

```tsx
import { useUpdateIdentifier } from '@ronas-it/clerk-react-native-hooks';

function UpdateEmailScreen() {
  const { createIdentifier, verifyCode, isCreating, isVerifying, isUpdating } = useUpdateIdentifier('email');
  const [newEmail, setNewEmail] = React.useState('');

  const onSaveNewEmail = async (email: string) => {
    setNewEmail(email);
    const { isSuccess, error } = await createIdentifier({ identifier: email });
    if (isSuccess) console.log('Verification code sent to', email);
    if (error) Alert.alert('Error', String(error));
  };

  const onVerify = async (code: string) => {
    const { isSuccess, error } = await verifyCode({ code, identifier: newEmail });
    if (isSuccess) console.log('Primary email updated to', newEmail);
    if (error) Alert.alert('Invalid code', String(error));
  };

  return (
    <>
      <EmailInput onSubmit={onSaveNewEmail} loading={isCreating} />
      <OtpInput onSubmit={onVerify} onResend={() => createIdentifier({ identifier: newEmail })} loading={isVerifying || isUpdating} />
    </>
  );
}
```

--------------------------------

### Use Reset Password: Request Reset Code

Source: https://github.com/ronasit/clerk-react-native-hooks/blob/main/README.md

Initiates the password reset process by sending a code to the provided identifier (email or phone). Call `startResetPassword` again with the same identifier to resend the code.

```typescript
// 1 — request code
const { startResetPassword, isCodeSending } = useResetPassword({ method: 'emailAddress' });

const onRequestCode = async (email: string) => {
  const { isSuccess, error } = await startResetPassword({ identifier: email });
  // if isSuccess → go to code step; keep `email` for resend
};
```

--------------------------------

### Forgot Password Flow with useResetPassword

Source: https://context7.com/ronasit/clerk-react-native-hooks/llms.txt

Three-step password reset via email or phone OTP: send reset code → verify code → submit new password. Call `startResetPassword` again with the same identifier to resend.

```tsx
import { useResetPassword } from '@ronas-it/clerk-react-native-hooks';

function ForgotPasswordFlow() {
  const { startResetPassword, verifyCode, resetPassword, isCodeSending, isVerifying, isResetting } = 
    useResetPassword({ method: 'emailAddress' });
  // For SMS: useResetPassword({ method: 'phoneNumber' })

  // Step 1 — request code
  const onRequestReset = async (email: string) => {
    const { isSuccess, error } = await startResetPassword({ identifier: email });
    if (isSuccess) console.log('Reset code sent');
    if (error) Alert.alert('Error', String(error));
  };

  // Step 2 — verify code
  const onVerifyCode = async (code: string) => {
    const { isSuccess, error } = await verifyCode({ code });
    if (isSuccess) console.log('Code verified, proceed to new password');
    if (error) Alert.alert('Invalid code', String(error));
  };

  // Step 3 — set new password
  const onSetPassword = async (password: string) => {
    const { isSuccess, sessionToken, error } = await resetPassword({
      password,
      tokenTemplate: 'my_jwt_template',
    });
    if (isSuccess) console.log('Password reset, session token:', sessionToken);
    if (error) Alert.alert('Error', String(error));
  };
}
```

--------------------------------

### useAuthWithTicket

Source: https://github.com/ronasit/clerk-react-native-hooks/blob/main/README.md

Enables ticket-based authentication where a backend service issues a sign-in token to the app.

```APIDOC
## useAuthWithTicket

### Description
Ticket-based auth: your **backend** obtains a sign-in token from Clerk ([Backend API / SDK](https://clerk.com/docs/reference/backend/sign-in-tokens/create-sign-in-token)) and returns it to the app.

### Methods
- `startAuthorization` — Accepts `ticket` and an optional `tokenTemplate`.
- `isLoading` — Boolean indicating if the authorization process is in progress.

### Example

```ts
const { startAuthorization, isLoading } = useAuthWithTicket();

const signInWithBackendTicket = async () => {
  const { ticket } = await yourApi.issueClerkSignInToken(); // server calls Clerk, returns the token to the client

  const { error, isSuccess } = await startAuthorization({
    ticket,
    tokenTemplate: 'your_jwt_template', // optional
  });

  if (isSuccess) {
    // handle success
  }

  if (error) {
    showToast(error?.longMessage);
  }
};
```
```

--------------------------------

### Use Auth With SSO Hook

Source: https://context7.com/ronasit/clerk-react-native-hooks/llms.txt

Initiates an OAuth SSO flow (Google, GitHub, Apple, etc.) using `expo-auth-session`. Returns a `sessionToken` on success. Ensure `redirectUrl` is correctly configured in your Clerk application.

```tsx
import * as AuthSession from 'expo-auth-session';
import { useAuthWithSSO } from '@ronas-it/clerk-react-native-hooks';

function SocialAuthButtons() {
  const { startSSOFlow, isLoading } = useAuthWithSSO();

  const signInWith = async (provider: 'oauth_google' | 'oauth_github' | 'oauth_apple') => {
    const { isSuccess, sessionToken, error } = await startSSOFlow({
      strategy: provider,
      redirectUrl: AuthSession.makeRedirectUri({ path: '/auth/callback' }),
      tokenTemplate: 'my_jwt_template', // optional
    });

    if (isSuccess) console.log('SSO token:', sessionToken);
    if (error) Alert.alert('SSO Error', String(error));
  };

  return (
    <View>
      <Button title="Continue with Google" onPress={() => signInWith('oauth_google')} disabled={isLoading} />
      <Button title="Continue with GitHub" onPress={() => signInWith('oauth_github')} disabled={isLoading} />
      <Button title="Continue with Apple"  onPress={() => signInWith('oauth_apple')}  disabled={isLoading} />
    </View>
  );
}
```

--------------------------------

### Use OTP Verification Hook

Source: https://context7.com/ronasit/clerk-react-native-hooks/llms.txt

Manages sending and verifying OTP codes for email or phone. Supports sign-up, sign-in, and second-factor authentication. Use `useOtpVerification('email_code')` for email or `useOtpVerification('phone_code')` for SMS.

```tsx
import { useOtpVerification } from '@ronas-it/clerk-react-native-hooks';

function OtpScreen({ isSignUp }: { isSignUp: boolean }) {
  const { sendOtpCode, verifyCode, isVerifying } = useOtpVerification('email_code');
  // For SMS use: useOtpVerification('phone_code')

  React.useEffect(() => {
    // Send code on mount
    sendOtpCode({ isSignUp });
  }, []);

  const onSubmit = async (code: string) => {
    const { isSuccess, sessionToken, error } = await verifyCode({
      code,
      isSignUp,
      tokenTemplate: 'my_jwt_template',
    });
    if (isSuccess) console.log('Authenticated, token:', sessionToken);
    if (error) Alert.alert('Invalid code', String(error));
  };

  return (
    <View>
      <OtpInput onSubmit={onSubmit} loading={isVerifying} />
      <Button title="Resend" onPress={() => sendOtpCode({ isSignUp })} />
    </View>
  );
}

// --- Second-factor (Client Trust) ---
async function handleSecondFactor() {
  const { sendOtpCode, verifyCode } = useOtpVerification('email_code');
  await sendOtpCode({ isSecondFactor: true });
  const { isSuccess } = await verifyCode({ code: '123456', isSecondFactor: true });
}
```

--------------------------------

### useGetSessionToken

Source: https://context7.com/ronasit/clerk-react-native-hooks/llms.txt

Retrieves the current session token on demand. It can optionally use a JWT template and falls back to `lastActiveToken` if `getToken` returns null.

```APIDOC
## `useGetSessionToken` — Read Session Token on Demand

Retrieves the current session token (with optional JWT template) outside of an auth flow. Falls back to `lastActiveToken` if `getToken` returns null.

```tsx
import { useGetSessionToken } from '@ronas-it/clerk-react-native-hooks';

function ApiCallExample() {
  const { getSessionToken } = useGetSessionToken();

  const fetchProtectedData = async () => {
    const { isSuccess, sessionToken, error } = await getSessionToken({
      tokenTemplate: 'my_jwt_template', // optional
    });

    if (!isSuccess || !sessionToken) {
      console.error('Could not get session token:', error);
      return;
    }

    const response = await fetch('https://api.example.com/protected', {
      headers: { Authorization: `Bearer ${sessionToken}` },
    });
    return response.json();
  };

  return <Button title="Fetch Data" onPress={fetchProtectedData} />;
}
```
```

--------------------------------

### Use Update Identifier: Verify New Email

Source: https://github.com/ronasit/clerk-react-native-hooks/blob/main/README.md

Step 2 for updating a user's email. Call `verifyCode` with the received code and the new email to complete the update. The new email becomes primary upon success.

```typescript
// Step 2 — same `identifier` as in createIdentifier
const { verifyCode, isVerifying, isUpdating } = useUpdateIdentifier('email');

const onSubmitCode = async (code: string, newEmail: string) => {
  const { isSuccess, error } = await verifyCode({ code, identifier: newEmail.trim() });

  if (isSuccess) {
    // handle success
  }
};
```

--------------------------------

### Add Email Identifier with useAddIdentifier

Source: https://github.com/ronasit/clerk-react-native-hooks/blob/main/README.md

Links an additional email address to a signed-in user. `createIdentifier` sends a verification code, and `verifyCode` confirms it. To resend the code, call `createIdentifier` again with the same identifier.

```typescript
// Step 1 — register identifier and trigger email code / SMS
const { createIdentifier, isCreating } = useAddIdentifier('email');

const onSaveEmail = async (email: string) => {
  const { isSuccess, error } = await createIdentifier({ identifier: email });

  if (isSuccess) {
    // go to verification; keep `email` for step 2
  }
};
```

```typescript
// Step 2 — same `identifier` as in createIdentifier
const { verifyCode, isVerifying } = useAddIdentifier('email');

const onSubmitCode = async (code: string, email: string) => {
  const { isSuccess, error } = await verifyCode({ code, identifier: email });

  if (isSuccess) {
    // handle success
  }
};
```

```typescript
// Resend — same as the first send: createIdentifier({ identifier }) again
const { createIdentifier, isCreating } = useAddIdentifier('email');

const onResendCode = async (email: string) => {
  await createIdentifier({ identifier: email });
};
```