finej3-ws

Type-safe Node.js client for JX3 API WebSocket events.

• 零运行时依赖
• 39 种实时事件的完整 TypeScript 类型
• 内置心跳保活和指数退避自动重连
• 同时支持 ESM import 和 CommonJS require

要求 Node.js >= 22.0.0

安装

npm install finej3-ws

快速上手

import { JX3Socket } from "finej3-ws";

const ws = new JX3Socket({
  token: "YOUR_TOKEN",
}).connect();

// 奇遇触发，detail 自动推导为 Socket1001Detail
ws.on(1001, (detail) => {
  console.log(`${detail.name} 触发了 ${detail.event}`);
});

// 开服状态
ws.on(2001, (detail) => {
  console.log(`${detail.server} ${detail.status}`);
});

// 监听所有事件
ws.onAny((action, detail) => {
  console.log(`[${action}]`, detail);
});

ws.onOpen(() => console.log("已连接"));
ws.onClose((code, reason) => console.log("连接关闭", code, reason));
ws.onError((error) => console.error("连接错误", error));

// 不再使用时主动关闭
ws.close();

配置

const ws = new JX3Socket({
  url: "wss://socket.nicemoe.cn",
  token: "YOUR_TOKEN",
  autoReconnect: true,
  maxReconnects: Infinity,
}).connect();

| 参数 | 类型 | 默认值 | 说明 | |---|---|---|---| | url | string | "wss://socket.nicemoe.cn" | WebSocket 地址 | | token | string | "" | 身份验证 Token | | autoReconnect | boolean | true | 断线后自动重连 | | maxReconnects | number | Infinity | 最大连续重连次数 |

心跳间隔为 30 秒。重连延迟从 1 秒开始指数增长，最高为 30 秒；连接成功后会重置重连次数。

监听管理

import type { Socket1001Detail } from "finej3-ws";

const onAdventure = (detail: Socket1001Detail) => {
  console.log(detail);
};

ws.on(1001, onAdventure);
ws.off(1001, onAdventure);

const onAnyEvent = (action: number, detail: unknown) => {
  console.log(action, detail);
};

ws.onAny(onAnyEvent);
ws.offAny(onAnyEvent);

console.log(ws.connected);

事件类型可以从主入口或 finej3-ws/types 导入：

import type {
  SocketAction,
  SocketEventMap,
  Socket1001Detail,
} from "finej3-ws/types";

WebSocket 客户端也可以通过子路径导入：

import { JX3Socket } from "finej3-ws/socket";

支持的事件

| Action | 说明 | |---|---| | 1001 | 奇遇触发 | | 1002 | 马驹刷新 | | 1003 | 马驹捕获 | | 1005 | 扶摇开启 | | 1006 | 扶摇点名 | | 1008 | 的卢每日 | | 1009 | 的卢刷新 | | 1010 | 的卢捕获 | | 1011 | 的卢拍卖 | | 1012 | 副本掉落 / 私货 | | 1013 | 阵营拍卖 | | 1014 | 诛恶事件 | | 1015 | 追魂点名 | | 1017 | 阵营祭祀 | | 1018 | 关隘首领 | | 1101 | 领地宣战开始 | | 1102 | 领地宣战结束 | | 1103 | 帮会宣战开始 | | 1104 | 帮会宣战结束 | | 1105 | 帮会约战完胜 | | 1111 | 抢占粮仓 | | 1112 | 大旗重置 | | 1113 | 大旗被夺 | | 1114 | 据点占领（有帮会） | | 1115 | 据点占领（无帮会） | | 1116 | 小攻防贡献（非开战） | | 1117 | 小攻防贡献 | | 1118 | 大攻防贡献 | | 1119 | 战利品竞拍 | | 1120 | 小攻防分红 | | 1121 | 大攻防分红 | | 1122 | 大攻防分红（含指挥） | | 1201 | 微博更新 | | 2001 | 开服状态 | | 2002 | 官方新闻 | | 2003 | 版本更新 | | 2004 | 八卦速报 | | 2005 | 关隘首领 | | 2006 | 云从预告 |

License

MIT