xxf_react 0.7.1 → 0.7.3

package/dist/http/api/ApiBuilder.d.ts

@@ -4,63 +4,114 @@
  * 使用 Builder 模式定义 API，类似 Android Retrofit。
  * 采用泛型累积模式，每次 .get() / .post() 调用都返回带有累积类型的新 Builder。
  *
- * ## 类型安全
+ * ## 类型安全特性
  *
- * - 每个端点名称保留字面量类型（如 `'getUser'`）
- * - 链式调用累积所有端点类型：`T & Record<K, ApiEndpoint<TResponse>>`
- * - `build()` 后返回完整类型安全的 API 对象
- * - 调用不存在的端点会产生编译错误
+ * - **端点名称字面量**：每个端点名称保留字面量类型（如 `'getUser'`）
+ * - **泛型累积**：链式调用累积所有端点类型 `T & Record<K, ApiEndpoint<...>>`
+ * - **路径参数推断**：从 path 字符串自动提取 `{param}` 并约束 `pathParams` 类型
+ * - **Body 类型约束**：POST/PUT/PATCH 支持指定请求体类型
+ * - **防止重复端点**：添加已存在的端点名称会编译报错
  *
  * @example
  * ```ts
+ * interface CreateUserDTO { name: string; email: string }
+ *
  * // 定义 API
  * const userApi = ApiBuilder.create({
  *   baseUrl: 'https://api.example.com',
  * })
  *   .get<User>('getUser', {
- *     path: '/users/{id}',
+ *     path: '/users/{id}',  // pathParams 自动约束为 { id: string | number }
  *     cache: { mode: CacheMode.IfCache, ttl: 60000 },
  *   })
  *   .get<User[]>('getUsers', { path: '/users' })
- *   .post<User>('createUser', { path: '/users' })
+ *   .post<User, CreateUserDTO>('createUser', { path: '/users' })  // body 类型为 CreateUserDTO
  *   .build()
  *
  * // ✅ 类型正确推断
- * userApi.getUser({ pathParams: { id: '123' } })   // ApiStream<User>
- * userApi.getUsers()                               // ApiStream<User[]>
- * userApi.createUser({ body: { name: 'John' } })   // ApiStream<User>
+ * userApi.getUser({ pathParams: { id: '123' } })          // pathParams 必须有 id
+ * userApi.getUsers()                                       // 无需 pathParams
+ * userApi.createUser({ body: { name: 'John', email: 'x' } }) // body 类型检查
  *
  * // ❌ 类型错误会被捕获
- * userApi.unknownMethod()  // Error: Property 'unknownMethod' does not exist
- *
- * // 多次响应
- * for await (const { data, fromCache } of userApi.getUser({ pathParams: { id: '123' } })) {
- *   console.log(data, fromCache)
- * }
+ * userApi.getUser({ pathParams: { wrong: '1' } })  // Error: 缺少 id
+ * userApi.createUser({ body: { wrong: 'x' } })     // Error: body 类型不匹配
+ * userApi.unknownMethod()                          // Error: 方法不存在
  * ```
  */
 import ky, { type Options as KyOptions } from 'ky';
 import { HttpClient } from '../client/HttpClient';
 import { ApiStream } from '../client/ApiStream';
