@svadmin/core 0.31.0 → 0.32.0

package/src/hook-utils.svelte.ts

@@ -3,33 +3,34 @@
 
 import { useQueryClient } from '@tanstack/svelte-query';
 import type { LiveProvider, LiveEvent, LiveMode } from './live.svelte';
-import { getAuthProvider } from './context.svelte';
+import { captureAdminContext } from './context.svelte';
+import type { AdminContextAccessor } from './context.svelte';
 import { notify } from './notification.svelte';
 
 // ─── Auth Error Delegate ────────────────────────────────────────
-// Delegate auth errors (401/403) to authProvider.onError() — refine pattern
+// Delegate auth errors to authProvider.onError() — refine pattern
 
-export async function checkError(error: unknown): Promise<void> {
+export async function checkError(
+  error: unknown,
+  adminContext: AdminContextAccessor = captureAdminContext(),
+): Promise<void> {
   try {
-    const authProvider = getAuthProvider({ optional: true });
+    const authProvider = adminContext.authProvider;
     if (authProvider?.onError) {
       const result = await authProvider.onError(error);
       if (!result) return;
       if (result.logout) {
-        try { await authProvider.logout?.(); } catch { /* logout failure should not block redirect */ }
-        const { navigate } = await import('./router');
-        navigate(result.redirectTo ?? '/login');
+        await authProvider.logout?.();
+        await adminContext.navigate(result.redirectTo ?? '/login');
       } else if (result.redirectTo) {
-        const { navigate } = await import('./router');
-        navigate(result.redirectTo);
+        await adminContext.navigate(result.redirectTo);
       }
       return;
     }
     if (error && typeof error === 'object' && 'statusCode' in error) {
       const status = (error as { statusCode: number }).statusCode;
-      if (status === 401 || status === 403) {
-        const { navigate } = await import('./router');
-        navigate('/login');
+      if (status === 401) {
+        await adminContext.navigate('/login');
       }
     }
   } catch { /* auth check failed silently */ }

package/src/hooks.svelte.ts

@@ -1,4 +1,3 @@
-/* eslint-disable svelte/prefer-svelte-reactivity */
 // @svadmin/core — Core Data and Hook APIs (Modularized for v0.2.29+)
 
 // ─── Re-exports from modular hook files ─────────────────────────────
@@ -24,7 +23,7 @@ export type { OvertimeResult, OvertimeOptions, NotificationConfig } from './hook
 
 import { createQuery, createInfiniteQuery, createMutation, useQueryClient } from '@tanstack/svelte-query';
 import { getAdminOptions } from './options.svelte';
-import { getDataProviderForResource, getDataProvider, getLiveProvider } from './context.svelte';
+import { captureAdminContext } from './context.svelte';
 import { useParsed } from './useParsed.svelte';
 import { createOvertimeTracker, createLiveSubscription, fireSuccessNotification, fireErrorNotification, checkError } from './hook-utils.svelte';
 import { invalidateByScopes, publishLiveEvent } from './mutation-hooks.svelte';
@@ -51,12 +50,13 @@ export interface UseInfiniteListOptions<_TData extends BaseRecord = BaseRecord,
 }
 
 export function useInfiniteList<TData extends BaseRecord = BaseRecord, TError = HttpError>(options: UseInfiniteListOptions<TData, TError> = {}) {
+  const adminContext = captureAdminContext();
   const parsed = useParsed();
   const adminOptions = getAdminOptions();
 
   const query = createInfiniteQuery<{ data: TData[]; total: number }, TError>(() => {
     const resource = options.resource ?? parsed.resource ?? '';
-    const provider = getDataProviderForResource(resource, options.dataProviderName);
+    const provider = adminContext.getDataProviderForResource(resource, options.dataProviderName);
     return {
     queryKey: [options.dataProviderName, resource, 'infiniteList', options.pagination?.pageSize, options.sorters, options.filters, options.meta],
     queryFn: async ({ pageParam = 1 }) => {
@@ -84,7 +84,7 @@ export function useInfiniteList<TData extends BaseRecord = BaseRecord, TError =
 
   createLiveSubscription((): LiveSubscriptionParams => ({
     resource: options.resource ?? parsed.resource ?? '',
-    liveProvider: getLiveProvider(),
+    liveProvider: adminContext.liveProvider,
     liveMode: options.liveMode ?? adminOptions.liveMode,
     onLiveEvent: (e: LiveEvent) => {
       options.onLiveEvent?.(e);
@@ -102,7 +102,7 @@ export function useInfiniteList<TData extends BaseRecord = BaseRecord, TError =
       fireSuccessNotification(options.successNotification, '', query.data, undefined, options.resource ?? parsed.resource ?? '');
     } else if (query.isError && query.errorUpdatedAt > lastErrorAt) {
       lastErrorAt = query.errorUpdatedAt;
-      checkError(query.error);
+      checkError(query.error, adminContext);
       fireErrorNotification(options.errorNotification, 'Fetch failed', query.error, options.resource ?? parsed.resource ?? '');
     }
   });
@@ -133,6 +133,7 @@ export interface UseSelectOptions<TData extends BaseRecord = BaseRecord, _TOptio
 }
 
 export function useSelect<TData extends BaseRecord = BaseRecord, TOption = { label: string; value: string | number }>(options: UseSelectOptions<TData, TOption>) {
+  const adminContext = captureAdminContext();
   const { resource, optionLabel = 'title', optionValue = 'id', sorters, filters, pagination, meta, dataProviderName, onSearch, debounce: debounceMs = 300 } = options;
   const adminOptions = getAdminOptions();
 
@@ -149,7 +150,7 @@ export function useSelect<TData extends BaseRecord = BaseRecord, TOption = { lab
   const effectivePageSize = options.fetchSize ?? pagination?.pageSize ?? 999;
 
   const query = createQuery<{ data: TData[]; total: number }>(() => {
-    const provider = getDataProviderForResource(resource, dataProviderName);
+    const provider = adminContext.getDataProviderForResource(resource, dataProviderName);
     return {
     queryKey: [dataProviderName, resource, 'select', allFilters, sorters, pagination, meta],
     queryFn: () => provider.getList<TData>({ resource, sorters, filters: allFilters, pagination: { current: 1, pageSize: effectivePageSize }, meta }),
@@ -162,7 +163,7 @@ export function useSelect<TData extends BaseRecord = BaseRecord, TOption = { lab
   const defaultValueIds = options.defaultValue ?? [];
   const defaultValueQuery = defaultValueIds.length > 0
     ? createQuery<{ data: TData[] }>(() => {
-        const provider = getDataProviderForResource(resource, dataProviderName);
+        const provider = adminContext.getDataProviderForResource(resource, dataProviderName);
         return {
           queryKey: [dataProviderName, resource, 'select-defaults', defaultValueIds],
           queryFn: async () => {
@@ -205,7 +206,7 @@ export function useSelect<TData extends BaseRecord = BaseRecord, TOption = { lab
       fireSuccessNotification(options.successNotification, '', query.data, undefined, resource);
     } else if (query.isError && query.errorUpdatedAt > lastErrorAt) {
       lastErrorAt = query.errorUpdatedAt;
-      checkError(query.error);
+      checkError(query.error, adminContext);
       fireErrorNotification(options.errorNotification, 'Fetch failed', query.error, resource);
     }
   });
@@ -243,10 +244,11 @@ export interface UseCustomOptions<_TData = unknown, _TError = HttpError> {
 }
 
 export function useCustom<TData = unknown, TError = HttpError>(options: UseCustomOptions<TData, TError>) {
+  const adminContext = captureAdminContext();
   const adminOptions = getAdminOptions();
 
   const query = createQuery<{ data: TData }, TError>(() => {
-    const provider = getDataProvider(options.dataProviderName);
+    const provider = adminContext.getDataProvider(options.dataProviderName);
     return {
     queryKey: [options.dataProviderName, 'custom', options.url, options.method, options.config, options.meta],
     queryFn: async () => {
@@ -277,7 +279,7 @@ export function useCustom<TData = unknown, TError = HttpError>(options: UseCusto
       fireSuccessNotification(options.successNotification, '', query.data);
     } else if (query.isError && query.errorUpdatedAt > lastErrorAt) {
       lastErrorAt = query.errorUpdatedAt;
-      checkError(query.error);
+      checkError(query.error, adminContext);
       fireErrorNotification(options.errorNotification, 'Custom request failed', query.error, '');
     }
   });
@@ -288,11 +290,12 @@ export function useCustom<TData = unknown, TError = HttpError>(options: UseCusto
 // ─── useCustomMutation ──────────────────────────────────────────────
 
 export function useCustomMutation<TData = unknown, TError = HttpError, TVariables = unknown>(dataProviderName?: string) {
+  const adminContext = captureAdminContext();
   const queryClient = useQueryClient();
 
   const mutation = createMutation<{ data: TData }, TError, { url: string; method: 'get' | 'post' | 'put' | 'patch' | 'delete'; values?: TVariables; query?: Record<string, unknown>; headers?: Record<string, string>; sorters?: Sort[]; filters?: Filter[]; meta?: Record<string, unknown>; invalidates?: string[] | false; resource?: string }>(() => ({
     mutationFn: async (params) => {
-      const provider = getDataProvider(dataProviderName);
+      const provider = adminContext.getDataProvider(dataProviderName);
       if (!provider.custom) throw new Error('DataProvider does not support custom method');
       return provider.custom<TData>({ url: params.url, method: params.method, payload: params.values, query: params.query, headers: params.headers, sorters: params.sorters, filters: params.filters, meta: params.meta });
     },
@@ -302,7 +305,7 @@ export function useCustomMutation<TData = unknown, TError = HttpError, TVariable
       }
     },
     onError: (error) => {
-      checkError(error);
+      checkError(error, adminContext);
     },
   }));
 
@@ -312,6 +315,7 @@ export function useCustomMutation<TData = unknown, TError = HttpError, TVariable
 // ─── useCreateMany / useUpdateMany / useDeleteMany ──────────────────
 
 export function useCreateMany<TData extends BaseRecord = BaseRecord, TError = HttpError, TVariables = Record<string, unknown>>(options: { resource?: KnownResources; overtimeOptions?: OvertimeOptions } = {}) {
+  const adminContext = captureAdminContext();
   const parsed = useParsed();
   const resource = options.resource ?? parsed.resource ?? '';
   const adminOptions = getAdminOptions();
@@ -320,7 +324,7 @@ export function useCreateMany<TData extends BaseRecord = BaseRecord, TError = Ht
   const mutation = createMutation<{ data: TData[] }, TError, { resource?: KnownResources; variables: TVariables[]; meta?: Record<string, unknown>; dataProviderName?: string }>(() => ({
     mutationFn: async (params) => {
       const resName = params.resource ?? resource;
-      const provider = getDataProviderForResource(resName, params.dataProviderName);
+      const provider = adminContext.getDataProviderForResource(resName, params.dataProviderName);
       if (provider.createMany) return await provider.createMany<TData, TVariables>({ resource: resName, variables: params.variables, meta: params.meta });
       const results = await Promise.all(params.variables.map(v => provider.create<TData, TVariables>({ resource: resName, variables: v, meta: params.meta })));
       return { data: results.map(r => r.data) };
@@ -329,10 +333,10 @@ export function useCreateMany<TData extends BaseRecord = BaseRecord, TError = Ht
       const resName = params.resource ?? resource;
       fireSuccessNotification(undefined, 'Created successfully', data.data, params.variables, resName);
       audit({ action: 'create', resource: resName });
-      publishLiveEvent(resName, 'created');
+      publishLiveEvent(resName, 'created', undefined, adminContext);
     },
     onError: (error, params) => {
-      checkError(error);
+      checkError(error, adminContext);
       fireErrorNotification(undefined, 'Create many failed', error, params.resource ?? resource);
     },
     onSettled: (_d, _e, params) => {
@@ -345,6 +349,7 @@ export function useCreateMany<TData extends BaseRecord = BaseRecord, TError = Ht
 }
 
 export function useUpdateMany<TData extends BaseRecord = BaseRecord, TError = HttpError, TVariables = Record<string, unknown>>(options: { resource?: KnownResources; overtimeOptions?: OvertimeOptions } = {}) {
+  const adminContext = captureAdminContext();
   const parsed = useParsed();
   const resource = options.resource ?? parsed.resource ?? '';
   const adminOptions = getAdminOptions();
@@ -353,7 +358,7 @@ export function useUpdateMany<TData extends BaseRecord = BaseRecord, TError = Ht
   const mutation = createMutation<{ data: TData[] }, TError, { resource?: KnownResources; ids: (string | number)[]; variables: TVariables; meta?: Record<string, unknown>; dataProviderName?: string }>(() => ({
     mutationFn: async (params) => {
       const resName = params.resource ?? resource;
-      const provider = getDataProviderForResource(resName, params.dataProviderName);
+      const provider = adminContext.getDataProviderForResource(resName, params.dataProviderName);
       if (provider.updateMany) return await provider.updateMany<TData, TVariables>({ resource: resName, ids: params.ids, variables: params.variables, meta: params.meta });
       const results = await Promise.all(params.ids.map(id => provider.update<TData, TVariables>({ resource: resName, id, variables: params.variables, meta: params.meta })));
       return { data: results.map(r => r.data) };
@@ -362,10 +367,10 @@ export function useUpdateMany<TData extends BaseRecord = BaseRecord, TError = Ht
       const resName = params.resource ?? resource;
       fireSuccessNotification(undefined, 'Updated successfully', data.data, params.variables, resName);
       audit({ action: 'update', resource: resName });
-      publishLiveEvent(resName, 'updated', params.ids);
+      publishLiveEvent(resName, 'updated', params.ids, adminContext);
     },
     onError: (error, params) => {
-      checkError(error);
+      checkError(error, adminContext);
       fireErrorNotification(undefined, 'Update many failed', error, params.resource ?? resource);
     },
     onSettled: (_d, _e, params) => {
@@ -381,6 +386,7 @@ export function useUpdateMany<TData extends BaseRecord = BaseRecord, TError = Ht
 }
 
 export function useDeleteMany<TData extends BaseRecord = BaseRecord, TError = HttpError>(options: { resource?: KnownResources; overtimeOptions?: OvertimeOptions } = {}) {
+  const adminContext = captureAdminContext();
   const parsed = useParsed();
   const resource = options.resource ?? parsed.resource ?? '';
   const adminOptions = getAdminOptions();
@@ -389,7 +395,7 @@ export function useDeleteMany<TData extends BaseRecord = BaseRecord, TError = Ht
   const mutation = createMutation<{ data: TData[] }, TError, { resource?: KnownResources; ids: (string | number)[]; meta?: Record<string, unknown>; dataProviderName?: string }>(() => ({
     mutationFn: async (params) => {
       const resName = params.resource ?? resource;
-      const provider = getDataProviderForResource(resName, params.dataProviderName);
+      const provider = adminContext.getDataProviderForResource(resName, params.dataProviderName);
       if (provider.deleteMany) return await provider.deleteMany<TData>({ resource: resName, ids: params.ids, meta: params.meta });
       const results = await Promise.all(params.ids.map(id => provider.deleteOne<TData>({ resource: resName, id, meta: params.meta })));
       return { data: results.map(r => r.data) };
@@ -398,10 +404,10 @@ export function useDeleteMany<TData extends BaseRecord = BaseRecord, TError = Ht
       const resName = params.resource ?? resource;
       fireSuccessNotification(undefined, 'Deleted successfully', data.data, undefined, resName);
       audit({ action: 'delete', resource: resName });
-      publishLiveEvent(resName, 'deleted', params.ids);
+      publishLiveEvent(resName, 'deleted', params.ids, adminContext);
     },
     onError: (error, params) => {
-      checkError(error);
+      checkError(error, adminContext);
       fireErrorNotification(undefined, 'Delete many failed', error, params.resource ?? resource);
     },
     onSettled: (_d, _e, params) => {
@@ -454,7 +460,8 @@ export function useOvertime(options?: OvertimeOptions) {
 // ─── useDataProvider ────────────────────────────────────────────────
 
 export function useDataProvider(): (dataProviderName?: string) => DataProvider {
-  return (name?: string) => getDataProvider(name);
+  const adminContext = captureAdminContext();
+  return (name?: string) => adminContext.getDataProvider(name);
 }
 
 // ─── useThemedLayoutContext ─────────────────────────────────────────
@@ -470,4 +477,3 @@ export function useThemedLayoutContext() {
     toggleSidebar() { _sidebarCollapsed = !_sidebarCollapsed; },
   };
 }
-

package/src/http.ts

@@ -1,11 +1,13 @@
 /**
- * HTTP fetch 工具 — 带 CSRF 防护、401 自动跳转、403 拦截的 fetch wrapper。
+ * HTTP fetch 工具 — 带 CSRF 防护、401 自动跳转和结构化错误语义。
  */
 
+import { HttpError, type ValidationErrors } from './types';
+
 export interface FetchWithInterceptorOptions {
   /** 401 时跳转的登录页路径 */
   loginPath?: string;
-  /** 403 时抛出的错误消息 */
+  /** 403 且服务端未返回消息时使用的错误消息 */
   forbiddenMessage?: string;
   /** 是否自动添加 X-Requested-With header (CSRF 防护) */
   csrfProtection?: boolean;
@@ -21,32 +23,103 @@ const DEFAULT_OPTIONS: Required<Omit<FetchWithInterceptorOptions, 'fetchImpl' |
   fetchImpl: FetchWithInterceptor;
   onUnauthorized: (loginPath: string, returnTo: string) => void;
 } = {
-  loginPath: "/auth/login",
-  forbiddenMessage: "Forbidden: 该操作已被安全策略拒绝",
+  loginPath: '/auth/login',
+  forbiddenMessage: 'Forbidden: 该操作已被安全策略拒绝',
   csrfProtection: true,
   get fetchImpl() {
-    if (typeof globalThis !== "undefined" && typeof globalThis.fetch === "function") {
+    if (typeof globalThis !== 'undefined' && typeof globalThis.fetch === 'function') {
       return (url: string, init?: RequestInit) => globalThis.fetch(url, init);
     }
     return async () => {
-      throw new Error("No fetch implementation found. Pass fetchImpl in options.");
+      throw new Error('No fetch implementation found. Pass fetchImpl in options.');
     };
   },
   onUnauthorized: (loginPath, returnTo) => {
-    if (typeof window !== "undefined") {
+    if (typeof window !== 'undefined') {
       window.location.href = `${loginPath}?returnTo=${returnTo}`;
     }
   },
 };
 
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return typeof value === 'object' && value !== null
+    ? value as Record<string, unknown>
+    : null;
+}
+
+function asStructuredHttpError(error: unknown): HttpError | null {
+  const record = asRecord(error);
+  if (!record || typeof record.statusCode !== 'number') return null;
+  const message = typeof record.message === 'string' ? record.message : 'HTTP request failed';
+  const errors = asValidationErrors(record.errors);
+  return new HttpError(message, record.statusCode, errors, {
+    code: typeof record.code === 'string' ? record.code : undefined,
+    details: record.details,
+    body: record.body,
+    cause: error,
+  });
+}
+
+function firstString(...values: unknown[]): string | undefined {
+  return values.find((value): value is string => typeof value === 'string');
+}
+
+function asValidationErrors(value: unknown): ValidationErrors | undefined {
+  const record = asRecord(value);
+  if (!record) return undefined;
+
+  const valid = Object.values(record).every((entry) => (
+    typeof entry === 'string'
+    || (Array.isArray(entry) && entry.every((item) => typeof item === 'string'))
+  ));
+  return valid ? record as ValidationErrors : undefined;
+}
+
+async function readErrorBody(response: Response): Promise<unknown> {
+  const text = await response.text();
+  if (!text) return undefined;
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return text;
+  }
+}
+
+async function createResponseError(
+  response: Response,
+  forbiddenMessage: string,
+): Promise<HttpError> {
+  const body = await readErrorBody(response);
+  const record = asRecord(body);
+  const nestedError = asRecord(record?.error);
+  const code = response.headers.get('X-Svadmin-Auth-Retry') === 'exhausted'
+    ? 'auth_retry_exhausted'
+    : firstString(
+      record?.code,
+      record?.error_code,
+      nestedError?.code,
+      nestedError?.error_code,
+      record?.error,
+    );
+  const details = record?.details ?? nestedError?.details;
+  const message = firstString(
+    record?.message,
+    nestedError?.message,
+    record?.error_description,
+    nestedError?.error_description,
+    body,
+  ) ?? (response.status === 401 ? 'Unauthorized' : forbiddenMessage);
+
+  return new HttpError(
+    message,
+    response.status,
+    asValidationErrors(record?.errors ?? nestedError?.errors),
+    { code, details, body },
+  );
+}
+
 /**
- * 带拦截器的 fetch — 自动注入 CSRF header，401 跳转登录，403 抛异常。
- *
- * @example
- * ```ts
- * const fetcher = createFetchWithInterceptor({ loginPath: '/login' });
- * const res = await fetcher('/api/users');
- * ```
+ * 带拦截器的 fetch。Core 只保留错误语义；认证刷新和请求重放由认证提供方处理。
  */
 export function createFetchWithInterceptor(
   options: FetchWithInterceptorOptions = {},
@@ -55,34 +128,42 @@ export function createFetchWithInterceptor(
 
   return async (url: string, init: RequestInit = {}): Promise<Response> => {
     const headers = new Headers(init.headers || {});
-
     if (
-      opts.csrfProtection &&
-      init.method &&
-      ["POST", "PUT", "DELETE", "PATCH"].includes(init.method.toUpperCase())
+      opts.csrfProtection
+      && init.method
+      && ['POST', 'PUT', 'DELETE', 'PATCH'].includes(init.method.toUpperCase())
     ) {
-      headers.set("X-Requested-With", "XMLHttpRequest");
+      headers.set('X-Requested-With', 'XMLHttpRequest');
     }
 
-    const res = await opts.fetchImpl(url, { ...init, headers });
+    let response: Response;
+    try {
+      response = await opts.fetchImpl(url, { ...init, headers });
+    } catch (error) {
+      if (error instanceof HttpError) throw error;
+      const structuredError = asStructuredHttpError(error);
+      if (structuredError) throw structuredError;
+      throw error;
+    }
 
-    if (!res.ok) {
-      if (res.status === 401) {
-        const returnTo = typeof window !== "undefined"
-          ? encodeURIComponent(window.location.pathname)
-          : "";
+    if (response.ok || (response.status !== 401 && response.status !== 403)) {
+      return response;
+    }
+
+    const httpError = await createResponseError(response, opts.forbiddenMessage);
+    if (response.status === 401) {
+      const returnTo = typeof window !== 'undefined'
+        ? encodeURIComponent(window.location.pathname)
+        : '';
+      try {
         opts.onUnauthorized(opts.loginPath, returnTo);
-        throw new Error("Unauthorized");
-      }
-      if (res.status === 403) {
-        throw new Error(opts.forbiddenMessage);
+      } catch {
+        // 重定向适配器失败不能覆盖服务端的结构化 401 错误。
       }
     }
-    return res;
+    throw httpError;
   };
 }
 
-/**
- * 便捷全局实例 — 使用默认配置。
- */
+/** 便捷全局实例 — 使用默认配置。 */
 export const fetchWithInterceptor = createFetchWithInterceptor();