raysync-sdk

Raysync SDK for JavaScript

$3

1. please see windows or linux server deployment manual, deploy your raysync server.
2. go to raysync admin website,create a new account.
3. install SDK using npm

``
npm install raysync-sdk --save
`

4. After installed raysync client,you can connect client by use Client instance

`js
import { Client, ClientResponse } from 'raysync-sdk'

const client = new Client({ server_ip: 'your raysync server ip' })
client.login({ username: 'Your raysync account', password: 'Your raysync password' })
// After login successful, you can use most of the functionalities of raysync client
// Some examples:
client.on(ClientResponse.LIST, (response) => {
console.log(response)
})
client.list('/')
`

5. If you don't want to install and start the raysync client,you can connect raysync file server by use FileServer instance

`js
import { FileServer, ServerResponse } from 'raysync-sdk'
const RAYSYNC_SERVER_IP = '127.0.0.1'
const server = new FileServer({ url: ws://${RAYSYNC_SERVER_IP}:2480 })
server.login({ username: 'Your raysync account', password: 'Your raysync password' })
// After login successful, you can use most of the functionalities of raysync server
// Some examples:
server.on(ServerResponse.LOGIN, (response) => {
console.log(response)
server.list('/')
})
server.on(ServerResponse.LIST, (response) => {
console.log(response)
})
`

$3

- Create A Client Instance
- Client Options
- Client Operations
- .login(userInfo)
- [.list(path [, groudId])](#client-list)
- [.download(files [,options])](#client-download)
- [.upload(path [,options])](#client-upload)
- .getTaskStatus(taskId)
- .getAllTaskStatus()
- .getTaskDetailInfo(taskId)
- [.mkdir(name [,path])](#client-mkdir)
- .rename(oldName,newName)
- [.copy(from,to [,cover])](#client-copy)
- [.move(from,to [,cover])](#client-move)
- .remove(files)
- .getAttributes(path)
- .getGroupList()
- .upgrade(version)
- .setLanguage(language)
- .setGroupId(groudId)
- .setSpaceId(spaceId)
- [.showSyncFolder(path [,options])](#client-show-sync-folder)
- .onConnect(connected)
- .close()
- .closeFileDialog()
- Listen for changes in the transfer task state
- Create A File Server Instance
- File Server Operations
- .login(userInfo)
- [.list(path [, groudId])](#server-list)
- .download(files)
- .httpDownload(path)
- .upload(path)
- [.mkdir(name [,path])](#server-mkdir)
- .rename(oldName,newName)
- .getFileInfo(path)
- [.copy(from,to [,cover])](#server-copy)
- [.move(from,to [,cover])](#server-move)
- [.remove({path,names}[])](#server-remove)
- .setGroupId(groudId)
- .setSpaceId(spaceId)
- .getAttributes(path)
- .close()
- Event Methods
- .on(command,handler)
- .once(command,handler)
- .off(command,handler)

Create A Client Instance

Client Instance options

options:

- [clientSign] {String} default is Raysync, Client sign value, if you use a customized raysync client, please provide it
- [language] {String} client language, default is en-US (optional: zh-CN,en-US)
- [protocol_version] {String} currently raysync server version
- [client_version] {String} currently client version
- [server_ip] {String} your raysync server ip, default is the host of the browser url
- [server_port] your raysync server port, default is 8090
- [proxy_ip] {String} raysync server proxy ip ,default is null
- [proxy_port] {Number} raysync server proxy port ,default is 32001
- [server5_port] {Number} file transmission port,default is 2442
- [server5_ssl_port] {Number} file transmission encryption port,default is 2443
- [space_id] currently space id , default is 1
- [tcpEnable] {Number} default is 0, select TCP/UDP transmission protocol. Options: 0 for automatic selection, 1 for priority UDP with automatic TCP fallback, 2 for only TCP, and 3 for only UDP.
- [tcpDelay] {Number} default is 10,Raysync supports both UDP and TCP transmissions. When Raysync client and Raysync server latency is less than tcpDelay, Raysync client automatically selects TCP for transmission; when the latency is greater than tcpDelay, Raysync client automatically selects UDP for transmission.
- [autoUpdateSwitch] {Boolean} default true, whether to automatically upgrade the raysync client

example:

1. basic usage

`js
import { Client, ClientResponse } from 'raysync-sdk'

const client = new Client({ server_ip: 'your raysync server ip' })
`

2. use custom options

`js
import { Client, ClientResponse } from 'raysync-sdk'

const client = new Client({
clientSign: 'your customized client sign',
server_ip: 'your raysync service ip',
server_port: 8090,
proxy_ip: 'your raysync service ip',
proxy_port: 32001,
server5_port: 2442,
server5_ssl_port: 2443,
tcpEnable: 1,
tcpDelay: 10,
autoUpdateSwitch: true,
language: 'en-US',
recv_state: false, // Whether to listen for task state changes
})
`

Client Operations

.login(userInfo)

- [username] {String} your raysync account.
- [password] {String} your raysync password.
- [spaceId] {Number} space id.
- [uk] {String} your custom token.
- [authWay] {Number} authentication method. Default is 1. Possible values:
- 1: RaySync (default)
- 2: Ldap
- 4: Email
- 8: System
- 16: External Http
- 32: Wechat
- 64: Oidc
- 128: Http
- 256: Oauth

example:

1. use raysync authentication service

`js
client.login({ username: 'your raysync account', password: 'your raysync password' })
`

2. use custom authentication service,detail see

`js
client.login({ uk: 'your custom token', authWay: 16 })
`

3. use System authentication

`js
client.login({ username: 'your system account', password: 'your system password', authWay: 8 })
`

.list(path [, groudId])

Get file list from the raysync client
parameters:

- path {String} list path, default is '/'
- [groudId] {Number} currently groud id, default is 0

Success will return list response info, including:

- path {String} list path
- list {Array} file list info:
- [name] {String} file name
- [size] {Number} file size
- [time] {Number} file modified time
- [file_type] {Number} file type (0:file,1:folder,2:virtual directory)
example:

`js
client.on(ClientResponse.LIST, (response) => {
console.log(response)
})
client.list('/')
`

.download(files [,options])

`js
client.download([{ path: '/', names: ['1.txt', '2.txt'] }])
`

.upload(path [,options])

Use the raysync client to upload files

parameters:

- path {String} upload path
- options {Object}
- regexExp?: {String} A regular expression to filter files with matching filenames for upload.
- taskName?: {String} The task name for the current transfer task.
- type?: {Number} {0:no restriction,1: folders only, 5: files only}
- isFullPath?: {Boolean} Whether to use the full path

example:

`js
client.upload('/')
`

.getTaskStatus(taskId)

`js
client.on(ClientResponse.GET_TASK_STATUS, (res) => {
console.log(res)
})
client.on(ClientResponse.UPLOAD, (response) => client.getTaskStatus(response.task_id))
client.on(ClientResponse.DOWNLOAD, (response) => client.getTaskStatus(response.task_id))
client.on(ClientResponse.SYNC, (response) => client.getTaskStatus(response.task_id))
`

.getAllTaskStatus()

`js
client.on(ClientResponse.GET_ALL_TASK_STATUS, (res) => {
console.log(res)
})
client.getAllTaskStatus()
`

.getTaskDetailInfo(taskId)

`js
client.on(ClientResponse.GET_TASK_INFO, (res) => {
console.log(res)
})
client.on(ClientResponse.UPLOAD, (response) => client.getTaskDetailInfo(response.task_id))
client.on(ClientResponse.DOWNLOAD, (response) => client.getTaskDetailInfo(response.task_id))
client.on(ClientResponse.SYNC, (response) => client.getTaskDetailInfo(response.task_id))
`

.mkdir(name [,path])

Create a new directory
parameters:

- name {String} directory name
- [path] {String} directory path, default is '/'

Success will return mkdir response info, including:

- result {Number} response code
- message {Number} response message
- success {Boolean} this operation is successful or not

example:

`js
client.on(ClientResponse.MKDIR, (response) => {
console.log(response)
})
client.mkdir('test', '/')
`

.rename(oldName,newName)

parameters:

- oldName {String} old file name
- newName {String} new file name

Success will return rename response info, including:

- result {Number} response code
- message {Number} response message
- is_end {Boolean} this operation is completed or not
- failed_count {Number} count of failed files
- file_count {Number} count of files

example:

`js
client.on(ClientResponse.RENAME, (response) => {
console.log(response)
})
client.rename('/old.txt', '/new.txt')
`

.copy(from,to [,cover])

- from {Array} list of files that need to be copied
- to {Array} list of target directory
- [cover] {Boolean} default false, whether the file is overwritten when the target directory exists, the default is not overwritten and the value is false, or else, is the opposite.

Success will return copy response info, including:

- result {Number} response code
- message {Number} response message
- is_end {Boolean} this operation is completed or not
- failed_count {Number} count of failed files
- file_count {Number} count of files

example:

`js
client.on(ClientResponse.COPY, (response) => {
console.log(response)
})
client.copy(['/old/1.txt', '/old/2.txt'], ['/new/1.txt', '/new/2.txt'], true)
`

.move(from,to [,cover])

parameters:

- from {Array} list of files that need to be moved
- to {Array} list of target directory
- [cover] {Boolean} default false, whether the file is overwritten when the target directory exists, the default is not overwritten and the value is false, or else, is the opposite.

Success will return move response info, including:

- result {Number} response code
- message {Number} response message
- is_end {Boolean} this operation is completed or not
- failed_count {Number} count of failed files
- file_count {Number} count of files

example:

`js
client.on(ClientResponse.MOVE, (response) => {
console.log(response)
})
client.move(['/old/1.txt', '/old/2.txt'], ['/new/1.txt', '/new/2.txt'], true)
`

.remove(files)

parameters:

- files {Object}
- path {string} file path
- names {Array} list of file name

Success will return remove response info, including:

- result {Number} response code
- message {Number} response message
- is_end {Boolean} this operation is completed or not
- failed_count {Number} count of failed files
- file_count {Number} count of files

example:

`js
client.on(ClientResponse.REMOVE, (response) => {
console.log(response)
})
client.remove({ path: '/', names: ['1.txt', '2.txt'] })
`

.getAttributes(path)

get folder attributes

parameters:

- path {String} folder path

Success will return get attributes response info, including:

- result {Number} response code
- message {Number} response message
- is_end {Boolean} this operation is completed or not
- folder_count {Number} count of folders
- file_count {Number} count of files
- file_size {Number} file size
- write_time {Number} last modified time

example:

`js
client.on(ClientResponse.GET_ATTRIBUTES, (response) => {
console.log(response)
})
client.getAttributes('/folder')
`

.getGroupList()

`js
client.getGroupList()
`

.upgrade(version)

when the server returns a higher version than that of the local raysync client,you can upgrade your raysync client by use this method

parameters:

- version {String} version of client that need to be upgraded

example:

`js
client.on(ClientResponse.UPDATE_CLIENT, (response) => {
console.log(response)
client.upgrade('6.0.0.8')
})
`

.setLanguage(language)

set current language of the raysync client

parameters:

- language {String} client language, default is en-US (optional: zh-CN,en-US)

example:

`js
client.setLanguage('en-US')
`

.setGroupId(groudId)

set current group id
parameters:

- groudId {Number} default is 0

example:

`js
client.setGroupId(1)
`

.setSpaceId(spaceId)

set current space id
parameters:

- spaceId {Number} default is 1

example:

`js
client.setGroupId(1)
`

.showSyncFolder(path [,forbid_sync_delete,regexExp])

open the client sync-folder window

parameters:

- path {String} target path of the sync-folder
- options {Object}
- [forbidSyncDelete] {Boolean} default false, hide the delete button of sync-folder or not.
- [regexExp]: {String} A regular expression to filter files with matching filenames.
- [showTaskName] {String}: The display name of the task.
- [serverPath] {String}: The server path.
- [transferTaskType] {Number}: Default is 0 (unknown). Possible values are 1 (upload), 2 (download), and 3 (sync).

example:

`js
client.showSyncFolder('/', {
forbidSyncDelete: false,
regexExp: '',
showTaskName: '',
serverPath: '/',
transferTaskType: 1,
})
`

.onConnect(connected)

This event is used to listen whether a connection with the client has been established.

Example:

`js
client.onConnect((connected) => {
if (connected) {
// Actions to perform when connected
}
})
`

.close()

close client connection, off all event listener

.closeFileDialog()

Close the file dialog of the client.

Parameters:

- type (optional): A string indicating the type of the file dialog to close. Default value is 'all', which means close all file dialogs.

Example:

`javascript
// Close all file dialogs
closeFileDialog('all')
`

Listen for changes in the transfer task state

When initializing the client, you can pass recv_state: true to enable receiving changes in the transfer task state.

`js
const client = new Client({
...
recv_state: true,
})
`

.on(ClientResponse.TASK_STATE_CHANGED, callback)
This event is used to listen for changes in the transfer task state.

this response will return task state changed response info, including:

- state {REQUEST_STATE} Task status, with the following meanings:
- STATE_UNKNOWN = 0
- STATE_TODO = 1 // Task is selecting upload/download path or file
- STATE_CONNECTING_PROXY = 2 // Connecting to the proxy server
- STATE_WAIT_NEXT_COMMAND = 3 // Disconnected login info, waiting for the next command to log in again
- STATE_WAIT_LOGIN_INFO = 4 // Waiting for login return before performing operations
- STATE_READY = 5 // Ready, waiting to be executed
- STATE_RECOVER = 6 // Recovering from a client crash
- STATE_STARTED = 7 // Started, running
- STATE_STOPPING = 8 // Stopping
- STATE_STOPPED = 9 // Stopped
- STATE_SUCCESSFUL = 10 // Successful
- STATE_FAILED = 11 // Failed
- STATE_AUTH_FAILED = 12 // Authentication failed, username or password error
- STATE_PROXY_CLOSED = 13 // Proxy connection disconnected or failed
- STATE_IDLE = 14 // Idle state, currently only used for timed tasks
- STATE_STOP_BY_SERVER = 15 // Server stopped transmission
- STATE_NO_PERMISSION = 16 // Insufficient permissions
- STATE_IP_IS_LOCKED = 17 // IP address is locked
- STATE_STOP_BY_PEER = 18 // Peer stopped transmission (P2P task)
- STATE_SEND_FAILED = 19 // Sending failed (P2P task)
- STATE_CONNECT_FAILED = 20 // Connection failed (P2P task)
- STATE_ACCOUNT_IS_LOCKED = 21 // Account is locked
- STATE_SERVER_STOPPED = 22 // Task server stopped
- STATE_LICENSE_EXPIRED = 23 // License expired
- STATE_DISABLED_BY_SERVER = 24 // Server disabled task
- task_id {Number} Task id
- success {Boolean} Whether the operation is successful

.on(ClientResponse.TRANSFER_SUCCESS, callback)
Listen for transfer success event, this response info please see .getTaskDetailInfo()

Example:

`js
const client = new Client({
...
recv_state: true,
})
client.on(ClientResponse.TASK_STATE_CHANGED, (res) => {
console.log('TASK_STATE_CHANGED', res)
})
client.on(ClientResponse.TRANSFER_SUCCESS, (res) => {
console.log('TRANSFER_SUCCESS', res)
})
`

Create A File Server Instance

options

- url {String} raysync file server url,if you uploaded TLS certificate,please provide wss url

example:

1. basic usage

`js
import { FileServer } from 'raysync-sdk'
const RAYSYNC_SERVER_IP = '127.0.0.1'
const server = new FileServer({ url: ws://${RAYSYNC_SERVER_IP}:2480 })
`

2. if you uploaded an HTTPS certificate, please provide the https domain, and the port will be changed to 2481

`js
const RAYSYNC_SERVER_IP = 'demo.raysync.cn'
const server = new FileServer({ url: wss://${RAYSYNC_SERVER_IP}:2481 })
`

File Server Operations

.login(userInfo)

parameters:

userInfo {Object}:

- [username] {String} your raysync account.
- [password] {String} your raysync password.
- [spaceId] {Number} space id.
- [uk] {String} your custom token.
- [authWay] {Number} authentication method. Default is 1. Possible values:
- 1: RaySync (default)
- 2: Ldap
- 4: Email
- 8: System
- 16: External Http
- 32: Wechat
- 64: Oidc
- 128: Http
- 256: Oauth2.0

example:

1. use raysync authentication service

`js
server.login({ username: 'your raysync account', password: 'your raysync password' })
`

2. use custom external http service,detail see

`js
server.login({ uk: 'your custom token', authWay: 16 })
`

3. use System authentication

`js
server.login({ username: 'your system account', password: 'your system password', authWay: 8 })
`

.list(path)

Get file list from the raysync file server
parameters:

- path {String} list path, default is '/'

Success will return list response info, including:

- result {Number} response code
- success {Boolean} this operation is success or not
- data {Array} file list info:
- [name] {String} file name
- [size] {Number} file size
- [time] {Number} file modified time
- [file_type] {Number} file type (0:file,1:folder,2:virtual directory)

example:

`js
server.on(ServerResponse.LIST, (response) => {
console.log(response)
})
server.list('/')
`

.download(path [,reportEvent, downloadId])

download file from the raysync server, only support download file

parameters:

- path {String} file path
- [reportEvent] {Boolean} report download event to raysync server ,default is true
- [downloadId] {Number} download id

example:

`js
server.on(ServerResponse.ON_DOWNLOAD_START, (response) => {
console.log(response)
})
server.on(ServerResponse.ON_DOWNLOADING, (response) => {
console.log(response)
})
server.on(ServerResponse.ON_DOWNLOAD_SUCCESS, (response) => {
console.log(response)
})
server.download('/1.txt')
`

.httpDownload(path)

Download files or folders using http

parameters:

- path {Array} download path list

`js
server.httpDownload(['/test']).then((res) => {
if (res.success) {
window.open(res.data.downloadUrl, '_blank')
}
})
`

.upload(options)

upload file to the raysync server

parameters:

- options {Object}
- file {File} file object instance
- [path] upload path, default is '/'

`js
server.on(ServerResponse.ON_UPLOAD_START, (response) => {
console.log(response)
})
server.on(ServerResponse.ON_UPLOADING, (response) => {
console.log(response)
})
server.on(ServerResponse.ON_UPLOAD_SUCCESS, (response) => {
console.log(response)
})
const file = new File(['1'], '1.txt', {
type: 'text/plain',
})
server.upload({ file, path: '/test' })
`

.mkdir(name [,path])

Create a new directory
parameters:

- name {String} directory name
- [path] {String} directory path, default is '/'

Success will return mkdir response info, including:

- result {Number} response code
- success {Boolean} this operation is successful or not

example:

`js
server.on(ServerResponse.MKDIR, (response) => {
console.log(response)
})
server.mkdir('test', '/')
`

.rename(path,newName)

`js
server.on(ServerResponse.RENAME, (response) => {
console.log(response)
})
server.rename('/test/old.txt', 'new.txt')
`

.getFileInfo(path)

parameters:

- path {String} file path

Success will return file info, including:

- result {Number} response code
- message {Number} response message
- data {Object}
- fileSize {Number} File size
- writeTime {Number} Last modified time

example:

`js
server.on(ServerResponse.GET_SERVER_FILE_INFO, (response) => {
console.log(response)
})
server.getFileInfo('/test/1.txt')
`

.copy(from,to)

`js
server.on(ServerResponse.MOVE_OR_COPY, (response) => {
console.log(response)
})
server.copy('/a/1.txt', '/a/b/1.txt')
`

.move(from,to)

`js
server.on(ServerResponse.MOVE_OR_COPY, (response) => {
console.log(response)
})
server.move('/a/1.txt', '/a/b/1.txt')
`

.remove(path)

remove a single file
parameters:
path {String} file path

Success will return remove response info, including:

- result {Number} response code
- message {Number} response message
- data {Object}
- isEnd {Boolean} this operation is completed or not
- failedCount {Number} count of failed files
- successCount {Number} count of success files

example:

`js
server.on(ServerResponse.REMOVE, (response) => {
console.log(response)
})
server.remove('/1.txt')
`

.setGroupId(groudId)

set current group id
parameters:

- groudId {Number} default is 0

example:

`js
server.setGroupId(1)
`

.setSpaceId(spaceId)

set current space id
parameters:

- spaceId {Number} default is 1

example:

`js
server.setGroupId(1)
`

.getAttributes(path)

`js
server.on(ServerResponse.GET_ATTRIBUTES, (response) => {
console.log(response)
})
server.getAttributes('/folder')
`

.close()

`js
const handler = (res) => console.log(res)
client.on(ClientResponse.LOGIN, handler)
client.once(ClientResponse.LOGIN, handler)
client.off(ClientResponse.LOGIN, handler)
``