@tellescope/sdk 2.0.0-beta.0 → 2.0.0-beta.2

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

@@ -0,0 +1,351 @@
+require('source-map-support').install();
+
+import { EnduserSession } from "../../enduser"
+import { EnduserProgram } from "@tellescope/types-models"
+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 `programs` field on Enduser / EnduserObservation / EnduserOrder, and for the
+ * `programs` filter on the Order Status Equals and Vital Update automation triggers.
+ *
+ * `EnduserOrder.programs` and `EnduserObservation.programs` are lists of `{ name }` objects; the
+ * trigger's `info.programs` is a list of names. A trigger matches when the two overlap, and — the part
+ * that matters most — a trigger with NO programs filter must keep matching every record, since that is
+ * every trigger that exists today.
+ *
+ * Both handlers apply the filter in JS after loading candidate triggers:
+ *   - handle_order_status_equals, api/modules/automation_triggers.ts
+ *   - handle_vital_create, api/v1/event_handlers_v2/vitals.ts
+ *
+ * This suite provisions its own throwaway tenant. That is not optional here: `vital_configurations`
+ * are business-wide (handle_vital_create reads them with `enduserId: { $exists: false }` across the
+ * businessId), so running on the shared fixture 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.
+ *
+ * Every check gets its own enduser: triggers are throttled to one fire per trigger per enduser per
+ * minute, so reusing a patient across checks would silently swallow the second fire.
+ *
+ * Triggers fire asynchronously. Each check polls for the unfiltered trigger's tag and uses that as the
+ * synchronization barrier, then asserts on the filtered trigger's tag. Without the barrier a negative
+ * check would pass merely by reading too early.
+ */
+
+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 programs_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: `ProgramFilters ${RAND()}`,
+      users: [{ isAdmin: true }],
+      apiKeys: 0,
+    })
+    const { sdk } = tenant
+
+    /* ===================== Enduser.programs ===================== */
+
+    const programsEnduser = await sdk.api.endusers.createOne({
+      fname: 'Programs',
+      lname: 'Field',
+      email: `programs-field-${RAND()}@tellescope.example`,
+      devices: [{ title: 'Cuff', id: `dev-a-${RAND()}` }, { title: 'Scale', id: `dev-b-${RAND()}` }],
+      programs: [
+        { name: 'CHF', deviceIds: ['dev-a'], status: 'Active' },
+        { name: 'Diabetes' }, // deviceIds and status are optional
+      ],
+    })
+
+    const createdPrograms = (await sdk.api.endusers.getOne(programsEnduser.id)).programs
+    record(
+      'F: Enduser.programs round-trips on create, with and without deviceIds / status',
+      createdPrograms?.length === 2
+      && createdPrograms[0].name === 'CHF'
+      && JSON.stringify(createdPrograms[0].deviceIds) === JSON.stringify(['dev-a'])
+      && createdPrograms[0].status === 'Active'
+      && createdPrograms[1].name === 'Diabetes'
+      && createdPrograms[1].deviceIds === undefined
+      && createdPrograms[1].status === undefined,
+      `programs=${JSON.stringify(createdPrograms)}`,
+    )
+
+    await sdk.api.endusers.updateOne(
+      programsEnduser.id,
+      { programs: [{ name: 'CHF', deviceIds: ['dev-a', 'dev-b'] }] },
+      { replaceObjectFields: true },
+    )
+    const replacedPrograms = (await sdk.api.endusers.getOne(programsEnduser.id)).programs
+    record(
+      'G: updating programs with replaceObjectFields replaces the whole list',
+      replacedPrograms?.length === 1
+      && replacedPrograms[0].name === 'CHF'
+      && JSON.stringify(replacedPrograms[0].deviceIds) === JSON.stringify(['dev-a', 'dev-b']),
+      `programs=${JSON.stringify(replacedPrograms)}`,
+    )
+
+    // name carries a non-optional validator inside the object validator, so it is required per item
+    let missingNameError = ''
+    try {
+      await sdk.api.endusers.updateOne(programsEnduser.id, { programs: [{ deviceIds: ['dev-a'] } as any] })
+    } catch (err: any) { missingNameError = err?.message ?? String(err) }
+    record(
+      'H: a program entry without a name is rejected',
+      missingNameError.includes('name'),
+      `error=${JSON.stringify(missingNameError) || '(none — the write was ACCEPTED)'}`,
+    )
+
+    /* --- programs is staff-only: redacted from enduser sessions, and not enduser-updatable --- */
+
+    const { authToken } = await sdk.api.endusers.generate_auth_token({ id: programsEnduser.id })
+    const enduserSession = new EnduserSession({ host, authToken, businessId: tenant.businessId })
+    await enduserSession.refresh_session()
+
+    const selfRead = await enduserSession.api.endusers.getOne(programsEnduser.id)
+    record(
+      'I: Enduser.programs is redacted from the enduser\'s own read of their record',
+      selfRead.programs === undefined,
+      `enduser-session programs=${JSON.stringify(selfRead.programs)}`,
+    )
+
+    let selfUpdateError = ''
+    try {
+      await enduserSession.api.endusers.updateOne(programsEnduser.id, { programs: [{ name: 'Self Assigned' }] })
+    } catch (err: any) { selfUpdateError = err?.message ?? String(err) }
+    const afterSelfUpdate = (await sdk.api.endusers.getOne(programsEnduser.id)).programs
+    record(
+      'J: an enduser cannot update their own programs',
+      selfUpdateError.includes('cannot be updated by endusers')
+      && afterSelfUpdate?.length === 1 && afterSelfUpdate[0].name === 'CHF',
+      `error=${JSON.stringify(selfUpdateError) || '(none — the write was ACCEPTED)'}`
+      + ` programs=${JSON.stringify(afterSelfUpdate)}`,
+    )
+
+    /* ===================== Order Status Equals ===================== */
+
+    const ORDER_SOURCE = `ProgramFilterSource${RAND()}`
+
+    await sdk.api.automation_triggers.createOne({
+      event: { type: 'Order Status Equals', info: { source: ORDER_SOURCE, status: 'shipped', programs: ['CHF'] } },
+      action: { type: 'Add Tags', info: { tags: ['order-chf'] } },
+      status: 'Active',
+      title: `Order programs=[CHF] ${RAND()}`,
+    })
+    // no programs filter — the shape of every trigger that exists today; must match regardless
+    await sdk.api.automation_triggers.createOne({
+      event: { type: 'Order Status Equals', info: { source: ORDER_SOURCE, status: 'shipped' } },
+      action: { type: 'Add Tags', info: { tags: ['order-any'] } },
+      status: 'Active',
+      title: `Order programs unset ${RAND()}`,
+    })
+
+    const create_order = async (enduserId: string, programs?: { name: string }[]) => (
+      sdk.api.enduser_orders.createOne({
+        enduserId,
+        source: ORDER_SOURCE,
+        externalId: `ext-${RAND()}`,
+        title: 'Program filter order',
+        status: 'shipped',
+        ...(programs ? { programs } : {}),
+      })
+    )
+
+    const tags_after_order = async (programs: { name: string }[] | undefined) => {
+      const enduser = await sdk.api.endusers.createOne({ fname: 'Programs', lname: 'Order' })
+      await create_order(enduser.id, programs)
+      // the unfiltered trigger always fires, so its tag is the barrier that makes an absence meaningful
+      const after = await poll_for(
+        () => sdk.api.endusers.getOne(enduser.id),
+        e => !!e.tags?.includes('order-any'),
+      )
+      return after.tags ?? []
+    }
+
+    const orderMatching = await tags_after_order([{ name: 'CHF' }])
+    record(
+      'A: Order Status Equals with programs=[CHF] fires for an order in program CHF',
+      orderMatching.includes('order-chf') && orderMatching.includes('order-any'),
+      `tags=${JSON.stringify(orderMatching)}`,
+    )
+
+    const orderNonMatching = await tags_after_order([{ name: 'Diabetes' }])
+    record(
+      'B: Order Status Equals with programs=[CHF] does NOT fire for an order in program Diabetes',
+      !orderNonMatching.includes('order-chf') && orderNonMatching.includes('order-any'),
+      `tags=${JSON.stringify(orderNonMatching)}`,
+    )
+
+    const orderNoPrograms = await tags_after_order(undefined)
+    record(
+      'C: Order Status Equals with programs=[CHF] does NOT fire for an order with no programs,'
+      + ' while the unfiltered trigger still does (back-compat)',
+      !orderNoPrograms.includes('order-chf') && orderNoPrograms.includes('order-any'),
+      `tags=${JSON.stringify(orderNoPrograms)}`,
+    )
+
+    /* ===================== Vital Update ===================== */
+
+    const configuration = await sdk.api.vital_configurations.createOne({
+      title: `Program filter SBP ${RAND()}`,
+      unit: 'SBP',
+      ranges: [
+        {
+          classification: 'High',
+          comparison: { type: 'Greater Than', value: 200 },
+        },
+      ],
+    })
+
+    await sdk.api.automation_triggers.createOne({
+      event: {
+        type: 'Vital Update',
+        info: { configurationIds: [configuration.id], classifications: ['High'], programs: ['CHF'] },
+      },
+      action: { type: 'Add Tags', info: { tags: ['vital-chf'] } },
+      status: 'Active',
+      title: `Vital programs=[CHF] ${RAND()}`,
+    })
+    await sdk.api.automation_triggers.createOne({
+      event: {
+        type: 'Vital Update',
+        info: { configurationIds: [configuration.id], classifications: ['High'] },
+      },
+      action: { type: 'Add Tags', info: { tags: ['vital-any'] } },
+      status: 'Active',
+      title: `Vital programs unset ${RAND()}`,
+    })
+
+    const tags_after_reading = async (programs: { name: string }[] | undefined) => {
+      const enduser = await sdk.api.endusers.createOne({ fname: 'Programs', lname: 'Vital' })
+      await sdk.api.enduser_observations.createOne({
+        category: 'vital-signs',
+        status: 'final',
+        enduserId: enduser.id,
+        measurement: { unit: 'SBP', value: 250 }, // High
+        timestamp: new Date(),
+        ...(programs ? { programs } : {}),
+      })
+      const after = await poll_for(
+        () => sdk.api.endusers.getOne(enduser.id),
+        e => !!e.tags?.includes('vital-any'),
+      )
+      return after.tags ?? []
+    }
+
+    const vitalMatching = await tags_after_reading([{ name: 'CHF' }])
+    record(
+      'D: Vital Update with programs=[CHF] fires for a reading in program CHF',
+      vitalMatching.includes('vital-chf') && vitalMatching.includes('vital-any'),
+      `tags=${JSON.stringify(vitalMatching)}`,
+    )
+
+    const vitalNonMatching = await tags_after_reading([{ name: 'Diabetes' }])
+    record(
+      'E: Vital Update with programs=[CHF] does NOT fire for a reading in program Diabetes,'
+      + ' while the unfiltered trigger still does (back-compat)',
+      !vitalNonMatching.includes('vital-chf') && vitalNonMatching.includes('vital-any'),
+      `tags=${JSON.stringify(vitalNonMatching)}`,
+    )
+
+    /* =============== Programs as a trigger enduserCondition (conditional logic) =============== */
+
+    // The `Programs` key is evaluated by evaluate_conditional_logic_for_enduser_fields, which is what
+    // handle_actions_for_triggers runs every trigger's enduserCondition through. These two checks are the
+    // end-to-end proof that a condition built in the UI actually gates a real trigger fire.
+    const CONDITION_FIELD = `ProgramConditionKey${RAND()}`
+
+    await sdk.api.automation_triggers.createOne({
+      event: { type: 'Field Equals', info: { field: CONDITION_FIELD, value: 'go' } },
+      action: { type: 'Add Tags', info: { tags: ['condition-chf'] } },
+      enduserCondition: { $and: [{ condition: { Programs: { $in: 'CHF' } } }] },
+      status: 'Active',
+      title: `Programs condition Is In CHF ${RAND()}`,
+    })
+    // the same event with no enduserCondition — the barrier that makes an absence above meaningful
+    await sdk.api.automation_triggers.createOne({
+      event: { type: 'Field Equals', info: { field: CONDITION_FIELD, value: 'go' } },
+      action: { type: 'Add Tags', info: { tags: ['condition-any'] } },
+      status: 'Active',
+      title: `Programs condition unset ${RAND()}`,
+    })
+
+    // `waitFor` is the tag that makes the read meaningful. For the positive check that is the
+    // conditioned trigger's own tag — the two triggers are dispatched by separate awaited calls, so the
+    // unconditioned trigger's tag can land first and polling on it alone would read too early. For the
+    // negative check, where there is no tag to wait for, the unconditioned trigger is the barrier.
+    const tags_after_create = async (programs: EnduserProgram[] | undefined, waitFor: string) => {
+      const enduser = await sdk.api.endusers.createOne({
+        fname: 'Programs',
+        lname: 'Condition',
+        fields: { [CONDITION_FIELD]: 'go' },
+        ...(programs ? { programs } : {}),
+      })
+      const after = await poll_for(
+        () => sdk.api.endusers.getOne(enduser.id),
+        e => !!e.tags?.includes(waitFor),
+      )
+      return after.tags ?? []
+    }
+
+    const conditionMatching = await tags_after_create([{ name: 'CHF', status: 'active' }], 'condition-chf')
+    record(
+      'K: a trigger with a Programs Is In CHF enduserCondition fires for a patient in program CHF',
+      conditionMatching.includes('condition-chf') && conditionMatching.includes('condition-any'),
+      `tags=${JSON.stringify(conditionMatching)}`,
+    )
+
+    const conditionNonMatching = await tags_after_create(undefined, 'condition-any')
+    record(
+      'L: the same trigger does NOT fire for a patient with no programs,'
+      + ' while the unconditioned trigger still does',
+      !conditionNonMatching.includes('condition-chf') && conditionNonMatching.includes('condition-any'),
+      `tags=${JSON.stringify(conditionNonMatching)}`,
+    )
+  } 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 programs_tests = async () => {
+  assert_checks('Programs', await programs_checks())
+}
+
+/** Enrolls this suite in the auto-discovered parallel pool — see run_discovered_isolated_suites. */
+export const ISOLATED_SUITE: IsolatedSuite = { name: 'Programs', run: programs_checks }
+
+// Allow running this test file independently
+if (require.main === module) {
+  console.log(`🌐 Using API URL: ${host}`)
+  programs_tests()
+    .then(() => {
+      console.log("✅ Programs test suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ Programs test suite failed:", error)
+      process.exit(1)
+    })
+}