From 0a5b33538f5a26547ece2c2e008a299fb06d9dbf Mon Sep 17 00:00:00 2001
From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com>
Date: Thu, 30 Jan 2025 16:35:07 -0500
Subject: [PATCH] docs review

---
 .../expo/deprecated-oauth-custom-flow.mdx     | 58 ------------------
 .../expo/enterprise-sso-custom-flow.mdx       | 28 ++++++---
 docs/_partials/expo/oauth-custom-flow.mdx     | 11 ++--
 docs/custom-flows/enterprise-connections.mdx  | 36 ++++++-----
 docs/custom-flows/oauth-connections.mdx       | 40 +++++-------
 docs/references/expo/overview.mdx             | 17 +++---
 docs/references/expo/use-oauth.mdx            | 61 ++++++++++++++++++-
 docs/references/expo/use-sso.mdx              | 55 ++++++++++++++++-
 docs/references/expo/web-support/overview.mdx |  9 +--
 9 files changed, 186 insertions(+), 129 deletions(-)
 delete mode 100644 docs/_partials/expo/deprecated-oauth-custom-flow.mdx

diff --git a/docs/_partials/expo/deprecated-oauth-custom-flow.mdx b/docs/_partials/expo/deprecated-oauth-custom-flow.mdx
deleted file mode 100644
index 81f09bee6c..0000000000
--- a/docs/_partials/expo/deprecated-oauth-custom-flow.mdx
+++ /dev/null
@@ -1,58 +0,0 @@
-The following example demonstrates how to create a custom OAuth sign-in flow for [Google accounts](/docs/authentication/social-connections/google).
-
-```tsx {{ filename: 'app/(auth)/sign-in.tsx', collapsible: true }}
-import React from 'react'
-import * as WebBrowser from 'expo-web-browser'
-import { Text, View, Button } from 'react-native'
-import { Link } from 'expo-router'
-import { useOAuth } from '@clerk/clerk-expo'
-import * as Linking from 'expo-linking'
-
-export const useWarmUpBrowser = () => {
-  React.useEffect(() => {
-    // Warm up the android browser to improve UX
-    // https://docs.expo.dev/guides/authentication/#improving-user-experience
-    void WebBrowser.warmUpAsync()
-    return () => {
-      void WebBrowser.coolDownAsync()
-    }
-  }, [])
-}
-
-WebBrowser.maybeCompleteAuthSession()
-
-export default function Page() {
-  useWarmUpBrowser()
-
-  const { startOAuthFlow } = useOAuth({ strategy: 'oauth_google' })
-
-  const onPress = React.useCallback(async () => {
-    try {
-      const { createdSessionId, signIn, signUp, setActive } = await startOAuthFlow({
-        redirectUrl: Linking.createURL('/dashboard', { scheme: 'myapp' }),
-      })
-
-      // If sign in was successful, set the active session
-      if (createdSessionId) {
-        setActive!({ session: createdSessionId })
-      } else {
-        // Use signIn or signUp returned from startOAuthFlow
-        // for next steps, such as MFA
-      }
-    } catch (err) {
-      // See https://clerk.com/docs/custom-flows/error-handling
-      // for more info on error handling
-      console.error(JSON.stringify(err, null, 2))
-    }
-  }, [])
-
-  return (
-    <View>
-      <Link href="/">
-        <Text>Home</Text>
-      </Link>
-      <Button title="Sign in with Google" onPress={onPress} />
-    </View>
-  )
-}
-```
diff --git a/docs/_partials/expo/enterprise-sso-custom-flow.mdx b/docs/_partials/expo/enterprise-sso-custom-flow.mdx
index 09d03253fb..4d62505224 100644
--- a/docs/_partials/expo/enterprise-sso-custom-flow.mdx
+++ b/docs/_partials/expo/enterprise-sso-custom-flow.mdx
@@ -1,11 +1,12 @@
-The following example demonstrates how to create a custom SSO flow with [SAML](docs/authentication/enterprise-connections/overview#saml).
+Expo supports SAML Enterprise SSO, but does not support EASIE or OIDC.
+
+The following example demonstrates how to create a custom SSO flow with [SAML](docs/authentication/enterprise-connections/overview#saml). In the following example, when the user selects the "Sign in with SAML" button, they will be redirected to the provider's authentication page. Once they authenticate, they will be redirected back to your app. If there are missing requirements, like they need to complete MFA, then the `createdSessionId` will remain `null`, and you'll need to add logic to handle the missing requirements. If there are no missing requirements, then the user will be signed in.
 
 ```tsx {{ filename: 'app/(auth)/sign-in.tsx', collapsible: true }}
-import React, { useCallback, useEffect } from 'react'
+import React, { useCallback, useEffect, useState } from 'react'
 import * as WebBrowser from 'expo-web-browser'
-import * as Linking from 'expo-linking'
 import { useSSO } from '@clerk/clerk-expo'
-import { View, Button } from 'react-native'
+import { View, Button, TextInput } from 'react-native'
 
 export const useWarmUpBrowser = () => {
   useEffect(() => {
@@ -25,22 +26,25 @@ WebBrowser.maybeCompleteAuthSession()
 export default function Page() {
   useWarmUpBrowser()
 
+  const [email, setEmail] = useState('')
+
   const { startSSOFlow } = useSSO()
 
   const onPress = useCallback(async () => {
     try {
       const { createdSessionId, setActive, signIn, signUp } = await startSSOFlow({
         strategy: 'enterprise_sso',
-        // This identifier would likely be derived from a text input
-        identifier: 'foo@corp.com',
+        identifier: email,
       })
 
       // If sign in was successful, set the active session
       if (createdSessionId) {
         setActive!({ session: createdSessionId })
       } else {
-        // Use `signIn` or `signUp` returned from `startSSOFlow`
-        // for next steps, such as MFA
+        // If there is no `createdSessionId`,
+        // there are missing requirements, such as MFA
+        // Use the `signIn` or `signUp` returned from `startSSOFlow`
+        // to handle next steps
       }
     } catch (err) {
       // See https://clerk.com/docs/custom-flows/error-handling
@@ -51,7 +55,13 @@ export default function Page() {
 
   return (
     <View>
-      <Button title="Sign in with SSO" onPress={onPress} />
+      <TextInput
+        value={email}
+        onChangeText={setEmail}
+        placeholder="Enter email"
+        placeholderTextColor="#666666"
+      />
+      <Button title="Sign in with SAML" onPress={onPress} />
     </View>
   )
 }
diff --git a/docs/_partials/expo/oauth-custom-flow.mdx b/docs/_partials/expo/oauth-custom-flow.mdx
index 671da6321b..9a652f467f 100644
--- a/docs/_partials/expo/oauth-custom-flow.mdx
+++ b/docs/_partials/expo/oauth-custom-flow.mdx
@@ -1,9 +1,8 @@
-The following example demonstrates how to create a custom SSO flow for [Google OAuth](/docs/authentication/social-connections/google).
+The following example demonstrates how to create a custom SSO flow for [Google OAuth](/docs/authentication/social-connections/google). In the following example, when the user selects the "Sign in with Google" button, they will be redirected to the Google authentication page. Once they authenticate, they will be redirected back to your app. If there are missing requirements, like they need to complete MFA, then the `createdSessionId` will remain `null`, and you'll need to add logic to handle the missing requirements. If there are no missing requirements, then the user will be signed in.
 
 ```tsx {{ filename: 'app/(auth)/sign-in.tsx', collapsible: true }}
 import React, { useCallback, useEffect } from 'react'
 import * as WebBrowser from 'expo-web-browser'
-import * as Linking from 'expo-linking'
 import { useSSO } from '@clerk/clerk-expo'
 import { View, Button } from 'react-native'
 
@@ -25,10 +24,12 @@ WebBrowser.maybeCompleteAuthSession()
 export default function Page() {
   useWarmUpBrowser()
 
+  // Use the `useSSO()` hook to access the `startSSOFlow()` method
   const { startSSOFlow } = useSSO()
 
   const onPress = useCallback(async () => {
     try {
+      // Start the OAuth process by calling `startSSOFlow()`
       const { createdSessionId, setActive, signIn, signUp } = await startSSOFlow({
         strategy: 'oauth_google',
       })
@@ -37,8 +38,10 @@ export default function Page() {
       if (createdSessionId) {
         setActive!({ session: createdSessionId })
       } else {
-        // Use `signIn` or `signUp` returned from `startSSOFlow`
-        // for next steps, such as MFA
+        // If there is no `createdSessionId`,
+        // there are missing requirements, such as MFA
+        // Use the `signIn` or `signUp` returned from `startSSOFlow`
+        // to handle next steps
       }
     } catch (err) {
       // See https://clerk.com/docs/custom-flows/error-handling
diff --git a/docs/custom-flows/enterprise-connections.mdx b/docs/custom-flows/enterprise-connections.mdx
index 261e082868..7ad20b0b16 100644
--- a/docs/custom-flows/enterprise-connections.mdx
+++ b/docs/custom-flows/enterprise-connections.mdx
@@ -11,8 +11,9 @@ You must configure your application instance through the Clerk Dashboard for the
 
 ## Create the sign-up and sign-in flow
 
-When using Enterprise SSO, the sign-in and sign-up flows are equivalent. A successful Enterprise SSO flow consists of the following steps:
+When using Enterprise SSO, **the sign-up and sign-in flows are equivalent.** A successful Enterprise SSO authentication flow consists of the following steps:
 
+1. Access the [`SignIn`](/docs/references/javascript/sign-in/sign-in) or [`SignUp`](/docs/references/javascript/sign-up/sign-up) object using the [`useSignIn()`](/docs/references/react/use-sign-in) or [`useSignUp()`](/docs/references/react/use-sign-up) hook, respectively.
 1. Start the Enterprise SSO flow by calling [`SignIn.authenticateWithRedirect(params)`][sign-in-redirect] or [`SignUp.authenticateWithRedirect(params)`][sign-up-redirect]. Both of these methods require a `redirectUrl` param, which is the URL that the browser will be redirected to once the user authenticates with the identity provider.
 1. Create a route at the URL that the `redirectUrl` param points to. The following example names this route `/sso-callback`. This route should either call the [`Clerk.handleRedirectCallback()`](/docs/references/javascript/clerk/handle-navigation#handle-redirect-callback) method or render the prebuilt [`<AuthenticateWithRedirectCallback/>`](/docs/components/control/authenticate-with-callback) component.
 
@@ -21,37 +22,38 @@ The following example shows two files:
 1. The sign-in page where the user can start the Enterprise SSO flow.
 1. The SSO callback page where the flow is completed.
 
-<Tabs items={["Next.js"]}>
+<Tabs items={["Next.js", "Expo"]}>
   <Tab>
     <CodeBlockTabs options={["Sign in page", "SSO callback page"]}>
       ```tsx {{ filename: 'app/sign-in/page.tsx' }}
       'use client'
 
       import * as React from 'react'
-      import { useSignIn, useSignUp } from '@clerk/nextjs'
+      import { useSignIn } from '@clerk/nextjs'
 
       export default function Page() {
-        const { signIn } = useSignIn()
-        const { signUp } = useSignUp()
-
-        if (!signIn || !signUp) return null
+        const { signIn, isLoaded } = useSignIn()
 
-        const signInWithEnterpriseSSO = (e: React.FormEvent) => {
+        const signInWithEnterpriseSSO = async (e: React.FormEvent) => {
           e.preventDefault()
 
+          if (!isLoaded) return null
+
           const email = (e.target as HTMLFormElement).email.value
 
-          signIn
+          await signIn
             .authenticateWithRedirect({
               identifier: email,
               strategy: 'enterprise_sso',
-              redirectUrl: '/sign-up/sso-callback',
+              redirectUrl: '/sign-in/sso-callback',
               redirectUrlComplete: '/',
             })
             .then((res) => {
               console.log(res)
             })
             .catch((err: any) => {
+              // See https://clerk.com/docs/custom-flows/error-handling
+              // for more info on error handling
               console.log(err.errors)
               console.error(err, null, 2)
             })
@@ -59,14 +61,14 @@ The following example shows two files:
 
         return (
           <form onSubmit={(e) => signInWithEnterpriseSSO(e)}>
-            <input type="email" name="email" placeholder="Enter email address" />
+            <input id="email" type="email" name="email" placeholder="Enter email address" />
             <button>Sign in with Enterprise SSO</button>
           </form>
         )
       }
       ```
 
-      ```jsx {{ filename: 'app/sign-up/sso-callback/page.tsx' }}
+      ```jsx {{ filename: 'app/sign-in/sso-callback/page.tsx' }}
       import { AuthenticateWithRedirectCallback } from '@clerk/nextjs'
 
       export default function Page() {
@@ -78,10 +80,16 @@ The following example shows two files:
       ```
     </CodeBlockTabs>
   </Tab>
+
+  <Tab>
+    <Include src="_partials/expo/enterprise-sso-custom-flow" />
+  </Tab>
 </Tabs>
 
 ## Enterprise account transfer flows
 
+{/* TODO(Laura): I believe this is built in with Expo's `useSSO()` hook, so I don't think we need to add Expo example here. Is this correct? */}
+
 It is common for users who are authenticating with an enterprise account to use a sign-in button when they mean to sign-up, and vice versa. For those cases, the `SignIn` and `SignUp` objects have a `transferable` status that indicates whether the user can be transferred to the other flow.
 
 **If you would like to keep your sign-in and sign-up flows completely separate, then you can skip this section.**
@@ -90,7 +98,7 @@ The following example demonstrates how to handle these cases in your sign-in flo
 
 <Tabs items={["Next.js"]}>
   <Tab>
-    ```tsx {{ filename: 'app/sign-in/[[...sign-in]]/page.tsx', collapsible: true }}
+    ```tsx {{ filename: 'app/sign-in/page.tsx', collapsible: true }}
     'use client'
 
     import * as React from 'react'
@@ -111,7 +119,7 @@ The following example demonstrates how to handle these cases in your sign-in flo
           .authenticateWithRedirect({
             identifier: email,
             strategy: 'enterprise_sso',
-            redirectUrl: '/sign-up/sso-callback',
+            redirectUrl: '/sign-in/sso-callback',
             redirectUrlComplete: '/',
           })
           .then((res) => {
diff --git a/docs/custom-flows/oauth-connections.mdx b/docs/custom-flows/oauth-connections.mdx
index 3456fe07f6..880d9a6462 100644
--- a/docs/custom-flows/oauth-connections.mdx
+++ b/docs/custom-flows/oauth-connections.mdx
@@ -39,11 +39,21 @@ When using OAuth, the sign-up and sign-in flows are equivalent.
         if (!signIn) return null
 
         const signInWith = (strategy: OAuthStrategy) => {
-          return signIn.authenticateWithRedirect({
-            strategy,
-            redirectUrl: '/sign-up/sso-callback',
-            redirectUrlComplete: '/',
-          })
+          return signIn
+            .authenticateWithRedirect({
+              strategy,
+              redirectUrl: '/sign-up/sso-callback',
+              redirectUrlComplete: '/',
+            })
+            .then((res) => {
+              console.log(res)
+            })
+            .catch((err: any) => {
+              // See https://clerk.com/docs/custom-flows/error-handling
+              // for more info on error handling
+              console.log(err.errors)
+              console.error(err, null, 2)
+            })
         }
 
         // Render a button for each supported OAuth provider
@@ -70,26 +80,6 @@ When using OAuth, the sign-up and sign-in flows are equivalent.
   </Tab>
 
   <Tab>
-    ### Before you start
-
-    Install `expo-linking` to handle linking.
-
-    <CodeBlockTabs options={["npm", "yarn", "pnpm"]}>
-      ```bash {{ filename: 'terminal' }}
-      npm install expo-linking
-      ```
-
-      ```bash {{ filename: 'terminal' }}
-      yarn add expo-linking
-      ```
-
-      ```bash {{ filename: 'terminal' }}
-      pnpm add expo-linking
-      ```
-    </CodeBlockTabs>
-
-    ### Build the flow
-
     <Include src="_partials/expo/oauth-custom-flow" />
   </Tab>
 
diff --git a/docs/references/expo/overview.mdx b/docs/references/expo/overview.mdx
index cdf3aa3bc5..36a05e22c0 100644
--- a/docs/references/expo/overview.mdx
+++ b/docs/references/expo/overview.mdx
@@ -11,20 +11,23 @@ The Expo SDK gives you access to the following resources:
 
 ### Clerk hooks {{ id: 'hooks' }}
 
-The following hooks are available for both **native** and **web** apps:
+The Expo SDK provides the following hooks:
 
-- All React hooks are available. See [the React docs](/docs/references/react/overview){{ target: '_blank' }} for more information.
 - [`useSSO()`](/docs/references/expo/use-sso)
 - [`useLocalCredentials()`](/docs/references/expo/use-local-credentials)
 
+Because the Expo SDK is built on top of the Clerk React SDK, you can use the hooks that the React SDK provides. These hooks include access to the [`Clerk`](/docs/references/javascript/clerk/clerk) object, [`User` object](/docs/references/javascript/user/user), [`Organization` object](/docs/references/javascript/organization/organization), and a set of useful helper methods for signing in and signing up.
+
+<Include src="_partials/hooks/hook-list" />
+
 ### Clerk components {{ id: 'components' }}
 
 - **Native** apps:
-  - [`<ClerkLoaded>`](/docs/components/control/clerk-loaded){{ target: '_blank' }}
-  - [`<ClerkLoading>`](/docs/components/control/clerk-loading){{ target: '_blank' }}
-  - [`<SignedIn>`](/docs/components/control/signed-in){{ target: '_blank' }}
-  - [`<SignedOut>`](/docs/components/control/signed-out){{ target: '_blank' }}
-  - [`<Protect>`](/docs/components/protect){{ target: '_blank' }}
+  - [`<ClerkLoaded>`](/docs/components/control/clerk-loaded)
+  - [`<ClerkLoading>`](/docs/components/control/clerk-loading)
+  - [`<SignedIn>`](/docs/components/control/signed-in)
+  - [`<SignedOut>`](/docs/components/control/signed-out)
+  - [`<Protect>`](/docs/components/protect)
 - **Web** apps:
   - All Clerk components are available. See [the component docs](/docs/components/overview) for more information.
 
diff --git a/docs/references/expo/use-oauth.mdx b/docs/references/expo/use-oauth.mdx
index 9fb23a157e..b0f3650d0b 100644
--- a/docs/references/expo/use-oauth.mdx
+++ b/docs/references/expo/use-oauth.mdx
@@ -1,5 +1,5 @@
 ---
-title: useOAuth()
+title: useOAuth() (deprecated)
 description: Clerk's useOAuth() hook is used to create a new OAuth flow.
 ---
 
@@ -61,4 +61,61 @@ It accepts the following parameters (`StartOAuthFlowParams`):
 
 ## How to use the `useOAuth()` hook
 
-<Include src="_partials/expo/deprecated-oauth-custom-flow" />
+The following example demonstrates how to create a custom OAuth sign-in flow for [Google accounts](/docs/authentication/social-connections/google).
+
+```tsx {{ filename: 'app/(auth)/sign-in.tsx', collapsible: true }}
+import React from 'react'
+import * as WebBrowser from 'expo-web-browser'
+import { Text, View, Button } from 'react-native'
+import { Link } from 'expo-router'
+import { useOAuth } from '@clerk/clerk-expo'
+import * as Linking from 'expo-linking'
+
+export const useWarmUpBrowser = () => {
+  React.useEffect(() => {
+    // Warm up the android browser to improve UX
+    // https://docs.expo.dev/guides/authentication/#improving-user-experience
+    void WebBrowser.warmUpAsync()
+    return () => {
+      void WebBrowser.coolDownAsync()
+    }
+  }, [])
+}
+
+WebBrowser.maybeCompleteAuthSession()
+
+export default function Page() {
+  useWarmUpBrowser()
+
+  const { startOAuthFlow } = useOAuth({ strategy: 'oauth_google' })
+
+  const onPress = React.useCallback(async () => {
+    try {
+      const { createdSessionId, signIn, signUp, setActive } = await startOAuthFlow({
+        redirectUrl: Linking.createURL('/dashboard', { scheme: 'myapp' }),
+      })
+
+      // If sign in was successful, set the active session
+      if (createdSessionId) {
+        setActive!({ session: createdSessionId })
+      } else {
+        // Use signIn or signUp returned from startOAuthFlow
+        // for next steps, such as MFA
+      }
+    } catch (err) {
+      // See https://clerk.com/docs/custom-flows/error-handling
+      // for more info on error handling
+      console.error(JSON.stringify(err, null, 2))
+    }
+  }, [])
+
+  return (
+    <View>
+      <Link href="/">
+        <Text>Home</Text>
+      </Link>
+      <Button title="Sign in with Google" onPress={onPress} />
+    </View>
+  )
+}
+```
diff --git a/docs/references/expo/use-sso.mdx b/docs/references/expo/use-sso.mdx
index eb8978510c..ec7ef2c523 100644
--- a/docs/references/expo/use-sso.mdx
+++ b/docs/references/expo/use-sso.mdx
@@ -9,9 +9,17 @@ The `useSSO()` hook is used to create a new SSO flow. It can be used in both web
 
 The `useSSO()` hook returns the `startSSOFlow()` method, which you can use to initiate the SSO flow.
 
-It accepts the following parameters (`StartSSOFlowParams`):
+### `startSSOFlow()`
 
-## Parameters
+`startSSOFlow()` has the following function signature:
+
+```ts
+function startSSOFlow(startSSOFlowParams: StartSSOFlowParams): Promise<StartSSOFlowReturnType>
+```
+
+#### Parameters
+
+`startSSOFlow()` accepts the following parameters (`StartSSOFlowParams`):
 
 <Properties>
   - `strategy`
@@ -37,8 +45,49 @@ It accepts the following parameters (`StartSSOFlowParams`):
   Metadata that can be read and set from the frontend and the backend. Once the authentication process is complete, the value of this field will be automatically copied to the created user's unsafe metadata (`User.unsafeMetadata`). One common use case is to collect custom information about the user during the authentication process and store it in this property. Read more about [unsafe metadata](/docs/users/metadata#unsafe-metadata).
 </Properties>
 
+#### Returns
+
+`startSSOFlow()` returns the following:
+
+<Properties>
+  - `createdSessionId`
+  - `string | null`
+
+  The ID of the session that was created.
+
+  ---
+
+  - `authSessionResult?`
+  - `WebBrowser.WebBrowserAuthSessionResult | undefined`
+
+  {/* TODO(Laura): Add description */}
+
+  ---
+
+  - `setActive?`
+  - `(params: SetActiveParams) => Promise<void>`
+
+  A method used to set the active session and/or organization. Accepts a [`SetActiveParams`](/docs/references/javascript/types/set-active-params) object.
+
+  ---
+
+  - `signIn?`
+  - <code>[SignIn](/docs/references/javascript/sign-in/sign-in) | undefined</code>
+
+  The [`SignIn`](/docs/references/javascript/sign-in/sign-in) object that was created, which holds the state of the current sign-in and provides helper methods to navigate and complete the sign-in process.
+
+  ---
+
+  - `signUp?`
+  - <code>[SignUp](/docs/references/javascript/sign-up/sign-up) | undefined</code>
+
+  The [`SignUp`](/docs/references/javascript/sign-up/sign-up) object that was created, which holds the state of the current sign-up and provides helper methods to navigate and complete the sign-up process.
+</Properties>
+
 ## How to use the `useSSO()` hook
 
+{/* TODO(Laura): Isn't allowlisting your SSO callback URL only required for production apps? */}
+
 Clerk ensures that security critical nonces will be passed only to allowlisted URLs when the SSO flow is complete in native browsers or webviews.
 
 So for maximum security in your production instances, you need to allowlist your the SSO callback URL in your Clerk Dashboard by following these steps:
@@ -53,6 +102,6 @@ So for maximum security in your production instances, you need to allowlist your
 
 <Include src="_partials/expo/oauth-custom-flow" />
 
-### With SAML
+### With Enterprise SSO
 
 <Include src="_partials/expo/enterprise-sso-custom-flow" />
diff --git a/docs/references/expo/web-support/overview.mdx b/docs/references/expo/web-support/overview.mdx
index 134b50e659..0f3e3fcb6f 100644
--- a/docs/references/expo/web-support/overview.mdx
+++ b/docs/references/expo/web-support/overview.mdx
@@ -31,11 +31,6 @@ Use the following guides to learn more about Clerk components, how to build cust
 
   ---
 
-  - [Custom flows](/docs/custom-flows/overview)
-  - Expo native apps require custom flows in place of prebuilt components. Learn more about custom flows.
-
-  ---
-
-  - [Client-side helpers](/docs/references/react/use-user)
-  - Learn more about our client-side helpers and how to use them.
+  - [Client-side helpers](/docs/references/expo/overview#hooks)
+  - Learn more about Clerk's client-side helpers and how to use them.
 </Cards>