@ray-js/api 1.7.69 → 1.7.71

package/@types/gateway.d.ts

@@ -1,146 +1,434 @@
 declare namespace ty.gateway {
-  // 1. 下发更新LQI指令
   type SendCmdForRefreshDeviceLQIParams = {
-    devId: string; // 子设备id
+    /** 子设备 ID */
+    devId: string;
   };
 
-  type SendCmdForRefreshDeviceLQIResponse = boolean; // 是否下发成功
+  type SendCmdForRefreshDeviceLQIResponse = boolean;
 
-  function sendCmdForRefreshDeviceLQI(params: SendCmdForRefreshDeviceLQIParams): Promise<SendCmdForRefreshDeviceLQIResponse>;
+  /**
+   * 下发更新 LQI 指令，用于刷新网关子设备的信号质量值
+   * @public
+   * @since @ray-js/ray 1.7.60
+   * @param params - 请求参数
+   * @param params.devId 子设备 ID
+   * @returns 是否下发成功
+   * @example
+   * ```typescript
+   * import { gateway } from '@ray-js/ray';
+   *
+   * const refreshLQI = async () => {
+   *   try {
+   *     const success = await gateway.sendCmdForRefreshDeviceLQI({
+   *       devId: 'sub_device_001',
+   *     });
+   *     console.log('下发刷新LQI指令:', success);
+   *   } catch (err) {
+   *     console.error('下发失败:', err);
+   *   }
+   * };
+   * ```
+   */
+  function sendCmdForRefreshDeviceLQI(
+    params: SendCmdForRefreshDeviceLQIParams,
+  ): Promise<SendCmdForRefreshDeviceLQIResponse>;
 
-  // 2. 获取设备最新LQI
   type GetLastDeviceLQIParams = {
-    devId: string; //子设备id
-    offsetTime: number; //时间偏移量，单位为毫秒
+    /** 子设备 ID */
+    devId: string;
+    /** 时间偏移量，单位为毫秒 */
+    offsetTime: number;
   };
 
   type DeviceLQI = {
-    deviceId: string; //设备id
-    deviceName: string; //设备名称
-    isGateway: boolean; //是否是网关
-    lqi: number; // 子设备lqi值
-  }
+    /** 设备 ID */
+    deviceId: string;
+    /** 设备名称 */
+    deviceName: string;
+    /** 是否是网关 */
+    isGateway: boolean;
+    /** 子设备 LQI 值 */
+    lqi: number;
+  };
 
   type GetLastDeviceLQIResponse = DeviceLQI[];
 
+  /**
+   * 获取设备最新 LQI（链路质量指示）信息
+   * @public
+   * @since @ray-js/ray 1.7.60
+   * @param params - 请求参数
+   * @param params.devId 子设备 ID
+   * @param params.offsetTime 时间偏移量，单位为毫秒
+   * @returns 设备 LQI 信息列表
+   * @example
+   * ```typescript
+   * import { gateway } from '@ray-js/ray';
+   *
+   * const fetchLQI = async () => {
+   *   try {
+   *     const lqiList = await gateway.getLastDeviceLQI({
+   *       devId: 'sub_device_001',
+   *       offsetTime: 60000,
+   *     });
+   *     lqiList.forEach(item => {
+   *       console.log(`设备: ${item.deviceName}, LQI: ${item.lqi}`);
+   *     });
+   *   } catch (err) {
+   *     console.error('获取LQI失败:', err);
+   *   }
+   * };
+   * ```
+   */
   function getLastDeviceLQI(params: GetLastDeviceLQIParams): Promise<GetLastDeviceLQIResponse>;
 
-  // 3. 查询设备高级能力
   type GetSeniorAbilityParams = {
-    devId: string; // 设备id
+    /** 设备 ID */
+    devId: string;
   };
 
   type GetSeniorAbilityResponse = {
     [key: string]: string;
   };
 
+  /**
+   * 查询设备高级能力，返回设备支持的扩展能力键值对
+   * @public
+   * @since @ray-js/ray 1.7.60
+   * @param params - 请求参数
+   * @param params.devId 设备 ID
+   * @returns 设备高级能力键值对
+   * @example
+   * ```typescript
+   * import { gateway } from '@ray-js/ray';
+   *
+   * const querySeniorAbility = async () => {
+   *   try {
+   *     const abilities = await gateway.getSeniorAbility({
+   *       devId: 'device_001',
+   *     });
+   *     console.log('设备高级能力:', abilities);
+   *   } catch (err) {
+   *     console.error('查询失败:', err);
+   *   }
+   * };
+   * ```
+   */
   function getSeniorAbility(params: GetSeniorAbilityParams): Promise<GetSeniorAbilityResponse>;
 
