@easecation/ecapi-sdk 0.1.1 → 0.1.3

package/README.md

@@ -17,7 +17,6 @@ npm install @easecation/ecapi-sdk
 import { ECAPIClient } from "@easecation/ecapi-sdk";
 
 const client = new ECAPIClient({
-  baseUrl: "https://your-ecapi-host",
   auth: { type: "apiKey", apiKey: process.env.EC_API_KEY! },
 });
 
@@ -33,11 +32,25 @@ client.setAppSessionToken(process.env.EC_APP_SESSION_TOKEN!);
 
 ## 客户端能力
 
+- 默认 `baseUrl`：`https://console.easecation.net/apiv2`
 - 统一请求入口：`client.request(method, path, options)`
 - 默认超时：15s（可在构造时 `timeoutMs` 覆盖）
 - 支持 per-request 覆盖鉴权：`options.auth`
 - 非 2xx 响应抛出 `ECAPIError`（包含 `status`、`payload`、`url`）
 
+## 参数传递（必填/可选）
+
+- 所有查询参数统一通过对象传入：`client.player.getWallet({ ecid: "..." })`
+- `QueryParams` 已补齐服务端常用 query key 自动提示
+- 每个 API 的必填/可选参数请查看：`API_REFERENCE.md`
+- 该参考文档由后端 OpenAPI 自动生成，和服务端校验保持一致
+
+## IDE 强类型提示
+
+- 包内提供方法级类型增强文件 `method-signatures.d.ts`
+- 调用每个 API 时，IDE 会提示该方法对应的 `Query` / `Body` 类型
+- 必填字段会在 TypeScript 类型检查中直接报错，减少运行时试错
+
 ## API 覆盖
 
 > 下列为 SDK 已封装的主要接口，未覆盖部分可通过 `client.request(...)` 直接调用。
@@ -110,3 +123,13 @@ client.setAppSessionToken(process.env.EC_APP_SESSION_TOKEN!);
 - `client.monitor.spamDetector.*` → `/monitor/spam-detector/*`
 - `client.system.getHealth()` → `/health`
 
+## 完整 API 参考
+
+- `API_REFERENCE.md`
+
+更新命令（在 `easecation-api` 根目录执行）：
+
+```bash
+python3 sdk/generate_sdk_api_reference.py
+```
+

package/dist/apis.d.ts

