@tier0/sdk-v2 0.0.0-stage → 0.2.1

package/dist/cjs/files.d.ts

@@ -0,0 +1,67 @@
+import { HttpClient, type ClientConfig, type RequestOptions } from './openapi/client.js';
+import type { components } from './openapi/types.generated.js';
+type Schemas = components['schemas'];
+export type UploadOptions = Omit<Schemas['AssetFileUploadReq'], 'fileName' | 'contentType' | 'size'> & RequestOptions;
+export type UploadResult = Schemas['AssetFileUploadResp'];
+export type MultipartResult = Schemas['AssetFileMultipartCompleteResp'];
+export interface MultipartOptions extends UploadOptions {
+    partSize?: number;
+    onProgress?: (progress: {
+        uploadedBytes: number;
+        totalBytes: number;
+    }) => void;
+}
+export interface MultipartSession {
+    fileKey: string;
+    uploadId: string;
+    parts: Schemas['AssetFileMultipartPart'][];
+    completionAttempted: boolean;
+}
+export declare class MultipartUploadError extends Error {
+    readonly session: MultipartSession;
+    readonly cause: unknown;
+    constructor(session: MultipartSession, cause: unknown);
+}
+export declare const MULTIPART_THRESHOLD_BYTES: number;
+export declare const DEFAULT_MULTIPART_PART_SIZE: number;
+/** All platform requests are scoped to this instance; storage requests never carry its API key. */
+export declare class FilesClient {
+    private readonly http;
+    private readonly api;
+    readonly multipart: {
+        abort: (body: components["schemas"]["SdkassetsFilesMultipartAbortRequest"], options?: RequestOptions) => Promise<{
+            aborted: number | bigint;
+        }>;
+        complete: (body: components["schemas"]["SdkassetsFilesMultipartCompleteRequest"], options?: RequestOptions) => Promise<{
+            expiresAt?: number | bigint;
+            filePath: string;
+            fileUrl?: string;
+            sizeBytes: number | bigint;
+        }>;
+        init: (body: components["schemas"]["SdkassetsFilesMultipartInitRequest"], options?: RequestOptions) => Promise<{
+            expiresAt: number | bigint;
+            fileKey: string;
+            filePath: string;
+            partCount: number | bigint;
+            partSize: number | bigint;
+            uploadId: string;
+        }>;
+        partUrls: (body: components["schemas"]["SdkassetsFilesMultipartPartUrlsRequest"], options?: RequestOptions) => Promise<{
+            partUrls: components["schemas"]["AssetFileMultipartPartUrl"][];
+        }>;
+    };
+    constructor(http: HttpClient);
+    private storage;
+    upload(file: File, options?: UploadOptions): Promise<UploadResult | MultipartResult>;
+    uploadMultipart(file: File, options?: MultipartOptions): Promise<MultipartResult>;
+    url(query: Parameters<typeof this.api.url>[0], options?: RequestOptions): Promise<{
+        expiresAt?: number | bigint;
+        fileUrl: string;
+    }>;
+    delete(body: Schemas['AssetFileDeleteReq'], options?: RequestOptions): Promise<{
+        deleted: boolean;
+    }>;
+    download(query: Parameters<typeof this.api.url>[0], options?: RequestOptions): Promise<Response>;
+}
+export declare function createFilesClient(config?: ClientConfig): FilesClient;
+export {};

