vet-sdk-core-ts 0.4.15 → 0.4.16

package/README.md

@@ -8,6 +8,14 @@ owns gateway request construction. GW VET remains the policy authority.
 
 ## Research studies
 
+`buildVeterinaryResearchStudyCreateWorkflowIds` accepts a client-generated
+operation UUID and the exact `PractitionerRole/...` references. It reuses the
+operation UUID as `researchStudyId` and deterministically derives distinct
+UUIDv5 values for the Group and every Communication/draft Consent pair. A
+retry therefore addresses the same resources and a partially completed saga
+can resume safely. Stable identifiers do not make separate service calls
+atomic and confer no membership, Consent or SMART authority.
+
 `buildVeterinaryResearchStudyCreateEntry` accepts ResearchStudy business data
 and projects it into the canonical JSON:API resource object: `resourceType`,
 `id` and flat `resource.meta.claims`. It does not send native `status`, `title`,

package/dist/research-study.d.ts

@@ -78,11 +78,33 @@ export declare const VeterinaryResearchStudyReviewTeamIdentifierNamespace: "6434
 export type VeterinaryResearchStudyReviewTeamGroupSearch = Readonly<{
     identifier: string;
 }>;
+export type VeterinaryResearchStudyCreateWorkflowIds = Readonly<{
+    researchStudyId: string;
+    groupId: string;
+    invitations: readonly Readonly<{
+        practitionerRoleReference: string;
+        communicationId: string;
+        consentId: string;
+    }>[];
+}>;
 export type VeterinaryResearchStudySmartAuthorization = Readonly<{
     purpose: typeof HealthcareConsentPurposes.Research;
     researchStudyReference: string;
     scopes: readonly [string];
 }>;
