@tellescope/sdk 2.0.0-beta.0 → 2.0.0-beta.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tellescope/sdk",
-  "version": "2.0.0-beta.0",
+  "version": "2.0.0-beta.2",
   "description": "Code for interacting with the Tellescope API",
   "main": "./lib/cjs/sdk.js",
   "module": "./lib/esm/sdk.js",
@@ -35,17 +35,18 @@
     "node": ">=22.12.0"
   },
   "dependencies": {
-    "@tellescope/constants": "2.0.0-beta.0",
-    "@tellescope/schema": "2.0.0-beta.0",
-    "@tellescope/testing": "2.0.0-beta.0",
-    "@tellescope/types-client": "2.0.0-beta.0",
-    "@tellescope/types-models": "2.0.0-beta.0",
-    "@tellescope/types-utilities": "2.0.0-beta.0",
-    "@tellescope/utilities": "2.0.0-beta.0",
-    "@tellescope/validation": "2.0.0-beta.0",
-    "axios": "0.33.0",
+    "@tellescope/constants": "2.0.0-beta.2",
+    "@tellescope/schema": "2.0.0-beta.2",
+    "@tellescope/testing": "2.0.0-beta.2",
+    "@tellescope/types-client": "2.0.0-beta.2",
+    "@tellescope/types-models": "2.0.0-beta.2",
+    "@tellescope/types-utilities": "2.0.0-beta.2",
+    "@tellescope/utilities": "2.0.0-beta.2",
+    "@tellescope/validation": "2.0.0-beta.2",
+    "axios": "0.34.0",
     "dotenv": "14.3.2",
     "form-data": "4.0.6",
+    "mongodb": "5.7.0",
     "source-map-support": "0.5.21"
   },
   "devDependencies": {
@@ -58,5 +59,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "95b2448bb219e7634e29ef4b7850f8f74d73dcbc"
+  "gitHead": "8f2fcf1866332fc118a58775092cc6464dabecc0"
 }

package/src/sdk.ts

@@ -35,6 +35,7 @@ import {
 } from "@tellescope/types-client"
 import { CustomUpdateOptions, SortOption, UserIdentity, FileDetails, ReactNativeFile, SessionType } from "@tellescope/types-utilities"
 import { url_safe_path } from "@tellescope/utilities"
+import type { Filter } from "mongodb"
 
 import { Session as SessionManager, SessionOptions } from "./session"
 
@@ -79,7 +80,7 @@ export interface LoadFunctionArguments <T> {
   search?: SearchOptions,
   ids?: string[],
   returnCount?: boolean,
-  mdbFilter?: any,
+  mdbFilter?: Filter<T>,
   mdbSort?: any,
   projection?: { [K in keyof T]?: 1 },
 }
