fhir-data-utils-ts 0.3.7 → 0.6.0

package/dist/converters/convert-organization.js

@@ -1,7 +1,7 @@
 // Copyright 2026 Conéctate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
 // File: src/convert/convert-organization.ts
 import { OrganizationClaim } from '../claims/organization-claims.js';
-import { codingFromValue, codingToValue, referenceToValue } from './convert-shared.js';
+import { codingFromValue, codingToValue, identifierFromValue, identifierToValue, referenceToValue } from './convert-shared.js';
 function splitCsv(value) {
     return String(value || '')
         .split(',')
@@ -11,7 +11,7 @@ function splitCsv(value) {
 export function organizationFlatToFhirR4(claims) {
     return {
         resourceType: 'Organization',
-        identifier: claims[OrganizationClaim.Identifier] ? [{ value: claims[OrganizationClaim.Identifier] }] : undefined,
+        identifier: claims[OrganizationClaim.Identifier] ? [identifierFromValue(claims[OrganizationClaim.Identifier])] : undefined,
         active: claims[OrganizationClaim.Active] === undefined ? undefined : claims[OrganizationClaim.Active] === 'true',
         type: claims[OrganizationClaim.Type] ? [{ coding: codingFromValue(claims[OrganizationClaim.Type]) }] : undefined,
         name: claims[OrganizationClaim.Name],
@@ -27,7 +27,7 @@ export function organizationFhirR4ToFlat(resource) {
         ?.map((item) => item?.value)
         .filter((item) => Boolean(item));
     return {
-        [OrganizationClaim.Identifier]: resource.identifier?.[0]?.value,
+        [OrganizationClaim.Identifier]: identifierToValue(resource.identifier?.[0]),
         [OrganizationClaim.Active]: resource.active === undefined ? undefined : String(resource.active),
         [OrganizationClaim.Type]: codingToValue(resource.type?.[0]?.coding?.[0]),
         [OrganizationClaim.Name]: resource.name,
@@ -37,3 +37,20 @@ export function organizationFhirR4ToFlat(resource) {
         [OrganizationClaim.Address]: resource.address?.[0]?.text,
     };
 }
+/** Materializes canonical Organization claims as native FHIR R5. */
+export function organizationFlatToFhirR5(claims) {
+    const identifier = identifierFromValue(claims[OrganizationClaim.Identifier]);
+    const telecom = splitCsv(claims[OrganizationClaim.Telecom]).map((value) => ({ value }));
+    const address = claims[OrganizationClaim.Address] ? [{ text: claims[OrganizationClaim.Address] }] : [];
+    return {
+        resourceType: 'Organization',
+        identifier: identifier ? [identifier] : undefined,
+        active: claims[OrganizationClaim.Active] === undefined ? undefined : claims[OrganizationClaim.Active] === 'true',
+        type: claims[OrganizationClaim.Type] ? [{ coding: codingFromValue(claims[OrganizationClaim.Type]) }] : undefined,
+        name: claims[OrganizationClaim.Name],
+        alias: splitCsv(claims[OrganizationClaim.Alias]),
+        description: claims[OrganizationClaim.Description],
+        partOf: claims[OrganizationClaim.PartOf] ? { reference: claims[OrganizationClaim.PartOf] } : undefined,
+        contact: telecom.length || address.length ? [{ telecom, address }] : undefined,
+    };
+}

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

@@ -1,3 +1,5 @@
 import type { FhirResource, FlatClaims } from './convert-shared.js';
 export declare function procedureFlatToFhirR4(claims: FlatClaims): FhirResource;
 export declare function procedureFhirR4ToFlat(resource: FhirResource): FlatClaims;
+/** Explicit FHIR R5 projection, including equipment calibration and inspection. */
+export declare function procedureFlatToFhirR5(claims: FlatClaims): FhirResource;

package/dist/converters/convert-procedure.js

@@ -62,3 +62,24 @@ export function procedureFhirR4ToFlat(resource) {
         [ProcedureClaim.Note]: resource.note?.[0]?.text,
     };
 }
+/** Explicit FHIR R5 projection, including equipment calibration and inspection. */
+export function procedureFlatToFhirR5(claims) {
+    const resource = procedureFlatToFhirR4(claims);
+    const { performedDateTime, reasonCode, reasonReference, ...common } = resource;
+    return {
+        ...common,
+        occurrenceDateTime: performedDateTime,
+        reason: reasonCode || reasonReference
+            ? [
+                ...(Array.isArray(reasonCode) ? reasonCode.map(concept => ({ concept })) : []),
+                ...(Array.isArray(reasonReference) ? reasonReference.map(reference => ({ reference })) : []),
+            ]
+            : undefined,
+        focalDevice: claims[ProcedureClaim.FocalDevice]
+            ? claims[ProcedureClaim.FocalDevice].split(',').map(reference => ({ manipulated: { reference: reference.trim() } }))
+            : undefined,
+        report: claims[ProcedureClaim.Report]
+            ? claims[ProcedureClaim.Report].split(',').map(reference => ({ reference: reference.trim() }))
+            : undefined,
+    };
+}

package/dist/converters/convert-regulated-authorization.d.ts

@@ -0,0 +1,3 @@
+import type { FhirResource, FlatClaims } from './convert-shared.js';
+export declare function regulatedAuthorizationFlatToFhirR5(claims: FlatClaims): FhirResource;
+export declare function regulatedAuthorizationFhirR5ToFlat(resource: FhirResource): FlatClaims;

package/dist/converters/convert-regulated-authorization.js

@@ -0,0 +1,34 @@
+import { RegulatedAuthorizationClaim } from '../claims/regulated-authorization-claims.js';
+import { codingFromValue, codingToValue, referenceToValue } from './convert-shared.js';
+export function regulatedAuthorizationFlatToFhirR5(claims) {
+    return {
+        resourceType: 'RegulatedAuthorization',
+        identifier: claims[RegulatedAuthorizationClaim.Identifier] ? [{ value: claims[RegulatedAuthorizationClaim.Identifier] }] : undefined,
+        subject: claims[RegulatedAuthorizationClaim.Subject] ? claims[RegulatedAuthorizationClaim.Subject].split(',').map(reference => ({ reference: reference.trim() })) : undefined,
+        type: claims[RegulatedAuthorizationClaim.Type] ? { coding: codingFromValue(claims[RegulatedAuthorizationClaim.Type]) } : undefined,
+        region: claims[RegulatedAuthorizationClaim.Region] ? [{ coding: codingFromValue(claims[RegulatedAuthorizationClaim.Region]) }] : undefined,
+        status: claims[RegulatedAuthorizationClaim.Status] ? { coding: [{ code: claims[RegulatedAuthorizationClaim.Status] }] } : undefined,
+        statusDate: claims[RegulatedAuthorizationClaim.StatusDate],
+        validityPeriod: claims[RegulatedAuthorizationClaim.ValidityStart] || claims[RegulatedAuthorizationClaim.ValidityEnd]
+            ? { start: claims[RegulatedAuthorizationClaim.ValidityStart], end: claims[RegulatedAuthorizationClaim.ValidityEnd] }
+            : undefined,
+        basis: claims[RegulatedAuthorizationClaim.Basis] ? [{ coding: codingFromValue(claims[RegulatedAuthorizationClaim.Basis]) }] : undefined,
+        holder: claims[RegulatedAuthorizationClaim.Holder] ? { reference: claims[RegulatedAuthorizationClaim.Holder] } : undefined,
+        regulator: claims[RegulatedAuthorizationClaim.Regulator] ? { reference: claims[RegulatedAuthorizationClaim.Regulator] } : undefined,
+    };
+}
+export function regulatedAuthorizationFhirR5ToFlat(resource) {
+    return {
+        [RegulatedAuthorizationClaim.Identifier]: resource.identifier?.[0]?.value,
+        [RegulatedAuthorizationClaim.Subject]: Array.isArray(resource.subject) ? resource.subject.map(item => item.reference).filter(Boolean).join(',') || undefined : undefined,
+        [RegulatedAuthorizationClaim.Type]: codingToValue(resource.type?.coding?.[0]),
+        [RegulatedAuthorizationClaim.Region]: codingToValue(resource.region?.[0]?.coding?.[0]),
+        [RegulatedAuthorizationClaim.Status]: resource.status?.coding?.[0]?.code,
+        [RegulatedAuthorizationClaim.StatusDate]: resource.statusDate,
+        [RegulatedAuthorizationClaim.ValidityStart]: resource.validityPeriod?.start,
+        [RegulatedAuthorizationClaim.ValidityEnd]: resource.validityPeriod?.end,
+        [RegulatedAuthorizationClaim.Basis]: codingToValue(resource.basis?.[0]?.coding?.[0]),
+        [RegulatedAuthorizationClaim.Holder]: referenceToValue(resource.holder),
+        [RegulatedAuthorizationClaim.Regulator]: referenceToValue(resource.regulator),
+    };
+}

package/dist/converters/convert-schedule-slot.d.ts

@@ -0,0 +1,9 @@
+import type { FhirResource, FlatClaims } from './convert-shared.js';
+/** Materializes canonical Schedule claims as native FHIR R5. */
+export declare function scheduleFlatToFhirR5(claims: FlatClaims): FhirResource;
+/** Extracts official Schedule search claims plus required materialization fields. */
+export declare function scheduleFhirR5ToFlat(resource: FhirResource): FlatClaims;
+/** Materializes canonical Slot claims as native FHIR R5. */
+export declare function slotFlatToFhirR5(claims: FlatClaims): FhirResource;
+/** Extracts official Slot search claims plus required materialization fields. */
+export declare function slotFhirR5ToFlat(resource: FhirResource): FlatClaims;

package/dist/converters/convert-schedule-slot.js

@@ -0,0 +1,96 @@
+// Copyright 2026 Conéctate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
+import { ScheduleClaim, SlotClaim } from '../claims/schedule-slot-claims.js';
+import { codingListFromCsv, codingListToCsv, identifierFromValue, identifierToValue, referenceListToCsv, referenceToValue, } from './convert-shared.js';
+const splitCsv = (value) => String(value || '').split(',').map(item => item.trim()).filter(Boolean);
+const referencesFromCsv = (value) => {
+    const values = splitCsv(value);
+    return values.length ? values.map(reference => ({ reference })) : undefined;
+};
+const conceptsFromCsv = (value) => {
+    const codings = codingListFromCsv(value);
+    return codings?.map(coding => ({ coding: [coding] }));
+};
+const conceptsToCsv = (value) => codingListToCsv((Array.isArray(value) ? value : []).flatMap(item => item && typeof item === 'object' && Array.isArray(item.coding)
+    ? item.coding ?? []
+    : []));
+const codeableReferencesFromClaims = (concepts, references) => {
+    const conceptList = conceptsFromCsv(concepts) ?? [];
+    const referenceList = referencesFromCsv(references) ?? [];
+    const length = Math.max(conceptList.length, referenceList.length);
+    if (!length)
+        return undefined;
+    return Array.from({ length }, (_, index) => ({
+        ...(conceptList[index] ? { concept: conceptList[index] } : {}),
+        ...(referenceList[index] ? { reference: referenceList[index] } : {}),
+    }));
+};
+const conceptsFromCodeableReferences = (value) => conceptsToCsv((Array.isArray(value) ? value : []).map(item => item?.concept));
+const referencesFromCodeableReferences = (value) => referenceListToCsv((Array.isArray(value) ? value : []).map(item => item?.reference ?? {}));
+/** Materializes canonical Schedule claims as native FHIR R5. */
+export function scheduleFlatToFhirR5(claims) {
+    return {
+        resourceType: 'Schedule',
+        identifier: claims[ScheduleClaim.Identifier] ? [identifierFromValue(claims[ScheduleClaim.Identifier])] : undefined,
+        active: claims[ScheduleClaim.Active] === undefined ? undefined : claims[ScheduleClaim.Active] === 'true',
+        serviceCategory: conceptsFromCsv(claims[ScheduleClaim.ServiceCategory]),
+        serviceType: codeableReferencesFromClaims(claims[ScheduleClaim.ServiceType], claims[ScheduleClaim.ServiceTypeReference]),
+        specialty: conceptsFromCsv(claims[ScheduleClaim.Specialty]),
+        name: claims[ScheduleClaim.Name],
+        actor: referencesFromCsv(claims[ScheduleClaim.Actor]),
+        planningHorizon: claims[ScheduleClaim.PlanningHorizonStart] || claims[ScheduleClaim.PlanningHorizonEnd]
+            ? { start: claims[ScheduleClaim.PlanningHorizonStart], end: claims[ScheduleClaim.PlanningHorizonEnd] }
+            : undefined,
+        comment: claims[ScheduleClaim.Comment],
+    };
+}
+/** Extracts official Schedule search claims plus required materialization fields. */
+export function scheduleFhirR5ToFlat(resource) {
+    const planningHorizon = resource.planningHorizon;
+    return {
+        [ScheduleClaim.Identifier]: identifierToValue(resource.identifier?.[0]),
+        [ScheduleClaim.Active]: resource.active === undefined ? undefined : String(resource.active),
+        [ScheduleClaim.ServiceCategory]: conceptsToCsv(resource.serviceCategory),
+        [ScheduleClaim.ServiceType]: conceptsFromCodeableReferences(resource.serviceType),
+        [ScheduleClaim.ServiceTypeReference]: referencesFromCodeableReferences(resource.serviceType),
+        [ScheduleClaim.Specialty]: conceptsToCsv(resource.specialty),
+        [ScheduleClaim.Name]: resource.name,
+        [ScheduleClaim.Actor]: referenceListToCsv(resource.actor),
+        [ScheduleClaim.PlanningHorizonStart]: planningHorizon?.start,
+        [ScheduleClaim.PlanningHorizonEnd]: planningHorizon?.end,
+        [ScheduleClaim.Comment]: resource.comment,
+    };
+}
+/** Materializes canonical Slot claims as native FHIR R5. */
+export function slotFlatToFhirR5(claims) {
+    return {
+        resourceType: 'Slot',
+        identifier: claims[SlotClaim.Identifier] ? [identifierFromValue(claims[SlotClaim.Identifier])] : undefined,
+        serviceCategory: conceptsFromCsv(claims[SlotClaim.ServiceCategory]),
+        serviceType: codeableReferencesFromClaims(claims[SlotClaim.ServiceType], claims[SlotClaim.ServiceTypeReference]),
+        specialty: conceptsFromCsv(claims[SlotClaim.Specialty]),
+        appointmentType: conceptsFromCsv(claims[SlotClaim.AppointmentType]),
+        schedule: claims[SlotClaim.Schedule] ? { reference: claims[SlotClaim.Schedule] } : undefined,
+        status: claims[SlotClaim.Status],
+        start: claims[SlotClaim.Start],
+        end: claims[SlotClaim.End],
+        overbooked: claims[SlotClaim.Overbooked] === undefined ? undefined : claims[SlotClaim.Overbooked] === 'true',
+        comment: claims[SlotClaim.Comment],
+    };
+}
+/** Extracts official Slot search claims plus required materialization fields. */
+export function slotFhirR5ToFlat(resource) {
+    return {
+        [SlotClaim.Identifier]: identifierToValue(resource.identifier?.[0]),
+        [SlotClaim.ServiceCategory]: conceptsToCsv(resource.serviceCategory),
+        [SlotClaim.ServiceType]: conceptsFromCodeableReferences(resource.serviceType),
+        [SlotClaim.ServiceTypeReference]: referencesFromCodeableReferences(resource.serviceType),
+        [SlotClaim.Specialty]: conceptsToCsv(resource.specialty),
+        [SlotClaim.AppointmentType]: conceptsToCsv(resource.appointmentType),
+        [SlotClaim.Schedule]: referenceToValue(resource.schedule),
+        [SlotClaim.Status]: resource.status,
+        [SlotClaim.Start]: resource.start,
+        [SlotClaim.End]: resource.end,
+        [SlotClaim.Overbooked]: resource.overbooked === undefined ? undefined : String(resource.overbooked),
+        [SlotClaim.Comment]: resource.comment,
+    };
+}

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

@@ -15,6 +15,16 @@ export declare function codingToValue(coding?: {
     system?: string;
     code?: string;
 }): string | undefined;
+/** Materializes one canonical FHIR token as an Identifier without losing its system. */
+export declare function identifierFromValue(value?: string): {
+    system?: string;
+    value: string;
+} | undefined;
+/** Extracts one Identifier as the canonical `system|value` token used by search claims. */
+export declare function identifierToValue(identifier?: {
+    system?: string;
+    value?: string;
+}): string | undefined;
 export declare function referenceToValue(reference?: {
     reference?: string;
 }): string | undefined;

package/dist/converters/convert-shared.js

@@ -25,6 +25,25 @@ export function codingToValue(coding) {
         return undefined;
     return coding.system ? `${coding.system}|${coding.code}` : coding.code;
 }
+/** Materializes one canonical FHIR token as an Identifier without losing its system. */
+export function identifierFromValue(value) {
+    if (!value)
+        return undefined;
+    const separator = value.indexOf('|');
+    if (separator < 0)
+        return { value };
+    const system = value.slice(0, separator).trim();
+    const identifierValue = value.slice(separator + 1).trim();
+    if (!identifierValue)
+        return undefined;
+    return system ? { system, value: identifierValue } : { value: identifierValue };
+}
+/** Extracts one Identifier as the canonical `system|value` token used by search claims. */
+export function identifierToValue(identifier) {
+    if (!identifier?.value)
+        return undefined;
+    return identifier.system ? `${identifier.system}|${identifier.value}` : identifier.value;
+}
 export function referenceToValue(reference) {
     return reference?.reference;
 }

package/dist/converters/index.d.ts

@@ -2,6 +2,7 @@ export * from './convert-shared.js';
 export * from './convert-allergy-intolerance.js';
 export * from './convert-appointment-response.js';
 export * from './convert-appointment.js';
+export * from './convert-appointment-communication.js';
 export * from './convert-care-plan.js';
 export * from './convert-clinical-impression.js';
 export * from './convert-communication-request.js';
@@ -11,6 +12,7 @@ export * from './convert-condition.js';
 export * from './convert-coverage.js';
 export * from './convert-device-use-statement.js';
 export * from './convert-device.js';
+export * from './convert-device-metric.js';
 export * from './convert-diagnostic-report.js';
 export * from './convert-document-reference.js';
 export * from './convert-encounter.js';
@@ -18,10 +20,14 @@ export * from './convert-flag.js';
 export * from './convert-immunization.js';
 export * from './convert-imaging-study.js';
 export * from './convert-location.js';
+export * from './convert-healthcare-service.js';
 export * from './convert-medication-statement.js';
 export * from './convert-observation.js';
 export * from './convert-organization.js';
 export * from './convert-practitioner-role.js';
 export * from './convert-procedure.js';
+export * from './convert-regulated-authorization.js';
 export * from './convert-related-person.js';
 export * from './convert-service-request.js';
+export * from './convert-schedule-slot.js';
+export * from './materialize-claims-first-resource.js';

package/dist/converters/index.js

@@ -2,6 +2,7 @@ export * from './convert-shared.js';
 export * from './convert-allergy-intolerance.js';
 export * from './convert-appointment-response.js';
 export * from './convert-appointment.js';
+export * from './convert-appointment-communication.js';
 export * from './convert-care-plan.js';
 export * from './convert-clinical-impression.js';
 export * from './convert-communication-request.js';
@@ -11,6 +12,7 @@ export * from './convert-condition.js';
 export * from './convert-coverage.js';
 export * from './convert-device-use-statement.js';
 export * from './convert-device.js';
+export * from './convert-device-metric.js';
 export * from './convert-diagnostic-report.js';
 export * from './convert-document-reference.js';
 export * from './convert-encounter.js';
@@ -18,10 +20,14 @@ export * from './convert-flag.js';
 export * from './convert-immunization.js';
 export * from './convert-imaging-study.js';
 export * from './convert-location.js';
+export * from './convert-healthcare-service.js';
 export * from './convert-medication-statement.js';
 export * from './convert-observation.js';
 export * from './convert-organization.js';
 export * from './convert-practitioner-role.js';
 export * from './convert-procedure.js';
+export * from './convert-regulated-authorization.js';
 export * from './convert-related-person.js';
 export * from './convert-service-request.js';
+export * from './convert-schedule-slot.js';
+export * from './materialize-claims-first-resource.js';

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

@@ -0,0 +1,16 @@
+import type { FhirResource } from '../fhir-types.js';
+export type ClaimsFirstFhirResource = Readonly<{
+    resourceType: 'Organization' | 'HealthcareService' | 'Location' | 'Schedule' | 'Slot' | 'DeviceMetric' | 'Procedure' | 'RegulatedAuthorization' | 'DocumentReference';
+    id: string;
+    meta: Readonly<{
+        claims: Readonly<Record<string, unknown>>;
+    }>;
+}>;
+/**
+ * Materializes native FHIR R5 only at an explicit adapter boundary.
+ *
+ * Canonical persistence remains `{ resourceType, id, meta: { claims } }`.
+ * Nested native fields are rejected so a materialized representation can never
+ * silently become a second business source of truth.
+ */
+export declare function materializeClaimsFirstResourceToFhirR5(input: unknown): FhirResource;

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

@@ -0,0 +1,61 @@
+import { healthcareServiceFlatToFhirR5 } from './convert-healthcare-service.js';
+import { locationFlatToFhirR5 } from './convert-location.js';
+import { organizationFlatToFhirR5 } from './convert-organization.js';
+import { scheduleFlatToFhirR5, slotFlatToFhirR5 } from './convert-schedule-slot.js';
+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';
+const materializers = Object.freeze({
+    Organization: organizationFlatToFhirR5,
+    HealthcareService: healthcareServiceFlatToFhirR5,
+    Location: locationFlatToFhirR5,
+    Schedule: scheduleFlatToFhirR5,
+    Slot: slotFlatToFhirR5,
+    DeviceMetric: deviceMetricFlatToFhirR5,
+    Procedure: procedureFlatToFhirR5,
+    RegulatedAuthorization: regulatedAuthorizationFlatToFhirR5,
+    DocumentReference: documentReferenceFlatToFhirR4,
+});
+/**
+ * Materializes native FHIR R5 only at an explicit adapter boundary.
+ *
+ * Canonical persistence remains `{ resourceType, id, meta: { claims } }`.
+ * Nested native fields are rejected so a materialized representation can never
+ * silently become a second business source of truth.
+ */
+export function materializeClaimsFirstResourceToFhirR5(input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input)) {
+        throw new TypeError('claims_first_resource_invalid');
+    }
+    const resource = input;
+    if (Object.keys(resource).some(key => !['resourceType', 'id', 'meta'].includes(key))) {
+        throw new TypeError('claims_first_resource_nested_fhir_forbidden');
+    }
+    const resourceType = String(resource.resourceType || '');
+    const materializer = materializers[resourceType];
+    if (!materializer)
+        throw new TypeError('claims_first_resource_type_unsupported');
+    const id = String(resource.id || '').trim();
+    if (!id)
+        throw new TypeError('claims_first_resource_id_required');
+    const meta = resource.meta;
+    if (!meta || typeof meta !== 'object' || Array.isArray(meta))
+        throw new TypeError('claims_first_resource_claims_required');
+    if (Object.keys(meta).some(key => key !== 'claims'))
+        throw new TypeError('claims_first_resource_nested_fhir_forbidden');
+    const rawClaims = meta.claims;
+    if (!rawClaims || typeof rawClaims !== 'object' || Array.isArray(rawClaims)) {
+        throw new TypeError('claims_first_resource_claims_required');
+    }
+    const claims = {};
+    for (const [claim, rawValue] of Object.entries(rawClaims)) {
+        const values = (Array.isArray(rawValue) ? rawValue : [rawValue])
+            .map(value => String(value).trim())
+            .filter(Boolean);
+        if (!values.length)
+            throw new TypeError('claims_first_resource_claim_value_invalid');
+        claims[claim] = values.join(',');
+    }
+    return Object.freeze({ ...materializer(claims), id });
+}

package/dist/fhir-bundle.d.ts

@@ -7,3 +7,24 @@ export declare function walkBundleResources(bundle: FhirBundle): readonly FhirRe
 export declare function classifyBundleResources(bundle: FhirBundle): ReadonlyMap<string, readonly FhirResource[]>;
 /** Resolves `ResourceType/id`, `urn:uuid:*`, an entry fullUrl, or a bare resource id. */
 export declare function findBundleResourceByReference(bundle: FhirBundle, reference: string): FhirResource | undefined;
+export type CommunicationInnerBundleType = 'document' | 'batch' | 'collection';
+export type CommunicationBundlePayload = Readonly<{
+    communication: FhirResource;
+    attachment: Readonly<{
+        contentType: 'application/fhir+json';
+        data: string;
+        title?: string;
+    }>;
+    bundle: FhirBundle;
+}>;
+/**
+ * Bundle Reader boundary used by every secure Communication flow.
+ *
+ * The outer operational payload is always a batch Bundle containing
+ * Communication entries. Each Communication carries exactly one FHIR JSON
+ * attachment whose decoded resource is an inner document, batch or collection
+ * Bundle. Individual clinical resources and arbitrary file MIME types are not
+ * accepted directly at this boundary; files belong to DocumentReference
+ * entries inside the inner Bundle and must be edited through Bundle Editor.
+ */
+export declare function readCommunicationBundlePayloads(input: unknown): readonly CommunicationBundlePayload[];

package/dist/fhir-bundle.js

@@ -41,3 +41,77 @@ export function findBundleResourceByReference(bundle, reference) {
         : [undefined, target.startsWith('urn:uuid:') ? target.slice('urn:uuid:'.length) : target];
     return readBundleResources(bundle).find(resource => resource.id === id && (!resourceType || resource.resourceType === resourceType));
 }
+/**
+ * Bundle Reader boundary used by every secure Communication flow.
+ *
+ * The outer operational payload is always a batch Bundle containing
+ * Communication entries. Each Communication carries exactly one FHIR JSON
+ * attachment whose decoded resource is an inner document, batch or collection
+ * Bundle. Individual clinical resources and arbitrary file MIME types are not
+ * accepted directly at this boundary; files belong to DocumentReference
+ * entries inside the inner Bundle and must be edited through Bundle Editor.
+ */
+export function readCommunicationBundlePayloads(input) {
+    const outerBatch = requireBundle(input);
+    if (outerBatch.type !== 'batch')
+        throw new TypeError('fhir_batch_bundle_required');
+    validateBatchRequests(outerBatch);
+    const payloads = readBundleResources(outerBatch)
+        .filter(resource => resource.resourceType === 'Communication')
+        .map(communication => {
+        const attachment = firstFhirBundleAttachment(communication);
+        let decoded;
+        try {
+            decoded = JSON.parse(decodeBase64Utf8(attachment.data));
+        }
+        catch {
+            throw new TypeError('fhir_bundle_attachment_invalid');
+        }
+        const bundle = requireBundle(decoded);
+        if (!['document', 'batch', 'collection'].includes(String(bundle.type)))
+            throw new TypeError('fhir_inner_bundle_type_invalid');
+        validateInnerBundle(bundle);
+        return Object.freeze({ communication, attachment, bundle });
+    });
+    if (!payloads.length)
+        throw new TypeError('fhir_communication_required');
+    return Object.freeze(payloads);
+}
+function requireBundle(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value) || value.resourceType !== 'Bundle')
+        throw new TypeError('fhir_bundle_required');
+    return value;
+}
+function firstFhirBundleAttachment(resource) {
+    const payload = Array.isArray(resource.payload) ? resource.payload : [];
+    if (payload.length !== 1)
+        throw new TypeError('fhir_single_bundle_attachment_required');
+    const item = payload[0];
+    if (!item || typeof item !== 'object' || Array.isArray(item))
+        throw new TypeError('fhir_bundle_attachment_required');
+    const attachment = item.contentAttachment;
+    if (!attachment || typeof attachment !== 'object' || Array.isArray(attachment))
+        throw new TypeError('fhir_bundle_attachment_required');
+    const candidate = attachment;
+    if (candidate.contentType !== 'application/fhir+json' || typeof candidate.data !== 'string' || !candidate.data) {
+        throw new TypeError('fhir_bundle_attachment_required');
+    }
+    return Object.freeze({ contentType: candidate.contentType, data: candidate.data, ...(typeof candidate.title === 'string' ? { title: candidate.title } : {}) });
+}
+function decodeBase64Utf8(value) {
+    const binary = globalThis.atob(value);
+    return new TextDecoder().decode(Uint8Array.from(binary, character => character.charCodeAt(0)));
+}
+function validateInnerBundle(bundle) {
+    if (bundle.type === 'document' && readBundleResources(bundle)[0]?.resourceType !== 'Composition') {
+        throw new TypeError('fhir_document_composition_first_required');
+    }
+    if (bundle.type === 'batch')
+        validateBatchRequests(bundle);
+}
+function validateBatchRequests(bundle) {
+    for (const entry of bundle.entry ?? []) {
+        if (!entry.request?.method || !entry.request.url)
+            throw new TypeError('fhir_batch_request_required');
+    }
+}

