@gov-cy/govcy-express-services 1.0.0-alpha.14 → 1.0.0-alpha.16

package/README.md

@@ -3,6 +3,7 @@
 ![License](https://img.shields.io/github/license/gov-cy/govcy-express-services)
 [![Unit test](https://github.com/gov-cy/govcy-express-services/actions/workflows/unit-test.yml/badge.svg)](https://github.com/gov-cy/govcy-express-services/actions/workflows/unit-test.yml)
 [![tag-and-publish-on-version-change](https://github.com/gov-cy/govcy-express-services/actions/workflows/tag-and-publish-on-version-change.yml/badge.svg)](https://github.com/gov-cy/govcy-express-services/actions/workflows/tag-and-publish-on-version-change.yml)
+![coverage](coverage-badges.svg)
 
 > ⚠️ **Warning:**  
 > This package is **under active development** and is not a finished product. It is intended for testing, acceptance, integration, and browser testing purposes only. 
@@ -12,10 +13,12 @@
 > You are responsible for ensuring your own compliance, security, and quality assurance processes.
 
 ## 📝 Description
-This project is an Express-based project that dynamically renders online service forms using `@gov-cy/govcy-frontend-renderer`. It is designed for developers building government services in Cyprus, enabling them to manage user authentication, form submissions, and OpenID authentication workflows in a timely manner.
+This project is an Express-based project that dynamically renders online service forms using `@gov-cy/govcy-frontend-renderer`, handles data input, validations, renders a review page and submits the data via a submission API. It is designed for developers building government services in Cyprus, enabling them to manage user authentication, form submissions, and OpenID authentication workflows in a timely manner. 
 
 The project is designed to support the [Linear structure](https://gov-cy.github.io/govcy-design-system-docs/patterns/service_structure/#variant-1---linear-structure) as described in the [Unified Design System](https://gov-cy.github.io/govcy-design-system-docs/). 
 
+The APIs used for submission, temporary save and file uploads are not part of this project. The project has been designed to work together with the **DSF Submission plarform** and all API calls are based on the **DSF Submission Platform APIs**. This readme file describes the definition of these APIs if you wish to develop your own for your own government back-end solution. For more details about the DSF Submission Platform [contact the DSF team](https://dsf.dmrid.gov.cy/contact/).
+
 ![govcy-express-services](express-services.png)
 
 ## Table of contents
@@ -27,15 +30,15 @@ The project is designed to support the [Linear structure](https://gov-cy.github.
 - [✅ Best Practices](#-best-practices)
 - [📦 Full installation guide](#-full-installation-guide)
 - [🛠️ Usage](#%EF%B8%8F-usage)
-  - [🧩 Dynamic services rendering](#-dynamic-services-rendering)
+  - [🧩 Dynamic services](#-dynamic-services)
   - [🛡️ Site eligibility checks](#%EF%B8%8F-site-eligibility-checks)
   - [📤 Site submissions](#-site-submissions)
   - [✅ Input validations](#-input-validations)
-  - [✅ Conditional logic](#-conditional-logic)
+  - [🔀 Conditional logic](#-conditional-logic)
   - [💾 Temporary save feature](#-temporary-save-feature)
   - [🗃️ Files uploads feature](#%EF%B8%8F-files-uploads-feature)
 - [🛣️ Routes](#%EF%B8%8F-routes)
-- [👨‍💻 Enviromental variables](#-enviromental-variables)
+- [👨‍💻 Environment variables](#-environment-variables)
 - [🔒 Security note](#-security-note)
 - [❓ Troubleshooting / FAQ](#-troubleshooting--faq)
 - [🙏 Credits](#-credits)
@@ -45,7 +48,7 @@ The project is designed to support the [Linear structure](https://gov-cy.github.
 
 ## ✨ Features
 - Dynamic form rendering from JSON templates
-    - Support for `textInput`, `textArea`, `select`, `radios`, `checkboxes`, `datePicker`, `dateInput`
+    - Support for `textInput`, `textArea`, `select`, `radios`, `checkboxes`, `datePicker`, `dateInput`, `fileInput` elements
     - Support for `conditional radios`
 - Dynamic creation of check your answers page
 - OpenID Connect authentication with CY Login
@@ -58,6 +61,7 @@ The project is designed to support the [Linear structure](https://gov-cy.github.
 - Site level API eligibility checks
 - API integration with retry logic for form submissions.
 - Optional temporary save of in-progress form data via configurable API endpoints
+- Optional file uploads via API endpoints
 
 ## 📋 Prerequisites
 - Node.js 20+
@@ -138,7 +142,7 @@ The CY Login tokens are used to also connect with the various APIs through [cyCo
 
 The CY Login settings are configured in the `secrets/.env` file.
 
-### 🧩 Dynamic Services Rendering
+### 🧩 Dynamic Services
 Services are rendered dynamically using JSON templates stored in the `/data` folder. All the service configuration, pages, routes, and logic is stored in the JSON files. The service will load `data/:siteId.json` to get the form data when a user visits `/:siteId/:pageUrl`. Checkout the [express-service-shema.json](express-service-shema.json) and the example JSON structure of the **[test.json](data/test.json)** file for more details.
 
 Here is an example JSON config:
@@ -749,8 +753,7 @@ Here's an example of a page defined in the JSON file:
             "element": "backLink",
             "params": {}
           }
-        ],
-        "params": {}
+        ]
       },
       {
         "name": "main",
@@ -1174,7 +1177,7 @@ Content-Type: application/json
 {
   "submission_username": "username",
   "submission_email": "email@example.com",
-  "submission_data": "{\"index\":{\"formData\":{\"certificate_select\":[\"birth\",\"permanent_residence\"]}}}",
+  "submission_data": "{\"index\":{\"certificate_select\":[\"birth\",\"permanent_residence\"]}}",
   "submission_data_version": "1",
   "print_friendly_data": "[{\"pageUrl\":\"index\",\"pageTitle\":{\"el\":\"Επιλογή Εγγάφου\",\"en\":\"Document selection\",\"tr\":\"\"},\"fields\":[{\"id\":\"certificate_select\",\"name\":\"certificate_select\",\"label\":{\"el\":\"Τι έγγραφα επιθυμείτε να εκδώσετε;\",\"en\":\"What documents do you wish to issue?\"},\"value\":[\"birth\",\"permanent_residence\"],\"valueLabel\":[{\"el\":\"Πιστοποιητικό γέννησης​\",\"en\":\"Birth certificate\",\"tr\":\"\"},{\"el\":\"Βεβαίωση μόνιμης διαμονής​\",\"en\":\"Certificate of permanent residence\",\"tr\":\"\"}]}]}]",
   "renderer_data": "{\"element\":\"summaryList\",\"params\":{\"items\":[{\"key\":{\"el\":\"Επιλογή Εγγάφου\",\"en\":\"Document selection\",\"tr\":\"\"},\"value\":[{\"element\":\"summaryList\",\"params\":{\"items\":[{\"key\":{\"el\":\"Τι έγγραφα επιθυμείτε να εκδώσετε;\",\"en\":\"What documents do you wish to issue?\"},\"value\":[{\"element\":\"textElement\",\"params\":{\"text\":{\"en\":\"Birth certificate, Certificate of permanent residence\",\"el\":\"Birth certificate, Certificate of permanent residence\",\"tr\":\"Birth certificate, Certificate of permanent residence\"},\"type\":\"span\"}}]}]}}]}]}}",
@@ -1260,35 +1263,34 @@ The data is collected from the form elements and the data layer and are sent via
   "submission_data_version": "0.1",         // Submission data version
   "submission_data": {                      // Submission raw data. Object, will be stringified
     "index": {                              // Page level
-      "formData": {
-        "id_select": ["id", "arc"],         // field level. Could be string or array
-        "id_number": "654654",
-        "arc_number": "",
-        "aka": "232323"
-      }
+      "id_select": ["id", "arc"],           // field level. Could be string or array
+      "id_number": "654654",
+      "arc_number": "",
+      "aka": "232323",
+      "evidenceAttachment":                // File attachments contains an object with `fileId` and `sha256`
+      {
+        "fileId": "1234567891234567890",
+        "sha256": "123456789012345678901234567890123456789012345678901234567890123456"
+      }        
     },
     "appointment": {
-      "formData": {
-        "diorismos": "monimos",
-        "fileno_monimos": "3233",
-        "eidikotita_monimos": "1",
-        "fileno_sumvasiouxos": "",
-        "eidikotita_sumvasiouxos": "",
-        "fileno_aoristou": "",
-        "eidikotita_aoristou": "",
-        "program": "",
-        "fileno_orismenou": ""
-      }
+      "diorismos": "monimos",
+      "fileno_monimos": "3233",
+      "eidikotita_monimos": "1",
+      "fileno_sumvasiouxos": "",
+      "eidikotita_sumvasiouxos": "",
+      "fileno_aoristou": "",
+      "eidikotita_aoristou": "",
+      "program": "",
+      "fileno_orismenou": ""
     },
     "takeover": {
-      "formData": {
-        "date_start_day": "11",
-        "date_start_month": "12",
-        "date_start_year": "2020",
-        "date_on_contract": "date_other",
-        "date_contract": "16/04/2025",
-        "reason": "24324dssf"
-      }
+      "date_start_day": "11",
+      "date_start_month": "12",
+      "date_start_year": "2020",
+      "date_on_contract": "date_other",
+      "date_contract": "16/04/2025",
+      "reason": "24324dssf"
     }
   },
   "submission_data_version": "1",           // Submission data version
@@ -1687,6 +1689,7 @@ The project includes input validation for the following elements:
 - `checkboxes`
 - `datePicker`
 - `dateInput`
+- `fileInput` (only required check)
 
 The validation rules for each element are defined in the `"validations` array for each element. The project support the following validations:
 
@@ -1742,7 +1745,7 @@ Example:
 ]
 ```
 
-### ✅ Conditional logic
+### 🔀 Conditional logic
 
 The project supports conditional logic on pages. Conditional logic is evaluated using a custom `govcyExpressions.mjs` module, which executes expressions in a safe and scoped context using `new Function`. Only safe data access through the `dataLayer` is allowed. The system uses expressions and session data from the service's [data layer](NOTES.md#data-layer) to decide if a page will be shown or not.
 
@@ -2285,7 +2288,13 @@ Here is a sample code section of a page definition with a file input field:
 - **On a form page with an upload input field**:
   - **On first load**: the page displays the fileInput field to choose a file.
   - **On choosing a file**: the file is uploaded to the `fileUploadAPIEndpoint` endpoint.
-    - The `fileUploadAPIEndpoint` validates the input for allowed file types and file size. On validation error an error message is displayed.
+    - The `fileUploadAPIEndpoint` validates the input for allowed file types and file size. On validation error an error message is displayed. The following validations are performed:
+      - The fileInput element is defined in the JSON config 
+      - API endpoints and environment variables are defined
+      - The page is not skiped because of conditional logic
+      - The file is not empty
+      - The file size must be less than 5MB
+      - The file type must be one of the following: pdf, jpg, jpeg, png
     - If `fileUploadAPIEndpoint` returns an success, the file is uploaded temporarilly and the `fileView` element is displayed, with links to `View` or `Delete` the file. The file infomation are store in the data layer of the page.
 - **On a form page after upload**:
   - The `fileView` element is displayed with links to `View` or `Delete` the file.
@@ -2300,7 +2309,7 @@ Here is a sample code section of a page definition with a file input field:
   
 
 #### `fileUploadAPIEndpoint` `POST` API Request and Response
-This API is used to temporarily store the file uploaded by the user.
+This API is used to temporarily store the file uploaded by the user. The API connects the file with a temporary saved submission, for the specific user and service. It does not create a connection with the actual field on the specific page, that is done by the `submissionPutAPIEndpoint` API.
 
 **Request:**
 
@@ -2457,7 +2466,7 @@ To help back-end systems recognize the field as a file, the field's element name
 ```
 
 #### File uploads backward compatibility
-If these endpoints are not defined in the service JSON, the temporary save/load logic is skipped entirely.
+If these endpoints are not defined in the service JSON, the file upload logic is skipped entirely.
 Existing services will continue to work without modification.
 
 ### 🛣️ Routes
@@ -2479,7 +2488,7 @@ The project uses express.js to serve the following routes:
 #### API routes:
 - **`/apis/:siteId/:pageUrl/upload`**: Uploads a file. Used from the client side JS.
 
-### 👨‍💻 Enviromental variables
+### 👨‍💻 Environment variables
 The environment variables are defined in:
  - **Secret environment variables**: These are secret variables and MUSR NOT be saved in version control. The are saved locally in the `secrets/.env` file and they control the server configuration, authentication, integrations, and development behavior. These variables vary depending on the environment and are defined through the deployment prosses for `staging` and `production`.
  - **Non secret environment variables**:  These are non secret enviromentat variables and can be saved in version control. These are stored in the root folder of the project:
@@ -2550,10 +2559,13 @@ TEST_SUBMISSION_API_CLIENT_KEY=12345678901234567890123456789000
 TEST_SUBMISSION_API_SERVIVE_ID=123
 TEST_SUBMISSION_DSF_GTW_KEY=12345678901234567890123456789000
 
-# Optional Temporary Save GET and PUT endpoint (test service)
+# Optional Temporary Save GET and PUT endpoints (test service)
 TEST_SUBMISSION_GET_API_URL=http://localhost:3002/getTempSubmission
 TEST_SUBMISSION_PUT_API_URL=http://localhost:3002/save
 
+# Optional File Upload and download endpoints (test service)
+TEST_FILE_UPLOAD_API_URL=http://localhost:3002/fileUpload
+TEST_FILE_DOWNLOAD_API_URL=http://localhost:3002/fileDownload
 
 # Eligibility checks (optional test APIs)
 TEST_ELIGIBILITY_1_API_URL=http://localhost:3002/eligibility1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gov-cy/govcy-express-services",
-  "version": "1.0.0-alpha.14",
+  "version": "1.0.0-alpha.16",
   "description": "An Express-based system that dynamically renders services using @gov-cy/govcy-frontend-renderer and posts data to a submission API.",
   "author": "DMRID - DSF Team",
   "license": "MIT",
@@ -45,8 +45,9 @@
     "test:package": "mocha --recursive tests/package/**/*.test.mjs",
     "test:functional": "mocha --timeout 30000 --recursive tests/functional/**/*.test.mjs",
     "test:watch": "mocha --watch --timeout 60000 tests/**/*.test.mjs",
-    "coverage": "c8 --reporter=html --reporter=text --reporter=lcov  --reporter=cobertura npm test",
-    "coverage:report": "c8 report"
+    "coverage": "c8 --reporter=html --reporter=text --reporter=lcov --reporter=json-summary npm test",
+    "coverage:report": "c8 report",
+    "coverage:badge": "coverage-badges --output ./coverage-badges.svg"
   },
   "dependencies": {
     "@gov-cy/dsf-email-templates": "^2.1.0",
@@ -65,6 +66,7 @@
     "c8": "^10.1.3",
     "chai": "^5.2.0",
     "chai-http": "^5.1.1",
+    "coverage-badges-cli": "^2.2.0",
     "mocha": "^11.1.0",
     "mochawesome": "^7.1.3",
     "nodemon": "^3.0.2",

package/src/auth/cyLoginAuth.mjs

@@ -2,7 +2,7 @@ import * as client from 'openid-client';
 import { getEnvVariable } from '../utils/govcyEnvVariables.mjs';
 import { logger } from "../utils/govcyLogger.mjs";
 
-
+/* c8 ignore start */
 // OpenID Configuration
 const issuerUrl = getEnvVariable('CYLOGIN_ISSUER_URL');
 const clientId = getEnvVariable('CYLOGIN_CLIENT_ID');
@@ -131,3 +131,4 @@ export function getLogoutUrl(id_token_hint = '') {
 
 // Export config if needed elsewhere
 export { config };
+/* c8 ignore end */

package/src/middleware/cyLoginAuth.mjs

@@ -10,6 +10,7 @@ import { handleMiddlewareError } from "../utils/govcyUtils.mjs";
 import { errorResponse } from "../utils/govcyApiResponse.mjs"; 
 import { isApiRequest } from '../utils/govcyApiDetection.mjs';
 
+/* c8 ignore start */
 /**
  * Middleware to check if the user is authenticated. If not, redirect to the login page.
  * 
@@ -136,4 +137,5 @@ export function handleLogout() {
             res.redirect(logoutUrl);
         });
     };
-}
+}
+/* c8 ignore end */

package/src/middleware/govcyPDFRender.mjs

@@ -6,6 +6,7 @@ import { logger } from "../utils/govcyLogger.mjs";
  * Middleware function to render PDFs using the GovCy Frontend Renderer.
  * This function takes the processed page data and template, and generates the final PDF response.
  */
+/* c8 ignore start */
 export function govcyPDFRender() {
     return async (req, res) => {
         try {
@@ -29,4 +30,5 @@ export function govcyPDFRender() {
             res.status(500).send('Unable to generate PDF at this time.');
         }
     };
-}
+}
+/* c8 ignore end */

package/src/utils/govcyConstants.mjs

@@ -4,5 +4,5 @@
 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_FILE_SIZE_MB = 4; // Maximum file size in MB
 export const ALLOWED_MULTER_FILE_SIZE_MB = 10; // Maximum file size in MB