-import type { RequestConfig, ApiOptions, CacheConfig, HttpClientConfig } from '../types';
+import type { RequestConfig, CacheConfig, HttpClientConfig } from '../types';
+/**
+ * 从路径字符串中提取参数名称
+ *
+ * @example
+ * ExtractPathParams<'/users/{id}'> = 'id'
+ * ExtractPathParams<'/users/{userId}/posts/{postId}'> = 'userId' | 'postId'
+ * ExtractPathParams<'/users'> = never
+ */
+type ExtractPathParams<Path extends string> = Path extends `${string}{${infer Param}}${infer Rest}` ? Param | ExtractPathParams<Rest> : never;
+/**
+ * 根据路径参数生成 pathParams 类型
+ *
+ * @example
+ * PathParamsType<'/users/{id}'> = { id: string | number }
+ * PathParamsType<'/users'> = undefined (无需路径参数)
+ */
+type PathParamsType<Path extends string> = ExtractPathParams<Path> extends never ? undefined : Record<ExtractPathParams<Path>, string | number>;
+/**
+ * 判断路径是否有参数
+ */
+type HasPathParams<Path extends string> = ExtractPathParams<Path> extends never ? false : true;
+/**
+ * 带类型约束的 API 调用选项
+ *
+ * @template Path 路径字符串字面量
+ * @template TBody 请求体类型（用于 POST/PUT/PATCH）
+ * @template HasBody 是否需要 body
+ */
+type TypedApiOptions<Path extends string, TBody = never, HasBody extends boolean = false> = {
+    /** 查询参数，会自动过滤 undefined 和 null */
+    query?: Record<string, string | number | boolean | undefined>;
+    /** 覆盖缓存配置（优先级最高） */
+    cache?: Partial<CacheConfig>;
+    /** 覆盖请求头 */
+    headers?: Record<string, string>;
+} & (HasPathParams<Path> extends true ? {
+    pathParams: PathParamsType<Path>;
+} : {
+    pathParams?: undefined;
+}) & (HasBody extends true ? {
+    body?: TBody;
+} : {
+    body?: never;
+});
 /**
- * API 端点函数类型
+ * API 端点函数类型（带路径参数和 Body 类型约束）
+ *
+ * @template TResponse 响应数据类型
+ * @template Path 路径字符串字面量
+ * @template TBody 请求体类型
+ * @template HasBody 是否需要 body
  */
