fhir-data-utils-ts 0.6.17 → 0.6.19

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+- Add the official `HealthcareService.appointmentRequired` flat claim and
+  R4/R5 materialization round trip. Availability remains authoritative in the
+  associated Schedule and Slot resources and is not duplicated on the service.
+
+## 0.6.18 - 2026-10-08
+
+- Add the canonical Immunization series-dose claim, its FHIR R4 round trip,
+  reusable dose-order validation and a standalone claims-first
+  ImmunizationRecommendation builder for progressive clinical authoring.
+
 ## 0.6.17 - 2026-10-08
 
 - Add the preferred HL7 Observation category catalogue for shared clinical

package/dist/builders/immunization-graph.d.ts

@@ -32,5 +32,17 @@ export type ImmunizationFlatInput = Readonly<{
     }>;
     attachments?: readonly FlatClaimResourceEntry[];
 }>;
+export type ImmunizationRecommendationFlatInput = Readonly<{
+    entryId: string;
+    immunizationEntryId: string;
+    subjectReference: string;
+    recommendationDate: string;
+    nextDoseDate: string;
+    vaccineCode: ImmunizationCoding;
+}>;
+/** Validates the optional positive dose number and its optional series total. */
+export declare function validateImmunizationDoseSeries(doseSequence?: string, seriesDoses?: string): void;
+/** Builds the recommendation related to one staged Immunization without reminder transport. */
+export declare function buildImmunizationRecommendationFlatEntry(input: ImmunizationRecommendationFlatInput): FlatClaimResourceEntry;
 /** Builds the shared claims-first human/animal immunization resource graph. */
 export declare function buildImmunizationFlatGraph(input: ImmunizationFlatInput): readonly FlatClaimResourceEntry[];

package/dist/builders/immunization-graph.js

@@ -5,6 +5,30 @@ import { ImmunizationClaim } from '../claims/immunization-claims.js';
 import { ImmunizationRecommendationClaim, ImmunizationRecommendationCodes, } from '../claims/immunization-recommendation-claims.js';
 import { MedicationClaim } from '../claims/medication-claims.js';
 import { ResourceTypesFhirR4 } from '../constants/fhir-resource-types.js';
