@backblaze-labs/b2-sdk 0.1.0 → 0.2.0

package/dist/raw/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","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 type { HttpTransport } from '../http/transport.ts'\nimport type {\n  ApplicationKey,\n  AuthorizeAccountResponse,\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/**\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    const response = await this.transport.send({\n      url: `${realmUrl}/b2api/v3/b2_authorize_account`,\n      method: 'GET',\n      headers: {\n        Authorization: `Basic ${btoa(`${applicationKeyId}:${applicationKey}`)}`,\n      },\n    })\n    return response.json<AuthorizeAccountResponse>()\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 {@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   *\n   * @returns The upload URL and authorization token.\n   */\n  async getUploadUrl(\n    apiUrl: string,\n    authToken: string,\n    request: GetUploadUrlRequest,\n  ): Promise<GetUploadUrlResponse> {\n    return this.postJson<GetUploadUrlResponse>(apiUrl, authToken, 'b2_get_upload_url', request)\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 - An optional abort signal for cancellation.\n   *\n   * @returns The uploaded file version metadata.\n   */\n  async uploadFile(\n    uploadUrl: string,\n    headers: UploadFileHeaders,\n    body: BodyInit,\n    signal?: AbortSignal,\n  ): Promise<FileVersion> {\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      ...(signal !== undefined ? { signal } : {}),\n    })\n    return normalizeFileVersionSha1(await response.json<FileVersion>())\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   *\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  ): Promise<ListFileNamesResponse> {\n    return normalizeFileVersionListSha1(\n      await this.postJson<ListFileNamesResponse>(apiUrl, authToken, 'b2_list_file_names', request),\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   *\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  ): Promise<ListFileVersionsResponse> {\n    return normalizeFileVersionListSha1(\n      await this.postJson<ListFileVersionsResponse>(\n        apiUrl,\n        authToken,\n        'b2_list_file_versions',\n        request,\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   *\n   * @returns The hidden file version metadata.\n   */\n  async hideFile(\n    apiUrl: string,\n    authToken: string,\n    request: HideFileRequest,\n  ): Promise<FileVersion> {\n    return normalizeFileVersionSha1(\n      await this.postJson<FileVersion>(apiUrl, authToken, 'b2_hide_file', request),\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   *\n   * @returns The deleted file version identifier.\n   */\n  async deleteFileVersion(\n    apiUrl: string,\n    authToken: string,\n    request: DeleteFileVersionRequest,\n  ): Promise<DeleteFileVersionResponse> {\n    return this.postJson<DeleteFileVersionResponse>(\n      apiUrl,\n      authToken,\n      'b2_delete_file_version',\n      request,\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   *\n   * @returns The copied file version metadata.\n   */\n  async copyFile(\n    apiUrl: string,\n    authToken: string,\n    request: CopyFileRequest,\n  ): Promise<FileVersion> {\n    return normalizeFileVersionSha1(\n      await this.postJson<FileVersion>(apiUrl, authToken, 'b2_copy_file', request),\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   *\n   * @returns The copied part metadata.\n   */\n  async copyPart(\n    apiUrl: string,\n    authToken: string,\n    request: CopyPartRequest,\n  ): Promise<CopyPartResponse> {\n    return this.postJson<CopyPartResponse>(apiUrl, authToken, 'b2_copy_part', request)\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   *\n   * @returns The started large file metadata with file ID.\n   */\n  async startLargeFile(\n    apiUrl: string,\n    authToken: string,\n    request: StartLargeFileRequest,\n  ): Promise<StartLargeFileResponse> {\n    return this.postJson<StartLargeFileResponse>(apiUrl, authToken, 'b2_start_large_file', request)\n  }\n\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   *\n   * @returns The upload part URL and authorization token.\n   */\n  async getUploadPartUrl(\n    apiUrl: string,\n    authToken: string,\n    request: GetUploadPartUrlRequest,\n  ): Promise<GetUploadPartUrlResponse> {\n    return this.postJson<GetUploadPartUrlResponse>(\n      apiUrl,\n      authToken,\n      'b2_get_upload_part_url',\n      request,\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 - An optional abort signal for cancellation.\n   *\n   * @returns The uploaded part metadata.\n   */\n  async uploadPart(\n    uploadUrl: string,\n    headers: UploadPartHeaders,\n    body: BodyInit,\n    signal?: AbortSignal,\n  ): Promise<UploadPartResponse> {\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      ...(signal !== undefined ? { signal } : {}),\n    })\n    return response.json<UploadPartResponse>()\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   *\n   * @returns The completed file version metadata.\n   */\n  async finishLargeFile(\n    apiUrl: string,\n    authToken: string,\n    request: FinishLargeFileRequest,\n  ): Promise<FileVersion> {\n    return normalizeFileVersionSha1(\n      await this.postJson<FileVersion>(apiUrl, authToken, 'b2_finish_large_file', request),\n    )\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   *\n   * @returns The cancelled large file metadata.\n   */\n  async cancelLargeFile(\n    apiUrl: string,\n    authToken: string,\n    request: CancelLargeFileRequest,\n  ): Promise<CancelLargeFileResponse> {\n    return this.postJson<CancelLargeFileResponse>(\n      apiUrl,\n      authToken,\n      'b2_cancel_large_file',\n      request,\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   *\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  ): Promise<ListUnfinishedLargeFilesResponse> {\n    return this.postJson<ListUnfinishedLargeFilesResponse>(\n      apiUrl,\n      authToken,\n      'b2_list_unfinished_large_files',\n      request,\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   *\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  ): Promise<ListPartsResponse> {\n    return this.postJson<ListPartsResponse>(apiUrl, authToken, 'b2_list_parts', request)\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    return this.postJson<FullApplicationKey>(apiUrl, authToken, 'b2_create_key', request)\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    return this.postJson<ListKeysResponse>(apiUrl, authToken, 'b2_list_keys', request)\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    return this.postJson<ApplicationKey>(apiUrl, authToken, 'b2_delete_key', request)\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   *\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  ): Promise<T> {\n    const response = await this.transport.send({\n      url: `${apiUrl}/b2api/v3/${endpoint}`,\n      method: 'POST',\n      headers: {\n        Authorization: authToken,\n        'Content-Type': 'application/json',\n      },\n      body: JSON.stringify(body),\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  encodeFileName,\n  decodeFileName,\n  buildFileInfoHeaders,\n  parseFileInfoHeaders,\n} from './encoding.ts'\n"],"names":[],"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'\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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"}

package/dist/s3/index.cjs

@@ -1,23 +1,360 @@
-"use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_url_redaction = require("../internal/url-redaction.cjs");
+const require_encoding = require("../raw/encoding.cjs");
+const require_url_guard = require("../http/url-guard.cjs");
+const require_http = require("../util/http.cjs");
+const require_validation = require("./validation.cjs");
+const require_sigv4 = require("./sigv4.cjs");
+//#region src/s3/index.ts
+var HTTP_HEADER_TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+var HTTP_MEDIA_TYPE = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+\/[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+var DEFAULT_NATIVE_DOWNLOAD_URL_EXPIRES_IN = 3600;
+var TRUSTED_NATIVE_DOWNLOAD_HOST_SUFFIXES = [
+	"backblazeb2.com",
+	"backblaze.com",
+	"backblaze.net",
+	"b2-staging.io"
+];
+var BROWSER_EXECUTABLE_CONTENT_TYPES = /* @__PURE__ */ new Set([
+	"text/html",
+	"application/xhtml+xml",
+	"image/svg+xml",
+	"application/javascript",
+	"text/javascript",
+	"application/x-javascript",
+	"text/x-javascript",
+	"application/ecmascript",
+	"text/ecmascript",
+	"application/x-ecmascript",
+	"text/x-ecmascript",
+	"text/xml",
+	"application/xml"
+]);
+/**
+* Server-side opt-in token for unsafe S3 presign options.
+*
+* Use this token as the value for `allowBrowserExecutableContentType`,
+* `allowBrowserExecutableResponseContentType`, or
+* `allowInlineResponseContentDisposition` only when active content or inline
+* rendering from the storage origin is intentional and trusted.
+*/
+var trustedUnsafeS3PresignOptIn = Object.freeze({ __trustedUnsafeS3PresignOptIn: "trustedUnsafeS3PresignOptIn" });
+/**
+* Derives an S3-compatible client configuration from B2 authorization state.
+* Pass the result to `new S3Client(config)` from `@aws-sdk/client-s3`.
+*
+* Non-standard, custom, or proxied endpoints require an explicit `region`; set
+* it before deploying this SDK to those endpoints. The SDK no longer falls back
+* to `us-west-004` because that can mis-sign requests.
+*
+* @param config - B2 auth state, application key credentials, and optional region override.
+*
+* @returns Configuration ready for the AWS S3 SDK.
+*
+* @example
+* ```ts
+* const { B2_APPLICATION_KEY_ID, B2_APPLICATION_KEY } = process.env
+* if (!B2_APPLICATION_KEY_ID || !B2_APPLICATION_KEY) throw new Error('Missing B2 credentials')
+* const s3 = new S3Client(createS3ClientConfig({
+*   accountInfo: client.accountInfo,
+*   applicationKeyId: B2_APPLICATION_KEY_ID,
+*   applicationKey: B2_APPLICATION_KEY,
+* }))
+* ```
+*/
 function createS3ClientConfig(config) {
-  const s3Url = config.accountInfo.getS3ApiUrl();
-  const regionMatch = s3Url.match(/s3\.([^.]+)\.backblazeb2\.com/);
-  const region = config.region ?? regionMatch?.[1] ?? "us-west-004";
-  return {
-    endpoint: s3Url,
-    region,
-    credentials: {
-      accessKeyId: config.applicationKeyId,
-      secretAccessKey: config.applicationKey
-    },
-    forcePathStyle: true
-  };
-}
-function presignGetObjectUrl(downloadUrl, bucketName, fileName, authorizationToken, validDurationInSeconds = 3600) {
-  const expires = Math.floor(Date.now() / 1e3) + validDurationInSeconds;
-  return `${downloadUrl}/file/${encodeURIComponent(bucketName)}/${encodeURIComponent(fileName)}?Authorization=${encodeURIComponent(authorizationToken)}&expires=${expires}`;
+	const s3Url = config.accountInfo.getS3ApiUrl();
+	const region = config.region ?? deriveRequiredS3Region(s3Url);
+	assertNonEmptyStringOption("applicationKeyId", config.applicationKeyId);
+	assertNonEmptyStringOption("applicationKey", config.applicationKey);
+	assertNonEmptyStringOption("region", region);
+	assertSigV4CredentialScopeComponent("applicationKeyId", config.applicationKeyId);
+	assertSigV4CredentialScopeComponent("region", region);
+	return {
+		endpoint: s3Url,
+		region,
+		credentials: {
+			accessKeyId: config.applicationKeyId,
+			secretAccessKey: config.applicationKey
+		},
+		forcePathStyle: true
+	};
 }
+/**
+* Extracts the B2 S3 region from a standard B2 S3 endpoint.
+*
+* Custom endpoints cannot be inferred safely. Pass `region` explicitly to
+* {@link createS3ClientConfig}, {@link presignS3GetObjectUrl}, or
+* {@link presignS3PutObjectUrl} when this returns `null`.
+*
+* @param endpoint - The S3 endpoint URL.
+*
+* @returns The derived region, or `null` when the endpoint is not a standard B2 S3 URL.
+*/
+function deriveS3RegionFromEndpoint(endpoint) {
+	let hostname;
+	try {
+		hostname = new URL(endpoint).hostname.toLowerCase();
+	} catch {
+		return null;
+	}
+	return /^s3\.([a-z0-9-]+)\.backblazeb2\.com$/.exec(hostname)?.[1] ?? null;
+}
+/**
+* Generates an AWS Signature Version 4 presigned GET URL for B2's S3-compatible API.
+*
+* This helper signs internally and does not pass the B2 application key to
+* runtime peer dependencies. Response override options are signed into the URL
+* and control headers served from the storage origin; do not populate them from
+* untrusted input without an allow-list. Presign success does not prove the URL
+* will be accepted later; keep URL-generating hosts clock-synchronized and
+* check clock skew when downstream use returns SigV4 403 errors.
+*
+* @param options - B2 auth state, S3 credentials, target object, and signing options.
+*
+* @returns The presigned URL string.
+*/
+async function presignS3GetObjectUrl(options) {
+	const query = [["x-id", "GetObject"]];
+	if (options.versionId !== void 0) {
+		assertSafeQueryValue("versionId", options.versionId);
+		query.push(["versionId", options.versionId]);
+	}
+	if (options.responseCacheControl !== void 0) {
+		assertSafeResponseOverride("responseCacheControl", options.responseCacheControl);
+		query.push(["response-cache-control", options.responseCacheControl]);
+	}
+	if (options.responseContentDisposition !== void 0) {
+		assertSafeResponseContentDisposition(options.responseContentDisposition, isTrustedUnsafeS3PresignOptIn(options.allowInlineResponseContentDisposition));
+		query.push(["response-content-disposition", options.responseContentDisposition]);
+	}
+	if (options.responseContentEncoding !== void 0) {
+		assertSafeResponseOverride("responseContentEncoding", options.responseContentEncoding);
+		query.push(["response-content-encoding", options.responseContentEncoding]);
+	}
+	if (options.responseContentLanguage !== void 0) {
+		assertSafeResponseOverride("responseContentLanguage", options.responseContentLanguage);
+		query.push(["response-content-language", options.responseContentLanguage]);
+	}
+	if (options.responseContentType !== void 0) {
+		if (isTrustedUnsafeS3PresignOptIn(options.allowBrowserExecutableResponseContentType)) assertSafeContentTypeValue("responseContentType", options.responseContentType, "response header value");
+		else assertSafeResponseContentType(options.responseContentType);
+		query.push(["response-content-type", options.responseContentType]);
+	}
+	if (options.responseExpires !== void 0) query.push(["response-expires", normalizeResponseExpires(options.responseExpires)]);
+	return await require_sigv4.presignS3Request("GET", createSigV4PresignOptions(options), query, []);
+}
+/**
+* Returns a B2-native download-authorization URL, not an S3 presigned URL.
+*
+* This deprecated helper preserves the legacy positional output contract where
+* the whole file name is encoded as one URL component, including `/` as `%2F`.
+* It keeps the legacy string-building contract for callers that relied on
+* custom/local download URLs or permissive inputs. Use
+* {@link createNativeDownloadAuthorizationUrl} for strict validation.
+*
+* @param downloadUrl - The B2 download URL from authorization.
+* @param bucketName - The bucket containing the file.
+* @param fileName - The file name (path) to download.
+* @param authorizationToken - A download authorization token from `b2_get_download_authorization`.
+* @param validDurationInSeconds - Compatibility-only value for the non-authoritative `expires` query.
+*
+* @returns The B2 native download-authorization URL string.
+*
+* @deprecated Use {@link createNativeDownloadAuthorizationUrl} for B2 native
+* download-token URLs, or {@link presignS3GetObjectUrl} for real S3-compatible
+* AWS Signature Version 4 presigned GET URLs.
+*/
+function presignGetObjectUrl(downloadUrl, bucketName, fileName, authorizationToken, validDurationInSeconds) {
+	const expires = Math.floor(Date.now() / 1e3) + (validDurationInSeconds ?? DEFAULT_NATIVE_DOWNLOAD_URL_EXPIRES_IN);
+	return `${downloadUrl}/file/${encodeURIComponent(bucketName)}/${encodeURIComponent(fileName)}?Authorization=${encodeURIComponent(authorizationToken)}&expires=${expires}`;
+}
+/**
+* Generates an AWS Signature Version 4 presigned PUT URL for browser or
+* third-party uploads through B2's S3-compatible API.
+*
+* This helper signs internally and does not pass the B2 application key to
+* runtime peer dependencies. A presigned PUT URL is a replayable bearer
+* credential for writing one key until expiry. Retried PUTs can create
+* duplicate B2 file versions when a response is lost after B2 stored the object.
+* Use unique keys or reconcile uploaded file IDs/checksums, and configure
+* lifecycle/version cleanup where duplicate versions must be removed
+* automatically. If `contentType` and `contentLength` are omitted, the holder
+* can choose any content type, including browser-executable types, and any size
+* accepted by B2; bind both values before handing URLs to untrusted uploaders
+* to limit financial-DoS and content-type smuggling risk.
+*
+* @param options - B2 auth state, S3 credentials, target object, and signing options.
+*
+* @returns The presigned URL string.
+*/
+async function presignS3PutObjectUrl(options) {
+	const headers = [];
+	if (options.contentType !== void 0) {
+		if (isTrustedUnsafeS3PresignOptIn(options.allowBrowserExecutableContentType)) assertSafeContentTypeValue("contentType", options.contentType, "stored object Content-Type");
+		else assertSafePutContentType(options.contentType);
+		headers.push(["content-type", options.contentType]);
+	}
+	if (options.contentLength !== void 0) headers.push(["content-length", normalizeContentLength(options.contentLength)]);
+	headers.push(...normalizeMetadataHeaders(options.metadata));
+	return await require_sigv4.presignS3Request("PUT", createSigV4PresignOptions(options), [["x-id", "PutObject"]], headers);
+}
+/**
+* Generates an AWS Signature Version 4 presigned PUT URL for B2's
+* S3-compatible API.
+*
+* @param options - B2 auth state, S3 credentials, target object, and signing options.
+*
+* @returns The presigned URL string.
+*
+* @deprecated Use {@link presignS3PutObjectUrl}; this alias is retained for
+* pre-release callers that adopted the shorter name.
+*/
+async function presignPutObjectUrl(options) {
+	return await presignS3PutObjectUrl(options);
+}
+/**
+* Constructs a B2-native download URL using a token from `b2_get_download_authorization`.
+* This is not an S3 presigned URL.
+*
+* The token lifetime is fixed when `b2_get_download_authorization` creates the
+* token. `validDurationInSeconds` is retained only for compatibility with the
+* legacy `presignGetObjectUrl` helper's decorative `expires` query parameter;
+* changing it here does not shorten or extend access.
+* Because the returned URL carries a bearer token, `downloadUrl` must be an
+* HTTPS Backblaze download origin without userinfo, path, query, or fragment.
+*
+* @param downloadUrl - The B2 download URL from authorization (e.g., `https://f004.backblazeb2.com`).
+* @param bucketName - The bucket containing the file.
+* @param fileName - The file name (path) to download.
+* @param authorizationToken - A download authorization token from `b2_get_download_authorization`.
+* @param validDurationInSeconds - Compatibility-only value for the non-authoritative `expires` query.
+*
+* @returns The B2 native download-authorization URL string, not an S3 presigned URL.
+*/
+function createNativeDownloadAuthorizationUrl(downloadUrl, bucketName, fileName, authorizationToken, validDurationInSeconds = DEFAULT_NATIVE_DOWNLOAD_URL_EXPIRES_IN) {
+	return buildNativeDownloadAuthorizationUrl(downloadUrl, bucketName, fileName, authorizationToken, validDurationInSeconds, require_encoding.encodeFileName, require_validation.assertNativeDownloadFileName);
+}
+function deriveRequiredS3Region(endpoint) {
+	const region = deriveS3RegionFromEndpoint(endpoint);
+	if (region !== null) return region;
+	throw new Error(`Unable to derive B2 S3 region from endpoint "${require_url_redaction.redactUrlForError(endpoint, { invalidUrlLabel: "<invalid S3 endpoint URL>" })}". Pass an explicit \`region\` option before deploying custom or proxied endpoints.`);
+}
+function createSigV4PresignOptions(options) {
+	const clientConfig = createS3ClientConfig(options);
+	return {
+		endpoint: clientConfig.endpoint,
+		region: clientConfig.region,
+		accessKeyId: clientConfig.credentials.accessKeyId,
+		secretAccessKey: clientConfig.credentials.secretAccessKey,
+		bucketName: options.bucketName,
+		fileName: options.fileName,
+		...options.expiresIn !== void 0 ? { expiresIn: options.expiresIn } : {}
+	};
+}
+function normalizeContentLength(contentLength) {
+	if (!Number.isSafeInteger(contentLength) || contentLength < 0) throw new RangeError(`contentLength must be a non-negative safe integer; received ${String(contentLength)}.`);
+	return String(contentLength);
+}
+function normalizeValidDurationInSeconds(validDurationInSeconds) {
+	if (!Number.isSafeInteger(validDurationInSeconds) || validDurationInSeconds < 0) throw new RangeError(`validDurationInSeconds must be a non-negative safe integer; received ${String(validDurationInSeconds)}.`);
+	return validDurationInSeconds;
+}
+function assertNonEmptyStringOption(name, value) {
+	if (typeof value !== "string" || value.trim().length === 0) throw new TypeError(`${name} must be a non-empty string.`);
+}
+function assertSigV4CredentialScopeComponent(name, value) {
+	if (/[\s/]/u.test(value) || require_http.hasHttpHeaderControlCharacter(value)) throw new TypeError(`${name} must not contain whitespace, control characters, or "/" because it is embedded in the SigV4 credential scope.`);
+}
+function isTrustedUnsafeS3PresignOptIn(value) {
+	return value === trustedUnsafeS3PresignOptIn;
+}
+function buildNativeDownloadAuthorizationUrl(downloadUrl, bucketName, fileName, authorizationToken, validDurationInSeconds, encodeFileNameForUrl, assertFileName) {
+	const baseUrl = parseNativeDownloadBaseUrl(downloadUrl);
+	require_validation.assertSafeBucketName(bucketName);
+	assertFileName(fileName);
+	const expires = Math.floor(Date.now() / 1e3) + normalizeValidDurationInSeconds(validDurationInSeconds);
+	return `${baseUrl}/file/${encodeURIComponent(bucketName)}/${encodeFileNameForUrl(fileName)}?Authorization=${encodeURIComponent(authorizationToken)}&expires=${expires}`;
+}
+function parseNativeDownloadBaseUrl(downloadUrl) {
+	let base;
+	try {
+		base = new URL(downloadUrl);
+	} catch {
+		throw new TypeError(`Native download-authorization URLs require a valid https: downloadUrl; received "${require_url_redaction.redactUrlForError(downloadUrl, { invalidUrlLabel: "<invalid downloadUrl>" })}".`);
+	}
+	if (base.protocol !== "https:") throw new TypeError(`Native download-authorization URLs require an https: downloadUrl; received "${require_url_redaction.redactUrlForError(base)}".`);
+	if (base.username !== "" || base.password !== "") throw new TypeError("Native download-authorization URLs must not include userinfo.");
+	if (base.search !== "" || base.hash !== "") throw new TypeError("Native download-authorization URLs must not include query or fragment.");
+	if (base.pathname !== "" && base.pathname !== "/") throw new TypeError("Native download-authorization URLs must not include a path.");
+	if (!isTrustedNativeDownloadHost(base.hostname)) throw new TypeError(`Native download-authorization URLs require a Backblaze download host; received "${require_url_redaction.redactUrlForError(base)}".`);
+	return base.origin;
+}
+function normalizeMetadataHeaders(metadata) {
+	const headers = [];
+	const seenKeys = /* @__PURE__ */ new Set();
+	for (const [key, value] of Object.entries(metadata ?? {})) {
+		if (!HTTP_HEADER_TOKEN.test(key)) throw new TypeError(`metadata key "${key}" must be a non-empty valid HTTP header token.`);
+		if (typeof value !== "string") throw new TypeError(`metadata value for "${key}" must be a string.`);
+		const lowerKey = key.toLowerCase();
+		if (seenKeys.has(lowerKey)) throw new TypeError(`metadata key "${key}" must not differ only by case.`);
+		seenKeys.add(lowerKey);
+		headers.push([`x-amz-meta-${lowerKey}`, value]);
+	}
+	return headers;
+}
+function normalizeResponseExpires(responseExpires) {
+	if (!Number.isFinite(responseExpires.getTime())) throw new RangeError("responseExpires must be a valid Date.");
+	return responseExpires.toUTCString();
+}
+function assertSafeResponseOverride(name, value) {
+	assertSafeHeaderValue(name, value, "response header value");
+}
+function assertSafeQueryValue(name, value) {
+	if (require_http.hasHttpHeaderControlCharacter(value)) throw new TypeError(`${name} must not contain control characters because it becomes a query parameter.`);
+}
+function assertSafeHeaderValue(name, value, target) {
+	if (require_http.hasHttpHeaderControlCharacter(value)) throw new TypeError(`${name} must not contain control characters because it becomes a ${target}.`);
+}
+function assertSafeResponseContentType(contentType) {
+	assertNonExecutableContentType("responseContentType", contentType, "response header value", "allow-list a safe content type before signing response overrides");
+}
+function assertSafePutContentType(contentType) {
+	assertNonExecutableContentType("contentType", contentType, "stored object Content-Type", "pass allowBrowserExecutableContentType only when active content is intentional");
+}
+function assertSafeResponseContentDisposition(contentDisposition, allowInline) {
+	assertSafeResponseOverride("responseContentDisposition", contentDisposition);
+	const disposition = contentDisposition.split(";", 1)[0]?.trim().toLowerCase();
+	if (!allowInline && disposition === "inline") throw new TypeError("responseContentDisposition must not force inline rendering; use an attachment disposition for response overrides.");
+}
+function mediaTypeFor(contentType) {
+	return contentType.split(";", 1)[0]?.trim().toLowerCase() ?? "";
+}
+function assertSafeContentTypeValue(name, contentType, target) {
+	assertSafeHeaderValue(name, contentType, target);
+	const mediaType = mediaTypeFor(contentType);
+	if (mediaType.length === 0) throw new TypeError(`${name} must include a non-empty media type.`);
+	if (!HTTP_MEDIA_TYPE.test(mediaType)) throw new TypeError(`${name} must include a valid media type.`);
+	return mediaType;
+}
+function assertNonExecutableContentType(name, contentType, target, guidance) {
+	const mediaType = assertSafeContentTypeValue(name, contentType, target);
+	if (isBrowserExecutableContentType(mediaType)) throw new TypeError(`${name} "${mediaType}" can execute in browsers; ${guidance}.`);
+}
+function isBrowserExecutableContentType(mediaType) {
+	return BROWSER_EXECUTABLE_CONTENT_TYPES.has(mediaType) || mediaType.endsWith("+xml");
+}
+function isTrustedNativeDownloadHost(hostname) {
+	return TRUSTED_NATIVE_DOWNLOAD_HOST_SUFFIXES.some((suffix) => require_url_guard.hostMatchesAllowedSuffix(hostname, suffix));
+}
+//#endregion
+exports.createNativeDownloadAuthorizationUrl = createNativeDownloadAuthorizationUrl;
 exports.createS3ClientConfig = createS3ClientConfig;
+exports.deriveS3RegionFromEndpoint = deriveS3RegionFromEndpoint;
 exports.presignGetObjectUrl = presignGetObjectUrl;
-//# sourceMappingURL=index.cjs.map
+exports.presignPutObjectUrl = presignPutObjectUrl;
+exports.presignS3GetObjectUrl = presignS3GetObjectUrl;
+exports.presignS3PutObjectUrl = presignS3PutObjectUrl;
+exports.trustedUnsafeS3PresignOptIn = trustedUnsafeS3PresignOptIn;
+
+//# sourceMappingURL=index.cjs.map