@aleph-alpha/chat-kit 1.4.0 → 1.5.1

package/src/composables/fileUpload/useFileUpload.ts

@@ -0,0 +1,1242 @@
+import { ref, computed, toRaw } from 'vue';
+import {
+  defaultEndpoints,
+  SdkError,
+  type EndpointResolver,
+  type FileConstraints,
+  type FileEntry,
+  type FileStateMap,
+  type FileUploadError,
+  type FileThumbnail,
+  type PersistOptions,
+  type RemoveFileOptions,
+  type RetryPolicy,
+  type ScopedFileView,
+  type SseEvent,
+  type UploadEvent,
+  type UploadFileResult,
+  type UploadParams,
+  type UploadResult,
+  type UseFileUploadOptions,
+  type UseFileUploadReturn,
+  type ValidatorFn,
+  type WorkflowRun,
+  type WorkflowRunEvent,
+  type WorkflowStream,
+} from './types';
+
+export * from './types';
+
+// ---------------------------------------------------------------------------
+//  Constants
+// ---------------------------------------------------------------------------
+
+const DEFAULT_CONSTRAINTS: FileConstraints = {
+  allowedMimeTypes: [
+    'application/pdf',
+    'text/plain',
+    'text/csv',
+    'application/msword',
+    'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    'application/vnd.ms-excel',
+    'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    'application/vnd.ms-powerpoint',
+    'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+    'image/png',
+    'image/jpeg',
+    'image/gif',
+    'image/webp',
+  ],
+  allowedExtensions: [
+    '.pdf',
+    '.txt',
+    '.csv',
+    '.doc',
+    '.docx',
+    '.xls',
+    '.xlsx',
+    '.ppt',
+    '.pptx',
+    '.png',
+    '.jpg',
+    '.jpeg',
+    '.gif',
+    '.webp',
+  ],
+  maxFileSizeBytes: 100 * 1024 * 1024,
+  maxFilesPerUpload: 20,
+};
+
+const DEFAULT_RETRY_POLICY: RetryPolicy = {
+  maxRetries: 2,
+  delayMs: 1000,
+  backoffMultiplier: 2,
+  retryableStatusCodes: [408, 429, 500, 502, 503],
+};
+
+const FILE_ICON_SVG = `data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='128' height='128' viewBox='0 0 24 24' fill='none' stroke='%2371717a' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z'/%3E%3Cpath d='M14 2v4a2 2 0 0 0 2 2h4'/%3E%3C/svg%3E`;
+
+const FILE_ICONS: Record<string, string> = {
+  _default: FILE_ICON_SVG,
+  'application/pdf': `data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='128' height='128' viewBox='0 0 24 24' fill='none' stroke='%23ef4444' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z'/%3E%3Cpath d='M14 2v4a2 2 0 0 0 2 2h4'/%3E%3Cpath d='M10 12h4'/%3E%3Cpath d='M10 16h4'/%3E%3C/svg%3E`,
+  'text/plain': `data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='128' height='128' viewBox='0 0 24 24' fill='none' stroke='%2371717a' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z'/%3E%3Cpath d='M14 2v4a2 2 0 0 0 2 2h4'/%3E%3Cpath d='M10 12h4'/%3E%3Cpath d='M10 16h4'/%3E%3C/svg%3E`,
+  'text/csv': `data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='128' height='128' viewBox='0 0 24 24' fill='none' stroke='%2322c55e' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z'/%3E%3Cpath d='M14 2v4a2 2 0 0 0 2 2h4'/%3E%3Cpath d='M8 15h2'/%3E%3Cpath d='M14 15h2'/%3E%3Cpath d='M8 11h2'/%3E%3Cpath d='M14 11h2'/%3E%3C/svg%3E`,
+};
+
+const DB_VERSION = 1;
+
+const ACTIVE_UPLOAD_STATUSES = new Set(['queued', 'validating', 'uploading']);
+const ACTIVE_OR_PROCESSING = new Set([
+  'queued',
+  'validating',
+  'uploading',
+  'processing',
+]);
+
+// ---------------------------------------------------------------------------
+//  Internal Helpers
+// ---------------------------------------------------------------------------
+
+function now(): string {
+  return new Date().toISOString();
+}
+
+function extensionOf(name: string): string {
+  const dot = name.lastIndexOf('.');
+  return dot === -1 ? '' : name.slice(dot).toLowerCase();
+}
+
+function debounce(fn: () => void, ms: number) {
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  return () => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(fn, ms);
+  };
+}
+
+// ---------------------------------------------------------------------------
+//  Concurrency Semaphore
+// ---------------------------------------------------------------------------
+
+class Semaphore {
+  private permits: number;
+  private queue: Array<() => void> = [];
+
+  constructor(permits: number) {
+    this.permits = permits;
+  }
+
+  acquire(): Promise<void> {
+    if (this.permits > 0) {
+      this.permits--;
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+      this.queue.push(resolve);
+    });
+  }
+
+  release(): void {
+    if (this.queue.length > 0) {
+      this.queue.shift()!();
+    } else {
+      this.permits++;
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+//  Thumbnail Generation
+// ---------------------------------------------------------------------------
+
+function iconFallback(file: File): FileThumbnail {
+  const dataUrl = FILE_ICONS[file.type] || FILE_ICONS._default;
+  return {
+    dataUrl: dataUrl ?? '',
+    width: 128,
+    height: 128,
+    generatedAt: now(),
+    strategy: 'icon-fallback',
+  };
+}
+
+function generateCanvasThumbnail(
+  file: File,
+  maxW = 128,
+  maxH = 128,
+): Promise<FileThumbnail> {
+  return new Promise((resolve, reject) => {
+    if (typeof document === 'undefined') {
+      reject(new Error('Canvas is not available in this environment'));
+      return;
+    }
+
+    const url = URL.createObjectURL(file);
+    const img = new Image();
+
+    img.onload = () => {
+      let w = img.naturalWidth;
+      let h = img.naturalHeight;
+      const ratio = Math.min(maxW / w, maxH / h, 1);
+      w = Math.round(w * ratio);
+      h = Math.round(h * ratio);
+
+      const canvas = document.createElement('canvas');
+      canvas.width = w;
+      canvas.height = h;
+      const ctx = canvas.getContext('2d')!;
+      ctx.drawImage(img, 0, 0, w, h);
+
+      const dataUrl = canvas.toDataURL('image/png');
+      URL.revokeObjectURL(url);
+      resolve({
+        dataUrl,
+        width: w,
+        height: h,
+        generatedAt: now(),
+        strategy: 'canvas',
+      });
+    };
+
+    img.onerror = () => {
+      URL.revokeObjectURL(url);
+      reject(new Error('Failed to load image for thumbnail generation'));
+    };
+
+    img.src = url;
+  });
+}
+
+async function generateThumbnail(file: File): Promise<FileThumbnail> {
+  if (file.type.startsWith('image/')) {
+    try {
+      return await generateCanvasThumbnail(file);
+    } catch {
+      return iconFallback(file);
+    }
+  }
+  return iconFallback(file);
+}
+
+// ---------------------------------------------------------------------------
+//  Validation
+// ---------------------------------------------------------------------------
+
+function validateFileConstraints(
+  file: File,
+  constraints: FileConstraints,
+): FileUploadError | null {
+  const ext = extensionOf(file.name);
+
+  if (file.size > constraints.maxFileSizeBytes) {
+    return {
+      code: 'FILE_TOO_LARGE',
+      message: `File "${file.name}" exceeds the maximum size of ${constraints.maxFileSizeBytes} bytes.`,
+      occurredAt: now(),
+    };
+  }
+
+  if (
+    constraints.allowedMimeTypes.length > 0 &&
+    !constraints.allowedMimeTypes.includes(file.type)
+  ) {
+    return {
+      code: 'FILE_TYPE_NOT_ALLOWED',
+      message: `MIME type "${file.type}" is not allowed for file "${file.name}".`,
+      occurredAt: now(),
+    };
+  }
+
+  if (
+    constraints.allowedExtensions.length > 0 &&
+    ext !== '' &&
+    !constraints.allowedExtensions.includes(ext)
+  ) {
+    return {
+      code: 'FILE_TYPE_NOT_ALLOWED',
+      message: `Extension "${ext}" is not allowed for file "${file.name}".`,
+      occurredAt: now(),
+    };
+  }
+
+  return null;
+}
+
+async function runCustomValidators(
+  file: File,
+  constraints: FileConstraints,
+  validators: ValidatorFn[],
+): Promise<FileUploadError | null> {
+  for (const validator of validators) {
+    const result = await validator(file, constraints);
+    if (!result.valid) {
+      return {
+        code: 'VALIDATION_FAILED',
+        message: result.reason ?? `Validation failed for "${file.name}".`,
+        occurredAt: now(),
+      };
+    }
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+//  Retry
+// ---------------------------------------------------------------------------
+
+function isRetryable(err: unknown, policy: RetryPolicy): boolean {
+  if (!policy.retryableStatusCodes?.length) return true;
+  const status =
+    (err as any)?.httpStatus ??
+    (err as any)?.status ??
+    (err as any)?.response?.status;
+  return status != null && policy.retryableStatusCodes.includes(status);
+}
+
+async function withRetry<T>(
+  fn: () => Promise<T>,
+  policy: RetryPolicy,
+  signal: AbortSignal,
+): Promise<T> {
+  let lastError: unknown;
+  for (let attempt = 0; attempt <= policy.maxRetries; attempt++) {
+    if (signal.aborted)
+      throw new SdkError('UPLOAD_ABORTED', 'Upload cancelled.');
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err;
+      if (signal.aborted) throw err;
+      if (attempt < policy.maxRetries && isRetryable(err, policy)) {
+        const delay =
+          policy.delayMs * Math.pow(policy.backoffMultiplier ?? 2, attempt);
+        await new Promise((r) => setTimeout(r, delay));
+      }
+    }
+  }
+  throw lastError;
+}
+
+// ---------------------------------------------------------------------------
+//  IndexedDB Persistence
+// ---------------------------------------------------------------------------
+
+function openDB(dbName: string, storeName: string): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    const request = indexedDB.open(dbName, DB_VERSION);
+    request.onupgradeneeded = () => {
+      const db = request.result;
+      if (!db.objectStoreNames.contains(storeName)) {
+        db.createObjectStore(storeName, { keyPath: 'id' });
+      }
+    };
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error);
+  });
+}
+
+function persistEntries(
+  db: IDBDatabase,
+  storeName: string,
+  entries: FileEntry[],
+  filter?: (entry: FileEntry) => boolean,
+): Promise<void> {
+  const filtered = filter ? entries.filter(filter) : entries;
+  const tx = db.transaction(storeName, 'readwrite');
+  const store = tx.objectStore(storeName);
+  for (const entry of filtered) {
+    store.put(structuredClone(toRaw(entry)));
+  }
+  return new Promise((resolve, reject) => {
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error);
+  });
+}
+
+function deletePersistedEntry(
+  db: IDBDatabase,
+  storeName: string,
+  id: string,
+): Promise<void> {
+  const tx = db.transaction(storeName, 'readwrite');
+  tx.objectStore(storeName).delete(id);
+  return new Promise((resolve, reject) => {
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error);
+  });
+}
+
+function restoreEntries(
+  db: IDBDatabase,
+  storeName: string,
+  maxAge?: number,
+): Promise<FileEntry[]> {
+  const tx = db.transaction(storeName, 'readonly');
+  const request = tx.objectStore(storeName).getAll();
+  return new Promise((resolve, reject) => {
+    request.onsuccess = () => {
+      let entries: FileEntry[] = request.result;
+      if (maxAge) {
+        const cutoff = Date.now() - maxAge;
+        entries = entries.filter(
+          (e) => new Date(e.queuedAt).getTime() > cutoff,
+        );
+      }
+      resolve(entries.map(rehydrateEntry));
+    };
+    request.onerror = () => reject(request.error);
+  });
+}
+
+function purgeStore(db: IDBDatabase, storeName: string): Promise<void> {
+  const tx = db.transaction(storeName, 'readwrite');
+  tx.objectStore(storeName).clear();
+  return new Promise((resolve, reject) => {
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error);
+  });
+}
+
+function rehydrateEntry(entry: FileEntry): FileEntry {
+  if (
+    entry.status === 'uploading' ||
+    entry.status === 'validating' ||
+    entry.status === 'queued'
+  ) {
+    return {
+      ...entry,
+      status: 'failed',
+      error: {
+        code: 'UPLOAD_INTERRUPTED',
+        message: 'Upload was interrupted by a page reload or browser close.',
+        occurredAt: now(),
+      },
+    };
+  }
+  if (entry.status === 'processing') {
+    return {
+      ...entry,
+      status: 'failed',
+      error: {
+        code: 'PROCESSING_INTERRUPTED',
+        message: 'Workflow processing was interrupted before completion.',
+        occurredAt: now(),
+      },
+    };
+  }
+  if (entry.status === 'removing') {
+    return {
+      ...entry,
+      status: 'failed',
+      error: {
+        code: 'REMOVE_INTERRUPTED',
+        message: 'File removal was interrupted.',
+        occurredAt: now(),
+      },
+    };
+  }
+  return entry;
+}
+
+function normalizePersistConfig(
+  opt: PersistOptions | boolean | undefined,
+): PersistOptions | null {
+  if (!opt) return null;
+  if (opt === true) return {};
+  return opt;
+}
+
+// ---------------------------------------------------------------------------
+//  State Key Derivation
+// ---------------------------------------------------------------------------
+
+function deriveStateKey(
+  groupId: string,
+  fileName: string,
+  existingKeys: Set<string>,
+): string {
+  const base = `${groupId}::${fileName}`;
+  if (!existingKeys.has(base)) return base;
+  let suffix = 2;
+  while (existingKeys.has(`${base}::${suffix}`)) suffix++;
+  return `${base}::${suffix}`;
+}
+
+// ---------------------------------------------------------------------------
+//  Composable
+// ---------------------------------------------------------------------------
+
+export function useFileUpload(
+  options: UseFileUploadOptions,
+): UseFileUploadReturn {
+  const { client, workflowId } = options;
+  let storeId = options.storeId ?? '';
+  const endpoints: EndpointResolver = options.endpoints ?? defaultEndpoints;
+  const retryPolicy: RetryPolicy = options.retryPolicy ?? DEFAULT_RETRY_POLICY;
+  const constraints: FileConstraints = { ...DEFAULT_CONSTRAINTS };
+  const validators: ValidatorFn[] = options.validators ?? [];
+  const maxConcurrency = options.maxConcurrency ?? 3;
+
+  // ---- Reactive state ----
+  const files = ref<FileStateMap>(new Map());
+  const workflowRun = ref<WorkflowRun | null>(null);
+  const isRestoring = ref(false);
+
+  // ---- Internal registries ----
+  const uploadControllers = new Map<string, AbortController>();
+  const semaphore = new Semaphore(maxConcurrency);
+
+  // ---- Persistence ----
+  const persistConfig = normalizePersistConfig(options.persist);
+  let db: IDBDatabase | null = null;
+  const persistDbName = persistConfig?.dbName ?? 'file-upload-sdk';
+  const persistStoreName = persistConfig?.storeName ?? 'file-entries';
+  const persistDebounceMs = persistConfig?.debounceMs ?? 300;
+
+  const schedulePersist = debounce(async () => {
+    if (!db) return;
+    try {
+      const entries = [...files.value.values()];
+      await persistEntries(
+        db,
+        persistStoreName,
+        entries,
+        persistConfig?.filter,
+      );
+      emit({ type: 'state:persisted', entryCount: entries.length });
+    } catch (err) {
+      emit({ type: 'state:persist-error', error: err as Error });
+    }
+  }, persistDebounceMs);
+
+  function persistIfEnabled() {
+    if (persistConfig && db) schedulePersist();
+  }
+
+  // ---- Events ----
+
+  function emit(event: UploadEvent) {
+    options.onEvent?.(event);
+  }
+
+  // ---- State helpers ----
+
+  function setEntry(entry: FileEntry) {
+    files.value.set(entry.id, entry);
+    persistIfEnabled();
+  }
+
+  function updateEntry(id: string, updates: Partial<FileEntry>) {
+    const entry = files.value.get(id);
+    if (!entry) return;
+    Object.assign(entry, updates);
+    persistIfEnabled();
+  }
+
+  // ---- Public API ----
+
+  function getSupportedFileTypes(): FileConstraints {
+    return { ...constraints };
+  }
+
+  // ---- Upload ----
+
+  async function validateAndQueueBatch(
+    batch: Array<{ file: File; stateKey: string }>,
+    groupId: string,
+    mergedMeta: Record<string, unknown>,
+  ): Promise<void> {
+    for (const { file, stateKey } of batch) {
+      const constraintErr = validateFileConstraints(file, constraints);
+      if (constraintErr) {
+        const entry = createEntry(stateKey, groupId, file, mergedMeta);
+        entry.status = 'failed';
+        entry.error = constraintErr;
+        setEntry(entry);
+        emit({ type: 'file:failed', fileId: stateKey, error: constraintErr });
+        continue;
+      }
+
+      let thumbnail: FileThumbnail | null = null;
+      try {
+        thumbnail = await generateThumbnail(file);
+      } catch (err) {
+        emit({
+          type: 'file:thumbnail-failed',
+          fileId: stateKey,
+          reason: (err as Error).message,
+        });
+      }
+
+      const entry = createEntry(stateKey, groupId, file, mergedMeta, thumbnail);
+      setEntry(entry);
+      emit({ type: 'file:queued', fileId: stateKey, entry });
+    }
+  }
+
+  async function runValidationPhase(
+    validBatch: Array<{ file: File; stateKey: string }>,
+  ): Promise<void> {
+    for (const { file, stateKey } of validBatch) {
+      updateEntry(stateKey, { status: 'validating' });
+      emit({ type: 'file:validating', fileId: stateKey });
+
+      const validationErr = await runCustomValidators(
+        file,
+        constraints,
+        validators,
+      );
+      if (validationErr) {
+        updateEntry(stateKey, { status: 'failed', error: validationErr });
+        emit({ type: 'file:failed', fileId: stateKey, error: validationErr });
+      }
+    }
+  }
+
+  function handleUploadSuccess(
+    uploadReady: Array<{ file: File; stateKey: string }>,
+    response: unknown,
+  ): void {
+    const completedAt = now();
+    const results = Array.isArray(response) ? response : [];
+
+    for (let i = 0; i < uploadReady.length; i++) {
+      const { stateKey } = uploadReady[i] as { file: File; stateKey: string };
+      const entry = files.value.get(stateKey)!;
+      const durationMs =
+        new Date(completedAt).getTime() -
+        new Date(entry.uploadStartedAt!).getTime();
+
+      const remoteResult = results[i] as
+        | { id?: string; documentId?: string }
+        | undefined;
+      const remoteFileId = remoteResult?.id ?? null;
+      const documentId = remoteResult?.documentId ?? null;
+
+      if (remoteFileId) {
+        updateEntry(stateKey, {
+          status: 'success',
+          progress: 100,
+          remoteFileId,
+          uploadCompletedAt: completedAt,
+          uploadDurationMs: durationMs,
+        });
+        if (documentId) {
+          updateFileMetadata(stateKey, { documentId });
+        }
+        emit({
+          type: 'file:success',
+          fileId: stateKey,
+          remoteFileId,
+          durationMs,
+        });
+      } else {
+        const err: FileUploadError = {
+          code: 'UPLOAD_FAILED',
+          message: `No remote ID returned for "${entry.fileName}".`,
+          occurredAt: completedAt,
+        };
+        updateEntry(stateKey, {
+          status: 'failed',
+          error: err,
+          uploadCompletedAt: completedAt,
+          uploadDurationMs: durationMs,
+        });
+        emit({ type: 'file:failed', fileId: stateKey, error: err });
+      }
+    }
+  }
+
+  function handleUploadError(
+    uploadReady: Array<{ file: File; stateKey: string }>,
+    err: unknown,
+    mergedSignal: AbortSignal,
+    batch: Array<{ file: File; stateKey: string }>,
+    groupId: string,
+  ): void {
+    const completedAt = now();
+
+    if (mergedSignal.aborted) {
+      for (const { stateKey } of uploadReady) {
+        transitionToCancelled(stateKey);
+      }
+      uploadControllers.delete(groupId);
+      const result = buildUploadResult(groupId, batch);
+      emit({
+        type: 'upload:complete',
+        groupId,
+        results: result.results,
+      });
+      throw new SdkError(
+        'UPLOAD_ABORTED',
+        `Upload "${groupId}" was cancelled.`,
+      );
+    }
+
+    const uploadErr: FileUploadError = {
+      code: 'UPLOAD_FAILED',
+      message: (err as Error).message ?? 'Upload failed.',
+      httpStatus: (err as any)?.httpStatus ?? (err as any)?.status,
+      occurredAt: completedAt,
+    };
+
+    for (const { stateKey } of uploadReady) {
+      const entry = files.value.get(stateKey)!;
+      const durationMs = entry.uploadStartedAt
+        ? new Date(completedAt).getTime() -
+          new Date(entry.uploadStartedAt).getTime()
+        : null;
+      updateEntry(stateKey, {
+        status: 'failed',
+        error: uploadErr,
+        uploadCompletedAt: completedAt,
+        uploadDurationMs: durationMs,
+      });
+      emit({ type: 'file:failed', fileId: stateKey, error: uploadErr });
+    }
+  }
+
+  async function upload(params: UploadParams): Promise<UploadResult> {
+    const fileList = Array.isArray(params.files)
+      ? params.files
+      : [params.files];
+
+    if (fileList.length > constraints.maxFilesPerUpload) {
+      throw new SdkError(
+        'MAX_FILES_EXCEEDED',
+        `Cannot upload ${fileList.length} files — maximum is ${constraints.maxFilesPerUpload}.`,
+      );
+    }
+
+    const mergedMeta: Record<string, unknown> = {
+      ...(params.metadata ?? {}),
+      ...(params.forwardedProps ?? {}),
+    };
+
+    const existingKeys = new Set(files.value.keys() as Iterable<string>);
+    const batch: Array<{ file: File; stateKey: string }> = [];
+
+    for (const file of fileList) {
+      const stateKey = deriveStateKey(params.id, file.name, existingKeys);
+      existingKeys.add(stateKey);
+      batch.push({ file, stateKey });
+    }
+
+    await validateAndQueueBatch(batch, params.id, mergedMeta);
+
+    const validBatch = batch.filter((b) => {
+      const entry = files.value.get(b.stateKey);
+      return entry && entry.status === 'queued';
+    });
+
+    if (validBatch.length === 0) {
+      return buildUploadResult(params.id, batch);
+    }
+
+    await runValidationPhase(validBatch);
+
+    const uploadReady = validBatch.filter((b) => {
+      const entry = files.value.get(b.stateKey);
+      return entry && entry.status === 'validating';
+    });
+
+    if (uploadReady.length === 0) {
+      return buildUploadResult(params.id, batch);
+    }
+
+    const formData = new FormData();
+    for (const { file } of uploadReady) {
+      formData.append('files', file, file.name);
+    }
+
+    const controller = new AbortController();
+    uploadControllers.set(params.id, controller);
+
+    const mergedSignal = params.signal
+      ? AbortSignal.any([controller.signal, params.signal])
+      : controller.signal;
+
+    const uploadStarted = now();
+    for (const { stateKey } of uploadReady) {
+      updateEntry(stateKey, {
+        status: 'uploading',
+        uploadStartedAt: uploadStarted,
+        attemptCount: (files.value.get(stateKey)?.attemptCount ?? 0) + 1,
+        lastAttemptAt: uploadStarted,
+      });
+      emit({
+        type: 'file:uploading',
+        fileId: stateKey,
+        attemptCount: files.value.get(stateKey)!.attemptCount,
+      });
+    }
+
+    const totalBytes = uploadReady.reduce(
+      (sum, { file }) => sum + file.size,
+      0,
+    );
+
+    const onUploadProgress = (event: { loaded: number; total: number }) => {
+      const ratio = event.total > 0 ? event.loaded / event.total : 0;
+      const loadedBytes = ratio * totalBytes;
+
+      for (const { file, stateKey } of uploadReady) {
+        const fileShare =
+          totalBytes > 0 ? loadedBytes * (file.size / totalBytes) : 0;
+        const progress = Math.min(
+          100,
+          Math.round((fileShare / Math.max(file.size, 1)) * 100),
+        );
+        updateEntry(stateKey, { progress });
+        emit({ type: 'file:progress', fileId: stateKey, progress });
+      }
+    };
+
+    await semaphore.acquire();
+
+    try {
+      const response = await withRetry(
+        () =>
+          client.post<unknown[]>(endpoints.files(storeId), formData, {
+            signal: mergedSignal,
+            onUploadProgress,
+          }),
+        retryPolicy,
+        mergedSignal,
+      );
+      handleUploadSuccess(uploadReady, response);
+    } catch (err) {
+      handleUploadError(uploadReady, err, mergedSignal, batch, params.id);
+    } finally {
+      semaphore.release();
+      uploadControllers.delete(params.id);
+    }
+
+    const result = buildUploadResult(params.id, batch);
+    emit({
+      type: 'upload:complete',
+      groupId: params.id,
+      results: result.results,
+    });
+    return result;
+  }
+
+  function createEntry(
+    id: string,
+    groupId: string,
+    file: File,
+    metadata: Record<string, unknown>,
+    thumbnail: FileThumbnail | null = null,
+  ): FileEntry {
+    return {
+      id,
+      groupId,
+      fileName: file.name,
+      fileSize: file.size,
+      fileType: file.type,
+      status: 'queued',
+      progress: 0,
+      queuedAt: now(),
+      uploadStartedAt: null,
+      uploadCompletedAt: null,
+      cancelledAt: null,
+      removedAt: null,
+      uploadDurationMs: null,
+      remoteFileId: null,
+      error: null,
+      attemptCount: 0,
+      lastAttemptAt: null,
+      thumbnail,
+      metadata: { ...metadata },
+    };
+  }
+
+  function buildUploadResult(
+    groupId: string,
+    batch: Array<{ stateKey: string }>,
+  ): UploadResult {
+    return {
+      id: groupId,
+      results: batch.map(({ stateKey }) => {
+        const entry = files.value.get(stateKey)!;
+        return {
+          fileId: stateKey,
+          success: entry.status === 'success',
+          status: entry.status,
+          remoteFileId: entry.remoteFileId ?? undefined,
+          error: entry.error ?? undefined,
+          uploadDate: entry.uploadCompletedAt ?? entry.queuedAt,
+          metadata: entry.metadata,
+        } satisfies UploadFileResult;
+      }),
+    };
+  }
+
+  // ---- Cancel ----
+
+  function cancel(groupId: string): void {
+    const controller = uploadControllers.get(groupId);
+    if (controller) {
+      controller.abort();
+      uploadControllers.delete(groupId);
+    }
+
+    for (const [, entry] of files.value) {
+      if (entry.groupId === groupId) {
+        transitionToCancelled(entry.id);
+      }
+    }
+  }
+
+  function transitionToCancelled(id: string): void {
+    const entry = files.value.get(id);
+    if (!entry || !ACTIVE_UPLOAD_STATUSES.has(entry.status)) return;
+
+    const ts = now();
+    updateEntry(id, {
+      status: 'cancelled',
+      cancelledAt: ts,
+      error: {
+        code: 'UPLOAD_ABORTED',
+        message: 'Upload cancelled.',
+        occurredAt: ts,
+      },
+    });
+    emit({ type: 'file:cancelled', fileId: id });
+  }
+
+  // ---- Remove ----
+
+  async function removeFile(
+    fileId: string,
+    opts?: RemoveFileOptions,
+  ): Promise<void> {
+    const removeFromState = opts?.removeFromState ?? true;
+    const removeFromRemote = opts?.removeFromRemote ?? true;
+
+    const entry = files.value.get(fileId);
+
+    if (removeFromRemote && entry?.remoteFileId) {
+      updateEntry(fileId, { status: 'removing' });
+      try {
+        await client.delete(endpoints.file(storeId, entry.remoteFileId));
+      } catch (err) {
+        const status =
+          (err as any)?.httpStatus ??
+          (err as any)?.status ??
+          (err as any)?.response?.status;
+
+        if (status === 404) {
+          // File no longer exists on the server — proceed with local removal.
+        } else {
+          const removeErr: FileUploadError = {
+            code: 'REMOVE_FAILED',
+            message: (err as Error).message ?? 'File removal failed.',
+            occurredAt: now(),
+          };
+          updateEntry(fileId, { status: 'failed', error: removeErr });
+          throw new SdkError('REMOVE_FAILED', removeErr.message);
+        }
+      }
+    }
+
+    if (removeFromState) {
+      files.value.delete(fileId);
+      if (db) {
+        try {
+          await deletePersistedEntry(db, persistStoreName, fileId);
+        } catch {
+          /* non-fatal */
+        }
+      }
+      emit({ type: 'file:removed', fileId });
+    } else if (entry) {
+      updateEntry(fileId, { status: 'removed', removedAt: now() });
+      emit({ type: 'file:removed', fileId });
+    }
+  }
+
+  // ---- State queries ----
+
+  function getFileState(id: string): FileEntry | undefined {
+    return files.value.get(id);
+  }
+
+  function updateFileMetadata(id: string, meta: Record<string, unknown>): void {
+    const entry = files.value.get(id);
+    if (!entry) return;
+    Object.assign(entry.metadata, meta);
+    persistIfEnabled();
+  }
+
+  function clearState(): void {
+    files.value.clear();
+    if (db) {
+      purgeStore(db, persistStoreName).catch(() => {
+        /* non-fatal */
+      });
+    }
+  }
+
+  // ---- Scoped views ----
+
+  function scopeBy(metadataKey: string, value: string): ScopedFileView {
+    const scopedFiles = computed(() =>
+      [...files.value.values()].filter(
+        (f) => f.metadata[metadataKey] === value,
+      ),
+    );
+
+    const progress = computed(() => {
+      const active = scopedFiles.value.filter((f) =>
+        ACTIVE_OR_PROCESSING.has(f.status),
+      );
+      if (!active.length) return 100;
+      return Math.round(
+        active.reduce((sum, f) => sum + f.progress, 0) / active.length,
+      );
+    });
+
+    const isUploading = computed(() =>
+      scopedFiles.value.some((f) => ACTIVE_UPLOAD_STATUSES.has(f.status)),
+    );
+
+    const hasErrors = computed(() =>
+      scopedFiles.value.some((f) => f.status === 'failed'),
+    );
+
+    return {
+      files: scopedFiles,
+      count: computed(() => scopedFiles.value.length),
+      progress,
+      isUploading,
+      hasErrors,
+      clear: () => {
+        for (const entry of scopedFiles.value) {
+          files.value.delete(entry.id);
+          if (db) {
+            deletePersistedEntry(db, persistStoreName, entry.id).catch(
+              () => {},
+            );
+          }
+        }
+      },
+      cancel: () => {
+        const groupIds = new Set<string>(
+          scopedFiles.value.map((e) => e.groupId),
+        );
+        for (const gid of groupIds) cancel(gid);
+      },
+      retry: (fileId: string) => {
+        const entry = files.value.get(fileId);
+        if (entry && entry.status === 'failed') {
+          updateEntry(fileId, { status: 'queued', error: null, progress: 0 });
+        }
+      },
+    };
+  }
+
+  // ---- Workflow ----
+
+  async function runWorkflow(fileIds: string[]): Promise<WorkflowStream> {
+    const source = fileIds.map((id) => `files://${id}`);
+    const input = { source };
+
+    const controller = new AbortController();
+
+    const involvedStateKeys = [...files.value.values()]
+      .filter((e) => e.remoteFileId && fileIds.includes(e.remoteFileId))
+      .map((e) => e.id);
+
+    let sseEventCount = 0;
+
+    for (const key of involvedStateKeys) {
+      updateEntry(key, { status: 'processing', progress: 0 });
+    }
+
+    const runResponse = await client.post<{ id: string }>(
+      endpoints.workflowRun(storeId, workflowId),
+      { input },
+      { signal: controller.signal },
+    );
+
+    const runId = runResponse.id;
+
+    workflowRun.value = {
+      runId,
+      workflowId,
+      storeId,
+      status: 'connecting',
+      events: [],
+      error: null,
+      startedAt: now(),
+      completedAt: null,
+    };
+
+    emit({ type: 'workflow:started', runId });
+
+    const sseEndpoint = endpoints.workflowRunEventStream(
+      storeId,
+      workflowId,
+      runId,
+    );
+    const sseStream = client.stream(sseEndpoint, {
+      signal: controller.signal,
+    });
+
+    sseStream.subscribe((event: SseEvent) => {
+      if (!workflowRun.value) return;
+
+      let data: { id?: string; status?: string };
+      try {
+        data = JSON.parse(event.data);
+      } catch {
+        data = {};
+      }
+
+      const runEvent: WorkflowRunEvent = {
+        id: data.id ?? '',
+        status: data.status ?? event.event,
+      };
+
+      workflowRun.value.events.push(runEvent);
+      emit({ type: 'workflow:event', event: runEvent });
+
+      if (data.status === 'completed') {
+        workflowRun.value.status = 'completed';
+        workflowRun.value.completedAt = now();
+        for (const key of involvedStateKeys) {
+          updateEntry(key, { status: 'success', progress: 100 });
+        }
+        emit({ type: 'workflow:completed', runId });
+      } else if (data.status === 'failed' || data.status === 'error') {
+        workflowRun.value.status = 'failed';
+        workflowRun.value.completedAt = now();
+        workflowRun.value.error = {
+          code: 'WORKFLOW_RUN_FAILED',
+          message: `Workflow run ${runId} failed.`,
+        };
+        const workflowErr: FileUploadError = {
+          code: 'UPLOAD_FAILED',
+          message: `Workflow run ${runId} failed.`,
+          occurredAt: now(),
+        };
+        for (const key of involvedStateKeys) {
+          updateEntry(key, { status: 'failed', error: workflowErr });
+        }
+        emit({
+          type: 'workflow:failed',
+          runId,
+          error: workflowRun.value.error,
+        });
+      } else {
+        workflowRun.value.status = 'running';
+        sseEventCount++;
+        const estimated = Math.round(100 * (1 - 1 / (1 + sseEventCount * 0.3)));
+        for (const key of involvedStateKeys) {
+          updateEntry(key, { progress: estimated });
+          emit({ type: 'file:progress', fileId: key, progress: estimated });
+        }
+      }
+    });
+
+    return {
+      close() {
+        controller.abort();
+        sseStream.close();
+        if (
+          workflowRun.value &&
+          !['completed', 'failed', 'cancelled'].includes(
+            workflowRun.value.status,
+          )
+        ) {
+          workflowRun.value.status = 'cancelled';
+          workflowRun.value.completedAt = now();
+        }
+      },
+    };
+  }
+
+  // ---- Persistence: restore / purge ----
+
+  async function restoreState(): Promise<void> {
+    if (!persistConfig) return;
+    isRestoring.value = true;
+    try {
+      if (!db) db = await openDB(persistDbName, persistStoreName);
+      const entries = await restoreEntries(
+        db,
+        persistStoreName,
+        persistConfig.maxAge,
+      );
+      for (const entry of entries) {
+        files.value.set(entry.id, entry);
+      }
+      emit({ type: 'state:restored', entryCount: entries.length });
+    } catch (err) {
+      emit({ type: 'state:persist-error', error: err as Error });
+    } finally {
+      isRestoring.value = false;
+    }
+  }
+
+  async function purgePersistedState(): Promise<void> {
+    if (!db) return;
+    try {
+      await purgeStore(db, persistStoreName);
+    } catch (err) {
+      emit({ type: 'state:persist-error', error: err as Error });
+    }
+  }
+
+  // ---- Init ----
+
+  if (persistConfig) {
+    openDB(persistDbName, persistStoreName)
+      .then((database) => {
+        db = database;
+        return restoreState();
+      })
+      .catch((err) => {
+        emit({ type: 'state:persist-error', error: err as Error });
+      });
+  }
+
+  // ---- Return ----
+
+  function setStoreId(id: string) {
+    storeId = id;
+  }
+
+  async function getPublicUrl(fileId: string): Promise<string> {
+    const res = await client.post<{ url: string; expires_at: string }>(
+      endpoints.filePublicUrl(storeId, fileId),
+      {},
+    );
+    return res.url;
+  }
+
+  return {
+    getSupportedFileTypes,
+
+    upload,
+    cancel,
+    removeFile,
+
+    files,
+    getFileState,
+    updateFileMetadata,
+    clearState,
+    setStoreId,
+    getPublicUrl,
+
+    scopeBy,
+
+    workflowRun,
+    runWorkflow,
+
+    isRestoring,
+    restoreState,
+    purgePersistedState,
+  };
+}