-  // 4. 获取网关子设备数量限制
   type GetGatewaySubDevLimitParams = {
-    devId: string; // 设备id
+    /** 设备 ID */
+    devId: string;
   };
 
   type GetGatewaySubDevLimitResponse = {
-    max?: number; // 子设备数量上限
-    blu?: number; // 蓝牙子设备数量上限
-    zig?: number; // zigbee子设备数量上限
-    ver?: number; // 版本，嵌入式端上报
+    /** 子设备数量上限 */
+    max?: number;
+    /** 蓝牙子设备数量上限 */
+    blu?: number;
+    /** Zigbee 子设备数量上限 */
+    zig?: number;
+    /** 版本，嵌入式端上报 */
+    ver?: number;
   };
 
+  /**
+   * 获取网关子设备数量限制，包括各类型子设备的上限
+   * @public
+   * @since @ray-js/ray 1.7.60
+   * @param params - 请求参数
+   * @param params.devId 设备 ID
+   * @returns 子设备数量限制信息
+   * @example
+   * ```typescript
+   * import { gateway } from '@ray-js/ray';
+   *
+   * const fetchSubDevLimit = async () => {
+   *   try {
+   *     const limit = await gateway.getGatewaySubDevLimit({
+   *       devId: 'gateway_001',
+   *     });
+   *     console.log('子设备上限:', limit.max);
+   *     console.log('蓝牙子设备上限:', limit.blu);
+   *     console.log('Zigbee子设备上限:', limit.zig);
+   *   } catch (err) {
+   *     console.error('获取失败:', err);
+   *   }
+   * };
+   * ```
+   */
   function getGatewaySubDevLimit(params: GetGatewaySubDevLimitParams): Promise<GetGatewaySubDevLimitResponse>;
 
-  // 5. mesh类设备拖拽
   type UpdateRelationMeshParams = {
-    nodeIds: string[]; // 需要拖拽的子设备id列表
-    sourceMeshId?: string; // 原meshId或者网关Id
-    targetMeshId?: string; // 目标meshId或者网关Id
+    /** 需要拖拽的子设备 ID 列表 */
+    nodeIds: string[];
+    /** 原 Mesh ID 或网关 ID */
+    sourceMeshId?: string;
+    /** 目标 Mesh ID 或网关 ID */
+    targetMeshId?: string;
   };
 
   type UpdateRelationMeshResponse = {
-    repeatNodeIds: string[]; //已在网关下的设备列表
+    /** 已在网关下的设备列表 */
+    repeatNodeIds: string[];
   };
 
+  /**
+   * Mesh 类设备拖拽，将子设备从一个 Mesh 网络移动到另一个
+   * @public
+   * @since @ray-js/ray 1.7.60
+   * @param params - 请求参数
+   * @param params.nodeIds 需要拖拽的子设备 ID 列表
+   * @param params.sourceMeshId 原 Mesh ID 或网关 ID
+   * @param params.targetMeshId 目标 Mesh ID 或网关 ID
+   * @returns 拖拽结果，包含已在目标网关下的设备列表
+   * @example
+   * ```typescript
+   * import { gateway } from '@ray-js/ray';
+   *
+   * const moveMeshDevices = async () => {
+   *   try {
+   *     const result = await gateway.updateRelationMesh({
+   *       nodeIds: ['node_001', 'node_002'],
+   *       sourceMeshId: 'mesh_source',
+   *       targetMeshId: 'mesh_target',
+   *     });
+   *     if (result.repeatNodeIds.length > 0) {
+   *       console.log('已在目标网关下的设备:', result.repeatNodeIds);
+   *     }
+   *   } catch (err) {
+   *     console.error('拖拽失败:', err);
+   *   }
+   * };
+   * ```
+   */
   function updateRelationMesh(params: UpdateRelationMeshParams): Promise<UpdateRelationMeshResponse>;
 
