@zero-transfer/sdk 0.4.0 → 0.4.6

package/dist/index.d.ts

@@ -396,7 +396,7 @@ interface TlsProfile {
      * hex form with or without colons. When present, the TLS handshake additionally requires the
      * leaf certificate's SHA-256 fingerprint to match one of these values.
      *
-     * Not required for normal CA-trusted endpoints — public CAs and `ca` bundles already gate
+     * Not required for normal CA-trusted endpoints - public CAs and `ca` bundles already gate
      * trust via `rejectUnauthorized`. Pinning is **recommended for production** when you control
      * the server and want defence-in-depth against rogue certificates issued by trusted CAs.
      *
@@ -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>;
 
@@ -1658,7 +1764,7 @@ interface ConnectionPoolOptions {
     /**
      * Maximum number of *idle* sessions retained per pool key.
      *
-     * Active leases are not counted against this limit — the cap only applies
+     * Active leases are not counted against this limit - the cap only applies
      * to sessions waiting in the pool. When more than `maxIdlePerKey` sessions
      * become idle simultaneously, the oldest ones are disconnected. Defaults
      * to `4`.
@@ -1717,9 +1823,9 @@ declare function createPooledTransferClient(inner: TransferClient, options?: Con
  *
  * Aggregates the {@link CapabilitySet} advertised by every shipped provider
  * factory so applications, docs, and diagnostics can compare features across
- * providers without instantiating each one. The S3 entry is captured twice —
+ * providers without instantiating each one. The S3 entry is captured twice -
  * once with the new multipart-by-default configuration and once with
- * `multipart.enabled: false` for the legacy single-shot variant — because
+ * `multipart.enabled: false` for the legacy single-shot variant - because
  * that flag flips `resumeUpload`.
  *
  * @module providers/capabilityMatrix
@@ -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;
 
@@ -1847,12 +2004,64 @@ interface OneDriveProviderOptions {
     fetch?: HttpFetch;
     /** Default headers applied before bearer auth on every request. */
     defaultHeaders?: Record<string, string>;
+    /** Resumable upload session tuning. Enabled by default. */
+    multipart?: OneDriveMultipartOptions;
+}
+/** Resumable-upload session tuning for the OneDrive provider. */
+interface OneDriveMultipartOptions {
+    /**
+     * Enable Microsoft Graph upload sessions. **Defaults to `true`** so payloads
+     * above {@link OneDriveMultipartOptions.thresholdBytes} stream in fixed-size
+     * chunks via `createUploadSession` instead of being buffered into a single
+     * `PUT /content`. Set to `false` to force the legacy single-shot behaviour.
+     */
+    enabled?: boolean;
+    /** Object size threshold above which an upload session is used. Defaults to 4 MiB. */
+    thresholdBytes?: number;
+    /**
+     * Target chunk size in bytes. Must be a multiple of 320 KiB per the Graph
+     * protocol (the final chunk is exempt). Defaults to 10 MiB.
+     */
+    partSizeBytes?: number;
 }
 /**
  * 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;
 
@@ -1878,8 +2087,65 @@ interface AzureBlobProviderOptions {
     fetch?: HttpFetch;
     /** Default headers applied before bearer auth on every request. */
     defaultHeaders?: Record<string, string>;
+    /** Multipart (staged-block) upload tuning. Enabled by default. */
+    multipart?: AzureBlobMultipartOptions;
+}
+/** Multipart (staged block) upload tuning for the Azure Blob provider. */
+interface AzureBlobMultipartOptions {
+    /**
+     * Enable staged-block uploads via `Put Block` + `Put Block List`. **Defaults
+     * to `true`** so payloads above {@link AzureBlobMultipartOptions.thresholdBytes}
+     * stream in fixed-size blocks instead of being buffered into a single PUT.
+     * Set to `false` to force single-shot block-blob PUTs.
+     */
+    enabled?: boolean;
+    /** Object size threshold above which staged-block upload is used. Defaults to 8 MiB. */
+    thresholdBytes?: number;
+    /** Target block size in bytes. Defaults to 8 MiB. Maximum 4000 MiB per Azure. */
+    partSizeBytes?: number;
 }
