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

package/src/GoTrueAdminApi.ts

@@ -106,6 +106,8 @@ export default class GoTrueAdminApi {
    * Removes a logged-in session.
    * @param jwt A valid, logged-in JWT.
    * @param scope The logout sope.
+   *
+   * @category Auth
    */
   async signOut(
     jwt: string,
@@ -137,6 +139,64 @@ export default class GoTrueAdminApi {
    * Sends an invite link to an email address.
    * @param email The email address of the user.
    * @param options Additional options to be included when inviting.
+   *
+   * @category Auth
+   *
+   * @remarks
+   * - Sends an invite link to the user's email address.
+   * - The `inviteUserByEmail()` method is typically used by administrators to invite users to join the application.
+   * - Note that PKCE is not supported when using `inviteUserByEmail`. This is because the browser initiating the invite is often different from the browser accepting the invite which makes it difficult to provide the security guarantees required of the PKCE flow.
+   *
+   * @example Invite a user
+   * ```js
+   * const { data, error } = await supabase.auth.admin.inviteUserByEmail('email@example.com')
+   * ```
+   *
+   * @exampleResponse Invite a user
+   * ```json
+   * {
+   *   "data": {
+   *     "user": {
+   *       "id": "11111111-1111-1111-1111-111111111111",
+   *       "aud": "authenticated",
+   *       "role": "authenticated",
+   *       "email": "example@email.com",
+   *       "invited_at": "2024-01-01T00:00:00Z",
+   *       "phone": "",
+   *       "confirmation_sent_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",
+   *       "is_anonymous": false
+   *     }
+   *   },
+   *   "error": null
+   * }
+   * ```
    */
   async inviteUserByEmail(
     email: string,
@@ -170,6 +230,115 @@ export default class GoTrueAdminApi {
    * @param options.password User password. For signup only.
    * @param options.data Optional user metadata. For signup only.
    * @param options.redirectTo The redirect url which should be appended to the generated link
+   *
+   * @category Auth
+   *
+   * @remarks
+   * - The following types can be passed into `generateLink()`: `signup`, `magiclink`, `invite`, `recovery`, `email_change_current`, `email_change_new`, `phone_change`.
+   * - `generateLink()` only generates the email link for `email_change_email` if the **Secure email change** is enabled in your project's [email auth provider settings](/dashboard/project/_/auth/providers).
+   * - `generateLink()` handles the creation of the user for `signup`, `invite` and `magiclink`.
+   *
+   * @example Generate a signup link
+   * ```js
+   * const { data, error } = await supabase.auth.admin.generateLink({
+   *   type: 'signup',
+   *   email: 'email@example.com',
+   *   password: 'secret'
+   * })
+   * ```
+   *
+   * @exampleResponse Generate a signup link
+   * ```json
+   * {
+   *   "data": {
+   *     "properties": {
+   *       "action_link": "<LINK_TO_SEND_TO_USER>",
+   *       "email_otp": "999999",
+   *       "hashed_token": "<HASHED_TOKEN",
+   *       "redirect_to": "<REDIRECT_URL>",
+   *       "verification_type": "signup"
+   *     },
+   *     "user": {
+   *       "id": "11111111-1111-1111-1111-111111111111",
+   *       "aud": "authenticated",
+   *       "role": "authenticated",
+   *       "email": "email@example.com",
+   *       "phone": "",
+   *       "confirmation_sent_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": "email@example.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"
+   *         }
+   *       ],
+   *       "created_at": "2024-01-01T00:00:00Z",
+   *       "updated_at": "2024-01-01T00:00:00Z",
+   *       "is_anonymous": false
+   *     }
+   *   },
+   *   "error": null
+   * }
+   * ```
+   *
+   * @example Generate an invite link
+   * ```js
+   * const { data, error } = await supabase.auth.admin.generateLink({
+   *   type: 'invite',
+   *   email: 'email@example.com'
+   * })
+   * ```
+   *
+   * @example Generate a magic link
+   * ```js
+   * const { data, error } = await supabase.auth.admin.generateLink({
+   *   type: 'magiclink',
+   *   email: 'email@example.com'
+   * })
+   * ```
+   *
+   * @example Generate a recovery link
+   * ```js
+   * const { data, error } = await supabase.auth.admin.generateLink({
+   *   type: 'recovery',
+   *   email: 'email@example.com'
+   * })
+   * ```
+   *
+   * @example Generate links to change current email address
+   * ```js
+   * // generate an email change link to be sent to the current email address
+   * const { data, error } = await supabase.auth.admin.generateLink({
+   *   type: 'email_change_current',
+   *   email: 'current.email@example.com',
+   *   newEmail: 'new.email@example.com'
+   * })
+   *
+   * // generate an email change link to be sent to the new email address
+   * const { data, error } = await supabase.auth.admin.generateLink({
+   *   type: 'email_change_new',
+   *   email: 'current.email@example.com',
+   *   newEmail: 'new.email@example.com'
+   * })
+   * ```
    */
   async generateLink(params: GenerateLinkParams): Promise<GenerateLinkResponse> {
     try {
@@ -204,6 +373,81 @@ export default class GoTrueAdminApi {
   /**
    * Creates a new user.
    * This function should only be called on a server. Never expose your `service_role` key in the browser.
+   *
+   * @category Auth
+   *
+   * @remarks
+   * - To confirm the user's email address or phone number, set `email_confirm` or `phone_confirm` to true. Both arguments default to false.
+   * - `createUser()` will not send a confirmation email to the user. You can use [`inviteUserByEmail()`](/docs/reference/javascript/auth-admin-inviteuserbyemail) if you want to send them an email invite instead.
+   * - If you are sure that the created user's email or phone number is legitimate and verified, you can set the `email_confirm` or `phone_confirm` param to `true`.
+   *
+   * @example With custom user metadata
+   * ```js
+   * const { data, error } = await supabase.auth.admin.createUser({
+   *   email: 'user@email.com',
+   *   password: 'password',
+   *   user_metadata: { name: 'Yoda' }
+   * })
+   * ```
+   *
+   * @exampleResponse With custom user metadata
+   * ```json
+   * {
+   *   data: {
+   *     user: {
+   *       id: '1',
+   *       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: {},
+   *       user_metadata: {},
+   *       identities: [
+   *         {
+   *           "identity_id": "22222222-2222-2222-2222-222222222222",
+   *           "id": "1",
+   *           "user_id": "1",
+   *           "identity_data": {
+   *             "email": "example@email.com",
+   *             "email_verified": true,
+   *             "phone_verified": false,
+   *             "sub": "1"
+   *           },
+   *           "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"
+   *         },
+   *       ],
+   *       created_at: '2024-01-01T00:00:00Z',
+   *       updated_at: '2024-01-01T00:00:00Z',
+   *       is_anonymous: false,
+   *     }
+   *   }
+   *   error: null
+   * }
+   * ```
+   *
+   * @example Auto-confirm the user's email
+   * ```js
+   * const { data, error } = await supabase.auth.admin.createUser({
+   *   email: 'user@email.com',
+   *   email_confirm: true
+   * })
+   * ```
+   *
+   * @example Auto-confirm the user's phone number
+   * ```js
+   * const { data, error } = await supabase.auth.admin.createUser({
+   *   phone: '1234567890',
+   *   phone_confirm: true
+   * })
+   * ```
    */
   async createUser(attributes: AdminUserAttributes): Promise<UserResponse> {
     try {
@@ -226,6 +470,24 @@ export default class GoTrueAdminApi {
    *
    * This function should only be called on a server. Never expose your `service_role` key in the browser.
    * @param params An object which supports `page` and `perPage` as numbers, to alter the paginated results.
+   *
+   * @category Auth
+   *
+   * @remarks
+   * - Defaults to return 50 users per page.
+   *
+   * @example Get a page of users
+   * ```js
+   * const { data: { users }, error } = await supabase.auth.admin.listUsers()
+   * ```
+   *
+   * @example Paginated list of users
+   * ```js
+   * const { data: { users }, error } = await supabase.auth.admin.listUsers({
+   *   page: 1,
+   *   perPage: 1000
+   * })
+   * ```
    */
   async listUsers(
     params?: PageParams
@@ -273,6 +535,60 @@ export default class GoTrueAdminApi {
    * @param uid The user's unique identifier
    *
    * This function should only be called on a server. Never expose your `service_role` key in the browser.
+   *
+   * @category Auth
+   *
+   * @remarks
+   * - Fetches the user object from the database based on the user's id.
+   * - The `getUserById()` method requires the user's id which maps to the `auth.users.id` column.
+   *
+   * @example Fetch the user object using the access_token jwt
+   * ```js
+   * const { data, error } = await supabase.auth.admin.getUserById(1)
+   * ```
+   *
+   * @exampleResponse Fetch the user object using the access_token jwt
+   * ```json
+   * {
+   *   data: {
+   *     user: {
+   *       id: '1',
+   *       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: {},
+   *       user_metadata: {},
+   *       identities: [
+   *         {
+   *           "identity_id": "22222222-2222-2222-2222-222222222222",
+   *           "id": "1",
+   *           "user_id": "1",
+   *           "identity_data": {
+   *             "email": "example@email.com",
+   *             "email_verified": true,
+   *             "phone_verified": false,
+   *             "sub": "1"
+   *           },
+   *           "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"
+   *         },
+   *       ],
+   *       created_at: '2024-01-01T00:00:00Z',
+   *       updated_at: '2024-01-01T00:00:00Z',
+   *       is_anonymous: false,
+   *     }
+   *   }
+   *   error: null
+   * }
+   * ```
    */
   async getUserById(uid: string): Promise<UserResponse> {
     validateUUID(uid)
@@ -322,6 +638,117 @@ export default class GoTrueAdminApi {
    *
    * @see {@link GoTrueClient.refreshSession} for syncing admin changes to the client
    * @see {@link GoTrueClient.updateUser} for client-side user updates (triggers listeners automatically)
+   *
+   * @category Auth
+   *
+   * @example Updates a user's email
+   * ```js
+   * const { data: user, error } = await supabase.auth.admin.updateUserById(
+   *   '11111111-1111-1111-1111-111111111111',
+   *   { email: 'new@email.com' }
+   * )
+   * ```
+   *
+   * @exampleResponse Updates a user's email
+   * ```json
+   * {
+   *   "data": {
+   *     "user": {
+   *       "id": "11111111-1111-1111-1111-111111111111",
+   *       "aud": "authenticated",
+   *       "role": "authenticated",
+   *       "email": "new@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 Updates a user's password
+   * ```js
+   * const { data: user, error } = await supabase.auth.admin.updateUserById(
+   *   '6aa5d0d4-2a9f-4483-b6c8-0cf4c6c98ac4',
+   *   { password: 'new_password' }
+   * )
+   * ```
+   *
+   * @example Updates a user's metadata
+   * ```js
+   * const { data: user, error } = await supabase.auth.admin.updateUserById(
+   *   '6aa5d0d4-2a9f-4483-b6c8-0cf4c6c98ac4',
+   *   { user_metadata: { hello: 'world' } }
+   * )
+   * ```
+   *
+   * @example Updates a user's app_metadata
+   * ```js
+   * const { data: user, error } = await supabase.auth.admin.updateUserById(
+   *   '6aa5d0d4-2a9f-4483-b6c8-0cf4c6c98ac4',
+   *   { app_metadata: { plan: 'trial' } }
+   * )
+   * ```
+   *
+   * @example Confirms a user's email address
+   * ```js
+   * const { data: user, error } = await supabase.auth.admin.updateUserById(
+   *   '6aa5d0d4-2a9f-4483-b6c8-0cf4c6c98ac4',
+   *   { email_confirm: true }
+   * )
+   * ```
+   *
+   * @example Confirms a user's phone number
+   * ```js
+   * const { data: user, error } = await supabase.auth.admin.updateUserById(
+   *   '6aa5d0d4-2a9f-4483-b6c8-0cf4c6c98ac4',
+   *   { phone_confirm: true }
+   * )
+   * ```
+   *
+   * @example Ban a user for 100 years
+   * ```js
+   * const { data: user, error } = await supabase.auth.admin.updateUserById(
+   *   '6aa5d0d4-2a9f-4483-b6c8-0cf4c6c98ac4',
+   *   { ban_duration: '876000h' }
+   * )
+   * ```
    */
   async updateUserById(uid: string, attributes: AdminUserAttributes): Promise<UserResponse> {
     validateUUID(uid)
@@ -349,6 +776,28 @@ export default class GoTrueAdminApi {
    * Defaults to false for backward compatibility.
    *
    * This function should only be called on a server. Never expose your `service_role` key in the browser.
+   *
+   * @category Auth
+   *
+   * @remarks
+   * - The `deleteUser()` method requires the user's ID, which maps to the `auth.users.id` column.
+   *
+   * @example Removes a user
+   * ```js
+   * const { data, error } = await supabase.auth.admin.deleteUser(
+   *   '715ed5db-f090-4b8c-a067-640ecee36aa0'
+   * )
+   * ```
+   *
+   * @exampleResponse Removes a user
+   * ```json
+   * {
+   *   "data": {
+   *     "user": {}
+   *   },
+   *   "error": null
+   * }
+   * ```
    */
   async deleteUser(id: string, shouldSoftDelete = false): Promise<UserResponse> {
     validateUUID(id)