@tellescope/sdk 1.253.0 → 1.253.1

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

@@ -0,0 +1,159 @@
+require('source-map-support').install();
+
+import { Session } from "../../sdk"
+import {
+  async_test,
+  log_header,
+} from "@tellescope/testing"
+import { setup_tests } from "../setup"
+import { BELUGA_TITLE } from "@tellescope/constants"
+
+const host = process.env.API_URL || 'http://localhost:8080' as const
+
+// Manual Beluga re-sync guard tests (CU-86e1uxz1n).
+//   - form_responses.push_to_EHR with target === BELUGA_TITLE
+//   - files.push with destination === BELUGA_TITLE
+//
+// Fast / no-upload: this only verifies the bad-input / guard branches that reject before any
+// Beluga call. It performs NO S3 file uploads and triggers NO actual sync (both slow and require
+// live Beluga sandbox credentials). File records are created via prepare_file_upload alone — that
+// inserts the DB record, which is all the guards need.
+export const beluga_manual_sync_tests = async ({ sdk, sdkNonAdmin }: { sdk: Session, sdkNonAdmin: Session }) => {
+  log_header("Beluga Manual Sync Guard Tests (FormResponses & Files)")
+
+  const errorMessage = (e: any) => (e?.message || e?.toString?.() || JSON.stringify(e)) as string
+
+  let enduserId: string | undefined
+  let belugaFormId: string | undefined
+  let plainFormId: string | undefined
+  const fileIds: string[] = []
+  let createdBelugaIntegrationId: string | undefined
+
+  try {
+    const enduser = await sdk.api.endusers.createOne({
+      fname: 'beluga-sync',
+      email: `beluga_manual_sync_${Date.now()}@test.tellescope.com`,
+    })
+    enduserId = enduser.id
+
+    // Beluga-configured form (belugaVisitType set) and a plain (non-Beluga) form
+    const belugaForm = await sdk.api.forms.createOne({ title: 'Beluga Manual Sync Form', belugaVisitType: 'sync' })
+    belugaFormId = belugaForm.id
+
+    const plainForm = await sdk.api.forms.createOne({ title: 'Non-Beluga Manual Sync Form' })
+    plainFormId = plainForm.id
+    // A form needs at least one field + a matching answer to be submittable (empty responses are rejected)
+    const plainField = await sdk.api.form_fields.createOne({
+      formId: plainForm.id, type: 'string', title: 'Field', previousFields: [{ type: 'root', info: {} }],
+    })
+
+    const submitForm = async (formId: string) => {
+      const { accessCode, response } = await sdk.api.form_responses.prepare_form_response({ enduserId: enduser.id, formId })
+      await sdk.api.form_responses.submit_form_response({
+        accessCode,
+        responses: [{ fieldId: plainField.id, fieldTitle: 'Field', answer: { type: 'string', value: 'x' } }],
+      })
+      return response.id
+    }
+
+    // Create a File DB record WITHOUT uploading to S3. prepare_file_upload inserts the record and
+    // returns it; skipping sdk.UPLOAD / confirm_file_upload keeps the test fast. The guards only
+    // read fields off the record (formResponseId, references), so no real upload is needed.
+    const createFileRecord = async (name: string) => {
+      const { file } = await sdk.api.files.prepare_file_upload({
+        name, type: 'text/plain', size: 1, enduserId: enduser.id,
+      })
+      fileIds.push(file.id)
+      return file
+    }
+
+    // ──────────────────────────────────────────────────────────────────────────
+    // 1. FormResponse guards (integration-independent)
+    // ──────────────────────────────────────────────────────────────────────────
+
+    // Unsubmitted draft → rejected before any integration lookup
+    const { response: draft } = await sdk.api.form_responses.prepare_form_response({ enduserId: enduser.id, formId: belugaForm.id })
+    await async_test(
+      "push_to_EHR(target=BELUGA) rejects an unsubmitted form response",
+      () => sdk.api.form_responses.push_to_EHR({ id: draft.id, target: BELUGA_TITLE }),
+      { shouldError: true, onError: (e: any) => /has not been submitted/i.test(errorMessage(e)) }
+    )
+
+    // Submitted, but the form has no belugaVisitType → rejected as not configured
+    const plainResponseId = await submitForm(plainForm.id)
+    await async_test(
+      "push_to_EHR(target=BELUGA) rejects a form not configured for Beluga",
+      () => sdk.api.form_responses.push_to_EHR({ id: plainResponseId, target: BELUGA_TITLE }),
+      { shouldError: true, onError: (e: any) => /not configured for Beluga/i.test(errorMessage(e)) }
+    )
+
+    // ──────────────────────────────────────────────────────────────────────────
+    // 2. files.push(destination=BELUGA) guard — the endpoint resolves the destination
+    //    integration first, so a Beluga integration must exist for the branch to be reached.
+    //    Create a placeholder if the org has none; skip gracefully if that's not permitted.
+    // ──────────────────────────────────────────────────────────────────────────
+
+    let belugaIntegrationAvailable = false
+    try {
+      const existing = await sdk.api.integrations.load_redacted({})
+      belugaIntegrationAvailable = !!existing.integrations.find((i: any) => i.title === BELUGA_TITLE)
+    } catch { /* load not permitted — fall through to create attempt */ }
+
+    if (!belugaIntegrationAvailable) {
+      try {
+        const created = await sdk.api.integrations.createOne({
+          title: BELUGA_TITLE,
+          authentication: {
+            type: 'oauth2',
+            info: { access_token: 'test-access-token', refresh_token: 'test-refresh-token', scope: '', token_type: 'Bearer', expiry_date: new Date().getTime() },
+          },
+        })
+        createdBelugaIntegrationId = created.id
+        belugaIntegrationAvailable = true
+      } catch (e) {
+        console.log("Could not create a Beluga integration for testing; skipping files.push guard:", errorMessage(e))
+      }
+    }
+
+    if (belugaIntegrationAvailable) {
+      // A file with no associated formResponseId cannot be synced to Beluga
+      const unlinkedFile = await createFileRecord('beluga-unlinked.txt')
+      await async_test(
+        "files.push(destination=BELUGA) rejects a file with no associated form response",
+        () => sdk.api.files.push({ id: unlinkedFile.id, destination: BELUGA_TITLE }),
+        { shouldError: true, onError: (e: any) => /not associated with a form response/i.test(errorMessage(e)) }
+      )
+    } else {
+      console.log("⏭️  Skipping files.push(destination=BELUGA) guard (no Beluga integration available)")
+    }
+  } finally {
+    for (const id of fileIds) {
+      await sdk.api.files.deleteOne(id).catch(console.error)
+    }
+    if (belugaFormId) await sdk.api.forms.deleteOne(belugaFormId).catch(console.error)
+    if (plainFormId) await sdk.api.forms.deleteOne(plainFormId).catch(console.error)
+    if (enduserId) await sdk.api.endusers.deleteOne(enduserId).catch(console.error)
+    if (createdBelugaIntegrationId) await sdk.api.integrations.deleteOne(createdBelugaIntegrationId).catch(console.error)
+  }
+}
+
+if (require.main === module) {
+  console.log(`Using API URL: ${host}`)
+  const sdk = new Session({ host })
+  const sdkNonAdmin = new Session({ host })
+
+  const runTests = async () => {
+    await setup_tests(sdk, sdkNonAdmin)
+    await beluga_manual_sync_tests({ sdk, sdkNonAdmin })
+  }
+
+  runTests()
+    .then(() => {
+      console.log("✅ Beluga manual sync test suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ Beluga manual sync test suite failed:", error)
+      process.exit(1)
+    })
+}

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

