@jiangtaste/baiwei-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul Lee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,360 @@
+# baiwei-sdk
+
+`baiwei-sdk` 现在收敛为一个面向百微智能网关的 TCP 长连接通信转换层。
+
+它默认只做几件事：
+
+- 建立和维护 TCP 长连接
+- 完成协议编解码
+- 关联请求/响应
+- 汇总分片消息
+- 透传网关 `report`
+- 保存登录后的 `token`
+
+它默认不再做这些事：
+
+- 不维护设备/房间/场景的长期缓存
+- 不自动帮业务层同步状态
+- 不把 SDK 本身做成状态中心
+
+## 安装
+
+```bash
+npm install baiwei-sdk
+```
+
+## 适用场景
+
+这个 SDK 适合放在更上层的库或服务下面，作为“百微网关协议适配层”：
+
+- 在 `NestJS` 服务里做网关接入
+- 在 `Homebridge` / `Home Assistant` 插件里做设备桥接
+- 在你自己的 `IoT Hub` 或家庭中台里做设备查询、控制和上报接收
+- 在脚本工具里做调试、巡检、排障
+
+如果你的目标是：
+
+- 维持 TCP 长连接
+- 请求设备、房间、场景
+- 控制设备
+- 接收网关 `report`
+
+那么可以直接使用这个 SDK。
+
+如果你的目标是：
+
+- 做设备缓存
+- 做状态中心
+- 做自动同步和状态广播
+- 做插件平台或业务编排
+
+这些建议放在你自己的上层库里实现，而不是塞进 SDK 本身。
+
+## 快速开始
+
+### 1. 管理员登录
+
+```ts
+import {
+  BaiweiClient,
+  BaiweiProductType,
+  LightState,
+  MessageResponse,
+} from "baiwei-sdk";
+
+async function main() {
+  const client = new BaiweiClient({
+    host: "1.2.3.4", // 网关IP
+    port: 12345, // 网关端口
+    gatewaySN: "设备序列号", // MAC地址去掉空格
+    timeoutMs: 5_000,
+  });
+
+  client.on("report", (message) => {
+    const device = client.controlService.getReportedDeviceState(
+      message as MessageResponse
+    );
+
+    if (device) {
+      console.log("device report", device.device_id, device.device_status);
+    }
+  });
+
+  await client.connect();
+  await client.userService.login();
+
+  const devices = await client.deviceService.getDevicesByType(
+    BaiweiProductType.ON_OFF_LIGHT
+  );
+
+  const states = await client.controlService.getDeviceStatesByType<LightState>(
+    BaiweiProductType.ON_OFF_LIGHT
+  );
+
+  console.log("devices", devices.length);
+  console.log("states", states.device_list?.length ?? 0);
+}
+
+main().catch(console.error);
+```
+
+### 2. 普通用户账号密码登录
+
+```ts
+import { BaiweiClient } from "baiwei-sdk";
+
+async function main() {
+  const client = new BaiweiClient({
+    host: "192.168.4.14",
+    port: 12345,
+    gatewaySN: "304a2656b37e",
+  });
+
+  await client.connect();
+  await client.userService.login({
+    userName: "alice",
+    userPwd: "123456",
+  });
+
+  const rooms = await client.roomService.listRooms();
+  console.log("rooms", rooms.length);
+}
+
+main().catch(console.error);
+```
+
+## API 边界
+
+你可以直接把它当作“协议适配器”来用：
+
+- `client.connect()` / `client.disconnect()` 负责连接生命周期
+- `client.request()` 允许你直接发原始协议请求
+- `client.on("report", handler)` 接收网关主动上报
+- `userService` / `deviceService` / `controlService` / `roomService` / `sceneService` / `gatewayService` 只保留单次请求封装
+
+## 当前设计原则
+
+- SDK 只保留通信所需的最小状态：连接、token、pending request、分片组装
+- 业务缓存、状态合并、同步策略交给上层网关服务实现
+- 如果后续要接 Home Assistant、NestJS、Homebridge，这一层都可以继续复用
+
+## 其他库如何使用这个 SDK
+
+最推荐的方式是：**把它当作底层驱动，不要直接把业务逻辑写进 SDK。**
+
+### 接入思路
+
+通常可以分成三层：
+
+1. `baiwei-sdk`
+   只负责 TCP、协议、请求/响应、report。
+2. 你的网关适配层
+   负责缓存设备目录、维护状态、重连后的重新同步、事件分发。
+3. 你的业务层 / 插件层
+   负责 UI、自动化、告警、场景编排、第三方平台桥接。
+
+### 在服务端项目中使用
+
+如果你在 `NestJS`、`Express`、`Fastify` 之类的服务端项目里接入，建议封装一个长期存活的网关服务：
+
+```ts
+import {
+  BaiweiClient,
+  BaiweiProductType,
+  MessageResponse,
+} from "baiwei-sdk";
+
+export class BaiweiGatewayService {
+  private readonly client = new BaiweiClient({
+    host: process.env.BAIWEI_HOST!,
+    port: Number(process.env.BAIWEI_PORT!),
+    gatewaySN: process.env.BAIWEI_GATEWAY_SN!,
+    timeoutMs: 5000,
+  });
+
+  async start() {
+    this.client.on("report", (message) => {
+      this.handleReport(message as MessageResponse);
+    });
+
+    await this.client.connect();
+    await this.client.userService.login({
+      userName: process.env.BAIWEI_USER_NAME!,
+      userPwd: process.env.BAIWEI_USER_PWD!,
+    });
+  }
+
+  async listLights() {
+    return this.client.deviceService.getDevicesByType(
+      BaiweiProductType.ON_OFF_LIGHT
+    );
+  }
+
+  async stop() {
+    this.client.disconnect();
+  }
+
+  private handleReport(message: MessageResponse) {
+    const device = this.client.controlService.getReportedDeviceState(message);
+    if (!device) return;
+
+    console.log("device report", device.device_id, device.device_status);
+  }
+}
+```
+
+这种模式适合：
+
+- 你的服务要长期在线
+- 你要统一管理连接和登录
+- 你要把上报转成自己的事件总线
+
+### 在 Homebridge / Home Assistant 类插件中使用
+
+插件层通常不要让每个 accessory / entity 自己建连接。更合理的方式是：
+
+- 整个插件只维护一个 `BaiweiClient`
+- 启动时统一登录
+- 用 `deviceService` 拉一次设备目录
+- 用 `controlService` 查询状态或发送控制
+- 用 `report` 更新插件内部缓存
+
+也就是说，这个 SDK 更适合作为“单网关单连接”的底层驱动，而不是每个设备实例各自使用。
+
+### 在你自己的领域库中二次封装
+
+如果你准备做一个更高层的库，比如：
+
+- `baiwei-homebridge-adapter`
+- `baiwei-nest-gateway`
+- `baiwei-state-manager`
+
+建议在上层封装这些能力：
+
+- 设备缓存：启动后拉取一次 `deviceService.listDevices()`
+- 状态缓存：收到 `report` 时合并到内存状态
+- 自动重同步：重连后重新登录、重新拉目录、重新拉状态
+- 业务事件：对外发出 `device-updated`、`room-updated`、`scene-triggered`
+- 权限与多租户：如果普通用户和管理员权限不同，这一层做权限隔离
+
+SDK 自己则尽量保持“薄”，避免和你的业务模型耦合。
+
+## 推荐封装方式
+
+### 1. 做一个单例 client
+
+不要在每次请求里都 `new BaiweiClient()`；更推荐在进程生命周期内复用一个实例。
+
+### 2. 登录逻辑集中管理
+
+建议只在一处完成：
+
+- `client.connect()`
+- `client.userService.login()`
+
+不要让业务层到处散落登录逻辑。
+
+### 3. 把 report 当事件源，不要当最终状态
+
+`report` 只是网关主动上报的消息流。上层如果要形成完整状态，仍然建议自己维护缓存和合并策略。
+
+### 4. 尽量让业务代码依赖你自己的适配层
+
+也就是说，业务代码最好依赖：
+
+```ts
+gateway.listLights()
+gateway.turnOn(deviceId)
+gateway.getRoomDevices(roomId)
+```
+
+而不是在每个业务模块里直接操作 `client.deviceService`、`client.controlService`。
+
+这样你以后换协议、换缓存策略、换权限模型，改动面会小很多。
+
+## 原始协议请求
+
+如果现成 service 还没覆盖某个接口，可以直接走 `client.request()`：
+
+```ts
+import { BaiweiClient, MsgClass, MsgName, MsgType } from "baiwei-sdk";
+
+const response = await client.request({
+  msgClass: MsgClass.CONTROL_MGMT,
+  msgName: MsgName.DEVICE_STATE_GET,
+  msgType: MsgType.GET,
+  payload: {
+    device: {
+      type: "On/Off Light",
+    },
+  },
+});
+```
+
+这对你做上层库很有用：即使 SDK 还没补好某个 service，你也能先继续开发。
+
+## 调试 SDK
+
+仓库里已经带了一个可直接运行的调试入口：[examples/debug.ts](/Users/paul/OrbStack/ubuntu/opt/baiwei-sdk/examples/debug.ts:1)。
+
+先准备连接参数：
+
+```bash
+export BAIWEI_HOST=192.168.4.14
+export BAIWEI_PORT=12345
+export BAIWEI_GATEWAY_SN=304a2656b37e
+export BAIWEI_USER_PWD=888888
+export BAIWEI_DEBUG=1
+```
+
+如果要测试普通用户登录，还可以额外设置：
+
+```bash
+export BAIWEI_USER_NAME=alice
+export BAIWEI_USER_PWD=123456
+```
+
+然后可以直接跑这些命令：
+
+```bash
+npm run debug -- overview
+npm run debug -- devices
+npm run debug -- devices ON_OFF_LIGHT
+npm run debug -- states ON_OFF_LIGHT
+npm run debug -- state <deviceId> ON_OFF_LIGHT
+npm run debug -- rooms
+npm run debug -- scenes
+npm run debug -- reports
+npm run debug -- permit-join 60
+npm run debug -- call-scene 1
+```
+
+如果你要直接调原始协议请求，用 `raw`：
+
+```bash
+export BAIWEI_MSG_CLASS=CONTROL_MGMT
+export BAIWEI_MSG_NAME=DEVICE_STATE_GET
+export BAIWEI_MSG_TYPE=GET
+export BAIWEI_RAW_PAYLOAD='{"device":{"type":"On/Off Light"}}'
+
+npm run debug -- raw
+```
+
+几个调试建议：
+
+- 连通性先看 `overview`，它会快速验证连接、登录、设备/房间/场景查询。
+- 想观察网关主动上报时，用 `reports`，保持连接直到你按 `Ctrl+C`。
+- 想看 SDK 底层收发和报文切包，打开 `BAIWEI_DEBUG=1`。
+- `state` 和 `states` 在当前无状态设计下都需要显式传设备类型。
+
+## 小结
+
+一句话概括：`baiwei-sdk` 更适合作为“百微网关协议驱动层”，而不是最终业务层。
+
+如果你在别的库里使用它，最佳实践通常是：
+
+- 复用单连接
+- 集中登录
+- 自己做缓存
+- 自己做事件模型
+- 需要时直接走原始协议请求

