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

package/README.md

@@ -494,7 +494,9 @@ Content-Type: application/json
 The API is expected to return a JSON response with the following structure (see [govcyApiRequest.mjs](src/utils/govcyApiRequest.mjs) for normalization):
 
 **On Success:**
-```json
+```http
+HTTP/1.1 200 OK
+
 {
   "Succeeded": true,
   "ErrorCode": 0,
@@ -503,7 +505,9 @@ The API is expected to return a JSON response with the following structure (see
 ```
 
 **On Failure:**
-```json
+```http
+HTTP/1.1 200 OK
+
 {
   "Succeeded": false,
   "ErrorCode": 102,
@@ -637,7 +641,9 @@ Content-Type: application/json
 The API is expected to return a JSON response with the following structure (see [govcyApiRequest.mjs](src/utils/govcyApiRequest.mjs) for normalization):
 
 **On Success:**
-```json
+```http
+HTTP/1.1 200 OK
+
 {
   "Succeeded": true,
   "ErrorCode": 0,
@@ -649,7 +655,9 @@ The API is expected to return a JSON response with the following structure (see
 ```
 
 **On Failure:**
-```json
+```http
+HTTP/1.1 200 OK
+
 {
   "Succeeded": false,
   "ErrorCode": 102,
@@ -1419,8 +1427,8 @@ Explanation:
 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:
+#### How to configure temporary save 
+To use this feature, configure the config JSON file. In your service’s `site` object, add both a `submissionGetAPIEndpoint` and `submissionPutAPIEndpoint` entry:
 
 ```json
 "submissionGetAPIEndpoint": {
@@ -1439,7 +1447,6 @@ In your service’s `site` object, add both a `submissionGetAPIEndpoint` and `su
 
 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
@@ -1449,17 +1456,155 @@ TEST_SUBMISSION_API_CLIENT_KEY=12345678901234567890123456789000
 TEST_SUBMISSION_API_SERVICE_ID=123
 ```
 
-#### 3. How it works
+#### How temporary save works
 
-- **On first page load** for a site, `govcyLoadSubmissionData` will:
+- **On first page load** for a site, using the `submissionGetAPIEndpoint` the system 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 `submissionPutAPIEndpoint` 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
+#### `submissionGetAPIEndpoint` `GET` API Request and Response
+This API is used to retrieve the saved submission data.
+
+**Request:**
+
+- **HTTP Method**: GET
+- **URL**: Resolved from the url property in your config (from the environment variable).
+- **Headers**:
+  - **Authorization**: `Bearer <access_token>` (form user's cyLogin access token)
+  - **client-key**: `<clientKey>` (from config/env)
+  - **service-id**: `<serviceId>` (from config/env)
+  - **Accept**: `text/plain`
+- **Body**: The body contains the and either:
+  - an a `null` which means no data was found for the user
+  - a JSON object with all the form data collected from the user across all pages in previous sessions.
+
+**Example Request:**
+
+```http
+GET /temp-save-get-endpoint?status=0 HTTP/1.1
+Host: localhost:3002
+Authorization: Bearer eyJhbGciOi...
+client-key: 12345678901234567890123456789000
+service-id: 123
+Accept: text/plain
+Content-Type: application/json
+```
+
+**Response:**
+
+The API is expected to return a JSON response with the following structure:
+
+**When temporary submission data are found:**
+
+```http
+HTTP/1.1 200 OK
+
+{
+    "Succeeded": true,
+    "ErrorCode": 0,
+    "ErrorMessage": null,
+    "Data": {
+        "submissionData": "{\"index\":{\"formData\":{\"certificate_select\":[\"birth\",\"permanent_residence\"]}},\"data-entry-radios\":{\"formData\":{\"mobile_select\":\"other\",\"mobileTxt\":\"+35799484967\"}}}"
+    }
+}
+```
+
+**When temporary submission data are NOT found:**
+
+```http
+HTTP/1.1 404 Not Found
+
+{
+    "Succeeded": true,
+    "ErrorCode": 0,
+    "ErrorMessage": null,
+    "Data": null
+}
+```
+
+**When temporary submission retreival fails:**
+
+```http
+HTTP/1.1 200 OK
+
+{
+    "Succeeded": false,
+    "ErrorCode": 401,
+    "ErrorMessage": "Not authorized",
+    "Data": null
+}
+```
+
+#### `submissionPutAPIEndpoint` `PUT` API Request and Response
+This API is used to temporary save the submission data.
+
+**Request:**
+
+- **HTTP Method**: PUT
+- **URL**: Resolved from the url property in your config (from the environment variable).
+- **Headers**:
+  - **Authorization**: `Bearer <access_token>` (form user's cyLogin access token)
+  - **client-key**: `<clientKey>` (from config/env)
+  - **service-id**: `<serviceId>` (from config/env)
+  - **Accept**: `text/plain`
+- **Body**: The body contains the a JSON object with all the form data collected from the user across all pages.
+
+**Example Request:**
+
+```http
+PUT /temp-save-endpoint HTTP/1.1
+Host: localhost:3002
+Authorization: Bearer eyJhbGciOi...
+client-key: 12345678901234567890123456789000
+service-id: 123
+Accept: text/plain
+Content-Type: application/json
+
+{
+  "submission_data" : "{\"index\":{\"formData\":{\"certificate_select\":[\"birth\",\"permanent_residence\"]}},\"data-entry-radios\":{\"formData\":{\"mobile_select\":\"other\",\"mobileTxt\":\"+35799484967\"}}}"
+}
+```
+
+**Response:**
+
+The API is expected to return a JSON response with the following structure:
+
+**On success:**
+
+```http
+HTTP/1.1 200 OK
+
+{
+    "Succeeded": true,
+    "ErrorCode": 0,
+    "ErrorMessage": null,
+    "Data": {
+        "submissionData": "{\"index\":{\"formData\":{\"certificate_select\":[\"birth\",\"permanent_residence\"]}},\"data-entry-radios\":{\"formData\":{\"mobile_select\":\"other\",\"mobileTxt\":\"+35799484967\"}}}"
+    }
+}
+```
+
+**On failure:**
+
+```http
+HTTP/1.1 401 Unauthorized
+
+{
+    "Succeeded": false,
+    "ErrorCode": 401,
+    "ErrorMessage": "Not authorized",
+    "Data": null
+}
+```
+
+**Notes**:
+- The response is normalized to always use PascalCase keys (`Succeeded`, `ErrorCode`, etc.), regardless of the backend’s casing.
+
+#### Temporary save 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.
 

package/package.json

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

@@ -11,6 +11,7 @@ import { logger } from "./govcyLogger.mjs";
  * @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;
 
@@ -48,6 +50,8 @@ export async function govcyApiRequest(
                 [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),
             };
 
             // Add httpsAgent if NOT production to allow self-signed certificates
@@ -60,9 +64,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 +85,7 @@ export async function govcyApiRequest(
                 ErrorMessage,
                 Data,
                 InformationMessage
-            } = response.data;
+            } = response.data ?? {};
 
             const normalized = {
                 Succeeded: Succeeded !== undefined ? Succeeded : succeeded,

package/src/utils/govcyLoadSubmissionDataAPIs.mjs

@@ -73,7 +73,8 @@ export async function govcyLoadSubmissionDataAPIs(store, service, siteId, next)
                     ...(getCfgDsfGtwApiKey !== '' && { "dsfgtw-api-key": getCfgDsfGtwApiKey }) // Use the DSF API GTW secret from environment variables
                 },
                 3,
-                allowSelfSignedCerts
+                allowSelfSignedCerts,
+                [200, 404] // Allowed HTTP status codes
             );
 
             // If not succeeded, handle error
@@ -88,7 +89,9 @@ export async function govcyLoadSubmissionDataAPIs(store, service, siteId, next)
                 dataLayer.storeSiteLoadData(store, siteId, getResponse.Data);
 
                 try {
-                    const parsed = JSON.parse(getResponse.Data.submissionData || "{}");
+                    const parsed = JSON.parse(getResponse.Data.submissionData
+                        || getResponse.Data.submission_data 
+                        || "{}");
                     if (parsed && typeof parsed === "object") {
                         dataLayer.storeSiteInputData(store, siteId, parsed);
                         logger.debug(`💾 Input data restored from saved submission for siteId: ${siteId}`);
@@ -99,11 +102,15 @@ export async function govcyLoadSubmissionDataAPIs(store, service, siteId, next)
 
             // if not call the PUT submission API
             } else {
+                const tempPutPayload = {
+                    // submission_data: JSON.stringify({}),
+                    submissionData: JSON.stringify({})
+                };
                 // If no data, call the PUT submission API to create it
                 const putResponse = await govcyApiRequest(
                     putCfgMethod,
                     putCfgUrl,
-                    putCfgParams,
+                    tempPutPayload,
                     true, // use access token auth
                     user,
                     { 

package/src/utils/govcyTempSave.mjs

@@ -27,7 +27,8 @@ export async function tempSaveIfConfigured(store, service, siteId) {
   const inputData = dataLayer.getSiteInputData(store, siteId) || {};
   const tempPayload = {
     // mirror final submission format: send stringified JSON
-    submission_data: JSON.stringify(inputData)
+    // submission_data: JSON.stringify(inputData),
+    submissionData: JSON.stringify(inputData)
   };
 
   if (!url || !clientKey) {