firebase-functions 4.5.0 → 4.7.0

package/lib/common/providers/database.d.ts

@@ -1,5 +1,12 @@
 import { App } from "firebase-admin/app";
 import * as database from "firebase-admin/database";
+/**
+ * Pulled from @firebase/database-types, make sure the interface is updated on dependencies upgrades.
+ * Represents a child snapshot of a `Reference` that is being iterated over. The key will never be undefined.
+ */
+interface IteratedDataSnapshot extends DataSnapshot {
+    key: string;
+}
 /**
  * Interface representing a Firebase Realtime database data snapshot.
  */
@@ -97,7 +104,7 @@ export declare class DataSnapshot implements database.DataSnapshot {
      * @return `true` if enumeration was canceled due to your callback
      *   returning `true`.
      */
-    forEach(action: (a: DataSnapshot) => boolean | void): boolean;
+    forEach(action: (a: IteratedDataSnapshot) => boolean | void): boolean;
     /**
      * Returns `true` if the specified child path has (non-`null`) data.
      *
@@ -141,3 +148,4 @@ export declare class DataSnapshot implements database.DataSnapshot {
     /** @hidden */
     private _fullPath;
 }
+export {};

package/lib/common/providers/database.js

@@ -101,6 +101,9 @@ class DataSnapshot {
         let source = this._data;
         if (parts.length) {
             for (const part of parts) {
+                if (source[part] === undefined) {
+                    return null;
+                }
                 source = source[part];
             }
         }

package/lib/common/providers/identity.d.ts

@@ -9,16 +9,17 @@ export { HttpsError };
  */
 export type AuthBlockingEventType = "beforeCreate" | "beforeSignIn";
 /**
- * The UserRecord passed to Cloud Functions is the same UserRecord that is returned by the Firebase Admin
- * SDK.
+ * The `UserRecord` passed to Cloud Functions is the same
+ * {@link https://firebase.google.com/docs/reference/admin/node/firebase-admin.auth.userrecord | UserRecord}
+ * that is returned by the Firebase Admin SDK.
  */
 export type UserRecord = auth.UserRecord;
 /**
- * UserInfo that is part of the UserRecord
+ * `UserInfo` that is part of the `UserRecord`.
  */
 export type UserInfo = auth.UserInfo;
 /**
- * Helper class to create the user metadata in a UserRecord object
+ * Helper class to create the user metadata in a `UserRecord` object.
  */
 export declare class UserRecordMetadata implements auth.UserMetadata {
     creationTime: string;
@@ -28,13 +29,13 @@ export declare class UserRecordMetadata implements auth.UserMetadata {
     toJSON(): AuthUserMetadata;
 }
 /**
- * Helper function that creates a UserRecord Class from data sent over the wire.
+ * Helper function that creates a `UserRecord` class from data sent over the wire.
  * @param wireData data sent over the wire
- * @returns an instance of UserRecord with correct toJSON functions
+ * @returns an instance of `UserRecord` with correct toJSON functions
  */
 export declare function userRecordConstructor(wireData: Record<string, unknown>): UserRecord;
 /**
- * User info that is part of the AuthUserRecord
+ * User info that is part of the `AuthUserRecord`.
  */
 export interface AuthUserInfo {
     /**
@@ -110,7 +111,7 @@ export interface AuthMultiFactorSettings {
     enrolledFactors: AuthMultiFactorInfo[];
 }
 /**
- * The UserRecord passed to auth blocking Cloud Functions from the identity platform.
+ * The `UserRecord` passed to auth blocking functions from the identity platform.
  */
 export interface AuthUserRecord {
     /**
@@ -205,7 +206,7 @@ export interface AuthEventContext extends EventContext {
     additionalUserInfo?: AdditionalUserInfo;
     credential?: Credential;
 }
-/** Defines the auth event for v2 blocking events */
+/** Defines the auth event for 2nd gen blocking events */
 export interface AuthBlockingEvent extends AuthEventContext {
     data: AuthUserRecord;
 }
@@ -213,7 +214,7 @@ export interface AuthBlockingEvent extends AuthEventContext {
  * The reCAPTCHA action options.
  */
 export type RecaptchaActionOptions = "ALLOW" | "BLOCK";
-/** The handler response type for beforeCreate blocking events */
+/** The handler response type for `beforeCreate` blocking events */
 export interface BeforeCreateResponse {
     displayName?: string;
     disabled?: boolean;
@@ -222,7 +223,7 @@ export interface BeforeCreateResponse {
     customClaims?: object;
     recaptchaActionOverride?: RecaptchaActionOptions;
 }
-/** The handler response type for beforeSignIn blocking events */
+/** The handler response type for `beforeSignIn` blocking events */
 export interface BeforeSignInResponse extends BeforeCreateResponse {
     sessionClaims?: object;
 }

package/lib/common/providers/identity.js

@@ -51,7 +51,7 @@ const EVENT_MAPPING = {
     beforeSignIn: "providers/cloud.auth/eventTypes/user.beforeSignIn",
 };
 /**
- * Helper class to create the user metadata in a UserRecord object
+ * Helper class to create the user metadata in a `UserRecord` object.
  */
 class UserRecordMetadata {
     constructor(creationTime, lastSignInTime) {
@@ -68,9 +68,9 @@ class UserRecordMetadata {
 }
 exports.UserRecordMetadata = UserRecordMetadata;
 /**
- * Helper function that creates a UserRecord Class from data sent over the wire.
+ * Helper function that creates a `UserRecord` class from data sent over the wire.
  * @param wireData data sent over the wire
- * @returns an instance of UserRecord with correct toJSON functions
+ * @returns an instance of `UserRecord` with correct toJSON functions
  */
 function userRecordConstructor(wireData) {
     // Falsey values from the wire format proto get lost when converted to JSON, this adds them back.
@@ -122,7 +122,7 @@ function userRecordConstructor(wireData) {
 }
 exports.userRecordConstructor = userRecordConstructor;
 /**
- * Checks for a valid identity platform web request, otherwise throws an HttpsError
+ * Checks for a valid identity platform web request, otherwise throws an HttpsError.
  * @internal
  */
 function isValidRequest(req) {
@@ -156,7 +156,7 @@ function unsafeDecodeAuthBlockingToken(token) {
     return decoded;
 }
 /**
- * Helper function to parse the decoded metadata object into a UserMetaData object
+ * Helper function to parse the decoded metadata object into a `UserMetaData` object
  * @internal
  */
 function parseMetadata(metadata) {
@@ -173,7 +173,7 @@ function parseMetadata(metadata) {
 }
 exports.parseMetadata = parseMetadata;
 /**
- * Helper function to parse the decoded user info array into an AuthUserInfo array
+ * Helper function to parse the decoded user info array into an `AuthUserInfo` array.
  * @internal
  */
 function parseProviderData(providerData) {
@@ -192,7 +192,7 @@ function parseProviderData(providerData) {
 }
 exports.parseProviderData = parseProviderData;
 /**
- * Helper function to parse the date into a UTC string
+ * Helper function to parse the date into a UTC string.
  * @internal
  */
 function parseDate(tokensValidAfterTime) {
@@ -276,7 +276,7 @@ function parseAuthUserRecord(decodedJWTUserRecord) {
     };
 }
 exports.parseAuthUserRecord = parseAuthUserRecord;
-/** Helper to get the AdditionalUserInfo from the decoded jwt */
+/** Helper to get the `AdditionalUserInfo` from the decoded JWT */
 function parseAdditionalUserInfo(decodedJWT) {
     let profile;
     let username;
@@ -327,7 +327,7 @@ function generateResponsePayload(authResponse) {
     return result;
 }
 exports.generateResponsePayload = generateResponsePayload;
-/** Helper to get the Credential from the decoded jwt */
+/** Helper to get the Credential from the decoded JWT */
 function parseAuthCredential(decodedJWT, time) {
     if (!decodedJWT.sign_in_attributes &&
         !decodedJWT.oauth_id_token &&

package/lib/common/providers/tasks.d.ts

@@ -61,8 +61,8 @@ export interface TaskContext {
     /**
      * The "short" name of the task, or, if no name was specified at creation, a unique
      * system-generated id.
-     * This is the my-task-id value in the complete task name, ie, task_name =
-     * projects/my-project-id/locations/my-location/queues/my-queue-id/tasks/my-task-id.
+     * This is the "my-task-id" value in the complete task name, such as "task_name =
+     * projects/my-project-id/locations/my-location/queues/my-queue-id/tasks/my-task-id."
      * Populated via the `X-CloudTasks-TaskName` header.
      */
     id: string;

package/lib/params/index.d.ts

@@ -3,6 +3,7 @@
  * @alpha
  */
 import { BooleanParam, Expression, IntParam, Param, ParamOptions, SecretParam, StringParam, ListParam } from "./types";
+export { BUCKET_PICKER, TextInput, SelectInput, SelectOptions, MultiSelectInput, select, multiSelect, } from "./types";
 export { ParamOptions, Expression };
 type SecretOrExpr = Param<any> | SecretParam;
 export declare const declaredParams: SecretOrExpr[];

package/lib/params/index.js

@@ -21,13 +21,17 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.defineList = exports.defineFloat = exports.defineInt = exports.defineBoolean = exports.defineString = exports.defineSecret = exports.storageBucket = exports.gcloudProject = exports.projectID = exports.databaseURL = exports.clearParams = exports.declaredParams = exports.Expression = void 0;
+exports.defineList = exports.defineFloat = exports.defineInt = exports.defineBoolean = exports.defineString = exports.defineSecret = exports.storageBucket = exports.gcloudProject = exports.projectID = exports.databaseURL = exports.clearParams = exports.declaredParams = exports.Expression = exports.multiSelect = exports.select = exports.BUCKET_PICKER = void 0;
 /**
  * @hidden
  * @alpha
  */
 const types_1 = require("./types");
 Object.defineProperty(exports, "Expression", { enumerable: true, get: function () { return types_1.Expression; } });
+var types_2 = require("./types");
+Object.defineProperty(exports, "BUCKET_PICKER", { enumerable: true, get: function () { return types_2.BUCKET_PICKER; } });
+Object.defineProperty(exports, "select", { enumerable: true, get: function () { return types_2.select; } });
+Object.defineProperty(exports, "multiSelect", { enumerable: true, get: function () { return types_2.multiSelect; } });
 exports.declaredParams = [];
 /**
  * Use a helper to manage the list such that params are uniquely

package/lib/params/types.d.ts

@@ -30,33 +30,35 @@ export declare class CompareExpression<T extends string | number | boolean | str
 }
 /** @hidden */
 type ParamValueType = "string" | "list" | "boolean" | "int" | "float" | "secret";
-type ParamInput<T> = {
-    text: TextInput<T>;
-} | {
-    select: SelectInput<T>;
-} | {
-    multiSelect: MultiSelectInput;
-} | {
-    resource: ResourceInput;
-};
+/** Create a select input from a series of values. */
+export declare function select<T>(options: T[]): SelectInput<T>;
+/** Create a select input from a map of labels to vaues. */
+export declare function select<T>(optionsWithLabels: Record<string, T>): SelectInput<T>;
+/** Create a multi-select input from a series of values. */
+export declare function multiSelect(options: string[]): MultiSelectInput;
+/** Create a multi-select input from map of labels to values. */
+export declare function multiSelect(options: Record<string, string>): MultiSelectInput;
+type ParamInput<T> = TextInput<T> | SelectInput<T> | (T extends string[] ? MultiSelectInput : never) | (T extends string ? ResourceInput : never);
 /**
  * Specifies that a Param's value should be determined by prompting the user
  * to type it in interactively at deploy-time. Input that does not match the
  * provided validationRegex, if present, will be retried.
  */
 export interface TextInput<T = unknown> {
-    example?: string;
-    /**
-     * A regular expression (or an escaped string to compile into a regular
-     * expression) which the prompted text must satisfy; the prompt will retry
-     * until input matching the regex is provided.
-     */
-    validationRegex?: string | RegExp;
-    /**
-     * A custom error message to display when retrying the prompt based on input
-     * failing to conform to the validationRegex,
-     */
-    validationErrorMessage?: string;
+    text: {
+        example?: string;
+        /**
+         * A regular expression (or an escaped string to compile into a regular
+         * expression) which the prompted text must satisfy; the prompt will retry
+         * until input matching the regex is provided.
+         */
+        validationRegex?: string | RegExp;
+        /**
+         * A custom error message to display when retrying the prompt based on input
+         * failing to conform to the validationRegex,
+         */
+        validationErrorMessage?: string;
+    };
 }
 /**
  * Specifies that a Param's value should be determined by having the user
@@ -65,15 +67,18 @@ export interface TextInput<T = unknown> {
  */
 export interface ResourceInput {
     resource: {
-        type: string;
+        type: "storage.googleapis.com/Bucket";
     };
 }
+export declare const BUCKET_PICKER: ResourceInput;
 /**
  * Specifies that a Param's value should be determined by having the user select
  * from a list of pre-canned options interactively at deploy-time.
  */
 export interface SelectInput<T = unknown> {
-    options: Array<SelectOptions<T>>;
+    select: {
+        options: Array<SelectOptions<T>>;
+    };
 }
 /**
  * Specifies that a Param's value should be determined by having the user select
@@ -81,7 +86,9 @@ export interface SelectInput<T = unknown> {
  * Will result in errors if used on Params of type other than string[].
  */
 export interface MultiSelectInput {
-    options: Array<SelectOptions<string>>;
+    multiSelect: {
+        options: Array<SelectOptions<string>>;
+    };
 }
 /**
  * One of the options provided to a SelectInput, containing a value and

package/lib/params/types.js

@@ -21,7 +21,7 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ListParam = exports.BooleanParam = exports.FloatParam = exports.IntParam = exports.InternalExpression = exports.StringParam = exports.SecretParam = exports.Param = exports.CompareExpression = exports.TernaryExpression = exports.Expression = void 0;
+exports.ListParam = exports.BooleanParam = exports.FloatParam = exports.IntParam = exports.InternalExpression = exports.StringParam = exports.SecretParam = exports.Param = exports.BUCKET_PICKER = exports.multiSelect = exports.select = exports.CompareExpression = exports.TernaryExpression = exports.Expression = void 0;
 const logger = require("../logger");
 /*
  * A CEL expression which can be evaluated during function deployment, and
@@ -142,6 +142,43 @@ class CompareExpression extends Expression {
     }
 }
 exports.CompareExpression = CompareExpression;
+/** Create a select input from a series of values or a map of labels to values */
+function select(options) {
+    let wireOpts;
+    if (Array.isArray(options)) {
+        wireOpts = options.map((opt) => ({ value: opt }));
+    }
+    else {
+        wireOpts = Object.entries(options).map(([label, value]) => ({ label, value }));
+    }
+    return {
+        select: {
+            options: wireOpts,
+        },
+    };
+}
+exports.select = select;
+/** Create a multi-select input from a series of values or map of labels to values. */
+function multiSelect(options) {
+    let wireOpts;
+    if (Array.isArray(options)) {
+        wireOpts = options.map((opt) => ({ value: opt }));
+    }
+    else {
+        wireOpts = Object.entries(options).map(([label, value]) => ({ label, value }));
+    }
+    return {
+        multiSelect: {
+            options: wireOpts,
+        },
+    };
+}
+exports.multiSelect = multiSelect;
+exports.BUCKET_PICKER = {
+    resource: {
+        type: "storage.googleapis.com/Bucket",
+    },
+};
 /**
  * Represents a parametrized value that will be read from .env files if present,
  * or prompted for by the CLI if missing. Instantiate these with the defineX

package/lib/v1/function-configuration.d.ts

@@ -177,7 +177,8 @@ export interface RuntimeOptions {
      *
      * @remarks
      * Set this to true to enable the App Check replay protection feature by consuming the App Check token on callable
-     * request. Tokens that are found to be already consumed will have request.app.alreadyConsumed property set true.
+     * request. Tokens that are found to be already consumed will have the `request.app.alreadyConsumed` property set
+     * to true.
      *
      *
      * Tokens are only considered to be consumed if it is sent to the App Check service by setting this option to true.
@@ -188,10 +189,10 @@ export interface RuntimeOptions {
      * performance and can potentially deplete your attestation providers' quotas faster. Use this feature only for
      * protecting low volume, security critical, or expensive operations.
      *
-     * This option does not affect the enforceAppCheck option. Setting the latter to true will cause the callable function
-     * to automatically respond with a 401 Unauthorized status code when request includes an invalid App Check token.
-     * When request includes valid but consumed App Check tokens, requests will not be automatically rejected. Instead,
-     * the request.app.alreadyConsumed property will be set to true and pass the execution to the handler code for making
+     * This option does not affect the `enforceAppCheck` option. Setting the latter to true will cause the callable function
+     * to automatically respond with a 401 Unauthorized status code when the request includes an invalid App Check token.
+     * When the request includes valid but consumed App Check tokens, requests will not be automatically rejected. Instead,
+     * the `request.app.alreadyConsumed` property will be set to true and pass the execution to the handler code for making
      * further decisions, such as requiring additional security checks or rejecting the request.
      */
     consumeAppCheckToken?: boolean;

package/lib/v2/providers/https.js

@@ -119,11 +119,12 @@ function onCall(optsOrHandler, handler) {
     // onCallHandler sniffs the function length to determine which API to present.
     // fix the length to prevent api versions from being mismatched.
     const fixedLen = (req) => handler(req);
-    const func = (0, https_1.onCallHandler)({
+    let func = (0, https_1.onCallHandler)({
         cors: { origin, methods: "POST" },
         enforceAppCheck: (_a = opts.enforceAppCheck) !== null && _a !== void 0 ? _a : options.getGlobalOptions().enforceAppCheck,
         consumeAppCheckToken: opts.consumeAppCheckToken,
     }, fixedLen);
+    func = (0, trace_1.wrapTraceContext)(func);
     Object.defineProperty(func, "__trigger", {
         get: () => {
             const baseOpts = options.optionsToTriggerAnnotations(options.getGlobalOptions());

package/lib/v2/providers/storage.d.ts

@@ -159,7 +159,7 @@ export interface StorageEvent extends CloudEvent<StorageObjectData> {
 /** StorageOptions extend EventHandlerOptions with a bucket name  */
 export interface StorageOptions extends options.EventHandlerOptions {
     /** The name of the bucket containing this object. */
-    bucket?: string;
+    bucket?: string | Expression<string>;
     /**
      * If true, do not deploy or emulate this function.
      */
@@ -259,7 +259,7 @@ export declare function onObjectArchived(handler: (event: StorageEvent) => any |
  * @param bucket - The name of the bucket containing this object.
  * @param handler - Event handler which is run every time a Google Cloud Storage archival occurs.
  */
-export declare function onObjectArchived(bucket: string, handler: (event: StorageEvent) => any | Promise<any>): CloudFunction<StorageEvent>;
+export declare function onObjectArchived(bucket: string | Expression<string>, handler: (event: StorageEvent) => any | Promise<any>): CloudFunction<StorageEvent>;
 /**
  * Event handler sent only when a bucket has enabled object versioning.
  * This event indicates that the live version of an object has become an
@@ -292,7 +292,7 @@ export declare function onObjectFinalized(handler: (event: StorageEvent) => any
  * @param bucket - The name of the bucket containing this object.
  * @param handler - Event handler which is run every time a Google Cloud Storage object creation occurs.
  */
-export declare function onObjectFinalized(bucket: string, handler: (event: StorageEvent) => any | Promise<any>): CloudFunction<StorageEvent>;
+export declare function onObjectFinalized(bucket: string | Expression<string>, handler: (event: StorageEvent) => any | Promise<any>): CloudFunction<StorageEvent>;
 /**
  * Event handler which fires every time a Google Cloud Storage object
  * creation occurs.
@@ -329,7 +329,7 @@ export declare function onObjectDeleted(handler: (event: StorageEvent) => any |
  * @param bucket - The name of the bucket containing this object.
  * @param handler - Event handler which is run every time a Google Cloud Storage object deletion occurs.
  */
-export declare function onObjectDeleted(bucket: string, handler: (event: StorageEvent) => any | Promise<any>): CloudFunction<StorageEvent>;
+export declare function onObjectDeleted(bucket: string | Expression<string>, handler: (event: StorageEvent) => any | Promise<any>): CloudFunction<StorageEvent>;
 /**
  * Event handler which fires every time a Google Cloud Storage deletion occurs.
  *
@@ -358,7 +358,7 @@ export declare function onObjectMetadataUpdated(handler: (event: StorageEvent) =
  * @param bucket - The name of the bucket containing this object.
  * @param handler - Event handler which is run every time a Google Cloud Storage object metadata update occurs.
  */
-export declare function onObjectMetadataUpdated(bucket: string, handler: (event: StorageEvent) => any | Promise<any>): CloudFunction<StorageEvent>;
+export declare function onObjectMetadataUpdated(bucket: string | Expression<string>, handler: (event: StorageEvent) => any | Promise<any>): CloudFunction<StorageEvent>;
 /**
  * Event handler which fires every time the metadata of an existing object
  * changes.

package/lib/v2/providers/storage.js

@@ -161,7 +161,8 @@ function getOptsAndBucket(bucketOrOpts) {
     var _a;
     let bucket;
     let opts;
-    if (typeof bucketOrOpts === "string") {
+    // If bucket is a string or Expression<string>
+    if (typeof bucketOrOpts === "string" || "value" in bucketOrOpts) {
         bucket = bucketOrOpts;
         opts = {};
     }
@@ -174,7 +175,7 @@ function getOptsAndBucket(bucketOrOpts) {
         throw new Error("Missing bucket name. If you are unit testing, please provide a bucket name" +
             " by providing bucket name directly in the event handler or by setting process.env.FIREBASE_CONFIG.");
     }
-    if (!/^[a-z\d][a-z\d\\._-]{1,230}[a-z\d]$/.test(bucket)) {
+    if (typeof bucket === "string" && !/^[a-z\d][a-z\d\\._-]{1,230}[a-z\d]$/.test(bucket)) {
         throw new Error(`Invalid bucket name ${bucket}`);
     }
     return [opts, bucket];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firebase-functions",
-  "version": "4.5.0",
+  "version": "4.7.0",
   "description": "Firebase SDK for Cloud Functions",
   "keywords": [
     "firebase",
@@ -225,7 +225,7 @@
     "eslint-config-prettier": "^8.3.0",
     "eslint-plugin-jsdoc": "^39.2.9",
     "eslint-plugin-prettier": "^4.0.0",
-    "firebase-admin": "^11.8.0",
+    "firebase-admin": "^12.0.0",
     "js-yaml": "^3.13.1",
     "jsdom": "^16.2.1",
     "jsonwebtoken": "^9.0.0",
@@ -245,7 +245,7 @@
     "yargs": "^15.3.1"
   },
   "peerDependencies": {
-    "firebase-admin": "^10.0.0 || ^11.0.0"
+    "firebase-admin": "^10.0.0 || ^11.0.0 || ^12.0.0"
   },
   "engines": {
     "node": ">=14.10.0"