gdc-common-utils-ts 1.6.0 → 1.7.0

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

@@ -1,6 +1,19 @@
 // Copyright 2026 Conéctate 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.
 // File: src/models/interoperable-claims/communication-claims.ts
+/**
+ * Canonical flat claim keys for FHIR `Communication`.
+ *
+ * Good practice note:
+ * - any code, examples, scripts, or tests that write/read reusable
+ *   `Communication.*` claims must import these keys instead of re-hardcoding
+ *   string literals inline
+ * - legacy aliases such as `Communication.partOf` may still appear in
+ *   compatibility readers, but new code must use the canonical key constants
+ */
 export const CommunicationClaim = {
+    Category: 'Communication.category',
+    Status: 'Communication.status',
     Identifier: 'Communication.identifier',
     Subject: 'Communication.subject',
     Recipient: 'Communication.recipient',
@@ -9,8 +22,10 @@ export const CommunicationClaim = {
     NoteText: 'Communication.note-text',
     Text: 'Communication.text',
     ContentReference: 'Communication.content-reference',
+    ContentCode: 'Communication.content-code',
     ContentAttachmentData: 'Communication.content-attachment-data',
     ContentAttachmentType: 'Communication.content-attachment-type',
     ContentAttachmentTitle: 'Communication.content-attachment-title',
+    ContentAttachmentUrl: 'Communication.content-attachment-url',
     PartOf: 'Communication.part-of'
 };

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

@@ -1,5 +1,6 @@
 // Copyright 2026 Conéctate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
 // File: src/models/interoperable-claims/condition-claims.ts
+// Always create JSDoc, do not use strings inline in keys nor values, use types instead, and reuse the data test examples.
 export const ConditionClaim = {
     Identifier: 'Condition.identifier',
     Subject: 'Condition.subject',

package/dist/models/interoperable-claims/device-use-statement-claims.js

@@ -1,5 +1,6 @@
 // Copyright 2026 Conéctate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
 // File: src/models/interoperable-claims/device-use-statement-claims.ts
+// Always create JSDoc, do not use strings inline in keys nor values, use types instead, and reuse the data test examples.
 export const DeviceUseStatementClaim = {
     Identifier: 'DeviceUseStatement.identifier',
     Subject: 'DeviceUseStatement.subject',

package/dist/models/interoperable-claims/document-reference-claims.js

@@ -1,5 +1,6 @@
 // Copyright 2026 Conéctate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
 // File: src/models/interoperable-claims/document-reference-claims.ts
+// Always create JSDoc, do not use strings inline in keys nor values, use types instead, and reuse the data test examples.
 export const DocumentReferenceClaim = {
     Attester: 'DocumentReference.attester',
     Author: 'DocumentReference.author',

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

@@ -1,3 +1,20 @@
+/**
+ * Canonical flat claim keys for the lightweight `MedicationStatement.*` mapping
+ * used by shared examples, GW ingestion, and converter roundtrip tests.
+ */
+export declare const MedicationStatementClaim: {
+    readonly Identifier: "MedicationStatement.identifier";
+    readonly Subject: "MedicationStatement.subject";
+    readonly Status: "MedicationStatement.status";
+    readonly Effective: "MedicationStatement.effective";
+    readonly Code: "MedicationStatement.code";
+    readonly MedicationText: "MedicationStatement.medication-text";
+    readonly Note: "MedicationStatement.note";
+    readonly DosageInstruction: "MedicationStatement.dosage-instruction";
+    readonly MedicationIdentifier: "MedicationStatement.medication-identifier";
+    readonly MedicationSerialNumber: "MedicationStatement.medication-serial-number";
+    readonly MedicationExpirationDate: "MedicationStatement.medication-expiration-date";
+};
 /**
  * Flat claims contract for MedicationStatement using FHIR API-like search params.
  *

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

@@ -1,4 +1,22 @@
 // src/models/fhir/MedicationStatement.claims.ts
+// Always create JSDoc, do not use strings inline in keys nor values, use types instead, and reuse the data test examples.
+/**
+ * Canonical flat claim keys for the lightweight `MedicationStatement.*` mapping
+ * used by shared examples, GW ingestion, and converter roundtrip tests.
+ */
+export const MedicationStatementClaim = {
+    Identifier: 'MedicationStatement.identifier',
+    Subject: 'MedicationStatement.subject',
+    Status: 'MedicationStatement.status',
+    Effective: 'MedicationStatement.effective',
+    Code: 'MedicationStatement.code',
+    MedicationText: 'MedicationStatement.medication-text',
+    Note: 'MedicationStatement.note',
+    DosageInstruction: 'MedicationStatement.dosage-instruction',
+    MedicationIdentifier: 'MedicationStatement.medication-identifier',
+    MedicationSerialNumber: 'MedicationStatement.medication-serial-number',
+    MedicationExpirationDate: 'MedicationStatement.medication-expiration-date',
+};
 /**
  * Flat claims contract for MedicationStatement using FHIR API-like search params.
  *

package/dist/utils/activation-policy.d.ts

@@ -1,4 +1,4 @@
-export type ActivationRepresentativePolicyErrorCode = 'MISSING_REPRESENTATIVE_DID_WEB' | 'MISSING_REPRESENTATIVE_ROLE_RESPRSN' | 'MISSING_REPRESENTATIVE_CREDENTIAL_MATERIAL' | 'REPRESENTATIVE_TAXID_MISMATCH';
+export type ActivationRepresentativePolicyErrorCode = 'MISSING_REPRESENTATIVE_DID_WEB' | 'MISSING_REPRESENTATIVE_ROLE_RESPRSN' | 'MISSING_REPRESENTATIVE_CREDENTIAL_BINDING' | 'REPRESENTATIVE_TAXID_MISMATCH';
 export type ActivationRepresentativePolicyError = {
     code: ActivationRepresentativePolicyErrorCode;
     message: string;
@@ -41,11 +41,16 @@ export declare function extractRepresentativeRoleCode(representativeCredential:
  */
 export declare function hasRoleCode(roleCode: string | undefined, requiredCode?: string): boolean;
 /**
- * Extracts representative credential material from `credentialSubject.hasCredential`.
+ * Extracts representative signing/binding continuity data from `credentialSubject.hasCredential`.
+ *
+ * Compatibility rules:
+ * - legacy VC payloads may still carry `hasCredential.material`
+ * - newer payloads may carry the same semantic value in `hasCredential.value`
+ *   or `hasCredential.identifier.value`
  *
  * @param representativeCredential Candidate representative credential.
  */
-export declare function extractRepresentativeCredentialMaterial(representativeCredential: unknown): string | undefined;
+export declare function extractRepresentativeCredentialBinding(representativeCredential: unknown): string | undefined;
 /**
  * Extracts a `did:web:` identifier from a VC-like credential.
  *

package/dist/utils/activation-policy.js

@@ -99,29 +99,43 @@ export function hasRoleCode(roleCode, requiredCode = 'RESPRSN') {
     return normalizedRole.includes(normalizedRequired);
 }
 /**
- * Extracts representative credential material from `credentialSubject.hasCredential`.
+ * Extracts representative signing/binding continuity data from `credentialSubject.hasCredential`.
+ *
+ * Compatibility rules:
+ * - legacy VC payloads may still carry `hasCredential.material`
+ * - newer payloads may carry the same semantic value in `hasCredential.value`
+ *   or `hasCredential.identifier.value`
  *
  * @param representativeCredential Candidate representative credential.
  */
-export function extractRepresentativeCredentialMaterial(representativeCredential) {
+export function extractRepresentativeCredentialBinding(representativeCredential) {
     const subject = extractCredentialSubject(representativeCredential) || {};
     const credentialData = subject.hasCredential;
     if (typeof credentialData === 'string')
         return credentialData.trim() || undefined;
     if (Array.isArray(credentialData)) {
         for (const item of credentialData) {
-            const mat = String(item?.material || '').trim();
-            if (mat)
-                return mat;
+            const candidate = extractCredentialBindingValue(item);
+            if (candidate)
+                return candidate;
         }
     }
     if (credentialData && typeof credentialData === 'object') {
-        const mat = String(credentialData?.material || '').trim();
-        if (mat)
-            return mat;
+        const candidate = extractCredentialBindingValue(credentialData);
+        if (candidate)
+            return candidate;
     }
     return undefined;
 }
+function extractCredentialBindingValue(value) {
+    const obj = asObject(value) || {};
+    const identifier = asObject(obj.identifier);
+    const candidate = String(obj.material
+        || obj.value
+        || identifier?.value
+        || '').trim();
+    return candidate || undefined;
+}
 /**
  * Extracts a `did:web:` identifier from a VC-like credential.
  *
@@ -193,11 +207,11 @@ export function validateActivationRepresentativePolicy(input) {
             message: 'ICA-issued representative credential must include Responsible Party role (RESPRSN) in credentialSubject.hasOccupation.',
         });
     }
-    const material = extractRepresentativeCredentialMaterial(input.representativeCredential);
-    if (!material) {
+    const binding = extractRepresentativeCredentialBinding(input.representativeCredential);
+    if (!binding) {
         errors.push({
-            code: 'MISSING_REPRESENTATIVE_CREDENTIAL_MATERIAL',
-            message: 'ICA-issued representative credential is missing credentialSubject.hasCredential.material.',
+            code: 'MISSING_REPRESENTATIVE_CREDENTIAL_BINDING',
+            message: 'ICA-issued representative credential is missing credentialSubject.hasCredential binding data (material, value, or identifier.value).',
         });
     }
     return errors;

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

@@ -1,6 +1,11 @@
 // Copyright 2026 Conéctate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
 // File: src/utils/clinical-resource-converters.ts
+// Always create JSDoc, do not use strings inline in keys nor values, use types instead, and reuse the data test examples.
+import { AllergyIntoleranceClaim } from '../models/interoperable-claims/allergy-intolerance-claims.js';
+import { ConditionClaim } from '../models/interoperable-claims/condition-claims.js';
+import { DeviceUseStatementClaim } from '../models/interoperable-claims/device-use-statement-claims.js';
 import { DocumentReferenceClaim } from '../models/interoperable-claims/document-reference-claims.js';
+import { MedicationStatementClaim } from '../models/interoperable-claims/medication-statement-claims.js';
 function codingFromValue(value) {
     if (!value) {
         return undefined;
@@ -40,13 +45,13 @@ function requireDidWeb(value, key) {
  * @param claims Flat medication claims map.
  */
 export function medicationStatementFlatToFhir(claims) {
-    const subject = requireClaim(claims, 'MedicationStatement.subject');
-    const status = requireClaim(claims, 'MedicationStatement.status');
-    const effectiveDateTime = claims['MedicationStatement.effective'];
-    const medicationText = claims['MedicationStatement.medication-text'];
-    const medicationIdentifier = claims['MedicationStatement.medication-identifier'];
-    const medicationSerialNumber = claims['MedicationStatement.medication-serial-number'];
-    const medicationExpirationDate = claims['MedicationStatement.medication-expiration-date'];
+    const subject = requireClaim(claims, MedicationStatementClaim.Subject);
+    const status = requireClaim(claims, MedicationStatementClaim.Status);
+    const effectiveDateTime = claims[MedicationStatementClaim.Effective];
+    const medicationText = claims[MedicationStatementClaim.MedicationText];
+    const medicationIdentifier = claims[MedicationStatementClaim.MedicationIdentifier];
+    const medicationSerialNumber = claims[MedicationStatementClaim.MedicationSerialNumber];
+    const medicationExpirationDate = claims[MedicationStatementClaim.MedicationExpirationDate];
     const hasContainedMedication = Boolean(medicationIdentifier)
         || Boolean(medicationSerialNumber)
         || Boolean(medicationExpirationDate)
@@ -66,16 +71,16 @@ export function medicationStatementFlatToFhir(claims) {
                 : undefined,
         }
         : undefined;
-    const dosageInstructionText = claims['MedicationStatement.dosage-instruction'];
-    const noteText = claims['MedicationStatement.note'];
+    const dosageInstructionText = claims[MedicationStatementClaim.DosageInstruction];
+    const noteText = claims[MedicationStatementClaim.Note];
     return {
         resourceType: 'MedicationStatement',
-        identifier: claims['MedicationStatement.identifier'] ? [{ value: claims['MedicationStatement.identifier'] }] : undefined,
+        identifier: claims[MedicationStatementClaim.Identifier] ? [{ value: claims[MedicationStatementClaim.Identifier] }] : undefined,
         status,
         subject: { reference: subject },
         effectiveDateTime,
-        medicationCodeableConcept: claims['MedicationStatement.code']
-            ? { coding: codingFromValue(claims['MedicationStatement.code']) }
+        medicationCodeableConcept: claims[MedicationStatementClaim.Code]
+            ? { coding: codingFromValue(claims[MedicationStatementClaim.Code]) }
             : (!hasContainedMedication && medicationText ? { text: medicationText } : undefined),
         medicationReference: hasContainedMedication ? { reference: `#${containedMedicationId}` } : undefined,
         contained: containedMedication ? [containedMedication] : undefined,
@@ -104,17 +109,17 @@ export function medicationStatementFhirToFlat(resource) {
         || resource.medicationCodeableConcept?.text
         || undefined;
     return {
-        'MedicationStatement.identifier': resource.identifier?.[0]?.value,
-        'MedicationStatement.subject': resource.subject?.reference,
-        'MedicationStatement.status': resource.status,
-        'MedicationStatement.effective': resource.effectiveDateTime,
-        'MedicationStatement.code': medicationCode,
-        'MedicationStatement.medication-text': medicationText,
-        'MedicationStatement.note': noteText,
-        'MedicationStatement.dosage-instruction': dosageInstructionText,
-        'MedicationStatement.medication-identifier': containedMedicationIdentifier,
-        'MedicationStatement.medication-serial-number': batch?.lotNumber,
-        'MedicationStatement.medication-expiration-date': batch?.expirationDate,
+        [MedicationStatementClaim.Identifier]: resource.identifier?.[0]?.value,
+        [MedicationStatementClaim.Subject]: resource.subject?.reference,
+        [MedicationStatementClaim.Status]: resource.status,
+        [MedicationStatementClaim.Effective]: resource.effectiveDateTime,
+        [MedicationStatementClaim.Code]: medicationCode,
+        [MedicationStatementClaim.MedicationText]: medicationText,
+        [MedicationStatementClaim.Note]: noteText,
+        [MedicationStatementClaim.DosageInstruction]: dosageInstructionText,
+        [MedicationStatementClaim.MedicationIdentifier]: containedMedicationIdentifier,
+        [MedicationStatementClaim.MedicationSerialNumber]: batch?.lotNumber,
+        [MedicationStatementClaim.MedicationExpirationDate]: batch?.expirationDate,
     };
 }
 /**
@@ -123,26 +128,27 @@ export function medicationStatementFhirToFlat(resource) {
  * @param claims Flat allergy/intolerance claims map.
  */
 export function allergyIntoleranceFlatToFhir(claims) {
-    const patient = claims['AllergyIntolerance.subject'] ?? claims['AllergyIntolerance.patient'];
+    const patient = claims[AllergyIntoleranceClaim.Subject] ?? claims[AllergyIntoleranceClaim.Patient];
+    const recorder = claims[AllergyIntoleranceClaim.Recorder];
     if (!patient) {
-        throw new Error('Missing required claim: AllergyIntolerance.subject');
+        throw new Error(`Missing required claim: ${AllergyIntoleranceClaim.Subject}`);
     }
-    requireSubjectIdentifier(patient, 'AllergyIntolerance.subject');
-    if (claims['AllergyIntolerance.recorder']) {
-        requireDidWeb(claims['AllergyIntolerance.recorder'], 'AllergyIntolerance.recorder');
+    requireSubjectIdentifier(patient, AllergyIntoleranceClaim.Subject);
+    if (recorder) {
+        requireDidWeb(recorder, AllergyIntoleranceClaim.Recorder);
     }
     return {
         resourceType: 'AllergyIntolerance',
-        identifier: claims['AllergyIntolerance.identifier'] ? [{ value: claims['AllergyIntolerance.identifier'] }] : undefined,
+        identifier: claims[AllergyIntoleranceClaim.Identifier] ? [{ value: claims[AllergyIntoleranceClaim.Identifier] }] : undefined,
         patient: { reference: patient },
-        code: claims['AllergyIntolerance.code'] ? { coding: codingFromValue(claims['AllergyIntolerance.code']) } : undefined,
-        clinicalStatus: claims['AllergyIntolerance.clinical-status']
-            ? { coding: [{ code: claims['AllergyIntolerance.clinical-status'] }] }
+        code: claims[AllergyIntoleranceClaim.Code] ? { coding: codingFromValue(claims[AllergyIntoleranceClaim.Code]) } : undefined,
+        clinicalStatus: claims[AllergyIntoleranceClaim.ClinicalStatus]
+            ? { coding: [{ code: claims[AllergyIntoleranceClaim.ClinicalStatus] }] }
             : undefined,
-        verificationStatus: claims['AllergyIntolerance.verification-status']
-            ? { coding: [{ code: claims['AllergyIntolerance.verification-status'] }] }
+        verificationStatus: claims[AllergyIntoleranceClaim.VerificationStatus]
+            ? { coding: [{ code: claims[AllergyIntoleranceClaim.VerificationStatus] }] }
             : undefined,
-        recorder: claims['AllergyIntolerance.recorder'] ? { reference: claims['AllergyIntolerance.recorder'] } : undefined,
+        recorder: recorder ? { reference: recorder } : undefined,
     };
 }
 /**
@@ -153,13 +159,13 @@ export function allergyIntoleranceFlatToFhir(claims) {
 export function allergyIntoleranceFhirToFlat(resource) {
     const subject = resource.patient?.reference;
     return {
-        'AllergyIntolerance.identifier': resource.identifier?.[0]?.value,
-        'AllergyIntolerance.subject': subject,
-        'AllergyIntolerance.patient': subject,
-        'AllergyIntolerance.code': codingToValue(resource.code?.coding?.[0]),
-        'AllergyIntolerance.clinical-status': resource.clinicalStatus?.coding?.[0]?.code,
-        'AllergyIntolerance.verification-status': resource.verificationStatus?.coding?.[0]?.code,
-        'AllergyIntolerance.recorder': resource.recorder?.reference,
+        [AllergyIntoleranceClaim.Identifier]: resource.identifier?.[0]?.value,
+        [AllergyIntoleranceClaim.Subject]: subject,
+        [AllergyIntoleranceClaim.Patient]: subject,
+        [AllergyIntoleranceClaim.Code]: codingToValue(resource.code?.coding?.[0]),
+        [AllergyIntoleranceClaim.ClinicalStatus]: resource.clinicalStatus?.coding?.[0]?.code,
+        [AllergyIntoleranceClaim.VerificationStatus]: resource.verificationStatus?.coding?.[0]?.code,
+        [AllergyIntoleranceClaim.Recorder]: resource.recorder?.reference,
     };
 }
 /**
@@ -168,14 +174,14 @@ export function allergyIntoleranceFhirToFlat(resource) {
  * @param claims Flat condition claims map.
  */
 export function conditionFlatToFhir(claims) {
-    const subject = requireClaim(claims, 'Condition.subject');
+    const subject = requireClaim(claims, ConditionClaim.Subject);
     return {
         resourceType: 'Condition',
-        identifier: claims['Condition.identifier'] ? [{ value: claims['Condition.identifier'] }] : undefined,
+        identifier: claims[ConditionClaim.Identifier] ? [{ value: claims[ConditionClaim.Identifier] }] : undefined,
         subject: { reference: subject },
-        code: claims['Condition.code'] ? { coding: codingFromValue(claims['Condition.code']) } : undefined,
-        clinicalStatus: claims['Condition.clinical-status'] ? { coding: [{ code: claims['Condition.clinical-status'] }] } : undefined,
-        verificationStatus: claims['Condition.verification-status'] ? { coding: [{ code: claims['Condition.verification-status'] }] } : undefined,
+        code: claims[ConditionClaim.Code] ? { coding: codingFromValue(claims[ConditionClaim.Code]) } : undefined,
+        clinicalStatus: claims[ConditionClaim.ClinicalStatus] ? { coding: [{ code: claims[ConditionClaim.ClinicalStatus] }] } : undefined,
+        verificationStatus: claims[ConditionClaim.VerificationStatus] ? { coding: [{ code: claims[ConditionClaim.VerificationStatus] }] } : undefined,
     };
 }
 /**
@@ -185,11 +191,11 @@ export function conditionFlatToFhir(claims) {
  */
 export function conditionFhirToFlat(resource) {
     return {
-        'Condition.identifier': resource.identifier?.[0]?.value,
-        'Condition.subject': resource.subject?.reference,
-        'Condition.code': codingToValue(resource.code?.coding?.[0]),
-        'Condition.clinical-status': resource.clinicalStatus?.coding?.[0]?.code,
-        'Condition.verification-status': resource.verificationStatus?.coding?.[0]?.code,
+        [ConditionClaim.Identifier]: resource.identifier?.[0]?.value,
+        [ConditionClaim.Subject]: resource.subject?.reference,
+        [ConditionClaim.Code]: codingToValue(resource.code?.coding?.[0]),
+        [ConditionClaim.ClinicalStatus]: resource.clinicalStatus?.coding?.[0]?.code,
+        [ConditionClaim.VerificationStatus]: resource.verificationStatus?.coding?.[0]?.code,
     };
 }
 /**
@@ -198,17 +204,17 @@ export function conditionFhirToFlat(resource) {
  * @param claims Flat device-use claims map.
  */
 export function deviceUseStatementFlatToFhir(claims) {
-    const subject = requireClaim(claims, 'DeviceUseStatement.subject');
-    const device = requireClaim(claims, 'DeviceUseStatement.device');
-    const status = requireClaim(claims, 'DeviceUseStatement.status');
+    const subject = requireClaim(claims, DeviceUseStatementClaim.Subject);
+    const device = requireClaim(claims, DeviceUseStatementClaim.Device);
+    const status = requireClaim(claims, DeviceUseStatementClaim.Status);
     return {
         resourceType: 'DeviceUseStatement',
-        identifier: claims['DeviceUseStatement.identifier'] ? [{ value: claims['DeviceUseStatement.identifier'] }] : undefined,
+        identifier: claims[DeviceUseStatementClaim.Identifier] ? [{ value: claims[DeviceUseStatementClaim.Identifier] }] : undefined,
         subject: { reference: subject },
         device: { reference: device },
         status,
-        recordedOn: claims['DeviceUseStatement.recordedon'],
-        timingDateTime: claims['DeviceUseStatement.timing-datetime'],
+        recordedOn: claims[DeviceUseStatementClaim.RecordedOn],
+        timingDateTime: claims[DeviceUseStatementClaim.TimingDateTime],
     };
 }
 /**
@@ -218,12 +224,12 @@ export function deviceUseStatementFlatToFhir(claims) {
  */
 export function deviceUseStatementFhirToFlat(resource) {
     return {
-        'DeviceUseStatement.identifier': resource.identifier?.[0]?.value,
-        'DeviceUseStatement.subject': resource.subject?.reference,
-        'DeviceUseStatement.device': resource.device?.reference,
-        'DeviceUseStatement.status': resource.status,
-        'DeviceUseStatement.recordedon': resource.recordedOn,
-        'DeviceUseStatement.timing-datetime': resource.timingDateTime,
+        [DeviceUseStatementClaim.Identifier]: resource.identifier?.[0]?.value,
+        [DeviceUseStatementClaim.Subject]: resource.subject?.reference,
+        [DeviceUseStatementClaim.Device]: resource.device?.reference,
+        [DeviceUseStatementClaim.Status]: resource.status,
+        [DeviceUseStatementClaim.RecordedOn]: resource.recordedOn,
+        [DeviceUseStatementClaim.TimingDateTime]: resource.timingDateTime,
     };
 }
 /**

package/dist/utils/communication-document-reference.js

@@ -1,5 +1,8 @@
+// Always create JSDoc, do not use strings inline in keys nor values, use types instead, and reuse the data test examples.
 import { sha256 } from '@noble/hashes/sha2.js';
 import { utf8ToBytes } from '@noble/hashes/utils.js';
+import { CommunicationClaim } from '../models/interoperable-claims/communication-claims.js';
+import { DocumentReferenceClaim } from '../models/interoperable-claims/document-reference-claims.js';
 import { encodeMultibase58btc } from './multibase58.js';
 import { canonicalizeFhirResource, fhirResourceToCid } from './fhir-cid.js';
 const CID_V1 = 0x01;
@@ -130,16 +133,19 @@ export function buildDocumentReferenceFromCommunicationPayload(communication, op
     if (!contentCid) {
         throw new Error('Unable to generate content CID from attachment.');
     }
-    const subject = communication?.meta?.claims?.['Communication.subject'];
+    // Good practice note:
+    // reusable Communication claim keys consumed here must come from
+    // `CommunicationClaim`, not re-hardcoded inline in readers/tests.
+    const subject = communication?.meta?.claims?.[CommunicationClaim.Subject];
     const documentReference = {
         resourceType: 'DocumentReference',
         status: 'current',
         meta: {
             versionId: contentCid,
             claims: {
-                'DocumentReference.subject': subject,
-                'DocumentReference.contenttype': contentType,
-                'DocumentReference.identifier': contentCid,
+                [DocumentReferenceClaim.Subject]: subject,
+                [DocumentReferenceClaim.ContentType]: contentType,
+                [DocumentReferenceClaim.Identifier]: contentCid,
             },
         },
         subject: subject ? { reference: subject } : undefined,

package/dist/utils/communication-fhir-r4.js

@@ -1,3 +1,5 @@
+// Always create JSDoc, do not use strings inline in keys nor values, use types instead, and reuse the data test examples.
+import { CommunicationClaim } from '../models/interoperable-claims/communication-claims.js';
 import { validateFhirResource } from './fhir-validator.js';
 /**
  * Validates a FHIR R4 `Communication` resource through the configured validator pipeline.
@@ -15,16 +17,20 @@ export async function validateCommunicationResourceFhirR4(resource) {
  * @param options.defaultStatus Default FHIR status when none is provided.
  */
 export function transformCommunicationClaimsToResourceFhirR4(communicationClaims, options = {}) {
+    // Good practice note:
+    // use `CommunicationClaim` for canonical claim keys whenever this helper
+    // writes or reads reusable Communication claims. Keep string literals only
+    // for explicit legacy-compatibility aliases such as `Communication.partOf`.
     const mode = options.mode ?? 'strict';
     const defaultStatus = options.defaultStatus ?? 'completed';
     const warnings = [];
     const resources = communicationClaims.map((claims, index) => {
-        const payloadAttachmentData = toStringOrUndefined(claims['Communication.content-attachment-data']);
-        const payloadAttachmentType = toStringOrUndefined(claims['Communication.content-attachment-type']);
-        const payloadAttachmentTitle = toStringOrUndefined(claims['Communication.content-attachment-title']);
-        const payloadAttachmentUrl = toStringOrUndefined(claims['Communication.content-attachment-url']);
-        const payloadReference = toStringOrUndefined(claims['Communication.content-reference']);
-        const payloadCodeRaw = toStringOrUndefined(claims['Communication.content-code']);
+        const payloadAttachmentData = toStringOrUndefined(claims[CommunicationClaim.ContentAttachmentData]);
+        const payloadAttachmentType = toStringOrUndefined(claims[CommunicationClaim.ContentAttachmentType]);
+        const payloadAttachmentTitle = toStringOrUndefined(claims[CommunicationClaim.ContentAttachmentTitle]);
+        const payloadAttachmentUrl = toStringOrUndefined(claims[CommunicationClaim.ContentAttachmentUrl]);
+        const payloadReference = toStringOrUndefined(claims[CommunicationClaim.ContentReference]);
+        const payloadCodeRaw = toStringOrUndefined(claims[CommunicationClaim.ContentCode]);
         const hasAttachment = Boolean(payloadAttachmentData || payloadAttachmentType || payloadAttachmentTitle || payloadAttachmentUrl);
         const hasReference = Boolean(payloadReference);
         const hasCode = Boolean(payloadCodeRaw);
@@ -35,9 +41,9 @@ export function transformCommunicationClaimsToResourceFhirR4(communicationClaims
                 throw new Error(msg);
             warnings.push(`${msg} Keeping attachment > reference > code.`);
         }
-        const noteValues = normalizeNoteValues(claims['Communication.note-text']
+        const noteValues = normalizeNoteValues(claims[CommunicationClaim.NoteText]
             ?? claims['Communication.note']
-            ?? claims['Communication.text']);
+            ?? claims[CommunicationClaim.Text]);
         if (noteValues.length > 1) {
             const msg = `Communication[${index}] has more than one note.`;
             if (mode === 'strict')
@@ -55,7 +61,7 @@ export function transformCommunicationClaimsToResourceFhirR4(communicationClaims
             payloadReference,
             payloadCodeRaw,
         });
-        const partOf = toStringOrUndefined(claims['Communication.part-of'] ?? claims['Communication.partOf']);
+        const partOf = toStringOrUndefined(claims[CommunicationClaim.PartOf] ?? claims['Communication.partOf']);
         if (claims['Communication.partOf'] !== undefined) {
             const msg = `Communication[${index}] uses legacy key 'Communication.partOf'. Use 'Communication.part-of'.`;
             if (mode === 'strict')
@@ -64,27 +70,27 @@ export function transformCommunicationClaimsToResourceFhirR4(communicationClaims
         }
         const resource = {
             resourceType: 'Communication',
-            status: toStringOrUndefined(claims['Communication.status']) || defaultStatus,
+            status: toStringOrUndefined(claims[CommunicationClaim.Status]) || defaultStatus,
             meta: {
                 claims: { ...claims },
             },
         };
-        const identifier = toStringOrUndefined(claims['Communication.identifier']);
+        const identifier = toStringOrUndefined(claims[CommunicationClaim.Identifier]);
         if (identifier)
             resource['identifier'] = [{ value: identifier }];
-        const sent = toStringOrUndefined(claims['Communication.sent']);
+        const sent = toStringOrUndefined(claims[CommunicationClaim.Sent]);
         if (sent)
             resource['sent'] = sent;
-        const category = toStringOrUndefined(claims['Communication.category']);
+        const category = toStringOrUndefined(claims[CommunicationClaim.Category]);
         if (category)
             resource['category'] = [{ coding: [parseSystemCode(category)] }];
-        const subject = toStringOrUndefined(claims['Communication.subject']);
+        const subject = toStringOrUndefined(claims[CommunicationClaim.Subject]);
         if (subject)
             resource['subject'] = { reference: subject };
-        const recipient = toStringOrUndefined(claims['Communication.recipient']);
+        const recipient = toStringOrUndefined(claims[CommunicationClaim.Recipient]);
         if (recipient)
             resource['recipient'] = [{ reference: recipient }];
-        const sender = toStringOrUndefined(claims['Communication.sender']);
+        const sender = toStringOrUndefined(claims[CommunicationClaim.Sender]);
         if (sender)
             resource['sender'] = { reference: sender };
         if (partOf)
@@ -124,37 +130,37 @@ export function extractCommunicationClaimsFromResourceFhirR4(resource, options =
     const contentReference = payload?.contentReference?.reference;
     const contentAttachment = payload?.contentAttachment;
     const contentCodeableConcept = payload?.contentCodeableConcept?.coding?.[0];
-    setIf(claims, 'Communication.identifier', identifierValue);
-    setIf(claims, 'Communication.status', status);
-    setIf(claims, 'Communication.sent', sent);
-    setIf(claims, 'Communication.subject', subjectRef);
-    setIf(claims, 'Communication.recipient', recipientRef);
-    setIf(claims, 'Communication.sender', senderRef);
-    setIf(claims, 'Communication.part-of', partOfRef);
-    setIf(claims, 'Communication.note-text', noteText);
-    setIf(claims, 'Communication.text', noteText);
+    setIf(claims, CommunicationClaim.Identifier, identifierValue);
+    setIf(claims, CommunicationClaim.Status, status);
+    setIf(claims, CommunicationClaim.Sent, sent);
+    setIf(claims, CommunicationClaim.Subject, subjectRef);
+    setIf(claims, CommunicationClaim.Recipient, recipientRef);
+    setIf(claims, CommunicationClaim.Sender, senderRef);
+    setIf(claims, CommunicationClaim.PartOf, partOfRef);
+    setIf(claims, CommunicationClaim.NoteText, noteText);
+    setIf(claims, CommunicationClaim.Text, noteText);
     if (categoryCoding) {
         const system = toStringOrUndefined(categoryCoding.system);
         const code = toStringOrUndefined(categoryCoding.code);
         if (system && code)
-            claims['Communication.category'] = `${system}|${code}`;
+            claims[CommunicationClaim.Category] = `${system}|${code}`;
         else if (code)
-            claims['Communication.category'] = code;
+            claims[CommunicationClaim.Category] = code;
     }
-    setIf(claims, 'Communication.content-reference', contentReference);
+    setIf(claims, CommunicationClaim.ContentReference, contentReference);
     if (contentAttachment) {
-        setIf(claims, 'Communication.content-attachment-data', contentAttachment.data);
-        setIf(claims, 'Communication.content-attachment-type', contentAttachment.contentType);
-        setIf(claims, 'Communication.content-attachment-title', contentAttachment.title);
-        setIf(claims, 'Communication.content-attachment-url', contentAttachment.url);
+        setIf(claims, CommunicationClaim.ContentAttachmentData, contentAttachment.data);
+        setIf(claims, CommunicationClaim.ContentAttachmentType, contentAttachment.contentType);
+        setIf(claims, CommunicationClaim.ContentAttachmentTitle, contentAttachment.title);
+        setIf(claims, CommunicationClaim.ContentAttachmentUrl, contentAttachment.url);
     }
     if (contentCodeableConcept) {
         const system = toStringOrUndefined(contentCodeableConcept.system);
         const code = toStringOrUndefined(contentCodeableConcept.code);
         if (system && code)
-            claims['Communication.content-code'] = `${system}|${code}`;
+            claims[CommunicationClaim.ContentCode] = `${system}|${code}`;
         else if (code)
-            claims['Communication.content-code'] = code;
+            claims[CommunicationClaim.ContentCode] = code;
     }
     return claims;
 }

package/dist/utils/consent.d.ts

@@ -1,5 +1,5 @@
 import type { ActiveConsentView, ConsentActorDescriptor, ConsentActorKind, ConsentCoverageRequest, EffectiveAccessEvaluation, NormalizedConsentTarget, ResolvedConsentActor } from '../models/consent-access.js';
-import type { ConsentRule } from '../models/consent-rule.js';
+import { type ConsentRule } from '../models/consent-rule.js';
 /**
  * Legacy structured actor selector kept for backwards compatibility while the
  * SDK converges on the canonical flat consent actor identifier contract.