### start

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/listener.md

Starts the FTP listener, initiating the monitoring of remote directories for file changes.

```APIDOC
## start

### Description
Starts the FTP listener, initiating the monitoring of remote directories for file changes.

### Signature
```ballerina
public isolated function 'start() returns error?
```

### Return
- `()` on success
- `error` if listener fails to start

### Example
```ballerina
check remoteServer.'start();
```
```

--------------------------------

### Basic FTP Listener Setup

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/configuration.md

Demonstrates how to configure and initialize a basic FTP listener with host, port, polling interval, and authentication credentials.

```ballerina
listener ftp:Listener remoteServer = check new({
    protocol: ftp:FTP,
    host: "ftp.example.com",
    port: 21,
    pollingInterval: 60,
    auth: {
        credentials: {
            username: "ftpuser",
            password: "ftppass"
        }
    }
});

service on remoteServer {
    remote function onFileText(string content, ftp:FileInfo fileInfo) returns error? {
        io:println("New text file: " + fileInfo.name);
    }
}
```

--------------------------------

### Run RabbitMQ Docker Container

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/examples/covid19-stat-publisher/An example on file handling using Ballerina FTP.md

Starts a RabbitMQ server using a Docker image. This is necessary for the example to publish messages to a queue.

```shell
sudo docker run -it --rm --name rabbitmq -p 5672:5672 -p 15672:15672 rabbitmq:3.9-management
```

--------------------------------

### Run SFTP Server

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/examples/covid19-stat-publisher/An example on file handling using Ballerina FTP.md

Executes the Ballerina FTP server project to start the SFTP server. This server will be monitored by the FTP listener.

```shell
./gradlew run
```

--------------------------------

### Start FTP Listener

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/listener.md

Starts the FTP listener to begin monitoring for file changes in the configured directory. This is a lifecycle management function.

```ballerina
check remoteServer.'start();
```

--------------------------------

### Start the Processor

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/examples/covid19-stat-publisher/An example on file handling using Ballerina FTP.md

Runs the Ballerina application that acts as the FTP listener and message processor. It initializes the file listening and processing job.

```shell
$ bal run
```

--------------------------------

### FTP Basic Password Authentication

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/configuration.md

Example of configuring basic username and password authentication for an FTP connection.

```ballerina
ftp:AuthConfiguration auth = {
    credentials: {
        username: "user",
        password: "password"
    }
};
```

--------------------------------

### onFileChange with ftp:Caller

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/proposals/caller-param-in-onfilechange.md

Example of an `onFileChange` implementation that accepts `ftp:Caller` as the first argument, allowing direct use of FTP client APIs.

```ballerina
ftp:Service ftpService = service object {
    remote function onFileChange(ftp:Caller caller, ftp:WatchEvent & readonly event) {
        // process event
    }
};
```

--------------------------------

### Handle Text File in Listener

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/api-index.md

Example of a service handler for processing text files. It demonstrates how to access the file content, metadata, and optionally use the caller for further FTP operations.

```ballerina
remote function onFileText(string content, ftp:FileInfo info, ftp:Caller? caller) returns error? {
    if caller is ftp:Caller {
        // Perform additional FTP operations
    }
}
```

--------------------------------

### FTP Listener with Distributed Coordination Configuration

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/spec/spec.md

Configure an FTP listener for distributed coordination by providing a CoordinationConfig. Ensure all instances share the same coordinationGroup name and have unique memberIds. This setup requires a shared database for state management.

```ballerina
listener ftp:Listener ftpListener = check new ({
    protocol: ftp:SFTP,
    host: "sftp.example.com",
    port: 22,
    auth: {credentials: {username: "user", password: "pass"}},
    coordination: {
        memberId: "node-1",
        coordinationGroup: "ftp-processors",
        livenessCheckInterval: 30,
        heartbeatFrequency: 1,
        databaseConfig: <task:MysqlConfig>{
            host: "db.example.com",
            user: "dbuser",
            password: "dbpass",
            database: "coordination_db"
        }
    }
});
```

--------------------------------

### onFileChange without ftp:Caller

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/proposals/caller-param-in-onfilechange.md

Example of a traditional `onFileChange` implementation that does not accept `ftp:Caller`, requiring manual `ftp:Client` creation for operations.

```ballerina
ftp:Service ftpService = service object {
    remote function onFileChange(ftp:WatchEvent & readonly event) {
        // process event
    }
};
```

--------------------------------

### FTP Private Key Authentication

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/configuration.md

Example of configuring authentication using an SSH private key, including the key path and an optional passphrase.

```ballerina
ftp:AuthConfiguration auth = {
    privateKey: {
        path: "/home/user/.ssh/id_rsa",
        password: "key_passphrase"
    }
};
```

--------------------------------

### SFTP Client with Retry and Circuit Breaker Configurations

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/configuration.md

Initializes an SFTP client with advanced retry and circuit breaker configurations. This setup enhances resilience by defining retry attempts and circuit breaker behavior for connection failures.

```ballerina
ftp:ClientConfiguration advancedConfig = {
    protocol: ftp:SFTP,
    host: "sftp.example.com",
    port: 22,
    auth: {
        credentials: {
            username: "user",
            password: "pass"
        }
    },
    retryConfig: {
        count: 3,
        interval: 1.0,
        backOffFactor: 2.0,
        maxWaitInterval: 30.0
    },
    circuitBreaker: {
        failureThreshold: 0.5,
        resetTime: 60,
        failureCategories: [ftp:CONNECTION_ERROR, ftp:TRANSIENT_ERROR]
    }
};

ftp:Client client = check new(advancedConfig);
```

