@gov-cy/govcy-express-services 0.2.15 → 1.0.0-alpha.1

package/README.md

@@ -32,6 +32,7 @@ The project is designed to support the [Linear structure](https://gov-cy.github.
   - [📤 Site submissions](#-site-submissions)
   - [✅ Input validations](#-input-validations)
   - [✅ Conditional logic](#-conditional-logic)
+  - [💾 Temporary save](#-temporary-save)
 - [🛣️ Routes](#%EF%B8%8F-routes)
 - [👨‍💻 Enviromental variables](#-enviromental-variables)
 - [🔒 Security note](#-security-note)
@@ -55,6 +56,7 @@ The project is designed to support the [Linear structure](https://gov-cy.github.
 - Pre-filling posted values (in the same session)
 - 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
 
 ## 📋 Prerequisites
 - Node.js 20+
@@ -1412,6 +1414,55 @@ Explanation:
 - `[].concat(...)`: safely flattens a string or array into an array.
 - `.includes('value1')`: checks if the value is selected.
 
+### 💾 Temporary save
+
+The **temporary save** feature allows user progress to be stored in an external API and automatically reloaded on the next visit.  
+This is useful for long forms or cases where users may leave and return later.
+
+#### 1. Configure the endpoints in your service JSON
+In your service’s `site` object, add both a `submissionGetAPIEndpoint` and `submissionPutAPIEndpoint` entry:
+
+```json
+"submissionGetAPIEndpoint": {
+  "url": "TEST_SUBMISSION_GET_API_URL",
+  "method": "GET",
+  "clientKey": "TEST_SUBMISSION_API_CLIENT_KEY",
+  "serviceId": "TEST_SUBMISSION_API_SERVICE_ID"
+},
+"submissionPutAPIEndpoint": {
+  "url": "TEST_SUBMISSION_PUT_API_URL",
+  "method": "PUT",
+  "clientKey": "TEST_SUBMISSION_API_CLIENT_KEY",
+  "serviceId": "TEST_SUBMISSION_API_SERVICE_ID"
+}
+```
+
+These values should point to environment variables that hold your real endpoint URLs and credentials.
+
+#### 2. Add environment variables
+In your `secrets/.env` file (and staging/production configs), define the variables referenced above:
+
+```dotenv
+TEST_SUBMISSION_GET_API_URL=https://example.com/api/submissionData
+TEST_SUBMISSION_PUT_API_URL=https://example.com/api/submissionData
+TEST_SUBMISSION_API_CLIENT_KEY=12345678901234567890123456789000
+TEST_SUBMISSION_API_SERVICE_ID=123
+```
+
+#### 3. How it works
+
+- **On first page load** for a site, `govcyLoadSubmissionData` will:
+  1. Call the GET endpoint to retrieve any saved submission.
+  2. If found, populate the session’s `inputData` so fields are pre-filled.
+  3. If not found, call the PUT endpoint to create a new temporary record.
+- **On every form POST**, after successful validation:
+  - The `govcyFormsPostHandler` will fire-and-forget a `PUT` request to update the saved submission with the latest form data.
+  - The payload includes all required submission fields with `submission_data` JSON-stringified.
+
+#### 4. Backward compatibility
+If these endpoints are not defined in the service JSON, the temporary save/load logic is skipped entirely.
+Existing services will continue to work without modification.
+
 ### 🛣️ Routes
 The project uses express.js to serve the following routes:
 
@@ -1500,6 +1551,11 @@ 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)
+TEST_SUBMISSION_GET_API_URL=http://localhost:3002/getTempSubmission
+TEST_SUBMISSION_PUT_API_URL=http://localhost:3002/save
+
+
 # Eligibility checks (optional test APIs)
 TEST_ELIGIBILITY_1_API_URL=http://localhost:3002/eligibility1
 TEST_ELIGIBILITY_2_API_URL=http://localhost:3002/eligibility2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gov-cy/govcy-express-services",
-  "version": "0.2.15",
+  "version": "1.0.0-alpha.1",
   "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",

package/src/index.mjs

@@ -23,6 +23,7 @@ import { serviceConfigDataMiddleware } from './middleware/govcyConfigSiteData.mj
 import { govcyManifestHandler } from './middleware/govcyManifestHandler.mjs';
 import { govcyRoutePageHandler } from './middleware/govcyRoutePageHandler.mjs';
 import { govcyServiceEligibilityHandler } from './middleware/govcyServiceEligibilityHandler.mjs';
+import { govcyLoadSubmissionData } from './middleware/govcyLoadSubmissionData.mjs';
 import { isProdOrStaging , getEnvVariable, whatsIsMyEnvironment } from './utils/govcyEnvVariables.mjs';
 import { logger } from "./utils/govcyLogger.mjs";
 
@@ -129,10 +130,10 @@ export default function initializeGovCyExpressService(){
   app.get('/:siteId/manifest.json', serviceConfigDataMiddleware, govcyManifestHandler());
   
   // 🏠 -- ROUTE: Handle route with only siteId (/:siteId or /:siteId/)
-  app.get('/:siteId', serviceConfigDataMiddleware, requireAuth, naturalPersonPolicy, govcyServiceEligibilityHandler(true),govcyPageHandler(), renderGovcyPage());
+  app.get('/:siteId', serviceConfigDataMiddleware, requireAuth, naturalPersonPolicy, govcyServiceEligibilityHandler(true),govcyLoadSubmissionData(),govcyPageHandler(), renderGovcyPage());
   
   // 👀 -- ROUTE: Add Review Page Route (BEFORE the dynamic route)
-  app.get('/:siteId/review',serviceConfigDataMiddleware, requireAuth, naturalPersonPolicy, govcyServiceEligibilityHandler(), govcyReviewPageHandler(), renderGovcyPage());
+  app.get('/:siteId/review',serviceConfigDataMiddleware, requireAuth, naturalPersonPolicy, govcyServiceEligibilityHandler(),govcyLoadSubmissionData(), govcyReviewPageHandler(), renderGovcyPage());
   
   // ✅📄 -- ROUTE: Add Success PDF Route (BEFORE the dynamic route)
   app.get('/:siteId/success/pdf',serviceConfigDataMiddleware, requireAuth, naturalPersonPolicy, govcyServiceEligibilityHandler(), govcySuccessPageHandler(true), govcyPDFRender());
@@ -141,7 +142,7 @@ export default function initializeGovCyExpressService(){
   app.get('/:siteId/success',serviceConfigDataMiddleware, requireAuth, naturalPersonPolicy, govcyServiceEligibilityHandler(), govcySuccessPageHandler(), renderGovcyPage());
   
   // 📝 -- ROUTE: Dynamic route to render pages based on siteId and pageUrl, using govcyPageHandler middleware
-  app.get('/:siteId/:pageUrl', serviceConfigDataMiddleware, requireAuth, naturalPersonPolicy, govcyServiceEligibilityHandler(true), govcyPageHandler(), renderGovcyPage());
+  app.get('/:siteId/:pageUrl', serviceConfigDataMiddleware, requireAuth, naturalPersonPolicy, govcyServiceEligibilityHandler(true), govcyLoadSubmissionData(), govcyPageHandler(), renderGovcyPage());
   
   // 📥 -- ROUTE: Handle POST requests for review page. The `submit` action
   app.post('/:siteId/review', serviceConfigDataMiddleware, requireAuth, naturalPersonPolicy, govcyServiceEligibilityHandler(), govcyReviewPostHandler());

package/src/middleware/govcyFormsPostHandler.mjs

@@ -6,6 +6,7 @@ import { logger } from "../utils/govcyLogger.mjs";
 import { handleMiddlewareError } from "../utils/govcyUtils.mjs";
 import { getFormData } from "../utils/govcyFormHandling.mjs"
 import { evaluatePageConditions } from "../utils/govcyExpressions.mjs"; 
+import { tempSaveIfConfigured } from "../utils/govcyTempSave.mjs";
 
 
 /**
@@ -59,7 +60,12 @@ export function govcyFormsPostHandler() {
     
             //⤴️ Store validated form data in session
             dataLayer.storePageData(req.session, siteId, pageUrl, formData);
-
+            
+            // 🔄 Fire-and-forget temporary save (non-blocking)
+            (async () => {
+                try { await tempSaveIfConfigured(req.session, service, siteId); }
+                catch (e) { /* already logged internally */ }
+            })();
             
             logger.debug("✅ Form submitted successfully:", dataLayer.getPageData(req.session, siteId, pageUrl), req);
             logger.info("✅ Form submitted successfully:", req.originalUrl);

package/src/middleware/govcyLoadSubmissionData.mjs

@@ -0,0 +1,22 @@
+import { logger } from "../utils/govcyLogger.mjs";
+import { govcyLoadSubmissionDataAPIs } from "../utils/govcyLoadSubmissionDataAPIs.mjs";
+/**
+ * Middleware to load submission data from APIs.
+ * This middleware fetches submission data from configured APIs and stores it in the session. 
+ * @returns {function} Middleware function to load submission data from APIs
+ */
+export function govcyLoadSubmissionData() {
+    return async (req, res, next) => {
+        try {
+            const service = req.serviceData;
+            // Extract siteId from request
+            const { siteId } = req.params;
+
+            return await govcyLoadSubmissionDataAPIs(req.session, service, siteId, next);
+            
+        } catch (error) {
+            logger.error("Error in govcyLoadSubmissionData middleware:", error.message);
+            return next(error); // Pass the error to the next middleware
+        }
+    }
+}

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 = {};
 
@@ -97,6 +98,33 @@ export function storePageData(store, siteId, pageUrl, formData) {
 
     store.siteData[siteId].inputData[pageUrl]["formData"] = formData;
 }
+/**
+ * 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 +184,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 +311,23 @@ 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 input data from the store 
  * 

package/src/utils/govcyLoadSubmissionDataAPIs.mjs

@@ -0,0 +1,135 @@
+import { govcyApiRequest } from "./govcyApiRequest.mjs";
+import { logger } from "./govcyLogger.mjs";
+import { getEnvVariable, getEnvVariableBool } from "./govcyEnvVariables.mjs";
+import { handleMiddlewareError } from "./govcyUtils.mjs";
+import * as dataLayer from "./govcyDataLayer.mjs";
+
+/**
+ * Load submission data from configured APIs and store it in the session.
+ * @param {object} store The session store
+ * @param {object} service The service configuration
+ * @param {string} siteId The site id
+ * @param {function} next The next middleware function
+ */
+export async function govcyLoadSubmissionDataAPIs(store, service, siteId, next) {
+    try {
+
+        // Get the API endpoints 
+        const getCfg = service?.site?.submissionGetAPIEndpoint;
+        const putCfg = service?.site?.submissionPutAPIEndpoint;
+
+        //If siteLoadData already exists, skip the API call
+        const siteLoadData = dataLayer.getSiteLoadData(store, siteId);
+        if (siteLoadData && Object.keys(siteLoadData).length > 0) {
+            // Data exists, skip API call
+            logger.debug("Load data already exists for site:", siteId);
+            return next();
+        }
+        
+        // Only continue if both endpoints and required fields are defined
+        if (
+            getCfg && putCfg &&
+            getCfg.clientKey && getCfg.serviceId &&
+            putCfg.clientKey && putCfg.serviceId 
+        ){
+            const user = dataLayer.getUser(store); // Get the user from the session;
+
+            // get the API endpoint URL, clientKey, serviceId from the environment variable (handle edge cases)
+            const getCfgUrl = getEnvVariable(getCfg?.url || "", false);
+            const getCfgClientKey = getEnvVariable(getCfg?.clientKey || "", false);
+            const getCfgServiceId = getEnvVariable(getCfg?.serviceId || "", false);
+            const getCfgDsfGtwApiKey = getEnvVariable(getCfg?.dsfgtwApiKey || "", "");
+            const getCfgParams = getCfg?.params || {};
+            const getCfgMethod = (getCfg?.method || "GET").toLowerCase();
+            const putCfgUrl = getEnvVariable(putCfg?.url || "", false);
+            const putCfgClientKey = getEnvVariable(putCfg?.clientKey || "", false);
+            const putCfgServiceId = getEnvVariable(putCfg?.serviceId || "", false);
+            const putCfgDsfGtwApiKey = getEnvVariable(putCfg?.dsfgtwApiKey || "", "");
+            const putCfgParams = putCfg?.params || {};
+            const putCfgMethod = (putCfg?.method || "PUT").toLowerCase();
+
+            const allowSelfSignedCerts = getEnvVariableBool("ALLOW_SELF_SIGNED_CERTIFICATES",false) ; // Default to false if not set
+            
+            // check necessary values exist
+            if (!getCfgUrl || !getCfgClientKey 
+                || !putCfgUrl || !putCfgClientKey ) {
+                
+                return handleMiddlewareError(`🚨 Get submission environment variable missing: 
+                        getURl : ${getCfgUrl}, getClientKey : ${getCfgClientKey}
+                        putURl : ${putCfgUrl}, putClientKey : ${putCfgClientKey}`
+                    , 500, next)
+            }
+            // get response form GET submission API
+            const getResponse = await govcyApiRequest(
+                getCfgMethod,
+                getCfgUrl,
+                getCfgParams,
+                true, // use access token auth
+                user,
+                { 
+                    accept: "text/plain",       // Set Accept header to text/plain
+                    "client-key": getCfgClientKey,    // Set the client key header
+                    "service-id": getCfgServiceId,    // Set the service ID header
+                    ...(getCfgDsfGtwApiKey !== '' && { "dsfgtw-api-key": getCfgDsfGtwApiKey }) // Use the DSF API GTW secret from environment variables
+                },
+                3,
+                allowSelfSignedCerts
+            );
+
+            // If not succeeded, handle error
+            if (!getResponse.Succeeded) {
+                logger.debug("govcyLoadSubmissionData returned succeeded false",getResponse)
+                return handleMiddlewareError(`🚨 govcyLoadSubmissionData returned succeeded false`, 500, next)
+            }
+            
+            //  check if getResponse.Data is defined
+            if (getResponse.Data) {
+                // Store the response in the request for later use
+                dataLayer.storeSiteLoadData(store, siteId, getResponse.Data);
+
+                try {
+                    const parsed = JSON.parse(getResponse.Data.submissionData || "{}");
+                    if (parsed && typeof parsed === "object") {
+                        dataLayer.storeSiteInputData(store, siteId, parsed);
+                        logger.debug(`💾 Input data restored from saved submission for siteId: ${siteId}`);
+                    }
+                } catch (err) {
+                    logger.warn(`⚠️ Failed to parse saved submissionData for siteId: ${siteId}`, err);
+                }
+
+            // if not call the PUT submission API
+            } else {
+                // If no data, call the PUT submission API to create it
+                const putResponse = await govcyApiRequest(
+                    putCfgMethod,
+                    putCfgUrl,
+                    putCfgParams,
+                    true, // use access token auth
+                    user,
+                    { 
+                        accept: "text/plain",       // Set Accept header to text/plain
+                        "client-key": putCfgClientKey,    // Set the client key header
+                        "service-id": putCfgServiceId,    // Set the service ID header
+                        ...(putCfgDsfGtwApiKey !== '' && { "dsfgtw-api-key": putCfgDsfGtwApiKey }) // Use the DSF API GTW secret from environment variables
+                    },
+                    3,
+                    allowSelfSignedCerts
+                );
+                // If not succeeded, handle error
+                if (!putResponse.Succeeded) {
+                    logger.debug("govcyLoadSubmissionData returned succeeded false",putResponse)
+                    return handleMiddlewareError(`🚨 govcyLoadSubmissionData returned succeeded false`, 500, next)
+                }
+                // Store the response in the request for later use
+                dataLayer.storeSiteLoadData(store, siteId, putResponse.Data);
+
+            }
+            
+        }
+        
+    next();
+    } catch (error) {
+        logger.error("Error in govcyLoadSubmissionData middleware:", error.message);
+        return next(error); // Pass the error to the next middleware
+    }
+}

package/src/utils/govcyTempSave.mjs

@@ -0,0 +1,70 @@
+// utils/govcyTempSave.mjs
+import { govcyApiRequest } from "./govcyApiRequest.mjs";
+import { getEnvVariable, getEnvVariableBool } from "./govcyEnvVariables.mjs";
+import * as dataLayer from "./govcyDataLayer.mjs";
+import { logger } from "./govcyLogger.mjs";
+/**
+ * Temporary save of in-progress form data via configured API endpoints.
+ * @param {object} store The session store
+ * @param {object} service The service object
+ * @param {string} siteId The site id
+ */
+export async function tempSaveIfConfigured(store, service, siteId) {
+    // Check if temp save is configured for this service with a PUT endpoint
+  const putCfg = service?.site?.submissionPutAPIEndpoint;
+  if (!putCfg?.url || !putCfg?.clientKey || !putCfg?.serviceId) return;
+
+  //Get environment variables
+  const allowSelfSignedCerts = getEnvVariableBool("ALLOW_SELF_SIGNED_CERTIFICATES", false);
+  const url = getEnvVariable(putCfg.url || "", false);
+  const clientKey = getEnvVariable(putCfg.clientKey || "", false);
+  const serviceId = getEnvVariable(putCfg.serviceId || "", false);
+  const dsfGtwKey = getEnvVariable(putCfg?.dsfgtwApiKey || "", "");
+  const method = (putCfg?.method || "PUT").toLowerCase();
+  const user = dataLayer.getUser(store);
+
+  // Prepare minimal temp payload (send whole inputData snapshot)
+  const inputData = dataLayer.getSiteInputData(store, siteId) || {};
+  const tempPayload = {
+    // mirror final submission format: send stringified JSON
+    submission_data: JSON.stringify(inputData)
+  };
+
+  if (!url || !clientKey) {
+    logger.error("🚨 Temp save API configuration is incomplete:", { url, clientKey })
+    return; // don't break UX
+  } 
+
+  try {
+    // Call the API to save temp data
+    const resp = await govcyApiRequest(
+      method,
+      url,
+      tempPayload,
+      true, // auth with user access token
+      user,
+      {
+        accept: "text/plain",
+        "client-key": clientKey,
+        "service-id": serviceId,
+        ...(dsfGtwKey !== "" && { "dsfgtw-api-key": dsfGtwKey }),
+        "content-type": "application/json"
+      },
+      3,
+      allowSelfSignedCerts
+    );
+
+    if (!resp?.Succeeded) {
+      logger.warn("Temp save returned Succeeded=false", resp);
+      return; // don’t break UX
+    }
+
+    logger.info("✅ Temp save successful for site:", siteId, "Response:", resp);
+    // Optional: reflect any server state locally (e.g., keep referenceValue in loadData)
+    if (resp?.Data) {
+      dataLayer.storeSiteLoadData(store, siteId,resp.Data );
+    }
+  } catch (e) {
+    logger.error("Temp save failed (non-blocking):", e?.message);
+  }
+}