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

* Firebase ML Node.js SDK Structure (#778) * Firebase ML Node.js SDK Structure * added tests * Added GetModel functionality and tests (#781) * Added GetModel functionality and tests * Added DeleteModel functionality and tests (#782) * Added DeleteModel functionality and tests * Added CreateModel functionality and tests (#788) * Added CreateModel functionality and tests * Added UpdateModel, publishModel,and unpublishModel functionality + tests (#791) * Added UpdateModel, publishModel,and unpublishModel functionality plus tests * Added ListModels functionality for Firebase ML (#795) * Added ListModels functionality for Firebase ML * Firebase ML changed endpoint (#813) * Add ML APIs to docgen toc (#847) * Docstring fixes and additions (#848) * Docstring fixes and additions * A few edits * Ml merge (#851) * Custom Action for sending Tweets (#784) * Experimental custom Action for sending Tweets * Added license headers * Added README file * Updated package descriptions * Improve customClaims Typing (#768) * chore: Experimental release flow based on Actions (#780) * chore: Experimental release flow based on Actions * Added tarball verification step; Simplified CI trigger * Splitting staging and publish phases into separate jobs * Fleshed out the full workflow * Trigger RC build * chore: Migrated to ESlint (#790) * chore: Migrated to ESlint * Added licesne header * Enabling additional ESLint checks (#794) * chore: Enabling more ESLint checks and fixing errors (#797) * Fix compilation error in integration tests (#798) Introduced by #790 * Build integration tests during CI (and release) (#800) Note that this won't actually run them. Additionally, the *unit* tests are also built, impying that we're building them twice (once during this step, and possibly again when running the unit tests.) * Fix revokeRefreshTokens to round consistently with the other platforms. (#801) This also makes it consistent with the comments a few lines above, as well as the integration test. * feat(auth): Multi-factor Auth support with SMS for Google Cloud Identity Platform (#804) Defines multi-factor auth administrative APIs for Google Cloud Identity Platform. * Defines new MFA types in toc.yaml. (#807) * Removes special char from index.d.ts. (#808) This is causing errors in the reference generation process. * Defines MultiFactor{Create|Update}Settings interfaces. (#809) * Defines MultiFactor{Create|Update}Settings interfaces. * chore: Adding a .npmrc file to the root of the repo (#810) * chore: Adding a .npmrc file to the root of the repo * Removing the root-level .npmrc file * [chore] Release 8.10.0 (#811) * [chore] Release 8.10.0 (take 2) (#812) * Bump acorn from 6.1.1 to 6.4.1 (#815) Bumps [acorn](https://github.com/acornjs/acorn) from 6.1.1 to 6.4.1. - [Release notes](https://github.com/acornjs/acorn/releases) - [Commits](acornjs/acorn@6.1.1...6.4.1) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * Fixing Android notification options descriptions (#820) * Fixing doc bug that conflated sound and tag options for Android notifications. * Removing duplicate documentation for tag. * Adding tag details in the right place this time, hopefully. * chore: Splitting the index.d.ts file into smaller files (#751) * Splitting the index.d.ts file into smaller files * Database return type fixed * chore: Cleaning up package verification scripts (#822) * chore: Cleaning up package verification scripts * Added package metadata to test package.json file * fix(auth): Fixing UserImportRecord typings declaration (#835) * fix(auth): Fixing UserImportRecord typings declaration * Fixing more integration test compilation errors * Trigger CI * Removed redundant line * Bump minimist from 1.2.0 to 1.2.3 (#839) Bumps [minimist](https://github.com/substack/minimist) from 1.2.0 to 1.2.3. - [Release notes](https://github.com/substack/minimist/releases) - [Commits](https://github.com/substack/minimist/compare/1.2.0...1.2.3) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * remerge conflict Co-authored-by: Hiranya Jayathilaka <hiranya911@gmail.com> Co-authored-by: William Sedlacek <wsedlacekc@gmail.com> Co-authored-by: rsgowman <rgowman@google.com> Co-authored-by: bojeil-google <bojeil-google@users.noreply.github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: egilmorez <egilmore@google.com> * Added Firebase ML API requirements to Contributing doc (#853) Co-authored-by: Kevin Cheung <kevinthecheung@users.noreply.github.com> Co-authored-by: Hiranya Jayathilaka <hiranya911@gmail.com> Co-authored-by: William Sedlacek <wsedlacekc@gmail.com> Co-authored-by: rsgowman <rgowman@google.com> Co-authored-by: bojeil-google <bojeil-google@users.noreply.github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: egilmorez <egilmore@google.com>
firebase · Apr 20, 2020 · 9f7ee6b · 9f7ee6b
1 parent ed6036f
commit 9f7ee6b
Show file tree

Hide file tree

Showing 17 changed files with 3,023 additions and 2 deletions.
diff --git a/CONTRIBUTING.md b/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).

diff --git a/docgen/content-sources/node/toc.yaml b/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:

diff --git a/src/firebase-app.ts b/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.
    *

diff --git a/src/firebase-namespace.ts b/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.

diff --git a/src/index.d.ts b/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' {
 }