From 31d3d4461b3c3bb1a418f07c3ab5102e1ccb90c6 Mon Sep 17 00:00:00 2001 From: dshukertjr <18113850+dshukertjr@users.noreply.github.com> Date: Thu, 13 Oct 2022 15:36:47 +0900 Subject: [PATCH] docs: updates auth methods of flutter sdk v1.0 --- apps/reference/nav/supabase_dart_sidebars.js | 10 +- spec/supabase_dart_v1.yml | 189 ++++++++++++++----- 2 files changed, 154 insertions(+), 45 deletions(-) diff --git a/apps/reference/nav/supabase_dart_sidebars.js b/apps/reference/nav/supabase_dart_sidebars.js index 6d68e2458b0..b98e3b02558 100644 --- a/apps/reference/nav/supabase_dart_sidebars.js +++ b/apps/reference/nav/supabase_dart_sidebars.js @@ -14,10 +14,14 @@ const sidebars = { label: 'Auth', items: [ 'generated/auth-signup', - 'generated/auth-signin', - 'generated/auth-signinwithprovider', + 'generated/auth-signinwithpassword', + 'generated/auth-signinwithotp', + 'generated/auth-signinwithoauth', 'generated/auth-signout', - 'generated/auth-update', + 'generated/auth-verifyotp', + 'generated/auth-currentsession', + 'generated/auth-currentuser', + 'generated/auth-updateuser', 'generated/auth-onauthstatechange', 'generated/reset-password-email', ], diff --git a/spec/supabase_dart_v1.yml b/spec/supabase_dart_v1.yml index eb3dd78da95..32d27032acf 100644 --- a/spec/supabase_dart_v1.yml +++ b/spec/supabase_dart_v1.yml @@ -17,20 +17,28 @@ info: pages: auth.signUp(): + title: 'signUp()' description: | Creates a new user. notes: | - - By default, the user will need to verify their email address before logging in. If you would like to change this, you can disable "Email Confirmations" by going to Authentication -> Settings on [app.supabase.com](https://app.supabase.com) - - If "Email Confirmations" is turned on, a user is returned but session will be null - - If "Email Confirmations" is turned off, both a `user` and a `session` will be returned - - When the user confirms their email address, they will be redirected to localhost:3000 by default. To change this, you can go to Authentication -> Settings on [app.supabase.com](https://app.supabase.com) + - By default, the user needs to verify their email address before logging in. To turn this off, disable **Confirm email** in [your project](https://app.supabase.com/project/_/auth/settings). + - **Confirm email** determines if users need to confirm their email address after signing up. + - If **Confirm email** is enabled, a `user` is returned but `session` is null. + - If **Confirm email** is disabled, both a `user` and a `session` are returned. + - When the user confirms their email address, they are redirected to the [`SITE_URL`](https://supabase.com/docs/reference/auth/config#site_url) by default. You can modify your `SITE_URL` or add additional redirect URLs in [your project](https://app.supabase.com/project/_/auth/settings). + - If signUp() is called for an existing confirmed user: + - If **Confirm email** is enabled in [your project](https://app.supabase.com/project/_/auth/settings), an obfuscated/fake user object is returned. + - If **Confirm email** is disabled, the error message, `User already registered` is returned. examples: - name: Sign up. isSpotlight: true dart: | ```dart - final GotrueSessionResponse res = await supabase.auth.signUp('example@email.com', 'example-password'); - + final AuthResponse res = await supabase.auth.signUp( + email: 'example@email.com', + password: 'example-password', + ); + final Session? session = res.session; final User? user = res.user; ``` - name: Sign up with third-party providers. @@ -38,55 +46,72 @@ pages: description: | If you are using Flutter, you can sign up with OAuth providers using the [`signInWithProvider()`](/docs/reference/dart/auth-signinwithprovider) method available on `supabase_flutter`. - auth.signIn(): + auth.signInWithPassword(): + title: 'signInWithPassword()' description: | - Log in an existing user, or login via a third-party provider. + Log in an existing user using email or phone number with password. notes: | - - A user can sign up via email, phone number. - - If you provide `email` without a `password`, the user will be sent a magic link. - - The magic link's destination URL is determined by the SITE_URL config variable. To change this, you can go to Authentication -> Settings on [app.supabase.com](https://app.supabase.com) - - Similarly, if you provide `phone` without a `password`, the user will be sent a one time password. - - If you are looking to sign users in with OAuth in Flutter apps, go to [`signInWithProvider()`](/docs/reference/dart/auth-signinwithprovider). + - Requires either an email and password or a phone number and password. examples: - - name: Sign in with email. + - name: Sign in with email and password isSpotlight: true dart: | ```dart - final GotrueSessionResponse res = await supabase.auth.signIn( + final AuthResponse res = await supabase.auth.signInWithPassword( email: 'example@email.com', password: 'example-password', ); - + final Session? session = res.session; final User? user = res.user; ``` - - name: Sign in with magic link. - description: If email is provided, but no password is provided, the user will be sent a "magic link" to their email address, which they can click to open your application with a valid session. By default, a given user can only request a Magic Link once every 60 seconds. + - name: Sign in with phone and password dart: | ```dart - final GotrueSessionResponse res = await supabase.auth.signIn( - email: 'example@email.com', + final AuthResponse res = await supabase.auth.signInWithPassword( + phone: '+13334445555', + password: 'example-password', ); + final Session? session = res.session; + final User? user = res.user; ``` - - name: Get OAuth sign in URL. + auth.signInWithOtp(): + title: 'signInWithOtp()' + notes: | + - 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 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`](https://supabase.com/docs/reference/auth/config#site_url). You can modify the `SITE_URL` or add additional redirect urls in [your project](https://app.supabase.com/project/_/auth/settings). + examples: + - name: Sign in with email. + isSpotlight: true description: | - Passing provider parameter to `signIn()` will return a URL to sign your user in via OAuth. - If you are looking to sign in a user via OAuth on Flutter app, go to [`signInWithProvider()`](/docs/reference/dart/auth-signinwithprovider). + 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. + You can pass `emailRedirectTo` with dynamic link to bring the users back to your app after they click on the magic link. dart: | ```dart - final GotrueSessionResponse res = await supabase.auth.signIn( - provider: Provider.github, + await supabase.auth.signInWithOtp( + email: 'example@email.com', + emailRedirectTo: kIsWeb ? null : 'io.supabase.flutter://signin-callback/', ); - - final User? user = res.user; ``` - auth.signInWithProvider(): + - name: Sign in with SMS OTP. + description: 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. + dart: | + ```dart + await supabase.auth.signInWithOtp( + phone: 'example@email.com', + ); + ``` + auth.signInWithOAuth(): + title: 'signInWithOAuth()' description: | Signs the user in using third party OAuth providers. notes: | - - `auth.signInWithProvider()` is only available on `supabase_flutter` - - It will open the browser to the relevant login page. + - This method is used for signing in using a third-party provider. + - Supabase supports many different [third-party providers](https://supabase.com/docs/guides/auth#providers). examples: - - name: Sign in with provider. + - name: Sign in using a third-party provider isSpotlight: true dart: | ```dart @@ -120,8 +145,11 @@ pages: final String? oAuthToken = session?.providerToken; ``` auth.signOut(): + title: 'signOut()' description: | Signs out the current user, if there is a logged in user. + notes: | + - In order to use the `signOut()` method, the user needs to be signed in first. examples: - name: Sign out isSpotlight: true @@ -129,8 +157,38 @@ pages: ```dart await supabase.auth.signOut(); ``` - + auth.verifyOtp(): + title: 'verifyOtp()' + notes: | + - The `verifyOtp` method takes in different verification types. If a phone number is used, the type can either be `sms` or `phone_change`. If an email address is used, the type can be one of the following: `signup`, `magiclink`, `recovery`, `invite` or `email_change`. + - The verification type used should be determined based on the corresponding auth method called before `verifyOtp` to sign up / sign-in a user. + examples: + - name: Verify Sms One-Time Password (OTP) + isSpotlight: true + dart: | + ```dart + final AuthResponse res = await supabase.auth.verifyOTP( + type: OtpType.sms, + token: '111111', + phone: '+13334445555', + ); + final Session? session = res.session; + final User? user = res.user; + ``` + - name: Verify Signup One-Time Password (OTP) + isSpotlight: false + dart: | + ```dart + final AuthResponse res = await supabase.auth.verifyOTP( + type: OtpType.signup, + token: token, + phone: '+13334445555', + ); + final Session? session = res.session; + final User? user = res.user; + ``` auth.currentSession: + title: 'currentSession' description: | Returns the session data, if there is an active session. examples: @@ -140,8 +198,8 @@ pages: ```dart final Session? session = supabase.auth.currentSession; ``` - auth.currentUser: + title: 'currentUser' description: | Returns the user data, if there is a logged in user. examples: @@ -151,26 +209,55 @@ pages: ```dart final User? user = supabase.auth.currentUser; ``` - - auth.update(): + auth.updateUser(): + title: 'updateUser()' description: | Updates user data, if there is a logged in user. notes: | - It's generally better to store user data in a table inside your public schema (i.e. `public.users`). - Use the `update()` method if you have data which rarely changes or is specific only to the logged in user. + - 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](https://app.supabase.com/project/_/auth/settings). examples: - - name: Update a user's metadata. + - name: Update the email for an authenticated user + description: Sends a "Confirm Email Change" email to the new email address. isSpotlight: true dart: | ```dart - final GotrueUserResponse res = await supabase.auth.update( - UserAttributes(data: {'hello': 'world'}), + final UserResponse res = await supabase.updateUser( + UserAttributes( + email: 'example@email.com', + ), ); + final User? updatedUser = res.user; + ``` + - name: Update the password for an authenticated user + isSpotlight: false + dart: | + ```dart + final UserResponse res = await supabase.updateUser( + UserAttributes( + password: 'new password', + ), + ); + final User? updatedUser = res.user; + ``` + - name: Update the user's metadata + isSpotlight: true + dart: | + ```dart + final UserResponse res = await supabase.updateUser( + UserAttributes( + data: { 'hello': 'world' }, + ), + ); + final User? updatedUser = res.user; ``` - auth.onAuthStateChange(): + title: 'onAuthStateChange()' description: | Receive a notification every time an auth event happens. + notes: | + - Types of auth events: `AuthChangeEvent.passwordRecovery`, `AuthChangeEvent.signedIn`, `AuthChangeEvent.signedOut`, `AuthChangeEvent.tokenRefreshed`, `AuthChangeEvent.userUpdated`and `AuthChangeEvent.userDeleted` examples: - name: Listen to auth changes isSpotlight: true @@ -178,12 +265,30 @@ pages: ```dart final subscription = supabase.auth.onAuthStateChange( (event, session) { - print(session?.user?.id); + print(session?.user.id); // handle auth state change }, ); ``` + - name: Listen to a specific event + dart: | + ```dart + final subscription = supabase.auth.onAuthStateChange( + (event, session) { + if (event == AuthChangeEvent.signedIn) { + print(session?.user.id); + // handle signIn + } + }, + ); + ``` + - name: Unsubscribe from auth subscription + dart: | + ```dart + final subscription = supabase.auth.onAuthStateChange((event, session) {}); + subscription.data?.unsubscribe(); + ``` Reset Password (Email): description: | Sends a reset request to an email address.