gdc-common-utils-ts 2.8.6 → 2.8.8

package/README.md

@@ -417,6 +417,9 @@ The canonical API contract should live in JSDoc on exported code. The README act
   - Use instead of inline resource type strings.
 - [`CommunicationCategoryCodes`](src/constants/communication.ts)
   - Canonical `Communication.category` coding descriptors and `<system>|<code>` claims.
+  - Exactly the four FHIR R4 categories; use `CommunicationTopicCodes.BreakTheGlass`
+    for the HL7 v3 ActReason `BTG` topic and LOINC catalogs for clinical
+    section/document topics. See [Communication Layering 101](docs/101-COMMUNICATION_LAYERING.md).
 - [`ObservationCategoryCodes`, `VitalSignsCodes`, `VitalSignsUnits`](src/constants/vital-signs.ts)
   - Canonical Vital Signs category, code, and UCUM unit descriptors for `Observation`.
 - [`HealthcareSummarySections`, `HealthcareCoreSections`, `HealthcareAllSections`](src/constants/healthcare.ts)
@@ -522,6 +525,12 @@ The canonical API contract should live in JSDoc on exported code. The README act
   - The base token examples are read-only; richer scenario fixtures intentionally add `organization/Consent.cruds`.
 - [`src/examples/related-person.ts`](src/examples/related-person.ts)
   - RelatedPerson/family-member examples.
+- [`buildFhirIpsCreatorProvenance(...)`](src/utils/fhir-ips-creator-identity.ts)
+  and [`docs/101-DIDCOMM-IDENTITY-BOUNDARY.md`](docs/101-DIDCOMM-IDENTITY-BOUNDARY.md)
+  - Keep `Composition.author`, `Composition.attester`, DIDComm sender and
+    signing key separate. A member-created fact may use the registered
+    RelatedPerson as both author and personal attester; a dictated
+    individual-created fact keeps the individual as author.
 - [`src/examples/frontend-session.ts`](src/examples/frontend-session.ts)
   - Frontend profile/session bootstrap examples.
 - [`src/examples/lifecycle.ts`](src/examples/lifecycle.ts)

package/dist/constants/communication.d.ts

@@ -10,6 +10,11 @@ export type CommunicationCategoryDescriptor = Readonly<{
      */
     claim: string;
 }>;
