CHI-3954-beacon_mappers_per_helpline

[stephenhand]

Description

• Reorganise beacon poller so beacon document processors are off in their own section
• Rework configuration to be much more generic and more easily scalable to more sets of mapping / processing logic
• Use more generically named SSM parameters

Checklist

• Corresponding issue has been opened
• New tests added
• Feature flags / configuration added

Other Related Issues

CHI-3953

Verification steps

Regression only

AFTER YOU MERGE

1. Cut a release tag using the GitHub workflow. Wait for it to complete and notify in the #aselo-deploys Slack channel.
2. Comment on the ticket with the release tag version AND any additional instructions required to configure an environment to test the changes.
3. Only then move the ticket into the QA column in JIRA

You are responsible for ensuring the above steps are completed. If you move a ticket into QA without advising what version to test, the QA team will assume the latest tag has the changes. If it does not, the following confusion is on you! :-P

[Copilot]

🟡 Changes recommended

There are confirmed runtime/behavioral issues in the new dispatcher’s helpline code extraction and the poller’s per-API chunk sizing configuration.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR generalizes the Beacon integration lambdas by renaming the USCR-specific dispatcher/poller to generic beacon-dispatcher / beacon-poller, reorganizing the poller’s document-processing logic by helpline, and updating CI/deploy configuration to target the new lambda locations and more generic SSM parameter names.

Changes:

• Rename/move USCR-specific lambdas to beacon-dispatcher and beacon-poller, updating build references and GitHub workflows accordingly.
• Refactor beacon poller into helpline-specific “document processor” modules (USCR/AS and GY) and update tests/service-test scaffolding.
• Update SSM parameter conventions to be helpline-short-code based and make configuration scalable to additional mappings.

File summaries

File	Description
tsconfig.json	Update TS project references to renamed beacon lambdas.
package.json	Add ms / @types/ms override/dependency entries.
hrm-domain/lambdas/custom-integrations/uscr-dispatcher/index.ts	Remove old USCR dispatcher entrypoint (replaced by beacon-dispatcher).
hrm-domain/lambdas/custom-integrations/uscr-dispatcher/authentication.ts	Remove old USCR dispatcher auth helper (logic moved/rewritten).
hrm-domain/lambdas/custom-integrations/uscr-beacon-poller/src/index.ts	Remove old USCR poller handler (replaced by beacon-poller).
hrm-domain/lambdas/custom-integrations/beacon-poller/tsconfig.json	Add TS config for beacon-poller.
hrm-domain/lambdas/custom-integrations/beacon-poller/tsconfig.build.json	Update build references for renamed poller + hrm-types.
hrm-domain/lambdas/custom-integrations/beacon-poller/tests/unit/verifyAddSectionRequest.ts	Add shared unit-test helper for verifying HRM section POST calls.
hrm-domain/lambdas/custom-integrations/beacon-poller/tests/unit/responder.test.ts	Add unit coverage for responder mapping.
hrm-domain/lambdas/custom-integrations/beacon-poller/tests/unit/caseUpdater.test.ts	Update unit tests for new case-updater API signatures.
hrm-domain/lambdas/custom-integrations/beacon-poller/tests/unit/beaconDocumentProcessors/uscr/incidentReport.test.ts	Update incident report tests for new processor factory + paths.
hrm-domain/lambdas/custom-integrations/beacon-poller/tests/unit/beaconDocumentProcessors/uscr/caseReport/caseReport.test.ts	Update case report tests for new processor factory + paths.
hrm-domain/lambdas/custom-integrations/beacon-poller/tests/unit/beaconDocumentProcessors/uscr/caseReport/apiPayload.test.ts	Update apiPayload tests for new module location.
hrm-domain/lambdas/custom-integrations/beacon-poller/tests/service/docker-compose.yml	Add local docker-compose stack for service tests.
hrm-domain/lambdas/custom-integrations/beacon-poller/tests/service/docker-compose-ci.yml	Add CI-flavored compose config for service tests.
hrm-domain/lambdas/custom-integrations/beacon-poller/tests/service/dbConnection.ts	Add pg-promise DB connection helper for service tests.
hrm-domain/lambdas/custom-integrations/beacon-poller/tests/service/beaconPoller.test.ts	Update service tests for new SSM paths + handler signature.
hrm-domain/lambdas/custom-integrations/beacon-poller/tests/service/.env.service-test	Update comments to reflect new poller name.
hrm-domain/lambdas/custom-integrations/beacon-poller/tests/mockGenerators.ts	Update mocks to import moved beacon processor types/helpers.
hrm-domain/lambdas/custom-integrations/beacon-poller/tests/fixtures.ts	Update fixtures to import moved apiPayload types.
hrm-domain/lambdas/custom-integrations/beacon-poller/src/types.ts	Introduce Beacon document typing + rename processor type.
hrm-domain/lambdas/custom-integrations/beacon-poller/src/responder.ts	Add responder mapping logic for case sections.
hrm-domain/lambdas/custom-integrations/beacon-poller/src/index.ts	New generic poller entrypoint supporting helpline short codes.
hrm-domain/lambdas/custom-integrations/beacon-poller/src/config.ts	Simplify config constants (remove env-derived headers/accountSid).
hrm-domain/lambdas/custom-integrations/beacon-poller/src/caseUpdater.ts	Refactor case update helpers to be accountSid-driven and generic.
hrm-domain/lambdas/custom-integrations/beacon-poller/src/beaconDocumentProcessors/uscr/index.ts	Add USCR/AS processor exports.
hrm-domain/lambdas/custom-integrations/beacon-poller/src/beaconDocumentProcessors/uscr/incidentReport.ts	Refactor USCR incident report processor into factory.
hrm-domain/lambdas/custom-integrations/beacon-poller/src/beaconDocumentProcessors/uscr/caseReport/index.ts	Refactor USCR case report processor into factory.
hrm-domain/lambdas/custom-integrations/beacon-poller/src/beaconDocumentProcessors/uscr/caseReport/apiPayload.ts	Move content extraction to shared helper module.
hrm-domain/lambdas/custom-integrations/beacon-poller/src/beaconDocumentProcessors/index.ts	Add dispatcher for helpline+apiType → processor mapping.
hrm-domain/lambdas/custom-integrations/beacon-poller/src/beaconDocumentProcessors/gy/index.ts	Add GY processor exports.
hrm-domain/lambdas/custom-integrations/beacon-poller/src/beaconDocumentProcessors/gy/incidentReport.ts	Add GY incident report processor factory.
hrm-domain/lambdas/custom-integrations/beacon-poller/src/beaconDocumentProcessors/gy/caseReport.ts	Add GY case report processor factory.
hrm-domain/lambdas/custom-integrations/beacon-poller/src/beaconDocumentProcessors/extractContentNodeValues.ts	New shared extractor for Beacon “content node” trees.
hrm-domain/lambdas/custom-integrations/beacon-poller/src/apiChunkReader.ts	Update chunk reader types to use BeaconDocumentProcessor.
hrm-domain/lambdas/custom-integrations/beacon-poller/setTestEnvVars.js	Add Jest setup for poller tests/service tests.
hrm-domain/lambdas/custom-integrations/beacon-poller/package.json	Rename package + add test/service-test tooling and scripts.
hrm-domain/lambdas/custom-integrations/beacon-poller/jest.config.js	Add Jest config for poller tests.
hrm-domain/lambdas/custom-integrations/beacon-dispatcher/validation.ts	Simplify validation to payload-only; env/headers handled in handler.
hrm-domain/lambdas/custom-integrations/beacon-dispatcher/tsconfig.json	Add TS config for beacon-dispatcher.
hrm-domain/lambdas/custom-integrations/beacon-dispatcher/tsconfig.build.json	Update build references for renamed dispatcher.
hrm-domain/lambdas/custom-integrations/beacon-dispatcher/package.json	Rename dispatcher package + docker build target.
hrm-domain/lambdas/custom-integrations/beacon-dispatcher/mapping.ts	Minor mapping behavior change (category selection without mutation).
hrm-domain/lambdas/custom-integrations/beacon-dispatcher/index.ts	New generic dispatcher with helpline-short-code path support + SSM lookups.
hrm-domain/lambdas/custom-integrations/beacon-dispatcher/hrm-service/index.ts	Rename/adjust pending-incident detection helper.
hrm-domain/lambdas/custom-integrations/beacon-dispatcher/hrm-service/contactService.ts	Add contact API calls (get/contact connect-to-case).
hrm-domain/lambdas/custom-integrations/beacon-dispatcher/hrm-service/caseService.ts	Add case and case-section CRUD helpers for HRM internal API.
hrm-domain/lambdas/custom-integrations/beacon-dispatcher/beacon-service/index.ts	Export beacon service module surface.
hrm-domain/lambdas/custom-integrations/beacon-dispatcher/beacon-service/incidentService.ts	Make Beacon creds lookup helpline-short-code driven via SSM paths.
.github/workflows/hrm-lambda-deploy.yml	Update deployment matrix paths to renamed lambdas.
.github/workflows/hrm-lambda-deploy-all.yml	Update deploy-all matrix paths to renamed lambdas.
.github/workflows/hrm-ci.yml	Update CI matrix paths to renamed lambdas.
.github/workflows/config/lambda-specific-region-map.json	Update region map keys for renamed lambdas.