@@ -0,0 +1,104 @@
+require('source-map-support').install();
+
+import { Session } from "../../sdk"
+import {
+  async_test,
+  log_header,
+  wait,
+} from "@tellescope/testing"
+import { setup_tests } from "../setup"
+
+const host = process.env.API_URL || 'http://localhost:8080' as const
+
+/**
+ * Google Calendar sync retry — integration coverage.
+ *
+ * ┌─ ARCHITECTURE NOTE (why the full mock-Google scenarios are gated) ──────────┐
+ * │ SDK api_tests run in a SEPARATE process from the API server (they talk to    │
+ * │ host = API_URL / http://localhost:8080). The retry scheduler, the Google     │
+ * │ retryable-error predicates, and the google.calendar() client all live in the │
+ * │ API SERVER process. A stub installed here (in the SDK test process) cannot   │
+ * │ replace the server's in-process google client, so we cannot deterministically│
+ * │ inject 429 / 500 / ECONNRESET responses from this test alone.                │
+ * │                                                                              │
+ * │ Two ways to run the full fail-429-then-succeed / exhaustion / cap scenarios: │
+ * │  1. Run the API server with NODE_ENV=test and RETRY_SCHEDULER_DELAYS_MS=10,20 │
+ * │     (already honored by the singleton constructor) plus a server-side        │
+ * │     fault-injection hook on sdk.events.* that reads e.g.                      │
+ * │     process.env.GCAL_TEST_FORCE_ERROR — that hook does not exist yet.         │
+ * │  2. Drive the scheduler directly with the in-process unit tests, which DO     │
+ * │     cover all retry mechanics deterministically:                             │
+ * │       packages/private/api/api/modules/retry_scheduler.test.ts               │
+ * │       packages/private/api/api/integrations/google.test.ts                   │
+ * │                                                                              │
+ * │ The scenario matrix below is recorded for when a server-side hook is added.  │
+ * └──────────────────────────────────────────────────────────────────────────────┘
+ *
+ * Scenario matrix (requires server-side Google fault injection — see note):
+ *   1. create retry:   fail 429 once then succeed -> gcal reference written, NO background_errors
+ *   2. exhaustion:     fail 429 on every call -> exactly one "Google Calendar Push Error" background_errors row
+ *   3. non-retryable:  fail 403 -> background_errors written immediately, no retries
+ *   4. create idempotency: fail ECONNRESET (network) -> NON-retryable for create (duplicate risk),
+ *                          background_errors written, no retry, no duplicate insert
+ *   5. update + delete: same as (1) for events.patch and events.delete
+ *   6. cap exceeded:   maxOpenRetries=2, 3 events all fail retryably -> 3rd -> background_errors immediately
+ *
+ * The runnable assertions below cover what IS observable end-to-end without a
+ * connected Google account: the refactored call sites must not regress the common
+ * "user has no Google integration" path (no sync attempt, no background_errors, no retry).
+ */
+export const gcal_sync_retry_tests = async ({ sdk } : { sdk: Session, sdkNonAdmin: Session }) => {
+  log_header("Google Calendar Sync Retry")
+
+  if (process.env.GCAL_RETRY_INTEGRATION !== '1') {
+    console.log("ℹ️  Skipping mock-Google scenarios (set GCAL_RETRY_INTEGRATION=1 with a server-side "
+      + "fault-injection hook to run scenarios 1-6). Running no-integration regression checks only.")
+  }
+
+  // No-integration regression check: a calendar event with a user attendee whose
+  // account has no Google integration should sync-skip silently (no background_errors).
+  const enduser = await sdk.api.endusers.createOne({ fname: 'GcalRetry', lname: 'Test' })
+
+  await async_test(
+    'create event for user without Google integration does not produce a background error',
+    async () => {
+      const event = await sdk.api.calendar_events.createOne({
+        title: 'Gcal Retry Regression',
+        startTimeInMS: Date.now() + 1000 * 60 * 60,
+        durationInMinutes: 30,
+        attendees: [{ type: 'user', id: sdk.userInfo.id }, { type: 'enduser', id: enduser.id }],
+      })
+
+      // give side-effect handlers a moment to run
+      await wait(undefined, 750)
+
+      const errors = await sdk.api.background_errors.getSome({}).catch(() => [])
+
+      // clean up
+      await sdk.api.calendar_events.deleteOne(event.id).catch(() => {})
+
+      // No Google integration on the test user => no push attempt => no error row.
+      return errors.filter((e: any) => (
+        e.userId === sdk.userInfo.id && e.title === "Google Calendar Push Error"
+      )).length
+    },
+    { onResult: (count) => count === 0 },
+  )
+
+  // cleanup
+  await sdk.api.endusers.deleteOne(enduser.id).catch(() => {})
+}
+
+if (require.main === module) {
+  const sdk = new Session({ host })
+  const sdkNonAdmin = new Session({ host })
+
+  const runTests = async () => {
+    await setup_tests(sdk, sdkNonAdmin)
+    await gcal_sync_retry_tests({ sdk, sdkNonAdmin })
+  }
+
+  runTests()
+    .then(() => { console.log("✅ gcal sync retry test suite completed successfully"); process.exit(0) })
+    .catch((error) => { console.error("❌ gcal sync retry test suite failed:", error); process.exit(1) })
+}

