EmailPassword Recipe: Email verification

[kant01ne]

EmailPassword Recipe: Email verification

Sub issue of https://github.com/supertokens/supertokens-core/issues/124

isEmailVerified

• type isEmailVerified = () => Promise<boolean>

• import { isEmailVerified } from "supertokens-auth-react/recipe/emailpassword"

• isEmailVerified will use an API for now. Later on, we can make it use sessions instead (as a caching layer). Page loading time problem (in required mode) is solved by setting the default to email being verified and then querying to check if it has been. This makes sense since most of the time, in required mode, the is verified will be true.

• If the user visits the {websiteBasePath}/verify-email?rid=emailpassword and the email is already verified, then they will be redirected to the success callback.

Configs

SuperTokens.init({
  recipes: [
     EmailPassword.init({
            emailVerificationFeature: {
                mode: "OFF" | "REQUIRED" | "OPTIONAL",
                disableDefaultImplementation: boolean,
                sendVerifyEmailScreen: {
                  style: {...}   
                },
                sendVerifyEmailBanner: {
                   style: {...}   
                },
                verifyEmailLinkClickedScreen: {
                   style: {...}  
                }
           }
        }
     })
  ]

Default URLs

For required mode email verify UI: {websiteBasePath}/verify-email?rid=emailpassword For email clicked UI: {websiteBasePath}/verify-email?rid=emailpassword&token=TOKEN

Email verification (Required mode)

• User is logged in after sign up
• If email verification mode is "required" and email is not verified, show the "email verification screen" (Can resend the email from there)

Auth Component

import {EmailPasswordAuth} from "supertokens-auth-react/recipe/emailpassword";

<EmailPasswordAuth
  onCallIsEmailVerifiedAPI?: (headers: HeadersInit) => Promise<IsEmailVerifiedAPIResponse>
  doesSessionExist?: () => Promise<boolean>
  onHandleShowEmailVerificationScreen?: () => Promise<boolean> // if true, we do nothing, if false, we do default redirection.
>
  <LoggedInComponents />
</EmailPasswordAuth>

• onCallEmailVerifiedAPI: By default, use new FDI specs
• doesSessionExist: By default, use session recipe
• onHandleShowEmailVerificationScreen:
• Logic:
  • 1/ Use Session doesSessionExist 1.1/ No => redirect to {websiteBasePath} 1.2/ Yes, continue
  • 2/ Use isEmailVerified 2.1/ No => redirect to {websiteBasePath}/verify-email?rid=emailpassword 2.2/ Yes, continue to onSuccessRedirectUrl

EmailVerificationScreen

• {websiteBasePath}/verify-email?rid=emailpassword => Automatically added by EmailPassword feature
• {websiteBasePath}/verify-email?rid=emailpassword&token=TOKEN => Make a call to corresponding API to verify email.
• Allow to resend verification email

import EmailVerification from "supertokens-auth-react/recipe/emailpassword";

<EmailVerification
  doesSessionExist?: () => Promise<boolean>
  onCallVerifyEmailAPI?: (requestJson: RequestJson, headers: HeadersInit) => Promise<VerifyEmailAPIResponse>
  onCallSendVerifyEmailAPI?: (headers: HeadersInit) => Promise<SendVeriyEmailAPIResponse>
  signOut?: () => Promise<SignOutAPIResponse>
  onHandleSuccess?: (context: {
        action: "VERIFY_EMAIL_SENT" | "EMAIL_VERIFIED_SUCCESSFUL"
    }): Promise<boolean>;
>

• onCallVerifyEmailAPI: By default, use new FDI specs.
• onCallSendVerifyEmailAPI By default use new FDI Specs.
• signOut: By default, use signOut method from EmailPassword recipe.

EmailVerification Themes

import {EmailVerification, EmailVerificationScreenTheme} from "supertokens-auth-react/recipe/emailpassword";

<EmailVerification>
  <EmailVerificationScreenTheme/>
</EmailVerification>

// OR 
import {EmailVerification} from "supertokens-auth-react/recipe/emailpassword";
import {EmailVerificationScreenThemeCustomTheme} from "customTheme";

<EmailVerification>
  <EmailVerificationScreenThemeCustomTheme/>
</EmailVerification>

// With
type EmailVerificationScreenThemeProps = {
    sendVerifyEmailScreen: {
           callAPI: () => Promise<SendVerifyEmailThemeResponse>;
           styleFromInit?: Styles;
    }

    verifyEmailLinkClickedScreen: {
               styleFromInit: Styles;
               callAPI: () => Promise<VerifyEmailThemeResponse>;
               redirectToVerifyEmailScreen: Promise<void>
               onSuccess: () => Promise<void>;
               onContinueClicked: () => Promise<void>
    }

}

[kant01ne]

TODO Email verified banner (Optional mode)

• import { EmailVerification, EmailVerificationBannerTheme } from "supertokens-auth-react/recipe/emailpassword"

   <EmailVerification>
       <EmailVerificationBannerTheme />
   <EmailVerification>

We can update the banner (update its color and text) to "We have sent you an email" if successful. Hence, making it harder to send it multiple times (would need a page refresh) which I think is fine.

---

TODO Later

• [ ] In the optional method, what is the behaviour of that?
  • [ ] What happens when the send email button is clicked?
  • [ ] How will the banner know when to disappear once the email has been verified? Does the user have to refresh the page?
  • [ ] Design

[kant01ne]

Email Verification Required Mode Release

• [x] Upgrade to supertokens-node version with email verification features
• [x] Implement tests for email verification
• [x] Update Changelog
• [x] Prepare Docs with new designs screenshots https://github.com/supertokens/main-website/pull/190
• [x] Update "Quick Start" guide adding EmailPasswordAuth component https://github.com/supertokens/main-website/pull/190
• [x] Create "Common Customisation > Email Verification" docs. https://github.com/supertokens/main-website/pull/190
  • [x] About (Explain "OFF" | "REQUIRED" modes)
  • [x] Embed in a page
• [x] Create auth-react v0.4 docs with emailVerificationFeature configs.
• [x] Push docs to test site
• [x] Add Dev Tag
• [x] Test everything in supertokens-react-themes
• [x] Prepare any supertokens-react-themes changes and prepare upgrade to 0.4.0
• [ ] Release to npm
• [ ] Bump lib in demo app https://github.com/supertokens/supertokens-demo-react/pull/2
• [ ] Bump lib in nextjs demo app
• [ ] Bump lib in supertokens-react-themes

• [ ] Release all new docs to production site

  This comment will be ignored in favour of https://github.com/supertokens/supertokens-core/issues/157

[kant01ne]

As raised in #110, we need a way to know the login URL in EmailPasswordAuth in case it gets overwritten, and would need yet another props for this. Not going to fix now with a new props as we are discussing https://github.com/supertokens/supertokens-auth-react/issues/117 tmrw.