fhir-data-utils-ts 0.2.4 → 0.3.1

package/.codex/skills/govern-fhir-data-utilities/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: govern-fhir-data-utilities
+description: Complete or audit migrations, claim catalogs, converters, builders, tests and releases in fhir-data-utils-ts. Use for shared FHIR types or utilities copied from frozen gdc-common-utils, former UHC utilities, SOS, Vet or UHC packages; raw flat-claim literals; duplicate root and family modules; Observation components; Immunization graphs; Group or ResearchStudy projections; package exports; coverage gates; or downstream promotion.
+---
+
+# Govern FHIR Data Utilities
+
+## Keep ownership explicit
+
+1. Read `docs/UHC_FHIR_UTILS_MIGRATION.md` and inventory every relevant source
+   family before declaring a migration complete.
+2. Treat `gdc-*` repositories as read-only evidence unless the user explicitly
+   changes that scope. Never patch them as part of this migration.
+3. Keep neutral FHIR data semantics here. Keep HTTP, SMART, DIDComm, storage,
+   authorization and product policy in their owning services or sector packages.
+4. Define every flat key once in its owning named catalog. Import that symbol in
+   converters, builders, tests and examples; never repeat a claim-path literal.
+
+## Separate catalogs, adapters and builders
+
+- Put claim names and specs under `src/claims/`.
+- Put native FHIR R4/R5 projection at `src/converters/`; persistence remains
+  flat claims and native FHIR exists only at an explicit adapter boundary.
+- Put multi-resource authoring under `src/builders/`. A root historical module
+  may remain only as a deprecated re-export shim so implementation is unique.
+- Preserve correlations by creating one claims-first row per member, party or
+  component when parallel arrays would lose identity.
+- Reconstruct native arrays such as `Observation.component[]` only during FHIR
+  projection. Do not invent resource-specific scalar aliases for indexing.
+- Keep Group membership and ResearchStudy associated parties descriptive;
+  neither is a Consent, SMART scope or authorization grant.
+
+## Change with executable contracts
+
+1. Use Node 24 and run `npm ci` before trusting failures.
+2. Begin every new or modified test file with the repository flow-contract
+   comment.
+3. Write and run the smallest failing test first. Cover success, malformed
+   input, lossless round trip, catalog ownership and packed public exports.
+4. Add data-rich converter fixtures that exercise meaningful optional fields;
+   a single happy-path assertion is not adequate migration evidence.
+5. Run `npm run check`. Preserve the built-in coverage floors for converters,
+   builders and core FHIR utilities; raise them when practical, never lower them
+   to make a branch green.
+6. Run `npm pack --dry-run`, then install the produced tarball in an isolated
+   temporary consumer and resolve every documented subpath.
+
+## Release without partial promotion
+
+1. Update JSDoc, tests, README, migration inventory, changelog and this skill in
+   the same behavior branch.
+2. Use one patch release for one branch closure. Commit and push the branch,
+   create an explicit merge commit, push `main`, and verify matching remote refs
+   and a clean worktree.
+3. Publish this lowest shared package before changing consumers. Verify the
+   exact registry version exists before pinning it downstream.
+4. Never commit `file:`, Git, workspace or vendored tarball dependencies.
+5. Report local green, merged, published and deployed as separate states.

package/.codex/skills/govern-fhir-data-utilities/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Govern FHIR Data Utilities"
+  short_description: "Keep FHIR catalogs, builders and releases complete"
+  default_prompt: "Use $govern-fhir-data-utilities to migrate or change shared FHIR data contracts safely."

package/.codex/skills/govern-fhir-observation-components/SKILL.md

@@ -36,6 +36,10 @@ description: Implement or audit neutral FHIR Observation claim catalogs, vital-s
   composite observations.
 - Reconstruct native `Observation.component[]` only at the explicit R4/R5
   adapter boundary by resolving the primary entry's governed member graph.
+- Use `observationFhirR4ToFlatGraph` for native component imports and
+  `observationFlatGraphToFhirR4` for export. The scalar
+  `observationFhirR4ToFlat` adapter must fail with
+  `observation_component_graph_required` when `component[]` is present.
 
 ## Reuse governed names
 
@@ -62,6 +66,20 @@ description: Implement or audit neutral FHIR Observation claim catalogs, vital-s
    catalog and against child-owned containment markers.
 5. Run Node 24, `npm ci`, `npm run check` and `npm pack --dry-run`.
 
