fhir-data-utils-ts 0.6.0 → 0.6.2

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## Unreleased
 
+## 0.6.2 - 2026-09-30
+
+- Add strict FHIR `instant` to Unix epoch-second derivation while preserving
+  the boundary between clinical time, `Encounter.id`, provider business
+  identifiers and human display codes.
+
+## 0.6.1 - 2026-09-30
+
+- Add canonical flat claims, a claims-first builder and native R5 projection
+  for `EncounterHistory`, including explicit Encounter, HealthcareService,
+  subject, status, class, period and Location boundaries.
+- Add the R5 Encounter lifecycle and projection without weakening the existing
+  R4 adapter; `on-hold`, `discharged` and `completed` are validated only at the
+  R5 boundary.
+
 ## 0.6.0 - 2026-09-29
 
 - Add canonical two-level Communication Bundle validation tools recovered from

package/README.md

@@ -92,6 +92,12 @@ metadata and protected endpoint references only. DICOM instances and pixel
 payloads remain outside this neutral package and are never embedded as flat
 claims.
 
+FHIR instants, resource ids and provider business identifiers remain separate.
+Use `fhirInstantToEpochSeconds(...)` only when a downstream convention needs a
+derived whole-second value; retain the original timezone-bearing instant and
+an independent `Encounter.id`. See
+[`docs/ENCOUNTER_IDENTIFIERS_AND_TIME.md`](docs/ENCOUNTER_IDENTIFIERS_AND_TIME.md).
+
 No consumer should copy claim paths or rebuild these structures with literals.
 Use `fhir-data-utils-ts/claims`, `/converters`, `/fhir-bundle`,
 `/fhir-search-parameters`, `/clinical-terminology`, `/group-r5` or

package/dist/care-emergency-alert.d.ts

