@tellescope/sdk 1.256.13 → 1.256.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tellescope/sdk",
-  "version": "1.256.13",
+  "version": "1.256.15",
   "description": "Code for interacting with the Tellescope API",
   "main": "./lib/cjs/sdk.js",
   "module": "./lib/esm/sdk.js",
@@ -32,14 +32,14 @@
   },
   "homepage": "https://github.com/tellescope-os/tellescope#readme",
   "dependencies": {
-    "@tellescope/constants": "1.256.13",
-    "@tellescope/schema": "1.256.13",
-    "@tellescope/testing": "1.256.13",
-    "@tellescope/types-client": "1.256.13",
-    "@tellescope/types-models": "1.256.13",
-    "@tellescope/types-utilities": "1.256.13",
-    "@tellescope/utilities": "1.256.13",
-    "@tellescope/validation": "1.256.13",
+    "@tellescope/constants": "1.256.15",
+    "@tellescope/schema": "1.256.15",
+    "@tellescope/testing": "1.256.15",
+    "@tellescope/types-client": "1.256.15",
+    "@tellescope/types-models": "1.256.15",
+    "@tellescope/types-utilities": "1.256.15",
+    "@tellescope/utilities": "1.256.15",
+    "@tellescope/validation": "1.256.15",
     "axios": "0.30.3",
     "dotenv": "14.3.2",
     "form-data": "4.0.4",
@@ -55,5 +55,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "457e037174ead2b05f585d810de05f724659430a"
+  "gitHead": "180f82301125bdd5e73608991061e49ed3d41e96"
 }

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

