@backblaze-labs/b2-sdk 0.1.0

package/dist/object.js

@@ -0,0 +1,212 @@
+import { createParallelDownloadStream } from "./download/parallel.js";
+import { downloadByName, headByName, downloadById, headById } from "./download/single.js";
+import { uploadLargeFile } from "./upload/large.js";
+import { uploadSmallFile } from "./upload/single.js";
+import { createWriteStream } from "./upload/stream.js";
+class B2Object {
+  /** The file name (path) within the bucket. */
+  fileName;
+  client;
+  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, bucket, fileName) {
+    this.client = client;
+    this.bucket = bucket;
+    this.fileName = fileName;
+  }
+  /**
+   * 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.
+   */
+  async upload(options) {
+    const recommendedPartSize = this.client.accountInfo.getRecommendedPartSize();
+    const isLarge = options.source.size > recommendedPartSize;
+    if (isLarge) {
+      return uploadLargeFile(this.client.raw, this.client.accountInfo, {
+        bucketId: this.bucket.id,
+        fileName: this.fileName,
+        ...options
+      });
+    }
+    const { resume: _resume, resumeFileId: _resumeFileId, ...smallOptions } = options;
+    return uploadSmallFile(this.client.raw, this.client.accountInfo, {
+      bucketId: this.bucket.id,
+      fileName: this.fileName,
+      ...smallOptions
+    });
+  }
+  /**
+   * 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.
+   */
+  async download(options) {
+    return downloadByName(this.client.raw, this.client.accountInfo, {
+      bucketName: this.bucket.name,
+      fileName: this.fileName,
+      ...options
+    });
+  }
+  /**
+   * 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.).
+   */
+  async head(options) {
+    return headByName(this.client.raw, this.client.accountInfo, {
+      bucketName: this.bucket.name,
+      fileName: this.fileName,
+      ...options
+    });
+  }
+  /**
+   * 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.
+   */
+  async downloadById(fileId, options) {
+    return downloadById(this.client.raw, this.client.accountInfo, {
+      fileId,
+      ...options
+    });
+  }
+  /**
+   * 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.
+   */
+  async headById(fileId, options) {
+    return headById(this.client.raw, this.client.accountInfo, {
+      fileId,
+      ...options
+    });
+  }
+  /**
+   * 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, totalSize, options) {
+    return createParallelDownloadStream(this.client.raw, this.client.accountInfo, {
+      fileId,
+      totalSize,
+      ...options
+    });
+  }
+  /**
+   * 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) {
+    return createWriteStream(this.client.raw, this.client.accountInfo, {
+      bucketId: this.bucket.id,
+      fileName: this.fileName,
+      ...options ?? {}
+    });
+  }
+  /**
+   * Retrieves metadata for a specific file version.
+   * @param fileId - The file version ID to look up.
+   *
+   * @returns The file version metadata.
+   */
+  async getFileInfo(fileId) {
+    return this.client.raw.getFileInfo(
+      this.client.accountInfo.getApiUrl(),
+      this.client.accountInfo.getAuthToken(),
+      { fileId }
+    );
+  }
+  /**
+   * Hides this file by creating a hide marker at this file name.
+   *
+   * @returns Metadata for the newly created hide marker.
+   */
+  async hide() {
+    return this.bucket.hideFile(this.fileName);
+  }
+  /**
+   * Permanently deletes a specific version of this file.
+   * @param fileId - The unique identifier of the file version to delete.
+   */
+  async deleteVersion(fileId) {
+    await this.bucket.deleteFileVersion(this.fileName, fileId);
+  }
+  /**
+   * 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.
+   */
+  async setRetention(fileId, retention, options) {
+    return this.bucket.updateFileRetention(this.fileName, fileId, retention, options);
+  }
+  /**
+   * 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.
+   */
+  async setLegalHold(fileId, legalHold) {
+    return this.bucket.updateFileLegalHold(this.fileName, fileId, legalHold);
+  }
+}
+export {
+  B2Object
+};
+//# sourceMappingURL=object.js.map

