@backblaze-labs/b2-sdk 0.1.0

package/dist/bucket.d.cts

@@ -0,0 +1,659 @@
+import { B2Client } from './client.js';
+import { DownloadResult, HeadResult } from './download/single.js';
+import { B2Object, DownloadCallOptions, HeadCallOptions } from './object.js';
+import { ProgressListener } from './streams/progress.js';
+import { ContentSource } from './streams/source.js';
+import { BucketInfo, BucketRetentionPolicy, BucketType, CorsRule, LifecycleRule } from './types/bucket.js';
+import { DownloadAuthorizationResponse } from './types/download.js';
+import { EncryptionSetting } from './types/encryption.js';
+import { FileVersion, ListFileNamesResponse, ListFileVersionsResponse, MetadataDirective } from './types/file.js';
+import { ApplicationKeyId, BucketId, FileId, LargeFileId } from './types/ids.js';
+import { FileRetentionValue, LegalHoldValue } from './types/lock.js';
+import { EventNotificationRule, GetBucketNotificationRulesResponse } from './types/notifications.js';
+import { ReplicationConfiguration, ReplicationRule } from './types/replication.js';
+import { CancelLargeFileResponse, PartInfo, UnfinishedLargeFile } from './types/upload.js';
+import { PaginatorOptions } from './util/paginator.js';
+/** A target for bulk deletion: a file name and its specific version ID. */
+export interface DeleteTarget {
+    /** File name (path) of the version to delete. */
+    readonly fileName: string;
+    /** Unique identifier of the file version. */
+    readonly fileId: FileId;
+}
+/** Per-target error encountered during bulk deletion. */
+export interface DeleteError {
+    /** The target that failed. */
+    readonly target: DeleteTarget;
+    /** The error thrown by the underlying `deleteFileVersion` call. */
+    readonly error: Error;
+}
+/** Aggregate result of a {@link Bucket.deleteMany} run. */
+export interface DeleteManyResult {
+    /** Number of file versions successfully deleted. */
+    readonly deleted: number;
+    /** Per-target failures. Empty on full success. */
+    readonly errors: readonly DeleteError[];
+}
+/** Emitted by {@link Bucket.deleteAll} once a file version has been successfully deleted. */
+export interface DeleteAllDeleteEvent {
+    /** Discriminant identifying a successful delete. */
+    readonly type: 'delete';
+    /** File name of the deleted version. */
+    readonly fileName: string;
+    /** Unique identifier of the deleted version. */
+    readonly fileId: FileId;
+}
+/** Emitted by {@link Bucket.deleteAll} when a single delete call fails (other versions keep streaming). */
+export interface DeleteAllErrorEvent {
+    /** Discriminant identifying a per-version delete failure. */
+    readonly type: 'error';
+    /** File name of the version that failed to delete. */
+    readonly fileName: string;
+    /** Unique identifier of the version that failed to delete. */
+    readonly fileId: FileId;
+    /** Human-readable failure reason taken from the underlying error. */
+    readonly message: string;
+}
+/** Emitted by {@link Bucket.deleteAll} in `dryRun` mode for every version that would have been deleted. */
+export interface DeleteAllSkipEvent {
+    /** Discriminant identifying a dry-run skip. */
+    readonly type: 'skip';
+    /** File name of the version that would have been deleted. */
+    readonly fileName: string;
+    /** Unique identifier of the version that would have been deleted. */
+    readonly fileId: FileId;
+}
+/** Event yielded by {@link Bucket.deleteAll} as it streams through file versions. */
+export type DeleteAllEvent = DeleteAllDeleteEvent | DeleteAllErrorEvent | DeleteAllSkipEvent;
+/**
+ * Handle to a B2 bucket providing upload, download, listing, and management operations.
+ *
+ * Obtained via {@link B2Client.createBucket}, {@link B2Client.listBuckets}, or {@link B2Client.getBucket}.
+ *
+ * @example
+ * ```ts
+ * const bucket = await client.getBucket('my-bucket')
+ * await bucket.upload({ fileName: 'hello.txt', source: new BufferSource(data) })
+ * ```
+ */
+export declare class Bucket {
+    /** Unique identifier for this bucket. */
+    readonly id: BucketId;
+    /** Human-readable bucket name. */
+    readonly name: string;
+    /** Full bucket metadata as returned by the B2 API. */
+    readonly info: BucketInfo;
+    private readonly client;
+    /**
+     * @param client - The parent B2Client instance.
+     * @param info - The bucket metadata from the API.
+     *
+     * @internal
+     */
+    constructor(client: B2Client, info: BucketInfo);
+    /**
+     * 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: string): B2Object;
+    /**
+     * 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.
+     */
+    upload(options: {
+        /** Destination file name (path) in the bucket. */
+        fileName: string;
+        /** Data source to upload. Use {@link BufferSource}, {@link BlobSource}, or {@link StreamSource}. */
+        source: ContentSource;
+        /** MIME type. Defaults to `"b2/x-auto"` (auto-detected by B2). */
+        contentType?: string;
+        /** Custom key-value metadata stored with the file. */
+        fileInfo?: Record<string, string>;
+        /** Server-side encryption settings. */
+        serverSideEncryption?: EncryptionSetting;
+        /** File retention policy (requires file lock on the bucket). */
+        fileRetention?: FileRetentionValue;
+        /** Legal hold status for the file. */
+        legalHold?: LegalHoldValue;
+        /** Last-modified timestamp in milliseconds since epoch. */
+        lastModifiedMillis?: number;
+        /** Part size override for multipart uploads, in bytes. */
+        partSize?: number;
+        /** Number of concurrent part uploads for large files. */
+        concurrency?: number;
+        /** Callback invoked with upload progress events. */
+        onProgress?: ProgressListener;
+        /** Abort signal for cancelling the upload. */
+        signal?: AbortSignal;
+        /**
+         * Resume an unfinished multipart upload for this file name when one
+         * exists. Only consulted on the large-file path (source size
+         * greater than `recommendedPartSize`). On the small-file path this
+         * option is silently ignored. Sliceable sources only — `StreamSource`
+         * rejects resume because it can't replay parts.
+         */
+        resume?: boolean;
+        /**
+         * Resume into a specific large-file ID. Overrides the `resume`
+         * discovery path. The local `partSize` must match the server-side
+         * plan.
+         */
+        resumeFileId?: LargeFileId;
+    }): Promise<FileVersion>;
+    /**
+     * 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.
+     */
+    download(fileName: string, options?: DownloadCallOptions): Promise<DownloadResult>;
+    /**
+     * 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)
+     * ```
+     */
+    head(fileName: string, options?: HeadCallOptions): Promise<HeadResult>;
+    /**
+     * 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.
+     */
+    listFileNames(options?: {
+        /** Start listing after this file name (for pagination). */
+        startFileName?: string;
+        /**
+         * Maximum number of files to return per request (1-10000).
+         * Forwarded to the raw API's `maxFileCount` parameter.
+         */
+        pageSize?: number;
+        /** Only list files with names starting with this prefix. */
+        prefix?: string;
+        /** Delimiter for virtual directory grouping (typically `"/"`). */
+        delimiter?: string;
+    }): Promise<ListFileNamesResponse>;
+    /**
+     * 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.
+     */
+    listFileVersions(options?: {
+        /** Start listing after this file name (for pagination). */
+        startFileName?: string;
+        /** Start listing after this file ID (for pagination within a file name). */
+        startFileId?: FileId;
+        /**
+         * Maximum number of file versions to return per request (1-10000).
+         * Forwarded to the raw API's `maxFileCount` parameter.
+         */
+        pageSize?: number;
+        /** Only list files with names starting with this prefix. */
+        prefix?: string;
+        /** Delimiter for virtual directory grouping. */
+        delimiter?: string;
+    }): Promise<ListFileVersionsResponse>;
+    /**
+     * 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?: {
+        /** Only yield files whose names start with this prefix. */
+        prefix?: string;
+        /** Delimiter for virtual directory grouping (typically `'/'`). */
+        delimiter?: string;
+    } & PaginatorOptions): AsyncIterableIterator<FileVersion>;
+    /**
+     * 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?: {
+        /** Only yield versions whose names start with this prefix. */
+        prefix?: string;
+        /** Delimiter for virtual directory grouping. */
+        delimiter?: string;
+    } & PaginatorOptions): AsyncIterableIterator<FileVersion>;
+    /**
+     * 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?: {
+        /** Only yield large files whose names start with this prefix. */
+        namePrefix?: string;
+    } & PaginatorOptions): AsyncIterableIterator<UnfinishedLargeFile>;
+    /**
+     * 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: LargeFileId, options?: PaginatorOptions): AsyncIterableIterator<PartInfo>;
+    /**
+     * 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.
+     */
+    getFileInfoByName(fileName: string): Promise<FileVersion | null>;
+    /**
+     * 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.
+     */
+    unhideFile(fileName: string): Promise<FileVersion | null>;
+    /**
+     * 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.
+     */
+    hideFile(fileName: string): Promise<FileVersion>;
+    /**
+     * 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.
+     */
+    deleteFileVersion(fileName: string, fileId: FileId, options?: {
+        bypassGovernance?: boolean;
+    }): Promise<void>;
+    /**
+     * 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.
+     */
+    cancelLargeFile(fileId: LargeFileId): Promise<CancelLargeFileResponse>;
+    /**
+     * 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.
+     */
+    listUnfinishedLargeFiles(options?: {
+        /** Restrict results to files whose name starts with this prefix. */
+        namePrefix?: string;
+        /** Start listing after this file ID (for pagination). */
+        startFileId?: LargeFileId;
+        /**
+         * Maximum number of files to return per request (1-100). Forwarded
+         * to the raw API's `maxFileCount` parameter.
+         */
+        pageSize?: number;
+    }): Promise<import('./index.js').ListUnfinishedLargeFilesResponse>;
+    /**
+     * 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.
+     */
+    deleteMany(targets: readonly DeleteTarget[], options?: {
+        concurrency?: number;
+        signal?: AbortSignal;
+    }): Promise<DeleteManyResult>;
+    /**
+     * 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.
+     */
+    deleteAll(options?: {
+        /** Only delete file versions whose names start with this prefix. */
+        prefix?: string;
+        /** Number of file versions fetched per API page (default 1000). */
+        pageSize?: number;
+        /** If true, yield `skip` events without actually deleting anything. */
+        dryRun?: boolean;
+    }): AsyncGenerator<DeleteAllEvent>;
+    /**
+     * 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.
+     */
+    copyFile(options: {
+        /** File ID of the source file to copy. */
+        sourceFileId: FileId;
+        /** Destination file name in the target bucket. */
+        fileName: string;
+        /** Target bucket ID. Defaults to this bucket if omitted. */
+        destinationBucketId?: BucketId;
+        /** Whether to copy or replace file metadata. */
+        metadataDirective?: MetadataDirective;
+        /** Override content type (only with `REPLACE` metadata directive). */
+        contentType?: string;
+        /** Override file info (only with `REPLACE` metadata directive). */
+        fileInfo?: Record<string, string>;
+        /** Server-side encryption for the destination file. */
+        serverSideEncryption?: EncryptionSetting;
+    }): Promise<FileVersion>;
+    /**
+     * 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.
+     */
+    copyLargeFile(options: {
+        /** File ID of the source file to copy. */
+        sourceFileId: FileId;
+        /** Destination file name in the target bucket. */
+        fileName: string;
+        /** Target bucket ID. Defaults to this bucket if omitted. */
+        destinationBucketId?: BucketId;
+        /** Override content type for the destination. */
+        contentType?: string;
+        /** Custom file info for the destination. */
+        fileInfo?: Record<string, string>;
+        /** Server-side encryption for the destination file. */
+        destinationServerSideEncryption?: EncryptionSetting;
+        /** SSE-C settings for the source if it was uploaded with SSE-C. */
+        sourceServerSideEncryption?: EncryptionSetting;
+        /** Part size in bytes. Defaults to the account's recommended part size. */
+        partSize?: number;
+        /**
+         * Maximum number of parts copied in parallel. Defaults to the
+         * SDK-wide transfer concurrency.
+         */
+        concurrency?: number;
+        /**
+         * Optional abort signal. Aborting cancels any remaining parts and
+         * triggers a best-effort `cancelLargeFile` on the unfinished upload.
+         */
+        signal?: AbortSignal;
+    }): Promise<FileVersion>;
+    /**
+     * 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.
+     */
+    update(options: {
+        /** Change the bucket access level. */
+        bucketType?: BucketType;
+        /** Replace custom bucket metadata. */
+        bucketInfo?: Record<string, string>;
+        /** Replace CORS rules. */
+        corsRules?: CorsRule[];
+        /** Change default server-side encryption. */
+        defaultServerSideEncryption?: EncryptionSetting;
+        /** Change default file retention policy. */
+        defaultRetention?: BucketRetentionPolicy;
+        /** Replace lifecycle rules. */
+        lifecycleRules?: LifecycleRule[];
+        /** Update replication configuration. */
+        replicationConfiguration?: ReplicationConfiguration;
+        /** Optimistic locking: only update if the bucket revision matches. */
+        ifRevisionIs?: number;
+    }): Promise<BucketInfo>;
+    /**
+     * Permanently deletes this bucket. The bucket must be empty (no file versions).
+     *
+     * @returns The deleted bucket metadata.
+     */
+    delete(): Promise<BucketInfo>;
+    /**
+     * 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.
+     */
+    getDownloadAuthorization(fileNamePrefix: string, validDurationInSeconds: number): Promise<DownloadAuthorizationResponse>;
+    /**
+     * Gets the event notification rules configured for this bucket.
+     *
+     * @returns The current notification rules for this bucket.
+     */
+    getNotificationRules(): Promise<GetBucketNotificationRulesResponse>;
+    /**
+     * 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.
+     */
+    setNotificationRules(rules: EventNotificationRule[]): Promise<GetBucketNotificationRulesResponse>;
+    /**
+     * 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.
+     */
+    updateFileRetention(fileName: string, fileId: FileId, retention: FileRetentionValue, options?: {
+        bypassGovernance?: boolean;
+    }): Promise<import('./index.js').UpdateFileRetentionResponse>;
+    /**
+     * 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.
+     */
+    updateFileLegalHold(fileName: string, fileId: FileId, legalHold: LegalHoldValue): Promise<import('./index.js').UpdateFileLegalHoldResponse>;
+    /**
+     * 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.
+     */
+    private refresh;
+    /**
+     * 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}.
+     */
+    getReplication(): Promise<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.
+     */
+    setReplication(replication: ReplicationConfiguration): Promise<BucketInfo>;
+    /**
+     * 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`.
+     */
+    addReplicationRule(rule: ReplicationRule, options?: {
+        sourceApplicationKeyId?: ApplicationKeyId;
+    }): Promise<BucketInfo>;
+    /**
+     * 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.
+     */
+    removeReplicationRule(replicationRuleName: string): Promise<BucketInfo>;
+    /**
+     * Returns the current lifecycle rules for this bucket, refetched from B2.
+     *
+     * @returns The current array of {@link LifecycleRule}s.
+     */
+    getLifecycleRules(): Promise<readonly LifecycleRule[]>;
+    /**
+     * 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.
+     */
+    setLifecycleRules(rules: readonly LifecycleRule[]): Promise<BucketInfo>;
+    /**
+     * 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.
+     */
+    addLifecycleRule(rule: LifecycleRule): Promise<BucketInfo>;
+    /**
+     * 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.
+     */
+    removeLifecycleRule(fileNamePrefix: string): Promise<BucketInfo>;
+    /**
+     * 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).
+     */
+    getDefaultRetention(): Promise<BucketRetentionPolicy>;
+    /**
+     * 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.
+     */
+    setDefaultRetention(policy: BucketRetentionPolicy): Promise<BucketInfo>;
+}
+//# sourceMappingURL=bucket.d.ts.map

package/dist/bucket.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bucket.d.ts","sourceRoot":"","sources":["../src/bucket.js"],"names":[],"mappings":"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"}