@movk/nuxt 0.1.1 → 1.0.0

package/dist/runtime/schemas/api.js

@@ -0,0 +1,212 @@
+import { z } from "zod/v4";
+export const apiSuccessConfigSchema = z.object({
+  /**
+   * 成功状态码列表
+   * @defaultValue [200, 0]
+   */
+  successCodes: z.array(z.union([z.number(), z.string()])).default([200, 0]),
+  /**
+   * 状态码字段名
+   * @defaultValue 'code'
+   */
+  codeKey: z.string().default("code"),
+  /**
+   * 消息字段名
+   * @defaultValue 'message'
+   */
+  messageKey: z.string().default("message"),
+  /**
+   * 数据字段名
+   * @defaultValue 'data'
+   */
+  dataKey: z.string().default("data")
+});
+export const apiSessionConfigSchema = z.object({
+  /**
+   * 是否启用 session 自动管理
+   * @defaultValue false
+   */
+  enabled: z.boolean().default(false),
+  /**
+   * 用户信息接口路径
+   * 登录成功后自动调用此接口获取用户信息
+   * 如果不设置，则从登录响应中提取用户信息
+   */
+  userInfoPath: z.string().optional(),
+  /**
+   * 从登录响应中提取 token 的路径
+   * @defaultValue 'data.token'
+   */
+  tokenPath: z.string().default("data.token"),
+  /**
+   * 用户信息在响应中的路径
+   * @defaultValue 'data'
+   */
+  userDataPath: z.string().default("data"),
+  /**
+   * session 中存储 token 的路径
+   * @defaultValue 'token'
+   */
+  sessionTokenPath: z.string().default("token")
+});
+export const apiAuthConfigSchema = z.object({
+  /**
+   * 是否启用认证
+   * @defaultValue false
+   */
+  enabled: z.boolean().default(false),
+  /**
+   * Token 来源
+   * - 'session': 从 nuxt-auth-utils 的 session 中获取 (推荐)
+   * - 'custom': 使用自定义 tokenGetter
+   * @defaultValue 'session'
+   */
+  tokenSource: z.enum(["session", "custom"]).default("session"),
+  /**
+   * Session 中 token 的路径
+   *
+   * 例如：
+   * - 'token' -> session.token
+   * - 'user.token' -> session.user.token
+   *
+   * @defaultValue 'token'
+   */
+  sessionTokenPath: z.string().default("token"),
+  /**
+   * Token 类型
+   * @defaultValue 'Bearer'
+   */
+  tokenType: z.enum(["Bearer", "Basic", "Custom"]).default("Bearer"),
+  /**
+   * 自定义 Token 类型值
+   * 当 tokenType 为 'Custom' 时使用
+   */
+  customTokenType: z.string().optional(),
+  /**
+   * 自定义 Header 名称
+   * @defaultValue 'Authorization'
+   */
+  headerName: z.string().default("Authorization"),
+  /**
+   * 401 错误时是否自动跳转登录页
+   * @defaultValue false
+   */
+  redirectOnUnauthorized: z.boolean().default(false),
+  /**
+   * 登录页路径
+   * @defaultValue '/login'
+   */
+  loginPath: z.string().default("/login"),
+  /**
+   * 是否在 401 时自动清除 session
+   * @defaultValue false
+   */
+  clearSessionOnUnauthorized: z.boolean().default(false)
+});
+export const apiToastConfigSchema = z.object({
+  /**
+   * 是否全局启用提示
+   * @defaultValue true
+   */
+  enabled: z.boolean().default(true),
+  /** 成功提示配置 */
+  success: z.object({
+    /**
+     * 是否显示成功提示
+     * @defaultValue true
+     */
+    show: z.boolean().default(true),
+    /**
+     * 默认颜色
+     * @defaultValue 'success'
+     */
+    color: z.string().default("success"),
+    /**
+     * 默认图标
+     */
+    icon: z.string().optional(),
+    /**
+     * 持续时间 (ms)
+     * @defaultValue 3000
+     */
+    duration: z.number().default(3e3)
+  }).loose().optional(),
+  /** 错误提示配置 */
+  error: z.object({
+    /**
+     * 是否显示错误提示
+     * @defaultValue true
+     */
+    show: z.boolean().default(true),
+    /**
+     * 默认颜色
+     * @defaultValue 'error'
+     */
+    color: z.string().default("error"),
+    /**
+     * 默认图标
+     */
+    icon: z.string().optional(),
+    /**
+     * 持续时间 (ms)
+     * @defaultValue 3000
+     */
+    duration: z.number().default(3e3)
+  }).loose().optional()
+});
+export const apiEndpointConfigSchema = z.object({
+  /** 基础 URL */
+  baseURL: z.string(),
+  /** 端点别名 */
+  alias: z.string().optional(),
+  /** 该端点的认证配置 */
+  auth: apiAuthConfigSchema.partial().optional(),
+  /** 该端点的 Toast 配置 */
+  toast: apiToastConfigSchema.partial().optional(),
+  /** 该端点的成功判断配置 */
+  success: apiSuccessConfigSchema.partial().optional(),
+  /** 默认请求头 */
+  headers: z.record(z.string(), z.string()).optional()
+});
+export const movkApiModuleOptionsSchema = z.object({
+  /**
+   * 是否启用 API 功能
+   * @defaultValue true
+   */
+  enabled: z.boolean().default(true),
+  /**
+   * 默认使用的端点名称
+   * @defaultValue 'default'
+   */
+  defaultEndpoint: z.string().default("default"),
+  /**
+   * API 端点配置
+   * @defaultValue { default: { baseURL: '/api' } }
+   */
+  endpoints: z.record(z.string(), apiEndpointConfigSchema).default({
+    default: { baseURL: "/api" }
+  }),
+  /**
+   * 全局认证配置
+   */
+  auth: apiAuthConfigSchema.optional(),
+  /**
+   * 全局 Toast 配置
+   */
+  toast: apiToastConfigSchema.optional(),
+  /**
+   * 全局成功判断配置
+   */
+  success: apiSuccessConfigSchema.optional(),
+  /**
+   * 是否启用调试模式
+   * @defaultValue false
+   */
+  debug: z.boolean().default(false)
+}).transform((data) => ({
+  ...data,
+  // 使用 schema 解析确保默认值生效
+  auth: apiAuthConfigSchema.parse(data.auth ?? {}),
+  toast: apiToastConfigSchema.parse(data.toast ?? {}),
+  success: apiSuccessConfigSchema.parse(data.success ?? {})
+}));