+/**
+ * The complete FHIR R4 Communication category value set.
+ *
+ * @see https://www.hl7.org/fhir/valueset-communication-category.html
+ */
 export declare const CommunicationCategoryCodes: Readonly<{
     readonly Alert: Readonly<{
         system: typeof HL7_COMMUNICATION_CATEGORY_SYSTEM;
@@ -56,3 +61,23 @@ export declare const CommunicationCategoryCodes: Readonly<{
         claim: string;
     }>;
 }>;
+export type CommunicationTopicDescriptor = Readonly<{
+    system: string;
+    code: string;
+    attributeValue: string;
+}>;
+/**
+ * Non-LOINC Communication topics explicitly governed by an HL7 code system.
+ * Clinical section and document topics continue to use the LOINC catalogs.
+ *
+ * `BTG` is the HL7 v3 ActReason override purpose used for break-glass alerts.
+ * @see http://terminology.hl7.org/CodeSystem/v3-ActReason#v3-ActReason-BTG
+ * @see https://profiles.ihe.net/ITI/PCF/Consent-ex-consent-advanced-normal-break-glass-restricted.json.html
+ */
+export declare const CommunicationTopicCodes: Readonly<{
+    readonly BreakTheGlass: Readonly<{
+        system: string;
+        code: string;
+        attributeValue: string;
+    }>;
+}>;

package/dist/constants/communication.js

@@ -1,4 +1,5 @@
-export const HL7_COMMUNICATION_CATEGORY_SYSTEM = 'http://terminology.hl7.org/CodeSystem/communication-category';
+import { FhirCodeSystems } from './fhir-code-systems.js';
+export const HL7_COMMUNICATION_CATEGORY_SYSTEM = FhirCodeSystems.CommunicationCategory;
 function defineCommunicationCategory(code) {
     const attributeValue = `${HL7_COMMUNICATION_CATEGORY_SYSTEM}|${code}`;
     return Object.freeze({
@@ -8,9 +9,28 @@ function defineCommunicationCategory(code) {
         claim: attributeValue,
     });
 }
+/**
+ * The complete FHIR R4 Communication category value set.
+ *
+ * @see https://www.hl7.org/fhir/valueset-communication-category.html
+ */
 export const CommunicationCategoryCodes = Object.freeze({
     Alert: defineCommunicationCategory('alert'),
     Notification: defineCommunicationCategory('notification'),
     Reminder: defineCommunicationCategory('reminder'),
     Instruction: defineCommunicationCategory('instruction'),
 });
+function defineCommunicationTopic(system, code) {
+    return Object.freeze({ system, code, attributeValue: `${system}|${code}` });
+}
+/**
+ * Non-LOINC Communication topics explicitly governed by an HL7 code system.
+ * Clinical section and document topics continue to use the LOINC catalogs.
+ *
+ * `BTG` is the HL7 v3 ActReason override purpose used for break-glass alerts.
+ * @see http://terminology.hl7.org/CodeSystem/v3-ActReason#v3-ActReason-BTG
+ * @see https://profiles.ihe.net/ITI/PCF/Consent-ex-consent-advanced-normal-break-glass-restricted.json.html
+ */
+export const CommunicationTopicCodes = Object.freeze({
+    BreakTheGlass: defineCommunicationTopic(FhirCodeSystems.ActReason, 'BTG'),
+});

package/dist/constants/fhir-code-systems.d.ts

@@ -9,6 +9,7 @@ export declare const FhirCodeSystems: Readonly<{
     readonly SnomedCt: "http://snomed.info/sct";
     readonly Ucum: "http://unitsofmeasure.org";
     readonly CommunicationCategory: "http://terminology.hl7.org/CodeSystem/communication-category";
+    readonly ActReason: "http://terminology.hl7.org/CodeSystem/v3-ActReason";
     readonly ObservationCategory: "http://terminology.hl7.org/CodeSystem/observation-category";
     readonly EventTiming: "http://hl7.org/fhir/event-timing";
 }>;

package/dist/constants/fhir-code-systems.js

@@ -9,6 +9,7 @@ export const FhirCodeSystems = Object.freeze({
     SnomedCt: 'http://snomed.info/sct',
     Ucum: 'http://unitsofmeasure.org',
     CommunicationCategory: 'http://terminology.hl7.org/CodeSystem/communication-category',
+    ActReason: 'http://terminology.hl7.org/CodeSystem/v3-ActReason',
     ObservationCategory: 'http://terminology.hl7.org/CodeSystem/observation-category',
     EventTiming: 'http://hl7.org/fhir/event-timing',
 });

package/dist/examples/license.d.ts

@@ -237,6 +237,9 @@ export declare const EXAMPLE_EMPLOYEE_LIFECYCLE_RECORD: Readonly<{
             clientId: "client-employee-primary" | "client-employee-secondary";
             name: "installation-employee-primary" | "installation-employee-secondary" | "Shared browser profile";
             status: "active" | "revoked";
+            ownerContact: string;
+            ownerContactKind: "email";
+            activatedAt: 1786570800 | 1786570900;
         }>[];
     }>;
 }>;

package/dist/examples/license.js

@@ -171,6 +171,9 @@ export const EXAMPLE_EMPLOYEE_LIFECYCLE_RECORD = Object.freeze({
                 || binding.deviceInfo.clientInstanceId
                 || binding.clientId,
             status: binding.status,
+            ownerContact: EXAMPLE_EMPLOYEE_CONTROLLER_ACTIVE.email,
+            ownerContactKind: 'email',
+            activatedAt: binding.activatedAt,
         }))),
     }),
 });

package/dist/models/organization-employee-lifecycle.d.ts