package/dist/core/BaiweiClient.d.ts

@@ -0,0 +1,38 @@
+import { EventEmitter } from "events";
+import { ControlService } from "../services/ControlService";
+import { DeviceService } from "../services/DeviceService";
+import { GatewayService } from "../services/GatewayService";
+import { RoomService } from "../services/RoomService";
+import { SceneService } from "../services/SceneService";
+import { UserService } from "../services/UserService";
+import { BaiweiClientOptions, MessageRequest } from "../types";
+/**
+ * SDK 对外主入口。
+ * 负责组装 session 和各类 service，并把底层事件转发给上层调用者。
+ */
+export declare class BaiweiClient extends EventEmitter {
+    readonly options: BaiweiClientOptions;
+    private readonly session;
+    private log;
+    private readonly onSessionConnected;
+    private readonly onSessionDisconnect;
+    private readonly onSessionReport;
+    private readonly onSessionError;
+    readonly userService: UserService;
+    readonly deviceService: DeviceService;
+    readonly gatewayService: GatewayService;
+    readonly controlService: ControlService;
+    readonly sceneService: SceneService;
+    readonly roomService: RoomService;
+    constructor(options: BaiweiClientOptions);
+    /** 返回当前是否已建立可用连接。 */
+    isConnected(): boolean;
+    /** 建立到网关的连接，失败时记录日志并继续抛错。 */
+    connect(): Promise<void>;
+    /** 不抛异常的连接封装，适合脚本或探测式调用。 */
+    connectSafe(): Promise<boolean>;
+    disconnect(): void;
+    request<T>(message: MessageRequest): Promise<T>;
+    /** 统一补齐 session 运行所需的默认值。 */
+    private buildSessionOptions;
+}

