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

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

@@ -0,0 +1,227 @@
+require('source-map-support').install();
+
+import { EnduserSession } from "../../sdk"
+import {
+  assert_checks,
+  Check,
+  setup_isolated_tenant,
+  IsolatedSuite,
+} from "../setup_isolated"
+import { authenticate_enduser_via_token } from "../setup"
+
+const host = process.env.API_URL || 'http://localhost:8080' as const
+
+const RAND = () => Math.random().toString(36).slice(2, 10)
+
+/** @tellescope/utilities' decodeJWT uses window.atob and returns null under node, which would make
+ *  the deny-list check below fail for the wrong reason. Decode the payload with Buffer instead. */
+const decode_jwt_payload = (jwt: string): Record<string, any> => (
+  JSON.parse(Buffer.from(jwt.split('.')[1], 'base64').toString('utf8'))
+)
+
+/**
+ * Coverage for `User.preferences`, the generic bag for frontend-only per-user settings
+ * (first key: `silenceNotificationPopups`).
+ *
+ * It shares its validator with `User.portalSettings` (`userPreferencesValidator` aliases
+ * `userPortalSettingsValidator`), so the validator bounds are re-asserted here rather than
+ * assumed: the alias is exactly the kind of thing a later edit splits apart.
+ *
+ * The two cases `user_portal_settings.test.ts` cannot supply, and the reason this suite exists:
+ *   - `preferences` carries `redactions: ['enduser']`, so an enduser reading that user must NOT
+ *     see it — the opposite of `portalSettings`, which is deliberately un-redacted. The check
+ *     asserts both on the same record, so "enduser cannot read the user at all" cannot pass it.
+ *   - `preferences` is deny-listed out of the JWT in `login_user`, while still reaching the
+ *     client on the refresh-session payload (that is what lets the webapp toggle take effect
+ *     without a reload).
+ *
+ * It also pins the write shape the webapp uses: `updateOne` WITHOUT `replaceObjectFields`, which
+ * must merge into the bag. Writing with `replaceObjectFields` would drop every other key, and a
+ * second key is coming in T2.
+ *
+ * Provisions its own throwaway tenant so the enduser it authenticates and the user records it
+ * mutates are nobody else's.
+ */
+export const user_preferences_checks = async (): Promise<Check[]> => {
+  const checks: Check[] = []
+  const record = (label: string, pass: boolean, detail: string) => checks.push({ label, pass, detail })
+
+  // async_test/handleAnyError call process.exit on failure, which would strand the tenant.
+  // Record the outcome instead, mirroring programs.test.ts.
+  const expect_rejected = async (label: string, write: () => Promise<any>) => {
+    try {
+      await write()
+      record(label, false, 'write was accepted, but the validator should have rejected it')
+    } catch (err) {
+      record(label, true, `rejected: ${(err as any)?.message ?? err}`)
+    }
+  }
+
+  let tenant: Awaited<ReturnType<typeof setup_isolated_tenant>> | undefined
+
+  try {
+    tenant = await setup_isolated_tenant({
+      name: `UserPreferences ${RAND()}`,
+      users: [{ isAdmin: true }],
+      apiKeys: 0,
+    })
+    const { sdk, businessId } = tenant
+
+    const testUser = await sdk.api.users.createOne({
+      email: `user_preferences_${RAND()}@test.tellescope.com`,
+    })
+
+    /* ===================== validator bounds ===================== */
+
+    await sdk.api.users.updateOne(testUser.id, {
+      preferences: { silenceNotificationPopups: true, theme: 'dark', dismissed: false },
+    })
+    const mixed = (await sdk.api.users.getOne(testUser.id)).preferences
+    record(
+      'A: string and boolean values round-trip as their real types',
+      mixed?.silenceNotificationPopups === true
+      && typeof mixed?.silenceNotificationPopups === 'boolean'
+      && mixed?.dismissed === false
+      && typeof mixed?.dismissed === 'boolean'
+      && mixed?.theme === 'dark'
+      && typeof mixed?.theme === 'string',
+      `preferences=${JSON.stringify(mixed)}`,
+    )
+
+    // The write the webapp makes: one key, no replaceObjectFields, must not clear the rest.
+    await sdk.api.users.updateOne(testUser.id, { preferences: { silenceNotificationPopups: false } })
+    const merged = (await sdk.api.users.getOne(testUser.id)).preferences
+    record(
+      'B: a single-key write without replaceObjectFields merges, leaving other keys intact',
+      merged?.silenceNotificationPopups === false
+      && merged?.theme === 'dark'
+      && merged?.dismissed === false,
+      `preferences=${JSON.stringify(merged)}`,
+    )
+
+    await expect_rejected(
+      'C: a value string over 250 chars is rejected',
+      () => sdk.api.users.updateOne(testUser.id, { preferences: { tooLong: 'a'.repeat(251) } }),
+    )
+    await expect_rejected(
+      'D: a key over 250 chars is rejected',
+      () => sdk.api.users.updateOne(testUser.id, { preferences: { ['a'.repeat(251)]: 'x' } }),
+    )
+    await expect_rejected(
+      'E: a nested object value is rejected',
+      () => sdk.api.users.updateOne(testUser.id, { preferences: { k: { nested: 1 } as any } }),
+    )
+    await expect_rejected(
+      'F: an array value is rejected',
+      () => sdk.api.users.updateOne(testUser.id, { preferences: { k: [1, 2] as any } }),
+    )
+    await expect_rejected(
+      'G: a number value is rejected',
+      () => sdk.api.users.updateOne(testUser.id, { preferences: { k: 1 as any } }),
+    )
+
+    // the bag survived every rejected write
+    const afterRejections = (await sdk.api.users.getOne(testUser.id)).preferences
+    record(
+      'H: no rejected write mutated the stored bag',
+      afterRejections?.theme === 'dark'
+      && afterRejections?.silenceNotificationPopups === false
+      && Object.keys(afterRejections ?? {}).length === 3,
+      `preferences=${JSON.stringify(afterRejections)}`,
+    )
+
+    /* ===================== enduser redaction ===================== */
+
+    // portalSettings is deliberately un-redacted, so reading it on the same record in the same
+    // request proves the enduser CAN see this user, and that preferences is specifically redacted.
+    await sdk.api.users.updateOne(testUser.id, {
+      preferences: { silenceNotificationPopups: true },
+      portalSettings: { showAvatar: true },
+    })
+
+    const enduser = await sdk.api.endusers.createOne({
+      email: `user_preferences_enduser_${RAND()}@test.tellescope.com`,
+    })
+    const enduserSDK = new EnduserSession({ host, businessId })
+    await authenticate_enduser_via_token(sdk, enduserSDK, { id: enduser.id })
+
+    const asEnduser = await enduserSDK.api.users.getOne(testUser.id)
+    record(
+      'I: an enduser reading that user does NOT see preferences, while portalSettings is still visible',
+      asEnduser.preferences === undefined && asEnduser.portalSettings?.showAvatar === true,
+      `preferences=${JSON.stringify(asEnduser.preferences)},`
+      + ` portalSettings=${JSON.stringify(asEnduser.portalSettings)}`,
+    )
+
+    const asEnduserList = (await enduserSDK.api.users.getSome({ filter: { email: testUser.email } }))
+      .filter(u => u.id === testUser.id)
+    record(
+      'J: the same redaction applies on a list read, not only getOne',
+      asEnduserList.length === 1 && asEnduserList[0].preferences === undefined,
+      `records=${JSON.stringify(asEnduserList.map(u => ({ id: u.id, preferences: u.preferences })))}`,
+    )
+
+    // /v1/bulk-actions/read is mounted with noAccessPermissions and takes an includeFields list that
+    // only ADDS to the projection — the least obvious way a new field could reach a patient.
+    const bulk = await (enduserSDK as any).POST(
+      '/v1/bulk-actions/read',
+      { load: [{ model: 'users', options: { includeFields: ['preferences'], filter: { _id: testUser.id } } }] },
+      true,
+    )
+    const bulkUsers: any[] = (bulk?.results?.[0]?.records ?? []).filter((u: any) => u.id === testUser.id)
+    record(
+      'K: the bulk-read route redacts preferences too, even when it is asked for by name',
+      bulkUsers.length === 1 && bulkUsers[0].preferences === undefined,
+      `records=${JSON.stringify(bulkUsers.map(u => ({ id: u.id, preferences: u.preferences })))}`,
+    )
+
+    await enduserSDK.api.endusers.logout().catch(() => {})
+
+    /* ===================== kept out of the JWT ===================== */
+
+    // on the admin's own record, so refresh_session reloads it
+    await sdk.api.users.updateOne(sdk.userInfo.id, { preferences: { silenceNotificationPopups: true } })
+    const { user: refreshed, authToken } = await sdk.refresh_session()
+
+    record(
+      'L: preferences reaches the client on the refresh-session payload (no reload needed)',
+      (refreshed as any)?.preferences?.silenceNotificationPopups === true,
+      `user.preferences=${JSON.stringify((refreshed as any)?.preferences)}`,
+    )
+
+    const decoded = decode_jwt_payload(authToken)
+    record(
+      'M: preferences is deny-listed out of the JWT, so no backend code can read it from the session',
+      // the id/type guard keeps this from passing merely because the payload failed to decode
+      decoded.id === sdk.userInfo.id && decoded.type === 'user' && decoded.preferences === undefined,
+      `jwt keys=${JSON.stringify(Object.keys(decoded).sort())}`,
+    )
+  } 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 user_preferences_tests = async () => {
+  assert_checks('User preferences', await user_preferences_checks())
+}
+
+/** Enrolls this suite in the auto-discovered parallel pool — see run_discovered_isolated_suites. */
+export const ISOLATED_SUITE: IsolatedSuite = { name: 'User preferences', run: user_preferences_checks }
+
+// Allow running this test file independently
+if (require.main === module) {
+  console.log(`🌐 Using API URL: ${host}`)
+  user_preferences_tests()
+    .then(() => {
+      console.log("✅ User preferences test suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ User preferences test suite failed:", error)
+      process.exit(1)
+    })
+}

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

@@ -6,16 +6,18 @@ import crypto from "crypto"
 import http from "http"
 
 import { Session } from "../../sdk"
+import { wait } from "@tellescope/testing"
 import {
-  assert,
-  async_test,
-  log_header,
-  wait,
-} from "@tellescope/testing"
-import { setup_tests } from "../setup"
+  assert_checks,
+  Check,
+  IsolatedSuite,
+  setup_isolated_tenant,
+} from "../setup_isolated"
 
 const host = process.env.API_URL || 'http://localhost:8080' as const
 
