firebase-functions 7.2.6-rc.0 → 7.3.0-rc.0

package/lib/common/api.d.ts

@@ -0,0 +1,7 @@
+export type GoogleCloudApi = `${string}.googleapis.com`;
+/**
+ * Declare that this project requires a specific Google Cloud API to be enabled.
+ * @param api The API name, e.g. "secretmanager.googleapis.com"
+ * @param reason Optional reason why the API is needed.
+ */
+export declare function requiresAPI(api: GoogleCloudApi, reason?: string): void;

package/lib/common/api.js

@@ -0,0 +1,34 @@
+
+//#region src/common/api.ts
+let globalRequiredAPIs = [];
+/**
+* Declare that this project requires a specific Google Cloud API to be enabled.
+* @param api The API name, e.g. "secretmanager.googleapis.com"
+* @param reason Optional reason why the API is needed.
+*/
+function requiresAPI(api, reason = "") {
+	if (!api || typeof api !== "string" || !api.endsWith(".googleapis.com")) {
+		throw new Error("requiresAPI: 'api' must be a non-empty string ending with '.googleapis.com'.");
+	}
+	globalRequiredAPIs.push({
+		api,
+		reason
+	});
+}
+/**
+* @internal
+*/
+function getGlobalRequiredAPIs() {
+	return globalRequiredAPIs;
+}
+/**
+* @internal
+*/
+function clearGlobalRequiredAPIs() {
+	globalRequiredAPIs = [];
+}
+
+//#endregion
+exports.clearGlobalRequiredAPIs = clearGlobalRequiredAPIs;
+exports.getGlobalRequiredAPIs = getGlobalRequiredAPIs;
+exports.requiresAPI = requiresAPI;

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

@@ -1,7 +1,9 @@
+import cors from "cors";
 import * as express from "express";
 import { DecodedAppCheckToken } from "firebase-admin/app-check";
 import { DecodedIdToken } from "firebase-admin/auth";
 import { TaskContext } from "./tasks";
+import { Expression } from "../../params";
 /** An express request with the wire format representation of the request body. */
 export interface Request extends express.Request {
     /** The wire format representation of the request body. */
@@ -240,4 +242,9 @@ export declare function decode(data: any): any;
 type TokenStatus = "MISSING" | "VALID" | "INVALID";
 /** @interanl */
 export declare function checkAuthToken(req: Request, ctx: CallableContext | TaskContext): Promise<TokenStatus>;
+export type CorsOption = string | Expression<string> | Expression<string[]> | boolean | RegExp | Array<string | RegExp>;
+export declare function resolveCorsOrigin(corsOption?: CorsOption): cors.CorsOptions["origin"];
+export type CorsInfo = Omit<cors.CorsOptions, "origin"> & {
+    origin?: CorsOption;
+};
 export {};

package/lib/common/providers/https.js

@@ -1,5 +1,7 @@
 const require_rolldown_runtime = require('../../_virtual/rolldown_runtime.js');
 const require_logger_index = require('../../logger/index.js');
+const require_params_types = require('../../params/types.js');
+require('../../params/index.js');
 const require_common_app = require('../app.js');
 const require_common_debug = require('../debug.js');
 let firebase_admin_auth = require("firebase-admin/auth");
@@ -373,13 +375,49 @@ async function checkAppCheckToken(req, ctx, options) {
 		return "INVALID";
 	}
 }