-  // 6. 蓝牙单点类设备拖拽
   type UpdateRelationBlueParams = {
+    /** 需要拖拽的子设备 ID 与 UUID 列表 */
     nodes: {
+      /** 设备 ID */
       devId: string;
+      /** 设备 UUID */
       uuid: string;
-    }[]; // 需要拖拽的子设备id与uuid列表
-    sourceMeshId?: string; // 原网关Id
-    targetMeshId?: string; // 目标网关Id
+    }[];
+    /** 原网关 ID */
+    sourceMeshId?: string;
+    /** 目标网关 ID */
+    targetMeshId?: string;
   };
 
   type UpdateRelationBlueResponse = {
-    repeatNodeIds: string[]; //已在网关下的设备列表
+    /** 已在网关下的设备列表 */
+    repeatNodeIds: string[];
   };
 
+  /**
+   * 蓝牙单点类设备拖拽，将蓝牙子设备从一个网关移动到另一个
+   * @public
+   * @since @ray-js/ray 1.7.60
+   * @param params - 请求参数
+   * @param params.nodes 需要拖拽的子设备 ID 与 UUID 列表
+   * @param params.sourceMeshId 原网关 ID
+   * @param params.targetMeshId 目标网关 ID
+   * @returns 拖拽结果，包含已在目标网关下的设备列表
+   * @example
+   * ```typescript
+   * import { gateway } from '@ray-js/ray';
+   *
+   * const moveBlueDevices = async () => {
+   *   try {
+   *     const result = await gateway.updateRelationBlue({
+   *       nodes: [
+   *         { devId: 'blue_dev_001', uuid: 'uuid_001' },
+   *         { devId: 'blue_dev_002', uuid: 'uuid_002' },
+   *       ],
+   *       sourceMeshId: 'gateway_source',
+   *       targetMeshId: 'gateway_target',
+   *     });
+   *     if (result.repeatNodeIds.length > 0) {
+   *       console.log('已在目标网关下的设备:', result.repeatNodeIds);
+   *     }
+   *   } catch (err) {
+   *     console.error('拖拽失败:', err);
+   *   }
+   * };
+   * ```
+   */
   function updateRelationBlue(params: UpdateRelationBlueParams): Promise<UpdateRelationBlueResponse>;
 
-  // 7. beacon类设备拖拽
   type UpdateRelationBeaconParams = {
+    /** 需要拖拽的子设备 ID 与 MAC 列表 */
     nodes: {
+      /** 设备 ID */
       devId: string;
+      /** 设备 MAC 地址 */
       mac: string;
-    }[]; // 需要拖拽的子设备id与mac列表
-    sourceMeshId?: string; // 原网关Id
-    targetMeshId?: string; // 目标网关Id
+    }[];
+    /** 原网关 ID */
+    sourceMeshId?: string;
+    /** 目标网关 ID */
+    targetMeshId?: string;
   };
 
   type UpdateRelationBeaconResponse = {
-    repeatNodeIds: string[]; //已在网关下的设备列表
+    /** 已在网关下的设备列表 */
+    repeatNodeIds: string[];
   };
 
+  /**
+   * Beacon 类设备拖拽，将 Beacon 子设备从一个网关移动到另一个
+   * @public
+   * @since @ray-js/ray 1.7.60
+   * @param params - 请求参数
+   * @param params.nodes 需要拖拽的子设备 ID 与 MAC 列表
+   * @param params.sourceMeshId 原网关 ID
+   * @param params.targetMeshId 目标网关 ID
+   * @returns 拖拽结果，包含已在目标网关下的设备列表
+   * @example
+   * ```typescript
+   * import { gateway } from '@ray-js/ray';
+   *
+   * const moveBeaconDevices = async () => {
+   *   try {
+   *     const result = await gateway.updateRelationBeacon({
+   *       nodes: [
+   *         { devId: 'beacon_dev_001', mac: 'AA:BB:CC:DD:EE:01' },
+   *         { devId: 'beacon_dev_002', mac: 'AA:BB:CC:DD:EE:02' },
+   *       ],
+   *       sourceMeshId: 'gateway_source',
+   *       targetMeshId: 'gateway_target',
+   *     });
+   *     if (result.repeatNodeIds.length > 0) {
+   *       console.log('已在目标网关下的设备:', result.repeatNodeIds);
+   *     }
+   *   } catch (err) {
+   *     console.error('拖拽失败:', err);
+   *   }
+   * };
+   * ```
+   */
   function updateRelationBeacon(params: UpdateRelationBeaconParams): Promise<UpdateRelationBeaconResponse>;
 