package/dist/object.js.map

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

package/dist/package.json.cjs

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toStringTag]: { value: "Module" } });
+const version = "0.1.0";
+const pkg = {
+  version
+};
+exports.default = pkg;
+exports.version = version;
+//# sourceMappingURL=package.json.cjs.map

package/dist/package.json.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.json.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;"}

package/dist/package.json.js

@@ -0,0 +1,9 @@
+const version = "0.1.0";
+const pkg = {
+  version
+};
+export {
+  pkg as default,
+  version
+};
+//# sourceMappingURL=package.json.js.map

package/dist/package.json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.json.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;"}

package/dist/raw/encoding.cjs

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const textCodec = require("../util/text-codec.cjs");
+const SAFE_CHARS = new Set(
+  "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._~!$&'()*+,;=:@/".split("")
+);
+function encodeFileName(name) {
+  const encoded = [];
+  for (const char of name) {
+    if (SAFE_CHARS.has(char)) {
+      encoded.push(char);
+    } else {
+      const bytes = textCodec.utf8Encoder.encode(char);
+      for (const byte of bytes) {
+        encoded.push(`%${byte.toString(16).toUpperCase().padStart(2, "0")}`);
+      }
+    }
+  }
+  return encoded.join("");
+}
+function decodeFileName(encoded) {
+  return decodeURIComponent(encoded);
+}
+function buildFileInfoHeaders(fileInfo) {
+  if (!fileInfo) return {};
+  const headers = {};
+  for (const [key, value] of Object.entries(fileInfo)) {
+    headers[`X-Bz-Info-${encodeFileName(key)}`] = encodeFileName(value);
+  }
+  return headers;
+}
+function parseFileInfoHeaders(headers) {
+  const info = {};
+  headers.forEach((value, key) => {
+    const lower = key.toLowerCase();
+    if (lower.startsWith("x-bz-info-")) {
+      const infoKey = decodeFileName(lower.slice("x-bz-info-".length));
+      info[infoKey] = decodeFileName(value);
+    }
+  });
+  return info;
+}
+exports.buildFileInfoHeaders = buildFileInfoHeaders;
+exports.decodeFileName = decodeFileName;
+exports.encodeFileName = encodeFileName;
+exports.parseFileInfoHeaders = parseFileInfoHeaders;
+//# sourceMappingURL=encoding.cjs.map

