feat(machine-learning): Adding Firebase ML management APIs

CONTRIBUTING.md

@@ -155,13 +155,17 @@ Then set up your Firebase/GCP project as follows:
    Firebase Console. Select the "Sign-in method" tab, and enable the
    "Email/Password" sign-in method, including the Email link (passwordless
    sign-in) option.
-3. Enable the IAM API: Go to the
+3. Enable the Firebase ML API: Go to the
+   [Google Developers Console](
+   https://console.developers.google.com/apis/api/firebaseml.googleapis.com/overview)
+   and make sure your project is selected. If the API is not already enabled, click Enable.
+4. Enable the IAM API: Go to the
    [Google Cloud Platform Console](https://console.cloud.google.com) and make
    sure your Firebase/GCP project is selected. Select "APIs & Services >
    Dashboard" from the main menu, and click the "ENABLE APIS AND SERVICES"
    button. Search for and enable the "Identity and Access Management (IAM)
    API".
-4. Grant your service account the 'Firebase Authentication Admin' role. This is
+5. Grant your service account the 'Firebase Authentication Admin' role. This is
    required to ensure that exported user records contain the password hashes of
    the user accounts:
    1. Go to [Google Cloud Platform Console / IAM & admin](https://console.cloud.google.com/iam-admin).

docgen/content-sources/node/toc.yaml

@@ -132,6 +132,22 @@ toc:
   - title: "InstanceId"
     path: /docs/reference/admin/node/admin.instanceId.InstanceId
 
+- title: "machinelearning"
+  path: /docs/reference/admin/node/admin.machinelearning
+  section:
+  - title: "ListModelsOptions"
+    path: /docs/reference/admin/node/admin.machinelearning.ListModelsOptions
+  - title: "ListModelsResult"
+    path: /docs/reference/admin/node/admin.machinelearning.ListModelsResult
+  - title: "MachineLearning"
+    path: /docs/reference/admin/node/admin.machinelearning.MachineLearning
+  - title: "Model"
+    path: /docs/reference/admin/node/admin.machinelearning.Model
+  - title: "ModelOptions"
+    path: /docs/reference/admin/node/admin.machinelearning.ModelOptions
+  - title: "TFLiteModel"
+    path: /docs/reference/admin/node/admin.machinelearning.TFLiteModel
+
 - title: "admin.messaging"
   path: /docs/reference/admin/node/admin.messaging
   section:

src/firebase-app.ts

@@ -22,13 +22,15 @@ import {FirebaseNamespaceInternals} from './firebase-namespace';
 import {AppErrorCodes, FirebaseAppError} from './utils/error';
 
 import {Auth} from './auth/auth';
+import {MachineLearning} from './machine-learning/machine-learning';
 import {Messaging} from './messaging/messaging';
 import {Storage} from './storage/storage';
 import {Database} from '@firebase/database';
 import {DatabaseService} from './database/database';
 import {Firestore} from '@google-cloud/firestore';
 import {FirestoreService} from './firestore/firestore';
 import {InstanceId} from './instance-id/instance-id';
+
 import {ProjectManagement} from './project-management/project-management';
 import {SecurityRules} from './security-rules/security-rules';
 
@@ -354,6 +356,19 @@ export class FirebaseApp {
     });
   }
 
+  /**
+   * Returns the MachineLearning service instance associated with this app.
+   *
+   * @return {MachineLearning} The Machine Learning service instance of this app
+   */
+  public machineLearning(): MachineLearning {
+    return this.ensureService_('machine-learning', () => {
+      const machineLearningService: typeof MachineLearning =
+          require('./machine-learning/machine-learning').MachineLearning;
+      return new machineLearningService(this);
+    });
+  }
+
   /**
    * Returns the ProjectManagement service instance associated with this app.
    *

src/firebase-namespace.ts

@@ -28,6 +28,7 @@ import {
 } from './auth/credential';
 
 import {Auth} from './auth/auth';
+import {MachineLearning} from './machine-learning/machine-learning';
 import {Messaging} from './messaging/messaging';
 import {Storage} from './storage/storage';
 import {Database} from '@firebase/database';
@@ -399,6 +400,21 @@ export class FirebaseNamespace {
     return fn;
   }
 
+  /**
+   * Gets the `MachineLearning` service namespace. The returned namespace can be
+   * used to get the `MachineLearning` service for the default app or an
+   * explicityly specified app.
+   */
+  get machineLearning(): FirebaseServiceNamespace<MachineLearning> {
+    const fn: FirebaseServiceNamespace<MachineLearning> =
+        (app?: FirebaseApp) => {
+          return this.ensureApp(app).machineLearning();
+        };
+    const machineLearning =
+        require('./machine-learning/machine-learning').MachineLearning;
+    return Object.assign(fn, {MachineLearning: machineLearning});
+  }
+
   /**
    * 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/index.d.ts

@@ -404,6 +404,37 @@ declare namespace admin {
   */
   function securityRules(app?: admin.app.App): admin.securityRules.SecurityRules;
 
+  /**
+   * Gets the {@link admin.machineLearning.MachineLearning `MachineLearning`} service for the
+   * default app or a given app.
+   *
+   * `admin.machineLearning()` can be called with no arguments to access the
+   * default app's {@link admin.machineLearning.MachineLearning
+    * `MachineLearning`} service or as `admin.machineLearning(app)` to access
+    * the {@link admin.machineLearning.MachineLearning `MachineLearning`}
+    * service associated with a specific app.
+    *
+    * @example
+    * ```javascript
+    * // Get the MachineLearning service for the default app
+    * var defaultMachineLearning = admin.machineLearning();
+    * ```
+    *
+    * @example
+    * ```javascript
+    * // Get the MachineLearning service for a given app
+    * var otherMachineLearning = admin.machineLearning(otherApp);
+    * ```
+    *
+    * @param app Optional app whose `MachineLearning` service to
+    *   return. If not provided, the default `MachineLearning` service
+    *   will be returned.
+    *
+    * @return The default `MachineLearning` service if no app is provided or the
+    *   `MachineLearning` service associated with the provided app.
+    */
+  function machineLearning(app?: admin.app.App): admin.machineLearning.MachineLearning;
+
   function initializeApp(options?: admin.AppOptions, name?: string): admin.app.App;
 }
 
