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>

apps/Backend/src/routes/index.ts

@@ -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);

apps/Backend/src/routes/insuranceStatusUnitedUcard.ts

@@ -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;