-/** 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}. */
@@ -1896,8 +2162,60 @@ interface GcsProviderOptions {
     fetch?: HttpFetch;
     /** Default headers applied before bearer auth on every request. */
     defaultHeaders?: Record<string, string>;
+    /** Resumable upload session tuning. Enabled by default. */
+    multipart?: GcsMultipartOptions;
 }
-/** Creates a Google Cloud Storage provider factory. */
+/** Resumable-upload session tuning for the GCS provider. */
+interface GcsMultipartOptions {
+    /**
+     * Enable resumable upload sessions. **Defaults to `true`** so payloads above
+     * {@link GcsMultipartOptions.thresholdBytes} stream in fixed-size chunks via
+     * the resumable session endpoint instead of being buffered into a single
+     * `uploadType=media` POST. Set to `false` to force the legacy single-shot
+     * behaviour.
+     */
+    enabled?: boolean;
+    /** Object size threshold above which a resumable session is used. Defaults to 8 MiB. */
+    thresholdBytes?: number;
+    /**
+     * Target chunk size in bytes. Must be a multiple of 256 KiB per the GCS
+     * protocol (the final chunk is exempt). Defaults to 8 MiB.
+     */
+    partSizeBytes?: number;
+}
+/**
+ * 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 +2233,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 +2275,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;
 
@@ -1956,18 +2332,18 @@ interface WebDavProviderOptions {
     /**
      * Streaming policy for `PUT` request bodies.
      *
-     * - `"when-known-size"` (default) — stream when the caller declares
+     * - `"when-known-size"` (default) - stream when the caller declares
      *   `request.totalBytes` (an explicit `Content-Length` is sent so all
      *   WebDAV servers accept the upload); otherwise buffer the entire body in
      *   memory before sending. This is the safe default that does not require
      *   the server to accept HTTP/1.1 chunked transfer-encoding.
-     * - `"always"` — always stream the body, even when the size is unknown
+     * - `"always"` - always stream the body, even when the size is unknown
      *   (the runtime will use chunked transfer-encoding). Some legacy WebDAV
      *   servers reject `Transfer-Encoding: chunked` and will respond `411
      *   Length Required` or `501 Not Implemented`; only enable this for
      *   servers known to accept chunked uploads (modern Apache/nginx, IIS
      *   with chunked transfer enabled, Nextcloud, ownCloud, sabre/dav).
-     * - `"never"` — always buffer (legacy behaviour pre-0.4.0). Use for
+     * - `"never"` - always buffer (legacy behaviour pre-0.4.0). Use for
      *   maximum compatibility at the cost of memory.
      */
     uploadStreaming?: "when-known-size" | "always" | "never";
@@ -1975,8 +2351,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;
 
