vet-sdk-core-ts 0.4.2 → 0.4.4

package/README.md

@@ -6,6 +6,31 @@ UHC SDK packages and must not import them.
 The SDK consumes governed browser-safe values from `vet-data-utils-ts` and
 owns gateway request construction. GW VET remains the policy authority.
 
+## Professional break-glass authorization
+
+Node BFFs call `buildVeterinaryBreakGlassSmartAuthorization` with only the
+animal DID, governed sections, incident id and clinical justification. The
+result can be passed directly to
+`ServerProfileSessionManager.openProfessional().requestSmartToken(...)`.
+It contains the veterinary purpose, scope, 15-minute cap and audited emergency
+claims, but never a `client_id`, SMART audience, private-key assertion or VP.
+Those OpenID proofs are reconstructed and signed by the registered server
+wallet in `gdc-sdk-node-ts`.
+
+```ts
+const authorization = buildVeterinaryBreakGlassSmartAuthorization({
+  subjectDid,
+  requestedSections,
+  incidentId,
+  justification,
+})
+
+await openedProfessional.requestSmartToken(authorization)
+```
+
+`buildVeterinaryBreakGlassSmartRequest` remains only as a low-level
+compatibility envelope for integrations that already own the OpenID fields.
+
 The numeric animal identity and external evidence contract is documented in
 [`docs/ANIMAL_IDENTITY.md`](docs/ANIMAL_IDENTITY.md).
 
