feat: add BCBS MA eligibility check with OTP flow

- New Selenium worker (fresh Chrome per run, no persistent session)
  login → OTP modal → eTools → ConnectCenter → Verification →
  New Eligibility Request → fill form (NPI, member ID, DOB) →
  Expand All → CDP PDF back to app
- Backend route fetches BCBS_MA credentials + provider NPI from settings
- Frontend OTP modal with 6-digit code entry
- BCBS MA added to insurance credentials dropdown in settings

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

apps/Backend/src/queue/jobRunner.ts

@@ -23,6 +23,7 @@ import { runUnitedDHClaimProcessor } from "./processors/unitedDHClaimProcessor";
 import { runTuftsSCOClaimProcessor } from "./processors/tuftsSCOClaimProcessor";
 import { runEligibilityHistoryProcessor } from "./processors/eligibilityHistoryProcessor";
 import { runCmspEligibilityHistoryRemainingProcessor } from "./processors/cmspEligibilityHistoryRemainingProcessor";
+import { runBcbsMaEligibilityProcessor } from "./processors/bcbsMaEligibilityProcessor";
 import type { SeleniumJobData, OcrJobData } from "./queues";
 
 // ── Queue instances ──────────────────────────────────────────────────────────
@@ -226,6 +227,20 @@ export function enqueueSeleniumJob(data: SeleniumJobData): string {
         formDob: data.formDob,
       });
     }
+    if (jobType === "bcbs-ma-eligibility-check") {
+      return runBcbsMaEligibilityProcessor(
+        {
+          enrichedPayload: data.enrichedPayload,
+          userId: data.userId,
+          insuranceId: data.insuranceId!,
+          formFirstName: data.formFirstName,
+          formLastName: data.formLastName,
+          formDob: data.formDob,
+          socketId: data.socketId,
+        },
+        job.id
+      );
+    }
     throw new Error(`Unknown selenium jobType: ${jobType}`);
   });
 

apps/Backend/src/queue/processors/bcbsMaEligibilityProcessor.ts

