gdc-common-utils-ts 2.2.2 → 2.3.1

package/dist/constants/healthcare.js

@@ -1,7 +1,8 @@
 import { LOINC_SYSTEM_URL, loincI18nKey } from '../models/clinical-sections.js';
 import { clinicalWorkbookSummaryLabelI18nEn } from '../models/clinical-workbook-summary.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 { 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';
+import { ResourceTypesFhirR4, } from './fhir-resource-types.js';
 /**
  * Canonical logical identifiers for document types backed by the LOINC
  * ontology. These keys are stable SDK-facing names; the concrete LOINC token
@@ -63,55 +64,63 @@ function workbookLabel(code) {
 function buildWorkbookSectionCatalog(codes) {
     return Object.freeze(Object.fromEntries(codes.map((code) => [code, defineSection(code, workbookLabel(code))])));
 }
-export const HealthcareCoreSections = Object.freeze({
-    PatientSummaryDocument: defineSection('60591-5', 'Patient summary document'),
+const planOfCareSection = defineSection('18776-5', 'Plan of care');
+const healthcareCoreSections = {
+    ProblemList: defineSection('11450-4', 'Problem list'),
     AllergiesAndIntolerances: defineSection('48765-2', 'Allergies and adverse reactions'),
-    Alert: defineSection('104605-1', 'Alert'),
-    DietAndNutrition: defineSection('61144-2', 'Diet and nutrition'),
     HistoryOfMedicationUse: defineSection('10160-0', 'History of medication use'),
-    HistoryOfFamilyMemberDiseases: defineSection('10157-6', 'History of family member diseases'),
-    HistoryOfHospitalizationsAndOutpatientVisits: defineSection('46240-8', 'History of hospitalizations+History of outpatient visits'),
-    HistoryOfPastIllness: defineSection('11348-0', 'History of past illness'),
-    HistoryOfPresentIllness: defineSection('10164-2', 'History of present illness'),
-    PregnancyHistory: defineSection('10162-6', 'Pregnancy History'),
-    ProblemList: defineSection('11450-4', 'Problem list'),
-    ProblemListNarrativeReported: defineSection('57852-6', 'Problem list'),
+    Immunizations: defineSection('11369-6', 'History of immunization'),
     Results: defineSection('30954-2', 'Relevant diagnostic tests/laboratory data'),
     Procedures: defineSection('47519-4', 'History of Procedures'),
-    Immunizations: defineSection('11369-6', 'History of immunization'),
     MedicalDevices: defineSection('46264-8', 'History of medical device use'),
-    FunctionalStatus: defineSection('47420-5', 'Functional status'),
-    GoalsAndPreferences: defineSection('81338-6', 'Goals / Preferences'),
-    PlanOfTreatment: defineSection('18776-5', 'Plan of treatment'),
-    /** @deprecated Use `PlanOfTreatment`. */
-    PlanOfCare: defineSection('18776-5', 'Plan of treatment'),
-    SocialHistory: defineSection('29762-2', 'Social history'),
     VitalSigns: defineSection('8716-3', 'Vital signs'),
+    SocialHistory: defineSection('29762-2', 'Social history'),
+    Alert: defineSection('104605-1', 'Alert'),
+    GoalsAndPreferences: defineSection('81338-6', 'Goals / Preferences'),
     AdvanceDirectives: defineSection('42348-3', 'Advance directives'),
+    FunctionalStatus: defineSection('47420-5', 'Functional status'),
+    HistoryOfPastIllness: defineSection('11348-0', 'History of past illness'),
+    PregnancyHistory: defineSection('10162-6', 'Pregnancy History'),
+    PlanOfCare: planOfCareSection,
+    DietAndNutrition: defineSection('61144-2', 'Diet and nutrition'),
+    HistoryOfFamilyMemberDiseases: defineSection('10157-6', 'History of family member diseases'),
+    HistoryOfHospitalizationsAndOutpatientVisits: defineSection('46240-8', 'History of hospitalizations+History of outpatient visits'),
+    HistoryOfPresentIllness: defineSection('10164-2', 'History of present illness'),
+    ProblemListNarrativeReported: defineSection('57852-6', 'Problem list'),
     Instructions: defineSection('69730-0', 'Instructions'),