package/src/tests/api_tests/security/F-0106-F-0110-enduser-write-restrictions.test.ts

@@ -0,0 +1,214 @@
+require('source-map-support').install();
+
+import { Session, EnduserSession } from "../../../sdk"
+import {
+  async_test,
+  log_header,
+} from "@tellescope/testing"
+import { setup_tests } from "../../setup"
+
+const host = process.env.API_URL || 'http://localhost:8080' as const
+const businessId = '60398b1131a295e64f084ff6'
+
+const ENDUSER_PASSWORD = 'F0106TestPassword!123'
+
+// Every endusers field marked enduserUpdatesDisabled in schema.ts, with a
+// validator-passing sample value so the only rejection in play is the
+// write-restriction (not input validation).
+const restrictedEnduserUpdates = (staffId: string, mongoId: string): Record<string, any> => ({
+  externalId: 'f0106-attacker-external-id',
+  tags: ['f0106-attacker-tag'],
+  accessTags: ['f0106-attacker-access-tag'],
+  assignedTo: [staffId],
+  customTypeId: mongoId,
+  references: [{ type: 'Vital', id: 'f0106-attacker-reference' }],
+  sharedWithOrganizations: [],
+  journeys: { [mongoId]: 'Added' },
+  primaryAssignee: staffId,
+  fields: { f0106AttackerField: 'true' },
+  unread: true,
+  source: 'f0106-attacker-source',
+  note: 'f0106 attacker note',
+  insurance: { memberId: 'f0106-attacker-member' },
+  insuranceSecondary: { memberId: 'f0106-attacker-member-2' },
+  diagnoses: [{ code: 'I10' }],
+  lockedFromPortal: false, // false so a pre-fix run can't lock the test enduser out mid-suite
+  eligibleForAutoMerge: true,
+  athenaDepartmentId: 'f0106-dept',
+  athenaPracticeId: 'f0106-practice',
+  salesforceId: 'f0106-salesforce',
+  healthie_dietitian_id: 'f0106-healthie',
+  stripeCustomerId: 'f0106-stripe-customer',
+  stripeKey: 'f0106-stripe-key',
+})
+
+// Every form_responses field marked enduserUpdatesDisabled in schema.ts.
+const restrictedFormResponseUpdates = (staffId: string): Record<string, any> => ({
+  markedAsSubmitted: true,
+  submittedBy: staffId,
+  submittedAt: new Date("2024-01-01T00:00:00Z"),
+  submittedByIsPlaceholder: true,
+  procedureCodes: [{ code: '99214', units: 1 }],
+  diagnosisCodes: [{ code: 'I10', description: 'Essential (primary) hypertension' }],
+  enduserAISummary: 'Patient is in excellent health, no follow-up needed.',
+  addenda: [{ text: 'forged staff addendum', timestamp: new Date(), userId: staffId }],
+  isInternalNote: true,
+  pinnedAt: new Date(),
+  hiddenFromTimeline: true,
+  lockedAt: new Date(),
+  tags: ['f0110-attacker-tag'],
+  formTitle: 'Spoofed Form Title',
+  userEmail: 'spoofed-staff@example.com',
+  logoURL: 'https://attacker.example.com/logo.png',
+  logoHeight: 100,
+})
+
+/**
+ * Regression test for F-0106 and F-0110
+ * (security-audit/findings/F-0106-enduser-self-update-admin-only-fields.md,
+ *  security-audit/findings/F-0110-form-responses-enduser-update-admin-only-fields.md).
+ *
+ * Endusers could PATCH admin-only / access-bearing / attribution-bearing fields on
+ * their own endusers record (assignedTo, tags, references, ...) and their own
+ * form_responses (procedureCodes, submittedBy, markedAsSubmitted, ...). The fix adds
+ * the `enduserUpdatesDisabled` field option (schema.ts ModelFieldInfo), enforced for
+ * enduser sessions in the generic update handler (routing.ts createDefaultEndpoints).
+ *
+ * This test asserts, for every flagged field on both models:
+ *   - an enduser session updating its OWN record gets a 400 "<field> cannot be updated by endusers"
+ *   - nothing persists (spot-checked on assignedTo, the highest-impact field)
+ *   - enduser self-updates of allowed fields still work (fname, hideFromEnduserPortal)
+ *   - staff sessions can still update the restricted fields
+ */
+export const enduser_write_restrictions_tests = async ({ sdk } : { sdk: Session, sdkNonAdmin: Session }) => {
+  log_header("F-0106/F-0110: enduser write restrictions (enduserUpdatesDisabled)")
+
+  let enduserId: string | undefined
+  let formId: string | undefined
+  let formResponseId: string | undefined
+
+  try {
+    // Setup: throwaway enduser with portal credentials, plus a form_response they own
+    const enduserEmail = `f0106-enduser-${Date.now()}@example.com`
+    const enduser = await sdk.api.endusers.createOne({ email: enduserEmail, fname: 'F0106', lname: 'Restricted' })
+    enduserId = enduser.id
+    await sdk.api.endusers.set_password({ id: enduser.id, password: ENDUSER_PASSWORD })
+
+    const enduserSDK = new EnduserSession({ host, businessId })
+    await enduserSDK.authenticate(enduserEmail, ENDUSER_PASSWORD)
+
+    const form = await sdk.api.forms.createOne({ title: 'F-0106/F-0110 Write Restriction Test Form' })
+    formId = form.id
+    const { response: formResponse } = await sdk.api.form_responses.prepare_form_response({
+      formId: form.id,
+      enduserId: enduser.id,
+    })
+    formResponseId = formResponse.id
+
+    // ---- F-0106: enduser self-update of restricted endusers fields must 400 ----
+    for (const [field, value] of Object.entries(restrictedEnduserUpdates(sdk.userInfo.id, enduser.id))) {
+      await async_test(
+        `F-0106: enduser cannot self-update endusers.${field}`,
+        () => enduserSDK.api.endusers.updateOne(enduser.id, { [field]: value } as any),
+        { shouldError: true, onError: e => e.message === `${field} cannot be updated by endusers` },
+      )
+    }
+
+    // F-0106 Variant A persistence check: the rejected assignedTo write must not
+    // have granted the staff read-filter match.
+    await async_test(
+      'F-0106: rejected assignedTo write did not persist',
+      () => sdk.api.endusers.getOne(enduser.id),
+      { onResult: e => !e.assignedTo?.length && !e.tags?.length && e.externalId === undefined },
+    )
+
+    // ---- F-0110: enduser self-update of restricted form_responses fields must 400 ----
+    for (const [field, value] of Object.entries(restrictedFormResponseUpdates(sdk.userInfo.id))) {
+      await async_test(
+        `F-0110: enduser cannot self-update form_responses.${field}`,
+        () => enduserSDK.api.form_responses.updateOne(formResponse.id, { [field]: value } as any),
+        { shouldError: true, onError: e => e.message === `${field} cannot be updated by endusers` },
+      )
+    }
+
+    await async_test(
+      'F-0110: rejected writes did not persist (markedAsSubmitted, procedureCodes, submittedBy)',
+      () => sdk.api.form_responses.getOne(formResponse.id),
+      { onResult: fr => !fr.markedAsSubmitted && !fr.procedureCodes?.length && fr.submittedBy === undefined },
+    )
+
+    // ---- Positive controls: intended enduser self-updates still work ----
+    await async_test(
+      'enduser can still update own profile fields (fname/lname)',
+      () => enduserSDK.api.endusers.updateOne(enduser.id, { fname: 'StillAllowed', lname: 'Patient' }),
+      { onResult: e => e.fname === 'StillAllowed' && e.lname === 'Patient' },
+    )
+    await async_test(
+      'enduser can still update own form_response (hideFromEnduserPortal — intended per schema)',
+      () => enduserSDK.api.form_responses.updateOne(formResponse.id, { hideFromEnduserPortal: true }),
+      { onResult: fr => fr.hideFromEnduserPortal === true },
+    )
+
+    // ---- Positive controls: staff sessions are unaffected by enduserUpdatesDisabled ----
+    await async_test(
+      'staff can still update restricted endusers fields (tags, assignedTo, externalId, note, source)',
+      () => sdk.api.endusers.updateOne(enduser.id, {
+        tags: ['staff-set-tag'],
+        assignedTo: [sdk.userInfo.id],
+        externalId: 'staff-set-external-id',
+        note: 'staff-set note',
+        source: 'staff-set-source',
+      }),
+      { onResult: e => (
+        !!e.tags?.includes('staff-set-tag')
+        && !!e.assignedTo?.includes(sdk.userInfo.id)
+        && e.externalId === 'staff-set-external-id'
+      ) },
+    )
+    await async_test(
+      'staff can still update restricted form_responses fields (procedureCodes, diagnosisCodes, tags)',
+      () => sdk.api.form_responses.updateOne(formResponse.id, {
+        procedureCodes: [{ code: 'G0019', units: 1 }],
+        diagnosisCodes: [{ code: 'Z71.3', description: 'Dietary counseling and surveillance' }],
+        tags: ['staff-set-tag'],
+      }),
+      { onResult: fr => (
+        fr.procedureCodes?.[0]?.code === 'G0019'
+        && fr.diagnosisCodes?.[0]?.code === 'Z71.3'
+        && !!fr.tags?.includes('staff-set-tag')
+      ) },
+    )
+  } finally {
+    if (formResponseId) {
+      try { await sdk.api.form_responses.deleteOne(formResponseId) } catch {}
+    }
+    if (formId) {
+      try { await sdk.api.forms.deleteOne(formId) } catch {}
+    }
+    if (enduserId) {
+      try { await sdk.api.endusers.deleteOne(enduserId) } catch {}
+    }
+  }
+}
+
+// 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 () => {
+    await setup_tests(sdk, sdkNonAdmin)
+    await enduser_write_restrictions_tests({ sdk, sdkNonAdmin })
+  }
+
+  runTests()
+    .then(() => {
+      console.log("✅ F-0106/F-0110 enduser write-restriction test suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ F-0106/F-0110 enduser write-restriction test suite failed:", error)
+      process.exit(1)
+    })
+}

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