--------------------------------

### FTP Listener Methods

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/api-index.md

Monitors remote FTP/SFTP directories and triggers service handlers on file changes. Includes methods for starting, stopping, attaching services, and manual polling.

```APIDOC
## FTP Listener Operations

### Description
Provides methods for monitoring remote FTP/SFTP directories and managing the listener lifecycle.

### Methods
- `'start()` — Start monitoring
- `attach()` — Attach a service
- `detach()` — Detach a service
- `register()` — Register a service
- `poll()` — Manual polling trigger
- `gracefulStop()` — Stop gracefully
- `immediateStop()` — Stop immediately

### Initialization
```ballerina
listener ftp:Listener server = check new(ListenerConfiguration);
```
```

--------------------------------

### Move File on Success or Failure

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/spec/spec.md

This example shows how to move files to different directories based on processing outcome. Successful processing moves the file to a success archive, while errors move it to a failed archive. It uses `afterProcess: {moveTo: ...}` and `afterError: {moveTo: ...}`.

```ballerina
service on ftpListener {
    @ftp:FunctionConfig {
        afterProcess: {moveTo: "/archive/success/"},
        afterError: {moveTo: "/archive/failed/"}
    }
    remote function onFileXml(xml content, ftp:FileInfo fileInfo) returns error? {
        check processXml(content);
    }
}
```

--------------------------------

### FTP Listener with Distributed Coordination

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/configuration.md

Configures an FTP listener with distributed coordination for high availability. This setup ensures only one node actively polls while others remain in warm standby.

```ballerina
listener ftp:Listener remoteServer = check new({
    protocol: ftp:SFTP,
    host: "sftp.example.com",
    port: 22,
    pollingInterval: 30,
    auth: {
        credentials: {
            username: "user",
            password: "pass"
        }
    },
    coordination: {
        databaseConfig: {
            host: "db.example.com",
            port: 3306,
            user: "coord_user",
            password: "coord_pass",
            database: "ftp_coordination"
        },
        memberId: "listener-1",
        coordinationGroup: "ftp-listeners",
        livenessCheckInterval: 30,
        heartbeatFrequency: 1
    }
});

service on remoteServer {
    remote function onFileJson(json data, ftp:FileInfo info) returns error? {
        // Only one node actively polls; others are warm standby
        io:println("Processing: " + info.name);
    }
}
```

--------------------------------

### Configure FTP Service Path and Pattern

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/api-index.md

Use the @ftp:ServiceConfig annotation to specify the directory path and filename pattern for a service to monitor. This example filters for text files.

```ballerina
@ftp:ServiceConfig {
    path: "/uploads",
    fileNamePattern: ".*\\.txt$",
    fileAgeFilter: {minAge: 5}
}
service on listener {...}
```

--------------------------------

### Basic FTP Client Usage

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/api-index.md

Demonstrates how to initialize an FTP client, read a file, and write a file using the Ballerina FTP module. Ensure you have the necessary imports and configure the client with connection details and authentication.

```ballerina
import ballerina/ftp;
import ballerina/io;

public function main() returns error? {
    ftp:ClientConfiguration config = {
        protocol: ftp:FTP,
        host: "ftp.example.com",
        port: 21,
        auth: {
            credentials: {
                username: "user",
                password: "pass"
            }
        }
    };

    ftp:Client client = check new(config);
    defer {
        check client->close();
    }

    // Read file
    string content = check client->getText("/remote/file.txt");
    io:println(content);

    // Write file
    check client->putText("/remote/output.txt", "Hello, FTP!");
}
```

--------------------------------

### size

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/client.md

Gets the size of a file in bytes on the FTP server.

```APIDOC
## size

### Description
Gets the size of a file in bytes.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)

### Parameters
#### Path Parameters
- **path** (string) - Required - File path to check

### Return
- File size in bytes
- `ftp:Error` if size cannot be determined

### Example
```ballerina
int fileSize = check ftpClient->size("/remote/data.csv");
io:println("File size: " + fileSize.toString() + " bytes");
```
```

--------------------------------

### init

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/listener.md

Initializes the FTP listener with the provided configuration. It sets up the connection details, authentication, and polling interval for monitoring remote directories.

```APIDOC
## init

### Description
Initializes the FTP listener with the provided configuration. It sets up the connection details, authentication, and polling interval for monitoring remote directories.

### Signature
```ballerina
public isolated function init(*ListenerConfiguration listenerConfig) returns Error?
```

### Parameters
#### listenerConfig
- **listenerConfig** (ListenerConfiguration) - Required - Configuration for the FTP listener.

### Return
- `()` on successful initialization
- `ftp:Error` if initialization fails

### Example
```ballerina
import ballerina/ftp;

listener ftp:Listener remoteServer = check new({
    protocol: ftp:FTP,
    host: "ftp.example.com",
    port: 21,
    path: "/uploads",
    pollingInterval: 60,
    auth: {
        credentials: {
            username: "user",
            password: "pass"
        }
    }
});

service on remoteServer {
    remote function onFileText(string content, ftp:FileInfo fileInfo) returns error?
}
```
```

--------------------------------

### Get File Size

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/client.md

Retrieves the size of a file in bytes from the FTP server. Useful for monitoring or validation.

```ballerina
int fileSize = check ftpClient->size("/remote/data.csv");
io:println("File size: " + fileSize.toString() + " bytes");
```

--------------------------------

### Create FTP Client with Basic Auth

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/ballerina/README.md

Creates an FTP client configuration and initializes the client using Basic Authentication. Ensure to replace placeholders with your actual FTP host, port, username, and password.

```ballerina
// Define the FTP client configuration.
ftp:ClientConfiguration ftpConfig = {
    protocol: ftp:FTP,
    host: "<The FTP host>",
    port: <The FTP port>,
    auth: {
        credentials: {
            username: "<The FTP username>",
            password: "<The FTP passowrd>"
        }
    }
};

