@defra-fish/sales-api-service 1.76.0-rc.5 → 1.77.0-rc.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defra-fish/sales-api-service",
-  "version": "1.76.0-rc.5",
+  "version": "1.77.0-rc.1",
   "description": "Rod Licensing Sales API",
   "type": "module",
   "engines": {
@@ -35,9 +35,9 @@
     "test": "echo \"Error: run tests from root\" && exit 1"
   },
   "dependencies": {
-    "@defra-fish/business-rules-lib": "1.76.0-rc.5",
-    "@defra-fish/connectors-lib": "1.76.0-rc.5",
-    "@defra-fish/dynamics-lib": "1.76.0-rc.5",
+    "@defra-fish/business-rules-lib": "1.77.0-rc.1",
+    "@defra-fish/connectors-lib": "1.77.0-rc.1",
+    "@defra-fish/dynamics-lib": "1.77.0-rc.1",
     "@hapi/boom": "9.1.2",
     "@hapi/hapi": "20.1.3",
     "@hapi/inert": "6.0.3",
@@ -53,5 +53,5 @@
     "moment-timezone": "0.5.34",
     "uuid": "8.3.2"
   },
-  "gitHead": "68399ce4682d08a92e4c073b19f178294ad855dc"
+  "gitHead": "2d2758c633c72fb22cd69fd5c9cbf0046568a9a9"
 }

package/src/__mocks__/test-data.js

@@ -165,8 +165,28 @@ export const MOCK_1DAY_FULL_PERMIT_DYNAMICS_RESPONSE = {
   defra_itemid: '42289'
 }
 
+export const MOCK_8DAY_SENIOR_PERMIT_DYNAMICS_RESPONSE = {
+  '@odata.etag': 'W/"51026150"',
+  defra_availablefrom: '2017-03-31T23:00:00Z',
+  defra_availableto: '2021-03-31T22:59:00Z',
+  defra_durationnumericpart: 8,
+  defra_durationdaymonthyearpart: 910400000,
+  defra_numberofrods: 2,
+  defra_permittype: 910400000,
+  defra_advertisedprice: 12.0,
+  defra_datasource: 910400002,
+  defra_permitid: 'a01b34a0-0c66-e611-80dc-c4346bad0190',
+  defra_name: 'Coarse 8 day 2 Rod Licence (Senior)',
+  defra_permitsubtype: 910400001,
+  defra_isforfulfilment: false,
+  defra_iscountersales: true,
+  defra_recurringsupported: false,
+  defra_itemid: '42291'
+}
+
 export const MOCK_1DAY_SENIOR_PERMIT_ENTITY = Permit.fromResponse(MOCK_1DAY_SENIOR_PERMIT_DYNAMICS_RESPONSE, optionSetData)
 export const MOCK_1DAY_FULL_PERMIT_ENTITY = Permit.fromResponse(MOCK_1DAY_FULL_PERMIT_DYNAMICS_RESPONSE, optionSetData)
