refactor for clarity

Author: nhsd-david-wass

internal/datastore/package.json

@@ -3,7 +3,7 @@
     "@aws-sdk/client-dynamodb": "^3.984.0",
     "@aws-sdk/lib-dynamodb": "^3.1008.0",
     "@internal/helpers": "*",
-    "@nhsdigital/nhs-notify-event-schemas-supplier-config": "^1.0.1",
+    "@nhsdigital/nhs-notify-event-schemas-supplier-config": "^1.1.0",
     "pino": "^10.3.0",
     "zod": "^4.1.11",
     "zod-mermaid": "^1.0.9"

lambdas/supplier-allocator/package.json

@@ -8,7 +8,7 @@
     "@nhsdigital/nhs-notify-event-schemas-letter-rendering": "2.0.1",
     "@nhsdigital/nhs-notify-event-schemas-letter-rendering-v1": "npm:@nhsdigital/nhs-notify-event-schemas-letter-rendering@^1.1.5",
     "@nhsdigital/nhs-notify-event-schemas-supplier-api": "^1.0.8",
-    "@nhsdigital/nhs-notify-event-schemas-supplier-config": "^1.0.1",
+    "@nhsdigital/nhs-notify-event-schemas-supplier-config": "^1.1.0",
     "@types/aws-lambda": "^8.10.148",
     "aws-embedded-metrics": "^4.2.1",
     "aws-lambda": "^1.0.7",

lambdas/supplier-allocator/src/handler/__tests__/allocate-handler.test.ts