@@ -25,6 +25,11 @@ export const user_portal_settings_tests = async ({ sdk, sdkNonAdmin }: { sdk: Se
   let testEnduserId: string | undefined
   let enduserSDK: EnduserSession | undefined
 
+  // Organization.onboardingStatus shares userPortalSettingsValidator — save the
+  // current value so we can restore it after exercising the field below.
+  const orgId = sdk.userInfo.businessId
+  const originalOnboardingStatus = (await sdk.api.organizations.getOne(orgId)).onboardingStatus
+
   try {
     // ===== Valid: string values =====
     await async_test(
@@ -179,6 +184,63 @@ export const user_portal_settings_tests = async ({ sdk, sdkNonAdmin }: { sdk: Se
       }
     )
 
+    // ===== Organization.onboardingStatus: same key-value shape as portalSettings =====
+    await async_test(
+      'onboardingStatus - mixed string and boolean values round-trip',
+      async () => {
+        await sdk.api.organizations.updateOne(
+          orgId,
+          { onboardingStatus: { completedIntro: true, currentStep: 'billing', skippedTour: false } },
+          { replaceObjectFields: true }
+        )
+        const updated = await sdk.api.organizations.getOne(orgId)
+        return updated.onboardingStatus
+      },
+      {
+        onResult: (r) =>
+          r?.completedIntro === true &&
+          typeof r?.completedIntro === 'boolean' &&
+          r?.currentStep === 'billing' &&
+          typeof r?.currentStep === 'string' &&
+          r?.skippedTour === false &&
+          typeof r?.skippedTour === 'boolean',
+      }
+    )
+
+    await async_test(
+      'onboardingStatus - empty object accepted',
+      async () => {
+        await sdk.api.organizations.updateOne(orgId, { onboardingStatus: {} }, { replaceObjectFields: true })
+        const updated = await sdk.api.organizations.getOne(orgId)
+        return updated.onboardingStatus
+      },
+      { onResult: (r) => !!r && typeof r === 'object' && Object.keys(r).length === 0 }
+    )
+
+    // breaking change: the previous string shape must no longer be accepted
+    await async_test(
+      'onboardingStatus - plain string (old shape) rejected',
+      () => sdk.api.organizations.updateOne(
+        orgId,
+        { onboardingStatus: 'started' as any },
+        { replaceObjectFields: true }
+      ),
+      handleAnyError
+    )
+
+    // representative validator rejection, confirming the indexable validator is
+    // enforced on the organizations route (full coverage lives in the
+    // portalSettings cases above, which use the same validator)
+    await async_test(
+      'onboardingStatus - number value rejected',
+      () => sdk.api.organizations.updateOne(
+        orgId,
+        { onboardingStatus: { k: 1 as any } },
+        { replaceObjectFields: true }
+      ),
+      handleAnyError
+    )
+
     console.log("✅ All User portalSettings tests passed!")
   } finally {
     try {
@@ -189,7 +251,15 @@ export const user_portal_settings_tests = async ({ sdk, sdkNonAdmin }: { sdk: Se
         await sdk.api.endusers.deleteOne(testEnduserId)
       }
     } finally {
-      await sdk.api.users.deleteOne(testUser.id)
+      try {
+        await sdk.api.organizations.updateOne(
+          orgId,
+          { onboardingStatus: originalOnboardingStatus ?? {} },
+          { replaceObjectFields: true }
+        )
+      } finally {
+        await sdk.api.users.deleteOne(testUser.id)
+      }
     }
   }
 }