Merge branch 'main' into feature/CCM-11207_doc

Author: masl2

.github/actions/build-proxies/action.yml

@@ -4,7 +4,27 @@ description: "Build Proxies"
 inputs:
   version:
     description: "Version number"
+    required: false
+  releaseVersion:
+    description: "Release, tag, branch, or commit ID to be used for deployment"
     required: true
+  environment:
+    description: "Deployment environment"
+    required: true
+  apimEnv:
+    description: "APIM environment"
+    required: true
+  runId:
+    description: "GitHub Actions run ID to fetch the OAS artifact from"
+    required: true
+  buildSandbox:
+    description: "Whether to build the sandbox OAS spec"
+    required: false
+    default: false
+  targetComponent:
+    description: "Name of the Component to deploy"
+    required: true
+    default: 'api'
 
 runs:
   using: composite
@@ -25,46 +45,71 @@ runs:
       shell: bash
       run: |
 
+        ENV="${{ inputs.apimEnv }}"
+        if [[ "$ENV" == "internal-dev" || "$ENV" == *pr ]]; then
+          echo "TARGET_DOMAIN=suppliers.dev.nhsnotify.national.nhs.uk" >> $GITHUB_ENV
+        elif [[ "$ENV" == "int" ]]; then
+          echo "TARGET_DOMAIN=suppliers.nonprod.nhsnotify.national.nhs.uk" >> $GITHUB_ENV
+        elif [[ "$ENV" == "prod" ]]; then
+          echo "TARGET_DOMAIN=suppliers.prod.nhsnotify.national.nhs.uk" >> $GITHUB_ENV
+        else
+          echo "TARGET_DOMAIN=suppliers.dev.nhsnotify.national.nhs.uk" >> $GITHUB_ENV
+        fi
+
         if [ -z $PR_NUMBER ]
         then
           echo "INSTANCE=$PROXYGEN_API_NAME" >> $GITHUB_ENV
-          echo "TARGET=https://main.suppliers.dev.nhsnotify.national.nhs.uk" >> $GITHUB_ENV
+          echo "TARGET=https://main.$TARGET_DOMAIN" >> $GITHUB_ENV
           echo "SANDBOX_TAG=latest" >> $GITHUB_ENV
           echo "MTLS_NAME=notify-supplier-mtls" >> $GITHUB_ENV
         else
-          echo "TARGET=https://pr$PR_NUMBER.suppliers.dev.nhsnotify.national.nhs.uk" >> $GITHUB_ENV
+          echo "TARGET=https://pr$PR_NUMBER.$TARGET_DOMAIN" >> $GITHUB_ENV
           echo "INSTANCE=$PROXYGEN_API_NAME-PR-$PR_NUMBER" >> $GITHUB_ENV
           echo "SANDBOX_TAG=pr$PR_NUMBER" >> $GITHUB_ENV
           echo "MTLS_NAME=notify-supplier-mtls-pr$PR_NUMBER" >> $GITHUB_ENV
         fi
 
-    - name: Install Proxygen client
-      shell: bash
-      run: |
-        # Install proxygen cli
-        pip install pipx
-        pipx install proxygen-cli
-
-        # Setup proxygen auth and settings
-        mkdir -p ${HOME}/.proxygen
-        echo -n $PROXYGEN_PRIVATE_KEY | base64 --decode > ${HOME}/.proxygen/key
-        envsubst < ./.github/proxygen-credentials-template.yaml > ${HOME}/.proxygen/credentials.yaml
-        envsubst < ./.github/proxygen-credentials-template.yaml | cat
-        envsubst < ./.github/proxygen-settings.yaml > ${HOME}/.proxygen/settings.yaml
-        envsubst < ./.github/proxygen-settings.yaml | cat
-
-    - name: Build sandbox oas
+    - name: Build ${{ inputs.apimEnv }} oas
       working-directory: .
+      env:
+        APIM_ENV: ${{ inputs.apimEnv }}
       shell: bash
       run: |
-        make build-json-oas-spec APIM_ENV=sandbox
+        if [ ${{ env.APIM_ENV }} == "internal-dev-sandbox" ] && [ ${{ inputs.buildSandbox }} == true ]
+        then
+          echo "Building sandbox OAS spec"
+          make build-json-oas-spec APIM_ENV=sandbox
+        else
+          echo "Building env specific OAS spec"
+          make build-json-oas-spec APIM_ENV=${{ env.APIM_ENV }}
+        fi
 
-    - name: Set docker tag
-      shell: bash
-      run: |
-        jq --arg newtag "$SANDBOX_TAG" '.["x-nhsd-apim"].target.containers[0].image.tag = $newtag' build/notify-supplier.json > build/notify-supplier_target.json && mv build/notify-supplier_target.json build/notify-supplier.json
+        if [[ $APIM_ENV == *-pr ]]; then
+          echo "Removing pr suffix from APIM_ENV after building OAS and calling proxygen"
+          APIM_ENV=$(echo "$APIM_ENV" | sed 's/-pr$//')
+        fi
+        echo "APIM_ENV=$APIM_ENV" >> $GITHUB_ENV
+
+    - name: Upload OAS Spec
+      uses: actions/upload-artifact@v4
+      with:
+        name: ${{ env.APIM_ENV }}-build-output
+        path: ./build
 
