@backblaze-labs/b2-sdk 0.1.0

package/dist/bucket.cjs

@@ -0,0 +1,789 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const large$1 = require("./copy/large.cjs");
+const single$1 = require("./download/single.cjs");
+const object = require("./object.cjs");
+const ids = require("./types/ids.cjs");
+const concurrency = require("./upload/concurrency.cjs");
+const large = require("./upload/large.cjs");
+const single = require("./upload/single.cjs");
+const defaults = require("./util/defaults.cjs");
+const paginator = require("./util/paginator.cjs");
+const toError = require("./util/to-error.cjs");
+class Bucket {
+  /** Unique identifier for this bucket. */
+  id;
+  /** Human-readable bucket name. */
+  name;
+  /** Full bucket metadata as returned by the B2 API. */
+  info;
+  client;
+  /**
+   * @param client - The parent B2Client instance.
+   * @param info - The bucket metadata from the API.
+   *
+   * @internal
+   */
+  constructor(client, info) {
+    this.client = client;
+    this.info = info;
+    this.id = info.bucketId;
+    this.name = info.bucketName;
+  }
+  /**
+   * Returns a {@link B2Object} handle for a specific file name in this bucket.
+   * @param fileName - The file path within the bucket.
+   *
+   * @returns A B2Object handle bound to this bucket and file name.
+   */
+  file(fileName) {
+    return new object.B2Object(this.client, this, fileName);
+  }
+  /**
+   * Uploads a file to this bucket. Automatically uses multipart upload for files
+   * larger than the recommended part size.
+   * @param options - Upload configuration including file name, source data, and optional settings.
+   *
+   * @returns Metadata for the uploaded file version.
+   */
+  async upload(options) {
+    const recommendedPartSize = this.client.accountInfo.getRecommendedPartSize();
+    const isLarge = options.source.size > recommendedPartSize;
+    if (isLarge) {
+      return large.uploadLargeFile(this.client.raw, this.client.accountInfo, {
+        bucketId: this.id,
+        ...options
+      });
+    }
+    const { resume: _resume, resumeFileId: _resumeFileId, ...smallOptions } = options;
+    return single.uploadSmallFile(this.client.raw, this.client.accountInfo, {
+      bucketId: this.id,
+      ...smallOptions
+    });
+  }
+  /**
+   * Downloads a file from this bucket by name. Pass `method: 'HEAD'` in
+   * `options` to fetch only the response headers (file metadata) without
+   * streaming the body.
+   * @param fileName - The file name (path) to download.
+   * @param options - Optional method, range, SSE-C decryption, response-header overrides, and abort signal.
+   *
+   * @returns The download result containing response headers and a readable body stream.
+   */
+  async download(fileName, options) {
+    return single$1.downloadByName(this.client.raw, this.client.accountInfo, {
+      bucketName: this.name,
+      fileName,
+      ...options
+    });
+  }
+  /**
+   * Fetches the response headers (file metadata) for a file via HTTP
+   * HEAD. Returns a body-less result so callers never have to drain
+   * the (logically empty) HEAD body themselves.
+   *
+   * Use this for metadata-only checks like "does this file exist", "what
+   * is its current SHA-1", "what is its Content-Length". For full file
+   * retrieval use {@link Bucket.download}.
+   *
+   * @param fileName - The file name (path) to inspect.
+   * @param options - Optional range, SSE-C decryption, response-header
+   *   overrides, and abort signal. Same shape as {@link Bucket.download}'s
+   *   options minus `method` (always HEAD) and `onProgress` (no body).
+   *
+   * @returns Parsed download headers (content type, SHA-1, file info, etc.).
+   *
+   * @example
+   * ```ts
+   * const { headers } = await bucket.head('photos/2026/sunset.jpg')
+   * console.log(headers.contentLength, headers.contentSha1)
+   * ```
+   */
+  async head(fileName, options) {
+    return single$1.headByName(this.client.raw, this.client.accountInfo, {
+      bucketName: this.name,
+      fileName,
+      ...options
+    });
+  }
+  /**
+   * Lists file names in this bucket (most recent versions only).
+   * @param options - Optional filtering and pagination settings.
+   *
+   * @returns A page of file versions with an optional continuation token.
+   */
+  async listFileNames(options) {
+    return this.client.raw.listFileNames(
+      this.client.accountInfo.getApiUrl(),
+      this.client.accountInfo.getAuthToken(),
+      {
+        bucketId: this.id,
+        ...options?.startFileName !== void 0 ? { startFileName: options.startFileName } : {},
+        ...options?.pageSize !== void 0 ? { maxFileCount: options.pageSize } : {},
+        ...options?.prefix !== void 0 ? { prefix: options.prefix } : {},
+        ...options?.delimiter !== void 0 ? { delimiter: options.delimiter } : {}
+      }
+    );
+  }
+  /**
+   * Lists all file versions in this bucket, including hidden files.
+   * @param options - Optional filtering and pagination settings.
+   *
+   * @returns A page of file versions with an optional continuation token.
+   */
+  async listFileVersions(options) {
+    return this.client.raw.listFileVersions(
+      this.client.accountInfo.getApiUrl(),
+      this.client.accountInfo.getAuthToken(),
+      {
+        bucketId: this.id,
+        ...options?.startFileName !== void 0 ? { startFileName: options.startFileName } : {},
+        ...options?.startFileId !== void 0 ? { startFileId: options.startFileId } : {},
+        ...options?.pageSize !== void 0 ? { maxFileCount: options.pageSize } : {},
+        ...options?.prefix !== void 0 ? { prefix: options.prefix } : {},
+        ...options?.delimiter !== void 0 ? { delimiter: options.delimiter } : {}
+      }
+    );
+  }
+  /**
+   * Async iterator that yields the latest visible version of every file in
+   * the bucket, automatically handling pagination via `listFileNames`.
+   *
+   * Hidden files (those whose latest version is a hide marker) are NOT
+   * yielded by this iterator. Use {@link paginateFileVersions} when you
+   * need full version history.
+   *
+   * @param options - Filter + pagination + abort options. `pageSize` is
+   *   forwarded to `b2_list_file_names`'s `maxFileCount` (default 1000,
+   *   B2-capped at 10000).
+   *
+   * @returns An async iterable of {@link FileVersion} entries.
+   *
+   * @example
+   * ```ts
+   * for await (const file of bucket.paginateFileNames({ prefix: 'photos/' })) {
+   *   console.log(file.fileName, file.contentLength)
+   * }
+   * ```
+   */
+  paginateFileNames(options) {
+    return paginator.paginateItems(
+      async (cursor) => {
+        const resp = await this.listFileNames({
+          pageSize: options?.pageSize ?? defaults.DEFAULT_PAGE_SIZE,
+          ...cursor !== void 0 ? { startFileName: cursor } : {},
+          ...options?.prefix !== void 0 ? { prefix: options.prefix } : {},
+          ...options?.delimiter !== void 0 ? { delimiter: options.delimiter } : {}
+        });
+        return { page: resp, nextCursor: resp.nextFileName ?? void 0 };
+      },
+      // Real B2 surfaces hide markers as rows in `b2_list_file_names`. This
+      // iterator's documented contract is "latest VISIBLE version", so we
+      // drop hide-action rows here. Callers who need full history should
+      // use `paginateFileVersions`.
+      (page) => page.files.filter((f) => f.action !== "hide"),
+      options?.signal
+    );
+  }
+  /**
+   * Async iterator that yields every version of every file in the bucket,
+   * including hidden files and historical versions, automatically handling
+   * pagination via `listFileVersions`.
+   *
+   * The two-cursor `(nextFileName, nextFileId)` continuation that the raw
+   * endpoint exposes is threaded internally; callers iterate flat.
+   *
+   * @param options - Filter + pagination + abort options.
+   *
+   * @returns An async iterable of {@link FileVersion} entries.
+   */
+  paginateFileVersions(options) {
+    return paginator.paginateItems(
+      async (cursor) => {
+        const resp = await this.listFileVersions({
+          pageSize: options?.pageSize ?? defaults.DEFAULT_PAGE_SIZE,
+          ...cursor !== void 0 ? { startFileName: cursor.fileName } : {},
+          ...cursor?.fileId !== void 0 ? { startFileId: cursor.fileId } : {},
+          ...options?.prefix !== void 0 ? { prefix: options.prefix } : {},
+          ...options?.delimiter !== void 0 ? { delimiter: options.delimiter } : {}
+        });
+        const nextCursor = resp.nextFileName !== null ? { fileName: resp.nextFileName, fileId: resp.nextFileId ?? void 0 } : void 0;
+        return { page: resp, nextCursor };
+      },
+      (page) => page.files,
+      options?.signal
+    );
+  }
+  /**
+   * Async iterator that yields every unfinished large file in the bucket,
+   * automatically handling pagination via `listUnfinishedLargeFiles`.
+   *
+   * Useful for janitorial scripts that want to inspect or cancel abandoned
+   * multipart uploads (typically followed by {@link cancelLargeFile} on
+   * the underlying raw client).
+   *
+   * @param options - Filter + pagination + abort options. `pageSize` is
+   *   B2-capped at 100 for this endpoint.
+   *
+   * @returns An async iterable of unfinished-large-file metadata entries.
+   */
+  paginateUnfinishedLargeFiles(options) {
+    return paginator.paginateItems(
+      async (cursor) => {
+        const resp = await this.listUnfinishedLargeFiles({
+          pageSize: options?.pageSize ?? 100,
+          ...cursor !== void 0 ? { startFileId: cursor } : {},
+          ...options?.namePrefix !== void 0 ? { namePrefix: options.namePrefix } : {}
+        });
+        return { page: resp, nextCursor: resp.nextFileId ?? void 0 };
+      },
+      (page) => page.files,
+      options?.signal
+    );
+  }
+  /**
+   * Async iterator that yields every uploaded part for a specific large
+   * file, automatically handling pagination via `listParts`.
+   *
+   * @param largeFileId - The unfinished large file to enumerate parts of.
+   * @param options - Pagination + abort options. `pageSize` is B2-capped
+   *   at 1000 for this endpoint; the default is 1000.
+   *
+   * @returns An async iterable of {@link PartInfo} entries.
+   */
+  paginateParts(largeFileId, options) {
+    return paginator.paginateItems(
+      async (cursor) => {
+        const resp = await this.client.raw.listParts(
+          this.client.accountInfo.getApiUrl(),
+          this.client.accountInfo.getAuthToken(),
+          {
+            fileId: largeFileId,
+            maxPartCount: options?.pageSize ?? defaults.DEFAULT_PAGE_SIZE,
+            ...cursor !== void 0 ? { startPartNumber: cursor } : {}
+          }
+        );
+        return { page: resp, nextCursor: resp.nextPartNumber ?? void 0 };
+      },
+      (page) => page.parts,
+      options?.signal
+    );
+  }
+  /**
+   * Looks up the latest visible version of a file by name.
+   * Uses `listFileNames` under the hood; returns `null` when the file does not
+   * exist or its latest version is a hide marker.
+   * @param fileName - The exact file path to look up.
+   *
+   * @returns The latest {@link FileVersion}, or `null` if not found.
+   */
+  async getFileInfoByName(fileName) {
+    const resp = await this.listFileNames({ prefix: fileName, pageSize: 1 });
+    const match = resp.files.find((f) => f.fileName === fileName);
+    if (!match || match.action === "hide") return null;
+    return match;
+  }
+  /**
+   * Removes the latest hide marker for a file, restoring visibility of the
+   * previous upload. Returns the deleted hide marker, or `null` if there was
+   * no hide marker to remove (file is already visible or does not exist).
+   * @param fileName - The file path to unhide.
+   *
+   * @returns The deleted hide marker version, or `null` if nothing was hidden.
+   */
+  async unhideFile(fileName) {
+    const resp = await this.listFileVersions({ prefix: fileName, pageSize: 100 });
+    const versions = resp.files.filter((f) => f.fileName === fileName);
+    if (versions.length === 0) return null;
+    const latest = versions[0];
+    if (!latest || latest.action !== "hide") return null;
+    await this.deleteFileVersion(fileName, latest.fileId);
+    return latest;
+  }
+  /**
+   * Hides a file by creating a hide marker. The file remains in version history but is no longer visible in `listFileNames`.
+   * @param fileName - The file path to hide.
+   *
+   * @returns Metadata for the newly created hide marker.
+   */
+  async hideFile(fileName) {
+    return this.client.raw.hideFile(
+      this.client.accountInfo.getApiUrl(),
+      this.client.accountInfo.getAuthToken(),
+      { bucketId: this.id, fileName }
+    );
+  }
+  /**
+   * Permanently deletes a specific file version. Both file name and file ID are required.
+   *
+   * If the file is under Object Lock retention, B2 will reject the
+   * delete: compliance-mode files cannot be deleted until the retention
+   * expires; governance-mode files require `bypassGovernance: true`
+   * AND a calling key with the `bypassGovernance` capability. Files on
+   * legal hold cannot be deleted by anyone until the hold is removed.
+   *
+   * @param fileName - The file path of the version to delete.
+   * @param fileId - The unique identifier of the file version to delete.
+   * @param options - Optional flag for bypassing governance retention.
+   */
+  async deleteFileVersion(fileName, fileId, options) {
+    await this.client.raw.deleteFileVersion(
+      this.client.accountInfo.getApiUrl(),
+      this.client.accountInfo.getAuthToken(),
+      {
+        fileName,
+        fileId,
+        ...options?.bypassGovernance !== void 0 ? { bypassGovernance: options.bypassGovernance } : {}
+      }
+    );
+  }
+  /**
+   * Cancels an in-progress large file upload so the partial parts are not
+   * retained or billed. The most common reason to call this is to clean up
+   * abandoned multipart uploads surfaced by {@link listUnfinishedLargeFiles}.
+   * @param fileId - The unique identifier of the unfinished large file to cancel.
+   *
+   * @returns Metadata about the cancelled large file.
+   */
+  async cancelLargeFile(fileId) {
+    return this.client.raw.cancelLargeFile(
+      this.client.accountInfo.getApiUrl(),
+      this.client.accountInfo.getAuthToken(),
+      { fileId }
+    );
+  }
+  /**
+   * Lists large files in this bucket that were started but never finished or
+   * cancelled. Wraps `b2_list_unfinished_large_files`.
+   * @param options - Optional pagination filters.
+   *
+   * @returns The page of unfinished large files plus a continuation token.
+   */
+  async listUnfinishedLargeFiles(options) {
+    return this.client.raw.listUnfinishedLargeFiles(
+      this.client.accountInfo.getApiUrl(),
+      this.client.accountInfo.getAuthToken(),
+      {
+        bucketId: this.id,
+        ...options?.namePrefix !== void 0 ? { namePrefix: options.namePrefix } : {},
+        ...options?.startFileId !== void 0 ? { startFileId: options.startFileId } : {},
+        ...options?.pageSize !== void 0 ? { maxFileCount: options.pageSize } : {}
+      }
+    );
+  }
+  /**
+   * Deletes many file versions with bounded concurrency. Errors from individual
+   * deletes are collected and returned rather than thrown, so partial success
+   * does not abort the run.
+   *
+   * When `options.signal` is supplied and aborted, in-flight deletes
+   * complete (they're already on the wire), but no new deletes start
+   * after the abort fires. Subsequent targets are short-circuited to an
+   * error entry so the result tally reflects what actually happened.
+   * @param targets - File versions to delete.
+   * @param options - Optional concurrency override and abort signal.
+   *   Concurrency defaults to the SDK-wide bulk-metadata setting
+   *   (currently 10, higher than transfer concurrency because each
+   *   task is a single tiny API round-trip).
+   *
+   * @returns A summary of successes and per-target errors.
+   */
+  async deleteMany(targets, options) {
+    const concurrency$1 = options?.concurrency ?? defaults.DEFAULT_BULK_CONCURRENCY;
+    const sem = new concurrency.Semaphore(concurrency$1);
+    const signal = options?.signal;
+    let deleted = 0;
+    const errors = [];
+    await Promise.all(
+      targets.map(async (target) => {
+        await sem.acquire();
+        try {
+          if (signal?.aborted) {
+            errors.push({
+              target,
+              error: toError.toError(signal.reason ?? "aborted")
+            });
+            return;
+          }
+          await this.deleteFileVersion(target.fileName, target.fileId);
+          deleted++;
+        } catch (err) {
+          errors.push({
+            target,
+            error: toError.toError(err)
+          });
+        } finally {
+          sem.release();
+        }
+      })
+    );
+    return { deleted, errors };
+  }
+  /**
+   * Async generator that streams every file version in the bucket (optionally
+   * filtered by prefix) and deletes each one. Yields a {@link DeleteAllEvent}
+   * per file version. With `dryRun: true`, no deletes are performed but `skip`
+   * events are still emitted.
+   * @param options - Optional prefix filter, page size, and dry-run flag.
+   *
+   * @returns An async generator of per-file events.
+   */
+  async *deleteAll(options) {
+    const dryRun = options?.dryRun ?? false;
+    const pageSize = options?.pageSize ?? defaults.DEFAULT_PAGE_SIZE;
+    let startFileName;
+    let startFileId;
+    while (true) {
+      const page = await this.listFileVersions({
+        pageSize,
+        ...options?.prefix !== void 0 ? { prefix: options.prefix } : {},
+        ...startFileName !== void 0 ? { startFileName } : {},
+        ...startFileId !== void 0 ? { startFileId } : {}
+      });
+      for (const version of page.files) {
+        if (dryRun) {
+          yield { type: "skip", fileName: version.fileName, fileId: version.fileId };
+          continue;
+        }
+        try {
+          await this.deleteFileVersion(version.fileName, version.fileId);
+          yield { type: "delete", fileName: version.fileName, fileId: version.fileId };
+        } catch (err) {
+          yield {
+            type: "error",
+            fileName: version.fileName,
+            fileId: version.fileId,
+            message: toError.toError(err).message
+          };
+        }
+      }
+      if (!page.nextFileName) break;
+      startFileName = page.nextFileName;
+      startFileId = page.nextFileId ?? void 0;
+    }
+  }
+  /**
+   * Creates a server-side copy of a file within or across buckets.
+   * @param options - Copy configuration including source file ID and destination name.
+   *
+   * @returns Metadata for the newly created file version.
+   */
+  async copyFile(options) {
+    return this.client.raw.copyFile(
+      this.client.accountInfo.getApiUrl(),
+      this.client.accountInfo.getAuthToken(),
+      options
+    );
+  }
+  /**
+   * Copies a file via the server-side multipart protocol. Each part is copied
+   * by reference through `b2_copy_part`; data never traverses the client. Falls
+   * back to a single `copyFile` call when the source fits within a single part.
+   * @param options - Copy parameters including source file ID, destination name, part size, and concurrency.
+   *
+   * @returns Metadata for the newly created destination file version.
+   */
+  async copyLargeFile(options) {
+    return large$1.copyLargeFile(this.client.raw, this.client.accountInfo, {
+      sourceFileId: options.sourceFileId,
+      fileName: options.fileName,
+      ...options.destinationBucketId !== void 0 ? { destinationBucketId: options.destinationBucketId } : { destinationBucketId: this.id },
+      ...options.contentType !== void 0 ? { contentType: options.contentType } : {},
+      ...options.fileInfo !== void 0 ? { fileInfo: options.fileInfo } : {},
+      ...options.destinationServerSideEncryption !== void 0 ? { destinationServerSideEncryption: options.destinationServerSideEncryption } : {},
+      ...options.sourceServerSideEncryption !== void 0 ? { sourceServerSideEncryption: options.sourceServerSideEncryption } : {},
+      ...options.partSize !== void 0 ? { partSize: options.partSize } : {},
+      ...options.concurrency !== void 0 ? { concurrency: options.concurrency } : {},
+      ...options.signal !== void 0 ? { signal: options.signal } : {}
+    });
+  }
+  /**
+   * Updates bucket settings such as type, CORS, lifecycle rules, and encryption.
+   * @param options - Fields to update. Omitted fields are left unchanged.
+   *
+   * @returns Updated bucket metadata.
+   */
+  async update(options) {
+    return this.client.raw.updateBucket(
+      this.client.accountInfo.getApiUrl(),
+      this.client.accountInfo.getAuthToken(),
+      {
+        accountId: ids.accountId(this.client.accountInfo.getAccountId()),
+        bucketId: this.id,
+        ...options
+      }
+    );
+  }
+  /**
+   * Permanently deletes this bucket. The bucket must be empty (no file versions).
+   *
+   * @returns The deleted bucket metadata.
+   */
+  async delete() {
+    return this.client.deleteBucket(this.id);
+  }
+  /**
+   * Gets a download authorization token scoped to a file name prefix in this bucket.
+   * @param fileNamePrefix - Only authorize downloads of files starting with this prefix.
+   * @param validDurationInSeconds - How long the authorization is valid (1-604800 seconds).
+   *
+   * @returns The download authorization response containing a time-limited token.
+   */
+  async getDownloadAuthorization(fileNamePrefix, validDurationInSeconds) {
+    return this.client.raw.getDownloadAuthorization(
+      this.client.accountInfo.getApiUrl(),
+      this.client.accountInfo.getAuthToken(),
+      { bucketId: this.id, fileNamePrefix, validDurationInSeconds }
+    );
+  }
+  /**
+   * Gets the event notification rules configured for this bucket.
+   *
+   * @returns The current notification rules for this bucket.
+   */
+  async getNotificationRules() {
+    return this.client.raw.getBucketNotificationRules(
+      this.client.accountInfo.getApiUrl(),
+      this.client.accountInfo.getAuthToken(),
+      { bucketId: this.id }
+    );
+  }
+  /**
+   * Replaces the event notification rules for this bucket.
+   * @param rules - The new set of notification rules to apply.
+   *
+   * @returns The updated notification rules for this bucket.
+   */
+  async setNotificationRules(rules) {
+    return this.client.raw.setBucketNotificationRules(
+      this.client.accountInfo.getApiUrl(),
+      this.client.accountInfo.getAuthToken(),
+      { bucketId: this.id, eventNotificationRules: rules }
+    );
+  }
+  /**
+   * Updates the file retention policy for a specific file version. Requires file lock on the bucket.
+   * @param fileName - The file path of the version to update.
+   * @param fileId - The unique identifier of the file version.
+   * @param retention - The new retention policy to apply.
+   * @param options - Optional flags. Set `bypassGovernance: true` to shorten governance-mode retention.
+   *
+   * @returns The updated file retention metadata.
+   */
+  async updateFileRetention(fileName, fileId, retention, options) {
+    return this.client.raw.updateFileRetention(
+      this.client.accountInfo.getApiUrl(),
+      this.client.accountInfo.getAuthToken(),
+      {
+        fileName,
+        fileId,
+        fileRetention: retention,
+        ...options?.bypassGovernance !== void 0 ? { bypassGovernance: options.bypassGovernance } : {}
+      }
+    );
+  }
+  /**
+   * Updates the legal hold status for a specific file version. Requires file lock on the bucket.
+   * @param fileName - The file path of the version to update.
+   * @param fileId - The unique identifier of the file version.
+   * @param legalHold - The new legal hold status to apply.
+   *
+   * @returns The updated legal hold metadata.
+   */
+  async updateFileLegalHold(fileName, fileId, legalHold) {
+    return this.client.raw.updateFileLegalHold(
+      this.client.accountInfo.getApiUrl(),
+      this.client.accountInfo.getAuthToken(),
+      { fileName, fileId, legalHold }
+    );
+  }
+  /**
+   * Refetches this bucket's metadata from B2 so callers operating on
+   * replication / lifecycle / retention configuration always start from the
+   * server-of-record state.
+   *
+   * Bucket configuration is monotonically revisioned by B2: B2 increments
+   * `revision` on every accepted update. The local {@link info} snapshot
+   * captured at construction time goes stale as soon as anyone else (or any
+   * prior `update()` call) mutates the bucket, so the ergonomic
+   * add/remove helpers below always refresh before composing the next
+   * `setX()` call. The result is that each helper is safe to call without
+   * the caller having to thread BucketInfo through their code.
+   *
+   * @returns Fresh {@link BucketInfo} for this bucket.
+   *
+   * @throws If the bucket no longer exists.
+   */
+  async refresh() {
+    const fresh = await this.client.listBuckets({ bucketId: this.id });
+    const found = fresh[0];
+    if (!found) throw new Error(`Bucket ${this.id} not found`);
+    return found.info;
+  }
+  /**
+   * Returns the current cross-region replication configuration, refetched
+   * from B2.
+   *
+   * Use this when you need to read replication state without composing a
+   * write. For add/remove flows the helper methods below handle the
+   * refresh-then-set sequence for you.
+   *
+   * @returns The current {@link ReplicationConfiguration}.
+   */
+  async getReplication() {
+    const fresh = await this.refresh();
+    return fresh.replicationConfiguration;
+  }
+  /**
+   * Replaces this bucket's complete replication configuration.
+   * @param replication - The new configuration. Pass an empty source/destination
+   *   pair (`{ asReplicationSource: null, asReplicationDestination: null }`)
+   *   to clear replication entirely.
+   *
+   * @returns The updated bucket metadata.
+   */
+  async setReplication(replication) {
+    return this.update({ replicationConfiguration: replication });
+  }
+  /**
+   * Adds (or replaces by `replicationRuleName`) a single replication rule
+   * on this bucket while leaving any other rules, the source key, and the
+   * destination key mapping untouched.
+   *
+   * When this is the very first source-side rule, `sourceApplicationKeyId`
+   * must be supplied to seed `asReplicationSource.sourceApplicationKeyId`;
+   * for subsequent calls the existing source key is reused unless the
+   * caller explicitly overrides it.
+   *
+   * @param rule - The replication rule to add or replace.
+   * @param options - Optional source application key ID override (or seed
+   *   when no source side exists yet).
+   *
+   * @returns The updated bucket metadata.
+   *
+   * @throws If no source-side replication exists yet and the caller did
+   *   not supply `sourceApplicationKeyId`.
+   */
+  async addReplicationRule(rule, options) {
+    const current = (await this.refresh()).replicationConfiguration;
+    const existingSource = current.asReplicationSource;
+    const sourceKey = options?.sourceApplicationKeyId ?? existingSource?.sourceApplicationKeyId;
+    if (!sourceKey) {
+      throw new Error(
+        "addReplicationRule: no existing source-side replication; pass options.sourceApplicationKeyId"
+      );
+    }
+    const existingRules = existingSource?.replicationRules ?? [];
+    const without = existingRules.filter((r) => r.replicationRuleName !== rule.replicationRuleName);
+    return this.setReplication({
+      asReplicationSource: {
+        sourceApplicationKeyId: sourceKey,
+        replicationRules: [...without, rule]
+      },
+      asReplicationDestination: current.asReplicationDestination
+    });
+  }
+  /**
+   * Removes a single replication rule by name. No-ops cleanly when the rule
+   * is not present (returns the unchanged-but-revision-bumped bucket info).
+   *
+   * @param replicationRuleName - Name of the rule to remove.
+   *
+   * @returns The updated bucket metadata.
+   */
+  async removeReplicationRule(replicationRuleName) {
+    const current = (await this.refresh()).replicationConfiguration;
+    const existingSource = current.asReplicationSource;
+    if (!existingSource) {
+      return this.setReplication(current);
+    }
+    const filtered = existingSource.replicationRules.filter(
+      (r) => r.replicationRuleName !== replicationRuleName
+    );
+    return this.setReplication({
+      asReplicationSource: {
+        sourceApplicationKeyId: existingSource.sourceApplicationKeyId,
+        replicationRules: filtered
+      },
+      asReplicationDestination: current.asReplicationDestination
+    });
+  }
+  /**
+   * Returns the current lifecycle rules for this bucket, refetched from B2.
+   *
+   * @returns The current array of {@link LifecycleRule}s.
+   */
+  async getLifecycleRules() {
+    const fresh = await this.refresh();
+    return fresh.lifecycleRules;
+  }
+  /**
+   * Replaces this bucket's lifecycle rules in their entirety.
+   * @param rules - The new rule set. Pass `[]` to remove all lifecycle
+   *   automation.
+   *
+   * @returns The updated bucket metadata.
+   */
+  async setLifecycleRules(rules) {
+    return this.update({ lifecycleRules: [...rules] });
+  }
+  /**
+   * Adds (or replaces, matched by `fileNamePrefix`) a single lifecycle rule
+   * while leaving any other rules untouched.
+   *
+   * Matching on prefix mirrors B2's own data model: each unique prefix can
+   * have at most one rule, and a `b2_update_bucket` call that contains two
+   * rules with the same prefix is rejected. The helper enforces this for
+   * the caller.
+   *
+   * @param rule - The lifecycle rule to add or replace.
+   *
+   * @returns The updated bucket metadata.
+   */
+  async addLifecycleRule(rule) {
+    const current = await this.getLifecycleRules();
+    const without = current.filter((r) => r.fileNamePrefix !== rule.fileNamePrefix);
+    return this.setLifecycleRules([...without, rule]);
+  }
+  /**
+   * Removes a single lifecycle rule by prefix. No-ops cleanly when the rule
+   * is not present.
+   *
+   * @param fileNamePrefix - The prefix of the rule to remove.
+   *
+   * @returns The updated bucket metadata.
+   */
+  async removeLifecycleRule(fileNamePrefix) {
+    const current = await this.getLifecycleRules();
+    return this.setLifecycleRules(current.filter((r) => r.fileNamePrefix !== fileNamePrefix));
+  }
+  /**
+   * Returns the current default Object Lock retention policy for new
+   * uploads to this bucket, refetched from B2.
+   *
+   * @returns The default {@link BucketRetentionPolicy} (which may be
+   *   `{ mode: 'none', period: null }` when Object Lock is enabled on the
+   *   bucket but no default is set).
+   */
+  async getDefaultRetention() {
+    const fresh = await this.refresh();
+    return fresh.defaultRetention;
+  }
+  /**
+   * Sets (or clears, by passing `{ mode: 'none', period: null }`) the
+   * default Object Lock retention policy applied to new uploads.
+   *
+   * Object Lock must already be enabled on the bucket. Buckets created
+   * without `fileLockEnabled: true` cannot accept a default retention
+   * policy and B2 will reject this call.
+   *
+   * @param policy - The new default retention policy.
+   *
+   * @returns The updated bucket metadata.
+   */
+  async setDefaultRetention(policy) {
+    return this.update({ defaultRetention: policy });
+  }
+}
+exports.Bucket = Bucket;
+//# sourceMappingURL=bucket.cjs.map