@@ -1,3 +1,4 @@
+import { EncounterStatusR5 } from './claims/index.js';
 import { type FlatClaimResourceEntry } from './flat-claim-resource-graph.js';
 export type ClinicalCoding = Readonly<{
     system: string;
@@ -14,6 +15,23 @@ export type EncounterJourneyNode = Readonly<{
     locationReference: string;
     type?: ClinicalCoding;
 }>;
+/** Builds one FHIR R5 EncounterHistory milestone from canonical flat claims. */
+export declare function buildEncounterHistoryR5FlatEntry(input: Readonly<{
+    entryId: string;
+    identifier: string;
+    encounterReference: string;
+    status: EncounterStatusR5;
+    class: ClinicalCoding;
+    serviceReference?: string;
+    subjectReference?: string;
+    subjectStatus?: ClinicalCoding;
+    actualPeriodStart?: string;
+    actualPeriodEnd?: string;
+    plannedStartDate?: string;
+    plannedEndDate?: string;
+    locationReference?: string;
+    locationForm?: ClinicalCoding;
+}>): FlatClaimResourceEntry;
 /**
  * Builds one actual-care Encounter graph from an originating Appointment.
  * Child service/location encounters inherit subject and provider and reference

package/dist/care-emergency-alert.js

@@ -1,5 +1,33 @@
-import { CommunicationRequestClaim, EncounterClaim, ServiceRequestClaim, TaskClaim, } from './claims/index.js';
+import { CommunicationRequestClaim, EncounterClaim, EncounterHistoryClaim, ServiceRequestClaim, TaskClaim, } from './claims/index.js';
 import { buildFlatClaimResourceEntry } from './flat-claim-resource-graph.js';
+/** Builds one FHIR R5 EncounterHistory milestone from canonical flat claims. */
+export function buildEncounterHistoryR5FlatEntry(input) {
+    const claims = {
+        [EncounterHistoryClaim.Identifier]: required(input.identifier, 'encounter_history_identifier_required'),
+        [EncounterHistoryClaim.Encounter]: reference(input.encounterReference, 'encounter_history_encounter_invalid'),
+        [EncounterHistoryClaim.Status]: input.status,
+        [EncounterHistoryClaim.Class]: coding(input.class, 'encounter_history_class_invalid'),
+    };
+    if (input.serviceReference)
+        claims[EncounterHistoryClaim.ServiceType] = reference(input.serviceReference, 'encounter_history_service_invalid');
+    if (input.subjectReference)
+        claims[EncounterHistoryClaim.Subject] = reference(input.subjectReference, 'encounter_history_subject_invalid');
+    if (input.subjectStatus)
+        claims[EncounterHistoryClaim.SubjectStatus] = coding(input.subjectStatus, 'encounter_history_subject_status_invalid');
+    if (input.actualPeriodStart)
+        claims[EncounterHistoryClaim.ActualPeriodStart] = dateTime(input.actualPeriodStart, 'encounter_history_actual_start_invalid');
+    if (input.actualPeriodEnd)
+        claims[EncounterHistoryClaim.ActualPeriodEnd] = dateTime(input.actualPeriodEnd, 'encounter_history_actual_end_invalid');
+    if (input.plannedStartDate)
+        claims[EncounterHistoryClaim.PlannedStartDate] = dateTime(input.plannedStartDate, 'encounter_history_planned_start_invalid');
+    if (input.plannedEndDate)
+        claims[EncounterHistoryClaim.PlannedEndDate] = dateTime(input.plannedEndDate, 'encounter_history_planned_end_invalid');
+    if (input.locationReference)
+        claims[EncounterHistoryClaim.Location] = reference(input.locationReference, 'encounter_history_location_invalid');
+    if (input.locationForm)
+        claims[EncounterHistoryClaim.LocationForm] = coding(input.locationForm, 'encounter_history_location_form_invalid');
+    return buildFlatClaimResourceEntry({ entryId: input.entryId, resourceType: 'EncounterHistory', claims });
+}
 /**
  * Builds one actual-care Encounter graph from an originating Appointment.
  * Child service/location encounters inherit subject and provider and reference

package/dist/claims/encounter-claims.d.ts

@@ -8,9 +8,12 @@ export declare const EncounterClaim: {
     readonly Subject: "Encounter.subject";
     readonly Patient: "Encounter.patient";
     readonly Participant: "Encounter.participant";
+    readonly ServiceType: "Encounter.service-type";
     readonly ServiceProvider: "Encounter.service-provider";
     readonly PeriodStart: "Encounter.period-start";
     readonly PeriodEnd: "Encounter.period-end";
+    readonly ActualPeriodStart: "Encounter.actual-period-start";
+    readonly ActualPeriodEnd: "Encounter.actual-period-end";
     readonly ReasonCode: "Encounter.reason-code";
     readonly Diagnosis: "Encounter.diagnosis";
     readonly Location: "Encounter.location";
@@ -28,5 +31,17 @@ export declare enum EncounterStatus {
     EnteredInError = "entered-in-error",
     Unknown = "unknown"
 }
+/** Canonical FHIR R5 Encounter lifecycle codes. */
+export declare enum EncounterStatusR5 {
+    Planned = "planned",
+    InProgress = "in-progress",
+    OnHold = "on-hold",
+    Discharged = "discharged",
+    Completed = "completed",
+    Cancelled = "cancelled",
+    Discontinued = "discontinued",
+    EnteredInError = "entered-in-error",
+    Unknown = "unknown"
+}
 export type EncounterClaimKey = typeof EncounterClaim[keyof typeof EncounterClaim];
 export declare const EncounterClaimSpecs: ClaimSpec[];

package/dist/claims/encounter-claims.js

@@ -9,9 +9,12 @@ export const EncounterClaim = {
     Subject: 'Encounter.subject',
     Patient: 'Encounter.patient',
     Participant: 'Encounter.participant',
+    ServiceType: 'Encounter.service-type',
     ServiceProvider: 'Encounter.service-provider',
     PeriodStart: 'Encounter.period-start',
     PeriodEnd: 'Encounter.period-end',
+    ActualPeriodStart: 'Encounter.actual-period-start',
+    ActualPeriodEnd: 'Encounter.actual-period-end',
     ReasonCode: 'Encounter.reason-code',
     Diagnosis: 'Encounter.diagnosis',
     Location: 'Encounter.location',
@@ -30,6 +33,19 @@ export var EncounterStatus;
     EncounterStatus["EnteredInError"] = "entered-in-error";
     EncounterStatus["Unknown"] = "unknown";
 })(EncounterStatus || (EncounterStatus = {}));
