@jiangtaste/baiwei-sdk 1.0.0

package/dist/core/Session.js

@@ -0,0 +1,330 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaiweiSession = void 0;
+const events_1 = __importDefault(require("events"));
+const TcpClient_1 = require("../transport/TcpClient");
+const types_1 = require("../types");
+const IdGenerator_1 = require("../utils/IdGenerator");
+const logger_1 = require("../utils/logger");
+class BaiweiSession extends events_1.default {
+    tcp;
+    options;
+    log;
+    listenersAttached = false;
+    token;
+    connecting;
+    onTcpMessage = (message) => this.onMessage(message);
+    onTcpConnected = () => this.emit("connected");
+    onTcpDisconnect = (reason) => this.handleDisconnect(reason);
+    onTcpError = (err) => {
+        if (this.connecting) {
+            return;
+        }
+        this.emit("error", err);
+    };
+    onTcpProtocolError = (err) => this.emit("error", err);
+    idGenerator = new IdGenerator_1.IdGenerator();
+    pending = new Map();
+    partialPayloads = new Map();
+    constructor(options) {
+        super();
+        this.log = (0, logger_1.createLogger)(options.logger);
+        this.options = options;
+        this.tcp = new TcpClient_1.TcpClient({ ...this.options });
+        this.bindTcpListeners();
+    }
+    /**
+     * Check if the session is currently connected.
+     */
+    isConnected() {
+        return this.tcp.isConnected();
+    }
+    /**
+     * Establish TCP connection.
+     * Returns existing promise if connection is already in progress.
+     * If already connected, returns a resolved promise.
+     */
+    connect() {
+        if (this.isConnected()) {
+            return Promise.resolve();
+        }
+        if (this.connecting) {
+            return this.connecting;
+        }
+        this.connecting = new Promise((resolve, reject) => {
+            let done = false;
+            let timer;
+            const cleanup = () => {
+                this.tcp.off("connected", onConnected);
+                this.tcp.off("error", onError);
+                if (timer) {
+                    clearTimeout(timer);
+                    timer = undefined;
+                }
+                this.connecting = undefined;
+            };
+            const succeed = () => {
+                if (done)
+                    return;
+                done = true;
+                cleanup();
+                resolve();
+            };
+            const fail = (err) => {
+                if (done)
+                    return;
+                done = true;
+                const error = err instanceof Error ? err : new Error(String(err ?? "connect failed"));
+                this.log.error("Connection failed:", error.message);
+                cleanup();
+                this.emit("error", error);
+                reject(error);
+            };
+            const onConnected = () => succeed();
+            const onError = (err) => fail(err);
+            this.tcp.on("connected", onConnected);
+            this.tcp.on("error", onError);
+            timer = setTimeout(() => {
+                try {
+                    fail(new Error("connect timeout"));
+                }
+                catch (e) {
+                    this.log.error("Unexpected error in timeout handler:", e);
+                }
+            }, 10_000);
+            try {
+                this.tcp.connect();
+            }
+            catch (e) {
+                fail(e);
+            }
+        });
+        return this.connecting;
+    }
+    updateToken(token) {
+        this.token = token;
+    }
+    disconnect() {
+        if (!this.isConnected() && !this.connecting) {
+            this.clearRuntimeState(new Error("Session disconnected"));
+            return;
+        }
+        this.connecting = undefined;
+        this.tcp.disconnect();
+    }
+    request(req) {
+        const msgId = this.idGenerator.next();
+        const base = {
+            api_version: "0.1",
+            appId: "010",
+            from: this.options.clientId,
+            to: this.options.gatewaySN,
+            msg_id: msgId,
+            msg_class: req.msgClass,
+            msg_name: req.msgName,
+            msg_type: req.msgType || types_1.MsgType.GET,
+            token: this.token,
+        };
+        const message = { ...base, ...req.payload };
+        return new Promise(async (resolve, reject) => {
+            const timeoutTimer = setTimeout(() => {
+                this.pending.delete(msgId);
+                const err = new Error(`Request timeout: msgClass/msgName=${req.msgClass}/${req.msgName}, msgId=${msgId}`);
+                this.log.info("TCP request timeout:", err);
+                reject(err);
+            }, this.options.timeoutMs);
+            this.pending.set(msgId, {
+                resolve: (v) => resolve(v),
+                reject,
+                timeoutTimer,
+            });
+            try {
+                await this.tcp.send(message);
+            }
+            catch (err) {
+                clearTimeout(timeoutTimer);
+                this.pending.delete(msgId);
+                this.log.info("Send failed:", err);
+                reject(err);
+            }
+        });
+    }
+    handleDisconnect(reason) {
+        this.connecting = undefined;
+        this.clearRuntimeState(reason);
+        this.emit("disconnect", reason);
+    }
+    bindTcpListeners() {
+        if (this.listenersAttached) {
+            return;
+        }
+        this.tcp.on("connected", this.onTcpConnected);
+        this.tcp.on("message", this.onTcpMessage);
+        this.tcp.on("disconnected", this.onTcpDisconnect);
+        this.tcp.on("error", this.onTcpError);
+        this.tcp.on("protocol_error", this.onTcpProtocolError);
+        this.listenersAttached = true;
+    }
+    clearRuntimeState(reason) {
+        if (this.pending.size > 0) {
+            for (const [msgId, pending] of this.pending.entries()) {
+                clearTimeout(pending.timeoutTimer);
+                pending.reject(new Error(`TCP disconnected. msgId=${msgId}. reason=${String(reason ?? "")}`));
+            }
+            this.pending.clear();
+        }
+        if (this.partialPayloads.size > 0) {
+            for (const [, entry] of this.partialPayloads.entries()) {
+                clearTimeout(entry.timer);
+            }
+            this.partialPayloads.clear();
+        }
+    }
+    onMessage(message) {
+        const { api_version, from, to, msg_id, msg_class, msg_name, msg_type, end = 1, status = 0, ...payload } = message;
+        this.log.info(`API_VERSION: ${api_version}, FROM: ${from}, TO: ${to}, MSG_TYPE: ${msg_type}, MSG_ID: ${msg_id}, MSG_CLASS: ${msg_class}, MSG_NAME: ${msg_name}, END: ${end}`);
+        // Validate message
+        if (!this.validateMessage(message, from, msg_id)) {
+            return;
+        }
+        // Handle gateway errors
+        if (status !== 0) {
+            this.handleGatewayError(msg_id, status, msg_class, msg_name);
+            return;
+        }
+        // Handle message fragmentation
+        const finalPayload = this.handleFragmentation(msg_id, payload, end, msg_class, msg_name);
+        if (!finalPayload) {
+            return; // Waiting for more fragments
+        }
+        // Process complete message
+        const res = {
+            msgId: msg_id,
+            msgClass: msg_class,
+            msgName: msg_name,
+            msgType: msg_type,
+            payload: finalPayload,
+        };
+        this.log.info("FULL MESSAGE =====>", JSON.stringify(res));
+        this.handleMessageResponse(res);
+    }
+    validateMessage(message, from, msgId) {
+        if (from !== this.options.gatewaySN) {
+            const err = new Error(`Invalid gatewaySN, got ${from}, expected: ${this.options.gatewaySN}`);
+            this.emit("error", err);
+            return false;
+        }
+        if (!msgId) {
+            const err = new Error(`Invalid msgId, got ${msgId}`);
+            this.emit("error", err);
+            return false;
+        }
+        return true;
+    }
+    handleGatewayError(msgId, status, msgClass, msgName) {
+        const pending = this.pending.get(msgId);
+        if (pending) {
+            clearTimeout(pending.timeoutTimer);
+            this.pending.delete(msgId);
+            pending.reject(new Error(`Gateway status=${status}, msgClass/msgName=${msgClass}/${msgName}, msgId=${msgId}`));
+        }
+        else {
+            this.emit("error", new Error(`Gateway status=${status}, unmatched msgId=${msgId}, msgClass/msgName=${msgClass}/${msgName}`));
+        }
+    }
+    handleFragmentation(msgId, payload, end, msgClass, msgName) {
+        if (end === 1) {
+            // Last fragment
+            const prev = this.partialPayloads.get(msgId);
+            if (prev) {
+                clearTimeout(prev.timer);
+                const finalPayload = this.mergePayload(prev.payload, payload);
+                this.partialPayloads.delete(msgId);
+                return finalPayload;
+            }
+            else {
+                // No previous fragments, this is a complete message
+                return payload;
+            }
+        }
+        else {
+            // Intermediate or first fragment
+            const prev = this.partialPayloads.get(msgId);
+            if (prev) {
+                prev.payload = this.mergePayload(prev.payload, payload);
+            }
+            else {
+                const timer = setTimeout(() => {
+                    // Expired without receiving end=1: cleanup and error
+                    const entry = this.partialPayloads.get(msgId);
+                    if (entry)
+                        this.partialPayloads.delete(msgId);
+                    this.emit("error", new Error(`Partial payload expired: msgId=${msgId}, msgClass/msgName=${msgClass}/${msgName}`));
+                }, this.options.timeoutMs);
+                this.partialPayloads.set(msgId, { payload, timer });
+            }
+            // Return null to indicate waiting for more fragments
+            return null;
+        }
+    }
+    mergePayload(prev, curr) {
+        const result = { ...prev };
+        for (const key of Object.keys(curr)) {
+            const prevVal = result[key];
+            const currVal = curr[key];
+            if (prevVal &&
+                currVal &&
+                typeof prevVal === "object" &&
+                typeof currVal === "object" &&
+                !Array.isArray(prevVal) &&
+                !Array.isArray(currVal)) {
+                // Recursive merge for nested objects
+                result[key] = this.mergePayload(prevVal, currVal);
+            }
+            else if (Array.isArray(prevVal) && Array.isArray(currVal)) {
+                // Concatenate arrays (useful for { type_list: [] } scenarios)
+                result[key] = [...prevVal, ...currVal];
+            }
+            else {
+                // Otherwise, directly overwrite
+                result[key] = currVal;
+            }
+        }
+        return result;
+    }
+    handleMessageResponse(res) {
+        switch (res.msgType) {
+            case types_1.MsgType.RESPONSE:
+                this.handleResponse(res);
+                break;
+            case types_1.MsgType.REPORT:
+                this.handleReport(res);
+                break;
+            default:
+                this.log.warn(`Unknown msg_type: ${res.msgType} for msgId: ${res.msgId}`);
+                return;
+        }
+    }
+    handleResponse(res) {
+        const { msgId: msg_id, payload } = res;
+        const pending = this.pending.get(msg_id);
+        if (!pending)
+            return;
+        // Remove from pending after finding it
+        this.pending.delete(msg_id);
+        // Clear timeout timer
+        clearTimeout(pending.timeoutTimer);
+        // Log response
+        this.log.info("RESPONSE =====>", JSON.stringify(payload));
+        // Resolve promise
+        pending.resolve(payload);
+    }
+    handleReport(res) {
+        this.log.info("REPORT =====>", JSON.stringify(res.payload));
+        this.emit("report", res);
+    }
+}
+exports.BaiweiSession = BaiweiSession;

