vet-sdk-core-ts 0.4.14 → 0.4.15

package/README.md

@@ -37,7 +37,9 @@ cannot be broadened to delete.
 `buildVeterinaryResearchStudyPartyInvitations` creates exactly one claims-only
 `Communication` per associated `PractitionerRole`. Its canonical attachment
 claims carry an `application/vnd.api+json` primary document containing one
-claims-only draft Consent. `Consent.source-reference` pins the ResearchStudy
+JSON:API resource object with `type`, `id` and flat Consent claims in
+`attributes`; `resource`, `request` and FHIR Bundle shapes are rejected.
+`Consent.source-reference` pins the ResearchStudy
 and `Consent.resource-type` pins `ResearchSubject`. The draft requests only
 create, read, update and search; it contains no delete permission and never
 authorizes SMART access. Native FHIR Communication, Consent or Bundle objects
@@ -53,6 +55,10 @@ through separate `ResearchStudy.associatedParty` PATCH entries. It must not use
 `ResearchStudy.recruitment.eligibility`, which represents research-subject
 cohorts or eligibility criteria. Group grants no authorization, permission or
 SMART scope; DCR and active Consent remain separate.
+The Group create builder requires the ResearchStudy UUID and derives a
+governed `Group.identifier`. Its exported search helper re-derives
+the same deterministic UUIDv5 review-team identifier after refresh without
+using eligibility or granting authority.
 
 The complete controller-to-professional contract and a browser-safe snippet
 are in

package/dist/research-study.d.ts

