@backblaze-labs/b2-sdk 0.2.0 → 0.4.0

package/dist/raw/index.js

@@ -1,8 +1,11 @@
 import { FinishLargeFileResponseBodyError, UploadResponseBodyError } from "../errors/index.js";
 import { buildFileInfoHeaders, decodeFileName, encodeFileName, parseFileInfoHeaders } from "./encoding.js";
-import { normalizeFileVersionListSha1, normalizeFileVersionSha1 } from "../util/normalize.js";
 import { EncryptionAlgorithm, EncryptionMode } from "../types/encryption.js";
+import { normalizeFileVersionListSha1, normalizeFileVersionSha1 } from "../util/normalize.js";
+import { BUCKET_INFO_KEY_MAX_BYTES, BUCKET_INFO_KEY_MIN_BYTES, BUCKET_INFO_KEY_PATTERN, BUCKET_INFO_RESERVED_PREFIX, BUCKET_INFO_VALUES_MAX_BYTES, BucketKeyOption, CORS_ALLOWED_OPERATIONS, CORS_MAX_AGE_SECONDS_MAX, CORS_RULES_MAX_COUNT, CORS_RULE_MAX_BYTES, CORS_RULE_NAME_MAX_LENGTH, CORS_RULE_NAME_MIN_LENGTH, CORS_RULE_NAME_PATTERN, CORS_RULE_NAME_RESERVED_PREFIX, CorsOperation } from "../types/bucket.js";
+import { assertValidBucketConfiguration, assertValidBucketInfo, assertValidCorsRules } from "../bucket-validation.js";
 import { assertSecureRealmUrl } from "../auth/realms.js";
+import { b2Url } from "./url.js";
 //#region src/raw/index.ts
 /**
 * Low-level 1:1 bindings for every B2 native API endpoint.
@@ -11,9 +14,16 @@ import { assertSecureRealmUrl } from "../auth/realms.js";
 * with fully typed request and response objects. No retry logic, no URL pooling,
 * no automatic reauthorization. Use this when you need precise control over
 * individual API calls; for most use cases prefer the high-level `B2Client`.
+* SDK-built B2 native storage API URLs use `/b2api/v4`. JSON endpoints use
+* POST request bodies, including read/list endpoints whose API docs also show
+* GET query examples but document POST JSON compatibility.
 *
 * @packageDocumentation
 */