package/dist/cjs/files.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FilesClient = exports.DEFAULT_MULTIPART_PART_SIZE = exports.MULTIPART_THRESHOLD_BYTES = exports.MultipartUploadError = void 0;
+exports.createFilesClient = createFilesClient;
+const client_js_1 = require("./openapi/client.js");
+const api_generated_js_1 = require("./openapi/api.generated.js");
+class MultipartUploadError extends Error {
+    session;
+    cause;
+    constructor(session, cause) {
+        super('Multipart upload interrupted. The session is retained; reconcile completion before retrying or aborting.');
+        this.session = session;
+        this.cause = cause;
+        this.name = 'MultipartUploadError';
+    }
+}
+exports.MultipartUploadError = MultipartUploadError;
+exports.MULTIPART_THRESHOLD_BYTES = 100 * 1024 * 1024;
+exports.DEFAULT_MULTIPART_PART_SIZE = 8 * 1024 * 1024;
+function positiveSafe(value, name) {
+    const n = Number(value);
+    if (!Number.isSafeInteger(n) || n <= 0)
+        throw new TypeError(`Invalid ${name}`);
+    return n;
+}
+function validateFile(file) {
+    if (!file || typeof file.name !== 'string' || !file.name || !Number.isSafeInteger(file.size) || file.size < 0 || typeof file.slice !== 'function')
+        throw new TypeError('A File is required');
+}
+/** All platform requests are scoped to this instance; storage requests never carry its API key. */
+class FilesClient {
+    http;
+    api;
+    multipart;
+    constructor(http) {
+        this.http = http;
+        this.api = (0, api_generated_js_1.createOpenAPI)(http).assets.files;
+        this.multipart = this.api.multipart;
+    }
+    async storage(urlString, init, options = {}) {
+        const url = new URL(urlString);
+        if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password)
+            throw new TypeError('Invalid signed storage URL');
+        const controller = new AbortController();
+        const abort = () => controller.abort(options.signal?.reason);
+        const timer = setTimeout(() => controller.abort(), this.http.timeoutMs);
+        options.signal?.addEventListener('abort', abort, { once: true });
+        try {
+            if (options.signal?.aborted)
+                abort();
+            const response = await this.http.getFetch()(url.href, { ...init, signal: controller.signal, credentials: 'omit', redirect: 'error' });
+            if (!response.ok)
+                throw new client_js_1.ApiError(response.status, 0, 'Object storage request failed');
+            return response;
+        }
+        finally {
+            clearTimeout(timer);
+            options.signal?.removeEventListener('abort', abort);
+        }
+    }
+    async upload(file, options = {}) {
+        validateFile(file);
+        if (file.size > exports.MULTIPART_THRESHOLD_BYTES)
+            return this.uploadMultipart(file, options);
+        const { signal, ...metadata } = options;
+        const prepared = await this.api.prepareUpload({ ...metadata, fileName: file.name, size: file.size, contentType: file.type || 'application/octet-stream' }, { signal });
+        if (!prepared.postUrl || !prepared.filePath || !prepared.postFields)
+            throw new client_js_1.ApiError(200, 0, 'Invalid upload preparation response');
+        const form = new FormData();
+        for (const [name, value] of Object.entries(prepared.postFields))
+            form.append(name, value);
+        form.append('file', file);
+        await this.storage(prepared.postUrl, { method: 'POST', body: form }, { signal });
+        return prepared;
+    }
+    async uploadMultipart(file, options = {}) {
+        validateFile(file);
+        if (file.size === 0)
+            throw new TypeError('Multipart upload requires a non-empty file');
+        const { signal, partSize = exports.DEFAULT_MULTIPART_PART_SIZE, onProgress, ...metadata } = options;
+        if (!Number.isSafeInteger(partSize) || partSize < 5 * 1024 * 1024)
+            throw new TypeError('partSize must be at least 5 MiB');
+        const start = await this.multipart.init({ ...metadata, fileName: file.name, contentType: file.type || 'application/octet-stream', size: file.size, partSize }, { signal });
+        const session = { fileKey: start.fileKey, uploadId: start.uploadId, parts: [], completionAttempted: false };
+        try {
+            const size = positiveSafe(start.partSize, 'server partSize');
+            const count = positiveSafe(start.partCount, 'server partCount');
+            if (!start.fileKey || !start.uploadId || count !== Math.ceil(file.size / size) || size < 5 * 1024 * 1024 || count > 10_000)
+                throw new TypeError('Invalid multipart preparation response');
+            for (let partNumber = 1; partNumber <= count; partNumber++) {
+                const result = await this.multipart.partUrls({ fileKey: start.fileKey, uploadId: start.uploadId, partNumbers: [partNumber] }, { signal });
+                const signed = result.partUrls.find(p => Number(p.partNumber) === partNumber);
+                if (!signed?.url)
+                    throw new client_js_1.ApiError(200, 0, 'Missing signed part URL');
+                const end = Math.min(partNumber * size, file.size);
+                const response = await this.storage(signed.url, { method: 'PUT', body: file.slice((partNumber - 1) * size, end) }, { signal });
+                const etag = response.headers.get('etag');
+                if (!etag)
+                    throw new client_js_1.ApiError(response.status, 0, 'Storage response is missing ETag');
+                session.parts.push({ partNumber, etag });
+                onProgress?.({ uploadedBytes: end, totalBytes: file.size });
+            }
+            session.completionAttempted = true;
+            return await this.multipart.complete({ fileKey: session.fileKey, uploadId: session.uploadId, parts: session.parts }, { signal });
+        }
+        catch (error) {
+            throw new MultipartUploadError(session, error);
+        }
+    }
+    url(query, options) { return this.api.url(query, options); }
+    delete(body, options) { return this.api.delete(body, options); }
+    async download(query, options = {}) {
+        const { fileUrl } = await this.api.url(query, options);
+        return this.storage(fileUrl, { method: 'GET' }, options);
+    }
+}
+exports.FilesClient = FilesClient;
+function createFilesClient(config = {}) { return new FilesClient(new client_js_1.HttpClient(config)); }
+//# sourceMappingURL=files.js.map

