# SSH JavaScript API

## Connector functions SSH JS API guide

This API allows users to execute operations in the SSH client from a connector function.

## Ssh Object

The `ssh object` is the main object of the SSH client. It allows to connect
to an SSH server, send commands and receive responses and disconnect from the
SSH server.

### Ssh Object Properties

| Property  | Type   | Default | Description                   |
|-----------|--------|---------|-------------------------------|
| ip        | string |         | IP address of the SSH server. |
| port      | number | 23      | Port of the SSH server.       |
| retries   | number | 3       | Number of retries.            |
| timeout   | number | 5000    | Timeout in milliseconds.      |
| user      | string |         | SSH user.                     |
| password  | string |         | SSH password.                 |
| identity  | string |         | Rsa key content.              |


### Ssh Object Methods

#### ssh.connect(waitFor)

Establish a connection with the SSH server.

| Property | Type | Default | Description                          |
|----------|------|---------|--------------------------------------|
| waitFor  | List |         | Strings to wait for in the response. |

Connects to the SSH server using the properties of the `ssh object`:

* `ip`: IP address of the SSH server.
* `port`: Port of the SSH server.
* `retries`: Number of retries.
* `timeout`: Timeout in milliseconds.
* `user`: SSH user.
* `password`: SSH password.
* `identity`: Rsa key content.

Returns an object with the following properties:

* `result`: `true` if the connection was successful, `false` otherwise.
* `message`: Empty if the connection was successful, error message otherwise.

Example of use:

```javascript
ssh.ip = "[IP_ADDRESS]";
ssh.port = 22;
ssh.user = "sshuser";
ssh.password = "password";

// this example shows how to connect to an SSH server and wait for the "Connection established" string.
var connectResult = ssh.connect(["Connection established"]);

if (connectResult.result) {
    // Connection was successful
} else {
    // Connection failed
}
```

#### ssh.send(command, pattern, waitFor)

Sends a command to the SSH server and waits for the response.

| Parameter | Type   | Description                                      |
|-----------|--------|--------------------------------------------------|
| command   | string | Command to send to the SSH server.               |
| pattern   | string | Pattern to extract response from sent command.   |
| waitFor   | List   | Strings to wait for in the response.             |

* `retries`: Number of retries.
* `timeout`: Timeout in milliseconds.

Returns the response of the SSH server in string format.

Example of use:

```javascript
// this example shows how to send a command to an SSH server and wait for the "/home/sshuser" string.
var sendResult = ssh.send("ls -la", "*", ["/home/sshuser"]);
```

#### ssh.disconnect()

Disconnects from the SSH server.

Example of use:

```javascript
ssh.disconnect();
```