vet-sdk-core-ts 0.4.12 → 0.4.13

package/README.md

@@ -41,6 +41,19 @@ to the ResearchStudy through `Consent.provision.data.reference` and to
 only create, read, update and search. It contains no delete permission and
 never authorizes SMART access.
 
+`buildVeterinaryResearchStudyGroupCreateEntry` and
+`buildVeterinaryResearchStudyGroupMemberPatchEntries` build the native R5 Group
+POST/PATCH entries for an enumerated professional review team. Every member is
+a registered `PractitionerRole`; the exact twelve Group search claims are
+derived from `vet-data-utils-ts/group`. The ResearchStudy points to the team
+through the reference returned by
+`buildVeterinaryResearchStudyEligibilityGroupReference`, used as
+`ResearchStudy.recruitment.eligibility`.
+`buildVeterinaryResearchStudyEligibilityGroupPatchEntry` links an existing
+study and is wrapped by `buildVeterinaryResearchStudyBatch`; it does not invent
+a mixed-resource gateway batch. Group itself contains no reverse study link
+and grants no authorization, permission or SMART scope.
+
 The complete controller-to-professional contract and a browser-safe snippet
 are in
 [`docs/101-RESEARCH-STUDY-INVITATIONS.md`](docs/101-RESEARCH-STUDY-INVITATIONS.md).
@@ -51,6 +64,8 @@ FHIR references:
 - https://hl7.org/fhir/R5/researchsubject-search.html
 - https://hl7.org/fhir/R5/communication.html
 - https://hl7.org/fhir/R5/consent-definitions.html
+- https://hl7.org/fhir/R5/group.html
+- https://hl7.org/fhir/R5/group-search.html
 
 ## Reusable professional BFF
 

package/dist/research-study.d.ts

@@ -1,4 +1,5 @@
 import { type ResearchStudyAssociatedParty } from 'vet-data-utils-ts/research-study';
+import { type GroupR5ResearchTeam } from 'vet-data-utils-ts/group';
 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';
