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

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

@@ -0,0 +1,632 @@
+require('source-map-support').install();
+
+import { EnduserSession, Session } from "../../sdk"
+import {
+  assert_checks,
+  Check,
+  setup_isolated_tenant,
+  IsolatedSuite,
+} from "../setup_isolated"
+import { Form, FormField } from "@tellescope/types-client"
+
+const host = process.env.API_URL || 'http://localhost:8080' as const
+
+const RAND = () => Math.random().toString(36).slice(2, 10)
+
+/**
+ * Coverage for `settings.endusers.caseInsensitiveMatching` — the per-org opt-in that makes public
+ * form intake match an existing contact when only the CAPITALIZATION of fname/lname differs.
+ *
+ * Two matchers are gated by the setting and both are exercised here:
+ *   - `session_for_public_form` (api/v1/api.ts), the intake screen
+ *   - `resolveAutoMergeBeforeSubmission` (api/modules/auto_merge.ts), for autoMergeOnSubmission forms
+ *
+ * Fixture warning: `nameValidator` applies `first_letter_capitalized`, so "john" is already stored and
+ * submitted as "John" and a "john"/"John" fixture would pass with the setting OFF, proving nothing.
+ * Every case here differs AFTER the first letter ("MCDONALD" vs "Mcdonald").
+ *
+ * `setup_isolated` rather than `setup_tests` because these checks flip an ORGANIZATION setting, which
+ * on the shared fixture org would change behavior under every concurrently running suite. It also
+ * asserts on "how many contacts match this name", which needs a tenant nobody else writes to.
+ *
+ * Runs standalone or as part of the main suite:
+ *   npm run test:modular -- api_tests/public_form_case_insensitive_match
+ */
+
+/** Builds a public form with the intake questions the matchers read.
+ *  `intakePhone: 'optional'` so `session_for_public_form` does not reject a submission with no phone
+ *  — the endpoint requires a phone number unless the form configures one. */
+const createPublicForm = async (sdk: Session, { autoMergeOnSubmission = false } = {}) => {
+  const form = await sdk.api.forms.createOne({
+    title: `Case Insensitive Match ${RAND()}`,
+    allowPublicURL: true,
+    intakePhone: 'optional',
+    autoMergeOnSubmission,
+  })
+
+  // sequential: each field's previousFields references the one before it
+  const fnameField = await sdk.api.form_fields.createOne({
+    formId: form.id, title: 'First Name', type: 'string', intakeField: 'fname',
+    previousFields: [{ type: 'root', info: {} }],
+  })
+  const lnameField = await sdk.api.form_fields.createOne({
+    formId: form.id, title: 'Last Name', type: 'string', intakeField: 'lname',
+    previousFields: [{ type: 'after', info: { fieldId: fnameField.id } }],
+  })
+  const dobField = await sdk.api.form_fields.createOne({
+    formId: form.id, title: 'Date of Birth', type: 'dateString', intakeField: 'dateOfBirth',
+    previousFields: [{ type: 'after', info: { fieldId: lnameField.id } }],
+  })
+  const emailField = await sdk.api.form_fields.createOne({
+    formId: form.id, title: 'Email', type: 'email', intakeField: 'email',
+    previousFields: [{ type: 'after', info: { fieldId: dobField.id } }],
+  })
+  const phoneField = await sdk.api.form_fields.createOne({
+    formId: form.id, title: 'Phone', type: 'phone', intakeField: 'phone',
+    previousFields: [{ type: 'after', info: { fieldId: emailField.id } }],
+  })
+
+  return { form, fields: [fnameField, lnameField, dobField, emailField, phoneField] }
+}
+
+/** Drives the intake screen exactly as a public visitor would, returning the enduser the session was
+ *  minted for. This is the `session_for_public_form` matcher under test. */
+const intakeSession = async (
+  form: Form,
+  values: { fname?: string, lname?: string, dateOfBirth?: string, email?: string },
+) => {
+  const enduserSDK = new EnduserSession({ host, businessId: form.businessId })
+  const { enduserId, accessCode, authToken } = await enduserSDK.api.form_responses.session_for_public_form({
+    formId: form.id,
+    businessId: form.businessId,
+    ...values,
+  })
+  return { enduserId, accessCode, authedSDK: new EnduserSession({ host, businessId: form.businessId, authToken }) }
+}
+
+/** The intake screen alone, which is the matcher under test. */
+const intake = async (
+  form: Form,
+  values: { fname?: string, lname?: string, dateOfBirth?: string, email?: string },
+) => (await intakeSession(form, values)).enduserId
+
+/** Intake followed by a real submission, so the intake-field write onto the matched contact runs. */
+const intakeAndSubmit = async (
+  form: Form,
+  fields: FormField[],
+  values: { fname: string, lname: string, dateOfBirth: string },
+) => {
+  const { enduserId, accessCode, authedSDK } = await intakeSession(form, values)
+  const byIntake = (intakeField: string) => fields.find(f => f.intakeField === intakeField)!
+  await authedSDK.api.form_responses.submit_form_response({
+    accessCode,
+    responses: [
+      { fieldId: byIntake('fname').id, fieldTitle: 'First Name', answer: { type: 'string', value: values.fname } },
+      { fieldId: byIntake('lname').id, fieldTitle: 'Last Name', answer: { type: 'string', value: values.lname } },
+      { fieldId: byIntake('dateOfBirth').id, fieldTitle: 'Date of Birth', answer: { type: 'dateString', value: values.dateOfBirth } },
+    ],
+  })
+  return enduserId
+}
+
+/** Drives an auto-merge submission: a `skipMatch` session (which always inserts a fresh contact),
+ *  then a submission whose intake answers are what `resolveAutoMergeBeforeSubmission` matches on. */
+const submitWithSkipMatch = async (
+  form: Form,
+  fields: FormField[],
+  values: { fname: string, lname: string, dateOfBirth: string },
+) => {
+  const enduserSDK = new EnduserSession({ host, businessId: form.businessId })
+  const { authToken, accessCode, enduserId } = await enduserSDK.api.form_responses.session_for_public_form({
+    formId: form.id,
+    businessId: form.businessId,
+    skipMatch: true,
+  })
+
+  const authedSDK = new EnduserSession({ host, businessId: form.businessId, authToken })
+
+  const byIntake = (intakeField: string) => fields.find(f => f.intakeField === intakeField)!
+  await authedSDK.api.form_responses.submit_form_response({
+    accessCode,
+    responses: [
+      { fieldId: byIntake('fname').id, fieldTitle: 'First Name', answer: { type: 'string', value: values.fname } },
+      { fieldId: byIntake('lname').id, fieldTitle: 'Last Name', answer: { type: 'string', value: values.lname } },
+      { fieldId: byIntake('dateOfBirth').id, fieldTitle: 'Date of Birth', answer: { type: 'dateString', value: values.dateOfBirth } },
+    ],
+  })
+
+  return enduserId
+}
+
+const enduserExists = async (sdk: Session, enduserId: string) => {
+  try {
+    await sdk.api.endusers.getOne(enduserId)
+    return true
+  } catch {
+    return false
+  }
+}
+
+export const public_form_case_insensitive_match_checks = async (): Promise<Check[]> => {
+  const checks: Check[] = []
+  const record = (label: string, pass: boolean, detail: string) => checks.push({ label, pass, detail })
+
+  let tenant: Awaited<ReturnType<typeof setup_isolated_tenant>> | undefined
+
+  try {
+    tenant = await setup_isolated_tenant({
+      name: `PublicFormCaseInsensitive ${RAND()}`,
+      users: [{ isAdmin: true }],
+      apiKeys: 0,
+    })
+    const { sdk, businessId } = tenant
+
+    // Only writes when the value actually changes. The generic update route throttles identical
+    // updates to the same record (3 per 30s, keyed on the serialized body), so re-asserting the same
+    // toggle between sections would fail the run with a 429 rather than a check.
+    let caseInsensitiveState: boolean | undefined
+    const setCaseInsensitive = async (on: boolean) => {
+      if (caseInsensitiveState === on) return
+      await sdk.api.organizations.updateOne(businessId, {
+        settings: { endusers: { caseInsensitiveMatching: on } },
+      })
+      caseInsensitiveState = on
+    }
+
+    /* ============ 1. setting OFF: a capitalization variant creates a second contact ============ */
+    {
+      await setCaseInsensitive(false)
+      const { form, fields } = await createPublicForm(sdk)
+      const DOB = '1990-01-02'
+
+      // stored "MCDONALD" — nameValidator only capitalizes the FIRST letter, so this survives as-is
+      const stored = await sdk.api.endusers.createOne({ fname: 'John', lname: 'MCDONALD', dateOfBirth: DOB })
+      record(
+        'fixture: a non-first-letter capitalization variant is stored verbatim',
+        stored.lname === 'MCDONALD',
+        `stored lname=${JSON.stringify(stored.lname)} (if this is not MCDONALD every other check is vacuous)`,
+      )
+
+      const matchedId = await intake(form, { fname: 'John', lname: 'Mcdonald', dateOfBirth: DOB })
+      record(
+        'setting OFF: "Mcdonald" does NOT match stored "MCDONALD" (unchanged behavior)',
+        matchedId !== stored.id,
+        `intake resolved to ${matchedId}, stored contact is ${stored.id}`,
+      )
+
+      // control for the check above: an exact match still matches with the setting off
+      const exactId = await intake(form, { fname: 'John', lname: 'MCDONALD', dateOfBirth: DOB })
+      record(
+        'setting OFF: an exactly-matching name still matches (control)',
+        exactId === stored.id,
+        `intake resolved to ${exactId}, expected ${stored.id}`,
+      )
+
+      // The capitalization guard in save_enduser_updates_for_form_response must be INERT for an
+      // organization that has not opted in: a case-only name difference submitted against a matched
+      // contact still writes through, exactly as before this change. Matched by email so the
+      // submitted last name is free to differ from the stored one.
+      const OFF_EMAIL = `dontsend-off-${RAND()}@tellescope.com`
+      const offContact = await sdk.api.endusers.createOne({ fname: 'Off', lname: 'MCDONALD', email: OFF_EMAIL })
+      const offSession = await intakeSession(form, { email: OFF_EMAIL })
+      const offField = (intakeField: string) => fields.find(f => f.intakeField === intakeField)!
+      await offSession.authedSDK.api.form_responses.submit_form_response({
+        accessCode: offSession.accessCode,
+        responses: [
+          { fieldId: offField('fname').id, fieldTitle: 'First Name', answer: { type: 'string', value: 'Off' } },
+          { fieldId: offField('lname').id, fieldTitle: 'Last Name', answer: { type: 'string', value: 'Mcdonald' } },
+        ],
+      })
+      const offAfter = await sdk.api.endusers.getOne(offContact.id)
+      record(
+        'setting OFF: a case-only name change from intake still writes through (guard is inert)',
+        offSession.enduserId === offContact.id && offAfter.lname === 'Mcdonald',
+        `intake resolved to ${offSession.enduserId} (expected ${offContact.id}); stored lname is ${JSON.stringify(offAfter.lname)}, expected "Mcdonald"`,
+      )
+    }
+
+    /* ============ 2. setting ON: the variant matches, and does not rewrite the name ============ */
+    {
+      await setCaseInsensitive(true)
+      const { form, fields } = await createPublicForm(sdk)
+      const DOB = '1991-02-03'
+      const stored = await sdk.api.endusers.createOne({ fname: 'Jane', lname: 'MCDONALD', dateOfBirth: DOB })
+
+      const matchedId = await intake(form, { fname: 'Jane', lname: 'Mcdonald', dateOfBirth: DOB })
+      record(
+        'setting ON: "Mcdonald" matches stored "MCDONALD"',
+        matchedId === stored.id,
+        `intake resolved to ${matchedId}, expected ${stored.id}`,
+      )
+
+      const afterIntake = await sdk.api.endusers.getOne(stored.id)
+      record(
+        'setting ON: the intake screen does not rewrite a matched contact\'s capitalization',
+        afterIntake.lname === 'MCDONALD',
+        `stored lname is now ${JSON.stringify(afterIntake.lname)}, must still be "MCDONALD"`,
+      )
+
+      // the submission itself writes intake answers onto the matched contact — that write must not
+      // rewrite the stored capitalization either
+      const submittedId = await intakeAndSubmit(form, fields, { fname: 'Jane', lname: 'Mcdonald', dateOfBirth: DOB })
+      const afterSubmit = await sdk.api.endusers.getOne(stored.id)
+      record(
+        'setting ON: SUBMITTING the form does not rewrite a matched contact\'s capitalization',
+        submittedId === stored.id && afterSubmit.lname === 'MCDONALD',
+        `submission resolved to ${submittedId} (expected ${stored.id}); stored lname is now ${JSON.stringify(afterSubmit.lname)}, must still be "MCDONALD"`,
+      )
+
+      // QA step 9: the submitted response must land on the matched contact's record, not just
+      // resolve to its id
+      const storedResponses = await sdk.api.form_responses.getSome({ filter: { enduserId: stored.id } })
+      record(
+        'setting ON: the submitted response is attached to the matched contact',
+        storedResponses.some(r => r.formId === form.id && !!r.submittedAt),
+        `form_responses on ${stored.id}: ${JSON.stringify(storedResponses.map(r => ({ formId: r.formId, submitted: !!r.submittedAt })))}`,
+      )
+
+      // QA step 19 / PHI: email and phone are authentication channels (password reset, OTP
+      // delivery). The auth-field lock already blocks intake answers from repointing them on a
+      // matched contact, but the case-insensitive setting creates a NEW way to reach a pre-existing
+      // patient, so the lock has to be re-proven in that state — the existing
+      // public_endpoint_auth_field_lock suite only exercises it with the setting off.
+      const LOCK_DOB = '1991-02-04'
+      const LOCK_EMAIL = `dontsend-lock-${RAND()}@tellescope.com`
+      const lockContact = await sdk.api.endusers.createOne({
+        fname: 'Lock', lname: 'MCDONALD', dateOfBirth: LOCK_DOB, email: LOCK_EMAIL, phone: '+15555550123',
+      })
+      const lockSession = await intakeSession(form, { fname: 'Lock', lname: 'Mcdonald', dateOfBirth: LOCK_DOB })
+      const lockField = (intakeField: string) => fields.find(f => f.intakeField === intakeField)!
+      await lockSession.authedSDK.api.form_responses.submit_form_response({
+        accessCode: lockSession.accessCode,
+        responses: [
+          { fieldId: lockField('fname').id, fieldTitle: 'First Name', answer: { type: 'string', value: 'Lock' } },
+          { fieldId: lockField('lname').id, fieldTitle: 'Last Name', answer: { type: 'string', value: 'Mcdonald' } },
+          { fieldId: lockField('email').id, fieldTitle: 'Email', answer: { type: 'email', value: `attacker-${RAND()}@example.com` } },
+          { fieldId: lockField('phone').id, fieldTitle: 'Phone', answer: { type: 'phone', value: '+15555559999' } },
+        ],
+      })
+      const lockAfter = await sdk.api.endusers.getOne(lockContact.id)
+      record(
+        'setting ON: a case-insensitively matched contact keeps its email and phone (auth-field lock holds)',
+        lockSession.enduserId === lockContact.id
+          && lockAfter.email === LOCK_EMAIL
+          && lockAfter.phone === '+15555550123',
+        `intake resolved to ${lockSession.enduserId} (expected ${lockContact.id});`
+        + ` email=${JSON.stringify(lockAfter.email)} (expected ${JSON.stringify(LOCK_EMAIL)}),`
+        + ` phone=${JSON.stringify(lockAfter.phone)} (expected "+15555550123")`,
+      )
+
+      // Counterweight: the guard must suppress ONLY a capitalization-only difference, never a real
+      // name correction. Matched here by EMAIL (so the submitted last name is free to differ), then
+      // submitted with a genuinely different spelling, which must still be written through.
+      const RENAME_EMAIL = `dontsend-rename-${RAND()}@tellescope.com`
+      const renameTarget = await sdk.api.endusers.createOne({ fname: 'Rename', lname: 'Smith', email: RENAME_EMAIL })
+      const renameSession = await intakeSession(form, { email: RENAME_EMAIL })
+      const byIntake = (intakeField: string) => fields.find(f => f.intakeField === intakeField)!
+      await renameSession.authedSDK.api.form_responses.submit_form_response({
+        accessCode: renameSession.accessCode,
+        responses: [
+          { fieldId: byIntake('fname').id, fieldTitle: 'First Name', answer: { type: 'string', value: 'Rename' } },
+          { fieldId: byIntake('lname').id, fieldTitle: 'Last Name', answer: { type: 'string', value: 'Smyth' } },
+        ],
+      })
+      const renamed = await sdk.api.endusers.getOne(renameTarget.id)
+      record(
+        'setting ON: a GENUINE name change from intake is still written through (control)',
+        renameSession.enduserId === renameTarget.id && renamed.lname === 'Smyth',
+        `intake resolved to ${renameSession.enduserId} (expected ${renameTarget.id}); stored lname is ${JSON.stringify(renamed.lname)}, expected "Smyth"`,
+      )
+
+      // the email clause of the same $or must keep working untouched
+      const EMAIL = `dontsend-ci-${RAND()}@tellescope.com`
+      const byEmail = await sdk.api.endusers.createOne({ fname: 'Email', lname: 'Only', email: EMAIL })
+      const emailMatchedId = await intake(form, { email: EMAIL })
+      record(
+        'setting ON: matching by email alone is unchanged',
+        emailMatchedId === byEmail.id,
+        `intake resolved to ${emailMatchedId}, expected ${byEmail.id}`,
+      )
+
+      // a blank last name must stay unmatchable rather than matching every nameless contact
+      const nameless = await sdk.api.endusers.createOne({ dateOfBirth: '1960-06-06' })
+      const namelessMatchId = await intake(form, { fname: 'Nobody', dateOfBirth: '1960-06-06' })
+      record(
+        'setting ON: a blank name does not match a nameless contact (sentinel survives)',
+        namelessMatchId !== nameless.id,
+        `intake resolved to ${namelessMatchId}, nameless contact is ${nameless.id}`,
+      )
+    }
+
+    /* ============ 3. several case variants: the OLDEST match wins, every time ============ */
+    {
+      await setCaseInsensitive(true)
+      const { form } = await createPublicForm(sdk)
+      const DOB = '1992-03-04'
+
+      // Two case variants of the same name with the same DOB. "Oldest" is `_id` order, which is
+      // creation order only to one-second granularity: ObjectIds are minted in the API process and
+      // the API runs one process per CPU, so two back-to-back creates handled by different cluster
+      // workers inside the same second can sort either way. The assertion is therefore on the LOWER
+      // _id rather than on which call was issued first — that is exactly what sort: 'oldFirst'
+      // promises, and it makes the check deterministic.
+      const a = await sdk.api.endusers.createOne({ fname: 'Olive', lname: 'Mcdonald', dateOfBirth: DOB })
+      const b = await sdk.api.endusers.createOne({ fname: 'Olive', lname: 'MCDONALD', dateOfBirth: DOB })
+      const [lowest, highest] = a.id < b.id ? [a, b] : [b, a]
+
+      const resolved: string[] = []
+      for (let i = 0; i < 3; i++) {
+        resolved.push(await intake(form, { fname: 'Olive', lname: 'McDonald', dateOfBirth: DOB }))
+      }
+      record(
+        'setting ON: with two case variants, the lowest-_id (oldest) contact wins on every submission',
+        resolved.every(id => id === lowest.id),
+        `resolved ${JSON.stringify(resolved)}, lowest _id=${lowest.id}, other=${highest.id}`,
+      )
+    }
+
+    /* ============ 4. regex metacharacters are escaped, not treated as wildcards ============ */
+    {
+      await setCaseInsensitive(true)
+      const { form } = await createPublicForm(sdk)
+      const DOB = '1993-04-05'
+
+      // Two INDEPENDENT checks rather than one contact plus a decoy sharing a DOB. With both under
+      // one DOB, an unescaped '.' would match them both and the oldest-wins rule could still return
+      // the intended contact, so the check would pass vacuously whenever _id order happened to
+      // favour it. Separating them removes any dependence on creation order.
+
+      // 4a. positive: the literal period matches itself, case-insensitively
+      const target = await sdk.api.endusers.createOne({ fname: 'Mary', lname: 'O.Brien', dateOfBirth: DOB })
+      const matchedId = await intake(form, { fname: 'Mary', lname: 'o.BRIEN', dateOfBirth: DOB })
+      record(
+        'setting ON: "." in a name is matched literally (matches the contact that has it)',
+        matchedId === target.id,
+        `intake resolved to ${matchedId}, expected O.Brien ${target.id}`,
+      )
+
+      // 4b. negative: the ONLY contact on this DOB has a different character where the '.' is, so an
+      // unescaped '.' (a wildcard) would match it and this check would fail. Nothing else can match.
+      const WILDCARD_DOB = '1993-04-06'
+      const decoy = await sdk.api.endusers.createOne({ fname: 'Mary', lname: 'OXBrien', dateOfBirth: WILDCARD_DOB })
+      const decoyProbeId = await intake(form, { fname: 'Mary', lname: 'O.Brien', dateOfBirth: WILDCARD_DOB })
+      record(
+        'setting ON: "." is NOT a wildcard (does not match a contact with another character there)',
+        decoyProbeId !== decoy.id,
+        `intake resolved to ${decoyProbeId}, must NOT be the OXBrien contact ${decoy.id}`,
+      )
+
+      // a hyphen is not a metacharacter but is the other punctuation real names carry
+      const HYPHEN_DOB = '1994-05-06'
+      const hyphenated = await sdk.api.endusers.createOne({ fname: 'Ann', lname: 'Smith-Jones', dateOfBirth: HYPHEN_DOB })
+      const hyphenMatchedId = await intake(form, { fname: 'Ann', lname: 'SMITH-JONES', dateOfBirth: HYPHEN_DOB })
+      record(
+        'setting ON: a hyphenated name matches case-insensitively',
+        hyphenMatchedId === hyphenated.id,
+        `intake resolved to ${hyphenMatchedId}, expected ${hyphenated.id}`,
+      )
+    }
+
+    /* ============ 5. auto-merge: gated by the setting, and still bails on ambiguity ============ */
+    {
+      const DOB = '1995-06-07'
+
+      // 5a. setting OFF: a capitalization variant is not a merge candidate
+      await setCaseInsensitive(false)
+      const offForm = await createPublicForm(sdk, { autoMergeOnSubmission: true })
+      const offDestination = await sdk.api.endusers.createOne({ fname: 'Merge', lname: 'MCDONALD', dateOfBirth: DOB })
+      const offSourceId = await submitWithSkipMatch(offForm.form, offForm.fields, {
+        fname: 'Merge', lname: 'Mcdonald', dateOfBirth: DOB,
+      })
+      record(
+        'auto-merge, setting OFF: a capitalization variant does NOT merge (unchanged behavior)',
+        await enduserExists(sdk, offSourceId),
+        `source ${offSourceId} should still exist alongside destination ${offDestination.id}`,
+      )
+
+      // 5b. setting ON: the same submission merges
+      await setCaseInsensitive(true)
+      const onForm = await createPublicForm(sdk, { autoMergeOnSubmission: true })
+      const ON_DOB = '1996-07-08'
+      const onDestination = await sdk.api.endusers.createOne({ fname: 'Merge', lname: 'MCDONNELL', dateOfBirth: ON_DOB })
+      const onSourceId = await submitWithSkipMatch(onForm.form, onForm.fields, {
+        fname: 'Merge', lname: 'Mcdonnell', dateOfBirth: ON_DOB,
+      })
+      const onSourceGone = !(await enduserExists(sdk, onSourceId))
+      const mergedDestination = await sdk.api.endusers.getOne(onDestination.id)
+      record(
+        'auto-merge, setting ON: a capitalization variant merges into the existing contact',
+        onSourceGone && !!mergedDestination.mergedIds?.includes(onSourceId),
+        `source deleted=${onSourceGone}, destination mergedIds=${JSON.stringify(mergedDestination.mergedIds)}`,
+      )
+      record(
+        'auto-merge, setting ON: the merged-into contact keeps its stored capitalization',
+        mergedDestination.lname === 'MCDONNELL',
+        `destination lname is ${JSON.stringify(mergedDestination.lname)}, must still be "MCDONNELL"`,
+      )
+
+      // 5c. setting ON: two case variants are ambiguous, so nothing may be merged
+      const AMBIGUOUS_DOB = '1997-08-09'
+      const ambiguousForm = await createPublicForm(sdk, { autoMergeOnSubmission: true })
+      const candidateA = await sdk.api.endusers.createOne({ fname: 'Ambi', lname: 'Mcguire', dateOfBirth: AMBIGUOUS_DOB })
+      const candidateB = await sdk.api.endusers.createOne({ fname: 'Ambi', lname: 'MCGUIRE', dateOfBirth: AMBIGUOUS_DOB })
+      const ambiguousSourceId = await submitWithSkipMatch(ambiguousForm.form, ambiguousForm.fields, {
+        fname: 'Ambi', lname: 'McGuire', dateOfBirth: AMBIGUOUS_DOB,
+      })
+      const [a, b] = await Promise.all([
+        sdk.api.endusers.getOne(candidateA.id),
+        sdk.api.endusers.getOne(candidateB.id),
+      ])
+      record(
+        'auto-merge, setting ON: two case variants are ambiguous, so NOTHING is merged',
+        await enduserExists(sdk, ambiguousSourceId)
+          && !a.mergedIds?.includes(ambiguousSourceId)
+          && !b.mergedIds?.includes(ambiguousSourceId),
+        `source ${ambiguousSourceId} exists=${await enduserExists(sdk, ambiguousSourceId)},`
+        + ` A.mergedIds=${JSON.stringify(a.mergedIds)}, B.mergedIds=${JSON.stringify(b.mergedIds)}`,
+      )
+    }
+
+    /* ====== 5b. a public form GROUP: form 2 must not rewrite the capitalization either ====== */
+    {
+      await setCaseInsensitive(true)
+      const DOB = '1986-06-16'
+      const stored = await sdk.api.endusers.createOne({ fname: 'Group', lname: 'MCDONALD', dateOfBirth: DOB })
+
+      // Form 1 carries the intake screen that does the matching; form 2 ALSO carries name intake
+      // questions, which is the case that escapes a publicSubmit-only guard — the follow-on group
+      // responses are inserted by session_for_public_form without publicSubmit.
+      const first = await createPublicForm(sdk)
+      const second = await createPublicForm(sdk)
+      const group = await sdk.api.form_groups.createOne({
+        title: `Case Insensitive Group ${RAND()}`,
+        formIds: [first.form.id, second.form.id],
+      })
+
+      const enduserSDK = new EnduserSession({ host, businessId })
+      const { authToken, enduserId } = await enduserSDK.api.form_responses.session_for_public_form({
+        formId: first.form.id,
+        businessId,
+        groupId: group.id,
+        fname: 'Group',
+        lname: 'Mcdonald',
+        dateOfBirth: DOB,
+      })
+      const authedSDK = new EnduserSession({ host, businessId, authToken })
+
+      // Find the group's response for form 2. session_for_public_form inserts the follow-on group
+      // responses in a fire-and-forget insertMany issued AFTER res.json, so it is not ordered
+      // against this request — poll rather than reading once, or a loaded parallel run can lose the
+      // race. A timeout here fails the check loudly (submitted stays false); it never passes by
+      // default.
+      let secondResponse: { accessCode?: string } | undefined
+      for (let attempt = 0; attempt < 20 && !secondResponse; attempt++) {
+        const responses = await sdk.api.form_responses.getSome({ filter: { enduserId: stored.id } })
+        secondResponse = responses.find(r => r.formId === second.form.id)
+        if (!secondResponse) await new Promise(res => setTimeout(res, 100))
+      }
+
+      let submitted = false
+      if (secondResponse?.accessCode) {
+        const f = (intakeField: string) => second.fields.find(x => x.intakeField === intakeField)!
+        await authedSDK.api.form_responses.submit_form_response({
+          accessCode: secondResponse.accessCode,
+          responses: [
+            { fieldId: f('fname').id, fieldTitle: 'First Name', answer: { type: 'string', value: 'Group' } },
+            { fieldId: f('lname').id, fieldTitle: 'Last Name', answer: { type: 'string', value: 'Mcdonald' } },
+          ],
+        })
+        submitted = true
+      }
+
+      const after = await sdk.api.endusers.getOne(stored.id)
+      record(
+        'setting ON: form 2 of a public GROUP does not rewrite the matched contact\'s capitalization',
+        enduserId === stored.id && submitted && after.lname === 'MCDONALD',
+        `intake resolved to ${enduserId} (expected ${stored.id}); submitted form 2 = ${submitted}`
+        + ` (accessCode present = ${!!secondResponse?.accessCode}); stored lname is ${JSON.stringify(after.lname)}, must still be "MCDONALD"`,
+      )
+    }
+
+    /* ====== 6. the email+fname+lname clause (matchEmailAndNames) is gated too, and the ======
+       ====== identifiers stay exact equality                                           ====== */
+    {
+      await setCaseInsensitive(true)
+      const { form } = await createPublicForm(sdk)
+
+      // dateOfBirth is an identifier and stays an exact match: the same name with a different DOB
+      // must not match, with the setting on
+      const DOB = '1999-10-11'
+      const dobContact = await sdk.api.endusers.createOne({ fname: 'Dob', lname: 'MCDONALD', dateOfBirth: DOB })
+      const wrongDobId = await intake(form, { fname: 'Dob', lname: 'Mcdonald', dateOfBirth: '1999-10-12' })
+      record(
+        'setting ON: dateOfBirth is still an exact match (a different DOB does not match)',
+        wrongDobId !== dobContact.id,
+        `intake resolved to ${wrongDobId}, contact with DOB ${DOB} is ${dobContact.id}`,
+      )
+
+      // with matchEmailAndNames on, the email branch of the $or additionally requires fname + lname;
+      // those two must be case-insensitive as well, or the opt-in silently excludes email matching
+      await sdk.api.organizations.updateOne(businessId, {
+        settings: { endusers: { matchEmailAndNames: true } },
+      })
+      try {
+        const EMAIL = `dontsend-mean-${RAND()}@tellescope.com`
+        const emailContact = await sdk.api.endusers.createOne({ fname: 'Mean', lname: 'MCDONALD', email: EMAIL })
+        const matchedId = await intake(form, { email: EMAIL, fname: 'Mean', lname: 'Mcdonald' })
+        record(
+          'setting ON + matchEmailAndNames: the email+fname+lname clause is case-insensitive too',
+          matchedId === emailContact.id,
+          `intake resolved to ${matchedId}, expected ${emailContact.id}`,
+        )
+      } finally {
+        await sdk.api.organizations.updateOne(businessId, {
+          settings: { endusers: { matchEmailAndNames: false } },
+        })
+      }
+    }
+
+    /* ============ 7. appointment booking is deliberately NOT gated by the setting ============ */
+    {
+      await setCaseInsensitive(true)
+      const DOB = '1998-09-10'
+      const stored = await sdk.api.endusers.createOne({ fname: 'Booking', lname: 'MCDONALD', dateOfBirth: DOB })
+
+      const template = await sdk.api.calendar_event_templates.createOne({
+        title: `Case Insensitive Booking ${RAND()}`,
+        durationInMinutes: 30,
+      })
+      const bookingSDK = new EnduserSession({ host, businessId })
+      let bookingMatched: boolean | undefined
+      try {
+        await bookingSDK.api.calendar_events.session_for_public_appointment_booking({
+          calendarEventTemplateId: template.id,
+          businessId,
+          fname: 'Booking',
+          lname: 'Mcdonald',
+          dateOfBirth: DOB,
+        })
+        // the booking endpoint returns only an authToken, so "did it match?" is read off the contact
+        // list: a non-match inserts a SECOND contact with the submitted capitalization
+        const sameName = await sdk.api.endusers.getSome({ filter: { dateOfBirth: DOB } })
+        bookingMatched = sameName.length === 1
+      } catch (err: any) {
+        bookingMatched = undefined
+      }
+
+      record(
+        'appointment booking stays byte-exact even with the setting ON (deliberately out of scope)',
+        bookingMatched === false,
+        bookingMatched === undefined
+          ? 'the booking endpoint errored, so this check could not be evaluated'
+          : `contacts with dateOfBirth ${DOB}: ${bookingMatched ? 1 : 2}; expected 2 (a separate contact), stored=${stored.id}`,
+      )
+    }
+
+    return checks
+  } finally {
+    await tenant?.teardown()
+  }
+}
+
+/** Asserting wrapper, for standalone runs. */
+export const public_form_case_insensitive_match_tests = async () => {
+  assert_checks('Public form case-insensitive matching', await public_form_case_insensitive_match_checks())
+}
+
+/** Enrolls this suite in the auto-discovered parallel pool — see run_discovered_isolated_suites. */
+export const ISOLATED_SUITE: IsolatedSuite = { name: 'Public form case-insensitive matching', run: public_form_case_insensitive_match_checks }
+
+// Allow running this test file independently
+if (require.main === module) {
+  console.log(`Using API URL: ${host}`)
+  public_form_case_insensitive_match_tests()
+    .then(() => {
+      console.log("Public form case-insensitive match test suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("Public form case-insensitive match test suite failed:", error)
+      process.exit(1)
+    })
+}

package/src/tests/api_tests/security/add-to-journey-foreign-enduserid.test.ts

@@ -4,6 +4,7 @@ import {
   assert_checks,
   Check,
   setup_isolated_tenant,
+  IsolatedSuite,
 } from "../../setup_isolated"
 import { poll_for_results } from "@tellescope/testing"
 
@@ -199,6 +200,9 @@ export const add_to_journey_foreign_enduserid_tests = async () => {
   assert_checks('add_to_journey foreign enduserId', await add_to_journey_foreign_enduserid_checks())
 }
 
+/** Enrolls this suite in the auto-discovered parallel pool — see run_discovered_isolated_suites. */
+export const ISOLATED_SUITE: IsolatedSuite = { name: 'add_to_journey foreign enduserId', run: add_to_journey_foreign_enduserid_checks }
+
 // Allow running this test file independently
 if (require.main === module) {
   console.log(`🌐 Using API URL: ${host}`)