@backblaze-labs/b2-sdk 0.1.0

package/dist/object.d.cts

@@ -0,0 +1,263 @@
+import { Bucket } from './bucket.js';
+import { B2Client } from './client.js';
+import { DownloadResult, HeadResult } from './download/single.js';
+import { SseCDownloadKey } from './raw/index.js';
+import { ProgressListener } from './streams/progress.js';
+import { ContentSource } from './streams/source.js';
+import { EncryptionSetting } from './types/encryption.js';
+import { FileVersion } from './types/file.js';
+import { FileId, LargeFileId } from './types/ids.js';
+import { FileRetentionValue, LegalHoldValue } from './types/lock.js';
+import { UploadWriteHandle } from './upload/stream.js';
+/** Options accepted by {@link B2Object.download} and {@link B2Object.downloadById}. */
+export interface DownloadCallOptions {
+    /**
+     * HTTP method. Defaults to `'GET'`. Use `'HEAD'` to fetch only
+     * response headers. Prefer the dedicated {@link B2Object.head} /
+     * {@link Bucket.head} method over this option — those return a
+     * body-less result so callers never have to remember to drain the
+     * empty body of a HEAD response.
+     */
+    readonly method?: 'GET' | 'HEAD';
+    /** HTTP Range header value (e.g., `"bytes=0-999"`). */
+    readonly range?: string;
+    /** SSE-C decryption parameters, required if the file was uploaded with SSE-C. */
+    readonly serverSideEncryption?: SseCDownloadKey;
+    /** Override the response `Content-Disposition` header. */
+    readonly b2ContentDisposition?: string;
+    /** Override the response `Content-Language` header. */
+    readonly b2ContentLanguage?: string;
+    /** Override the response `Content-Encoding` header. */
+    readonly b2ContentEncoding?: string;
+    /** Override the response `Content-Type` header. */
+    readonly b2ContentType?: string;
+    /** Override the response `Cache-Control` header. */
+    readonly b2CacheControl?: string;
+    /** Override the response `Expires` header. */
+    readonly b2Expires?: string;
+    /** Abort signal for cancelling the download. */
+    readonly signal?: AbortSignal;
+    /**
+     * Callback invoked as the response body is consumed.
+     *
+     * Progress is byte-driven, not request-driven: the callback fires per
+     * chunk as the caller reads the returned `body` stream, and the final
+     * `partsCompleted: 1` event only fires once the stream is read to
+     * completion. Downloads that are dropped or aborted partway through
+     * will NOT emit a `completePart()` event.
+     */
+    readonly onProgress?: ProgressListener;
+}
+/**
+ * Options accepted by {@link B2Object.head} / {@link Bucket.head}.
+ * Same shape as {@link DownloadCallOptions} minus `method` (always
+ * HEAD) and `onProgress` (no body to track).
+ */
+export type HeadCallOptions = Omit<DownloadCallOptions, 'method' | 'onProgress'>;
+/**
+ * Handle to a specific file (by name) within a B2 bucket.
+ *
+ * Provides file-scoped upload, download, and management operations.
+ * Obtained via {@link Bucket.file}.
+ *
+ * @example
+ * ```ts
+ * const obj = bucket.file('photos/2026/sunset.jpg')
+ * await obj.upload({ source: new BufferSource(data) })
+ * const result = await obj.download()
+ * ```
+ */
+export declare class B2Object {
+    /** The file name (path) within the bucket. */
+    readonly fileName: string;
+    private readonly client;
+    private readonly bucket;
+    /**
+     * @param client - The parent B2Client instance.
+     * @param bucket - The parent Bucket this object belongs to.
+     * @param fileName - The file path within the bucket.
+     *
+     * @internal
+     */
+    constructor(client: B2Client, bucket: Bucket, fileName: string);
+    /**
+     * Uploads data to this file name. Automatically uses multipart upload for large files.
+     * @param options - Upload configuration including data source and optional settings.
+     *
+     * @returns Metadata for the uploaded file version.
+     */
+    upload(options: {
+        /** Data source to upload. */
+        source: ContentSource;
+        /** MIME type. Defaults to auto-detection 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). */
+        fileRetention?: FileRetentionValue;
+        /** Legal hold status. */
+        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 meaningful on the large-file path. Ignored on the
+         * small-file path.
+         */
+        resume?: boolean;
+        /**
+         * Resume into a specific large-file ID, bypassing discovery.
+         * Overrides the `resume` discovery path.
+         */
+        resumeFileId?: LargeFileId;
+    }): Promise<FileVersion>;
+    /**
+     * Downloads this file by name. Pass `method: 'HEAD'` to fetch only the
+     * response headers (file metadata) without streaming the body.
+     * @param options - Optional method, range, SSE-C decryption, response-header overrides, and abort signal.
+     *
+     * @returns The download result with response headers and body stream.
+     */
+    download(options?: DownloadCallOptions): Promise<DownloadResult>;
+    /**
+     * Fetches response headers for this file via HTTP HEAD. Returns a
+     * body-less result so callers never have to drain the (logically
+     * empty) HEAD body themselves.
+     *
+     * @param options - Optional range, SSE-C decryption, response-header
+     *   overrides, and abort signal. Same shape as {@link B2Object.download}'s
+     *   options minus `method` (always HEAD) and `onProgress` (no body).
+     *
+     * @returns Parsed download headers (content type, SHA-1, file info, etc.).
+     */
+    head(options?: HeadCallOptions): Promise<HeadResult>;
+    /**
+     * Downloads a specific version of this file by ID. Pass `method: 'HEAD'`
+     * to fetch only the response headers (file metadata) without streaming the body.
+     * @param fileId - The file version ID to download.
+     * @param options - Optional method, range, SSE-C decryption, response-header overrides, and abort signal.
+     *
+     * @returns The download result with response headers and body stream.
+     */
+    downloadById(fileId: FileId, options?: DownloadCallOptions): Promise<DownloadResult>;
+    /**
+     * Fetches response headers for a specific version of this file by ID
+     * via HTTP HEAD. Returns a body-less result so callers never have to
+     * drain the (logically empty) HEAD body themselves.
+     *
+     * @param fileId - The file version ID to inspect.
+     * @param options - Optional range, SSE-C decryption, response-header
+     *   overrides, and abort signal.
+     *
+     * @returns Parsed download headers.
+     */
+    headById(fileId: FileId, options?: HeadCallOptions): Promise<HeadResult>;
+    /**
+     * Creates a parallel-download ReadableStream that fetches the file in concurrent ranged chunks.
+     * @param fileId - The file version ID to download.
+     * @param totalSize - Total file size in bytes (needed to compute range boundaries).
+     * @param options - Concurrency, range size, and abort signal.
+     *
+     * @returns A Web ReadableStream of file data in sequential order.
+     */
+    createReadStream(fileId: FileId, totalSize: number, options?: {
+        /** Size of each ranged GET request in bytes. Defaults to 8 MB. */
+        rangeSize?: number;
+        /** Number of concurrent range requests. Defaults to 4. */
+        concurrency?: number;
+        /** Abort signal for cancelling the download. */
+        signal?: AbortSignal;
+    }): ReadableStream<Uint8Array>;
+    /**
+     * Creates a Web `WritableStream` that uploads streamed data into this file
+     * using the multipart protocol. Pipe a `ReadableStream<Uint8Array>` into the
+     * returned `writable` and await `done` to get the final {@link FileVersion}.
+     *
+     * Note: streaming uploads do not support resume because the size and per-part
+     * hashes are not known in advance. Use {@link upload} with a buffered source
+     * when resume is required.
+     *
+     * @param options - Streaming upload parameters (part size, concurrency, encryption).
+     *
+     * @returns A handle with the writable sink and a completion promise.
+     */
+    createWriteStream(options?: {
+        /** MIME type. Defaults to `b2/x-auto`. */
+        contentType?: string;
+        /** Custom key-value metadata stored with the file. */
+        fileInfo?: Record<string, string>;
+        /** Server-side encryption applied to each part. */
+        serverSideEncryption?: EncryptionSetting;
+        /** Target part size in bytes. Defaults to the account's recommended part size. */
+        partSize?: number;
+        /** Maximum number of parts uploaded in parallel. Defaults to 4. */
+        concurrency?: number;
+        /** Callback invoked with upload progress events. */
+        onProgress?: ProgressListener;
+        /** Abort signal that cancels the upload and the unfinished large file. */
+        signal?: AbortSignal;
+    }): UploadWriteHandle;
+    /**
+     * Retrieves metadata for a specific file version.
+     * @param fileId - The file version ID to look up.
+     *
+     * @returns The file version metadata.
+     */
+    getFileInfo(fileId: FileId): Promise<FileVersion>;
+    /**
+     * Hides this file by creating a hide marker at this file name.
+     *
+     * @returns Metadata for the newly created hide marker.
+     */
+    hide(): Promise<FileVersion>;
+    /**
+     * Permanently deletes a specific version of this file.
+     * @param fileId - The unique identifier of the file version to delete.
+     */
+    deleteVersion(fileId: FileId): Promise<void>;
+    /**
+     * Sets or updates the Object Lock retention policy on a specific file
+     * version of this file.
+     *
+     * The bucket must have Object Lock enabled (`fileLockEnabled: true` at
+     * creation time). Governance-mode retention can be shortened or removed
+     * by passing `bypassGovernance: true` together with an application key
+     * that carries the `bypassGovernance` capability; compliance-mode
+     * retention cannot be shortened by anyone until the
+     * `retainUntilTimestamp` elapses.
+     *
+     * @param fileId - The file version to apply the policy to.
+     * @param retention - The retention policy to apply.
+     * @param options - Optional flag for shortening governance-mode retention.
+     *
+     * @returns Metadata for the updated file version.
+     */
+    setRetention(fileId: FileId, retention: FileRetentionValue, options?: {
+        bypassGovernance?: boolean;
+    }): Promise<import('./index.js').UpdateFileRetentionResponse>;
+    /**
+     * Toggles the legal hold flag on a specific file version of this file.
+     *
+     * Legal hold is independent of retention: a file can be on legal hold
+     * without any retention policy, and vice versa. The bucket must have
+     * Object Lock enabled, and any caller must hold the `writeFileLegalHolds`
+     * capability.
+     *
+     * @param fileId - The file version to apply the flag to.
+     * @param legalHold - `'on'` to apply the hold, `'off'` to remove it.
+     *
+     * @returns Metadata for the updated file version.
+     */
+    setLegalHold(fileId: FileId, legalHold: LegalHoldValue): Promise<import('./index.js').UpdateFileLegalHoldResponse>;
+}
+//# sourceMappingURL=object.d.ts.map