package/dist/core/BaiweiClient.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaiweiClient = void 0;
+const events_1 = require("events");
+const ControlService_1 = require("../services/ControlService");
+const DeviceService_1 = require("../services/DeviceService");
+const GatewayService_1 = require("../services/GatewayService");
+const RoomService_1 = require("../services/RoomService");
+const SceneService_1 = require("../services/SceneService");
+const UserService_1 = require("../services/UserService");
+const types_1 = require("../types");
+const logger_1 = require("../utils/logger");
+const BaiweiSession_1 = require("./BaiweiSession");
+/**
+ * SDK 对外主入口。
+ * 负责组装 session 和各类 service，并把底层事件转发给上层调用者。
+ */
+class BaiweiClient extends events_1.EventEmitter {
+    options;
+    session;
+    log;
+    onSessionConnected = () => this.emit("connected");
+    onSessionDisconnect = (reason) => this.emit("disconnect", reason);
+    onSessionReport = (message) => this.emit("report", message);
+    onSessionError = (error) => {
+        if (this.listenerCount("error") > 0) {
+            this.emit("error", error);
+        }
+    };
+    userService;
+    deviceService;
+    gatewayService;
+    controlService;
+    sceneService;
+    roomService;
+    constructor(options) {
+        super();
+        this.options = options;
+        this.log = (0, logger_1.createLogger)(options.logger, { prefix: "Baiwei" });
+        const session = new BaiweiSession_1.BaiweiSession(this.buildSessionOptions());
+        this.userService = new UserService_1.UserService(session);
+        this.deviceService = new DeviceService_1.DeviceService(session);
+        this.gatewayService = new GatewayService_1.GatewayService(session);
+        this.controlService = new ControlService_1.ControlService(session);
+        this.sceneService = new SceneService_1.SceneService(session);
+        this.roomService = new RoomService_1.RoomService(session);
+        session.on("connected", this.onSessionConnected);
+        session.on("disconnect", this.onSessionDisconnect);
+        session.on("report", this.onSessionReport);
+        session.on("error", this.onSessionError);
+        this.session = session;
+    }
+    /** 返回当前是否已建立可用连接。 */
+    isConnected() {
+        return this.session.isConnected();
+    }
+    /** 建立到网关的连接，失败时记录日志并继续抛错。 */
+    async connect() {
+        try {
+            await this.session.connect();
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.log.error("Failed to connect to gateway:", errorMessage);
+            throw error;
+        }
+    }
+    /** 不抛异常的连接封装，适合脚本或探测式调用。 */
+    async connectSafe() {
+        try {
+            await this.connect();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    disconnect() {
+        this.session.disconnect();
+    }
+    request(message) {
+        return this.session.request(message);
+    }
+    /** 统一补齐 session 运行所需的默认值。 */
+    buildSessionOptions() {
+        return {
+            ...this.options,
+            clientId: this.options.clientId ?? types_1.DEFAULT_CLIENT_ID,
+            timeoutMs: this.options.timeoutMs ?? types_1.DEFAULT_TIMEOUT_MS,
+            logger: this.log,
+        };
+    }
+}
+exports.BaiweiClient = BaiweiClient;

package/dist/core/BaiweiSession.d.ts

@@ -0,0 +1,56 @@
+import EventEmitter from "events";
+import { BaiweiSessionOptions, MessageRequest } from "../types";
+/**
+ * 会话编排层。
+ * 负责连接、请求派发、响应匹配、分片合并和 report 转发。
+ */
+export declare class BaiweiSession extends EventEmitter {
+    private readonly tcp;
+    private readonly options;
+    private readonly log;
+    private listenersAttached;
+    private token?;
+    private connecting?;
+    private onTcpMessage;
+    private onTcpConnected;
+    private onTcpDisconnect;
+    private onTcpError;
+    private onTcpProtocolError;
+    private readonly idGenerator;
+    private readonly pending;
+    private readonly assembler;
+    private readonly connector;
+    constructor(options: BaiweiSessionOptions);
+    /** 返回 TCP 层当前是否可用。 */
+    isConnected(): boolean;
+    /** 幂等连接：重复调用时复用同一个连接过程。 */
+    connect(): Promise<void>;
+    /** 登录成功后保存 token，后续请求会自动带上。 */
+    updateToken(token?: string): void;
+    disconnect(): void;
+    /** 构造协议请求并注册 pending，等待后续 response 匹配回填。 */
+    request<T>(req: MessageRequest): Promise<T>;
+    /** 把 SDK 内部请求结构转换成网关协议报文。 */
+    private createMessage;
+    private handleDisconnect;
+    /** 只在构造时绑定一次底层事件，避免重复注册。 */
+    private bindTcpListeners;
+    /** 断线时统一清理请求与分片状态，避免悬空定时器和脏数据。 */
+    private clearRuntimeState;
+    /** 统一处理来自 TCP 层的完整 JSON 消息。 */
+    private onMessage;
+    /** 只接受来自目标网关且带有合法 msg_id 的消息。 */
+    private validateMessage;
+    /** 网关返回非 0 状态码时，优先回填给对应请求。 */
+    private handleGatewayError;
+    /** 分片逻辑委托给 assembler，session 只保留编排职责。 */
+    private handleFragmentation;
+    /** 按消息类型分发到 response/report 两条处理链。 */
+    private handleMessageResponse;
+    /** response 通过 msgId 命中 pending 请求并完成 Promise。 */
+    private handleResponse;
+    /** report 不做状态缓存，保持原样向上层抛出。 */
+    private handleReport;
+    /** 统一发出 Error 对象，避免到处重复 new Error。 */
+    private emitError;
+}