@backblaze-labs/b2-sdk 0.1.0

package/dist/sync/synchronizer.js

@@ -0,0 +1,181 @@
+import { BufferSource } from "../streams/source.js";
+import { fileId } from "../types/ids.js";
+import { Semaphore } from "../upload/concurrency.js";
+import { DEFAULT_TRANSFER_CONCURRENCY } from "../util/defaults.js";
+import { toError } from "../util/to-error.js";
+import { DeleteLocalAction, DeleteRemoteAction, HideAction, CopyAction, DownloadAction, UploadAction } from "./actions/index.js";
+import { zipFolders } from "./pairing.js";
+import { generateActions } from "./policies/index.js";
+function resolveDirection(source, dest) {
+  if (source.type === "local" && dest.type === "b2") return "local-to-b2";
+  if (source.type === "b2" && dest.type === "local") return "b2-to-local";
+  if (source.type === "b2" && dest.type === "b2") return "b2-to-b2";
+  throw new Error(`Unsupported sync direction: ${source.type} to ${dest.type}`);
+}
+async function* synchronize(config) {
+  const { source, dest, options } = config;
+  const direction = resolveDirection(source, dest);
+  const dryRun = options.dryRun ?? false;
+  const concurrency = options.concurrency ?? DEFAULT_TRANSFER_CONCURRENCY;
+  const keepDays = options.keepDays ?? 0;
+  const compareThreshold = options.compareThreshold ?? 0;
+  const nowMillis = Date.now();
+  const factory = createActionFactory(config);
+  const actions = [];
+  for await (const pair of zipFolders(source, dest)) {
+    if (options.signal?.aborted) return;
+    for (const action of generateActions(
+      pair,
+      direction,
+      options.compareMode,
+      options.keepMode,
+      keepDays,
+      nowMillis,
+      factory,
+      compareThreshold
+    )) {
+      actions.push(action);
+    }
+    yield { type: "compare", path: (pair[0] ?? pair[1])?.relativePath ?? "", size: 0 };
+  }
+  const sem = new Semaphore(concurrency);
+  const results = [];
+  const errors = [];
+  const promises = actions.map(async (action) => {
+    await sem.acquire();
+    try {
+      if (options.signal?.aborted) return;
+      const event = await action.execute(dryRun);
+      results.push(event);
+    } catch (err) {
+      const errorValue = toError(err);
+      errors.push(errorValue);
+      results.push({
+        type: "error",
+        path: action.relativePath,
+        size: 0,
+        message: errorValue.message
+      });
+    } finally {
+      sem.release();
+    }
+  });
+  await Promise.all(promises);
+  for (const event of results) {
+    yield event;
+  }
+  if (errors.length > 0) {
+    yield {
+      type: "error",
+      path: "",
+      size: 0,
+      message: `${errors.length} action(s) failed`
+    };
+  }
+}
+function assertBucket(bucket, context) {
+  if (!bucket) throw new Error(`Bucket required for ${context} actions`);
+}
+function createActionFactory(config) {
+  const upConfig = config;
+  const downConfig = config;
+  const destBucket = upConfig.bucket ?? downConfig.bucket;
+  const bucketIsLocked = destBucket?.info?.fileLockConfiguration?.value?.isFileLockEnabled ?? false;
+  const factory = {
+    upload(source) {
+      const bucket = upConfig.bucket;
+      const prefix = upConfig.prefix ?? "";
+      assertBucket(bucket, "upload");
+      return new UploadAction(
+        source.relativePath,
+        source.absolutePath,
+        source.size,
+        async (absPath, relPath) => {
+          const { readFile } = await import("node:fs/promises");
+          const data = await readFile(absPath);
+          await bucket.upload({
+            fileName: `${prefix}${relPath}`,
+            source: new BufferSource(new Uint8Array(data))
+          });
+        }
+      );
+    },
+    download(source) {
+      const bucket = downConfig.bucket;
+      const root = downConfig.dest?.type === "local" ? downConfig.dest.root : "";
+      assertBucket(bucket, "download");
+      return new DownloadAction(source.relativePath, source.size, async (relPath) => {
+        const result = await bucket.download(source.selectedVersion.fileName);
+        const reader = result.body.getReader();
+        let combined;
+        try {
+          const chunks = [];
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            chunks.push(value);
+          }
+          let total = 0;
+          for (const c of chunks) total += c.byteLength;
+          combined = new Uint8Array(total);
+          let offset = 0;
+          for (const c of chunks) {
+            combined.set(c, offset);
+            offset += c.byteLength;
+          }
+        } finally {
+          reader.releaseLock();
+        }
+        const { mkdir, writeFile } = await import("node:fs/promises");
+        const { dirname, join } = await import("node:path");
+        const destPath = join(root, relPath);
+        await mkdir(dirname(destPath), { recursive: true });
+        await writeFile(destPath, combined);
+      });
+    },
+    copy(source, destPath) {
+      const bucket = upConfig.bucket;
+      assertBucket(bucket, "copy");
+      return new CopyAction(source.relativePath, source.size, async () => {
+        await bucket.copyFile({
+          sourceFileId: source.selectedVersion.fileId,
+          fileName: destPath
+        });
+      });
+    },
+    hide(path) {
+      const bucket = upConfig.bucket ?? downConfig.bucket;
+      assertBucket(bucket, "hide");
+      return new HideAction(path, async (relPath) => {
+        const prefix = upConfig.prefix ?? "";
+        await bucket.hideFile(`${prefix}${relPath}`);
+      });
+    },
+    deleteRemote(path) {
+      const bucket = upConfig.bucket ?? downConfig.bucket;
+      assertBucket(bucket, "delete");
+      const b2FileName = path.selectedVersion.fileName;
+      return new DeleteRemoteAction(
+        path.relativePath,
+        path.selectedVersion.fileId,
+        async (fileId$1) => {
+          await bucket.deleteFileVersion(b2FileName, fileId(fileId$1));
+        }
+      );
+    },
+    deleteLocal(path) {
+      return new DeleteLocalAction(path.relativePath, path.absolutePath, async (absPath) => {
+        const { unlink } = await import("node:fs/promises");
+        await unlink(absPath);
+      });
+    },
+    removeOrphan(dest) {
+      return bucketIsLocked ? factory.hide(dest.relativePath) : factory.deleteRemote(dest);
+    }
+  };
+  return factory;
+}
+export {
+  synchronize
+};
+//# sourceMappingURL=synchronizer.js.map

