app-manager-edge-worker 1.2.2 → 1.2.5

package/README.md

@@ -201,7 +201,22 @@ Log levels: `[INFO]` · `[SUCCESS]` · `[WARN]` · `[ERROR]` · `[TASK]` (job di
 
 ---
 
-## 📝 Changelog
+### v1.2.5
+- **Interactive Session Visual Inspector Sync & Robust Captcha Refresh**:
+  - `HITL_SESSION_INIT` now captures and returns full-page `pageScreenshotBase64`, dimensions, and title after typing initial form inputs, keeping the Visual Element Inspector synchronized with the active session.
+  - Enhanced `HITL_SESSION_REFRESH` with multi-selector fallback candidates (`button[ng-click*="refreshCaptcha"]`, `button[ng-click*="captcha"]`, `#reloadCaptcha`, etc.) ensuring reliable refresh on AngularJS and custom portal architectures.
+  - Captures and returns updated `pageScreenshotBase64` upon captcha refresh to keep inspect canvas up to date.
+
+### v1.2.4
+- **Preserved Live Inspection & Field Extraction on Results Pages**:
+  - Added `preservePageForInspection` capability to `HITL_SESSION_SOLVE`: keeps Puppeteer browser page alive upon successful captcha solve and returns full-page Results Page screenshot with dimensions and metadata.
+  - Linked active interactive sessions directly to `INSPECT_ELEMENT`: enables clicking and resolving exact selectors on the live Results Page without reloading or losing post-submit DOM state.
+  - Added `HITL_SESSION_EXTRACT` job handler to test and evaluate field mappings and transforms directly against the active Results Page in real-time.
+
+### v1.2.3
+- **Resilient Dynamic Attachment Streaming**:
+  - Implemented automatic loopback host and port reconciliation for WhatsApp document streaming (`WHATSAPP_SEND_DOCUMENT`).
+  - Automatically redirects loopback/localhost requests to the worker's active connected cluster address, preventing `ECONNREFUSED ::1:3000` errors when cluster port or host differs from server defaults or when worker runs remotely on mobile/VPS.
 
 ### v1.2.2
 - **Reactive Portal Form & Dynamic Captcha Reveal Compatibility**:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "app-manager-edge-worker",
-  "version": "1.2.2",
+  "version": "1.2.5",
   "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.2.2";
+let workerVersion = "1.2.5";
 try {
     const pkg = require("../package.json");
     if (pkg?.version) workerVersion = pkg.version;

package/src/client.js

@@ -13,12 +13,13 @@ import {
     handleInteractiveSessionRefresh,
     handleInteractiveSessionSolve,
     handleInteractiveSessionAbort,
+    handleInteractiveSessionExtract,
 } 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.2.2";
+let workerPkgVersion = "1.2.5";
 try {
     const pkg = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
     if (pkg?.version) workerPkgVersion = pkg.version;
@@ -122,6 +123,7 @@ export async function startWorkerClient(config) {
 
     // Initialize WhatsApp Companion Device Engine
     const waHandler = getWhatsAppHandler({
+        serverUrl: config.serverUrl || config.server,
         onStatusChange: (statusData) => {
             socket.emit("whatsapp:status_update", statusData);
         },
@@ -252,7 +254,7 @@ export async function startWorkerClient(config) {
             } else if (jobType === "WHATSAPP_SEND_MESSAGE") {
                 resultData = await waHandler.sendMessage(payload);
             } else if (jobType === "WHATSAPP_SEND_DOCUMENT") {
-                resultData = await waHandler.sendDocument(payload);
+                resultData = await waHandler.sendDocument({ ...payload, serverUrl: config.serverUrl || config.server });
             } else if (jobType === "WHATSAPP_RECONCILE") {
                 resultData = await waHandler.reconcileDelivery(payload.recipientPhone, payload.idempotencyKey);
             } else if (jobType === "HITL_SESSION_INIT") {
@@ -261,6 +263,8 @@ export async function startWorkerClient(config) {
                 resultData = await handleInteractiveSessionRefresh(payload);
             } else if (jobType === "HITL_SESSION_SOLVE") {
                 resultData = await handleInteractiveSessionSolve(payload);
+            } else if (jobType === "HITL_SESSION_EXTRACT") {
+                resultData = await handleInteractiveSessionExtract(payload);
             } else if (jobType === "HITL_SESSION_ABORT") {
                 resultData = await handleInteractiveSessionAbort(payload);
             } else {

package/src/handlers/interactiveHandler.js

@@ -8,6 +8,13 @@ import { runTransformPipeline, castValueToType } from "./transformUtils.js";
  */
 const activeSessions = new Map();
 
+/**
+ * Returns an active interactive session by ID if alive.
+ */
+export function getActiveInteractiveSession(sessionId) {
+    return activeSessions.get(sessionId) || null;
+}
+
 /**
  * Extracts a single field from a Puppeteer page given a strategy.
  */
@@ -216,6 +223,25 @@ export async function handleInteractiveSessionInit(payload) {
         });
         const imageBase64 = Buffer.from(screenshotBuffer).toString("base64");
 
+        // Settle briefly for form state & portal validation UI
+        await new Promise((r) => setTimeout(r, 400));
+
+        // Capture full-page screenshot showing the filled inputs and revealed captcha
+        const pageScreenshotBuffer = await page.screenshot({
+            encoding: "binary",
+            fullPage: false,
+            type: "jpeg",
+            quality: 85,
+        });
+        const pageScreenshotBase64 = `data:image/jpeg;base64,${Buffer.from(pageScreenshotBuffer).toString("base64")}`;
+        const title = (await page.title().catch(() => "")) || "Interactive Portal Session";
+        const dimensions = await page
+            .evaluate(() => ({
+                width: document.documentElement.scrollWidth || window.innerWidth,
+                height: document.documentElement.scrollHeight || window.innerHeight,
+            }))
+            .catch(() => ({ width: 1366, height: 900 }));
+
         const sessionTtlSeconds = captchaConfig.sessionTimeoutSeconds || 90;
 
         // Set auto-purge timer to prevent resource leaks
@@ -237,6 +263,9 @@ export async function handleInteractiveSessionInit(payload) {
         return {
             sessionId,
             imageBase64: `data:image/png;base64,${imageBase64}`,
+            pageScreenshotBase64,
+            dimensions,
+            title,
             expiresInSeconds: sessionTtlSeconds,
         };
     } catch (err) {
@@ -262,10 +291,6 @@ export async function handleInteractiveSessionRefresh(payload) {
     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) {
@@ -280,9 +305,41 @@ export async function handleInteractiveSessionRefresh(payload) {
         return el ? el.getAttribute("src") : null;
     }, imageSelector);
 
-    // 2. Click the reload button
-    await page.waitForSelector(refreshSelector, { timeout: 3000 });
-    await page.click(refreshSelector);
+    // 2. Click the reload button with robust candidate fallbacks
+    const candidateSelectors = [
+        refreshSelector,
+        "button[ng-click*='refreshCaptcha' i]",
+        "button[ng-click*='captcha' i]",
+        "*[ng-click*='refreshCaptcha' i]",
+        "*[ng-click*='captcha' i]",
+        "#reloadCaptcha",
+        "#refreshCaptcha",
+        "a[title*='refresh' i]",
+        "button[title*='refresh' i]",
+        "a[title*='reload' i]",
+        "button[title*='reload' i]",
+        ".captcha-refresh",
+        ".reload-captcha",
+        ".glyphicon-refresh",
+        "i.fa-refresh",
+        "i.fa-arrows-rotate",
+    ].filter(Boolean);
+
+    let clicked = false;
+    for (const sel of candidateSelectors) {
+        try {
+            const btn = await page.$(sel);
+            if (btn) {
+                await btn.click();
+                clicked = true;
+                break;
+            }
+        } catch (_) {}
+    }
+
+    if (!clicked) {
+        throw new Error(`Captcha refresh button not found on page (tried: ${refreshSelector || "standard reload selectors"})`);
+    }
 
     // 3. Wait for src attribute change first
     await page
@@ -319,9 +376,20 @@ export async function handleInteractiveSessionRefresh(payload) {
     }
 
     const imageBase64 = Buffer.from(newBuffer).toString("base64");
+
+    // Capture updated full page screenshot showing new captcha
+    const pageScreenshotBuffer = await page.screenshot({
+        encoding: "binary",
+        fullPage: false,
+        type: "jpeg",
+        quality: 85,
+    });
+    const pageScreenshotBase64 = `data:image/jpeg;base64,${Buffer.from(pageScreenshotBuffer).toString("base64")}`;
+
     return {
         sessionId,
         imageBase64: `data:image/png;base64,${imageBase64}`,
+        pageScreenshotBase64,
     };
 }
 
@@ -332,7 +400,14 @@ export async function handleInteractiveSessionRefresh(payload) {
  *    If success, extracts data and closes page.
  */
 export async function handleInteractiveSessionSolve(payload) {
-    const { sessionId, captchaSolution, captchaConfig = {}, fieldMappings = [], collections = [] } = payload;
+    const {
+        sessionId,
+        captchaSolution,
+        captchaConfig = {},
+        fieldMappings = [],
+        collections = [],
+        preservePageForInspection = false,
+    } = payload;
     const session = activeSessions.get(sessionId);
 
     if (!session || !session.page || session.page.isClosed()) {
@@ -396,6 +471,44 @@ export async function handleInteractiveSessionSolve(payload) {
             raw[mapping.field || mapping.key] = val;
         }
 
+        if (preservePageForInspection) {
+            // Keep the page alive for visual inspection & testing
+            if (session.timeoutTimer) clearTimeout(session.timeoutTimer);
+            const inspectTtl = 300; // 5 minutes for interactive element picking
+            session.timeoutTimer = setTimeout(() => {
+                purgeSession(sessionId).catch(() => {});
+            }, inspectTtl * 1000);
+
+            // Settle time for tables & styles
+            await new Promise((r) => setTimeout(r, 600));
+
+            const screenshotBuffer = await page.screenshot({
+                encoding: "binary",
+                fullPage: false,
+                type: "jpeg",
+                quality: 85,
+            });
+            const screenshotBase64 = Buffer.from(screenshotBuffer).toString("base64");
+            const title = await page.title().catch(() => "");
+            const dimensions = await page
+                .evaluate(() => ({
+                    width: document.documentElement.scrollWidth || window.innerWidth,
+                    height: document.documentElement.scrollHeight || window.innerHeight,
+                }))
+                .catch(() => ({ width: 1366, height: 900 }));
+
+            return {
+                status: "COMPLETED",
+                success: true,
+                data: raw,
+                screenshotBase64: `data:image/jpeg;base64,${screenshotBase64}`,
+                dimensions,
+                title: title || "Results Page",
+                sessionId,
+                isInspectionMode: true,
+            };
+        }
+
         // Clean up session and close page
         await purgeSession(sessionId);
 
@@ -475,3 +588,42 @@ export async function handleInteractiveSessionAbort(payload) {
     }
     return { success: true, aborted: true };
 }
+
+/**
+ * 5. Handles HITL_SESSION_EXTRACT:
+ *    Extracts fields directly from an active interactive session's live page.
+ */
+export async function handleInteractiveSessionExtract(payload) {
+    const { sessionId, 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 raw = {};
+
+    for (const mapping of fieldMappings) {
+        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;
+    }
+
+    return {
+        success: true,
+        data: raw,
+    };
+}
+

package/src/handlers/previewHandler.js

@@ -1,4 +1,5 @@
 import localBrowserManager from "../browser.js";
+import { getActiveInteractiveSession } from "./interactiveHandler.js";
 
 /**
  * Handles PREVIEW_PAGE task: captures full-page screenshot and dimensions on the edge worker.
@@ -120,74 +121,89 @@ export async function handlePreviewPage(payload) {
  * Handles INSPECT_ELEMENT task: resolves DOM element coordinates or evaluates candidate selectors on the edge worker.
  */
 export async function handleInspectElement(payload) {
-    const { url, preScrapeActions, authentication, selector, strategyType, strategies, fingerprint, x, y, timeout = 20000 } = payload;
-    const browser = await localBrowserManager.getBrowser();
-    const page = await browser.newPage();
+    const { sessionId, url, preScrapeActions, authentication, selector, strategyType, strategies, fingerprint, x, y, timeout = 20000 } = payload;
+    let page = null;
+    let isLiveSession = false;
+
+    if (sessionId) {
+        const liveSession = getActiveInteractiveSession(sessionId);
+        if (liveSession && liveSession.page && !liveSession.page.isClosed()) {
+            page = liveSession.page;
+            isLiveSession = true;
+        }
+    }
 
-    try {
-        await page.setViewport({ width: 1366, height: 900, deviceScaleFactor: 1 });
+    if (!page) {
+        const browser = await localBrowserManager.getBrowser();
+        page = await browser.newPage();
+    }
 
-        // Apply authentication 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(() => {});
+    try {
+        if (!isLiveSession) {
+            await page.setViewport({ width: 1366, height: 900, deviceScaleFactor: 1 });
+
+            // Apply authentication 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(() => {});
+                }
             }
-        }
 
-        await page.goto(url, { waitUntil: "domcontentloaded", timeout });
-        try {
-            await page.waitForNetworkIdle({ idleTime: 500, timeout: 3500 }).catch(() => {});
-        } catch (_) {}
-        await page.evaluate(() => document.fonts?.ready).catch(() => {});
-        await new Promise((r) => setTimeout(r, 800));
-
-        // Execute pre-scrape actions if present
-        if (Array.isArray(preScrapeActions) && preScrapeActions.length > 0) {
-            for (const action of preScrapeActions) {
-                try {
-                    if (action.actionType === "CLICK" && action.selector) {
-                        await page.waitForSelector(action.selector, { timeout: 4000 });
-                        await page.click(action.selector);
-                    } else if (action.actionType === "TYPE" && action.selector && action.value) {
-                        await page.waitForSelector(action.selector, { timeout: 4000 });
-                        await page.type(action.selector, action.value, { delay: action.delayMs || 30 });
-                        await page.evaluate((sel) => {
-                            const el = document.querySelector(sel);
-                            if (el) {
-                                el.dispatchEvent(new Event("input", { bubbles: true }));
-                                el.dispatchEvent(new Event("change", { bubbles: true }));
-                                el.dispatchEvent(new Event("blur", { bubbles: true }));
-                            }
-                        }, action.selector).catch(() => {});
-                        await page.keyboard.press("Tab").catch(() => {});
-                    } else if (action.actionType === "SCROLL") {
-                        const scrollPixels = parseInt(action.value, 10) || 500;
-                        await page.evaluate((px) => window.scrollBy(0, px), scrollPixels);
-                    } else if (action.actionType === "WAIT_FOR" && action.selector) {
-                        await page.waitForSelector(action.selector, { timeout: 8000 });
-                    } else if (action.actionType === "SELECT_OPTION" && action.selector && action.value) {
-                        await page.waitForSelector(action.selector, { timeout: 4000 });
-                        await page.select(action.selector, action.value);
-                    } else if (action.actionType === "PRESS_KEY" && action.value) {
-                        await page.keyboard.press(action.value);
-                    }
-                    if (action.delayMs && action.delayMs > 0) {
-                        await new Promise((r) => setTimeout(r, Math.min(action.delayMs, 5000)));
+            await page.goto(url, { waitUntil: "domcontentloaded", timeout });
+            try {
+                await page.waitForNetworkIdle({ idleTime: 500, timeout: 3500 }).catch(() => {});
+            } catch (_) {}
+            await page.evaluate(() => document.fonts?.ready).catch(() => {});
+            await new Promise((r) => setTimeout(r, 800));
+
+            // Execute pre-scrape actions if present
+            if (Array.isArray(preScrapeActions) && preScrapeActions.length > 0) {
+                for (const action of preScrapeActions) {
+                    try {
+                        if (action.actionType === "CLICK" && action.selector) {
+                            await page.waitForSelector(action.selector, { timeout: 4000 });
+                            await page.click(action.selector);
+                        } else if (action.actionType === "TYPE" && action.selector && action.value) {
+                            await page.waitForSelector(action.selector, { timeout: 4000 });
+                            await page.type(action.selector, action.value, { delay: action.delayMs || 30 });
+                            await page.evaluate((sel) => {
+                                const el = document.querySelector(sel);
+                                if (el) {
+                                    el.dispatchEvent(new Event("input", { bubbles: true }));
+                                    el.dispatchEvent(new Event("change", { bubbles: true }));
+                                    el.dispatchEvent(new Event("blur", { bubbles: true }));
+                                }
+                            }, action.selector).catch(() => {});
+                            await page.keyboard.press("Tab").catch(() => {});
+                        } else if (action.actionType === "SCROLL") {
+                            const scrollPixels = parseInt(action.value, 10) || 500;
+                            await page.evaluate((px) => window.scrollBy(0, px), scrollPixels);
+                        } else if (action.actionType === "WAIT_FOR" && action.selector) {
+                            await page.waitForSelector(action.selector, { timeout: 8000 });
+                        } else if (action.actionType === "SELECT_OPTION" && action.selector && action.value) {
+                            await page.waitForSelector(action.selector, { timeout: 4000 });
+                            await page.select(action.selector, action.value);
+                        } else if (action.actionType === "PRESS_KEY" && action.value) {
+                            await page.keyboard.press(action.value);
+                        }
+                        if (action.delayMs && action.delayMs > 0) {
+                            await new Promise((r) => setTimeout(r, Math.min(action.delayMs, 5000)));
+                        }
+                    } catch (actErr) {
+                        console.warn(`[WorkerInspect] Pre-scrape action ${action.actionType} (${action.selector}) skipped: ${actErr.message}`);
                     }
-                } catch (actErr) {
-                    console.warn(`[WorkerInspect] Pre-scrape action ${action.actionType} (${action.selector}) skipped: ${actErr.message}`);
                 }
+                await new Promise((r) => setTimeout(r, 600));
             }
-            await new Promise((r) => setTimeout(r, 600));
         }
 
         if (x !== undefined && y !== undefined) {
@@ -983,6 +999,8 @@ export async function handleInspectElement(payload) {
 
         return { message: "Specify coordinates (x, y) or selector to inspect." };
     } finally {
-        await page.close().catch(() => {});
+        if (!isLiveSession && page) {
+            await page.close().catch(() => {});
+        }
     }
 }

package/src/handlers/whatsappHandler.js

@@ -29,6 +29,7 @@ export class WhatsAppWorkerHandler {
         const homeDir = os.homedir();
         const baseDir = options.authDir || path.join(homeDir, ".app-manager-edge-worker", "wa-session");
         this.authDir = baseDir;
+        this.serverUrl = options.serverUrl || null;
         this.sock = null;
         this.status = "DISCONNECTED"; // DISCONNECTED | PAIRING | CONNECTED | STANDBY
         this.user = null; // { id, name, phone }
@@ -533,6 +534,7 @@ export class WhatsAppWorkerHandler {
         mimetype = "application/pdf",
         caption = "",
         idempotencyKey = null,
+        serverUrl = null,
     }) {
         logInfo(`[WhatsApp] Incoming document task for ${recipientPhone} (${fileName})`);
         await this.initialize(false);
@@ -565,8 +567,27 @@ export class WhatsAppWorkerHandler {
         const targetJid = verified.jid || jid;
 
         // 3. Stream PDF from authenticated URL (Zero buffer in central WebSocket)
-        logInfo(`[WhatsApp] Streaming document attachment (${fileName})...`);
-        const response = await axios.get(downloadUrl, {
+        let resolvedDownloadUrl = downloadUrl;
+        const activeServerUrl = serverUrl || this.serverUrl;
+        if (resolvedDownloadUrl && activeServerUrl) {
+            try {
+                const targetObj = new URL(resolvedDownloadUrl);
+                const srvObj = new URL(activeServerUrl);
+                const isTargetLoopback = ["localhost", "127.0.0.1", "::1"].includes(targetObj.hostname);
+                const isSrvLoopback = ["localhost", "127.0.0.1", "::1"].includes(srvObj.hostname);
+
+                // If target is loopback/localhost with mismatching port, or if worker connects to a remote server
+                if (isTargetLoopback && (!isSrvLoopback || targetObj.port !== srvObj.port)) {
+                    targetObj.protocol = srvObj.protocol;
+                    targetObj.hostname = srvObj.hostname;
+                    targetObj.port = srvObj.port;
+                    resolvedDownloadUrl = targetObj.toString();
+                }
+            } catch (_) {}
+        }
+
+        logInfo(`[WhatsApp] Streaming document attachment (${fileName}) from ${resolvedDownloadUrl}...`);
+        const response = await axios.get(resolvedDownloadUrl, {
             responseType: "arraybuffer",
             timeout: 25000,
         });