firebase-admin 9.12.0 → 10.0.1

package/lib/machine-learning/machine-learning.d.ts

@@ -0,0 +1,181 @@
+/*! firebase-admin v10.0.1 */
+/*!
+ * 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 { App } from '../app';
+import { ListModelsOptions, ModelOptions } from './machine-learning-api-client';
+/** Response object for a listModels operation. */
+export 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
+ *
+ * One of either the `gcsTfliteUri` or `automlModel` properties will be
+ * defined.
+ */
+export interface TFLiteModel {
+    /** The size of the model. */
+    readonly sizeBytes: number;
+    /** The URI from which the model was originally provided to Firebase. */
+    readonly gcsTfliteUri?: string;
+    /**
+     * The AutoML model reference from which the model was originally provided
+     * to Firebase.
+     */
+    readonly automlModel?: string;
+}
+/**
+ * The Firebase `MachineLearning` service interface.
+ */
+export declare class MachineLearning {
+    private readonly client;
+    private readonly appInternal;
+    /**
+     *  The {@link firebase-admin.app#App} associated with the current `MachineLearning`
+     *  service instance.
+     */
+    get app(): App;
+    /**
+     * Creates a model in the current Firebase project.
+     *
+     * @param model - The model to create.
+     *
+     * @returns A Promise fulfilled with the created model.
+     */
+    createModel(model: ModelOptions): Promise<Model>;
+    /**
+     * Updates a model's metadata or model file.
+     *
+     * @param modelId - The ID of the model to update.
+     * @param model - The model fields to update.
+     *
+     * @returns A Promise fulfilled with the updated model.
+     */
+    updateModel(modelId: string, model: ModelOptions): Promise<Model>;
+    /**
+     * Publishes a Firebase ML model.
+     *
+     * A published model can be downloaded to client apps.
+     *
+     * @param modelId - The ID of the model to publish.
+     *
+     * @returns A Promise fulfilled with the published model.
+     */
+    publishModel(modelId: string): Promise<Model>;
+    /**
+     * Unpublishes a Firebase ML model.
+     *
+     * @param modelId - The ID of the model to unpublish.
+     *
+     * @returns A Promise fulfilled with the unpublished model.
+     */
+    unpublishModel(modelId: string): Promise<Model>;
+    /**
+     * Gets the model specified by the given ID.
+     *
+     * @param modelId - The ID of the model to get.
+     *
+     * @returns A Promise fulfilled with the model object.
+     */
+    getModel(modelId: string): Promise<Model>;
+    /**
+     * Lists the current project's models.
+     *
+     * @param options - The listing options.
+     *
+     * @returns 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 the current project.
+     *
+     * @param modelId - The ID of the model to delete.
+     */
+    deleteModel(modelId: string): Promise<void>;
+    private setPublishStatus;
+    private signUrlIfPresent;
+    private signUrl;
+}
+/**
+ * A Firebase ML Model output object.
+ */
+export declare class Model {
+    private model;
+    private readonly client?;
+    /** The ID of the model. */
+    get modelId(): string;
+    /**
+     * The model's name. This is the name you use from your app to load the
+     * model.
+     */
+    get displayName(): string;
+    /**
+     * The model's tags, which can be used to group or filter models in list
+     * operations.
+     */
+    get tags(): string[];
+    /** The timestamp of the model's creation. */
+    get createTime(): string;
+    /** The timestamp of the model's most recent update. */
+    get updateTime(): string;
+    /** Error message when model validation fails. */
+    get validationError(): string | undefined;
+    /** True if the model is published. */
+    get published(): boolean;
+    /**
+     * The ETag identifier of the current version of the model. This value
+     * changes whenever you update any of the model's properties.
+     */
+    get etag(): string;
+    /**
+     * The hash of the model's `tflite` file. This value changes only when
+     * you upload a new TensorFlow Lite model.
+     */
+    get modelHash(): string | undefined;
+    /** Metadata about the model's TensorFlow Lite model file. */
+    get tfliteModel(): TFLiteModel | undefined;
+    /**
+     * True if the model is locked by a server-side operation. You can't make
+     * changes to a locked model. See {@link Model.waitForUnlocked}.
+     */
+    get locked(): boolean;
+    /**
+     * Return the model as a JSON object.
+     */
+    toJSON(): {
+        [key: string]: any;
+    };
+    /**
+     * Wait for the model to be unlocked.
+     *
+     * @param maxTimeMillis - The maximum time in milliseconds to wait.
+     *     If not specified, a default maximum of 2 minutes is used.
+     *
+     * @returns A promise that resolves when the model is unlocked
+     *   or the maximum wait time has passed.
+     */
+    waitForUnlocked(maxTimeMillis?: number): Promise<void>;
+    private static validateAndClone;
+}