@@ -0,0 +1,255 @@
+import fs from "fs/promises";
+import fsSync from "fs";
+import path from "path";
+import { storage } from "../../storage";
+import { emptyFolderContainingFile } from "../../utils/emptyTempFolder";
+import {
+  forwardToSeleniumBcbsMaEligibilityAgent,
+  getSeleniumBcbsMaSessionStatus,
+} from "../../services/seleniumBcbsMaInsuranceEligibilityClient";
+import { splitName, createOrUpdatePatientByInsuranceId } from "./_shared";
+import { io } from "../../socket";
+
+function log(tag: string, msg: string, ctx?: any) {
+  console.log(`${new Date().toISOString()} [${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);
+  } catch (err: any) {
+    log("bcbs-ma-processor", `emit failed for ${event}`, { err: err?.message });
+  }
+}
+
+export interface BcbsMaEligibilityProcessorInput {
+  enrichedPayload: any;
+  userId: number;
+  insuranceId: string;
+  formFirstName?: string;
+  formLastName?: string;
+  formDob?: string;
+  socketId?: string;
+}
+
+export interface BcbsMaEligibilityProcessorResult {
+  patientUpdateStatus?: string;
+  pdfUploadStatus?: string;
+  pdfFileId?: number | null;
+  pdfFilename?: string | null;
+}
+
+async function processBcbsMaResult(
+  userId: number,
+  insuranceId: string,
+  formFirstName: string | undefined,
+  formLastName: string | undefined,
+  formDob: string | undefined,
+  seleniumResult: any
+): Promise<BcbsMaEligibilityProcessorResult> {
+  const output: BcbsMaEligibilityProcessorResult = {};
+  let createdPdfFileId: number | null = null;
+
+  try {
+    // Resolve patient name
+    const rawName =
+      typeof seleniumResult?.patientName === "string" ? seleniumResult.patientName.trim() : null;
+
+    let firstName: string;
+    let lastName: string;
+
+    if (rawName) {
+      if (rawName.includes(",")) {
+        const [last, ...firstParts] = rawName.split(",").map((s: string) => s.trim());
+        lastName = last || formLastName || "";
+        firstName = firstParts.join(" ").trim() || formFirstName || "";
+      } else {
+        const parsed = splitName(rawName);
+        if (!parsed.lastName) {
+          lastName = parsed.firstName || formLastName || "";
+          firstName = formFirstName || "";
+        } else {
+          firstName = parsed.firstName || formFirstName || "";
+          lastName = parsed.lastName || formLastName || "";
+        }
+      }
+    } else {
+      firstName = formFirstName ?? "";
+      lastName = formLastName ?? "";
+    }
+
+    await createOrUpdatePatientByInsuranceId({ insuranceId, firstName, lastName, dob: formDob, userId });
+
+    const normalizedInsuranceId = insuranceId.replace(/\s+/g, "");
+    const patient = await storage.getPatientByInsuranceId(normalizedInsuranceId);
+    if (!patient?.id) {
+      output.patientUpdateStatus = "Patient not found; no update performed";
+      return output;
+    }
+
+    const eligStatus = (seleniumResult?.eligibility ?? "").toLowerCase();
+    const newStatus =
+      eligStatus === "eligible" || eligStatus === "active" ? "ACTIVE" : "INACTIVE";
+    await storage.updatePatient(patient.id, {
+      status: newStatus,
+      insuranceProvider: "BCBS MA",
+    });
+    output.patientUpdateStatus = `Patient status updated to ${newStatus}`;
+
+    // Save PDF
+    let pdfBuffer: Buffer | null = null;
+    let pdfFilename: string | null = null;
+    const pdfPath: string | null = seleniumResult?.pdf_path ?? null;
+
+    if (pdfPath && fsSync.existsSync(pdfPath)) {
+      try {
+        pdfBuffer = await fs.readFile(pdfPath);
+        pdfFilename = path.basename(pdfPath);
+      } catch (e: any) {
+        output.pdfUploadStatus = `Failed to read PDF: ${e.message}`;
+      }
+    } else {
+      output.pdfUploadStatus = "No valid PDF path from Selenium.";
+    }
+
+    if (pdfBuffer && pdfFilename) {
+      const groupTitleKey = "ELIGIBILITY_STATUS";
+      const groupTitle = "Eligibility Status";
+      let group = await storage.findPdfGroupByPatientTitleKey(patient.id, groupTitleKey);
+      if (!group) group = await storage.createPdfGroup(patient.id, groupTitle, groupTitleKey);
+      if (!group?.id) throw new Error("PDF group creation failed");
+      const created = await storage.createPdfFile(group.id, pdfFilename, pdfBuffer);
+      if (created && typeof created === "object" && "id" in created) {
+        createdPdfFileId = Number(created.id);
+      }
+      output.pdfUploadStatus = `PDF saved to group: ${group.title}`;
+      output.pdfFilename = pdfFilename;
+    }
+
+    output.pdfFileId = createdPdfFileId;
+    return output;
+  } catch (err: any) {
+    log("bcbs-ma-processor", `processBcbsMaResult ERROR: ${err?.message}`, err);
+    return {
+      ...output,
+      pdfUploadStatus: output.pdfUploadStatus ?? `Processing failed: ${err?.message}`,
+      pdfFileId: createdPdfFileId,
+    };
+  } finally {
+    const cleanupPath = seleniumResult?.pdf_path ?? null;
+    if (cleanupPath) {
+      try {
+        await emptyFolderContainingFile(cleanupPath);
+      } catch (_) {}
+    }
+  }
+}
+
+async function pollUntilDone(
+  sessionId: string,
+  socketId: string | undefined,
+  jobId: string,
+  pollTimeoutMs = 8 * 60 * 1000  // 8 min — accounts for fresh login + OTP wait
+): Promise<any> {
+  const maxAttempts = 960;  // 960 × 500ms = 8 min
+  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(`BCBS MA polling timeout (${Math.round(pollTimeoutMs / 1000)}s) for session ${sessionId}`);
+    }
+
+    try {
+      const st = await getSeleniumBcbsMaSessionStatus(sessionId);
+      const status: string = st?.status ?? "unknown";
+      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 6-digit code from the BCBS MA email.",
+        });
+        await new Promise((r) => setTimeout(r, pollIntervalMs));
+        continue;
+      }
+
+      if (status === "completed") return st.result;
+
+      if (status === "error" || status === "not_found") {
+        throw new Error(st?.message || `BCBS MA 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 BCBS MA session ${sessionId}`);
+      }
+      const backoff = Math.min(30_000, 500 * Math.pow(2, transientErrors - 1));
+      await new Promise((r) => setTimeout(r, backoff));
+    }
+  }
+
+  throw new Error(`BCBS MA polling exhausted all attempts for session ${sessionId}`);
+}
+
+export async function runBcbsMaEligibilityProcessor(
+  input: BcbsMaEligibilityProcessorInput,
+  jobId: string
+): Promise<BcbsMaEligibilityProcessorResult> {
+  const { enrichedPayload, userId, insuranceId, formFirstName, formLastName, formDob, socketId } = input;
+
+  log("bcbs-ma-processor", "starting Python agent session", { insuranceId });
+  const agentResp = await forwardToSeleniumBcbsMaEligibilityAgent(enrichedPayload);
+
+  if (!agentResp?.session_id) {
+    throw new Error("Python agent did not return a session_id for BCBS MA eligibility");
+  }
+
+  const sessionId = agentResp.session_id as string;
+  log("bcbs-ma-processor", "got session_id", { sessionId });
+
+  emitToSocket(socketId, "selenium:bcbs_ma_session_started", { session_id: sessionId, jobId });
+
+  const seleniumResult = await pollUntilDone(sessionId, socketId, jobId);
+
+  if (!seleniumResult || seleniumResult.status === "error") {
+    throw new Error(seleniumResult?.message ?? "BCBS MA session returned an error result");
+  }
+
+  log("bcbs-ma-processor", "processing DB result", { insuranceId });
+  const result = await processBcbsMaResult(
+    userId, insuranceId, formFirstName, formLastName, formDob, seleniumResult
+  );
+
+  log("bcbs-ma-processor", "done", { result });
+  return result;
+}

apps/Backend/src/queue/queues.ts

@@ -18,7 +18,8 @@ export type SeleniumJobType =
   | "uniteddh-claim-submit"
   | "tuftssco-eligibility-check"
   | "mh-eligibility-history-check"
-  | "cmsp-eligibility-history-remaining-check";
+  | "cmsp-eligibility-history-remaining-check"
+  | "bcbs-ma-eligibility-check";
 
 export interface SeleniumJobData {
   jobType: SeleniumJobType;

apps/Backend/src/routes/index.ts

@@ -40,6 +40,7 @@ import commissionsRoutes from "./commissions";
 import shoppingVendorsRoutes from "./shopping-vendors";
 import feeScheduleRoutes from "./feeSchedule";
 import licenseRoutes from "./license";
+import insuranceStatusBcbsMaRoutes from "./insuranceStatusBcbsMa";
 
 const router = Router();
 
@@ -60,6 +61,7 @@ router.use("/insurance-status-deltains", insuranceStatusDeltaInsRoutes);
 router.use("/insurance-status-unitedsco", insuranceStatusUnitedSCORoutes);
 router.use("/insurance-status-tuftssco", insuranceStatusTuftsSCORoutes);
 router.use("/insurance-status-cca", insuranceStatusCCARoutes);
+router.use("/insurance-status-bcbs-ma", insuranceStatusBcbsMaRoutes);
 router.use("/claims", insuranceStatusCCAClaimRoutes);
 router.use("/claims", insuranceStatusCCAPreAuthRoutes);
 router.use("/claims", insuranceStatusDDMAClaimRoutes);

apps/Backend/src/routes/insuranceStatusBcbsMa.ts

@@ -0,0 +1,108 @@
+import { Router, Request, Response } from "express";
+import { storage } from "../storage";
+import { forwardOtpToSeleniumBcbsMaAgent } from "../services/seleniumBcbsMaInsuranceEligibilityClient";
+import { io } from "../socket";
+import { enqueueSeleniumJob } from "../queue/jobRunner";
+
+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("bcbs-ma-route", "emit failed", { socketId, event, err: err?.message });
+  }
+}
+
+/**
+ * POST /bcbs-ma-eligibility
+ * Enqueues a BCBS MA eligibility check.
+ * Body: { data: { memberId, dateOfBirth, firstName, lastName, insuranceSiteKey }, socketId }
+ */
+router.post("/bcbs-ma-eligibility", async (req: Request, res: Response): Promise<any> => {
+  if (!req.body.data) {
+    return res.status(400).json({ error: "Missing data for BCBS MA eligibility check" });
+  }
+  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;
+
+    const credentials = await storage.getInsuranceCredentialByUserAndSiteKey(req.user.id, "BCBS_MA");
+    if (!credentials) {
+      return res.status(404).json({
+        error: "No BCBS MA credentials found. Please add them in Settings → Insurance Credentials.",
+      });
+    }
+
+    // Fetch provider NPI — use the first one on file for this user
+    const npiProviders = await storage.getNpiProvidersByUser(req.user.id);
+    const npiNumber = npiProviders?.[0]?.npiNumber ?? "";
+    if (!npiNumber) {
+      return res.status(404).json({
+        error: "No NPI provider found. Please add one in Settings → NPI Providers.",
+      });
+    }
+
+    const enrichedData = {
+      ...rawData,
+      bcbsMaUsername: credentials.username,
+      bcbsMaPassword: credentials.password,
+      providerNpi: npiNumber,
+    };
+
+    const socketId: string | undefined = req.body.socketId;
+
+    const jobId = enqueueSeleniumJob({
+      jobType: "bcbs-ma-eligibility-check",
+      userId: req.user.id,
+      socketId,
+      enrichedPayload: enrichedData,
+      insuranceId: String(rawData.memberId ?? "").trim(),
+      formFirstName: rawData.firstName,
+      formLastName: rawData.lastName,
+      formDob: rawData.dateOfBirth,
+    });
+
+    log("bcbs-ma-route", "job enqueued", { jobId, insuranceId: rawData.memberId });
+    return res.json({ status: "queued", jobId });
+  } catch (err: any) {
+    console.error("[bcbs-ma-route] enqueue failed:", err);
+    return res.status(500).json({ error: err.message || "Failed to enqueue BCBS MA selenium job" });
+  }
+});
+
+/**
+ * POST /selenium/submit-otp
+ * Forwards the OTP to the Python agent (side-channel, bypasses 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 forwardOtpToSeleniumBcbsMaAgent(sessionId, otp);
+    emitSafe(socketId, "selenium:otp_submitted", { session_id: sessionId, result: r });
+    return res.json(r);
+  } catch (err: any) {
+    console.error("[bcbs-ma-route] submit-otp failed:", err?.message || err);
+    return res.status(500).json({
+      error: "Failed to forward OTP to selenium agent",
+      detail: err?.message || err,
+    });
+  }
+});
+
+export default router;

apps/Backend/src/services/seleniumBcbsMaInsuranceEligibilityClient.ts

@@ -0,0 +1,67 @@
+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;
+    } catch (err: any) {
+      const code = err?.code;
+      const isTransient =
+        code === "ECONNRESET" || code === "ECONNREFUSED" || code === "EPIPE" || code === "ETIMEDOUT";
+      if (!isTransient) throw err;
+    }
+    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 forwardToSeleniumBcbsMaEligibilityAgent(data: any): Promise<any> {
+  const payload = { data };
+  log("bcbs-ma-client", "POST bcbs-ma-eligibility", { keys: Object.keys(payload) });
+  const r = await requestWithRetries({ url: "/bcbs-ma-eligibility", method: "POST", data: payload }, 4);
+  log("bcbs-ma-client", "agent response", { status: r.status });
+  if (r.status >= 500) throw new Error(`Selenium agent server error: ${r.status}`);
+  return r.data;
+}
+
+export async function forwardOtpToSeleniumBcbsMaAgent(sessionId: string, otp: string): Promise<any> {
+  log("bcbs-ma-client", "POST submit-otp", { sessionId });
+  const r = await requestWithRetries(
+    { url: "/submit-otp", method: "POST", data: { session_id: sessionId, otp } },
+    4
+  );
+  if (r.status >= 500) throw new Error(`Selenium agent server error on submit-otp: ${r.status}`);
+  return r.data;
+}
+
+export async function getSeleniumBcbsMaSessionStatus(sessionId: string): Promise<any> {
+  const r = await requestWithRetries({ url: `/session/${sessionId}/status`, method: "GET" }, 4);
+  if (r.status === 404) {
+    const e: any = new Error("not_found");
+    e.response = { status: 404, data: r.data };
+    throw e;
+  }
+  return r.data;
+}