@63mmo/api

63MMO 网关编程客户端：HTTP + WebSocket 的 isomorphic 封装，供玩家脚本、 CI 与第三方工具调用。发布产物零运行时依赖（Node ≥22 原生 fetch/WebSocket，浏览器原生）；prepack 时经 tsc + esbuild 产出 dist/——npm 安装即可在纯 Node 直跑，无需 tsx/打包器。

• GatewayApi：REST（账号/部署/永久令牌/模板），isomorphic fetch
• connectWorld：WS 世界帧流（play/live 双模式、自动 pong、指数退避重连）
• 帧类型来自 @63mmo/protocol（ServerFrame/ClientFrame 等，随本包再导出）

源码形态（本仓库内 / git 直引）入口是 .ts，消费方需 bundler 或 tsx； TS 消费方建议 moduleResolution: "bundler"（@63mmo/protocol 的类型 入口是源码形态）。

快速开始

npm install @63mmo/api

import { GatewayApi, connectWorld } from "@63mmo/api";

// 1. 登录（或用你在游戏页面创建的永久令牌——不随登出吊销）
const api = new GatewayApi({ baseUrl: "http://127.0.0.1:9165" });
const auth = await api.login("alice", "secret");
api.setToken(auth.token);

// 2. 部署代码（lint + 影子运行 + 版本化；两次部署至少间隔 3s）
const out = await api.deploy("function loop() { /* ... */ }");
await api.activate(out.versionId); // 下一 tick 生效

// 3. 永久令牌（页面管理面的编程入口；上限 10 条命名令牌）
const tok = await api.createToken("ci");
// 之后：new GatewayApi({ baseUrl }).setToken(tok.token) 即可长期使用
// await api.revokeToken(tok.token)  // 吊销

// 4. 世界帧流（play 模式 = 玩家视角视野过滤帧；无 token = live 全量观战）
const conn = connectWorld({
  url: "ws://127.0.0.1:9165/ws",
  token: auth.token,
  onFrame: (frame) => {
    if (frame.t === "delta") console.log("tick", frame.delta.tick);
  },
});
// conn.close();

浏览器里 baseUrl/url 可缺省（同源推导，配 Vite 代理 /api、/ws）。

错误约定

• REST 非 2xx 一律抛 ApiStatusError：message 优先取服务端 {error} 字段（反代回 HTML 等非 JSON 错误体时回退状态行），status 保留 HTTP 状态码——401 = 令牌无效/被吊销，429 = 部署冷却
• WS 的 error 帧经 onFrame 透传；协议版本失配时连接自动停止单元 （onNotice("alert", …)）
• 用命名令牌调 logout() 会被服务端拒绝（400）——logout 是会话语义， 吊销命名令牌请用 revokeToken()

端点一览

| 方法 | 网关端点 | 说明 | |---|---|---| | register | POST /api/register | 玩家名 + 邮箱 + 密码 | | login / logout | POST /api/login / POST /api/logout | 会话令牌（登出即吊销） | | me | GET /api/me | 账号档案 + 当前 tick 节拍 | | spawn / rebirth | POST /api/spawn / POST /api/rebirth | 地图选点出生/重生 | | deploy | POST /api/deploy | 上传代码（3s 冷却） | | activate | POST /api/deploy/{id}/activate | 激活/回滚版本 | | versions | GET /api/versions | 版本列表（可选携带源码） | | templates | GET /api/templates | 官方 bot 模板 | | listTokens | GET /api/tokens | 全部令牌（明文 + lastUsedAt） | | createToken | POST /api/tokens | 创建永久命名令牌 | | revokeToken | DELETE /api/tokens/{token} | 吊销 | | connectWorld | GET /ws（升级） | hello(token) + subscribe(play|live) |

线上协议格式（JSON 文本帧、tag "t"、camelCase）见 @63mmo/protocol 与 docs/tech/02「客户端架构」。