vet-sdk-core-ts 0.4.11 → 0.4.12

package/README.md

@@ -21,7 +21,17 @@ read, update and search for ResearchSubjects filtered by the exact study. It
 never requests deletion of the twin; deletion of selected clinical facts must
 target those concrete resources under an active controller-approved Consent.
 The builder fails closed unless the professional has completed DCR and the
-later controller-approved Consent is `active`.
+later controller-approved Consent is `active`. It emits the canonical purpose
+`HRESCH` and the unescaped scope
+`organization/ResearchSubject.crus?study=ResearchStudy/<id>` so it can be
+passed to the protected professional runtime; the DCR-bound runtime supplies
+the professional actor as `sub`.
+
+`buildVeterinaryResearchStudyActiveConsentBatch` builds the controller's
+separate JSON:API `Consent/_batch`. Every POST is fixed to `active`, `permit`,
+`HRESCH`, one `PractitionerRole`, its ISCO-08 role, and that same exact
+ResearchStudy scope. The API does not accept caller-authored actions, so it
+cannot be broadened to delete.
 
 `buildVeterinaryResearchStudyPartyInvitations` creates exactly one R5
 `Communication` per associated `PractitionerRole`. Each Communication carries

package/dist/research-study.d.ts

@@ -1,14 +1,17 @@
 import { type ResearchStudyAssociatedParty } from 'vet-data-utils-ts/research-study';