// Create the FTP client.
ftp:Client|ftp:Error ftpClient = new(ftpConfig);
```

--------------------------------

### Initialize SFTP Client with Credentials

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/spec/spec.md

Initializes a secure SFTP client using the SFTP protocol, host, port, and user credentials. The user directory is set as the root.

```ballerina
ftp:Client sftpClient = check new ({
    protocol: ftp:SFTP,
    host: "sftp.example.com",
    port: 22,
    auth: {
        credentials: {
            username: "user",
            password: "pass"
        }
    },
    userDirIsRoot: true
});
```

--------------------------------

### Initialize FTP Client

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/api-index.md

Initialize an FTP client endpoint using the ClientConfiguration. Ensure the 'ftp' module is imported.

```ballerina
ftp:Client client = check new(ClientConfiguration);
```

--------------------------------

### Get Remote File Size

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/ballerina/README.md

Retrieves the size of a specified file on the remote FTP server. The size is returned in bytes.

```ballerina
int|ftp:Error sizeResponse = ftpClient->size("<The resource path>");
```

--------------------------------

### ftp:Client Initialization

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/client.md

Initializes the FTP client with the provided configuration. This is the first step before performing any FTP operations.

```APIDOC
## ftp:Client Constructor

### Description
Initializes the FTP client with the provided configuration. This is the first step before performing any FTP operations.

### Signature
```ballerina
public isolated function init(ClientConfiguration clientConfig) returns Error?
```

### Parameters
#### Path Parameters
- **clientConfig** (ClientConfiguration) - Required - Configuration object for the FTP client

### Return
- `()` on successful initialization
- `ftp:Error` if initialization fails (e.g., invalid host, connection timeout)
```

--------------------------------

### Configure SFTP Listener with Password and Private Key Authentication

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/ballerina/README.md

Set up an SFTP listener with support for both username/password and private key authentication. Includes host, port, path, polling interval, and file name pattern.

```ballerina
listener ftp:Listener remoteServer = check new({
    protocol: ftp:SFTP,
    host: "<The SFTP host>",
    port: <The SFTP port>,
    path: "<The remote SFTP directory location>",
    pollingInterval: <Polling interval>,
    fileNamePattern: "<File name pattern>",
    auth: {
        credentials: {username: "<The SFTP username>", password: "<The SFTP password>"},
        privateKey: {
            path: "<The private key file path>",
            password: "<The private key file password>"
        }
    }
});
```

--------------------------------

### Initialize FTP Listener

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/listener.md

Initializes an FTP listener with connection details, path, and authentication credentials. This snippet demonstrates setting up a listener for FTP protocol.

```ballerina
import ballerina/ftp;

listener ftp:Listener remoteServer = check new({
    protocol: ftp:FTP,
    host: "ftp.example.com",
    port: 21,
    path: "/uploads",
    pollingInterval: 60,
    auth: {
        credentials: {
            username: "user",
            password: "pass"
        }
    }
});

service on remoteServer {
    remote function onFileText(string content, ftp:FileInfo fileInfo) returns error? {
        io:println("New text file: " + fileInfo.name);
    }
}
```

--------------------------------

### Stream Handling

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/listener.md

Demonstrates how to handle file content as a stream, including consuming chunks and closing the stream.

```ballerina
remote function onFile(stream<byte[], error?> content, ftp:FileInfo info) returns error? {
    record {|byte[] value;|}? chunk = check content.next();
    while chunk is record {|byte[] value;|} {
        // Process chunk
        chunk = check content.next();
    }
    check content.close();
}

```

--------------------------------

### Build Ballerina FTP Library

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/README.md

Execute this command to clean and build the Ballerina FTP library from source.

```bash
./gradlew clean build
```

--------------------------------

### Get CSV File Content as Stream

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/client.md

Retrieves CSV file content as a stream of rows or records for memory-efficient processing. Specify the target row type for parsing.

```ballerina
type Row record {
    string id;
    string name;
    string email;
};

stream<Row, error?> csvStream = check ftpClient->getCsvAsStream("/remote/large.csv");
record {|Row value;|}? row = check csvStream.next();
while row is record {|Row value;|} {
    // Process row
    row = check csvStream.next();
}
check csvStream.close();
```

--------------------------------

### Create Backup File Before Processing using Caller

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/caller.md

Demonstrates creating a backup of an incoming file before processing it, using the `copy` method of the ftp:Caller.

```ballerina
service on remoteServer {
    remote function onFileJson(json data, ftp:FileInfo info, ftp:Caller? caller) returns error? {
        if caller is ftp:Caller {
            // Create backup before processing
            check caller->copy(info.path, info.path + ".backup");
            
            // Process the file
            // ...
        }
    }
}
```

--------------------------------

### Initialize FTP Listener

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/api-index.md

Initialize an FTP listener endpoint using the ListenerConfiguration. Ensure the 'ftp' module is imported.

```ballerina
listener ftp:Listener server = check new(ListenerConfiguration);
```

--------------------------------

### Get File Content as Byte Stream

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/client.md

Retrieves file content as a stream of byte arrays for efficient handling of large files. Ensure the file path is correct.

```ballerina
stream<byte[], error?> byteStream = check ftpClient->getBytesAsStream("/remote/large.bin");
record {|byte[] value;|}? chunk = check byteStream.next();
while chunk is record {|byte[] value;|} {
    // Process chunk
    chunk = check byteStream.next();
}
check byteStream.close();
```

--------------------------------

### SFTP Client with Key-Based Authentication

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/configuration.md

Initializes an SFTP client using private key authentication. Specify the path to your private key file and its password if applicable.

```ballerina
ftp:ClientConfiguration sftpConfig = {
    protocol: ftp:SFTP,
    host: "sftp.example.com",
    port: 22,
    auth: {
        privateKey: {
            path: "/home/user/.ssh/id_rsa",
            password: "keypassword"
        }
    }
};