+## Audit migrations completely
+
+- Inventory the old UHC package, `gdc-common-utils-ts`, `sos-data-utils-ts`,
+  `vet-data-utils-ts`, and the UHC/Vet/SOS SDKs before calling a migration
+  complete.
+- Move only neutral FHIR data types, claim catalogs, conversion rules and pure
+  helpers here. Keep transport clients and sector authorization/policy in
+  their owning package.
+- Record every migrated, retired or intentionally retained family in
+  `docs/UHC_FHIR_UTILS_MIGRATION.md`; an unmentioned file is an incomplete
+  audit.
+- Expose each supported family through a stable package subpath and prove the
+  packed artifact, not only root source imports.
+
 ## Promote consumers
 
 Release bottom-up. Publish this package first, install its exact registry

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 0.3.1 - 2026-09-21
+
+- Separate canonical claim catalogs from graph builders and move Immunization
+  graph/reminder implementations under the stable `builders` subpaths, leaving
+  their historical root paths as deprecated compatibility re-exports.
+- Add missing Medication and ImmunizationRecommendation catalogs, Group and
+  ResearchStudy named claim constants, legacy-read aliases and missing neutral
+  FHIR resource type constants; remove duplicated flat-claim literals from
+  builders and converters.
+- Correct impossible calendar-date acceptance, empty list persistence and
+  nested `meta.claims` leakage through generic fallback flattening.
+- Expand executable contracts to the complete converter/helper matrix, rich
+  optional resource fields, FHIR primitives/search/Bundle behavior,
+  Immunization graphs and Group/ResearchStudy row boundaries.
+- Enforce coverage and packed-subpath gates as part of the release contract.
+
+## 0.3.0 - 2026-09-21
+
+- Consolidate the complete product-neutral claim catalogs, claim helpers and
+  R4/R5 converters previously exposed from `gdc-common-utils-ts`, without
+  modifying that frozen source repository.
+- Recover strict FHIR primitives, value/search/token utilities, Bundle readers,
+  resource search/template types, terminology model types, RelatedPerson and
+  telecom helpers, and DICOMDIR structural types from the retired UHC package.
+- Move cross-sector terminology, Immunization graph/reminder, Group R5 and
+  ResearchStudy R5 contracts that existed only in SOS or Vet data packages.
+- Require component Observations to use independently indexable graph entries;
+  deprecated JSON-array component claims remain read-only compatibility input.
+- Add stable package subpaths for every migrated contract family.
+
 ## 0.2.4 - 2026-09-21
 
 - Restore the canonical composite-Observation resource graph: the primary

package/README.md

@@ -29,6 +29,32 @@ through `<ResourceType>.contained-reference-list`; children do not carry
 as `<ResourceType>.language`, `.narrative-status` and `.xhtml`. Native FHIR is
 materialized only by an explicit R4/R5/R6 import or export adapter.
 
+## Public contract
+
+The root export and stable subpaths provide:
+
+- strict version-neutral FHIR datatypes, value/token helpers, Bundle traversal
+  and typed search parsing/building;
+- complete flat-claim catalogs and claim helpers for the resource families
+  formerly scattered through `gdc-common-utils-ts`;
+- explicit R4/R5 conversion adapters, including Consent and PractitionerRole;
+- the recovered UHC resource search/template types, terminology model types,
+  RelatedPerson/telecom helpers and type-only DICOMDIR tree contract;
+- cross-sector terminology, Immunization graphs/reminders, and FHIR R5 Group
+  and ResearchStudy contracts previously located only in SOS or Vet packages.
+
+Claim catalogs and graph builders are deliberately different surfaces.
+`fhir-data-utils-ts/claims` owns canonical storage names and their specs;
+`fhir-data-utils-ts/builders` authors correlated multi-resource graphs using
+those catalogs. The old `/immunization-flat-claims` and
+`/immunization-reminder-plan` paths are deprecated compatibility re-exports;
+new code imports `/builders` or `/builders/immunization`.
+
+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
+`/research-study-r5` as appropriate.
+
 ## Observation components
 
 Composite observations use a claims-first resource graph. The primary
@@ -44,6 +70,12 @@ aliases are read-only compatibility inputs. Current writers emit none of them.
 Components never use `is-contained`, `contained-parent-reference` or the
 generic contained-resource link.
 
