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

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

@@ -1,24 +1,56 @@
 require('source-map-support').install();
 
-import { Session } from "../../sdk"
-import {
-  assert,
-  async_test,
-  log_header,
-} from "@tellescope/testing"
-import { setup_tests } from "../setup"
 import { METRIPORT_TITLE } from "@tellescope/constants"
+import {
+  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)
+
 // metriportPushFormResponse journey action (CU-86e2cucba).
 //
 // Fast / no-upload: this exercises validation and the guard branches that reject before any
 // Metriport HTTP call. A real upload needs a Metriport sandbox API key plus a patient already
 // synced to a facility, so the happy path is verified manually (see the task plan).
-export const metriport_push_form_response_tests = async ({ sdk, sdkNonAdmin }: { sdk: Session, sdkNonAdmin: Session }) => {
-  log_header("Metriport Push Form Response Tests")
+//
+// Runs on its own provisioned tenant, which is what makes the no-integration guard reliable: a
+// fresh tenant never holds a Metriport integration, so that assertion always runs. On the shared
+// fixture it was wrapped in `if (!metriportIntegrationExists)` and was silently skipped whenever
+// another suite had left an integration behind — a skip reports green without asserting anything.
+export const metriport_push_form_response_checks = async (): Promise<Check[]> => {
+  const checks: Check[] = []
+  const record = (label: string, pass: boolean, detail: string) => checks.push({ label, pass, detail })
+
+  // The raw value decides the fallback, not JSON.stringify of it — JSON.stringify('') is '""',
+  // which is truthy, so a `|| fallback` on the stringified form could never fire.
+  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)
+  )
+
+  /**
+   * The async_test({ shouldError: true, onError: () => true }) equivalent: a call that RESOLVES is a
+   * failure (async_test treats it the same way), and any rejection passes.
+   */
+  const expect_rejected = async (label: string, fn: () => Promise<any>) => {
+    try {
+      const unexpected = await fn()
+      record(label, false, `resolved instead of rejecting; result=${describe(unexpected)}`)
+    } catch (e: any) {
+      record(label, true, `rejected with ${errorMessage(e)}`)
+    }
+  }
 
+  let tenant: Awaited<ReturnType<typeof setup_isolated_tenant>> | undefined
   let enduserId: string | undefined
   let otherEnduserId: string | undefined
   let formId: string | undefined