package/dist/object.d.cts.map

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

package/dist/object.d.ts

@@ -0,0 +1,263 @@
+import { Bucket } from './bucket.js';
+import { B2Client } from './client.js';
+import { DownloadResult, HeadResult } from './download/single.js';
+import { SseCDownloadKey } from './raw/index.js';
+import { ProgressListener } from './streams/progress.js';
+import { ContentSource } from './streams/source.js';
+import { EncryptionSetting } from './types/encryption.js';
+import { FileVersion } from './types/file.js';
+import { FileId, LargeFileId } from './types/ids.js';
+import { FileRetentionValue, LegalHoldValue } from './types/lock.js';
+import { UploadWriteHandle } from './upload/stream.js';
+/** Options accepted by {@link B2Object.download} and {@link B2Object.downloadById}. */
+export interface DownloadCallOptions {
+    /**
+     * HTTP method. Defaults to `'GET'`. Use `'HEAD'` to fetch only
+     * response headers. Prefer the dedicated {@link B2Object.head} /
+     * {@link Bucket.head} method over this option — those return a
+     * body-less result so callers never have to remember to drain the
+     * empty body of a HEAD response.
+     */
+    readonly method?: 'GET' | 'HEAD';
+    /** HTTP Range header value (e.g., `"bytes=0-999"`). */
+    readonly range?: string;
+    /** SSE-C decryption parameters, required if the file was uploaded with SSE-C. */
+    readonly serverSideEncryption?: SseCDownloadKey;
+    /** Override the response `Content-Disposition` header. */
+    readonly b2ContentDisposition?: string;
+    /** Override the response `Content-Language` header. */
+    readonly b2ContentLanguage?: string;
+    /** Override the response `Content-Encoding` header. */
+    readonly b2ContentEncoding?: string;
+    /** Override the response `Content-Type` header. */
+    readonly b2ContentType?: string;
+    /** Override the response `Cache-Control` header. */
+    readonly b2CacheControl?: string;
+    /** Override the response `Expires` header. */
+    readonly b2Expires?: string;
+    /** Abort signal for cancelling the download. */
+    readonly signal?: AbortSignal;
+    /**
+     * Callback invoked as the response body is consumed.
+     *
+     * Progress is byte-driven, not request-driven: the callback fires per
+     * chunk as the caller reads the returned `body` stream, and the final
+     * `partsCompleted: 1` event only fires once the stream is read to
+     * completion. Downloads that are dropped or aborted partway through
+     * will NOT emit a `completePart()` event.
+     */
+    readonly onProgress?: ProgressListener;
+}
+/**
+ * Options accepted by {@link B2Object.head} / {@link Bucket.head}.
+ * Same shape as {@link DownloadCallOptions} minus `method` (always
+ * HEAD) and `onProgress` (no body to track).
+ */
+export type HeadCallOptions = Omit<DownloadCallOptions, 'method' | 'onProgress'>;
+/**
+ * Handle to a specific file (by name) within a B2 bucket.
+ *
+ * Provides file-scoped upload, download, and management operations.
+ * Obtained via {@link Bucket.file}.
+ *
+ * @example
+ * ```ts
+ * const obj = bucket.file('photos/2026/sunset.jpg')
+ * await obj.upload({ source: new BufferSource(data) })
+ * const result = await obj.download()
+ * ```
+ */
+export declare class B2Object {
+    /** The file name (path) within the bucket. */
+    readonly fileName: string;
+    private readonly client;
+    private readonly bucket;
+    /**
+     * @param client - The parent B2Client instance.
+     * @param bucket - The parent Bucket this object belongs to.
+     * @param fileName - The file path within the bucket.
+     *
+     * @internal
+     */
+    constructor(client: B2Client, bucket: Bucket, fileName: string);
+    /**
+     * Uploads data to this file name. Automatically uses multipart upload for large files.
+     * @param options - Upload configuration including data source and optional settings.
+     *
+     * @returns Metadata for the uploaded file version.
+     */
+    upload(options: {
+        /** Data source to upload. */
+        source: ContentSource;
+        /** MIME type. Defaults to auto-detection 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). */
+        fileRetention?: FileRetentionValue;
+        /** Legal hold status. */
+        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 meaningful on the large-file path. Ignored on the
+         * small-file path.
+         */
+        resume?: boolean;
+        /**
+         * Resume into a specific large-file ID, bypassing discovery.
+         * Overrides the `resume` discovery path.
+         */
+        resumeFileId?: LargeFileId;
+    }): Promise<FileVersion>;
+    /**
+     * Downloads this file by name. Pass `method: 'HEAD'` to fetch only the
+     * response headers (file metadata) without streaming the body.
+     * @param options - Optional method, range, SSE-C decryption, response-header overrides, and abort signal.
+     *
+     * @returns The download result with response headers and body stream.
+     */
+    download(options?: DownloadCallOptions): Promise<DownloadResult>;
+    /**
+     * Fetches response headers for this file via HTTP HEAD. Returns a
+     * body-less result so callers never have to drain the (logically
+     * empty) HEAD body themselves.
+     *
+     * @param options - Optional range, SSE-C decryption, response-header
+     *   overrides, and abort signal. Same shape as {@link B2Object.download}'s
+     *   options minus `method` (always HEAD) and `onProgress` (no body).
+     *
+     * @returns Parsed download headers (content type, SHA-1, file info, etc.).
+     */
+    head(options?: HeadCallOptions): Promise<HeadResult>;
+    /**
+     * Downloads a specific version of this file by ID. Pass `method: 'HEAD'`
+     * to fetch only the response headers (file metadata) without streaming the body.
+     * @param fileId - The file version ID to download.
+     * @param options - Optional method, range, SSE-C decryption, response-header overrides, and abort signal.
+     *
+     * @returns The download result with response headers and body stream.
+     */
+    downloadById(fileId: FileId, options?: DownloadCallOptions): Promise<DownloadResult>;
+    /**
+     * Fetches response headers for a specific version of this file by ID
+     * via HTTP HEAD. Returns a body-less result so callers never have to
+     * drain the (logically empty) HEAD body themselves.
+     *
+     * @param fileId - The file version ID to inspect.
+     * @param options - Optional range, SSE-C decryption, response-header
+     *   overrides, and abort signal.
+     *
+     * @returns Parsed download headers.
+     */
+    headById(fileId: FileId, options?: HeadCallOptions): Promise<HeadResult>;
+    /**
+     * Creates a parallel-download ReadableStream that fetches the file in concurrent ranged chunks.
+     * @param fileId - The file version ID to download.
+     * @param totalSize - Total file size in bytes (needed to compute range boundaries).
+     * @param options - Concurrency, range size, and abort signal.
+     *
+     * @returns A Web ReadableStream of file data in sequential order.
+     */
+    createReadStream(fileId: FileId, totalSize: number, options?: {
+        /** Size of each ranged GET request in bytes. Defaults to 8 MB. */
+        rangeSize?: number;
+        /** Number of concurrent range requests. Defaults to 4. */
+        concurrency?: number;
+        /** Abort signal for cancelling the download. */
+        signal?: AbortSignal;
+    }): ReadableStream<Uint8Array>;
+    /**
+     * Creates a Web `WritableStream` that uploads streamed data into this file
+     * using the multipart protocol. Pipe a `ReadableStream<Uint8Array>` into the
+     * returned `writable` and await `done` to get the final {@link FileVersion}.
+     *
+     * Note: streaming uploads do not support resume because the size and per-part
+     * hashes are not known in advance. Use {@link upload} with a buffered source
+     * when resume is required.
+     *
+     * @param options - Streaming upload parameters (part size, concurrency, encryption).
+     *
+     * @returns A handle with the writable sink and a completion promise.
+     */
+    createWriteStream(options?: {
+        /** MIME type. Defaults to `b2/x-auto`. */
+        contentType?: string;
+        /** Custom key-value metadata stored with the file. */
+        fileInfo?: Record<string, string>;
+        /** Server-side encryption applied to each part. */
+        serverSideEncryption?: EncryptionSetting;
+        /** Target part size in bytes. Defaults to the account's recommended part size. */
+        partSize?: number;
+        /** Maximum number of parts uploaded in parallel. Defaults to 4. */
+        concurrency?: number;
+        /** Callback invoked with upload progress events. */
+        onProgress?: ProgressListener;
+        /** Abort signal that cancels the upload and the unfinished large file. */
+        signal?: AbortSignal;
+    }): UploadWriteHandle;
+    /**
+     * Retrieves metadata for a specific file version.
+     * @param fileId - The file version ID to look up.
+     *
+     * @returns The file version metadata.
+     */
+    getFileInfo(fileId: FileId): Promise<FileVersion>;
+    /**
+     * Hides this file by creating a hide marker at this file name.
+     *
+     * @returns Metadata for the newly created hide marker.
+     */
+    hide(): Promise<FileVersion>;
+    /**
+     * Permanently deletes a specific version of this file.
+     * @param fileId - The unique identifier of the file version to delete.
+     */
+    deleteVersion(fileId: FileId): Promise<void>;
+    /**
+     * Sets or updates the Object Lock retention policy on a specific file
+     * version of this file.
+     *
+     * The bucket must have Object Lock enabled (`fileLockEnabled: true` at
+     * creation time). Governance-mode retention can be shortened or removed
+     * by passing `bypassGovernance: true` together with an application key
+     * that carries the `bypassGovernance` capability; compliance-mode
+     * retention cannot be shortened by anyone until the
+     * `retainUntilTimestamp` elapses.
+     *
+     * @param fileId - The file version to apply the policy to.
+     * @param retention - The retention policy to apply.
+     * @param options - Optional flag for shortening governance-mode retention.
+     *
+     * @returns Metadata for the updated file version.
+     */
+    setRetention(fileId: FileId, retention: FileRetentionValue, options?: {
+        bypassGovernance?: boolean;
+    }): Promise<import('./index.js').UpdateFileRetentionResponse>;
+    /**
+     * Toggles the legal hold flag on a specific file version of this file.
+     *
+     * Legal hold is independent of retention: a file can be on legal hold
+     * without any retention policy, and vice versa. The bucket must have
+     * Object Lock enabled, and any caller must hold the `writeFileLegalHolds`
+     * capability.
+     *
+     * @param fileId - The file version to apply the flag to.
+     * @param legalHold - `'on'` to apply the hold, `'off'` to remove it.
+     *
+     * @returns Metadata for the updated file version.
+     */
+    setLegalHold(fileId: FileId, legalHold: LegalHoldValue): Promise<import('./index.js').UpdateFileLegalHoldResponse>;
+}
+//# sourceMappingURL=object.d.ts.map

package/dist/object.d.ts.map

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