gdc-common-utils-ts 1.14.0 → 1.14.2

package/dist/constants/healthcare.js

@@ -1,11 +1,31 @@
-import { LOINC_SYSTEM_URL } from '../models/clinical-sections.js';
-function defineSection(code) {
+import { LOINC_SYSTEM_URL, loincI18nKey } from '../models/clinical-sections.js';
+import { clinicalDocTypes, clinicalSectionAdditional, clinicalSectionsBase, } from '../models/clinical-sections.en.js';
+import { HL7_CODING_SYSTEM_PERSONAL_RELATIONSHIP, HL7_CODING_SYSTEM_V3_ROLE_CODE, HL7_PERSONAL_RELATIONSHIP_ROLES, HL7_V3_ROLE_CODE_LEGAL_REPRESENTATIVE, } from './hl7-roles.js';
+import { DataspaceSectors } from './sectors.js';
+export const ISCO08_CODING_SYSTEM = 'org.ilo.isco';
+export const ISCO08_I18N_NAMESPACE = 'org.ilo.isco-08';
+export const HealthcareRoleFamilies = Object.freeze({
+    ProfessionalOccupationIsco08: 'professionalOccupationIsco08',
+    PersonalRelationshipHl7: 'personalRelationshipHl7',
+    LegalRepresentativeHl7: 'legalRepresentativeHl7',
+});
+function defineSection(code, titleEn) {
     return Object.freeze({
         system: LOINC_SYSTEM_URL,
         code,
         claim: `LOINC|${code}`,
+        i18nKey: loincI18nKey(code),
+        titleEn,
     });
 }
+export const HealthcareSectionFamilies = Object.freeze({
+    Summary: 'summary',
+    Management: 'management',
+    SubjectMatterDomain: 'subjectMatterDomain',
+});
+function buildSectionCatalogByCode(source) {
+    return Object.freeze(Object.fromEntries(Object.entries(source).map(([code, titleEn]) => [code, defineSection(code, titleEn)])));
+}
 export const HealthcareBasicSections = Object.freeze({
     PatientSummaryDocument: defineSection('60591-5'),
     AllergiesAndIntolerances: defineSection('48765-2'),
@@ -32,6 +52,31 @@ export const HealthcareAllSections = Object.freeze({
     ...HealthcareBasicSections,
     ...HealthcareAdditionalSections,
 });
+/**
+ * Full section families sourced from the existing section catalogs in
+ * `models/clinical-sections.en.ts`.
+ *
+ * Family mapping used by SDK/business layers:
+ * - `summary`: IPS/base summary sections.
+ * - `management`: kind-of-document and type-of-service oriented sections.
+ * - `subjectMatterDomain`: additional service-domain sections.
+ */
+export const HealthcareSectionsByFamily = Object.freeze({
+    [HealthcareSectionFamilies.Summary]: buildSectionCatalogByCode(clinicalSectionsBase),
+    [HealthcareSectionFamilies.Management]: buildSectionCatalogByCode(clinicalDocTypes),
+    [HealthcareSectionFamilies.SubjectMatterDomain]: buildSectionCatalogByCode(clinicalSectionAdditional),
+});
+export const HealthcareAllSectionsByCode = Object.freeze({
+    ...HealthcareSectionsByFamily[HealthcareSectionFamilies.Summary],
+    ...HealthcareSectionsByFamily[HealthcareSectionFamilies.Management],
+    ...HealthcareSectionsByFamily[HealthcareSectionFamilies.SubjectMatterDomain],
+});
+export function getHealthcareSectionByCode(code) {
+    return HealthcareAllSectionsByCode[String(code || '').trim()];
+}
+export function getHealthcareSectionsByFamily(family) {
+    return HealthcareSectionsByFamily[family];
+}
 export const HealthcareConsentPurposes = Object.freeze({
     Treatment: 'TREAT',
     EmergencyTreatment: 'ETREAT',
@@ -45,6 +90,7 @@ export const HealthcareActorRoles = Object.freeze({
     Physician: 'ISCO-08|2211',
     NursingProfessional: 'ISCO-08|2221',
     Paramedic: 'ISCO-08|2240',
+    Veterinarian: 'ISCO-08|2250',
 });
 export const HealthcareActorRoleCodes = Object.freeze({
     Controller: '1120',
@@ -52,7 +98,171 @@ export const HealthcareActorRoleCodes = Object.freeze({
     PhysicianBroad: '221',
     NursingProfessional: '2221',
     Paramedic: '2240',
+    Veterinarian: '2250',
+});
+function buildProfessionalIscoRoles() {
+    const entries = [
+        [
+            HealthcareActorRoleCodes.Controller,
+            Object.freeze({
+                family: HealthcareRoleFamilies.ProfessionalOccupationIsco08,
+                codingSystem: ISCO08_CODING_SYSTEM,
+                code: HealthcareActorRoleCodes.Controller,
+                claim: HealthcareActorRoles.Controller,
+                i18nKey: `${ISCO08_I18N_NAMESPACE}.${HealthcareActorRoleCodes.Controller}`,
+                titleEn: 'Controller',
+            }),
+        ],
+        [
+            HealthcareActorRoleCodes.Physician,
+            Object.freeze({
+                family: HealthcareRoleFamilies.ProfessionalOccupationIsco08,
+                codingSystem: ISCO08_CODING_SYSTEM,
+                code: HealthcareActorRoleCodes.Physician,
+                claim: HealthcareActorRoles.Physician,
+                i18nKey: `${ISCO08_I18N_NAMESPACE}.${HealthcareActorRoleCodes.Physician}`,
+                titleEn: 'Physician',
+            }),
+        ],
+        [
+            HealthcareActorRoleCodes.NursingProfessional,
+            Object.freeze({
+                family: HealthcareRoleFamilies.ProfessionalOccupationIsco08,
+                codingSystem: ISCO08_CODING_SYSTEM,
+                code: HealthcareActorRoleCodes.NursingProfessional,
+                claim: HealthcareActorRoles.NursingProfessional,
+                i18nKey: `${ISCO08_I18N_NAMESPACE}.${HealthcareActorRoleCodes.NursingProfessional}`,
+                titleEn: 'Nursing professional',
+            }),
+        ],
+        [
+            HealthcareActorRoleCodes.Paramedic,
+            Object.freeze({
+                family: HealthcareRoleFamilies.ProfessionalOccupationIsco08,
+                codingSystem: ISCO08_CODING_SYSTEM,
+                code: HealthcareActorRoleCodes.Paramedic,
+                claim: HealthcareActorRoles.Paramedic,
+                i18nKey: `${ISCO08_I18N_NAMESPACE}.${HealthcareActorRoleCodes.Paramedic}`,
+                titleEn: 'Paramedic',
+            }),
+        ],
+        [
+            HealthcareActorRoleCodes.Veterinarian,
+            Object.freeze({
+                family: HealthcareRoleFamilies.ProfessionalOccupationIsco08,
+                codingSystem: ISCO08_CODING_SYSTEM,
+                code: HealthcareActorRoleCodes.Veterinarian,
+                claim: HealthcareActorRoles.Veterinarian,
+                i18nKey: `${ISCO08_I18N_NAMESPACE}.${HealthcareActorRoleCodes.Veterinarian}`,
+                titleEn: 'Veterinarian',
+            }),
+        ],
+    ];
+    return Object.freeze(Object.fromEntries(entries));
+}
+function buildPersonalRelationshipRoles() {
+    return Object.freeze(Object.fromEntries(HL7_PERSONAL_RELATIONSHIP_ROLES.map((item) => [
+        item.code,
+        Object.freeze({
+            family: HealthcareRoleFamilies.PersonalRelationshipHl7,
+            codingSystem: HL7_CODING_SYSTEM_PERSONAL_RELATIONSHIP,
+            code: item.code,
+            claim: `v3-PersonalRelationshipRoleType|${item.code}`,
+            i18nKey: `org.hl7.v3.personalRelationship.${item.code}`,
+            titleEn: item.display,
+            definition: item.definition,
+        }),
+    ])));
+}
+function buildLegalRepresentativeRoles() {
+    return Object.freeze(Object.fromEntries(HL7_V3_ROLE_CODE_LEGAL_REPRESENTATIVE.map((item) => [
+        item.code,
+        Object.freeze({
+            family: HealthcareRoleFamilies.LegalRepresentativeHl7,
+            codingSystem: HL7_CODING_SYSTEM_V3_ROLE_CODE,
+            code: item.code,
+            claim: `v3-RoleCode|${item.code}`,
+            i18nKey: `org.hl7.v3.roleCode.${item.code}`,
+            titleEn: item.display,
+            definition: item.definition,
+        }),
+    ])));
+}
+export const HealthcareRolesByFamily = Object.freeze({
+    [HealthcareRoleFamilies.ProfessionalOccupationIsco08]: buildProfessionalIscoRoles(),
+    [HealthcareRoleFamilies.PersonalRelationshipHl7]: buildPersonalRelationshipRoles(),
+    [HealthcareRoleFamilies.LegalRepresentativeHl7]: buildLegalRepresentativeRoles(),
+});
+export const HealthcareAllRolesByClaim = Object.freeze(Object.fromEntries(Object.values(HealthcareRolesByFamily)
+    .flatMap((catalog) => Object.values(catalog))
+    .map((descriptor) => [descriptor.claim, descriptor])));
+function pickRoleCatalogByCodes(catalog, codes) {
+    return Object.freeze(Object.fromEntries(codes
+        .map((code) => [code, catalog[code]])
+        .filter((entry) => Boolean(entry[1]))));
+}
+export const HealthcareProfessionalRoleCodesBySector = Object.freeze({
+    [DataspaceSectors.HealthCare]: Object.freeze([
+        HealthcareActorRoleCodes.Controller,
+        HealthcareActorRoleCodes.Physician,
+        HealthcareActorRoleCodes.NursingProfessional,
+        HealthcareActorRoleCodes.Paramedic,
+    ]),
+    [DataspaceSectors.HealthResearch]: Object.freeze([
+        HealthcareActorRoleCodes.Controller,
+        HealthcareActorRoleCodes.Physician,
+    ]),
+    [DataspaceSectors.HealthTech]: Object.freeze([HealthcareActorRoleCodes.Controller]),
+    [DataspaceSectors.HealthInsurance]: Object.freeze([HealthcareActorRoleCodes.Controller]),
+    [DataspaceSectors.AnimalCare]: Object.freeze([
+        HealthcareActorRoleCodes.Controller,
+        HealthcareActorRoleCodes.Veterinarian,
+    ]),
+    [DataspaceSectors.AnimalResearch]: Object.freeze([
+        HealthcareActorRoleCodes.Controller,
+        HealthcareActorRoleCodes.Veterinarian,
+    ]),
+    [DataspaceSectors.AnimalInsurance]: Object.freeze([HealthcareActorRoleCodes.Controller]),
+    [DataspaceSectors.AnimalTech]: Object.freeze([HealthcareActorRoleCodes.Controller]),
+    [DataspaceSectors.OneHealthResearch]: Object.freeze([
+        HealthcareActorRoleCodes.Controller,
+        HealthcareActorRoleCodes.Physician,
+        HealthcareActorRoleCodes.Veterinarian,
+    ]),
+    [DataspaceSectors.OneHealthTech]: Object.freeze([HealthcareActorRoleCodes.Controller]),
+});
+export const HealthcareProfessionalRolesBySector = Object.freeze({
+    [DataspaceSectors.HealthCare]: pickRoleCatalogByCodes(HealthcareRolesByFamily[HealthcareRoleFamilies.ProfessionalOccupationIsco08], HealthcareProfessionalRoleCodesBySector[DataspaceSectors.HealthCare]),
+    [DataspaceSectors.HealthResearch]: pickRoleCatalogByCodes(HealthcareRolesByFamily[HealthcareRoleFamilies.ProfessionalOccupationIsco08], HealthcareProfessionalRoleCodesBySector[DataspaceSectors.HealthResearch]),
+    [DataspaceSectors.HealthTech]: pickRoleCatalogByCodes(HealthcareRolesByFamily[HealthcareRoleFamilies.ProfessionalOccupationIsco08], HealthcareProfessionalRoleCodesBySector[DataspaceSectors.HealthTech]),
+    [DataspaceSectors.HealthInsurance]: pickRoleCatalogByCodes(HealthcareRolesByFamily[HealthcareRoleFamilies.ProfessionalOccupationIsco08], HealthcareProfessionalRoleCodesBySector[DataspaceSectors.HealthInsurance]),
+    [DataspaceSectors.AnimalCare]: pickRoleCatalogByCodes(HealthcareRolesByFamily[HealthcareRoleFamilies.ProfessionalOccupationIsco08], HealthcareProfessionalRoleCodesBySector[DataspaceSectors.AnimalCare]),
+    [DataspaceSectors.AnimalResearch]: pickRoleCatalogByCodes(HealthcareRolesByFamily[HealthcareRoleFamilies.ProfessionalOccupationIsco08], HealthcareProfessionalRoleCodesBySector[DataspaceSectors.AnimalResearch]),
+    [DataspaceSectors.AnimalInsurance]: pickRoleCatalogByCodes(HealthcareRolesByFamily[HealthcareRoleFamilies.ProfessionalOccupationIsco08], HealthcareProfessionalRoleCodesBySector[DataspaceSectors.AnimalInsurance]),
+    [DataspaceSectors.AnimalTech]: pickRoleCatalogByCodes(HealthcareRolesByFamily[HealthcareRoleFamilies.ProfessionalOccupationIsco08], HealthcareProfessionalRoleCodesBySector[DataspaceSectors.AnimalTech]),
+    [DataspaceSectors.OneHealthResearch]: pickRoleCatalogByCodes(HealthcareRolesByFamily[HealthcareRoleFamilies.ProfessionalOccupationIsco08], HealthcareProfessionalRoleCodesBySector[DataspaceSectors.OneHealthResearch]),
+    [DataspaceSectors.OneHealthTech]: pickRoleCatalogByCodes(HealthcareRolesByFamily[HealthcareRoleFamilies.ProfessionalOccupationIsco08], HealthcareProfessionalRoleCodesBySector[DataspaceSectors.OneHealthTech]),
 });
+export const HealthcareRolesBySector = Object.freeze(Object.fromEntries(Object.values(DataspaceSectors).map((sector) => [
+    sector,
+    Object.freeze({
+        [HealthcareRoleFamilies.ProfessionalOccupationIsco08]: HealthcareProfessionalRolesBySector[sector] || {},
+        [HealthcareRoleFamilies.PersonalRelationshipHl7]: HealthcareRolesByFamily[HealthcareRoleFamilies.PersonalRelationshipHl7],
+        [HealthcareRoleFamilies.LegalRepresentativeHl7]: HealthcareRolesByFamily[HealthcareRoleFamilies.LegalRepresentativeHl7],
+    }),
+])));
+export function getHealthcareRolesByFamily(family) {
+    return HealthcareRolesByFamily[family];
+}
+export function getHealthcareRoleByClaim(claim) {
+    return HealthcareAllRolesByClaim[String(claim || '').trim()];
+}
+export function getHealthcareProfessionalRolesBySector(sector) {
+    return HealthcareProfessionalRolesBySector[sector] || {};
+}
+export function getHealthcareRolesBySector(sector, family) {
+    return HealthcareRolesBySector[sector]?.[family] || {};
+}
 export const HealthcareConsentActions = Object.freeze({
     PatientSummaryDocument: HealthcareBasicSections.PatientSummaryDocument.claim,
     AllergiesAndIntolerances: HealthcareBasicSections.AllergiesAndIntolerances.claim,

package/dist/examples/communication-bundle-session.d.ts

@@ -0,0 +1,22 @@
+import { BundleEntry, BundleJsonApi } from '../models/bundle';
+/**
+ * First developer use case:
+ * - edit a Consent entry inside a Communication-attached Bundle
+ * - keep active entry in memory
+ * - serialize full Bundle to Communication.content-attachment-data on save
+ * - release active entry memory when finished
+ */
+export declare function buildConsentEditingCommunicationSessionExample(): {
+    communicationClaims: Record<string, unknown>;
+    bundleInMemory: BundleJsonApi<BundleEntry>;
+};
+/**
+ * Second developer use case:
+ * - edit MedicationStatement claims to drive a health view
+ * - keep bundle attached to Communication as base64 payload
+ * - apply save/release lifecycle consistently
+ */
+export declare function buildMedicationEditingCommunicationSessionExample(): {
+    communicationClaims: Record<string, unknown>;
+    bundleInMemory: BundleJsonApi<BundleEntry>;
+};

package/dist/examples/communication-bundle-session.js

@@ -0,0 +1,81 @@
+// Copyright 2026 Conectate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
+// Always create JSDoc, do not use strings inline in keys nor values, use types instead, and reuse the data test examples.
+import { HealthcareBasicSections } from '../constants/healthcare.js';
+import { CommunicationCategoryCodes } from '../constants/communication.js';
+import { ClaimConsent } from '../models/consent-rule.js';
+import { CommunicationClaim } from '../models/interoperable-claims/communication-claims.js';
+import { MedicationStatementClaim } from '../models/interoperable-claims/medication-statement-claims.js';
+import { EXAMPLE_COMMUNICATION_IDENTIFIER, EXAMPLE_CONSENT_DATE, EXAMPLE_CONSENT_IDENTIFIER, EXAMPLE_CONSENT_PERIOD_END, EXAMPLE_CONSENT_PERIOD_START, EXAMPLE_CONSENT_PURPOSE_TREATMENT, EXAMPLE_EMAIL_PROFESSIONAL, EXAMPLE_HEALTHCARE_ACTOR_ROLE_PHYSICIAN, EXAMPLE_IPS_BUNDLE_NOTE_TEXT, EXAMPLE_MEDICATION_STATEMENT_CODE, EXAMPLE_MEDICATION_STATEMENT_IDENTIFIER, EXAMPLE_MEDICATION_STATEMENT_STATUS, EXAMPLE_MEDICATION_STATEMENT_TEXT, EXAMPLE_SUBJECT_DID, } from './shared.js';
+import { CommunicationBundleSession } from '../utils/communication-bundle-session.js';
+/**
+ * First developer use case:
+ * - edit a Consent entry inside a Communication-attached Bundle
+ * - keep active entry in memory
+ * - serialize full Bundle to Communication.content-attachment-data on save
+ * - release active entry memory when finished
+ */
+export function buildConsentEditingCommunicationSessionExample() {
+    const session = new CommunicationBundleSession({
+        communicationClaims: {
+            '@context': 'org.hl7.fhir.r4',
+            [CommunicationClaim.Identifier]: EXAMPLE_COMMUNICATION_IDENTIFIER,
+            [CommunicationClaim.Subject]: EXAMPLE_SUBJECT_DID,
+            [CommunicationClaim.Category]: CommunicationCategoryCodes.Notification.claim,
+            [CommunicationClaim.Text]: EXAMPLE_IPS_BUNDLE_NOTE_TEXT,
+        },
+    });
+    session.upsertActiveConsentEntry({
+        claims: {
+            '@context': 'org.hl7.fhir.api',
+            [ClaimConsent.decision]: 'permit',
+            [ClaimConsent.subject]: EXAMPLE_SUBJECT_DID,
+            [ClaimConsent.identifier]: EXAMPLE_CONSENT_IDENTIFIER,
+            [ClaimConsent.date]: EXAMPLE_CONSENT_DATE,
+            [ClaimConsent.periodStart]: EXAMPLE_CONSENT_PERIOD_START,
+            [ClaimConsent.periodEnd]: EXAMPLE_CONSENT_PERIOD_END,
+            [ClaimConsent.purpose]: EXAMPLE_CONSENT_PURPOSE_TREATMENT,
+            [ClaimConsent.action]: HealthcareBasicSections.AllergiesAndIntolerances.claim,
+            [ClaimConsent.actorIdentifier]: EXAMPLE_EMAIL_PROFESSIONAL,
+            [ClaimConsent.actorRole]: EXAMPLE_HEALTHCARE_ACTOR_ROLE_PHYSICIAN,
+        },
+        fullUrl: `urn:uuid:${EXAMPLE_CONSENT_IDENTIFIER}`,
+    });
+    session.saveAndReleaseActiveEntry();
+    return {
+        communicationClaims: session.getCommunicationClaims(),
+        bundleInMemory: session.getBundleInMemory(),
+    };
+}
+/**
+ * Second developer use case:
+ * - edit MedicationStatement claims to drive a health view
+ * - keep bundle attached to Communication as base64 payload
+ * - apply save/release lifecycle consistently
+ */
+export function buildMedicationEditingCommunicationSessionExample() {
+    const session = new CommunicationBundleSession({
+        communicationClaims: {
+            '@context': 'org.hl7.fhir.r4',
+            [CommunicationClaim.Identifier]: EXAMPLE_COMMUNICATION_IDENTIFIER,
+            [CommunicationClaim.Subject]: EXAMPLE_SUBJECT_DID,
+            [CommunicationClaim.Category]: CommunicationCategoryCodes.Reminder.claim,
+            [CommunicationClaim.Text]: EXAMPLE_IPS_BUNDLE_NOTE_TEXT,
+        },
+    });
+    session.upsertActiveMedicationStatementEntry({
+        claims: {
+            '@context': 'org.hl7.fhir.api',
+            [MedicationStatementClaim.Identifier]: EXAMPLE_MEDICATION_STATEMENT_IDENTIFIER,
+            [MedicationStatementClaim.Subject]: EXAMPLE_SUBJECT_DID,
+            [MedicationStatementClaim.Status]: EXAMPLE_MEDICATION_STATEMENT_STATUS,
+            [MedicationStatementClaim.Code]: EXAMPLE_MEDICATION_STATEMENT_CODE,
+            [MedicationStatementClaim.MedicationText]: EXAMPLE_MEDICATION_STATEMENT_TEXT,
+        },
+        fullUrl: `urn:uuid:${EXAMPLE_MEDICATION_STATEMENT_IDENTIFIER}`,
+    });
+    session.saveAndReleaseActiveEntry();
+    return {
+        communicationClaims: session.getCommunicationClaims(),
+        bundleInMemory: session.getBundleInMemory(),
+    };
+}

package/dist/examples/index.d.ts

@@ -11,3 +11,4 @@ export * from './frontend-session';
 export * from './lifecycle';
 export * from './api-flow-examples';
 export * from './contract-examples';
+export * from './communication-bundle-session';

package/dist/examples/index.js

@@ -11,3 +11,4 @@ export * from './frontend-session.js';
 export * from './lifecycle.js';
 export * from './api-flow-examples.js';
 export * from './contract-examples.js';
+export * from './communication-bundle-session.js';

package/dist/examples/shared.d.ts

@@ -74,6 +74,14 @@ export declare const EXAMPLE_CLINICAL_CODE_PROBLEM: "LOINC|11450-4";
 export declare const EXAMPLE_CONSENT_DATE: "2026-05-20";
 export declare const EXAMPLE_CONSENT_PERIOD_END: "2026-05-01T00:00:00Z";
 export declare const EXAMPLE_CONSENT_PURPOSE_TREATMENT: "TREAT";
+export declare const EXAMPLE_CONSENT_IDENTIFIER: "urn:uuid:consent-example-001";
+export declare const EXAMPLE_CONSENT_PERIOD_START: "2026-05-20T00:00:00Z";
+export declare const EXAMPLE_COMMUNICATION_IDENTIFIER: "urn:uuid:communication-example-001";
+export declare const EXAMPLE_IPS_BUNDLE_NOTE_TEXT: "IPS ingestion request";
+export declare const EXAMPLE_MEDICATION_STATEMENT_IDENTIFIER: "urn:uuid:medication-statement-example-001";
+export declare const EXAMPLE_MEDICATION_STATEMENT_STATUS: "active";
+export declare const EXAMPLE_MEDICATION_STATEMENT_CODE: "http://www.nlm.nih.gov/research/umls/rxnorm|313782";
+export declare const EXAMPLE_MEDICATION_STATEMENT_TEXT: "atorvastatin 20 mg oral tablet";
 export declare const EXAMPLE_EMPLOYEE_ACTIVATION_CODE: "ACT-001";
 export declare const EXAMPLE_DEVICE_CLIENT_ID: "did:web:device-001";
 export type ExampleDateRange = Readonly<{

package/dist/examples/shared.js

@@ -80,6 +80,14 @@ export const EXAMPLE_CLINICAL_CODE_PROBLEM = 'LOINC|11450-4';
 export const EXAMPLE_CONSENT_DATE = '2026-05-20';
 export const EXAMPLE_CONSENT_PERIOD_END = '2026-05-01T00:00:00Z';
 export const EXAMPLE_CONSENT_PURPOSE_TREATMENT = HealthcareConsentPurposes.Treatment;
+export const EXAMPLE_CONSENT_IDENTIFIER = 'urn:uuid:consent-example-001';
+export const EXAMPLE_CONSENT_PERIOD_START = '2026-05-20T00:00:00Z';
+export const EXAMPLE_COMMUNICATION_IDENTIFIER = 'urn:uuid:communication-example-001';
+export const EXAMPLE_IPS_BUNDLE_NOTE_TEXT = 'IPS ingestion request';
+export const EXAMPLE_MEDICATION_STATEMENT_IDENTIFIER = 'urn:uuid:medication-statement-example-001';
+export const EXAMPLE_MEDICATION_STATEMENT_STATUS = 'active';
+export const EXAMPLE_MEDICATION_STATEMENT_CODE = 'http://www.nlm.nih.gov/research/umls/rxnorm|313782';
+export const EXAMPLE_MEDICATION_STATEMENT_TEXT = 'atorvastatin 20 mg oral tablet';
 export const EXAMPLE_EMPLOYEE_ACTIVATION_CODE = 'ACT-001';
 export const EXAMPLE_DEVICE_CLIENT_ID = 'did:web:device-001';
 export const EXAMPLE_CLINICAL_DATE_RANGE = {

package/dist/i18n/role-codes.i18n.d.ts

@@ -0,0 +1,4 @@
+export type RoleCodeI18nKey = `org.ilo.isco-08.${string}` | `org.isco08.${string}` | `org.hl7.v3.personalRelationship.${string}` | `org.hl7.v3.roleCode.${string}`;
+export type RoleCodeI18nMap = Readonly<Record<RoleCodeI18nKey, string>>;
+export declare const roleCodeI18nEn: Readonly<Record<RoleCodeI18nKey, string>>;
+export declare const healthcareRoleI18nEn: Readonly<Record<RoleCodeI18nKey, string>>;

package/dist/i18n/role-codes.i18n.js

@@ -0,0 +1,13 @@
+import { HealthcareRolesByFamily } from '../constants/healthcare.js';
+function buildRoleCodeI18nMap() {
+    const baseEntries = Object.values(HealthcareRolesByFamily)
+        .flatMap((catalog) => Object.values(catalog))
+        .map((descriptor) => [descriptor.i18nKey, descriptor.titleEn]);
+    const legacyIscoAliases = baseEntries
+        .filter(([key]) => key.startsWith('org.ilo.isco-08.'))
+        .map(([key, label]) => [key.replace('org.ilo.isco-08.', 'org.isco08.'), label]);
+    const entries = [...baseEntries, ...legacyIscoAliases];
+    return Object.freeze(Object.fromEntries(entries));
+}
+export const roleCodeI18nEn = buildRoleCodeI18nMap();
+export const healthcareRoleI18nEn = roleCodeI18nEn;

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export * from './constants';
 export * from './examples';
 export * from './hmac';
 export * from './i18n/clinical-sections.i18n';
+export * from './i18n/role-codes.i18n';
 export * from './models';
 export * from './storage';
 export * from './utils';

package/dist/index.js

@@ -4,6 +4,7 @@ export * from './constants/index.js';
 export * from './examples/index.js';
 export * from './hmac.js';
 export * from './i18n/clinical-sections.i18n.js';
+export * from './i18n/role-codes.i18n.js';
 export * from './models/index.js';
 export * from './storage/index.js';
 export * from './utils/index.js';

package/dist/models/bundle.d.ts

@@ -72,6 +72,7 @@ export interface BundleEntryResource {
  */
 export interface BundleEntryRequest {
     id?: string;
+    fullUrl?: string;
     type: string;
     request: BundleRequest;
     resource?: BundleEntryResource;
@@ -84,6 +85,7 @@ export interface BundleEntryRequest {
  */
 export interface BundleEntryResponse {
     id?: string;
+    fullUrl?: string;
     type: string;
     response: BundleResponse;
     resource?: BundleEntryResource;
@@ -126,6 +128,7 @@ export interface ErrorEntry {
  */
 export type BundleEntry = {
     id?: string;
+    fullUrl?: string;
     type: string;
     /** @deprecated Legacy claims location. Prefer resource.meta.claims. */
     meta?: BundleEntryMeta;

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

@@ -9,21 +9,45 @@
  *   compatibility readers, but new code must use the canonical key constants
  */
 export declare const CommunicationClaim: {
+    /** Communication category code (`system|code`). */
     readonly Category: "Communication.category";
+    /** FHIR Communication status. */
     readonly Status: "Communication.status";
+    /** Stable communication identifier. */
     readonly Identifier: "Communication.identifier";
+    /** Subject identifier (typically `did:web`). */
     readonly Subject: "Communication.subject";
+    /** Recipient identifier(s); CSV allowed. */
     readonly Recipient: "Communication.recipient";
+    /** Sender identifier. */
     readonly Sender: "Communication.sender";
+    /** Sent timestamp (ISO 8601 DateTime). */
     readonly Sent: "Communication.sent";
+    /** Human note text for the communication context. */
     readonly NoteText: "Communication.note-text";
+    /** Narrative text (short summary or body). */
     readonly Text: "Communication.text";
+    /** Related resource references; CSV allowed. */
     readonly ContentReference: "Communication.content-reference";
+    /** Content code (`system|code`) when payload is coded. */
     readonly ContentCode: "Communication.content-code";
+    /**
+     * Base64 encoded payload for attachment-based communication flows.
+     *
+     * Recommended lifecycle:
+     * - maintain the editable Bundle as object in memory
+     * - edit one active entry at a time (`fullUrl`, `resource`, `request`, ...)
+     * - re-serialize Bundle JSON to this claim after each save/update
+     * - treat this claim as derived data (never manual source of truth)
+     */
     readonly ContentAttachmentData: "Communication.content-attachment-data";
+    /** Attachment MIME type (`application/fhir+json`, `application/pdf`, ...). */
     readonly ContentAttachmentType: "Communication.content-attachment-type";
+    /** Attachment title for UI/readability contexts. */
     readonly ContentAttachmentTitle: "Communication.content-attachment-title";
+    /** External attachment URL when payload is not embedded. */
     readonly ContentAttachmentUrl: "Communication.content-attachment-url";
+    /** Parent communication thread/reference (`Communication.part-of`). */
     readonly PartOf: "Communication.part-of";
 };
 export type CommunicationClaimKey = typeof CommunicationClaim[keyof typeof CommunicationClaim];

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

@@ -12,20 +12,44 @@
  *   compatibility readers, but new code must use the canonical key constants
  */
 export const CommunicationClaim = {
+    /** Communication category code (`system|code`). */
     Category: 'Communication.category',
+    /** FHIR Communication status. */
     Status: 'Communication.status',
+    /** Stable communication identifier. */
     Identifier: 'Communication.identifier',
+    /** Subject identifier (typically `did:web`). */
     Subject: 'Communication.subject',
+    /** Recipient identifier(s); CSV allowed. */
     Recipient: 'Communication.recipient',
+    /** Sender identifier. */
     Sender: 'Communication.sender',
+    /** Sent timestamp (ISO 8601 DateTime). */
     Sent: 'Communication.sent',
+    /** Human note text for the communication context. */
     NoteText: 'Communication.note-text',
+    /** Narrative text (short summary or body). */
     Text: 'Communication.text',
+    /** Related resource references; CSV allowed. */
     ContentReference: 'Communication.content-reference',
+    /** Content code (`system|code`) when payload is coded. */
     ContentCode: 'Communication.content-code',
+    /**
+     * Base64 encoded payload for attachment-based communication flows.
+     *
+     * Recommended lifecycle:
+     * - maintain the editable Bundle as object in memory
+     * - edit one active entry at a time (`fullUrl`, `resource`, `request`, ...)
+     * - re-serialize Bundle JSON to this claim after each save/update
+     * - treat this claim as derived data (never manual source of truth)
+     */
     ContentAttachmentData: 'Communication.content-attachment-data',
+    /** Attachment MIME type (`application/fhir+json`, `application/pdf`, ...). */
     ContentAttachmentType: 'Communication.content-attachment-type',
+    /** Attachment title for UI/readability contexts. */
     ContentAttachmentTitle: 'Communication.content-attachment-title',
+    /** External attachment URL when payload is not embedded. */
     ContentAttachmentUrl: 'Communication.content-attachment-url',
+    /** Parent communication thread/reference (`Communication.part-of`). */
     PartOf: 'Communication.part-of'
 };

package/dist/models/interoperable-claims/medication-statement-claims.d.ts

@@ -5,9 +5,14 @@
 export declare const MedicationStatementClaim: {
     readonly Identifier: "MedicationStatement.identifier";
     readonly Subject: "MedicationStatement.subject";
+    readonly Patient: "MedicationStatement.patient";
     readonly Status: "MedicationStatement.status";
+    readonly Category: "MedicationStatement.category";
     readonly Effective: "MedicationStatement.effective";
     readonly Code: "MedicationStatement.code";
+    readonly Medication: "MedicationStatement.medication";
+    readonly PartOf: "MedicationStatement.part-of";
+    readonly Source: "MedicationStatement.source";
     readonly MedicationText: "MedicationStatement.medication-text";
     readonly Note: "MedicationStatement.note";
     readonly DosageInstruction: "MedicationStatement.dosage-instruction";

package/dist/models/interoperable-claims/medication-statement-claims.js

@@ -7,9 +7,14 @@
 export const MedicationStatementClaim = {
     Identifier: 'MedicationStatement.identifier',
     Subject: 'MedicationStatement.subject',
+    Patient: 'MedicationStatement.patient',
     Status: 'MedicationStatement.status',
+    Category: 'MedicationStatement.category',
     Effective: 'MedicationStatement.effective',
     Code: 'MedicationStatement.code',
+    Medication: 'MedicationStatement.medication',
+    PartOf: 'MedicationStatement.part-of',
+    Source: 'MedicationStatement.source',
     MedicationText: 'MedicationStatement.medication-text',
     Note: 'MedicationStatement.note',
     DosageInstruction: 'MedicationStatement.dosage-instruction',

package/dist/utils/bundle-query.d.ts

@@ -0,0 +1,35 @@
+import type { BundleEntry, BundleJsonApi } from '../models/bundle.js';
+export type BundleResourceIdFilters = Readonly<{
+    sections?: string | readonly string[];
+    resourceTypes?: string | readonly string[];
+    dateFrom?: string;
+    dateTo?: string;
+}>;
+/**
+ * Generic bundle query helper for reusable entry filtering and lookup.
+ *
+ * This utility is intentionally communication-agnostic and can be reused by
+ * any package that works with BundleJsonApi payloads.
+ */
+export declare class BundleQuery {
+    private readonly bundle;
+    constructor(bundle: BundleJsonApi<BundleEntry>);
+    /**
+     * Returns stable resource IDs from bundle entries with optional filters.
+     */
+    getResourceIds(filters?: BundleResourceIdFilters): string[];
+    /**
+     * Returns bundle entries matching resource IDs produced by `getResourceIds`.
+     */
+    getResourceEntriesByIds(resourceIds: readonly string[]): BundleEntry[];
+    /**
+     * Resolves the entry URL (`fullUrl`) for a given entry/resource identifier.
+     */
+    getEntryUrl(entryId: string): string | undefined;
+    private resolveBundleEntryId;
+    private resolveIdentifierFromClaims;
+    private matchesResourceFilters;
+    private matchesSections;
+    private resolveEntryDate;
+    private matchesDateRange;
+}