package/dist/group-r5.d.ts

@@ -89,6 +89,12 @@ export type GroupR5ResearchTeam = Readonly<Record<string, unknown> & {
     membership: 'enumerated';
     member: readonly GroupPractitionerRoleMember[];
 }>;
+export type GroupR5ProfessionalServiceTeam = GroupR5ResearchTeam & Readonly<{
+    managingEntity: Readonly<{
+        reference: `Organization/${string}`;
+        type: 'Organization';
+    }>;
+}>;
 /**
  * Normalizes the members used by an enumerated professional research team.
  * Every entity is a native PractitionerRole reference; a Practitioner or an
@@ -101,6 +107,12 @@ export declare function normalizeGroupPractitionerRoleMembers(input: unknown): r
  * properties are rejected at every depth.
  */
 export declare function normalizeGroupR5ResearchTeam(input: unknown): GroupR5ResearchTeam;
+/**
+ * Normalizes a professional team assigned to one Organization department.
+ * `managingEntity` is singular in FHIR R5, so one Group cannot span several
+ * departments. Membership remains descriptive and grants no permission.
+ */
+export declare function normalizeGroupR5ProfessionalServiceTeam(input: unknown): GroupR5ProfessionalServiceTeam;
 /**
  * Projects all populated official resource-specific R5 Group SearchParameters
  * into flat `resource.meta.claims`. A referenced characteristic is indexed by

package/dist/group-r5.js

@@ -131,6 +131,26 @@ export function normalizeGroupR5ResearchTeam(input) {
     const member = normalizeGroupPractitionerRoleMembers(input.member);
     return Object.freeze({ ...input, type: 'practitioner', membership: 'enumerated', member });
 }
+/**
+ * Normalizes a professional team assigned to one Organization department.
+ * `managingEntity` is singular in FHIR R5, so one Group cannot span several
+ * departments. Membership remains descriptive and grants no permission.
+ */
+export function normalizeGroupR5ProfessionalServiceTeam(input) {
+    const team = normalizeGroupR5ResearchTeam(input);
+    const managingEntity = team.managingEntity;
+    if (!isRecord(managingEntity))
+        throw new TypeError('group_professional_service_managing_organization_invalid');
+    const reference = optionalString(managingEntity.reference);
+    const declaredType = optionalString(managingEntity.type);
+    if (!reference || !/^Organization\/[A-Za-z0-9.-]{1,64}$/.test(reference) || (declaredType && declaredType !== 'Organization')) {
+        throw new TypeError('group_professional_service_managing_organization_invalid');
+    }
+    return Object.freeze({
+        ...team,
+        managingEntity: Object.freeze({ reference: reference, type: 'Organization' }),
+    });
+}
 /**
  * Projects all populated official resource-specific R5 Group SearchParameters
  * into flat `resource.meta.claims`. A referenced characteristic is indexed by

package/dist/healthcare-service-specialty-map.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Candidate SNOMED CT C80 to LOINC specialty map supplied for review.
+ *
+ * This is not an official SNOMED or LOINC map. The declared relationship is
+ * preserved so consumers can automate only strict equivalence and present
+ * wider, related, inexact or unmatched rows for professional governance.
+ */
+export declare const ClinicalSpecialtyMappingEquivalence: Readonly<{
+    readonly Equivalent: "equivalent";
+    readonly Wider: "wider";
+    readonly RelatedTo: "relatedto";
+    readonly Inexact: "inexact";
+    readonly Unmatched: "unmatched";
+}>;
+export type ClinicalSpecialtyMappingEquivalenceCode = typeof ClinicalSpecialtyMappingEquivalence[keyof typeof ClinicalSpecialtyMappingEquivalence];
+export type ClinicalSpecialtyMapping = Readonly<{
+    snomedSystem: 'http://snomed.info/sct';
+    snomedCode: string;
+    snomedDisplay: string;
+    loincSystem?: 'http://loinc.org';
+    loincCode?: string;
+    loincDisplay?: string;
+    equivalence: ClinicalSpecialtyMappingEquivalenceCode;
+    automatic: boolean;
+}>;
+export declare const SnomedC80ToLoincSpecialtyConceptMap: readonly ClinicalSpecialtyMapping[];
+/** Returns a portable LOINC specialty only for a strict reviewed equivalence. */
+export declare function findAutomaticLoincSpecialty(snomedCode: string): Readonly<{
+    system: 'http://loinc.org';
+    code: string;
+    display: string;
+}> | undefined;