@@ -5,6 +5,12 @@ export type OrganizationEmployeeDeviceRecord = Readonly<{
     clientId: string;
     name: string;
     status: DeviceBindingStatus;
+    /** Verified licensed contact that owns this installation. */
+    ownerContact?: string;
+    /** Contact channel represented by `ownerContact`. */
+    ownerContactKind?: 'email' | 'phone';
+    /** DCR activation time as Unix epoch seconds. */
+    activatedAt?: number;
 }>;
 /** License state attached to one employee directory entry. */
 export type OrganizationEmployeeLicenseRecord = Readonly<{

package/dist/utils/fhir-ips-creator-identity.d.ts

@@ -32,7 +32,12 @@ export type FhirIpsCreatorAuthor = Readonly<{
     entries: readonly FhirIpsCreatorBundleEntry[];
 }>;
 export type FhirIpsCreatorProvenanceInput = FhirIpsCreatorAuthorInput & Readonly<{
-    /** Explicit source originator; defaults to organization, subject, or oneself by creator kind. */
+    /**
+     * Explicit source originator. Defaults to the owning organization or
+     * individual. When the authenticated member/professional actually authored
+     * the content, pass its registered RelatedPerson/PractitionerRole assignment
+     * reference; that same assignment may also remain the attester.
+     */
     compositionAuthorReference?: string;
     /** Defaults to professional for employees and personal for individual members. */
     attesterMode?: CompositionAttesterMode;
@@ -53,10 +58,13 @@ export type FhirIpsCreatorProvenance = Readonly<{
 /**
  * Builds source authorship separately from the person or role that attests it.
  *
- * Defaults model the ordinary delegated flows: an organization's professional
- * attests an organization-authored record, while a member/caregiver attests a
- * subject-authored record. `compositionAuthorReference` remains explicit for
- * imports and cases where the actual originator differs from those defaults.
+ * Defaults model delegated flows: an organization's professional attests an
+ * organization-authored record, while a member/caregiver attests a
+ * subject-authored record. For content actually created by that authenticated
+ * member or professional, set `compositionAuthorReference` to its registered
+ * RelatedPerson or PractitionerRole assignment. Author and attester may then
+ * intentionally reference the same assignment; neither is the transport
+ * sender or signing key.
  */
 export declare function buildFhirIpsCreatorProvenance(input: FhirIpsCreatorProvenanceInput): FhirIpsCreatorProvenance;
 /**

package/dist/utils/fhir-ips-creator-identity.js

@@ -11,10 +11,13 @@ export const FhirIpsCreatorKinds = Object.freeze({
 /**
  * Builds source authorship separately from the person or role that attests it.
  *
- * Defaults model the ordinary delegated flows: an organization's professional
- * attests an organization-authored record, while a member/caregiver attests a
- * subject-authored record. `compositionAuthorReference` remains explicit for
- * imports and cases where the actual originator differs from those defaults.
+ * Defaults model delegated flows: an organization's professional attests an
+ * organization-authored record, while a member/caregiver attests a
+ * subject-authored record. For content actually created by that authenticated
+ * member or professional, set `compositionAuthorReference` to its registered
+ * RelatedPerson or PractitionerRole assignment. Author and attester may then
+ * intentionally reference the same assignment; neither is the transport
+ * sender or signing key.
  */
 export function buildFhirIpsCreatorProvenance(input) {
     if (input.kind === FhirIpsCreatorKinds.IndividualSubject) {

package/dist/utils/organization-employee-lifecycle.js

@@ -74,21 +74,33 @@ export function projectOrganizationEmployeeLifecycle(input) {
         const claims = record(employee.claims) || record(record(employee.meta)?.claims) || {};
         const resourceId = text(employee.id);
         const employeeDid = text(claims[ClaimsPersonSchemaorg.identifier]);
+        const employeeEmail = text(claims[ClaimsPersonSchemaorg.email]);
+        const employeeRole = text(claims[ClaimsPersonSchemaorg.hasOccupationalRoleValue]);
         const license = licenses.find((candidate) => {
             const meta = record(candidate.meta) || {};
             const subjectId = text(meta.subjectId);
-            return subjectId === resourceId || subjectId === employeeDid;
+            if (subjectId === resourceId || subjectId === employeeDid)
+                return true;
+            const licenseClaims = record(meta.claims) || record(candidate.claims) || {};
+            return Boolean(employeeEmail && employeeRole
+                && text(licenseClaims[ClaimsPersonSchemaorg.email]).toLowerCase() === employeeEmail.toLowerCase()
+                && text(licenseClaims[ClaimsPersonSchemaorg.hasOccupationalRoleValue]) === employeeRole);
         });
         const status = normalizeEmployeeDirectoryStatus(text(employee.status) || text(record(employee.meta)?.status));
         if (!license)
             return {
                 resourceId,
-                email: text(claims[ClaimsPersonSchemaorg.email]),
-                roleCode: text(claims[ClaimsPersonSchemaorg.hasOccupationalRoleValue]),
+                email: employeeEmail,
+                roleCode: employeeRole,
                 employeeDid,
                 status,
             };
         const meta = record(license.meta) || {};
+        const licenseClaims = record(meta.claims) || record(license.claims) || {};
+        const licensedEmail = text(licenseClaims[ClaimsPersonSchemaorg.email]) || employeeEmail;
+        const licensedPhone = text(licenseClaims[ClaimsPersonSchemaorg.telephone]);
+        const ownerContact = licensedEmail || licensedPhone;
+        const ownerContactKind = licensedEmail ? 'email' : licensedPhone ? 'phone' : undefined;
         const bindings = Array.isArray(meta.deviceBindings) ? meta.deviceBindings.map(record).filter(isRecord) : [];
         const devices = bindings.map((binding) => {
             const info = record(binding.deviceInfo) || {};
@@ -99,12 +111,15 @@ export function projectOrganizationEmployeeLifecycle(input) {
                 status: binding.status === DeviceBindingStatuses.Revoked
                     ? DeviceBindingStatuses.Revoked
                     : DeviceBindingStatuses.Active,
+                ...(ownerContact ? { ownerContact } : {}),
+                ...(ownerContactKind ? { ownerContactKind } : {}),
+                ...(positiveNumber(binding.activatedAt) ? { activatedAt: positiveNumber(binding.activatedAt) } : {}),
             };
         }).filter((device) => Boolean(device.clientId));
         return {
             resourceId,
-            email: text(claims[ClaimsPersonSchemaorg.email]),
-            roleCode: text(claims[ClaimsPersonSchemaorg.hasOccupationalRoleValue]),
+            email: employeeEmail,
+            roleCode: employeeRole,
             employeeDid,
             status,
             license: {
@@ -156,3 +171,7 @@ function positiveInteger(value) {
     const parsed = Number(value);
     return Number.isInteger(parsed) && parsed > 0 ? parsed : undefined;
 }
+function positiveNumber(value) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}

package/dist/utils/service-act-reasons.d.ts

@@ -1,4 +1,4 @@
-export declare const HL7_ACT_REASON_CODE_SYSTEM = "http://terminology.hl7.org/CodeSystem/v3-ActReason";
+export declare const HL7_ACT_REASON_CODE_SYSTEM: "http://terminology.hl7.org/CodeSystem/v3-ActReason";
 export type ServiceActReasonCoding = Readonly<{
     system: string;
     code: string;

package/dist/utils/service-act-reasons.js

@@ -1,5 +1,6 @@
 // Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
-export const HL7_ACT_REASON_CODE_SYSTEM = 'http://terminology.hl7.org/CodeSystem/v3-ActReason';
+import { FhirCodeSystems } from '../constants/fhir-code-systems.js';
+export const HL7_ACT_REASON_CODE_SYSTEM = FhirCodeSystems.ActReason;
 function normalizeText(value) {
     return typeof value === 'string' ? value.trim() : '';
 }

package/package.json

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