app-manager-edge-worker 1.1.5 → 1.2.0

package/README.md

@@ -203,6 +203,16 @@ Log levels: `[INFO]` · `[SUCCESS]` · `[WARN]` · `[ERROR]` · `[TASK]` (job di
 
 ## 📝 Changelog
 
+### v1.2.0
+- **Human-In-The-Loop (HITL) Interactive Scraping Engine**:
+  - Added stateful interactive session handlers: `HITL_SESSION_INIT`, `HITL_SESSION_REFRESH`, `HITL_SESSION_SOLVE`, and `HITL_SESSION_ABORT`.
+  - Automated form field pre-filling (GSTIN, PAN, registration numbers) with clear-first input semantics.
+  - Direct DOM element screenshotting for precise visual captcha capture (`imageSelector`).
+  - MD5 visual pixel hash comparison and DOM `src` watcher for guaranteed captcha refresh verification.
+  - Post-submit dual-outcome race between success selectors and in-page error messages (handling HTTP 200 responses with error banners).
+  - Fast-retry loop: on invalid captcha entry, preserves active browser page, resets TTL timer, and captures newly regenerated captcha without restarting form from scratch.
+  - Resource protection with active session maps and configurable TTL auto-close timers to prevent worker memory leaks.
+
 ### v1.1.5
 - **Real-Time WhatsApp Task & Document Streaming Telemetry**:
   - Added timestamped terminal logging for incoming WhatsApp text and document task receipts.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "app-manager-edge-worker",
-  "version": "1.1.5",
+  "version": "1.2.0",
   "description": "Distributed Scraper Edge Worker for Apps Manager. Run on any local machine, VPS, or Termux Android device to serve browser and HTTP scraping jobs.",
   "type": "module",
   "bin": {

package/src/banner.js

@@ -1,7 +1,7 @@
 import { createRequire } from "module";
 
 const require = createRequire(import.meta.url);
-let workerVersion = "1.1.5";
+let workerVersion = "1.2.0";
 try {
     const pkg = require("../package.json");
     if (pkg?.version) workerVersion = pkg.version;

package/src/client.js

@@ -8,11 +8,17 @@ import { handleChromiumScrape, handleHttpScrape } from "./handlers/scrapeHandler
 import { handlePreviewPage, handleInspectElement } from "./handlers/previewHandler.js";
 import { handleSendEmail } from "./handlers/mailHandler.js";
 import { handleAiSmartRepair } from "./handlers/aiRepairHandler.js";
+import {
+    handleInteractiveSessionInit,
+    handleInteractiveSessionRefresh,
+    handleInteractiveSessionSolve,
+    handleInteractiveSessionAbort,
+} from "./handlers/interactiveHandler.js";
 import fs from "fs";
 import { getWhatsAppHandler } from "./handlers/whatsappHandler.js";
 import { printBanner, logInfo, logSuccess, logWarn, logError, logJob } from "./banner.js";
 
-let workerPkgVersion = "1.1.5";
+let workerPkgVersion = "1.2.0";
 try {
     const pkg = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
     if (pkg?.version) workerPkgVersion = pkg.version;
@@ -249,6 +255,14 @@ export async function startWorkerClient(config) {
                 resultData = await waHandler.sendDocument(payload);
             } else if (jobType === "WHATSAPP_RECONCILE") {
                 resultData = await waHandler.reconcileDelivery(payload.recipientPhone, payload.idempotencyKey);
+            } else if (jobType === "HITL_SESSION_INIT") {
+                resultData = await handleInteractiveSessionInit(payload);
+            } else if (jobType === "HITL_SESSION_REFRESH") {
+                resultData = await handleInteractiveSessionRefresh(payload);
+            } else if (jobType === "HITL_SESSION_SOLVE") {
+                resultData = await handleInteractiveSessionSolve(payload);
+            } else if (jobType === "HITL_SESSION_ABORT") {
+                resultData = await handleInteractiveSessionAbort(payload);
             } else {
                 throw new Error(`Unsupported job type: ${jobType}`);
             }

package/src/handlers/interactiveHandler.js

@@ -0,0 +1,466 @@
+import crypto from "crypto";
+import localBrowserManager from "../browser.js";
+import { runTransformPipeline, castValueToType } from "./transformUtils.js";
+
+/**
+ * In-memory map of active interactive sessions on this Edge Worker.
+ * sessionId -> { page, timeoutTimer, createdAt, url, captchaConfig, fieldMappings, collections }
+ */
+const activeSessions = new Map();
+
+/**
+ * Extracts a single field from a Puppeteer page given a strategy.
+ */
+async function extractBrowserField(page, strategy) {
+    if (!strategy || !strategy.value) return null;
+
+    try {
+        const type = strategy.type || "css";
+        const attr = strategy.attribute || "text";
+
+        if (type === "css") {
+            const el = await page.$(strategy.value);
+            if (!el) return null;
+
+            if (attr === "text") {
+                const text = await page.evaluate((element) => element.textContent, el);
+                return text ? text.trim() : null;
+            } else if (attr === "html") {
+                return await page.evaluate((element) => element.innerHTML, el);
+            } else {
+                const val = await page.evaluate((element, a) => element.getAttribute(a), el, attr);
+                return val !== null && val !== undefined ? String(val).trim() : null;
+            }
+        }
+
+        if (type === "xpath") {
+            const val = await page.evaluate(
+                (xpathStr, attrName) => {
+                    try {
+                        const result = document.evaluate(
+                            xpathStr,
+                            document,
+                            null,
+                            XPathResult.FIRST_ORDERED_NODE_TYPE,
+                            null
+                        );
+                        const node = result.singleNodeValue;
+                        if (!node) return null;
+                        if (attrName === "text") {
+                            return node.textContent ? node.textContent.trim() : null;
+                        }
+                        return node.getAttribute ? node.getAttribute(attrName) : null;
+                    } catch (e) {
+                        return null;
+                    }
+                },
+                strategy.value,
+                attr
+            );
+            return val;
+        }
+
+        return null;
+    } catch (_) {
+        return null;
+    }
+}
+
+/**
+ * Closes and purges an interactive session safely.
+ */
+async function purgeSession(sessionId) {
+    const session = activeSessions.get(sessionId);
+    if (!session) return;
+
+    if (session.timeoutTimer) {
+        clearTimeout(session.timeoutTimer);
+    }
+
+    try {
+        if (session.page && !session.page.isClosed()) {
+            await session.page.close().catch(() => {});
+        }
+    } catch (_) {}
+
+    activeSessions.delete(sessionId);
+}
+
+/**
+ * 1. Handles HITL_SESSION_INIT:
+ *    Launches page, pre-fills initial form inputs, captures captcha screenshot,
+ *    and keeps the page alive with an auto-close TTL timer.
+ */
+export async function handleInteractiveSessionInit(payload) {
+    const {
+        sessionId,
+        url,
+        formInputs = [],
+        captchaConfig = {},
+        preScrapeActions = [],
+        authentication = null,
+        timeoutMs = 30000,
+        fieldMappings = [],
+        collections = [],
+    } = payload;
+
+    if (!sessionId || !url) {
+        throw new Error("sessionId and url are required for HITL_SESSION_INIT");
+    }
+
+    // Clean up any existing session with this ID
+    if (activeSessions.has(sessionId)) {
+        await purgeSession(sessionId);
+    }
+
+    const browser = await localBrowserManager.getBrowser();
+    const page = await browser.newPage();
+
+    try {
+        await page.setViewport({ width: 1366, height: 900, deviceScaleFactor: 1 });
+
+        // Apply authentication headers or cookies if provided
+        if (authentication) {
+            if (authentication.type === "COOKIES" && Array.isArray(authentication.cookies)) {
+                const parsedUrl = new URL(url);
+                await page
+                    .setCookie(
+                        ...authentication.cookies.map((c) => ({
+                            name: c.name,
+                            value: c.value,
+                            domain: c.domain || parsedUrl.hostname,
+                            path: c.path || "/",
+                        }))
+                    )
+                    .catch(() => {});
+            }
+            if (authentication.type === "HEADERS" && authentication.headers) {
+                await page.setExtraHTTPHeaders(authentication.headers).catch(() => {});
+            }
+        }
+
+        // Navigate to target portal
+        await page.goto(url, { waitUntil: "domcontentloaded", timeout: timeoutMs });
+        try {
+            await page.waitForNetworkIdle({ idleTime: 500, timeout: 3500 }).catch(() => {});
+        } catch (_) {}
+
+        // Execute pre-scrape actions if present
+        if (Array.isArray(preScrapeActions) && preScrapeActions.length > 0) {
+            for (const action of preScrapeActions) {
+                try {
+                    const actType = (action.type || action.actionType || "").toUpperCase();
+                    if (actType === "CLICK" && action.selector) {
+                        await page.waitForSelector(action.selector, { timeout: action.timeoutMs || 4000 });
+                        await page.click(action.selector);
+                    } else if (actType === "TYPE" && action.selector) {
+                        await page.waitForSelector(action.selector, { timeout: action.timeoutMs || 4000 });
+                        await page.type(action.selector, action.value || "", { delay: 30 });
+                    } else if (actType === "WAIT_FOR" && action.selector) {
+                        await page.waitForSelector(action.selector, { timeout: action.timeoutMs || 8000 });
+                    }
+                    if (action.delayMs > 0) {
+                        await new Promise((r) => setTimeout(r, Math.min(action.delayMs, 4000)));
+                    }
+                } catch (actErr) {
+                    if (action.optional === false) throw actErr;
+                }
+            }
+        }
+
+        // Fill Form Inputs (e.g. GSTIN, PAN, registration number)
+        if (Array.isArray(formInputs) && formInputs.length > 0) {
+            for (const input of formInputs) {
+                if (!input.selector || input.value === undefined || input.value === null) continue;
+                await page.waitForSelector(input.selector, { timeout: 6000 });
+
+                if (input.clearFirst !== false) {
+                    await page.click(input.selector, { clickCount: 3 }).catch(() => {});
+                    await page.keyboard.press("Backspace").catch(() => {});
+                }
+
+                if (input.actionType === "SELECT") {
+                    await page.select(input.selector, String(input.value));
+                } else {
+                    await page.type(input.selector, String(input.value), { delay: input.delayMs || 30 });
+                }
+
+                await new Promise((r) => setTimeout(r, 150));
+            }
+        }
+
+        // Locate and Screenshot Captcha DOM Element
+        const imageSelector = captchaConfig.imageSelector || "img[src*='captcha'], #imgCaptcha, #captchaImg";
+        await page.waitForSelector(imageSelector, { timeout: 8000 });
+
+        const captchaElement = await page.$(imageSelector);
+        if (!captchaElement) {
+            throw new Error(`Captcha element not found with selector: ${imageSelector}`);
+        }
+
+        // Capture screenshot of the exact visual captcha DOM node
+        const screenshotBuffer = await captchaElement.screenshot({
+            encoding: "binary",
+            type: "png",
+        });
+        const imageBase64 = Buffer.from(screenshotBuffer).toString("base64");
+
+        const sessionTtlSeconds = captchaConfig.sessionTimeoutSeconds || 90;
+
+        // Set auto-purge timer to prevent resource leaks
+        const timeoutTimer = setTimeout(() => {
+            purgeSession(sessionId).catch(() => {});
+        }, sessionTtlSeconds * 1000);
+
+        // Store active session in memory
+        activeSessions.set(sessionId, {
+            page,
+            timeoutTimer,
+            createdAt: Date.now(),
+            url,
+            captchaConfig,
+            fieldMappings,
+            collections,
+        });
+
+        return {
+            sessionId,
+            imageBase64: `data:image/png;base64,${imageBase64}`,
+            expiresInSeconds: sessionTtlSeconds,
+        };
+    } catch (err) {
+        await page.close().catch(() => {});
+        throw err;
+    }
+}
+
+/**
+ * 2. Handles HITL_SESSION_REFRESH:
+ *    Clicks the refresh button and verifies the visual MD5 hash of the captcha changed.
+ */
+export async function handleInteractiveSessionRefresh(payload) {
+    const { sessionId, captchaConfig = {} } = payload;
+    const session = activeSessions.get(sessionId);
+
+    if (!session || !session.page || session.page.isClosed()) {
+        throw new Error("Interactive session not found or already expired");
+    }
+
+    const { page } = session;
+    const cfg = { ...session.captchaConfig, ...captchaConfig };
+    const imageSelector = cfg.imageSelector || "img[src*='captcha'], #imgCaptcha";
+    const refreshSelector = cfg.refreshSelector;
+
+    if (!refreshSelector) {
+        throw new Error("refreshSelector is not configured for this captcha");
+    }
+
+    // 1. Snapshot current image hash and src attribute
+    const oldEl = await page.$(imageSelector);
+    if (!oldEl) {
+        throw new Error(`Captcha element not found with selector: ${imageSelector}`);
+    }
+
+    const oldBuffer = await oldEl.screenshot({ encoding: "binary" });
+    const oldHash = crypto.createHash("md5").update(oldBuffer).digest("hex");
+
+    const oldSrc = await page.evaluate((sel) => {
+        const el = document.querySelector(sel);
+        return el ? el.getAttribute("src") : null;
+    }, imageSelector);
+
+    // 2. Click the reload button
+    await page.waitForSelector(refreshSelector, { timeout: 3000 });
+    await page.click(refreshSelector);
+
+    // 3. Wait for src attribute change first
+    await page
+        .waitForFunction(
+            (sel, prevSrc) => {
+                const el = document.querySelector(sel);
+                return el && el.getAttribute("src") !== prevSrc;
+            },
+            { timeout: 3500 },
+            imageSelector,
+            oldSrc
+        )
+        .catch(() => {});
+
+    // 4. Verify visual pixel change via MD5 hash check
+    let newBuffer = null;
+    let retries = 0;
+
+    while (retries < 6) {
+        await new Promise((r) => setTimeout(r, 350));
+        const newEl = await page.$(imageSelector);
+        if (newEl) {
+            newBuffer = await newEl.screenshot({ encoding: "binary" });
+            const newHash = crypto.createHash("md5").update(newBuffer).digest("hex");
+            if (newHash !== oldHash) {
+                break; // Verified fresh captcha
+            }
+        }
+        retries++;
+    }
+
+    if (!newBuffer) {
+        newBuffer = await oldEl.screenshot({ encoding: "binary" });
+    }
+
+    const imageBase64 = Buffer.from(newBuffer).toString("base64");
+    return {
+        sessionId,
+        imageBase64: `data:image/png;base64,${imageBase64}`,
+    };
+}
+
+/**
+ * 3. Handles HITL_SESSION_SOLVE:
+ *    Types the captcha solution, clicks submit, and performs a post-submit race.
+ *    If captcha is invalid, keeps session alive and snaps new captcha for retry.
+ *    If success, extracts data and closes page.
+ */
+export async function handleInteractiveSessionSolve(payload) {
+    const { sessionId, captchaSolution, captchaConfig = {}, fieldMappings = [], collections = [] } = payload;
+    const session = activeSessions.get(sessionId);
+
+    if (!session || !session.page || session.page.isClosed()) {
+        throw new Error("Interactive session not found or already expired");
+    }
+
+    const { page } = session;
+    const cfg = { ...session.captchaConfig, ...captchaConfig };
+    const mappings = fieldMappings.length > 0 ? fieldMappings : session.fieldMappings || [];
+    const colls = collections.length > 0 ? collections : session.collections || [];
+
+    const inputSelector = cfg.inputSelector || "#captcha, input[name='captcha']";
+    const submitSelector = cfg.submitSelector || "button[type='submit']";
+    const successSelector = cfg.waitForAfterSubmit?.selector || ".table-responsive, table, .result-pane";
+    const errorSelector = cfg.errorDetection?.selector || ".alert-danger, .has-error, #error-msg, .ui-messages-error";
+    const invalidPattern = cfg.errorDetection?.invalidCaptchaPattern || "captcha.*(incorrect|invalid|wrong|mismatch|enter text)";
+
+    // 1. Type captcha solution
+    await page.waitForSelector(inputSelector, { timeout: 4000 });
+    await page.click(inputSelector, { clickCount: 3 }).catch(() => {});
+    await page.keyboard.press("Backspace").catch(() => {});
+    await page.type(inputSelector, String(captchaSolution).trim(), { delay: 35 });
+
+    // 2. Click submit button
+    await page.waitForSelector(submitSelector, { timeout: 4000 });
+    await page.click(submitSelector);
+
+    // 3. Post-Submit Race: Wait for Success Selector OR Error Selector
+    const matchedOutcome = await page
+        .waitForFunction(
+            (succ, err) => {
+                if (document.querySelector(succ)) return "SUCCESS";
+                const errEl = document.querySelector(err);
+                if (errEl && errEl.innerText && errEl.innerText.trim().length > 0) return "ERROR";
+                return null;
+            },
+            { timeout: cfg.waitForAfterSubmit?.timeoutMs || 15000 },
+            successSelector,
+            errorSelector
+        )
+        .then((handle) => handle.jsonValue())
+        .catch(() => "TIMEOUT");
+
+    // Case A: Success Result Page
+    if (matchedOutcome === "SUCCESS") {
+        const raw = {};
+        for (const mapping of mappings) {
+            let val = null;
+            const strategies = mapping.strategies || (mapping.strategy ? [mapping.strategy] : []);
+            for (const strat of strategies) {
+                val = await extractBrowserField(page, strat);
+                if (val !== null && val !== undefined && val !== "") break;
+            }
+
+            if (mapping.transforms && mapping.transforms.length > 0) {
+                val = runTransformPipeline(val, mapping.transforms);
+            }
+            if (mapping.type) {
+                val = castValueToType(val, mapping.type);
+            }
+            raw[mapping.field || mapping.key] = val;
+        }
+
+        // Clean up session and close page
+        await purgeSession(sessionId);
+
+        return {
+            status: "COMPLETED",
+            success: true,
+            data: raw,
+        };
+    }
+
+    // Case B: In-Page Error Banner Detected
+    if (matchedOutcome === "ERROR") {
+        const errorText = await page.evaluate((sel) => {
+            const el = document.querySelector(sel);
+            return el ? el.innerText.trim() : "";
+        }, errorSelector);
+
+        const regex = new RegExp(invalidPattern, "i");
+        const isCaptchaError = regex.test(errorText);
+
+        if (isCaptchaError) {
+            // Keep page alive! Reset TTL timer for retry
+            if (session.timeoutTimer) clearTimeout(session.timeoutTimer);
+            const retryTtlSeconds = cfg.sessionTimeoutSeconds || 90;
+            session.timeoutTimer = setTimeout(() => {
+                purgeSession(sessionId).catch(() => {});
+            }, retryTtlSeconds * 1000);
+
+            // Give the target portal 400ms to re-render the refreshed captcha image
+            await new Promise((r) => setTimeout(r, 400));
+            const imageSelector = cfg.imageSelector || "img[src*='captcha'], #imgCaptcha";
+            const newCaptchaEl = await page.$(imageSelector);
+            let newImageBase64 = null;
+
+            if (newCaptchaEl) {
+                const newBuffer = await newCaptchaEl.screenshot({ encoding: "binary", type: "png" });
+                newImageBase64 = `data:image/png;base64,${Buffer.from(newBuffer).toString("base64")}`;
+            }
+
+            return {
+                status: "INVALID_CAPTCHA",
+                success: false,
+                message: errorText || "The captcha entered was incorrect.",
+                canRetry: true,
+                newImageBase64,
+            };
+        } else {
+            // Business error (e.g. "No record found for this number")
+            await purgeSession(sessionId);
+            return {
+                status: "BUSINESS_ERROR",
+                success: false,
+                message: errorText || "Target portal returned an error.",
+                canRetry: false,
+            };
+        }
+    }
+
+    // Case C: Timeout
+    await purgeSession(sessionId);
+    return {
+        status: "TIMEOUT",
+        success: false,
+        message: "Target portal did not respond with results within the expected time window.",
+        canRetry: false,
+    };
+}
+
+/**
+ * 4. Handles HITL_SESSION_ABORT:
+ *    Explicit client abort or session abandonment.
+ */
+export async function handleInteractiveSessionAbort(payload) {
+    const { sessionId } = payload;
+    if (sessionId) {
+        await purgeSession(sessionId);
+    }
+    return { success: true, aborted: true };
+}