Allow instance-id to auto-generate typings, separate internal vs external APIs (#969)

* Allow instance-id to auto-generate typings, separate internal vs external APIs (#969)

Author: MathBunny

gulpfile.js

@@ -52,7 +52,7 @@ var paths = {
 
   build: 'lib/',
 
-  curatedTypings: ['src/*.d.ts'],
+  curatedTypings: ['src/*.d.ts', '!src/instance-id.d.ts'],
 };
 
 const TEMPORARY_TYPING_EXCLUDES = [
@@ -63,7 +63,6 @@ const TEMPORARY_TYPING_EXCLUDES = [
   '!lib/auth/*.d.ts',
   '!lib/database/*.d.ts',
   '!lib/firestore/*.d.ts',
-  '!lib/instance-id/*.d.ts',
   '!lib/machine-learning/*.d.ts',
   '!lib/messaging/*.d.ts',
   '!lib/project-management/*.d.ts',

src/firebase-app.ts

@@ -30,6 +30,7 @@ import { DatabaseService } from './database/database';
 import { Firestore } from '@google-cloud/firestore';
 import { FirestoreService } from './firestore/firestore';
 import { InstanceId } from './instance-id/instance-id';
+import { InstanceIdImpl } from './instance-id/instance-id-internal';
 
 import { ProjectManagement } from './project-management/project-management';
 import { SecurityRules } from './security-rules/security-rules';
@@ -352,7 +353,7 @@ export class FirebaseApp {
    */
   public instanceId(): InstanceId {
     return this.ensureService_('iid', () => {
-      const iidService: typeof InstanceId = require('./instance-id/instance-id').InstanceId;
+      const iidService: typeof InstanceIdImpl = require('./instance-id/instance-id-internal').InstanceIdImpl;
       return new iidService(this);
     });
   }

src/firebase-namespace.ts

@@ -425,7 +425,7 @@ export class FirebaseNamespace {
     const fn: FirebaseServiceNamespace<InstanceId> = (app?: FirebaseApp) => {
       return this.ensureApp(app).instanceId();
     };
-    const instanceId = require('./instance-id/instance-id').InstanceId;
+    const instanceId = require('./instance-id/instance-id-internal').InstanceIdImpl;
     return Object.assign(fn, { InstanceId: instanceId });
   }
 

src/instance-id/index.ts

@@ -0,0 +1,41 @@
+/*!
+ * Copyright 2020 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 { FirebaseApp } from '../firebase-app';
+import * as instanceIdApi from './instance-id';
+import * as firebaseAdmin from '../index';
+
+export function instanceId(app?: FirebaseApp): instanceIdApi.InstanceId {
+  if (typeof(app) === 'undefined') {
+    app = firebaseAdmin.app();
+  }
+  return app.instanceId();
+}
+
+/**
+ * We must define a namespace to make the typings work correctly. Otherwise
+ * `admin.instanceId()` cannot be called like a function. Temporarily,
+ * admin.instanceId is used as the namespace name because we cannot barrel 
+ * re-export the contents from instance-id, and we want it to
+ * match the namespacing in the re-export inside src/index.d.ts
+ */
+/* eslint-disable @typescript-eslint/no-namespace */
+export namespace admin.instanceId {
+  // See https://github.com/microsoft/TypeScript/issues/4336
+  /* eslint-disable @typescript-eslint/no-unused-vars */
+  // See https://github.com/typescript-eslint/typescript-eslint/issues/363
+  export import InstanceId = instanceIdApi.InstanceId;
+}

src/instance-id/instance-id-internal.ts

@@ -0,0 +1,85 @@
+/*!
+ * Copyright 2020 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 { FirebaseApp } from '../firebase-app';
+import { InstanceId } from './instance-id';
+import { FirebaseInstanceIdError, InstanceIdClientErrorCode } from '../utils/error';
+import { FirebaseServiceInterface, FirebaseServiceInternalsInterface } from '../firebase-service';
+import { FirebaseInstanceIdRequestHandler } from './instance-id-request';
+
+import * as validator from '../utils/validator';
+
+/**
+ * Internals of an InstanceId service instance.
+ */
+class InstanceIdInternals implements FirebaseServiceInternalsInterface {
+  /**
+   * Deletes the service and its associated resources.
+   *
+   * @return {Promise<()>} An empty Promise that will be fulfilled when the service is deleted.
+   */
+  public delete(): Promise<void> {
+    // There are no resources to clean up
+    return Promise.resolve(undefined);
+  }
+}
+
+export class InstanceIdImpl implements FirebaseServiceInterface, InstanceId {
+  public INTERNAL: InstanceIdInternals = new InstanceIdInternals();
+
+  private app_: FirebaseApp;
+  private requestHandler: FirebaseInstanceIdRequestHandler;
+
+  /**
+   * @param {FirebaseApp} app The app for this InstanceId service.
+   * @constructor
+   */
+  constructor(app: FirebaseApp) {
+    if (!validator.isNonNullObject(app) || !('options' in app)) {
+      throw new FirebaseInstanceIdError(
+        InstanceIdClientErrorCode.INVALID_ARGUMENT,
+        'First argument passed to admin.instanceId() must be a valid Firebase app instance.',
+      );
+    }
+
+    this.app_ = app;
+    this.requestHandler = new FirebaseInstanceIdRequestHandler(app);
+  }
+
+  /**
+   * Deletes the specified instance ID from Firebase. This can be used to delete an instance ID
+   * and associated user data from a Firebase project, pursuant to the General Data Protection
+   * Regulation (GDPR).
+   *
+   * @param {string} instanceId The instance ID to be deleted
+   * @return {Promise<void>} A promise that resolves when the instance ID is successfully deleted.
+   */
+  public deleteInstanceId(instanceId: string): Promise<void> {
+    return this.requestHandler.deleteInstanceId(instanceId)
+      .then(() => {
+        // Return nothing on success
+      });
+  }
+
+  /**
+   * Returns the app associated with this InstanceId instance.
+   *
+   * @return {FirebaseApp} The app associated with this InstanceId instance.
+   */
+  get app(): FirebaseApp {
+    return this.app_;
+  }
+}

src/instance-id/instance-id.ts

@@ -1,5 +1,5 @@
 /*!
- * Copyright 2017 Google Inc.
+ * Copyright 2020 Google Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -15,70 +15,36 @@
  */
 
 import { FirebaseApp } from '../firebase-app';
-import { FirebaseInstanceIdError, InstanceIdClientErrorCode } from '../utils/error';
-import { FirebaseServiceInterface, FirebaseServiceInternalsInterface } from '../firebase-service';
-import { FirebaseInstanceIdRequestHandler } from './instance-id-request';
-
-import * as validator from '../utils/validator';
 
 /**
- * Internals of an InstanceId service instance.
+ * Gets the {@link InstanceId `InstanceId`} service for the
+ * current app.
+ *
+ * @example
+ * ```javascript
+ * var instanceId = app.instanceId();
+ * // The above is shorthand for:
+ * // var instanceId = admin.instanceId(app);
+ * ```
+ *
+ * @return The `InstanceId` service for the
+ *   current app.
  */
-class InstanceIdInternals implements FirebaseServiceInternalsInterface {
-  /**
-   * Deletes the service and its associated resources.
-   *
-   * @return {Promise<()>} An empty Promise that will be fulfilled when the service is deleted.
-   */
-  public delete(): Promise<void> {
-    // There are no resources to clean up
-    return Promise.resolve(undefined);
-  }
-}
-
-export class InstanceId implements FirebaseServiceInterface {
-  public INTERNAL: InstanceIdInternals = new InstanceIdInternals();
-
-  private app_: FirebaseApp;
-  private requestHandler: FirebaseInstanceIdRequestHandler;
+export interface InstanceId {
+  app: FirebaseApp;
 
   /**
-   * @param {FirebaseApp} app The app for this InstanceId service.
-   * @constructor
-   */
-  constructor(app: FirebaseApp) {
-    if (!validator.isNonNullObject(app) || !('options' in app)) {
-      throw new FirebaseInstanceIdError(
-        InstanceIdClientErrorCode.INVALID_ARGUMENT,
-        'First argument passed to admin.instanceId() must be a valid Firebase app instance.',
-      );
-    }
-
-    this.app_ = app;
-    this.requestHandler = new FirebaseInstanceIdRequestHandler(app);
-  }
-
-  /**
-   * Deletes the specified instance ID from Firebase. This can be used to delete an instance ID
-   * and associated user data from a Firebase project, pursuant to the General Data Protection
-   * Regulation (GDPR).
+   * Deletes the specified instance ID and the associated data from Firebase.
    *
-   * @param {string} instanceId The instance ID to be deleted
-   * @return {Promise<void>} A promise that resolves when the instance ID is successfully deleted.
-   */
-  public deleteInstanceId(instanceId: string): Promise<void> {
-    return this.requestHandler.deleteInstanceId(instanceId)
-      .then(() => {
-        // Return nothing on success
-      });
-  }
-
-  /**
-   * Returns the app associated with this InstanceId instance.
+   * Note that Google Analytics for Firebase uses its own form of Instance ID to
+   * keep track of analytics data. Therefore deleting a Firebase Instance ID does
+   * not delete Analytics data. See
+   * [Delete an Instance ID](/support/privacy/manage-iids#delete_an_instance_id)
+   * for more information.
+   *
+   * @param instanceId The instance ID to be deleted.
    *
-   * @return {FirebaseApp} The app associated with this InstanceId instance.
+   * @return A promise fulfilled when the instance ID is deleted.
    */
-  get app(): FirebaseApp {
-    return this.app_;
-  }
+  deleteInstanceId(instanceId: string): Promise<void>;
 }

test/unit/firebase-namespace.spec.ts

@@ -49,6 +49,7 @@ import {
   setLogFunction,
 } from '@google-cloud/firestore';
 import { InstanceId } from '../../src/instance-id/instance-id';
+import { InstanceIdImpl } from '../../src/instance-id/instance-id-internal';
 import { ProjectManagement } from '../../src/project-management/project-management';
 import { SecurityRules } from '../../src/security-rules/security-rules';
 import { RemoteConfig } from '../../src/remote-config/remote-config';
@@ -623,7 +624,7 @@ describe('FirebaseNamespace', () => {
     });
 
     it('should return a reference to InstanceId type', () => {
-      expect(firebaseNamespace.instanceId.InstanceId).to.be.deep.equal(InstanceId);
+      expect(firebaseNamespace.instanceId.InstanceId).to.be.deep.equal(InstanceIdImpl);
     });
   });
 

test/unit/instance-id/instance-id.spec.ts

@@ -26,6 +26,7 @@ import * as utils from '../utils';
 import * as mocks from '../../resources/mocks';
 
 import { InstanceId } from '../../../src/instance-id/instance-id';
+import { InstanceIdImpl } from '../../../src/instance-id/instance-id-internal';
 import { FirebaseInstanceIdRequestHandler } from '../../../src/instance-id/instance-id-request';
 import { FirebaseApp } from '../../../src/firebase-app';
 import { FirebaseInstanceIdError, InstanceIdClientErrorCode } from '../../../src/utils/error';
@@ -57,14 +58,14 @@ describe('InstanceId', () => {
     mockApp = mocks.app();
     getTokenStub = utils.stubGetAccessToken(undefined, mockApp);
     mockCredentialApp = mocks.mockCredentialApp();
-    iid = new InstanceId(mockApp);
+    iid = new InstanceIdImpl(mockApp);
 
     googleCloudProject = process.env.GOOGLE_CLOUD_PROJECT;
     gcloudProject = process.env.GCLOUD_PROJECT;
 
-    nullAccessTokenClient = new InstanceId(mocks.appReturningNullAccessToken());
-    malformedAccessTokenClient = new InstanceId(mocks.appReturningMalformedAccessToken());
-    rejectedPromiseAccessTokenClient = new InstanceId(mocks.appRejectedWhileFetchingAccessToken());
+    nullAccessTokenClient = new InstanceIdImpl(mocks.appReturningNullAccessToken());
+    malformedAccessTokenClient = new InstanceIdImpl(mocks.appReturningMalformedAccessToken());
+    rejectedPromiseAccessTokenClient = new InstanceIdImpl(mocks.appRejectedWhileFetchingAccessToken());
   });
 
   afterEach(() => {
@@ -80,15 +81,15 @@ describe('InstanceId', () => {
     invalidApps.forEach((invalidApp) => {
       it('should throw given invalid app: ' + JSON.stringify(invalidApp), () => {
         expect(() => {
-          const iidAny: any = InstanceId;
+          const iidAny: any = InstanceIdImpl;
           return new iidAny(invalidApp);
         }).to.throw('First argument passed to admin.instanceId() must be a valid Firebase app instance.');
       });
     });
 
     it('should throw given no app', () => {
       expect(() => {
-        const iidAny: any = InstanceId;
+        const iidAny: any = InstanceIdImpl;
         return new iidAny();
       }).to.throw('First argument passed to admin.instanceId() must be a valid Firebase app instance.');
     });
@@ -97,14 +98,14 @@ describe('InstanceId', () => {
       // Project ID not set in the environment.
       delete process.env.GOOGLE_CLOUD_PROJECT;
       delete process.env.GCLOUD_PROJECT;
-      const instanceId = new InstanceId(mockCredentialApp);
+      const instanceId = new InstanceIdImpl(mockCredentialApp);
       return instanceId.deleteInstanceId('iid')
         .should.eventually.rejectedWith(noProjectIdError);
     });
 
     it('should not throw given a valid app', () => {
       expect(() => {
-        return new InstanceId(mockApp);
+        return new InstanceIdImpl(mockApp);
       }).not.to.throw();
     });
   });
@@ -118,7 +119,7 @@ describe('InstanceId', () => {
     it('is read-only', () => {
       expect(() => {
         (iid as any).app = mockApp;
-      }).to.throw('Cannot set property app of #<InstanceId> which has only a getter');
+      }).to.throw('Cannot set property app of #<InstanceIdImpl> which has only a getter');
     });
   });