CCM-12352: Internal package refactor

.markdownlint.jsonc

@@ -0,0 +1,11 @@
+// SEE: https://github.com/DavidAnson/markdownlint/blob/main/schema/.markdownlint.yaml
+{
+  // https://github.com/DavidAnson/markdownlint/blob/main/doc/md013.md
+  "MD013": false,
+  // https://github.com/DavidAnson/markdownlint/blob/main/doc/md024.md
+  "MD024": {
+    "siblings_only": true
+  },
+  // https://github.com/DavidAnson/markdownlint/blob/main/doc/md033.md
+  "MD033": false
+}

.syncpackrc

@@ -0,0 +1,10 @@
+{
+  "versionGroups": [
+    {
+      "dependencies": ["@internal/**", "@nhsdigital/nhs-notify-event-schemas-supplier-api"],
+      "specifierTypes": ["*"],
+      "label": "Internal deps",
+      "isIgnored": true
+    }
+  ]
+}

internal/datastore/jest.config.ts

@@ -15,6 +15,11 @@ export const baseJestConfig: Config = {
   // Indicates which provider should be used to instrument code for coverage
   coverageProvider: 'babel',
 
+  // Module name mapper to handle TypeScript path aliases
+  moduleNameMapper: {
+    '^@internal/helpers$': '<rootDir>/../helpers/src'
+  },
+
   coverageThreshold: {
     global: {
       branches: 100,

internal/datastore/package.json

@@ -2,8 +2,9 @@
   "dependencies": {
     "@aws-sdk/client-dynamodb": "^3.858.0",
     "@aws-sdk/lib-dynamodb": "^3.858.0",
+    "@internal/helpers": "*",
     "pino": "^9.7.0",
-    "zod": "^4.0.14"
+    "zod": "^4.1.11"
   },
   "devDependencies": {
     "@stylistic/eslint-plugin": "^3.1.0",
@@ -18,15 +19,15 @@
     "testcontainers": "^11.4.0",
     "ts-jest": "^29.4.0",
     "ts-node": "^10.9.2",
-    "typescript": "^5.8.2",
+    "typescript": "^5.8.3",
     "zod-mermaid": "^1.0.9"
   },
   "license": "MIT",
   "main": "src/index.ts",
-  "name": "datastore",
+  "name": "@internal/datastore",
   "private": true,
   "scripts": {
-    "diagrams": "ts-node src/cli/diagrams.ts",
+    "diagrams": "tsx src/cli/diagrams.ts",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "test:unit": "jest",

internal/datastore/src/cli/diagrams.ts

@@ -1,4 +1,4 @@
-import { LetterSchema, MISchema } from '../types';
+import {LetterSchema, MISchema, SupplierSchema} from '../types';
 import { generateMermaidDiagram } from 'zod-mermaid';
 import * as fs from 'node:fs';
 
@@ -11,7 +11,7 @@ This document contains the mermaid diagrams for the data store schemas used in t
 The schemas are generated from Zod definitions and provide a visual representation of the data structure.
 `);
 
-for (const [name, schema] of Object.entries({ Letter: [LetterSchema], MI: [MISchema] })) {
+for (const [name, schema] of Object.entries({ Letter: [LetterSchema], MI: [MISchema], Supplier: [SupplierSchema] })) {
   const mermaid = generateMermaidDiagram(schema);
   fs.writeSync(out, `
 ## ${name} schema

internal/datastore/src/types.md

@@ -31,7 +31,7 @@ erDiagram
 erDiagram
     MI {
         string id
-        string supplierId "ref: Supplier"
+        string supplierId
         string specificationId
         string groupId
         string lineItem
@@ -40,7 +40,16 @@ erDiagram
         string createdAt
         string updatedAt
     }
+```
+
+## Supplier schema
+
+```mermaid
+erDiagram
     Supplier {
+        string id
+        string name
+        string apimId
+        string status "enum: ENABLED, DISABLED"
     }
-    MI }o--|| Supplier : "supplierId"
 ```

internal/datastore/src/types.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { idRef } from 'zod-mermaid';
+import { idRef } from '@internal/helpers';
 
 export const SupplerStatus = z.enum(['ENABLED', 'DISABLED']);
 
@@ -29,7 +29,7 @@ export const LetterSchemaBase = z.object({
 });
 
 export const LetterSchema = LetterSchemaBase.extend({
-  supplierId: z.string(),
+  supplierId: idRef(SupplierSchema, 'id'),
   url: z.url(),
   createdAt: z.string(),
   updatedAt: z.string(),
@@ -57,7 +57,7 @@ export const MISchemaBase = z.object({
 });
 
 export const MISchema = MISchemaBase.extend({
-  supplierId: idRef(SupplierSchema),
+  supplierId: idRef(SupplierSchema, 'id'),
   createdAt: z.string(),
   updatedAt: z.string(),
   ttl: z.int(),

internal/datastore/tsconfig.json

@@ -1,8 +1,6 @@
 {
-  "compilerOptions": {
-    "isolatedModules": true
-  },
-  "extends": "@tsconfig/node22/tsconfig.json",
+  "compilerOptions": {},
+  "extends": "../../tsconfig.base.json",
   "include": [
     "src/**/*",
     "jest.config.ts"

internal/helpers/.gitignore

@@ -0,0 +1,24 @@
+# Dependency directories
+node_modules/
+
+# Built output
+dist/
+
+# Coverage directory used by tools like istanbul
+coverage/
+
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Editor directories and files
+.idea/
+.vscode/
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

internal/helpers/jest.config.ts

@@ -0,0 +1,15 @@
+import type { Config } from "jest";
+
+const config: Config = {
+  preset: "ts-jest",
+  testEnvironment: "node",
+  testMatch: ["**/src/__tests__/**/*.ts?(x)", "**/src/?(*.)+(spec|test).ts?(x)"],
+  collectCoverageFrom: ["src/**/*.ts"],
+  coveragePathIgnorePatterns: ["/node_modules/", "__tests__"],
+  testPathIgnorePatterns: ["/node_modules/", "/dist/"],
+  transform: {
+    "^.+\\.tsx?$": ["ts-jest", {  }]
+  }
+};
+
+export default config;

internal/helpers/package.json

@@ -0,0 +1,32 @@
+{
+  "dependencies": {
+    "zod": "^4.1.11"
+  },
+  "description": "Common helper utilities for NHS Notify Supplier API",
+  "devDependencies": {
+    "@stylistic/eslint-plugin": "^3.1.0",
+    "@tsconfig/node22": "^22.0.2",
+    "@types/jest": "^29.5.14",
+    "@typescript-eslint/eslint-plugin": "^8.27.0",
+    "@typescript-eslint/parser": "^8.27.0",
+    "eslint": "^9.27.0",
+    "eslint-plugin-jest": "^29.0.1",
+    "jest": "^30.1.3",
+    "ts-jest": "^29.4.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.8.3"
+  },
+  "license": "MIT",
+  "main": "src/index.ts",
+  "name": "@internal/helpers",
+  "private": true,
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "jest",
+    "test:unit": "jest",
+    "typecheck": "tsc --noEmit"
+  },
+  "version": "0.1.0"
+}

internal/helpers/src/__tests__/id-ref.test.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import { idRef } from "../id-ref";
+
+describe("idRef", () => {
+  const TestSchema = z.object({
+    domainId: z.uuid(),
+    name: z.string(),
+  });
+
+  it("should create an ID reference with the same type as the source schema's ID field", () => {
+    const refField = idRef(TestSchema);
+
+    // Should validate UUIDs like the original schema's domainId
+    expect(() => refField.parse("not-a-uuid")).toThrow();
+    expect(() => refField.parse("123e4567-e89b-12d3-a456-426614174000")).not.toThrow();
+  });
+
+  it("should add reference metadata", () => {
+    const refField = idRef(TestSchema, "domainId", "TestEntity");
+
+    expect(refField).toBeDefined();
+    expect(z.globalRegistry.has(refField)).toBe(true);
+    expect(z.globalRegistry.get(refField)).toEqual(expect.objectContaining({
+      title: "TestEntity ID Reference",
+      description: "Reference to a TestEntity by its unique identifier",
+    }));
+  });
+
+  it("should use custom ID field name when provided", () => {
+    const CustomSchema = z.object({
+      customId: z.number(),
+      name: z.string(),
+    });
+
+    const refField = idRef(CustomSchema, "customId");
+
+    // Should validate numbers like the custom ID field
+    expect(() => refField.parse("not-a-number")).toThrow();
+    expect(() => refField.parse(123)).not.toThrow();
+  });
+});

internal/helpers/src/domain-base.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+
+export function DomainBase<T extends string>(
+  type: T,
+): z.ZodObject<{ domainId: z.core.$ZodBranded<z.ZodString, T> }> {
+  const idType = z
+    .string()
+    .brand<T>(type)
+    .meta({
+      title: `${type} ID`,
+      description: `Unique identifier for the ${type}`,
+      examples: ["1y3q9v1zzzz"],
+    }) as z.core.$ZodBranded<z.ZodString, T>;
+
+  return z.object({
+    domainId: idType,
+  });
+}

internal/helpers/src/environment.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+
+/**
+ * Deployment / execution environment identifier.
+ * Intentionally liberal; constrain in callers as needed.
+ */
+export const $Environment = z.string().meta({
+  title: 'Environment',
+  description: 'The environment in which the configuration has effect',
+  examples: ['dev', 'int', 'prod'],
+});

internal/helpers/src/id-ref.ts

@@ -0,0 +1,65 @@
+import { z } from "zod";
+
+/**
+ * Creates a field that references another entity by ID, inferring the type from the referenced
+ * schema's domainId field.
+ * This allows you to indicate relationships without embedding the full entity.
+ *
+ * @param schema - The Zod object schema representing the referenced entity
+ * @param idFieldName - The name of the ID field in the referenced schema (default: 'domainId')
+ * @param entityName - Optional custom name for the referenced entity
+ * @returns A Zod schema for the ID field with reference metadata, with the type inferred from
+ * the referenced schema
+ *
+ * @example
+ * import { z } from 'zod';
+ * import { idRef } from './id-ref';
+ *
+ * const CustomerSchema = z.object({ domainId: z.string() });
+ * const OrderSchema = z.object({
+ *   domainId: z.string(),
+ *   customerId: idRef(CustomerSchema), // Inferred as ZodString
+ * });
+ */
+// Overload for when a specific ID field is provided
+export function idRef<
+  T extends z.ZodObject<Record<string, z.ZodTypeAny>>,
+  K extends keyof T["shape"] & string
+>(schema: T, idFieldName: K, entityName?: string): T["shape"][K];
+
+// Overload for when using the default "domainId" field
+export function idRef<
+  T extends z.ZodObject<Record<string, z.ZodTypeAny>> & {
+    shape: { domainId: z.ZodTypeAny }
+  }
+>(schema: T, idFieldName?: undefined, entityName?: string): T["shape"]["domainId"];
+
+// Implementation
+export function idRef<
+  T extends z.ZodObject<Record<string, z.ZodTypeAny>>,
+  K extends keyof T["shape"] & string = "domainId",
+>(schema: T, idFieldName?: K, entityName?: string): T["shape"][K] {
+  const { shape } = schema;
+  const field = idFieldName ?? "domainId";
+
+  if (!(field in shape)) {
+    throw new Error(`ID field '${field}' not found in schema`);
+  }
+
+  // Get the ID field schema
+  const idFieldSchema = shape[field];
+  if (!idFieldSchema) {
+    throw new Error(`ID field '${field}' not found in schema`);
+  }
+
+  // Use the provided entity name or the schema description
+  const targetEntityName = entityName || schema.description || "Unknown";
+
+  // Create a new schema with the same type and validation as the ID field
+  const resultSchema = idFieldSchema.clone().meta({
+    title: `${targetEntityName} ID Reference`,
+    description: `Reference to a ${targetEntityName} by its unique identifier`,
+  });
+
+  return resultSchema as T["shape"][K];
+}

internal/helpers/src/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Common helper utilities for NHS Notify Supplier API
+ * @module helpers
+ */
+
+// Export all helpers
+export * from './version';
+export * from './environment';
+export * from "./id-ref";
+export * from "./domain-base";

internal/helpers/src/version.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+
+/**
+ * Semantic version (major.minor.patch) with numeric segments only.
+ * Branded for nominal typing.
+ */
+export const $Version = z
+  .string()
+  .regex(/^[0-9]+\.[0-9]+\.[0-9]+$/)
+  .brand('Version');
+
+export type Version = z.infer<typeof $Version>;

internal/helpers/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "declaration": true
+  },
+  "exclude": [
+    "node_modules",
+    "dist"
+  ],
+  "extends": "../../tsconfig.base.json",
+  "include": [
+    "src/**/*",
+    "jest.config.ts"
+  ]
+}