@@ -35,3 +60,24 @@ import {
 VetChainDomesticAnimalSpecies.DomesticFerret.ncbiTaxonomyId; // "9669"
 findVetChainSpeciesByTaxonomyId("9685")?.key; // "Cat"
 ```
+
+## Digital-twin search
+
+`buildVeterinaryDigitalTwinSearchRequest` accepts only one governed section,
+selected resource families, display text and dates. It returns both the FHIR
+`Parameters` body and the `filters` map for `DigitalTwinSdk.search`; callers do
+not author `Composition.section` or resource claim names.
+
+```ts
+const request = buildVeterinaryDigitalTwinSearchRequest({
+  thid: crypto.randomUUID(),
+  search: { section, resourceTypes, text, dateFrom, ...(dateTo ? { dateTo } : {}) },
+})
+
+await digitalTwins.search(routeContext, {
+  thid: request.payload.thid,
+  format: request.format,
+  resourceType: request.resourceType,
+  filters: request.filters,
+})
+```

package/dist/gateway-contract.d.ts

@@ -26,15 +26,53 @@ export type VeterinaryBreakGlassSmartRequest = Readonly<{
         }>;
     }>;
 }>;
+/**
+ * Business-only SMART authorization consumed by a high-level professional
+ * runtime. Wallet keys, client identifiers, audiences, JWT assertions and VPs
+ * deliberately do not belong to this browser-safe contract.
+ */
+export type VeterinaryBreakGlassSmartAuthorization = Readonly<{
+    subjectDid: string;
+    purpose: 'EMERGENCY';
+    scopes: readonly [string];
+    acrValues: 'urn:antifraud:acr:openid4vp:employee';
+    requestBodyClaims: Readonly<{
+        expires_in: number;
+        break_glass: Readonly<{
+            incidentId: string;
+            subjectKind: 'animal';
+            reasonCode: 'animal-emergency';
+            justification: string;
+        }>;
+    }>;
+}>;
 export type VeterinaryDigitalTwinSearchRequest = Readonly<{
     format: VeterinaryDigitalTwinFormat;
     resourceType: 'Composition';
+    filters: Readonly<Record<string, string | readonly string[]>>;
     payload: Readonly<{
         thid: string;
         body: Readonly<Record<string, unknown>>;
     }>;
 }>;
 export declare function buildVetGatewayRoutePrefix(context: VetGatewayRouteContext): string;
+/**
+ * Converts the portal's governed emergency form into the business fields for
+ * `ServerProfileSessionManager.openProfessional().requestSmartToken(...)`.
+ * The Node SDK derives and signs every OpenID/VP field from the registered
+ * wallet; the portal never supplies or persists that plumbing.
+ */
+export declare function buildVeterinaryBreakGlassSmartAuthorization(input: Readonly<{
+    subjectDid: string;
+    requestedSections: readonly string[];
+    incidentId: string;
+    justification: string;
+}>): VeterinaryBreakGlassSmartAuthorization;
+/**
+ * Low-level compatibility envelope for callers that already own OpenID
+ * plumbing. New Node BFFs should use
+ * `buildVeterinaryBreakGlassSmartAuthorization` with `openProfessional`.
+ */
 export declare function buildVeterinaryBreakGlassSmartRequest(input: Readonly<{
     thid: string;
     actorDid: string;
@@ -47,6 +85,11 @@ export declare function buildVeterinaryBreakGlassSmartRequest(input: Readonly<{
     vpToken: string;
     audience: string;
 }>): VeterinaryBreakGlassSmartRequest;
+/**
+ * Converts browser-safe search values into both FHIR Parameters and the exact
+ * filter map accepted by the Node DigitalTwin SDK. Callers never choose flat
+ * claim names.
+ */
 export declare function buildVeterinaryDigitalTwinSearchRequest(input: Readonly<{
     thid: string;
     format?: VeterinaryDigitalTwinFormat;

package/dist/gateway-contract.js

@@ -1,4 +1,4 @@
-import { VeterinaryBreakGlassMaxLifetimeSeconds, VeterinaryDigitalTwinFormats, parseVetChainAnimalCardDid, parseVeterinaryBreakGlassRequestData, parseVeterinaryDigitalTwinSearch, } from 'vet-data-utils-ts';
+import { VeterinaryBreakGlassMaxLifetimeSeconds, VeterinaryDigitalTwinFormats, VeterinaryDigitalTwinSectionSearchProfiles, parseVetChainAnimalCardDid, parseVeterinaryBreakGlassRequestData, parseVeterinaryDigitalTwinSearch, } from 'vet-data-utils-ts';
 export function buildVetGatewayRoutePrefix(context) {
     const tenantId = bounded(context.tenantId, 'tenantId');
     const jurisdiction = bounded(context.jurisdiction, 'jurisdiction').toUpperCase();
@@ -6,11 +6,41 @@ export function buildVetGatewayRoutePrefix(context) {
         throw new TypeError('vet_gateway_jurisdiction_invalid');
     return `/${tenantId}/cds-${jurisdiction}/v1/${context.sector}`;
 }
-export function buildVeterinaryBreakGlassSmartRequest(input) {
+/**
+ * Converts the portal's governed emergency form into the business fields for
+ * `ServerProfileSessionManager.openProfessional().requestSmartToken(...)`.
+ * The Node SDK derives and signs every OpenID/VP field from the registered
+ * wallet; the portal never supplies or persists that plumbing.
+ */
+export function buildVeterinaryBreakGlassSmartAuthorization(input) {
     const emergency = parseVeterinaryBreakGlassRequestData(input);
-    const actorDid = did(input.actorDid, 'vet_break_glass_actor_invalid');
     const section = emergency.requestedSections.join(',');
     const scope = `organization/Composition.rs?subject=${encodeURIComponent(emergency.subjectDid)}&section=${encodeURIComponent(section)}`;
+    return Object.freeze({
+        subjectDid: emergency.subjectDid,
+        purpose: 'EMERGENCY',
+        scopes: Object.freeze([scope]),
+        acrValues: 'urn:antifraud:acr:openid4vp:employee',
+        requestBodyClaims: Object.freeze({
+            expires_in: VeterinaryBreakGlassMaxLifetimeSeconds,
+            break_glass: Object.freeze({
+                incidentId: emergency.incidentId,
+                subjectKind: emergency.subjectKind,
+                reasonCode: emergency.reasonCode,
+                justification: emergency.justification,
+            }),
+        }),
+    });
+}
+/**
+ * Low-level compatibility envelope for callers that already own OpenID
+ * plumbing. New Node BFFs should use
+ * `buildVeterinaryBreakGlassSmartAuthorization` with `openProfessional`.
+ */
+export function buildVeterinaryBreakGlassSmartRequest(input) {
+    const emergency = parseVeterinaryBreakGlassRequestData(input);
+    const actorDid = did(input.actorDid, 'vet_break_glass_actor_invalid');
+    const authorization = buildVeterinaryBreakGlassSmartAuthorization(emergency);
     return Object.freeze({
         thid: bounded(input.thid, 'thid'),
         iss: actorDid,
@@ -21,31 +51,50 @@ export function buildVeterinaryBreakGlassSmartRequest(input) {
             client_assertion: bounded(input.clientAssertion, 'clientAssertion'),
             client_assertion_type: 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
             vp_token: bounded(input.vpToken, 'vpToken'),
-            acr_values: 'urn:antifraud:acr:openid4vp:employee',
-            purpose: 'EMERGENCY',
-            scope,
-            expires_in: VeterinaryBreakGlassMaxLifetimeSeconds,
-            break_glass: {
-                incidentId: emergency.incidentId,
-                subjectKind: emergency.subjectKind,
-                reasonCode: emergency.reasonCode,
-                justification: emergency.justification,
-            },
+            acr_values: authorization.acrValues,
+            purpose: authorization.purpose,
+            scope: authorization.scopes[0],
+            expires_in: authorization.requestBodyClaims.expires_in,
+            break_glass: authorization.requestBodyClaims.break_glass,
         },
     });
 }
+/**
+ * Converts browser-safe search values into both FHIR Parameters and the exact
+ * filter map accepted by the Node DigitalTwin SDK. Callers never choose flat
+ * claim names.
+ */
 export function buildVeterinaryDigitalTwinSearchRequest(input) {
     const search = parseVeterinaryDigitalTwinSearch(input.search);
     const format = input.format || VeterinaryDigitalTwinFormats.R4;
     const parameter = [
-        { name: 'section', valueString: search.section },
-        { name: search.claim, valueString: search.value },
+        { name: 'Composition.section', valueString: search.section },
     ];
+    const profiles = VeterinaryDigitalTwinSectionSearchProfiles[search.section] || [];
+    for (const resourceType of search.resourceTypes) {
+        const selectedProfile = profiles.find(profile => profile.resourceType === resourceType);
+        if (!selectedProfile)
+            throw new TypeError('veterinary_digital_twin_resource_invalid');
+        parameter.push({ name: selectedProfile.codeDisplayClaim, valueString: search.text }, { name: selectedProfile.dateClaim, valueString: `ge${search.dateFrom}` });
+        if (search.dateTo)
+            parameter.push({ name: selectedProfile.dateClaim, valueString: `le${search.dateTo}` });
+    }
+    const filters = {};
+    for (const item of parameter) {
+        const existing = filters[item.name];
+        if (!existing)
+            filters[item.name] = item.valueString;
+        else if (Array.isArray(existing))
+            existing.push(item.valueString);
+        else
+            filters[item.name] = [existing, item.valueString];
+    }
     return Object.freeze({
         format,
-        // GW stores the pseudonymous twin as a Composition. `search.resourceType`
-        // names the nested clinical resource whose claim is being filtered; it is
-        // never the asynchronous route resource type.
+        filters: Object.freeze(filters),
+        // GW stores the pseudonymous twin as a Composition. The selected nested
+        // resource families become repeated Parameters entries; they never change
+        // the asynchronous route resource type.
         resourceType: 'Composition',
         payload: {
             thid: bounded(input.thid, 'thid'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vet-sdk-core-ts",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "Browser-safe VetChain core contracts and governed animal species identifiers",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",
@@ -54,6 +54,6 @@
   },
   "dependencies": {
     "@noble/hashes": "^2.2.0",
-    "vet-data-utils-ts": "0.3.0"
+    "vet-data-utils-ts": "0.3.1"
   }
 }