@@ -589,7 +589,7 @@ export const auto_merge_form_submission_tests = async ({ sdk, sdkNonAdmin }: { s
         // Filling a BLANK phone is deliberately blocked too — contact-less patients are the primary
         // takeover target, so "fill only if empty" would not close the hole. Staff update these fields.
         // Previously this test asserted `phone === newPhone`; that behaviour was the vulnerability.
-        // See api_tests/security/public_endpoint_auth_field_lock.test.ts (G26).
+        // See api_tests/security/public_endpoint_auth_field_lock.test.ts.
         && !updatedDestination.phone
         && updatedDestination.email === testEmail
     },

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

@@ -0,0 +1,358 @@
+require('source-map-support').install();
+
+import { SYSTEM_REVIEWER_ID } from "@tellescope/constants"
+import {
+  assert_checks,
+  Check,
+  setup_isolated_tenant,
+} 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 auto-review of in-range vital readings — the `autoReview` flag on
+ * `vital_configurations.ranges`, applied inside `handle_vital_create` at the moment a reading is
+ * classified. For RPM-style programs most readings are in range, and clearing them one at a time
+ * out of the unreviewed-vitals queue is pure busywork; a range marked auto-review sets
+ * `reviewedAt` + `reviewedBy = SYSTEM_REVIEWER_ID` on the same update that writes classifications.
+ *
+ * The rule under test is deliberately strict: a reading gets one classification per MATCHING
+ * configuration, and auto-review happens only when EVERY one of those classifications came from an
+ * autoReview range. C is the check that pins this — a reading that is in-range under one
+ * configuration but caught by a non-auto-review range under another still needs a human, because
+ * the second configuration is the one expressing clinical concern.
+ *
+ * Vital configurations are business-wide (the handler reads them with `enduserId: { $exists: false }`
+ * over the caller's businessId), so this suite provisions its own throwaway tenant: without that it
+ * would classify — and auto-review — other concurrently running suites' readings, and theirs would
+ * bleed into these checks. It never calls `sdk.reset_db()`, which clears global throttle namespaces.
+ *
+ * Units come from the fixed VITAL_UNITS list, so checks that must not see each other's
+ * configurations are separated by unit rather than by name: SBP for A/B, DBP for the multi-config
+ * rule, A1C for the uncovered case.
+ *
+ * Classification is an asynchronous create side effect, so every read polls.
+ */
+
+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 enduser_observations_auto_review_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: `VitalAutoReview ${RAND()}`,
+      users: [{ isAdmin: true }],
+      apiKeys: 0,
+    })
+    const { sdk } = tenant
+
+    const enduser = await sdk.api.endusers.createOne({ fname: 'AutoReview', lname: 'Patient' })
+
+    const create_reading = (unit: string, value: number) => (
+      sdk.api.enduser_observations.createOne({
+        category: 'vital-signs',
+        status: 'final',
+        enduserId: enduser.id,
+        measurement: { unit, value },
+        timestamp: new Date(),
+      })
+    )
+
+    /* ===== A / B: one configuration, Target auto-reviews and High does not ===== */
+
+    await sdk.api.vital_configurations.createOne({
+      title: `AutoReview SBP ${RAND()}`,
+      unit: 'SBP',
+      ranges: [
+        {
+          classification: 'Target',
+          comparison: { type: 'Between', value: { lower: 100, upper: 200 } },
+          autoReview: true,
+        },
+        {
+          classification: 'High',
+          comparison: { type: 'Greater Than', value: 200 },
+        },
+      ],
+    })
+
+    /* ===== A: an in-range reading is reviewed automatically ===== */
+
+    const inRange = await create_reading('SBP', 150)
+    const inRangeAfter = await poll_for(
+      () => sdk.api.enduser_observations.getOne(inRange.id),
+      o => !!o.reviewedAt,
+    )
+    record(
+      'A1: a reading matching an auto-review range is marked reviewed',
+      !!inRangeAfter.reviewedAt,
+      `reviewedAt=${JSON.stringify(inRangeAfter.reviewedAt)} classifications=${JSON.stringify(inRangeAfter.classifications)}`
+      + ` — must be set by handle_vital_create, not by an acknowledge call`,
+    )
+    record(
+      'A2: reviewedBy records the system sentinel, not a user id',
+      inRangeAfter.reviewedBy === SYSTEM_REVIEWER_ID,
+      `reviewedBy=${JSON.stringify(inRangeAfter.reviewedBy)} (want ${JSON.stringify(SYSTEM_REVIEWER_ID)})`,
+    )
+    record(
+      'A3: the auto-reviewed reading still carries its classification',
+      inRangeAfter.classifications?.length === 1 && inRangeAfter.classifications?.[0].classification === 'Target',
+      `classifications=${JSON.stringify(inRangeAfter.classifications)} (want exactly one, Target)`,
+    )
+
+    /* ===== B: an out-of-range reading is classified but left for a human ===== */
+
+    const outOfRange = await create_reading('SBP', 250)
+    const outOfRangeAfter = await poll_for(
+      () => sdk.api.enduser_observations.getOne(outOfRange.id),
+      o => !!o.classifications?.length,
+    )
+    record(
+      'B1: an out-of-range reading is classified High',
+      outOfRangeAfter.classifications?.length === 1 && outOfRangeAfter.classifications?.[0].classification === 'High',
+      `classifications=${JSON.stringify(outOfRangeAfter.classifications)} (want exactly one, High)`,
+    )
+    record(
+      'B2: an out-of-range reading is NOT auto-reviewed',
+      !outOfRangeAfter.reviewedAt && !outOfRangeAfter.reviewedBy,
+      `reviewedAt=${JSON.stringify(outOfRangeAfter.reviewedAt)} reviewedBy=${JSON.stringify(outOfRangeAfter.reviewedBy)} (want neither set)`,
+    )
+
+    /* ===== C: strict multi-config rule — one non-auto-review match blocks auto-review =====
+     * On its own unit (DBP) so these two configurations cannot affect A/B/D. */
+
+    await sdk.api.vital_configurations.createOne({
+      title: `AutoReview DBP target ${RAND()}`,
+      unit: 'DBP',
+      ranges: [
+        {
+          classification: 'Target',
+          comparison: { type: 'Between', value: { lower: 100, upper: 200 } },
+          autoReview: true,
+        },
+      ],
+    })
+    await sdk.api.vital_configurations.createOne({
+      title: `AutoReview DBP catchall ${RAND()}`,
+      unit: 'DBP',
+      // catch-all with autoReview off: this configuration always has an opinion, and it is never
+      // "clear this automatically"
+      ranges: [
+        {
+          classification: 'Low',
+          comparison: { type: 'Greater Than', value: 0 },
+        },
+      ],
+    })
+
+    const multiConfig = await create_reading('DBP', 150)
+    const multiConfigAfter = await poll_for(
+      () => sdk.api.enduser_observations.getOne(multiConfig.id),
+      o => (o.classifications?.length ?? 0) >= 2,
+    )
+    record(
+      'C1: a reading matched by two configurations gets one classification from each',
+      multiConfigAfter.classifications?.length === 2,
+      `classifications=${JSON.stringify(multiConfigAfter.classifications)} (want 2 — one per matching configuration)`,
+    )
+    record(
+      'C2: auto-review requires EVERY matched classification to come from an auto-review range',
+      !multiConfigAfter.reviewedAt && !multiConfigAfter.reviewedBy,
+      `reviewedAt=${JSON.stringify(multiConfigAfter.reviewedAt)} reviewedBy=${JSON.stringify(multiConfigAfter.reviewedBy)}`
+      + ` — in range under one configuration, but the other's non-auto-review range also matched`,
+    )
+
+    /* ===== D: a reading no configuration covers is never auto-reviewed ===== */
+
+    const uncovered = await create_reading('A1C', 150)
+    // nothing to wait for turning true, so poll for the negative to settle instead of reading once
+    const uncoveredAfter = await poll_for(
+      () => sdk.api.enduser_observations.getOne(uncovered.id),
+      o => !!o.reviewedAt || !!o.classifications?.length,
+      8,
+    )
+    record(
+      'D1: a reading on an uncovered unit gets no classifications and is not auto-reviewed',
+      !uncoveredAfter.classifications?.length && !uncoveredAfter.reviewedAt && !uncoveredAfter.reviewedBy,
+      `classifications=${JSON.stringify(uncoveredAfter.classifications)} reviewedAt=${JSON.stringify(uncoveredAfter.reviewedAt)}`
+      + ` reviewedBy=${JSON.stringify(uncoveredAfter.reviewedBy)} (want all empty — no configuration covers A1C here)`,
+    )
+
+    /* ===== E: a manual acknowledge still records the real reviewer ===== */
+
+    await sdk.api.enduser_observations.acknowledge({ ids: [outOfRange.id] })
+    const acknowledged = await sdk.api.enduser_observations.getOne(outOfRange.id)
+    record(
+      'E1: manual acknowledge still sets reviewedBy to the acting user',
+      !!acknowledged.reviewedAt && acknowledged.reviewedBy === tenant.users[0].id,
+      `reviewedAt=${JSON.stringify(acknowledged.reviewedAt)} reviewedBy=${JSON.stringify(acknowledged.reviewedBy)}`
+      + ` (want the acting user ${tenant.users[0].id}, NOT the sentinel)`,
+    )
+
+    /* ===== F/G/H: enduser-conditional auto-review =====
+     * A range's autoReviewConditions gate auto-review on the enduser: the range still classifies the
+     * reading, but only auto-reviews when the enduser satisfies the conditions. Separate endusers whose
+     * custom field `arField` matches vs. does not, on their own units so configs stay isolated. */
+
+    const matchingEnduser = await sdk.api.endusers.createOne({ fname: 'Match', lname: 'Patient', fields: { arField: 'yes' } })
+    const nonMatchingEnduser = await sdk.api.endusers.createOne({ fname: 'NoMatch', lname: 'Patient', fields: { arField: 'no' } })
+
+    const create_reading_for = (enduserId: string, unit: string, value: number) => (
+      sdk.api.enduser_observations.createOne({
+        category: 'vital-signs',
+        status: 'final',
+        enduserId,
+        measurement: { unit, value },
+        timestamp: new Date(),
+      })
+    )
+
+    /* ===== F: a Target range that auto-reviews only for endusers matching a custom-field condition ===== */
+
+    await sdk.api.vital_configurations.createOne({
+      title: `AutoReview BPM conditional ${RAND()}`,
+      unit: 'BPM',
+      ranges: [
+        {
+          classification: 'Target',
+          comparison: { type: 'Between', value: { lower: 60, upper: 100 } },
+          autoReview: true,
+          autoReviewConditions: { $and: [{ condition: { arField: 'yes' } }] },
+        },
+      ],
+    })
+
+    const condMatch = await create_reading_for(matchingEnduser.id, 'BPM', 80)
+    const condMatchAfter = await poll_for(
+      () => sdk.api.enduser_observations.getOne(condMatch.id),
+      o => !!o.reviewedAt || !!o.classifications?.length,
+    )
+    record(
+      'F1: a reading for an enduser matching the auto-review conditions IS auto-reviewed',
+      !!condMatchAfter.reviewedAt && condMatchAfter.reviewedBy === SYSTEM_REVIEWER_ID
+      && condMatchAfter.classifications?.[0]?.classification === 'Target',
+      `reviewedAt=${JSON.stringify(condMatchAfter.reviewedAt)} reviewedBy=${JSON.stringify(condMatchAfter.reviewedBy)}`
+      + ` classifications=${JSON.stringify(condMatchAfter.classifications)} (enduser arField=yes matches)`,
+    )
+
+    const condNoMatch = await create_reading_for(nonMatchingEnduser.id, 'BPM', 80)
+    const condNoMatchAfter = await poll_for(
+      () => sdk.api.enduser_observations.getOne(condNoMatch.id),
+      o => !!o.classifications?.length,
+    )
+    record(
+      'F2: the same reading for an enduser NOT matching the conditions is classified but NOT auto-reviewed',
+      condNoMatchAfter.classifications?.[0]?.classification === 'Target'
+      && !condNoMatchAfter.reviewedAt && !condNoMatchAfter.reviewedBy,
+      `reviewedAt=${JSON.stringify(condNoMatchAfter.reviewedAt)} reviewedBy=${JSON.stringify(condNoMatchAfter.reviewedBy)}`
+      + ` classifications=${JSON.stringify(condNoMatchAfter.classifications)} (enduser arField=no does not match)`,
+    )
+
+    /* ===== G: $or conditions — matching either branch auto-reviews ===== */
+
+    await sdk.api.vital_configurations.createOne({
+      title: `AutoReview O2 or-conditions ${RAND()}`,
+      unit: 'O2 Sat%',
+      ranges: [
+        {
+          classification: 'Target',
+          comparison: { type: 'Greater Than', value: 90 },
+          autoReview: true,
+          autoReviewConditions: { $or: [{ condition: { arField: 'other' } }, { condition: { arField: 'yes' } }] },
+        },
+      ],
+    })
+
+    const orMatch = await create_reading_for(matchingEnduser.id, 'O2 Sat%', 98)
+    const orMatchAfter = await poll_for(
+      () => sdk.api.enduser_observations.getOne(orMatch.id),
+      o => !!o.reviewedAt || !!o.classifications?.length,
+    )
+    record(
+      'G1: an enduser matching either $or branch is auto-reviewed',
+      !!orMatchAfter.reviewedAt && orMatchAfter.reviewedBy === SYSTEM_REVIEWER_ID,
+      `reviewedAt=${JSON.stringify(orMatchAfter.reviewedAt)} reviewedBy=${JSON.stringify(orMatchAfter.reviewedBy)}`
+      + ` (arField=yes matches the second $or branch)`,
+    )
+
+    /* ===== H: multi-config safety — a failing condition in one config blocks auto-review =====
+     * matchingEnduser (arField=yes) matches config-1's Target but NOT config-2's catch-all condition. */
+
+    await sdk.api.vital_configurations.createOne({
+      title: `AutoReview L/min target ${RAND()}`,
+      unit: 'L/min',
+      ranges: [
+        {
+          classification: 'Target',
+          comparison: { type: 'Between', value: { lower: 100, upper: 600 } },
+          autoReview: true,
+          autoReviewConditions: { $and: [{ condition: { arField: 'yes' } }] },
+        },
+      ],
+    })
+    await sdk.api.vital_configurations.createOne({
+      title: `AutoReview L/min catchall ${RAND()}`,
+      unit: 'L/min',
+      ranges: [
+        {
+          classification: 'Low',
+          comparison: { type: 'Greater Than', value: 0 },
+          autoReview: true,
+          // enduser arField=yes, so this condition (arField=other) fails: config-2 is not auto-reviewable
+          autoReviewConditions: { $and: [{ condition: { arField: 'other' } }] },
+        },
+      ],
+    })
+
+    const condMultiConfig = await create_reading_for(matchingEnduser.id, 'L/min', 300)
+    const condMultiConfigAfter = await poll_for(
+      () => sdk.api.enduser_observations.getOne(condMultiConfig.id),
+      o => (o.classifications?.length ?? 0) >= 2,
+    )
+    record(
+      'H1: auto-review requires EVERY matched range to be auto-reviewable for this enduser',
+      condMultiConfigAfter.classifications?.length === 2
+      && !condMultiConfigAfter.reviewedAt && !condMultiConfigAfter.reviewedBy,
+      `reviewedAt=${JSON.stringify(condMultiConfigAfter.reviewedAt)} reviewedBy=${JSON.stringify(condMultiConfigAfter.reviewedBy)}`
+      + ` classifications=${JSON.stringify(condMultiConfigAfter.classifications)}`
+      + ` — config-1 conditions match, config-2 conditions do not, so a human is still required`,
+    )
+  } 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 enduser_observations_auto_review_tests = async () => {
+  assert_checks('Vital auto-review on create', await enduser_observations_auto_review_checks())
+}
+
+// Allow running this test file independently
+if (require.main === module) {
+  console.log(`🌐 Using API URL: ${host}`)
+  enduser_observations_auto_review_tests()
+    .then(() => {
+      console.log("✅ Vital auto-review test suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ Vital auto-review test suite failed:", error)
+      process.exit(1)
+    })
+}

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

