@defra/fcp-sfd-frontend-engine 0.22.1 → 0.24.0

package/src/services/initialise-fix-journey-service.js

@@ -0,0 +1,125 @@
+/**
+ * Initialises the fix journey in the user's session.
+ *
+ * This service is the single place where the fix journey order is defined.
+ * It calculates and stores the ordered list of either personal or business
+ * detail sections that the user needs to fix.
+ *
+ * This sets:
+ * - orderedSectionsToFix: the ordered list of sections to fix
+ * - source: the section the user selected to start the journey (if provided)
+ *
+ * If a source is provided, that section is placed first, followed by the
+ * remaining sections in the order defined by this service.
+ *
+ * Downstream routes and presenters read this data from the session and
+ * don't reorder it.
+ *
+ * @module initialiseFixJourneyService
+ */
+
+import {
+  PERSONAL_SECTION_ORDER,
+  BUSINESS_SECTION_ORDER
+} from '../constants/interrupter-journey.js'
+
+/**
+ * Initialises the fix journey session data.
+ *
+ * @param {Object} yar - Hapi session object
+ * @param {string} source - The section user clicked to fix (optional)
+ * @param {string} journeyType - Either 'personal' or 'business'
+ * @returns {Object|undefined} Updated session data, or undefined if session data does not exist
+ */
+const initialiseFixJourneyService = (yar, source, journeyType) => {
+  // Determined by journeyType
+  let sessionKey
+  let sectionOrder = []
+
+  if (journeyType === 'business') {
+    sessionKey = 'businessDetailsValidation'
+    sectionOrder = BUSINESS_SECTION_ORDER
+  }
+
+  if (journeyType === 'personal') {
+    sessionKey = 'personalDetailsValidation'
+    sectionOrder = PERSONAL_SECTION_ORDER
+  }
+
+  const sessionData = yar.get(sessionKey)
+
+  if (!sessionData?.sectionsNeedingUpdate) {
+    return sessionData
+  }
+
+  const orderedSectionsToFix = orderSectionsToFix(
+    sessionData.sectionsNeedingUpdate,
+    source,
+    sectionOrder
+  )
+
+  updateSessionData(sessionData, source, orderedSectionsToFix)
+
+  yar.set(sessionKey, sessionData)
+
+  return sessionData
+}
+
+/**
+ * Updates session data with the ordered sections and clears temporary fields.
+ *
+ * @param {Object} sessionData - The session data to update
+ * @param {string} source - The selected section (optional)
+ * @param {Array<string>} orderedSectionsToFix - Ordered list of sections to fix
+ */
+const updateSessionData = (sessionData, source, orderedSectionsToFix) => {
+  sessionData.orderedSectionsToFix = orderedSectionsToFix
+
+  // Clean up temporary fields used only during validation
+  delete sessionData.sectionsNeedingUpdate
+  delete sessionData.personalFixUpdates
+  delete sessionData.businessFixUpdates
+
+  if (source) {
+    sessionData.source = source
+  }
+}
+
+/**
+ * Returns an ordered list of sections that the user needs to fix.
+ *
+ * Sections are ordered based on how the personal/business details data
+ * is presented on the main page.
+ *
+ * If a source is provided, that section is moved to the top of the list.
+ * Source indicates which link the user clicked to get to the fix list page.
+ *
+ * @param {Array<string>} sectionsNeedingUpdate - Sections identified as needing fixes
+ * @param {string} source - The section user clicked on (optional)
+ * @param {Array<string>} SECTION_ORDER - The defined order for sections
+ * @returns {Array<string>} Ordered list of sections to fix
+ */
+const orderSectionsToFix = (sectionsNeedingUpdate, source, SECTION_ORDER) => {
+  const sections = SECTION_ORDER.filter((section) => {
+    return sectionsNeedingUpdate.includes(section)
+  })
+
+  if (!source) {
+    return sections
+  }
+
+  // Source comes from a URL query param, so only allow known section keys
+  // for this journey type to avoid injecting unexpected values into session state.
+  if (!SECTION_ORDER.includes(source)) {
+    return sections
+  }
+
+  return [
+    source,
+    ...sections.filter(section => section !== source)
+  ]
+}
+
+export {
+  initialiseFixJourneyService
+}

package/src/services/personal/build-customer-fix-update-variables-service.js

