Connection Management

/**
 * Creates a new SFTP client instance
 * @param clientName - Optional client name for debugging (default: 'sftp')
 * @param callbacks - Optional event callbacks for error, end, and close events
 */
constructor(clientName = 'sftp', callbacks = {
  error: (err) => console.error(`Global error listener: ${err.message}`),
  end: () => console.log('Global end listener: end event raised'),
  close: () => console.log('Global close listener: close event raised')
});

const SftpClient = require('ssh2-sftp-client');

// Basic client
const sftp = new SftpClient();

// Named client with custom callbacks
const sftp = new SftpClient('myClient', {
  error: (err) => console.error('SFTP Error:', err.message),
  end: () => console.log('SFTP connection ended'),
  close: () => console.log('SFTP connection closed')
});

/**
 * Create a new SFTP connection to a remote SFTP server
 * @param config - SFTP configuration object with connection details
 * @returns Promise resolving to SFTP client object
 */
connect(config): Promise<Object>;

interface ConnectionConfig {
  host: string;                    // Remote server hostname or IP
  port?: number;                   // SSH port (default: 22)
  username: string;                // Username for authentication
  password?: string;               // Password authentication
  privateKey?: string | Buffer;    // Private key for key-based auth
  passphrase?: string;             // Private key passphrase
  readyTimeout?: number;           // Connection timeout in milliseconds
  strictVendor?: boolean;          // Strict vendor checking
  debug?: Function;                // Debug function for logging
  promiseLimit?: number;           // Concurrent operation limit (default: 10)
  // Additional SSH2 options supported
}

// Password authentication
await sftp.connect({
  host: 'example.com',
  port: 22,
  username: 'user',
  password: 'password'
});

// SSH key authentication
const fs = require('fs');
await sftp.connect({
  host: 'example.com',
  username: 'user',
  privateKey: fs.readFileSync('/path/to/private/key'),
  passphrase: 'key-passphrase'
});

// With debugging and custom settings
await sftp.connect({
  host: 'example.com',
  username: 'user',
  password: 'password',
  readyTimeout: 20000,
  promiseLimit: 5,
  debug: console.log
});

/**
 * End the SFTP connection and clean up resources
 * @returns Promise resolving to true when connection is closed
 */
end(): Promise<Boolean>;

// Always end connections in finally blocks
try {
  await sftp.connect(config);
  // perform operations
} catch (err) {
  console.error(err);
} finally {
  await sftp.end();
}

// Check if connection ended successfully
const closed = await sftp.end();
if (closed) {
  console.log('Connection closed successfully');
}

/**
 * Add event listener to the client
 * @param eventType - Event type ('error', 'end', 'close', 'ready', etc.)
 * @param callback - Function to call when event triggers
 */
on(eventType, callback): void;

/**
 * Remove event listener from the client
 * @param eventType - Event type to remove listener for
 * @param callback - Specific callback function to remove
 */
removeListener(eventType, callback): void;

// Add custom error handler
const errorHandler = (err) => {
  console.error('Custom error handler:', err.message);
};
sftp.on('error', errorHandler);

// Add connection ready handler
sftp.on('ready', () => {
  console.log('SFTP connection is ready');
});

// Remove listener when done
sftp.removeListener('error', errorHandler);