@tellescope/sdk 1.256.11 → 1.256.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tellescope/sdk",
-  "version": "1.256.11",
+  "version": "1.256.13",
   "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.11",
-    "@tellescope/schema": "1.256.11",
-    "@tellescope/testing": "1.256.11",
-    "@tellescope/types-client": "1.256.11",
-    "@tellescope/types-models": "1.256.11",
-    "@tellescope/types-utilities": "1.256.11",
-    "@tellescope/utilities": "1.256.11",
-    "@tellescope/validation": "1.256.11",
+    "@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",
     "axios": "0.30.3",
     "dotenv": "14.3.2",
     "form-data": "4.0.4",
@@ -55,5 +55,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "e0b2785223de7100a93651f4cf6f501223103054"
+  "gitHead": "457e037174ead2b05f585d810de05f724659430a"
 }

package/src/sdk.ts

@@ -810,6 +810,9 @@ type Queries = { [K in keyof ClientModelForName]: APIQuery<K> } & {
     load_events: (args: extractFields<CustomActions['calendar_events']['load_events']['parameters']>) => (
       Promise<extractFields<CustomActions['calendar_events']['load_events']['returns']>>
     ),
+    out_of_office: (args?: extractFields<CustomActions['calendar_events']['out_of_office']['parameters']>) => (
+      Promise<extractFields<CustomActions['calendar_events']['out_of_office']['returns']>>
+    ),
     generate_zoom_meeting: (args: extractFields<CustomActions['calendar_events']['generate_zoom_meeting']['parameters']>) => (
       Promise<extractFields<CustomActions['calendar_events']['generate_zoom_meeting']['returns']>>
     ),
@@ -1146,6 +1149,7 @@ export class Session extends SessionManager {
     queries.calendar_events.session_for_start_link = a => this._GET(`/v1${schema.calendar_events.publicActions.session_for_start_link.path}`, a)
     queries.calendar_events.get_events_for_user = a => this._GET(`/v1/${schema.calendar_events.customActions.get_events_for_user.path}`, a)
     queries.calendar_events.load_events = a => this._GET(`/v1/${schema.calendar_events.customActions.load_events.path}`, a)
+    queries.calendar_events.out_of_office = a => this._GET(`/v1${schema.calendar_events.customActions.out_of_office.path}`, a)
     queries.calendar_events.generate_meeting_link = a => this._POST(`/v1/${schema.calendar_events.customActions.generate_meeting_link.path}`, a)
     queries.calendar_events.generate_zoom_meeting = a => this._POST(`/v1/${schema.calendar_events.customActions.generate_zoom_meeting.path}`, a)
     queries.calendar_events.change_zoom_host = a => this._POST(`/v1/${schema.calendar_events.customActions.change_zoom_host.path}`, a)

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

@@ -0,0 +1,435 @@
+require('source-map-support').install();
+
+import { Session, EnduserSession } from "../../sdk"
+import {
+  async_test,
+  handleAnyError,
+  log_header,
+  wait,
+} from "@tellescope/testing"
+import { authenticate_enduser_via_token, setup_tests } from "../setup"
+
+const host = process.env.API_URL || 'http://localhost:8080' as const
+const businessId = '60398b1131a295e64f084ff6'
+
+// Second-tenant session, used to prove the active patient count never crosses tenants.
+// Same key used by the org-isolation tests in tests.ts.
+const OTHER_TENANT_API_KEY = "ba745e25162bb95a795c5fa1af70df188d93c4d3aac9c48b34a5c8c9dd7b80f7"
+
+// Arbitrary valid ObjectId — endusers carrying a customTypeId are excluded from the default count
+const TEST_CUSTOM_TYPE_ID = '60398b0231a295e64f084fd9'
+
+/**
+ * Locks in the behavior of getEngagedEndusers (endusers/engagement), which backs both the billing
+ * /usage endpoint and the super-admin active patient count. Every case creates exactly one
+ * qualifying (or deliberately non-qualifying) engagement record and asserts its effect on the
+ * distinct enduser count.
+ *
+ * All assertions are made inside a time window opened at the top of the test, so unrelated records
+ * left behind by other suites can't move the numbers.
+ */
+export const active_patient_count_tests = async ({ sdk, sdkNonAdmin } : { sdk: Session, sdkNonAdmin: Session }) => {
+  log_header("Active Patient Count Tests")
+
+  const userId = sdk.userInfo.id
+
+  // _id-based range filters use ObjectId.createFromTime, which floors to whole seconds — back off a
+  // couple of seconds so nothing created below can land before the window starts.
+  const windowStart = new Date(Date.now() - 2000)
+
+  const activeCount = (args: Parameters<typeof sdk.api.endusers.get_engagement_statistics>[0] = {}) => (
+    sdk.api.endusers.get_engagement_statistics({ range: { from: windowStart }, ...args })
+    .then(r => r.count)
+  )
+
+  // Scenarios are identified by fields.apcCase rather than fname, because fname is title-cased on
+  // create ('apc-email' is stored as 'Apc-email') while stored fields are kept verbatim.
+  const onlyCase = (apcCase: string) => activeCount({ enduserFields: [{ field: 'fields.apcCase', value: apcCase }] })
+  // every enduser this test creates, and nothing else
+  const onlyThisTest = (args: Parameters<typeof activeCount>[0] = {}) => activeCount({
+    ...args, enduserFields: [{ field: 'fields.apcCase', value: '$exists' }],
+  })
+
+  // One enduser per scenario, created in a single call to avoid create throttling
+  const [
+    eEmail, eEmailOutbound,
+    eSMS, eSMSOutbound,
+    eCallInbound, eCallLongOutbound, eCallShortOutbound,
+    eChat, eChatNoEnduser,
+    eForm, eFormUnsubmitted, eFormOtherForm,
+    eCalendar, eCalendarUserOnly, eCalendarPastStart,
+    eGroupMMS, eGroupMMSUserSender,
+    eDedupe,
+    eCustomType,
+    eInactive,
+  ] = (await sdk.api.endusers.createSome([
+    { fname: 'apc-email', fields: { apcCase: 'email', apcTag: 'yes', apcGroup: 'A' } },
+    { fname: 'apc-email-outbound', fields: { apcCase: 'email-outbound' } },
+    { fname: 'apc-sms', fields: { apcCase: 'sms', apcTag: 'yes', apcGroup: 'A' } },
+    { fname: 'apc-sms-outbound', fields: { apcCase: 'sms-outbound' } },
+    { fname: 'apc-call-inbound', fields: { apcCase: 'call-inbound', apcGroup: 'B' } },
+    { fname: 'apc-call-long-outbound', fields: { apcCase: 'call-long-outbound', apcGroup: 'B' } },
+    { fname: 'apc-call-short-outbound', fields: { apcCase: 'call-short-outbound' } },
+    { fname: 'apc-chat', fields: { apcCase: 'chat', apcGroup: 'B' } },
+    { fname: 'apc-chat-no-enduserid', fields: { apcCase: 'chat-no-enduserid' } },
+    { fname: 'apc-form', fields: { apcCase: 'form', apcGroup: 'C' } },
+    { fname: 'apc-form-unsubmitted', fields: { apcCase: 'form-unsubmitted' } },
+    { fname: 'apc-form-other-form', fields: { apcCase: 'form-other-form', apcGroup: 'C' } },
+    // deliberately has no apcGroup, so the $exists case below is narrower than the total
+    { fname: 'apc-calendar', fields: { apcCase: 'calendar' } },
+    { fname: 'apc-calendar-user-only', fields: { apcCase: 'calendar-user-only' } },
+    { fname: 'apc-calendar-past-start', fields: { apcCase: 'calendar-past-start' } },
+    { fname: 'apc-group-mms', fields: { apcCase: 'group-mms', apcGroup: 'D' } },
+    { fname: 'apc-group-mms-user-sender', fields: { apcCase: 'group-mms-user-sender' } },
+    { fname: 'apc-dedupe', fields: { apcCase: 'dedupe', apcTag: 'yes', apcGroup: 'D' } },
+    { fname: 'apc-custom-type', customTypeId: TEST_CUSTOM_TYPE_ID, fields: { apcCase: 'custom-type' } },
+    { fname: 'apc-inactive', fields: { apcCase: 'inactive' } },
+  ])).created
+
+  const createdEnduserIds = [
+    eEmail, eEmailOutbound, eSMS, eSMSOutbound, eCallInbound, eCallLongOutbound, eCallShortOutbound,
+    eChat, eChatNoEnduser, eForm, eFormUnsubmitted, eFormOtherForm, eCalendar, eCalendarUserOnly,
+    eCalendarPastStart, eGroupMMS, eGroupMMSUserSender, eDedupe, eCustomType, eInactive,
+  ].map(e => e.id)
+
+  const chatRoomIds: string[] = []
+  const conversationIds: string[] = []
+  const calendarEventIds: string[] = []
+  const formIds: string[] = []
+
+  try {
+    // --- emails ---------------------------------------------------------------------------------
+    await sdk.api.emails.createOne({
+      logOnly: true, inbound: true, userId,
+      enduserId: eEmail.id, subject: 'apc inbound', textContent: 'inbound email',
+    })
+    // outbound with no link opens does not qualify
+    await sdk.api.emails.createOne({
+      logOnly: true, inbound: false, userId,
+      enduserId: eEmailOutbound.id, subject: 'apc outbound', textContent: 'outbound email',
+    })
+
+    // --- sms_messages ---------------------------------------------------------------------------
+    await sdk.api.sms_messages.createOne({
+      logOnly: true, inbound: true, userId,
+      enduserId: eSMS.id, message: 'apc inbound sms',
+    })
+    await sdk.api.sms_messages.createOne({
+      logOnly: true, inbound: false, userId,
+      enduserId: eSMSOutbound.id, message: 'apc outbound sms',
+    })
+
+    // --- phone_calls ----------------------------------------------------------------------------
+    // inbound qualifies regardless of duration
+    await sdk.api.phone_calls.createOne({ enduserId: eCallInbound.id, inbound: true, userId })
+    // outbound qualifies only at >= 60 seconds
+    await sdk.api.phone_calls.createOne({
+      enduserId: eCallLongOutbound.id, inbound: false, userId, callDurationInSeconds: 60,
+    })
+    await sdk.api.phone_calls.createOne({
+      enduserId: eCallShortOutbound.id, inbound: false, userId, callDurationInSeconds: 59,
+    })
+
+    // --- chats ----------------------------------------------------------------------------------
+    const chatRoom = await sdk.api.chat_rooms.createOne({ enduserIds: [eChat.id], userIds: [userId] })
+    chatRoomIds.push(chatRoom.id)
+    await sdk.api.chats.createOne({
+      roomId: chatRoom.id, message: 'apc chat', senderId: eChat.id, enduserId: eChat.id,
+    })
+
+    // a chat with no enduserId can't be attributed to a patient
+    const chatRoomNoEnduser = await sdk.api.chat_rooms.createOne({
+      enduserIds: [eChatNoEnduser.id], userIds: [userId],
+    })
+    chatRoomIds.push(chatRoomNoEnduser.id)
+    await sdk.api.chats.createOne({
+      roomId: chatRoomNoEnduser.id, message: 'apc chat without enduserId', senderId: userId,
+    })
+
+    // --- form_responses -------------------------------------------------------------------------
+    const formA = await sdk.api.forms.createOne({ title: 'Active Patient Count Form A' })
+    formIds.push(formA.id)
+    const fieldA = await sdk.api.form_fields.createOne({
+      formId: formA.id, type: 'string', title: 'FieldA', previousFields: [{ type: 'root', info: {} }],
+    })
+
+    const formB = await sdk.api.forms.createOne({ title: 'Active Patient Count Form B' })
+    formIds.push(formB.id)
+    const fieldB = await sdk.api.form_fields.createOne({
+      formId: formB.id, type: 'string', title: 'FieldB', previousFields: [{ type: 'root', info: {} }],
+    })
+
+    const submitForm = async (formId: string, fieldId: string, fieldTitle: string, enduserId: string) => {
+      const { accessCode } = await sdk.api.form_responses.prepare_form_response({ enduserId, formId })
+      await sdk.api.form_responses.submit_form_response({
+        accessCode,
+        responses: [{ fieldId, fieldTitle, answer: { type: 'string', value: 'apc' } }],
+      })
+    }
+
+    await submitForm(formA.id, fieldA.id, 'FieldA', eForm.id)
+    await submitForm(formB.id, fieldB.id, 'FieldB', eFormOtherForm.id)
+
+    // prepared but never submitted — no submittedAt, so it must not qualify
+    await sdk.api.form_responses.prepare_form_response({
+      enduserId: eFormUnsubmitted.id, formId: formA.id,
+    })
+
+    // --- calendar_events ------------------------------------------------------------------------
+    // starts now, not in the future — the bounded-range case below closes the window a couple of
+    // seconds out, and calendar_events are filtered on startTimeInMS
+    const calendarEvent = await sdk.api.calendar_events.createOne({
+      title: 'apc event', durationInMinutes: 30, startTimeInMS: Date.now(),
+      attendees: [{ id: eCalendar.id, type: 'enduser' }],
+    })
+    calendarEventIds.push(calendarEvent.id)
+
+    const calendarEventUserOnly = await sdk.api.calendar_events.createOne({
+      title: 'apc event user only', durationInMinutes: 30, startTimeInMS: Date.now(),
+      attendees: [{ id: userId, type: 'user' }],
+    })
+    calendarEventIds.push(calendarEventUserOnly.id)
+
+    // created now, but starts 30 days ago — calendar_events filter on startTimeInMS, not _id, so
+    // this must fall outside the window even though the record itself is brand new
+    const calendarEventPastStart = await sdk.api.calendar_events.createOne({
+      title: 'apc event past start', durationInMinutes: 30,
+      startTimeInMS: Date.now() - 30 * 24 * 60 * 60 * 1000,
+      attendees: [{ id: eCalendarPastStart.id, type: 'enduser' }],
+    })
+    calendarEventIds.push(calendarEventPastStart.id)
+
+    // --- group_mms_conversations ----------------------------------------------------------------
+    const conversation = await sdk.api.group_mms_conversations.createOne({
+      enduserIds: [eGroupMMS.id, eGroupMMSUserSender.id], userIds: [userId], userStates: [], messages: [],
+    })
+    conversationIds.push(conversation.id)
+
+    await sdk.api.group_mms_conversations.send_message({
+      conversationId: conversation.id, sender: eGroupMMS.id, message: 'apc group mms', logOnly: true,
+    })
+    await wait(undefined, 250)
+    // sent by a user, so it counts for nobody — the other enduser in the conversation included
+    await sdk.api.group_mms_conversations.send_message({
+      conversationId: conversation.id, sender: userId, message: 'apc group mms from user', logOnly: true,
+    })
+    await wait(undefined, 250)
+
+    // --- dedupe: one enduser active across three channels ----------------------------------------
+    await sdk.api.emails.createOne({
+      logOnly: true, inbound: true, userId,
+      enduserId: eDedupe.id, subject: 'apc dedupe', textContent: 'inbound email',
+    })
+    await sdk.api.sms_messages.createOne({
+      logOnly: true, inbound: true, userId, enduserId: eDedupe.id, message: 'apc dedupe sms',
+    })
+    const dedupeRoom = await sdk.api.chat_rooms.createOne({ enduserIds: [eDedupe.id], userIds: [userId] })
+    chatRoomIds.push(dedupeRoom.id)
+    await sdk.api.chats.createOne({
+      roomId: dedupeRoom.id, message: 'apc dedupe chat', senderId: eDedupe.id, enduserId: eDedupe.id,
+    })
+
+    // --- customTypeId: excluded from the default count --------------------------------------------
+    await sdk.api.emails.createOne({
+      logOnly: true, inbound: true, userId,
+      enduserId: eCustomType.id, subject: 'apc custom type', textContent: 'inbound email',
+    })
+
+    await wait(undefined, 1000) // let side effects settle
+
+    // Qualifying endusers: email, sms, inbound call, long outbound call, chat, form A, form B,
+    // calendar, group mms, dedupe = 10. eCustomType is excluded by customTypeId.
+    const EXPECTED_ACTIVE = 10
+
+    await async_test(
+      "Active count includes exactly the qualifying endusers",
+      () => onlyThisTest(),
+      { onResult: r => r === EXPECTED_ACTIVE }
+    )
+
+    // --- dedupe ----------------------------------------------------------------------------------
+    await async_test(
+      "Enduser active on email + sms + chat counts once",
+      () => onlyCase('dedupe'),
+      { onResult: r => r === 1 }
+    )
+
+    // --- per-channel attribution -----------------------------------------------------------------
+    const expectActive = (label: string, apcCase: string, expected: number) => async_test(
+      label,
+      () => onlyCase(apcCase),
+      { onResult: r => r === expected }
+    )
+
+    await expectActive("Inbound email counts", 'email', 1)
+    await expectActive("Outbound email without link opens does not count", 'email-outbound', 0)
+    await expectActive("Inbound SMS counts", 'sms', 1)
+    await expectActive("Outbound SMS does not count", 'sms-outbound', 0)
+    await expectActive("Inbound phone call counts", 'call-inbound', 1)
+    await expectActive("Outbound phone call >= 60s counts", 'call-long-outbound', 1)
+    await expectActive("Outbound phone call < 60s does not count", 'call-short-outbound', 0)
+    await expectActive("Chat with enduserId counts", 'chat', 1)
+    await expectActive("Chat without enduserId does not count", 'chat-no-enduserid', 0)
+    await expectActive("Submitted form response counts", 'form', 1)
+    await expectActive("Unsubmitted form response does not count", 'form-unsubmitted', 0)
+    await expectActive("Calendar event with enduser attendee counts", 'calendar', 1)
+    await expectActive("Calendar event with only user attendees does not count", 'calendar-user-only', 0)
+    await expectActive("Inbound group MMS counts", 'group-mms', 1)
+    await expectActive("Group MMS sent by a user does not count", 'group-mms-user-sender', 0)
+    await expectActive("Enduser with no engagement does not count", 'inactive', 0)
+
+    // --- date field per collection ----------------------------------------------------------------
+    await async_test(
+      "Calendar event is filtered by startTimeInMS, not creation time",
+      () => onlyCase('calendar-past-start'),
+      { onResult: r => r === 0 }
+    )
+
+    // --- range boundaries -------------------------------------------------------------------------
+    const afterAll = new Date(Date.now() + 2000)
+
+    await async_test(
+      "Active count is unchanged with an explicit upper bound after all activity",
+      () => sdk.api.endusers.get_engagement_statistics({
+        range: { from: windowStart, to: afterAll },
+        enduserFields: [{ field: 'fields.apcCase', value: '$exists' }],
+      }).then(r => r.count),
+      { onResult: r => r === EXPECTED_ACTIVE }
+    )
+    await async_test(
+      "Active count is 0 for a range that starts after all activity",
+      () => sdk.api.endusers.get_engagement_statistics({ range: { from: afterAll } }).then(r => r.count),
+      { onResult: r => r === 0 }
+    )
+    await async_test(
+      "Active count is 0 for a range that ends before all activity",
+      () => sdk.api.endusers.get_engagement_statistics({
+        range: { from: new Date(windowStart.getTime() - 4000), to: windowStart },
+        enduserFields: [{ field: 'fields.apcCase', value: '$exists' }],
+      }).then(r => r.count),
+      { onResult: r => r === 0 }
+    )
+
+    // --- customTypeId ------------------------------------------------------------------------------
+    await async_test(
+      "Endusers with a customTypeId are excluded by default",
+      () => onlyCase('custom-type'),
+      { onResult: r => r === 0 }
+    )
+    await async_test(
+      "Endusers with a customTypeId are included when that customTypeId is requested",
+      () => activeCount({ customTypeId: TEST_CUSTOM_TYPE_ID }),
+      { onResult: r => r === 1 }
+    )
+
+    // --- formIds ------------------------------------------------------------------------------------
+    await async_test(
+      "formIds narrows which form responses qualify",
+      () => onlyThisTest({ formIds: [formA.id] }),
+      { onResult: r => r === EXPECTED_ACTIVE - 1 } // drops the enduser who only submitted form B
+    )
+
+    // --- endusersFilter (a separate code path from enduserFields) -------------------------------------
+    await async_test(
+      "endusersFilter narrows the counted endusers",
+      () => activeCount({ endusersFilter: { 'fields.apcCase': 'email' } }),
+      { onResult: r => r === 1 }
+    )
+
+    // --- enduserFields -------------------------------------------------------------------------------
+    await async_test(
+      "enduserFields matches on a stored field value",
+      () => activeCount({ enduserFields: [{ field: 'fields.apcTag', value: 'yes' }] }),
+      { onResult: r => r === 3 } // email, sms, dedupe
+    )
+    await async_test(
+      "enduserFields supports the $exists qualifier",
+      () => activeCount({ enduserFields: [{ field: 'fields.apcGroup', value: '$exists' }] }),
+      { onResult: r => r === EXPECTED_ACTIVE - 1 } // all active endusers except apc-calendar
+    )
+
+    // --- groupBy ---------------------------------------------------------------------------------------
+    await async_test(
+      "groupBy returns per-group counts summing to the total",
+      () => sdk.api.endusers.get_engagement_statistics({
+        range: { from: windowStart }, groupBy: 'fields.apcGroup',
+        enduserFields: [{ field: 'fields.apcCase', value: '$exists' }],
+      }),
+      {
+        onResult: r => (
+          Array.isArray(r.grouped)
+          && r.grouped.reduce((sum, g) => sum + g.count, 0) === EXPECTED_ACTIVE
+        )
+      }
+    )
+
+    // --- endusers cannot read org-wide staff analytics ------------------------------------------------
+    const enduserSDK = new EnduserSession({ host, businessId })
+    await authenticate_enduser_via_token(sdk, enduserSDK, { id: eEmail.id })
+
+    await async_test(
+      "Endusers cannot call get_engagement_statistics",
+      () => enduserSDK._GET('/v1/endusers/engagement', { range: { from: windowStart } }),
+      handleAnyError
+    )
+
+    // --- tenant isolation --------------------------------------------------------------------------------
+    // The refactor drops restrictAccess in favor of a direct businessId match, so this is the one
+    // boundary the function now enforces entirely on its own.
+    const sdkOther = new Session({ host, apiKey: OTHER_TENANT_API_KEY })
+    const otherWindowStart = new Date(Date.now() - 2000)
+    const otherEnduser = await sdkOther.api.endusers.createOne({ fname: 'apc-other-tenant' })
+
+    try {
+      // userId is left to its session initializer — this is an API-key session with no logged-in user
+      await sdkOther.api.emails.createOne({
+        logOnly: true, inbound: true,
+        enduserId: otherEnduser.id, subject: 'apc other tenant', textContent: 'inbound email',
+      })
+      await wait(undefined, 500)
+
+      await async_test(
+        "Other tenant's engagement does not appear in this tenant's count",
+        () => onlyThisTest(),
+        { onResult: r => r === EXPECTED_ACTIVE }
+      )
+      await async_test(
+        "This tenant's engagement does not appear in the other tenant's count",
+        () => sdkOther.api.endusers.get_engagement_statistics({ range: { from: otherWindowStart } })
+          .then(r => r.count),
+        { onResult: r => r === 1 }
+      )
+    } finally {
+      await sdkOther.api.endusers.deleteOne(otherEnduser.id).catch(console.error)
+    }
+  } finally {
+    await Promise.all([
+      ...createdEnduserIds.map(id => sdk.api.endusers.deleteOne(id).catch(console.error)),
+      ...chatRoomIds.map(id => sdk.api.chat_rooms.deleteOne(id).catch(console.error)),
+      ...conversationIds.map(id => sdk.api.group_mms_conversations.deleteOne(id).catch(console.error)),
+      ...calendarEventIds.map(id => sdk.api.calendar_events.deleteOne(id).catch(console.error)),
+      ...formIds.map(id => sdk.api.forms.deleteOne(id).catch(console.error)),
+    ])
+  }
+}
+
+// Allow running this test file independently
+if (require.main === module) {
+  const sdk = new Session({ host })
+  const sdkNonAdmin = new Session({ host })
+
+  const runTests = async () => {
+    await setup_tests(sdk, sdkNonAdmin)
+    await active_patient_count_tests({ sdk, sdkNonAdmin })
+  }
+
+  runTests()
+  .then(() => {
+    console.log("✅ Active patient count test suite completed successfully")
+    process.exit(0)
+  })
+  .catch((error) => {
+    console.error("❌ Active patient count test suite failed:", error)
+    process.exit(1)
+  })
+}

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

@@ -0,0 +1,162 @@
+require('source-map-support').install();
+
+import { Session } from "../../sdk"
+import {
+  assert,
+  log_header,
+} from "@tellescope/testing"
+import { setup_tests } from "../setup"
+
+const host = process.env.API_URL || 'http://localhost:8080' as const
+
+const MS_PER_MINUTE = 60 * 1000
+const MS_PER_HOUR = 60 * MS_PER_MINUTE
+
+// Covers the calendar_events.out_of_office endpoint, whose whole reason to exist is that it reads
+// ACROSS users: calendar_events is row-filtered on attendees.id and a non-admin defaults to
+// read: 'Assigned', so the ordinary read path returns only the caller's own blocks. The endpoint
+// therefore queries organization-wide on purpose, and returns no event content to make that safe.
+//
+// The cross-user assertion below is the one that matters: swapping the handler's
+// buildOrganizationWideQueries back to the request-scoped DB would silently break peer visibility in
+// Team Chat without breaking a build or any other test.
+export const out_of_office_endpoint_tests = async ({ sdk, sdkNonAdmin } : { sdk: Session, sdkNonAdmin: Session }) => {
+  log_header("Out of Office Endpoint")
+
+  const adminId = sdk.userInfo.id
+  const nonAdminId = sdkNonAdmin.userInfo.id
+  const now = Date.now()
+
+  // active right now, on the ADMIN, so the non-admin is neither an attendee nor the creator
+  const active = await sdk.api.calendar_events.createOne({
+    title: 'Out of Office',
+    outOfOffice: true,
+    startTimeInMS: now - 2 * MS_PER_HOUR,
+    durationInMinutes: 8 * 60,
+    attendees: [{ id: adminId, type: 'user' }],
+  })
+  // ended three hours ago — inside the query's start-time range, so only the handler's computed
+  // end-time check excludes it
+  const ended = await sdk.api.calendar_events.createOne({
+    title: 'Out of Office',
+    outOfOffice: true,
+    startTimeInMS: now - 5 * MS_PER_HOUR,
+    durationInMinutes: 2 * 60,
+    attendees: [{ id: adminId, type: 'user' }],
+  })
+  const cancelled = await sdk.api.calendar_events.createOne({
+    title: 'Out of Office',
+    outOfOffice: true,
+    startTimeInMS: now - MS_PER_HOUR,
+    durationInMinutes: 4 * 60,
+    attendees: [{ id: adminId, type: 'user' }],
+    cancelledAt: new Date(),
+  })
+  // not flagged: a normal event overlapping now must never appear
+  const normal = await sdk.api.calendar_events.createOne({
+    title: 'Regular Appointment',
+    startTimeInMS: now - MS_PER_HOUR,
+    durationInMinutes: 4 * 60,
+    attendees: [{ id: adminId, type: 'user' }],
+  })
+  // on the non-admin, used for the userIds scoping check
+  const nonAdminOwn = await sdk.api.calendar_events.createOne({
+    title: 'Out of Office',
+    outOfOffice: true,
+    startTimeInMS: now - MS_PER_HOUR,
+    durationInMinutes: 4 * 60,
+    attendees: [{ id: nonAdminId, type: 'user' }],
+  })
+
+  try {
+    const { outOfOffice } = await sdkNonAdmin.api.calendar_events.out_of_office()
+
+    // assert(assertion, failureMessage, successTitle)
+    assert(
+      !!outOfOffice.find(o => o.userId === adminId && o.startTimeInMS === active.startTimeInMS),
+      'non-admin does NOT see a peer out of office window — is the handler using the request-scoped DB instead of buildOrganizationWideQueries?',
+      'non-admin sees a peer out of office window',
+    )
+
+    assert(
+      outOfOffice.every(o => (
+        Object.keys(o).sort().join(',') === 'endTimeInMS,startTimeInMS,userId'
+      )),
+      `response leaked event fields: ${JSON.stringify(outOfOffice[0] ?? {})}`,
+      'response carries no event content',
+    )
+
+    const forAdmin = outOfOffice.filter(o => o.userId === adminId)
+    assert(
+      forAdmin.length === 1,
+      `expected exactly the one active window for the admin, got ${forAdmin.length}: ${JSON.stringify(forAdmin)}`,
+      'ended, cancelled and unflagged events are excluded',
+    )
+    assert(
+      forAdmin[0]?.endTimeInMS === active.startTimeInMS + active.durationInMinutes * MS_PER_MINUTE,
+      `endTimeInMS was ${forAdmin[0]?.endTimeInMS}, expected ${active.startTimeInMS + active.durationInMinutes * MS_PER_MINUTE}`,
+      'endTimeInMS is resolved from startTimeInMS + durationInMinutes',
+    )
+
+    // An admin's reads are unrestricted anyway, so this passes even if the handler were reverted to
+    // the request-scoped DB — it's the non-admin assertion above that pins the design. Kept as the
+    // pair, so the two together show the result is role-independent rather than role-dependent.
+    const asAdmin = await sdk.api.calendar_events.out_of_office()
+    assert(
+      !!asAdmin.outOfOffice.find(o => o.userId === adminId && o.startTimeInMS === active.startTimeInMS)
+      && !!asAdmin.outOfOffice.find(o => o.userId === nonAdminId),
+      `admin load missing windows: ${JSON.stringify(asAdmin.outOfOffice)}`,
+      'admin sees both its own and a peer out of office window',
+    )
+    assert(
+      asAdmin.outOfOffice.filter(o => o.userId === adminId).length === forAdmin.length,
+      `admin and non-admin disagree on the admin's windows: ${JSON.stringify(asAdmin.outOfOffice.filter(o => o.userId === adminId))} vs ${JSON.stringify(forAdmin)}`,
+      'admin and non-admin loads return the same windows',
+    )
+
+    const scoped = await sdkNonAdmin.api.calendar_events.out_of_office({ userIds: [nonAdminId] })
+    assert(
+      scoped.outOfOffice.length === 1 && scoped.outOfOffice[0].userId === nonAdminId,
+      `expected only the requested user, got ${JSON.stringify(scoped.outOfOffice)}`,
+      'userIds scopes the result',
+    )
+
+    // a real ObjectId that belongs to no user in this business
+    const foreign = await sdkNonAdmin.api.calendar_events.out_of_office({ userIds: ['5fdb3d4a4e6e2a0016a1a1a1'] })
+    assert(
+      foreign.outOfOffice.length === 0,
+      `expected empty for unknown userIds, got ${JSON.stringify(foreign.outOfOffice)}`,
+      'unknown userIds return nothing',
+    )
+  } finally {
+    await Promise.all([
+      sdk.api.calendar_events.deleteOne(active.id),
+      sdk.api.calendar_events.deleteOne(ended.id),
+      sdk.api.calendar_events.deleteOne(cancelled.id),
+      sdk.api.calendar_events.deleteOne(normal.id),
+      sdk.api.calendar_events.deleteOne(nonAdminOwn.id),
+    ])
+  }
+}
+
+// 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 out_of_office_endpoint_tests({ sdk, sdkNonAdmin })
+  }
+
+  runTests()
+    .then(() => {
+      console.log("✅ Out of office endpoint test suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ Out of office endpoint test suite failed:", error)
+      process.exit(1)
+    })
+}