feat: add getUserByEmail function to GoTrueAdminApi

src/GoTrueAdminApi.ts

@@ -20,7 +20,7 @@ import {
   AuthMFAAdminListFactorsResponse,
   PageParams,
 } from './lib/types'
-import { AuthError, isAuthError } from './lib/errors'
+import { AuthError, CustomAuthError, isAuthError, UserNotFoundError } from './lib/errors'
 
 export default class GoTrueAdminApi {
   /** Contains all MFA administration methods. */
@@ -233,6 +233,38 @@ export default class GoTrueAdminApi {
     }
   }
 
+  /**
+   * Get user by email.
+   *
+   * @param email The user's email
+   *
+   * This function should only be called on a server. Never expose your `service_role` key in the browser.
+   */
+  async getUserByEmail(email: string): Promise<UserResponse> {
+    try {
+      const response = await _request(this.fetch, 'GET', `${this.url}/admin/users`, {
+        headers: this.headers,
+        xform: _userResponse,
+        query: {
+          filter: email,
+        },
+      })
+
+      const users = response?.data?.user?.users || []
+      if (users.length > 0) {
+        return { data: { user: users[0] }, error: null }
+      }
+
+      throw new UserNotFoundError()
+    } catch (error) {
+      if (isAuthError(error)) {
+        return { data: { user: null }, error }
+      }
+
+      throw error
+    }
+  }
+
   /**
    * Updates the user data.
    *

src/lib/errors.ts

@@ -73,6 +73,12 @@ export function isAuthSessionMissingError(error: any): error is AuthSessionMissi
   return isAuthError(error) && error.name === 'AuthSessionMissingError'
 }
 
+export class UserNotFoundError extends CustomAuthError {
+  constructor() {
+    super('User not found', 'UserNotFoundError', 404, 'user_not_found')
+  }
+}
+
 export class AuthInvalidTokenResponseError extends CustomAuthError {
   constructor() {
     super('Auth session or user missing', 'AuthInvalidTokenResponseError', 500, undefined)

src/lib/types.ts

@@ -1,4 +1,4 @@
-import { AuthError } from './errors'
+import { AuthError, CustomAuthError } from './errors'
 import { Fetch } from './fetch'
 
 /** One of the providers supported by GoTrue. */
@@ -224,6 +224,12 @@ export type UserResponse =
       }
       error: AuthError
     }
+  | {
+      data: {
+        user: null
+      }
+      error: CustomAuthError
+    }
 
 export interface Session {
   /**

test/GoTrueApi.test.ts

@@ -136,6 +136,22 @@ describe('GoTrueAdminApi', () => {
       expect(foundUser).not.toBeUndefined()
       expect(foundUser.user?.email).toEqual(email)
     })
+
+    test('getUserByEmail() should a registered user given its email', async () => {
+      const { email } = mockUserCredentials()
+      const { error: createError, data: createdUser } = await createNewUserWithEmail({ email })
+
+      expect(createError).toBeNull()
+      expect(createdUser.user).not.toBeUndefined()
+
+      const { error: foundError, data: foundUser } = await serviceRoleApiClient.getUserByEmail(
+        email
+      )
+
+      expect(foundError).toBeNull()
+      expect(foundUser).not.toBeUndefined()
+      expect(foundUser.user?.email).toEqual(email)
+    })
   })
 
   describe('User updates', () => {