RELEASE athena contribution w/ appointment type id filtering and encounter summaries #4414
Conversation
Ref: ENG-634 Ref: #1040 Signed-off-by: Thomas Yopes <thomasyopes@Mac.attlocal.net>
Ref: ENG-634 Ref: #1040 Signed-off-by: Thomas Yopes <thomasyopes@Mac.attlocal.net>
Ref: ENG-634 Ref: #1040 Signed-off-by: Thomas Yopes <thomasyopes@Mac.attlocal.net>
Ref: ENG-559 Ref: #1040 Signed-off-by: Thomas Yopes <thomasyopes@Mac.attlocal.net>
…-athena-contribution-update Signed-off-by: Thomas Yopes <thomasyopes@Mac.attlocal.net>
Ref: ENG-634 Ref: #1040 Signed-off-by: Thomas Yopes <thomasyopes@Mac.attlocal.net>
…-athena-contribution-update Signed-off-by: Thomas Yopes <thomasyopes@Mac.attlocal.net>
Ref: ENG-634 Ref: #1040 Signed-off-by: Thomas Yopes <thomasyopes@Mac.attlocal.net>
Ref: ENG-634 Ref: #1040 Signed-off-by: Thomas Yopes <thomasyopes@Mac.attlocal.net>
Ref: ENG-634 Ref: #1040 Signed-off-by: Thomas Yopes <thomasyopes@Mac.attlocal.net>
Ref: ENG-634 Ref: #1040 Signed-off-by: Thomas Yopes <thomasyopes@Mac.attlocal.net>
Ref: ENG-634 Ref: #1040 Signed-off-by: Thomas Yopes <thomasyopes@Mac.attlocal.net>
Ref: ENG-634 Ref: #1040 Signed-off-by: Thomas Yopes <thomasyopes@Mac.attlocal.net>
…source Ref: ENG-634 Ref: #1040 Signed-off-by: Thomas Yopes <thomasyopes@Mac.attlocal.net>
Ref: ENG-634 Ref: #1040 Signed-off-by: Thomas Yopes <thomasyopes@Mac.attlocal.net>
Ref: ENG-634 Ref: #1040 Signed-off-by: Thomas Yopes <thomasyopes@Mac.attlocal.net>
Ref: ENG-634 Ref: #1040 Signed-off-by: Thomas Yopes <thomasyopes@Mac.attlocal.net>
Ref: ENG-634 Ref: #1040 Signed-off-by: Thomas Yopes <thomasyopes@Mac.attlocal.net>
Ref: ENG-634 Ref: #1040 Signed-off-by: Thomas Yopes <thomasyopes@Mac.attlocal.net>
…-athena-contribution-update Signed-off-by: Thomas Yopes <thomasyopes@Mac.attlocal.net>
Ref: ENG-634 Ref: #1040 Signed-off-by: Thomas Yopes <thomasyopes@Mac.attlocal.net>
…-athena-contribution-update Signed-off-by: Thomas Yopes <thomasyopes@Mac.attlocal.net>
Ref: ENG-634 Ref: #1040 Signed-off-by: Thomas Yopes <thomasyopes@Mac.attlocal.net>
Ref: ENG-634 Ref: #1040 Signed-off-by: Thomas Yopes <thomasyopes@Mac.attlocal.net>
…-athena-contribution-update Signed-off-by: Thomas Yopes <thomasyopes@Mac.attlocal.net>
Ref: ENG-634 Ref: #1040 Signed-off-by: Thomas Yopes <thomasyopes@Mac.attlocal.net>
Ref: ENG-634 Ref: #1040 Signed-off-by: Thomas Yopes <thomasyopes@Mac.attlocal.net>
Ref: ENG-634 Ref: #1040 Signed-off-by: Thomas Yopes <thomasyopes@Mac.attlocal.net>
Ref: ENG-634 Ref: #1040 Signed-off-by: Thomas Yopes <thomasyopes@Mac.attlocal.net>
Ref: ENG-634 Ref: #1040 Signed-off-by: Thomas Yopes <thomasyopes@Mac.attlocal.net>
…pdate feat(ehr): sollis contribute ehr summaries + remove bad encounters
|
Caution Review failedThe pull request is closed. WalkthroughCentralizes medical document upload into a new orchestrator that upserts DocumentReference and returns a presigned S3 URL. Adds Athena-specific encounter preprocessing (appointment-type blacklist, optional summaries upload), new S3-backed document fetch utilities, bundle type for removed contributions, schema additions, and minor renames/refactors. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant Client
participant API Route (/medical/document)
participant Orchestrator (getUploadUrlAndCreateDocRef)
participant FHIR Server
participant S3
Client->>API Route: POST /upload-url (docRef draft)
API Route->>Orchestrator: cxId, patientId, docRefDraft
par Parallel ops
Orchestrator->>FHIR Server: Upsert DocumentReference
Orchestrator->>S3: Generate presigned PUT URL (key from doc path)
end
Orchestrator-->>API Route: { documentReferenceId, uploadUrl }
API Route-->>Client: { documentReferenceId, uploadUrl }
note over Client,S3: Client then PUTs file bytes to uploadUrl (application/pdf)
sequenceDiagram
autonumber
participant Caller
participant ContributeDiffBundle
participant MappingsStore
participant AthenaSDK
participant S3 Docs
Caller->>ContributeDiffBundle: contributeResourceDiffBundle(bundle)
ContributeDiffBundle->>MappingsStore: getSecondaryMappings(ehr=athena, practiceId)
MappingsStore-->>ContributeDiffBundle: mappings
alt Blacklist present
ContributeDiffBundle->>ContributeDiffBundle: remove Encounters with blacklisted appointment types
ContributeDiffBundle->>ContributeDiffBundle: remove resources referencing removed Encounters
ContributeDiffBundle->>S3 Docs: create "contribution removed" bundle
end
ContributeDiffBundle->>AthenaSDK: fetch bundle (attachAppointmentType?, fetchEncounterSummary?)
AthenaSDK-->>ContributeDiffBundle: Bundle (with optional appointment types/summaries)
opt Summaries enabled
loop each Encounter needing summary
ContributeDiffBundle->>S3 Docs: fetchDocument(existing?)
alt Missing
ContributeDiffBundle->>Orchestrator: getUploadUrlAndCreateDocRef
Orchestrator-->>ContributeDiffBundle: uploadUrl, docRefId
ContributeDiffBundle->>S3 Docs: PUT HTML summary via uploadUrl
end
end
end
ContributeDiffBundle-->>Caller: completed
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related PRs
Tip 🔌 Remote MCP (Model Context Protocol) integration is now available!Pro plan users can now connect to remote MCP servers from the Integrations page. Connect with popular remote MCPs such as Notion and Linear to add more context to your reviews and chats. 📜 Recent review detailsConfiguration used: CodeRabbit UI 💡 Knowledge Base configuration:
You can enable these sources in your CodeRabbit configuration. 📒 Files selected for processing (1)
✨ Finishing Touches
🧪 Generate unit tests
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
packages/api/Dockerfile.dev (1)
12-18: Add@metriport/fhir-sdkbuild to all production Dockerfiles & align package depsOur scan shows only
packages/api/Dockerfile.devbuildspackages/fhir-sdk. Production Dockerfiles and some downstream packages import the SDK but don’t build it or declare it as a dependency:• packages/api/Dockerfile
– MissingRUN npm run build -w packages/fhir-sdkbefore building the API.
• Other service Dockerfiles (data-transformation/fhir-to-csv,fhir-converter,mllp-server,terminology)
– None include a build forpackages/fhir-sdk; add the same step if their code (directly or viapackages/utils/packages/core) consumes FHIR SDK.
• packages/utils/package.json
– Imports@metriport/fhir-sdkin source but doesn’t declare it; add it todependencies.
• packages/core/package.json
– Correctly declares afile:packages/fhir-sdkdependency—ensure its build order remains after fhir-sdk.Please update the Dockerfiles and package.json files above so that every consumer builds the FHIR SDK first and declares it as a dependency.
packages/core/src/external/ehr/bundle/bundle-shared.ts (1)
93-100: Type guard and union type are inconsistent; fix the narrowingisResourceDiffBundleType returns true for RESOURCE_DIFF_DATA_CONTRIBUTION_REMOVED and RESOURCE_DIFF_WRITE_BACK, but ResourceDiffBundleType excludes both. This makes the type guard unsound and can cause incorrect narrowing downstream.
Recommend expanding the union to match the guard (or restrict the guard). Suggest expanding.
Apply this diff to align the union with the guard:
export type ResourceDiffBundleType = | BundleType.RESOURCE_DIFF_EHR_ONLY | BundleType.RESOURCE_DIFF_METRIPORT_ONLY - | BundleType.RESOURCE_DIFF_DATA_CONTRIBUTION; + | BundleType.RESOURCE_DIFF_DATA_CONTRIBUTION + | BundleType.RESOURCE_DIFF_DATA_CONTRIBUTION_REMOVED + | BundleType.RESOURCE_DIFF_WRITE_BACK;
🧹 Nitpick comments (17)
packages/api/Dockerfile.dev (1)
13-13: Optional: consolidate SDK builds to reduce duplication across DockerfilesIf you maintain similar steps in multiple Dockerfiles, consider a single root NPM script (e.g., build:sdks) that builds shared + fhir-sdk + other SDKs in the correct order, and call that once here. It keeps Dockerfiles DRY and reduces drift.
packages/core/src/external/ehr/unit-conversion.ts (1)
206-209: Clarify semantics: mixing breath-rate units into isBpm may conflate HR vs RR; consider explicit support.If loincCodeMap maps respiratory rate targets to "bpm", this is fine, but it risks mislabeling RR as bpm. Either:
- keep the union intentionally and document it, or
- add a dedicated check (e.g., isRespPerMin) and map RR targets to a neutral unit like "1/min".
Also consider additional common synonyms to improve coverage.
Would you like to include more RR synonyms? Minimal addition shown below.
return ( units === "bpm" || units === "/min" || units === "beats/min" || units === "per minute" || units === "br/min" || units === "breaths/min" || - units === "breaths per minute" + units === "breaths per minute" || + units === "resp/min" || + units === "respirations/min" );packages/core/src/external/fhir/shared/index.ts (1)
307-309: Rename is fine; add a deprecated alias to avoid cross-package breakages.If any downstream package still imports buildEntryReference, a temporary alias smooths the transition.
Apply this alias just below the new function:
export function buildResourceReference(resource: Resource): string { return `${resource.resourceType}/${resource.id}`; } + +/** @deprecated Use buildResourceReference */ +export const buildEntryReference = buildResourceReference;packages/shared/src/interface/external/ehr/athenahealth/cx-mapping.ts (1)
10-12: Schema additions match intended optional controls
- contributionEncounterAppointmentTypesBlacklist: optional string[]
- contributionEncounterSummariesEnabled: optional boolean
These will zod-validate presence/shape and are compatible with “presence implies enablement” semantics downstream.
Consider adding short comments documenting semantics:
- Blacklist: presence enables appointment-type tracking; entries define types to exclude.
- Summaries: true enables encounter summary upload path.
packages/api/src/external/ehr/shared/command/bundle/contribute-resource-diff-bundle.ts (2)
285-331: Summary upload pre-check is sound; minor nit on “predecessor” ID source
- Skips upload if an “upload” job artifact already exists (good).
- Falls back to fetching the “latest” source summary.
Confirm that getPredecessorExtensionValue returning valueRelatedArtifact.display is indeed the canonical encounter identifier expected by your document keying. If the ID should be taken from a Reference or from valueRelatedArtifact.resource, adjust accordingly.
If display is free text in your extension, prefer an explicit identifier field to avoid mismatches.
335-384: Upload flow is correct; ensure headers match presigned policyUsing axios.put with explicit Content-Length and Content-Type is standard. Be aware that some S3 policies require exact matching headers; if presigned URLs include additional constraints (e.g., x-amz-acl), propagate them here.
If needed, extend getUploadUrlAndCreateDocRef to return required headers and pass them through.
packages/core/src/external/ehr/athenahealth/command/get-resource-bundle-by-resource-id.ts (2)
41-46: Avoid enabling attachAppointmentType when the blacklist is emptyAn empty array is truthy in JS/TS, so this condition will enable
attachAppointmentTypeeven when the blacklist is empty. If the intent is to enable only when there are entries, check for length.Apply this minimal change:
- ...(mappings?.contributionEncounterAppointmentTypesBlacklist && { + ...(mappings?.contributionEncounterAppointmentTypesBlacklist?.length && { attachAppointmentType: true, }),
21-33: Minor perf: fetch client and mappings in parallelClient creation and mappings retrieval are independent. You can shave off latency by doing them concurrently.
Apply this refactor:
- const client = await createAthenaHealthClient({ - cxId, - practiceId, - ...(tokenId && { tokenId }), - }); - const mappings = - resourceType === "Encounter" - ? await getSecondaryMappings({ - ehr: EhrSources.athena, - practiceId, - schema: athenaSecondaryMappingsSchema, - }) - : undefined; + const [client, mappings] = await Promise.all([ + createAthenaHealthClient({ + cxId, + practiceId, + ...(tokenId && { tokenId }), + }), + resourceType === "Encounter" + ? getSecondaryMappings({ + ehr: EhrSources.athena, + practiceId, + schema: athenaSecondaryMappingsSchema, + }) + : Promise.resolve(undefined), + ]);packages/core/src/external/ehr/athenahealth/command/get-bundle-by-resource-type.ts (2)
39-44: Avoid enabling attachAppointmentType when the blacklist is emptyAlign with the intent: only set
attachAppointmentTypeif the blacklist has entries.Apply this minimal change:
- ...(mappings?.contributionEncounterAppointmentTypesBlacklist && { + ...(mappings?.contributionEncounterAppointmentTypesBlacklist?.length && { attachAppointmentType: true, }),
25-33: DRY opportunity: extract common Encounter options logicThis Encounter-specific mappings fetch + flag computation is duplicated in both commands. Consider a small helper (e.g.,
getAthenaEncounterRequestOptions(practiceId)) returning{ attachAppointmentType?: true; fetchEncounterSummary?: true }to reduce duplication and ensure parity between the two endpoints.packages/api/src/routes/medical/document.ts (1)
232-241: Consider pushing validation into the shared command to prevent misuseTo ensure future non-route callers don’t bypass validation, you could move
docRefCheckinto the command function (or add an optionalvalidateflag defaulting to true). This keeps invariants centralized.If you want to centralize validation, apply the following changes in the command module (see the next file comment for concrete diffs).
packages/api/src/command/medical/document/get-upload-url-and-create-doc-ref.ts (2)
7-7: Centralize draft validation in the commandImport
docRefCheckalongsidecomposeDocumentReferenceso the command can enforce input validity regardless of caller. This prevents accidental misuse outside the route.Apply this import tweak:
-import { composeDocumentReference } from "../../../external/fhir/document/draft-update-document-reference"; +import { composeDocumentReference, docRefCheck } from "../../../external/fhir/document/draft-update-document-reference";
26-31: Validate draft and enrich logging with docRefIdAdd
docRefCheck(docRefDraft)to enforce invariants and includedocRefIdin the log for better traceability.Apply this change:
- const { log } = out(`getUploadUrlAndCreateDocRef - patient ${patientId}`); + const { log } = out(`getUploadUrlAndCreateDocRef - patient ${patientId} docRefId ${docRefId}`); + docRefCheck(docRefDraft);packages/core/src/external/ehr/athenahealth/index.ts (4)
1567-1576: Avoid unnecessary work when both flags are false.We always call dangerouslyAdjustEncountersInBundle for Encounter resources even if both attachAppointmentType and fetchEncounterSummary are false. Short-circuit to skip the call and the iteration for performance.
Apply this diff:
- if (resourceType === "Encounter") { + if (resourceType === "Encounter" && (attachAppointmentType || fetchEncounterSummary)) { await client.dangerouslyAdjustEncountersInBundle({ cxId, metriportPatientId, athenaPatientId, bundle: validBundle, attachAppointmentType, fetchEncounterSummary, }); }
1668-1677: Repeat the guard here to skip unnecessary adjustment.Same optimization as the other path.
Apply this diff:
- if (resourceType === "Encounter") { + if (resourceType === "Encounter" && (attachAppointmentType || fetchEncounterSummary)) { await client.dangerouslyAdjustEncountersInBundle({ cxId, metriportPatientId, athenaPatientId, bundle: validBundle, attachAppointmentType, fetchEncounterSummary, }); }
1948-1954: Plumb jobId through the params so it can be used downstream.The type for the params includes jobId, but it isn’t destructured, so it’s unavailable inside the function. If we intend to tag S3 documents with jobId (recommended), destructure it here.
Apply this diff:
private async dangerouslyAdjustEncountersInBundle({ cxId, metriportPatientId, athenaPatientId, bundle, + jobId, attachAppointmentType = false, fetchEncounterSummary = false, }: { cxId: string; metriportPatientId: string; athenaPatientId: string; jobId?: string | undefined; bundle: EhrStrictFhirResourceBundle; attachAppointmentType?: boolean; fetchEncounterSummary?: boolean; }): Promise<void> {Also applies to: 1960-1962
2002-2035: Propagate jobId to document fetch/store for better traceability.Pass jobId to fetchDocument and createOrReplaceDocument so generated S3 keys (and logs) can be traced to the running job. This also keeps parity with other document commands.
Apply this diff:
- const existingEncounterSummary = await fetchDocument({ + const existingEncounterSummary = await fetchDocument({ ehr: EhrSources.athena, cxId, metriportPatientId, ehrPatientId: athenaPatientId, documentType: DocumentType.HTML, resourceType: "Encounter", resourceId: encounterId, + jobId, }); @@ - await createOrReplaceDocument({ + await createOrReplaceDocument({ ehr: EhrSources.athena, cxId, metriportPatientId, ehrPatientId: athenaPatientId, documentType: DocumentType.HTML, payload: encounterSummary, resourceType: "Encounter", resourceId: encounterId, + jobId, });
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled
- Linear integration is disabled
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (17)
docs/medical-api/api-reference/document/post-upload-url.mdx(1 hunks)packages/api/Dockerfile.dev(1 hunks)packages/api/src/command/mapping/patient.ts(1 hunks)packages/api/src/command/medical/document/get-upload-url-and-create-doc-ref.ts(1 hunks)packages/api/src/external/ehr/shared/command/bundle/contribute-resource-diff-bundle.ts(3 hunks)packages/api/src/routes/medical/document.ts(4 hunks)packages/core/src/external/ehr/athenahealth/command/get-bundle-by-resource-type.ts(2 hunks)packages/core/src/external/ehr/athenahealth/command/get-resource-bundle-by-resource-id.ts(2 hunks)packages/core/src/external/ehr/athenahealth/index.ts(9 hunks)packages/core/src/external/ehr/bundle/bundle-shared.ts(4 hunks)packages/core/src/external/ehr/bundle/command/fetch-bundle.ts(3 hunks)packages/core/src/external/ehr/document/command/create-or-replace-document.ts(1 hunks)packages/core/src/external/ehr/document/command/fetch-document.ts(1 hunks)packages/core/src/external/ehr/unit-conversion.ts(1 hunks)packages/core/src/external/fhir/shared/index.ts(1 hunks)packages/core/src/external/fhir/shared/references.ts(4 hunks)packages/shared/src/interface/external/ehr/athenahealth/cx-mapping.ts(1 hunks)
🧰 Additional context used
📓 Path-based instructions (3)
**/*.{js,jsx,ts,tsx}
📄 CodeRabbit Inference Engine (.cursorrules)
**/*.{js,jsx,ts,tsx}: Don’t use null inside the app, only on code interacting with external interfaces/services, like DB and HTTP; convert to undefined before sending inwards into the code
Useconstwhenever possible
Useasync/awaitinstead of.then()
Naming: classes, enums: PascalCase
Naming: constants, variables, functions: camelCase
Naming: file names: kebab-case
Naming: Don’t use negative names, likenotEnabled, preferisDisabled
If possible, use decomposing objects for function parameters
Prefer Nullish Coalesce (??) than the OR operator (||) when you want to provide a default value
Avoid creating arrow functions
Use truthy syntax instead ofin- i.e.,if (data.link)notif ('link' in data)
While handling errors, keep the stack trace around: if you create a new Error (e.g., MetriportError), make sure to pass the original error as the new one’s cause so the stack trace is available upstream.
max column length is 100 chars
multi-line comments use/** */
top-level comments go after the import (save pre-import to basic file header, like license)
move literals to constants declared after imports when possible
Files:
packages/core/src/external/ehr/document/command/fetch-document.tspackages/core/src/external/ehr/unit-conversion.tspackages/core/src/external/ehr/athenahealth/command/get-resource-bundle-by-resource-id.tspackages/api/src/routes/medical/document.tspackages/api/src/command/mapping/patient.tspackages/core/src/external/ehr/document/command/create-or-replace-document.tspackages/core/src/external/fhir/shared/index.tspackages/core/src/external/fhir/shared/references.tspackages/api/src/external/ehr/shared/command/bundle/contribute-resource-diff-bundle.tspackages/shared/src/interface/external/ehr/athenahealth/cx-mapping.tspackages/core/src/external/ehr/bundle/bundle-shared.tspackages/core/src/external/ehr/athenahealth/command/get-bundle-by-resource-type.tspackages/api/src/command/medical/document/get-upload-url-and-create-doc-ref.tspackages/core/src/external/ehr/bundle/command/fetch-bundle.tspackages/core/src/external/ehr/athenahealth/index.ts
**/*.{ts,tsx}
📄 CodeRabbit Inference Engine (.cursorrules)
Use types whenever possible
Files:
packages/core/src/external/ehr/document/command/fetch-document.tspackages/core/src/external/ehr/unit-conversion.tspackages/core/src/external/ehr/athenahealth/command/get-resource-bundle-by-resource-id.tspackages/api/src/routes/medical/document.tspackages/api/src/command/mapping/patient.tspackages/core/src/external/ehr/document/command/create-or-replace-document.tspackages/core/src/external/fhir/shared/index.tspackages/core/src/external/fhir/shared/references.tspackages/api/src/external/ehr/shared/command/bundle/contribute-resource-diff-bundle.tspackages/shared/src/interface/external/ehr/athenahealth/cx-mapping.tspackages/core/src/external/ehr/bundle/bundle-shared.tspackages/core/src/external/ehr/athenahealth/command/get-bundle-by-resource-type.tspackages/api/src/command/medical/document/get-upload-url-and-create-doc-ref.tspackages/core/src/external/ehr/bundle/command/fetch-bundle.tspackages/core/src/external/ehr/athenahealth/index.ts
**/*.ts
⚙️ CodeRabbit Configuration File
**/*.ts: - Use the Onion Pattern to organize a package's code in layers
- Try to use immutable code and avoid sharing state across different functions, objects, and systems
- Try to build code that's idempotent whenever possible
- Prefer functional programming style functions: small, deterministic, 1 input, 1 output
- Minimize coupling / dependencies
- Avoid modifying objects received as parameter
- Only add comments to code to explain why something was done, not how it works
- Naming
- classes, enums:
PascalCase- constants, variables, functions:
camelCase- file names:
kebab-case- table and column names:
snake_case- Use meaningful names, so whoever is reading the code understands what it means
- Don’t use negative names, like
notEnabled, preferisDisabled- For numeric values, if the type doesn’t convey the unit, add the unit to the name
- Typescript
- Use types
- Prefer
constinstead oflet- Avoid
anyand casting fromanyto other types- Type predicates: only applicable to narrow down the type, not to force a complete type conversion
- Prefer deconstructing parameters for functions instead of multiple parameters that might be of
the same type- Don’t use
nullinside the app, only on code interacting with external interfaces/services,
like DB and HTTP; convert toundefinedbefore sending inwards into the code- Use
async/awaitinstead of.then()- Use the strict equality operator
===, don’t use abstract equality operator==- When calling a Promise-returning function asynchronously (i.e., not awaiting), use
.catch()to
handle errors (seeprocessAsyncErrorandemptyFunctiondepending on the case)- Date and Time
- Always use
buildDayjs()to createdayjsinstances- Prefer
dayjs.duration(...)to create duration consts and keep them asduration- Prefer Nullish Coalesce (??) than the OR operator (||) to provide a default value
- Avoid creating arrow functions
- U...
Files:
packages/core/src/external/ehr/document/command/fetch-document.tspackages/core/src/external/ehr/unit-conversion.tspackages/core/src/external/ehr/athenahealth/command/get-resource-bundle-by-resource-id.tspackages/api/src/routes/medical/document.tspackages/api/src/command/mapping/patient.tspackages/core/src/external/ehr/document/command/create-or-replace-document.tspackages/core/src/external/fhir/shared/index.tspackages/core/src/external/fhir/shared/references.tspackages/api/src/external/ehr/shared/command/bundle/contribute-resource-diff-bundle.tspackages/shared/src/interface/external/ehr/athenahealth/cx-mapping.tspackages/core/src/external/ehr/bundle/bundle-shared.tspackages/core/src/external/ehr/athenahealth/command/get-bundle-by-resource-type.tspackages/api/src/command/medical/document/get-upload-url-and-create-doc-ref.tspackages/core/src/external/ehr/bundle/command/fetch-bundle.tspackages/core/src/external/ehr/athenahealth/index.ts
🧠 Learnings (27)
📓 Common learnings
Learnt from: thomasyopes
PR: metriport/metriport#4346
File: packages/api/src/external/ehr/shared/command/bundle/contribute-resource-diff-bundle.ts:221-233
Timestamp: 2025-08-14T20:43:26.281Z
Learning: In Athena EHR integration, encounter references are housed specifically in the 'encounter' and 'context' fields as checked by the doesResourceReferToEncounter function in packages/api/src/external/ehr/shared/command/bundle/contribute-resource-diff-bundle.ts. No broadening of encounter reference detection is needed since the current implementation matches Athena's exact data structure.
📚 Learning: 2025-04-21T17:07:30.574Z
Learnt from: thomasyopes
PR: metriport/metriport#3608
File: packages/core/src/external/ehr/canvas/index.ts:451-469
Timestamp: 2025-04-21T17:07:30.574Z
Learning: The `getMetriportOnlyBundleByResourceType` method in CanvasApi returns `Promise<Bundle | undefined>` because the Metriport-only bundle is a computed artifact that may not exist yet. In contrast, `getBundleByResourceType` returns `Promise<Bundle>` because it can always fetch from the EHR API if the S3 cached bundle doesn't exist.
Applied to files:
packages/core/src/external/ehr/document/command/fetch-document.tspackages/core/src/external/ehr/athenahealth/command/get-resource-bundle-by-resource-id.tspackages/api/src/external/ehr/shared/command/bundle/contribute-resource-diff-bundle.tspackages/core/src/external/ehr/bundle/bundle-shared.tspackages/core/src/external/ehr/athenahealth/command/get-bundle-by-resource-type.tspackages/core/src/external/ehr/bundle/command/fetch-bundle.tspackages/core/src/external/ehr/athenahealth/index.ts
📚 Learning: 2025-08-17T18:46:42.110Z
Learnt from: leite08
PR: metriport/metriport#4399
File: packages/scripts/deploy-api.sh:29-30
Timestamp: 2025-08-17T18:46:42.110Z
Learning: In the Metriport codebase, `/dist` directories for SDK packages (like `packages/fhir-sdk/dist`) are generated at build time and not committed to the repository. Deployment scripts correctly reference these build artifacts that exist during the CI/CD pipeline packaging step.
Applied to files:
packages/api/Dockerfile.dev
📚 Learning: 2025-03-19T13:58:17.253Z
Learnt from: leite08
PR: metriport/metriport#3463
File: packages/api-sdk/src/medical/models/patient.ts:1-1
Timestamp: 2025-03-19T13:58:17.253Z
Learning: When changes are made to SDK packages (`api-sdk`, `commonwell-sdk`, `carequality-sdk`) or `packages/shared` in the Metriport codebase, alpha versions need to be published to NPM before merging the PR.
Applied to files:
packages/api/Dockerfile.dev
📚 Learning: 2025-08-13T21:37:33.680Z
Learnt from: thomasyopes
PR: metriport/metriport#4346
File: packages/core/src/external/ehr/athenahealth/command/get-bundle-by-resource-type.ts:25-29
Timestamp: 2025-08-13T21:37:33.680Z
Learning: In Athena EHR integration (packages/core/src/external/ehr/athenahealth/command/get-bundle-by-resource-type.ts), thomasyopes prefers hard-failing when secondary mappings fetch fails rather than graceful degradation, because these mappings control critical behaviors like contributionEncounterAppointmentTypesBlacklist and contributionEncounterSummariesEnabled. Running with default values when mappings are unavailable could lead to incorrect processing.
Applied to files:
packages/core/src/external/ehr/athenahealth/command/get-resource-bundle-by-resource-id.tspackages/api/src/external/ehr/shared/command/bundle/contribute-resource-diff-bundle.tspackages/shared/src/interface/external/ehr/athenahealth/cx-mapping.tspackages/core/src/external/ehr/athenahealth/command/get-bundle-by-resource-type.tspackages/core/src/external/ehr/athenahealth/index.ts
📚 Learning: 2025-08-14T20:43:26.281Z
Learnt from: thomasyopes
PR: metriport/metriport#4346
File: packages/api/src/external/ehr/shared/command/bundle/contribute-resource-diff-bundle.ts:221-233
Timestamp: 2025-08-14T20:43:26.281Z
Learning: In Athena EHR integration, encounter references are housed specifically in the 'encounter' and 'context' fields as checked by the doesResourceReferToEncounter function in packages/api/src/external/ehr/shared/command/bundle/contribute-resource-diff-bundle.ts. No broadening of encounter reference detection is needed since the current implementation matches Athena's exact data structure.
Applied to files:
packages/core/src/external/ehr/athenahealth/command/get-resource-bundle-by-resource-id.tspackages/core/src/external/fhir/shared/references.tspackages/api/src/external/ehr/shared/command/bundle/contribute-resource-diff-bundle.tspackages/shared/src/interface/external/ehr/athenahealth/cx-mapping.tspackages/core/src/external/ehr/athenahealth/command/get-bundle-by-resource-type.tspackages/core/src/external/ehr/athenahealth/index.ts
📚 Learning: 2025-05-28T19:22:09.281Z
Learnt from: thomasyopes
PR: metriport/metriport#3882
File: packages/core/src/external/ehr/command/get-bundle-by-resource-type/ehr-get-bundle-by-resource-type-cloud.ts:27-49
Timestamp: 2025-05-28T19:22:09.281Z
Learning: In packages/core/src/external/ehr/command/get-bundle-by-resource-type/ehr-get-bundle-by-resource-type-cloud.ts, the EHR get bundle by resource type Lambda endpoint is guaranteed to return valid JSON, so JSON.parse() error handling is not necessary for this specific endpoint.
Applied to files:
packages/core/src/external/ehr/athenahealth/command/get-resource-bundle-by-resource-id.tspackages/core/src/external/ehr/bundle/bundle-shared.tspackages/core/src/external/ehr/athenahealth/command/get-bundle-by-resource-type.tspackages/core/src/external/ehr/athenahealth/index.ts
📚 Learning: 2025-06-06T16:45:31.832Z
Learnt from: thomasyopes
PR: metriport/metriport#3970
File: packages/api/src/external/ehr/athenahealth/command/write-back/medication.ts:17-17
Timestamp: 2025-06-06T16:45:31.832Z
Learning: The writeMedicationToChart function in packages/api/src/external/ehr/athenahealth/command/write-back/medication.ts returns a response that is not currently used by any consumers, so changes to its return type are not breaking changes in practice.
Applied to files:
packages/core/src/external/ehr/athenahealth/command/get-resource-bundle-by-resource-id.tspackages/api/src/command/mapping/patient.tspackages/shared/src/interface/external/ehr/athenahealth/cx-mapping.tspackages/core/src/external/ehr/athenahealth/index.ts
📚 Learning: 2025-05-28T19:20:47.442Z
Learnt from: thomasyopes
PR: metriport/metriport#3882
File: packages/core/src/external/ehr/lambdas/get-bundle-by-resource-type/ehr-get-bundle-by-resource-type-cloud.ts:0-0
Timestamp: 2025-05-28T19:20:47.442Z
Learning: In packages/core/src/external/ehr/lambdas/get-bundle-by-resource-type/ehr-get-bundle-by-resource-type-cloud.ts, the EHR get bundle by resource type Lambda endpoint is guaranteed to return valid JSON, so JSON.parse() error handling is not necessary for this specific endpoint.
Applied to files:
packages/core/src/external/ehr/athenahealth/command/get-resource-bundle-by-resource-id.tspackages/core/src/external/ehr/bundle/bundle-shared.tspackages/core/src/external/ehr/athenahealth/command/get-bundle-by-resource-type.tspackages/core/src/external/ehr/athenahealth/index.ts
📚 Learning: 2025-08-11T23:36:57.573Z
Learnt from: thomasyopes
PR: metriport/metriport#4315
File: packages/core/src/external/ehr/healthie/index.ts:622-657
Timestamp: 2025-08-11T23:36:57.573Z
Learning: In the Healthie EHR integration's `getResourceBundleByResourceId` method, returning an empty bundle when a resource doesn't exist (by using `fetchResourcesFromEhr: () => Promise.resolve([])`) is intentional design. Empty bundles are an acceptable state for non-existent resources rather than throwing NotFoundError.
Applied to files:
packages/core/src/external/ehr/athenahealth/command/get-resource-bundle-by-resource-id.tspackages/core/src/external/ehr/bundle/bundle-shared.tspackages/core/src/external/ehr/athenahealth/command/get-bundle-by-resource-type.ts
📚 Learning: 2025-05-20T21:26:26.804Z
Learnt from: leite08
PR: metriport/metriport#3814
File: packages/api/src/routes/internal/medical/patient-consolidated.ts:141-174
Timestamp: 2025-05-20T21:26:26.804Z
Learning: The functionality introduced in packages/api/src/routes/internal/medical/patient-consolidated.ts is planned to be refactored in downstream PR #3857, including improvements to error handling and validation.
Applied to files:
packages/api/src/routes/medical/document.tspackages/api/src/command/mapping/patient.tspackages/api/src/external/ehr/shared/command/bundle/contribute-resource-diff-bundle.tspackages/api/src/command/medical/document/get-upload-url-and-create-doc-ref.ts
📚 Learning: 2025-06-18T21:05:22.256Z
Learnt from: RamilGaripov
PR: metriport/metriport#3976
File: packages/api/src/routes/medical/patient.ts:541-543
Timestamp: 2025-06-18T21:05:22.256Z
Learning: In packages/api/src/routes/medical/patient.ts, inline schema definitions like cohortIdSchema are acceptable and don't need to be moved to separate schema files when the user prefers to keep them inline.
Applied to files:
packages/api/src/routes/medical/document.ts
📚 Learning: 2025-06-13T20:24:16.668Z
Learnt from: thomasyopes
PR: metriport/metriport#3997
File: packages/api/src/routes/internal/medical/patient-job.ts:28-29
Timestamp: 2025-06-13T20:24:16.668Z
Learning: In packages/api/src/routes/internal/medical/patient-job.ts, mounting patientJobsRouter at the root path before other route handlers is intentional behavior, even though it could potentially consume requests before later handlers.
Applied to files:
packages/api/src/routes/medical/document.ts
📚 Learning: 2025-06-18T18:50:40.968Z
Learnt from: keshavsaharia
PR: metriport/metriport#4045
File: packages/core/src/external/surescripts/fhir/shared.ts:87-93
Timestamp: 2025-06-18T18:50:40.968Z
Learning: The `getResourceFromResourceMap` function in `packages/core/src/external/surescripts/fhir/shared.ts` works correctly as implemented. The comparison `resourceValue === resourceMap[key]` where `resourceValue = resource[key]` is intentional and functions as designed, despite appearing to compare different types.
Applied to files:
packages/core/src/external/fhir/shared/index.ts
📚 Learning: 2025-06-19T22:44:49.393Z
Learnt from: thomasyopes
PR: metriport/metriport#4061
File: packages/api/src/external/ehr/shared/job/bundle/create-resource-diff-bundles/run-job.ts:34-47
Timestamp: 2025-06-19T22:44:49.393Z
Learning: In packages/api/src/external/ehr/shared/job/bundle/create-resource-diff-bundles/run-job.ts, the team prefers to keep refreshEhrBundles operations grouped using fire-and-forget pattern rather than awaiting all operations with Promise.allSettled(). This allows individual refresh operations to run independently without blocking the job runner.
Applied to files:
packages/api/src/external/ehr/shared/command/bundle/contribute-resource-diff-bundle.tspackages/core/src/external/ehr/athenahealth/index.ts
📚 Learning: 2025-04-21T03:47:54.332Z
Learnt from: lucasdellabella
PR: metriport/metriport#3608
File: packages/core/src/external/ehr/resource-diff/steps/start/ehr-start-resource-diff-local.ts:0-0
Timestamp: 2025-04-21T03:47:54.332Z
Learning: In the EHR resource diff implementation, bundles should always have an `entry` property, and code should be allowed to throw if `entry` is missing rather than using null-coalescing operators, as this represents an unexpected state that should be caught and addressed.
Applied to files:
packages/api/src/external/ehr/shared/command/bundle/contribute-resource-diff-bundle.tspackages/core/src/external/ehr/bundle/bundle-shared.tspackages/core/src/external/ehr/athenahealth/index.ts
📚 Learning: 2025-05-28T02:32:27.527Z
Learnt from: lucasdellabella
PR: metriport/metriport#3907
File: packages/core/src/external/fhir/adt-encounters.ts:118-143
Timestamp: 2025-05-28T02:32:27.527Z
Learning: In packages/core/src/external/fhir/adt-encounters.ts, conversion bundles stored by saveAdtConversionBundle do not require version ID assertions or versioning, unlike the sourced encounter data stored by putAdtSourcedEncounter which does require versionId validation.
Applied to files:
packages/api/src/external/ehr/shared/command/bundle/contribute-resource-diff-bundle.tspackages/core/src/external/ehr/athenahealth/command/get-bundle-by-resource-type.tspackages/core/src/external/ehr/athenahealth/index.ts
📚 Learning: 2025-05-08T19:41:36.533Z
Learnt from: thomasyopes
PR: metriport/metriport#3788
File: packages/api/src/external/ehr/shared/utils/bundle.ts:83-93
Timestamp: 2025-05-08T19:41:36.533Z
Learning: In the Metriport codebase, the team prefers to let errors bubble up naturally in some cases rather than adding explicit error handling at every layer, as demonstrated in the refreshEhrBundle function in the bundle.ts file.
Applied to files:
packages/api/src/external/ehr/shared/command/bundle/contribute-resource-diff-bundle.tspackages/core/src/external/ehr/bundle/command/fetch-bundle.ts
📚 Learning: 2025-05-19T18:24:41.632Z
Learnt from: thomasyopes
PR: metriport/metriport#3870
File: packages/core/src/external/ehr/bundle/job/create-resource-diff-bundles/steps/compute/ehr-compute-resource-diff-bundles-local.ts:55-91
Timestamp: 2025-05-19T18:24:41.632Z
Learning: In EHR bundles related to resource diff computations, bundle creation operations that are for auditing purposes should not stop the main job flow if they fail. These operations typically use try/catch blocks that log errors without rethrowing them, which is the intended behavior.
Applied to files:
packages/api/src/external/ehr/shared/command/bundle/contribute-resource-diff-bundle.tspackages/core/src/external/ehr/bundle/bundle-shared.ts
📚 Learning: 2025-04-23T21:19:02.589Z
Learnt from: thomasyopes
PR: metriport/metriport#3709
File: packages/api/src/external/ehr/canvas/command/bundle/fetch-ehr-bundle.ts:63-72
Timestamp: 2025-04-23T21:19:02.589Z
Learning: In the metriport codebase, factory functions like `fetchCanvasBundle` in the Canvas EHR subsystem intentionally let errors bubble up to the caller rather than handling them at the factory function level.
Applied to files:
packages/api/src/external/ehr/shared/command/bundle/contribute-resource-diff-bundle.tspackages/core/src/external/ehr/bundle/command/fetch-bundle.ts
📚 Learning: 2025-08-13T21:36:10.069Z
Learnt from: thomasyopes
PR: metriport/metriport#4346
File: packages/core/src/external/ehr/athenahealth/command/get-bundle-by-resource-type.ts:36-41
Timestamp: 2025-08-13T21:36:10.069Z
Learning: For contributionEncounterSummariesEnabled in Athena secondary mappings, strict boolean checking (=== true) is unnecessary because Zod schema validation ensures the value is boolean or undefined, making truthy checks sufficient.
Applied to files:
packages/shared/src/interface/external/ehr/athenahealth/cx-mapping.ts
📚 Learning: 2025-08-13T21:36:10.069Z
Learnt from: thomasyopes
PR: metriport/metriport#4346
File: packages/core/src/external/ehr/athenahealth/command/get-bundle-by-resource-type.ts:36-41
Timestamp: 2025-08-13T21:36:10.069Z
Learning: In Athena EHR integration, when contributionEncounterAppointmentTypesBlacklist is present (even if empty), attachAppointmentType should be enabled to start tracking appointment type IDs for future use, rather than only enabling when the array has items.
Applied to files:
packages/shared/src/interface/external/ehr/athenahealth/cx-mapping.tspackages/core/src/external/ehr/athenahealth/index.ts
📚 Learning: 2025-06-11T21:39:26.805Z
Learnt from: thomasyopes
PR: metriport/metriport#4000
File: packages/core/src/external/ehr/athenahealth/index.ts:504-507
Timestamp: 2025-06-11T21:39:26.805Z
Learning: In AthenaHealth write-back (`packages/core/src/external/ehr/athenahealth/index.ts`), only the condition statuses “relapse” and “recurrence” are currently mapped to AthenaHealth problem statuses (“CHRONIC”); other FHIR clinicalStatus values (e.g., “active”, “resolved”, “inactive”, “remission”) are not yet supported.
Applied to files:
packages/shared/src/interface/external/ehr/athenahealth/cx-mapping.ts
📚 Learning: 2025-06-20T15:35:00.546Z
Learnt from: thomasyopes
PR: metriport/metriport#3891
File: packages/api/src/routes/internal/ehr/patient.ts:142-142
Timestamp: 2025-06-20T15:35:00.546Z
Learning: In the EHR resource diff contribution system, there are no "invalid" resource types. The system is designed to gracefully handle any resource type string by attempting to find a corresponding bundle, and if no bundle exists for that resource type, it will simply exit early rather than throwing an error.
Applied to files:
packages/core/src/external/ehr/bundle/bundle-shared.ts
📚 Learning: 2025-05-08T19:45:07.783Z
Learnt from: thomasyopes
PR: metriport/metriport#3788
File: packages/api/src/external/ehr/shared/command/bundle/fetch-bundle-presignd-urls.ts:45-62
Timestamp: 2025-05-08T19:45:07.783Z
Learning: In the Metriport codebase, the preferred error handling strategy is to let errors bubble up rather than catching and handling them at lower levels, especially in bundle operations like `fetchBundlePreSignedUrls`.
Applied to files:
packages/core/src/external/ehr/bundle/command/fetch-bundle.ts
📚 Learning: 2025-04-23T18:57:54.964Z
Learnt from: thomasyopes
PR: metriport/metriport#3608
File: packages/api/src/external/ehr/canvas/command/bundle/fetch-ehr-bundle.ts:62-72
Timestamp: 2025-04-23T18:57:54.964Z
Learning: In the metriport codebase, factory implementations like `fetchCanvasBundle` intentionally let errors bubble up to the caller rather than handling them at the factory function level.
Applied to files:
packages/core/src/external/ehr/bundle/command/fetch-bundle.ts
📚 Learning: 2025-04-23T21:19:08.443Z
Learnt from: thomasyopes
PR: metriport/metriport#3709
File: packages/api/src/external/ehr/canvas/command/bundle/fetch-resource-diff-bundle.ts:62-73
Timestamp: 2025-04-23T21:19:08.443Z
Learning: In the metriport codebase, factory functions like `fetchResourceDiffBundle` intentionally let errors bubble up to the caller rather than handling them at the factory function level. This is a consistent pattern across factory implementations.
Applied to files:
packages/core/src/external/ehr/bundle/command/fetch-bundle.ts
🧬 Code Graph Analysis (9)
packages/core/src/external/ehr/document/command/fetch-document.ts (2)
packages/core/src/external/ehr/document/document-shared.ts (2)
DocumentKeyBaseParams(47-57)createKeyAndExtensionMap(35-41)packages/core/src/util/log.ts (1)
out(30-35)
packages/core/src/external/ehr/athenahealth/command/get-resource-bundle-by-resource-id.ts (2)
packages/core/src/external/ehr/api/get-secondary-mappings.ts (1)
getSecondaryMappings(17-41)packages/shared/src/interface/external/ehr/athenahealth/cx-mapping.ts (1)
athenaSecondaryMappingsSchema(4-13)
packages/api/src/routes/medical/document.ts (1)
packages/api/src/command/medical/document/get-upload-url-and-create-doc-ref.ts (1)
getUploadUrlAndCreateDocRef(15-56)
packages/core/src/external/ehr/document/command/create-or-replace-document.ts (1)
packages/shared/src/index.ts (1)
BadRequestError(42-42)
packages/core/src/external/fhir/shared/references.ts (1)
packages/core/src/external/fhir/shared/index.ts (1)
buildResourceReference(307-309)
packages/api/src/external/ehr/shared/command/bundle/contribute-resource-diff-bundle.ts (12)
packages/api/src/command/mapping/cx.ts (1)
getCxMappingOrFail(54-63)packages/shared/src/index.ts (2)
MetriportError(43-43)errorToString(45-45)packages/shared/src/interface/external/ehr/athenahealth/cx-mapping.ts (1)
athenaSecondaryMappingsSchema(4-13)packages/core/src/external/ehr/athenahealth/index.ts (1)
getEncounterAppointmentTypeIdExtension(175-180)packages/core/src/external/fhir/shared/index.ts (1)
buildResourceReference(307-309)packages/core/src/external/ehr/bundle/command/create-or-replace-bundle.ts (1)
createOrReplaceBundle(32-96)packages/shared/src/interface/external/ehr/fhir-resource.ts (1)
createBundleFromResourceList(56-61)packages/core/src/util/log.ts (1)
out(30-35)packages/core/src/external/ehr/document/command/fetch-document.ts (1)
fetchDocument(40-97)packages/api/src/command/medical/document/get-upload-url-and-create-doc-ref.ts (1)
getUploadUrlAndCreateDocRef(15-56)packages/core/src/external/ehr/document/command/create-or-replace-document.ts (1)
createOrReplaceDocument(33-89)packages/lambdas/src/shared/capture.ts (1)
capture(19-118)
packages/core/src/external/ehr/athenahealth/command/get-bundle-by-resource-type.ts (2)
packages/core/src/external/ehr/api/get-secondary-mappings.ts (1)
getSecondaryMappings(17-41)packages/shared/src/interface/external/ehr/athenahealth/cx-mapping.ts (1)
athenaSecondaryMappingsSchema(4-13)
packages/api/src/command/medical/document/get-upload-url-and-create-doc-ref.ts (4)
packages/core/src/external/aws/s3.ts (1)
S3Utils(140-570)packages/shared/src/util/uuid-v7.ts (1)
uuidv7(369-371)packages/core/src/util/log.ts (1)
out(30-35)packages/core/src/domain/document/filename.ts (1)
createDocumentFilePath(11-18)
packages/core/src/external/ehr/athenahealth/index.ts (2)
packages/core/src/external/ehr/document/command/fetch-document.ts (1)
fetchDocument(40-97)packages/core/src/external/ehr/document/command/create-or-replace-document.ts (1)
createOrReplaceDocument(33-89)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: e2e-tests / E2E Tests
- GitHub Check: Analyze (javascript)
🔇 Additional comments (32)
packages/api/Dockerfile.dev (1)
13-13: Good addition: ensure fhir-sdk is built into the imageAdding the fhir-sdk build step aligns with the repo’s pattern where SDK /dist artifacts are produced at build time (per prior learnings) and prevents runtime “module not found” issues when code starts importing it.
packages/core/src/external/ehr/document/command/create-or-replace-document.ts (1)
53-55: LGTM: defensive guard now clearly scoped.The added braces around the throw improve readability without changing behavior.
docs/medical-api/api-reference/document/post-upload-url.mdx (1)
140-147: Example update to PDF upload looks good.The guidance to use Content-Type: application/pdf and the renamed fileContent variable align with the new upload flow.
packages/api/src/command/mapping/patient.ts (1)
97-102: Verify Healthie support in parseExternalId & downstream flowsFile: packages/api/src/command/mapping/patient.ts
Lines: 97–102export const defaultSources = [ EhrSources.athena, EhrSources.canvas, EhrSources.elation, EhrSources.healthie, ];Please confirm the following:
- parseExternalId (in
external-id.ts) only special-casesEhrSources.athenaand otherwise returns the raw ID. Verify that falling through forEhrSources.healthieis correct.- Any calls to
getSourceMapForPatient(…)that omit thesourcesparameter now includehealthie. Locate all single-argument calls and ensure those consumers handle Healthie inputs without unintended data fan-out.packages/core/src/external/fhir/shared/index.ts (1)
301-302: Rename verified: no remainingbuildEntryReferenceusagesAll occurrences of
buildEntryReferencehave been replaced withbuildResourceReferenceacross the repository.
- Confirmed no calls to
buildEntryReference(- Confirmed no imports of
buildEntryReferenceNo further action required.
packages/core/src/external/fhir/shared/references.ts (2)
12-12: Import rename aligns with shared helper; safe changeSwitching to buildResourceReference centralizes reference formatting and keeps behavior consistent with toReference in this module.
113-114: Reference construction is correct for FHIR Encounter-related componentsUsing buildResourceReference(resource) to populate the Reference.reference string (e.g., "Practitioner/123") is appropriate for EncounterParticipant.individual, EncounterLocation.location, and EncounterDiagnosis.condition.
Also applies to: 122-123, 131-132
packages/core/src/external/ehr/bundle/bundle-shared.ts (3)
47-51: New file key for “contribution removed” bundles is consistentNaming and path convention match existing keys and prefixing.
81-81: Enum extension for removal bundle type looks goodRESOURCE_DIFF_DATA_CONTRIBUTION_REMOVED integrates cleanly with existing BundleType.
109-111: Key map entry for removal bundle is correctMapping to createFileKeyResourceDiffDataContributionRemoved is consistent with others.
packages/api/src/external/ehr/shared/command/bundle/contribute-resource-diff-bundle.ts (4)
70-81: Hard-fail on missing Athena secondary mappings matches intended behaviorThe fetch of CX mapping by practiceId, schema parse, and explicit MetriportError when missing are aligned with prior decisions to avoid silent defaults.
176-184: Partition-based removal is correct and efficientUsing a Set for membership and lodash.partition to split keep/remove lists is clean and O(n).
233-272: Auditing bundle creation failure is non-fatal by designCatching and logging errors while creating the “contribution removed” bundle matches the established pattern for audit artifacts not blocking main flow.
205-220: Encounter reference detection misses DocumentReference.context.encounter[]; fix shape handlingdoesResourceReferenceEncounter currently checks:
- resource.encounter.reference (ok for single Reference)
- resource.context.reference (incorrect: DocumentReference.context is an object whose encounter is Reference[])
This will fail to remove DocumentReferences linked to excluded Encounters, leaving dangling artifacts.
Refactor to handle both single Reference and arrays under context.encounter.
Apply this diff:
function doesResourceReferenceEncounter( resource: Resource, encounterReferences: string[] ): boolean { - if ("encounter" in resource) { - const encounter = resource.encounter; - if (!encounter || !encounter.reference) return false; - return encounterReferences.includes(encounter.reference); - } - if ("context" in resource) { - const context = resource.context; - if (!context || !("reference" in context) || !context.reference) return false; - return encounterReferences.includes(context.reference); - } - return false; + const asAny = resource as any; + // Handle Resource.encounter as Reference or Reference[] + if (asAny.encounter) { + const refs = Array.isArray(asAny.encounter) ? asAny.encounter : [asAny.encounter]; + if (refs.some((r: any) => r?.reference && encounterReferences.includes(r.reference))) { + return true; + } + } + // Handle DocumentReference.context.encounter as Reference[] + const ctx = asAny.context; + if (ctx?.encounter) { + const ctxRefs = Array.isArray(ctx.encounter) ? ctx.encounter : [ctx.encounter]; + if (ctxRefs.some((r: any) => r?.reference && encounterReferences.includes(r.reference))) { + return true; + } + } + return false; }⛔ Skipped due to learnings
Learnt from: thomasyopes PR: metriport/metriport#4346 File: packages/api/src/external/ehr/shared/command/bundle/contribute-resource-diff-bundle.ts:221-233 Timestamp: 2025-08-14T20:43:26.281Z Learning: In Athena EHR integration, encounter references are housed specifically in the 'encounter' and 'context' fields as checked by the doesResourceReferToEncounter function in packages/api/src/external/ehr/shared/command/bundle/contribute-resource-diff-bundle.ts. No broadening of encounter reference detection is needed since the current implementation matches Athena's exact data structure.packages/core/src/external/ehr/document/command/fetch-document.ts (3)
23-24: Constant for URL validity is appropriatedocumentUrlDuration = 1 hour is centralized and reused; good for consistency.
40-97: Robust S3 fetch with retries and contextual errors
- Validates documentType via map
- Early-exits on missing file
- Batches content and metadata fetch under executeWithNetworkRetries
- Throws MetriportError with rich context
LGTM.
116-169: S3Utils.getSignedUrl parameter names align with implementationThe parameter names
bucketName,fileName, anddurationSecondsin your call match thegetSignedUrlsignature exactly. No changes needed.packages/core/src/external/ehr/athenahealth/command/get-resource-bundle-by-resource-id.ts (2)
26-33: Hard-fail on secondary mappings fetch for Encounters — LGTMFetching Athena secondary mappings only for Encounters and allowing failures to bubble up aligns with prior decision to hard-fail when mappings control critical behavior. Good call.
41-46: Athena client already supports both new flagsI’ve confirmed that in packages/core/src/external/ehr/athenahealth/index.ts the AthenaHealthApi methods getResourceBundleByResourceId and getBundleByResourceType declare, default, and wire through both attachAppointmentType and fetchEncounterSummary. No further changes needed here.
packages/core/src/external/ehr/athenahealth/command/get-bundle-by-resource-type.ts (2)
25-33: Hard-fail on mappings fetch for Encounters — LGTMSame pattern here as per-resource-id: fetching mappings only for Encounters and letting failures bubble up is consistent with the chosen approach. Looks good.
39-44: Parity Confirmed for Athena Command FlagsShell diff shows both
packages/core/src/external/ehr/athenahealth/command/get-bundle-by-resource-type.tspackages/core/src/external/ehr/athenahealth/command/get-resource-bundle-by-resource-id.tsinclude identical mapping logic:
mappings?.contributionEncounterAppointmentTypesBlacklist→attachAppointmentType: truemappings?.contributionEncounterSummariesEnabled→fetchEncounterSummary: trueNo discrepancies found—no further action needed.
packages/core/src/external/ehr/bundle/command/fetch-bundle.ts (2)
52-53: S3 bucket paramization + richer error context — LGTMAdding
s3BucketNamewith a sensible default, threading it through S3 calls, and enriching error context (including the bucket and key) improves operability and debuggability.Also applies to: 75-83, 88-102
164-176: Pre-signed URL path improvements — LGTMClearer error message and inclusion of
keyands3BucketNamein the context are solid improvements.packages/api/src/routes/medical/document.ts (3)
232-241: Centralizing upload orchestration — LGTMValidating via
docRefCheckhere and delegating to the shared command is the right move. This removes route-level S3/FHIR coupling and improves reuse.
279-287: New /upload route return payload — LGTMReturning
{ documentReferenceId, uploadUrl }from the centralized command is a clean contract and will help clients track the DocumentReference immediately.
256-265: Verify deprecated/upload-urlresponse shape and update docs/tests
I didn’t find any references in docs (MD/MDX), code, or tests forPOST /document/upload-url. Please:
- Confirm existing clients still expect the raw URL string response
- Update any documentation or automated tests to reflect this behavior if they rely on
/upload-urlpackages/api/src/command/medical/document/get-upload-url-and-create-doc-ref.ts (1)
15-25: Command signature and overall flow — LGTMClear contract, deterministic behavior, parallelizing FHIR upsert with URL generation, and no unnecessary arrow functions. Good adherence to the codebase patterns.
packages/core/src/external/ehr/athenahealth/index.ts (5)
6-8: Imports look good and purposeful.Aliasing Encounter to EncounterFhir and adding Extension is appropriate for the new helper, and the new fetchDocument import is used correctly below.
Also applies to: 123-123
172-181: Helper for extracting appointment-type extension: solid addition.Encapsulating the URL and providing a typed accessor increases reuse and readability. No issues spotted.
1609-1620: New flags on getResourceBundleByResourceId: API remains backward compatible.Defaults and typing look good. No concerns here.
1976-1976: Encounter narrowing check: LGTM.The guard correctly ensures only Encounter resources are processed.
1504-1514: Mapping logic validated—flags correctly driven by secondary mappingsVerified that in packages/core/src/external/ehr/athenahealth/command/get-bundle-by-resource-type.ts (and the analogous get-resource-bundle-by-resource-id.ts):
attachAppointmentTypeis enabled whenevermappings.contributionEncounterAppointmentTypesBlacklistis present (empty array is truthy in JS/TS), matching the learning.fetchEncounterSummaryis enabled only whenmappings.contributionEncounterSummariesEnabledistrue.No changes required.
| if (secondaryMappings.contributionEncounterAppointmentTypesBlacklist) { | ||
| await dangerouslyRemoveEncounterEntriesWithBlacklistedAppointmentType({ | ||
| ehr, | ||
| cxId, | ||
| metriportPatientId, | ||
| ehrPatientId, | ||
| resourceType, | ||
| jobId, | ||
| bundle: bundle.bundle, | ||
| blacklistedAppointmentTypes: | ||
| secondaryMappings.contributionEncounterAppointmentTypesBlacklist, | ||
| }); | ||
| } |
There was a problem hiding this comment.
💡 Verification agent
🧩 Analysis chain
Presence vs. emptiness of blacklist: verify intent to remove encounters without extension
Currently, if contributionEncounterAppointmentTypesBlacklist is present (even empty), the code proceeds to removal with dangerouslyRemoveEncounterEntriesWithBlacklistedAppointmentType. That function removes:
- Encounters whose appointmentType is in the blacklist
- Encounters that do NOT have the appointment type extension at all
With an empty blacklist, the latter behavior will remove all encounters missing the extension (and cascade-remove their referencing resources). Given rollout timing, this could aggressively prune bundles where the extension hasn’t propagated yet.
If the intended behavior is “presence enables tracking but does not remove anything when the array is empty,” adjust the filter to only remove when an extension is present and matches the blacklist.
Apply this diff inside dangerouslyRemoveEncounterEntriesWithBlacklistedAppointmentType to avoid removing encounters solely due to missing extension:
- .filter((encounter: Encounter) => {
- const appointmentTypeExtension = getEncounterAppointmentTypeIdExtension(encounter);
- if (!appointmentTypeExtension || !appointmentTypeExtension.valueString) return true;
- return blacklistedAppointmentTypes.includes(appointmentTypeExtension.valueString);
- })
+ .filter((encounter: Encounter) => {
+ const appointmentTypeExtension = getEncounterAppointmentTypeIdExtension(encounter);
+ // Only remove when the extension exists and matches the blacklist
+ if (!appointmentTypeExtension || !appointmentTypeExtension.valueString) return false;
+ return blacklistedAppointmentTypes.includes(appointmentTypeExtension.valueString);
+ })If you do want the “remove encounters missing the extension” behavior, consider gating it behind a separate mapping flag (e.g., dropEncountersWithoutAppointmentType: boolean).
🏁 Script executed:
#!/bin/bash
# Locate the implementation of dangerouslyRemoveEncounterEntriesWithBlacklistedAppointmentType
rg -n "dangerouslyRemoveEncounterEntriesWithBlacklistedAppointmentType" -C5Length of output: 2839
🏁 Script executed:
#!/bin/bash
# Show filter logic in dangerouslyRemoveEncounterEntriesWithBlacklistedAppointmentType
echo "=== Filter logic ==="
rg -nP '\.filter\(' -C3 packages/api/src/external/ehr/shared/command/bundle/contribute-resource-diff-bundle.ts
# Locate the definition of the secondary mappings schema to see defaults/optionality
echo ""
echo "=== Athena Secondary Mappings Schema ==="
rg -n "athenaSecondaryMappingsSchema" -C5 packages/api/srcLength of output: 7320
🏁 Script executed:
#!/bin/bash
# Locate the Athena secondary mappings schema definition
rg -n "athenaSecondaryMappingsSchema" -C5 .
# Search for any attachAppointmentType flag in the mapping schema or usages
rg -n "attachAppointmentType" -C5 .Length of output: 25597
Prevent blanket removal when the blacklist is empty
The current logic will remove every encounter lacking the appointment-type extension as soon as contributionEncounterAppointmentTypesBlacklist is set—even if it’s an empty array. This can inadvertently prune all encounters when the mapping is present but no IDs are blacklisted.
• In packages/api/src/external/ehr/shared/command/bundle/contribute-resource-diff-bundle.ts (around line 81), only call the removal step when there are actual blacklist entries:
Change
if (secondaryMappings.contributionEncounterAppointmentTypesBlacklist) {
To
if (secondaryMappings.contributionEncounterAppointmentTypesBlacklist?.length > 0) {
• Or, inside dangerouslyRemoveEncounterEntriesWithBlacklistedAppointmentType (around lines 159–162), adjust the filter so it only removes encounters whose extension exists and matches the blacklist:
.filter((encounter: Encounter) => {
- const appointmentTypeExtension = getEncounterAppointmentTypeIdExtension(encounter);
- if (!appointmentTypeExtension || !appointmentTypeExtension.valueString) return true;
- return blacklistedAppointmentTypes.includes(appointmentTypeExtension.valueString);
+ const appointmentTypeExtension = getEncounterAppointmentTypeIdExtension(encounter);
+ // only drop when the extension is present and in the blacklist
+ if (!appointmentTypeExtension?.valueString) return false;
+ return blacklistedAppointmentTypes.includes(appointmentTypeExtension.valueString);
})• If you still need to prune encounters missing the extension, introduce a separate flag (e.g. dropEncountersWithoutAppointmentType) instead of tying that behavior to the blacklist’s presence.
Committable suggestion skipped: line range outside the PR's diff.
🤖 Prompt for AI Agents
In
packages/api/src/external/ehr/shared/command/bundle/contribute-resource-diff-bundle.ts
around lines 81–93, the current if-check triggers blanket removal whenever
contributionEncounterAppointmentTypesBlacklist is present (even when it's an
empty array); update the call site to only run
dangerouslyRemoveEncounterEntriesWithBlacklistedAppointmentType when the
blacklist actually contains entries (e.g. check .length > 0), or alternatively
modify dangerouslyRemoveEncounterEntriesWithBlacklistedAppointmentType (around
its implementation lines ~159–162) so the filter only removes encounters whose
appointment-type extension exists and matches a blacklisted id (and do not
remove encounters that lack the extension unless an explicit flag like
dropEncountersWithoutAppointmentType is provided); implement one of these fixes
and ensure tests cover empty-array behavior.
| let encounter: Encounter | undefined; | ||
| if (attachAppointmentType) { | ||
| encounter = await this.getEncounter({ | ||
| cxId, | ||
| patientId: athenaPatientId, | ||
| encounterId, | ||
| }); | ||
| await createOrReplaceDocument({ | ||
| ehr: EhrSources.athena, | ||
| const appointment = await this.getAppointment({ | ||
| cxId, | ||
| metriportPatientId, | ||
| ehrPatientId: athenaPatientId, | ||
| documentType: DocumentType.HTML, | ||
| payload: encounterSummary, | ||
| resourceType: "Encounter", | ||
| resourceId: encounterId, | ||
| patientId: athenaPatientId, | ||
| appointmentId: encounter.appointmentid, | ||
| }); | ||
| entry.resource.extension = [ | ||
| ...(entry.resource.extension ?? []), | ||
| { | ||
| url: encounterAppointmentExtensionUrl, | ||
| valueString: appointment.appointmenttypeid, | ||
| }, | ||
| ]; | ||
| } | ||
| if (fetchEncounterSummary) { |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Make appointment-type extension idempotent and guard missing IDs.
Currently we always append a new extension, which can duplicate entries across repeated fetches or cache hits. Also, we don’t guard against missing appointmentid/appointmenttypeid. Use the helper to update-in-place if present, or append only once.
Apply this diff:
- let encounter: Encounter | undefined;
+ let encounter: Encounter | undefined;
if (attachAppointmentType) {
encounter = await this.getEncounter({
cxId,
patientId: athenaPatientId,
encounterId,
});
- const appointment = await this.getAppointment({
+ if (!encounter.appointmentid) return;
+ const appointment = await this.getAppointment({
cxId,
- patientId: athenaPatientId,
- appointmentId: encounter.appointmentid,
+ patientId: athenaPatientId,
+ appointmentId: encounter.appointmentid,
});
- entry.resource.extension = [
- ...(entry.resource.extension ?? []),
- {
- url: encounterAppointmentExtensionUrl,
- valueString: appointment.appointmenttypeid,
- },
- ];
+ const existingExt = getEncounterAppointmentTypeIdExtension(
+ entry.resource as EncounterFhir
+ );
+ const typeId = appointment.appointmenttypeid;
+ if (!typeId) return;
+ if (existingExt) {
+ existingExt.valueString = String(typeId);
+ } else {
+ entry.resource.extension = [
+ ...(entry.resource.extension ?? []),
+ {
+ url: encounterAppointmentExtensionUrl,
+ valueString: String(typeId),
+ },
+ ];
+ }
}🤖 Prompt for AI Agents
In packages/core/src/external/ehr/athenahealth/index.ts around lines 1981 to
2001, the code always appends an appointment-type extension which can create
duplicates and does not guard for missing appointmentid or appointmenttypeid;
update the logic to first verify encounter and appointment exist and that
encounter.appointmentid and appointment.appointmenttypeid are present, then use
the existing helper to upsert (update-in-place) the extension if one with url
encounterAppointmentExtensionUrl already exists, otherwise append it once;
ensure you do not append duplicates on repeated calls and handle missing IDs by
skipping the extension addition when IDs are absent.
…backmerge Signed-off-by: Thomas Yopes <thomasyopes@Mac.attlocal.net>
Eng 000 backmerge
Issues:
Description
Testing
Check each PR.
Release Plan
masterSummary by CodeRabbit
New Features
Documentation
Chores