package/dist/cjs/files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.js","sourceRoot":"","sources":["../../src/files.ts"],"names":[],"mappings":"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","sourcesContent":["import { HttpClient, ApiError, type ClientConfig, type RequestOptions } from './openapi/client.js';\nimport { createOpenAPI } from './openapi/api.generated.js';\nimport type { components } from './openapi/types.generated.js';\n\ntype Schemas = components['schemas'];\nexport type UploadOptions = Omit<Schemas['AssetFileUploadReq'], 'fileName' | 'contentType' | 'size'> & RequestOptions;\nexport type UploadResult = Schemas['AssetFileUploadResp'];\nexport type MultipartResult = Schemas['AssetFileMultipartCompleteResp'];\nexport interface MultipartOptions extends UploadOptions {\n  partSize?: number;\n  onProgress?: (progress: { uploadedBytes: number; totalBytes: number }) => void;\n}\nexport interface MultipartSession {\n  fileKey: string;\n  uploadId: string;\n  parts: Schemas['AssetFileMultipartPart'][];\n  completionAttempted: boolean;\n}\nexport class MultipartUploadError extends Error {\n  constructor(readonly session: MultipartSession, readonly cause: unknown) {\n    super('Multipart upload interrupted. The session is retained; reconcile completion before retrying or aborting.');\n    this.name = 'MultipartUploadError';\n  }\n}\nexport const MULTIPART_THRESHOLD_BYTES = 100 * 1024 * 1024;\nexport const DEFAULT_MULTIPART_PART_SIZE = 8 * 1024 * 1024;\n\nfunction positiveSafe(value: number | bigint, name: string): number {\n  const n = Number(value);\n  if (!Number.isSafeInteger(n) || n <= 0) throw new TypeError(`Invalid ${name}`);\n  return n;\n}\nfunction validateFile(file: File): void {\n  if (!file || typeof file.name !== 'string' || !file.name || !Number.isSafeInteger(file.size) || file.size < 0 || typeof file.slice !== 'function') throw new TypeError('A File is required');\n}\n\n/** All platform requests are scoped to this instance; storage requests never carry its API key. */\nexport class FilesClient {\n  private readonly api;\n  readonly multipart;\n  constructor(private readonly http: HttpClient) {\n    this.api = createOpenAPI(http).assets.files;\n    this.multipart = this.api.multipart;\n  }\n\n  private async storage(urlString: string, init: RequestInit, options: RequestOptions = {}): Promise<Response> {\n    const url = new URL(urlString);\n    if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password) throw new TypeError('Invalid signed storage URL');\n    const controller = new AbortController();\n    const abort = () => controller.abort(options.signal?.reason);\n    const timer = setTimeout(() => controller.abort(), this.http.timeoutMs);\n    options.signal?.addEventListener('abort', abort, { once: true });\n    try {\n      if (options.signal?.aborted) abort();\n      const response = await this.http.getFetch()(url.href, { ...init, signal: controller.signal, credentials: 'omit', redirect: 'error' });\n      if (!response.ok) throw new ApiError(response.status, 0, 'Object storage request failed');\n      return response;\n    } finally { clearTimeout(timer); options.signal?.removeEventListener('abort', abort); }\n  }\n\n  async upload(file: File, options: UploadOptions = {}): Promise<UploadResult | MultipartResult> {\n    validateFile(file);\n    if (file.size > MULTIPART_THRESHOLD_BYTES) return this.uploadMultipart(file, options);\n    const { signal, ...metadata } = options;\n    const prepared = await this.api.prepareUpload({ ...metadata, fileName: file.name, size: file.size, contentType: file.type || 'application/octet-stream' }, { signal });\n    if (!prepared.postUrl || !prepared.filePath || !prepared.postFields) throw new ApiError(200, 0, 'Invalid upload preparation response');\n    const form = new FormData();\n    for (const [name, value] of Object.entries(prepared.postFields)) form.append(name, value);\n    form.append('file', file);\n    await this.storage(prepared.postUrl, { method: 'POST', body: form }, { signal });\n    return prepared;\n  }\n\n  async uploadMultipart(file: File, options: MultipartOptions = {}): Promise<MultipartResult> {\n    validateFile(file);\n    if (file.size === 0) throw new TypeError('Multipart upload requires a non-empty file');\n    const { signal, partSize = DEFAULT_MULTIPART_PART_SIZE, onProgress, ...metadata } = options;\n    if (!Number.isSafeInteger(partSize) || partSize < 5 * 1024 * 1024) throw new TypeError('partSize must be at least 5 MiB');\n    const start = await this.multipart.init({ ...metadata, fileName: file.name, contentType: file.type || 'application/octet-stream', size: file.size, partSize }, { signal });\n    const session: MultipartSession = { fileKey: start.fileKey, uploadId: start.uploadId, parts: [], completionAttempted: false };\n    try {\n      const size = positiveSafe(start.partSize, 'server partSize');\n      const count = positiveSafe(start.partCount, 'server partCount');\n      if (!start.fileKey || !start.uploadId || count !== Math.ceil(file.size / size) || size < 5 * 1024 * 1024 || count > 10_000) throw new TypeError('Invalid multipart preparation response');\n      for (let partNumber = 1; partNumber <= count; partNumber++) {\n        const result = await this.multipart.partUrls({ fileKey: start.fileKey, uploadId: start.uploadId, partNumbers: [partNumber] }, { signal });\n        const signed = result.partUrls.find(p => Number(p.partNumber) === partNumber);\n        if (!signed?.url) throw new ApiError(200, 0, 'Missing signed part URL');\n        const end = Math.min(partNumber * size, file.size);\n        const response = await this.storage(signed.url, { method: 'PUT', body: file.slice((partNumber - 1) * size, end) }, { signal });\n        const etag = response.headers.get('etag');\n        if (!etag) throw new ApiError(response.status, 0, 'Storage response is missing ETag');\n        session.parts.push({ partNumber, etag });\n        onProgress?.({ uploadedBytes: end, totalBytes: file.size });\n      }\n      session.completionAttempted = true;\n      return await this.multipart.complete({ fileKey: session.fileKey, uploadId: session.uploadId, parts: session.parts }, { signal });\n    } catch (error) { throw new MultipartUploadError(session, error); }\n  }\n\n  url(query: Parameters<typeof this.api.url>[0], options?: RequestOptions) { return this.api.url(query, options); }\n  delete(body: Schemas['AssetFileDeleteReq'], options?: RequestOptions) { return this.api.delete(body, options); }\n  async download(query: Parameters<typeof this.api.url>[0], options: RequestOptions = {}): Promise<Response> {\n    const { fileUrl } = await this.api.url(query, options);\n    return this.storage(fileUrl, { method: 'GET' }, options);\n  }\n}\nexport function createFilesClient(config: ClientConfig = {}): FilesClient { return new FilesClient(new HttpClient(config)); }\n"]}