ftp:Client sftpClient = check new(sftpConfig);
```

--------------------------------

### FTP Client with Circuit Breaker Configuration

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/spec/spec.md

Configures an FTP client with a circuit breaker to prevent cascading failures. This setup defines thresholds and timings for tripping the circuit breaker when the server becomes unavailable.

```ballerina
ftp:Client ftpClient = check new ({
    protocol: ftp:FTP,
    host: "ftp.example.com",
    circuitBreaker: {
        failureThreshold: 0.5,
        resetTime: 30,
        rollingWindow: {
            requestVolumeThreshold: 5,
            timeWindow: 60,
            bucketSize: 10
        },
        failureCategories: [ftp:CONNECTION_ERROR, ftp:TRANSIENT_ERROR]
    }
});
```

--------------------------------

### Initialize Insecure FTP Client

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/spec/spec.md

Initializes an insecure FTP client by specifying the FTP protocol, host, and port.

```ballerina
ftp:Client ftpClient = check new ({
    protocol: ftp:FTP,
    host: "ftp.example.com",
    port: 21
});
```

--------------------------------

### Configure FTPS Listener

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/ballerina/README.md

Set up an FTPS listener to monitor a secure directory. Requires authentication credentials and truststore configuration for secure connections.

```ballerina
listener ftp:Listener ftpsListener = check new({
    protocol: ftp:FTPS,
    host: "ftps.example.com",
    port: 990,
    path: "/upload",
    pollingInterval: 5,
    auth: {
        credentials: { username: "user", password: "password" },
        secureSocket: {
            cert: { path: "/path/to/truststore.jks", password: "password" },
            mode: ftp:IMPLICIT
        }
    }
});
```

--------------------------------

### List Files in a Directory

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/spec/spec.md

Lists files in a specified directory and prints their names and sizes. Requires the ftp:FileInfo type and io:println for output.

```ballerina
ftp:FileInfo[] files = check ftpClient->list("/incoming");
foreach ftp:FileInfo file in files {
    io:println(file.name + " (" + file.size.toString() + " bytes)");
}
```

--------------------------------

### Handle Binary Files with FTP Listener

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/ballerina/README.md

Configure an FTP listener to process binary files. The `onFile` method receives the file content as a byte array and file information.

```ballerina
service on remoteServer {
    // Handle as byte array
    remote function onFile(byte[] content, ftp:FileInfo fileInfo) returns error? {
        log:print("Binary file: " + fileInfo.path);
        log:print("File size: " + content.length().toString());
    }
}
```

--------------------------------

### Process CSV Only When Marker File Exists

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/spec/spec.md

This example demonstrates conditional file processing using `fileDependencyConditions`. It configures the service to process CSV files only if a corresponding '.marker' file exists in the same directory. It uses `targetPattern` and `requiredFiles` with `matchingMode: ftp:ALL`.

```ballerina
@ftp:ServiceConfig {
    path: "/incoming/orders",
    fileNamePattern: "order_.*\\.csv",
    fileDependencyConditions: [
        {
            targetPattern: "order_(\d+)\\.csv",
            requiredFiles: ["order_$1.marker"],
            matchingMode: ftp:ALL
        }
    ]
}
service on ftpListener {
    remote function onFileCsv(record {}[] content, ftp:FileInfo fileInfo, ftp:Caller caller) returns error? {
        check caller->move(fileInfo.path, "/processed/" + fileInfo.name);
    }
}
```

--------------------------------

### Configure FTPS Client

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/ballerina/README.md

Set up an FTPS client configuration, specifying the protocol, host, port, and secure socket details including keystore, truststore, and connection mode (Explicit/Implicit).

```ballerina
ftp:ClientConfiguration ftpsConfig = {
    protocol: ftp:FTPS,
    host: "ftps.example.com",
    port: 21, // 21 for EXPLICIT, 990 for IMPLICIT
    auth: {
        credentials: { username: "user", password: "password" },
        secureSocket: {
            key: {
                path: "/path/to/keystore.p12",
                password: "keystore-password"
            },
            cert: {
                path: "/path/to/truststore.p12",
                password: "truststore-password"
            },
            mode: ftp:EXPLICIT, // or ftp:IMPLICIT
            dataChannelProtection: ftp:PRIVATE // PROT P (Encrypted data channel)
        }
    }
};

ftp:Client ftpsClient = check new(ftpsConfig);
```

--------------------------------

### Configure FTP Client Settings

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/types.md

Sets up an FTP client configuration using Ballerina enums and records. This includes defining the protocol, transfer mode, authentication credentials, and connection details.

```ballerina
import ballerina/ftp;

// Using enums
ftp:Protocol protocol = ftp:SFTP;
ftp:FileTransferMode mode = ftp:BINARY;
ftp:PreferredMethod[] methods = [ftp:PUBLICKEY, ftp:PASSWORD];

// Using records
ftp:Credentials creds = {
    username: "user",
    password: "pass"
};

