=======

Tuya Connector FE SDK

English | 中文版

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

• login(userName, password[, config]) Log in

• 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: '[email protected]',
  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: '[email protected]',
  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: '[email protected]',
  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: '[email protected]',
}).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.