package/dist/sync/synchronizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"synchronizer.js","sources":["../../src/sync/synchronizer.ts"],"sourcesContent":["import type { Bucket } from '../bucket.ts'\nimport { BufferSource } from '../streams/source.ts'\nimport { fileId as fileIdOf } from '../types/ids.ts'\nimport { Semaphore } from '../upload/concurrency.ts'\nimport { DEFAULT_TRANSFER_CONCURRENCY } from '../util/defaults.ts'\nimport { toError } from '../util/to-error.ts'\nimport type { SyncAction } from './actions/index.ts'\nimport {\n  CopyAction,\n  DeleteLocalAction,\n  DeleteRemoteAction,\n  DownloadAction,\n  HideAction,\n  UploadAction,\n} from './actions/index.ts'\nimport { zipFolders } from './pairing.ts'\nimport type { ActionFactory } from './policies/index.ts'\nimport { generateActions } from './policies/index.ts'\nimport type {\n  B2SyncPath,\n  LocalSyncPath,\n  SyncDirection,\n  SyncEvent,\n  SyncFolder,\n  SyncOptions,\n} from './types.ts'\n\n/** Base configuration for a sync operation. */\nexport interface SynchronizerConfig {\n  /** The folder to read files from. */\n  readonly source: SyncFolder\n  /** The folder to write files to. */\n  readonly dest: SyncFolder\n  /** Options controlling comparison, deletion policy, and concurrency. */\n  readonly options: SyncOptions\n}\n\n/** A sync folder constrained to the local filesystem. */\nexport interface LocalSyncFolder extends SyncFolder {\n  /** Discriminant identifying a local folder. */\n  readonly type: 'local'\n  /** Absolute filesystem path to the local root directory. */\n  readonly root: string\n}\n\n/** A sync folder constrained to a B2 bucket prefix. */\nexport interface B2SyncFolder extends SyncFolder {\n  /** Discriminant identifying a B2 folder. */\n  readonly type: 'b2'\n}\n\n/** Configuration for a local-to-B2 sync (upload direction). */\nexport interface SynchronizerUpConfig extends SynchronizerConfig {\n  /** Local source folder. */\n  readonly source: LocalSyncFolder\n  /** B2 destination folder. */\n  readonly dest: B2SyncFolder\n  /** The target B2 bucket. */\n  readonly bucket: Bucket\n  /** Key prefix for uploaded files in the bucket. */\n  readonly prefix: string\n}\n\n/** Configuration for a B2-to-local sync (download direction). */\nexport interface SynchronizerDownConfig extends SynchronizerConfig {\n  /** B2 source folder. */\n  readonly source: B2SyncFolder\n  /** Local destination folder. */\n  readonly dest: LocalSyncFolder\n  /** The source B2 bucket. */\n  readonly bucket: Bucket\n}\n\n/**\n * Infers the sync direction from the source and destination folder types.\n * @param source - The folder to read files from.\n * @param dest - The folder to write files to.\n *\n * @returns The resolved sync direction based on folder types.\n *\n * @throws When the source and destination folder types form an unsupported combination.\n */\nfunction resolveDirection(source: SyncFolder, dest: SyncFolder): SyncDirection {\n  if (source.type === 'local' && dest.type === 'b2') return 'local-to-b2'\n  if (source.type === 'b2' && dest.type === 'local') return 'b2-to-local'\n  if (source.type === 'b2' && dest.type === 'b2') return 'b2-to-b2'\n  throw new Error(`Unsupported sync direction: ${source.type} to ${dest.type}`)\n}\n\n/**\n * Runs a full sync operation: scans both folders, pairs files, generates actions,\n * and executes them with bounded concurrency. Yields {@link SyncEvent} entries for\n * each comparison and action result.\n *\n * @param config - The synchronizer configuration (source, dest, options, and optional bucket).\n */\nexport async function* synchronize(config: SynchronizerConfig): AsyncGenerator<SyncEvent> {\n  const { source, dest, options } = config\n  const direction = resolveDirection(source, dest)\n  const dryRun = options.dryRun ?? false\n  const concurrency = options.concurrency ?? DEFAULT_TRANSFER_CONCURRENCY\n  const keepDays = options.keepDays ?? 0\n  const compareThreshold = options.compareThreshold ?? 0\n  const nowMillis = Date.now()\n\n  const factory = createActionFactory(config)\n\n  const actions: SyncAction[] = []\n\n  for await (const pair of zipFolders(source, dest)) {\n    if (options.signal?.aborted) return\n\n    for (const action of generateActions(\n      pair,\n      direction,\n      options.compareMode,\n      options.keepMode,\n      keepDays,\n      nowMillis,\n      factory,\n      compareThreshold,\n    )) {\n      actions.push(action)\n    }\n\n    yield { type: 'compare', path: (pair[0] ?? pair[1])?.relativePath ?? '', size: 0 }\n  }\n\n  const sem = new Semaphore(concurrency)\n  const results: SyncEvent[] = []\n  const errors: Error[] = []\n\n  const promises = actions.map(async (action) => {\n    await sem.acquire()\n    try {\n      if (options.signal?.aborted) return\n      const event = await action.execute(dryRun)\n      results.push(event)\n    } catch (err) {\n      const errorValue = toError(err)\n      errors.push(errorValue)\n      results.push({\n        type: 'error',\n        path: action.relativePath,\n        size: 0,\n        message: errorValue.message,\n      })\n    } finally {\n      sem.release()\n    }\n  })\n\n  await Promise.all(promises)\n\n  for (const event of results) {\n    yield event\n  }\n\n  if (errors.length > 0) {\n    yield {\n      type: 'error',\n      path: '',\n      size: 0,\n      message: `${errors.length} action(s) failed`,\n    }\n  }\n}\n\n/**\n * Narrowing assertion that a `Bucket` is present for an action that requires\n * it. Throws with a consistent, context-tagged message when the configured\n * direction did not supply one (e.g. `b2-to-local` direction asking for an\n * upload action).\n *\n * Uses TypeScript's `asserts` signature so call-site flow narrows\n * `bucket` from `Bucket | undefined` to `Bucket` after the check, without\n * requiring a separate `if (!bucket) throw ...` line per action factory.\n *\n * @param bucket - The (possibly missing) bucket reference.\n * @param context - Short verb describing the action being constructed\n *   (e.g. `'upload'`, `'download'`). Surfaced in the error message.\n *\n * @throws `Error` when `bucket` is `undefined` or `null`.\n */\nfunction assertBucket(bucket: Bucket | undefined, context: string): asserts bucket is Bucket {\n  if (!bucket) throw new Error(`Bucket required for ${context} actions`)\n}\n\n/**\n * Creates a configured sync engine wired to the bucket and paths in the given config.\n *\n * For sync operations that may need to remove destination-only files (the\n * `keepMode: 'delete'` policy), the factory reads the destination\n * bucket's cached `fileLockConfiguration` once so `removeOrphan` can\n * dispatch to either `hide` (locked buckets) or `deleteFileVersion`\n * (vanilla buckets) without a per-file branch. The cache is whatever\n * `client.listBuckets()` or `client.createBucket()` returned — callers\n * who flipped lock state mid-sync (rare) should refresh before\n * synchronize().\n *\n * @param config - The synchronizer configuration containing source, destination, and options.\n *\n * @returns An action factory bound to the provided configuration.\n */\nfunction createActionFactory(config: SynchronizerConfig): ActionFactory {\n  const upConfig = config as Partial<SynchronizerUpConfig>\n  const downConfig = config as Partial<SynchronizerDownConfig>\n\n  const destBucket = upConfig.bucket ?? downConfig.bucket\n  // Defensive optional chain on `info`: synchronizer tests use Bucket\n  // mocks that don't populate this field. Real `Bucket` instances always\n  // do (constructor parameter).\n  const bucketIsLocked = destBucket?.info?.fileLockConfiguration?.value?.isFileLockEnabled ?? false\n\n  const factory: ActionFactory = {\n    upload(source: LocalSyncPath): SyncAction {\n      const bucket = upConfig.bucket\n      const prefix = upConfig.prefix ?? ''\n      assertBucket(bucket, 'upload')\n\n      return new UploadAction(\n        source.relativePath,\n        source.absolutePath,\n        source.size,\n        async (absPath, relPath) => {\n          const { readFile } = await import('node:fs/promises')\n          const data = await readFile(absPath)\n          await bucket.upload({\n            fileName: `${prefix}${relPath}`,\n            source: new BufferSource(new Uint8Array(data)),\n          })\n        },\n      )\n    },\n\n    download(source: B2SyncPath): SyncAction {\n      const bucket = downConfig.bucket\n      const root =\n        downConfig.dest?.type === 'local' ? (downConfig.dest as { root: string }).root : ''\n      assertBucket(bucket, 'download')\n\n      return new DownloadAction(source.relativePath, source.size, async (relPath) => {\n        const result = await bucket.download(source.selectedVersion.fileName)\n        const reader = result.body.getReader()\n        let combined: Uint8Array\n        try {\n          const chunks: Uint8Array[] = []\n          while (true) {\n            const { done, value } = await reader.read()\n            if (done) break\n            chunks.push(value)\n          }\n          let total = 0\n          for (const c of chunks) total += c.byteLength\n          combined = new Uint8Array(total)\n          let offset = 0\n          for (const c of chunks) {\n            combined.set(c, offset)\n            offset += c.byteLength\n          }\n        } finally {\n          // Release the body stream's reader lock so a downstream\n          // writeFile failure doesn't strand the response stream half-\n          // open with the upstream HTTP connection still pumping.\n          reader.releaseLock()\n        }\n\n        const { mkdir, writeFile } = await import('node:fs/promises')\n        const { dirname, join } = await import('node:path')\n        const destPath = join(root, relPath)\n        await mkdir(dirname(destPath), { recursive: true })\n        await writeFile(destPath, combined)\n      })\n    },\n\n    copy(source: B2SyncPath, destPath: string): SyncAction {\n      const bucket = upConfig.bucket\n      assertBucket(bucket, 'copy')\n\n      return new CopyAction(source.relativePath, source.size, async () => {\n        await bucket.copyFile({\n          sourceFileId: source.selectedVersion.fileId,\n          fileName: destPath,\n        })\n      })\n    },\n\n    hide(path: string): SyncAction {\n      const bucket = upConfig.bucket ?? downConfig.bucket\n      assertBucket(bucket, 'hide')\n\n      return new HideAction(path, async (relPath) => {\n        const prefix = upConfig.prefix ?? ''\n        await bucket.hideFile(`${prefix}${relPath}`)\n      })\n    },\n\n    deleteRemote(path: B2SyncPath): SyncAction {\n      const bucket = upConfig.bucket ?? downConfig.bucket\n      assertBucket(bucket, 'delete')\n\n      // Bug fix: `DeleteRemoteAction` invokes the closure with\n      // `relativePath` (the scanner-stripped name relative to the sync\n      // prefix), but B2 stores files under the FULL name including the\n      // prefix. Use the FileVersion's authoritative `fileName` — the\n      // actual B2 key — rather than reconstructing it via prefix\n      // concat. Without this, syncs with a non-empty destination\n      // prefix (e.g. `'site/'`) failed orphan deletion with\n      // `file_not_present`.\n      const b2FileName = path.selectedVersion.fileName\n      return new DeleteRemoteAction(\n        path.relativePath,\n        path.selectedVersion.fileId as string,\n        async (fileId) => {\n          await bucket.deleteFileVersion(b2FileName, fileIdOf(fileId))\n        },\n      )\n    },\n\n    deleteLocal(path: LocalSyncPath): SyncAction {\n      return new DeleteLocalAction(path.relativePath, path.absolutePath, async (absPath) => {\n        const { unlink } = await import('node:fs/promises')\n        await unlink(absPath)\n      })\n    },\n\n    removeOrphan(dest: B2SyncPath): SyncAction {\n      // Locked buckets: `b2_delete_file_version` is blocked or stacks\n      // hide markers under retention; a hide is the safe choice.\n      // Vanilla buckets: plain delete is the right move — hide markers\n      // would just litter the version history.\n      return bucketIsLocked ? factory.hide(dest.relativePath) : factory.deleteRemote(dest)\n    },\n  }\n\n  return factory\n}\n"],"names":["fileId","fileIdOf"],"mappings":"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"}

