@tellescope/sdk 1.253.0 → 1.254.0

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/field_redaction.test.ts

@@ -56,14 +56,27 @@ export const field_redaction_tests = async ({ sdk, sdkNonAdmin } : { sdk: Sessio
   const FULL_ACCESS = { create: 'All' as const, read: 'All' as const, update: 'All' as const, delete: 'All' as const }
 
   const fullRedactionRole = 'full-redaction-test-role'
+  const ROLE_COLOR = '#FF8800'
+  const ROLE_DESCRIPTION = 'Role used by field redaction tests'
   const rbapFull = await sdk.api.role_based_access_permissions.createOne({
     role: fullRedactionRole,
     permissions: { ...PROVIDER_PERMISSIONS, phone_calls: FULL_ACCESS, endusers: FULL_ACCESS },
     fieldRedactions: {
       phone_calls: [...ALL_REDACTABLE_FIELDS],
     },
+    color: ROLE_COLOR,
+    description: ROLE_DESCRIPTION,
   })
 
+  // Verify color/description persist and round-trip via getOne
+  await async_test(
+    "role_based_access_permissions - color and description persist on create/read",
+    () => sdk.api.role_based_access_permissions.getOne(rbapFull.id),
+    {
+      onResult: (r: any) => r.color === ROLE_COLOR && r.description === ROLE_DESCRIPTION,
+    }
+  )
+
   const originalRoles = sdkNonAdmin.userInfo.roles
 
   try {

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/journey_error_branching.test.ts

@@ -428,7 +428,11 @@ const pollForErrorHandling = async <T>(
   evaluateFn: (result: T) => boolean,
   description: string,
   intervalMs = 500,
-  maxIterations = 20
+  // Default window must exceed two worker poll cycles. Automated actions are processed every
+  // >= 8s (worker pollingDelaySeconds = Math.max(NUM_THREADS, 8)), and the onError flow needs
+  // two cycles (cycle 1: action fails + onError action created; cycle 2: onError tag added),
+  // so ~16s worst case. 60 * 500ms = 30s gives buffer. Do not lower below ~30s.
+  maxIterations = 60
 ): Promise<void> => {
   let lastResult: T | undefined
 

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

@@ -0,0 +1,303 @@
+require('source-map-support').install();
+
+import { Session } from "../../sdk"
+import {
+  async_test,
+  handleAnyError,
+  log_header,
+  wait,
+  assert,
+} from "@tellescope/testing"
+import { PROVIDER_PERMISSIONS } from "@tellescope/constants"
+import { setup_tests } from "../setup"
+
+const host = process.env.API_URL || 'http://localhost:8080' as const
+
+const RAND = () => Math.random().toString(36).slice(2, 10)
+
+const TAG_A = 'resource-access-tag-A'
+const TAG_B = 'resource-access-tag-B'
+
+/**
+ * Tests for settings.users.enableResourceAccessTags (the `erat` session flag).
+ *
+ * When the org setting is enabled, org-level configuration resources carrying `accessTags`
+ * become visible only to non-admin (Default/Assigned) users whose own tags intersect the
+ * record's accessTags. This mirrors the existing enduser accessTags behavior, generalized
+ * to the 9 RESOURCE_ACCESS_TAG_MODELS.
+ *
+ * The model is ADDITIVE: a record only becomes tag-gated once an admin sets accessTags on it.
+ * Records without accessTags keep their existing rules (Default == creator-only). Admins and
+ * All-access users are unaffected.
+ *
+ * Per the throwaway-user testing guidance, this test creates throwaway users rather than
+ * mutating existing user roles. Tokens are minted via generate_auth_token AFTER the org
+ * setting is enabled, so the `erat` flag lands in their sessions.
+ */
+export const resource_access_tags_tests = async ({ sdk } : { sdk: Session, sdkNonAdmin: Session }) => {
+  log_header("Resource Access Tags Tests")
+
+  const DEFAULT_RW = { create: 'Default', read: 'Default', update: 'Default', delete: 'Default' } as const
+  const ALL_RW = { create: 'All', read: 'All', update: 'All', delete: 'All' } as const
+
+  const RESOURCE_MODELS = [
+    'templates', 'forms', 'journeys', 'automation_triggers', 'calendar_event_templates',
+    'appointment_booking_pages', 'table_views', 'files', 'managed_content_records',
+  ] as const
+
+  // track everything we create for cleanup
+  const createdUserIds: string[] = []
+  const createdRoleIds: string[] = []
+  const createdByModel: Record<string, string[]> = {}
+  for (const m of RESOURCE_MODELS) createdByModel[m] = []
+  let helperTemplateId: string | undefined // calendar_event_template used as a booking-page dependency
+
+  const orgId = sdk.userInfo.businessId
+
+  try {
+    // ── 1. Enable the org setting ───────────────────────────────────────────────
+    // Explicitly disable enduser access tags (eat) so that the tag-edit-restriction
+    // assertions below prove the `erat` flag alone enforces the protection (otherwise
+    // a residual `eat` could mask the gap). Settings deep-merge, so this is targeted.
+    await sdk.api.organizations.updateOne(orgId, {
+      settings: { users: { enableResourceAccessTags: true }, endusers: { enableAccessTags: false } },
+    })
+
+    // ── 2. Roles: Default read for a tag-gated user, All read for a control user ──
+    const defaultPermissions: any = { ...PROVIDER_PERMISSIONS }
+    const allPermissions: any = { ...PROVIDER_PERMISSIONS }
+    for (const m of RESOURCE_MODELS) {
+      defaultPermissions[m] = { ...DEFAULT_RW }
+      allPermissions[m] = { ...ALL_RW }
+    }
+
+    const defaultRole = `resource-access-tags-default-${RAND()}`
+    const allRole = `resource-access-tags-all-${RAND()}`
+    const rbapDefault = await sdk.api.role_based_access_permissions.createOne({ role: defaultRole, permissions: defaultPermissions })
+    const rbapAll = await sdk.api.role_based_access_permissions.createOne({ role: allRole, permissions: allPermissions })
+    createdRoleIds.push(rbapDefault.id, rbapAll.id)
+
+    // ── 3. Throwaway users + tokens (minted AFTER enabling the setting → erat set) ─
+    const mkUser = async (tags: string[], roles: string[]) => {
+      const user = await sdk.api.users.createOne({
+        email: `resource-access-tags-${RAND()}@tellescope.example`,
+        fname: 'Resource', lname: 'AccessTags',
+        notificationEmailsDisabled: true, verifiedEmail: true,
+        tags, roles,
+      } as any)
+      createdUserIds.push(user.id)
+      // mint AFTER the setting is enabled so the erat flag lands in the session/JWT
+      const { authToken, user: sessionUser } = await sdk.api.users.generate_auth_token({ id: user.id })
+      const session = new Session({ host })
+      session.setAuthToken(authToken)
+      session.setUserInfo(sessionUser as any)
+      return { session, sessionUser: sessionUser as any }
+    }
+
+    const { session: sdkWithTag, sessionUser: withTagUser } = await mkUser([TAG_A], [defaultRole]) // Default access, carries the gating tag
+    const { session: sdkWithoutTag } = await mkUser([TAG_B], [defaultRole]) // Default access, lacks the gating tag
+    const { session: sdkAllAccess } = await mkUser([TAG_B], [allRole])      // All access, lacks the tag (should still see everything)
+
+    // sanity check: erat made it into the gated sessions
+    assert(!!withTagUser.erat, 'erat flag missing on tagged user session', 'erat flag present on tagged user session')
+
+    // ── 4. Per-model record creation (tagged with TAG_A + untagged control) ──────
+    // calendar_event_template dependency for booking pages
+    const helperTemplate = await sdk.api.calendar_event_templates.createOne({ title: `RAT helper ${RAND()}`, durationInMinutes: 30 })
+    helperTemplateId = helperTemplate.id
+    createdByModel['calendar_event_templates'].push(helperTemplate.id)
+
+    const createRecord = async (model: typeof RESOURCE_MODELS[number], accessTags?: string[]): Promise<string> => {
+      const tags = accessTags ? { accessTags } : {}
+      let id: string
+      switch (model) {
+        case 'templates': {
+          const r = await sdk.api.templates.createOne({ title: `RAT tmpl ${RAND()}`, subject: 's', html: '<p>x</p>', message: 'm', ...tags } as any)
+          id = r.id; break
+        }
+        case 'forms': {
+          const r = await sdk.api.forms.createOne({ title: `RAT form ${RAND()}`, ...tags } as any)
+          id = r.id; break
+        }
+        case 'journeys': {
+          const r = await sdk.api.journeys.createOne({ title: `RAT jrn ${RAND()}`, ...tags } as any)
+          id = r.id; break
+        }
+        case 'automation_triggers': {
+          const r = await sdk.api.automation_triggers.createOne({
+            title: `RAT trg ${RAND()}`, status: 'Active',
+            event: { type: 'Appointment Completed', info: {} },
+            action: { type: 'Add Tags', info: { tags: ['x'] } },
+            ...tags,
+          } as any)
+          id = r.id; break
+        }
+        case 'calendar_event_templates': {
+          const r = await sdk.api.calendar_event_templates.createOne({ title: `RAT cet ${RAND()}`, durationInMinutes: 30, ...tags } as any)
+          id = r.id; break
+        }
+        case 'appointment_booking_pages': {
+          const r = await sdk.api.appointment_booking_pages.createOne({
+            title: `RAT bp ${RAND()}`, calendarEventTemplateIds: [helperTemplateId!], locationIds: [], ...tags,
+          } as any)
+          id = r.id; break
+        }
+        case 'table_views': {
+          const r = await sdk.api.table_views.createOne({ title: `RAT view ${RAND()}`, page: 'Ticket', columns: [], ...tags } as any)
+          id = r.id; break
+        }
+        case 'files': {
+          const { file } = await sdk.api.files.prepare_file_upload({ name: `RAT file ${RAND()}`, type: 'text/plain', size: 1 })
+          if (accessTags) await sdk.api.files.updateOne(file.id, { accessTags } as any)
+          id = file.id; break
+        }
+        case 'managed_content_records': {
+          const r = await sdk.api.managed_content_records.createOne({ title: `RAT content ${RAND()}`, textContent: 't', ...tags } as any)
+          id = r.id; break
+        }
+        default: throw new Error(`unhandled model ${model}`)
+      }
+      createdByModel[model].push(id)
+      return id
+    }
+
+    const recordsByModel: Record<string, { taggedId: string, untaggedId: string }> = {}
+    for (const model of RESOURCE_MODELS) {
+      const taggedId = await createRecord(model, [TAG_A])
+      const untaggedId = await createRecord(model)
+      recordsByModel[model] = { taggedId, untaggedId }
+    }
+
+    // ── 5. Assertions per model ──────────────────────────────────────────────────
+    const visibleIds = async (session: Session, model: string, ids: string[]): Promise<Set<string>> => {
+      const records = await (session.api as any)[model].getSome({ ids, limit: 100 })
+      return new Set(records.map((r: any) => r.id))
+    }
+
+    for (const model of RESOURCE_MODELS) {
+      const { taggedId, untaggedId } = recordsByModel[model]
+      const ids = [taggedId, untaggedId]
+
+      const withTag = await visibleIds(sdkWithTag, model, ids)
+      const withoutTag = await visibleIds(sdkWithoutTag, model, ids)
+      const admin = await visibleIds(sdk, model, ids)
+      const allAccess = await visibleIds(sdkAllAccess, model, ids)
+
+      await async_test(
+        `${model}: user WITH matching tag CAN read the tagged record`,
+        async () => withTag.has(taggedId),
+        { onResult: r => r === true },
+      )
+      await async_test(
+        `${model}: user WITHOUT matching tag CANNOT read the tagged record`,
+        async () => withoutTag.has(taggedId),
+        { onResult: r => r === false },
+      )
+      await async_test(
+        `${model}: untagged admin record NOT visible to tagged user (additive model)`,
+        async () => withTag.has(untaggedId),
+        { onResult: r => r === false },
+      )
+      await async_test(
+        `${model}: untagged admin record NOT visible to untagged user (additive model)`,
+        async () => withoutTag.has(untaggedId),
+        { onResult: r => r === false },
+      )
+      await async_test(
+        `${model}: admin sees both records (gating does not apply)`,
+        async () => admin.has(taggedId) && admin.has(untaggedId),
+        { onResult: r => r === true },
+      )
+      await async_test(
+        `${model}: All-access user sees both records (gating does not apply)`,
+        async () => allAccess.has(taggedId) && allAccess.has(untaggedId),
+        { onResult: r => r === true },
+      )
+    }
+
+    // ── 5b. Tag-edit restriction: a non-admin cannot edit tags to self-escalate ──
+    // With erat ON and eat OFF, the users.tags edit guard must still fire — proving
+    // resource access tags (not just enduser access tags) trigger the protection.
+    log_header("Resource Access Tags: tag-edit blocked")
+    const withTagUserId = createdUserIds[0]
+    await async_test(
+      `non-admin can't update own tags (erat enabled)`,
+      () => sdkWithTag.api.users.updateOne(withTagUserId, { tags: ['escalate'] }),
+      handleAnyError,
+    )
+    await async_test(
+      `non-admin can't update own tags alongside other fields (erat enabled)`,
+      () => sdkWithTag.api.users.updateOne(withTagUserId, { tags: ['escalate'], bio: '' }),
+      handleAnyError,
+    )
+    await async_test(
+      `non-admin can still update non-tag fields (control)`,
+      () => sdkWithTag.api.users.updateOne(withTagUserId, { bio: '' }),
+      { shouldError: false, onResult: () => true },
+    )
+
+    // ── 6. Org-setting-OFF control: disabling the flag gates the whole feature ────
+    log_header("Resource Access Tags: org-setting-OFF control")
+    await sdk.api.organizations.updateOne(orgId, {
+      settings: { users: { enableResourceAccessTags: false } },
+    })
+    // re-mint the tagged user's token so the (now-disabled) setting is reflected in the session
+    const { authToken: reAuthToken, user: reAuthUser } = await sdk.api.users.generate_auth_token({ id: createdUserIds[0] })
+    const sdkWithTagOff = new Session({ host })
+    sdkWithTagOff.setAuthToken(reAuthToken)
+    sdkWithTagOff.setUserInfo(reAuthUser as any)
+    assert(!(reAuthUser as any).erat, 'erat flag should be absent after disabling setting', 'erat flag absent after disabling setting')
+
+    const { taggedId: templatesTaggedId } = recordsByModel['templates']
+    const offVisible = await visibleIds(sdkWithTagOff, 'templates', [templatesTaggedId])
+    await async_test(
+      `templates: tagged record NOT visible to tagged user once setting is OFF`,
+      async () => offVisible.has(templatesTaggedId),
+      { onResult: r => r === false },
+    )
+
+    console.log("\n" + "=".repeat(60))
+    console.log("Resource Access Tags Tests Complete")
+    console.log("=".repeat(60))
+  } finally {
+    // ── Cleanup ────────────────────────────────────────────────────────────────
+    for (const model of RESOURCE_MODELS) {
+      for (const id of createdByModel[model]) {
+        await (sdk.api as any)[model].deleteOne(id).catch(() => {})
+      }
+    }
+    for (const id of createdRoleIds) {
+      await sdk.api.role_based_access_permissions.deleteOne(id).catch(() => {})
+    }
+    for (const id of createdUserIds) {
+      await sdk.api.users.deleteOne(id).catch(() => {})
+    }
+    // reset the org setting
+    await sdk.api.organizations.updateOne(orgId, {
+      settings: { users: { enableResourceAccessTags: false } },
+    }).catch(() => {})
+    await wait(undefined, 250)
+  }
+}
+
+// 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 resource_access_tags_tests({ sdk, sdkNonAdmin })
+  }
+
+  runTests()
+    .then(() => {
+      console.log("✅ Resource access tags test suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ Resource access tags test suite failed:", error)
+      process.exit(1)
+    })
+}