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>
This commit is contained in:
2026-09-13 22:44:43 -04:00
co-authored by Claude Sonnet 5
parent e8889c0ff8
commit f30016e674
14 changed files with 2226 additions and 17 deletions
+15
View File
@@ -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;
}
+1
View File
@@ -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"
+2
View File
@@ -14,6 +14,7 @@ import insuranceStatusRoutes from "./insuranceStatus";
import insuranceStatusDdmaRoutes from "./insuranceStatusDDMA";
import insuranceStatusDeltaInsRoutes from "./insuranceStatusDeltaIns";
import insuranceStatusUnitedSCORoutes from "./insuranceStatusUnitedSCO";
import insuranceStatusUnitedUcardRoutes from "./insuranceStatusUnitedUcard";
import insuranceStatusTuftsSCORoutes from "./insuranceStatusTuftsSCO";
import insuranceStatusCCARoutes from "./insuranceStatusCCA";
import insuranceStatusCCAClaimRoutes from "./insuranceStatusCCAClaim";
@@ -66,6 +67,7 @@ router.use("/insurance-status", insuranceStatusRoutes);
router.use("/insurance-status-ddma", insuranceStatusDdmaRoutes);
router.use("/insurance-status-deltains", insuranceStatusDeltaInsRoutes);
router.use("/insurance-status-unitedsco", insuranceStatusUnitedSCORoutes);
router.use("/insurance-status-uniteducard", insuranceStatusUnitedUcardRoutes);
router.use("/insurance-status-tuftssco", insuranceStatusTuftsSCORoutes);
router.use("/insurance-status-cca", insuranceStatusCCARoutes);
router.use("/insurance-status-bcbs-ma", insuranceStatusBcbsMaRoutes);
@@ -0,0 +1,135 @@
import { Router, Request, Response } from "express";
import { storage } from "../storage";
import { forwardOtpToSeleniumUnitedUcardAgent } from "../services/seleniumUnitedUcardEligibilityClient";
import { io } from "../socket";
import { enqueueSeleniumJob } from "../queue/jobRunner";
import { prisma as db } from "@repo/db/client";
const router = Router();
function log(tag: string, msg: string, ctx?: any) {
console.log(`${new Date().toISOString()} [${tag}] ${msg}`, ctx ?? "");
}
function emitSafe(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);
} catch (err: any) {
log("socket", "emit failed", { socketId, event, err: err?.message });
}
}
/**
* POST /uniteducard-eligibility
*
* Enqueues a United Ucard (OneHealthcareID) eligibility check (concurrency=1).
*
* Body:
* data — patient + search fields (memberId, dateOfBirth, firstName, lastName, …)
* socketId — socket.io client id for real-time updates
*
* Response: { status: "queued", jobId: "…" }
*
* Real-time socket events:
* job:update { jobId, jobType, status: "active"|"completed"|"failed", … }
* selenium:uniteducard_session_started { session_id, jobId }
* selenium:otp_required { session_id, jobId, message }
*/
router.post(
"/uniteducard-eligibility",
async (req: Request, res: Response): Promise<any> => {
if (!req.body.data) {
return res.status(400).json({ error: "Missing eligibility data for selenium" });
}
if (!req.user?.id) {
return res.status(401).json({ error: "Unauthorized: user info missing" });
}
try {
const rawData =
typeof req.body.data === "string" ? JSON.parse(req.body.data) : req.body.data;
// Fetch United Ucard credentials from DB
const credentials = await storage.getInsuranceCredentialByUserAndSiteKey(
req.user.id,
rawData.insuranceSiteKey
);
if (!credentials) {
return res.status(404).json({
error:
"No credentials found for United Ucard. Please add them on the Settings page.",
});
}
const seleniumSettings = await db.seleniumSettings.findUnique({ where: { userId: req.user.id } });
const enrichedData = {
...rawData,
uniteducardUsername: credentials.username,
uniteducardPassword: credentials.password,
paymentGroupId: seleniumSettings?.paymentGroupId ?? "",
};
const socketId: string | undefined = req.body.socketId;
const jobId = enqueueSeleniumJob({
jobType: "uniteducard-eligibility-check",
userId: req.user.id,
socketId,
enrichedPayload: enrichedData,
insuranceId: String(rawData.memberId ?? "").trim(),
formFirstName: rawData.firstName,
formLastName: rawData.lastName,
formDob: rawData.dateOfBirth,
});
log("uniteducard-route", "job enqueued", { jobId, insuranceId: rawData.memberId });
return res.json({ status: "queued", jobId });
} catch (err: any) {
console.error("[uniteducard-route] enqueue failed:", err);
return res.status(500).json({
error: err.message || "Failed to enqueue United Ucard selenium job",
});
}
}
);
/**
* POST /selenium/submit-otp
* Side-channel OTP forwarding — does NOT go through the queue.
* Body: { session_id, otp, socketId? }
*/
router.post(
"/selenium/submit-otp",
async (req: Request, res: Response): Promise<any> => {
const { session_id: sessionId, otp, socketId } = req.body;
if (!sessionId || !otp) {
return res.status(400).json({ error: "session_id and otp are required" });
}
try {
const r = await forwardOtpToSeleniumUnitedUcardAgent(sessionId, otp);
emitSafe(socketId, "selenium:otp_submitted", {
session_id: sessionId,
result: r,
});
return res.json(r);
} catch (err: any) {
console.error(
"[uniteducard-route] submit-otp failed:",
err?.response?.data || err?.message || err
);
return res.status(500).json({
error: "Failed to forward OTP to selenium agent",
detail: err?.message || err,
});
}
}
);
export default router;
@@ -0,0 +1,72 @@
import axios from "axios";
import http from "http";
import https from "https";
import dotenv from "dotenv";
dotenv.config();
const SELENIUM_AGENT_BASE = process.env.SELENIUM_AGENT_BASE_URL;
const httpAgent = new http.Agent({ keepAlive: true, keepAliveMsecs: 60_000 });
const httpsAgent = new https.Agent({ keepAlive: true, keepAliveMsecs: 60_000 });
const client = axios.create({
baseURL: SELENIUM_AGENT_BASE,
timeout: 5 * 60 * 1000,
httpAgent,
httpsAgent,
validateStatus: (s) => s >= 200 && s < 600,
});
async function requestWithRetries(config: any, retries = 4, baseBackoffMs = 300) {
for (let attempt = 1; attempt <= retries; attempt++) {
try {
const r = await client.request(config);
if (![502, 503, 504].includes(r.status)) return r;
console.warn(`[uniteducard-client] retryable HTTP status ${r.status} (attempt ${attempt})`);
} catch (err: any) {
const code = err?.code;
const isTransient =
code === "ECONNRESET" || code === "ECONNREFUSED" || code === "EPIPE" || code === "ETIMEDOUT";
if (!isTransient) throw err;
console.warn(`[uniteducard-client] transient network error ${code} (attempt ${attempt})`);
}
await new Promise((r) => setTimeout(r, baseBackoffMs * attempt));
}
return client.request(config);
}
function log(tag: string, msg: string, ctx?: any) {
console.log(`${new Date().toISOString()} [${tag}] ${msg}`, ctx ?? "");
}
export async function forwardToSeleniumUnitedUcardEligibilityAgent(data: any): Promise<any> {
const payload = { data };
const url = `/uniteducard-eligibility`;
log("uniteducard-client", "POST uniteducard-eligibility", { url: SELENIUM_AGENT_BASE + url });
const r = await requestWithRetries({ url, method: "POST", data: payload }, 4);
log("uniteducard-client", "agent response", { status: r.status, dataKeys: r.data ? Object.keys(r.data) : null });
if (r.status >= 500) throw new Error(`Selenium agent server error: ${r.status}`);
return r.data;
}
export async function forwardOtpToSeleniumUnitedUcardAgent(sessionId: string, otp: string): Promise<any> {
const url = `/submit-otp`;
log("uniteducard-client", "POST submit-otp", { url: SELENIUM_AGENT_BASE + url, sessionId });
const r = await requestWithRetries({ url, method: "POST", data: { session_id: sessionId, otp } }, 4);
log("uniteducard-client", "submit-otp response", { status: r.status, data: r.data });
if (r.status >= 500) throw new Error(`Selenium agent server error on submit-otp: ${r.status}`);
return r.data;
}
export async function getSeleniumUnitedUcardSessionStatus(sessionId: string): Promise<any> {
const url = `/session/${sessionId}/status`;
log("uniteducard-client", "GET session status", { url: SELENIUM_AGENT_BASE + url, sessionId });
const r = await requestWithRetries({ url, method: "GET" }, 4);
log("uniteducard-client", "session status response", { status: r.status, dataKeys: r.data ? Object.keys(r.data) : null });
if (r.status === 404) {
const e: any = new Error("not_found");
e.response = { status: 404, data: r.data };
throw e;
}
return r.data;
}