@@ -15,21 +15,12 @@ export declare const VeterinaryResearchStudyInvitationClaimNames: Readonly<{
     readonly ResourceType: ClaimConsent.resourceType;
 }>;
 export type VeterinaryResearchStudyDraftConsent = Readonly<{
-    resourceType: 'Consent';
+    type: 'Consent-v5.0.0';
     id: string;
-    meta: Readonly<{
-        claims: Readonly<Record<string, string>>;
-    }>;
+    attributes: Readonly<Record<string, string>>;
 }>;
 export type VeterinaryResearchStudyInvitationDocument = Readonly<{
-    data: readonly Readonly<{
-        type: 'Consent-v5.0.0';
-        resource: VeterinaryResearchStudyDraftConsent;
-        request: Readonly<{
-            method: 'POST';
-            url: 'Consent';
-        }>;
-    }>[];
+    data: readonly VeterinaryResearchStudyDraftConsent[];
 }>;
 export type VeterinaryResearchStudyPartyInvitation = Readonly<{
     resourceType: 'Communication';
@@ -74,6 +65,19 @@ export type VeterinaryResearchStudyGroupBatchEntry = Readonly<{
 export type VeterinaryResearchStudyGroupBatch = Readonly<{
     data: readonly VeterinaryResearchStudyGroupBatchEntry[];
 }>;
+/**
+ * Canonical URI Identifier.system linking one descriptive review-team Group
+ * to its study through an RFC 9562 UUIDv5 value.
+ *
+ * @see https://hl7.org/fhir/R5/datatypes.html#Identifier
+ * @see https://www.rfc-editor.org/rfc/rfc9562#name-uuid-version-5
+ */
+export declare const VeterinaryResearchStudyReviewTeamIdentifierSystem: "urn:ietf:rfc:3986";
+/** UUIDv5 namespace governed by this SDK for ResearchStudy review-team identifiers. */
+export declare const VeterinaryResearchStudyReviewTeamIdentifierNamespace: "6434afe2-d152-5ec2-a88b-ec2a96e0f010";
+export type VeterinaryResearchStudyReviewTeamGroupSearch = Readonly<{
+    identifier: string;
+}>;
 export type VeterinaryResearchStudySmartAuthorization = Readonly<{
     purpose: typeof HealthcareConsentPurposes.Research;
     researchStudyReference: string;
@@ -145,8 +149,22 @@ export declare function buildVeterinaryResearchStudyBatch(entries: readonly Vete
  * @see https://hl7.org/fhir/R5/group-search.html
  */
 export declare function buildVeterinaryResearchStudyGroupCreateEntry(input: Readonly<{
+    researchStudyId: string;
     group: GroupR5ResearchTeam;
 }>): VeterinaryResearchStudyGroupBatchEntry;
+/** Builds the governed business Identifier; it describes correlation, never authority. */
+export declare function buildVeterinaryResearchStudyReviewTeamIdentifier(researchStudyId: string): Readonly<{
+    system: typeof VeterinaryResearchStudyReviewTeamIdentifierSystem;
+    value: string;
+}>;
+/**
+ * Builds the standard FHIR `Group.identifier` token search used to recover the
+ * Group after refresh. Re-derivation avoids storing a second linkage and never
+ * constitutes access authority.
+ *
+ * @see https://hl7.org/fhir/R5/group-search.html
+ */
+export declare function buildVeterinaryResearchStudyReviewTeamGroupSearch(researchStudyId: string): VeterinaryResearchStudyReviewTeamGroupSearch;
 /**
  * Builds one independently correlated PATCH per PractitionerRole member. A
  * PATCH changes descriptive membership only; DCR, Consent and SMART remain

package/dist/research-study.js

@@ -7,6 +7,7 @@ import { ResourceTypesFhirR5 } from 'gdc-common-utils-ts/constants/fhir-resource
 import { InteroperableContext } from 'gdc-common-utils-ts/constants/lifecycle';
 import { ClaimConsent, ConsentDecisions, ConsentStatuses, } from 'gdc-common-utils-ts/models/consent-rule';
 import { CommunicationClaim } from 'gdc-common-utils-ts/models/interoperable-claims/communication-claims';
+import { sha1 } from '@noble/hashes/legacy.js';
 export const VeterinaryResearchStudyPermissionActions = Object.freeze([
     'create',
     'read',
@@ -22,6 +23,16 @@ export const VeterinaryResearchStudyInvitationClaimNames = Object.freeze({
     Action: ClaimConsent.action,
     ResourceType: ClaimConsent.resourceType,
 });
+/**
+ * Canonical URI Identifier.system linking one descriptive review-team Group
+ * to its study through an RFC 9562 UUIDv5 value.
+ *
+ * @see https://hl7.org/fhir/R5/datatypes.html#Identifier
+ * @see https://www.rfc-editor.org/rfc/rfc9562#name-uuid-version-5
+ */
+export const VeterinaryResearchStudyReviewTeamIdentifierSystem = 'urn:ietf:rfc:3986';
+/** UUIDv5 namespace governed by this SDK for ResearchStudy review-team identifiers. */
+export const VeterinaryResearchStudyReviewTeamIdentifierNamespace = '6434afe2-d152-5ec2-a88b-ec2a96e0f010';
 /** Builds the exact GW study-pinned ResearchSubject `crus` capability. */
 export function buildVeterinaryResearchStudyAccessScope(researchStudyId) {
     return `organization/ResearchSubject.crus?study=ResearchStudy/${boundedId(researchStudyId)}`;
@@ -122,12 +133,32 @@ export function buildVeterinaryResearchStudyGroupCreateEntry(input) {
     const group = normalizedResearchTeamGroup(input.group);
     if (group.member.length > 0)
         throw new TypeError('group_members_require_patch_entries');
+    const identifier = buildVeterinaryResearchStudyReviewTeamIdentifier(input.researchStudyId);
     return deepFreeze({
         type: 'Group-v5.0.0',
-        resource: projectGroupR5FlatClaimsResource(group),
+        resource: projectGroupR5FlatClaimsResource({ ...group, identifier: [identifier] }),
         request: { method: 'POST', url: 'Group' },
     });
 }
+/** Builds the governed business Identifier; it describes correlation, never authority. */
+export function buildVeterinaryResearchStudyReviewTeamIdentifier(researchStudyId) {
+    const studyUuid = boundedStudyUuid(researchStudyId);
+    return deepFreeze({
+        system: VeterinaryResearchStudyReviewTeamIdentifierSystem,
+        value: `urn:uuid:${uuidV5(studyUuid, VeterinaryResearchStudyReviewTeamIdentifierNamespace)}`,
+    });
+}
+/**
+ * Builds the standard FHIR `Group.identifier` token search used to recover the
+ * Group after refresh. Re-derivation avoids storing a second linkage and never
+ * constitutes access authority.
+ *
+ * @see https://hl7.org/fhir/R5/group-search.html
+ */
+export function buildVeterinaryResearchStudyReviewTeamGroupSearch(researchStudyId) {
+    const identifier = buildVeterinaryResearchStudyReviewTeamIdentifier(researchStudyId);
+    return deepFreeze({ identifier: `${identifier.system}|${identifier.value}` });
+}
 /**
  * Builds one independently correlated PATCH per PractitionerRole member. A
  * PATCH changes descriptive membership only; DCR, Consent and SMART remain
@@ -212,28 +243,22 @@ export function buildVeterinaryResearchStudyPartyInvitation(input) {
     if (!topic)
         throw new TypeError('veterinary_research_study_invitation_topic_unavailable');
     const consent = {
-        resourceType: 'Consent',
+        type: 'Consent-v5.0.0',
         id: consentId,
-        meta: {
-            claims: {
-                [VeterinaryResearchStudyInvitationClaimNames.Context]: InteroperableContext.FhirApi,
-                [VeterinaryResearchStudyInvitationClaimNames.Status]: ConsentStatuses.Draft,
-                [VeterinaryResearchStudyInvitationClaimNames.Decision]: ConsentDecisions.Permit,
-                [VeterinaryResearchStudyInvitationClaimNames.ActorIdentifier]: partyReference,
-                [ClaimConsent.grantee]: partyReference,
-                [VeterinaryResearchStudyInvitationClaimNames.Purpose]: topic.value,
-                [VeterinaryResearchStudyInvitationClaimNames.Action]: VeterinaryResearchStudyPermissionActions.join(','),
-                [VeterinaryResearchStudyInvitationClaimNames.ResourceType]: 'ResearchSubject',
-                [ClaimConsent.sourceReference]: researchStudyReference,
-            },
+        attributes: {
+            [VeterinaryResearchStudyInvitationClaimNames.Context]: InteroperableContext.FhirApi,
+            [VeterinaryResearchStudyInvitationClaimNames.Status]: ConsentStatuses.Draft,
+            [VeterinaryResearchStudyInvitationClaimNames.Decision]: ConsentDecisions.Permit,
+            [VeterinaryResearchStudyInvitationClaimNames.ActorIdentifier]: partyReference,
+            [ClaimConsent.grantee]: partyReference,
+            [VeterinaryResearchStudyInvitationClaimNames.Purpose]: topic.value,
+            [VeterinaryResearchStudyInvitationClaimNames.Action]: VeterinaryResearchStudyPermissionActions.join(','),
+            [VeterinaryResearchStudyInvitationClaimNames.ResourceType]: 'ResearchSubject',
+            [ClaimConsent.sourceReference]: researchStudyReference,
         },
     };
     const document = {
-        data: [{
-                type: 'Consent-v5.0.0',
-                resource: consent,
-                request: { method: 'POST', url: 'Consent' },
-            }],
+        data: [consent],
     };
     const category = VeterinaryCommunicationPresetFilters.ResearchAgreements.categories[0];
     const sent = optionalInstant(input.sentAt);
@@ -292,10 +317,10 @@ export function decodeVeterinaryResearchStudyInvitationDocument(communication) {
     const entry = decoded?.data?.[0];
     if (decoded?.data?.length !== 1
         || entry?.type !== 'Consent-v5.0.0'
-        || entry.request?.method !== 'POST'
-        || entry.request.url !== 'Consent'
-        || !isClaimsOnlyResource(entry.resource, 'Consent')
-        || entry.resource.meta.claims[ClaimConsent.status] !== ConsentStatuses.Draft) {
+        || Object.keys(entry).some(key => !['type', 'id', 'attributes'].includes(key))
+        || !boundedJsonApiId(entry.id)
+        || !isFlatStringAttributes(entry.attributes)
+        || !isValidInvitationDraftConsentAttributes(entry.attributes, claims)) {
         throw new TypeError('veterinary_research_study_invitation_document_invalid');
     }
     return deepFreeze(decoded);
@@ -385,6 +410,34 @@ function boundedId(value) {
         throw new TypeError('veterinary_research_study_id_invalid');
     return id;
 }
+function boundedStudyUuid(value) {
+    const uuid = String(value || '').trim().toLowerCase();
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(uuid)) {
+        throw new TypeError('veterinary_research_study_review_team_study_id_invalid');
+    }
+    return uuid;
+}
+function uuidV5(name, namespace) {
+    const namespaceHexBytes = namespace.replace(/-/g, '').match(/.{2}/g) || [];
+    const namespaceBytes = Uint8Array.from(namespaceHexBytes.map(byte => Number.parseInt(byte, 16)));
+    const nameBytes = new TextEncoder().encode(name);
+    const input = new Uint8Array(namespaceBytes.length + nameBytes.length);
+    input.set(namespaceBytes);
+    input.set(nameBytes, namespaceBytes.length);
+    const digest = sha1(input).slice(0, 16);
+    digest[6] = (digest[6] & 0x0f) | 0x50;
+    digest[8] = (digest[8] & 0x3f) | 0x80;
+    const hex = Array.from(digest, byte => byte.toString(16).padStart(2, '0')).join('');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+function boundedJsonApiId(value) {
+    try {
+        return boundedId(value);
+    }
+    catch {
+        return undefined;
+    }
+}
 function boundedGroupId(value) {
     const id = String(value || '').trim();
     if (!/^[A-Za-z0-9\-.]{1,64}$/.test(id))
@@ -450,3 +503,24 @@ function isClaimsOnlyResource(value, resourceType) {
         return false;
     return Object.values(value.meta.claims).every(claim => typeof claim === 'string' && claim.trim().length > 0);
 }
+function isFlatStringAttributes(value) {
+    return isRecord(value)
+        && Object.keys(value).length > 0
+        && Object.values(value).every(attribute => typeof attribute === 'string' && attribute.trim().length > 0);
+}
+function isValidInvitationDraftConsentAttributes(attributes, communicationClaims) {
+    const expected = {
+        [VeterinaryResearchStudyInvitationClaimNames.Context]: InteroperableContext.FhirApi,
+        [VeterinaryResearchStudyInvitationClaimNames.Status]: ConsentStatuses.Draft,
+        [VeterinaryResearchStudyInvitationClaimNames.Decision]: ConsentDecisions.Permit,
+        [VeterinaryResearchStudyInvitationClaimNames.ActorIdentifier]: communicationClaims[CommunicationClaim.Recipient],
+        [ClaimConsent.grantee]: communicationClaims[CommunicationClaim.Recipient],
+        [VeterinaryResearchStudyInvitationClaimNames.Purpose]: communicationClaims[CommunicationClaim.Topic],
+        [VeterinaryResearchStudyInvitationClaimNames.Action]: VeterinaryResearchStudyPermissionActions.join(','),
+        [VeterinaryResearchStudyInvitationClaimNames.ResourceType]: 'ResearchSubject',
+        [ClaimConsent.sourceReference]: communicationClaims[CommunicationClaim.ContentReference],
+    };
+    const expectedEntries = Object.entries(expected);
+    return Object.keys(attributes).length === expectedEntries.length
+        && expectedEntries.every(([name, value]) => Boolean(value) && attributes[name] === value);
+}

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

@@ -27,6 +27,7 @@ import {
 
 const researchGroupId = 'review-team'
 const groupCreate = buildVeterinaryResearchStudyGroupCreateEntry({
+  researchStudyId: study.id,
   group: {
     resourceType: 'Group',
     id: researchGroupId,
@@ -96,11 +97,13 @@ Consent contain only `resourceType`, `id` and `resource.meta.claims`. Their
 FHIR-like field names are flat claims. Native nested FHIR JSON is reserved for
 an explicit export/projection boundary, not these GW builders.
 
-The draft Consent inside the Communication attachment is an explicit
-`application/vnd.api+json` proposal for recipient review. Both the outer
-Communication and the attached Consent contain only `resourceType`, `id` and
-`resource.meta.claims`. It never authorizes access; only the later flat-claims
-active Consent POST is evaluated by GW.
+The draft Consent inside the Communication attachment is an explicit JSON:API
+1.x `application/vnd.api+json` proposal for recipient review. Its `data[]`
+resource object contains only `type`, `id` and `attributes`; those attributes
+are the flat Consent claims. It has no internal `resource`, `request`, FHIR
+Bundle or Bundle entry. The outer Communication remains claims-only. The draft
+never authorizes access; only the later flat-claims active Consent POST is
+evaluated by GW.
 
 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).
@@ -124,6 +127,14 @@ Consent claims use:
 - `Consent.source-reference` for the exact `ResearchStudy/{id}`;
 - `Consent.action` for `create`, `read`, `update`, and `search`.
 
+The Group POST adds a governed business `Group.identifier` derived from the
+ResearchStudy UUID. Use
+`buildVeterinaryResearchStudyReviewTeamGroupSearch(study.id)` to recover the
+same descriptive review-team Group after a refresh. The helper deterministically
+re-derives a UUIDv5 using the SDK-exported, governed namespace and emits
+`urn:ietf:rfc:3986|urn:uuid:<uuidv5>`. This one-way correlation is a standard
+Group identifier token, not eligibility, Consent, permission or SMART authority.
+
 FHIR R5 references:
 
 - [ResearchStudy](https://hl7.org/fhir/R5/researchstudy.html)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vet-sdk-core-ts",
-  "version": "0.4.14",
+  "version": "0.4.15",
   "description": "Browser-safe VetChain core contracts and governed animal species identifiers",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",