@djvlc/openapi-user-client 1.1.1 → 1.2.0

package/dist/index.d.mts

@@ -1,4 +1,5 @@
-import { ApiResponse, PageResolveResult, ActionExecuteRequest, ActionExecuteResponse, DataQueryRequest, DataQueryResponse } from '@djvlc/contracts-types';
+import { ApiResponse, PageResolveResult, ActionExecuteRequest, ActionExecuteResponse, DataQueryRequest, DataQueryResponse, TrackEvent, HealthCheckResponse } from '@djvlc/contracts-types';
+export { ActionContext, ActionExecuteRequest, ActionExecuteResponse, ApiResponse, BlockedComponent, DataQueryContext, DataQueryRequest, DataQueryResponse, HealthCheckResponse, ManifestItem, PageManifest, PageResolveRequest, PageResolveResult, RuntimeConfig, TrackEvent } from '@djvlc/contracts-types';
 
 /**
  * @djvlc/openapi-user-client - User API 客户端
@@ -9,11 +10,16 @@ import { ApiResponse, PageResolveResult, ActionExecuteRequest, ActionExecuteResp
  * @packageDocumentation
  */
 
+/**
+ * User API 客户端配置
+ */
 interface UserClientConfig {
     /** API 基础 URL */
     baseUrl: string;
     /** 用户 Token */
     token?: string;
+    /** 获取 Token 的函数（支持动态获取） */
+    getToken?: () => string | Promise<string>;
     /** 设备 ID */
     deviceId?: string;
     /** 渠道 */
@@ -22,6 +28,8 @@ interface UserClientConfig {
     timeout?: number;
     /** 自定义请求头 */
     headers?: Record<string, string>;
+    /** 获取 Trace Headers（用于链路追踪） */
+    getTraceHeaders?: () => Record<string, string>;
     /** 请求拦截器 */
     onRequest?: (config: RequestInit) => RequestInit;
     /** 响应拦截器 */
@@ -29,14 +37,58 @@ interface UserClientConfig {
     /** 错误处理 */
     onError?: (error: Error) => void;
 }
-/** 页面解析请求 */
-interface ResolvePageRequest {
+/**
+ * 页面解析请求参数（Query 参数版本）
+ * GET /api/page/resolve
+ */
+interface ResolvePageParams {
+    /** 页面 UID */
     pageUid: string;
+    /** 渠道 */
     channel?: string;
+    /** 用户 ID（用于灰度） */
     uid?: string;
+    /** 设备 ID */
     deviceId?: string;
+    /** 预览 Token */
     previewToken?: string;
 }
+/**
+ * 埋点上报请求
+ * POST /api/track
+ */
+interface TrackRequest {
+    /** 事件列表 */
+    events: TrackEvent[];
+}
+/**
+ * 活动状态响应
+ * GET /api/activity/state
+ */
+interface ActivityStateResult {
+    /** 活动 ID */
+    activityId: string;
+    /** 活动整体状态 */
+    status: 'active' | 'inactive' | 'ended';
+    /** 用户参与状态 */
+    userStatus: 'not_participated' | 'participated' | 'claimed' | 'expired';
+    /** 剩余参与次数 */
+    remainingAttempts?: number;
+    /** 下次可参与时间 */
+    nextAvailableTime?: string;
+}
+/**
+ * 活动状态查询参数
+ * GET /api/activity/state
+ */
+interface ActivityStateParams {
+    /** 活动 ID */
+    activityId: string;
+    /** 用户 ID */
+    uid?: string;
+    /** 设备 ID */
+    deviceId?: string;
+}
 /**
  * User API 客户端类
  * 用于 Runtime 访问后端服务
@@ -44,6 +96,10 @@ interface ResolvePageRequest {
 declare class UserApiClient {
     private config;
     constructor(config: UserClientConfig);
+    /**
+     * 获取认证 Token
+     */
+    private getAuthToken;
     /**
      * 获取通用请求头
      */
@@ -52,11 +108,15 @@ declare class UserApiClient {
      * 发送请求
      */
     private request;
+    /**
+     * 发送请求（返回完整响应）
+     */
+    private requestFull;
     /**
      * 解析页面
      * GET /api/page/resolve
      */
-    resolvePage(request: ResolvePageRequest): Promise<PageResolveResult>;
+    resolvePage(params: ResolvePageParams): Promise<PageResolveResult>;
     /**
      * 执行动作
      * POST /api/actions/execute
@@ -70,6 +130,10 @@ declare class UserApiClient {
      * 快捷方法：签到
      */
     signin(activityId: string): Promise<ActionExecuteResponse>;
+    /**
+     * 快捷方法：抽奖
+     */
+    lottery(activityId: string, params?: Record<string, unknown>): Promise<ActionExecuteResponse>;
     /**
      * 查询数据
      * POST /api/data/query
@@ -83,23 +147,25 @@ declare class UserApiClient {
      * 上报埋点
      * POST /api/track
      */
-    track(events: Array<{
-        eventName: string;
-        params?: Record<string, unknown>;
-        timestamp?: number;
-    }>): Promise<void>;
+    track(events: TrackEvent[]): Promise<void>;
+    /**
+     * 快捷方法：上报单个事件
+     */
+    trackEvent(eventName: string, params?: Record<string, unknown>): Promise<void>;
+    /**
+     * 获取活动状态
+     * GET /api/activity/state
+     */
+    getActivityState(params: ActivityStateParams): Promise<ActivityStateResult>;
     /**
      * 健康检查
      * GET /api/health
      */
-    health(): Promise<{
-        status: string;
-        version: string;
-    }>;
+    health(): Promise<HealthCheckResponse>;
 }
 /**
  * 创建 User API 客户端实例
  */
 declare function createUserClient(config: UserClientConfig): UserApiClient;
 
-export { type ResolvePageRequest, UserApiClient, type UserClientConfig, createUserClient, UserApiClient as default };
+export { type ActivityStateParams, type ActivityStateResult, type ResolvePageParams, type TrackRequest, UserApiClient, type UserClientConfig, createUserClient, UserApiClient as default };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import { ApiResponse, PageResolveResult, ActionExecuteRequest, ActionExecuteResponse, DataQueryRequest, DataQueryResponse } from '@djvlc/contracts-types';
+import { ApiResponse, PageResolveResult, ActionExecuteRequest, ActionExecuteResponse, DataQueryRequest, DataQueryResponse, TrackEvent, HealthCheckResponse } from '@djvlc/contracts-types';
+export { ActionContext, ActionExecuteRequest, ActionExecuteResponse, ApiResponse, BlockedComponent, DataQueryContext, DataQueryRequest, DataQueryResponse, HealthCheckResponse, ManifestItem, PageManifest, PageResolveRequest, PageResolveResult, RuntimeConfig, TrackEvent } from '@djvlc/contracts-types';
 
 /**
  * @djvlc/openapi-user-client - User API 客户端
@@ -9,11 +10,16 @@ import { ApiResponse, PageResolveResult, ActionExecuteRequest, ActionExecuteResp
  * @packageDocumentation
  */
 
+/**
+ * User API 客户端配置
+ */
 interface UserClientConfig {
     /** API 基础 URL */
     baseUrl: string;
     /** 用户 Token */
     token?: string;
+    /** 获取 Token 的函数（支持动态获取） */
+    getToken?: () => string | Promise<string>;
     /** 设备 ID */
     deviceId?: string;
     /** 渠道 */
@@ -22,6 +28,8 @@ interface UserClientConfig {
     timeout?: number;
     /** 自定义请求头 */
     headers?: Record<string, string>;
+    /** 获取 Trace Headers（用于链路追踪） */
+    getTraceHeaders?: () => Record<string, string>;
     /** 请求拦截器 */
     onRequest?: (config: RequestInit) => RequestInit;
     /** 响应拦截器 */
@@ -29,14 +37,58 @@ interface UserClientConfig {
     /** 错误处理 */
     onError?: (error: Error) => void;
 }
-/** 页面解析请求 */
-interface ResolvePageRequest {
+/**
+ * 页面解析请求参数（Query 参数版本）
+ * GET /api/page/resolve
+ */
+interface ResolvePageParams {
+    /** 页面 UID */
     pageUid: string;
+    /** 渠道 */
     channel?: string;
+    /** 用户 ID（用于灰度） */
     uid?: string;
+    /** 设备 ID */
     deviceId?: string;
+    /** 预览 Token */
     previewToken?: string;
 }
+/**
+ * 埋点上报请求
+ * POST /api/track
+ */
+interface TrackRequest {
+    /** 事件列表 */
+    events: TrackEvent[];
+}
+/**
+ * 活动状态响应
+ * GET /api/activity/state
+ */
+interface ActivityStateResult {
+    /** 活动 ID */
+    activityId: string;
+    /** 活动整体状态 */
+    status: 'active' | 'inactive' | 'ended';
+    /** 用户参与状态 */
+    userStatus: 'not_participated' | 'participated' | 'claimed' | 'expired';
+    /** 剩余参与次数 */
+    remainingAttempts?: number;
+    /** 下次可参与时间 */
+    nextAvailableTime?: string;
+}
+/**
+ * 活动状态查询参数
+ * GET /api/activity/state
+ */
+interface ActivityStateParams {
+    /** 活动 ID */
+    activityId: string;
+    /** 用户 ID */
+    uid?: string;
+    /** 设备 ID */
+    deviceId?: string;
+}
 /**
  * User API 客户端类
  * 用于 Runtime 访问后端服务
@@ -44,6 +96,10 @@ interface ResolvePageRequest {
 declare class UserApiClient {
     private config;
     constructor(config: UserClientConfig);
+    /**
+     * 获取认证 Token
+     */
+    private getAuthToken;
     /**
      * 获取通用请求头
      */
@@ -52,11 +108,15 @@ declare class UserApiClient {
      * 发送请求
      */
     private request;
+    /**
+     * 发送请求（返回完整响应）
+     */
+    private requestFull;
     /**
      * 解析页面
      * GET /api/page/resolve
      */
-    resolvePage(request: ResolvePageRequest): Promise<PageResolveResult>;
+    resolvePage(params: ResolvePageParams): Promise<PageResolveResult>;
     /**
      * 执行动作
      * POST /api/actions/execute
@@ -70,6 +130,10 @@ declare class UserApiClient {
      * 快捷方法：签到
      */
     signin(activityId: string): Promise<ActionExecuteResponse>;
+    /**
+     * 快捷方法：抽奖
+     */
+    lottery(activityId: string, params?: Record<string, unknown>): Promise<ActionExecuteResponse>;
     /**
      * 查询数据
      * POST /api/data/query
@@ -83,23 +147,25 @@ declare class UserApiClient {
      * 上报埋点
      * POST /api/track
      */
-    track(events: Array<{
-        eventName: string;
-        params?: Record<string, unknown>;
-        timestamp?: number;
-    }>): Promise<void>;
+    track(events: TrackEvent[]): Promise<void>;
+    /**
+     * 快捷方法：上报单个事件
+     */
+    trackEvent(eventName: string, params?: Record<string, unknown>): Promise<void>;
+    /**
+     * 获取活动状态
+     * GET /api/activity/state
+     */
+    getActivityState(params: ActivityStateParams): Promise<ActivityStateResult>;
     /**
      * 健康检查
      * GET /api/health
      */
-    health(): Promise<{
-        status: string;
-        version: string;
-    }>;
+    health(): Promise<HealthCheckResponse>;
 }
 /**
  * 创建 User API 客户端实例
  */
 declare function createUserClient(config: UserClientConfig): UserApiClient;
 
-export { type ResolvePageRequest, UserApiClient, type UserClientConfig, createUserClient, UserApiClient as default };
+export { type ActivityStateParams, type ActivityStateResult, type ResolvePageParams, type TrackRequest, UserApiClient, type UserClientConfig, createUserClient, UserApiClient as default };

package/dist/index.js

@@ -32,16 +32,26 @@ var UserApiClient = class {
       ...config
     };
   }
+  /**
+   * 获取认证 Token
+   */
+  async getAuthToken() {
+    if (this.config.getToken) {
+      return this.config.getToken();
+    }
+    return this.config.token;
+  }
   /**
    * 获取通用请求头
    */
-  getCommonHeaders() {
+  async getCommonHeaders() {
     const headers = {
       "Content-Type": "application/json",
       ...this.config.headers
     };
-    if (this.config.token) {
-      headers["Authorization"] = `Bearer ${this.config.token}`;
+    const token = await this.getAuthToken();
+    if (token) {
+      headers["Authorization"] = `Bearer ${token}`;
     }
     if (this.config.deviceId) {
       headers["x-device-id"] = this.config.deviceId;
@@ -49,6 +59,9 @@ var UserApiClient = class {
     if (this.config.channel) {
       headers["x-channel"] = this.config.channel;
     }
+    if (this.config.getTraceHeaders) {
+      Object.assign(headers, this.config.getTraceHeaders());
+    }
     return headers;
   }
   /**
@@ -68,10 +81,11 @@ var UserApiClient = class {
         url += `?${queryString}`;
       }
     }
+    const commonHeaders = await this.getCommonHeaders();
     let requestConfig = {
       method,
       headers: {
-        ...this.getCommonHeaders(),
+        ...commonHeaders,
         ...options?.headers
       },
       body: options?.body ? JSON.stringify(options.body) : void 0
@@ -92,7 +106,9 @@ var UserApiClient = class {
         result = this.config.onResponse(result);
       }
       if (!result.success) {
-        throw new Error(result.message || "Request failed");
+        const error = new Error(result.message || "Request failed");
+        error.code = result.code;
+        throw error;
       }
       return result.data;
     } catch (error) {
@@ -102,19 +118,65 @@ var UserApiClient = class {
       throw error;
     }
   }
+  /**
+   * 发送请求（返回完整响应）
+   */
+  async requestFull(method, path, options) {
+    let url = `${this.config.baseUrl}${path}`;
+    if (options?.params) {
+      const searchParams = new URLSearchParams();
+      Object.entries(options.params).forEach(([key, value]) => {
+        if (value !== void 0) {
+          searchParams.append(key, value);
+        }
+      });
+      const queryString = searchParams.toString();
+      if (queryString) {
+        url += `?${queryString}`;
+      }
+    }
+    const commonHeaders = await this.getCommonHeaders();
+    let requestConfig = {
+      method,
+      headers: commonHeaders,
+      body: options?.body ? JSON.stringify(options.body) : void 0
+    };
+    if (this.config.onRequest) {
+      requestConfig = this.config.onRequest(requestConfig);
+    }
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+      const response = await fetch(url, {
+        ...requestConfig,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      let result = await response.json();
+      if (this.config.onResponse) {
+        result = this.config.onResponse(result);
+      }
+      return result;
+    } catch (error) {
+      if (this.config.onError) {
+        this.config.onError(error);
+      }
+      throw error;
+    }
+  }
   // ==================== 页面解析 ====================
   /**
    * 解析页面
    * GET /api/page/resolve
    */
-  async resolvePage(request) {
+  async resolvePage(params) {
     return this.request("GET", "/api/page/resolve", {
       params: {
-        pageUid: request.pageUid,
-        channel: request.channel,
-        uid: request.uid,
-        deviceId: request.deviceId,
-        previewToken: request.previewToken
+        pageUid: params.pageUid,
+        channel: params.channel,
+        uid: params.uid,
+        deviceId: params.deviceId,
+        previewToken: params.previewToken
       }
     });
   }
@@ -154,6 +216,19 @@ var UserApiClient = class {
       }
     });
   }
+  /**
+   * 快捷方法：抽奖
+   */
+  async lottery(activityId, params) {
+    return this.executeAction({
+      actionType: "lottery",
+      params: { activityId, ...params },
+      context: {
+        deviceId: this.config.deviceId,
+        channel: this.config.channel
+      }
+    });
+  }
   // ==================== Data Proxy ====================
   /**
    * 查询数据
@@ -184,6 +259,32 @@ var UserApiClient = class {
       body: { events }
     });
   }
+  /**
+   * 快捷方法：上报单个事件
+   */
+  async trackEvent(eventName, params) {
+    await this.track([
+      {
+        eventName,
+        params,
+        timestamp: Date.now()
+      }
+    ]);
+  }
+  // ==================== 活动状态 ====================
+  /**
+   * 获取活动状态
+   * GET /api/activity/state
+   */
+  async getActivityState(params) {
+    return this.request("GET", "/api/activity/state", {
+      params: {
+        activityId: params.activityId,
+        uid: params.uid,
+        deviceId: params.deviceId
+      }
+    });
+  }
   // ==================== 健康检查 ====================
   /**
    * 健康检查

package/dist/index.mjs

@@ -6,16 +6,26 @@ var UserApiClient = class {
       ...config
     };
   }
+  /**
+   * 获取认证 Token
+   */
+  async getAuthToken() {
+    if (this.config.getToken) {
+      return this.config.getToken();
+    }
+    return this.config.token;
+  }
   /**
    * 获取通用请求头
    */
-  getCommonHeaders() {
+  async getCommonHeaders() {
     const headers = {
       "Content-Type": "application/json",
       ...this.config.headers
     };
-    if (this.config.token) {
-      headers["Authorization"] = `Bearer ${this.config.token}`;
+    const token = await this.getAuthToken();
+    if (token) {
+      headers["Authorization"] = `Bearer ${token}`;
     }
     if (this.config.deviceId) {
       headers["x-device-id"] = this.config.deviceId;
@@ -23,6 +33,9 @@ var UserApiClient = class {
     if (this.config.channel) {
       headers["x-channel"] = this.config.channel;
     }
+    if (this.config.getTraceHeaders) {
+      Object.assign(headers, this.config.getTraceHeaders());
+    }
     return headers;
   }
   /**
@@ -42,10 +55,11 @@ var UserApiClient = class {
         url += `?${queryString}`;
       }
     }
+    const commonHeaders = await this.getCommonHeaders();
     let requestConfig = {
       method,
       headers: {
-        ...this.getCommonHeaders(),
+        ...commonHeaders,
         ...options?.headers
       },
       body: options?.body ? JSON.stringify(options.body) : void 0
@@ -66,7 +80,9 @@ var UserApiClient = class {
         result = this.config.onResponse(result);
       }
       if (!result.success) {
-        throw new Error(result.message || "Request failed");
+        const error = new Error(result.message || "Request failed");
+        error.code = result.code;
+        throw error;
       }
       return result.data;
     } catch (error) {
@@ -76,19 +92,65 @@ var UserApiClient = class {
       throw error;
     }
   }
+  /**
+   * 发送请求（返回完整响应）
+   */
+  async requestFull(method, path, options) {
+    let url = `${this.config.baseUrl}${path}`;
+    if (options?.params) {
+      const searchParams = new URLSearchParams();
+      Object.entries(options.params).forEach(([key, value]) => {
+        if (value !== void 0) {
+          searchParams.append(key, value);
+        }
+      });
+      const queryString = searchParams.toString();
+      if (queryString) {
+        url += `?${queryString}`;
+      }
+    }
+    const commonHeaders = await this.getCommonHeaders();
+    let requestConfig = {
+      method,
+      headers: commonHeaders,
+      body: options?.body ? JSON.stringify(options.body) : void 0
+    };
+    if (this.config.onRequest) {
+      requestConfig = this.config.onRequest(requestConfig);
+    }
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+      const response = await fetch(url, {
+        ...requestConfig,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      let result = await response.json();
+      if (this.config.onResponse) {
+        result = this.config.onResponse(result);
+      }
+      return result;
+    } catch (error) {
+      if (this.config.onError) {
+        this.config.onError(error);
+      }
+      throw error;
+    }
+  }
   // ==================== 页面解析 ====================
   /**
    * 解析页面
    * GET /api/page/resolve
    */
-  async resolvePage(request) {
+  async resolvePage(params) {
     return this.request("GET", "/api/page/resolve", {
       params: {
-        pageUid: request.pageUid,
-        channel: request.channel,
-        uid: request.uid,
-        deviceId: request.deviceId,
-        previewToken: request.previewToken
+        pageUid: params.pageUid,
+        channel: params.channel,
+        uid: params.uid,
+        deviceId: params.deviceId,
+        previewToken: params.previewToken
       }
     });
   }
@@ -128,6 +190,19 @@ var UserApiClient = class {
       }
     });
   }
+  /**
+   * 快捷方法：抽奖
+   */
+  async lottery(activityId, params) {
+    return this.executeAction({
+      actionType: "lottery",
+      params: { activityId, ...params },
+      context: {
+        deviceId: this.config.deviceId,
+        channel: this.config.channel
+      }
+    });
+  }
   // ==================== Data Proxy ====================
   /**
    * 查询数据
@@ -158,6 +233,32 @@ var UserApiClient = class {
       body: { events }
     });
   }
+  /**
+   * 快捷方法：上报单个事件
+   */
+  async trackEvent(eventName, params) {
+    await this.track([
+      {
+        eventName,
+        params,
+        timestamp: Date.now()
+      }
+    ]);
+  }
+  // ==================== 活动状态 ====================
+  /**
+   * 获取活动状态
+   * GET /api/activity/state
+   */
+  async getActivityState(params) {
+    return this.request("GET", "/api/activity/state", {
+      params: {
+        activityId: params.activityId,
+        uid: params.uid,
+        deviceId: params.deviceId
+      }
+    });
+  }
   // ==================== 健康检查 ====================
   /**
    * 健康检查

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@djvlc/openapi-user-client",
-  "version": "1.1.1",
-  "description": "DJV Low-code Platform - User API 客户端（自动生成）",
+  "version": "1.2.0",
+  "description": "DJV Low-code Platform - User API 客户端",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -17,25 +17,31 @@
   ],
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts --clean",
-    "generate": "openapi-typescript ../specs/user-api.yaml -o src/types.ts && npm run build",
     "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
     "lint": "eslint src/ --ext .ts",
     "typecheck": "tsc --noEmit",
     "clean": "rimraf dist"
   },
   "dependencies": {
-    "@djvlc/contracts-types": "1.2.0"
+    "@djvlc/contracts-types": "1.3.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "@typescript-eslint/eslint-plugin": "^7.0.0",
     "@typescript-eslint/parser": "^7.0.0",
     "eslint": "^8.56.0",
-    "openapi-typescript": "^6.0.0",
     "rimraf": "^5.0.0",
     "tsup": "^8.0.0",
     "typescript": "^5.3.0"
   },
+  "peerDependencies": {
+    "@djvlc/contracts-types": "1.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@djvlc/contracts-types": {
+      "optional": false
+    }
+  },
   "keywords": [
     "lowcode",
     "openapi",