({\n id: 1, // DataService ID from BIZUIT Dashboard\n parameters: [\n { name: 'typename', value: 'Motivos de Rechazo' }\n ]\n}, token)\n\nif (result.success) {\n console.log('Rejection types:', result.data)\n}\n\n// Execute multiple queries in parallel\nconst [suppliers, statuses] = await sdk.dataService.executeMany([\n { id: 101, parameters: [] }, // Suppliers\n { id: 102, parameters: [] } // Statuses\n], token)\n\n// Create parameters helper\nconst params = sdk.dataService.createParameters([\n { name: 'customerId', value: 'ALFKI' },\n { name: 'year', value: 2024 }\n])\n\n// Force fresh query (skip cache)\nconst liveData = await sdk.dataService.execute({\n id: 100,\n parameters: [],\n withoutCache: true // Skip cache\n}, token)\n```\n\n**When to use DataService:**\n- ✅ Combo box data (rejection types, status lists)\n- ✅ Reference tables (countries, categories)\n- ✅ Read-only reports and dashboards\n- ✅ Autocomplete suggestions\n\n**When NOT to use DataService:**\n- ❌ Business logic execution (use `process.raiseEvent()`)\n- ❌ Data updates (use processes)\n- ❌ Workflow steps (use processes)\n\nSee [Example 7: DataService Queries](./docs/examples/example7-dataservice-queries.md) for complete usage examples.\n\n### BizuitTaskService ✨ NEW in v2.3.0\n\nRetrieve user task lists based on Bizuit BPM permissions. Perfect for building task management UIs, dashboards, and work queues.\n\n**Key Features:**\n- ✅ Automatic JSON flattening - Clean, flat objects for easy rendering\n- ✅ User-friendly property names - Access columns by display name (e.g., `task['CLIENTE']`)\n- ✅ Pagination support - Handle large task lists efficiently\n- ✅ Process metadata - Get all processes with activities and start points\n- ✅ Task filtering - Search by process, activity, date range, locked state\n\n```typescript\n// Get all processes available to user\nconst processes = await sdk.tasks.getProcesses(token)\n\nprocesses.forEach(process => {\n console.log('Process:', process.workflowDisplayName)\n console.log('Start points:', process.activities.filter(a => a.isStartPoint))\n console.log('Activities:', process.activities.filter(a => !a.isStartPoint))\n})\n\n// Search for task instances with pagination\nconst result = await sdk.tasks.searchTasks({\n ProcessName: 'TestWix',\n ActivityName: 'userInteractionActivity1',\n pageNumber: 1,\n pageSize: 20,\n DateFrom: '2025-01-01',\n DateTo: '2025-12-31',\n LockedState: -1 // -1 = all, 0 = unlocked, 1 = locked\n}, token)\n\nconsole.log('Total tasks:', result.instancesTotalCount[0]?.count)\nconsole.log('Instances:', result.instances.length)\n\n// Access instances with flattened JSON structure\nresult.instances.forEach(instance => {\n // Standard properties\n console.log('Instance ID:', instance.instanceId)\n console.log('Status:', instance.locked ? 'Locked' : 'Available')\n console.log('Locked by:', instance.lockedBy)\n\n // Dynamic columns with user-friendly names (automatically flattened)\n console.log('Cliente:', instance['CLIENTE'])\n console.log('Descripción:', instance['Descripción'])\n console.log('Versión:', instance['Versión'])\n console.log('Usuario:', instance['Último ejecutado por'])\n console.log('Fecha:', instance['Fecha Ejecución'])\n console.log('Tiempo:', instance['Tiempo Transcurrido'])\n})\n```\n\n**Before/After JSON Transformation:**\n\n```typescript\n// ❌ RAW API Response (complex structure)\n{\n \"instanceId\": \"abc-123\",\n \"locked\": false,\n \"lockedBy\": \"\",\n \"eventName\": \"TestWix\", // Removed by SDK\n \"activityName\": \"activity1\", // Removed by SDK\n \"instanceDescription\": \"...\", // Removed by SDK\n \"columnDefinitionValues\": [ // Removed by SDK (flattened)\n { \"columnName\": \"xCol_159307d8\", \"value\": \"ACME Corp\" },\n { \"columnName\": \"xCol_234abcd\", \"value\": \"Producto X\" }\n ]\n}\n\n// ✅ SDK Returns (clean, flat structure)\n{\n \"instanceId\": \"abc-123\",\n \"locked\": false,\n \"lockedBy\": \"\",\n \"CLIENTE\": \"ACME Corp\", // User-friendly property name!\n \"Descripción\": \"Producto X\" // Direct access via headerText\n}\n```\n\n**All TaskService Methods:**\n\n```typescript\n// Get all processes\nconst processes = await sdk.tasks.getProcesses(token)\n\n// Get specific process details\nconst processDetails = await sdk.tasks.getProcessDetails('TestWix', token)\n\n// Search tasks (with pagination)\nconst tasks = await sdk.tasks.searchTasks({\n ProcessName: 'TestWix',\n ActivityName: 'userInteractionActivity1',\n pageNumber: 1,\n pageSize: 20\n}, token)\n\n// Get task count only\nconst count = await sdk.tasks.getTaskCount('TestWix', 'activity1', token)\n\n// Get all start points across processes\nconst startPoints = await sdk.tasks.getStartPoints(token)\n\n// Get all activities (non-start points)\nconst activities = await sdk.tasks.getActivities(token)\n```\n\n**Building a Task List UI:**\n\n```typescript\nimport { useBizuitSDK } from '@tyconsa/bizuit-form-sdk'\nimport { useState, useEffect } from 'react'\n\nfunction TaskListDemo() {\n const sdk = useBizuitSDK()\n const [processes, setProcesses] = useState([])\n const [tasks, setTasks] = useState([])\n const [columnDefinitions, setColumnDefinitions] = useState([])\n\n // Load processes on mount\n useEffect(() => {\n loadProcesses()\n }, [])\n\n const loadProcesses = async () => {\n const data = await sdk.tasks.getProcesses(token)\n setProcesses(data)\n }\n\n const loadTasks = async (processName, activityName) => {\n const response = await sdk.tasks.searchTasks({\n ProcessName: processName,\n ActivityName: activityName,\n pageNumber: 1,\n pageSize: 20\n }, token)\n\n // Extract column definitions from events metadata\n const eventActivity = response.events\n .find(e => e.eventName === processName)\n ?.activities.find(a => a.activityName === activityName)\n\n setColumnDefinitions(eventActivity?.columnsDefinitions || [])\n setTasks(response.instances)\n }\n\n return (\n \n {/* Process selector */}\n
\n\n {/* Task table with dynamic columns */}\n
\n \n \n | Estado | \n Instance ID | \n {columnDefinitions.map(col => (\n {col.headerText} | \n ))}\n
\n \n \n {tasks.map(task => (\n \n | {task.locked ? '🔒 Bloqueado' : '✅ Disponible'} | \n {task.instanceId.substring(0, 8)}... | \n {columnDefinitions.map(col => (\n \n {task[col.headerText] || '-'}\n | \n ))}\n
\n ))}\n \n
\n
\n
All My Tasks ({allTasks.length})
\n {allTasks.map(task => (\n
\n {task.instanceId}\n {task.locked && 🔒 Locked by {task.lockedBy}}\n
\n ))}\n
\n
\n setFilters({...filters, dateFrom: e.target.value})}\n />\n setFilters({...filters, dateTo: e.target.value})}\n />\n setFilters({...filters, lockedState: Number(e.target.value)})}\n >\n \n \n \n \n \n
\n\n
\n {/* Render tasks */}\n
\n
\n
\n {tasks.map(task => (\n
{/* task card */}
\n ))}\n
\n\n {hasMore && (\n
\n )}\n
\n {processes.map(process => (\n
\n
{process.workflowDisplayName}
\n {process.activities.map(activity => {\n const key = `${process.name}-${activity.activityName}`\n const count = taskCounts[key] || 0\n\n return (\n \n )\n })}\n \n ))}\n
\n {/* Left panel: Start new processes */}\n
\n\n {/* Main area: Pending tasks */}\n
\n My Pending Tasks
\n {activities.map(activity => (\n \n
{activity.processDisplayName} - {activity.displayName}
\n {/* Load tasks for this activity */}\n \n ))}\n \n
\n {/* Fully typed task rendering */}\n
\n )\n}\n```\n\n---\n\n## Process Workflows\n\n### Understanding `initialize()`\n\nThe `initialize()` method is used to **obtain the initial or current state of a process/instance** before presenting a form to the user. It returns:\n\n- **Parameters**: Process fields with their default or current values\n- **Variables**: Available process variables\n- **Metadata**: `processName`, `version`, `instanceId` (if continuing)\n- **Activities**: History of completed activities (optional)\n\n### Workflow 1: Starting a New Process\n\n```typescript\n// Step 1: Get process definition (optional but recommended)\nconst processData = await sdk.process.initialize({\n processName: 'ExpenseRequest',\n version: '1.0.0',\n token: authToken,\n userName: 'user@company.com'\n})\n\n// processData contains:\n// {\n// parameters: [\n// { name: 'amount', value: null, type: 'SingleValue', direction: 'In' },\n// { name: 'description', value: null, type: 'SingleValue', direction: 'In' },\n// { name: 'category', value: 'General', type: 'SingleValue', direction: 'In' } // with default value\n// ],\n// variables: [...],\n// processName: 'ExpenseRequest',\n// version: '1.0.0'\n// }\n\n// Step 2: Render form based on processData.parameters\n// User fills in the form fields...\n\n// Step 3: Start the process with submitted values\nconst result = await sdk.process.start({\n processName: 'ExpenseRequest',\n processVersion: '1.0.0',\n parameters: [\n { name: 'amount', value: '5000', type: 'SingleValue', direction: 'In' },\n { name: 'description', value: 'Equipment purchase', type: 'SingleValue', direction: 'In' },\n { name: 'category', value: 'Hardware', type: 'SingleValue', direction: 'In' }\n ]\n}, undefined, authToken)\n\n// result contains:\n// {\n// instanceId: 'instance-uuid',\n// status: 'Waiting', // or 'Completed'\n// parameters: [...] // updated output parameters\n// }\n\nconsole.log(`Process started with ID: ${result.instanceId}`)\n```\n\n### Workflow 2: Continuing an Existing Instance\n\n```typescript\n// Scenario: User has a pending task (instanceId = 'abc-123')\n\n// Step 1: Get current state of the instance\nconst processData = await sdk.process.initialize({\n processName: 'ExpenseRequest',\n instanceId: 'abc-123', // ⭐ Key: include instanceId\n activityName: 'ManagerApproval', // optional: specific activity\n token: authToken,\n userName: 'manager@company.com'\n})\n\n// processData contains CURRENT values of the instance:\n// {\n// parameters: [\n// { name: 'amount', value: '5000', type: 'SingleValue', direction: 'In' },\n// { name: 'description', value: 'Equipment purchase', type: 'SingleValue', direction: 'In' },\n// { name: 'approved', value: null, type: 'SingleValue', direction: 'Out' }, // new field for this activity\n// { name: 'comments', value: null, type: 'SingleValue', direction: 'Out' }\n// ],\n// instanceId: 'abc-123',\n// processName: 'ExpenseRequest'\n// }\n\n// Step 2: Render form with existing values pre-populated\n// User completes new fields (approved, comments)...\n\n// Step 3: Continue the instance with updated values\nconst result = await sdk.process.continue({\n processName: 'ExpenseRequest',\n instanceId: 'abc-123', // ⭐ Key: instanceId to continue\n parameters: [\n // Keep existing values + add new ones\n { name: 'amount', value: '5000', type: 'SingleValue', direction: 'In' },\n { name: 'description', value: 'Equipment purchase', type: 'SingleValue', direction: 'In' },\n { name: 'approved', value: 'true', type: 'SingleValue', direction: 'Out' },\n { name: 'comments', value: 'Approved with observations', type: 'SingleValue', direction: 'Out' }\n ]\n}, undefined, authToken)\n\n// result contains:\n// {\n// instanceId: 'abc-123',\n// status: 'Completed', // or 'Waiting' if more activities exist\n// parameters: [...] // updated parameters\n// }\n```\n\n### Workflow 3: With Pessimistic Locking (Concurrent Editing)\n\n```typescript\n// Scenario: Prevent two users from editing the same instance simultaneously\n\n// Step 1: Acquire lock\nconst lockResult = await sdk.process.acquireLock({\n instanceId: 'abc-123',\n token: authToken\n})\n\nconst { sessionToken, processData } = lockResult\n\n// Step 2: Use sessionToken to get data\nconst data = await sdk.process.initialize({\n processName: 'ExpenseRequest',\n instanceId: 'abc-123',\n token: authToken,\n sessionToken: sessionToken // ⭐ Identifies the locked session\n})\n\n// Step 3: User edits the form...\n\n// Step 4: Continue with the same session\nconst result = await sdk.process.continue({\n processName: 'ExpenseRequest',\n instanceId: 'abc-123',\n parameters: [...]\n}, undefined, authToken)\n\n// Step 5: Release lock\nawait sdk.process.releaseLock({\n instanceId: 'abc-123',\n sessionToken: sessionToken\n})\n```\n\n### Method Comparison\n\n| Method | When to Use | Requires instanceId |\n|--------|-------------|---------------------|\n| **`initialize()`** | Get initial/current state before showing form | ❌ For new process
✅ For continuing |\n| **`start()`** | Start new process instance | ❌ No (generates new one) |\n| **`continue()`** | Continue existing instance at specific activity | ✅ Required |\n| **`getParameters()`** | Get only parameter definitions (no values) | ❌ No |\n\n### Benefits of Using `initialize()`\n\n1. **Pre-population**: Get default or current values\n2. **Validation**: Know which parameters are required\n3. **Metadata**: Receive context information (version, variables)\n4. **Consistency**: Ensure form shows correct instance state\n\n### ParameterParser Utilities\n\n```typescript\nimport { ParameterParser } from '@bizuit/form-sdk'\n\n// Flatten parameters for form\nconst formData = ParameterParser.flattenParameters(parameters)\n\n// Convert form data back to parameters\nconst updatedParams = ParameterParser.mergeWithFormData(parameters, formData)\n\n// Get only input parameters\nconst inputs = ParameterParser.getInputParameters(parameters)\n\n// Validate required fields\nconst validation = ParameterParser.validateRequired(parameters, formData)\nif (!validation.valid) {\n console.log('Missing fields:', validation.missing)\n}\n```\n\n### Selective Parameter Mapping (New in v1.0.2)\n\nThe `buildParameters()` utility allows you to selectively map form fields to specific Bizuit parameters/variables, instead of sending all form data. This is useful when you only want to send specific fields or need to transform values before sending.\n\n```typescript\nimport { buildParameters, type IParameterMapping } from '@tyconsa/bizuit-form-sdk'\n\n// Simple mapping: only send specific fields\nconst mapping = {\n 'empleado': { parameterName: 'pEmpleado' },\n 'monto': { parameterName: 'pMonto' },\n 'categoria': { parameterName: 'pCategoria' },\n}\n\nconst formData = {\n empleado: 'Juan Pérez',\n monto: '1500.50',\n categoria: 'Viajes',\n // These fields won't be included:\n comentarios: 'Internal notes',\n prioridad: 'Alta',\n}\n\nconst parameters = buildParameters(mapping, formData)\n// Result: only 3 parameters (empleado, monto, categoria)\n```\n\n**With value transformations:**\n\n```typescript\nconst mapping = {\n 'empleado': {\n parameterName: 'pEmpleado',\n transform: (val) => val.toUpperCase(),\n },\n 'monto': {\n parameterName: 'pMonto',\n transform: (val) => parseFloat(val).toFixed(2),\n },\n}\n\nconst parameters = buildParameters(mapping, formData)\n// empleado will be 'JUAN PÉREZ', monto will be '1500.50'\n```\n\n**Map to variables:**\n\n```typescript\nconst mapping = {\n 'aprobado': {\n parameterName: 'vAprobado',\n isVariable: true,\n transform: (val) => val ? 'SI' : 'NO',\n },\n}\n```\n\n**Specify parameter types and directions:**\n\n```typescript\nconst mapping = {\n 'xmlData': {\n parameterName: 'pXmlData',\n type: 'Xml' as const,\n },\n 'config': {\n parameterName: 'pConfig',\n type: 'ComplexObject' as const,\n direction: 'InOut' as const,\n },\n}\n```\n\n**IParameterMapping Interface:**\n\n```typescript\ninterface IParameterMapping {\n parameterName: string // Bizuit parameter/variable name\n isVariable?: boolean // true for variables, false/undefined for parameters\n transform?: (value: any) => any // Optional value transformation function\n type?: 'SingleValue' | 'Xml' | 'ComplexObject' // Parameter type (default: SingleValue)\n direction?: 'In' | 'Out' | 'InOut' // Parameter direction (default: In)\n}\n```\n\n### formDataToParameters() - Convert All Fields\n\nThe `formDataToParameters()` utility converts **all** form fields to Bizuit parameters. Use this when you want to send everything from your form state.\n\n```typescript\nimport { formDataToParameters } from '@tyconsa/bizuit-form-sdk'\n\nconst formData = {\n pEmpleado: 'Juan Pérez',\n pLegajo: '12345',\n pMonto: '1500.50',\n pCategoria: 'Viajes',\n pAprobado: true,\n pFechaSolicitud: '2025-01-15',\n}\n\n// Convert all fields to parameters\nconst parameters = formDataToParameters(formData)\n\n// Result: Array of IParameter objects\n[\n { name: 'pEmpleado', value: 'Juan Pérez', direction: 'In', type: 'SingleValue' },\n { name: 'pLegajo', value: '12345', direction: 'In', type: 'SingleValue' },\n { name: 'pMonto', value: '1500.50', direction: 'In', type: 'SingleValue' },\n { name: 'pCategoria', value: 'Viajes', direction: 'In', type: 'SingleValue' },\n { name: 'pAprobado', value: true, direction: 'In', type: 'SingleValue' },\n { name: 'pFechaSolicitud', value: '2025-01-15', direction: 'In', type: 'SingleValue' },\n]\n\n// Send to Bizuit\nawait sdk.process.start({\n eventName: 'SolicitudGasto',\n parameters\n}, undefined, token)\n```\n\n**Key differences:**\n\n| Feature | `formDataToParameters()` | `buildParameters()` |\n|---------|-------------------------|---------------------|\n| **Selectivity** | Sends ALL fields | Sends ONLY mapped fields |\n| **Transformation** | No transformations | Supports transform functions |\n| **Use Case** | Simple forms, all data needed | Complex forms, selective fields |\n| **Setup** | Quick, no configuration | Requires mapping definition |\n\n**When to use `formDataToParameters()`:**\n- All form fields should be sent to Bizuit\n- No value transformations needed\n- Simple, straightforward forms\n- Quick prototyping\n\n**When to use `buildParameters()`:**\n- Only specific fields should be sent\n- Need value transformations\n- Multiple form fields map to single parameter\n- Production applications with complex business logic\n\n## React Hooks\n\n### useAuth\n\n```typescript\nconst {\n user,\n isAuthenticated,\n isLoading,\n error,\n validateToken,\n checkFormAuth,\n getUserInfo,\n checkPermissions,\n logout,\n} = useAuth({\n token: 'optional-token',\n userName: 'optional-username',\n autoValidate: true, // Auto-validate token on mount\n})\n```\n\n### useBizuitSDK\n\n```typescript\nconst sdk = useBizuitSDK()\n\n// Access all services\nsdk.auth.validateToken(...)\nsdk.process.initialize(...)\nsdk.instanceLock.lock(...)\n```\n\n## TypeScript Support\n\nAll types and utilities are exported and available:\n\n```typescript\nimport type {\n IBizuitConfig,\n IUserInfo,\n IParameter,\n IProcessData,\n IRaiseEventParams,\n IRaiseEventResult,\n ILockStatus,\n // ... and many more\n} from '@bizuit/form-sdk'\n\n// XML/JSON conversion utilities (v2.1.0+)\nimport { xmlToJson, jsonToXml } from '@tyconsa/bizuit-form-sdk'\n\n// Example: Manual conversion if needed\nconst obj = { raiz: { nombre: 'Test', productos: { producto: [...] } } }\nconst xml = jsonToXml(obj)\nconsole.log(xml)\n// \n// Test\n// \n// ...\n// \n// \n\nconst parsed = xmlToJson(xml)\nconsole.log(parsed) // Back to object\n```\n\n## Error Handling\n\n```typescript\nimport { BizuitError, handleError } from '@bizuit/form-sdk'\n\ntry {\n await sdk.process.start(...)\n} catch (error) {\n const bizuitError = handleError(error)\n\n if (bizuitError.isAuthError()) {\n // Handle authentication error\n } else if (bizuitError.isNetworkError()) {\n // Handle network error\n } else {\n console.error(bizuitError.message)\n }\n}\n```\n\n## 📁 Flexible File Uploads ✨ NEW in v2.4.0\n\nThe SDK now supports **multiple file sources** for uploads, not just browser `File` objects. This makes it easy to upload files from:\n- 📷 **Base64 strings** (camera captures, canvas exports, data URLs)\n- 🎨 **Blob objects** (canvas.toBlob(), fetch responses)\n- 📦 **ArrayBuffer** (binary data, WebSocket transfers)\n- 📂 **Browser File objects** (traditional file inputs)\n\n### Quick Example: Upload Base64 Image\n\n```typescript\nimport { useBizuitSDK } from '@tyconsa/bizuit-form-sdk'\n\nfunction UploadSignature() {\n const sdk = useBizuitSDK()\n\n const handleSubmit = async (signatureBase64: string) => {\n // Create IBizuitFile from base64 string\n const signatureFile = {\n fileName: 'signature.png',\n content: signatureBase64, // Can be data URL or pure base64\n mimeType: 'image/png',\n encoding: 'base64' as const\n }\n\n // Upload directly - SDK handles conversion!\n const result = await sdk.process.start(\n {\n processName: 'DocumentApproval',\n parameters: [\n { name: 'pApproved', value: 'true', type: 'SingleValue', direction: 'In' }\n ],\n files: [signatureFile] // ← IBizuitFile instead of File!\n },\n undefined,\n token\n )\n\n console.log('Uploaded!', result.instanceId)\n }\n\n return \n}\n```\n\n### Supported File Sources\n\n#### 1. Base64 Strings 📷\n\nPerfect for camera captures, canvas exports, or server-provided data:\n\n```typescript\n// From canvas.toDataURL()\nconst dataUrl = canvas.toDataURL('image/jpeg')\nconst file: IBizuitFile = {\n fileName: 'photo.jpg',\n content: dataUrl, // SDK strips \"data:image/jpeg;base64,\" prefix\n mimeType: 'image/jpeg',\n encoding: 'base64'\n}\n\n// Pure base64 string\nconst base64 = 'iVBORw0KGgoAAAANSUhEUgAA...'\nconst file2: IBizuitFile = {\n fileName: 'document.pdf',\n content: base64,\n mimeType: 'application/pdf',\n encoding: 'base64'\n}\n\nawait sdk.process.start({\n processName: 'UploadDocs',\n parameters: [],\n files: [file, file2]\n}, undefined, token)\n```\n\n#### 2. Blob Objects 🎨\n\nPerfect for canvas exports, fetch responses, or binary data:\n\n```typescript\n// From canvas\ncanvas.toBlob(async (blob) => {\n const file: IBizuitFile = {\n fileName: 'drawing.png',\n content: blob!,\n mimeType: 'image/png'\n }\n\n await sdk.process.start({\n processName: 'UploadDrawing',\n parameters: [],\n files: [file]\n }, undefined, token)\n})\n\n// From fetch\nconst response = await fetch('https://example.com/document.pdf')\nconst blob = await response.blob()\n\nconst file: IBizuitFile = {\n fileName: 'remote-doc.pdf',\n content: blob,\n mimeType: blob.type || 'application/pdf'\n}\n```\n\n#### 3. ArrayBuffer 📦\n\nPerfect for binary data, WebSocket transfers, or FileReader results:\n\n```typescript\n// From fetch\nconst response = await fetch('https://example.com/data.bin')\nconst arrayBuffer = await response.arrayBuffer()\n\nconst file: IBizuitFile = {\n fileName: 'data.bin',\n content: arrayBuffer,\n mimeType: 'application/octet-stream'\n}\n\nawait sdk.process.start({\n processName: 'UploadBinary',\n parameters: [],\n files: [file]\n}, undefined, token)\n```\n\n#### 4. Browser File Objects 📂\n\nTraditional file input still works - fully backward compatible:\n\n```typescript\nconst fileInput = document.getElementById('fileInput') as HTMLInputElement\nconst browserFiles = Array.from(fileInput.files || [])\n\n// Old way still works!\nawait sdk.process.start(\n { processName: 'UploadDocs', parameters: [] },\n browserFiles, // File[]\n token\n)\n\n// Or using IBizuitFile wrapper\nconst wrapped: IBizuitFile = {\n fileName: 'document.pdf',\n content: browserFiles[0], // Wrap File in IBizuitFile\n mimeType: browserFiles[0].type\n}\n```\n\n### Mixed File Sources\n\nYou can mix different file sources in the same upload:\n\n```typescript\nconst files = [\n // Browser file\n browserFile,\n\n // Base64 signature\n {\n fileName: 'signature.png',\n content: signatureBase64,\n mimeType: 'image/png',\n encoding: 'base64' as const\n },\n\n // Canvas blob\n {\n fileName: 'drawing.png',\n content: canvasBlob,\n mimeType: 'image/png'\n }\n]\n\nawait sdk.process.start({\n processName: 'SubmitForm',\n parameters: [...],\n files: files // Mix of File and IBizuitFile!\n}, undefined, token)\n```\n\n### Real-World Use Cases\n\n**Camera Capture:**\n```typescript\n// Capture photo and upload as base64\nconst stream = await navigator.mediaDevices.getUserMedia({ video: true })\nconst canvas = document.createElement('canvas')\n// ... capture frame to canvas\nconst base64Image = canvas.toDataURL('image/jpeg')\n\nawait sdk.process.start({\n processName: 'UploadPhoto',\n parameters: [],\n files: [{\n fileName: 'photo.jpg',\n content: base64Image,\n mimeType: 'image/jpeg',\n encoding: 'base64'\n }]\n}, undefined, token)\n```\n\n**Download and Re-upload:**\n```typescript\n// Download from one instance\nconst blob = await sdk.process.downloadDocument(docId, version, token)\n\n// Upload to another instance\nawait sdk.process.start({\n processName: 'CopyDocument',\n parameters: [],\n files: [{\n fileName: 'copied-doc.pdf',\n content: blob,\n mimeType: blob.type\n }]\n}, undefined, token)\n```\n\n**Generate PDF from HTML:**\n```typescript\nimport jsPDF from 'jspdf'\n\nconst doc = new jsPDF()\ndoc.text('Report Content', 10, 10)\nconst pdfBlob = doc.output('blob')\n\nawait sdk.process.start({\n processName: 'SubmitReport',\n parameters: [],\n files: [{\n fileName: 'report.pdf',\n content: pdfBlob,\n mimeType: 'application/pdf'\n }]\n}, undefined, token)\n```\n\n### TypeScript Interface\n\n```typescript\ninterface IBizuitFile {\n fileName: string // Name for uploaded file\n content: File | string | Blob | ArrayBuffer // File content from any source\n mimeType?: string // MIME type (e.g., 'image/png')\n encoding?: 'base64' | 'binary' // Encoding (only for strings)\n}\n\n// Usage in process params\ninterface IStartProcessParams {\n processName: string\n instanceId?: string\n parameters: IParameter[]\n processVersion?: string\n closeOnSuccess?: boolean\n deletedDocuments?: string[]\n files?: File[] | IBizuitFile[] // ← Supports both!\n}\n```\n\n### Continue Operations\n\nThe same flexible file support works for `continue()` operations:\n\n```typescript\nawait sdk.process.continue({\n processName: 'DocumentReview',\n instanceId: 'existing-instance-id',\n parameters: [...],\n files: [\n {\n fileName: 'additional-doc.pdf',\n content: base64String,\n mimeType: 'application/pdf',\n encoding: 'base64'\n }\n ],\n deletedDocuments: ['16', '17'] // Remove old docs\n}, undefined, token)\n```\n\n### Important Notes\n\n✅ **Backward Compatible** - Existing code using `File[]` still works\n✅ **Automatic Conversion** - SDK converts all sources to `File` objects before sending\n✅ **Data URL Detection** - Automatically strips `data:image/png;base64,` prefixes\n✅ **MIME Type Inference** - Uses sensible defaults if not provided\n✅ **Error Handling** - Clear error messages for malformed base64\n\nFor complete examples and HTML test forms, see **[EXAMPLES_FILE_UPLOAD.md](./EXAMPLES_FILE_UPLOAD.md)**.\n\n---\n\n## 📚 Documentation\n\nFor detailed guides and advanced features:\n\n- **[File Upload Examples](./EXAMPLES_FILE_UPLOAD.md)** - Complete guide with 9 examples showing all file upload patterns\n - Base64 string uploads (camera, canvas, data URLs)\n - Blob uploads (canvas.toBlob, fetch responses)\n - ArrayBuffer uploads (binary data, WebSocket)\n - Mixed file sources in same upload\n - Real-world use cases (camera, PDF generation, download/re-upload)\n\n- **[XmlParameter Guide](./XMLPARAMETER_GUIDE.md)** - Complete guide for working with XML parameters using mutable objects\n - XSD auto-template generation\n - Direct property access via Proxy\n - Advanced helper methods (merge, validate, fillFrom, getByPath, setByPath)\n\n- **[XmlParameter Examples](./EXAMPLES_XMLPARAMETER.md)** - 6 real-world examples showing common patterns:\n - Simple forms with validation\n - Complex nested structures\n - Multi-step forms\n - Array manipulation\n - Editing existing instances\n\n## License\n\nMIT\n\n## Support\n\nFor issues and questions, please visit [Bizuit Support](https://bizuit.com/support)\n","readmeFilename":"README.md"}