vet-data-utils-ts 0.5.30 → 0.5.31

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/index.d.ts

@@ -23,4 +23,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

@@ -23,4 +23,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.31",
   "description": "Browser-safe governed VetChain data contracts",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",
@@ -115,6 +115,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": [