@@ -462,6 +493,7 @@ declare namespace admin.app {
     database(url?: string): admin.database.Database;
     firestore(): admin.firestore.Firestore;
     instanceId(): admin.instanceId.InstanceId;
+    machineLearning(): admin.machineLearning.MachineLearning;
     messaging(): admin.messaging.Messaging;
     projectManagement(): admin.projectManagement.ProjectManagement;
     securityRules(): admin.securityRules.SecurityRules;
@@ -788,6 +820,212 @@ declare namespace admin.securityRules {
   export import SecurityRules = _securityRules.admin.securityRules.SecurityRules;
 }
 
+declare namespace admin.machineLearning {
+  /**
+   * Interface representing options for listing Models.
+   */
+  interface ListModelsOptions {
+    /**
+     * An expression that specifies how to filter the results.
+     *
+     * Examples:
+     *
+     * ```
+     * display_name = your_model
+     * display_name : experimental_*
+     * tags: face_detector AND tags: experimental
+     * state.published = true
+     * ```
+     *
+     * See https://firebase.google.com/docs/ml-kit/manage-hosted-models#list_your_projects_models
+     */
+    filter?: string;
+
+    /** The number of results to return in each page. */
+    pageSize?: number;
+
+    /** A token that specifies the result page to return. */
+    pageToken?: string;
+  }
+
+  /** Response object for a listModels operation. */
+  interface ListModelsResult {
+    /** A list of models in your project. */
+    readonly models: Model[];
+
+    /**
+     * A token you can use to retrieve the next page of results. If null, the
+     * current page is the final page.
+     */
+    readonly pageToken?: string;
+  }
+
+  /**
+   * A TensorFlow Lite Model output object
+   */
+  interface TFLiteModel {
+    /** The size of the model. */
+    readonly sizeBytes: number;
+
+    /** The URI from which the model was originally provided to Firebase. */
+    readonly gcsTfliteUri?: string;
+  }
+
+  /**
+   * A Firebase ML Model input object
+   */
+  interface ModelOptions {
+    /** A name for the model. This is the name you use from your app to load the model. */
+    displayName?: string;
+
+    /** Tags for easier model management. */
+    tags?: string[];
+
+    /**
+     * An object containing the URI of the model in Cloud Storage.
+     *
+     * Example: `tfliteModel: { gcsTfliteUri: 'gs://your-bucket/your-model.tflite' }`
+     */
+    tfliteModel?: {gcsTfliteUri: string};
+  }
+
+  /**
+   * A Firebase ML Model output object
+   */
+  interface Model {
+    /** The ID of the model. */
+    readonly modelId: string;
+
+    /** The model's name. This is the name you use from your app to load the model. */
+    readonly displayName: string;
+
+    /** The model's tags. */
+    readonly tags?: string[];
+
+    /** The timestamp of the model's creation. */
+    readonly createTime: string;
+
+    /** The timestamp of the model's most recent update. */
+    readonly updateTime: string;
+
+    /** Error message when model validation fails. */
+    readonly validationError?: string;
+
+    /** True if the model is published. */
+    readonly published: boolean;
+
+    /**
+     * The ETag identifier of the current version of the model. This value
+     * changes whenever you update any of the model's properties.
+     */
+    readonly etag: string;
+
+    /**
+     * The hash of the model's `tflite` file. This value changes only when
+     * you upload a new TensorFlow Lite model.
+     */
+    readonly modelHash?: string;
+
+    /**
+     * True if the model is locked by a server-side operation. You can't make
+     * changes to a locked model. See {@link waitForUnlocked `waitForUnlocked()`}.
+     */
+    readonly locked: boolean;
+
+    /**
+     * Wait for the model to be unlocked.
+     *
+     * @param {number} maxTimeSeconds The maximum time in seconds to wait.
+     *
+     * @return {Promise<void>} A promise that resolves when the model is unlocked
+     *   or the maximum wait time has passed.
+     */
+    waitForUnlocked(maxTimeSeconds?: number): Promise<void>;
+
+    /** Metadata about the model's TensorFlow Lite model file. */
+    readonly tfliteModel?: TFLiteModel;
+  }
+
+  /**
+   * The Firebase `MachineLearning` service interface.
+   *
+   * Do not call this constructor directly. Instead, use
+   * [`admin.machineLearning()`](admin.machineLearning#machineLearning).
+   */
+  interface MachineLearning {
+    /**
+     *  The {@link admin.app.App} associated with the current `MachineLearning`
+     *  service instance.
+     */
+    app: admin.app.App;
+
+    /**
+     * Creates a model in Firebase ML.
+     *
+     * @param {ModelOptions} model The model to create.
+     *
+     * @return {Promise<Model>} A Promise fulfilled with the created model.
+     */
+    createModel(model: ModelOptions): Promise<Model>;
+
+    /**
+     * Updates a model in Firebase ML.
+     *
+     * @param {string} modelId The ID of the model to update.
+     * @param {ModelOptions} model The model fields to update.
+     *
+     * @return {Promise<Model>} A Promise fulfilled with the updated model.
+     */
+    updateModel(modelId: string, model: ModelOptions): Promise<Model>;
+
+    /**
+     * Publishes a model in Firebase ML.
+     *
+     * @param {string} modelId The ID of the model to publish.
+     *
+     * @return {Promise<Model>} A Promise fulfilled with the published model.
+     */
+    publishModel(modelId: string): Promise<Model>;
+
+    /**
+     * Unpublishes a model in Firebase ML.
+     *
+     * @param {string} modelId The ID of the model to unpublish.
+     *
+     * @return {Promise<Model>} A Promise fulfilled with the unpublished model.
+     */
+    unpublishModel(modelId: string): Promise<Model>;
+
+    /**
+     * Gets a model from Firebase ML.
+     *
+     * @param {string} modelId The ID of the model to get.
+     *
+     * @return {Promise<Model>} A Promise fulfilled with the model object.
+     */
+    getModel(modelId: string): Promise<Model>;
+
+    /**
+     * Lists models from Firebase ML.
+     *
+     * @param {ListModelsOptions} options The listing options.
+     *
+     * @return {Promise<ListModelsResult>} A promise that
+     *     resolves with the current (filtered) list of models and the next page
+     *     token. For the last page, an empty list of models and no page token
+     *     are returned.
+     */
+    listModels(options?: ListModelsOptions): Promise<ListModelsResult>;
+
+    /**
+     * Deletes a model from Firebase ML.
+     *
+     * @param {string} modelId The ID of the model to delete.
+     */
+    deleteModel(modelId: string): Promise<void>;
+  }
+}
+
 declare module 'firebase-admin' {
 }