gdc-common-utils-ts 2.3.26 → 2.3.28

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

@@ -100,6 +100,14 @@ export declare const ObservationClaim: {
     readonly ValueQuantityNumber: "Observation.value-quantity-number";
     /** Human-readable quantity unit. Example: `/min`, `mmHg`, `Cel`. */
     readonly ValueQuantityUnit: "Observation.value-quantity-unit";
+    readonly ReferenceRangeLowNumber: "Observation.reference-range-low-number";
+    readonly ReferenceRangeHighNumber: "Observation.reference-range-high-number";
+    readonly ReferenceRangeUnit: "Observation.reference-range-unit";
+    readonly ReferenceRangeText: "Observation.reference-range-text";
+    readonly ComponentCode: "Observation.component-code";
+    readonly ComponentCodeDisplay: "Observation.component-code-display";
+    readonly ComponentValueQuantityNumber: "Observation.component-value-quantity-number";
+    readonly ComponentValueQuantityUnit: "Observation.component-value-quantity-unit";
     /** Aggregated score total for composite assessment observations when present. Example: `8`. */
     readonly ScoreTotalNumber: "Observation.score-total-number";
     /** Indexed systolic scalar copied onto the parent blood pressure observation. Example: `120`. */
@@ -110,8 +118,8 @@ export declare const ObservationClaim: {
     readonly ValueString: "Observation.value-string";
     /** User-authored note. Example: `Measured after resting 5 minutes.` */
     readonly Note: "Observation.note";
-    /** FHIR-compatible explicit `effectiveDateTime` fallback. Example: `2026-06-01T10:00:00Z`. */
-    readonly EffectiveDateTime: "Observation.effectiveDateTime";
+    /** FHIR-compatible explicit `effectiveDateTime` fallback using the canonical kebab-case claim name. Example: `2026-06-01T10:00:00Z`. */
+    readonly EffectiveDateTime: "Observation.effective-datetime";
 };
 export type ObservationClaimKey = typeof ObservationClaim[keyof typeof ObservationClaim];
 export type SplitCodingClaims = Readonly<{
@@ -259,14 +267,14 @@ export type ClaimsVitalSign = ClaimsObservationVitalSigns;
  * Free-text or UI-only fields may exist here even when they must stay out of
  * blind-query/search indexes.
  */
-export declare const ObservationGeneralClaimsList: readonly ["Observation.based-on", "Observation.category", "Observation.code-system", "Observation.code-value", "Observation.code-text", "Observation.code-display", "Observation.code", "Observation.date", "Observation.device", "Observation.encounter", "Observation.effectiveDateTime", "Observation.focus", "Observation.has-member", "Observation.component-tags", "Observation.component-code-values", "Observation.component-names", "Observation.identifier", "Observation.language", "Observation.method", "Observation.note", "Observation.patient", "Observation.performer", "Observation.specimen", "Observation.status", "Observation.subject", "Observation.value-concept-system", "Observation.value-concept-value", "Observation.value-concept-text", "Observation.value-concept-display", "Observation.value-concept", "Observation.value-date", "Observation.value-quantity-comparator", "Observation.value-quantity-number", "Observation.value-quantity-unit", "Observation.score-total-number", "Observation.bp-systolic-number", "Observation.bp-diastolic-number", "Observation.value-string"];
+export declare const ObservationGeneralClaimsList: readonly ["Observation.based-on", "Observation.category", "Observation.code-system", "Observation.code-value", "Observation.code-text", "Observation.code-display", "Observation.code", "Observation.date", "Observation.device", "Observation.encounter", "Observation.effective-datetime", "Observation.focus", "Observation.has-member", "Observation.component-tags", "Observation.component-code-values", "Observation.component-names", "Observation.identifier", "Observation.language", "Observation.method", "Observation.note", "Observation.patient", "Observation.performer", "Observation.specimen", "Observation.status", "Observation.subject", "Observation.value-concept-system", "Observation.value-concept-value", "Observation.value-concept-text", "Observation.value-concept-display", "Observation.value-concept", "Observation.value-date", "Observation.value-quantity-comparator", "Observation.value-quantity-number", "Observation.value-quantity-unit", "Observation.score-total-number", "Observation.bp-systolic-number", "Observation.bp-diastolic-number", "Observation.value-string"];
 /**
  * Full persisted claim surface for visible/searchable Vital Signs rows.
  *
  * This keeps the claims-first authoring fields but still avoids introducing
  * fields that only belong to broader Observation families.
  */
-export declare const ObservationVitalSignsClaimsList: readonly ["Observation.category", "Observation.code-system", "Observation.code-value", "Observation.code-text", "Observation.code-display", "Observation.code", "Observation.date", "Observation.effectiveDateTime", "Observation.has-member", "Observation.component-tags", "Observation.component-code-values", "Observation.component-names", "Observation.identifier", "Observation.language", "Observation.method", "Observation.note", "Observation.patient", "Observation.status", "Observation.subject", "Observation.value-concept-system", "Observation.value-concept-value", "Observation.value-concept-text", "Observation.value-concept-display", "Observation.value-concept", "Observation.value-date", "Observation.value-quantity-comparator", "Observation.value-quantity-number", "Observation.value-quantity-unit", "Observation.score-total-number", "Observation.bp-systolic-number", "Observation.bp-diastolic-number", "Observation.value-string"];
+export declare const ObservationVitalSignsClaimsList: readonly ["Observation.category", "Observation.code-system", "Observation.code-value", "Observation.code-text", "Observation.code-display", "Observation.code", "Observation.date", "Observation.effective-datetime", "Observation.has-member", "Observation.component-tags", "Observation.component-code-values", "Observation.component-names", "Observation.identifier", "Observation.language", "Observation.method", "Observation.note", "Observation.patient", "Observation.status", "Observation.subject", "Observation.value-concept-system", "Observation.value-concept-value", "Observation.value-concept-text", "Observation.value-concept-display", "Observation.value-concept", "Observation.value-date", "Observation.value-quantity-comparator", "Observation.value-quantity-number", "Observation.value-quantity-unit", "Observation.score-total-number", "Observation.bp-systolic-number", "Observation.bp-diastolic-number", "Observation.value-string"];
 export declare const ObservationClaimSpecs: ClaimSpec[];
 /**
  * Returns `true` when the flat claims represent one visible/searchable vital

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

@@ -102,6 +102,14 @@ export const ObservationClaim = {
     ValueQuantityNumber: 'Observation.value-quantity-number',
     /** Human-readable quantity unit. Example: `/min`, `mmHg`, `Cel`. */
     ValueQuantityUnit: 'Observation.value-quantity-unit',
+    ReferenceRangeLowNumber: 'Observation.reference-range-low-number',
+    ReferenceRangeHighNumber: 'Observation.reference-range-high-number',
+    ReferenceRangeUnit: 'Observation.reference-range-unit',
+    ReferenceRangeText: 'Observation.reference-range-text',
+    ComponentCode: 'Observation.component-code',
+    ComponentCodeDisplay: 'Observation.component-code-display',
+    ComponentValueQuantityNumber: 'Observation.component-value-quantity-number',
+    ComponentValueQuantityUnit: 'Observation.component-value-quantity-unit',
     /** Aggregated score total for composite assessment observations when present. Example: `8`. */
     ScoreTotalNumber: 'Observation.score-total-number',
     /** Indexed systolic scalar copied onto the parent blood pressure observation. Example: `120`. */
@@ -112,8 +120,8 @@ export const ObservationClaim = {
     ValueString: 'Observation.value-string',
     /** User-authored note. Example: `Measured after resting 5 minutes.` */
     Note: 'Observation.note',
-    /** FHIR-compatible explicit `effectiveDateTime` fallback. Example: `2026-06-01T10:00:00Z`. */
-    EffectiveDateTime: 'Observation.effectiveDateTime',
+    /** FHIR-compatible explicit `effectiveDateTime` fallback using the canonical kebab-case claim name. Example: `2026-06-01T10:00:00Z`. */
+    EffectiveDateTime: 'Observation.effective-datetime',
 };
 /**
  * Builds the legacy compact `system|code` token from split claims.

package/dist/models/interoperable-claims/practitioner-role-claims.d.ts

@@ -1,6 +1,15 @@
 import type { ClaimSpec } from './types';
 /** Canonical claims used to preserve the primary coded PractitionerRole label. */
 export declare const PractitionerRoleClaim: {
+    readonly Identifier: "PractitionerRole.identifier";
+    readonly Active: "PractitionerRole.active";
+    readonly Practitioner: "PractitionerRole.practitioner";
+    readonly Organization: "PractitionerRole.organization";
+    readonly Location: "PractitionerRole.location";
+    readonly Service: "PractitionerRole.service";
+    readonly Specialty: "PractitionerRole.specialty";
+    readonly PeriodStart: "PractitionerRole.period-start";
+    readonly PeriodEnd: "PractitionerRole.period-end";
     readonly Code: "PractitionerRole.code";
     readonly CodeText: "PractitionerRole.code-text";
     readonly CodeDisplay: "PractitionerRole.code-display";

package/dist/models/interoperable-claims/practitioner-role-claims.js

@@ -1,6 +1,15 @@
 // Copyright 2026 Conéctate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
 /** Canonical claims used to preserve the primary coded PractitionerRole label. */
 export const PractitionerRoleClaim = {
+    Identifier: 'PractitionerRole.identifier',
+    Active: 'PractitionerRole.active',
+    Practitioner: 'PractitionerRole.practitioner',
+    Organization: 'PractitionerRole.organization',
+    Location: 'PractitionerRole.location',
+    Service: 'PractitionerRole.service',
+    Specialty: 'PractitionerRole.specialty',
+    PeriodStart: 'PractitionerRole.period-start',
+    PeriodEnd: 'PractitionerRole.period-end',
     Code: 'PractitionerRole.code',
     CodeText: 'PractitionerRole.code-text',
     CodeDisplay: 'PractitionerRole.code-display',

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

@@ -1,8 +1,9 @@
 import type { ClaimSpec } from './types';
 export declare const RelatedPersonClaim: {
-    /** @deprecated Prefer `RelatedPerson.identifier.value` for canonical exactness. */
+    /** Canonical FHIR API identifier search parameter. */
     readonly Identifier: "RelatedPerson.identifier";
-    readonly IdentifierValue: "RelatedPerson.identifier.value";
+    /** @deprecated Use `Identifier`; retained as a source-compatible property alias. */
+    readonly IdentifierValue: "RelatedPerson.identifier";
     readonly Active: "RelatedPerson.active";
     readonly Patient: "RelatedPerson.patient";
     readonly Relationship: "RelatedPerson.relationship";

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

@@ -1,9 +1,10 @@
 // Copyright 2026 Conéctate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
 // File: src/models/interoperable-claims/related-person-claims.ts
 export const RelatedPersonClaim = {
-    /** @deprecated Prefer `RelatedPerson.identifier.value` for canonical exactness. */
+    /** Canonical FHIR API identifier search parameter. */
     Identifier: 'RelatedPerson.identifier',
-    IdentifierValue: 'RelatedPerson.identifier.value',
+    /** @deprecated Use `Identifier`; retained as a source-compatible property alias. */
+    IdentifierValue: 'RelatedPerson.identifier',
     Active: 'RelatedPerson.active',
     Patient: 'RelatedPerson.patient',
     Relationship: 'RelatedPerson.relationship',

package/dist/models/params.d.ts

@@ -3,7 +3,7 @@
  */
 export interface ClaimInteroperable {
     /**
-     * Key name of the interoperable claim in reverse-DNS (e.g., 'org.hl7.fhir.immunization.vaccine-code').
+     * Key name of the interoperable FHIR API claim in reverse-DNS (e.g., 'org.hl7.fhir.api.Immunization.vaccine-code').
      */
     name: string;
     /**

package/dist/utils/bundle-document-builder.js

@@ -5,7 +5,9 @@ import { ConditionClaim } from '../models/interoperable-claims/condition-claims.
 import { DiagnosticReportClaim } from '../models/interoperable-claims/diagnostic-report-claims.js';
 import { MedicationStatementClaim } from '../models/interoperable-claims/medication-statement-claims.js';
 import { ClaimConsent } from '../models/consent-rule.js';
-import { allergyIntoleranceFlatToFhirR4, appointmentFlatToFhirR4, carePlanFlatToFhirR4, clinicalImpressionFlatToFhirR4, compositionFlatToFhirR4, conditionFlatToFhirR4, consentFlatToFhirR4, convertFhirResourceToClaims, coverageFlatToFhirR4, deviceFlatToFhirR4, documentReferenceFlatToFhirR4, diagnosticReportFlatToFhirR4, encounterFlatToFhirR4, flagFlatToFhirR4, flatClaimsToFhirResource, immunizationFlatToFhirR4, locationFlatToFhirR4, medicationStatementFlatToFhirR4, observationFromFlatToFhirR4, organizationFlatToFhirR4, procedureFlatToFhirR4, practitionerRoleFlatToFhirR4, relatedPersonFlatToFhirR4, } from './clinical-resource-converters.js';
+import { allergyIntoleranceFlatToFhirR4, appointmentResponseFlatToFhirR4, appointmentFlatToFhirR4, carePlanFlatToFhirR4, clinicalImpressionFlatToFhirR4, compositionFlatToFhirR4, conditionFlatToFhirR4, consentFlatToFhirR4, convertFhirResourceToClaims, coverageFlatToFhirR4, deviceFlatToFhirR4, deviceUseStatementFlatToFhirR4, documentReferenceFlatToFhirR4, diagnosticReportFlatToFhirR4, encounterFlatToFhirR4, flagFlatToFhirR4, flatClaimsToFhirResource, immunizationFlatToFhirR4, locationFlatToFhirR4, medicationStatementFlatToFhirR4, observationFromFlatToFhirR4, organizationFlatToFhirR4, procedureFlatToFhirR4, practitionerRoleFlatToFhirR4, relatedPersonFlatToFhirR4, } from './clinical-resource-converters.js';
+/** Version-independent FHIR SearchParameter claim context. */
+const FHIR_API_CLAIMS_CONTEXT = 'org.hl7.fhir.api';
 function asTrimmedString(value) {
     if (value === undefined || value === null)
         return '';
@@ -22,8 +24,7 @@ export function getSimpleClaimAttributeName(key) {
     if (!value)
         return '';
     const knownPrefixes = [
-        'org.hl7.fhir.r4.',
-        'org.hl7.fhir.api.',
+        `${FHIR_API_CLAIMS_CONTEXT}.`,
     ];
     for (const prefix of knownPrefixes) {
         if (value.startsWith(prefix)) {
@@ -39,19 +40,13 @@ export function extractFlatClaimValue(record, key) {
     const direct = record[normalizedKey];
     if (typeof direct === 'string' && direct.trim())
         return direct.trim();
-    const contextualizedR4 = record[`org.hl7.fhir.r4.${normalizedKey}`];
-    if (typeof contextualizedR4 === 'string' && contextualizedR4.trim())
-        return contextualizedR4.trim();
-    const contextualizedApi = record[`org.hl7.fhir.api.${normalizedKey}`];
+    const contextualizedApi = record[`${FHIR_API_CLAIMS_CONTEXT}.${normalizedKey}`];
     if (typeof contextualizedApi === 'string' && contextualizedApi.trim())
         return contextualizedApi.trim();
     const nested = record?.meta?.claims?.[normalizedKey];
     if (typeof nested === 'string' && nested.trim())
         return nested.trim();
-    const nestedR4 = record?.meta?.claims?.[`org.hl7.fhir.r4.${normalizedKey}`];
-    if (typeof nestedR4 === 'string' && nestedR4.trim())
-        return nestedR4.trim();
-    const nestedApi = record?.meta?.claims?.[`org.hl7.fhir.api.${normalizedKey}`];
+    const nestedApi = record?.meta?.claims?.[`${FHIR_API_CLAIMS_CONTEXT}.${normalizedKey}`];
     if (typeof nestedApi === 'string' && nestedApi.trim())
         return nestedApi.trim();
     return '';
@@ -59,12 +54,33 @@ export function extractFlatClaimValue(record, key) {
 function claimsToFlatStrings(claims) {
     const out = {};
     for (const [key, value] of Object.entries(claims || {})) {
-        if (value === undefined || value === null)
+        if (value === undefined || value === null || key === '@context')
+            continue;
+        const canonicalKey = getSimpleClaimAttributeName(key);
+        if (canonicalKey === key)
+            continue;
+        out[canonicalKey] = typeof value === 'string' ? value : String(value);
+    }
+    for (const [key, value] of Object.entries(claims || {})) {
+        if (value === undefined || value === null || key === '@context')
+            continue;
+        const canonicalKey = getSimpleClaimAttributeName(key);
+        if (canonicalKey !== key)
             continue;
         out[key] = typeof value === 'string' ? value : String(value);
     }
     return out;
 }
+/** Rejects version-specific FHIR resource contexts from the claims contract. */
+function assertFhirApiClaimsContext(claims) {
+    const context = asTrimmedString(claims?.['@context']);
+    const hasVersionSpecificContext = context.startsWith('org.hl7.fhir.')
+        && context !== FHIR_API_CLAIMS_CONTEXT;
+    const hasVersionSpecificExpandedKey = Object.keys(claims || {}).some((key) => key.startsWith('org.hl7.fhir.') && !key.startsWith(`${FHIR_API_CLAIMS_CONTEXT}.`));
+    if (hasVersionSpecificContext || hasVersionSpecificExpandedKey) {
+        throw new Error(`FHIR claims require @context ${FHIR_API_CLAIMS_CONTEXT}. Version-specific FHIR resource contexts are not claim namespaces.`);
+    }
+}
 function ensureClaimsIdentifier(claims, resource) {
     const resourceType = asTrimmedString(resource?.resourceType);
     const identifierKey = resourceType ? `${resourceType}.identifier` : '';
@@ -202,7 +218,7 @@ export function prepareBundleDocumentForSubject(bundle, subjectDid, options = {}
         if (!resource || typeof resource !== 'object')
             continue;
         replacePatientSubjectReference(resource, normalizedSubjectDid);
-        const generated = convertFhirResourceToClaims(resource, options.context || 'org.hl7.fhir.r4');
+        const generated = convertFhirResourceToClaims(resource, options.context || FHIR_API_CLAIMS_CONTEXT);
         const existing = resource?.meta?.claims;
         const claims = {
             ...generated,
@@ -324,7 +340,7 @@ export function detectClaimsResourceType(claims) {
         return ResourceTypesFhirR4.DocumentReference;
     const firstContextualized = keys
         .map((key) => getSimpleClaimAttributeName(key))
-        .find((key) => key.includes('.'));
+        .find((key) => key.includes('.') && !key.startsWith(`${ResourceTypesFhirR4.Composition}.`));
     if (firstContextualized) {
         return firstContextualized.split('.')[0];
     }
@@ -332,10 +348,11 @@ export function detectClaimsResourceType(claims) {
 }
 export function convertClaimsToFhirResource(claims, version = 'r4') {
     void version;
+    assertFhirApiClaimsContext(claims);
     const flatClaims = claimsToFlatStrings(claims);
     const resourceType = detectClaimsResourceType(claims);
     const resource = convertClaimsToFhirResourceByType(flatClaims, resourceType);
-    const language = resourceType ? asTrimmedString(claims[`${resourceType}.language`]) : '';
+    const language = resourceType ? asTrimmedString(flatClaims[`${resourceType}.language`]) : '';
     return language ? { ...resource, language } : resource;
 }
 function convertClaimsToFhirResourceByType(flatClaims, resourceType) {
@@ -348,6 +365,8 @@ function convertClaimsToFhirResourceByType(flatClaims, resourceType) {
             return conditionFlatToFhirR4(flatClaims);
         case ResourceTypesFhirR4.DocumentReference:
             return documentReferenceFlatToFhirR4(flatClaims);
+        case ResourceTypesFhirR4.DeviceUseStatement:
+            return deviceUseStatementFlatToFhirR4(flatClaims);
         case 'Immunization':
             return immunizationFlatToFhirR4(flatClaims);
         case 'Location':
@@ -370,6 +389,8 @@ function convertClaimsToFhirResourceByType(flatClaims, resourceType) {
             return compositionFlatToFhirR4(flatClaims);
         case 'Appointment':
             return appointmentFlatToFhirR4(flatClaims);
+        case 'AppointmentResponse':
+            return appointmentResponseFlatToFhirR4(flatClaims);
         case 'Encounter':
             return encounterFlatToFhirR4(flatClaims);
         case 'RelatedPerson':
@@ -397,7 +418,7 @@ function convertClaimsToFhirResourceByType(flatClaims, resourceType) {
  * not yet part of the clinical claims-first pipeline:
  * `Composition`, `Patient`, `Practitioner`, `PractitionerRole`.
  */
-export function extractBundleDocumentClaimsList(bundle, context = 'org.hl7.fhir.r4') {
+export function extractBundleDocumentClaimsList(bundle, context = 'org.hl7.fhir.api') {
     const entries = Array.isArray(bundle?.entry) ? bundle.entry : [];
     const ignoredResourceTypes = new Set([
         ResourceTypesFhirR4.Composition,

package/dist/utils/bundle-entry-editor.d.ts

@@ -75,6 +75,19 @@ export declare class BundleEntryEditor {
     hasClaim(key: string): boolean;
     /** Writes one claim on this entry. */
     setClaim(key: string, value: unknown): this;
+    /**
+     * Writes one viewer/editor field using the canonical short FHIR API claim.
+     * Expanded `org.hl7.fhir.api.*` input is normalized; versioned FHIR claim
+     * namespaces and structural/camelCase paths are rejected.
+     */
+    setFhirApiClaim(key: string, value: unknown): this;
+    /** Reads one short or expanded FHIR API claim through the canonical short key. */
+    getFhirApiClaim(key: string): unknown;
+    /** Applies a complete field collection returned by a clinical card view. */
+    setFhirApiClaimFields(fields: readonly Readonly<{
+        claim: string;
+        value: unknown;
+    }>[]): this;
     /** Appends one claim value on this entry. */
     addClaim(key: string, value: unknown): this;
     /** Removes one claim from this entry. */

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

@@ -6,6 +6,7 @@
  */
 import { ResourceTypesFhirR4 } from '../constants/fhir-resource-types.js';
 import { BundleEditableResourceTypes, } from '../models/bundle-editor-types.js';
+import { normalizeFhirApiClaimKey } from './fhir-api-claim-helpers.js';
 import { EmployeeResourceTypes, } from './employee.js';
 import { cloneClaimValue, normalizeOptionalIdentifier } from './bundle-editor-helpers.js';
 import { createRegisteredBundleEntryEditor } from './bundle-editor-registry.js';
@@ -241,6 +242,23 @@ export class BundleEntryEditor {
         };
         return this;
     }
+    /**
+     * Writes one viewer/editor field using the canonical short FHIR API claim.
+     * Expanded `org.hl7.fhir.api.*` input is normalized; versioned FHIR claim
+     * namespaces and structural/camelCase paths are rejected.
+     */
+    setFhirApiClaim(key, value) {
+        return this.setClaim(normalizeFhirApiClaimKey(key), value);
+    }
+    /** Reads one short or expanded FHIR API claim through the canonical short key. */
+    getFhirApiClaim(key) {
+        return this.getClaim(normalizeFhirApiClaimKey(key));
+    }
+    /** Applies a complete field collection returned by a clinical card view. */
+    setFhirApiClaimFields(fields) {
+        fields.forEach((field) => this.setFhirApiClaim(field.claim, field.value));
+        return this;
+    }
     /** Appends one claim value on this entry. */
     addClaim(key, value) {
         const normalizedKey = String(key).trim();

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

@@ -99,12 +99,14 @@ export const practitionerRoleFhirToFlat = practitionerRoleFhirR4ToFlat;
  * resource-specific converter exists. Unsupported resources fall back to the
  * generic structural flattening.
  */
-export function convertFhirResourceToClaims(resource, context = 'org.hl7.fhir.r4') {
+export function convertFhirResourceToClaims(resource, context = 'org.hl7.fhir.api') {
     const claims = convertFhirResourceToClaimsByType(resource, context);
     const language = typeof resource.language === 'string' ? resource.language.trim() : '';
-    return language
-        ? { ...claims, [`${resource.resourceType}.language`]: language }
-        : claims;
+    return {
+        '@context': context,
+        ...claims,
+        ...(language ? { [`${resource.resourceType}.language`]: language } : {}),
+    };
 }
 function convertFhirResourceToClaimsByType(resource, context) {
     switch (resource.resourceType) {

package/dist/utils/clinical-resource-view.d.ts

@@ -20,9 +20,54 @@ export type ClinicalResourceCommonView = Readonly<{
 export type ClinicalResourceCardView = Readonly<{
     title: string;
     resourceType: string;
+    /** Stable business identifier used to reconcile repeated readbacks. */
+    identifier?: string;
     date?: string;
+    periodStart?: string;
+    periodEnd?: string;
     fullUrl?: string;
     actorsCount: number;
+    /** Resource status resolved from canonical claims first, then native FHIR. */
+    status?: string;
+    /** Observation scalar value for result cards. */
+    value?: string | number;
+    /** Observation quantity unit for result cards. */
+    unit?: string;
+    /** Immunization lot number. */
+    lotNumber?: string;
+    /** Immunization dose sequence. */
+    doseSequence?: string;
+    /** AllergyIntolerance criticality. */
+    criticality?: string;
+    /** AllergyIntolerance onset date/time. */
+    onsetDateTime?: string;
+    /** MedicationStatement human-readable dosage instruction. */
+    dosageInstruction?: string;
+    category?: string;
+    severity?: string;
+    recordedDate?: string;
+    source?: string;
+    route?: string;
+    site?: string;
+    doseQuantityValue?: number;
+    doseQuantityUnit?: string;
+    referenceRangeText?: string;
+    description?: string;
+    /**
+     * Complete editable field surface resolved from `resource.meta.claims`.
+     *
+     * `claim` always uses the short, version-independent FHIR API form
+     * (`<ResourceType>.<search-param>`). Consumers can therefore render and
+     * hydrate fields that do not yet have a dedicated card convenience member.
+     */
+    fields: readonly ClinicalResourceClaimFieldView[];
+}>;
+export type ClinicalResourceClaimFieldView = Readonly<{
+    /** Canonical short FHIR API claim, for example `Immunization.lot-number`. */
+    claim: string;
+    /** Concrete FHIR API SearchParameter name, for example `lot-number`. */
+    parameter: string;
+    value: unknown;
 }>;
 export type ClinicalTerminologyTranslationInput = Readonly<{
     resourceType: string;
@@ -110,6 +155,16 @@ export declare function toClinicalResourceCommonViews(bundle: ClinicalResourceBu
  * Maps one bundle entry to a minimal card view for section counters/list cards.
  */
 export declare function toClinicalResourceCardView(entry: ClinicalResourceEntryLike, options?: ClinicalResourceDisplayOptions): ClinicalResourceCardView;
+/**
+ * Normalizes all clinical `meta.claims` into the short FHIR API vocabulary
+ * consumed by generic clinical viewers and editors.
+ *
+ * Short claims take precedence over their expanded
+ * `org.hl7.fhir.api.<ResourceType>.<search-param>` equivalent. Versioned
+ * `org.hl7.fhir.<version>.*` namespaces are rejected because they are native
+ * FHIR representation namespaces, never claims vocabularies.
+ */
+export declare function toClinicalResourceClaimFieldViews(claims: ClinicalViewClaims): ClinicalResourceClaimFieldView[];
 /**
  * Maps all entries from a Bundle into minimal card views.
  */

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

@@ -14,6 +14,7 @@ import { MedicationStatementClaim, MedicationStatementClaimsFhirApi, MedicationS
 import { ObservationClaim } from '../models/interoperable-claims/observation-claims.js';
 import { PractitionerRoleClaim } from '../models/interoperable-claims/practitioner-role-claims.js';
 import { ProcedureClaim } from '../models/interoperable-claims/procedure-claims.js';
+import { normalizeFhirApiClaimKey } from './fhir-api-claim-helpers.js';
 const CONSENT_ACTOR_REFERENCE_CLAIM = 'Consent.actor-reference';
 const GENERIC_CREATOR_CLAIM_SUFFIX = '.creator';
 const GENERIC_PERFORMER_CLAIM_SUFFIX = '.performer';
@@ -49,14 +50,112 @@ export function toClinicalResourceCommonViews(bundle, options = {}) {
  */
 export function toClinicalResourceCardView(entry, options = {}) {
     const common = toClinicalResourceCommonView(entry, options);
+    const resource = entry.resource;
+    const status = resolveCardStatus(common.resourceType, common.claims, resource);
+    const value = resolveCardValue(common.resourceType, common.claims, resource);
+    const unit = resolveCardUnit(common.resourceType, common.claims, resource);
+    const lotNumber = readCanonicalClaimValue(common.claims, ImmunizationClaim.LotNumber)
+        || trimValue(resource?.lotNumber);
+    const doseSequence = readCanonicalClaimValue(common.claims, ImmunizationClaim.DoseSequence)
+        || trimValue(asRecord(asArray(resource?.protocolApplied)[0]).doseNumberString);
+    const criticality = readCanonicalClaimValue(common.claims, AllergyIntoleranceClaim.Criticality)
+        || trimValue(resource?.criticality);
+    const onsetDateTime = readCanonicalClaimValue(common.claims, AllergyIntoleranceClaim.OnsetDateTime)
+        || trimValue(resource?.onsetDateTime);
+    const dosageInstruction = readCanonicalClaimValue(common.claims, MedicationStatementClaim.DosageInstruction)
+        || trimValue(asRecord(asArray(resource?.dosage)[0]).text);
+    const fields = toClinicalResourceClaimFieldViews(common.claims);
+    const category = readCanonicalClaimValue(common.claims, `${common.resourceType}.category`);
+    const severity = readCanonicalClaimValue(common.claims, `${common.resourceType}.severity`);
+    const recordedDate = readCanonicalClaimValue(common.claims, ConditionClaim.RecordedDate);
+    const source = readCanonicalClaimValue(common.claims, MedicationStatementClaim.Source);
+    const route = readCanonicalClaimValue(common.claims, ImmunizationClaim.Route);
+    const site = readCanonicalClaimValue(common.claims, ImmunizationClaim.Site);
+    const doseQuantityValueRaw = readCanonicalClaimValue(common.claims, MedicationStatementClaim.DoseQuantityValue);
+    const doseQuantityValue = doseQuantityValueRaw === undefined ? undefined : Number(doseQuantityValueRaw);
+    const doseQuantityUnit = readCanonicalClaimValue(common.claims, MedicationStatementClaim.DoseQuantityUnit);
+    const referenceRangeText = readCanonicalClaimValue(common.claims, ObservationClaim.ReferenceRangeText);
+    const description = readCanonicalClaimValue(common.claims, CarePlanClaim.Description);
     return {
         title: common.title,
         resourceType: common.resourceType,
+        ...(common.identifier ? { identifier: common.identifier } : {}),
         date: common.date,
+        ...(common.periodStart ? { periodStart: common.periodStart } : {}),
+        ...(common.periodEnd ? { periodEnd: common.periodEnd } : {}),
         fullUrl: common.fullUrl,
         actorsCount: common.actors.length,
+        fields,
+        ...(status ? { status } : {}),
+        ...(value !== undefined ? { value } : {}),
+        ...(unit ? { unit } : {}),
+        ...(lotNumber ? { lotNumber } : {}),
+        ...(doseSequence ? { doseSequence } : {}),
+        ...(criticality ? { criticality } : {}),
+        ...(onsetDateTime ? { onsetDateTime } : {}),
+        ...(dosageInstruction ? { dosageInstruction } : {}),
+        ...(category ? { category } : {}),
+        ...(severity ? { severity } : {}),
+        ...(recordedDate ? { recordedDate } : {}),
+        ...(source ? { source } : {}),
+        ...(route ? { route } : {}),
+        ...(site ? { site } : {}),
+        ...(doseQuantityValue !== undefined && Number.isFinite(doseQuantityValue) ? { doseQuantityValue } : {}),
+        ...(doseQuantityUnit ? { doseQuantityUnit } : {}),
+        ...(referenceRangeText ? { referenceRangeText } : {}),
+        ...(description ? { description } : {}),
     };
 }
+/**
+ * Normalizes all clinical `meta.claims` into the short FHIR API vocabulary
+ * consumed by generic clinical viewers and editors.
+ *
+ * Short claims take precedence over their expanded
+ * `org.hl7.fhir.api.<ResourceType>.<search-param>` equivalent. Versioned
+ * `org.hl7.fhir.<version>.*` namespaces are rejected because they are native
+ * FHIR representation namespaces, never claims vocabularies.
+ */
+export function toClinicalResourceClaimFieldViews(claims) {
+    const fields = new Map();
+    const entries = Object.entries(claims || {});
+    for (const [rawClaim, value] of entries) {
+        if (rawClaim.startsWith('@') || value === undefined)
+            continue;
+        if (rawClaim.startsWith('org.hl7.fhir.') && !rawClaim.startsWith('org.hl7.fhir.api.')) {
+            throw new Error(`FHIR meta.claims must use org.hl7.fhir.api, not version-specific key: ${rawClaim}`);
+        }
+        if (!rawClaim.startsWith('org.hl7.fhir.api.') && !/^[A-Z][A-Za-z0-9]+\./.test(rawClaim))
+            continue;
+        const claim = normalizeFhirApiClaimKey(rawClaim);
+        const separator = claim.indexOf('.');
+        if (separator <= 0 || separator === claim.length - 1)
+            continue;
+        if (!fields.has(claim)) {
+            fields.set(claim, {
+                claim,
+                parameter: claim.slice(separator + 1),
+                value,
+            });
+        }
+    }
+    // Apply canonical short keys last so they win over expanded aliases even
+    // when the expanded property appeared later in insertion order.
+    for (const [claim, value] of entries) {
+        if (claim.startsWith('@') || claim.startsWith('org.hl7.fhir.') || value === undefined)
+            continue;
+        if (!/^[A-Z][A-Za-z0-9]+\./.test(claim))
+            continue;
+        const separator = claim.indexOf('.');
+        if (separator <= 0 || separator === claim.length - 1)
+            continue;
+        fields.set(claim, {
+            claim,
+            parameter: claim.slice(separator + 1),
+            value,
+        });
+    }
+    return [...fields.values()].sort((left, right) => left.claim.localeCompare(right.claim));
+}
 /**
  * Maps all entries from a Bundle into minimal card views.
  */
@@ -196,6 +295,42 @@ export function getNarrative(resource) {
         source: 'derived-from-claims',
     };
 }
+function resolveCardStatus(resourceType, claims, resource) {
+    const claimsStatus = resourceType === ResourceTypesFhirR4.AllergyIntolerance
+        ? readCanonicalClaimValue(claims, AllergyIntoleranceClaim.ClinicalStatus)
+        : readCanonicalClaimValue(claims, `${resourceType}.status`);
+    if (claimsStatus)
+        return claimsStatus;
+    const nativeStatus = trimValue(resource?.status);
+    if (nativeStatus)
+        return nativeStatus;
+    return trimValue(asRecord(asArray(asRecord(resource?.clinicalStatus).coding)[0]).code) || undefined;
+}
+function resolveCardValue(resourceType, claims, resource) {
+    if (resourceType !== ResourceTypesFhirR4.Observation)
+        return undefined;
+    const claimNumber = readCanonicalClaimValue(claims, ObservationClaim.ValueQuantityNumber);
+    if (claimNumber !== undefined) {
+        const numeric = Number(claimNumber);
+        if (Number.isFinite(numeric))
+            return numeric;
+    }
+    const claimString = readCanonicalClaimValue(claims, ObservationClaim.ValueString);
+    if (claimString)
+        return claimString;
+    const nativeNumber = asRecord(resource?.valueQuantity).value;
+    if (typeof nativeNumber === 'number' && Number.isFinite(nativeNumber))
+        return nativeNumber;
+    return trimValue(resource?.valueString) || undefined;
+}
+function resolveCardUnit(resourceType, claims, resource) {
+    if (resourceType !== ResourceTypesFhirR4.Observation)
+        return undefined;
+    return readCanonicalClaimValue(claims, ObservationClaim.ValueQuantityUnit)
+        || trimValue(asRecord(resource?.valueQuantity).unit)
+        || trimValue(asRecord(resource?.valueQuantity).code)
+        || undefined;
+}
 function readClaims(entry) {
     const resourceClaims = asRecord(entry?.resource?.meta?.claims);
     const legacyClaims = asRecord(entry?.meta?.claims);
@@ -397,7 +532,8 @@ function resolveIdentifier(resourceType, claims, resource) {
             AllergyIntoleranceClaimsFhirApi.Identifier,
         ]) || resolveFhirIdentifier(resource);
     }
-    return resolveFhirIdentifier(resource);
+    return readCanonicalClaimValue(claims, `${resourceType}.identifier`)
+        || resolveFhirIdentifier(resource);
 }
 function resolveDate(resourceType, claims, resource) {
     if (resourceType === ResourceTypesFhirR4.Communication) {

package/dist/utils/communication-bundle-document-request.js

@@ -67,7 +67,7 @@ export function buildBundleDocumentRequestCommunicationClaims(input) {
             : `Request ${documentTypeDescriptor.id} Bundle search with sections: ${sections.join(', ')}`)).trim();
     const noteText = String(input.noteText || text).trim();
     const claims = {
-        '@context': 'org.hl7.fhir.r4',
+        '@context': 'org.hl7.fhir.api',
         [CommunicationClaim.Identifier]: communicationIdentifier,
         [CommunicationClaim.Status]: String(input.status || 'completed').trim(),
         [CommunicationClaim.Category]: CommunicationCategoryCodes.Notification.claim,

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

@@ -121,7 +121,7 @@ export function extractCommunicationClaimsFromResourceFhirR4(resource, options =
         return { ...existingClaims };
     }
     const claims = {};
-    claims['@context'] = 'org.hl7.fhir.r4';
+    claims['@context'] = 'org.hl7.fhir.api';
     const identifierValue = resource?.identifier?.[0]?.value;
     const status = resource?.status;
     const sent = resource?.sent;

package/dist/utils/fhir-api-claim-helpers.d.ts

@@ -0,0 +1,2 @@
+/** Returns the canonical short FHIR API claim or throws for another vocabulary. */
+export declare function normalizeFhirApiClaimKey(claimKey: string): string;

package/dist/utils/fhir-api-claim-helpers.js

@@ -0,0 +1,16 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+const FHIR_API_PREFIX = 'org.hl7.fhir.api.';
+const FHIR_VERSIONED_PREFIX = 'org.hl7.fhir.';
+const SHORT_FHIR_API_CLAIM = /^[A-Z][A-Za-z0-9]+\.[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** Returns the canonical short FHIR API claim or throws for another vocabulary. */
+export function normalizeFhirApiClaimKey(claimKey) {
+    const raw = String(claimKey || '').trim();
+    if (raw.startsWith(FHIR_VERSIONED_PREFIX) && !raw.startsWith(FHIR_API_PREFIX)) {
+        throw new Error(`FHIR claims must use org.hl7.fhir.api, not version-specific key: ${raw}`);
+    }
+    const normalized = raw.startsWith(FHIR_API_PREFIX) ? raw.slice(FHIR_API_PREFIX.length) : raw;
+    if (!SHORT_FHIR_API_CLAIM.test(normalized)) {
+        throw new Error(`Invalid FHIR API claim key: ${raw}`);
+    }
+    return normalized;
+}