@tellescope/sdk 1.256.14 → 1.256.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tellescope/sdk",
-  "version": "1.256.14",
+  "version": "1.256.15",
   "description": "Code for interacting with the Tellescope API",
   "main": "./lib/cjs/sdk.js",
   "module": "./lib/esm/sdk.js",
@@ -32,14 +32,14 @@
   },
   "homepage": "https://github.com/tellescope-os/tellescope#readme",
   "dependencies": {
-    "@tellescope/constants": "1.256.14",
-    "@tellescope/schema": "1.256.14",
-    "@tellescope/testing": "1.256.14",
-    "@tellescope/types-client": "1.256.14",
-    "@tellescope/types-models": "1.256.14",
-    "@tellescope/types-utilities": "1.256.14",
-    "@tellescope/utilities": "1.256.14",
-    "@tellescope/validation": "1.256.14",
+    "@tellescope/constants": "1.256.15",
+    "@tellescope/schema": "1.256.15",
+    "@tellescope/testing": "1.256.15",
+    "@tellescope/types-client": "1.256.15",
+    "@tellescope/types-models": "1.256.15",
+    "@tellescope/types-utilities": "1.256.15",
+    "@tellescope/utilities": "1.256.15",
+    "@tellescope/validation": "1.256.15",
     "axios": "0.30.3",
     "dotenv": "14.3.2",
     "form-data": "4.0.4",
@@ -55,5 +55,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "0b32ba0040e286c4a1013287f9e154e612db11af"
+  "gitHead": "180f82301125bdd5e73608991061e49ed3d41e96"
 }

package/src/tests/api_tests/auto_merge_form_submission.test.ts

