jx3api-ts

Type-safe Node.js SDK for JX3 API，覆盖全部 HTTP 接口和 WebSocket 实时事件。

• 零运行时依赖 — 仅使用 Node.js 22+ 原生 fetch 和 WebSocket
• 完整类型定义 — 80+ HTTP API 请求/响应类型 + 38 种 WebSocket 事件类型
• ESM Only — target: ES2024，module: NodeNext
• Token/Ticket 自动注入 — 构造时传入一次，所有请求自动携带

安装

npm install jx3api-ts

要求 Node.js >= 22.0.0

快速上手

import { JX3API } from "jx3api-ts";

const api = new JX3API({
  token: "YOUR_TOKEN",   // API 令牌
  ticket: "YOUR_TICKET", // 推栏 Ticket（可选）
});

HTTP API

// 查询角色信息
const role = await api.role.detail({ server: "唯我独尊", name: "夜温言" });
console.log(role.data.forceName); // "万花"

// 活动日历
const calendar = await api.active.calendar({ server: "长安城" });
console.log(calendar.data.war);

// 开服状态
const status = await api.status.check({ server: "长安城" });
console.log(status.data.status); // "爆满"

// 骚话
const saohua = await api.saohua.random();
console.log(saohua.data.text);

WebSocket 实时事件

const ws = api.socket();

// 奇遇报时
ws.on(1001, (detail) => {
  console.log(`${detail.name} 触发了 ${detail.event}`);
});

// 开服报时
ws.on(2001, (detail) => {
  console.log(`${detail.server} ${detail.status === 1 ? "开服" : "维护"}`);
});

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

// 连接状态
ws.onOpen(() => console.log("已连接"));
ws.onClose((code, reason) => console.log("断开", code, reason));

// 关闭连接
ws.close();

WebSocket 内置心跳保活（30s 间隔）和指数退避自动重连。可通过配置关闭：

const ws = api.socket({ autoReconnect: false });

配置项

JX3API 构造参数

| 参数 | 类型 | 默认值 | 说明 | |---|---|---|---| | token | string | "" | API 令牌 | | ticket | string | "" | 推栏 Ticket | | baseUrl | string | "https://www.jx3api.com" | API 基础地址 | | timeout | number | 30000 | 请求超时（毫秒） |

socket() 参数

| 参数 | 类型 | 默认值 | 说明 | |---|---|---|---| | url | string | "wss://socket.jx3api.com" | WebSocket 地址 | | autoReconnect | boolean | true | 自动重连 | | maxReconnects | number | Infinity | 最大重连次数 |

完整 API 列表

免费接口 (USER)

| 方法 | 说明 | |---|---| | api.active.calendar() | 活动日历 | | api.active.listCalendar() | 活动月历 | | api.active.celebs() | 行侠事件 | | api.exam.search() | 科举答题 | | api.home.flower() | 家园鲜花 | | api.home.furniture() | 家园装饰 | | api.home.travel() | 器物图谱 | | api.news.allnews() | 新闻资讯 | | api.news.announce() | 维护公告 | | api.master.search() | 搜索区服 | | api.status.check() | 开服状态 | | api.skill.rework() | 技改记录 | | api.saohua.random() | 世界骚话 | | api.saohua.content() | 舔狗日记 |

会员接口 (VIP1 / VIP2)

| 方法 | 说明 | |---|---| | api.active.monster() | 百战首领 | | api.active.nextEvent() | 扶摇预测 | | api.auction.records() | 阵营拍卖 | | api.steed.records() | 的卢记录 | | api.show.records() | 烟花记录 | | api.fraud.detail() | 骗子查询 | | api.event.records() | 角色奇遇 | | api.event.unfinished() | 未做奇遇 | | api.event.recent() | 近期奇遇 | | api.event.statistics() | 奇遇统计 | | api.event.collect() | 奇遇汇总 | | api.arena.recent() | 名剑战绩 | | api.arena.awesome() | 名剑排行 | | api.arena.schools() | 名剑统计 | | api.recruit.search() | 团队招募 | | api.mentor.search() | 师徒系统 | | api.rank.statistics() | 本服榜单 | | api.rank.trials() | 试炼排行 | | api.reward.statistics() | 掉落统计 | | api.role.detail() | 角色信息 | | api.role.monster() | 角色百战 | | api.card.record() | 角色名片 | | api.card.records() | 所有名片 | | api.card.cached() | 缓存名片 | | api.raid.records() | 副本记录 | | api.school.matrix() | 心法阵眼 | | api.school.talent() | 奇穴详情 | | api.school.skills() | 技能详情 | | api.school.seniority() | 资历排行 | | api.sand.records() | 阵营沙盘 | | api.fenxian.records() | 阵营事件 | | api.smite.records() | 诛恶事件 | | api.mine.cart() | 关隘首领 | | api.chitu.records() | 本日赤兔 | | api.chitu.weekRecords() | 本周赤兔 | | api.ranch.records() | 马场刷新 | | api.tieba.itemRecords() | 贴吧物价 | | api.trade.demon() | 金币价格 | | api.trade.records() | 黑市物价 | | api.trade.itemSearch() | 搜索物品 | | api.trade.itemRecords() | 物品价格 | | api.battle.records() | 帮战记录 | | api.mech.calculator() | 副本解密 | | api.duowan.statistics() | 统战歪歪 | | api.tieba.random() | 八卦帖子 | | api.sound.converter() | 阿里语音 |

WebSocket 事件

| Action | 说明 | |---|---| | 1001 | 奇遇报时 | | 1002 | 刷马事件 | | 1003 | 抓马事件 | | 1004 | 扶摇预告 | | 1005 | 扶摇开启 | | 1006 | 扶摇点名 | | 1007 | 烟花报时 | | 1008 | 的卢预告 | | 1009 | 的卢刷新 | | 1010 | 的卢捕获 | | 1011 | 的卢拍卖 | | 1012 | 玄晶报时 | | 1013 | 阵营拍卖 | | 1014 | 诛恶事件 | | 1015 | 追魂点名 | | 1016 | 阵营祭天预告 | | 1017 | 阵营祭天终点 | | 1101 | 领地宣战开始 | | 1102 | 领地宣战结束 | | 1108 | 帮会野外宣战开始 | | 1109 | 帮会野外宣战结束 | | 1111 | 抢占粮仓 | | 1112 | 大旗重置 | | 1113 | 大旗被夺 | | 1114 | 据点占领（有帮会） | | 1115 | 据点占领（无帮会） | | 1116~1118 | 贡献排行 | | 1119 | 攻防拍卖 | | 1120 | 拍卖分红（小攻防） | | 1121 | 拍卖分红（大攻防） | | 1122 | 拍卖分红（大攻防+指挥） | | 2001 | 开服报时 | | 2002 | 新闻资讯 | | 2003 | 游戏更新 | | 2004 | 八卦速报 | | 2005 | 关隘首领 | | 2006 | 云丛预告 |

错误处理

import { JX3ApiError } from "jx3api-ts";

try {
  await api.role.detail({ server: "不存在", name: "test" });
} catch (err) {
  if (err instanceof JX3ApiError) {
    console.log(err.code); // API 错误码
    console.log(err.msg);  // 错误信息
    console.log(err.path); // 请求路径
  }
}

License

MIT