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

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

@@ -0,0 +1,393 @@
+require('source-map-support').install();
+
+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)
+
+const FORM_VITAL_READING_SOURCE = 'tellescope-form'
+
+/**
+ * Coverage for the per-question opt-in that turns a numeric form answer into an
+ * `enduser_observations` vital reading on submission — `form_fields.options.vitalUnit`, consumed by
+ * `create_vital_readings_for_form_response` in api/modules/forms.ts.
+ *
+ * The point of the feature is that weight (and the other VITAL_UNITS) collected in a form charts
+ * beside device, portal and manually entered readings. The point of the opt-in being per FIELD is
+ * that nothing changes for an existing org or form until an admin configures a question — which is
+ * why the "no opt-in configured" check below is as load-bearing as the positive ones.
+ *
+ * Provisions its own throwaway tenant: readings are read back by enduser, and `handle_vital_create`
+ * reads business-wide vital_configurations, so a shared tenant would let concurrently running suites
+ * see each other's observations. Never calls `sdk.reset_db()`.
+ *
+ * Readings are created as an asynchronous side effect of the submission (fire-and-forget, so that a
+ * reading can never delay or fail a patient's submit), so every read polls — and every NEGATIVE
+ * check polls too, with a barrier that proves the submission's side effects have run.
+ */
+
+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 form_vital_reading_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: `FormVitals ${RAND()}`,
+      users: [{ isAdmin: true }],
+      apiKeys: 0,
+    })
+    const { sdk } = tenant
+
+    const observations_for = (enduserId: string) => (
+      sdk.api.enduser_observations.getSome({ filter: { enduserId } })
+    )
+
+    /* ===== A: a configured Number question creates a reading on submission ===== */
+
+    const form = await sdk.api.forms.createOne({ title: `Vitals intake ${RAND()}` })
+    const weightField = await sdk.api.form_fields.createOne({
+      formId: form.id,
+      title: 'Weight (lbs)',
+      type: 'number',
+      options: { vitalUnit: 'LB' },
+      previousFields: [{ type: 'root', info: {} }],
+    })
+    // a second question with NO vitalUnit, to prove the opt-in is per field and not per form
+    const plainField = await sdk.api.form_fields.createOne({
+      formId: form.id,
+      title: 'How many glasses of water?',
+      type: 'number',
+      previousFields: [{ type: 'after', info: { fieldId: weightField.id } }],
+    })
+
+    const enduser = await sdk.api.endusers.createOne({ fname: 'Form', lname: 'Vitals' })
+
+    const prepared = await sdk.api.form_responses.prepare_form_response({
+      formId: form.id, enduserId: enduser.id,
+    })
+    const submittedAt = new Date()
+    await sdk.api.form_responses.submit_form_response({
+      accessCode: prepared.accessCode,
+      responses: [
+        { fieldId: weightField.id, fieldTitle: weightField.title, answer: { type: 'number', value: 185 } },
+        { fieldId: plainField.id, fieldTitle: plainField.title, answer: { type: 'number', value: 8 } },
+      ],
+    })
+
+    const readings = await poll_for(() => observations_for(enduser.id), o => o.length >= 1)
+
+    record(
+      'A1: exactly one reading is created — the opt-in is per field, not per form',
+      readings.length === 1,
+      `created ${readings.length}: ${JSON.stringify(readings.map(r => r.measurement))}`
+      + ` — the second Number question has no vitalUnit and must contribute nothing`,
+    )
+
+    const reading = readings[0]
+    record(
+      'A2: the reading carries the answer value in the configured unit',
+      reading?.measurement?.value === 185 && reading?.measurement?.unit === 'LB',
+      `measurement=${JSON.stringify(reading?.measurement)} (want { value: 185, unit: 'LB' })`,
+    )
+    record(
+      'A3: source marks it as form-collected',
+      reading?.source === FORM_VITAL_READING_SOURCE,
+      `source=${JSON.stringify(reading?.source)} (want ${JSON.stringify(FORM_VITAL_READING_SOURCE)})`
+      + ` — the webapp Vitals table renders an unlisted source as "Source: <source>"`,
+    )
+    record(
+      'A4: it is a final vital-signs observation, like any other charted reading',
+      reading?.category === 'vital-signs' && reading?.status === 'final',
+      `category=${JSON.stringify(reading?.category)} status=${JSON.stringify(reading?.status)}`,
+    )
+    record(
+      'A5: timestamp and recordedAt are the submission time',
+      (
+        !!reading?.timestamp && !!reading?.recordedAt
+        && new Date(reading.recordedAt).getTime() === new Date(reading.timestamp).getTime()
+        && Math.abs(new Date(reading.timestamp).getTime() - submittedAt.getTime()) < 1000 * 60 * 5
+      ),
+      `timestamp=${JSON.stringify(reading?.timestamp)} recordedAt=${JSON.stringify(reading?.recordedAt)}`
+      + ` (want both ~= the submission at ${submittedAt.toISOString()})`,
+    )
+    record(
+      'A6: externalId links the reading back to <formResponseId>:<fieldId>',
+      reading?.externalId === `${prepared.response.id}:${weightField.id}`,
+      `externalId=${JSON.stringify(reading?.externalId)}`
+      + ` (want ${JSON.stringify(`${prepared.response.id}:${weightField.id}`)})`,
+    )
+    record(
+      'A7: vital triggers are left enabled for an ordinary enduser',
+      reading?.dontTrigger !== true,
+      `dontTrigger=${JSON.stringify(reading?.dontTrigger)} (want not true, so Vital Update triggers fire)`,
+    )
+
+    /* ===== C: a form with no opted-in question creates nothing ===== */
+
+    const plainForm = await sdk.api.forms.createOne({ title: `No vitals ${RAND()}` })
+    const plainOnlyField = await sdk.api.form_fields.createOne({
+      formId: plainForm.id,
+      title: 'Current weight',
+      type: 'number',
+      previousFields: [{ type: 'root', info: {} }],
+    })
+    const plainEnduser = await sdk.api.endusers.createOne({ fname: 'NoOptIn', lname: 'Patient' })
+    const plainPrepared = await sdk.api.form_responses.prepare_form_response({
+      formId: plainForm.id, enduserId: plainEnduser.id,
+    })
+    await sdk.api.form_responses.submit_form_response({
+      accessCode: plainPrepared.accessCode,
+      responses: [
+        { fieldId: plainOnlyField.id, fieldTitle: plainOnlyField.title, answer: { type: 'number', value: 200 } },
+      ],
+    })
+    // barrier: the submission completed, so its side effects have had their chance
+    await poll_for(
+      () => sdk.api.form_responses.getOne(plainPrepared.response.id),
+      r => !!r.submittedAt,
+    )
+    const plainReadings = await poll_for(() => observations_for(plainEnduser.id), o => o.length > 0, 8)
+    record(
+      'C1: a Number question with no vitalUnit creates no reading',
+      plainReadings.length === 0,
+      `created ${plainReadings.length}: ${JSON.stringify(plainReadings.map(r => r.measurement))}`
+      + ` — this is what keeps every existing org and form unchanged`,
+    )
+
+    /* ===== D: blank and non-numeric answers are skipped, and never fail the submission ===== */
+
+    const skipEnduser = await sdk.api.endusers.createOne({ fname: 'Skipped', lname: 'Answers' })
+    const skipPrepared = await sdk.api.form_responses.prepare_form_response({
+      formId: form.id, enduserId: skipEnduser.id,
+    })
+
+    let submitError: any = undefined
+    try {
+      await sdk.api.form_responses.submit_form_response({
+        accessCode: skipPrepared.accessCode,
+        responses: [
+          // a blank answer for the opted-in question
+          { fieldId: weightField.id, fieldTitle: weightField.title, answer: { type: 'number', value: '' as any } },
+          { fieldId: plainField.id, fieldTitle: plainField.title, answer: { type: 'number', value: 8 } },
+        ],
+      })
+    } catch (err) { submitError = err }
+
+    record(
+      'D1: a blank answer does not fail the submission',
+      submitError === undefined,
+      `error=${submitError ? (submitError.message || JSON.stringify(submitError)) : 'none'}`
+      + ` — a patient must never see an error because of a vital reading`,
+    )
+    if (submitError === undefined) {
+      await poll_for(
+        () => sdk.api.form_responses.getOne(skipPrepared.response.id),
+        r => !!r.submittedAt,
+      )
+      const skipReadings = await poll_for(() => observations_for(skipEnduser.id), o => o.length > 0, 8)
+      record(
+        'D2: a blank answer creates no reading',
+        skipReadings.length === 0,
+        `created ${skipReadings.length}: ${JSON.stringify(skipReadings.map(r => r.measurement))}`,
+      )
+    }
+
+    // A non-numeric answer never reaches the reading code over HTTP: the submit endpoint validates
+    // a 'number' answer with numberValidator ("Response must be a number") and rejects the whole
+    // submission. Pinned here because QA step 16 is written as if the field type allowed it.
+    // The parseFloat/NaN guard in create_vital_readings_for_form_response is therefore defence in
+    // depth for the non-HTTP path (submit_form_response_internal, whose responses are persisted
+    // incrementally rather than through this validator).
+    const badEnduser = await sdk.api.endusers.createOne({ fname: 'NonNumeric', lname: 'Answer' })
+    const badPrepared = await sdk.api.form_responses.prepare_form_response({
+      formId: form.id, enduserId: badEnduser.id,
+    })
+    let badError: any = undefined
+    try {
+      await sdk.api.form_responses.submit_form_response({
+        accessCode: badPrepared.accessCode,
+        responses: [
+          { fieldId: weightField.id, fieldTitle: weightField.title, answer: { type: 'number', value: 'one hundred' as any } },
+        ],
+      })
+    } catch (err) { badError = err }
+    const badReadings = await poll_for(() => observations_for(badEnduser.id), o => o.length > 0, 8)
+    record(
+      'D3: a non-numeric answer on a Number question is rejected and creates no reading',
+      // assert the rejection too, so this check starts failing if numberValidator ever stops
+      // rejecting and the answer begins reaching create_vital_readings_for_form_response for real
+      !!badError && badReadings.length === 0,
+      `submit ${badError ? `rejected (${badError.message || JSON.stringify(badError)})` : 'ACCEPTED'};`
+      + ` ${badReadings.length} reading(s) — rejection happens in numberValidator, before this feature`,
+    )
+
+    /* ===== E: one unit per question — SBP and DBP are two questions ===== */
+
+    const bpForm = await sdk.api.forms.createOne({ title: `Blood pressure ${RAND()}` })
+    const sbpField = await sdk.api.form_fields.createOne({
+      formId: bpForm.id, title: 'Systolic', type: 'number',
+      options: { vitalUnit: 'SBP' },
+      previousFields: [{ type: 'root', info: {} }],
+    })
+    const dbpField = await sdk.api.form_fields.createOne({
+      formId: bpForm.id, title: 'Diastolic', type: 'number',
+      options: { vitalUnit: 'DBP' },
+      previousFields: [{ type: 'after', info: { fieldId: sbpField.id } }],
+    })
+    const bpEnduser = await sdk.api.endusers.createOne({ fname: 'Blood', lname: 'Pressure' })
+    const bpPrepared = await sdk.api.form_responses.prepare_form_response({
+      formId: bpForm.id, enduserId: bpEnduser.id,
+    })
+    await sdk.api.form_responses.submit_form_response({
+      accessCode: bpPrepared.accessCode,
+      responses: [
+        { fieldId: sbpField.id, fieldTitle: sbpField.title, answer: { type: 'number', value: 128 } },
+        { fieldId: dbpField.id, fieldTitle: dbpField.title, answer: { type: 'number', value: 82 } },
+      ],
+    })
+    const bpReadings = await poll_for(() => observations_for(bpEnduser.id), o => o.length >= 2)
+    const sbp = bpReadings.find(r => r.measurement?.unit === 'SBP')
+    const dbp = bpReadings.find(r => r.measurement?.unit === 'DBP')
+    record(
+      'E1: two opted-in questions produce one reading each, in their own units',
+      bpReadings.length === 2 && sbp?.measurement?.value === 128 && dbp?.measurement?.value === 82,
+      `readings=${JSON.stringify(bpReadings.map(r => r.measurement))} (want SBP 128 and DBP 82)`,
+    )
+
+    /* ===== F: an enduser with vital triggers disabled still gets the reading ===== */
+
+    const quietEnduser = await sdk.api.endusers.createOne({
+      fname: 'Quiet', lname: 'Triggers', vitalTriggersDisabled: true,
+    })
+    const quietPrepared = await sdk.api.form_responses.prepare_form_response({
+      formId: form.id, enduserId: quietEnduser.id,
+    })
+    await sdk.api.form_responses.submit_form_response({
+      accessCode: quietPrepared.accessCode,
+      responses: [
+        { fieldId: weightField.id, fieldTitle: weightField.title, answer: { type: 'number', value: 210 } },
+      ],
+    })
+    const quietReadings = await poll_for(() => observations_for(quietEnduser.id), o => o.length >= 1)
+    record(
+      'F1: the reading is still created and charted for a triggers-disabled enduser',
+      quietReadings.length === 1 && quietReadings[0]?.measurement?.value === 210,
+      `readings=${JSON.stringify(quietReadings.map(r => r.measurement))} (want one, 210 LB)`,
+    )
+    record(
+      'F2: but it is marked dontTrigger, so no Vital Update automation fires',
+      quietReadings[0]?.dontTrigger === true,
+      `dontTrigger=${JSON.stringify(quietReadings[0]?.dontTrigger)} (want true, as smartmeter.ts does)`,
+    )
+
+    /* ===== G: a partial save creates nothing — final submission only ===== */
+
+    const partialEnduser = await sdk.api.endusers.createOne({ fname: 'Partial', lname: 'Save' })
+    const partialPrepared = await sdk.api.form_responses.prepare_form_response({
+      formId: form.id, enduserId: partialEnduser.id,
+    })
+    await sdk.api.form_responses.save_field_response({
+      accessCode: partialPrepared.accessCode,
+      response: { fieldId: weightField.id, fieldTitle: weightField.title, answer: { type: 'number', value: 175 } },
+    })
+    // barrier: the draft answer is persisted, so anything the save path triggers has had its chance
+    await poll_for(
+      () => sdk.api.form_responses.getOne(partialPrepared.response.id),
+      r => !!(r.responses || []).length,
+    )
+    const partialReadings = await poll_for(() => observations_for(partialEnduser.id), o => o.length > 0, 8)
+    record(
+      'G1: a partial save creates no reading before the response is submitted',
+      partialReadings.length === 0,
+      `created ${partialReadings.length}: ${JSON.stringify(partialReadings.map(r => r.measurement))}`
+      + ` — readings are a final-submission side effect only`,
+    )
+
+
+    /* ===== H: clearing the select (vitalUnit '') is the documented off switch ===== */
+
+    // The editor writes '' rather than removing the key, so '' must read as off just like an absent
+    // vitalUnit. This is the path QA step 9 takes to turn a configured question back off.
+    const clearedForm = await sdk.api.forms.createOne({ title: `Cleared unit ${RAND()}` })
+    const clearedField = await sdk.api.form_fields.createOne({
+      formId: clearedForm.id, title: 'Weight (lbs)', type: 'number',
+      options: { vitalUnit: 'LB' },
+      previousFields: [{ type: 'root', info: {} }],
+    })
+    await sdk.api.form_fields.updateOne(clearedField.id, { options: { vitalUnit: '' } })
+    const storedCleared = await sdk.api.form_fields.getOne(clearedField.id)
+    record(
+      "H1: clearing the unit persists as '', it is not dropped back to the old value",
+      storedCleared.options?.vitalUnit === '',
+      `stored vitalUnit=${JSON.stringify(storedCleared.options?.vitalUnit)} (want '')`
+      + ` — stringValidatorOptionalEmptyOkay is what lets the empty round-trip`,
+    )
+
+    const clearedEnduser = await sdk.api.endusers.createOne({ fname: 'Cleared', lname: 'OptIn' })
+    const clearedPrepared = await sdk.api.form_responses.prepare_form_response({
+      formId: clearedForm.id, enduserId: clearedEnduser.id,
+    })
+    await sdk.api.form_responses.submit_form_response({
+      accessCode: clearedPrepared.accessCode,
+      responses: [
+        { fieldId: clearedField.id, fieldTitle: clearedField.title, answer: { type: 'number', value: 199 } },
+      ],
+    })
+    await poll_for(
+      () => sdk.api.form_responses.getOne(clearedPrepared.response.id),
+      r => !!r.submittedAt,
+    )
+    const clearedReadings = await poll_for(() => observations_for(clearedEnduser.id), o => o.length > 0, 8)
+    record(
+      'H2: a question whose unit was cleared creates no reading',
+      clearedReadings.length === 0,
+      `created ${clearedReadings.length}: ${JSON.stringify(clearedReadings.map(r => r.measurement))}`
+      + ` — the field query treats '' as off, same as an absent vitalUnit`,
+    )
+
+  } 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 form_vital_reading_tests = async () => {
+  assert_checks('Vitals from form submissions', await form_vital_reading_checks())
+}
+
+/** Enrolls this suite in the auto-discovered parallel pool — see run_discovered_isolated_suites. */
+export const ISOLATED_SUITE: IsolatedSuite = { name: 'Vitals from form submissions', run: form_vital_reading_checks }
+
+// Allow running this test file independently
+if (require.main === module) {
+  console.log(`🌐 Using API URL: ${host}`)
+  form_vital_reading_tests()
+    .then(() => {
+      console.log("✅ Vitals from form submissions test suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ Vitals from form submissions test suite failed:", error)
+      process.exit(1)
+    })
+}