vet-sdk-core-ts 0.4.10 → 0.4.12

package/README.md

@@ -6,6 +6,52 @@ 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.
 
+## Research studies
+
+`buildVeterinaryResearchStudyCreateEntry` preserves a native FHIR R5
+ResearchStudy and derives its standard flat search claims. Associated parties
+are retained as complete objects. Later changes use one independent PATCH
+entry per party, so the party reference, role, periods and classifiers cannot
+be mixed across employees. `buildVeterinaryResearchStudyBatch` wraps these
+entries in JSON:API `data[]` for GW VET.
+
+Study participation does not itself authorize access. The separate
+`buildVeterinaryResearchStudySmartAuthorization` request is limited to create,
+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`. 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
+an `application/fhir+json` batch Bundle with exactly one draft Consent, scoped
+to the ResearchStudy through `Consent.provision.data.reference` and to
+`ResearchSubject` through `Consent.provision.resourceType`. The draft requests
+only create, read, update and search. It contains no delete permission and
+never authorizes SMART access.
+
+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).
+
+FHIR references:
+
+- https://hl7.org/fhir/R5/researchstudy.html
+- https://hl7.org/fhir/R5/researchsubject-search.html
+- https://hl7.org/fhir/R5/communication.html
+- https://hl7.org/fhir/R5/consent-definitions.html
+
 ## Reusable professional BFF
 
 `ReusableProfessionalBffClient` exposes the complete business-level portal

package/dist/index.d.ts

@@ -4,4 +4,5 @@ export * from "./gateway-contract.js";
 export * from "./card-issuance.js";
 export * from "./animal-onboarding.js";
 export * from "./reusable-bff.js";
+export * from "./research-study.js";
 export * from "vet-data-utils-ts";

package/dist/index.js

@@ -4,4 +4,5 @@ export * from "./gateway-contract.js";
 export * from "./card-issuance.js";
 export * from "./animal-onboarding.js";
 export * from "./reusable-bff.js";
+export * from "./research-study.js";
 export * from "vet-data-utils-ts";

package/dist/research-study.d.ts

@@ -0,0 +1,222 @@
+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: 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;
+    type?: string;
+}>;
+type FhirCoding = Readonly<{
+    system: string;
+    code: string;
+}>;
+type FhirCodeableConcept = Readonly<{
+    coding: readonly FhirCoding[];
+}>;
+export type VeterinaryResearchStudyDraftConsent = Readonly<{
+    resourceType: 'Consent';
+    id: string;
+    status: 'draft';
+    grantor: readonly FhirReference[];
+    controller: readonly FhirReference[];
+    grantee: readonly FhirReference[];
+    decision: 'permit';
+    provision: readonly Readonly<{
+        actor: readonly Readonly<{
+            reference: FhirReference;
+        }>[];
+        action: readonly FhirCodeableConcept[];
+        purpose: readonly FhirCoding[];
+        resourceType: readonly FhirCoding[];
+        data: readonly Readonly<{
+            meaning: 'related';
+            reference: FhirReference;
+        }>[];
+    }>[];
+    meta: Readonly<{
+        claims: Readonly<Record<string, string>>;
+    }>;
+}>;
+export type VeterinaryResearchStudyInvitationBundle = Readonly<{
+    resourceType: 'Bundle';
+    type: 'batch';
+    entry: readonly Readonly<{
+        fullUrl: string;
+        resource: VeterinaryResearchStudyDraftConsent;
+        request: Readonly<{
+            method: 'POST';
+            url: 'Consent';
+        }>;
+    }>[];
+}>;
+export type VeterinaryResearchStudyPartyInvitation = Readonly<{
+    resourceType: 'Communication';
+    id: string;
+    status: 'completed';
+    category: readonly FhirCodeableConcept[];
+    topic: FhirCodeableConcept;
+    about: readonly FhirReference[];
+    recipient: readonly FhirReference[];
+    sender: FhirReference;
+    sent?: string;
+    payload: readonly Readonly<{
+        contentAttachment: Readonly<{
+            contentType: 'application/fhir+json';
+            title: 'research-study-draft-consent.json';
+            data: string;
+        }>;
+    }>[];
+}>;
+export type VeterinaryResearchStudyResource = Readonly<{
+    resourceType: 'ResearchStudy';
+    id: string;
+    status?: 'draft' | 'active' | 'retired' | 'unknown';
+    associatedParty?: readonly ResearchStudyAssociatedParty[];
+    meta?: Readonly<Record<string, unknown>>;
+    [key: string]: unknown;
+}>;
+export type VeterinaryResearchStudyCreateResource = VeterinaryResearchStudyResource & Readonly<{
+    status: NonNullable<VeterinaryResearchStudyResource['status']>;
+}>;
+export type VeterinaryResearchStudyBatchEntry = Readonly<{
+    type: 'ResearchStudy-v5.0.0';
+    resource: VeterinaryResearchStudyResource;
+    request: Readonly<{
+        method: 'POST' | 'PATCH';
+        url: string;
+    }>;
+}>;
+export type VeterinaryResearchStudyBatch = Readonly<{
+    data: readonly VeterinaryResearchStudyBatchEntry[];
+}>;
+export type VeterinaryResearchStudySmartAuthorization = Readonly<{
+    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;
+ * it must never be represented as deleting the ResearchSubject/twin itself.
+ */
+export declare function buildVeterinaryResearchStudySmartAuthorization(input: Readonly<{
+    researchStudyId: string;
+    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;
+}>): VeterinaryResearchStudyBatchEntry;
+/**
+ * Builds one independent `_batch` PATCH entry per R5 associatedParty. Keeping
+ * each complete party in its own entry prevents roles, periods and classifiers
+ * from being correlated with the wrong PractitionerRole. These entries update
+ * study membership only; they do not grant CRUDS access.
+ */
+export declare function buildVeterinaryResearchStudyPartyPatchEntries(input: Readonly<{
+    researchStudyId: string;
+    associatedParties: unknown;
+}>): readonly VeterinaryResearchStudyBatchEntry[];
+/**
+ * Builds the auditable R5 invitation sent to one ResearchStudy associated
+ * party. The Communication payload is an `application/fhir+json` attachment
+ * containing a batch Bundle with exactly one `Consent.status = draft`.
+ * Draft is descriptive only and can never satisfy authorization. The invitee
+ * must finish DCR and a controller must later persist a separate active
+ * Consent before the study-scoped SMART request can succeed.
+ *
+ * Native R5 fields retain the exact study boundary in
+ * `Consent.provision.data.reference` and the affected `ResearchSubject`
+ * resource family. Project authorization actions remain create/read/update/
+ * search; their FHIR representation uses the matching REST interaction codes,
+ * where search is `search-type`. Delete is deliberately absent.
+ *
+ * @see https://hl7.org/fhir/R5/communication.html
+ * @see https://hl7.org/fhir/R5/consent.html
+ * @see https://hl7.org/fhir/R5/codesystem-restful-interaction.html
+ */
+export declare function buildVeterinaryResearchStudyPartyInvitation(input: Readonly<{
+    researchStudyId: string;
+    associatedParty: ResearchStudyAssociatedParty;
+    controllerReference: string;
+    communicationId: string;
+    consentId: string;
+    sentAt?: string;
+}>): VeterinaryResearchStudyPartyInvitation;
+/**
+ * Builds one isolated Communication/draft-Consent pair for every associated
+ * party. Callers provide the auditable identifiers; no identifier, recipient,
+ * or Consent is shared across invitations.
+ */
+export declare function buildVeterinaryResearchStudyPartyInvitations(input: Readonly<{
+    researchStudyId: string;
+    controllerReference: string;
+    sentAt?: string;
+    invitations: readonly Readonly<{
+        associatedParty: ResearchStudyAssociatedParty;
+        communicationId: string;
+        consentId: string;
+    }>[];
+}>): readonly VeterinaryResearchStudyPartyInvitation[];
+/** Decodes the single attached Consent Bundle after validating its boundary. */
+export declare function decodeVeterinaryResearchStudyInvitationBundle(communication: VeterinaryResearchStudyPartyInvitation): VeterinaryResearchStudyInvitationBundle;
+export {};

package/dist/research-study.js

@@ -0,0 +1,381 @@
+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([
+    'create',
+    'read',
+    'update',
+    'search',
+]);
+export const VeterinaryResearchStudyInvitationClaimNames = Object.freeze({
+    Context: '@context',
+    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;
+ * it must never be represented as deleting the ResearchSubject/twin itself.
+ */
+export function buildVeterinaryResearchStudySmartAuthorization(input) {
+    if (input.consentStatus !== 'active') {
+        throw new TypeError('veterinary_research_study_active_consent_required');
+    }
+    if (input.dcrCompleted !== true) {
+        throw new TypeError('veterinary_research_study_dcr_required');
+    }
+    const researchStudyReference = `ResearchStudy/${boundedId(input.researchStudyId)}`;
+    return deepFreeze({
+        purpose: HealthcareConsentPurposes.Research,
+        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) {
+    if (!Array.isArray(entries) || entries.length === 0)
+        throw new TypeError('veterinary_research_study_batch_empty');
+    return deepFreeze({ data: entries.map(entry => clonePlain(entry)) });
+}
+export function buildVeterinaryResearchStudyCreateEntry(input) {
+    const study = normalizedStudy(input.study);
+    return deepFreeze({
+        type: 'ResearchStudy-v5.0.0',
+        resource: withProjectedClaims(study),
+        request: { method: 'POST', url: 'ResearchStudy' },
+    });
+}
+/**
+ * Builds one independent `_batch` PATCH entry per R5 associatedParty. Keeping
+ * each complete party in its own entry prevents roles, periods and classifiers
+ * from being correlated with the wrong PractitionerRole. These entries update
+ * study membership only; they do not grant CRUDS access.
+ */
+export function buildVeterinaryResearchStudyPartyPatchEntries(input) {
+    const id = boundedId(input.researchStudyId);
+    const parties = normalizeResearchStudyAssociatedParties(input.associatedParties);
+    return deepFreeze(parties.map(party => ({
+        type: 'ResearchStudy-v5.0.0',
+        resource: withProjectedClaims({
+            resourceType: 'ResearchStudy',
+            id,
+            associatedParty: [party],
+        }),
+        request: { method: 'PATCH', url: `ResearchStudy/${id}` },
+    })));
+}
+/**
+ * Builds the auditable R5 invitation sent to one ResearchStudy associated
+ * party. The Communication payload is an `application/fhir+json` attachment
+ * containing a batch Bundle with exactly one `Consent.status = draft`.
+ * Draft is descriptive only and can never satisfy authorization. The invitee
+ * must finish DCR and a controller must later persist a separate active
+ * Consent before the study-scoped SMART request can succeed.
+ *
+ * Native R5 fields retain the exact study boundary in
+ * `Consent.provision.data.reference` and the affected `ResearchSubject`
+ * resource family. Project authorization actions remain create/read/update/
+ * search; their FHIR representation uses the matching REST interaction codes,
+ * where search is `search-type`. Delete is deliberately absent.
+ *
+ * @see https://hl7.org/fhir/R5/communication.html
+ * @see https://hl7.org/fhir/R5/consent.html
+ * @see https://hl7.org/fhir/R5/codesystem-restful-interaction.html
+ */
+export function buildVeterinaryResearchStudyPartyInvitation(input) {
+    const researchStudyReference = `ResearchStudy/${boundedId(input.researchStudyId)}`;
+    let party;
+    try {
+        party = normalizeResearchStudyAssociatedParties([input.associatedParty])[0];
+    }
+    catch {
+        throw new TypeError('veterinary_research_study_invitation_party_invalid');
+    }
+    const partyReference = String(party?.party?.reference || '').trim();
+    if (!partyReference.startsWith('PractitionerRole/')) {
+        throw new TypeError('veterinary_research_study_invitation_party_invalid');
+    }
+    const controllerReference = boundedReference(input.controllerReference, 'Organization');
+    const communicationId = boundedId(input.communicationId);
+    const consentId = boundedId(input.consentId);
+    const topic = VeterinaryResearchCommunicationTopics[0];
+    if (!topic)
+        throw new TypeError('veterinary_research_study_invitation_topic_unavailable');
+    const consent = {
+        resourceType: 'Consent',
+        id: consentId,
+        status: 'draft',
+        grantor: [{ reference: controllerReference, type: 'Organization' }],
+        controller: [{ reference: controllerReference, type: 'Organization' }],
+        grantee: [{ reference: partyReference, type: 'PractitionerRole' }],
+        decision: 'permit',
+        provision: [{
+                actor: [{ reference: { reference: partyReference, type: 'PractitionerRole' } }],
+                action: VeterinaryResearchStudyPermissionActions.map(action => ({
+                    coding: [{
+                            system: FHIR_RESTFUL_INTERACTION_SYSTEM,
+                            code: action === 'search' ? 'search-type' : action,
+                        }],
+                })),
+                purpose: [{ system: topic.system, code: topic.code }],
+                resourceType: [{ system: FHIR_RESOURCE_TYPES_SYSTEM, code: 'ResearchSubject' }],
+                data: [{ meaning: 'related', reference: { reference: researchStudyReference, type: 'ResearchStudy' } }],
+            }],
+        meta: {
+            claims: {
+                [VeterinaryResearchStudyInvitationClaimNames.Context]: 'org.hl7.fhir.api',
+                [VeterinaryResearchStudyInvitationClaimNames.Status]: 'draft',
+                [VeterinaryResearchStudyInvitationClaimNames.Decision]: 'permit',
+                [VeterinaryResearchStudyInvitationClaimNames.ActorIdentifier]: partyReference,
+                [VeterinaryResearchStudyInvitationClaimNames.Purpose]: topic.value,
+                [VeterinaryResearchStudyInvitationClaimNames.Action]: VeterinaryResearchStudyPermissionActions.join(','),
+                [VeterinaryResearchStudyInvitationClaimNames.ResourceType]: 'ResearchSubject',
+            },
+        },
+    };
+    const bundle = {
+        resourceType: 'Bundle',
+        type: 'batch',
+        entry: [{
+                fullUrl: `urn:uuid:${consentId}`,
+                resource: consent,
+                request: { method: 'POST', url: 'Consent' },
+            }],
+    };
+    const category = VeterinaryCommunicationPresetFilters.ResearchAgreements.categories[0];
+    const [categorySystem, categoryCode] = splitCodingToken(category);
+    const sent = optionalInstant(input.sentAt);
+    return deepFreeze({
+        resourceType: 'Communication',
+        id: communicationId,
+        status: 'completed',
+        category: [{ coding: [{ system: categorySystem, code: categoryCode }] }],
+        topic: { coding: [{ system: topic.system, code: topic.code }] },
+        about: [{ reference: researchStudyReference, type: 'ResearchStudy' }],
+        recipient: [{ reference: partyReference, type: 'PractitionerRole' }],
+        sender: { reference: controllerReference, type: 'Organization' },
+        ...(sent ? { sent } : {}),
+        payload: [{
+                contentAttachment: {
+                    contentType: 'application/fhir+json',
+                    title: 'research-study-draft-consent.json',
+                    data: encodeJsonBase64(bundle),
+                },
+            }],
+    });
+}
+/**
+ * Builds one isolated Communication/draft-Consent pair for every associated
+ * party. Callers provide the auditable identifiers; no identifier, recipient,
+ * or Consent is shared across invitations.
+ */
+export function buildVeterinaryResearchStudyPartyInvitations(input) {
+    if (!Array.isArray(input.invitations) || input.invitations.length === 0) {
+        throw new TypeError('veterinary_research_study_invitations_empty');
+    }
+    return deepFreeze(input.invitations.map(invitation => buildVeterinaryResearchStudyPartyInvitation({
+        researchStudyId: input.researchStudyId,
+        controllerReference: input.controllerReference,
+        sentAt: input.sentAt,
+        ...invitation,
+    })));
+}
+/** Decodes the single attached Consent Bundle after validating its boundary. */
+export function decodeVeterinaryResearchStudyInvitationBundle(communication) {
+    const attachment = communication?.payload?.[0]?.contentAttachment;
+    if (communication?.resourceType !== 'Communication'
+        || attachment?.contentType !== 'application/fhir+json'
+        || !attachment.data) {
+        throw new TypeError('veterinary_research_study_invitation_bundle_invalid');
+    }
+    const decoded = JSON.parse(decodeJsonBase64(attachment.data));
+    if (decoded?.resourceType !== 'Bundle'
+        || decoded.type !== 'batch'
+        || decoded.entry?.length !== 1
+        || decoded.entry[0]?.resource?.resourceType !== 'Consent'
+        || decoded.entry[0].resource.status !== 'draft') {
+        throw new TypeError('veterinary_research_study_invitation_bundle_invalid');
+    }
+    return deepFreeze(decoded);
+}
+function normalizedStudy(input) {
+    if (!input || input.resourceType !== 'ResearchStudy')
+        throw new TypeError('veterinary_research_study_invalid');
+    const source = clonePlain(input);
+    const id = boundedId(input.id);
+    const status = String(input.status || '');
+    if (!['draft', 'active', 'retired', 'unknown'].includes(status)) {
+        throw new TypeError('veterinary_research_study_status_invalid');
+    }
+    const associatedParty = input.associatedParty === undefined
+        ? undefined
+        : normalizeResearchStudyAssociatedParties(input.associatedParty);
+    return deepFreeze({
+        ...source,
+        id,
+        status: status,
+        ...(associatedParty ? { associatedParty } : {}),
+    });
+}
+function clonePlain(value) {
+    if (Array.isArray(value))
+        return value.map(clonePlain);
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([key, nested]) => [key, clonePlain(nested)]));
+    }
+    return value;
+}
+function withProjectedClaims(study) {
+    const standardClaims = projectResearchStudyR5SearchClaims(study);
+    const partyClaims = aggregatePartyClaims(study.associatedParty || []);
+    return deepFreeze({
+        ...study,
+        meta: {
+            ...(study.meta || {}),
+            claims: { ...standardClaims, ...partyClaims },
+        },
+    });
+}
+function aggregatePartyClaims(parties) {
+    const output = {};
+    for (const projection of projectResearchStudyAssociatedPartyClaims(parties)) {
+        for (const [name, values] of Object.entries(projection.claims)) {
+            if (values.length > 0)
+                (output[name] || (output[name] = [])).push(...values);
+        }
+    }
+    return Object.fromEntries(Object.entries(output).map(([name, values]) => [name, Object.freeze([...values])]));
+}
+function boundedId(value) {
+    const id = String(value || '').trim();
+    if (!/^[A-Za-z0-9\-.]{1,64}$/.test(id))
+        throw new TypeError('veterinary_research_study_id_invalid');
+    return id;
+}
+function boundedReference(value, resourceType) {
+    const reference = String(value || '').trim();
+    const prefix = `${resourceType}/`;
+    if (!reference.startsWith(prefix))
+        throw new TypeError('veterinary_research_study_reference_invalid');
+    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)
+        return undefined;
+    if (!Number.isFinite(Date.parse(instant)))
+        throw new TypeError('veterinary_research_study_invitation_sent_invalid');
+    return instant;
+}
+function splitCodingToken(value) {
+    const separator = value.lastIndexOf('|');
+    if (separator < 1 || separator === value.length - 1) {
+        throw new TypeError('veterinary_research_study_invitation_category_invalid');
+    }
+    return [value.slice(0, separator), value.slice(separator + 1)];
+}
+function encodeJsonBase64(value) {
+    const bytes = new TextEncoder().encode(JSON.stringify(value));
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary);
+}
+function decodeJsonBase64(value) {
+    const binary = atob(value);
+    const bytes = Uint8Array.from(binary, character => character.charCodeAt(0));
+    return new TextDecoder().decode(bytes);
+}
+function deepFreeze(value, seen = new WeakSet()) {
+    if (!value || typeof value !== 'object' || seen.has(value))
+        return value;
+    seen.add(value);
+    for (const nested of Object.values(value))
+        deepFreeze(nested, seen);
+    return Object.freeze(value);
+}

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

@@ -0,0 +1,88 @@
+# ResearchStudy party invitations
+
+This SDK separates study membership, an invitation, and authorization. They
+are three different facts:
+
+1. `ResearchStudy.associatedParty` records who is expected to collaborate.
+2. One R5 `Communication` invites that exact `PractitionerRole` and carries a
+   batch Bundle with one `Consent.status = draft`.
+3. Only after the professional completes DCR and the controller persists a
+   later `Consent.status = active` may the professional request the
+   study-scoped SMART authorization.
+
+A draft Consent is inbox/audit evidence. It never grants access. The requested
+operations are create, read, update and search for `ResearchSubject` resources
+related to the exact ResearchStudy. Whole-twin delete is absent.
+
+```ts
+import {
+  buildVeterinaryResearchStudyActiveConsentBatch,
+  buildVeterinaryResearchStudyPartyInvitations,
+  buildVeterinaryResearchStudySmartAuthorization,
+} from 'vet-sdk-core-ts/research-study'
+
+const invitations = buildVeterinaryResearchStudyPartyInvitations({
+  researchStudyId: study.id,
+  controllerReference: organizationReference,
+  sentAt: new Date().toISOString(),
+  invitations: associatedParties.map((associatedParty, index) => ({
+    associatedParty,
+    communicationId: communicationIds[index],
+    consentId: draftConsentIds[index],
+  })),
+})
+
+// Persist each Communication through the protected BFF/runtime. Its attached
+// draft Consent remains non-authorizing while the recipient completes DCR.
+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({
+  researchStudyId: study.id,
+  dcrCompleted: protectedProfessional.dcrCompleted,
+  consentStatus: protectedStudyConsent.status,
+})
+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:
+
+- `Consent.grantee` and `Consent.provision.actor` for the invited
+  `PractitionerRole`;
+- `Consent.grantor` and `Consent.controller` for the controller organization;
+- `Consent.provision.purpose` with HL7 v3 ActReason `HRESCH`;
+- `Consent.provision.resourceType` for `ResearchSubject`;
+- `Consent.provision.data.reference` for the exact `ResearchStudy/{id}`;
+- FHIR REST interaction codes `create`, `read`, `update`, and `search-type`.
+
+FHIR R5 references:
+
+- [ResearchStudy](https://hl7.org/fhir/R5/researchstudy.html)
+- [Communication](https://hl7.org/fhir/R5/communication.html)
+- [Consent](https://hl7.org/fhir/R5/consent.html)
+- [RESTful interaction codes](https://hl7.org/fhir/R5/codesystem-restful-interaction.html)
+- [Communication category](https://www.hl7.org/fhir/valueset-communication-category.html)
+- [HL7 v3 ActReason](http://terminology.hl7.org/CodeSystem/v3-ActReason)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vet-sdk-core-ts",
-  "version": "0.4.10",
+  "version": "0.4.12",
   "description": "Browser-safe VetChain core contracts and governed animal species identifiers",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",
@@ -35,6 +35,10 @@
     "./reusable-bff": {
       "types": "./dist/reusable-bff.d.ts",
       "default": "./dist/reusable-bff.js"
+    },
+    "./research-study": {
+      "types": "./dist/research-study.d.ts",
+      "default": "./dist/research-study.js"
     }
   },
   "files": [
@@ -59,6 +63,7 @@
   },
   "dependencies": {
     "@noble/hashes": "^2.2.0",
-    "vet-data-utils-ts": "0.4.8"
+    "gdc-common-utils-ts": "2.9.4",
+    "vet-data-utils-ts": "0.5.0"
   }
 }