vet-data-utils-ts 0.5.16 → 0.5.18

package/README.md

@@ -30,6 +30,26 @@ shows FHIR `Immunization.occurrenceDateTime`, `vaccineCode` and
 `protocolApplied.targetDisease`. Its issuer-supplied validity interval is not
 FHIR `Immunization.expirationDate`, which means vaccine-batch expiry.
 
+`prepareVeterinaryIndexTaggedBundle(...)` creates the interoperable messaging
+copy of a native FHIR Bundle document. It derives only the caller-allowlisted
+`<ResourceType>.<search-param-or-custom>` Coding systems in
+`resource.meta.tag[]`, preserves repeated values as repeated tags for later CSV
+projection, rejects generic `Resource.*` systems, and never mutates the source
+Bundle.
+
+`projectVeterinaryClaimsIndexForUi(...)` is the reverse BFF boundary for an
+already role-authorized GW search result. It removes every clinical field and
+`meta.claims`, returning only `fullUrl`, `resourceType`, `id` and allowlisted
+`meta.tag[]`; CSV claims are restored as repeated tags.
+`summarizeVeterinaryTaggedIndex(...)` then sorts and counts that minimized copy
+without inspecting resource content.
+
+`buildSmartHealthCardJwsProofReference(...)` serves a different purpose: it
+hashes the exact compact SHC JWS, including its ES256 signature, with a domain
+separator. A product ledger/resolver may use that key to retrieve the existing
+detached `pqc:/` proofs when only the SHC QR is printed and internet access is
+available. Offline PQC verification still requires the companion QR labels.
+
 Development and releases follow the mandatory
 [`local-first TDD and release contract`](docs/LOCAL_FIRST_RELEASE_CONTRACT.md).
 

package/dist/index-projection-tags.d.ts

@@ -0,0 +1,27 @@
+type JsonObject = Record<string, unknown>;
+export type VeterinaryIndexTagPolicy = Readonly<{
+    allowedTagSystems: ReadonlySet<string>;
+}>;
+export type VeterinaryUiIndexPolicy = VeterinaryIndexTagPolicy & Readonly<{
+    allowedResourceTypes: ReadonlySet<string>;
+}>;
+/**
+ * Creates the interoperable message/index copy of a native FHIR Bundle.
+ * Only allowlisted, resource-qualified Coding tags are retained or derived;
+ * display/text are deliberately omitted and the caller's Bundle is unchanged.
+ */
+export declare function prepareVeterinaryIndexTaggedBundle<T extends JsonObject>(source: T, policy: VeterinaryIndexTagPolicy): T;
+/**
+ * Converts an authorized GW claims search response into the only shape exposed
+ * to an index-only UI. Clinical fields and `meta.claims` are discarded.
+ */
+export declare function projectVeterinaryClaimsIndexForUi(source: JsonObject, policy: VeterinaryUiIndexPolicy): JsonObject;
+/** Counts and sorts an already minimized tagged index without reading clinical content. */
+export declare function summarizeVeterinaryTaggedIndex(source: JsonObject, options?: Readonly<{
+    sortSystem?: string;
+}>): Readonly<{
+    total: number;
+    countsByResourceType: Record<string, number>;
+    entries: JsonObject[];
+}>;
+export {};

package/dist/index-projection-tags.js

