@easecation/ecapi-sdk 3.0.6 → 3.0.12

package/README.md

@@ -65,7 +65,24 @@ new ECAPIClient({
 });
 ```
 
-单次请求可通过 `options.auth` 覆盖，传 `null` 表示本次请求不发送认证。
+如果认证来自 IAM callback、短期 token 或其它异步来源，可以使用 `authProvider`。`ECAPIClient`、`configureECAPIFetch` 和 `createECAPIFetch` 都支持它，SDK 会在每次请求前调用：
+
+```ts
+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
 

package/dist/client.d.ts

@@ -2,10 +2,12 @@
 import { AdminApi, AuditApi, AuthApi, BroadcastApi, CfgLangApi, CountApi, EaseChatApi, GamelogApi, GlobalKVApi, ItemApi, LobbyApi, LogApi, MonitorApi, OrderApi, PermissionApi, PlayerApi, PullConfigApi, PunishApi, ServersApi, StageApi, SystemApi, UserApi } from './apis';
 import { ECAPIError } from './errors';
 import { ECAPIHttpClient, HttpMethod } from './http';
-import { AuthCredentials, ClientOptions, HeaderMap, RequestOptions } from './types';
+import { AuthCredentials, AuthProvider, ClientOptions, HeaderMap, RequestOptions } from './types';
 export interface ECAPIClientConfig extends ClientOptions {
     /** API 根地址，默认 https://api.easecation.net。 */
     baseUrl?: string;
+    /** 动态默认认证；每次请求调用，优先于 auth 和 token 简写。 */
+    authProvider?: AuthProvider;
     /** IAM API Key 简写；与 auth 同时存在时优先使用 auth。 */
     apiKey?: string;
     /** App Session Token 简写；与 auth 同时存在时优先使用 auth。 */
@@ -56,6 +58,8 @@ export declare class ECAPIClient {
     request<T = unknown>(method: HttpMethod, path: string, options?: RequestOptions): Promise<T>;
     /** 设置默认认证。 */
     setAuth(auth?: AuthCredentials): void;
+    /** 设置动态默认认证；每次请求都会重新解析。 */
+    setAuthProvider(authProvider?: AuthProvider): void;
     /** 清空默认认证。 */
     clearAuth(): void;
     /** 使用 IAM API Key 作为默认认证。 */

package/dist/client.js

@@ -29,6 +29,7 @@ class ECAPIClient {
         this.http = new http_1.ECAPIHttpClient({
             baseUrl: config.baseUrl,
             auth: resolveAuth(config),
+            authProvider: config.authProvider,
             timeoutMs: config.timeoutMs ?? config.timeout,
             defaultHeaders: config.defaultHeaders,
         });
@@ -63,6 +64,10 @@ class ECAPIClient {
     setAuth(auth) {
         this.http.setAuth(auth);
     }
+    /** 设置动态默认认证；每次请求都会重新解析。 */
+    setAuthProvider(authProvider) {
+        this.http.setAuthProvider(authProvider);
+    }
     /** 清空默认认证。 */
     clearAuth() {
         this.http.clearAuth();

package/dist/custom-fetch.d.ts

@@ -1,4 +1,4 @@
-import type { ResponseType } from './types';
+import type { AuthProvider, ResponseType } from './types';
 export interface CustomFetchConfig {
     /** API 根地址；浏览器同源调用可以留空，Node.js 中建议显式配置。 */
     baseUrl?: string;
@@ -10,6 +10,8 @@ export interface CustomFetchConfig {
     bearerToken?: string;
     /** Bearer/JWT token 的简写别名，会写入 `Authorization: Bearer ...`。 */
     jwt?: string;
+    /** 动态默认认证；优先于静态 token 字段，每次请求前调用。 */
+    authProvider?: AuthProvider;
     /** 请求超时时间，单位毫秒，默认 30000。 */
     timeout?: number;
     /** 发送到每个请求的默认 header。 */

package/dist/custom-fetch.js

@@ -110,7 +110,20 @@ async function parsePayload(response, responseType) {
     }
     return response.arrayBuffer();
 }
-function applyAuth(headers, config) {
+function applyAuthCredentials(headers, auth) {
+    if (!auth)
+        return;
+    if (auth.type === 'apiKey' && !headers.has('X-API-Key')) {
+        headers.set('X-API-Key', auth.apiKey);
+    }
+    if (auth.type === 'appSessionToken' && !headers.has('X-App-Session-Token')) {
+        headers.set('X-App-Session-Token', auth.appSessionToken);
+    }
+    if ((auth.type === 'bearer' || auth.type === 'jwt') && !headers.has('Authorization')) {
+        headers.set('Authorization', `Bearer ${auth.token}`);
+    }
+}
+function applyStaticAuth(headers, config) {
     if (config.apiKey && !headers.has('X-API-Key')) {
         headers.set('X-API-Key', config.apiKey);
     }
@@ -122,6 +135,13 @@ function applyAuth(headers, config) {
         headers.set('Authorization', `Bearer ${bearer}`);
     }
 }
+async function applyAuth(headers, config) {
+    if (config.authProvider) {
+        applyAuthCredentials(headers, await config.authProvider());
+        return;
+    }
+    applyStaticAuth(headers, config);
+}
 /** 配置 Orval 生成式函数默认使用的 baseUrl、认证和超时。 */
 function configureECAPIFetch(config) {
     globalFetchConfig = {
@@ -160,7 +180,7 @@ async function customFetch(url, config = {}, fetchConfig) {
         shouldUseJsonContentType(config.body)) {
         headers.set('Content-Type', 'application/json');
     }
-    applyAuth(headers, effectiveConfig);
+    await applyAuth(headers, effectiveConfig);
     const timeout = config.timeout ?? effectiveConfig.timeout ?? 30000;
     const { signal, cleanup } = createTimeoutSignal(timeout, config.signal ?? undefined);
     const body = serializeBody(config.body);

package/dist/http.d.ts

@@ -1,4 +1,4 @@
-import { AuthCredentials, ClientOptions, RequestOptions } from './types';
+import { AuthCredentials, AuthProvider, ClientOptions, RequestOptions } from './types';
 import { ECAPIError } from './errors';
 export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
 export declare class ECAPIHttpClient {
@@ -6,11 +6,15 @@ export declare class ECAPIHttpClient {
     private readonly defaultHeaders;
     private readonly timeoutMs;
     private auth?;
+    private authProvider?;
     constructor(options: ClientOptions);
     setAuth(auth?: AuthCredentials): void;
+    /** 设置动态默认认证；每次请求都会重新解析。 */
+    setAuthProvider(authProvider?: AuthProvider): void;
     clearAuth(): void;
     setApiKey(apiKey: string): void;
     setAppSessionToken(appSessionToken: string): void;
+    private resolveAuth;
     request<T = unknown>(method: HttpMethod, path: string, options?: RequestOptions): Promise<T>;
 }
 export { ECAPIError };

package/dist/http.js

@@ -45,24 +45,38 @@ class ECAPIHttpClient {
         this.defaultHeaders = { ...(options.defaultHeaders || {}) };
         this.timeoutMs = options.timeoutMs ?? 15000;
         this.auth = options.auth;
+        this.authProvider = options.authProvider;
     }
     setAuth(auth) {
         this.auth = auth;
+        this.authProvider = undefined;
+    }
+    /** 设置动态默认认证；每次请求都会重新解析。 */
+    setAuthProvider(authProvider) {
+        this.authProvider = authProvider;
     }
     clearAuth() {
         this.auth = undefined;
+        this.authProvider = undefined;
     }
     setApiKey(apiKey) {
-        this.auth = { type: 'apiKey', apiKey };
+        this.setAuth({ type: 'apiKey', apiKey });
     }
     setAppSessionToken(appSessionToken) {
-        this.auth = { type: 'appSessionToken', appSessionToken };
+        this.setAuth({ type: 'appSessionToken', appSessionToken });
+    }
+    async resolveAuth(requestAuth) {
+        if (requestAuth !== undefined)
+            return requestAuth;
+        if (this.authProvider)
+            return this.authProvider();
+        return this.auth;
     }
     async request(method, path, options = {}) {
         const requestPath = path.startsWith('/') ? path : `/${path}`;
         const queryString = toQueryString(options.query);
         const url = `${requestPath}${queryString}`;
-        const resolvedAuth = options.auth === undefined ? this.auth : options.auth;
+        const resolvedAuth = await this.resolveAuth(options.auth);
         const fetchConfig = {
             baseUrl: this.baseUrl,
             timeout: this.timeoutMs,

package/dist/types.d.ts

@@ -98,6 +98,10 @@ export type AuthCredentials = {
     type: 'jwt';
     token: string;
 };
+/** 动态认证提供器的解析结果；null/undefined 表示本次不发送认证。 */
+export type AuthProviderResult = AuthCredentials | null | undefined;
+/** 每次请求前解析的动态认证提供器，适合 IAM callback / STS 短期凭证。 */
+export type AuthProvider = () => AuthProviderResult | Promise<AuthProviderResult>;
 /** 统一成功响应 envelope。 */
 export interface ApiEnvelope<T = unknown> {
     success: true;
@@ -130,6 +134,8 @@ export interface ClientOptions {
     baseUrl?: string;
     /** 默认认证信息；单次请求可通过 RequestOptions.auth 覆盖。 */
     auth?: AuthCredentials;
+    /** 动态默认认证；优先于 auth，返回 null/undefined 表示不发送认证。 */
+    authProvider?: AuthProvider;
     /** 请求超时时间，单位毫秒，默认 15000。 */
     timeoutMs?: number;
     /** 合并到每个请求中的默认 header。 */
@@ -147,6 +153,6 @@ export interface RequestOptions {
     signal?: AbortSignal;
     /** 当前请求的响应解析模式。 */
     responseType?: ResponseType;
-    /** 覆盖客户端默认认证；传 null 表示当前请求不发送认证。 */
+    /** 覆盖客户端默认认证；传 null 表示当前请求不发送认证且不会调用 authProvider。 */
     auth?: AuthCredentials | null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@easecation/ecapi-sdk",
-  "version": "3.0.6",
+  "version": "3.0.12",
   "description": "EaseCation Console API Node.js SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",