@tier0/sdk-v2 0.0.0-stage → 0.2.1

package/dist/cjs/mq/client.js

@@ -0,0 +1,321 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Tier0MQClient = void 0;
+const mqtt_1 = __importDefault(require("mqtt"));
+const runtime_env_js_1 = require("../runtime-env.js");
+const broker_js_1 = require("./broker.js");
+function parseWorkspaceIDFromApiKey(apiKey) {
+    // Match the backend's sk-<type>-ws<base36>_<secret> contract, not only
+    // service keys. Other workspace-encoded keys use the same MQTT identity.
+    const match = /^sk-[^-]+-ws([0-9a-zA-Z]+)_.+$/.exec(apiKey.trim());
+    if (!match)
+        return undefined;
+    // Keep the int64 workspace ID exact; parseInt can round IDs above 2^53.
+    let workspaceID = 0n;
+    for (const digit of match[1]) {
+        workspaceID = workspaceID * 36n + BigInt(parseInt(digit, 36));
+        if (workspaceID > 9223372036854775807n)
+            return undefined;
+    }
+    return workspaceID > 0n ? workspaceID.toString() : undefined;
+}
+function generateRandomString(length = 8) {
+    const chars = 'abcdefghijklmnopqrstuvwxyz0123456789';
+    let result = '';
+    for (let i = 0; i < length; i++) {
+        result += chars.charAt(Math.floor(Math.random() * chars.length));
+    }
+    return result;
+}
+class Tier0MQClient {
+    client = null;
+    config;
+    explicitClientId;
+    explicitUsername;
+    listeners = {};
+    subscriptions = [];
+    connectingPromise = null;
+    _connected = false;
+    constructor(config) {
+        this.explicitClientId = config?.clientId !== undefined;
+        this.explicitUsername = config?.username !== undefined;
+        const envHost = (0, runtime_env_js_1.getEnvVar)('TIER0_MQTT_HOST');
+        const envPort = (0, runtime_env_js_1.getEnvVar)('TIER0_MQTT_PORT');
+        const host = config?.host || envHost || '';
+        const port = config?.port || parseInt(envPort || '8084') || 8084;
+        const password = config?.password || (0, runtime_env_js_1.getEnvVar)('TIER0_API_KEY') || '';
+        // 从 apiKey 解析 workspaceID，自动生成 clientId 和 username
+        const workspaceID = config?.clientId && config?.username
+            ? undefined
+            : parseWorkspaceIDFromApiKey(password);
+        const autoClientId = workspaceID
+            ? `${workspaceID}&${generateRandomString(8)}`
+            : undefined;
+        const autoUsername = workspaceID
+            ? `${workspaceID}&open`
+            : undefined;
+        this.config = {
+            host,
+            port,
+            clientId: config?.clientId || autoClientId,
+            username: config?.username || autoUsername,
+            password,
+            keepAlive: config?.keepAlive ?? 60,
+            reconnectPeriod: config?.reconnectPeriod ?? 5000,
+            connectTimeout: config?.connectTimeout ?? 30000,
+            clean: config?.clean ?? true,
+            ...config,
+        };
+    }
+    get mqttUrl() {
+        const { host, port, secure } = this.config;
+        if (!host) {
+            throw new Error('MQTT host is required. Provide it via MQTTConfig or TIER0_MQTT_HOST environment variable.');
+        }
+        const normalizedHost = host.trim().replace(/\/+$/, '');
+        if (/^wss?:\/\//i.test(normalizedHost)) {
+            const url = (0, broker_js_1.toWebSocketUrl)(normalizedHost);
+            if (!url)
+                throw new TypeError('Invalid MQTT WebSocket URL');
+            return url;
+        }
+        // 裸 host（可含端口）：按运行环境自适应 ws/wss
+        const endpoint = (0, broker_js_1.parseMqttBroker)(normalizedHost);
+        const hostname = endpoint?.hostname ?? normalizedHost;
+        // 裸 host:port 和 ws(s) URL 的端口按 WebSocket 端口处理；
+        // tcp/mqtt/mqtts 的端口是 TCP 端口（如 1883），wss 下不能沿用，回退到配置的 port
+        const effectivePort = !endpoint?.scheme || endpoint.scheme === 'ws' || endpoint.scheme === 'wss'
+            ? endpoint?.port ?? port
+            : port;
+        const useSecure = secure ?? ((0, broker_js_1.isBrowserHttps)() || effectivePort === broker_js_1.DEFAULT_WSS_PORT);
+        return `${useSecure ? 'wss' : 'ws'}://${hostname}:${effectivePort}/mqtt`;
+    }
+    // 内部确保已连接（懒连接）
+    async ensureConnected() {
+        if (this._connected)
+            return;
+        if (this.connectingPromise)
+            return this.connectingPromise;
+        void this.mqttUrl;
+        if (!this.config.password || !this.config.username || !this.config.clientId) {
+            throw new Error('Tier0 SDK v2: provide a workspace-encoded API key or explicit MQTT username, clientId and password.');
+        }
+        this.connectingPromise = this.doConnect();
+        return this.connectingPromise;
+    }
+    doConnect() {
+        return new Promise((resolve, reject) => {
+            const options = {
+                clientId: this.config.clientId,
+                username: this.config.username,
+                password: this.config.password,
+                keepalive: this.config.keepAlive,
+                reconnectPeriod: this.config.reconnectPeriod,
+                connectTimeout: this.config.connectTimeout,
+                clean: this.config.clean,
+            };
+            this.client = mqtt_1.default.connect(this.mqttUrl, options);
+            this.client.on('connect', () => {
+                this._connected = true;
+                this.connectingPromise = null;
+                this.emit('connect');
+                // 断连重连后自动恢复所有订阅
+                this.resubscribeAll();
+                resolve();
+            });
+            this.client.on('error', (err) => {
+                this.emit('error', err);
+                this.connectingPromise = null;
+                reject(err);
+            });
+            this.client.on('disconnect', () => {
+                this._connected = false;
+                this.emit('disconnect');
+            });
+            this.client.on('close', () => {
+                this._connected = false;
+            });
+            this.client.on('message', (topic, payload, _packet) => {
+                const payloadStr = payload.toString();
+                // 复制一份快照：handler 触发背压自动退订时会重建 this.subscriptions
+                this.subscriptions.slice().forEach((sub) => {
+                    if (this.topicMatch(sub.topic, topic)) {
+                        try {
+                            // 公开类型为 void 返回（兼容 async/简写 handler），运行时仅识别严格的 false
+                            const accepted = sub.handler(topic, payloadStr);
+                            if (accepted === false) {
+                                sub.backpressuredCount = (sub.backpressuredCount ?? 0) + 1;
+                                const limit = this.config.maxBackpressuredDeliveries ?? 0;
+                                if (limit > 0 && sub.backpressuredCount >= limit) {
+                                    this.unsubscribe(sub.topic, sub.handler);
+                                    this.emit('subscriptionDropped', {
+                                        topic: sub.topic,
+                                        reason: `handler 连续 ${sub.backpressuredCount} 次返回背压（false），已按 maxBackpressuredDeliveries=${limit} 自动退订`,
+                                    });
+                                }
+                            }
+                            else {
+                                sub.backpressuredCount = 0;
+                            }
+                        }
+                        catch (e) {
+                            this.emit('error', e);
+                        }
+                    }
+                });
+            });
+        });
+    }
+    // 显式连接（需要等待连接完成时使用）
+    async connect(config) {
+        if (config) {
+            const previousPassword = this.config.password;
+            this.config = { ...this.config, ...config };
+            if (config.clientId !== undefined)
+                this.explicitClientId = true;
+            if (config.username !== undefined)
+                this.explicitUsername = true;
+            // A connect-time key may belong to a different workspace. Preserve only
+            // caller-supplied identity fields, not values derived from the previous key.
+            if (config.password !== undefined && config.password !== previousPassword) {
+                const workspaceID = parseWorkspaceIDFromApiKey(config.password);
+                if (!this.explicitClientId) {
+                    this.config.clientId = workspaceID ? workspaceID + '&' + generateRandomString(8) : undefined;
+                }
+                if (!this.explicitUsername)
+                    this.config.username = workspaceID ? workspaceID + '&open' : undefined;
+            }
+        }
+        return this.ensureConnected();
+    }
+    // 订阅 topic，内部 qos 固定为 1，handler 接收 (topic, payload)
+    // 无需先调用 connect()，自动处理连接
+    subscribe(topic, handler) {
+        // 避免重复注册同一 topic 的同一 handler
+        const exists = this.subscriptions.some((s) => s.topic === topic && s.handler === handler);
+        if (exists) {
+            return;
+        }
+        this.subscriptions.push({ topic, handler });
+        if (this._connected && this.client) {
+            this.client.subscribe(topic, { qos: 1 }, (err) => {
+                if (err) {
+                    this.emit('error', err);
+                    // 订阅失败时回滚
+                    this.subscriptions = this.subscriptions.filter((s) => !(s.topic === topic && s.handler === handler));
+                }
+            });
+        }
+        else {
+            // 未连接时触发懒连接，连接成功后 resubscribeAll 会自动 subscribe
+            this.ensureConnected().catch((err) => this.emit('error', err));
+        }
+    }
+    // 取消订阅：如果提供了 handler 则仅移除该 handler，否则移除该 topic 下所有 handler
+    unsubscribe(topic, handler) {
+        if (handler) {
+            this.subscriptions = this.subscriptions.filter((s) => !(s.topic === topic && s.handler === handler));
+        }
+        else {
+            this.subscriptions = this.subscriptions.filter((s) => s.topic !== topic);
+        }
+        if (!this.client)
+            return;
+        // 如果该 topic 下已无任何 handler，则向 broker 发送 unsubscribe
+        const stillHasHandler = this.subscriptions.some((s) => s.topic === topic);
+        if (!stillHasHandler) {
+            this.client.unsubscribe(topic, (err) => {
+                if (err) {
+                    this.emit('error', err);
+                }
+            });
+        }
+    }
+    // 发布消息，无需先调用 connect()，内部自动处理连接
+    async publish(topic, payload, options) {
+        await this.ensureConnected();
+        const message = typeof payload === 'string' ? payload : JSON.stringify(payload);
+        this.client.publish(topic, message, {
+            qos: (options?.qos ?? 0),
+            retain: options?.retain ?? false,
+        });
+    }
+    disconnect() {
+        if (!this.client)
+            return;
+        this.client.end(true, () => {
+            this.emit('disconnect');
+        });
+        this.client = null;
+        this._connected = false;
+        this.connectingPromise = null;
+        this.subscriptions = [];
+    }
+    on(event, handler) {
+        if (!this.listeners[event]) {
+            this.listeners[event] = [];
+        }
+        this.listeners[event].push(handler);
+    }
+    off(event, handler) {
+        const handlers = this.listeners[event];
+        if (!handlers)
+            return;
+        const idx = handlers.indexOf(handler);
+        if (idx !== -1) {
+            handlers.splice(idx, 1);
+        }
+    }
+    emit(event, ...args) {
+        const handlers = this.listeners[event];
+        if (!handlers)
+            return;
+        handlers.forEach((h) => h(...args));
+    }
+    // 断连后自动重新订阅所有已注册的 topic
+    resubscribeAll() {
+        if (!this.client)
+            return;
+        // 按 topic 去重，每个 topic 只订阅一次
+        const uniqueTopics = Array.from(new Set(this.subscriptions.map((s) => s.topic)));
+        uniqueTopics.forEach((topic) => {
+            this.client.subscribe(topic, { qos: 1 }, (err) => {
+                if (err) {
+                    this.emit('error', err);
+                }
+            });
+        });
+    }
+    // 判断接收到的 topic 是否匹配订阅的 topic（支持通配符 # 和 +）
+    topicMatch(subscribed, received) {
+        const subParts = subscribed.split('/');
+        const recParts = received.split('/');
+        for (let i = 0; i < subParts.length; i++) {
+            const sp = subParts[i];
+            const rp = recParts[i];
+            if (sp === '#') {
+                // # 必须是最后一个层级，匹配后面所有
+                return true;
+            }
+            if (sp === '+') {
+                // + 匹配单个层级
+                continue;
+            }
+            if (sp !== rp) {
+                return false;
+            }
+        }
+        return subParts.length === recParts.length;
+    }
+    get isConnected() {
+        return this._connected;
+    }
+    get subscribedTopics() {
+        return Array.from(new Set(this.subscriptions.map((s) => s.topic)));
+    }
+}
+exports.Tier0MQClient = Tier0MQClient;
+//# sourceMappingURL=client.js.map

