fix(auth): Updated API docs for firebase-admin/auth (#1170)

Author: hiranya911

etc/firebase-admin.auth.api.md

@@ -155,14 +155,13 @@ export interface AuthProviderConfigFilter {
 }
 
 // @public
-export class BaseAuth {
+export abstract class BaseAuth {
     createCustomToken(uid: string, developerClaims?: object): Promise<string>;
     createProviderConfig(config: AuthProviderConfig): Promise<AuthProviderConfig>;
     createSessionCookie(idToken: string, sessionCookieOptions: SessionCookieOptions): Promise<string>;
     createUser(properties: CreateRequest): Promise<UserRecord>;
     deleteProviderConfig(providerId: string): Promise<void>;
     deleteUser(uid: string): Promise<void>;
-    // (undocumented)
     deleteUsers(uids: string[]): Promise<DeleteUsersResult>;
     generateEmailVerificationLink(email: string, actionCodeSettings?: ActionCodeSettings): Promise<string>;
     generatePasswordResetLink(email: string, actionCodeSettings?: ActionCodeSettings): Promise<string>;
@@ -205,7 +204,6 @@ export type CreateTenantRequest = UpdateTenantRequest;
 
 // @public
 export interface DecodedIdToken {
-    // (undocumented)
     [key: string]: any;
     aud: string;
     auth_time: number;
@@ -250,7 +248,7 @@ export interface EmailSignInProviderConfig {
     passwordRequired?: boolean;
 }
 
-// @public (undocumented)
+// @public
 export function getAuth(app?: App): Auth;
 
 // @public
@@ -280,7 +278,7 @@ export interface ListUsersResult {
     users: UserRecord[];
 }
 
-// @public (undocumented)
+// @public
 export interface MultiFactorConfig {
     factorIds?: AuthFactorType[];
     state: MultiFactorConfigState;
@@ -296,20 +294,15 @@ export interface MultiFactorCreateSettings {
 
 // @public
 export abstract class MultiFactorInfo {
-    // (undocumented)
     readonly displayName?: string;
-    // (undocumented)
     readonly enrollmentTime?: string;
-    // (undocumented)
     readonly factorId: string;
-    toJSON(): any;
-    // (undocumented)
+    toJSON(): object;
     readonly uid: string;
 }
 
 // @public
 export class MultiFactorSettings {
-    // (undocumented)
     enrolledFactors: MultiFactorInfo[];
     toJSON(): any;
 }
@@ -341,9 +334,8 @@ export interface PhoneIdentifier {
 
 // @public
 export class PhoneMultiFactorInfo extends MultiFactorInfo {
-    // (undocumented)
     readonly phoneNumber: string;
-    toJSON(): any;
+    toJSON(): object;
 }
 
 // @public
@@ -381,15 +373,10 @@ export interface SessionCookieOptions {
 
 // @public
 export class Tenant {
-    // (undocumented)
     readonly displayName?: string;
-    // (undocumented)
     get emailSignInConfig(): EmailSignInProviderConfig | undefined;
-    // (undocumented)
     get multiFactorConfig(): MultiFactorConfig | undefined;
-    // (undocumented)
     readonly tenantId: string;
-    // (undocumented)
     readonly testPhoneNumbers?: {
         [phoneNumber: string]: string;
     };
@@ -399,7 +386,6 @@ export class Tenant {
 // @public
 export class TenantAwareAuth extends BaseAuth {
     createSessionCookie(idToken: string, sessionCookieOptions: SessionCookieOptions): Promise<string>;
-    // (undocumented)
     readonly tenantId: string;
     verifyIdToken(idToken: string, checkRevoked?: boolean): Promise<DecodedIdToken>;
     verifySessionCookie(sessionCookie: string, checkRevoked?: boolean): Promise<DecodedIdToken>;
@@ -505,27 +491,19 @@ export interface UserImportResult {
 
 // @public
 export class UserInfo {
-    // (undocumented)
     readonly displayName: string;
-    // (undocumented)
     readonly email: string;
-    // (undocumented)
     readonly phoneNumber: string;
-    // (undocumented)
     readonly photoURL: string;
-    // (undocumented)
     readonly providerId: string;
     toJSON(): object;
-    // (undocumented)
     readonly uid: string;
 }
 
 // @public
 export class UserMetadata {
-    // (undocumented)
     readonly creationTime: string;
     readonly lastRefreshTime: string | null;
-    // (undocumented)
     readonly lastSignInTime: string;
     toJSON(): object;
 }
@@ -548,38 +526,23 @@ export interface UserProviderRequest {
 
 // @public
 export class UserRecord {
-    // (undocumented)
-    readonly customClaims: {
+    readonly customClaims?: {
         [key: string]: any;
     };
-    // (undocumented)
     readonly disabled: boolean;
-    // (undocumented)
-    readonly displayName: string;
-    // (undocumented)
-    readonly email: string;
-    // (undocumented)
+    readonly displayName?: string;
+    readonly email?: string;
     readonly emailVerified: boolean;
-    // (undocumented)
     readonly metadata: UserMetadata;
-    // (undocumented)
     readonly multiFactor?: MultiFactorSettings;
-    // (undocumented)
     readonly passwordHash?: string;
-    // (undocumented)
     readonly passwordSalt?: string;
-    // (undocumented)
-    readonly phoneNumber: string;
-    // (undocumented)
-    readonly photoURL: string;
-    // (undocumented)
+    readonly phoneNumber?: string;
+    readonly photoURL?: string;
     readonly providerData: UserInfo[];
-    // (undocumented)
     readonly tenantId?: string | null;
     toJSON(): object;
-    // (undocumented)
     readonly tokensValidAfterTime?: string;
-    // (undocumented)
     readonly uid: string;
 }
 

src/auth/auth-config.ts

@@ -406,6 +406,11 @@ export type AuthFactorType = 'phone';
  */
 export type MultiFactorConfigState = 'ENABLED' | 'DISABLED';
 
+/**
+ * Interface representing a multi-factor configuration.
+ * This can be used to define whether multi-factor authentication is enabled
+ * or disabled and the list of second factor challenges that are supported.
+ */
 export interface MultiFactorConfig {
   /**
    * The multi-factor config state.
@@ -584,7 +589,7 @@ export function validateTestPhoneNumbers(
 }
 
 /**
- * The email sign in configuration.
+ * The email sign in provider configuration.
  */
 export interface EmailSignInProviderConfig {
   /**
@@ -1010,7 +1015,7 @@ export class SAMLConfig implements SAMLAuthProviderConfig {
   /**
    * The SAMLConfig constructor.
    *
-   * @param {any} response The server side response used to initialize the SAMLConfig object.
+   * @param response The server side response used to initialize the SAMLConfig object.
    * @constructor
    */
   constructor(response: SAMLConfigServerResponse) {
@@ -1211,7 +1216,7 @@ export class OIDCConfig implements OIDCAuthProviderConfig {
   /**
    * The OIDCConfig constructor.
    *
-   * @param {any} response The server side response used to initialize the OIDCConfig object.
+   * @param response The server side response used to initialize the OIDCConfig object.
    * @constructor
    */
   constructor(response: OIDCConfigServerResponse) {

src/auth/auth-namespace.ts

@@ -95,6 +95,27 @@ import {
   UserRecord as TUserRecord,
 } from './user-record';
 
+/**
+ * Gets the {@link auth.Auth `Auth`} service for the default app or a
+ * given app.
+ *
+ * `getAuth()` can be called with no arguments to access the default app's
+ * {@link auth.Auth `Auth`} service or as `getAuth(app)` to access the
+ * {@link auth.Auth `Auth`} service associated with a specific app.
+ *
+ * @example
+ * ```javascript
+ * // Get the Auth service for the default app
+ * const defaultAuth = getAuth();
+ * ```
+ *
+ * @example
+ * ```javascript
+ * // Get the Auth service for a given app
+ * const otherAuth = getAuth(otherApp);
+ * ```
+ *
+ */
 export function getAuth(app?: App): Auth {
   if (typeof app === 'undefined') {
     app = getApp();

src/auth/auth.ts

@@ -49,7 +49,9 @@ export class Auth extends BaseAuth {
     return this.app_;
   }
 
-  /** @return The current Auth instance's tenant manager. */
+  /**
+   * @return The tenant manager instance associated with the current project.
+   */
   public tenantManager(): TenantManager {
     return this.tenantManager_;
   }