@jiangtaste/baiwei-sdk 1.0.0

package/dist/core/BaiweiSession.js

@@ -0,0 +1,229 @@
+"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 MessageAssembler_1 = require("./MessageAssembler");
+const PendingRequestStore_1 = require("./PendingRequestStore");
+const SessionConnector_1 = require("./SessionConnector");
+const TcpClient_1 = require("../transport/TcpClient");
+const types_1 = require("../types");
+const MessageIdGenerator_1 = require("../utils/MessageIdGenerator");
+const logger_1 = require("../utils/logger");
+/**
+ * 会话编排层。
+ * 负责连接、请求派发、响应匹配、分片合并和 report 转发。
+ */
+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 MessageIdGenerator_1.MessageIdGenerator();
+    pending = new PendingRequestStore_1.PendingRequestStore();
+    assembler;
+    connector;
+    constructor(options) {
+        super();
+        this.log = (0, logger_1.createLogger)(options.logger);
+        this.options = options;
+        this.tcp = new TcpClient_1.TcpClient({ ...this.options });
+        this.assembler = new MessageAssembler_1.MessageAssembler(this.options.timeoutMs, (msgId, label) => this.emitError(`Partial payload expired: msgId=${msgId}, ${label}`));
+        this.connector = new SessionConnector_1.SessionConnector(this.tcp, this.log, (error) => {
+            this.emit("error", error);
+        });
+        this.bindTcpListeners();
+    }
+    /** 返回 TCP 层当前是否可用。 */
+    isConnected() {
+        return this.tcp.isConnected();
+    }
+    /** 幂等连接：重复调用时复用同一个连接过程。 */
+    connect() {
+        if (this.isConnected()) {
+            return Promise.resolve();
+        }
+        if (this.connecting) {
+            return this.connecting;
+        }
+        this.connecting = this.connector.connect().finally(() => {
+            this.connecting = undefined;
+        });
+        return this.connecting;
+    }
+    /** 登录成功后保存 token，后续请求会自动带上。 */
+    updateToken(token) {
+        this.token = token;
+    }
+    disconnect() {
+        if (!this.isConnected() && !this.connecting) {
+            this.clearRuntimeState(new Error("Session disconnected"));
+            return;
+        }
+        this.connecting = undefined;
+        this.tcp.disconnect();
+    }
+    /** 构造协议请求并注册 pending，等待后续 response 匹配回填。 */
+    request(req) {
+        const msgId = this.idGenerator.next();
+        const message = this.createMessage(req, msgId);
+        return new Promise(async (resolve, reject) => {
+            const timeoutTimer = setTimeout(() => {
+                this.pending.delete(msgId);
+                const error = new Error(`Request timeout: msgClass/msgName=${req.msgClass}/${req.msgName}, msgId=${msgId}`);
+                this.log.info("TCP request timeout:", error);
+                reject(error);
+            }, this.options.timeoutMs);
+            this.pending.set(msgId, {
+                resolve: (value) => resolve(value),
+                reject,
+                timeoutTimer,
+            });
+            try {
+                await this.tcp.send(message);
+            }
+            catch (error) {
+                this.pending.delete(msgId);
+                this.log.info("Send failed:", error);
+                reject(error);
+            }
+        });
+    }
+    /** 把 SDK 内部请求结构转换成网关协议报文。 */
+    createMessage(req, msgId) {
+        return {
+            api_version: "0.1",
+            appId: types_1.DEFAULT_APP_ID,
+            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,
+            ...req.payload,
+        };
+    }
+    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) {
+        this.pending.rejectAll(reason);
+        this.assembler.clearAll();
+    }
+    /** 统一处理来自 TCP 层的完整 JSON 消息。 */
+    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}`);
+        if (!this.validateMessage(message, from, msg_id)) {
+            return;
+        }
+        if (status !== 0) {
+            this.handleGatewayError(msg_id, status, msg_class, msg_name);
+            return;
+        }
+        const finalPayload = this.handleFragmentation(msg_id, payload, end, msg_class, msg_name);
+        if (!finalPayload) {
+            return;
+        }
+        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);
+    }
+    /** 只接受来自目标网关且带有合法 msg_id 的消息。 */
+    validateMessage(message, from, msgId) {
+        if (from !== this.options.gatewaySN) {
+            this.emitError(`Invalid gatewaySN, got ${from}, expected: ${this.options.gatewaySN}`);
+            return false;
+        }
+        if (!msgId) {
+            this.emitError(`Invalid msgId, got ${msgId}`);
+            return false;
+        }
+        return true;
+    }
+    /** 网关返回非 0 状态码时，优先回填给对应请求。 */
+    handleGatewayError(msgId, status, msgClass, msgName) {
+        const pending = this.pending.get(msgId);
+        if (pending) {
+            this.pending.delete(msgId);
+            pending.reject(new Error(`Gateway status=${status}, msgClass/msgName=${msgClass}/${msgName}, msgId=${msgId}`));
+        }
+        else {
+            this.emitError(`Gateway status=${status}, unmatched msgId=${msgId}, msgClass/msgName=${msgClass}/${msgName}`);
+        }
+    }
+    /** 分片逻辑委托给 assembler，session 只保留编排职责。 */
+    handleFragmentation(msgId, payload, end, msgClass, msgName) {
+        return this.assembler.append(msgId, payload, end, `msgClass/msgName=${msgClass}/${msgName}`);
+    }
+    /** 按消息类型分发到 response/report 两条处理链。 */
+    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;
+        }
+    }
+    /** response 通过 msgId 命中 pending 请求并完成 Promise。 */
+    handleResponse(res) {
+        const { msgId: msg_id, payload } = res;
+        const pending = this.pending.get(msg_id);
+        if (!pending)
+            return;
+        this.pending.delete(msg_id);
+        this.log.info("RESPONSE =====>", JSON.stringify(payload));
+        pending.resolve(payload);
+    }
+    /** report 不做状态缓存，保持原样向上层抛出。 */
+    handleReport(res) {
+        this.log.info("REPORT =====>", JSON.stringify(res.payload));
+        this.emit("report", res);
+    }
+    /** 统一发出 Error 对象，避免到处重复 new Error。 */
+    emitError(message) {
+        this.emit("error", new Error(message));
+    }
+}
+exports.BaiweiSession = BaiweiSession;

package/dist/core/Client.d.ts

@@ -0,0 +1,74 @@
+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";
+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);
+    /**
+     * Connect to the gateway.
+     *
+     * @throws {Error} If connection fails or times out
+     *
+     * @example
+     * ```typescript
+     * // Recommended: Always use try-catch or .catch()
+     * try {
+     *   await client.connect();
+     * } catch (error) {
+     *   console.error('Connection failed:', error);
+     *   // Handle error gracefully
+     * }
+     *
+     * // Or use .catch()
+     * client.connect().catch((error) => {
+     *   console.error('Connection failed:', error);
+     * });
+     * ```
+     */
+    /**
+     * Check if the client is currently connected.
+     */
+    isConnected(): boolean;
+    connect(): Promise<void>;
+    /**
+     * Safely connect to the gateway without throwing errors.
+     * Errors are emitted as 'error' events instead.
+     *
+     * @returns {Promise<boolean>} true if connected successfully, false otherwise
+     *
+     * @example
+     * ```typescript
+     * // Use this if you don't want to handle exceptions
+     * const connected = await client.connectSafe();
+     * if (connected) {
+     *   console.log('Connected successfully');
+     * } else {
+     *   console.log('Connection failed, check error event');
+     * }
+     *
+     * client.on('error', (error) => {
+     *   console.error('Connection error:', error);
+     * });
+     * ```
+     */
+    connectSafe(): Promise<boolean>;
+    disconnect(): void;
+    request<T>(message: MessageRequest): Promise<T>;
+}

package/dist/core/Client.js

@@ -0,0 +1,127 @@
+"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 logger_1 = require("../utils/logger");
+const Session_1 = require("./Session");
+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 Session_1.BaiweiSession({
+            ...options,
+            clientId: options.clientId ?? "baiwei-sdk",
+            timeoutMs: options.timeoutMs ?? 5_000,
+            logger: this.log,
+        });
+        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;
+    }
+    /**
+     * Connect to the gateway.
+     *
+     * @throws {Error} If connection fails or times out
+     *
+     * @example
+     * ```typescript
+     * // Recommended: Always use try-catch or .catch()
+     * try {
+     *   await client.connect();
+     * } catch (error) {
+     *   console.error('Connection failed:', error);
+     *   // Handle error gracefully
+     * }
+     *
+     * // Or use .catch()
+     * client.connect().catch((error) => {
+     *   console.error('Connection failed:', error);
+     * });
+     * ```
+     */
+    /**
+     * Check if the client is currently connected.
+     */
+    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;
+        }
+    }
+    /**
+     * Safely connect to the gateway without throwing errors.
+     * Errors are emitted as 'error' events instead.
+     *
+     * @returns {Promise<boolean>} true if connected successfully, false otherwise
+     *
+     * @example
+     * ```typescript
+     * // Use this if you don't want to handle exceptions
+     * const connected = await client.connectSafe();
+     * if (connected) {
+     *   console.log('Connected successfully');
+     * } else {
+     *   console.log('Connection failed, check error event');
+     * }
+     *
+     * client.on('error', (error) => {
+     *   console.error('Connection error:', error);
+     * });
+     * ```
+     */
+    async connectSafe() {
+        try {
+            await this.connect();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    disconnect() {
+        this.session.disconnect();
+    }
+    request(message) {
+        return this.session.request(message);
+    }
+}
+exports.BaiweiClient = BaiweiClient;

package/dist/core/MessageAssembler.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 负责把同一 msgId 的多段 payload 合并为完整消息。
+ * 这里不关心协议语义，只处理“分片”和“过期”。
+ */
+export declare class MessageAssembler {
+    private readonly timeoutMs;
+    private readonly onExpired;
+    private readonly partialPayloads;
+    constructor(timeoutMs: number, onExpired: (msgId: string, label: string) => void);
+    /** `end === 1` 表示最后一片，否则继续缓存并等待后续分片。 */
+    append(msgId: string, payload: Record<string, unknown>, end: number, label: string): Record<string, unknown> | null;
+    /** 断线或重置时统一清掉所有分片缓存。 */
+    clearAll(): void;
+    private clear;
+    /** 递归合并对象，数组则做追加，适配网关分片返回的常见结构。 */
+    private merge;
+}

package/dist/core/MessageAssembler.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MessageAssembler = void 0;
+/**
+ * 负责把同一 msgId 的多段 payload 合并为完整消息。
+ * 这里不关心协议语义，只处理“分片”和“过期”。
+ */
+class MessageAssembler {
+    timeoutMs;
+    onExpired;
+    partialPayloads = new Map();
+    constructor(timeoutMs, onExpired) {
+        this.timeoutMs = timeoutMs;
+        this.onExpired = onExpired;
+    }
+    /** `end === 1` 表示最后一片，否则继续缓存并等待后续分片。 */
+    append(msgId, payload, end, label) {
+        if (end === 1) {
+            const prev = this.partialPayloads.get(msgId);
+            if (!prev) {
+                return payload;
+            }
+            this.clear(msgId, prev);
+            return this.merge(prev.payload, payload);
+        }
+        const prev = this.partialPayloads.get(msgId);
+        if (prev) {
+            prev.payload = this.merge(prev.payload, payload);
+            return null;
+        }
+        const timer = setTimeout(() => {
+            const entry = this.partialPayloads.get(msgId);
+            if (!entry) {
+                return;
+            }
+            this.clear(msgId, entry);
+            this.onExpired(msgId, label);
+        }, this.timeoutMs);
+        this.partialPayloads.set(msgId, { payload, timer });
+        return null;
+    }
+    /** 断线或重置时统一清掉所有分片缓存。 */
+    clearAll() {
+        for (const [msgId, entry] of this.partialPayloads.entries()) {
+            this.clear(msgId, entry);
+        }
+    }
+    clear(msgId, entry) {
+        clearTimeout(entry.timer);
+        this.partialPayloads.delete(msgId);
+    }
+    /** 递归合并对象，数组则做追加，适配网关分片返回的常见结构。 */
+    merge(prev, curr) {
+        const result = { ...prev };
+        for (const key of Object.keys(curr)) {
+            const prevValue = result[key];
+            const currValue = curr[key];
+            if (prevValue &&
+                currValue &&
+                typeof prevValue === "object" &&
+                typeof currValue === "object" &&
+                !Array.isArray(prevValue) &&
+                !Array.isArray(currValue)) {
+                result[key] = this.merge(prevValue, currValue);
+                continue;
+            }
+            if (Array.isArray(prevValue) && Array.isArray(currValue)) {
+                result[key] = [...prevValue, ...currValue];
+                continue;
+            }
+            result[key] = currValue;
+        }
+        return result;
+    }
+}
+exports.MessageAssembler = MessageAssembler;

package/dist/core/PendingRequestStore.d.ts

@@ -0,0 +1,18 @@
+interface PendingRequest<T = unknown> {
+    resolve: (value: T) => void;
+    reject: (reason?: unknown) => void;
+    timeoutTimer: NodeJS.Timeout;
+}
+/**
+ * 维护“请求 msgId -> Promise 回调”的映射。
+ * session 只通过它做增删查和批量拒绝。
+ */
+export declare class PendingRequestStore {
+    private readonly pending;
+    set<T>(msgId: string, entry: PendingRequest<T>): void;
+    get<T>(msgId: string): PendingRequest<T> | undefined;
+    delete(msgId: string): void;
+    /** 断线时批量拒绝所有未完成请求，避免上层永久等待。 */
+    rejectAll(reason: unknown): void;
+}
+export {};

package/dist/core/PendingRequestStore.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PendingRequestStore = void 0;
+/**
+ * 维护“请求 msgId -> Promise 回调”的映射。
+ * session 只通过它做增删查和批量拒绝。
+ */
+class PendingRequestStore {
+    pending = new Map();
+    set(msgId, entry) {
+        this.pending.set(msgId, entry);
+    }
+    get(msgId) {
+        return this.pending.get(msgId);
+    }
+    delete(msgId) {
+        const pending = this.pending.get(msgId);
+        if (!pending) {
+            return;
+        }
+        clearTimeout(pending.timeoutTimer);
+        this.pending.delete(msgId);
+    }
+    /** 断线时批量拒绝所有未完成请求，避免上层永久等待。 */
+    rejectAll(reason) {
+        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();
+    }
+}
+exports.PendingRequestStore = PendingRequestStore;

package/dist/core/Session.d.ts

@@ -0,0 +1,43 @@
+import EventEmitter from "events";
+import { BaiweiSessionOptions, MessageRequest } from "../types";
+export declare class BaiweiSession extends EventEmitter {
+    private tcp;
+    private options;
+    private log;
+    private listenersAttached;
+    private token?;
+    private connecting?;
+    private onTcpMessage;
+    private onTcpConnected;
+    private onTcpDisconnect;
+    private onTcpError;
+    private onTcpProtocolError;
+    private idGenerator;
+    private pending;
+    private partialPayloads;
+    constructor(options: BaiweiSessionOptions);
+    /**
+     * Check if the session is currently connected.
+     */
+    isConnected(): boolean;
+    /**
+     * Establish TCP connection.
+     * Returns existing promise if connection is already in progress.
+     * If already connected, returns a resolved promise.
+     */
+    connect(): Promise<void>;
+    updateToken(token?: string): void;
+    disconnect(): void;
+    request<T>(req: MessageRequest): Promise<T>;
+    private handleDisconnect;
+    private bindTcpListeners;
+    private clearRuntimeState;
+    private onMessage;
+    private validateMessage;
+    private handleGatewayError;
+    private handleFragmentation;
+    private mergePayload;
+    private handleMessageResponse;
+    private handleResponse;
+    private handleReport;
+}