vet-data-utils-ts 0.5.31 → 0.5.36

package/README.md

@@ -1,4 +1,13 @@
 # vet-data-utils-ts
+## Blocking local-first SDK release
+
+The canonical contract is [`SDK_LAYERING.md`](https://github.com/Fundacion-UNID/sos-data-utils-ts/blob/main/docs/SDK_LAYERING.md). Its
+indivisible order is **local packages -> full local test matrix -> merge every
+validated branch to `main` -> publish bottom-up -> install exact registry
+versions and commit lockfiles on `main` -> staging**. Never publish to discover
+deterministic failures and never commit a local package reference. Staging
+begins only after exact registry packages are installed and verified.
+
 
 ## Lost-animal access and behavior
 
@@ -189,6 +198,16 @@ for immunologicals); ordinary human ATC is not substituted for it. Veterinary
 allergy product coding may also use ATCvet, while manifestations use an allowed
 SNOMED source.
 
+Terminology-assisted entry uses the neutral coding-review contract from
+`fhir-data-utils-ts/coding-review-flat-claims`. Spoken, typed or imported text
+is `Immunization.vaccine-code-text`; an unconfirmed candidate stays in
+`meta.codingProposals[]` beside the Immunization's `meta.claims`, targets
+`Immunization.vaccine-code`, and is never copied to `ResearchSubject.meta`.
+Confirmation adds the selected `system|code` and official `-display` without
+overwriting local `-text`. Vet policy supplies ATCvet/species constraints; it
+does not redefine the shared shape. Consumers reuse exported fixtures and
+builders rather than repeating governed literals.
+
 `vet-data-utils-ts/veterinary-biologic-product` keeps three independent axes:
 
 - WHO ATCvet QI is the international medicine classification;

package/dist/clinical-bundle-reader.js

@@ -1,4 +1,5 @@
 import { normalizeClaimsFromFhirResource } from 'gdc-common-utils-ts/utils/interoperable-resource-operation';