package/dist/cjs/framework-scope.d.ts

@@ -0,0 +1 @@
+export declare function clientScope(client: object): number;

package/dist/cjs/framework-scope.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clientScope = clientScope;
+const scopes = new WeakMap();
+let nextScope = 0;
+function clientScope(client) {
+    let scope = scopes.get(client);
+    if (scope === undefined) {
+        scope = ++nextScope;
+        scopes.set(client, scope);
+    }
+    return scope;
+}
+//# sourceMappingURL=framework-scope.js.map

package/dist/cjs/framework-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"framework-scope.js","sourceRoot":"","sources":["../../src/framework-scope.ts"],"names":[],"mappings":";;AAEA,kCAIC;AAND,MAAM,MAAM,GAAG,IAAI,OAAO,EAAkB,CAAC;AAC7C,IAAI,SAAS,GAAG,CAAC,CAAC;AAClB,SAAgB,WAAW,CAAC,MAAc;IACxC,IAAI,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC/B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QAAC,KAAK,GAAG,EAAE,SAAS,CAAC;QAAC,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAAC,CAAC;IAC5E,OAAO,KAAK,CAAC;AACf,CAAC","sourcesContent":["const scopes = new WeakMap<object, number>();\nlet nextScope = 0;\nexport function clientScope(client: object): number {\n  let scope = scopes.get(client);\n  if (scope === undefined) { scope = ++nextScope; scopes.set(client, scope); }\n  return scope;\n}\n"]}

package/dist/cjs/index.d.ts

@@ -0,0 +1,14 @@
+export { createClient } from './client.js';
+export type { Tier0Client, Tier0ClientConfig } from './client.js';
+export { createSourceClient } from './source.js';
+export type { SourceClient, SourceClientConfig } from './source.js';
+export { createStreamClient } from './stream.js';
+export type { StreamClient, StreamClientConfig } from './stream.js';
+export { ApiError, TransportError, configureClient } from './openapi/client.js';
+export type { ClientConfig, RequestOptions } from './openapi/client.js';
+export type { components, paths } from './openapi/types.generated.js';
+export * from './uns-v2/index.js';
+export * from './controls.js';
+export * from './capabilities.js';
+export * from './files.js';
+export * from './runtime-context.js';

package/dist/cjs/index.js

