@openedc/sdk 3.8.2-next.0 → 3.8.2-next.2

package/README.md

@@ -7,15 +7,20 @@
 </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";
+import { scope, 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.d.ts

@@ -196,6 +196,13 @@ export type FieldDefinition = {
 	relation?: typeof DataBlock | typeof DataBlock[];
 	delete?: "unset" | "cascade";
 };
+export type FieldsOf<T> = {
+	[K in keyof T as T[K] extends Function ? never : K]: T[K];
+};
+export type WhereValue<T> = T extends DataBlock ? T | BlockReference<T> : T extends BlockReference<infer U> ? T | U : T extends (infer E)[] ? WhereValue<E>[] : T;
+export type WhereFilter<T> = {
+	[K in keyof FieldsOf<T>]?: WhereValue<T[K]>;
+};
 declare class DataBlock {
 	static adapter: PersistenceAdapter;
 	static fields: Record<string, FieldDefinition>;
@@ -215,8 +222,8 @@ declare class DataBlock {
 	get static(): typeof DataBlock;
 	protected get children(): DataBlock[];
 	static where<T extends typeof DataBlock>(this: T): Collection<T>;
-	static where<T extends typeof DataBlock>(this: T, value: string): Where<T>;
-	static where<T extends typeof DataBlock>(this: T, value: Record<string, ExtendedKey>): Collection<T>;
+	static where<T extends typeof DataBlock>(this: T, value: keyof WhereFilter<InstanceType<T>> & string): Where<T>;
+	static where<T extends typeof DataBlock>(this: T, value: WhereFilter<InstanceType<T>>): Collection<T>;
 	commit(options?: {
 		cascade?: boolean;
 		project?: Project | string;
@@ -243,7 +250,7 @@ declare class DataBlock {
 	}, visited?: Record<string, DataBlock>): this;
 	find<T extends typeof DataBlock>(block: T, key?: string, value?: unknown, all?: boolean, visited?: Set<string>): InstanceType<T> | undefined;
 	find<T extends typeof DataBlock>(block: T, key: string | undefined, value: unknown | undefined, all: true, visited?: Set<string>): InstanceType<T>[] | undefined;
-	set(values: Partial<this>): this & Partial<this>;
+	set(values: Partial<FieldsOf<this>>): this & Partial<FieldsOf<this>>;
 	get uncommitted(): boolean;
 	get reference(): BlockReference<this>;
 	private static withCache;
@@ -801,9 +808,9 @@ export declare class CalendarEvent extends DataBlock {
 	studyEventInstance?: number;
 	name?: string;
 	description?: string;
-	private startDateUTC;
+	startDateUTC: string;
 	private startTimeUTC?;
-	private endDateUTC;
+	endDateUTC: string;
 	private endTimeUTC?;
 	shared?: boolean;
 	constructor(owner: BlockReference<User>, startDate: string);

package/openedc-sdk.js

@@ -9833,15 +9833,17 @@ const Gs = (Ve = class {
   static async rebuildBlock(e) {
     const r = Object.assign(new this(), e);
     for (const [n, i] of Object.entries(this.fields)) {
-      if (!i.relation) continue;
       const s = Reflect.get(r, n);
-      if (Array.isArray(s)) {
-        const o = s.map((u) => ke.fromString(u)).filter((u) => !!u), a = i.lazy ? o : await Promise.all(o.map((u) => u.data));
-        Reflect.set(r, n, a.filter((u) => u));
-      } else {
-        const o = ke.fromString(s), a = i.lazy ? o : await (o == null ? void 0 : o.data);
-        Reflect.set(r, n, a);
-      }
+      if (i.type === Date && s)
+        Reflect.set(r, n, new Date(s));
+      else if (i.relation)
+        if (Array.isArray(s)) {
+          const o = s.map((u) => ke.fromString(u)).filter((u) => !!u), a = i.lazy ? o : await Promise.all(o.map((u) => u.data));
+          Reflect.set(r, n, a.filter(Boolean));
+        } else {
+          const o = ke.fromString(s), a = i.lazy ? o : await (o == null ? void 0 : o.data);
+          Reflect.set(r, n, a);
+        }
     }
     return r.internal.lastState = structuredClone(e), r;
   }
@@ -10636,11 +10638,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 +10667,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--)
@@ -20766,7 +20770,7 @@ Ze = Et([
 let Yn;
 const xD = async ({ serverUrl: t, apiKey: e }) => {
   var d;
-  const r = await fetch(t + "/api/status");
+  const r = await fetch(new URL("/api/status", t));
   if (!r.ok) throw new Error("Server not available");
   const { supabaseUrl: n, supabaseKey: i } = await r.json();
   Yn = ip(n, i, {
@@ -20777,7 +20781,7 @@ const xD = async ({ serverUrl: t, apiKey: e }) => {
       }
     }
   });
-  const s = await fetch(t + "/api/auth/api-key", {
+  const s = await fetch(new URL("/api/auth/token", t), {
     method: "POST",
     headers: {
       Authorization: `Bearer ${e}`
@@ -20786,9 +20790,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.2-next.0",
+    "version": "3.8.2-next.2",
     "description": "TypeScript SDK for the OpenEDC Health Platform",
     "type": "module",
     "main": "./openedc-sdk.js",