@supabase/auth-js 2.100.0-rc.0 → 2.100.1

package/dist/module/GoTrueClient.d.ts

@@ -111,6 +111,8 @@ export default class GoTrueClient {
      * Initializes the client session either from the url or from storage.
      * This method is automatically called when instantiating the client, but should also be called
      * manually when checking for an error from an auth redirect (oauth, magiclink, password recovery, etc).
+     *
+     * @category Auth
      */
     initialize(): Promise<InitializeResult>;
     /**
@@ -124,6 +126,74 @@ export default class GoTrueClient {
      * Creates a new anonymous user.
      *
      * @returns A session where the is_anonymous claim in the access token JWT set to true
+     *
+     * @category Auth
+     *
+     * @remarks
+     * - Returns an anonymous user
+     * - It is recommended to set up captcha for anonymous sign-ins to prevent abuse. You can pass in the captcha token in the `options` param.
+     *
+     * @example Create an anonymous user
+     * ```js
+     * const { data, error } = await supabase.auth.signInAnonymously({
+     *   options: {
+     *     captchaToken
+     *   }
+     * });
+     * ```
+     *
+     * @exampleResponse Create an anonymous user
+     * ```json
+     * {
+     *   "data": {
+     *     "user": {
+     *       "id": "11111111-1111-1111-1111-111111111111",
+     *       "aud": "authenticated",
+     *       "role": "authenticated",
+     *       "email": "",
+     *       "phone": "",
+     *       "last_sign_in_at": "2024-01-01T00:00:00Z",
+     *       "app_metadata": {},
+     *       "user_metadata": {},
+     *       "identities": [],
+     *       "created_at": "2024-01-01T00:00:00Z",
+     *       "updated_at": "2024-01-01T00:00:00Z",
+     *       "is_anonymous": true
+     *     },
+     *     "session": {
+     *       "access_token": "<ACCESS_TOKEN>",
+     *       "token_type": "bearer",
+     *       "expires_in": 3600,
+     *       "expires_at": 1700000000,
+     *       "refresh_token": "<REFRESH_TOKEN>",
+     *       "user": {
+     *         "id": "11111111-1111-1111-1111-111111111111",
+     *         "aud": "authenticated",
+     *         "role": "authenticated",
+     *         "email": "",
+     *         "phone": "",
+     *         "last_sign_in_at": "2024-01-01T00:00:00Z",
+     *         "app_metadata": {},
+     *         "user_metadata": {},
+     *         "identities": [],
+     *         "created_at": "2024-01-01T00:00:00Z",
+     *         "updated_at": "2024-01-01T00:00:00Z",
+     *         "is_anonymous": true
+     *       }
+     *     }
+     *   },
+     *   "error": null
+     * }
+     * ```
+     *
+     * @example Create an anonymous user with custom user metadata
+     * ```js
+     * const { data, error } = await supabase.auth.signInAnonymously({
+     *   options: {
+     *     data
+     *   }
+     * })
+     * ```
      */
     signInAnonymously(credentials?: SignInAnonymouslyCredentials): Promise<AuthResponse>;
     /**
@@ -311,90 +381,899 @@ export default class GoTrueClient {
      * between the cases where the account does not exist or that the
      * email/phone and password combination is wrong or that the account can only
      * be accessed via social login.
+     *
+     * @category Auth
+     *
+     * @remarks
+     * - Requires either an email and password or a phone number and password.
+     *
+     * @example Sign in with email and password
+     * ```js
+     * const { data, error } = await supabase.auth.signInWithPassword({
+     *   email: 'example@email.com',
+     *   password: 'example-password',
+     * })
+     * ```
+     *
+     * @exampleResponse Sign in with email and password
+     * ```json
+     * {
+     *   "data": {
+     *     "user": {
+     *       "id": "11111111-1111-1111-1111-111111111111",
+     *       "aud": "authenticated",
+     *       "role": "authenticated",
+     *       "email": "example@email.com",
+     *       "email_confirmed_at": "2024-01-01T00:00:00Z",
+     *       "phone": "",
+     *       "last_sign_in_at": "2024-01-01T00:00:00Z",
+     *       "app_metadata": {
+     *         "provider": "email",
+     *         "providers": [
+     *           "email"
+     *         ]
+     *       },
+     *       "user_metadata": {},
+     *       "identities": [
+     *         {
+     *           "identity_id": "22222222-2222-2222-2222-222222222222",
+     *           "id": "11111111-1111-1111-1111-111111111111",
+     *           "user_id": "11111111-1111-1111-1111-111111111111",
+     *           "identity_data": {
+     *             "email": "example@email.com",
+     *             "email_verified": false,
+     *             "phone_verified": false,
+     *             "sub": "11111111-1111-1111-1111-111111111111"
+     *           },
+     *           "provider": "email",
+     *           "last_sign_in_at": "2024-01-01T00:00:00Z",
+     *           "created_at": "2024-01-01T00:00:00Z",
+     *           "updated_at": "2024-01-01T00:00:00Z",
+     *           "email": "example@email.com"
+     *         }
+     *       ],
+     *       "created_at": "2024-01-01T00:00:00Z",
+     *       "updated_at": "2024-01-01T00:00:00Z"
+     *     },
+     *     "session": {
+     *       "access_token": "<ACCESS_TOKEN>",
+     *       "token_type": "bearer",
+     *       "expires_in": 3600,
+     *       "expires_at": 1700000000,
+     *       "refresh_token": "<REFRESH_TOKEN>",
+     *       "user": {
+     *         "id": "11111111-1111-1111-1111-111111111111",
+     *         "aud": "authenticated",
+     *         "role": "authenticated",
+     *         "email": "example@email.com",
+     *         "email_confirmed_at": "2024-01-01T00:00:00Z",
+     *         "phone": "",
+     *         "last_sign_in_at": "2024-01-01T00:00:00Z",
+     *         "app_metadata": {
+     *           "provider": "email",
+     *           "providers": [
+     *             "email"
+     *           ]
+     *         },
+     *         "user_metadata": {},
+     *         "identities": [
+     *           {
+     *             "identity_id": "22222222-2222-2222-2222-222222222222",
+     *             "id": "11111111-1111-1111-1111-111111111111",
+     *             "user_id": "11111111-1111-1111-1111-111111111111",
+     *             "identity_data": {
+     *               "email": "example@email.com",
+     *               "email_verified": false,
+     *               "phone_verified": false,
+     *               "sub": "11111111-1111-1111-1111-111111111111"
+     *             },
+     *             "provider": "email",
+     *             "last_sign_in_at": "2024-01-01T00:00:00Z",
+     *             "created_at": "2024-01-01T00:00:00Z",
+     *             "updated_at": "2024-01-01T00:00:00Z",
+     *             "email": "example@email.com"
+     *           }
+     *         ],
+     *         "created_at": "2024-01-01T00:00:00Z",
+     *         "updated_at": "2024-01-01T00:00:00Z"
+     *       }
+     *     }
+     *   },
+     *   "error": null
+     * }
+     * ```
+     *
+     * @example Sign in with phone and password
+     * ```js
+     * const { data, error } = await supabase.auth.signInWithPassword({
+     *   phone: '+13334445555',
+     *   password: 'some-password',
+     * })
+     * ```
      */
     signInWithPassword(credentials: SignInWithPasswordCredentials): Promise<AuthTokenResponsePassword>;
     /**
      * Log in an existing user via a third-party provider.
      * This method supports the PKCE flow.
+     *
+     * @category Auth
+     *
+     * @remarks
+     * - This method is used for signing in using [Social Login (OAuth) providers](/docs/guides/auth#configure-third-party-providers).
+     * - It works by redirecting your application to the provider's authorization screen, before bringing back the user to your app.
+     *
+     * @example Sign in using a third-party provider
+     * ```js
+     * const { data, error } = await supabase.auth.signInWithOAuth({
+     *   provider: 'github'
+     * })
+     * ```
+     *
+     * @exampleResponse Sign in using a third-party provider
+     * ```json
+     * {
+     *   data: {
+     *     provider: 'github',
+     *     url: <PROVIDER_URL_TO_REDIRECT_TO>
+     *   },
+     *   error: null
+     * }
+     * ```
+     *
+     * @exampleDescription Sign in using a third-party provider with redirect
+     * - When the OAuth provider successfully authenticates the user, they are redirected to the URL specified in the `redirectTo` parameter. This parameter defaults to the [`SITE_URL`](/docs/guides/auth/redirect-urls#use-wildcards-in-redirect-urls). It does not redirect the user immediately after invoking this method.
+     * - See [redirect URLs and wildcards](/docs/guides/auth/redirect-urls#use-wildcards-in-redirect-urls) to add additional redirect URLs to your project.
+     *
+     * @example Sign in using a third-party provider with redirect
+     * ```js
+     * const { data, error } = await supabase.auth.signInWithOAuth({
+     *   provider: 'github',
+     *   options: {
+     *     redirectTo: 'https://example.com/welcome'
+     *   }
+     * })
+     * ```
+     *
+     * @exampleDescription Sign in with scopes and access provider tokens
+     * If you need additional access from an OAuth provider, in order to access provider specific APIs in the name of the user, you can do this by passing in the scopes the user should authorize for your application. Note that the `scopes` option takes in **a space-separated list** of scopes.
+     *
+     * Because OAuth sign-in often includes redirects, you should register an `onAuthStateChange` callback immediately after you create the Supabase client. This callback will listen for the presence of `provider_token` and `provider_refresh_token` properties on the `session` object and store them in local storage. The client library will emit these values **only once** immediately after the user signs in. You can then access them by looking them up in local storage, or send them to your backend servers for further processing.
+     *
+     * Finally, make sure you remove them from local storage on the `SIGNED_OUT` event. If the OAuth provider supports token revocation, make sure you call those APIs either from the frontend or schedule them to be called on the backend.
+     *
+     * @example Sign in with scopes and access provider tokens
+     * ```js
+     * // Register this immediately after calling createClient!
+     * // Because signInWithOAuth causes a redirect, you need to fetch the
+     * // provider tokens from the callback.
+     * supabase.auth.onAuthStateChange((event, session) => {
+     *   if (session && session.provider_token) {
+     *     window.localStorage.setItem('oauth_provider_token', session.provider_token)
+     *   }
+     *
+     *   if (session && session.provider_refresh_token) {
+     *     window.localStorage.setItem('oauth_provider_refresh_token', session.provider_refresh_token)
+     *   }
+     *
+     *   if (event === 'SIGNED_OUT') {
+     *     window.localStorage.removeItem('oauth_provider_token')
+     *     window.localStorage.removeItem('oauth_provider_refresh_token')
+     *   }
+     * })
+     *
+     * // Call this on your Sign in with GitHub button to initiate OAuth
+     * // with GitHub with the requested elevated scopes.
+     * await supabase.auth.signInWithOAuth({
+     *   provider: 'github',
+     *   options: {
+     *     scopes: 'repo gist notifications'
+     *   }
+     * })
+     * ```
      */
     signInWithOAuth(credentials: SignInWithOAuthCredentials): Promise<OAuthResponse>;
     /**
      * Log in an existing user by exchanging an Auth Code issued during the PKCE flow.
-     */
-    exchangeCodeForSession(authCode: string): Promise<AuthTokenResponse>;
-    /**
-     * Signs in a user by verifying a message signed by the user's private key.
-     * Supports Ethereum (via Sign-In-With-Ethereum) & Solana (Sign-In-With-Solana) standards,
-     * both of which derive from the EIP-4361 standard
-     * With slight variation on Solana's side.
-     * @reference https://eips.ethereum.org/EIPS/eip-4361
-     */
-    signInWithWeb3(credentials: Web3Credentials): Promise<{
-        data: {
-            session: Session;
-            user: User;
-        };
-        error: null;
-    } | {
-        data: {
-            session: null;
-            user: null;
-        };
-        error: AuthError;
-    }>;
-    private signInWithEthereum;
-    private signInWithSolana;
-    private _exchangeCodeForSession;
-    /**
-     * Allows signing in with an OIDC ID token. The authentication provider used
-     * should be enabled and configured.
-     */
-    signInWithIdToken(credentials: SignInWithIdTokenCredentials): Promise<AuthTokenResponse>;
-    /**
-     * Log in a user using magiclink or a one-time password (OTP).
-     *
-     * If the `{{ .ConfirmationURL }}` variable is specified in the email template, a magiclink will be sent.
-     * If the `{{ .Token }}` variable is specified in the email template, an OTP will be sent.
-     * If you're using phone sign-ins, only an OTP will be sent. You won't be able to send a magiclink for phone sign-ins.
      *
-     * Be aware that you may get back an error message that will not distinguish
-     * between the cases where the account does not exist or, that the account
-     * can only be accessed via social login.
+     * @category Auth
      *
-     * Do note that you will need to configure a Whatsapp sender on Twilio
-     * if you are using phone sign in with the 'whatsapp' channel. The whatsapp
-     * channel is not supported on other providers
-     * at this time.
-     * This method supports PKCE when an email is passed.
-     */
-    signInWithOtp(credentials: SignInWithPasswordlessCredentials): Promise<AuthOtpResponse>;
-    /**
-     * Log in a user given a User supplied OTP or TokenHash received through mobile or email.
-     */
-    verifyOtp(params: VerifyOtpParams): Promise<AuthResponse>;
-    /**
-     * Attempts a single-sign on using an enterprise Identity Provider. A
-     * successful SSO attempt will redirect the current page to the identity
-     * provider authorization page. The redirect URL is implementation and SSO
-     * protocol specific.
+     * @remarks
+     * - Used when `flowType` is set to `pkce` in client options.
      *
-     * You can use it by providing a SSO domain. Typically you can extract this
-     * domain by asking users for their email address. If this domain is
-     * registered on the Auth instance the redirect will use that organization's
-     * currently active SSO Identity Provider for the login.
+     * @example Exchange Auth Code
+     * ```js
+     * supabase.auth.exchangeCodeForSession('34e770dd-9ff9-416c-87fa-43b31d7ef225')
+     * ```
      *
-     * If you have built an organization-specific login page, you can use the
-     * organization's SSO Identity Provider UUID directly instead.
-     */
-    signInWithSSO(params: SignInWithSSO): Promise<SSOResponse>;
+     * @exampleResponse Exchange Auth Code
+     * ```json
+     * {
+     *   "data": {
+     *     session: {
+     *       access_token: '<ACCESS_TOKEN>',
+     *       token_type: 'bearer',
+     *       expires_in: 3600,
+     *       expires_at: 1700000000,
+     *       refresh_token: '<REFRESH_TOKEN>',
+     *       user: {
+     *         id: '11111111-1111-1111-1111-111111111111',
+     *         aud: 'authenticated',
+     *         role: 'authenticated',
+     *         email: 'example@email.com'
+     *         email_confirmed_at: '2024-01-01T00:00:00Z',
+     *         phone: '',
+     *         confirmation_sent_at: '2024-01-01T00:00:00Z',
+     *         confirmed_at: '2024-01-01T00:00:00Z',
+     *         last_sign_in_at: '2024-01-01T00:00:00Z',
+     *         app_metadata: {
+     *           "provider": "email",
+     *           "providers": [
+     *             "email",
+     *             "<OTHER_PROVIDER>"
+     *           ]
+     *         },
+     *         user_metadata: {
+     *           email: 'email@email.com',
+     *           email_verified: true,
+     *           full_name: 'User Name',
+     *           iss: '<ISS>',
+     *           name: 'User Name',
+     *           phone_verified: false,
+     *           provider_id: '<PROVIDER_ID>',
+     *           sub: '<SUB>'
+     *         },
+     *         identities: [
+     *           {
+     *             "identity_id": "22222222-2222-2222-2222-222222222222",
+     *             "id": "11111111-1111-1111-1111-111111111111",
+     *             "user_id": "11111111-1111-1111-1111-111111111111",
+     *             "identity_data": {
+     *               "email": "example@email.com",
+     *               "email_verified": false,
+     *               "phone_verified": false,
+     *               "sub": "11111111-1111-1111-1111-111111111111"
+     *             },
+     *             "provider": "email",
+     *             "last_sign_in_at": "2024-01-01T00:00:00Z",
+     *             "created_at": "2024-01-01T00:00:00Z",
+     *             "updated_at": "2024-01-01T00:00:00Z",
+     *             "email": "email@example.com"
+     *           },
+     *           {
+     *             "identity_id": "33333333-3333-3333-3333-333333333333",
+     *             "id": "<ID>",
+     *             "user_id": "<USER_ID>",
+     *             "identity_data": {
+     *               "email": "example@email.com",
+     *               "email_verified": true,
+     *               "full_name": "User Name",
+     *               "iss": "<ISS>",
+     *               "name": "User Name",
+     *               "phone_verified": false,
+     *               "provider_id": "<PROVIDER_ID>",
+     *               "sub": "<SUB>"
+     *             },
+     *             "provider": "<PROVIDER>",
+     *             "last_sign_in_at": "2024-01-01T00:00:00Z",
+     *             "created_at": "2024-01-01T00:00:00Z",
+     *             "updated_at": "2024-01-01T00:00:00Z",
+     *             "email": "example@email.com"
+     *           }
+     *         ],
+     *         created_at: '2024-01-01T00:00:00Z',
+     *         updated_at: '2024-01-01T00:00:00Z',
+     *         is_anonymous: false
+     *       },
+     *       provider_token: '<PROVIDER_TOKEN>',
+     *       provider_refresh_token: '<PROVIDER_REFRESH_TOKEN>'
+     *     },
+     *     user: {
+     *       id: '11111111-1111-1111-1111-111111111111',
+     *       aud: 'authenticated',
+     *       role: 'authenticated',
+     *       email: 'example@email.com',
+     *       email_confirmed_at: '2024-01-01T00:00:00Z',
+     *       phone: '',
+     *       confirmation_sent_at: '2024-01-01T00:00:00Z',
+     *       confirmed_at: '2024-01-01T00:00:00Z',
+     *       last_sign_in_at: '2024-01-01T00:00:00Z',
+     *       app_metadata: {
+     *         provider: 'email',
+     *         providers: [
+     *           "email",
+     *           "<OTHER_PROVIDER>"
+     *         ]
+     *       },
+     *       user_metadata: {
+     *         email: 'email@email.com',
+     *         email_verified: true,
+     *         full_name: 'User Name',
+     *         iss: '<ISS>',
+     *         name: 'User Name',
+     *         phone_verified: false,
+     *         provider_id: '<PROVIDER_ID>',
+     *         sub: '<SUB>'
+     *       },
+     *       identities: [
+     *         {
+     *           "identity_id": "22222222-2222-2222-2222-222222222222",
+     *           "id": "11111111-1111-1111-1111-111111111111",
+     *           "user_id": "11111111-1111-1111-1111-111111111111",
+     *           "identity_data": {
+     *             "email": "example@email.com",
+     *             "email_verified": false,
+     *             "phone_verified": false,
+     *             "sub": "11111111-1111-1111-1111-111111111111"
+     *           },
+     *           "provider": "email",
+     *           "last_sign_in_at": "2024-01-01T00:00:00Z",
+     *           "created_at": "2024-01-01T00:00:00Z",
+     *           "updated_at": "2024-01-01T00:00:00Z",
+     *           "email": "email@example.com"
+     *         },
+     *         {
+     *           "identity_id": "33333333-3333-3333-3333-333333333333",
+     *           "id": "<ID>",
+     *           "user_id": "<USER_ID>",
+     *           "identity_data": {
+     *             "email": "example@email.com",
+     *             "email_verified": true,
+     *             "full_name": "User Name",
+     *             "iss": "<ISS>",
+     *             "name": "User Name",
+     *             "phone_verified": false,
+     *             "provider_id": "<PROVIDER_ID>",
+     *             "sub": "<SUB>"
+     *           },
+     *           "provider": "<PROVIDER>",
+     *           "last_sign_in_at": "2024-01-01T00:00:00Z",
+     *           "created_at": "2024-01-01T00:00:00Z",
+     *           "updated_at": "2024-01-01T00:00:00Z",
+     *           "email": "example@email.com"
+     *         }
+     *       ],
+     *       created_at: '2024-01-01T00:00:00Z',
+     *       updated_at: '2024-01-01T00:00:00Z',
+     *       is_anonymous: false
+     *     },
+     *     redirectType: null
+     *   },
+     *   "error": null
+     * }
+     * ```
+     */
+    exchangeCodeForSession(authCode: string): Promise<AuthTokenResponse>;
+    /**
+     * Signs in a user by verifying a message signed by the user's private key.
+     * Supports Ethereum (via Sign-In-With-Ethereum) & Solana (Sign-In-With-Solana) standards,
+     * both of which derive from the EIP-4361 standard
+     * With slight variation on Solana's side.
+     * @reference https://eips.ethereum.org/EIPS/eip-4361
+     *
+     * @category Auth
+     *
+     * @remarks
+     * - Uses a Web3 (Ethereum, Solana) wallet to sign a user in.
+     * - Read up on the [potential for abuse](/docs/guides/auth/auth-web3#potential-for-abuse) before using it.
+     *
+     * @example Sign in with Solana or Ethereum (Window API)
+     * ```js
+     *   // uses window.ethereum for the wallet
+     *   const { data, error } = await supabase.auth.signInWithWeb3({
+     *     chain: 'ethereum',
+     *     statement: 'I accept the Terms of Service at https://example.com/tos'
+     *   })
+     *
+     *   // uses window.solana for the wallet
+     *   const { data, error } = await supabase.auth.signInWithWeb3({
+     *     chain: 'solana',
+     *     statement: 'I accept the Terms of Service at https://example.com/tos'
+     *   })
+     * ```
+     *
+     * @example Sign in with Ethereum (Message and Signature)
+     * ```js
+     *   const { data, error } = await supabase.auth.signInWithWeb3({
+     *     chain: 'ethereum',
+     *     message: '<sign in with ethereum message>',
+     *     signature: '<hex of the ethereum signature over the message>',
+     *   })
+     * ```
+     *
+     * @example Sign in with Solana (Brave)
+     * ```js
+     *   const { data, error } = await supabase.auth.signInWithWeb3({
+     *     chain: 'solana',
+     *     statement: 'I accept the Terms of Service at https://example.com/tos',
+     *     wallet: window.braveSolana
+     *   })
+     * ```
+     *
+     * @example Sign in with Solana (Wallet Adapter)
+     * ```jsx
+     *   function SignInButton() {
+     *   const wallet = useWallet()
+     *
+     *   return (
+     *     <>
+     *       {wallet.connected ? (
+     *         <button
+     *           onClick={() => {
+     *             supabase.auth.signInWithWeb3({
+     *               chain: 'solana',
+     *               statement: 'I accept the Terms of Service at https://example.com/tos',
+     *               wallet,
+     *             })
+     *           }}
+     *         >
+     *           Sign in with Solana
+     *         </button>
+     *       ) : (
+     *         <WalletMultiButton />
+     *       )}
+     *     </>
+     *   )
+     * }
+     *
+     * function App() {
+     *   const endpoint = clusterApiUrl('devnet')
+     *   const wallets = useMemo(() => [], [])
+     *
+     *   return (
+     *     <ConnectionProvider endpoint={endpoint}>
+     *       <WalletProvider wallets={wallets}>
+     *         <WalletModalProvider>
+     *           <SignInButton />
+     *         </WalletModalProvider>
+     *       </WalletProvider>
+     *     </ConnectionProvider>
+     *   )
+     * }
+     * ```
+     */
+    signInWithWeb3(credentials: Web3Credentials): Promise<{
+        data: {
+            session: Session;
+            user: User;
+        };
+        error: null;
+    } | {
+        data: {
+            session: null;
+            user: null;
+        };
+        error: AuthError;
+    }>;
+    private signInWithEthereum;
+    private signInWithSolana;
+    private _exchangeCodeForSession;
+    /**
+     * Allows signing in with an OIDC ID token. The authentication provider used
+     * should be enabled and configured.
+     *
+     * @category Auth
+     *
+     * @remarks
+     * - Use an ID token to sign in.
+     * - Especially useful when implementing sign in using native platform dialogs in mobile or desktop apps using Sign in with Apple or Sign in with Google on iOS and Android.
+     * - You can also use Google's [One Tap](https://developers.google.com/identity/gsi/web/guides/display-google-one-tap) and [Automatic sign-in](https://developers.google.com/identity/gsi/web/guides/automatic-sign-in-sign-out) via this API.
+     *
+     * @example Sign In using ID Token
+     * ```js
+     * const { data, error } = await supabase.auth.signInWithIdToken({
+     *   provider: 'google',
+     *   token: 'your-id-token'
+     * })
+     * ```
+     *
+     * @exampleResponse Sign In using ID Token
+     * ```json
+     * {
+     *   "data": {
+     *     "user": {
+     *       "id": "11111111-1111-1111-1111-111111111111",
+     *       "aud": "authenticated",
+     *       "role": "authenticated",
+     *       "last_sign_in_at": "2024-01-01T00:00:00Z",
+     *       "app_metadata": {
+     *         ...
+     *       },
+     *       "user_metadata": {
+     *         ...
+     *       },
+     *       "identities": [
+     *         {
+     *           "identity_id": "22222222-2222-2222-2222-222222222222",
+     *           "provider": "google",
+     *         }
+     *       ],
+     *       "created_at": "2024-01-01T00:00:00Z",
+     *       "updated_at": "2024-01-01T00:00:00Z",
+     *     },
+     *     "session": {
+     *       "access_token": "<ACCESS_TOKEN>",
+     *       "token_type": "bearer",
+     *       "expires_in": 3600,
+     *       "expires_at": 1700000000,
+     *       "refresh_token": "<REFRESH_TOKEN>",
+     *       "user": {
+     *         "id": "11111111-1111-1111-1111-111111111111",
+     *         "aud": "authenticated",
+     *         "role": "authenticated",
+     *         "last_sign_in_at": "2024-01-01T00:00:00Z",
+     *         "app_metadata": {
+     *           ...
+     *         },
+     *         "user_metadata": {
+     *           ...
+     *         },
+     *         "identities": [
+     *           {
+     *             "identity_id": "22222222-2222-2222-2222-222222222222",
+     *             "provider": "google",
+     *           }
+     *         ],
+     *         "created_at": "2024-01-01T00:00:00Z",
+     *         "updated_at": "2024-01-01T00:00:00Z",
+     *       }
+     *     }
+     *   },
+     *   "error": null
+     * }
+     * ```
+     */
+    signInWithIdToken(credentials: SignInWithIdTokenCredentials): Promise<AuthTokenResponse>;
+    /**
+     * Log in a user using magiclink or a one-time password (OTP).
+     *
+     * If the `{{ .ConfirmationURL }}` variable is specified in the email template, a magiclink will be sent.
+     * If the `{{ .Token }}` variable is specified in the email template, an OTP will be sent.
+     * If you're using phone sign-ins, only an OTP will be sent. You won't be able to send a magiclink for phone sign-ins.
+     *
+     * Be aware that you may get back an error message that will not distinguish
+     * between the cases where the account does not exist or, that the account
+     * can only be accessed via social login.
+     *
+     * Do note that you will need to configure a Whatsapp sender on Twilio
+     * if you are using phone sign in with the 'whatsapp' channel. The whatsapp
+     * channel is not supported on other providers
+     * at this time.
+     * This method supports PKCE when an email is passed.
+     *
+     * @category Auth
+     *
+     * @remarks
+     * - Requires either an email or phone number.
+     * - This method is used for passwordless sign-ins where a OTP is sent to the user's email or phone number.
+     * - If the user doesn't exist, `signInWithOtp()` will signup the user instead. To restrict this behavior, you can set `shouldCreateUser` in `SignInWithPasswordlessCredentials.options` to `false`.
+     * - If you're using an email, you can configure whether you want the user to receive a magiclink or a OTP.
+     * - If you're using phone, you can configure whether you want the user to receive a OTP.
+     * - The magic link's destination URL is determined by the [`SITE_URL`](/docs/guides/auth/redirect-urls#use-wildcards-in-redirect-urls).
+     * - See [redirect URLs and wildcards](/docs/guides/auth/redirect-urls#use-wildcards-in-redirect-urls) to add additional redirect URLs to your project.
+     * - Magic links and OTPs share the same implementation. To send users a one-time code instead of a magic link, [modify the magic link email template](/dashboard/project/_/auth/templates) to include `{{ .Token }}` instead of `{{ .ConfirmationURL }}`.
+     * - See our [Twilio Phone Auth Guide](/docs/guides/auth/phone-login?showSMSProvider=Twilio) for details about configuring WhatsApp sign in.
+     *
+     * @exampleDescription Sign in with email
+     * The user will be sent an email which contains either a magiclink or a OTP or both. By default, a given user can only request a OTP once every 60 seconds.
+     *
+     * @example Sign in with email
+     * ```js
+     * const { data, error } = await supabase.auth.signInWithOtp({
+     *   email: 'example@email.com',
+     *   options: {
+     *     emailRedirectTo: 'https://example.com/welcome'
+     *   }
+     * })
+     * ```
+     *
+     * @exampleResponse Sign in with email
+     * ```json
+     * {
+     *   "data": {
+     *     "user": null,
+     *     "session": null
+     *   },
+     *   "error": null
+     * }
+     * ```
+     *
+     * @exampleDescription Sign in with SMS OTP
+     * The user will be sent a SMS which contains a OTP. By default, a given user can only request a OTP once every 60 seconds.
+     *
+     * @example Sign in with SMS OTP
+     * ```js
+     * const { data, error } = await supabase.auth.signInWithOtp({
+     *   phone: '+13334445555',
+     * })
+     * ```
+     *
+     * @exampleDescription Sign in with WhatsApp OTP
+     * The user will be sent a WhatsApp message which contains a OTP. By default, a given user can only request a OTP once every 60 seconds. Note that a user will need to have a valid WhatsApp account that is linked to Twilio in order to use this feature.
+     *
+     * @example Sign in with WhatsApp OTP
+     * ```js
+     * const { data, error } = await supabase.auth.signInWithOtp({
+     *   phone: '+13334445555',
+     *   options: {
+     *     channel:'whatsapp',
+     *   }
+     * })
+     * ```
+     */
+    signInWithOtp(credentials: SignInWithPasswordlessCredentials): Promise<AuthOtpResponse>;
+    /**
+     * Log in a user given a User supplied OTP or TokenHash received through mobile or email.
+     *
+     * @category Auth
+     *
+     * @remarks
+     * - The `verifyOtp` method takes in different verification types.
+     * - If a phone number is used, the type can either be:
+     *   1. `sms` – Used when verifying a one-time password (OTP) sent via SMS during sign-up or sign-in.
+     *   2. `phone_change` – Used when verifying an OTP sent to a new phone number during a phone number update process.
+     * - If an email address is used, the type can be one of the following (note: `signup` and `magiclink` types are deprecated):
+     *   1. `email` – Used when verifying an OTP sent to the user's email during sign-up or sign-in.
+     *   2. `recovery` – Used when verifying an OTP sent for account recovery, typically after a password reset request.
+     *   3. `invite` – Used when verifying an OTP sent as part of an invitation to join a project or organization.
+     *   4. `email_change` – Used when verifying an OTP sent to a new email address during an email update process.
+     * - The verification type used should be determined based on the corresponding auth method called before `verifyOtp` to sign up / sign-in a user.
+     * - The `TokenHash` is contained in the [email templates](/docs/guides/auth/auth-email-templates) and can be used to sign in.  You may wish to use the hash for the PKCE flow for Server Side Auth. Read [the Password-based Auth guide](/docs/guides/auth/passwords) for more details.
+     *
+     * @example Verify Signup One-Time Password (OTP)
+     * ```js
+     * const { data, error } = await supabase.auth.verifyOtp({ email, token, type: 'email'})
+     * ```
+     *
+     * @exampleResponse Verify Signup One-Time Password (OTP)
+     * ```json
+     * {
+     *   "data": {
+     *     "user": {
+     *       "id": "11111111-1111-1111-1111-111111111111",
+     *       "aud": "authenticated",
+     *       "role": "authenticated",
+     *       "email": "example@email.com",
+     *       "email_confirmed_at": "2024-01-01T00:00:00Z",
+     *       "phone": "",
+     *       "confirmed_at": "2024-01-01T00:00:00Z",
+     *       "recovery_sent_at": "2024-01-01T00:00:00Z",
+     *       "last_sign_in_at": "2024-01-01T00:00:00Z",
+     *       "app_metadata": {
+     *         "provider": "email",
+     *         "providers": [
+     *           "email"
+     *         ]
+     *       },
+     *       "user_metadata": {
+     *         "email": "example@email.com",
+     *         "email_verified": false,
+     *         "phone_verified": false,
+     *         "sub": "11111111-1111-1111-1111-111111111111"
+     *       },
+     *       "identities": [
+     *         {
+     *           "identity_id": "22222222-2222-2222-2222-222222222222",
+     *           "id": "11111111-1111-1111-1111-111111111111",
+     *           "user_id": "11111111-1111-1111-1111-111111111111",
+     *           "identity_data": {
+     *             "email": "example@email.com",
+     *             "email_verified": false,
+     *             "phone_verified": false,
+     *             "sub": "11111111-1111-1111-1111-111111111111"
+     *           },
+     *           "provider": "email",
+     *           "last_sign_in_at": "2024-01-01T00:00:00Z",
+     *           "created_at": "2024-01-01T00:00:00Z",
+     *           "updated_at": "2024-01-01T00:00:00Z",
+     *           "email": "example@email.com"
+     *         }
+     *       ],
+     *       "created_at": "2024-01-01T00:00:00Z",
+     *       "updated_at": "2024-01-01T00:00:00Z",
+     *       "is_anonymous": false
+     *     },
+     *     "session": {
+     *       "access_token": "<ACCESS_TOKEN>",
+     *       "token_type": "bearer",
+     *       "expires_in": 3600,
+     *       "expires_at": 1700000000,
+     *       "refresh_token": "<REFRESH_TOKEN>",
+     *       "user": {
+     *         "id": "11111111-1111-1111-1111-111111111111",
+     *         "aud": "authenticated",
+     *         "role": "authenticated",
+     *         "email": "example@email.com",
+     *         "email_confirmed_at": "2024-01-01T00:00:00Z",
+     *         "phone": "",
+     *         "confirmed_at": "2024-01-01T00:00:00Z",
+     *         "recovery_sent_at": "2024-01-01T00:00:00Z",
+     *         "last_sign_in_at": "2024-01-01T00:00:00Z",
+     *         "app_metadata": {
+     *           "provider": "email",
+     *           "providers": [
+     *             "email"
+     *           ]
+     *         },
+     *         "user_metadata": {
+     *           "email": "example@email.com",
+     *           "email_verified": false,
+     *           "phone_verified": false,
+     *           "sub": "11111111-1111-1111-1111-111111111111"
+     *         },
+     *         "identities": [
+     *           {
+     *             "identity_id": "22222222-2222-2222-2222-222222222222",
+     *             "id": "11111111-1111-1111-1111-111111111111",
+     *             "user_id": "11111111-1111-1111-1111-111111111111",
+     *             "identity_data": {
+     *               "email": "example@email.com",
+     *               "email_verified": false,
+     *               "phone_verified": false,
+     *               "sub": "11111111-1111-1111-1111-111111111111"
+     *             },
+     *             "provider": "email",
+     *             "last_sign_in_at": "2024-01-01T00:00:00Z",
+     *             "created_at": "2024-01-01T00:00:00Z",
+     *             "updated_at": "2024-01-01T00:00:00Z",
+     *             "email": "example@email.com"
+     *           }
+     *         ],
+     *         "created_at": "2024-01-01T00:00:00Z",
+     *         "updated_at": "2024-01-01T00:00:00Z",
+     *         "is_anonymous": false
+     *       }
+     *     }
+     *   },
+     *   "error": null
+     * }
+     * ```
+     *
+     * @example Verify SMS One-Time Password (OTP)
+     * ```js
+     * const { data, error } = await supabase.auth.verifyOtp({ phone, token, type: 'sms'})
+     * ```
+     *
+     * @example Verify Email Auth (Token Hash)
+     * ```js
+     * const { data, error } = await supabase.auth.verifyOtp({ token_hash: tokenHash, type: 'email'})
+     * ```
+     */
+    verifyOtp(params: VerifyOtpParams): Promise<AuthResponse>;
+    /**
+     * Attempts a single-sign on using an enterprise Identity Provider. A
+     * successful SSO attempt will redirect the current page to the identity
+     * provider authorization page. The redirect URL is implementation and SSO
+     * protocol specific.
+     *
+     * You can use it by providing a SSO domain. Typically you can extract this
+     * domain by asking users for their email address. If this domain is
+     * registered on the Auth instance the redirect will use that organization's
+     * currently active SSO Identity Provider for the login.
+     *
+     * If you have built an organization-specific login page, you can use the
+     * organization's SSO Identity Provider UUID directly instead.
+     *
+     * @category Auth
+     *
+     * @remarks
+     * - Before you can call this method you need to [establish a connection](/docs/guides/auth/sso/auth-sso-saml#managing-saml-20-connections) to an identity provider. Use the [CLI commands](/docs/reference/cli/supabase-sso) to do this.
+     * - If you've associated an email domain to the identity provider, you can use the `domain` property to start a sign-in flow.
+     * - In case you need to use a different way to start the authentication flow with an identity provider, you can use the `providerId` property. For example:
+     *     - Mapping specific user email addresses with an identity provider.
+     *     - Using different hints to identity the identity provider to be used by the user, like a company-specific page, IP address or other tracking information.
+     *
+     * @example Sign in with email domain
+     * ```js
+     *   // You can extract the user's email domain and use it to trigger the
+     *   // authentication flow with the correct identity provider.
+     *
+     *   const { data, error } = await supabase.auth.signInWithSSO({
+     *     domain: 'company.com'
+     *   })
+     *
+     *   if (data?.url) {
+     *     // redirect the user to the identity provider's authentication flow
+     *     window.location.href = data.url
+     *   }
+     * ```
+     *
+     * @example Sign in with provider UUID
+     * ```js
+     *   // Useful when you need to map a user's sign in request according
+     *   // to different rules that can't use email domains.
+     *
+     *   const { data, error } = await supabase.auth.signInWithSSO({
+     *     providerId: '21648a9d-8d5a-4555-a9d1-d6375dc14e92'
+     *   })
+     *
+     *   if (data?.url) {
+     *     // redirect the user to the identity provider's authentication flow
+     *     window.location.href = data.url
+     *   }
+     * ```
+     */
+    signInWithSSO(params: SignInWithSSO): Promise<SSOResponse>;
     /**
      * Sends a reauthentication OTP to the user's email or phone number.
      * Requires the user to be signed-in.
+     *
+     * @category Auth
+     *
+     * @remarks
+     * - This method is used together with `updateUser()` when a user's password needs to be updated.
+     * - If you require your user to reauthenticate before updating their password, you need to enable the **Secure password change** option in your [project's email provider settings](/dashboard/project/_/auth/providers).
+     * - A user is only require to reauthenticate before updating their password if **Secure password change** is enabled and the user **hasn't recently signed in**. A user is deemed recently signed in if the session was created in the last 24 hours.
+     * - This method will send a nonce to the user's email. If the user doesn't have a confirmed email address, the method will send the nonce to the user's confirmed phone number instead.
+     * - After receiving the OTP, include it as the `nonce` in your `updateUser()` call to finalize the password change.
+     *
+     * @exampleDescription Send reauthentication nonce
+     * Sends a reauthentication nonce to the user's email or phone number.
+     *
+     * @example Send reauthentication nonce
+     * ```js
+     * const { error } = await supabase.auth.reauthenticate()
+     * ```
      */
     reauthenticate(): Promise<AuthResponse>;
     private _reauthenticate;
     /**
      * Resends an existing signup confirmation email, email change email, SMS OTP or phone change OTP.
+     *
+     * @category Auth
+     *
+     * @remarks
+     * - Resends a signup confirmation, email change or phone change email to the user.
+     * - Passwordless sign-ins can be resent by calling the `signInWithOtp()` method again.
+     * - Password recovery emails can be resent by calling the `resetPasswordForEmail()` method again.
+     * - This method will only resend an email or phone OTP to the user if there was an initial signup, email change or phone change request being made(note: For existing users signing in with OTP, you should use `signInWithOtp()` again to resend the OTP).
+     * - You can specify a redirect url when you resend an email link using the `emailRedirectTo` option.
+     *
+     * @exampleDescription Resend an email signup confirmation
+     * Resends the email signup confirmation to the user
+     *
+     * @example Resend an email signup confirmation
+     * ```js
+     * const { error } = await supabase.auth.resend({
+     *   type: 'signup',
+     *   email: 'email@example.com',
+     *   options: {
+     *     emailRedirectTo: 'https://example.com/welcome'
+     *   }
+     * })
+     * ```
+     *
+     * @exampleDescription Resend a phone signup confirmation
+     * Resends the phone signup confirmation email to the user
+     *
+     * @example Resend a phone signup confirmation
+     * ```js
+     * const { error } = await supabase.auth.resend({
+     *   type: 'sms',
+     *   phone: '1234567890'
+     * })
+     * ```
+     *
+     * @exampleDescription Resend email change email
+     * Resends the email change email to the user
+     *
+     * @example Resend email change email
+     * ```js
+     * const { error } = await supabase.auth.resend({
+     *   type: 'email_change',
+     *   email: 'email@example.com'
+     * })
+     * ```
+     *
+     * @exampleDescription Resend phone change OTP
+     * Resends the phone change OTP to the user
+     *
+     * @example Resend phone change OTP
+     * ```js
+     * const { error } = await supabase.auth.resend({
+     *   type: 'phone_change',
+     *   phone: '1234567890'
+     * })
+     * ```
      */
     resend(credentials: ResendParams): Promise<AuthOtpResponse>;
     /**
@@ -407,6 +1286,80 @@ export default class GoTrueClient {
      * the values in it may not be authentic and therefore it's strongly advised
      * against using this method and its results in such circumstances. A warning
      * will be emitted if this is detected. Use {@link #getUser()} instead.
+     *
+     * @category Auth
+     *
+     * @remarks
+     * - Since the introduction of [asymmetric JWT signing keys](/docs/guides/auth/signing-keys), this method is considered low-level and we encourage you to use `getClaims()` or `getUser()` instead.
+     * - Retrieves the current [user session](/docs/guides/auth/sessions) from the storage medium (local storage, cookies).
+     * - The session contains an access token (signed JWT), a refresh token and the user object.
+     * - If the session's access token is expired or is about to expire, this method will use the refresh token to refresh the session.
+     * - When using in a browser, or you've called `startAutoRefresh()` in your environment (React Native, etc.) this function always returns a valid access token without refreshing the session itself, as this is done in the background. This function returns very fast.
+     * - **IMPORTANT SECURITY NOTICE:** If using an insecure storage medium, such as cookies or request headers, the user object returned by this function **must not be trusted**. Always verify the JWT using `getClaims()` or your own JWT verification library to securely establish the user's identity and access. You can also use `getUser()` to fetch the user object directly from the Auth server for this purpose.
+     * - When using in a browser, this function is synchronized across all tabs using the [LockManager](https://developer.mozilla.org/en-US/docs/Web/API/LockManager) API. In other environments make sure you've defined a proper `lock` property, if necessary, to make sure there are no race conditions while the session is being refreshed.
+     *
+     * @example Get the session data
+     * ```js
+     * const { data, error } = await supabase.auth.getSession()
+     * ```
+     *
+     * @exampleResponse Get the session data
+     * ```json
+     * {
+     *   "data": {
+     *     "session": {
+     *       "access_token": "<ACCESS_TOKEN>",
+     *       "token_type": "bearer",
+     *       "expires_in": 3600,
+     *       "expires_at": 1700000000,
+     *       "refresh_token": "<REFRESH_TOKEN>",
+     *       "user": {
+     *         "id": "11111111-1111-1111-1111-111111111111",
+     *         "aud": "authenticated",
+     *         "role": "authenticated",
+     *         "email": "example@email.com",
+     *         "email_confirmed_at": "2024-01-01T00:00:00Z",
+     *         "phone": "",
+     *         "last_sign_in_at": "2024-01-01T00:00:00Z",
+     *         "app_metadata": {
+     *           "provider": "email",
+     *           "providers": [
+     *             "email"
+     *           ]
+     *         },
+     *         "user_metadata": {
+     *           "email": "example@email.com",
+     *           "email_verified": false,
+     *           "phone_verified": false,
+     *           "sub": "11111111-1111-1111-1111-111111111111"
+     *         },
+     *         "identities": [
+     *           {
+     *             "identity_id": "22222222-2222-2222-2222-222222222222",
+     *             "id": "11111111-1111-1111-1111-111111111111",
+     *             "user_id": "11111111-1111-1111-1111-111111111111",
+     *             "identity_data": {
+     *               "email": "example@email.com",
+     *               "email_verified": false,
+     *               "phone_verified": false,
+     *               "sub": "11111111-1111-1111-1111-111111111111"
+     *             },
+     *             "provider": "email",
+     *             "last_sign_in_at": "2024-01-01T00:00:00Z",
+     *             "created_at": "2024-01-01T00:00:00Z",
+     *             "updated_at": "2024-01-01T00:00:00Z",
+     *             "email": "example@email.com"
+     *           }
+     *         ],
+     *         "created_at": "2024-01-01T00:00:00Z",
+     *         "updated_at": "2024-01-01T00:00:00Z",
+     *         "is_anonymous": false
+     *       }
+     *     }
+     *   },
+     *   "error": null
+     * }
+     * ```
      */
     getSession(): Promise<{
         data: {
@@ -447,11 +1400,191 @@ export default class GoTrueClient {
      * value is authentic and can be used to base authorization rules on.
      *
      * @param jwt Takes in an optional access token JWT. If no JWT is provided, the JWT from the current session is used.
+     *
+     * @category Auth
+     *
+     * @remarks
+     * - This method fetches the user object from the database instead of local session.
+     * - This method is useful for checking if the user is authorized because it validates the user's access token JWT on the server.
+     * - Should always be used when checking for user authorization on the server. On the client, you can instead use `getSession().session.user` for faster results. `getSession` is insecure on the server.
+     *
+     * @example Get the logged in user with the current existing session
+     * ```js
+     * const { data: { user } } = await supabase.auth.getUser()
+     * ```
+     *
+     * @exampleResponse Get the logged in user with the current existing session
+     * ```json
+     * {
+     *   "data": {
+     *     "user": {
+     *       "id": "11111111-1111-1111-1111-111111111111",
+     *       "aud": "authenticated",
+     *       "role": "authenticated",
+     *       "email": "example@email.com",
+     *       "email_confirmed_at": "2024-01-01T00:00:00Z",
+     *       "phone": "",
+     *       "confirmed_at": "2024-01-01T00:00:00Z",
+     *       "last_sign_in_at": "2024-01-01T00:00:00Z",
+     *       "app_metadata": {
+     *         "provider": "email",
+     *         "providers": [
+     *           "email"
+     *         ]
+     *       },
+     *       "user_metadata": {
+     *         "email": "example@email.com",
+     *         "email_verified": false,
+     *         "phone_verified": false,
+     *         "sub": "11111111-1111-1111-1111-111111111111"
+     *       },
+     *       "identities": [
+     *         {
+     *           "identity_id": "22222222-2222-2222-2222-222222222222",
+     *           "id": "11111111-1111-1111-1111-111111111111",
+     *           "user_id": "11111111-1111-1111-1111-111111111111",
+     *           "identity_data": {
+     *             "email": "example@email.com",
+     *             "email_verified": false,
+     *             "phone_verified": false,
+     *             "sub": "11111111-1111-1111-1111-111111111111"
+     *           },
+     *           "provider": "email",
+     *           "last_sign_in_at": "2024-01-01T00:00:00Z",
+     *           "created_at": "2024-01-01T00:00:00Z",
+     *           "updated_at": "2024-01-01T00:00:00Z",
+     *           "email": "example@email.com"
+     *         }
+     *       ],
+     *       "created_at": "2024-01-01T00:00:00Z",
+     *       "updated_at": "2024-01-01T00:00:00Z",
+     *       "is_anonymous": false
+     *     }
+     *   },
+     *   "error": null
+     * }
+     * ```
+     *
+     * @example Get the logged in user with a custom access token jwt
+     * ```js
+     * const { data: { user } } = await supabase.auth.getUser(jwt)
+     * ```
      */
     getUser(jwt?: string): Promise<UserResponse>;
     private _getUser;
     /**
      * Updates user data for a logged in user.
+     *
+     * @category Auth
+     *
+     * @remarks
+     * - In order to use the `updateUser()` method, the user needs to be signed in first.
+     * - By default, email updates sends a confirmation link to both the user's current and new email.
+     * To only send a confirmation link to the user's new email, disable **Secure email change** in your project's [email auth provider settings](/dashboard/project/_/auth/providers).
+     *
+     * @exampleDescription Update the email for an authenticated user
+     * Sends a "Confirm Email Change" email to the new address. If **Secure Email Change** is enabled (default), confirmation is also required from the **old email** before the change is applied. To skip dual confirmation and apply the change after only the new email is verified, disable **Secure Email Change** in the [Email Auth Provider settings](/dashboard/project/_/auth/providers?provider=Email).
+     *
+     * @example Update the email for an authenticated user
+     * ```js
+     * const { data, error } = await supabase.auth.updateUser({
+     *   email: 'new@email.com'
+     * })
+     * ```
+     *
+     * @exampleResponse Update the email for an authenticated user
+     * ```json
+     * {
+     *   "data": {
+     *     "user": {
+     *       "id": "11111111-1111-1111-1111-111111111111",
+     *       "aud": "authenticated",
+     *       "role": "authenticated",
+     *       "email": "example@email.com",
+     *       "email_confirmed_at": "2024-01-01T00:00:00Z",
+     *       "phone": "",
+     *       "confirmed_at": "2024-01-01T00:00:00Z",
+     *       "new_email": "new@email.com",
+     *       "email_change_sent_at": "2024-01-01T00:00:00Z",
+     *       "last_sign_in_at": "2024-01-01T00:00:00Z",
+     *       "app_metadata": {
+     *         "provider": "email",
+     *         "providers": [
+     *           "email"
+     *         ]
+     *       },
+     *       "user_metadata": {
+     *         "email": "example@email.com",
+     *         "email_verified": false,
+     *         "phone_verified": false,
+     *         "sub": "11111111-1111-1111-1111-111111111111"
+     *       },
+     *       "identities": [
+     *         {
+     *           "identity_id": "22222222-2222-2222-2222-222222222222",
+     *           "id": "11111111-1111-1111-1111-111111111111",
+     *           "user_id": "11111111-1111-1111-1111-111111111111",
+     *           "identity_data": {
+     *             "email": "example@email.com",
+     *             "email_verified": false,
+     *             "phone_verified": false,
+     *             "sub": "11111111-1111-1111-1111-111111111111"
+     *           },
+     *           "provider": "email",
+     *           "last_sign_in_at": "2024-01-01T00:00:00Z",
+     *           "created_at": "2024-01-01T00:00:00Z",
+     *           "updated_at": "2024-01-01T00:00:00Z",
+     *           "email": "example@email.com"
+     *         }
+     *       ],
+     *       "created_at": "2024-01-01T00:00:00Z",
+     *       "updated_at": "2024-01-01T00:00:00Z",
+     *       "is_anonymous": false
+     *     }
+     *   },
+     *   "error": null
+     * }
+     * ```
+     *
+     * @exampleDescription Update the phone number for an authenticated user
+     * Sends a one-time password (OTP) to the new phone number.
+     *
+     * @example Update the phone number for an authenticated user
+     * ```js
+     * const { data, error } = await supabase.auth.updateUser({
+     *   phone: '123456789'
+     * })
+     * ```
+     *
+     * @example Update the password for an authenticated user
+     * ```js
+     * const { data, error } = await supabase.auth.updateUser({
+     *   password: 'new password'
+     * })
+     * ```
+     *
+     * @exampleDescription Update the user's metadata
+     * Updates the user's custom metadata.
+     *
+     * **Note**: The `data` field maps to the `auth.users.raw_user_meta_data` column in your Supabase database. When calling `getUser()`, the data will be available as `user.user_metadata`.
+     *
+     * @example Update the user's metadata
+     * ```js
+     * const { data, error } = await supabase.auth.updateUser({
+     *   data: { hello: 'world' }
+     * })
+     * ```
+     *
+     * @exampleDescription Update the user's password with a nonce
+     * If **Secure password change** is enabled in your [project's email provider settings](/dashboard/project/_/auth/providers), updating the user's password would require a nonce if the user **hasn't recently signed in**. The nonce is sent to the user's email or phone number. A user is deemed recently signed in if the session was created in the last 24 hours.
+     *
+     * @example Update the user's password with a nonce
+     * ```js
+     * const { data, error } = await supabase.auth.updateUser({
+     *   password: 'new password',
+     *   nonce: '123456'
+     * })
+     * ```
      */
     updateUser(attributes: UserAttributes, options?: {
         emailRedirectTo?: string | undefined;
@@ -463,6 +1596,125 @@ export default class GoTrueClient {
      * Sets the session data from the current session. If the current session is expired, setSession will take care of refreshing it to obtain a new session.
      * If the refresh token or access token in the current session is invalid, an error will be thrown.
      * @param currentSession The current session that minimally contains an access token and refresh token.
+     *
+     * @category Auth
+     *
+     * @remarks
+     * - This method sets the session using an `access_token` and `refresh_token`.
+     * - If successful, a `SIGNED_IN` event is emitted.
+     *
+     * @exampleDescription Set the session
+     * Sets the session data from an access_token and refresh_token, then returns an auth response or error.
+     *
+     * @example Set the session
+     * ```js
+     *   const { data, error } = await supabase.auth.setSession({
+     *     access_token,
+     *     refresh_token
+     *   })
+     * ```
+     *
+     * @exampleResponse Set the session
+     * ```json
+     * {
+     *   "data": {
+     *     "user": {
+     *       "id": "11111111-1111-1111-1111-111111111111",
+     *       "aud": "authenticated",
+     *       "role": "authenticated",
+     *       "email": "example@email.com",
+     *       "email_confirmed_at": "2024-01-01T00:00:00Z",
+     *       "phone": "",
+     *       "confirmed_at": "2024-01-01T00:00:00Z",
+     *       "last_sign_in_at": "2024-01-01T00:00:00Z",
+     *       "app_metadata": {
+     *         "provider": "email",
+     *         "providers": [
+     *           "email"
+     *         ]
+     *       },
+     *       "user_metadata": {
+     *         "email": "example@email.com",
+     *         "email_verified": false,
+     *         "phone_verified": false,
+     *         "sub": "11111111-1111-1111-1111-111111111111"
+     *       },
+     *       "identities": [
+     *         {
+     *           "identity_id": "22222222-2222-2222-2222-222222222222",
+     *           "id": "11111111-1111-1111-1111-111111111111",
+     *           "user_id": "11111111-1111-1111-1111-111111111111",
+     *           "identity_data": {
+     *             "email": "example@email.com",
+     *             "email_verified": false,
+     *             "phone_verified": false,
+     *             "sub": "11111111-1111-1111-1111-111111111111"
+     *           },
+     *           "provider": "email",
+     *           "last_sign_in_at": "2024-01-01T00:00:00Z",
+     *           "created_at": "2024-01-01T00:00:00Z",
+     *           "updated_at": "2024-01-01T00:00:00Z",
+     *           "email": "example@email.com"
+     *         }
+     *       ],
+     *       "created_at": "2024-01-01T00:00:00Z",
+     *       "updated_at": "2024-01-01T00:00:00Z",
+     *       "is_anonymous": false
+     *     },
+     *     "session": {
+     *       "access_token": "<ACCESS_TOKEN>",
+     *       "refresh_token": "<REFRESH_TOKEN>",
+     *       "user": {
+     *         "id": "11111111-1111-1111-1111-111111111111",
+     *         "aud": "authenticated",
+     *         "role": "authenticated",
+     *         "email": "example@email.com",
+     *         "email_confirmed_at": "2024-01-01T00:00:00Z",
+     *         "phone": "",
+     *         "confirmed_at": "2024-01-01T00:00:00Z",
+     *         "last_sign_in_at": "11111111-1111-1111-1111-111111111111",
+     *         "app_metadata": {
+     *           "provider": "email",
+     *           "providers": [
+     *             "email"
+     *           ]
+     *         },
+     *         "user_metadata": {
+     *           "email": "example@email.com",
+     *           "email_verified": false,
+     *           "phone_verified": false,
+     *           "sub": "11111111-1111-1111-1111-111111111111"
+     *         },
+     *         "identities": [
+     *           {
+     *             "identity_id": "2024-01-01T00:00:00Z",
+     *             "id": "11111111-1111-1111-1111-111111111111",
+     *             "user_id": "11111111-1111-1111-1111-111111111111",
+     *             "identity_data": {
+     *               "email": "example@email.com",
+     *               "email_verified": false,
+     *               "phone_verified": false,
+     *               "sub": "11111111-1111-1111-1111-111111111111"
+     *             },
+     *             "provider": "email",
+     *             "last_sign_in_at": "2024-01-01T00:00:00Z",
+     *             "created_at": "2024-01-01T00:00:00Z",
+     *             "updated_at": "2024-01-01T00:00:00Z",
+     *             "email": "example@email.com"
+     *           }
+     *         ],
+     *         "created_at": "2024-01-01T00:00:00Z",
+     *         "updated_at": "2024-01-01T00:00:00Z",
+     *         "is_anonymous": false
+     *       },
+     *       "token_type": "bearer",
+     *       "expires_in": 3500,
+     *       "expires_at": 1700000000
+     *     }
+     *   },
+     *   "error": null
+     * }
+     * ```
      */
     setSession(currentSession: {
         access_token: string;
@@ -477,6 +1729,125 @@ export default class GoTrueClient {
      * Takes in an optional current session. If not passed in, then refreshSession() will attempt to retrieve it from getSession().
      * If the current session's refresh token is invalid, an error will be thrown.
      * @param currentSession The current session. If passed in, it must contain a refresh token.
+     *
+     * @category Auth
+     *
+     * @remarks
+     * - This method will refresh and return a new session whether the current one is expired or not.
+     *
+     * @example Refresh session using the current session
+     * ```js
+     * const { data, error } = await supabase.auth.refreshSession()
+     * const { session, user } = data
+     * ```
+     *
+     * @exampleResponse Refresh session using the current session
+     * ```json
+     * {
+     *   "data": {
+     *     "user": {
+     *       "id": "11111111-1111-1111-1111-111111111111",
+     *       "aud": "authenticated",
+     *       "role": "authenticated",
+     *       "email": "example@email.com",
+     *       "email_confirmed_at": "2024-01-01T00:00:00Z",
+     *       "phone": "",
+     *       "confirmed_at": "2024-01-01T00:00:00Z",
+     *       "last_sign_in_at": "2024-01-01T00:00:00Z",
+     *       "app_metadata": {
+     *         "provider": "email",
+     *         "providers": [
+     *           "email"
+     *         ]
+     *       },
+     *       "user_metadata": {
+     *         "email": "example@email.com",
+     *         "email_verified": false,
+     *         "phone_verified": false,
+     *         "sub": "11111111-1111-1111-1111-111111111111"
+     *       },
+     *       "identities": [
+     *         {
+     *           "identity_id": "22222222-2222-2222-2222-222222222222",
+     *           "id": "11111111-1111-1111-1111-111111111111",
+     *           "user_id": "11111111-1111-1111-1111-111111111111",
+     *           "identity_data": {
+     *             "email": "example@email.com",
+     *             "email_verified": false,
+     *             "phone_verified": false,
+     *             "sub": "11111111-1111-1111-1111-111111111111"
+     *           },
+     *           "provider": "email",
+     *           "last_sign_in_at": "2024-01-01T00:00:00Z",
+     *           "created_at": "2024-01-01T00:00:00Z",
+     *           "updated_at": "2024-01-01T00:00:00Z",
+     *           "email": "example@email.com"
+     *         }
+     *       ],
+     *       "created_at": "2024-01-01T00:00:00Z",
+     *       "updated_at": "2024-01-01T00:00:00Z",
+     *       "is_anonymous": false
+     *     },
+     *     "session": {
+     *       "access_token": "<ACCESS_TOKEN>",
+     *       "token_type": "bearer",
+     *       "expires_in": 3600,
+     *       "expires_at": 1700000000,
+     *       "refresh_token": "<REFRESH_TOKEN>",
+     *       "user": {
+     *         "id": "11111111-1111-1111-1111-111111111111",
+     *         "aud": "authenticated",
+     *         "role": "authenticated",
+     *         "email": "example@email.com",
+     *         "email_confirmed_at": "2024-01-01T00:00:00Z",
+     *         "phone": "",
+     *         "confirmed_at": "2024-01-01T00:00:00Z",
+     *         "last_sign_in_at": "2024-01-01T00:00:00Z",
+     *         "app_metadata": {
+     *           "provider": "email",
+     *           "providers": [
+     *             "email"
+     *           ]
+     *         },
+     *         "user_metadata": {
+     *           "email": "example@email.com",
+     *           "email_verified": false,
+     *           "phone_verified": false,
+     *           "sub": "11111111-1111-1111-1111-111111111111"
+     *         },
+     *         "identities": [
+     *           {
+     *             "identity_id": "22222222-2222-2222-2222-222222222222",
+     *             "id": "11111111-1111-1111-1111-111111111111",
+     *             "user_id": "11111111-1111-1111-1111-111111111111",
+     *             "identity_data": {
+     *               "email": "example@email.com",
+     *               "email_verified": false,
+     *               "phone_verified": false,
+     *               "sub": "11111111-1111-1111-1111-111111111111"
+     *             },
+     *             "provider": "email",
+     *             "last_sign_in_at": "2024-01-01T00:00:00Z",
+     *             "created_at": "2024-01-01T00:00:00Z",
+     *             "updated_at": "2024-01-01T00:00:00Z",
+     *             "email": "example@email.com"
+     *           }
+     *         ],
+     *         "created_at": "2024-01-01T00:00:00Z",
+     *         "updated_at": "2024-01-01T00:00:00Z",
+     *         "is_anonymous": false
+     *       }
+     *     }
+     *   },
+     *   "error": null
+     * }
+     * ```
+     *
+     * @example Refresh session using a refresh token
+     * ```js
+     * const { data, error } = await supabase.auth.refreshSession({ refresh_token })
+     * const { session, user } = data
+     * ```
      */
     refreshSession(currentSession?: {
         refresh_token: string;
@@ -507,6 +1878,28 @@ export default class GoTrueClient {
      * There is no way to revoke a user's access token jwt until it expires. It is recommended to set a shorter expiry on the jwt for this reason.
      *
      * If using `others` scope, no `SIGNED_OUT` event is fired!
+     *
+     * @category Auth
+     *
+     * @remarks
+     * - In order to use the `signOut()` method, the user needs to be signed in first.
+     * - By default, `signOut()` uses the global scope, which signs out all other sessions that the user is logged into as well. Customize this behavior by passing a scope parameter.
+     * - Since Supabase Auth uses JWTs for authentication, the access token JWT will be valid until it's expired. When the user signs out, Supabase revokes the refresh token and deletes the JWT from the client-side. This does not revoke the JWT and it will still be valid until it expires.
+     *
+     * @example Sign out (all sessions)
+     * ```js
+     * const { error } = await supabase.auth.signOut()
+     * ```
+     *
+     * @example Sign out (current session)
+     * ```js
+     * const { error } = await supabase.auth.signOut({ scope: 'local' })
+     * ```
+     *
+     * @example Sign out (other sessions)
+     * ```js
+     * const { error } = await supabase.auth.signOut({ scope: 'others' })
+     * ```
      */
     signOut(options?: SignOut): Promise<{
         error: AuthError | null;
@@ -549,6 +1942,66 @@ export default class GoTrueClient {
      * @param email The email address of the user.
      * @param options.redirectTo The URL to send the user to after they click the password reset link.
      * @param options.captchaToken Verification token received when the user completes the captcha on the site.
+     *
+     * @category Auth
+     *
+     * @remarks
+     * - The password reset flow consist of 2 broad steps: (i) Allow the user to login via the password reset link; (ii) Update the user's password.
+     * - The `resetPasswordForEmail()` only sends a password reset link to the user's email.
+     * To update the user's password, see [`updateUser()`](/docs/reference/javascript/auth-updateuser).
+     * - A `PASSWORD_RECOVERY` event will be emitted when the password recovery link is clicked.
+     * You can use [`onAuthStateChange()`](/docs/reference/javascript/auth-onauthstatechange) to listen and invoke a callback function on these events.
+     * - When the user clicks the reset link in the email they are redirected back to your application.
+     * You can configure the URL that the user is redirected to with the `redirectTo` parameter.
+     * See [redirect URLs and wildcards](/docs/guides/auth/redirect-urls#use-wildcards-in-redirect-urls) to add additional redirect URLs to your project.
+     * - After the user has been redirected successfully, prompt them for a new password and call `updateUser()`:
+     * ```js
+     * const { data, error } = await supabase.auth.updateUser({
+     *   password: new_password
+     * })
+     * ```
+     *
+     * @example Reset password
+     * ```js
+     * const { data, error } = await supabase.auth.resetPasswordForEmail(email, {
+     *   redirectTo: 'https://example.com/update-password',
+     * })
+     * ```
+     *
+     * @exampleResponse Reset password
+     * ```json
+     * {
+     *   data: {}
+     *   error: null
+     * }
+     * ```
+     *
+     * @example Reset password (React)
+     * ```js
+     * /**
+     *  * Step 1: Send the user an email to get a password reset token.
+     *  * This email contains a link which sends the user back to your application.
+     *  *\/
+     * const { data, error } = await supabase.auth
+     *   .resetPasswordForEmail('user@email.com')
+     *
+     * /**
+     *  * Step 2: Once the user is redirected back to your application,
+     *  * ask the user to reset their password.
+     *  *\/
+     *  useEffect(() => {
+     *    supabase.auth.onAuthStateChange(async (event, session) => {
+     *      if (event == "PASSWORD_RECOVERY") {
+     *        const newPassword = prompt("What would you like your new password to be?");
+     *        const { data, error } = await supabase.auth
+     *          .updateUser({ password: newPassword })
+     *
+     *        if (data) alert("Password updated successfully!")
+     *        if (error) alert("There was an error updating your password.")
+     *      }
+     *    })
+     *  }, [])
+     * ```
      */
     resetPasswordForEmail(email: string, options?: {
         redirectTo?: string;
@@ -562,6 +2015,43 @@ export default class GoTrueClient {
     }>;
     /**
      * Gets all the identities linked to a user.
+     *
+     * @category Auth
+     *
+     * @remarks
+     * - The user needs to be signed in to call `getUserIdentities()`.
+     *
+     * @example Returns a list of identities linked to the user
+     * ```js
+     * const { data, error } = await supabase.auth.getUserIdentities()
+     * ```
+     *
+     * @exampleResponse Returns a list of identities linked to the user
+     * ```json
+     * {
+     *   "data": {
+     *     "identities": [
+     *       {
+     *         "identity_id": "22222222-2222-2222-2222-222222222222",
+     *         "id": "2024-01-01T00:00:00Z",
+     *         "user_id": "2024-01-01T00:00:00Z",
+     *         "identity_data": {
+     *           "email": "example@email.com",
+     *           "email_verified": false,
+     *           "phone_verified": false,
+     *           "sub": "11111111-1111-1111-1111-111111111111"
+     *         },
+     *         "provider": "email",
+     *         "last_sign_in_at": "2024-01-01T00:00:00Z",
+     *         "created_at": "2024-01-01T00:00:00Z",
+     *         "updated_at": "2024-01-01T00:00:00Z",
+     *         "email": "example@email.com"
+     *       }
+     *     ]
+     *   },
+     *   "error": null
+     * }
+     * ```
      */
     getUserIdentities(): Promise<{
         data: {
@@ -585,6 +2075,28 @@ export default class GoTrueClient {
     private linkIdentityIdToken;
     /**
      * Unlinks an identity from a user by deleting it. The user will no longer be able to sign in with that identity once it's unlinked.
+     *
+     * @category Auth
+     *
+     * @remarks
+     * - The **Enable Manual Linking** option must be enabled from your [project's authentication settings](/dashboard/project/_/auth/providers).
+     * - The user needs to be signed in to call `unlinkIdentity()`.
+     * - The user must have at least 2 identities in order to unlink an identity.
+     * - The identity to be unlinked must belong to the user.
+     *
+     * @example Unlink an identity
+     * ```js
+     * // retrieve all identities linked to a user
+     * const identities = await supabase.auth.getUserIdentities()
+     *
+     * // find the google identity
+     * const googleIdentity = identities.find(
+     *   identity => identity.provider === 'google'
+     * )
+     *
+     * // unlink the google identity
+     * const { error } = await supabase.auth.unlinkIdentity(googleIdentity)
+     * ```
      */
     unlinkIdentity(identity: UserIdentity): Promise<{
         data: {};
@@ -651,6 +2163,28 @@ export default class GoTrueClient {
      * appropriately to conserve resources.
      *
      * {@see #stopAutoRefresh}
+     *
+     * @category Auth
+     *
+     * @remarks
+     * - Only useful in non-browser environments such as React Native or Electron.
+     * - The Supabase Auth library automatically starts and stops proactively refreshing the session when a tab is focused or not.
+     * - On non-browser platforms, such as mobile or desktop apps built with web technologies, the library is not able to effectively determine whether the application is _focused_ or not.
+     * - To give this hint to the application, you should be calling this method when the app is in focus and calling `supabase.auth.stopAutoRefresh()` when it's out of focus.
+     *
+     * @example Start and stop auto refresh in React Native
+     * ```js
+     * import { AppState } from 'react-native'
+     *
+     * // make sure you register this only once!
+     * AppState.addEventListener('change', (state) => {
+     *   if (state === 'active') {
+     *     supabase.auth.startAutoRefresh()
+     *   } else {
+     *     supabase.auth.stopAutoRefresh()
+     *   }
+     * })
+     * ```
      */
     startAutoRefresh(): Promise<void>;
     /**
@@ -660,6 +2194,28 @@ export default class GoTrueClient {
      * removed and you must manage visibility changes on your own.
      *
      * See {@link #startAutoRefresh} for more details.
+     *
+     * @category Auth
+     *
+     * @remarks
+     * - Only useful in non-browser environments such as React Native or Electron.
+     * - The Supabase Auth library automatically starts and stops proactively refreshing the session when a tab is focused or not.
+     * - On non-browser platforms, such as mobile or desktop apps built with web technologies, the library is not able to effectively determine whether the application is _focused_ or not.
+     * - When your application goes in the background or out of focus, call this method to stop the proactive refreshing of the session.
+     *
+     * @example Start and stop auto refresh in React Native
+     * ```js
+     * import { AppState } from 'react-native'
+     *
+     * // make sure you register this only once!
+     * AppState.addEventListener('change', (state) => {
+     *   if (state === 'active') {
+     *     supabase.auth.startAutoRefresh()
+     *   } else {
+     *     supabase.auth.stopAutoRefresh()
+     *   }
+     * })
+     * ```
      */
     stopAutoRefresh(): Promise<void>;
     /**
@@ -753,6 +2309,55 @@ export default class GoTrueClient {
      *            can obtain from {@link #getSession}.
      * @param options Various additional options that allow you to customize the
      *                behavior of this method.
+     *
+     * @category Auth
+     *
+     * @remarks
+     * - Parses the user's [access token](/docs/guides/auth/sessions#access-token-jwt-claims) as a [JSON Web Token (JWT)](/docs/guides/auth/jwts) and returns its components if valid and not expired.
+     * - If your project is using asymmetric JWT signing keys, then the verification is done locally usually without a network request using the [WebCrypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API).
+     * - A network request is sent to your project's JWT signing key discovery endpoint `https://project-id.supabase.co/auth/v1/.well-known/jwks.json`, which is cached locally. If your environment is ephemeral, such as a Lambda function that is destroyed after every request, a network request will be sent for each new invocation. Supabase provides a network-edge cache providing fast responses for these situations.
+     * - If the user's access token is about to expire when calling this function, the user's session will first be refreshed before validating the JWT.
+     * - If your project is using a symmetric secret to sign the JWT, it always sends a request similar to `getUser()` to validate the JWT at the server before returning the decoded token. This is also used if the WebCrypto API is not available in the environment. Make sure you polyfill it in such situations.
+     * - The returned claims can be customized per project using the [Custom Access Token Hook](/docs/guides/auth/auth-hooks/custom-access-token-hook).
+     *
+     * @example Get JWT claims, header and signature
+     * ```js
+     * const { data, error } = await supabase.auth.getClaims()
+     * ```
+     *
+     * @exampleResponse Get JWT claims, header and signature
+     * ```json
+     * {
+     *   "data": {
+     *     "claims": {
+     *       "aal": "aal1",
+     *       "amr": [{
+     *         "method": "email",
+     *         "timestamp": 1715766000
+     *       }],
+     *       "app_metadata": {},
+     *       "aud": "authenticated",
+     *       "email": "example@email.com",
+     *       "exp": 1715769600,
+     *       "iat": 1715766000,
+     *       "is_anonymous": false,
+     *       "iss": "https://project-id.supabase.co/auth/v1",
+     *       "phone": "+13334445555",
+     *       "role": "authenticated",
+     *       "session_id": "11111111-1111-1111-1111-111111111111",
+     *       "sub": "11111111-1111-1111-1111-111111111111",
+     *       "user_metadata": {}
+     *     },
+     *     "header": {
+     *       "alg": "RS256",
+     *       "typ": "JWT",
+     *       "kid": "11111111-1111-1111-1111-111111111111"
+     *     },
+     *     "signature": [/** Uint8Array *\/],
+     *   },
+     *   "error": null
+     * }
+     * ```
      */
     getClaims(jwt?: string, options?: {
         /**