+function resolveCorsOrigin(corsOption) {
+	let origin;
+	if (corsOption instanceof require_params_types.Expression) {
+		try {
+			origin = corsOption.runtimeValue();
+		} catch (e) {
+			require_logger_index.warn(`Failed to resolve CORS parameter: ${e}`);
+			origin = false;
+		}
+	} else {
+		origin = corsOption;
+	}
+	if (Array.isArray(origin) && origin.length === 0) {
+		require_logger_index.warn("CORS parameter resolved to an empty array. Disabling CORS.");
+		origin = false;
+	}
+	if (origin === "") {
+		require_logger_index.warn("CORS parameter resolved to an empty string. Disabling CORS.");
+		origin = false;
+	}
+	if (require_common_debug.isDebugFeatureEnabled("enableCors")) {
+		origin = origin === false ? false : true;
+	}
+	if (origin === undefined) {
+		origin = true;
+	}
+	if (Array.isArray(origin) && origin.length === 1) {
+		origin = origin[0];
+	}
+	return origin;
+}
 /** @internal */
 function onCallHandler(options, handler, version) {
 	const wrapped = wrapOnCallHandler(options, handler, version);
 	return (req, res) => {
 		return new Promise((resolve) => {
 			res.on("finish", resolve);
-			(0, cors.default)(options.cors)(req, res, () => {
+			const origin = resolveCorsOrigin(options.cors.origin);
+			const corsOptions = {
+				...options.cors,
+				origin
+			};
+			(0, cors.default)(corsOptions)(req, res, () => {
 				resolve(wrapped(req, res));
 			});
 		});
@@ -583,6 +621,7 @@ exports.decode = decode;
 exports.encode = encode;
 exports.isValidRequest = isValidRequest;
 exports.onCallHandler = onCallHandler;
+exports.resolveCorsOrigin = resolveCorsOrigin;
 exports.unsafeDecodeAppCheckToken = unsafeDecodeAppCheckToken;
 exports.unsafeDecodeIdToken = unsafeDecodeIdToken;
 exports.unsafeDecodeToken = unsafeDecodeToken;

package/lib/esm/common/api.mjs

@@ -0,0 +1,31 @@
+//#region src/common/api.ts
+let globalRequiredAPIs = [];
+/**
+* Declare that this project requires a specific Google Cloud API to be enabled.
+* @param api The API name, e.g. "secretmanager.googleapis.com"
+* @param reason Optional reason why the API is needed.
+*/
+function requiresAPI(api, reason = "") {
+	if (!api || typeof api !== "string" || !api.endsWith(".googleapis.com")) {
+		throw new Error("requiresAPI: 'api' must be a non-empty string ending with '.googleapis.com'.");
+	}
+	globalRequiredAPIs.push({
+		api,
+		reason
+	});
+}
+/**
+* @internal
+*/
+function getGlobalRequiredAPIs() {
+	return globalRequiredAPIs;
+}
+/**
+* @internal
+*/
+function clearGlobalRequiredAPIs() {
+	globalRequiredAPIs = [];
+}
+
+//#endregion
+export { clearGlobalRequiredAPIs, getGlobalRequiredAPIs, requiresAPI };

package/lib/esm/common/providers/https.mjs

@@ -1,4 +1,6 @@
 import { debug, error, warn } from "../../logger/index.mjs";
+import { Expression } from "../../params/types.mjs";
+import "../../params/index.mjs";
 import { getApp } from "../app.mjs";
 import { isDebugFeatureEnabled } from "../debug.mjs";
 import { getAuth } from "firebase-admin/auth";
@@ -369,13 +371,49 @@ async function checkAppCheckToken(req, ctx, options) {
 		return "INVALID";
 	}
 }
+function resolveCorsOrigin(corsOption) {
+	let origin;
+	if (corsOption instanceof Expression) {
+		try {
+			origin = corsOption.runtimeValue();
+		} catch (e) {
+			warn(`Failed to resolve CORS parameter: ${e}`);
+			origin = false;
+		}
+	} else {
+		origin = corsOption;
+	}
+	if (Array.isArray(origin) && origin.length === 0) {
+		warn("CORS parameter resolved to an empty array. Disabling CORS.");
+		origin = false;
+	}
+	if (origin === "") {
+		warn("CORS parameter resolved to an empty string. Disabling CORS.");
+		origin = false;
+	}
+	if (isDebugFeatureEnabled("enableCors")) {
+		origin = origin === false ? false : true;
+	}
+	if (origin === undefined) {
+		origin = true;
+	}
+	if (Array.isArray(origin) && origin.length === 1) {
+		origin = origin[0];
+	}
+	return origin;
+}
 /** @internal */
 function onCallHandler(options, handler, version) {
 	const wrapped = wrapOnCallHandler(options, handler, version);
 	return (req, res) => {
 		return new Promise((resolve) => {
 			res.on("finish", resolve);
-			cors(options.cors)(req, res, () => {
+			const origin = resolveCorsOrigin(options.cors.origin);
+			const corsOptions = {
+				...options.cors,
+				origin
+			};
+			cors(corsOptions)(req, res, () => {
 				resolve(wrapped(req, res));
 			});
 		});
@@ -570,4 +608,4 @@ function withErrorHandler(handler) {
 }
 
 //#endregion
-export { CALLABLE_AUTH_HEADER, DEFAULT_HEARTBEAT_SECONDS, HttpsError, ORIGINAL_AUTH_HEADER, checkAuthToken, decode, encode, isValidRequest, onCallHandler, unsafeDecodeAppCheckToken, unsafeDecodeIdToken, unsafeDecodeToken, withErrorHandler };
+export { CALLABLE_AUTH_HEADER, DEFAULT_HEARTBEAT_SECONDS, HttpsError, ORIGINAL_AUTH_HEADER, checkAuthToken, decode, encode, isValidRequest, onCallHandler, resolveCorsOrigin, unsafeDecodeAppCheckToken, unsafeDecodeIdToken, unsafeDecodeToken, withErrorHandler };

package/lib/esm/lifecycle/index.mjs

@@ -0,0 +1,55 @@
+//#region src/lifecycle/index.ts
+/**
+* Use a global singleton to manage the list of declared lifecycle hooks.
+*
+* This ensures that lifecycle hooks are shared between CJS and ESM builds,
+* avoiding the "dual-package hazard" where the src/bin/firebase-functions.ts (CJS) sees
+* an empty list while the user's code (ESM) populates a different list.
+*/
+const majorVersion = typeof "7" !== "undefined" ? "7" : "0";
+const GLOBAL_SYMBOL = Symbol.for(`firebase-functions:lifecycle:declaredHooks:v${majorVersion}`);
+const globalSymbols = globalThis;
+if (!globalSymbols[GLOBAL_SYMBOL]) {
+	globalSymbols[GLOBAL_SYMBOL] = {};
+}
+/**
+* Singleton dictionary of declared lifecycle hooks.
+* @internal
+*/
+const declaredLifecycleHooks = globalSymbols[GLOBAL_SYMBOL];
+/**
+* Registers an action to be executed automatically post-deployment when resources in this codebase
+* are deployed for the first time.
+*
+* @param action The lifecycle action to execute.
+*/
+function afterFirstDeploy(action) {
+	if (declaredLifecycleHooks.afterFirstDeploy) {
+		throw new Error("Only one afterFirstDeploy lifecycle hook is allowed per codebase.");
+	}
+	declaredLifecycleHooks.afterFirstDeploy = action;
+}
+/**
+* Registers an action to be executed automatically post-deployment when resources in this codebase
+* are updated.
+*
+* @param action The lifecycle action to execute.
+*/
+function afterRedeploy(action) {
+	if (declaredLifecycleHooks.afterRedeploy) {
+		throw new Error("Only one afterRedeploy lifecycle hook is allowed per codebase.");
+	}
+	declaredLifecycleHooks.afterRedeploy = action;
+}
+/**
+* Helper to clear declared lifecycle hooks.
+* @internal
+*/
+function clearDeclaredLifecycleHooks() {
+	for (const key of Object.keys(declaredLifecycleHooks)) {
+		delete declaredLifecycleHooks[key];
+	}
+}
+
+//#endregion
+export { afterFirstDeploy, afterRedeploy, clearDeclaredLifecycleHooks, declaredLifecycleHooks };

package/lib/esm/runtime/loader.mjs

@@ -1,5 +1,8 @@
 import { __require } from "../_virtual/rolldown_runtime.mjs";
 import { declaredParams } from "../params/index.mjs";
+import { declaredRoles } from "../security/roles.mjs";
+import { clearGlobalRequiredAPIs, getGlobalRequiredAPIs } from "../common/api.mjs";
+import { clearDeclaredLifecycleHooks, declaredLifecycleHooks } from "../lifecycle/index.mjs";
 import * as path from "path";
 import * as url from "url";
 
@@ -7,9 +10,7 @@ import * as url from "url";
 /**
 * Dynamically load import function to prevent TypeScript from
 * transpiling into a require.
-*
 * See https://github.com/microsoft/TypeScript/issues/43329.
-*
 */
 const dynamicImport = new Function("modulePath", "return import(modulePath)");
 async function loadModule(functionsDir) {
@@ -116,6 +117,8 @@ async function loadStack(functionsDir) {
 	const extensions = {};
 	const mod = await loadModule(functionsDir);
 	extractStack(mod, endpoints, requiredAPIs, extensions);
+	requiredAPIs.push(...getGlobalRequiredAPIs());
+	clearGlobalRequiredAPIs();
 	const stack = {
 		endpoints,
 		specVersion: "v1alpha1",
@@ -125,6 +128,13 @@ async function loadStack(functionsDir) {
 	if (declaredParams.length > 0) {
 		stack.params = declaredParams.map((p) => p.toSpec());
 	}
+	if (declaredRoles.size > 0) {
+		stack.requiredRoles = Array.from(declaredRoles);
+	}
+	if (Object.keys(declaredLifecycleHooks).length > 0) {
+		stack.lifecycleHooks = { ...declaredLifecycleHooks };
+	}
+	clearDeclaredLifecycleHooks();
 	return stack;
 }
 

package/lib/esm/runtime/manifest.mjs

@@ -7,7 +7,6 @@ import { RESET_VALUE, ResetValue } from "../common/options.mjs";
 * Returns the JSON representation of a ManifestStack, which has CEL
 * expressions in its options as object types, with its expressions
 * transformed into the actual CEL strings.
-*
 * @alpha
 */
 function stackToWire(stack) {

package/lib/esm/security/roles.mjs

@@ -0,0 +1,17 @@
+//#region src/security/roles.ts
+/**
+* Global set of declared IAM roles required by this codebase.
+* Accumulated in-memory during manifest generation.
+*/
+const declaredRoles = new Set();
+/**
+* Registers a role to be required by this codebase.
+* Automatically deduplicates using the Set.
+* @internal
+*/
+function registerRole(role) {
+	declaredRoles.add(role);
+}
+
+//#endregion
+export { declaredRoles, registerRole };

package/lib/esm/v1/cloud-functions.mjs

@@ -13,6 +13,7 @@ const WILDCARD_REGEX = new RegExp("{[^/{}]*}", "g");
 /** @internal */
 function makeCloudFunction({ contextOnlyHandler, dataConstructor = (raw) => raw.data, eventType, handler, labels = {}, legacyEventType, options = {}, provider, service, triggerResource }) {
 	handler = withInit(handler ?? contextOnlyHandler);
+	const contextOnlyHandlerWithInit = contextOnlyHandler && withInit(contextOnlyHandler);
 	const cloudFunction = (data, context) => {
 		if (legacyEventType && context.eventType === legacyEventType) {
 			context.eventType = provider + "." + eventType;
@@ -42,7 +43,7 @@ function makeCloudFunction({ contextOnlyHandler, dataConstructor = (raw) => raw.
 		}
 		let promise;
 		if (labels && labels["deployment-scheduled"]) {
-			promise = contextOnlyHandler(context);
+			promise = contextOnlyHandlerWithInit(context);
 		} else {
 			const dataOrChange = dataConstructor(event);
 			promise = handler(dataOrChange, context);

package/lib/esm/v1/function-builder.mjs

@@ -200,7 +200,21 @@ var FunctionBuilder = class {
 			console.warn("RuntimeOptions.failurePolicy is not supported in https functions.");
 		}
 		return {
-			onRequest: (handler) => _onRequestWithOptions(handler, this.options),
+			onRequest: (optsOrHandler, handler) => {
+				let opts;
+				let userHandler;
+				if (typeof optsOrHandler === "function") {
+					opts = {};
+					userHandler = optsOrHandler;
+				} else {
+					opts = optsOrHandler;
+					userHandler = handler;
+				}
+				return _onRequestWithOptions(userHandler, {
+					...this.options,
+					...opts
+				});
+			},
 			onCall: (handler) => _onCallWithOptions(handler, this.options)
 		};
 	}

package/lib/esm/v1/index.mjs

@@ -1,5 +1,6 @@
 import { logger_exports } from "../logger/index.mjs";
 import { params_exports } from "../params/index.mjs";
+import { requiresAPI } from "../common/api.mjs";
 import { RESET_VALUE } from "../common/options.mjs";
 import { firebaseConfig } from "../common/config.mjs";
 import { setApp } from "../common/app.mjs";
@@ -24,4 +25,4 @@ import { FunctionBuilder, region, runWith } from "./function-builder.mjs";
 const app = { setEmulatedAdminApp: setApp };
 
 //#endregion
-export { Change, DEFAULT_FAILURE_POLICY, FunctionBuilder, INGRESS_SETTINGS_OPTIONS, MAX_NUMBER_USER_LABELS, MAX_TIMEOUT_SECONDS, MIN_TIMEOUT_SECONDS, RESET_VALUE, SUPPORTED_REGIONS, VALID_MEMORY_OPTIONS, VPC_EGRESS_SETTINGS_OPTIONS, analytics_exports as analytics, app, auth_exports as auth, config, database_exports as database, firebaseConfig, firestore_exports as firestore, https_exports as https, logger_exports as logger, makeCloudFunction, onInit, optionsToEndpoint, optionsToTrigger, params_exports as params, pubsub_exports as pubsub, region, remoteConfig_exports as remoteConfig, runWith, storage_exports as storage, tasks_exports as tasks, testLab_exports as testLab };
+export { Change, DEFAULT_FAILURE_POLICY, FunctionBuilder, INGRESS_SETTINGS_OPTIONS, MAX_NUMBER_USER_LABELS, MAX_TIMEOUT_SECONDS, MIN_TIMEOUT_SECONDS, RESET_VALUE, SUPPORTED_REGIONS, VALID_MEMORY_OPTIONS, VPC_EGRESS_SETTINGS_OPTIONS, analytics_exports as analytics, app, auth_exports as auth, config, database_exports as database, firebaseConfig, firestore_exports as firestore, https_exports as https, logger_exports as logger, makeCloudFunction, onInit, optionsToEndpoint, optionsToTrigger, params_exports as params, pubsub_exports as pubsub, region, remoteConfig_exports as remoteConfig, requiresAPI, runWith, storage_exports as storage, tasks_exports as tasks, testLab_exports as testLab };

package/lib/esm/v1/providers/https.mjs

@@ -1,10 +1,12 @@
 import { __export } from "../../_virtual/rolldown_runtime.mjs";
 import { initV1Endpoint } from "../../runtime/manifest.mjs";
+import { isDebugFeatureEnabled } from "../../common/debug.mjs";
 import { convertIfPresent, convertInvoker } from "../../common/encoding.mjs";
 import { withInit } from "../../common/onInit.mjs";
 import { optionsToEndpoint, optionsToTrigger } from "../cloud-functions.mjs";
-import { HttpsError, onCallHandler, withErrorHandler } from "../../common/providers/https.mjs";
+import { HttpsError, onCallHandler, resolveCorsOrigin, withErrorHandler } from "../../common/providers/https.mjs";
 import { wrapTraceContext } from "../../v2/trace.mjs";
+import cors from "cors";
 
 //#region src/v1/providers/https.ts
 var https_exports = /* @__PURE__ */ __export({
@@ -16,11 +18,20 @@ var https_exports = /* @__PURE__ */ __export({
 });
 /**
 * Handle HTTP requests.
-* @param handler A function that takes a request and response object,
+* @param optsOrHandler Options or a function that takes a request and response object,
 * same signature as an Express app.
 */
-function onRequest(handler) {
-	return _onRequestWithOptions(handler, {});
+function onRequest(optsOrHandler, handler) {
+	let opts;
+	let userHandler;
+	if (typeof optsOrHandler === "function") {
+		opts = {};
+		userHandler = optsOrHandler;
+	} else {
+		opts = optsOrHandler;
+		userHandler = handler;
+	}
+	return _onRequestWithOptions(userHandler, opts);
 }
 /**
 * Declares a callable method for clients to call using a Firebase SDK.
@@ -31,6 +42,19 @@ function onCall(handler) {
 }
 /** @internal */
 function _onRequestWithOptions(handler, options) {
+	if (isDebugFeatureEnabled("enableCors") || "cors" in options) {
+		const userProvidedHandler = handler;
+		handler = (req, res) => {
+			return new Promise((resolve) => {
+				res.on("finish", resolve);
+				const origin = resolveCorsOrigin(options.cors);
+				const middleware = cors({ origin });
+				middleware(req, res, () => {
+					resolve(userProvidedHandler(req, res));
+				});
+			});
+		};
+	}
 	const cloudFunction = (req, res) => {
 		return wrapTraceContext(withInit(withErrorHandler(handler)))(req, res);
 	};

package/lib/esm/v2/index.doc.mjs

@@ -1,9 +1,12 @@
 import { traceContext } from "../common/trace.mjs";
 import { logger } from "../logger/index.mjs";
 import { params_exports } from "../params/index.mjs";
+import { requiresAPI } from "../common/api.mjs";
+import { afterFirstDeploy, afterRedeploy } from "../lifecycle/index.mjs";
 import { Change } from "../common/change.mjs";
 import { onInit } from "../common/onInit.mjs";
 import { config } from "../v1/config.mjs";
+import { requiresRole } from "./security.mjs";
 import { setGlobalOptions } from "./options.mjs";
 import { dataconnect_doc_exports } from "./dataconnect.doc.mjs";
 import { alerts_exports } from "./providers/alerts/index.mjs";
@@ -20,4 +23,4 @@ import { testLab_exports } from "./providers/testLab.mjs";
 import { firestore_exports } from "./providers/firestore.mjs";
 import { app } from "./index.mjs";
 
-export { Change, alerts_exports as alerts, app, config, database_exports as database, dataconnect_doc_exports as dataconnect, eventarc_exports as eventarc, firestore_exports as firestore, https_exports as https, identity_exports as identity, logger, onInit, params_exports as params, pubsub_exports as pubsub, remoteConfig_exports as remoteConfig, scheduler_exports as scheduler, setGlobalOptions, storage_exports as storage, tasks_exports as tasks, testLab_exports as testLab, traceContext };
+export { Change, afterFirstDeploy, afterRedeploy, alerts_exports as alerts, app, config, database_exports as database, dataconnect_doc_exports as dataconnect, eventarc_exports as eventarc, firestore_exports as firestore, https_exports as https, identity_exports as identity, logger, onInit, params_exports as params, pubsub_exports as pubsub, remoteConfig_exports as remoteConfig, requiresAPI, requiresRole, scheduler_exports as scheduler, setGlobalOptions, storage_exports as storage, tasks_exports as tasks, testLab_exports as testLab, traceContext };

package/lib/esm/v2/index.mjs

@@ -1,11 +1,14 @@
 import { traceContext } from "../common/trace.mjs";
 import { logger } from "../logger/index.mjs";
 import { params_exports } from "../params/index.mjs";
+import { requiresAPI } from "../common/api.mjs";
+import { afterFirstDeploy, afterRedeploy } from "../lifecycle/index.mjs";
 import { setApp } from "../common/app.mjs";
 import { Change } from "../common/change.mjs";
 import { onInit } from "../common/onInit.mjs";
 import { config } from "../v1/config.mjs";
 import "./core.mjs";
+import { requiresRole } from "./security.mjs";
 import { setGlobalOptions } from "./options.mjs";
 import { dataconnect_exports } from "./providers/dataconnect/index.mjs";
 import { alerts_exports } from "./providers/alerts/index.mjs";
@@ -25,4 +28,4 @@ import { firestore_exports } from "./providers/firestore.mjs";
 const app = { setEmulatedAdminApp: setApp };
 
 //#endregion
-export { Change, alerts_exports as alerts, app, config, database_exports as database, dataconnect_exports as dataconnect, eventarc_exports as eventarc, firestore_exports as firestore, https_exports as https, identity_exports as identity, logger, onInit, params_exports as params, pubsub_exports as pubsub, remoteConfig_exports as remoteConfig, scheduler_exports as scheduler, setGlobalOptions, storage_exports as storage, tasks_exports as tasks, testLab_exports as testLab, traceContext };
+export { Change, afterFirstDeploy, afterRedeploy, alerts_exports as alerts, app, config, database_exports as database, dataconnect_exports as dataconnect, eventarc_exports as eventarc, firestore_exports as firestore, https_exports as https, identity_exports as identity, logger, onInit, params_exports as params, pubsub_exports as pubsub, remoteConfig_exports as remoteConfig, requiresAPI, requiresRole, scheduler_exports as scheduler, setGlobalOptions, storage_exports as storage, tasks_exports as tasks, testLab_exports as testLab, traceContext };

package/lib/esm/v2/options.mjs

@@ -1,9 +1,34 @@
 import { warn } from "../logger/index.mjs";
+import { Expression } from "../params/types.mjs";
 import { declaredParams } from "../params/index.mjs";
 import { RESET_VALUE, ResetValue } from "../common/options.mjs";
 import { convertIfPresent, copyIfPresent, durationFromSeconds, serviceAccountFromShorthand } from "../common/encoding.mjs";
+import { assertNever } from "../common/utilities/assertions.mjs";
+import { requiresRole } from "./security.mjs";
 
 //#region src/v2/options.ts
+/**
+* Maximum timeout in seconds for event-handling functions (e.g. Firestore,
+* Realtime Database, Pub/Sub, Storage, Eventarc, alerts, scheduler).
+* See https://firebase.google.com/docs/functions/manage-functions
+* @internal
+*/
+const MAX_EVENT_TIMEOUT_SECONDS = 540;
+/**
+* Maximum timeout in seconds for HTTPS and callable functions.
+* @internal
+*/
+const MAX_HTTPS_TIMEOUT_SECONDS = 3600;
+/**
+* Maximum timeout in seconds for Task Queue functions.
+* @internal
+*/
+const MAX_TASK_TIMEOUT_SECONDS = 1800;
+/**
+* Maximum timeout in seconds for Identity blocking functions.
+* @internal
+*/
+const MAX_IDENTITY_TIMEOUT_SECONDS = 7;
 const MemoryOptionToMB = {
 	"128MiB": 128,
 	"256MiB": 256,
@@ -35,10 +60,58 @@ function getGlobalOptions() {
 	return globalOptions || {};
 }
 /**
+* Validate that `timeoutSeconds` (resolved with global option fallback) is
+* finite and within the accepted range for the given function kind. Throws a
+* plain `Error` matching the v1 `assertRuntimeOptionsValid` shape so the
+* problem surfaces at function-definition time instead of at deploy time.
+* `Expression`, `RESET_VALUE`, and `undefined` are skipped. Literal numbers
+* are range checked, and other types are rejected.
+* @internal
+*/
+function assertTimeoutSecondsValid(opts, kind) {
+	const timeoutSeconds = opts.timeoutSeconds === undefined ? getGlobalOptions().timeoutSeconds : opts.timeoutSeconds;
+	if (typeof timeoutSeconds !== "number") {
+		if (timeoutSeconds === undefined || timeoutSeconds instanceof Expression || timeoutSeconds instanceof ResetValue) {
+			return;
+		}
+		throw new Error(`timeoutSeconds must be a number, Expression, or RESET_VALUE. Got ${typeof timeoutSeconds}.`);
+	}
+	if (!Number.isFinite(timeoutSeconds)) {
+		throw new Error(`timeoutSeconds must be a finite number. Got ${timeoutSeconds}.`);
+	}
+	let max;
+	let label;
+	switch (kind) {
+		case "event":
+			max = MAX_EVENT_TIMEOUT_SECONDS;
+			label = "event-handling";
+			break;
+		case "https":
+			max = MAX_HTTPS_TIMEOUT_SECONDS;
+			label = "HTTPS and callable";
+			break;
+		case "task":
+			max = MAX_TASK_TIMEOUT_SECONDS;
+			label = "task queue";
+			break;
+		case "identity":
+			max = MAX_IDENTITY_TIMEOUT_SECONDS;
+			label = "blocking";
+			break;
+		default: assertNever(kind);
+	}
+	if (timeoutSeconds < 0 || timeoutSeconds > max) {
+		throw new Error(`timeoutSeconds must be between 0 and ${max} for ${label} functions. Got ${timeoutSeconds}.`);
+	}
+}
+/**
 * Apply GlobalOptions to trigger definitions.
 * @internal
 */
-function optionsToTriggerAnnotations(opts) {
+function optionsToTriggerAnnotations(opts, kind) {
+	if (kind !== undefined) {
+		assertTimeoutSecondsValid(opts, kind);
+	}
 	const annotation = {};
 	copyIfPresent(annotation, opts, "concurrency", "minInstances", "maxInstances", "ingressSettings", "labels", "vpcConnector", "secrets");
 	const vpcEgress = opts.vpcEgress ?? opts.vpcConnectorEgressSettings;
@@ -69,7 +142,10 @@ function optionsToTriggerAnnotations(opts) {
 * Apply GlobalOptions to endpoint manifest.
 * @internal
 */
-function optionsToEndpoint(opts) {
+function optionsToEndpoint(opts, kind) {
+	if (kind !== undefined) {
+		assertTimeoutSecondsValid(opts, kind);
+	}
 	const endpoint = {};
 	copyIfPresent(endpoint, opts, "omit", "concurrency", "minInstances", "maxInstances", "ingressSettings", "labels", "timeoutSeconds", "cpu");
 	convertIfPresent(endpoint, opts, "serviceAccountEmail", "serviceAccount");
@@ -127,4 +203,4 @@ function __getSpec() {
 }
 
 //#endregion
-export { RESET_VALUE, __getSpec, getGlobalOptions, optionsToEndpoint, optionsToTriggerAnnotations, setGlobalOptions };
+export { MAX_EVENT_TIMEOUT_SECONDS, MAX_HTTPS_TIMEOUT_SECONDS, MAX_IDENTITY_TIMEOUT_SECONDS, MAX_TASK_TIMEOUT_SECONDS, RESET_VALUE, __getSpec, assertTimeoutSecondsValid, getGlobalOptions, optionsToEndpoint, optionsToTriggerAnnotations, requiresRole, setGlobalOptions };

package/lib/esm/v2/providers/ai/index.mjs

@@ -90,7 +90,7 @@ function beforeGenerateContent(optsOrCb, cb) {
 	func.run = handler;
 	func = wrapTraceContext(withInit(func));
 	const baseOpts = optionsToEndpoint(getGlobalOptions());
-	const specificOpts = optionsToEndpoint(opts);
+	const specificOpts = optionsToEndpoint(opts, "https");
 	func.__endpoint = {
 		...initV2Endpoint(getGlobalOptions(), opts),
 		platform: "gcfv2",
@@ -165,7 +165,7 @@ function afterGenerateContent(optsOrCb, cb) {
 	func.run = handler;
 	func = wrapTraceContext(withInit(func));
 	const baseOpts = optionsToEndpoint(getGlobalOptions());
-	const specificOpts = optionsToEndpoint(opts);
+	const specificOpts = optionsToEndpoint(opts, "https");
 	func.__endpoint = {
 		...initV2Endpoint(getGlobalOptions(), opts),
 		platform: "gcfv2",

package/lib/esm/v2/providers/alerts/alerts.mjs

@@ -21,7 +21,7 @@ function onAlertPublished(alertTypeOrOpts, handler) {
 */
 function getEndpointAnnotation(opts, alertType, appId) {
 	const baseOpts = optionsToEndpoint(getGlobalOptions());
-	const specificOpts = optionsToEndpoint(opts);
+	const specificOpts = optionsToEndpoint(opts, "event");
 	const endpoint = {
 		...initV2Endpoint(getGlobalOptions(), opts),
 		platform: "gcfv2",