+/** Canonical FHIR R5 Encounter lifecycle codes. */
+export var EncounterStatusR5;
+(function (EncounterStatusR5) {
+    EncounterStatusR5["Planned"] = "planned";
+    EncounterStatusR5["InProgress"] = "in-progress";
+    EncounterStatusR5["OnHold"] = "on-hold";
+    EncounterStatusR5["Discharged"] = "discharged";
+    EncounterStatusR5["Completed"] = "completed";
+    EncounterStatusR5["Cancelled"] = "cancelled";
+    EncounterStatusR5["Discontinued"] = "discontinued";
+    EncounterStatusR5["EnteredInError"] = "entered-in-error";
+    EncounterStatusR5["Unknown"] = "unknown";
+})(EncounterStatusR5 || (EncounterStatusR5 = {}));
 export const EncounterClaimSpecs = [
     { key: EncounterClaim.Identifier, meaning: 'Business identifier.', example: 'enc-001' },
     { key: EncounterClaim.Appointment, meaning: 'Originating appointment references (CSV).', example: 'Appointment/appointment-1' },
@@ -39,9 +55,12 @@ export const EncounterClaimSpecs = [
     { key: EncounterClaim.Subject, meaning: 'Canonical subject reference.', example: 'did:web:patient.example.org' },
     { key: EncounterClaim.Patient, meaning: 'Patient alias reference.', example: 'did:web:patient.example.org' },
     { key: EncounterClaim.Participant, meaning: 'Participant references (CSV).', example: 'Practitioner/prac-1' },
+    { key: EncounterClaim.ServiceType, meaning: 'HealthcareService references (CSV in R5).', example: 'HealthcareService/emergency-department-1' },
     { key: EncounterClaim.ServiceProvider, meaning: 'Service provider reference.', example: 'Organization/org-1' },
     { key: EncounterClaim.PeriodStart, meaning: 'Encounter start.', example: '2026-06-01T10:00:00Z' },
     { key: EncounterClaim.PeriodEnd, meaning: 'Encounter end.', example: '2026-06-01T10:30:00Z' },
+    { key: EncounterClaim.ActualPeriodStart, meaning: 'R5 actual encounter start.', example: '2026-06-01T10:00:00Z' },
+    { key: EncounterClaim.ActualPeriodEnd, meaning: 'R5 actual encounter end.', example: '2026-06-01T10:30:00Z' },
     { key: EncounterClaim.ReasonCode, meaning: 'Reason code token.', example: 'http://snomed.info/sct|65363002' },
     { key: EncounterClaim.Diagnosis, meaning: 'Diagnosis references (CSV).', example: 'Condition/cond-1' },
     { key: EncounterClaim.Location, meaning: 'Location references (CSV).', example: 'Location/loc-1' },

package/dist/claims/encounter-history-claims.d.ts

@@ -0,0 +1,20 @@
+import type { ClaimSpec } from './claim-types.js';
+/** Canonical flat claims for the FHIR R5 EncounterHistory resource. */
+export declare const EncounterHistoryClaim: {
+    readonly Identifier: "EncounterHistory.identifier";
+    readonly Encounter: "EncounterHistory.encounter";
+    readonly Status: "EncounterHistory.status";
+    readonly Class: "EncounterHistory.class";
+    readonly Type: "EncounterHistory.type";
+    readonly ServiceType: "EncounterHistory.service-type";
+    readonly Subject: "EncounterHistory.subject";
+    readonly SubjectStatus: "EncounterHistory.subject-status";
+    readonly ActualPeriodStart: "EncounterHistory.actual-period-start";
+    readonly ActualPeriodEnd: "EncounterHistory.actual-period-end";
+    readonly PlannedStartDate: "EncounterHistory.planned-start-date";
+    readonly PlannedEndDate: "EncounterHistory.planned-end-date";
+    readonly Location: "EncounterHistory.location";
+    readonly LocationForm: "EncounterHistory.location-form";
+};
+export type EncounterHistoryClaimKey = typeof EncounterHistoryClaim[keyof typeof EncounterHistoryClaim];
+export declare const EncounterHistoryClaimSpecs: ClaimSpec[];

package/dist/claims/encounter-history-claims.js

@@ -0,0 +1,34 @@
+// Copyright 2026 Conéctate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
+/** Canonical flat claims for the FHIR R5 EncounterHistory resource. */
+export const EncounterHistoryClaim = {
+    Identifier: 'EncounterHistory.identifier',
+    Encounter: 'EncounterHistory.encounter',
+    Status: 'EncounterHistory.status',
+    Class: 'EncounterHistory.class',
+    Type: 'EncounterHistory.type',
+    ServiceType: 'EncounterHistory.service-type',
+    Subject: 'EncounterHistory.subject',
+    SubjectStatus: 'EncounterHistory.subject-status',
+    ActualPeriodStart: 'EncounterHistory.actual-period-start',
+    ActualPeriodEnd: 'EncounterHistory.actual-period-end',
+    PlannedStartDate: 'EncounterHistory.planned-start-date',
+    PlannedEndDate: 'EncounterHistory.planned-end-date',
+    Location: 'EncounterHistory.location',
+    LocationForm: 'EncounterHistory.location-form',
+};
+export const EncounterHistoryClaimSpecs = [
+    { key: EncounterHistoryClaim.Identifier, meaning: 'Business identifier.', example: 'urn:uuid:encounter-history-1' },
+    { key: EncounterHistoryClaim.Encounter, meaning: 'Encounter whose milestone is recorded.', example: 'Encounter/encounter-1' },
+    { key: EncounterHistoryClaim.Status, meaning: 'FHIR R5 Encounter status at this milestone.', example: 'on-hold' },
+    { key: EncounterHistoryClaim.Class, meaning: 'Encounter class token.', example: 'http://terminology.hl7.org/CodeSystem/v3-ActCode|EMER' },
+    { key: EncounterHistoryClaim.Type, meaning: 'Encounter type tokens (CSV).', example: 'http://snomed.info/sct|50849002' },
+    { key: EncounterHistoryClaim.ServiceType, meaning: 'HealthcareService references (CSV).', example: 'HealthcareService/emergency-1' },
+    { key: EncounterHistoryClaim.Subject, meaning: 'Patient or Group reference.', example: 'Patient/patient-1' },
+    { key: EncounterHistoryClaim.SubjectStatus, meaning: 'Subject status token.', example: 'departed' },
+    { key: EncounterHistoryClaim.ActualPeriodStart, meaning: 'Milestone period start.', example: '2026-09-29T08:00:00Z' },
+    { key: EncounterHistoryClaim.ActualPeriodEnd, meaning: 'Milestone period end.', example: '2026-09-29T08:30:00Z' },
+    { key: EncounterHistoryClaim.PlannedStartDate, meaning: 'Planned start.', example: '2026-09-29T08:00:00Z' },
+    { key: EncounterHistoryClaim.PlannedEndDate, meaning: 'Planned end.', example: '2026-09-29T08:30:00Z' },
+    { key: EncounterHistoryClaim.Location, meaning: 'Location references (CSV).', example: 'Location/emergency-box-1' },
+    { key: EncounterHistoryClaim.LocationForm, meaning: 'Location form token.', example: 'http://terminology.hl7.org/CodeSystem/location-physical-type|ro' },
+];

package/dist/claims/index.d.ts

@@ -16,6 +16,7 @@ export * from './device-use-statement-claims.js';
 export * from './diagnostic-report-claims.js';
 export * from './document-reference-claims.js';
 export * from './encounter-claims.js';
+export * from './encounter-history-claims.js';
 export * from './flag-claims.js';
 export * from './immunization-claims.js';
 export * from './immunization-recommendation-claims.js';

package/dist/claims/index.js

@@ -16,6 +16,7 @@ export * from './device-use-statement-claims.js';
 export * from './diagnostic-report-claims.js';
 export * from './document-reference-claims.js';
 export * from './encounter-claims.js';
+export * from './encounter-history-claims.js';
 export * from './flag-claims.js';
 export * from './immunization-claims.js';
 export * from './immunization-recommendation-claims.js';

package/dist/constants/fhir-resource-types.d.ts

@@ -116,6 +116,7 @@ export declare const FhirResourceTypes: Readonly<{
 }>;
 /** FHIR R5-only resources currently emitted by shared subscription contracts. */
 export declare const ResourceTypesFhirR5: Readonly<{
+    readonly EncounterHistory: "EncounterHistory";
     readonly Subscription: "Subscription";
     readonly SubscriptionTopic: "SubscriptionTopic";
     readonly SubscriptionStatus: "SubscriptionStatus";

package/dist/constants/fhir-resource-types.js

@@ -65,6 +65,7 @@ export const FhirResourceTypes = ResourceTypesFhirR4;
 /** FHIR R5-only resources currently emitted by shared subscription contracts. */
 export const ResourceTypesFhirR5 = Object.freeze({
     ...ResourceTypesFhirR4,
+    EncounterHistory: 'EncounterHistory',
     Subscription: 'Subscription',
     SubscriptionTopic: 'SubscriptionTopic',
     SubscriptionStatus: 'SubscriptionStatus',

package/dist/converters/convert-encounter-history.d.ts

@@ -0,0 +1,5 @@
+import type { FhirResource, FlatClaims } from './convert-shared.js';
+/** Materializes canonical EncounterHistory claims as native FHIR R5. */
+export declare function encounterHistoryFlatToFhirR5(claims: FlatClaims): FhirResource;
+/** Extracts supported native FHIR R5 EncounterHistory fields into flat claims. */
+export declare function encounterHistoryFhirR5ToFlat(resource: FhirResource): FlatClaims;

package/dist/converters/convert-encounter-history.js

@@ -0,0 +1,83 @@
+// Copyright 2026 Conéctate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
+import { EncounterHistoryClaim } from '../claims/encounter-history-claims.js';
+import { EncounterStatusR5 } from '../claims/encounter-claims.js';
+import { codingFromValue, codingToValue, referenceToValue } from './convert-shared.js';
+const R5_STATUSES = new Set(Object.values(EncounterStatusR5));
+/** Materializes canonical EncounterHistory claims as native FHIR R5. */
+export function encounterHistoryFlatToFhirR5(claims) {
+    const status = claims[EncounterHistoryClaim.Status];
+    if (!status || !R5_STATUSES.has(status))
+        throw new TypeError('encounter_history_r5_status_invalid');
+    const klass = claims[EncounterHistoryClaim.Class];
+    if (!klass)
+        throw new TypeError('encounter_history_r5_class_required');
+    return {
+        resourceType: 'EncounterHistory',
+        identifier: claims[EncounterHistoryClaim.Identifier] ? [{ value: claims[EncounterHistoryClaim.Identifier] }] : undefined,
+        encounter: claims[EncounterHistoryClaim.Encounter] ? { reference: claims[EncounterHistoryClaim.Encounter] } : undefined,
+        status,
+        class: { coding: codingFromValue(klass) },
+        type: concepts(claims[EncounterHistoryClaim.Type]),
+        serviceType: codeableReferences(claims[EncounterHistoryClaim.ServiceType]),
+        subject: claims[EncounterHistoryClaim.Subject] ? { reference: claims[EncounterHistoryClaim.Subject] } : undefined,
+        subjectStatus: claims[EncounterHistoryClaim.SubjectStatus] ? { coding: codingFromValue(claims[EncounterHistoryClaim.SubjectStatus]) } : undefined,
+        actualPeriod: period(claims[EncounterHistoryClaim.ActualPeriodStart], claims[EncounterHistoryClaim.ActualPeriodEnd]),
+        plannedStartDate: claims[EncounterHistoryClaim.PlannedStartDate],
+        plannedEndDate: claims[EncounterHistoryClaim.PlannedEndDate],
+        location: locations(claims[EncounterHistoryClaim.Location], claims[EncounterHistoryClaim.LocationForm]),
+    };
+}
+/** Extracts supported native FHIR R5 EncounterHistory fields into flat claims. */
+export function encounterHistoryFhirR5ToFlat(resource) {
+    const klass = resource.class;
+    const actualPeriod = resource.actualPeriod;
+    const location = resource.location?.[0];
+    return {
+        [EncounterHistoryClaim.Identifier]: resource.identifier?.[0]?.value,
+        [EncounterHistoryClaim.Encounter]: referenceToValue(resource.encounter),
+        [EncounterHistoryClaim.Status]: resource.status,
+        [EncounterHistoryClaim.Class]: codingToValue(klass?.coding?.[0]),
+        [EncounterHistoryClaim.Type]: conceptsToCsv(resource.type),
+        [EncounterHistoryClaim.ServiceType]: codeableReferencesToCsv(resource.serviceType),
+        [EncounterHistoryClaim.Subject]: referenceToValue(resource.subject),
+        [EncounterHistoryClaim.SubjectStatus]: codingToValue(resource.subjectStatus?.coding?.[0]),
+        [EncounterHistoryClaim.ActualPeriodStart]: actualPeriod?.start,
+        [EncounterHistoryClaim.ActualPeriodEnd]: actualPeriod?.end,
+        [EncounterHistoryClaim.PlannedStartDate]: resource.plannedStartDate,
+        [EncounterHistoryClaim.PlannedEndDate]: resource.plannedEndDate,
+        [EncounterHistoryClaim.Location]: location?.location?.reference,
+        [EncounterHistoryClaim.LocationForm]: codingToValue(location?.form?.coding?.[0]),
+    };
+}
+function period(start, end) {
+    return start || end ? { start, end } : undefined;
+}
+function concepts(value) {
+    const values = value?.split(',').map(item => item.trim()).filter(Boolean) ?? [];
+    return values.length ? values.map(item => ({ coding: codingFromValue(item) })) : undefined;
+}
+function conceptsToCsv(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const values = value.map(item => codingToValue(item?.coding?.[0])).filter(Boolean);
+    return values.length ? values.join(',') : undefined;
+}
+function codeableReferences(value) {
+    const values = value?.split(',').map(item => item.trim()).filter(Boolean) ?? [];
+    return values.length ? values.map(reference => ({ reference: { reference } })) : undefined;
+}
+function codeableReferencesToCsv(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const values = value.map(item => referenceToValue(item?.reference)).filter(Boolean);
+    return values.length ? values.join(',') : undefined;
+}
+function locations(locationValue, formValue) {
+    const values = locationValue?.split(',').map(item => item.trim()).filter(Boolean) ?? [];
+    if (!values.length)
+        return undefined;
+    return values.map((reference, index) => ({
+        location: { reference },
+        form: index === 0 && formValue ? { coding: codingFromValue(formValue) } : undefined,
+    }));
+}

package/dist/converters/convert-encounter.d.ts

@@ -1,3 +1,7 @@
 import type { FhirResource, FlatClaims } from './convert-shared.js';
 export declare function encounterFlatToFhirR4(claims: FlatClaims): FhirResource;
 export declare function encounterFhirR4ToFlat(resource: FhirResource): FlatClaims;
+/** Materializes canonical Encounter claims as native FHIR R5. */
+export declare function encounterFlatToFhirR5(claims: FlatClaims): FhirResource;
+/** Extracts the supported R5 Encounter fields into canonical flat claims. */
+export declare function encounterFhirR5ToFlat(resource: FhirResource): FlatClaims;

package/dist/converters/convert-encounter.js

@@ -1,6 +1,6 @@
 // Copyright 2026 Conéctate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
 // File: src/utils/convert-encounter.ts
-import { EncounterClaim } from '../claims/encounter-claims.js';
+import { EncounterClaim, EncounterStatusR5 } from '../claims/encounter-claims.js';
 import { codingFromValue, codingToValue, referenceListToCsv, referenceToValue } from './convert-shared.js';
 export function encounterFlatToFhirR4(claims) {
     const subject = claims[EncounterClaim.Subject] ?? claims[EncounterClaim.Patient];
@@ -72,3 +72,75 @@ export function encounterFhirR4ToFlat(resource) {
         [EncounterClaim.PartOf]: referenceToValue(resource.partOf),
     };
 }
+const R5_STATUSES = new Set(Object.values(EncounterStatusR5));
+/** Materializes canonical Encounter claims as native FHIR R5. */
+export function encounterFlatToFhirR5(claims) {
+    const status = claims[EncounterClaim.Status];
+    if (status && !R5_STATUSES.has(status))
+        throw new TypeError('encounter_r5_status_invalid');
+    const subject = claims[EncounterClaim.Subject] ?? claims[EncounterClaim.Patient];
+    const actualPeriodStart = claims[EncounterClaim.ActualPeriodStart] ?? claims[EncounterClaim.PeriodStart];
+    const actualPeriodEnd = claims[EncounterClaim.ActualPeriodEnd] ?? claims[EncounterClaim.PeriodEnd];
+    return {
+        resourceType: 'Encounter',
+        identifier: claims[EncounterClaim.Identifier] ? [{ value: claims[EncounterClaim.Identifier] }] : undefined,
+        appointment: referenceList(claims[EncounterClaim.Appointment]),
+        status,
+        class: claims[EncounterClaim.Class] ? { coding: codingFromValue(claims[EncounterClaim.Class]) } : undefined,
+        type: claims[EncounterClaim.Type] ? [{ coding: codingFromValue(claims[EncounterClaim.Type]) }] : undefined,
+        serviceType: codeableReferenceList(claims[EncounterClaim.ServiceType]),
+        subject: subject ? { reference: subject } : undefined,
+        participant: claims[EncounterClaim.Participant]
+            ? claims[EncounterClaim.Participant].split(',').map(reference => ({ actor: { reference: reference.trim() } }))
+            : undefined,
+        serviceProvider: claims[EncounterClaim.ServiceProvider] ? { reference: claims[EncounterClaim.ServiceProvider] } : undefined,
+        actualPeriod: (actualPeriodStart || actualPeriodEnd) ? { start: actualPeriodStart, end: actualPeriodEnd } : undefined,
+        location: claims[EncounterClaim.Location]
+            ? claims[EncounterClaim.Location].split(',').map(reference => ({ location: { reference: reference.trim() } }))
+            : undefined,
+        partOf: claims[EncounterClaim.PartOf] ? { reference: claims[EncounterClaim.PartOf] } : undefined,
+    };
+}
+/** Extracts the supported R5 Encounter fields into canonical flat claims. */
+export function encounterFhirR5ToFlat(resource) {
+    const klass = resource.class;
+    const actualPeriod = resource.actualPeriod;
+    return {
+        [EncounterClaim.Identifier]: resource.identifier?.[0]?.value,
+        [EncounterClaim.Appointment]: referenceListToCsv(resource.appointment),
+        [EncounterClaim.Status]: resource.status,
+        [EncounterClaim.Class]: codingToValue(klass?.coding?.[0]),
+        [EncounterClaim.Type]: codingToValue(resource.type?.[0]?.coding?.[0]),
+        [EncounterClaim.ServiceType]: codeableReferencesToCsv(resource.serviceType),
+        [EncounterClaim.Subject]: referenceToValue(resource.subject),
+        [EncounterClaim.Patient]: referenceToValue(resource.subject),
+        [EncounterClaim.Participant]: Array.isArray(resource.participant)
+            ? resource.participant.map(item => item.actor?.reference).filter(Boolean).join(',') || undefined
+            : undefined,
+        [EncounterClaim.ServiceProvider]: referenceToValue(resource.serviceProvider),
+        [EncounterClaim.ActualPeriodStart]: actualPeriod?.start,
+        [EncounterClaim.ActualPeriodEnd]: actualPeriod?.end,
+        [EncounterClaim.Location]: Array.isArray(resource.location)
+            ? resource.location.map(item => item.location?.reference).filter(Boolean).join(',') || undefined
+            : undefined,
+        [EncounterClaim.PartOf]: referenceToValue(resource.partOf),
+    };
+}
+function referenceList(value) {
+    const references = value?.split(',').map(reference => reference.trim()).filter(Boolean) ?? [];
+    return references.length ? references.map(reference => ({ reference })) : undefined;
+}
+function codeableReferenceList(value) {
+    const references = referenceList(value);
+    return references?.map(reference => ({ reference }));
+}
+function codeableReferencesToCsv(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const references = value.map(item => {
+        if (!item || typeof item !== 'object')
+            return undefined;
+        return referenceToValue(item.reference);
+    }).filter((item) => Boolean(item));
+    return references.length ? references.join(',') : undefined;
+}

package/dist/converters/index.d.ts

@@ -16,6 +16,7 @@ export * from './convert-device-metric.js';
 export * from './convert-diagnostic-report.js';
 export * from './convert-document-reference.js';
 export * from './convert-encounter.js';
+export * from './convert-encounter-history.js';
 export * from './convert-flag.js';
 export * from './convert-immunization.js';
 export * from './convert-imaging-study.js';

package/dist/converters/index.js

@@ -16,6 +16,7 @@ export * from './convert-device-metric.js';
 export * from './convert-diagnostic-report.js';
 export * from './convert-document-reference.js';
 export * from './convert-encounter.js';
+export * from './convert-encounter-history.js';
 export * from './convert-flag.js';
 export * from './convert-immunization.js';
 export * from './convert-imaging-study.js';

package/dist/converters/materialize-claims-first-resource.d.ts

@@ -1,6 +1,6 @@
 import type { FhirResource } from '../fhir-types.js';
 export type ClaimsFirstFhirResource = Readonly<{
-    resourceType: 'Organization' | 'HealthcareService' | 'Location' | 'Schedule' | 'Slot' | 'DeviceMetric' | 'Procedure' | 'RegulatedAuthorization' | 'DocumentReference';
+    resourceType: 'Organization' | 'HealthcareService' | 'Location' | 'Schedule' | 'Slot' | 'DeviceMetric' | 'Procedure' | 'RegulatedAuthorization' | 'DocumentReference' | 'Encounter' | 'EncounterHistory';
     id: string;
     meta: Readonly<{
         claims: Readonly<Record<string, unknown>>;

package/dist/converters/materialize-claims-first-resource.js

@@ -6,6 +6,8 @@ import { deviceMetricFlatToFhirR5 } from './convert-device-metric.js';
 import { procedureFlatToFhirR5 } from './convert-procedure.js';
 import { regulatedAuthorizationFlatToFhirR5 } from './convert-regulated-authorization.js';
 import { documentReferenceFlatToFhirR4 } from './convert-document-reference.js';
+import { encounterFlatToFhirR5 } from './convert-encounter.js';
+import { encounterHistoryFlatToFhirR5 } from './convert-encounter-history.js';
 const materializers = Object.freeze({
     Organization: organizationFlatToFhirR5,
     HealthcareService: healthcareServiceFlatToFhirR5,
@@ -16,6 +18,8 @@ const materializers = Object.freeze({
     Procedure: procedureFlatToFhirR5,
     RegulatedAuthorization: regulatedAuthorizationFlatToFhirR5,
     DocumentReference: documentReferenceFlatToFhirR4,
+    Encounter: encounterFlatToFhirR5,
+    EncounterHistory: encounterHistoryFlatToFhirR5,
 });
 /**
  * Materializes native FHIR R5 only at an explicit adapter boundary.

package/dist/encounter-transfer-test-data.d.ts

@@ -0,0 +1,41 @@
+import { EncounterStatusR5 } from './claims/encounter-claims.js';
+/** Product-neutral identifiers and references for cross-package Encounter transfer contract tests. */
+export declare const FHIR_ENCOUNTER_TRANSFER_TEST_DATA: Readonly<{
+    communicationIdentifier: "urn:uuid:00000000-0000-4000-8000-000000000401";
+    subjectReference: "Patient/00000000-0000-4000-8000-000000000402";
+    senderReference: "Organization/00000000-0000-4000-8000-000000000403";
+    indexRecipientReference: "Organization/00000000-0000-4000-8000-000000000404";
+    occurredAt: "2026-09-30T10:10:00Z";
+    invalidOccurredAtWithoutTimezone: "2026-09-30T10:10:00";
+    class: Readonly<{
+        system: "http://terminology.hl7.org/CodeSystem/v3-ActCode";
+        code: "EMER";
+    }>;
+    source: Readonly<{
+        id: "00000000-0000-4000-8000-000000000405";
+        reference: "Encounter/00000000-0000-4000-8000-000000000405";
+        identifier: "urn:uuid:00000000-0000-4000-8000-000000000405";
+        serviceReference: "HealthcareService/00000000-0000-4000-8000-000000000406";
+        locationReference: "Location/00000000-0000-4000-8000-000000000407";
+        statusWhenReturning: EncounterStatusR5.OnHold;
+        statusWhenNotReturning: EncounterStatusR5.Completed;
+    }>;
+    destination: Readonly<{
+        id: "00000000-0000-4000-8000-000000000408";
+        reference: "Encounter/00000000-0000-4000-8000-000000000408";
+        identifier: "urn:uuid:00000000-0000-4000-8000-000000000408";
+        serviceReference: "HealthcareService/00000000-0000-4000-8000-000000000409";
+        locationReference: "Location/00000000-0000-4000-8000-000000000410";
+        statusOnArrival: EncounterStatusR5.InProgress;
+    }>;
+    sourceHistory: Readonly<{
+        id: "00000000-0000-4000-8000-000000000411";
+        identifier: "urn:uuid:00000000-0000-4000-8000-000000000411";
+        encounterReference: "Encounter/00000000-0000-4000-8000-000000000405";
+    }>;
+    destinationHistory: Readonly<{
+        id: "00000000-0000-4000-8000-000000000412";
+        identifier: "urn:uuid:00000000-0000-4000-8000-000000000412";
+        encounterReference: "Encounter/00000000-0000-4000-8000-000000000408";
+    }>;
+}>;

package/dist/encounter-transfer-test-data.js

@@ -0,0 +1,38 @@
+import { EncounterStatusR5 } from './claims/encounter-claims.js';
+/** Product-neutral identifiers and references for cross-package Encounter transfer contract tests. */
+export const FHIR_ENCOUNTER_TRANSFER_TEST_DATA = Object.freeze({
+    communicationIdentifier: 'urn:uuid:00000000-0000-4000-8000-000000000401',
+    subjectReference: 'Patient/00000000-0000-4000-8000-000000000402',
+    senderReference: 'Organization/00000000-0000-4000-8000-000000000403',
+    indexRecipientReference: 'Organization/00000000-0000-4000-8000-000000000404',
+    occurredAt: '2026-09-30T10:10:00Z',
+    invalidOccurredAtWithoutTimezone: '2026-09-30T10:10:00',
+    class: Object.freeze({ system: 'http://terminology.hl7.org/CodeSystem/v3-ActCode', code: 'EMER' }),
+    source: Object.freeze({
+        id: '00000000-0000-4000-8000-000000000405',
+        reference: 'Encounter/00000000-0000-4000-8000-000000000405',
+        identifier: 'urn:uuid:00000000-0000-4000-8000-000000000405',
+        serviceReference: 'HealthcareService/00000000-0000-4000-8000-000000000406',
+        locationReference: 'Location/00000000-0000-4000-8000-000000000407',
+        statusWhenReturning: EncounterStatusR5.OnHold,
+        statusWhenNotReturning: EncounterStatusR5.Completed,
+    }),
+    destination: Object.freeze({
+        id: '00000000-0000-4000-8000-000000000408',
+        reference: 'Encounter/00000000-0000-4000-8000-000000000408',
+        identifier: 'urn:uuid:00000000-0000-4000-8000-000000000408',
+        serviceReference: 'HealthcareService/00000000-0000-4000-8000-000000000409',
+        locationReference: 'Location/00000000-0000-4000-8000-000000000410',
+        statusOnArrival: EncounterStatusR5.InProgress,
+    }),
+    sourceHistory: Object.freeze({
+        id: '00000000-0000-4000-8000-000000000411',
+        identifier: 'urn:uuid:00000000-0000-4000-8000-000000000411',
+        encounterReference: 'Encounter/00000000-0000-4000-8000-000000000405',
+    }),
+    destinationHistory: Object.freeze({
+        id: '00000000-0000-4000-8000-000000000412',
+        identifier: 'urn:uuid:00000000-0000-4000-8000-000000000412',
+        encounterReference: 'Encounter/00000000-0000-4000-8000-000000000408',
+    }),
+});

package/dist/fhir-instant.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Derives whole Unix epoch seconds from a valid FHIR `instant`.
+ *
+ * A FHIR instant remains the authoritative ISO 8601 value with a timezone.
+ * Epoch seconds are a derived numeric representation and must never replace
+ * `Encounter.id`, `Encounter.identifier`, or the original clinical time.
+ */
+export declare function fhirInstantToEpochSeconds(instant: string): number;

package/dist/fhir-instant.js

@@ -0,0 +1,16 @@
+const FHIR_INSTANT_PATTERN = /^\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/;
+/**
+ * Derives whole Unix epoch seconds from a valid FHIR `instant`.
+ *
+ * A FHIR instant remains the authoritative ISO 8601 value with a timezone.
+ * Epoch seconds are a derived numeric representation and must never replace
+ * `Encounter.id`, `Encounter.identifier`, or the original clinical time.
+ */
+export function fhirInstantToEpochSeconds(instant) {
+    if (!FHIR_INSTANT_PATTERN.test(instant))
+        throw new TypeError('fhir_instant_invalid');
+    const epochMilliseconds = Date.parse(instant);
+    if (!Number.isFinite(epochMilliseconds))
+        throw new TypeError('fhir_instant_invalid');
+    return Math.floor(epochMilliseconds / 1000);
+}

package/dist/index.d.ts

@@ -26,3 +26,5 @@ export * from './imaging-types.js';
 export * from './subscription-r5.js';
 export * from './healthcare-service-specialty-map.js';
 export * from './appointment-communication-test-data.js';
+export * from './encounter-transfer-test-data.js';
+export * from './fhir-instant.js';

package/dist/index.js

@@ -26,3 +26,5 @@ export * from './imaging-types.js';
 export * from './subscription-r5.js';
 export * from './healthcare-service-specialty-map.js';
 export * from './appointment-communication-test-data.js';
+export * from './encounter-transfer-test-data.js';
+export * from './fhir-instant.js';

package/docs/ENCOUNTER_IDENTIFIERS_AND_TIME.md

@@ -0,0 +1,19 @@
+# Encounter identifiers and time
+
+FHIR time and encounter identity are separate concepts.
+
+- A FHIR `instant` is an ISO 8601 date and time with at least second precision
+  and an explicit timezone. It is not a Unix timestamp.
+- Unix epoch seconds may be derived for sorting, interoperability or a
+  provider-owned business identifier, but they never replace the original
+  instant.
+- `Encounter.id` is the FHIR resource identifier.
+- `Encounter.identifier` contains the business identifiers assigned by the
+  care provider. Their namespace and uniqueness belong to the assigning
+  organization.
+- A display code is not sufficient authorization or subject resolution. An
+  authoritative lookup must also verify the assigner and exact subject.
+
+Reusable test data lives in `FHIR_ENCOUNTER_TRANSFER_TEST_DATA`. Tests and
+downstream documentation import its named fields instead of duplicating raw
+identifiers, timestamps or references.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fhir-data-utils-ts",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "FHIR-version-neutral flat-claim and SearchParameter data utilities",
   "license": "Apache-2.0",
   "type": "module",