+import { normalizeFhirApiClaimKey } from 'gdc-common-utils-ts/utils/fhir-api-claim-helpers';
 const PRIMARY_CODE_PROJECTIONS = Object.freeze({
     Condition: { field: 'Condition.code', code: 'Condition.code', text: 'Condition.code-text', display: 'Condition.code-display' },
     Procedure: { field: 'Procedure.code', code: 'Procedure.code', text: 'Procedure.code-text', display: 'Procedure.code-display' },
@@ -42,7 +43,7 @@ async function projectResource(resource, options) {
     const existingMeta = asRecord(resource.meta);
     const existingClaims = asRecord(existingMeta.claims);
     const claims = Object.keys(existingClaims).length
-        ? { ...existingClaims }
+        ? presentationClaims(existingClaims)
         : normalizeClaimsFromFhirResource(resource, {});
     const projection = PRIMARY_CODE_PROJECTIONS[resourceType];
     if (projection) {
@@ -69,6 +70,24 @@ async function projectResource(resource, options) {
         meta: { ...existingMeta, claims },
     };
 }
+/**
+ * Keeps structural FHIR metadata on the resource while preventing derived
+ * paths such as `Immunization.meta.versionId` from becoming editable/search
+ * claims in the presentation copy.
+ */
+function presentationClaims(source) {
+    return Object.fromEntries(Object.entries(source).filter(([claim]) => {
+        if (claim.startsWith('@'))
+            return true;
+        try {
+            normalizeFhirApiClaimKey(claim);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }));
+}
 function parseCodingToken(value) {
     const separator = value.lastIndexOf('|');
     if (separator <= 0 || separator === value.length - 1)

package/dist/clinical-terminology.d.ts

@@ -1,8 +1,9 @@
+/** @deprecated Import `ClinicalTerminologySystems` from sos-data-utils-ts. */
 export declare const VeterinaryClinicalTerminologySystems: Readonly<{
     readonly Loinc: "http://loinc.org";
     readonly SnomedCt: "http://snomed.info/sct";
     readonly Icd10: "http://hl7.org/fhir/sid/icd-10";
-    /** WHO Collaborating Centre ATCvet classification, distinct from human ATC. */
+    readonly Atc: "http://www.whocc.no/atc";
     readonly AtcVet: "http://www.whocc.no/atcvet";
 }>;
 /**
@@ -11,15 +12,19 @@ export declare const VeterinaryClinicalTerminologySystems: Readonly<{
  * canonical SNOMED system URI.
  * https://www.snomed.org/gps
  */
+/** @deprecated Import `ClinicalTerminologySourceScopes` from sos-data-utils-ts. */
 export declare const VeterinaryTerminologySourceScopes: Readonly<{
     readonly Loinc: "LNC";
     readonly SnomedGps: "SNOMED_GPS";
+    readonly SnomedIps: "SNOMED_IPS";
     readonly SnomedCt: "SNOMED_CT";
     readonly SnomedVeterinary: "SNOMEDCT_VET";
     readonly Icd10: "ICD10";
+    readonly Atc: "ATC";
     readonly AtcVet: "ATCVET";
 }>;
 /** Deterministic standards-based data for the isolated local terminology upstream. */
+/** @deprecated Import `CLINICAL_TERMINOLOGY_TEST_DATA` from sos-data-utils-ts. */
 export declare const VET_TERMINOLOGY_TEST_DATA: Readonly<{
     readonly localApiKey: "local-playwright-umls-key";
     readonly bodyTemperature: Readonly<{
@@ -35,8 +40,31 @@ export declare const VET_TERMINOLOGY_TEST_DATA: Readonly<{
         code: "3135009";
         display: "otitis externa";
     }>;
+    readonly canineRabiesVaccine: Readonly<{
+        scope: "ATCVET";
+        system: "http://www.whocc.no/atcvet";
+        code: "QI07AA02";
+        text: "virus de la rabia";
+        display: "rabies virus";
+        ncbiTaxonomyId: "9615";
+    }>;
+    readonly humanInactivatedInfluenzaVaccine: Readonly<{
+        scope: "ATC";
+        system: "http://www.whocc.no/atc";
+        code: "J07BB02";
+        text: "vacuna contra la gripe inactivada de virus fraccionados o ant\u00EDgeno de superficie";
+        display: "influenza, inactivated, split virus or surface antigen";
+        ncbiTaxonomyId: "9606";
+    }>;
+    readonly rabiesDisease: Readonly<{
+        scope: "SNOMED_GPS";
+        umlsSource: "SNOMEDCT_US";
+        system: "http://snomed.info/sct";
+        code: "14168008";
+        display: "Rabies";
+    }>;
 }>;
-export type VeterinaryTerminologySourceScope = typeof VeterinaryTerminologySourceScopes[keyof typeof VeterinaryTerminologySourceScopes];
+export type VeterinaryTerminologySourceScope = Exclude<typeof VeterinaryTerminologySourceScopes[keyof typeof VeterinaryTerminologySourceScopes], 'ATC' | 'SNOMED_IPS'>;
 export type VeterinaryTerminologyCapability = Readonly<{
     type: 'terminology-capability';
     id: string;

package/dist/clinical-terminology.js

@@ -1,41 +1,17 @@
-export const VeterinaryClinicalTerminologySystems = Object.freeze({
-    Loinc: 'http://loinc.org',
-    SnomedCt: 'http://snomed.info/sct',
-    Icd10: 'http://hl7.org/fhir/sid/icd-10',
-    /** WHO Collaborating Centre ATCvet classification, distinct from human ATC. */
-    AtcVet: 'http://www.whocc.no/atcvet',
-});
+import { CLINICAL_TERMINOLOGY_TEST_DATA, ClinicalTerminologySourceScopes, ClinicalTerminologySystems, } from 'sos-data-utils-ts/clinical-terminology';
+/** @deprecated Import `ClinicalTerminologySystems` from sos-data-utils-ts. */
+export const VeterinaryClinicalTerminologySystems = ClinicalTerminologySystems;
 /**
  * Source scopes are authorization/content boundaries, not Coding.system URIs.
  * GPS, full SNOMED CT and the veterinary extension intentionally share the
  * canonical SNOMED system URI.
  * https://www.snomed.org/gps
  */
-export const VeterinaryTerminologySourceScopes = Object.freeze({
-    Loinc: 'LNC',
-    SnomedGps: 'SNOMED_GPS',
-    SnomedCt: 'SNOMED_CT',
-    SnomedVeterinary: 'SNOMEDCT_VET',
-    Icd10: 'ICD10',
-    AtcVet: 'ATCVET',
-});
+/** @deprecated Import `ClinicalTerminologySourceScopes` from sos-data-utils-ts. */
+export const VeterinaryTerminologySourceScopes = ClinicalTerminologySourceScopes;
 /** Deterministic standards-based data for the isolated local terminology upstream. */
-export const VET_TERMINOLOGY_TEST_DATA = Object.freeze({
-    localApiKey: 'local-playwright-umls-key',
-    bodyTemperature: Object.freeze({
-        source: VeterinaryTerminologySourceScopes.Loinc,
-        system: VeterinaryClinicalTerminologySystems.Loinc,
-        code: '8310-5',
-        display: 'Body temperature:Temp:Pt:^Patient:Qn',
-    }),
-    otitisExternaSpanish: Object.freeze({
-        scope: VeterinaryTerminologySourceScopes.SnomedCt,
-        umlsSource: 'SCTSPA',
-        system: VeterinaryClinicalTerminologySystems.SnomedCt,
-        code: '3135009',
-        display: 'otitis externa',
-    }),
-});
+/** @deprecated Import `CLINICAL_TERMINOLOGY_TEST_DATA` from sos-data-utils-ts. */
+export const VET_TERMINOLOGY_TEST_DATA = CLINICAL_TERMINOLOGY_TEST_DATA;
 /**
  * ISO 3166-1 alpha-2 territories enumerated by the official SNOMED
  * International member page on 2026-09-05.

package/dist/immunization-coding-review.d.ts

@@ -0,0 +1,51 @@
+import { type FlatClaimCodingCandidate, type FlatClaimCodingReviewResource } from 'fhir-data-utils-ts/coding-review-flat-claims';
+/** Governed claim coordinates reused by Vet gateways, portals and assistants. */
+export declare const VeterinaryImmunizationCodingReviewClaims: Readonly<{
+    code: "Immunization.vaccine-code";
+    display: string;
+    localText: string;
+}>;
+/**
+ * Builds an unconfirmed veterinary Immunization coding review from text spoken,
+ * typed or imported by a channel. The neutral helper owns proposal placement;
+ * this wrapper contributes veterinary resource coordinates and ATCvet policy.
+ */
+export declare function buildVeterinaryImmunizationCodingReview(input: Readonly<{
+    entryId: string;
+    animalReference: string;
+    administrationDate: string;
+    localText: string;
+    language: string;
+    proposalId: string;
+    candidates: readonly FlatClaimCodingCandidate[];
+}>): FlatClaimCodingReviewResource;
+/** Package-owned synthetic example for assistants, portals and downstream tests. */
+export declare const VETERINARY_IMMUNIZATION_CODING_REVIEW_EXAMPLE: Readonly<{
+    input: Readonly<{
+        entryId: "00000000-0000-4000-8000-000000000201";
+        animalReference: "Patient/00000000-0000-4000-8000-000000000202";
+        administrationDate: "2024-05-23";
+        localText: "vacuna contra la rabia";
+        language: "es-ES";
+        proposalId: "veterinary-immunization-proposal-example";
+        candidates: readonly Readonly<{
+            id: "veterinary-immunization-candidate-example";
+            system: "http://www.whocc.no/atcvet";
+            code: "QI07AA02";
+            display: "Inactivated rabies virus vaccines";
+        }>[];
+    }>;
+    claims: Readonly<{
+        code: "Immunization.vaccine-code";
+        display: string;
+        localText: string;
+    }>;
+    expected: Readonly<{
+        resourceType: string;
+        id: string;
+        meta: Readonly<{
+            claims: Readonly<Record<string, string>>;
+            codingProposals?: readonly import("fhir-data-utils-ts/coding-review-flat-claims").FlatClaimCodingProposal[];
+        }>;
+    }>;
+}>;

package/dist/immunization-coding-review.js

@@ -0,0 +1,59 @@
+import { buildFlatClaimCodingReviewResource, deriveCodingDisplayClaim, deriveCodingLocalTextClaim, } from 'fhir-data-utils-ts/coding-review-flat-claims';
+import { VeterinaryClinicalTerminologySystems } from './clinical-terminology.js';
+const IMMUNIZATION_RESOURCE_TYPE = 'Immunization';
+const IMMUNIZATION_VACCINE_CODE_CLAIM = `${IMMUNIZATION_RESOURCE_TYPE}.vaccine-code`;
+/** Governed claim coordinates reused by Vet gateways, portals and assistants. */
+export const VeterinaryImmunizationCodingReviewClaims = Object.freeze({
+    code: IMMUNIZATION_VACCINE_CODE_CLAIM,
+    display: deriveCodingDisplayClaim(IMMUNIZATION_VACCINE_CODE_CLAIM),
+    localText: deriveCodingLocalTextClaim(IMMUNIZATION_VACCINE_CODE_CLAIM),
+});
+/**
+ * Builds an unconfirmed veterinary Immunization coding review from text spoken,
+ * typed or imported by a channel. The neutral helper owns proposal placement;
+ * this wrapper contributes veterinary resource coordinates and ATCvet policy.
+ */
+export function buildVeterinaryImmunizationCodingReview(input) {
+    const candidates = input.candidates.map((candidate) => {
+        if (candidate.system !== VeterinaryClinicalTerminologySystems.AtcVet) {
+            throw new TypeError('veterinary_immunization_candidate_system_invalid');
+        }
+        return candidate;
+    });
+    return buildFlatClaimCodingReviewResource({
+        resourceType: IMMUNIZATION_RESOURCE_TYPE,
+        resourceId: input.entryId,
+        targetClaim: VeterinaryImmunizationCodingReviewClaims.code,
+        localText: input.localText,
+        language: input.language,
+        baseClaims: {
+            'Immunization.status': 'completed',
+            'Immunization.patient': input.animalReference,
+            'Immunization.date': input.administrationDate,
+        },
+        proposalId: input.proposalId,
+        candidates,
+    });
+}
+const EXAMPLE_ENTRY_ID = '00000000-0000-4000-8000-000000000201';
+const EXAMPLE_ANIMAL_ID = '00000000-0000-4000-8000-000000000202';
+const EXAMPLE_INPUT = Object.freeze({
+    entryId: EXAMPLE_ENTRY_ID,
+    animalReference: `Patient/${EXAMPLE_ANIMAL_ID}`,
+    administrationDate: '2024-05-23',
+    localText: 'vacuna contra la rabia',
+    language: 'es-ES',
+    proposalId: 'veterinary-immunization-proposal-example',
+    candidates: Object.freeze([Object.freeze({
+            id: 'veterinary-immunization-candidate-example',
+            system: VeterinaryClinicalTerminologySystems.AtcVet,
+            code: 'QI07AA02',
+            display: 'Inactivated rabies virus vaccines',
+        })]),
+});
+/** Package-owned synthetic example for assistants, portals and downstream tests. */
+export const VETERINARY_IMMUNIZATION_CODING_REVIEW_EXAMPLE = Object.freeze({
+    input: EXAMPLE_INPUT,
+    claims: VeterinaryImmunizationCodingReviewClaims,
+    expected: buildVeterinaryImmunizationCodingReview(EXAMPLE_INPUT),
+});

package/dist/immunization-draft.d.ts

@@ -0,0 +1,43 @@
+import { type FlatClaimResourceEntry } from 'sos-data-utils-ts/flat-claim-resource-graph';
+import { type VeterinaryImmunizationCoding } from './immunization-flat-claims.js';
+export type VeterinaryImmunizationDraftAttachment = Readonly<{
+    entryId: string;
+    identifier: string;
+    contentType: 'application/pdf' | 'image/jpeg' | 'image/png';
+    contentHash: string;
+    title?: string;
+    dataBase64?: string;
+}>;
+export type VeterinaryImmunizationDraft = Readonly<{
+    status: 'preparation' | 'confirmed';
+    administrationDate: string;
+    vaccineCode: VeterinaryImmunizationCoding;
+    targetDiseases: readonly VeterinaryImmunizationCoding[];
+    productName?: string;
+    productCode?: VeterinaryImmunizationCoding;
+    productIdentifiers: readonly Readonly<{
+        system: string;
+        value: string;
+    }>[];
+    manufacturer?: string;
+    lotNumber?: string;
+    productExpirationDate?: string;
+    barcode?: string;
+    routeCode?: string;
+    siteCode?: string;
+    doseValue?: string;
+    doseUnit?: string;
+    nextDoseDate?: string;
+    attachments: readonly VeterinaryImmunizationDraftAttachment[];
+    confirmedAt?: string;
+}>;
+/** Normalizes the same reviewable draft for web, chat, WhatsApp and telephone adapters. */
+export declare function prepareVeterinaryImmunizationDraft(input: Partial<Omit<VeterinaryImmunizationDraft, 'status' | 'confirmedAt'>>): VeterinaryImmunizationDraft;
+/** Records the channel's explicit human readback/preview confirmation. */
+export declare function confirmVeterinaryImmunizationDraft(draft: VeterinaryImmunizationDraft, confirmedAt: string): VeterinaryImmunizationDraft;
+/** Completes a confirmed channel draft with server-owned subject and performer coordinates. */
+export declare function materializeVeterinaryImmunizationDraft(draft: VeterinaryImmunizationDraft, context: Readonly<{
+    entryId: string;
+    animalReference: string;
+    performerReference?: string;
+}>): readonly FlatClaimResourceEntry[];

package/dist/immunization-draft.js

@@ -0,0 +1,100 @@
+import { buildDocumentReferenceFlatEntry } from 'sos-data-utils-ts/flat-claim-resource-graph';
+import { buildVeterinaryImmunizationFlatGraph, } from './immunization-flat-claims.js';
+/** Normalizes the same reviewable draft for web, chat, WhatsApp and telephone adapters. */
+export function prepareVeterinaryImmunizationDraft(input) {
+    const administrationDate = date(input.administrationDate, 'veterinary_immunization_date_invalid');
+    const vaccineCode = coding(input.vaccineCode, 'veterinary_immunization_vaccine_code_required');
+    const productExpirationDate = input.productExpirationDate ? date(input.productExpirationDate, 'veterinary_medication_expiration_date_invalid') : undefined;
+    const nextDoseDate = input.nextDoseDate ? date(input.nextDoseDate, 'veterinary_immunization_next_dose_date_invalid') : undefined;
+    return Object.freeze({
+        status: 'preparation', administrationDate, vaccineCode,
+        targetDiseases: Object.freeze((input.targetDiseases ?? []).map((value) => coding(value, 'veterinary_immunization_target_disease_invalid'))),
+        ...(text(input.productName) ? { productName: text(input.productName) } : {}),
+        ...(input.productCode ? { productCode: coding(input.productCode, 'veterinary_immunization_product_code_invalid') } : {}),
+        productIdentifiers: Object.freeze((input.productIdentifiers ?? []).map(({ system, value }) => Object.freeze({
+            system: required(system, 'veterinary_immunization_product_identifier_invalid'),
+            value: required(value, 'veterinary_immunization_product_identifier_invalid'),
+        }))),
+        ...(text(input.manufacturer) ? { manufacturer: text(input.manufacturer) } : {}),
+        ...(text(input.lotNumber) ? { lotNumber: text(input.lotNumber) } : {}),
+        ...(productExpirationDate ? { productExpirationDate } : {}),
+        ...(text(input.barcode) ? { barcode: text(input.barcode) } : {}),
+        ...(text(input.routeCode) ? { routeCode: text(input.routeCode) } : {}),
+        ...(text(input.siteCode) ? { siteCode: text(input.siteCode) } : {}),
+        ...(text(input.doseValue) ? { doseValue: text(input.doseValue) } : {}),
+        ...(text(input.doseUnit) ? { doseUnit: text(input.doseUnit) } : {}),
+        ...(nextDoseDate ? { nextDoseDate } : {}),
+        attachments: Object.freeze([...(input.attachments ?? [])]),
+    });
+}
+/** Records the channel's explicit human readback/preview confirmation. */
+export function confirmVeterinaryImmunizationDraft(draft, confirmedAt) {
+    if (draft.status !== 'preparation')
+        throw new TypeError('veterinary_immunization_draft_already_confirmed');
+    const instant = required(confirmedAt, 'veterinary_immunization_confirmation_time_required');
+    if (Number.isNaN(Date.parse(instant)))
+        throw new TypeError('veterinary_immunization_confirmation_time_invalid');
+    return Object.freeze({ ...draft, status: 'confirmed', confirmedAt: instant });
+}
+/** Completes a confirmed channel draft with server-owned subject and performer coordinates. */
+export function materializeVeterinaryImmunizationDraft(draft, context) {
+    if (draft.status !== 'confirmed')
+        throw new TypeError('veterinary_immunization_draft_confirmation_required');
+    const attachments = draft.attachments.map(attachment => buildDocumentReferenceFlatEntry(attachment));
+    const hasMedication = Boolean(draft.productName || draft.productCode || draft.productIdentifiers.length
+        || draft.manufacturer || draft.lotNumber || draft.productExpirationDate || draft.barcode);
+    return buildVeterinaryImmunizationFlatGraph({
+        entryId: required(context.entryId, 'veterinary_immunization_entry_id_required'),
+        animalReference: required(context.animalReference, 'veterinary_immunization_animal_reference_required'),
+        ...(context.performerReference ? {
+            performerReference: required(context.performerReference, 'veterinary_immunization_performer_invalid'),
+        } : {}),
+        administrationDate: draft.administrationDate,
+        vaccineCode: draft.vaccineCode,
+        targetDiseases: draft.targetDiseases,
+        ...(draft.routeCode ? { route: { system: 'http://terminology.hl7.org/CodeSystem/v3-RouteOfAdministration', code: draft.routeCode } } : {}),
+        ...(draft.siteCode ? { site: { system: 'http://terminology.hl7.org/CodeSystem/v3-ActSite', code: draft.siteCode } } : {}),
+        ...(draft.doseValue ? { dose: { value: draft.doseValue, ...(draft.doseUnit ? { unit: draft.doseUnit } : {}) } } : {}),
+        ...(draft.nextDoseDate ? {
+            nextDoseDate: draft.nextDoseDate,
+            recommendationDate: required(draft.confirmedAt, 'veterinary_immunization_confirmation_time_required'),
+        } : {}),
+        ...(hasMedication ? { medication: {
+                entryId: `${context.entryId}-medication`,
+                productName: draft.productName || draft.vaccineCode.display || `${draft.vaccineCode.system}|${draft.vaccineCode.code}`,
+                ...(draft.productCode ? { productCode: draft.productCode } : {}),
+                identifiers: draft.productIdentifiers,
+                ...(draft.manufacturer ? { manufacturer: draft.manufacturer } : {}),
+                ...(draft.lotNumber ? { lotNumber: draft.lotNumber } : {}),
+                ...(draft.productExpirationDate ? { expirationDate: draft.productExpirationDate } : {}),
+                ...(draft.barcode ? { barcode: draft.barcode } : {}),
+            } } : {}),
+        attachments,
+        attachmentEntryIds: attachments.map(({ entryId }) => entryId),
+    });
+}
+function coding(value, error) {
+    if (!value || typeof value !== 'object')
+        throw new TypeError(error);
+    const candidate = value;
+    return Object.freeze({
+        system: required(candidate.system, error), code: required(candidate.code, error),
+        ...(text(candidate.display) ? { display: text(candidate.display) } : {}),
+        ...(text(candidate.text) ? { text: text(candidate.text) } : {}),
+    });
+}
+function date(value, error) {
+    const normalized = required(value, error);
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(normalized) || Number.isNaN(Date.parse(normalized)))
+        throw new TypeError(error);
+    return normalized;
+}
+function required(value, error) {
+    const normalized = text(value);
+    if (!normalized)
+        throw new TypeError(error);
+    return normalized;
+}
+function text(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}

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

@@ -0,0 +1,70 @@
+import { type FlatClaimResourceEntry } from 'sos-data-utils-ts/flat-claim-resource-graph';
+import { type ImmunizationReminderChannel } from 'sos-data-utils-ts/immunization-reminder-plan';
+export type VeterinaryImmunizationCoding = Readonly<{
+    system: string;
+    code: string;
+    display?: string;
+    /**
+     * Canonical requested-language term entered or selected by the channel.
+     * A neutral coding proposal targets `Immunization.vaccine-code`; accepting
+     * it must preserve this value as `Immunization.vaccine-code-text`.
+     */
+    text?: string;
+}>;
+export type VeterinaryImmunizationFlatInput = Readonly<{
+    entryId: string;
+    identifier?: string;
+    animalReference: string;
+    administrationDate: string;
+    vaccineCode: VeterinaryImmunizationCoding;
+    /** Present only when the administering professional is known. */
+    performerReference?: string;
+    targetDiseases?: readonly VeterinaryImmunizationCoding[];
+    route?: VeterinaryImmunizationCoding;
+    site?: VeterinaryImmunizationCoding;
+    dose?: Readonly<{
+        value: string;
+        unit?: string;
+    }>;
+    nextDoseDate?: string;
+    /** FHIR dateTime when the recommendation was created; required with nextDoseDate. */
+    recommendationDate?: string;
+    /** Ordered candidates only; dispatch rechecks current preference and Consent. */
+    reminderChannels?: readonly ImmunizationReminderChannel[];
+    medication?: Readonly<{
+        entryId: string;
+        productName: string;
+        productCode?: VeterinaryImmunizationCoding;
+        identifiers?: readonly Readonly<{
+            system: string;
+            value: string;
+        }>[];
+        manufacturer?: string;
+        lotNumber?: string;
+        expirationDate?: string;
+        barcode?: string;
+    }>;
+    attachments?: readonly FlatClaimResourceEntry[];
+    attachmentEntryIds?: readonly string[];
+}>;
+/**
+ * Creates a version-neutral flat graph after coding review is confirmed.
+ * Unconfirmed `meta.codingProposals[]` use the neutral `fhir-data-utils-ts`
+ * contract and remain on the same resource, outside `meta.claims`.
+ * SearchParameter names are preferred
+ * (`Immunization.date`, `Medication.expiration-date`) and product evidence is
+ * kept in Medication instead of overloading credential validity.
+ */
+export declare function buildVeterinaryImmunizationFlatGraph(input: VeterinaryImmunizationFlatInput): readonly FlatClaimResourceEntry[];
+export type FhirExportRelease = 'R4' | 'R5' | 'R6';
+/** Explicit adapter boundary from canonical flat claims to a selected FHIR release. */
+export declare function exportVeterinaryImmunizationFlatGraph(graph: readonly FlatClaimResourceEntry[], release: FhirExportRelease): Readonly<{
+    resourceType: 'Bundle';
+    type: 'collection';
+    entry: readonly Readonly<{
+        fullUrl: string;
+        resource: Record<string, unknown>;
+    }>[];
+}>;
+/** De-identified three-event fixture based on the supplied Canadian certificate; no owner contact data is retained. */
+export declare const NALA_VACCINATION_FLAT_GRAPH_TEST_DATA: readonly FlatClaimResourceEntry[];

package/dist/immunization-flat-claims.js

@@ -0,0 +1,313 @@
+import { buildDocumentReferenceFlatEntry, buildFlatClaimResourceEntry, linkFlatClaimResourceEntries, } from 'sos-data-utils-ts/flat-claim-resource-graph';
+import { ImmunizationReminderChannels, buildImmunizationReminderTasks, } from 'sos-data-utils-ts/immunization-reminder-plan';
+/**
+ * Creates a version-neutral flat graph after coding review is confirmed.
+ * Unconfirmed `meta.codingProposals[]` use the neutral `fhir-data-utils-ts`
+ * contract and remain on the same resource, outside `meta.claims`.
+ * SearchParameter names are preferred
+ * (`Immunization.date`, `Medication.expiration-date`) and product evidence is
+ * kept in Medication instead of overloading credential validity.
+ */
+export function buildVeterinaryImmunizationFlatGraph(input) {
+    const vaccineCode = codingToken(input.vaccineCode);
+    const claims = {
+        'Immunization.status': 'completed',
+        'Immunization.patient': required(input.animalReference, 'veterinary_immunization_animal_reference_required'),
+        'Immunization.date': isoDate(input.administrationDate, 'veterinary_immunization_date_invalid'),
+        'Immunization.vaccine-code': vaccineCode,
+    };
+    if (input.identifier)
+        claims['Immunization.identifier'] = required(input.identifier, 'veterinary_immunization_identifier_invalid');
+    if (input.vaccineCode.display)
+        claims['Immunization.vaccine-code-display'] = input.vaccineCode.display.trim();
+    if (input.vaccineCode.text)
+        claims['Immunization.vaccine-code-text'] = input.vaccineCode.text.trim();
+    if (input.performerReference)
+        claims['Immunization.performer'] = required(input.performerReference, 'veterinary_immunization_performer_invalid');
+    if (input.targetDiseases?.length) {
+        claims['Immunization.target-disease'] = input.targetDiseases.map(codingToken).join(',');
+        if (input.targetDiseases.some(({ display }) => display?.trim())) {
+            claims['Immunization.target-disease-display'] = joinCsv(input.targetDiseases.map(({ display }) => display?.trim() ?? ''));
+        }
+        if (input.targetDiseases.some(({ text }) => text?.trim())) {
+            claims['Immunization.target-disease-text'] = joinCsv(input.targetDiseases.map(({ text }) => text?.trim() ?? ''));
+        }
+    }
+    if (input.route)
+        claims['Immunization.route'] = codingToken(input.route);
+    if (input.site)
+        claims['Immunization.site'] = codingToken(input.site);
+    if (input.dose) {
+        claims['Immunization.dose-quantity-value'] = required(input.dose.value, 'veterinary_immunization_dose_invalid');
+        if (input.dose.unit)
+            claims['Immunization.dose-quantity-unit'] = input.dose.unit.trim();
+    }
+    const immunization = buildFlatClaimResourceEntry({ entryId: input.entryId, resourceType: 'Immunization', claims });
+    const children = [];
+    let recommendationId;
+    let reminderTasks = [];
+    if (input.medication)
+        children.push(buildMedicationEntry(input.medication));
+    if (input.nextDoseDate) {
+        recommendationId = `${input.entryId}-recommendation`;
+        children.push(buildFlatClaimResourceEntry({
+            entryId: recommendationId,
+            resourceType: 'ImmunizationRecommendation',
+            claims: {
+                'ImmunizationRecommendation.patient': input.animalReference,
+                // FHIR date is when the forecast was created, not when coverage ends.
+                'ImmunizationRecommendation.date': isoDate(required(input.recommendationDate, 'veterinary_immunization_recommendation_date_required'), 'veterinary_immunization_recommendation_date_invalid'),
+                'ImmunizationRecommendation.vaccine-code': vaccineCode,
+                'ImmunizationRecommendation.forecast-status': 'http://terminology.hl7.org/CodeSystem/immunization-recommendation-status|due',
+                'ImmunizationRecommendation.date-criterion-code': 'http://loinc.org|30980-7',
+                'ImmunizationRecommendation.date-criterion-value': isoDate(input.nextDoseDate, 'veterinary_immunization_next_dose_date_invalid'),
+                'ImmunizationRecommendation.supporting-immunization': `Immunization/${input.entryId}`,
+            },
+        }));
+        reminderTasks = buildImmunizationReminderTasks({
+            entryIdPrefix: recommendationId,
+            recommendationReference: `ImmunizationRecommendation/${recommendationId}`,
+            subjectReference: input.animalReference,
+            coverageEndDate: input.nextDoseDate,
+            channelCandidates: input.reminderChannels ?? ImmunizationReminderChannels,
+        });
+        children.push(...reminderTasks);
+    }
+    for (const attachment of input.attachments ?? []) {
+        if (attachment.resourceType !== 'DocumentReference')
+            throw new TypeError('veterinary_immunization_attachment_invalid');
+        children.push(attachment);
+    }
+    const graph = uniqueEntries([immunization, ...children]);
+    const childEntryIds = [
+        ...(input.medication ? [input.medication.entryId] : []),
+        ...(input.nextDoseDate ? [`${input.entryId}-recommendation`] : []),
+        ...(input.attachments ?? []).map(({ entryId }) => entryId),
+        ...(input.attachmentEntryIds ?? []),
+    ];
+    const linkedImmunization = childEntryIds.length
+        ? linkFlatClaimResourceEntries(graph, { parentEntryId: input.entryId, childEntryIds })
+        : graph;
+    return recommendationId && reminderTasks.length
+        ? linkFlatClaimResourceEntries(linkedImmunization, {
+            parentEntryId: recommendationId,
+            childEntryIds: reminderTasks.map(({ entryId }) => entryId),
+        })
+        : linkedImmunization;
+}
+function buildMedicationEntry(input) {
+    const claims = {
+        'Medication.code': input.productCode ? codingToken(input.productCode) : required(input.productName, 'veterinary_medication_product_required'),
+        'Medication.code-text': required(input.productName, 'veterinary_medication_product_required'),
+    };
+    if (input.identifiers?.length) {
+        claims['Medication.identifier'] = input.identifiers.map(({ system, value }) => (`${required(system, 'veterinary_medication_identifier_invalid')}|${required(value, 'veterinary_medication_identifier_invalid')}`)).join(',');
+    }
+    if (input.manufacturer)
+        claims['Medication.manufacturer'] = input.manufacturer.trim();
+    if (input.lotNumber)
+        claims['Medication.lot-number'] = input.lotNumber.trim();
+    if (input.expirationDate)
+        claims['Medication.expiration-date'] = isoDate(input.expirationDate, 'veterinary_medication_expiration_date_invalid');
+    if (input.barcode)
+        claims['Medication.serial-number'] = input.barcode.trim();
+    return buildFlatClaimResourceEntry({ entryId: input.entryId, resourceType: 'Medication', claims });
+}
+/** Explicit adapter boundary from canonical flat claims to a selected FHIR release. */
+export function exportVeterinaryImmunizationFlatGraph(graph, release) {
+    const byReference = new Map(graph.map((entry) => [entry.reference, entry]));
+    return Object.freeze({
+        resourceType: 'Bundle',
+        type: 'collection',
+        entry: Object.freeze(graph.map((entry) => Object.freeze({
+            fullUrl: entry.reference,
+            resource: exportEntry(entry, release, byReference),
+        }))),
+    });
+}
+function exportEntry(entry, release, byReference) {
+    const claims = entry.claims;
+    if (entry.resourceType === 'Immunization') {
+        const vaccineCode = codeableConcept(claims['Immunization.vaccine-code'], claims['Immunization.vaccine-code-display'], claims['Immunization.vaccine-code-text']);
+        const children = splitCsv(claims['Immunization.contained-reference-list']).map((reference) => byReference.get(reference)).filter(Boolean);
+        const medication = children.find((child) => child?.resourceType === 'Medication');
+        const resource = {
+            resourceType: 'Immunization', id: entry.entryId, status: claims['Immunization.status'],
+            vaccineCode, patient: { reference: claims['Immunization.patient'] },
+            occurrenceDateTime: claims['Immunization.date'],
+        };
+        if (claims['Immunization.performer'])
+            resource.performer = [{ actor: { reference: claims['Immunization.performer'] } }];
+        if (claims['Immunization.identifier'])
+            resource.identifier = [{ value: claims['Immunization.identifier'] }];
+        if (claims['Immunization.route'])
+            resource.route = codeableConcept(claims['Immunization.route']);
+        if (claims['Immunization.site'])
+            resource.site = codeableConcept(claims['Immunization.site']);
+        if (claims['Immunization.target-disease']) {
+            const displays = splitCsvKeepingEmpty(claims['Immunization.target-disease-display']);
+            const texts = splitCsvKeepingEmpty(claims['Immunization.target-disease-text']);
+            resource.protocolApplied = [{
+                    targetDisease: splitCsv(claims['Immunization.target-disease']).map((code, index) => (codeableConcept(code, displays[index], texts[index]))),
+                }];
+        }
+        if (medication && release !== 'R4')
+            resource.administeredProduct = { reference: { reference: medication.reference } };
+        return resource;
+    }
+    if (entry.resourceType === 'Medication') {
+        const lotNumber = claims['Medication.lot-number'];
+        const expirationDate = claims['Medication.expiration-date'];
+        const resource = {
+            resourceType: 'Medication', id: entry.entryId,
+            code: codeableConcept(claims['Medication.code'], undefined, claims['Medication.code-text']),
+        };
+        if (claims['Medication.identifier'])
+            resource.identifier = splitCsv(claims['Medication.identifier']).map(identifierFromToken);
+        if (lotNumber || expirationDate)
+            resource[release === 'R6' ? 'instance' : 'batch'] = {
+                ...(lotNumber ? { lotNumber } : {}), ...(expirationDate ? { expirationDate } : {}),
+            };
+        return resource;
+    }
+    if (entry.resourceType === 'ImmunizationRecommendation')
+        return {
+            resourceType: 'ImmunizationRecommendation', id: entry.entryId,
+            patient: { reference: claims['ImmunizationRecommendation.patient'] },
+            date: claims['ImmunizationRecommendation.date'],
+            recommendation: [{
+                    vaccineCode: [codeableConcept(claims['ImmunizationRecommendation.vaccine-code'])],
+                    forecastStatus: codeableConcept(claims['ImmunizationRecommendation.forecast-status']),
+                    dateCriterion: [{
+                            code: codeableConcept(claims['ImmunizationRecommendation.date-criterion-code']),
+                            value: claims['ImmunizationRecommendation.date-criterion-value'],
+                        }],
+                    supportingImmunization: [{ reference: claims['ImmunizationRecommendation.supporting-immunization'] }],
+                }],
+        };
+    if (entry.resourceType === 'DocumentReference')
+        return {
+            resourceType: 'DocumentReference', id: entry.entryId, status: 'current',
+            identifier: [{ value: claims['DocumentReference.identifier'] }],
+            content: [{ attachment: {
+                        contentType: claims['DocumentReference.content-type'],
+                        ...(claims['DocumentReference.url'] ? { url: claims['DocumentReference.url'] } : {}),
+                        ...(claims['DocumentReference.title'] ? { title: claims['DocumentReference.title'] } : {}),
+                    } }],
+        };
+    return { resourceType: entry.resourceType, id: entry.entryId, meta: { claims: { ...claims } } };
+}
+function codeableConcept(token, display, text) {
+    const value = required(token, 'veterinary_coding_required');
+    const separator = value.lastIndexOf('|');
+    if (separator <= 0 || separator === value.length - 1)
+        return { text: text || display || value };
+    return {
+        coding: [{ system: value.slice(0, separator), code: value.slice(separator + 1), ...(display ? { display } : {}) }],
+        ...(text ? { text } : {}),
+    };
+}
+function identifierFromToken(token) {
+    const separator = token.lastIndexOf('|');
+    return separator > 0 ? { system: token.slice(0, separator), value: token.slice(separator + 1) } : { value: token };
+}
+function codingToken(coding) {
+    return `${required(coding.system, 'veterinary_coding_system_required')}|${required(coding.code, 'veterinary_coding_code_required')}`;
+}
+function isoDate(value, error) {
+    const normalized = required(value, error);
+    if (!/^\d{4}-\d{2}-\d{2}(?:T.*)?$/.test(normalized) || Number.isNaN(Date.parse(normalized)))
+        throw new TypeError(error);
+    return normalized;
+}
+function required(value, error) {
+    if (typeof value !== 'string' || !value.trim())
+        throw new TypeError(error);
+    return value.trim();
+}
+function splitCsv(value) {
+    return splitCsvKeepingEmpty(value).filter(Boolean);
+}
+function splitCsvKeepingEmpty(value) {
+    if (value === undefined)
+        return [];
+    const values = [];
+    let current = '';
+    let quoted = false;
+    for (let index = 0; index < value.length; index += 1) {
+        const character = value[index];
+        if (character === '"' && quoted && value[index + 1] === '"') {
+            current += '"';
+            index += 1;
+        }
+        else if (character === '"')
+            quoted = !quoted;
+        else if (character === ',' && !quoted) {
+            values.push(current.trim());
+            current = '';
+        }
+        else
+            current += character;
+    }
+    values.push(current.trim());
+    return values;
+}
+function joinCsv(values) {
+    return values.map((value) => value.includes(',') || value.includes('"')
+        ? `"${value.replaceAll('"', '""')}"`
+        : value).join(',');
+}
+function uniqueEntries(entries) {
+    const byId = new Map();
+    for (const entry of entries) {
+        const existing = byId.get(entry.entryId);
+        if (existing && existing.reference !== entry.reference)
+            throw new TypeError('flat_claim_entry_id_collision');
+        byId.set(entry.entryId, existing ?? entry);
+    }
+    return Object.freeze([...byId.values()]);
+}
+const atcVet = 'http://www.whocc.no/atcvet';
+const certificate = buildDocumentReferenceFlatEntry({
+    entryId: 'nala-vaccination-certificate', identifier: 'urn:uuid:nala-vaccination-certificate',
+    contentType: 'image/jpeg', contentHash: 'sha256:test-only-nala-certificate-digest', title: 'Vaccination certificate',
+});
+/** De-identified three-event fixture based on the supplied Canadian certificate; no owner contact data is retained. */
+export const NALA_VACCINATION_FLAT_GRAPH_TEST_DATA = uniqueEntries([
+    ...buildVeterinaryImmunizationFlatGraph({
+        entryId: 'nala-rabies', animalReference: 'Patient/nala', administrationDate: '2024-05-23',
+        performerReference: 'PractitionerRole/certificate-veterinarian',
+        vaccineCode: {
+            system: atcVet, code: 'QI07AA02', display: 'Inactivated rabies virus vaccines',
+            text: 'Vacuna contra el virus de la rabia',
+        },
+        targetDiseases: [{ system: 'http://snomed.info/sct', code: '14168008', display: 'Rabies', text: 'Rabia' }],
+        nextDoseDate: '2027-05-23',
+        recommendationDate: '2026-09-20T12:00:00.000Z',
+        medication: {
+            entryId: 'nala-rabies-product', productName: 'Imrab 3 TF',
+            productCode: { system: atcVet, code: 'QI07AA02' }, manufacturer: 'Boehringer Ingelheim',
+            identifiers: [
+                { system: 'https://inspection.canada.ca/ccvb', value: '820VV/R1.14/R2.1' },
+                { system: 'https://www.aphis.usda.gov/cvb/product-code', value: '1905.26' },
+            ],
+            lotNumber: '18595', expirationDate: '2025-06-28',
+        },
+        route: { system: 'http://terminology.hl7.org/CodeSystem/v3-RouteOfAdministration', code: 'SQ', display: 'Subcutaneous' },
+        attachments: [certificate], attachmentEntryIds: [certificate.entryId],
+    }),
+    ...buildVeterinaryImmunizationFlatGraph({
+        entryId: 'nala-da2plp', animalReference: 'Patient/nala', administrationDate: '2024-05-23',
+        performerReference: 'PractitionerRole/certificate-veterinarian',
+        vaccineCode: { system: atcVet, code: 'QI07AI02', display: 'Canine viral and bacterial combination vaccines' },
+        nextDoseDate: '2025-05-23', recommendationDate: '2026-09-20T12:00:00.000Z',
+        attachments: [certificate], attachmentEntryIds: [certificate.entryId],
+    }),
+    ...buildVeterinaryImmunizationFlatGraph({
+        entryId: 'nala-lyme', animalReference: 'Patient/nala', administrationDate: '2024-05-23',
+        performerReference: 'PractitionerRole/certificate-veterinarian',
+        vaccineCode: { system: atcVet, code: 'QI07AB04', display: 'Borrelia vaccines' },
+        nextDoseDate: '2025-05-23', recommendationDate: '2026-09-20T12:00:00.000Z',
+        attachments: [certificate], attachmentEntryIds: [certificate.entryId],
+    }),
+]);

package/dist/index.d.ts

@@ -10,6 +10,9 @@ export * from './financial.js';
 export * from './group.js';
 export * from './health-dcat.js';
 export * from './immunization.js';
+export * from './immunization-flat-claims.js';
+export * from './immunization-coding-review.js';
+export * from './immunization-draft.js';
 export * from './international-health-card.js';
 export * from './index-projection-tags.js';
 export * from './insurance-consent.js';
@@ -18,6 +21,7 @@ export * from './lost-animal-access.js';
 export * from './organization-application.js';
 export * from './payment.js';
 export * from './place-service-directory.js';
+export * from './professional-access-policy.js';
 export * from './provenance.js';
 export * from './research-study.js';
 export * from './sectors.js';

package/dist/index.js

@@ -10,6 +10,9 @@ export * from './financial.js';
 export * from './group.js';
 export * from './health-dcat.js';
 export * from './immunization.js';
+export * from './immunization-flat-claims.js';
+export * from './immunization-coding-review.js';
+export * from './immunization-draft.js';
 export * from './international-health-card.js';
 export * from './index-projection-tags.js';
 export * from './insurance-consent.js';
@@ -18,6 +21,7 @@ export * from './lost-animal-access.js';
 export * from './organization-application.js';
 export * from './payment.js';
 export * from './place-service-directory.js';
+export * from './professional-access-policy.js';
 export * from './provenance.js';
 export * from './research-study.js';
 export * from './sectors.js';

package/dist/professional-access-policy.d.ts

@@ -0,0 +1,2 @@
+/** Vet compatibility surface; the product-neutral policy is owned by SOS. */
+export * from 'sos-data-utils-ts/professional-access-policy';

package/dist/professional-access-policy.js

@@ -0,0 +1,2 @@
+/** Vet compatibility surface; the product-neutral policy is owned by SOS. */
+export * from 'sos-data-utils-ts/professional-access-policy';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vet-data-utils-ts",
-  "version": "0.5.31",
+  "version": "0.5.36",
   "description": "Browser-safe governed VetChain data contracts",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",
@@ -56,6 +56,18 @@
       "types": "./dist/immunization.d.ts",
       "default": "./dist/immunization.js"
     },
+    "./immunization-flat-claims": {
+      "types": "./dist/immunization-flat-claims.d.ts",
+      "default": "./dist/immunization-flat-claims.js"
+    },
+    "./immunization-coding-review": {
+      "types": "./dist/immunization-coding-review.d.ts",
+      "default": "./dist/immunization-coding-review.js"
+    },
+    "./immunization-draft": {
+      "types": "./dist/immunization-draft.d.ts",
+      "default": "./dist/immunization-draft.js"
+    },
     "./international-health-card": {
       "types": "./dist/international-health-card.d.ts",
       "default": "./dist/international-health-card.js"
@@ -92,6 +104,10 @@
       "types": "./dist/place-service-directory.d.ts",
       "default": "./dist/place-service-directory.js"
     },
+    "./professional-access-policy": {
+      "types": "./dist/professional-access-policy.d.ts",
+      "default": "./dist/professional-access-policy.js"
+    },
     "./research-study": {
       "types": "./dist/research-study.d.ts",
       "default": "./dist/research-study.js"
@@ -141,8 +157,10 @@
     "typescript": "^5.5.4"
   },
   "dependencies": {
+    "fhir-data-utils-ts": "0.2.4",
     "gdc-common-utils-ts": "2.9.12",
-    "pako": "^2.2.0"
+    "pako": "^2.2.0",
+    "sos-data-utils-ts": "0.3.6"
   },
   "engines": {
     "node": ">=20"