@@ -3010,7 +3417,7 @@ interface SshKeyboardInteractiveCredential {
 type SshCredential = SshPasswordCredential | SshPublickeyCredential | SshKeyboardInteractiveCredential;
 interface SshAuthOptions {
     credential: SshCredential;
-    /** SSH session id (exchange hash) from key exchange — required for publickey signing. */
+    /** SSH session id (exchange hash) from key exchange - required for publickey signing. */
     sessionId: Uint8Array;
     /** Maximum number of USERAUTH_FAILURE retries before giving up. Defaults to 4. */
     maxAttempts?: number;
@@ -3252,6 +3659,71 @@ declare class SshDataWriter {
     private assertByte;
 }
 
+/**
+ * Options for {@link runSshCommand}.
+ */
+interface RunSshCommandOptions {
+    /** Hostname or IP of the SSH server. */
+    host: string;
+    /** TCP port. Defaults to `22`. */
+    port?: number;
+    /** Command to execute on the remote shell. */
+    command: string;
+    /**
+     * Authentication credential. Use one of:
+     *
+     * - `{ type: "password", username, password }`
+     * - `{ type: "publickey", username, algorithmName, publicKeyBlob, sign }`
+     *   (build one from a private-key file with `buildPublickeyCredential`)
+     * - `{ type: "keyboard-interactive", username, respond }`
+     */
+    auth: SshCredential;
+    /**
+     * Forwarded to {@link SshTransportConnection}; covers host-key pinning,
+     * algorithm overrides, and handshake timeout. The default
+     * `handshakeTimeoutMs` is 10 seconds.
+     */
+    transport?: SshTransportConnectionOptions;
+    /** TCP connect timeout in milliseconds. Defaults to 10 000. */
+    connectTimeoutMs?: number;
+    /** Maximum total bytes captured from stdout. Defaults to 16 MiB. */
+    maxOutputBytes?: number;
+}
+/**
+ * Result of {@link runSshCommand}. The full captured stdout is provided as
+ * both a `Buffer` (for binary output) and as a UTF-8 decoded `string`.
+ *
+ * Note: stderr (CHANNEL_EXTENDED_DATA) and exit-status are not currently
+ * surfaced - drop down to {@link SshConnectionManager}/{@link SshSessionChannel}
+ * directly if you need them.
+ */
+interface RunSshCommandResult {
+    /** Captured stdout as raw bytes. */
+    stdout: Buffer;
+    /** Captured stdout decoded as UTF-8. */
+    stdoutText: string;
+    /** Bytes received before the channel closed. */
+    bytesReceived: number;
+}
+/**
+ * Connects, authenticates, runs `command` on a fresh exec channel, drains
+ * stdout, and disconnects. The TCP socket, transport, auth session, and
+ * channel are all owned by this helper and torn down before it returns.
+ *
+ * @example Run `uname -a` with a password credential
+ * ```ts
+ * import { runSshCommand } from "@zero-transfer/ssh";
+ *
+ * const { stdoutText } = await runSshCommand({
+ *   host: "ssh.example.com",
+ *   auth: { type: "password", username: "deploy", password: process.env.SSH_PASSWORD! },
+ *   command: "uname -a",
+ * });
+ * console.log(stdoutText);
+ * ```
+ */
+declare function runSshCommand(options: RunSshCommandOptions): Promise<RunSshCommandResult>;
+
 /**
  * FTPS control-channel TLS mode.
  *
@@ -3294,7 +3766,7 @@ interface FtpsProviderOptions extends FtpProviderOptions {
  * @param options - Optional provider defaults.
  * @returns Provider factory suitable for `createTransferClient({ providers: [...] })`.
  *
- * @example Plain FTP (cleartext — prefer FTPS or SFTP whenever possible)
+ * @example Plain FTP (cleartext - prefer FTPS or SFTP whenever possible)
  * ```ts
  * import { createFtpProviderFactory, createTransferClient } from "@zero-transfer/sdk";
  *
@@ -3698,7 +4170,7 @@ interface NativeSftpRawSession {
 }
 /**
  * Creates a {@link ProviderFactory} backed by the native SSH/SFTP protocol
- * stack — no `ssh2` dependency required.
+ * stack - no `ssh2` dependency required.
  *
  * **Supported algorithms**
  * - Key exchange: `curve25519-sha256`, `curve25519-sha256@libssh.org`
@@ -3967,9 +4439,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 +4556,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;
@@ -4317,7 +4861,7 @@ interface DiffRemoteTreesOptions {
  * Compares two remote subtrees and produces an entry-level diff.
  *
  * Source and destination paths are walked independently; entries are then aligned by
- * the relative path from each tree root. Directory equality is structural — directories
+ * the relative path from each tree root. Directory equality is structural - directories
  * are equal when their relative paths match and the entry types agree.
  *
  * @param source - Source-side remote file system.
@@ -4326,6 +4870,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 +4961,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 +5101,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 +5633,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 +5814,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 +5999,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;
 
@@ -5393,4 +6100,10 @@ declare function joinRemotePath(...segments: string[]): string;
  */
 declare function basenameRemotePath(input: string): string;
 
-export { AbortError, type AgeRetentionPolicy, ApprovalRegistry, ApprovalRejectedError, type ApprovalRequest, type ApprovalStatus, type AtomicDeployActivateOperation, type AtomicDeployActivateStep, type AtomicDeployPlan, type AtomicDeployPruneStep, type AtomicDeployStrategy, type AuthenticationCapability, AuthenticationError, AuthorizationError, type AzureBlobProviderOptions, type BandwidthSleep, type BandwidthThrottle, type BandwidthThrottleOptions, type Base64EnvSecretSource, type BuiltInProviderId, type BuiltinCapabilityMatrixEntry, type BuiltinProviderMatrixId, CLASSIC_PROVIDER_IDS, type CapabilitySet, type ChecksumCapability, type ClassicProviderId, type ClientDiagnostics, type CompareRemoteManifestsOptions, ConfigurationError, type ConnectionDiagnosticTimings, type ConnectionDiagnosticsResult, ConnectionError, type ConnectionPoolOptions, type ConnectionProfile, type ConventionEndpoint, type CopyBetweenOptions, type CountRetentionPolicy, type CreateApprovalGateOptions, type CreateAtomicDeployPlanOptions, type CreateInboxRouteOptions, type CreateOutboxRouteOptions, type CreateRemoteBrowserOptions, type CreateRemoteManifestOptions, type CreateSyncPlanOptions, type CreateWebhookAuditLogOptions, type CronExpression, type CronField, type CronScheduleTrigger, DEFAULT_FAILED_SUBDIR, DEFAULT_PROCESSED_SUBDIR, DEFAULT_SSH_ALGORITHM_PREFERENCES, type DiffRemoteTreesOptions, type DispatchWebhookOptions, type DispatchWebhookResult, type DownloadFileOptions, type DropboxProviderOptions, type EnvSecretSource, type EvaluateRetentionOptions, type FileSecretSource, type FileSystemS3MultipartResumeStoreOptions, type FileZillaSite, type FriendlyTransferOptions, type FtpFeatures, type FtpPassiveHostStrategy, type FtpProviderOptions, type FtpReplyErrorInput, type FtpResponse, FtpResponseParser, type FtpResponseStatus, type FtpsDataProtection, type FtpsMode, type FtpsProviderOptions, type GcsProviderOptions, type GoogleDriveProviderOptions, type HttpFetch, type HttpProviderOptions, type ImportFileZillaSitesResult, type ImportOpenSshConfigOptions, type ImportOpenSshConfigResult, type ImportWinScpSessionsResult, InMemoryAuditLog, type IntervalScheduleTrigger, type JsonlWriter, type KnownHostsEntry, type KnownHostsMarker, type ListOptions, type LocalProviderOptions, type LogLevel, type LogRecord, type LogRecordInput, type LoggerMethod, type MemoryProviderEntry, type MemoryProviderOptions, type MetadataCapability, type MftAuditEntry, type MftAuditEntryType, type MftAuditLog, type MftInboxConvention, type MftOutboxConvention, type MftRoute, type MftRouteEndpoint, type MftRouteFilter, type MftRouteOperation, type MftSchedule, type MftScheduleTrigger, MftScheduler, type MftSchedulerOptions, type MkdirOptions, type NativeSftpProviderOptions, type NativeSftpRawSession, type NegotiatedSshAlgorithms, type OAuthAccessToken, type OAuthRefreshCallback, type OAuthTokenSecretSourceOptions, type OneDriveProviderOptions, type OpenSshConfigEntry, ParseError, PathAlreadyExistsError, PathNotFoundError, PermissionDeniedError, type PooledTransferClient, type ProgressEventInput, ProtocolError, type AuthenticationCapability as ProviderAuthenticationCapability, type CapabilitySet as ProviderCapabilities, type ChecksumCapability as ProviderChecksumCapability, type ProviderFactory, type ProviderId, type MetadataCapability as ProviderMetadataCapability, ProviderRegistry, type ProviderSelection, type ProviderTransferEndpointRole, type ProviderTransferExecutorOptions, type ProviderTransferOperations, type ProviderTransferReadRequest, type ProviderTransferReadResult, type ProviderTransferRequest, type ProviderTransferSessionResolver, type ProviderTransferSessionResolverInput, type ProviderTransferWriteRequest, type ProviderTransferWriteResult, REDACTED, REMOTE_MANIFEST_FORMAT_VERSION, type RemoteBreadcrumb, type RemoteBrowser, type RemoteBrowserFilter, type RemoteBrowserSnapshot, type RemoteEntry, type RemoteEntrySortKey, type RemoteEntrySortOrder, type RemoteEntryType, type RemoteFileAdapter, type RemoteFileEndpoint, type RemoteFileSystem, type RemoteManifest, type RemoteManifestEntry, type RemotePermissions, type RemoteProtocol, type RemoteStat, type RemoteTreeDiff, type RemoteTreeDiffEntry, type RemoteTreeDiffReason, type RemoteTreeDiffStatus, type RemoteTreeDiffSummary, type RemoteTreeEntry, type RemoteTreeFilter, type RemoveOptions, type RenameOptions, type ResolveSecretOptions, type ResolvedConnectionProfile, type ResolvedOpenSshHost, type ResolvedSshProfile, type ResolvedTlsProfile, type RetentionEvaluation, type RetentionPolicy, type RmdirOptions, RouteRegistry, type RunConnectionDiagnosticsOptions, type RunRouteOptions, type S3MultipartCheckpoint, type S3MultipartOptions, type S3MultipartPart, type S3MultipartResumeKey, type S3MultipartResumeStore, type S3ProviderOptions, ScheduleRegistry, type ScheduleRouteRunner, type ScheduleTimerHooks, type SecretProvider, type SecretSource, type SecretValue, type NativeSftpProviderOptions as SftpProviderOptions, type NativeSftpRawSession as SftpRawSession, type SpecializedErrorDetails, type SshAgentSource, type SshAlgorithmPreferences, type SshAlgorithms, SshAuthSession, SshConnectionManager, SshDataReader, SshDataWriter, SshDisconnectReason, type SshKeyboardInteractiveChallenge, type SshKeyboardInteractiveCredential, type SshKeyboardInteractiveHandler, type SshKeyboardInteractivePrompt, type SshKnownHostsSource, type SshPasswordCredential, type SshProfile, type SshPublickeyCredential, SshSessionChannel, type SshSocketFactory, type SshSocketFactoryContext, SshTransportConnection, type SshTransportConnectionOptions, SshTransportHandshake, type SshTransportHandshakeResult, type StatOptions, type SyncConflictPolicy, type SyncDeletePolicy, type SyncDirection, type SyncEndpointInput, TimeoutError, type TlsProfile, type TlsSecretSource, type TransferAttempt, type TransferAttemptError, type TransferBandwidthLimit, type TransferByteRange, TransferClient, type TransferClientOptions, type TransferDataChunk, type TransferDataSource, type TransferEndpoint, TransferEngine, type TransferEngineExecuteOptions, type TransferEngineOptions, TransferError, type TransferExecutionContext, type TransferExecutionResult, type TransferExecutor, type TransferJob, type TransferOperation, type TransferPlan, type TransferPlanAction, type TransferPlanInput, type TransferPlanStep, type TransferPlanSummary, type TransferProgressEvent, type TransferProvider, TransferQueue, type TransferQueueExecutorResolver, type TransferQueueItem, type TransferQueueItemStatus, type TransferQueueOptions, type TransferQueueRunOptions, type TransferQueueSummary, type TransferReceipt, type TransferResult, type TransferResultInput, type TransferRetryDecisionInput, type TransferRetryPolicy, type TransferSession, type TransferTimeoutPolicy, type TransferVerificationResult, UnsupportedFeatureError, type UploadFileOptions, type ValueSecretSource, VerificationError, type WalkRemoteTreeOptions, type WebDavProviderOptions, type WebhookRetryPolicy, type WebhookSignature, type WebhookTarget, type WinScpSession, ZeroTransfer, type ZeroTransferCapabilities, ZeroTransferError, type ZeroTransferErrorDetails, type ZeroTransferLogger, type ZeroTransferOptions, assertSafeFtpArgument, basenameRemotePath, buildPublickeyCredential, buildRemoteBreadcrumbs, compareRemoteManifests, composeAuditLogs, copyBetween, createApprovalGate, createAtomicDeployPlan, createAzureBlobProviderFactory, createBandwidthThrottle, createDropboxProviderFactory, createFileSystemS3MultipartResumeStore, createFtpProviderFactory, createFtpsProviderFactory, createGcsProviderFactory, createGoogleDriveProviderFactory, createHttpProviderFactory, createInboxRoute, createJsonlAuditLog, createLocalProviderFactory, createMemoryProviderFactory, createMemoryS3MultipartResumeStore, createNativeSftpProviderFactory, createOAuthTokenSecretSource, createOneDriveProviderFactory, createOutboxRoute, createPooledTransferClient, createProgressEvent, createProviderTransferExecutor, createRemoteBrowser, createRemoteManifest, createS3ProviderFactory, createNativeSftpProviderFactory as createSftpProviderFactory, createSyncPlan, createTransferClient, createTransferJobsFromPlan, createTransferPlan, createTransferResult, createWebDavProviderFactory, createWebhookAuditLog, diffRemoteTrees, dispatchWebhook, downloadFile, emitLog, errorFromFtpReply, evaluateRetention, filterRemoteEntries, formatCapabilityMatrixMarkdown, freezeReceipt, getBuiltinCapabilityMatrix, importFileZillaSites, importOpenSshConfig, importWinScpSessions, inboxFailedPath, inboxProcessedPath, isClassicProviderId, isSensitiveKey, joinRemotePath, matchKnownHosts, matchKnownHostsEntry, negotiateSshAlgorithms, nextCronFireAt, nextScheduleFireAt, noopLogger, normalizeRemotePath, parentRemotePath, parseCronExpression, parseFtpFeatures, parseFtpResponseLines, parseKnownHosts, parseMlsdLine, parseMlsdList, parseMlstTimestamp, parseOpenSshConfig, parseRemoteManifest, parseUnixList, parseUnixListLine, redactCommand, redactConnectionProfile, redactObject, redactSecretSource, redactValue, resolveConnectionProfileSecrets, resolveOpenSshHost, resolveProviderId, resolveSecret, runConnectionDiagnostics, runRoute, serializeRemoteManifest, signWebhookPayload, sortRemoteEntries, summarizeClientDiagnostics, summarizeError, summarizeTransferPlan, throttleByteIterable, uploadFile, validateConnectionProfile, validateSchedule, walkRemoteTree };
+/**
+ * Returns `true` when the file containing `import.meta.url` is the entry point
+ * of the current Node.js process. Returns `false` outside Node.
+ */
+declare function isMainModule(importMetaUrl: string): boolean;
+
+export { AbortError, type AgeRetentionPolicy, ApprovalRegistry, ApprovalRejectedError, type ApprovalRequest, type ApprovalStatus, type AtomicDeployActivateOperation, type AtomicDeployActivateStep, type AtomicDeployPlan, type AtomicDeployPruneStep, type AtomicDeployStrategy, type AuthenticationCapability, AuthenticationError, AuthorizationError, type AzureBlobMultipartOptions, type AzureBlobProviderOptions, type BandwidthSleep, type BandwidthThrottle, type BandwidthThrottleOptions, type Base64EnvSecretSource, type BuiltInProviderId, type BuiltinCapabilityMatrixEntry, type BuiltinProviderMatrixId, CLASSIC_PROVIDER_IDS, type CapabilitySet, type ChecksumCapability, type ClassicProviderId, type ClientDiagnostics, type CompareRemoteManifestsOptions, ConfigurationError, type ConnectionDiagnosticTimings, type ConnectionDiagnosticsResult, ConnectionError, type ConnectionPoolOptions, type ConnectionProfile, type ConventionEndpoint, type CopyBetweenOptions, type CountRetentionPolicy, type CreateApprovalGateOptions, type CreateAtomicDeployPlanOptions, type CreateInboxRouteOptions, type CreateOutboxRouteOptions, type CreateRemoteBrowserOptions, type CreateRemoteManifestOptions, type CreateSyncPlanOptions, type CreateWebhookAuditLogOptions, type CronExpression, type CronField, type CronScheduleTrigger, DEFAULT_FAILED_SUBDIR, DEFAULT_PROCESSED_SUBDIR, DEFAULT_SSH_ALGORITHM_PREFERENCES, type DiffRemoteTreesOptions, type DispatchWebhookOptions, type DispatchWebhookResult, type DownloadFileOptions, type DropboxProviderOptions, type EnvSecretSource, type EvaluateRetentionOptions, type FileSecretSource, type FileSystemS3MultipartResumeStoreOptions, type FileZillaSite, type FriendlyTransferOptions, type FtpFeatures, type FtpPassiveHostStrategy, type FtpProviderOptions, type FtpReplyErrorInput, type FtpResponse, FtpResponseParser, type FtpResponseStatus, type FtpsDataProtection, type FtpsMode, type FtpsProviderOptions, type GcsMultipartOptions, type GcsProviderOptions, type GoogleDriveProviderOptions, type HttpFetch, type HttpProviderOptions, type ImportFileZillaSitesResult, type ImportOpenSshConfigOptions, type ImportOpenSshConfigResult, type ImportWinScpSessionsResult, InMemoryAuditLog, type IntervalScheduleTrigger, type JsonlWriter, type KnownHostsEntry, type KnownHostsMarker, type ListOptions, type LocalProviderOptions, type LogLevel, type LogRecord, type LogRecordInput, type LoggerMethod, type MemoryProviderEntry, type MemoryProviderOptions, type MetadataCapability, type MftAuditEntry, type MftAuditEntryType, type MftAuditLog, type MftInboxConvention, type MftOutboxConvention, type MftRoute, type MftRouteEndpoint, type MftRouteFilter, type MftRouteOperation, type MftSchedule, type MftScheduleTrigger, MftScheduler, type MftSchedulerOptions, type MkdirOptions, type NativeSftpProviderOptions, type NativeSftpRawSession, type NegotiatedSshAlgorithms, type OAuthAccessToken, type OAuthRefreshCallback, type OAuthTokenSecretSourceOptions, type OneDriveMultipartOptions, type OneDriveProviderOptions, type OpenSshConfigEntry, ParseError, PathAlreadyExistsError, PathNotFoundError, PermissionDeniedError, type PooledTransferClient, type ProgressEventInput, ProtocolError, type AuthenticationCapability as ProviderAuthenticationCapability, type CapabilitySet as ProviderCapabilities, type ChecksumCapability as ProviderChecksumCapability, type ProviderFactory, type ProviderId, type MetadataCapability as ProviderMetadataCapability, ProviderRegistry, type ProviderSelection, type ProviderTransferEndpointRole, type ProviderTransferExecutorOptions, type ProviderTransferOperations, type ProviderTransferReadRequest, type ProviderTransferReadResult, type ProviderTransferRequest, type ProviderTransferSessionResolver, type ProviderTransferSessionResolverInput, type ProviderTransferWriteRequest, type ProviderTransferWriteResult, REDACTED, REMOTE_MANIFEST_FORMAT_VERSION, type RemoteBreadcrumb, type RemoteBrowser, type RemoteBrowserFilter, type RemoteBrowserSnapshot, type RemoteEntry, type RemoteEntrySortKey, type RemoteEntrySortOrder, type RemoteEntryType, type RemoteFileAdapter, type RemoteFileEndpoint, type RemoteFileSystem, type RemoteManifest, type RemoteManifestEntry, type RemotePermissions, type RemoteProtocol, type RemoteStat, type RemoteTreeDiff, type RemoteTreeDiffEntry, type RemoteTreeDiffReason, type RemoteTreeDiffStatus, type RemoteTreeDiffSummary, type RemoteTreeEntry, type RemoteTreeFilter, type RemoveOptions, type RenameOptions, type ResolveSecretOptions, type ResolvedConnectionProfile, type ResolvedOpenSshHost, type ResolvedSshProfile, type ResolvedTlsProfile, type RetentionEvaluation, type RetentionPolicy, type RmdirOptions, RouteRegistry, type RunConnectionDiagnosticsOptions, type RunRouteOptions, type RunSshCommandOptions, type RunSshCommandResult, type S3MultipartCheckpoint, type S3MultipartOptions, type S3MultipartPart, type S3MultipartResumeKey, type S3MultipartResumeStore, type S3ProviderOptions, ScheduleRegistry, type ScheduleRouteRunner, type ScheduleTimerHooks, type SecretProvider, type SecretSource, type SecretValue, type NativeSftpProviderOptions as SftpProviderOptions, type NativeSftpRawSession as SftpRawSession, type SpecializedErrorDetails, type SshAgentSource, type SshAlgorithmPreferences, type SshAlgorithms, SshAuthSession, SshConnectionManager, SshDataReader, SshDataWriter, SshDisconnectReason, type SshKeyboardInteractiveChallenge, type SshKeyboardInteractiveCredential, type SshKeyboardInteractiveHandler, type SshKeyboardInteractivePrompt, type SshKnownHostsSource, type SshPasswordCredential, type SshProfile, type SshPublickeyCredential, SshSessionChannel, type SshSocketFactory, type SshSocketFactoryContext, SshTransportConnection, type SshTransportConnectionOptions, SshTransportHandshake, type SshTransportHandshakeResult, type StatOptions, type SyncConflictPolicy, type SyncDeletePolicy, type SyncDirection, type SyncEndpointInput, TimeoutError, type TlsProfile, type TlsSecretSource, type TransferAttempt, type TransferAttemptError, type TransferBandwidthLimit, type TransferByteRange, TransferClient, type TransferClientOptions, type TransferDataChunk, type TransferDataSource, type TransferEndpoint, TransferEngine, type TransferEngineExecuteOptions, type TransferEngineOptions, TransferError, type TransferExecutionContext, type TransferExecutionResult, type TransferExecutor, type TransferJob, type TransferOperation, type TransferPlan, type TransferPlanAction, type TransferPlanInput, type TransferPlanStep, type TransferPlanSummary, type TransferProgressEvent, type TransferProvider, TransferQueue, type TransferQueueExecutorResolver, type TransferQueueItem, type TransferQueueItemStatus, type TransferQueueOptions, type TransferQueueRunOptions, type TransferQueueSummary, type TransferReceipt, type TransferResult, type TransferResultInput, type TransferRetryDecisionInput, type TransferRetryPolicy, type TransferSession, type TransferTimeoutPolicy, type TransferVerificationResult, UnsupportedFeatureError, type UploadFileOptions, type ValueSecretSource, VerificationError, type WalkRemoteTreeOptions, type WebDavProviderOptions, type WebhookRetryPolicy, type WebhookSignature, type WebhookTarget, type WinScpSession, ZeroTransfer, type ZeroTransferCapabilities, ZeroTransferError, type ZeroTransferErrorDetails, type ZeroTransferLogger, type ZeroTransferOptions, assertSafeFtpArgument, basenameRemotePath, buildPublickeyCredential, buildRemoteBreadcrumbs, compareRemoteManifests, composeAuditLogs, copyBetween, createApprovalGate, createAtomicDeployPlan, createAzureBlobProviderFactory, createBandwidthThrottle, createDropboxProviderFactory, createFileSystemS3MultipartResumeStore, createFtpProviderFactory, createFtpsProviderFactory, createGcsProviderFactory, createGoogleDriveProviderFactory, createHttpProviderFactory, createInboxRoute, createJsonlAuditLog, createLocalProviderFactory, createMemoryProviderFactory, createMemoryS3MultipartResumeStore, createNativeSftpProviderFactory, createOAuthTokenSecretSource, createOneDriveProviderFactory, createOutboxRoute, createPooledTransferClient, createProgressEvent, createProviderTransferExecutor, createRemoteBrowser, createRemoteManifest, createS3ProviderFactory, createNativeSftpProviderFactory as createSftpProviderFactory, createSyncPlan, createTransferClient, createTransferJobsFromPlan, createTransferPlan, createTransferResult, createWebDavProviderFactory, createWebhookAuditLog, diffRemoteTrees, dispatchWebhook, downloadFile, emitLog, errorFromFtpReply, evaluateRetention, filterRemoteEntries, formatCapabilityMatrixMarkdown, freezeReceipt, getBuiltinCapabilityMatrix, importFileZillaSites, importOpenSshConfig, importWinScpSessions, inboxFailedPath, inboxProcessedPath, isClassicProviderId, isMainModule, isSensitiveKey, joinRemotePath, matchKnownHosts, matchKnownHostsEntry, negotiateSshAlgorithms, nextCronFireAt, nextScheduleFireAt, noopLogger, normalizeRemotePath, parentRemotePath, parseCronExpression, parseFtpFeatures, parseFtpResponseLines, parseKnownHosts, parseMlsdLine, parseMlsdList, parseMlstTimestamp, parseOpenSshConfig, parseRemoteManifest, parseUnixList, parseUnixListLine, redactCommand, redactConnectionProfile, redactObject, redactSecretSource, redactValue, resolveConnectionProfileSecrets, resolveOpenSshHost, resolveProviderId, resolveSecret, runConnectionDiagnostics, runRoute, runSshCommand, serializeRemoteManifest, signWebhookPayload, sortRemoteEntries, summarizeClientDiagnostics, summarizeError, summarizeTransferPlan, throttleByteIterable, uploadFile, validateConnectionProfile, validateSchedule, walkRemoteTree };