ftp:PrivateKey key = {
    path: "/home/user/.ssh/id_rsa",
    password: "keypass"
};

ftp:AuthConfiguration auth = {
    credentials: creds,
    privateKey: key
};

ftp:ClientConfiguration config = {
    protocol: ftp:SFTP,
    host: "sftp.example.com",
    port: 22,
    auth: auth,
    retryConfig: {
        count: 3,
        interval: 2.0
    }
};
```

--------------------------------

### Fallback Binary File Handling with onFile

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/listener.md

Use `onFile` as a fallback for unhandled file extensions, processing binary content as a byte array or stream.

```ballerina
service on remoteServer {
    // Handle as byte array
    remote function onFile(byte[] content, ftp:FileInfo fileInfo) returns error? {
        io:println("Binary file: " + fileInfo.name + " (" + content.length().toString() + " bytes)");
    }
    
    // Or streaming for large files
    remote function onFile(stream<byte[], error?> content, ftp:FileInfo fileInfo) returns error? {
        record {|byte[] value;|}? chunk = check content.next();
        while chunk is record {|byte[] value;|} {
            // Process chunk
            chunk = check content.next();
        }
        check content.close();
    }
}
```

--------------------------------

### Initialize Secure SFTP Listener

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/spec/spec.md

Initializes a secure SFTP listener with authentication credentials and private key configuration. The user directory is set as the root.

```ballerina
listener ftp:Listener ftpListener = check new ({
    protocol: ftp:SFTP,
    host: "sftp.example.com",
    port: 22,
    auth: {
        credentials: {
            username: "user",
            password: "pass"
        },
        privateKey: {
            path: "/path/to/private.key",
            password: "keypassphrase"
        }
    },
    pollingInterval: 60,
    userDirIsRoot: true
});
```

--------------------------------

### Handle XML Files with onFileXml

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/listener.md

Use `onFileXml` to process `.xml` files. Content can be handled as generic `xml` or bound to a record type.

```ballerina
service on remoteServer {
    remote function onFileXml(xml content, ftp:FileInfo fileInfo) returns error? {
        io:println("XML file: " + fileInfo.name);
    }
}
```

--------------------------------

### mkdir

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/client.md

Creates a new directory on the FTP server at the specified path.

```APIDOC
## mkdir

### Description
Creates a new directory on the FTP server at the specified path.