+import { HealthcareConsentPurposes } from 'gdc-common-utils-ts/constants/healthcare';
+import { ResourceTypesFhirR5 } from 'gdc-common-utils-ts/constants/fhir-resource-types';
+import { ClaimConsent, ConsentStatuses } from 'gdc-common-utils-ts/models/consent-rule';
 export declare const VeterinaryResearchStudyPermissionActions: readonly ["create", "read", "update", "search"];
 export type VeterinaryResearchStudyPermissionAction = typeof VeterinaryResearchStudyPermissionActions[number];
 export declare const VeterinaryResearchStudyInvitationClaimNames: Readonly<{
     readonly Context: "@context";
-    readonly Status: "Consent.status";
-    readonly Decision: "Consent.decision";
-    readonly ActorIdentifier: "Consent.actor-identifier";
-    readonly Purpose: "Consent.purpose";
-    readonly Action: "Consent.action";
-    readonly ResourceType: "Consent.resource-type";
+    readonly Status: ClaimConsent.status;
+    readonly Decision: ClaimConsent.decision;
+    readonly ActorIdentifier: ClaimConsent.actorIdentifier;
+    readonly Purpose: ClaimConsent.purpose;
+    readonly Action: ClaimConsent.action;
+    readonly ResourceType: ClaimConsent.resourceType;
 }>;
 type FhirReference = Readonly<{
     reference: string;
@@ -98,10 +101,39 @@ export type VeterinaryResearchStudyBatch = Readonly<{
     data: readonly VeterinaryResearchStudyBatchEntry[];
 }>;
 export type VeterinaryResearchStudySmartAuthorization = Readonly<{
-    purpose: 'RESEARCH';
+    purpose: typeof HealthcareConsentPurposes.Research;
     researchStudyReference: string;
     scopes: readonly [string];
 }>;
+export type VeterinaryResearchStudyActiveConsentInput = Readonly<{
+    consentId: string;
+    researchStudyId: string;
+    practitionerRoleId: string;
+    actorRole: `ISCO-08|${string}`;
+    date: string;
+    status?: typeof ConsentStatuses.Active;
+}>;
+export type VeterinaryResearchStudyActiveConsent = Readonly<{
+    resourceType: typeof ResourceTypesFhirR5.Consent;
+    id: string;
+    status: typeof ConsentStatuses.Active;
+    meta: Readonly<{
+        claims: Readonly<Record<string, string>>;
+    }>;
+}>;
+export type VeterinaryResearchStudyActiveConsentEntry = Readonly<{
+    type: 'Consent-v5.0.0';
+    resource: VeterinaryResearchStudyActiveConsent;
+    request: Readonly<{
+        method: 'POST';
+        url: typeof ResourceTypesFhirR5.Consent;
+    }>;
+}>;
+export type VeterinaryResearchStudyActiveConsentBatch = Readonly<{
+    data: readonly VeterinaryResearchStudyActiveConsentEntry[];
+}>;
+/** Builds the exact GW study-pinned ResearchSubject `crus` capability. */
+export declare function buildVeterinaryResearchStudyAccessScope(researchStudyId: string): string;
 /**
  * Requests the current study-scoped ResearchSubject operations. Deleting
  * selected clinical facts is a later operation on those concrete resources;
@@ -112,6 +144,24 @@ export declare function buildVeterinaryResearchStudySmartAuthorization(input: Re
     dcrCompleted: boolean;
     consentStatus: 'draft' | 'active' | 'inactive' | 'not-done' | 'entered-in-error' | 'unknown';
 }>): VeterinaryResearchStudySmartAuthorization;
+/**
+ * Builds controller decisions for the VET ResearchStudy Consent `_batch`.
+ * Every entry is an explicit active/permit decision for one DCR-bound
+ * PractitionerRole. Invitation drafts, descriptive Group membership and
+ * `ResearchStudy.associatedParty` never authorize. The only action is the
+ * exact study-scoped ResearchSubject create/read/update/search capability;
+ * delete is deliberately absent.
+ *
+ * `subjectDid` is deliberately absent from the matching SMART authorization:
+ * the high-level professional runtime supplies the DCR-bound actor as `sub`,
+ * while GW derives the ResearchStudy authorization subject from this scope.
+ *
+ * @see https://hl7.org/fhir/R5/consent.html
+ * @see https://hl7.org/fhir/R5/researchstudy.html
+ */
+export declare function buildVeterinaryResearchStudyActiveConsentBatch(inputs: readonly VeterinaryResearchStudyActiveConsentInput[]): VeterinaryResearchStudyActiveConsentBatch;
+/** Builds one POST Consent entry accepted by the VET ResearchStudy manager. */
+export declare function buildVeterinaryResearchStudyActiveConsentEntry(input: VeterinaryResearchStudyActiveConsentInput): VeterinaryResearchStudyActiveConsentEntry;
 export declare function buildVeterinaryResearchStudyBatch(entries: readonly VeterinaryResearchStudyBatchEntry[]): VeterinaryResearchStudyBatch;
 export declare function buildVeterinaryResearchStudyCreateEntry(input: Readonly<{
     study: VeterinaryResearchStudyCreateResource;

package/dist/research-study.js

@@ -1,5 +1,9 @@
 import { normalizeResearchStudyAssociatedParties, projectResearchStudyAssociatedPartyClaims, projectResearchStudyR5SearchClaims, } from 'vet-data-utils-ts/research-study';
 import { VeterinaryCommunicationPresetFilters, VeterinaryResearchCommunicationTopics, } from 'vet-data-utils-ts/communication';
+import { HealthcareConsentPurposes } from 'gdc-common-utils-ts/constants/healthcare';
+import { ResourceTypesFhirR5 } from 'gdc-common-utils-ts/constants/fhir-resource-types';
+import { InteroperableContext } from 'gdc-common-utils-ts/constants/lifecycle';
+import { ClaimConsent, ConsentDecisions, ConsentStatuses, } from 'gdc-common-utils-ts/models/consent-rule';
 const FHIR_RESTFUL_INTERACTION_SYSTEM = 'http://hl7.org/fhir/restful-interaction';
 const FHIR_RESOURCE_TYPES_SYSTEM = 'http://hl7.org/fhir/fhir-types';
 export const VeterinaryResearchStudyPermissionActions = Object.freeze([
@@ -10,13 +14,17 @@ export const VeterinaryResearchStudyPermissionActions = Object.freeze([
 ]);
 export const VeterinaryResearchStudyInvitationClaimNames = Object.freeze({
     Context: '@context',
-    Status: 'Consent.status',
-    Decision: 'Consent.decision',
-    ActorIdentifier: 'Consent.actor-identifier',
-    Purpose: 'Consent.purpose',
-    Action: 'Consent.action',
-    ResourceType: 'Consent.resource-type',
+    Status: ClaimConsent.status,
+    Decision: ClaimConsent.decision,
+    ActorIdentifier: ClaimConsent.actorIdentifier,
+    Purpose: ClaimConsent.purpose,
+    Action: ClaimConsent.action,
+    ResourceType: ClaimConsent.resourceType,
 });
+/** Builds the exact GW study-pinned ResearchSubject `crus` capability. */
+export function buildVeterinaryResearchStudyAccessScope(researchStudyId) {
+    return `organization/ResearchSubject.crus?study=ResearchStudy/${boundedId(researchStudyId)}`;
+}
 /**
  * Requests the current study-scoped ResearchSubject operations. Deleting
  * selected clinical facts is a later operation on those concrete resources;
@@ -31,9 +39,70 @@ export function buildVeterinaryResearchStudySmartAuthorization(input) {
     }
     const researchStudyReference = `ResearchStudy/${boundedId(input.researchStudyId)}`;
     return deepFreeze({
-        purpose: 'RESEARCH',
+        purpose: HealthcareConsentPurposes.Research,
         researchStudyReference,
-        scopes: [`organization/ResearchSubject.crus?study=${encodeURIComponent(researchStudyReference)}`],
+        // This is a SMART scope value, not a URL query assembled by the browser.
+        // Encoding the slash would no longer equal the active Consent action.
+        scopes: [buildVeterinaryResearchStudyAccessScope(input.researchStudyId)],
+    });
+}
+/**
+ * Builds controller decisions for the VET ResearchStudy Consent `_batch`.
+ * Every entry is an explicit active/permit decision for one DCR-bound
+ * PractitionerRole. Invitation drafts, descriptive Group membership and
+ * `ResearchStudy.associatedParty` never authorize. The only action is the
+ * exact study-scoped ResearchSubject create/read/update/search capability;
+ * delete is deliberately absent.
+ *
+ * `subjectDid` is deliberately absent from the matching SMART authorization:
+ * the high-level professional runtime supplies the DCR-bound actor as `sub`,
+ * while GW derives the ResearchStudy authorization subject from this scope.
+ *
+ * @see https://hl7.org/fhir/R5/consent.html
+ * @see https://hl7.org/fhir/R5/researchstudy.html
+ */
+export function buildVeterinaryResearchStudyActiveConsentBatch(inputs) {
+    if (!Array.isArray(inputs) || inputs.length === 0) {
+        throw new TypeError('veterinary_research_study_active_consent_batch_empty');
+    }
+    const data = inputs.map(buildVeterinaryResearchStudyActiveConsentEntry);
+    return deepFreeze({ data });
+}
+/** Builds one POST Consent entry accepted by the VET ResearchStudy manager. */
+export function buildVeterinaryResearchStudyActiveConsentEntry(input) {
+    if (input.status !== undefined && input.status !== ConsentStatuses.Active) {
+        throw new TypeError('veterinary_research_study_active_consent_status_invalid');
+    }
+    const consentId = boundedId(input.consentId);
+    const researchStudyReference = `ResearchStudy/${boundedId(input.researchStudyId)}`;
+    const practitionerRoleReference = `PractitionerRole/${boundedId(input.practitionerRoleId)}`;
+    const actorRole = String(input.actorRole || '').trim();
+    if (!/^ISCO-08\|[0-9]{1,4}$/.test(actorRole)) {
+        throw new TypeError('veterinary_research_study_active_consent_actor_role_invalid');
+    }
+    const date = boundedDate(input.date);
+    const action = buildVeterinaryResearchStudyAccessScope(input.researchStudyId);
+    return deepFreeze({
+        type: 'Consent-v5.0.0',
+        resource: {
+            resourceType: ResourceTypesFhirR5.Consent,
+            id: consentId,
+            status: ConsentStatuses.Active,
+            meta: {
+                claims: {
+                    '@context': InteroperableContext.FhirApi,
+                    [ClaimConsent.status]: ConsentStatuses.Active,
+                    [ClaimConsent.decision]: ConsentDecisions.Permit,
+                    [ClaimConsent.purpose]: HealthcareConsentPurposes.Research,
+                    [ClaimConsent.sourceReference]: researchStudyReference,
+                    [ClaimConsent.actorIdentifier]: practitionerRoleReference,
+                    [ClaimConsent.actorRole]: actorRole,
+                    [ClaimConsent.action]: action,
+                    [ClaimConsent.date]: date,
+                },
+            },
+        },
+        request: { method: 'POST', url: ResourceTypesFhirR5.Consent },
     });
 }
 export function buildVeterinaryResearchStudyBatch(entries) {
@@ -264,6 +333,17 @@ function boundedReference(value, resourceType) {
     boundedId(reference.slice(prefix.length));
     return reference;
 }
+function boundedDate(value) {
+    const date = String(value || '').trim();
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) {
+        throw new TypeError('veterinary_research_study_active_consent_date_invalid');
+    }
+    const parsed = new Date(`${date}T00:00:00Z`);
+    if (!Number.isFinite(parsed.valueOf()) || parsed.toISOString().slice(0, 10) !== date) {
+        throw new TypeError('veterinary_research_study_active_consent_date_invalid');
+    }
+    return date;
+}
 function optionalInstant(value) {
     const instant = String(value || '').trim();
     if (!instant)

package/docs/101-RESEARCH-STUDY-INVITATIONS.md

@@ -16,6 +16,7 @@ related to the exact ResearchStudy. Whole-twin delete is absent.
 
 ```ts
 import {
+  buildVeterinaryResearchStudyActiveConsentBatch,
   buildVeterinaryResearchStudyPartyInvitations,
   buildVeterinaryResearchStudySmartAuthorization,
 } from 'vet-sdk-core-ts/research-study'
@@ -37,6 +38,18 @@ for (const communication of invitations) {
   await professionalRuntime.ingestCommunicationAndUpdateIndex({ communication })
 }
 
+// Once DCR is confirmed, the controller persists a new active Consent. This
+// is separate from the draft inside Communication and is the actual grant.
+const activeConsentBatch = buildVeterinaryResearchStudyActiveConsentBatch([{
+  consentId: activeConsentId,
+  researchStudyId: study.id,
+  practitionerRoleId: protectedProfessional.practitionerRoleId,
+  actorRole: protectedProfessional.iscoRole,
+  date: new Date().toISOString().slice(0, 10),
+}])
+// The protected BFF submits this primary document to the tenant organization
+// FHIR R5 Consent/_batch boundary; the browser never authors that route.
+
 // This succeeds only after protected state proves both prerequisites. Browser
 // input must not be trusted as that proof.
 const authorization = buildVeterinaryResearchStudySmartAuthorization({
@@ -47,6 +60,12 @@ const authorization = buildVeterinaryResearchStudySmartAuthorization({
 await professionalRuntime.requestSmartToken(authorization)
 ```
 
+The SMART authorization intentionally does not carry `subjectDid`:
+`openProfessional()` supplies its DCR-bound actor as `sub`, while GW derives
+the authorization subject `ResearchStudy/<id>` from the exact unescaped scope.
+Percent-encoding the `/` in that scope would no longer match the active
+Consent action and is rejected.
+
 The Bundle is encoded as the standard
 `Communication.payload.contentAttachment` with
 `contentType = application/fhir+json`. The Consent uses:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vet-sdk-core-ts",
-  "version": "0.4.11",
+  "version": "0.4.12",
   "description": "Browser-safe VetChain core contracts and governed animal species identifiers",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",
@@ -63,6 +63,7 @@
   },
   "dependencies": {
     "@noble/hashes": "^2.2.0",
+    "gdc-common-utils-ts": "2.9.4",
     "vet-data-utils-ts": "0.5.0"
   }
 }