package/dist/raw/encoding.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoding.cjs","sources":["../../src/raw/encoding.ts"],"sourcesContent":["import { utf8Encoder } from '../util/text-codec.ts'\n\n/**\n * Characters that B2 treats as safe (not percent-encoded) in file names.\n *\n * Per the B2 docs, everything except `a-z A-Z 0-9 - . _ ~ / ! $ & ' ( ) * + , ; = : @`\n * must be percent-encoded using UTF-8 byte values.\n */\nconst SAFE_CHARS = new Set(\n  \"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._~!$&'()*+,;=:@/\".split(''),\n)\n\n/**\n * Percent-encodes a file name using the B2-specific encoding rules.\n *\n * Unlike standard `encodeURIComponent`, B2 keeps `/` and several other\n * characters unencoded while encoding all other non-ASCII and special\n * characters as uppercase percent-encoded UTF-8 bytes.\n *\n * @param name - The raw (unencoded) file name.\n *\n * @returns The percent-encoded file name suitable for `X-Bz-File-Name` headers.\n */\nexport function encodeFileName(name: string): string {\n  const encoded: string[] = []\n  for (const char of name) {\n    if (SAFE_CHARS.has(char)) {\n      encoded.push(char)\n    } else {\n      const bytes = utf8Encoder.encode(char)\n      for (const byte of bytes) {\n        encoded.push(`%${byte.toString(16).toUpperCase().padStart(2, '0')}`)\n      }\n    }\n  }\n  return encoded.join('')\n}\n\n/**\n * Decodes a B2 percent-encoded file name back to a plain string.\n *\n * B2 percent-encoding is compatible with standard `decodeURIComponent`,\n * so this is a thin wrapper.\n *\n * @param encoded - The percent-encoded file name from B2.\n *\n * @returns The decoded file name.\n */\nexport function decodeFileName(encoded: string): string {\n  return decodeURIComponent(encoded)\n}\n\n/**\n * Converts a file-info map into `X-Bz-Info-*` HTTP headers.\n *\n * Both keys and values are percent-encoded with {@link encodeFileName}\n * to satisfy B2 header requirements.\n *\n * @param fileInfo - Key/value pairs to attach as custom file info, or `undefined`.\n *\n * @returns A record of header name/value pairs (empty if `fileInfo` is `undefined`).\n */\nexport function buildFileInfoHeaders(\n  fileInfo: Record<string, string> | undefined,\n): Record<string, string> {\n  if (!fileInfo) return {}\n  const headers: Record<string, string> = {}\n  for (const [key, value] of Object.entries(fileInfo)) {\n    headers[`X-Bz-Info-${encodeFileName(key)}`] = encodeFileName(value)\n  }\n  return headers\n}\n\n/**\n * Extracts custom file-info key/value pairs from B2 response headers.\n *\n * Scans for headers prefixed with `x-bz-info-` and decodes both the\n * key suffix and value using {@link decodeFileName}.\n *\n * @param headers - The HTTP response headers from a B2 download or file-info call.\n *\n * @returns A record of decoded file-info key/value pairs.\n */\nexport function parseFileInfoHeaders(headers: Headers): Record<string, string> {\n  const info: Record<string, string> = {}\n  headers.forEach((value, key) => {\n    const lower = key.toLowerCase()\n    if (lower.startsWith('x-bz-info-')) {\n      const infoKey = decodeFileName(lower.slice('x-bz-info-'.length))\n      info[infoKey] = decodeFileName(value)\n    }\n  })\n  return info\n}\n"],"names":["utf8Encoder"],"mappings":";;;AAQA,MAAM,aAAa,IAAI;AAAA,EACrB,mFAAmF,MAAM,EAAE;AAC7F;AAaO,SAAS,eAAe,MAAsB;AACnD,QAAM,UAAoB,CAAA;AAC1B,aAAW,QAAQ,MAAM;AACvB,QAAI,WAAW,IAAI,IAAI,GAAG;AACxB,cAAQ,KAAK,IAAI;AAAA,IACnB,OAAO;AACL,YAAM,QAAQA,UAAAA,YAAY,OAAO,IAAI;AACrC,iBAAW,QAAQ,OAAO;AACxB,gBAAQ,KAAK,IAAI,KAAK,SAAS,EAAE,EAAE,YAAA,EAAc,SAAS,GAAG,GAAG,CAAC,EAAE;AAAA,MACrE;AAAA,IACF;AAAA,EACF;AACA,SAAO,QAAQ,KAAK,EAAE;AACxB;AAYO,SAAS,eAAe,SAAyB;AACtD,SAAO,mBAAmB,OAAO;AACnC;AAYO,SAAS,qBACd,UACwB;AACxB,MAAI,CAAC,SAAU,QAAO,CAAA;AACtB,QAAM,UAAkC,CAAA;AACxC,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,QAAQ,GAAG;AACnD,YAAQ,aAAa,eAAe,GAAG,CAAC,EAAE,IAAI,eAAe,KAAK;AAAA,EACpE;AACA,SAAO;AACT;AAYO,SAAS,qBAAqB,SAA0C;AAC7E,QAAM,OAA+B,CAAA;AACrC,UAAQ,QAAQ,CAAC,OAAO,QAAQ;AAC9B,UAAM,QAAQ,IAAI,YAAA;AAClB,QAAI,MAAM,WAAW,YAAY,GAAG;AAClC,YAAM,UAAU,eAAe,MAAM,MAAM,aAAa,MAAM,CAAC;AAC/D,WAAK,OAAO,IAAI,eAAe,KAAK;AAAA,IACtC;AAAA,EACF,CAAC;AACD,SAAO;AACT;;;;;"}

