Redesgin ToolOperationConfig so types are known for single/multiple/custom tools (#4221)

# Description of Changes
Redesigns `ToolOperationConfig` so that the types of the functions are
always known depending on whether the tool runs on single files,
multiple files, or uses custom behaviour

frontend/src/hooks/tools/addPassword/useAddPasswordOperation.test.ts

@@ -4,9 +4,13 @@ import { useAddPasswordOperation } from './useAddPasswordOperation';
 import type { AddPasswordFullParameters, AddPasswordParameters } from './useAddPasswordParameters';
 
 // Mock the useToolOperation hook
-vi.mock('../shared/useToolOperation', () => ({
-  useToolOperation: vi.fn()
-}));
+vi.mock('../shared/useToolOperation', async () => {
+  const actual = await vi.importActual('../shared/useToolOperation');  // Need to keep ToolType etc.
+  return {
+    ...actual,
+    useToolOperation: vi.fn()
+  };
+});
 
 // Mock the translation hook
 const mockT = vi.fn((key: string) => `translated-${key}`);
@@ -20,13 +24,13 @@ vi.mock('../../../utils/toolErrorHandler', () => ({
 }));
 
 // Import the mocked function
-import { ToolOperationConfig, ToolOperationHook, useToolOperation } from '../shared/useToolOperation';
+import { SingleFileToolOperationConfig, ToolOperationHook, ToolType, useToolOperation } from '../shared/useToolOperation';
 
 
 describe('useAddPasswordOperation', () => {
   const mockUseToolOperation = vi.mocked(useToolOperation);
 
-  const getToolConfig = (): ToolOperationConfig<AddPasswordFullParameters> => mockUseToolOperation.mock.calls[0][0] as ToolOperationConfig<AddPasswordFullParameters>;
+  const getToolConfig = () => mockUseToolOperation.mock.calls[0][0] as SingleFileToolOperationConfig<AddPasswordFullParameters>;
 
   const mockToolOperationReturn: ToolOperationHook<unknown> = {
     files: [],
@@ -91,7 +95,7 @@ describe('useAddPasswordOperation', () => {
     };
 
     const testFile = new File(['test content'], 'test.pdf', { type: 'application/pdf' });
-    const formData = buildFormData(testParameters, testFile as any /* FIX ME */);
+    const formData = buildFormData(testParameters, testFile);
 
     // Verify the form data contains the file
     expect(formData.get('fileInput')).toBe(testFile);
@@ -112,7 +116,7 @@ describe('useAddPasswordOperation', () => {
   });
 
   test.each([
-    { property: 'multiFileEndpoint' as const, expectedValue: false },
+    { property: 'toolType' as const, expectedValue: ToolType.singleFile },
     { property: 'endpoint' as const, expectedValue: '/api/v1/security/add-password' },
     { property: 'filePrefix' as const, expectedValue: 'translated-addPassword.filenamePrefix_' },
     { property: 'operationType' as const, expectedValue: 'addPassword' }

frontend/src/hooks/tools/addPassword/useAddPasswordOperation.ts

@@ -1,5 +1,5 @@
 import { useTranslation } from 'react-i18next';
-import { useToolOperation } from '../shared/useToolOperation';
+import { ToolType, useToolOperation } from '../shared/useToolOperation';
 import { createStandardErrorHandler } from '../../../utils/toolErrorHandler';
 import { AddPasswordFullParameters, defaultParameters } from './useAddPasswordParameters';
 import { defaultParameters as permissionsDefaults } from '../changePermissions/useChangePermissionsParameters';
@@ -26,11 +26,11 @@ const fullDefaultParameters: AddPasswordFullParameters = {
 
 // Static configuration object
 export const addPasswordOperationConfig = {
+  toolType: ToolType.singleFile,
+  buildFormData: buildAddPasswordFormData,
   operationType: 'addPassword',
   endpoint: '/api/v1/security/add-password',
-  buildFormData: buildAddPasswordFormData,
   filePrefix: 'encrypted_', // Will be overridden in hook with translation
-  multiFileEndpoint: false,
   defaultParameters: fullDefaultParameters,
 } as const;
 

frontend/src/hooks/tools/addWatermark/useAddWatermarkOperation.ts

@@ -1,5 +1,5 @@
 import { useTranslation } from 'react-i18next';
-import { useToolOperation } from '../shared/useToolOperation';
+import { ToolType, useToolOperation } from '../shared/useToolOperation';
 import { createStandardErrorHandler } from '../../../utils/toolErrorHandler';
 import { AddWatermarkParameters, defaultParameters } from './useAddWatermarkParameters';
 
@@ -35,11 +35,11 @@ export const buildAddWatermarkFormData = (parameters: AddWatermarkParameters, fi
 
 // Static configuration object
 export const addWatermarkOperationConfig = {
+  toolType: ToolType.singleFile,
+  buildFormData: buildAddWatermarkFormData,
   operationType: 'watermark',
   endpoint: '/api/v1/security/add-watermark',
-  buildFormData: buildAddWatermarkFormData,
   filePrefix: 'watermarked_', // Will be overridden in hook with translation
-  multiFileEndpoint: false,
   defaultParameters,
 } as const;
 
@@ -51,4 +51,4 @@ export const useAddWatermarkOperation = () => {
     filePrefix: t('watermark.filenamePrefix', 'watermarked') + '_',
     getErrorMessage: createStandardErrorHandler(t('watermark.error.failed', 'An error occurred while adding watermark to the PDF.'))
   });
-};
+};

frontend/src/hooks/tools/automate/useAutomateOperation.ts

@@ -1,4 +1,4 @@
-import { useToolOperation } from '../shared/useToolOperation';
+import { ToolType, useToolOperation } from '../shared/useToolOperation';
 import { useCallback } from 'react';
 import { executeAutomationSequence } from '../../../utils/automationExecutor';
 import { useFlatToolRegistry } from '../../../data/useTranslatedToolRegistry';
@@ -10,7 +10,7 @@ export function useAutomateOperation() {
 
   const customProcessor = useCallback(async (params: AutomateParameters, files: File[]) => {
     console.log('🚀 Starting automation execution via customProcessor', { params, files });
-    
+
     if (!params.automationConfig) {
       throw new Error('No automation configuration provided');
     }
@@ -40,10 +40,9 @@ export function useAutomateOperation() {
   }, [toolRegistry]);
 
   return useToolOperation<AutomateParameters>({
+    toolType: ToolType.custom,
     operationType: 'automate',
-    endpoint: '/api/v1/pipeline/handleData', // Not used with customProcessor
-    buildFormData: () => new FormData(), // Not used with customProcessor
     customProcessor,
     filePrefix: '' // No prefix needed since automation handles naming internally
   });
-}
+}

frontend/src/hooks/tools/changePermissions/useChangePermissionsOperation.test.ts

@@ -4,9 +4,13 @@ import { useChangePermissionsOperation } from './useChangePermissionsOperation';
 import type { ChangePermissionsParameters } from './useChangePermissionsParameters';
 
 // Mock the useToolOperation hook
-vi.mock('../shared/useToolOperation', () => ({
-  useToolOperation: vi.fn()
-}));
+vi.mock('../shared/useToolOperation', async () => {
+  const actual = await vi.importActual('../shared/useToolOperation');  // Need to keep ToolType etc.
+  return {
+    ...actual,
+    useToolOperation: vi.fn()
+  };
+});
 
 // Mock the translation hook
 const mockT = vi.fn((key: string) => `translated-${key}`);
@@ -20,12 +24,12 @@ vi.mock('../../../utils/toolErrorHandler', () => ({
 }));
 
 // Import the mocked function
-import { ToolOperationConfig, ToolOperationHook, useToolOperation } from '../shared/useToolOperation';
+import { SingleFileToolOperationConfig, ToolOperationHook, ToolType, useToolOperation } from '../shared/useToolOperation';
 
 describe('useChangePermissionsOperation', () => {
   const mockUseToolOperation = vi.mocked(useToolOperation);
 
-  const getToolConfig = (): ToolOperationConfig<ChangePermissionsParameters> => mockUseToolOperation.mock.calls[0][0] as ToolOperationConfig<ChangePermissionsParameters>;
+  const getToolConfig = () => mockUseToolOperation.mock.calls[0][0] as SingleFileToolOperationConfig<ChangePermissionsParameters>;
 
   const mockToolOperationReturn: ToolOperationHook<unknown> = {
     files: [],
@@ -86,7 +90,7 @@ describe('useChangePermissionsOperation', () => {
     const buildFormData = callArgs.buildFormData;
 
     const testFile = new File(['test content'], 'test.pdf', { type: 'application/pdf' });
-    const formData = buildFormData(testParameters, testFile as any /* FIX ME */);
+    const formData = buildFormData(testParameters, testFile);
 
     // Verify the form data contains the file
     expect(formData.get('fileInput')).toBe(testFile);
@@ -106,7 +110,7 @@ describe('useChangePermissionsOperation', () => {
   });
 
   test.each([
-    { property: 'multiFileEndpoint' as const, expectedValue: false },
+    { property: 'toolType' as const, expectedValue: ToolType.singleFile },
     { property: 'endpoint' as const, expectedValue: '/api/v1/security/add-password' },
     { property: 'filePrefix' as const, expectedValue: 'permissions_' },
     { property: 'operationType' as const, expectedValue: 'change-permissions' }

frontend/src/hooks/tools/changePermissions/useChangePermissionsOperation.ts

@@ -1,5 +1,5 @@
 import { useTranslation } from 'react-i18next';
-import { useToolOperation } from '../shared/useToolOperation';
+import { ToolType, useToolOperation } from '../shared/useToolOperation';
 import { createStandardErrorHandler } from '../../../utils/toolErrorHandler';
 import { ChangePermissionsParameters, defaultParameters } from './useChangePermissionsParameters';
 
@@ -24,11 +24,11 @@ export const buildChangePermissionsFormData = (parameters: ChangePermissionsPara
 
 // Static configuration object
 export const changePermissionsOperationConfig = {
+  toolType: ToolType.singleFile,
+  buildFormData: buildChangePermissionsFormData,
   operationType: 'change-permissions',
   endpoint: '/api/v1/security/add-password', // Change Permissions is a fake endpoint for the Add Password tool
-  buildFormData: buildChangePermissionsFormData,
   filePrefix: 'permissions_',
-  multiFileEndpoint: false,
   defaultParameters,
 } as const;
 
@@ -39,6 +39,6 @@ export const useChangePermissionsOperation = () => {
     ...changePermissionsOperationConfig,
     getErrorMessage: createStandardErrorHandler(
       t('changePermissions.error.failed', 'An error occurred while changing PDF permissions.')
-    )
+    ),
   });
 };

frontend/src/hooks/tools/compress/useCompressOperation.ts

@@ -1,5 +1,5 @@
 import { useTranslation } from 'react-i18next';
-import { useToolOperation, ToolOperationConfig } from '../shared/useToolOperation';
+import { useToolOperation, ToolOperationConfig, ToolType } from '../shared/useToolOperation';
 import { createStandardErrorHandler } from '../../../utils/toolErrorHandler';
 import { CompressParameters, defaultParameters } from './useCompressParameters';
 
@@ -24,11 +24,11 @@ export const buildCompressFormData = (parameters: CompressParameters, file: File
 
 // Static configuration object
 export const compressOperationConfig = {
+  toolType: ToolType.singleFile,
+  buildFormData: buildCompressFormData,
   operationType: 'compress',
   endpoint: '/api/v1/misc/compress-pdf',
-  buildFormData: buildCompressFormData,
   filePrefix: 'compressed_',
-  multiFileEndpoint: false, // Individual API calls per file
   defaultParameters,
 } as const;
 

frontend/src/hooks/tools/convert/useConvertOperation.ts

@@ -4,7 +4,7 @@ import { useTranslation } from 'react-i18next';
 import { ConvertParameters, defaultParameters } from './useConvertParameters';
 import { detectFileExtension } from '../../../utils/fileUtils';
 import { createFileFromApiResponse } from '../../../utils/fileResponseUtils';
-import { useToolOperation, ToolOperationConfig } from '../shared/useToolOperation';
+import { useToolOperation, ToolOperationConfig, ToolType } from '../shared/useToolOperation';
 import { getEndpointUrl, isImageFormat, isWebFormat } from '../../../utils/convertUtils';
 
 // Static function that can be used by both the hook and automation executor
@@ -129,11 +129,10 @@ export const convertProcessor = async (
 
 // Static configuration object
 export const convertOperationConfig = {
+  toolType: ToolType.custom,
+  customProcessor: convertProcessor, // Can't use callback version here
   operationType: 'convert',
-  endpoint: '', // Not used with customProcessor but required
-  buildFormData: buildConvertFormData, // Not used with customProcessor but required
   filePrefix: 'converted_',
-  customProcessor: convertProcessor,
   defaultParameters,
 } as const;
 
@@ -158,6 +157,6 @@ export const useConvertOperation = () => {
         return error.message;
       }
       return t("convert.errorConversion", "An error occurred while converting the file.");
-    }
+    },
   });
 };

frontend/src/hooks/tools/ocr/useOCROperation.ts

@@ -1,7 +1,7 @@
 import { useCallback } from 'react';
 import { useTranslation } from 'react-i18next';
 import { OCRParameters, defaultParameters } from './useOCRParameters';
-import { useToolOperation, ToolOperationConfig } from '../shared/useToolOperation';
+import { useToolOperation, ToolOperationConfig, ToolType } from '../shared/useToolOperation';
 import { createStandardErrorHandler } from '../../../utils/toolErrorHandler';
 import { useToolResources } from '../shared/useToolResources';
 
@@ -52,7 +52,7 @@ export const buildOCRFormData = (parameters: OCRParameters, file: File): FormDat
   return formData;
 };
 
-// Static response handler for OCR - can be used by automation executor  
+// Static response handler for OCR - can be used by automation executor
 export const ocrResponseHandler = async (blob: Blob, originalFiles: File[], extractZipFiles: (blob: Blob) => Promise<File[]>): Promise<File[]> => {
   const headBuf = await blob.slice(0, 8).arrayBuffer();
   const head = new TextDecoder().decode(new Uint8Array(headBuf));
@@ -94,11 +94,11 @@ export const ocrResponseHandler = async (blob: Blob, originalFiles: File[], extr
 
 // Static configuration object (without t function dependencies)
 export const ocrOperationConfig = {
+  toolType: ToolType.singleFile,
+  buildFormData: buildOCRFormData,
   operationType: 'ocr',
   endpoint: '/api/v1/misc/ocr-pdf',
-  buildFormData: buildOCRFormData,
   filePrefix: 'ocr_',
-  multiFileEndpoint: false,
   defaultParameters,
 } as const;
 

frontend/src/hooks/tools/removeCertificateSign/useRemoveCertificateSignOperation.ts

@@ -1,5 +1,5 @@
 import { useTranslation } from 'react-i18next';
-import { useToolOperation } from '../shared/useToolOperation';
+import { ToolType, useToolOperation } from '../shared/useToolOperation';
 import { createStandardErrorHandler } from '../../../utils/toolErrorHandler';
 import { RemoveCertificateSignParameters, defaultParameters } from './useRemoveCertificateSignParameters';
 
@@ -12,11 +12,11 @@ export const buildRemoveCertificateSignFormData = (parameters: RemoveCertificate
 
 // Static configuration object
 export const removeCertificateSignOperationConfig = {
+  toolType: ToolType.singleFile,
+  buildFormData: buildRemoveCertificateSignFormData,
   operationType: 'remove-certificate-sign',
   endpoint: '/api/v1/security/remove-cert-sign',
-  buildFormData: buildRemoveCertificateSignFormData,
   filePrefix: 'unsigned_', // Will be overridden in hook with translation
-  multiFileEndpoint: false,
   defaultParameters,
 } as const;
 
@@ -28,4 +28,4 @@ export const useRemoveCertificateSignOperation = () => {
     filePrefix: t('removeCertSign.filenamePrefix', 'unsigned') + '_',
     getErrorMessage: createStandardErrorHandler(t('removeCertSign.error.failed', 'An error occurred while removing certificate signatures.'))
   });
-};
+};

frontend/src/hooks/tools/removePassword/useRemovePasswordOperation.test.ts

@@ -3,10 +3,13 @@ import { renderHook } from '@testing-library/react';
 import { useRemovePasswordOperation } from './useRemovePasswordOperation';
 import type { RemovePasswordParameters } from './useRemovePasswordParameters';
 
-// Mock the useToolOperation hook
-vi.mock('../shared/useToolOperation', () => ({
-  useToolOperation: vi.fn()
-}));
+vi.mock('../shared/useToolOperation', async () => {
+  const actual = await vi.importActual('../shared/useToolOperation');  // Need to keep ToolType etc.
+  return {
+    ...actual,
+    useToolOperation: vi.fn()
+  };
+});
 
 // Mock the translation hook
 const mockT = vi.fn((key: string) => `translated-${key}`);
@@ -20,12 +23,12 @@ vi.mock('../../../utils/toolErrorHandler', () => ({
 }));
 
 // Import the mocked function
-import { ToolOperationConfig, ToolOperationHook, useToolOperation } from '../shared/useToolOperation';
+import { SingleFileToolOperationConfig, ToolOperationHook, ToolType, useToolOperation } from '../shared/useToolOperation';
 
 describe('useRemovePasswordOperation', () => {
   const mockUseToolOperation = vi.mocked(useToolOperation);
 
-  const getToolConfig = (): ToolOperationConfig<RemovePasswordParameters> => mockUseToolOperation.mock.calls[0][0] as ToolOperationConfig<RemovePasswordParameters>;
+  const getToolConfig = () => mockUseToolOperation.mock.calls[0][0] as SingleFileToolOperationConfig<RemovePasswordParameters>;
 
   const mockToolOperationReturn: ToolOperationHook<unknown> = {
     files: [],
@@ -91,7 +94,7 @@ describe('useRemovePasswordOperation', () => {
   });
 
   test.each([
-    { property: 'multiFileEndpoint' as const, expectedValue: false },
+    { property: 'toolType' as const, expectedValue: ToolType.singleFile },
     { property: 'endpoint' as const, expectedValue: '/api/v1/security/remove-password' },
     { property: 'filePrefix' as const, expectedValue: 'translated-removePassword.filenamePrefix_' },
     { property: 'operationType' as const, expectedValue: 'removePassword' }

frontend/src/hooks/tools/removePassword/useRemovePasswordOperation.ts

@@ -1,5 +1,5 @@
 import { useTranslation } from 'react-i18next';
-import { useToolOperation } from '../shared/useToolOperation';
+import { ToolType, useToolOperation } from '../shared/useToolOperation';
 import { createStandardErrorHandler } from '../../../utils/toolErrorHandler';
 import { RemovePasswordParameters, defaultParameters } from './useRemovePasswordParameters';
 
@@ -13,11 +13,11 @@ export const buildRemovePasswordFormData = (parameters: RemovePasswordParameters
 
 // Static configuration object
 export const removePasswordOperationConfig = {
+  toolType: ToolType.singleFile,
+  buildFormData: buildRemovePasswordFormData,
   operationType: 'removePassword',
   endpoint: '/api/v1/security/remove-password',
-  buildFormData: buildRemovePasswordFormData,
   filePrefix: 'decrypted_', // Will be overridden in hook with translation
-  multiFileEndpoint: false,
   defaultParameters,
 } as const;
 

frontend/src/hooks/tools/repair/useRepairOperation.ts

@@ -1,5 +1,5 @@
 import { useTranslation } from 'react-i18next';
-import { useToolOperation } from '../shared/useToolOperation';
+import { ToolType, useToolOperation } from '../shared/useToolOperation';
 import { createStandardErrorHandler } from '../../../utils/toolErrorHandler';
 import { RepairParameters, defaultParameters } from './useRepairParameters';
 
@@ -12,11 +12,11 @@ export const buildRepairFormData = (parameters: RepairParameters, file: File): F
 
 // Static configuration object
 export const repairOperationConfig = {
+  toolType: ToolType.singleFile,
+  buildFormData: buildRepairFormData,
   operationType: 'repair',
   endpoint: '/api/v1/misc/repair',
-  buildFormData: buildRepairFormData,
   filePrefix: 'repaired_', // Will be overridden in hook with translation
-  multiFileEndpoint: false,
   defaultParameters,
 } as const;
 
@@ -28,4 +28,4 @@ export const useRepairOperation = () => {
     filePrefix: t('repair.filenamePrefix', 'repaired') + '_',
     getErrorMessage: createStandardErrorHandler(t('repair.error.failed', 'An error occurred while repairing the PDF.'))
   });
-};
+};

frontend/src/hooks/tools/sanitize/useSanitizeOperation.ts

@@ -1,5 +1,5 @@
 import { useTranslation } from 'react-i18next';
-import { useToolOperation } from '../shared/useToolOperation';
+import { ToolType, useToolOperation } from '../shared/useToolOperation';
 import { createStandardErrorHandler } from '../../../utils/toolErrorHandler';
 import { SanitizeParameters, defaultParameters } from './useSanitizeParameters';
 
@@ -21,9 +21,10 @@ export const buildSanitizeFormData = (parameters: SanitizeParameters, file: File
 
 // Static configuration object
 export const sanitizeOperationConfig = {
+  toolType: ToolType.singleFile,
+  buildFormData: buildSanitizeFormData,
   operationType: 'sanitize',
   endpoint: '/api/v1/security/sanitize-pdf',
-  buildFormData: buildSanitizeFormData,
   filePrefix: 'sanitized_', // Will be overridden in hook with translation
   multiFileEndpoint: false,
   defaultParameters,

frontend/src/hooks/tools/shared/useToolOperation.ts

@@ -12,6 +12,12 @@ import { ResponseHandler } from '../../../utils/toolResponseProcessor';
 // Re-export for backwards compatibility
 export type { ProcessingProgress, ResponseHandler };
 
+export enum ToolType {
+  singleFile,
+  multiFile,
+  custom,
+}
+
 /**
  * Configuration for tool operations defining processing behavior and API integration.
  *
@@ -20,45 +26,16 @@ export type { ProcessingProgress, ResponseHandler };
  * 2. Multi-file tools: multiFileEndpoint: true, single API call with all files
  * 3. Complex tools: customProcessor handles all processing logic
  */
-export interface ToolOperationConfig<TParams = void> {
+interface BaseToolOperationConfig<TParams> {
   /** Operation identifier for tracking and logging */
   operationType: string;
 
-  /**
-   * API endpoint for the operation. Can be static string or function for dynamic routing.
-   * Not used when customProcessor is provided.
-   */
-  endpoint: string | ((params: TParams) => string);
-
-  /**
-   * Builds FormData for API request. Signature determines processing approach:
-   * - (params, file: File) => FormData: Single-file processing
-   * - (params, files: File[]) => FormData: Multi-file processing
-   * Not used when customProcessor is provided.
-   */
-  buildFormData: ((params: TParams, file: File) => FormData) | ((params: TParams, files: File[]) => FormData); /* FIX ME */
-
   /** Prefix added to processed filenames (e.g., 'compressed_', 'split_') */
   filePrefix: string;
 
-  /**
-   * Whether this tool uses backends that accept MultipartFile[] arrays.
-   * - true: Single API call with all files (backend uses MultipartFile[])
-   * - false/undefined: Individual API calls per file (backend uses single MultipartFile)
-   * Ignored when customProcessor is provided.
-   */
-  multiFileEndpoint?: boolean;
-
   /** How to handle API responses (e.g., ZIP extraction, single file response) */
   responseHandler?: ResponseHandler;
 
-  /**
-   * Custom processing logic that completely bypasses standard file processing.
-   * When provided, tool handles all API calls, response processing, and file creation.
-   * Use for tools with complex routing logic or non-standard processing requirements.
-   */
-  customProcessor?: (params: TParams, files: File[]) => Promise<File[]>;
-
   /** Extract user-friendly error messages from API errors */
   getErrorMessage?: (error: any) => string;
 
@@ -66,6 +43,49 @@ export interface ToolOperationConfig<TParams = void> {
   defaultParameters?: TParams;
 }
 
+export interface SingleFileToolOperationConfig<TParams> extends BaseToolOperationConfig<TParams> {
+  /** This tool processes one file at a time. */
+  toolType: ToolType.singleFile;
+
+  /** Builds FormData for API request. */
+  buildFormData: ((params: TParams, file: File) => FormData);
+
+  /** API endpoint for the operation. Can be static string or function for dynamic routing. */
+  endpoint: string | ((params: TParams) => string);
+
+  customProcessor?: undefined;
+}
+
+export interface MultiFileToolOperationConfig<TParams> extends BaseToolOperationConfig<TParams> {
+  /** This tool processes multiple files at once. */
+  toolType: ToolType.multiFile;
+
+  /** Builds FormData for API request. */
+  buildFormData: ((params: TParams, files: File[]) => FormData);
+
+  /** API endpoint for the operation. Can be static string or function for dynamic routing. */
+  endpoint: string | ((params: TParams) => string);
+
+  customProcessor?: undefined;
+}
+
+export interface CustomToolOperationConfig<TParams> extends BaseToolOperationConfig<TParams> {
+  /** This tool has custom behaviour. */
+  toolType: ToolType.custom;
+
+  buildFormData?: undefined;
+  endpoint?: undefined;
+
+  /**
+   * Custom processing logic that completely bypasses standard file processing.
+   * This tool handles all API calls, response processing, and file creation.
+   * Use for tools with complex routing logic or non-standard processing requirements.
+   */
+  customProcessor: (params: TParams, files: File[]) => Promise<File[]>;
+}
+
+export type ToolOperationConfig<TParams = void> = SingleFileToolOperationConfig<TParams> | MultiFileToolOperationConfig<TParams> | CustomToolOperationConfig<TParams>;
+
 /**
  * Complete tool operation interface with execution capability
  */
@@ -103,7 +123,7 @@ export { createStandardErrorHandler } from '../../../utils/toolErrorHandler';
  * @param config - Tool operation configuration
  * @returns Hook interface with state and execution methods
  */
-export const useToolOperation = <TParams = void>(
+export const useToolOperation = <TParams>(
   config: ToolOperationConfig<TParams>
 ): ToolOperationHook<TParams> => {
   const { t } = useTranslation();
@@ -143,15 +163,28 @@ export const useToolOperation = <TParams = void>(
     try {
       let processedFiles: File[];
 
-      if (config.customProcessor) {
-        actions.setStatus('Processing files...');
-        processedFiles = await config.customProcessor(params, validFiles);
-      } else {
-        // Use explicit multiFileEndpoint flag to determine processing approach
-        if (config.multiFileEndpoint) {
+      switch (config.toolType) {
+        case ToolType.singleFile:
+          // Individual file processing - separate API call per file
+          const apiCallsConfig: ApiCallsConfig<TParams> = {
+            endpoint: config.endpoint,
+            buildFormData: config.buildFormData,
+            filePrefix: config.filePrefix,
+            responseHandler: config.responseHandler
+          };
+          processedFiles = await processFiles(
+            params,
+            validFiles,
+            apiCallsConfig,
+            actions.setProgress,
+            actions.setStatus
+          );
+          break;
+
+        case ToolType.multiFile:
           // Multi-file processing - single API call with all files
           actions.setStatus('Processing files...');
-          const formData = (config.buildFormData as (params: TParams, files: File[]) => FormData)(params, validFiles);
+          const formData = config.buildFormData(params, validFiles);
           const endpoint = typeof config.endpoint === 'function' ? config.endpoint(params) : config.endpoint;
 
           const response = await axios.post(endpoint, formData, { responseType: 'blob' });
@@ -160,7 +193,7 @@ export const useToolOperation = <TParams = void>(
           if (config.responseHandler) {
             // Use custom responseHandler for multi-file (handles ZIP extraction)
             processedFiles = await config.responseHandler(response.data, validFiles);
-          } else if (response.data.type === 'application/pdf' || 
+          } else if (response.data.type === 'application/pdf' ||
                      (response.headers && response.headers['content-type'] === 'application/pdf')) {
             // Single PDF response (e.g. split with merge option) - use original filename
             const originalFileName = validFiles[0]?.name || 'document.pdf';
@@ -175,22 +208,12 @@ export const useToolOperation = <TParams = void>(
               processedFiles = await extractAllZipFiles(response.data);
             }
           }
-        } else {
-          // Individual file processing - separate API call per file
-          const apiCallsConfig: ApiCallsConfig<TParams> = {
-            endpoint: config.endpoint,
-            buildFormData: config.buildFormData as (params: TParams, file: File) => FormData,
-            filePrefix: config.filePrefix,
-            responseHandler: config.responseHandler
-          };
-          processedFiles = await processFiles(
-            params,
-            validFiles,
-            apiCallsConfig,
-            actions.setProgress,
-            actions.setStatus
-          );
-        }
+          break;
+
+        case ToolType.custom:
+          actions.setStatus('Processing files...');
+          processedFiles = await config.customProcessor(params, validFiles);
+          break;
       }
 
       if (processedFiles.length > 0) {

frontend/src/hooks/tools/singleLargePage/useSingleLargePageOperation.ts

@@ -1,5 +1,5 @@
 import { useTranslation } from 'react-i18next';
-import { useToolOperation } from '../shared/useToolOperation';
+import { ToolType, useToolOperation } from '../shared/useToolOperation';
 import { createStandardErrorHandler } from '../../../utils/toolErrorHandler';
 import { SingleLargePageParameters, defaultParameters } from './useSingleLargePageParameters';
 
@@ -12,11 +12,11 @@ export const buildSingleLargePageFormData = (parameters: SingleLargePageParamete
 
 // Static configuration object
 export const singleLargePageOperationConfig = {
+  toolType: ToolType.singleFile,
+  buildFormData: buildSingleLargePageFormData,
   operationType: 'single-large-page',
   endpoint: '/api/v1/general/pdf-to-single-page',
-  buildFormData: buildSingleLargePageFormData,
   filePrefix: 'single_page_', // Will be overridden in hook with translation
-  multiFileEndpoint: false,
   defaultParameters,
 } as const;
 
@@ -28,4 +28,4 @@ export const useSingleLargePageOperation = () => {
     filePrefix: t('pdfToSinglePage.filenamePrefix', 'single_page') + '_',
     getErrorMessage: createStandardErrorHandler(t('pdfToSinglePage.error.failed', 'An error occurred while converting to single page.'))
   });
-};
+};

frontend/src/hooks/tools/split/useSplitOperation.ts

@@ -1,5 +1,5 @@
 import { useTranslation } from 'react-i18next';
-import { useToolOperation } from '../shared/useToolOperation';
+import { ToolType, useToolOperation } from '../shared/useToolOperation';
 import { createStandardErrorHandler } from '../../../utils/toolErrorHandler';
 import { SplitParameters, defaultParameters } from './useSplitParameters';
 import { SPLIT_MODES } from '../../../constants/splitConstants';
@@ -57,11 +57,11 @@ export const getSplitEndpoint = (parameters: SplitParameters): string => {
 
 // Static configuration object
 export const splitOperationConfig = {
+  toolType: ToolType.multiFile,
+  buildFormData: buildSplitFormData,
   operationType: 'splitPdf',
   endpoint: getSplitEndpoint,
-  buildFormData: buildSplitFormData,
   filePrefix: 'split_',
-  multiFileEndpoint: true, // Single API call with all files
   defaultParameters,
 } as const;
 

frontend/src/hooks/tools/unlockPdfForms/useUnlockPdfFormsOperation.ts

@@ -1,5 +1,5 @@
 import { useTranslation } from 'react-i18next';
-import { useToolOperation } from '../shared/useToolOperation';
+import { ToolType, useToolOperation } from '../shared/useToolOperation';
 import { createStandardErrorHandler } from '../../../utils/toolErrorHandler';
 import { UnlockPdfFormsParameters, defaultParameters } from './useUnlockPdfFormsParameters';
 
@@ -12,11 +12,11 @@ export const buildUnlockPdfFormsFormData = (parameters: UnlockPdfFormsParameters
 
 // Static configuration object
 export const unlockPdfFormsOperationConfig = {
+  toolType: ToolType.singleFile,
+  buildFormData: buildUnlockPdfFormsFormData,
   operationType: 'unlock-pdf-forms',
   endpoint: '/api/v1/misc/unlock-pdf-forms',
-  buildFormData: buildUnlockPdfFormsFormData,
   filePrefix: 'unlocked_forms_', // Will be overridden in hook with translation
-  multiFileEndpoint: false,
   defaultParameters,
 } as const;
 
@@ -28,4 +28,4 @@ export const useUnlockPdfFormsOperation = () => {
     filePrefix: t('unlockPDFForms.filenamePrefix', 'unlocked_forms') + '_',
     getErrorMessage: createStandardErrorHandler(t('unlockPDFForms.error.failed', 'An error occurred while unlocking PDF forms.'))
   });
-};
+};

frontend/src/utils/automationExecutor.ts

@@ -4,14 +4,15 @@ import { AutomationConfig, AutomationExecutionCallbacks } from '../types/automat
 import { AUTOMATION_CONSTANTS } from '../constants/automation';
 import { AutomationFileProcessor } from './automationFileProcessor';
 import { ResourceManager } from './resourceManager';
+import { ToolType } from '../hooks/tools/shared/useToolOperation';
 
 
 /**
  * Execute a tool operation directly without using React hooks
  */
 export const executeToolOperation = async (
-  operationName: string, 
-  parameters: any, 
+  operationName: string,
+  parameters: any,
   files: File[],
   toolRegistry: ToolRegistry
 ): Promise<File[]> => {
@@ -22,14 +23,14 @@ export const executeToolOperation = async (
  * Execute a tool operation with custom prefix
  */
 export const executeToolOperationWithPrefix = async (
-  operationName: string, 
-  parameters: any, 
+  operationName: string,
+  parameters: any,
   files: File[],
   toolRegistry: ToolRegistry,
   filePrefix: string = AUTOMATION_CONSTANTS.FILE_PREFIX
 ): Promise<File[]> => {
   console.log(`🔧 Executing tool: ${operationName}`, { parameters, fileCount: files.length });
-  
+
   const config = toolRegistry[operationName]?.operationConfig;
   if (!config) {
     console.error(`❌ Tool operation not supported: ${operationName}`);
@@ -47,17 +48,17 @@ export const executeToolOperationWithPrefix = async (
       return resultFiles;
     }
 
-    if (config.multiFileEndpoint) {
+    if (config.toolType === ToolType.multiFile) {
       // Multi-file processing - single API call with all files
-      const endpoint = typeof config.endpoint === 'function' 
-        ? config.endpoint(parameters) 
+      const endpoint = typeof config.endpoint === 'function'
+        ? config.endpoint(parameters)
         : config.endpoint;
-      
+
       console.log(`🌐 Making multi-file request to: ${endpoint}`);
       const formData = (config.buildFormData as (params: any, files: File[]) => FormData)(parameters, files);
       console.log(`📤 FormData entries:`, Array.from(formData.entries()));
-      
-      const response = await axios.post(endpoint, formData, { 
+
+      const response = await axios.post(endpoint, formData, {
         responseType: 'blob',
         timeout: AUTOMATION_CONSTANTS.OPERATION_TIMEOUT
       });
@@ -66,7 +67,7 @@ export const executeToolOperationWithPrefix = async (
 
       // Multi-file responses are typically ZIP files, but may be single files (e.g. split with merge=true)
       let result;
-      if (response.data.type === 'application/pdf' || 
+      if (response.data.type === 'application/pdf' ||
           (response.headers && response.headers['content-type'] === 'application/pdf')) {
         // Single PDF response (e.g. split with merge option) - use original filename
         const originalFileName = files[0]?.name || 'document.pdf';
@@ -80,19 +81,18 @@ export const executeToolOperationWithPrefix = async (
         // ZIP response
         result = await AutomationFileProcessor.extractAutomationZipFiles(response.data);
       }
-      
+
       if (result.errors.length > 0) {
         console.warn(`⚠️ File processing warnings:`, result.errors);
       }
-      
       // Apply prefix to files, replacing any existing prefix
-      const processedFiles = filePrefix 
+      const processedFiles = filePrefix
         ? result.files.map(file => {
             const nameWithoutPrefix = file.name.replace(/^[^_]*_/, '');
             return new File([file], `${filePrefix}${nameWithoutPrefix}`, { type: file.type });
           })
         : result.files;
-      
+
       console.log(`📁 Processed ${processedFiles.length} files from response`);
       return processedFiles;
 
@@ -100,18 +100,18 @@ export const executeToolOperationWithPrefix = async (
       // Single-file processing - separate API call per file
       console.log(`🔄 Processing ${files.length} files individually`);
       const resultFiles: File[] = [];
-      
+
       for (let i = 0; i < files.length; i++) {
         const file = files[i];
-        const endpoint = typeof config.endpoint === 'function' 
-          ? config.endpoint(parameters) 
+        const endpoint = typeof config.endpoint === 'function'
+          ? config.endpoint(parameters)
           : config.endpoint;
-        
+
         console.log(`🌐 Making single-file request ${i+1}/${files.length} to: ${endpoint} for file: ${file.name}`);
         const formData = (config.buildFormData as (params: any, file: File) => FormData)(parameters, file);
         console.log(`📤 FormData entries:`, Array.from(formData.entries()));
-        
-        const response = await axios.post(endpoint, formData, { 
+
+        const response = await axios.post(endpoint, formData, {
           responseType: 'blob',
           timeout: AUTOMATION_CONSTANTS.OPERATION_TIMEOUT
         });
@@ -119,9 +119,9 @@ export const executeToolOperationWithPrefix = async (
         console.log(`📥 Response ${i+1} status: ${response.status}, size: ${response.data.size} bytes`);
 
         // Create result file with automation prefix
-        
+
         const resultFile = ResourceManager.createResultFile(
-          response.data, 
+          response.data,
           file.name,
           filePrefix
         );
@@ -143,7 +143,7 @@ export const executeToolOperationWithPrefix = async (
  * Execute an entire automation sequence
  */
 export const executeAutomationSequence = async (
-  automation: any, 
+  automation: any,
   initialFiles: File[],
   toolRegistry: ToolRegistry,
   onStepStart?: (stepIndex: number, operationName: string) => void,
@@ -153,7 +153,7 @@ export const executeAutomationSequence = async (
   console.log(`🚀 Starting automation sequence: ${automation.name || 'Unnamed'}`);
   console.log(`📁 Initial files: ${initialFiles.length}`);
   console.log(`🔧 Operations: ${automation.operations?.length || 0}`);
-  
+
   if (!automation?.operations || automation.operations.length === 0) {
     throw new Error('No operations in automation');
   }
@@ -163,26 +163,26 @@ export const executeAutomationSequence = async (
 
   for (let i = 0; i < automation.operations.length; i++) {
     const operation = automation.operations[i];
-    
+
     console.log(`📋 Step ${i + 1}/${automation.operations.length}: ${operation.operation}`);
     console.log(`📄 Input files: ${currentFiles.length}`);
     console.log(`⚙️ Parameters:`, operation.parameters || {});
-    
+
     try {
       onStepStart?.(i, operation.operation);
-      
+
       const resultFiles = await executeToolOperationWithPrefix(
-        operation.operation, 
-        operation.parameters || {}, 
+        operation.operation,
+        operation.parameters || {},
         currentFiles,
         toolRegistry,
         i === automation.operations.length - 1 ? automationPrefix : '' // Only add prefix to final step
       );
-      
+
       console.log(`✅ Step ${i + 1} completed: ${resultFiles.length} result files`);
       currentFiles = resultFiles;
       onStepComplete?.(i, resultFiles);
-      
+
     } catch (error: any) {
       console.error(`❌ Step ${i + 1} failed:`, error);
       onStepError?.(i, error.message);
@@ -192,4 +192,4 @@ export const executeAutomationSequence = async (
 
   console.log(`🎉 Automation sequence completed: ${currentFiles.length} final files`);
   return currentFiles;
-};
+};