calculate allocation factors

Author: nhsd-david-wass

internal/datastore/src/index.ts

@@ -3,6 +3,7 @@ export * from "./mi-repository";
 export * from "./letter-repository";
 export * from "./supplier-repository";
 export * from "./supplier-config-repository";
+export * from "./supplier-quotas-repository";
 export { default as LetterQueueRepository } from "./letter-queue-repository";
 export { default as DBHealthcheck } from "./healthcheck";
 export { default as LetterAlreadyExistsError } from "./errors/letter-already-exists-error";

internal/datastore/src/supplier-quotas-repository.ts

@@ -0,0 +1,155 @@
+import {
+  DynamoDBDocumentClient,
+  GetCommand,
+  PutCommand,
+  UpdateCommand,
+} from "@aws-sdk/lib-dynamodb";
+import {
+  $DailyAllocation,
+  $OverallAllocation,
+  DailyAllocation,
+  OverallAllocation,
+} from "./types";
+
+export type SupplierQuotasRepositoryConfig = {
+  supplierQuotasTableName: string;
+};
+
+function ItemForRecord(
+  entity: string,
+  id: string,
+  record: Record<string, any>,
+): Record<string, any> {
+  return {
+    pk: `ENTITY#${entity}`,
+    sk: `ID#${id}`,
+    ...record,
+  };
+}
+
+export class SupplierQuotasRepository {
+  constructor(
+    readonly ddbClient: DynamoDBDocumentClient,
+    readonly config: SupplierQuotasRepositoryConfig,
+  ) {}
+
+  async getOverallAllocation(groupId: string): Promise<OverallAllocation> {
+    const result = await this.ddbClient.send(
+      new GetCommand({
+        TableName: this.config.supplierQuotasTableName,
+        Key: { pk: "ENTITY#overall_allocation", sk: `ID#${groupId}` },
+      }),
+    );
+    if (!result.Item) {
+      throw new Error(
+        `No overall allocation found for volume group id ${groupId}`,
+      );
+    }
+    return $OverallAllocation.parse(result.Item);
+  }
+
+  async putOverallAllocation(allocation: OverallAllocation): Promise<void> {
+    await this.ddbClient.send(
+      new PutCommand({
+        TableName: this.config.supplierQuotasTableName,
+        Item: ItemForRecord(
+          "overall_allocation",
+          allocation.id,
+          $OverallAllocation.parse(allocation),
+        ),
+      }),
+    );
+  }
+
+  // Update the overallAllocation table updating the allocations array for a given volume group
+  // or adding the value if the supplier is not present //
+  async updateOverallAllocation(
+    groupId: string,
+    supplierId: string,
+    newAllocation: number,
+  ): Promise<void> {
+    const overallAllocation = await this.getOverallAllocation(groupId);
+    const currentAllocation = overallAllocation.allocations[supplierId] ?? 0;
+    const updatedAllocation = currentAllocation + newAllocation;
+
+    await this.ddbClient.send(
+      new UpdateCommand({
+        TableName: this.config.supplierQuotasTableName,
+        Key: { pk: "ENTITY#overall_allocation", sk: `ID#${groupId}` },
+        UpdateExpression:
+          "SET allocations.#supplierId = :updatedAllocation, updatedAt = :updatedAt",
+        ExpressionAttributeNames: {
+          "#supplierId": supplierId,
+        },
+        ExpressionAttributeValues: {
+          ":updatedAllocation": updatedAllocation,
+          ":updatedAt": new Date().toISOString(),
+        },
+      }),
+    );
+  }
+
+  async getDailyAllocation(
+    groupId: string,
+    date: string,
+  ): Promise<DailyAllocation> {
+    const result = await this.ddbClient.send(
+      new GetCommand({
+        TableName: this.config.supplierQuotasTableName,
+        Key: {
+          pk: "ENTITY#daily_allocation",
+          sk: `ID#${groupId}#DATE#${date}`,
+        },
+      }),
+    );
+    if (!result.Item) {
+      throw new Error(
+        `No daily allocation found for volume group id ${groupId} and date ${date}`,
+      );
+    }
+    return $DailyAllocation.parse(result.Item);
+  }
+
+  async putDailyAllocation(allocation: DailyAllocation): Promise<void> {
+    await this.ddbClient.send(
+      new PutCommand({
+        TableName: this.config.supplierQuotasTableName,
+        Item: ItemForRecord(
+          "daily_allocation",
+          `${allocation.volumeGroup}#DATE#${allocation.date}`,
+          $DailyAllocation.parse(allocation),
+        ),
+      }),
+    );
+  }
+
+  async updateDailyAllocation(
+    groupId: string,
+    date: string,
+    supplierId: string,
+    newAllocation: number,
+  ): Promise<void> {
+    const dailyAllocation = await this.getDailyAllocation(groupId, date);
+    const currentAllocation = dailyAllocation.allocations[supplierId] ?? 0;
+    const updatedAllocation = currentAllocation + newAllocation;
+
+    await this.ddbClient.send(
+      new UpdateCommand({
+        TableName: this.config.supplierQuotasTableName,
+        Key: {
+          pk: "ENTITY#daily_allocation",
+          sk: `ID#${groupId}#DATE#${date}`,
+        },
+        UpdateExpression:
+          "SET allocations.#supplierId = :updatedAllocation, updatedAt = :updatedAt",
+        ExpressionAttributeNames: {
+          "#supplierId": supplierId,
+        },
+        ExpressionAttributeValues: {
+          ":updatedAllocation": updatedAllocation,
+          ":updatedAt": new Date().toISOString(),
+        },
+      }),
+    );
+  }
+}

