vet-data-utils-ts 0.5.18 → 0.5.21

package/README.md

@@ -1,5 +1,13 @@
 # vet-data-utils-ts
 
+The product-local `place-service-directory` export models persistent public
+sites as claims-only Schema.org `Place` resources and their offerings as
+claims-only `Service` resources. Photos, accessibility, coordinates, address
+and opening-hours specifications remain neutral indexed claims. Native FHIR R5
+`Location` and `HealthcareService` are produced only by explicit projection
+helpers; the shared `gdc-*` claim catalog is unchanged while this profile is
+validated in VetChain.
+
 ## Veterinary immunization credentials
 
 `buildVeterinaryImmunization(...)` creates a FHIR R4 `Immunization` with the
@@ -44,6 +52,16 @@ already role-authorized GW search result. It removes every clinical field and
 `summarizeVeterinaryTaggedIndex(...)` then sorts and counts that minimized copy
 without inspecting resource content.
 
+`readVeterinaryBundleTags(...)` is the fail-closed UI reader for that minimized
+shape. It is intentionally separate from the clinical Bundle Reader and rejects
+`meta.claims`, clinical fields, resource types or tags outside the caller's
+already server-authorized policy. Its `cards` output groups repeated Coding
+values by resource-qualified search parameter, so an index-only screen can use
+the same card shell without constructing a clinical-resource view. An
+authorized full Bundle may first be reduced with
+`projectVeterinaryClaimsIndexForUi(...)` when it only needs that summary; the
+full clinical reader itself remains claims-first and unchanged.
+
 `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

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

@@ -5,6 +5,13 @@ export type VeterinaryIndexTagPolicy = Readonly<{
 export type VeterinaryUiIndexPolicy = VeterinaryIndexTagPolicy & Readonly<{
     allowedResourceTypes: ReadonlySet<string>;
 }>;
+export type VeterinaryIndexCardView = Readonly<{
+    fullUrl: string;
+    resourceType: string;
+    id: string;
+    /** Only server-authorized index values; never clinical resource content. */
+    tags: Readonly<Record<string, readonly string[]>>;
+}>;
 /**
  * Creates the interoperable message/index copy of a native FHIR Bundle.
  * Only allowlisted, resource-qualified Coding tags are retained or derived;
@@ -24,4 +31,22 @@ export declare function summarizeVeterinaryTaggedIndex(source: JsonObject, optio
     countsByResourceType: Record<string, number>;
     entries: JsonObject[];
 }>;
+/**
+ * Strict UI reader for an index-only Bundle. Unlike the clinical Bundle
+ * Reader, this refuses claims and every clinical resource field.
+ */
+export declare function readVeterinaryBundleTags(source: JsonObject, options: VeterinaryUiIndexPolicy & Readonly<{
+    sortSystem?: string;
+}>): {
+    cards: Readonly<{
+        fullUrl: string;
+        resourceType: string;
+        id: string;
+        /** Only server-authorized index values; never clinical resource content. */
+        tags: Readonly<Record<string, readonly string[]>>;
+    }>[];
+    total: number;
+    countsByResourceType: Record<string, number>;
+    entries: JsonObject[];
+};
 export {};

package/dist/index-projection-tags.js

@@ -79,6 +79,59 @@ export function summarizeVeterinaryTaggedIndex(source, options = {}) {
     }
     return { total: entries.length, countsByResourceType, entries };
 }
+/**
+ * Strict UI reader for an index-only Bundle. Unlike the clinical Bundle
+ * Reader, this refuses claims and every clinical resource field.
+ */
+export function readVeterinaryBundleTags(source, options) {
+    if (source.resourceType !== 'Bundle' || source.type !== 'searchset' || !Array.isArray(source.entry)) {
+        throw new TypeError('bundle_tags_reader_searchset_required');
+    }
+    for (const rawEntry of source.entry) {
+        if (!isObject(rawEntry) || !onlyKeys(rawEntry, ['fullUrl', 'resource'])
+            || typeof rawEntry.fullUrl !== 'string' || !isObject(rawEntry.resource)) {
+            throw new TypeError('bundle_tags_reader_unsafe_shape');
+        }
+        const resource = rawEntry.resource;
+        if (!onlyKeys(resource, ['resourceType', 'id', 'meta'])
+            || typeof resource.resourceType !== 'string' || typeof resource.id !== 'string'
+            || !isObject(resource.meta) || !onlyKeys(resource.meta, ['tag'])
+            || !Array.isArray(resource.meta.tag)) {
+            throw new TypeError('bundle_tags_reader_unsafe_shape');
+        }
+        if (!options.allowedResourceTypes.has(resource.resourceType)) {
+            throw new TypeError('bundle_tags_reader_resource_forbidden');
+        }
+        for (const rawTag of resource.meta.tag) {
+            if (!isObject(rawTag) || !onlyKeys(rawTag, ['system', 'code'])
+                || typeof rawTag.system !== 'string' || typeof rawTag.code !== 'string') {
+                throw new TypeError('bundle_tags_reader_unsafe_shape');
+            }
+            if (!options.allowedTagSystems.has(rawTag.system)
+                || !rawTag.system.startsWith(`${resource.resourceType}.`)) {
+                throw new TypeError('bundle_tags_reader_tag_forbidden');
+            }
+        }
+    }
+    const summary = summarizeVeterinaryTaggedIndex(source, { sortSystem: options.sortSystem });
+    const cards = summary.entries.map(entry => {
+        const resource = entry.resource;
+        const meta = resource.meta;
+        const tags = {};
+        for (const rawTag of meta.tag) {
+            const values = tags[rawTag.system] || [];
+            values.push(rawTag.code);
+            tags[rawTag.system] = values;
+        }
+        return {
+            fullUrl: entry.fullUrl,
+            resourceType: resource.resourceType,
+            id: resource.id,
+            tags,
+        };
+    });
+    return { ...summary, cards };
+}
 function deriveValues(resource, parameter) {
     switch (`${String(resource.resourceType)}.${parameter}`) {
         case 'Composition.date': return scalar(resource.date);
@@ -101,6 +154,9 @@ function deriveValues(resource, parameter) {
         case 'Condition.severity': return conceptCodes(resource.severity);
         case 'Condition.code': return conceptCodes(resource.code);
         case 'Condition.language': return scalar(resource.language);
+        case 'Observation.date': return [...dateChoice(resource, 'effective'), ...scalar(resource.issued)];
+        case 'Observation.status': return scalar(resource.status);
+        case 'Observation.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);
@@ -181,3 +237,7 @@ function uniqueTags(tags) {
 function isObject(value) {
     return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 }
+function onlyKeys(value, allowed) {
+    const names = new Set(allowed);
+    return Object.keys(value).every(key => names.has(key));
+}

package/dist/index.d.ts

@@ -13,6 +13,7 @@ export * from './index-projection-tags.js';
 export * from './iso-jurisdictions.js';
 export * from './organization-application.js';
 export * from './payment.js';
+export * from './place-service-directory.js';
 export * from './research-study.js';
 export * from './sectors.js';
 export * from './shc.js';

package/dist/index.js

@@ -13,6 +13,7 @@ export * from './index-projection-tags.js';
 export * from './iso-jurisdictions.js';
 export * from './organization-application.js';
 export * from './payment.js';
+export * from './place-service-directory.js';
 export * from './research-study.js';
 export * from './sectors.js';
 export * from './shc.js';

package/dist/place-service-directory.d.ts

@@ -0,0 +1,223 @@
+/** Schema.org flat claims for a persistent, sector-neutral public Place. */
+export declare enum ClaimsPlaceSchemaorg {
+    identifier = "org.schema.Place.identifier",
+    additionalType = "org.schema.Place.additionalType",
+    name = "org.schema.Place.name",
+    description = "org.schema.Place.description",
+    ownerIdentifier = "org.schema.Place.owner.identifier",
+    addressCountry = "org.schema.Place.address.addressCountry",
+    addressRegion = "org.schema.Place.address.addressRegion",
+    addressLocality = "org.schema.Place.address.addressLocality",
+    extendedAddress = "org.schema.Place.address.extendedAddress",
+    postalCode = "org.schema.Place.address.postalCode",
+    streetAddress = "org.schema.Place.address.streetAddress",
+    latitude = "org.schema.Place.geo.latitude",
+    longitude = "org.schema.Place.geo.longitude",
+    elevation = "org.schema.Place.geo.elevation",
+    photoContentUrl = "org.schema.Place.photo.contentUrl",
+    amenityFeature = "org.schema.Place.amenityFeature",
+    publicAccess = "org.schema.Place.publicAccess",
+    openingHoursSpecification = "org.schema.Place.openingHoursSpecification",
+    specialOpeningHoursSpecification = "org.schema.Place.specialOpeningHoursSpecification",
+    userSelected = "Place.user-selected"
+}
+/** Schema.org Service claims needed to join a public service to one or more Places. */
+export declare enum ClaimsDirectoryServiceSchemaorg {
+    identifier = "org.schema.Service.identifier",
+    name = "org.schema.Service.name",
+    description = "org.schema.Service.description",
+    providerIdentifier = "org.schema.Service.provider.identifier",
+    placeIdentifier = "org.schema.Service.availableChannel.serviceLocation.identifier",
+    serviceType = "org.schema.Service.serviceType",
+    category = "org.schema.Service.category",
+    areaServed = "org.schema.Service.areaServed",
+    userSelected = "Service.user-selected"
+}
+/** Product-local allowlist for the experimental Place and Service directory profile. */
+export declare const DirectoryFlatClaimCatalog: Readonly<{
+    readonly Place: readonly ClaimsPlaceSchemaorg[];
+    readonly Service: readonly ClaimsDirectoryServiceSchemaorg[];
+}>;
+export type DirectoryResourceType = keyof typeof DirectoryFlatClaimCatalog;
+export type DirectoryClaimValue = string | number | boolean | readonly string[];
+export type DirectoryResource = Readonly<{
+    resourceType: DirectoryResourceType;
+    id: string;
+    meta: Readonly<{
+        claims: Readonly<Record<string, DirectoryClaimValue>>;
+    }>;
+}>;
+export type DirectoryFlatClaimsResource = Readonly<{
+    resourceType: DirectoryResourceType;
+    id: string;
+    meta: Readonly<{
+        claims: Readonly<Record<string, readonly string[]>>;
+    }>;
+}>;
+export type OpeningHoursInput = Readonly<{
+    daysOfWeek: readonly string[];
+    opens: string;
+    closes: string;
+    validFrom?: string;
+    validThrough?: string;
+}>;
+export type SpecialOpeningHoursInput = Readonly<{
+    validFrom: string;
+    validThrough: string;
+    closed?: boolean;
+    opens?: string;
+    closes?: string;
+}>;
+export type PlaceDirectoryInput = Readonly<{
+    id: string;
+    organizationIdentifier: string;
+    name: string;
+    description?: string;
+    additionalType?: string;
+    address: Readonly<{
+        addressCountry: string;
+        addressRegion?: string;
+        addressLocality?: string;
+        extendedAddress?: string;
+        postalCode: string;
+        streetAddress?: string;
+    }>;
+    position: Readonly<{
+        latitude: number;
+        longitude: number;
+        elevation?: number;
+    }>;
+    photoUrl?: string;
+    accessibilityFeatures?: readonly string[];
+    publicAccess?: boolean;
+    openingHours?: readonly OpeningHoursInput[];
+    specialOpeningHours?: readonly SpecialOpeningHoursInput[];
+    userSelected?: boolean;
+}>;
+export type ServiceDirectoryInput = Readonly<{
+    id: string;
+    organizationIdentifier: string;
+    placeIdentifiers: readonly string[];
+    name: string;
+    description?: string;
+    serviceTypes: readonly string[];
+    categories?: readonly string[];
+    areaServed?: readonly string[];
+    userSelected?: boolean;
+}>;
+/** Builds the claims-only public Place authored by an organization. */
+export declare function buildPlaceDirectoryResource(input: PlaceDirectoryInput): DirectoryResource;
+/** Builds a claims-only Schema.org Service joined to its provider and public Places. */
+export declare function buildServiceDirectoryResource(input: ServiceDirectoryInput): DirectoryResource;
+/** Rejects native fields and converts a Place or Service into deterministic array-valued claims. */
+export declare function normalizeDirectoryFlatClaimsResource(input: unknown): DirectoryFlatClaimsResource;
+/** Explicitly projects one neutral Place to native FHIR R5 Location for export or interop. */
+export declare function projectPlaceToFhirR5Location(place: DirectoryResource | DirectoryFlatClaimsResource): Readonly<{
+    resourceType: "Location";
+    id: string;
+    status: "active";
+    mode: "instance";
+    name: string | undefined;
+    description: string | undefined;
+    address: {
+        line?: (string | undefined)[] | undefined;
+        country: string | undefined;
+        state: string | undefined;
+        city: string | undefined;
+        postalCode: string;
+    };
+    position: {
+        altitude?: number | undefined;
+        latitude: number;
+        longitude: number;
+    };
+    managingOrganization: {
+        reference: string;
+    };
+    characteristic: {
+        coding: {
+            code: string;
+        }[];
+    }[];
+    hoursOfOperation: {
+        availableTime: {
+            daysOfWeek: string[];
+            availableStartTime: string;
+            availableEndTime: string;
+        }[];
+        notAvailableTime: {
+            description: string;
+            during: {
+                start: string;
+                end: string;
+            };
+        }[];
+    }[];
+    meta: {
+        claims: {
+            'Location.characteristic'?: readonly string[] | undefined;
+            'Location.identifier': string;
+            'Location.status': string;
+            'Location.name': string | undefined;
+            'Location.address-postalcode': string;
+            'Location.near': string;
+            'Location.organization': string;
+        };
+    };
+}>;
+/** Explicitly projects a neutral Service and its Places to native FHIR R5 HealthcareService. */
+export declare function projectServiceToFhirR5HealthcareService(service: DirectoryResource | DirectoryFlatClaimsResource, input: Readonly<{
+    places: readonly (DirectoryResource | DirectoryFlatClaimsResource)[];
+}>): Readonly<{
+    meta: {
+        claims: {
+            'HealthcareService.service-category'?: readonly string[] | undefined;
+            'HealthcareService.identifier': string;
+            'HealthcareService.organization': string;
+            'HealthcareService.name': string | undefined;
+            'HealthcareService.location': string[];
+            'HealthcareService.service-type': readonly string[];
+        };
+    };
+    photo?: {
+        url: string;
+    } | undefined;
+    resourceType: "HealthcareService";
+    id: string;
+    active: true;
+    providedBy: {
+        reference: string;
+    };
+    name: string | undefined;
+    comment: string | undefined;
+    category: {
+        coding: {
+            code: string;
+        }[];
+    }[];
+    type: {
+        coding: {
+            code: string;
+        }[];
+    }[];
+    location: {
+        reference: string;
+    }[];
+}>;
+export type ClinicMarketplaceResult = Readonly<{
+    place: DirectoryResource | DirectoryFlatClaimsResource;
+    services: readonly (DirectoryResource | DirectoryFlatClaimsResource)[];
+    distanceKm?: number;
+}>;
+/** Joins and filters a public clinic directory by postal code, service and optional geographic radius. */
+export declare function searchClinicMarketplace(input: Readonly<{
+    places: readonly (DirectoryResource | DirectoryFlatClaimsResource)[];
+    services: readonly (DirectoryResource | DirectoryFlatClaimsResource)[];
+    postalCode?: string;
+    serviceTypes?: readonly string[];
+    near?: Readonly<{
+        latitude: number;
+        longitude: number;
+        radiusKm: number;
+    }>;
+}>): readonly ClinicMarketplaceResult[];

package/dist/place-service-directory.js

@@ -0,0 +1,332 @@
+// Copyright 2026 Connecting Solution & Applications Ltd under the Apache License, Version 2.0.
+/** Schema.org flat claims for a persistent, sector-neutral public Place. */
+export var ClaimsPlaceSchemaorg;
+(function (ClaimsPlaceSchemaorg) {
+    ClaimsPlaceSchemaorg["identifier"] = "org.schema.Place.identifier";
+    ClaimsPlaceSchemaorg["additionalType"] = "org.schema.Place.additionalType";
+    ClaimsPlaceSchemaorg["name"] = "org.schema.Place.name";
+    ClaimsPlaceSchemaorg["description"] = "org.schema.Place.description";
+    ClaimsPlaceSchemaorg["ownerIdentifier"] = "org.schema.Place.owner.identifier";
+    ClaimsPlaceSchemaorg["addressCountry"] = "org.schema.Place.address.addressCountry";
+    ClaimsPlaceSchemaorg["addressRegion"] = "org.schema.Place.address.addressRegion";
+    ClaimsPlaceSchemaorg["addressLocality"] = "org.schema.Place.address.addressLocality";
+    ClaimsPlaceSchemaorg["extendedAddress"] = "org.schema.Place.address.extendedAddress";
+    ClaimsPlaceSchemaorg["postalCode"] = "org.schema.Place.address.postalCode";
+    ClaimsPlaceSchemaorg["streetAddress"] = "org.schema.Place.address.streetAddress";
+    ClaimsPlaceSchemaorg["latitude"] = "org.schema.Place.geo.latitude";
+    ClaimsPlaceSchemaorg["longitude"] = "org.schema.Place.geo.longitude";
+    ClaimsPlaceSchemaorg["elevation"] = "org.schema.Place.geo.elevation";
+    ClaimsPlaceSchemaorg["photoContentUrl"] = "org.schema.Place.photo.contentUrl";
+    ClaimsPlaceSchemaorg["amenityFeature"] = "org.schema.Place.amenityFeature";
+    ClaimsPlaceSchemaorg["publicAccess"] = "org.schema.Place.publicAccess";
+    ClaimsPlaceSchemaorg["openingHoursSpecification"] = "org.schema.Place.openingHoursSpecification";
+    ClaimsPlaceSchemaorg["specialOpeningHoursSpecification"] = "org.schema.Place.specialOpeningHoursSpecification";
+    ClaimsPlaceSchemaorg["userSelected"] = "Place.user-selected";
+})(ClaimsPlaceSchemaorg || (ClaimsPlaceSchemaorg = {}));
+/** Schema.org Service claims needed to join a public service to one or more Places. */
+export var ClaimsDirectoryServiceSchemaorg;
+(function (ClaimsDirectoryServiceSchemaorg) {
+    ClaimsDirectoryServiceSchemaorg["identifier"] = "org.schema.Service.identifier";
+    ClaimsDirectoryServiceSchemaorg["name"] = "org.schema.Service.name";
+    ClaimsDirectoryServiceSchemaorg["description"] = "org.schema.Service.description";
+    ClaimsDirectoryServiceSchemaorg["providerIdentifier"] = "org.schema.Service.provider.identifier";
+    ClaimsDirectoryServiceSchemaorg["placeIdentifier"] = "org.schema.Service.availableChannel.serviceLocation.identifier";
+    ClaimsDirectoryServiceSchemaorg["serviceType"] = "org.schema.Service.serviceType";
+    ClaimsDirectoryServiceSchemaorg["category"] = "org.schema.Service.category";
+    ClaimsDirectoryServiceSchemaorg["areaServed"] = "org.schema.Service.areaServed";
+    ClaimsDirectoryServiceSchemaorg["userSelected"] = "Service.user-selected";
+})(ClaimsDirectoryServiceSchemaorg || (ClaimsDirectoryServiceSchemaorg = {}));
+/** Product-local allowlist for the experimental Place and Service directory profile. */
+export const DirectoryFlatClaimCatalog = Object.freeze({
+    Place: Object.freeze(Object.values(ClaimsPlaceSchemaorg)),
+    Service: Object.freeze(Object.values(ClaimsDirectoryServiceSchemaorg)),
+});
+const RESOURCE_ID_PATTERN = /^[A-Za-z0-9\-.]{1,64}$/;
+const TIME_PATTERN = /^(?:[01]\d|2[0-3]):[0-5]\d$/;
+const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+const DAY_NAMES = new Set(['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday']);
+function required(value, code) {
+    const normalized = String(value ?? '').trim();
+    if (!normalized)
+        throw new TypeError(code);
+    return normalized;
+}
+function optional(value) {
+    const normalized = String(value ?? '').trim();
+    return normalized || undefined;
+}
+function unique(values, code) {
+    const result = [...new Set((values ?? []).map(value => required(value, code)))];
+    return Object.freeze(result);
+}
+function assertCoordinate(value, minimum, maximum, code) {
+    if (!Number.isFinite(value) || value < minimum || value > maximum)
+        throw new TypeError(code);
+}
+function assertDate(value, code) {
+    if (!DATE_PATTERN.test(value) || Number.isNaN(Date.parse(`${value}T00:00:00Z`)))
+        throw new TypeError(code);
+    return value;
+}
+function timeMinutes(value, code) {
+    if (!TIME_PATTERN.test(value))
+        throw new TypeError(code);
+    const [hour, minute] = value.split(':').map(Number);
+    return hour * 60 + minute;
+}
+function encodeOpeningHours(value) {
+    const daysOfWeek = unique(value.daysOfWeek, 'place_opening_hours_invalid');
+    if (!daysOfWeek.length || daysOfWeek.some(day => !DAY_NAMES.has(day)))
+        throw new TypeError('place_opening_hours_invalid');
+    if (timeMinutes(value.opens, 'place_opening_hours_invalid') >= timeMinutes(value.closes, 'place_opening_hours_invalid'))
+        throw new TypeError('place_opening_hours_invalid');
+    const validFrom = value.validFrom ? assertDate(value.validFrom, 'place_opening_hours_invalid') : undefined;
+    const validThrough = value.validThrough ? assertDate(value.validThrough, 'place_opening_hours_invalid') : undefined;
+    if (Boolean(validFrom) !== Boolean(validThrough) || (validFrom && validThrough && validFrom > validThrough))
+        throw new TypeError('place_opening_hours_invalid');
+    return JSON.stringify({ daysOfWeek, opens: value.opens, closes: value.closes, ...(validFrom ? { validFrom, validThrough } : {}) });
+}
+function encodeSpecialOpeningHours(value) {
+    const validFrom = assertDate(value.validFrom, 'place_special_opening_hours_invalid');
+    const validThrough = assertDate(value.validThrough, 'place_special_opening_hours_invalid');
+    if (validFrom > validThrough)
+        throw new TypeError('place_special_opening_hours_invalid');
+    if (value.closed)
+        return JSON.stringify({ validFrom, validThrough, closed: true });
+    if (!value.opens || !value.closes || timeMinutes(value.opens, 'place_special_opening_hours_invalid') >= timeMinutes(value.closes, 'place_special_opening_hours_invalid'))
+        throw new TypeError('place_special_opening_hours_invalid');
+    return JSON.stringify({ validFrom, validThrough, opens: value.opens, closes: value.closes });
+}
+/** Builds the claims-only public Place authored by an organization. */
+export function buildPlaceDirectoryResource(input) {
+    const id = required(input.id, 'place_id_required');
+    if (!RESOURCE_ID_PATTERN.test(id))
+        throw new TypeError('place_id_invalid');
+    assertCoordinate(input.position.latitude, -90, 90, 'place_latitude_invalid');
+    assertCoordinate(input.position.longitude, -180, 180, 'place_longitude_invalid');
+    if (input.position.elevation !== undefined && !Number.isFinite(input.position.elevation))
+        throw new TypeError('place_elevation_invalid');
+    let photoUrl;
+    if (input.photoUrl) {
+        try {
+            const parsed = new URL(input.photoUrl);
+            if (parsed.protocol !== 'https:')
+                throw new Error();
+            photoUrl = parsed.toString();
+        }
+        catch {
+            throw new TypeError('place_photo_url_invalid');
+        }
+    }
+    const accessibilityFeatures = unique(input.accessibilityFeatures, 'place_amenity_feature_invalid');
+    const openingHours = Object.freeze((input.openingHours ?? []).map(encodeOpeningHours));
+    const specialOpeningHours = Object.freeze((input.specialOpeningHours ?? []).map(encodeSpecialOpeningHours));
+    const claims = {
+        [ClaimsPlaceSchemaorg.identifier]: id,
+        [ClaimsPlaceSchemaorg.ownerIdentifier]: required(input.organizationIdentifier, 'place_organization_required'),
+        [ClaimsPlaceSchemaorg.name]: required(input.name, 'place_name_required'),
+        [ClaimsPlaceSchemaorg.addressCountry]: required(input.address.addressCountry, 'place_country_required').toUpperCase(),
+        [ClaimsPlaceSchemaorg.postalCode]: required(input.address.postalCode, 'place_postal_code_required'),
+        [ClaimsPlaceSchemaorg.latitude]: input.position.latitude,
+        [ClaimsPlaceSchemaorg.longitude]: input.position.longitude,
+        [ClaimsPlaceSchemaorg.publicAccess]: input.publicAccess ?? true,
+        [ClaimsPlaceSchemaorg.userSelected]: input.userSelected ?? false,
+    };
+    const textValues = [
+        [ClaimsPlaceSchemaorg.additionalType, input.additionalType], [ClaimsPlaceSchemaorg.description, input.description],
+        [ClaimsPlaceSchemaorg.addressRegion, input.address.addressRegion], [ClaimsPlaceSchemaorg.addressLocality, input.address.addressLocality],
+        [ClaimsPlaceSchemaorg.extendedAddress, input.address.extendedAddress], [ClaimsPlaceSchemaorg.streetAddress, input.address.streetAddress],
+    ];
+    for (const [name, raw] of textValues) {
+        const value = optional(raw);
+        if (value)
+            claims[name] = value;
+    }
+    if (input.position.elevation !== undefined)
+        claims[ClaimsPlaceSchemaorg.elevation] = input.position.elevation;
+    if (photoUrl)
+        claims[ClaimsPlaceSchemaorg.photoContentUrl] = photoUrl;
+    if (accessibilityFeatures.length)
+        claims[ClaimsPlaceSchemaorg.amenityFeature] = accessibilityFeatures;
+    if (openingHours.length)
+        claims[ClaimsPlaceSchemaorg.openingHoursSpecification] = openingHours;
+    if (specialOpeningHours.length)
+        claims[ClaimsPlaceSchemaorg.specialOpeningHoursSpecification] = specialOpeningHours;
+    return Object.freeze({ resourceType: 'Place', id, meta: Object.freeze({ claims: Object.freeze(claims) }) });
+}
+/** Builds a claims-only Schema.org Service joined to its provider and public Places. */
+export function buildServiceDirectoryResource(input) {
+    const id = required(input.id, 'service_id_required');
+    if (!RESOURCE_ID_PATTERN.test(id))
+        throw new TypeError('service_id_invalid');
+    const placeIdentifiers = unique(input.placeIdentifiers, 'service_place_required');
+    const serviceTypes = unique(input.serviceTypes, 'service_type_required');
+    if (!placeIdentifiers.length)
+        throw new TypeError('service_place_required');
+    if (!serviceTypes.length)
+        throw new TypeError('service_type_required');
+    const categories = unique(input.categories, 'service_category_invalid');
+    const areaServed = unique(input.areaServed, 'service_area_invalid');
+    const claims = {
+        [ClaimsDirectoryServiceSchemaorg.identifier]: id,
+        [ClaimsDirectoryServiceSchemaorg.providerIdentifier]: required(input.organizationIdentifier, 'service_organization_required'),
+        [ClaimsDirectoryServiceSchemaorg.placeIdentifier]: placeIdentifiers,
+        [ClaimsDirectoryServiceSchemaorg.name]: required(input.name, 'service_name_required'),
+        [ClaimsDirectoryServiceSchemaorg.serviceType]: serviceTypes,
+        [ClaimsDirectoryServiceSchemaorg.userSelected]: input.userSelected ?? false,
+    };
+    const description = optional(input.description);
+    if (description)
+        claims[ClaimsDirectoryServiceSchemaorg.description] = description;
+    if (categories.length)
+        claims[ClaimsDirectoryServiceSchemaorg.category] = categories;
+    if (areaServed.length)
+        claims[ClaimsDirectoryServiceSchemaorg.areaServed] = areaServed;
+    return Object.freeze({ resourceType: 'Service', id, meta: Object.freeze({ claims: Object.freeze(claims) }) });
+}
+/** Rejects native fields and converts a Place or Service into deterministic array-valued claims. */
+export function normalizeDirectoryFlatClaimsResource(input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        throw new TypeError('directory_flat_resource_invalid');
+    const value = input;
+    if ((value.resourceType !== 'Place' && value.resourceType !== 'Service') || Object.keys(value).some(key => !['resourceType', 'id', 'meta'].includes(key)))
+        throw new TypeError('directory_flat_resource_invalid');
+    const resourceType = value.resourceType;
+    const id = required(value.id, 'directory_flat_resource_invalid');
+    if (!RESOURCE_ID_PATTERN.test(id))
+        throw new TypeError('directory_flat_resource_invalid');
+    const rawClaims = value.meta?.claims;
+    if (!rawClaims || typeof rawClaims !== 'object' || Array.isArray(rawClaims))
+        throw new TypeError('directory_flat_resource_invalid');
+    const allowed = new Set(DirectoryFlatClaimCatalog[resourceType]);
+    const claims = {};
+    for (const [name, raw] of Object.entries(rawClaims)) {
+        if (!allowed.has(name))
+            throw new TypeError('directory_flat_claim_invalid');
+        const values = (Array.isArray(raw) ? raw : [raw]).map(item => String(item).trim());
+        if (!values.length || values.some(item => !item))
+            throw new TypeError('directory_flat_claim_invalid');
+        claims[name] = Object.freeze([...new Set(values)]);
+    }
+    return Object.freeze({ resourceType, id, meta: Object.freeze({ claims: Object.freeze(claims) }) });
+}
+function values(resource, name) {
+    const raw = resource.meta.claims[name];
+    return (Array.isArray(raw) ? raw : raw === undefined ? [] : [raw]).map(String);
+}
+function first(resource, name) {
+    return values(resource, name)[0];
+}
+function parseJson(value, code) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        throw new TypeError(code);
+    }
+}
+/** Explicitly projects one neutral Place to native FHIR R5 Location for export or interop. */
+export function projectPlaceToFhirR5Location(place) {
+    if (place.resourceType !== 'Place')
+        throw new TypeError('place_resource_required');
+    const latitude = Number(first(place, ClaimsPlaceSchemaorg.latitude));
+    const longitude = Number(first(place, ClaimsPlaceSchemaorg.longitude));
+    const postalCode = required(first(place, ClaimsPlaceSchemaorg.postalCode), 'place_postal_code_required');
+    const owner = required(first(place, ClaimsPlaceSchemaorg.ownerIdentifier), 'place_organization_required');
+    const opening = values(place, ClaimsPlaceSchemaorg.openingHoursSpecification).map(value => parseJson(value, 'place_opening_hours_invalid'));
+    const special = values(place, ClaimsPlaceSchemaorg.specialOpeningHoursSpecification).map(value => parseJson(value, 'place_special_opening_hours_invalid'));
+    const address = {
+        country: first(place, ClaimsPlaceSchemaorg.addressCountry), state: first(place, ClaimsPlaceSchemaorg.addressRegion),
+        city: first(place, ClaimsPlaceSchemaorg.addressLocality), postalCode,
+        ...(first(place, ClaimsPlaceSchemaorg.streetAddress) ? { line: [first(place, ClaimsPlaceSchemaorg.streetAddress)] } : {}),
+    };
+    const availableTime = opening.map(period => ({
+        daysOfWeek: period.daysOfWeek.map(day => day.slice(0, 3).toLowerCase()),
+        availableStartTime: period.opens, availableEndTime: period.closes,
+    }));
+    const notAvailableTime = special.filter(period => period.closed).map(period => ({
+        description: 'Special closure', during: { start: period.validFrom, end: period.validThrough },
+    }));
+    return Object.freeze({
+        resourceType: 'Location', id: place.id, status: 'active', mode: 'instance',
+        name: first(place, ClaimsPlaceSchemaorg.name), description: first(place, ClaimsPlaceSchemaorg.description),
+        address, position: { latitude, longitude, ...(first(place, ClaimsPlaceSchemaorg.elevation) ? { altitude: Number(first(place, ClaimsPlaceSchemaorg.elevation)) } : {}) },
+        managingOrganization: { reference: owner },
+        characteristic: values(place, ClaimsPlaceSchemaorg.amenityFeature).map(code => ({ coding: [{ code }] })),
+        hoursOfOperation: [{ availableTime, notAvailableTime }],
+        meta: { claims: {
+                'Location.identifier': place.id, 'Location.status': 'active', 'Location.name': first(place, ClaimsPlaceSchemaorg.name),
+                'Location.address-postalcode': postalCode, 'Location.near': `${latitude}|${longitude}`, 'Location.organization': owner,
+                ...(values(place, ClaimsPlaceSchemaorg.amenityFeature).length ? { 'Location.characteristic': values(place, ClaimsPlaceSchemaorg.amenityFeature) } : {}),
+            } },
+    });
+}
+/** Explicitly projects a neutral Service and its Places to native FHIR R5 HealthcareService. */
+export function projectServiceToFhirR5HealthcareService(service, input) {
+    if (service.resourceType !== 'Service')
+        throw new TypeError('service_resource_required');
+    const placeIdentifiers = values(service, ClaimsDirectoryServiceSchemaorg.placeIdentifier);
+    const places = placeIdentifiers.map(identifier => {
+        const place = input.places.find(candidate => candidate.resourceType === 'Place' && candidate.id === identifier);
+        if (!place)
+            throw new TypeError('service_place_not_found');
+        return place;
+    });
+    const serviceTypes = values(service, ClaimsDirectoryServiceSchemaorg.serviceType);
+    const categories = values(service, ClaimsDirectoryServiceSchemaorg.category);
+    const organization = required(first(service, ClaimsDirectoryServiceSchemaorg.providerIdentifier), 'service_organization_required');
+    const photoUrl = places.map(place => first(place, ClaimsPlaceSchemaorg.photoContentUrl)).find(Boolean);
+    const concept = (code) => ({ coding: [{ code }] });
+    return Object.freeze({
+        resourceType: 'HealthcareService', id: service.id, active: true, providedBy: { reference: organization },
+        name: first(service, ClaimsDirectoryServiceSchemaorg.name), comment: first(service, ClaimsDirectoryServiceSchemaorg.description),
+        category: categories.map(concept), type: serviceTypes.map(concept),
+        location: places.map(place => ({ reference: `Location/${place.id}` })),
+        ...(photoUrl ? { photo: { url: photoUrl } } : {}),
+        meta: { claims: {
+                'HealthcareService.identifier': service.id, 'HealthcareService.organization': organization,
+                'HealthcareService.name': first(service, ClaimsDirectoryServiceSchemaorg.name),
+                'HealthcareService.location': places.map(place => `Location/${place.id}`),
+                'HealthcareService.service-type': serviceTypes,
+                ...(categories.length ? { 'HealthcareService.service-category': categories } : {}),
+            } },
+    });
+}
+function normalizedPostal(value) { return value.replace(/[^A-Za-z0-9]/g, '').toUpperCase(); }
+function distanceKm(left, right) {
+    const radians = (value) => value * Math.PI / 180;
+    const lat = radians(right.latitude - left.latitude);
+    const lon = radians(right.longitude - left.longitude);
+    const a = Math.sin(lat / 2) ** 2 + Math.cos(radians(left.latitude)) * Math.cos(radians(right.latitude)) * Math.sin(lon / 2) ** 2;
+    return 6371 * 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+}
+/** Joins and filters a public clinic directory by postal code, service and optional geographic radius. */
+export function searchClinicMarketplace(input) {
+    const postalCode = input.postalCode ? normalizedPostal(required(input.postalCode, 'marketplace_postal_code_invalid')) : undefined;
+    const requestedTypes = new Set(unique(input.serviceTypes, 'marketplace_service_type_invalid'));
+    if (input.near) {
+        assertCoordinate(input.near.latitude, -90, 90, 'marketplace_latitude_invalid');
+        assertCoordinate(input.near.longitude, -180, 180, 'marketplace_longitude_invalid');
+        if (!Number.isFinite(input.near.radiusKm) || input.near.radiusKm <= 0)
+            throw new TypeError('marketplace_radius_invalid');
+    }
+    const results = [];
+    for (const place of input.places) {
+        if (place.resourceType !== 'Place')
+            throw new TypeError('place_resource_required');
+        if (postalCode && normalizedPostal(String(first(place, ClaimsPlaceSchemaorg.postalCode) || '')) !== postalCode)
+            continue;
+        const services = input.services.filter(service => service.resourceType === 'Service'
+            && values(service, ClaimsDirectoryServiceSchemaorg.placeIdentifier).includes(place.id)
+            && (!requestedTypes.size || values(service, ClaimsDirectoryServiceSchemaorg.serviceType).some(type => requestedTypes.has(type))));
+        if (!services.length)
+            continue;
+        const distance = input.near ? distanceKm(input.near, {
+            latitude: Number(first(place, ClaimsPlaceSchemaorg.latitude)), longitude: Number(first(place, ClaimsPlaceSchemaorg.longitude)),
+        }) : undefined;
+        if (input.near && (distance === undefined || distance > input.near.radiusKm))
+            continue;
+        results.push(Object.freeze({ place, services: Object.freeze(services), ...(distance === undefined ? {} : { distanceKm: distance }) }));
+    }
+    return Object.freeze(results.sort((left, right) => (left.distanceKm ?? 0) - (right.distanceKm ?? 0) || left.place.id.localeCompare(right.place.id)));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vet-data-utils-ts",
-  "version": "0.5.18",
+  "version": "0.5.21",
   "description": "Browser-safe governed VetChain data contracts",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",
@@ -68,6 +68,10 @@
       "types": "./dist/payment.d.ts",
       "default": "./dist/payment.js"
     },
+    "./place-service-directory": {
+      "types": "./dist/place-service-directory.d.ts",
+      "default": "./dist/place-service-directory.js"
+    },
     "./research-study": {
       "types": "./dist/research-study.d.ts",
       "default": "./dist/research-study.js"