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

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

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

@@ -0,0 +1,220 @@
+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)
+
+/**
+ * The backend contract behind the Journey editor's manual per-step count.
+ *
+ * When the journey statistics aggregation cannot produce numbers, a step node offers a "Get count"
+ * link that counts that one step through the ORDINARY automated_actions read — no new endpoint:
+ *
+ *     automated_actions.getSome({ returnCount: true, filter: { automationStepId } })
+ *     automated_actions.getSome({ returnCount: true, filter: { automationStepId, status: 'finished' } })
+ *
+ * Two properties the UI depends on and that nothing else covers:
+ *
+ *   1. `returnCount` resolves to `{ count }` (not a list), and `filter` is actually applied to the
+ *      count — `queries.count` takes a different code path from `findPage`, so "the filter is
+ *      honoured" is a real assertion, not a tautology. A count that ignored `filter` would silently
+ *      report the whole tenant's automated_actions on every step.
+ *   2. The count is session-scoped the same way the list read is, so it equals the number of rows
+ *      the step drawer lists for that same session. This is what makes a lower number for a
+ *      restricted user correct rather than a bug — and it is asserted by comparing the count with
+ *      the rows, for an admin and for a non-admin, rather than by hardcoding either access level.
+ *
+ * `setup_isolated` because every assertion here is an exact count over a whole businessId
+ * partition; on the shared org, other journey suites leave automated_actions behind.
+ *
+ * automated_actions are seeded directly rather than by driving a real journey: the counts are what
+ * is under test, and seeding makes the expected numbers exact and the run fast. `processAfter` is
+ * far in the future so the worker cannot process (and so mutate) them mid-assertion.
+ */
+export const journey_step_manual_count_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: `JourneyStepManualCount ${RAND()}`,
+      users: [{ isAdmin: true }, { roles: ['Non-Admin'] }],
+      apiKeys: 0,
+    })
+    const { sdk, sdkNonAdmin } = tenant
+
+    /* ================= fixtures ================= */
+
+    const journey = await sdk.api.journeys.createOne({ title: `Manual Count ${RAND()}` })
+
+    const makeStep = (status: string) => sdk.api.automation_steps.createOne({
+      journeyId: journey.id,
+      action: { type: 'setEnduserStatus', info: { status } },
+      events: [{ type: 'onJourneyStart', info: {} }],
+    })
+    // counted, a second step to prove the filter discriminates, and one that is never entered
+    const [countedStep, otherStep, emptyStep] = await Promise.all([
+      makeStep('Counted'), makeStep('Other'), makeStep('Empty'),
+    ])
+
+    const enduser = await sdk.api.endusers.createOne({
+      fname: 'Manual', lname: 'Count', email: `dontsend-manual-count-${RAND()}@tellescope.com`,
+    })
+
+    const seed = (automationStepId: string, status: 'finished' | 'active' | 'cancelled' | 'error') => (
+      sdk.api.automated_actions.createOne({
+        journeyId: journey.id,
+        automationStepId,
+        enduserId: enduser.id,
+        processAfter: Date.now() + 1000000,
+        status,
+        event: { type: 'onJourneyStart', info: {} },
+        action: { type: 'setEnduserStatus', info: { status: 'Counted' } },
+      })
+    )
+
+    // countedStep: 3 finished, 2 active, 1 cancelled, 1 error => total 7, finished 3.
+    // The non-finished statuses matter: the UI shows Total and Finished only, so a count that
+    // quietly excluded cancelled/error rows would still look plausible with a simpler fixture.
+    await Promise.all([
+      seed(countedStep.id, 'finished'), seed(countedStep.id, 'finished'), seed(countedStep.id, 'finished'),
+      seed(countedStep.id, 'active'), seed(countedStep.id, 'active'),
+      seed(countedStep.id, 'cancelled'),
+      seed(countedStep.id, 'error'),
+      // a second step, so a filter that was dropped would report 9 rather than 7
+      seed(otherStep.id, 'finished'), seed(otherStep.id, 'active'),
+    ])
+
+    /* ================= helpers ================= */
+
+    // getSome is typed Promise<T[]>, but a returnCount read resolves to { count }
+    const count_for = async (session: typeof sdk, automationStepId: string, status?: string) => (
+      await session.api.automated_actions.getSome({
+        returnCount: true,
+        filter: { automationStepId, ...(status ? { status } : { }) } as any,
+      }) as unknown as { count?: number }
+    )
+
+    const rows_for = (session: typeof sdk, automationStepId: string, status?: string) => (
+      session.api.automated_actions.getSome({
+        limit: 100, // the step drawer's page size
+        filter: { automationStepId, ...(status ? { status } : { }) } as any,
+      })
+    )
+
+    /* ====== 1. returnCount + filter: the shape and the arithmetic ====== */
+
+    const total = await count_for(sdk, countedStep.id)
+    record(
+      '1a. returnCount resolves to { count }, not a list of records',
+      !Array.isArray(total) && typeof total?.count === 'number',
+      `response=${JSON.stringify(total)}`,
+    )
+    record(
+      '1b. the count is filtered to the step, counting every status',
+      total?.count === 7,
+      `count=${JSON.stringify(total?.count)}, expected 7 (3 finished + 2 active + 1 cancelled + 1 error)`,
+    )
+
+    const finished = await count_for(sdk, countedStep.id, 'finished')
+    record(
+      '1c. adding status: finished narrows the same count',
+      finished?.count === 3,
+      `count=${JSON.stringify(finished?.count)}, expected 3`,
+    )
+
+    // if `filter` were dropped on the count path, both steps would report the tenant-wide 9
+    const otherTotal = await count_for(sdk, otherStep.id)
+    record(
+      '1d. a different step counts separately, so the filter is genuinely applied',
+      otherTotal?.count === 2,
+      `count=${JSON.stringify(otherTotal?.count)}, expected 2 (and NOT 9, the tenant-wide total)`,
+    )
+
+    // QA step 13: a step nobody has entered is 0, not a failure
+    const emptyTotal = await count_for(sdk, emptyStep.id)
+    record(
+      '1e. a step with no automated actions counts 0 rather than erroring',
+      emptyTotal?.count === 0,
+      `count=${JSON.stringify(emptyTotal?.count)}`,
+    )
+
+    /* ====== 2. the count equals the rows the step drawer lists ====== */
+
+    const [adminRows, adminFinishedRows] = await Promise.all([
+      rows_for(sdk, countedStep.id),
+      rows_for(sdk, countedStep.id, 'finished'),
+    ])
+    record(
+      '2a. the admin count equals the rows the same session can list',
+      total?.count === adminRows.length && finished?.count === adminFinishedRows.length,
+      `count=${total?.count} vs rows=${adminRows.length};`
+      + ` finished count=${finished?.count} vs rows=${adminFinishedRows.length}`,
+    )
+
+    /* ====== 3. the count is session-scoped, the same way the list read is ====== */
+
+    // The point is NOT that a non-admin sees a particular number — that depends on the tenant's
+    // role-based access for automated_actions. It is that whatever they can READ is what they
+    // COUNT, so the number on the node always matches the drawer they open from it.
+    const [nonAdminTotal, nonAdminFinished] = await Promise.all([
+      count_for(sdkNonAdmin, countedStep.id),
+      count_for(sdkNonAdmin, countedStep.id, 'finished'),
+    ])
+    const [nonAdminRows, nonAdminFinishedRows] = await Promise.all([
+      rows_for(sdkNonAdmin, countedStep.id),
+      rows_for(sdkNonAdmin, countedStep.id, 'finished'),
+    ])
+
+    record(
+      '3a. a non-admin count equals the rows that non-admin can list',
+      nonAdminTotal?.count === nonAdminRows.length
+        && nonAdminFinished?.count === nonAdminFinishedRows.length,
+      `count=${nonAdminTotal?.count} vs rows=${nonAdminRows.length};`
+      + ` finished count=${nonAdminFinished?.count} vs rows=${nonAdminFinishedRows.length}`,
+    )
+    // a restricted session may legitimately count lower, but never higher than the admin
+    record(
+      '3b. a non-admin never counts more than the admin',
+      (nonAdminTotal?.count ?? 0) <= (total?.count ?? 0)
+        && (nonAdminFinished?.count ?? 0) <= (finished?.count ?? 0),
+      `non-admin total=${nonAdminTotal?.count} vs admin ${total?.count};`
+      + ` non-admin finished=${nonAdminFinished?.count} vs admin ${finished?.count}`,
+    )
+    record(
+      '3c. finished never exceeds the total, for either session',
+      (finished?.count ?? 0) <= (total?.count ?? 0)
+        && (nonAdminFinished?.count ?? 0) <= (nonAdminTotal?.count ?? 0),
+      `admin ${finished?.count}/${total?.count}, non-admin ${nonAdminFinished?.count}/${nonAdminTotal?.count}`,
+    )
+
+    return checks
+  } finally {
+    await tenant?.teardown()
+  }
+}
+
+/** Asserting wrapper, for standalone runs. */
+export const journey_step_manual_count_tests = async () => {
+  assert_checks('Journey step manual count', await journey_step_manual_count_checks())
+}
+
+/** Enrolls this suite in the auto-discovered parallel pool — see run_discovered_isolated_suites. */
+export const ISOLATED_SUITE: IsolatedSuite = { name: 'Journey step manual count', run: journey_step_manual_count_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_step_manual_count_tests()
+  .then(() => { console.log("✅ Journey step manual count tests passed"); process.exit(0) })
+  .catch(error => { console.error("❌ Journey step manual count tests failed:", error); process.exit(1) })
+}

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