-  // 8. 获取网关的能力
   type GetGatewayAbilityParams = {
-    devIds: string; // 设备id拼成的字符串，以逗号分隔
+    /** 设备 ID 拼成的字符串，以逗号分隔 */
+    devIds: string;
   };
 
   type GatewayAbility = {
-    capability: number; // 能力值
-    devId: string; // 设备id
-    lqi: number; // 设备信号质量
-    performance?: number; // 网关性能指标
-    subMaximum?: { // 子设备数量上线
-      data?: { // 各类型子设备数量上线
+    /** 能力值 */
+    capability: number;
+    /** 设备 ID */
+    devId: string;
+    /** 设备信号质量 */
+    lqi: number;
+    /** 网关性能指标 */
+    performance?: number;
+    /** 子设备数量上限 */
+    subMaximum?: {
+      /** 各类型子设备数量上限 */
+      data?: {
         [key: string]: number;
-      },
-      version?: number; // 版本
+      };
+      /** 版本 */
+      version?: number;
     };
-  }
+  };
 
   type GetGatewayAbilityResponse = GatewayAbility[];
 
+  /**
+   * 获取网关的能力信息，包括信号质量、性能指标和子设备数量上限
+   * @public
+   * @since @ray-js/ray 1.7.60
+   * @param params - 请求参数
+   * @param params.devIds 设备 ID 拼成的字符串，以逗号分隔
+   * @returns 网关能力信息列表
+   * @example
+   * ```typescript
+   * import { gateway } from '@ray-js/ray';
+   *
+   * const fetchGatewayAbility = async () => {
+   *   try {
+   *     const abilities = await gateway.getGatewayAbility({
+   *       devIds: 'gateway_001,gateway_002',
+   *     });
+   *     abilities.forEach(item => {
+   *       console.log(`设备: ${item.devId}, 能力值: ${item.capability}, LQI: ${item.lqi}`);
+   *     });
+   *   } catch (err) {
+   *     console.error('获取失败:', err);
+   *   }
+   * };
+   * ```
+   */
   function getGatewayAbility(params: GetGatewayAbilityParams): Promise<GetGatewayAbilityResponse>;
 
-  // 9. 获取设备日志
   type GetSecurityDeviceLogParams = {
+    /** 查询条件字符串 */
     queryStr: string;
   };
 
   type DeviceLogData = {
-    rowkey: string; // key
-    dpName: string; // dp名称
-    createTime: number; // 创建时间
-    eventTime: number; // 上报时间
-    dpId: string; // dpId
-    eventType: string; // 事件类型
-    value: string; // dp值
-    deviceId: string; // 设备id
-  }
+    /** 数据行唯一标识 */
+    rowkey: string;
+    /** DP 名称 */
+    dpName: string;
+    /** 创建时间 */
+    createTime: number;
+    /** 上报时间 */
+    eventTime: number;
+    /** DP ID */
+    dpId: string;
+    /** 事件类型 */
+    eventType: string;
+    /** DP 值 */
+    value: string;
+    /** 设备 ID */
+    deviceId: string;
+  };
 
   type GetSecurityDeviceLogResponse = {
-    devId: string; // 设备id
+    /** 设备 ID */
+    devId: string;
+    /** 日志数据列表 */
     datas: DeviceLogData[];
-    hasNext: boolean; // 是否还有下一页
-    totalCount: number; // 总数
-    currentPageStartRowKey?: string; // 当前页起始key
+    /** 是否还有下一页 */
+    hasNext: boolean;
+    /** 总数 */
+    totalCount: number;
+    /** 当前页起始 key */
+    currentPageStartRowKey?: string;
   };
 
+  /**
+   * 获取设备安全日志，支持分页查询
+   * @public
+   * @since @ray-js/ray 1.7.60
+   * @param params - 请求参数
+   * @param params.queryStr 查询条件字符串
+   * @returns 设备日志数据，包含日志列表和分页信息
+   * @example
+   * ```typescript
+   * import { gateway } from '@ray-js/ray';
+   *
+   * const fetchDeviceLog = async () => {
+   *   try {
+   *     const logData = await gateway.getSecurityDeviceLog({
+   *       queryStr: 'device_001',
+   *     });
+   *     console.log('总数:', logData.totalCount);
+   *     logData.datas.forEach(log => {
+   *       console.log(`DP: ${log.dpName}, 值: ${log.value}, 时间: ${log.eventTime}`);
+   *     });
+   *     if (logData.hasNext) {
+   *       console.log('还有更多数据');
+   *     }
+   *   } catch (err) {
+   *     console.error('获取日志失败:', err);
+   *   }
+   * };
+   * ```
+   */
   function getSecurityDeviceLog(params: GetSecurityDeviceLogParams): Promise<GetSecurityDeviceLogResponse>;
 }
-