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

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

@@ -1,27 +1,76 @@
-import { Session } from '../../sdk'
-import { log_header, wait } from "@tellescope/testing"
+require('source-map-support').install();
+
+import { wait } from "@tellescope/testing"
 import { AUTOMATED_ACTION_CANCEL_REASONS } from "@tellescope/constants"
+import {
+  assert_checks,
+  Check,
+  setup_isolated_tenant,
+  IsolatedSuite,
+} from "../setup_isolated"
+
+const host = process.env.API_URL || 'http://localhost:8080' as const
+
+const RAND = () => Math.random().toString(36).slice(2, 10)
+
+/**
+ * Deleting a journey must cascade-cancel its pending automated_actions (with the Journey Deleted
+ * reason, attributed to the deleting user) and leave finished ones untouched.
+ *
+ * Provisions its own throwaway tenant: the journey, its step and its automated_actions are org-wide
+ * records, and the cascade runs over every action of the journey.
+ */
+
+/**
+ * Polls until `evaluateFn` passes, returning the LAST value seen — a timeout returns rather than
+ * throwing, so the caller records a FAIL Check with the evidence. A rejection here would abort the
+ * whole parallel batch instead of letting the other suites report.
+ */
+const pollForResults = async <T>(
+  fetchFn: () => Promise<T>,
+  evaluateFn: (result: T) => boolean,
+  description: string,
+  intervalMs = 500,
+  maxIterations = 30,
+): Promise<{ result: T, timedOut: boolean }> => {
+  let lastResult = await fetchFn()
 
-const host = process.env.API_URL || 'http://localhost:8080'
+  for (let i = 0; i < maxIterations; i++) {
+    if (evaluateFn(lastResult)) {
+      console.log(`✓ ${description} - completed after ${i * intervalMs}ms`)
+      return { result: lastResult, timedOut: false }
+    }
 
-export const journey_delete_cancels_actions_tests = async ({ sdk, sdkNonAdmin }: { sdk: Session, sdkNonAdmin: Session }) => {
-  log_header("Journey Delete Cancels Pending Actions Tests")
+    await wait(undefined, intervalMs)
+    lastResult = await fetchFn()
+  }
+
+  console.log('Final polling result:', lastResult)
+  return { result: lastResult, timedOut: !evaluateFn(lastResult) }
+}
+
+export const journey_delete_cancels_actions_checks = async (): Promise<Check[]> => {
+  const checks: Check[] = []
+  const record = (label: string, pass: boolean, detail: string) => checks.push({ label, pass, detail })
 
-  let journeyId: string | undefined
-  let enduserId: string | undefined
-  let stepId: string | undefined
+  let tenant: Awaited<ReturnType<typeof setup_isolated_tenant>> | undefined
 
   try {
+    tenant = await setup_isolated_tenant({
+      name: `Journey delete cancels actions ${RAND()}`,
+      users: [{ isAdmin: true }],
+      apiKeys: 0,
+    })
+    const { sdk } = tenant
+
     // Create a journey + an automation_step
     const journey = await sdk.api.journeys.createOne({ title: "Cascade Cancel Journey " + Date.now() })
-    journeyId = journey.id
 
     const step = await sdk.api.automation_steps.createOne({
       journeyId: journey.id,
       action: { type: 'setEnduserStatus', info: { status: 'Test Status' } },
       events: [{ type: 'onJourneyStart', info: {} }],
     })
-    stepId = step.id
 
     // Create an enduser
     const enduser = await sdk.api.endusers.createOne({
@@ -29,7 +78,6 @@ export const journey_delete_cancels_actions_tests = async ({ sdk, sdkNonAdmin }:
       lname: 'Cancel',
       email: 'test-cascade-cancel-' + Date.now() + '@example.com',
     })
-    enduserId = enduser.id
 
     // Create an active action with a far-future processAfter so the worker won't process it during the test
     const activeAction = await sdk.api.automated_actions.createOne({
@@ -53,26 +101,24 @@ export const journey_delete_cancels_actions_tests = async ({ sdk, sdkNonAdmin }:
       action: { type: 'setEnduserStatus', info: { status: 'Test Status' } },
     })
 
-    // Assert the action starts active
+    // Check the action starts active
     const before = await sdk.api.automated_actions.getOne(activeAction.id)
-    if (before.status !== 'active') {
-      throw new Error(`Expected action to start 'active', got '${before.status}'`)
-    }
-    console.log("✓ Action is active before journey deletion")
+    record(
+      'Action is active before journey deletion',
+      before.status === 'active',
+      `status=${before.status}`,
+    )
 
     // Delete the journey — this should cascade cancel the pending action
     await sdk.api.journeys.deleteOne(journey.id)
-    journeyId = undefined // already deleted, skip in cleanup
 
     // Poll until the active action transitions to cancelled with the Journey Deleted reason,
     // attributed to the deleting user via cancelledBy
     const expectedReason = AUTOMATED_ACTION_CANCEL_REASONS.indexOf('Journey Deleted')
-    await pollForResults(
+    const { result: polled, timedOut } = await pollForResults(
       async () => {
         const actions = await sdk.api.automated_actions.getSome({ filter: { enduserId: enduser.id } })
-        const active = actions.find(a => a.id === activeAction.id)
-        const finished = actions.find(a => a.id === finishedAction.id)
-        return { active, finished }
+        return { active: actions.find(a => a.id === activeAction.id) }
       },
       ({ active }) => (
         active?.status === 'cancelled'
@@ -81,7 +127,14 @@ export const journey_delete_cancels_actions_tests = async ({ sdk, sdkNonAdmin }:
       ),
       'Active action should be cancelled with Journey Deleted reason and cancelledBy after journey deletion',
     )
-    console.log("✓ Active action cancelled with Journey Deleted reason and cancelledBy set to deleting user")
+    record(
+      'Active action cancelled with Journey Deleted reason and cancelledBy set to deleting user',
+      !timedOut,
+      timedOut
+        ? `polling timed out after ~14.5s — action=${JSON.stringify(polled.active)},`
+          + ` expected status=cancelled, cancelReason=${expectedReason}, cancelledBy=${sdk.userInfo.id}`
+        : `action=${JSON.stringify(polled.active)}`,
+    )
 
     // Not covered here: journey deletion also removes outstanding_froms_trackers. Creating a tracker
     // requires an automation to actually send an email/SMS with multiple form links, and the collection
@@ -89,58 +142,34 @@ export const journey_delete_cancels_actions_tests = async ({ sdk, sdkNonAdmin }:
 
     // Confirm the finished action was left untouched
     const finishedAfter = await sdk.api.automated_actions.getOne(finishedAction.id)
-    if (finishedAfter.status !== 'finished') {
-      throw new Error(`Expected finished action to remain 'finished', got '${finishedAfter.status}'`)
-    }
-    console.log("✓ Finished action left untouched")
-
-    console.log("✅ Journey Delete Cancels Pending Actions tests completed successfully")
+    record(
+      'Finished action left untouched',
+      finishedAfter.status === 'finished',
+      `status=${finishedAfter.status}`,
+    )
   } finally {
-    // Cleanup — journey is already deleted if the flow completed
-    await Promise.all([
-      enduserId ? sdk.api.endusers.deleteOne(enduserId).catch(() => {}) : undefined,
-      stepId ? sdk.api.automation_steps.deleteOne(stepId).catch(() => {}) : undefined,
-      journeyId ? sdk.api.journeys.deleteOne(journeyId).catch(() => {}) : undefined,
-    ])
+    // 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) } }
   }
-}
 
-const pollForResults = async <T>(
-  fetchFn: () => Promise<T>,
-  evaluateFn: (result: T) => boolean,
-  description: string,
-  intervalMs = 500,
-  maxIterations = 30,
-): Promise<void> => {
-  let lastResult: T | undefined
-
-  for (let i = 0; i < maxIterations; i++) {
-    await wait(undefined, intervalMs)
+  return checks
+}
 
-    lastResult = await fetchFn()
-    if (evaluateFn(lastResult)) {
-      console.log(`✓ ${description} - completed after ${(i + 1) * intervalMs}ms`)
-      return
-    }
-  }
+/** Asserting wrapper, for standalone runs. */
+export const journey_delete_cancels_actions_tests = async () => {
+  assert_checks('Journey delete cancels actions', await journey_delete_cancels_actions_checks())
+}
 
-  console.log('Final polling result:', lastResult)
-  throw new Error(`Polling timeout: ${description} - waited ${maxIterations * intervalMs}ms`)
+/** Enrolls this suite in the auto-discovered parallel pool — see run_discovered_isolated_suites. */
+export const ISOLATED_SUITE: IsolatedSuite = {
+  name: 'Journey delete cancels actions',
+  run: journey_delete_cancels_actions_checks,
 }
 
 // Allow running this test file independently
 if (require.main === module) {
   console.log(`🌐 Using API URL: ${host}`)
-  const sdk = new Session({ host })
-  const sdkNonAdmin = new Session({ host })
-
-  const runTests = async () => {
-    const { setup_tests } = await import("../setup")
-    await setup_tests(sdk, sdkNonAdmin)
-    await journey_delete_cancels_actions_tests({ sdk, sdkNonAdmin })
-  }
-
-  runTests()
+  journey_delete_cancels_actions_tests()
     .then(() => {
       console.log("✅ Journey Delete Cancels Pending Actions test suite completed successfully")
       process.exit(0)

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