@@ -589,7 +589,7 @@ export const auto_merge_form_submission_tests = async ({ sdk, sdkNonAdmin }: { s
         // Filling a BLANK phone is deliberately blocked too — contact-less patients are the primary
         // takeover target, so "fill only if empty" would not close the hole. Staff update these fields.
         // Previously this test asserted `phone === newPhone`; that behaviour was the vulnerability.
-        // See api_tests/security/public_endpoint_auth_field_lock.test.ts (G26).
+        // See api_tests/security/public_endpoint_auth_field_lock.test.ts.
         && !updatedDestination.phone
         && updatedDestination.email === testEmail
     },

package/src/tests/api_tests/enduser_observations_auto_review.test.ts

@@ -0,0 +1,358 @@
+require('source-map-support').install();
+
+import { SYSTEM_REVIEWER_ID } from "@tellescope/constants"
+import {
+  assert_checks,
+  Check,
+  setup_isolated_tenant,
+} from "../setup_isolated"
+
+const host = process.env.API_URL || 'http://localhost:8080' as const
+
+const RAND = () => Math.random().toString(36).slice(2, 10)
+
+/**
+ * Coverage for auto-review of in-range vital readings — the `autoReview` flag on
+ * `vital_configurations.ranges`, applied inside `handle_vital_create` at the moment a reading is
+ * classified. For RPM-style programs most readings are in range, and clearing them one at a time
+ * out of the unreviewed-vitals queue is pure busywork; a range marked auto-review sets
+ * `reviewedAt` + `reviewedBy = SYSTEM_REVIEWER_ID` on the same update that writes classifications.
+ *
+ * The rule under test is deliberately strict: a reading gets one classification per MATCHING
+ * configuration, and auto-review happens only when EVERY one of those classifications came from an
+ * autoReview range. C is the check that pins this — a reading that is in-range under one
+ * configuration but caught by a non-auto-review range under another still needs a human, because
+ * the second configuration is the one expressing clinical concern.
+ *
+ * Vital configurations are business-wide (the handler reads them with `enduserId: { $exists: false }`
+ * over the caller's businessId), so this suite provisions its own throwaway tenant: without that it
+ * would classify — and auto-review — other concurrently running suites' readings, and theirs would
+ * bleed into these checks. It never calls `sdk.reset_db()`, which clears global throttle namespaces.
+ *
+ * Units come from the fixed VITAL_UNITS list, so checks that must not see each other's
+ * configurations are separated by unit rather than by name: SBP for A/B, DBP for the multi-config
+ * rule, A1C for the uncovered case.
+ *
+ * Classification is an asynchronous create side effect, so every read polls.
+ */
+
+const poll_for = async <T,>(get: () => Promise<T>, done: (v: T) => boolean, attempts=20): Promise<T> => {
+  let value = await get()
+  for (let i = 0; i < attempts && !done(value); i++) {
+    await new Promise(resolve => setTimeout(resolve, 250))
+    value = await get()
+  }
+  return value
+}
+
+export const enduser_observations_auto_review_checks = async (): Promise<Check[]> => {
+  const checks: Check[] = []
+  const record = (label: string, pass: boolean, detail: string) => checks.push({ label, pass, detail })
+
+  let tenant: Awaited<ReturnType<typeof setup_isolated_tenant>> | undefined
+
+  try {
+    tenant = await setup_isolated_tenant({
+      name: `VitalAutoReview ${RAND()}`,
+      users: [{ isAdmin: true }],
+      apiKeys: 0,
+    })
+    const { sdk } = tenant
+
+    const enduser = await sdk.api.endusers.createOne({ fname: 'AutoReview', lname: 'Patient' })
+
+    const create_reading = (unit: string, value: number) => (
+      sdk.api.enduser_observations.createOne({
+        category: 'vital-signs',
+        status: 'final',
+        enduserId: enduser.id,
+        measurement: { unit, value },
+        timestamp: new Date(),
+      })
+    )
+
+    /* ===== A / B: one configuration, Target auto-reviews and High does not ===== */
+
+    await sdk.api.vital_configurations.createOne({
+      title: `AutoReview SBP ${RAND()}`,
+      unit: 'SBP',
+      ranges: [
+        {
+          classification: 'Target',
+          comparison: { type: 'Between', value: { lower: 100, upper: 200 } },
+          autoReview: true,
+        },
+        {
+          classification: 'High',
+          comparison: { type: 'Greater Than', value: 200 },
+        },
+      ],
+    })
+
+    /* ===== A: an in-range reading is reviewed automatically ===== */
+
+    const inRange = await create_reading('SBP', 150)
+    const inRangeAfter = await poll_for(
+      () => sdk.api.enduser_observations.getOne(inRange.id),
+      o => !!o.reviewedAt,
+    )
+    record(
+      'A1: a reading matching an auto-review range is marked reviewed',
+      !!inRangeAfter.reviewedAt,
+      `reviewedAt=${JSON.stringify(inRangeAfter.reviewedAt)} classifications=${JSON.stringify(inRangeAfter.classifications)}`
+      + ` — must be set by handle_vital_create, not by an acknowledge call`,
+    )
+    record(
+      'A2: reviewedBy records the system sentinel, not a user id',
+      inRangeAfter.reviewedBy === SYSTEM_REVIEWER_ID,
+      `reviewedBy=${JSON.stringify(inRangeAfter.reviewedBy)} (want ${JSON.stringify(SYSTEM_REVIEWER_ID)})`,
+    )
+    record(
+      'A3: the auto-reviewed reading still carries its classification',
+      inRangeAfter.classifications?.length === 1 && inRangeAfter.classifications?.[0].classification === 'Target',
+      `classifications=${JSON.stringify(inRangeAfter.classifications)} (want exactly one, Target)`,
+    )
+
+    /* ===== B: an out-of-range reading is classified but left for a human ===== */
+
+    const outOfRange = await create_reading('SBP', 250)
+    const outOfRangeAfter = await poll_for(
+      () => sdk.api.enduser_observations.getOne(outOfRange.id),
+      o => !!o.classifications?.length,
+    )
+    record(
+      'B1: an out-of-range reading is classified High',
+      outOfRangeAfter.classifications?.length === 1 && outOfRangeAfter.classifications?.[0].classification === 'High',
+      `classifications=${JSON.stringify(outOfRangeAfter.classifications)} (want exactly one, High)`,
+    )
+    record(
+      'B2: an out-of-range reading is NOT auto-reviewed',
+      !outOfRangeAfter.reviewedAt && !outOfRangeAfter.reviewedBy,
+      `reviewedAt=${JSON.stringify(outOfRangeAfter.reviewedAt)} reviewedBy=${JSON.stringify(outOfRangeAfter.reviewedBy)} (want neither set)`,
+    )
+
+    /* ===== C: strict multi-config rule — one non-auto-review match blocks auto-review =====
+     * On its own unit (DBP) so these two configurations cannot affect A/B/D. */
+
+    await sdk.api.vital_configurations.createOne({
+      title: `AutoReview DBP target ${RAND()}`,
+      unit: 'DBP',
+      ranges: [
+        {
+          classification: 'Target',
+          comparison: { type: 'Between', value: { lower: 100, upper: 200 } },
+          autoReview: true,
+        },
+      ],
+    })
+    await sdk.api.vital_configurations.createOne({
+      title: `AutoReview DBP catchall ${RAND()}`,
+      unit: 'DBP',
+      // catch-all with autoReview off: this configuration always has an opinion, and it is never
+      // "clear this automatically"
+      ranges: [
+        {
+          classification: 'Low',
+          comparison: { type: 'Greater Than', value: 0 },
+        },
+      ],
+    })
+
+    const multiConfig = await create_reading('DBP', 150)
+    const multiConfigAfter = await poll_for(
+      () => sdk.api.enduser_observations.getOne(multiConfig.id),
+      o => (o.classifications?.length ?? 0) >= 2,
+    )
+    record(
+      'C1: a reading matched by two configurations gets one classification from each',
+      multiConfigAfter.classifications?.length === 2,
+      `classifications=${JSON.stringify(multiConfigAfter.classifications)} (want 2 — one per matching configuration)`,
+    )
+    record(
+      'C2: auto-review requires EVERY matched classification to come from an auto-review range',
+      !multiConfigAfter.reviewedAt && !multiConfigAfter.reviewedBy,
+      `reviewedAt=${JSON.stringify(multiConfigAfter.reviewedAt)} reviewedBy=${JSON.stringify(multiConfigAfter.reviewedBy)}`
+      + ` — in range under one configuration, but the other's non-auto-review range also matched`,
+    )
+
+    /* ===== D: a reading no configuration covers is never auto-reviewed ===== */
+
+    const uncovered = await create_reading('A1C', 150)
+    // nothing to wait for turning true, so poll for the negative to settle instead of reading once
+    const uncoveredAfter = await poll_for(
+      () => sdk.api.enduser_observations.getOne(uncovered.id),
+      o => !!o.reviewedAt || !!o.classifications?.length,
+      8,
+    )
+    record(
+      'D1: a reading on an uncovered unit gets no classifications and is not auto-reviewed',
+      !uncoveredAfter.classifications?.length && !uncoveredAfter.reviewedAt && !uncoveredAfter.reviewedBy,
+      `classifications=${JSON.stringify(uncoveredAfter.classifications)} reviewedAt=${JSON.stringify(uncoveredAfter.reviewedAt)}`
+      + ` reviewedBy=${JSON.stringify(uncoveredAfter.reviewedBy)} (want all empty — no configuration covers A1C here)`,
+    )
+
+    /* ===== E: a manual acknowledge still records the real reviewer ===== */
+
+    await sdk.api.enduser_observations.acknowledge({ ids: [outOfRange.id] })
+    const acknowledged = await sdk.api.enduser_observations.getOne(outOfRange.id)
+    record(
+      'E1: manual acknowledge still sets reviewedBy to the acting user',
+      !!acknowledged.reviewedAt && acknowledged.reviewedBy === tenant.users[0].id,
+      `reviewedAt=${JSON.stringify(acknowledged.reviewedAt)} reviewedBy=${JSON.stringify(acknowledged.reviewedBy)}`
+      + ` (want the acting user ${tenant.users[0].id}, NOT the sentinel)`,
+    )
+
+    /* ===== F/G/H: enduser-conditional auto-review =====
+     * A range's autoReviewConditions gate auto-review on the enduser: the range still classifies the
+     * reading, but only auto-reviews when the enduser satisfies the conditions. Separate endusers whose
+     * custom field `arField` matches vs. does not, on their own units so configs stay isolated. */
+
+    const matchingEnduser = await sdk.api.endusers.createOne({ fname: 'Match', lname: 'Patient', fields: { arField: 'yes' } })
+    const nonMatchingEnduser = await sdk.api.endusers.createOne({ fname: 'NoMatch', lname: 'Patient', fields: { arField: 'no' } })
+
+    const create_reading_for = (enduserId: string, unit: string, value: number) => (
+      sdk.api.enduser_observations.createOne({
+        category: 'vital-signs',
+        status: 'final',
+        enduserId,
+        measurement: { unit, value },
+        timestamp: new Date(),
+      })
+    )
+
+    /* ===== F: a Target range that auto-reviews only for endusers matching a custom-field condition ===== */
+
+    await sdk.api.vital_configurations.createOne({
+      title: `AutoReview BPM conditional ${RAND()}`,
+      unit: 'BPM',
+      ranges: [
+        {
+          classification: 'Target',
+          comparison: { type: 'Between', value: { lower: 60, upper: 100 } },
+          autoReview: true,
+          autoReviewConditions: { $and: [{ condition: { arField: 'yes' } }] },
+        },
+      ],
+    })
+
+    const condMatch = await create_reading_for(matchingEnduser.id, 'BPM', 80)
+    const condMatchAfter = await poll_for(
+      () => sdk.api.enduser_observations.getOne(condMatch.id),
+      o => !!o.reviewedAt || !!o.classifications?.length,
+    )
+    record(
+      'F1: a reading for an enduser matching the auto-review conditions IS auto-reviewed',
+      !!condMatchAfter.reviewedAt && condMatchAfter.reviewedBy === SYSTEM_REVIEWER_ID
+      && condMatchAfter.classifications?.[0]?.classification === 'Target',
+      `reviewedAt=${JSON.stringify(condMatchAfter.reviewedAt)} reviewedBy=${JSON.stringify(condMatchAfter.reviewedBy)}`
+      + ` classifications=${JSON.stringify(condMatchAfter.classifications)} (enduser arField=yes matches)`,
+    )
+
+    const condNoMatch = await create_reading_for(nonMatchingEnduser.id, 'BPM', 80)
+    const condNoMatchAfter = await poll_for(
+      () => sdk.api.enduser_observations.getOne(condNoMatch.id),
+      o => !!o.classifications?.length,
+    )
+    record(
+      'F2: the same reading for an enduser NOT matching the conditions is classified but NOT auto-reviewed',
+      condNoMatchAfter.classifications?.[0]?.classification === 'Target'
+      && !condNoMatchAfter.reviewedAt && !condNoMatchAfter.reviewedBy,
+      `reviewedAt=${JSON.stringify(condNoMatchAfter.reviewedAt)} reviewedBy=${JSON.stringify(condNoMatchAfter.reviewedBy)}`
+      + ` classifications=${JSON.stringify(condNoMatchAfter.classifications)} (enduser arField=no does not match)`,
+    )
+
+    /* ===== G: $or conditions — matching either branch auto-reviews ===== */
+
+    await sdk.api.vital_configurations.createOne({
+      title: `AutoReview O2 or-conditions ${RAND()}`,
+      unit: 'O2 Sat%',
+      ranges: [
+        {
+          classification: 'Target',
+          comparison: { type: 'Greater Than', value: 90 },
+          autoReview: true,
+          autoReviewConditions: { $or: [{ condition: { arField: 'other' } }, { condition: { arField: 'yes' } }] },
+        },
+      ],
+    })
+
+    const orMatch = await create_reading_for(matchingEnduser.id, 'O2 Sat%', 98)
+    const orMatchAfter = await poll_for(
+      () => sdk.api.enduser_observations.getOne(orMatch.id),
+      o => !!o.reviewedAt || !!o.classifications?.length,
+    )
+    record(
+      'G1: an enduser matching either $or branch is auto-reviewed',
+      !!orMatchAfter.reviewedAt && orMatchAfter.reviewedBy === SYSTEM_REVIEWER_ID,
+      `reviewedAt=${JSON.stringify(orMatchAfter.reviewedAt)} reviewedBy=${JSON.stringify(orMatchAfter.reviewedBy)}`
+      + ` (arField=yes matches the second $or branch)`,
+    )
+
+    /* ===== H: multi-config safety — a failing condition in one config blocks auto-review =====
+     * matchingEnduser (arField=yes) matches config-1's Target but NOT config-2's catch-all condition. */
+
+    await sdk.api.vital_configurations.createOne({
+      title: `AutoReview L/min target ${RAND()}`,
+      unit: 'L/min',
+      ranges: [
+        {
+          classification: 'Target',
+          comparison: { type: 'Between', value: { lower: 100, upper: 600 } },
+          autoReview: true,
+          autoReviewConditions: { $and: [{ condition: { arField: 'yes' } }] },
+        },
+      ],
+    })
+    await sdk.api.vital_configurations.createOne({
+      title: `AutoReview L/min catchall ${RAND()}`,
+      unit: 'L/min',
+      ranges: [
+        {
+          classification: 'Low',
+          comparison: { type: 'Greater Than', value: 0 },
+          autoReview: true,
+          // enduser arField=yes, so this condition (arField=other) fails: config-2 is not auto-reviewable
+          autoReviewConditions: { $and: [{ condition: { arField: 'other' } }] },
+        },
+      ],
+    })
+
+    const condMultiConfig = await create_reading_for(matchingEnduser.id, 'L/min', 300)
+    const condMultiConfigAfter = await poll_for(
+      () => sdk.api.enduser_observations.getOne(condMultiConfig.id),
+      o => (o.classifications?.length ?? 0) >= 2,
+    )
+    record(
+      'H1: auto-review requires EVERY matched range to be auto-reviewable for this enduser',
+      condMultiConfigAfter.classifications?.length === 2
+      && !condMultiConfigAfter.reviewedAt && !condMultiConfigAfter.reviewedBy,
+      `reviewedAt=${JSON.stringify(condMultiConfigAfter.reviewedAt)} reviewedBy=${JSON.stringify(condMultiConfigAfter.reviewedBy)}`
+      + ` classifications=${JSON.stringify(condMultiConfigAfter.classifications)}`
+      + ` — config-1 conditions match, config-2 conditions do not, so a human is still required`,
+    )
+  } finally {
+    // Teardown BEFORE anything asserts — assert calls process.exit, which would strand this tenant.
+    if (tenant) { try { await tenant.teardown() } catch (e) { console.error('teardown failed', e) } }
+  }
+
+  return checks
+}
+
+/** Asserting wrapper, for standalone runs and for sequential use in the suite. */
+export const enduser_observations_auto_review_tests = async () => {
+  assert_checks('Vital auto-review on create', await enduser_observations_auto_review_checks())
+}
+
+// Allow running this test file independently
+if (require.main === module) {
+  console.log(`🌐 Using API URL: ${host}`)
+  enduser_observations_auto_review_tests()
+    .then(() => {
+      console.log("✅ Vital auto-review test suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ Vital auto-review test suite failed:", error)
+      process.exit(1)
+    })
+}

package/src/tests/api_tests/integrations_redacted.test.ts

@@ -207,7 +207,7 @@ export const integrations_redacted_tests = async ({ sdk, sdkNonAdmin } : { sdk:
       }}
     )
 
