@ovok/core 0.4.4 → 0.4.5

package/README.md

@@ -247,6 +247,45 @@ item count: access filtering can produce a short or empty page with another curs
 and `reload` start again at the first page. The hook exposes `reload` so a screen can refresh its
 alert list after `useAcknowledgeSignalsAlert` succeeds.
 
+### Raw Signals alerts
+
+`listSignalsAlerts` reads episodes and needs the project's `episodicAlerts` (409
+`signals_episodes_disabled` otherwise). To work with individual alerts instead, whether or not
+`episodicAlerts` is on, use the raw alert methods:
+
+```ts
+const open = await client.listSignalsRawAlerts({
+  acknowledged: false,
+  codes: ["8867-4", "9279-1"],
+  since: "2026-10-01T00:00:00Z",
+  limit: 50,
+});
+const alert = await client.getSignalsRawAlert(open.items[0].id);
+const acked = await client.acknowledgeSignalsRawAlert(alert.id);
+// acked.acknowledgedAt and acked.acknowledgedActor record when and by whom.
+```
+
+Each `SignalsRawAlert` carries Signals' own `id`, `createdAt` and `resolvedAt`. `status` is Signals'
+state of the reading: `ACTIVE` while it breaches, `RESOLVED` once it recovered or the alert was
+acknowledged. An alert stays open for the practitioner until it is acknowledged, so list the
+worklist with `acknowledged: false` rather than `status: "ACTIVE"`. Acknowledging resolves the
+alert, and the next breaching reading opens a new one. It is idempotent: an acknowledged alert keeps
+its first `acknowledgedAt` and `acknowledgedActor`.
+
+Filters: `status`, `acknowledged`, `patientId` (a Medplum Patient id), `codes` (LOINC codes), and
+`since` (inclusive) and `until` (exclusive) on `createdAt`, as date-times with `Z` or an offset.
+Pages hold at most 50 alerts. As with episodes, a page can be short or empty and still have a
+`nextCursor`, because alerts of residents the caller can't read are left out; page until
+`nextCursor` is null, and pass it back unchanged: it is sealed to the project.
+
+Alerts raised before a project starts acknowledging are unacknowledged too, so a new worklist
+should bound its history with `since`. Each row also carries the breaching reading (`valueNumber`
+or `valueString`), the rule's `message` and the alert's `reason`. Acknowledging a raw alert does not
+acknowledge an episode: with `episodicAlerts` on, keep a screen to one of the two. Every request is scoped to the
+caller's project and the residents their access policy allows: an alert outside that scope answers
+404, and acknowledging needs `signals_alerts:update` and update access to the resident (403 when the
+caller can only read them).
+
 ## CareHub APIs
 
 CareHub methods cover the verified `/v1/slim/*` and `/v2/slim/*` application routes for

package/dist/client/signals/methods.d.ts

@@ -1,5 +1,5 @@
 import { OvokClient } from "../ovok-client";
-import { EnableSignalsResponse, SetSignalsThresholdBody, SignalsAlert, SignalsAlertsPage, SignalsAlertsQuery, SignalsSettingsPatch, SignalsSettingsResponse, SignalsThreshold, SignalsThresholds } from "./types";
+import { EnableSignalsResponse, SetSignalsThresholdBody, SignalsAlert, SignalsAlertsPage, SignalsAlertsQuery, SignalsRawAlert, SignalsRawAlertsPage, SignalsRawAlertsQuery, SignalsSettingsPatch, SignalsSettingsResponse, SignalsThreshold, SignalsThresholds } from "./types";
 /**
  * Enables Signals for an existing patient. The operation is idempotent; retry after 409 or 503.
  * Observations saved through Ovok are forwarded by the backend, so callers should not submit
@@ -9,9 +9,21 @@ export declare function enableSignalsForPatient(this: OvokClient, patientId: str
 export declare function getSignalsThresholds(this: OvokClient, patientId: string): Promise<SignalsThresholds>;
 export declare function setSignalsThreshold(this: OvokClient, patientId: string, code: string, body: SetSignalsThresholdBody): Promise<SignalsThreshold>;
 export declare function removeSignalsThreshold(this: OvokClient, patientId: string, code: string, reason: string): Promise<void>;
-export declare function serializeSignalsAlertsQuery(query?: SignalsAlertsQuery): string;
+export declare function serializeSignalsAlertsQuery(query?: SignalsAlertsQuery | SignalsRawAlertsQuery, keys?: readonly string[]): string;
 export declare function listSignalsAlerts(this: OvokClient, query?: SignalsAlertsQuery): Promise<SignalsAlertsPage>;
 export declare function getSignalsAlert(this: OvokClient, episodeId: string): Promise<SignalsAlert>;
 export declare function acknowledgeSignalsAlert(this: OvokClient, episodeId: string): Promise<SignalsAlert>;
+/**
+ * The project's individual Signals alerts, not episodes: works whether or not the project's
+ * `episodicAlerts` is on. `acknowledged: false` lists what is still open for the practitioner.
+ */
+export declare function listSignalsRawAlerts(this: OvokClient, query?: SignalsRawAlertsQuery): Promise<SignalsRawAlertsPage>;
+export declare function getSignalsRawAlert(this: OvokClient, alertId: string): Promise<SignalsRawAlert>;
+/**
+ * Acknowledges one alert: it resolves, and `acknowledgedAt` and `acknowledgedActor` record when
+ * and by whom. Idempotent: an acknowledged alert keeps its first acknowledgement. Needs
+ * `signals_alerts:update` and update access to the resident.
+ */
+export declare function acknowledgeSignalsRawAlert(this: OvokClient, alertId: string): Promise<SignalsRawAlert>;
 export declare function getSignalsSettings(this: OvokClient): Promise<SignalsSettingsResponse>;
 export declare function updateSignalsSettings(this: OvokClient, patch: SignalsSettingsPatch, reason?: string | null): Promise<SignalsSettingsResponse>;

