@movk/nuxt 1.2.0 → 1.3.0

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

@@ -1,139 +1,39 @@
-import {
-  showToast,
-  isBusinessSuccess,
-  extractMessage,
-  extractData,
-  createApiError,
-  extractToastMessage,
-  getAuthHeaders
-} from "../utils/api-utils.js";
-import { defineNuxtPlugin, navigateTo, useNuxtApp, useUserSession, useRuntimeConfig } from "#imports";
-import defu from "defu";
-async function handleUnauthorized(config, nuxtApp) {
-  const unauthorizedConfig = config.unauthorized;
-  if (!unauthorizedConfig) return;
-  if (unauthorizedConfig.clearSession) {
-    try {
-      const userSession = nuxtApp.vueApp.runWithContext(() => useUserSession());
-      if (userSession?.clear) {
-        await userSession.clear();
-        await userSession.fetch();
-      }
-    } catch {
-    }
-  }
-  if (unauthorizedConfig.redirect) {
-    const loginPath = unauthorizedConfig.loginPath || "/login";
-    await nuxtApp.runWithContext(() => navigateTo(loginPath));
-  }
-}
-function getApiFetchContext(options) {
-  return options.context || {};
-}
+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) {
-  const { auth: authConfig, toast: toastConfig, response: responseConfig } = resolvedConfig;
   return $fetch.create({
     baseURL: resolvedConfig.baseURL,
     headers: resolvedConfig.headers,
-    async onRequest(context) {
-      if (authConfig.enabled) {
-        const authHeaders = getAuthHeaders({ auth: authConfig });
-        const headers = new Headers(context.options.headers);
-        for (const [key, value] of Object.entries(authHeaders)) {
-          headers.set(key, value);
-        }
-        context.options.headers = headers;
-      }
-      if (publicConfig.debug) {
-        const h = context.options.headers;
-        const headersLog = h instanceof Headers ? Object.fromEntries(h.entries()) : h;
-        console.log("[Movk API] Request:", {
-          method: context.options.method || "GET",
-          url: `${resolvedConfig.baseURL}${context.request}`,
-          headers: headersLog,
-          body: context.options.body ? "(body present)" : void 0
-        });
-      }
-      await nuxtApp.callHook("movk:api:request", context);
-    },
-    async onResponse(context) {
-      const raw = context.response._data;
-      const { toast, skipBusinessCheck } = getApiFetchContext(context.options);
-      if (publicConfig.debug) {
-        console.log("[Movk API] Response:", raw);
-      }
-      if (skipBusinessCheck || isBusinessSuccess(raw, responseConfig)) {
-        context.response._data = extractData(raw, responseConfig);
-        await nuxtApp.callHook("movk:api:response", context);
-        if (import.meta.client) {
-          const message = toast !== false ? extractToastMessage(toast, "success", extractMessage(raw, responseConfig) || "") : void 0;
-          showToast("success", message, toast, toastConfig);
-        }
-      } else {
-        await nuxtApp.callHook("movk:api:error", context);
-        if (import.meta.client) {
-          const message = extractMessage(raw, responseConfig);
-          const errorMessage = toast !== false ? extractToastMessage(toast, "error", message || "\u8BF7\u6C42\u5931\u8D25") : void 0;
-          showToast("error", errorMessage, toast, toastConfig);
-        }
-        throw createApiError(raw, extractMessage(raw, responseConfig));
-      }
-    },
-    async onResponseError(context) {
-      const { response } = context;
-      const { toast } = getApiFetchContext(context.options);
-      if (response.status === 401) {
-        const result = { handled: false };
-        await nuxtApp.callHook("movk:api:unauthorized", context, result);
-        if (!result.handled) {
-          await handleUnauthorized(authConfig, nuxtApp);
-        }
-      }
-      await nuxtApp.callHook("movk:api:error", context);
-      if (import.meta.client) {
-        const data = response._data;
-        const message = data ? extractMessage(data, responseConfig) : void 0;
-        const errorMessage = toast !== false ? extractToastMessage(toast, "error", message || `\u8BF7\u6C42\u5931\u8D25 (${response.status})`) : void 0;
-        showToast("error", errorMessage, toast, toastConfig);
-      }
-      if (publicConfig.debug) {
-        console.error("[Movk API] Error:", response.status, response._data);
-      }
-    }
+    onRequest: createOnRequest(resolvedConfig, publicConfig, nuxtApp),
+    onResponse: createOnResponse(resolvedConfig, publicConfig, nuxtApp),
+    onResponseError: createOnResponseError(resolvedConfig, publicConfig, nuxtApp)
   });
 }
 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 $fetchInstance = createEndpointFetch(resolvedConfig, publicConfig, nuxtApp);