package/dist/core/SessionConnector.d.ts

@@ -0,0 +1,14 @@
+import { TcpClient } from "../transport/TcpClient";
+import { Logger } from "../utils/logger";
+/**
+ * 一次性连接握手器。
+ * 只负责本次 connect 的监听、超时和错误归一化。
+ */
+export declare class SessionConnector {
+    private readonly tcp;
+    private readonly log;
+    private readonly onError;
+    constructor(tcp: TcpClient, log: Required<Logger>, onError: (error: Error) => void);
+    /** 连接成功 resolve，连接错误或超时 reject。 */
+    connect(): Promise<void>;
+}

package/dist/core/SessionConnector.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionConnector = void 0;
+const CONNECT_TIMEOUT_MS = 10_000;
+/**
+ * 一次性连接握手器。
+ * 只负责本次 connect 的监听、超时和错误归一化。
+ */
+class SessionConnector {
+    tcp;
+    log;
+    onError;
+    constructor(tcp, log, onError) {
+        this.tcp = tcp;
+        this.log = log;
+        this.onError = onError;
+    }
+    /** 连接成功 resolve，连接错误或超时 reject。 */
+    connect() {
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            let timer;
+            const cleanup = () => {
+                this.tcp.off("connected", handleConnected);
+                this.tcp.off("error", handleError);
+                if (timer) {
+                    clearTimeout(timer);
+                    timer = undefined;
+                }
+            };
+            const finish = (error) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                cleanup();
+                if (!error) {
+                    resolve();
+                    return;
+                }
+                const normalized = error instanceof Error ? error : new Error(String(error ?? "connect failed"));
+                this.log.error("Connection failed:", normalized.message);
+                this.onError(normalized);
+                reject(normalized);
+            };
+            const handleConnected = () => finish();
+            const handleError = (error) => finish(error);
+            this.tcp.on("connected", handleConnected);
+            this.tcp.on("error", handleError);
+            timer = setTimeout(() => {
+                finish(new Error("connect timeout"));
+            }, CONNECT_TIMEOUT_MS);
+            try {
+                this.tcp.connect();
+            }
+            catch (error) {
+                finish(error);
+            }
+        });
+    }
+}
+exports.SessionConnector = SessionConnector;

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/** SDK 对外公共导出入口。 */
+export * from "./core/BaiweiClient";
+export * from "./core/BaiweiSession";
+export * from "./services/BaseService";
+export * from "./services/ControlService";
+export * from "./services/DeviceService";
+export * from "./services/GatewayService";
+export * from "./services/RoomService";
+export * from "./services/SceneService";
+export * from "./services/UserService";
+export * from "./types";