### Method
POST (assumed, as it's a directory creation operation)

### Endpoint
/remote/

### Parameters
#### Path Parameters
- **path** (string) - Required - Directory path to create
```

--------------------------------

### Build Library Without Tests

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/README.md

Execute this command to build the Ballerina FTP library, excluding the test execution.

```bash
./gradlew clean build -x test
```

--------------------------------

### Initialize Insecure FTP Listener

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/spec/spec.md

Initializes an insecure FTP listener. The monitored directory is configured at the service level.

```ballerina
listener ftp:Listener ftpListener = check new ({
    protocol: ftp:FTP,
    host: "ftp.example.com",
    port: 21,
    pollingInterval: 30
});
```

--------------------------------

### onFileText

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/listener.md

Handles `.txt` files by deserializing content as UTF-8 text. It takes the file content as a string and file metadata as input.

```APIDOC
## onFileText

### Description
Handles `.txt` files by deserializing content as UTF-8 text. It takes the file content as a string and file metadata as input.

### Signature
```ballerina
remote function onFileText(string content, ftp:FileInfo fileInfo) returns error?
```

### Parameters
#### Parameters
- **content** (string) - Required - File content as text
- **fileInfo** (ftp:FileInfo) - Required - File metadata

### Return
`error?` — `()` on success, error to trigger `onError`

### Example
```ballerina
service on remoteServer {
    remote function onFileText(string content, ftp:FileInfo fileInfo) returns error? {
        io:println("Text file: " + fileInfo.path);
        io:println("Content: " + content);
    }
}
```
```

--------------------------------

### List Files and Directories

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/client.md

Lists all files and subdirectories within a specified remote directory. Useful for iterating over directory contents.

```ballerina
ftp:FileInfo[] files = check ftpClient->list("/remote");
foreach ftp:FileInfo f in files {
    io:println(f.name + " (" + f.size.toString() + " bytes)");
}
```

--------------------------------

### Debug Library Implementation

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/README.md

Use this command to build the Ballerina FTP library with debugging enabled for the Java implementation, specifying the debug port.

```bash
./gradlew clean build -Pdebug=<port>
```

--------------------------------

### Listener File Events by Type (PromQL)

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/spec/spec.md

Derives counts for listener file events, filtered by event type. Use this to monitor file creation events.

```promql
# Listener file events by type
rate(requests_total_value{action_type="event", event_type="create"}[1m])
```

--------------------------------

### Handle Text Files with FTP Listener

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/ballerina/README.md

Configure an FTP listener to process text files. The `onFileText` method receives file content as a string and file information.

```ballerina
service on remoteServer {
    remote function onFileText(string content, ftp:FileInfo fileInfo) returns error? {
        log:print("Text file: " + fileInfo.path);
        log:print("Content: " + content);
    }
}
```

--------------------------------

### Run Ballerina FTP Tests

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/README.md

Execute this command to clean and run all tests for the Ballerina FTP library.

```bash
./gradlew clean test
```

--------------------------------

### FTP Listener with Age Filtering

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/configuration.md

Sets up an FTP listener to process files within a specified age range, using the last modified timestamp for calculation.

```ballerina
@ftp:ServiceConfig {
    path: "/data",
    fileAgeFilter: {
        minAge: 5,      // Skip files modified less than 5 seconds ago
        maxAge: 86400,  // Skip files modified more than 1 day ago
        ageCalculationMode: ftp:LAST_MODIFIED
    }
}
service on remoteServer {
    remote function onFileText(string content, ftp:FileInfo info) returns error? {
        io:println("Processing file: " + info.name);
    }
}
```

--------------------------------

### Publish to Local Ballerina Central

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/README.md

Run this command to publish the generated artifacts to the local Ballerina central repository.

```bash
./gradlew clean build -PpublishToLocalCentral=true
```

--------------------------------

### Debug with Ballerina Language

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/README.md

Execute this command to build the Ballerina FTP library with debugging enabled for the Ballerina language, specifying the debug port.

```bash
./gradlew clean build -PbalJavaDebug=<port>
```

--------------------------------

### FTP Listener Configuration

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/types.md

Configure an FTP listener for monitoring remote directories. Supports various protocols, authentication, polling intervals, and file filtering.

```ballerina
public type ListenerConfiguration record {|Protocol protocol = FTP;
    string host = "127.0.0.1";
    int port = 21;
    AuthConfiguration auth?;
    string path = "/";
    string fileNamePattern?;
    decimal pollingInterval = 60;
    boolean userDirIsRoot = false;
    FileAgeFilter fileAgeFilter?;
    FileDependencyCondition[] fileDependencyConditions = [];
    boolean laxDataBinding = false;
    decimal connectTimeout = 30.0;
    SocketConfig socketConfig?;
    ProxyConfiguration proxy?;
    FileTransferMode fileTransferMode = BINARY;
    TransferCompression[] sftpCompression = [NO];
    string sftpSshKnownHosts?;
    FailSafeOptions csvFailSafe?;
    CoordinationConfig coordination?;
    RetryConfig retryConfig?;
|};
```

--------------------------------

### Initialize Secure FTPS Client

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/spec/spec.md

Initializes a secure FTPS client with credentials and custom SSL/TLS configurations, including a truststore and explicit connection mode.

```ballerina
ftp:Client ftpsClient = check new ({
    protocol: ftp:FTPS,
    host: "ftps.example.com",
    port: 21,
    auth: {
        credentials: {username: "user", password: "pass"},
        secureSocket: {
            cert: {path: "/path/to/truststore.p12", password: "changeit"},
            mode: ftp:EXPLICIT
        }
    }
});
```

--------------------------------

### All FTP Activity on a Specific Node (PromQL)

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/spec/spec.md

Calculates the rate of all FTP activity on a specific node over a 1-minute window, filtering by host and Ballerina FTP module. Use this for overall FTP traffic monitoring on a given node.

```promql
# All FTP activity on a specific node
rate(requests_total_value{host="node-1", src_module=~"ballerina/ftp.*"}[1m])
```

--------------------------------

### FTP Coordination Configuration

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/types.md

Configure distributed task coordination for multiple FTP listeners. Requires database configuration for state management.

```ballerina
public type CoordinationConfig record {|task:DatabaseConfig databaseConfig = <task:MysqlConfig>{};
    int livenessCheckInterval = 30;
    string memberId;
    string coordinationGroup;
    int heartbeatFrequency = 1;
|};
```

--------------------------------

### Route File by Name Pattern with Post-Processing

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/spec/spec.md

This snippet illustrates routing files based on a specific name pattern and performing a post-processing move action. It utilizes `fileNamePattern` to match files like 'order_*.csv' and moves them to '/processed/'.

```ballerina
service on ftpListener {
    @ftp:FunctionConfig {
        fileNamePattern: "order_.*\\.csv",
        afterProcess: {moveTo: "/processed/"}
    }
    remote function onFileCsv(Employee[] content, ftp:FileInfo fileInfo) returns error? {
        saveEmployees(content);
    }
}
```

--------------------------------

### Catch File Already Exists Errors

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/errors.md

Demonstrates catching `ftp:FileAlreadyExistsError` when trying to create a directory that already exists, preventing accidental overwrites or duplicate creations.

```ballerina
do {
    check ftpClient->mkdir("/remote/existing-dir");
} on fail ftp:FileAlreadyExistsError e {
    io:println("Directory already exists: " + e.message());
}
```

--------------------------------

### FTP Listener with File Dependencies

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/configuration.md

Configures an FTP listener to process a file only if its corresponding dependency files exist, ensuring data integrity.

```ballerina
@ftp:ServiceConfig {
    path: "/data",
    fileNamePattern: "data_([0-9]+)\\.csv$",
    fileDependencyConditions: [
        {
            targetPattern: "data_([0-9]+)\\.csv$",
            requiredFiles: ["data_$1.csv.metadata"],
            matchingMode: ftp:ALL
        }
    ]
}
service on remoteServer {
    remote function onFileCsv(string[][] data, ftp:FileInfo info) returns error? {
        // Only processes CSV files if corresponding .metadata file exists
        io:println("Processing: " + info.name);
    }
}
```

--------------------------------

### list

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/client.md

Lists all files and subdirectories in a directory on the FTP server.

```APIDOC
## list

### Description
Lists all files and subdirectories in a directory.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)

### Parameters
#### Path Parameters
- **path** (string) - Required - Directory path to list

### Return
- Array of FileInfo records
- ftp:Error if listing fails

