feat: add United Ucard eligibility check with OTP + persistent session

Adds a full login/OTP/search/capture flow for United Ucard (OneHealthcareID -> UHC Dental provider portal), mirroring the United SCO/DDMA pattern: persistent Chrome profile, OTP polling, member eligibility search, and PDF capture saved to the patient's Eligibility folder. Also fixes a validation bug in the browser-safe patient schema where email/address/city/zipCode/gender/phone were optional but not nullable, rejecting patient records with null values on those fields during edits (e.g. "Expected string, received null"). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-09-13 22:44:43 -04:00
parent e8889c0ff8
commit f30016e674
14 changed files with 2226 additions and 17 deletions
@@ -14,6 +14,7 @@ import { runOcrProcessor } from "./processors/ocrProcessor";
 import { runDdmaEligibilityProcessor } from "./processors/ddmaEligibilityProcessor";
 import { runDeltaInsEligibilityProcessor } from "./processors/deltaInsEligibilityProcessor";
 import { runUnitedSCOEligibilityProcessor } from "./processors/unitedSCOEligibilityProcessor";
+import { runUnitedUcardEligibilityProcessor } from "./processors/unitedUcardEligibilityProcessor";
 import { runDentaQuestEligibilityProcessor } from "./processors/dentaQuestEligibilityProcessor";
 import { runCCAEligibilityProcessor } from "./processors/ccaEligibilityProcessor";
 import { runCCAClaimProcessor } from "./processors/ccaClaimProcessor";
@@ -128,6 +129,20 @@ export function enqueueSeleniumJob(data: SeleniumJobData): string {
        job.id
      );
    }