@@ -26,6 +58,13 @@ export const metriport_push_form_response_tests = async ({ sdk, sdkNonAdmin }: {
   let createdIntegrationId: string | undefined
 
   try {
+    tenant = await setup_isolated_tenant({
+      name: `Metriport push form response ${RAND()}`,
+      users: [{ isAdmin: true }],
+      apiKeys: 0,
+    })
+    const { sdk } = tenant
+
     const journey = await sdk.api.journeys.createOne({ title: 'Metriport Push Form Response Journey' })
     journeyId = journey.id
 
@@ -48,10 +87,10 @@ export const metriport_push_form_response_tests = async ({ sdk, sdkNonAdmin }: {
       events: [{ type: 'onJourneyStart', info: {} }],
       action: { type: 'metriportPushFormResponse', info: { formId: form.id, integrationTitle: '' } },
     })
-    assert(
-      step.action.type === 'metriportPushFormResponse' && step.action.info.formId === form.id,
-      'metriportPushFormResponse step round-trip failed',
+    record(
       'metriportPushFormResponse step round-trips',
+      step.action.type === 'metriportPushFormResponse' && (step.action.info as any).formId === form.id,
+      `action=${describe(step.action)}`,
     )
 
     // formId is optional — a step with no info at all is valid (uses the journey's form response)
@@ -60,19 +99,19 @@ export const metriport_push_form_response_tests = async ({ sdk, sdkNonAdmin }: {
       events: [{ type: 'onJourneyStart', info: {} }],
       action: { type: 'metriportPushFormResponse', info: {} },
     })
-    assert(
-      contextOnlyStep.action.type === 'metriportPushFormResponse',
-      'metriportPushFormResponse step without info was rejected',
+    record(
       'metriportPushFormResponse info is optional',
+      contextOnlyStep.action.type === 'metriportPushFormResponse',
+      `action=${describe(contextOnlyStep.action)}`,
     )
 
-    await async_test('metriportPushFormResponse with a malformed formId is rejected',
+    await expect_rejected(
+      'metriportPushFormResponse with a malformed formId is rejected',
       () => sdk.api.automation_steps.createOne({
         journeyId: journey.id,
         events: [{ type: 'onJourneyStart', info: {} }],
         action: { type: 'metriportPushFormResponse', info: { formId: 'not-a-mongo-id' } },
       }),
-      { shouldError: true, onError: () => true },
     )
 
     /*************** runtime ***************/
@@ -99,8 +138,10 @@ export const metriport_push_form_response_tests = async ({ sdk, sdkNonAdmin }: {
       return sdk.api.automated_actions.process({ automatedActionId: automatedAction.id })
     }
 
-    // The org may already have a Metriport integration; only the no-integration assertion depends
-    // on it being absent, so check first.
+    // Kept from the shared-fixture version, and now expected never to be true: a freshly provisioned
+    // tenant holds no Metriport integration, so the no-integration assertion below always runs. If
+    // the probe ever does find one, that is a failed check rather than a silent skip — provisioning
+    // would have changed.
     let metriportIntegrationExists = false
     try {
       const existing = await sdk.api.integrations.load_redacted({})
@@ -109,12 +150,12 @@ export const metriport_push_form_response_tests = async ({ sdk, sdkNonAdmin }: {
 
     if (!metriportIntegrationExists) {
       const noIntegrationResult = await processStep()
-      assert(
+      record(
+        'metriportPushFormResponse is wired into automated_actions.process (no integration)',
         !noIntegrationResult.success
           && !noIntegrationResult.unimplemented
           && noIntegrationResult.error === 'Metriport integration not found',
-        `expected 'Metriport integration not found', got: ${JSON.stringify(noIntegrationResult)}`,
-        'metriportPushFormResponse is wired into automated_actions.process (no integration)',
+        `expected 'Metriport integration not found', got: ${describe(noIntegrationResult)}`,
       )
 
       const created = await sdk.api.integrations.createOne({
@@ -125,17 +166,25 @@ export const metriport_push_form_response_tests = async ({ sdk, sdkNonAdmin }: {
         },
       })
       createdIntegrationId = created.id
+    } else {
+      record(
+        'a freshly provisioned tenant holds no Metriport integration',
+        false,
+        'the tenant already had a Metriport integration, so the no-integration assertion could not run'
+        + ' (no placeholder is created on this branch, so the not-synced check below fails too, with'
+        + " a misleading 'Metriport integration not found')",
+      )
     }
 
     // With an integration but a patient that was never synced to a facility, the action fails
     // before any HTTP call to Metriport
     const unsyncedResult = await processStep()
-    assert(
+    record(
+      'metriportPushFormResponse rejects a patient not synced to Metriport',
       !unsyncedResult.success
         && !unsyncedResult.unimplemented
         && /not synced to Metriport/i.test(unsyncedResult.error || ''),
-      `expected a 'Patient is not synced to Metriport' error, got: ${JSON.stringify(unsyncedResult)}`,
-      'metriportPushFormResponse rejects a patient not synced to Metriport',
+      `expected a 'Patient is not synced to Metriport' error, got: ${describe(unsyncedResult)}`,
     )
 
     /*************** cross-patient ownership (CU-86e2cucba security fix) ***************/
@@ -160,26 +209,27 @@ export const metriport_push_form_response_tests = async ({ sdk, sdkNonAdmin }: {
       processAfter: Date.now(),
     })
     const crossPatientResult = await sdk.api.automated_actions.process({ automatedActionId: crossPatientAction.id })
-    assert(
+    record(
+      'metriportPushFormResponse rejects a form response owned by a different patient',
       !crossPatientResult.success
         && !crossPatientResult.unimplemented
         && crossPatientResult.error === 'Form response does not belong to this patient',
-      `expected a cross-patient ownership rejection, got: ${JSON.stringify(crossPatientResult)}`,
-      'metriportPushFormResponse rejects a form response owned by a different patient',
+      `expected a cross-patient ownership rejection, got: ${describe(crossPatientResult)}`,
     )
 
     // the rejection must occur before any Metriport reference is stamped on A's response
     const untouched = await sdk.api.form_responses.getOne(formResponseId)
-    assert(
-      !(untouched as any).references?.find((r: any) => r.type === METRIPORT_TITLE),
-      `patient A's form response was stamped despite a cross-patient rejection: ${JSON.stringify((untouched as any).references)}`,
+    record(
       'metriportPushFormResponse does not stamp a form response on cross-patient rejection',
+      !(untouched as any).references?.find((r: any) => r.type === METRIPORT_TITLE),
+      `references=${describe((untouched as any).references)}`,
     )
 
     /*************** idempotency ***************/
     // form_responses.references is a readonly field, so it can only be stamped server-side (which
     // is what a successful upload does). Attempt the stamp; if the API drops it, skip the check
-    // rather than assert on a state we couldn't set up.
+    // rather than assert on a state we couldn't set up. (This skip is about a readonly schema field,
+    // not about shared-tenant contention, so isolation does not make it unreachable.)
     await sdk.api.form_responses.updateOne(formResponseId, {
       references: [{ type: METRIPORT_TITLE, id: 'test-document-reference-id' }],
     } as any).catch(() => {})
@@ -187,34 +237,44 @@ export const metriport_push_form_response_tests = async ({ sdk, sdkNonAdmin }: {
     const stamped = await sdk.api.form_responses.getOne(formResponseId)
     if ((stamped as any).references?.find((r: any) => r.type === METRIPORT_TITLE)) {
       const idempotentResult = await processStep()
-      assert(
-        idempotentResult.success === true,
-        `expected a no-op success for an already-shared form response, got: ${JSON.stringify(idempotentResult)}`,
+      record(
         'metriportPushFormResponse no-ops for an already-shared form response',
+        idempotentResult.success === true,
+        `expected a no-op success for an already-shared form response, got: ${describe(idempotentResult)}`,
       )
     } else {
       console.log("⏭️  Skipping idempotency check (form_responses.references is readonly over the API)")
     }
   } finally {
-    if (createdIntegrationId) await sdk.api.integrations.deleteOne(createdIntegrationId).catch(console.error)
-    if (journeyId) await sdk.api.journeys.deleteOne(journeyId).catch(console.error)
-    if (formId) await sdk.api.forms.deleteOne(formId).catch(console.error)
-    if (enduserId) await sdk.api.endusers.deleteOne(enduserId).catch(console.error)
-    if (otherEnduserId) await sdk.api.endusers.deleteOne(otherEnduserId).catch(console.error)
+    if (tenant) {
+      const { sdk } = tenant
+      if (createdIntegrationId) await sdk.api.integrations.deleteOne(createdIntegrationId).catch(console.error)
+      if (journeyId) await sdk.api.journeys.deleteOne(journeyId).catch(console.error)
+      if (formId) await sdk.api.forms.deleteOne(formId).catch(console.error)
+      if (enduserId) await sdk.api.endusers.deleteOne(enduserId).catch(console.error)
+      if (otherEnduserId) await sdk.api.endusers.deleteOne(otherEnduserId).catch(console.error)
+      // Teardown BEFORE anything asserts — assert calls process.exit, which would strand this tenant.
+      try { await tenant.teardown() } catch (e) { console.error('teardown failed', e) }
+    }
   }
+
+  return checks
 }
 
-if (require.main === module) {
-  console.log(`Using API URL: ${host}`)
-  const sdk = new Session({ host })
-  const sdkNonAdmin = new Session({ host })
+/** Asserting wrapper, for standalone runs. */
+export const metriport_push_form_response_tests = async () => {
+  assert_checks('Metriport push form response', await metriport_push_form_response_checks())
+}
 
-  const runTests = async () => {
-    await setup_tests(sdk, sdkNonAdmin)
-    await metriport_push_form_response_tests({ sdk, sdkNonAdmin })
-  }
+/** Enrolls this suite in the auto-discovered parallel pool — see run_discovered_isolated_suites. */
+export const ISOLATED_SUITE: IsolatedSuite = {
+  name: 'Metriport push form response',
+  run: metriport_push_form_response_checks,
+}
 
-  runTests()
+if (require.main === module) {
+  console.log(`Using API URL: ${host}`)
+  metriport_push_form_response_tests()
     .then(() => {
       console.log("✅ Metriport push form response test suite completed successfully")
       process.exit(0)

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

@@ -8,11 +8,12 @@ import {
   wait,
 } from "@tellescope/testing"
 import { setup_tests } from "../setup"
+import { FORM_INGESTION_API_KEY_SCOPE } from "@tellescope/types-models"
 
 const host = process.env.API_URL || 'http://localhost:8080' as const
 
 // fields that the admin org-wide list endpoint is allowed to return
-const ALLOWED_FIELDS = ['id', 'creator', 'businessId', 'updatedAt', 'scopes'].sort()
+const ALLOWED_FIELDS = ['id', 'creator', 'businessId', 'updatedAt', 'scopes', 'description'].sort()
 
 export const organization_api_keys_tests = async (
   { sdk, sdkNonAdmin }: { sdk: Session, sdkNonAdmin: Session }
@@ -56,6 +57,9 @@ export const organization_api_keys_tests = async (
     // A key created by the admin...
     const adminKey = await sdk.api.api_keys.createOne({})
     adminKeyIds.push(adminKey.id)
+    // the plaintext secret is returned once, at creation — kept here only to prove that relabelling
+    // a key never rotates or invalidates it (never logged, never asserted on by value)
+    const adminKeySecret = adminKey.key
 
     // ...and a key created by ANOTHER user in the org (the offboarded-employee scenario)
     const otherKey = await otherSdk.api.api_keys.createOne({})
@@ -104,7 +108,7 @@ export const organization_api_keys_tests = async (
     assert(
       offending === undefined,
       `a returned record exposed non-allowlisted fields: ${JSON.stringify(offending)}`,
-      "returned records contain only allowlisted fields (subset of id, creator, businessId, updatedAt, scopes)"
+      "returned records contain only allowlisted fields (subset of id, creator, businessId, updatedAt, scopes, description)"
     )
 
     // =============================================
@@ -116,6 +120,158 @@ export const organization_api_keys_tests = async (
       "all returned keys are scoped to the admin's businessId"
     )
 
+    // =============================================
+    // DESCRIPTION (the only editable field on an api_key)
+    // =============================================
+    // a creator relabels their OWN key through the generic routed update
+    await async_test(
+      "creator sets a description on their own key (generic update)",
+      () => otherSdk.api.api_keys.updateOne(otherKeyId!, { description: 'Billing export script' }),
+      { onResult: (k: any) => k.description === 'Billing export script' },
+    )
+
+    // the admin's org-wide list must surface it — both the Mongo projection AND the explicit
+    // re-map in get_organization_api_keys have to know the field, or it is dropped with no error
+    const withDescription = await sdk.api.api_keys.get_organization_api_keys()
+    assert(
+      withDescription.apiKeys.find(k => k.id === otherKeyId)?.description === 'Billing export script',
+      "org-wide list did not return the description set by its creator",
+      "org-wide list returns the description (projection + explicit re-map)"
+    )
+    // re-run the strict allowlist now that an optional field is actually populated
+    const offendingWithDescription = withDescription.apiKeys
+      .map(k => Object.keys(k).filter(key => !ALLOWED_FIELDS.includes(key)))
+      .find(extra => extra.length > 0)
+    assert(
+      offendingWithDescription === undefined,
+      `a described record exposed non-allowlisted fields: ${JSON.stringify(offendingWithDescription)}`,
+      "records with a description still contain only allowlisted fields"
+    )
+
+    // CREATOR_ONLY_ACCESS still applies to the generic update — this is precisely why the admin
+    // needs a dedicated org-wide action to relabel a key somebody else created
+    await async_test(
+      "non-admin cannot relabel another user's key via the generic update",
+      () => otherSdk.api.api_keys.updateOne(adminKey.id, { description: 'hijacked' }),
+      { shouldError: true, onError: () => true },
+    )
+    await async_test(
+      "admin cannot relabel another user's key via the generic update either (CREATOR_ONLY_ACCESS)",
+      () => sdk.api.api_keys.updateOne(otherKeyId!, { description: 'hijacked' }),
+      { shouldError: true, onError: () => true },
+    )
+    const afterBlockedWrites = await sdk.api.api_keys.get_organization_api_keys()
+    assert(
+      afterBlockedWrites.apiKeys.find(k => k.id === adminKey.id)?.description === undefined
+      && afterBlockedWrites.apiKeys.find(k => k.id === otherKeyId)?.description === 'Billing export script',
+      "a rejected cross-creator relabel still changed a description",
+      "rejected cross-creator relabels left both descriptions untouched"
+    )
+
+    // the dedicated admin action DOES reach another user's key
+    await async_test(
+      "admin update_organization_api_key relabels another user's key",
+      () => sdk.api.api_keys.update_organization_api_key({ id: otherKeyId!, description: 'Relabelled by admin' }),
+      { shouldError: false, onResult: () => true },
+    )
+    const afterAdminRelabel = await sdk.api.api_keys.get_organization_api_keys()
+    assert(
+      afterAdminRelabel.apiKeys.find(k => k.id === otherKeyId)?.description === 'Relabelled by admin',
+      "admin relabel of another user's key did not persist",
+      "admin relabel of another user's key persisted"
+    )
+
+    // clearing back to empty is accepted (description is not a required field)
+    await async_test(
+      "admin can clear a description (empty string)",
+      () => sdk.api.api_keys.update_organization_api_key({ id: otherKeyId!, description: '' }),
+      { shouldError: false, onResult: () => true },
+    )
+    const afterClear = await sdk.api.api_keys.get_organization_api_keys()
+    assert(
+      !afterClear.apiKeys.find(k => k.id === otherKeyId)?.description,
+      "cleared description is still set",
+      "a description can be cleared back to empty"
+    )
+
+    // a cross-org / non-existent id is reported as not found, never as a successful relabel
+    await async_test(
+      "admin update of a non-existent/cross-org key id is rejected, not reported as success",
+      () => sdk.api.api_keys.update_organization_api_key({ id: '000000000000000000000000', description: 'nope' }),
+      { shouldError: true, onError: (e: any) => e.statusCode === 404 || /could not find a record/i.test(e.message || e || '') },
+    )
+    const afterMissingUpdate = await sdk.api.api_keys.get_organization_api_keys()
+    assert(
+      afterMissingUpdate.apiKeys.every(k => k.description !== 'nope'),
+      "a rejected update of an unknown id still wrote a description somewhere",
+      "a rejected update of an unknown id left our org's keys untouched"
+    )
+
+    // =============================================
+    // DESCRIPTION INPUT HANDLING (edge cases from the QA script)
+    // =============================================
+    // over the 1000-character limit: a clear 400, never a silent truncation or a 500
+    await async_test(
+      "an over-long description is rejected with a validation error",
+      () => sdk.api.api_keys.updateOne(adminKey.id, { description: 'a'.repeat(1200) }),
+      { shouldError: true, onError: (e: any) => /exceeds maxLength 1000/i.test(e.message || e || '') },
+    )
+    // punctuation, quotes, emoji and HTML-looking fragments are stored as literal text
+    const literalText = '<b>test</b> "quoted" & \'apostrophe\' — emoji 🎉 <script>alert(1)</script>'
+    await async_test(
+      "punctuation, emoji and HTML-looking text round-trip verbatim",
+      async () => {
+        await sdk.api.api_keys.updateOne(adminKey.id, { description: literalText })
+        return sdk.api.api_keys.getOne(adminKey.id)
+      },
+      { onResult: (k: any) => k.description === literalText },
+    )
+
+    // =============================================
+    // READONLY FIELDS STAY UNWRITABLE THROUGH UPDATE
+    // =============================================
+    // enabling `update` on this model must not open a path to the key material. Assert on resulting
+    // STATE, so this holds whether the API rejects the write or silently drops the readonly fields.
+    // The readonly fields travel WITH a description the request is allowed to write, so the request
+    // cannot be rejected wholesale and still pass: the description must land while they do not.
+    await sdk.api.api_keys.updateOne(
+      adminKey.id,
+      { description: 'tamper probe', hashedKey: 'tampered', scopes: [FORM_INGESTION_API_KEY_SCOPE], creator: otherUser.id } as any,
+    )
+    const afterTamper = await sdk.api.api_keys.getOne(adminKey.id)
+    assert(
+      afterTamper.description === 'tamper probe'
+      && (afterTamper as any).hashedKey !== 'tampered'
+      && !afterTamper.scopes?.length
+      && afterTamper.creator === sdk.userInfo.id,
+      `readonly fields were not stripped from an accepted update: ${JSON.stringify({ description: afterTamper.description, scopes: afterTamper.scopes, creator: afterTamper.creator })}`,
+      "hashedKey, scopes and creator are stripped from an otherwise-valid update"
+    )
+    // a field that is not on the model at all is a hard rejection, not a silent drop
+    await async_test(
+      "an undeclared field is rejected by update validation",
+      () => sdk.api.api_keys.updateOne(adminKey.id, { key: 'tampered' } as any),
+      { shouldError: true, onError: () => true },
+    )
+
+    // whitespace-only input is accepted (the webapp trims it to empty before sending)
+    await async_test(
+      "a whitespace-only description is accepted, not an error",
+      async () => {
+        await sdk.api.api_keys.updateOne(adminKey.id, { description: '   ' })
+        return sdk.api.api_keys.getOne(adminKey.id)
+      },
+      { onResult: (k: any) => typeof k.description === 'string' },
+    )
+
+    // relabelling must never rotate or invalidate a key
+    await sdk.api.api_keys.updateOne(adminKey.id, { description: 'Admin automation key' })
+    await async_test(
+      "a key still authenticates after its description is changed",
+      () => new Session({ host, apiKey: adminKeySecret }).test_authenticated(),
+      { shouldError: false, onResult: () => true },
+    )
+
     // =============================================
     // ADMIN GATING (negative tests)
     // =============================================
@@ -124,11 +280,23 @@ export const organization_api_keys_tests = async (
       () => otherSdk.api.api_keys.get_organization_api_keys(),
       { shouldError: true, onError: (e: any) => e.statusCode === 401 || /admin access only/i.test(e.message || '') }
     )
+    await async_test(
+      "non-admin update_organization_api_key is rejected (401)",
+      () => otherSdk.api.api_keys.update_organization_api_key({ id: adminKey.id, description: 'hijacked' }),
+      { shouldError: true, onError: (e: any) => e.statusCode === 401 || /admin access only/i.test(e.message || '') }
+    )
     await async_test(
       "non-admin delete_organization_api_key is rejected (401)",
       () => otherSdk.api.api_keys.delete_organization_api_key({ id: adminKey.id }),
       { shouldError: true, onError: (e: any) => e.statusCode === 401 || /admin access only/i.test(e.message || '') }
     )
+    // the rejected non-admin relabel must not have landed
+    const afterUpdateGating = await sdk.api.api_keys.get_organization_api_keys()
+    assert(
+      afterUpdateGating.apiKeys.find(k => k.id === adminKey.id)?.description === 'Admin automation key',
+      "rejected non-admin update_organization_api_key still changed the description",
+      "rejected non-admin update left the description intact"
+    )
 
     // confirm the gating did not delete the key
     const afterGating = await sdk.api.api_keys.get_organization_api_keys()