package/dist/index.js

@@ -0,0 +1,27 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/** SDK 对外公共导出入口。 */
+__exportStar(require("./core/BaiweiClient"), exports);
+__exportStar(require("./core/BaiweiSession"), exports);
+__exportStar(require("./services/BaseService"), exports);
+__exportStar(require("./services/ControlService"), exports);
+__exportStar(require("./services/DeviceService"), exports);
+__exportStar(require("./services/GatewayService"), exports);
+__exportStar(require("./services/RoomService"), exports);
+__exportStar(require("./services/SceneService"), exports);
+__exportStar(require("./services/UserService"), exports);
+__exportStar(require("./types"), exports);

package/dist/services/BaseService.d.ts

@@ -0,0 +1,11 @@
+import { BaiweiSession } from "../core/BaiweiSession";
+import { MessageRequest } from "../types";
+/**
+ * 所有 service 的公共基类。
+ * 统一把协议请求委托给 session。
+ */
+export declare abstract class BaseService {
+    protected readonly session: BaiweiSession;
+    constructor(session: BaiweiSession);
+    protected request<TResponse, TPayload extends Record<string, unknown> = Record<string, unknown>>(message: MessageRequest<TPayload>): Promise<TResponse>;
+}

package/dist/services/BaseService.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseService = void 0;
+/**
+ * 所有 service 的公共基类。
+ * 统一把协议请求委托给 session。
+ */
+class BaseService {
+    session;
+    constructor(session) {
+        this.session = session;
+    }
+    request(message) {
+        return this.session.request(message);
+    }
+}
+exports.BaseService = BaseService;

