@zero-transfer/mft 0.4.0 → 0.4.2

package/dist/index.d.ts

@@ -833,7 +833,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;
     /**
@@ -1416,9 +1450,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>;
 
@@ -1592,8 +1658,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}. */
@@ -1646,8 +1724,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>;
 
@@ -1754,8 +1860,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;
 
@@ -2493,9 +2620,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[];
@@ -2572,7 +2737,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;
@@ -2852,6 +3051,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>;
 
@@ -2923,6 +3142,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;
 
@@ -3038,9 +3282,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;
 
@@ -3634,9 +3908,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;
 
@@ -3791,7 +4089,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;
@@ -3935,10 +4274,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;