Allow project-management to auto-generate typings, separate internal vs external APIs (#971)

* Allow project-management to auto-generate typings, separate internal vs external APIs (#971)

Author: MathBunny

gulpfile.js

@@ -52,7 +52,11 @@ var paths = {
 
   build: 'lib/',
 
-  curatedTypings: ['src/*.d.ts', '!src/instance-id.d.ts'],
+  curatedTypings: [
+    'src/*.d.ts',
+    '!src/instance-id.d.ts',
+    '!src/project-management.d.ts'
+  ],
 };
 
 const TEMPORARY_TYPING_EXCLUDES = [
@@ -65,7 +69,6 @@ const TEMPORARY_TYPING_EXCLUDES = [
   '!lib/firestore/*.d.ts',
   '!lib/machine-learning/*.d.ts',
   '!lib/messaging/*.d.ts',
-  '!lib/project-management/*.d.ts',
   '!lib/remote-config/*.d.ts',
   '!lib/security-rules/*.d.ts',
   '!lib/storage/*.d.ts',

src/project-management/android-app.ts

@@ -16,7 +16,7 @@
 
 import { FirebaseProjectManagementError } from '../utils/error';
 import * as validator from '../utils/validator';
-import { ProjectManagementRequestHandler, assertServerResponse } from './project-management-api-request';
+import { ProjectManagementRequestHandler, assertServerResponse } from './project-management-api-request-internal';
 import { AndroidAppMetadata, AppPlatform } from './app-metadata';
 
 export class AndroidApp {
@@ -33,6 +33,11 @@ export class AndroidApp {
     this.resourceName = `projects/-/androidApps/${appId}`;
   }
 
+  /**
+   * Retrieves metadata about this Android app.
+   *
+   * @return A promise that resolves to the retrieved metadata about this Android app.
+   */
   public getMetadata(): Promise<AndroidAppMetadata> {
     return this.requestHandler.getResource(this.resourceName)
       .then((responseData: any) => {
@@ -61,10 +66,23 @@ export class AndroidApp {
       });
   }
 
+  /**
+   * Sets the optional user-assigned display name of the app.
+   *
+   * @param newDisplayName The new display name to set.
+   *
+   * @return A promise that resolves when the display name has been set.
+   */
   public setDisplayName(newDisplayName: string): Promise<void> {
     return this.requestHandler.setDisplayName(this.resourceName, newDisplayName);
   }
 
+  /**
+   * Gets the list of SHA certificates associated with this Android app in Firebase.
+   *
+   * @return The list of SHA-1 and SHA-256 certificates associated with this Android app in
+   *     Firebase.
+   */
   public getShaCertificates(): Promise<ShaCertificate[]> {
     return this.requestHandler.getAndroidShaCertificates(this.resourceName)
       .then((responseData: any) => {
@@ -98,10 +116,26 @@ export class AndroidApp {
       });
   }
 
+  /**
+   * Adds the given SHA certificate to this Android app.
+   *
+   * @param certificateToAdd The SHA certificate to add.
+   *
+   * @return A promise that resolves when the given certificate
+   *     has been added to the Android app.
+   */
   public addShaCertificate(certificateToAdd: ShaCertificate): Promise<void> {
     return this.requestHandler.addAndroidShaCertificate(this.resourceName, certificateToAdd);
   }
 
+  /**
+   * Deletes the specified SHA certificate from this Android app.
+   *
+   * @param  certificateToDelete The SHA certificate to delete.
+   *
+   * @return A promise that resolves when the specified
+   *     certificate has been removed from the Android app.
+   */
   public deleteShaCertificate(certificateToDelete: ShaCertificate): Promise<void> {
     if (!certificateToDelete.resourceName) {
       throw new FirebaseProjectManagementError(
@@ -113,8 +147,12 @@ export class AndroidApp {
   }
 
   /**
-   * @return {Promise<string>} A promise that resolves to a UTF-8 JSON string, typically intended to
-   *     be written to a JSON file.
+   * Gets the configuration artifact associated with this app.
+   *
+   * @return A promise that resolves to the Android app's
+   *     Firebase config file, in UTF-8 string format. This string is typically
+   *     intended to be written to a JSON file that gets shipped with your Android
+   *     app.
    */
   public getConfig(): Promise<string> {
     return this.requestHandler.getConfig(this.resourceName)
@@ -135,16 +173,38 @@ export class AndroidApp {
   }
 }
 
+/**
+ * A SHA-1 or SHA-256 certificate.
+ *
+ * Do not call this constructor directly. Instead, use
+ * [`projectManagement.shaCertificate()`](admin.projectManagement.ProjectManagement#shaCertificate).
+ */
 export class ShaCertificate {
+  /**
+   * The SHA certificate type.
+   *
+   * @example
+   * ```javascript
+   * var certType = shaCertificate.certType;
+   * ```
+   */
   public readonly certType: ('sha1' | 'sha256');
 
   /**
    * Creates a ShaCertificate using the given hash. The ShaCertificate's type (eg. 'sha256') is
    * automatically determined from the hash itself.
    *
    * @param shaHash The sha256 or sha1 hash for this certificate.
+   * @example
+   * ```javascript
+   * var shaHash = shaCertificate.shaHash;
+   * ```
    * @param resourceName The Firebase resource name for this certificate. This does not need to be
    *     set when creating a new certificate.
+   * @example
+   * ```javascript
+   * var resourceName = shaCertificate.resourceName;
+   * ```
    */
   constructor(public readonly shaHash: string, public readonly resourceName?: string) {
     if (/^[a-fA-F0-9]{40}$/.test(shaHash)) {

src/project-management/app-metadata.ts

@@ -14,26 +14,117 @@
  * limitations under the License.
  */
 
+/**
+ * Platforms with which a Firebase App can be associated.
+ */
 export enum AppPlatform {
+
+  /**
+   * Unknown state. This is only used for distinguishing unset values.
+   */
   PLATFORM_UNKNOWN = 'PLATFORM_UNKNOWN',
+
+  /**
+   * The Firebase App is associated with iOS.
+   */
   IOS = 'IOS',
+
+  /**
+   * The Firebase App is associated with Android.
+   */
   ANDROID = 'ANDROID',
 }
 
+/**
+ * Metadata about a Firebase app.
+ */
 export interface AppMetadata {
+
+  /**
+   * The globally unique, Firebase-assigned identifier of the app.
+   *
+   * @example
+   * ```javascript
+   * var appId = appMetadata.appId;
+   * ```
+   */
   appId: string;
+
+  /**
+   * The optional user-assigned display name of the app.
+   *
+   * @example
+   * ```javascript
+   * var displayName = appMetadata.displayName;
+   * ```
+   */
   displayName?: string;
+
+  /**
+   * The development platform of the app. Supporting Android and iOS app platforms.
+   *
+   * @example
+   * ```javascript
+   * var platform = AppPlatform.ANDROID;
+   * ```
+   */
   platform: AppPlatform;
+
+  /**
+   * The globally unique, user-assigned ID of the parent project for the app.
+   *
+   * @example
+   * ```javascript
+   * var projectId = appMetadata.projectId;
+   * ```
+   */
   projectId: string;
-  resourceName: string;
-}
 
-export interface AndroidAppMetadata extends AppMetadata {
-  platform: AppPlatform.ANDROID;
-  packageName: string;
+  /**
+   * The fully-qualified resource name that identifies this app.
+   *
+   * This is useful when manually constructing requests for Firebase's public API.
+   *
+   * @example
+   * ```javascript
+   * var resourceName = androidAppMetadata.resourceName;
+   * ```
+   */
+  resourceName: string;
 }
 
+/**
+ * Metadata about a Firebase iOS App.
+ */
 export interface IosAppMetadata extends AppMetadata {
   platform: AppPlatform.IOS;
+
+  /**
+   * The canonical bundle ID of the iOS App as it would appear in the iOS App Store.
+   *
+   * @example
+   * ```javascript
+   * var bundleId = iosAppMetadata.bundleId;
+   *```
+   */
   bundleId: string;
 }
+
+/**
+ * Metadata about a Firebase Android App.
+ */
+export interface AndroidAppMetadata extends AppMetadata {
+
+  platform: AppPlatform.ANDROID;
+
+  /**
+   * The canonical package name of the Android App, as would appear in the Google Play Developer
+   * Console.
+   *
+   * @example
+   * ```javascript
+   * var packageName = androidAppMetadata.packageName;
+   * ```
+   */
+  packageName: string;
+}

src/project-management/index.ts

@@ -0,0 +1,54 @@
+/*!
+ * 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 androidAppApi from './android-app';
+import * as appMetadataApi from './app-metadata';
+import * as iosAppApi from './ios-app';
+import * as projectManagementApi from './project-management';
+import * as firebaseAdmin from '../index';
+
+export function projectManagement(app?: FirebaseApp): projectManagementApi.ProjectManagement {
+  if (typeof(app) === 'undefined') {
+    app = firebaseAdmin.app();
+  }
+  return app.projectManagement();
+}
+
+/**
+ * We must define a namespace to make the typings work correctly. Otherwise
+ * `admin.projectManagement()` cannot be called like a function. Temporarily,
+ * admin.projectManagement 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.projectManagement {
+  // 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 AndroidAppMetadata = appMetadataApi.AndroidAppMetadata
+  export import AppMetadata = appMetadataApi.AppMetadata
+  export import AppPlatform = appMetadataApi.AppPlatform 
+  export import IosAppMetadata = appMetadataApi.IosAppMetadata
+
+  // Allows for exposing classes as interfaces in typings
+  /* eslint-disable @typescript-eslint/no-empty-interface */
+  export interface AndroidApp extends androidAppApi.AndroidApp {}
+  export interface IosApp extends iosAppApi.IosApp {}
+  export interface ProjectManagement extends projectManagementApi.ProjectManagement {}
+  export interface ShaCertificate extends androidAppApi.ShaCertificate {}
+}

src/project-management/ios-app.ts

@@ -16,7 +16,7 @@
 
 import { FirebaseProjectManagementError } from '../utils/error';
 import * as validator from '../utils/validator';
-import { ProjectManagementRequestHandler, assertServerResponse } from './project-management-api-request';
+import { ProjectManagementRequestHandler, assertServerResponse } from './project-management-api-request-internal';
 import { IosAppMetadata, AppPlatform } from './app-metadata';
 
 export class IosApp {
@@ -33,6 +33,12 @@ export class IosApp {
     this.resourceName = `projects/-/iosApps/${appId}`;
   }
 
+  /**
+   * Retrieves metadata about this iOS app.
+   *
+   * @return {!Promise<admin.projectManagement.IosAppMetadata>} A promise that
+   *     resolves to the retrieved metadata about this iOS app.
+   */
   public getMetadata(): Promise<IosAppMetadata> {
     return this.requestHandler.getResource(this.resourceName)
       .then((responseData: any) => {
@@ -61,13 +67,24 @@ export class IosApp {
       });
   }
 
+  /**
+   * Sets the optional user-assigned display name of the app.
+   *
+   * @param newDisplayName The new display name to set.
+   *
+   * @return A promise that resolves when the display name has
+   *     been set.
+   */
   public setDisplayName(newDisplayName: string): Promise<void> {
     return this.requestHandler.setDisplayName(this.resourceName, newDisplayName);
   }
 
   /**
-   * @return {Promise<string>} A promise that resolves to a UTF-8 XML string, typically intended to
-   *     be written to a plist file.
+   * Gets the configuration artifact associated with this app.
+   *
+   * @return A promise that resolves to the iOS app's Firebase
+   *     config file, in UTF-8 string format. This string is typically intended to
+   *     be written to a plist file that gets shipped with your iOS app.
    */
   public getConfig(): Promise<string> {
     return this.requestHandler.getConfig(this.resourceName)