btsync

BitTorrent Sync - API

BitTorrent Sync - API

NodeJS implementation of BitTorrent Sync API

// long version
var btsync = require('btsync'),
    btsyncInstance = btsync({
        host: 'domain.tld', // (optional) - Hostname or ip of btsync api instance (default: 127.0.0.1)
        port: 9999, // (optional) - Port of btsync api instance (default: 8888)
        username: 'api', // (optional) - Username of btsync api instance (no authentication by default)
        password: 'password' // (optional) - Password of btsync api instance (no password by default)
    });

// or short version
var btsi = require('btsync')({
    host: 'domain.tld',
    port: 9999
});

Returns OS name where BitTorrent Sync is running.

btsi.getOs().then(function(data){
    console.log(data); // { "os": "win32" }
}, function(error){
    console.error(error);
});

Returns BitTorrent Sync version.

btsi.getVersion().then(function(data){
    console.log(data); // { "version": "1.2.48" }
}, function(error){
    console.error(error);
});

Returns current upload and download speed.

btsi.getSpeed().then(function(data){
    console.log(data);
    /*
    {
        "download": 61007,
        "upload": 0
    }
    */
}, function(error){
    console.error(error);
});

Generates read-write, read-only and encryption read-only secrets. If ‘secret’ parameter is specified, will return secrets available for sharing under this secret. The Encryption Secret is new functionality. This is a secret for a read-only peer with encrypted content (the peer can sync files but can not see their content). One example use is if a user wanted to backup files to an untrusted, unsecure, or public location. This is set to disabled by default for all users but included in the API.

btsi.getSecrets({
    'secret': 'RWRWRWRWRWRWRWRWRWRWRWRWRWRWRWRWR', // (required) - must specify folder secret
    'type': 'encrypted' // (optional) - if type=encrypted, generate secret with support of encrypted peer
}).then(function(data){
    console.log(data);
    /*
    {
        "read_only": "ROROROROROROROROROROROROROROROROR",
        "read_write": "RWRWRWRWRWRWRWRWRWRWRWRWRWRWRWRWR",
        "encryption": "EEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEE"
    }
    */
}, function(error){
    console.error(error);
});

Returns BitTorrent Sync preferences. Contains dictionary with advanced preferences. Please see Sync user guide for description of each option.

btsi.getPreferences().then(function(data){
    console.log(data);
    /*
    {
        "device_name": "iMac",
        "disk_low_priority": "true",
        "download_limit": 0,
        "folder_rescan_interval": "600",
        "lan_encrypt_data": "true",
        "lan_use_tcp": "false",
        "lang": -1,
        "listening_port": 11589,
        "max_file_size_diff_for_patching": "1000",
        "max_file_size_for_versioning": "1000",
        "rate_limit_local_peers": "false",
        "send_buf_size": "5",
        "sync_max_time_diff": "600",
        "sync_trash_ttl": "30",
        "upload_limit": 0,
        "use_upnp": 0,
        "recv_buf_size": "5"
    }
    */
}, function(error){
    console.error(error);
});

Sets BitTorrent Sync preferences. Parameters are the same as in ‘Get preferences’. Advanced preferences are set as general settings. Returns current settings.

btsi.setPreferences({
    'device_name': iMac, // (optional)
    'disk_low_priority': true, // (optional)
    'download_limit': 0, // (optional)
    'folder_rescan_interval': 600, // (optional)
    'lan_encrypt_data': true, // (optional)
    'lan_use_tcp': false, // (optional)
    'lang': -1, // (optional)
    'listening_port': 11589, // (optional)
    'max_file_size_diff_for_patching': 1000, // (optional)
    'max_file_size_for_versioning': 1000, // (optional)
    'rate_limit_local_peers': false, // (optional)
    'send_buf_size': 5, // (optional)
    'sync_max_time_diff': 600, // (optional)
    'sync_trash_ttl': 30, // (optional)
    'upload_limit': 0, // (optional)
    'use_upnp': 0, // (optional)
    'recv_buf_size': 5 // (optional)
}).then(function(data){
    console.log(data);
}, function(error){
    console.error(error);
});

Returns an array with folders info. If a secret is specified, will return info about the folder with this secret.

btsi.getFolders({
    'secret': 'RWRWRWRWRWRWRWRWRWRWRWRWRWRWRWRWR' // (optional) - if a secret is specified, will return info about the folder with this secret
}).then(function(data){
    console.log(data);
    /*
    [
        {
            "dir": "\\\\?\\D:\\share",
            "secret": "RWRWRWRWRWRWRWRWRWRWRWRWRWRWRWRWR",
            "size": 23762511569,
            "type": "read_write",
            "files": 3206,
            "error": 0,
            "indexing": 0
        }
    ]
    */
}, function(error){
    console.error(error);
});

Adds a folder to Sync. If a secret is not specified, it will be generated automatically. The folder will have to pre-exist on the disk and Sync will add it into a list of syncing folders. Returns '0' if no errors, error code and error message otherwise.