package/dist/runtime/server/api/_movk/session.post.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 用于登录成功后设置完整的 session 数据
+ * POST /api/_movk/session
+ *
+ * @body UserSession
+ */
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<{
+    success: boolean;
+}>>;
+export default _default;

package/dist/runtime/server/api/_movk/session.post.js

@@ -0,0 +1,18 @@
+import { defineEventHandler, readBody, createError } from "h3";
+export default defineEventHandler(async (event) => {
+  const body = await readBody(event);
+  if (!body || typeof body !== "object") {
+    throw createError({
+      statusCode: 400,
+      message: "Invalid request body"
+    });
+  }
+  if (!body.user || typeof body.user !== "object") {
+    throw createError({
+      statusCode: 400,
+      message: "User data is required"
+    });
+  }
+  await setUserSession(event, body);
+  return { success: true };
+});

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

@@ -0,0 +1,218 @@
+import type { $Fetch, FetchOptions, FetchHooks, 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 { apiSessionConfigSchema, apiEndpointConfigSchema, movkApiModuleOptionsSchema } from '../schemas/api.js';
+import { apiSuccessConfigSchema, apiAuthConfigSchema, apiToastConfigSchema } from '../schemas/api.js';
+import type { User, UserSession, UserSessionComposable } from '#auth-utils';
+/**
+ * 扩展 ofetch FetchOptions，添加 context 字段
+ *
+ * ofetch 运行时支持 context 字段用于在 hooks 间传递自定义数据，
+ * 但其 TypeScript 类型定义未包含此字段，这里进行补充
+ */
+declare module 'ofetch' {
+    interface FetchOptions {
+        /** 请求上下文，用于在 hooks 间传递自定义数据 */
+        context?: ApiFetchContext;
+    }
+}
+/**
+ * API 请求上下文
+ *
+ * 用于在 hooks 中传递请求级配置（如 Toast、业务检查等）
+ */
+export interface ApiFetchContext {
+    /** Toast 配置 */
+    toast?: RequestToastOptions | false;
+    /** 跳过业务状态码检查 */
+    skipBusinessCheck?: boolean;
+}
+/** 成功响应判断配置 */
+export type ApiSuccessConfig = z.infer<typeof apiSuccessConfigSchema>;
+/** Session 管理配置 */
+export type ApiSessionConfig = z.infer<typeof apiSessionConfigSchema>;
+/** 认证配置 */
+export type ApiAuthConfig = z.infer<typeof apiAuthConfigSchema>;
+/** Toast 配置 */
+export type ApiToastConfig = z.infer<typeof apiToastConfigSchema>;
+/** 单个端点配置 */
+export type ApiEndpointConfig = z.infer<typeof apiEndpointConfigSchema>;
+/** 模块配置 */
+export type MovkApiModuleOptions = z.infer<typeof movkApiModuleOptionsSchema>;
+/**
+ * API 标准响应结构
+ * 支持多种常见后端响应格式
+ */
+export interface ApiResponse<T = unknown> {
+    code?: number | string;
+    status?: number | string;
+    msg?: string;
+    message?: string;
+    data?: T;
+    result?: T;
+    token?: string;
+    accessToken?: string;
+    error?: string | null;
+    [key: string]: unknown;
+}
+/**
+ * API 业务错误
+ */
+export interface ApiError extends Error {
+    statusCode: number;
+    response?: ApiResponse;
+    isBusinessError: boolean;
+}
+/**
+ * 合并后的端点配置（运行时使用）
+ */
+export interface ResolvedEndpointConfig extends ApiEndpointConfig {
+    auth: Partial<ApiAuthConfig>;
+    toast: Partial<ApiToastConfig>;
+    success: Partial<ApiSuccessConfig>;
+    builtinHooks?: FetchHooks;
+}
+/**
+ * 请求级 Toast 配置
+ */
+export interface RequestToastOptions {
+    success?: Partial<ToastProps> | false;
+    error?: Partial<ToastProps> | false;
+    successMessage?: string;
+    errorMessage?: string;
+}
+/**
+ * useApiFetch 扩展选项
+ *
+ * @typeParam ResT - API 响应 data 字段的原始类型
+ * @typeParam DataT - transform 转换后的最终类型（默认等于 ResT）
+ */
+export interface ApiFetchExtras<ResT, DataT = ResT> {
+    /** 端点名称 */
+    endpoint?: string;
+    /** Toast 配置 */
+    toast?: RequestToastOptions | false;
+    /**
+     * 跳过业务状态码检查
+     * @defaultValue false
+     */
+    skipBusinessCheck?: boolean;
+    /**
+     * 自定义数据转换函数
+     * 接收解包后的数据（response.data），与 Nuxt 官方 useFetch 行为一致
+     *
+     * @example
+     * ```ts
+     * // 从分页响应中提取列表
+     * const { data } = useApiFetch<{ content: User[] }, User[]>('/users', {
+     *   transform: ({ content }) => content ?? []
+     * })
+     * ```
+     */
+    transform?: (data: ResT) => DataT;
+}
+/**
+ * useApiFetch 选项类型
+ *
+ * 基于 Nuxt UseFetchOptions，使用 Omit 移除冲突的 transform
+ * 支持双泛型：ResT 为原始响应类型，DataT 为转换后类型
+ *
+ * @typeParam ResT - API 响应 data 字段的原始类型
+ * @typeParam DataT - transform 转换后的最终类型（默认等于 ResT）
+ */
+export type UseApiFetchOptions<ResT, DataT = ResT> = Omit<NuxtUseFetchOptions<ApiResponse<ResT>, DataT>, 'transform'> & ApiFetchExtras<ResT, DataT>;
+/**
+ * useApiFetch 返回类型
+ */
+export type UseApiFetchReturn<DataT> = AsyncData<DataT | null, FetchError | ApiError | null>;
+/**
+ * 下载选项
+ */
+export interface DownloadOptions extends Omit<FetchOptions<'json'>, 'responseType'> {
+    /**
+     * Toast 配置
+     * - false: 禁用所有提示
+     * - RequestToastOptions: 自定义成功/失败提示
+     */
+    toast?: RequestToastOptions | false;
+    /**
+     * 下载进度回调
+     * @param progress - 下载进度百分比 (0-100)
+     */
+    onProgress?: (progress: number) => void;
+}
+/**
+ * 上传选项
+ */
+export interface UploadOptions extends Omit<FetchOptions<'json'>, 'responseType' | 'body'> {
+    /**
+     * 文件字段名
+     * @defaultValue 'file'
+     */
+    fieldName?: string;
+    /**
+     * Toast 配置
+     * - false: 禁用所有提示
+     * - RequestToastOptions: 自定义成功/失败提示
+     */
+    toast?: RequestToastOptions | false;
+    /**
+     * 上传进度回调
+     * @param progress - 上传进度百分比 (0-100)
+     */
+    onProgress?: (progress: number) => void;
+}
+/**
+ * API 客户端实例
+ */
+export interface ApiClient {
+    $fetch: $Fetch;
+    /**
+     * 切换端点
+     * @example $api.use('v2').$fetch('/users')
+     */
+    use: (endpoint: string) => ApiClient;
+    /**
+     * 下载文件
+     * @param url - 下载 URL
+     * @param filename - 可选的文件名,如果不提供会从 Content-Disposition 响应头中提取
+     * @param options - 下载选项
+     * @example await $api.download('/export', 'data.csv')
+     * @example await $api.download('/export') // 自动从响应头提取文件名
+     */
+    download: (url: string, filename?: string, options?: DownloadOptions) => Promise<void>;
+    /**
+     * 上传单个或多个文件
+     * @param url - 上传 URL
+     * @param file - 单个文件、文件数组或 FormData
+     * @param options - 上传选项
+     * @example await $api.upload('/upload', file, { fieldName: 'avatar' })
+     * @example await $api.upload('/upload', [file1, file2]) // 多文件上传
+     */
+    upload: <T = unknown>(url: string, file: File | File[] | FormData, options?: UploadOptions) => Promise<ApiResponse<T>>;
+    /**
+     * 获取端点配置（内部使用）
+     * @internal
+     */
+    getConfig: () => ResolvedEndpointConfig;
+}
+/** 登录选项 */
+export interface LoginOptions<LoginRData = unknown> {
+    loginPath: string;
+    credentials: unknown;
+    userInfoPath?: string;
+    tokenExtractor?: (response: ApiResponse<LoginRData>) => string | null | undefined;
+    sessionBuilder?: (userInfo: User, token: string) => UserSession;
+    endpoint?: string;
+}
+export interface LoginResult {
+    user: User;
+    token: string;
+}
+export interface UseApiAuthReturn extends UserSessionComposable {
+    login: <LoginRData = unknown>(options: LoginOptions<LoginRData>) => Promise<LoginResult>;
+}
+export declare const DEFAULT_SUCCESS_CONFIG: ApiSuccessConfig;
+export declare const DEFAULT_AUTH_CONFIG: ApiAuthConfig;
+export declare const DEFAULT_TOAST_CONFIG: ApiToastConfig;

package/dist/runtime/types/api.js

@@ -0,0 +1,8 @@
+import {
+  apiSuccessConfigSchema,
+  apiAuthConfigSchema,
+  apiToastConfigSchema
+} from "../schemas/api.js";
+export const DEFAULT_SUCCESS_CONFIG = apiSuccessConfigSchema.parse({});
+export const DEFAULT_AUTH_CONFIG = apiAuthConfigSchema.parse({});
+export const DEFAULT_TOAST_CONFIG = apiToastConfigSchema.parse({});

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

@@ -0,0 +1,34 @@
+declare module '#auth-utils' {
+  interface User {
+    // Add your own fields
+  }
+
+  interface UserSession {
+    /**
+     * Session ID
+     */
+    id?: string
+    /**
+     * User session data, available on client and server
+     */
+    user?: User
+    /**
+     * Private session data, only available on server/ code
+     */
+    secure?: SecureSessionData
+    /**
+     * 认证 Token
+     */
+    token?: string
+    /**
+     * Extra session data, available on client and server
+     */
+    [key: string]: unknown
+  }
+
+  interface SecureSessionData {
+    // Add your own fields
+  }
+}
+
+export { }

package/dist/runtime/types/auto-form-renderer.d.ts

@@ -1,30 +1,22 @@
-import type { z } from 'zod/v4'
-import type { AnyObject } from '@movk/core'
-import type { ButtonProps } from '@nuxt/ui'
-import type { AutoFormField } from './auto-form'
-import type { AutoFormProps } from '../components/AutoForm.vue'
-
-// AutoFormRendererArray
+import type { z } from 'zod/v4';
+import type { AnyObject } from '@movk/core';
+import type { ButtonProps } from '@nuxt/ui';
+import type { AutoFormField } from './auto-form.js';
+import type { AutoFormProps } from '../components/AutoForm.vue.js';
 export interface AutoFormRendererArrayProps<S extends z.ZodObject> extends Pick<AutoFormProps<S>, 'schema'> {
-  field: AutoFormField
-  extraProps?: AnyObject
-  addButtonProps?: Partial<ButtonProps>
+    field: AutoFormField;
+    extraProps?: AnyObject;
+    addButtonProps?: Partial<ButtonProps>;
 }
-
-// AutoFormRendererField
 export interface AutoFormFieldProps<S extends z.ZodObject> extends Pick<AutoFormProps<S>, 'schema'> {
-  field: AutoFormField
-  extraProps?: AnyObject
+    field: AutoFormField;
+    extraProps?: AnyObject;
 }
-
-// AutoFormRendererLayout
 export interface AutoFormRendererLayoutProps<S extends z.ZodObject> extends Pick<AutoFormProps<S>, 'schema'> {
-  field: AutoFormField
-  extraProps?: AnyObject
+    field: AutoFormField;
+    extraProps?: AnyObject;
 }
-
-// AutoFormRendererNested
 export interface AutoFormRendererNestedProps<S extends z.ZodObject> extends Pick<AutoFormProps<S>, 'schema'> {
-  field: AutoFormField
-  extraProps?: AnyObject
+    field: AutoFormField;
+    extraProps?: AnyObject;
 }

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

@@ -1,55 +1,43 @@
-import type { ButtonProps, PopoverProps, ColorPickerProps, PopoverEmits, CalendarProps, CalendarEmits, InputProps, InputEmits, InputSlots, TooltipProps, InputValue } from '@nuxt/ui'
-import type { OmitByKey } from '@movk/core'
-import type { ClassNameValue } from 'tailwind-merge'
-import type { DateFormatterOptions, useDateFormatter } from '../composables/useDateFormatter'
-
-// ColorChooser
+import type { ButtonProps, PopoverProps, ColorPickerProps, PopoverEmits, CalendarProps, CalendarEmits, InputProps, InputEmits, InputSlots, TooltipProps, InputValue } from '@nuxt/ui';
+import type { OmitByKey } from '@movk/core';
+import type { ClassNameValue } from 'tailwind-merge';
+import type { DateFormatterOptions, useDateFormatter } from '../composables/useDateFormatter.js';
 export interface ColorChooserProps<P extends 'click' | 'hover' = 'click'> extends /** @vue-ignore */ ColorPickerProps {
-  popoverProps?: PopoverProps<P>
-  buttonProps?: ButtonProps
+    popoverProps?: PopoverProps<P>;
+    buttonProps?: ButtonProps;
 }
-
-export type ColorChooserEmits = PopoverEmits
-
-// DatePicker
-export type LabelFormat = 'iso' | 'formatted' | 'date' | 'timestamp' | 'unix'
-export type ValueType<R extends boolean, M extends boolean> = CalendarProps<R, M>['modelValue']
-
+export type ColorChooserEmits = PopoverEmits;
+export type LabelFormat = 'iso' | 'formatted' | 'date' | 'timestamp' | 'unix';
+export type ValueType<R extends boolean, M extends boolean> = CalendarProps<R, M>['modelValue'];
 export interface DatePickerProps<R extends boolean, M extends boolean, P extends 'click' | 'hover' = 'click'> extends /** @vue-ignore */ OmitByKey<CalendarProps<R, M>, 'modelValue'>, DateFormatterOptions {
-  buttonProps?: ButtonProps
-  popoverProps?: PopoverProps<P>
-  labelFormat?: LabelFormat | ((formatter: ReturnType<typeof useDateFormatter>, modelValue: ValueType<R, M>) => string)
+    buttonProps?: ButtonProps;
+    popoverProps?: PopoverProps<P>;
+    labelFormat?: LabelFormat | ((formatter: ReturnType<typeof useDateFormatter>, modelValue: ValueType<R, M>) => string);
 }
-
-export type DatePickerEmits<R extends boolean, M extends boolean> = PopoverEmits & CalendarEmits<R, M>
-
-// Input components
+export type DatePickerEmits<R extends boolean, M extends boolean> = PopoverEmits & CalendarEmits<R, M>;
 export interface WithCharacterLimitProps<T extends InputValue = InputValue> extends /** @vue-ignore */ OmitByKey<InputProps<T>, 'modelValue'> {
-  maxLength?: number
-  counterClass?: ClassNameValue
+    maxLength?: number;
+    counterClass?: ClassNameValue;
 }
-export type WithCharacterLimitEmits<T extends InputValue = InputValue> = InputEmits<T>
-export type WithCharacterLimitSlots = OmitByKey<InputSlots, 'trailing'>
-
+export type WithCharacterLimitEmits<T extends InputValue = InputValue> = InputEmits<T>;
+export type WithCharacterLimitSlots = OmitByKey<InputSlots, 'trailing'>;
 export interface WithClearProps<T extends InputValue = InputValue> extends /** @vue-ignore */ OmitByKey<InputProps<T>, 'modelValue'> {
-  buttonProps?: ButtonProps
+    buttonProps?: ButtonProps;
 }
 export type WithClearEmits<T extends InputValue = InputValue> = InputEmits<T> & {
-  clear: []
-}
-export type WithClearSlots = OmitByKey<InputSlots, 'trailing'>
-
+    clear: [];
+};
+export type WithClearSlots = OmitByKey<InputSlots, 'trailing'>;
 export interface WithCopyProps<T extends InputValue = InputValue> extends /** @vue-ignore */ OmitByKey<InputProps<T>, 'modelValue'> {
-  buttonProps?: ButtonProps
-  tooltipProps?: TooltipProps
+    buttonProps?: ButtonProps;
+    tooltipProps?: TooltipProps;
 }
 export type WithCopyEmits<T extends InputValue = InputValue> = InputEmits<T> & {
-  copy: [value: string]
-}
-export type WithCopySlots = OmitByKey<InputSlots, 'trailing'>
-
+    copy: [value: string];
+};
+export type WithCopySlots = OmitByKey<InputSlots, 'trailing'>;
 export interface WithPasswordToggleProps<T extends InputValue = InputValue> extends /** @vue-ignore */ OmitByKey<InputProps<T>, 'type' | 'modelValue'> {
-  buttonProps?: ButtonProps
+    buttonProps?: ButtonProps;
 }
-export type WithPasswordToggleEmits<T extends InputValue = InputValue> = InputEmits<T>
-export type WithPasswordToggleSlots = OmitByKey<InputSlots, 'trailing'>
+export type WithPasswordToggleEmits<T extends InputValue = InputValue> = InputEmits<T>;
+export type WithPasswordToggleSlots = OmitByKey<InputSlots, 'trailing'>;

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

@@ -1,3 +1,4 @@
 export * from './auto-form.js';
 export * from './components.js';
 export * from './auto-form-renderer.js';
+export * from './api.js';

package/dist/runtime/types/index.js

@@ -1,3 +1,4 @@
 export * from "./auto-form.js";
-export * from "./components";
-export * from "./auto-form-renderer";
+export * from "./components.js";
+export * from "./auto-form-renderer.js";
+export * from "./api.js";