@movk/nuxt 1.1.1 → 1.2.0

package/dist/runtime/types/api.d.ts

@@ -1,9 +1,6 @@
-import type { $Fetch, FetchOptions, FetchHooks, FetchError } from 'ofetch';
+import type { $Fetch, FetchError } from 'ofetch';
 import type { UseFetchOptions as NuxtUseFetchOptions, AsyncData } from 'nuxt/app';
 import type { ToastProps } from '@nuxt/ui';
-import type { z } from 'zod/v4';
-import type { apiEndpointPublicConfigSchema, movkApiPublicConfigSchema, movkApiPrivateConfigSchema, movkApiFullConfigSchema, apiUnauthorizedConfigSchema, apiResponseConfigSchema, apiAuthConfigSchema, apiToastConfigSchema } from '../schemas/api.js';
-import type { User, UserSession, UserSessionComposable } from '#auth-utils';
 declare module 'ofetch' {
     interface FetchOptions {
         context?: ApiFetchContext;
@@ -19,47 +16,264 @@ export interface ApiFetchContext {
     /** 是否跳过业务状态码检查 */
     skipBusinessCheck?: boolean;
 }
-/** API 响应配置（包含业务状态码、数据/消息字段映射） */
-export type ApiResponseConfig = z.infer<typeof apiResponseConfigSchema>;
-/** API 认证配置（包含令牌来源、认证头配置） */
-export type ApiAuthConfig = z.infer<typeof apiAuthConfigSchema>;
-/** 401 未授权处理配置（包含重定向和会话清理选项） */
-export type ApiUnauthorizedConfig = z.infer<typeof apiUnauthorizedConfigSchema>;
-/** Toast 提示配置（包含成功/错误提示的样式和行为） */
-export type ApiToastConfig = z.infer<typeof apiToastConfigSchema>;
-/** API 端点公共配置（用于模块配置的公共部分） */
-export type ApiEndpointPublicConfig = z.infer<typeof apiEndpointPublicConfigSchema>;
-/** Movk API 模块公共配置 */
-export type MovkApiPublicConfig = z.infer<typeof movkApiPublicConfigSchema>;
-/** Movk API 模块私有配置（仅服务端可访问） */
-export type MovkApiPrivateConfig = z.infer<typeof movkApiPrivateConfigSchema>;
-/** Movk API 模块完整配置（公共+私有） */
-export type MovkApiFullConfig = z.input<typeof movkApiFullConfigSchema>;
+/**
+ * API 响应配置
+ * @description 定义业务状态码判断规则和数据/消息字段的映射关系
+ */
+export interface ApiResponseConfig {
+    /**
+     * 表示成功的业务状态码列表
+     * @defaultValue [200, 0]
+     */
+    successCodes: (number | string)[];
+    /**
+     * 响应中业务状态码的字段名
+     * @defaultValue 'code'
+     */
+    codeKey: string;
+    /**
+     * 响应中消息内容的字段名
+     * @defaultValue 'message'
+     */
+    messageKey: string;
+    /**
+     * 响应中业务数据的字段名
+     * @defaultValue 'data'
+     */
+    dataKey: string;
+}
+/**
+ * 401 未授权处理配置
+ * @description 定义当接收到 401 响应时的自动处理行为
+ */
+export interface ApiUnauthorizedConfig {
+    /**
+     * 是否自动重定向到登录页
+     * @defaultValue true
+     */
+    redirect?: boolean;
+    /**
+     * 登录页路径
+     * @defaultValue '/login'
+     */
+    loginPath?: string;
+    /**
+     * 是否清除用户会话
+     * @defaultValue true
+     */
+    clearSession?: boolean;
+}
+/**
+ * API 认证配置
+ * @description 定义认证令牌的来源、格式和请求头配置
+ */
+export interface ApiAuthConfig {
+    /**
+     * 是否启用认证
+     * @defaultValue false
+     */
+    enabled: boolean;
+    /**
+     * 令牌来源类型
+     * @defaultValue 'session'
+     */
+    tokenSource: 'session';
+    /**
+     * 令牌在会话对象中的路径（支持点号分隔的嵌套路径）
+     * @defaultValue 'token'
+     * @example 'token' | 'user.accessToken' | 'auth.credentials.token'
+     */
+    sessionTokenPath: string;
+    /**
+     * 令牌类型前缀
+     * @defaultValue 'Bearer'
+     */
+    tokenType: 'Bearer' | 'Basic' | 'Custom';
+    /**
+     * 自定义令牌类型前缀（当 tokenType 为 'Custom' 时使用）
+     */
+    customTokenType?: string;
+    /**
+     * 认证请求头名称
+     * @defaultValue 'Authorization'
+     */
+    headerName: string;
+    /**
+     * 401 未授权处理配置
+     */
+    unauthorized?: ApiUnauthorizedConfig;
+}
+/**
+ * Toast 提示配置
+ * @description 定义成功和错误提示的全局样式和行为
+ */
+export interface ApiToastConfig {
+    /**
+     * 是否启用 Toast 提示
+     * @defaultValue true
+     */
+    enabled: boolean;
+    /**
+     * 成功提示配置
+     */
+    success?: {
+        /**
+         * 是否显示成功提示
+         * @defaultValue true
+         */
+        show: boolean;
+        /**
+         * 提示颜色
+         * @defaultValue 'success'
+         */
+        color: string;
+        /**
+         * 图标类名
+         * @defaultValue 'i-lucide-circle-check'
+         */
+        icon?: string;
+        /**
+         * 显示时长（毫秒）
+         * @defaultValue 3000
+         */
+        duration: number;
+    };
+    /**
+     * 错误提示配置
+     */
+    error?: {
+        /**
+         * 是否显示错误提示
+         * @defaultValue true
+         */
+        show: boolean;
+        /**
+         * 提示颜色
+         * @defaultValue 'error'
+         */
+        color: string;
+        /**
+         * 图标类名
+         * @defaultValue 'i-lucide-circle-x'
+         */
+        icon?: string;
+        /**
+         * 显示时长（毫秒）
+         * @defaultValue 3000
+         */
+        duration: number;
+    };
+}
+/**
+ * API 端点公共配置
+ * @description 定义单个 API 端点的配置（可在客户端访问的配置）
+ */
+export interface ApiEndpointPublicConfig {
+    /**
+     * 端点的基础 URL
+     */
+    baseURL: string;
+    /**
+     * 端点别名（用于标识）
+     */
+    alias?: string;
+    /**
+     * 端点级别的认证配置（覆盖全局配置）
+     */
+    auth?: Partial<ApiAuthConfig>;
+    /**
+     * 端点级别的 Toast 配置（覆盖全局配置）
+     */
+    toast?: Partial<ApiToastConfig>;
+    /**
+     * 端点级别的响应配置（覆盖全局配置）
+     */
+    response?: Partial<ApiResponseConfig>;
+}
+/**
+ * Movk API 模块公共配置
+ * @description 定义模块的全局配置（可在客户端访问）
+ */
+export interface MovkApiPublicConfig {
+    /**
+     * 默认使用的端点名称
+     * @defaultValue 'default'
+     */
+    defaultEndpoint: string;
+    /**
+     * 是否启用调试模式（在控制台输出请求和响应日志）
+     * @defaultValue false
+     */
+    debug: boolean;
+    /**
+     * 端点配置映射
+     * @defaultValue { default: { baseURL: '/api' } }
+     */
+    endpoints: Record<string, ApiEndpointPublicConfig>;
+    /**
+     * 全局响应配置（已合并默认值，运行时必然存在）
+     */
+    response: ApiResponseConfig;
+    /**
+     * 全局认证配置（已合并默认值，运行时必然存在）
+     */
+    auth: ApiAuthConfig;
+    /**
+     * 全局 Toast 配置（已合并默认值，运行时必然存在）
+     */
+    toast: ApiToastConfig;
+}
+/**
+ * 端点私有配置（仅服务端）
+ * @description 从端点配置中拆分出的服务端专用字段，不会暴露给客户端
+ */
+export interface EndpointPrivateConfig {
+    /** 自定义请求头（仅服务端使用，不会暴露给客户端） */
+    headers?: Record<string, string>;
+}
+/**
+ * Movk API 模块完整配置
+ * @description 定义模块的完整配置（公共+私有），用于模块初始化时的配置验证
+ */
+export interface MovkApiFullConfig {
+    /**
+     * 是否启用 API 模块
+     * @defaultValue true
+     */
+    enabled?: boolean;
+    /**
+     * 默认使用的端点名称
+     * @defaultValue 'default'
+     */
+    defaultEndpoint?: string;
+    /**
+     * 是否启用调试模式
+     * @defaultValue false
+     */
+    debug?: boolean;
+    /**
+     * 端点配置映射（包含公共和私有配置）
+     * @defaultValue { default: { baseURL: '/api' } }
+     */
+    endpoints?: Record<string, ApiEndpointPublicConfig & EndpointPrivateConfig>;
+    /**
+     * 全局响应配置
+     */
+    response?: Partial<ApiResponseConfig>;
+    /**
+     * 全局认证配置
+     */
+    auth?: Partial<ApiAuthConfig>;
+    /**
+     * 全局 Toast 配置
+     */
+    toast?: Partial<ApiToastConfig>;
+}
 /**
  * API 响应数据结构
- * @description 适配多种常见的后端响应格式
- * @template T - 业务数据类型
- */
-export interface ApiResponse<T = unknown> {
-    /** 业务状态码 */
-    code?: number | string;
-    /** HTTP 状态码或业务状态 */
-    status?: number | string;
-    /** 消息内容（简写） */
-    msg?: string;
-    /** 消息内容 */
-    message?: string;
-    /** 业务数据 */
-    data?: T;
-    /** 业务数据（别名） */
-    result?: T;
-    /** 认证令牌 */
-    token?: string;
-    /** 访问令牌 */
-    accessToken?: string;
-    /** 错误信息 */
-    error?: string | null;
-    /** 支持任意额外字段 */
+ * @description 字段名通过 ApiResponseConfig 的 codeKey/messageKey/dataKey 配置化读取
+ */
+export interface ApiResponse {
     [key: string]: unknown;
 }
 /**
@@ -79,16 +293,14 @@ export interface ApiError extends Error {
  * @description 合并全局配置和端点配置后的最终配置，供内部使用
  */
 export interface ResolvedEndpointConfig extends ApiEndpointPublicConfig {
-    /** 认证配置（已合并全局配置） */
-    auth: Partial<ApiAuthConfig>;
-    /** Toast 配置（已合并全局配置） */
-    toast: Partial<ApiToastConfig>;
-    /** 响应配置（已合并全局配置） */
-    response: Partial<ApiResponseConfig>;
+    /** 认证配置（已合并全局默认值） */
+    auth: ApiAuthConfig;
+    /** Toast 配置（已合并全局默认值） */
+    toast: ApiToastConfig;
+    /** 响应配置（已合并全局默认值） */
+    response: ApiResponseConfig;
     /** 自定义请求头（仅服务端配置） */
     headers?: Record<string, string>;
-    /** 内置请求钩子（内部使用） */
-    builtinHooks?: FetchHooks;
 }
 /**
  * 请求级别的 Toast 提示选项
@@ -104,115 +316,34 @@ export interface RequestToastOptions {
     /** 自定义错误消息 */
     errorMessage?: string;
 }
+/**
+ * API 实例类型
+ * @description $fetch.create() 返回的实例，附加 use() 方法支持多端点切换
+ */
+export type ApiInstance = $Fetch & {
+    /** 切换到指定端点，返回该端点的 $fetch 实例 */
+    use: (endpoint: string) => ApiInstance;
+};
 /**
  * useApiFetch 的扩展选项
- * @template ResT - API 响应数据类型
- * @template DataT - 转换后的数据类型
+ * @template T - 业务数据类型（已解包）
  */
-export interface ApiFetchExtras<ResT, DataT = ResT> {
+export interface ApiFetchExtras {
     /** 使用的端点名称（默认使用 defaultEndpoint） */
     endpoint?: string;
     /** Toast 提示配置，设置为 false 禁用提示 */
     toast?: RequestToastOptions | false;
     /** 是否跳过业务状态码检查 */
     skipBusinessCheck?: boolean;
-    /** 数据转换函数（应用于提取后的业务数据） */
-    transform?: (data: ResT) => DataT;
 }
 /**
  * useApiFetch 选项类型
- * @template ResT - API 响应数据类型
- * @template DataT - 转换后的数据类型
+ * @template T - 业务数据类型（已解包）
+ * @template DataT - transform 转换后的类型（默认等于 T）
  */
-export type UseApiFetchOptions<ResT, DataT = ResT> = Omit<NuxtUseFetchOptions<ApiResponse<ResT>, DataT>, 'transform'> & ApiFetchExtras<ResT, DataT>;
+export type UseApiFetchOptions<T = unknown, DataT = T> = Omit<NuxtUseFetchOptions<T, DataT>, '$fetch' | 'context'> & ApiFetchExtras;
 /**
  * useApiFetch 返回值类型
- * @template DataT - 数据类型
+ * @template DataT - 最终数据类型
  */
 export type UseApiFetchReturn<DataT> = AsyncData<DataT | null, FetchError | ApiError | null>;
-/**
- * 文件下载选项
- */
-export interface DownloadOptions extends Omit<FetchOptions<'json'>, 'responseType'> {
-    /** Toast 提示配置，设置为 false 禁用提示 */
-    toast?: RequestToastOptions | false;
-    /** 下载进度回调（0-100） */
-    onProgress?: (progress: number) => void;
-}
-/**
- * 文件上传选项
- */
-export interface UploadOptions extends Omit<FetchOptions<'json'>, 'responseType' | 'body'> {
-    /**
-     * FormData 中的文件字段名
-     * @defaultValue 'file'
-     */
-    fieldName?: string;
-    /** Toast 提示配置，设置为 false 禁用提示 */
-    toast?: RequestToastOptions | false;
-    /** 上传进度回调（0-100） */
-    onProgress?: (progress: number) => void;
-}
-/**
- * API 客户端接口
- * @description 提供统一的 API 请求、文件上传下载等功能
- */
-export interface ApiClient {
-    /** ofetch 实例，用于发起请求 */
-    $fetch: $Fetch;
-    /** 切换到指定端点 */
-    use: (endpoint: string) => ApiClient;
-    /** 下载文件 */
-    download: (url: string, filename?: string, options?: DownloadOptions) => Promise<void>;
-    /**
-     * 上传文件
-     * @template T - API 响应数据类型
-     */
-    upload: <T = unknown>(url: string, file: File | File[] | FormData, options?: UploadOptions) => Promise<ApiResponse<T>>;
-    /** 获取当前端点配置 */
-    getConfig: () => ResolvedEndpointConfig;
-}
-/**
- * 登录选项
- * @template LoginRData - 登录接口响应数据类型
- */
-export interface LoginOptions<LoginRData = unknown> {
-    /** 登录接口路径 */
-    loginPath: string;
-    /** 登录凭证（用户名/密码等） */
-    credentials: unknown;
-    /** 获取用户信息的接口路径（可选，如果登录接口不返回用户信息） */
-    userInfoPath?: string;
-    /**
-     * 从登录响应中提取令牌的函数
-     * @defaultValue 从 response.token 或 response.data.token 提取
-     */
-    tokenExtractor?: (response: ApiResponse<LoginRData>) => string | null | undefined;
-    /**
-     * 自定义会话构建函数
-     * @defaultValue 使用 { user, token } 作为会话数据
-     */
-    sessionBuilder?: (userInfo: User, token: string) => UserSession;
-    /** 使用的端点名称（默认使用 defaultEndpoint） */
-    endpoint?: string;
-}
-/**
- * 登录结果
- */
-export interface LoginResult {
-    /** 用户信息 */
-    user: User;
-    /** 认证令牌 */
-    token: string;
-}
-/**
- * useApiAuth 返回值类型
- * @description 扩展 nuxt-auth-utils 的 UserSessionComposable，添加 login 方法
- */
-export interface UseApiAuthReturn extends UserSessionComposable {
-    /**
-     * 登录方法
-     * @template LoginRData - 登录接口响应数据类型
-     */
-    login: <LoginRData = unknown>(options: LoginOptions<LoginRData>) => Promise<LoginResult>;
-}