@hot-updater/firebase 1.2.0-rc.7 → 1.2.0-rc.9

package/dist/firebase/functions/index.cjs

@@ -4683,7 +4683,7 @@ const createKvAdapter = ({ store, tablePrefix = "" }) => {
 };
 //#endregion
 //#region ../../packages/server/dist/version.mjs
-const HOT_UPDATER_SERVER_VERSION = "1.2.0-rc.7";
+const HOT_UPDATER_SERVER_VERSION = "1.2.0-rc.9";
 //#endregion
 //#region ../../packages/server/dist/handlerVersionRoutes.mjs
 /**
@@ -12139,11 +12139,14 @@ const firebaseDatabase = (config) => ({
 //#region src/firebaseStorage.ts
 /** Signed URLs kept per adapter, enough for a few Bundles' assets. */
 const MAX_CACHED_SIGNED_URLS = 1e4;
+/** Objects deleted at once: Cloud Storage deletes one object a request. */
+const DELETE_CONCURRENCY = 16;
 const firebaseStorage = (config) => {
 	const app = (0, firebase_admin_app.getApps)().length ? (0, firebase_admin_app.getApp)() : (0, firebase_admin_app.initializeApp)(config);
 	let opened;
 	const bucket = () => opened ??= (0, firebase_admin_storage.getStorage)(app).bucket(config.storageBucket);
 	const getStorageKey = createStorageKeyBuilder(config.basePath);
+	const basePrefix = getStorageKey() ? `${getStorageKey()}/` : "";
 	/**
 	* Signed URLs by object. Without a private key, as in Cloud Functions, each
 	* signature is an IAM signBlob request, and an update check returns a URL
@@ -12232,6 +12235,39 @@ const firebaseStorage = (config) => {
 			const { key } = parseAndValidate(storageUri);
 			await bucket().file(key).delete({ ignoreNotFound: true });
 			return { deleted: true };
+		},
+		async listObjects(prefix) {
+			const folder = getStorageKey(prefix ?? "");
+			const [files] = await bucket().getFiles({
+				autoPaginate: true,
+				prefix: folder ? `${folder}/` : ""
+			});
+			const objects = [];
+			for (const file of files) {
+				if (!file.name.startsWith(basePrefix)) continue;
+				let storageUri;
+				try {
+					storageUri = createStorageUri({
+						bucket: config.storageBucket,
+						key: file.name,
+						protocol: "gs"
+					});
+				} catch {
+					continue;
+				}
+				const { size, updated } = file.metadata;
+				objects.push({
+					key: file.name.slice(basePrefix.length),
+					...updated ? { lastModifiedAt: new Date(updated) } : {},
+					size: Number(size ?? 0),
+					storageUri
+				});
+			}
+			return objects;
+		},
+		async deleteObjects(relativeKeys) {
+			const keys = relativeKeys.map((key) => getStorageKey(key));
+			for (let offset = 0; offset < keys.length; offset += DELETE_CONCURRENCY) await Promise.all(keys.slice(offset, offset + DELETE_CONCURRENCY).map((key) => bucket().file(key).delete({ ignoreNotFound: true })));
 		}
 	});
 };

package/dist/index.cjs

@@ -202,11 +202,14 @@ const firebaseDatabase = (config) => ({
 //#region src/firebaseStorage.ts
 /** Signed URLs kept per adapter, enough for a few Bundles' assets. */
 const MAX_CACHED_SIGNED_URLS = 1e4;
+/** Objects deleted at once: Cloud Storage deletes one object a request. */
+const DELETE_CONCURRENCY = 16;
 const firebaseStorage = (config) => {
 	const app = (0, firebase_admin_app.getApps)().length ? (0, firebase_admin_app.getApp)() : (0, firebase_admin_app.initializeApp)(config);
 	let opened;
 	const bucket = () => opened ??= (0, firebase_admin_storage.getStorage)(app).bucket(config.storageBucket);
 	const getStorageKey = (0, _hot_updater_plugin_core.createStorageKeyBuilder)(config.basePath);
+	const basePrefix = getStorageKey() ? `${getStorageKey()}/` : "";
 	/**
 	* Signed URLs by object. Without a private key, as in Cloud Functions, each
 	* signature is an IAM signBlob request, and an update check returns a URL
@@ -295,6 +298,39 @@ const firebaseStorage = (config) => {
 			const { key } = parseAndValidate(storageUri);
 			await bucket().file(key).delete({ ignoreNotFound: true });
 			return { deleted: true };
+		},
+		async listObjects(prefix) {
+			const folder = getStorageKey(prefix ?? "");
+			const [files] = await bucket().getFiles({
+				autoPaginate: true,
+				prefix: folder ? `${folder}/` : ""
+			});
+			const objects = [];
+			for (const file of files) {
+				if (!file.name.startsWith(basePrefix)) continue;
+				let storageUri;
+				try {
+					storageUri = (0, _hot_updater_plugin_core.createStorageUri)({
+						bucket: config.storageBucket,
+						key: file.name,
+						protocol: "gs"
+					});
+				} catch {
+					continue;
+				}
+				const { size, updated } = file.metadata;
+				objects.push({
+					key: file.name.slice(basePrefix.length),
+					...updated ? { lastModifiedAt: new Date(updated) } : {},
+					size: Number(size ?? 0),
+					storageUri
+				});
+			}
+			return objects;
+		},
+		async deleteObjects(relativeKeys) {
+			const keys = relativeKeys.map((key) => getStorageKey(key));
+			for (let offset = 0; offset < keys.length; offset += DELETE_CONCURRENCY) await Promise.all(keys.slice(offset, offset + DELETE_CONCURRENCY).map((key) => bucket().file(key).delete({ ignoreNotFound: true })));
 		}
 	});
 };
@@ -356,23 +392,51 @@ const crc32c = (bytes) => {
 /** The version IDs the secret's annotation lists. */
 const trackedVersions = (secret) => (secret.annotations?.[VERSIONS_ANNOTATION] ?? "").split(",").map((entry) => entry.trim()).filter((entry) => VERSION_ID_PATTERN.test(entry));
 const versionOf = (name) => typeof name === "string" ? name.slice(name.lastIndexOf("/") + 1) : "";
+/** The widest line a message has: the CLI prints no wider. */
+const LINE_WIDTH = 76;
+/** `text`, such as Google's own message, in lines that fit, broken at spaces. */
+const wrap = (text) => {
+	const lines = [];
+	let line = "";
+	for (const word of text.split(/\s+/u).filter(Boolean)) if (line && line.length + 1 + word.length > LINE_WIDTH) {
+		lines.push(line);
+		line = word;
+	} else line = line ? `${line} ${word}` : word;
+	if (line) lines.push(line);
+	return lines;
+};
+/** An error of one line each, for a terminal. */
+const failure = (lines, cause) => new Error(lines.join("\n"), cause === void 0 ? void 0 : { cause });
 const hint = (response, permission) => {
 	const { status, error } = response;
-	if (error.details?.some((detail) => detail.reason === "SERVICE_DISABLED")) return " Enable the Secret Manager API (secretmanager.googleapis.com) in the project: gcloud services enable secretmanager.googleapis.com --project <project>.";
-	if (status === 401) return " Google rejected the access token: sign in again with `gcloud auth application-default login`, or check the job's Workload Identity Federation.";
-	if (status === 403) return ` The Google identity needs ${permission}.`;
-	if (status === 429) return " Secret Manager's quota is exhausted: try again later.";
-	return "";
+	if (error.details?.some((detail) => detail.reason === "SERVICE_DISABLED")) return ["Enable the Secret Manager API in the project:", "gcloud services enable secretmanager.googleapis.com --project <project>"];
+	if (status === 401) return [
+		"Google rejected the access token.",
+		"Sign in again with gcloud auth application-default login.",
+		"In CI, check the job's Workload Identity Federation."
+	];
+	if (status === 403) return wrap(`The Google identity needs ${permission}.`);
+	if (status === 429) return ["Secret Manager's quota is exhausted: try again later."];
+	return [];
 };
 /**
-* An error for a failed request: the HTTP status, Google's status and
-* message, which name resources but never a value, and what to fix.
+* An error for a failed request on `resource`, a line each: the HTTP
+* status, the resource, Google's status and message, which name resources
+* but never a value, `notes`, and what to fix.
 */
-const requestError = (action, response, permission) => {
+const requestError = (action, resource, response, permission, notes = []) => {
 	const { status, message } = response.error;
 	const detail = [status, message?.slice(0, 300)].filter(Boolean).join(": ");
-	return /* @__PURE__ */ new Error(`${ADAPTER_NAME} could not ${action} (${response.status}${detail ? ` ${detail}` : ""}).${hint(response, permission)}`);
+	return failure([
+		`${ADAPTER_NAME} couldn't ${action} (${response.status}).`,
+		resourceLine(resource),
+		...wrap(detail),
+		...notes,
+		...hint(response, permission)
+	]);
 };
+/** The line that names a secret: its resource name is a line's worth. */
+const resourceLine = (secret) => `Secret: ${secret}`;
 /** Masks a value in the CLI's output, which loads `@hot-updater/cli-tools`. */
 const mask = async (value) => {
 	const { registerSecretValue } = await import("@hot-updater/cli-tools");
@@ -411,7 +475,14 @@ const createAccessToken = (credentials, projectId) => {
 		try {
 			return await client.getAccessToken() ?? void 0;
 		} catch (error) {
-			throw new Error(`${ADAPTER_NAME} found no Google credentials (${error instanceof Error ? error.message.split("\n")[0] : String(error)}). Sign in with \`gcloud auth application-default login\`, use google-github-actions/auth in CI, set GOOGLE_APPLICATION_CREDENTIALS, or set ${ACCESS_TOKEN_ENV_NAMES.join(" or ")} to an access token.`, { cause: error });
+			throw failure([
+				`${ADAPTER_NAME} found no Google credentials.`,
+				...wrap(error instanceof Error ? error.message.split("\n")[0] : String(error)),
+				"On your machine, run gcloud auth application-default login.",
+				"In CI, use google-github-actions/auth.",
+				"Or set GOOGLE_APPLICATION_CREDENTIALS to a service account key.",
+				`Or set ${ACCESS_TOKEN_ENV_NAMES.join(" or ")} to a token.`
+			], error);
 		}
 	};
 	return async () => {
@@ -434,13 +505,17 @@ const createAccessToken = (credentials, projectId) => {
 const secretManager = ({ projectId, prefix = "hot-updater-", credentials }) => {
 	const accessToken = createAccessToken(credentials, projectId);
 	const projectPath = () => {
-		if (typeof projectId !== "string" || !PROJECT_PATTERN.test(projectId)) throw new Error(`${ADAPTER_NAME} needs the Google Cloud project ID or number as projectId, and ${JSON.stringify(projectId)} is not one.`);
-		if (!PREFIX_PATTERN.test(prefix)) throw new Error(`${ADAPTER_NAME}'s prefix takes letters, digits, "-", and "_", and ${JSON.stringify(prefix)} has others.`);
+		if (typeof projectId !== "string" || !PROJECT_PATTERN.test(projectId)) throw failure([`${ADAPTER_NAME} can't use the projectId ${JSON.stringify(projectId)}.`, "Set the Google Cloud project's ID or number."]);
+		if (!PREFIX_PATTERN.test(prefix)) throw failure([`${ADAPTER_NAME} can't use the prefix ${JSON.stringify(prefix)}.`, "It takes letters, digits, \"-\", and \"_\"."]);
 		return `projects/${projectId}`;
 	};
 	const secretId = (name) => {
 		const id = `${prefix}${name}`;
-		if (!SECRET_ID_PATTERN.test(id)) throw new Error(`${ADAPTER_NAME} keeps ${JSON.stringify(name)} as the secret ID ${JSON.stringify(id)}, and Secret Manager's IDs take only letters, digits, "-", and "_", up to 255 characters.`);
+		if (!SECRET_ID_PATTERN.test(id)) throw failure([
+			`${ADAPTER_NAME} can't name a secret ${JSON.stringify(name)}.`,
+			`Secret: ${id}`,
+			"Secret Manager's IDs take up to 255 letters, digits, \"-\", and \"_\"."
+		]);
 		return id;
 	};
 	const request = async (token, method, path, body) => {
@@ -475,14 +550,18 @@ const secretManager = ({ projectId, prefix = "hot-updater-", credentials }) => {
 	const accessLatest = async (token, secret) => {
 		const response = await request(token, "GET", `${secret}/versions/latest:access`);
 		if (response.status === 404) return void 0;
-		if (!response.ok) throw requestError(`read ${secret}`, response, "roles/secretmanager.secretAccessor on the secret");
+		if (!response.ok) throw requestError("read", secret, response, "roles/secretmanager.secretAccessor on the secret");
 		const body = isRecord(response.body) ? response.body : void 0;
 		const payload = body?.payload;
 		const data = isRecord(payload) ? payload.data : void 0;
-		if (typeof data !== "string") throw new Error(`${ADAPTER_NAME} read no payload for ${secret}.`);
+		if (typeof data !== "string") throw failure([`${ADAPTER_NAME} read no payload.`, resourceLine(secret)]);
 		const bytes = Buffer.from(data, "base64");
 		const checksum = isRecord(payload) ? payload.dataCrc32c : void 0;
-		if (checksum !== void 0 && Number(checksum) !== crc32c(bytes)) throw new Error(`${ADAPTER_NAME} read ${secret} with a checksum that does not match its payload.`);
+		if (checksum !== void 0 && Number(checksum) !== crc32c(bytes)) throw failure([
+			`${ADAPTER_NAME} can't trust what it read.`,
+			resourceLine(secret),
+			"Its checksum doesn't match its payload."
+		]);
 		const value = bytes.toString("utf8");
 		await mask(value);
 		return {
@@ -515,7 +594,7 @@ const secretManager = ({ projectId, prefix = "hot-updater-", credentials }) => {
 	const readSecret = async (token, secret) => {
 		const response = await request(token, "GET", secret);
 		if (response.status === 404) return void 0;
-		if (!response.ok) throw requestError(`read ${secret}`, response, "secretmanager.secrets.get on the secret");
+		if (!response.ok) throw requestError("read", secret, response, "secretmanager.secrets.get on the secret");
 		return response.body;
 	};
 	const getOrCreateSecret = async (token, parent, id) => {
@@ -528,14 +607,21 @@ const secretManager = ({ projectId, prefix = "hot-updater-", credentials }) => {
 			const raced = await readSecret(token, secret);
 			if (raced) return raced;
 		}
-		throw requestError(`create ${secret}`, created, `secretmanager.secrets.create on ${parent}`);
+		throw requestError("create", secret, created, `secretmanager.secrets.create on ${parent}`);
 	};
 	const assertCanSet = async (token, secret) => {
 		const response = await request(token, "POST", `${secret}:testIamPermissions`, { permissions: SET_PERMISSIONS });
-		if (!response.ok) throw requestError(`check its permissions on ${secret}`, response, SET_PERMISSIONS.join(", "));
+		if (!response.ok) throw requestError("check its permissions", secret, response, SET_PERMISSIONS.join(", "));
 		const held = isRecord(response.body) && Array.isArray(response.body.permissions) ? response.body.permissions : [];
 		const missing = SET_PERMISSIONS.filter((name) => !held.includes(name));
-		if (missing.length > 0) throw new Error(`${ADAPTER_NAME} stores a value as a new version of ${secret} and destroys the versions it added before, and the Google identity lacks ${missing.join(", ")} on it: grant a custom role with secretmanager.secrets.get, secretmanager.secrets.update, secretmanager.versions.add, secretmanager.versions.destroy, and secretmanager.versions.access on it, or roles/secretmanager.admin.`);
+		if (missing.length > 0) throw failure([
+			`${ADAPTER_NAME} can't store a value.`,
+			resourceLine(secret),
+			...wrap(`The Google identity lacks ${missing.join(", ")} on it.`),
+			"It adds a version, then destroys the versions it added before.",
+			"Grant roles/secretmanager.admin, or a custom role with:",
+			...wrap("secretmanager.secrets.get, secretmanager.secrets.update, secretmanager.versions.add, secretmanager.versions.destroy, secretmanager.versions.access")
+		]);
 	};
 	/**
 	* Destroys `version` of `secret`: true once it is destroyed, or already
@@ -582,7 +668,7 @@ const secretManager = ({ projectId, prefix = "hot-updater-", credentials }) => {
 			const parent = projectPath();
 			const id = secretId(name);
 			const secret = `${parent}/secrets/${id}`;
-			if (typeof value !== "string" || value === "") throw new Error(`${ADAPTER_NAME} cannot store an empty ${secret}.`);
+			if (typeof value !== "string" || value === "") throw failure([`${ADAPTER_NAME} can't store an empty value.`, resourceLine(secret)]);
 			await mask(value);
 			const token = await accessToken();
 			const current = await getOrCreateSecret(token, parent, id);
@@ -593,7 +679,7 @@ const secretManager = ({ projectId, prefix = "hot-updater-", credentials }) => {
 				dataCrc32c: String(crc32c(data))
 			} });
 			const version = versionOf(isRecord(added.body) ? added.body.name : void 0);
-			if (!added.ok || !VERSION_ID_PATTERN.test(version)) throw requestError(`add a version to ${secret}`, added, "secretmanager.versions.add on the secret");
+			if (!added.ok || !VERSION_ID_PATTERN.test(version)) throw requestError("add a version", secret, added, "secretmanager.versions.add on the secret");
 			const visible = await waitForLatest(token, secret, version);
 			const destroyed = /* @__PURE__ */ new Set();
 			if (visible) {
@@ -603,7 +689,8 @@ const secretManager = ({ projectId, prefix = "hot-updater-", credentials }) => {
 					if (results[index]) destroyed.add(entry);
 				});
 			}
-			const notListed = `list version ${version}, which it stored, in ${secret}'s ${VERSIONS_ANNOTATION} annotation, so the next set will not destroy it`;
+			const notListed = `record version ${version}, which it stored`;
+			const notDestroyed = `The next set won't destroy it: ${VERSIONS_ANNOTATION} misses it.`;
 			let base = current;
 			let updated;
 			try {
@@ -623,10 +710,20 @@ const secretManager = ({ projectId, prefix = "hot-updater-", credentials }) => {
 					if (updated.error.status !== "FAILED_PRECONDITION") break;
 				}
 			} catch (error) {
-				throw new Error(`${ADAPTER_NAME} could not ${notListed} (${error instanceof Error ? error.message : String(error)}).`, { cause: error });
+				throw failure([
+					`${ADAPTER_NAME} couldn't ${notListed}.`,
+					resourceLine(secret),
+					...wrap(error instanceof Error ? error.message : String(error)),
+					notDestroyed
+				], error);
 			}
-			if (!updated?.ok) throw requestError(notListed, updated, "secretmanager.secrets.update on the secret");
-			if (!visible) throw new Error(`${ADAPTER_NAME} stored ${secret} as version ${version}, and its latest alias does not resolve to that version yet, so it kept the versions it added before; the next set destroys them.`);
+			if (!updated?.ok) throw requestError(notListed, secret, updated, "secretmanager.secrets.update on the secret", [notDestroyed]);
+			if (!visible) throw failure([
+				`${ADAPTER_NAME} stored version ${version}.`,
+				resourceLine(secret),
+				"Its latest alias doesn't resolve to that version yet.",
+				"It kept the versions it added before: the next set destroys them."
+			]);
 		},
 		describe: (name) => {
 			const id = `${prefix}${name}`;

package/dist/index.d.cts

@@ -37,7 +37,7 @@ interface FirebaseStorageConfig extends AppOptions {
   /** Firebase signed URL lifetime in seconds. @default 3600 */
   signedUrlExpiresIn?: number;
 }
-declare const firebaseStorage: (config: FirebaseStorageConfig) => StorageAdapterWith<"put" | "get" | "getDownloadUrl" | "exists" | "delete">;
+declare const firebaseStorage: (config: FirebaseStorageConfig) => StorageAdapterWith<"put" | "get" | "getDownloadUrl" | "exists" | "delete" | "listObjects" | "deleteObjects">;
 //#endregion
 //#region src/secretManager.d.ts
 /**
@@ -56,7 +56,7 @@ interface SecretManagerOptions {
   /** The Google Cloud project ID or number that holds the secrets. */
   readonly projectId: string;
   /**
-   * Put before each name to make its secret ID, so `secret:asc-api-key`
+   * Put before each name to make its secret ID, so `secret("asc-api-key")`
    * reads `hot-updater-asc-api-key`. Letters, digits, `-`, and `_`.
    *
    * @default "hot-updater-"

package/dist/index.d.mts

@@ -37,7 +37,7 @@ interface FirebaseStorageConfig extends AppOptions {
   /** Firebase signed URL lifetime in seconds. @default 3600 */
   signedUrlExpiresIn?: number;
 }
-declare const firebaseStorage: (config: FirebaseStorageConfig) => StorageAdapterWith<"put" | "get" | "getDownloadUrl" | "exists" | "delete">;
+declare const firebaseStorage: (config: FirebaseStorageConfig) => StorageAdapterWith<"put" | "get" | "getDownloadUrl" | "exists" | "delete" | "listObjects" | "deleteObjects">;
 //#endregion
 //#region src/secretManager.d.ts
 /**
@@ -56,7 +56,7 @@ interface SecretManagerOptions {
   /** The Google Cloud project ID or number that holds the secrets. */
   readonly projectId: string;
   /**
-   * Put before each name to make its secret ID, so `secret:asc-api-key`
+   * Put before each name to make its secret ID, so `secret("asc-api-key")`
    * reads `hot-updater-asc-api-key`. Letters, digits, `-`, and `_`.
    *
    * @default "hot-updater-"

package/dist/index.mjs

@@ -201,11 +201,14 @@ const firebaseDatabase = (config) => ({
 //#region src/firebaseStorage.ts
 /** Signed URLs kept per adapter, enough for a few Bundles' assets. */
 const MAX_CACHED_SIGNED_URLS = 1e4;
+/** Objects deleted at once: Cloud Storage deletes one object a request. */
+const DELETE_CONCURRENCY = 16;
 const firebaseStorage = (config) => {
 	const app = getApps().length ? getApp() : initializeApp(config);
 	let opened;
 	const bucket = () => opened ??= getStorage(app).bucket(config.storageBucket);
 	const getStorageKey = createStorageKeyBuilder(config.basePath);
+	const basePrefix = getStorageKey() ? `${getStorageKey()}/` : "";
 	/**
 	* Signed URLs by object. Without a private key, as in Cloud Functions, each
 	* signature is an IAM signBlob request, and an update check returns a URL
@@ -294,6 +297,39 @@ const firebaseStorage = (config) => {
 			const { key } = parseAndValidate(storageUri);
 			await bucket().file(key).delete({ ignoreNotFound: true });
 			return { deleted: true };
+		},
+		async listObjects(prefix) {
+			const folder = getStorageKey(prefix ?? "");
+			const [files] = await bucket().getFiles({
+				autoPaginate: true,
+				prefix: folder ? `${folder}/` : ""
+			});
+			const objects = [];
+			for (const file of files) {
+				if (!file.name.startsWith(basePrefix)) continue;
+				let storageUri;
+				try {
+					storageUri = createStorageUri({
+						bucket: config.storageBucket,
+						key: file.name,
+						protocol: "gs"
+					});
+				} catch {
+					continue;
+				}
+				const { size, updated } = file.metadata;
+				objects.push({
+					key: file.name.slice(basePrefix.length),
+					...updated ? { lastModifiedAt: new Date(updated) } : {},
+					size: Number(size ?? 0),
+					storageUri
+				});
+			}
+			return objects;
+		},
+		async deleteObjects(relativeKeys) {
+			const keys = relativeKeys.map((key) => getStorageKey(key));
+			for (let offset = 0; offset < keys.length; offset += DELETE_CONCURRENCY) await Promise.all(keys.slice(offset, offset + DELETE_CONCURRENCY).map((key) => bucket().file(key).delete({ ignoreNotFound: true })));
 		}
 	});
 };
@@ -355,23 +391,51 @@ const crc32c = (bytes) => {
 /** The version IDs the secret's annotation lists. */
 const trackedVersions = (secret) => (secret.annotations?.[VERSIONS_ANNOTATION] ?? "").split(",").map((entry) => entry.trim()).filter((entry) => VERSION_ID_PATTERN.test(entry));
 const versionOf = (name) => typeof name === "string" ? name.slice(name.lastIndexOf("/") + 1) : "";
+/** The widest line a message has: the CLI prints no wider. */
+const LINE_WIDTH = 76;
+/** `text`, such as Google's own message, in lines that fit, broken at spaces. */
+const wrap = (text) => {
+	const lines = [];
+	let line = "";
+	for (const word of text.split(/\s+/u).filter(Boolean)) if (line && line.length + 1 + word.length > LINE_WIDTH) {
+		lines.push(line);
+		line = word;
+	} else line = line ? `${line} ${word}` : word;
+	if (line) lines.push(line);
+	return lines;
+};
+/** An error of one line each, for a terminal. */
+const failure = (lines, cause) => new Error(lines.join("\n"), cause === void 0 ? void 0 : { cause });
 const hint = (response, permission) => {
 	const { status, error } = response;
-	if (error.details?.some((detail) => detail.reason === "SERVICE_DISABLED")) return " Enable the Secret Manager API (secretmanager.googleapis.com) in the project: gcloud services enable secretmanager.googleapis.com --project <project>.";
-	if (status === 401) return " Google rejected the access token: sign in again with `gcloud auth application-default login`, or check the job's Workload Identity Federation.";
-	if (status === 403) return ` The Google identity needs ${permission}.`;
-	if (status === 429) return " Secret Manager's quota is exhausted: try again later.";
-	return "";
+	if (error.details?.some((detail) => detail.reason === "SERVICE_DISABLED")) return ["Enable the Secret Manager API in the project:", "gcloud services enable secretmanager.googleapis.com --project <project>"];
+	if (status === 401) return [
+		"Google rejected the access token.",
+		"Sign in again with gcloud auth application-default login.",
+		"In CI, check the job's Workload Identity Federation."
+	];
+	if (status === 403) return wrap(`The Google identity needs ${permission}.`);
+	if (status === 429) return ["Secret Manager's quota is exhausted: try again later."];
+	return [];
 };
 /**
-* An error for a failed request: the HTTP status, Google's status and
-* message, which name resources but never a value, and what to fix.
+* An error for a failed request on `resource`, a line each: the HTTP
+* status, the resource, Google's status and message, which name resources
+* but never a value, `notes`, and what to fix.
 */
-const requestError = (action, response, permission) => {
+const requestError = (action, resource, response, permission, notes = []) => {
 	const { status, message } = response.error;
 	const detail = [status, message?.slice(0, 300)].filter(Boolean).join(": ");
-	return /* @__PURE__ */ new Error(`${ADAPTER_NAME} could not ${action} (${response.status}${detail ? ` ${detail}` : ""}).${hint(response, permission)}`);
+	return failure([
+		`${ADAPTER_NAME} couldn't ${action} (${response.status}).`,
+		resourceLine(resource),
+		...wrap(detail),
+		...notes,
+		...hint(response, permission)
+	]);
 };
+/** The line that names a secret: its resource name is a line's worth. */
+const resourceLine = (secret) => `Secret: ${secret}`;
 /** Masks a value in the CLI's output, which loads `@hot-updater/cli-tools`. */
 const mask = async (value) => {
 	const { registerSecretValue } = await import("@hot-updater/cli-tools");
@@ -410,7 +474,14 @@ const createAccessToken = (credentials, projectId) => {
 		try {
 			return await client.getAccessToken() ?? void 0;
 		} catch (error) {
-			throw new Error(`${ADAPTER_NAME} found no Google credentials (${error instanceof Error ? error.message.split("\n")[0] : String(error)}). Sign in with \`gcloud auth application-default login\`, use google-github-actions/auth in CI, set GOOGLE_APPLICATION_CREDENTIALS, or set ${ACCESS_TOKEN_ENV_NAMES.join(" or ")} to an access token.`, { cause: error });
+			throw failure([
+				`${ADAPTER_NAME} found no Google credentials.`,
+				...wrap(error instanceof Error ? error.message.split("\n")[0] : String(error)),
+				"On your machine, run gcloud auth application-default login.",
+				"In CI, use google-github-actions/auth.",
+				"Or set GOOGLE_APPLICATION_CREDENTIALS to a service account key.",
+				`Or set ${ACCESS_TOKEN_ENV_NAMES.join(" or ")} to a token.`
+			], error);
 		}
 	};
 	return async () => {
@@ -433,13 +504,17 @@ const createAccessToken = (credentials, projectId) => {
 const secretManager = ({ projectId, prefix = "hot-updater-", credentials }) => {
 	const accessToken = createAccessToken(credentials, projectId);
 	const projectPath = () => {
-		if (typeof projectId !== "string" || !PROJECT_PATTERN.test(projectId)) throw new Error(`${ADAPTER_NAME} needs the Google Cloud project ID or number as projectId, and ${JSON.stringify(projectId)} is not one.`);
-		if (!PREFIX_PATTERN.test(prefix)) throw new Error(`${ADAPTER_NAME}'s prefix takes letters, digits, "-", and "_", and ${JSON.stringify(prefix)} has others.`);
+		if (typeof projectId !== "string" || !PROJECT_PATTERN.test(projectId)) throw failure([`${ADAPTER_NAME} can't use the projectId ${JSON.stringify(projectId)}.`, "Set the Google Cloud project's ID or number."]);
+		if (!PREFIX_PATTERN.test(prefix)) throw failure([`${ADAPTER_NAME} can't use the prefix ${JSON.stringify(prefix)}.`, "It takes letters, digits, \"-\", and \"_\"."]);
 		return `projects/${projectId}`;
 	};
 	const secretId = (name) => {
 		const id = `${prefix}${name}`;
-		if (!SECRET_ID_PATTERN.test(id)) throw new Error(`${ADAPTER_NAME} keeps ${JSON.stringify(name)} as the secret ID ${JSON.stringify(id)}, and Secret Manager's IDs take only letters, digits, "-", and "_", up to 255 characters.`);
+		if (!SECRET_ID_PATTERN.test(id)) throw failure([
+			`${ADAPTER_NAME} can't name a secret ${JSON.stringify(name)}.`,
+			`Secret: ${id}`,
+			"Secret Manager's IDs take up to 255 letters, digits, \"-\", and \"_\"."
+		]);
 		return id;
 	};
 	const request = async (token, method, path, body) => {
@@ -474,14 +549,18 @@ const secretManager = ({ projectId, prefix = "hot-updater-", credentials }) => {
 	const accessLatest = async (token, secret) => {
 		const response = await request(token, "GET", `${secret}/versions/latest:access`);
 		if (response.status === 404) return void 0;
-		if (!response.ok) throw requestError(`read ${secret}`, response, "roles/secretmanager.secretAccessor on the secret");
+		if (!response.ok) throw requestError("read", secret, response, "roles/secretmanager.secretAccessor on the secret");
 		const body = isRecord(response.body) ? response.body : void 0;
 		const payload = body?.payload;
 		const data = isRecord(payload) ? payload.data : void 0;
-		if (typeof data !== "string") throw new Error(`${ADAPTER_NAME} read no payload for ${secret}.`);
+		if (typeof data !== "string") throw failure([`${ADAPTER_NAME} read no payload.`, resourceLine(secret)]);
 		const bytes = Buffer.from(data, "base64");
 		const checksum = isRecord(payload) ? payload.dataCrc32c : void 0;
-		if (checksum !== void 0 && Number(checksum) !== crc32c(bytes)) throw new Error(`${ADAPTER_NAME} read ${secret} with a checksum that does not match its payload.`);
+		if (checksum !== void 0 && Number(checksum) !== crc32c(bytes)) throw failure([
+			`${ADAPTER_NAME} can't trust what it read.`,
+			resourceLine(secret),
+			"Its checksum doesn't match its payload."
+		]);
 		const value = bytes.toString("utf8");
 		await mask(value);
 		return {
@@ -514,7 +593,7 @@ const secretManager = ({ projectId, prefix = "hot-updater-", credentials }) => {
 	const readSecret = async (token, secret) => {
 		const response = await request(token, "GET", secret);
 		if (response.status === 404) return void 0;
-		if (!response.ok) throw requestError(`read ${secret}`, response, "secretmanager.secrets.get on the secret");
+		if (!response.ok) throw requestError("read", secret, response, "secretmanager.secrets.get on the secret");
 		return response.body;
 	};
 	const getOrCreateSecret = async (token, parent, id) => {
@@ -527,14 +606,21 @@ const secretManager = ({ projectId, prefix = "hot-updater-", credentials }) => {
 			const raced = await readSecret(token, secret);
 			if (raced) return raced;
 		}
-		throw requestError(`create ${secret}`, created, `secretmanager.secrets.create on ${parent}`);
+		throw requestError("create", secret, created, `secretmanager.secrets.create on ${parent}`);
 	};
 	const assertCanSet = async (token, secret) => {
 		const response = await request(token, "POST", `${secret}:testIamPermissions`, { permissions: SET_PERMISSIONS });
-		if (!response.ok) throw requestError(`check its permissions on ${secret}`, response, SET_PERMISSIONS.join(", "));
+		if (!response.ok) throw requestError("check its permissions", secret, response, SET_PERMISSIONS.join(", "));
 		const held = isRecord(response.body) && Array.isArray(response.body.permissions) ? response.body.permissions : [];
 		const missing = SET_PERMISSIONS.filter((name) => !held.includes(name));
-		if (missing.length > 0) throw new Error(`${ADAPTER_NAME} stores a value as a new version of ${secret} and destroys the versions it added before, and the Google identity lacks ${missing.join(", ")} on it: grant a custom role with secretmanager.secrets.get, secretmanager.secrets.update, secretmanager.versions.add, secretmanager.versions.destroy, and secretmanager.versions.access on it, or roles/secretmanager.admin.`);
+		if (missing.length > 0) throw failure([
+			`${ADAPTER_NAME} can't store a value.`,
+			resourceLine(secret),
+			...wrap(`The Google identity lacks ${missing.join(", ")} on it.`),
+			"It adds a version, then destroys the versions it added before.",
+			"Grant roles/secretmanager.admin, or a custom role with:",
+			...wrap("secretmanager.secrets.get, secretmanager.secrets.update, secretmanager.versions.add, secretmanager.versions.destroy, secretmanager.versions.access")
+		]);
 	};
 	/**
 	* Destroys `version` of `secret`: true once it is destroyed, or already
@@ -581,7 +667,7 @@ const secretManager = ({ projectId, prefix = "hot-updater-", credentials }) => {
 			const parent = projectPath();
 			const id = secretId(name);
 			const secret = `${parent}/secrets/${id}`;
-			if (typeof value !== "string" || value === "") throw new Error(`${ADAPTER_NAME} cannot store an empty ${secret}.`);
+			if (typeof value !== "string" || value === "") throw failure([`${ADAPTER_NAME} can't store an empty value.`, resourceLine(secret)]);
 			await mask(value);
 			const token = await accessToken();
 			const current = await getOrCreateSecret(token, parent, id);
@@ -592,7 +678,7 @@ const secretManager = ({ projectId, prefix = "hot-updater-", credentials }) => {
 				dataCrc32c: String(crc32c(data))
 			} });
 			const version = versionOf(isRecord(added.body) ? added.body.name : void 0);
-			if (!added.ok || !VERSION_ID_PATTERN.test(version)) throw requestError(`add a version to ${secret}`, added, "secretmanager.versions.add on the secret");
+			if (!added.ok || !VERSION_ID_PATTERN.test(version)) throw requestError("add a version", secret, added, "secretmanager.versions.add on the secret");
 			const visible = await waitForLatest(token, secret, version);
 			const destroyed = /* @__PURE__ */ new Set();
 			if (visible) {
@@ -602,7 +688,8 @@ const secretManager = ({ projectId, prefix = "hot-updater-", credentials }) => {
 					if (results[index]) destroyed.add(entry);
 				});
 			}
-			const notListed = `list version ${version}, which it stored, in ${secret}'s ${VERSIONS_ANNOTATION} annotation, so the next set will not destroy it`;
+			const notListed = `record version ${version}, which it stored`;
+			const notDestroyed = `The next set won't destroy it: ${VERSIONS_ANNOTATION} misses it.`;
 			let base = current;
 			let updated;
 			try {
@@ -622,10 +709,20 @@ const secretManager = ({ projectId, prefix = "hot-updater-", credentials }) => {
 					if (updated.error.status !== "FAILED_PRECONDITION") break;
 				}
 			} catch (error) {
-				throw new Error(`${ADAPTER_NAME} could not ${notListed} (${error instanceof Error ? error.message : String(error)}).`, { cause: error });
+				throw failure([
+					`${ADAPTER_NAME} couldn't ${notListed}.`,
+					resourceLine(secret),
+					...wrap(error instanceof Error ? error.message : String(error)),
+					notDestroyed
+				], error);
 			}
-			if (!updated?.ok) throw requestError(notListed, updated, "secretmanager.secrets.update on the secret");
-			if (!visible) throw new Error(`${ADAPTER_NAME} stored ${secret} as version ${version}, and its latest alias does not resolve to that version yet, so it kept the versions it added before; the next set destroys them.`);
+			if (!updated?.ok) throw requestError(notListed, secret, updated, "secretmanager.secrets.update on the secret", [notDestroyed]);
+			if (!visible) throw failure([
+				`${ADAPTER_NAME} stored version ${version}.`,
+				resourceLine(secret),
+				"Its latest alias doesn't resolve to that version yet.",
+				"It kept the versions it added before: the next set destroys them."
+			]);
 		},
 		describe: (name) => {
 			const id = `${prefix}${name}`;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hot-updater/firebase",
   "type": "module",
-  "version": "1.2.0-rc.7",
+  "version": "1.2.0-rc.9",
   "description": "React Native OTA solution for self-hosted",
   "main": "dist/index.cjs",
   "types": "dist/index.d.cts",
@@ -38,10 +38,10 @@
   "dependencies": {
     "hono": "4.12.34",
     "google-auth-library": "10.7.0",
-    "@hot-updater/cli-tools": "1.2.0-rc.7",
-    "@hot-updater/protocol": "1.2.0-rc.7",
-    "@hot-updater/plugin-core": "1.2.0-rc.7",
-    "@hot-updater/server": "1.2.0-rc.7"
+    "@hot-updater/protocol": "1.2.0-rc.9",
+    "@hot-updater/plugin-core": "1.2.0-rc.9",
+    "@hot-updater/server": "1.2.0-rc.9",
+    "@hot-updater/cli-tools": "1.2.0-rc.9"
   },
   "publishConfig": {
     "access": "public"
@@ -56,8 +56,8 @@
     "firebase-tools": "15.29.0",
     "fkill": "^9.0.0",
     "mime": "^4.0.4",
-    "@hot-updater/test-utils": "1.2.0-rc.7",
-    "@hot-updater/mock": "1.2.0-rc.7"
+    "@hot-updater/mock": "1.2.0-rc.9",
+    "@hot-updater/test-utils": "1.2.0-rc.9"
   },
   "peerDependencies": {
     "firebase-admin": ">=11.10.0",