CCM-17943: Add function Readme documentation (#608)

* first review pass

* add information on how to run tests

* increment version of internal/events/package.json

* include information on setting the api key in main and for TestSupplier1

* correct the proxy_name format

---------

Co-authored-by: Vlasis-Perdikidis <vlasis.perdikidis1@nhs.net>

Author: francisco-videira-nhs

.env.template

@@ -3,7 +3,7 @@ PR_NUMBER=prxx # remove if needs to run against main
 GITHUB_TOKEN=
 
 # Apigee proxy name to be used for test execution
-# nhs-notify-supplier--internal-dev--nhs-notify-supplier-PR-XX
+# nhs-notify-supplier--internal-dev--nhs-notify-supplier-PR-xxx
 PROXY_NAME=
 
 # APIM env to run e2e tests against, other options are: ref, int, prod
@@ -25,18 +25,35 @@ TARGET_ENVIRONMENT=prxx
 
 # API Keys
 # ========
-# In order to find out the value of an environments given API key, follow these steps
-# 1. Log in to Non-Prod
-# 2. Navigate to 'Publish' > 'Apps' and search for the app linked to authentication
-# 3. Copy the "key" from the Credentials related to the app
+# In order to find out and set the value of NON_PROD_API_KEY follow these steps
+# 1. Log in to the AWS NHS Notify Suppliers Dev account
+# 2. Open the paramenter store and search for the parameter /dev/e2e/keys/apim/pr (this key will use the supplier Supplier1)
+#    a. to use the supplier TestSupplier1, search for the parameter /dev/e2e/keys/apim/pr/secondary
+#       NOTE: this needs to be set to the NON_PROD_SECONDARY_API_KEY environment variable
+#    b. If you want to run against main, search for the parameter /dev/e2e/keys/apim/main
+# 3. Copy the decrypted "value"
 # Note: For INT and higher environments use developer portal https://identity.prod.api.platform.nhs.uk/
 export NON_PROD_API_KEY=xxx
+export NON_PROD_SECONDARY_API_KEY=xxx
 export INTEGRATION_API_KEY=xxx
 export PRODUCTION_API_KEY=xxx
+
+# Status Endpoint API Key
+# In order to find the value of the status endpoint API key, follow these steps:
+# 1. Log in to the AWS NHS Notify Suppliers Dev account
+# 2. Open the paramenter store and search for the parameter /dev/e2e/keys/apim/status
+# 3. Copy the decrypted "value"
 export STATUS_ENDPOINT_API_KEY=xxx
 
 # Private Keys
 # ============
+# In order to set the NON_PROD_PRIVATE_KEY, follow these steps:
+# 1. Log in to the AWS NHS Notify Suppliers Dev account
+# 2. Open the paramenter store and search for the parameter /dev/e2e/keys/private
+# 3. Copy the decrypted "value"
+# 4. Create a .pem file and paste the value copied in step 3,
+#    save the file and provide the path to the file as the value for NON_PROD_PRIVATE_KEY
+#    for example /workspaces/nhs-notify-supplier-api/scripts/JWT/internal-dev-test-1.pem
 # private key path used to generate authentication for tests ran against the internal-dev and internal-qa
 export NON_PROD_PRIVATE_KEY=xxx
 # private key path used to generate authentication for tests ran against the int environment

CONTRIBUTING.md

@@ -1,4 +1,6 @@
-## Contributing to NHS Notify Supplier API
+<!-- vale off -->
+
+# Contributing to NHS Notify Supplier API
 
 ## Feature Branches
 
@@ -45,3 +47,11 @@ GitHooks **must** be configured and run on commits before pushing to remote. Ref
 ## Testing Your Branch
 
 You can test your branch in a dynamic environment prior to merging to `main`. These are created as part of the `cicd-1-pull-request.yaml` workflow, triggered when a PR is created or updated.
+
+## Function Documentation
+
+Each Lambda and internal package has a `README.md` alongside the source describing its purpose, flow, integration points, and peculiarities. These are bundled into the docs site via `docs/generate-includes.sh`.
+
+When making changes to a Lambda or internal package, check whether the corresponding README needs updating. Function documentation is not auto-generated and can become stale if not maintained alongside code changes.
+
+<!-- vale on -->

README.md

@@ -24,7 +24,6 @@ This repository documents the Supplier API specification and provides an SDK wit
     - [Packages](#packages)
     - [Documentation](#documentation)
     - [SDK Assets](#sdk-assets)
-    - [Examples](#examples)
   - [API Developers](#api-developers)
     - [Setup](#setup)
       - [Prerequisites and Configuration](#prerequisites-and-configuration)
@@ -64,10 +63,6 @@ If packages are unavailable the latest SDKs can be downloaded directly from:
   - TypeScript `sdk-ts-[Version].zip`
   - CSharp `sdk-csharp-[Version].zip`
 
-### Examples
-
-TODO:CCM-11209 Links to example clients.
-
 ## API Developers
 
 New developers of the NHS Notify Supplier API should understand the below.
@@ -153,6 +148,14 @@ by default they will be available at [http://localhost:3050](http://localhost:30
 
 These are generated using [https://hub.docker.com/r/openapitools/openapi-generator-cli](https://hub.docker.com/r/openapitools/openapi-generator-cli)
 
+### Unit Testing
+
+Run unit tests from the repository root:
+
+```bash
+npm run test:unit
+```
+
 ### Documentation
 
 - You can preview the OAS locally by running `make serve-oas`

config/suppliers/README.md

@@ -0,0 +1,39 @@
+<!-- vale off -->
+
+# Supplier Configuration
+
+## Purpose
+
+Static JSON configuration files that define the supplier allocation rules for the Supplier API. These are loaded into DynamoDB by infrastructure tooling and are queried at runtime by the `supplier-allocator` Lambda. Check relevant repositories (nhs-notify-internal, nhs-notify-supplier-config) as they orchestrate supplier config data ingress depending on target account, environment, etc.
+
+## Configuration Entities
+
+| Entity                  | Directory              | Description                                                                                                                                                    |
+| ----------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Supplier**            | `supplier/`            | Print supplier definitions with ID, name, channel type, daily capacity, and status (PROD/DRAFT)                                                                |
+| **Letter Variant**      | `letter-variant/`      | Letter type definitions with physical constraints (sheets, sides, ink coverage, delivery days), associated pack specification IDs, and volume group assignment |
+| **Volume Group**        | `volume-group/`        | Groupings of letter variants for allocation purposes, with status and date range validity                                                                      |
+| **Supplier Allocation** | `supplier-allocation/` | Maps a supplier to a volume group with a target `allocationPercentage` and status                                                                              |
+| **Pack Specification**  | `pack-specification/`  | Detailed print assembly specs (paper, envelope, print colour, duplex) with constraints and billing ID                                                          |
+| **Supplier Pack**       | `supplier-pack/`       | Links a supplier to a pack specification with approval status                                                                                                  |
+
+## Allocation Lookup Chain
+
+When the `supplier-allocator` Lambda processes a `LetterRequestPreparedEvent`:
+
+1. The event's `letterVariantId` identifies the **Letter Variant**.
+2. The variant's `volumeGroupId` identifies the **Volume Group** (must be `PROD` status and within date range).
+3. **Supplier Allocations** for that volume group determine which suppliers are eligible and their target allocation percentages (must sum to 100).
+4. The variant's `packSpecificationIds` are filtered by the letter's physical constraints.
+5. **Supplier Packs** confirm which eligible suppliers support the selected pack specification.
+6. The supplier with the lowest weighted allocation factor (furthest below their target share) is selected.
+
+## Nuances and Peculiarities
+
+- These files are the source of truth for the supplier config DynamoDB table (`SUPPLIER_CONFIG_TABLE_NAME`). Changes here flow into DynamoDB via infrastructure deployment.
+- Runtime persistence is event-driven: supplier-config events are routed through SQS to the `supplier-config-ingress` Lambda, which upserts records into the config table.
+- `status: "PROD"` is required at multiple levels (supplier, volume group, allocation) for an allocation to be active.
+- Volume groups have `startDate` (and optional `endDate`) fields. Allocations are only valid when the current date falls within this range (evaluated in London timezone).
+- Supplier `dailyCapacity` is tracked separately in `SUPPLIER_QUOTAS_TABLE` and resets at midnight London time. It is not stored in these config files.
+
+<!-- vale on -->