@edirect/sftp-client

SFTP client module for eDirect NestJS applications. Provides a SftpClientService with methods for uploading, downloading, listing, renaming, and deleting files on SFTP servers — backed by ssh2-sftp-client.

Features

• Upload files (string content or Buffer)
• Download files to a local path or writable stream
• List directory contents with optional sort by modification date
• Read file content as string
• Rename files (rename and posixRename)
• Delete files
• Connection options support both password and private key authentication
• NestJS module — injectable via SftpClientModule

Installation

pnpm add @edirect/sftp-client
# or
npm install @edirect/sftp-client

Setup

Register SftpClientModule in your AppModule

import { Module } from '@nestjs/common';
import { SftpClientModule } from '@edirect/sftp-client';

@Module({
  imports: [SftpClientModule],
})
export class AppModule {}

Inject and use SftpClientService

import { Injectable } from '@nestjs/common';
import { SftpClientService } from '@edirect/sftp-client';

const SFTP_OPTIONS = {
  host: process.env.SFTP_HOST,
  username: process.env.SFTP_USERNAME,
  password: process.env.SFTP_PASSWORD,
  port: process.env.SFTP_PORT ?? '22',
};

@Injectable()
export class ReportService {
  constructor(private readonly sftp: SftpClientService) {}

  async uploadReport(content: string, filename: string): Promise<void> {
    await this.sftp.upload(SFTP_OPTIONS, content, `/reports/${filename}`);
  }

  async downloadReport(filename: string, localPath: string): Promise<void> {
    await this.sftp.download(SFTP_OPTIONS, `/reports/${filename}`, localPath);
  }

  async listReports(): Promise<string[]> {
    return this.sftp.listFiles(SFTP_OPTIONS, '/reports', 'DESC');
  }

  async readLatestReport(filename: string): Promise<string> {
    return this.sftp.getFileContent(SFTP_OPTIONS, `/reports/${filename}`);
  }
}

Connection Options (ISFTPClientOptions)

| Option | Type | Required | Description | | ------------ | ------------------ | -------- | ---------------------------------------- | | host | string | Yes | SFTP server hostname or IP | | port | string | Yes | SFTP server port (usually '22') | | username | string | Yes | SSH username | | password | string | No | Password authentication | | privateKey | string \| Buffer | No | Private key for key-based authentication | | passphrase | string | No | Passphrase for the private key | | encoding | string | No | File encoding |

Either password or privateKey must be provided.

API

SftpClientService

| Method | Signature | Description | | ---------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------- | | upload | (options, dataToUpload: string \| Buffer, fileName: string): Promise<void> | Upload content to fileName on the SFTP server | | download | (options, fileName: string, downloadPath: string \| WritableStream): Promise<void> | Download fileName to a local path or writable stream | | delete | (options, deletePath: string): Promise<void> | Delete a file at the given path | | rename | (options, fromPath: string, toPath: string): Promise<void> | Rename a file | | posixRename | (options, fromPath: string, toPath: string): Promise<void> | Rename using POSIX atomic rename (server-side) | | listFiles | (options, path: string, orderByModifiedDate?: 'ASC' \| 'DESC'): Promise<string[]> | List filenames in a directory, optionally sorted by modification time | | getFileContent | (options, filePath: string): Promise<string> | Read and return file content as a UTF-8 string |

Each method opens a new SFTP connection, performs the operation, and closes the connection. This avoids stale connection issues in long-running services.

Environment Variables

The module does not read environment variables directly — connection options are passed per-call. A recommended pattern is to load them from @edirect/config:

import { ConfigService } from '@edirect/config';

const options = {
  host: configService.get('SFTP_HOST'),
  port: configService.get('SFTP_PORT') ?? '22',
  username: configService.get('SFTP_USERNAME'),
  password: configService.get('SFTP_PASSWORD'),
  privateKey: configService.get('SFTP_PRIVATE_KEY'),
};

Key-Based Authentication

import fs from 'fs';

await sftp.upload(
  {
    host: 'sftp.example.com',
    port: '22',
    username: 'deploy',
    privateKey: fs.readFileSync('/path/to/id_rsa'),
    passphrase: process.env.SSH_PASSPHRASE,
  },
  fileContent,
  '/uploads/report.csv',
);