feat(fis): Adding the admin.installations() API for deleting Firebase installation IDs (#1187)

* feat(fis): Added admin.installations() API * fix: Marked IID APIs deprecated * fix: Deprecated App.instanceId() method; Added more unit and integration tests * fix: Throwing FirebaseInstallationsError from constructor * fix: Some docs updates * fix: Minor update to API doc comment * fix: Added Installations class to API ref toc * fix: Minor doc updates

Author: hiranya911

docgen/content-sources/node/toc.yaml

@@ -144,6 +144,12 @@ toc:
 - title: "admin.firestore"
  path: /docs/reference/admin/node/admin.firestore
 
+- title: "admin.installations"
+ path: /docs/reference/admin/node/admin.installations
+ section:
+ - title: "Installations"
+ path: /docs/reference/admin/node/admin.installations.Installations-1
+
 - title: "admin.instanceId"
  path: /docs/reference/admin/node/admin.instanceId
  section:

etc/firebase-admin.api.md

@@ -25,6 +25,8 @@ export namespace app {
  // (undocumented)
  firestore(): firestore.Firestore;
  // (undocumented)
+ installations(): installations.Installations;
+ // @deprecated (undocumented)
  instanceId(): instanceId.InstanceId;
  // (undocumented)
  machineLearning(): machineLearning.MachineLearning;
@@ -542,13 +544,27 @@ export interface GoogleOAuthAccessToken {
 export function initializeApp(options?: AppOptions, name?: string): app.App;
 
 // @public
+export function installations(app?: app.App): installations.Installations;
+
+// @public (undocumented)
+export namespace installations {
+ export interface Installations {
+ // (undocumented)
+ app: app.App;
+ deleteInstallation(fid: string): Promise<void>;
+ }
+}
+
+// @public @deprecated
 export function instanceId(app?: app.App): instanceId.InstanceId;
 
 // @public (undocumented)
 export namespace instanceId {
+ // @deprecated
  export interface InstanceId {
  // (undocumented)
  app: app.App;
+ // @deprecated
  deleteInstanceId(instanceId: string): Promise<void>;
  }
 }

src/firebase-app.ts

@@ -31,6 +31,7 @@ import { database } from './database/index';
 import { DatabaseService } from './database/database-internal';
 import { Firestore } from '@google-cloud/firestore';
 import { FirestoreService } from './firestore/firestore-internal';
+import { Installations } from './installations/installations';
 import { InstanceId } from './instance-id/instance-id';
 import { ProjectManagement } from './project-management/project-management';
 import { SecurityRules } from './security-rules/security-rules';
@@ -256,9 +257,23 @@ export class FirebaseApp implements app.App {
  return service.client;
  }
 
+ /**
+ * Returns the `Installations` service instance associated with this app.
+ *
+ * @return The `Installations` service instance of this app.
+ */
+ public installations(): Installations {
+ return this.ensureService_('installations', () => {
+ const fisService: typeof Installations = require('./installations/installations').Installations;
+ return new fisService(this);
+ });
+ }
+
  /**
  * Returns the InstanceId service instance associated with this app.
  *
+ * This API is deprecated. Use the `installations()` API instead.
+ *
  * @return The InstanceId service instance of this app.
  */
  public instanceId(): InstanceId {

src/firebase-namespace-api.ts

@@ -20,6 +20,7 @@ import { auth } from './auth/index';
 import { credential } from './credential/index';
 import { database } from './database/index';
 import { firestore } from './firestore/index';
+import { installations } from './installations/index';
 import { instanceId } from './instance-id/index';
 import { machineLearning } from './machine-learning/index';
 import { messaging } from './messaging/index';
@@ -227,6 +228,8 @@ export namespace app {
  auth(): auth.Auth;
  database(url?: string): database.Database;
  firestore(): firestore.Firestore;
+ installations(): installations.Installations;
+ /** @deprecated */
  instanceId(): instanceId.InstanceId;
  machineLearning(): machineLearning.MachineLearning;
  messaging(): messaging.Messaging;

src/firebase-namespace.d.ts

@@ -20,6 +20,7 @@ export * from './app-check/index';
 export * from './auth/index';
 export * from './database/index';
 export * from './firestore/index';
+export * from './installations/index';
 export * from './instance-id/index';
 export * from './machine-learning/index';
 export * from './messaging/index';

src/firebase-namespace.ts

@@ -27,6 +27,7 @@ import { appCheck } from './app-check/index';
 import { auth } from './auth/index';
 import { database } from './database/index';
 import { firestore } from './firestore/index';
+import { installations } from './installations/index';
 import { instanceId } from './instance-id/index';
 import { machineLearning } from './machine-learning/index';
 import { messaging } from './messaging/index';
@@ -43,6 +44,7 @@ import AppCheck = appCheck.AppCheck;
 import Auth = auth.Auth;
 import Database = database.Database;
 import Firestore = firestore.Firestore;
+import Installations = installations.Installations;
 import InstanceId = instanceId.InstanceId;
 import MachineLearning = machineLearning.MachineLearning;
 import Messaging = messaging.Messaging;
@@ -311,6 +313,18 @@ export class FirebaseNamespace {
  return Object.assign(fn, { MachineLearning: machineLearning });
  }
 
+ /**
+ * Gets the `Installations` service namespace. The returned namespace can be used to get the
+ * `Installations` service for the default app or an explicitly specified app.
+ */
+ get installations(): FirebaseServiceNamespace<Installations> {
+ const fn: FirebaseServiceNamespace<Installations> = (app?: App) => {
+ return this.ensureApp(app).installations();
+ };
+ const installations = require('./installations/installations').Installations;
+ return Object.assign(fn, { Installations: installations });
+ }
+
  /**
  * Gets the `InstanceId` service namespace. The returned namespace can be used to get the
  * `Instance` service for the default app or an explicitly specified app.

src/installations/index.ts

@@ -0,0 +1,85 @@
+/*!
+ * Copyright 2021 Google Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { app } from '../firebase-namespace-api';
+
+/**
+ * Gets the {@link installations.Installations `Installations`} service for the
+ * default app or a given app.
+ *
+ * `admin.installations()` can be called with no arguments to access the default
+ * app's {@link installations.Installations `Installations`} service or as
+ * `admin.installations(app)` to access the
+ * {@link installations.Installations `Installations`} service associated with a
+ * specific app.
+ *
+ * @example
+ * ```javascript
+ * // Get the Installations service for the default app
+ * var defaultInstallations = admin.installations();
+ * ```
+ *
+ * @example
+ * ```javascript
+ * // Get the Installations service for a given app
+ * var otherInstallations = admin.installations(otherApp);
+ *```
+ *
+ * @param app Optional app whose `Installations` service to
+ * return. If not provided, the default `Installations` service is
+ * returned.
+ *
+ * @return The default `Installations` service if
+ * no app is provided or the `Installations` service associated with the
+ * provided app.
+ */
+export declare function installations(app?: app.App): installations.Installations;
+
+/* eslint-disable @typescript-eslint/no-namespace */
+export namespace installations {
+ /**
+ * Gets the {@link Installations `Installations`} service for the
+ * current app.
+ *
+ * @example
+ * ```javascript
+ * var installations = app.installations();
+ * // The above is shorthand for:
+ * // var installations = admin.installations(app);
+ * ```
+ *
+ * @return The `Installations` service for the
+ * current app.
+ */
+ export interface Installations {
+ app: app.App;
+
+ /**
+ * Deletes the specified installation ID and the associated data from Firebase.
+ *
+ * Note that Google Analytics for Firebase uses its own form of Instance ID to
+ * keep track of analytics data. Therefore deleting a Firebase installation ID does
+ * not delete Analytics data. See
+ * [Delete a Firebase installation](/docs/projects/manage-installations#delete-installation)
+ * for more information.
+ *
+ * @param fid The Firebase installation ID to be deleted.
+ *
+ * @return A promise fulfilled when the installation ID is deleted.
+ */
+ deleteInstallation(fid: string): Promise<void>;
+ }
+}

src/instance-id/instance-id-request-internal.ts renamed to src/installations/installations-request-handler.ts

@@ -1,6 +1,6 @@
 /*!
  * @license
- * Copyright 2017 Google Inc.
+ * Copyright 2021 Google Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -16,7 +16,7 @@
  */
 
 import { FirebaseApp } from '../firebase-app';
-import { FirebaseInstanceIdError, InstanceIdClientErrorCode } from '../utils/error';
+import { FirebaseInstallationsError, InstallationsClientErrorCode } from '../utils/error';
 import {
  ApiSettings, AuthorizedHttpClient, HttpRequestConfig, HttpError,
 } from '../utils/api-request';
@@ -33,50 +33,50 @@ const FIREBASE_IID_TIMEOUT = 10000;
 
 /** HTTP error codes raised by the backend server. */
 const ERROR_CODES: {[key: number]: string} = {
- 400: 'Malformed instance ID argument.',
+ 400: 'Malformed installation ID argument.',
  401: 'Request not authorized.',
- 403: 'Project does not match instance ID or the client does not have sufficient privileges.',
- 404: 'Failed to find the instance ID.',
+ 403: 'Project does not match installation ID or the client does not have sufficient privileges.',
+ 404: 'Failed to find the installation ID.',
  409: 'Already deleted.',
  429: 'Request throttled out by the backend server.',
  500: 'Internal server error.',
  503: 'Backend servers are over capacity. Try again later.',
 };
 
 /**
- * Class that provides mechanism to send requests to the Firebase Instance ID backend endpoints.
+ * Class that provides mechanism to send requests to the FIS backend endpoints.
  */
-export class FirebaseInstanceIdRequestHandler {
+export class FirebaseInstallationsRequestHandler {
 
  private readonly host: string = FIREBASE_IID_HOST;
  private readonly timeout: number = FIREBASE_IID_TIMEOUT;
  private readonly httpClient: AuthorizedHttpClient;
  private path: string;
 
  /**
- * @param {FirebaseApp} app The app used to fetch access tokens to sign API requests.
+ * @param app The app used to fetch access tokens to sign API requests.
  *
  * @constructor
  */
  constructor(private readonly app: FirebaseApp) {
  this.httpClient = new AuthorizedHttpClient(app);
  }
 
- public deleteInstanceId(instanceId: string): Promise<void> {
- if (!validator.isNonEmptyString(instanceId)) {
- return Promise.reject(new FirebaseInstanceIdError(
- InstanceIdClientErrorCode.INVALID_INSTANCE_ID,
- 'Instance ID must be a non-empty string.',
+ public deleteInstallation(fid: string): Promise<void> {
+ if (!validator.isNonEmptyString(fid)) {
+ return Promise.reject(new FirebaseInstallationsError(
+ InstallationsClientErrorCode.INVALID_INSTALLATION_ID,
+ 'Installation ID must be a non-empty string.',
  ));
  }
- return this.invokeRequestHandler(new ApiSettings(instanceId, 'DELETE'));
+ return this.invokeRequestHandler(new ApiSettings(fid, 'DELETE'));
  }
 
  /**
  * Invokes the request handler based on the API settings object passed.
  *
- * @param {ApiSettings} apiSettings The API endpoint settings to apply to request and response.
- * @return {Promise<void>} A promise that resolves when the request is complete.
+ * @param apiSettings The API endpoint settings to apply to request and response.
+ * @return A promise that resolves when the request is complete.
  */
  private invokeRequestHandler(apiSettings: ApiSettings): Promise<void> {
  return this.getPathPrefix()
@@ -98,8 +98,8 @@ export class FirebaseInstanceIdRequestHandler {
  response.data.error : response.text;
  const template: string = ERROR_CODES[response.status];
  const message: string = template ?
- `Instance ID "${apiSettings.getEndpoint()}": ${template}` : errorMessage;
- throw new FirebaseInstanceIdError(InstanceIdClientErrorCode.API_ERROR, message);
+ `Installation ID "${apiSettings.getEndpoint()}": ${template}` : errorMessage;
+ throw new FirebaseInstallationsError(InstallationsClientErrorCode.API_ERROR, message);
  }
  // In case of timeouts and other network errors, the HttpClient returns a
  // FirebaseError wrapped in the response. Simply throw it here.
@@ -116,9 +116,9 @@ export class FirebaseInstanceIdRequestHandler {
  .then((projectId) => {
  if (!validator.isNonEmptyString(projectId)) {
  // Assert for an explicit projct ID (either via AppOptions or the cert itself).
- throw new FirebaseInstanceIdError(
- InstanceIdClientErrorCode.INVALID_PROJECT_ID,
- 'Failed to determine project ID for InstanceId. Initialize the '
+ throw new FirebaseInstallationsError(
+ InstallationsClientErrorCode.INVALID_PROJECT_ID,
+ 'Failed to determine project ID for Installations. Initialize the '
  + 'SDK with service account credentials or set project ID as an app option. '
  + 'Alternatively set the GOOGLE_CLOUD_PROJECT environment variable.',
  );