@zero-transfer/sdk 0.4.0 → 0.4.2

package/dist/index.d.mts

@@ -835,7 +835,41 @@ interface TransferEngineOptions {
     /** Clock used for receipts and progress events. Defaults to `new Date()`. */
     now?: () => Date;
 }
-/** Executes transfer jobs and produces audit-friendly receipts. */
+/**
+ * Executes transfer jobs and produces audit-friendly receipts.
+ *
+ * The engine is the lowest-level entry point in the transfer stack: it owns
+ * retry policy, attempt history, abort propagation, progress event
+ * normalization, and receipt construction. Most callers reach the engine
+ * indirectly through {@link runRoute}, {@link uploadFile}, {@link downloadFile},
+ * {@link copyBetween}, or {@link TransferQueue}; instantiate it directly when
+ * you need full control over execution semantics.
+ *
+ * @example Execute a single job with a custom executor
+ * ```ts
+ * import { TransferEngine, type TransferExecutor, type TransferJob } from "@zero-transfer/sdk";
+ *
+ * const engine = new TransferEngine();
+ *
+ * const executor: TransferExecutor = async ({ job, signal, onProgress }) => {
+ *   onProgress?.({ jobId: job.id, bytesTransferred: 0 });
+ *   // … perform the bytes here, honoring `signal` …
+ *   return { jobId: job.id, bytesTransferred: 1234, completedAt: new Date() };
+ * };
+ *
+ * const job: TransferJob = {
+ *   id: "manual-1",
+ *   operation: "upload",
+ *   source: { profile: localProfile, path: "./data.bin" },
+ *   destination: { profile: s3Profile, path: "/data/data.bin" },
+ * };
+ *
+ * const receipt = await engine.execute(job, executor, {
+ *   retry: { maxAttempts: 3, baseDelayMs: 250 },
+ * });
+ * console.log(receipt.attempts.length); // 1 on success
+ * ```
+ */
 declare class TransferEngine {
     private readonly now;
     /**
@@ -1418,9 +1452,41 @@ interface RunRouteOptions {
 /**
  * Executes an MFT route as a single transfer through the supplied client.
  *
+ * Connects the source and destination profiles, runs the route's transfer
+ * through the engine, and returns the resulting receipt. The friendly helpers
+ * {@link uploadFile}, {@link downloadFile}, and {@link copyBetween} synthesize
+ * routes and delegate to this function, so behaviour around retry, abort,
+ * progress, timeout, and bandwidth limits is identical.
+ *
  * @param options - Client, route, and optional engine/abort/retry hooks.
  * @returns Receipt produced by the underlying transfer engine.
  * @throws {@link ConfigurationError} When the route is disabled.
+ *
+ * @example Run a pre-built route with progress + retry
+ * ```ts
+ * import { createTransferClient, runRoute, type MftRoute } from "@zero-transfer/sdk";
+ *
+ * const route: MftRoute = {
+ *   id: "nightly-export",
+ *   operation: "copy",
+ *   source: {
+ *     path: "/exports/daily.csv",
+ *     profile: { host: "sftp.example.com", provider: "sftp", username: "etl" },
+ *   },
+ *   destination: {
+ *     path: "warehouse/daily.csv",
+ *     profile: { host: "warehouse", provider: "s3", s3: { region: "us-east-1" } },
+ *   },
+ * };
+ *
+ * const receipt = await runRoute({
+ *   client,
+ *   route,
+ *   onProgress: (e) => console.log(`${e.bytesTransferred}/${e.totalBytes ?? "?"}`),
+ *   retry: { maxAttempts: 3, baseDelayMs: 500 },
+ * });
+ * console.log(`Job ${receipt.jobId} moved ${receipt.bytesTransferred} bytes…`);
+ * ```
  */
 declare function runRoute(options: RunRouteOptions): Promise<TransferReceipt>;
 
@@ -1594,8 +1660,20 @@ interface ClientDiagnostics {
 /**
  * Returns a redaction-safe snapshot of the providers registered with a client.
  *
+ * Use this when rendering a setup screen, generating a support bundle, or
+ * asserting in tests that the expected provider factories were registered.
+ *
  * @param client - Transfer client to inspect.
  * @returns Provider id and capability snapshot tuples.
+ *
+ * @example List registered providers
+ * ```ts
+ * import { summarizeClientDiagnostics } from "@zero-transfer/sdk";
+ *
+ * for (const { id, capabilities } of summarizeClientDiagnostics(client).providers) {
+ *   console.log(`${id}: streaming=${capabilities.readStream} resume=${capabilities.resumeDownload}`);
+ * }
+ * ```
  */
 declare function summarizeClientDiagnostics(client: TransferClient): ClientDiagnostics;
 /** Per-step duration measurements collected by {@link runConnectionDiagnostics}. */
@@ -1648,8 +1726,36 @@ interface RunConnectionDiagnosticsOptions {
 /**
  * Connects to a profile, captures capability and listing samples, and returns a redaction-safe report.
  *
+ * Useful for connectivity "ping" pages, smoke tests, and bug reports. Secrets
+ * in the profile are redacted via {@link redactConnectionProfile} before being
+ * returned. The session is always disconnected before the function returns,
+ * including when probes throw.
+ *
  * @param options - Diagnostic probe options.
  * @returns Diagnostic report including timings and any captured error.
+ *
+ * @example Probe an SFTP connection
+ * ```ts
+ * import { runConnectionDiagnostics } from "@zero-transfer/sdk";
+ *
+ * const report = await runConnectionDiagnostics({
+ *   client,
+ *   profile: {
+ *     host: "sftp.example.com",
+ *     provider: "sftp",
+ *     username: "deploy",
+ *     ssh: { privateKey: { path: "./keys/id_ed25519" } },
+ *   },
+ *   listPath: "/uploads",
+ * });
+ *
+ * if (!report.ok) {
+ *   console.error("connection failed:", report.error);
+ * } else {
+ *   console.log(`connect=${report.timings.connectMs}ms list=${report.timings.listMs}ms`);
+ *   console.log(report.sample); // up to 5 entries from /uploads
+ * }
+ * ```
  */
 declare function runConnectionDiagnostics(options: RunConnectionDiagnosticsOptions): Promise<ConnectionDiagnosticsResult>;
 
@@ -1802,7 +1908,31 @@ interface DropboxProviderOptions {
  *
  * The bearer token is resolved per-connection from `profile.password`. The
  * `profile.host` field is unused; Dropbox connections are identified solely by
- * their token.
+ * their token. Uploads go to `/2/files/upload` (single-shot); resumable upload
+ * sessions are not yet supported.
+ *
+ * @param options - Optional API base URL overrides and fetch implementation.
+ * @returns Provider factory suitable for `createTransferClient({ providers: [...] })`.
+ *
+ * @example Upload a backup to Dropbox
+ * ```ts
+ * import { createDropboxProviderFactory, createTransferClient, uploadFile } from "@zero-transfer/sdk";
+ *
+ * const client = createTransferClient({ providers: [createDropboxProviderFactory()] });
+ *
+ * await uploadFile({
+ *   client,
+ *   localPath: "./backups/db.dump",
+ *   destination: {
+ *     path: "/Backups/2026-04-28/db.dump",
+ *     profile: {
+ *       host: "",
+ *       provider: "dropbox",
+ *       password: { env: "DROPBOX_ACCESS_TOKEN" },
+ *     },
+ *   },
+ * });
+ * ```
  */
 declare function createDropboxProviderFactory(options?: DropboxProviderOptions): ProviderFactory;
 
@@ -1829,7 +1959,34 @@ interface GoogleDriveProviderOptions {
  * Creates a Google Drive provider factory.
  *
  * The bearer token is resolved per-connection from `profile.password`
- * (typically an OAuth 2 access token). `profile.host` is unused.
+ * (typically an OAuth 2 access token). `profile.host` is unused. Set
+ * `rootFolderId` to scope the provider to a shared-drive subtree instead
+ * of the authenticated user's My Drive root.
+ *
+ * @param options - Optional `rootFolderId`, `fetch`, and default headers.
+ * @returns Provider factory suitable for `createTransferClient({ providers: [...] })`.
+ *
+ * @example Upload to a shared drive folder
+ * ```ts
+ * import { createGoogleDriveProviderFactory, createTransferClient, uploadFile } from "@zero-transfer/sdk";
+ *
+ * const client = createTransferClient({
+ *   providers: [createGoogleDriveProviderFactory({ rootFolderId: "0AB1cDeFG2HiJk" })],
+ * });
+ *
+ * await uploadFile({
+ *   client,
+ *   localPath: "./contracts/2026-Q2.pdf",
+ *   destination: {
+ *     path: "/Contracts/2026-Q2.pdf",
+ *     profile: {
+ *       host: "",
+ *       provider: "google-drive",
+ *       password: { env: "GOOGLE_OAUTH_ACCESS_TOKEN" },
+ *     },
+ *   },
+ * });
+ * ```
  */
 declare function createGoogleDriveProviderFactory(options?: GoogleDriveProviderOptions): ProviderFactory;
 
@@ -1852,7 +2009,40 @@ interface OneDriveProviderOptions {
  * Creates a OneDrive/SharePoint provider factory backed by Microsoft Graph.
  *
  * The bearer token is resolved per-connection from `profile.password`.
- * `profile.host` is unused.
+ * `profile.host` is unused. To target a SharePoint site or specific drive,
+ * override `driveBaseUrl` with `https://graph.microsoft.com/v1.0/drives/{driveId}`.
+ *
+ * @param options - Optional `driveBaseUrl`, `fetch`, and default headers.
+ * @returns Provider factory suitable for `createTransferClient({ providers: [...] })`.
+ *
+ * @example Upload to the authenticated user's OneDrive
+ * ```ts
+ * import { createOneDriveProviderFactory, createTransferClient, uploadFile } from "@zero-transfer/sdk";
+ *
+ * const client = createTransferClient({
+ *   providers: [createOneDriveProviderFactory()],
+ * });
+ *
+ * await uploadFile({
+ *   client,
+ *   localPath: "./report.xlsx",
+ *   destination: {
+ *     path: "/Reports/Q2/report.xlsx",
+ *     profile: {
+ *       host: "",
+ *       provider: "one-drive",
+ *       password: { env: "GRAPH_ACCESS_TOKEN" },
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * @example Target a specific SharePoint drive
+ * ```ts
+ * createOneDriveProviderFactory({
+ *   driveBaseUrl: "https://graph.microsoft.com/v1.0/drives/b!abc123",
+ * });
+ * ```
  */
 declare function createOneDriveProviderFactory(options?: OneDriveProviderOptions): ProviderFactory;
 
@@ -1879,7 +2069,48 @@ interface AzureBlobProviderOptions {
     /** Default headers applied before bearer auth on every request. */
     defaultHeaders?: Record<string, string>;
 }
-/** Creates an Azure Blob Storage provider factory. */
+/**
+ * Creates an Azure Blob Storage provider factory.
+ *
+ * The container is fixed at factory construction time. Authenticate per-connection
+ * with either a SAS token (configured at factory level via {@link AzureBlobProviderOptions.sasToken})
+ * or an AAD bearer token resolved from `profile.password`. Override `endpoint` for
+ * sovereign clouds or local Azurite testing.
+ *
+ * @param options - Container plus optional endpoint, SAS token, fetch override.
+ * @returns Provider factory suitable for `createTransferClient({ providers: [...] })`.
+ *
+ * @example AAD-bearer upload
+ * ```ts
+ * import { createAzureBlobProviderFactory, createTransferClient, uploadFile } from "@zero-transfer/sdk";
+ *
+ * const client = createTransferClient({
+ *   providers: [createAzureBlobProviderFactory({ container: "snapshots" })],
+ * });
+ *
+ * await uploadFile({
+ *   client,
+ *   localPath: "./snapshots/2026-04-28.tar.zst",
+ *   destination: {
+ *     path: "/2026/04/28/snapshot.tar.zst",
+ *     profile: {
+ *       host: "mystorageacct",
+ *       provider: "azure-blob",
+ *       password: { env: "AZURE_AAD_TOKEN" },
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * @example SAS-token + Azurite emulator
+ * ```ts
+ * createAzureBlobProviderFactory({
+ *   container: "devstoreaccount1",
+ *   endpoint: "http://127.0.0.1:10000/devstoreaccount1",
+ *   sasToken: "sv=2024-11-04&ss=b&srt=co&sp=rwdlac&se=...",
+ * });
+ * ```
+ */
 declare function createAzureBlobProviderFactory(options: AzureBlobProviderOptions): ProviderFactory;
 
 /** Options accepted by {@link createGcsProviderFactory}. */
@@ -1897,7 +2128,39 @@ interface GcsProviderOptions {
     /** Default headers applied before bearer auth on every request. */
     defaultHeaders?: Record<string, string>;
 }
-/** Creates a Google Cloud Storage provider factory. */
+/**
+ * Creates a Google Cloud Storage provider factory.
+ *
+ * Authentication is per-connection: pass a Google OAuth 2 access token via
+ * `profile.password`. `profile.host` is unused — the bucket is fixed at
+ * factory construction time so a single client can target multiple buckets
+ * by registering separate factories.
+ *
+ * @param options - Bucket plus optional fetch/transport overrides.
+ * @returns Provider factory suitable for `createTransferClient({ providers: [...] })`.
+ *
+ * @example Bearer-token upload
+ * ```ts
+ * import { createGcsProviderFactory, createTransferClient, uploadFile } from "@zero-transfer/sdk";
+ *
+ * const client = createTransferClient({
+ *   providers: [createGcsProviderFactory({ bucket: "my-bucket" })],
+ * });
+ *
+ * await uploadFile({
+ *   client,
+ *   localPath: "./build/app.tar.gz",
+ *   destination: {
+ *     path: "releases/2026.04/app.tar.gz",
+ *     profile: {
+ *       host: "my-bucket",
+ *       provider: "gcs",
+ *       password: { env: "GCP_OAUTH_ACCESS_TOKEN" },
+ *     },
+ *   },
+ * });
+ * ```
+ */
 declare function createGcsProviderFactory(options: GcsProviderOptions): ProviderFactory;
 
 /** Fixture entry used to seed a memory provider instance. */
@@ -1915,8 +2178,29 @@ interface MemoryProviderOptions {
 /**
  * Creates a provider factory backed by deterministic in-memory fixture entries.
  *
+ * Useful for tests and examples where you want a real `TransferSession` without
+ * touching disk or the network. Entries are pre-seeded; mutations made through
+ * the session are visible to subsequent operations on the same provider.
+ *
  * @param options - Optional fixture entries to expose through the memory provider.
  * @returns Provider factory suitable for `createTransferClient({ providers: [...] })`.
+ *
+ * @example Seed entries and read them back
+ * ```ts
+ * import { createMemoryProviderFactory, createTransferClient } from "@zero-transfer/sdk";
+ *
+ * const client = createTransferClient({
+ *   providers: [createMemoryProviderFactory({
+ *     entries: [
+ *       { path: "/fixtures/hello.txt", content: "hello world" },
+ *       { path: "/fixtures/data.bin", content: new Uint8Array([1, 2, 3]) },
+ *     ],
+ *   })],
+ * });
+ *
+ * const session = await client.connect({ host: "fixtures", provider: "memory" });
+ * console.log(await session.fs.list("/fixtures"));
+ * ```
  */
 declare function createMemoryProviderFactory(options?: MemoryProviderOptions): ProviderFactory;
 
@@ -1936,8 +2220,45 @@ interface HttpProviderOptions {
 /**
  * Creates a provider factory backed by HTTP(S) GET/HEAD.
  *
- * @param options - Optional provider configuration.
+ * Read-only by design — use it to fetch artifacts from public URLs, signed
+ * URLs, or HTTP-only artifact servers. Range-based resume is supported when
+ * the server advertises `Accept-Ranges: bytes`. To upload to an HTTP endpoint,
+ * use the WebDAV provider, the S3 provider, or a cloud-specific provider.
+ *
+ * @param options - Optional id, base path, secure flag, fetch override.
  * @returns Provider factory suitable for `createTransferClient({ providers: [...] })`.
+ *
+ * @example Download a public artifact
+ * ```ts
+ * import { createHttpProviderFactory, createTransferClient, downloadFile } from "@zero-transfer/sdk";
+ *
+ * const client = createTransferClient({ providers: [createHttpProviderFactory()] });
+ *
+ * await downloadFile({
+ *   client,
+ *   localPath: "./tmp/release.tar.gz",
+ *   source: {
+ *     path: "/releases/v1.0.0/release.tar.gz",
+ *     profile: { host: "downloads.example.com", provider: "http" },
+ *   },
+ * });
+ * ```
+ *
+ * @example Bearer-token-protected endpoint
+ * ```ts
+ * await downloadFile({
+ *   client,
+ *   localPath: "./reports/today.json",
+ *   source: {
+ *     path: "/reports/today.json",
+ *     profile: {
+ *       host: "api.example.com",
+ *       provider: "http",
+ *       password: { env: "REPORTS_TOKEN" },
+ *     },
+ *   },
+ * });
+ * ```
  */
 declare function createHttpProviderFactory(options?: HttpProviderOptions): ProviderFactory;
 
@@ -1975,8 +2296,39 @@ interface WebDavProviderOptions {
 /**
  * Creates a WebDAV provider factory.
  *
- * @param options - Optional provider configuration.
+ * Talks to any RFC 4918 server: Nextcloud, ownCloud, sabre/dav, Apache `mod_dav`,
+ * IIS WebDAV, etc. PROPFIND drives directory listings, GET supports byte-range
+ * resume on download, and PUT handles uploads. Server-side `COPY` is exposed via
+ * the capability set. Authentication is per-connection from `profile.password`.
+ *
+ * @param options - Optional id, base path, secure flag, fetch, streaming policy.
  * @returns Provider factory suitable for `createTransferClient({ providers: [...] })`.
+ *
+ * @example Upload to Nextcloud
+ * ```ts
+ * import { createTransferClient, createWebDavProviderFactory, uploadFile } from "@zero-transfer/sdk";
+ *
+ * const client = createTransferClient({
+ *   providers: [createWebDavProviderFactory({
+ *     secure: true,
+ *     basePath: "/remote.php/dav/files/alice",
+ *   })],
+ * });
+ *
+ * await uploadFile({
+ *   client,
+ *   localPath: "./contracts/2026.pdf",
+ *   destination: {
+ *     path: "/Documents/Contracts/2026.pdf",
+ *     profile: {
+ *       host: "cloud.example.com",
+ *       provider: "webdav",
+ *       username: "alice",
+ *       password: { env: "NEXTCLOUD_APP_PASSWORD" },
+ *     },
+ *   },
+ * });
+ * ```
  */
 declare function createWebDavProviderFactory(options?: WebDavProviderOptions): ProviderFactory;
 
@@ -3967,9 +4319,47 @@ interface TransferPlanSummary {
     /** Counts grouped by action. */
     actions: Record<string, number>;
 }
-/** Creates a transfer plan from dry-run planning input. */
+/**
+ * Creates a transfer plan from dry-run planning input.
+ *
+ * Plans are immutable, structured descriptions of intended work. Pair with
+ * {@link createSyncPlan} or {@link createAtomicDeployPlan} for end-to-end
+ * planning, or build steps by hand when you need full control. Pass the plan
+ * to {@link createTransferJobsFromPlan} to materialize executable jobs.
+ *
+ * @example Build a plan with two upload steps and inspect it
+ * ```ts
+ * import { createTransferPlan, summarizeTransferPlan } from "@zero-transfer/sdk";
+ *
+ * const plan = createTransferPlan({
+ *   id: "manual-batch",
+ *   steps: [
+ *     { action: "upload", source: "./a.bin", destination: "/lake/a.bin", expectedBytes: 1024 },
+ *     { action: "upload", source: "./b.bin", destination: "/lake/b.bin", expectedBytes: 2048 },
+ *   ],
+ * });
+ *
+ * console.table(summarizeTransferPlan(plan));
+ * ```
+ */
 declare function createTransferPlan(input: TransferPlanInput): TransferPlan;
-/** Summarizes a transfer plan for diagnostics, previews, and tests. */
+/**
+ * Summarizes a transfer plan for diagnostics, previews, and tests.
+ *
+ * Returns aggregate counts (total / executable / skipped / destructive),
+ * total expected bytes, and a per-action histogram. Useful for printing a
+ * one-line plan summary before executing or for asserting plan shape in
+ * tests.
+ *
+ * @example Print a plan preview
+ * ```ts
+ * import { summarizeTransferPlan } from "@zero-transfer/sdk";
+ *
+ * const summary = summarizeTransferPlan(plan);
+ * console.log(`${summary.executableSteps} steps, ${summary.totalExpectedBytes} bytes total`);
+ * console.log("Actions:", summary.actions);
+ * ```
+ */
 declare function summarizeTransferPlan(plan: TransferPlan): TransferPlanSummary;
 /** Converts executable plan steps into transfer jobs while preserving order. */
 declare function createTransferJobsFromPlan(plan: TransferPlan): TransferJob[];
@@ -4046,7 +4436,41 @@ interface TransferQueueSummary {
     /** Failed queue items in queue order. */
     failures: TransferQueueItem[];
 }
-/** Minimal transfer queue with concurrency, pause/resume, cancellation, and drain summaries. */
+/**
+ * Minimal transfer queue with concurrency, pause/resume, cancellation, and drain summaries.
+ *
+ * Wrap a {@link TransferEngine} with a queue when you need to run many transfers
+ * concurrently with bounded parallelism, observe per-job progress, or drive
+ * a UI from a single source of truth. Items are FIFO; failures and successes
+ * are surfaced via observers and in the final {@link TransferQueueSummary}.
+ *
+ * @example Run a batch of uploads with concurrency=4
+ * ```ts
+ * import {
+ *   TransferQueue,
+ *   createProviderTransferExecutor,
+ * } from "@zero-transfer/sdk";
+ *
+ * const queue = new TransferQueue({
+ *   concurrency: 4,
+ *   executor: createProviderTransferExecutor({ client }),
+ *   onProgress: (e) => console.log(`${e.jobId}: ${e.bytesTransferred}`),
+ *   onError: (item, err) => console.error(`${item.job.id} failed`, err),
+ * });
+ *
+ * for (const file of files) {
+ *   queue.enqueue({
+ *     id: file.name,
+ *     operation: "upload",
+ *     source: { profile: localProfile, path: file.path },
+ *     destination: { profile: s3Profile, path: `/lake/${file.name}` },
+ *   });
+ * }
+ *
+ * const summary = await queue.drain();
+ * console.log(`Completed ${summary.completed} / ${summary.total}`);
+ * ```
+ */
 declare class TransferQueue {
     private readonly engine;
     private readonly items;
@@ -4326,6 +4750,26 @@ interface DiffRemoteTreesOptions {
  * @param destinationPath - Destination-side root path being compared.
  * @param options - Optional comparison controls.
  * @returns Diff result containing entries and a summary.
+ *
+ * @example Diff two SFTP subtrees and feed the result into createSyncPlan
+ * ```ts
+ * import { createSyncPlan, diffRemoteTrees } from "@zero-transfer/sdk";
+ *
+ * const diff = await diffRemoteTrees(
+ *   srcSession.fs, "/exports",
+ *   dstSession.fs, "/exports",
+ *   { compareUniqueId: true },
+ * );
+ *
+ * console.log(diff.summary); // { added, removed, changed, unchanged }
+ *
+ * const plan = createSyncPlan({
+ *   id: "exports-sync",
+ *   diff,
+ *   source: { provider: "sftp", rootPath: "/exports" },
+ *   destination: { provider: "sftp", rootPath: "/exports" },
+ * });
+ * ```
  */
 declare function diffRemoteTrees(source: RemoteFileSystem, sourcePath: string, destination: RemoteFileSystem, destinationPath: string, options?: DiffRemoteTreesOptions): Promise<RemoteTreeDiff>;
 
@@ -4397,6 +4841,31 @@ interface CreateSyncPlanOptions {
  * @param options - Inputs and policies that shape the plan.
  * @returns Transfer plan ready for `createTransferJobsFromPlan` or queue execution.
  * @throws {@link ConfigurationError} When `conflictPolicy: "error"` encounters a conflict.
+ *
+ * @example Mirror SFTP → S3 with deletes
+ * ```ts
+ * import {
+ *   createSyncPlan,
+ *   diffRemoteTrees,
+ *   summarizeTransferPlan,
+ * } from "@zero-transfer/sdk";
+ *
+ * const diff = await diffRemoteTrees(
+ *   srcSession.fs, "/dist",
+ *   dstSession.fs, "/releases/current",
+ * );
+ *
+ * const plan = createSyncPlan({
+ *   id: "release-mirror",
+ *   diff,
+ *   source: { provider: "sftp", rootPath: "/dist" },
+ *   destination: { provider: "s3", rootPath: "/releases/current" },
+ *   deletePolicy: "mirror",
+ *   conflictPolicy: "overwrite",
+ * });
+ *
+ * console.table(summarizeTransferPlan(plan));
+ * ```
  */
 declare function createSyncPlan(options: CreateSyncPlanOptions): TransferPlan;
 
@@ -4512,9 +4981,39 @@ interface CreateAtomicDeployPlanOptions {
 /**
  * Builds an {@link AtomicDeployPlan} that stages a release, swaps it live, and prunes old releases.
  *
+ * The plan describes a blue/green-style deploy:
+ *  1. Upload to a timestamped staging directory under `<destination>/.releases/`.
+ *  2. Atomically swap the `current` symlink/rename to point at the new release.
+ *  3. Optionally prune old releases beyond `retain`.
+ *
+ * No I/O is performed — the host executes the plan steps. Pair with
+ * {@link createTransferPlan} or {@link createTransferJobsFromPlan} to execute.
+ *
  * @param options - Inputs and policies that shape the deploy.
  * @returns Structured deploy plan ready for execution by the calling host.
  * @throws {@link ConfigurationError} When `retain` is less than `1` or the destination root is empty.
+ *
+ * @example Plan a release with rollback path
+ * ```ts
+ * import { createAtomicDeployPlan } from "@zero-transfer/sdk";
+ *
+ * const plan = createAtomicDeployPlan({
+ *   id: "web-2026-04-28",
+ *   source: { rootPath: "./dist" },
+ *   destination: {
+ *     profile: { host: "web1.example.com", provider: "sftp", username: "deploy" },
+ *     rootPath: "/srv/www",
+ *   },
+ *   retain: 5,
+ *   existingReleases: [
+ *     "/srv/www/.releases/2026-04-21T00-00-00Z",
+ *     "/srv/www/.releases/2026-04-14T00-00-00Z",
+ *   ],
+ * });
+ *
+ * console.log(plan.swap);   // staging → current rename
+ * console.log(plan.prune);  // releases scheduled for removal
+ * ```
  */
 declare function createAtomicDeployPlan(options: CreateAtomicDeployPlanOptions): AtomicDeployPlan;
 
@@ -5014,9 +5513,33 @@ interface CreateWebhookAuditLogOptions {
  *
  * Entries whose `type` is not in `target.types` are silently dropped. `list()`
  * always returns an empty array because webhook deliveries are not buffered.
+ * Payloads are HMAC-signed with `target.secret` (when provided) so receivers
+ * can verify authenticity before acting on them.
  *
  * @param options - Webhook target plus optional retry/observer hooks.
  * @returns An audit log that delivers each `record` call to the webhook.
+ *
+ * @example Compose a webhook log with an in-memory log for local replay
+ * ```ts
+ * import {
+ *   InMemoryAuditLog,
+ *   composeAuditLogs,
+ *   createWebhookAuditLog,
+ * } from "@zero-transfer/sdk";
+ *
+ * const memory = new InMemoryAuditLog();
+ * const webhook = createWebhookAuditLog({
+ *   target: {
+ *     url: "https://hooks.example.com/zt",
+ *     secret: { env: "ZT_WEBHOOK_SECRET" },
+ *     types: ["transfer.success", "transfer.failure"],
+ *   },
+ *   onDelivery: ({ result }) => console.log("delivered", result.statusCode),
+ * });
+ *
+ * const audit = composeAuditLogs(memory, webhook);
+ * await audit.record({ type: "transfer.success", receipt });
+ * ```
  */
 declare function createWebhookAuditLog(options: CreateWebhookAuditLogOptions): MftAuditLog;
 
@@ -5171,7 +5694,48 @@ interface MftSchedulerOptions {
     /** Timer/clock injection used by tests. */
     timer?: ScheduleTimerHooks;
 }
-/** Runs routes on configured schedules. */
+/**
+ * Runs routes on configured schedules.
+ *
+ * Subscribes to a {@link ScheduleRegistry}, computes the next fire time for
+ * each schedule (cron or interval), and dispatches the matching route through
+ * a runner of your choice (`runRoute` by default, or a wrapped runner for
+ * approvals / rate limiting / circuit breaking). Observers fire on each cycle
+ * for telemetry. Tests can inject a deterministic timer via `timer`.
+ *
+ * @example Wire a cron schedule with audit + approval
+ * ```ts
+ * import {
+ *   ApprovalRegistry,
+ *   InMemoryAuditLog,
+ *   MftScheduler,
+ *   RouteRegistry,
+ *   ScheduleRegistry,
+ *   createApprovalGate,
+ *   runRoute,
+ * } from "@zero-transfer/sdk";
+ *
+ * const audit = new InMemoryAuditLog();
+ * const approvals = new ApprovalRegistry();
+ *
+ * const scheduler = new MftScheduler({
+ *   client,
+ *   routes: new RouteRegistry([route]),
+ *   schedules: new ScheduleRegistry([
+ *     { id: "nightly", routeId: route.id, cron: "0 2 * * *" },
+ *   ]),
+ *   runner: createApprovalGate({
+ *     registry: approvals,
+ *     approvalId: ({ route }) => `release:${route.id}`,
+ *     runner: ({ client: c, route: r, signal }) => runRoute({ client: c, route: r, signal }),
+ *   }),
+ *   onResult: ({ receipt }) => audit.record({ type: "transfer.success", receipt }),
+ *   onError:  ({ error })   => audit.record({ type: "transfer.failure", error }),
+ * });
+ *
+ * scheduler.start();
+ * ```
+ */
 declare class MftScheduler {
     private readonly options;
     private readonly now;
@@ -5315,10 +5879,33 @@ interface CreateApprovalGateOptions {
  *
  * The returned runner creates an approval request, waits for resolution, and
  * dispatches the underlying runner only when the request is approved. Rejection
- * surfaces an {@link ApprovalRejectedError}.
+ * surfaces an {@link ApprovalRejectedError}. Pair with {@link MftScheduler} to
+ * implement two-person rules and human-in-the-loop release flows.
  *
  * @param options - Registry, downstream runner, approval-id derivation, hooks.
  * @returns A {@link ScheduleRouteRunner} that gates execution behind approval.
+ *
+ * @example Two-person rule on a release route
+ * ```ts
+ * import {
+ *   ApprovalRegistry,
+ *   createApprovalGate,
+ *   runRoute,
+ * } from "@zero-transfer/sdk";
+ *
+ * const approvals = new ApprovalRegistry();
+ *
+ * const gatedRunner = createApprovalGate({
+ *   registry: approvals,
+ *   approvalId: ({ route }) => `release:${route.id}:${Date.now()}`,
+ *   onRequested: (req) => notifyOnCallChannel(req),
+ *   runner: ({ client, route, signal }) => runRoute({ client, route, signal }),
+ * });
+ *
+ * // Elsewhere, an authorized operator approves or rejects:
+ * approvals.approve(approvalId, { actor: "alice@example.com" });
+ * // approvals.reject(approvalId, { actor: "bob@example.com", reason: "hold release" });
+ * ```
  */
 declare function createApprovalGate(options: CreateApprovalGateOptions): ScheduleRouteRunner;