node-urbackup-server-api

This module provides a Node.js interface for interacting with the UrBackup server's web API, whether the server is installed locally or accessed over a network. It facilitates the management and monitoring of backup operations by offering a range of functionalities, including:

- Viewing and modifying server settings
- Viewing and modifying client settings
- Adding or removing clients
- Managing groups
- Retrieving information about running tasks and client statuses
- Managing backup jobs, including starting and stopping backups
- Accessing live logs
- Fetching backup history and details for specific clients

The module aims to simplify the integration of UrBackup server management into Node.js applications, making it easier to automate and control backup operations programmatically.

_Please note that this module is still in a pre-1.0.0 release. Some functionality is missing, and method signatures may change without notice. Always review the CHANGELOG before updating to understand any potential breaking changes._

Requirements

To use this module, ensure you have the following:

- An Active LTS or Maintenance LTS version of Node.js (https://nodejs.org/en/about/previous-releases)
- A current release of the UrBackup Server

Installation

To install the module, use npm:

``shell
npm install urbackup-server-api
`

Usage Example

Here's a basic example to get you started:

`javascript
import { UrbackupServer } from 'urbackup-server-api';

// When troubleshooting TSL connections with self-signed certificates you may try to disable certificate validation. Keep in mind that it's strongly discouraged for production use.
//process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';

const server = new UrbackupServer({
url: 'http://127.0.0.1:55414',
username: 'admin',
password: 'secretpassword',
});

(async () => {
try {
// Check if server is currently busy
const activities = await urbackup.getCurrentActivities();
console.log(Busy: ${activities.length > 0});

// Get a list of production clients
const prodClients = await urbackup
.getGroupMembers({ groupName: 'prod' })
.then((data) => console.log(data));

// Get production clients with failed image backup
const failedClients = await urbackup
.getFailedClients({ groupName: 'prod', includeFileBackups: false })
.then((data) => console.log(data));

// Get all clients without both file and image backups
const blankClients = await urbackup
.getBlankClients()
.then((data) => console.log(data));
} catch (error) {
// Deal with it
}
})();
`

Example implementation

urbstat

The missing command-line tool for UrBackup Server. It provides valuable insights into the utilization of data, clients' status and activities, and helps administrator to identify, troubleshoot and resolve issues that may arise within the system.

---

Below is an automatically generated reference from JSDoc.

UrbackupServer

Represents a UrBackup Server.

Kind: global class

- UrbackupServer
- [new UrbackupServer([params])](#new_UrbackupServer_new)
- .getServerIdentity() ⇒ Promise.<string>
- .getServerVersion() ⇒ Promise.<object>
- .isServerOutdated() ⇒ Promise.<boolean>
- .getUsers() ⇒ Promise.<Array.<object>>
- .addUser(params) ⇒ Promise.<boolean>
- .removeUser(params) ⇒ Promise.<boolean>
- [.getUserRights([params])](#UrbackupServer+getUserRights) ⇒ Promise.<(Array\|null)>
- .getGroups() ⇒ Promise.<Array.<object>>
- .addGroup(params) ⇒ Promise.<boolean>
- .removeGroup(params) ⇒ Promise.<boolean>
- .getGroupMembers(params) ⇒ Promise.<Array.<object>>
- [.getClients([params])](#UrbackupServer+getClients) ⇒ Promise.<Array.<object>>
- [.getRemovedClients([params])](#UrbackupServer+getRemovedClients) ⇒ Promise.<Array.<object>>
- [.getOnlineClients([params])](#UrbackupServer+getOnlineClients) ⇒ Promise.<Array.<object>>
- [.getOfflineClients([params])](#UrbackupServer+getOfflineClients) ⇒ Promise.<Array.<object>>
- [.getActiveClients([params])](#UrbackupServer+getActiveClients) ⇒ Promise.<Array.<object>>
- [.getBlankClients([params])](#UrbackupServer+getBlankClients) ⇒ Promise.<Array.<object>>
- [.getFailedClients([params])](#UrbackupServer+getFailedClients) ⇒ Promise.<Array.<object>>
- [.getOkClients([params])](#UrbackupServer+getOkClients) ⇒ Promise.<Array.<object>>
- [.getOutdatedClients([params])](#UrbackupServer+getOutdatedClients) ⇒ Promise.<Array.<object>>
- [.getConflictingClients([params])](#UrbackupServer+getConflictingClients) ⇒ Promise.<Array.<object>>
- [.getUnseenClients([params])](#UrbackupServer+getUnseenClients) ⇒ Promise.<Array.<object>>
- [.getStaleClients([params])](#UrbackupServer+getStaleClients) ⇒ Promise.<Array>
- .addClient(params) ⇒ Promise.<boolean>
- .removeClient(params) ⇒ Promise.<boolean>
- .cancelRemoveClient(params) ⇒ Promise.<boolean>
- .getClientHints() ⇒ Promise.<Array>
- .addClientHint(params) ⇒ Promise.<boolean>
- .removeClientHint(params) ⇒ Promise.<boolean>
- [.getClientSettings([params])](#UrbackupServer+getClientSettings) ⇒ Promise.<Array>
- .setClientSettings(params) ⇒ Promise.<boolean>
- .getClientGroup(params) ⇒ Promise.<(object\|null)>
- .setClientGroup(params) ⇒ Promise.<boolean>
- .getClientAuthkey(params) ⇒ Promise.<string>
- [.getStatus([params])](#UrbackupServer+getStatus) ⇒ Promise.<Array>
- [.getUsage([params])](#UrbackupServer+getUsage) ⇒ Promise.<Array>
- [.getActivities([params])](#UrbackupServer+getActivities) ⇒ Promise.<object>
- [.getCurrentActivities([params])](#UrbackupServer+getCurrentActivities) ⇒ Promise.<Array>
- [.getLastActivities([params])](#UrbackupServer+getLastActivities) ⇒ Promise.<Array>
- [.getPausedActivities([params])](#UrbackupServer+getPausedActivities) ⇒ Promise.<Array>
- .stopActivity(params) ⇒ Promise.<boolean>
- .getBackups(params) ⇒ Promise.<object>
- .startFullFileBackup(params) ⇒ Promise.<boolean>
- .startIncrementalFileBackup(params) ⇒ Promise.<boolean>
- .startFullImageBackup(params) ⇒ Promise.<boolean>
- .startIncrementalImageBackup(params) ⇒ Promise.<boolean>
- [.getLiveLog([params])](#UrbackupServer+getLiveLog) ⇒ Promise.<Array>
- .getGeneralSettings() ⇒ Promise.<object>
- .getMailSettings() ⇒ Promise.<object>
- .getLdapSettings() ⇒ Promise.<object>
- .setGeneralSettings(params) ⇒ Promise.<boolean>
- .getRawStatus() ⇒ Promise.<object>
- .getRawUsage() ⇒ Promise.<object>
- .getRawProgress() ⇒ Promise.<object>

$3

This is a constructor.

| Param | Type | Default | Description |
| ----------------- | ------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| [params] | object | | An optional object containing parameters. |
| [params.url] | string | "'http://127.0.0.1:55414'" | The URL of the server, must include the protocol, hostname, and port. Defaults to http://127.0.0.1:55414. |
| [params.username] | string | "''" | The username used for logging in. If empty, anonymous login method will be used. Defaults to an empty string. |
| [params.password] | string | "''" | The password used to log in. Defaults to an empty string. |

Example _(Connect to the built-in server locally without a password)_

`js
const server = new UrbackupServer();
`

Example _(Connect locally with a specified password)_

`js
const server = new UrbackupServer({
url: 'http://127.0.0.1:55414',
username: 'admin',
password: 'secretpassword',
});
`

Example _(Connect over the network)_

`js
const server = new UrbackupServer({
url: 'https://192.168.0.2:443',
username: 'admin',
password: 'secretpassword',
});
`

$3

Retrieves server identity.

Kind: instance method of UrbackupServer
Returns: Promise.<string> - The server identity.
Throws:

- Error If the API response is missing required values or if the login fails.

Example _(Get server identity)_

`js
server.getServerIdentity().then((data) => console.log(data));
`

$3

Retrieves the server version in both number and string representation.

Kind: instance method of UrbackupServer
Returns: Promise.<object> - An object containing the server version number and string.
Throws:

- Error If the API response is missing required values or if the login fails.

Example _(Get server version number)_

`js
server.getServerVersion().then((data) => console.log(data.number));
`

Example _(Get server version string)_

`js
server.getServerVersion().then((data) => console.log(data.string));
`

$3

Checks if the server version is outdated compared to the available version.

Kind: instance method of UrbackupServer
Returns: Promise.<boolean> - A promise that resolves to true if the server version is outdated, false otherwise.
Throws:

- Error If the API response is missing required values or if the login fails.

Example

`js
server.isServerOutdated().then((isOutdated) => console.log(isOutdated));
`

$3

Retrieves a list of users.

Kind: instance method of UrbackupServer
Returns: Promise.<Array.<object>> - A promise that resolves to an array of objects representing users. If no users are found, it returns an empty array.
Throws:

- Error If the login fails or the API response is missing expected values.

Example _(Get all users)_

`js
server.getUsers().then((data) => console.log(data));
`

$3

Adds a new user with the specified username, password, and rights.

Kind: instance method of UrbackupServer
Returns: Promise.<boolean> - A promise that resolves to true if the user was added successfully, false otherwise.
Throws:

- Error If required parameters are missing, the login fails, or the API response is missing expected values.

| Param | Type | Default | Description |
| ---------------- | --------------------------------- | ------------------ | --------------------------------------------------------------------------------------------- |
| params | object | | An object containing parameters. |
| params.userName | string | | The username for the new user. |
| params.password | string | | The password for the new user. |
| [params.isAdmin] | boolean | false | Whether the new user should have admin rights (all domains, all rights). Defaults to false. |
| [params.rights] | Array.<object> | | Array of user permissions. Ignored if isAdmin is true. Defaults to the default user rights. |

Example _(Add a regular user)_

`js
server
.addUser({ userName: 'newUser', password: 'userPassword' })
.then((result) => console.log(result));
`

Example _(Add an admin user)_

`js
server
.addUser({ userName: 'adminUser', password: 'adminPassword', isAdmin: true })
.then((result) => console.log(result));
`

$3

Removes a user by their user ID.

Kind: instance method of UrbackupServer
Returns: Promise.<boolean> - A promise that resolves to a boolean indicating whether the user was successfully removed.
Throws:

- Error If the userId parameter is missing or invalid, or if the login fails.

| Param | Type | Description |
| ------------- | ------------------- | --------------------------------- |
| params | object | An object containing parameters. |
| params.userId | number | The ID of the user to be removed. |

Example _(Remove a user by their ID)_

`js
server.removeUser({ userId: 123 }).then((status) => console.log(status));
`

$3

Retrieves the rights of a specific user.

Kind: instance method of UrbackupServer
Returns: Promise.<(Array\|null)> - A promise that resolves to an array of user rights, or null if the user is not found.
Throws:

- Error If the login fails or the API response is missing expected values.

| Param | Type | Default | Description |
| ----------------- | ------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| [params] | object | | An optional object containing parameters. |
| [params.userId] | string | | The user's ID. Takes precedence if both userId and userName are defined. Required if clientName is undefined. |
| [params.userName] | string | "this.#username" | The user's name. Ignored if userId is defined. Defaults to the username of the current session. Required if clientId is undefined. |

Example _(Get user rights of the current session user)_

`js
server.getUserRights().then((data) => console.log(data));
`

Example _(Get user rights by user ID)_

`js
server.getUserRights({ userId: '12345' }).then((data) => console.log(data));
`

Example _(Get user rights by user name)_

`js
server
.getUserRights({ userName: 'john_doe' })
.then((data) => console.log(data));
`

$3

Retrieves a list of groups.
By default, UrBackup clients are added to a group with ID 0 and an empty name (empty string).

Kind: instance method of UrbackupServer
Returns: Promise.<Array.<object>> - A promise that resolves to an array of objects representing groups. If no groups are found, it returns an empty array.
Throws:

- Error If the login fails or the API response is missing expected values.

Example _(Get all groups)_

`js
server.getGroups().then((data) => console.log(data));
`

$3

Adds a new group.

Kind: instance method of UrbackupServer
Returns: Promise.<boolean> - When successful, returns true. If the group already exists, or adding the group was not successful for any reason, returns false.
Throws:

- Error If the groupName is missing or invalid, or if the API response is missing expected values.

| Param | Type | Description |
| ---------------- | ------------------- | ------------------------------------------------------------- |
| params | object | An object containing parameters. |
| params.groupName | string | The group name. Must be unique and cannot be an empty string. |

Example _(Add new group)_

`js
server.addGroup({ groupName: 'prod' }).then((data) => console.log(data));
`

$3

Removes a group.
All clients in this group will be reassigned to the default group. Does not allow removal of the default group (ID: 0, name: '').

Kind: instance method of UrbackupServer
Returns: Promise.<boolean> - When the removal is successful, the method returns true. If the removal is not successful, the method returns false.
Throws:

- Error If both groupId and groupName are missing or invalid, or if the login fails.

| Param | Type | Description |
| ---------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| params | object | An object containing parameters. |
| params.groupId | number | Group ID. Must be greater than 0. Takes precedence if both groupId and groupName are defined. Required if groupName is undefined. |
| params.groupName | string | Group name. Must be different than empty string. Ignored if both groupId and groupName are defined. Required if groupId is undefined. |

Example _(Remove group)_

`js
server.removeGroup({ groupId: 1 }).then((data) => console.log(data));
server.removeGroup({ groupName: 'prod' }).then((data) => console.log(data));
`

$3

Retrieves a list of clients who are members of a given group.
This is only a convenience method that wraps the getClients() method.

Kind: instance method of UrbackupServer
Returns: Promise.<Array.<object>> - A promise that resolves to an array of objects representing clients matching the search criteria. Returns an empty array when no matching clients are found.
Throws:

- Error If both groupId and groupName are missing or invalid.

| Param | Type | Description |
| ---------------- | ------------------- | --------------------------------------------------------------------------------------------------------------- |
| params | object | An object containing parameters. |
| params.groupId | number | Group ID. Takes precedence if both groupId and groupName are defined. Required if groupName is undefined. |
| params.groupName | string | Group name. Ignored if both groupId and groupName are defined. Required if groupId is undefined. |

Example _(Get members of default group)_

`js
server.getGroupMembers({ groupId: 0 }).then((data) => console.log(data));
`

Example _(Get all clients belonging to a specific group)_

`js
server
.getGroupMembers({ groupName: 'office' })
.then((data) => console.log(data));
`

$3

Retrieves a list of clients.
By default, this method matches all clients, including those marked for removal.

Kind: instance method of UrbackupServer
Returns: Promise.<Array.<object>> - A promise that resolves to an array of objects representing clients matching the search criteria. Returns an empty array when no matching clients are found.
Throws:

- Error If the login fails or the API response is missing expected values.

| Param | Type | Default | Description |
| ----------------------- | -------------------- | ----------------- | ----------------------------------------------------------------------------- |
| [params] | object | | An optional object containing parameters. |
| [params.groupName] | string | | Group name. Defaults to undefined, which matches all groups. |
| [params.includeRemoved] | boolean | true | Whether or not clients pending deletion should be included. Defaults to true. |

Example _(Get all clients)_

`js
server.getClients().then((data) => console.log(data));
`

Example _(Get all clients, but exclude clients marked for removal)_

`js
server.getClients({ includeRemoved: false }).then((data) => console.log(data));
`

Example _(Get all clients belonging to a specific group)_

`js
server.getClients({ groupName: 'office' }).then((data) => console.log(data));
`

$3

Retrieves a list of clients marked for removal.

Kind: instance method of UrbackupServer
Returns: Promise.<Array.<object>> - A promise that resolves to an array of objects representing clients. Returns an empty array when no matching clients are found.
Throws:

- Error If the login fails or the API response is missing expected values.

| Param | Type | Description |
| ------------------ | ------------------- | ------------------------------------------------------------ |
| [params] | object | An optional object containing parameters. |
| [params.groupName] | string | Group name. Defaults to undefined, which matches all groups. |

Example _(Get clients marked for removal)_

`js
server.getRemovedClients().then((data) => console.log(data));
`

Example _(Get clients marked for removal in a specific group)_

`js
server
.getRemovedClients({ groupName: 'sales' })
.then((data) => console.log(data));
`

$3

Retrieves a list of online clients.

Kind: instance method of UrbackupServer
Returns: Promise.<Array.<object>> - A promise that resolves to an array of objects representing clients. Returns an empty array when no matching clients are found.
Throws:

- Error If the login fails or the API response is missing expected values.

| Param | Type | Default | Description |
| ----------------------- | -------------------- | ----------------- | -------------------------------------------------------------------------------------------------- |
| [params] | object | | An optional object containing parameters. |
| [params.groupName] | string | | Group name. Defaults to undefined, which matches all groups. |
| [params.includeRemoved] | boolean | true | Whether or not clients pending deletion should be included. Defaults to true. |
| [params.includeBlank] | boolean | true | Whether or not blank clients should be taken into account when matching clients. Defaults to true. |

Example _(Get all online clients)_

`js
server.getOnlineClients().then((data) => console.log(data));
`

Example _(Get online clients from a specific group)_

`js
server
.getOnlineClients({ groupName: 'servers' })
.then((data) => console.log(data));
`

$3

Retrieves a list of offline clients.

Kind: instance method of UrbackupServer
Returns: Promise.<Array.<object>> - A promise that resolves to an array of objects representing clients. Returns an empty array when no matching clients are found.
Throws:

- Error If the login fails or the API response is missing expected values.

| Param | Type | Default | Description |
| ----------------------- | -------------------- | ----------------- | -------------------------------------------------------------------------------------------------- |
| [params] | object | | An optional object containing parameters. |
| [params.groupName] | string | | Group name. Defaults to undefined, which matches all groups. |
| [params.includeRemoved] | boolean | true | Whether or not clients pending deletion should be included. Defaults to true. |
| [params.includeBlank] | boolean | true | Whether or not blank clients should be taken into account when matching clients. Defaults to true. |

Example _(Get all offline clients)_

`js
server.getOfflineClients().then((data) => console.log(data));
`

Example _(Get offline clients, skip clients marked for removal)_

`js
server
.getOfflineClients({ includeRemoved: false })
.then((data) => console.log(data));
`

Example _(Get offline clients from a specific groups)_

`js
server
.getOfflineClients({ groupName: 'servers' })
.then((data) => console.log(data));
`

$3

Retrieves a list of active clients.

Kind: instance method of UrbackupServer
Returns: Promise.<Array.<object>> - A promise that resolves to an array of objects representing clients. Returns an empty array when no matching clients are found.
Throws:

- Error If the login fails or the API response is missing expected values.

| Param | Type | Default | Description |
| ----------------------- | -------------------- | ----------------- | ----------------------------------------------------------------------------- |
| [params] | object | | An optional object containing parameters. |
| [params.groupName] | string | | Group name. Defaults to undefined, which matches all groups. |
| [params.includeRemoved] | boolean | true | Whether or not clients pending deletion should be included. Defaults to true. |

Example _(Get all active clients)_

`js
server.getActiveClients().then((data) => console.log(data));
`

$3

Retrieves a list of blank clients, i.e., clients without any finished file and/or image backups.
Matching empty clients considers whether file backups or image backups are enabled.
By default, it matches clients without both file and image backups.

Kind: instance method of UrbackupServer
Returns: Promise.<Array.<object>> - A promise that resolves to an array of objects representing clients. Returns an empty array when no matching clients are found.
Throws:

- Error If the login fails or the API response is missing expected values.

| Param | Type | Default | Description |
| ---------------------------- | -------------------- | ----------------- | -------------------------------------------------------------------------------------------------- |
| [params] | object | | An optional object containing parameters. |
| [params.groupName] | string | | Group name. Defaults to undefined, which matches all groups. |
| [params.includeRemoved] | boolean | true | Whether or not clients pending deletion should be included. Defaults to true. |
| [params.includeFileBackups] | boolean | true | Whether or not file backups should be taken into account when matching clients. Defaults to true. |
| [params.includeImageBackups] | boolean | true | Whether or not image backups should be taken into account when matching clients. Defaults to true. |

Example _(Get all blank clients, i.e., clients without both file and image backups)_

`js
server.getBlankClients().then((data) => console.log(data));
`

Example _(Get blank clients, skip clients marked for removal)_

`js
server
.getBlankClients({ includeRemoved: false })
.then((data) => console.log(data));
`

Example _(Get clients without any file backups)_

`js
server
.getBlankClients({ includeImageBackups: false })
.then((data) => console.log(data));
`

Example _(Get clients without any image backups)_

`js
server
.getBlankClients({ includeFileBackups: false })
.then((data) => console.log(data));
`

$3

Retrieves a list of failed clients, i.e., clients with failed backup status.

Kind: instance method of UrbackupServer
Returns: Promise.<Array.<object>> - A promise that resolves to an array of objects representing clients. Returns an empty array when no matching clients are found.
Throws:

- Error If the login fails or the API response is missing expected values.

| Param | Type | Default | Description |
| ---------------------------- | -------------------- | ------------------ | -------------------------------------------------------------------------------------------------- |
| [params] | object | | An optional object containing parameters. |
| [params.groupName] | string | | Group name. Defaults to undefined, which matches all groups. |
| [params.includeRemoved] | boolean | true | Whether or not clients pending deletion should be included. Defaults to true. |
| [params.includeBlank] | boolean | true | Whether or not blank clients should be taken into account when matching clients. Defaults to true. |
| [params.includeFileBackups] | boolean | true | Whether or not file backups should be taken into account when matching clients. Defaults to true. |
| [params.includeImageBackups] | boolean | true | Whether or not image backups should be taken into account when matching clients. Defaults to true. |
| [params.failOnFileIssues] | boolean | false | Whether or not to treat file backups finished with issues as being failed. Defaults to false. |

Example _(Get clients with failed file or image backups)_

`js
server.getFailedClients().then((data) => console.log(data));
`

Example _(Get failed clients, skip clients marked for removal)_

`js
server
.getFailedClients({ includeRemoved: false })
.then((data) => console.log(data));
`

Example _(Get clients with failed file backups)_

`js
server
.getFailedClients({ includeImageBackups: false })
.then((data) => console.log(data));
`

Example _(Get clients with failed image backups)_

`js
server
.getFailedClients({ includeFileBackups: false })
.then((data) => console.log(data));
`

$3

Retrieves a list of OK clients, i.e., clients with OK backup status.
File backups finished with issues are treated as OK by default.

Kind: instance method of UrbackupServer
Returns: Promise.<Array.<object>> - A promise that resolves to an array of objects representing clients. Returns an empty array when no matching clients are found.
Throws:

- Error If the login fails or the API response is missing expected values.

| Param | Type | Default | Description |
| ---------------------------- | -------------------- | ------------------ | -------------------------------------------------------------------------------------------------- |
| [params] | object | | An optional object containing parameters. |
| [params.groupName] | string | | Group name. Defaults to undefined, which matches all groups. |
| [params.includeRemoved] | boolean | true | Whether or not clients pending deletion should be included. Defaults to true. |
| [params.includeFileBackups] | boolean | true | Whether or not file backups should be taken into account when matching clients. Defaults to true. |
| [params.includeImageBackups] | boolean | true | Whether or not image backups should be taken into account when matching clients. Defaults to true. |
| [params.failOnFileIssues] | boolean | false | Whether or not to treat file backups finished with issues as being failed. Defaults to false. |

Example _(Get OK clients, use default parameters)_

`js
server.getOkClients().then((data) => console.log(data));
`

Example _(Get OK clients, skip clients marked for removal)_

`js
server
.getOkClients({ includeRemoved: false })
.then((data) => console.log(data));
`

Example _(Get clients with OK file backup, skip image backup status)_

`js
server
.getOkClients({ includeImageBackups: false })
.then((data) => console.log(data));
`

Example _(Get clients with OK file backup but treat backup issues as a failure, skip image backup status)_

`js
server
.getOkClients({ includeImageBackups: false, failOnFileIssues: true })
.then((data) => console.log(data));
`

$3

Retrieves a list of clients using an outdated version.

Kind: instance method of UrbackupServer
Returns: Promise.<Array.<object>> - A promise that resolves to an array of objects representing clients. Returns an empty array when no matching clients are found.
Throws:

- Error If the login fails or the API response is missing expected values.

| Param | Type | Default | Description |
| ----------------------- | -------------------- | ----------------- | ----------------------------------------------------------------------------- |
| [params] | object | | An optional object containing parameters. |
| [params.groupName] | string | | Group name. Defaults to undefined, which matches all groups. |
| [params.includeRemoved] | boolean | true | Whether or not clients pending deletion should be included. Defaults to true. |

Example _(Get all outdated clients)_

`js
server.getOutdatedClients().then((data) => console.log(data));
`

Example _(Get outdated clients in a specific group)_

`js
server
.getOutdatedClients({ groupName: 'exampleGroup' })
.then((data) => console.log(data));
`

Example _(Get outdated clients, exclude clients marked for removal)_

`js
server
.getOutdatedClients({ includeRemoved: false })
.then((data) => console.log(data));
`

$3

Retrieves a list of online clients with the same, i.e., conflicting IP address.

Kind: instance method of UrbackupServer
Returns: Promise.<Array.<object>> - A promise that resolves to an array of objects representing clients. Returns an empty array when no matching clients are found.
Throws:

- Error If the login fails or the API response is missing expected values.

| Param | Type | Default | Description |
| ----------------------- | -------------------- | ----------------- | ----------------------------------------------------------------------------- |
| [params] | object | | An optional object containing parameters. |
| [params.includeRemoved] | boolean | true | Whether or not clients pending deletion should be included. Defaults to true. |

Example _(Get all online clients with conflicting IP addresses)_

`js
server.getConflictingClients().then((data) => console.log(data));
`

Example _(Get online clients with conflicting IP addresses, exclude clients marked for removal)_

`js
server
.getConflictingClients({ includeRemoved: false })
.then((data) => console.log(data));
`

$3

Retrieves a list of clients who have not been seen for a specified period of time. Defaults to 24 hours.

Kind: instance method of UrbackupServer
Returns: Promise.<Array.<object>> - A promise that resolves to an array of objects representing clients. Returns an empty array when no matching clients are found.
Throws:

- Error If the login fails or the API response is missing expected values.

| Param | Type | Default | Description |
| ----------------------- | -------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------- |
| [params] | object | | An optional object containing parameters. |
| [params.groupName] | string | | Group name. Defaults to undefined, which matches all groups. |
| [params.includeRemoved] | boolean | true | Whether or not clients pending deletion should be included. Defaults to true. |
| [params.includeBlank] | boolean | true | Whether or not blank clients should be taken into account when matching clients. Defaults to true. |
| [params.timeThreshold] | number | 1440 | A time threshold, measured in minutes, after which a client is considered unseen. Defaults to 1440 minutes (24 hours). |

Example _(Get clients not seen for more than 2 days)_

`js
server
.getUnseenClients({ timeThreshold: 2880 })
.then((data) => console.log(data));
`

$3

Retrieves a list of clients that are considered "stale" (i.e., have backups older than the specified threshold).
This method fetches all clients within a specified group and filters those that are stale based on their last backup times.
Optionally, it can exclude blank clients (clients with no backups) from the results.

Kind: instance method of UrbackupServer
Returns: Promise.<Array> - - A promise that resolves to an array of clients that are considered stale.
Throws:

- Error If the login fails or the API response is missing expected values.

| Param | Type | Default | Description |
| ---------------------------- | -------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------- |
| [params] | object | | An optional object containing parameters. |
| [params.groupName] | string | | Group name. Defaults to undefined, which matches all groups. |
| [params.includeRemoved] | boolean | true | Whether or not clients pending deletion should be included. Defaults to true. |
| [params.includeBlank] | boolean | true | Whether or not blank clients should be taken into account when matching clients. Defaults to true. |
| [params.includeFileBackups] | boolean | true | Whether or not file backups should be taken into account when matching clients. Defaults to true. |
| [params.includeImageBackups] | boolean | true | Whether or not image backups should be taken into account when matching clients. Defaults to true. |
| [params.timeThreshold] | number | 1440 | The time threshold (in minutes) for determining if a client is stale. Defaults to 1440 minutes (24 hours). |

Example _(Get clients with file backup older than a day, skip blank clients)_

`js
server
.getStaleClients({
includeBlank: false,
includeImageBackups: false,
timeThreshold: 1440,
})
.then((data) => console.log(data));
`

$3

Adds a new client.

Kind: instance method of UrbackupServer
Returns: Promise.<boolean> - When successful, returns true. If adding the client was not successful, for example if the client already exists, returns false.
Throws:

- Error If the clientName is missing or invalid, if the login fails, or if the API response is missing expected values.

| Param | Type | Description |
| ----------------- | ------------------- | -------------------------------- |
| params | object | An object containing parameters. |
| params.clientName | string | The client's name. |

Example _(Add new client)_

`js
server.addClient({ clientName: 'laptop2' }).then((data) => console.log(data));
`

$3

Marks the client for removal.
Actual removal occurs during the cleanup time window. Until then, this operation can be reversed with the cancelRemoveClient method.
WARNING: Removing clients will also delete all their backups stored on the UrBackup server.

Kind: instance method of UrbackupServer
Returns: Promise.<boolean> - When successful, returns true. Returns false if the removal was not successful.
Throws:

- Error If parameters are missing or invalid.

| Param | Type | Description |
| ----------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| params | object | An object containing parameters. |
| params.clientId | number | Client's ID. If both clientId and clientName are defined, the ID takes precedence. Required if clientName is undefined. |
| params.clientName | string | Client's name. Ignored if both clientId and clientName are defined. Required if clientId is undefined. |

Example _(Remove client by ID)_

`js
server.removeClient({ clientId: 1 }).then((data) => console.log(data));
`

Example _(Remove client by name)_

`js
server
.removeClient({ clientName: 'laptop2' })
.then((data) => console.log(data));
`

$3

Unmarks the client as ready for removal.

Kind: instance method of UrbackupServer
Returns: Promise.<boolean> - When successful, returns true. Returns false if the stopping process was not successful.
Throws:

- Error If parameters are missing or invalid.

| Param | Type | Description |
| ----------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------- |
| params | object | An object containing parameters. |
| params.clientId | number | Client's ID. Takes precedence if both clientId and clientName are defined. Required if clientName is undefined. |
| params.clientName | string | Client's name. Ignored if both clientId and clientName are defined. Required if clientId is undefined. |

Example _(Stop the server from removing a client by ID)_

`js
server.cancelRemoveClient({ clientId: 1 }).then((data) => console.log(data));
`

Example _(Stop the server from removing a client by name)_

`js
server
.cancelRemoveClient({ clientName: 'laptop2' })
.then((data) => console.log(data));
`

$3

Retrieves a list of client discovery hints, which are also known as extra clients.

Kind: instance method of UrbackupServer
Returns: Promise.<Array> - Array of objects representing client hints. Returns an empty array when no matching client hints are found.
Throws:

- Error If the login fails or the API response is incorrect.

Example _(Get extra clients)_

`js
server.getClientHints().then((data) => console.log(data));
`

$3

Adds a new client discovery hint, also known as an extra client.
Discovery hints are a way of improving client discovery in local area networks.

Kind: instance method of UrbackupServer
Returns: Promise.<boolean> - When successful, returns true. Returns false when adding was not successful.
Throws:

- Error If parameters are missing or invalid, or if the API response is incorrect.

| Param | Type | Description |
| -------------- | ------------------- | -------------------------------- |
| params | object | An object containing parameters. |
| params.address | string | Client's IP address or hostname. |

Example _(Add new extra client)_

`js
server
.addClientHint({ address: '192.168.100.200' })
.then((data) => console.log(data));
`

$3

Removes a specific client discovery hint, also known as an extra client.

Kind: instance method of UrbackupServer
Returns: Promise.<boolean> - When successful, returns true. Returns false when removing was not successful.
Throws:

- Error If parameters are missing or invalid, or if the API response is incorrect.

| Param | Type | Description |
| -------------- | ------------------- | -------------------------------- |
| params | object | An object containing parameters. |
| params.address | string | Client's IP address or hostname. |

Example _(Remove extra client)_

`js
server
.removeClientHint({ address: '192.168.100.200' })
.then((data) => console.log(data));
`

$3

Retrieves client settings.
Matches all clients by default, but clientId or clientName can be used to request settings for one particular client.
Clients marked for removal are not excluded from the results.

Kind: instance method of UrbackupServer
Returns: Promise.<Array> - An array with objects representing client settings. Returns an empty array if no matching client is found.
Throws:

- Error If parameters are missing or invalid, or if the API response is incorrect.

| Param | Type | Description |
| ------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [params] | object | An optional object containing parameters. |
| [params.clientId] | number | Client's ID. Takes precedence if both clientId and clientName are defined. Defaults to undefined, which matches all clients if clientName is also undefined. |
| [params.clientName] | string | Client's name. Ignored if both clientId and clientName are defined. Defaults to undefined, which matches all clients if clientId is also undefined. |

Example _(Get settings for all clients)_

`js
server.getClientSettings().then((data) => console.log(data));
`

Example _(Get settings for a specific client only)_

`js
server
.getClientSettings({ clientName: 'laptop1' })
.then((data) => console.log(data));
server.getClientSettings({ clientId: 3 }).then((data) => console.log(data));
`

$3

Changes one specific element of client settings.
A list of settings can be obtained with the getClientSettings method.

Kind: instance method of UrbackupServer
Returns: Promise.<boolean> - When successful, returns true. Returns false when the save request was unsuccessful or if the key/value is invalid.
Throws:

- Error If parameters are missing or invalid, or if the API response is incorrect.

| Param | Type | Description |
| ----------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| params | object | An object containing parameters. |
| params.clientId | number | Client's ID. Takes precedence if both clientId and clientName are defined. Required if clientName is undefined. |
| params.clientName | string | Client's name. Ignored if both clientId and clientName are defined. Required if clientId is undefined. |
| params.key | string | Settings element to change. |
| params.newValue | string \| number \| boolean | New value for settings element. |

Example _(Set directories to backup to be optional by default)_

`js
server
.setClientSettings({
clientName: 'laptop1',
key: 'backup_dirs_optional',
newValue: true,
})
.then((data) => console.log(data));
server
.setClientSettings({
clientId: 3,
key: 'backup_dirs_optional',
newValue: true,
})
.then((data) => console.log(data));
`

$3

Retrieves the group information for a specific client.

Kind: instance method of UrbackupServer
Returns: Promise.<(object\|null)> - A promise that resolves to an object containing the group ID and name, or null if the client or group is not found.
Throws:

- Error If parameters are missing or invalid, if the API response is missing values, or if login fails.

| Param | Type | Description |
| ----------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| params | object | An object containing parameters. |
| params.clientId | number | The client's ID. Takes precedence if both clientId and clientName are defined. Required if clientName is undefined. |
| params.clientName | string | The client's name. Ignored if both clientId and clientName are defined. Required if clientId is undefined. |

Example _(Get client group by client ID)_

`js
server.getClientGroup({ clientId: 1 }).then((data) => console.log(data));
`

Example _(Get client group by client name)_

`js
server
.getClientGroup({ clientName: 'laptop2' })
.then((data) => console.log(data));
`

$3

Sets the group for a specific client.

Kind: instance method of UrbackupServer
Returns: Promise.<boolean> - A promise that resolves to true if the group was successfully set, or false otherwise.
Throws:

- Error If parameters are missing or invalid, or if the API response is incorrect.

| Param | Type | Description |
| ----------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------- |
| params | object | An object containing parameters. |
| params.clientId | number | Client's ID. Takes precedence if both clientId and clientName are defined. Required if clientName is undefined. |
| params.clientName | string | Client's name. Ignored if both clientId and clientName are defined. Required if clientId is undefined. |
| params.groupId | number | Group ID. |

Example _(Set client group by client ID)_

`js
server
.setClientGroup({ clientId: 1, groupId: 123 })
.then((data) => console.log(data));
`

Example _(Set client group by client name)_

`js
server
.setClientGroup({ clientName: 'laptop2', groupId: 123 })
.then((data) => console.log(data));
`

$3

Retrieves the authentication key for a specified client.

Kind: instance method of UrbackupServer
Returns: Promise.<string> - Client's authentication key. Returns an empty string if no matching clients are found.
Throws:

- Error If parameters are missing or invalid, or if the API response is incorrect.

| Param | Type | Description |
| ----------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------- |
| params | object | An object containing parameters. |
| params.clientId | number | Client's ID. Takes precedence if both clientId and clientName are defined. Required if clientName is undefined. |
| params.clientName | string | Client's name. Ignored if both clientId and clientName are defined. Required if clientId is undefined. |

Example _(Get authentication key for a specific client)_

`js
server
.getClientAuthkey({ clientName: 'laptop1' })
.then((data) => console.log(data));
server.getClientAuthkey({ clientId: 3 }).then((data) => console.log(data));
``

$3

Retrieves backup status.
Matches all clients by default, including clients marked for removal.
Client name or client ID can be passed as an