@das-fed/upf-utils 6.4.0-dev.288 → 6.4.0-dev.289

package/esm-map.json

@@ -276,5 +276,7 @@
   "fromTimeZonePickerValue": "/common-tools/timezone-format/index",
   "toTimestampAtZoneStartOfDay": "/common-tools/timezone-format/index",
   "toTimestampAtZoneEndOfDay": "/common-tools/timezone-format/index",
-  "readInjectedParentIanaTimeZoneDataSnapshot": "/common-tools/timezone-format/index"
+  "readInjectedParentIanaTimeZoneDataSnapshot": "/common-tools/timezone-format/index",
+  "RealtimeSocketClient": "/realtime-connection/index",
+  "createRealtimeSocketClient": "/realtime-connection/index"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@das-fed/upf-utils",
-  "version": "6.4.0-dev.288",
+  "version": "6.4.0-dev.289",
   "description": "",
   "type": "module",
   "main": "./index.js",
@@ -22,8 +22,8 @@
   },
   "devDependencies": {
     "@babel/preset-env": "7.26.0",
-    "@das-fed/upf-cli": "6.4.0-dev.288",
-    "@das-fed/upf-web": "6.4.0-dev.288",
+    "@das-fed/upf-cli": "6.4.0-dev.289",
+    "@das-fed/upf-web": "6.4.0-dev.289",
     "@rollup/plugin-babel": "6.0.4",
     "@types/js-cookie": "^3.0.6",
     "@types/lodash-es": "^4.17.12",
@@ -51,13 +51,13 @@
   },
   "upfReleaseMeta": {
     "packageName": "@das-fed/upf-utils",
-    "releaseVersion": "6.4.0-dev.288",
+    "releaseVersion": "6.4.0-dev.289",
     "distTag": "dev",
     "releaseType": "publish",
-    "publishedAt": "2026-07-03T03:51:37.579Z",
+    "publishedAt": "2026-07-08T01:52:46.305Z",
     "sourceBranch": "dev",
-    "sourceCommit": "26cbb351f0872945bb47a2fb8472de0f2234132e",
-    "gitTag": "upf-release/v6.4.0-dev.288",
+    "sourceCommit": "78a710c274cfb48feeff4e3e4b5c18d43396202b",
+    "gitTag": "upf-release/v6.4.0-dev.289",
     "gitRemote": "origin",
     "gitRemoteUrl": "http://gitlab.dasiot.cn/foundation/frontend/framework.git",
     "releaseStatus": "success"

package/realtime-connection/es5.d.ts

@@ -0,0 +1,70 @@
+export type RealtimeSocketState = 'idle' | 'waiting-token' | 'connecting' | 'open' | 'reconnecting' | 'closed' | 'unsupported';
+export type RealtimeSocketHeartbeatOptions = {
+    message: string | (() => string);
+    interval: number;
+    timeout?: number;
+    response?: string | string[];
+};
+export type RealtimeSocketReconnectOptions = {
+    enabled: boolean;
+    delay?: number;
+    maxDelay?: number;
+    maxAttempts?: number;
+    jitter?: boolean;
+};
+export type RealtimeSocketClientOptions<T = unknown> = {
+    url: string;
+    params?: Record<string, any>;
+    tokenParamName?: string;
+    tokenProvider?: () => string | Promise<string>;
+    heartbeat?: RealtimeSocketHeartbeatOptions;
+    reconnect?: RealtimeSocketReconnectOptions;
+    parser?: (event: MessageEvent) => T;
+    onOpen?: (event: Event) => void;
+    onMessage?: (message: T, event: MessageEvent) => void;
+    onClose?: (event: CloseEvent) => void;
+    onError?: (event: Event) => void;
+    onInvalidMessage?: (error: unknown, event: MessageEvent) => void;
+    onStateChange?: (state: RealtimeSocketState) => void;
+};
+export declare class RealtimeSocketClient<T = unknown> {
+    private ws;
+    private options;
+    private state;
+    private heartbeatTimer;
+    private heartbeatTimeoutTimer;
+    private reconnectTimer;
+    private reconnectAttempts;
+    private manualClosed;
+    private started;
+    private lastHeartbeatAck;
+    constructor(options: RealtimeSocketClientOptions<T>);
+    /** 获取当前连接状态，供业务显示或调试兜底使用。 */
+    getState(): RealtimeSocketState;
+    /** 建立连接；重复调用不会创建多个活动 WebSocket。 */
+    connect(): Promise<void>;
+    /** 仅在连接已打开时发送消息，失败时返回 false。 */
+    send(message: string | ArrayBufferLike | Blob | ArrayBufferView): boolean;
+    /** 主动关闭连接，并清理心跳、重连和网络监听。 */
+    close(): void;
+    private openSocket;
+    private resolveToken;
+    private handleOpen;
+    private handleMessage;
+    private handleClose;
+    private handleError;
+    private startHeartbeat;
+    private scheduleReconnect;
+    private getReconnectDelay;
+    private handleOnline;
+    private handleOffline;
+    private setState;
+    private closeSocket;
+    private clearTimers;
+    private clearHeartbeatTimers;
+    private clearHeartbeatTimeoutTimer;
+    private clearReconnectTimer;
+    private removeNetworkListeners;
+}
+/** 创建独立实时连接实例，调用方负责在卸载时 close。 */
+export declare const createRealtimeSocketClient: <T = unknown>(options: RealtimeSocketClientOptions<T>) => RealtimeSocketClient<T>;

package/realtime-connection/es5.js

@@ -0,0 +1,340 @@
+'use strict';
+
+function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+function _defineProperty(e, r, t) { return (r = _toPropertyKey(r)) in e ? Object.defineProperty(e, r, { value: t, enumerable: !0, configurable: !0, writable: !0 }) : e[r] = t, e; }
+function _regenerator() { /*! regenerator-runtime -- Copyright (c) 2014-present, Facebook, Inc. -- license (MIT): https://github.com/babel/babel/blob/main/packages/babel-helpers/LICENSE */ var e, t, r = "function" == typeof Symbol ? Symbol : {}, n = r.iterator || "@@iterator", o = r.toStringTag || "@@toStringTag"; function i(r, n, o, i) { var c = n && n.prototype instanceof Generator ? n : Generator, u = Object.create(c.prototype); return _regeneratorDefine2(u, "_invoke", function (r, n, o) { var i, c, u, f = 0, p = o || [], y = !1, G = { p: 0, n: 0, v: e, a: d, f: d.bind(e, 4), d: function d(t, r) { return i = t, c = 0, u = e, G.n = r, a; } }; function d(r, n) { for (c = r, u = n, t = 0; !y && f && !o && t < p.length; t++) { var o, i = p[t], d = G.p, l = i[2]; r > 3 ? (o = l === n) && (u = i[(c = i[4]) ? 5 : (c = 3, 3)], i[4] = i[5] = e) : i[0] <= d && ((o = r < 2 && d < i[1]) ? (c = 0, G.v = n, G.n = i[1]) : d < l && (o = r < 3 || i[0] > n || n > l) && (i[4] = r, i[5] = n, G.n = l, c = 0)); } if (o || r > 1) return a; throw y = !0, n; } return function (o, p, l) { if (f > 1) throw TypeError("Generator is already running"); for (y && 1 === p && d(p, l), c = p, u = l; (t = c < 2 ? e : u) || !y;) { i || (c ? c < 3 ? (c > 1 && (G.n = -1), d(c, u)) : G.n = u : G.v = u); try { if (f = 2, i) { if (c || (o = "next"), t = i[o]) { if (!(t = t.call(i, u))) throw TypeError("iterator result is not an object"); if (!t.done) return t; u = t.value, c < 2 && (c = 0); } else 1 === c && (t = i["return"]) && t.call(i), c < 2 && (u = TypeError("The iterator does not provide a '" + o + "' method"), c = 1); i = e; } else if ((t = (y = G.n < 0) ? u : r.call(n, G)) !== a) break; } catch (t) { i = e, c = 1, u = t; } finally { f = 1; } } return { value: t, done: y }; }; }(r, o, i), !0), u; } var a = {}; function Generator() {} function GeneratorFunction() {} function GeneratorFunctionPrototype() {} t = Object.getPrototypeOf; var c = [][n] ? t(t([][n]())) : (_regeneratorDefine2(t = {}, n, function () { return this; }), t), u = GeneratorFunctionPrototype.prototype = Generator.prototype = Object.create(c); function f(e) { return Object.setPrototypeOf ? Object.setPrototypeOf(e, GeneratorFunctionPrototype) : (e.__proto__ = GeneratorFunctionPrototype, _regeneratorDefine2(e, o, "GeneratorFunction")), e.prototype = Object.create(u), e; } return GeneratorFunction.prototype = GeneratorFunctionPrototype, _regeneratorDefine2(u, "constructor", GeneratorFunctionPrototype), _regeneratorDefine2(GeneratorFunctionPrototype, "constructor", GeneratorFunction), GeneratorFunction.displayName = "GeneratorFunction", _regeneratorDefine2(GeneratorFunctionPrototype, o, "GeneratorFunction"), _regeneratorDefine2(u), _regeneratorDefine2(u, o, "Generator"), _regeneratorDefine2(u, n, function () { return this; }), _regeneratorDefine2(u, "toString", function () { return "[object Generator]"; }), (_regenerator = function _regenerator() { return { w: i, m: f }; })(); }
+function _regeneratorDefine2(e, r, n, t) { var i = Object.defineProperty; try { i({}, "", {}); } catch (e) { i = 0; } _regeneratorDefine2 = function _regeneratorDefine(e, r, n, t) { function o(r, n) { _regeneratorDefine2(e, r, function (e) { return this._invoke(r, n, e); }); } r ? i ? i(e, r, { value: n, enumerable: !t, configurable: !t, writable: !t }) : e[r] = n : (o("next", 0), o("throw", 1), o("return", 2)); }, _regeneratorDefine2(e, r, n, t); }
+function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
+function asyncGeneratorStep(n, t, e, r, o, a, c) { try { var i = n[a](c), u = i.value; } catch (n) { return void e(n); } i.done ? t(u) : Promise.resolve(u).then(r, o); }
+function _asyncToGenerator(n) { return function () { var t = this, e = arguments; return new Promise(function (r, o) { var a = n.apply(t, e); function _next(n) { asyncGeneratorStep(a, r, o, _next, _throw, "next", n); } function _throw(n) { asyncGeneratorStep(a, r, o, _next, _throw, "throw", n); } _next(void 0); }); }; }
+function _classCallCheck(a, n) { if (!(a instanceof n)) throw new TypeError("Cannot call a class as a function"); }
+function _defineProperties(e, r) { for (var t = 0; t < r.length; t++) { var o = r[t]; o.enumerable = o.enumerable || !1, o.configurable = !0, "value" in o && (o.writable = !0), Object.defineProperty(e, _toPropertyKey(o.key), o); } }
+function _createClass(e, r, t) { return r && _defineProperties(e.prototype, r), t && _defineProperties(e, t), Object.defineProperty(e, "prototype", { writable: !1 }), e; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == _typeof(i) ? i : i + ""; }
+function _toPrimitive(t, r) { if ("object" != _typeof(t) || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != _typeof(i)) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+var config = require('@das-fed/upf-utils/config/es5');
+var commonTools = require('@das-fed/upf-utils/common-tools/es5');
+var l = 3e3,
+  u = 3e4,
+  m = function m() {
+    var i = config.getConfig(),
+      t = i.wsBaseURL || i.baseURL || location.origin;
+    return String(t || "").replace(/^https:/i, "wss:").replace(/^http:/i, "ws:").replace(/\/+$/, "");
+  },
+  d = function d(i) {
+    return /^wss?:\/\//i.test(i);
+  },
+  f = function f(i) {
+    return /^https?:\/\//i.test(i);
+  },
+  p = function p(i, t) {
+    var e = String(i || "").trim(),
+      s = d(e) ? e : f(e) ? e.replace(/^https:/i, "wss:").replace(/^http:/i, "ws:") : "".concat(m()).concat(e.startsWith("/") ? e : "/".concat(e)),
+      r = commonTools.objectToUrlparams(t);
+    return r ? "".concat(s).concat(s.includes("?") ? "&" : "?").concat(r) : s;
+  },
+  T = function T(i, t) {
+    return t ? (Array.isArray(t) ? t : [t]).includes(String(i !== null && i !== void 0 ? i : "")) : false;
+  },
+  b = function b(i) {
+    return typeof i.data == "string" ? JSON.parse(i.data) : i.data;
+  };
+var S = /*#__PURE__*/function () {
+  function S(t) {
+    _classCallCheck(this, S);
+    this.ws = null, this.state = "idle", this.heartbeatTimer = null, this.heartbeatTimeoutTimer = null, this.reconnectTimer = null, this.reconnectAttempts = 0, this.manualClosed = false, this.started = false, this.lastHeartbeatAck = true, this.options = t, this.handleOnline = this.handleOnline.bind(this), this.handleOffline = this.handleOffline.bind(this);
+  }
+  /** 获取当前连接状态，供业务显示或调试兜底使用。 */
+  return _createClass(S, [{
+    key: "getState",
+    value: function getState() {
+      return this.state;
+    }
+    /** 建立连接；重复调用不会创建多个活动 WebSocket。 */
+  }, {
+    key: "connect",
+    value: (function () {
+      var _connect = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee() {
+        return _regenerator().w(function (_context) {
+          while (1) switch (_context.n) {
+            case 0:
+              if (this.started && (this.state === "connecting" || this.state === "open" || this.state === "reconnecting")) {
+                _context.n = 2;
+                break;
+              }
+              if (!(this.started = true, this.manualClosed = false, (typeof WebSocket === "undefined" ? "undefined" : _typeof(WebSocket)) > "u")) {
+                _context.n = 1;
+                break;
+              }
+              this.setState("unsupported");
+              return _context.a(2);
+            case 1:
+              (typeof window === "undefined" ? "undefined" : _typeof(window)) < "u" && (window.addEventListener("online", this.handleOnline), window.addEventListener("offline", this.handleOffline));
+              _context.n = 2;
+              return this.openSocket();
+            case 2:
+              return _context.a(2);
+          }
+        }, _callee, this);
+      }));
+      function connect() {
+        return _connect.apply(this, arguments);
+      }
+      return connect;
+    }() /** 仅在连接已打开时发送消息，失败时返回 false。 */)
+  }, {
+    key: "send",
+    value: function send(t) {
+      var e;
+      return ((e = this.ws) == null ? undefined : e.readyState) !== WebSocket.OPEN ? false : (this.ws.send(t), true);
+    }
+    /** 主动关闭连接，并清理心跳、重连和网络监听。 */
+  }, {
+    key: "close",
+    value: function close() {
+      this.manualClosed = true, this.started = false, this.clearTimers(), this.removeNetworkListeners(), this.closeSocket(), this.setState("closed");
+    }
+  }, {
+    key: "openSocket",
+    value: function () {
+      var _openSocket = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee2() {
+        var _this = this;
+        var s, r, t, e, n;
+        return _regenerator().w(function (_context2) {
+          while (1) switch (_context2.n) {
+            case 0:
+              if (!this.manualClosed) {
+                _context2.n = 1;
+                break;
+              }
+              return _context2.a(2);
+            case 1:
+              this.clearReconnectTimer(), this.closeSocket(), this.setState(this.reconnectAttempts > 0 ? "reconnecting" : "connecting");
+              t = _objectSpread({}, this.options.params || {});
+              _context2.n = 2;
+              return this.resolveToken();
+            case 2:
+              e = _context2.v;
+              if (!(this.options.tokenProvider && !e)) {
+                _context2.n = 3;
+                break;
+              }
+              this.scheduleReconnect("waiting-token");
+              return _context2.a(2);
+            case 3:
+              e && (t[this.options.tokenParamName || "access_token"] = e);
+              try {
+                n = new WebSocket(p(this.options.url, t));
+                this.ws = n, n.onopen = function (o) {
+                  return _this.handleOpen(o);
+                }, n.onmessage = function (o) {
+                  return _this.handleMessage(o);
+                }, n.onclose = function (o) {
+                  return _this.handleClose(o);
+                }, n.onerror = function (o) {
+                  return _this.handleError(o);
+                };
+              } catch (n) {
+                (r = (s = this.options).onInvalidMessage) == null || r.call(s, n, {}), this.scheduleReconnect();
+              }
+            case 4:
+              return _context2.a(2);
+          }
+        }, _callee2, this);
+      }));
+      function openSocket() {
+        return _openSocket.apply(this, arguments);
+      }
+      return openSocket;
+    }()
+  }, {
+    key: "resolveToken",
+    value: function () {
+      var _resolveToken = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee3() {
+        var _t, _t2, _t3;
+        return _regenerator().w(function (_context3) {
+          while (1) switch (_context3.p = _context3.n) {
+            case 0:
+              if (this.options.tokenProvider) {
+                _context3.n = 1;
+                break;
+              }
+              return _context3.a(2, "");
+            case 1:
+              _context3.p = 1;
+              _t = String;
+              _context3.n = 2;
+              return this.options.tokenProvider();
+            case 2:
+              _t2 = _context3.v;
+              if (_t2) {
+                _context3.n = 3;
+                break;
+              }
+              _t2 = "";
+            case 3:
+              return _context3.a(2, _t(_t2).trim());
+            case 4:
+              _context3.p = 4;
+              _t3 = _context3.v;
+              return _context3.a(2, "");
+          }
+        }, _callee3, this, [[1, 4]]);
+      }));
+      function resolveToken() {
+        return _resolveToken.apply(this, arguments);
+      }
+      return resolveToken;
+    }()
+  }, {
+    key: "handleOpen",
+    value: function handleOpen(t) {
+      var e, s;
+      this.reconnectAttempts = 0, this.lastHeartbeatAck = true, this.setState("open"), (s = (e = this.options).onOpen) == null || s.call(e, t), this.startHeartbeat();
+    }
+  }, {
+    key: "handleMessage",
+    value: function handleMessage(t) {
+      var e, s, r, n, o;
+      if (T(t.data, (e = this.options.heartbeat) == null ? undefined : e.response)) {
+        this.lastHeartbeatAck = true, this.clearHeartbeatTimeoutTimer();
+        return;
+      }
+      try {
+        var a = this.options.parser || b;
+        (r = (s = this.options).onMessage) == null || r.call(s, a(t), t);
+      } catch (a) {
+        (o = (n = this.options).onInvalidMessage) == null || o.call(n, a, t);
+      }
+    }
+  }, {
+    key: "handleClose",
+    value: function handleClose(t) {
+      var e, s;
+      if (this.clearHeartbeatTimers(), (s = (e = this.options).onClose) == null || s.call(e, t), this.manualClosed) {
+        this.setState("closed");
+        return;
+      }
+      this.scheduleReconnect();
+    }
+  }, {
+    key: "handleError",
+    value: function handleError(t) {
+      var e, s;
+      (s = (e = this.options).onError) == null || s.call(e, t);
+    }
+  }, {
+    key: "startHeartbeat",
+    value: function startHeartbeat() {
+      var _this2 = this;
+      var t = this.options.heartbeat;
+      !(t != null && t.message) || !t.interval || (this.clearHeartbeatTimers(), this.heartbeatTimer = setInterval(function () {
+        if (!_this2.ws || _this2.ws.readyState !== WebSocket.OPEN) return;
+        if (t.timeout && !_this2.lastHeartbeatAck) {
+          _this2.closeSocket(), _this2.scheduleReconnect();
+          return;
+        }
+        var e = typeof t.message == "function" ? t.message() : t.message;
+        _this2.lastHeartbeatAck = false, _this2.send(e), t.timeout && (_this2.clearHeartbeatTimeoutTimer(), _this2.heartbeatTimeoutTimer = setTimeout(function () {
+          _this2.lastHeartbeatAck || _this2.manualClosed || (_this2.closeSocket(), _this2.scheduleReconnect());
+        }, t.timeout));
+      }, t.interval));
+    }
+  }, {
+    key: "scheduleReconnect",
+    value: function scheduleReconnect() {
+      var _this3 = this;
+      var t = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : "reconnecting";
+      var n;
+      if (this.manualClosed || !((n = this.options.reconnect) != null && n.enabled)) {
+        this.setState("closed");
+        return;
+      }
+      if ((typeof navigator === "undefined" ? "undefined" : _typeof(navigator)) < "u" && navigator.onLine === false) {
+        this.setState(t);
+        return;
+      }
+      var _this$options$reconne = this.options.reconnect,
+        e = _this$options$reconne.maxAttempts,
+        s = _this$options$reconne.jitter;
+      if (typeof e == "number" && e >= 0 && this.reconnectAttempts >= e) {
+        this.setState("closed");
+        return;
+      }
+      this.reconnectAttempts += 1;
+      var r = this.getReconnectDelay();
+      this.setState(t), this.clearReconnectTimer(), this.reconnectTimer = setTimeout(function () {
+        if (s) {
+          setTimeout(function () {
+            return _this3.openSocket();
+          }, Math.floor(Math.random() * 300));
+          return;
+        }
+        _this3.openSocket();
+      }, r);
+    }
+  }, {
+    key: "getReconnectDelay",
+    value: function getReconnectDelay() {
+      var t = this.options.reconnect || {
+          enabled: false
+        },
+        e = t.delay || l,
+        s = t.maxDelay || u;
+      return Math.min(e * Math.pow(2, Math.max(0, this.reconnectAttempts - 1)), s);
+    }
+  }, {
+    key: "handleOnline",
+    value: function handleOnline() {
+      !this.started || this.manualClosed || this.state === "open" || this.state === "connecting" || this.openSocket();
+    }
+  }, {
+    key: "handleOffline",
+    value: function handleOffline() {
+      this.manualClosed || (this.clearReconnectTimer(), this.closeSocket(), this.setState("reconnecting"));
+    }
+  }, {
+    key: "setState",
+    value: function setState(t) {
+      var e, s;
+      this.state !== t && (this.state = t, (s = (e = this.options).onStateChange) == null || s.call(e, t));
+    }
+  }, {
+    key: "closeSocket",
+    value: function closeSocket() {
+      var t = this.ws;
+      t && (t.onopen = null, t.onmessage = null, t.onclose = null, t.onerror = null, (t.readyState === WebSocket.OPEN || t.readyState === WebSocket.CONNECTING) && t.close(), this.ws = null);
+    }
+  }, {
+    key: "clearTimers",
+    value: function clearTimers() {
+      this.clearHeartbeatTimers(), this.clearReconnectTimer();
+    }
+  }, {
+    key: "clearHeartbeatTimers",
+    value: function clearHeartbeatTimers() {
+      this.heartbeatTimer && clearInterval(this.heartbeatTimer), this.heartbeatTimer = null, this.clearHeartbeatTimeoutTimer();
+    }
+  }, {
+    key: "clearHeartbeatTimeoutTimer",
+    value: function clearHeartbeatTimeoutTimer() {
+      this.heartbeatTimeoutTimer && clearTimeout(this.heartbeatTimeoutTimer), this.heartbeatTimeoutTimer = null;
+    }
+  }, {
+    key: "clearReconnectTimer",
+    value: function clearReconnectTimer() {
+      this.reconnectTimer && clearTimeout(this.reconnectTimer), this.reconnectTimer = null;
+    }
+  }, {
+    key: "removeNetworkListeners",
+    value: function removeNetworkListeners() {
+      (typeof window === "undefined" ? "undefined" : _typeof(window)) > "u" || (window.removeEventListener("online", this.handleOnline), window.removeEventListener("offline", this.handleOffline));
+    }
+  }]);
+}();
+var g = function g(i) {
+  return new S(i);
+};
+exports.RealtimeSocketClient = S;
+exports.createRealtimeSocketClient = g;