internal/datastore/src/types.ts

@@ -1,5 +1,9 @@
 import { z } from "zod";
 import { idRef } from "@internal/helpers";
+import {
+  $Supplier,
+  $VolumeGroup,
+} from "@nhsdigital/nhs-notify-event-schemas-supplier-config";
 
 export const SupplierStatus = z.enum(["ENABLED", "DISABLED"]);
 
@@ -120,3 +124,38 @@ export const MISchema = MISchemaBase.extend({
 
 export type MI = z.infer<typeof MISchema>;
 export type MIBase = z.infer<typeof MISchemaBase>;
+
+export const $OverallAllocation = z
+  .object({
+    id: z.string(),
+    volumeGroup: idRef($VolumeGroup, "id"),
+    allocations: z.record(
+      idRef($Supplier, "id"),
+      z.number().int().nonnegative(),
+    ),
+  })
+  .meta({
+    title: "OverallAllocation",
+    description:
+      "The overall allocation for a volume group, including all suppliers",
+  });
+
+export type OverallAllocation = z.infer<typeof $OverallAllocation>;
+
+export const $DailyAllocation = z
+  .object({
+    id: z.string(),
+    date: z.ZodISODate,
+    volumeGroup: idRef($VolumeGroup, "id"),
+    allocations: z.record(
+      idRef($Supplier, "id"),
+      z.number().int().nonnegative(),
+    ),
+  })
+  .meta({
+    title: "DailyAllocation",
+    description:
+      "The daily allocation for a volume group, including all suppliers",
+  });
+
+export type DailyAllocation = z.infer<typeof $DailyAllocation>;

lambdas/supplier-allocator/jest.config.ts

@@ -14,7 +14,7 @@ export const baseJestConfig = {
   clearMocks: true,
 
   // Indicates whether the coverage information should be collected while executing the test
-  collectCoverage: true,
+  collectCoverage: false,
 
   // The directory where Jest should output its coverage files
   coverageDirectory: "./.reports/unit/coverage",

lambdas/supplier-allocator/src/config/__tests__/deps.test.ts

@@ -3,6 +3,7 @@ import type { Deps } from "lambdas/supplier-allocator/src/config/deps";
 describe("createDependenciesContainer", () => {
   const env = {
     SUPPLIER_CONFIG_TABLE_NAME: "SupplierConfigTable",
+    SUPPLIER_QUOTAS_TABLE_NAME: "SupplierQuotasTable",
     VARIANT_MAP: {
       lv1: {
         supplierId: "supplier1",

lambdas/supplier-allocator/src/config/__tests__/env.test.ts

@@ -16,6 +16,7 @@ describe("lambdaEnv", () => {
 
   it("should load all environment variables successfully", () => {
     process.env.SUPPLIER_CONFIG_TABLE_NAME = "SupplierConfigTable";
+    process.env.SUPPLIER_QUOTAS_TABLE_NAME = "SupplierQuotasTable";
     process.env.VARIANT_MAP = `{
       "lv1": {
         "supplierId": "supplier1",

lambdas/supplier-allocator/src/config/deps.ts

@@ -4,10 +4,12 @@ import { SQSClient } from "@aws-sdk/client-sqs";
 import { Logger } from "pino";
 import { createLogger } from "@internal/helpers";
 import { SupplierConfigRepository } from "@internal/datastore";
+import { SupplierQuotasRepository } from "@internal/datastore";
 import { EnvVars, envVars } from "./env";
 
 export type Deps = {
   supplierConfigRepo: SupplierConfigRepository;
+  supplierQuotasRepo: SupplierQuotasRepository;
   logger: Logger;
   env: EnvVars;
   sqsClient: SQSClient;
@@ -30,11 +32,24 @@ function createSupplierConfigRepository(
   return new SupplierConfigRepository(createDocumentClient(), config);
 }
 
+function createSupplierQuotasRepository(
+  log: Logger,
+  // eslint-disable-next-line @typescript-eslint/no-shadow
+  envVars: EnvVars,
+): SupplierQuotasRepository {
+  const config = {
+    supplierQuotasTableName: envVars.SUPPLIER_QUOTAS_TABLE_NAME,
+  };
+
+  return new SupplierQuotasRepository(createDocumentClient(), config);
+}
+
 export function createDependenciesContainer(): Deps {
   const log = createLogger({ logLevel: envVars.PINO_LOG_LEVEL });
 
   return {
     supplierConfigRepo: createSupplierConfigRepository(log, envVars),
+    supplierQuotasRepo: createSupplierQuotasRepository(log, envVars),
     logger: log,
     env: envVars,
     sqsClient: new SQSClient({}),

lambdas/supplier-allocator/src/config/env.ts

@@ -13,6 +13,7 @@ export type LetterVariant = z.infer<typeof LetterVariantSchema>;
 
 const EnvVarsSchema = z.object({
   SUPPLIER_CONFIG_TABLE_NAME: z.string(),
+  SUPPLIER_QUOTAS_TABLE_NAME: z.string(),
   PINO_LOG_LEVEL: z.coerce.string().optional(),
   VARIANT_MAP: z.string().transform((str, _) => {
     const parsed = JSON.parse(str);

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

@@ -7,9 +7,13 @@ import {
   $LetterStatusChangeEvent,
   LetterStatusChangeEvent,
 } from "@nhsdigital/nhs-notify-event-schemas-supplier-api/src/events/letter-events";
-import { SupplierConfigRepository } from "@internal/datastore";
+import {
+  SupplierConfigRepository,
+  SupplierQuotasRepository,
+} from "@internal/datastore";
 import createSupplierAllocatorHandler from "../allocate-handler";
 import * as supplierConfig from "../../services/supplier-config";
+import * as supplierQuotas from "../../services/supplier-quotas";
 
 import { Deps } from "../../config/deps";
 import { EnvVars } from "../../config/env";
@@ -21,6 +25,7 @@ const renderingSchemaVersion: string =
   ];
 
 jest.mock("../../services/supplier-config");
+jest.mock("../../services/supplier-quotas");
 
 function createSQSEvent(records: SQSRecord[]): SQSEvent {
   return {
@@ -169,12 +174,19 @@ function setupDefaultMocks() {
     colour: false,
     duplex: false,
   });
+  (
+    supplierQuotas.calculateSupplierAllocatedFactor as jest.Mock
+  ).mockResolvedValue({
+    supplierId: "supplier-1",
+    factor: 0.5,
+  });
 }
 
 describe("createSupplierAllocatorHandler", () => {
   let mockSqsClient: jest.Mocked<SQSClient>;
   let mockedDeps: jest.Mocked<Deps>;
   let mockedSupplierConfigRepo: jest.Mocked<SupplierConfigRepository>;
+  let mockedSupplierQuotasRepo: jest.Mocked<SupplierQuotasRepository>;
   beforeEach(() => {
     mockSqsClient = {
       send: jest.fn(),
@@ -191,10 +203,22 @@ describe("createSupplierAllocatorHandler", () => {
       getPackSpecification: jest.fn(),
     } as jest.Mocked<SupplierConfigRepository>;
 
+    mockedSupplierQuotasRepo = {
+      ddbClient: {} as any,
+      config: {} as any,
+      getOverallAllocation: jest.fn(),
+      putOverallAllocation: jest.fn(),
+      updateOverallAllocation: jest.fn(),
+      getDailyAllocation: jest.fn(),
+      putDailyAllocation: jest.fn(),
+      updateDailyAllocation: jest.fn(),
+    } as jest.Mocked<SupplierQuotasRepository>;
+
     mockedDeps = {
       logger: { error: jest.fn(), info: jest.fn() } as unknown as pino.Logger,
       env: {
         SUPPLIER_CONFIG_TABLE_NAME: "SupplierConfigTable",
+        SUPPLIER_QUOTAS_TABLE_NAME: "SupplierQuotasTable",
         VARIANT_MAP: {
           lv1: {
             supplierId: "supplier1",
@@ -206,6 +230,7 @@ describe("createSupplierAllocatorHandler", () => {
       } as EnvVars,
       sqsClient: mockSqsClient,
       supplierConfigRepo: mockedSupplierConfigRepo,
+      supplierQuotasRepo: mockedSupplierQuotasRepo,
     } as jest.Mocked<Deps>;
     jest.clearAllMocks();
   });
@@ -434,6 +459,39 @@ describe("createSupplierAllocatorHandler", () => {
     );
   });
 
+  test("returns batch failure when variant mapping is missing for multiple events", async () => {
+    const preparedEvent1 = createPreparedV2Event();
+    preparedEvent1.data.letterVariantId = "missing-variant1";
+    const preparedEvent2 = createPreparedV2Event();
+    preparedEvent2.data.letterVariantId = "missing-variant2";
+
+    const evt: SQSEvent = createSQSEvent([
+      createSqsRecord("msg1", JSON.stringify(preparedEvent1)),
+      createSqsRecord("msg2", JSON.stringify(preparedEvent2)),
+    ]);
+
+    process.env.UPSERT_LETTERS_QUEUE_URL = "https://sqs.test.queue";
+
+    // Override variant map to be empty for this test
+    mockedDeps.env.VARIANT_MAP = {} as any;
+
+    const handler = createSupplierAllocatorHandler(mockedDeps);
+    const result = await handler(evt, {} as any, {} as any);
+    if (!result) throw new Error("expected BatchResponse, got void");
+
+    expect(result.batchItemFailures).toHaveLength(2);
+    expect(result.batchItemFailures[0].itemIdentifier).toBe("msg1");
+    expect(result.batchItemFailures[1].itemIdentifier).toBe("msg2");
+    expect(
+      (mockedDeps.logger.error as jest.Mock).mock.calls.length,
+    ).toBeGreaterThan(0);
+    expect((mockedDeps.logger.error as jest.Mock).mock.calls[0][0]).toEqual(
+      expect.objectContaining({
+        description: "No supplier mapping found for variant",
+      }),
+    );
+  });
+
   test("handles SQS send errors and returns batch failure", async () => {
     const preparedEvent = createPreparedV2Event();