### Example
```ballerina
ftp:FileInfo[] files = check ftpClient->list("/remote");
foreach ftp:FileInfo f in files {
    io:println(f.name + " (" + f.size.toString() + " bytes)");
}
```
```

--------------------------------

### FTP Service Configuration

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/types.md

Configure service-level monitoring for FTP directories. Includes path, file name patterns, and filtering options.

```ballerina
public type ServiceConfiguration record {|string path;
    string fileNamePattern?;
    FileAgeFilter fileAgeFilter?;
    FileDependencyCondition[] fileDependencyConditions = [];
|};
```

--------------------------------

### Configure FTP Service with Path and File Filters

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/configuration.md

Define service-level monitoring configuration, including the path, file name pattern, and optional file age or dependency filters. Used with the @ftp:ServiceConfig annotation.

```ballerina
public type ServiceConfiguration record {|
    string path;
    string fileNamePattern?;
    FileAgeFilter fileAgeFilter?;
    FileDependencyCondition[] fileDependencyConditions = [];
|};

@ftp:ServiceConfig {
    path: "/uploads",
    fileNamePattern: ".*\.txt$",
    fileAgeFilter: {
        minAge: 5,
        maxAge: 3600
    }
}
service on remoteServer {
    remote function onFileText(string content, ftp:FileInfo info) returns error? {
        // ...
    }
}
```

--------------------------------

### SFTP Client Configuration with Password and Private Key Authentication

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/ballerina/README.md

Define SFTP client configuration supporting both password-based and private key-based authentication. Specify paths and passwords for credentials and private keys.

```ballerina
ftp:ClientConfiguration sftpConfig = {
    protocol: ftp:SFTP,
    host: "<The SFTP host>",
    port: <The SFTP port>,
    auth: {
        credentials: {username: "<The SFTP username>", password: "<The SFTP password>"},
        privateKey: {
            path: "<The private key file path>",
            password: "<The private key file password>"
        }
    }
};
```

--------------------------------

### Configure Distributed Task Coordination

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/configuration.md

Set up distributed task coordination for multiple listeners using database configuration, liveness checks, and heartbeat frequencies. Requires a unique memberId and coordinationGroup.

```ballerina
public type CoordinationConfig record {|
    task:DatabaseConfig databaseConfig = <task:MysqlConfig>{};
    int livenessCheckInterval = 30;
    string memberId;
    string coordinationGroup;
    int heartbeatFrequency = 1;
|};

ftp:CoordinationConfig coordination = {
    databaseConfig: {
        host: "db.example.com",
        port: 3306,
        user: "coord",
        password: "coordpass",
        database: "ftp_coord"
    },
    memberId: "listener-node-1",
    coordinationGroup: "production-ftp",
    livenessCheckInterval: 30,
    heartbeatFrequency: 1
};
```

--------------------------------

### Handle XML Files with FTP Listener

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/ballerina/README.md

Configure an FTP listener to process XML files, handling them as a typed record. The `onFileXml` method receives deserialized XML content and file information.

```ballerina
type Config record {
    string database;
    int timeout;
    boolean debug;
};

service on remoteServer {
    // Handle as typed record
    remote function onFileXml(Config content, ftp:FileInfo fileInfo) returns error? {
        log:print("Config file: " + fileInfo.path);
        log:print("Database: " + content.database);
    }
}
```

--------------------------------

### Define FTP Client Configuration

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/types.md

Configures settings for an FTP client connection. Includes protocol, host, port, authentication, timeouts, transfer mode, and optional retry/circuit breaker settings.

```ballerina
public type ClientConfiguration record {| 
    Protocol protocol = FTP;                           
    string host = "127.0.0.1";                        
    int port = 21;                                    
    AuthConfiguration auth?;                          
    boolean userDirIsRoot = false;                    
    boolean laxDataBinding = false;                   
    decimal connectTimeout = 30.0;                    
    SocketConfig socketConfig?;                       
    ProxyConfiguration proxy?;                        
    FileTransferMode fileTransferMode = BINARY;       
    TransferCompression[] sftpCompression = [NO];     
    string sftpSshKnownHosts?;                        
    FailSafeOptions csvFailSafe?;                     
    RetryConfig retryConfig?;                         
    CircuitBreakerConfig circuitBreaker?;             
|};

```

--------------------------------

### Handle Multiple Specific FTP Errors

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/errors.md

Demonstrates handling specific FTP errors like `FileNotFoundError` and `ConnectionError`, followed by a general `ftp:Error` catch-all. This allows for tailored responses to different failure scenarios.

```ballerina
do {
    check ftpClient->delete("/remote/file.txt");
} on fail ftp:FileNotFoundError e {
    io:println("File doesn't exist, continuing...");
} on fail ftp:ConnectionError e {
    io:println("Connection error, will retry later");
    return e;
} on fail ftp:Error e {
    io:println("Unexpected FTP error: " + e.message());
    return e;
}
```

--------------------------------

### FTP Preferred SFTP Methods

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/configuration.md

Configures preferred SFTP authentication methods in a specific order, including public key, keyboard interactive, and password.

```ballerina
ftp:AuthConfiguration auth = {
    credentials: {
        username: "user",
        password: "password"
    },
    preferredMethods: [ftp:PUBLICKEY, ftp:KEYBOARD_INTERACTIVE, ftp:PASSWORD]
};
```

--------------------------------

### Publish to Ballerina Central

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/README.md

Execute this command to publish the generated artifacts to the main Ballerina central repository.

```bash
./gradlew clean build -PpublishToCentral=true
```

--------------------------------

### Configure HTTP CONNECT Proxy

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/configuration.md

Use this configuration for FTP connections through an HTTP CONNECT proxy. Requires host, port, type, and optional authentication credentials.

```ballerina
ftp:ProxyConfiguration proxy = {
    host: "proxy.example.com",
    port: 3128,
    'type: ftp:HTTP,
    auth: {
        username: "proxyuser",
        password: "proxypass"
    }
};
```

--------------------------------

### FTP Client with Retry Configuration

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/spec/spec.md

Initializes an FTP client with custom retry settings for read operations. This configuration helps in handling transient network issues by automatically retrying failed requests.

```ballerina
ftp:Client ftpClient = check new ({
    protocol: ftp:FTP,
    host: "ftp.example.com",
    retryConfig: {
        count: 5,
        interval: 2.0,
        backOffFactor: 1.5,
        maxWaitInterval: 20.0
    }
});
```

--------------------------------

### Upload File as Binary Stream

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/ballerina/README.md

Uploads a file to a remote FTP server by reading it as a stream of blocks. This is efficient for large files. Ensure the `putFilePath` and `<Block size>` are correctly defined.

```ballerina
stream<io:Block, io:Error?> fileByteStream
    = check io:fileReadBlocksAsStream(putFilePath, <Block size>);