+var B2_NATIVE_API = {
+	prefix: "b2api",
+	version: "v4"
+};
 function normalizeRawRequestOptions(optionsOrSignal, retry) {
 	if (optionsOrSignal === void 0) return retry === void 0 ? void 0 : { retry };
 	if (isAbortSignal(optionsOrSignal)) return {
@@ -28,6 +38,34 @@ function normalizeRawRequestOptions(optionsOrSignal, retry) {
 function isAbortSignal(value) {
 	return typeof value === "object" && value !== null && "aborted" in value && typeof value.addEventListener === "function";
 }
+function assertCustomUploadTimestamp(value) {
+	if (value === void 0) return;
+	if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0) return;
+	throw new TypeError("customUploadTimestamp must be a non-negative safe integer");
+}
+function assertSafeHttpHeaderValue(name, value) {
+	if (hasHttpHeaderControlByte(value)) throw new TypeError(`${name} must not contain HTTP control characters`);
+}
+function hasHttpHeaderControlByte(value) {
+	for (let i = 0; i < value.length; i += 1) {
+		const code = value.charCodeAt(i);
+		if (code <= 31 || code === 127) return true;
+	}
+	return false;
+}
+function setB2ContentFileInfoHeader(headers, key, optionName, value) {
+	if (!value) return;
+	assertSafeHttpHeaderValue(optionName, value);
+	Object.assign(headers, buildFileInfoHeaders({ [key]: value }));
+}
+function assertRawCustomUploadTimestamp(value) {
+	if (value === void 0 || value === null) return;
+	if (typeof value === "string" && /^\d+$/.test(value)) {
+		const timestamp = Number(value);
+		if (Number.isSafeInteger(timestamp)) return;
+	}
+	throw new TypeError("customUploadTimestamp must be a non-negative safe integer string or null");
+}
 function normalizeCreateKeyRequest(request) {
 	const { bucketId, ...withoutDeprecatedBucketId } = request;
 	if (bucketId !== void 0 && withoutDeprecatedBucketId.bucketIds !== void 0) throw new TypeError("createKey accepts either bucketIds or deprecated bucketId, not both");
@@ -91,7 +129,8 @@ function normalizeAuthorizeAccountResponse(response) {
 }
 function uploadResponseBodyError(err, signal) {
 	if (signal?.aborted === true) throw signal.reason ?? new DOMException("Aborted", "AbortError");
-	return new UploadResponseBodyError(err instanceof Error ? err.message : "Upload response body could not be read", { cause: err });
+	const message = err instanceof Error ? err.message : "Upload response body could not be read";
+	return new UploadResponseBodyError(message, { cause: err });
 }
 /**
 * Low-level client providing 1:1 bindings to all B2 native API endpoints.
@@ -115,15 +154,21 @@ var RawClient = class {
 	* @param applicationKeyId - The application key ID for authentication.
 	* @param applicationKey - The application key secret.
 	* @param realmUrl - The B2 realm URL to authenticate against.
+	* @param options - Optional request controls.
 	*
 	* @returns The authorization response with API URLs and credentials.
 	*/
-	async authorizeAccount(applicationKeyId, applicationKey, realmUrl = "https://api.backblazeb2.com") {
+	async authorizeAccount(applicationKeyId, applicationKey, realmUrl = "https://api.backblazeb2.com", options) {
 		assertSecureRealmUrl(realmUrl);
 		return normalizeAuthorizeAccountResponse(await (await this.transport.send({
-			url: `${realmUrl}/b2api/v4/b2_authorize_account`,
+			url: b2Url(realmUrl, {
+				...B2_NATIVE_API,
+				endpoint: "b2_authorize_account"
+			}),
 			method: "GET",
-			headers: { Authorization: `Basic ${btoa(`${applicationKeyId}:${applicationKey}`)}` }
+			headers: { Authorization: `Basic ${btoa(`${applicationKeyId}:${applicationKey}`)}` },
+			...options?.signal !== void 0 ? { signal: options.signal } : {},
+			...options?.retry !== void 0 ? { retry: options.retry } : {}
 		})).json());
 	}
 	/**
@@ -135,6 +180,7 @@ var RawClient = class {
 	* @returns The created bucket metadata.
 	*/
 	async createBucket(apiUrl, authToken, request) {
+		assertValidBucketConfiguration(request);
 		return this.postJson(apiUrl, authToken, "b2_create_bucket", request);
 	}
 	/**
@@ -168,6 +214,7 @@ var RawClient = class {
 	* @returns The updated bucket metadata.
 	*/
 	async updateBucket(apiUrl, authToken, request) {
+		assertValidBucketConfiguration(request);
 		return this.postJson(apiUrl, authToken, "b2_update_bucket", request);
 	}
 	/**
@@ -195,6 +242,9 @@ var RawClient = class {
 	*/
 	async uploadFile(uploadUrl, headers, body, optionsOrSignal, retry) {
 		const options = normalizeRawRequestOptions(optionsOrSignal, retry);
+		assertSafeHttpHeaderValue("authorization", headers.authorization);
+		assertSafeHttpHeaderValue("contentType", headers.contentType);
+		assertSafeHttpHeaderValue("contentSha1", headers.contentSha1);
 		const reqHeaders = {
 			Authorization: headers.authorization,
 			"X-Bz-File-Name": encodeFileName(headers.fileName),
@@ -204,11 +254,15 @@ var RawClient = class {
 			...buildFileInfoHeaders(headers.fileInfo)
 		};
 		if (headers.lastModifiedMillis !== void 0) reqHeaders["X-Bz-Info-src_last_modified_millis"] = String(headers.lastModifiedMillis);
-		if (headers.contentDisposition) reqHeaders["X-Bz-Info-b2-content-disposition"] = headers.contentDisposition;
-		if (headers.contentLanguage) reqHeaders["X-Bz-Info-b2-content-language"] = headers.contentLanguage;
-		if (headers.expires) reqHeaders["X-Bz-Info-b2-expires"] = headers.expires;
-		if (headers.cacheControl) reqHeaders["X-Bz-Info-b2-cache-control"] = headers.cacheControl;
-		if (headers.contentEncoding) reqHeaders["X-Bz-Info-b2-content-encoding"] = headers.contentEncoding;
+		if (headers.customUploadTimestamp !== void 0) {
+			assertCustomUploadTimestamp(headers.customUploadTimestamp);
+			reqHeaders["X-Bz-Custom-Upload-Timestamp"] = String(headers.customUploadTimestamp);
+		}
+		setB2ContentFileInfoHeader(reqHeaders, "b2-content-disposition", "contentDisposition", headers.contentDisposition);
+		setB2ContentFileInfoHeader(reqHeaders, "b2-content-language", "contentLanguage", headers.contentLanguage);
+		setB2ContentFileInfoHeader(reqHeaders, "b2-expires", "expires", headers.expires);
+		setB2ContentFileInfoHeader(reqHeaders, "b2-cache-control", "cacheControl", headers.cacheControl);
+		setB2ContentFileInfoHeader(reqHeaders, "b2-content-encoding", "contentEncoding", headers.contentEncoding);
 		applyEncryptionHeaders(reqHeaders, headers.serverSideEncryption);
 		applyRetentionHeaders(reqHeaders, headers.fileRetention);
 		applyLegalHoldHeader(reqHeaders, headers.legalHold);
@@ -226,27 +280,9 @@ var RawClient = class {
 			throw uploadResponseBodyError(err, options?.signal);
 		}
 	}
-	/**
-	* Calls {@link https://www.backblaze.com/apidocs/b2-list-file-names | b2_list_file_names}.
-	* @param apiUrl - The B2 API base URL.
-	* @param authToken - The authorization token.
-	* @param request - The API request parameters.
-	* @param options - Optional request controls such as an abort signal.
-	*
-	* @returns The list of file names and optional continuation token.
-	*/
 	async listFileNames(apiUrl, authToken, request, options) {
 		return normalizeFileVersionListSha1(await this.postJson(apiUrl, authToken, "b2_list_file_names", request, options));
 	}
-	/**
-	* Calls {@link https://www.backblaze.com/apidocs/b2-list-file-versions | b2_list_file_versions}.
-	* @param apiUrl - The B2 API base URL.
-	* @param authToken - The authorization token.
-	* @param request - The API request parameters.
-	* @param options - Optional request controls such as an abort signal.
-	*
-	* @returns The list of file versions and optional continuation token.
-	*/
 	async listFileVersions(apiUrl, authToken, request, options) {
 		return normalizeFileVersionListSha1(await this.postJson(apiUrl, authToken, "b2_list_file_versions", request, options));
 	}
@@ -295,7 +331,7 @@ var RawClient = class {
 	* @returns The copied file version metadata.
 	*/
 	async copyFile(apiUrl, authToken, request, options) {
-		return normalizeFileVersionSha1(await this.postJson(apiUrl, authToken, "b2_copy_file", request, options));
+		return normalizeFileVersionSha1(await this.postJson(apiUrl, authToken, "b2_copy_file", withJsonBodyWireSseC(request), options));
 	}
 	/**
 	* Calls {@link https://www.backblaze.com/apidocs/b2-copy-part | b2_copy_part}.
@@ -307,7 +343,7 @@ var RawClient = class {
 	* @returns The copied part metadata.
 	*/
 	async copyPart(apiUrl, authToken, request, options) {
-		return this.postJson(apiUrl, authToken, "b2_copy_part", request, options);
+		return this.postJson(apiUrl, authToken, "b2_copy_part", withJsonBodyWireSseC(request), options);
 	}
 	/**
 	* Calls {@link https://www.backblaze.com/apidocs/b2-start-large-file | b2_start_large_file}.
@@ -319,7 +355,8 @@ var RawClient = class {
 	* @returns The started large file metadata with file ID.
 	*/
 	async startLargeFile(apiUrl, authToken, request, options) {
-		return this.postJson(apiUrl, authToken, "b2_start_large_file", request, options);
+		assertRawCustomUploadTimestamp(request.customUploadTimestamp);
+		return normalizeFileVersionSha1(await this.postJson(apiUrl, authToken, "b2_start_large_file", withJsonBodyWireSseC(request), options));
 	}
 	/**
 	* Implementation for both upload part URL request-control signatures.
@@ -346,6 +383,8 @@ var RawClient = class {
 	*/
 	async uploadPart(uploadUrl, headers, body, optionsOrSignal, retry) {
 		const options = normalizeRawRequestOptions(optionsOrSignal, retry);
+		assertSafeHttpHeaderValue("authorization", headers.authorization);
+		assertSafeHttpHeaderValue("contentSha1", headers.contentSha1);
 		const reqHeaders = {
 			Authorization: headers.authorization,
 			"X-Bz-Part-Number": String(headers.partNumber),
@@ -378,7 +417,10 @@ var RawClient = class {
 	*/
 	async finishLargeFile(apiUrl, authToken, request, options) {
 		const response = await this.transport.send({
-			url: `${apiUrl}/b2api/v3/b2_finish_large_file`,
+			url: b2Url(apiUrl, {
+				...B2_NATIVE_API,
+				endpoint: "b2_finish_large_file"
+			}),
 			method: "POST",
 			headers: {
 				Authorization: authToken,
@@ -421,7 +463,7 @@ var RawClient = class {
 	* @returns The list of unfinished large files and optional continuation token.
 	*/
 	async listUnfinishedLargeFiles(apiUrl, authToken, request, options) {
-		return this.postJson(apiUrl, authToken, "b2_list_unfinished_large_files", request, options);
+		return normalizeFileVersionListSha1(await this.postJson(apiUrl, authToken, "b2_list_unfinished_large_files", request, options));
 	}
 	/**
 	* Calls {@link https://www.backblaze.com/apidocs/b2-list-parts | b2_list_parts}.
@@ -446,7 +488,10 @@ var RawClient = class {
 	*/
 	async downloadFileById(downloadUrl, authToken, fileId, options) {
 		const headers = buildDownloadRequestHeaders(authToken, options);
-		const url = appendDownloadOverrides(`${downloadUrl}/b2api/v3/b2_download_file_by_id?fileId=${encodeURIComponent(fileId)}`, options);
+		const url = appendDownloadOverrides(`${b2Url(downloadUrl, {
+			...B2_NATIVE_API,
+			endpoint: "b2_download_file_by_id"
+		})}?fileId=${encodeURIComponent(fileId)}`, options);
 		const response = await this.transport.send({
 			url,
 			method: options?.method ?? "GET",
@@ -504,7 +549,7 @@ var RawClient = class {
 	* @returns The newly created application key with secret.
 	*/
 	async createKey(apiUrl, authToken, request) {
-		return normalizeKeyResponse(await this.postJson(apiUrl, authToken, "b2_create_key", normalizeCreateKeyRequest(request), void 0, "v4"));
+		return normalizeKeyResponse(await this.postJson(apiUrl, authToken, "b2_create_key", normalizeCreateKeyRequest(request)));
 	}
 	/**
 	* Calls {@link https://www.backblaze.com/apidocs/b2-list-keys | b2_list_keys}.
@@ -515,7 +560,7 @@ var RawClient = class {
 	* @returns The list of application keys and optional continuation token.
 	*/
 	async listKeys(apiUrl, authToken, request) {
-		const response = await this.postJson(apiUrl, authToken, "b2_list_keys", request, void 0, "v4");
+		const response = await this.postJson(apiUrl, authToken, "b2_list_keys", request);
 		return {
 			...response,
 			keys: response.keys.map((key) => normalizeKeyResponse(key))
@@ -530,7 +575,7 @@ var RawClient = class {
 	* @returns The deleted application key metadata.
 	*/
 	async deleteKey(apiUrl, authToken, request) {
-		return normalizeKeyResponse(await this.postJson(apiUrl, authToken, "b2_delete_key", request, void 0, "v4"));
+		return normalizeKeyResponse(await this.postJson(apiUrl, authToken, "b2_delete_key", request));
 	}
 	/**
 	* Calls {@link https://www.backblaze.com/apidocs/b2-update-file-retention | b2_update_file_retention}.
@@ -583,13 +628,15 @@ var RawClient = class {
 	* @param endpoint - The B2 API endpoint name.
 	* @param body - The JSON request body.
 	* @param options - Optional abort and per-request retry settings.
-	* @param apiVersion - B2 Native API version segment for this endpoint.
 	*
 	* @returns The parsed JSON response.
 	*/
-	async postJson(apiUrl, authToken, endpoint, body, options, apiVersion = "v3") {
+	async postJson(apiUrl, authToken, endpoint, body, options) {
 		return (await this.transport.send({
-			url: `${apiUrl}/b2api/${apiVersion}/${endpoint}`,
+			url: b2Url(apiUrl, {
+				...B2_NATIVE_API,
+				endpoint
+			}),
 			method: "POST",
 			headers: {
 				Authorization: authToken,
@@ -601,6 +648,23 @@ var RawClient = class {
 		})).json();
 	}
 };
+function withJsonBodyWireSseC(request) {
+	return {
+		...request,
+		...request.serverSideEncryption !== void 0 ? { serverSideEncryption: toWireSseC(request.serverSideEncryption) } : {},
+		...request.sourceServerSideEncryption !== void 0 ? { sourceServerSideEncryption: toWireSseC(request.sourceServerSideEncryption) } : {},
+		...request.destinationServerSideEncryption !== void 0 ? { destinationServerSideEncryption: toWireSseC(request.destinationServerSideEncryption) } : {}
+	};
+}
+function toWireSseC(setting) {
+	if (setting.mode !== EncryptionMode.SseC) return setting;
+	return {
+		mode: EncryptionMode.SseC,
+		algorithm: setting.algorithm,
+		customerKey: setting.customerKey,
+		customerKeyMd5: setting.customerKeyMd5
+	};
+}
 /**
 * Applies server-side encryption headers to the request.
 * @param headers - The mutable headers object to populate.
@@ -635,10 +699,15 @@ var DOWNLOAD_OVERRIDE_PARAMS = [
 function buildDownloadRequestHeaders(authToken, options) {
 	const headers = { Authorization: authToken };
 	if (options?.range) headers["Range"] = options.range;
-	if (options?.serverSideEncryption) applyEncryptionHeaders(headers, {
-		mode: EncryptionMode.SseC,
-		...options.serverSideEncryption
-	});
+	if (options?.serverSideEncryption) {
+		const encryption = options.serverSideEncryption;
+		applyEncryptionHeaders(headers, {
+			mode: EncryptionMode.SseC,
+			algorithm: encryption.algorithm,
+			customerKey: encryption.customerKey,
+			customerKeyMd5: encryption.customerKeyMd5
+		});
+	}
 	return headers;
 }
 /**
@@ -681,6 +750,6 @@ function applyLegalHoldHeader(headers, legalHold) {
 	headers["X-Bz-File-Legal-Hold"] = legalHold;
 }
 //#endregion
-export { RawClient, buildFileInfoHeaders, decodeFileName, encodeFileName, parseFileInfoHeaders };
+export { BUCKET_INFO_KEY_MAX_BYTES, BUCKET_INFO_KEY_MIN_BYTES, BUCKET_INFO_KEY_PATTERN, BUCKET_INFO_RESERVED_PREFIX, BUCKET_INFO_VALUES_MAX_BYTES, BucketKeyOption, CORS_ALLOWED_OPERATIONS, CORS_MAX_AGE_SECONDS_MAX, CORS_RULES_MAX_COUNT, CORS_RULE_MAX_BYTES, CORS_RULE_NAME_MAX_LENGTH, CORS_RULE_NAME_MIN_LENGTH, CORS_RULE_NAME_PATTERN, CORS_RULE_NAME_RESERVED_PREFIX, CorsOperation, RawClient, assertValidBucketConfiguration, assertValidBucketInfo, assertValidCorsRules, buildFileInfoHeaders, decodeFileName, encodeFileName, parseFileInfoHeaders };
 
 //# sourceMappingURL=index.js.map