NixMsg/sdk/js/README.md

NixMsg JavaScript / TypeScript SDK

包名 @nixevol/nixmsg。支持 Node.js ≥ 20 与浏览器；发布 ESM 与 CJS。

安装

在 .npmrc 中：

@nixevol:registry=https://git.asio.asia/api/packages/nixevol/npm/

然后：

npm install @nixevol/nixmsg

许可证字段为 SEE LICENSE IN LICENSE（专有），包内附带仓库根目录 LICENSE 副本。

最小示例

见 example/minimal.mjs：

import { Client, register } from "@nixevol/nixmsg";

const c = new Client();
c.onSessionHandler((tok) => console.log("session", tok));
c.onMessageHandler((msg) => console.log("msg", msg.from, msg.body.data));
await c.connect("ws://127.0.0.1:7443/mqtt", "device-1", { password: "secret" });
await c.send(
  { kind: "endpoint", id: "device-2" },
  { enc: "utf8", data: "hello" },
  { delayMs: 0 },
);
await c.close();

浏览器页面与服务器不同源时，注册接口已回 Access-Control-Allow-Origin: *，WebSocket /mqtt 不校验 Origin，可直接连接。

行为约定

四种 SDK 同一套对外语义，详见仓库 docs/DEVELOPMENT.md 第 9 节附录「SDK 行为约定」。要点：

• 首次连接默认 30 秒内未握手则停止重连，connect() 返回 not_connected；Client 可再次 connect。
• 顶号原因一律 taken_over；DISCONNECT 0x8B 可重试；CONNECT 不带 Receive Maximum；心跳默认 30 秒。
• 重连退避只维护一个计数 n：第 n 次等待 min(1s×2^(n-1), 30s)×随机(0.7,1.3)。仅 connect 后第一次可不等待；断线后首次重连也约 1 秒；在线不足 60 秒断开则 n+1，稳定 60 秒后断开 n=1。不要用「attempt 与 base 同时翻倍」。
• rate_limited 与断线重交：每次重新生成 rid 并重新序列化；消息 id、正文、send_at_ms 不变。
• logout 请求失败返回给应用；本地仍停止重连、清空令牌、结束队列并发 offline。
• 时长与时间戳用 64 位整数。sendAt 与 delay 同时给时本地 bad_request。停止重连后再 send 立即失败。
• 取消尚未发出的条目即出队；已发出的返回 result_unknown，应用应以同一消息号重试。

打包试运行

npm pack --dry-run

不要对本仓库执行 npm publish（发布由阶段 3 总控完成）。