-    - name: Deploy to Internal Dev Sandbox
+    - name: Trigger deploy proxy
+      env:
+        PR_TRIGGER_PAT: ${{ env.PR_TRIGGER_PAT }}
       shell: bash
       run: |
-        proxygen instance deploy internal-dev-sandbox $INSTANCE build/notify-supplier.json --no-confirm
+        .github/scripts/dispatch_internal_repo_workflow.sh \
+          --infraRepoName "nhs-notify-supplier-api" \
+          --releaseVersion "${{ inputs.releaseVersion }}" \
+          --targetComponent "${{ inputs.targetComponent }}" \
+          --targetWorkflow "proxy-deploy.yaml" \
+          --targetEnvironment "${{ inputs.environment }}" \
+          --runId "${{ inputs.runId }}" \
+          --buildSandbox ${{ inputs.buildSandbox }} \
+          --apimEnvironment "${{ env.APIM_ENV }}" \
+          --boundedContext "notify-supplier" \
+          --targetDomain "$TARGET_DOMAIN" \
+          --version "${{ inputs.version }}"

.github/copilot-instructions.md

@@ -0,0 +1,59 @@
+# Copilot Instructions for NHS Notify Supplier API
+
+## Project Overview
+
+- This repository provides the NHS Notify Supplier API for print suppliers to integrate with NHS Notify message queueing.
+- Major components: OpenAPI specification (`specification/api/notify-supplier.yml`), SDKs (`sdk/`), server implementations (`server/`, `src/server/host`), and Lambda handlers (`lambdas/`).
+- Data flows: API requests are modeled via OAS, processed by server/Lambda code, and may interact with AWS services (e.g., S3, database).
+
+## Developer Workflows
+
+- **Build SDKs and Docs:**
+  - Run `make clean && make build` to generate Python/TypeScript SDKs and HTML docs from the OAS spec.
+  - Serve docs locally with `make serve` [default](http://localhost:3050).
+- **CI/CD:**
+  - PRs trigger CI via GitHub Actions (`.github/workflows/cicd-1-pull-request.yaml`).
+  - Merging to `main` creates a pre-release; deployments use `.github/workflows/cicd-3-deploy.yaml`.
+- **Dev Environment:**
+  - Use the provided devcontainer for setup and configuration. Avoid manual SDK changes; always rebuild.
+
+## Project-Specific Conventions
+
+- **SDKs:**
+  - Never manually edit files in `sdk/`; always regenerate from the OAS spec.
+  - SDK folder is excluded from git and built/released via CI.
+- **Servers:**
+  - Server code is generated at build time from OAS specs. See `server/` and `src/server/host` for custom logic.
+- **Test Data:**
+  - Use `scripts/test-data` to generate and upload test letters to S3. Example command:
+
+    ```bash
+    npm run cli -- create-letter --supplier-id ... --environment ... --awsAccountId ... --letter-id ... --group-id ... --specification-id ... --status PENDING
+    ```
+
+## Integration Points
+
+- **External Services:**
+  - AWS S3 and database for test data and letter storage.
+  - OpenAPI Generator CLI for SDK/server generation.
+- **Documentation:**
+  - Latest [docs](https://nhsdigital.github.io/nhs-notify-supplier-api/)
+  - Local docs: `make serve`
+
+## Key Files & Directories
+
+- `specification/api/notify-supplier.yml`: Main API spec
+- `sdk/`: Generated SDKs (Python, TypeScript, CSharp)
+- `server/`, `src/server/host`: Server implementations
+- `lambdas/`: Lambda handlers
+- `scripts/test-data/`: Test data generation scripts
+- `docs/`: Documentation source
+
+## Patterns & Examples
+
+- Always regenerate SDKs/servers after spec changes.
+- Use Makefile targets for all build/test workflows.
+- Reference the README for up-to-date workflow and integration details.
+
+---
+For unclear or missing conventions, consult `/README.md` or ask maintainers for guidance.

.github/scripts/dispatch_internal_repo_workflow.sh

@@ -68,6 +68,10 @@ while [[ $# -gt 0 ]]; do
       internalRef="$2"
       shift 2
       ;;
+    --runId) # Github Run ID (optional)
+      runId="$2"
+      shift 2
+      ;;
     --overrides) # Terraform overrides for passing in extra variables (optional)
       overrides="$2"
       shift 2
@@ -80,6 +84,26 @@ while [[ $# -gt 0 ]]; do
       overrideRoleName="$2"
       shift 2
       ;;
+    --buildSandbox) # Build sandbox flag (optional)
+      buildSandbox="$2"
+      shift 2
+      ;;
+    --apimEnvironment) # APIM environment (optional)
+      apimEnvironment="$2"
+      shift 2
+      ;;
+    --boundedContext) # Bounded context (optional)
+      boundedContext="$2"
+      shift 2
+      ;;
+    --targetDomain) # Target domain (optional)
+      targetDomain="$2"
+      shift 2
+      ;;
+    --version) # Version (optional)
+      version="$2"
+      shift 2
+      ;;
     *)
     echo "[ERROR] Unknown argument: $1"
       exit 1