@@ -0,0 +1,214 @@
+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)
+
+/**
+ * Coverage for the `careTeamUserIds` parameter on `load_threads` (GET /v1/inbox-threads/load).
+ *
+ * The caller used to resolve "every patient these users are on the care team for" client-side and
+ * push the resulting enduser ids into `mdbFilter`. For a care team of hundreds of patients that
+ * overflows the GET query string (Node's 16KB header limit) before any Tellescope code runs. The
+ * parameter moves the join to the server: the API resolves the user ids to endusers via
+ * `assignedTo`, and ANDs `{ enduserIds: { $in: [...] } }` onto the thread filter.
+ *
+ * `setup_isolated` rather than `setup_tests` because several checks assert on the COMPLETE thread
+ * set of the tenant. On the shared fixture org, `build_threads` and the other inbox suites leave
+ * threads behind and every "returns exactly these" assertion would be flaky.
+ *
+ * The threads are created directly with `inbox_threads.createOne` (the model exposes create for
+ * exactly this reason) rather than via `build_threads`, so the tenant contains exactly three.
+ *
+ * Check 4 is the one that catches a wrong implementation: a care team with no patients resolves to
+ * an empty enduser list, and the clause must still be applied (returning nothing) rather than
+ * dropped (returning everything). Check 5 is its counterweight — it rules out an implementation
+ * that returns nothing for every call, which would satisfy 3, 4 and 7c vacuously.
+ *
+ * Check 7 is the permission boundary. A provisioned non-admin gets
+ * `sms_messages: ASSIGNED_AND_DEFAULT_ACCESS` (read: 'Assigned'), and the fixture threads carry
+ * `userIds: []`, so that session sees a thread only through the assigned-enduser branch. 7c fails
+ * if the care-team clause is ever pushed into the access `$or` instead of `filter.$and`, i.e. if
+ * the parameter could be used to WIDEN what a session can see.
+ */
+export const load_threads_care_team_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 {
+    /* ================= fixtures ================= */
+
+    tenant = await setup_isolated_tenant({
+      name: `LoadThreadsCareTeam ${RAND()}`,
+      users: [{ isAdmin: true }, { roles: ['Non-Admin'] }],
+      apiKeys: 0,
+    })
+
+    const { sdk, sdkNonAdmin } = tenant
+    const NA = tenant.users[1].id // the non-admin's own user id
+
+    // care-team users: they never log in, they exist only to appear in endusers.assignedTo
+    const [U1, U2, U3] = await Promise.all([1, 2, 3].map(n => sdk.api.users.createOne({
+      email: `dontsend-care-team-${n}-${RAND()}@tellescope.com`,
+      fname: 'CareTeam', lname: `User${n}`,
+      verifiedEmail: true,
+      notificationEmailsDisabled: true,
+    })))
+
+    // E1 is also assigned to the non-admin, so check 7a has a non-empty baseline to measure against
+    const E1 = await sdk.api.endusers.createOne({ fname: 'CareTeam', lname: 'PatientOne', assignedTo: [U1.id, NA] })
+    const E2 = await sdk.api.endusers.createOne({ fname: 'CareTeam', lname: 'PatientTwo', assignedTo: [U2.id] })
+    const E3 = await sdk.api.endusers.createOne({ fname: 'CareTeam', lname: 'PatientThree', assignedTo: [] })
+
+    const now = Date.now()
+    const MINUTE = 60 * 1000
+    const defaultThreadFields = {
+      type: 'SMS' as const,
+      assignedTo: [],
+      userIds: [],
+      inboxStatus: 'New',
+      preview: 'care team test',
+      title: 'Care team test',
+    }
+
+    const T1 = await sdk.api.inbox_threads.createOne({
+      ...defaultThreadFields,
+      enduserIds: [E1.id], threadId: `care-team-t1-${RAND()}`, timestamp: new Date(now - 3 * MINUTE),
+    })
+    const T2 = await sdk.api.inbox_threads.createOne({
+      ...defaultThreadFields,
+      enduserIds: [E2.id], threadId: `care-team-t2-${RAND()}`, timestamp: new Date(now - 2 * MINUTE),
+    })
+    const T3 = await sdk.api.inbox_threads.createOne({
+      ...defaultThreadFields,
+      enduserIds: [E3.id], threadId: `care-team-t3-${RAND()}`, timestamp: new Date(now - 1 * MINUTE),
+    })
+
+    const label_for: { [id: string]: string } = { [T1.id]: 'T1', [T2.id]: 'T2', [T3.id]: 'T3' }
+    const describe = (ids: string[]) => `[${ids.map(id => label_for[id] || id).sort().join(', ')}]`
+    const load = async (args: any, session = sdk) => (
+      (await session.api.inbox_threads.load_threads(args)).threads.map(t => t.id)
+    )
+    const same_set = (a: string[], b: string[]) => (
+      a.length === b.length && [...a].sort().join() === [...b].sort().join()
+    )
+
+    /* ===== 1: a single care-team user ===== */
+
+    const one = await load({ careTeamUserIds: [U1.id] })
+    record(
+      '1: careTeamUserIds=[U1] returns exactly the thread for U1\'s patient',
+      same_set(one, [T1.id]),
+      `got ${describe(one)} (want [T1])`,
+    )
+
+    /* ===== 2: multiple care-team users union their patients ===== */
+
+    const two = await load({ careTeamUserIds: [U1.id, U2.id] })
+    record(
+      '2: careTeamUserIds=[U1, U2] returns both their threads and not the unassigned one',
+      same_set(two, [T1.id, T2.id]),
+      `got ${describe(two)} (want [T1, T2] — T3\'s enduser has an empty care team)`,
+    )
+
+    /* ===== 3: ANDs with enduserIds rather than ORing ===== */
+
+    const intersect = await load({ careTeamUserIds: [U2.id], enduserIds: [E1.id] })
+    record(
+      '3: careTeamUserIds AND enduserIds narrows to the intersection',
+      intersect.length === 0,
+      `got ${describe(intersect)} (want [] — E1 is not on U2\'s care team; a non-empty result means the`
+      + ` two filters OR instead of AND)`,
+    )
+
+    /* ===== 4: an empty resolution must not degrade to "no filter" ===== */
+
+    const emptyCareTeam = await load({ careTeamUserIds: [U3.id] })
+    record(
+      '4: a care-team user with no patients returns no threads, not every thread',
+      emptyCareTeam.length === 0,
+      `got ${describe(emptyCareTeam)} (want [] — returning all three means the clause was dropped when`
+      + ` the enduser lookup came back empty)`,
+    )
+
+    /* ===== 5: the feature-off path is unchanged ===== */
+
+    const baseline = await load({})
+    const emptyParam = await load({ careTeamUserIds: [] })
+    record(
+      '5: omitting careTeamUserIds, and passing [], both return exactly the three fixture threads',
+      same_set(baseline, [T1.id, T2.id, T3.id]) && same_set(emptyParam, baseline),
+      `omitted=${describe(baseline)} empty=${describe(emptyParam)} (want [T1, T2, T3] for both)`,
+    )
+
+    /* ===== 6: the count path shares the filter ===== */
+
+    const { count } = await sdk.api.inbox_threads.load_threads({ careTeamUserIds: [U1.id], returnCount: true })
+    record(
+      '6: returnCount applies the care-team filter too',
+      count === 1,
+      `count=${count} (want 1 — 3 means the count path skipped the filter)`,
+    )
+
+    /* ===== 7: permission boundary — the parameter can only narrow, never widen ===== */
+
+    const naBaseline = await load({}, sdkNonAdmin)
+    record(
+      '7a: the non-admin\'s unfiltered inbox is exactly the thread for the patient assigned to them',
+      same_set(naBaseline, [T1.id]),
+      `got ${describe(naBaseline)} (want [T1] — the baseline the next two checks are measured against;`
+      + ` if this is empty, 7b and 7c pass vacuously)`,
+    )
+
+    const naOwnCareTeam = await load({ careTeamUserIds: [U1.id] }, sdkNonAdmin)
+    record(
+      '7b: the parameter does not remove a thread the non-admin legitimately sees',
+      same_set(naOwnCareTeam, [T1.id]),
+      `got ${describe(naOwnCareTeam)} (want [T1])`,
+    )
+
+    const naForeignCareTeam = await load({ careTeamUserIds: [U2.id] }, sdkNonAdmin)
+    record(
+      '7c: the parameter cannot reach a thread outside the non-admin\'s access',
+      naForeignCareTeam.length === 0,
+      `got ${describe(naForeignCareTeam)} (want [] — T2 matches U2\'s care team but is outside this`
+      + ` session's access; a non-empty result means the clause was pushed into the access $or)`,
+    )
+  } finally {
+    // Teardown BEFORE anything asserts — assert calls process.exit, which would strand the 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 load_threads_care_team_tests = async () => {
+  assert_checks('Load threads care team', await load_threads_care_team_checks())
+}
+
+/** Enrolls this suite in the auto-discovered parallel pool — see run_discovered_isolated_suites. */
+export const ISOLATED_SUITE: IsolatedSuite = { name: 'Load threads care team', run: load_threads_care_team_checks }
+
+// Allow running this test file independently
+if (require.main === module) {
+  console.log(`🌐 Using API URL: ${host}`)
+  load_threads_care_team_tests()
+    .then(() => {
+      console.log("✅ Load threads care team test suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ Load threads care team test suite failed:", error)
+      process.exit(1)
+    })
+}