-});
+};
+/**
+ * Application healthcare sections: the 16 IPS sections followed by six
+ * LOINC-coded extensions. Deprecated aliases remain accessible but are not
+ * enumerable, so section pickers and `HealthcareAllSections` do not duplicate
+ * the IPS document or plan-of-care entry.
+ */
+export const HealthcareCoreSections = Object.freeze(Object.defineProperties(healthcareCoreSections, {
+    PatientSummaryDocument: {
+        value: defineSection('60591-5', 'Patient summary document'),
+        enumerable: false,
+    },
+    PlanOfTreatment: {
+        value: planOfCareSection,
+        enumerable: false,
+    },
+}));
 /** @deprecated Use `HealthcareCoreSections`. */
 export const HealthcareBasicSections = HealthcareCoreSections;
 /**
- * IPS summary-oriented subset aligned with the official HL7 IPS all-sections
- * example and intended for "full patient summary / digital twin" flows.
+ * The 16 clinical sections from the official HL7 IPS 2.0 all-sections example.
+ * Order follows `Composition.section`. The `60591-5` IPS document descriptor
+ * is represented by `HealthcareDocumentTypes.IPS`, not as a section.
  *
- * It excludes the broader core sections that are outside that summary example:
- * - Diet and Nutrition
- * - History of Family Member Diseases
- * - History of Hospitalizations and Outpatient Visits
- * - History of Present Illness
- * - Problem List Narrative Reported
- * - Instructions
+ * @see https://hl7.org/fhir/uv/ips/STU2/Bundle-bundle-ips-all-sections.html
  */
 export const HealthcareSummarySections = Object.freeze({
-    PatientSummaryDocument: HealthcareCoreSections.PatientSummaryDocument,
+    ProblemList: HealthcareCoreSections.ProblemList,
     AllergiesAndIntolerances: HealthcareCoreSections.AllergiesAndIntolerances,
     HistoryOfMedicationUse: HealthcareCoreSections.HistoryOfMedicationUse,
-    ProblemList: HealthcareCoreSections.ProblemList,
+    Immunizations: HealthcareCoreSections.Immunizations,
     Results: HealthcareCoreSections.Results,
     Procedures: HealthcareCoreSections.Procedures,
-    Immunizations: HealthcareCoreSections.Immunizations,
     MedicalDevices: HealthcareCoreSections.MedicalDevices,
     VitalSigns: HealthcareCoreSections.VitalSigns,
     SocialHistory: HealthcareCoreSections.SocialHistory,
@@ -122,8 +131,61 @@ export const HealthcareSummarySections = Object.freeze({
     HistoryOfPastIllness: HealthcareCoreSections.HistoryOfPastIllness,
     PregnancyHistory: HealthcareCoreSections.PregnancyHistory,
     PlanOfCare: HealthcareCoreSections.PlanOfCare,
-    PlanOfTreatment: HealthcareCoreSections.PlanOfTreatment,
 });
+function defineIpsSectionResourceProfile(section, requirement, expectedResourceTypes, acceptsAnyResource) {
+    return Object.freeze({
+        section,
+        requirement,
+        expectedResourceTypes: Object.freeze([...expectedResourceTypes]),
+        acceptsOtherSupportingResources: true,
+        ...(acceptsAnyResource ? { acceptsAnyResource } : {}),
+    });
+}
+/**
+ * Resource-profile expectations for the 16 IPS 2.0 sections.
+ *
+ * Consumers must group a document by `Composition.section.entry` references;
+ * they must not infer a section from `resourceType` alone because the same
+ * type, especially Observation, is valid in several sections.
+ *
+ * @see https://hl7.org/fhir/uv/ips/STU2/Structure-of-the-International-Patient-Summary.html
+ * @see https://hl7.org/fhir/uv/ips/STU2/profiles.html
+ */
+export const HealthcareIpsSectionResourceProfiles = Object.freeze({
+    ProblemList: defineIpsSectionResourceProfile(HealthcareSummarySections.ProblemList, 'required', [ResourceTypesFhirR4.Condition]),
+    AllergiesAndIntolerances: defineIpsSectionResourceProfile(HealthcareSummarySections.AllergiesAndIntolerances, 'required', [ResourceTypesFhirR4.AllergyIntolerance]),
+    HistoryOfMedicationUse: defineIpsSectionResourceProfile(HealthcareSummarySections.HistoryOfMedicationUse, 'required', [
+        ResourceTypesFhirR4.MedicationStatement,
+        ResourceTypesFhirR4.MedicationRequest,
+        ResourceTypesFhirR4.Medication,
+    ]),
+    Immunizations: defineIpsSectionResourceProfile(HealthcareSummarySections.Immunizations, 'recommended', [ResourceTypesFhirR4.Immunization]),
+    Results: defineIpsSectionResourceProfile(HealthcareSummarySections.Results, 'recommended', [
+        ResourceTypesFhirR4.DiagnosticReport,
+        ResourceTypesFhirR4.Observation,
+        ResourceTypesFhirR4.Specimen,
+        ResourceTypesFhirR4.Device,
+        ResourceTypesFhirR4.ImagingStudy,
+    ]),
+    Procedures: defineIpsSectionResourceProfile(HealthcareSummarySections.Procedures, 'recommended', [ResourceTypesFhirR4.Procedure, ResourceTypesFhirR4.Device]),
+    MedicalDevices: defineIpsSectionResourceProfile(HealthcareSummarySections.MedicalDevices, 'recommended', [ResourceTypesFhirR4.DeviceUseStatement, ResourceTypesFhirR4.Device]),
+    VitalSigns: defineIpsSectionResourceProfile(HealthcareSummarySections.VitalSigns, 'optional', [ResourceTypesFhirR4.Observation]),
+    SocialHistory: defineIpsSectionResourceProfile(HealthcareSummarySections.SocialHistory, 'optional', [ResourceTypesFhirR4.Observation]),
+    Alert: defineIpsSectionResourceProfile(HealthcareSummarySections.Alert, 'optional', [ResourceTypesFhirR4.Flag]),
+    GoalsAndPreferences: defineIpsSectionResourceProfile(HealthcareSummarySections.GoalsAndPreferences, 'optional', [], true),
+    AdvanceDirectives: defineIpsSectionResourceProfile(HealthcareSummarySections.AdvanceDirectives, 'optional', [ResourceTypesFhirR4.Consent]),
+    FunctionalStatus: defineIpsSectionResourceProfile(HealthcareSummarySections.FunctionalStatus, 'optional', [ResourceTypesFhirR4.Condition, ResourceTypesFhirR4.ClinicalImpression]),
+    HistoryOfPastIllness: defineIpsSectionResourceProfile(HealthcareSummarySections.HistoryOfPastIllness, 'optional', [ResourceTypesFhirR4.Condition]),
+    PregnancyHistory: defineIpsSectionResourceProfile(HealthcareSummarySections.PregnancyHistory, 'optional', [ResourceTypesFhirR4.Observation]),
+    PlanOfCare: defineIpsSectionResourceProfile(HealthcareSummarySections.PlanOfCare, 'optional', [ResourceTypesFhirR4.CarePlan, ResourceTypesFhirR4.ImmunizationRecommendation]),
+});
+/** IPS profiles used across sections rather than owned by one section. */
+export const HealthcareIpsSharedResourceTypes = Object.freeze([
+    ResourceTypesFhirR4.Organization,
+    ResourceTypesFhirR4.Practitioner,
+    ResourceTypesFhirR4.PractitionerRole,
+    ResourceTypesFhirR4.DocumentReference,
+]);
 export const HealthcareDocumentTypes = Object.freeze({
     [DocumentTypeLoincOntology.IPS]: defineDocumentType(DocumentTypeLoincOntology.IPS, '60591-5', 'International Patient Summary'),
 });
@@ -413,10 +475,10 @@ function buildPersonalRelationshipRoles() {
         item.code,
         Object.freeze({
             family: HealthcareRoleFamilies.PersonalRelationshipHl7,
-            codingSystem: HL7_CODING_SYSTEM_PERSONAL_RELATIONSHIP,
+            codingSystem: HL7_CODING_SYSTEM_V3_ROLE_CODE,
             code: item.code,
-            claim: `v3-PersonalRelationshipRoleType|${item.code}`,
-            i18nKey: `org.hl7.v3.personalRelationship.${item.code}`,
+            claim: `v3-RoleCode|${item.code}`,
+            i18nKey: `org.hl7.terminology.CodeSystem.v3-RoleCode.${item.code}`,
             titleEn: item.display,
             definition: item.definition,
         }),
@@ -430,7 +492,7 @@ function buildLegalRepresentativeRoles() {
             codingSystem: HL7_CODING_SYSTEM_V3_ROLE_CODE,
             code: item.code,
             claim: `v3-RoleCode|${item.code}`,
-            i18nKey: `org.hl7.v3.roleCode.${item.code}`,
+            i18nKey: `org.hl7.terminology.CodeSystem.v3-RoleCode.${item.code}`,
             titleEn: item.display,
             definition: item.definition,
         }),

package/dist/constants/hl7-roles.d.ts

@@ -1,13 +1,13 @@
 /**
  * HL7 role constants shared across GDC projects.
  *
- * Two distinct value sets are provided:
+ * Two curated HL7 role families are exposed:
  *
- * 1. v3-PersonalRelationshipRoleType
+ * 1. personal relationship roles
  *    "Who are you in relation to the subject?" (family / social relationship)
  *    Source: http://terminology.hl7.org/ValueSet/v3-PersonalRelationshipRoleType
  *
- * 2. v3-RoleCode — legal / functional representative subset
+ * 2. legal / functional representative roles
  *    "What legal role do you exercise over the subject?" (guardian, attorney…)
  *    Source: http://terminology.hl7.org/ValueSet/v3-RoleCode
  *    Used as default for non-human subjects (e.g. animal-care sector).
@@ -19,7 +19,7 @@ export type Hl7RoleEntry = {
     definition: string;
 };
 export declare const HL7_CODING_SYSTEM_PERSONAL_RELATIONSHIP = "http://terminology.hl7.org/CodeSystem/v3-PersonalRelationshipRoleType";
-/** Canonical OID alias used in GDC claims (org.hl7.v3.RoleCode covers both sets). */
+/** Canonical GDC compatibility claim namespace used by legacy payloads. */
 export declare const HL7_CLAIMS_CODING_SYSTEM = "org.hl7.v3.RoleCode";
 /**
  * Full ordered list of HL7 v3-PersonalRelationshipRoleType entries.
@@ -27,7 +27,30 @@ export declare const HL7_CLAIMS_CODING_SYSTEM = "org.hl7.v3.RoleCode";
  * Default role: `ONESELF` (patient represents themselves).
  */
 export declare const HL7_PERSONAL_RELATIONSHIP_ROLES: Hl7RoleEntry[];
+/**
+ * Small, non-gender-forcing family-role catalog used by individual-member
+ * selectors. `FAMMEMB` is the safe fallback when no more specific relationship
+ * applies. The generic great-grandparent code is `GGRPRN`; `GGRFTH` means a
+ * male great-grandfather and therefore must not be used as its substitute.
+ */
+export declare const HL7_INDIVIDUAL_MEMBER_RELATIONSHIP_CODES: readonly ["FAMMEMB", "WIFE", "HUSB", "DOMPART", "SIS", "BRO", "SON", "DAU", "PRN", "GRPRN", "GRNDCHILD", "GGRPRN", "FRND", "NBOR", "ROOM"];
+export type Hl7IndividualMemberRelationshipCode = typeof HL7_INDIVIDUAL_MEMBER_RELATIONSHIP_CODES[number];
+/** Returns whether a code belongs to the intentionally simplified member picker. */
+export declare function isHl7IndividualMemberRelationshipCode(value: unknown): value is Hl7IndividualMemberRelationshipCode;
+/** Ordered descriptors for the individual/family member role selector. */
+export declare const HL7_INDIVIDUAL_MEMBER_RELATIONSHIP_ROLES: readonly Hl7RoleEntry[];
+/**
+ * Complete personal-relationship catalog. It is the extended picker surface:
+ * every entry from the compact individual-member catalog is included together
+ * with all more specific HL7 personal relationship choices.
+ */
+export declare const HL7_INDIVIDUAL_MEMBER_RELATIONSHIP_ROLES_FULL: readonly Hl7RoleEntry[];
 export declare const HL7_CODING_SYSTEM_V3_ROLE_CODE = "http://terminology.hl7.org/CodeSystem/v3-RoleCode";
+/** Canonical system for functional RelatedPerson role-class values. */
+export declare const HL7_CODING_SYSTEM_V3_ROLE_CLASS = "http://terminology.hl7.org/CodeSystem/v3-RoleClass";
+export type Hl7RelatedPersonFunctionalRoleEntry = Hl7RoleEntry & {
+    codingSystem: typeof HL7_CODING_SYSTEM_V3_ROLE_CODE | typeof HL7_CODING_SYSTEM_V3_ROLE_CLASS;
+};
 /**
  * Legal representative / guardian roles from HL7 v3-RoleCode.
  *
@@ -38,6 +61,17 @@ export declare const HL7_CODING_SYSTEM_V3_ROLE_CODE = "http://terminology.hl7.or
  * Default for animal-care sector: `RESPRSN` (Responsible party).
  */
 export declare const HL7_V3_ROLE_CODE_LEGAL_REPRESENTATIVE: Hl7RoleEntry[];
+/**
+ * Functional tags accepted by the GDC `RelatedPerson.role` flat-claim
+ * extension. They do not replace `RelatedPerson.relationship`: kinship belongs
+ * in `relationship`, while these comma-separated values describe an explicit
+ * operational or legal function. CAREGIVER/ECON/DEPEN use v3-RoleClass;
+ * RESPRSN/BILL/POWATT use v3-RoleCode. `POWATT` must only be assigned when a
+ * real power of attorney exists; it is never inferred from controller status.
+ * The bare CSV is resolved through the descriptors below when a Coding system
+ * is required.
+ */
+export declare const HL7_RELATED_PERSON_FUNCTIONAL_ROLES: readonly Hl7RelatedPersonFunctionalRoleEntry[];
 /** Default role code for animal-care and non-human subjects. */
 export declare const HL7_DEFAULT_ROLE_ANIMAL_CARE = "RESPRSN";
 /** Default role code for health sector (patient self-represents). */

package/dist/constants/hl7-roles.js

@@ -1,13 +1,13 @@
 /**
  * HL7 role constants shared across GDC projects.
  *
- * Two distinct value sets are provided:
+ * Two curated HL7 role families are exposed:
  *
- * 1. v3-PersonalRelationshipRoleType
+ * 1. personal relationship roles
  *    "Who are you in relation to the subject?" (family / social relationship)
  *    Source: http://terminology.hl7.org/ValueSet/v3-PersonalRelationshipRoleType
  *
- * 2. v3-RoleCode — legal / functional representative subset
+ * 2. legal / functional representative roles
  *    "What legal role do you exercise over the subject?" (guardian, attorney…)
  *    Source: http://terminology.hl7.org/ValueSet/v3-RoleCode
  *    Used as default for non-human subjects (e.g. animal-care sector).
@@ -17,9 +17,10 @@
 // 1. v3-PersonalRelationshipRoleType
 // ---------------------------------------------------------------------------
 export const HL7_CODING_SYSTEM_PERSONAL_RELATIONSHIP = 'http://terminology.hl7.org/CodeSystem/v3-PersonalRelationshipRoleType';
-/** Canonical OID alias used in GDC claims (org.hl7.v3.RoleCode covers both sets). */
+/** Canonical GDC compatibility claim namespace used by legacy payloads. */
 export const HL7_CLAIMS_CODING_SYSTEM = 'org.hl7.v3.RoleCode';
 const PERSONAL_RELATIONSHIP_LIST = [
+    { code: 'FAMMEMB', display: 'family member', definition: 'A relationship between two people characterizing their family association.' },
     { code: 'ONESELF', display: 'self', definition: 'The relationship that a person has with himself or herself.' },
     { code: 'CHILD', display: 'child', definition: 'The player of the role is a child of the scoping entity.' },
     { code: 'CHLDADOPT', display: 'adopted child', definition: 'The player of the role is a child taken into a family through legal means and raised by the scoping person as his or her own child.' },
@@ -162,10 +163,53 @@ export const HL7_PERSONAL_RELATIONSHIP_ROLES = [
     ..._personalPreferred,
     ..._personalRemaining,
 ];
+/**
+ * Small, non-gender-forcing family-role catalog used by individual-member
+ * selectors. `FAMMEMB` is the safe fallback when no more specific relationship
+ * applies. The generic great-grandparent code is `GGRPRN`; `GGRFTH` means a
+ * male great-grandfather and therefore must not be used as its substitute.
+ */
+export const HL7_INDIVIDUAL_MEMBER_RELATIONSHIP_CODES = [
+    'FAMMEMB',
+    'WIFE',
+    'HUSB',
+    'DOMPART',
+    'SIS',
+    'BRO',
+    'SON',
+    'DAU',
+    'PRN',
+    'GRPRN',
+    'GRNDCHILD',
+    'GGRPRN',
+    'FRND',
+    'NBOR',
+    'ROOM',
+];
+const _individualMemberRelationshipCodeSet = new Set(HL7_INDIVIDUAL_MEMBER_RELATIONSHIP_CODES);
+/** Returns whether a code belongs to the intentionally simplified member picker. */
+export function isHl7IndividualMemberRelationshipCode(value) {
+    return _individualMemberRelationshipCodeSet.has(String(value || '').trim().toUpperCase());
+}
+/** Ordered descriptors for the individual/family member role selector. */
+export const HL7_INDIVIDUAL_MEMBER_RELATIONSHIP_ROLES = HL7_INDIVIDUAL_MEMBER_RELATIONSHIP_CODES.map((code) => {
+    const descriptor = PERSONAL_RELATIONSHIP_LIST.find((entry) => entry.code === code);
+    if (!descriptor)
+        throw new Error(`Missing HL7 relationship descriptor for ${code}.`);
+    return descriptor;
+});
+/**
+ * Complete personal-relationship catalog. It is the extended picker surface:
+ * every entry from the compact individual-member catalog is included together
+ * with all more specific HL7 personal relationship choices.
+ */
+export const HL7_INDIVIDUAL_MEMBER_RELATIONSHIP_ROLES_FULL = HL7_PERSONAL_RELATIONSHIP_ROLES;
 // ---------------------------------------------------------------------------
 // 2. v3-RoleCode — legal / functional representative subset
 // ---------------------------------------------------------------------------
 export const HL7_CODING_SYSTEM_V3_ROLE_CODE = 'http://terminology.hl7.org/CodeSystem/v3-RoleCode';
+/** Canonical system for functional RelatedPerson role-class values. */
+export const HL7_CODING_SYSTEM_V3_ROLE_CLASS = 'http://terminology.hl7.org/CodeSystem/v3-RoleClass';
 /**
  * Legal representative / guardian roles from HL7 v3-RoleCode.
  *
@@ -202,6 +246,50 @@ export const HL7_V3_ROLE_CODE_LEGAL_REPRESENTATIVE = [
         definition: 'A relationship between two people in which one person acts on behalf of another even if the grantor becomes incapacitated.',
     },
 ];
+/**
+ * Functional tags accepted by the GDC `RelatedPerson.role` flat-claim
+ * extension. They do not replace `RelatedPerson.relationship`: kinship belongs
+ * in `relationship`, while these comma-separated values describe an explicit
+ * operational or legal function. CAREGIVER/ECON/DEPEN use v3-RoleClass;
+ * RESPRSN/BILL/POWATT use v3-RoleCode. `POWATT` must only be assigned when a
+ * real power of attorney exists; it is never inferred from controller status.
+ * The bare CSV is resolved through the descriptors below when a Coding system
+ * is required.
+ */
+export const HL7_RELATED_PERSON_FUNCTIONAL_ROLES = [
+    {
+        ...HL7_V3_ROLE_CODE_LEGAL_REPRESENTATIVE[0],
+        codingSystem: HL7_CODING_SYSTEM_V3_ROLE_CODE,
+    },
+    {
+        code: 'CAREGIVER',
+        display: 'Caregiver',
+        definition: 'A person responsible for the primary care of a patient at home.',
+        codingSystem: HL7_CODING_SYSTEM_V3_ROLE_CLASS,
+    },
+    {
+        code: 'ECON',
+        display: 'Emergency contact',
+        definition: 'A contact for use in an emergency.',
+        codingSystem: HL7_CODING_SYSTEM_V3_ROLE_CLASS,
+    },
+    {
+        code: 'DEPEN',
+        display: 'Dependent',
+        definition: 'A person covered under a policy or program based on an association with a subscriber.',
+        codingSystem: HL7_CODING_SYSTEM_V3_ROLE_CLASS,
+    },
+    {
+        code: 'BILL',
+        display: 'Billing contact',
+        definition: 'A contact used for billing in the applicable provider-organization context.',
+        codingSystem: HL7_CODING_SYSTEM_V3_ROLE_CODE,
+    },
+    {
+        ...HL7_V3_ROLE_CODE_LEGAL_REPRESENTATIVE[3],
+        codingSystem: HL7_CODING_SYSTEM_V3_ROLE_CODE,
+    },
+];
 /** Default role code for animal-care and non-human subjects. */
 export const HL7_DEFAULT_ROLE_ANIMAL_CARE = 'RESPRSN';
 /** Default role code for health sector (patient self-represents). */

package/dist/examples/shared.d.ts

@@ -131,7 +131,7 @@ export declare const EXAMPLE_PROVIDER_SECTOR_DID: string;
  *
  * There are two valid base roots:
  * - hosted provider root:
- *   `did:web:<host.domain>:<sector>;organization:taxid:<provider-tax-id>`
+ *   `did:web:<host.domain>:<sector>:organization:taxid:<provider-tax-id>`
  * - external provider custom-domain root:
  *   `did:web:<sector.provider.domain>`
  *

package/dist/examples/shared.js

@@ -156,7 +156,7 @@ export const EXAMPLE_PROVIDER_SECTOR_DID = EXAMPLE_PROVIDER_DOMAIN_DID;
  *
  * There are two valid base roots:
  * - hosted provider root:
- *   `did:web:<host.domain>:<sector>;organization:taxid:<provider-tax-id>`
+ *   `did:web:<host.domain>:<sector>:organization:taxid:<provider-tax-id>`
  * - external provider custom-domain root:
  *   `did:web:<sector.provider.domain>`
  *

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

@@ -1,4 +1,12 @@
-export type RoleCodeI18nKey = `org.ilo.isco-08.${string}` | `org.isco08.${string}` | `org.hl7.v3.personalRelationship.${string}` | `org.hl7.v3.roleCode.${string}`;
+export type RoleCodeI18nKey = `org.ilo.isco-08.${string}` | `org.isco08.${string}` | `org.hl7.terminology.CodeSystem.v3-RoleCode.${string}`
+/**
+ * @deprecated Use `org.hl7.terminology.CodeSystem.v3-RoleCode.<code>`.
+ */
+ | `org.hl7.v3.personalRelationship.${string}`
+/**
+ * @deprecated Use `org.hl7.terminology.CodeSystem.v3-RoleCode.<code>`.
+ */
+ | `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

@@ -6,7 +6,18 @@ function buildRoleCodeI18nMap() {
     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];
+    const legacyHl7Aliases = baseEntries
+        .filter(([key]) => key.startsWith('org.hl7.terminology.CodeSystem.v3-RoleCode.'))
+        .flatMap(([key, label]) => {
+        const suffix = key.replace('org.hl7.terminology.CodeSystem.v3-RoleCode.', '');
+        return [
+            /** @deprecated Compatibility alias for older consumers. */
+            [`org.hl7.v3.personalRelationship.${suffix}`, label],
+            /** @deprecated Compatibility alias for older consumers. */
+            [`org.hl7.v3.roleCode.${suffix}`, label],
+        ];
+    });
+    const entries = [...baseEntries, ...legacyIscoAliases, ...legacyHl7Aliases];
     return Object.freeze(Object.fromEntries(entries));
 }
 export const roleCodeI18nEn = buildRoleCodeI18nMap();

package/dist/models/device-license.d.ts

@@ -42,6 +42,16 @@ export interface DeviceLicense {
      * @example "acme"
      */
     tenantId: string;
+    /**
+     * Organization that owns this seat pool.
+     *
+     * This is essential for hosted individual organizations because many
+     * households can share one UNID tenant vault. It is distinct from
+     * `subjectId`, which identifies the member currently assigned to the seat.
+     */
+    ownerOrganizationId?: string;
+    /** Subject/card DID made accessible when this member invitation is accepted. */
+    authorizedSubjectDid?: string;
     /**
      * Identifier for the purchase order or invoice that generated this license.
      * All licenses created from the same purchase will share the same orderId.
@@ -116,6 +126,16 @@ export interface DeviceLicense {
      * Populated when the status becomes 'issued'.
      */
     subjectId?: string;
+    /** Verified email selected from the invited contact, when email is used. */
+    issuedToEmail?: string;
+    /** Verified ITU telephone selected from the invited contact, when phone is used. */
+    issuedToPhone?: string;
+    /** Canonical FHIR v3 or ISCO role used to choose the owning license pool. */
+    issuedToRole?: string;
+    /** Relationship invitation workflow that reserved this seat. */
+    invitationId?: string;
+    /** RelatedPerson/contact selected before the invitation was sent. */
+    relatedPersonId?: string;
     /**
      * The unique identifier (`client_id`) of the device registered with this license.
      * Populated when the status becomes 'active'.

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

@@ -12,7 +12,7 @@ export declare const InvoiceClaim: {
     readonly Date: "Invoice.date";
     /** Invoice lifecycle status. Example: `issued`. */
     readonly Status: "Invoice.status";
-    /** Subject or tenant context reference. Example: `did:web:host.example.com:health-care;organization:taxid:VATES-B00112233:individual:multibase:zExampleIndividualId`. */
+    /** Subject or tenant context reference. Example: `did:web:host.example.com:health-care:organization:taxid:VATES-B00112233:individual:multibase:zExampleIndividualId`. */
     readonly Subject: "Invoice.subject";
     /** Billed recipient reference. Example: `did:web:portal.example.org:billing`. */
     readonly Recipient: "Invoice.recipient";

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

@@ -13,7 +13,7 @@ export const InvoiceClaim = {
     Date: 'Invoice.date',
     /** Invoice lifecycle status. Example: `issued`. */
     Status: 'Invoice.status',
-    /** Subject or tenant context reference. Example: `did:web:host.example.com:health-care;organization:taxid:VATES-B00112233:individual:multibase:zExampleIndividualId`. */
+    /** Subject or tenant context reference. Example: `did:web:host.example.com:health-care:organization:taxid:VATES-B00112233:individual:multibase:zExampleIndividualId`. */
     Subject: 'Invoice.subject',
     /** Billed recipient reference. Example: `did:web:portal.example.org:billing`. */
     Recipient: 'Invoice.recipient',
@@ -156,7 +156,7 @@ export const InvoiceClaimSpecs = [
     {
         key: InvoiceClaim.Subject,
         meaning: 'Subject or tenant context reference.',
-        example: 'did:web:host.example.com:health-care;organization:taxid:VATES-B00112233:individual:multibase:zExampleIndividualId',
+        example: 'did:web:host.example.com:health-care:organization:taxid:VATES-B00112233:individual:multibase:zExampleIndividualId',
     },
     { key: InvoiceClaim.Recipient, meaning: 'Billed recipient reference.', example: 'did:web:portal.example.org:billing' },
     { key: InvoiceClaim.Issuer, meaning: 'Invoice issuer reference.', example: 'did:web:api.acme.org' },

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

@@ -72,7 +72,7 @@ export declare const ObservationClaim: {
     readonly Language: "Observation.language";
     /** Observation method token. Example: `http://snomed.info/sct|252465000`. */
     readonly Method: "Observation.method";
-    /** Optional compatibility alias of `Observation.subject`. Example: `did:web:host.example.com:health-care;organization:taxid:VATES-B00112233:individual:multibase:zExampleIndividualId`. */
+    /** Optional compatibility alias of `Observation.subject`. Example: `did:web:host.example.com:health-care:organization:taxid:VATES-B00112233:individual:multibase:zExampleIndividualId`. */
     readonly Patient: "Observation.patient";
     /** Performer reference list. Example: `Practitioner/prac-1`. */
     readonly Performer: "Observation.performer";
@@ -80,7 +80,7 @@ export declare const ObservationClaim: {
     readonly Specimen: "Observation.specimen";
     /** Observation status. Presence marks one visible/searchable main observation. Example: `final`. */
     readonly Status: "Observation.status";
-    /** Canonical subject reference. Example: `did:web:host.example.com:health-care;organization:taxid:VATES-B00112233:individual:multibase:zExampleIndividualId`. */
+    /** Canonical subject reference. Example: `did:web:host.example.com:health-care:organization:taxid:VATES-B00112233:individual:multibase:zExampleIndividualId`. */
     readonly Subject: "Observation.subject";
     /** Value as coded concept token. Example: `http://terminology.hl7.org/CodeSystem/data-absent-reason|not-performed`. */
     readonly ValueConcept: "Observation.value-concept";

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

@@ -74,7 +74,7 @@ export const ObservationClaim = {
     Language: 'Observation.language',
     /** Observation method token. Example: `http://snomed.info/sct|252465000`. */
     Method: 'Observation.method',
-    /** Optional compatibility alias of `Observation.subject`. Example: `did:web:host.example.com:health-care;organization:taxid:VATES-B00112233:individual:multibase:zExampleIndividualId`. */
+    /** Optional compatibility alias of `Observation.subject`. Example: `did:web:host.example.com:health-care:organization:taxid:VATES-B00112233:individual:multibase:zExampleIndividualId`. */
     Patient: 'Observation.patient',
     /** Performer reference list. Example: `Practitioner/prac-1`. */
     Performer: 'Observation.performer',
@@ -82,7 +82,7 @@ export const ObservationClaim = {
     Specimen: 'Observation.specimen',
     /** Observation status. Presence marks one visible/searchable main observation. Example: `final`. */
     Status: 'Observation.status',
-    /** Canonical subject reference. Example: `did:web:host.example.com:health-care;organization:taxid:VATES-B00112233:individual:multibase:zExampleIndividualId`. */
+    /** Canonical subject reference. Example: `did:web:host.example.com:health-care:organization:taxid:VATES-B00112233:individual:multibase:zExampleIndividualId`. */
     Subject: 'Observation.subject',
     /** Value as coded concept token. Example: `http://terminology.hl7.org/CodeSystem/data-absent-reason|not-performed`. */
     ValueConcept: 'Observation.value-concept',

package/dist/models/interoperable-claims/related-person-claims.d.ts

@@ -6,11 +6,24 @@ export declare const RelatedPersonClaim: {
     readonly Active: "RelatedPerson.active";
     readonly Patient: "RelatedPerson.patient";
     readonly Relationship: "RelatedPerson.relationship";
+    /**
+     * GDC flat-claim extension for comma-separated functional HL7 role codes.
+     * FHIR R4 RelatedPerson has no native `role` property; relationship/kinship
+     * remains in `RelatedPerson.relationship`.
+     */
+    readonly Role: "RelatedPerson.role";
     readonly Name: "RelatedPerson.name";
     readonly Telecom: "RelatedPerson.telecom";
     readonly Gender: "RelatedPerson.gender";
     readonly BirthDate: "RelatedPerson.birthdate";
     readonly Address: "RelatedPerson.address";
+    /** Logical kind used when a RelatedPerson record acts as a related entity. */
+    readonly RelatedEntityType: "RelatedPerson.related-entity-type";
+    /**
+     * Original public values used to calculate the Consent rule/asset id.
+     * These values must not be replaced by the opaque RelatedPerson resource id.
+     */
+    readonly ActorIdentifier: "RelatedPerson.actor-identifier";
 };
 export type RelatedPersonClaimKey = typeof RelatedPersonClaim[keyof typeof RelatedPersonClaim];
 export declare const RelatedPersonClaimSpecs: ClaimSpec[];

package/dist/models/interoperable-claims/related-person-claims.js

@@ -7,11 +7,24 @@ export const RelatedPersonClaim = {
     Active: 'RelatedPerson.active',
     Patient: 'RelatedPerson.patient',
     Relationship: 'RelatedPerson.relationship',
+    /**
+     * GDC flat-claim extension for comma-separated functional HL7 role codes.
+     * FHIR R4 RelatedPerson has no native `role` property; relationship/kinship
+     * remains in `RelatedPerson.relationship`.
+     */
+    Role: 'RelatedPerson.role',
     Name: 'RelatedPerson.name',
     Telecom: 'RelatedPerson.telecom',
     Gender: 'RelatedPerson.gender',
     BirthDate: 'RelatedPerson.birthdate',
     Address: 'RelatedPerson.address',
+    /** Logical kind used when a RelatedPerson record acts as a related entity. */
+    RelatedEntityType: 'RelatedPerson.related-entity-type',
+    /**
+     * Original public values used to calculate the Consent rule/asset id.
+     * These values must not be replaced by the opaque RelatedPerson resource id.
+     */
+    ActorIdentifier: 'RelatedPerson.actor-identifier',
 };
 export const RelatedPersonClaimSpecs = [
     { key: RelatedPersonClaim.IdentifierValue, meaning: 'Business identifier value.', example: 'rel-001' },
@@ -19,9 +32,12 @@ export const RelatedPersonClaimSpecs = [
     { key: RelatedPersonClaim.Active, meaning: 'Active flag.', example: 'true' },
     { key: RelatedPersonClaim.Patient, meaning: 'Linked patient reference.', example: 'did:web:patient.example.org' },
     { key: RelatedPersonClaim.Relationship, meaning: 'Relationship token.', example: 'http://terminology.hl7.org/CodeSystem/v3-RoleCode|MTH' },
+    { key: RelatedPersonClaim.Role, meaning: 'Comma-separated functional HL7 role values; this is a GDC flat-claim extension, not a native FHIR R4 RelatedPerson property. Known codes resolve to their canonical RoleClass or RoleCode system.', example: 'CAREGIVER,ECON,BILL' },
     { key: RelatedPersonClaim.Name, meaning: 'Display name.', example: 'Jane Doe' },
     { key: RelatedPersonClaim.Telecom, meaning: 'Contact value.', example: 'mailto:jane@example.org' },
     { key: RelatedPersonClaim.Gender, meaning: 'Administrative gender.', example: 'female' },
     { key: RelatedPersonClaim.BirthDate, meaning: 'Birth date.', example: '1980-02-01' },
     { key: RelatedPersonClaim.Address, meaning: 'Display address.', example: '123 Main St, Vancouver' },
+    { key: RelatedPersonClaim.RelatedEntityType, meaning: 'Logical related-entity kind.', example: 'country-set' },
+    { key: RelatedPersonClaim.ActorIdentifier, meaning: 'Original public Consent actor identifiers as CSV.', example: 'ES,PT' },
 ];

package/dist/utils/allergy-intolerance-entry-editor.js

@@ -48,8 +48,8 @@ export class AllergyIntoleranceEntryEditor extends ClinicalResourceEntryEditor {
     /** Reads the recorder reference. */
     getRecorder() { return this.getScalarClaim(AllergyIntoleranceClaim.Recorder); }
     /** Writes the linked contained-document identifier list. */
-    setContainedDocumentIdentifierList(identifiers) { return this.setCsvClaimList(AllergyIntoleranceClaim.ContainedDocuments, identifiers); }
+    setContainedDocumentIdentifierList(identifiers) { return this.setCsvClaimList(AllergyIntoleranceClaim.ContainedReferenceList, identifiers); }
     /** Reads the linked contained-document identifier list. */
-    getContainedDocumentIdentifierList() { return this.getCsvClaimList(AllergyIntoleranceClaim.ContainedDocuments); }
+    getContainedDocumentIdentifierList() { return this.getCsvClaimList(AllergyIntoleranceClaim.ContainedReferenceList); }
 }
 registerBundleEntryEditor(BundleEditableResourceTypes.allergyIntolerance, AllergyIntoleranceEntryEditor);