@@ -0,0 +1,33 @@
+"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 });
+exports.configureClient = exports.TransportError = exports.ApiError = exports.createStreamClient = exports.createSourceClient = exports.createClient = void 0;
+var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "createClient", { enumerable: true, get: function () { return client_js_1.createClient; } });
+var source_js_1 = require("./source.js");
+Object.defineProperty(exports, "createSourceClient", { enumerable: true, get: function () { return source_js_1.createSourceClient; } });
+var stream_js_1 = require("./stream.js");
+Object.defineProperty(exports, "createStreamClient", { enumerable: true, get: function () { return stream_js_1.createStreamClient; } });
+var client_js_2 = require("./openapi/client.js");
+Object.defineProperty(exports, "ApiError", { enumerable: true, get: function () { return client_js_2.ApiError; } });
+Object.defineProperty(exports, "TransportError", { enumerable: true, get: function () { return client_js_2.TransportError; } });
+Object.defineProperty(exports, "configureClient", { enumerable: true, get: function () { return client_js_2.configureClient; } });
+__exportStar(require("./uns-v2/index.js"), exports);
+__exportStar(require("./controls.js"), exports);
+__exportStar(require("./capabilities.js"), exports);
+__exportStar(require("./files.js"), exports);
+__exportStar(require("./runtime-context.js"), exports);
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,yCAA2C;AAAlC,yGAAA,YAAY,OAAA;AAErB,yCAAiD;AAAxC,+GAAA,kBAAkB,OAAA;AAE3B,yCAAiD;AAAxC,+GAAA,kBAAkB,OAAA;AAE3B,iDAAgF;AAAvE,qGAAA,QAAQ,OAAA;AAAE,2GAAA,cAAc,OAAA;AAAE,4GAAA,eAAe,OAAA;AAGlD,oDAAkC;AAClC,gDAA8B;AAC9B,oDAAkC;AAClC,6CAA2B;AAC3B,uDAAqC","sourcesContent":["export { createClient } from './client.js';\nexport type { Tier0Client, Tier0ClientConfig } from './client.js';\nexport { createSourceClient } from './source.js';\nexport type { SourceClient, SourceClientConfig } from './source.js';\nexport { createStreamClient } from './stream.js';\nexport type { StreamClient, StreamClientConfig } from './stream.js';\nexport { ApiError, TransportError, configureClient } from './openapi/client.js';\nexport type { ClientConfig, RequestOptions } from './openapi/client.js';\nexport type { components, paths } from './openapi/types.generated.js';\nexport * from './uns-v2/index.js';\nexport * from './controls.js';\nexport * from './capabilities.js';\nexport * from './files.js';\nexport * from './runtime-context.js';\n"]}

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

@@ -0,0 +1,65 @@
+/**
+ * MQTT broker 地址归一化工具。
+ *
+ * 平台 `/openapi/v1/info` 返回的 `mqttBroker` 格式随环境变化，不保证统一：
+ * - enterprise：env 为空时后端兜底返回 `tcp://<host>:1883`（面向边缘/服务端客户端的连接串）；
+ * - SaaS（Tier0 Cloud）：env 原样透传，常见为 `host:port` 或裸 `host`。
+ *
+ * 浏览器 wss 客户端不应直接把它当 hostname 拼 URL（会得到 `wss://tcp://...`
+ * 这类非法地址），先经本模块解析/推导，再交给 `Tier0MQClient`。
+ */
+/** 解析后的 broker 端点。hostname 保证为裸主机（无 scheme、无端口、无路径）。 */
+export interface MqttBrokerEndpoint {
+    /** 裸主机名（已剥离 scheme/path/query，不含端口）。 */
+    hostname: string;
+    /**
+     * 原始端口。注意：对 `tcp://host:1883` 这是 **tcp 端口**，浏览器 wss 场景
+     * 不能直接沿用（wss 通常是 8084），由 `toWebSocketUrl` 的 `wssPort` 决定。
+     */
+    port?: number;
+    /** 原始 scheme（tcp/mqtt/mqtts/ws/wss/...），裸 host 输入时为 undefined。 */
+    scheme?: string;
+}
+/**
+ * 解析各种形态的 broker 字符串为结构化端点。
+ *
+ * 兼容输入：`tcp://host:1883`、`mqtts://host:8883`、`wss://host:8084/mqtt`、
+ * `host:1883`、裸 `host`。无法解析（空串、非法 URL）返回 undefined。
+ */
+export declare function parseMqttBroker(broker?: string | null): MqttBrokerEndpoint | undefined;
+/** 浏览器 wss 默认端口（与平台 OS_MQTT_WEBSOCKET_TSL_PORT 默认值一致）。 */
+export declare const DEFAULT_WSS_PORT = 8084;
+/** MQTT over WebSocket 路径。 */
+export declare const DEFAULT_WS_PATH = "/mqtt";
+export interface ToWebSocketUrlOptions {
+    /** wss 端口，默认 {@link DEFAULT_WSS_PORT}（8084）。 */
+    wssPort?: number;
+    /**
+     * 显式指定 ws(false)/wss(true)。缺省自适应：浏览器 https 页面用 wss，
+     * 或 WebSocket 端口为 8084 时用 wss，其余用 ws。
+     */
+    secure?: boolean;
+}
+/**
+ * 当前运行环境是否处于 https 安全上下文。
+ *
+ * 用 `globalThis.location` 而不是 `window.location`：Web Worker
+ * （dedicated/shared）里 `window` 不存在，但 `location.protocol` 同样是 `https:`，
+ * 应同等视为安全上下文（否则会被降级为 ws 而被浏览器按 mixed content 拦截）。
+ */
+export declare function isBrowserHttps(): boolean;
+/**
+ * 把 `mqttBroker`（或 {@link MqttBrokerEndpoint}）推导为可直接传给
+ * `Tier0MQClient` 的 WebSocket URL。
+ *
+ * 规则：
+ * - 输入已是 `ws(s)://` URL：原样归一（补 `/mqtt` 路径，端口、path、query 均保留）；
+ * - 输入 `tcp://host:1883` / `host:port` / 裸 `host`：按 `secure` 推导 scheme，
+ *   端口一律用 `wssPort`（8084），**不沿用** tcp 端口；
+ * - 输入为空/无法解析：返回 undefined（调用方应回退或报错，勿硬拼 URL）。
+ *
+ * @example
+ * toWebSocketUrl('tcp://example.tier0.dev:1883', { secure: true });
+ * // → 'wss://example.tier0.dev:8084/mqtt'
+ */
+export declare function toWebSocketUrl(broker: string | MqttBrokerEndpoint | undefined | null, opts?: ToWebSocketUrlOptions): string | undefined;

