@svadmin/core 0.24.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svadmin/core",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "author": "zuohuadong",
   "repository": {
     "type": "git",

package/src/context.svelte.ts

@@ -1,7 +1,7 @@
 // Svelte 5 Context — module-level $state singletons (no setContext/getContext required)
 // This removes the constraint that hooks must be called at component init time.
 
-import type { DataProvider, AuthProvider, ResourceDefinition } from './types';
+import type { DataProvider, AuthProvider, ResourceDefinition, TaskProvider } from './types';
 import type { RouterProvider } from './router-provider';
 import { resetNotificationProvider } from './notification.svelte';
 import { resetAuditLogProvider } from './audit';
@@ -136,6 +136,23 @@ export function getLiveProvider(): import('./live.svelte').LiveProvider | undefi
   return liveProviderState;
 }
 
+// ─── Task Provider ──────────────────────────────────────────────
+
+let taskProviderState = $state<TaskProvider | undefined>(undefined);
+
+export function setTaskProvider(provider: TaskProvider | undefined): void {
+  taskProviderState = provider;
+}
+
+export function getTaskProvider(): TaskProvider;
+export function getTaskProvider(options: { optional: true }): TaskProvider | undefined;
+export function getTaskProvider(options?: { optional?: boolean }): TaskProvider | undefined {
+  if (!taskProviderState && !options?.optional) {
+    throw new Error('TaskProvider not found. Did you call setTaskProvider in App.svelte?');
+  }
+  return taskProviderState;
+}
+
 // ─── Reset — for testing / HMR ─────────────────────────────────
 
 export function resetContext(): void {
@@ -144,6 +161,7 @@ export function resetContext(): void {
   resources = [];
   routerProvider = undefined;
   liveProviderState = undefined;
+  taskProviderState = undefined;
   resetNotificationProvider();
   resetAuditLogProvider();
   resetAccessControlProvider();

package/src/i18n.svelte.ts

@@ -2,7 +2,7 @@
 
 
 
-let locales = $state<Record<string, Record<string, string>>>({
+const baseLocales: Record<string, Record<string, string>> = {
   'zh-CN': {
     'common.list': '列表',
     'common.prev': '上一页',
@@ -253,6 +253,62 @@ let locales = $state<Record<string, Record<string, string>>>({
     'profile.currentPassword': '当前密码',
     'profile.passwordChanged': '密码已修改',
     'profile.updatePassword': '更新密码',
+    // Tasks
+    'task.drawerTitle': '任务中心',
+    'task.listTitle': '任务列表',
+    'task.dlqTitle': '死信队列',
+    'task.tabTasks': '任务',
+    'task.tabDlq': '死信',
+    'task.count': '{count} 个任务',
+    'task.activeCount': '{count} 个进行中',
+    'task.lastQueuedAt': '最近排队时间 {time}',
+    'task.loadingList': '正在加载任务...',
+    'task.loadingDetail': '正在加载任务详情...',
+    'task.noTasks': '暂无任务',
+    'task.noDlq': '暂无死信任务',
+    'task.noSelection': '未选择任务',
+    'task.selectHint': '从左侧选择一个任务查看详情',
+    'task.taskColumn': '任务',
+    'task.statusColumn': '状态',
+    'task.updatedColumn': '更新时间',
+    'task.actionsColumn': '操作',
+    'task.detailsAction': '详情',
+    'task.detailsTitle': '任务详情',
+    'task.detailsSummary': '任务详情',
+    'task.createdLabel': '创建时间',
+    'task.updatedLabel': '更新时间',
+    'task.messageLabel': '消息',
+    'task.errorLabel': '错误',
+    'task.payloadLabel': '负载',
+    'task.searchPlaceholder': '按名称、ID、状态或消息筛选任务...',
+    'task.statusFilterLabel': '状态筛选',
+    'task.statusAll': '全部状态',
+    'task.autoRefreshLabel': '自动刷新',
+    'task.refreshOff': '关闭',
+    'task.refresh5s': '每 5 秒',
+    'task.refresh15s': '每 15 秒',
+    'task.refresh30s': '每 30 秒',
+    'task.submitTitle': '提交任务',
+    'task.submitDescription': '直接从任务中心提交一个新任务并跟踪执行状态。',
+    'task.taskNameLabel': '任务名称',
+    'task.idempotencyKeyLabel': '幂等键',
+    'task.bodyLabel': '任务负载（JSON）',
+    'task.bodyPlaceholder': '{\n  "prompt": "生成一张海报"\n}',
+    'task.submitAction': '提交任务',
+    'task.invalidJson': '任务负载必须是合法 JSON',
+    'task.submitSuccess': '任务提交成功',
+    'task.submitFailed': '任务提交失败',
+    'task.fetchFailed': '加载任务失败',
+    'task.fetchListFailed': '加载任务列表失败',
+    'task.status.pending': '等待中',
+    'task.status.queued': '已排队',
+    'task.status.running': '执行中',
+    'task.status.processing': '处理中',
+    'task.status.completed': '已完成',
+    'task.status.success': '成功',
+    'task.status.done': '已完成',
+    'task.status.failed': '失败',
+    'task.status.error': '错误',
   },
   'en': {
     'common.list': 'List',
@@ -504,10 +560,67 @@ let locales = $state<Record<string, Record<string, string>>>({
     'profile.currentPassword': 'Current Password',
     'profile.passwordChanged': 'Password updated successfully',
     'profile.updatePassword': 'Update Password',
+    // Tasks
+    'task.drawerTitle': 'Task Center',
+    'task.listTitle': 'Tasks',
+    'task.dlqTitle': 'Dead Letter Queue',
+    'task.tabTasks': 'Tasks',
+    'task.tabDlq': 'DLQ',
+    'task.count': '{count} task(s)',
+    'task.activeCount': '{count} active',
+    'task.lastQueuedAt': 'Last queued at {time}',
+    'task.loadingList': 'Loading tasks...',
+    'task.loadingDetail': 'Loading task...',
+    'task.noTasks': 'No tasks found',
+    'task.noDlq': 'No dead-letter tasks',
+    'task.noSelection': 'No task selected',
+    'task.selectHint': 'Select a task from the list to inspect details',
+    'task.taskColumn': 'Task',
+    'task.statusColumn': 'Status',
+    'task.updatedColumn': 'Updated',
+    'task.actionsColumn': 'Actions',
+    'task.detailsAction': 'Details',
+    'task.detailsTitle': 'Task Details',
+    'task.detailsSummary': 'Task details',
+    'task.createdLabel': 'Created',
+    'task.updatedLabel': 'Updated',
+    'task.messageLabel': 'Message',
+    'task.errorLabel': 'Error',
+    'task.payloadLabel': 'Payload',
+    'task.searchPlaceholder': 'Filter tasks by name, ID, status, or message...',
+    'task.statusFilterLabel': 'Status filter',
+    'task.statusAll': 'All statuses',
+    'task.autoRefreshLabel': 'Auto refresh',
+    'task.refreshOff': 'Off',
+    'task.refresh5s': 'Every 5s',
+    'task.refresh15s': 'Every 15s',
+    'task.refresh30s': 'Every 30s',
+    'task.submitTitle': 'Submit Task',
+    'task.submitDescription': 'Submit a new task from the drawer and follow it through completion.',
+    'task.taskNameLabel': 'Task name',
+    'task.idempotencyKeyLabel': 'Idempotency key',
+    'task.bodyLabel': 'Task payload (JSON)',
+    'task.bodyPlaceholder': '{\n  "prompt": "Generate a poster"\n}',
+    'task.submitAction': 'Submit Task',
+    'task.invalidJson': 'Task payload must be valid JSON',
+    'task.submitSuccess': 'Task submitted successfully',
+    'task.submitFailed': 'Task submission failed',
+    'task.fetchFailed': 'Fetch task failed',
+    'task.fetchListFailed': 'Fetch tasks failed',
+    'task.status.pending': 'Pending',
+    'task.status.queued': 'Queued',
+    'task.status.running': 'Running',
+    'task.status.processing': 'Processing',
+    'task.status.completed': 'Completed',
+    'task.status.success': 'Success',
+    'task.status.done': 'Done',
+    'task.status.failed': 'Failed',
+    'task.status.error': 'Error',
   },
-});
+};
 
-const initialLocales = locales;
+let locales = $state(structuredClone(baseLocales));
+const initialLocales = structuredClone(baseLocales);
 
 /** Detect best locale from browser language */
 function detectLocale(): string {

package/src/index.ts

@@ -6,6 +6,7 @@ export {
   setResources, getResources, getResource,
   setRouterProvider, getRouterProvider,
   setLiveProvider, getLiveProvider,
+  setTaskProvider, getTaskProvider,
   resetContext,
 } from './context.svelte';
 export type { DataProviderInput } from './context.svelte';
@@ -87,6 +88,12 @@ export {
   useOnError, usePermissions,
   getLogoutVersion, resetLogoutVersion,
 } from './auth-hooks.svelte';
+export {
+  useSubmitTask,
+  useTask,
+  useTaskList,
+  useTaskSubscription,
+} from './task-hooks.svelte';
 export { useParsed, resetGlobalPath, syncGlobalPath } from './useParsed.svelte';
 export * from './useStepsForm.svelte';
 export { createHashRouterProvider, createHistoryRouterProvider } from './router-provider';
@@ -110,3 +117,11 @@ export type { TableStateOptions } from './table-state.svelte';
 export type { UseInfiniteListOptions } from './hooks.svelte';
 export type { UseSelectOptions } from './hooks.svelte';
 export type { UseFormReturn } from './form-hooks.svelte';
+export type {
+  TaskProvider,
+  TaskRecord,
+  SubmitTaskOptions,
+  TaskHandle,
+  TaskListResult,
+  TaskSubscription,
+} from './types';

package/src/task-hooks.svelte.ts

@@ -0,0 +1,240 @@
+import { createMutation, createQuery, useQueryClient } from '@tanstack/svelte-query';
+import { getAdminOptions } from './options.svelte';
+import { getTaskProvider } from './context.svelte';
+import { checkError, createOvertimeTracker, fireErrorNotification, fireSuccessNotification } from './hook-utils.svelte';
+import type { NotificationConfig, OvertimeOptions } from './hook-utils.svelte';
+import { t } from './i18n.svelte';
+import type {
+  HttpError,
+  SubmitTaskOptions,
+  TaskHandle,
+  TaskListResult,
+  TaskProvider,
+  TaskRecord,
+} from './types';
+
+function normalizeTaskProvider<TTask extends TaskRecord = TaskRecord>(
+  provider?: TaskProvider<TTask>,
+): TaskProvider<TTask> {
+  return (provider ?? getTaskProvider({ optional: true }) ?? getTaskProvider()) as TaskProvider<TTask>;
+}
+
+export interface UseSubmitTaskOptions {
+  mutationOptions?: {
+    onSuccess?: (data: unknown, variables: unknown, context: unknown) => void;
+    onError?: (error: unknown, variables: unknown, context: unknown) => void;
+  };
+  overtimeOptions?: OvertimeOptions;
+}
+
+export interface UseSubmitTaskMutateParams<TTask extends TaskRecord = TaskRecord> {
+  taskName: string;
+  options?: SubmitTaskOptions;
+  taskProvider?: TaskProvider<TTask>;
+  successNotification?: NotificationConfig;
+  errorNotification?: NotificationConfig;
+}
+
+export function useSubmitTask<
+  TTask extends TaskRecord = TaskRecord,
+  TError = HttpError,
+>(options: UseSubmitTaskOptions = {}) {
+  const adminOptions = getAdminOptions();
+  const queryClient = useQueryClient();
+  const overtime = createOvertimeTracker(() => mutation.isPending, options.overtimeOptions ?? adminOptions.overtime);
+
+  const mutation = createMutation<TaskHandle<TTask>, TError, UseSubmitTaskMutateParams<TTask>>(() => ({
+    mutationFn: async (params) => {
+      const provider = normalizeTaskProvider<TTask>(params.taskProvider);
+      return provider.submit(params.taskName, params.options);
+    },
+    onSuccess: (data, params, context) => {
+      fireSuccessNotification(
+        params.successNotification,
+        t('task.submitSuccess'),
+        data,
+        params.options,
+        params.taskName,
+      );
+      void queryClient.invalidateQueries({ queryKey: ['taskList'] });
+      options.mutationOptions?.onSuccess?.(data, params, context);
+    },
+    onError: (error, params, context) => {
+      checkError(error);
+      fireErrorNotification(
+        params.errorNotification,
+        t('task.submitFailed'),
+        error,
+        params.taskName,
+      );
+      options.mutationOptions?.onError?.(error, params, context);
+    },
+  }));
+
+  return { mutation, get overtime() { return overtime; } };
+}
+
+export interface UseTaskOptions<TTask extends TaskRecord = TaskRecord, TError = HttpError> {
+  taskId?: string;
+  taskProvider?: TaskProvider<TTask>;
+  queryOptions?: {
+    enabled?: boolean;
+    staleTime?: number;
+    gcTime?: number;
+    refetchOnWindowFocus?: boolean;
+    refetchInterval?: number | false;
+    refetchIntervalInBackground?: boolean;
+  };
+  successNotification?: NotificationConfig;
+  errorNotification?: NotificationConfig;
+  overtimeOptions?: OvertimeOptions;
+}
+
+export function useTask<TTask extends TaskRecord = TaskRecord, TError = HttpError>(
+  options: UseTaskOptions<TTask, TError> = {},
+) {
+  const adminOptions = getAdminOptions();
+
+  const query = createQuery<TTask, TError>(() => {
+    const provider = normalizeTaskProvider<TTask>(options.taskProvider);
+    const queryOptions = options.queryOptions;
+    return {
+      queryKey: ['task', options.taskId],
+      queryFn: async () => {
+        if (!options.taskId) throw new Error('useTask requires a taskId');
+        return provider.get(options.taskId);
+      },
+      enabled: (queryOptions?.enabled ?? true) && !!options.taskId,
+      staleTime: queryOptions?.staleTime ?? adminOptions.reactQuery?.staleTime,
+      gcTime: queryOptions?.gcTime ?? adminOptions.reactQuery?.gcTime,
+      refetchOnWindowFocus: queryOptions?.refetchOnWindowFocus ?? adminOptions.reactQuery?.refetchOnWindowFocus,
+      refetchInterval: queryOptions?.refetchInterval,
+      refetchIntervalInBackground: queryOptions?.refetchIntervalInBackground,
+    };
+  });
+
+  const overtime = createOvertimeTracker(() => query.isLoading, options.overtimeOptions ?? adminOptions.overtime);
+
+  let lastSuccessAt = 0;
+  let lastErrorAt = 0;
+  $effect(() => {
+    if (query.isSuccess && query.dataUpdatedAt > lastSuccessAt) {
+      lastSuccessAt = query.dataUpdatedAt;
+      if (options.successNotification) {
+        fireSuccessNotification(options.successNotification, '', query.data, undefined, options.taskId);
+      }
+    } else if (query.isError && query.errorUpdatedAt > lastErrorAt) {
+      lastErrorAt = query.errorUpdatedAt;
+      checkError(query.error);
+      fireErrorNotification(options.errorNotification, t('task.fetchFailed'), query.error, options.taskId);
+    }
+  });
+
+  return new Proxy(query, {
+    get(target, prop) {
+      if (prop === 'overtime') return overtime;
+      return target[prop as keyof typeof target];
+    },
+  }) as typeof query & { overtime: typeof overtime };
+}
+
+export interface UseTaskListOptions<TTask extends TaskRecord = TaskRecord, TError = HttpError> {
+  params?: Record<string, unknown>;
+  dlq?: boolean;
+  taskProvider?: TaskProvider<TTask>;
+  queryOptions?: {
+    enabled?: boolean;
+    staleTime?: number;
+    gcTime?: number;
+    refetchOnWindowFocus?: boolean;
+    refetchInterval?: number | false;
+    refetchIntervalInBackground?: boolean;
+  };
+  successNotification?: NotificationConfig;
+  errorNotification?: NotificationConfig;
+  overtimeOptions?: OvertimeOptions;
+}
+
+export function useTaskList<TTask extends TaskRecord = TaskRecord, TError = HttpError>(
+  options: UseTaskListOptions<TTask, TError> = {},
+) {
+  const adminOptions = getAdminOptions();
+
+  const query = createQuery<TaskListResult<TTask>, TError>(() => {
+    const provider = normalizeTaskProvider<TTask>(options.taskProvider);
+    const queryOptions = options.queryOptions;
+    return {
+      queryKey: ['taskList', options.dlq ? 'dlq' : 'default', options.params],
+      queryFn: async () => {
+        if (options.dlq) {
+          if (!provider.listDlq) throw new Error('TaskProvider does not implement listDlq');
+          return provider.listDlq(options.params);
+        }
+        if (!provider.list) throw new Error('TaskProvider does not implement list');
+        return provider.list(options.params);
+      },
+      enabled: queryOptions?.enabled ?? true,
+      staleTime: queryOptions?.staleTime ?? adminOptions.reactQuery?.staleTime,
+      gcTime: queryOptions?.gcTime ?? adminOptions.reactQuery?.gcTime,
+      refetchOnWindowFocus: queryOptions?.refetchOnWindowFocus ?? adminOptions.reactQuery?.refetchOnWindowFocus,
+      refetchInterval: queryOptions?.refetchInterval,
+      refetchIntervalInBackground: queryOptions?.refetchIntervalInBackground,
+    };
+  });
+
+  const overtime = createOvertimeTracker(() => query.isLoading, options.overtimeOptions ?? adminOptions.overtime);
+
+  let lastSuccessAt = 0;
+  let lastErrorAt = 0;
+  $effect(() => {
+    if (query.isSuccess && query.dataUpdatedAt > lastSuccessAt) {
+      lastSuccessAt = query.dataUpdatedAt;
+      if (options.successNotification) {
+        fireSuccessNotification(options.successNotification, '', query.data, options.params, options.dlq ? 'taskDlq' : 'tasks');
+      }
+    } else if (query.isError && query.errorUpdatedAt > lastErrorAt) {
+      lastErrorAt = query.errorUpdatedAt;
+      checkError(query.error);
+      fireErrorNotification(options.errorNotification, t('task.fetchListFailed'), query.error, options.dlq ? 'taskDlq' : 'tasks');
+    }
+  });
+
+  return new Proxy(query, {
+    get(target, prop) {
+      if (prop === 'overtime') return overtime;
+      return target[prop as keyof typeof target];
+    },
+  }) as typeof query & { overtime: typeof overtime };
+}
+
+export interface UseTaskSubscriptionOptions<TTask extends TaskRecord = TaskRecord> {
+  taskId: string;
+  taskProvider?: TaskProvider<TTask>;
+  enabled?: boolean;
+  onTask: (task: TTask) => void;
+}
+
+export function useTaskSubscription<TTask extends TaskRecord = TaskRecord>(
+  options: UseTaskSubscriptionOptions<TTask>,
+): void {
+  $effect(() => {
+    const enabled = options.enabled ?? true;
+    if (!enabled) return;
+
+    const provider = normalizeTaskProvider<TTask>(options.taskProvider);
+    if (!provider.subscribe) {
+      throw new Error('TaskProvider does not implement subscribe');
+    }
+
+    const subscription = provider.subscribe(options.taskId, options.onTask);
+    if (!subscription) return;
+
+    if (typeof subscription === 'function') {
+      return subscription;
+    }
+
+    if (typeof subscription.unsubscribe === 'function') {
+      return () => subscription.unsubscribe();
+    }
+  });
+}

package/src/task-hooks.test.svelte.ts

@@ -0,0 +1,129 @@
+import { describe, it, expect, vi } from 'vitest';
+import { flushSync } from 'svelte';
+import { QueryClient } from '@tanstack/svelte-query';
+import { useSubmitTask, useTask, useTaskList, useTaskSubscription } from './task-hooks.svelte';
+
+const mockTaskProvider = {
+  submit: vi.fn(async () => ({
+    id: 'task-1',
+    wait: async () => ({ id: 'task-1', status: 'done' }),
+  })),
+  get: vi.fn(async (taskId: string) => ({ id: taskId, status: 'running' })),
+  list: vi.fn(async () => ({ data: [{ id: 'task-1', status: 'queued' }], total: 1 })),
+  listDlq: vi.fn(async () => ({ data: [{ id: 'task-2', status: 'failed' }], total: 1 })),
+  subscribe: vi.fn((_taskId: string, callback: (task: { id: string; status: string }) => void) => {
+    callback({ id: 'task-1', status: 'running' });
+    return () => {};
+  }),
+};
+
+vi.mock('./context.svelte', () => ({
+  getTaskProvider: () => mockTaskProvider,
+  getAuthProvider: () => null,
+}));
+
+vi.mock('./notification.svelte', () => ({
+  notify: vi.fn(),
+}));
+
+vi.mock('@tanstack/svelte-query', async (importOriginal) => {
+  const actual = await importOriginal();
+  return {
+    ...actual as any,
+    useQueryClient: () => new QueryClient(),
+    createMutation: (factory: any) => {
+      const config = factory();
+      return {
+        mutateAsync: async (vars: unknown) => config.mutationFn(vars),
+        mutate: vi.fn(),
+        isPending: false,
+      };
+    },
+    createQuery: (factory: any) => {
+      const config = factory();
+      return {
+        data: config.queryKey[0] === 'taskList'
+          ? { data: [{ id: 'task-1', status: 'queued' }], total: 1 }
+          : { id: 'task-1', status: 'running' },
+        isLoading: false,
+        isSuccess: true,
+        isError: false,
+        error: null,
+        dataUpdatedAt: Date.now(),
+        errorUpdatedAt: 0,
+      };
+    },
+  };
+});
+
+describe('task-hooks', () => {
+  it('useSubmitTask exposes a working mutation', async () => {
+    let submitTask: ReturnType<typeof useSubmitTask>;
+
+    const cleanup = $effect.root(() => {
+      submitTask = useSubmitTask();
+    });
+
+    flushSync();
+
+    const handle = await submitTask!.mutation.mutateAsync({
+      taskName: 'image.generate',
+      options: { body: { prompt: 'poster' } },
+    });
+
+    expect(handle.id).toBe('task-1');
+    expect(mockTaskProvider.submit).toHaveBeenCalledWith('image.generate', {
+      body: { prompt: 'poster' },
+    });
+
+    cleanup();
+  });
+
+  it('useTask returns query state for a single task', () => {
+    let taskQuery: ReturnType<typeof useTask>;
+
+    const cleanup = $effect.root(() => {
+      taskQuery = useTask({ taskId: 'task-1' });
+    });
+
+    flushSync();
+
+    expect(taskQuery!.data).toBeDefined();
+    expect((taskQuery!.data as any).status).toBe('running');
+
+    cleanup();
+  });
+
+  it('useTaskList returns task collection data', () => {
+    let taskListQuery: ReturnType<typeof useTaskList>;
+
+    const cleanup = $effect.root(() => {
+      taskListQuery = useTaskList();
+    });
+
+    flushSync();
+
+    expect(taskListQuery!.data).toBeDefined();
+    expect((taskListQuery!.data as any).data[0].id).toBe('task-1');
+
+    cleanup();
+  });
+
+  it('useTaskSubscription subscribes to task updates', () => {
+    const onTask = vi.fn();
+
+    const cleanup = $effect.root(() => {
+      useTaskSubscription({
+        taskId: 'task-1',
+        onTask,
+      });
+    });
+
+    flushSync();
+
+    expect(mockTaskProvider.subscribe).toHaveBeenCalledWith('task-1', expect.any(Function));
+    expect(onTask).toHaveBeenCalledWith({ id: 'task-1', status: 'running' });
+
+    cleanup();
+  });
+});

package/src/types.ts

@@ -192,6 +192,50 @@ export interface DataProvider {
   custom?: <TData = unknown, TVariables = unknown>(params: CustomParams<TVariables>) => Promise<CustomResult<TData>>;
 }
 
+// ─── TaskProvider ─────────────────────────────────────────────
+
+export interface TaskRecord extends BaseRecord {
+  id: string;
+  status?: string;
+  createdAt?: string | Date;
+  updatedAt?: string | Date;
+  error?: unknown;
+}
+
+export interface SubmitTaskOptions {
+  body?: Record<string, unknown>;
+  idempotencyKey?: string;
+  headers?: Record<string, string>;
+  meta?: Record<string, unknown>;
+}
+
+export interface TaskSubscription {
+  unsubscribe(): void;
+}
+
+export interface TaskHandle<TTask extends TaskRecord = TaskRecord> {
+  id?: string;
+  wait(): Promise<TTask>;
+  subscribe?(callback: (task: TTask) => void): TaskSubscription | (() => void) | void;
+  cancel?(): Promise<unknown>;
+  retry?(): Promise<unknown>;
+}
+
+export interface TaskListResult<TTask extends TaskRecord = TaskRecord> {
+  data: TTask[];
+  total?: number;
+}
+
+export interface TaskProvider<TTask extends TaskRecord = TaskRecord> {
+  submit(taskName: string, options?: SubmitTaskOptions): Promise<TaskHandle<TTask>>;
+  get(taskId: string): Promise<TTask>;
+  list?(params?: Record<string, unknown>): Promise<TaskListResult<TTask>>;
+  listDlq?(params?: Record<string, unknown>): Promise<TaskListResult<TTask>>;
+  cancel?(taskId: string): Promise<unknown>;
+  retry?(taskId: string): Promise<unknown>;
+  subscribe?(taskId: string, callback: (task: TTask) => void): TaskSubscription | (() => void) | void;
+}
+
 // ─── AuthProvider ─────────────────────────────────────────────
 
 export interface Identity {