vet-data-utils-ts 0.3.0 → 0.4.1

package/README.md

@@ -8,7 +8,29 @@ Current surfaces cover the canonical animal-card DID, veterinary summary
 sections, animal-only emergency data, pseudonymous DigitalTwin search input and
 veterinary assistant intents.
 
+The financial surface defines provider-neutral flat claims for FHIR R5
+`Account`, `Invoice`, `PaymentNotice` and `PaymentReconciliation`. `Account`
+tracks charges and balances; the responsible party is represented through
+`Invoice.recipient`, `Account.guarantor-party` and, for an actual payment,
+`PaymentReconciliation.payment-issuer`. Payment processors and wallets remain
+adapters outside this package. `Communication` transports or references these
+resources but does not duplicate their financial claims.
+
+`vet-data-utils-ts/iso-jurisdictions` exports the assigned ISO 3166-1 alpha-2
+country catalogue and every ISO 3166-2 subdivision level, including type and
+parent relationships. Consumers persist codes such as `CA`, `CA-BC`, `ES-MD`
+or its child province `ES-M`; localized labels remain presentation concerns.
+Selecting a jurisdiction grants no authority. The generated catalogue comes
+from Debian `iso-codes` 4.20.1; run `npm run update:iso-jurisdictions` to
+refresh it deliberately.
+
 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.
+
+Digital-twin search input contains one section, one or more resource types
+allowed by that section, display text, `dateFrom` and optional `dateTo`.
+`VeterinaryDigitalTwinSectionSearchProfiles` owns the corresponding
+`code-display` and date claims so browser code never supplies claim names.
+Identifying fields and caller-authored `claim`/`dateClaim` values are rejected.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,13 @@
+# Third-party notices
+
+The generated ISO jurisdiction catalogue is derived from Debian `iso-codes`
+4.20.1-1:
+
+- Source: https://salsa.debian.org/iso-codes-team/iso-codes
+- Copyright: 2001-2008 Alastair McKinstry; 2004-2016 Christian Perrier;
+  2005-2026 Dr. Tobias Quathamer
+- License: GNU Lesser General Public License 2.1 or later
+- License text: https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html
+
+The generated catalogue may be replaced or updated independently by running
+`npm run update:iso-jurisdictions` against the version pinned in that script.

package/dist/digital-twin.d.ts

@@ -3,11 +3,24 @@ export declare const VeterinaryDigitalTwinFormats: Readonly<{
     readonly R4: "org.hl7.fhir.r4";
 }>;
 export type VeterinaryDigitalTwinFormat = typeof VeterinaryDigitalTwinFormats[keyof typeof VeterinaryDigitalTwinFormats];
+export type VeterinaryDigitalTwinResourceSearchProfile = Readonly<{
+    resourceType: string;
+    codeDisplayClaim: `${string}.code-display`;
+    dateClaim: `${string}.${string}`;
+}>;
+/**
+ * Searchable flat-claim projections for each veterinary section.
+ *
+ * Native FHIR resources are converted by GW into these governed claims. The
+ * browser selects resource families only; it never supplies claim names.
+ */
+export declare const VeterinaryDigitalTwinSectionSearchProfiles: Readonly<Record<string, readonly VeterinaryDigitalTwinResourceSearchProfile[]>>;
 export type VeterinaryDigitalTwinSearch = Readonly<{
     section: string;
-    resourceType: string;
-    claim: string;
-    value: string;
+    resourceTypes: readonly string[];
+    text: string;
+    dateFrom: string;
+    dateTo?: string;
 }>;
-/** Bounds one section-first pseudonymous search and rejects direct identifiers. */
+/** Bounds one section-first pseudonymous search and rejects direct identifiers and caller-authored claims. */
 export declare function parseVeterinaryDigitalTwinSearch(input: unknown): VeterinaryDigitalTwinSearch;

package/dist/digital-twin.js