package/dist/services/ControlService.d.ts

@@ -0,0 +1,33 @@
+import { BaiweiSession } from "../core/BaiweiSession";
+import { BaiweiDeviceState, BaiweiDeviceStateReport, BaiweiProductType, DeviceStateList, MessageResponse } from "../types";
+import { BaseService } from "./BaseService";
+/**
+ * 薄控制层：只负责协议映射，不在 SDK 内维护设备状态缓存。
+ */
+export declare class ControlService extends BaseService {
+    constructor(session: BaiweiSession);
+    /**
+     * 兼容旧命名。
+     * 当前实现不会在 SDK 内同步或缓存状态，只是发起一次查询。
+     */
+    syncDeviceStatesByType<T>(type: BaiweiProductType): Promise<DeviceStateList<T>>;
+    /** 查询某个产品类型下的全部设备状态。 */
+    getDeviceStatesByType<T>(type: BaiweiProductType): Promise<DeviceStateList<T>>;
+    /**
+     * 发送控制命令。
+     */
+    controlDevice<T>(deviceState: BaiweiDeviceState<T>): Promise<unknown>;
+    /**
+     * 在无缓存模式下，查询单个设备状态时需要显式提供设备类型。
+     */
+    getDeviceState<T>(deviceId: string, type?: BaiweiProductType): Promise<BaiweiDeviceState<T> | undefined>;
+    /**
+     * `report` 会由 client/session 原样抛出，业务层可用这个 helper 来识别设备状态上报。
+     */
+    /** 判断一条 report 是否为设备状态上报。 */
+    isDeviceStateReport(message: MessageResponse): message is MessageResponse<BaiweiDeviceStateReport>;
+    /**
+     * 从 report 中提取设备状态；如果不是设备状态上报，则返回 `undefined`。
+     */
+    getReportedDeviceState(message: MessageResponse): BaiweiDeviceState | undefined;
+}

