@backblaze-labs/b2-sdk 0.1.0

package/dist/raw/index.cjs

@@ -0,0 +1,600 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const normalize = require("../util/normalize.cjs");
+const encoding = require("./encoding.cjs");
+const encryption = require("../types/encryption.cjs");
+class RawClient {
+  /** @internal */
+  transport;
+  /**
+   * Creates a new RawClient with the given transport.
+   * @param options - The constructor configuration.
+   */
+  constructor(options) {
+    this.transport = options.transport;
+  }
+  // --- Auth ---
+  /**
+   * Calls {@link https://www.backblaze.com/apidocs/b2-authorize-account | b2_authorize_account}.
+   * @param applicationKeyId - The application key ID for authentication.
+   * @param applicationKey - The application key secret.
+   * @param realmUrl - The B2 realm URL to authenticate against.
+   *
+   * @returns The authorization response with API URLs and credentials.
+   */
+  async authorizeAccount(applicationKeyId, applicationKey, realmUrl = "https://api.backblazeb2.com") {
+    const response = await this.transport.send({
+      url: `${realmUrl}/b2api/v3/b2_authorize_account`,
+      method: "GET",
+      headers: {
+        Authorization: `Basic ${btoa(`${applicationKeyId}:${applicationKey}`)}`
+      }
+    });
+    return response.json();
+  }
+  // --- Buckets ---
+  /**
+   * Calls {@link https://www.backblaze.com/apidocs/b2-create-bucket | b2_create_bucket}.
+   * @param apiUrl - The B2 API base URL.
+   * @param authToken - The authorization token.
+   * @param request - The API request parameters.
+   *
+   * @returns The created bucket metadata.
+   */
+  async createBucket(apiUrl, authToken, request) {
+    return this.postJson(apiUrl, authToken, "b2_create_bucket", request);
+  }
+  /**
+   * Calls {@link https://www.backblaze.com/apidocs/b2-delete-bucket | b2_delete_bucket}.
+   * @param apiUrl - The B2 API base URL.
+   * @param authToken - The authorization token.
+   * @param request - The API request parameters.
+   *
+   * @returns The deleted bucket metadata.
+   */
+  async deleteBucket(apiUrl, authToken, request) {
+    return this.postJson(apiUrl, authToken, "b2_delete_bucket", request);
+  }
+  /**
+   * Calls {@link https://www.backblaze.com/apidocs/b2-list-buckets | b2_list_buckets}.
+   * @param apiUrl - The B2 API base URL.
+   * @param authToken - The authorization token.
+   * @param request - The API request parameters.
+   *
+   * @returns The list of matching buckets.
+   */
+  async listBuckets(apiUrl, authToken, request) {
+    return this.postJson(apiUrl, authToken, "b2_list_buckets", request);
+  }
+  /**
+   * Calls {@link https://www.backblaze.com/apidocs/b2-update-bucket | b2_update_bucket}.
+   * @param apiUrl - The B2 API base URL.
+   * @param authToken - The authorization token.
+   * @param request - The API request parameters.
+   *
+   * @returns The updated bucket metadata.
+   */
+  async updateBucket(apiUrl, authToken, request) {
+    return this.postJson(apiUrl, authToken, "b2_update_bucket", request);
+  }
+  // --- Files ---
+  /**
+   * Calls {@link https://www.backblaze.com/apidocs/b2-get-upload-url | b2_get_upload_url}.
+   * @param apiUrl - The B2 API base URL.
+   * @param authToken - The authorization token.
+   * @param request - The API request parameters.
+   *
+   * @returns The upload URL and authorization token.
+   */
+  async getUploadUrl(apiUrl, authToken, request) {
+    return this.postJson(apiUrl, authToken, "b2_get_upload_url", request);
+  }
+  /**
+   * Calls {@link https://www.backblaze.com/apidocs/b2-upload-file | b2_upload_file}.
+   *
+   * Unlike most methods, this posts directly to the `uploadUrl` obtained
+   * from {@link getUploadUrl} rather than the API URL.
+   * @param uploadUrl - The upload endpoint URL.
+   * @param headers - The request headers including authorization and content metadata.
+   * @param body - The file data to upload.
+   * @param signal - An optional abort signal for cancellation.
+   *
+   * @returns The uploaded file version metadata.
+   */
+  async uploadFile(uploadUrl, headers, body, signal) {
+    const reqHeaders = {
+      Authorization: headers.authorization,
+      "X-Bz-File-Name": encoding.encodeFileName(headers.fileName),
+      "Content-Type": headers.contentType,
+      "Content-Length": String(headers.contentLength),
+      "X-Bz-Content-Sha1": headers.contentSha1,
+      ...encoding.buildFileInfoHeaders(headers.fileInfo)
+    };
+    if (headers.lastModifiedMillis !== void 0) {
+      reqHeaders["X-Bz-Info-src_last_modified_millis"] = String(headers.lastModifiedMillis);
+    }
+    if (headers.contentDisposition) {
+      reqHeaders["X-Bz-Info-b2-content-disposition"] = headers.contentDisposition;
+    }
+    if (headers.contentLanguage) {
+      reqHeaders["X-Bz-Info-b2-content-language"] = headers.contentLanguage;
+    }
+    if (headers.expires) {
+      reqHeaders["X-Bz-Info-b2-expires"] = headers.expires;
+    }
+    if (headers.cacheControl) {
+      reqHeaders["X-Bz-Info-b2-cache-control"] = headers.cacheControl;
+    }
+    if (headers.contentEncoding) {
+      reqHeaders["X-Bz-Info-b2-content-encoding"] = headers.contentEncoding;
+    }
+    applyEncryptionHeaders(reqHeaders, headers.serverSideEncryption);
+    applyRetentionHeaders(reqHeaders, headers.fileRetention);
+    applyLegalHoldHeader(reqHeaders, headers.legalHold);
+    const response = await this.transport.send({
+      url: uploadUrl,
+      method: "POST",
+      headers: reqHeaders,
+      body,
+      ...signal !== void 0 ? { signal } : {}
+    });
+    return normalize.normalizeFileVersionSha1(await response.json());
+  }
+  /**
+   * Calls {@link https://www.backblaze.com/apidocs/b2-list-file-names | b2_list_file_names}.
+   * @param apiUrl - The B2 API base URL.
+   * @param authToken - The authorization token.
+   * @param request - The API request parameters.
+   *
+   * @returns The list of file names and optional continuation token.
+   */
+  async listFileNames(apiUrl, authToken, request) {
+    return normalize.normalizeFileVersionListSha1(
+      await this.postJson(apiUrl, authToken, "b2_list_file_names", request)
+    );
+  }
+  /**
+   * Calls {@link https://www.backblaze.com/apidocs/b2-list-file-versions | b2_list_file_versions}.
+   * @param apiUrl - The B2 API base URL.
+   * @param authToken - The authorization token.
+   * @param request - The API request parameters.
+   *
+   * @returns The list of file versions and optional continuation token.
+   */
+  async listFileVersions(apiUrl, authToken, request) {
+    return normalize.normalizeFileVersionListSha1(
+      await this.postJson(
+        apiUrl,
+        authToken,
+        "b2_list_file_versions",
+        request
+      )
+    );
+  }
+  /**
+   * Calls {@link https://www.backblaze.com/apidocs/b2-get-file-info | b2_get_file_info}.
+   * @param apiUrl - The B2 API base URL.
+   * @param authToken - The authorization token.
+   * @param request - The API request parameters.
+   *
+   * @returns The file version metadata.
+   */
+  async getFileInfo(apiUrl, authToken, request) {
+    return normalize.normalizeFileVersionSha1(
+      await this.postJson(apiUrl, authToken, "b2_get_file_info", request)
+    );
+  }
+  /**
+   * Calls {@link https://www.backblaze.com/apidocs/b2-hide-file | b2_hide_file}.
+   * @param apiUrl - The B2 API base URL.
+   * @param authToken - The authorization token.
+   * @param request - The API request parameters.
+   *
+   * @returns The hidden file version metadata.
+   */
+  async hideFile(apiUrl, authToken, request) {
+    return normalize.normalizeFileVersionSha1(
+      await this.postJson(apiUrl, authToken, "b2_hide_file", request)
+    );
+  }
+  /**
+   * Calls {@link https://www.backblaze.com/apidocs/b2-delete-file-version | b2_delete_file_version}.
+   * @param apiUrl - The B2 API base URL.
+   * @param authToken - The authorization token.
+   * @param request - The API request parameters.
+   *
+   * @returns The deleted file version identifier.
+   */
+  async deleteFileVersion(apiUrl, authToken, request) {
+    return this.postJson(
+      apiUrl,
+      authToken,
+      "b2_delete_file_version",
+      request
+    );
+  }
+  /**
+   * Calls {@link https://www.backblaze.com/apidocs/b2-copy-file | b2_copy_file}.
+   * @param apiUrl - The B2 API base URL.
+   * @param authToken - The authorization token.
+   * @param request - The API request parameters.
+   *
+   * @returns The copied file version metadata.
+   */
+  async copyFile(apiUrl, authToken, request) {
+    return normalize.normalizeFileVersionSha1(
+      await this.postJson(apiUrl, authToken, "b2_copy_file", request)
+    );
+  }
+  /**
+   * Calls {@link https://www.backblaze.com/apidocs/b2-copy-part | b2_copy_part}.
+   * @param apiUrl - The B2 API base URL.
+   * @param authToken - The authorization token.
+   * @param request - The API request parameters.
+   *
+   * @returns The copied part metadata.
+   */
+  async copyPart(apiUrl, authToken, request) {
+    return this.postJson(apiUrl, authToken, "b2_copy_part", request);
+  }
+  // --- Large Files ---
+  /**
+   * Calls {@link https://www.backblaze.com/apidocs/b2-start-large-file | b2_start_large_file}.
+   * @param apiUrl - The B2 API base URL.
+   * @param authToken - The authorization token.
+   * @param request - The API request parameters.
+   *
+   * @returns The started large file metadata with file ID.
+   */
+  async startLargeFile(apiUrl, authToken, request) {
+    return this.postJson(apiUrl, authToken, "b2_start_large_file", request);
+  }
+  /**
+   * Calls {@link https://www.backblaze.com/apidocs/b2-get-upload-part-url | b2_get_upload_part_url}.
+   * @param apiUrl - The B2 API base URL.
+   * @param authToken - The authorization token.
+   * @param request - The API request parameters.
+   *
+   * @returns The upload part URL and authorization token.
+   */
+  async getUploadPartUrl(apiUrl, authToken, request) {
+    return this.postJson(
+      apiUrl,
+      authToken,
+      "b2_get_upload_part_url",
+      request
+    );
+  }
+  /**
+   * Calls {@link https://www.backblaze.com/apidocs/b2-upload-part | b2_upload_part}.
+   *
+   * Posts directly to the `uploadUrl` obtained from {@link getUploadPartUrl}
+   * rather than the API URL.
+   * @param uploadUrl - The upload endpoint URL.
+   * @param headers - The request headers including authorization and content metadata.
+   * @param body - The file data to upload.
+   * @param signal - An optional abort signal for cancellation.
+   *
+   * @returns The uploaded part metadata.
+   */
+  async uploadPart(uploadUrl, headers, body, signal) {
+    const reqHeaders = {
+      Authorization: headers.authorization,
+      "X-Bz-Part-Number": String(headers.partNumber),
+      "Content-Length": String(headers.contentLength),
+      "X-Bz-Content-Sha1": headers.contentSha1
+    };
+    applyEncryptionHeaders(reqHeaders, headers.serverSideEncryption);
+    const response = await this.transport.send({
+      url: uploadUrl,
+      method: "POST",
+      headers: reqHeaders,
+      body,
+      ...signal !== void 0 ? { signal } : {}
+    });
+    return response.json();
+  }
+  /**
+   * Calls {@link https://www.backblaze.com/apidocs/b2-finish-large-file | b2_finish_large_file}.
+   * @param apiUrl - The B2 API base URL.
+   * @param authToken - The authorization token.
+   * @param request - The API request parameters.
+   *
+   * @returns The completed file version metadata.
+   */
+  async finishLargeFile(apiUrl, authToken, request) {
+    return normalize.normalizeFileVersionSha1(
+      await this.postJson(apiUrl, authToken, "b2_finish_large_file", request)
+    );
+  }
+  /**
+   * Calls {@link https://www.backblaze.com/apidocs/b2-cancel-large-file | b2_cancel_large_file}.
+   * @param apiUrl - The B2 API base URL.
+   * @param authToken - The authorization token.
+   * @param request - The API request parameters.
+   *
+   * @returns The cancelled large file metadata.
+   */
+  async cancelLargeFile(apiUrl, authToken, request) {
+    return this.postJson(
+      apiUrl,
+      authToken,
+      "b2_cancel_large_file",
+      request
+    );
+  }
+  /**
+   * Calls {@link https://www.backblaze.com/apidocs/b2-list-unfinished-large-files | b2_list_unfinished_large_files}.
+   * @param apiUrl - The B2 API base URL.
+   * @param authToken - The authorization token.
+   * @param request - The API request parameters.
+   *
+   * @returns The list of unfinished large files and optional continuation token.
+   */
+  async listUnfinishedLargeFiles(apiUrl, authToken, request) {
+    return this.postJson(
+      apiUrl,
+      authToken,
+      "b2_list_unfinished_large_files",
+      request
+    );
+  }
+  /**
+   * Calls {@link https://www.backblaze.com/apidocs/b2-list-parts | b2_list_parts}.
+   * @param apiUrl - The B2 API base URL.
+   * @param authToken - The authorization token.
+   * @param request - The API request parameters.
+   *
+   * @returns The list of uploaded parts and optional continuation token.
+   */
+  async listParts(apiUrl, authToken, request) {
+    return this.postJson(apiUrl, authToken, "b2_list_parts", request);
+  }
+  // --- Downloads ---
+  /**
+   * Calls {@link https://www.backblaze.com/apidocs/b2-download-file-by-id | b2_download_file_by_id}.
+   * @param downloadUrl - The B2 download base URL.
+   * @param authToken - The authorization token.
+   * @param fileId - The unique identifier of the file to download.
+   * @param options - Optional download parameters for range requests and cancellation.
+   *
+   * @returns The response headers, streaming body, and HTTP status code.
+   */
+  async downloadFileById(downloadUrl, authToken, fileId, options) {
+    const headers = buildDownloadRequestHeaders(authToken, options);
+    const url = appendDownloadOverrides(
+      `${downloadUrl}/b2api/v3/b2_download_file_by_id?fileId=${encodeURIComponent(fileId)}`,
+      options
+    );
+    const response = await this.transport.send({
+      url,
+      method: options?.method ?? "GET",
+      headers,
+      ...options?.signal !== void 0 ? { signal: options.signal } : {}
+    });
+    return { headers: response.headers, body: response.body, status: response.status };
+  }
+  /**
+   * Calls {@link https://www.backblaze.com/apidocs/b2-download-file-by-name | b2_download_file_by_name}.
+   * @param downloadUrl - The B2 download base URL.
+   * @param authToken - The authorization token.
+   * @param bucketName - The name of the bucket containing the file.
+   * @param fileName - The name of the file to download.
+   * @param options - Optional download parameters for range requests and cancellation.
+   *
+   * @returns The response headers, streaming body, and HTTP status code.
+   */
+  async downloadFileByName(downloadUrl, authToken, bucketName, fileName, options) {
+    const headers = buildDownloadRequestHeaders(authToken, options);
+    const url = appendDownloadOverrides(
+      `${downloadUrl}/file/${encodeURIComponent(bucketName)}/${encoding.encodeFileName(fileName)}`,
+      options
+    );
+    const response = await this.transport.send({
+      url,
+      method: options?.method ?? "GET",
+      headers,
+      ...options?.signal !== void 0 ? { signal: options.signal } : {}
+    });
+    return { headers: response.headers, body: response.body, status: response.status };
+  }
+  /**
+   * Calls {@link https://www.backblaze.com/apidocs/b2-get-download-authorization | b2_get_download_authorization}.
+   * @param apiUrl - The B2 API base URL.
+   * @param authToken - The current session authorization token.
+   * @param request - The API request parameters.
+   *
+   * @returns The download authorization token for the specified file prefix.
+   */
+  async getDownloadAuthorization(apiUrl, authToken, request) {
+    return this.postJson(
+      apiUrl,
+      authToken,
+      "b2_get_download_authorization",
+      request
+    );
+  }
+  // --- Keys ---
+  /**
+   * Calls {@link https://www.backblaze.com/apidocs/b2-create-key | b2_create_key}.
+   * @param apiUrl - The B2 API base URL.
+   * @param authToken - The authorization token.
+   * @param request - The API request parameters.
+   *
+   * @returns The newly created application key with secret.
+   */
+  async createKey(apiUrl, authToken, request) {
+    return this.postJson(apiUrl, authToken, "b2_create_key", request);
+  }
+  /**
+   * Calls {@link https://www.backblaze.com/apidocs/b2-list-keys | b2_list_keys}.
+   * @param apiUrl - The B2 API base URL.
+   * @param authToken - The authorization token.
+   * @param request - The API request parameters.
+   *
+   * @returns The list of application keys and optional continuation token.
+   */
+  async listKeys(apiUrl, authToken, request) {
+    return this.postJson(apiUrl, authToken, "b2_list_keys", request);
+  }
+  /**
+   * Calls {@link https://www.backblaze.com/apidocs/b2-delete-key | b2_delete_key}.
+   * @param apiUrl - The B2 API base URL.
+   * @param authToken - The authorization token.
+   * @param request - The API request parameters.
+   *
+   * @returns The deleted application key metadata.
+   */
+  async deleteKey(apiUrl, authToken, request) {
+    return this.postJson(apiUrl, authToken, "b2_delete_key", request);
+  }
+  // --- Retention / Legal Hold ---
+  /**
+   * Calls {@link https://www.backblaze.com/apidocs/b2-update-file-retention | b2_update_file_retention}.
+   * @param apiUrl - The B2 API base URL.
+   * @param authToken - The authorization token.
+   * @param request - The API request parameters.
+   *
+   * @returns The updated file retention settings.
+   */
+  async updateFileRetention(apiUrl, authToken, request) {
+    return this.postJson(
+      apiUrl,
+      authToken,
+      "b2_update_file_retention",
+      request
+    );
+  }
+  /**
+   * Calls {@link https://www.backblaze.com/apidocs/b2-update-file-legal-hold | b2_update_file_legal_hold}.
+   * @param apiUrl - The B2 API base URL.
+   * @param authToken - The authorization token.
+   * @param request - The API request parameters.
+   *
+   * @returns The updated file legal hold status.
+   */
+  async updateFileLegalHold(apiUrl, authToken, request) {
+    return this.postJson(
+      apiUrl,
+      authToken,
+      "b2_update_file_legal_hold",
+      request
+    );
+  }
+  // --- Notifications ---
+  /**
+   * Calls {@link https://www.backblaze.com/apidocs/b2-get-bucket-notification-rules | b2_get_bucket_notification_rules}.
+   * @param apiUrl - The B2 API base URL.
+   * @param authToken - The authorization token.
+   * @param request - The API request parameters.
+   *
+   * @returns The configured event notification rules for the specified bucket.
+   */
+  async getBucketNotificationRules(apiUrl, authToken, request) {
+    return this.postJson(
+      apiUrl,
+      authToken,
+      "b2_get_bucket_notification_rules",
+      request
+    );
+  }
+  /**
+   * Calls {@link https://www.backblaze.com/apidocs/b2-set-bucket-notification-rules | b2_set_bucket_notification_rules}.
+   * @param apiUrl - The B2 API base URL.
+   * @param authToken - The authorization token.
+   * @param request - The API request parameters.
+   *
+   * @returns The updated bucket notification rules.
+   */
+  async setBucketNotificationRules(apiUrl, authToken, request) {
+    return this.postJson(
+      apiUrl,
+      authToken,
+      "b2_set_bucket_notification_rules",
+      request
+    );
+  }
+  // --- Internal ---
+  /**
+   * Sends a JSON POST request to the specified B2 API endpoint.
+   * @param apiUrl - The B2 API base URL.
+   * @param authToken - The authorization token.
+   * @param endpoint - The B2 API endpoint name.
+   * @param body - The JSON request body.
+   *
+   * @returns The parsed JSON response.
+   */
+  async postJson(apiUrl, authToken, endpoint, body) {
+    const response = await this.transport.send({
+      url: `${apiUrl}/b2api/v3/${endpoint}`,
+      method: "POST",
+      headers: {
+        Authorization: authToken,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(body)
+    });
+    return response.json();
+  }
+}
+function applyEncryptionHeaders(headers, encryption$1) {
+  if (!encryption$1 || encryption$1.mode === encryption.EncryptionMode.None) return;
+  if (encryption$1.mode === encryption.EncryptionMode.SseB2) {
+    headers["X-Bz-Server-Side-Encryption"] = encryption.EncryptionAlgorithm.Aes256;
+  } else if (encryption$1.mode === encryption.EncryptionMode.SseC) {
+    headers["X-Bz-Server-Side-Encryption-Customer-Algorithm"] = encryption.EncryptionAlgorithm.Aes256;
+    headers["X-Bz-Server-Side-Encryption-Customer-Key"] = encryption$1.customerKey;
+    headers["X-Bz-Server-Side-Encryption-Customer-Key-Md5"] = encryption$1.customerKeyMd5;
+  }
+}
+const DOWNLOAD_OVERRIDE_PARAMS = [
+  "b2ContentDisposition",
+  "b2ContentLanguage",
+  "b2ContentEncoding",
+  "b2ContentType",
+  "b2CacheControl",
+  "b2Expires"
+];
+function buildDownloadRequestHeaders(authToken, options) {
+  const headers = { Authorization: authToken };
+  if (options?.range) headers["Range"] = options.range;
+  if (options?.serverSideEncryption) {
+    applyEncryptionHeaders(headers, {
+      mode: encryption.EncryptionMode.SseC,
+      ...options.serverSideEncryption
+    });
+  }
+  return headers;
+}
+function appendDownloadOverrides(url, options) {
+  if (!options) return url;
+  const params = [];
+  for (const key of DOWNLOAD_OVERRIDE_PARAMS) {
+    const value = options[key];
+    if (value !== void 0) {
+      params.push(`${key}=${encodeURIComponent(value)}`);
+    }
+  }
+  if (params.length === 0) return url;
+  const separator = url.includes("?") ? "&" : "?";
+  return `${url}${separator}${params.join("&")}`;
+}
+function applyRetentionHeaders(headers, retention) {
+  if (!retention) return;
+  if (retention.mode) {
+    headers["X-Bz-File-Retention-Mode"] = retention.mode;
+  }
+  if (retention.retainUntilTimestamp) {
+    headers["X-Bz-File-Retention-Retain-Until-Timestamp"] = String(retention.retainUntilTimestamp);
+  }
+}
+function applyLegalHoldHeader(headers, legalHold) {
+  if (!legalHold) return;
+  headers["X-Bz-File-Legal-Hold"] = legalHold;
+}
+exports.buildFileInfoHeaders = encoding.buildFileInfoHeaders;
+exports.decodeFileName = encoding.decodeFileName;
+exports.encodeFileName = encoding.encodeFileName;
+exports.parseFileInfoHeaders = encoding.parseFileInfoHeaders;
+exports.RawClient = RawClient;
+//# sourceMappingURL=index.cjs.map