+/** Validates the optional positive dose number and its optional series total. */
+export function validateImmunizationDoseSeries(doseSequence, seriesDoses) {
+    const dose = positiveInteger(doseSequence, 'immunization_dose_sequence_invalid');
+    const total = positiveInteger(seriesDoses, 'immunization_series_doses_invalid');
+    if (dose !== undefined && total !== undefined && total < dose) {
+        throw new TypeError('immunization_series_doses_invalid');
+    }
+}
+/** Builds the recommendation related to one staged Immunization without reminder transport. */
+export function buildImmunizationRecommendationFlatEntry(input) {
+    return buildFlatClaimResourceEntry({
+        entryId: required(input.entryId, 'immunization_recommendation_id_required'),
+        resourceType: ResourceTypesFhirR4.ImmunizationRecommendation,
+        claims: {
+            [ImmunizationRecommendationClaim.Patient]: required(input.subjectReference, 'immunization_subject_required'),
+            [ImmunizationRecommendationClaim.Date]: isoDate(input.recommendationDate, 'immunization_recommendation_date_invalid'),
+            [ImmunizationRecommendationClaim.VaccineCode]: codingToken(input.vaccineCode),
+            [ImmunizationRecommendationClaim.ForecastStatus]: ImmunizationRecommendationCodes.ForecastDue,
+            [ImmunizationRecommendationClaim.DateCriterionCode]: ImmunizationRecommendationCodes.RecommendedDate,
+            [ImmunizationRecommendationClaim.DateCriterionValue]: isoDate(input.nextDoseDate, 'immunization_next_dose_date_invalid'),
+            [ImmunizationRecommendationClaim.SupportingImmunization]: `${ResourceTypesFhirR4.Immunization}/${required(input.immunizationEntryId, 'immunization_id_required')}`,
+        },
+    });
+}
 /** Builds the shared claims-first human/animal immunization resource graph. */
 export function buildImmunizationFlatGraph(input) {
     const vaccineCode = codingToken(input.vaccineCode);
@@ -33,18 +57,13 @@ export function buildImmunizationFlatGraph(input) {
         children.push(buildMedicationEntry(input.medication));
     if (input.nextDoseDate) {
         const recommendationId = `${input.entryId}-recommendation`;
-        const recommendation = buildFlatClaimResourceEntry({
+        const recommendation = buildImmunizationRecommendationFlatEntry({
             entryId: recommendationId,
-            resourceType: ResourceTypesFhirR4.ImmunizationRecommendation,
-            claims: {
-                [ImmunizationRecommendationClaim.Patient]: input.subjectReference,
-                [ImmunizationRecommendationClaim.Date]: isoDate(required(input.recommendationDate, 'immunization_recommendation_date_required'), 'immunization_recommendation_date_invalid'),
-                [ImmunizationRecommendationClaim.VaccineCode]: vaccineCode,
-                [ImmunizationRecommendationClaim.ForecastStatus]: ImmunizationRecommendationCodes.ForecastDue,
-                [ImmunizationRecommendationClaim.DateCriterionCode]: ImmunizationRecommendationCodes.RecommendedDate,
-                [ImmunizationRecommendationClaim.DateCriterionValue]: isoDate(input.nextDoseDate, 'immunization_next_dose_date_invalid'),
-                [ImmunizationRecommendationClaim.SupportingImmunization]: `${ResourceTypesFhirR4.Immunization}/${input.entryId}`,
-            },
+            immunizationEntryId: input.entryId,
+            subjectReference: input.subjectReference,
+            recommendationDate: required(input.recommendationDate, 'immunization_recommendation_date_required'),
+            nextDoseDate: input.nextDoseDate,
+            vaccineCode: input.vaccineCode,
         });
         const tasks = buildImmunizationReminderTasks({
             entryIdPrefix: recommendationId,
@@ -113,3 +132,10 @@ function required(value, error) {
         throw new TypeError(error);
     return value.trim();
 }
+function positiveInteger(value, error) {
+    if (value === undefined || value === '')
+        return undefined;
+    if (!/^\d+$/.test(value) || Number(value) <= 0)
+        throw new TypeError(error);
+    return Number(value);
+}

package/dist/claims/healthcare-service-claims.d.ts

@@ -8,6 +8,7 @@ import type { ClaimSpec } from './claim-types.js';
  */
 export declare const HealthcareServiceClaim: Readonly<{
     readonly Active: "HealthcareService.active";
+    readonly AppointmentRequired: "HealthcareService.appointment-required";
     readonly Characteristic: "HealthcareService.characteristic";
     readonly CoverageArea: "HealthcareService.coverage-area";
     readonly Endpoint: "HealthcareService.endpoint";

package/dist/claims/healthcare-service-claims.js

@@ -9,6 +9,7 @@ import { defineFlatSearchParameter } from '../search-parameters.js';
  */
 export const HealthcareServiceClaim = Object.freeze({
     Active: 'HealthcareService.active',
+    AppointmentRequired: 'HealthcareService.appointment-required',
     Characteristic: 'HealthcareService.characteristic',
     CoverageArea: 'HealthcareService.coverage-area',
     Endpoint: 'HealthcareService.endpoint',
@@ -39,6 +40,7 @@ export const HealthcareServiceR4SearchParameterCatalog = Object.freeze([
 ]);
 export const HealthcareServiceClaimSpecs = Object.freeze([
     { key: HealthcareServiceClaim.Active, meaning: 'Whether the service is active.', example: 'true' },
+    { key: HealthcareServiceClaim.AppointmentRequired, meaning: 'Whether an appointment is required before receiving the service.', example: 'true' },
     { key: HealthcareServiceClaim.Characteristic, meaning: 'Repeatable service characteristic tokens as CSV.', example: 'https://example.org/CodeSystem/service-characteristic|24-hours' },
     { key: HealthcareServiceClaim.CoverageArea, meaning: 'Repeatable intended coverage Location references as CSV.', example: 'Location/british-columbia' },
     { key: HealthcareServiceClaim.Endpoint, meaning: 'Repeatable technical Endpoint references as CSV.', example: 'Endpoint/emergency-group-inbox' },

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

@@ -20,6 +20,7 @@ export declare const ImmunizationClaim: {
     readonly VaccineCodeText: "Immunization.vaccine-code-text";
     readonly VaccineCodeDisplay: "Immunization.vaccine-code-display";
     readonly DoseSequence: "Immunization.dose-sequence";
+    readonly SeriesDoses: "Immunization.series-doses";
     readonly Subject: "Immunization.subject";
     readonly Note: "Immunization.note";
     readonly Route: "Immunization.route";

package/dist/claims/immunization-claims.js

@@ -21,6 +21,7 @@ export const ImmunizationClaim = {
     VaccineCodeText: 'Immunization.vaccine-code-text',
     VaccineCodeDisplay: 'Immunization.vaccine-code-display',
     DoseSequence: 'Immunization.dose-sequence',
+    SeriesDoses: 'Immunization.series-doses',
     Subject: 'Immunization.subject',
     Note: 'Immunization.note',
     Route: 'Immunization.route',
@@ -49,6 +50,7 @@ export const ImmunizationClaimSpecs = [
     { key: ImmunizationClaim.VaccineCodeText, meaning: 'Local-language vaccine label used by forms/UI.', example: 'Vacuna COVID-19' },
     { key: ImmunizationClaim.VaccineCodeDisplay, meaning: 'Canonical/international vaccine display label.', example: 'COVID-19 vaccine' },
     { key: ImmunizationClaim.DoseSequence, meaning: 'Dose sequence string.', example: '2' },
+    { key: ImmunizationClaim.SeriesDoses, meaning: 'Total number of doses in the vaccination series.', example: '3' },
     { key: ImmunizationClaim.Subject, meaning: 'Canonical subject reference.', example: 'did:web:patient.example.org' },
     { key: ImmunizationClaim.Note, meaning: 'Clinical note text.', example: 'No adverse reaction recorded.' },
 ];

package/dist/converters/convert-healthcare-service.js

@@ -23,6 +23,9 @@ export function healthcareServiceFlatToFhirR4(claims) {
         active: claims[HealthcareServiceClaim.Active] === undefined
             ? undefined
             : claims[HealthcareServiceClaim.Active] === 'true',
+        appointmentRequired: claims[HealthcareServiceClaim.AppointmentRequired] === undefined
+            ? undefined
+            : claims[HealthcareServiceClaim.AppointmentRequired] === 'true',
         providedBy: claims[HealthcareServiceClaim.Organization]
             ? { reference: claims[HealthcareServiceClaim.Organization] }
             : undefined,
@@ -42,6 +45,9 @@ export function healthcareServiceFlatToFhirR4(claims) {
 export function healthcareServiceFhirR4ToFlat(resource) {
     return {
         [HealthcareServiceClaim.Active]: resource.active === undefined ? undefined : String(resource.active),
+        [HealthcareServiceClaim.AppointmentRequired]: resource.appointmentRequired === undefined
+            ? undefined
+            : String(resource.appointmentRequired),
         [HealthcareServiceClaim.Characteristic]: conceptsToCsv(resource.characteristic),
         [HealthcareServiceClaim.CoverageArea]: referenceListToCsv(resource.coverageArea),
         [HealthcareServiceClaim.Endpoint]: referenceListToCsv(resource.endpoint),

package/dist/converters/convert-immunization.js

@@ -33,12 +33,15 @@ export function immunizationFlatToFhirR4(claims) {
         reasonReference: claims[ImmunizationClaim.ReasonReference] ? [{ reference: claims[ImmunizationClaim.ReasonReference] }] : undefined,
         statusReason: claims[ImmunizationClaim.StatusReason] ? { coding: codingFromValue(claims[ImmunizationClaim.StatusReason]) } : undefined,
         note: claims[ImmunizationClaim.Note] ? [{ text: claims[ImmunizationClaim.Note] }] : undefined,
-        protocolApplied: (claims[ImmunizationClaim.Series] || claims[ImmunizationClaim.TargetDisease] || claims[ImmunizationClaim.DoseSequence]) ? [{
+        protocolApplied: (claims[ImmunizationClaim.Series] || claims[ImmunizationClaim.TargetDisease] || claims[ImmunizationClaim.DoseSequence] || claims[ImmunizationClaim.SeriesDoses]) ? [{
                 series: claims[ImmunizationClaim.Series],
                 targetDisease: claims[ImmunizationClaim.TargetDisease] ? [{ coding: codingFromValue(claims[ImmunizationClaim.TargetDisease]) }] : undefined,
                 ...(claims[ImmunizationClaim.DoseSequence] && /^\d+$/.test(claims[ImmunizationClaim.DoseSequence])
                     ? { doseNumberPositiveInt: Number(claims[ImmunizationClaim.DoseSequence]) }
                     : { doseNumberString: claims[ImmunizationClaim.DoseSequence] }),
+                ...(claims[ImmunizationClaim.SeriesDoses] && /^\d+$/.test(claims[ImmunizationClaim.SeriesDoses])
+                    ? { seriesDosesPositiveInt: Number(claims[ImmunizationClaim.SeriesDoses]) }
+                    : {}),
             }] : undefined,
         reaction: claims[ImmunizationClaim.ReactionDate] ? [{ date: claims[ImmunizationClaim.ReactionDate] }] : undefined,
     };
@@ -70,6 +73,9 @@ export function immunizationFhirR4ToFlat(resource) {
         [ImmunizationClaim.DoseSequence]: protocolApplied?.doseNumberPositiveInt === undefined
             ? protocolApplied?.doseNumberString
             : String(protocolApplied.doseNumberPositiveInt),
+        [ImmunizationClaim.SeriesDoses]: protocolApplied?.seriesDosesPositiveInt === undefined
+            ? protocolApplied?.seriesDosesString
+            : String(protocolApplied.seriesDosesPositiveInt),
         [ImmunizationClaim.Subject]: referenceToValue(resource.patient),
         [ImmunizationClaim.Note]: resource.note?.[0]?.text,
         [ImmunizationClaim.Route]: codingToValue(resource.route?.coding?.[0]),

package/docs/HEALTHCARE_SERVICE_DEPARTMENT_CATALOG.md

@@ -18,6 +18,12 @@ donation independently. Each service can own different Location references and
 be the actor of a different Schedule; Slot duration and availability follow
 that Schedule rather than the department.
 
+`HealthcareService.appointmentRequired` states whether a person or animal must
+have an appointment before receiving the service. It does not describe when
+the service is available. Operational availability remains authoritative in
+the service's `Schedule` and its `Slot` resources; clients must not copy those
+intervals into a second service-level availability model.
+
 `buildServiceScheduleFlatGraph(...)` implements that boundary. It emits one
 independent claims-first `Schedule` plus independent `Slot` rows. A 15-minute
 blood-donation interval and a one-hour plasma-donation interval are represented
@@ -143,6 +149,9 @@ Repeatable coding identities remain complete `system|code` tokens; labels are
 resolved by the terminology service and are not trusted storage identity.
 `HealthcareService.comment` and R5 `Organization.description` are governed
 materialization claims, but are not falsely advertised as R4 SearchParameters.
+The same applies to `HealthcareService.appointmentRequired`: it is an official
+R4/R5 element and a governed materialization claim, not a resource-specific R4
+SearchParameter.
 
 `materializeClaimsFirstResourceToFhirR5(...)` accepts only minimal resource
 identity plus `resource.meta.claims`. It rejects nested native FHIR fields and

package/package.json

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