gdc-common-utils-ts 2.2.2 → 2.3.1

package/dist/utils/communication-consent-access-editor.d.ts

@@ -4,11 +4,15 @@ import type { CommunicationAttachedBundleSessionOptions, ConsentEditorClassified
 import type { ConsentDuplicateRuleConflict } from './consent-duplicate-rules';
 import { CommunicationAttachedBundleSession } from './communication-attached-bundle-session';
 /**
- * High-level consent-access editor alias for onboarding and app-facing code.
+ * High-level access-policy editor for onboarding and app-facing code.
  *
- * This keeps the business intent explicit for developers who are editing
- * Consent access rules inside a Communication-carried bundle and should not
- * need to start from the lower-level generic session name.
+ * This edits permit/deny rules governing who may access which data, for which
+ * purpose and scope, inside a Communication-carried bundle. It does not model
+ * informed consent for a clinical procedure, treatment or intervention.
+ *
+ * The name deliberately separates authorization consent from clinical
+ * intervention consent while retaining the FHIR-like `Consent` resource used
+ * by the existing access-rule contract.
  */
 export declare class ConsentAccessEditor extends CommunicationAttachedBundleSession {
     /** Returns duplicate atomic consent-rule conflicts across the current bundle. */

package/dist/utils/communication-consent-access-editor.js

@@ -7,11 +7,15 @@ import { detectDuplicateConsentRuleConflicts } from './consent-duplicate-rules.j
 import { CommunicationAttachedBundleSession } from './communication-attached-bundle-session.js';
 import { asTrimmedString, buildClassifiedConsentTarget, buildConsentViewModel, buildSectionCatalogOptions, classifyConsentActors, classifyConsentPurposes, classifyConsentRoles, classifyConsentTargetsFromClaims, CSV_SEPARATOR, flattenClassifiedActors, flattenClassifiedRoles, flattenClassifiedTargets, normalizeCsvValues, splitCsv, } from './communication-attached-bundle-session-helpers.js';
 /**
- * High-level consent-access editor alias for onboarding and app-facing code.
+ * High-level access-policy editor for onboarding and app-facing code.
  *
- * This keeps the business intent explicit for developers who are editing
- * Consent access rules inside a Communication-carried bundle and should not
- * need to start from the lower-level generic session name.
+ * This edits permit/deny rules governing who may access which data, for which
+ * purpose and scope, inside a Communication-carried bundle. It does not model
+ * informed consent for a clinical procedure, treatment or intervention.
+ *
+ * The name deliberately separates authorization consent from clinical
+ * intervention consent while retaining the FHIR-like `Consent` resource used
+ * by the existing access-rule contract.
  */
 export class ConsentAccessEditor extends CommunicationAttachedBundleSession {
     /** Returns duplicate atomic consent-rule conflicts across the current bundle. */

package/dist/utils/condition-entry-editor.js

@@ -28,7 +28,7 @@ export class ConditionEntryEditor extends ClinicalResourceEntryEditor {
     getOnsetDateTime() { return this.getScalarClaim(ConditionClaim.OnsetDateTime); }
     setRecorder(reference) { return this.setScalarClaim(ConditionClaim.Recorder, reference); }
     getRecorder() { return this.getScalarClaim(ConditionClaim.Recorder); }
-    setContainedDocumentIdentifierList(identifiers) { return this.setCsvClaimList(ConditionClaim.ContainedDocuments, identifiers); }
-    getContainedDocumentIdentifierList() { return this.getCsvClaimList(ConditionClaim.ContainedDocuments); }
+    setContainedDocumentIdentifierList(identifiers) { return this.setCsvClaimList(ConditionClaim.ContainedReferenceList, identifiers); }
+    getContainedDocumentIdentifierList() { return this.getCsvClaimList(ConditionClaim.ContainedReferenceList); }
 }
 registerBundleEntryEditor(BundleEditableResourceTypes.condition, ConditionEntryEditor);

package/dist/utils/consent-duplicate-rules.js

@@ -205,7 +205,7 @@ function normalizeConsentRoleForRuleKey(value) {
         return `org.hl7.terminology.codesystem.v3-rolecode.${code}`;
     }
     if (system === 'v3-personalrelationshiproletype') {
-        return `org.hl7.v3.personalrelationship.${code}`;
+        return `org.hl7.terminology.codesystem.v3-rolecode.${code}`;
     }
     return claim.toLowerCase();
 }

package/dist/utils/did.d.ts

@@ -71,7 +71,7 @@ export declare function extractTenantIdFromHostedDidWeb(did: string): string | u
  * Builds the canonical hosted provider DID root used by hosted tenant services.
  *
  * Canonical form:
- * `did:web:<host.domain>:<sector>;organization:taxid:<provider-tax-id>`
+ * `did:web:<host.domain>:<sector>:organization:taxid:<provider-tax-id>`
  *
  * This is the provider-scoped DID root under which hosted individual and member
  * identities are published. Downstream individual DIDs extend this root with
@@ -167,7 +167,7 @@ export declare function buildProfessionalDidWeb(input: {
  *
  * Canonical supported forms:
  * - hosted:
- *   `did:web:<host.domain>:<sector>;organization:taxid:<provider-tax-id>:individual:multibase:<individualId>`
+ *   `did:web:<host.domain>:<sector>:organization:taxid:<provider-tax-id>:individual:multibase:<individualId>`
  * - external/provider-domain:
  *   `did:web:<sector.provider.domain>:individual:multibase:<individualId>`
  *

package/dist/utils/did.js

@@ -137,7 +137,7 @@ export function extractTenantIdFromHostedDidWeb(did) {
  * Builds the canonical hosted provider DID root used by hosted tenant services.
  *
  * Canonical form:
- * `did:web:<host.domain>:<sector>;organization:taxid:<provider-tax-id>`
+ * `did:web:<host.domain>:<sector>:organization:taxid:<provider-tax-id>`
  *
  * This is the provider-scoped DID root under which hosted individual and member
  * identities are published. Downstream individual DIDs extend this root with
@@ -153,7 +153,7 @@ export function buildHostedProviderDidWeb(input) {
         throw new Error('buildHostedProviderDidWeb requires sector.');
     if (!providerTaxId)
         throw new Error('buildHostedProviderDidWeb requires providerTaxId.');
-    return `did:web:${hostDomain}:${sector};organization:taxid:${providerTaxId}`;
+    return `did:web:${hostDomain}:${sector}:organization:taxid:${providerTaxId}`;
 }
 /**
  * Builds the canonical public provider DID root used by an external provider domain.
@@ -269,7 +269,7 @@ export function buildProfessionalDidWeb(input) {
  *
  * Canonical supported forms:
  * - hosted:
- *   `did:web:<host.domain>:<sector>;organization:taxid:<provider-tax-id>:individual:multibase:<individualId>`
+ *   `did:web:<host.domain>:<sector>:organization:taxid:<provider-tax-id>:individual:multibase:<individualId>`
  * - external/provider-domain:
  *   `did:web:<sector.provider.domain>:individual:multibase:<individualId>`
  *

package/dist/utils/license-list-search.d.ts

@@ -8,9 +8,11 @@ import { buildLicenseSearchEntry, type LicenseClaims, type LicenseSearchInput, t
 export type LicenseListSearchState = Readonly<{
     serialNumbers?: readonly string[];
     email?: string;
+    telephone?: string;
     role?: string;
     status?: LicenseStatus;
     subjectId?: string;
+    ownerOrganizationId?: string;
     userClass?: string;
     type?: string;
     active?: boolean;
@@ -28,6 +30,7 @@ export type LicenseListRecord = Readonly<{
     id?: string;
     status?: string;
     subjectId?: string;
+    ownerOrganizationId?: string;
     email?: string;
     role?: string;
     category?: string;
@@ -66,6 +69,8 @@ export declare class LicenseListSearchEditor {
     setRole(value: string): this;
     setStatus(value: LicenseStatus): this;
     setSubjectId(value: string): this;
+    /** Limits results to the organization that owns the seat pool. */
+    setOwnerOrganizationId(value: string): this;
     setUserClass(value: string): this;
     setAppType(value: string): this;
     setActive(value: boolean): this;

package/dist/utils/license-list-search.js

@@ -15,6 +15,7 @@ function cloneDraft(state) {
         role: normalizeText(state?.role),
         status: state?.status,
         subjectId: normalizeText(state?.subjectId),
+        ownerOrganizationId: normalizeText(state?.ownerOrganizationId),
         userClass: normalizeText(state?.userClass),
         type: normalizeText(state?.type),
         active: typeof state?.active === 'boolean' ? state.active : undefined,
@@ -71,6 +72,11 @@ export class LicenseListSearchEditor {
         this.draft = cloneDraft({ ...this.draft, subjectId: value });
         return this;
     }
+    /** Limits results to the organization that owns the seat pool. */
+    setOwnerOrganizationId(value) {
+        this.draft = cloneDraft({ ...this.draft, ownerOrganizationId: value });
+        return this;
+    }
     setUserClass(value) {
         this.draft = cloneDraft({ ...this.draft, userClass: value });
         return this;
@@ -117,6 +123,7 @@ export class LicenseListSearchEditor {
             ...(this.draft.role ? { role: this.draft.role } : {}),
             ...(resolveStatus(this.draft) ? { status: resolveStatus(this.draft) } : {}),
             ...(this.draft.subjectId ? { subjectId: this.draft.subjectId } : {}),
+            ...(this.draft.ownerOrganizationId ? { ownerOrganizationId: this.draft.ownerOrganizationId } : {}),
             additionalClaims: cloneClaims(this.draft.additionalClaims),
         };
     }
@@ -151,7 +158,9 @@ export function readLicenseListRecords(body) {
                 || entry.id),
             status: normalizeText(meta.status),
             subjectId: normalizeText(meta.subjectId),
+            ownerOrganizationId: normalizeText(meta.ownerOrganizationId || claims['License.ownerOrganizationId']),
             email: normalizeText(claims[ClaimsPersonSchemaorg.email]),
+            telephone: normalizeText(claims[ClaimsPersonSchemaorg.telephone]),
             role: normalizeText(claims[ClaimsPersonSchemaorg.hasOccupationalRoleValue]),
             category: normalizeText(claims[ClaimsIndividualProductSchemaorg.category]),
             appType: normalizeText(claims[ClaimsIndividualProductSchemaorg.additionalType]),

package/dist/utils/license.d.ts

@@ -54,11 +54,44 @@ export declare const LicenseStatuses: Readonly<{
     readonly Inactive: "inactive";
 }>;
 export type LicenseStatus = typeof LicenseStatuses[keyof typeof LicenseStatuses];
+/**
+ * Role families that decide which organization owns the actor's license.
+ *
+ * This classification is deliberately independent from Consent. A person may
+ * receive permissions in either case, but only a FHIR v3 relationship role is
+ * a member of the individual's organization and consumes its seat pool.
+ */
+export declare const LicenseRoleKinds: Readonly<{
+    readonly IndividualMember: "individual-member";
+    readonly Professional: "professional";
+    readonly Unsupported: "unsupported";
+}>;
+export type LicenseRoleKind = typeof LicenseRoleKinds[keyof typeof LicenseRoleKinds];
+/**
+ * Classifies one canonical or compatibility role token for license ownership.
+ *
+ * Rules:
+ * - FHIR/HL7 v3 `RoleCode` actors are non-employee members of the individual
+ *   organization and consume one of its licenses.
+ * - ISCO/ISCO-08 actors are professionals. Their employer/organization owns
+ *   their professional license, so a patient's individual pool is untouched.
+ * - Unknown role systems are not silently charged to either pool.
+ */
+export declare function classifyLicenseRole(role: string): LicenseRoleKind;
 export type LicenseIssueInput = Readonly<{
-    email: string;
+    email?: string;
+    telephone?: string;
     role: string;
     userClass?: DeviceUserClass;
     type?: DeviceAppType;
+    /** Individual/legal organization that owns the seat pool. */
+    ownerOrganizationId?: string;
+    /** Card/individual DID granted by the invitation after acceptance. */
+    subjectDid?: string;
+    /** Existing RelatedPerson/contact selected before the invitation. */
+    relatedPersonId?: string;
+    /** Stable invitation workflow identifier; not the license id or code. */
+    invitationId?: string;
     additionalClaims?: LicenseClaims;
 }>;
 export type LicensePurchaseInput = Readonly<{
@@ -66,6 +99,10 @@ export type LicensePurchaseInput = Readonly<{
     userClass?: DeviceUserClass;
     type?: DeviceAppType;
     serialNumbers?: readonly string[];
+    price?: number;
+    priceCurrency?: string;
+    /** Organization whose pool receives the newly materialized seats. */
+    ownerOrganizationId?: string;
     additionalClaims?: LicenseClaims;
 }>;
 export type LicenseSearchInput = Readonly<{
@@ -76,6 +113,7 @@ export type LicenseSearchInput = Readonly<{
     role?: string;
     status?: LicenseStatus;
     subjectId?: string;
+    ownerOrganizationId?: string;
     additionalClaims?: LicenseClaims;
 }>;
 /**
@@ -106,6 +144,10 @@ export declare function buildLicenseIssueEntry(input: LicenseIssueInput): {
     };
     meta: {
         claims: LicenseClaims;
+        ownerOrganizationId?: string;
+        subjectDid?: string;
+        relatedPersonId?: string;
+        invitationId?: string;
     };
 };
 /**
@@ -130,6 +172,7 @@ export declare function buildLicensePurchaseEntry(input: LicensePurchaseInput):
     };
     meta: {
         claims: LicenseClaims;
+        ownerOrganizationId?: string;
     };
 };
 /**
@@ -151,5 +194,6 @@ export declare function buildLicenseSearchEntry(input: LicenseSearchInput): {
         claims: LicenseClaims;
         status?: LicenseStatus;
         subjectId?: string;
+        ownerOrganizationId?: string;
     };
 };

package/dist/utils/license.js

@@ -52,6 +52,47 @@ export const LicenseStatuses = Object.freeze({
     Active: 'active',
     Inactive: 'inactive',
 });
+/**
+ * Role families that decide which organization owns the actor's license.
+ *
+ * This classification is deliberately independent from Consent. A person may
+ * receive permissions in either case, but only a FHIR v3 relationship role is
+ * a member of the individual's organization and consumes its seat pool.
+ */
+export const LicenseRoleKinds = Object.freeze({
+    IndividualMember: 'individual-member',
+    Professional: 'professional',
+    Unsupported: 'unsupported',
+});
+/**
+ * Classifies one canonical or compatibility role token for license ownership.
+ *
+ * Rules:
+ * - FHIR/HL7 v3 `RoleCode` actors are non-employee members of the individual
+ *   organization and consume one of its licenses.
+ * - ISCO/ISCO-08 actors are professionals. Their employer/organization owns
+ *   their professional license, so a patient's individual pool is untouched.
+ * - Unknown role systems are not silently charged to either pool.
+ */
+export function classifyLicenseRole(role) {
+    const normalized = String(role || '').trim().toLowerCase();
+    if (!normalized)
+        return LicenseRoleKinds.Unsupported;
+    const system = normalized.includes('|') ? normalized.split('|', 1)[0] : normalized;
+    if (system === 'isco'
+        || system === 'isco-08'
+        || system === 'org.ilo.isco'
+        || system === 'org.ilo.isco-08'
+        || system.endsWith('/isco-08')) {
+        return LicenseRoleKinds.Professional;
+    }
+    if (system === 'v3-rolecode'
+        || system === 'org.hl7.v3.rolecode'
+        || system.endsWith('/v3-rolecode')) {
+        return LicenseRoleKinds.IndividualMember;
+    }
+    return LicenseRoleKinds.Unsupported;
+}
 function cloneClaims(claims) {
     return { ...(claims || {}) };
 }
@@ -82,12 +123,31 @@ export function serializeLicenseSerialNumbers(serialNumbers) {
  * - seat/app semantics come from `IndividualProduct.*`
  */
 export function buildLicenseIssueClaims(input) {
+    const email = String(input.email || '').trim();
+    const telephone = String(input.telephone || '').trim();
+    if (!email && !telephone) {
+        throw new Error('License issue requires an email or telephone recipient.');
+    }
+    if (telephone && !/^\+[1-9]\d{6,14}$/.test(telephone)) {
+        throw new Error('License issue telephone must use an international ITU format beginning with +.');
+    }
+    const userClass = input.userClass || DeviceUserClasses.Employee;
+    if (userClass === DeviceUserClasses.Individual) {
+        const roleKind = classifyLicenseRole(input.role);
+        if (roleKind === LicenseRoleKinds.Professional) {
+            throw new Error('ISCO professional roles do not consume individual-member licenses.');
+        }
+        if (roleKind !== LicenseRoleKinds.IndividualMember) {
+            throw new Error('Individual-member licenses require a FHIR v3-RoleCode role.');
+        }
+    }
     const claims = {
         '@context': LicenseClaimContext.SchemaOrg,
         ...cloneClaims(input.additionalClaims),
-        [ClaimsPersonSchemaorg.email]: input.email.trim(),
+        ...(email ? { [ClaimsPersonSchemaorg.email]: email } : {}),
+        ...(telephone ? { [ClaimsPersonSchemaorg.telephone]: telephone } : {}),
         [ClaimsPersonSchemaorg.hasOccupationalRoleValue]: input.role.trim(),
-        [ClaimsIndividualProductSchemaorg.category]: mapLicenseCategoryFromUserClass(input.userClass || DeviceUserClasses.Employee),
+        [ClaimsIndividualProductSchemaorg.category]: mapLicenseCategoryFromUserClass(userClass),
         [ClaimsIndividualProductSchemaorg.additionalType]: input.type || DeviceAppTypes.Mobile,
     };
     return claims;
@@ -104,6 +164,18 @@ export function buildLicenseIssueEntry(input) {
                 ...buildLicenseIssueClaims(input),
                 '@type': LicenseEntryOperations.Issue,
             },
+            ...(String(input.ownerOrganizationId || '').trim()
+                ? { ownerOrganizationId: String(input.ownerOrganizationId).trim() }
+                : {}),
+            ...(String(input.subjectDid || '').trim()
+                ? { subjectDid: String(input.subjectDid).trim() }
+                : {}),
+            ...(String(input.relatedPersonId || '').trim()
+                ? { relatedPersonId: String(input.relatedPersonId).trim() }
+                : {}),
+            ...(String(input.invitationId || '').trim()
+                ? { invitationId: String(input.invitationId).trim() }
+                : {}),
         },
     };
 }
@@ -129,6 +201,12 @@ export function buildLicensePurchaseClaims(input) {
     if (serializedSerialNumbers) {
         claims[ClaimsOfferSchemaorg.serialNumber] = serializedSerialNumbers;
     }
+    if (typeof input.price === 'number' && Number.isFinite(input.price) && input.price >= 0) {
+        claims[ClaimsOfferSchemaorg.price] = input.price;
+    }
+    if (typeof input.priceCurrency === 'string' && input.priceCurrency.trim()) {
+        claims[ClaimsOfferSchemaorg.priceCurrency] = input.priceCurrency.trim().toUpperCase();
+    }
     return claims;
 }
 /**
@@ -144,6 +222,9 @@ export function buildLicensePurchaseEntry(input) {
                 ...buildLicensePurchaseClaims(input),
                 '@type': LicenseEntryOperations.Purchase,
             },
+            ...(String(input.ownerOrganizationId || '').trim()
+                ? { ownerOrganizationId: String(input.ownerOrganizationId).trim() }
+                : {}),
         },
     };
 }
@@ -189,6 +270,9 @@ export function buildLicenseSearchEntry(input) {
             ...(typeof input.subjectId === 'string' && input.subjectId.trim()
                 ? { subjectId: input.subjectId.trim() }
                 : {}),
+            ...(typeof input.ownerOrganizationId === 'string' && input.ownerOrganizationId.trim()
+                ? { ownerOrganizationId: input.ownerOrganizationId.trim() }
+                : {}),
         },
     };
 }

package/dist/utils/related-person-list.d.ts

@@ -2,11 +2,15 @@ export type RelatedPersonListRecord = Readonly<{
     identifier?: string;
     patient?: string;
     relationship?: string;
+    /** Functional `RelatedPerson.role` extension values, separate from kinship. */
+    roles: readonly string[];
     name?: string;
     telecom?: string;
     active?: string;
     status?: string;
     resourceId?: string;
+    relatedEntityType?: string;
+    actorIdentifiers: readonly string[];
     claims: Record<string, unknown>;
 }>;
 export type RelatedPersonListSelection = Readonly<{

package/dist/utils/related-person-list.js

@@ -12,6 +12,17 @@ function extractClaims(entry) {
     const resourceClaims = resourceMeta.claims && typeof resourceMeta.claims === 'object' ? resourceMeta.claims : undefined;
     return { ...(resourceClaims || {}), ...(metaClaims || {}) };
 }
+function readClaim(claims, claimKey) {
+    if (claims[claimKey] !== undefined)
+        return claims[claimKey];
+    const context = normalizeText(claims['@context']);
+    if (context && claims[`${context.replace(/\.$/, '')}.${claimKey}`] !== undefined) {
+        return claims[`${context.replace(/\.$/, '')}.${claimKey}`];
+    }
+    const suffix = `.${claimKey}`;
+    const matchedKey = Object.keys(claims).find((key) => key.endsWith(suffix));
+    return matchedKey ? claims[matchedKey] : undefined;
+}
 /**
  * Reads subject-side relationship records from one current GW-style result
  * body into one neutral list shape for frontend screens.
@@ -29,14 +40,23 @@ export function readRelatedPersonListRecords(body) {
         const meta = entry.meta && typeof entry.meta === 'object' ? entry.meta : {};
         const resource = entry.resource && typeof entry.resource === 'object' ? entry.resource : {};
         return {
-            identifier: normalizeText(claims[RelatedPersonClaim.IdentifierValue] ?? claims[RelatedPersonClaim.Identifier]),
-            patient: normalizeText(claims[RelatedPersonClaim.Patient]),
-            relationship: normalizeText(claims[RelatedPersonClaim.Relationship]),
-            name: normalizeText(claims[RelatedPersonClaim.Name]),
-            telecom: normalizeText(claims[RelatedPersonClaim.Telecom]),
-            active: normalizeText(claims[RelatedPersonClaim.Active]),
+            identifier: normalizeText(readClaim(claims, RelatedPersonClaim.IdentifierValue) ?? readClaim(claims, RelatedPersonClaim.Identifier)),
+            patient: normalizeText(readClaim(claims, RelatedPersonClaim.Patient)),
+            relationship: normalizeText(readClaim(claims, RelatedPersonClaim.Relationship)),
+            roles: String(readClaim(claims, RelatedPersonClaim.Role) ?? '')
+                .split(',')
+                .map((value) => value.trim().toUpperCase())
+                .filter(Boolean),
+            name: normalizeText(readClaim(claims, RelatedPersonClaim.Name)),
+            telecom: normalizeText(readClaim(claims, RelatedPersonClaim.Telecom)),
+            active: normalizeText(readClaim(claims, RelatedPersonClaim.Active)),
             status: normalizeText(meta.status),
             resourceId: normalizeText(resource.id || entry.id),
+            relatedEntityType: normalizeText(readClaim(claims, RelatedPersonClaim.RelatedEntityType)),
+            actorIdentifiers: String(readClaim(claims, RelatedPersonClaim.ActorIdentifier) ?? '')
+                .split(',')
+                .map((value) => value.trim())
+                .filter(Boolean),
             claims,
         };
     });

package/package.json

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