package/realtime-connection/index.d.ts

@@ -0,0 +1,70 @@
+export type RealtimeSocketState = 'idle' | 'waiting-token' | 'connecting' | 'open' | 'reconnecting' | 'closed' | 'unsupported';
+export type RealtimeSocketHeartbeatOptions = {
+    message: string | (() => string);
+    interval: number;
+    timeout?: number;
+    response?: string | string[];
+};
+export type RealtimeSocketReconnectOptions = {
+    enabled: boolean;
+    delay?: number;
+    maxDelay?: number;
+    maxAttempts?: number;
+    jitter?: boolean;
+};
+export type RealtimeSocketClientOptions<T = unknown> = {
+    url: string;
+    params?: Record<string, any>;
+    tokenParamName?: string;
+    tokenProvider?: () => string | Promise<string>;
+    heartbeat?: RealtimeSocketHeartbeatOptions;
+    reconnect?: RealtimeSocketReconnectOptions;
+    parser?: (event: MessageEvent) => T;
+    onOpen?: (event: Event) => void;
+    onMessage?: (message: T, event: MessageEvent) => void;
+    onClose?: (event: CloseEvent) => void;
+    onError?: (event: Event) => void;
+    onInvalidMessage?: (error: unknown, event: MessageEvent) => void;
+    onStateChange?: (state: RealtimeSocketState) => void;
+};
+export declare class RealtimeSocketClient<T = unknown> {
+    private ws;
+    private options;
+    private state;
+    private heartbeatTimer;
+    private heartbeatTimeoutTimer;
+    private reconnectTimer;
+    private reconnectAttempts;
+    private manualClosed;
+    private started;
+    private lastHeartbeatAck;
+    constructor(options: RealtimeSocketClientOptions<T>);
+    /** 获取当前连接状态，供业务显示或调试兜底使用。 */
+    getState(): RealtimeSocketState;
+    /** 建立连接；重复调用不会创建多个活动 WebSocket。 */
+    connect(): Promise<void>;
+    /** 仅在连接已打开时发送消息，失败时返回 false。 */
+    send(message: string | ArrayBufferLike | Blob | ArrayBufferView): boolean;
+    /** 主动关闭连接，并清理心跳、重连和网络监听。 */
+    close(): void;
+    private openSocket;
+    private resolveToken;
+    private handleOpen;
+    private handleMessage;
+    private handleClose;
+    private handleError;
+    private startHeartbeat;
+    private scheduleReconnect;
+    private getReconnectDelay;
+    private handleOnline;
+    private handleOffline;
+    private setState;
+    private closeSocket;
+    private clearTimers;
+    private clearHeartbeatTimers;
+    private clearHeartbeatTimeoutTimer;
+    private clearReconnectTimer;
+    private removeNetworkListeners;
+}
+/** 创建独立实时连接实例，调用方负责在卸载时 close。 */
+export declare const createRealtimeSocketClient: <T = unknown>(options: RealtimeSocketClientOptions<T>) => RealtimeSocketClient<T>;