package/dist/client/signals/methods.js

@@ -8,6 +8,9 @@ exports.serializeSignalsAlertsQuery = serializeSignalsAlertsQuery;
 exports.listSignalsAlerts = listSignalsAlerts;
 exports.getSignalsAlert = getSignalsAlert;
 exports.acknowledgeSignalsAlert = acknowledgeSignalsAlert;
+exports.listSignalsRawAlerts = listSignalsRawAlerts;
+exports.getSignalsRawAlert = getSignalsRawAlert;
+exports.acknowledgeSignalsRawAlert = acknowledgeSignalsRawAlert;
 exports.getSignalsSettings = getSignalsSettings;
 exports.updateSignalsSettings = updateSignalsSettings;
 const segment = (value) => encodeURIComponent(value);
@@ -28,28 +31,28 @@ function setSignalsThreshold(patientId, code, body) {
 function removeSignalsThreshold(patientId, code, reason) {
     return this.delete(`/v1/signals/patients/${segment(patientId)}/thresholds/${segment(code)}?reason=${segment(reason)}`);
 }
-function serializeSignalsAlertsQuery(query = {}) {
-    const params = [];
-    if (query.status !== undefined) {
-        params.push(["status", query.status]);
-    }
-    if (query.since !== undefined) {
-        params.push(["since", query.since]);
-    }
-    if (query.acknowledged !== undefined) {
-        params.push(["acknowledged", String(query.acknowledged)]);
-    }
-    if (query.codes !== undefined) {
-        params.push(["codes", query.codes.join(",")]);
-    }
-    if (query.limit !== undefined) {
-        params.push(["limit", String(query.limit)]);
-    }
-    if (query.cursor !== undefined) {
-        params.push(["cursor", query.cursor]);
-    }
-    return params
-        .map(([key, value]) => `${segment(key)}=${segment(value)}`)
+// Each route's own filters, in the order they are sent: a key outside the list is never sent, so
+// a wider object passed as an episode query can't turn into a refused request.
+const EPISODE_QUERY_KEYS = ["status", "since", "acknowledged", "codes", "limit", "cursor"];
+const RAW_ALERT_QUERY_KEYS = [
+    "status",
+    "patientId",
+    "since",
+    "until",
+    "acknowledged",
+    "codes",
+    "limit",
+    "cursor",
+];
+function serializeSignalsAlertsQuery(query = {}, keys = EPISODE_QUERY_KEYS) {
+    const values = query;
+    return keys
+        .filter((key) => values[key] !== undefined)
+        .map((key) => {
+        const value = values[key];
+        const text = Array.isArray(value) ? value.join(",") : String(value);
+        return `${segment(key)}=${segment(text)}`;
+    })
         .join("&");
 }
 function listSignalsAlerts(query = {}) {
@@ -62,6 +65,25 @@ function getSignalsAlert(episodeId) {
 function acknowledgeSignalsAlert(episodeId) {
     return this.post(`/v1/signals/alerts/${segment(episodeId)}/ack`);
 }
+/**
+ * The project's individual Signals alerts, not episodes: works whether or not the project's
+ * `episodicAlerts` is on. `acknowledged: false` lists what is still open for the practitioner.
+ */
+function listSignalsRawAlerts(query = {}) {
+    const serialized = serializeSignalsAlertsQuery(query, RAW_ALERT_QUERY_KEYS);
+    return this.get(`/v1/signals/raw-alerts${serialized ? `?${serialized}` : ""}`);
+}
+function getSignalsRawAlert(alertId) {
+    return this.get(`/v1/signals/raw-alerts/${segment(alertId)}`);
+}
+/**
+ * Acknowledges one alert: it resolves, and `acknowledgedAt` and `acknowledgedActor` record when
+ * and by whom. Idempotent: an acknowledged alert keeps its first acknowledgement. Needs
+ * `signals_alerts:update` and update access to the resident.
+ */
+function acknowledgeSignalsRawAlert(alertId) {
+    return this.post(`/v1/signals/raw-alerts/${segment(alertId)}/ack`);
+}
 function getSignalsSettings() {
     return this.get("/v1/signals/settings");
 }

package/dist/client/signals/types.d.ts

@@ -39,6 +39,79 @@ export type SignalsAlertsPage = {
     items: SignalsAlert[];
     nextCursor: string | null;
 };
+/** Signals' own state of a raw alert: ACTIVE while breaching, RESOLVED once recovered or acknowledged. */
+export type SignalsRawAlertStatus = "ACTIVE" | "RESOLVED";
+/** The person who acknowledged an alert. */
+export type SignalsAcknowledgedActor = {
+    /** A FHIR reference, e.g. `Practitioner/<id>`. */
+    reference: string;
+    display: string | null;
+};
+/**
+ * One individual Signals alert, not an episode: available whether or not the project's
+ * `episodicAlerts` is on. `id`, `createdAt` and `resolvedAt` are Signals' own.
+ *
+ * An alert stays open for the practitioner until it is acknowledged: `acknowledgedAt` is null until
+ * then, even when `status` is already RESOLVED because the reading recovered. Acknowledging
+ * resolves it, and the next breaching reading opens a new alert.
+ */
+export type SignalsRawAlert = {
+    id: string;
+    /** The resident's Medplum Patient id. */
+    patientId: string;
+    signalsPatientId: string;
+    /** The LOINC code that breached; null when no reading's code raised it. */
+    code: string | null;
+    /**
+     * TRIGGER is a threshold breach; EMPTY a reading with no value; NOTE a note; INACTIVE a resident
+     * who stopped reporting.
+     */
+    reason: "TRIGGER" | "EMPTY" | "NOTE" | "INACTIVE";
+    /** The latest breaching reading, as a number or as text. */
+    valueNumber: number | null;
+    valueString: string | null;
+    /** The rule's own payload; it names the bound that was crossed. */
+    message: string | null;
+    observationId: string | null;
+    triggerCode: string | null;
+    triggerVersion: number | null;
+    status: SignalsRawAlertStatus;
+    createdAt: string;
+    resolvedAt: string | null;
+    acknowledgedAt: string | null;
+    /** The Signals client that acknowledged it (Ovok's), not a person: use `acknowledgedActor`. */
+    acknowledgedBy: string | null;
+    acknowledgedActor: SignalsAcknowledgedActor | null;
+    [key: string]: unknown;
+};
+export type SignalsRawAlertsQuery = {
+    status?: SignalsRawAlertStatus;
+    /** `false` for the alerts still open for the practitioner, whatever their `status`. */
+    acknowledged?: boolean;
+    /**
+     * One resident's alerts, by Medplum Patient id. 404 when the caller can't read the resident,
+     * 409 `signals_patient_not_enrolled` when they aren't in Signals yet.
+     */
+    patientId?: string;
+    /** LOINC codes, e.g. `["8867-4", "9279-1"]`. Omitted or empty, every alert. */
+    codes?: readonly string[];
+    /** Alerts created at or after this date-time, with `Z` or an offset. */
+    since?: string;
+    /** Alerts created before this date-time, with `Z` or an offset. */
+    until?: string;
+    /** 1 to 50; 50 when omitted. */
+    limit?: number;
+    /** The previous page's `nextCursor`, passed back unchanged. */
+    cursor?: string;
+};
+/**
+ * Newest first. A page can be shorter than `limit`, even empty, and still have a next one: alerts
+ * of residents the caller can't read are left out. Page until `nextCursor` is null.
+ */
+export type SignalsRawAlertsPage = {
+    items: SignalsRawAlert[];
+    nextCursor: string | null;
+};
 export type SignalsSettings = {
     episodicAlerts: boolean;
     synchronousMode: boolean;

package/dist/conformance/capability-requirements.js

@@ -48,7 +48,7 @@ exports.OVOK_CORE_REQUIREMENTS = {
     description: "The FHIR surface a server must provide for the @ovok/core client library's own methods to function.",
     software: {
         name: "@ovok/core",
-        version: "0.4.4",
+        version: "0.4.5",
     },
     fhirVersion: "4.0.1",
     format: ["json"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ovok/core",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "private": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",