SuperTokens SDK for vanilla JS for all recipes
This is a plain Javascript SDK that provides the login functionality with SuperTokens.
Learn more at https://supertokens.com
To see documentation, please click here.
Please refer to the CONTRIBUTING.md file in this repo.
For any queries, or support requests, please email us at team@supertokens.com, or join our Discord server.
Created with :heart: by the folks at SuperTokens.com.
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning
supertokensWebauthn recipe to support logins using WebAuthN (Passkeys)shouldTryLinkingToSessionUser flag to sign in/up related function inputs:false (or leave as undefined) during first factor sign-instrue for secondary factors.EmailPassword.signIn, EmailPassword.signUp: both override and callable functionsThirdParty.getAuthorisationURLWithQueryParamsAndSetState: both override and callable functionPasswordless:consumeCode, resendCode, createCode, setLoginAttemptInfo, getLoginAttemptInfocreateCode and setLoginAttemptInfo take this flag as an optional input (it defaults to false)getTenantId to default to the tenantId query parameter (if present) then falling back to the public tenant instead of always defaulting to the public tenantconsumeCode function in the Passwordless Recipe (see in the Migration guide section below for more information)You can re-enable linking by overriding the consumeCode function in the passwordless recipe and setting shouldTryLinkingToSessionUser to true.
Passwordless.init({
override: {
functions: (original) => {
return {
...original,
consumeCode: async (input) => {
// Please note that this is means that the session is required and will cause an error if it is not present
return original.consumeCode({ ...input, shouldTryLinkingWithSessionUser: true });
},
};
},
},
});maxAgeInSeconds value (previously 300 seconds) in EmailVerification Claim. If the claim value is true and maxAgeInSeconds is not provided, it will not be refreshed.createCode, resendCode and consumeCode from the exports of recipe/passwordless/utilsSESSION_ALREADY_EXISTS event to the session recipe. This is used by our pre-built UI.If you were using ThirdPartyEmailPassword, you should now init ThirdParty and EmailPassword recipes separately. The config for the individual recipes are mostly the same, except the syntax may be different. Check our recipe guides for ThirdParty and EmailPassword for more information.
If you were using ThirdPartyPasswordless, you should now init ThirdParty and Passwordless recipes separately. The config for the individual recipes are mostly the same, except the syntax may be different. Check our recipe guides for ThirdParty and Passwordless for more information.
The shouldDoInterceptionBasedOnUrl function now returns true:
refetchTimeOnFalseInSeconds and maxAgeInSecondsWith this release, we are introducing MultiFactorAuthentication and TOTP, this will let you:
Check our guide for more information.
MultiFactorAuth and TOTP recipes. To start using them you'll need compatible versions:firstFactors into the return type of getLoginMethods and removed the enabled flags of different login methods.validatorId in claim validation errors to id to match the backend SDKsIf you used to use the enabled flags in getLoginMethods:
Before:
async function checkLoginMethods() {
const loginMethods = await Multitenancy.getLoginMethods();
if (loginMethods.thirdParty.enabled) {
// custom logic
}
if (loginMethods.emailPassword.enabled) {
// custom logic
}
if (loginMethods.passwordless.enabled) {
// custom logic
}
}After:
async function checkLoginMethods() {
const loginMethods = await Multitenancy.getLoginMethods();
if (loginMethods.firstFactors.includes("thirdparty")) {
// custom logic
}
if (loginMethods.firstFactors.includes("emailpassword")) {
// custom logic
}
if (
loginMethods.firstFactors.includes("otp-email") ||
loginMethods.firstFactors.includes("otp-phone") ||
loginMethods.firstFactors.includes("link-email") ||
loginMethods.firstFactors.includes("link-phone")
) {
// custom logic
}
}If you used to use the validatorId prop of validationErrors, you should now use id instead.
Before:
async function checkValidators() {
const validationErrors = await Session.validateClaims();
for (const error of validationErrors) {
console.log(error.validatorId, error.reason);
}
}After:
async function checkValidators() {
const validationErrors = await Session.validateClaims();
for (const error of validationErrors) {
console.log(error.id, error.reason);
}
}dateprovider.js bundle file to enable importing DateProvider via a script tagDateProvider implementation relies on localStorage. If your environment lacks support for localStorage, you must provide custom implementations for either the DateProvider or localStorage.EmailVerificationClaim now uses DateProvider to account for clock skew.DateProvider from supertokens-website, that both built-in and custom validators can use instead of Date.now to get an estimate of the server clock.dateProvider prop to the configuration that can be used to customize the built-in DateProvider.calculateClockSkewInMillis as an overrideable function to the Session recipe that estimates the time difference between the backend and the client.With this release, we are introducing AccountLinking, this will let you:
Check our guide for more information.
To use this you'll need compatible versions:
createdNewUser has been renamed to createdNewRecipeUsercreateCode, consumeCode, createPasswordlessCode and consumePasswordlessCode can now return status: SIGN_IN_UP_NOT_ALLOWEDsignInAndUp and thirdPartySignInAndUp can now return new status: SIGN_IN_UP_NOT_ALLOWEDsendPasswordResetEmail can now return status: "PASSWORD_RESET_NOT_ALLOWED"signIn and emailPasswordSignIn can now return SIGN_IN_NOT_ALLOWEDsignUp and emailPasswordSignUp can now return SIGN_UP_NOT_ALLOWEDWe've added a generic User type instead of the old recipe specific ones. The mapping of old props to new in case you are not using account-linking:
user.id stays user.iduser.email becomes user.emails[0]user.phoneNumber becomes user.phoneNumbers[0]user.thirdParty becomes user.thirdParty[0]user.timeJoined is still user.timeJoineduser.tenantIds is still user.tenantIds // Here res refers to the result the function/api functions mentioned above.
const isNewUser = res.createdNewRecipeUser && res.user.loginMethods.length === 1; const isNewUser = res.user.loginMethods.length === 1;clientType usage in thirdpartypasswordlessclientType usage in thirdpartyemailpassword and thirdpartypasswordlessisEmailVerified and sendVerificationEmail requestsgetTenantIdFromURL to multiple recipesclientType config in the input for SuperTokens.init function, that is used by thirdparty and multitenancy recipes.getAuthorisationURLWithQueryParamsAndSetStatesetStateAndOtherInfoToStorage, getAuthorisationURLFromBackend, generateStateToSendToOAuthProvider, verifyAndGetStateOrThrowError, getAuthCodeFromURL, getAuthErrorFromURL, getAuthStateFromURLgetAuthorisationURLWithQueryParamsAndSetStatesetStateAndOtherInfoToStorage, getAuthorisationURLFromBackend, generateStateToSendToOAuthProvider, verifyAndGetStateOrThrowError, getAuthCodeFromURL, getAuthErrorFromURL, getAuthStateFromURLgetThirdPartyAuthorisationURLWithQueryParamsAndSetStatesetThirdPartyStateAndOtherInfoToStorage, getAuthorisationURLFromBackend, generateThirdPartyStateToSendToOAuthProvider, verifyAndGetThirdPartyStateOrThrowError, getThirdPartyAuthCodeFromURL, getThirdPartyAuthErrorFromURL, getThirdPartyAuthStateFromURLgetAuthorisationURLWithQueryParamsAndSetStateBefore:
const authUrl = await ThirdPartyEmailPassword.getAuthorisationURLWithQueryParamsAndSetState({
providerId: "google",
authorisationURL: `${websiteDomain}/auth/callback/google`,
});After:
const authUrl = await ThirdPartyEmailPassword.getAuthorisationURLWithQueryParamsAndSetState({
thirdPartyId: "google",
frontendRedirectURI: `${websiteDomain}/auth/callback/google`,
});Before:
const authUrl = await ThirdPartyEmailPassword.getAuthorisationURLWithQueryParamsAndSetState({
providerId: "apple",
authorisationURL: `${websiteDomain}/auth/callback/apple`,
});After:
const authUrl = await ThirdPartyEmailPassword.getAuthorisationURLWithQueryParamsAndSetState({
thirdPartyId: "apple",
frontendRedirectURI: `${websiteDomain}/auth/callback/apple`,
redirectURIOnProviderDashboard: `${apiDomain}/auth/callback/apple`
});supertokens-website dependency that requires a backend SDK update to:sessionScope renamed to sessionTokenFrontendDomaincookieDomain renamed to sessionTokenBackendDomainAuthorization header instead of cookiestokenTransferMethod config optioncookieHandler, windowHandler and sessionClaimValidatorStore from supertokens-website.getWindowUnsafe to the WindowHandlerInterface. This function should return the raw window object.addAxiosInterceptors as deprecatedsuperTokensDoNotDoInterception to the hash of the request (works as a queryparam as well)maxAgeInSeconds param of validators to check expiration)Passwordless.consumeCodevalidateClaims & getClaimValue functionsgetInvalidClaimsFromResponse to the SessionClass to help parsing responses with invalid claim errorsAPI_INVALID_CLAIM event to the Session recipeUserRoleClaim and PermissionClaimEmailVerification.init like other recipes.verifyEmail, sendVerificationEmail and isEmailVerified from auth recipes. These should now be called on the EmailVerification recipeEmailVerification recipe. You should configure them while initializing the EmailVerification recipe.consumeCode in the passwordless recipeSuperTokens.init({
// Normal init conf...
recipeList: [
EmailPassword.init({
preAPIHook: (context) => {
// Move email verification related pre-API hooks into the preAPIHook of the EmailVerification config
},
postAPIHook: (context) => {
// Move email verification related post-API hooks into the postAPIHook of the EmailVerification config
}
override: {
emailVerificationFeature: {
// These overrides should be moved into the config of the EmailVerification recipe
}
}
}),
]
})Should become:
SuperTokens.init({
// Normal init conf...
recipeList: [
EmailVerification.init({
// Props from emailVerificationFeature of the EmailPassword.init config should be moved here.
override: {
// The overrides from emailVerificationFeature in the overrides of the EmailPassword config should be moved here
},
preAPIHook: (context) => {
// Move email verification related pre-API hooks here
},
postAPIHook: (context) => {
// Move email verification related post-API hooks here
},
}),
EmailPassword.init({}),
],
});consumePasswordlessCode in ThirdPartyPasswordless optional.Passwordless.consumeCode was not honoring the API specsetCookieSync and getCookieSync from the interface for cookieHandler when calling SuperTokens.init