fix: prettify types and improved typesafety for MFA methods (#1116)

## What kind of change does this PR introduce?

This is a preparatory PR for adding webauthn support, which will have
different params/responses across the
`client.mfa.{enroll/challenge/verify}()` methods.

At the moment, some parameters in the calls are present in the type even
when they are not valid for that factor/method type, and the response
signature that the function returns does not match what's actually being
returned.

Also, in some instances of the types returned, we can assert some values
in the return types as being one property of the valid union types in
that property, for example:

in the call to `client.mfa.listFactors()` an object returns which
contains:`

```json
all: [],
totp: [],
phone: [],
```

If the developer tries to iterate through this list, the `factor_type`
will be a union of all the possible values in `.all`, and status will be
`verified | unverified` which is correct.
but in `.phone`, we *know* that it's of type `phone` and that its status
is `verified`, thus, we can assert this in the type, the `Factor`
signature has been updated to accept 2 generics (which are optional),
which enable us to set specific shapes in different parts of the
library, some other examples:

- In `.enroll()`, we *know* for a *fact* that the `.type()` of the
factor will match the `factorType` that was passed in the function call,
- Similarly, in the `AuthMFAChallengeResponse`, we *know* for a fact
that the `.type` property will always be `totp` or `phone` based on what
parameters were passed.

I believe these type revamps greately enhance the Developer Experience &
enable the developer to not make any mistakes while accessing those
fields.

It will also enable us to add specific documentation/links that will
appear in intellisense depending on which parameters were passed to each
function.

## What is the current behavior?

Most calls to the backend result in either:

```typescript
type ExampleCalltoT = {data: T, error: null} | {data: null, error: AuthError}
```

or

```typescript
type ExampleCalltoT = {data: T, error: null} | {data: ...keys of T set to null, error: AuthError}
```

Also, there was no distinction in calls to `.enroll()` and
`.challenge()`

## What is the new behavior?

- Consolidate response patterns into `RequestResult<T>` and
`RequestResultSafeDestructure<T>`
- Provide better type inference and IDE support with `Prettify<T>`
utility
- Add specific overloads to each function so that all the possible
parameters show up in the IDE, then narrow down as soon as you lock into
a specific parameter.
- Update AMR Methods to include everything that's supported by the
GoTrue backend.

### Key improvements

1. **Generic response utilities**:
   - `RequestResult<T>` - Standard result type with data/error pattern
- `RequestResultSafeDestructure<T>` - Allows safe destructuring with
null safety
- `Prettify<T>` - Improves IDE hover experience by resolving mapped
types

2. **Enhanced type safety**:
   - Stronger typing for MFA factor types using discriminated unions
   - Better type narrowing for factor verification status
   - Consistent error type handling across all responses

3. **Internally breaking change**:
- `_callRefreshToken` now returns `{ data: Session, error: null }`
instead of `{ session: Session, error: null }`, for consistency, this
will not affect users as it's an internal utility (tests have been
adjusted to accomodate this)

## Additional context

This refactoring improves developer experience by:

- Making response types more predictable and easier to work with
- Providing better IntelliSense/autocomplete in IDEs
- Reducing the likelihood of type-related bugs
- Making the codebase more maintainable

All existing tests pass with minimal adjustments to accommodate the
internal API change, and to prepare for the next PR here that adds
webauthn types, which require that some function calls have distinct
parameters/responses to not confuse users and guide them to use the
library correctly using the TYPES as a source of truth, so the developer
can use the api naturally just through the types.

Author: Bewinxed

packages/core/auth-js/src/GoTrueClient.ts

@@ -55,7 +55,7 @@ import { polyfillGlobalThis } from './lib/polyfills'
 import { version } from './lib/version'
 import { LockAcquireTimeoutError, navigatorLock } from './lib/locks'
 
-import type {
+import {
   AuthChangeEvent,
   AuthResponse,
   AuthResponsePassword,
@@ -113,6 +113,8 @@ import type {
   Web3Credentials,
   EthereumWeb3Credentials,
   EthereumWallet,
+  FactorType,
+  FactorTypes,
 } from './lib/types'
 import { stringToUint8Array, bytesToBase64URL } from './lib/base64url'
 import {
@@ -1578,7 +1580,7 @@ export default class GoTrueClient {
         return { data: { session: currentSession }, error: null }
       }
 
-      const { session, error } = await this._callRefreshToken(currentSession.refresh_token)
+      const { data: session, error } = await this._callRefreshToken(currentSession.refresh_token)
       if (error) {
         return { data: { session: null }, error }
       }
@@ -1757,7 +1759,7 @@ export default class GoTrueClient {
       }
 
       if (hasExpired) {
-        const { session: refreshedSession, error } = await this._callRefreshToken(
+        const { data: refreshedSession, error } = await this._callRefreshToken(
           currentSession.refresh_token
         )
         if (error) {
@@ -1827,7 +1829,7 @@ export default class GoTrueClient {
           throw new AuthSessionMissingError()
         }
 
-        const { session, error } = await this._callRefreshToken(currentSession.refresh_token)
+        const { data: session, error } = await this._callRefreshToken(currentSession.refresh_token)
         if (error) {
           return { data: { user: null, session: null }, error: error }
         }
@@ -1963,7 +1965,7 @@ export default class GoTrueClient {
         expires_in: expiresIn,
         expires_at: expiresAt,
         refresh_token,
-        token_type,
+        token_type: token_type as 'bearer',
         user: data.user,
       }
 
@@ -2478,7 +2480,7 @@ export default class GoTrueClient {
       await this._saveSession(data.session)
       await this._notifyAllSubscribers('TOKEN_REFRESHED', data.session)
 
-      const result = { session: data.session, error: null }
+      const result = { data: data.session, error: null }
 
       this.refreshingDeferred.resolve(result)
 
@@ -2487,7 +2489,7 @@ export default class GoTrueClient {
       this._debug(debugName, 'error', error)
 
       if (isAuthError(error)) {
-        const result = { session: null, error }
+        const result = { data: null, error }
 
         if (!isAuthRetryableFetchError(error)) {
           await this._removeSession()
@@ -2997,7 +2999,9 @@ export default class GoTrueClient {
   /**
    * {@see GoTrueMFAApi#challenge}
    */
-  private async _challenge(params: MFAChallengeParams): Promise<AuthMFAChallengeResponse> {
+  private async _challenge<T extends FactorType>(
+    params: MFAChallengeParams
+  ): Promise<AuthMFAChallengeResponse<T>> {
     return this._acquireLock(-1, async () => {
       try {
         return await this._useSession(async (result) => {
@@ -3011,7 +3015,7 @@ export default class GoTrueClient {
             'POST',
             `${this.url}/factors/${params.factorId}/challenge`,
             {
-              body: { channel: params.channel },
+              body: 'channel' in params ? { channel: params.channel } : {},
               headers: this.headers,
               jwt: sessionData?.session?.access_token,
             }
@@ -3062,20 +3066,21 @@ export default class GoTrueClient {
       return { data: null, error: userError }
     }
 
-    const factors = user?.factors || []
-    const totp = factors.filter(
-      (factor) => factor.factor_type === 'totp' && factor.status === 'verified'
-    )
-    const phone = factors.filter(
-      (factor) => factor.factor_type === 'phone' && factor.status === 'verified'
-    )
+    const data: AuthMFAListFactorsResponse['data'] = {
+      all: [],
+      phone: [],
+      totp: [],
+    }
+
+    for (const factor of user?.factors ?? []) {
+      data.all.push(factor)
+      if (factor.status === 'verified') {
+        ;(data[factor.factor_type] as typeof factor[]).push(factor)
+      }
+    }
 
     return {
-      data: {
-        all: factors,
-        totp,
-        phone,
-      },
+      data,
       error: null,
     }
   }

packages/core/auth-js/src/lib/errors.ts

@@ -147,7 +147,7 @@ export class AuthWeakPasswordError extends CustomAuthError {
    */
   reasons: WeakPasswordReasons[]
 
-  constructor(message: string, status: number, reasons: string[]) {
+  constructor(message: string, status: number, reasons: WeakPasswordReasons[]) {
     super(message, 'AuthWeakPasswordError', status, 'weak_password')
 
     this.reasons = reasons