@openedc/sdk 3.9.0 → 3.9.2

package/README.md

@@ -2,8 +2,9 @@
 <div align="center">
 <img src="https://openedc.health/logo.png" alt="OpenEDC Logo" width="48">
 
-### SDK for the OpenEDC Health Platform
-#### OpenEDC Health is a modular, standards-compliant platform for medical research
+### Software Development Kit (SDK) for the OpenEDC Health Platform
+#### OpenEDC Health is a modular, standards-compliant platform for clinical trials and medical research.
+#### Compliant with ICH GCP and FDA CFR Part 11. Validated following GAMP 5 guidelines.
 </div>
 <br>
 
@@ -99,7 +100,7 @@ await subject.set({ subjectKey: "Patient-003" }).commit();
 
 #### Global project scope
 
-Instead of specifying the project per call, a global scope can be set for all upcoming statements. This works well for linear, sequential flows but should be avoided in parallel or callback-based code that handles multiple projects concurrently. Assumed for the rest of the examples.
+Instead of specifying the project per call, a global scope can be set for all upcoming statements. This works well for linear, sequential flows but should be avoided in parallel or callback-based code that handles multiple projects concurrently. This scope is assumed for the rest of the examples.
 
 ```ts
 import { scope, Location, SubjectData } from "@openedc/sdk";
@@ -152,6 +153,23 @@ const itemData = await ItemData
     .all();
 ```
 
+#### Subject key rendering
+
+Full subject keys (e.g., SCREENING-MS-001) are rendered dynamically to allow updates to prefix, padding, and location settings. This requires the use of certain `SubjectData` methods to compose and render full subject keys at runtime.
+
+```ts
+import { SubjectData } from "@openedc/sdk";
+
+// Render one subject key dynamically
+const subject = await SubjectData.where().first();
+const subjectKey = await subject.getIdAsync();
+
+// Render multiple subject keys in a loop
+const subjects = await SubjectData.where().all();
+const keyOptions = await SubjectData.fetchSubjectKeyOptions();
+const subjectKeys = subjects.map(subject => subject.getId(keyOptions));
+```
+
 ### Live queries
 
 ```ts
@@ -162,6 +180,8 @@ await SubjectData.where({ location }).all((_, subject, method) => {
 ```
 
 ```ts
+import { FormStatus } from "@openedc/sdk";
+
 // Subscribe to item data changes via the form status as proxy
 await FormStatus.where().all(async (_, status) => {
     const subject = await status.subject.data;
@@ -183,6 +203,8 @@ const auditTrailItemsBySubject = await ItemData.where({ subject }).audit();
 ### File management
 
 ```ts
+import { FileMetadata, FileContent } from "@openedc/sdk";
+
 // Upload a file (only readable to users with access to the subject)
 const file = new File(["exemplary-data"], "file.txt");
 const fileMetadata = await new FileMetadata(file, subject.reference).commit();
