=======
Tuya Connector FE SDK
Contents
- Overview
- Compatible browsers
- Installation
- Examples
- Features
- Methods
- Error handling
- Configure requests
- Test cases
Overview
Tuya Connector FE SDK encapsulates APIs in JavaScript that allow the Tuya SaaS Admin to manage data.
Currently, it provides APIs related to account login and logout
, password change
, asset management
, and device management
.
For more information about the image of the demo project,visit https://hub.docker.com/r/iotportal/iot-suite.
Compatible browsers
Latest |
Latest |
Latest |
Latest |
Latest |
11 |
Installation
npm install @tuya/connector
or
yarn add @tuya/connector
Examples
import {version, apiService} from '@tuya/connector'
// Current SDK version number.
console.log(version);
const {multiLogin} = apiService;
multiLogin({
userName: 'test',
pwd: '123123a',
}).then((res) => {
if (res) {
// Login is successful.
console.log('logged in');
} else {
console.error('fail to login');
}
}).catch((err) => {
// Failed to log in.
console.error('login fail', err);
})
If a specific domain or port is required, you can initialize the relevant configuration before use.
import {configMethod} from '@tuya/connector'
const {initGlobalConfig, getGlobalConfig, setGlobalConfig} = configMethod;
// Called when the project is initialized. Global initialization is required only once.
// For specific configurations, see Request Config.
initGlobalConfig({
baseURL: '',
method: 'GET',
onError: () => {}, // Global error callback.
})
// Returns the currently changed configuration. The default configuration of Request Config will not be carried.
getGlobalConfig()
// The specific configuration is the same as initGlobalConfig, and the underlying layer of initGlobalConfig is implemented using setGlobalConfig.
setGlobalConfig({})
Features
-
multiLogin(loginParams[, config]) Log in with an email or phone number
-
logout() Log out
-
resetPassword(userName, currentPwd, newPwd[, config]) Change the password
-
forgetPassword(params[, config]) Reset the password
-
getVerifyCode(params[, config]) Get a verification code
-
addAsset(assetName[, parentAssetId)[, config]] Add an asset
-
editAsset(assetId, assetName[, config]) Edit a specified asset
-
removeAsset(assetId[, config]) Remove a specified asset
-
getChildrenAssetsByAssetId(assetId[, config]) Get the list of assets by asset ID
-
searchAssetByName(assetName[, config]) Perform a fuzzy search for assets
-
getEntireTree([config]) Get a specified asset tree (with device information)
-
getSubTree(assetId[, config]) Get the subtree of the specified asset
-
getDevicesInfoByAssetId(assetId, pageNum, pageSize[, config]) Get device information under the specified asset
-
getDeviceInfoByDeviceId(deviceId[, config]) Get device information
-
removeDeviceById(deviceId[, config]) Remove a device
-
modifyDeviceInfo(deviceId, name[,config]) Modify a device
-
modifyDeviceDP(deviceId, deviceStatuses[, config]) Control a device
-
getDeviceDP(deviceId[,config]) Get a device control command
-
getDeviceInfoWithDP(deviceId[, config]) Get device information and data point (DP)
-
getProjectInfo([config]) Get the QR code to bind a device
-
getAccountList(params[, config]) Get the list of users
-
getPermissionListByAccount(uid[, config]) Get the list of user permissions
-
addAccount(params[, config]) Add a user
-
batchRemoveAccount(userIds[, config]) Delete multiple users
-
removeAccount(userId[, config]) Delete a user
-
editAccountPwd(userName, newPwd[, config]) Modify the password
-
batchModifyUserRole(userIds, roleCode[, config]) Modify multiple passwords
-
modifyUserRole(userId, roleCode[, config]) Modify a single user role
-
getEntireAssetTree([config]) Get the entire asset tree (without the information about device quantity)
-
getUserAssetPermissionTree(userId) Get the list of a user's available assets
-
grantUserAssetPermission(userId, assetIds[, config]) Modify a user's asset authorization
-
getRoleList(pageNo, pageSize, opts) Get the list of roles on pages
-
getEntireRoles() Get all roles
-
addRole(params[, config]) Add a role
-
removeRole(roleCode[, config]) Remove a role
-
editRoleName(params[, config]) Edit a role name
-
grantPermissionByRole(params[, config]) Modify the permissions of a specified role
-
getRolePermissionDetail(roleCode[, config]) Get the permission list of a specified role
-
getRolePermissionTemplate(roleCode[, config]) Get the template of role permissions
Methods
login
Log in with an email address.
type UserToken = {
nick_name: string, // Username.
token: string,
role_type: string[], // Role type.
userId: string;
}
/**
* @param username: string
* @param pwd: string
*/
login('test', 'test').then((<UserToken>res) => {
// Returns UserToken on success.
console.log(res)
})
multiLogin
Log in with an email address or mobile phone number.
interface loginParams {
userName?: string,
pwd: string,
countryCode?: string,
phoneNum?: string,
}
// Log in with an email address.
multiLogin({
userName: 'xxx@email.com',
pwd: 'test',
}).then((<UserToken>res) => {
// Returns UserToken on success.
console.log(res)
});
// Log in with a mobile phone number.
multiLogin({
countryCode: '86',
phoneNum: '13000000000',
pwd: 'test',
}).then((<UserToken>res) => {
// Returns UserToken on success.
console.log(res)
})
logout
Log out of the current account.
logout().then(() => {
// The login status in the server has been cleaned up, and you must maintain the local status.
console.log('logout success');
});
resetPassword
Change the password.
/**
* @param username
* @param oldPwd
* @param newPwd
*/
resetPassword('test', '123', '321').then((res) => {
// Boolean type. It indicates whether the operation is successful.
console.log(res);
})
resetPassword('test', '123', '321', {
baseURL: 'http://localhost:8000',
method: 'POST'
}).then((res) => {
// Boolean type. It indicates whether the operation is successful.
console.log(res);
})
forgetPassword
Reset the password.
interface forgetPwdParams {
code: string;
newPassword: string;
}
interface emailForgetPwdParams extends forgetPwdParams {
mail: string;
}
interface phoneForgetPwdParams extends forgetPwdParams {
countryCode: string;
phone: string;
}
const params1 = {
countryCode: '86',
phone: '13100001111',
code: '123456',
newPassword: 'abcdefg123',
} : phoneForgetPwdParams;
forgetPassword(params1).then((res) => {
console.log(<boolean>res);
});
const params1 = {
mail: 'xx@tuya.com',
code: '123456',
newPassword: 'abcdefg123',
} : emailForgetPwdParams;
forgetPassword(params1).then((res) => {
console.log(<boolean>res);
});
getVerifyCode
Get a verification code.
interface verifyCodeParamsPhone {
language: string,
countryCode: string,
phone: string,
}
interface verifyCodeParamsEmail {
mail: string,
language: string,
}
const params1 = {
countryCode: '86',
phone: '13100001111',
language: 'zh-CN',
}: verifyCodeParamsPhone;
getVerifyCode(params1).then((res) => {
console.log(<boolean>res);
});
const params2 = {
mail: 'xx@tuya.com',
language: 'en-US',
}: verifyCodeParamsEmail;
getVerifyCode(params2).then((res) => {
console.log(<boolean>res);
});
getChildrenAssetsByAssetId
Get the list of first-level sub-assets.
type Asset = {
asset_id: string;
asset_name: string;
full_asset_name: string;
};
/**
* @param assetId: string
*/
getChildrenAssetsByAssetId('1').then((res) => {
console.log(<Asset[]>res);
})
searchAssetByName
Search for an asset.
/**
* @param assetName: string
*/
searchAssetByName('test').then((res) => {
console.log(<Asset[]>res);
})
addAsset
Add an asset.
/**
* @param assetName: string,
* @param parentAssetId: string = "",
*/
addAsset('newAsset', '1').then((res) => {
// The ID of the new asset.
console.log(<string>res)
})
editAsset
Edit the asset name.
type errorType = {
apiMethodName: string;
msg: string;
code: number;
httpCode: string;
}
/**
* @param assetId: string,
* @param assetName: string,
*/
editAsset('assetId', 'assetName').then((res) => {
// Edited the asset name successfully.
console.log(<boolean>res)
}).catch((err) => {
// Failure reason.
console.error(<errorType>err)
})
removeAsset
Remove an asset.
type errorType = {
apiMethodName: string;
msg: string;
code: number;
httpCode: string;
}
/**
* @param assetId: string,
*/
removeAsset('assetId').then((res) => {
// Deleted the asset successfully.
console.log(<boolean>res)
}).catch((err) => {
// Failure reason.
console.error(<errorType>err)
})
getEntireTree
Get the entire asset tree.
type BaseAsset = {
asset_id: string;
asset_name: string;
full_asset_name: string;
};
type Asset = BaseAsset & {
child_asset_count: number;
child_device_count: number;
};
type AssetDeep = Asset & {
subAssets: AssetDeep[];
};
getEntireTree().then((res) => {
// Got the asset tree successfully.
console.log(<AssetDeep>res);
})
getSubTree
Get the asset subtree.
/**
* @param assetId: string,
*/
getSubTree('1').then((res) => {
// Get the asset subtree of which the asset ID is `1`.
console.log(<AssetDeep>res);
});
getDevicesInfoByAssetId
type DeviceStatus = {
code: string; // Status name
value: Object; // Status value
options?: string; // DP value configuration
editable?: boolean; // Indicates whether it is editable
name?: string; // DP name
type?: string; // DP type
};
type DeviceInfo = {
id: string; // Device number
name: string; // Device name
uid: string; // User ID
local_key: string; // Key
category: string; // Product category
product_id: string; // Product ID
product_name: string; // Product name
sub: boolean; // Indicates whether a sub-device is used
uuid: string; // The universally unique identifier of a device
online: boolean; // The online status of a device
active_time: number; // The timestamp when a device is activated, in seconds
icon: string; // The icon of a device
ip: string; // The IP address of a device
create_time: number; // The timestamp when a device is created, in seconds
update_time: number; // The timestamp when a device is updated, in seconds
time_zone: string; // Time zone, for example, `+08:00`
status: DeviceStatus[];
}
/**
* @param assetId: string,
* @param pageNum: number,
* @param pageSize: number,
*/
getDevicesInfoByAssetId('1', 1, 20).then((res) => {
console.log(<DeviceInfo[]>res);
})
getDeviceInfoByDeviceId
type DeviceInfo = {
id: string; // Device number
name: string; // Device name
uid: string; // User ID
local_key: string; // Key
category: string; // Product category
product_id: string; // Product ID
product_name: string; // Product name
sub: boolean; // Indicates whether a sub-device is used
uuid: string; // The universally unique identifier of a device
online: boolean; // The online status of a device
active_time: number; // The timestamp when a device is activated, in seconds
icon: string; // The icon of a device
ip: string; // The IP address of a device
create_time: number; // The timestamp when a device is created, in seconds
update_time: number; // The timestamp when a device is updated, in seconds
time_zone: string; // Time zone, for example, `+08:00`
status: DeviceStatus[];
}
/**
* @param deviceId: string,
*/
getDeviceInfoByDeviceId('1').then((res) => {
console.log(<DeviceInfo>res)
})
removeDeviceById
Remove a device.
/**
* @param deviceId: string,
*/
removeDeviceById('12').then((res) => {
console.log(<boolean>res);
})
modifyDeviceInfo
Modify the information about a device.
/**
* @param deviceId: string,
* @param devicename: string,
*/
modifyDeviceInfo('12', 'devicename').then((res) => {
console.log(<boolean>res);
})
modifyDeviceDP
Control a device.
For more information about standard instruction sets, see the official website.
type DeviceStatus = {
code: string; // Status name
value: Object; // Status value
options?: string; // DP value configuration
editable?: boolean; // Indicates whether it is editable
name?: string; // DP name
type?: string; // DP type
};
/**
* @param deviceId: string,
* @param deviceStatuses: DeviceStatus[],
*/
modifyDeviceDP('12', [{code: '', value: 2}]).then((res) => {
console.log(<boolean>res);
})
getDeviceDP
Get the instructions.
For more information about standard instruction sets, see the official website.
/**
* @param deviceId: string,
*/
getDeviceDP('12').then((res) => {
console.log(res)
})
getDeviceInfoWithDP
Get the device information and DP.
This method is the aggregation result of getDeviceDP
and getDeviceInfoByDeviceId
. Specify the DP in the status
field of deviceInfo
.
/**
* @param deviceId: string,
*/
getDeviceInfoWithDP('deviceId1').then((res) => {
console.log(<DeviceInfo>res);
})
// Sample
{
id: 'deviceId1',
name: 'deviceId1',
uid: 'uid1',
local_key: 'local_key',
category: 'category',
product_id: 'product_id',
product_name: 'product_name',
sub: true,
uuid: 'uuid',
online: true,
active_time: 1615175477,
icon: 'icon',
ip: '127.0.0.1',
create_time: 1615175477,
update_time: 1615175477,
time_zone: '+08:00',
status: [
{
code: "va_temperature",
value: 243,
editable: false,
type: "Integer",
options: "{\"unit\":\"℃\",\"min\":-399,\"max\":800,\"scale\":1,\"step\":1}",
name: '',
},
{
code: "va_humidity",
value: 55,
editable: false,
type: "Integer",
options: "{\"unit\":\"%\",\"min\":0,\"max\":100,\"scale\":0,\"step\":1}",
name: '',
},
{
code: "battery_percentage",
value: 40,
name: '',
editable: false,
type: "Integer",
options: "{\"unit\":\"%\",\"min\":0,\"max\":100,\"scale\":0,\"step\":1}",
},
{
code: "charge_state",
value: false,
editable: false,
type: "Boolean",
options: "{}",
name: '',
},
{
code: "temp_unit_convert",
value: "c",
editable: true,
name: "Temperature unit conversion",
type: "Enum",
options: "{\"range\":[\"c\",\"f\"]}",
},
{
code: "maxtemp_set",
value: 535,
editable: true,
name: "Maximum temperature",
type: "Integer",
options: "{\"unit\":\"℃\",\"min\":-399,\"max\":800,\"scale\":1,\"step\":1}",
},
{
code: "minitemp_set",
value: 0,
editable: true,
name: "Minimum temperature",
type: "Integer",
options: "{\"unit\":\"℃\",\"min\":-399,\"max\":800,\"scale\":1,\"step\":1}",
},
{
code: "maxhum_set",
value: 95,
editable: true,
name: "Maximum humidity",
type: "Integer",
options: "{\"unit\":\"%\",\"min\":0,\"max\":100,\"scale\":0,\"step\":1}"
},
{
code: "minihum_set",
value: 10,
name: "Minimum humidity",
editable: true,
type: "Integer",
options: "{\"unit\":\"%\",\"min\":0,\"max\":100,\"scale\":0,\"step\":1}"
},
{
code: "temp_alarm",
value: "upperalarm",
type: "Enum",
editable: false,
options: "{\"range\":[\"loweralarm\",\"upperalarm\",\"cancel\"]}",
name: '',
},
{
code: "hum_alarm",
value: "cancel",
type: "Enum",
editable: false,
options: "{\"range\":[\"loweralarm\",\"upperalarm\",\"cancel\"]}",
name: '',
}
]
}
getProjectInfo
Get the QR code to bind a device.
type ProjectInfo = {
project_name: string;
project_code: string;
};
getProjectInfo().then((res) => {
// Got the QR code successfully.
console.log(<ProjectInfo>res);
})
getAccountList
Get the list of accounts.
interface user {
userId: string;
nickName: string;
userName: string; // The login account
createTime: string;
roles: role[];
}
interface getAccountListParams {
searchKey: string;
roleCode: string;
pageNo: number;
pageSize: number;
}
interface userListResp {
total: number;
pageNo: number;
pageSize: number;
data: user[];
}
getAccountList({
searchKey: '',
roleCode: '',
pageNo: 1,
pageSize: 20,
}).then((res) => {
return <userListResp>res;
})
getPermissionListByAccount
Get the list of permissions granted to the account.
getPermissionListByAccount('uid').then((res) => {
return <permission[]>res;
})
addAccount
Add an account.
interface addAccountParams {
password: string;
nickName?: string;
roleCodes: string[];
userName: string,
countryCode?: string,
}
addAccount({
password: '123123A',
roleCodes: ['manager-1000'],
userName: 'xxx@tuya.com',
}).then((res) => {
return <boolean>res;
})
batchRemoveAccount
Delete multiple accounts in a call.
batchRemoveAccount(['userId1', 'userId2']).then((res) => {
return <boolean>res;
})
removeAccount
Delete an account.
removeAccount('userID').then((res) => {
return <boolean>res;
})
editAccountPwd
Change the account password.
editAccountPwd('userName', '123456A').then((res) => {
return <boolean>res;
})
batchModifyUserRole
Modify multiple account roles.
batchModifyUserRole(['userId1', 'userId2'], 'manager-1000').then((res) => {
return <boolean>res;
})
modifyUserRole
Modify an account role.
modifyUserRole('userId', 'manager-1000').then((res) => {
return <boolean>res;
});
getEntireAssetTree
Get the entire asset tree (without the information about device quantity).
type PermissionAsset = Omit<Asset, 'child_device_count'>;
type PermissionAssetTree = PermissionAsset & {
subAssets: PermissionAssetTree[];
};
getEntireAssetTree().then((res) => {
return <PermissionAsset[]>res;
});
getUserAssetPermissionTree
Get the list of user assets.
getUserAssetPermissionTree('userId').then((res) => {
return <PermissionAsset[]>res;
});
grantUserAssetPermission
Modify the list of user assets.
grantUserAssetPermission('userId', ['1', '2']).then((res) => {
return <boolean>res;
});
getRoleList
Get the list of roles.
interface role {
roleCode: string;
roleName: string;
}
interface paginationType {
total: number;
pageNo: number;
pageSize: number;
};
interface roleListResp extends paginationType {
data: role[],
}
getRoleList(1, 20).then((res) => {
return <roleListResp>res;
})
getEntireRoles
Get all roles.
getEntireRoles().then((res) => {
return <role[]>res;
})
addRole
Add a role.
enum RoleType {
manager = 'manager',
normal = 'normal',
}
interface addRoleParams {
roleName: string;
roleType: RoleType;
roleRemark?: string; // Role description
}
addRole({
roleName: 'roleName',
roleType: 'normal',
}).then((res) => {
return <boolean>res;
})
removeRole
Delete a role.
removeRole('roleCode').then((res) => {
return <boolean>res;
})
editRoleName
Modify a role name.
interface editRoleNameParams {
roleCode: string,
roleName: string,
roleRemark?: string,
}
editRoleName({
roleCode: 'normal-xxx',
roleName: '321',
}).then((res) => {
return <boolean>res;
})
grantPermissionByRole
Modify the list of permissions granted to a role.
interface grantPermissionByRoleParams {
roleCode: string;
permissionCodes: string[];
}
grantPermissionByRole({
roleCode: 'normal-xxxxx',
permissionCodes: ['1000', '2000'],
}).then((res) => {
return <boolean>res;
})
getRolePermissionDetail
Get the list of permissions granted to a role.
enum PermissionType {
menu = 'menu',
api = 'api',
button = 'button',
data = 'data',
};
interface permission {
permissionCode: string;
permissionName: string;
permissionType: PermissionType;
parentCode: string;
order: string;
remark: string;
authorizable: boolean;
}
getRolePermissionDetail('manager-1000').then((res) => {
return <permission[]>res;
})
getRolePermissionTemplate
Get the template of role permissions.
getRolePermissionTemplate('manager').then((res) => {
return <permission[]>res;
})
Error handling
If an HTTP error occurs, apiService
will get the error. You can use promise catch
to get the error message.
apiService.getDeviceInfoByDeviceId('1').catch(({msg, code}) => {
console.error(msg);
})
Alternatively, you can register the global error handling methods in initConfig
.
type ApiError = {
httpCode: number, // HTTP code
code: number,
msg: string,
apiMethodName: string, // The API method name
}
initConfig({
onError: (<ApiError>errorObj) => {}
})
Configure requests
For more information about request configuration, see Axios request config.
Test cases
As a preparation, start the mock server.
Listen on port 7001 by default.
npm run testServer
Start the unit test.
npm run jest
License
For more information about the license, see MIT License.