-export type ApiEndpoint<TResponse> = {
-    (options?: ApiOptions): ApiStream<TResponse>;
+export type ApiEndpoint<TResponse, Path extends string = string, TBody = never, HasBody extends boolean = false> = {
+    (options?: TypedApiOptions<Path, TBody, HasBody>): ApiStream<TResponse>;
     /** 请求配置 */
     config: RequestConfig;
 };
 /**
- * API 定义类型
+ * API 定义类型（端点集合）
  */
-export type ApiDefinition = Record<string, ApiEndpoint<unknown>>;
+export type ApiDefinition = Record<string, ApiEndpoint<unknown, string, unknown, boolean>>;
 /**
- * 端点选项
+ * 端点选项（构建时配置）
+ *
+ * @template Path 路径字符串字面量，用于类型推断
  */
-interface EndpointOptions {
+interface EndpointOptions<Path extends string = string> {
     /** 请求路径，支持 {param} 占位符 */
-    path: string;
+    path: Path;
     /** 请求方法 */
     method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
     /** 请求头 */
@@ -73,7 +124,9 @@ interface EndpointOptions {
     cache?: CacheConfig;
 }
 /**
- * API 构建器
+ * API 构建器类
+ *
+ * @template T 当前已定义的端点类型集合，通过链式调用累积
  */
 export declare class ApiBuilder<T extends ApiDefinition = Record<string, never>> {
     private client;
@@ -81,54 +134,206 @@ export declare class ApiBuilder<T extends ApiDefinition = Record<string, never>>
     private constructor();
     /**
      * 创建 API 构建器
+     *
+     * @param config HTTP 客户端配置
+     * @returns 新的 ApiBuilder 实例
+     *
+     * @example
+     * ```ts
+     * const api = ApiBuilder.create({
+     *   baseUrl: 'https://api.example.com',
+     *   timeout: 10000,
+     * })
+     * ```
      */
     static create(config: HttpClientConfig): ApiBuilder;
     /**
      * 从现有 ky 实例创建
+     *
+     * @param kyInstance 已配置的 ky 实例
+     * @param config 可选的额外配置
+     * @returns 新的 ApiBuilder 实例
+     *
+     * @example
+     * ```ts
+     * const kyInstance = ky.create({ prefixUrl: 'https://api.example.com' })
+     * const api = ApiBuilder.from(kyInstance)
+     * ```
      */
     static from(kyInstance: ReturnType<typeof ky.create>, config?: Partial<HttpClientConfig>): ApiBuilder;
     /**
      * 定义 GET 请求
-     * @param name 端点名称（使用字面量类型实现类型累积）
+     *
+     * @template TResponse 响应数据类型
+     * @template K 端点名称（自动推断，不能与已有端点重复）
+     * @template Path 路径字符串（自动推断，用于提取路径参数）
+     *
+     * @param name 端点名称
+     * @param options 端点配置
+     * @returns 累积了新端点类型的 ApiBuilder
+     *
+     * @example
+     * ```ts
+     * .get<User>('getUser', {
+     *   path: '/users/{id}',  // pathParams 自动约束为 { id: string | number }
+     *   cache: { mode: CacheMode.IfCache },
+     * })
+     * ```
      */
-    get<TResponse, K extends string>(name: K, options: Omit<EndpointOptions, 'method'>): ApiBuilder<T & Record<K, ApiEndpoint<TResponse>>>;
+    get<TResponse, K extends string = string, Path extends string = string>(name: K extends keyof T ? never : K, // 防止重复端点名称
+    options: Omit<EndpointOptions<Path>, 'method'>): ApiBuilder<T & Record<K, ApiEndpoint<TResponse, Path, never, false>>>;
     /**
      * 定义 POST 请求
-     * @param name 端点名称（使用字面量类型实现类型累积）
+     *
+     * @template TResponse 响应数据类型
+     * @template TBody 请求体类型（可选，默认 unknown）
+     * @template K 端点名称（自动推断）
+     * @template Path 路径字符串（自动推断）
+     *
+     * @param name 端点名称
+     * @param options 端点配置
+     * @returns 累积了新端点类型的 ApiBuilder
+     *
+     * @example
+     * ```ts
+     * interface CreateUserDTO { name: string; email: string }
+     *
+     * .post<User, CreateUserDTO>('createUser', {
+     *   path: '/users',
+     * })
+     * // body 类型约束为 CreateUserDTO
+     * ```
      */
-    post<TResponse, K extends string>(name: K, options: Omit<EndpointOptions, 'method'>): ApiBuilder<T & Record<K, ApiEndpoint<TResponse>>>;
+    post<TResponse, TBody = unknown, K extends string = string, Path extends string = string>(name: K extends keyof T ? never : K, options: Omit<EndpointOptions<Path>, 'method'>): ApiBuilder<T & Record<K, ApiEndpoint<TResponse, Path, TBody, true>>>;
     /**
      * 定义 PUT 请求
-     * @param name 端点名称（使用字面量类型实现类型累积）
+     *
+     * @template TResponse 响应数据类型
+     * @template TBody 请求体类型（可选，默认 unknown）
+     * @template K 端点名称（自动推断）
+     * @template Path 路径字符串（自动推断）
+     *
+     * @param name 端点名称
+     * @param options 端点配置
+     * @returns 累积了新端点类型的 ApiBuilder
+     *
+     * @example
+     * ```ts
+     * .put<User, UpdateUserDTO>('updateUser', {
+     *   path: '/users/{id}',
+     * })
+     * ```
      */
-    put<TResponse, K extends string>(name: K, options: Omit<EndpointOptions, 'method'>): ApiBuilder<T & Record<K, ApiEndpoint<TResponse>>>;
+    put<TResponse, TBody = unknown, K extends string = string, Path extends string = string>(name: K extends keyof T ? never : K, options: Omit<EndpointOptions<Path>, 'method'>): ApiBuilder<T & Record<K, ApiEndpoint<TResponse, Path, TBody, true>>>;
     /**
      * 定义 DELETE 请求
-     * @param name 端点名称（使用字面量类型实现类型累积）
+     *
+     * @template TResponse 响应数据类型
+     * @template K 端点名称（自动推断）
+     * @template Path 路径字符串（自动推断）
+     *
+     * @param name 端点名称
+     * @param options 端点配置
+     * @returns 累积了新端点类型的 ApiBuilder
+     *
+     * @example
+     * ```ts
+     * .delete<void>('deleteUser', {
+     *   path: '/users/{id}',
+     * })
+     * ```
      */
-    delete<TResponse, K extends string>(name: K, options: Omit<EndpointOptions, 'method'>): ApiBuilder<T & Record<K, ApiEndpoint<TResponse>>>;
+    delete<TResponse, K extends string = string, Path extends string = string>(name: K extends keyof T ? never : K, options: Omit<EndpointOptions<Path>, 'method'>): ApiBuilder<T & Record<K, ApiEndpoint<TResponse, Path, never, false>>>;
     /**
      * 定义 PATCH 请求
-     * @param name 端点名称（使用字面量类型实现类型累积）
+     *
+     * @template TResponse 响应数据类型
+     * @template TBody 请求体类型（可选，默认 unknown）
+     * @template K 端点名称（自动推断）
+     * @template Path 路径字符串（自动推断）
+     *
+     * @param name 端点名称
+     * @param options 端点配置
+     * @returns 累积了新端点类型的 ApiBuilder
+     *
+     * @example
+     * ```ts
+     * .patch<User, Partial<UpdateUserDTO>>('patchUser', {
+     *   path: '/users/{id}',
+     * })
+     * ```
      */
-    patch<TResponse, K extends string>(name: K, options: Omit<EndpointOptions, 'method'>): ApiBuilder<T & Record<K, ApiEndpoint<TResponse>>>;
+    patch<TResponse, TBody = unknown, K extends string = string, Path extends string = string>(name: K extends keyof T ? never : K, options: Omit<EndpointOptions<Path>, 'method'>): ApiBuilder<T & Record<K, ApiEndpoint<TResponse, Path, TBody, true>>>;
     /**
-     * 通用端点定义
-     * 使用 `as unknown as` 类型断言绕过 TS 限制，实现泛型累积
+     * 通用端点定义（内部方法）
+     *
+     * @template TResponse 响应数据类型
+     * @template K 端点名称
+     * @template Path 路径字符串
+     * @template TBody 请求体类型
+     * @template HasBody 是否有请求体
      */
     private endpoint;
     /**
      * 扩展 ky 实例（添加 hooks 等）
+     *
+     * @param options ky 配置选项
+     * @returns this（支持链式调用）
+     *
+     * @example
+     * ```ts
+     * .extend({
+     *   hooks: {
+     *     beforeRequest: [(req) => {
+     *       req.headers.set('Authorization', `Bearer ${token}`)
+     *     }],
+     *   },
+     * })
+     * ```
      */
     extend(options: KyOptions): this;
     /**
      * 构建 API 服务
+     *
+     * 将所有定义的端点转换为可调用的 API 对象。
+     * 每个端点都带有完整的类型信息（响应类型、路径参数、请求体类型）。
+     *
+     * @returns 类型安全的 API 对象
+     *
+     * @example
+     * ```ts
+     * const api = ApiBuilder.create({ baseUrl: '...' })
+     *   .get<User>('getUser', { path: '/users/{id}' })
+     *   .post<User, CreateUserDTO>('createUser', { path: '/users' })
+     *   .build()
+     *
+     * // 类型安全调用
+     * await api.getUser({ pathParams: { id: '1' } })
+     * await api.createUser({ body: { name: 'John', email: 'x@x.com' } })
+     * ```
      */
     build(): T;
     /**
      * 获取 HTTP 客户端实例（用于高级操作）
+     *
+     * @returns HttpClient 实例
+     *
+     * @example
+     * ```ts
+     * const client = api.getClient()
+     * await client.clearCache()
+     * ```
      */
     getClient(): HttpClient;
 }
-export {};
+/**
+ * 从路径字符串中提取参数名称
+ *
+ * @example
+ * ```ts
+ * type Params = ExtractPathParams<'/users/{userId}/posts/{postId}'>
+ * // Params = 'userId' | 'postId'
+ * ```
+ */
+export type { ExtractPathParams, PathParamsType, HasPathParams };
 //# sourceMappingURL=ApiBuilder.d.ts.map

package/dist/http/api/ApiBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ApiBuilder.d.ts","sourceRoot":"","sources":["../../../src/http/api/ApiBuilder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ApiBuilder.d.ts","sourceRoot":"","sources":["../../../src/http/api/ApiBuilder.ts"],"names":[],"mappings":"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"}

package/dist/http/api/ApiBuilder.js

@@ -4,44 +4,49 @@
  * 使用 Builder 模式定义 API，类似 Android Retrofit。
  * 采用泛型累积模式，每次 .get() / .post() 调用都返回带有累积类型的新 Builder。
  *
- * ## 类型安全
+ * ## 类型安全特性
  *
- * - 每个端点名称保留字面量类型（如 `'getUser'`）
- * - 链式调用累积所有端点类型：`T & Record<K, ApiEndpoint<TResponse>>`
- * - `build()` 后返回完整类型安全的 API 对象
- * - 调用不存在的端点会产生编译错误
+ * - **端点名称字面量**：每个端点名称保留字面量类型（如 `'getUser'`）
+ * - **泛型累积**：链式调用累积所有端点类型 `T & Record<K, ApiEndpoint<...>>`
+ * - **路径参数推断**：从 path 字符串自动提取 `{param}` 并约束 `pathParams` 类型
+ * - **Body 类型约束**：POST/PUT/PATCH 支持指定请求体类型
+ * - **防止重复端点**：添加已存在的端点名称会编译报错
  *
  * @example
  * ```ts
+ * interface CreateUserDTO { name: string; email: string }
+ *
  * // 定义 API
  * const userApi = ApiBuilder.create({
  *   baseUrl: 'https://api.example.com',
  * })
  *   .get<User>('getUser', {
- *     path: '/users/{id}',
+ *     path: '/users/{id}',  // pathParams 自动约束为 { id: string | number }
  *     cache: { mode: CacheMode.IfCache, ttl: 60000 },
  *   })
  *   .get<User[]>('getUsers', { path: '/users' })
- *   .post<User>('createUser', { path: '/users' })
+ *   .post<User, CreateUserDTO>('createUser', { path: '/users' })  // body 类型为 CreateUserDTO
  *   .build()
  *
  * // ✅ 类型正确推断
- * userApi.getUser({ pathParams: { id: '123' } })   // ApiStream<User>
- * userApi.getUsers()                               // ApiStream<User[]>
- * userApi.createUser({ body: { name: 'John' } })   // ApiStream<User>
+ * userApi.getUser({ pathParams: { id: '123' } })          // pathParams 必须有 id
+ * userApi.getUsers()                                       // 无需 pathParams
+ * userApi.createUser({ body: { name: 'John', email: 'x' } }) // body 类型检查
  *
  * // ❌ 类型错误会被捕获
- * userApi.unknownMethod()  // Error: Property 'unknownMethod' does not exist
- *
- * // 多次响应
- * for await (const { data, fromCache } of userApi.getUser({ pathParams: { id: '123' } })) {
- *   console.log(data, fromCache)
- * }
+ * userApi.getUser({ pathParams: { wrong: '1' } })  // Error: 缺少 id
+ * userApi.createUser({ body: { wrong: 'x' } })     // Error: body 类型不匹配
+ * userApi.unknownMethod()                          // Error: 方法不存在
  * ```
  */
 import { HttpClient } from '../client/HttpClient';
+// ============================================================================
+// API 构建器
+// ============================================================================
 /**
- * API 构建器
+ * API 构建器类
+ *
+ * @template T 当前已定义的端点类型集合，通过链式调用累积
  */
 export class ApiBuilder {
     constructor(config) {
@@ -50,12 +55,33 @@ export class ApiBuilder {
     }
     /**
      * 创建 API 构建器
+     *
+     * @param config HTTP 客户端配置
+     * @returns 新的 ApiBuilder 实例
+     *
+     * @example
+     * ```ts
+     * const api = ApiBuilder.create({
+     *   baseUrl: 'https://api.example.com',
+     *   timeout: 10000,
+     * })
+     * ```
      */
     static create(config) {
         return new ApiBuilder(config);
     }
     /**
      * 从现有 ky 实例创建
+     *
+     * @param kyInstance 已配置的 ky 实例
+     * @param config 可选的额外配置
+     * @returns 新的 ApiBuilder 实例
+     *
+     * @example
+     * ```ts
+     * const kyInstance = ky.create({ prefixUrl: 'https://api.example.com' })
+     * const api = ApiBuilder.from(kyInstance)
+     * ```
      */
     static from(kyInstance, config) {
         const builder = new ApiBuilder({
@@ -67,42 +93,125 @@ export class ApiBuilder {
     }
     /**
      * 定义 GET 请求
-     * @param name 端点名称（使用字面量类型实现类型累积）
+     *
+     * @template TResponse 响应数据类型
+     * @template K 端点名称（自动推断，不能与已有端点重复）
+     * @template Path 路径字符串（自动推断，用于提取路径参数）
+     *
+     * @param name 端点名称
+     * @param options 端点配置
+     * @returns 累积了新端点类型的 ApiBuilder
+     *
+     * @example
+     * ```ts
+     * .get<User>('getUser', {
+     *   path: '/users/{id}',  // pathParams 自动约束为 { id: string | number }
+     *   cache: { mode: CacheMode.IfCache },
+     * })
+     * ```
      */
-    get(name, options) {
+    get(name, // 防止重复端点名称
+    options) {
         return this.endpoint(name, { ...options, method: 'GET' });
     }
     /**
      * 定义 POST 请求
-     * @param name 端点名称（使用字面量类型实现类型累积）
+     *
+     * @template TResponse 响应数据类型
+     * @template TBody 请求体类型（可选，默认 unknown）
+     * @template K 端点名称（自动推断）
+     * @template Path 路径字符串（自动推断）
+     *
+     * @param name 端点名称
+     * @param options 端点配置
+     * @returns 累积了新端点类型的 ApiBuilder
+     *
+     * @example
+     * ```ts
+     * interface CreateUserDTO { name: string; email: string }
+     *
+     * .post<User, CreateUserDTO>('createUser', {
+     *   path: '/users',
+     * })
+     * // body 类型约束为 CreateUserDTO
+     * ```
      */
     post(name, options) {
         return this.endpoint(name, { ...options, method: 'POST' });
     }
     /**
      * 定义 PUT 请求
-     * @param name 端点名称（使用字面量类型实现类型累积）
+     *
+     * @template TResponse 响应数据类型
+     * @template TBody 请求体类型（可选，默认 unknown）
+     * @template K 端点名称（自动推断）
+     * @template Path 路径字符串（自动推断）
+     *
+     * @param name 端点名称
+     * @param options 端点配置
+     * @returns 累积了新端点类型的 ApiBuilder
+     *
+     * @example
+     * ```ts
+     * .put<User, UpdateUserDTO>('updateUser', {
+     *   path: '/users/{id}',
+     * })
+     * ```
      */
     put(name, options) {
         return this.endpoint(name, { ...options, method: 'PUT' });
     }
     /**
      * 定义 DELETE 请求
-     * @param name 端点名称（使用字面量类型实现类型累积）
+     *
+     * @template TResponse 响应数据类型
+     * @template K 端点名称（自动推断）
+     * @template Path 路径字符串（自动推断）
+     *
+     * @param name 端点名称
+     * @param options 端点配置
+     * @returns 累积了新端点类型的 ApiBuilder
+     *
+     * @example
+     * ```ts
+     * .delete<void>('deleteUser', {
+     *   path: '/users/{id}',
+     * })
+     * ```
      */
     delete(name, options) {
         return this.endpoint(name, { ...options, method: 'DELETE' });
     }
     /**
      * 定义 PATCH 请求
-     * @param name 端点名称（使用字面量类型实现类型累积）
+     *
+     * @template TResponse 响应数据类型
+     * @template TBody 请求体类型（可选，默认 unknown）
+     * @template K 端点名称（自动推断）
+     * @template Path 路径字符串（自动推断）
+     *
+     * @param name 端点名称
+     * @param options 端点配置
+     * @returns 累积了新端点类型的 ApiBuilder
+     *
+     * @example
+     * ```ts
+     * .patch<User, Partial<UpdateUserDTO>>('patchUser', {
+     *   path: '/users/{id}',
+     * })
+     * ```
      */
     patch(name, options) {
         return this.endpoint(name, { ...options, method: 'PATCH' });
     }
     /**
-     * 通用端点定义
-     * 使用 `as unknown as` 类型断言绕过 TS 限制，实现泛型累积
+     * 通用端点定义（内部方法）
+     *
+     * @template TResponse 响应数据类型
+     * @template K 端点名称
+     * @template Path 路径字符串
+     * @template TBody 请求体类型
+     * @template HasBody 是否有请求体
      */
     endpoint(name, options) {
         var _a;
@@ -120,6 +229,20 @@ export class ApiBuilder {
     }
     /**
      * 扩展 ky 实例（添加 hooks 等）
+     *
+     * @param options ky 配置选项
+     * @returns this（支持链式调用）
+     *
+     * @example
+     * ```ts
+     * .extend({
+     *   hooks: {
+     *     beforeRequest: [(req) => {
+     *       req.headers.set('Authorization', `Bearer ${token}`)
+     *     }],
+     *   },
+     * })
+     * ```
      */
     extend(options) {
         this.client.extendKy(options);
@@ -127,10 +250,28 @@ export class ApiBuilder {
     }
     /**
      * 构建 API 服务
+     *
+     * 将所有定义的端点转换为可调用的 API 对象。
+     * 每个端点都带有完整的类型信息（响应类型、路径参数、请求体类型）。
+     *
+     * @returns 类型安全的 API 对象
+     *
+     * @example
+     * ```ts
+     * const api = ApiBuilder.create({ baseUrl: '...' })
+     *   .get<User>('getUser', { path: '/users/{id}' })
+     *   .post<User, CreateUserDTO>('createUser', { path: '/users' })
+     *   .build()
+     *
+     * // 类型安全调用
+     * await api.getUser({ pathParams: { id: '1' } })
+     * await api.createUser({ body: { name: 'John', email: 'x@x.com' } })
+     * ```
      */
     build() {
         const api = {};
         for (const [name, config] of this.endpoints) {
+            // 运行时不需要类型检查，类型安全由编译时保证
             const endpoint = ((options) => {
                 return this.client.request(config, options);
             });
@@ -141,6 +282,14 @@ export class ApiBuilder {
     }
     /**
      * 获取 HTTP 客户端实例（用于高级操作）
+     *
+     * @returns HttpClient 实例
+     *
+     * @example
+     * ```ts
+     * const client = api.getClient()
+     * await client.clearCache()
+     * ```
      */
     getClient() {
         return this.client;

package/dist/http/api/index.d.ts

@@ -1,2 +1,2 @@
-export { ApiBuilder, type ApiEndpoint, type ApiDefinition } from './ApiBuilder';
+export { ApiBuilder, type ApiEndpoint, type ApiDefinition, type ExtractPathParams, type PathParamsType, type HasPathParams, } from './ApiBuilder';
 //# sourceMappingURL=index.d.ts.map

package/dist/http/api/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/http/api/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/http/api/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,UAAU,EACV,KAAK,WAAW,EAChB,KAAK,aAAa,EAElB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,aAAa,GACrB,MAAM,cAAc,CAAA"}

package/dist/http/api/index.js

@@ -1 +1 @@
-export { ApiBuilder } from './ApiBuilder';
+export { ApiBuilder, } from './ApiBuilder';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xxf_react",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "private": false,
   "type": "module",
   "main": "dist/index.js",