+export const MOCK_8DAY_SENIOR_PERMIT_ENTITY = Permit.fromResponse(MOCK_8DAY_SENIOR_PERMIT_DYNAMICS_RESPONSE, optionSetData)
 
 export const MOCK_12MONTH_SENIOR_PERMIT_DYNAMICS_RESPONSE = {
   '@odata.etag': 'W/"51026180"',
@@ -204,9 +224,47 @@ export const MOCK_12MONTH_DISABLED_PERMIT_DYNAMICS_RESPONSE = {
   defra_recurringsupported: true,
   defra_itemid: '42376'
 }
+export const MOCK_12MONTH_JUNIOR_PERMIT_DYNAMICS_RESPONSE = {
+  '@odata.etag': 'W/"51026204"',
+  defra_availablefrom: '2017-03-31T23:00:00Z',
+  defra_availableto: '2021-03-31T22:59:00Z',
+  defra_durationnumericpart: 12,
+  defra_durationdaymonthyearpart: 910400001,
+  defra_numberofrods: 2,
+  defra_permittype: 910400000,
+  defra_advertisedprice: 6.0,
+  defra_datasource: 910400002,
+  defra_permitid: 'f21b34a0-0c66-e611-80dc-c4346bad0190',
+  defra_name: 'Coarse 12 month 2 Rod Licence (Junior)',
+  defra_permitsubtype: 910400001,
+  defra_isforfulfilment: true,
+  defra_iscountersales: true,
+  defra_recurringsupported: true,
+  defra_itemid: '42410'
+}
+export const MOCK_12MONTH_FULL_PERMIT_DYNAMICS_RESPONSE = {
+  '@odata.etag': 'W/"51026211"',
+  defra_availablefrom: '2017-03-31T23:00:00Z',
+  defra_availableto: '2021-03-31T22:59:00Z',
+  defra_durationnumericpart: 12,
+  defra_durationdaymonthyearpart: 910400001,
+  defra_numberofrods: 2,
+  defra_permittype: 910400000,
+  defra_advertisedprice: 54.0,
+  defra_datasource: 910400002,
+  defra_permitid: 'f41b34a0-0c66-e611-80dc-c4346bad0190',
+  defra_name: 'Coarse 12 month 2 Rod Licence (Full)',
+  defra_permitsubtype: 910400001,
+  defra_isforfulfilment: true,
+  defra_iscountersales: true,
+  defra_recurringsupported: true,
+  defra_itemid: '42420'
+}
 
 export const MOCK_12MONTH_SENIOR_PERMIT = Permit.fromResponse(MOCK_12MONTH_SENIOR_PERMIT_DYNAMICS_RESPONSE, optionSetData)
 export const MOCK_12MONTH_DISABLED_PERMIT = Permit.fromResponse(MOCK_12MONTH_DISABLED_PERMIT_DYNAMICS_RESPONSE, optionSetData)
+export const MOCK_12MONTH_JUNIOR_PERMIT = Permit.fromResponse(MOCK_12MONTH_JUNIOR_PERMIT_DYNAMICS_RESPONSE, optionSetData)
+export const MOCK_12MONTH_FULL_PERMIT = Permit.fromResponse(MOCK_12MONTH_FULL_PERMIT_DYNAMICS_RESPONSE, optionSetData)
 
 export const MOCK_CONCESSION_PROOF_ENTITY = ConcessionProof.fromResponse(
   {

package/src/schema/__tests__/licence-details.schema.spec.js

@@ -0,0 +1,93 @@
+import moment from 'moment'
+import { licenceDetailsRequestQuerySchema, licenceDetailsResponseSchema } from '../licence-details.schema.js'
+
+const getRequestSampleData = () => ({
+  licenseeFirstName: 'Laila',
+  licenseeLastName: 'Alial',
+  licenseeBirthDate: '2000-10-03',
+  licenseePostcode: 'W8 7PP'
+})
+
+const optionSetOptionSample = () => ({ id: 910400000, label: 'Example Label', description: 'Example Description' })
+
+const addDays = days => moment().add(days, 'days').toISOString()
+
+const getResponseSampleData = () => ({
+  licences: [
+    {
+      id: 'a17fc331-141b-4fc0-8549-329d6934fadb',
+      referenceNumber: '00310321-2DC3FAS-F4A315',
+      issueDate: new Date().toISOString(),
+      startDate: addDays(7),
+      endDate: addDays(7 + 365),
+      stagingId: 'a17fc331-141b-4fc0-8549-329d6934fadb',
+      licensee: {
+        firstName: 'Laila',
+        lastName: 'Alial',
+        birthDate: '2000-10-03',
+        premises: '1',
+        town: 'Exampleton',
+        postcode: 'W8 7PP',
+        country: optionSetOptionSample()
+      },
+      permit: {
+        id: 'a17fc331-141b-4fc0-8549-329d6934fadb',
+        description: 'Coarse 12 month 3 Rod Licence',
+        availableFrom: new Date().toISOString(),
+        availableTo: new Date().toISOString(),
+        isForFulfilment: true,
+        isCounterSales: false,
+        isRecurringPaymentSupported: true
+      }
+    }
+  ]
+})
+
+describe('licenceDetailsRequestQuerySchema', () => {
+  it('validates successfully when all query parameters are valid', async () => {
+    const result = await licenceDetailsRequestQuerySchema.validateAsync(getRequestSampleData())
+    expect(result).toEqual(getRequestSampleData())
+  })
+
+  it.each([['licenseeFirstName'], ['licenseeLastName'], ['licenseeBirthDate'], ['licenseePostcode']])(
+    'fails when %s is missing',
+    async field => {
+      const { [field]: _, ...invalidData } = getRequestSampleData()
+      await expect(licenceDetailsRequestQuerySchema.validateAsync(invalidData)).rejects.toThrow(`"${field}" is required`)
+    }
+  )
+
+  it('validates and formats a UK postcode', async () => {
+    const result = await licenceDetailsRequestQuerySchema.validateAsync({ ...getRequestSampleData(), licenseePostcode: 'w87pp' })
+    expect(result.licenseePostcode).toBe('W8 7PP')
+  })
+
+  it('validates an overseas postcode', async () => {
+    const result = await licenceDetailsRequestQuerySchema.validateAsync({ ...getRequestSampleData(), licenseePostcode: '90210' })
+    expect(result.licenseePostcode).toBe('90210')
+  })
+
+  it('fails when the postcode is invalid', async () => {
+    await expect(
+      licenceDetailsRequestQuerySchema.validateAsync({ ...getRequestSampleData(), licenseePostcode: '!!invalid!!' })
+    ).rejects.toThrow('"licenseePostcode" does not match any of the allowed types')
+  })
+})
+
+describe('licenceDetailsResponseSchema', () => {
+  it('validates successfully with a valid licences array', async () => {
+    const sampleData = getResponseSampleData()
+    const result = await licenceDetailsResponseSchema.validateAsync(sampleData)
+    expect(result).toEqual(sampleData)
+  })
+
+  it('fails when the licences array is missing', async () => {
+    await expect(licenceDetailsResponseSchema.validateAsync({})).rejects.toThrow('"licences" is required')
+  })
+
+  it('fails when a nested field is invalid', async () => {
+    const invalidData = getResponseSampleData()
+    invalidData.licences[0].permit.id = 'not-a-guid'
+    await expect(licenceDetailsResponseSchema.validateAsync(invalidData)).rejects.toThrow('"licences[0].permit.id" must be a valid GUID')
+  })
+})

package/src/schema/licence-details.schema.js

@@ -0,0 +1,29 @@
+import Joi from 'joi'
+import { validation } from '@defra-fish/business-rules-lib'
+import { permitSchema } from './permit.schema.js'
+import { contactResponseSchema } from './contact.schema.js'
+import { finalisedPermissionSchemaContent } from './permission.schema.js'
+
+export const licenceDetailsRequestQuerySchema = Joi.object({
+  licenseeFirstName: validation.contact.createFirstNameValidator(Joi).description('The first name of the licensee'),
+  licenseeLastName: validation.contact.createLastNameValidator(Joi).description('The last name of the licensee'),
+  licenseeBirthDate: validation.contact.createBirthDateValidator(Joi).description('The date of birth of the licensee'),
+  licenseePostcode: Joi.alternatives()
+    .try(
+      validation.contact.createUKPostcodeValidator(Joi).description('The postcode of the licensee'),
+      validation.contact.createOverseasPostcodeValidator(Joi)
+    )
+    .required()
+}).label('licence-details-request-query')
+
+export const licenceDetailsResponseSchema = Joi.object({
+  licences: Joi.array()
+    .items(
+      Joi.object({
+        ...finalisedPermissionSchemaContent,
+        licensee: contactResponseSchema,
+        permit: permitSchema
+      })
+    )
+    .required()
+}).label('licence-details-response')

package/src/schema/payment-journal.schema.js

@@ -3,17 +3,10 @@ import { v4 as uuidv4 } from 'uuid'
 import { PAYMENT_JOURNAL_STATUS_CODES } from '@defra-fish/business-rules-lib'
 
 export const paymentJournalEntryParamsSchema = Joi.object({
-  id: Joi.string()
-    .min(1)
-    .trim()
-    .required()
-    .description('The payment journal identifier')
-    .example(uuidv4())
+  id: Joi.string().min(1).trim().required().description('The payment journal identifier').example(uuidv4())
 })
 
-const paymentReferenceSchema = Joi.string()
-  .min(1)
-  .example(uuidv4())
+const paymentReferenceSchema = Joi.string().min(1).example(uuidv4())
 const paymentTimestampSchema = Joi.string()
   .isoDate()
   .required()
@@ -40,17 +33,17 @@ export const createPaymentJournalRequestSchema = Joi.object({
 export const updatePaymentJournalRequestSchema = Joi.object({
   paymentReference: paymentReferenceSchema.optional(),
   paymentTimestamp: paymentTimestampSchema.optional(),
-  paymentStatus: paymentStatusSchema.optional()
+  paymentStatus: paymentStatusSchema.optional(),
+  eligibleForEarlyMopUp: Joi.boolean()
+    .description('A flag showing whether the payment journal can be mopped up before the normal elapsed time has occurred')
+    .optional()
 })
-  .or('paymentTimestamp', 'paymentReference', 'paymentStatus')
+  .or('paymentTimestamp', 'paymentReference', 'paymentStatus', 'eligibleForEarlyMopUp')
   .label('update-payment-journal-request')
 
 export const paymentJournalResponseSchema = createPaymentJournalRequestSchema
   .append({
-    id: Joi.string()
-      .trim()
-      .required()
-      .example(uuidv4()),
+    id: Joi.string().trim().required().example(uuidv4()),
     expires: Joi.number().required()
   })
   .label('payment-journal-response')
@@ -61,20 +54,12 @@ export const paymentJournalResponseSchema = createPaymentJournalRequestSchema
  */
 export const paymentJournalQueryParams = Joi.object({
   paymentStatus: paymentStatusSchema,
-  from: Joi.string()
-    .isoDate()
-    .required()
-    .description('From date (inclusive)'),
-  to: Joi.string()
-    .isoDate()
-    .required()
-    .description('To date (inclusive)')
+  from: Joi.string().isoDate().required().description('From date (inclusive)'),
+  to: Joi.string().isoDate().required().description('To date (inclusive)')
 }).external(value => {
   if (value.from > value.to) {
     throw new Error('From date must not be after to date')
   }
 })
 
-export const paymentJournalQueryResponse = Joi.array()
-  .items(paymentJournalResponseSchema)
-  .label('payment-journal-query-response')
+export const paymentJournalQueryResponse = Joi.array().items(paymentJournalResponseSchema).label('payment-journal-query-response')

package/src/server/routes/__tests__/licence-details.spec.js

@@ -0,0 +1,258 @@
+import moment from 'moment'
+import { contactForLicenseeByPersonalDetails, executeQuery, permissionForContacts, Permission } from '@defra-fish/dynamics-lib'
+import route, { getLicenceDetails } from '../licence-details.js'
+import db from 'debug'
+import {
+  MOCK_EXISTING_PERMISSION_ENTITY,
+  MOCK_EXISTING_CONTACT_ENTITY,
+  MOCK_1DAY_SENIOR_PERMIT_ENTITY,
+  MOCK_8DAY_SENIOR_PERMIT_ENTITY,
+  MOCK_12MONTH_SENIOR_PERMIT,
+  MOCK_12MONTH_DISABLED_PERMIT,
+  MOCK_12MONTH_JUNIOR_PERMIT,
+  MOCK_12MONTH_FULL_PERMIT
+} from '../../../__mocks__/test-data.js'
+
+jest.mock('@defra-fish/dynamics-lib', () => ({
+  ...jest.requireActual('@defra-fish/dynamics-lib'),
+  contactForLicenseeByPersonalDetails: jest.fn(),
+  executeQuery: jest.fn(),
+  permissionForContacts: jest.fn()
+}))
+
+jest.mock('debug', () => jest.fn(() => jest.fn()))
+const { value: mockDebug } = db.mock.results[db.mock.calls.findIndex(c => c[0] === 'sales:licence-details')]
+
+describe('licence-details handler', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+    contactForLicenseeByPersonalDetails.mockReturnValue({ filter: 'mock-contact-filter' })
+    permissionForContacts.mockImplementation(contactIds => ({ filter: `contactIds eq ${contactIds.join(',')}` }))
+  })
+
+  const baseRequest = {
+    query: {
+      licenseeFirstName: 'Bilbo',
+      licenseeLastName: 'Baggins',
+      licenseeBirthDate: '2000-10-03',
+      licenseePostcode: 'AB12 3CD'
+    }
+  }
+
+  const mockContact = () => ({ entity: MOCK_EXISTING_CONTACT_ENTITY, expanded: {} })
+
+  const addDays = days => moment().add(days, 'days').toISOString()
+
+  const mockPermission = ({ permit = MOCK_12MONTH_SENIOR_PERMIT, startDate = addDays(-30), endDate = addDays(30) } = {}) => ({
+    entity: Object.assign(new Permission(), MOCK_EXISTING_PERMISSION_ENTITY, { startDate, endDate }),
+    expanded: {
+      licensee: { entity: MOCK_EXISTING_CONTACT_ENTITY, expanded: {} },
+      permit: { entity: permit, expanded: {} }
+    }
+  })
+
+  const expectNotFoundError = promise =>
+    expect(promise).rejects.toMatchObject({
+      output: {
+        statusCode: 404,
+        payload: {
+          error: 'Not Found',
+          message: 'Licence details could not be found for the provided contact details',
+          statusCode: 404
+        }
+      }
+    })
+
+  const mockContactWithPermissions = (...permissions) => {
+    executeQuery.mockResolvedValueOnce([mockContact()])
+    executeQuery.mockResolvedValueOnce(permissions)
+  }
+
+  it('registers the expected route metadata', () => {
+    const routeMetadata = {
+      method: route[0].method,
+      path: route[0].path,
+      description: route[0].options.description,
+      notes: route[0].options.notes.trim(),
+      tags: route[0].options.tags
+    }
+
+    expect(routeMetadata).toMatchInlineSnapshot(`
+      Object {
+        "description": "Look up licence details for a licensee using their name, postcode and date of birth",
+        "method": "GET",
+        "notes": "Look up licence details for a licensee using their name, postcode and date of birth",
+        "path": "/licenceDetails",
+        "tags": Array [
+          "api",
+          "licence-details",
+        ],
+      }
+    `)
+  })
+
+  it('returns 500 if executeQuery throws', async () => {
+    executeQuery.mockRejectedValueOnce(new Error('some error'))
+
+    await expect(getLicenceDetails(baseRequest)).rejects.toThrow('some error')
+    expect(mockDebug).toHaveBeenCalledWith('Error executing query with filter mock-contact-filter')
+  })
+
+  it('logs an unknown filter if executeQuery throws with no query', async () => {
+    contactForLicenseeByPersonalDetails.mockReturnValueOnce(undefined)
+    executeQuery.mockRejectedValueOnce(new Error('some error'))
+
+    await expect(getLicenceDetails(baseRequest)).rejects.toThrow('some error')
+    expect(mockDebug).toHaveBeenCalledWith('Error executing query with filter unknown')
+  })
+
+  it.each([
+    ['Frodo', 'Underhill', '1993-09-22', 'EF45 6GH'],
+    ['Samwise', 'Gamgee', '1998-03-06', 'IJ78 9KL'],
+    ['Peregrin', 'Took', '1994-04-01', 'ZZ99 9ZZ']
+  ])(
+    'calls contactForLicenseeByPersonalDetails with the name, dob and postcode from the query (%s %s)',
+    async (licenseeFirstName, licenseeLastName, licenseeBirthDate, licenseePostcode) => {
+      mockContactWithPermissions(mockPermission())
+      const query = { licenseeFirstName, licenseeLastName, licenseeBirthDate, licenseePostcode }
+
+      await getLicenceDetails({ query })
+
+      expect(contactForLicenseeByPersonalDetails).toHaveBeenCalledWith(query)
+    }
+  )
+
+  it('throws a not found error if no contacts match the provided details', async () => {
+    executeQuery.mockResolvedValueOnce([])
+
+    await expectNotFoundError(getLicenceDetails(baseRequest))
+  })
+
+  it('does not call permissionForContacts if no contacts match the provided details', async () => {
+    executeQuery.mockResolvedValueOnce([])
+
+    await expect(getLicenceDetails(baseRequest)).rejects.toThrow()
+    expect(permissionForContacts).not.toHaveBeenCalled()
+  })
+
+  it('calls permissionForContacts with contact ids from contactForLicenseeByPersonalDetails', async () => {
+    mockContactWithPermissions(mockPermission())
+
+    await getLicenceDetails(baseRequest)
+
+    expect(permissionForContacts).toHaveBeenCalledWith([MOCK_EXISTING_CONTACT_ENTITY.id])
+  })
+
+  it('throws a not found error if no permissions are found for the matching contacts', async () => {
+    executeQuery.mockResolvedValueOnce([mockContact()])
+    executeQuery.mockResolvedValueOnce([])
+
+    await expectNotFoundError(getLicenceDetails(baseRequest))
+  })
+
+  it('returns licence details matching the expected shape', async () => {
+    const permission = mockPermission()
+    mockContactWithPermissions(permission)
+
+    await expect(getLicenceDetails(baseRequest)).resolves.toMatchObject({
+      licences: [
+        expect.objectContaining({
+          ...permission.entity.toJSON(),
+          licensee: MOCK_EXISTING_CONTACT_ENTITY.toJSON(),
+          permit: MOCK_12MONTH_SENIOR_PERMIT.toJSON()
+        })
+      ]
+    })
+  })
+
+  it('returns multiple licences when more than one permission matches', async () => {
+    mockContactWithPermissions(mockPermission(), mockPermission())
+
+    const result = await getLicenceDetails(baseRequest)
+
+    expect(result).toMatchObject({
+      licences: expect.arrayContaining([expect.any(Object), expect.any(Object)])
+    })
+  })
+
+  it('returns 2 licences when more than one permission matches', async () => {
+    mockContactWithPermissions(mockPermission(), mockPermission())
+
+    const result = await getLicenceDetails(baseRequest)
+
+    expect(result.licences).toHaveLength(2)
+  })
+
+  it.each([
+    ['1-day', MOCK_1DAY_SENIOR_PERMIT_ENTITY],
+    ['8-day', MOCK_8DAY_SENIOR_PERMIT_ENTITY]
+  ])('excludes %s permits from the response', async (_, permit) => {
+    mockContactWithPermissions(mockPermission({ permit }))
+
+    await expectNotFoundError(getLicenceDetails(baseRequest))
+  })
+
+  it('excludes expired licences from the response', async () => {
+    mockContactWithPermissions(mockPermission({ endDate: addDays(-1) }))
+
+    await expectNotFoundError(getLicenceDetails(baseRequest))
+  })
+
+  it('includes licences that have been issued but have not yet started', async () => {
+    mockContactWithPermissions(mockPermission({ startDate: addDays(30), endDate: addDays(395) }))
+
+    await expect(getLicenceDetails(baseRequest)).resolves.toMatchObject({
+      licences: [expect.any(Object)]
+    })
+  })
+
+  it.each([
+    ['junior', MOCK_12MONTH_JUNIOR_PERMIT],
+    ['full', MOCK_12MONTH_FULL_PERMIT],
+    ['full, disabled', MOCK_12MONTH_DISABLED_PERMIT],
+    ['senior', MOCK_12MONTH_SENIOR_PERMIT]
+  ])('includes active twelve month licences for %s permits regardless of concession', async (_, permit) => {
+    mockContactWithPermissions(mockPermission({ permit }))
+
+    await expect(getLicenceDetails(baseRequest)).resolves.toMatchObject({
+      licences: [expect.any(Object)]
+    })
+  })
+
+  it('returns a valid result for a matching contact', async () => {
+    mockContactWithPermissions(mockPermission())
+
+    await expect(getLicenceDetails(baseRequest)).resolves.toMatchObject({
+      licences: [
+        expect.objectContaining({
+          id: MOCK_EXISTING_PERMISSION_ENTITY.id,
+          licensee: MOCK_EXISTING_CONTACT_ENTITY.toJSON(),
+          permit: MOCK_12MONTH_SENIOR_PERMIT.toJSON()
+        })
+      ]
+    })
+  })
+
+  it('documents the validation contract for the route query string', () => {
+    expect(route[0].options.validate.query).toBeDefined()
+  })
+
+  it('handler wraps the licence details in a 200 response', async () => {
+    mockContactWithPermissions(mockPermission())
+    const code = jest.fn()
+    const h = { response: jest.fn().mockReturnValue({ code }) }
+
+    await route[0].options.handler(baseRequest, h)
+
+    expect(h.response).toHaveBeenCalledWith({
+      licences: [
+        expect.objectContaining({
+          id: MOCK_EXISTING_PERMISSION_ENTITY.id,
+          licensee: MOCK_EXISTING_CONTACT_ENTITY.toJSON(),
+          permit: MOCK_12MONTH_SENIOR_PERMIT.toJSON()
+        })
+      ]
+    })
+    expect(code).toHaveBeenCalledWith(200)
+  })
+})

package/src/server/routes/__tests__/payment-journals.spec.js

@@ -132,7 +132,7 @@ describe('payment journals handlers', () => {
       expect(JSON.parse(result.payload)).toMatchObject({
         error: 'Unprocessable Entity',
         message:
-          'Invalid payload: "update-payment-journal-request" must contain at least one of [paymentTimestamp, paymentReference, paymentStatus]',
+          'Invalid payload: "update-payment-journal-request" must contain at least one of [paymentTimestamp, paymentReference, paymentStatus, eligibleForEarlyMopUp]',
         statusCode: 422
       })
     })

package/src/server/routes/index.js

@@ -8,6 +8,7 @@ import Authenticate from './authenticate.js'
 import Users from './system-users.js'
 import RecurringPayment from './recurring-payments.js'
 import Renewals from './renewals.js'
+import LicenceDetails from './licence-details.js'
 
 import Static from './static.js'
 
@@ -22,5 +23,6 @@ export default [
   ...Authenticate,
   ...Users,
   ...RecurringPayment,
-  ...Renewals
+  ...Renewals,
+  ...LicenceDetails
 ]

package/src/server/routes/licence-details.js

@@ -0,0 +1,86 @@
+import Boom from '@hapi/boom'
+import { licenceDetailsRequestQuerySchema, licenceDetailsResponseSchema } from '../../schema/licence-details.schema.js'
+import db from 'debug'
+import { permissionForContacts, contactForLicenseeByPersonalDetails, executeQuery } from '@defra-fish/dynamics-lib'
+
+const debug = db('sales:licence-details')
+const failLicenceDetails = 'Licence details could not be found for the provided contact details'
+const HTTP_OK = 200
+const TWELVE_MONTH_DURATION_MAGNITUDE = 12
+const TWELVE_MONTH_DURATION_DESIGNATOR = 'M'
+
+const executeWithErrorLog = async query => {
+  try {
+    return await executeQuery(query)
+  } catch (e) {
+    debug(`Error executing query with filter ${query?.filter ?? 'unknown'}`)
+    throw e
+  }
+}
+
+const isActiveTwelveMonthLicence = permission => {
+  const { durationMagnitude, durationDesignator } = permission.expanded.permit.entity
+  const isTwelveMonthPermit =
+    durationMagnitude === TWELVE_MONTH_DURATION_MAGNITUDE && durationDesignator.description === TWELVE_MONTH_DURATION_DESIGNATOR
+  const hasNotExpired = new Date(permission.entity.endDate) >= new Date()
+  return isTwelveMonthPermit && hasNotExpired
+}
+
+export const getLicenceDetails = async request => {
+  const { licenseeFirstName, licenseeLastName, licenseeBirthDate, licenseePostcode } = request.query
+  const contacts = await executeWithErrorLog(
+    contactForLicenseeByPersonalDetails({ licenseeFirstName, licenseeLastName, licenseeBirthDate, licenseePostcode })
+  )
+
+  if (!contacts.length) {
+    throw Boom.notFound(failLicenceDetails)
+  }
+
+  const contactIds = contacts.map(contact => contact.entity.id)
+  const permissions = await executeWithErrorLog(permissionForContacts(contactIds))
+  const activeLicences = permissions.filter(isActiveTwelveMonthLicence)
+
+  if (!activeLicences.length) {
+    throw Boom.notFound(failLicenceDetails)
+  }
+
+  return {
+    licences: activeLicences.map(permission => ({
+      ...permission.entity.toJSON(),
+      licensee: permission.expanded.licensee.entity.toJSON(),
+      permit: permission.expanded.permit.entity.toJSON()
+    }))
+  }
+}
+
+const handler = async (request, h) => {
+  const licenceDetails = await getLicenceDetails(request)
+  return h.response(licenceDetails).code(HTTP_OK)
+}
+
+export default [
+  {
+    method: 'GET',
+    path: '/licenceDetails',
+    options: {
+      handler,
+      description: 'Look up licence details for a licensee using their name, postcode and date of birth',
+      notes: `
+        Look up licence details for a licensee using their name, postcode and date of birth
+      `,
+      tags: ['api', 'licence-details'],
+      validate: {
+        query: licenceDetailsRequestQuerySchema
+      },
+      plugins: {
+        'hapi-swagger': {
+          responses: {
+            200: { description: 'Licence details were found for the given contact details', schema: licenceDetailsResponseSchema },
+            404: { description: failLicenceDetails }
+          },
+          order: 1
+        }
+      }
+    }
+  }
+]

package/src/services/paymentjournals/__tests__/payment-journals.service.spec.js

@@ -27,7 +27,7 @@ describe('payment-journals service', () => {
       await createPaymentJournal('test-id', { some: 'data' })
       expect(docClient.put).toHaveBeenCalledWith({
         TableName: PAYMENTS_TABLE.TableName,
-        Item: { id: 'test-id', some: 'data', expires: expect.any(Number) },
+        Item: { id: 'test-id', some: 'data', eligibleForEarlyMopUp: false, expires: expect.any(Number) },
         ConditionExpression: 'attribute_not_exists(id)'
       })
     })

package/src/services/paymentjournals/payment-journals.service.js

@@ -10,7 +10,7 @@ const debug = db('sales:paymentjournals')
  * @returns {Promise<*>}
  */
 export async function createPaymentJournal (id, payload) {
-  const record = { id, expires: Math.floor(Date.now() / 1000) + PAYMENTS_TABLE.Ttl, ...payload }
+  const record = { id, expires: Math.floor(Date.now() / 1000) + PAYMENTS_TABLE.Ttl, eligibleForEarlyMopUp: false, ...payload }
   await docClient.put({ TableName: PAYMENTS_TABLE.TableName, Item: record, ConditionExpression: 'attribute_not_exists(id)' })
   debug('Payment journal stored with payload %o', record)
   return record

package/src/services/transactions/__tests__/finalise-transaction.spec.js

@@ -11,6 +11,7 @@ import BusinessRulesLib from '@defra-fish/business-rules-lib'
 import moment from 'moment'
 import { TRANSACTION_STATUS } from '../constants.js'
 import permissionsService from '../../permissions.service.js'
+import { updatePaymentJournal } from '../../paymentjournals/payment-journals.service.js'
 import { AWS } from '@defra-fish/connectors-lib'
 import db from 'debug'
 
@@ -19,6 +20,8 @@ const { docClient, sqs } = AWS.mock.results[0].value
 const debugLogger = db.mock.results[1].value // first call is by retrieve-transaction.js
 global.structuredClone = global.structuredClone ?? (obj => JSON.parse(JSON.stringify(obj)))
 
+jest.mock('../../paymentjournals/payment-journals.service.js')
+
 jest.mock('../../permissions.service.js', () => ({
   generatePermissionNumber: jest.fn(() => MOCK_PERMISSION_NUMBER),
   calculateEndDate: jest.fn(() => MOCK_END_DATE)
@@ -327,6 +330,18 @@ describe('transaction service', () => {
         expect(docClient.createUpdateExpression).toHaveBeenNthCalledWith(2, originalRecord)
       })
 
+      it('updates the payment journal to be eligible for mop-up when the SQS message fails to send', async () => {
+        const { mockRecord } = sqsFailureSetup()
+        try {
+          await finaliseTransaction({
+            id: mockRecord.id,
+            payment: getSamplePayment()
+          })
+        } catch (e) {}
+
+        expect(updatePaymentJournal).toHaveBeenCalledWith(mockRecord.id, expect.objectContaining({ eligibleForEarlyMopUp: true }))
+      })
+
       it('throws an internal server error if the SQS message fails to send', async () => {
         const {
           mockRecord: { id }

package/src/services/transactions/finalise-transaction.js

@@ -8,6 +8,7 @@ import moment from 'moment'
 import Boom from '@hapi/boom'
 import { AWS } from '@defra-fish/connectors-lib'
 import db from 'debug'
+import { updatePaymentJournal } from '../paymentjournals/payment-journals.service.js'
 const { sqs, docClient } = AWS()
 const debug = db('sales:transactions')
 
@@ -77,6 +78,7 @@ export async function finaliseTransaction ({ id, ...payload }) {
           ...docClient.createUpdateExpression(originalTransactionRecord),
           ReturnValues: 'ALL_NEW'
         })
+        await updatePaymentJournal(id, { eligibleForEarlyMopUp: true })
       } catch (rollbackError) {
         throw Boom.internal(`Failed to rollback transaction record ${id} after SQS send failure`, rollbackError)
       }