Feature/v2/shared tool hooks (#4134)

# Description of Changes

<!--
Please provide a summary of the changes, including:

- What was changed
- Why the change was made
- Any challenges encountered

Closes #(issue_number)
-->

---

## Checklist

### General

- [ ] I have read the [Contribution
Guidelines](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/CONTRIBUTING.md)
- [ ] I have read the [Stirling-PDF Developer
Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md)
(if applicable)
- [ ] I have read the [How to add new languages to
Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md)
(if applicable)
- [ ] I have performed a self-review of my own code
- [ ] My changes generate no new warnings

### Documentation

- [ ] I have updated relevant docs on [Stirling-PDF's doc
repo](https://github.com/Stirling-Tools/Stirling-Tools.github.io/blob/main/docs/)
(if functionality has heavily changed)
- [ ] I have read the section [Add New Translation
Tags](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md#add-new-translation-tags)
(for new translation tags only)

### UI Changes (if applicable)

- [ ] Screenshots or videos demonstrating the UI changes are attached
(e.g., as comments or direct attachments in the PR)

### Testing (if applicable)

- [ ] I have tested my changes locally. Refer to the [Testing
Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md#6-testing)
for more details.

---------

Co-authored-by: Reece Browne <[email protected]>

frontend/src/utils/toolErrorHandler.ts

@@ -0,0 +1,33 @@
+/**
+ * Standardized error handling utilities for tool operations
+ */
+
+/**
+ * Default error extractor that follows the standard pattern
+ */
+export const extractErrorMessage = (error: any): string => {
+  if (error.response?.data && typeof error.response.data === 'string') {
+    return error.response.data;
+  }
+  if (error.message) {
+    return error.message;
+  }
+  return 'Operation failed';
+};
+
+/**
+ * Creates a standardized error handler for tool operations
+ * @param fallbackMessage - Message to show when no specific error can be extracted
+ * @returns Error handler function that follows the standard pattern
+ */
+export const createStandardErrorHandler = (fallbackMessage: string) => {
+  return (error: any): string => {
+    if (error.response?.data && typeof error.response.data === 'string') {
+      return error.response.data;
+    }
+    if (error.message) {
+      return error.message;
+    }
+    return fallbackMessage;
+  };
+};

frontend/src/utils/toolOperationTracker.ts

@@ -0,0 +1,28 @@
+import { FileOperation } from '../types/fileContext';
+
+/**
+ * Creates operation tracking data for FileContext integration
+ */
+export const createOperation = <TParams = void>(
+  operationType: string,
+  params: TParams,
+  selectedFiles: File[]
+): { operation: FileOperation; operationId: string; fileId: string } => {
+  const operationId = `${operationType}-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+  const fileId = selectedFiles.map(f => f.name).join(',');
+
+  const operation: FileOperation = {
+    id: operationId,
+    type: operationType,
+    timestamp: Date.now(),
+    fileIds: selectedFiles.map(f => f.name),
+    status: 'pending',
+    metadata: {
+      originalFileName: selectedFiles[0]?.name,
+      parameters: params,
+      fileSize: selectedFiles.reduce((sum, f) => sum + f.size, 0)
+    }
+  };
+
+  return { operation, operationId, fileId };
+};

frontend/src/utils/toolResponseProcessor.ts

@@ -0,0 +1,25 @@
+// Note: This utility should be used with useToolResources for ZIP operations
+
+export type ResponseHandler = (blob: Blob, originalFiles: File[]) => Promise<File[]> | File[];
+
+/**
+ * Processes a blob response into File(s).
+ * - If a tool-specific responseHandler is provided, it is used.
+ * - Otherwise, create a single file using the filePrefix + original name.
+ */
+export async function processResponse(
+  blob: Blob,
+  originalFiles: File[],
+  filePrefix: string,
+  responseHandler?: ResponseHandler
+): Promise<File[]> {
+  if (responseHandler) {
+    const out = await responseHandler(blob, originalFiles);
+    return Array.isArray(out) ? out : [out as unknown as File];
+  }
+
+  const original = originalFiles[0]?.name ?? 'result.pdf';
+  const name = `${filePrefix}${original}`;
+  const type = blob.type || 'application/octet-stream';
+  return [new File([blob], name, { type })];
+}