firebase-admin 13.4.0 → 13.5.0

package/lib/app/core.d.ts

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 /*!
  * @license
  * Copyright 2021 Google Inc.

package/lib/app/core.js

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 "use strict";
 /*!
  * @license

package/lib/app/credential-factory.d.ts

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 /*!
  * @license
  * Copyright 2021 Google Inc.

package/lib/app/credential-factory.js

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 "use strict";
 /*!
  * @license

package/lib/app/credential-internal.d.ts

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 /*!
  * @license
  * Copyright 2020 Google Inc.

package/lib/app/credential-internal.js

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 "use strict";
 /*!
  * @license

package/lib/app/credential.d.ts

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 /*!
  * @license
  * Copyright 2021 Google Inc.

package/lib/app/credential.js

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 "use strict";
 /*!
  * @license

package/lib/app/firebase-app.d.ts

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 /*!
  * @license
  * Copyright 2017 Google Inc.

package/lib/app/firebase-app.js

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 "use strict";
 /*!
  * @license
@@ -121,18 +121,22 @@ exports.FirebaseAppInternals = FirebaseAppInternals;
  * @internal
  */
 class FirebaseApp {
-    constructor(options, name, appStore) {
+    constructor(options, name, autoInit = false, appStore) {
         this.appStore = appStore;
         this.services_ = {};
         this.isDeleted_ = false;
+        this.autoInit_ = false;
+        this.customCredential_ = true;
         this.name_ = name;
         this.options_ = (0, deep_copy_1.deepCopy)(options);
+        this.autoInit_ = autoInit;
         if (!validator.isNonNullObject(this.options_)) {
             throw new error_1.FirebaseAppError(error_1.AppErrorCodes.INVALID_APP_OPTIONS, 'Invalid Firebase app options passed as the first argument to initializeApp() for the ' +
                 `app named "${this.name_}". Options must be a non-null object.`);
         }
         const hasCredential = ('credential' in this.options_);
         if (!hasCredential) {
+            this.customCredential_ = false;
             this.options_.credential = (0, credential_internal_1.getApplicationDefault)(this.options_.httpAgent);
         }
         const credential = this.options_.credential;
@@ -167,6 +171,23 @@ class FirebaseApp {
     getOrInitService(name, init) {
         return this.ensureService_(name, () => init(this));
     }
+    /**
+     * Returns `true` if this app was initialized with auto-initialization.
+     *
+     * @internal
+     */
+    autoInit() {
+        return this.autoInit_;
+    }
+    /**
+     * Returns `true` if the `FirebaseApp` instance was initialized with a custom
+     * `Credential`.
+     *
+     * @internal
+     */
+    customCredential() {
+        return this.customCredential_;
+    }
     /**
      * Deletes the FirebaseApp instance.
      *

package/lib/app/firebase-namespace.d.ts

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 /*!
  * @license
  * Copyright 2017 Google Inc.

package/lib/app/firebase-namespace.js

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 "use strict";
 /*!
  * @license

package/lib/app/index.d.ts

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 /*!
  * @license
  * Copyright 2021 Google Inc.

package/lib/app/index.js

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 "use strict";
 /*!
  * @license

package/lib/app/lifecycle.d.ts

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 /*!
  * @license
  * Copyright 2021 Google Inc.
@@ -31,8 +31,64 @@ export declare class AppStore {
     removeApp(appName: string): void;
 }
 export declare const defaultAppStore: AppStore;
+/**
+ * Initializes the `App` instance.
+ *
+ * Creates a new instance of {@link App} if one doesn't exist, or returns an existing
+ * `App` instance if one exists with the same `appName` and `options`.
+ *
+ * Note, due to the inablity to compare `http.Agent` objects and `Credential` objects,
+ * this function cannot support idempotency if either of `options.httpAgent` or
+ * `options.credential` are defined. When either is defined, subsequent invocations will
+ * throw a `FirebaseAppError` instead of returning an `App` object.
+ *
+ * For example, to safely initialize an app that may already exist:
+ *
+ * ```javascript
+ * let app;
+ * try {
+ *   app = getApp("myApp");
+ * } catch (error) {
+ *   app = initializeApp({ credential: myCredential }, "myApp");
+ * }
+ * ```
+ *
+ * @param options - Optional A set of {@link AppOptions} for the `App` instance.
+ *   If not present, `initializeApp` will try to initialize with the options from the
+ *   `FIREBASE_CONFIG` environment variable. If the environment variable contains a
+ *   string that starts with `{` it will be parsed as JSON, otherwise it will be
+ *   assumed to be pointing to a file.
+ * @param appName - Optional name of the `App` instance.
+ *
+ * @returns A new App instance, or the existing App if the instance already exists with
+ *   the provided configuration.
+ *
+ * @throws FirebaseAppError if an `App` with the same name has already been
+ *   initialized with a different set of `AppOptions`.
+ * @throws FirebaseAppError if an existing `App` exists and `options.httpAgent`
+ *   or `options.credential` are defined. This is due to the function's inability to
+ *   determine if the existing `App`'s `options` equate to the `options` parameter
+ *   of this function. It's recommended to use {@link getApp} or {@link getApps} if your
+ *   implementation uses either of these two fields in `AppOptions`.
+ */
 export declare function initializeApp(options?: AppOptions, appName?: string): App;
+/**
+ * Returns an existing {@link App} instance for the provided name. If no name
+ * is provided the the default app name is used.
+ *
+ * @param appName - Optional name of the `App` instance.
+ *
+ * @returns An existing `App` instance that matches the name provided.
+ *
+ * @throws FirebaseAppError if no `App` exists for the given name.
+ * @throws FirebaseAppError if the `appName` is malformed.
+ */
 export declare function getApp(appName?: string): App;
+/**
+ * A (read-only) array of all initialized apps.
+ *
+ * @returns An array containing all initialized apps.
+ */
 export declare function getApps(): App[];
 /**
  * Renders this given `App` unusable and frees the resources of

package/lib/app/lifecycle.js

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 "use strict";
 /*!
  * @license
@@ -27,42 +27,52 @@ const validator = require("../utils/validator");
 const error_1 = require("../utils/error");
 const credential_internal_1 = require("./credential-internal");
 const firebase_app_1 = require("./firebase-app");
+const fastDeepEqual = require('fast-deep-equal');
 const DEFAULT_APP_NAME = '[DEFAULT]';
 class AppStore {
     constructor() {
         this.appStore = new Map();
     }
     initializeApp(options, appName = DEFAULT_APP_NAME) {
+        validateAppNameFormat(appName);
+        let autoInit = false;
         if (typeof options === 'undefined') {
+            autoInit = true;
             options = loadOptionsFromEnvVar();
             options.credential = (0, credential_internal_1.getApplicationDefault)();
         }
-        if (typeof appName !== 'string' || appName === '') {
-            throw new error_1.FirebaseAppError(error_1.AppErrorCodes.INVALID_APP_NAME, `Invalid Firebase app name "${appName}" provided. App name must be a non-empty string.`);
+        // Check if an app already exists and, if so, ensure its `AppOptions` match
+        // those of this `initializeApp` request. 
+        if (!this.appStore.has(appName)) {
+            const app = new firebase_app_1.FirebaseApp(options, appName, autoInit, this);
+            this.appStore.set(app.name, app);
+            return app;
         }
-        else if (this.appStore.has(appName)) {
-            if (appName === DEFAULT_APP_NAME) {
-                throw new error_1.FirebaseAppError(error_1.AppErrorCodes.DUPLICATE_APP, 'The default Firebase app already exists. This means you called initializeApp() ' +
-                    'more than once without providing an app name as the second argument. In most cases ' +
-                    'you only need to call initializeApp() once. But if you do want to initialize ' +
-                    'multiple apps, pass a second argument to initializeApp() to give each app a unique ' +
-                    'name.');
-            }
-            else {
-                throw new error_1.FirebaseAppError(error_1.AppErrorCodes.DUPLICATE_APP, `Firebase app named "${appName}" already exists. This means you called initializeApp() ` +
-                    'more than once with the same app name as the second argument. Make sure you provide a ' +
-                    'unique name every time you call initializeApp().');
-            }
+        const currentApp = this.appStore.get(appName);
+        // Ensure the `autoInit` state matches the existing app's. If not, throw.
+        if (currentApp.autoInit() !== autoInit) {
+            throw new error_1.FirebaseAppError(error_1.AppErrorCodes.INVALID_APP_OPTIONS, `A Firebase app named "${appName}" already exists with a different configuration.`);
         }
-        const app = new firebase_app_1.FirebaseApp(options, appName, this);
-        this.appStore.set(app.name, app);
-        return app;
+        if (autoInit) {
+            // Auto-initialization is triggered when no options were passed to
+            // `initializeApp`. With no options to compare, simply return the App.
+            return currentApp;
+        }
+        // Ensure the options objects don't break deep equal comparisons.
+        validateAppOptionsSupportDeepEquals(options, currentApp);
+        // `FirebaseApp()` adds a synthesized `Credential` to `app.options` upon
+        // app construction. Run a comparison w/o `Credential` to see if the base
+        // configurations match. Return the existing app if so.
+        const currentAppOptions = { ...currentApp.options };
+        delete currentAppOptions.credential;
+        if (!fastDeepEqual(options, currentAppOptions)) {
+            throw new error_1.FirebaseAppError(error_1.AppErrorCodes.DUPLICATE_APP, `A Firebase app named "${appName}" already exists with a different configuration.`);
+        }
+        return currentApp;
     }
     getApp(appName = DEFAULT_APP_NAME) {
-        if (typeof appName !== 'string' || appName === '') {
-            throw new error_1.FirebaseAppError(error_1.AppErrorCodes.INVALID_APP_NAME, `Invalid Firebase app name "${appName}" provided. App name must be a non-empty string.`);
-        }
-        else if (!this.appStore.has(appName)) {
+        validateAppNameFormat(appName);
+        if (!this.appStore.has(appName)) {
             let errorMessage = (appName === DEFAULT_APP_NAME)
                 ? 'The default Firebase app does not exist. ' : `Firebase app named "${appName}" does not exist. `;
             errorMessage += 'Make sure you call initializeApp() before using any of the Firebase services.';
@@ -101,13 +111,121 @@ class AppStore {
     }
 }
 exports.AppStore = AppStore;
+/**
+ * Validates that the `requestedOptions` and the `existingApp` options objects
+ * do not have fields that would break deep equals comparisons.
+ *
+ * @param requestedOptions The incoming `AppOptions` of a new `initailizeApp`
+ *   request.
+ * @param existingApp An existing `FirebaseApp` with internal `options` to
+ *   compare against.
+ *
+ * @throws FirebaseAppError if the objects cannot be deeply compared.
+ *
+ * @internal
+ */
+function validateAppOptionsSupportDeepEquals(requestedOptions, existingApp) {
+    // http.Agent checks.
+    if (typeof requestedOptions.httpAgent !== 'undefined') {
+        throw new error_1.FirebaseAppError(error_1.AppErrorCodes.INVALID_APP_OPTIONS, `Firebase app named "${existingApp.name}" already exists and initializeApp was` +
+            ' invoked with an optional http.Agent. The SDK cannot confirm the equality' +
+            ' of http.Agent objects with the existing app. Please use getApp or getApps to reuse' +
+            ' the existing app instead.');
+    }
+    else if (typeof existingApp.options.httpAgent !== 'undefined') {
+        throw new error_1.FirebaseAppError(error_1.AppErrorCodes.INVALID_APP_OPTIONS, `An existing app named "${existingApp.name}" already exists with a different` +
+            ' options configuration: httpAgent.');
+    }
+    // Credential checks.
+    if (typeof requestedOptions.credential !== 'undefined') {
+        throw new error_1.FirebaseAppError(error_1.AppErrorCodes.INVALID_APP_OPTIONS, `Firebase app named "${existingApp.name}" already exists and initializeApp was` +
+            ' invoked with an optional Credential. The SDK cannot confirm the equality' +
+            ' of Credential objects with the existing app. Please use getApp or getApps' +
+            ' to reuse the existing app instead.');
+    }
+    if (existingApp.customCredential()) {
+        throw new error_1.FirebaseAppError(error_1.AppErrorCodes.INVALID_APP_OPTIONS, `An existing app named "${existingApp.name}" already exists with a different` +
+            ' options configuration: Credential.');
+    }
+}
+/**
+ * Checks to see if the provided appName is a non-empty string and throws if it
+ * is not.
+ *
+ * @param appName A string representation of an App name.
+ *
+ * @throws FirebaseAppError if appName is not of type string or is empty.
+ *
+ * @internal
+ */
+function validateAppNameFormat(appName) {
+    if (!validator.isNonEmptyString(appName)) {
+        throw new error_1.FirebaseAppError(error_1.AppErrorCodes.INVALID_APP_NAME, `Invalid Firebase app name "${appName}" provided. App name must be a non-empty string.`);
+    }
+}
 exports.defaultAppStore = new AppStore();
+/**
+ * Initializes the `App` instance.
+ *
+ * Creates a new instance of {@link App} if one doesn't exist, or returns an existing
+ * `App` instance if one exists with the same `appName` and `options`.
+ *
+ * Note, due to the inablity to compare `http.Agent` objects and `Credential` objects,
+ * this function cannot support idempotency if either of `options.httpAgent` or
+ * `options.credential` are defined. When either is defined, subsequent invocations will
+ * throw a `FirebaseAppError` instead of returning an `App` object.
+ *
+ * For example, to safely initialize an app that may already exist:
+ *
+ * ```javascript
+ * let app;
+ * try {
+ *   app = getApp("myApp");
+ * } catch (error) {
+ *   app = initializeApp({ credential: myCredential }, "myApp");
+ * }
+ * ```
+ *
+ * @param options - Optional A set of {@link AppOptions} for the `App` instance.
+ *   If not present, `initializeApp` will try to initialize with the options from the
+ *   `FIREBASE_CONFIG` environment variable. If the environment variable contains a
+ *   string that starts with `{` it will be parsed as JSON, otherwise it will be
+ *   assumed to be pointing to a file.
+ * @param appName - Optional name of the `App` instance.
+ *
+ * @returns A new App instance, or the existing App if the instance already exists with
+ *   the provided configuration.
+ *
+ * @throws FirebaseAppError if an `App` with the same name has already been
+ *   initialized with a different set of `AppOptions`.
+ * @throws FirebaseAppError if an existing `App` exists and `options.httpAgent`
+ *   or `options.credential` are defined. This is due to the function's inability to
+ *   determine if the existing `App`'s `options` equate to the `options` parameter
+ *   of this function. It's recommended to use {@link getApp} or {@link getApps} if your
+ *   implementation uses either of these two fields in `AppOptions`.
+ */
 function initializeApp(options, appName = DEFAULT_APP_NAME) {
     return exports.defaultAppStore.initializeApp(options, appName);
 }
+/**
+ * Returns an existing {@link App} instance for the provided name. If no name
+ * is provided the the default app name is used.
+ *
+ * @param appName - Optional name of the `App` instance.
+ *
+ * @returns An existing `App` instance that matches the name provided.
+ *
+ * @throws FirebaseAppError if no `App` exists for the given name.
+ * @throws FirebaseAppError if the `appName` is malformed.
+ */
 function getApp(appName = DEFAULT_APP_NAME) {
     return exports.defaultAppStore.getApp(appName);
 }
+/**
+ * A (read-only) array of all initialized apps.
+ *
+ * @returns An array containing all initialized apps.
+ */
 function getApps() {
     return exports.defaultAppStore.getApps();
 }

package/lib/app-check/app-check-api-client-internal.d.ts

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 /*!
  * @license
  * Copyright 2021 Google Inc.

package/lib/app-check/app-check-api-client-internal.js

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 "use strict";
 /*!
  * @license

package/lib/app-check/app-check-api.d.ts

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 /*!
  * @license
  * Copyright 2021 Google Inc.

package/lib/app-check/app-check-api.js

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 "use strict";
 /*!
  * @license

package/lib/app-check/app-check-namespace.d.ts

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 /*!
  * Copyright 2021 Google Inc.
  *

package/lib/app-check/app-check-namespace.js

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 "use strict";
 /*!
  * Copyright 2021 Google Inc.

package/lib/app-check/app-check.d.ts

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 /*!
  * @license
  * Copyright 2021 Google Inc.

package/lib/app-check/app-check.js

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 "use strict";
 /*!
  * @license

package/lib/app-check/index.d.ts

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 /*!
  * @license
  * Copyright 2021 Google Inc.

package/lib/app-check/index.js

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 "use strict";
 /*!
  * @license

package/lib/app-check/token-generator.d.ts

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 /*!
  * @license
  * Copyright 2021 Google Inc.

package/lib/app-check/token-generator.js

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 "use strict";
 /*!
  * @license

package/lib/app-check/token-verifier.d.ts

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 /*!
  * Copyright 2021 Google Inc.
  *

package/lib/app-check/token-verifier.js

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 "use strict";
 /*!
  * Copyright 2021 Google Inc.

package/lib/auth/action-code-settings-builder.d.ts

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 /*!
  * Copyright 2018 Google Inc.
  *

package/lib/auth/action-code-settings-builder.js

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 "use strict";
 /*!
  * Copyright 2018 Google Inc.

package/lib/auth/auth-api-request.d.ts

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 /*!
  * @license
  * Copyright 2017 Google Inc.

package/lib/auth/auth-api-request.js

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 "use strict";
 /*!
  * @license

package/lib/auth/auth-config.d.ts

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 /*!
  * Copyright 2018 Google Inc.
  *

package/lib/auth/auth-config.js

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 "use strict";
 /*!
  * Copyright 2018 Google Inc.

package/lib/auth/auth-namespace.d.ts

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 /*!
  * Copyright 2021 Google Inc.
  *

package/lib/auth/auth-namespace.js

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 "use strict";
 /*!
  * Copyright 2021 Google Inc.

package/lib/auth/auth.d.ts

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 /*!
  * @license
  * Copyright 2017 Google Inc.

package/lib/auth/auth.js

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 "use strict";
 /*!
  * @license

package/lib/auth/base-auth.d.ts

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 /*!
  * Copyright 2021 Google Inc.
  *

package/lib/auth/base-auth.js

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 "use strict";
 /*!
  * Copyright 2021 Google Inc.

package/lib/auth/identifier.d.ts

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 /*!
  * Copyright 2020 Google Inc.
  *

package/lib/auth/identifier.js

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 "use strict";
 /*!
  * Copyright 2020 Google Inc.

package/lib/auth/index.d.ts

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 /*!
  * Copyright 2020 Google Inc.
  *

package/lib/auth/index.js

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 "use strict";
 /*!
  * Copyright 2020 Google Inc.

package/lib/auth/project-config-manager.d.ts

@@ -1,4 +1,4 @@
-/*! firebase-admin v13.4.0 */
+/*! firebase-admin v13.5.0 */
 import { ProjectConfig, UpdateProjectConfigRequest } from './project-config';
 /**
  * Manages (gets and updates) the current project config.