@@ -0,0 +1,76 @@
+/**
+ * Builds mutation variables for updating a user's personal details via the fix journey.
+ * Only includes the sections that actually need updating, using the
+ * unified `input` format for the GraphQL mutation.
+ *
+ * @module buildCustomerFixUpdateVariablesService
+ */
+
+import { buildManualAddress } from '../build-address-variables-service.js'
+
+const buildCustomerFixUpdateVariablesService = (personalDetails) => {
+  const { orderedSectionsToFix, crn } = personalDetails
+
+  const input = { crn }
+
+  // Conditionally merge each section into input if it's been updated by the user
+  if (orderedSectionsToFix.includes('name') && personalDetails.changePersonalName) {
+    Object.assign(input, buildNameInput(personalDetails.changePersonalName))
+  }
+
+  if (orderedSectionsToFix.includes('email') && personalDetails.changePersonalEmail) {
+    Object.assign(input, buildEmailInput(personalDetails.changePersonalEmail))
+  }
+
+  if (orderedSectionsToFix.includes('phone') && personalDetails.changePersonalPhoneNumbers) {
+    Object.assign(input, buildPhoneInput(personalDetails.changePersonalPhoneNumbers))
+  }
+
+  if (orderedSectionsToFix.includes('dob') && personalDetails.changePersonalDob) {
+    Object.assign(input, buildDobInput(personalDetails.changePersonalDob))
+  }
+
+  if (orderedSectionsToFix.includes('address') && personalDetails.changePersonalAddress) {
+    Object.assign(input, { address: buildManualAddress(personalDetails.changePersonalAddress) })
+  }
+
+  return { input }
+}
+
+const buildPhoneInput = (change) => {
+  return {
+    phone: {
+      landline: change.personalTelephone ?? null,
+      mobile: change.personalMobile ?? null
+    }
+  }
+}
+
+const buildEmailInput = (change) => {
+  return {
+    email: {
+      address: change.personalEmail
+    }
+  }
+}
+
+const buildNameInput = (change) => {
+  return {
+    first: change.first,
+    middle: change.middle ?? null,
+    last: change.last
+  }
+}
+
+const buildDobInput = (change) => {
+  const { day, month, year } = change
+
+  return {
+    // DAL expects dateOfBirth as YYYY-MM-DD e.g. '1990-04-05' not '1990-4-5'
+    dateOfBirth: `${year}-${String(month).padStart(2, '0')}-${String(day).padStart(2, '0')}`
+  }
+}
+
+export {
+  buildCustomerFixUpdateVariablesService
+}

package/src/services/services.js

@@ -1,8 +1,20 @@
 import { addressLookupService } from './os-places/address-lookup-service.js'
 import { buildUprnAddress, buildManualAddress } from './build-address-variables-service.js'
+import { checkInterrupterJourneySessionService } from './check-interrupter-journey-session-service.js'
+import { initialiseFixJourneyService } from './initialise-fix-journey-service.js'
+import { validateFixDetailsService } from './validate-fix-details-service.js'
+import { setFixSessionDataService } from './set-fix-session-data-service.js'
+import { buildFixSuccessMessageService } from './build-fix-success-message-service.js'
+import { buildCustomerFixUpdateVariablesService } from './personal/build-customer-fix-update-variables-service.js'
 
 export const services = {
   addressLookup: addressLookupService,
   buildUprnAddress,
-  buildManualAddress
+  buildManualAddress,
+  checkInterrupterJourneySession: checkInterrupterJourneySessionService,
+  initialiseFixJourney: initialiseFixJourneyService,
+  validateFixDetails: validateFixDetailsService,
+  setFixSessionData: setFixSessionDataService,
+  buildFixSuccessMessage: buildFixSuccessMessageService,
+  buildCustomerFixUpdateVariables: buildCustomerFixUpdateVariablesService
 }

package/src/services/set-fix-session-data-service.js

