@backblaze-labs/b2-sdk 0.3.0 → 0.4.0

package/dist/bucket.js

@@ -1,3 +1,4 @@
+import { FileAction } from "./types/file.js";
 import { accountId } from "./types/ids.js";
 import { Semaphore } from "./upload/concurrency.js";
 import "./util/defaults.js";
@@ -11,6 +12,14 @@ import { toError } from "./util/to-error.js";
 import { B2Object } from "./object.js";
 import { paginateItems } from "./util/paginator.js";
 //#region src/bucket.ts
+var EMPTY_REPLICATION_CONFIGURATION = {
+	asReplicationSource: null,
+	asReplicationDestination: null
+};
+function readableReplicationConfigurationOrEmpty(response, operation) {
+	if (!response.isClientAuthorizedToRead) throw new Error(`${operation}: replication configuration is not readable; grant readBucketReplications before composing replication updates`);
+	return response.value ?? EMPTY_REPLICATION_CONFIGURATION;
+}
 function bucketDefaultRetentionSnapshot(info) {
 	const fileLock = info.fileLockConfiguration;
 	if (!fileLock.isClientAuthorizedToRead) return { unreadable: true };
@@ -20,9 +29,69 @@ function bucketDefaultRetentionSnapshot(info) {
 		unreadable: false
 	};
 }
+function bucketDefaultServerSideEncryptionSnapshot(info) {
+	const encryption = info.defaultServerSideEncryption;
+	if (!encryption.isClientAuthorizedToRead) return { unreadable: true };
+	if (encryption.value === null) return { unreadable: false };
+	return {
+		encryption: encryption.value,
+		unreadable: false
+	};
+}
 function resumeNeedsFreshBucketDefaults(options) {
 	return (options.resume === true || options.resumeFileId !== void 0) && (options.serverSideEncryption === void 0 || options.fileRetention === void 0);
 }
