fix(auth): Better type hierarchies for Auth API (#1294)

* fix(auth): Better type heirarchies for Auth API

* fix: Moved factorId back to the base types

* fix: Updated API report

* fix: Fixed a grammar error in comment

* fix: Update to comment text

etc/firebase-admin.api.md

@@ -113,11 +113,7 @@ export namespace auth {
         tenantManager(): TenantManager;
     }
     export type AuthFactorType = 'phone';
-    export interface AuthProviderConfig {
-        displayName?: string;
-        enabled: boolean;
-        providerId: string;
-    }
+    export type AuthProviderConfig = SAMLAuthProviderConfig | OIDCAuthProviderConfig;
     export interface AuthProviderConfigFilter {
         maxResults?: number;
         pageToken?: string;
@@ -151,11 +147,23 @@ export namespace auth {
         verifyIdToken(idToken: string, checkRevoked?: boolean): Promise<DecodedIdToken>;
         verifySessionCookie(sessionCookie: string, checkForRevocation?: boolean): Promise<DecodedIdToken>;
     }
-    export interface CreateMultiFactorInfoRequest {
+    export interface BaseAuthProviderConfig {
+        displayName?: string;
+        enabled: boolean;
+        providerId: string;
+    }
+    export interface BaseCreateMultiFactorInfoRequest {
+        displayName?: string;
+        factorId: string;
+    }
+    export interface BaseUpdateMultiFactorInfoRequest {
         displayName?: string;
+        enrollmentTime?: string;
         factorId: string;
+        uid?: string;
     }
-    export interface CreatePhoneMultiFactorInfoRequest extends CreateMultiFactorInfoRequest {
+    export type CreateMultiFactorInfoRequest = CreatePhoneMultiFactorInfoRequest;
+    export interface CreatePhoneMultiFactorInfoRequest extends BaseCreateMultiFactorInfoRequest {
         phoneNumber: string;
     }
     export interface CreateRequest extends UpdateRequest {
@@ -245,7 +253,7 @@ export namespace auth {
         code?: boolean;
         idToken?: boolean;
     }
-    export interface OIDCAuthProviderConfig extends AuthProviderConfig {
+    export interface OIDCAuthProviderConfig extends BaseAuthProviderConfig {
         clientId: string;
         clientSecret?: string;
         issuer: string;
@@ -272,7 +280,7 @@ export namespace auth {
         // (undocumented)
         providerUid: string;
     }
-    export interface SAMLAuthProviderConfig extends AuthProviderConfig {
+    export interface SAMLAuthProviderConfig extends BaseAuthProviderConfig {
         callbackURL?: string;
         idpEntityId: string;
         rpEntityId: string;
@@ -323,13 +331,8 @@ export namespace auth {
     }
     // (undocumented)
     export type UpdateAuthProviderRequest = SAMLUpdateAuthProviderRequest | OIDCUpdateAuthProviderRequest;
-    export interface UpdateMultiFactorInfoRequest {
-        displayName?: string;
-        enrollmentTime?: string;
-        factorId: string;
-        uid?: string;
-    }
-    export interface UpdatePhoneMultiFactorInfoRequest extends UpdateMultiFactorInfoRequest {
+    export type UpdateMultiFactorInfoRequest = UpdatePhoneMultiFactorInfoRequest;
+    export interface UpdatePhoneMultiFactorInfoRequest extends BaseUpdateMultiFactorInfoRequest {
         phoneNumber: string;
     }
     export interface UpdateRequest {

src/auth/auth-api-request.ts

@@ -1480,7 +1480,12 @@ export abstract class AbstractAuthRequestHandler {
     }
 
     // Build the signupNewUser request.
-    const request: any = deepCopy(properties);
+    type SignUpNewUserRequest = CreateRequest & {
+      photoUrl?: string | null;
+      localId?: string;
+      mfaInfo?: AuthFactorInfo[];
+    };
+    const request: SignUpNewUserRequest = deepCopy(properties);
     // Rewrite photoURL to photoUrl.
     if (typeof request.photoURL !== 'undefined') {
       request.photoUrl = request.photoURL;
@@ -1496,14 +1501,14 @@ export abstract class AbstractAuthRequestHandler {
       if (validator.isNonEmptyArray(request.multiFactor.enrolledFactors)) {
         const mfaInfo: AuthFactorInfo[] = [];
         try {
-          request.multiFactor.enrolledFactors.forEach((multiFactorInfo: any) => {
+          request.multiFactor.enrolledFactors.forEach((multiFactorInfo) => {
             // Enrollment time and uid are not allowed for signupNewUser endpoint.
             // They will automatically be provisioned server side.
-            if (multiFactorInfo.enrollmentTime) {
+            if ('enrollmentTime' in multiFactorInfo) {
               throw new FirebaseAuthError(
                 AuthClientErrorCode.INVALID_ARGUMENT,
                 '"enrollmentTime" is not supported when adding second factors via "createUser()"');
-            } else if (multiFactorInfo.uid) {
+            } else if ('uid' in multiFactorInfo) {
               throw new FirebaseAuthError(
                 AuthClientErrorCode.INVALID_ARGUMENT,
                 '"uid" is not supported when adding second factors via "createUser()"');

src/auth/index.ts

@@ -112,7 +112,7 @@ export namespace auth {
   }
 
   /**
-   * Interface representing the common properties of a user enrolled second factor.
+   * Interface representing the common properties of a user-enrolled second factor.
    */
   export interface MultiFactorInfo {
 
@@ -143,7 +143,7 @@ export namespace auth {
   }
 
   /**
-   * Interface representing a phone specific user enrolled second factor.
+   * Interface representing a phone specific user-enrolled second factor.
    */
   export interface PhoneMultiFactorInfo extends MultiFactorInfo {
 
@@ -336,10 +336,10 @@ export namespace auth {
   }
 
   /**
-   * Interface representing common properties of a user enrolled second factor
+   * Interface representing common properties of a user-enrolled second factor
    * for an `UpdateRequest`.
    */
-  export interface UpdateMultiFactorInfoRequest {
+  export interface BaseUpdateMultiFactorInfoRequest {
 
     /**
      * The ID of the enrolled second factor. This ID is unique to the user. When not provided,
@@ -364,17 +364,23 @@ export namespace auth {
   }
 
   /**
-   * Interface representing a phone specific user enrolled second factor
+   * Interface representing a phone specific user-enrolled second factor
    * for an `UpdateRequest`.
    */
-  export interface UpdatePhoneMultiFactorInfoRequest extends UpdateMultiFactorInfoRequest {
+  export interface UpdatePhoneMultiFactorInfoRequest extends BaseUpdateMultiFactorInfoRequest {
 
     /**
      * The phone number associated with a phone second factor.
      */
     phoneNumber: string;
   }
 
+  /**
+   * Type representing the properties of a user-enrolled second factor
+   * for an `UpdateRequest`.
+   */
+  export type UpdateMultiFactorInfoRequest = | UpdatePhoneMultiFactorInfoRequest;
+
   /**
    * Interface representing the properties to update on the provided user.
    */
@@ -443,10 +449,10 @@ export namespace auth {
   }
 
   /**
-   * Interface representing base properties of a user enrolled second factor for a
+   * Interface representing base properties of a user-enrolled second factor for a
    * `CreateRequest`.
    */
-  export interface CreateMultiFactorInfoRequest {
+  export interface BaseCreateMultiFactorInfoRequest {
 
     /**
      * The optional display name for an enrolled second factor.
@@ -460,17 +466,23 @@ export namespace auth {
   }
 
   /**
-   * Interface representing a phone specific user enrolled second factor for a
+   * Interface representing a phone specific user-enrolled second factor for a
    * `CreateRequest`.
    */
-  export interface CreatePhoneMultiFactorInfoRequest extends CreateMultiFactorInfoRequest {
+  export interface CreatePhoneMultiFactorInfoRequest extends BaseCreateMultiFactorInfoRequest {
 
     /**
      * The phone number associated with a phone second factor.
      */
     phoneNumber: string;
   }
 
+  /**
+   * Type representing the properties of a user-enrolled second factor
+   * for a `CreateRequest`.
+   */
+  export type CreateMultiFactorInfoRequest = | CreatePhoneMultiFactorInfoRequest;
+
   /**
    * Interface representing the properties to set on a new user record to be
    * created.
@@ -1221,7 +1233,7 @@ export namespace auth {
   /**
    * The base Auth provider configuration interface.
    */
-  export interface AuthProviderConfig {
+  export interface BaseAuthProviderConfig {
 
     /**
      * The provider ID defined by the developer.
@@ -1249,7 +1261,7 @@ export namespace auth {
    * Auth provider configuration interface. A SAML provider can be created via
    * {@link auth.Auth.createProviderConfig `createProviderConfig()`}.
    */
-  export interface SAMLAuthProviderConfig extends AuthProviderConfig {
+  export interface SAMLAuthProviderConfig extends BaseAuthProviderConfig {
 
     /**
      * The SAML IdP entity identifier.
@@ -1301,7 +1313,7 @@ export namespace auth {
   export interface OAuthResponseType {
     /**
      * Whether ID token is returned from IdP's authorization endpoint.
-     */ 
+     */
     idToken?: boolean;
 
     /**
@@ -1315,7 +1327,7 @@ export namespace auth {
    * provider configuration interface. An OIDC provider can be created via
    * {@link auth.Auth.createProviderConfig `createProviderConfig()`}.
    */
-  export interface OIDCAuthProviderConfig extends AuthProviderConfig {
+  export interface OIDCAuthProviderConfig extends BaseAuthProviderConfig {
 
     /**
      * This is the required client ID used to confirm the audience of an OIDC
@@ -1347,13 +1359,19 @@ export namespace auth {
      * The OIDC provider's client secret to enable OIDC code flow.
      */
     clientSecret?: string;
-    
+
     /**
      * The OIDC provider's response object for OAuth authorization flow.
      */
     responseType?: OAuthResponseType;
   }
 
+  /**
+   * The Auth provider configuration type.
+   * {@link auth.Auth.createProviderConfig `createProviderConfig()`}.
+   */
+  export type AuthProviderConfig = SAMLAuthProviderConfig | OIDCAuthProviderConfig;
+
   /**
    * The request interface for updating a SAML Auth provider. This is used
    * when updating a SAML provider's configuration via
@@ -1440,7 +1458,7 @@ export namespace auth {
      * If not provided, the existing configuration's value is not modified.
      */
     clientSecret?: string;
-    
+
     /**
      * The OIDC provider's response object for OAuth authorization flow.
      */

test/unit/auth/auth-api-request.spec.ts

@@ -1425,12 +1425,6 @@ AUTH_REQUEST_HANDLER_TESTS.forEach((handler) => {
                 factorId: 'phone',
                 enrollmentTime: new Date().toUTCString(),
               },
-              {
-                uid: 'mfaUid2',
-                phoneNumber: '+16505550002',
-                displayName: 'Personal phone number',
-                factorId: 'phone',
-              },
             ],
           },
           customClaims: { admin: true },