@tellescope/sdk 2.0.0-beta.1 → 2.0.0-beta.3

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

@@ -0,0 +1,491 @@
+require('source-map-support').install();
+
+import axios from 'axios'
+import { ObjectId } from 'bson'
+
+import {
+  assert_checks,
+  Check,
+  IsolatedSuite,
+  setup_isolated_tenant,
+} from "../setup_isolated"
+import { EnduserSession, Session } from "../../sdk"
+
+const host = process.env.API_URL || 'http://localhost:8080' as const
+
+const RAND = () => Math.random().toString(36).slice(2, 10)
+
+/**
+ * ai_conversations.agent_message — the endpoint-level contract.
+ *
+ * Everything in the first two sections runs on a freshly provisioned tenant that has NO credits
+ * and needs no AWS access, because every rule it covers is enforced before a billed call:
+ * transcript shape, tool_use/tool_result pairing, the cache_control budget, the maxTokens cap, the
+ * two conversation-level 400s, and the two credit messages themselves. That ordering is the point
+ * — a client must be able to tell "you sent me a bad transcript" from "you are out of credits",
+ * and the chat app string-matches the credit messages, so they are pinned verbatim here.
+ *
+ * The live-model section runs ONLY when this tenant turns out to have a positive creditCount at
+ * runtime (and therefore a Bedrock-capable API behind it). There is no env var for it: on a normal
+ * local or CI run the organization is provisioned without credits, those checks are skipped, and
+ * the skip is RECORDED as a check so it is visible rather than silently absent.
+ */
+export const ai_conversations_agent_message_checks = async (): Promise<Check[]> => {
+  const checks: Check[] = []
+  const record = (label: string, pass: boolean, detail: string) => checks.push({ label, pass, detail })
+
+  // Branch the fallback on the raw value: JSON.stringify('') is '""', which is truthy, so a
+  // `|| fallback` over the stringified form could never fire and a real failure would print
+  // `error=""` instead of the explanation.
+  const describe = (value: any): string => {
+    if (value === undefined || value === null) return String(value)
+    const stringified = JSON.stringify(value)
+    return stringified === undefined ? String(value) : stringified
+  }
+  const errorMessage = (e: any): string => (
+    typeof e?.message === 'string' && e.message !== '' ? e.message : describe(e)
+  )
+
+  /**
+   * A call that must be REJECTED, with every fragment present in the message. Resolving is a
+   * failure. The predicate is evaluated inside its own try: a throw escaping `run` would abort
+   * every remaining suite in the batch rather than failing this one check.
+   */
+  const rejects = async (label: string, body: object, ...mustContain: string[]) => {
+    let rejection: { e: any }
+    try {
+      const unexpected = await callAgentMessage(body)
+      record(label, false, `resolved instead of rejecting; result=${describe(unexpected)}`)
+      return
+    } catch (e: any) {
+      rejection = { e }
+    }
+    try {
+      const message = errorMessage(rejection.e)
+      record(
+        label,
+        mustContain.every(fragment => message.includes(fragment)),
+        `rejected with "${message}" (expected ${mustContain.map(f => `"${f}"`).join(' + ')})`,
+      )
+    } catch (predicateError: any) {
+      record(label, false, `predicate threw on rejection: ${errorMessage(predicateError)}`)
+    }
+  }
+
+  const roleName = `agent-message-${RAND()}`
+  let tenant: Awaited<ReturnType<typeof setup_isolated_tenant>> | undefined
+  let sdk: Session
+  let callAgentMessage: (body: object) => Promise<any> = async () => { throw new Error('not initialized') }
+
+  try {
+    tenant = await setup_isolated_tenant({
+      name: `agent_message ${roleName}`,
+      users: [{ isAdmin: true }, { roles: ['Non-Admin'] }],
+      apiKeys: 1,
+    })
+    sdk = tenant.sdk
+    callAgentMessage = (body: object) => sdk.api.ai_conversations.agent_message(body as any)
+
+    const organization: any = await sdk.api.organizations.getOne(tenant.businessId)
+    const creditCount: number | undefined = (
+      typeof organization?.creditCount === 'number' ? organization.creditCount : undefined
+    )
+    const hasCredits = (creditCount ?? 0) > 0
+
+    const text = (t: string) => ({ type: 'text', text: t })
+    const ask = [{ role: 'user', content: [text('hello')] }]
+
+    /* =================== transcript shape (no credits, no AWS) =================== */
+
+    await rejects('an empty transcript is rejected', { messages: [] }, 'messages is empty')
+    await rejects(
+      'a transcript ending on the assistant is rejected',
+      { messages: [...ask, { role: 'assistant', content: [text('hi')] }] },
+      'last message must be from the user',
+    )
+    await rejects(
+      'a message with an empty content array is rejected',
+      { messages: [{ role: 'user', content: [] }] },
+      'empty content array',
+    )
+    await rejects(
+      'an unsupported content-block type is rejected by name',
+      { messages: [{ role: 'user', content: [{ type: 'image', source: { type: 'url', url: 'https://x/y.png' } }] }] },
+      'image', 'not supported',
+    )
+    await rejects(
+      'a text block over the per-block limit is rejected',
+      { messages: [{ role: 'user', content: [text('x'.repeat(100001))] }] },
+      '100000',
+    )
+
+    /* ----------------------- tool_use / tool_result pairing ----------------------- */
+
+    const TOOLS = [{ name: 'lookup', description: 'Look something up', input_schema: { type: 'object' } }]
+
+    await rejects(
+      'an unanswered tool_use is rejected, naming the id',
+      {
+        messages: [
+          ...ask,
+          { role: 'assistant', content: [{ type: 'tool_use', id: 'toolu_qa3', name: 'lookup', input: { q: 'x' } }] },
+          { role: 'user', content: [text('never mind')] },
+        ],
+        tools: TOOLS,
+      },
+      'toolu_qa3', 'no matching tool_result',
+    )
+    await rejects(
+      'an orphan tool_result is rejected, naming the id',
+      {
+        messages: [
+          ...ask,
+          { role: 'assistant', content: [text('sure')] },
+          { role: 'user', content: [{ type: 'tool_result', tool_use_id: 'toolu_qa4', content: 'done' }] },
+        ],
+        tools: TOOLS,
+      },
+      'toolu_qa4', 'does not answer a tool_use',
+    )
+    await rejects(
+      'a transcript using tools with no tools array is rejected',
+      {
+        messages: [
+          ...ask,
+          { role: 'assistant', content: [{ type: 'tool_use', id: 'toolu_qa7', name: 'lookup', input: {} }] },
+          { role: 'user', content: [{ type: 'tool_result', tool_use_id: 'toolu_qa7', content: 'done' }] },
+        ],
+      },
+      'tools array is required',
+    )
+    await rejects(
+      'tool_choice naming an unknown tool is rejected',
+      { messages: ask, tools: TOOLS, tool_choice: { type: 'tool', name: 'not_in_list' } },
+      'unknown tool', 'not_in_list',
+    )
+
+    /* ----------------------------- caps and budgets ----------------------------- */
+
+    await rejects(
+      'five cache_control markers are rejected',
+      {
+        messages: ask,
+        system: Array.from({ length: 5 }, (_, i) => ({
+          type: 'text', text: `block ${i}`, cache_control: { type: 'ephemeral' },
+        })),
+      },
+      '5 cache_control markers', 'at most 4',
+    )
+    await rejects('maxTokens above the cap is rejected', { messages: ask, maxTokens: 70000 }, '70000', '64000')
+    await rejects('an unknown model name is rejected', { messages: ask, model: 'Claude Opus 9' }, 'model')
+
+    /* =============== the credit gate: the two strings the chat app matches ===============
+       Pinned verbatim. A reworded message silently breaks the client's "buy more credits" branch.
+       On a credited tenant the equivalent assertion is that these do NOT appear. */
+
+    {
+      const label = 'the credit gate answers with the exact string the chat client matches'
+      let outcome: { resolved: true, value: any } | { resolved: false, error: any }
+      try {
+        outcome = { resolved: true, value: await callAgentMessage({ messages: ask, maxTokens: 16 }) }
+      } catch (e: any) {
+        outcome = { resolved: false, error: e }
+      }
+
+      if (hasCredits) {
+        const message = outcome.resolved ? '' : errorMessage(outcome.error)
+        record(
+          label,
+          !message.includes('Organization has not set up credits') && !message.includes('credits left'),
+          `tenant has ${creditCount} credits; ${outcome.resolved ? 'the call was allowed through' : `rejected with "${message}"`}`,
+        )
+      } else {
+        const message = outcome.resolved ? '' : errorMessage(outcome.error)
+        record(
+          label,
+          creditCount === undefined
+            ? message === 'Organization has not set up credits'
+            : message === `Organization has ${creditCount} credits left`,
+          `creditCount=${describe(creditCount)}; ${outcome.resolved ? 'resolved unexpectedly' : `rejected with "${message}"`}`,
+        )
+      }
+    }
+
+    /* ============ conversation-level 400s — checked BEFORE the credit gate ============
+       These are properties of the request, not of the balance, so they must be reachable on an
+       uncredited tenant; if they ever moved behind the gate, these two checks would start
+       reporting the credits message instead. */
+
+    const conversation = await sdk.api.ai_conversations.createOne({
+      type: 'Agent Message Test',
+      modelName: 'Claude Sonnet 5.5',
+      messages: [],
+    } as any)
+
+    await rejects(
+      'a model conflicting with the conversation is rejected before the credit gate',
+      { messages: ask, conversationId: conversation.id, model: 'Claude Opus 5' },
+      'conflicts with this conversation', 'Omit model',
+    )
+
+    const fullConversation = await sdk.api.ai_conversations.createOne({
+      type: 'Agent Message Test',
+      modelName: 'Claude Sonnet 5.5',
+      messages: Array.from({ length: 999 }, (_, i) => ({
+        role: i % 2 === 0 ? 'user' : 'assistant', text: `m${i}`, timestamp: new Date(), tokens: 0,
+      })),
+    } as any)
+    await rejects(
+      'a conversation at the stored-message cap is rejected with an actionable message',
+      { messages: ask, conversationId: fullConversation.id },
+      '1000-message limit', 'Start a new conversation record',
+    )
+    await rejects(
+      'an unknown conversationId is a 404, not a crash',
+      { messages: ask, conversationId: new ObjectId().toHexString() },
+      'not found',
+    )
+
+    /* ================= accepted shapes: they must pass shape validation =================
+       On an uncredited tenant "accepted" means the call reaches the credit gate — the specific
+       shape errors above are what these would produce if the validator rejected them. */
+
+    // Fragments that only this endpoint's own shape rules produce. The check below is "the body
+    // was NOT rejected for its shape" — stated this way rather than as `gated || hasCredits`,
+    // which on a credited tenant would make every one of these checks unfailable, precisely where
+    // the live QA run needs them to bite.
+    const SHAPE_REJECTION_FRAGMENTS = [
+      'Error parsing field', 'messages[', 'system[', 'tools[', 'tool_choice',
+      'messages is empty', 'last message must be', 'empty content array', 'is not supported',
+      'exceeds the', 'cache_control markers', 'tools array is required', 'unknown tool',
+      'conflicts with this conversation', 'positive whole number',
+    ]
+
+    const acceptedShape = async (label: string, body: object) => {
+      try {
+        await callAgentMessage(body)
+        record(label, true, 'accepted (reached the model)')
+      } catch (e: any) {
+        const message = errorMessage(e)
+        const shapeRejection = SHAPE_REJECTION_FRAGMENTS.some(fragment => message.includes(fragment))
+        const gated = message.includes('credits')
+        record(
+          label,
+          !shapeRejection,
+          shapeRejection ? `REJECTED FOR ITS SHAPE: "${message}"`
+          : gated ? 'accepted (reached the credit gate)'
+          : `accepted (rejected downstream of validation with "${message}")`,
+        )
+      }
+    }
+
+    await acceptedShape('two consecutive user messages are accepted', {
+      messages: [{ role: 'user', content: [text('part one')] }, { role: 'user', content: [text('part two')] }],
+      maxTokens: 16,
+    })
+    await acceptedShape('a plain-string system is accepted', {
+      messages: ask, system: 'You are a helpful assistant', maxTokens: 16,
+    })
+    await acceptedShape('a single cached system text block is accepted', {
+      messages: ask,
+      system: [{ type: 'text', text: 'You are a helpful assistant', cache_control: { type: 'ephemeral' } }],
+      maxTokens: 16,
+    })
+    await acceptedShape('maxTokens exactly at the cap is accepted', {
+      messages: ask, maxTokens: 64000,
+    })
+    await acceptedShape('a correctly paired tool round with thinking blocks is accepted', {
+      messages: [
+        ...ask,
+        {
+          role: 'assistant',
+          content: [
+            { type: 'thinking', thinking: 'I should look this up', signature: 'sig-abc' },
+            { type: 'tool_use', id: 'toolu_ok', name: 'lookup', input: { q: 'x' } },
+          ],
+        },
+        { role: 'user', content: [{ type: 'tool_result', tool_use_id: 'toolu_ok', content: 'the answer' }] },
+      ],
+      tools: TOOLS,
+      maxTokens: 16,
+    })
+
+    /* ========================== streaming: the pre-stream contract ==========================
+       A client must be able to check status and content-type BEFORE it starts parsing SSE. An
+       invalid body with stream: true therefore has to come back as an ordinary JSON 400, not as
+       an event stream carrying an error event — the headers are only flushed once the Bedrock
+       call has been accepted. */
+
+    {
+      const label = 'stream: true with an invalid body answers JSON 400, not an event stream'
+      const response = await axios.request({
+        method: 'post',
+        url: `${host}/v1/ai-conversations/agent-message`,
+        data: { messages: [], stream: true },
+        headers: { Authorization: `Bearer ${tenant.users[0].authToken}` },
+        validateStatus: () => true,
+      })
+      const contentType = String(response.headers['content-type'] || '')
+      record(
+        label,
+        response.status === 400
+        && contentType.includes('application/json')
+        && !contentType.includes('text/event-stream'),
+        `status=${response.status} content-type="${contentType}" body=${describe(response.data)}`,
+      )
+    }
+
+    /* ============================== API-key sessions ==============================
+       An API key must behave exactly like the equivalent user session — same gate, same message. */
+
+    {
+      const label = 'an API-key session behaves like the equivalent user session'
+      const apiKeySDK = new Session({ host, apiKey: tenant.apiKeys[0] })
+      let message = ''
+      let resolved = false
+      try {
+        await apiKeySDK.api.ai_conversations.agent_message({ messages: [] } as any)
+        resolved = true
+      } catch (e: any) {
+        message = errorMessage(e)
+      }
+      record(
+        label,
+        !resolved && message.includes('messages is empty'),
+        resolved ? 'resolved instead of rejecting' : `rejected with "${message}"`,
+      )
+    }
+
+    /* ================================ enduser sessions ================================
+       ai_conversations is provider-only. A patient session must be refused by the handler's first
+       line, with the same message send_message uses. */
+
+    {
+      const enduserEmail = `agent-message-${RAND()}@example.com`
+      const enduserPassword = `Agent-${RAND()}-Password1!`
+      const enduser = await sdk.api.endusers.createOne({ email: enduserEmail, fname: 'Agent', lname: 'Message' })
+      await sdk.api.endusers.set_password({ id: enduser.id, password: enduserPassword })
+
+      const enduserSession = new EnduserSession({ host, businessId: tenant.businessId })
+      await enduserSession.authenticate(enduserEmail, enduserPassword)
+
+      const asEnduser = (path: string) => axios.request({
+        method: 'post',
+        url: `${host}/v1${path}`,
+        data: path.endsWith('agent-message') ? { messages: ask } : { message: 'hi', type: 'Test' },
+        headers: { Authorization: `Bearer ${enduserSession.authToken}` },
+        validateStatus: () => true,
+      })
+
+      // ai_conversations declares no enduserActions, so addEndpoint's access middleware refuses a
+      // patient session with 401 BEFORE the handler runs — the handler's own
+      // "End users cannot send messages" 403 is defence in depth behind it, never the observed
+      // response. That is pre-existing behaviour, asserted here against send_message in the same
+      // breath so the two endpoints can never diverge: whatever a patient gets from one, they get
+      // from the other.
+      const agent = await asEnduser('/ai-conversations/agent-message')
+      const legacy = await asEnduser('/ai-conversations/send-message')
+      // The 401 is pinned, not just the parity: parity alone would stay green if BOTH endpoints
+      // regressed to the same wrong code. 401 is the discriminator proving the refusal came from
+      // the access middleware (ai_conversations declares no enduserActions) rather than from some
+      // later, weaker check.
+      record(
+        'an enduser session is refused with 401 by the access middleware, as send_message is',
+        agent.status === 401 && legacy.status === 401,
+        `agent-message → ${agent.status} ${describe(agent.data)};`
+        + ` send-message → ${legacy.status} ${describe(legacy.data)}`,
+      )
+    }
+
+    /* ================================ live model ================================
+       Runs only on a tenant that actually has credits (and therefore a Bedrock-capable API). */
+
+    if (!hasCredits) {
+      record(
+        'live-model checks',
+        true,
+        `SKIPPED — this tenant's creditCount is ${describe(creditCount)}.`
+        + ` QA steps 14-24 (live model, streaming, interruption) remain manual.`,
+      )
+    } else {
+      const label = 'a simple transcript returns a reply, a conversationId and a priced usage block'
+      let live: any
+      let liveError = ''
+      try {
+        live = await callAgentMessage({ messages: ask, maxTokens: 64 })
+      } catch (e: any) {
+        liveError = errorMessage(e)
+      }
+
+      const usage = live?.reply?.usage
+      record(
+        label,
+        !!live?.conversationId
+        && live?.reply?.role === 'assistant'
+        && Array.isArray(live?.reply?.content)
+        && typeof usage?.input_tokens === 'number'
+        && typeof usage?.output_tokens === 'number'
+        && typeof usage?.cache_creation_input_tokens === 'number'
+        && typeof usage?.cache_read_input_tokens === 'number'
+        && typeof usage?.credits_charged === 'number',
+        live ? `reply=${describe({ stop_reason: live?.reply?.stop_reason, usage })}` : `failed with "${liveError}"`,
+      )
+
+      if (live?.conversationId) {
+        const stored: any = await sdk.api.ai_conversations.getOne(live.conversationId)
+        const entries = (stored?.messages || []).slice(-2)
+        const assistantEntry = entries[1]
+        record(
+          'the turn is recorded as a completed, rated user/assistant pair',
+          entries.length === 2
+          && entries[0]?.role === 'user' && assistantEntry?.role === 'assistant'
+          && assistantEntry?.status === 'completed'
+          && !!assistantEntry?.turnId
+          && assistantEntry?.toolRound === 0
+          && !!assistantEntry?.ratedAt
+          && typeof assistantEntry?.creditsCharged === 'number',
+          describe(entries.map((e: any) => ({
+            role: e?.role, status: e?.status, toolRound: e?.toolRound, creditsCharged: e?.creditsCharged,
+          }))),
+        )
+        record(
+          'no thinking text is stored on the ledger entry',
+          (assistantEntry?.content || []).every((b: any) => b?.type !== 'thinking' && b?.type !== 'redacted_thinking'),
+          describe((assistantEntry?.content || []).map((b: any) => b?.type)),
+        )
+      }
+    }
+  } 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. */
+export const ai_conversations_agent_message_tests = async () => {
+  assert_checks('ai_conversations.agent_message', await ai_conversations_agent_message_checks())
+}
+
+/** Enrolls this suite in the auto-discovered parallel pool — see run_discovered_isolated_suites. */
+export const ISOLATED_SUITE: IsolatedSuite = {
+  name: 'ai_conversations.agent_message',
+  run: ai_conversations_agent_message_checks,
+}
+
+// Allow running this test file independently
+if (require.main === module) {
+  console.log(`🌐 Using API URL: ${host}`)
+  ai_conversations_agent_message_tests()
+    .then(() => {
+      console.log("✅ ai_conversations.agent_message test suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ ai_conversations.agent_message test suite failed:", error)
+      process.exit(1)
+    })
+}

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

@@ -2,15 +2,31 @@ require('source-map-support').install();
 
 import axios from "axios"
 
-import { Session } from "../../sdk"
-import { log_header, async_test } from "@tellescope/testing"
-import { setup_tests } from "../setup"
+import {
+  assert_checks,
+  Check,
+  setup_isolated_tenant,
+  IsolatedSuite,
+} from "../setup_isolated"
 
 const host = process.env.API_URL || 'http://localhost:8080'
 
+const RAND = () => Math.random().toString(36).slice(2, 10)
+
 const ONE_DAY_IN_SECONDS = 86400
 const EVENT_DAYS_OUT = 120 // under the old expiry (event lead time + 4 weeks) this token lived ~148 days
 
+/**
+ * A meeting link minted for an event far in the future must still expire within 24h.
+ *
+ * This suite provisions its own throwaway tenant, so it enrolls in the auto-discovered parallel pool
+ * instead of running sequentially against the shared fixture. It never calls `sdk.reset_db()`, which
+ * clears global state shared with other concurrently running suites.
+ *
+ * The bound stays `0 < lifetime <= 86400` rather than an exact equality: pinning the exact value would
+ * couple this test to DEFAULT_ENDUSER_LINK_EXPIRATION_SECONDS, which is not what is under test.
+ */
+
 // Decode a JWT payload WITHOUT verifying it — the signing key is server-side only, and the only
 // thing under test is the lifetime the server stamped on the token.
 const decode_jwt_payload = (token: string) => {
@@ -42,50 +58,93 @@ const resolve_redirect_token = async (link: string) => {
   return token
 }
 
-export const appointment_link_expiration_tests = async ({ sdk } : { sdk: Session, sdkNonAdmin: Session }) => {
-  log_header("Appointment Link Expiration")
+export const appointment_link_expiration_checks = async (): Promise<Check[]> => {
+  const checks: Check[] = []
+  const record = (label: string, pass: boolean, detail: string) => checks.push({ label, pass, detail })
 
-  const enduser = await sdk.api.endusers.createOne({
-    email: `appointment-link-expiration-${Date.now()}@tellescope.com`,
-  })
-  const event = await sdk.api.calendar_events.createOne({
-    title: 'Appointment Link Expiration Test',
-    durationInMinutes: 30,
-    startTimeInMS: Date.now() + EVENT_DAYS_OUT * ONE_DAY_IN_SECONDS * 1000,
-    enableVideoCall: true,
-    attendees: [{ type: 'enduser', id: enduser.id }],
-  })
+  let tenant: Awaited<ReturnType<typeof setup_isolated_tenant>> | undefined
+  let enduserId = ''
+  let eventId = ''
 
   try {
-    const { link } = await sdk.api.calendar_events.generate_meeting_link({
-      eventId: event.id,
-      enduserId: enduser.id,
+    // A provisioned tenant already carries a future subscriptionExpiresAt, so generate_meeting_link's
+    // requiresSubscription needs no organization edit here.
+    tenant = await setup_isolated_tenant({
+      name: `ApptLinkExpiration ${RAND()}`,
+      users: [{ isAdmin: true }],
+      apiKeys: 0,
     })
-    const { iat, exp } = decode_jwt_payload(await resolve_redirect_token(link))
-    const lifetimeInSeconds = exp - iat
+    const { sdk } = tenant
+
+    const enduser = await sdk.api.endusers.createOne({
+      // `dontsend` prefix AND the @tellescope.com domain are both required for outbound suppression
+      email: `dontsend-appointment-link-expiration-${RAND()}@tellescope.com`,
+    })
+    enduserId = enduser.id
+
+    const event = await sdk.api.calendar_events.createOne({
+      title: 'Appointment Link Expiration Test',
+      durationInMinutes: 30,
+      startTimeInMS: Date.now() + EVENT_DAYS_OUT * ONE_DAY_IN_SECONDS * 1000,
+      enableVideoCall: true,
+      attendees: [{ type: 'enduser', id: enduser.id }],
+    })
+    eventId = event.id
+
+    // Never throw out of the suite: a failure to mint or decode the link is a FAILED check, so the
+    // other concurrently running suites still get to tear their tenants down.
+    let lifetimeInSeconds: number | undefined
+    let error = ''
+    try {
+      const { link } = await sdk.api.calendar_events.generate_meeting_link({
+        eventId: event.id,
+        enduserId: enduser.id,
+      })
+      const { iat, exp } = decode_jwt_payload(await resolve_redirect_token(link))
+      lifetimeInSeconds = exp - iat
+    } catch (err: any) {
+      error = err?.message ?? String(err)
+    }
 
-    await async_test(
-      `meeting link token for an event ${EVENT_DAYS_OUT} days out expires within 24h`,
-      async () => lifetimeInSeconds,
-      { onResult: (lifetime: number) => lifetime > 0 && lifetime <= ONE_DAY_IN_SECONDS },
+    record(
+      `A: meeting link token for an event ${EVENT_DAYS_OUT} days out expires within 24h`,
+      lifetimeInSeconds !== undefined
+        && lifetimeInSeconds > 0
+        && lifetimeInSeconds <= ONE_DAY_IN_SECONDS,
+      // branch on the raw value, never on JSON.stringify of it: JSON.stringify('') is '""', which is
+      // truthy, so a `${JSON.stringify(x) || 'fallback'}` fallback can never be reached
+      lifetimeInSeconds !== undefined
+        ? `lifetime=${lifetimeInSeconds}s (expected 0 < lifetime <= ${ONE_DAY_IN_SECONDS})`
+        : `no lifetime decoded; error=${error ? JSON.stringify(error) : '(none thrown — nothing produced a lifetime)'}`,
     )
   } finally {
-    await sdk.api.calendar_events.deleteOne(event.id).catch(console.error)
-    await sdk.api.endusers.deleteOne(enduser.id).catch(console.error)
+    // Teardown BEFORE anything asserts — assert calls process.exit, which would strand this tenant.
+    if (tenant) {
+      const { sdk } = tenant
+      if (eventId) { await sdk.api.calendar_events.deleteOne(eventId).catch(console.error) }
+      if (enduserId) { await sdk.api.endusers.deleteOne(enduserId).catch(console.error) }
+      try { await tenant.teardown() } catch (e) { console.error('teardown failed', e) }
+    }
   }
+
+  return checks
 }
 
-// Allow running this test file independently
-if (require.main === module) {
-  const sdk = new Session({ host })
-  const sdkNonAdmin = new Session({ host })
+/** Asserting wrapper, for standalone runs. */
+export const appointment_link_expiration_tests = async () => {
+  assert_checks('Appointment link expiration', await appointment_link_expiration_checks())
+}
 
-  const runTests = async () => {
-    await setup_tests(sdk, sdkNonAdmin)
-    await appointment_link_expiration_tests({ sdk, sdkNonAdmin })
-  }
+/** Enrolls this suite in the auto-discovered parallel pool — see run_discovered_isolated_suites. */
+export const ISOLATED_SUITE: IsolatedSuite = {
+  name: 'Appointment link expiration',
+  run: appointment_link_expiration_checks,
+}
 
-  runTests()
+// Allow running this test file independently
+if (require.main === module) {
+  console.log(`🌐 Using API URL: ${host}`)
+  appointment_link_expiration_tests()
     .then(() => {
       console.log("✅ Appointment link expiration test suite completed successfully")
       process.exit(0)