+    if (jobType === "uniteducard-eligibility-check") {
+      return runUnitedUcardEligibilityProcessor(
+        {
+          enrichedPayload: data.enrichedPayload,
+          userId: data.userId,
+          insuranceId: data.insuranceId!,
+          formFirstName: data.formFirstName,
+          formLastName: data.formLastName,
+          formDob: data.formDob,
+          socketId: data.socketId,
+        },
+        job.id
+      );
+    }
    if (jobType === "tuftssco-eligibility-check") {
      return runDentaQuestEligibilityProcessor(
        {
@@ -0,0 +1,349 @@
+/**
+ * Processor for "uniteducard-eligibility-check" jobs (United Ucard / OneHealthcareID).
+ *
+ * Same persistent-session flow as UnitedSCO/DDMA:
+ *   1. Start a session on the Python agent (POST /uniteducard-eligibility)
+ *   2. Emit selenium:uniteducard_session_started → frontend stores session_id for OTP
+ *   3. Poll agent status, emitting selenium:otp_required when OTP is needed
+ *   4. On completion: save PDF (file path), create/update patient, update status
+ *   5. Return { pdfFileId, pdfFilename, patientUpdateStatus, pdfUploadStatus }
+ */
+import fs from "fs/promises";
+import fsSync from "fs";
+import path from "path";
+import { storage } from "../../storage";
+import { emptyFolderContainingFile } from "../../utils/emptyTempFolder";
+import {
+  forwardToSeleniumUnitedUcardEligibilityAgent,
+  getSeleniumUnitedUcardSessionStatus,
+} from "../../services/seleniumUnitedUcardEligibilityClient";
+import { splitName, createOrUpdatePatientByInsuranceId, imageToPdfBuffer } from "./_shared";
+import { io } from "../../socket";
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function now() {
+  return new Date().toISOString();
+}
+
+function log(tag: string, msg: string, ctx?: any) {
+  console.log(`${now()} [${tag}] ${msg}`, ctx ?? "");
+}
+
+function emitToSocket(socketId: string | undefined, event: string, payload: any) {
+  if (!socketId || !io) return;
+  try {
+    const socket = io.sockets.sockets.get(socketId);
+    if (socket) {
+      socket.emit(event, payload);
+      log("uniteducard-processor", `emitted ${event}`, { socketId });
+    }
+  } catch (err: any) {
+    log("uniteducard-processor", `emit failed for ${event}`, { err: err?.message });
+  }
+}
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface UnitedUcardEligibilityProcessorInput {
+  enrichedPayload: any;
+  userId: number;
+  insuranceId: string;
+  formFirstName?: string;
+  formLastName?: string;
+  formDob?: string;
+  socketId?: string;
+}
+
+export interface UnitedUcardEligibilityProcessorResult {
+  patientUpdateStatus?: string;
+  pdfUploadStatus?: string;
+  pdfFileId?: number | string | null;
+  pdfFilename?: string | null;
+}
+
+// ─── Core DB processing ───────────────────────────────────────────────────────
+
+async function processUnitedUcardResult(
+  userId: number,
+  insuranceId: string,
+  formFirstName: string | undefined,
+  formLastName: string | undefined,
+  formDob: string | undefined,
+  seleniumResult: any
+): Promise<UnitedUcardEligibilityProcessorResult> {
+  const output: UnitedUcardEligibilityProcessorResult = {};
+  let createdPdfFileId: number | string | null = null;
+
+  try {
+    // 1) Resolve patient name
+    const rawName =
+      typeof seleniumResult?.patientName === "string"
+        ? seleniumResult.patientName.trim()
+        : null;
+
+    const { firstName, lastName } = rawName
+      ? splitName(rawName)
+      : { firstName: formFirstName ?? "", lastName: formLastName ?? "" };
+
+    // 2) Create / update patient
+    await createOrUpdatePatientByInsuranceId({
+      insuranceId,
+      firstName,
+      lastName,
+      dob: formDob,
+      userId,
+    });
+
+    // 3) Fetch patient
+    const patient = await storage.getPatientByInsuranceId(insuranceId);
+    if (!patient?.id) {
+      output.patientUpdateStatus = "Patient not found; no update performed";
+      return output;
+    }
+
+    // 4) Determine eligibility status
+    const eligStatus = (seleniumResult?.eligibility ?? "").toLowerCase();
+    const newStatus =
+      eligStatus === "active" || eligStatus === "y" ? "ACTIVE" :
+      eligStatus === "inactive" ? "INACTIVE" : null;
+
+    const statusUpdates: any = { insuranceProvider: "United Ucard" };
+    if (newStatus) statusUpdates.status = newStatus;
+
+    const scrapedMemberId =
+      typeof seleniumResult?.memberId === "string"
+        ? seleniumResult.memberId.replace(/\s+/g, "")
+        : null;
+    if (scrapedMemberId && scrapedMemberId !== insuranceId) {
+      statusUpdates.insuranceId = scrapedMemberId;
+      log("uniteducard-processor", "member ID changed, overwriting on patient record", {
+        patientId: patient.id,
+        oldInsuranceId: insuranceId,
+        newInsuranceId: scrapedMemberId,
+      });
+    }
+
+    await storage.updatePatient(patient.id, statusUpdates);
+    output.patientUpdateStatus = newStatus
+      ? `Patient status updated to ${newStatus}`
+      : `Eligibility unknown — status not changed`;
+    if (statusUpdates.insuranceId) {
+      output.patientUpdateStatus += ` (Member ID updated from ${insuranceId} to ${statusUpdates.insuranceId})`;
+    }
+
+    // 5) Resolve PDF buffer from file path
+    let pdfBuffer: Buffer | null = null;
+    let pdfFilename: string | null = null;
+
+    const pdfPath: string | null =
+      seleniumResult?.pdf_path ?? seleniumResult?.ss_path ?? null;
+
+    if (pdfPath && fsSync.existsSync(pdfPath)) {
+      if (pdfPath.endsWith(".pdf")) {
+        try {
+          pdfBuffer = await fs.readFile(pdfPath);
+          pdfFilename = path.basename(pdfPath);
+          log("uniteducard-processor", "read PDF directly", { pdfPath });
+        } catch (e: any) {
+          output.pdfUploadStatus = `Failed to read PDF: ${e.message}`;
+        }
+      } else if (
+        pdfPath.endsWith(".png") ||
+        pdfPath.endsWith(".jpg") ||
+        pdfPath.endsWith(".jpeg")
+      ) {
+        try {
+          pdfBuffer = await imageToPdfBuffer(pdfPath);
+          pdfFilename = `uniteducard_eligibility_${insuranceId}_${Date.now()}.pdf`;
+          log("uniteducard-processor", "converted screenshot to PDF", { pdfPath });
+        } catch (e: any) {
+          output.pdfUploadStatus = `Failed to convert screenshot to PDF: ${e.message}`;
+        }
+      }
+    } else {
+      output.pdfUploadStatus = "No valid file path from Selenium; nothing uploaded.";
+    }
+
+    // 6) Save PDF to patient document group
+    if (pdfBuffer && pdfFilename) {
+      const patientName = `${patient.firstName ?? ""} ${patient.lastName ?? ""}`.trim() || `Patient ${patient.id}`;
+      const cloudFile = await storage.savePdfToCloudStorage(
+        userId,
+        patient.id,
+        patientName,
+        "Eligibility",
+        pdfFilename,
+        pdfBuffer
+      );
+      createdPdfFileId = `cloud:${cloudFile.id}`;
+      output.pdfUploadStatus = "PDF saved to Eligibility folder";
+      output.pdfFilename = pdfFilename;
+    }
+
+    output.pdfFileId = createdPdfFileId;
+    return output;
+  } catch (err: any) {
+    return {
+      ...output,
+      pdfUploadStatus:
+        output.pdfUploadStatus ?? `Processing failed: ${err?.message ?? String(err)}`,
+      pdfFileId: createdPdfFileId,
+    };
+  } finally {
+    const cleanupPath = seleniumResult?.pdf_path ?? seleniumResult?.ss_path ?? null;
+    if (cleanupPath) {
+      try {
+        await emptyFolderContainingFile(cleanupPath);
+      } catch (e) {
+        log("uniteducard-processor", "cleanup failed", { cleanupPath });
+      }
+    }
+  }
+}
+
+// ─── Polling loop ────────────────────────────────────────────────────────────
+
+async function pollUntilDone(
+  sessionId: string,
+  socketId: string | undefined,
+  jobId: string,
+  pollTimeoutMs = 5 * 60 * 1000
+): Promise<any> {
+  const maxAttempts = 600;
+  const pollIntervalMs = 500;
+  const maxTransientErrors = 12;
+  const noProgressLimit = 120;
+
+  let transientErrors = 0;
+  let consecutiveNoProgress = 0;
+  let lastStatus: string | null = null;
+  const deadline = Date.now() + pollTimeoutMs;
+
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    if (Date.now() > deadline) {
+      throw new Error(
+        `UnitedUcard polling timeout (${Math.round(pollTimeoutMs / 1000)}s) for session ${sessionId}`
+      );
+    }
+
+    try {
+      const st = await getSeleniumUnitedUcardSessionStatus(sessionId);
+      const status: string = st?.status ?? "unknown";
+
+      log("uniteducard-processor", `poll attempt=${attempt}`, { sessionId, status });
+
+      transientErrors = 0;
+
+      const isTerminal =
+        status === "completed" || status === "error" || status === "not_found";
+      if (status === lastStatus && !isTerminal) {
+        consecutiveNoProgress++;
+      } else {
+        consecutiveNoProgress = 0;
+      }
+      lastStatus = status;
+
+      if (consecutiveNoProgress >= noProgressLimit) {
+        throw new Error(
+          `No progress from Python agent (status="${status}") after ${consecutiveNoProgress} polls`
+        );
+      }
+
+      if (status === "waiting_for_otp") {
+        emitToSocket(socketId, "selenium:otp_required", {
+          session_id: sessionId,
+          jobId,
+          message: "OTP required. Please enter the verification code.",
+        });
+        await new Promise((r) => setTimeout(r, pollIntervalMs));
+        continue;
+      }
+
+      if (status === "completed") {
+        log("uniteducard-processor", "session completed", { sessionId });
+        return st.result;
+      }
+
+      if (status === "error" || status === "not_found") {
+        throw new Error(st?.message || `UnitedUcard session ended with status: ${status}`);
+      }
+
+      await new Promise((r) => setTimeout(r, pollIntervalMs));
+    } catch (err: any) {
+      const isTerminal =
+        err?.response?.status === 404 ||
+        (typeof err?.message === "string" &&
+          (err.message.includes("not_found") ||
+            err.message.includes("polling timeout") ||
+            err.message.includes("No progress")));
+
+      if (isTerminal) throw err;
+
+      transientErrors++;
+      if (transientErrors > maxTransientErrors) {
+        throw new Error(
+          `Too many transient network errors polling UnitedUcard session ${sessionId}`
+        );
+      }
+      const backoff = Math.min(30_000, 500 * Math.pow(2, transientErrors - 1));
+      log("uniteducard-processor", `transient error #${transientErrors}, backoff ${backoff}ms`, {
+        err: err?.message,
+      });
+      await new Promise((r) => setTimeout(r, backoff));
+    }
+  }
+
+  throw new Error(`UnitedUcard polling exhausted all attempts for session ${sessionId}`);
+}
+
+// ─── Main processor entry point ───────────────────────────────────────────────
+
+export async function runUnitedUcardEligibilityProcessor(
+  input: UnitedUcardEligibilityProcessorInput,
+  jobId: string
+): Promise<UnitedUcardEligibilityProcessorResult> {
+  const {
+    enrichedPayload,
+    userId,
+    insuranceId,
+    formFirstName,
+    formLastName,
+    formDob,
+    socketId,
+  } = input;
+
+  log("uniteducard-processor", "starting Python agent session", { insuranceId });
+  const agentResp = await forwardToSeleniumUnitedUcardEligibilityAgent(enrichedPayload);
+
+  if (!agentResp?.session_id) {
+    throw new Error("Python agent did not return a session_id for United Ucard eligibility");
+  }
+
+  const sessionId = agentResp.session_id as string;
+  log("uniteducard-processor", "got session_id", { sessionId });
+
+  emitToSocket(socketId, "selenium:uniteducard_session_started", {
+    session_id: sessionId,
+    jobId,
+  });
+
+  const seleniumResult = await pollUntilDone(sessionId, socketId, jobId);
+
+  if (!seleniumResult || seleniumResult.status === "error") {
+    throw new Error(seleniumResult?.message ?? "United Ucard session returned an error result");
+  }
+
+  log("uniteducard-processor", "processing DB result", { insuranceId });
+  const result = await processUnitedUcardResult(
+    userId,
+    insuranceId,
+    formFirstName,
+    formLastName,
+    formDob,
+    seleniumResult
+  );
+
+  log("uniteducard-processor", "done", { result });
+  return result;
+}
@@ -10,6 +10,7 @@ export type SeleniumJobType =
  | "ddma-eligibility-check"
  | "deltains-eligibility-check"
  | "unitedsco-eligibility-check"
+  | "uniteducard-eligibility-check"
  | "cca-eligibility-check"
  | "cca-claim-submit"
  | "cca-preauth-submit"