@ray-js/api 1.7.69 → 1.7.71

package/lib/cloud/linkage.js

@@ -5,9 +5,31 @@ const _excluded = ["gid", "devId", "sourceEntityId"],
 import { requestCloud } from '../';
 import { THING } from '../constants';
 /**
- * 获取家庭下支持联动的设备列表
- * @param {number} gid 家庭id
- * @param {string} sourceType 业务范围
+ * 查询家庭下支持联动的所有设备
+ * @param params - 查询设备列表参数
+ * @param params.gid 家庭 ID，可通过 getCurrentHomeInfo 获取
+ * @param params.sourceType 请求类型
+ * @returns 支持联动的设备列表
+ * @public
+ * @since @ray-js/ray 1.4.61
+ * @example
+ * ```typescript
+ * import { getLinkageDeviceList } from '@ray-js/ray';
+ *
+ * const fetchDevices = async () => {
+ *   try {
+ *     const devices = await getLinkageDeviceList({
+ *       gid: 12345678,
+ *       sourceType: 'condition',
+ *     });
+ *     devices.forEach(dev => {
+ *       console.log(`设备: ${dev.name}, ID: ${dev.devId}`);
+ *     });
+ *   } catch (err) {
+ *     console.error('查询失败:', err);
+ *   }
+ * };
+ * ```
  */
 const getLinkageDeviceList = params => {
   return requestCloud({
@@ -21,9 +43,29 @@ const getLinkageDeviceList = params => {
 };
 
 /**
- * 查询家庭下联动规则列表，包含失效及自动化规则
- * @param {number} devId 设备id
- * @param {number} gid 家庭Id
+ * 查询设备支持的一键执行场景，包含失效及自动化规则
+ * @param params - 查询参数
+ * @param params.devId 设备 ID
+ * @param params.gid 家庭 ID
+ * @returns 联动规则列表
+ * @public
+ * @since @ray-js/ray 1.4.61
+ * @example
+ * ```typescript
+ * import { getSceneList } from '@ray-js/ray';
+ *
+ * const fetchScenes = async () => {
+ *   try {
+ *     const scenes = await getSceneList({
+ *       devId: 'device_001',
+ *       gid: '12345678',
+ *     });
+ *     console.log('场景列表:', scenes);
+ *   } catch (err) {
+ *     console.error('查询失败:', err);
+ *   }
+ * };
+ * ```
  */
 const getSceneList = _ref => {
   let {
@@ -44,9 +86,31 @@ const getSceneList = _ref => {
 
 /**
  * 查询家庭下一键执行列表，会去掉失效或自动化规则
- * @param {number} devId 设备id
- * @param {boolean} containStandardZigBee 是否包含标准场景，默认不包含
- * @param {number} gid 家庭Id
+ * @param params - 查询参数
+ * @param params.devId 设备 ID
+ * @param params.gid 家庭 ID
+ * @param params.containStandardZigBee 是否包含标准场景
+ * @defaultValue containStandardZigBee false
+ * @returns 一键执行类型的联动规则列表
+ * @public
+ * @since @ray-js/ray 1.5.15
+ * @example
+ * ```typescript
+ * import { getSceneListV2 } from '@ray-js/ray';
+ *
+ * const fetchScenes = async () => {
+ *   try {
+ *     const scenes = await getSceneListV2({
+ *       devId: 'device_001',
+ *       gid: '12345678',
+ *       containStandardZigBee: false,
+ *     });
+ *     console.log('一键执行列表:', scenes);
+ *   } catch (err) {
+ *     console.error('查询失败:', err);
+ *   }
+ * };
+ * ```
  */
 const getSceneListV2 = _ref2 => {
   let {
@@ -68,10 +132,35 @@ const getSceneListV2 = _ref2 => {
 };
 
 /**
- * 查询家庭下已绑定的列表
- * @param {string} bizDomain 业务范围
- * @param {string} devId 设备id
- * @param {number} entityType 实体类型
+ * 查询设备条件已绑定的场景
+ * @param params - 查询参数
+ * @param params.bizDomain 业务域
+ * @param params.devId 设备 ID
+ * @param params.entityType 实体类型，1 为设备，2 为联动规则
+ * @param params.gid 家庭 ID
+ * @returns 已绑定的规则列表
+ * @public
+ * @since @ray-js/ray 1.4.61
+ * @example
+ * ```typescript
+ * import { getBindRuleList } from '@ray-js/ray';
+ *
+ * const fetchBindRules = async () => {
+ *   try {
+ *     const rules = await getBindRuleList({
+ *       bizDomain: 'wirelessSwitch',
+ *       devId: 'device_001',
+ *       entityType: 1,
+ *       gid: '12345678',
+ *     });
+ *     rules.forEach(rule => {
+ *       console.log(`绑定ID: ${rule.bindId}, 启用: ${rule.enable}`);
+ *     });
+ *   } catch (err) {
+ *     console.error('查询失败:', err);
+ *   }
+ * };
+ * ```
  */
 const getBindRuleList = async params => {
   const {
@@ -93,14 +182,39 @@ const getBindRuleList = async params => {
 };
 
 /**
- * 绑定联动
- * @param {string} devId 设备 ID
- * @param {string} associativeEntityId 关联DP点和DP点值的组合
- * @param {string} ruleId 关联场景 ID
- * @param {string} entitySubIds 关联 DP 点
- * @param {Array} expr 关联DP点、动作组合
- * @param {string} bizDomain 业务域
- * @param {string} bizDomain 业务域
+ * 将按键条件与场景规则关联，建立设备按键与联动规则的绑定关系
+ * @param params - 绑定规则参数
+ * @param params.devId 设备 ID
+ * @param params.associativeEntityId 与面板/设备建立绑定关系，通常为设备 ID、DP 点、群组、规则，dpId#value 等
+ * @param params.ruleId 关联场景 ID
+ * @param params.entitySubIds 关联 DP 点
+ * @param params.expr 关联 DP 点、动作组合
+ * @param params.bizDomain 业务域
+ * @param params.gid 家庭 ID，可通过 getCurrentHomeInfo 获取
+ * @returns 绑定结果信息
+ * @public
+ * @since @ray-js/ray 1.7.60
+ * @example
+ * ```typescript
+ * import { bindRule } from '@ray-js/ray';
+ *
+ * const bindSceneRule = async () => {
+ *   try {
+ *     const result = await bindRule({
+ *       devId: 'device_001',
+ *       associativeEntityId: '1',
+ *       ruleId: 'rule_001',
+ *       entitySubIds: '1',
+ *       expr: [['$dp1', '==', 'true']],
+ *       bizDomain: 'wirelessSwitch',
+ *       gid: '12345678',
+ *     });
+ *     console.log('绑定成功, ID:', result.id);
+ *   } catch (err) {
+ *     console.error('绑定失败:', err);
+ *   }
+ * };
+ * ```
  */
 const bindRule = params => {
   const {
@@ -149,9 +263,29 @@ const bindRule = params => {
 };
 
 /**
- * 解绑联动
- * @param {string} bindId 绑定 id
- * @param {string} gid 家庭id
+ * 解绑联动，删除按键条件与场景规则的绑定关系
+ * @param params - 解绑规则参数
+ * @param params.bindId 绑定 ID
+ * @param params.gid 家庭 ID
+ * @returns 是否解绑成功
+ * @public
+ * @since @ray-js/ray 1.5.15
+ * @example
+ * ```typescript
+ * import { unbindRule } from '@ray-js/ray';
+ *
+ * const unbindSceneRule = async () => {
+ *   try {
+ *     const success = await unbindRule({
+ *       bindId: '123456',
+ *       gid: '12345678',
+ *     });
+ *     console.log('解绑结果:', success);
+ *   } catch (err) {
+ *     console.error('解绑失败:', err);
+ *   }
+ * };
+ * ```
  */
 const unbindRule = params => {
   return requestCloud({
@@ -167,12 +301,35 @@ const unbindRule = params => {
 };
 
 /**
- * 解除联动
- * @param {string} bizDomain 业务范围
- * @param {string} devId 设备id
- * @param {string} associativeEntityId 关联dp组合
- * @param {string} associativeEntityValue 规则id
- * @param {string} gid 家庭id
+ * 移除相关按键条件下的场景规则
+ * @param params - 移除规则参数
+ * @param params.bizDomain 业务域
+ * @param params.devId 设备 ID
+ * @param params.associativeEntityId 绑定关系标识
+ * @param params.associativeEntityValue 规则 ID
+ * @param params.gid 家庭 ID
+ * @returns 是否删除成功
+ * @public
+ * @since @ray-js/ray 1.7.60
+ * @example
+ * ```typescript
+ * import { removeRule } from '@ray-js/ray';
+ *
+ * const removeSceneRule = async () => {
+ *   try {
+ *     const success = await removeRule({
+ *       bizDomain: 'wirelessSwitch',
+ *       devId: 'device_001',
+ *       associativeEntityId: '1',
+ *       associativeEntityValue: 'rule_001',
+ *       gid: '12345678',
+ *     });
+ *     console.log('移除结果:', success);
+ *   } catch (err) {
+ *     console.error('移除失败:', err);
+ *   }
+ * };
+ * ```
  */
 const removeRule = params => {
   const {
@@ -194,52 +351,100 @@ const removeRule = params => {
 };
 
 /**
- * 触发联动
- * @param {string} ruleId 规则id
+ * 一键触发场景联动，由云端执行关联的自动化规则
+ * @param params - 触发规则参数
+ * @param params.ruleId 规则 ID
+ * @returns 是否执行成功
+ * @public
+ * @since @ray-js/ray 1.7.60
+ * @example
+ * ```typescript
+ * import { triggerRule } from '@ray-js/ray';
+ *
+ * const triggerSceneRule = async () => {
+ *   try {
+ *     const success = await triggerRule({
+ *       ruleId: 'rule_001',
+ *     });
+ *     console.log('触发结果:', success);
+ *   } catch (err) {
+ *     console.error('触发失败:', err);
+ *   }
+ * };
+ * ```
  */
-const triggerRule = _ref3 => {
-  let {
-    ruleId
-  } = _ref3;
+const triggerRule = params => {
   return requestCloud({
     api: "".concat(THING, ".m.linkage.rule.trigger"),
     version: '1.0',
     data: {
-      ruleId
+      ruleId: params.ruleId
     }
   });
 };
 
 /**
- *  启用联动
- * @param {string} ruleId 规则id
+ * 开启已绑定规则，恢复规则的自动执行
+ * @param params - 启用规则参数
+ * @param params.ruleId 规则 ID
+ * @returns 是否操作成功
+ * @public
+ * @since @ray-js/ray 1.7.60
+ * @example
+ * ```typescript
+ * import { enableRule } from '@ray-js/ray';
+ *
+ * const enableSceneRule = async () => {
+ *   try {
+ *     const success = await enableRule({
+ *       ruleId: 'rule_001',
+ *     });
+ *     console.log('开启规则结果:', success);
+ *   } catch (err) {
+ *     console.error('开启失败:', err);
+ *   }
+ * };
+ * ```
  */
-const enableRule = _ref4 => {
-  let {
-    ruleId
-  } = _ref4;
+const enableRule = params => {
   return requestCloud({
     api: "".concat(THING, ".m.linkage.rule.enable"),
     version: '1.0',
     data: {
-      ruleId
+      ruleId: params.ruleId
     }
   });
 };
 
 /**
- * 停用联动
- * @param {string} ruleId 规则id
+ * 关闭已绑定规则，暂停规则的自动执行
+ * @param params - 禁用规则参数
+ * @param params.ruleId 规则 ID
+ * @returns 是否操作成功
+ * @public
+ * @since @ray-js/ray 1.7.60
+ * @example
+ * ```typescript
+ * import { disableRule } from '@ray-js/ray';
+ *
+ * const disableSceneRule = async () => {
+ *   try {
+ *     const success = await disableRule({
+ *       ruleId: 'rule_001',
+ *     });
+ *     console.log('关闭规则结果:', success);
+ *   } catch (err) {
+ *     console.error('关闭失败:', err);
+ *   }
+ * };
+ * ```
  */
-const disableRule = _ref5 => {
-  let {
-    ruleId
-  } = _ref5;
+const disableRule = params => {
   return requestCloud({
     api: "".concat(THING, ".m.linkage.rule.disable"),
     version: '1.0',
     data: {
-      ruleId
+      ruleId: params.ruleId
     }
   });
 };

package/lib/cloud/remoteGroup.d.ts

@@ -1,10 +1,47 @@
 import { IGetZigbeeLocalGroupDeviceList, IGetZigbeeLocalGroupDeviceListResponse, IGetZigbeeLocalGroupRelation, IGetZigbeeLocalGroupRelationResponse } from './interface';
 /**
  * 获取 Zigbee 遥控器群组 localId 列表
+ *
+ * @public
+ * @since @ray-js/ray 1.5.2
+ * @param params - 请求参数
+ * @returns 包含 locals 数组的对象，每个元素包含 code、order、localId、categoryCode 信息
+ * @example 基础用法
+ * ```ts
+ * import { getZigbeeLocalGroupRelation } from '@ray-js/ray';
+ *
+ * getZigbeeLocalGroupRelation({
+ *   devId: 'your_device_id',
+ * }).then((response) => {
+ *   console.log('localId 列表:', response.locals);
+ * }).catch((err) => {
+ *   console.error(err);
+ * });
+ * ```
  */
 declare const getZigbeeLocalGroupRelation: (params: IGetZigbeeLocalGroupRelation) => Promise<IGetZigbeeLocalGroupRelationResponse>;
 /**
  * 获取可以加入 Zigbee 遥控器群组的设备列表
+ *
+ * @public
+ * @since @ray-js/ray 1.5.2
+ * @param params - 请求参数
+ * @returns 设备列表数组，每个元素包含 productId、devId、devOnline、devName 等设备信息
+ * @example 基础用法
+ * ```ts
+ * import { getZigbeeLocalGroupDeviceList } from '@ray-js/ray';
+ *
+ * getZigbeeLocalGroupDeviceList({
+ *   devId: 'your_device_id',
+ *   meshId: 'gateway_mesh_id',
+ *   categoryCode: '7001',
+ *   homeId: 'your_home_id',
+ * }).then((response) => {
+ *   console.log('设备列表:', response);
+ * }).catch((err) => {
+ *   console.error(err);
+ * });
+ * ```
  */
 declare const getZigbeeLocalGroupDeviceList: (params: IGetZigbeeLocalGroupDeviceList) => Promise<IGetZigbeeLocalGroupDeviceListResponse>;
 export { getZigbeeLocalGroupRelation, getZigbeeLocalGroupDeviceList };

package/lib/cloud/remoteGroup.js

@@ -3,6 +3,23 @@ import { requestCloud } from '../';
 import { THING } from '../constants';
 /**
  * 获取 Zigbee 遥控器群组 localId 列表
+ *
+ * @public
+ * @since @ray-js/ray 1.5.2
+ * @param params - 请求参数
+ * @returns 包含 locals 数组的对象，每个元素包含 code、order、localId、categoryCode 信息
+ * @example 基础用法
+ * ```ts
+ * import { getZigbeeLocalGroupRelation } from '@ray-js/ray';
+ *
+ * getZigbeeLocalGroupRelation({
+ *   devId: 'your_device_id',
+ * }).then((response) => {
+ *   console.log('localId 列表:', response.locals);
+ * }).catch((err) => {
+ *   console.error(err);
+ * });
+ * ```
  */
 const getZigbeeLocalGroupRelation = params => {
   return requestCloud({
@@ -17,6 +34,26 @@ const getZigbeeLocalGroupRelation = params => {
 
 /**
  * 获取可以加入 Zigbee 遥控器群组的设备列表
+ *
+ * @public
+ * @since @ray-js/ray 1.5.2
+ * @param params - 请求参数
+ * @returns 设备列表数组，每个元素包含 productId、devId、devOnline、devName 等设备信息
+ * @example 基础用法
+ * ```ts
+ * import { getZigbeeLocalGroupDeviceList } from '@ray-js/ray';
+ *
+ * getZigbeeLocalGroupDeviceList({
+ *   devId: 'your_device_id',
+ *   meshId: 'gateway_mesh_id',
+ *   categoryCode: '7001',
+ *   homeId: 'your_home_id',
+ * }).then((response) => {
+ *   console.log('设备列表:', response);
+ * }).catch((err) => {
+ *   console.error(err);
+ * });
+ * ```
  */
 const getZigbeeLocalGroupDeviceList = params => {
   return requestCloud({

package/lib/cloud/timer.d.ts

@@ -98,47 +98,125 @@ declare const getDpsLastTimer: (params: IGetDpLastTimer) => Promise<IGetDpLastTi
 declare const getLastTimerPeriod: (params: IGetLastTimerPeriod) => Promise<IGetLastTimerPeriodResponse>;
 /**
  * 获取天文定时列表
+ *
+ * @public
+ * @since @ray-js/ray 1.5.2
+ * @param params - 请求参数
+ * @returns 天文定时列表数组
+ * @example 基础用法
+ * ```ts
+ * import { getAstronomicalList } from '@ray-js/ray';
+ *
+ * getAstronomicalList({
+ *   bizId: 'vdevo160456552237748',
+ * }).then((response) => {
+ *   console.log('天文定时列表:', response);
+ * }).catch((err) => {
+ *   console.error(err);
+ * });
+ * ```
  */
 declare const getAstronomicalList: (params: IGetAstronomicalList) => Promise<IGetAstronomicalListResponse>;
 /**
  * 添加天文定时
- * @param {string} bizId 设备 ID 或群组 ID
- * @param {number} bizType 0:设备; 1:设备群组
- * @param {string} loops 周期
- * @param {any} dps dp 点，json 格式
- * @param {number} astronomicalType 天文类型， 0:日出; 1:日落
- * @param {string} timezone 时区
- * @param {string} date 日期 yyyyMMdd
- * @param {string} time 偏移时间，“HH:mm” 24 进制
- * @param {number} offsetType 偏移类型，-1 : 向前; 0 正常; 1 : 向后
- * @param {number} lat 纬度
- * @param {number} lon 经度
+ *
+ * @public
+ * @since @ray-js/ray 1.5.2
+ * @param params - 请求参数
+ * @returns 新添加天文定时的 ID
+ * @example 基础用法
+ * ```ts
+ * import { addAstronomical } from '@ray-js/ray';
+ *
+ * addAstronomical({
+ *   astronomicalType: 1,
+ *   bizId: 'vdevo160456552237748',
+ *   bizType: 0,
+ *   dps: { 1: true },
+ *   lat: 30.300694,
+ *   lon: 120.068634,
+ *   loops: '1111111',
+ *   offsetType: -1,
+ *   time: '00:04',
+ *   timezone: '+08:00',
+ * }).then((response) => {
+ *   console.log('新增天文定时 ID:', response);
+ * }).catch((err) => {
+ *   console.error(err);
+ * });
+ * ```
  */
 declare const addAstronomical: (params: IAstronomical) => Promise<number>;
 /**
  * 修改天文定时
- * @param {string} bizId 设备 ID 或群组 ID
- * @param {number} bizType 0:设备; 1:设备群组
- * @param {string} loops 周期
- * @param {any} dps dp 点，json 格式
- * @param {number} astronomicalType 天文类型， 0:日出; 1:日落
- * @param {string} timezone 时区
- * @param {string} date 日期 yyyyMMdd
- * @param {string} time 偏移时间，“HH:mm” 24 进制
- * @param {number} offsetType 偏移类型，-1 : 向前; 0 正常; 1 : 向后
- * @param {number} lat 纬度
- * @param {number} lon 经度
+ *
+ * @public
+ * @since @ray-js/ray 1.5.2
+ * @param params - 请求参数
+ * @returns 是否成功修改天文定时
+ * @example 基础用法
+ * ```ts
+ * import { updateAstronomical } from '@ray-js/ray';
+ *
+ * updateAstronomical({
+ *   id: 8642566,
+ *   astronomicalType: 1,
+ *   bizId: 'vdevo160456552237748',
+ *   bizType: 0,
+ *   dps: { 1: true },
+ *   lat: 30.300694,
+ *   lon: 120.068634,
+ *   loops: '1111111',
+ *   offsetType: -1,
+ *   time: '00:04',
+ *   timezone: '+08:00',
+ * }).then((response) => {
+ *   console.log('修改结果:', response);
+ * }).catch((err) => {
+ *   console.error(err);
+ * });
+ * ```
  */
 declare const updateAstronomical: (params: IAstronomical) => Promise<boolean>;
 /**
- * 修改天文定时使能
- * @param {string} id 定时任务id
- * @param {number} status 0:关闭；1开启
+ * 修改天文定时使能状态
+ *
+ * @public
+ * @since @ray-js/ray 1.5.2
+ * @param params - 请求参数
+ * @returns 是否成功修改状态
+ * @example 基础用法
+ * ```ts
+ * import { updateAstronomicalStatus } from '@ray-js/ray';
+ *
+ * updateAstronomicalStatus({
+ *   id: '8642566',
+ *   status: 0,
+ * }).then((response) => {
+ *   console.log('修改状态结果:', response);
+ * }).catch((err) => {
+ *   console.error(err);
+ * });
+ * ```
  */
 declare const updateAstronomicalStatus: (params: IUpdateAstronomicalStatus) => Promise<boolean>;
 /**
  * 删除天文定时
- * @param {string} id 定时任务 id
+ *
+ * @public
+ * @since @ray-js/ray 1.5.2
+ * @param params - 请求参数
+ * @returns 是否成功删除天文定时
+ * @example 基础用法
+ * ```ts
+ * import { removeAstronomical } from '@ray-js/ray';
+ *
+ * removeAstronomical({ id: '8642566' }).then((response) => {
+ *   console.log('删除结果:', response);
+ * }).catch((err) => {
+ *   console.error(err);
+ * });
+ * ```
  */
 declare const removeAstronomical: (params: {
     id: string;