+This is why blood pressure does not have writable `bp-*` claims. Systolic and
+diastolic are independently indexed reduced Observation rows linked by the
+parent's `Observation.has-member`; the R4/R5 adapter alone reconstructs native
+`component[]`. The same representation works for future assessment scales
+without inventing a new flat-claim family for each scale.
+
 `buildVitalSignObservation` owns the graph, canonical displays and optional
 `Observation.user-selected` provenance flag. Consumers submit its `entries`
 without reconstructing component claims or relationships.
@@ -70,3 +102,10 @@ DataConv, Vet and UHC share one neutral review contract from
 The package exports builders, traversal/confirmation helpers and
 `CODING_REVIEW_EXAMPLES`. Tests and consumers reuse them instead of duplicating
 claim strings, terminology identifiers, codes or UUIDs.
+
+## Verification gate
+
+`npm run check` runs strict type checking, all contract tests and built-in
+coverage over converters, builders and core FHIR utilities. The package also
+tests every stable export subpath. Release validation additionally inspects the
+packed artifact and installs it in an isolated consumer before publication.

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

@@ -0,0 +1,36 @@
+import { type FlatClaimResourceEntry } from '../flat-claim-resource-graph.js';
+import { type ImmunizationReminderChannel } from './immunization-reminders.js';
+export type ImmunizationCoding = Readonly<{
+    system: string;
+    code: string;
+    display?: string;
+    text?: string;
+}>;
+export type ImmunizationFlatInput = Readonly<{
+    entryId: string;
+    identifier?: string;
+    subjectReference: string;
+    administrationDate: string;
+    vaccineCode: ImmunizationCoding;
+    performerReference?: string;
+    targetDiseases?: readonly ImmunizationCoding[];
+    nextDoseDate?: string;
+    /** FHIR dateTime when the recommendation was created; required with nextDoseDate. */
+    recommendationDate?: string;
+    reminderChannels?: readonly ImmunizationReminderChannel[];
+    medication?: Readonly<{
+        entryId: string;
+        productName: string;
+        identifiers?: readonly Readonly<{
+            system: string;
+            value: string;
+        }>[];
+        manufacturer?: string;
+        lotNumber?: string;
+        expirationDate?: string;
+        barcode?: string;
+    }>;
+    attachments?: readonly 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

@@ -0,0 +1,115 @@
+// Copyright 2026 ConnectHealth.info (Connecting Solution & Applications Ltd.) under the Apache License, Version 2.0.
+import { buildFlatClaimResourceEntry, linkFlatClaimResourceEntries, } from '../flat-claim-resource-graph.js';
+import { buildImmunizationReminderTasks, ImmunizationReminderChannels, } from './immunization-reminders.js';
+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';
+/** Builds the shared claims-first human/animal immunization resource graph. */
+export function buildImmunizationFlatGraph(input) {
+    const vaccineCode = codingToken(input.vaccineCode);
+    const claims = {
+        [ImmunizationClaim.Status]: 'completed',
+        [ImmunizationClaim.Patient]: required(input.subjectReference, 'immunization_subject_required'),
+        [ImmunizationClaim.Date]: isoDate(input.administrationDate, 'immunization_date_invalid'),
+        [ImmunizationClaim.VaccineCode]: vaccineCode,
+    };
+    if (input.identifier)
+        claims[ImmunizationClaim.Identifier] = required(input.identifier, 'immunization_identifier_invalid');
+    if (input.vaccineCode.display?.trim())
+        claims[ImmunizationClaim.VaccineCodeDisplay] = input.vaccineCode.display.trim();
+    if (input.vaccineCode.text?.trim())
+        claims[ImmunizationClaim.VaccineCodeText] = input.vaccineCode.text.trim();
+    if (input.performerReference)
+        claims[ImmunizationClaim.Performer] = required(input.performerReference, 'immunization_performer_invalid');
+    if (input.targetDiseases?.length) {
+        claims[ImmunizationClaim.TargetDisease] = input.targetDiseases.map(codingToken).join(',');
+        claims[ImmunizationClaim.TargetDiseaseDisplay] = input.targetDiseases.map(value => value.display?.trim() ?? '').join(',');
+        claims[ImmunizationClaim.TargetDiseaseText] = input.targetDiseases.map(value => value.text?.trim() ?? '').join(',');
+    }
+    const immunization = buildFlatClaimResourceEntry({ entryId: input.entryId, resourceType: ResourceTypesFhirR4.Immunization, claims });
+    const children = [];
+    if (input.medication)
+        children.push(buildMedicationEntry(input.medication));
+    if (input.nextDoseDate) {
+        const recommendationId = `${input.entryId}-recommendation`;
+        const recommendation = buildFlatClaimResourceEntry({
+            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}`,
+            },
+        });
+        const tasks = buildImmunizationReminderTasks({
+            entryIdPrefix: recommendationId,
+            recommendationReference: recommendation.reference,
+            subjectReference: input.subjectReference,
+            coverageEndDate: input.nextDoseDate,
+            channelCandidates: input.reminderChannels ?? ImmunizationReminderChannels,
+        });
+        children.push(recommendation, ...tasks);
+    }
+    for (const attachment of input.attachments ?? []) {
+        if (attachment.resourceType !== ResourceTypesFhirR4.DocumentReference)
+            throw new TypeError('immunization_attachment_invalid');
+        children.push(attachment);
+    }
+    const graph = [immunization, ...children];
+    const linkedToImmunization = children.length
+        ? linkFlatClaimResourceEntries(graph, {
+            parentEntryId: input.entryId,
+            childEntryIds: children.filter(entry => entry.resourceType !== ResourceTypesFhirR4.Task).map(entry => entry.entryId),
+        })
+        : graph;
+    const recommendation = linkedToImmunization.find(entry => entry.resourceType === ResourceTypesFhirR4.ImmunizationRecommendation);
+    const tasks = linkedToImmunization.filter(entry => entry.resourceType === ResourceTypesFhirR4.Task);
+    return recommendation && tasks.length
+        ? linkFlatClaimResourceEntries(linkedToImmunization, {
+            parentEntryId: recommendation.entryId,
+            childEntryIds: tasks.map(entry => entry.entryId),
+        })
+        : linkedToImmunization;
+}
+function buildMedicationEntry(input) {
+    const claims = {
+        [MedicationClaim.Code]: required(input.productName, 'medication_product_required'),
+        [MedicationClaim.CodeText]: required(input.productName, 'medication_product_required'),
+    };
+    if (input.identifiers?.length)
+        claims[MedicationClaim.Identifier] = input.identifiers
+            .map(({ system, value }) => `${required(system, 'medication_identifier_invalid')}|${required(value, 'medication_identifier_invalid')}`)
+            .join(',');
+    if (input.manufacturer?.trim())
+        claims[MedicationClaim.Manufacturer] = input.manufacturer.trim();
+    if (input.lotNumber?.trim())
+        claims[MedicationClaim.LotNumber] = input.lotNumber.trim();
+    if (input.expirationDate)
+        claims[MedicationClaim.ExpirationDate] = isoDate(input.expirationDate, 'medication_expiration_date_invalid');
+    if (input.barcode?.trim())
+        claims[MedicationClaim.SerialNumber] = input.barcode.trim();
+    return buildFlatClaimResourceEntry({ entryId: input.entryId, resourceType: ResourceTypesFhirR4.Medication, claims });
+}
+function codingToken(value) {
+    return `${required(value.system, 'immunization_coding_system_required')}|${required(value.code, 'immunization_coding_code_required')}`;
+}
+function isoDate(value, error) {
+    const normalized = required(value, error);
+    const match = /^(\d{4})-(\d{2})-(\d{2})(?:T.*)?$/.exec(normalized);
+    if (!match || Number.isNaN(Date.parse(normalized)))
+        throw new TypeError(error);
+    const calendarDate = new Date(Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3])));
+    if (calendarDate.toISOString().slice(0, 10) !== `${match[1]}-${match[2]}-${match[3]}`)
+        throw new TypeError(error);
+    return normalized;
+}
+function required(value, error) {
+    if (typeof value !== 'string' || !value.trim())
+        throw new TypeError(error);
+    return value.trim();
+}

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

@@ -0,0 +1,35 @@
+import { type FlatClaimResourceEntry } from '../flat-claim-resource-graph.js';
+export declare const ImmunizationReminderTaskValues: Readonly<{
+    readonly Status: "requested";
+    readonly Intent: "order";
+    readonly Code: "immunization-reminder";
+    readonly TriggerType: "scheduled";
+}>;
+export declare const ImmunizationReminderChannels: readonly ["push", "email", "sms", "whatsapp", "telephone"];
+export type ImmunizationReminderChannel = (typeof ImmunizationReminderChannels)[number];
+export type ImmunizationReminderPlanInput = Readonly<{
+    entryIdPrefix: string;
+    recommendationReference: string;
+    subjectReference: string;
+    coverageEndDate: string;
+    /** Ordered delivery candidates; dispatch must filter them by current preferences and Consent. */
+    channelCandidates: readonly ImmunizationReminderChannel[];
+}>;
+export type ImmunizationReminderDispatchState = Readonly<{
+    channelCandidates: readonly ImmunizationReminderChannel[];
+    attemptedChannels: readonly ImmunizationReminderChannel[];
+    enabledPreferences: readonly ImmunizationReminderChannel[];
+    consentedChannels: readonly ImmunizationReminderChannel[];
+    acknowledged: boolean;
+}>;
+/**
+ * Builds the three notification Tasks attached to an ImmunizationRecommendation.
+ * Task creation is automatic; actual delivery is a separate runtime decision
+ * that rechecks channel preference, Consent and prior acknowledgement.
+ */
+export declare function buildImmunizationReminderTasks(input: ImmunizationReminderPlanInput): readonly FlatClaimResourceEntry[];
+/**
+ * Selects one next delivery channel without bypassing the subject's current
+ * preferences or Consent. Acknowledgement ends escalation immediately.
+ */
+export declare function selectNextImmunizationReminderChannel(state: ImmunizationReminderDispatchState): ImmunizationReminderChannel | undefined;

package/dist/builders/immunization-reminders.js

@@ -0,0 +1,104 @@
+// Copyright 2026 ConnectHealth.info (Connecting Solution & Applications Ltd.) under the Apache License, Version 2.0.
+import { buildFlatClaimResourceEntry } from '../flat-claim-resource-graph.js';
+import { TaskClaim } from '../claims/task-claims.js';
+import { ResourceTypesFhirR4 } from '../constants/fhir-resource-types.js';
+export const ImmunizationReminderTaskValues = Object.freeze({
+    Status: 'requested',
+    Intent: 'order',
+    Code: 'immunization-reminder',
+    TriggerType: 'scheduled',
+});
+export const ImmunizationReminderChannels = Object.freeze([
+    'push',
+    'email',
+    'sms',
+    'whatsapp',
+    'telephone',
+]);
+const OFFSETS = Object.freeze([
+    Object.freeze({ suffix: '1m', subtract: subtractOneCalendarMonth }),
+    Object.freeze({ suffix: '1w', subtract: (date) => subtractUtcDays(date, 7) }),
+    Object.freeze({ suffix: '1d', subtract: (date) => subtractUtcDays(date, 1) }),
+]);
+/**
+ * Builds the three notification Tasks attached to an ImmunizationRecommendation.
+ * Task creation is automatic; actual delivery is a separate runtime decision
+ * that rechecks channel preference, Consent and prior acknowledgement.
+ */
+export function buildImmunizationReminderTasks(input) {
+    const prefix = required(input.entryIdPrefix, 'immunization_reminder_entry_id_required');
+    const recommendation = required(input.recommendationReference, 'immunization_recommendation_reference_required');
+    const subject = required(input.subjectReference, 'immunization_reminder_subject_required');
+    const coverageEnd = parseIsoDate(input.coverageEndDate);
+    const channels = [...new Set(input.channelCandidates)].filter((channel) => ImmunizationReminderChannels.includes(channel));
+    if (channels.length === 0)
+        throw new TypeError('immunization_reminder_channels_required');
+    return Object.freeze(OFFSETS.map(({ suffix, subtract }) => {
+        const entryId = `${prefix}-reminder-${suffix}`;
+        return buildFlatClaimResourceEntry({
+            entryId,
+            resourceType: ResourceTypesFhirR4.Task,
+            claims: {
+                [TaskClaim.Identifier]: `urn:uuid:${entryId}`,
+                [TaskClaim.GroupIdentifier]: recommendation,
+                [TaskClaim.Status]: ImmunizationReminderTaskValues.Status,
+                [TaskClaim.Intent]: ImmunizationReminderTaskValues.Intent,
+                [TaskClaim.Code]: ImmunizationReminderTaskValues.Code,
+                [TaskClaim.For]: subject,
+                [TaskClaim.Focus]: recommendation,
+                [TaskClaim.BasedOn]: recommendation,
+                [TaskClaim.ScheduledAt]: formatIsoDate(subtract(coverageEnd)),
+                [TaskClaim.TriggerType]: ImmunizationReminderTaskValues.TriggerType,
+                [TaskClaim.Channel]: channels.join(','),
+                [TaskClaim.Attempt]: '0',
+                [TaskClaim.MaxAttempts]: String(channels.length),
+                [TaskClaim.Confirmed]: 'false',
+            },
+        });
+    }));
+}
+/**
+ * Selects one next delivery channel without bypassing the subject's current
+ * preferences or Consent. Acknowledgement ends escalation immediately.
+ */
+export function selectNextImmunizationReminderChannel(state) {
+    if (state.acknowledged)
+        return undefined;
+    const attempted = new Set(state.attemptedChannels);
+    const preferred = new Set(state.enabledPreferences);
+    const consented = new Set(state.consentedChannels);
+    return state.channelCandidates.find((channel) => ImmunizationReminderChannels.includes(channel)
+        && !attempted.has(channel)
+        && preferred.has(channel)
+        && consented.has(channel));
+}
+function parseIsoDate(value) {
+    const normalized = required(value, 'immunization_coverage_end_date_invalid');
+    const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(normalized);
+    if (!match)
+        throw new TypeError('immunization_coverage_end_date_invalid');
+    const date = new Date(Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3])));
+    if (formatIsoDate(date) !== normalized)
+        throw new TypeError('immunization_coverage_end_date_invalid');
+    return date;
+}
+function subtractOneCalendarMonth(date) {
+    const year = date.getUTCFullYear();
+    const month = date.getUTCMonth();
+    const targetMonth = month === 0 ? 11 : month - 1;
+    const targetYear = month === 0 ? year - 1 : year;
+    const lastDay = new Date(Date.UTC(targetYear, targetMonth + 1, 0)).getUTCDate();
+    return new Date(Date.UTC(targetYear, targetMonth, Math.min(date.getUTCDate(), lastDay)));
+}
+function subtractUtcDays(date, days) {
+    return new Date(date.getTime() - days * 86_400_000);
+}
+function formatIsoDate(date) {
+    return date.toISOString().slice(0, 10);
+}
+function required(value, error) {
+    const normalized = String(value ?? '').trim();
+    if (!normalized)
+        throw new TypeError(error);
+    return normalized;
+}

package/dist/builders/index.d.ts

@@ -0,0 +1,2 @@
+export * from './immunization-graph.js';
+export * from './immunization-reminders.js';

package/dist/builders/index.js

@@ -0,0 +1,2 @@
+export * from './immunization-graph.js';
+export * from './immunization-reminders.js';

package/dist/claim-helpers/claim-list-helpers.d.ts

@@ -0,0 +1,21 @@
+export type GenericInteroperableClaims = Record<string, unknown>;
+export declare function splitClaimCsv(value: unknown): string[];
+export declare function normalizeClaimTokens(values: readonly string[]): string[];
+export declare function normalizeClaimInput(values: string | readonly string[]): string[];
+export declare function normalizeClaimScalar(value: unknown): string;
+/**
+ * Returns the tokenized values for a claims field stored as CSV.
+ */
+export declare function getClaimValues(claims: GenericInteroperableClaims, claimKey: string): string[];
+/**
+ * Replaces a claims CSV field with the provided values.
+ */
+export declare function setClaimValues(claims: GenericInteroperableClaims, claimKey: string, values: string | readonly string[]): GenericInteroperableClaims;
+/**
+ * Adds one or many values into a claims CSV field while preserving uniqueness.
+ */
+export declare function addClaimValues(claims: GenericInteroperableClaims, claimKey: string, values: string | readonly string[]): GenericInteroperableClaims;
+/**
+ * Removes one or many values from a claims CSV field while preserving uniqueness.
+ */
+export declare function removeClaimValues(claims: GenericInteroperableClaims, claimKey: string, values: string | readonly string[]): GenericInteroperableClaims;

package/dist/claim-helpers/claim-list-helpers.js

@@ -0,0 +1,54 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+export function splitClaimCsv(value) {
+    return String(value || '')
+        .split(',')
+        .map((item) => item.trim())
+        .filter(Boolean);
+}
+export function normalizeClaimTokens(values) {
+    return [...new Set(values.map((value) => String(value || '').trim()).filter(Boolean))];
+}
+export function normalizeClaimInput(values) {
+    return Array.isArray(values)
+        ? normalizeClaimTokens(values)
+        : normalizeClaimTokens(splitClaimCsv(values));
+}
+export function normalizeClaimScalar(value) {
+    return String(value || '').trim();
+}
+/**
+ * Returns the tokenized values for a claims field stored as CSV.
+ */
+export function getClaimValues(claims, claimKey) {
+    return normalizeClaimTokens(splitClaimCsv(claims[claimKey]));
+}
+/**
+ * Replaces a claims CSV field with the provided values.
+ */
+export function setClaimValues(claims, claimKey, values) {
+    const nextValues = normalizeClaimInput(values);
+    if (nextValues.length === 0) {
+        const { [claimKey]: _removed, ...remaining } = claims;
+        return remaining;
+    }
+    return {
+        ...claims,
+        [claimKey]: nextValues.join(','),
+    };
+}
+/**
+ * Adds one or many values into a claims CSV field while preserving uniqueness.
+ */
+export function addClaimValues(claims, claimKey, values) {
+    const current = getClaimValues(claims, claimKey);
+    const additions = normalizeClaimInput(values);
+    return setClaimValues(claims, claimKey, [...current, ...additions]);
+}
+/**
+ * Removes one or many values from a claims CSV field while preserving uniqueness.
+ */
+export function removeClaimValues(claims, claimKey, values) {
+    const removals = new Set(normalizeClaimInput(values));
+    const nextValues = getClaimValues(claims, claimKey).filter((value) => !removals.has(value));
+    return setClaimValues(claims, claimKey, nextValues);
+}

package/dist/claim-helpers/claims-helpers-allergy-intolerance.d.ts

@@ -0,0 +1,18 @@
+import { type GenericInteroperableClaims } from './claim-list-helpers.js';
+export type AllergyIntoleranceInteroperableClaims = GenericInteroperableClaims;
+export declare function getAllergyIntoleranceClaimList(claims: AllergyIntoleranceInteroperableClaims, claimKey: string): string[];
+export declare function setAllergyIntoleranceClaimList(claims: AllergyIntoleranceInteroperableClaims, claimKey: string, values: string | readonly string[]): AllergyIntoleranceInteroperableClaims;
+export declare function addAllergyIntoleranceClaimList(claims: AllergyIntoleranceInteroperableClaims, claimKey: string, values: string | readonly string[]): AllergyIntoleranceInteroperableClaims;
+export declare function removeAllergyIntoleranceClaimList(claims: AllergyIntoleranceInteroperableClaims, claimKey: string, values: string | readonly string[]): AllergyIntoleranceInteroperableClaims;
+export declare function getAllergyIntoleranceContainedResourceReferenceList(claims: AllergyIntoleranceInteroperableClaims): string[];
+export declare function setAllergyIntoleranceContainedResourceReferenceList(claims: AllergyIntoleranceInteroperableClaims, values: string | readonly string[]): AllergyIntoleranceInteroperableClaims;
+export declare function addAllergyIntoleranceContainedResourceReferenceList(claims: AllergyIntoleranceInteroperableClaims, values: string | readonly string[]): AllergyIntoleranceInteroperableClaims;
+export declare function removeAllergyIntoleranceContainedResourceReferenceList(claims: AllergyIntoleranceInteroperableClaims, values: string | readonly string[]): AllergyIntoleranceInteroperableClaims;
+/** @deprecated Use `getAllergyIntoleranceContainedResourceReferenceList`. */
+export declare function getAllergyIntoleranceContainedDocumentIdentifierList(claims: AllergyIntoleranceInteroperableClaims): string[];
+/** @deprecated Use `setAllergyIntoleranceContainedResourceReferenceList`. */
+export declare function setAllergyIntoleranceContainedDocumentIdentifierList(claims: AllergyIntoleranceInteroperableClaims, values: string | readonly string[]): AllergyIntoleranceInteroperableClaims;
+/** @deprecated Use `addAllergyIntoleranceContainedResourceReferenceList`. */
+export declare function addAllergyIntoleranceContainedDocumentIdentifierList(claims: AllergyIntoleranceInteroperableClaims, values: string | readonly string[]): AllergyIntoleranceInteroperableClaims;
+/** @deprecated Use `removeAllergyIntoleranceContainedResourceReferenceList`. */
+export declare function removeAllergyIntoleranceContainedDocumentIdentifierList(claims: AllergyIntoleranceInteroperableClaims, values: string | readonly string[]): AllergyIntoleranceInteroperableClaims;

package/dist/claim-helpers/claims-helpers-allergy-intolerance.js

@@ -0,0 +1,65 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+import { AllergyIntoleranceClaim } from '../claims/allergy-intolerance-claims.js';
+import { addClaimValues, getClaimValues, removeClaimValues, setClaimValues, } from './claim-list-helpers.js';
+export function getAllergyIntoleranceClaimList(claims, claimKey) {
+    return getClaimValues(claims, claimKey);
+}
+export function setAllergyIntoleranceClaimList(claims, claimKey, values) {
+    return setClaimValues(claims, claimKey, values);
+}
+export function addAllergyIntoleranceClaimList(claims, claimKey, values) {
+    return addClaimValues(claims, claimKey, values);
+}
+export function removeAllergyIntoleranceClaimList(claims, claimKey, values) {
+    return removeClaimValues(claims, claimKey, values);
+}
+export function getAllergyIntoleranceContainedResourceReferenceList(claims) {
+    return uniqueCsvLists([
+        getAllergyIntoleranceClaimList(claims, AllergyIntoleranceClaim.ContainedReferenceList),
+        getAllergyIntoleranceClaimList(claims, AllergyIntoleranceClaim.ContainedDocuments),
+        getAllergyIntoleranceClaimList(claims, AllergyIntoleranceClaim.AttachmentContentIds),
+    ]);
+}
+export function setAllergyIntoleranceContainedResourceReferenceList(claims, values) {
+    return setContainedResources(claims, values);
+}
+export function addAllergyIntoleranceContainedResourceReferenceList(claims, values) {
+    return setContainedResources(claims, uniqueCsvLists([
+        getAllergyIntoleranceContainedResourceReferenceList(claims),
+        Array.isArray(values) ? [...values] : getAllergyIntoleranceClaimList({ [AllergyIntoleranceClaim.ContainedReferenceList]: values }, AllergyIntoleranceClaim.ContainedReferenceList),
+    ]));
+}
+export function removeAllergyIntoleranceContainedResourceReferenceList(claims, values) {
+    const toRemove = new Set((Array.isArray(values) ? values : getAllergyIntoleranceClaimList({ [AllergyIntoleranceClaim.ContainedReferenceList]: values }, AllergyIntoleranceClaim.ContainedReferenceList))
+        .map((item) => String(item || '').trim())
+        .filter(Boolean));
+    return setContainedResources(claims, getAllergyIntoleranceContainedResourceReferenceList(claims).filter((item) => !toRemove.has(item)));
+}
+/** @deprecated Use `getAllergyIntoleranceContainedResourceReferenceList`. */
+export function getAllergyIntoleranceContainedDocumentIdentifierList(claims) {
+    return getAllergyIntoleranceContainedResourceReferenceList(claims);
+}
+/** @deprecated Use `setAllergyIntoleranceContainedResourceReferenceList`. */
+export function setAllergyIntoleranceContainedDocumentIdentifierList(claims, values) {
+    return setAllergyIntoleranceContainedResourceReferenceList(claims, values);
+}
+/** @deprecated Use `addAllergyIntoleranceContainedResourceReferenceList`. */
+export function addAllergyIntoleranceContainedDocumentIdentifierList(claims, values) {
+    return addAllergyIntoleranceContainedResourceReferenceList(claims, values);
+}
+/** @deprecated Use `removeAllergyIntoleranceContainedResourceReferenceList`. */
+export function removeAllergyIntoleranceContainedDocumentIdentifierList(claims, values) {
+    return removeAllergyIntoleranceContainedResourceReferenceList(claims, values);
+}
+function setContainedResources(claims, values) {
+    const next = setAllergyIntoleranceClaimList(claims, AllergyIntoleranceClaim.ContainedReferenceList, values);
+    const cleaned = {
+        ...next,
+    };
+    delete cleaned[AllergyIntoleranceClaim.ContainedDocuments];
+    delete cleaned[AllergyIntoleranceClaim.AttachmentContentIds];
+    return cleaned;
+}
+function uniqueCsvLists(lists) {
+    return [...new Set(lists.flatMap((list) => list.map((item) => String(item || '').trim()).filter(Boolean)))];
+}