@tellescope/sdk 2.0.0-beta.1 → 2.0.0-beta.3

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

@@ -0,0 +1,455 @@
+require('source-map-support').install();
+
+import { SYSTEM_REVIEWER_ID } from "@tellescope/constants"
+import {
+  assert_checks,
+  Check,
+  setup_isolated_tenant,
+  IsolatedSuite,
+} 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 the "Review Vital Reading" automation trigger action, and — because the same change
+ * carved that action out of two shared dedupe mechanisms — for the dedupe mechanisms themselves.
+ *
+ * The action marks the reading in `journeyContext.observationId` as reviewed
+ * (`reviewedAt` + `reviewedBy = SYSTEM_REVIEWER_ID`), so a trigger's own gating (programs, enduser
+ * conditions, active hours) can decide what auto-reviews. Only the Vital Update event supplies an
+ * observationId, so the pairing is enforced by a schema relationship constraint.
+ *
+ * To be useful it has to run for EVERY matching reading, which means opting out of both things that
+ * normally collapse repeat fires:
+ *   1. the 60s `throttled_events` window, one fire per (trigger, enduser)   — automation_triggers.ts
+ *   2. the per-batch `enduserIdTriggerTracker`, one fire per (trigger, enduser) per create batch,
+ *      which a blood pressure reading trips because it creates SBP + DBP together — vitals.ts
+ *
+ * Both carve-outs are qualified by action type, and both live on code paths every other trigger
+ * shares. Checks G-I are the regression half of this suite: they pin that the ordinary behavior is
+ * unchanged for other actions and other events. Nothing else in the repo asserts trigger
+ * throttling — every other trigger suite is written to avoid it (one enduser per case) rather than
+ * to test it — so if these go, the platform-wide throttle has no coverage at all.
+ *
+ * This suite provisions its own throwaway tenant. That is not optional: `vital_configurations` are
+ * business-wide (handle_vital_create reads them with `enduserId: { $exists: false }` across the
+ * businessId), so on the shared fixture these configurations would classify other concurrently
+ * running suites' readings and theirs would bleed into these checks. It never calls `sdk.reset_db()`,
+ * which clears global throttle namespaces shared with other suites — which would be especially
+ * destructive here, where the throttle is the thing under test.
+ *
+ * Checks are separated by vital unit rather than by name, because a configuration applies to every
+ * reading of its unit across the tenant.
+ *
+ * Synchronization. Classification and trigger actions are asynchronous create side effects, so every
+ * read polls.
+ *   - Positive checks poll directly on the condition they assert, which is sound on its own.
+ *   - Negative checks ("this did NOT fire") need a barrier, or they would pass by reading too early.
+ *     Two are used. Where a control trigger fires on the same reading, it is created AFTER the
+ *     trigger under test so it runs last within `triggersForClassification` (the same ordering
+ *     programs.test.ts relies on). Where the control would itself be throttled, the barrier is a
+ *     Review Vital Reading trigger instead — it is throttle-exempt by construction, so its effect
+ *     landing proves the later reading was processed.
+ */
+
+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 vital_review_trigger_action_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: `VitalReviewAction ${RAND()}`,
+      users: [{ isAdmin: true }],
+      apiKeys: 0,
+    })
+    const { sdk } = tenant
+
+    const high_configuration = (unit: string, over: number) => sdk.api.vital_configurations.createOne({
+      title: `Review action ${unit} ${RAND()}`,
+      unit,
+      ranges: [{ classification: 'High', comparison: { type: 'Greater Than', value: over } }],
+    })
+
+    const new_enduser = (label: string) => sdk.api.endusers.createOne({ fname: 'Review', lname: label })
+
+    const add_reading = (enduserId: string, unit: string, value: number, extra: object = {}) => (
+      sdk.api.enduser_observations.createOne({
+        category: 'vital-signs',
+        status: 'final',
+        enduserId,
+        measurement: { unit, value },
+        timestamp: new Date(),
+        ...extra,
+      })
+    )
+
+    const is_system_reviewed = (o: { reviewedAt?: Date, reviewedBy?: string }) => (
+      !!o.reviewedAt && o.reviewedBy === SYSTEM_REVIEWER_ID
+    )
+
+    /* ================= A, D, E: the action marks the reading in context ================= */
+
+    // one configuration, two ranges, so a reading can match the trigger's classification or miss it
+    const glucoseConfiguration = await sdk.api.vital_configurations.createOne({
+      title: `Review action glucose ${RAND()}`,
+      unit: 'mg/dL',
+      ranges: [
+        { classification: 'High', comparison: { type: 'Greater Than', value: 200 } },
+        { classification: 'Low', comparison: { type: 'Less Than', value: 50 } },
+      ],
+    })
+
+    // created FIRST, so the control trigger below runs after it on the same reading
+    await sdk.api.automation_triggers.createOne({
+      title: `Review High glucose ${RAND()}`,
+      status: 'Active',
+      event: {
+        type: 'Vital Update',
+        info: { configurationIds: [glucoseConfiguration.id], classifications: ['High'] },
+      },
+      action: { type: 'Review Vital Reading', info: {} },
+    })
+    // control/barrier: matches both classifications, so its tag marks "this reading was processed"
+    await sdk.api.automation_triggers.createOne({
+      title: `Glucose processed marker ${RAND()}`,
+      status: 'Active',
+      event: {
+        type: 'Vital Update',
+        info: { configurationIds: [glucoseConfiguration.id], classifications: ['High', 'Low'] },
+      },
+      action: { type: 'Add Tags', info: { tags: ['glucose-processed'] } },
+    })
+
+    const matchingEnduser = await new_enduser('Matching')
+    const matchingReading = await add_reading(matchingEnduser.id, 'mg/dL', 250) // High
+    const reviewedMatching = await poll_for(
+      () => sdk.api.enduser_observations.getOne(matchingReading.id),
+      is_system_reviewed,
+    )
+    record(
+      'A: Review Vital Reading marks the reading that fired the trigger as system-reviewed',
+      is_system_reviewed(reviewedMatching),
+      `reviewedAt=${JSON.stringify(reviewedMatching.reviewedAt)} reviewedBy=${JSON.stringify(reviewedMatching.reviewedBy)}`,
+    )
+
+    // a reading classified Low never matches this trigger, so it must stay in the unreviewed queue
+    const otherClassEnduser = await new_enduser('OtherClass')
+    const otherClassReading = await add_reading(otherClassEnduser.id, 'mg/dL', 10) // Low
+    await poll_for(
+      () => sdk.api.endusers.getOne(otherClassEnduser.id),
+      e => !!e.tags?.includes('glucose-processed'),
+    )
+    const afterOtherClass = await sdk.api.enduser_observations.getOne(otherClassReading.id)
+    record(
+      'D: a reading whose classification the trigger does not match is left unreviewed',
+      !afterOtherClass.reviewedAt,
+      `reviewedAt=${JSON.stringify(afterOtherClass.reviewedAt)}`
+      + ` (barrier tag seen, so the reading was processed)`,
+    )
+
+    // an already-reviewed reading must not be re-stamped — the $exists: false guard on the update
+    const PRE_REVIEWED_AT = new Date('2020-01-02T03:04:05.000Z')
+    const preReviewedEnduser = await new_enduser('PreReviewed')
+    const preReviewedReading = await add_reading(
+      preReviewedEnduser.id, 'mg/dL', 250, { reviewedAt: PRE_REVIEWED_AT },
+    )
+    await poll_for(
+      () => sdk.api.endusers.getOne(preReviewedEnduser.id),
+      e => !!e.tags?.includes('glucose-processed'),
+    )
+    const afterPreReviewed = await sdk.api.enduser_observations.getOne(preReviewedReading.id)
+    record(
+      'E: an already-reviewed reading is not re-stamped',
+      !!afterPreReviewed.reviewedAt
+      && new Date(afterPreReviewed.reviewedAt).getTime() === PRE_REVIEWED_AT.getTime()
+      && afterPreReviewed.reviewedBy !== SYSTEM_REVIEWER_ID,
+      `reviewedAt=${JSON.stringify(afterPreReviewed.reviewedAt)} (want ${PRE_REVIEWED_AT.toISOString()})`
+      + ` reviewedBy=${JSON.stringify(afterPreReviewed.reviewedBy)}`,
+    )
+
+    /* ============ B: every reading of a multi-component batch (the tracker carve-out) ============ */
+
+    const sbpConfiguration = await high_configuration('SBP', 200)
+    const dbpConfiguration = await high_configuration('DBP', 120)
+
+    await sdk.api.automation_triggers.createOne({
+      title: `Review High BP ${RAND()}`,
+      status: 'Active',
+      event: {
+        type: 'Vital Update',
+        info: {
+          configurationIds: [sbpConfiguration.id, dbpConfiguration.id],
+          classifications: ['High'],
+        },
+      },
+      action: { type: 'Review Vital Reading', info: {} },
+    })
+
+    // one blood pressure reading = two observations in ONE create batch for ONE enduser, which is
+    // exactly what the per-batch tracker would otherwise collapse to a single fire
+    const bpEnduser = await new_enduser('BloodPressure')
+    const bpReadings = await sdk.api.enduser_observations.createSome([
+      {
+        category: 'vital-signs', status: 'final', enduserId: bpEnduser.id,
+        measurement: { unit: 'SBP', value: 250 }, timestamp: new Date(),
+      },
+      {
+        category: 'vital-signs', status: 'final', enduserId: bpEnduser.id,
+        measurement: { unit: 'DBP', value: 150 }, timestamp: new Date(),
+      },
+    ])
+    const bpIds = bpReadings.created.map(o => o.id)
+    const bpAfter = await poll_for(
+      () => Promise.all(bpIds.map(id => sdk.api.enduser_observations.getOne(id))),
+      os => os.every(is_system_reviewed),
+    )
+    record(
+      'B: both observations of a two-component reading created in one batch are reviewed',
+      bpAfter.length === 2 && bpAfter.every(is_system_reviewed),
+      bpAfter.map(o => `${o.measurement.unit}:${o.reviewedBy ?? 'unreviewed'}`).join(' '),
+    )
+
+    /* ============ C: readings seconds apart (the throttle carve-out) ============ */
+
+    const bpmConfiguration = await high_configuration('BPM', 150)
+    await sdk.api.automation_triggers.createOne({
+      title: `Review High BPM ${RAND()}`,
+      status: 'Active',
+      event: {
+        type: 'Vital Update',
+        info: { configurationIds: [bpmConfiguration.id], classifications: ['High'] },
+      },
+      action: { type: 'Review Vital Reading', info: {} },
+    })
+
+    // Same enduser, same trigger, well inside the 60s window that would normally swallow the second.
+    // The second reading is only created once the first has been reviewed: the throttle record is
+    // written at the END of the fire it belongs to, so two readings posted back to back race it and
+    // both get through even with the carve-out removed. Waiting makes the second fire genuinely
+    // throttle-eligible, which is what gives this check its teeth.
+    const burstEnduser = await new_enduser('Burst')
+    const burstFirst = await add_reading(burstEnduser.id, 'BPM', 180)
+    await poll_for(
+      () => sdk.api.enduser_observations.getOne(burstFirst.id),
+      is_system_reviewed,
+    )
+    const burstSecond = await add_reading(burstEnduser.id, 'BPM', 190)
+    const burstSecondAfter = await poll_for(
+      () => sdk.api.enduser_observations.getOne(burstSecond.id),
+      is_system_reviewed,
+    )
+    record(
+      'C: a second reading inside the 60s window is still reviewed (throttle-exempt action)',
+      is_system_reviewed(burstSecondAfter),
+      `second reading reviewedBy=${JSON.stringify(burstSecondAfter.reviewedBy)}`
+      + ` (first reading was already reviewed, so the throttle record existed)`,
+    )
+
+    /* ================= F: the action is rejected on events with no reading ================= */
+
+    let createError = ''
+    try {
+      await sdk.api.automation_triggers.createOne({
+        title: `Review action wrong event ${RAND()}`,
+        status: 'Active',
+        event: { type: 'Field Equals', info: { field: '0', value: 'anything' } },
+        action: { type: 'Review Vital Reading', info: {} },
+      })
+    } catch (err: any) { createError = err?.message ?? String(err) }
+    record(
+      'F: creating a Review Vital Reading trigger on a non-Vital Update event is rejected',
+      createError.includes('Review Vital Reading') && createError.includes('Vital Update'),
+      `error=${JSON.stringify(createError) || '(none — the trigger was ACCEPTED)'}`,
+    )
+
+    const validTrigger = await sdk.api.automation_triggers.createOne({
+      title: `Review action valid, to be broken ${RAND()}`,
+      status: 'Active',
+      event: {
+        type: 'Vital Update',
+        info: { configurationIds: [bpmConfiguration.id], classifications: ['Critical High'] },
+      },
+      action: { type: 'Review Vital Reading', info: {} },
+    })
+    let updateError = ''
+    try {
+      await sdk.api.automation_triggers.updateOne(validTrigger.id, {
+        event: { type: 'Field Equals', info: { field: '0', value: 'anything' } },
+      })
+    } catch (err: any) { updateError = err?.message ?? String(err) }
+    const afterUpdate = await sdk.api.automation_triggers.getOne(validTrigger.id)
+    record(
+      'F2: switching an existing Review Vital Reading trigger to a non-Vital Update event is rejected',
+      updateError.includes('Review Vital Reading') && afterUpdate.event.type === 'Vital Update',
+      `error=${JSON.stringify(updateError) || '(none — the update was ACCEPTED)'}`
+      + ` event=${afterUpdate.event.type}`,
+    )
+
+    /* ======= G-I: the carve-outs must not leak to other actions or other events ======= */
+
+    // G. the 60s throttle still applies to a Vital Update trigger with an ordinary action. Same
+    // event and timing as check C — the only difference is the action type.
+    const o2Configuration = await high_configuration('O2 Sat%', 90)
+    await sdk.api.automation_triggers.createOne({
+      title: `O2 alert ${RAND()}`,
+      status: 'Active',
+      event: {
+        type: 'Vital Update',
+        info: { configurationIds: [o2Configuration.id], classifications: ['High'] },
+      },
+      action: { type: 'Add Tags', info: { tags: ['o2-alert'] } },
+    })
+    // barrier for the second reading: throttle-exempt by construction, so its effect landing proves
+    // the reading was processed and the missing tag is a throttle, not a race
+    await sdk.api.automation_triggers.createOne({
+      title: `O2 review barrier ${RAND()}`,
+      status: 'Active',
+      event: {
+        type: 'Vital Update',
+        info: { configurationIds: [o2Configuration.id], classifications: ['High'] },
+      },
+      action: { type: 'Review Vital Reading', info: {} },
+    })
+
+    const o2Enduser = await new_enduser('Oxygen')
+    await add_reading(o2Enduser.id, 'O2 Sat%', 95)
+    await poll_for(
+      () => sdk.api.endusers.getOne(o2Enduser.id),
+      e => !!e.tags?.includes('o2-alert'),
+    )
+    await sdk.api.endusers.updateOne(o2Enduser.id, { tags: [] }, { replaceObjectFields: true })
+
+    const o2Second = await add_reading(o2Enduser.id, 'O2 Sat%', 97)
+    await poll_for(
+      () => sdk.api.enduser_observations.getOne(o2Second.id),
+      is_system_reviewed,
+    )
+    const o2After = await sdk.api.endusers.getOne(o2Enduser.id)
+    record(
+      'G: the 60s throttle still applies to a Vital Update trigger with an ordinary action',
+      !o2After.tags?.includes('o2-alert'),
+      `tags=${JSON.stringify(o2After.tags)}`
+      + ` (the second reading was reviewed, so it was processed)`,
+    )
+
+    // H. the throttle still applies to an entirely different event type. The carve-out lives in
+    // handle_actions_for_triggers_inner, which every trigger event shares.
+    await sdk.api.automation_triggers.createOne({
+      title: `Field equals throttle ${RAND()}`,
+      status: 'Active',
+      event: { type: 'Field Equals', info: { field: '0', value: 'throttle-test' } },
+      action: { type: 'Add Tags', info: { tags: ['fe-fired'] } },
+    })
+
+    const feEnduser = await new_enduser('FieldEquals')
+    await sdk.api.endusers.updateOne(feEnduser.id, { fields: { '0': 'throttle-test' } })
+    await poll_for(
+      () => sdk.api.endusers.getOne(feEnduser.id),
+      e => !!e.tags?.includes('fe-fired'),
+    )
+    await sdk.api.endusers.updateOne(feEnduser.id, { tags: [] }, { replaceObjectFields: true })
+
+    await sdk.api.endusers.updateOne(feEnduser.id, { fields: { '0': 'something-else' } })
+    await sdk.api.endusers.updateOne(feEnduser.id, { fields: { '0': 'throttle-test' } })
+    // barrier: the same trigger on a DIFFERENT enduser has no throttle record, so its tag landing
+    // shows the trigger is processing updates made after the throttled one
+    const feBarrierEnduser = await new_enduser('FieldEqualsBarrier')
+    await sdk.api.endusers.updateOne(feBarrierEnduser.id, { fields: { '0': 'throttle-test' } })
+    await poll_for(
+      () => sdk.api.endusers.getOne(feBarrierEnduser.id),
+      e => !!e.tags?.includes('fe-fired'),
+    )
+    const feAfter = await sdk.api.endusers.getOne(feEnduser.id)
+    record(
+      'H: the 60s throttle still applies to a non-vital event type (Field Equals)',
+      !feAfter.tags?.includes('fe-fired'),
+      `tags=${JSON.stringify(feAfter.tags)}`
+      + ` (the same trigger fired for another enduser afterwards, so it was processing)`,
+    )
+
+    // I. the per-batch tracker is unchanged for other actions: one fire per enduser per batch, even
+    // though the batch carries two classifying readings. Create User Notifications is used because
+    // it is countable, unlike Add Tags.
+    const NOTIFICATION_TYPE = `review-tracker-${RAND()}`
+    const a1cConfiguration = await high_configuration('A1C', 9)
+    const flowConfiguration = await high_configuration('L/min', 300)
+    await sdk.api.automation_triggers.createOne({
+      title: `Batch notification ${RAND()}`,
+      status: 'Active',
+      event: {
+        type: 'Vital Update',
+        info: {
+          configurationIds: [a1cConfiguration.id, flowConfiguration.id],
+          classifications: ['High'],
+        },
+      },
+      action: {
+        type: 'Create User Notifications',
+        info: { message: 'Two readings arrived together', notificationType: NOTIFICATION_TYPE },
+      },
+    })
+
+    const batchEnduser = await new_enduser('BatchNotify')
+    await sdk.api.enduser_observations.createSome([
+      {
+        category: 'vital-signs', status: 'final', enduserId: batchEnduser.id,
+        measurement: { unit: 'A1C', value: 12 }, timestamp: new Date(),
+      },
+      {
+        category: 'vital-signs', status: 'final', enduserId: batchEnduser.id,
+        measurement: { unit: 'L/min', value: 400 }, timestamp: new Date(),
+      },
+    ])
+    const load_notifications = () => sdk.api.user_notifications.getSome({
+      filter: { type: NOTIFICATION_TYPE },
+    })
+    await poll_for(load_notifications, n => n.length > 0)
+    // keep polling past the first arrival, so a second fire would have time to show up
+    const notifications = await poll_for(load_notifications, n => n.length > 1, 8)
+    record(
+      'I: the per-batch tracker still collapses other actions to one fire per batch',
+      notifications.length === 1,
+      `notifications=${notifications.length} (want 1, for a batch of 2 classifying readings)`,
+    )
+  } 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 vital_review_trigger_action_tests = async () => {
+  assert_checks('Review Vital Reading trigger action', await vital_review_trigger_action_checks())
+}
+
+/** Enrolls this suite in the auto-discovered parallel pool — see run_discovered_isolated_suites. */
+export const ISOLATED_SUITE: IsolatedSuite = { name: 'Review Vital Reading trigger action', run: vital_review_trigger_action_checks }
+
+// Allow running this test file independently
+if (require.main === module) {
+  console.log(`🌐 Using API URL: ${host}`)
+  vital_review_trigger_action_tests()
+    .then(() => {
+      console.log("✅ Review Vital Reading trigger action suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ Review Vital Reading trigger action suite failed:", error)
+      process.exit(1)
+    })
+}