@@ -14,6 +14,7 @@ import {
 import createSupplierAllocatorHandler from "../allocate-handler";
 import * as supplierConfig from "../../services/supplier-config";
 import * as supplierQuotas from "../../services/supplier-quotas";
+import * as allocationConfig from "../allocation-config";
 
 import { Deps } from "../../config/deps";
 import { EnvVars } from "../../config/env";
@@ -26,6 +27,7 @@ const renderingSchemaVersion: string =
 
 jest.mock("../../services/supplier-config");
 jest.mock("../../services/supplier-quotas");
+jest.mock("../allocation-config");
 
 function createSQSEvent(records: SQSRecord[]): SQSEvent {
   return {
@@ -154,26 +156,27 @@ function setupDefaultMocks() {
     id: "g1",
     status: "PROD",
   });
-  (
-    supplierConfig.getSupplierAllocationsForVolumeGroup as jest.Mock
-  ).mockResolvedValue([{ supplier: "s1" }]);
-  (supplierConfig.getSupplierDetails as jest.Mock).mockResolvedValue({
-    supplierId: "supplier-1",
-    specId: "spec-1",
-    priority: 1,
-    billingId: "billing-1",
+  (allocationConfig.eligibleSuppliers as jest.Mock).mockResolvedValue({
+    supplierAllocations: [{ supplier: "s1", variantId: "v1" }],
+    suppliers: [{ id: "s1", name: "Supplier 1", status: "PROD" }],
   });
-  (supplierConfig.getPreferredSupplierPacks as jest.Mock).mockResolvedValue([
-    {
-      packSpecificationId: "pack-spec-1",
-    },
-  ]);
-  (supplierConfig.getPackSpecification as jest.Mock).mockResolvedValue({
+  (allocationConfig.preferredSupplierPack as jest.Mock).mockResolvedValue({
     id: "pack-spec-1",
     type: "A4",
     colour: false,
     duplex: false,
   });
+  (allocationConfig.filterSuppliersWithCapacity as jest.Mock).mockResolvedValue(
+    [{ id: "s1", name: "Supplier 1", status: "PROD" }],
+  );
+  (allocationConfig.selectSupplierByFactor as jest.Mock).mockResolvedValue({
+    id: "s1",
+    name: "Supplier 1",
+    status: "PROD",
+  });
+  (allocationConfig.suppliersWithValidPack as jest.Mock).mockResolvedValue([
+    { id: "s1", name: "Supplier 1", status: "PROD" },
+  ]);
   (
     supplierQuotas.calculateSupplierAllocatedFactor as jest.Mock
   ).mockResolvedValue({

lambdas/supplier-allocator/src/handler/allocate-handler.ts

@@ -5,28 +5,25 @@ import {
   LetterVariant,
   PackSpecification,
   Supplier,
-  SupplierAllocation,
-  SupplierPack,
   VolumeGroup,
 } from "@nhsdigital/nhs-notify-event-schemas-supplier-config";
 import { LetterRequestPreparedEventV2 } from "@nhsdigital/nhs-notify-event-schemas-letter-rendering";
 import z from "zod";
 import { Unit } from "aws-embedded-metrics";
 import { MetricEntry, MetricStatus, buildEMFObject } from "@internal/helpers";
 import {
-  filterPacksForLetter,
-  getPackSpecification,
-  getPreferredSupplierPacks,
-  getSupplierAllocationsForVolumeGroup,
-  getSupplierDetails,
-  getSuppliersWithValidPack,
   getVariantDetails,
   getVolumeGroupDetails,
 } from "../services/supplier-config";
+import { updateSupplierAllocation } from "../services/supplier-quotas";
 import {
-  calculateSupplierAllocatedFactor,
-  updateSupplierAllocation,
-} from "../services/supplier-quotas";
+  eligibleSuppliers,
+  filterSuppliersWithCapacity,
+  preferredSupplierPack,
+  selectSupplierByFactor,
+  suppliersWithValidPack,
+} from "./allocation-config";
+
 import { Deps } from "../config/deps";
 
 type SupplierSpec = {
@@ -85,87 +82,68 @@ async function getSupplierFromConfig(
   deps: Deps,
 ): Promise<SupplierDetails | undefined> {
   try {
-    const variantDetails: LetterVariant = await getVariantDetails(
+    const letterVariant: LetterVariant = await getVariantDetails(
       letterEvent.data.letterVariantId,
       deps,
     );
 
-    const volumeGroupDetails: VolumeGroup = await getVolumeGroupDetails(
-      variantDetails.volumeGroupId,
+    const volumeGroup: VolumeGroup = await getVolumeGroupDetails(
+      letterVariant.volumeGroupId,
       deps,
     );
 
-    const supplierAllocations: SupplierAllocation[] =
-      await getSupplierAllocationsForVolumeGroup(
-        variantDetails.volumeGroupId,
-        deps,
-        variantDetails.supplierId,
-      );
+    const { supplierAllocations, suppliers: allocatedSuppliers } =
+      await eligibleSuppliers(volumeGroup, deps);
 
-    const supplierIds = supplierAllocations.map((alloc) => alloc.supplier);
-
-    const allocatedSuppliers: Supplier[] = await getSupplierDetails(
-      supplierIds,
-      deps,
-    );
-
-    const eligiblePacks: string[] = await filterPacksForLetter(
+    const preferredPack: PackSpecification = await preferredSupplierPack(
       letterEvent,
-      variantDetails.packSpecificationIds,
-      deps,
-    );
-
-    const preferredSupplierPacks: SupplierPack[] =
-      await getPreferredSupplierPacks(eligiblePacks, allocatedSuppliers, deps);
-
-    const preferredPack: PackSpecification = await getPackSpecification(
-      preferredSupplierPacks[0].packSpecificationId,
+      allocatedSuppliers,
+      letterVariant.packSpecificationIds,
       deps,
     );
 
-    const suppliersForPack: Supplier[] = await getSuppliersWithValidPack(
+    const allSuppliersForPack: Supplier[] = await suppliersWithValidPack(
       allocatedSuppliers,
       preferredPack.id,
       deps,
     );
 
-    let supplierAllocationsForPack: SupplierAllocation[] = [];
-    let supplierFactors: { supplierId: string; factor: number }[] = [];
-    let selectedSupplierId = "unknown"; // Default to first supplier if no allocations or factors can be calculated
-    if (suppliersForPack && suppliersForPack.length > 0) {
-      supplierAllocationsForPack = supplierAllocations.filter((alloc) =>
-        suppliersForPack.some((supplier) => supplier.id === alloc.supplier),
+    const suppliersForPackWithCapacity: Supplier[] =
+      await filterSuppliersWithCapacity(
+        allSuppliersForPack,
+        volumeGroup.id,
+        deps,
       );
 
-      supplierFactors = await calculateSupplierAllocatedFactor(
-        supplierAllocationsForPack,
+    // selected supplier id is determined by first calling selectSupplierByFactor for suppliers with capacity and if nothing is returned tryong again with all suppliers for pack
+    const selectedSupplierId =
+      (await selectSupplierByFactor(
+        suppliersForPackWithCapacity,
+        supplierAllocations,
         deps,
-      );
+      )) ??
+      (await selectSupplierByFactor(
+        allSuppliersForPack,
+        supplierAllocations,
+        deps,
+      ));
 
-      // Get the supplierid with the lowest factor
-      selectedSupplierId = supplierFactors[0].supplierId;
-      let lowestFactor = supplierFactors[0].factor;
-      for (const supplierFactor of supplierFactors) {
-        if (supplierFactor.factor < lowestFactor) {
-          lowestFactor = supplierFactor.factor;
-          selectedSupplierId = supplierFactor.supplierId;
-        }
-      }
+    if (!selectedSupplierId) {
+      throw new Error(
+        "No suppliers found with capacity or valid allocation factor for preferred pack",
+      );
     }
 
     deps.logger.info({
       description: "Fetched supplier details for supplier allocations",
       variantId: letterEvent.data.letterVariantId,
-      volumeGroupId: volumeGroupDetails.id,
+      volumeGroupId: volumeGroup.id,
       supplierAllocationIds: supplierAllocations.map((a) => a.id),
       allocatedSuppliers,
-      variantPacks: variantDetails.packSpecificationIds,
-      eligiblePacks,
-      preferredSupplierPacks,
-      preferredPack,
-      suppliersForPack,
-      supplierAllocationsForPack,
-      supplierFactors,
+      allSuppliersForPack: allSuppliersForPack.map((s) => s.id),
+      suppliersForPackWithCapacity: suppliersForPackWithCapacity.map(
+        (s) => s.id,
+      ),
       selectedSupplierId,
     });
 
@@ -176,7 +154,7 @@ async function getSupplierFromConfig(
         priority: 0,
         billingId: preferredPack.billingId,
       },
-      volumeGroupId: volumeGroupDetails.id,
+      volumeGroupId: volumeGroup.id,
     };
     deps.logger.info({
       description: "Resolved supplier details for letter event",

lambdas/supplier-allocator/src/handler/allocation-config.ts

@@ -0,0 +1,125 @@
+import { LetterRequestPreparedEvent } from "@nhsdigital/nhs-notify-event-schemas-letter-rendering-v1";
+import { LetterRequestPreparedEventV2 } from "@nhsdigital/nhs-notify-event-schemas-letter-rendering";
+import {
+  PackSpecification,
+  Supplier,
+  SupplierAllocation,
+  SupplierPack,
+  VolumeGroup,
+} from "@nhsdigital/nhs-notify-event-schemas-supplier-config";
+import {
+  filterPacksForLetter,
+  getPackSpecification,
+  getPreferredSupplierPacks,
+  getSupplierAllocationsForVolumeGroup,
+  getSupplierDetails,
+  getSupplierPacks,
+} from "../services/supplier-config";
+import { calculateSupplierAllocatedFactor } from "../services/supplier-quotas";
+import { Deps } from "../config/deps";
+
+type PreparedEvents = LetterRequestPreparedEventV2 | LetterRequestPreparedEvent;
+
+export async function eligibleSuppliers(
+  volumeGroup: VolumeGroup,
+  deps: Deps,
+): Promise<{
+  supplierAllocations: SupplierAllocation[];
+  suppliers: Supplier[];
+}> {
+  const supplierAllocations = await getSupplierAllocationsForVolumeGroup(
+    volumeGroup.id,
+    deps,
+  );
+  const supplierIds = supplierAllocations.map((alloc) => alloc.supplier);
+
+  const suppliers = await getSupplierDetails(supplierIds, deps);
+  return { supplierAllocations, suppliers };
+}
+
+export async function preferredSupplierPack(
+  letterEvent: PreparedEvents,
+  suppliers: Supplier[],
+  packSpecificationIds: string[],
+  deps: Deps,
+): Promise<PackSpecification> {
+  const eligiblePacks: string[] = await filterPacksForLetter(
+    letterEvent,
+    packSpecificationIds,
+    deps,
+  );
+  const preferredSupplierPacks: SupplierPack[] =
+    await getPreferredSupplierPacks(eligiblePacks, suppliers, deps);
+  const preferredPack: PackSpecification = await getPackSpecification(
+    preferredSupplierPacks[0].packSpecificationId,
+    deps,
+  );
+  return preferredPack;
+}
+
+// This function is used to filter the allocated suppliers based on those that support the supplied pack specification
+export async function suppliersWithValidPack(
+  suppliers: Supplier[],
+  packSpecificationId: string,
+  deps: Deps,
+): Promise<Supplier[]> {
+  const validSuppliers: Supplier[] = [];
+  const supplierPacks = await getSupplierPacks(packSpecificationId, deps);
+
+  for (const supplier of suppliers) {
+    const hasValidPack = supplierPacks.some(
+      (pack) => pack.supplierId === supplier.id,
+    );
+    if (hasValidPack) {
+      validSuppliers.push(supplier);
+    }
+  }
+
+  return validSuppliers;
+}
+
+export async function filterSuppliersWithCapacity(
+  suppliers: Supplier[],
+  volumeGroupId: string,
+  deps: Deps,
+): Promise<Supplier[]> {
+  const dailyAllocationDate = new Date().toISOString().split("T")[0]; // Get current date in YYYY-MM-DD format
+  const dailyAllocation = await deps.supplierQuotasRepo.getDailyAllocation(
+    volumeGroupId,
+    dailyAllocationDate,
+  );
+  if (dailyAllocation) {
+    const suppliersWithCapacity = suppliers.filter((supplier) => {
+      const allocated = dailyAllocation.allocations[supplier.id] ?? 0;
+      return allocated < supplier.dailyCapacity;
+    });
+    return suppliersWithCapacity;
+  }
+  return suppliers; // If no daily allocation exists, assume all suppliers have capacity
+}
+
+export async function selectSupplierByFactor(
+  suppliers: Supplier[],
+  supplierAllocations: SupplierAllocation[],
+  deps: Deps,
+): Promise<string> {
+  const supplierAllocationsForPack = supplierAllocations.filter((alloc) =>
+    suppliers.some((supplier) => supplier.id === alloc.supplier),
+  );
+  const supplierFactors: { supplierId: string; factor: number }[] =
+    await calculateSupplierAllocatedFactor(supplierAllocationsForPack, deps);
+
+  deps.logger.info({
+    description: "Calculated supplier factors for allocation",
+    supplierFactors,
+  });
+  let selectedSupplierId = supplierFactors[0].supplierId;
+  let lowestFactor = supplierFactors[0].factor;
+  for (const supplierFactor of supplierFactors) {
+    if (supplierFactor.factor < lowestFactor) {
+      lowestFactor = supplierFactor.factor;
+      selectedSupplierId = supplierFactor.supplierId;
+    }
+  }
+  return selectedSupplierId;
+}