gdc-common-utils-ts 2.9.26 → 2.9.28

package/dist/constants/identity-identifiers.d.ts

@@ -31,6 +31,21 @@ export declare const HL7_V2_0203_IDENTIFIER_CODES: Readonly<{
     readonly DonorRecord: "DR";
     readonly PatientIdentifier: "PI";
 }>;
+/**
+ * HL7 v2-0203 organization identifier codes used by governed legal identities.
+ *
+ * `BN` is a governed extension for jurisdictions whose official legal identifier
+ * is a business number. It is intentionally kept separate from the HL7 codes.
+ */
+export declare const HL7_V2_0203_ORGANIZATION_IDENTIFIER_CODES: Readonly<{
+    readonly TaxIdentifier: "TAX";
+    readonly EmployerNumber: "EN";
+}>;
+export declare const GovernedOrganizationIdentifierCodes: Readonly<{
+    readonly BusinessNumber: "BN";
+    readonly TaxIdentifier: "TAX";
+    readonly EmployerNumber: "EN";
+}>;
 export type Hl7V20203IdentifierCode = typeof HL7_V2_0203_IDENTIFIER_CODES[keyof typeof HL7_V2_0203_IDENTIFIER_CODES];
 /**
  * Private identifier types accepted when deriving an opaque hosted-individual

package/dist/constants/identity-identifiers.js

@@ -31,6 +31,20 @@ export const HL7_V2_0203_IDENTIFIER_CODES = Object.freeze({
     DonorRecord: 'DR',
     PatientIdentifier: 'PI',
 });
+/**
+ * HL7 v2-0203 organization identifier codes used by governed legal identities.
+ *
+ * `BN` is a governed extension for jurisdictions whose official legal identifier
+ * is a business number. It is intentionally kept separate from the HL7 codes.
+ */
+export const HL7_V2_0203_ORGANIZATION_IDENTIFIER_CODES = Object.freeze({
+    TaxIdentifier: 'TAX',
+    EmployerNumber: 'EN',
+});
+export const GovernedOrganizationIdentifierCodes = Object.freeze({
+    ...HL7_V2_0203_ORGANIZATION_IDENTIFIER_CODES,
+    BusinessNumber: 'BN',
+});
 /**
  * Private identifier types accepted when deriving an opaque hosted-individual
  * multihash. These values govern normalization only and are never serialized

package/dist/examples/inter-tenant-access-contract.js

@@ -1,15 +1,14 @@
 // Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
 import { ServiceCapability } from '../constants/service-capabilities.js';
-import { HealthcareConsentPurposes, ISCO08_CODING_SYSTEM } from '../constants/healthcare.js';
-import { SecureIdTypesIndividual } from '../constants/identity-identifiers.js';
+import { HealthcareActorRoleCodes, HealthcareConsentPurposes } from '../constants/healthcare.js';
 import { DataspaceSectors } from '../constants/sectors.js';
 import { ClaimConsent } from '../models/consent-rule.js';
 import { ClaimInterTenantAccessContract } from '../models/inter-tenant-access-contract.js';
 import { BundleEntryClaimsContext } from '../models/communication-attached-bundle-session.js';
 import { buildInterTenantAccessContractCredential, buildInterTenantAccessContractResource, getInterTenantAccessContractBlockchainReference, } from '../utils/inter-tenant-access-contract.js';
-import { buildOrganizationAuthorizationUrnCds, buildOrganizationMemberAuthorizationUrnCds, } from '../utils/organization-authorization-urn.js';
-import { buildProfessionalDidWeb, buildSecureIdValueMember } from '../utils/did.js';
-import { EXAMPLE_API_ORGANIZATION_DID, EXAMPLE_CONTROLLER_DID, EXAMPLE_HEALTHCARE_ACTOR_ROLE_PHYSICIAN, EXAMPLE_JURISDICTION, EXAMPLE_RESEARCH_API_ORGANIZATION_DID, EXAMPLE_RESEARCH_TENANT_IDENTIFIER, EXAMPLE_SECTOR, EXAMPLE_TENANT_IDENTIFIER, } from './shared.js';
+import { buildOrganizationAuthorizationUrnCds, buildOrganizationEmployeeAuthorizationUrnCds, } from '../utils/organization-authorization-urn.js';
+import { buildProfessionalDidWeb } from '../utils/did.js';
+import { EXAMPLE_API_ORGANIZATION_DID, EXAMPLE_CONTROLLER_DID, EXAMPLE_HEALTHCARE_ACTOR_ROLE_PHYSICIAN, EXAMPLE_JURISDICTION, EXAMPLE_KYC_CONTROLLER_USER_UUID, EXAMPLE_RESEARCH_API_ORGANIZATION_DID, EXAMPLE_RESEARCH_TENANT_IDENTIFIER, EXAMPLE_SECTOR, EXAMPLE_TENANT_IDENTIFIER, } from './shared.js';
 /**
  * Shared synthetic inter-tenant contract fixtures reused by GW and SDK tests.
  *
@@ -112,14 +111,10 @@ export const EXAMPLE_INTER_TENANT_ACCESS_CONTRACT_CONSUMER_ORGANIZATION_URN = bu
     identifierType: 'TAX',
     identifierValue: EXAMPLE_RESEARCH_TENANT_IDENTIFIER,
 });
-export const EXAMPLE_INTER_TENANT_ACCESS_CONTRACT_CONSUMER_MEMBER_URN = buildOrganizationMemberAuthorizationUrnCds({
+export const EXAMPLE_INTER_TENANT_ACCESS_CONTRACT_CONSUMER_MEMBER_URN = buildOrganizationEmployeeAuthorizationUrnCds({
     organizationUrn: EXAMPLE_INTER_TENANT_ACCESS_CONTRACT_CONSUMER_ORGANIZATION_URN,
-    memberId: buildSecureIdValueMember({
-        secureIdTypeMember: SecureIdTypesIndividual.Email,
-        privateIdValueMember: EXAMPLE_INTER_TENANT_ACCESS_CONTRACT_CONSUMER_PROFESSIONAL_EMAIL,
-    }),
-    roleType: ISCO08_CODING_SYSTEM,
-    roleValue: EXAMPLE_HEALTHCARE_ACTOR_ROLE_PHYSICIAN,
+    employeeUuid: EXAMPLE_KYC_CONTROLLER_USER_UUID,
+    roleCode: HealthcareActorRoleCodes.GeneralistMedicalPractitioner,
 });
 export const EXAMPLE_INTER_TENANT_ACCESS_CONTRACT_CONTEXT_WITH_URNS = Object.freeze({
     ...EXAMPLE_INTER_TENANT_ACCESS_CONTRACT_CONTEXT,

package/dist/examples/shared.js

@@ -8,13 +8,13 @@ import { ResourceTypesFhirR4 } from '../constants/fhir-resource-types.js';
 import { BirthSex, GenderIdentity } from '../constants/identity-gender.js';
 import { IdKind, SecureIdTypesIndividual } from '../constants/identity-identifiers.js';
 import { HL7_CODING_SYSTEM_V3_ROLE_CODE } from '../constants/hl7-roles.js';
-import { HealthcareActorRoles, HealthcareBasicSections, HealthcareConsentPurposes, HealthcareDocumentTypes, ISCO08_CODING_SYSTEM, } from '../constants/healthcare.js';
+import { HealthcareActorRoleCodes, HealthcareActorRoles, HealthcareBasicSections, HealthcareConsentPurposes, HealthcareDocumentTypes, } from '../constants/healthcare.js';
 import { CommunicationCategoryCodes } from '../constants/communication.js';
 import { LOINC_SYSTEM_URL } from '../models/clinical-sections.js';
 import { CommunicationClaim } from '../models/interoperable-claims/communication-claims.js';
 import { buildHostedProviderDidWeb, buildIndividualDidWeb, buildIndividualMemberDidWeb, buildSecureIdValueIndividual, buildSecureIdValueMember, buildProfessionalDidWeb, buildProviderSectorDidWeb, } from '../utils/did.js';
 import { encodeHexToMultibase58btc } from '../utils/multibase58.js';
-import { buildOrganizationAuthorizationUrnCds, buildOrganizationMemberAuthorizationUrnCds, } from '../utils/organization-authorization-urn.js';
+import { buildOrganizationAuthorizationUrnCds, buildOrganizationEmployeeAuthorizationUrnCds, } from '../utils/organization-authorization-urn.js';
 import { MedicationStatementClaim, MedicationStatementClaimsFhirApiExtended, } from '../models/interoperable-claims/medication-statement-claims.js';
 import { medicationStatementFlatToFhirR4 } from '../utils/clinical-resource-converters.js';
 /**
@@ -265,14 +265,10 @@ export const EXAMPLE_HEALTHCARE_ACTOR_ROLE_RECEPTIONIST = 'ISCO-08|4226';
 export const EXAMPLE_HEALTHCARE_ROLE_PHYSICIAN_TEXT = 'physician';
 export const EXAMPLE_INDIVIDUAL_CONTROLLER_ROLE_TYPE = HL7_CODING_SYSTEM_V3_ROLE_CODE;
 export const EXAMPLE_INDIVIDUAL_CONTROLLER_ROLE_VALUE = EXAMPLE_ORGANIZATION_CONTROLLER_ROLE;
-export const EXAMPLE_PROFESSIONAL_AUTHORIZATION_URN_CDS = buildOrganizationMemberAuthorizationUrnCds({
+export const EXAMPLE_PROFESSIONAL_AUTHORIZATION_URN_CDS = buildOrganizationEmployeeAuthorizationUrnCds({
     organizationUrn: EXAMPLE_PROVIDER_ORGANIZATION_AUTHORIZATION_URN_CDS,
-    memberId: buildSecureIdValueMember({
-        secureIdTypeMember: SecureIdTypesIndividual.Email,
-        privateIdValueMember: EXAMPLE_EMAIL_PROFESSIONAL,
-    }),
-    roleType: ISCO08_CODING_SYSTEM,
-    roleValue: HealthcareActorRoles.GeneralistMedicalPractitioner,
+    employeeUuid: EXAMPLE_KYC_CONTROLLER_USER_UUID,
+    roleCode: HealthcareActorRoleCodes.GeneralistMedicalPractitioner,
 });
 export const EXAMPLE_RELATED_PERSON_ROLE = 'v3-RoleCode|RESPRSN';
 export const EXAMPLE_SECURE_ID_VALUE_INDIVIDUAL = buildSecureIdValueIndividual({

package/dist/utils/clinical-resource-view.js

@@ -576,8 +576,19 @@ function resolveDate(resourceType, claims, resource) {
             AllergyIntoleranceClaimsFhirApi.OnsetDateTime,
         ]) || resolveFhirDate(resourceType, resource);
     }
+    const resourceDate = readCanonicalClaimValue(claims, `${resourceType}.date`);
+    if (resourceDate)
+        return resourceDate;
+    if (resourceType === ResourceTypesFhirR4.Observation) {
+        const effectiveDateTime = readCanonicalClaimValue(claims, ObservationClaim.EffectiveDateTime);
+        if (effectiveDateTime)
+            return effectiveDateTime;
+    }
+    const nativeDate = resolveFhirDate(resourceType, resource);
+    if (nativeDate)
+        return nativeDate;
     const genericDate = findBySuffix(claims, '.date');
-    return genericDate || resolveFhirDate(resourceType, resource) || undefined;
+    return genericDate || undefined;
 }
 function resolvePeriodStart(resourceType, claims, resource) {
     if (resourceType === ResourceTypesFhirR4.Consent) {

package/dist/utils/organization-authorization-urn.d.ts

@@ -8,7 +8,7 @@ export type OrganizationAuthorizationUrnCdsInput = Readonly<{
     jurisdiction: string;
     /** Version of the stable CDS identifier grammar. Defaults to v1. */
     version?: string;