-    // F-0049: connect_stripe must reject caller-supplied accountId (Stripe-account-spoofing defense).
+    // connect_stripe must reject caller-supplied accountId (Stripe-account-spoofing defense).
     // Stripe Connect is deprecated in Tellescope; accountId was a test shortcut, kept rejected to preserve SDK shape.
     await async_test(
       "connect_stripe rejects caller-supplied accountId",

package/src/tests/api_tests/organization_signup.test.ts

@@ -23,7 +23,7 @@ const SEEDED_TEST_BUSINESS_ID = '60398b1131a295e64f084ff6'
  * Covers the self-service organization signup chain, which had ZERO test coverage:
  * `users.register` -> `users.submit_email_verification` -> `organizations.create_and_join`.
  *
- * That gap is why F-0191 nearly shipped a schema `adminOnly` flag on create_and_join that would have
+ * That gap is why an earlier review nearly shipped a schema `adminOnly` flag on create_and_join that would have
  * 401'd every new organization — a freshly registered user has no `roles`, because create_and_join is
  * itself what grants Admin. This test is the regression guard for that.
  *
@@ -136,7 +136,7 @@ export const organization_signup_checks = async (): Promise<Check[]> => {
       `status=${verified.status} authToken=${!!verified.data?.authToken}`,
     )
 
-    /* ===== D: create_and_join — what F-0191's flag would have broken ===== */
+    /* ===== D: create_and_join — what that flag would have broken ===== */
 
     const subdomain = `signup-${RAND()}`
     const joined = await axios.request({