@@ -101,6 +125,30 @@ if [[ -z "$internalRef" ]]; then
   internalRef="main"
 fi
 
+if [[ -z "$runId" ]]; then
+  runId=""
+fi
+
+if [[ -z "$buildSandbox" ]]; then
+  buildSandbox=""
+fi
+
+if [[ -z "$apimEnvironment" ]]; then
+  apimEnvironment=""
+fi
+
+if [[ -z "$boundedContext" ]]; then
+  boundedContext=""
+fi
+
+if [[ -z "$targetDomain" ]]; then
+  targetDomain=""
+fi
+
+if [[ -z "$version" ]]; then
+  version=""
+fi
+
 echo "==================== Workflow Dispatch Parameters ===================="
 echo "  infraRepoName:      $infraRepoName"
 echo "  releaseVersion:     $releaseVersion"
@@ -114,6 +162,12 @@ echo "  overrides:          $overrides"
 echo "  overrideProjectName: $overrideProjectName"
 echo "  overrideRoleName:   $overrideRoleName"
 echo "  targetProject:      $targetProject"
+echo "  runId:              $runId"
+echo "  buildSandbox:        $buildSandbox"
+echo "  apimEnvironment:     $apimEnvironment"
+echo "  boundedContext:       $boundedContext"
+echo "  targetDomain:         $targetDomain"
+echo "  version:              $version"
 
 DISPATCH_EVENT=$(jq -ncM \
   --arg infraRepoName "$infraRepoName" \
@@ -127,6 +181,12 @@ DISPATCH_EVENT=$(jq -ncM \
   --arg overrideProjectName "$overrideProjectName" \
   --arg overrideRoleName "$overrideRoleName" \
   --arg targetProject "$targetProject" \
+  --arg runId "$runId" \
+  --arg buildSandbox "$buildSandbox" \
+  --arg apimEnvironment "$apimEnvironment" \
+  --arg boundedContext "$boundedContext" \
+  --arg targetDomain "$targetDomain" \
+  --arg version "$version" \
   '{
     "ref": "'"$internalRef"'",
     "inputs": (
@@ -135,18 +195,26 @@ DISPATCH_EVENT=$(jq -ncM \
       (if $overrideProjectName != "" then { "overrideProjectName": $overrideProjectName } else {} end) +
       (if $overrideRoleName != "" then { "overrideRoleName": $overrideRoleName } else {} end) +
       (if $targetProject != "" then { "targetProject": $targetProject } else {} end) +
+      (if $overrides != "" then { "overrides": $overrides } else {} end) +
+      (if $runId != "" then { "runId": $runId } else {} end) +
+      (if $buildSandbox != "" then { "buildSandbox": $buildSandbox } else {} end) +
+      (if $apimEnvironment != "" then { "apimEnvironment": $apimEnvironment } else {} end) +
+      (if $boundedContext != "" then { "boundedContext": $boundedContext } else {} end) +
+      (if $targetDomain != "" then { "targetDomain": $targetDomain } else {} end) +
+      (if $version != "" then { "version": $version } else {} end) +
+      (if $targetAccountGroup != "" then { "targetAccountGroup": $targetAccountGroup } else {} end) +
       {
         "releaseVersion": $releaseVersion,
         "targetEnvironment": $targetEnvironment,
-        "targetAccountGroup": $targetAccountGroup,
         "targetComponent": $targetComponent,
-        "overrides": $overrides,
       }
     )
   }')
 
 echo "[INFO] Triggering workflow '$targetWorkflow' in nhs-notify-internal..."
 
+echo "[DEBUG] Dispatch event payload: $DISPATCH_EVENT"
+
 trigger_response=$(curl -s -L \
   --fail \
   -X POST \
@@ -185,16 +253,12 @@ for _ in {1..18}; do
   workflow_run_url=$(echo "$response" | jq -r \
     --arg targetWorkflow "$targetWorkflow" \
     --arg targetEnvironment "$targetEnvironment" \
-    --arg targetAccountGroup "$targetAccountGroup" \
     --arg targetComponent "$targetComponent" \
-    --arg terraformAction "$terraformAction" \
     '.workflow_runs[]
       | select(.path == ".github/workflows/" + $targetWorkflow)
       | select(.name
           | contains($targetEnvironment)
-          and contains($targetAccountGroup)
           and contains($targetComponent)
-          and contains($terraformAction)
       )
       | .url')