+const RAND = () => Math.random().toString(36).slice(2, 10)
+
 const TEST_SECRET = "this is a test secret for verifying integrity of web hooks"
 const sha256 = (s: string) => crypto.createHash('sha256').update(s).digest('hex')
 
@@ -53,9 +55,20 @@ const wait_for_failure_count = async (sdk: Session, expected: number) => {
   return count
 }
 
-// Main test function that can be called independently
-export const webhook_error_handling_tests = async ({ sdk, sdkNonAdmin } : { sdk: Session, sdkNonAdmin: Session }) => {
-  log_header("Webhook Error Handling Tests")
+/**
+ * Webhook delivery error handling: what is written to webhook_logs, and how the webhook config's
+ * deliveryFailureCount moves, for an unresolvable host, an HTTP 400, an HTTP 500 and a success.
+ *
+ * Provisions its own throwaway tenant: both observables are org-wide singletons. There is one
+ * webhook configuration per organization, so configuring one on the shared fixture overwrote
+ * whatever was there and left the row behind, and deliveryFailureCount is a counter on that single
+ * row that any concurrent suite's failed delivery also increments. webhook_logs is likewise read
+ * business-wide (the log is found by URL among the 50 most recent), so another suite's traffic can
+ * push the log under test out of the window.
+ */
+export const webhook_error_handling_checks = async (): Promise<Check[]> => {
+  const checks: Check[] = []
+  const record = (label: string, pass: boolean, detail: string) => checks.push({ label, pass, detail })
 
   // local receiver: error paths for failure scenarios, a healthy path that verifies integrity
   const app = express()
@@ -77,17 +90,27 @@ export const webhook_error_handling_tests = async ({ sdk, sdkNonAdmin } : { sdk:
   })
   const receiverBase = `http://127.0.0.1:${(server.address() as any).port}`
 
-  const enduserIds: string[] = []
-  const trigger_delivery = async (label: string) => {
-    const enduser = await sdk.api.endusers.createOne({ email: `webhook-error-${label}-${Date.now()}@tellescope.com` })
-    enduserIds.push(enduser.id)
-  }
+  let tenant: Awaited<ReturnType<typeof setup_isolated_tenant>> | undefined
 
   try {
-    await async_test(
+    tenant = await setup_isolated_tenant({
+      name: `Webhook error handling ${RAND()}`,
+      users: [{ isAdmin: true }],
+      apiKeys: 0,
+    })
+    const { sdk } = tenant
+
+    const trigger_delivery = async (label: string) => {
+      await sdk.api.endusers.createOne({ email: `webhook-error-${label}-${Date.now()}@tellescope.com` })
+    }
+
+    const configureError = await sdk.api.webhooks.configure({ url: ENOTFOUND_URL, secret: TEST_SECRET })
+      .then(() => null)
+      .catch((e: any) => e)
+    record(
       'configure webhook',
-      () => sdk.api.webhooks.configure({ url: ENOTFOUND_URL, secret: TEST_SECRET }),
-      { shouldError: false, onResult: () => true },
+      configureError === null,
+      configureError === null ? 'configure resolved' : `configure threw: ${configureError?.message ?? String(configureError)}`,
     )
     await sdk.api.webhooks.update({ subscriptionUpdates: { endusers: { create: true, update: false, delete: false } } })
 
@@ -96,39 +119,58 @@ export const webhook_error_handling_tests = async ({ sdk, sdkNonAdmin } : { sdk:
     // Scenario 1: ENOTFOUND — no HTTP response at all
     await trigger_delivery('enotfound')
     const enotfoundLog = await find_log_for_url(sdk, ENOTFOUND_URL)
-    assert(!!enotfoundLog, 'no webhook_logs entry for ENOTFOUND delivery', 'ENOTFOUND failure logged to webhook_logs')
-    assert(
+    record(
+      'ENOTFOUND failure logged to webhook_logs',
+      !!enotfoundLog,
+      enotfoundLog ? `log id=${enotfoundLog.id}` : 'no webhook_logs entry for ENOTFOUND delivery',
+    )
+    record(
+      'ENOTFOUND log has error message as response',
       typeof enotfoundLog?.response === 'string' && enotfoundLog.response.length > 0,
-      `expected string error message response, got: ${JSON.stringify(enotfoundLog?.response)}`,
-      'ENOTFOUND log has error message as response'
+      `response=${JSON.stringify(enotfoundLog?.response ?? null)}`,
+    )
+    record(
+      'ENOTFOUND log has no responseCode',
+      enotfoundLog?.responseCode === undefined,
+      `responseCode=${JSON.stringify(enotfoundLog?.responseCode ?? null)}`,
     )
-    assert(enotfoundLog?.responseCode === undefined, 'unexpected responseCode for ENOTFOUND', 'ENOTFOUND log has no responseCode')
-    assert(
-      await wait_for_failure_count(sdk, initialCount + 1) === initialCount + 1,
-      'deliveryFailureCount not incremented after ENOTFOUND',
-      'deliveryFailureCount incremented after ENOTFOUND'
+    const afterEnotfound = await wait_for_failure_count(sdk, initialCount + 1)
+    record(
+      'deliveryFailureCount incremented after ENOTFOUND',
+      afterEnotfound === initialCount + 1,
+      `deliveryFailureCount=${afterEnotfound} (want ${initialCount + 1})`,
     )
 
     // Scenario 2a: HTTP 400 from the receiver
     await sdk.api.webhooks.update({ url: `${receiverBase}/fail-400` })
     await trigger_delivery('http400')
     const log400 = await find_log_for_url(sdk, `${receiverBase}/fail-400`)
-    assert(log400?.responseCode === 400, `expected responseCode 400, got ${log400?.responseCode}`, 'HTTP 400 responseCode recorded')
-    assert(
-      await wait_for_failure_count(sdk, initialCount + 2) === initialCount + 2,
-      'deliveryFailureCount not incremented after HTTP 400',
-      'deliveryFailureCount incremented after HTTP 400'
+    record(
+      'HTTP 400 responseCode recorded',
+      log400?.responseCode === 400,
+      `responseCode=${JSON.stringify(log400?.responseCode ?? null)} (want 400)`,
+    )
+    const after400 = await wait_for_failure_count(sdk, initialCount + 2)
+    record(
+      'deliveryFailureCount incremented after HTTP 400',
+      after400 === initialCount + 2,
+      `deliveryFailureCount=${after400} (want ${initialCount + 2})`,
     )
 
     // Scenario 2b: HTTP 500 from the receiver
     await sdk.api.webhooks.update({ url: `${receiverBase}/fail-500` })
     await trigger_delivery('http500')
     const log500 = await find_log_for_url(sdk, `${receiverBase}/fail-500`)
-    assert(log500?.responseCode === 500, `expected responseCode 500, got ${log500?.responseCode}`, 'HTTP 500 responseCode recorded')
-    assert(
-      await wait_for_failure_count(sdk, initialCount + 3) === initialCount + 3,
-      'deliveryFailureCount not incremented after HTTP 500',
-      'deliveryFailureCount incremented after HTTP 500'
+    record(
+      'HTTP 500 responseCode recorded',
+      log500?.responseCode === 500,
+      `responseCode=${JSON.stringify(log500?.responseCode ?? null)} (want 500)`,
+    )
+    const after500 = await wait_for_failure_count(sdk, initialCount + 3)
+    record(
+      'deliveryFailureCount incremented after HTTP 500',
+      after500 === initialCount + 3,
+      `deliveryFailureCount=${after500} (want ${initialCount + 3})`,
     )
 
     // Scenario 3 (timeout): skipped — WEBHOOK_TIMEOUT_MS is a constant (15s), not env-overridable,
@@ -139,46 +181,65 @@ export const webhook_error_handling_tests = async ({ sdk, sdkNonAdmin } : { sdk:
     await sdk.api.webhooks.update({ url: `${receiverBase}/success` })
     await trigger_delivery('success')
     const successLog = await find_log_for_url(sdk, `${receiverBase}/success`)
-    assert(successLog?.responseCode === 200, `expected responseCode 200, got ${successLog?.responseCode}`, 'success responseCode recorded')
-    assert(successIntegrityVerified, 'integrity check failed on success delivery', 'success delivery integrity verified')
+    record(
+      'success responseCode recorded',
+      successLog?.responseCode === 200,
+      `responseCode=${JSON.stringify(successLog?.responseCode ?? null)} (want 200)`,
+    )
+    record(
+      'success delivery integrity verified',
+      successIntegrityVerified,
+      successIntegrityVerified ? 'sha256(ids + timestamp + secret) matched' : 'integrity check failed on success delivery',
+    )
     await wait(undefined, 1000) // allow any (erroneous) counter update to land before checking
-    assert(
-      await get_failure_count(sdk) === initialCount + 3,
-      'deliveryFailureCount changed on successful delivery',
-      'deliveryFailureCount untouched on success'
+    const afterSuccess = await get_failure_count(sdk)
+    record(
+      'deliveryFailureCount untouched on success',
+      afterSuccess === initialCount + 3,
+      `deliveryFailureCount=${afterSuccess} (want ${initialCount + 3})`,
     )
 
     // deliveryFailureCount is server-managed: not settable through the public update endpoint
     const configs = await sdk.api.webhooks.getSome() as Array<any>
     const webhookId = configs[0]?.id
     await sdk.api.webhooks.updateOne(webhookId, { deliveryFailureCount: 9999 } as any).catch(() => {}) // may reject (readonly)
-    assert(
-      await get_failure_count(sdk) === initialCount + 3,
-      'customer was able to overwrite deliveryFailureCount',
-      'deliveryFailureCount not customer-settable'
+    const afterOverwrite = await get_failure_count(sdk)
+    record(
+      'deliveryFailureCount not customer-settable',
+      afterOverwrite === initialCount + 3,
+      `deliveryFailureCount=${afterOverwrite} (want ${initialCount + 3})`,
     )
   } finally {
-    // stop deliveries for subsequent tests and shut down the local receiver
-    await sdk.api.webhooks.update({ subscriptionUpdates: { endusers: { create: false, update: false, delete: false } } }).catch(() => {})
-    server.close()
-    for (const id of enduserIds) {
-      try { await sdk.api.endusers.deleteOne(id) } catch {}
+    // stop deliveries and shut down the local receiver BEFORE the tenant goes away, so no delivery
+    // is in flight against a closed socket while teardown runs
+    if (tenant) {
+      await tenant.sdk.api.webhooks.update({
+        subscriptionUpdates: { endusers: { create: false, update: false, delete: false } },
+      }).catch(() => {})
     }
+    server.close()
+    // 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 webhook_error_handling_tests = async () => {
+  assert_checks('Webhook error handling', await webhook_error_handling_checks())
+}
+
+/** Enrolls this suite in the auto-discovered parallel pool — see run_discovered_isolated_suites. */
+export const ISOLATED_SUITE: IsolatedSuite = {
+  name: 'Webhook error handling',
+  run: webhook_error_handling_checks,
 }
 
 // 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 webhook_error_handling_tests({ sdk, sdkNonAdmin })
-  }
-
-  runTests()
+  webhook_error_handling_tests()
     .then(() => {
       console.log("✅ Webhook error handling test suite completed successfully")
       process.exit(0)