@movk/nuxt 1.1.2 → 1.3.0

package/dist/runtime/composables/useUploadWithProgress.d.ts

@@ -1,52 +1,46 @@
-import type { ApiResponse, RequestToastOptions } from '../types/api.js';
+import type { NitroFetchRequest } from 'nitropack/types';
+import type { ApiError, TransferRequestOptions, TransferResult } from '../types/api';
 /**
- * 上传选项(带进度监控)
+ * 上传选项（带进度监控）
  */
-export interface UploadWithProgressOptions {
+export interface UploadWithProgressOptions<T = unknown> extends TransferRequestOptions {
     /** 文件字段名 @defaultValue 'file' */
     fieldName?: string;
     /** 额外的表单字段 */
     fields?: Record<string, string | Blob>;
-    /** 额外的请求头 */
-    headers?: Record<string, string>;
-    /** Toast 配置 */
-    toast?: RequestToastOptions | false;
-    /** 端点名称 */
-    endpoint?: string;
-    /** 上传成功回调 */
-    onSuccess?: (response: ApiResponse) => void;
-    /** 上传失败回调 */
-    onError?: (error: Error) => void;
+    /** 超时毫秒数，0 或未设置不超时 */
+    timeoutMs?: number;
+    /** 是否跨域携带凭证 */
+    withCredentials?: boolean;
+    /** 上传成功回调（解包后业务数据） */
+    onSuccess?: (data: T) => void;
+    /** 上传失败回调；中止时不触发 */
+    onError?: (error: ApiError | Error) => void;
 }
 /**
- * 带进度监控的文件上传 composable
+ * 带进度监控的文件上传 composable（仅客户端）
  *
- * 基于原生 XMLHttpRequest 实现，支持实时进度和取消上传
+ * @description 基于原生 XMLHttpRequest 实现，复用 `@movk/nuxt` 的端点/认证/业务校验/toast/hook 体系。
+ *  返回的 `data` 是按 `dataKey` 解包后的业务数据，与 `useApiFetch<T>` 一致。
  *
  * @example
  * ```ts
- * const { progress, uploading, upload, abort } = useUploadWithProgress()
+ * const { progress, status, data, upload, abort } = useUploadWithProgress<{ files: Array<{ name: string }> }>()
  *
- * const { data, error } = await upload('/api/upload', files, {
- *   fieldName: 'files',
- *   onSuccess: (res) => console.log('上传成功', res)
- * })
+ * await upload('/api/upload', files, { fieldName: 'files' })
  * ```
  */
 export declare function useUploadWithProgress<T = unknown>(): {
-    /** 上传进度 (0-100) */
+    /** 上传进度 0-100 */
     progress: any;
-    /** 是否正在上传 */
-    uploading: any;
-    /** 上传结果 */
+    /** 传输状态 */
+    status: any;
+    /** 解包后的业务数据 */
     data: any;
     /** 错误信息 */
     error: any;
     /** 执行上传 */
-    upload: (url: string, files: File | File[], options?: UploadWithProgressOptions) => Promise<{
-        data: ApiResponse<T> | null;
-        error: Error | null;
-    }>;
+    upload: (url: NitroFetchRequest, files: File | File[], options?: UploadWithProgressOptions<T>) => Promise<TransferResult<T>>;
     /** 中止上传 */
     abort: () => void;
 };

package/dist/runtime/composables/useUploadWithProgress.js

@@ -1,111 +1,122 @@
-import { ref, useNuxtApp } from "#imports";
+import { ref, useNuxtApp, useRuntimeConfig } from "#imports";
 import {
-  showToast,
-  isBusinessSuccess,
-  extractMessage,
-  extractToastMessage,
-  getAuthHeaders
-} from "../utils/api-utils.js";
+  buildFetchContext,
+  finalizeTransfer,
+  parseXhrHeaders,
+  prepareTransfer,
+  tryParseJsonResponse
+} from "../domains/api/transfer.js";
 export function useUploadWithProgress() {
-  const { $api } = useNuxtApp();
+  const publicConfig = useRuntimeConfig().public.movkApi;
+  const nuxtApp = useNuxtApp();
   const progress = ref(0);
-  const uploading = ref(false);
+  const status = ref("idle");
   const data = ref(null);
   const error = ref(null);
   let currentXhr = null;
   const abort = () => {
     currentXhr?.abort();
     currentXhr = null;
-    uploading.value = false;
+    status.value = "aborted";
     progress.value = 0;
   };
-  const upload = async (url, files, options = {}) => {
-    const { fieldName = "file", fields = {}, headers = {}, toast, endpoint, onSuccess, onError } = options;
-    const apiInstance = endpoint ? $api.use(endpoint) : $api;
-    const config = apiInstance.getConfig();
-    const fullUrl = `${config.baseURL || ""}${url}`;
+  const upload = (url, files, options = {}) => {
+    const {
+      fieldName = "file",
+      fields = {},
+      headers: userHeaders,
+      toast,
+      endpoint,
+      skipBusinessCheck,
+      timeoutMs,
+      withCredentials,
+      onSuccess,
+      onError
+    } = options;
+    const urlStr = typeof url === "string" ? url : url.url;
+    const { fullUrl, headers, config } = prepareTransfer(publicConfig, urlStr, {
+      endpoint,
+      headers: userHeaders,
+      toast,
+      skipBusinessCheck
+    });
     const formData = new FormData();
     const fileArray = Array.isArray(files) ? files : [files];
     fileArray.forEach((file) => formData.append(fieldName, file));
     Object.entries(fields).forEach(([key, value]) => formData.append(key, value));
     progress.value = 0;
-    uploading.value = true;
+    status.value = "pending";
     data.value = null;
     error.value = null;
     return new Promise((resolve) => {
       const xhr = new XMLHttpRequest();
       currentXhr = xhr;
+      if (withCredentials) xhr.withCredentials = true;
+      if (timeoutMs && timeoutMs > 0) xhr.timeout = timeoutMs;
       xhr.upload.addEventListener("progress", (e) => {
         if (e.lengthComputable) {
           progress.value = Math.round(e.loaded / e.total * 100);
         }
       });
-      xhr.addEventListener("load", () => {
-        uploading.value = false;
+      const finishWith = async (raw, fallback) => {
+        const responseHeaders = parseXhrHeaders(xhr.getAllResponseHeaders());
+        const fetchContext = buildFetchContext(fullUrl, { context: { toast, skipBusinessCheck } }, {
+          status: xhr.status,
+          headers: responseHeaders
+        });
+        const result = await finalizeTransfer(nuxtApp, {
+          raw,
+          fallback: fallback ? { isSuccess: fallback.isSuccess, data: null, message: fallback.message } : void 0,
+          config,
+          publicConfig,
+          requestToast: toast,
+          skipBusinessCheck,
+          fetchContext
+        });
         currentXhr = null;
-        try {
-          const response = JSON.parse(xhr.responseText);
-          const isSuccess = isBusinessSuccess(response, config.response);
-          const message = extractMessage(response, config.response);
-          if (isSuccess) {
-            data.value = response;
-            if (import.meta.client && toast !== false) {
-              const msg = extractToastMessage(toast, "success", message || "\u4E0A\u4F20\u6210\u529F");
-              showToast("success", msg, toast, config.toast);
-            }
-            onSuccess?.(response);
-            resolve({ data: response, error: null });
-          } else {
-            const err = new Error(message || "\u4E0A\u4F20\u5931\u8D25");
-            error.value = err;
-            if (import.meta.client && toast !== false) {
-              const msg = extractToastMessage(toast, "error", message || "\u4E0A\u4F20\u5931\u8D25");
-              showToast("error", msg, toast, config.toast);
-            }
-            onError?.(err);
-            resolve({ data: null, error: err });
-          }
-        } catch (err) {
-          const parseError = err instanceof Error ? err : new Error("\u54CD\u5E94\u89E3\u6790\u5931\u8D25");
-          error.value = parseError;
-          if (import.meta.client && toast !== false) {
-            showToast("error", "\u4E0A\u4F20\u5931\u8D25", toast, config.toast);
-          }
-          onError?.(parseError);
-          resolve({ data: null, error: parseError });
+        if (result.error) {
+          status.value = "error";
+          error.value = result.error;
+          onError?.(result.error);
+        } else {
+          status.value = "success";
+          data.value = result.data;
+          progress.value = 100;
+          if (result.data !== null) onSuccess?.(result.data);
+        }
+        resolve(result);
+      };
+      xhr.addEventListener("load", () => {
+        const responseHeaders = parseXhrHeaders(xhr.getAllResponseHeaders());
+        const raw = tryParseJsonResponse(responseHeaders, xhr.responseText);
+        if (xhr.status < 200 || xhr.status >= 300) {
+          void finishWith(raw, { isSuccess: false, message: `HTTP ${xhr.status} ${xhr.statusText}` });
+          return;
         }
+        void finishWith(raw, raw ? void 0 : { isSuccess: true, message: "\u4E0A\u4F20\u6210\u529F" });
       });
       xhr.addEventListener("error", () => {
-        uploading.value = false;
-        currentXhr = null;
-        const err = new Error("\u7F51\u7EDC\u9519\u8BEF");
-        error.value = err;
-        if (import.meta.client && toast !== false) {
-          showToast("error", "\u4E0A\u4F20\u5931\u8D25", toast, config.toast);
-        }
-        onError?.(err);
-        resolve({ data: null, error: err });
+        void finishWith(null, { isSuccess: false, message: "\u7F51\u7EDC\u9519\u8BEF" });
+      });
+      xhr.addEventListener("timeout", () => {
+        void finishWith(null, { isSuccess: false, message: `\u4E0A\u4F20\u8D85\u65F6\uFF08${timeoutMs}ms\uFF09` });
       });
       xhr.addEventListener("abort", () => {
-        uploading.value = false;
         currentXhr = null;
-        error.value = new Error("\u4E0A\u4F20\u5DF2\u53D6\u6D88");
-        resolve({ data: null, error: error.value });
+        status.value = "aborted";
+        resolve({ data: null, error: null, aborted: true });
       });
       xhr.open("POST", fullUrl);
-      const authHeaders = getAuthHeaders(config);
-      Object.entries({ ...headers, ...authHeaders }).forEach(([key, value]) => {
-        xhr.setRequestHeader(key, value);
-      });
+      Object.entries(headers).forEach(([k, v]) => xhr.setRequestHeader(k, v));
       xhr.send(formData);
     });
   };
   return {
-    /** 上传进度 (0-100) */
+    /** 上传进度 0-100 */
     progress,
-    /** 是否正在上传 */
-    uploading,
-    /** 上传结果 */
+    /** 传输状态 */
+    status,
+    /** 解包后的业务数据 */
     data,
     /** 错误信息 */
     error,

package/dist/runtime/domains/api/auth.d.ts

@@ -0,0 +1,2 @@
+import type { ApiAuthConfig } from '../../types/api';
+export declare function getAuthHeaders(auth: ApiAuthConfig): Record<string, string>;

package/dist/runtime/domains/api/auth.js

@@ -0,0 +1,31 @@
+import { getPath } from "@movk/core";
+import { useNuxtApp, useUserSession } from "#imports";
+function getUserSession() {
+  try {
+    const nuxtApp = useNuxtApp();
+    return nuxtApp.vueApp.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 buildAuthHeaderValue(token, config) {
+  const tokenType = config.tokenType === "Custom" ? config.customTokenType || "" : config.tokenType || "Bearer";
+  return tokenType ? `${tokenType} ${token}` : token;
+}
+export function getAuthHeaders(auth) {
+  const headers = {};
+  if (!auth.enabled) return headers;
+  const tokenPath = auth.sessionTokenPath || "token";
+  const token = getTokenFromSession(tokenPath);
+  if (token) {
+    const headerName = auth.headerName || "Authorization";
+    headers[headerName] = buildAuthHeaderValue(token, auth);
+  }
+  return headers;
+}

package/dist/runtime/domains/api/endpoint-config.d.ts

@@ -0,0 +1,11 @@
+import type { MovkApiPublicConfig } from '../../types/api';
+import type { EndpointPrivateConfig, ResolvedEndpointConfig } from '../../types/api/module';
+/**
+ * 合并全局与端点配置为运行时实际生效的 ResolvedEndpointConfig
+ *
+ * @param publicConfig 模块公共配置
+ * @param endpoint 端点名称；未指定时使用 defaultEndpoint
+ * @param privateEndpoints 服务端私有端点配置（含 headers），仅在服务端可用
+ * @description 端点不存在时降级到 defaultEndpoint，并打印警告
+ */
+export declare function resolveEndpointConfig(publicConfig: MovkApiPublicConfig, endpoint?: string, privateEndpoints?: Record<string, EndpointPrivateConfig>): ResolvedEndpointConfig;

package/dist/runtime/domains/api/endpoint-config.js

@@ -0,0 +1,17 @@
+import defu from "defu";
+export function resolveEndpointConfig(publicConfig, endpoint, privateEndpoints) {
+  const endpointName = endpoint || publicConfig.defaultEndpoint || "default";
+  const endpointConfig = publicConfig.endpoints?.[endpointName];
+  if (!endpointConfig) {
+    console.warn(`[@movk/nuxt] Endpoint "${endpointName}" not found, using default`);
+    return resolveEndpointConfig(publicConfig, publicConfig.defaultEndpoint || "default", privateEndpoints);
+  }
+  return {
+    ...endpointConfig,
+    baseURL: endpointConfig.baseURL || "",
+    headers: privateEndpoints?.[endpointName]?.headers,
+    auth: defu(endpointConfig.auth, publicConfig.auth),
+    toast: defu(endpointConfig.toast, publicConfig.toast),
+    response: defu(endpointConfig.response, publicConfig.response)
+  };
+}

package/dist/runtime/domains/api/errors.d.ts

@@ -0,0 +1,2 @@
+import type { ApiError, ApiResponse } from '../../types/api';
+export declare function createApiError(response: ApiResponse, message?: string): ApiError;

package/dist/runtime/domains/api/errors.js

@@ -0,0 +1,10 @@
+export function createApiError(response, message) {
+  const error = new Error(message || "\u8BF7\u6C42\u5931\u8D25", { cause: response });
+  const rawCode = response.code ?? response.status ?? 500;
+  const numericCode = typeof rawCode === "number" ? rawCode : Number(rawCode);
+  error.statusCode = Number.isNaN(numericCode) ? 500 : numericCode;
+  error.response = response;
+  error.isBusinessError = true;
+  Error.captureStackTrace?.(error, createApiError);
+  return error;
+}

package/dist/runtime/domains/api/fetch-key.d.ts

@@ -0,0 +1,20 @@
+import type { RequestToastOptions } from '../../types/api';
+interface ApiFetchKeyInput {
+    endpoint?: string;
+    skipUnwrap?: boolean;
+    skipBusinessCheck?: boolean;
+    toast?: RequestToastOptions | false;
+    method?: string;
+    url: unknown;
+    query?: unknown;
+    body?: unknown;
+}
+/**
+ * 计算 useApiFetch 的去重 key
+ *
+ * @description 纳入所有影响处理逻辑的维度（含请求级 toast），避免同 URL 不同 toast 配置
+ * 因 key 相同被 Nuxt useAsyncData 去重，复用首个 handler 导致单次配置失效。
+ * 入参须为已 resolve 的值（调用方负责 toValue）。
+ */
+export declare function buildApiFetchKey(input: ApiFetchKeyInput): string;
+export {};

package/dist/runtime/domains/api/fetch-key.js

@@ -0,0 +1,23 @@
+import { simpleHash } from "@movk/core";
+export function buildApiFetchKey(input) {
+  const { endpoint, skipUnwrap, skipBusinessCheck, toast, method, url, query, body } = input;
+  const payload = {
+    e: endpoint ?? null,
+    su: skipUnwrap === true,
+    sbc: skipBusinessCheck === true,
+    t: toast ?? null,
+    m: method ?? "GET",
+    u: url,
+    q: query ?? null,
+    b: body ?? null
+  };
+  let raw;
+  try {
+    raw = JSON.stringify(payload);
+  } catch {
+    const toastTag = toast === false ? "off" : toast ? "obj" : "";
+    const urlTag = typeof url === "string" ? url : "<req>";
+    raw = `${endpoint ?? ""}|${skipUnwrap}|${skipBusinessCheck}|${toastTag}|${payload.m}|${urlTag}|<body>`;
+  }
+  return `mvk-api:${simpleHash(raw)}`;
+}

package/dist/runtime/domains/api/interceptors/error.d.ts

@@ -0,0 +1,13 @@
+import type { FetchContext } from 'ofetch';
+import type { MovkApiPublicConfig } from '../../../types/api';
+import type { ResolvedEndpointConfig } from '../../../types/api/module';
+import type { useNuxtApp } from '#imports';
+type NuxtApp = ReturnType<typeof useNuxtApp>;
+/**
+ * 构造 onResponseError 拦截器
+ *
+ * @description 401 优先派发 `movk:api:unauthorized` hook 让业务侧自定义处理；
+ * `result.handled === true` 时**跳过** `movk:api:error` 派发，避免全局错误上报双计 401。
+ */
+export declare function createOnResponseError(resolvedConfig: ResolvedEndpointConfig, publicConfig: MovkApiPublicConfig, nuxtApp: NuxtApp): (context: FetchContext) => Promise<void>;
+export {};

package/dist/runtime/domains/api/interceptors/error.js

@@ -0,0 +1,49 @@
+import { navigateTo, useUserSession } from "#imports";
+import { showToast } from "../toast.js";
+function readApiContext(options) {
+  return options.context || {};
+}
+async function handleUnauthorized(authConfig, nuxtApp) {
+  const unauthorizedConfig = authConfig.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));
+  }
+}
+export function createOnResponseError(resolvedConfig, publicConfig, nuxtApp) {
+  const { auth: authConfig, toast: toastConfig, response: responseConfig } = resolvedConfig;
+  return async function onResponseError(context) {
+    const { response } = context;
+    if (!response) return;
+    const { toast } = readApiContext(context.options);
+    let unauthorizedHandled = false;
+    if (response.status === 401) {
+      const result = { handled: false };
+      await nuxtApp.callHook("movk:api:unauthorized", context, result);
+      unauthorizedHandled = result.handled;
+      if (!unauthorizedHandled) {
+        await handleUnauthorized(authConfig, nuxtApp);
+      }
+    }
+    if (!unauthorizedHandled) {
+      await nuxtApp.callHook("movk:api:error", context);
+    }
+    const data = response._data;
+    const fallback = `\u8BF7\u6C42\u5931\u8D25 (${response.status})`;
+    showToast("error", data ?? fallback, toast, toastConfig, responseConfig);
+    if (publicConfig.debug) {
+      console.error("[@movk/nuxt] Error:", response.status, response._data);
+    }
+  };
+}

package/dist/runtime/domains/api/interceptors/request.d.ts

@@ -0,0 +1,12 @@
+import type { FetchContext } from 'ofetch';
+import type { MovkApiPublicConfig } from '../../../types/api';
+import type { ResolvedEndpointConfig } from '../../../types/api/module';
+import type { useNuxtApp } from '#imports';
+type NuxtApp = ReturnType<typeof useNuxtApp>;
+/**
+ * 构造 onRequest 拦截器：注入认证头、debug 日志、派发 movk:api:request hook
+ *
+ * @description Headers 重建前会过滤 undefined 值，规避 ofetch 某些版本 `Record<string, string | undefined>` 导致的 TypeError
+ */
+export declare function createOnRequest(resolvedConfig: ResolvedEndpointConfig, publicConfig: MovkApiPublicConfig, nuxtApp: NuxtApp): (context: FetchContext) => Promise<void>;
+export {};

package/dist/runtime/domains/api/interceptors/request.js

@@ -0,0 +1,46 @@
+import { getAuthHeaders } from "../auth.js";
+function toHeaderRecord(headers) {
+  const out = {};
+  if (!headers) return out;
+  if (headers instanceof Headers) {
+    headers.forEach((value, key) => {
+      out[key] = value;
+    });
+    return out;
+  }
+  if (Array.isArray(headers)) {
+    for (const entry of headers) {
+      if (entry && entry[1] !== void 0) out[entry[0]] = entry[1];
+    }
+    return out;
+  }
+  for (const [key, value] of Object.entries(headers)) {
+    if (value !== void 0) out[key] = value;
+  }
+  return out;
+}
+export function createOnRequest(resolvedConfig, publicConfig, nuxtApp) {
+  const { auth: authConfig } = resolvedConfig;
+  return async function onRequest(context) {
+    if (authConfig.enabled) {
+      const authHeaders = getAuthHeaders(authConfig);
+      const normalized = toHeaderRecord(context.options.headers);
+      const headers = new Headers(normalized);
+      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.info("[@movk/nuxt] 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);
+  };
+}

package/dist/runtime/domains/api/interceptors/response.d.ts

@@ -0,0 +1,17 @@
+import type { FetchContext } from 'ofetch';
+import type { MovkApiPublicConfig } from '../../../types/api';
+import type { ResolvedEndpointConfig } from '../../../types/api/module';
+import type { useNuxtApp } from '#imports';
+type NuxtApp = ReturnType<typeof useNuxtApp>;
+/**
+ * 构造 onResponse 拦截器
+ *
+ * @description 业务校验链路：
+ * - 校验通过（或 skipBusinessCheck）→ 按 skipUnwrap 决定是否解包 _data → 派发 movk:api:response hook → 触发成功 toast
+ * - 校验失败 → 派发 movk:api:error hook → 触发错误 toast → 抛 createApiError
+ *
+ * **契约**：拦截器输出 = 业务数据。`movk:api:response` hook 收到的 `context.response._data` 已解包；
+ * 调用方设置 `skipUnwrap: true` 时不重写 `_data`，保留原始响应。
+ */
+export declare function createOnResponse(resolvedConfig: ResolvedEndpointConfig, publicConfig: MovkApiPublicConfig, nuxtApp: NuxtApp): (context: FetchContext) => Promise<void>;
+export {};

package/dist/runtime/domains/api/interceptors/response.js

@@ -0,0 +1,27 @@
+import { extractData, extractMessage, isBusinessSuccess } from "../response.js";
+import { createApiError } from "../errors.js";
+import { showToast } from "../toast.js";
+function readApiContext(options) {
+  return options.context || {};
+}
+export function createOnResponse(resolvedConfig, publicConfig, nuxtApp) {
+  const { toast: toastConfig, response: responseConfig } = resolvedConfig;
+  return async function onResponse(context) {
+    const raw = context.response?._data;
+    const { toast, skipBusinessCheck, skipUnwrap } = readApiContext(context.options);
+    if (publicConfig.debug) {
+      console.info("[@movk/nuxt] Response:", raw);
+    }
+    if (skipBusinessCheck || isBusinessSuccess(raw, responseConfig)) {
+      if (!skipUnwrap && context.response) {
+        context.response._data = extractData(raw, responseConfig);
+      }
+      await nuxtApp.callHook("movk:api:response", context);
+      showToast("success", raw, toast, toastConfig, responseConfig);
+      return;
+    }
+    await nuxtApp.callHook("movk:api:error", context);
+    showToast("error", raw, toast, toastConfig, responseConfig);
+    throw createApiError(raw, extractMessage(raw, responseConfig));
+  };
+}

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

@@ -0,0 +1,4 @@
+import type { ApiResponse, ApiResponseConfig } from '../../types/api';
+export declare function isBusinessSuccess(response: ApiResponse, config?: Partial<ApiResponseConfig>): boolean;
+export declare function extractMessage(response: ApiResponse, config?: Partial<ApiResponseConfig>): string | undefined;
+export declare function extractData(response: ApiResponse, config?: Partial<ApiResponseConfig>): unknown;

package/dist/runtime/domains/api/response.js

@@ -0,0 +1,14 @@
+export function isBusinessSuccess(response, config = {}) {
+  const codeKey = config.codeKey || "code";
+  const successCodes = config.successCodes || [200, 0];
+  const code = response[codeKey];
+  return successCodes.includes(code);
+}
+export function extractMessage(response, config = {}) {
+  const messageKey = config.messageKey || "message";
+  return response[messageKey] || response.message || response.msg;
+}
+export function extractData(response, config = {}) {
+  const dataKey = config.dataKey || "data";
+  return dataKey in response ? response[dataKey] : void 0;
+}

package/dist/runtime/domains/api/toast.d.ts

@@ -0,0 +1,15 @@
+import type { ApiResponse, ApiResponseConfig, ApiToastConfig, RequestToastOptions } from '../../types/api';
+type ToastType = 'success' | 'error';
+/**
+ * 触发 Toast 提示
+ *
+ * @description 决策收敛在本函数内：是否启用 / 类型是否启用 / 提示文案选择 / payload 构造。
+ *
+ * @param type 提示类型
+ * @param source 字符串作为 fallback 文案；ApiResponse 时按 responseConfig 抽取 message；undefined 走类型默认文案
+ * @param requestOptions 单次请求覆盖配置；为 false 时整体禁用
+ * @param globalConfig 全局 Toast 配置（已合并端点级覆盖）
+ * @param responseConfig 用于从 ApiResponse 抽取 message 的字段映射；source 为字符串时可省略
+ */
+export declare function showToast(type: ToastType, source: ApiResponse | string | undefined, requestOptions: RequestToastOptions | false | undefined, globalConfig: Partial<ApiToastConfig>, responseConfig?: Partial<ApiResponseConfig>): void;
+export {};

package/dist/runtime/domains/api/toast.js

@@ -0,0 +1,46 @@
+import { extractMessage } from "./response.js";
+import { useNuxtApp, useToast } from "#imports";
+function getToast() {
+  try {
+    const nuxtApp = useNuxtApp();
+    return nuxtApp.vueApp.runWithContext(() => useToast());
+  } catch {
+    return null;
+  }
+}
+function pickMessage(type, source, requestOptions, responseConfig) {
+  if (typeof requestOptions === "object") {
+    const custom = requestOptions[`${type}Message`];
+    if (custom) return custom;
+  }
+  if (typeof source === "string") return source;
+  if (source && responseConfig) {
+    const extracted = extractMessage(source, responseConfig);
+    if (extracted) return extracted;
+  }
+  return type === "success" ? "\u64CD\u4F5C\u6210\u529F" : "\u8BF7\u6C42\u5931\u8D25";
+}
+function compact(obj) {
+  const out = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (v !== void 0) out[k] = v;
+  }
+  return out;
+}
+export function showToast(type, source, requestOptions, globalConfig, responseConfig) {
+  if (globalConfig.enabled === false || requestOptions === false) return;
+  const typeConfig = globalConfig[type];
+  if (typeConfig?.show === false) return;
+  if (requestOptions?.[type] === false) return;
+  const message = pickMessage(type, source, requestOptions, responseConfig);
+  if (!message) return;
+  const toast = getToast();
+  if (!toast) return;
+  const { show: _show, ...typeConfigProps } = typeConfig ?? {};
+  const requestTypeConfig = typeof requestOptions?.[type] === "object" ? requestOptions[type] : {};
+  toast.add(compact({
+    title: message,
+    ...typeConfigProps,
+    ...requestTypeConfig
+  }));
+}