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

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)
+    })
+}

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

@@ -0,0 +1,237 @@
+require('source-map-support').install();
+
+import {
+  assert_checks,
+  Check,
+  setup_isolated_tenant,
+  IsolatedSuite,
+} from "../setup_isolated"
+
+const RAND = () => Math.random().toString(36).slice(2, 10)
+
+/**
+ * Coverage for the caching added to GET /v1/journeys/statistics.
+ *
+ * The aggregation behind this endpoint runs past the proxy's 30s socket timeout on large tenants,
+ * so the handler now stores each complete result in the `cache` collection and can serve it back
+ * without aggregating (`cachedOnly: true`). The editor paints the stored blob on mount and decides
+ * for itself when to rebuild.
+ *
+ * `setup_isolated` rather than the shared fixture because these checks assert on the COMPLETE
+ * per-step counts of a journey — on the shared org, other journey suites leave automated_actions
+ * behind and every "exactly these counts" assertion would be flaky. It also gives each run its own
+ * businessId, which is what the cache key is scoped by.
+ *
+ * automated_actions are created directly rather than by driving a real journey: the counts are what
+ * is under test, and seeding them makes the expected numbers exact and the test fast.
+ *
+ * The >30s path itself is not automatable here — it needs a tenant whose aggregation genuinely
+ * exceeds the proxy timeout. What IS covered is the contract the fix rests on: a non-cachedOnly
+ * call stores a blob, and a later cachedOnly call returns that same blob without recomputing.
+ */
+export const journey_statistics_cache_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: `JourneyStatisticsCache ${RAND()}`,
+      users: [{ isAdmin: true }, { roles: ['Non-Admin'] }],
+      apiKeys: 0,
+    })
+    const { sdk, sdkNonAdmin } = tenant
+
+    /* ================= fixtures ================= */
+
+    const [journey, uncachedJourney] = await Promise.all([
+      sdk.api.journeys.createOne({ title: `Stats Cache ${RAND()}` }),
+      sdk.api.journeys.createOne({ title: `Never Computed ${RAND()}` }),
+    ])
+
+    const step = await sdk.api.automation_steps.createOne({
+      journeyId: journey.id,
+      action: { type: 'setEnduserStatus', info: { status: 'Cached Stats' } },
+      events: [{ type: 'onJourneyStart', info: {} }],
+    })
+
+    const enduser = await sdk.api.endusers.createOne({
+      fname: 'Stats', lname: 'Cache', email: `dontsend-stats-cache-${RAND()}@tellescope.com`,
+    })
+
+    // 2 finished, 1 active, 1 cancelled => count 4. processAfter is far future so the worker
+    // cannot process (and so mutate) these out from under the assertions.
+    const seed = (status: 'finished' | 'active' | 'cancelled') => sdk.api.automated_actions.createOne({
+      journeyId: journey.id,
+      automationStepId: step.id,
+      enduserId: enduser.id,
+      processAfter: Date.now() + 1000000,
+      status,
+      event: { type: 'onJourneyStart', info: {} },
+      action: { type: 'setEnduserStatus', info: { status: 'Cached Stats' } },
+    })
+    await Promise.all([seed('finished'), seed('finished'), seed('active'), seed('cancelled')])
+
+    /* ====== 1. cachedOnly on a journey that was never computed ====== */
+
+    const neverComputed = await sdk.api.journeys.get_journey_statistics({
+      journeyId: uncachedJourney.id, cachedOnly: true,
+    })
+    record(
+      '1a. cachedOnly on an uncached journey returns empty steps, not an error',
+      !!neverComputed.statistics && Object.keys(neverComputed.statistics.steps ?? {}).length === 0,
+      `statistics=${JSON.stringify(neverComputed.statistics)}`,
+    )
+    // the absence of cachedAt is the whole signal the editor uses to decide to rebuild. If this
+    // ever starts returning a timestamp for a journey that was never computed, the editor would
+    // paint zeroes and never recompute them.
+    record(
+      '1b. cachedOnly on an uncached journey returns NO cachedAt',
+      neverComputed.cachedAt === undefined || neverComputed.cachedAt === null,
+      `cachedAt=${JSON.stringify(neverComputed.cachedAt)}`,
+    )
+
+    /* ====== 2. a plain call computes fresh numbers and now carries cachedAt ====== */
+
+    const fresh = await sdk.api.journeys.get_journey_statistics({ journeyId: journey.id })
+    const freshForStep = fresh.statistics?.steps?.[step.id]
+
+    record(
+      '2a. a plain call (no new parameter) still returns the per-step counts',
+      !!freshForStep
+        && freshForStep.count === 4
+        && freshForStep.finishedCount === 2
+        && freshForStep.activeCount === 1
+        && freshForStep.cancelledCount === 1
+        && freshForStep.errorCount === 0,
+      `steps[${step.id}]=${JSON.stringify(freshForStep)}`,
+    )
+    record(
+      '2b. a plain call returns a cachedAt for the result it just stored',
+      !!fresh.cachedAt && !isNaN(new Date(fresh.cachedAt).getTime()),
+      `cachedAt=${JSON.stringify(fresh.cachedAt)}`,
+    )
+    // engagement ran (there is a step id), so clicked must be a real 0 rather than absent —
+    // absent is what drives the editor's "Opens and link clicks are unavailable" line
+    record(
+      '2c. engagement ran, so clicked is 0 rather than absent',
+      freshForStep?.clicked === 0,
+      `clicked=${JSON.stringify(freshForStep?.clicked)}`,
+    )
+
+    /* ====== 3. store-then-cachedOnly-read returns the SAME blob ====== */
+
+    const fromCache = await sdk.api.journeys.get_journey_statistics({
+      journeyId: journey.id, cachedOnly: true,
+    })
+
+    record(
+      '3a. cachedOnly returns the stored statistics verbatim',
+      JSON.stringify(fromCache.statistics) === JSON.stringify(fresh.statistics),
+      `cached=${JSON.stringify(fromCache.statistics)} fresh=${JSON.stringify(fresh.statistics)}`,
+    )
+    // the same timestamp is the proof that cachedOnly SERVED the blob rather than recomputing it
+    record(
+      '3b. cachedOnly returns the stored cachedAt, proving it did not recompute',
+      !!fromCache.cachedAt && new Date(fromCache.cachedAt).getTime() === new Date(fresh.cachedAt!).getTime(),
+      `cached=${JSON.stringify(fromCache.cachedAt)} fresh=${JSON.stringify(fresh.cachedAt)}`,
+    )
+
+    /* ====== 4. the blob is per journey, not shared across journeys ====== */
+
+    const stillUncached = await sdk.api.journeys.get_journey_statistics({
+      journeyId: uncachedJourney.id, cachedOnly: true,
+    })
+    record(
+      '4. computing one journey does not populate another journey\'s blob',
+      (stillUncached.cachedAt === undefined || stillUncached.cachedAt === null)
+        && Object.keys(stillUncached.statistics?.steps ?? {}).length === 0,
+      `cachedAt=${JSON.stringify(stillUncached.cachedAt)} steps=${JSON.stringify(stillUncached.statistics?.steps)}`,
+    )
+
+    /* ====== 5. a rebuild refreshes the stored blob ====== */
+
+    await seed('finished') // a 5th action, so a rebuild must produce different numbers
+
+    const rebuilt = await sdk.api.journeys.get_journey_statistics({ journeyId: journey.id })
+    record(
+      '5a. a rebuild picks up records added since the blob was stored',
+      rebuilt.statistics?.steps?.[step.id]?.count === 5
+        && rebuilt.statistics?.steps?.[step.id]?.finishedCount === 3,
+      `steps[${step.id}]=${JSON.stringify(rebuilt.statistics?.steps?.[step.id])}`,
+    )
+    record(
+      '5b. the rebuild advanced cachedAt',
+      !!rebuilt.cachedAt && new Date(rebuilt.cachedAt).getTime() >= new Date(fresh.cachedAt!).getTime(),
+      `rebuilt=${JSON.stringify(rebuilt.cachedAt)} previous=${JSON.stringify(fresh.cachedAt)}`,
+    )
+
+    const afterRebuild = await sdk.api.journeys.get_journey_statistics({
+      journeyId: journey.id, cachedOnly: true,
+    })
+    record(
+      '5c. the refreshed blob is what a later cachedOnly read returns',
+      afterRebuild.statistics?.steps?.[step.id]?.count === 5,
+      `steps[${step.id}]=${JSON.stringify(afterRebuild.statistics?.steps?.[step.id])}`,
+    )
+
+    /* ====== 6. metric: 'steps' is unchanged for external consumers ====== */
+
+    // the parameter documents itself as per-step counts only; it must not start returning
+    // engagement just because a blob now exists for this journey
+    const stepsOnly = await sdk.api.journeys.get_journey_statistics({
+      journeyId: journey.id, metric: 'steps',
+    })
+    const stepsOnlyForStep = stepsOnly.statistics?.steps?.[step.id] as any
+    record(
+      '6a. metric: \'steps\' still returns the counts',
+      stepsOnlyForStep?.count === 5 && stepsOnlyForStep?.finishedCount === 3,
+      `steps[${step.id}]=${JSON.stringify(stepsOnlyForStep)}`,
+    )
+    record(
+      '6b. metric: \'steps\' does not return opens/clicked',
+      stepsOnlyForStep?.opens === undefined && stepsOnlyForStep?.clicked === undefined,
+      `opens=${JSON.stringify(stepsOnlyForStep?.opens)} clicked=${JSON.stringify(stepsOnlyForStep?.clicked)}`,
+    )
+
+    /* ====== 7. the endpoint is not admin-only ====== */
+
+    const asNonAdmin = await sdkNonAdmin.api.journeys.get_journey_statistics({
+      journeyId: journey.id, cachedOnly: true,
+    })
+    record(
+      '7. a non-admin staff user can still read journey statistics',
+      asNonAdmin.statistics?.steps?.[step.id]?.count === 5,
+      `steps[${step.id}]=${JSON.stringify(asNonAdmin.statistics?.steps?.[step.id])}`,
+    )
+  } catch (err: any) {
+    record('unexpected error', false, err?.message ?? JSON.stringify(err))
+  } finally {
+    await tenant?.teardown()
+  }
+
+  return checks
+}
+
+export const journey_statistics_cache_tests = async () => {
+  assert_checks('Journey statistics cache', await journey_statistics_cache_checks())
+}
+
+/** Enrolls this suite in the auto-discovered parallel pool — see run_discovered_isolated_suites. */
+export const ISOLATED_SUITE: IsolatedSuite = { name: 'Journey statistics cache', run: journey_statistics_cache_checks }
+
+// Allow running this test file independently
+if (require.main === module) {
+  const host = process.env.API_URL || 'http://localhost:8080'
+  console.log(`🌐 Using API URL: ${host}`)
+  journey_statistics_cache_tests()
+    .then(() => {
+      console.log("✅ Journey statistics cache test suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ Journey statistics cache test suite failed:", error)
+      process.exit(1)
+    })
+}