Refactor: Excel to config model parser tooling

Author: m-houston

.gitignore

@@ -26,3 +26,5 @@ dist
 
 .env
 /.envrc
+/specifications.xlsx
+~*

package-lock.json

@@ -0,0 +1,51 @@
+# Excel Parser
+
+A package for parsing and generating Excel files for NHS Notify supplier configuration data.
+
+## Features
+
+- Parse Excel files containing supplier configuration data (PackSpecification, LetterVariant, VolumeGroup, Supplier, SupplierAllocation, SupplierPack)
+- Generate template Excel files with the correct sheet structure and headers
+- Validate parsed data against Zod schemas
+
+## Usage
+
+### Parsing an Excel file
+
+```typescript
+import { parseExcelFile } from "@nhs-notify/excel-parser";
+
+const result = parseExcelFile("./specifications.xlsx");
+
+console.log(result.packs);           // Record<string, PackSpecification>
+console.log(result.variants);        // Record<string, LetterVariant>
+console.log(result.volumeGroups);    // Record<string, VolumeGroup>
+console.log(result.suppliers);       // Record<string, Supplier>
+console.log(result.allocations);     // Record<string, SupplierAllocation>
+console.log(result.supplierPacks);   // Record<string, SupplierPack>
+```
+
+### Generating a template Excel file
+
+```typescript
+import { generateTemplateExcel } from "@nhs-notify/excel-parser";
+
+// Generate a new template (fails if file exists)
+generateTemplateExcel("./specifications.template.xlsx");
+
+// Force overwrite existing file
+generateTemplateExcel("./specifications.template.xlsx", true);
+```
+
+## Required Excel Sheets
+
+The Excel file must contain the following sheets:
+
+1. **PackSpecification** - Pack specification definitions
+2. **LetterVariant** - Letter variant configurations
+3. **VolumeGroup** - Volume group definitions
+4. **Supplier** - Supplier information
+5. **SupplierAllocation** - Supplier allocation percentages per volume group
+6. **SupplierPack** - Mapping of suppliers to pack specifications
+
+See `EXCEL_HEADERS.md` for detailed column specifications.

packages/excel-parser/README.md

@@ -0,0 +1,26 @@
+import type { Config } from "jest";
+
+const config: Config = {
+  moduleNameMapper: {
+    "^@supplier-config/excel-parser/(.*)$": "<rootDir>/src/$1",
+  },
+  preset: "ts-jest",
+  testEnvironment: "node",
+  testPathIgnorePatterns: ["/node_modules/", "/dist/"],
+  transform: {
+    "^.+\\.tsx?$": [
+      "@swc/jest",
+      {
+        jsc: {
+          parser: {
+            syntax: "typescript",
+            tsx: false,
+          },
+          target: "es2022",
+        },
+      },
+    ],
+  },
+};
+
+export default config;

packages/excel-parser/examples/example_specifications.xlsx

@@ -0,0 +1,28 @@
+{
+  "dependencies": {
+    "@nhsdigital/nhs-notify-event-schemas-supplier-config": "*",
+    "xlsx": "^0.18.5",
+    "zod": "^4.1.12"
+  },
+  "devDependencies": {
+    "@swc/core": "^1.11.13",
+    "@swc/jest": "^0.2.37",
+    "@tsconfig/node22": "^22.0.2",
+    "@types/jest": "^29.5.14",
+    "@types/xlsx": "^0.0.35",
+    "jest": "^29.7.0",
+    "jest-mock-extended": "^3.0.7",
+    "typescript": "^5.9.3"
+  },
+  "name": "@supplier-config/excel-parser",
+  "private": true,
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "jest",
+    "test:unit": "jest",
+    "typecheck": "tsc --noEmit"
+  },
+  "version": "0.0.1"
+}