+    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: {

package/dist/runtime/plugins/theme.js

@@ -1,6 +1,6 @@
-import { defineNuxtPlugin, useAppConfig, useHead, useSiteConfig } from "#imports";
 import { kebabCase } from "@movk/core";
-import { themeIcons } from "../utils/theme.js";
+import { defineNuxtPlugin, useAppConfig, useHead, useSiteConfig } from "#imports";
+import { themeIcons } from "../domains/theme/theme-icons.js";
 export default defineNuxtPlugin({
   enforce: "post",
   setup() {
@@ -16,62 +16,84 @@ export default defineNuxtPlugin({
       if (icons) appConfig.ui.icons = themeIcons[icons];
     }
     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: `
-            var colorsEl = document.querySelector('style#nuxt-ui-colors');
-            if (colorsEl) {
-              let html = colorsEl.innerHTML;
-              if (localStorage.getItem('${name}-ui-primary')) {
-                const primaryColor = localStorage.getItem('${name}-ui-primary');
-                if (primaryColor !== 'black') {
+            (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('${name}-ui-neutral')) {
-                let neutralColor = localStorage.getItem('${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\`
-                );
+              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 });
               }
-
-              colorsEl.innerHTML = html;
-            }
+            })();
             `.replace(/\s+/g, " "),
           type: "text/javascript",
           tagPriority: -1
         }, {
           innerHTML: `
-            if (localStorage.getItem('${name}-ui-radius')) {
-              document.getElementById('${name}-ui-radius').innerHTML = ':root { --ui-radius: ' + localStorage.getItem('${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('${name}-ui-black-as-primary') === 'true') {
-              document.getElementById('${name}-ui-black-as-primary').innerHTML = ':root { --ui-primary: black; } .dark { --ui-primary: white; }';
-            } else {
-              document.getElementById('${name}-ui-black-as-primary').innerHTML = '';
+              var isDark = document.documentElement.classList.contains('dark');
+              document.documentElement.style.setProperty('--ui-primary', isDark ? 'white' : 'black');
             }
           `.replace(/\s+/g, " ")
         }, {
           innerHTML: [
             `if (localStorage.getItem('${name}-ui-font')) {`,
             `var font = localStorage.getItem('${name}-ui-font');`,
-            `document.getElementById('${name}-ui-font').innerHTML = ':root { --font-sans: \\'' + font + '\\', sans-serif; }';`,
-            `if (font !== 'Alibaba PuHuiTi' && ['Alibaba PuHuiTi', 'Public Sans', 'DM Sans', 'Geist', 'Inter', 'Poppins', 'Outfit', 'Raleway'].includes(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 = 'https://fonts.googleapis.com/css2?family=' + encodeURIComponent(font) + ':wght@400;500;600;700&display=swap';`,
+            `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>;
+}

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

@@ -0,0 +1,62 @@
+import type { Toast } from '@nuxt/ui/composables';
+declare module 'ofetch' {
+    interface FetchOptions {
+        context?: ApiFetchContext;
+    }
+}
+/**
+ * API 请求扩展上下文
+ * @description 通过 fetch options 的 context 字段传递的额外配置
+ */
+export interface ApiFetchContext {
+    /** Toast 提示配置，设置为 false 禁用提示 */
+    toast?: RequestToastOptions | false;
+    /**
+     * 是否跳过业务状态码检查
+     * @description 仅跳过 code 校验，**仍按 dataKey 解包**业务数据。与 skipUnwrap 正交。
+     */
+    skipBusinessCheck?: boolean;
+    /**
+     * 是否跳过数据解包
+     * @description 为 true 时拦截器不重写 response._data，调用方拿到原始响应。与 skipBusinessCheck 正交。
+     */
+    skipUnwrap?: boolean;
+}
+/**
+ * 请求级别的 Toast 提示选项
+ * @description 用于单个请求的 Toast 配置，可覆盖全局配置
+ */
+export interface RequestToastOptions {
+    /** 成功提示配置，设置为 false 禁用成功提示 */
+    success?: Partial<Toast> | false;
+    /** 错误提示配置，设置为 false 禁用错误提示 */
+    error?: Partial<Toast> | false;
+    /** 自定义成功消息 */
+    successMessage?: string;
+    /** 自定义错误消息 */
+    errorMessage?: string;
+}
+/**
+ * API 响应数据结构
+ * @description 字段名通过 ApiResponseConfig 的 codeKey/messageKey/dataKey 配置化读取
+ */
+export interface ApiResponse {
+    code?: number | string;
+    message?: string;
+    msg?: string;
+    data?: unknown;
+    status?: number;
+    [key: string]: unknown;
+}
+/**
+ * API 错误对象
+ * @description 扩展标准 Error，包含业务响应和状态码信息
+ */
+export interface ApiError extends Error {
+    /** HTTP 或业务状态码 */
+    statusCode?: number;
+    /** 原始 API 响应数据 */
+    response?: ApiResponse;
+    /** 是否为业务逻辑错误（非 HTTP 错误） */
+    isBusinessError: boolean;
+}

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

@@ -0,0 +1,32 @@
+import type { MovkApiEndpointName } from './fetch';
+import type { ApiError, RequestToastOptions } from './response';
+/**
+ * 传输状态
+ * @description idle 初始；pending 进行中；success 成功；error 失败；aborted 已中止
+ */
+export type TransferStatus = 'idle' | 'pending' | 'success' | 'error' | 'aborted';
+/**
+ * 传输结果（命令式调用返回值）
+ * @description data/error 二选一；aborted 标记是否被 abort 取消
+ */
+export interface TransferResult<T = unknown> {
+    /** 业务数据（已按 dataKey 解包）；失败或中止时为 null */
+    data: T | null;
+    /** 错误对象；成功或中止时为 null */
+    error: ApiError | Error | null;
+    /** 是否因调用方主动 abort 而结束 */
+    aborted: boolean;
+}
+/**
+ * 传输请求公共选项
+ */
+export interface TransferRequestOptions {
+    /** 端点名称，未指定时使用 defaultEndpoint */
+    endpoint?: MovkApiEndpointName;
+    /** 额外的请求头（覆盖同名 auth 头） */
+    headers?: Record<string, string>;
+    /** Toast 配置，设置为 false 整体禁用 */
+    toast?: RequestToastOptions | false;
+    /** 跳过业务码校验（仍按 dataKey 解包），与 useApiFetch.skipBusinessCheck 同义 */
+    skipBusinessCheck?: boolean;
+}

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

@@ -0,0 +1,6 @@
+declare module '#build/app.config' {
+  import type { AppConfig } from '@nuxt/schema'
+
+  const _default: AppConfig
+  export default _default
+}