package/dist/raw/encoding.d.cts

@@ -0,0 +1,46 @@
+/**
+ * Percent-encodes a file name using the B2-specific encoding rules.
+ *
+ * Unlike standard `encodeURIComponent`, B2 keeps `/` and several other
+ * characters unencoded while encoding all other non-ASCII and special
+ * characters as uppercase percent-encoded UTF-8 bytes.
+ *
+ * @param name - The raw (unencoded) file name.
+ *
+ * @returns The percent-encoded file name suitable for `X-Bz-File-Name` headers.
+ */
+export declare function encodeFileName(name: string): string;
+/**
+ * Decodes a B2 percent-encoded file name back to a plain string.
+ *
+ * B2 percent-encoding is compatible with standard `decodeURIComponent`,
+ * so this is a thin wrapper.
+ *
+ * @param encoded - The percent-encoded file name from B2.
+ *
+ * @returns The decoded file name.
+ */
+export declare function decodeFileName(encoded: string): string;
+/**
+ * Converts a file-info map into `X-Bz-Info-*` HTTP headers.
+ *
+ * Both keys and values are percent-encoded with {@link encodeFileName}
+ * to satisfy B2 header requirements.
+ *
+ * @param fileInfo - Key/value pairs to attach as custom file info, or `undefined`.
+ *
+ * @returns A record of header name/value pairs (empty if `fileInfo` is `undefined`).
+ */
+export declare function buildFileInfoHeaders(fileInfo: Record<string, string> | undefined): Record<string, string>;
+/**
+ * Extracts custom file-info key/value pairs from B2 response headers.
+ *
+ * Scans for headers prefixed with `x-bz-info-` and decodes both the
+ * key suffix and value using {@link decodeFileName}.
+ *
+ * @param headers - The HTTP response headers from a B2 download or file-info call.
+ *
+ * @returns A record of decoded file-info key/value pairs.
+ */
+export declare function parseFileInfoHeaders(headers: Headers): Record<string, string>;
+//# sourceMappingURL=encoding.d.ts.map

package/dist/raw/encoding.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoding.d.ts","sourceRoot":"","sources":["../../src/raw/encoding.js"],"names":[],"mappings":"AAYA;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAanD;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,GAC3C,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOxB;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAU7E"}

package/dist/raw/encoding.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Percent-encodes a file name using the B2-specific encoding rules.
+ *
+ * Unlike standard `encodeURIComponent`, B2 keeps `/` and several other
+ * characters unencoded while encoding all other non-ASCII and special
+ * characters as uppercase percent-encoded UTF-8 bytes.
+ *
+ * @param name - The raw (unencoded) file name.
+ *
+ * @returns The percent-encoded file name suitable for `X-Bz-File-Name` headers.
+ */
+export declare function encodeFileName(name: string): string;
+/**
+ * Decodes a B2 percent-encoded file name back to a plain string.
+ *
+ * B2 percent-encoding is compatible with standard `decodeURIComponent`,
+ * so this is a thin wrapper.
+ *
+ * @param encoded - The percent-encoded file name from B2.
+ *
+ * @returns The decoded file name.
+ */
+export declare function decodeFileName(encoded: string): string;
+/**
+ * Converts a file-info map into `X-Bz-Info-*` HTTP headers.
+ *
+ * Both keys and values are percent-encoded with {@link encodeFileName}
+ * to satisfy B2 header requirements.
+ *
+ * @param fileInfo - Key/value pairs to attach as custom file info, or `undefined`.
+ *
+ * @returns A record of header name/value pairs (empty if `fileInfo` is `undefined`).
+ */
+export declare function buildFileInfoHeaders(fileInfo: Record<string, string> | undefined): Record<string, string>;
+/**
+ * Extracts custom file-info key/value pairs from B2 response headers.
+ *
+ * Scans for headers prefixed with `x-bz-info-` and decodes both the
+ * key suffix and value using {@link decodeFileName}.
+ *
+ * @param headers - The HTTP response headers from a B2 download or file-info call.
+ *
+ * @returns A record of decoded file-info key/value pairs.
+ */
+export declare function parseFileInfoHeaders(headers: Headers): Record<string, string>;
+//# sourceMappingURL=encoding.d.ts.map