Review details

Suppressed comments (3)

hrm-domain/lambdas/custom-integrations/beacon-poller/src/index.ts:21

• This file contains the AGPL header twice; the duplicated block adds noise and makes future edits harder to read.

/**
 * Copyright (C) 2021-2023 Technology Matters
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as published
 * by the Free Software Foundation, either version 3 of the License, or

hrm-domain/lambdas/custom-integrations/beacon-poller/src/beaconDocumentProcessors/uscr/incidentReport.ts:23

• Avoid importing from '@tech-matters/types/dist/index' (internal build output). This can break consumers/build tooling and is inconsistent with other imports in this package; import from the package root instead.
  hrm-domain/lambdas/custom-integrations/beacon-poller/tests/unit/beaconDocumentProcessors/uscr/caseReport/caseReport.test.ts:26
• Avoid importing from '@tech-matters/types/dist/index' in tests as well; it ties tests to an internal path and can break under different build outputs.

• Files reviewed: 19/19 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[gpaoloni]

LGTM! (with annoying comments as usual 😛)

[gpaoloni]

In other places where we do this, we use helplineCode.toUpperCase(). Can we consolidate this one as well?

[gpaoloni]

Since this is evaluated twice so far, would it make sense to move all mappings into a package, and define both things together? I.e. "a mapping" would return createBeaconDocumentProcessor and newCreateIncidentMapper functions? I know that might make harder to follow the types, so I'm not expecting this to change is more of a question.

[gpaoloni]

Also, the internal switch of each mapping (incidentReport, caseReport and default) seem like something we could de-duplicate?

[stephenhand]

The GY code is placeholder, we can't factor assuming that is what it will look like, I don't know if GY will have the same top level sections

[stephenhand]

As for having all the mappers together, it's worth considering. Not sure if we will use the 2 sides of the integration independently ever? If we do it definitely makes sense to keep them in their respective lambda

I think it's best to see how it shakes out if we do the generic, config driven version after TrekMedics refactor the case report side, it will be clearer if there's a lot of shared code between the two mappings then