@@ -1,24 +1,61 @@
-import { isVeterinarySummarySection } from './veterinary-sections.js';
+import { VeterinarySummarySections, 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. */
+const profile = (resourceType, dateClaim) => Object.freeze({ resourceType, codeDisplayClaim: `${resourceType}.code-display`, dateClaim });
+/**
+ * Searchable flat-claim projections for each veterinary section.
+ *
+ * Native FHIR resources are converted by GW into these governed claims. The
+ * browser selects resource families only; it never supplies claim names.
+ */
+export const VeterinaryDigitalTwinSectionSearchProfiles = Object.freeze({
+    [VeterinarySummarySections.Problems.value]: Object.freeze([profile('Condition', 'Condition.onset-datetime')]),
+    [VeterinarySummarySections.Allergies.value]: Object.freeze([profile('AllergyIntolerance', 'AllergyIntolerance.onset-datetime')]),
+    [VeterinarySummarySections.Medications.value]: Object.freeze([profile('MedicationStatement', 'MedicationStatement.effective')]),
+    [VeterinarySummarySections.Immunizations.value]: Object.freeze([profile('Immunization', 'Immunization.date')]),
+    [VeterinarySummarySections.Results.value]: Object.freeze([
+        profile('Observation', 'Observation.date'),
+        profile('DiagnosticReport', 'DiagnosticReport.date'),
+    ]),
+    [VeterinarySummarySections.Procedures.value]: Object.freeze([profile('Procedure', 'Procedure.date')]),
+    [VeterinarySummarySections.VitalSigns.value]: Object.freeze([profile('Observation', 'Observation.date')]),
+    [VeterinarySummarySections.EnvironmentAndLifestyle.value]: Object.freeze([profile('Observation', 'Observation.date')]),
+    [VeterinarySummarySections.FunctionalStatus.value]: Object.freeze([profile('Condition', 'Condition.onset-datetime')]),
+    [VeterinarySummarySections.PastIllness.value]: Object.freeze([profile('Condition', 'Condition.onset-datetime')]),
+    [VeterinarySummarySections.ReproductiveHistory.value]: Object.freeze([profile('Observation', 'Observation.date')]),
+});
+/** Bounds one section-first pseudonymous search and rejects direct identifiers and caller-authored claims. */
 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');
     }
