@gov-cy/govcy-express-services 0.2.16 → 1.0.0-alpha.10

package/src/utils/govcyApiRequest.mjs

@@ -5,12 +5,13 @@ import { logger } from "./govcyLogger.mjs";
  * Utility to handle API communication with retry logic
  * @param {string} method - HTTP method (e.g., 'post', 'get', etc.)
  * @param {string} url - API endpoint URL
- * @param {object} inputData - Payload for the request (optional)
+ * @param {object|FormData} inputData - Payload for the request (optional)
  * @param {boolean} useAccessTokenAuth - Whether to use Authorization header with Bearer token
  * @param {object} user - User object containing access_token (optional)
  * @param {object} headers - Custom headers (optional)
  * @param {number} retries - Number of retry attempts (default: 3)
  * @param {boolean} allowSelfSignedCerts - Whether to allow self-signed certificates (default: false)
+ * @param {array} allowedHTTPStatusCodes - Array of allowed HTTP status codes (default: [200])
  * @returns {Promise<object>} - API response
  */
 export async function govcyApiRequest(
@@ -21,7 +22,8 @@ export async function govcyApiRequest(
     user = null, 
     headers = {}, 
     retries = 3,
-    allowSelfSignedCerts = false
+    allowSelfSignedCerts = false,
+    allowedHTTPStatusCodes = [200]
 ) {
     let attempt = 0;
 
@@ -37,6 +39,14 @@ export async function govcyApiRequest(
         requestHeaders['Authorization'] = `Bearer ${user.access_token}`;
     }
 
+    // If inputData is FormData, for attachments
+    if (inputData instanceof (await import('form-data')).default) {
+        requestHeaders = {
+        ...requestHeaders,
+        ...inputData.getHeaders(), // includes boundary in content-type
+        };
+    }
+
     while (attempt < retries) {
         try {
             logger.debug(`📤 Sending API request (Attempt ${attempt + 1})`, { method, url, inputData, requestHeaders });
@@ -45,11 +55,22 @@ export async function govcyApiRequest(
             const axiosConfig = {
                 method,
                 url,
-                [method?.toLowerCase() === 'get' ? 'params' : 'data']: inputData,
+                ...(inputData instanceof (await import('form-data')).default // If inputData is FormData, for attachments
+                    ? { data: inputData }
+                    : { [method?.toLowerCase() === 'get' ? 'params' : 'data']: inputData }),
                 headers: requestHeaders,
                 timeout: 10000, // 10 seconds timeout
+                // ✅ Treat only these statuses as "resolved" (no throw)
+                validateStatus: (status) => allowedHTTPStatusCodes.includes(status),
             };
 
+            // If inputData is FormData, for attachments
+            if (inputData instanceof (await import('form-data')).default) {
+                axiosConfig.maxContentLength = Infinity;
+                axiosConfig.maxBodyLength = Infinity;
+            }
+
+
             // Add httpsAgent if NOT production to allow self-signed certificates
             // Use per-call config for self-signed certs
             if (allowSelfSignedCerts) {
@@ -60,9 +81,13 @@ export async function govcyApiRequest(
 
             logger.debug(`📥 Received API response`, { status: response.status, data: response.data });
 
-            if (response.status !== 200) {
+            // Validate HTTP status
+            if (!allowedHTTPStatusCodes.includes(response.status)) {
                 throw new Error(`Unexpected HTTP status: ${response.status}`);
             }
+            // if (response.status !== 200) {
+            //     throw new Error(`Unexpected HTTP status: ${response.status}`);
+            // }
             
             // const { Succeeded, ErrorCode, ErrorMessage } = response.data;
             // Normalize to PascalCase regardless of input case
@@ -77,7 +102,7 @@ export async function govcyApiRequest(
                 ErrorMessage,
                 Data,
                 InformationMessage
-            } = response.data;
+            } = response.data ?? {};
 
             const normalized = {
                 Succeeded: Succeeded !== undefined ? Succeeded : succeeded,

package/src/utils/govcyApiResponse.mjs

@@ -0,0 +1,31 @@
+/**
+ * The successResponse function creates a standardized success response object.
+ * 
+ * @param {*} data - The data to be included in the response. 
+ * @returns  {Object} - The success response object.
+ */
+export function successResponse(data = null) {
+  return {
+    Succeeded: true,
+    ErrorCode: 0,
+    ErrorMessage: '',
+    Data: data
+  };
+}
+
+/**
+ * The errorResponse function creates a standardized error response object.
+ * 
+ * @param {int} code - The error code to be included in the response.
+ * @param {string} message - The error message to be included in the response.
+ * @param {Object} data - Additional data to be included in the response.
+ * @returns {Object} - The error response object.
+ */
+export function errorResponse(code = 1, message = 'Unknown error', data = null) {
+  return {
+    Succeeded: false,
+    ErrorCode: code,
+    ErrorMessage: message,
+    Data: data
+  };
+}

package/src/utils/govcyConstants.mjs

@@ -1,4 +1,8 @@
 /**
  * Shared constants for allowed form elements.
  */
-export const ALLOWED_FORM_ELEMENTS = ["textInput", "textArea", "select", "radios", "checkboxes", "datePicker", "dateInput"];
+export const ALLOWED_FORM_ELEMENTS = ["textInput", "textArea", "select", "radios", "checkboxes", "datePicker", "dateInput","fileInput","fileView"];
+export const ALLOWED_FILE_MIME_TYPES = ['application/pdf', 'image/jpeg', 'image/png'];
+export const ALLOWED_FILE_EXTENSIONS = ['pdf', 'jpg', 'jpeg', 'png'];
+export const ALLOWED_FILE_SIZE_MB = 5; // Maximum file size in MB
+export const ALLOWED_MULTER_FILE_SIZE_MB = 10; // Maximum file size in MB

package/src/utils/govcyDataLayer.mjs

@@ -16,6 +16,7 @@
 export function initializeSiteData(store, siteId, pageUrl = null) {
     if (!store.siteData) store.siteData = {};
     if (!store.siteData[siteId]) store.siteData[siteId] = {};
+    if (!store.siteData[siteId].inputData) store.siteData[siteId].loadData = {};
     if (!store.siteData[siteId].inputData) store.siteData[siteId].inputData = {};
     if (!store.siteData[siteId].submissionData) store.siteData[siteId].submissionData = {};
 
@@ -98,6 +99,41 @@ export function storePageData(store, siteId, pageUrl, formData) {
     store.siteData[siteId].inputData[pageUrl]["formData"] = formData;
 }
 
+export function storePageDataElement(store, siteId, pageUrl, elementName, value) {
+    // Ensure session structure is initialized
+    initializeSiteData(store, siteId, pageUrl);
+    
+    // Store the element value
+    store.siteData[siteId].inputData[pageUrl].formData[elementName] = value;
+}
+/**
+ * Stores the page's input data in the data layer
+ *  * 
+ * @param {object} store The session store 
+ * @param {string} siteId The site id
+ * @param {object} loadData The form data to be stored 
+ */
+export function storeSiteInputData(store, siteId, loadData) {
+    // Ensure session structure is initialized
+    initializeSiteData(store, siteId);
+
+    store.siteData[siteId]["inputData"] = loadData;
+}
+
+/**
+ * Stores the page's load data in the data layer
+ *  * 
+ * @param {object} store The session store 
+ * @param {string} siteId The site id
+ * @param {object} loadData The form data to be stored 
+ */
+export function storeSiteLoadData(store, siteId, loadData) {
+    // Ensure session structure is initialized
+    initializeSiteData(store, siteId);
+
+    store.siteData[siteId]["loadData"] = loadData;
+}
+
 /**
  * Stores the site validation errors in the data layer 
  * 
@@ -156,8 +192,11 @@ export function storeSiteSubmissionData(store, siteId, submissionData) {
     // Store the submission data
     store.siteData[siteId].submissionData = submissionData;
       
-      // Clear validation errors from the session
+    // Clear validation errors from the session
     store.siteData[siteId].inputData = {};
+    // Clear presaved/temporary save data
+    store.siteData[siteId].loadData = {}; 
+
 }
 
 
@@ -280,6 +319,37 @@ export function getSiteInputData(store, siteId) {
     return null;
 }
 
+/**
+ * Get the site's load data from the store 
+ * 
+ * @param {object} store The session store
+ * @param {string} siteId |The site id
+ * @returns The site load data or null if none exist.
+ */
+export function getSiteLoadData(store, siteId) {
+    const loadData = store?.siteData?.[siteId]?.loadData || {};
+    
+    if (loadData) {
+        return loadData;
+    }
+
+    return null;
+}
+
+/**
+ * Get the site's reference number from load data from the store 
+ * 
+ * @param {object} store The session store
+ * @param {string} siteId The site ID
+ * @returns {string|null} The reference number or null if not available
+ */
+export function getSiteLoadDataReferenceNumber(store, siteId) {
+  const ref = store?.siteData?.[siteId]?.loadData?.referenceValue;
+
+  return typeof ref === 'string' && ref.trim() !== '' ? ref : null;
+}
+
+
 /**
  * Get the site's input data from the store 
  * 

package/src/utils/govcyExpressions.mjs

@@ -124,7 +124,7 @@ export function evaluateExpressionWithFlattening(expression, object, prefix = ''
  * @returns {{ result: true } | { result: false, redirect: string }}
  *          An object indicating whether to render the page or redirect
  */
-export function evaluatePageConditions(page, store, siteKey, req) {
+export function evaluatePageConditions(page, store, siteKey, req = {}) {
   // Get conditions array from nested page structure
   const conditions = page?.pageData?.conditions;
 

package/src/utils/govcyFormHandling.mjs

@@ -5,16 +5,28 @@
  * and show error summary when there are validation errors.
  */
 import { ALLOWED_FORM_ELEMENTS } from "./govcyConstants.mjs";
+import * as dataLayer from "./govcyDataLayer.mjs";
+import * as govcyResources from "../resources/govcyResources.mjs";
 
 
 /**
  * Helper function to populate form data with session data
  * @param {Array} formElements The form elements  
  * @param {*} theData The data either from session or request
+ * @param {Object} validationErrors The validation errors
+ * @param {Object} store The session store
+ * @param {string} siteId The site ID
+ * @param {string} pageUrl The page URL
+ * @param {string} lang The language
+ * @param {Object} fileInputElements The file input elements
+ * @param {string} routeParam The route parameter
  */
-export function populateFormData(formElements, theData, validationErrors) {
+export function populateFormData(formElements, theData, validationErrors, store = {}, siteId = "", pageUrl = "", lang = "el", fileInputElements = null, routeParam = "") {
     const inputElements = ALLOWED_FORM_ELEMENTS;
-
+    const isRootCall = !fileInputElements;
+    if (isRootCall) {
+        fileInputElements = {};
+    }
     // Recursively populate form data with session data
     formElements.forEach(element => {
         if (inputElements.includes(element.element)) {
@@ -53,6 +65,27 @@ export function populateFormData(formElements, theData, validationErrors) {
                     // Invalid format (not matching D/M/YYYY or DD/MM/YYYY)
                     element.params.value = "";
                 }
+            } else if (element.element === "fileInput") {
+                // For fileInput, we change the element.element to "fileView" and set the 
+                // fileId and sha256 from the session store
+                // unneeded handle of `Attachment` at the end
+                // const fileData = dataLayer.getFormDataValue(store, siteId, pageUrl, fieldName + "Attachment");
+                const fileData = dataLayer.getFormDataValue(store, siteId, pageUrl, fieldName);
+                // TODO: Ask Andreas how to handle empty file inputs
+                if (fileData) {
+                    element.element = "fileView";
+                    element.params.fileId = fileData.fileId;
+                    element.params.sha256 = fileData.sha256;
+                    element.params.visuallyHiddenText = element.params.label;
+                    // TODO: Also need to set the `view` and `download` URLs 
+                    element.params.viewHref = `/${siteId}/${pageUrl}/view-file/${fieldName}`;
+                    element.params.viewTarget = "_blank";
+                    element.params.deleteHref  = `/${siteId}/${pageUrl}/delete-file/${fieldName}${(routeParam) ? `?route=${routeParam}` : ''}`;
+                } else {
+                    // TODO: Ask Andreas how to handle empty file inputs
+                    element.params.value = "";
+                }       
+                fileInputElements[fieldName] = element;
             // Handle all other input elements (textInput, checkboxes, radios, etc.)
             } else {
                 element.params.value = theData[fieldName] || "";
@@ -78,7 +111,7 @@ export function populateFormData(formElements, theData, validationErrors) {
         if (element.element === "radios" && element.params.items) {
             element.params.items.forEach(item => {
                 if (item.conditionalElements) {
-                    populateFormData(item.conditionalElements, theData, validationErrors);
+                    populateFormData(item.conditionalElements, theData, validationErrors,store, siteId , pageUrl, lang, fileInputElements, routeParam);
                   
                     // Check if any conditional element has an error and add to the parent "conditionalHasErrors": true
                     if (item.conditionalElements.some(condEl => condEl.params?.error)) {
@@ -88,6 +121,29 @@ export function populateFormData(formElements, theData, validationErrors) {
             });
         }
     });
+    // add file input elements's definition in js object
+    if (isRootCall && Object.keys(fileInputElements).length > 0) {
+        const scriptTag = `
+        <script type="text/javascript">
+            window._govcyFileInputs = ${JSON.stringify(fileInputElements)};
+            window._govcySiteId = "${siteId}";
+            window._govcyPageUrl = "${pageUrl}";
+            window._govcyLang = "${lang}";
+        </script>
+        <div id="_govcy-upload-status" class="govcy-visually-hidden" role="status" aria-live="assertive"></div>
+        <div id="_govcy-upload-error" class="govcy-visually-hidden" role="alert" aria-live="assertive"></div>
+        `.trim();
+        formElements.push({
+            element: 'htmlElement',
+            params: {
+                text: {
+                    en: scriptTag,
+                    el: scriptTag,
+                    tr: scriptTag
+                }
+            }
+        });
+    }
 }
 
 
@@ -96,9 +152,12 @@ export function populateFormData(formElements, theData, validationErrors) {
  * 
  * @param {Array} elements - The form elements (including conditional ones).
  * @param {Object} formData - The submitted form data.
+ * @param {Object} store - The session store .
+ * @param {string} siteId - The site ID .
+ * @param {string} pageUrl - The page URL .
  * @returns {Object} filteredData - The filtered form data.
  */
-export function getFormData(elements, formData) {
+export function getFormData(elements, formData, store = {}, siteId = "", pageUrl = "") {
     const filteredData = {};
     elements.forEach(element => {
         const { name } = element.params || {};
@@ -115,7 +174,7 @@ export function getFormData(elements, formData) {
                         if (item.conditionalElements) {
                             Object.assign(
                                 filteredData,
-                                getFormData(item.conditionalElements, formData)
+                                getFormData(item.conditionalElements, formData, store, siteId, pageUrl)
                             );
                         }
                     });
@@ -130,6 +189,23 @@ export function getFormData(elements, formData) {
                 filteredData[`${name}_day`] = day !== undefined && day !== null ? day : "";
                 filteredData[`${name}_month`] = month !== undefined && month !== null ? month : "";
                 filteredData[`${name}_year`] = year !== undefined && year !== null ? year : "";
+            // handle fileInput
+            } else if (element.element === "fileInput") {
+                // fileInput elements are already stored in the store when it was uploaded
+                // so we just need to check if the file exists in the dataLayer in the store and add it the filteredData
+                // unneeded handle of `Attachment` at the end
+                // const fileData = dataLayer.getFormDataValue(store, siteId, pageUrl, name + "Attachment");
+                const fileData = dataLayer.getFormDataValue(store, siteId, pageUrl, name);
+                if (fileData) {
+                    // unneeded handle of `Attachment` at the end
+                    // filteredData[name + "Attachment"] = fileData;
+                    filteredData[name] = fileData;
+                } else {
+                    //TODO: Ask Andreas how to handle empty file inputs
+                    // unneeded handle of `Attachment` at the end
+                    // filteredData[name + "Attachment"] = ""; // or handle as needed
+                    filteredData[name] = ""; // or handle as needed
+                }
             // Handle other elements (e.g., textInput, textArea, datePicker)
             } else {
                 filteredData[name] = formData[name] !== undefined && formData[name] !== null ? formData[name] : "";

package/src/utils/govcyHandleFiles.mjs

@@ -0,0 +1,307 @@
+import FormData from 'form-data';
+import { getPageConfigData } from "./govcyLoadConfigData.mjs";
+import { evaluatePageConditions } from "./govcyExpressions.mjs";
+import { getEnvVariable, getEnvVariableBool } from "./govcyEnvVariables.mjs";
+import { ALLOWED_FILE_MIME_TYPES, ALLOWED_FILE_SIZE_MB } from "./govcyConstants.mjs";
+import { govcyApiRequest } from "./govcyApiRequest.mjs";
+import * as dataLayer from "./govcyDataLayer.mjs";
+import { logger } from './govcyLogger.mjs'; 
+
+/**
+ * Handles the logic for uploading a file to the configured Upload API.
+ * Does not send a response — just returns a standard object to be handled by middleware.
+ *
+ * @param {object} opts - Input parameters
+ * @param {object} opts.service - The service config object
+ * @param {object} opts.store - Session store (req.session)
+ * @param {string} opts.siteId - Site ID
+ * @param {string} opts.pageUrl - Page URL
+ * @param {string} opts.elementName - Name of file input
+ * @param {object} opts.file - File object from multer (req.file)
+ * @returns {Promise<{ status: number, data?: object, errorMessage?: string }>}
+ */
+export async function handleFileUpload({ service, store, siteId, pageUrl, elementName, file }) {
+  try {
+    // Validate essentials
+    // Early exit if key things are missing
+    if (!file || !elementName) {
+      return {
+        status: 400,
+        dataStatus: 400,
+        errorMessage: 'Missing file or element name'
+      };
+    }
+
+    // Get the upload configuration
+    const uploadCfg = service?.site?.fileUploadAPIEndpoint;
+    // Check if upload configuration is available
+    if (!uploadCfg?.url || !uploadCfg?.clientKey || !uploadCfg?.serviceId) {
+      return {
+        status: 400,
+        dataStatus: 401,
+        errorMessage: 'Missing upload configuration'
+      };
+    }
+
+    // Environment vars
+    const allowSelfSignedCerts = getEnvVariableBool("ALLOW_SELF_SIGNED_CERTIFICATES", false);
+    let url = getEnvVariable(uploadCfg.url || "", false);
+    const clientKey = getEnvVariable(uploadCfg.clientKey || "", false);
+    const serviceId = getEnvVariable(uploadCfg.serviceId || "", false);
+    const dsfGtwKey = getEnvVariable(uploadCfg?.dsfgtwApiKey || "", "");
+    const method = (uploadCfg?.method || "PUT").toLowerCase();
+
+     // Check if the upload API is configured correctly
+    if (!url || !clientKey) {
+      return {
+        status: 400,
+        dataStatus: 402,
+        errorMessage: 'Missing environment variables for upload'
+      };
+    }
+
+    // Construct the URL with tag being the elementName
+    const tag = encodeURIComponent(elementName.trim());
+    url += `/${tag}`;
+
+    // Get the page configuration using utility (safely extracts the correct page)
+    const page = getPageConfigData(service, pageUrl);
+    // Check if the page template is valid
+    if (!page?.pageTemplate) {
+      return {
+        status: 400,
+        dataStatus: 403,
+        errorMessage: 'Invalid page configuration'
+      };
+    }
+
+    // ----- Conditional logic comes here
+    // Respect conditional logic: If the page is skipped due to conditions, abort
+    const conditionResult = evaluatePageConditions(page, store, siteId);
+    if (conditionResult.result === false) {
+      return {
+        status: 403,
+        dataStatus: 404,
+        errorMessage: 'This page is skipped by conditional logic'
+      };
+    }
+
+    // deep copy the page template to avoid modifying the original
+    const pageTemplateCopy = JSON.parse(JSON.stringify(page.pageTemplate));
+    // Validate the field: Only allow upload if the page contains a fileInput with the given name
+    const isAllowed = pageContainsFileInput(pageTemplateCopy, elementName);
+    if (!isAllowed) {
+      return {
+        status: 403,
+        dataStatus: 405,
+        errorMessage: `File input [${elementName}] not allowed on this page`
+      };
+    }
+
+    // Empty file check
+    if (file.size === 0) {
+      return {
+        status: 400,
+        dataStatus: 406,
+        errorMessage: 'Uploaded file is empty'
+      };
+    }
+
+    // file type checks
+    // 1. Check declared mimetype
+    if (!ALLOWED_FILE_MIME_TYPES.includes(file.mimetype)) {
+        return {
+            status: 400,
+            dataStatus: 407,
+            errorMessage: 'Invalid file type (MIME not allowed)'
+        };
+    }
+
+    // 2. Check actual file content (magic bytes) matches claimed MIME type
+    if (!isMagicByteValid(file.buffer, file.mimetype)) {
+        return {
+            status: 400,
+            dataStatus: 408,
+            errorMessage: 'Invalid file type (magic byte mismatch)'
+        };
+    }
+
+    // File size check
+    if (file.size > ALLOWED_FILE_SIZE_MB * 1024 * 1024) {
+      return {
+        status: 400,
+        dataStatus: 409,
+        errorMessage: 'File exceeds allowed size'
+      };
+    }
+
+    // Prepare FormData
+    const form = new FormData();
+    form.append('file', file.buffer, {
+      filename: file.originalname,
+      contentType: file.mimetype,
+    });
+    
+    logger.debug("Prepared FormData with file:", {
+        filename: file.originalname,
+        mimetype: file.mimetype,
+        size: file.size
+    });
+
+    // Get the user
+    const user = dataLayer.getUser(store);
+    // Perform the upload request
+    const response = await govcyApiRequest(
+      method,
+      url,
+      form,
+      true,
+      user,
+      {
+        accept: "text/plain",
+        "client-key": clientKey,
+        "service-id": serviceId,
+        ...(dsfGtwKey !== "" && { "dsfgtw-api-key": dsfGtwKey })
+      },
+      3,
+      allowSelfSignedCerts
+    );
+
+    // If not succeeded, handle error
+    if (!response?.Succeeded) {
+      return {
+        status: 500,
+        dataStatus: 410,
+        errorMessage: `${response?.ErrorCode} - ${response?.ErrorMessage} - fileUploadAPIEndpoint returned succeeded false`
+      };
+    }
+
+    // Check if the response contains the expected data
+    if (!response?.Data?.fileId || !response?.Data?.sha256) {
+      return {
+        status: 500,
+        dataStatus: 411,
+        errorMessage: 'Missing fileId or sha256 in response'
+      };
+    }
+
+    // ✅ Success
+    // Store the file metadata in the session store
+    // unneeded handle of `Attachment` at the end
+    // dataLayer.storePageDataElement(store, siteId, pageUrl, elementName+"Attachment", {
+    dataLayer.storePageDataElement(store, siteId, pageUrl, elementName, {
+      sha256: response.Data.sha256,
+      fileId: response.Data.fileId,
+    });
+    logger.debug("File upload successful", response.Data);
+    logger.info(`File uploaded successfully for element ${elementName} on page ${pageUrl} for site ${siteId}`);
+    return {
+      status: 200,
+      data: {
+        sha256: response.Data.sha256,
+        filename: response.Data.fileName || '',
+        fileId: response.Data.fileId,
+        mimeType: response.Data.contentType || '',
+        fileSize: response.Data?.fileSize || ''
+      }
+    };
+
+  } catch (err) {
+    return {
+      status: 500,
+      dataStatus: 500,
+      errorMessage: 'Upload failed' + (err.message ? `: ${err.message}` : ''),
+    };
+  }
+}
+
+//--------------------------------------------------------------------------
+// Helper Functions
+/**
+ * Recursively checks whether any element (or its children) is a fileInput
+ * with the matching elementName.
+ *
+ * Supports:
+ * - Top-level fileInput
+ * - Nested `params.elements` (used in groups, conditionals, etc.)
+ * - Conditional radios/checkboxes with `items[].conditionalElements`
+ * 
+ * @param {Array} elements - The array of elements to search
+ * @param {string} targetName - The name of the file input to check
+ * @returns {boolean} True if a matching fileInput is found, false otherwise
+ */
+function containsFileInput(elements = [], targetName) {
+  for (const el of elements) {
+    // ✅ Direct file input match
+    if (el.element === 'fileInput' && el.params?.name === targetName) {
+      return el;
+    }
+    // 🔁 Recurse into nested elements (e.g. groups, conditionals)
+    if (Array.isArray(el?.params?.elements)) {
+      const nestedMatch = containsFileInput(el.params.elements, targetName);
+      if (nestedMatch) return nestedMatch; // ← propagate the found element
+    }
+
+    // 🎯 Special case: conditional radios/checkboxes
+    if (
+      (el.element === 'radios' || el.element === 'checkboxes') &&
+      Array.isArray(el?.params?.items)
+    ) {
+      for (const item of el.params.items) {
+        if (Array.isArray(item?.conditionalElements)) {
+          const match = containsFileInput(item.conditionalElements, targetName);
+          if (match) return match; // ← propagate the found element
+        }
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * Checks whether the specified page contains a valid fileInput for this element ID
+ * under any <form> element in its sections
+ * 
+ * @param {object} pageTemplate The page template object
+ * @param {string} elementName The name of the element to check
+ * @return {boolean} True if a fileInput exists, false otherwise
+ */
+export function pageContainsFileInput(pageTemplate, elementName) {
+  const sections = pageTemplate?.sections || [];
+
+  for (const section of sections) {
+    for (const el of section?.elements || []) {
+      if (el.element === 'form') {
+        const match = containsFileInput(el.params?.elements, elementName);
+        if (match) {
+          return match; // ← return the actual element
+        }
+      }
+    }
+  }
+
+  return null; // no match found
+}
+
+
+/**
+ * Validates magic bytes against expected mimetype
+ * @param {Buffer} buffer 
+ * @param {string} mimetype 
+ * @returns {boolean}
+ */
+export function isMagicByteValid(buffer, mimetype) {
+  const signatures = {
+    'application/pdf':      [0x25, 0x50, 0x44, 0x46],                // %PDF
+    'image/png':            [0x89, 0x50, 0x4E, 0x47],                // PNG
+    'image/jpeg':           [0xFF, 0xD8, 0xFF],                      // JPG/JPEG
+    'application/vnd.openxmlformats-officedocument.wordprocessingml.document': [0x50, 0x4B, 0x03, 0x04], // DOCX
+    'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': [0x50, 0x4B, 0x03, 0x04],       // XLSX
+  };
+
+  const expected = signatures[mimetype];
+  if (!expected) return false; // unknown type
+
+  const actual = Array.from(buffer.slice(0, expected.length));
+  return expected.every((byte, i) => actual[i] === byte);
+}