vet-data-utils-ts 0.5.30 → 0.5.32

package/README.md

@@ -189,6 +189,20 @@ 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.
 
+`vet-data-utils-ts/veterinary-biologic-product` keeps three independent axes:
+
+- WHO ATCvet QI is the international medicine classification;
+- the authorized commercial product and its identifier are regional, sourced
+  from [EMA UPD](https://medicines.health.europa.eu/veterinary/),
+  [USDA APHIS CVB](https://www.aphis.usda.gov/veterinary-biologics/licensed-products)
+  or [CFIA CCVB](https://active.inspection.gc.ca/netapp/veterinarybio-bioveterinaire/vetbioe.aspx);
+- `targetDiseases` contains the separately coded diseases/antigens used by
+  FHIR `Immunization.protocolApplied.targetDisease`.
+
+Source adapters preserve the authority's original product/true/trade names,
+manufacturer, agents and identifiers. Filtering uses reviewed exact NCBI taxa;
+broad words such as “poultry” are source labels, not invented species IDs.
+
 The shared IPS reader boundary is `projectClinicalBundleForReading(...)` from
 `vet-data-utils-ts/clinical-bundle-reader`. It accepts a native FHIR Bundle
 (including R4/R5 resources supported by the common normalizer) or resources

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,94 @@
+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'),
+        performerReference: required(context.performerReference, 'veterinary_immunization_performer_required'),
+        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 } : {}),
+        ...(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) } : {}),
+    });
+}
+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,55 @@
+import { type FlatClaimResourceEntry } from 'sos-data-utils-ts/flat-claim-resource-graph';
+export type VeterinaryImmunizationCoding = Readonly<{
+    system: string;
+    code: string;
+    display?: string;
+}>;
+export type VeterinaryImmunizationFlatInput = Readonly<{
+    entryId: string;
+    identifier?: string;
+    animalReference: string;
+    administrationDate: string;
+    vaccineCode: VeterinaryImmunizationCoding;
+    performerReference: string;
+    targetDiseases?: readonly VeterinaryImmunizationCoding[];
+    route?: VeterinaryImmunizationCoding;
+    site?: VeterinaryImmunizationCoding;
+    dose?: Readonly<{
+        value: string;
+        unit?: string;
+    }>;
+    nextDoseDate?: string;
+    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. 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,224 @@
+import { buildDocumentReferenceFlatEntry, buildFlatClaimResourceEntry, linkFlatClaimResourceEntries, } from 'sos-data-utils-ts/flat-claim-resource-graph';
+/**
+ * Creates a version-neutral flat graph. 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,
+        'Immunization.performer': required(input.performerReference, 'veterinary_immunization_performer_required'),
+    };
+    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.targetDiseases?.length)
+        claims['Immunization.target-disease'] = input.targetDiseases.map(codingToken).join(',');
+    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 = [];
+    if (input.medication)
+        children.push(buildMedicationEntry(input.medication));
+    if (input.nextDoseDate) {
+        children.push(buildFlatClaimResourceEntry({
+            entryId: `${input.entryId}-recommendation`,
+            resourceType: 'ImmunizationRecommendation',
+            claims: {
+                'ImmunizationRecommendation.patient': input.animalReference,
+                'ImmunizationRecommendation.date': isoDate(input.nextDoseDate, 'veterinary_immunization_next_dose_date_invalid'),
+                'ImmunizationRecommendation.vaccine-code': vaccineCode,
+            },
+        }));
+    }
+    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.attachmentEntryIds ?? []),
+    ];
+    return childEntryIds.length
+        ? linkFlatClaimResourceEntries(graph, { parentEntryId: input.entryId, childEntryIds })
+        : graph;
+}
+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']);
+        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'],
+            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'])
+            resource.protocolApplied = [{ targetDisease: splitCsv(claims['Immunization.target-disease']).map((code) => codeableConcept(code)) }];
+        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'], 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'])] }],
+        };
+    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) {
+    const value = required(token, 'veterinary_coding_required');
+    const separator = value.lastIndexOf('|');
+    if (separator <= 0 || separator === value.length - 1)
+        return { text: display || value };
+    return { coding: [{ system: value.slice(0, separator), code: value.slice(separator + 1), ...(display ? { display } : {}) }] };
+}
+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 value?.split(',').map((item) => item.trim()).filter(Boolean) ?? [];
+}
+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' },
+        targetDiseases: [{ system: 'http://snomed.info/sct', code: '14168008', display: 'Rabies' }],
+        nextDoseDate: '2027-05-23',
+        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', 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', attachments: [certificate], attachmentEntryIds: [certificate.entryId],
+    }),
+]);

package/dist/index.d.ts

@@ -10,6 +10,8 @@ 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-draft.js';
 export * from './international-health-card.js';
 export * from './index-projection-tags.js';
 export * from './insurance-consent.js';
@@ -23,4 +25,5 @@ export * from './research-study.js';
 export * from './sectors.js';
 export * from './shc.js';
 export * from './veterinary-sections.js';
+export * from './veterinary-biologic-product.js';
 export * from './scheduling.js';

package/dist/index.js

@@ -10,6 +10,8 @@ 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-draft.js';
 export * from './international-health-card.js';
 export * from './index-projection-tags.js';
 export * from './insurance-consent.js';
@@ -23,4 +25,5 @@ export * from './research-study.js';
 export * from './sectors.js';
 export * from './shc.js';
 export * from './veterinary-sections.js';
+export * from './veterinary-biologic-product.js';
 export * from './scheduling.js';

package/dist/veterinary-biologic-product.d.ts

@@ -0,0 +1,184 @@
+export declare const NcbiTaxonomySystem: "https://www.ncbi.nlm.nih.gov/taxonomy";
+export type VeterinarySpeciesTaxon = Readonly<{
+    system: typeof NcbiTaxonomySystem;
+    code: string;
+    display: string;
+}>;
+/** Exact taxa used by shared animal-product filters; broad groups are not identities. */
+export declare const VeterinarySpeciesTaxonomy: Readonly<{
+    readonly Dog: Readonly<{
+        system: typeof NcbiTaxonomySystem;
+        code: string;
+        display: string;
+    }>;
+    readonly Cat: Readonly<{
+        system: typeof NcbiTaxonomySystem;
+        code: string;
+        display: string;
+    }>;
+    readonly Horse: Readonly<{
+        system: typeof NcbiTaxonomySystem;
+        code: string;
+        display: string;
+    }>;
+    readonly Cattle: Readonly<{
+        system: typeof NcbiTaxonomySystem;
+        code: string;
+        display: string;
+    }>;
+    readonly Pig: Readonly<{
+        system: typeof NcbiTaxonomySystem;
+        code: string;
+        display: string;
+    }>;
+    readonly Sheep: Readonly<{
+        system: typeof NcbiTaxonomySystem;
+        code: string;
+        display: string;
+    }>;
+    readonly Goat: Readonly<{
+        system: typeof NcbiTaxonomySystem;
+        code: string;
+        display: string;
+    }>;
+    readonly Chicken: Readonly<{
+        system: typeof NcbiTaxonomySystem;
+        code: string;
+        display: string;
+    }>;
+}>;
+export declare const VeterinaryBiologicAuthorizationRegions: Readonly<{
+    readonly EuEea: "EU-EEA";
+    readonly Us: "US";
+    readonly Ca: "CA";
+}>;
+export type VeterinaryBiologicAuthorizationRegion = typeof VeterinaryBiologicAuthorizationRegions[keyof typeof VeterinaryBiologicAuthorizationRegions];
+export declare const VeterinaryBiologicProductSources: Readonly<{
+    readonly EmaUpd: "ema-upd";
+    readonly UsdaCvb: "usda-cvb";
+    readonly CfiaCcvb: "cfia-ccvb";
+}>;
+export declare const VeterinaryBiologicIdentifierKinds: Readonly<{
+    readonly EmaUpdProductId: "eu-upd-product-id";
+    readonly UsdaCvbPcn: "usda-cvb-pcn";
+    readonly CfiaCcvbNumber: "cfia-ccvb-number";
+    readonly UsdaCode: "usda-code";
+}>;
+export type VeterinaryBiologicIdentifierKind = typeof VeterinaryBiologicIdentifierKinds[keyof typeof VeterinaryBiologicIdentifierKinds];
+export type VeterinaryBiologicCoding = Readonly<{
+    system: string;
+    code: string;
+    display?: string;
+}>;
+export type VeterinaryBiologicProduct = Readonly<{
+    source: typeof VeterinaryBiologicProductSources[keyof typeof VeterinaryBiologicProductSources];
+    authorization: Readonly<{
+        region: VeterinaryBiologicAuthorizationRegion;
+        identifiers: readonly Readonly<{
+            kind: VeterinaryBiologicIdentifierKind;
+            value: string;
+        }>[];
+    }>;
+    productName: string;
+    trueName?: string;
+    tradeNames: readonly string[];
+    manufacturer: string;
+    species: readonly VeterinarySpeciesTaxon[];
+    targetDiseases: readonly VeterinaryBiologicCoding[];
+    /** WHO ATCvet QI classifications; never a regional product authorization id. */
+    atcVetCodes: readonly string[];
+    agents: readonly string[];
+}>;
+/** Validates one authority record without conflating its identifiers with terminology. */
+export declare function parseVeterinaryBiologicProduct(value: unknown): VeterinaryBiologicProduct;
+/** Pure catalog filtering after source adapters have produced governed records. */
+export declare function filterVeterinaryBiologicProducts(products: readonly VeterinaryBiologicProduct[], filter: Readonly<{
+    region: VeterinaryBiologicAuthorizationRegion;
+    speciesTaxonomyCode: string;
+    targetDisease?: Readonly<{
+        system: string;
+        code: string;
+    }>;
+    text?: string;
+}>): readonly VeterinaryBiologicProduct[];
+/** Shared synthetic fixtures; identifiers are deliberately test-only, while systems/taxa are canonical. */
+export declare const VETERINARY_BIOLOGIC_PRODUCT_TEST_DATA: Readonly<{
+    readonly euDogRabies: Readonly<{
+        source: "ema-upd";
+        authorization: Readonly<{
+            region: "EU-EEA";
+            identifiers: readonly Readonly<{
+                kind: "eu-upd-product-id";
+                value: "test-eu-product-1";
+            }>[];
+        }>;
+        productName: "Test EU canine rabies vaccine";
+        tradeNames: readonly string[];
+        manufacturer: "Test manufacturer EU";
+        species: readonly Readonly<{
+            system: typeof NcbiTaxonomySystem;
+            code: string;
+            display: string;
+        }>[];
+        targetDiseases: readonly Readonly<{
+            system: "http://snomed.info/sct";
+            code: "14168008";
+            display: "Rabies";
+        }>[];
+        atcVetCodes: readonly string[];
+        agents: readonly string[];
+    }>;
+    readonly usCattleProduct: Readonly<{
+        source: "usda-cvb";
+        authorization: Readonly<{
+            region: "US";
+            identifiers: readonly Readonly<{
+                kind: "usda-cvb-pcn";
+                value: "test-us-pcn-1";
+            }>[];
+        }>;
+        productName: "Test US cattle biologic";
+        trueName: "Test cattle agent vaccine";
+        tradeNames: readonly never[];
+        manufacturer: "Test manufacturer US";
+        species: readonly Readonly<{
+            system: typeof NcbiTaxonomySystem;
+            code: string;
+            display: string;
+        }>[];
+        targetDiseases: readonly {
+            system: string;
+            code: string;
+        }[];
+        atcVetCodes: readonly never[];
+        agents: readonly string[];
+    }>;
+    readonly caDogRabies: Readonly<{
+        source: "cfia-ccvb";
+        authorization: Readonly<{
+            region: "CA";
+            identifiers: readonly (Readonly<{
+                kind: "cfia-ccvb-number";
+                value: "test-ca-ccvb-1";
+            }> | Readonly<{
+                kind: "usda-code";
+                value: "test-usda-code-1";
+            }>)[];
+        }>;
+        productName: "Test Canadian canine rabies vaccine";
+        tradeNames: readonly string[];
+        manufacturer: "Test manufacturer CA";
+        species: readonly Readonly<{
+            system: typeof NcbiTaxonomySystem;
+            code: string;
+            display: string;
+        }>[];
+        targetDiseases: readonly Readonly<{
+            system: "http://snomed.info/sct";
+            code: "14168008";
+            display: "Rabies";
+        }>[];
+        atcVetCodes: readonly string[];
+        agents: readonly string[];
+    }>;
+}>;

package/dist/veterinary-biologic-product.js

@@ -0,0 +1,171 @@
+export const NcbiTaxonomySystem = 'https://www.ncbi.nlm.nih.gov/taxonomy';
+function taxon(code, display) {
+    return Object.freeze({ system: NcbiTaxonomySystem, code, display });
+}
+/** Exact taxa used by shared animal-product filters; broad groups are not identities. */
+export const VeterinarySpeciesTaxonomy = Object.freeze({
+    Dog: taxon('9615', 'Canis lupus familiaris'),
+    Cat: taxon('9685', 'Felis catus'),
+    Horse: taxon('9796', 'Equus caballus'),
+    Cattle: taxon('9913', 'Bos taurus'),
+    Pig: taxon('9823', 'Sus scrofa'),
+    Sheep: taxon('9940', 'Ovis aries'),
+    Goat: taxon('9925', 'Capra hircus'),
+    Chicken: taxon('9031', 'Gallus gallus'),
+});
+export const VeterinaryBiologicAuthorizationRegions = Object.freeze({
+    EuEea: 'EU-EEA',
+    Us: 'US',
+    Ca: 'CA',
+});
+export const VeterinaryBiologicProductSources = Object.freeze({
+    EmaUpd: 'ema-upd',
+    UsdaCvb: 'usda-cvb',
+    CfiaCcvb: 'cfia-ccvb',
+});
+export const VeterinaryBiologicIdentifierKinds = Object.freeze({
+    EmaUpdProductId: 'eu-upd-product-id',
+    UsdaCvbPcn: 'usda-cvb-pcn',
+    CfiaCcvbNumber: 'cfia-ccvb-number',
+    UsdaCode: 'usda-code',
+});
+const SOURCE_REGION = Object.freeze({
+    [VeterinaryBiologicProductSources.EmaUpd]: VeterinaryBiologicAuthorizationRegions.EuEea,
+    [VeterinaryBiologicProductSources.UsdaCvb]: VeterinaryBiologicAuthorizationRegions.Us,
+    [VeterinaryBiologicProductSources.CfiaCcvb]: VeterinaryBiologicAuthorizationRegions.Ca,
+});
+const PRIMARY_IDENTIFIER = Object.freeze({
+    [VeterinaryBiologicAuthorizationRegions.EuEea]: VeterinaryBiologicIdentifierKinds.EmaUpdProductId,
+    [VeterinaryBiologicAuthorizationRegions.Us]: VeterinaryBiologicIdentifierKinds.UsdaCvbPcn,
+    [VeterinaryBiologicAuthorizationRegions.Ca]: VeterinaryBiologicIdentifierKinds.CfiaCcvbNumber,
+});
+function required(value, error) {
+    if (typeof value !== 'string' || !value.trim())
+        throw new TypeError(error);
+    return value.trim();
+}
+function strings(value, error) {
+    if (!Array.isArray(value))
+        throw new TypeError(error);
+    const normalized = value.map((item) => required(item, error));
+    return Object.freeze([...new Set(normalized)]);
+}
+/** Validates one authority record without conflating its identifiers with terminology. */
+export function parseVeterinaryBiologicProduct(value) {
+    if (!value || typeof value !== 'object')
+        throw new TypeError('veterinary_biologic_product_invalid');
+    const input = value;
+    const source = required(input.source, 'veterinary_biologic_source_invalid');
+    if (!(source in SOURCE_REGION))
+        throw new TypeError('veterinary_biologic_source_invalid');
+    const authorizationInput = input.authorization;
+    const region = required(authorizationInput?.region, 'veterinary_biologic_authorization_region_invalid');
+    if (SOURCE_REGION[source] !== region)
+        throw new TypeError('veterinary_biologic_authorization_region_invalid');
+    if (!Array.isArray(authorizationInput?.identifiers) || authorizationInput.identifiers.length === 0) {
+        throw new TypeError('veterinary_biologic_authorization_identifier_invalid');
+    }
+    const identifiers = authorizationInput.identifiers.map((entry) => {
+        if (!entry || typeof entry !== 'object')
+            throw new TypeError('veterinary_biologic_authorization_identifier_invalid');
+        const identifier = entry;
+        const kind = required(identifier.kind, 'veterinary_biologic_authorization_identifier_invalid');
+        if (!Object.values(VeterinaryBiologicIdentifierKinds).includes(kind)) {
+            throw new TypeError('veterinary_biologic_authorization_identifier_invalid');
+        }
+        return Object.freeze({ kind, value: required(identifier.value, 'veterinary_biologic_authorization_identifier_invalid') });
+    });
+    if (identifiers[0]?.kind !== PRIMARY_IDENTIFIER[region]) {
+        throw new TypeError('veterinary_biologic_authorization_identifier_invalid');
+    }
+    if (identifiers.slice(1).some(({ kind }) => region !== VeterinaryBiologicAuthorizationRegions.Ca
+        || kind !== VeterinaryBiologicIdentifierKinds.UsdaCode)) {
+        throw new TypeError('veterinary_biologic_authorization_identifier_invalid');
+    }
+    if (!Array.isArray(input.species) || input.species.length === 0)
+        throw new TypeError('veterinary_biologic_species_invalid');
+    const species = input.species.map((entry) => {
+        if (!entry || typeof entry !== 'object')
+            throw new TypeError('veterinary_biologic_species_invalid');
+        const candidate = entry;
+        if (candidate.system !== NcbiTaxonomySystem)
+            throw new TypeError('veterinary_biologic_species_invalid');
+        return Object.freeze({
+            system: NcbiTaxonomySystem,
+            code: required(candidate.code, 'veterinary_biologic_species_invalid'),
+            display: required(candidate.display, 'veterinary_biologic_species_invalid'),
+        });
+    });
+    if (!Array.isArray(input.targetDiseases) || input.targetDiseases.length === 0) {
+        throw new TypeError('veterinary_biologic_target_disease_invalid');
+    }
+    const targetDiseases = input.targetDiseases.map((entry) => {
+        if (!entry || typeof entry !== 'object')
+            throw new TypeError('veterinary_biologic_target_disease_invalid');
+        const candidate = entry;
+        const display = typeof candidate.display === 'string' && candidate.display.trim() ? candidate.display.trim() : undefined;
+        return Object.freeze({
+            system: required(candidate.system, 'veterinary_biologic_target_disease_invalid'),
+            code: required(candidate.code, 'veterinary_biologic_target_disease_invalid'),
+            ...(display ? { display } : {}),
+        });
+    });
+    const atcVetCodes = strings(input.atcVetCodes ?? [], 'veterinary_biologic_atcvet_invalid');
+    if (atcVetCodes.some((code) => !/^QI[A-Z0-9]{0,8}$/.test(code)))
+        throw new TypeError('veterinary_biologic_atcvet_invalid');
+    return Object.freeze({
+        source,
+        authorization: Object.freeze({ region, identifiers: Object.freeze(identifiers) }),
+        productName: required(input.productName, 'veterinary_biologic_product_name_required'),
+        ...(typeof input.trueName === 'string' && input.trueName.trim() ? { trueName: input.trueName.trim() } : {}),
+        tradeNames: strings(input.tradeNames ?? [], 'veterinary_biologic_trade_name_invalid'),
+        manufacturer: required(input.manufacturer, 'veterinary_biologic_manufacturer_required'),
+        species: Object.freeze(species),
+        targetDiseases: Object.freeze(targetDiseases),
+        atcVetCodes,
+        agents: strings(input.agents ?? [], 'veterinary_biologic_agent_invalid'),
+    });
+}
+/** Pure catalog filtering after source adapters have produced governed records. */
+export function filterVeterinaryBiologicProducts(products, filter) {
+    const speciesCode = required(filter.speciesTaxonomyCode, 'veterinary_biologic_species_filter_required');
+    const text = String(filter.text || '').trim().toLocaleLowerCase('en');
+    return products.filter((product) => product.authorization.region === filter.region)
+        .filter((product) => product.species.some(({ code }) => code === speciesCode))
+        .filter((product) => !filter.targetDisease || product.targetDiseases.some(({ system, code }) => (system === filter.targetDisease?.system && code === filter.targetDisease.code)))
+        .filter((product) => !text || [product.productName, product.trueName, ...product.tradeNames, ...product.agents]
+        .filter(Boolean).some((candidate) => String(candidate).toLocaleLowerCase('en').includes(text)));
+}
+const rabies = Object.freeze({ system: 'http://snomed.info/sct', code: '14168008', display: 'Rabies' });
+/** Shared synthetic fixtures; identifiers are deliberately test-only, while systems/taxa are canonical. */
+export const VETERINARY_BIOLOGIC_PRODUCT_TEST_DATA = Object.freeze({
+    euDogRabies: Object.freeze({
+        source: VeterinaryBiologicProductSources.EmaUpd,
+        authorization: Object.freeze({ region: VeterinaryBiologicAuthorizationRegions.EuEea, identifiers: Object.freeze([
+                Object.freeze({ kind: VeterinaryBiologicIdentifierKinds.EmaUpdProductId, value: 'test-eu-product-1' }),
+            ]) }),
+        productName: 'Test EU canine rabies vaccine', tradeNames: Object.freeze(['Test EU Rabies']),
+        manufacturer: 'Test manufacturer EU', species: Object.freeze([VeterinarySpeciesTaxonomy.Dog]),
+        targetDiseases: Object.freeze([rabies]), atcVetCodes: Object.freeze(['QI07AA90']), agents: Object.freeze(['Rabies virus']),
+    }),
+    usCattleProduct: Object.freeze({
+        source: VeterinaryBiologicProductSources.UsdaCvb,
+        authorization: Object.freeze({ region: VeterinaryBiologicAuthorizationRegions.Us, identifiers: Object.freeze([
+                Object.freeze({ kind: VeterinaryBiologicIdentifierKinds.UsdaCvbPcn, value: 'test-us-pcn-1' }),
+            ]) }),
+        productName: 'Test US cattle biologic', trueName: 'Test cattle agent vaccine', tradeNames: Object.freeze([]),
+        manufacturer: 'Test manufacturer US', species: Object.freeze([VeterinarySpeciesTaxonomy.Cattle]),
+        targetDiseases: Object.freeze([{ system: 'https://example.test/disease', code: 'test-cattle-disease' }]),
+        atcVetCodes: Object.freeze([]), agents: Object.freeze(['Test cattle agent']),
+    }),
+    caDogRabies: Object.freeze({
+        source: VeterinaryBiologicProductSources.CfiaCcvb,
+        authorization: Object.freeze({ region: VeterinaryBiologicAuthorizationRegions.Ca, identifiers: Object.freeze([
+                Object.freeze({ kind: VeterinaryBiologicIdentifierKinds.CfiaCcvbNumber, value: 'test-ca-ccvb-1' }),
+                Object.freeze({ kind: VeterinaryBiologicIdentifierKinds.UsdaCode, value: 'test-usda-code-1' }),
+            ]) }),
+        productName: 'Test Canadian canine rabies vaccine', tradeNames: Object.freeze(['Test CA Rabies']),
+        manufacturer: 'Test manufacturer CA', species: Object.freeze([VeterinarySpeciesTaxonomy.Dog]),
+        targetDiseases: Object.freeze([rabies]), atcVetCodes: Object.freeze(['QI07AA90']), agents: Object.freeze(['Rabies virus']),
+    }),
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vet-data-utils-ts",
-  "version": "0.5.30",
+  "version": "0.5.32",
   "description": "Browser-safe governed VetChain data contracts",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",
@@ -56,6 +56,14 @@
       "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-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"
@@ -115,6 +123,10 @@
     "./scheduling": {
       "types": "./dist/scheduling.d.ts",
       "default": "./dist/scheduling.js"
+    },
+    "./veterinary-biologic-product": {
+      "types": "./dist/veterinary-biologic-product.d.ts",
+      "default": "./dist/veterinary-biologic-product.js"
     }
   },
   "files": [
@@ -138,7 +150,8 @@
   },
   "dependencies": {
     "gdc-common-utils-ts": "2.9.12",
-    "pako": "^2.2.0"
+    "pako": "^2.2.0",
+    "sos-data-utils-ts": "0.3.1"
   },
   "engines": {
     "node": ">=20"