@@ -95,7 +96,7 @@ export interface APIQuery<
 {
   createOne: (t: CREATE & { sharedWithOrganizations?: string[][], _overrideUnique?: boolean }) => Promise<T>;
   createSome: (ts: CREATE[], o?: { _overrideUnique?: boolean }) => Promise<{ created: T[], errors: object[] }>;
-  getOne: (argument: string | ReadFilter<T>, mdbFilter?: any) => Promise<T>;
+  getOne: (argument: string | ReadFilter<T>, mdbFilter?: Filter<T>) => Promise<T>;
   getSome: LoadFunction<T>;
   getByIds: ({ ids } : { ids: string[] }) => Promise<{ matches: T[] }>;
   updateOne: (id: string, updates: UPDATE, options?: CustomUpdateOptions, _overrideUnique?: boolean) => Promise<T>;
@@ -234,6 +235,11 @@ const loadDefaultQueries = (s: Session): { [K in keyof ClientModelForName] : API
 })
 
 type Queries = { [K in keyof ClientModelForName]: APIQuery<K> } & {
+  user_logs: {
+    restore_deleted: (args: extractFields<CustomActions['user_logs']['restore_deleted']['parameters']>) => (
+      Promise<extractFields<CustomActions['user_logs']['restore_deleted']['returns']>>
+    ),
+  },
   inbox_threads: {
     build_threads: (args: extractFields<CustomActions['inbox_threads']['build_threads']['parameters']>) => (
       Promise<extractFields<CustomActions['inbox_threads']['build_threads']['returns']>>
@@ -996,6 +1002,7 @@ export class Session extends SessionManager {
     queries.api_keys.get_organization_api_keys = () => this._GET(`/v1${schema.api_keys.customActions.get_organization_api_keys.path}`)
     queries.api_keys.delete_organization_api_key = ({ id }) => this._DELETE(`/v1/organization-api-key/${id}`)
 
+    queries.user_logs.restore_deleted = a => this._POST(`/v1${schema.user_logs.customActions.restore_deleted.path}`, a)
     queries.enduser_orders.get_available_tests = a => this._GET(`/v1${schema.enduser_orders.customActions.get_available_tests.path}`, a)
     queries.enduser_orders.create_lab_order = a => this._POST(`/v1${schema.enduser_orders.customActions.create_lab_order.path}`, a)
     queries.enduser_orders.cancel_order = a => this._POST(`/v1${schema.enduser_orders.customActions.cancel_order.path}`, a)

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

@@ -0,0 +1,541 @@
+require('source-map-support').install();
+
+import { DateTime } from "luxon"
+import { CalendarEvent } from "@tellescope/types-models"
+import { find_conflicting_upcoming_event } from "@tellescope/utilities"
+import { EnduserSession } from "../../sdk"
+import {
+  assert_checks,
+  Check,
+  setup_isolated_tenant,
+  IsolatedSuite,
+} from "../setup_isolated"
+
+const host = process.env.API_URL || 'http://localhost:8080' as const
+
+const RAND = () => Math.random().toString(36).slice(2, 10)
+
+// dontsend- addresses are the provisioning convention for "never actually deliver"; no phone number
+// is set on any enduser here, and every template disables confirmations and carries no reminders,
+// so this suite cannot send a message to anyone.
+const TEST_EMAIL = () => `dontsend-booking-dup-${RAND()}@tellescope.com`
+
+const ONE_DAY_IN_MS = 24 * 60 * 60 * 1000
+
+/**
+ * Covers the per-template `preventBookingWhenUpcomingExists` setting: a patient cannot book a
+ * template while they already have an unresolved upcoming appointment of that same template.
+ *
+ * Provisions its own tenant because it needs host availability, two providers and templates in a
+ * known state — a shared tenant's weeklyAvailabilities and calendar are changed by other suites.
+ *
+ * Two layers:
+ *  - unit checks of the pure predicate (find_conflicting_upcoming_event), which is the rule itself
+ *    and is shared verbatim by the API and the webapp staff warning
+ *  - end-to-end checks through book_appointment as an authenticated enduser, which is what the
+ *    portal and the public booking page both call
+ *
+ * NOT covered here (manual QA): the AI voice-agent path and an EHR-synced event blocking a booking.
+ */
+export const booking_prevent_upcoming_duplicate_checks = async (): Promise<Check[]> => {
+  const checks: Check[] = []
+  const record = (label: string, pass: boolean, detail: string) => checks.push({ label, pass, detail })
+
+  /* ===================== Unit checks: the pure predicate ===================== */
+
+  const TEMPLATE_ID = '507f1f77bcf86cd799439011'
+  const ENDUSER_ID = '507f1f77bcf86cd799439012'
+  const NOW = 1_700_000_000_000
+
+  const baseEvent = {
+    id: 'event-1',
+    startTimeInMS: NOW + ONE_DAY_IN_MS,
+    templateId: TEMPLATE_ID,
+    attendees: [{ id: 'some-user' }, { id: ENDUSER_ID }],
+  }
+  const find = (overrides: object = {}, args: object = {}) => find_conflicting_upcoming_event({
+    events: [{ ...baseEvent, ...overrides }],
+    enduserId: ENDUSER_ID,
+    templateId: TEMPLATE_ID,
+    nowInMS: NOW,
+    ...args,
+  })
+
+  record(
+    'U1: a future unresolved event of the same template conflicts',
+    !!find(),
+    'the base case the setting exists for',
+  )
+  record(
+    'U2: the enduser need not be the FIRST attendee (group events)',
+    !!find({ attendees: [{ id: 'other-enduser' }, { id: 'some-user' }, { id: ENDUSER_ID }] }),
+    'get_enduserId uses first-enduser-attendee; this predicate deliberately does not',
+  )
+  record(
+    'U3: a PAST event never conflicts',
+    !find({ startTimeInMS: NOW - ONE_DAY_IN_MS }),
+    'past appointments never block, resolved or not',
+  )
+  record(
+    'U4: an event for a different template never conflicts',
+    !find({ templateId: 'a-different-template' }),
+    'the restriction is per template',
+  )
+  record(
+    'U5: an event this enduser does not attend never conflicts',
+    !find({ attendees: [{ id: 'someone-else' }] }),
+    "another patient's appointment must not block",
+  )
+  record(
+    'U6: cancelledAt resolves the event',
+    !find({ cancelledAt: new Date(NOW) }),
+    'cancelling frees up rebooking',
+  )
+  record(
+    'U7: noShowedAt resolves the event',
+    !find({ noShowedAt: new Date(NOW) }),
+    'a no-show frees up rebooking',
+  )
+  record(
+    'U8: rescheduledAt resolves the event',
+    !find({ rescheduledAt: new Date(NOW) }),
+    'a rescheduled-away event frees up rebooking',
+  )
+  record(
+    "U9: empty-string timestamps (the `Date | ''` shape) do NOT resolve the event",
+    !!find({ cancelledAt: '' as const, noShowedAt: '' as const, rescheduledAt: '' as const }),
+    "these fields are typed Date | '' — falsiness is what must be tested, not absence",
+  )
+  for (const status of ['Cancelled', 'No-showed', 'Rescheduled']) {
+    record(
+      `U10: an attendeeStatuses entry of '${status}' for THIS enduser resolves the event`,
+      !find({ attendeeStatuses: [{ id: ENDUSER_ID, status, at: new Date(NOW) }] }),
+      "note the exact spelling 'No-showed', which is not 'NoShow'",
+    )
+  }
+  record(
+    "U11: an attendeeStatuses entry of 'Confirmed' does NOT resolve the event",
+    !!find({ attendeeStatuses: [{ id: ENDUSER_ID, status: 'Confirmed', at: new Date(NOW) }] }),
+    'only Cancelled / No-showed / Rescheduled free up rebooking',
+  )
+  record(
+    "U12: another attendee's 'Cancelled' status does NOT resolve it for this enduser",
+    !!find({ attendeeStatuses: [{ id: 'other-enduser', status: 'Cancelled', at: new Date(NOW) }] }),
+    'a group event cancelled for someone else still blocks this patient',
+  )
+  record(
+    'U13: excludeEventId (the event being rescheduled away) does not conflict',
+    !find({}, { excludeEventId: 'event-1' }),
+    'a reschedule must not be blocked by the very event it replaces',
+  )
+  record(
+    'U14: an event on hold (holdUntil) still conflicts',
+    !!find({ holdUntil: new Date(NOW + ONE_DAY_IN_MS) }),
+    'accepted: an abandoned hold blocks rebooking until it expires',
+  )
+  record(
+    'U15: a cancelledGroupAttendees entry for this enduser resolves the event',
+    !find({ cancelledGroupAttendees: [{ id: ENDUSER_ID }] }),
+    'Healthie and the portal cancel a group attendee with ONLY this legacy mirror, leaving them in attendees',
+  )
+  record(
+    "U16: an explicit 'Confirmed' status outranks a cancelledGroupAttendees entry",
+    !!find({
+      attendeeStatuses: [{ id: ENDUSER_ID, status: 'Confirmed', at: new Date(NOW) }],
+      cancelledGroupAttendees: [{ id: ENDUSER_ID }],
+    }),
+    'same precedence as enduser_ids_for_event_wide_completion: an explicit status is authoritative',
+  )
+  record(
+    "U17: another attendee's cancelledGroupAttendees entry does not resolve it for this enduser",
+    !!find({ cancelledGroupAttendees: [{ id: 'other-enduser' }] }),
+    'a group event cancelled for someone else still blocks this patient',
+  )
+  const SAME_SLOT = { startTimeInMS: NOW + ONE_DAY_IN_MS, hostUserId: 'some-user' }
+  record(
+    'U18: the slot being booked right now (same time AND same host) is not a duplicate of itself',
+    !find({ wasSelfScheduled: true }, { excludeSlot: SAME_SLOT }),
+    'keeps a retry / an idempotent voice-agent replay from being refused as a duplicate',
+  )
+  record(
+    'U19: the same time with a DIFFERENT host is still a duplicate',
+    !!find({ wasSelfScheduled: true }, { excludeSlot: { ...SAME_SLOT, hostUserId: 'a-different-host' } }),
+    'excludeSlot must not become a bypass for a genuine second appointment at the same moment',
+  )
+  record(
+    'U20: a NON-self-scheduled event at the same time and host is still a duplicate',
+    !!find({ wasSelfScheduled: false }, { excludeSlot: SAME_SLOT }),
+    'the atomic upsert we defer to matches wasSelfScheduled: true, so it would never catch a '
+      + 'staff-created or EHR-synced event at that instant — excusing it here would let a second one through',
+  )
+
+  /* ===================== End-to-end checks ===================== */
+
+  let tenant: Awaited<ReturnType<typeof setup_isolated_tenant>> | undefined
+
+  try {
+    tenant = await setup_isolated_tenant({
+      name: `BookingDup ${RAND()}`,
+      users: [{ isAdmin: true }, { isAdmin: true }],
+      apiKeys: 0,
+    })
+    const { sdk } = tenant
+    const hostUserId = tenant.users[0].id
+    const otherHostUserId = tenant.users[1].id
+
+    const WEEKLY_AVAILABILITY = [1, 2, 3, 4, 5].map(dayOfWeekStartingSundayIndexedByZero => ({
+      dayOfWeekStartingSundayIndexedByZero,
+      startTimeInMinutes: 9 * 60,
+      endTimeInMinutes: 17 * 60,
+      intervalInMinutes: 60,
+    }))
+    await Promise.all([hostUserId, otherHostUserId].map(id => (
+      sdk.api.users.updateOne(id, {
+        timezone: 'America/New_York',
+        weeklyAvailabilities: WEEKLY_AVAILABILITY,
+      }, { replaceObjectFields: true })
+    )))
+
+    // no reminders, confirmations disabled — this suite must never send anything
+    const templateFields = {
+      durationInMinutes: 60,
+      confirmationEmailDisabled: true,
+      confirmationSMSDisabled: true,
+      reminders: [],
+    }
+    const [restrictedTemplate, unrestrictedTemplate] = await Promise.all([
+      sdk.api.calendar_event_templates.createOne({
+        title: 'Consult', ...templateFields, preventBookingWhenUpcomingExists: true,
+      }),
+      sdk.api.calendar_event_templates.createOne({
+        title: 'Follow-up', ...templateFields, // setting deliberately absent
+      }),
+    ])
+
+    const create_enduser_session = async (fname: string) => {
+      const enduser = await sdk.api.endusers.createOne({ fname, lname: 'Tester', email: TEST_EMAIL() })
+      const { authToken } = await sdk.api.endusers.generate_auth_token({ id: enduser.id })
+      const enduserSDK = new EnduserSession({ host, businessId: tenant!.businessId, authToken })
+      return { enduser, enduserSDK }
+    }
+
+    // A synthetic upcoming appointment, written straight through POST /calendar-event (which is
+    // deliberately NOT blocked server-side — EHR sync and automations write through it too).
+    // dontBlockAvailability + no user attendee keeps it from perturbing the host's open slots.
+    const give_upcoming_event = async (enduserId: string, templateId: string, overrides: Partial<CalendarEvent> = {}) => (
+      sdk.api.calendar_events.createOne({
+        title: 'Consult',
+        startTimeInMS: Date.now() + 3 * ONE_DAY_IN_MS,
+        durationInMinutes: 60,
+        templateId,
+        attendees: [{ type: 'enduser', id: enduserId }],
+        dontBlockAvailability: true,
+        reminders: [],
+        ...overrides,
+      } as any)
+    )
+
+    // Every booking attempt gets its own never-reused slot, so "Someone has already booked this
+    // time" can never be mistaken for the duplicate block we are actually testing. Both hosts share
+    // the 9-17 weekday availability set above: 8 hourly slots a day, walked forwards from a weekday
+    // next week (Tue->Fri stay inside the Mon-Fri availability).
+    const SLOTS_PER_DAY = 8
+    const nowET = DateTime.now().setZone('America/New_York')
+    let bookingStart = nowET.startOf('week').plus({ days: 1, weeks: 1 })
+    if (bookingStart <= nowET) bookingStart = bookingStart.plus({ weeks: 1 })
+
+    let slotCursor = 0
+    const next_slot = () => {
+      const i = slotCursor++
+      return (
+        bookingStart
+        .plus({ days: Math.floor(i / SLOTS_PER_DAY) })
+        .set({ hour: 9 + (i % SLOTS_PER_DAY), minute: 0, second: 0, millisecond: 0 })
+        .toJSDate()
+      )
+    }
+
+    const EXPECTED_REFUSAL = "This appointment can't be booked. Please contact us if you need help scheduling."
+
+    const attempt_booking = async (enduserSDK: EnduserSession, args: object) => {
+      try {
+        const { createdEvent } = await enduserSDK.api.calendar_events.book_appointment({
+          userId: hostUserId,
+          timezone: 'America/New_York',
+          ...args,
+        } as any)
+        return { booked: true as const, event: createdEvent, error: '' }
+      } catch (err: any) {
+        const message = typeof err === 'string' ? err : (err?.message ?? JSON.stringify(err))
+        return { booked: false as const, event: undefined, error: message }
+      }
+    }
+
+    /* --- Core: the block itself --- */
+
+    const { enduser: patA, enduserSDK: patASDK } = await create_enduser_session('PatA')
+
+    const firstBooking = await attempt_booking(patASDK, {
+      calendarEventTemplateId: restrictedTemplate.id,
+      startTime: next_slot(),
+    })
+    record(
+      'E1: the first booking of a restricted template succeeds',
+      firstBooking.booked,
+      `error=${firstBooking.error}`,
+    )
+
+    const secondBooking = await attempt_booking(patASDK, {
+      calendarEventTemplateId: restrictedTemplate.id,
+      startTime: next_slot(),
+    })
+    record(
+      'E2: a second booking of the same template is refused',
+      !secondBooking.booked,
+      `error=${secondBooking.error}`,
+    )
+    record(
+      'E3: the refusal is the generic message, verbatim',
+      secondBooking.error === EXPECTED_REFUSAL,
+      `got ${JSON.stringify(secondBooking.error)}, expected ${JSON.stringify(EXPECTED_REFUSAL)}`,
+    )
+    record(
+      'E4: the refusal leaks no template title, date or host',
+      !['Consult', 'Follow-up', String(hostUserId), String(patA.id)].some(s => secondBooking.error.includes(s)),
+      `the public booking page is unauthenticated, so any detail is an oracle — got ${JSON.stringify(secondBooking.error)}`,
+    )
+
+    const otherHostBooking = await attempt_booking(patASDK, {
+      calendarEventTemplateId: restrictedTemplate.id,
+      startTime: next_slot(),
+      userId: otherHostUserId,
+    })
+    record(
+      'E5: the block is per TEMPLATE, not per provider — the other host is refused too',
+      !otherHostBooking.booked && otherHostBooking.error === EXPECTED_REFUSAL,
+      `booked=${otherHostBooking.booked} error=${otherHostBooking.error}`,
+    )
+
+    // scheduledBy is only a URL query parameter validated as a mongo id — if it exempted the
+    // booking, the block would be bypassable by anyone who could edit the link
+    const scheduledByBooking = await attempt_booking(patASDK, {
+      calendarEventTemplateId: restrictedTemplate.id,
+      startTime: next_slot(),
+      scheduledBy: hostUserId,
+    })
+    record(
+      'E5b: a staff-sent link (scheduledBy) is NOT an exemption',
+      !scheduledByBooking.booked && scheduledByBooking.error === EXPECTED_REFUSAL,
+      `booked=${scheduledByBooking.booked} error=${scheduledByBooking.error}`,
+    )
+
+    const unrestrictedBooking = await attempt_booking(patASDK, {
+      calendarEventTemplateId: unrestrictedTemplate.id,
+      startTime: next_slot(),
+    })
+    record(
+      'E6: a template WITHOUT the setting is unaffected (the default for every org)',
+      unrestrictedBooking.booked,
+      `error=${unrestrictedBooking.error}`,
+    )
+
+    /* --- An unrelated patient is never blocked --- */
+
+    const { enduserSDK: patBSDK } = await create_enduser_session('PatB')
+    const patBBooking = await attempt_booking(patBSDK, {
+      calendarEventTemplateId: restrictedTemplate.id,
+      startTime: next_slot(),
+    })
+    record(
+      "E7: another patient's appointment never blocks",
+      patBBooking.booked,
+      `error=${patBBooking.error}`,
+    )
+
+    /* --- Freeing up the slot: each case gets its own patient, so order cannot matter --- */
+
+    const freeing_case = async (
+      label: string,
+      overrides: (enduserId: string) => Partial<CalendarEvent>,
+      detail: string,
+    ) => {
+      const { enduser, enduserSDK } = await create_enduser_session('Freeing')
+      await give_upcoming_event(enduser.id, restrictedTemplate.id, overrides(enduser.id))
+      const result = await attempt_booking(enduserSDK, {
+        calendarEventTemplateId: restrictedTemplate.id,
+        startTime: next_slot(),
+      })
+      record(label, result.booked, `${detail} — error=${result.error}`)
+    }
+
+    await freeing_case('E8: a cancelled upcoming event frees up rebooking', () => ({ cancelledAt: new Date() }), 'cancelledAt set')
+    await freeing_case('E9: a no-showed upcoming event frees up rebooking', () => ({ noShowedAt: new Date() }), 'noShowedAt set')
+    await freeing_case('E10: a rescheduled-away upcoming event frees up rebooking', () => ({ rescheduledAt: new Date() }), 'rescheduledAt set')
+    await freeing_case(
+      "E11: an attendeeStatuses 'No-showed' entry frees up rebooking",
+      enduserId => ({ attendeeStatuses: [{ id: enduserId, status: 'No-showed', at: new Date() }] }),
+      "per-attendee status, spelled 'No-showed'",
+    )
+
+    /* --- A PAST unresolved event never blocks --- */
+
+    const { enduser: pastPat, enduserSDK: pastPatSDK } = await create_enduser_session('PastPat')
+    await give_upcoming_event(pastPat.id, restrictedTemplate.id, {
+      startTimeInMS: Date.now() - 3 * ONE_DAY_IN_MS, // nobody ever marked it complete
+    })
+    const pastBooking = await attempt_booking(pastPatSDK, {
+      calendarEventTemplateId: restrictedTemplate.id,
+      startTime: next_slot(),
+      userId: otherHostUserId,
+    })
+    record(
+      'E12: a PAST unresolved appointment never blocks',
+      pastBooking.booked,
+      `error=${pastBooking.error}`,
+    )
+
+    /* --- Group event where the patient is not the first attendee --- */
+
+    const { enduser: groupPat, enduserSDK: groupPatSDK } = await create_enduser_session('GroupPat')
+    const { enduser: groupOther } = await create_enduser_session('GroupOther')
+    await give_upcoming_event(groupPat.id, restrictedTemplate.id, {
+      attendees: [
+        { type: 'enduser', id: groupOther.id },
+        { type: 'enduser', id: groupPat.id },
+      ],
+      enduserAttendeeLimit: 5,
+    })
+    const groupBooking = await attempt_booking(groupPatSDK, {
+      calendarEventTemplateId: restrictedTemplate.id,
+      startTime: next_slot(),
+      userId: otherHostUserId,
+    })
+    record(
+      'E13: a group event blocks a patient who is NOT its first attendee',
+      !groupBooking.booked && groupBooking.error === EXPECTED_REFUSAL,
+      `booked=${groupBooking.booked} error=${groupBooking.error}`,
+    )
+
+    /* --- A retried identical booking is the same appointment, not a duplicate --- */
+
+    const { enduserSDK: retrySDK } = await create_enduser_session('RetryPat')
+    const retrySlot = next_slot()
+    const retryArgs = {
+      calendarEventTemplateId: restrictedTemplate.id,
+      startTime: retrySlot,
+      userId: otherHostUserId,
+    }
+    const retryFirst = await attempt_booking(retrySDK, retryArgs)
+    const retrySecond = await attempt_booking(retrySDK, retryArgs)
+    record(
+      'E13b: re-submitting the SAME slot is not refused as a duplicate',
+      retryFirst.booked && retrySecond.error !== EXPECTED_REFUSAL,
+      `first=${retryFirst.booked} secondError=${retrySecond.error} — the duplicate block must not `
+        + 'swallow the idempotent-replay / slot-taken handling for the very booking being retried '
+        + '(the first booking is wasSelfScheduled, which is what excludeSlot is limited to)',
+    )
+
+    /* --- A group cancellation recorded only in cancelledGroupAttendees frees up rebooking --- */
+
+    const { enduser: groupCancelled, enduserSDK: groupCancelledSDK } = await create_enduser_session('GroupCancelled')
+    await give_upcoming_event(groupCancelled.id, restrictedTemplate.id, {
+      attendees: [{ type: 'enduser', id: groupCancelled.id }],
+      cancelledGroupAttendees: [{ at: new Date(), id: groupCancelled.id }],
+      enduserAttendeeLimit: 5,
+    })
+    const groupCancelledBooking = await attempt_booking(groupCancelledSDK, {
+      calendarEventTemplateId: restrictedTemplate.id,
+      startTime: next_slot(),
+      userId: otherHostUserId,
+    })
+    record(
+      'E13c: a cancelledGroupAttendees-only cancellation frees up rebooking',
+      groupCancelledBooking.booked,
+      `Healthie-synced group cancels write only this mirror — error=${groupCancelledBooking.error}`,
+    )
+
+    /* --- Reschedule still works --- */
+
+    const { enduserSDK: reschedSDK } = await create_enduser_session('ReschedPat')
+    const reschedFirst = await attempt_booking(reschedSDK, {
+      calendarEventTemplateId: restrictedTemplate.id,
+      startTime: next_slot(),
+      userId: otherHostUserId,
+    })
+    const rescheduled = reschedFirst.booked
+      ? await attempt_booking(reschedSDK, {
+          calendarEventTemplateId: restrictedTemplate.id,
+          startTime: next_slot(),
+          userId: otherHostUserId,
+          rescheduledCalendarEventId: reschedFirst.event!.id,
+        })
+      : { booked: false as const, error: 'initial booking failed' }
+    record(
+      'E14: rescheduling is not blocked by the event it replaces',
+      rescheduled.booked,
+      `initialBooked=${reschedFirst.booked} error=${rescheduled.error}`,
+    )
+
+    /* --- An unavailable slot cannot be used to probe for an upcoming appointment --- */
+
+    // The public booking page gives a session on an existing patient by email alone, so the refusal
+    // must not be reachable without first holding an open slot: an unavailable slot has to fail the
+    // same way whether or not the patient is already booked.
+    const { enduser: probedBooked, enduserSDK: probedBookedSDK } = await create_enduser_session('ProbedBooked')
+    const { enduserSDK: probedFreeSDK } = await create_enduser_session('ProbedFree')
+    await give_upcoming_event(probedBooked.id, restrictedTemplate.id)
+
+    // Sunday 10:00 ET, outside the hosts' Mon-Fri availability
+    const closedSlot = bookingStart.startOf('week').plus({ days: 6 }).set({ hour: 10, minute: 0, second: 0, millisecond: 0 }).toJSDate()
+    const probeArgs = { calendarEventTemplateId: restrictedTemplate.id, startTime: closedSlot }
+    const [probeBooked, probeFree] = await Promise.all([
+      attempt_booking(probedBookedSDK, probeArgs),
+      attempt_booking(probedFreeSDK, { ...probeArgs, userId: otherHostUserId }),
+    ])
+    const UNAVAILABLE = "This timeslot is no longer available"
+    record(
+      'E15: an unavailable slot fails identically with or without an upcoming duplicate',
+      !probeBooked.booked && !probeFree.booked && probeBooked.error === UNAVAILABLE && probeFree.error === UNAVAILABLE,
+      `booked-patient error=${JSON.stringify(probeBooked.error)}, free-patient error=${JSON.stringify(probeFree.error)}`,
+    )
+
+    // the endpoint deletes a failed booking's placeholder without awaiting it, so give it a moment
+    let leftovers = await sdk.api.calendar_events.getSome({ filter: { startTimeInMS: closedSlot.getTime() } })
+    for (let i = 0; i < 10 && leftovers.length; i++) {
+      await new Promise(r => setTimeout(r, 200))
+      leftovers = await sdk.api.calendar_events.getSome({ filter: { startTimeInMS: closedSlot.getTime() } })
+    }
+    record(
+      'E15b: the probes leave no placeholder event behind',
+      leftovers.length === 0,
+      `found ${leftovers.length} event(s) at the closed slot`,
+    )
+  } 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 booking_prevent_upcoming_duplicate_tests = async () => {
+  assert_checks('Prevent booking when an upcoming duplicate exists', await booking_prevent_upcoming_duplicate_checks())
+}
+
+/** Enrolls this suite in the auto-discovered parallel pool — see run_discovered_isolated_suites. */
+export const ISOLATED_SUITE: IsolatedSuite = { name: 'Prevent booking when an upcoming duplicate exists', run: booking_prevent_upcoming_duplicate_checks }
+
+// Allow running this test file independently
+if (require.main === module) {
+  console.log(`🌐 Using API URL: ${host}`)
+  booking_prevent_upcoming_duplicate_tests()
+    .then(() => {
+      console.log("✅ Prevent-duplicate-booking test suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ Prevent-duplicate-booking test suite failed:", error)
+      process.exit(1)
+    })
+}