package/dist/sync/types.d.cts

@@ -0,0 +1,121 @@
+import { EncryptionSetting } from '../types/encryption.js';
+import { FileVersion } from '../types/file.js';
+/** Strategy for comparing source and destination files: by modification time, size, or skip comparison. */
+export type CompareMode = 'modtime' | 'size' | 'none';
+/** Strategy for handling destination files not present in the source. */
+export type KeepMode = 'no-delete' | 'delete' | 'keep-days';
+/** Direction of a sync operation. */
+export type SyncDirection = 'local-to-b2' | 'b2-to-local' | 'b2-to-b2';
+/** Common metadata for a file discovered during a folder scan. */
+export interface SyncPath {
+    /** Path relative to the sync folder root, using forward slashes. */
+    readonly relativePath: string;
+    /** Last modification time in milliseconds since epoch. */
+    readonly modTimeMillis: number;
+    /** File size in bytes. */
+    readonly size: number;
+}
+/** A file on the local filesystem discovered during a scan. */
+export interface LocalSyncPath extends SyncPath {
+    /** Absolute filesystem path to the file. */
+    readonly absolutePath: string;
+}
+/** A file in a B2 bucket discovered during a scan. */
+export interface B2SyncPath extends SyncPath {
+    /** The most recent visible file version. */
+    readonly selectedVersion: FileVersion;
+    /** All versions of this file, sorted newest first. */
+    readonly allVersions: FileVersion[];
+}
+/** Discriminated event types emitted during synchronization. */
+export type SyncEventType = 'upload-start' | 'upload-done' | 'download-start' | 'download-done' | 'copy-start' | 'copy-done' | 'hide' | 'delete-remote' | 'delete-local' | 'skip' | 'error' | 'compare';
+/**
+ * Action event types: per-file outcomes (transfer / metadata change /
+ * skip) that always carry a `path` and a `size`. These never carry a
+ * `message` because the type tag already says what happened.
+ */
+export type SyncActionEventType = 'upload-start' | 'upload-done' | 'download-start' | 'download-done' | 'copy-start' | 'copy-done' | 'hide' | 'delete-remote' | 'delete-local' | 'compare';
+/**
+ * Per-action progress event (transfer, metadata change, comparison). All
+ * action-event variants share the same shape; the `type` tag distinguishes
+ * them.
+ */
+export interface SyncActionEvent {
+    /** Discriminant tag identifying which action this event reports. */
+    readonly type: SyncActionEventType;
+    /** Relative path of the file this event concerns. */
+    readonly path: string;
+    /** Size in bytes of the file involved, or 0 for metadata-only events. */
+    readonly size: number;
+}
+/**
+ * `skip` event — a destination-only file that policy decided to keep, or
+ * a same-on-both file that didn't need transfer. Always carries a
+ * non-empty `message` explaining why.
+ */
+export interface SyncSkipEvent {
+    /** Discriminant tag (always the literal string `'skip'`). */
+    readonly type: 'skip';
+    /** Relative path of the skipped file. */
+    readonly path: string;
+    /** Size in bytes of the file involved, always 0 for skip events. */
+    readonly size: number;
+    /** Human-readable reason for skipping this file. */
+    readonly message: string;
+}
+/**
+ * `error` event — an action threw or the engine encountered a fatal
+ * condition. Always carries a non-empty `message` describing the failure
+ * so consumers don't need a `message ?? 'unknown'` fallback.
+ */
+export interface SyncErrorEvent {
+    /** Discriminant tag (always the literal string `'error'`). */
+    readonly type: 'error';
+    /** Relative path of the file the failed action targeted, or `''` for engine-level errors. */
+    readonly path: string;
+    /** Size in bytes; always 0 for error events. */
+    readonly size: number;
+    /** Human-readable error message; never empty. */
+    readonly message: string;
+}
+/**
+ * An event emitted by the sync engine to report progress, skip
+ * decisions, or errors. Discriminated by `type`: consumers can
+ * `case 'error':` (or `'skip':`) to narrow into a variant with `message`
+ * guaranteed non-optional.
+ */
+export type SyncEvent = SyncActionEvent | SyncSkipEvent | SyncErrorEvent;
+/** Configuration options for a sync operation. */
+export interface SyncOptions {
+    /** How to decide whether two files differ. */
+    readonly compareMode: CompareMode;
+    /** What to do with destination files absent from the source. */
+    readonly keepMode: KeepMode;
+    /** Number of days to retain orphaned destination files when keepMode is 'keep-days'. */
+    readonly keepDays?: number;
+    /** Maximum number of concurrent transfer actions. Defaults to 4. */
+    readonly concurrency?: number;
+    /** When true, actions are generated but not executed. */
+    readonly dryRun?: boolean;
+    /** Tolerance for comparison (bytes for size, milliseconds for modtime). */
+    readonly compareThreshold?: number;
+    /** Signal to abort the sync operation. */
+    readonly signal?: AbortSignal;
+    /** Optional provider for per-file encryption settings. */
+    readonly encryptionProvider?: SyncEncryptionProvider;
+}
+/** Supplies encryption settings on a per-file basis during sync. */
+export interface SyncEncryptionProvider {
+    /** Returns the encryption setting to use when uploading a file, or undefined for default. */
+    getSettingForUpload(fileName: string, size: number): EncryptionSetting | undefined;
+    /** Returns the encryption setting to use when downloading a file, or undefined for default. */
+    getSettingForDownload(fileVersion: FileVersion): EncryptionSetting | undefined;
+}
+/** A scannable folder (local or B2) that yields files in sorted order. */
+export interface SyncFolder {
+    /** Whether this folder is local or in B2. */
+    readonly type: 'local' | 'b2';
+    /** Scans the folder and yields files sorted by relative path. */
+    scan(): AsyncIterable<SyncPath>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/sync/types.d.cts.map

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

package/dist/sync/types.d.ts

@@ -0,0 +1,121 @@
+import { EncryptionSetting } from '../types/encryption.js';
+import { FileVersion } from '../types/file.js';
+/** Strategy for comparing source and destination files: by modification time, size, or skip comparison. */
+export type CompareMode = 'modtime' | 'size' | 'none';
+/** Strategy for handling destination files not present in the source. */
+export type KeepMode = 'no-delete' | 'delete' | 'keep-days';
+/** Direction of a sync operation. */
+export type SyncDirection = 'local-to-b2' | 'b2-to-local' | 'b2-to-b2';
+/** Common metadata for a file discovered during a folder scan. */
+export interface SyncPath {
+    /** Path relative to the sync folder root, using forward slashes. */
+    readonly relativePath: string;
+    /** Last modification time in milliseconds since epoch. */
+    readonly modTimeMillis: number;
+    /** File size in bytes. */
+    readonly size: number;
+}
+/** A file on the local filesystem discovered during a scan. */
+export interface LocalSyncPath extends SyncPath {
+    /** Absolute filesystem path to the file. */
+    readonly absolutePath: string;
+}
+/** A file in a B2 bucket discovered during a scan. */
+export interface B2SyncPath extends SyncPath {
+    /** The most recent visible file version. */
+    readonly selectedVersion: FileVersion;
+    /** All versions of this file, sorted newest first. */
+    readonly allVersions: FileVersion[];
+}
+/** Discriminated event types emitted during synchronization. */
+export type SyncEventType = 'upload-start' | 'upload-done' | 'download-start' | 'download-done' | 'copy-start' | 'copy-done' | 'hide' | 'delete-remote' | 'delete-local' | 'skip' | 'error' | 'compare';
+/**
+ * Action event types: per-file outcomes (transfer / metadata change /
+ * skip) that always carry a `path` and a `size`. These never carry a
+ * `message` because the type tag already says what happened.
+ */
+export type SyncActionEventType = 'upload-start' | 'upload-done' | 'download-start' | 'download-done' | 'copy-start' | 'copy-done' | 'hide' | 'delete-remote' | 'delete-local' | 'compare';
+/**
+ * Per-action progress event (transfer, metadata change, comparison). All
+ * action-event variants share the same shape; the `type` tag distinguishes
+ * them.
+ */
+export interface SyncActionEvent {
+    /** Discriminant tag identifying which action this event reports. */
+    readonly type: SyncActionEventType;
+    /** Relative path of the file this event concerns. */
+    readonly path: string;
+    /** Size in bytes of the file involved, or 0 for metadata-only events. */
+    readonly size: number;
+}
+/**
+ * `skip` event — a destination-only file that policy decided to keep, or
+ * a same-on-both file that didn't need transfer. Always carries a
+ * non-empty `message` explaining why.
+ */
+export interface SyncSkipEvent {
+    /** Discriminant tag (always the literal string `'skip'`). */
+    readonly type: 'skip';
+    /** Relative path of the skipped file. */
+    readonly path: string;
+    /** Size in bytes of the file involved, always 0 for skip events. */
+    readonly size: number;
+    /** Human-readable reason for skipping this file. */
+    readonly message: string;
+}
+/**
+ * `error` event — an action threw or the engine encountered a fatal
+ * condition. Always carries a non-empty `message` describing the failure
+ * so consumers don't need a `message ?? 'unknown'` fallback.
+ */
+export interface SyncErrorEvent {
+    /** Discriminant tag (always the literal string `'error'`). */
+    readonly type: 'error';
+    /** Relative path of the file the failed action targeted, or `''` for engine-level errors. */
+    readonly path: string;
+    /** Size in bytes; always 0 for error events. */
+    readonly size: number;
+    /** Human-readable error message; never empty. */
+    readonly message: string;
+}
+/**
+ * An event emitted by the sync engine to report progress, skip
+ * decisions, or errors. Discriminated by `type`: consumers can
+ * `case 'error':` (or `'skip':`) to narrow into a variant with `message`
+ * guaranteed non-optional.
+ */
+export type SyncEvent = SyncActionEvent | SyncSkipEvent | SyncErrorEvent;
+/** Configuration options for a sync operation. */
+export interface SyncOptions {
+    /** How to decide whether two files differ. */
+    readonly compareMode: CompareMode;
+    /** What to do with destination files absent from the source. */
+    readonly keepMode: KeepMode;
+    /** Number of days to retain orphaned destination files when keepMode is 'keep-days'. */
+    readonly keepDays?: number;
+    /** Maximum number of concurrent transfer actions. Defaults to 4. */
+    readonly concurrency?: number;
+    /** When true, actions are generated but not executed. */
+    readonly dryRun?: boolean;
+    /** Tolerance for comparison (bytes for size, milliseconds for modtime). */
+    readonly compareThreshold?: number;
+    /** Signal to abort the sync operation. */
+    readonly signal?: AbortSignal;
+    /** Optional provider for per-file encryption settings. */
+    readonly encryptionProvider?: SyncEncryptionProvider;
+}
+/** Supplies encryption settings on a per-file basis during sync. */
+export interface SyncEncryptionProvider {
+    /** Returns the encryption setting to use when uploading a file, or undefined for default. */
+    getSettingForUpload(fileName: string, size: number): EncryptionSetting | undefined;
+    /** Returns the encryption setting to use when downloading a file, or undefined for default. */
+    getSettingForDownload(fileVersion: FileVersion): EncryptionSetting | undefined;
+}
+/** A scannable folder (local or B2) that yields files in sorted order. */
+export interface SyncFolder {
+    /** Whether this folder is local or in B2. */
+    readonly type: 'local' | 'b2';
+    /** Scans the folder and yields files sorted by relative path. */
+    scan(): AsyncIterable<SyncPath>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/sync/types.d.ts.map

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

package/dist/types/auth.cjs

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const Capability = {
+  /** List application keys. */
+  ListKeys: "listKeys",
+  /** Create new application keys. */
+  WriteKeys: "writeKeys",
+  /** Delete application keys. */
+  DeleteKeys: "deleteKeys",
+  /** List buckets (subject to key restrictions). */
+  ListBuckets: "listBuckets",
+  /** List bucket names without other metadata. */
+  ListAllBucketNames: "listAllBucketNames",
+  /** Read bucket settings. */
+  ReadBuckets: "readBuckets",
+  /** Create and update buckets. */
+  WriteBuckets: "writeBuckets",
+  /** Remove existing buckets from the account. */
+  DeleteBuckets: "deleteBuckets",
+  /** Read bucket-level Object Lock retention settings. */
+  ReadBucketRetentions: "readBucketRetentions",
+  /** Modify bucket-level Object Lock retention settings. */
+  WriteBucketRetentions: "writeBucketRetentions",
+  /** Read default bucket encryption settings. */
+  ReadBucketEncryption: "readBucketEncryption",
+  /** Modify default bucket encryption settings. */
+  WriteBucketEncryption: "writeBucketEncryption",
+  /** Read bucket replication configuration. */
+  ReadBucketReplications: "readBucketReplications",
+  /** Modify bucket replication configuration. */
+  WriteBucketReplications: "writeBucketReplications",
+  /** Read bucket event-notification rules. */
+  ReadBucketNotifications: "readBucketNotifications",
+  /** Modify bucket event-notification rules. */
+  WriteBucketNotifications: "writeBucketNotifications",
+  /** List file names and versions. */
+  ListFiles: "listFiles",
+  /** Download files. */
+  ReadFiles: "readFiles",
+  /** Mint download authorisation tokens. */
+  ShareFiles: "shareFiles",
+  /** Upload files. */
+  WriteFiles: "writeFiles",
+  /** Delete file versions. */
+  DeleteFiles: "deleteFiles",
+  /** Read per-file legal hold flags. */
+  ReadFileLegalHolds: "readFileLegalHolds",
+  /** Modify per-file legal hold flags. */
+  WriteFileLegalHolds: "writeFileLegalHolds",
+  /** Read per-file Object Lock retention settings. */
+  ReadFileRetentions: "readFileRetentions",
+  /** Modify per-file Object Lock retention settings. */
+  WriteFileRetentions: "writeFileRetentions",
+  /** Shorten governance-mode retention. */
+  BypassGovernance: "bypassGovernance"
+};
+exports.Capability = Capability;
+//# sourceMappingURL=auth.cjs.map

package/dist/types/auth.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.cjs","sources":["../../src/types/auth.ts"],"sourcesContent":["import type { AccountId, AuthToken, BucketId } from './ids.ts'\n\n/**\n * Named constants for the B2 API capabilities that can be granted to an\n * application key. Each capability controls access to a specific set of\n * API operations.\n *\n * Use these when constructing the `capabilities` array for an application\n * key request, or when checking required capabilities via\n * `B2Client.hasCapabilities`.\n *\n * @example\n * ```ts\n * const check = client.hasCapabilities([Capability.WriteFiles, Capability.ReadFiles])\n * if (!check.ok) throw new Error(`missing: ${check.missing.join(', ')}`)\n * ```\n */\nexport const Capability = {\n  /** List application keys. */\n  ListKeys: 'listKeys',\n  /** Create new application keys. */\n  WriteKeys: 'writeKeys',\n  /** Delete application keys. */\n  DeleteKeys: 'deleteKeys',\n  /** List buckets (subject to key restrictions). */\n  ListBuckets: 'listBuckets',\n  /** List bucket names without other metadata. */\n  ListAllBucketNames: 'listAllBucketNames',\n  /** Read bucket settings. */\n  ReadBuckets: 'readBuckets',\n  /** Create and update buckets. */\n  WriteBuckets: 'writeBuckets',\n  /** Remove existing buckets from the account. */\n  DeleteBuckets: 'deleteBuckets',\n  /** Read bucket-level Object Lock retention settings. */\n  ReadBucketRetentions: 'readBucketRetentions',\n  /** Modify bucket-level Object Lock retention settings. */\n  WriteBucketRetentions: 'writeBucketRetentions',\n  /** Read default bucket encryption settings. */\n  ReadBucketEncryption: 'readBucketEncryption',\n  /** Modify default bucket encryption settings. */\n  WriteBucketEncryption: 'writeBucketEncryption',\n  /** Read bucket replication configuration. */\n  ReadBucketReplications: 'readBucketReplications',\n  /** Modify bucket replication configuration. */\n  WriteBucketReplications: 'writeBucketReplications',\n  /** Read bucket event-notification rules. */\n  ReadBucketNotifications: 'readBucketNotifications',\n  /** Modify bucket event-notification rules. */\n  WriteBucketNotifications: 'writeBucketNotifications',\n  /** List file names and versions. */\n  ListFiles: 'listFiles',\n  /** Download files. */\n  ReadFiles: 'readFiles',\n  /** Mint download authorisation tokens. */\n  ShareFiles: 'shareFiles',\n  /** Upload files. */\n  WriteFiles: 'writeFiles',\n  /** Delete file versions. */\n  DeleteFiles: 'deleteFiles',\n  /** Read per-file legal hold flags. */\n  ReadFileLegalHolds: 'readFileLegalHolds',\n  /** Modify per-file legal hold flags. */\n  WriteFileLegalHolds: 'writeFileLegalHolds',\n  /** Read per-file Object Lock retention settings. */\n  ReadFileRetentions: 'readFileRetentions',\n  /** Modify per-file Object Lock retention settings. */\n  WriteFileRetentions: 'writeFileRetentions',\n  /** Shorten governance-mode retention. */\n  BypassGovernance: 'bypassGovernance',\n} as const\n\n/**\n * A B2 API capability that can be granted to an application key. Derived\n * from {@link Capability}.\n */\nexport type Capability = (typeof Capability)[keyof typeof Capability]\n\n/** Describes the capabilities and scope restrictions of an authorized application key. */\nexport interface AllowedInfo {\n  /** List of capabilities granted to this key. */\n  readonly capabilities: readonly Capability[]\n  /** Bucket ID this key is restricted to, or null if unrestricted. */\n  readonly bucketId: BucketId | null\n  /** Bucket name this key is restricted to, or null if unrestricted. */\n  readonly bucketName: string | null\n  /** File name prefix this key is restricted to, or null if unrestricted. */\n  readonly namePrefix: string | null\n}\n\n/** Configuration for the B2 Cloud Storage API returned during authorization. */\nexport interface StorageApiInfo {\n  /** Minimum allowed part size for large file uploads, in bytes. */\n  readonly absoluteMinimumPartSize: number\n  /** Base URL for B2 API calls. */\n  readonly apiUrl: string\n  /** Bucket ID this key is restricted to, or null if unrestricted. */\n  readonly bucketId: BucketId | null\n  /** Bucket name this key is restricted to, or null if unrestricted. */\n  readonly bucketName: string | null\n  /** Base URL for file downloads. */\n  readonly downloadUrl: string\n  /** Discriminator indicating this is storage API info. Always `'storageApi'`. */\n  readonly infoType: 'storageApi'\n  /** File name prefix this key is restricted to, or null if unrestricted. */\n  readonly namePrefix: string | null\n  /** Recommended part size for large file uploads, in bytes. */\n  readonly recommendedPartSize: number\n  /** Base URL for the S3-compatible API. */\n  readonly s3ApiUrl: string\n  /** Capabilities and scope of the authorized key. */\n  readonly allowed: AllowedInfo\n}\n\n/** Configuration for the B2 Groups API returned during authorization. */\nexport interface GroupsApiInfo {\n  /** Base URL for Groups API calls. */\n  readonly groupsApiUrl: string\n  /** Discriminator indicating this is groups API info. Always `'groupsApi'`. */\n  readonly infoType: 'groupsApi'\n}\n\n/** Container for all API-specific configuration returned by `b2_authorize_account`. */\nexport interface ApiInfo {\n  /** Storage API configuration (always present). */\n  readonly storageApi: StorageApiInfo\n  /** Groups API configuration (present only when the account has groups enabled). */\n  readonly groupsApi?: GroupsApiInfo\n}\n\n/**\n * Response from the `b2_authorize_account` API call.\n * Contains the authorization token and API endpoint URLs needed for subsequent requests.\n */\nexport interface AuthorizeAccountResponse {\n  /** The account ID for the authorized account. */\n  readonly accountId: AccountId\n  /** Authorization token to use in subsequent API calls. */\n  readonly authorizationToken: AuthToken\n  /** API-specific configuration including endpoint URLs and key scope. */\n  readonly apiInfo: ApiInfo\n  /** Expiration timestamp of the application key in milliseconds, or null if the key does not expire. */\n  readonly applicationKeyExpirationTimestamp: number | null\n}\n\n/**\n * Request parameters for the `b2_authorize_account` API call.\n * Credentials are sent via HTTP Basic auth in the raw API, but represented here as fields.\n */\nexport interface AuthorizeAccountRequest {\n  /** The application key ID (account ID or app key ID). */\n  readonly applicationKeyId: string\n  /** The application key secret. */\n  readonly applicationKey: string\n  /** Optional realm override (e.g., `'production'`, `'staging'`). Defaults to production. */\n  readonly realm?: string\n}\n"],"names":[],"mappings":";;AAiBO,MAAM,aAAa;AAAA;AAAA,EAExB,UAAU;AAAA;AAAA,EAEV,WAAW;AAAA;AAAA,EAEX,YAAY;AAAA;AAAA,EAEZ,aAAa;AAAA;AAAA,EAEb,oBAAoB;AAAA;AAAA,EAEpB,aAAa;AAAA;AAAA,EAEb,cAAc;AAAA;AAAA,EAEd,eAAe;AAAA;AAAA,EAEf,sBAAsB;AAAA;AAAA,EAEtB,uBAAuB;AAAA;AAAA,EAEvB,sBAAsB;AAAA;AAAA,EAEtB,uBAAuB;AAAA;AAAA,EAEvB,wBAAwB;AAAA;AAAA,EAExB,yBAAyB;AAAA;AAAA,EAEzB,yBAAyB;AAAA;AAAA,EAEzB,0BAA0B;AAAA;AAAA,EAE1B,WAAW;AAAA;AAAA,EAEX,WAAW;AAAA;AAAA,EAEX,YAAY;AAAA;AAAA,EAEZ,YAAY;AAAA;AAAA,EAEZ,aAAa;AAAA;AAAA,EAEb,oBAAoB;AAAA;AAAA,EAEpB,qBAAqB;AAAA;AAAA,EAErB,oBAAoB;AAAA;AAAA,EAEpB,qBAAqB;AAAA;AAAA,EAErB,kBAAkB;AACpB;;"}