vet-data-utils-ts 0.3.0

package/README.md

@@ -0,0 +1,14 @@
+# vet-data-utils-ts
+
+Browser-safe, transport-neutral VetChain data contracts shared by GW VET and
+`vet-sdk-core-ts`. The package owns governed values and validation only; GW VET
+owns authorization and the SDK owns request construction.
+
+Current surfaces cover the canonical animal-card DID, veterinary summary
+sections, animal-only emergency data, pseudonymous DigitalTwin search input and
+veterinary assistant intents.
+
+The catalogue retains longitudinal sections that also apply to animal care,
+with animal-facing labels where needed. Human advance directives
+(`LOINC|42348-3`) are deliberately excluded because they express the patient's
+own legal/autonomy decisions, not controller preferences.

package/dist/animal-card.d.ts

@@ -0,0 +1,14 @@
+export type VetChainAnimalCardIdentity = Readonly<{
+    did: string;
+    host: string;
+    jurisdictionCode5: string;
+    animalNumericId15: string;
+    checkDigit1: string;
+    animalId16: string;
+    cardNumber21: string;
+}>;
+/** Parses only the current VetChain card DID; legacy UHC animal aliases are rejected. */
+export declare function parseVetChainAnimalCardDid(value: unknown): VetChainAnimalCardIdentity;
+export declare function isVetChainAnimalCardDid(value: unknown): value is string;
+/** Returns the Damm digit that makes the complete decimal card validate to zero. */
+export declare function computeVetChainDammCheckDigit(value: string): string;

package/dist/animal-card.js