package/dist/services/ControlService.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ControlService = void 0;
+const types_1 = require("../types");
+const BaseService_1 = require("./BaseService");
+/**
+ * 薄控制层：只负责协议映射，不在 SDK 内维护设备状态缓存。
+ */
+class ControlService extends BaseService_1.BaseService {
+    constructor(session) {
+        super(session);
+    }
+    /**
+     * 兼容旧命名。
+     * 当前实现不会在 SDK 内同步或缓存状态，只是发起一次查询。
+     */
+    async syncDeviceStatesByType(type) {
+        return this.getDeviceStatesByType(type);
+    }
+    /** 查询某个产品类型下的全部设备状态。 */
+    async getDeviceStatesByType(type) {
+        return this.request({
+            msgClass: types_1.MsgClass.CONTROL_MGMT,
+            msgName: types_1.MsgName.DEVICE_STATE_GET,
+            payload: { device: { type } },
+        });
+    }
+    /**
+     * 发送控制命令。
+     */
+    async controlDevice(deviceState) {
+        return this.request({
+            msgClass: types_1.MsgClass.CONTROL_MGMT,
+            msgName: types_1.MsgName.DEVICE_CONTROL,
+            msgType: types_1.MsgType.SET,
+            payload: { device: deviceState },
+        });
+    }
+    /**
+     * 在无缓存模式下，查询单个设备状态时需要显式提供设备类型。
+     */
+    async getDeviceState(deviceId, type) {
+        if (!type) {
+            throw new Error("getDeviceState requires a product type in stateless mode.");
+        }
+        const result = await this.getDeviceStatesByType(type);
+        return result.device_list?.find((device) => device.device_id === deviceId);
+    }
+    /**
+     * `report` 会由 client/session 原样抛出，业务层可用这个 helper 来识别设备状态上报。
+     */
+    /** 判断一条 report 是否为设备状态上报。 */
+    isDeviceStateReport(message) {
+        return (message.msgClass === types_1.MsgClass.CONTROL_MGMT &&
+            message.msgName === types_1.MsgName.DEVICE_STATE_REPORT);
+    }
+    /**
+     * 从 report 中提取设备状态；如果不是设备状态上报，则返回 `undefined`。
+     */
+    getReportedDeviceState(message) {
+        if (!this.isDeviceStateReport(message)) {
+            return undefined;
+        }
+        return message.payload.device;
+    }
+}
+exports.ControlService = ControlService;