+function listedVersionFileIdOrThrow(version) {
+	const fileId = version.fileId;
+	if (typeof fileId === "string") return fileId;
+	throw new Error(`deleteAll: listFileVersions returned a row without a fileId for ${JSON.stringify(version.fileName)}; delimiter folder rows are invalid because deleteAll does not request delimiter grouping`);
+}
+function listedFileIdOrThrow(version, operation) {
+	if (typeof version.fileId === "string") return version.fileId;
+	throw new Error(`${operation}: list response returned a row without a string fileId for ${JSON.stringify(version.fileName)}`);
+}
+function assertNotFolderListEntry(version, operation) {
+	if (version.action !== FileAction.Folder) return;
+	throw new Error(`${operation}: list response returned a delimiter folder row for ${JSON.stringify(version.fileName)} without requesting delimiter grouping`);
+}
+function validateListedConcreteEntry(version, operation) {
+	assertNotFolderListEntry(version, operation);
+	listedFileIdOrThrow(version, operation);
+	return version;
+}
+function validateListedNameEntry(version, operation, options) {
+	if (version.action === FileAction.Folder) {
+		if (options.allowFolder) return version;
+		throw new Error(`${operation}: list response returned a delimiter folder row for ${JSON.stringify(version.fileName)} without requesting delimiter grouping`);
+	}
+	if (version.action === FileAction.Hide) throw new Error(`${operation}: list response returned a hide marker for ${JSON.stringify(version.fileName)}; b2_list_file_names only returns visible file versions`);
+	listedFileIdOrThrow(version, operation);
+	return version;
+}
+function validateListFileNamesResponse(response, options) {
+	const files = response.files.map((version) => validateListedNameEntry(version, "listFileNames", options));
+	return {
+		...response,
+		files
+	};
+}
+function validateListFileVersionsResponse(response, options) {
+	if (options.allowFolder) {
+		const files = response.files.map((version) => {
+			if (version.action === FileAction.Folder) return version;
+			return validateListedConcreteEntry(version, "listFileVersions");
+		});
+		return {
+			...response,
+			files
+		};
+	}
+	const files = response.files.map((version) => validateListedConcreteEntry(version, "listFileVersions"));
+	return {
+		...response,
+		files
+	};
+}
 /**
 * Handle to a B2 bucket providing upload, download, listing, and management operations.
 *
@@ -80,11 +149,13 @@ var Bucket = class {
 		if (isLarge) {
 			const bucketInfo = resumeNeedsFreshBucketDefaults(options) ? await this.refresh() : this.info;
 			const bucketDefaultRetention = bucketDefaultRetentionSnapshot(bucketInfo);
+			const bucketDefaultSse = bucketDefaultServerSideEncryptionSnapshot(bucketInfo);
 			return uploadLargeFile(this.client.raw, this.client.accountInfo, {
 				...options,
 				bucketId: this.id,
 				retry: uploadRetryOptions,
-				bucketDefaultServerSideEncryption: bucketInfo.defaultServerSideEncryption,
+				...bucketDefaultSse.encryption !== void 0 ? { bucketDefaultServerSideEncryption: bucketDefaultSse.encryption } : {},
+				...bucketDefaultSse.unreadable ? { bucketDefaultServerSideEncryptionUnreadable: true } : {},
 				...bucketDefaultRetention.retention !== void 0 ? { bucketDefaultRetention: bucketDefaultRetention.retention } : {},
 				...bucketDefaultRetention.unreadable ? { bucketDefaultRetentionUnreadable: true } : {}
 			});
@@ -142,29 +213,18 @@ var Bucket = class {
 			...options
 		});
 	}
-	/**
-	* Lists file names in this bucket (most recent versions only).
-	* @param options - Optional filtering and pagination settings.
-	*
-	* @returns A page of file versions with an optional continuation token.
-	*/
 	async listFileNames(options) {
-		return this.client.raw.listFileNames(this.client.accountInfo.getApiUrl(), this.client.accountInfo.getAuthToken(), {
+		const response = await this.client.raw.listFileNames(this.client.accountInfo.getApiUrl(), this.client.accountInfo.getAuthToken(), {
 			bucketId: this.id,
 			...options?.startFileName !== void 0 ? { startFileName: options.startFileName } : {},
 			...options?.pageSize !== void 0 ? { maxFileCount: options.pageSize } : {},
 			...options?.prefix !== void 0 ? { prefix: options.prefix } : {},
 			...options?.delimiter !== void 0 ? { delimiter: options.delimiter } : {}
 		}, { ...options?.signal !== void 0 ? { signal: options.signal } : {} });
+		return options?.delimiter !== void 0 ? validateListFileNamesResponse(response, { allowFolder: true }) : validateListFileNamesResponse(response, { allowFolder: false });
 	}
-	/**
-	* Lists all file versions in this bucket, including hidden files.
-	* @param options - Optional filtering and pagination settings.
-	*
-	* @returns A page of file versions with an optional continuation token.
-	*/
 	async listFileVersions(options) {
-		return this.client.raw.listFileVersions(this.client.accountInfo.getApiUrl(), this.client.accountInfo.getAuthToken(), {
+		const response = await this.client.raw.listFileVersions(this.client.accountInfo.getApiUrl(), this.client.accountInfo.getAuthToken(), {
 			bucketId: this.id,
 			...options?.startFileName !== void 0 ? { startFileName: options.startFileName } : {},
 			...options?.startFileId !== void 0 ? { startFileId: options.startFileId } : {},
@@ -172,65 +232,39 @@ var Bucket = class {
 			...options?.prefix !== void 0 ? { prefix: options.prefix } : {},
 			...options?.delimiter !== void 0 ? { delimiter: options.delimiter } : {}
 		}, { ...options?.signal !== void 0 ? { signal: options.signal } : {} });
+		return options?.delimiter !== void 0 ? validateListFileVersionsResponse(response, { allowFolder: true }) : validateListFileVersionsResponse(response, { allowFolder: false });
 	}
-	/**
-	* Async iterator that yields the latest visible version of every file in
-	* the bucket, automatically handling pagination via `listFileNames`.
-	*
-	* Hidden files (those whose latest version is a hide marker) are NOT
-	* yielded by this iterator. Use {@link paginateFileVersions} when you
-	* need full version history.
-	*
-	* @param options - Filter + pagination + abort options. `pageSize` is
-	*   forwarded to `b2_list_file_names`'s `maxFileCount` (default 1000,
-	*   B2-capped at 10000).
-	*
-	* @returns An async iterable of {@link FileVersion} entries.
-	*
-	* @example
-	* ```ts
-	* for await (const file of bucket.paginateFileNames({ prefix: 'photos/' })) {
-	*   console.log(file.fileName, file.contentLength)
-	* }
-	* ```
-	*/
 	paginateFileNames(options) {
 		return paginateItems(async (cursor) => {
-			const resp = await this.listFileNames({
+			const request = {
 				pageSize: options?.pageSize ?? 1e3,
 				...cursor !== void 0 ? { startFileName: cursor } : {},
 				...options?.prefix !== void 0 ? { prefix: options.prefix } : {},
-				...options?.delimiter !== void 0 ? { delimiter: options.delimiter } : {},
 				...options?.signal !== void 0 ? { signal: options.signal } : {}
-			});
+			};
+			const resp = options?.delimiter !== void 0 ? await this.listFileNames({
+				...request,
+				delimiter: options.delimiter
+			}) : await this.listFileNames(request);
 			return {
 				page: resp,
 				nextCursor: resp.nextFileName ?? void 0
 			};
-		}, (page) => page.files.filter((f) => f.action !== "hide"), options?.signal);
+		}, (page) => page.files, options?.signal);
 	}
-	/**
-	* Async iterator that yields every version of every file in the bucket,
-	* including hidden files and historical versions, automatically handling
-	* pagination via `listFileVersions`.
-	*
-	* The two-cursor `(nextFileName, nextFileId)` continuation that the raw
-	* endpoint exposes is threaded internally; callers iterate flat.
-	*
-	* @param options - Filter + pagination + abort options.
-	*
-	* @returns An async iterable of {@link FileVersion} entries.
-	*/
 	paginateFileVersions(options) {
 		return paginateItems(async (cursor) => {
-			const resp = await this.listFileVersions({
+			const request = {
 				pageSize: options?.pageSize ?? 1e3,
 				...cursor !== void 0 ? { startFileName: cursor.fileName } : {},
 				...cursor?.fileId !== void 0 ? { startFileId: cursor.fileId } : {},
 				...options?.prefix !== void 0 ? { prefix: options.prefix } : {},
-				...options?.delimiter !== void 0 ? { delimiter: options.delimiter } : {},
 				...options?.signal !== void 0 ? { signal: options.signal } : {}
-			});
+			};
+			const resp = options?.delimiter !== void 0 ? await this.listFileVersions({
+				...request,
+				delimiter: options.delimiter
+			}) : await this.listFileVersions(request);
 			return {
 				page: resp,
 				nextCursor: resp.nextFileName !== null ? {
@@ -293,7 +327,7 @@ var Bucket = class {
 	/**
 	* Looks up the latest visible version of a file by name.
 	* Uses `listFileNames` under the hood; returns `null` when the file does not
-	* exist or its latest version is a hide marker.
+	* exist or is hidden.
 	* @param fileName - The exact file path to look up.
 	*
 	* @returns The latest {@link FileVersion}, or `null` if not found.
@@ -303,7 +337,7 @@ var Bucket = class {
 			prefix: fileName,
 			pageSize: 1
 		})).files.find((f) => f.fileName === fileName);
-		if (!match || match.action === "hide") return null;
+		if (!match) return null;
 		return match;
 	}
 	/**
@@ -312,7 +346,7 @@ var Bucket = class {
 	* no hide marker to remove (file is already visible or does not exist).
 	* @param fileName - The file path to unhide.
 	*
-	* @returns The deleted hide marker version, or `null` if nothing was hidden.
+	* @returns The deleted listed hide-marker row, or `null` if nothing was hidden.
 	*/
 	async unhideFile(fileName) {
 		const versions = (await this.listFileVersions({
@@ -321,8 +355,10 @@ var Bucket = class {
 		})).files.filter((f) => f.fileName === fileName);
 		if (versions.length === 0) return null;
 		const latest = versions[0];
-		if (latest?.action !== "hide") return null;
-		await this.deleteFileVersion(fileName, latest.fileId);
+		if (latest?.action !== FileAction.Hide) return null;
+		const latestFileId = latest.fileId;
+		if (typeof latestFileId !== "string") throw new Error(`unhideFile: listFileVersions returned a hide marker without a fileId for ${JSON.stringify(fileName)}`);
+		await this.deleteFileVersion(fileName, latestFileId);
 		return latest;
 	}
 	/**
@@ -455,26 +491,27 @@ var Bucket = class {
 				...startFileId !== void 0 ? { startFileId } : {}
 			});
 			for (const version of page.files) {
+				const fileId = listedVersionFileIdOrThrow(version);
 				if (dryRun) {
 					yield {
 						type: "skip",
 						fileName: version.fileName,
-						fileId: version.fileId
+						fileId
 					};
 					continue;
 				}
 				try {
-					await this.deleteFileVersion(version.fileName, version.fileId);
+					await this.deleteFileVersion(version.fileName, fileId);
 					yield {
 						type: "delete",
 						fileName: version.fileName,
-						fileId: version.fileId
+						fileId
 					};
 				} catch (err) {
 					yield {
 						type: "error",
 						fileName: version.fileName,
-						fileId: version.fileId,
+						fileId,
 						message: toError(err).message
 					};
 				}
@@ -528,10 +565,18 @@ var Bucket = class {
 	* @returns Updated bucket metadata.
 	*/
 	async update(options) {
+		const { bucketInfo, bucketType, corsRules, defaultRetention, defaultServerSideEncryption, ifRevisionIs, lifecycleRules, replicationConfiguration } = options;
 		return this.client.raw.updateBucket(this.client.accountInfo.getApiUrl(), this.client.accountInfo.getAuthToken(), {
+			...bucketType !== void 0 ? { bucketType } : {},
+			...bucketInfo !== void 0 ? { bucketInfo } : {},
+			...corsRules !== void 0 ? { corsRules } : {},
+			...defaultServerSideEncryption !== void 0 ? { defaultServerSideEncryption } : {},
+			...defaultRetention !== void 0 ? { defaultRetention } : {},
+			...lifecycleRules !== void 0 ? { lifecycleRules } : {},
+			...replicationConfiguration !== void 0 ? { replicationConfiguration } : {},
+			...ifRevisionIs !== void 0 ? { ifRevisionIs } : {},
 			accountId: accountId(this.client.accountInfo.getAccountId()),
-			bucketId: this.id,
-			...options
+			bucketId: this.id
 		});
 	}
 	/**
@@ -638,7 +683,9 @@ var Bucket = class {
 	* write. For add/remove flows the helper methods below handle the
 	* refresh-then-set sequence for you.
 	*
-	* @returns The current {@link ReplicationConfiguration}.
+	* @returns The current readable replication wrapper. Its `value` is null
+	*   when no replication is configured or when the caller is not authorized
+	*   to read replication settings.
 	*/
 	async getReplication() {
 		return (await this.refresh()).replicationConfiguration;
@@ -672,9 +719,10 @@ var Bucket = class {
 	*
 	* @throws If no source-side replication exists yet and the caller did
 	*   not supply `sourceApplicationKeyId`.
+	* @throws If the caller is not authorized to read current replication settings.
 	*/
 	async addReplicationRule(rule, options) {
-		const current = (await this.refresh()).replicationConfiguration;
+		const current = readableReplicationConfigurationOrEmpty((await this.refresh()).replicationConfiguration, "addReplicationRule");
 		const existingSource = current.asReplicationSource;
 		const sourceKey = options?.sourceApplicationKeyId ?? existingSource?.sourceApplicationKeyId;
 		if (!sourceKey) throw new Error("addReplicationRule: no existing source-side replication; pass options.sourceApplicationKeyId");
@@ -694,9 +742,11 @@ var Bucket = class {
 	* @param replicationRuleName - Name of the rule to remove.
 	*
 	* @returns The updated bucket metadata.
+	*
+	* @throws If the caller is not authorized to read current replication settings.
 	*/
 	async removeReplicationRule(replicationRuleName) {
-		const current = (await this.refresh()).replicationConfiguration;
+		const current = readableReplicationConfigurationOrEmpty((await this.refresh()).replicationConfiguration, "removeReplicationRule");
 		const existingSource = current.asReplicationSource;
 		if (!existingSource) return this.setReplication(current);
 		const filtered = existingSource.replicationRules.filter((r) => r.replicationRuleName !== replicationRuleName);
@@ -759,12 +809,12 @@ var Bucket = class {
 	* Returns the current default Object Lock retention policy for new
 	* uploads to this bucket, refetched from B2.
 	*
-	* @returns The default {@link BucketRetentionPolicy} (which may be
-	*   `{ mode: 'none', period: null }` when Object Lock is enabled on the
-	*   bucket but no default is set).
+	* @returns The default {@link BucketDefaultRetention}, or `undefined` if
+	*   the file lock configuration is not readable. B2 represents no bucket
+	*   default retention as `{ mode: null, period: null }`.
 	*/
 	async getDefaultRetention() {
-		return (await this.refresh()).defaultRetention;
+		return bucketDefaultRetentionSnapshot(await this.refresh()).retention;
 	}
 	/**
 	* Sets (or clears, by passing `{ mode: 'none', period: null }`) the