gdc-common-utils-ts 1.4.12 → 1.4.14

package/README.md

@@ -4,6 +4,13 @@ Shared TypeScript utilities for GDC client and connector code. This package prov
 
 It is intentionally not a full backend orchestration layer.
 
+## Non-Negotiable Conventions
+
+- FHIR SearchParameter names must use canonical FHIR naming (lowercase, with `-` when defined by FHIR).
+- Never use invented camelCase parameter names for FHIR claims/search keys (example: `Communication.part-of` is valid, `Communication.partOf` is not).
+- Only define custom names when no canonical FHIR SearchParameter exists.
+- `resource.meta.claims` is the canonical claims container and must be preserved across conversions/transports.
+
 ## Install
 
 ```bash
@@ -48,6 +55,7 @@ The `utils` export exposes reusable helpers for DID and message handling, such a
 - `utils/content`
 - `utils/normalize`
 - `utils/fhir-cid` for recursive FHIR canonicalization + CID generation + `meta.versionId` assignment
+- `utils/fhir-validator` for adapter-based FHIR validation (`validateFhirResource`, pluggable formal validator)
 - conversion, formatting, and multibase helpers
 
 These helpers support DIDComm-style message construction and related transport/data-shaping workflows.

package/dist/i18n/clinical-sections.i18n.d.ts

@@ -0,0 +1,6 @@
+export type ClinicalSectionI18nMap = Readonly<Record<`org.loinc.${string}`, string>>;
+export declare const clinicalSectionsBaseI18nEn: Readonly<Record<`org.loinc.${string}`, string>>;
+export declare const clinicalDocTypesI18nEn: Readonly<Record<`org.loinc.${string}`, string>>;
+export declare const clinicalSectionAdditionalI18nEn: Readonly<Record<`org.loinc.${string}`, string>>;
+export declare const clinicalSectionI18nEn: ClinicalSectionI18nMap;
+export declare const clinicalSectionsI18nEn: Readonly<Record<`org.loinc.${string}`, string>>;

package/dist/i18n/clinical-sections.i18n.js

@@ -0,0 +1,15 @@
+import { clinicalDocTypes, clinicalSectionAdditional, clinicalSectionsBase, } from '../models/clinical-sections.en.js';
+import { loincI18nKey } from '../models/clinical-sections.js';
+function toClinicalI18nMap(source) {
+    const entries = Object.entries(source).map(([code, label]) => [loincI18nKey(code), label]);
+    return Object.freeze(Object.fromEntries(entries));
+}
+export const clinicalSectionsBaseI18nEn = toClinicalI18nMap(clinicalSectionsBase);
+export const clinicalDocTypesI18nEn = toClinicalI18nMap(clinicalDocTypes);
+export const clinicalSectionAdditionalI18nEn = toClinicalI18nMap(clinicalSectionAdditional);
+export const clinicalSectionI18nEn = Object.freeze({
+    ...clinicalSectionsBaseI18nEn,
+    ...clinicalDocTypesI18nEn,
+    ...clinicalSectionAdditionalI18nEn,
+});
+export const clinicalSectionsI18nEn = clinicalSectionI18nEn;

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from './AesManager';
 export * from './CryptographyService';
 export * from './hmac';
+export * from './i18n/clinical-sections.i18n';
 export * from './storage';
 export * from './utils';

package/dist/index.js

@@ -1,5 +1,6 @@
 export * from './AesManager.js';
 export * from './CryptographyService.js';
 export * from './hmac.js';
+export * from './i18n/clinical-sections.i18n.js';
 export * from './storage/index.js';
 export * from './utils/index.js';

package/dist/models/clinical-sections.d.ts

@@ -30,7 +30,7 @@ export type ClinicalSectionDescriptor = {
 };
 export declare function loincI18nKey(code: string): string;
 export type SupportedClinicalSectionCode = keyof typeof clinicalSectionTitleEn;
-export declare const supportedClinicalSectionCodes: readonly ("10154-3" | "10157-6" | "10160-0" | "10164-2" | "10183-2" | "10184-0" | "10187-3" | "10210-3" | "10216-0" | "10218-6" | "10222-8" | "10223-6" | "11329-0" | "11348-0" | "11369-6" | "11493-4" | "11535-2" | "11537-8" | "18776-5" | "18841-7" | "29299-5" | "29545-1" | "29549-3" | "29554-3" | "29762-2" | "30954-2" | "42344-2" | "42346-7" | "42348-3" | "42349-1" | "46240-8" | "46241-6" | "46264-8" | "47420-5" | "47519-4" | "48765-2" | "48768-6" | "51848-0" | "55109-3" | "55122-6" | "57852-6" | "59768-2" | "59769-0" | "59770-8" | "59771-6" | "59772-4" | "59773-2" | "59775-7" | "59776-5" | "61149-1" | "61150-9" | "69730-0" | "8648-8" | "8653-8" | "8716-3" | "60591-5" | "11450-4" | "61144-2" | "82810-3" | "87520-3" | "10190-7" | "18726-0" | "11503-0" | "56796-6")[];
+export declare const supportedClinicalSectionCodes: readonly ("61144-2" | "82810-3" | "87520-3" | "10190-7" | "18726-0" | "10154-3" | "10164-2" | "10183-2" | "10184-0" | "10187-3" | "10210-3" | "10216-0" | "10218-6" | "10222-8" | "10223-6" | "11329-0" | "48768-6" | "51848-0" | "57852-6" | "18776-5" | "18841-7" | "60591-5" | "11493-4" | "11535-2" | "11537-8" | "29299-5" | "29549-3" | "29554-3" | "42344-2" | "42346-7" | "42349-1" | "46241-6" | "55109-3" | "55122-6" | "59768-2" | "59769-0" | "59770-8" | "59771-6" | "59772-4" | "59773-2" | "59775-7" | "59776-5" | "61149-1" | "61150-9" | "69730-0" | "8648-8" | "8653-8" | "11503-0" | "56796-6" | "10157-6" | "10160-0" | "11348-0" | "11369-6" | "11450-4" | "29762-2" | "30954-2" | "42348-3" | "46240-8" | "46264-8" | "47420-5" | "47519-4" | "48765-2" | "56446-8" | "8716-3")[];
 export declare const clinicalSectionRegistry: Readonly<Record<string, ClinicalSectionDescriptor>>;
 export { clinicalSectionTitleEn };
 export declare function getClinicalSectionByCode(code: string): ClinicalSectionDescriptor | undefined;

package/dist/models/clinical-sections.en.d.ts

@@ -5,71 +5,146 @@
  * - This file is intentionally separate from the section registry so apps can:
  *   - use these labels as a default (e.g., server-side rendering), and/or
  *   - override them via i18n resources keyed by `org.loinc.<CODE>`.
- * - Sources: HL7 FHIR doc-section-codes + project-specific additions.
+ * - Source layers:
+ *   - Base / IPS-aligned sections: HL7 FHIR `doc-section-codes` for `Composition.section`.
+ *   - Additional labels: project-specific additions and Excel-driven taxonomy entries.
+ * - Keep section labels and document-type labels separate in UI permission filters to avoid duplicates.
+ * - Broader data-space artifact families such as `RelatedPerson`, `Appointment`, `Communication`,
+ *   or other sector-independent profiles should live in their own registries.
  */
-export declare const clinicalSectionTitleEn: {
+export declare const clinicalSectionsBase: {
+    readonly '10157-6': "History of family member diseases";
+    readonly '10160-0': "History of Medication use";
+    readonly '11348-0': "History of Past illness";
+    readonly '11369-6': "History of Immunization";
+    readonly '11450-4': "Problem list";
+    readonly '29762-2': "Social history";
+    readonly '30954-2': "Relevant diagnostic tests/laboratory data";
+    readonly '42348-3': "Advance directives";
+    readonly '46240-8': "History of Hospitalizations+Outpatient visits";
+    readonly '46264-8': "History of medical device use";
+    readonly '47420-5': "Functional status";
+    readonly '47519-4': "History of Procedures";
+    readonly '48765-2': "Allergies and adverse reactions";
+    readonly '56446-8': "Appointment summary";
+    readonly '8716-3': "Vital signs";
+};
+export declare const clinicalDocTypes: {
     readonly '10154-3': "Chief complaint Narrative - Reported";
-    readonly '10157-6': "History of family member diseases Narrative";
-    readonly '10160-0': "History of Medication use Narrative";
-    readonly '10164-2': "History of Present illness Narrative";
-    readonly '10183-2': "Hospital discharge medications Narrative";
-    readonly '10184-0': "Hospital discharge physical findings Narrative";
-    readonly '10187-3': "Review of systems Narrative - Reported";
-    readonly '10210-3': "Physical findings of General status Narrative";
+    readonly '10164-2': "History of Present illness";
+    readonly '10183-2': "Hospital discharge medications";
+    readonly '10184-0': "Hospital discharge physical findings";
+    readonly '10187-3': "Review of systems";
+    readonly '10210-3': "Physical findings of General status";
     readonly '10216-0': "Surgical operation note fluids Narrative";
-    readonly '10218-6': "Surgical operation note postoperative diagnosis Narrative";
-    readonly '10222-8': "Surgical operation note surgical complications [Interpretation] Narrative";
-    readonly '10223-6': "Surgical operation note surgical procedure Narrative";
-    readonly '11329-0': "History general Narrative - Reported";
-    readonly '11348-0': "History of Past illness Narrative";
-    readonly '11369-6': "History of Immunization Narrative";
-    readonly '11493-4': "Hospital discharge studies summary Narrative";
-    readonly '11535-2': "Hospital discharge Dx Narrative";
-    readonly '11537-8': "Surgical drains Narrative";
+    readonly '10218-6': "Surgical operation note postoperative diagnosis";
+    readonly '10222-8': "Surgical operation note surgical complications [Interpretation]";
+    readonly '10223-6': "Surgical operation note surgical procedure";
+    readonly '11329-0': "History general";
+    readonly '48768-6': "Payment sources Document";
+    readonly '51848-0': "Evaluation note";
+    readonly '57852-6': "Problem list Narrative - Reported";
     readonly '18776-5': "Plan of care note";
     readonly '18841-7': "Hospital consultations Document";
+    readonly '60591-5': "Patient summary";
+    readonly '11493-4': "Hospital discharge studies summary";
+    readonly '11535-2': "Hospital discharge Dx";
+    readonly '11537-8': "Surgical drains";
     readonly '29299-5': "Reason for visit Narrative";
-    readonly '29545-1': "Physical findings Narrative";
-    readonly '29549-3': "Medication administered Narrative";
-    readonly '29554-3': "Procedure Narrative";
-    readonly '29762-2': "Social history Narrative";
-    readonly '30954-2': "Relevant diagnostic tests/laboratory data Narrative";
-    readonly '42344-2': "Discharge diet (narrative)";
-    readonly '42346-7': "Medications on admission (narrative)";
-    readonly '42348-3': "Advance directives";
-    readonly '42349-1': "Reason for referral (narrative)";
-    readonly '46240-8': "History of Hospitalizations+Outpatient visits Narrative";
-    readonly '46241-6': "Hospital admission diagnosis Narrative - Reported";
-    readonly '46264-8': "History of medical device use";
-    readonly '47420-5': "Functional status assessment note";
-    readonly '47519-4': "History of Procedures Document";
-    readonly '48765-2': "Allergies and adverse reactions Document";
-    readonly '48768-6': "Payment sources Document";
-    readonly '51848-0': "Evaluation note";
+    readonly '29549-3': "Medication administered";
+    readonly '29554-3': "Procedure";
+    readonly '42344-2': "Discharge diet";
+    readonly '42346-7': "Medications on admission";
+    readonly '42349-1': "Reason for referral";
+    readonly '46241-6': "Hospital admission diagnosis";
     readonly '55109-3': "Complications Document";
-    readonly '55122-6': "Surgical operation note implants Narrative";
-    readonly '57852-6': "Problem list Narrative - Reported";
-    readonly '59768-2': "Procedure indications [Interpretation] Narrative";
-    readonly '59769-0': "Postprocedure diagnosis Narrative";
-    readonly '59770-8': "Procedure estimated blood loss Narrative";
-    readonly '59771-6': "Procedure implants Narrative";
-    readonly '59772-4': "Planned procedure Narrative";
-    readonly '59773-2': "Procedure specimens taken Narrative";
-    readonly '59775-7': "Procedure disposition Narrative";
-    readonly '59776-5': "Procedure findings Narrative";
-    readonly '61149-1': "Objective Narrative";
-    readonly '61150-9': "Subjective Narrative";
+    readonly '55122-6': "Surgical operation note implants";
+    readonly '59768-2': "Procedure indications [Interpretation]";
+    readonly '59769-0': "Postprocedure diagnosis";
+    readonly '59770-8': "Procedure estimated blood loss";
+    readonly '59771-6': "Procedure implants";
+    readonly '59772-4': "Planned procedure";
+    readonly '59773-2': "Procedure specimens taken";
+    readonly '59775-7': "Procedure disposition";
+    readonly '59776-5': "Procedure findings";
+    readonly '61149-1': "Objective";
+    readonly '61150-9': "Subjective";
     readonly '69730-0': "Instructions";
-    readonly '8648-8': "Hospital course Narrative";
+    readonly '8648-8': "Hospital course";
     readonly '8653-8': "Hospital Discharge instructions";
-    readonly '8716-3': "Vital signs";
-    readonly '60591-5': "Patient summary";
-    readonly '11450-4': "Problem list";
+    readonly '11503-0': "Medical records (generic)";
+    readonly '56796-6': "Healthcare (general)";
+};
+export declare const clinicalSectionAdditional: {
+    readonly '61144-2': "Diet";
+    readonly '82810-3': "History of pregnancy";
+    readonly '87520-3': "Health insurance coverage";
+    readonly '10190-7': "Mental status";
+    readonly '18726-0': "Radiology studies";
+};
+export declare const clinicalSectionTitleEn: {
     readonly '61144-2': "Diet";
     readonly '82810-3': "History of pregnancy";
     readonly '87520-3': "Health insurance coverage";
     readonly '10190-7': "Mental status";
     readonly '18726-0': "Radiology studies";
+    readonly '10154-3': "Chief complaint Narrative - Reported";
+    readonly '10164-2': "History of Present illness";
+    readonly '10183-2': "Hospital discharge medications";
+    readonly '10184-0': "Hospital discharge physical findings";
+    readonly '10187-3': "Review of systems";
+    readonly '10210-3': "Physical findings of General status";
+    readonly '10216-0': "Surgical operation note fluids Narrative";
+    readonly '10218-6': "Surgical operation note postoperative diagnosis";
+    readonly '10222-8': "Surgical operation note surgical complications [Interpretation]";
+    readonly '10223-6': "Surgical operation note surgical procedure";
+    readonly '11329-0': "History general";
+    readonly '48768-6': "Payment sources Document";
+    readonly '51848-0': "Evaluation note";
+    readonly '57852-6': "Problem list Narrative - Reported";
+    readonly '18776-5': "Plan of care note";
+    readonly '18841-7': "Hospital consultations Document";
+    readonly '60591-5': "Patient summary";
+    readonly '11493-4': "Hospital discharge studies summary";
+    readonly '11535-2': "Hospital discharge Dx";
+    readonly '11537-8': "Surgical drains";
+    readonly '29299-5': "Reason for visit Narrative";
+    readonly '29549-3': "Medication administered";
+    readonly '29554-3': "Procedure";
+    readonly '42344-2': "Discharge diet";
+    readonly '42346-7': "Medications on admission";
+    readonly '42349-1': "Reason for referral";
+    readonly '46241-6': "Hospital admission diagnosis";
+    readonly '55109-3': "Complications Document";
+    readonly '55122-6': "Surgical operation note implants";
+    readonly '59768-2': "Procedure indications [Interpretation]";
+    readonly '59769-0': "Postprocedure diagnosis";
+    readonly '59770-8': "Procedure estimated blood loss";
+    readonly '59771-6': "Procedure implants";
+    readonly '59772-4': "Planned procedure";
+    readonly '59773-2': "Procedure specimens taken";
+    readonly '59775-7': "Procedure disposition";
+    readonly '59776-5': "Procedure findings";
+    readonly '61149-1': "Objective";
+    readonly '61150-9': "Subjective";
+    readonly '69730-0': "Instructions";
+    readonly '8648-8': "Hospital course";
+    readonly '8653-8': "Hospital Discharge instructions";
     readonly '11503-0': "Medical records (generic)";
     readonly '56796-6': "Healthcare (general)";
+    readonly '10157-6': "History of family member diseases";
+    readonly '10160-0': "History of Medication use";
+    readonly '11348-0': "History of Past illness";
+    readonly '11369-6': "History of Immunization";
+    readonly '11450-4': "Problem list";
+    readonly '29762-2': "Social history";
+    readonly '30954-2': "Relevant diagnostic tests/laboratory data";
+    readonly '42348-3': "Advance directives";
+    readonly '46240-8': "History of Hospitalizations+Outpatient visits";
+    readonly '46264-8': "History of medical device use";
+    readonly '47420-5': "Functional status";
+    readonly '47519-4': "History of Procedures";
+    readonly '48765-2': "Allergies and adverse reactions";
+    readonly '56446-8': "Appointment summary";
+    readonly '8716-3': "Vital signs";
 };

package/dist/models/clinical-sections.en.js

@@ -5,77 +5,100 @@
  * - This file is intentionally separate from the section registry so apps can:
  *   - use these labels as a default (e.g., server-side rendering), and/or
  *   - override them via i18n resources keyed by `org.loinc.<CODE>`.
- * - Sources: HL7 FHIR doc-section-codes + project-specific additions.
+ * - Source layers:
+ *   - Base / IPS-aligned sections: HL7 FHIR `doc-section-codes` for `Composition.section`.
+ *   - Additional labels: project-specific additions and Excel-driven taxonomy entries.
+ * - Keep section labels and document-type labels separate in UI permission filters to avoid duplicates.
+ * - Broader data-space artifact families such as `RelatedPerson`, `Appointment`, `Communication`,
+ *   or other sector-independent profiles should live in their own registries.
  */
-export const clinicalSectionTitleEn = {
+export const clinicalSectionsBase = {
+    // ---------------------------------------------------------------------------
+    // Base / IPS-aligned section labels
+    // Source: https://hl7.org/fhir/R4/valueset-doc-section-codes.html
+    // These labels are normalized for section use: document suffixes such as
+    // Narrative / Document / note are removed when the concept is used as a section.
+    // ---------------------------------------------------------------------------
+    '10157-6': 'History of family member diseases',
+    '10160-0': 'History of Medication use',
+    '11348-0': 'History of Past illness',
+    '11369-6': 'History of Immunization',
+    '11450-4': 'Problem list',
+    '29762-2': 'Social history',
+    '30954-2': 'Relevant diagnostic tests/laboratory data',
+    '42348-3': 'Advance directives',
+    '46240-8': 'History of Hospitalizations+Outpatient visits',
+    '46264-8': 'History of medical device use',
+    '47420-5': 'Functional status',
+    '47519-4': 'History of Procedures',
+    '48765-2': 'Allergies and adverse reactions',
+    '56446-8': 'Appointment summary',
+    '8716-3': 'Vital signs',
+};
+export const clinicalDocTypes = {
     // ---------------------------------------------------------------------------
-    // HL7 FHIR doc-section-codes (LOINC) — subset used by the platform/docs
+    // Document-oriented labels used as buckets or wrappers in the UI.
+    // Source: FHIR/IPS document taxonomy and project-specific document buckets.
     // ---------------------------------------------------------------------------
     '10154-3': 'Chief complaint Narrative - Reported',
-    '10157-6': 'History of family member diseases Narrative',
-    '10160-0': 'History of Medication use Narrative',
-    '10164-2': 'History of Present illness Narrative',
-    '10183-2': 'Hospital discharge medications Narrative',
-    '10184-0': 'Hospital discharge physical findings Narrative',
-    '10187-3': 'Review of systems Narrative - Reported',
-    '10210-3': 'Physical findings of General status Narrative',
+    '10164-2': 'History of Present illness',
+    '10183-2': 'Hospital discharge medications',
+    '10184-0': 'Hospital discharge physical findings',
+    '10187-3': 'Review of systems',
+    '10210-3': 'Physical findings of General status',
     '10216-0': 'Surgical operation note fluids Narrative',
-    '10218-6': 'Surgical operation note postoperative diagnosis Narrative',
-    '10222-8': 'Surgical operation note surgical complications [Interpretation] Narrative',
-    '10223-6': 'Surgical operation note surgical procedure Narrative',
-    '11329-0': 'History general Narrative - Reported',
-    '11348-0': 'History of Past illness Narrative',
-    '11369-6': 'History of Immunization Narrative',
-    '11493-4': 'Hospital discharge studies summary Narrative',
-    '11535-2': 'Hospital discharge Dx Narrative',
-    '11537-8': 'Surgical drains Narrative',
+    '10218-6': 'Surgical operation note postoperative diagnosis',
+    '10222-8': 'Surgical operation note surgical complications [Interpretation]',
+    '10223-6': 'Surgical operation note surgical procedure',
+    '11329-0': 'History general',
+    '48768-6': 'Payment sources Document',
+    '51848-0': 'Evaluation note',
+    '57852-6': 'Problem list Narrative - Reported',
     '18776-5': 'Plan of care note',
     '18841-7': 'Hospital consultations Document',
+    '60591-5': 'Patient summary',
+    '11493-4': 'Hospital discharge studies summary',
+    '11535-2': 'Hospital discharge Dx',
+    '11537-8': 'Surgical drains',
     '29299-5': 'Reason for visit Narrative',
-    '29545-1': 'Physical findings Narrative',
-    '29549-3': 'Medication administered Narrative',
-    '29554-3': 'Procedure Narrative',
-    '29762-2': 'Social history Narrative',
-    '30954-2': 'Relevant diagnostic tests/laboratory data Narrative',
-    '42344-2': 'Discharge diet (narrative)',
-    '42346-7': 'Medications on admission (narrative)',
-    '42348-3': 'Advance directives',
-    '42349-1': 'Reason for referral (narrative)',
-    '46240-8': 'History of Hospitalizations+Outpatient visits Narrative',
-    '46241-6': 'Hospital admission diagnosis Narrative - Reported',
-    '46264-8': 'History of medical device use',
-    '47420-5': 'Functional status assessment note',
-    '47519-4': 'History of Procedures Document',
-    '48765-2': 'Allergies and adverse reactions Document',
-    '48768-6': 'Payment sources Document',
-    '51848-0': 'Evaluation note',
+    '29549-3': 'Medication administered',
+    '29554-3': 'Procedure',
+    '42344-2': 'Discharge diet',
+    '42346-7': 'Medications on admission',
+    '42349-1': 'Reason for referral',
+    '46241-6': 'Hospital admission diagnosis',
     '55109-3': 'Complications Document',
-    '55122-6': 'Surgical operation note implants Narrative',
-    '57852-6': 'Problem list Narrative - Reported',
-    '59768-2': 'Procedure indications [Interpretation] Narrative',
-    '59769-0': 'Postprocedure diagnosis Narrative',
-    '59770-8': 'Procedure estimated blood loss Narrative',
-    '59771-6': 'Procedure implants Narrative',
-    '59772-4': 'Planned procedure Narrative',
-    '59773-2': 'Procedure specimens taken Narrative',
-    '59775-7': 'Procedure disposition Narrative',
-    '59776-5': 'Procedure findings Narrative',
-    '61149-1': 'Objective Narrative',
-    '61150-9': 'Subjective Narrative',
+    '55122-6': 'Surgical operation note implants',
+    '59768-2': 'Procedure indications [Interpretation]',
+    '59769-0': 'Postprocedure diagnosis',
+    '59770-8': 'Procedure estimated blood loss',
+    '59771-6': 'Procedure implants',
+    '59772-4': 'Planned procedure',
+    '59773-2': 'Procedure specimens taken',
+    '59775-7': 'Procedure disposition',
+    '59776-5': 'Procedure findings',
+    '61149-1': 'Objective',
+    '61150-9': 'Subjective',
     '69730-0': 'Instructions',
-    '8648-8': 'Hospital course Narrative',
+    '8648-8': 'Hospital course',
     '8653-8': 'Hospital Discharge instructions',
-    '8716-3': 'Vital signs',
+    '11503-0': 'Medical records (generic)',
+    '56796-6': 'Healthcare (general)',
+};
+export const clinicalSectionAdditional = {
     // ---------------------------------------------------------------------------
-    // Project additions (not part of doc-section-codes, but used by clients)
+    // Additional Excel / project-driven sections
+    // Source: local workbook derived from the LOINC ontology tables and product needs.
+    // Keep these out of the base permission list to avoid duplicate section semantics.
     // ---------------------------------------------------------------------------
-    '60591-5': 'Patient summary',
-    '11450-4': 'Problem list',
     '61144-2': 'Diet',
     '82810-3': 'History of pregnancy',
     '87520-3': 'Health insurance coverage',
     '10190-7': 'Mental status',
     '18726-0': 'Radiology studies',
-    '11503-0': 'Medical records (generic)',
-    '56796-6': 'Healthcare (general)',
+};
+export const clinicalSectionTitleEn = {
+    ...clinicalSectionsBase,
+    ...clinicalDocTypes,
+    ...clinicalSectionAdditional,
 };

package/dist/models/clinical-workbook-summary.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Workbook summary extracted from rows marked Include = Y/y.
+ *
+ * Source workbook: Sections-from-LOINC_Document_Ontology_Tables.xlsx
+ * This summary is separate from the full LP taxonomy and from the clinical section registry.
+ */
+export declare const clinicalWorkbookSummaryLabelI18nEn: Readonly<{
+    readonly 'org.loinc.LP447691-9': "Administrative information";
+    readonly 'org.loinc.LP173390-8': "Certificate";
+    readonly 'org.loinc.LP173394-0': "Consent";
+    readonly 'org.loinc.LP173404-7': "Health insurance card";
+    readonly 'org.loinc.LP181119-1': "Action plan";
+    readonly 'org.loinc.LP181204-1': "Prescription";
+    readonly 'org.loinc.LP173421-1': "Report";
+    readonly 'org.loinc.LP437010-4': "Goals, preferences, and priorities for care experience";
+    readonly 'org.loinc.LP310260-7': "Care management";
+    readonly 'org.loinc.LP173209-0': "Plan of care";
+    readonly 'org.loinc.LP200117-2': "Summary of encounters";
+    readonly 'org.loinc.LP203673-1': "Notification";
+    readonly 'org.loinc.LP172918-7': "Anesthesiology";
+    readonly 'org.loinc.LP172919-5': "Audiology";
+    readonly 'org.loinc.LP172923-7': "Chiropractic medicine";
+    readonly 'org.loinc.LP172934-4': "Dentistry";
+    readonly 'org.loinc.LP172935-1': "Dermatology";
+    readonly 'org.loinc.LP172957-5': "Medical toxicology";
+    readonly 'org.loinc.LP183499-5': "Trauma";
+    readonly 'org.loinc.LP172943-5': "Family medicine";
+    readonly 'org.loinc.LP172894-0': "Forensic medicine";
+    readonly 'org.loinc.LP172946-8': "General medicine";
+    readonly 'org.loinc.LP172911-2': "Acupuncture";
+    readonly 'org.loinc.LP172941-9': "Endocrinology";
+    readonly 'org.loinc.LP172945-0': "Gastroenterology";
+    readonly 'org.loinc.LP172947-6': "Geriatric medicine";
+    readonly 'org.loinc.LP175685-9': "Hematology";
+    readonly 'org.loinc.LP172951-8': "Infectious disease";
+    readonly 'org.loinc.LP175686-7': "Medical Oncology";
+    readonly 'org.loinc.LP172962-5': "Nephrology";
+    readonly 'org.loinc.LP173015-1': "Pulmonary disease";
+    readonly 'org.loinc.LP173023-5': "Rheumatology";
+    readonly 'org.loinc.LP248728-0': "Sleep medicine";
+    readonly 'org.loinc.LP417852-3': "Solid organ transplant";
+    readonly 'org.loinc.LP173027-6': "Sports medicine";
+    readonly 'org.loinc.LP172956-7': "Medical genetics";
+    readonly 'org.loinc.LP173011-0': "Psychiatry";
+    readonly 'org.loinc.LP173012-8': "Psychology";
+    readonly 'org.loinc.LP345049-3': "Cleft and Craniofacial";
+    readonly 'org.loinc.LP172964-1': "Neurology";
+    readonly 'org.loinc.LP172968-2': "Nuclear medicine";
+    readonly 'org.loinc.LP172899-9': "Nutrition and dietetics";
+    readonly 'org.loinc.LP172971-6': "Obstetrics and gynecology";
+    readonly 'org.loinc.LP172973-2': "Occupational therapy";
+    readonly 'org.loinc.LP172901-3': "Oncology";
+    readonly 'org.loinc.LP172974-0': "Ophthalmology";
+    readonly 'org.loinc.LP434870-4': "Orthopaedic";
+    readonly 'org.loinc.LP172979-9': "Orthotics prosthetics";
+    readonly 'org.loinc.LP434767-2': "Osteopathic medicine";
+    readonly 'org.loinc.LP172980-7': "Otolaryngology";
+    readonly 'org.loinc.LP172982-3': "Palliative care";
+    readonly 'org.loinc.LP172984-9': "Pathology";
+    readonly 'org.loinc.LP173002-9': "Pediatrics";
+    readonly 'org.loinc.LP173004-5': "Physical medicine and rehabilitation";
+    readonly 'org.loinc.LP173008-6': "Podiatry";
+    readonly 'org.loinc.LP173018-5': "Radiology";
+    readonly 'org.loinc.LP173036-7': "Urology";
+    readonly 'org.loinc.LP248732-2': "Womens health";
+}>;
+export declare const clinicalWorkbookSummaryLabelsEn: Readonly<{
+    readonly 'org.loinc.LP447691-9': "Administrative information";
+    readonly 'org.loinc.LP173390-8': "Certificate";
+    readonly 'org.loinc.LP173394-0': "Consent";
+    readonly 'org.loinc.LP173404-7': "Health insurance card";
+    readonly 'org.loinc.LP181119-1': "Action plan";
+    readonly 'org.loinc.LP181204-1': "Prescription";
+    readonly 'org.loinc.LP173421-1': "Report";
+    readonly 'org.loinc.LP437010-4': "Goals, preferences, and priorities for care experience";
+    readonly 'org.loinc.LP310260-7': "Care management";
+    readonly 'org.loinc.LP173209-0': "Plan of care";
+    readonly 'org.loinc.LP200117-2': "Summary of encounters";
+    readonly 'org.loinc.LP203673-1': "Notification";
+    readonly 'org.loinc.LP172918-7': "Anesthesiology";
+    readonly 'org.loinc.LP172919-5': "Audiology";
+    readonly 'org.loinc.LP172923-7': "Chiropractic medicine";
+    readonly 'org.loinc.LP172934-4': "Dentistry";
+    readonly 'org.loinc.LP172935-1': "Dermatology";
+    readonly 'org.loinc.LP172957-5': "Medical toxicology";
+    readonly 'org.loinc.LP183499-5': "Trauma";
+    readonly 'org.loinc.LP172943-5': "Family medicine";
+    readonly 'org.loinc.LP172894-0': "Forensic medicine";
+    readonly 'org.loinc.LP172946-8': "General medicine";
+    readonly 'org.loinc.LP172911-2': "Acupuncture";
+    readonly 'org.loinc.LP172941-9': "Endocrinology";
+    readonly 'org.loinc.LP172945-0': "Gastroenterology";
+    readonly 'org.loinc.LP172947-6': "Geriatric medicine";
+    readonly 'org.loinc.LP175685-9': "Hematology";
+    readonly 'org.loinc.LP172951-8': "Infectious disease";
+    readonly 'org.loinc.LP175686-7': "Medical Oncology";
+    readonly 'org.loinc.LP172962-5': "Nephrology";
+    readonly 'org.loinc.LP173015-1': "Pulmonary disease";
+    readonly 'org.loinc.LP173023-5': "Rheumatology";
+    readonly 'org.loinc.LP248728-0': "Sleep medicine";
+    readonly 'org.loinc.LP417852-3': "Solid organ transplant";
+    readonly 'org.loinc.LP173027-6': "Sports medicine";
+    readonly 'org.loinc.LP172956-7': "Medical genetics";
+    readonly 'org.loinc.LP173011-0': "Psychiatry";
+    readonly 'org.loinc.LP173012-8': "Psychology";
+    readonly 'org.loinc.LP345049-3': "Cleft and Craniofacial";
+    readonly 'org.loinc.LP172964-1': "Neurology";
+    readonly 'org.loinc.LP172968-2': "Nuclear medicine";
+    readonly 'org.loinc.LP172899-9': "Nutrition and dietetics";
+    readonly 'org.loinc.LP172971-6': "Obstetrics and gynecology";
+    readonly 'org.loinc.LP172973-2': "Occupational therapy";
+    readonly 'org.loinc.LP172901-3': "Oncology";
+    readonly 'org.loinc.LP172974-0': "Ophthalmology";
+    readonly 'org.loinc.LP434870-4': "Orthopaedic";
+    readonly 'org.loinc.LP172979-9': "Orthotics prosthetics";
+    readonly 'org.loinc.LP434767-2': "Osteopathic medicine";
+    readonly 'org.loinc.LP172980-7': "Otolaryngology";
+    readonly 'org.loinc.LP172982-3': "Palliative care";
+    readonly 'org.loinc.LP172984-9': "Pathology";
+    readonly 'org.loinc.LP173002-9': "Pediatrics";
+    readonly 'org.loinc.LP173004-5': "Physical medicine and rehabilitation";
+    readonly 'org.loinc.LP173008-6': "Podiatry";
+    readonly 'org.loinc.LP173018-5': "Radiology";
+    readonly 'org.loinc.LP173036-7': "Urology";
+    readonly 'org.loinc.LP248732-2': "Womens health";
+}>;

package/dist/models/clinical-workbook-summary.js

@@ -0,0 +1,67 @@
+/**
+ * Workbook summary extracted from rows marked Include = Y/y.
+ *
+ * Source workbook: Sections-from-LOINC_Document_Ontology_Tables.xlsx
+ * This summary is separate from the full LP taxonomy and from the clinical section registry.
+ */
+export const clinicalWorkbookSummaryLabelI18nEn = Object.freeze({
+    'org.loinc.LP447691-9': "Administrative information",
+    'org.loinc.LP173390-8': "Certificate",
+    'org.loinc.LP173394-0': "Consent",
+    'org.loinc.LP173404-7': "Health insurance card",
+    'org.loinc.LP181119-1': "Action plan",
+    'org.loinc.LP181204-1': "Prescription",
+    'org.loinc.LP173421-1': "Report",
+    'org.loinc.LP437010-4': "Goals, preferences, and priorities for care experience",
+    'org.loinc.LP310260-7': "Care management",
+    'org.loinc.LP173209-0': "Plan of care",
+    'org.loinc.LP200117-2': "Summary of encounters",
+    'org.loinc.LP203673-1': "Notification",
+    'org.loinc.LP172918-7': "Anesthesiology",
+    'org.loinc.LP172919-5': "Audiology",
+    'org.loinc.LP172923-7': "Chiropractic medicine",
+    'org.loinc.LP172934-4': "Dentistry",
+    'org.loinc.LP172935-1': "Dermatology",
+    'org.loinc.LP172957-5': "Medical toxicology",
+    'org.loinc.LP183499-5': "Trauma",
+    'org.loinc.LP172943-5': "Family medicine",
+    'org.loinc.LP172894-0': "Forensic medicine",
+    'org.loinc.LP172946-8': "General medicine",
+    'org.loinc.LP172911-2': "Acupuncture",
+    'org.loinc.LP172941-9': "Endocrinology",
+    'org.loinc.LP172945-0': "Gastroenterology",
+    'org.loinc.LP172947-6': "Geriatric medicine",
+    'org.loinc.LP175685-9': "Hematology",
+    'org.loinc.LP172951-8': "Infectious disease",
+    'org.loinc.LP175686-7': "Medical Oncology",
+    'org.loinc.LP172962-5': "Nephrology",
+    'org.loinc.LP173015-1': "Pulmonary disease",
+    'org.loinc.LP173023-5': "Rheumatology",
+    'org.loinc.LP248728-0': "Sleep medicine",
+    'org.loinc.LP417852-3': "Solid organ transplant",
+    'org.loinc.LP173027-6': "Sports medicine",
+    'org.loinc.LP172956-7': "Medical genetics",
+    'org.loinc.LP173011-0': "Psychiatry",
+    'org.loinc.LP173012-8': "Psychology",
+    'org.loinc.LP345049-3': "Cleft and Craniofacial",
+    'org.loinc.LP172964-1': "Neurology",
+    'org.loinc.LP172968-2': "Nuclear medicine",
+    'org.loinc.LP172899-9': "Nutrition and dietetics",
+    'org.loinc.LP172971-6': "Obstetrics and gynecology",
+    'org.loinc.LP172973-2': "Occupational therapy",
+    'org.loinc.LP172901-3': "Oncology",
+    'org.loinc.LP172974-0': "Ophthalmology",
+    'org.loinc.LP434870-4': "Orthopaedic",
+    'org.loinc.LP172979-9': "Orthotics prosthetics",
+    'org.loinc.LP434767-2': "Osteopathic medicine",
+    'org.loinc.LP172980-7': "Otolaryngology",
+    'org.loinc.LP172982-3': "Palliative care",
+    'org.loinc.LP172984-9': "Pathology",
+    'org.loinc.LP173002-9': "Pediatrics",
+    'org.loinc.LP173004-5': "Physical medicine and rehabilitation",
+    'org.loinc.LP173008-6': "Podiatry",
+    'org.loinc.LP173018-5': "Radiology",
+    'org.loinc.LP173036-7': "Urology",
+    'org.loinc.LP248732-2': "Womens health",
+});
+export const clinicalWorkbookSummaryLabelsEn = clinicalWorkbookSummaryLabelI18nEn;

package/dist/models/index.d.ts

@@ -4,6 +4,7 @@ export * from './bundle';
 export * from './comm';
 export * from './clinical-sections';
 export * from './clinical-sections.en';
+export * from './clinical-workbook-summary';
 export * from './confidential-job';
 export * from './confidential-message';
 export * from './confidential-storage';
@@ -20,6 +21,7 @@ export * from './jwe';
 export * from './jwk';
 export * from './jws';
 export * from './jwt';
+export * from './loinc-document-ontology';
 export * from './oidc4ida.common.model';
 export * from './oidc4ida.document.model';
 export * from './oidc4ida.electronicRecord.model';

package/dist/models/index.js

@@ -4,6 +4,7 @@ export * from './bundle.js';
 export * from './comm.js';
 export * from './clinical-sections.js';
 export * from './clinical-sections.en.js';
+export * from './clinical-workbook-summary.js';
 export * from './confidential-job.js';
 export * from './confidential-message.js';
 export * from './confidential-storage.js';
@@ -20,6 +21,7 @@ export * from './jwe.js';
 export * from './jwk.js';
 export * from './jws.js';
 export * from './jwt.js';
+export * from './loinc-document-ontology.js';
 export * from './oidc4ida.common.model.js';
 export * from './oidc4ida.document.model.js';
 export * from './oidc4ida.electronicRecord.model.js';

package/dist/models/interoperable-claims/communication-claims.d.ts

@@ -9,6 +9,7 @@ export declare const CommunicationClaim: {
     readonly ContentAttachmentData: "Communication.content-attachment-data";
     readonly ContentAttachmentType: "Communication.content-attachment-type";
     readonly ContentAttachmentTitle: "Communication.content-attachment-title";
-    readonly PartOf: "Communication.partOf";
+    readonly PartOf: "Communication.part-of";
+    readonly PartOfLegacy: "Communication.partOf";
 };
 export type CommunicationClaimKey = typeof CommunicationClaim[keyof typeof CommunicationClaim];

package/dist/models/interoperable-claims/communication-claims.js

@@ -11,5 +11,6 @@ export const CommunicationClaim = {
     ContentAttachmentData: 'Communication.content-attachment-data',
     ContentAttachmentType: 'Communication.content-attachment-type',
     ContentAttachmentTitle: 'Communication.content-attachment-title',
-    PartOf: 'Communication.partOf',
+    PartOf: 'Communication.part-of',
+    PartOfLegacy: 'Communication.partOf',
 };

package/dist/models/loinc-document-ontology.d.ts

@@ -0,0 +1,55 @@
+/**
+ * LOINC Document Ontology helpers for Communication ingestion workflows.
+ *
+ * Source:
+ * - https://loinc.org/kb/users-guide/document-ontology/
+ *
+ * Notes:
+ * - LP codes are represented as bare codes (e.g., "LP173418-7").
+ * - When a claim requires a coding token value, prefer `LOINC|<CODE>`.
+ */
+export declare const LOINC_TOKEN_PREFIX: "LOINC|";
+export declare function toLoincToken(code: string): `${typeof LOINC_TOKEN_PREFIX}${string}`;
+export declare const loincOntology: Readonly<{
+    KindOfDocument: Readonly<{
+        Note: Readonly<{
+            code: "LP173418-7";
+            AdverseEventNote: Readonly<{
+                code: "LP173419-5";
+            }>;
+            Alert: Readonly<{
+                code: "LP173420-3";
+            }>;
+            AppointmentReminder: Readonly<{
+                code: "LP434808-4";
+            }>;
+            ArrivalNotificationNote: Readonly<{
+                code: "LP436847-0";
+            }>;
+            ComprehensivePlanOfCareNote: Readonly<{
+                code: "LP436848-8";
+            }>;
+            ClinicalNote: Readonly<{
+                code: "LP447692-7";
+            }>;
+            ScreeningInvitationLetter: Readonly<{
+                code: "LP448671-0";
+            }>;
+            ImplantedDeviceNote: Readonly<{
+                code: "LP450051-0";
+            }>;
+            RepositoryInitialEvaluationNote: Readonly<{
+                code: "LP436851-2";
+            }>;
+        }>;
+    }>;
+}>;
+/**
+ * Defaults agreed for Communication ingestion:
+ * - datatype: KindOfDocument.Note
+ * - category: Arrival notification note
+ */
+export declare const communicationIngestionDefaults: Readonly<{
+    datatype: `LOINC|${string}`;
+    category: `LOINC|${string}`;
+}>;

package/dist/models/loinc-document-ontology.js

@@ -0,0 +1,57 @@
+/**
+ * LOINC Document Ontology helpers for Communication ingestion workflows.
+ *
+ * Source:
+ * - https://loinc.org/kb/users-guide/document-ontology/
+ *
+ * Notes:
+ * - LP codes are represented as bare codes (e.g., "LP173418-7").
+ * - When a claim requires a coding token value, prefer `LOINC|<CODE>`.
+ */
+export const LOINC_TOKEN_PREFIX = 'LOINC|';
+export function toLoincToken(code) {
+    return `${LOINC_TOKEN_PREFIX}${code}`;
+}
+export const loincOntology = Object.freeze({
+    KindOfDocument: Object.freeze({
+        Note: Object.freeze({
+            code: 'LP173418-7',
+            AdverseEventNote: Object.freeze({
+                code: 'LP173419-5',
+            }),
+            Alert: Object.freeze({
+                code: 'LP173420-3',
+            }),
+            AppointmentReminder: Object.freeze({
+                code: 'LP434808-4',
+            }),
+            ArrivalNotificationNote: Object.freeze({
+                code: 'LP436847-0',
+            }),
+            ComprehensivePlanOfCareNote: Object.freeze({
+                code: 'LP436848-8',
+            }),
+            ClinicalNote: Object.freeze({
+                code: 'LP447692-7',
+            }),
+            ScreeningInvitationLetter: Object.freeze({
+                code: 'LP448671-0',
+            }),
+            ImplantedDeviceNote: Object.freeze({
+                code: 'LP450051-0',
+            }),
+            RepositoryInitialEvaluationNote: Object.freeze({
+                code: 'LP436851-2',
+            }),
+        }),
+    }),
+});
+/**
+ * Defaults agreed for Communication ingestion:
+ * - datatype: KindOfDocument.Note
+ * - category: Arrival notification note
+ */
+export const communicationIngestionDefaults = Object.freeze({
+    datatype: toLoincToken(loincOntology.KindOfDocument.Note.code),
+    category: toLoincToken(loincOntology.KindOfDocument.Note.ArrivalNotificationNote.code),
+});

package/dist/utils/communication-fhir-r4.d.ts

@@ -0,0 +1,23 @@
+export type CommunicationClaims = Record<string, unknown>;
+export type CommunicationTransformMode = 'strict' | 'normalize';
+export type TransformCommunicationClaimsToResourceFhirR4Options = {
+    mode?: CommunicationTransformMode;
+    defaultStatus?: string;
+};
+export type TransformCommunicationClaimsToResourceFhirR4Result = {
+    resources: Array<Record<string, unknown>>;
+    warnings: string[];
+};
+export declare function validateCommunicationResourceFhirR4(resource: Record<string, unknown>): Promise<{
+    ok: boolean;
+    issues: Array<{
+        severity: 'error' | 'warning';
+        code: string;
+        diagnostics: string;
+        expression?: string;
+    }>;
+}>;
+export declare function transformCommunicationClaimsToResourceFhirR4(communicationClaims: CommunicationClaims[], options?: TransformCommunicationClaimsToResourceFhirR4Options): TransformCommunicationClaimsToResourceFhirR4Result;
+export declare function extractCommunicationClaimsFromResourceFhirR4(resource: Record<string, unknown>, options?: {
+    preferMetaClaims?: boolean;
+}): CommunicationClaims;

package/dist/utils/communication-fhir-r4.js

@@ -0,0 +1,189 @@
+import { validateFhirResource } from './fhir-validator.js';
+export async function validateCommunicationResourceFhirR4(resource) {
+    return validateFhirResource(resource, 'r4');
+}
+export function transformCommunicationClaimsToResourceFhirR4(communicationClaims, options = {}) {
+    const mode = options.mode ?? 'strict';
+    const defaultStatus = options.defaultStatus ?? 'completed';
+    const warnings = [];
+    const resources = communicationClaims.map((claims, index) => {
+        const payloadAttachmentData = toStringOrUndefined(claims['Communication.content-attachment-data']);
+        const payloadAttachmentType = toStringOrUndefined(claims['Communication.content-attachment-type']);
+        const payloadAttachmentTitle = toStringOrUndefined(claims['Communication.content-attachment-title']);
+        const payloadAttachmentUrl = toStringOrUndefined(claims['Communication.content-attachment-url']);
+        const payloadReference = toStringOrUndefined(claims['Communication.content-reference']);
+        const payloadCodeRaw = toStringOrUndefined(claims['Communication.content-code']);
+        const hasAttachment = Boolean(payloadAttachmentData || payloadAttachmentType || payloadAttachmentTitle || payloadAttachmentUrl);
+        const hasReference = Boolean(payloadReference);
+        const hasCode = Boolean(payloadCodeRaw);
+        const payloadKinds = [hasAttachment, hasReference, hasCode].filter(Boolean).length;
+        if (payloadKinds > 1) {
+            const msg = `Communication[${index}] has more than one payload kind (attachment/reference/code).`;
+            if (mode === 'strict')
+                throw new Error(msg);
+            warnings.push(`${msg} Keeping attachment > reference > code.`);
+        }
+        const noteValues = normalizeNoteValues(claims['Communication.note'] ?? claims['Communication.text']);
+        if (noteValues.length > 1) {
+            const msg = `Communication[${index}] has more than one note.`;
+            if (mode === 'strict')
+                throw new Error(msg);
+            warnings.push(`${msg} Keeping first note only.`);
+        }
+        const payload = buildPayload({
+            hasAttachment,
+            hasReference,
+            hasCode,
+            payloadAttachmentData,
+            payloadAttachmentType,
+            payloadAttachmentTitle,
+            payloadAttachmentUrl,
+            payloadReference,
+            payloadCodeRaw,
+        });
+        const partOf = toStringOrUndefined(claims['Communication.part-of'] ?? claims['Communication.partOf']);
+        if (claims['Communication.partOf'] !== undefined) {
+            const msg = `Communication[${index}] uses legacy key 'Communication.partOf'. Use 'Communication.part-of'.`;
+            if (mode === 'strict')
+                throw new Error(msg);
+            warnings.push(msg);
+        }
+        const resource = {
+            resourceType: 'Communication',
+            status: toStringOrUndefined(claims['Communication.status']) || defaultStatus,
+            meta: {
+                claims: { ...claims },
+            },
+        };
+        const identifier = toStringOrUndefined(claims['Communication.identifier']);
+        if (identifier)
+            resource['identifier'] = [{ value: identifier }];
+        const sent = toStringOrUndefined(claims['Communication.sent']);
+        if (sent)
+            resource['sent'] = sent;
+        const category = toStringOrUndefined(claims['Communication.category']);
+        if (category)
+            resource['category'] = [{ coding: [parseSystemCode(category)] }];
+        const subject = toStringOrUndefined(claims['Communication.subject']);
+        if (subject)
+            resource['subject'] = { reference: subject };
+        const recipient = toStringOrUndefined(claims['Communication.recipient']);
+        if (recipient)
+            resource['recipient'] = [{ reference: recipient }];
+        const sender = toStringOrUndefined(claims['Communication.sender']);
+        if (sender)
+            resource['sender'] = { reference: sender };
+        if (partOf)
+            resource['partOf'] = [{ reference: partOf }];
+        if (payload)
+            resource['payload'] = [payload];
+        if (noteValues.length)
+            resource['note'] = [{ text: noteValues[0] }];
+        return resource;
+    });
+    return { resources, warnings };
+}
+export function extractCommunicationClaimsFromResourceFhirR4(resource, options = {}) {
+    const preferMetaClaims = options.preferMetaClaims !== false;
+    const existingClaims = resource?.meta?.claims;
+    if (preferMetaClaims && existingClaims && typeof existingClaims === 'object') {
+        return { ...existingClaims };
+    }
+    const claims = {};
+    claims['@context'] = 'org.hl7.fhir.r4';
+    const identifierValue = resource?.identifier?.[0]?.value;
+    const status = resource?.status;
+    const sent = resource?.sent;
+    const subjectRef = resource?.subject?.reference;
+    const recipientRef = resource?.recipient?.[0]?.reference;
+    const senderRef = resource?.sender?.reference;
+    const partOfRef = resource?.partOf?.[0]?.reference;
+    const noteText = resource?.note?.[0]?.text;
+    const categoryCoding = resource?.category?.[0]?.coding?.[0];
+    const payload = resource?.payload?.[0];
+    const contentReference = payload?.contentReference?.reference;
+    const contentAttachment = payload?.contentAttachment;
+    const contentCodeableConcept = payload?.contentCodeableConcept?.coding?.[0];
+    setIf(claims, 'Communication.identifier', identifierValue);
+    setIf(claims, 'Communication.status', status);
+    setIf(claims, 'Communication.sent', sent);
+    setIf(claims, 'Communication.subject', subjectRef);
+    setIf(claims, 'Communication.recipient', recipientRef);
+    setIf(claims, 'Communication.sender', senderRef);
+    setIf(claims, 'Communication.part-of', partOfRef);
+    setIf(claims, 'Communication.text', noteText);
+    setIf(claims, 'Communication.note', noteText);
+    if (categoryCoding) {
+        const system = toStringOrUndefined(categoryCoding.system);
+        const code = toStringOrUndefined(categoryCoding.code);
+        if (system && code)
+            claims['Communication.category'] = `${system}|${code}`;
+        else if (code)
+            claims['Communication.category'] = code;
+    }
+    setIf(claims, 'Communication.content-reference', contentReference);
+    if (contentAttachment) {
+        setIf(claims, 'Communication.content-attachment-data', contentAttachment.data);
+        setIf(claims, 'Communication.content-attachment-type', contentAttachment.contentType);
+        setIf(claims, 'Communication.content-attachment-title', contentAttachment.title);
+        setIf(claims, 'Communication.content-attachment-url', contentAttachment.url);
+    }
+    if (contentCodeableConcept) {
+        const system = toStringOrUndefined(contentCodeableConcept.system);
+        const code = toStringOrUndefined(contentCodeableConcept.code);
+        if (system && code)
+            claims['Communication.content-code'] = `${system}|${code}`;
+        else if (code)
+            claims['Communication.content-code'] = code;
+    }
+    return claims;
+}
+function setIf(claims, key, value) {
+    const text = toStringOrUndefined(value);
+    if (text)
+        claims[key] = text;
+}
+function normalizeNoteValues(raw) {
+    if (typeof raw === 'string' && raw.trim())
+        return [raw.trim()];
+    if (Array.isArray(raw)) {
+        return raw.map((item) => (typeof item === 'string' ? item.trim() : '')).filter(Boolean);
+    }
+    return [];
+}
+function buildPayload(input) {
+    const { hasAttachment, hasReference, hasCode, payloadAttachmentData, payloadAttachmentType, payloadAttachmentTitle, payloadAttachmentUrl, payloadReference, payloadCodeRaw, } = input;
+    if (hasAttachment) {
+        const value = {};
+        if (payloadAttachmentData)
+            value['data'] = payloadAttachmentData;
+        if (payloadAttachmentType)
+            value['contentType'] = payloadAttachmentType;
+        if (payloadAttachmentTitle)
+            value['title'] = payloadAttachmentTitle;
+        if (payloadAttachmentUrl)
+            value['url'] = payloadAttachmentUrl;
+        return { contentAttachment: value };
+    }
+    if (hasReference)
+        return { contentReference: { reference: payloadReference } };
+    if (hasCode && payloadCodeRaw)
+        return { contentCodeableConcept: { coding: [parseSystemCode(payloadCodeRaw)] } };
+    return undefined;
+}
+function parseSystemCode(value) {
+    const trimmed = String(value || '').trim();
+    const separatorIndex = trimmed.indexOf('|');
+    if (separatorIndex > 0) {
+        const system = trimmed.slice(0, separatorIndex).trim();
+        const code = trimmed.slice(separatorIndex + 1).trim();
+        return { system, code };
+    }
+    return { code: trimmed };
+}
+function toStringOrUndefined(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const text = String(value).trim();
+    return text || undefined;
+}

package/dist/utils/fhir-validator.d.ts

@@ -0,0 +1,54 @@
+export type FhirVersion = 'r4' | 'r5' | string;
+export type FhirValidationIssue = {
+    severity: 'error' | 'warning';
+    code: string;
+    diagnostics: string;
+    expression?: string;
+};
+export type FhirValidationResult = {
+    ok: boolean;
+    issues: FhirValidationIssue[];
+};
+export type FhirValidatorAdapter = {
+    /**
+     * Stable adapter id for observability/configuration.
+     * Example: `basic`, `hl7-official-cli`, `hapi`.
+     */
+    id: string;
+    /**
+     * Returns true when this adapter can validate the requested FHIR version.
+     */
+    supports(version: FhirVersion): boolean;
+    /**
+     * Validates one resource and returns OperationOutcome-like issues.
+     */
+    validate(resource: Record<string, unknown>, version: FhirVersion): Promise<FhirValidationResult> | FhirValidationResult;
+};
+/**
+ * Registers a custom FHIR validator adapter.
+ * Adapters are checked in registration order.
+ */
+export declare function registerFhirValidatorAdapter(adapter: FhirValidatorAdapter): void;
+/**
+ * Clears all registered adapters.
+ * Intended for tests or explicit runtime reconfiguration.
+ */
+export declare function clearFhirValidatorAdapters(): void;
+/**
+ * Returns currently registered adapters (read-only copy).
+ */
+export declare function listFhirValidatorAdapters(): FhirValidatorAdapter[];
+/**
+ * Validates a FHIR resource using the first registered adapter that supports the requested version.
+ * Falls back to built-in structural validation when no adapter matches.
+ *
+ * This utility is intentionally adapter-based so SDK/GW can share one validation entrypoint while
+ * keeping the formal validator implementation pluggable per deployment.
+ */
+export declare function validateFhirResource(resource: Record<string, unknown>, version?: FhirVersion): Promise<FhirValidationResult>;
+/**
+ * Minimal built-in structural validation.
+ * This does not replace a formal HL7 profile validator; it provides a safe baseline
+ * and deterministic checks for common gateway constraints.
+ */
+export declare function validateFhirResourceBasic(resource: Record<string, unknown>, _version?: FhirVersion): FhirValidationResult;

package/dist/utils/fhir-validator.js

@@ -0,0 +1,84 @@
+const validators = [];
+/**
+ * Registers a custom FHIR validator adapter.
+ * Adapters are checked in registration order.
+ */
+export function registerFhirValidatorAdapter(adapter) {
+    validators.push(adapter);
+}
+/**
+ * Clears all registered adapters.
+ * Intended for tests or explicit runtime reconfiguration.
+ */
+export function clearFhirValidatorAdapters() {
+    validators.length = 0;
+}
+/**
+ * Returns currently registered adapters (read-only copy).
+ */
+export function listFhirValidatorAdapters() {
+    return [...validators];
+}
+/**
+ * Validates a FHIR resource using the first registered adapter that supports the requested version.
+ * Falls back to built-in structural validation when no adapter matches.
+ *
+ * This utility is intentionally adapter-based so SDK/GW can share one validation entrypoint while
+ * keeping the formal validator implementation pluggable per deployment.
+ */
+export async function validateFhirResource(resource, version = 'r4') {
+    const adapter = validators.find((item) => item.supports(version));
+    if (adapter)
+        return adapter.validate(resource, version);
+    return validateFhirResourceBasic(resource, version);
+}
+/**
+ * Minimal built-in structural validation.
+ * This does not replace a formal HL7 profile validator; it provides a safe baseline
+ * and deterministic checks for common gateway constraints.
+ */
+export function validateFhirResourceBasic(resource, _version = 'r4') {
+    const issues = [];
+    const resourceType = String(resource?.resourceType || '').trim();
+    if (!resourceType) {
+        issues.push({
+            severity: 'error',
+            code: 'required',
+            diagnostics: 'Missing required field: resourceType.',
+            expression: 'resourceType',
+        });
+    }
+    if (resourceType === 'Communication') {
+        const status = String(resource?.status || '').trim();
+        if (!status) {
+            issues.push({
+                severity: 'error',
+                code: 'required',
+                diagnostics: 'Communication.status is required.',
+                expression: 'Communication.status',
+            });
+        }
+        const payload = resource?.payload;
+        if (Array.isArray(payload) && payload.length > 1) {
+            issues.push({
+                severity: 'warning',
+                code: 'business-rule',
+                diagnostics: 'Gateway convention recommends one payload per Communication.',
+                expression: 'Communication.payload',
+            });
+        }
+        const note = resource?.note;
+        if (Array.isArray(note) && note.length > 1) {
+            issues.push({
+                severity: 'warning',
+                code: 'business-rule',
+                diagnostics: 'Gateway convention recommends one note per Communication.',
+                expression: 'Communication.note',
+            });
+        }
+    }
+    return {
+        ok: issues.every((issue) => issue.severity !== 'error'),
+        issues,
+    };
+}

package/dist/utils/index.d.ts

@@ -10,6 +10,8 @@ export * from './didcomm-submit';
 export * from './didcomm-submit-policy';
 export * from './format-converter';
 export * from './fhir-cid';
+export * from './communication-fhir-r4';
+export * from './fhir-validator';
 export * from './jwt';
 export * from './manager-error';
 export * from './multibase58';

package/dist/utils/index.js

@@ -10,6 +10,8 @@ export * from './didcomm-submit.js';
 export * from './didcomm-submit-policy.js';
 export * from './format-converter.js';
 export * from './fhir-cid.js';
+export * from './communication-fhir-r4.js';
+export * from './fhir-validator.js';
 export * from './jwt.js';
 export * from './manager-error.js';
 export * from './multibase58.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdc-common-utils-ts",
-  "version": "1.4.12",
+  "version": "1.4.14",
   "publishConfig": {
     "access": "public"
   },