@openedc/sdk 3.8.1 → 3.8.2-next.1

package/README.md

@@ -1,21 +1,26 @@
 <br>
 <div align="center">
-<img src="../public/icons/custom/openedc.svg" alt="OpenEDC Logo" width="48">
+<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
 </div>
 <br>
 
-The official TypeScript SDK for the OpenEDC Health Platform — a modular, standards-compliant platform for medical research.
+The official TypeScript SDK for the OpenEDC Health Platform.
 
 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
+- **Data access:** Query study metadata, clinical data, administrative data, and more, with flexible filtering, sorting, and cross-project support
+- **Data editing:** Create or modify study data reliably with a single commit call, with all changes automatically recorded in the audit trail
+- **Audit trail:** Query the complete history of all study data changes, supporting data integrity and GCP compliance
+- **Live updates:** Subscribe to real-time changes via live queries that automatically reflect updates as they happen
+- **File management:** Upload and download files securely with resumable transfers, supporting files up to 5 GB
+
+The OpenEDC Health platform and the SDK are built around PostgreSQL Row Level Security (RLS) Policies and Triggers. This ensures that:
+
+- **Scoped access:** Only the projects and data the authenticated user has been granted access to can be read or modified through the SDK
+- **Automated records:** All data changes are automatically recorded in the audit trail, attributed to the user with a server-side timestamp
 
 ## Getting started
 
@@ -34,6 +39,12 @@ deno add npm:@openedc/sdk
 
 ### Initialization
 
+Before you can authenticate within the SDK, please create an API key in the OpenEDC Health application. Click on your name in the bottom-left corner, select *Account*, and then create an API key at the bottom of the dialog.
+
+![API key creation](https://cappie.studio/images/74d309b5-ee64-4302-9a5c-3b33df49ede4.jpg)
+
+The API key can then be used as shown below.
+
 ```ts
 import { login, logout } from "@openedc/sdk";
 
@@ -69,8 +80,8 @@ const location = await Location
 const subjects = await SubjectData
     .where({ location })
     .project(project)
-    .sort("createdDate")
-    .asc().all();
+    .sort("createdDate").asc()
+    .all();
 
 // Create a new subject within a location
 const subject = await new SubjectData("Patient-001", location.reference)
@@ -86,12 +97,12 @@ 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.
+
 ```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 subsequent queries and commits
 scope(project);
 
 const sameLocation = await Location
@@ -100,8 +111,8 @@ const sameLocation = await Location
 
 const sameSubjects = await SubjectData
     .where({ location })
-    .sort("createdDate")
-    .asc().all();
+    .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();

package/openedc-sdk.js

@@ -10636,11 +10636,13 @@ const kt = class kt {
       const [o, ...a] = s.split("."), u = a.at(0) === "ref" ? this.getLocalization(o, { locale: n, interpolation: r }) : r == null ? void 0 : r[o];
       return String(a.reduce(
         (c, h) => this.transform(c, h, n),
-        u ?? "—"
+        u
       ));
     });
   }
   static transform(e, r, n) {
+    if (e == null || e === "")
+      return "—";
     switch (r) {
       case "upper":
         return String(e).toUpperCase();
@@ -10663,7 +10665,7 @@ const kt = class kt {
     }
   }
 };
-kt.SELECTED_LANGUAGE = "SELECTED_LANGUAGE", kt.translationGlob = {}, kt.defaults = {}, kt.overwrites = {}, kt.localizedElements = /* @__PURE__ */ new Map(), kt.defaultLocale = new Intl.Locale("en"), kt.currentLocale = kt.defaultLocale;
+kt.SELECTED_LANGUAGE = "SELECTED_LANGUAGE", kt.defaults = {}, kt.overwrites = {}, kt.defaultLocale = new Intl.Locale("en"), kt.currentLocale = kt.defaultLocale, kt.translationGlob = {}, kt.localizedElements = /* @__PURE__ */ new Map();
 let ye = kt;
 var _p = Object.defineProperty, Ep = Object.getOwnPropertyDescriptor, Ur = (t, e, r, n) => {
   for (var i = n > 1 ? void 0 : n ? Ep(e, r) : e, s = t.length - 1, o; s >= 0; s--)
@@ -20777,7 +20779,7 @@ const xD = async ({ serverUrl: t, apiKey: e }) => {
       }
     }
   });
-  const s = await fetch(t + "/api/auth/api-key", {
+  const s = await fetch(t + "/api/auth/token", {
     method: "POST",
     headers: {
       Authorization: `Bearer ${e}`
@@ -20786,9 +20788,10 @@ const xD = async ({ serverUrl: t, apiKey: e }) => {
   if (!s.ok) throw new Error("Invalid API key");
   const { email: o, token: a, type: u } = await s.json(), { data: c, error: h } = await Yn.auth.verifyOtp({ email: o, token: a, type: u });
   if (!c.user) throw h ?? new Error("Error during OTP verification");
+  Ps.supabaseClient = Yn, V.adapter = Ps;
   const f = await ((d = ke.fromString(c.user.app_metadata.user)) == null ? void 0 : d.data);
   if (!f) throw new Error("User not found");
-  return Ps.supabaseClient = Yn, V.adapter = Ps, f;
+  return f;
 }, TD = async () => {
   await Yn.auth.signOut();
 }, FD = (t) => {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@openedc/sdk",
-    "version": "3.8.1",
+    "version": "3.8.2-next.1",
     "description": "TypeScript SDK for the OpenEDC Health Platform",
     "type": "module",
     "main": "./openedc-sdk.js",