@@ -15,74 +15,20 @@ declare class BaseApi {
     protected delete<T = unknown>(path: string, query?: QueryParams, options?: Omit<RequestOptions, "query">): Promise<T>;
 }
 export declare class UserApi extends BaseApi {
-    /**
-     * Get current user profile.
-     * Note: backend expects Authorization token for this endpoint in some deployments.
-     */
-    getMe(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    loginByPassword(payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
-    loginByOauth2(payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
-    refreshToken(payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
-    /**
-     * Get current user's OpenID.
-     * May return 404 if OpenID context is unavailable for current auth mode.
-     */
-    getOpenId(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    /** List all registered users (admin-scoped endpoint). */
-    listAll(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    updatePermissions(payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
-    /** Query user detail by user id. */
-    getById(id: string, query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
 }
 export declare class PlayerScoreApi extends BaseApi {
-    /**
-     * Get player score summary.
-     * Common required query: `nick`, `game`.
-     */
-    getScore(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    /** Get player score stages. Common required query: `nick`. */
-    getStages(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    /**
-     * Get top ranking records.
-     * Common required query: `game`, `score_type`, `deadline_type`, `limit`, `is_ascending`.
-     */
-    getTop(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    deleteTop(query?: QueryParams, options?: Omit<RequestOptions, "query">): Promise<unknown>;
-    getConfig(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    getLeaderboard(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
 }
 export declare class PlayerTasksApi extends BaseApi {
-    /**
-     * List tasks for one player.
-     * Common required query: `current`, `pageSize`.
-     */
-    list(ecid: string, query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    create(ecid: string, payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
     update(ecid: string, taskId: string, payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
     deleteOne(ecid: string, taskId: string, query?: QueryParams, options?: Omit<RequestOptions, "query">): Promise<unknown>;
 }
 export declare class PlayerMerchandiseApi extends BaseApi {
-    /**
-     * List merchandise items for one player.
-     * Common required query: `current`, `pageSize`.
-     */
-    list(ecid: string, query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    create(ecid: string, payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
     update(ecid: string, idItem: string, payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
     deleteOne(ecid: string, idItem: string, query?: QueryParams, options?: Omit<RequestOptions, "query">): Promise<unknown>;
 }
 export declare class PlayerYearSummaryApi extends BaseApi {
-    /** Get year summary basic info. Common required query: `ecid` (optional `year`). */
-    getBasicInfo(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    getLoginStats(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    getGameStats(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    getRankData(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    getCurrencyData(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    getSocialData(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
 }
 export declare class PlayerVoteApi extends BaseApi {
-    /** Process vote rewards. Common required query: `players` (semicolon-separated). */
-    processRewards(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
 }
 /** Player-related endpoints and nested modules. */
 export declare class PlayerApi extends BaseApi {
@@ -92,184 +38,51 @@ export declare class PlayerApi extends BaseApi {
     readonly yearSummary: PlayerYearSummaryApi;
     readonly vote: PlayerVoteApi;
     constructor(http: ECAPIHttpClient);
-    /** Get online/runtime player info. Common required query: `name`. */
-    getInfo(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    /** Search ECID by nickname/ecid keyword. Common required query: `name`. */
-    searchEcid(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    /** Get player profile data. Common required query: `ecid`. */
-    getUserData(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    /** Query NetEase player data. Common required query: `name`. */
-    queryNetease(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    setRankLevel(payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
-    clearRespackCache(query?: QueryParams, options?: Omit<RequestOptions, "query">): Promise<unknown>;
-    /** Get wallet info. Common required query: `ecid`. */
-    getWallet(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    listGamingTags(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    operateGamingTag(payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
-    /** Get recent play history. Common required query: `ecid`. */
-    getLastPlayed(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    /** Get stage records. Common required query: `ecid`, `start`, `end`. */
-    getStageRecord(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    /** Get player head icon as binary image data. Common required query: `ecid`. */
-    getHeadicon(query?: QueryParams, options?: Omit<RequestOptions, "query" | "responseType">): Promise<ArrayBuffer>;
-    /** Get player skin as binary image data. Common required query: `ecid`. */
-    getSkin(query?: QueryParams, options?: Omit<RequestOptions, "query" | "responseType">): Promise<ArrayBuffer>;
-    batchNeteaseNicknames(payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
-    /** Get player binding info. Common required query: `ecid`. */
-    getBinding(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    resetBinding(payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
-    updateBinding(payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
-    updateUserData(nick: string, payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
-    updatePassword(ecid: string, payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
-    /** Get password hash by ecid. */
-    getPasswordHash(ecid: string, query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
 }
 export declare class AdminApi extends BaseApi {
-    sendMail(payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
-    prismDeviceBan(payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
-    getPrismDeviceBanLog(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    upsertOverwatchCase(payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
-    /** Query overwatch case. Common required query: `record_id`. */
-    getOverwatchCase(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    /** Query admin operation logs. Common required query: `start`/`end` or `target_nick`. */
-    getOperationLogs(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    /** Query admin operation statistics. Common required query: `start`, `end`. */
-    getOperationStatistics(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
 }
 export declare class PunishApi extends BaseApi {
-    hack(payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
-    ban(payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
-    unban(payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
-    mute(payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
-    unmute(payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
-    warn(payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
-    kick(payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
-    clearDegree(payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
-    overwatch(payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
 }
 export declare class BanApi extends BaseApi {
-    ban(payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
-    clearDegree(payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
-    parkourPunish(query?: QueryParams, payload?: Record<string, unknown>, options?: Omit<RequestOptions, "query" | "body">): Promise<unknown>;
 }
 export declare class PermissionApi extends BaseApi {
-    /** Get player permission. Common required query: `ecid`. */
-    getPermission(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    upsert(payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
-    deleteOne(query?: QueryParams, options?: Omit<RequestOptions, "query">): Promise<unknown>;
 }
 export declare class LogApi extends BaseApi {
-    /** Query action log. Common required query: `start`, `end`, `ecid`. */
-    getAction(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    getChat(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    getAuth(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    /** Query teaming log. Common required query: `start`, `end`, `current`, `ecid`. */
-    getTeaming(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    getLatestTeaming(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    /** Query command log. Common required query: `start`, `end`, `current`, `ecid`. */
-    getCommand(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    getMail(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
 }
 export declare class OrderApi extends BaseApi {
-    /** Query delivery status. Common required query: `key`, `ecid`. */
-    getDeliver(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    /** Query order logs. Common required query: `ecid`. */
-    getLogs(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    /** Query exchange logs. Common required query: `ecid`, `from`, `to`. */
-    getExchangeLogs(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    /** Get download task count. Common required query: `from`, `to`. */
-    getDownloadCount(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    createDownloadTask(query?: QueryParams, payload?: Record<string, unknown>, options?: Omit<RequestOptions, "query" | "body">): Promise<unknown>;
-    /** Get one download task status. Common required query: `downloadId`. */
-    getDownloadStatus(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    listDownloadTasks(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
 }
 export declare class StageLogApi extends BaseApi {
-    list(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    query(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
 }
 export declare class StageApi extends BaseApi {
     readonly logs: StageLogApi;
     constructor(http: ECAPIHttpClient);
-    getTypes(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    create(payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
-    /** Query stage info by filters such as game/state/runtimeid/requestid. */
-    getInfo(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    /** Query stage DB id. Common required query: `runtime-id`. */
-    getDbId(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
 }
 export declare class ItemApi extends BaseApi {
-    getCommodity(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
 }
 export declare class CountApi extends BaseApi {
-    getHistory(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    getLatest(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    getTypes(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
 }
 export declare class ServersApi extends BaseApi {
-    list(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    getStatistics(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    getMainstackEvent(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
 }
 export declare class LobbyApi extends BaseApi {
-    list(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
 }
 export declare class CfgLangApi extends BaseApi {
-    list(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    compare(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    deploy(payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
-    create(query: QueryParams | undefined, payload: Record<string, unknown>, options?: Omit<RequestOptions, "query" | "body">): Promise<unknown>;
-    update(query: QueryParams | undefined, payload: Record<string, unknown>, options?: Omit<RequestOptions, "query" | "body">): Promise<unknown>;
-    deleteOne(query?: QueryParams, options?: Omit<RequestOptions, "query">): Promise<unknown>;
 }
 export declare class GlobalKVApi extends BaseApi {
-    list(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    getOne(key: string, query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    create(payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
-    update(key: string, payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
-    deleteOne(key: string, query?: QueryParams, options?: Omit<RequestOptions, "query">): Promise<unknown>;
-    deleteBatch(payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
 }
 export declare class BroadcastApi extends BaseApi {
-    list(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    compare(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    deploy(payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
-    getOne(msg: string, query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    create(payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
-    update(msg: string, payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
-    deleteOne(msg: string, payload?: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
 }
 export declare class EaseChatApi extends BaseApi {
-    sendHlaba(payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
-    listSubscriptions(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    createSubscription(payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
-    deleteSubscription(query?: QueryParams, options?: Omit<RequestOptions, "query">): Promise<unknown>;
 }
 export declare class AuditApi extends BaseApi {
-    getAuthLogs(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    getPlayerLogs(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    getPunishmentLogs(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    getPermissionLogs(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    getAdminLogs(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    getConfigLogs(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
 }
 export declare class SpamDetectorApi extends BaseApi {
-    getStatus(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    control(payload: Record<string, unknown>, options?: Omit<RequestOptions, "body">): Promise<unknown>;
-    getStats(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
 }
 export declare class MonitorApi extends BaseApi {
     readonly spamDetector: SpamDetectorApi;
     constructor(http: ECAPIHttpClient);
 }
 export declare class PullConfigApi extends BaseApi {
-    /** Pull current config snapshot. */
-    pull(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
 }
 export declare class SystemApi extends BaseApi {
-    /** Get API root text payload. */
-    getRoot(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
-    /** Health check endpoint. */
-    getHealth(query?: QueryParams, options?: NonBodyOptions): Promise<unknown>;
 }
 export {};

package/dist/http.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ECAPIHttpClient = exports.ECAPIError = void 0;
+const DEFAULT_BASE_URL = "https://console.easecation.net/apiv2";
 function normalizeBaseUrl(baseUrl) {
     return baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
 }
@@ -101,7 +102,7 @@ class ECAPIError extends Error {
 exports.ECAPIError = ECAPIError;
 class ECAPIHttpClient {
     constructor(options) {
-        this.baseUrl = normalizeBaseUrl(options.baseUrl);
+        this.baseUrl = normalizeBaseUrl(options.baseUrl ?? DEFAULT_BASE_URL);
         this.defaultHeaders = { ...(options.defaultHeaders || {}) };
         this.timeoutMs = options.timeoutMs ?? 15000;
         this.auth = options.auth;

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference path="../src/method-signatures.d.ts" />
 import { ECAPIError } from "./http";
 import { AdminApi, AuditApi, BanApi, BroadcastApi, CfgLangApi, CountApi, EaseChatApi, GlobalKVApi, ItemApi, LobbyApi, LogApi, MonitorApi, OrderApi, PermissionApi, PlayerApi, PullConfigApi, PunishApi, ServersApi, StageApi, SystemApi, UserApi } from "./apis";
 import { AuthCredentials, ClientOptions, RequestOptions } from "./types";

package/dist/index.js

@@ -15,6 +15,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ECAPIError = exports.ECAPIClient = void 0;
+/// <reference path="./method-signatures.d.ts" />
 const http_1 = require("./http");
 Object.defineProperty(exports, "ECAPIError", { enumerable: true, get: function () { return http_1.ECAPIError; } });
 const apis_1 = require("./apis");