@gov-cy/govcy-express-services 0.1.3 → 0.1.5

package/README.md

@@ -14,6 +14,8 @@
 ## 📝 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.
 
+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/). 
+
 ![govcy-express-services](express-services.png)
 
 ## Table of contents
@@ -22,6 +24,7 @@ This project is an Express-based project that dynamically renders online service
 - [✨ Features](#-features)
 - [📋 Prerequisites](#-prerequisites)
 - [🚀 Quick start](#-quick-start)
+- [✅ Best Practices](#-best-practices)
 - [📦 Full installation guide](#-full-installation-guide)
 - [🛠️ Usage](#%EF%B8%8F-usage)
   - [🧩 Dynamic services rendering](#-dynamic-services-rendering)
@@ -97,6 +100,15 @@ For more details on configuration, environment variables, and advanced features,
 ## 📦 Full installation guide
 The project acts as an npm package and you need to install it as a dependency in your npm project. Check out the [install notes](INSTALL-NOTES.md) a detailed installation guide.
 
+## ✅ Best Practices
+
+Before starting your service, please review the [Best Practices guide](BEST-PRACTICES.md) for guidance on:
+
+- Repository structure
+- Environment separation (`dev` / `staging` / `prod`)
+- Secure CY Login client registration
+- Mandatory footer pages (privacy, cookies, accessibility)
+
 ## 🛠️ Usage
 ### Starting the Server
 Add in your `package.json`:
@@ -141,7 +153,7 @@ Here are some details explaining the JSON structure:
 A typical service flow that includes pages `index`, `question-1`, `question-2` under the `pages` array in the JSON file looks like this:
 
 ```mermaid
-flowchart TD
+flowchart LR
     govcy-page --> isAuth{Is User Authenticated?}
     isAuth -- Yes<br><br> Eligibility Check --> index([:siteId/index])
     isAuth -- No --> cyLogin[cyLogin]
@@ -281,6 +293,11 @@ Lets break down the JSON config for this page:
   - Not perform the eligibility checks
   - Display the static content
 
+When designing form pages, refer to the Unified Design System's [question pages pattern](https://gov-cy.github.io/govcy-design-system-docs/patterns/question_pages/).
+
+**Error pages**
+Pages that can be used to display messages when eligibility or submission fail are simply static content pages. That is pages that do not include a `form` element.
+
 **Notes**:
 - Check out the [govcy-frontend-renderer's design elements](https://github.com/gov-cy/govcy-frontend-renderer/blob/main/DESIGN_ELEMENTS.md) for more details on the supported elements and their parameters.
 - Check out the [input validations section](#-input-validations) for more details on how to add validations to the JSON file.
@@ -380,6 +397,32 @@ With the above config, when a user visits a page under the specific site, `/:sit
 
 The response is cached to the session storage for the specified number of minutes. If the `cashingTimeoutMinutes` is set to `0`, the API endpoint will be called every time.
 
+Here's a flowchart showing how the eligibility checks work:
+
+```mermaid
+flowchart LR
+    A[🧭 User visits /:siteId/* page] --> B{{❓ Are eligibilityAPIEndpoints configured?}}
+    B -- No --> H[✅ Access granted<br>Show page]
+    B -- Yes --> D[🔁 Loop through API endpoints]
+
+    D --> D1{{❓ Is cached response still valid?}}
+    D1 -- Yes --> D2[🗃️ Use cached result]
+    D1 -- No --> E[🔄 Send request with:<br>- Method GET or POST<br>- Auth header<br>- Params or body]
+
+    D2 --> F{{❓ Did cached result<br>have Succeeded: true?}}
+    E --> F
+
+    F -- Yes --> G{{❓ More endpoints to check?}}
+    G -- Yes --> D
+    G -- No --> H
+
+    F -- No --> I[📄 Check ErrorCode<br>in config]
+    I --> J{{❓ Is ErrorCode in config?}}
+    J -- Yes --> K[❌ Redirect to configured error page]
+    J -- No --> L[❌ Show generic error page]
+
+```
+
 #### Eligibility API request and response
 
 For each eligibility API endpoint, the project sends a request to the API endpoint. The project uses the [CY Connect - OAuth 2.0 (CY Login)](https://dev.azure.com/cyprus-gov-cds/Documentation/_wiki/wikis/Documentation/122/CY-Connect-OAuth-2.0-(CY-Login)) authentication policy, so the user's `<access_token>` is sent in the `Authorization` header.
@@ -508,6 +551,27 @@ TEST_SUBMISSION_API_SERVIVE_ID=123
 
 With the above config, when a user submits the `review` page, the service sends a request to the configured submission API endpoint.
 
+Here's a flowchart showing how the submission work:
+
+```mermaid
+
+flowchart LR
+    A[📤 User submits review page] --> B[🔄 Send POST request]
+
+    B --> C{{❓ Did response have Succeeded: true?}}
+
+    C -- Yes --> D[✅ Show success confirmation with reference code]
+
+    C -- No --> E[📄 Check ErrorCode in config]
+    E --> F{{❓ Is ErrorCode in config?}}
+    F -- Yes --> G[❌ Redirect to configured error page]
+    F -- No --> H[❌ Show generic error page]
+
+    B --> I{{❓ Did request fail or return invalid response?}}
+    I -- Yes --> H
+
+```
+
 #### Submission API Request and Response
 
 **Submission Request:**
@@ -602,7 +666,7 @@ The data is collected from the form elements and the data layer and are sent via
 ##### Submission Data Sample
 
 <details>
-  <summary>Here's a sample submission data JSON (as an object, before stringification)</summary>
+  <summary>Click here for a sample submission data JSON</summary>
 
 > ℹ️ **Note:**  
 >
@@ -1120,6 +1184,7 @@ Absolutely! Here’s a **ready-to-paste Troubleshooting / FAQ section** you can
 
 ## 🔒 Security note
 - Always set a strong, random `SESSION_SECRET` in your `.env` file. Never commit secrets or credentials to version control.
+- Add `.gitignore` & `.npmignore`: Ensure no real `.env`, `server.key`, or other sensitive files are published.
 - In production, ensure cookies are set with `secure`, `httpOnly`, and `sameSite` attributes to protect against common web vulnerabilities.
 - Make sure your server is running behind HTTPS in production.
 - Regularly rotate secrets and credentials, and restrict access to your `.env` and configuration files.

package/package.json

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