package/dist/cjs/mq/broker.js

@@ -0,0 +1,115 @@
+"use strict";
+/**
+ * MQTT broker 地址归一化工具。
+ *
+ * 平台 `/openapi/v1/info` 返回的 `mqttBroker` 格式随环境变化，不保证统一：
+ * - enterprise：env 为空时后端兜底返回 `tcp://<host>:1883`（面向边缘/服务端客户端的连接串）；
+ * - SaaS（Tier0 Cloud）：env 原样透传，常见为 `host:port` 或裸 `host`。
+ *
+ * 浏览器 wss 客户端不应直接把它当 hostname 拼 URL（会得到 `wss://tcp://...`
+ * 这类非法地址），先经本模块解析/推导，再交给 `Tier0MQClient`。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_WS_PATH = exports.DEFAULT_WSS_PORT = void 0;
+exports.parseMqttBroker = parseMqttBroker;
+exports.isBrowserHttps = isBrowserHttps;
+exports.toWebSocketUrl = toWebSocketUrl;
+const SCHEME_RE = /^([a-zA-Z][a-zA-Z0-9+.-]*):\/\//;
+/**
+ * 解析各种形态的 broker 字符串为结构化端点。
+ *
+ * 兼容输入：`tcp://host:1883`、`mqtts://host:8883`、`wss://host:8084/mqtt`、
+ * `host:1883`、裸 `host`。无法解析（空串、非法 URL）返回 undefined。
+ */
+function parseMqttBroker(broker) {
+    const raw = broker?.trim();
+    if (!raw)
+        return undefined;
+    if (SCHEME_RE.test(raw)) {
+        try {
+            const u = new URL(raw);
+            if (!u.hostname)
+                return undefined;
+            const scheme = SCHEME_RE.exec(raw)?.[1]?.toLowerCase();
+            return {
+                hostname: u.hostname,
+                port: u.port ? Number.parseInt(u.port, 10) : undefined,
+                scheme,
+            };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    // 无 scheme：`host:port` 或裸 `host`；含路径/空白的是垃圾输入，拒绝
+    if (/[\s/]/.test(raw))
+        return undefined;
+    const i = raw.lastIndexOf(':');
+    if (i > 0 && /^\d+$/.test(raw.slice(i + 1))) {
+        const hostname = raw.slice(0, i);
+        if (!hostname)
+            return undefined;
+        return { hostname, port: Number.parseInt(raw.slice(i + 1), 10) };
+    }
+    return { hostname: raw };
+}
+/** 浏览器 wss 默认端口（与平台 OS_MQTT_WEBSOCKET_TSL_PORT 默认值一致）。 */
+exports.DEFAULT_WSS_PORT = 8084;
+/** MQTT over WebSocket 路径。 */
+exports.DEFAULT_WS_PATH = '/mqtt';
+/**
+ * 当前运行环境是否处于 https 安全上下文。
+ *
+ * 用 `globalThis.location` 而不是 `window.location`：Web Worker
+ * （dedicated/shared）里 `window` 不存在，但 `location.protocol` 同样是 `https:`，
+ * 应同等视为安全上下文（否则会被降级为 ws 而被浏览器按 mixed content 拦截）。
+ */
+function isBrowserHttps() {
+    const loc = globalThis.location;
+    return typeof loc?.protocol === 'string' && loc.protocol === 'https:';
+}
+/**
+ * 把 `mqttBroker`（或 {@link MqttBrokerEndpoint}）推导为可直接传给
+ * `Tier0MQClient` 的 WebSocket URL。
+ *
+ * 规则：
+ * - 输入已是 `ws(s)://` URL：原样归一（补 `/mqtt` 路径，端口、path、query 均保留）；
+ * - 输入 `tcp://host:1883` / `host:port` / 裸 `host`：按 `secure` 推导 scheme，
+ *   端口一律用 `wssPort`（8084），**不沿用** tcp 端口；
+ * - 输入为空/无法解析：返回 undefined（调用方应回退或报错，勿硬拼 URL）。
+ *
+ * @example
+ * toWebSocketUrl('tcp://example.tier0.dev:1883', { secure: true });
+ * // → 'wss://example.tier0.dev:8084/mqtt'
+ */
+function toWebSocketUrl(broker, opts = {}) {
+    if (broker == null || broker === '')
+        return undefined;
+    // 已是 ws(s) URL：解析后归一直通（保留其 scheme/端口/path/query，仅补 /mqtt 路径）
+    if (typeof broker === 'string' && /^wss?:\/\//i.test(broker.trim())) {
+        try {
+            const u = new URL(broker.trim());
+            if (!u.hostname)
+                return undefined;
+            if (!u.pathname || u.pathname === '/') {
+                u.pathname = exports.DEFAULT_WS_PATH;
+            }
+            return u.toString();
+        }
+        catch {
+            return undefined;
+        }
+    }
+    const endpoint = typeof broker === 'string' ? parseMqttBroker(broker) : broker;
+    if (!endpoint?.hostname)
+        return undefined;
+    // ws(s) 端点：保留其 scheme 与端口（"已是 WebSocket 地址"的直通语义）
+    if (endpoint.scheme === 'ws' || endpoint.scheme === 'wss') {
+        const port = endpoint.port ? `:${endpoint.port}` : '';
+        return `${endpoint.scheme}://${endpoint.hostname}${port}${exports.DEFAULT_WS_PATH}`;
+    }
+    const port = opts.wssPort ?? exports.DEFAULT_WSS_PORT;
+    const secure = opts.secure ?? (isBrowserHttps() || port === exports.DEFAULT_WSS_PORT);
+    return `${secure ? 'wss' : 'ws'}://${endpoint.hostname}:${port}${exports.DEFAULT_WS_PATH}`;
+}
+//# sourceMappingURL=broker.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"broker.js","sourceRoot":"","sources":["../../../src/mq/broker.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * MQTT broker 地址归一化工具。\n *\n * 平台 `/openapi/v1/info` 返回的 `mqttBroker` 格式随环境变化，不保证统一：\n * - enterprise：env 为空时后端兜底返回 `tcp://<host>:1883`（面向边缘/服务端客户端的连接串）；\n * - SaaS（Tier0 Cloud）：env 原样透传，常见为 `host:port` 或裸 `host`。\n *\n * 浏览器 wss 客户端不应直接把它当 hostname 拼 URL（会得到 `wss://tcp://...`\n * 这类非法地址），先经本模块解析/推导，再交给 `Tier0MQClient`。\n */\n\n/** 解析后的 broker 端点。hostname 保证为裸主机（无 scheme、无端口、无路径）。 */\nexport interface MqttBrokerEndpoint {\n  /** 裸主机名（已剥离 scheme/path/query，不含端口）。 */\n  hostname: string;\n  /**\n   * 原始端口。注意：对 `tcp://host:1883` 这是 **tcp 端口**，浏览器 wss 场景\n   * 不能直接沿用（wss 通常是 8084），由 `toWebSocketUrl` 的 `wssPort` 决定。\n   */\n  port?: number;\n  /** 原始 scheme（tcp/mqtt/mqtts/ws/wss/...），裸 host 输入时为 undefined。 */\n  scheme?: string;\n}\n\nconst SCHEME_RE = /^([a-zA-Z][a-zA-Z0-9+.-]*):\\/\\//;\n\n/**\n * 解析各种形态的 broker 字符串为结构化端点。\n *\n * 兼容输入：`tcp://host:1883`、`mqtts://host:8883`、`wss://host:8084/mqtt`、\n * `host:1883`、裸 `host`。无法解析（空串、非法 URL）返回 undefined。\n */\nexport function parseMqttBroker(broker?: string | null): MqttBrokerEndpoint | undefined {\n  const raw = broker?.trim();\n  if (!raw) return undefined;\n\n  if (SCHEME_RE.test(raw)) {\n    try {\n      const u = new URL(raw);\n      if (!u.hostname) return undefined;\n      const scheme = SCHEME_RE.exec(raw)?.[1]?.toLowerCase();\n      return {\n        hostname: u.hostname,\n        port: u.port ? Number.parseInt(u.port, 10) : undefined,\n        scheme,\n      };\n    } catch {\n      return undefined;\n    }\n  }\n\n  // 无 scheme：`host:port` 或裸 `host`；含路径/空白的是垃圾输入，拒绝\n  if (/[\\s/]/.test(raw)) return undefined;\n  const i = raw.lastIndexOf(':');\n  if (i > 0 && /^\\d+$/.test(raw.slice(i + 1))) {\n    const hostname = raw.slice(0, i);\n    if (!hostname) return undefined;\n    return { hostname, port: Number.parseInt(raw.slice(i + 1), 10) };\n  }\n  return { hostname: raw };\n}\n\n/** 浏览器 wss 默认端口（与平台 OS_MQTT_WEBSOCKET_TSL_PORT 默认值一致）。 */\nexport const DEFAULT_WSS_PORT = 8084;\n/** MQTT over WebSocket 路径。 */\nexport const DEFAULT_WS_PATH = '/mqtt';\n\nexport interface ToWebSocketUrlOptions {\n  /** wss 端口，默认 {@link DEFAULT_WSS_PORT}（8084）。 */\n  wssPort?: number;\n  /**\n   * 显式指定 ws(false)/wss(true)。缺省自适应：浏览器 https 页面用 wss，\n   * 或 WebSocket 端口为 8084 时用 wss，其余用 ws。\n   */\n  secure?: boolean;\n}\n\n/**\n * 当前运行环境是否处于 https 安全上下文。\n *\n * 用 `globalThis.location` 而不是 `window.location`：Web Worker\n * （dedicated/shared）里 `window` 不存在，但 `location.protocol` 同样是 `https:`，\n * 应同等视为安全上下文（否则会被降级为 ws 而被浏览器按 mixed content 拦截）。\n */\nexport function isBrowserHttps(): boolean {\n  const loc = (globalThis as { location?: { protocol?: string } }).location;\n  return typeof loc?.protocol === 'string' && loc.protocol === 'https:';\n}\n\n/**\n * 把 `mqttBroker`（或 {@link MqttBrokerEndpoint}）推导为可直接传给\n * `Tier0MQClient` 的 WebSocket URL。\n *\n * 规则：\n * - 输入已是 `ws(s)://` URL：原样归一（补 `/mqtt` 路径，端口、path、query 均保留）；\n * - 输入 `tcp://host:1883` / `host:port` / 裸 `host`：按 `secure` 推导 scheme，\n *   端口一律用 `wssPort`（8084），**不沿用** tcp 端口；\n * - 输入为空/无法解析：返回 undefined（调用方应回退或报错，勿硬拼 URL）。\n *\n * @example\n * toWebSocketUrl('tcp://example.tier0.dev:1883', { secure: true });\n * // → 'wss://example.tier0.dev:8084/mqtt'\n */\nexport function toWebSocketUrl(\n  broker: string | MqttBrokerEndpoint | undefined | null,\n  opts: ToWebSocketUrlOptions = {},\n): string | undefined {\n  if (broker == null || broker === '') return undefined;\n\n  // 已是 ws(s) URL：解析后归一直通（保留其 scheme/端口/path/query，仅补 /mqtt 路径）\n  if (typeof broker === 'string' && /^wss?:\\/\\//i.test(broker.trim())) {\n    try {\n      const u = new URL(broker.trim());\n      if (!u.hostname) return undefined;\n      if (!u.pathname || u.pathname === '/') {\n        u.pathname = DEFAULT_WS_PATH;\n      }\n      return u.toString();\n    } catch {\n      return undefined;\n    }\n  }\n\n  const endpoint = typeof broker === 'string' ? parseMqttBroker(broker) : broker;\n  if (!endpoint?.hostname) return undefined;\n\n  // ws(s) 端点：保留其 scheme 与端口（\"已是 WebSocket 地址\"的直通语义）\n  if (endpoint.scheme === 'ws' || endpoint.scheme === 'wss') {\n    const port = endpoint.port ? `:${endpoint.port}` : '';\n    return `${endpoint.scheme}://${endpoint.hostname}${port}${DEFAULT_WS_PATH}`;\n  }\n\n  const port = opts.wssPort ?? DEFAULT_WSS_PORT;\n  const secure = opts.secure ?? (isBrowserHttps() || port === DEFAULT_WSS_PORT);\n  return `${secure ? 'wss' : 'ws'}://${endpoint.hostname}:${port}${DEFAULT_WS_PATH}`;\n}\n"]}

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

@@ -0,0 +1,37 @@
+import type { MQTTConfig, MQTTEventMap } from './types.js';
+/**
+ * 消息回调。公开类型保持 `void` 返回，以兼容 async handler、`push()` 简写等
+ * 既有写法；运行时额外识别返回值：handler 返回严格的 `false` 视为下游停滞
+ * （背压），SDK 会统计连续背压次数，配合 MQTTConfig.maxBackpressuredDeliveries
+ * 可在阈值内自动移除订阅。
+ */
+export type TopicHandler = (topic: string, payload: string) => void;
+export declare class Tier0MQClient {
+    private client;
+    private config;
+    private explicitClientId;
+    private explicitUsername;
+    private listeners;
+    private subscriptions;
+    private connectingPromise;
+    private _connected;
+    constructor(config?: MQTTConfig);
+    private get mqttUrl();
+    private ensureConnected;
+    private doConnect;
+    connect(config?: MQTTConfig): Promise<void>;
+    subscribe(topic: string, handler: TopicHandler): void;
+    unsubscribe(topic: string, handler?: TopicHandler): void;
+    publish(topic: string, payload: string | object, options?: {
+        qos?: number;
+        retain?: boolean;
+    }): Promise<void>;
+    disconnect(): void;
+    on<K extends keyof MQTTEventMap>(event: K, handler: MQTTEventMap[K]): void;
+    off<K extends keyof MQTTEventMap>(event: K, handler: MQTTEventMap[K]): void;
+    private emit;
+    private resubscribeAll;
+    private topicMatch;
+    get isConnected(): boolean;
+    get subscribedTopics(): string[];
+}