@openedc/sdk 3.8.1

package/README.md

@@ -0,0 +1,189 @@
+<br>
+<div align="center">
+<img src="../public/icons/custom/openedc.svg" alt="OpenEDC Logo" width="48">
+
+### SDK for the OpenEDC Health Platform
+#### OpenEDC Health is a modular, standards-compliant platform for medical research
+</div>
+<br>
+
+The official TypeScript SDK for the OpenEDC Health Platform — a modular, standards-compliant platform for medical research.
+
+Fully typed end-to-end, it runs on any modern JavaScript runtime (Node, Deno, Bun) and gives you a clean, expressive API to work with all aspects of a clinical study:
+
+- **Query** metadata, clinical data, administrative data, and more — with filtering, sorting, and cross-project support
+- **Mutate** study data with a single `.commit()` call, including cascading saves across related records
+- **Stream live updates** via reactive queries that automatically reflect changes in real time
+- **Track changes** with a built-in audit trail for all relevant study data
+- **Manage files** with resumable uploads and signed downloads, supporting files up to 5 GB
+
+## Getting started
+
+### Installation
+
+```sh
+# npm
+npm install @openedc/sdk
+
+# pnpm / yarn / bun
+pnpm add @openedc/sdk
+
+# Deno
+deno add npm:@openedc/sdk
+```
+
+### Initialization
+
+```ts
+import { login, logout } from "@openedc/sdk";
+
+const user = await login({
+    serverUrl: "server-base-url",
+    apiKey: "your-api-key"
+});
+
+await logout();
+```
+
+## Usage
+
+### Data querying, creation, and modification
+
+#### Explicit project scope
+
+```ts
+import { Project, Location, SubjectData } from "@openedc/sdk";
+
+// Get project by name
+const project = await Project
+    .where({ name: "Exemplary study" })
+    .first();
+
+// Get the first location
+const location = await Location
+    .where()
+    .project(project)
+    .first();
+
+// Get all subjects from a location sorted by creation
+const subjects = await SubjectData
+    .where({ location })
+    .project(project)
+    .sort("createdDate")
+    .asc().all();
+
+// Create a new subject within a location
+const subject = await new SubjectData("Patient-001", location.reference)
+    .commit({ project });
+
+// Update an existing subject (no need to specify the project again)
+subject.subjectKey = "Patient-002";
+await subject.commit();
+
+// Alternatively, use .set() for a single expression
+await subject.set({ subjectKey: "Patient-003" }).commit();
+```
+
+#### Global project scope
+
+```ts
+import { Location, SubjectData } from "@openedc/sdk";
+
+// Instead of specifying the project for each query or commit, it can also be scoped globally for
+// all upcoming statements. This can be changed at any time but shouldn't be used when handling
+// multiple projects at the same time. Will be assumed to be set for the rest of the examples.
+scope(project);
+
+const sameLocation = await Location
+    .where()
+    .first();
+
+const sameSubjects = await SubjectData
+    .where({ location })
+    .sort("createdDate")
+    .asc().all();
+
+// Create a new subject (note that Patient-003 would result in a unique constraint violation)
+const newSubject = await new SubjectData("Patient-004").commit();
+```
+
+#### Clinical data retrieval
+
+```ts
+import { ItemGroupDef, ItemDef, ItemData } from "@openedc/sdk";
+
+// Get data for specific subject and form (project-scoped from above)
+const form = await ItemGroupDef
+    .where({
+        type: "Form",
+        name: "Demographics"
+    })
+    .first();
+
+const formData = await ItemData
+    .where({
+        subject,
+        formOID: form?.oid
+    })
+    .all();
+
+// Get data for specific subject, form, and item (using a form-scoped local search)
+const item = form?.find(ItemDef, "name", "Gender");
+
+const itemData = await ItemData
+    .where({
+        subject,
+        formOID: form?.oid,
+        itemOID: item?.oid
+    })
+    .all();
+```
+
+### Live queries
+
+```ts
+// Subscribe to subject changes with a live query
+await SubjectData.where({ location }).all((_, subject, method) => {
+    console.log(`Subject ${subject.subjectKey} was ${method} in ${location.name}.`);
+});
+```
+
+```ts
+// Subscribe to item data changes via the form status as proxy
+await FormStatus.where().all(async (_, status) => {
+    const subject = await status.subject.data;
+    const items = await ItemData.where(ODMPath.with(status).toObject()).all();
+    console.log(`Updated form with ${items.length} items for subject ${subject.subjectKey}.`);
+});
+```
+
+### Audit trail
+
+```ts
+// Get the audit trail of all subjects within a project
+const auditTrailSubjects = await SubjectData.where().audit();
+
+// Get the audit trail of all item data of a given subject
+const auditTrailItemsBySubject = await ItemData.where({ subject }).audit();
+```
+
+### File management
+
+```ts
+// 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();
+const fileContent = await new FileContent(fileMetadata.reference, file).commit();
+
+// Track upload progress in real time
+await fileContent.upload(progress => {
+    console.log(`Upload progress: ${progress * 100}`);
+});
+```
+
+```ts
+// Download a file
+const downloadMetadata = await FileMetadata.where({ fileName: "file.txt" }).first();
+const downloadContent = await FileContent.where({ metadata: downloadMetadata }).first();
+const downloadURL = await downloadContent?.getUrl();
+```