package/lib/machine-learning/machine-learning.js

@@ -1,4 +1,4 @@
-/*! firebase-admin v9.12.0 */
+/*! firebase-admin v10.0.1 */
 "use strict";
 /*!
  * Copyright 2020 Google Inc.
@@ -17,19 +17,21 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Model = exports.MachineLearning = void 0;
-var machine_learning_api_client_1 = require("./machine-learning-api-client");
+var index_1 = require("../storage/index");
 var error_1 = require("../utils/error");
 var validator = require("../utils/validator");
-var machine_learning_utils_1 = require("./machine-learning-utils");
 var deep_copy_1 = require("../utils/deep-copy");
 var utils = require("../utils");
+var machine_learning_api_client_1 = require("./machine-learning-api-client");
+var machine_learning_utils_1 = require("./machine-learning-utils");
 /**
- * The Firebase Machine Learning class
+ * The Firebase `MachineLearning` service interface.
  */
 var MachineLearning = /** @class */ (function () {
     /**
-     * @param {FirebaseApp} app The app for this ML service.
+     * @param app - The app for this ML service.
      * @constructor
+     * @internal
      */
     function MachineLearning(app) {
         if (!validator.isNonNullObject(app) || !('options' in app)) {
@@ -44,9 +46,8 @@ var MachineLearning = /** @class */ (function () {
     }
     Object.defineProperty(MachineLearning.prototype, "app", {
         /**
-         * Returns the app associated with this ML instance.
-         *
-         * @return {FirebaseApp} The app associated with this ML instance.
+         *  The {@link firebase-admin.app#App} associated with the current `MachineLearning`
+         *  service instance.
          */
         get: function () {
             return this.appInternal;
@@ -55,11 +56,11 @@ var MachineLearning = /** @class */ (function () {
         configurable: true
     });
     /**
-     * Creates a model in Firebase ML.
+     * Creates a model in the current Firebase project.
      *
-     * @param {ModelOptions} model The model to create.
+     * @param model - The model to create.
      *
-     * @return {Promise<Model>} A Promise fulfilled with the created model.
+     * @returns A Promise fulfilled with the created model.
      */
     MachineLearning.prototype.createModel = function (model) {
         var _this = this;
@@ -69,12 +70,12 @@ var MachineLearning = /** @class */ (function () {
             .then(function (modelResponse) { return new Model(modelResponse, _this.client); });
     };
     /**
-     * Updates a model in Firebase ML.
+     * Updates a model's metadata or model file.
      *
-     * @param {string} modelId The id of the model to update.
-     * @param {ModelOptions} model The model fields to update.
+     * @param modelId - The ID of the model to update.
+     * @param model - The model fields to update.
      *
-     * @return {Promise<Model>} A Promise fulfilled with the updated model.
+     * @returns A Promise fulfilled with the updated model.
      */
     MachineLearning.prototype.updateModel = function (modelId, model) {
         var _this = this;
@@ -85,31 +86,33 @@ var MachineLearning = /** @class */ (function () {
             .then(function (modelResponse) { return new Model(modelResponse, _this.client); });
     };
     /**
-     * Publishes a model in Firebase ML.
+     * Publishes a Firebase ML model.
+     *
+     * A published model can be downloaded to client apps.
      *
-     * @param {string} modelId The id of the model to publish.
+     * @param modelId - The ID of the model to publish.
      *
-     * @return {Promise<Model>} A Promise fulfilled with the published model.
+     * @returns A Promise fulfilled with the published model.
      */
     MachineLearning.prototype.publishModel = function (modelId) {
         return this.setPublishStatus(modelId, true);
     };
     /**
-     * Unpublishes a model in Firebase ML.
+     * Unpublishes a Firebase ML model.
      *
-     * @param {string} modelId The id of the model to unpublish.
+     * @param modelId - The ID of the model to unpublish.
      *
-     * @return {Promise<Model>} A Promise fulfilled with the unpublished model.
+     * @returns A Promise fulfilled with the unpublished model.
      */
     MachineLearning.prototype.unpublishModel = function (modelId) {
         return this.setPublishStatus(modelId, false);
     };
     /**
-     * Gets a model from Firebase ML.
+     * Gets the model specified by the given ID.
      *
-     * @param {string} modelId The id of the model to get.
+     * @param modelId - The ID of the model to get.
      *
-     * @return {Promise<Model>} A Promise fulfilled with the unpublished model.
+     * @returns A Promise fulfilled with the model object.
      */
     MachineLearning.prototype.getModel = function (modelId) {
         var _this = this;
@@ -117,14 +120,14 @@ var MachineLearning = /** @class */ (function () {
             .then(function (modelResponse) { return new Model(modelResponse, _this.client); });
     };
     /**
-     * Lists models from Firebase ML.
+     * Lists the current project's models.
      *
-     * @param {ListModelsOptions} options The listing options.
+     * @param options - The listing options.
      *
-     * @return {Promise<{models: Model[], pageToken?: string}>} A promise that
+     * @returns 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.
+     *     token. For the last page, an empty list of models and no page token
+     *     are returned.
      */
     MachineLearning.prototype.listModels = function (options) {
         var _this = this;
@@ -146,9 +149,9 @@ var MachineLearning = /** @class */ (function () {
         });
     };
     /**
-     * Deletes a model from Firebase ML.
+     * Deletes a model from the current project.
      *
-     * @param {string} modelId The id of the model to delete.
+     * @param modelId - The ID of the model to delete.
      */
     MachineLearning.prototype.deleteModel = function (modelId) {
         return this.client.deleteModel(modelId);
@@ -185,7 +188,7 @@ var MachineLearning = /** @class */ (function () {
         }
         var bucketName = matches[1];
         var blobName = matches[2];
-        var bucket = this.appInternal.storage().bucket(bucketName);
+        var bucket = index_1.getStorage(this.app).bucket(bucketName);
         var blob = bucket.file(blobName);
         return blob.getSignedUrl({
             action: 'read',
@@ -199,11 +202,15 @@ exports.MachineLearning = MachineLearning;
  * A Firebase ML Model output object.
  */
 var Model = /** @class */ (function () {
+    /**
+     * @internal
+     */
     function Model(model, client) {
         this.model = Model.validateAndClone(model);
         this.client = client;
     }
     Object.defineProperty(Model.prototype, "modelId", {
+        /** The ID of the model. */
         get: function () {
             return extractModelId(this.model.name);
         },
@@ -211,6 +218,10 @@ var Model = /** @class */ (function () {
         configurable: true
     });
     Object.defineProperty(Model.prototype, "displayName", {
+        /**
+         * The model's name. This is the name you use from your app to load the
+         * model.
+         */
         get: function () {
             return this.model.displayName;
         },
@@ -218,6 +229,10 @@ var Model = /** @class */ (function () {
         configurable: true
     });
     Object.defineProperty(Model.prototype, "tags", {
+        /**
+         * The model's tags, which can be used to group or filter models in list
+         * operations.
+         */
         get: function () {
             return this.model.tags || [];
         },
@@ -225,6 +240,7 @@ var Model = /** @class */ (function () {
         configurable: true
     });
     Object.defineProperty(Model.prototype, "createTime", {
+        /** The timestamp of the model's creation. */
         get: function () {
             return new Date(this.model.createTime).toUTCString();
         },
@@ -232,6 +248,7 @@ var Model = /** @class */ (function () {
         configurable: true
     });
     Object.defineProperty(Model.prototype, "updateTime", {
+        /** The timestamp of the model's most recent update. */
         get: function () {
             return new Date(this.model.updateTime).toUTCString();
         },
@@ -239,6 +256,7 @@ var Model = /** @class */ (function () {
         configurable: true
     });
     Object.defineProperty(Model.prototype, "validationError", {
+        /** Error message when model validation fails. */
         get: function () {
             var _a, _b;
             return (_b = (_a = this.model.state) === null || _a === void 0 ? void 0 : _a.validationError) === null || _b === void 0 ? void 0 : _b.message;
@@ -247,6 +265,7 @@ var Model = /** @class */ (function () {
         configurable: true
     });
     Object.defineProperty(Model.prototype, "published", {
+        /** True if the model is published. */
         get: function () {
             var _a;
             return ((_a = this.model.state) === null || _a === void 0 ? void 0 : _a.published) || false;
@@ -255,6 +274,10 @@ var Model = /** @class */ (function () {
         configurable: true
     });
     Object.defineProperty(Model.prototype, "etag", {
+        /**
+         * The ETag identifier of the current version of the model. This value
+         * changes whenever you update any of the model's properties.
+         */
         get: function () {
             return this.model.etag;
         },
@@ -262,6 +285,10 @@ var Model = /** @class */ (function () {
         configurable: true
     });
     Object.defineProperty(Model.prototype, "modelHash", {
+        /**
+         * The hash of the model's `tflite` file. This value changes only when
+         * you upload a new TensorFlow Lite model.
+         */
         get: function () {
             return this.model.modelHash;
         },
@@ -269,6 +296,7 @@ var Model = /** @class */ (function () {
         configurable: true
     });
     Object.defineProperty(Model.prototype, "tfliteModel", {
+        /** Metadata about the model's TensorFlow Lite model file. */
         get: function () {
             // Make a copy so people can't directly modify the private this.model object.
             return deep_copy_1.deepCopy(this.model.tfliteModel);
@@ -278,8 +306,8 @@ var Model = /** @class */ (function () {
     });
     Object.defineProperty(Model.prototype, "locked", {
         /**
-         * Locked indicates if there are active long running operations on the model.
-         * Models may not be modified when they are locked.
+         * True if the model is locked by a server-side operation. You can't make
+         * changes to a locked model. See {@link Model.waitForUnlocked}.
          */
         get: function () {
             var _a, _b;
@@ -288,6 +316,9 @@ var Model = /** @class */ (function () {
         enumerable: false,
         configurable: true
     });
+    /**
+     * Return the model as a JSON object.
+     */
     Model.prototype.toJSON = function () {
         // We can't just return this.model because it has extra fields and
         // different formats etc. So we build the expected model object.
@@ -314,9 +345,13 @@ var Model = /** @class */ (function () {
         return jsonModel;
     };
     /**
-     * Wait for the active operations on the model to complete.
-     * @param maxTimeMillis The number of milliseconds to wait for the model to be unlocked. If unspecified,
-     *     a default will be used.
+     * Wait for the model to be unlocked.
+     *
+     * @param maxTimeMillis - The maximum time in milliseconds to wait.
+     *     If not specified, a default maximum of 2 minutes is used.
+     *
+     * @returns A promise that resolves when the model is unlocked
+     *   or the maximum wait time has passed.
      */
     Model.prototype.waitForUnlocked = function (maxTimeMillis) {
         var _this = this;

package/lib/messaging/batch-request-internal.d.ts

@@ -0,0 +1,55 @@
+/*! firebase-admin v10.0.1 */
+/*!
+ * Copyright 2019 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 { HttpClient, HttpResponse } from '../utils/api-request';
+/**
+ * Represents a request that can be sent as part of an HTTP batch request.
+ */
+export interface SubRequest {
+    url: string;
+    body: object;
+    headers?: {
+        [key: string]: any;
+    };
+}
+/**
+ * An HTTP client that can be used to make batch requests. This client is not tied to any service
+ * (FCM or otherwise). Therefore it can be used to make batch requests to any service that allows
+ * it. If this requirement ever arises we can move this implementation to the utils module
+ * where it can be easily shared among other modules.
+ */
+export declare class BatchRequestClient {
+    private readonly httpClient;
+    private readonly batchUrl;
+    private readonly commonHeaders?;
+    /**
+     * @param {HttpClient} httpClient The client that will be used to make HTTP calls.
+     * @param {string} batchUrl The URL that accepts batch requests.
+     * @param {object=} commonHeaders Optional headers that will be included in all requests.
+     *
+     * @constructor
+     */
+    constructor(httpClient: HttpClient, batchUrl: string, commonHeaders?: object | undefined);
+    /**
+     * Sends the given array of sub requests as a single batch, and parses the results into an array
+     * of HttpResponse objects.
+     *
+     * @param requests - An array of sub requests to send.
+     * @returns A promise that resolves when the send operation is complete.
+     */
+    send(requests: SubRequest[]): Promise<HttpResponse[]>;
+    private getMultipartPayload;
+}

package/lib/messaging/batch-request-internal.js

@@ -1,4 +1,4 @@
-/*! firebase-admin v9.12.0 */
+/*! firebase-admin v10.0.1 */
 "use strict";
 /*!
  * Copyright 2019 Google Inc.
@@ -44,8 +44,8 @@ var BatchRequestClient = /** @class */ (function () {
      * Sends the given array of sub requests as a single batch, and parses the results into an array
      * of HttpResponse objects.
      *
-     * @param {SubRequest[]} requests An array of sub requests to send.
-     * @return {Promise<HttpResponse[]>} A promise that resolves when the send operation is complete.
+     * @param requests - An array of sub requests to send.
+     * @returns A promise that resolves when the send operation is complete.
      */
     BatchRequestClient.prototype.send = function (requests) {
         var _this = this;
@@ -89,10 +89,10 @@ exports.BatchRequestClient = BatchRequestClient;
  * API, sets the content-type header to application/http, and the content-transfer-encoding to
  * binary.
  *
- * @param {SubRequest} request A sub request that will be used to populate the part.
- * @param {string} boundary Multipart boundary string.
- * @param {number} idx An index number that is used to set the content-id header.
- * @return {string} The part as a string that can be included in the HTTP body.
+ * @param request - A sub request that will be used to populate the part.
+ * @param boundary - Multipart boundary string.
+ * @param idx - An index number that is used to set the content-id header.
+ * @returns The part as a string that can be included in the HTTP body.
  */
 function createPart(request, boundary, idx) {
     var serializedRequest = serializeSubRequest(request);
@@ -110,8 +110,8 @@ function createPart(request, boundary, idx) {
  * format of the string is the wire format of a typical HTTP request, consisting of a header and a
  * body.
  *
- * @param request {SubRequest} The sub request to be serialized.
- * @return {string} String representation of the SubRequest.
+ * @param request - The sub request to be serialized.
+ * @returns String representation of the SubRequest.
  */
 function serializeSubRequest(request) {
     var requestBody = JSON.stringify(request.body);