+/**
+ * Derives every identifier needed to retry or resume one ResearchStudy create
+ * workflow. The client-generated operation UUID is the ResearchStudy id and
+ * UUIDv5 names produce a stable Group, Communication and draft Consent id.
+ * Reusing these ids supports idempotent saga steps; it does not make separate
+ * persistence calls atomic and does not convey Consent or SMART authority.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc9562#name-uuid-version-5
+ */
+export declare function buildVeterinaryResearchStudyCreateWorkflowIds(input: Readonly<{
+    operationId: string;
+    practitionerRoleReferences: readonly string[];
+}>): VeterinaryResearchStudyCreateWorkflowIds;
 export type VeterinaryResearchStudyActiveConsentInput = Readonly<{
     consentId: string;
     researchStudyId: string;

package/dist/research-study.js

@@ -33,6 +33,47 @@ export const VeterinaryResearchStudyInvitationClaimNames = Object.freeze({
 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';
+/**
+ * Derives every identifier needed to retry or resume one ResearchStudy create
+ * workflow. The client-generated operation UUID is the ResearchStudy id and
+ * UUIDv5 names produce a stable Group, Communication and draft Consent id.
+ * Reusing these ids supports idempotent saga steps; it does not make separate
+ * persistence calls atomic and does not convey Consent or SMART authority.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc9562#name-uuid-version-5
+ */
+export function buildVeterinaryResearchStudyCreateWorkflowIds(input) {
+    let operationId;
+    try {
+        operationId = normalizedUuid(input?.operationId);
+    }
+    catch {
+        throw new TypeError('veterinary_research_study_create_operation_id_invalid');
+    }
+    if (!Array.isArray(input?.practitionerRoleReferences)) {
+        throw new TypeError('veterinary_research_study_create_practitioner_role_reference_invalid');
+    }
+    const references = input.practitionerRoleReferences.map(reference => {
+        try {
+            return boundedReference(reference, 'PractitionerRole');
+        }
+        catch {
+            throw new TypeError('veterinary_research_study_create_practitioner_role_reference_invalid');
+        }
+    });
+    if (new Set(references).size !== references.length) {
+        throw new TypeError('veterinary_research_study_create_practitioner_role_duplicate');
+    }
+    return deepFreeze({
+        researchStudyId: operationId,
+        groupId: uuidV5('Group', operationId),
+        invitations: references.map(practitionerRoleReference => ({
+            practitionerRoleReference,
+            communicationId: uuidV5(`Communication|${practitionerRoleReference}`, operationId),
+            consentId: uuidV5(`Consent|${practitionerRoleReference}`, operationId),
+        })),
+    });
+}
 /** Builds the exact GW study-pinned ResearchSubject `crus` capability. */
 export function buildVeterinaryResearchStudyAccessScope(researchStudyId) {
     return `organization/ResearchSubject.crus?study=ResearchStudy/${boundedId(researchStudyId)}`;
@@ -411,9 +452,17 @@ function boundedId(value) {
     return id;
 }
 function boundedStudyUuid(value) {
+    try {
+        return normalizedUuid(value);
+    }
+    catch {
+        throw new TypeError('veterinary_research_study_review_team_study_id_invalid');
+    }
+}
+function normalizedUuid(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');
+        throw new TypeError('uuid_invalid');
     }
     return uuid;
 }

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

@@ -18,6 +18,7 @@ related to the exact ResearchStudy. Whole-twin delete is absent.
 ```ts
 import {
   buildVeterinaryResearchStudyActiveConsentBatch,
+  buildVeterinaryResearchStudyCreateWorkflowIds,
   buildVeterinaryResearchStudyGroupBatch,
   buildVeterinaryResearchStudyGroupCreateEntry,
   buildVeterinaryResearchStudyGroupMemberPatchEntries,
@@ -25,9 +26,13 @@ import {
   buildVeterinaryResearchStudySmartAuthorization,
 } from 'vet-sdk-core-ts/research-study'
 
-const researchGroupId = 'review-team'
+const workflowIds = buildVeterinaryResearchStudyCreateWorkflowIds({
+  operationId: crypto.randomUUID(),
+  practitionerRoleReferences: associatedParties.map(({ party }) => party.reference),
+})
+const researchGroupId = workflowIds.groupId
 const groupCreate = buildVeterinaryResearchStudyGroupCreateEntry({
-  researchStudyId: study.id,
+  researchStudyId: workflowIds.researchStudyId,
   group: {
     resourceType: 'Group',
     id: researchGroupId,
@@ -44,13 +49,13 @@ const groupBatch = buildVeterinaryResearchStudyGroupBatch([groupCreate, ...membe
 // The protected controller BFF submits `groupBatch`; membership grants no access.
 
 const invitations = buildVeterinaryResearchStudyPartyInvitations({
-  researchStudyId: study.id,
+  researchStudyId: workflowIds.researchStudyId,
   controllerReference: organizationReference,
   sentAt: new Date().toISOString(),
   invitations: associatedParties.map((associatedParty, index) => ({
     associatedParty,
-    communicationId: communicationIds[index],
-    consentId: draftConsentIds[index],
+    communicationId: workflowIds.invitations[index].communicationId,
+    consentId: workflowIds.invitations[index].consentId,
   })),
 })
 
@@ -64,7 +69,7 @@ for (const communication of invitations) {
 // is separate from the draft inside Communication and is the actual grant.
 const activeConsentBatch = buildVeterinaryResearchStudyActiveConsentBatch([{
   consentId: activeConsentId,
-  researchStudyId: study.id,
+  researchStudyId: workflowIds.researchStudyId,
   practitionerRoleId: protectedProfessional.practitionerRoleId,
   actorRole: protectedProfessional.iscoRole,
   date: new Date().toISOString().slice(0, 10),
@@ -75,13 +80,20 @@ const activeConsentBatch = buildVeterinaryResearchStudyActiveConsentBatch([{
 // This succeeds only after protected state proves both prerequisites. Browser
 // input must not be trusted as that proof.
 const authorization = buildVeterinaryResearchStudySmartAuthorization({
-  researchStudyId: study.id,
+  researchStudyId: workflowIds.researchStudyId,
   dcrCompleted: protectedProfessional.dcrCompleted,
   consentStatus: protectedStudyConsent.status,
 })
 await professionalRuntime.requestSmartToken(authorization)
 ```
 
+Persist the client-generated `operationId` with the UI operation state. A
+retry passes the same UUID and the same set of exact PractitionerRole
+references, producing the same ResearchStudy, Group, Communication and draft
+Consent identifiers. This enables an idempotent, resumable saga after a
+partial failure. It does not create a transaction across services, roll back
+completed steps, or authorize any professional.
+
 The controller may independently create a descriptive review team with
 `buildVeterinaryResearchStudyGroupCreateEntry()` and append each registered
 `PractitionerRole` with
@@ -129,7 +141,7 @@ Consent claims use:
 
 The Group POST adds a governed business `Group.identifier` derived from the
 ResearchStudy UUID. Use
-`buildVeterinaryResearchStudyReviewTeamGroupSearch(study.id)` to recover the
+`buildVeterinaryResearchStudyReviewTeamGroupSearch(workflowIds.researchStudyId)` 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

package/package.json

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