package/dist/services/DeviceService.d.ts

@@ -0,0 +1,26 @@
+import { BaiweiSession } from "../core/BaiweiSession";
+import { BaiweiDevice, BaiweiProductType, DeviceQuery } from "../types";
+import { BaseService } from "./BaseService";
+/**
+ * 设备目录查询层。
+ * 当前设计不缓存设备列表，每次调用都直接向网关查询。
+ */
+export declare class DeviceService extends BaseService {
+    constructor(session: BaiweiSession);
+    queryDevices(): Promise<DeviceQuery>;
+    /**
+     * 兼容旧命名。
+     * 当前实现不会在 SDK 内缓存设备目录。
+     */
+    syncDevices(): Promise<DeviceQuery>;
+    /** 按产品类型过滤设备。 */
+    getDevicesByType(type: BaiweiProductType): Promise<BaiweiDevice[]>;
+    /**
+     * 查询并拍平全部设备。
+     */
+    listDevices(): Promise<BaiweiDevice[]>;
+    /**
+     * 查询单个设备，不在 SDK 内保留目录缓存。
+     */
+    getDeviceById(deviceId: string): Promise<BaiweiDevice | undefined>;
+}

package/dist/services/DeviceService.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeviceService = void 0;
+const types_1 = require("../types");
+const BaseService_1 = require("./BaseService");
+/**
+ * 设备目录查询层。
+ * 当前设计不缓存设备列表，每次调用都直接向网关查询。
+ */
+class DeviceService extends BaseService_1.BaseService {
+    constructor(session) {
+        super(session);
+    }
+    async queryDevices() {
+        return this.request({
+            msgClass: types_1.MsgClass.DEVICE_MGMT,
+            msgName: types_1.MsgName.DEVICE_QUERY,
+        });
+    }
+    /**
+     * 兼容旧命名。
+     * 当前实现不会在 SDK 内缓存设备目录。
+     */
+    async syncDevices() {
+        return this.queryDevices();
+    }
+    /** 按产品类型过滤设备。 */
+    async getDevicesByType(type) {
+        const response = await this.queryDevices();
+        const matched = response.type_list?.find((item) => item.product_type === type);
+        return matched?.device_list ?? [];
+    }
+    /**
+     * 查询并拍平全部设备。
+     */
+    async listDevices() {
+        const response = await this.queryDevices();
+        return flattenDevices(response.type_list ?? []);
+    }
+    /**
+     * 查询单个设备，不在 SDK 内保留目录缓存。
+     */
+    async getDeviceById(deviceId) {
+        const devices = await this.listDevices();
+        return devices.find((device) => device.device_id === deviceId);
+    }
+}
+exports.DeviceService = DeviceService;
+function flattenDevices(typeList) {
+    return typeList.flatMap((item) => item.device_list ?? []);
+}

package/dist/services/GatewayService.d.ts

@@ -0,0 +1,11 @@
+import { BaiweiSession } from "../core/BaiweiSession";
+import { BaseService } from "./BaseService";
+/** 网关级操作封装，例如允许设备入网。 */
+export declare class GatewayService extends BaseService {
+    constructor(session: BaiweiSession);
+    discovery(): void;
+    /** 打开入网窗口，允许新 Zigbee 设备在指定时间内加入。 */
+    permitZigbeeJoin(time?: number): Promise<unknown>;
+    /** 提前关闭入网窗口。 */
+    stopZigbeeJoin(): Promise<unknown>;
+}