@@ -200,3 +222,63 @@ const downloadMetadata = await FileMetadata.where({ fileName: "file.txt" }).firs
 const downloadContent = await FileContent.where({ metadata: downloadMetadata }).first();
 const downloadURL = await downloadContent?.getUrl();
 ```
+
+### Further examples
+
+<details>
+<summary>Show</summary>
+
+#### Create custom randomization schedule
+
+If you want to use a custom randomization schedule that is not yet supported by OpenEDC Health natively, you can use the SDK to upload your own schedule.
+
+For this, first create the treatment groups and randomization configuration within the web application that matches your desired configuration as good as possible (e.g., selecting a simple, permuted, or stratified block randomization and choosing stratification variables).
+
+Then, fetch the created draft randomization plan and create your schedule programmatically:
+
+```ts
+import { RandomizationPlan, RandomizationSchedule, StudyEventGroupDef } from "@openedc/sdk";
+
+// First, fetch the created draft randomization plan
+const plan = await RandomizationPlan.where().first();
+
+// Also get the list of your study arms
+const arms = await StudyEventGroupDef.where("armOID").notEquals(undefined).all();
+
+// Then, generate and commit your custom randomization schedule as a batch using these parameters:
+// new RandomizationSchedule(planReference, orderNumber, blockNumber, subjectKey, armReference).
+// In this example, 6 entries with a block size of 3 and 2 arms with 2:1 ratio are created.
+await RandomizationSchedule.commit([
+    new RandomizationSchedule(plan.reference, 0, 1, 1, arms[0].reference),
+    new RandomizationSchedule(plan.reference, 1, 1, 2, arms[0].reference),
+    new RandomizationSchedule(plan.reference, 2, 1, 3, arms[1].reference),
+    new RandomizationSchedule(plan.reference, 3, 2, 4, arms[1].reference),
+    new RandomizationSchedule(plan.reference, 4, 2, 5, arms[0].reference),
+    new RandomizationSchedule(plan.reference, 5, 2, 6, arms[0].reference)
+]);
+
+// Finally, update the plan status to be able to see and review it within OpenEDC Health
+await plan.info.set({ status: "review" }).commit();
+```
+
+When using stratification variables, you can specify them for each randomization schedule entry. During randomization, the system will then automatically draw the next available entry for the given values of the current subject.
+
+```ts
+// Specify values for one or more stratification variables (please use the actual
+// location UUID instead of munich and the actual item OID instead of gender)
+await RandomizationSchedule.commit([
+    new RandomizationSchedule(plan.reference, 0, 1, 1, arms[0].reference).set({ stratification: {
+        locationUUID: "munich",
+        gender: "female"
+    }}),
+    new RandomizationSchedule(plan.reference, 1, 1, 2, arms[0].reference).set({ stratification: {
+        locationUUID: "munich",
+        gender: "male"
+    }}),
+    // ...
+]);
+```
+
+If you want to start over, you can either delete the created randomization schedule within the OpenEDC Health application or execute `await RandomizationSchedule.where({ plan }).delete();` using the SDK.
+
+</details>

package/openedc-sdk.d.ts

@@ -231,8 +231,8 @@ declare class DataBlock {
 		refresh?: boolean;
 	}, transaction?: string): Promise<this>;
 	static commit(data: DataBlock[], project?: string, reasons?: Record<string, string>, refresh?: boolean): Promise<void>;
-	protected beforeTrigger(): Promise<void> | void;
-	protected afterTrigger(): Promise<void> | void;
+	protected beforeTrigger(changes: Record<string, unknown>): Promise<void> | void;
+	protected afterTrigger(changes: Record<string, unknown>): Promise<void> | void;
 	prepareSerialization(): Promise<void> | void;
 	discard(): Promise<void>;
 	private updateLocalQueryCache;
@@ -240,7 +240,7 @@ declare class DataBlock {
 		cascade?: boolean;
 		reason?: string;
 	}): Promise<undefined>;
-	get changedFields(): Record<string, unknown>;
+	getChanges(state?: Record<string, unknown>): Record<string, unknown>;
 	toObject(): Record<string, unknown>;
 	toString(): string;
 	clone(options?: {
@@ -642,8 +642,7 @@ export declare class ProjectUser extends DataBlock {
 	get language(): string | undefined;
 	get fullName(): string | undefined;
 	get type(): "team-member" | "study-participant";
-	getMemberNameOrSubjectId(subjects?: SubjectData[], options?: SubjectKeyOptions): string | undefined;
-	getComboboxEntry(subjects?: SubjectData[], options?: SubjectKeyOptions): {
+	getComboboxEntry(): {
 		value: string;
 		content: string;
 	};
@@ -800,6 +799,10 @@ export declare class SubjectData extends DataBlock {
 	static fetchSubjectKeyOptions(projectUUID?: string | undefined): Promise<SubjectKeyOptions>;
 	editableBy(user?: ProjectUser, action?: string): boolean | BlockReference<Location$1> | undefined;
 	viewableBy(user?: ProjectUser): boolean | BlockReference<Location$1> | undefined;
+	getComboboxEntry(options: SubjectKeyOptions): {
+		value: string;
+		content: string;
+	};
 }
 export declare class CalendarEvent extends DataBlock {
 	owner: BlockReference<User>;
@@ -871,7 +874,7 @@ export declare class Signature extends DataBlock {
 	status: typeof SignatureStatus[keyof typeof SignatureStatus];
 	lastUpdateDatetime: number;
 	constructor(signee?: BlockReference<User>, form?: BlockReference<FormStatus>, dataHash?: string);
-	beforeTrigger(): void;
+	beforeTrigger(changes: Record<string, unknown>): void;
 }
 export declare class SurveyInstance extends DataBlock {
 	id: string;
@@ -1103,12 +1106,14 @@ declare class ShareableBlock extends DataBlock {
 	sharedWithParticipants?: boolean;
 	locationsFilter?: BlockReference<Location$1>[];
 	usersFilter?: BlockReference<User>[];
+	subjectsFilter?: BlockReference<SubjectData>[];
 	collaborators?: BlockReference<User>[];
 	constructor(owner: BlockReference<User>);
-	get explicitUsers(): BlockReference<User>[];
 	userHasAccess(user?: ProjectUser, subjects?: SubjectData[]): boolean | undefined;
 	userMayEdit(user?: ProjectUser): boolean | undefined;
-	usersLocationFilter(user?: ProjectUser, subjects?: SubjectData[]): boolean | undefined;
+	usersLocationFilter(user?: ProjectUser): boolean | undefined;
+	subjectsLocationFilter(subject?: SubjectData): boolean;
+	static getWith(owner: User, recipient: BlockReference<User> | BlockReference<SubjectData>): Promise<ShareableBlock>;
 }
 export declare class MessengerChannel extends ShareableBlock {
 	title?: string;
@@ -1118,7 +1123,8 @@ export declare class ChannelMessage extends DataBlock {
 	channel: BlockReference<MessengerChannel>;
 	author: BlockReference<User>;
 	text: string;
-	constructor(channel: BlockReference<MessengerChannel>, author: BlockReference<User>, text: string);
+	participant?: BlockReference<SubjectData>;
+	constructor(channel: BlockReference<MessengerChannel>, author: BlockReference<User>, text: string, participant?: BlockReference<SubjectData>);
 }
 export declare class ChannelStatus extends DataBlock {
 	channel: BlockReference<MessengerChannel>;