@@ -0,0 +1,124 @@
+/**
+ * Stores fix journey data on the session.
+ *
+ * This service is used during the interrupter journey to persist form data
+ * as users progress through multiple steps. When users provide updates to
+ * invalid personal or business details, their input is stored in the session
+ * so it can be reviewed and submitted in later steps.
+ *
+ * The service automatically determines whether this is a personal or business
+ * journey by examining the journeyKey parameter, then structures the payload
+ * data according to the appropriate section-based schema.
+ *
+ * Why this matters:
+ * - Users may need to fix multiple detail sections (e.g., name + address + email)
+ * - Each section has its own set of fields defined in SECTION_FIELD_ORDER
+ * - By organizing data by section, the review page can easily iterate and
+ *   display each section with its corresponding fields
+ * - Session storage preserves form state across page navigations
+ *
+ * Data structure example:
+ * For personal details with sections ['name', 'email']:
+ * {
+ *   personalFixUpdates: {
+ *     name: { first: 'John', middle: '', last: 'Doe' },
+ *     email: { personalEmail: 'john@example.com' }
+ *   }
+ * }
+ *
+ * @module setFixSessionDataService
+ */
+
+import {
+  PERSONAL_SECTION_FIELD_ORDER,
+  BUSINESS_SECTION_FIELD_ORDER
+} from '../constants/interrupter-journey.js'
+
+/**
+ * Maps form payload data into session storage, organized by detail sections.
+ *
+ * This function takes flat form submission data and restructures it into a
+ * hierarchical object where each section (e.g., 'name', 'email', 'address')
+ * contains its corresponding fields. Any fields missing from the payload
+ * are populated with empty strings, ensuring the session always has a
+ * complete structure for downstream presenters and services.
+ *
+ * The section-based structure is essential because:
+ * 1. The fix journey is organized by sections that need fixing
+ * 2. The review page displays each section separately
+ * 3. The mutation needs to know which fields belong to which section
+ * 4. Presenters can easily iterate sections and their fields
+ *
+ * @param {Object} yar - Hapi session object with get/set methods
+ * @param {Object} sessionData - Current session data object to be mutated; expects sessionData.orderedSectionsToFix to exist
+ * @param {Object} payload - Flat form submission data (e.g., { first: 'John', last: 'Doe', personalEmail: '...' })
+ *                        Example: ['name', 'address', 'email'] - order matches the presentation order
+ * @param {string} journeyKey - Session key that identifies the journey type
+ *                              - 'personalDetailsValidation' for personal details
+ *                              - 'businessDetailsValidation' for business details
+ *                              This key is used to auto-detect the journey type
+ * @param {string} updateKey - Object key where the structured updates are stored
+ *                              - 'personalFixUpdates' for personal details
+ *                              - 'businessFixUpdates' for business details
+ *
+ * @returns {void} Modifies sessionData in place and persists via yar.set()
+ *
+ * @example
+ * // Store personal detail updates
+ * setFixSessionDataService(
+ *   yar,
+ *   sessionData,
+ *   { first: 'Jane', last: '', personalEmail: 'jane@example.com' },
+ *   'personalDetailsValidation',
+ *   'personalFixUpdates'
+ * )
+ * // Result: sessionData.personalFixUpdates = {
+ * //   name: { first: 'Jane', middle: '', last: '' },
+ * //   email: { personalEmail: 'jane@example.com' }
+ * // }
+ */
+const setFixSessionDataService = (
+  yar,
+  sessionData,
+  payload,
+  journeyKey,
+  updateKey
+) => {
+  const orderedSectionsToFix = sessionData.orderedSectionsToFix
+  // Determine type from journey key
+  // This allows the service to auto-select the correct field schema
+  const type = journeyKey === 'businessDetailsValidation' ? 'business' : 'personal'
+
+  // Select the appropriate field order based on type
+  // Each type (personal/business) has different fields for each section
+  const SECTION_FIELD_ORDER = type === 'business' ? BUSINESS_SECTION_FIELD_ORDER : PERSONAL_SECTION_FIELD_ORDER
+
+  const fixUpdates = {}
+
+  // Loop through each section that needs fixing (e.g. name, email)
+  // The order is preserved from orderedSectionsToFix
+  for (const section of orderedSectionsToFix) {
+    const fields = SECTION_FIELD_ORDER[section]
+
+    fixUpdates[section] = {}
+
+    // Loop through each field in the section (e.g. firstName, lastName)
+    // This ensures all expected fields are present in the session,
+    // even if they weren't provided in the form submission
+    for (const field of fields) {
+      // Map the payload value to the session data, defaulting to an empty string if not provided
+      // Empty strings are used as defaults to maintain a consistent structure
+      // for downstream presenters and mutation builders
+      fixUpdates[section][field] = payload[field] ?? ''
+    }
+  }
+
+  // Store the structured updates in the session under the appropriate key
+  sessionData[updateKey] = fixUpdates
+  // Persist the updated session data
+  yar.set(journeyKey, sessionData)
+}
+
+export {
+  setFixSessionDataService
+}

package/src/services/validate-fix-details-service.js

@@ -0,0 +1,59 @@
+/**
+ * Validates fix payload data for personal or business details.
+ *
+ * This service validates the payload for each section the user is fixing
+ * (e.g. name, date of birth, email, business details), running each provided
+ * Joi schema separately and collecting any validation errors.
+ *
+ * The schemas are passed into the service and validated individually rather
+ * than being combined into a single Joi schema. Combining schemas previously
+ * caused issues with custom validation logic. For example, the date of birth
+ * schema includes custom validation to check for real and valid dates. When
+ * schemas were combined, failures in other schemas could prevent this custom
+ * validation from running, meaning some errors were not surfaced.
+ *
+ * By validating each schema independently (and allowing unknown fields), we
+ * ensure that all section-specific validation logic runs correctly and that
+ * all relevant errors are returned to the user.
+ *
+ * @module validateFixDetailsService
+ */
+
+/**
+ * Validates payload against multiple schemas for different sections.
+ *
+ * @param {Object} payload - The form data to validate
+ * @param {Array<string>} orderedSectionsToFix - List of sections being fixed
+ * @param {Object} schemas - Map of section names to Joi schemas
+ * @returns {Object} Joi validation result with combined errors
+ */
+const validateFixDetailsService = (payload, orderedSectionsToFix, schemas) => {
+  const errors = []
+
+  for (const section of orderedSectionsToFix) {
+    const schema = schemas[section]
+
+    const result = schema.validate(payload, {
+      abortEarly: false,
+      allowUnknown: true
+    })
+
+    if (result.error) {
+      errors.push(...result.error.details)
+    }
+  }
+
+  if (errors.length > 0) {
+    return {
+      error: {
+        details: errors
+      }
+    }
+  }
+
+  return { value: payload }
+}
+
+export {
+  validateFixDetailsService
+}