package/dist/cjs/mq/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../src/mq/client.ts"],"names":[],"mappings":"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","sourcesContent":["import mqtt from 'mqtt';\nimport type { MqttClient, IClientOptions } from 'mqtt';\nimport { getEnvVar } from '../runtime-env.js';\nimport { DEFAULT_WSS_PORT, isBrowserHttps, parseMqttBroker, toWebSocketUrl } from './broker.js';\nimport type { MQTTConfig, MQTTEventMap } from './types.js';\n\n/**\n * 消息回调。公开类型保持 `void` 返回，以兼容 async handler、`push()` 简写等\n * 既有写法；运行时额外识别返回值：handler 返回严格的 `false` 视为下游停滞\n * （背压），SDK 会统计连续背压次数，配合 MQTTConfig.maxBackpressuredDeliveries\n * 可在阈值内自动移除订阅。\n */\nexport type TopicHandler = (topic: string, payload: string) => void;\n\nfunction parseWorkspaceIDFromApiKey(apiKey: string): string | undefined {\n  // Match the backend's sk-<type>-ws<base36>_<secret> contract, not only\n  // service keys. Other workspace-encoded keys use the same MQTT identity.\n  const match = /^sk-[^-]+-ws([0-9a-zA-Z]+)_.+$/.exec(apiKey.trim());\n  if (!match) return undefined;\n\n  // Keep the int64 workspace ID exact; parseInt can round IDs above 2^53.\n  let workspaceID = 0n;\n  for (const digit of match[1]) {\n    workspaceID = workspaceID * 36n + BigInt(parseInt(digit, 36));\n    if (workspaceID > 9223372036854775807n) return undefined;\n  }\n  return workspaceID > 0n ? workspaceID.toString() : undefined;\n}\n\nfunction generateRandomString(length = 8): string {\n  const chars = 'abcdefghijklmnopqrstuvwxyz0123456789';\n  let result = '';\n  for (let i = 0; i < length; i++) {\n    result += chars.charAt(Math.floor(Math.random() * chars.length));\n  }\n  return result;\n}\n\ninterface Subscription {\n  topic: string;\n  handler: TopicHandler;\n  /** handler 连续返回 false（背压）的次数，正常返回时清零。 */\n  backpressuredCount?: number;\n}\n\nexport class Tier0MQClient {\n  private client: MqttClient | null = null;\n  private config: MQTTConfig;\n  private explicitClientId: boolean;\n  private explicitUsername: boolean;\n  private listeners: { [K in keyof MQTTEventMap]?: Array<MQTTEventMap[K]> } = {};\n  private subscriptions: Subscription[] = [];\n  private connectingPromise: Promise<void> | null = null;\n  private _connected = false;\n\n  constructor(config?: MQTTConfig) {\n    this.explicitClientId = config?.clientId !== undefined;\n    this.explicitUsername = config?.username !== undefined;\n    const envHost = getEnvVar('TIER0_MQTT_HOST');\n    const envPort = getEnvVar('TIER0_MQTT_PORT');\n\n    const host = config?.host || envHost || '';\n    const port = config?.port || parseInt(envPort || '8084') || 8084;\n    const password = config?.password || getEnvVar('TIER0_API_KEY') || '';\n\n    // 从 apiKey 解析 workspaceID，自动生成 clientId 和 username\n    const workspaceID = config?.clientId && config?.username\n      ? undefined\n      : parseWorkspaceIDFromApiKey(password);\n\n    const autoClientId = workspaceID\n      ? `${workspaceID}&${generateRandomString(8)}`\n      : undefined;\n    const autoUsername = workspaceID\n      ? `${workspaceID}&open`\n      : undefined;\n\n    this.config = {\n      host,\n      port,\n      clientId: config?.clientId || autoClientId,\n      username: config?.username || autoUsername,\n      password,\n      keepAlive: config?.keepAlive ?? 60,\n      reconnectPeriod: config?.reconnectPeriod ?? 5000,\n      connectTimeout: config?.connectTimeout ?? 30000,\n      clean: config?.clean ?? true,\n      ...config,\n    };\n  }\n\n  private get mqttUrl(): string {\n    const { host, port, secure } = this.config;\n    if (!host) {\n      throw new Error(\n        'MQTT host is required. Provide it via MQTTConfig or TIER0_MQTT_HOST environment variable.'\n      );\n    }\n    const normalizedHost = host.trim().replace(/\\/+$/, '');\n    if (/^wss?:\\/\\//i.test(normalizedHost)) {\n      const url = toWebSocketUrl(normalizedHost);\n      if (!url) throw new TypeError('Invalid MQTT WebSocket URL');\n      return url;\n    }\n    // 裸 host（可含端口）：按运行环境自适应 ws/wss\n    const endpoint = parseMqttBroker(normalizedHost);\n    const hostname = endpoint?.hostname ?? normalizedHost;\n    // 裸 host:port 和 ws(s) URL 的端口按 WebSocket 端口处理；\n    // tcp/mqtt/mqtts 的端口是 TCP 端口（如 1883），wss 下不能沿用，回退到配置的 port\n    const effectivePort =\n      !endpoint?.scheme || endpoint.scheme === 'ws' || endpoint.scheme === 'wss'\n        ? endpoint?.port ?? port\n        : port;\n    const useSecure = secure ?? (isBrowserHttps() || effectivePort === DEFAULT_WSS_PORT);\n    return `${useSecure ? 'wss' : 'ws'}://${hostname}:${effectivePort}/mqtt`;\n  }\n\n  // 内部确保已连接（懒连接）\n  private async ensureConnected(): Promise<void> {\n    if (this._connected) return;\n    if (this.connectingPromise) return this.connectingPromise;\n\n    void this.mqttUrl;\n    if (!this.config.password || !this.config.username || !this.config.clientId) {\n      throw new Error('Tier0 SDK v2: provide a workspace-encoded API key or explicit MQTT username, clientId and password.');\n    }\n\n    this.connectingPromise = this.doConnect();\n    return this.connectingPromise;\n  }\n\n  private doConnect(): Promise<void> {\n    return new Promise((resolve, reject) => {\n      const options: IClientOptions = {\n        clientId: this.config.clientId,\n        username: this.config.username,\n        password: this.config.password,\n        keepalive: this.config.keepAlive,\n        reconnectPeriod: this.config.reconnectPeriod,\n        connectTimeout: this.config.connectTimeout,\n        clean: this.config.clean,\n      };\n\n      this.client = mqtt.connect(this.mqttUrl, options);\n\n      this.client.on('connect', () => {\n        this._connected = true;\n        this.connectingPromise = null;\n        this.emit('connect');\n        // 断连重连后自动恢复所有订阅\n        this.resubscribeAll();\n        resolve();\n      });\n\n      this.client.on('error', (err) => {\n        this.emit('error', err);\n        this.connectingPromise = null;\n        reject(err);\n      });\n\n      this.client.on('disconnect', () => {\n        this._connected = false;\n        this.emit('disconnect');\n      });\n\n      this.client.on('close', () => {\n        this._connected = false;\n      });\n\n      this.client.on(\n        'message',\n        (topic: string, payload: Buffer, _packet: mqtt.IPublishPacket) => {\n          const payloadStr = payload.toString();\n          // 复制一份快照：handler 触发背压自动退订时会重建 this.subscriptions\n          this.subscriptions.slice().forEach((sub) => {\n            if (this.topicMatch(sub.topic, topic)) {\n              try {\n                // 公开类型为 void 返回（兼容 async/简写 handler），运行时仅识别严格的 false\n                const accepted = (\n                  sub.handler as (t: string, p: string) => unknown\n                )(topic, payloadStr);\n                if (accepted === false) {\n                  sub.backpressuredCount = (sub.backpressuredCount ?? 0) + 1;\n                  const limit = this.config.maxBackpressuredDeliveries ?? 0;\n                  if (limit > 0 && sub.backpressuredCount >= limit) {\n                    this.unsubscribe(sub.topic, sub.handler);\n                    this.emit('subscriptionDropped', {\n                      topic: sub.topic,\n                      reason: `handler 连续 ${sub.backpressuredCount} 次返回背压（false），已按 maxBackpressuredDeliveries=${limit} 自动退订`,\n                    });\n                  }\n                } else {\n                  sub.backpressuredCount = 0;\n                }\n              } catch (e) {\n                this.emit('error', e as Error);\n              }\n            }\n          });\n        }\n      );\n    });\n  }\n\n  // 显式连接（需要等待连接完成时使用）\n  async connect(config?: MQTTConfig): Promise<void> {\n    if (config) {\n      const previousPassword = this.config.password;\n      this.config = { ...this.config, ...config };\n      if (config.clientId !== undefined) this.explicitClientId = true;\n      if (config.username !== undefined) this.explicitUsername = true;\n      // A connect-time key may belong to a different workspace. Preserve only\n      // caller-supplied identity fields, not values derived from the previous key.\n      if (config.password !== undefined && config.password !== previousPassword) {\n        const workspaceID = parseWorkspaceIDFromApiKey(config.password);\n        if (!this.explicitClientId) {\n          this.config.clientId = workspaceID ? workspaceID + '&' + generateRandomString(8) : undefined;\n        }\n        if (!this.explicitUsername) this.config.username = workspaceID ? workspaceID + '&open' : undefined;\n      }\n    }\n    return this.ensureConnected();\n  }\n\n  // 订阅 topic，内部 qos 固定为 1，handler 接收 (topic, payload)\n  // 无需先调用 connect()，自动处理连接\n  subscribe(topic: string, handler: TopicHandler): void {\n    // 避免重复注册同一 topic 的同一 handler\n    const exists = this.subscriptions.some(\n      (s) => s.topic === topic && s.handler === handler\n    );\n    if (exists) {\n      return;\n    }\n\n    this.subscriptions.push({ topic, handler });\n\n    if (this._connected && this.client) {\n      this.client.subscribe(topic, { qos: 1 as 0 | 1 | 2 }, (err) => {\n        if (err) {\n          this.emit('error', err);\n          // 订阅失败时回滚\n          this.subscriptions = this.subscriptions.filter(\n            (s) => !(s.topic === topic && s.handler === handler)\n          );\n        }\n      });\n    } else {\n      // 未连接时触发懒连接，连接成功后 resubscribeAll 会自动 subscribe\n      this.ensureConnected().catch((err) => this.emit('error', err));\n    }\n  }\n\n  // 取消订阅：如果提供了 handler 则仅移除该 handler，否则移除该 topic 下所有 handler\n  unsubscribe(topic: string, handler?: TopicHandler): void {\n    if (handler) {\n      this.subscriptions = this.subscriptions.filter(\n        (s) => !(s.topic === topic && s.handler === handler)\n      );\n    } else {\n      this.subscriptions = this.subscriptions.filter((s) => s.topic !== topic);\n    }\n\n    if (!this.client) return;\n\n    // 如果该 topic 下已无任何 handler，则向 broker 发送 unsubscribe\n    const stillHasHandler = this.subscriptions.some((s) => s.topic === topic);\n    if (!stillHasHandler) {\n      this.client.unsubscribe(topic, (err) => {\n        if (err) {\n          this.emit('error', err);\n        }\n      });\n    }\n  }\n\n  // 发布消息，无需先调用 connect()，内部自动处理连接\n  async publish(\n    topic: string,\n    payload: string | object,\n    options?: { qos?: number; retain?: boolean }\n  ): Promise<void> {\n    await this.ensureConnected();\n\n    const message =\n      typeof payload === 'string' ? payload : JSON.stringify(payload);\n    this.client!.publish(topic, message, {\n      qos: (options?.qos ?? 0) as 0 | 1 | 2,\n      retain: options?.retain ?? false,\n    });\n  }\n\n  disconnect(): void {\n    if (!this.client) return;\n\n    this.client.end(true, () => {\n      this.emit('disconnect');\n    });\n    this.client = null;\n    this._connected = false;\n    this.connectingPromise = null;\n    this.subscriptions = [];\n  }\n\n  on<K extends keyof MQTTEventMap>(event: K, handler: MQTTEventMap[K]): void {\n    if (!this.listeners[event]) {\n      this.listeners[event] = [];\n    }\n    this.listeners[event]!.push(handler);\n  }\n\n  off<K extends keyof MQTTEventMap>(event: K, handler: MQTTEventMap[K]): void {\n    const handlers = this.listeners[event];\n    if (!handlers) return;\n    const idx = handlers.indexOf(handler);\n    if (idx !== -1) {\n      handlers.splice(idx, 1);\n    }\n  }\n\n  private emit<K extends keyof MQTTEventMap>(\n    event: K,\n    ...args: Parameters<MQTTEventMap[K]>\n  ): void {\n    const handlers = this.listeners[event];\n    if (!handlers) return;\n    handlers.forEach((h) => (h as any)(...args));\n  }\n\n  // 断连后自动重新订阅所有已注册的 topic\n  private resubscribeAll(): void {\n    if (!this.client) return;\n\n    // 按 topic 去重，每个 topic 只订阅一次\n    const uniqueTopics = Array.from(\n      new Set(this.subscriptions.map((s) => s.topic))\n    );\n    uniqueTopics.forEach((topic) => {\n      this.client!.subscribe(topic, { qos: 1 as 0 | 1 | 2 }, (err) => {\n        if (err) {\n          this.emit('error', err);\n        }\n      });\n    });\n  }\n\n  // 判断接收到的 topic 是否匹配订阅的 topic（支持通配符 # 和 +）\n  private topicMatch(subscribed: string, received: string): boolean {\n    const subParts = subscribed.split('/');\n    const recParts = received.split('/');\n\n    for (let i = 0; i < subParts.length; i++) {\n      const sp = subParts[i];\n      const rp = recParts[i];\n\n      if (sp === '#') {\n        // # 必须是最后一个层级，匹配后面所有\n        return true;\n      }\n      if (sp === '+') {\n        // + 匹配单个层级\n        continue;\n      }\n      if (sp !== rp) {\n        return false;\n      }\n    }\n\n    return subParts.length === recParts.length;\n  }\n\n  get isConnected(): boolean {\n    return this._connected;\n  }\n\n  get subscribedTopics(): string[] {\n    return Array.from(new Set(this.subscriptions.map((s) => s.topic)));\n  }\n}\n"]}

package/dist/cjs/mq/index.d.ts

@@ -0,0 +1,5 @@
+export { Tier0MQClient } from './client.js';
+export type { TopicHandler } from './client.js';
+export { parseMqttBroker, toWebSocketUrl, DEFAULT_WSS_PORT, DEFAULT_WS_PATH, } from './broker.js';
+export type { MqttBrokerEndpoint, ToWebSocketUrlOptions } from './broker.js';
+export type { MQTTConfig, MQTTMessage, MQTTEventMap } from './types.js';

package/dist/cjs/mq/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_WS_PATH = exports.DEFAULT_WSS_PORT = exports.toWebSocketUrl = exports.parseMqttBroker = exports.Tier0MQClient = void 0;
+var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "Tier0MQClient", { enumerable: true, get: function () { return client_js_1.Tier0MQClient; } });
+var broker_js_1 = require("./broker.js");
+Object.defineProperty(exports, "parseMqttBroker", { enumerable: true, get: function () { return broker_js_1.parseMqttBroker; } });
+Object.defineProperty(exports, "toWebSocketUrl", { enumerable: true, get: function () { return broker_js_1.toWebSocketUrl; } });
+Object.defineProperty(exports, "DEFAULT_WSS_PORT", { enumerable: true, get: function () { return broker_js_1.DEFAULT_WSS_PORT; } });
+Object.defineProperty(exports, "DEFAULT_WS_PATH", { enumerable: true, get: function () { return broker_js_1.DEFAULT_WS_PATH; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/mq/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/mq/index.ts"],"names":[],"mappings":";;;AAAA,yCAA4C;AAAnC,0GAAA,aAAa,OAAA;AAEtB,yCAKqB;AAJnB,4GAAA,eAAe,OAAA;AACf,2GAAA,cAAc,OAAA;AACd,6GAAA,gBAAgB,OAAA;AAChB,4GAAA,eAAe,OAAA","sourcesContent":["export { Tier0MQClient } from './client.js';\nexport type { TopicHandler } from './client.js';\nexport {\n  parseMqttBroker,\n  toWebSocketUrl,\n  DEFAULT_WSS_PORT,\n  DEFAULT_WS_PATH,\n} from './broker.js';\nexport type { MqttBrokerEndpoint, ToWebSocketUrlOptions } from './broker.js';\nexport type { MQTTConfig, MQTTMessage, MQTTEventMap } from './types.js';\n"]}

package/dist/cjs/mq/types.d.ts

@@ -0,0 +1,48 @@
+export interface MQTTConfig {
+    /**
+     * broker 地址。支持三种形态：
+     * - 完整 WebSocket URL，如 `wss://host:8084/mqtt`（推荐浏览器场景显式使用）；
+     * - 裸 `host`（可含端口，如 `host:8084`）；
+     * - 平台 `/openapi/v1/info` 返回的原始 `mqttBroker`（如 `tcp://host:1883`，
+     *   建议先用 {@link toWebSocketUrl} 归一后再传入，见 `@tier0/sdk-v2/mq` 的 broker 工具）。
+     */
+    host?: string;
+    /** WebSocket port fallback when host has no embedded WebSocket port. */
+    port?: number;
+    /**
+     * 当 host 不带 ws(s) scheme 时，显式指定用 wss(true) 还是 ws(false)。
+     * 缺省自适应：浏览器 https 页面或端口 8084 用 wss，其余用 ws。
+     */
+    secure?: boolean;
+    clientId?: string;
+    username?: string;
+    /** Original API key; connect-time changes refresh automatically derived identity fields. */
+    password?: string;
+    keepAlive?: number;
+    reconnectPeriod?: number;
+    connectTimeout?: number;
+    clean?: boolean;
+    /**
+     * 背压保护阈值：handler 连续返回 false（表示下游停滞/消费者已断开）达到
+     * 该次数后，SDK 自动移除该订阅并向 broker 退订，避免消息在无消费者的
+     * 应用内队列中持续堆积。0 或不设置表示关闭该保护（保持原有行为）。
+     */
+    maxBackpressuredDeliveries?: number;
+}
+export type MQTTMessage = {
+    topic: string;
+    payload: string | Buffer;
+    qos: number;
+    retain: boolean;
+};
+export type MQTTEventMap = {
+    connect: () => void;
+    disconnect: () => void;
+    error: (error: Error) => void;
+    message: (message: MQTTMessage) => void;
+    /** 订阅因持续背压被 SDK 自动移除时触发。 */
+    subscriptionDropped: (info: {
+        topic: string;
+        reason: string;
+    }) => void;
+};

package/dist/cjs/mq/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/cjs/mq/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/mq/types.ts"],"names":[],"mappings":"","sourcesContent":["export interface MQTTConfig {\n  /**\n   * broker 地址。支持三种形态：\n   * - 完整 WebSocket URL，如 `wss://host:8084/mqtt`（推荐浏览器场景显式使用）；\n   * - 裸 `host`（可含端口，如 `host:8084`）；\n   * - 平台 `/openapi/v1/info` 返回的原始 `mqttBroker`（如 `tcp://host:1883`，\n   *   建议先用 {@link toWebSocketUrl} 归一后再传入，见 `@tier0/sdk-v2/mq` 的 broker 工具）。\n   */\n  host?: string;\n  /** WebSocket port fallback when host has no embedded WebSocket port. */\n  port?: number;\n  /**\n   * 当 host 不带 ws(s) scheme 时，显式指定用 wss(true) 还是 ws(false)。\n   * 缺省自适应：浏览器 https 页面或端口 8084 用 wss，其余用 ws。\n   */\n  secure?: boolean;\n  clientId?: string;\n  username?: string;\n  /** Original API key; connect-time changes refresh automatically derived identity fields. */\n  password?: string;\n  keepAlive?: number;\n  reconnectPeriod?: number;\n  connectTimeout?: number;\n  clean?: boolean;\n  /**\n   * 背压保护阈值：handler 连续返回 false（表示下游停滞/消费者已断开）达到\n   * 该次数后，SDK 自动移除该订阅并向 broker 退订，避免消息在无消费者的\n   * 应用内队列中持续堆积。0 或不设置表示关闭该保护（保持原有行为）。\n   */\n  maxBackpressuredDeliveries?: number;\n}\n\nexport type MQTTMessage = {\n  topic: string;\n  payload: string | Buffer;\n  qos: number;\n  retain: boolean;\n};\n\nexport type MQTTEventMap = {\n  connect: () => void;\n  disconnect: () => void;\n  error: (error: Error) => void;\n  message: (message: MQTTMessage) => void;\n  /** 订阅因持续背压被 SDK 自动移除时触发。 */\n  subscriptionDropped: (info: { topic: string; reason: string }) => void;\n};\n"]}