@@ -100,6 +101,24 @@ export type VeterinaryResearchStudyBatchEntry = Readonly<{
 export type VeterinaryResearchStudyBatch = Readonly<{
     data: readonly VeterinaryResearchStudyBatchEntry[];
 }>;
+export type VeterinaryResearchStudyGroupResource = GroupR5ResearchTeam & Readonly<{
+    id: string;
+    meta: Readonly<{
+        claims: Readonly<Record<string, readonly string[]>>;
+        [key: string]: unknown;
+    }>;
+}>;
+export type VeterinaryResearchStudyGroupBatchEntry = Readonly<{
+    type: 'Group-v5.0.0';
+    resource: VeterinaryResearchStudyGroupResource;
+    request: Readonly<{
+        method: 'POST' | 'PATCH';
+        url: string;
+    }>;
+}>;
+export type VeterinaryResearchStudyGroupBatch = Readonly<{
+    data: readonly VeterinaryResearchStudyGroupBatchEntry[];
+}>;
 export type VeterinaryResearchStudySmartAuthorization = Readonly<{
     purpose: typeof HealthcareConsentPurposes.Research;
     researchStudyReference: string;
@@ -163,6 +182,54 @@ export declare function buildVeterinaryResearchStudyActiveConsentBatch(inputs: r
 /** 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;
+/**
+ * Returns the native eligibility reference by which an R5 ResearchStudy links
+ * to its descriptive professional Group. The direction is deliberately from
+ * `ResearchStudy.recruitment.eligibility` to Group; no invented study field or
+ * search claim is added to Group.
+ *
+ * @see https://hl7.org/fhir/R5/researchstudy.html
+ * @see https://hl7.org/fhir/R5/group.html
+ */
+export declare function buildVeterinaryResearchStudyEligibilityGroupReference(groupId: string): Readonly<{
+    reference: `Group/${string}`;
+    type: 'Group';
+}>;
+/**
+ * Builds the native ResearchStudy PATCH that links a descriptive Group through
+ * `ResearchStudy.recruitment.eligibility`. The existing ResearchStudy batch
+ * builder wraps this entry; Group and ResearchStudy remain separate resource
+ * endpoints and no mixed-resource transport envelope is invented.
+ *
+ * @see https://hl7.org/fhir/R5/researchstudy.html
+ * @see https://hl7.org/fhir/R5/researchstudy-search.html
+ */
+export declare function buildVeterinaryResearchStudyEligibilityGroupPatchEntry(input: Readonly<{
+    researchStudyId: string;
+    groupId: string;
+}>): VeterinaryResearchStudyBatchEntry;
+/**
+ * Builds the Group POST used to create one enumerated ResearchStudy review
+ * team. Every member is a native PractitionerRole reference. Group remains a
+ * description only and the generated resource cannot carry access policy.
+ *
+ * @see https://hl7.org/fhir/R5/group.html
+ * @see https://hl7.org/fhir/R5/group-search.html
+ */
+export declare function buildVeterinaryResearchStudyGroupCreateEntry(input: Readonly<{
+    group: GroupR5ResearchTeam;
+}>): VeterinaryResearchStudyGroupBatchEntry;
+/**
+ * Builds one independently correlated PATCH per PractitionerRole member. A
+ * PATCH changes descriptive membership only; DCR, Consent and SMART remain
+ * separate authorization boundaries.
+ */
+export declare function buildVeterinaryResearchStudyGroupMemberPatchEntries(input: Readonly<{
+    groupId: string;
+    members: unknown;
+}>): readonly VeterinaryResearchStudyGroupBatchEntry[];
+/** Wraps only validated Group POST/PATCH entries in one JSON:API document. */
+export declare function buildVeterinaryResearchStudyGroupBatch(entries: readonly VeterinaryResearchStudyGroupBatchEntry[]): VeterinaryResearchStudyGroupBatch;
 export declare function buildVeterinaryResearchStudyCreateEntry(input: Readonly<{
     study: VeterinaryResearchStudyCreateResource;
 }>): VeterinaryResearchStudyBatchEntry;

package/dist/research-study.js

@@ -1,5 +1,6 @@
 import { normalizeResearchStudyAssociatedParties, projectResearchStudyAssociatedPartyClaims, projectResearchStudyR5SearchClaims, } from 'vet-data-utils-ts/research-study';
 import { VeterinaryCommunicationPresetFilters, VeterinaryResearchCommunicationTopics, } from 'vet-data-utils-ts/communication';
+import { normalizeGroupPractitionerRoleMembers, normalizeGroupR5ResearchTeam, projectGroupR5SearchClaims, } from 'vet-data-utils-ts/group';
 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';
@@ -110,6 +111,86 @@ export function buildVeterinaryResearchStudyBatch(entries) {
         throw new TypeError('veterinary_research_study_batch_empty');
     return deepFreeze({ data: entries.map(entry => clonePlain(entry)) });
 }
+/**
+ * Returns the native eligibility reference by which an R5 ResearchStudy links
+ * to its descriptive professional Group. The direction is deliberately from
+ * `ResearchStudy.recruitment.eligibility` to Group; no invented study field or
+ * search claim is added to Group.
+ *
+ * @see https://hl7.org/fhir/R5/researchstudy.html
+ * @see https://hl7.org/fhir/R5/group.html
+ */
+export function buildVeterinaryResearchStudyEligibilityGroupReference(groupId) {
+    return deepFreeze({ reference: `Group/${boundedGroupId(groupId)}`, type: 'Group' });
+}
+/**
+ * Builds the native ResearchStudy PATCH that links a descriptive Group through
+ * `ResearchStudy.recruitment.eligibility`. The existing ResearchStudy batch
+ * builder wraps this entry; Group and ResearchStudy remain separate resource
+ * endpoints and no mixed-resource transport envelope is invented.
+ *
+ * @see https://hl7.org/fhir/R5/researchstudy.html
+ * @see https://hl7.org/fhir/R5/researchstudy-search.html
+ */
+export function buildVeterinaryResearchStudyEligibilityGroupPatchEntry(input) {
+    if (containsAuthorizationProperty(input)) {
+        throw new TypeError('veterinary_research_study_group_authorization_forbidden');
+    }
+    const researchStudyId = boundedId(input.researchStudyId);
+    const eligibility = buildVeterinaryResearchStudyEligibilityGroupReference(input.groupId);
+    return deepFreeze({
+        type: 'ResearchStudy-v5.0.0',
+        resource: withProjectedClaims({
+            resourceType: 'ResearchStudy',
+            id: researchStudyId,
+            recruitment: { eligibility },
+        }),
+        request: { method: 'PATCH', url: `ResearchStudy/${researchStudyId}` },
+    });
+}
+/**
+ * Builds the Group POST used to create one enumerated ResearchStudy review
+ * team. Every member is a native PractitionerRole reference. Group remains a
+ * description only and the generated resource cannot carry access policy.
+ *
+ * @see https://hl7.org/fhir/R5/group.html
+ * @see https://hl7.org/fhir/R5/group-search.html
+ */
+export function buildVeterinaryResearchStudyGroupCreateEntry(input) {
+    const group = normalizedResearchTeamGroup(input.group);
+    return deepFreeze({
+        type: 'Group-v5.0.0',
+        resource: withProjectedGroupClaims(group),
+        request: { method: 'POST', url: 'Group' },
+    });
+}
+/**
+ * Builds one independently correlated PATCH per PractitionerRole member. A
+ * PATCH changes descriptive membership only; DCR, Consent and SMART remain
+ * separate authorization boundaries.
+ */
+export function buildVeterinaryResearchStudyGroupMemberPatchEntries(input) {
+    const id = boundedGroupId(input.groupId);
+    const members = normalizeGroupPractitionerRoleMembers(input.members);
+    return deepFreeze(members.map(member => ({
+        type: 'Group-v5.0.0',
+        resource: withProjectedGroupClaims(deepFreeze({
+            resourceType: 'Group',
+            id,
+            type: 'practitioner',
+            membership: 'enumerated',
+            member: [member],
+        })),
+        request: { method: 'PATCH', url: `Group/${id}` },
+    })));
+}
+/** Wraps only validated Group POST/PATCH entries in one JSON:API document. */
+export function buildVeterinaryResearchStudyGroupBatch(entries) {
+    if (!Array.isArray(entries) || entries.length === 0) {
+        throw new TypeError('veterinary_research_study_group_batch_empty');
+    }
+    return deepFreeze({ data: entries.map(normalizeResearchStudyGroupEntry) });
+}
 export function buildVeterinaryResearchStudyCreateEntry(input) {
     const study = normalizedStudy(input.study);
     return deepFreeze({
@@ -290,6 +371,37 @@ function normalizedStudy(input) {
         ...(associatedParty ? { associatedParty } : {}),
     });
 }
+function normalizedResearchTeamGroup(input) {
+    const source = clonePlain(input);
+    const normalized = normalizeGroupR5ResearchTeam(source);
+    return deepFreeze({ ...normalized, id: boundedGroupId(normalized.id) });
+}
+function normalizeResearchStudyGroupEntry(input) {
+    if (!input || input.type !== 'Group-v5.0.0') {
+        throw new TypeError('veterinary_research_study_group_entry_invalid');
+    }
+    const group = normalizedResearchTeamGroup(input.resource);
+    const method = input.request?.method;
+    const expectedUrl = method === 'POST' ? 'Group' : method === 'PATCH' ? `Group/${group.id}` : '';
+    if (!expectedUrl || input.request.url !== expectedUrl) {
+        throw new TypeError('veterinary_research_study_group_request_invalid');
+    }
+    return deepFreeze({
+        type: 'Group-v5.0.0',
+        resource: withProjectedGroupClaims(group),
+        request: { method, url: expectedUrl },
+    });
+}
+function withProjectedGroupClaims(group) {
+    const claims = projectGroupR5SearchClaims(group);
+    return deepFreeze({
+        ...group,
+        meta: {
+            ...(typeof group.meta === 'object' && group.meta !== null ? group.meta : {}),
+            claims,
+        },
+    });
+}
 function clonePlain(value) {
     if (Array.isArray(value))
         return value.map(clonePlain);
@@ -325,6 +437,12 @@ function boundedId(value) {
         throw new TypeError('veterinary_research_study_id_invalid');
     return id;
 }
+function boundedGroupId(value) {
+    const id = String(value || '').trim();
+    if (!/^[A-Za-z0-9\-.]{1,64}$/.test(id))
+        throw new TypeError('veterinary_research_study_group_id_invalid');
+    return id;
+}
 function boundedReference(value, resourceType) {
     const reference = String(value || '').trim();
     const prefix = `${resourceType}/`;
@@ -352,6 +470,16 @@ function optionalInstant(value) {
         throw new TypeError('veterinary_research_study_invitation_sent_invalid');
     return instant;
 }
+function containsAuthorizationProperty(value, seen = new WeakSet()) {
+    if (!value || typeof value !== 'object')
+        return false;
+    if (seen.has(value))
+        return false;
+    seen.add(value);
+    if (Array.isArray(value))
+        return value.some(item => containsAuthorizationProperty(item, seen));
+    return Object.entries(value).some(([name, nested]) => ['authorization', 'permission', 'scope'].includes(name) || containsAuthorizationProperty(nested, seen));
+}
 function splitCodingToken(value) {
     const separator = value.lastIndexOf('|');
     if (separator < 1 || separator === value.length - 1) {

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

@@ -17,10 +17,39 @@ related to the exact ResearchStudy. Whole-twin delete is absent.
 ```ts
 import {
   buildVeterinaryResearchStudyActiveConsentBatch,
+  buildVeterinaryResearchStudyBatch,
+  buildVeterinaryResearchStudyEligibilityGroupPatchEntry,
+  buildVeterinaryResearchStudyGroupBatch,
+  buildVeterinaryResearchStudyGroupCreateEntry,
+  buildVeterinaryResearchStudyGroupMemberPatchEntries,
   buildVeterinaryResearchStudyPartyInvitations,
   buildVeterinaryResearchStudySmartAuthorization,
 } from 'vet-sdk-core-ts/research-study'
 
+const researchGroupId = 'review-team'
+const groupCreate = buildVeterinaryResearchStudyGroupCreateEntry({
+  group: {
+    resourceType: 'Group',
+    id: researchGroupId,
+    type: 'practitioner',
+    membership: 'enumerated',
+    member: [],
+  },
+})
+const memberPatches = buildVeterinaryResearchStudyGroupMemberPatchEntries({
+  groupId: researchGroupId,
+  members: associatedParties.map(({ party }) => ({ entity: party })),
+})
+const groupBatch = buildVeterinaryResearchStudyGroupBatch([groupCreate, ...memberPatches])
+// The protected controller BFF submits `groupBatch`; membership grants no access.
+const eligibilityPatch = buildVeterinaryResearchStudyEligibilityGroupPatchEntry({
+  researchStudyId: study.id,
+  groupId: researchGroupId,
+})
+const studyPatchBatch = buildVeterinaryResearchStudyBatch([eligibilityPatch])
+// Submit `studyPatchBatch` through the protected ResearchStudy BFF after the
+// Group exists. The two native resource endpoints remain separate.
+
 const invitations = buildVeterinaryResearchStudyPartyInvitations({
   researchStudyId: study.id,
   controllerReference: organizationReference,
@@ -60,6 +89,18 @@ const authorization = buildVeterinaryResearchStudySmartAuthorization({
 await professionalRuntime.requestSmartToken(authorization)
 ```
 
+The controller may also create a descriptive review team with
+`buildVeterinaryResearchStudyGroupCreateEntry()` and append each registered
+`PractitionerRole` with
+`buildVeterinaryResearchStudyGroupMemberPatchEntries()`. The Group is linked
+from `ResearchStudy.recruitment.eligibility` using
+`buildVeterinaryResearchStudyEligibilityGroupPatchEntry()` and the existing
+ResearchStudy batch builder. Group membership is not evidence of DCR or
+Consent and never grants the SMART authorization above.
+
+These builders follow the native [FHIR R5 Group resource](https://hl7.org/fhir/R5/group.html)
+and its exact [resource-specific search catalogue](https://hl7.org/fhir/R5/group-search.html).
+
 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.

package/package.json

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