@@ -207,7 +207,7 @@ export const integrations_redacted_tests = async ({ sdk, sdkNonAdmin } : { sdk:
       }}
     )
 
-    // F-0049: connect_stripe must reject caller-supplied accountId (Stripe-account-spoofing defense).
+    // connect_stripe must reject caller-supplied accountId (Stripe-account-spoofing defense).
     // Stripe Connect is deprecated in Tellescope; accountId was a test shortcut, kept rejected to preserve SDK shape.
     await async_test(
       "connect_stripe rejects caller-supplied accountId",

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

@@ -0,0 +1,240 @@
+require('source-map-support').install();
+
+import axios from "axios"
+
+import { Session } from "../../sdk"
+import { wait } from "@tellescope/testing"
+import {
+  assert_checks,
+  Check,
+  set_email_verification_code,
+  setup_isolated_tenant,
+  test_support_request,
+} from "../setup_isolated"
+
+const host = process.env.API_URL || 'http://localhost:8080' as const
+
+const RAND = () => Math.random().toString(36).slice(2, 10)
+
+// legacy shared fixture — teardown must refuse it
+const SEEDED_TEST_BUSINESS_ID = '60398b1131a295e64f084ff6'
+
+/**
+ * Covers the self-service organization signup chain, which had ZERO test coverage:
+ * `users.register` -> `users.submit_email_verification` -> `organizations.create_and_join`.
+ *
+ * That gap is why an earlier review nearly shipped a schema `adminOnly` flag on create_and_join that would have
+ * 401'd every new organization — a freshly registered user has no `roles`, because create_and_join is
+ * itself what grants Admin. This test is the regression guard for that.
+ *
+ * It also covers the new test-support provisioning module, including the assertion that matters most:
+ * teardown refuses any organization it did not create.
+ *
+ * Uses a `dontsend...@tellescope.com` address so the verification email is dropped at
+ * forCommunications before it is ever enqueued (locally the worker consumes the same test queue the
+ * API writes to, so an unsuppressed registration really does send mail).
+ */
+export const organization_signup_checks = async (): Promise<Check[]> => {
+  const checks: Check[] = []
+  const record = (label: string, pass: boolean, detail: string) => checks.push({ label, pass, detail })
+
+  let bootstrapUserId = ''
+  let createdBusinessId = ''
+  let provisioned: Awaited<ReturnType<typeof setup_isolated_tenant>> | undefined
+
+  try {
+    /* ===== A: provisioning works with no seeded database ===== */
+
+    provisioned = await setup_isolated_tenant()
+    record(
+      'A1: provision-tenant returns a usable admin session',
+      !!provisioned.businessId && provisioned.sdk.userInfo?.businessId === provisioned.businessId,
+      `businessId=${provisioned.businessId} session businessId=${provisioned.sdk.userInfo?.businessId}`,
+    )
+
+    // proves the frozen utf8 api-key hash was reproduced correctly, and that the key's creator
+    // resolves — a key whose creator is missing fails authentication outright
+    let keyDetail = ''
+    let keyPass = false
+    try {
+      const keySession = new Session({ host, apiKey: provisioned.apiKeys[0] })
+      keyDetail = await keySession.test_authenticated()
+      keyPass = keyDetail === 'Authenticated!'
+    } catch (e: any) {
+      keyDetail = `rejected: ${e?.message || e?.toString()}`
+    }
+    record('A2: a provisioned API key authenticates', keyPass, `test_authenticated -> ${keyDetail}`)
+
+    // the tenant is genuinely usable, not just addressable
+    const enduser = await provisioned.sdk.api.endusers.createOne({ fname: 'Provisioned', lname: 'Patient' })
+    record('A3: the provisioned tenant accepts writes', !!enduser.id, `enduserId=${enduser.id}`)
+
+    /* ===== B: teardown refuses anything it did not create — the safety assertion ===== */
+
+    const refusal = await test_support_request('/teardown-tenant', { businessId: SEEDED_TEST_BUSINESS_ID })
+    record(
+      'B1: teardown REFUSES an organization without the provenance marker',
+      refusal.status === 403,
+      `status=${refusal.status} ${JSON.stringify(refusal.body)} (expected 403)`,
+    )
+
+    /* ===== C: the signup chain ===== */
+
+    const email = `dontsend-signup-${RAND()}@tellescope.com`
+    const password = `Signup-${RAND()}-A1!`
+
+    const registerResult = await axios.request({
+      method: 'post', url: `${host}/v1/users/register`,
+      data: { email, password, termsVersion: '1' },
+      validateStatus: () => true,
+    })
+    record(
+      'C1: register accepts a new org-less user',
+      registerResult.status === 204,
+      `status=${registerResult.status} ${JSON.stringify(registerResult.data ?? '')}`,
+    )
+    await wait(undefined, 1200) // register is IP-limited to ~1/sec
+
+    // login works before verification, which is how a test learns the new user's id
+    const preVerifyLogin = await axios.request({
+      method: 'post', url: `${host}/v1/users/login`,
+      data: { email, password },
+      validateStatus: () => true,
+    })
+    bootstrapUserId = preVerifyLogin.data?.user?.id ?? ''
+    record(
+      'C2: the unverified user can log in (and is org-less)',
+      preVerifyLogin.status === 200 && !!bootstrapUserId && !preVerifyLogin.data?.user?.businessId,
+      `status=${preVerifyLogin.status} id=${bootstrapUserId} businessId=${preVerifyLogin.data?.user?.businessId ?? '(none)'}`,
+    )
+
+    // an unverified session must be rejected by a gated endpoint
+    const unverifiedAttempt = await axios.request({
+      method: 'post', url: `${host}/v1/organizations/create-and-join`,
+      data: { name: 'Should Not Work', subdomain: `nope-${RAND()}` },
+      headers: { Authorization: `Bearer ${preVerifyLogin.data?.authToken}` },
+      validateStatus: () => true,
+    })
+    record(
+      'C3: create_and_join is rejected before email verification',
+      unverifiedAttempt.status === 400,
+      `status=${unverifiedAttempt.status} ${JSON.stringify(unverifiedAttempt.data ?? '')}`,
+    )
+
+    // set the pending code, then drive the REAL verification endpoint
+    const code = `verify-${RAND()}`
+    await set_email_verification_code(email, code)
+
+    const verified = await axios.request({
+      method: 'post', url: `${host}/v1/users/submit-email-verification`,
+      data: { email, code },
+      validateStatus: () => true,
+    })
+    record(
+      'C4: submit_email_verification accepts the code and mints a token',
+      verified.status === 200 && !!verified.data?.authToken,
+      `status=${verified.status} authToken=${!!verified.data?.authToken}`,
+    )
+
+    /* ===== D: create_and_join — what that flag would have broken ===== */
+
+    const subdomain = `signup-${RAND()}`
+    const joined = await axios.request({
+      method: 'post', url: `${host}/v1/organizations/create-and-join`,
+      data: { name: `Signup Test ${RAND()}`, subdomain },
+      headers: { Authorization: `Bearer ${verified.data?.authToken}` },
+      validateStatus: () => true,
+    })
+    createdBusinessId = joined.data?.organization?.id ?? ''
+    record(
+      'D1: a freshly verified, org-less user can create and join an organization',
+      joined.status === 200 && !!createdBusinessId,
+      `status=${joined.status} organizationId=${createdBusinessId} ${joined.status !== 200 ? JSON.stringify(joined.data) : ''}`,
+    )
+    record(
+      'D2: the handler grants Admin and sets businessId (the roles bootstrap)',
+      joined.data?.user?.roles?.includes('Admin') && joined.data?.user?.businessId === createdBusinessId,
+      `roles=${JSON.stringify(joined.data?.user?.roles)} businessId=${joined.data?.user?.businessId}`,
+    )
+    record(
+      'D3: a fresh token is returned',
+      !!joined.data?.authToken && joined.data.authToken !== verified.data?.authToken,
+      `token returned=${!!joined.data?.authToken}, rotated=${joined.data?.authToken !== verified.data?.authToken}`,
+    )
+
+    const second = await axios.request({
+      method: 'post', url: `${host}/v1/organizations/create-and-join`,
+      data: { name: 'Second Org', subdomain: `signup-${RAND()}` },
+      headers: { Authorization: `Bearer ${joined.data?.authToken}` },
+      validateStatus: () => true,
+    })
+    record(
+      'D4: a user already in an organization cannot create another',
+      second.status === 400,
+      `status=${second.status} ${JSON.stringify(second.data ?? '')}`,
+    )
+
+    /* ===== E: teardown actually removes the tenant ===== */
+
+    // a second, disposable tenant so the assertions above keep their fixture
+    const disposable = await setup_isolated_tenant({ users: [{ isAdmin: true }], apiKeys: 1 })
+    const disposableKey = disposable.apiKeys[0]
+    await disposable.sdk.api.endusers.createOne({ fname: 'Disposable', lname: 'Patient' })
+    await disposable.teardown()
+
+    const secondTeardown = await test_support_request('/teardown-tenant', { businessId: disposable.businessId })
+    record(
+      'E1: teardown removes the organization record itself',
+      secondTeardown.status === 404,
+      `re-teardown status=${secondTeardown.status} ${JSON.stringify(secondTeardown.body)} (expected 404 — org gone)`,
+    )
+
+    let revokedDetail = ''
+    let revokedPass = false
+    try {
+      revokedDetail = await (new Session({ host, apiKey: disposableKey })).test_authenticated()
+    } catch (e: any) {
+      revokedPass = true
+      revokedDetail = `rejected: ${e?.message || e?.toString()}`
+    }
+    record(
+      'E2: the torn-down tenant\'s API key no longer authenticates',
+      revokedPass,
+      revokedDetail,
+    )
+
+  } finally {
+    if (provisioned) { try { await provisioned.teardown() } catch (e) { console.error('teardown failed', e) } }
+    // The signup-created org is NOT test-seeded, so teardown-tenant correctly refuses it; the org row
+    // is documented residue. The bootstrap user IS removable via test-support (the
+    // /tellescope-admin/delete-user route needs a staff session an isolated test deliberately lacks —
+    // posting to it without an Authorization header silently 401'd, so this used to leak every run).
+    if (bootstrapUserId) {
+      try { await test_support_request('/delete-user', { userId: bootstrapUserId }) } catch {}
+    }
+    if (createdBusinessId) {
+      console.log(`  note: organization ${createdBusinessId} was created by the signup flow and is left behind (nothing can delete an org record)`)
+    }
+  }
+
+  return checks
+}
+
+/** Asserting wrapper, for standalone runs and for sequential use in the suite. */
+export const organization_signup_tests = async () => {
+  assert_checks('Organization signup', await organization_signup_checks())
+}
+
+// Allow running this test file independently
+if (require.main === module) {
+  console.log(`🌐 Using API URL: ${host}`)
+  organization_signup_tests()
+    .then(() => {
+      console.log("✅ Organization signup test suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ Organization signup test suite failed:", error)
+      process.exit(1)
+    })
+}