@@ -0,0 +1,183 @@
+/**
+ * Creates the interoperable message/index copy of a native FHIR Bundle.
+ * Only allowlisted, resource-qualified Coding tags are retained or derived;
+ * display/text are deliberately omitted and the caller's Bundle is unchanged.
+ */
+export function prepareVeterinaryIndexTaggedBundle(source, policy) {
+    if (source.resourceType !== 'Bundle' || source.type !== 'document' || !Array.isArray(source.entry)) {
+        throw new TypeError('veterinary_index_bundle_document_required');
+    }
+    const result = structuredClone(source);
+    const entries = result.entry;
+    for (const entry of entries) {
+        const resource = isObject(entry.resource) ? entry.resource : undefined;
+        const resourceType = typeof resource?.resourceType === 'string' ? resource.resourceType : '';
+        if (!resource || !resourceType)
+            continue;
+        const retained = existingTags(resource).filter(tag => (policy.allowedTagSystems.has(tag.system)
+            && tag.system.startsWith(`${resourceType}.`)));
+        const derived = [...policy.allowedTagSystems]
+            .filter(system => system.startsWith(`${resourceType}.`))
+            .flatMap(system => deriveValues(resource, system.slice(resourceType.length + 1))
+            .map(code => ({ system, code })));
+        const tags = uniqueTags([...retained, ...derived])
+            .sort((left, right) => left.system.localeCompare(right.system) || left.code.localeCompare(right.code));
+        if (!tags.length)
+            continue;
+        const meta = isObject(resource.meta) ? resource.meta : {};
+        resource.meta = { ...meta, tag: tags };
+    }
+    return result;
+}
+/**
+ * Converts an authorized GW claims search response into the only shape exposed
+ * to an index-only UI. Clinical fields and `meta.claims` are discarded.
+ */
+export function projectVeterinaryClaimsIndexForUi(source, policy) {
+    if (source.resourceType !== 'Bundle' || !Array.isArray(source.entry)) {
+        throw new TypeError('veterinary_claims_index_bundle_required');
+    }
+    const entry = source.entry.flatMap(rawEntry => {
+        if (!isObject(rawEntry) || typeof rawEntry.fullUrl !== 'string' || !isObject(rawEntry.resource))
+            return [];
+        const resource = rawEntry.resource;
+        const resourceType = typeof resource.resourceType === 'string' ? resource.resourceType : '';
+        const id = typeof resource.id === 'string' ? resource.id : '';
+        if (!resourceType || !id || !policy.allowedResourceTypes.has(resourceType))
+            return [];
+        const meta = isObject(resource.meta) ? resource.meta : undefined;
+        const claims = isObject(meta?.claims) ? meta.claims : undefined;
+        if (!claims)
+            return [];
+        const tag = Object.entries(claims)
+            .filter(([system]) => policy.allowedTagSystems.has(system) && system.startsWith(`${resourceType}.`))
+            .flatMap(([system, raw]) => claimValues(raw).map(code => ({ system, code })))
+            .sort((left, right) => left.system.localeCompare(right.system) || left.code.localeCompare(right.code));
+        if (!tag.length)
+            return [];
+        return [{
+                fullUrl: rawEntry.fullUrl,
+                resource: { resourceType, id, meta: { tag } },
+            }];
+    });
+    return { resourceType: 'Bundle', type: 'searchset', total: entry.length, entry };
+}
+/** Counts and sorts an already minimized tagged index without reading clinical content. */
+export function summarizeVeterinaryTaggedIndex(source, options = {}) {
+    if (source.resourceType !== 'Bundle' || !Array.isArray(source.entry)) {
+        throw new TypeError('veterinary_tagged_index_bundle_required');
+    }
+    const entries = source.entry.filter(isObject).map(entry => structuredClone(entry));
+    if (options.sortSystem)
+        entries.sort((left, right) => (taggedValue(right, options.sortSystem) || '').localeCompare(taggedValue(left, options.sortSystem) || ''));
+    const countsByResourceType = {};
+    for (const entry of entries) {
+        const resource = isObject(entry.resource) ? entry.resource : undefined;
+        if (typeof resource?.resourceType !== 'string')
+            continue;
+        countsByResourceType[resource.resourceType] = (countsByResourceType[resource.resourceType] || 0) + 1;
+    }
+    return { total: entries.length, countsByResourceType, entries };
+}
+function deriveValues(resource, parameter) {
+    switch (`${String(resource.resourceType)}.${parameter}`) {
+        case 'Composition.date': return scalar(resource.date);
+        case 'Composition.language': return scalar(resource.language);
+        case 'Composition.type': return conceptCodes(resource.type);
+        case 'Immunization.date': return scalar(resource.occurrenceDateTime);
+        case 'Immunization.status': return scalar(resource.status);
+        case 'Immunization.language': return scalar(resource.language);
+        case 'Immunization.reason-code': return conceptArrayCodes(resource.reasonCode);
+        case 'Immunization.vaccine-code': return conceptCodes(resource.vaccineCode);
+        case 'AllergyIntolerance.onset-date': return dateChoice(resource, 'onset');
+        case 'AllergyIntolerance.criticality': return scalar(resource.criticality);
+        case 'AllergyIntolerance.clinical-status': return conceptCodes(resource.clinicalStatus);
+        case 'AllergyIntolerance.category': return stringArray(resource.category);
+        case 'AllergyIntolerance.code': return conceptCodes(resource.code);
+        case 'AllergyIntolerance.language': return scalar(resource.language);
+        case 'Condition.onset-date': return dateChoice(resource, 'onset');
+        case 'Condition.abatement-date': return dateChoice(resource, 'abatement');
+        case 'Condition.clinical-status': return conceptCodes(resource.clinicalStatus);
+        case 'Condition.severity': return conceptCodes(resource.severity);
+        case 'Condition.code': return conceptCodes(resource.code);
+        case 'Condition.language': return scalar(resource.language);
+        case 'MedicationStatement.effective': return dateChoice(resource, 'effective');
+        case 'MedicationStatement.status': return scalar(resource.status);
+        case 'MedicationStatement.medication': return conceptCodes(resource.medicationCodeableConcept);
+        case 'MedicationStatement.language': return scalar(resource.language);
+        case 'Appointment.date': return scalar(resource.start);
+        case 'Appointment.status': return scalar(resource.status);
+        case 'Appointment.service-type': return conceptArrayCodes(resource.serviceType);
+        case 'Appointment.language': return scalar(resource.language);
+        case 'Coverage.period': return periodValues(resource.period);
+        case 'Coverage.status': return scalar(resource.status);
+        case 'Coverage.type': return conceptCodes(resource.type);
+        case 'Coverage.language': return scalar(resource.language);
+        case 'Contract.issued': return scalar(resource.issued);
+        case 'Contract.status': return scalar(resource.status);
+        case 'Contract.type': return conceptCodes(resource.type);
+        case 'Contract.language': return scalar(resource.language);
+        case 'DocumentReference.date': return scalar(resource.date);
+        case 'DocumentReference.status': return scalar(resource.status);
+        case 'DocumentReference.type': return conceptCodes(resource.type);
+        case 'DocumentReference.language': return scalar(resource.language);
+        default: return [];
+    }
+}
+function existingTags(resource) {
+    const meta = isObject(resource.meta) ? resource.meta : undefined;
+    return Array.isArray(meta?.tag) ? meta.tag.flatMap(value => {
+        if (!isObject(value) || typeof value.system !== 'string' || typeof value.code !== 'string')
+            return [];
+        return value.system && value.code ? [{ system: value.system, code: value.code }] : [];
+    }) : [];
+}
+function conceptCodes(value) {
+    if (!isObject(value) || !Array.isArray(value.coding))
+        return [];
+    return value.coding.flatMap(coding => isObject(coding) ? scalar(coding.code) : []);
+}
+function conceptArrayCodes(value) {
+    return Array.isArray(value) ? value.flatMap(conceptCodes) : conceptCodes(value);
+}
+function dateChoice(resource, prefix) {
+    return [
+        ...scalar(resource[`${prefix}DateTime`]),
+        ...scalar(resource[`${prefix}Date`]),
+        ...periodValues(resource[`${prefix}Period`]),
+    ];
+}
+function periodValues(value) {
+    if (!isObject(value))
+        return [];
+    return [...scalar(value.start), ...scalar(value.end)];
+}
+function scalar(value) {
+    return typeof value === 'string' && value.trim() ? [value.trim()] : [];
+}
+function stringArray(value) {
+    return Array.isArray(value) ? value.flatMap(scalar) : scalar(value);
+}
+function claimValues(value) {
+    return (Array.isArray(value) ? value : [value]).flatMap(item => (typeof item === 'string' ? item.split(',').map(part => part.trim()).filter(Boolean) : []));
+}
+function taggedValue(entry, system) {
+    const resource = isObject(entry.resource) ? entry.resource : undefined;
+    const meta = isObject(resource?.meta) ? resource.meta : undefined;
+    const tags = Array.isArray(meta?.tag) ? meta.tag : [];
+    const tag = tags.find(value => isObject(value) && value.system === system);
+    return isObject(tag) && typeof tag.code === 'string' ? tag.code : undefined;
+}
+function uniqueTags(tags) {
+    const seen = new Set();
+    return tags.filter(tag => {
+        const key = `${tag.system}\0${tag.code}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+function isObject(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}

package/dist/index.d.ts

@@ -9,6 +9,7 @@ export * from './financial.js';
 export * from './group.js';
 export * from './immunization.js';
 export * from './international-health-card.js';
+export * from './index-projection-tags.js';
 export * from './iso-jurisdictions.js';
 export * from './organization-application.js';
 export * from './payment.js';

package/dist/index.js

@@ -9,6 +9,7 @@ export * from './financial.js';
 export * from './group.js';
 export * from './immunization.js';
 export * from './international-health-card.js';
+export * from './index-projection-tags.js';
 export * from './iso-jurisdictions.js';
 export * from './organization-application.js';
 export * from './payment.js';

package/dist/shc.d.ts

@@ -55,6 +55,13 @@ export declare function assembleSmartHealthCardJws(prepared: Pick<PreparedSmartH
  * content identifier. They are deliberately not aliases.
  */
 export declare function buildSmartHealthCardPayloadReferences(payloadBytes: Uint8Array): SmartHealthCardPayloadReferences;
+/**
+ * Builds the optional online lookup key for a PQC companion proof from the
+ * exact compact SHC JWS printed by `shc:/`. This is intentionally distinct
+ * from the canonical payload references above: it includes the ES256
+ * signature and uses a domain separator so the two namespaces cannot collide.
+ */
+export declare function buildSmartHealthCardJwsProofReference(compactJws: string): string;
 /** Encodes one compact SHC JWS into one or more standard numeric QR payloads. */
 export declare function encodeSmartHealthCardQr(compactJws: string): readonly string[];
 /** Reassembles standard SHC QR payloads regardless of scan order. */

package/dist/shc.js

@@ -156,6 +156,19 @@ export function buildSmartHealthCardPayloadReferences(payloadBytes) {
         cidV1: buildRawCidV1FromUtf8String(payloadText),
     };
 }
+/**
+ * Builds the optional online lookup key for a PQC companion proof from the
+ * exact compact SHC JWS printed by `shc:/`. This is intentionally distinct
+ * from the canonical payload references above: it includes the ES256
+ * signature and uses a domain separator so the two namespaces cannot collide.
+ */
+export function buildSmartHealthCardJwsProofReference(compactJws) {
+    const jws = nonEmptyString(compactJws, 'shc_compact_jws_required');
+    if (jws.split('.').length !== 3)
+        throw new TypeError('shc_compact_jws_required');
+    const lookupBytes = Content.stringToBytesUTF8(`vetchain:shc-jws-pqc-proof:v1\0${jws}`);
+    return `urn:multibase:${encodeMultibaseSha3(lookupBytes, 384)}`;
+}
 /** Encodes one compact SHC JWS into one or more standard numeric QR payloads. */
 export function encodeSmartHealthCardQr(compactJws) {
     const jws = nonEmptyString(compactJws, 'shc_compact_jws_required');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vet-data-utils-ts",
-  "version": "0.5.16",
+  "version": "0.5.18",
   "description": "Browser-safe governed VetChain data contracts",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",
@@ -52,6 +52,10 @@
       "types": "./dist/international-health-card.d.ts",
       "default": "./dist/international-health-card.js"
     },
+    "./index-projection-tags": {
+      "types": "./dist/index-projection-tags.d.ts",
+      "default": "./dist/index-projection-tags.js"
+    },
     "./iso-jurisdictions": {
       "types": "./dist/iso-jurisdictions.d.ts",
       "default": "./dist/iso-jurisdictions.js"