@@ -0,0 +1,44 @@
+const CARD_DID = /^did:web:([^:]+):card:vetchain:(\d{5}):(\d{16})$/i;
+/** Parses only the current VetChain card DID; legacy UHC animal aliases are rejected. */
+export function parseVetChainAnimalCardDid(value) {
+    const did = String(value || '').trim();
+    const match = CARD_DID.exec(did);
+    if (!match)
+        throw new TypeError('vet_animal_card_did_invalid');
+    const [, host, jurisdictionCode5, animalId16] = match;
+    const cardNumber21 = `${jurisdictionCode5}${animalId16}`;
+    return Object.freeze({
+        did,
+        host: host.toLowerCase(),
+        jurisdictionCode5,
+        animalNumericId15: animalId16.slice(0, 15),
+        checkDigit1: animalId16.slice(15),
+        animalId16,
+        cardNumber21,
+    });
+}
+export function isVetChainAnimalCardDid(value) {
+    try {
+        parseVetChainAnimalCardDid(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Returns the Damm digit that makes the complete decimal card validate to zero. */
+export function computeVetChainDammCheckDigit(value) {
+    if (!/^\d+$/.test(value))
+        throw new TypeError('vet_animal_card_damm_input_invalid');
+    let interim = 0;
+    for (const digit of value)
+        interim = DAMM_TABLE[interim][Number(digit)];
+    return String(interim);
+}
+const DAMM_TABLE = [
+    [0, 3, 1, 7, 5, 9, 8, 6, 4, 2], [7, 0, 9, 2, 1, 5, 4, 8, 6, 3],
+    [4, 2, 0, 6, 8, 7, 1, 3, 5, 9], [1, 7, 5, 0, 9, 8, 3, 4, 2, 6],
+    [6, 1, 2, 3, 0, 4, 5, 9, 7, 8], [3, 6, 7, 4, 2, 0, 9, 5, 8, 1],
+    [5, 8, 6, 9, 7, 2, 0, 1, 3, 4], [8, 9, 4, 5, 3, 6, 2, 0, 1, 7],
+    [9, 4, 3, 8, 6, 1, 7, 2, 0, 5], [2, 5, 8, 1, 4, 3, 6, 7, 9, 0],
+];

package/dist/assistant.d.ts

@@ -0,0 +1,7 @@
+export declare const VeterinaryAssistantIntents: Readonly<{
+    readonly ExplainAnimalIdentity: "explain-animal-identity";
+    readonly ExplainPermissions: "explain-permissions";
+    readonly ExplainEmergencyAccess: "explain-emergency-access";
+    readonly ExplainDigitalTwin: "explain-digital-twin";
+}>;
+export type VeterinaryAssistantIntent = typeof VeterinaryAssistantIntents[keyof typeof VeterinaryAssistantIntents];

package/dist/assistant.js

@@ -0,0 +1,6 @@
+export const VeterinaryAssistantIntents = Object.freeze({
+    ExplainAnimalIdentity: 'explain-animal-identity',
+    ExplainPermissions: 'explain-permissions',
+    ExplainEmergencyAccess: 'explain-emergency-access',
+    ExplainDigitalTwin: 'explain-digital-twin',
+});

package/dist/digital-twin.d.ts

@@ -0,0 +1,13 @@
+export declare const VeterinaryDigitalTwinFormats: Readonly<{
+    readonly Api: "org.hl7.fhir.api";
+    readonly R4: "org.hl7.fhir.r4";
+}>;
+export type VeterinaryDigitalTwinFormat = typeof VeterinaryDigitalTwinFormats[keyof typeof VeterinaryDigitalTwinFormats];
+export type VeterinaryDigitalTwinSearch = Readonly<{
+    section: string;
+    resourceType: string;
+    claim: string;
+    value: string;
+}>;
+/** Bounds one section-first pseudonymous search and rejects direct identifiers. */
+export declare function parseVeterinaryDigitalTwinSearch(input: unknown): VeterinaryDigitalTwinSearch;

package/dist/digital-twin.js

@@ -0,0 +1,24 @@
+import { isVeterinarySummarySection } from './veterinary-sections.js';
+export const VeterinaryDigitalTwinFormats = Object.freeze({ Api: 'org.hl7.fhir.api', R4: 'org.hl7.fhir.r4' });
+/** Bounds one section-first pseudonymous search and rejects direct identifiers. */
+export function parseVeterinaryDigitalTwinSearch(input) {
+    const value = (input || {});
+    for (const forbidden of ['name', 'email', 'telephone', 'identifier', 'subjectDid', 'cardNumber']) {
+        if (String(value[forbidden] || '').trim())
+            throw new TypeError('veterinary_digital_twin_identifying_filter_forbidden');
+    }
+    const section = String(value.section || '').trim();
+    const resourceType = String(value.resourceType || '').trim();
+    const claim = String(value.claim || '').trim();
+    const filterValue = String(value.value || '').trim();
+    if (!isVeterinarySummarySection(section))
+        throw new TypeError('veterinary_digital_twin_section_invalid');
+    if (!/^[A-Z][A-Za-z]{1,63}$/.test(resourceType))
+        throw new TypeError('veterinary_digital_twin_resource_invalid');
+    if (!new RegExp(`^${resourceType.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\.[A-Za-z0-9][A-Za-z0-9.-]{0,127}$`).test(claim)) {
+        throw new TypeError('veterinary_digital_twin_claim_invalid');
+    }
+    if (!filterValue || filterValue.length > 256)
+        throw new TypeError('veterinary_digital_twin_value_invalid');
+    return Object.freeze({ section, resourceType, claim, value: filterValue });
+}

package/dist/emergency.d.ts

@@ -0,0 +1,17 @@
+export declare const VeterinaryOccupationCodes: Readonly<{
+    Veterinarian: "2250";
+}>;
+export declare const VeterinaryEmergencyReasonCodes: Readonly<{
+    AnimalEmergency: "animal-emergency";
+}>;
+export declare const VeterinaryBreakGlassMaxLifetimeSeconds: number;
+export type VeterinaryBreakGlassRequestData = Readonly<{
+    subjectDid: string;
+    requestedSections: readonly string[];
+    incidentId: string;
+    justification: string;
+    subjectKind: 'animal';
+    reasonCode: 'animal-emergency';
+}>;
+/** Normalizes transport-neutral animal emergency data; GW remains the policy authority. */
+export declare function parseVeterinaryBreakGlassRequestData(input: unknown): VeterinaryBreakGlassRequestData;

package/dist/emergency.js

@@ -0,0 +1,25 @@
+import { isVetChainAnimalCardDid } from './animal-card.js';
+import { isVeterinarySummarySection } from './veterinary-sections.js';
+export const VeterinaryOccupationCodes = Object.freeze({ Veterinarian: '2250' });
+export const VeterinaryEmergencyReasonCodes = Object.freeze({ AnimalEmergency: 'animal-emergency' });
+export const VeterinaryBreakGlassMaxLifetimeSeconds = 15 * 60;
+/** Normalizes transport-neutral animal emergency data; GW remains the policy authority. */
+export function parseVeterinaryBreakGlassRequestData(input) {
+    const value = (input || {});
+    const subjectDid = String(value.subjectDid || '').trim();
+    if (!isVetChainAnimalCardDid(subjectDid))
+        throw new TypeError('veterinary_break_glass_animal_required');
+    const incidentId = String(value.incidentId || '').trim();
+    if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$/.test(incidentId))
+        throw new TypeError('veterinary_break_glass_incident_invalid');
+    const justification = String(value.justification || '').trim();
+    if (justification.length < 20 || justification.length > 500)
+        throw new TypeError('veterinary_break_glass_justification_invalid');
+    const requestedSections = [...new Set(Array.isArray(value.requestedSections)
+            ? value.requestedSections.map(String).map(item => item.trim()).filter(Boolean)
+            : [])];
+    if (!requestedSections.length || requestedSections.some(section => !isVeterinarySummarySection(section))) {
+        throw new TypeError('veterinary_break_glass_sections_invalid');
+    }
+    return Object.freeze({ subjectDid, requestedSections, incidentId, justification, subjectKind: 'animal', reasonCode: 'animal-emergency' });
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './animal-card.js';
+export * from './assistant.js';
+export * from './digital-twin.js';
+export * from './emergency.js';
+export * from './veterinary-sections.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from './animal-card.js';
+export * from './assistant.js';
+export * from './digital-twin.js';
+export * from './emergency.js';
+export * from './veterinary-sections.js';

package/dist/veterinary-sections.d.ts

@@ -0,0 +1,101 @@
+export type VeterinarySummarySection = Readonly<{
+    system: 'http://loinc.org';
+    code: string;
+    value: `LOINC|${string}`;
+    titleEn: string;
+}>;
+/** VetChain-owned clinical section catalog. It is not an alias of human IPS. */
+export declare const VeterinarySummarySections: Readonly<{
+    Problems: Readonly<{
+        system: "http://loinc.org";
+        code: string;
+        value: `LOINC|${string}`;
+        titleEn: string;
+    }>;
+    Allergies: Readonly<{
+        system: "http://loinc.org";
+        code: string;
+        value: `LOINC|${string}`;
+        titleEn: string;
+    }>;
+    Medications: Readonly<{
+        system: "http://loinc.org";
+        code: string;
+        value: `LOINC|${string}`;
+        titleEn: string;
+    }>;
+    Immunizations: Readonly<{
+        system: "http://loinc.org";
+        code: string;
+        value: `LOINC|${string}`;
+        titleEn: string;
+    }>;
+    Results: Readonly<{
+        system: "http://loinc.org";
+        code: string;
+        value: `LOINC|${string}`;
+        titleEn: string;
+    }>;
+    Procedures: Readonly<{
+        system: "http://loinc.org";
+        code: string;
+        value: `LOINC|${string}`;
+        titleEn: string;
+    }>;
+    Devices: Readonly<{
+        system: "http://loinc.org";
+        code: string;
+        value: `LOINC|${string}`;
+        titleEn: string;
+    }>;
+    VitalSigns: Readonly<{
+        system: "http://loinc.org";
+        code: string;
+        value: `LOINC|${string}`;
+        titleEn: string;
+    }>;
+    EnvironmentAndLifestyle: Readonly<{
+        system: "http://loinc.org";
+        code: string;
+        value: `LOINC|${string}`;
+        titleEn: string;
+    }>;
+    Alerts: Readonly<{
+        system: "http://loinc.org";
+        code: string;
+        value: `LOINC|${string}`;
+        titleEn: string;
+    }>;
+    CareGoalsAndControllerPreferences: Readonly<{
+        system: "http://loinc.org";
+        code: string;
+        value: `LOINC|${string}`;
+        titleEn: string;
+    }>;
+    FunctionalStatus: Readonly<{
+        system: "http://loinc.org";
+        code: string;
+        value: `LOINC|${string}`;
+        titleEn: string;
+    }>;
+    PastIllness: Readonly<{
+        system: "http://loinc.org";
+        code: string;
+        value: `LOINC|${string}`;
+        titleEn: string;
+    }>;
+    ReproductiveHistory: Readonly<{
+        system: "http://loinc.org";
+        code: string;
+        value: `LOINC|${string}`;
+        titleEn: string;
+    }>;
+    CarePlan: Readonly<{
+        system: "http://loinc.org";
+        code: string;
+        value: `LOINC|${string}`;
+        titleEn: string;
+    }>;
+}>;
+export declare const VeterinarySummarySectionValues: readonly `LOINC|${string}`[];
+export declare function isVeterinarySummarySection(value: unknown): value is string;

package/dist/veterinary-sections.js

@@ -0,0 +1,25 @@
+function loinc(code, titleEn) {
+    return Object.freeze({ system: 'http://loinc.org', code, value: `LOINC|${code}`, titleEn });
+}
+/** VetChain-owned clinical section catalog. It is not an alias of human IPS. */
+export const VeterinarySummarySections = Object.freeze({
+    Problems: loinc('11450-4', 'Problems and active conditions'),
+    Allergies: loinc('48765-2', 'Allergies and adverse reactions'),
+    Medications: loinc('10160-0', 'Medication history'),
+    Immunizations: loinc('11369-6', 'Vaccination history'),
+    Results: loinc('30954-2', 'Diagnostic and laboratory results'),
+    Procedures: loinc('47519-4', 'Procedure history'),
+    Devices: loinc('46264-8', 'Implants and animal devices'),
+    VitalSigns: loinc('8716-3', 'Vital signs'),
+    EnvironmentAndLifestyle: loinc('29762-2', 'Environment, lifestyle and husbandry history'),
+    Alerts: loinc('104605-1', 'Clinical alerts'),
+    CareGoalsAndControllerPreferences: loinc('81338-6', 'Care goals and controller preferences'),
+    FunctionalStatus: loinc('47420-5', 'Functional status'),
+    PastIllness: loinc('11348-0', 'History of past illness'),
+    ReproductiveHistory: loinc('10162-6', 'Reproductive history'),
+    CarePlan: loinc('18776-5', 'Veterinary care plan'),
+});
+export const VeterinarySummarySectionValues = Object.freeze(Object.values(VeterinarySummarySections).map(({ value }) => value));
+export function isVeterinarySummarySection(value) {
+    return VeterinarySummarySectionValues.includes(String(value || '').trim());
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "vet-data-utils-ts",
+  "version": "0.3.0",
+  "description": "Browser-safe governed VetChain data contracts",
+  "license": "Apache-2.0",
+  "author": "Connecting Solution & Applications Ltd",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
+    "./animal-card": { "types": "./dist/animal-card.d.ts", "default": "./dist/animal-card.js" },
+    "./digital-twin": { "types": "./dist/digital-twin.d.ts", "default": "./dist/digital-twin.js" },
+    "./emergency": { "types": "./dist/emergency.d.ts", "default": "./dist/emergency.js" },
+    "./veterinary-sections": { "types": "./dist/veterinary-sections.d.ts", "default": "./dist/veterinary-sections.js" },
+    "./assistant": { "types": "./dist/assistant.d.ts", "default": "./dist/assistant.js" }
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run typecheck && npm test"
+  },
+  "devDependencies": { "@types/node": "^22.0.0", "typescript": "^5.5.4" },
+  "engines": { "node": ">=20" }
+}