package/dist/raw/encoding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoding.d.ts","sourceRoot":"","sources":["../../src/raw/encoding.js"],"names":[],"mappings":"AAYA;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAanD;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,GAC3C,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOxB;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAU7E"}

package/dist/raw/encoding.js

@@ -0,0 +1,47 @@
+import { utf8Encoder } from "../util/text-codec.js";
+const SAFE_CHARS = new Set(
+  "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._~!$&'()*+,;=:@/".split("")
+);
+function encodeFileName(name) {
+  const encoded = [];
+  for (const char of name) {
+    if (SAFE_CHARS.has(char)) {
+      encoded.push(char);
+    } else {
+      const bytes = utf8Encoder.encode(char);
+      for (const byte of bytes) {
+        encoded.push(`%${byte.toString(16).toUpperCase().padStart(2, "0")}`);
+      }
+    }
+  }
+  return encoded.join("");
+}
+function decodeFileName(encoded) {
+  return decodeURIComponent(encoded);
+}
+function buildFileInfoHeaders(fileInfo) {
+  if (!fileInfo) return {};
+  const headers = {};
+  for (const [key, value] of Object.entries(fileInfo)) {
+    headers[`X-Bz-Info-${encodeFileName(key)}`] = encodeFileName(value);
+  }
+  return headers;
+}
+function parseFileInfoHeaders(headers) {
+  const info = {};
+  headers.forEach((value, key) => {
+    const lower = key.toLowerCase();
+    if (lower.startsWith("x-bz-info-")) {
+      const infoKey = decodeFileName(lower.slice("x-bz-info-".length));
+      info[infoKey] = decodeFileName(value);
+    }
+  });
+  return info;
+}
+export {
+  buildFileInfoHeaders,
+  decodeFileName,
+  encodeFileName,
+  parseFileInfoHeaders
+};
+//# sourceMappingURL=encoding.js.map