ftp:Error? putResponse = ftpClient->put("<The resource path>", fileByteStream);
```

--------------------------------

### Append Content to Aggregate File using Caller

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/caller.md

Illustrates reading an existing aggregate file, appending new content to it, and saving the combined content using `getBytes` and `putBytes` with the `APPEND` option.

```ballerina
service on remoteServer {
    remote function onFile(byte[] content, ftp:FileInfo info, ftp:Caller? caller) returns error? {
        if caller is ftp:Caller {
            // Read existing aggregate file
            byte[] existing = [];
            if check caller->exists("/aggregate/combined.bin") {
                existing = check caller->getBytes("/aggregate/combined.bin");
            }
            
            // Append new content
            byte[] combined = existing + content;
            check caller->putBytes("/aggregate/combined.bin", combined, ftp:APPEND);
        }
    }
}
```

--------------------------------

### Client File Operations by Type (PromQL)

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/spec/spec.md

Derives counts for client file operations on SFTP, filtered by operation type and protocol. Use this to monitor specific client actions.

```promql
# Client file operations by type
rate(requests_total_value{action_type="operation", operation_type="admin", protocol="sftp"}[1m])
```

--------------------------------

### Enable Observability Configuration

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/spec/spec.md

Configuration settings for enabling metrics and tracing in the Ballerina runtime. Ensure these settings are present in your `Config.toml` file to activate observability.

```toml
[ballerina.observe]
metricsEnabled=true
metricsReporter="prometheus"
tracingEnabled=true
tracingProvider="jaeger"
```

--------------------------------

### Catch File Not Found Errors

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/errors.md

Shows how to catch `ftp:FileNotFoundError` when operations like reading, deleting, or listing files fail because the specified path does not exist on the server.

```ballerina
do {
    string content = check ftpClient->getText("/remote/missing.txt");
} on fail ftp:FileNotFoundError e {
    io:println("File not found: " + e.message());
}
```

--------------------------------

### Handle Text Files with onFileText

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/listener.md

Use `onFileText` to process files with UTF-8 text content. The content is provided as a string.

```ballerina
service on remoteServer {
    remote function onFileText(string content, ftp:FileInfo fileInfo) returns error? {
        io:println("Text file: " + fileInfo.path);
        io:println("Content: " + content);
    }
}
```

--------------------------------

### SFTP Listener with File Pattern Filtering

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/configuration.md

Configures an SFTP listener to monitor a specific directory and process files matching a defined naming pattern.

```ballerina
@ftp:ServiceConfig {
    path: "/uploads",
    fileNamePattern: "([a-z]+)_data_\\d{8}\\.json$"
}
service on remoteServer {
    remote function onFileJson(json data, ftp:FileInfo info) returns error? {
        io:println("Processing data file: " + info.name);
    }
}
```

--------------------------------

### Data Binding Configuration

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/spec/spec.md

Explains how the `targetType` parameter in read methods supports data binding and the effect of the `laxDataBinding` client configuration.

```APIDOC
## Data Binding

### Description
The typed read methods (`getJson`, `getXml`, `getCsv`, `getCsvAsStream`) support data binding through the `targetType` parameter, which automatically binds parsed content to a specified Ballerina type. The `laxDataBinding` client configuration influences how structured data is bound, allowing for flexible handling of missing or null fields.

### Parameters
- **targetType** - Optional - The Ballerina type to bind the parsed content to.

### Configuration
- **laxDataBinding** (boolean) - Client configuration that controls strictness of data binding. `true` allows missing/null fields; `false` (default) enforces strict binding.

### Error Handling
- Returns `ContentBindingError` if parsing or binding fails.
```

--------------------------------

### FTP Client Methods

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/api-index.md

The primary API for connecting to and managing FTP/SFTP servers. This includes read, write, directory, file, and query operations, as well as connection management.

```APIDOC
## FTP Client Operations

### Description
Provides methods for interacting with FTP/SFTP servers, including file operations, directory management, and connection handling.

### Methods
#### Read Operations
- `getBytes()`
- `getText()`
- `getJson()`
- `getXml()`
- `getCsv()`
- `getBytesAsStream()`
- `getCsvAsStream()`

#### Write Operations
- `putBytes()`
- `putText()`
- `putJson()`
- `putXml()`
- `putCsv()`
- `putBytesAsStream()`
- `putCsvAsStream()`

#### Directory Operations
- `mkdir()`
- `rmdir()`
- `list()`

#### File Operations
- `delete()`
- `rename()`
- `move()`
- `copy()`

#### Query Operations
- `size()`
- `exists()`
- `isDirectory()`

#### Connection
- `close()`

### Initialization
```ballerina
ftp:Client client = check new(ClientConfiguration);
```
```