-    /** Governed legal identifier type such as TAX, EIN or BN. */
+    /** Governed legal identifier type such as TAX, EN or BN. */
     identifierType: string;
     /** Canonical value issued by that jurisdiction's identifier authority. */
     identifierValue: string;
@@ -22,6 +22,14 @@ export type OrganizationMemberAuthorizationUrnCdsInput = Readonly<{
     /** Coded role value serialized as the final compact path segment. */
     roleValue: string;
 }>;
+export type OrganizationEmployeeAuthorizationUrnCdsInput = Readonly<{
+    /** Existing canonical organization URN. Its official identifier is preserved byte-for-byte. */
+    organizationUrn: string;
+    /** Employee UUID, either bare or prefixed with `urn:uuid:`. */
+    employeeUuid: string;
+    /** Bare ISCO-08 code. The fixed coding system is implicit in this grammar. */
+    roleCode: string;
+}>;
 export type MemberAuthorizationUrnInput = Readonly<{
     organizationUrn?: string;
     identifierType?: string;
@@ -52,7 +60,7 @@ export declare function buildOrganizationAuthorizationUrn(input: OrganizationAut
  * Format:
  * `urn:cds-<jurisdiction>:<version>:organization:<identifier-type>:<identifier-value>`
  *
- * Jurisdiction is mandatory because identifier schemes such as BN, EIN and
+ * Jurisdiction is mandatory because identifier schemes such as BN, EN and
  * TAX are interpreted by different national/subnational authorities.
  */
 export declare function buildOrganizationAuthorizationUrnCds(input: OrganizationAuthorizationUrnCdsInput): string;
@@ -62,6 +70,17 @@ export declare function buildOrganizationAuthorizationUrnCds(input: Organization
  * the compact role convention used by member did:web paths.
  */
 export declare function buildOrganizationMemberAuthorizationUrnCds(input: OrganizationMemberAuthorizationUrnCdsInput): string;
+/**
+ * Appends an employee identity and role to an existing legal-organization URN.
+ *
+ * Format:
+ * `urn:cds-<jurisdiction>:v1:organization:<type>:<official-id>:member:<uuid-base58btc>:<isco-08-code>`
+ *
+ * The UUID is encoded from its 16 raw bytes. It is neither hashed nor encoded
+ * from its textual representation. The organization URN is never rebuilt or
+ * lowercased, so the authority-issued legal identifier remains unchanged.
+ */
+export declare function buildOrganizationEmployeeAuthorizationUrnCds(input: OrganizationEmployeeAuthorizationUrnCdsInput): string;
 /**
  * Accepts either the legacy `TYPE|VALUE` input or an already-canonical
  * `urn:org:...` identifier and always returns the canonical URN form.

package/dist/utils/organization-authorization-urn.js

@@ -1,5 +1,6 @@
 // Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
 import { ClaimsOrganizationSchemaorg } from '../constants/schemaorg.js';
+import { encodeHexToMultibase58btc } from './multibase58.js';
 const ORGANIZATION_URN_PREFIX = 'urn:org:';
 const CDS_ORGANIZATION_URN_PATTERN = /^urn:cds-([a-z]{2}(?:-[a-z0-9]{2,3})?):(v[1-9][0-9]*):organization:([a-z][a-z0-9-]*):([^:]+)$/;
 const BARE_MULTIBASE_PATTERN = /^z[1-9A-HJ-NP-Za-km-z]+$/;
@@ -38,7 +39,7 @@ export function buildOrganizationAuthorizationUrn(input) {
  * Format:
  * `urn:cds-<jurisdiction>:<version>:organization:<identifier-type>:<identifier-value>`
  *
- * Jurisdiction is mandatory because identifier schemes such as BN, EIN and
+ * Jurisdiction is mandatory because identifier schemes such as BN, EN and
  * TAX are interpreted by different national/subnational authorities.
  */
 export function buildOrganizationAuthorizationUrnCds(input) {
@@ -78,6 +79,36 @@ export function buildOrganizationMemberAuthorizationUrnCds(input) {
     }
     return `${organizationUrn}:member:${memberId}:${roleValue}`;
 }
+/**
+ * Appends an employee identity and role to an existing legal-organization URN.
+ *
+ * Format:
+ * `urn:cds-<jurisdiction>:v1:organization:<type>:<official-id>:member:<uuid-base58btc>:<isco-08-code>`
+ *
+ * The UUID is encoded from its 16 raw bytes. It is neither hashed nor encoded
+ * from its textual representation. The organization URN is never rebuilt or
+ * lowercased, so the authority-issued legal identifier remains unchanged.
+ */
+export function buildOrganizationEmployeeAuthorizationUrnCds(input) {
+    const organizationUrn = String(input.organizationUrn || '').trim();
+    const employeeUuid = String(input.employeeUuid || '').trim().replace(/^urn:uuid:/i, '');
+    const roleCode = String(input.roleCode || '').trim();
+    if (!CDS_ORGANIZATION_URN_PATTERN.test(organizationUrn)) {
+        throw new Error('CDS employee authorization URN requires a canonical CDS organization URN.');
+    }
+    if (!/^[0-9a-f]{8}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{12}$/i.test(employeeUuid)) {
+        throw new Error('CDS employee authorization URN requires an employee UUID.');
+    }
+    if (!/^[0-9]+$/.test(roleCode)) {
+        throw new Error('CDS employee authorization URN requires a bare ISCO-08 role code.');
+    }
+    return buildOrganizationMemberAuthorizationUrnCds({
+        organizationUrn,
+        memberId: encodeHexToMultibase58btc(employeeUuid),
+        roleType: 'ISCO-08',
+        roleValue: roleCode,
+    });
+}
 /**
  * Accepts either the legacy `TYPE|VALUE` input or an already-canonical
  * `urn:org:...` identifier and always returns the canonical URN form.

package/package.json

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