package/dist/raw/encoding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoding.js","sources":["../../src/raw/encoding.ts"],"sourcesContent":["import { utf8Encoder } from '../util/text-codec.ts'\n\n/**\n * Characters that B2 treats as safe (not percent-encoded) in file names.\n *\n * Per the B2 docs, everything except `a-z A-Z 0-9 - . _ ~ / ! $ & ' ( ) * + , ; = : @`\n * must be percent-encoded using UTF-8 byte values.\n */\nconst SAFE_CHARS = new Set(\n  \"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._~!$&'()*+,;=:@/\".split(''),\n)\n\n/**\n * Percent-encodes a file name using the B2-specific encoding rules.\n *\n * Unlike standard `encodeURIComponent`, B2 keeps `/` and several other\n * characters unencoded while encoding all other non-ASCII and special\n * characters as uppercase percent-encoded UTF-8 bytes.\n *\n * @param name - The raw (unencoded) file name.\n *\n * @returns The percent-encoded file name suitable for `X-Bz-File-Name` headers.\n */\nexport function encodeFileName(name: string): string {\n  const encoded: string[] = []\n  for (const char of name) {\n    if (SAFE_CHARS.has(char)) {\n      encoded.push(char)\n    } else {\n      const bytes = utf8Encoder.encode(char)\n      for (const byte of bytes) {\n        encoded.push(`%${byte.toString(16).toUpperCase().padStart(2, '0')}`)\n      }\n    }\n  }\n  return encoded.join('')\n}\n\n/**\n * Decodes a B2 percent-encoded file name back to a plain string.\n *\n * B2 percent-encoding is compatible with standard `decodeURIComponent`,\n * so this is a thin wrapper.\n *\n * @param encoded - The percent-encoded file name from B2.\n *\n * @returns The decoded file name.\n */\nexport function decodeFileName(encoded: string): string {\n  return decodeURIComponent(encoded)\n}\n\n/**\n * Converts a file-info map into `X-Bz-Info-*` HTTP headers.\n *\n * Both keys and values are percent-encoded with {@link encodeFileName}\n * to satisfy B2 header requirements.\n *\n * @param fileInfo - Key/value pairs to attach as custom file info, or `undefined`.\n *\n * @returns A record of header name/value pairs (empty if `fileInfo` is `undefined`).\n */\nexport function buildFileInfoHeaders(\n  fileInfo: Record<string, string> | undefined,\n): Record<string, string> {\n  if (!fileInfo) return {}\n  const headers: Record<string, string> = {}\n  for (const [key, value] of Object.entries(fileInfo)) {\n    headers[`X-Bz-Info-${encodeFileName(key)}`] = encodeFileName(value)\n  }\n  return headers\n}\n\n/**\n * Extracts custom file-info key/value pairs from B2 response headers.\n *\n * Scans for headers prefixed with `x-bz-info-` and decodes both the\n * key suffix and value using {@link decodeFileName}.\n *\n * @param headers - The HTTP response headers from a B2 download or file-info call.\n *\n * @returns A record of decoded file-info key/value pairs.\n */\nexport function parseFileInfoHeaders(headers: Headers): Record<string, string> {\n  const info: Record<string, string> = {}\n  headers.forEach((value, key) => {\n    const lower = key.toLowerCase()\n    if (lower.startsWith('x-bz-info-')) {\n      const infoKey = decodeFileName(lower.slice('x-bz-info-'.length))\n      info[infoKey] = decodeFileName(value)\n    }\n  })\n  return info\n}\n"],"names":[],"mappings":";AAQA,MAAM,aAAa,IAAI;AAAA,EACrB,mFAAmF,MAAM,EAAE;AAC7F;AAaO,SAAS,eAAe,MAAsB;AACnD,QAAM,UAAoB,CAAA;AAC1B,aAAW,QAAQ,MAAM;AACvB,QAAI,WAAW,IAAI,IAAI,GAAG;AACxB,cAAQ,KAAK,IAAI;AAAA,IACnB,OAAO;AACL,YAAM,QAAQ,YAAY,OAAO,IAAI;AACrC,iBAAW,QAAQ,OAAO;AACxB,gBAAQ,KAAK,IAAI,KAAK,SAAS,EAAE,EAAE,YAAA,EAAc,SAAS,GAAG,GAAG,CAAC,EAAE;AAAA,MACrE;AAAA,IACF;AAAA,EACF;AACA,SAAO,QAAQ,KAAK,EAAE;AACxB;AAYO,SAAS,eAAe,SAAyB;AACtD,SAAO,mBAAmB,OAAO;AACnC;AAYO,SAAS,qBACd,UACwB;AACxB,MAAI,CAAC,SAAU,QAAO,CAAA;AACtB,QAAM,UAAkC,CAAA;AACxC,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,QAAQ,GAAG;AACnD,YAAQ,aAAa,eAAe,GAAG,CAAC,EAAE,IAAI,eAAe,KAAK;AAAA,EACpE;AACA,SAAO;AACT;AAYO,SAAS,qBAAqB,SAA0C;AAC7E,QAAM,OAA+B,CAAA;AACrC,UAAQ,QAAQ,CAAC,OAAO,QAAQ;AAC9B,UAAM,QAAQ,IAAI,YAAA;AAClB,QAAI,MAAM,WAAW,YAAY,GAAG;AAClC,YAAM,UAAU,eAAe,MAAM,MAAM,aAAa,MAAM,CAAC;AAC/D,WAAK,OAAO,IAAI,eAAe,KAAK;AAAA,IACtC;AAAA,EACF,CAAC;AACD,SAAO;AACT;"}