+    if (String(value.claim || '').trim() || String(value.dateClaim || '').trim()) {
+        throw new TypeError('veterinary_digital_twin_claim_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))
+    const allowedProfiles = VeterinaryDigitalTwinSectionSearchProfiles[section] || [];
+    if (allowedProfiles.length === 0)
+        throw new TypeError('veterinary_digital_twin_section_not_searchable');
+    const rawResourceTypes = Array.isArray(value.resourceTypes) ? value.resourceTypes : [value.resourceType];
+    const resourceTypes = Array.from(new Set(rawResourceTypes.map(item => String(item || '').trim()).filter(Boolean)));
+    if (resourceTypes.length === 0 || resourceTypes.some(resourceType => !allowedProfiles.some(item => item.resourceType === 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 });
+    const text = String(value.text || value.value || '').trim();
+    if (!text || text.length > 256)
+        throw new TypeError('veterinary_digital_twin_text_invalid');
+    const dateFrom = parseIsoDate(value.dateFrom, 'date_from');
+    const dateTo = String(value.dateTo || '').trim() ? parseIsoDate(value.dateTo, 'date_to') : undefined;
+    if (dateTo && Date.parse(dateTo) < Date.parse(dateFrom))
+        throw new TypeError('veterinary_digital_twin_date_range_invalid');
+    return Object.freeze({ section, resourceTypes: Object.freeze(resourceTypes), text, dateFrom, ...(dateTo ? { dateTo } : {}) });
+}
+function parseIsoDate(value, field) {
+    const normalized = String(value || '').trim();
+    if (!normalized || Number.isNaN(Date.parse(normalized)))
+        throw new TypeError(`veterinary_digital_twin_${field}_invalid`);
+    return normalized;
 }

package/dist/financial.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Provider-neutral flat-claim names for veterinary financial resources.
+ *
+ * These names describe FHIR R5 Account, Invoice, PaymentNotice and
+ * PaymentReconciliation projections. They do not authorize payment, select a
+ * ledger channel or expose a payment-provider payload. Repeating FHIR elements
+ * remain repeated claim values; datatype serialization belongs to GW.
+ */
+export declare const VeterinaryFinancialResourceTypes: Readonly<{
+    readonly Account: "Account";
+    readonly Invoice: "Invoice";
+    readonly PaymentNotice: "PaymentNotice";
+    readonly PaymentReconciliation: "PaymentReconciliation";
+}>;
+export type VeterinaryFinancialResourceType = typeof VeterinaryFinancialResourceTypes[keyof typeof VeterinaryFinancialResourceTypes];
+/** Canonical claim allow-list used before a native FHIR resource is indexed. */
+export declare const VeterinaryFinancialClaimCatalog: Readonly<{
+    Account: readonly ["Account.identifier", "Account.status", "Account.billing-status", "Account.type", "Account.name", "Account.subject", "Account.service-period", "Account.coverage-coverage", "Account.coverage-priority", "Account.owner", "Account.description", "Account.guarantor-party", "Account.guarantor-on-hold", "Account.guarantor-period", "Account.diagnosis-sequence", "Account.diagnosis-condition", "Account.diagnosis-date", "Account.diagnosis-type", "Account.diagnosis-on-admission", "Account.diagnosis-package-code", "Account.procedure-sequence", "Account.procedure-code", "Account.procedure-date-of-service", "Account.procedure-type", "Account.procedure-package-code", "Account.procedure-device", "Account.related-account-account", "Account.related-account-relationship", "Account.currency", "Account.balance-aggregate", "Account.balance-term", "Account.balance-estimate", "Account.balance-amount", "Account.calculated-at"];
+    Invoice: readonly ["Invoice.identifier", "Invoice.status", "Invoice.cancelled-reason", "Invoice.type", "Invoice.subject", "Invoice.recipient", "Invoice.creation", "Invoice.period", "Invoice.participant-role", "Invoice.participant-actor", "Invoice.issuer", "Invoice.account", "Invoice.line-item-sequence", "Invoice.line-item-serviced", "Invoice.line-item-charge-item", "Invoice.line-item-price-component-type", "Invoice.line-item-price-component-code", "Invoice.line-item-price-component-factor", "Invoice.line-item-price-component-amount", "Invoice.total-price-component-type", "Invoice.total-price-component-code", "Invoice.total-price-component-factor", "Invoice.total-price-component-amount", "Invoice.total-net", "Invoice.total-gross", "Invoice.payment-terms", "Invoice.note"];
+    PaymentNotice: readonly ["PaymentNotice.identifier", "PaymentNotice.status", "PaymentNotice.request", "PaymentNotice.response", "PaymentNotice.created", "PaymentNotice.reporter", "PaymentNotice.payment", "PaymentNotice.payment-date", "PaymentNotice.payee", "PaymentNotice.recipient", "PaymentNotice.amount", "PaymentNotice.payment-status"];
+    PaymentReconciliation: readonly ["PaymentReconciliation.identifier", "PaymentReconciliation.type", "PaymentReconciliation.status", "PaymentReconciliation.kind", "PaymentReconciliation.period", "PaymentReconciliation.created", "PaymentReconciliation.enterer", "PaymentReconciliation.issuer-type", "PaymentReconciliation.payment-issuer", "PaymentReconciliation.request", "PaymentReconciliation.requestor", "PaymentReconciliation.outcome", "PaymentReconciliation.disposition", "PaymentReconciliation.date", "PaymentReconciliation.location", "PaymentReconciliation.method", "PaymentReconciliation.card-brand", "PaymentReconciliation.account-number", "PaymentReconciliation.expiration-date", "PaymentReconciliation.processor", "PaymentReconciliation.reference-number", "PaymentReconciliation.authorization", "PaymentReconciliation.tendered-amount", "PaymentReconciliation.returned-amount", "PaymentReconciliation.amount", "PaymentReconciliation.payment-identifier", "PaymentReconciliation.allocation-identifier", "PaymentReconciliation.allocation-predecessor", "PaymentReconciliation.allocation-target", "PaymentReconciliation.allocation-target-item", "PaymentReconciliation.allocation-encounter", "PaymentReconciliation.allocation-account", "PaymentReconciliation.allocation-type", "PaymentReconciliation.allocation-submitter", "PaymentReconciliation.allocation-response", "PaymentReconciliation.allocation-date", "PaymentReconciliation.allocation-responsible", "PaymentReconciliation.allocation-payee", "PaymentReconciliation.allocation-amount", "PaymentReconciliation.form-code", "PaymentReconciliation.process-note-type", "PaymentReconciliation.process-note-text"];
+}>;
+/** Returns the immutable allow-list for one supported financial resource. */
+export declare function getVeterinaryFinancialClaims(resourceType: unknown): readonly string[];
+/** Checks both the resource family and its claim prefix/allow-list. */
+export declare function isVeterinaryFinancialClaim(resourceType: unknown, claim: unknown): boolean;

package/dist/financial.js

@@ -0,0 +1,162 @@
+/**
+ * Provider-neutral flat-claim names for veterinary financial resources.
+ *
+ * These names describe FHIR R5 Account, Invoice, PaymentNotice and
+ * PaymentReconciliation projections. They do not authorize payment, select a
+ * ledger channel or expose a payment-provider payload. Repeating FHIR elements
+ * remain repeated claim values; datatype serialization belongs to GW.
+ */
+export const VeterinaryFinancialResourceTypes = Object.freeze({
+    Account: 'Account',
+    Invoice: 'Invoice',
+    PaymentNotice: 'PaymentNotice',
+    PaymentReconciliation: 'PaymentReconciliation',
+});
+const accountClaims = Object.freeze([
+    'Account.identifier',
+    'Account.status',
+    'Account.billing-status',
+    'Account.type',
+    'Account.name',
+    'Account.subject',
+    'Account.service-period',
+    'Account.coverage-coverage',
+    'Account.coverage-priority',
+    'Account.owner',
+    'Account.description',
+    'Account.guarantor-party',
+    'Account.guarantor-on-hold',
+    'Account.guarantor-period',
+    'Account.diagnosis-sequence',
+    'Account.diagnosis-condition',
+    'Account.diagnosis-date',
+    'Account.diagnosis-type',
+    'Account.diagnosis-on-admission',
+    'Account.diagnosis-package-code',
+    'Account.procedure-sequence',
+    'Account.procedure-code',
+    'Account.procedure-date-of-service',
+    'Account.procedure-type',
+    'Account.procedure-package-code',
+    'Account.procedure-device',
+    'Account.related-account-account',
+    'Account.related-account-relationship',
+    'Account.currency',
+    'Account.balance-aggregate',
+    'Account.balance-term',
+    'Account.balance-estimate',
+    'Account.balance-amount',
+    'Account.calculated-at',
+]);
+const invoiceClaims = Object.freeze([
+    'Invoice.identifier',
+    'Invoice.status',
+    'Invoice.cancelled-reason',
+    'Invoice.type',
+    'Invoice.subject',
+    'Invoice.recipient',
+    'Invoice.creation',
+    'Invoice.period',
+    'Invoice.participant-role',
+    'Invoice.participant-actor',
+    'Invoice.issuer',
+    'Invoice.account',
+    'Invoice.line-item-sequence',
+    'Invoice.line-item-serviced',
+    'Invoice.line-item-charge-item',
+    'Invoice.line-item-price-component-type',
+    'Invoice.line-item-price-component-code',
+    'Invoice.line-item-price-component-factor',
+    'Invoice.line-item-price-component-amount',
+    'Invoice.total-price-component-type',
+    'Invoice.total-price-component-code',
+    'Invoice.total-price-component-factor',
+    'Invoice.total-price-component-amount',
+    'Invoice.total-net',
+    'Invoice.total-gross',
+    'Invoice.payment-terms',
+    'Invoice.note',
+]);
+const paymentNoticeClaims = Object.freeze([
+    'PaymentNotice.identifier',
+    'PaymentNotice.status',
+    'PaymentNotice.request',
+    'PaymentNotice.response',
+    'PaymentNotice.created',
+    'PaymentNotice.reporter',
+    'PaymentNotice.payment',
+    'PaymentNotice.payment-date',
+    'PaymentNotice.payee',
+    'PaymentNotice.recipient',
+    'PaymentNotice.amount',
+    'PaymentNotice.payment-status',
+]);
+const paymentReconciliationClaims = Object.freeze([
+    'PaymentReconciliation.identifier',
+    'PaymentReconciliation.type',
+    'PaymentReconciliation.status',
+    'PaymentReconciliation.kind',
+    'PaymentReconciliation.period',
+    'PaymentReconciliation.created',
+    'PaymentReconciliation.enterer',
+    'PaymentReconciliation.issuer-type',
+    'PaymentReconciliation.payment-issuer',
+    'PaymentReconciliation.request',
+    'PaymentReconciliation.requestor',
+    'PaymentReconciliation.outcome',
+    'PaymentReconciliation.disposition',
+    'PaymentReconciliation.date',
+    'PaymentReconciliation.location',
+    'PaymentReconciliation.method',
+    'PaymentReconciliation.card-brand',
+    'PaymentReconciliation.account-number',
+    'PaymentReconciliation.expiration-date',
+    'PaymentReconciliation.processor',
+    'PaymentReconciliation.reference-number',
+    'PaymentReconciliation.authorization',
+    'PaymentReconciliation.tendered-amount',
+    'PaymentReconciliation.returned-amount',
+    'PaymentReconciliation.amount',
+    'PaymentReconciliation.payment-identifier',
+    'PaymentReconciliation.allocation-identifier',
+    'PaymentReconciliation.allocation-predecessor',
+    'PaymentReconciliation.allocation-target',
+    'PaymentReconciliation.allocation-target-item',
+    'PaymentReconciliation.allocation-encounter',
+    'PaymentReconciliation.allocation-account',
+    'PaymentReconciliation.allocation-type',
+    'PaymentReconciliation.allocation-submitter',
+    'PaymentReconciliation.allocation-response',
+    'PaymentReconciliation.allocation-date',
+    'PaymentReconciliation.allocation-responsible',
+    'PaymentReconciliation.allocation-payee',
+    'PaymentReconciliation.allocation-amount',
+    'PaymentReconciliation.form-code',
+    'PaymentReconciliation.process-note-type',
+    'PaymentReconciliation.process-note-text',
+]);
+/** Canonical claim allow-list used before a native FHIR resource is indexed. */
+export const VeterinaryFinancialClaimCatalog = Object.freeze({
+    Account: accountClaims,
+    Invoice: invoiceClaims,
+    PaymentNotice: paymentNoticeClaims,
+    PaymentReconciliation: paymentReconciliationClaims,
+});
+/** Returns the immutable allow-list for one supported financial resource. */
+export function getVeterinaryFinancialClaims(resourceType) {
+    const normalized = String(resourceType || '').trim();
+    if (!isVeterinaryFinancialResourceType(normalized)) {
+        throw new TypeError('veterinary_financial_resource_type_invalid');
+    }
+    return VeterinaryFinancialClaimCatalog[normalized];
+}
+/** Checks both the resource family and its claim prefix/allow-list. */
+export function isVeterinaryFinancialClaim(resourceType, claim) {
+    const normalizedResourceType = String(resourceType || '').trim();
+    if (!isVeterinaryFinancialResourceType(normalizedResourceType))
+        return false;
+    return VeterinaryFinancialClaimCatalog[normalizedResourceType].includes(String(claim || '').trim());
+}
+function isVeterinaryFinancialResourceType(value) {
+    return Object.values(VeterinaryFinancialResourceTypes).includes(value);
+}

package/dist/index.d.ts

@@ -2,4 +2,6 @@ export * from './animal-card.js';
 export * from './assistant.js';
 export * from './digital-twin.js';
 export * from './emergency.js';
+export * from './financial.js';
+export * from './iso-jurisdictions.js';
 export * from './veterinary-sections.js';

package/dist/index.js

@@ -2,4 +2,6 @@ export * from './animal-card.js';
 export * from './assistant.js';
 export * from './digital-twin.js';
 export * from './emergency.js';
+export * from './financial.js';
+export * from './iso-jurisdictions.js';
 export * from './veterinary-sections.js';

package/dist/iso-jurisdictions-data.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Generated from Debian iso-codes 4.20.1-1. Do not edit manually.
+ * Source: https://sources.debian.org/data/main/i/iso-codes/4.20.1-1/data
+ */
+export declare const Iso3166CountryData: readonly {
+    code: string;
+    name: string;
+}[];
+export declare const Iso3166SubdivisionData: readonly {
+    code: string;
+    countryCode: string;
+    name: string;
+    parentCode?: string;
+    type: string;
+}[];