btsi.addFolder({
    'dir': '/home/whoami/shared', // (required) - specify path to the sync folder
    'secret': 'RWRWRWRWRWRWRWRWRWRWRWRWRWRWRWRWR', // (optional) - specify folder secret
    'selective_sync': false // (optional) - specify sync mode, selective - 1, all files (default) - 0
}).then(function(data){
    console.log(data); // { "error": 0 }
}, function(error){
    console.error(error);
});

Removes folder from Sync while leaving actual folder and files on disk. It will remove a folder from the Sync list of folders and does not touch any files or folders on disk. Returns '0' if no error, '1' if there’s no folder with specified secret.

btsi.removeFolder({
    'secret': 'RWRWRWRWRWRWRWRWRWRWRWRWRWRWRWRWR' // (required) - specify folder secret
}).then(function(data){
    console.log(data); // { "error": 0 }
}, function(error){
    console.error(error);
});

Returns preferences for the specified sync folder.

btsi.getFolderPreferences({
    'secret': 'RWRWRWRWRWRWRWRWRWRWRWRWRWRWRWRWR' // (required) - must specify folder secret
}).then(function(data){
    console.log(data);
    /*
    {
        "search_lan":1,
        "use_dht":0,
        "use_hosts":0,
        "use_relay_server":1,
        "use_sync_trash":1,
        "use_tracker":1
    }
    */
}, function(error){
    console.error(error);
});

Sets preferences for the specified sync folder. Parameters are the same as in ‘Get folder preferences’. Returns current settings.

btsi.setFolderPreferences({
    'secret': 'RWRWRWRWRWRWRWRWRWRWRWRWRWRWRWRWR', // (required) - must specify folder secret
    'search_lan': 1, // (optional)
    'use_dht': 0, // (optional)
    'use_hosts': 0, // (optional)
    'use_relay_server': 1, // (optional)
    'use_sync_trash': 1, // (optional)
    'use_tracker': 1 // (optional)
}).then(function(data){
    console.log(data);
}, function(error){
    console.error(error);
});

Returns list of predefined hosts for the folder, or error code if a secret is not specified.

btsi.getFolderHosts({
    'secret': 'RWRWRWRWRWRWRWRWRWRWRWRWRWRWRWRWR' // (required) - must specify folder secret
}).then(function(data){
    console.log(data);
}, function(error){
    console.error(error);
});

Sets one or several predefined hosts for the specified sync folder. Existing list of hosts will be replaced. Hosts should be added as values of the ‘host’ parameter and separated by commas. Returns current hosts if set successfully, error code otherwise.

btsi.setFolderHosts({
    'secret': 'RWRWRWRWRWRWRWRWRWRWRWRWRWRWRWRWR', // (required) - must specify folder secret
    'hosts': 'domain.tld:1234' // (required) - enter list of hosts separated by comma. Host should be represented as “[address]:[port]”
}).then(function(data){
    console.log(data);
}, function(error){
    console.error(error);
});

Returns list of peers connected to the specified folder.

btsi.getFolderPeers({
    'secret': 'RWRWRWRWRWRWRWRWRWRWRWRWRWRWRWRWR' // (required) - must specify folder secret
}).then(function(data){
    console.log(data);
    /*
    [
        {
            "id": "ARRdk5XANMb7RmQqEDfEZE-k5aI=",
            "connection": "direct", // direct or relay
            "name": "GT-I9500",
            "synced": 0, // timestamp when last sync completed
            "download": 0,
            "upload": 22455367417
        }
    ]
    */
}, function(error){
    console.error(error);
});

Returns list of files within the specified directory. If a directory is not specified, will return list of files and folders within the root folder. Note that the Selective Sync function is only available in the API at this time.

btsi.getFiles({
    'secret': 'RWRWRWRWRWRWRWRWRWRWRWRWRWRWRWRWR', // (required) - must specify folder secret
    'path': '/' // (optional) - specify path to a subfolder of the sync folder.
}).then(function(data){
    console.log(data);
    /*
    [
        {
            "name": "images",
            "state": "created",
            "type": "folder"
        },
        {
            "have_pieces": 1,
            "name": "index.html",
            "size": 2726,
            "state": "created",
            "total_pieces": 1,
            "type": "file",
            "download": 1 // only for selective sync folders
        }
    ]
    */
}, function(error){
    console.error(error);
});

Selects file for download for selective sync folders. Returns file information with applied preferences.

btsi.setFilePreferences({
    'secret': 'RWRWRWRWRWRWRWRWRWRWRWRWRWRWRWRWR', // (required) - must specify folder secret
    'path': '/folder/file.jpg', // (required) - specify path to a subfolder of the sync folder.
    'download': 1 // (required) - specify if file should be downloaded (yes - 1, no - 0)
}).then(function(data){
    console.log(data);
}, function(error){
    console.error(error);
});

Gracefully stops Sync.

btsi.shutdown().then(function(data){
    console.log(data); // { "error": 0 }
}, function(error){
    console.error(error);
});