@easecation/ecapi-sdk

ECAPI 的 Node.js / TypeScript SDK。SDK 同时提供两层入口：

• ECAPIClient：推荐给业务代码使用的人类友好门面，按领域分组，由 OpenAPI 生成并覆盖当前全部 160 个接口。
• generated：Orval 从 openapi.json 生成的完整低层函数与响应类型，适合需要精确状态码联合类型的场景。

安装

npm install @easecation/ecapi-sdk

项目内开发请使用仓库根目录命令重新生成和构建：

yarn generate:openapi
yarn generate:sdk
yarn type-check:sdk
yarn --cwd sdk/npm/ecapi-sdk build

快速开始

import { ECAPIClient, isECAPIError } from '@easecation/ecapi-sdk';

const client = new ECAPIClient({
  baseUrl: 'https://api.easecation.net',
  apiKey: process.env.EC_API_KEY,
  timeoutMs: 15_000,
});

try {
  const me = await client.user.getMe();
  const player = await client.player.getInfo({ displayName: 'Steve' });

  console.log(me.data, player.data);
} catch (error) {
  if (isECAPIError(error)) {
    console.error(error.status, error.code, error.requestId, error.message);
  }
  throw error;
}

认证方式

ECAPIClient 支持构造时配置，也支持运行时切换：

const client = new ECAPIClient({ apiKey: process.env.EC_API_KEY });

client.setApiKey('ec_xxx');
client.setBearerToken(process.env.EC_IAM_ACCESS_TOKEN!);
client.setAppSessionToken(process.env.EC_APP_SESSION_TOKEN!);
client.clearAuth();

也可以使用更显式的 auth：

new ECAPIClient({
  auth: { type: 'bearer', token: process.env.EC_TOKEN! },
});

如果认证来自 IAM callback、短期 token 或其它异步来源，可以使用 authProvider。ECAPIClient、configureECAPIFetch 和 createECAPIFetch 都支持它，SDK 会在每次请求前调用：

const client = new ECAPIClient({
  authProvider: async () => {
    const token = await getAppSessionTokenFromIamCallback();
    return token ? { type: 'appSessionToken', appSessionToken: token } : null;
  },
});

认证优先级：

1. 单次请求 options.auth 最高；传 null 表示本次请求不发送认证，也不会调用 authProvider。
2. 客户端 authProvider 次之；返回 null/undefined 表示本次请求不发送认证。
3. 客户端静态 auth、apiKey、appSessionToken、bearerToken、jwt 作为兼容简写。

SDK 不做 401 自动重试；如果 token 需要刷新，请在 IAM callback / authProvider 侧处理，下一次请求会重新解析认证。

类型提示与 Docstring

• client.player.getInfo({ displayName: '...' }) 这类方法会提示 query/body 的必填字段、字段类型和字段说明。
• 常用 DTO 类型可直接从顶层导入，例如 ReplayVisualizationDatasetDto；需要低层状态码联合类型时仍可使用 generated 命名空间。
• apis.ts、method-signatures.d.ts、API Reference 与 Python stub 均由 sdk/generate_sdk_api_reference.py 从 openapi.json 自动生成。
• Query、Body、路径、权限和成功响应类型都从 OpenAPI schema 推断；新增后端接口会在生成时自动进入门面并接受覆盖检查。
• 每个方法的 JSDoc 包含接口说明与所需权限；完整表格见 API_REFERENCE.md。
• 响应体保持服务端统一 envelope；常规 JSON 接口会直接提示对应 OpenAPI 成功响应类型。

常用调用

await client.system.getHealth();
await client.system.getLiveness();
await client.system.getReadiness();

await client.player.searchEcid({ search: 'Steve' });
await client.player.cutoffLeaderboard.getLeaderboard({ game: 'bedwar' });
await client.server.leaderboard.getTop({
  game: 'labour',
  scoreType: 'ONLINE',
  deadlineType: 'WEEK',
});
await client.player.leaderboard.getRank('player-ecid', {
  game: 'labour',
  scoreType: 'ONLINE',
  deadlineType: 'MONTH',
});
await client.replay.getReplayRecord(123456);
await client.punish.create({
  type: 'WARNING',
  ecid: 'player-ecid',
  source: 'console',
  reason: '测试警告',
});

未封装或临时接口可以直接走统一请求入口：

const result = await client.request('GET', '/players/info', {
  query: { displayName: 'Steve' },
});

生成式 SDK

生成式函数默认返回 Orval 风格 { data, status, headers }，其中 data 是服务端响应 payload。 Node.js 中使用相对路径前需要配置 baseUrl：

import { configureECAPIFetch, generated, patchECAPIFetchConfig } from '@easecation/ecapi-sdk';

configureECAPIFetch({
  baseUrl: 'http://localhost:8083',
  bearerToken: process.env.EC_TOKEN,
});

// configureECAPIFetch 会替换全局配置；如需只补充 header 或 token，使用 patchECAPIFetchConfig。
patchECAPIFetchConfig({ defaultHeaders: { 'X-Trace-Id': 'trace-1' } });

const res = await generated.healthControllerCheck();
console.log(res.status, res.data);

如果你只想要 payload 本身，可使用绑定配置的 createECAPIFetch() 或 ECAPIClient。

错误处理

非 2xx 响应、网络错误和超时都会抛出 ECAPIError：

try {
  await client.permission.getPermission('player-ecid');
} catch (error) {
  if (isECAPIError(error)) {
    console.log({
      status: error.status,
      code: error.code,
      requestId: error.requestId,
      details: error.details,
      message: error.message,
    });
  }
}

字段说明：

• status：HTTP 状态码；网络错误或取消为 0。
• message：优先来自服务端 error.message / message。
• code：来自服务端 error.code，例如 VALIDATION_ERROR。
• requestId：来自响应 envelope 或 x-request-id header。
• payload：完整错误响应，便于调试或上报。

二进制响应

手写门面中的二进制接口会返回 ArrayBuffer：

const headIcon = await client.player.getHeadicon('player-ecid');

生成式 SDK 对非 JSON 响应会把 Blob 放在 { data } 中；手写门面会按方法语义返回 ArrayBuffer 或 string。

API 覆盖

当前 ECAPIClient 门面由 openapi.json 生成并覆盖全部 160 个接口。主要分组包括：

• client.auth、client.user
• client.player、client.player.score、client.player.cutoffLeaderboard
• client.punish、client.permission、client.admin
• client.log、client.audit、client.gamelog
• client.stage、client.item、client.cfglang、client.globalKV、client.broadcast
• client.order、client.count、client.servers、client.lobby、client.easechat
• client.monitor.spamDetector、client.pullConfig、client.system

完整方法、权限和参数请查看 API_REFERENCE.md。

契约说明

SDK 只面向新的 REST/OpenAPI 契约，不提供旧路径兼容别名。接口路径、权限、参数说明以 openapi.json 和 Swagger 文档为准；yarn check:sdk-contracts 会校验门面对 OpenAPI 的双向覆盖。