@backblaze-labs/b2-sdk 0.2.0 → 0.3.0

package/dist/raw/index.js

@@ -1,8 +1,9 @@
 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 { 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.
@@ -14,6 +15,14 @@ import { assertSecureRealmUrl } from "../auth/realms.js";
 *
 * @packageDocumentation
 */
+var B2_NATIVE_API_V3 = {
+	prefix: "b2api",
+	version: "v3"
+};
+var B2_NATIVE_API_V4 = {
+	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 +37,19 @@ 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 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 +113,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.
@@ -121,7 +144,10 @@ var RawClient = class {
 	async authorizeAccount(applicationKeyId, applicationKey, realmUrl = "https://api.backblazeb2.com") {
 		assertSecureRealmUrl(realmUrl);
 		return normalizeAuthorizeAccountResponse(await (await this.transport.send({
-			url: `${realmUrl}/b2api/v4/b2_authorize_account`,
+			url: b2Url(realmUrl, {
+				...B2_NATIVE_API_V4,
+				endpoint: "b2_authorize_account"
+			}),
 			method: "GET",
 			headers: { Authorization: `Basic ${btoa(`${applicationKeyId}:${applicationKey}`)}` }
 		})).json());
@@ -204,6 +230,10 @@ var RawClient = class {
 			...buildFileInfoHeaders(headers.fileInfo)
 		};
 		if (headers.lastModifiedMillis !== void 0) reqHeaders["X-Bz-Info-src_last_modified_millis"] = String(headers.lastModifiedMillis);
+		if (headers.customUploadTimestamp !== void 0) {
+			assertCustomUploadTimestamp(headers.customUploadTimestamp);
+			reqHeaders["X-Bz-Custom-Upload-Timestamp"] = String(headers.customUploadTimestamp);
+		}
 		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;
@@ -295,7 +325,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 +337,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 +349,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.
@@ -378,7 +409,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_V3,
+				endpoint: "b2_finish_large_file"
+			}),
 			method: "POST",
 			headers: {
 				Authorization: authToken,
@@ -421,7 +455,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 +480,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_V3,
+			endpoint: "b2_download_file_by_id"
+		})}?fileId=${encodeURIComponent(fileId)}`, options);
 		const response = await this.transport.send({
 			url,
 			method: options?.method ?? "GET",
@@ -504,7 +541,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), void 0, B2_NATIVE_API_V4));
 	}
 	/**
 	* Calls {@link https://www.backblaze.com/apidocs/b2-list-keys | b2_list_keys}.
@@ -515,7 +552,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, void 0, B2_NATIVE_API_V4);
 		return {
 			...response,
 			keys: response.keys.map((key) => normalizeKeyResponse(key))
@@ -530,7 +567,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, void 0, B2_NATIVE_API_V4));
 	}
 	/**
 	* Calls {@link https://www.backblaze.com/apidocs/b2-update-file-retention | b2_update_file_retention}.
@@ -583,13 +620,16 @@ 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.
+	* @param urlOptions - B2 endpoint path prefix and version settings.
 	*
 	* @returns The parsed JSON response.
 	*/
-	async postJson(apiUrl, authToken, endpoint, body, options, apiVersion = "v3") {
+	async postJson(apiUrl, authToken, endpoint, body, options, urlOptions = B2_NATIVE_API_V3) {
 		return (await this.transport.send({
-			url: `${apiUrl}/b2api/${apiVersion}/${endpoint}`,
+			url: b2Url(apiUrl, {
+				...urlOptions,
+				endpoint
+			}),
 			method: "POST",
 			headers: {
 				Authorization: authToken,
@@ -601,6 +641,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 +692,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;
 }
 /**

package/dist/raw/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/raw/index.ts"],"sourcesContent":["/**\n * Low-level 1:1 bindings for every B2 native API endpoint.\n *\n * Each method on {@link RawClient} maps directly to a single `b2_*` HTTP call\n * with fully typed request and response objects. No retry logic, no URL pooling,\n * no automatic reauthorization. Use this when you need precise control over\n * individual API calls; for most use cases prefer the high-level `B2Client`.\n *\n * @packageDocumentation\n */\n\nimport { assertSecureRealmUrl } from '../auth/realms.ts'\nimport { FinishLargeFileResponseBodyError, UploadResponseBodyError } from '../errors/index.ts'\nimport type { RetryOptions } from '../http/retry.ts'\nimport type { HttpTransport } from '../http/transport.ts'\nimport type {\n  AllowedBucket,\n  ApplicationKey,\n  AuthorizeAccountResponse,\n  BucketId,\n  BucketInfo,\n  CancelLargeFileRequest,\n  CancelLargeFileResponse,\n  CopyFileRequest,\n  CopyPartRequest,\n  CopyPartResponse,\n  CreateBucketRequest,\n  CreateKeyRequest,\n  DeleteBucketRequest,\n  DeleteFileVersionRequest,\n  DeleteFileVersionResponse,\n  DeleteKeyRequest,\n  DownloadAuthorizationRequest,\n  DownloadAuthorizationResponse,\n  FileVersion,\n  FinishLargeFileRequest,\n  FullApplicationKey,\n  GetBucketNotificationRulesRequest,\n  GetBucketNotificationRulesResponse,\n  GetFileInfoRequest,\n  GetUploadPartUrlRequest,\n  GetUploadPartUrlResponse,\n  GetUploadUrlRequest,\n  GetUploadUrlResponse,\n  HideFileRequest,\n  ListBucketsRequest,\n  ListBucketsResponse,\n  ListFileNamesRequest,\n  ListFileNamesResponse,\n  ListFileVersionsRequest,\n  ListFileVersionsResponse,\n  ListKeysRequest,\n  ListKeysResponse,\n  ListPartsRequest,\n  ListPartsResponse,\n  ListUnfinishedLargeFilesRequest,\n  ListUnfinishedLargeFilesResponse,\n  SetBucketNotificationRulesRequest,\n  SetBucketNotificationRulesResponse,\n  StartLargeFileRequest,\n  StartLargeFileResponse,\n  UpdateBucketRequest,\n  UpdateFileLegalHoldRequest,\n  UpdateFileLegalHoldResponse,\n  UpdateFileRetentionRequest,\n  UpdateFileRetentionResponse,\n} from '../types/index.ts'\nimport type { UploadFileHeaders, UploadPartHeaders, UploadPartResponse } from '../types/upload.ts'\nimport { normalizeFileVersionListSha1, normalizeFileVersionSha1 } from '../util/normalize.ts'\nimport { buildFileInfoHeaders, encodeFileName } from './encoding.ts'\n\n/** Configuration for constructing a {@link RawClient}. */\nexport interface RawClientOptions {\n  /** The HTTP transport used to send requests (e.g., FetchTransport or RetryTransport). */\n  readonly transport: HttpTransport\n}\n\n/** Optional request controls for {@link RawClient.listFileNames}. */\nexport type ListFileNamesOptions = RawRequestOptions\n\n/** Optional request controls for {@link RawClient.listFileVersions}. */\nexport type ListFileVersionsOptions = RawRequestOptions\n\n/** Optional controls for raw JSON API requests. */\nexport interface RawRequestOptions {\n  /** Abort signal for cancelling the request. */\n  readonly signal?: AbortSignal\n  /** Per-request retry override. */\n  readonly retry?: Partial<RetryOptions>\n}\n\n/**\n * @deprecated Use {@link RawRequestOptions}.\n */\nexport type JsonPostOptions = RawRequestOptions\n\n/** Optional request controls for {@link RawClient.finishLargeFile}. */\nexport type FinishLargeFileOptions = RawRequestOptions\n\n/** Optional request controls for {@link RawClient.copyPart}. */\nexport type CopyPartOptions = RawRequestOptions\n\n/** Optional request controls for {@link RawClient.startLargeFile}. */\nexport type StartLargeFileOptions = RawRequestOptions\n\n/** Optional request controls for {@link RawClient.uploadFile}. */\nexport type UploadFileOptions = RawRequestOptions\n\n/** Optional request controls for {@link RawClient.uploadPart}. */\nexport type UploadPartOptions = RawRequestOptions\n\nfunction normalizeRawRequestOptions(\n  optionsOrSignal?: RawRequestOptions | AbortSignal,\n  retry?: Partial<RetryOptions>,\n): RawRequestOptions | undefined {\n  if (optionsOrSignal === undefined) {\n    return retry === undefined ? undefined : { retry }\n  }\n  if (isAbortSignal(optionsOrSignal)) {\n    return {\n      signal: optionsOrSignal,\n      ...(retry !== undefined ? { retry } : {}),\n    }\n  }\n  return retry === undefined ? optionsOrSignal : { ...optionsOrSignal, retry }\n}\n\nfunction isAbortSignal(value: unknown): value is AbortSignal {\n  // Back-compat only: legacy upload-URL overloads accepted an AbortSignal as\n  // the fourth positional argument. Prefer the RawRequestOptions bag.\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    'aborted' in value &&\n    typeof (value as AbortSignal).addEventListener === 'function'\n  )\n}\n\nfunction normalizeCreateKeyRequest(request: CreateKeyRequest): CreateKeyRequest {\n  const { bucketId, ...withoutDeprecatedBucketId } = request\n  if (bucketId !== undefined && withoutDeprecatedBucketId.bucketIds !== undefined) {\n    throw new TypeError('createKey accepts either bucketIds or deprecated bucketId, not both')\n  }\n  if (bucketId === undefined) {\n    return withoutDeprecatedBucketId\n  }\n  return { ...withoutDeprecatedBucketId, bucketIds: [bucketId] }\n}\n\nfunction singleBucketId(bucketIds: readonly BucketId[] | null): BucketId | null {\n  return bucketIds?.length === 1 ? (bucketIds[0] ?? null) : null\n}\n\nfunction normalizeKeyResponse<T extends { readonly bucketIds: readonly BucketId[] | null }>(\n  key: T,\n): T & { readonly bucketId: BucketId | null } {\n  return { ...key, bucketId: singleBucketId(key.bucketIds) }\n}\n\ntype NormalizedAllowedInfo = AuthorizeAccountResponse['apiInfo']['storageApi']['allowed']\ntype NormalizedStorageApiInfo = AuthorizeAccountResponse['apiInfo']['storageApi']\n\ninterface WireAllowedInfo {\n  readonly capabilities?: NormalizedAllowedInfo['capabilities']\n  readonly buckets?: readonly AllowedBucket[] | null\n  readonly bucketId?: BucketId | null\n  readonly bucketName?: string | null\n  readonly namePrefix?: string | null\n}\n\ntype WireStorageApiInfo = Omit<\n  NormalizedStorageApiInfo,\n  'allowed' | 'bucketId' | 'bucketName' | 'infoType' | 'namePrefix'\n> & {\n  readonly allowed?: WireAllowedInfo\n  readonly capabilities?: NormalizedAllowedInfo['capabilities']\n  readonly bucketId?: BucketId | null\n  readonly bucketName?: string | null\n  readonly infoType?: 'storageApi'\n  readonly namePrefix?: string | null\n}\n\ntype WireAuthorizeAccountResponse = Omit<AuthorizeAccountResponse, 'apiInfo'> & {\n  readonly apiInfo: Omit<AuthorizeAccountResponse['apiInfo'], 'storageApi'> & {\n    readonly storageApi: WireStorageApiInfo\n  }\n}\n\nfunction normalizeAllowedBuckets(storageApi: WireStorageApiInfo): readonly AllowedBucket[] | null {\n  const allowed = storageApi.allowed\n  if (allowed?.buckets !== undefined) {\n    return allowed.buckets === null ? null : allowed.buckets.map((bucket) => ({ ...bucket }))\n  }\n  const bucketId = allowed?.bucketId ?? storageApi.bucketId ?? null\n  if (bucketId === null) return null\n  return [{ id: bucketId, name: allowed?.bucketName ?? storageApi.bucketName ?? null }]\n}\n\nfunction normalizeAuthorizeAccountResponse(\n  response: WireAuthorizeAccountResponse,\n): AuthorizeAccountResponse {\n  const storageApi = response.apiInfo.storageApi\n  const allowed = storageApi.allowed\n  const buckets = normalizeAllowedBuckets(storageApi)\n  const singleBucket = buckets?.length === 1 ? buckets[0] : undefined\n  const bucketId = singleBucket?.id ?? null\n  const bucketName = singleBucket?.name ?? null\n  const namePrefix = allowed?.namePrefix ?? storageApi.namePrefix ?? null\n  const capabilities = allowed?.capabilities ?? storageApi.capabilities ?? []\n  const { allowed: _wireAllowed, capabilities: _legacyCapabilities, ...storageApiBase } = storageApi\n\n  return {\n    ...response,\n    apiInfo: {\n      ...response.apiInfo,\n      storageApi: {\n        ...storageApiBase,\n        bucketId,\n        bucketName,\n        downloadUrl: storageApi.downloadUrl,\n        infoType: 'storageApi',\n        namePrefix,\n        allowed: {\n          ...(allowed ?? {}),\n          capabilities,\n          buckets,\n          bucketId,\n          bucketName,\n          namePrefix,\n        },\n      },\n    },\n  }\n}\n\nfunction uploadResponseBodyError(\n  err: unknown,\n  signal: AbortSignal | undefined,\n): UploadResponseBodyError {\n  if (signal?.aborted === true) {\n    throw signal.reason ?? new DOMException('Aborted', 'AbortError')\n  }\n  const message = err instanceof Error ? err.message : 'Upload response body could not be read'\n  return new UploadResponseBodyError(message, { cause: err })\n}\n\n/**\n * Low-level client providing 1:1 bindings to all B2 native API endpoints.\n *\n * Each method maps directly to a single B2 API call. Most methods accept\n * `(apiUrl, authToken, request)` and return the JSON response. Upload and\n * download methods accept endpoint-specific parameters instead.\n */\nexport class RawClient {\n  /** @internal */\n  private readonly transport: HttpTransport\n\n  /**\n   * Creates a new RawClient with the given transport.\n   * @param options - The constructor configuration.\n   */\n  constructor(options: RawClientOptions) {\n    this.transport = options.transport\n  }\n\n  // --- Auth ---\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-authorize-account | b2_authorize_account}.\n   * @param applicationKeyId - The application key ID for authentication.\n   * @param applicationKey - The application key secret.\n   * @param realmUrl - The B2 realm URL to authenticate against.\n   *\n   * @returns The authorization response with API URLs and credentials.\n   */\n  async authorizeAccount(\n    applicationKeyId: string,\n    applicationKey: string,\n    realmUrl = 'https://api.backblazeb2.com',\n  ): Promise<AuthorizeAccountResponse> {\n    assertSecureRealmUrl(realmUrl)\n    const response = await this.transport.send({\n      url: `${realmUrl}/b2api/v4/b2_authorize_account`,\n      method: 'GET',\n      headers: {\n        Authorization: `Basic ${btoa(`${applicationKeyId}:${applicationKey}`)}`,\n      },\n    })\n    return normalizeAuthorizeAccountResponse(await response.json<WireAuthorizeAccountResponse>())\n  }\n\n  // --- Buckets ---\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-create-bucket | b2_create_bucket}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   *\n   * @returns The created bucket metadata.\n   */\n  async createBucket(\n    apiUrl: string,\n    authToken: string,\n    request: CreateBucketRequest,\n  ): Promise<BucketInfo> {\n    return this.postJson<BucketInfo>(apiUrl, authToken, 'b2_create_bucket', request)\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-delete-bucket | b2_delete_bucket}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   *\n   * @returns The deleted bucket metadata.\n   */\n  async deleteBucket(\n    apiUrl: string,\n    authToken: string,\n    request: DeleteBucketRequest,\n  ): Promise<BucketInfo> {\n    return this.postJson<BucketInfo>(apiUrl, authToken, 'b2_delete_bucket', request)\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-list-buckets | b2_list_buckets}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   *\n   * @returns The list of matching buckets.\n   */\n  async listBuckets(\n    apiUrl: string,\n    authToken: string,\n    request: ListBucketsRequest,\n  ): Promise<ListBucketsResponse> {\n    return this.postJson<ListBucketsResponse>(apiUrl, authToken, 'b2_list_buckets', request)\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-update-bucket | b2_update_bucket}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   *\n   * @returns The updated bucket metadata.\n   */\n  async updateBucket(\n    apiUrl: string,\n    authToken: string,\n    request: UpdateBucketRequest,\n  ): Promise<BucketInfo> {\n    return this.postJson<BucketInfo>(apiUrl, authToken, 'b2_update_bucket', request)\n  }\n\n  // --- Files ---\n\n  /**\n   * Calls `b2_get_upload_url` with legacy positional request controls.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   * @param signal - Optional abort signal for cancellation.\n   * @param retry - Optional per-request retry override.\n   *\n   * @returns The upload URL and authorization token.\n   *\n   * @deprecated Use the options-bag overload: `getUploadUrl(apiUrl, authToken, request, { signal, retry })`.\n   */\n  async getUploadUrl(\n    apiUrl: string,\n    authToken: string,\n    request: GetUploadUrlRequest,\n    signal?: AbortSignal,\n    retry?: Partial<RetryOptions>,\n  ): Promise<GetUploadUrlResponse>\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-get-upload-url | b2_get_upload_url}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   * @param options - Optional request controls such as cancellation and retry overrides.\n   *\n   * @returns The upload URL and authorization token.\n   */\n  async getUploadUrl(\n    apiUrl: string,\n    authToken: string,\n    request: GetUploadUrlRequest,\n    options?: RawRequestOptions,\n  ): Promise<GetUploadUrlResponse>\n  /**\n   * Implementation for both upload URL request-control signatures.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   * @param optionsOrSignal - Options bag or legacy abort signal.\n   * @param retry - Optional legacy per-request retry override.\n   *\n   * @returns The upload URL and authorization token.\n   */\n  async getUploadUrl(\n    apiUrl: string,\n    authToken: string,\n    request: GetUploadUrlRequest,\n    optionsOrSignal?: RawRequestOptions | AbortSignal,\n    retry?: Partial<RetryOptions>,\n  ): Promise<GetUploadUrlResponse> {\n    return this.postJson<GetUploadUrlResponse>(\n      apiUrl,\n      authToken,\n      'b2_get_upload_url',\n      request,\n      normalizeRawRequestOptions(optionsOrSignal, retry),\n    )\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-upload-file | b2_upload_file}.\n   *\n   * Unlike most methods, this posts directly to the `uploadUrl` obtained\n   * from {@link getUploadUrl} rather than the API URL.\n   * @param uploadUrl - The upload endpoint URL.\n   * @param headers - The request headers including authorization and content metadata.\n   * @param body - The file data to upload.\n   * @param signal - Optional legacy abort signal for cancellation.\n   * @param retry - Optional legacy per-request retry override.\n   *\n   * @returns The uploaded file version metadata.\n   *\n   * @deprecated Use the options-bag overload: `uploadFile(uploadUrl, headers, body, { signal, retry })`.\n   */\n  async uploadFile(\n    uploadUrl: string,\n    headers: UploadFileHeaders,\n    body: BodyInit,\n    signal?: AbortSignal,\n    retry?: Partial<RetryOptions>,\n  ): Promise<FileVersion>\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-upload-file | b2_upload_file}.\n   *\n   * Unlike most methods, this posts directly to the `uploadUrl` obtained\n   * from {@link getUploadUrl} rather than the API URL.\n   * @param uploadUrl - The upload endpoint URL.\n   * @param headers - The request headers including authorization and content metadata.\n   * @param body - The file data to upload.\n   * @param options - Optional request controls such as cancellation and retry overrides.\n   *\n   * @returns The uploaded file version metadata.\n   */\n  async uploadFile(\n    uploadUrl: string,\n    headers: UploadFileHeaders,\n    body: BodyInit,\n    options?: UploadFileOptions,\n  ): Promise<FileVersion>\n  /**\n   * Implementation for both upload-file request-control signatures.\n   * @param uploadUrl - The upload endpoint URL.\n   * @param headers - The request headers including authorization and content metadata.\n   * @param body - The file data to upload.\n   * @param optionsOrSignal - Options bag or legacy abort signal.\n   * @param retry - Optional legacy per-request retry override.\n   *\n   * @returns The uploaded file version metadata.\n   */\n  async uploadFile(\n    uploadUrl: string,\n    headers: UploadFileHeaders,\n    body: BodyInit,\n    optionsOrSignal?: UploadFileOptions | AbortSignal,\n    retry?: Partial<RetryOptions>,\n  ): Promise<FileVersion> {\n    const options = normalizeRawRequestOptions(optionsOrSignal, retry)\n    const reqHeaders: Record<string, string> = {\n      Authorization: headers.authorization,\n      'X-Bz-File-Name': encodeFileName(headers.fileName),\n      'Content-Type': headers.contentType,\n      'Content-Length': String(headers.contentLength),\n      'X-Bz-Content-Sha1': headers.contentSha1,\n      ...buildFileInfoHeaders(headers.fileInfo),\n    }\n\n    if (headers.lastModifiedMillis !== undefined) {\n      reqHeaders['X-Bz-Info-src_last_modified_millis'] = String(headers.lastModifiedMillis)\n    }\n    if (headers.contentDisposition) {\n      reqHeaders['X-Bz-Info-b2-content-disposition'] = headers.contentDisposition\n    }\n    if (headers.contentLanguage) {\n      reqHeaders['X-Bz-Info-b2-content-language'] = headers.contentLanguage\n    }\n    if (headers.expires) {\n      reqHeaders['X-Bz-Info-b2-expires'] = headers.expires\n    }\n    if (headers.cacheControl) {\n      reqHeaders['X-Bz-Info-b2-cache-control'] = headers.cacheControl\n    }\n    if (headers.contentEncoding) {\n      reqHeaders['X-Bz-Info-b2-content-encoding'] = headers.contentEncoding\n    }\n\n    applyEncryptionHeaders(reqHeaders, headers.serverSideEncryption)\n    applyRetentionHeaders(reqHeaders, headers.fileRetention)\n    applyLegalHoldHeader(reqHeaders, headers.legalHold)\n\n    const response = await this.transport.send({\n      url: uploadUrl,\n      method: 'POST',\n      headers: reqHeaders,\n      body,\n      ...(options?.signal !== undefined ? { signal: options.signal } : {}),\n      ...(options?.retry !== undefined ? { retry: options.retry } : {}),\n    })\n    try {\n      return normalizeFileVersionSha1(await response.json<FileVersion>())\n    } catch (err) {\n      throw uploadResponseBodyError(err, options?.signal)\n    }\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-list-file-names | b2_list_file_names}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   * @param options - Optional request controls such as an abort signal.\n   *\n   * @returns The list of file names and optional continuation token.\n   */\n  async listFileNames(\n    apiUrl: string,\n    authToken: string,\n    request: ListFileNamesRequest,\n    options?: ListFileNamesOptions,\n  ): Promise<ListFileNamesResponse> {\n    return normalizeFileVersionListSha1(\n      await this.postJson<ListFileNamesResponse>(\n        apiUrl,\n        authToken,\n        'b2_list_file_names',\n        request,\n        options,\n      ),\n    )\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-list-file-versions | b2_list_file_versions}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   * @param options - Optional request controls such as an abort signal.\n   *\n   * @returns The list of file versions and optional continuation token.\n   */\n  async listFileVersions(\n    apiUrl: string,\n    authToken: string,\n    request: ListFileVersionsRequest,\n    options?: ListFileVersionsOptions,\n  ): Promise<ListFileVersionsResponse> {\n    return normalizeFileVersionListSha1(\n      await this.postJson<ListFileVersionsResponse>(\n        apiUrl,\n        authToken,\n        'b2_list_file_versions',\n        request,\n        options,\n      ),\n    )\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-get-file-info | b2_get_file_info}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   *\n   * @returns The file version metadata.\n   */\n  async getFileInfo(\n    apiUrl: string,\n    authToken: string,\n    request: GetFileInfoRequest,\n  ): Promise<FileVersion> {\n    return normalizeFileVersionSha1(\n      await this.postJson<FileVersion>(apiUrl, authToken, 'b2_get_file_info', request),\n    )\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-hide-file | b2_hide_file}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   * @param options - Optional request controls such as an abort signal.\n   *\n   * @returns The hidden file version metadata.\n   */\n  async hideFile(\n    apiUrl: string,\n    authToken: string,\n    request: HideFileRequest,\n    options?: { readonly signal?: AbortSignal },\n  ): Promise<FileVersion> {\n    return normalizeFileVersionSha1(\n      await this.postJson<FileVersion>(apiUrl, authToken, 'b2_hide_file', request, options),\n    )\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-delete-file-version | b2_delete_file_version}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   * @param options - Optional request controls such as an abort signal.\n   *\n   * @returns The deleted file version identifier.\n   */\n  async deleteFileVersion(\n    apiUrl: string,\n    authToken: string,\n    request: DeleteFileVersionRequest,\n    options?: { readonly signal?: AbortSignal },\n  ): Promise<DeleteFileVersionResponse> {\n    return this.postJson<DeleteFileVersionResponse>(\n      apiUrl,\n      authToken,\n      'b2_delete_file_version',\n      request,\n      options,\n    )\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-copy-file | b2_copy_file}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   * @param options - Optional request controls such as an abort signal.\n   *\n   * @returns The copied file version metadata.\n   */\n  async copyFile(\n    apiUrl: string,\n    authToken: string,\n    request: CopyFileRequest,\n    options?: RawRequestOptions,\n  ): Promise<FileVersion> {\n    return normalizeFileVersionSha1(\n      await this.postJson<FileVersion>(apiUrl, authToken, 'b2_copy_file', request, options),\n    )\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-copy-part | b2_copy_part}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   * @param options - Optional abort and retry controls.\n   *\n   * @returns The copied part metadata.\n   */\n  async copyPart(\n    apiUrl: string,\n    authToken: string,\n    request: CopyPartRequest,\n    options?: CopyPartOptions,\n  ): Promise<CopyPartResponse> {\n    return this.postJson<CopyPartResponse>(apiUrl, authToken, 'b2_copy_part', request, options)\n  }\n\n  // --- Large Files ---\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-start-large-file | b2_start_large_file}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   * @param options - Optional abort and retry controls.\n   *\n   * @returns The started large file metadata with file ID.\n   */\n  async startLargeFile(\n    apiUrl: string,\n    authToken: string,\n    request: StartLargeFileRequest,\n    options?: StartLargeFileOptions,\n  ): Promise<StartLargeFileResponse> {\n    return this.postJson<StartLargeFileResponse>(\n      apiUrl,\n      authToken,\n      'b2_start_large_file',\n      request,\n      options,\n    )\n  }\n\n  /**\n   * Calls `b2_get_upload_part_url` with legacy positional request controls.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   * @param signal - Optional abort signal for cancellation.\n   * @param retry - Optional per-request retry override.\n   *\n   * @returns The upload part URL and authorization token.\n   *\n   * @deprecated Use the options-bag overload: `getUploadPartUrl(apiUrl, authToken, request, { signal, retry })`.\n   */\n  async getUploadPartUrl(\n    apiUrl: string,\n    authToken: string,\n    request: GetUploadPartUrlRequest,\n    signal?: AbortSignal,\n    retry?: Partial<RetryOptions>,\n  ): Promise<GetUploadPartUrlResponse>\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-get-upload-part-url | b2_get_upload_part_url}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   * @param options - Optional request controls such as cancellation and retry overrides.\n   *\n   * @returns The upload part URL and authorization token.\n   */\n  async getUploadPartUrl(\n    apiUrl: string,\n    authToken: string,\n    request: GetUploadPartUrlRequest,\n    options?: RawRequestOptions,\n  ): Promise<GetUploadPartUrlResponse>\n  /**\n   * Implementation for both upload part URL request-control signatures.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   * @param optionsOrSignal - Options bag or legacy abort signal.\n   * @param retry - Optional legacy per-request retry override.\n   *\n   * @returns The upload part URL and authorization token.\n   */\n  async getUploadPartUrl(\n    apiUrl: string,\n    authToken: string,\n    request: GetUploadPartUrlRequest,\n    optionsOrSignal?: RawRequestOptions | AbortSignal,\n    retry?: Partial<RetryOptions>,\n  ): Promise<GetUploadPartUrlResponse> {\n    return this.postJson<GetUploadPartUrlResponse>(\n      apiUrl,\n      authToken,\n      'b2_get_upload_part_url',\n      request,\n      normalizeRawRequestOptions(optionsOrSignal, retry),\n    )\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-upload-part | b2_upload_part}.\n   *\n   * Posts directly to the `uploadUrl` obtained from {@link getUploadPartUrl}\n   * rather than the API URL.\n   * @param uploadUrl - The upload endpoint URL.\n   * @param headers - The request headers including authorization and content metadata.\n   * @param body - The file data to upload.\n   * @param signal - Optional legacy abort signal for cancellation.\n   * @param retry - Optional legacy per-request retry override.\n   *\n   * @returns The uploaded part metadata.\n   *\n   * @deprecated Use the options-bag overload: `uploadPart(uploadUrl, headers, body, { signal, retry })`.\n   */\n  async uploadPart(\n    uploadUrl: string,\n    headers: UploadPartHeaders,\n    body: BodyInit,\n    signal?: AbortSignal,\n    retry?: Partial<RetryOptions>,\n  ): Promise<UploadPartResponse>\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-upload-part | b2_upload_part}.\n   *\n   * Posts directly to the `uploadUrl` obtained from {@link getUploadPartUrl}\n   * rather than the API URL.\n   * @param uploadUrl - The upload endpoint URL.\n   * @param headers - The request headers including authorization and content metadata.\n   * @param body - The file data to upload.\n   * @param options - Optional request controls such as cancellation and retry overrides.\n   *\n   * @returns The uploaded part metadata.\n   */\n  async uploadPart(\n    uploadUrl: string,\n    headers: UploadPartHeaders,\n    body: BodyInit,\n    options?: UploadPartOptions,\n  ): Promise<UploadPartResponse>\n  /**\n   * Implementation for both upload-part request-control signatures.\n   * @param uploadUrl - The upload endpoint URL.\n   * @param headers - The request headers including authorization and content metadata.\n   * @param body - The file data to upload.\n   * @param optionsOrSignal - Options bag or legacy abort signal.\n   * @param retry - Optional legacy per-request retry override.\n   *\n   * @returns The uploaded part metadata.\n   */\n  async uploadPart(\n    uploadUrl: string,\n    headers: UploadPartHeaders,\n    body: BodyInit,\n    optionsOrSignal?: UploadPartOptions | AbortSignal,\n    retry?: Partial<RetryOptions>,\n  ): Promise<UploadPartResponse> {\n    const options = normalizeRawRequestOptions(optionsOrSignal, retry)\n    const reqHeaders: Record<string, string> = {\n      Authorization: headers.authorization,\n      'X-Bz-Part-Number': String(headers.partNumber),\n      'Content-Length': String(headers.contentLength),\n      'X-Bz-Content-Sha1': headers.contentSha1,\n    }\n\n    applyEncryptionHeaders(reqHeaders, headers.serverSideEncryption)\n\n    const response = await this.transport.send({\n      url: uploadUrl,\n      method: 'POST',\n      headers: reqHeaders,\n      body,\n      ...(options?.signal !== undefined ? { signal: options.signal } : {}),\n      ...(options?.retry !== undefined ? { retry: options.retry } : {}),\n    })\n    try {\n      return await response.json<UploadPartResponse>()\n    } catch (err) {\n      throw uploadResponseBodyError(err, options?.signal)\n    }\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-finish-large-file | b2_finish_large_file}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   * @param options - Optional abort and retry controls.\n   *\n   * @returns The completed file version metadata.\n   */\n  async finishLargeFile(\n    apiUrl: string,\n    authToken: string,\n    request: FinishLargeFileRequest,\n    options?: FinishLargeFileOptions,\n  ): Promise<FileVersion> {\n    const response = await this.transport.send({\n      url: `${apiUrl}/b2api/v3/b2_finish_large_file`,\n      method: 'POST',\n      headers: {\n        Authorization: authToken,\n        'Content-Type': 'application/json',\n      },\n      body: JSON.stringify(request),\n      ...(options?.signal !== undefined ? { signal: options.signal } : {}),\n      ...(options?.retry !== undefined ? { retry: options.retry } : {}),\n    })\n\n    let fileVersion: FileVersion\n    try {\n      fileVersion = await response.json<FileVersion>()\n    } catch (err) {\n      throw new FinishLargeFileResponseBodyError(\n        err instanceof Error ? err.message : 'Finish large file response body could not be read',\n        { cause: err, fileId: request.fileId },\n      )\n    }\n    return normalizeFileVersionSha1(fileVersion)\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-cancel-large-file | b2_cancel_large_file}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   * @param options - Optional request controls such as cancellation and retry overrides.\n   *\n   * @returns The cancelled large file metadata.\n   */\n  async cancelLargeFile(\n    apiUrl: string,\n    authToken: string,\n    request: CancelLargeFileRequest,\n    options?: RawRequestOptions,\n  ): Promise<CancelLargeFileResponse> {\n    return this.postJson<CancelLargeFileResponse>(\n      apiUrl,\n      authToken,\n      'b2_cancel_large_file',\n      request,\n      options,\n    )\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-list-unfinished-large-files | b2_list_unfinished_large_files}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   * @param options - Optional request controls such as cancellation and retry.\n   *\n   * @returns The list of unfinished large files and optional continuation token.\n   */\n  async listUnfinishedLargeFiles(\n    apiUrl: string,\n    authToken: string,\n    request: ListUnfinishedLargeFilesRequest,\n    options?: RawRequestOptions,\n  ): Promise<ListUnfinishedLargeFilesResponse> {\n    return this.postJson<ListUnfinishedLargeFilesResponse>(\n      apiUrl,\n      authToken,\n      'b2_list_unfinished_large_files',\n      request,\n      options,\n    )\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-list-parts | b2_list_parts}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   * @param options - Optional request controls such as cancellation and retry.\n   *\n   * @returns The list of uploaded parts and optional continuation token.\n   */\n  async listParts(\n    apiUrl: string,\n    authToken: string,\n    request: ListPartsRequest,\n    options?: RawRequestOptions,\n  ): Promise<ListPartsResponse> {\n    return this.postJson<ListPartsResponse>(apiUrl, authToken, 'b2_list_parts', request, options)\n  }\n\n  // --- Downloads ---\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-download-file-by-id | b2_download_file_by_id}.\n   * @param downloadUrl - The B2 download base URL.\n   * @param authToken - The authorization token.\n   * @param fileId - The unique identifier of the file to download.\n   * @param options - Optional download parameters for range requests and cancellation.\n   *\n   * @returns The response headers, streaming body, and HTTP status code.\n   */\n  async downloadFileById(\n    downloadUrl: string,\n    authToken: string,\n    fileId: string,\n    options?: DownloadFileOptions,\n  ): Promise<{\n    /** Response headers containing file metadata and B2 info headers. */\n    headers: Headers\n    /** Streaming response body, or `null` for HEAD-like responses. */\n    body: ReadableStream<Uint8Array> | null\n    /** HTTP status code (200 for full content, 206 for partial content). */\n    status: number\n  }> {\n    const headers = buildDownloadRequestHeaders(authToken, options)\n    const url = appendDownloadOverrides(\n      `${downloadUrl}/b2api/v3/b2_download_file_by_id?fileId=${encodeURIComponent(fileId)}`,\n      options,\n    )\n\n    const response = await this.transport.send({\n      url,\n      method: options?.method ?? 'GET',\n      headers,\n      ...(options?.signal !== undefined ? { signal: options.signal } : {}),\n    })\n\n    return { headers: response.headers, body: response.body, status: response.status }\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-download-file-by-name | b2_download_file_by_name}.\n   * @param downloadUrl - The B2 download base URL.\n   * @param authToken - The authorization token.\n   * @param bucketName - The name of the bucket containing the file.\n   * @param fileName - The name of the file to download.\n   * @param options - Optional download parameters for range requests and cancellation.\n   *\n   * @returns The response headers, streaming body, and HTTP status code.\n   */\n  async downloadFileByName(\n    downloadUrl: string,\n    authToken: string,\n    bucketName: string,\n    fileName: string,\n    options?: DownloadFileOptions,\n  ): Promise<{\n    /** Response headers containing file metadata and B2 info headers. */\n    headers: Headers\n    /** Streaming response body, or `null` for HEAD-like responses. */\n    body: ReadableStream<Uint8Array> | null\n    /** HTTP status code (200 for full content, 206 for partial content). */\n    status: number\n  }> {\n    const headers = buildDownloadRequestHeaders(authToken, options)\n    const url = appendDownloadOverrides(\n      `${downloadUrl}/file/${encodeURIComponent(bucketName)}/${encodeFileName(fileName)}`,\n      options,\n    )\n\n    const response = await this.transport.send({\n      url,\n      method: options?.method ?? 'GET',\n      headers,\n      ...(options?.signal !== undefined ? { signal: options.signal } : {}),\n    })\n\n    return { headers: response.headers, body: response.body, status: response.status }\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-get-download-authorization | b2_get_download_authorization}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The current session authorization token.\n   * @param request - The API request parameters.\n   *\n   * @returns The download authorization token for the specified file prefix.\n   */\n  async getDownloadAuthorization(\n    apiUrl: string,\n    authToken: string,\n    request: DownloadAuthorizationRequest,\n  ): Promise<DownloadAuthorizationResponse> {\n    return this.postJson<DownloadAuthorizationResponse>(\n      apiUrl,\n      authToken,\n      'b2_get_download_authorization',\n      request,\n    )\n  }\n\n  // --- Keys ---\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-create-key | b2_create_key}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   *\n   * @returns The newly created application key with secret.\n   */\n  async createKey(\n    apiUrl: string,\n    authToken: string,\n    request: CreateKeyRequest,\n  ): Promise<FullApplicationKey> {\n    const key = await this.postJson<FullApplicationKey>(\n      apiUrl,\n      authToken,\n      'b2_create_key',\n      normalizeCreateKeyRequest(request),\n      undefined,\n      'v4',\n    )\n    return normalizeKeyResponse(key)\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-list-keys | b2_list_keys}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   *\n   * @returns The list of application keys and optional continuation token.\n   */\n  async listKeys(\n    apiUrl: string,\n    authToken: string,\n    request: ListKeysRequest,\n  ): Promise<ListKeysResponse> {\n    const response = await this.postJson<ListKeysResponse>(\n      apiUrl,\n      authToken,\n      'b2_list_keys',\n      request,\n      undefined,\n      'v4',\n    )\n    return { ...response, keys: response.keys.map((key) => normalizeKeyResponse(key)) }\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-delete-key | b2_delete_key}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   *\n   * @returns The deleted application key metadata.\n   */\n  async deleteKey(\n    apiUrl: string,\n    authToken: string,\n    request: DeleteKeyRequest,\n  ): Promise<ApplicationKey> {\n    const key = await this.postJson<ApplicationKey>(\n      apiUrl,\n      authToken,\n      'b2_delete_key',\n      request,\n      undefined,\n      'v4',\n    )\n    return normalizeKeyResponse(key)\n  }\n\n  // --- Retention / Legal Hold ---\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-update-file-retention | b2_update_file_retention}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   *\n   * @returns The updated file retention settings.\n   */\n  async updateFileRetention(\n    apiUrl: string,\n    authToken: string,\n    request: UpdateFileRetentionRequest,\n  ): Promise<UpdateFileRetentionResponse> {\n    return this.postJson<UpdateFileRetentionResponse>(\n      apiUrl,\n      authToken,\n      'b2_update_file_retention',\n      request,\n    )\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-update-file-legal-hold | b2_update_file_legal_hold}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   *\n   * @returns The updated file legal hold status.\n   */\n  async updateFileLegalHold(\n    apiUrl: string,\n    authToken: string,\n    request: UpdateFileLegalHoldRequest,\n  ): Promise<UpdateFileLegalHoldResponse> {\n    return this.postJson<UpdateFileLegalHoldResponse>(\n      apiUrl,\n      authToken,\n      'b2_update_file_legal_hold',\n      request,\n    )\n  }\n\n  // --- Notifications ---\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-get-bucket-notification-rules | b2_get_bucket_notification_rules}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   *\n   * @returns The configured event notification rules for the specified bucket.\n   */\n  async getBucketNotificationRules(\n    apiUrl: string,\n    authToken: string,\n    request: GetBucketNotificationRulesRequest,\n  ): Promise<GetBucketNotificationRulesResponse> {\n    return this.postJson<GetBucketNotificationRulesResponse>(\n      apiUrl,\n      authToken,\n      'b2_get_bucket_notification_rules',\n      request,\n    )\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-set-bucket-notification-rules | b2_set_bucket_notification_rules}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   *\n   * @returns The updated bucket notification rules.\n   */\n  async setBucketNotificationRules(\n    apiUrl: string,\n    authToken: string,\n    request: SetBucketNotificationRulesRequest,\n  ): Promise<SetBucketNotificationRulesResponse> {\n    return this.postJson<SetBucketNotificationRulesResponse>(\n      apiUrl,\n      authToken,\n      'b2_set_bucket_notification_rules',\n      request,\n    )\n  }\n\n  // --- Internal ---\n\n  /**\n   * Sends a JSON POST request to the specified B2 API endpoint.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param endpoint - The B2 API endpoint name.\n   * @param body - The JSON request body.\n   * @param options - Optional abort and per-request retry settings.\n   * @param apiVersion - B2 Native API version segment for this endpoint.\n   *\n   * @returns The parsed JSON response.\n   */\n  private async postJson<T>(\n    apiUrl: string,\n    authToken: string,\n    endpoint: string,\n    body: unknown,\n    options?: RawRequestOptions,\n    apiVersion: 'v3' | 'v4' = 'v3',\n  ): Promise<T> {\n    const response = await this.transport.send({\n      url: `${apiUrl}/b2api/${apiVersion}/${endpoint}`,\n      method: 'POST',\n      headers: {\n        Authorization: authToken,\n        'Content-Type': 'application/json',\n      },\n      body: JSON.stringify(body),\n      ...(options?.signal !== undefined ? { signal: options.signal } : {}),\n      ...(options?.retry !== undefined ? { retry: options.retry } : {}),\n    })\n    return response.json<T>()\n  }\n}\n\n// --- Header helpers ---\n\nimport { EncryptionAlgorithm, EncryptionMode, type EncryptionSetting } from '../types/encryption.ts'\nimport type { FileRetentionValue, LegalHoldValue } from '../types/lock.ts'\n\n/**\n * Applies server-side encryption headers to the request.\n * @param headers - The mutable headers object to populate.\n * @param encryption - The encryption settings, or undefined to skip.\n */\nfunction applyEncryptionHeaders(\n  headers: Record<string, string>,\n  encryption: EncryptionSetting | undefined,\n): void {\n  if (!encryption || encryption.mode === EncryptionMode.None) return\n  if (encryption.mode === EncryptionMode.SseB2) {\n    headers['X-Bz-Server-Side-Encryption'] = EncryptionAlgorithm.Aes256\n  } else if (encryption.mode === EncryptionMode.SseC) {\n    headers['X-Bz-Server-Side-Encryption-Customer-Algorithm'] = EncryptionAlgorithm.Aes256\n    headers['X-Bz-Server-Side-Encryption-Customer-Key'] = encryption.customerKey\n    headers['X-Bz-Server-Side-Encryption-Customer-Key-Md5'] = encryption.customerKeyMd5\n  }\n}\n\n/**\n * SSE-C decryption parameters supplied to downloads of files that were\n * uploaded with customer-managed keys.\n */\nexport interface SseCDownloadKey {\n  /** Encryption algorithm. Always `EncryptionAlgorithm.Aes256` (`'AES256'`). */\n  readonly algorithm: EncryptionAlgorithm\n  /** Base64-encoded customer-provided decryption key. */\n  readonly customerKey: string\n  /** Base64-encoded MD5 digest of the decryption key. */\n  readonly customerKeyMd5: string\n}\n\n/**\n * Options accepted by {@link RawClient.downloadFileById} and\n * {@link RawClient.downloadFileByName}. Mirrors the B2 native API: range +\n * SSE-C decryption headers + the documented `b2Content*` response-header\n * overrides (query-string parameters on the request URL).\n */\nexport interface DownloadFileOptions {\n  /** HTTP method. Defaults to `'GET'`. Use `'HEAD'` to fetch headers without the body. */\n  readonly method?: 'GET' | 'HEAD'\n  /** HTTP Range header value for partial content requests. */\n  readonly range?: string\n  /** SSE-C decryption parameters, required if the file was uploaded with SSE-C. */\n  readonly serverSideEncryption?: SseCDownloadKey\n  /** Override the `Content-Disposition` header in the download response. */\n  readonly b2ContentDisposition?: string\n  /** Override the `Content-Language` header in the download response. */\n  readonly b2ContentLanguage?: string\n  /** Override the `Content-Encoding` header in the download response. */\n  readonly b2ContentEncoding?: string\n  /** Override the `Content-Type` header in the download response. */\n  readonly b2ContentType?: string\n  /** Override the `Cache-Control` header in the download response. */\n  readonly b2CacheControl?: string\n  /** Override the `Expires` header in the download response. */\n  readonly b2Expires?: string\n  /** Signal to abort the download. */\n  readonly signal?: AbortSignal\n}\n\nconst DOWNLOAD_OVERRIDE_PARAMS = [\n  'b2ContentDisposition',\n  'b2ContentLanguage',\n  'b2ContentEncoding',\n  'b2ContentType',\n  'b2CacheControl',\n  'b2Expires',\n] as const\n\n/**\n * Builds the HTTP request headers for a download: Authorization, optional\n * Range, and optional SSE-C decryption headers.\n *\n * @param authToken - The B2 session authorization token.\n * @param options - Caller-supplied download options.\n *\n * @returns The header map to send with the request.\n */\nfunction buildDownloadRequestHeaders(\n  authToken: string,\n  options: DownloadFileOptions | undefined,\n): Record<string, string> {\n  const headers: Record<string, string> = { Authorization: authToken }\n  if (options?.range) headers['Range'] = options.range\n  if (options?.serverSideEncryption) {\n    applyEncryptionHeaders(headers, {\n      mode: EncryptionMode.SseC,\n      ...options.serverSideEncryption,\n    })\n  }\n  return headers\n}\n\n/**\n * Appends the documented `b2Content*` response-header overrides to a download\n * URL as query-string parameters. B2 echoes the values into the response\n * headers so callers can control content type, disposition, and caching.\n *\n * @param url - The base download URL.\n * @param options - Caller-supplied download options.\n *\n * @returns The URL with any override parameters appended.\n */\nfunction appendDownloadOverrides(url: string, options: DownloadFileOptions | undefined): string {\n  if (!options) return url\n  const params: string[] = []\n  for (const key of DOWNLOAD_OVERRIDE_PARAMS) {\n    const value = options[key]\n    if (value !== undefined) {\n      params.push(`${key}=${encodeURIComponent(value)}`)\n    }\n  }\n  if (params.length === 0) return url\n  const separator = url.includes('?') ? '&' : '?'\n  return `${url}${separator}${params.join('&')}`\n}\n\n/**\n * Applies file retention headers to the request.\n * @param headers - The mutable headers object to populate.\n * @param retention - The retention settings, or undefined to skip.\n */\nfunction applyRetentionHeaders(\n  headers: Record<string, string>,\n  retention: FileRetentionValue | undefined,\n): void {\n  if (!retention) return\n  if (retention.mode) {\n    headers['X-Bz-File-Retention-Mode'] = retention.mode\n  }\n  if (retention.retainUntilTimestamp) {\n    headers['X-Bz-File-Retention-Retain-Until-Timestamp'] = String(retention.retainUntilTimestamp)\n  }\n}\n\n/**\n * Applies the legal hold header to the request.\n * @param headers - The mutable headers object to populate.\n * @param legalHold - The legal hold value, or undefined to skip.\n */\nfunction applyLegalHoldHeader(\n  headers: Record<string, string>,\n  legalHold: LegalHoldValue | undefined,\n): void {\n  if (!legalHold) return\n  headers['X-Bz-File-Legal-Hold'] = legalHold\n}\n\nexport {\n  buildFileInfoHeaders,\n  decodeFileName,\n  encodeFileName,\n  parseFileInfoHeaders,\n} from './encoding.ts'\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/raw/index.ts"],"sourcesContent":["/**\n * Low-level 1:1 bindings for every B2 native API endpoint.\n *\n * Each method on {@link RawClient} maps directly to a single `b2_*` HTTP call\n * with fully typed request and response objects. No retry logic, no URL pooling,\n * no automatic reauthorization. Use this when you need precise control over\n * individual API calls; for most use cases prefer the high-level `B2Client`.\n *\n * @packageDocumentation\n */\n\nimport { assertSecureRealmUrl } from '../auth/realms.ts'\nimport { FinishLargeFileResponseBodyError, UploadResponseBodyError } from '../errors/index.ts'\nimport type { RetryOptions } from '../http/retry.ts'\nimport type { HttpTransport } from '../http/transport.ts'\nimport type {\n  AllowedBucket,\n  ApplicationKey,\n  AuthorizeAccountResponse,\n  BucketId,\n  BucketInfo,\n  CancelLargeFileRequest,\n  CancelLargeFileResponse,\n  CopyFileRequest,\n  CopyPartRequest,\n  CopyPartResponse,\n  CreateBucketRequest,\n  CreateKeyRequest,\n  DeleteBucketRequest,\n  DeleteFileVersionRequest,\n  DeleteFileVersionResponse,\n  DeleteKeyRequest,\n  DownloadAuthorizationRequest,\n  DownloadAuthorizationResponse,\n  FileVersion,\n  FinishLargeFileRequest,\n  FullApplicationKey,\n  GetBucketNotificationRulesRequest,\n  GetBucketNotificationRulesResponse,\n  GetFileInfoRequest,\n  GetUploadPartUrlRequest,\n  GetUploadPartUrlResponse,\n  GetUploadUrlRequest,\n  GetUploadUrlResponse,\n  HideFileRequest,\n  ListBucketsRequest,\n  ListBucketsResponse,\n  ListFileNamesRequest,\n  ListFileNamesResponse,\n  ListFileVersionsRequest,\n  ListFileVersionsResponse,\n  ListKeysRequest,\n  ListKeysResponse,\n  ListPartsRequest,\n  ListPartsResponse,\n  ListUnfinishedLargeFilesRequest,\n  ListUnfinishedLargeFilesResponse,\n  SetBucketNotificationRulesRequest,\n  SetBucketNotificationRulesResponse,\n  StartLargeFileRequest,\n  StartLargeFileResponse,\n  UpdateBucketRequest,\n  UpdateFileLegalHoldRequest,\n  UpdateFileLegalHoldResponse,\n  UpdateFileRetentionRequest,\n  UpdateFileRetentionResponse,\n} from '../types/index.ts'\nimport type { UploadFileHeaders, UploadPartHeaders, UploadPartResponse } from '../types/upload.ts'\nimport { normalizeFileVersionListSha1, normalizeFileVersionSha1 } from '../util/normalize.ts'\nimport { buildFileInfoHeaders, encodeFileName } from './encoding.ts'\nimport { type B2EndpointUrlOptions, b2Url } from './url.ts'\n\nconst B2_NATIVE_API_V3: B2EndpointUrlOptions = { prefix: 'b2api', version: 'v3' }\nconst B2_NATIVE_API_V4: B2EndpointUrlOptions = { prefix: 'b2api', version: 'v4' }\n\n/** Configuration for constructing a {@link RawClient}. */\nexport interface RawClientOptions {\n  /** The HTTP transport used to send requests (e.g., FetchTransport or RetryTransport). */\n  readonly transport: HttpTransport\n}\n\n/** Optional request controls for {@link RawClient.listFileNames}. */\nexport type ListFileNamesOptions = RawRequestOptions\n\n/** Optional request controls for {@link RawClient.listFileVersions}. */\nexport type ListFileVersionsOptions = RawRequestOptions\n\n/** Optional controls for raw JSON API requests. */\nexport interface RawRequestOptions {\n  /** Abort signal for cancelling the request. */\n  readonly signal?: AbortSignal\n  /** Per-request retry override. */\n  readonly retry?: Partial<RetryOptions>\n}\n\n/**\n * @deprecated Use {@link RawRequestOptions}.\n */\nexport type JsonPostOptions = RawRequestOptions\n\n/** Optional request controls for {@link RawClient.finishLargeFile}. */\nexport type FinishLargeFileOptions = RawRequestOptions\n\n/** Optional request controls for {@link RawClient.copyPart}. */\nexport type CopyPartOptions = RawRequestOptions\n\n/** Optional request controls for {@link RawClient.startLargeFile}. */\nexport type StartLargeFileOptions = RawRequestOptions\n\n/** Optional request controls for {@link RawClient.uploadFile}. */\nexport type UploadFileOptions = RawRequestOptions\n\n/** Optional request controls for {@link RawClient.uploadPart}. */\nexport type UploadPartOptions = RawRequestOptions\n\nfunction normalizeRawRequestOptions(\n  optionsOrSignal?: RawRequestOptions | AbortSignal,\n  retry?: Partial<RetryOptions>,\n): RawRequestOptions | undefined {\n  if (optionsOrSignal === undefined) {\n    return retry === undefined ? undefined : { retry }\n  }\n  if (isAbortSignal(optionsOrSignal)) {\n    return {\n      signal: optionsOrSignal,\n      ...(retry !== undefined ? { retry } : {}),\n    }\n  }\n  return retry === undefined ? optionsOrSignal : { ...optionsOrSignal, retry }\n}\n\nfunction isAbortSignal(value: unknown): value is AbortSignal {\n  // Back-compat only: legacy upload-URL overloads accepted an AbortSignal as\n  // the fourth positional argument. Prefer the RawRequestOptions bag.\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    'aborted' in value &&\n    typeof (value as AbortSignal).addEventListener === 'function'\n  )\n}\n\nfunction assertCustomUploadTimestamp(value: unknown): asserts value is number {\n  if (value === undefined) return\n  if (typeof value === 'number' && Number.isSafeInteger(value) && value >= 0) return\n  throw new TypeError('customUploadTimestamp must be a non-negative safe integer')\n}\n\nfunction assertRawCustomUploadTimestamp(\n  value: unknown,\n): asserts value is string | null | undefined {\n  if (value === undefined || value === null) return\n  if (typeof value === 'string' && /^\\d+$/.test(value)) {\n    const timestamp = Number(value)\n    if (Number.isSafeInteger(timestamp)) return\n  }\n  throw new TypeError('customUploadTimestamp must be a non-negative safe integer string or null')\n}\n\nfunction normalizeCreateKeyRequest(request: CreateKeyRequest): CreateKeyRequest {\n  const { bucketId, ...withoutDeprecatedBucketId } = request\n  if (bucketId !== undefined && withoutDeprecatedBucketId.bucketIds !== undefined) {\n    throw new TypeError('createKey accepts either bucketIds or deprecated bucketId, not both')\n  }\n  if (bucketId === undefined) {\n    return withoutDeprecatedBucketId\n  }\n  return { ...withoutDeprecatedBucketId, bucketIds: [bucketId] }\n}\n\nfunction singleBucketId(bucketIds: readonly BucketId[] | null): BucketId | null {\n  return bucketIds?.length === 1 ? (bucketIds[0] ?? null) : null\n}\n\nfunction normalizeKeyResponse<T extends { readonly bucketIds: readonly BucketId[] | null }>(\n  key: T,\n): T & { readonly bucketId: BucketId | null } {\n  return { ...key, bucketId: singleBucketId(key.bucketIds) }\n}\n\ntype NormalizedAllowedInfo = AuthorizeAccountResponse['apiInfo']['storageApi']['allowed']\ntype NormalizedStorageApiInfo = AuthorizeAccountResponse['apiInfo']['storageApi']\n\ninterface WireAllowedInfo {\n  readonly capabilities?: NormalizedAllowedInfo['capabilities']\n  readonly buckets?: readonly AllowedBucket[] | null\n  readonly bucketId?: BucketId | null\n  readonly bucketName?: string | null\n  readonly namePrefix?: string | null\n}\n\ntype WireStorageApiInfo = Omit<\n  NormalizedStorageApiInfo,\n  'allowed' | 'bucketId' | 'bucketName' | 'infoType' | 'namePrefix'\n> & {\n  readonly allowed?: WireAllowedInfo\n  readonly capabilities?: NormalizedAllowedInfo['capabilities']\n  readonly bucketId?: BucketId | null\n  readonly bucketName?: string | null\n  readonly infoType?: 'storageApi'\n  readonly namePrefix?: string | null\n}\n\ntype WireAuthorizeAccountResponse = Omit<AuthorizeAccountResponse, 'apiInfo'> & {\n  readonly apiInfo: Omit<AuthorizeAccountResponse['apiInfo'], 'storageApi'> & {\n    readonly storageApi: WireStorageApiInfo\n  }\n}\n\nfunction normalizeAllowedBuckets(storageApi: WireStorageApiInfo): readonly AllowedBucket[] | null {\n  const allowed = storageApi.allowed\n  if (allowed?.buckets !== undefined) {\n    return allowed.buckets === null ? null : allowed.buckets.map((bucket) => ({ ...bucket }))\n  }\n  const bucketId = allowed?.bucketId ?? storageApi.bucketId ?? null\n  if (bucketId === null) return null\n  return [{ id: bucketId, name: allowed?.bucketName ?? storageApi.bucketName ?? null }]\n}\n\nfunction normalizeAuthorizeAccountResponse(\n  response: WireAuthorizeAccountResponse,\n): AuthorizeAccountResponse {\n  const storageApi = response.apiInfo.storageApi\n  const allowed = storageApi.allowed\n  const buckets = normalizeAllowedBuckets(storageApi)\n  const singleBucket = buckets?.length === 1 ? buckets[0] : undefined\n  const bucketId = singleBucket?.id ?? null\n  const bucketName = singleBucket?.name ?? null\n  const namePrefix = allowed?.namePrefix ?? storageApi.namePrefix ?? null\n  const capabilities = allowed?.capabilities ?? storageApi.capabilities ?? []\n  const { allowed: _wireAllowed, capabilities: _legacyCapabilities, ...storageApiBase } = storageApi\n\n  return {\n    ...response,\n    apiInfo: {\n      ...response.apiInfo,\n      storageApi: {\n        ...storageApiBase,\n        bucketId,\n        bucketName,\n        downloadUrl: storageApi.downloadUrl,\n        infoType: 'storageApi',\n        namePrefix,\n        allowed: {\n          ...(allowed ?? {}),\n          capabilities,\n          buckets,\n          bucketId,\n          bucketName,\n          namePrefix,\n        },\n      },\n    },\n  }\n}\n\nfunction uploadResponseBodyError(\n  err: unknown,\n  signal: AbortSignal | undefined,\n): UploadResponseBodyError {\n  if (signal?.aborted === true) {\n    throw signal.reason ?? new DOMException('Aborted', 'AbortError')\n  }\n  const message = err instanceof Error ? err.message : 'Upload response body could not be read'\n  return new UploadResponseBodyError(message, { cause: err })\n}\n\n/**\n * Low-level client providing 1:1 bindings to all B2 native API endpoints.\n *\n * Each method maps directly to a single B2 API call. Most methods accept\n * `(apiUrl, authToken, request)` and return the JSON response. Upload and\n * download methods accept endpoint-specific parameters instead.\n */\nexport class RawClient {\n  /** @internal */\n  private readonly transport: HttpTransport\n\n  /**\n   * Creates a new RawClient with the given transport.\n   * @param options - The constructor configuration.\n   */\n  constructor(options: RawClientOptions) {\n    this.transport = options.transport\n  }\n\n  // --- Auth ---\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-authorize-account | b2_authorize_account}.\n   * @param applicationKeyId - The application key ID for authentication.\n   * @param applicationKey - The application key secret.\n   * @param realmUrl - The B2 realm URL to authenticate against.\n   *\n   * @returns The authorization response with API URLs and credentials.\n   */\n  async authorizeAccount(\n    applicationKeyId: string,\n    applicationKey: string,\n    realmUrl = 'https://api.backblazeb2.com',\n  ): Promise<AuthorizeAccountResponse> {\n    assertSecureRealmUrl(realmUrl)\n    const response = await this.transport.send({\n      url: b2Url(realmUrl, { ...B2_NATIVE_API_V4, endpoint: 'b2_authorize_account' }),\n      method: 'GET',\n      headers: {\n        Authorization: `Basic ${btoa(`${applicationKeyId}:${applicationKey}`)}`,\n      },\n    })\n    return normalizeAuthorizeAccountResponse(await response.json<WireAuthorizeAccountResponse>())\n  }\n\n  // --- Buckets ---\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-create-bucket | b2_create_bucket}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   *\n   * @returns The created bucket metadata.\n   */\n  async createBucket(\n    apiUrl: string,\n    authToken: string,\n    request: CreateBucketRequest,\n  ): Promise<BucketInfo> {\n    return this.postJson<BucketInfo>(apiUrl, authToken, 'b2_create_bucket', request)\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-delete-bucket | b2_delete_bucket}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   *\n   * @returns The deleted bucket metadata.\n   */\n  async deleteBucket(\n    apiUrl: string,\n    authToken: string,\n    request: DeleteBucketRequest,\n  ): Promise<BucketInfo> {\n    return this.postJson<BucketInfo>(apiUrl, authToken, 'b2_delete_bucket', request)\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-list-buckets | b2_list_buckets}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   *\n   * @returns The list of matching buckets.\n   */\n  async listBuckets(\n    apiUrl: string,\n    authToken: string,\n    request: ListBucketsRequest,\n  ): Promise<ListBucketsResponse> {\n    return this.postJson<ListBucketsResponse>(apiUrl, authToken, 'b2_list_buckets', request)\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-update-bucket | b2_update_bucket}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   *\n   * @returns The updated bucket metadata.\n   */\n  async updateBucket(\n    apiUrl: string,\n    authToken: string,\n    request: UpdateBucketRequest,\n  ): Promise<BucketInfo> {\n    return this.postJson<BucketInfo>(apiUrl, authToken, 'b2_update_bucket', request)\n  }\n\n  // --- Files ---\n\n  /**\n   * Calls `b2_get_upload_url` with legacy positional request controls.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   * @param signal - Optional abort signal for cancellation.\n   * @param retry - Optional per-request retry override.\n   *\n   * @returns The upload URL and authorization token.\n   *\n   * @deprecated Use the options-bag overload: `getUploadUrl(apiUrl, authToken, request, { signal, retry })`.\n   */\n  async getUploadUrl(\n    apiUrl: string,\n    authToken: string,\n    request: GetUploadUrlRequest,\n    signal?: AbortSignal,\n    retry?: Partial<RetryOptions>,\n  ): Promise<GetUploadUrlResponse>\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-get-upload-url | b2_get_upload_url}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   * @param options - Optional request controls such as cancellation and retry overrides.\n   *\n   * @returns The upload URL and authorization token.\n   */\n  async getUploadUrl(\n    apiUrl: string,\n    authToken: string,\n    request: GetUploadUrlRequest,\n    options?: RawRequestOptions,\n  ): Promise<GetUploadUrlResponse>\n  /**\n   * Implementation for both upload URL request-control signatures.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   * @param optionsOrSignal - Options bag or legacy abort signal.\n   * @param retry - Optional legacy per-request retry override.\n   *\n   * @returns The upload URL and authorization token.\n   */\n  async getUploadUrl(\n    apiUrl: string,\n    authToken: string,\n    request: GetUploadUrlRequest,\n    optionsOrSignal?: RawRequestOptions | AbortSignal,\n    retry?: Partial<RetryOptions>,\n  ): Promise<GetUploadUrlResponse> {\n    return this.postJson<GetUploadUrlResponse>(\n      apiUrl,\n      authToken,\n      'b2_get_upload_url',\n      request,\n      normalizeRawRequestOptions(optionsOrSignal, retry),\n    )\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-upload-file | b2_upload_file}.\n   *\n   * Unlike most methods, this posts directly to the `uploadUrl` obtained\n   * from {@link getUploadUrl} rather than the API URL.\n   * @param uploadUrl - The upload endpoint URL.\n   * @param headers - The request headers including authorization and content metadata.\n   * @param body - The file data to upload.\n   * @param signal - Optional legacy abort signal for cancellation.\n   * @param retry - Optional legacy per-request retry override.\n   *\n   * @returns The uploaded file version metadata.\n   *\n   * @deprecated Use the options-bag overload: `uploadFile(uploadUrl, headers, body, { signal, retry })`.\n   */\n  async uploadFile(\n    uploadUrl: string,\n    headers: UploadFileHeaders,\n    body: BodyInit,\n    signal?: AbortSignal,\n    retry?: Partial<RetryOptions>,\n  ): Promise<FileVersion>\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-upload-file | b2_upload_file}.\n   *\n   * Unlike most methods, this posts directly to the `uploadUrl` obtained\n   * from {@link getUploadUrl} rather than the API URL.\n   * @param uploadUrl - The upload endpoint URL.\n   * @param headers - The request headers including authorization and content metadata.\n   * @param body - The file data to upload.\n   * @param options - Optional request controls such as cancellation and retry overrides.\n   *\n   * @returns The uploaded file version metadata.\n   */\n  async uploadFile(\n    uploadUrl: string,\n    headers: UploadFileHeaders,\n    body: BodyInit,\n    options?: UploadFileOptions,\n  ): Promise<FileVersion>\n  /**\n   * Implementation for both upload-file request-control signatures.\n   * @param uploadUrl - The upload endpoint URL.\n   * @param headers - The request headers including authorization and content metadata.\n   * @param body - The file data to upload.\n   * @param optionsOrSignal - Options bag or legacy abort signal.\n   * @param retry - Optional legacy per-request retry override.\n   *\n   * @returns The uploaded file version metadata.\n   */\n  async uploadFile(\n    uploadUrl: string,\n    headers: UploadFileHeaders,\n    body: BodyInit,\n    optionsOrSignal?: UploadFileOptions | AbortSignal,\n    retry?: Partial<RetryOptions>,\n  ): Promise<FileVersion> {\n    const options = normalizeRawRequestOptions(optionsOrSignal, retry)\n    const reqHeaders: Record<string, string> = {\n      Authorization: headers.authorization,\n      'X-Bz-File-Name': encodeFileName(headers.fileName),\n      'Content-Type': headers.contentType,\n      'Content-Length': String(headers.contentLength),\n      'X-Bz-Content-Sha1': headers.contentSha1,\n      ...buildFileInfoHeaders(headers.fileInfo),\n    }\n\n    if (headers.lastModifiedMillis !== undefined) {\n      reqHeaders['X-Bz-Info-src_last_modified_millis'] = String(headers.lastModifiedMillis)\n    }\n    if (headers.customUploadTimestamp !== undefined) {\n      assertCustomUploadTimestamp(headers.customUploadTimestamp)\n      reqHeaders['X-Bz-Custom-Upload-Timestamp'] = String(headers.customUploadTimestamp)\n    }\n    if (headers.contentDisposition) {\n      reqHeaders['X-Bz-Info-b2-content-disposition'] = headers.contentDisposition\n    }\n    if (headers.contentLanguage) {\n      reqHeaders['X-Bz-Info-b2-content-language'] = headers.contentLanguage\n    }\n    if (headers.expires) {\n      reqHeaders['X-Bz-Info-b2-expires'] = headers.expires\n    }\n    if (headers.cacheControl) {\n      reqHeaders['X-Bz-Info-b2-cache-control'] = headers.cacheControl\n    }\n    if (headers.contentEncoding) {\n      reqHeaders['X-Bz-Info-b2-content-encoding'] = headers.contentEncoding\n    }\n\n    applyEncryptionHeaders(reqHeaders, headers.serverSideEncryption)\n    applyRetentionHeaders(reqHeaders, headers.fileRetention)\n    applyLegalHoldHeader(reqHeaders, headers.legalHold)\n\n    const response = await this.transport.send({\n      url: uploadUrl,\n      method: 'POST',\n      headers: reqHeaders,\n      body,\n      ...(options?.signal !== undefined ? { signal: options.signal } : {}),\n      ...(options?.retry !== undefined ? { retry: options.retry } : {}),\n    })\n    try {\n      return normalizeFileVersionSha1(await response.json<FileVersion>())\n    } catch (err) {\n      throw uploadResponseBodyError(err, options?.signal)\n    }\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-list-file-names | b2_list_file_names}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   * @param options - Optional request controls such as an abort signal.\n   *\n   * @returns The list of file names and optional continuation token.\n   */\n  async listFileNames(\n    apiUrl: string,\n    authToken: string,\n    request: ListFileNamesRequest,\n    options?: ListFileNamesOptions,\n  ): Promise<ListFileNamesResponse> {\n    return normalizeFileVersionListSha1(\n      await this.postJson<ListFileNamesResponse>(\n        apiUrl,\n        authToken,\n        'b2_list_file_names',\n        request,\n        options,\n      ),\n    )\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-list-file-versions | b2_list_file_versions}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   * @param options - Optional request controls such as an abort signal.\n   *\n   * @returns The list of file versions and optional continuation token.\n   */\n  async listFileVersions(\n    apiUrl: string,\n    authToken: string,\n    request: ListFileVersionsRequest,\n    options?: ListFileVersionsOptions,\n  ): Promise<ListFileVersionsResponse> {\n    return normalizeFileVersionListSha1(\n      await this.postJson<ListFileVersionsResponse>(\n        apiUrl,\n        authToken,\n        'b2_list_file_versions',\n        request,\n        options,\n      ),\n    )\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-get-file-info | b2_get_file_info}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   *\n   * @returns The file version metadata.\n   */\n  async getFileInfo(\n    apiUrl: string,\n    authToken: string,\n    request: GetFileInfoRequest,\n  ): Promise<FileVersion> {\n    return normalizeFileVersionSha1(\n      await this.postJson<FileVersion>(apiUrl, authToken, 'b2_get_file_info', request),\n    )\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-hide-file | b2_hide_file}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   * @param options - Optional request controls such as an abort signal.\n   *\n   * @returns The hidden file version metadata.\n   */\n  async hideFile(\n    apiUrl: string,\n    authToken: string,\n    request: HideFileRequest,\n    options?: { readonly signal?: AbortSignal },\n  ): Promise<FileVersion> {\n    return normalizeFileVersionSha1(\n      await this.postJson<FileVersion>(apiUrl, authToken, 'b2_hide_file', request, options),\n    )\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-delete-file-version | b2_delete_file_version}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   * @param options - Optional request controls such as an abort signal.\n   *\n   * @returns The deleted file version identifier.\n   */\n  async deleteFileVersion(\n    apiUrl: string,\n    authToken: string,\n    request: DeleteFileVersionRequest,\n    options?: { readonly signal?: AbortSignal },\n  ): Promise<DeleteFileVersionResponse> {\n    return this.postJson<DeleteFileVersionResponse>(\n      apiUrl,\n      authToken,\n      'b2_delete_file_version',\n      request,\n      options,\n    )\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-copy-file | b2_copy_file}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   * @param options - Optional request controls such as an abort signal.\n   *\n   * @returns The copied file version metadata.\n   */\n  async copyFile(\n    apiUrl: string,\n    authToken: string,\n    request: CopyFileRequest,\n    options?: RawRequestOptions,\n  ): Promise<FileVersion> {\n    return normalizeFileVersionSha1(\n      await this.postJson<FileVersion>(\n        apiUrl,\n        authToken,\n        'b2_copy_file',\n        withJsonBodyWireSseC(request),\n        options,\n      ),\n    )\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-copy-part | b2_copy_part}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   * @param options - Optional abort and retry controls.\n   *\n   * @returns The copied part metadata.\n   */\n  async copyPart(\n    apiUrl: string,\n    authToken: string,\n    request: CopyPartRequest,\n    options?: CopyPartOptions,\n  ): Promise<CopyPartResponse> {\n    return this.postJson<CopyPartResponse>(\n      apiUrl,\n      authToken,\n      'b2_copy_part',\n      withJsonBodyWireSseC(request),\n      options,\n    )\n  }\n\n  // --- Large Files ---\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-start-large-file | b2_start_large_file}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   * @param options - Optional abort and retry controls.\n   *\n   * @returns The started large file metadata with file ID.\n   */\n  async startLargeFile(\n    apiUrl: string,\n    authToken: string,\n    request: StartLargeFileRequest,\n    options?: StartLargeFileOptions,\n  ): Promise<StartLargeFileResponse> {\n    assertRawCustomUploadTimestamp(request.customUploadTimestamp)\n    return normalizeFileVersionSha1(\n      await this.postJson<StartLargeFileResponse>(\n        apiUrl,\n        authToken,\n        'b2_start_large_file',\n        withJsonBodyWireSseC(request),\n        options,\n      ),\n    )\n  }\n\n  /**\n   * Calls `b2_get_upload_part_url` with legacy positional request controls.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   * @param signal - Optional abort signal for cancellation.\n   * @param retry - Optional per-request retry override.\n   *\n   * @returns The upload part URL and authorization token.\n   *\n   * @deprecated Use the options-bag overload: `getUploadPartUrl(apiUrl, authToken, request, { signal, retry })`.\n   */\n  async getUploadPartUrl(\n    apiUrl: string,\n    authToken: string,\n    request: GetUploadPartUrlRequest,\n    signal?: AbortSignal,\n    retry?: Partial<RetryOptions>,\n  ): Promise<GetUploadPartUrlResponse>\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-get-upload-part-url | b2_get_upload_part_url}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   * @param options - Optional request controls such as cancellation and retry overrides.\n   *\n   * @returns The upload part URL and authorization token.\n   */\n  async getUploadPartUrl(\n    apiUrl: string,\n    authToken: string,\n    request: GetUploadPartUrlRequest,\n    options?: RawRequestOptions,\n  ): Promise<GetUploadPartUrlResponse>\n  /**\n   * Implementation for both upload part URL request-control signatures.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   * @param optionsOrSignal - Options bag or legacy abort signal.\n   * @param retry - Optional legacy per-request retry override.\n   *\n   * @returns The upload part URL and authorization token.\n   */\n  async getUploadPartUrl(\n    apiUrl: string,\n    authToken: string,\n    request: GetUploadPartUrlRequest,\n    optionsOrSignal?: RawRequestOptions | AbortSignal,\n    retry?: Partial<RetryOptions>,\n  ): Promise<GetUploadPartUrlResponse> {\n    return this.postJson<GetUploadPartUrlResponse>(\n      apiUrl,\n      authToken,\n      'b2_get_upload_part_url',\n      request,\n      normalizeRawRequestOptions(optionsOrSignal, retry),\n    )\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-upload-part | b2_upload_part}.\n   *\n   * Posts directly to the `uploadUrl` obtained from {@link getUploadPartUrl}\n   * rather than the API URL.\n   * @param uploadUrl - The upload endpoint URL.\n   * @param headers - The request headers including authorization and content metadata.\n   * @param body - The file data to upload.\n   * @param signal - Optional legacy abort signal for cancellation.\n   * @param retry - Optional legacy per-request retry override.\n   *\n   * @returns The uploaded part metadata.\n   *\n   * @deprecated Use the options-bag overload: `uploadPart(uploadUrl, headers, body, { signal, retry })`.\n   */\n  async uploadPart(\n    uploadUrl: string,\n    headers: UploadPartHeaders,\n    body: BodyInit,\n    signal?: AbortSignal,\n    retry?: Partial<RetryOptions>,\n  ): Promise<UploadPartResponse>\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-upload-part | b2_upload_part}.\n   *\n   * Posts directly to the `uploadUrl` obtained from {@link getUploadPartUrl}\n   * rather than the API URL.\n   * @param uploadUrl - The upload endpoint URL.\n   * @param headers - The request headers including authorization and content metadata.\n   * @param body - The file data to upload.\n   * @param options - Optional request controls such as cancellation and retry overrides.\n   *\n   * @returns The uploaded part metadata.\n   */\n  async uploadPart(\n    uploadUrl: string,\n    headers: UploadPartHeaders,\n    body: BodyInit,\n    options?: UploadPartOptions,\n  ): Promise<UploadPartResponse>\n  /**\n   * Implementation for both upload-part request-control signatures.\n   * @param uploadUrl - The upload endpoint URL.\n   * @param headers - The request headers including authorization and content metadata.\n   * @param body - The file data to upload.\n   * @param optionsOrSignal - Options bag or legacy abort signal.\n   * @param retry - Optional legacy per-request retry override.\n   *\n   * @returns The uploaded part metadata.\n   */\n  async uploadPart(\n    uploadUrl: string,\n    headers: UploadPartHeaders,\n    body: BodyInit,\n    optionsOrSignal?: UploadPartOptions | AbortSignal,\n    retry?: Partial<RetryOptions>,\n  ): Promise<UploadPartResponse> {\n    const options = normalizeRawRequestOptions(optionsOrSignal, retry)\n    const reqHeaders: Record<string, string> = {\n      Authorization: headers.authorization,\n      'X-Bz-Part-Number': String(headers.partNumber),\n      'Content-Length': String(headers.contentLength),\n      'X-Bz-Content-Sha1': headers.contentSha1,\n    }\n\n    applyEncryptionHeaders(reqHeaders, headers.serverSideEncryption)\n\n    const response = await this.transport.send({\n      url: uploadUrl,\n      method: 'POST',\n      headers: reqHeaders,\n      body,\n      ...(options?.signal !== undefined ? { signal: options.signal } : {}),\n      ...(options?.retry !== undefined ? { retry: options.retry } : {}),\n    })\n    try {\n      return await response.json<UploadPartResponse>()\n    } catch (err) {\n      throw uploadResponseBodyError(err, options?.signal)\n    }\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-finish-large-file | b2_finish_large_file}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   * @param options - Optional abort and retry controls.\n   *\n   * @returns The completed file version metadata.\n   */\n  async finishLargeFile(\n    apiUrl: string,\n    authToken: string,\n    request: FinishLargeFileRequest,\n    options?: FinishLargeFileOptions,\n  ): Promise<FileVersion> {\n    const response = await this.transport.send({\n      url: b2Url(apiUrl, { ...B2_NATIVE_API_V3, endpoint: 'b2_finish_large_file' }),\n      method: 'POST',\n      headers: {\n        Authorization: authToken,\n        'Content-Type': 'application/json',\n      },\n      body: JSON.stringify(request),\n      ...(options?.signal !== undefined ? { signal: options.signal } : {}),\n      ...(options?.retry !== undefined ? { retry: options.retry } : {}),\n    })\n\n    let fileVersion: FileVersion\n    try {\n      fileVersion = await response.json<FileVersion>()\n    } catch (err) {\n      throw new FinishLargeFileResponseBodyError(\n        err instanceof Error ? err.message : 'Finish large file response body could not be read',\n        { cause: err, fileId: request.fileId },\n      )\n    }\n    return normalizeFileVersionSha1(fileVersion)\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-cancel-large-file | b2_cancel_large_file}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   * @param options - Optional request controls such as cancellation and retry overrides.\n   *\n   * @returns The cancelled large file metadata.\n   */\n  async cancelLargeFile(\n    apiUrl: string,\n    authToken: string,\n    request: CancelLargeFileRequest,\n    options?: RawRequestOptions,\n  ): Promise<CancelLargeFileResponse> {\n    return this.postJson<CancelLargeFileResponse>(\n      apiUrl,\n      authToken,\n      'b2_cancel_large_file',\n      request,\n      options,\n    )\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-list-unfinished-large-files | b2_list_unfinished_large_files}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   * @param options - Optional request controls such as cancellation and retry.\n   *\n   * @returns The list of unfinished large files and optional continuation token.\n   */\n  async listUnfinishedLargeFiles(\n    apiUrl: string,\n    authToken: string,\n    request: ListUnfinishedLargeFilesRequest,\n    options?: RawRequestOptions,\n  ): Promise<ListUnfinishedLargeFilesResponse> {\n    return normalizeFileVersionListSha1(\n      await this.postJson<ListUnfinishedLargeFilesResponse>(\n        apiUrl,\n        authToken,\n        'b2_list_unfinished_large_files',\n        request,\n        options,\n      ),\n    )\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-list-parts | b2_list_parts}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   * @param options - Optional request controls such as cancellation and retry.\n   *\n   * @returns The list of uploaded parts and optional continuation token.\n   */\n  async listParts(\n    apiUrl: string,\n    authToken: string,\n    request: ListPartsRequest,\n    options?: RawRequestOptions,\n  ): Promise<ListPartsResponse> {\n    return this.postJson<ListPartsResponse>(apiUrl, authToken, 'b2_list_parts', request, options)\n  }\n\n  // --- Downloads ---\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-download-file-by-id | b2_download_file_by_id}.\n   * @param downloadUrl - The B2 download base URL.\n   * @param authToken - The authorization token.\n   * @param fileId - The unique identifier of the file to download.\n   * @param options - Optional download parameters for range requests and cancellation.\n   *\n   * @returns The response headers, streaming body, and HTTP status code.\n   */\n  async downloadFileById(\n    downloadUrl: string,\n    authToken: string,\n    fileId: string,\n    options?: DownloadFileOptions,\n  ): Promise<{\n    /** Response headers containing file metadata and B2 info headers. */\n    headers: Headers\n    /** Streaming response body, or `null` for HEAD-like responses. */\n    body: ReadableStream<Uint8Array> | null\n    /** HTTP status code (200 for full content, 206 for partial content). */\n    status: number\n  }> {\n    const headers = buildDownloadRequestHeaders(authToken, options)\n    const url = appendDownloadOverrides(\n      `${b2Url(downloadUrl, {\n        ...B2_NATIVE_API_V3,\n        endpoint: 'b2_download_file_by_id',\n      })}?fileId=${encodeURIComponent(fileId)}`,\n      options,\n    )\n\n    const response = await this.transport.send({\n      url,\n      method: options?.method ?? 'GET',\n      headers,\n      ...(options?.signal !== undefined ? { signal: options.signal } : {}),\n    })\n\n    return { headers: response.headers, body: response.body, status: response.status }\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-download-file-by-name | b2_download_file_by_name}.\n   * @param downloadUrl - The B2 download base URL.\n   * @param authToken - The authorization token.\n   * @param bucketName - The name of the bucket containing the file.\n   * @param fileName - The name of the file to download.\n   * @param options - Optional download parameters for range requests and cancellation.\n   *\n   * @returns The response headers, streaming body, and HTTP status code.\n   */\n  async downloadFileByName(\n    downloadUrl: string,\n    authToken: string,\n    bucketName: string,\n    fileName: string,\n    options?: DownloadFileOptions,\n  ): Promise<{\n    /** Response headers containing file metadata and B2 info headers. */\n    headers: Headers\n    /** Streaming response body, or `null` for HEAD-like responses. */\n    body: ReadableStream<Uint8Array> | null\n    /** HTTP status code (200 for full content, 206 for partial content). */\n    status: number\n  }> {\n    const headers = buildDownloadRequestHeaders(authToken, options)\n    const url = appendDownloadOverrides(\n      `${downloadUrl}/file/${encodeURIComponent(bucketName)}/${encodeFileName(fileName)}`,\n      options,\n    )\n\n    const response = await this.transport.send({\n      url,\n      method: options?.method ?? 'GET',\n      headers,\n      ...(options?.signal !== undefined ? { signal: options.signal } : {}),\n    })\n\n    return { headers: response.headers, body: response.body, status: response.status }\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-get-download-authorization | b2_get_download_authorization}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The current session authorization token.\n   * @param request - The API request parameters.\n   *\n   * @returns The download authorization token for the specified file prefix.\n   */\n  async getDownloadAuthorization(\n    apiUrl: string,\n    authToken: string,\n    request: DownloadAuthorizationRequest,\n  ): Promise<DownloadAuthorizationResponse> {\n    return this.postJson<DownloadAuthorizationResponse>(\n      apiUrl,\n      authToken,\n      'b2_get_download_authorization',\n      request,\n    )\n  }\n\n  // --- Keys ---\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-create-key | b2_create_key}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   *\n   * @returns The newly created application key with secret.\n   */\n  async createKey(\n    apiUrl: string,\n    authToken: string,\n    request: CreateKeyRequest,\n  ): Promise<FullApplicationKey> {\n    const key = await this.postJson<FullApplicationKey>(\n      apiUrl,\n      authToken,\n      'b2_create_key',\n      normalizeCreateKeyRequest(request),\n      undefined,\n      B2_NATIVE_API_V4,\n    )\n    return normalizeKeyResponse(key)\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-list-keys | b2_list_keys}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   *\n   * @returns The list of application keys and optional continuation token.\n   */\n  async listKeys(\n    apiUrl: string,\n    authToken: string,\n    request: ListKeysRequest,\n  ): Promise<ListKeysResponse> {\n    const response = await this.postJson<ListKeysResponse>(\n      apiUrl,\n      authToken,\n      'b2_list_keys',\n      request,\n      undefined,\n      B2_NATIVE_API_V4,\n    )\n    return { ...response, keys: response.keys.map((key) => normalizeKeyResponse(key)) }\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-delete-key | b2_delete_key}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   *\n   * @returns The deleted application key metadata.\n   */\n  async deleteKey(\n    apiUrl: string,\n    authToken: string,\n    request: DeleteKeyRequest,\n  ): Promise<ApplicationKey> {\n    const key = await this.postJson<ApplicationKey>(\n      apiUrl,\n      authToken,\n      'b2_delete_key',\n      request,\n      undefined,\n      B2_NATIVE_API_V4,\n    )\n    return normalizeKeyResponse(key)\n  }\n\n  // --- Retention / Legal Hold ---\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-update-file-retention | b2_update_file_retention}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   *\n   * @returns The updated file retention settings.\n   */\n  async updateFileRetention(\n    apiUrl: string,\n    authToken: string,\n    request: UpdateFileRetentionRequest,\n  ): Promise<UpdateFileRetentionResponse> {\n    return this.postJson<UpdateFileRetentionResponse>(\n      apiUrl,\n      authToken,\n      'b2_update_file_retention',\n      request,\n    )\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-update-file-legal-hold | b2_update_file_legal_hold}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   *\n   * @returns The updated file legal hold status.\n   */\n  async updateFileLegalHold(\n    apiUrl: string,\n    authToken: string,\n    request: UpdateFileLegalHoldRequest,\n  ): Promise<UpdateFileLegalHoldResponse> {\n    return this.postJson<UpdateFileLegalHoldResponse>(\n      apiUrl,\n      authToken,\n      'b2_update_file_legal_hold',\n      request,\n    )\n  }\n\n  // --- Notifications ---\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-get-bucket-notification-rules | b2_get_bucket_notification_rules}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   *\n   * @returns The configured event notification rules for the specified bucket.\n   */\n  async getBucketNotificationRules(\n    apiUrl: string,\n    authToken: string,\n    request: GetBucketNotificationRulesRequest,\n  ): Promise<GetBucketNotificationRulesResponse> {\n    return this.postJson<GetBucketNotificationRulesResponse>(\n      apiUrl,\n      authToken,\n      'b2_get_bucket_notification_rules',\n      request,\n    )\n  }\n\n  /**\n   * Calls {@link https://www.backblaze.com/apidocs/b2-set-bucket-notification-rules | b2_set_bucket_notification_rules}.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param request - The API request parameters.\n   *\n   * @returns The updated bucket notification rules.\n   */\n  async setBucketNotificationRules(\n    apiUrl: string,\n    authToken: string,\n    request: SetBucketNotificationRulesRequest,\n  ): Promise<SetBucketNotificationRulesResponse> {\n    return this.postJson<SetBucketNotificationRulesResponse>(\n      apiUrl,\n      authToken,\n      'b2_set_bucket_notification_rules',\n      request,\n    )\n  }\n\n  // --- Internal ---\n\n  /**\n   * Sends a JSON POST request to the specified B2 API endpoint.\n   * @param apiUrl - The B2 API base URL.\n   * @param authToken - The authorization token.\n   * @param endpoint - The B2 API endpoint name.\n   * @param body - The JSON request body.\n   * @param options - Optional abort and per-request retry settings.\n   * @param urlOptions - B2 endpoint path prefix and version settings.\n   *\n   * @returns The parsed JSON response.\n   */\n  private async postJson<T>(\n    apiUrl: string,\n    authToken: string,\n    endpoint: string,\n    body: unknown,\n    options?: RawRequestOptions,\n    urlOptions: B2EndpointUrlOptions = B2_NATIVE_API_V3,\n  ): Promise<T> {\n    const response = await this.transport.send({\n      url: b2Url(apiUrl, { ...urlOptions, endpoint }),\n      method: 'POST',\n      headers: {\n        Authorization: authToken,\n        'Content-Type': 'application/json',\n      },\n      body: JSON.stringify(body),\n      ...(options?.signal !== undefined ? { signal: options.signal } : {}),\n      ...(options?.retry !== undefined ? { retry: options.retry } : {}),\n    })\n    return response.json<T>()\n  }\n}\n\n// --- Header helpers ---\n\nimport { EncryptionAlgorithm, EncryptionMode, type EncryptionSetting } from '../types/encryption.ts'\nimport type { FileRetentionValue, LegalHoldValue } from '../types/lock.ts'\n\ninterface JsonBodySseCRequest {\n  readonly serverSideEncryption?: EncryptionSetting\n  readonly sourceServerSideEncryption?: EncryptionSetting\n  readonly destinationServerSideEncryption?: EncryptionSetting\n}\n\nfunction withJsonBodyWireSseC<T extends JsonBodySseCRequest>(request: T): T {\n  return {\n    ...request,\n    ...(request.serverSideEncryption !== undefined\n      ? { serverSideEncryption: toWireSseC(request.serverSideEncryption) }\n      : {}),\n    ...(request.sourceServerSideEncryption !== undefined\n      ? { sourceServerSideEncryption: toWireSseC(request.sourceServerSideEncryption) }\n      : {}),\n    ...(request.destinationServerSideEncryption !== undefined\n      ? { destinationServerSideEncryption: toWireSseC(request.destinationServerSideEncryption) }\n      : {}),\n  }\n}\n\nfunction toWireSseC(setting: EncryptionSetting): EncryptionSetting {\n  if (setting.mode !== EncryptionMode.SseC) return setting\n  // SSE-C settings may be redacted wrappers with non-enumerable key fields.\n  // Passing the wrapper through would let toJSON() emit the redaction placeholder;\n  // spreading it would drop the key fields. Read directly into a plain wire\n  // literal for the B2 JSON body only, and never pass that cleartext literal to\n  // diagnostics or logging sinks.\n  return {\n    mode: EncryptionMode.SseC,\n    algorithm: setting.algorithm,\n    customerKey: setting.customerKey,\n    customerKeyMd5: setting.customerKeyMd5,\n  }\n}\n\n/**\n * Applies server-side encryption headers to the request.\n * @param headers - The mutable headers object to populate.\n * @param encryption - The encryption settings, or undefined to skip.\n */\nfunction applyEncryptionHeaders(\n  headers: Record<string, string>,\n  encryption: EncryptionSetting | undefined,\n): void {\n  if (!encryption || encryption.mode === EncryptionMode.None) return\n  if (encryption.mode === EncryptionMode.SseB2) {\n    headers['X-Bz-Server-Side-Encryption'] = EncryptionAlgorithm.Aes256\n  } else if (encryption.mode === EncryptionMode.SseC) {\n    headers['X-Bz-Server-Side-Encryption-Customer-Algorithm'] = EncryptionAlgorithm.Aes256\n    headers['X-Bz-Server-Side-Encryption-Customer-Key'] = encryption.customerKey\n    headers['X-Bz-Server-Side-Encryption-Customer-Key-Md5'] = encryption.customerKeyMd5\n  }\n}\n\n/**\n * SSE-C decryption parameters supplied to downloads of files that were\n * uploaded with customer-managed keys.\n */\nexport interface SseCDownloadKey {\n  /** Encryption algorithm. Always `EncryptionAlgorithm.Aes256` (`'AES256'`). */\n  readonly algorithm: EncryptionAlgorithm\n  /**\n   * Base64-encoded customer-provided decryption key. This value must be sent as\n   * an HTTP request header for SSE-C downloads, so custom transports should not\n   * log request headers without redacting them first.\n   */\n  readonly customerKey: string\n  /** Base64-encoded MD5 digest of the decryption key. */\n  readonly customerKeyMd5: string\n}\n\n/**\n * Options accepted by {@link RawClient.downloadFileById} and\n * {@link RawClient.downloadFileByName}. Mirrors the B2 native API: range +\n * SSE-C decryption headers + the documented `b2Content*` response-header\n * overrides (query-string parameters on the request URL).\n */\nexport interface DownloadFileOptions {\n  /** HTTP method. Defaults to `'GET'`. Use `'HEAD'` to fetch headers without the body. */\n  readonly method?: 'GET' | 'HEAD'\n  /** HTTP Range header value for partial content requests. */\n  readonly range?: string\n  /** SSE-C decryption parameters, required if the file was uploaded with SSE-C. */\n  readonly serverSideEncryption?: SseCDownloadKey\n  /** Override the `Content-Disposition` header in the download response. */\n  readonly b2ContentDisposition?: string\n  /** Override the `Content-Language` header in the download response. */\n  readonly b2ContentLanguage?: string\n  /** Override the `Content-Encoding` header in the download response. */\n  readonly b2ContentEncoding?: string\n  /** Override the `Content-Type` header in the download response. */\n  readonly b2ContentType?: string\n  /** Override the `Cache-Control` header in the download response. */\n  readonly b2CacheControl?: string\n  /** Override the `Expires` header in the download response. */\n  readonly b2Expires?: string\n  /** Signal to abort the download. */\n  readonly signal?: AbortSignal\n}\n\nconst DOWNLOAD_OVERRIDE_PARAMS = [\n  'b2ContentDisposition',\n  'b2ContentLanguage',\n  'b2ContentEncoding',\n  'b2ContentType',\n  'b2CacheControl',\n  'b2Expires',\n] as const\n\n/**\n * Builds the HTTP request headers for a download: Authorization, optional\n * Range, and optional SSE-C decryption headers.\n *\n * @param authToken - The B2 session authorization token.\n * @param options - Caller-supplied download options.\n *\n * @returns The header map to send with the request.\n */\nfunction buildDownloadRequestHeaders(\n  authToken: string,\n  options: DownloadFileOptions | undefined,\n): Record<string, string> {\n  const headers: Record<string, string> = { Authorization: authToken }\n  if (options?.range) headers['Range'] = options.range\n  if (options?.serverSideEncryption) {\n    const encryption = options.serverSideEncryption\n    // SSE-C keys may be redacted wrappers with non-enumerable key fields.\n    // Read fields directly; object spread would drop the wire header values.\n    applyEncryptionHeaders(headers, {\n      mode: EncryptionMode.SseC,\n      algorithm: encryption.algorithm,\n      customerKey: encryption.customerKey,\n      customerKeyMd5: encryption.customerKeyMd5,\n    })\n  }\n  return headers\n}\n\n/**\n * Appends the documented `b2Content*` response-header overrides to a download\n * URL as query-string parameters. B2 echoes the values into the response\n * headers so callers can control content type, disposition, and caching.\n *\n * @param url - The base download URL.\n * @param options - Caller-supplied download options.\n *\n * @returns The URL with any override parameters appended.\n */\nfunction appendDownloadOverrides(url: string, options: DownloadFileOptions | undefined): string {\n  if (!options) return url\n  const params: string[] = []\n  for (const key of DOWNLOAD_OVERRIDE_PARAMS) {\n    const value = options[key]\n    if (value !== undefined) {\n      params.push(`${key}=${encodeURIComponent(value)}`)\n    }\n  }\n  if (params.length === 0) return url\n  const separator = url.includes('?') ? '&' : '?'\n  return `${url}${separator}${params.join('&')}`\n}\n\n/**\n * Applies file retention headers to the request.\n * @param headers - The mutable headers object to populate.\n * @param retention - The retention settings, or undefined to skip.\n */\nfunction applyRetentionHeaders(\n  headers: Record<string, string>,\n  retention: FileRetentionValue | undefined,\n): void {\n  if (!retention) return\n  if (retention.mode) {\n    headers['X-Bz-File-Retention-Mode'] = retention.mode\n  }\n  if (retention.retainUntilTimestamp) {\n    headers['X-Bz-File-Retention-Retain-Until-Timestamp'] = String(retention.retainUntilTimestamp)\n  }\n}\n\n/**\n * Applies the legal hold header to the request.\n * @param headers - The mutable headers object to populate.\n * @param legalHold - The legal hold value, or undefined to skip.\n */\nfunction applyLegalHoldHeader(\n  headers: Record<string, string>,\n  legalHold: LegalHoldValue | undefined,\n): void {\n  if (!legalHold) return\n  headers['X-Bz-File-Legal-Hold'] = legalHold\n}\n\nexport {\n  buildFileInfoHeaders,\n  decodeFileName,\n  encodeFileName,\n  parseFileInfoHeaders,\n} from './encoding.ts'\n"],"mappings":"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"}

package/dist/raw/url.cjs

@@ -0,0 +1,111 @@
+//#region src/raw/url.ts
+var SLASH = "/";
+var BACKSLASH = "\\";
+var VERSION_PREFIX = "v";
+var VERSION_DIGITS = "0123456789";
+var URL_DELIMITERS = ["?", "#"];
+/**
+* Returns true when `value` is a B2 API version segment of the form `vN`.
+*
+* @param value - Candidate API version segment.
+*
+* @returns Whether the value is a valid B2 API version segment.
+*/
+function isB2ApiVersion(value) {
+	if (!value.startsWith(VERSION_PREFIX) || value.length === 1) return false;
+	for (let index = 1; index < value.length; index += 1) {
+		const digit = value[index];
+		if (digit === void 0 || !VERSION_DIGITS.includes(digit)) return false;
+	}
+	return true;
+}
+function assertB2ApiVersion(value) {
+	if (!isB2ApiVersion(value)) throw new TypeError("Invalid version: expected a B2 API version segment like \"v3\"");
+}
+function trimSlashes(value, { leading, trailing }) {
+	let start = 0;
+	let end = value.length;
+	while (leading && start < end && value[start] === SLASH) start += 1;
+	while (trailing && end > start && value[end - 1] === SLASH) end -= 1;
+	return start === 0 && end === value.length ? value : value.slice(start, end);
+}
+function hasUrlDelimiter(value) {
+	return URL_DELIMITERS.some((delimiter) => value.includes(delimiter));
+}
+function hasEncodedPathDelimiter(value) {
+	const lowerValue = value.toLowerCase();
+	return lowerValue.includes("%2f") || lowerValue.includes("%3f") || lowerValue.includes("%23") || lowerValue.includes("%5c");
+}
+function withDotEscapesDecoded(value) {
+	let decoded = "";
+	let index = 0;
+	while (index < value.length) if (value.slice(index, index + 3).toLowerCase() === "%2e") {
+		decoded += ".";
+		index += 3;
+	} else {
+		decoded += value[index];
+		index += 1;
+	}
+	return decoded;
+}
+function isTraversalComponent(value) {
+	const decoded = withDotEscapesDecoded(value);
+	return decoded === "." || decoded === "..";
+}
+function validatePathComponent(component, optionName) {
+	if (component.length === 0) throw new TypeError(`Invalid ${optionName}: path components must not be empty`);
+	if (hasUrlDelimiter(component)) throw new TypeError(`Invalid ${optionName}: path components must not contain "?" or "#"`);
+	if (component.includes(BACKSLASH)) throw new TypeError(`Invalid ${optionName}: path components must not contain "\\"`);
+	if (hasEncodedPathDelimiter(component)) throw new TypeError(`Invalid ${optionName}: path components must not contain encoded "/", "\\", "?", or "#"`);
+	if (isTraversalComponent(component)) throw new TypeError(`Invalid ${optionName}: path components must not be "." or ".."`);
+}
+function preparePathPrefix(prefix) {
+	const trimmed = trimSlashes(prefix, {
+		leading: true,
+		trailing: true
+	});
+	if (trimmed.length === 0) return "";
+	for (const component of trimmed.split(SLASH)) validatePathComponent(component, "prefix");
+	return trimmed;
+}
+function preparePathSegment(segment, optionName) {
+	const trimmed = trimSlashes(segment, {
+		leading: true,
+		trailing: true
+	});
+	if (trimmed.length === 0) return "";
+	if (trimmed.includes(SLASH)) throw new TypeError(`Invalid ${optionName}: expected a single path segment`);
+	validatePathComponent(trimmed, optionName);
+	return trimmed;
+}
+function prepareVersionSegment(version) {
+	const trimmed = preparePathSegment(version, "version");
+	assertB2ApiVersion(trimmed);
+	return trimmed;
+}
+/**
+* Builds a B2 API endpoint URL from a base URL, path prefix, optional version,
+* and endpoint name.
+*
+* @param baseUrl - API or download base URL.
+* @param options - Path prefix, optional version, and endpoint name.
+*
+* @returns The absolute endpoint URL.
+*/
+function b2Url(baseUrl, { prefix = "b2api", version, endpoint }) {
+	const base = trimSlashes(baseUrl, {
+		leading: false,
+		trailing: true
+	});
+	const path = [
+		preparePathPrefix(prefix),
+		version === void 0 ? void 0 : prepareVersionSegment(version),
+		preparePathSegment(endpoint, "endpoint")
+	].filter((segment) => segment !== void 0).filter((segment) => segment.length > 0).join(SLASH);
+	return path.length === 0 ? base : `${base}/${path}`;
+}
+//#endregion
+exports.b2Url = b2Url;
+exports.isB2ApiVersion = isB2ApiVersion;
+
+//# sourceMappingURL=url.cjs.map