@zero-transfer/sdk 0.1.0-alpha.0 → 0.1.1

package/dist/index.d.mts

@@ -375,7 +375,17 @@ interface TlsProfile {
     minVersion?: SecureVersion;
     /** Maximum TLS protocol version accepted by the client. */
     maxVersion?: SecureVersion;
-    /** Expected server certificate SHA-256 fingerprint or fingerprints, using hex with optional colons. */
+    /**
+     * Optional. Expected server certificate SHA-256 fingerprint(s) for **certificate pinning**, in
+     * 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
+     * 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.
+     *
+     * @example "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99"
+     */
     pinnedFingerprint256?: string | readonly string[];
     /** Optional custom server identity checker for private PKI or certificate pinning. */
     checkServerIdentity?: (host: string, cert: PeerCertificate) => Error | undefined;
@@ -395,9 +405,25 @@ interface SshProfile {
     privateKey?: SecretSource;
     /** Passphrase used to decrypt an encrypted private key. */
     passphrase?: SecretSource;
-    /** OpenSSH known_hosts content used for strict SFTP host-key verification. */
+    /**
+     * Optional. OpenSSH `known_hosts` content used for **strict SFTP host-key verification**.
+     * Mutually exclusive with provider-level `hostHash`/`hostVerifier` options.
+     *
+     * Not required for the connection to succeed, but **strongly recommended for production**:
+     * without `knownHosts` (and without {@link SshProfile.pinnedHostKeySha256 | pinnedHostKeySha256}),
+     * the SSH session accepts any host key the server presents, leaving you exposed to MITM.
+     */
     knownHosts?: SshKnownHostsSource;
-    /** Expected SSH host-key SHA-256 fingerprint or fingerprints, using OpenSSH `SHA256:` form, base64, or hex. */
+    /**
+     * Optional. SSH host-key SHA-256 fingerprint(s) the remote must present, in OpenSSH
+     * `SHA256:<base64>` form, raw base64, or hex.
+     *
+     * Use this as a lighter-weight alternative to a full `known_hosts` file when you only need
+     * to pin a single host. Like `knownHosts`, it is **optional but recommended for production**;
+     * leaving both unset disables host-key verification entirely.
+     *
+     * @example "SHA256:abc123basesixfourpinFromKnownHosts="
+     */
     pinnedHostKeySha256?: string | readonly string[];
     /** Runtime callback that answers SSH keyboard-interactive authentication prompts. */
     keyboardInteractive?: SshKeyboardInteractiveHandler;
@@ -406,6 +432,46 @@ interface SshProfile {
 }
 /**
  * Connection settings accepted by facade and adapter implementations.
+ *
+ * Every `ConnectionProfile` has a `host` and a `provider` (or `protocol`).
+ * Authentication and transport-specific material is layered on via the
+ * optional `ssh`, `tls`, `oauth`, and provider-specific blocks (e.g. `s3`,
+ * `azure`, `dropbox`).
+ *
+ * @example SFTP with public-key auth
+ * ```ts
+ * const profile: ConnectionProfile = {
+ *   host: "sftp.example.com",
+ *   provider: "sftp",
+ *   username: "deploy",
+ *   ssh: {
+ *     privateKey: { path: "./keys/id_ed25519" },
+ *     pinnedHostKeySha256: "SHA256:abc123basesixfourpinFromKnownHosts=",
+ *   },
+ * };
+ * ```
+ *
+ * @example FTPS with username/password and public-CA TLS
+ * ```ts
+ * const profile: ConnectionProfile = {
+ *   host: "ftps.example.com",
+ *   provider: "ftps",
+ *   username: "deploy",
+ *   password: { env: "FTPS_PASSWORD" },
+ *   tls: { minVersion: "TLSv1.2" },
+ * };
+ * ```
+ *
+ * @example S3-compatible
+ * ```ts
+ * const profile: ConnectionProfile = {
+ *   host: "my-bucket",
+ *   provider: "s3",
+ *   username: process.env.AWS_ACCESS_KEY_ID,
+ *   password: { env: "AWS_SECRET_ACCESS_KEY" },
+ *   s3: { region: "us-east-1" },
+ * };
+ * ```
  */
 interface ConnectionProfile {
     /** Provider to use for this connection. Prefer this over the compatibility protocol field. */
@@ -982,8 +1048,50 @@ declare class TransferClient {
 /**
  * Creates a provider-neutral transfer client.
  *
+ * The returned client owns a registry of provider factories and produces
+ * `TransferSession` instances on demand via {@link TransferClient.connect}.
+ * Registering only the providers you actually use keeps bundle size small
+ * (each factory pulls in its own SDK dependencies).
+ *
  * @param options - Optional registry, provider factories, and logger.
  * @returns A disconnected {@link TransferClient} instance.
+ *
+ * @example Multi-provider client
+ * ```ts
+ * import {
+ *   createS3ProviderFactory,
+ *   createSftpProviderFactory,
+ *   createTransferClient,
+ * } from "@zero-transfer/sdk";
+ *
+ * const client = createTransferClient({
+ *   providers: [createSftpProviderFactory(), createS3ProviderFactory()],
+ * });
+ *
+ * const session = await client.connect({
+ *   host: "sftp.example.com",
+ *   provider: "sftp",
+ *   username: "deploy",
+ *   ssh: { privateKey: { path: "./keys/id_ed25519" } },
+ * });
+ * try {
+ *   const list = await session.fs.list("/uploads");
+ *   console.log(list);
+ * } finally {
+ *   await session.disconnect();
+ * }
+ * ```
+ *
+ * @example Friendly one-shot helpers
+ * ```ts
+ * import { uploadFile } from "@zero-transfer/sdk";
+ *
+ * await uploadFile({
+ *   client,
+ *   destination: { path: "/uploads/report.csv", profile },
+ *   localPath: "./out/report.csv",
+ * });
+ * ```
  */
 declare function createTransferClient(options?: TransferClientOptions): TransferClient;
 
@@ -1280,8 +1388,37 @@ interface UploadFileOptions extends FriendlyTransferOptions {
 /**
  * Uploads a single local file to a remote endpoint.
  *
+ * The remote provider is resolved from `destination.profile.provider`, so any
+ * provider factory you registered with {@link createTransferClient} can be used
+ * as the destination.
+ *
  * @param options - Friendly upload options.
  * @returns Receipt produced by the underlying transfer engine.
+ *
+ * @example Upload to SFTP with public-key auth
+ * ```ts
+ * import {
+ *   createSftpProviderFactory,
+ *   createTransferClient,
+ *   uploadFile,
+ * } from "@zero-transfer/sdk";
+ *
+ * const client = createTransferClient({ providers: [createSftpProviderFactory()] });
+ *
+ * await uploadFile({
+ *   client,
+ *   destination: {
+ *     path: "/uploads/report.csv",
+ *     profile: {
+ *       host: "sftp.example.com",
+ *       provider: "sftp",
+ *       username: "deploy",
+ *       ssh: { privateKey: { path: "./keys/id_ed25519" } },
+ *     },
+ *   },
+ *   localPath: "./out/report.csv",
+ * });
+ * ```
  */
 declare function uploadFile(options: UploadFileOptions): Promise<TransferReceipt>;
 /** Options for {@link downloadFile}. */
@@ -1296,8 +1433,35 @@ interface DownloadFileOptions extends FriendlyTransferOptions {
 /**
  * Downloads a single remote file to a local path.
  *
+ * The remote provider is resolved from `source.profile.provider`. The local
+ * destination path is created (including parent directories) on demand.
+ *
  * @param options - Friendly download options.
  * @returns Receipt produced by the underlying transfer engine.
+ *
+ * @example Download from S3
+ * ```ts
+ * import {
+ *   createS3ProviderFactory,
+ *   createTransferClient,
+ *   downloadFile,
+ * } from "@zero-transfer/sdk";
+ *
+ * const client = createTransferClient({ providers: [createS3ProviderFactory()] });
+ *
+ * await downloadFile({
+ *   client,
+ *   localPath: "./tmp/snapshot.tar.gz",
+ *   source: {
+ *     path: "snapshots/2026-04-28/snapshot.tar.gz",
+ *     profile: {
+ *       host: "snapshots", // S3 bucket
+ *       provider: "s3",
+ *       s3: { region: "us-east-1" },
+ *     },
+ *   },
+ * });
+ * ```
  */
 declare function downloadFile(options: DownloadFileOptions): Promise<TransferReceipt>;
 /** Options for {@link copyBetween}. */
@@ -1312,8 +1476,38 @@ interface CopyBetweenOptions extends FriendlyTransferOptions {
 /**
  * Copies a file between two remote endpoints in a single call.
  *
+ * Both source and destination providers must be registered with the
+ * {@link TransferClient}. Streams are piped end-to-end without staging the file
+ * on the local disk.
+ *
  * @param options - Friendly copy options.
  * @returns Receipt produced by the underlying transfer engine.
+ *
+ * @example Copy from SFTP to S3
+ * ```ts
+ * import {
+ *   copyBetween,
+ *   createS3ProviderFactory,
+ *   createSftpProviderFactory,
+ *   createTransferClient,
+ * } from "@zero-transfer/sdk";
+ *
+ * const client = createTransferClient({
+ *   providers: [createSftpProviderFactory(), createS3ProviderFactory()],
+ * });
+ *
+ * await copyBetween({
+ *   client,
+ *   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" } },
+ *   },
+ * });
+ * ```
  */
 declare function copyBetween(options: CopyBetweenOptions): Promise<TransferReceipt>;
 
@@ -1444,8 +1638,24 @@ interface LocalProviderOptions {
 /**
  * Creates a provider factory backed by the local filesystem.
  *
+ * Useful for copying files between two remote endpoints via a local staging
+ * area, or as the destination for `downloadFile`. The friendly `uploadFile`
+ * helper registers a local provider implicitly.
+ *
  * @param options - Optional local root path exposed through provider sessions.
  * @returns Provider factory suitable for `createTransferClient({ providers: [...] })`.
+ *
+ * @example Use a fixed root directory
+ * ```ts
+ * import { createLocalProviderFactory, createTransferClient } from "@zero-transfer/sdk";
+ *
+ * const client = createTransferClient({
+ *   providers: [createLocalProviderFactory({ rootPath: "/var/lib/zt-staging" })],
+ * });
+ *
+ * const session = await client.connect({ host: "staging", provider: "local" });
+ * const list = await session.fs.list("/");
+ * ```
  */
 declare function createLocalProviderFactory(options?: LocalProviderOptions): ProviderFactory;
 
@@ -1692,7 +1902,7 @@ interface S3MultipartPart {
  * Persistence contract for resuming partial multipart uploads across
  * processes or retries. Implementations may be synchronous or asynchronous;
  * `clear` is invoked once the multipart upload completes successfully (or is
- * explicitly aborted via {@link abortS3MultipartUpload}).
+ * explicitly aborted).
  */
 interface S3MultipartResumeStore {
     load(key: S3MultipartResumeKey): Promise<S3MultipartCheckpoint | undefined> | S3MultipartCheckpoint | undefined;
@@ -1707,6 +1917,34 @@ declare function createMemoryS3MultipartResumeStore(): S3MultipartResumeStore;
  * Credentials must be supplied via the connection profile: `username` is the
  * access key id and `password` is the secret access key. `profile.host` may
  * be set to the bucket name (taking precedence over `options.bucket`).
+ *
+ * Works with AWS S3 and any S3-compatible API (MinIO, Cloudflare R2,
+ * Backblaze B2, DigitalOcean Spaces, Wasabi, etc.) via `options.endpoint`.
+ *
+ * @example AWS S3
+ * ```ts
+ * import { createS3ProviderFactory, createTransferClient } from "@zero-transfer/sdk";
+ *
+ * const client = createTransferClient({ providers: [createS3ProviderFactory()] });
+ *
+ * const session = await client.connect({
+ *   host: "my-bucket",
+ *   provider: "s3",
+ *   username: process.env.AWS_ACCESS_KEY_ID,
+ *   password: { env: "AWS_SECRET_ACCESS_KEY" },
+ *   s3: { region: "us-east-1" },
+ * });
+ * ```
+ *
+ * @example MinIO / R2 / S3-compatible endpoint
+ * ```ts
+ * const client = createTransferClient({
+ *   providers: [createS3ProviderFactory({
+ *     endpoint: "https://minio.internal:9000",
+ *     pathStyle: true,
+ *   })],
+ * });
+ * ```
  */
 declare function createS3ProviderFactory(options?: S3ProviderOptions): ProviderFactory;
 
@@ -2325,6 +2563,20 @@ 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)
+ * ```ts
+ * import { createFtpProviderFactory, createTransferClient } from "@zero-transfer/sdk";
+ *
+ * const client = createTransferClient({ providers: [createFtpProviderFactory()] });
+ *
+ * const session = await client.connect({
+ *   host: "ftp.example.com",
+ *   provider: "ftp",
+ *   username: "deploy",
+ *   password: { env: "FTP_PASSWORD" },
+ * });
+ * ```
  */
 declare function createFtpProviderFactory(options?: FtpProviderOptions): ProviderFactory;
 /**
@@ -2335,6 +2587,37 @@ declare function createFtpProviderFactory(options?: FtpProviderOptions): Provide
  *
  * @param options - Optional provider defaults.
  * @returns Provider factory suitable for `createTransferClient({ providers: [...] })`.
+ *
+ * @example FTPS with public-CA TLS (no extra TLS material needed)
+ * ```ts
+ * import { createFtpsProviderFactory, createTransferClient } from "@zero-transfer/sdk";
+ *
+ * const client = createTransferClient({ providers: [createFtpsProviderFactory()] });
+ *
+ * const session = await client.connect({
+ *   host: "ftps.example.com",
+ *   provider: "ftps",
+ *   username: "deploy",
+ *   password: { env: "FTPS_PASSWORD" },
+ *   tls: { minVersion: "TLSv1.2" },
+ * });
+ * ```
+ *
+ * @example FTPS with private CA + certificate pinning (defence-in-depth)
+ * ```ts
+ * await client.connect({
+ *   host: "ftps.internal.example",
+ *   provider: "ftps",
+ *   username: "audit",
+ *   tls: {
+ *     ca: { path: "./certs/ca-bundle.pem" },
+ *     cert: { path: "./certs/client.crt" },
+ *     key: { path: "./certs/client.key" },
+ *     // Optional but recommended:
+ *     pinnedFingerprint256: "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99",
+ *   },
+ * });
+ * ```
  */
 declare function createFtpsProviderFactory(options?: FtpsProviderOptions): ProviderFactory;
 
@@ -2514,6 +2797,28 @@ interface SftpRawSession {
  *
  * @param options - Optional ssh2 host-key verifier and timeout defaults.
  * @returns Provider factory suitable for `createTransferClient({ providers: [...] })`.
+ *
+ * @example Register and use
+ * ```ts
+ * import { createSftpProviderFactory, createTransferClient } from "@zero-transfer/sdk";
+ *
+ * const client = createTransferClient({ providers: [createSftpProviderFactory()] });
+ *
+ * const session = await client.connect({
+ *   host: "sftp.example.com",
+ *   provider: "sftp",
+ *   username: "deploy",
+ *   ssh: {
+ *     privateKey: { path: "./keys/id_ed25519" },
+ *     // Optional but recommended for production:
+ *     pinnedHostKeySha256: "SHA256:abc123basesixfourpinFromKnownHosts=",
+ *   },
+ * });
+ * ```
+ *
+ * Host-key verification (`ssh.knownHosts` and/or `ssh.pinnedHostKeySha256`) is
+ * optional; without either, the client trusts whatever host key the server
+ * presents. Use one for any non-lab deployment.
  */
 declare function createSftpProviderFactory(options?: SftpProviderOptions): ProviderFactory;