@movk/nuxt 1.1.2 → 1.3.0

package/dist/runtime/plugins/api.factory.js

@@ -1,186 +1,43 @@
-import { getPath, triggerDownload, extractFilename } from "@movk/core";
-import {
-  showToast,
-  isBusinessSuccess,
-  extractMessage,
-  extractToastMessage
-} from "../utils/api-utils.js";
-import { defineNuxtPlugin, navigateTo, useNuxtApp, useUserSession, useRuntimeConfig } from "#imports";
-import defu from "defu";
-function getUserSession() {
-  try {
-    const nuxtApp = useNuxtApp();
-    return nuxtApp.runWithContext(() => useUserSession());
-  } catch {
-    return null;
-  }
-}
-function getTokenFromSession(tokenPath) {
-  const userSession = getUserSession();
-  if (!userSession?.session?.value) return null;
-  const sessionData = userSession.session.value;
-  return getPath(sessionData, tokenPath) || null;
-}
-function buildAuthHeader(token, config) {
-  const tokenType = config.tokenType === "Custom" ? config.customTokenType || "" : config.tokenType || "Bearer";
-  return tokenType ? `${tokenType} ${token}` : token;
-}
-async function handleUnauthorized(config) {
-  const userSession = getUserSession();
-  const unauthorizedConfig = config.unauthorized;
-  if (unauthorizedConfig?.clearSession && userSession?.clear) {
-    await userSession.clear();
-  }
-  if (unauthorizedConfig?.redirect) {
-    const loginPath = unauthorizedConfig.loginPath || "/login";
-    const nuxtApp = useNuxtApp();
-    await nuxtApp.runWithContext(() => navigateTo(loginPath));
-  }
-}
-function getApiFetchContext(context) {
-  return context.options.context || {};
-}
-function createBuiltinHooks(resolvedConfig, publicConfig) {
-  const { auth: authConfig, toast: toastConfig, response: responseConfig } = resolvedConfig;
-  return {
-    onRequest(context) {
-      if (authConfig.enabled) {
-        const tokenPath = authConfig.sessionTokenPath || "token";
-        const token = getTokenFromSession(tokenPath);
-        if (token) {
-          const headerName = authConfig.headerName || "Authorization";
-          const headerValue = buildAuthHeader(token, authConfig);
-          context.options.headers = context.options.headers || new Headers();
-          if (context.options.headers instanceof Headers) {
-            context.options.headers.set(headerName, headerValue);
-          } else {
-            context.options.headers[headerName] = headerValue;
-          }
-        }
-      }
-      if (publicConfig.debug) {
-        console.log(`[Movk API] Request: ${context.options.method || "GET"} ${resolvedConfig.baseURL}${context.request}`);
-      }
-    },
-    async onRequestError({ error }) {
-      if (publicConfig.debug) {
-        console.error("[Movk API] Request Error:", error);
-      }
-    },
-    async onResponse(context) {
-      const response = context.response;
-      const data = response._data;
-      if (publicConfig.debug) {
-        console.log("[Movk API] Response:", data);
-      }
-      if (!import.meta.client) return;
-      const { toast, skipBusinessCheck } = getApiFetchContext(context);
-      const isSuccess = skipBusinessCheck || isBusinessSuccess(data, responseConfig);
-      const message = extractMessage(data, responseConfig);
-      if (isSuccess) {
-        const successMessage = toast !== false ? toast?.successMessage || message : void 0;
-        showToast("success", successMessage, toast, toastConfig);
-      }
-    },
-    async onResponseError(context) {
-      const { response } = context;
-      if (response.status === 401) {
-        await handleUnauthorized(authConfig);
-      }
-      if (publicConfig.debug) {
-        console.error("[Movk API] Error:", response.status, response._data);
-      }
-      if (!import.meta.client) return;
-      const { toast } = getApiFetchContext(context);
-      const data = response._data;
-      const message = data ? extractMessage(data, responseConfig) : void 0;
-      const errorMessage = toast !== false ? toast?.errorMessage || message || `\u8BF7\u6C42\u5931\u8D25 (${response.status})` : void 0;
-      showToast("error", errorMessage, toast, toastConfig);
-    }
-  };
-}
-function createApiClient(resolvedConfig, publicConfig, getOrCreateEndpoint) {
-  const builtinHooks = createBuiltinHooks(resolvedConfig, publicConfig);
-  resolvedConfig.builtinHooks = builtinHooks;
-  const $fetchInstance = $fetch.create({
+import { resolveEndpointConfig } from "../domains/api/endpoint-config.js";
+import { createOnRequest } from "../domains/api/interceptors/request.js";
+import { createOnResponse } from "../domains/api/interceptors/response.js";
+import { createOnResponseError } from "../domains/api/interceptors/error.js";
+import { defineNuxtPlugin, useNuxtApp, useRuntimeConfig } from "#imports";
+function createEndpointFetch(resolvedConfig, publicConfig, nuxtApp) {
+  return $fetch.create({
     baseURL: resolvedConfig.baseURL,
     headers: resolvedConfig.headers,
-    onRequest: builtinHooks.onRequest,
-    onRequestError: builtinHooks.onRequestError,
-    onResponse: builtinHooks.onResponse,
-    onResponseError: builtinHooks.onResponseError
+    onRequest: createOnRequest(resolvedConfig, publicConfig, nuxtApp),
+    onResponse: createOnResponse(resolvedConfig, publicConfig, nuxtApp),
+    onResponseError: createOnResponseError(resolvedConfig, publicConfig, nuxtApp)
   });
-  const download = async (url, filename, options = {}) => {
-    const { toast, ...fetchOptions } = options;
-    const response = await $fetchInstance.raw(url, {
-      ...fetchOptions,
-      method: "GET",
-      responseType: "blob",
-      context: { toast }
-    });
-    if (!response._data) {
-      throw new Error("\u4E0B\u8F7D\u5931\u8D25: \u672A\u63A5\u6536\u5230\u6570\u636E");
-    }
-    const finalFilename = filename || extractFilename(response.headers, url.split("/").pop() || "download");
-    triggerDownload(response._data, finalFilename);
-    if (import.meta.client && toast !== false) {
-      const message = extractToastMessage(toast, "success", `\u4E0B\u8F7D\u6210\u529F: ${finalFilename}`);
-      showToast("success", message, toast, resolvedConfig.toast);
-    }
-  };
-  const upload = async (url, file, options = {}) => {
-    const { toast, fieldName = "file", ...fetchOptions } = options;
-    const formData = file instanceof FormData ? file : (() => {
-      const fd = new FormData();
-      const files = Array.isArray(file) ? file : [file];
-      files.forEach((f) => fd.append(fieldName, f));
-      return fd;
-    })();
-    return $fetchInstance(url, {
-      ...fetchOptions,
-      method: "POST",
-      body: formData,
-      context: { toast }
-    });
-  };
-  return {
-    $fetch: $fetchInstance,
-    use: (endpoint) => getOrCreateEndpoint(endpoint),
-    download,
-    upload,
-    getConfig: () => resolvedConfig
-  };
 }
 export default defineNuxtPlugin(() => {
+  const nuxtApp = useNuxtApp();
   const runtimeConfig = useRuntimeConfig();
   const publicConfig = runtimeConfig.public.movkApi;
-  const privateConfig = import.meta.server ? runtimeConfig.movkApi : void 0;
+  const privateEndpoints = import.meta.server ? runtimeConfig.movkApi?.endpoints : void 0;
   const endpointCache = /* @__PURE__ */ new Map();
+  const defaultEndpoint = publicConfig.defaultEndpoint || "default";
   const getOrCreateEndpoint = (endpointName) => {
-    if (endpointCache.has(endpointName)) {
-      return endpointCache.get(endpointName);
-    }
-    const endpoints = publicConfig.endpoints || {};
-    const endpointConfig = endpoints[endpointName];
-    if (!endpointConfig) {
-      console.warn(`[Movk API] Endpoint "${endpointName}" not found, using default`);
-      return getOrCreateEndpoint(publicConfig.defaultEndpoint || "default");
+    const cached = endpointCache.get(endpointName);
+    if (cached) return cached;
+    if (!publicConfig.endpoints?.[endpointName] && endpointName !== defaultEndpoint) {
+      console.warn(`[@movk/nuxt] Endpoint "${endpointName}" not found, using default`);
+      return getOrCreateEndpoint(defaultEndpoint);
     }
-    const privateEndpointConfig = privateConfig?.endpoints?.[endpointName];
-    const resolvedConfig = {
-      ...endpointConfig,
-      headers: privateEndpointConfig?.headers,
-      auth: defu(endpointConfig.auth, publicConfig.auth),
-      toast: defu(endpointConfig.toast, publicConfig.toast),
-      response: defu(endpointConfig.response, publicConfig.response)
-    };
-    const client = createApiClient(resolvedConfig, publicConfig, getOrCreateEndpoint);
-    endpointCache.set(endpointName, client);
-    return client;
+    const resolved = resolveEndpointConfig(publicConfig, endpointName, privateEndpoints);
+    const $fetchInstance = createEndpointFetch(resolved, publicConfig, nuxtApp);
+    const apiInstance = Object.assign($fetchInstance, {
+      use: (endpoint) => getOrCreateEndpoint(endpoint)
+    });
+    endpointCache.set(endpointName, apiInstance);
+    return apiInstance;
   };
-  const defaultEndpoint = publicConfig.defaultEndpoint || "default";
   const api = getOrCreateEndpoint(defaultEndpoint);
   return {
-    provide: { api }
+    provide: {
+      api
+    }
   };
 });

package/dist/runtime/plugins/theme.js

@@ -1,98 +1,100 @@
-import { defineNuxtPlugin, onNuxtReady, useAppConfig, useHead, useSiteConfig } from "#imports";
-import { themeIcons } from "../utils/theme.js";
+import { kebabCase } from "@movk/core";
+import { defineNuxtPlugin, useAppConfig, useHead, useSiteConfig } from "#imports";
+import { themeIcons } from "../domains/theme/theme-icons.js";
 export default defineNuxtPlugin({
   enforce: "post",
   setup() {
     const appConfig = useAppConfig();
     const site = useSiteConfig();
+    const name = kebabCase(site.name);
     if (import.meta.client) {
-      let updateColor = function(type) {
-        const color = localStorage.getItem(`${site.name}-ui-${type}`);
-        if (color) {
-          appConfig.ui.colors[type] = color;
-        }
-      }, updateRadius = function() {
-        const radius = localStorage.getItem(`${site.name}-ui-radius`);
-        if (radius) {
-          appConfig.theme.radius = Number.parseFloat(radius);
-        }
-      }, updateBlackAsPrimary = function() {
-        const blackAsPrimary = localStorage.getItem(`${site.name}-ui-black-as-primary`);
-        if (blackAsPrimary) {
-          appConfig.theme.blackAsPrimary = blackAsPrimary === "true";
-        }
-      }, updateFont = function() {
-        const font = localStorage.getItem(`${site.name}-ui-font`);
-        if (font) {
-          appConfig.theme.font = font;
-        }
-      };
-      updateColor("primary");
-      updateColor("neutral");
-      updateRadius();
-      updateBlackAsPrimary();
-      updateFont();
+      const primary = localStorage.getItem(`${name}-ui-primary`);
+      if (primary) appConfig.ui.colors.primary = primary;
+      const neutral = localStorage.getItem(`${name}-ui-neutral`);
+      if (neutral) appConfig.ui.colors.neutral = neutral;
+      const icons = localStorage.getItem(`${name}-ui-icons`);
+      if (icons) appConfig.ui.icons = themeIcons[icons];
     }
-    onNuxtReady(() => {
-      function updateIcons() {
-        const icons = localStorage.getItem(`${site.name}-ui-icons`);
-        if (icons) {
-          appConfig.theme.icons = icons;
-          appConfig.ui.icons = themeIcons[icons];
-        }
-      }
-      updateIcons();
-    });
     if (import.meta.server) {
+      const pickerFonts = appConfig.movk?.picker?.fonts ?? [];
+      const fontHrefMap = {};
+      for (const f of pickerFonts) {
+        if (f.href) fontHrefMap[f.name] = f.href;
+      }
+      const fontHrefMapJson = JSON.stringify(fontHrefMap);
       useHead({
         script: [{
           innerHTML: `
-            let html = document.querySelector('style#nuxt-ui-colors').innerHTML;
-
-            if (localStorage.getItem('${site.name}-ui-primary')) {
-              const primaryColor = localStorage.getItem('${site.name}-ui-primary');
-              if (primaryColor !== 'black') {
-                html = html.replace(
-                  /(--ui-color-primary-\\d{2,3}:\\s*var\\(--color-)${appConfig.ui.colors.primary}(-\\d{2,3}.*?\\))/g,
-                  \`$1\${primaryColor}$2\`
-                );
+            (function() {
+              var primaryColor = localStorage.getItem('${name}-ui-primary');
+              var neutralColor = localStorage.getItem('${name}-ui-neutral');
+              if (!primaryColor && !neutralColor) return;
+              function swapColors(el) {
+                var html = el.innerHTML;
+                if (primaryColor && primaryColor !== 'black') {
+                  html = html.replace(
+                    /(--ui-color-primary-\\d{2,3}:\\s*var\\(--color-)${appConfig.ui.colors.primary}(-\\d{2,3}.*?\\))/g,
+                    \`$1\${primaryColor}$2\`
+                  );
+                }
+                if (neutralColor) {
+                  html = html.replace(
+                    /(--ui-color-neutral-\\d{2,3}:\\s*var\\(--color-)${appConfig.ui.colors.neutral}(-\\d{2,3}.*?\\))/g,
+                    \`$1\${neutralColor === 'neutral' ? 'old-neutral' : neutralColor}$2\`
+                  );
+                }
+                el.innerHTML = html;
               }
-            }
-            if (localStorage.getItem('${site.name}-ui-neutral')) {
-              let neutralColor = localStorage.getItem('${site.name}-ui-neutral');
-              html = html.replace(
-                /(--ui-color-neutral-\\d{2,3}:\\s*var\\(--color-)${appConfig.ui.colors.neutral}(-\\d{2,3}.*?\\))/g,
-                \`$1\${neutralColor === 'neutral' ? 'old-neutral' : neutralColor}$2\`
-              );
-            }
-
-            document.querySelector('style#nuxt-ui-colors').innerHTML = html;
+              var colorsEl = document.querySelector('style#nuxt-ui-colors');
+              if (colorsEl) {
+                swapColors(colorsEl);
+              } else {
+                var obs = new MutationObserver(function(mutations) {
+                  for (var i = 0; i < mutations.length; i++) {
+                    for (var j = 0; j < mutations[i].addedNodes.length; j++) {
+                      var node = mutations[i].addedNodes[j];
+                      if (node.id === 'nuxt-ui-colors') {
+                        swapColors(node);
+                        obs.disconnect();
+                        return;
+                      }
+                    }
+                  }
+                });
+                obs.observe(document.head, { childList: true });
+              }
+            })();
             `.replace(/\s+/g, " "),
           type: "text/javascript",
           tagPriority: -1
         }, {
           innerHTML: `
-            if (localStorage.getItem('${site.name}-ui-radius')) {
-              document.querySelector('style#nuxt-ui-radius').innerHTML = ':root { --ui-radius: ' + localStorage.getItem('${site.name}-ui-radius') + 'rem; }';
-            }
+            var r = localStorage.getItem('${name}-ui-radius');
+            if (r) document.documentElement.style.setProperty('--ui-radius', r + 'rem');
           `.replace(/\s+/g, " "),
           type: "text/javascript",
           tagPriority: -1
         }, {
           innerHTML: `
-            if (localStorage.getItem('${site.name}-ui-black-as-primary') === 'true') {
-              document.querySelector('style#nuxt-ui-black-as-primary').innerHTML = ':root { --ui-primary: black; } .dark { --ui-primary: white; }';
-            } else {
-              document.querySelector('style#nuxt-ui-black-as-primary').innerHTML = '';
+            if (localStorage.getItem('${name}-ui-black-as-primary') === 'true') {
+              var isDark = document.documentElement.classList.contains('dark');
+              document.documentElement.style.setProperty('--ui-primary', isDark ? 'white' : 'black');
             }
           `.replace(/\s+/g, " ")
         }, {
-          innerHTML: `
-            if (localStorage.getItem('${site.name}-ui-font')) {
-              const font = localStorage.getItem('${site.name}-ui-font');
-              document.querySelector('style#nuxt-ui-font').innerHTML = ':root { --font-sans: \\'' + font + '\\', sans-serif; }';
-            }
-          `.replace(/\s+/g, " ")
+          innerHTML: [
+            `if (localStorage.getItem('${name}-ui-font')) {`,
+            `var font = localStorage.getItem('${name}-ui-font');`,
+            `var fontEl = document.querySelector('style#nuxt-ui-font');`,
+            `if (fontEl) { fontEl.innerHTML = ':root { --font-sans: \\'' + font + '\\', sans-serif; }'; }`,
+            `var fontMap = ${fontHrefMapJson};`,
+            `var lnk = document.createElement('link');`,
+            `lnk.rel = 'stylesheet';`,
+            `lnk.href = fontMap[font] || ('https://fonts.googleapis.com/css2?family=' + encodeURIComponent(font) + ':wght@400;500;600;700&display=swap');`,
+            `lnk.id = 'font-' + font.toLowerCase().replace(/\\s+/g, '-');`,
+            `document.head.appendChild(lnk);`,
+            `}`
+          ].join(" ")
         }]
       });
     }

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

@@ -0,0 +1,127 @@
+import type { Suggest } from '@movk/core';
+import type { Toast } from '@nuxt/ui/composables/useToast';
+/**
+ * API 响应配置
+ * @description 定义业务状态码判断规则和数据/消息字段的映射关系
+ */
+export interface ApiResponseConfig {
+    /**
+     * 表示成功的业务状态码列表
+     * @defaultValue [200, 0]
+     */
+    successCodes?: (number | string)[];
+    /**
+     * 响应中业务状态码的字段名
+     * @defaultValue 'code'
+     */
+    codeKey?: string;
+    /**
+     * 响应中消息内容的字段名
+     * @defaultValue 'message'
+     */
+    messageKey?: string;
+    /**
+     * 响应中业务数据的字段名
+     * @defaultValue 'data'
+     */
+    dataKey?: string;
+}
+/**
+ * API 认证配置
+ * @description 定义认证令牌的来源、格式和请求头配置
+ */
+export interface ApiAuthConfig {
+    /**
+     * 是否启用认证
+     * @defaultValue false
+     */
+    enabled?: boolean;
+    /**
+     * 令牌来源类型
+     * @defaultValue 'session'
+     */
+    tokenSource?: Suggest<'session'>;
+    /**
+     * 令牌在会话对象中的路径（支持点号分隔的嵌套路径）
+     * @defaultValue 'token'
+     * @example 'token' | 'user.accessToken' | 'auth.credentials.token'
+     */
+    sessionTokenPath?: string;
+    /**
+     * 令牌类型前缀
+     * @defaultValue 'Bearer'
+     */
+    tokenType?: Suggest<'Bearer' | 'Basic' | 'Custom'>;
+    /**
+     * 自定义令牌类型前缀（当 tokenType 为 'Custom' 时使用）
+     */
+    customTokenType?: string;
+    /**
+     * 认证请求头名称
+     * @defaultValue 'Authorization'
+     */
+    headerName?: string;
+    /**
+     * 401 未授权处理配置
+     */
+    unauthorized?: {
+        /** 是否自动重定向到登录页 @defaultValue true */
+        redirect?: boolean;
+        /** 登录页路径 @defaultValue '/login' */
+        loginPath?: string;
+        /** 是否清除用户会话 @defaultValue true */
+        clearSession?: boolean;
+    };
+}
+export interface ApiToast extends Toast {
+    /**
+     * 是否显示提示
+     * @defaultValue true
+     */
+    show?: boolean;
+}
+/**
+ * Toast 提示配置
+ * @description 定义成功和错误提示的全局样式和行为
+ */
+export interface ApiToastConfig {
+    /**
+     * 是否启用 Toast 提示
+     * @defaultValue true
+     */
+    enabled?: boolean;
+    /**
+     * 成功提示配置
+     */
+    success?: ApiToast;
+    /**
+     * 错误提示配置
+     */
+    error?: ApiToast;
+}
+/**
+ * API 端点公共配置
+ * @description 定义单个 API 端点的配置（可在客户端访问的配置）
+ */
+export interface ApiEndpointPublicConfig {
+    /**
+     * 端点的基础 URL
+     */
+    baseURL: string;
+    /**
+     * 端点别名（用于标识）
+     */
+    alias?: string;
+    /**
+     * 端点级别的认证配置（覆盖全局配置）
+     */
+    auth?: ApiAuthConfig;
+    /**
+     * 端点级别的 Toast 配置（覆盖全局配置）
+     */
+    toast?: ApiToastConfig;
+    /**
+     * 端点级别的响应配置（覆盖全局配置）
+     */
+    response?: ApiResponseConfig;
+}

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

@@ -0,0 +1,50 @@
+import type { $Fetch } from 'nitropack/types';
+import type { FetchError } from 'ofetch';
+import type { UseFetchOptions as NuxtUseFetchOptions, AsyncData } from 'nuxt/app';
+import type { RequestToastOptions, ApiError } from './response';
+/**
+ * 端点名声明合并入口
+ * @description 构建期由模块按 nuxt.config 的 movk.api.endpoints 自动注入；
+ * 用户也可在自有 d.ts 中通过 `declare module '@movk/nuxt'` 追加自定义端点名
+ */
+export interface MovkApiEndpoints {
+}
+/**
+ * 已声明的端点名联合
+ * @description 派生自 MovkApiEndpoints 的键集合
+ */
+export type MovkApiEndpointName = keyof MovkApiEndpoints & string;
+/**
+ * API 实例类型
+ * @description $fetch.create() 返回的实例，附加 use() 方法支持多端点切换
+ */
+export type ApiInstance = $Fetch & {
+    /** 切换到指定端点，返回该端点的 $fetch 实例 */
+    use: (endpoint: MovkApiEndpointName) => ApiInstance;
+};
+/**
+ * useApiFetch 选项类型
+ * @template T - 业务数据类型（已解包）
+ * @template DataT - transform 转换后的类型（默认等于 T）
+ */
+export type UseApiFetchOptions<T = unknown, DataT = T> = Omit<NuxtUseFetchOptions<T, DataT>, '$fetch' | 'context'> & {
+    /** 使用的端点名称（默认使用 defaultEndpoint） */
+    endpoint?: MovkApiEndpointName;
+    /** Toast 提示配置，设置为 false 禁用提示 */
+    toast?: RequestToastOptions | false;
+    /**
+     * 是否跳过业务状态码检查
+     * @description 仅跳过 code 校验，仍解包；与 skipUnwrap 正交。
+     */
+    skipBusinessCheck?: boolean;
+    /**
+     * 是否跳过数据解包
+     * @description 为 true 时返回原始响应；与 skipBusinessCheck 正交。
+     */
+    skipUnwrap?: boolean;
+};
+/**
+ * useApiFetch 返回值类型
+ * @template DataT - 最终数据类型
+ */
+export type UseApiFetchReturn<DataT> = AsyncData<DataT | null, FetchError | ApiError | null>;

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

@@ -0,0 +1,5 @@
+export type { ApiAuthConfig, ApiEndpointPublicConfig, ApiResponseConfig, ApiToastConfig } from './config';
+export type { MovkApiPublicConfig } from './module';
+export type { ApiError, ApiResponse, RequestToastOptions } from './response';
+export type { ApiInstance, MovkApiEndpointName, MovkApiEndpoints, UseApiFetchOptions, UseApiFetchReturn } from './fetch';
+export type { TransferRequestOptions, TransferResult, TransferStatus } from './transfer';

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

@@ -0,0 +1,94 @@
+import type { ApiAuthConfig, ApiEndpointPublicConfig, ApiResponseConfig, ApiToastConfig } from './config';
+/**
+ * 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?: ApiResponseConfig;
+    /**
+     * 全局认证配置
+     */
+    auth?: ApiAuthConfig;
+    /**
+     * 全局 Toast 配置
+     */
+    toast?: ApiToastConfig;
+}
+/**
+ * 已解析的端点配置
+ * @description 合并全局配置和端点配置后的最终配置，供内部使用
+ */
+export interface ResolvedEndpointConfig extends Omit<ApiEndpointPublicConfig, 'auth' | 'toast' | 'response'> {
+    /** 认证配置（已合并全局默认值，必然存在） */
+    auth: ApiAuthConfig;
+    /** Toast 配置（已合并全局默认值，必然存在） */
+    toast: ApiToastConfig;
+    /** 响应配置（已合并全局默认值，必然存在） */
+    response: ApiResponseConfig;
+    /** 自定义请求头（仅服务端配置） */
+    headers?: Record<string, string>;
+}