gologin-web-access 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -5,6 +5,12 @@
 - browser automation is now embedded directly in `gologin-web-access`, so one repo and one install contains both Web Unlocker and Cloud Browser flows
 - doctor now reports the embedded browser runtime source and version
 
+## 0.3.2 - 2026-04-03
+
+- added unified page outcome classification across `read`, `scrape-json`, and `batch-scrape`
+- structured and readable paths now distinguish `ok`, `empty`, `incomplete`, `authwall`, `challenge`, `blocked`, and `cookie_wall`
+- batch and extract-oriented flows now propagate next-step hints and fallback metadata more consistently for agents
+
 ## 0.1.0 - 2026-03-10
 
 Initial public release of Gologin Web Access.

package/README.md

@@ -7,6 +7,7 @@ This is a unified web access layer, not just a scraping tool and not just a brow
 - Read the web through stateless extraction APIs
 - Interact with the web through stateful cloud browser sessions
 - Carry Gologin’s browser-side strengths into those workflows: profiles, identity-aware browser sessions, cloud browser infrastructure, and Gologin’s profile/proxy stack when you run against a configured profile
+- Manage common GoLogin profile/proxy API operations without leaving the CLI: cloud usage, cloud profile start/stop, profile cookies, fingerprint refresh, managed proxies, and user-agent updates
 
 Package name and binary are the same:
 
@@ -108,6 +109,24 @@ These commands use Gologin Cloud Browser through the local daemon-backed agent l
 
 Use these when you need state, interaction, or multi-step browser flows.
 
+### GoLogin API Helpers
+
+These commands use the GoLogin REST API directly through `GOLOGIN_TOKEN`. They do not require Web Unlocker and do not start the browser daemon:
+
+- `gologin-web-access cloud-usage --profile <profileId> | --workspace <workspaceId> [--days <1-30>] [--json]`
+- `gologin-web-access profile-cloud start <profileId> [--json]`
+- `gologin-web-access profile-cloud stop <profileId> [--json]`
+- `gologin-web-access profile-cookies export <profileId> [--output <path>] [--json]`
+- `gologin-web-access profile-cookies import <profileId> <cookies.json> [--clean] [--json]`
+- `gologin-web-access profile-fingerprint refresh <profileId...> [--json]`
+- `gologin-web-access profile-proxy list [--page <n>] [--json]`
+- `gologin-web-access profile-proxy traffic`
+- `gologin-web-access profile-proxy add-gologin <profileId> --country <cc> [--city <city>] [--type residential|mobile|dc] [--json]`
+- `gologin-web-access profile-ua latest [--os lin|mac|win|android|android-cloud] [--json]`
+- `gologin-web-access profile-ua update <profileId...> [--all-profiles] [--workspace <id>] [--json]`
+
+Use these when an agent needs GoLogin account/profile operations and would otherwise drop into raw REST calls or SDK code.
+
 ## When To Use `scrape` vs `browser`
 
 - Use `scrape` commands when you need page content, extracted text, markdown, or simple structured output.
@@ -124,6 +143,7 @@ Use these when you need state, interaction, or multi-step browser flows.
 - Use `batch-change-track` when you want to monitor a watchlist of pages in one pass.
 - Use `parse-document` when the source is a PDF, DOCX, XLSX, HTML, or local document path instead of a normal HTML page.
 - Use browser commands when you need clicks, forms, navigation, screenshots, sessions, or logged-in/profile-backed flows.
+- Use GoLogin API helper commands when you need to attach managed proxy traffic, export/import profile cookies, refresh fingerprints, update user agents, inspect usage, or start/stop a cloud profile.
 - Use browser commands when you need ref-based interaction, uploads, PDFs, semantic find flows, keyboard control, or a browser-visible search journey.
 - Use `run` and `batch` when you want reusable workflows or multi-target execution on top of the CLI surface.
 - Use `scrape` when stateless speed matters more than interaction.
@@ -168,7 +188,7 @@ This CLI uses two different GoLogin credentials on purpose, because the underlyi
 - `GOLOGIN_WEB_UNLOCKER_API_KEY`
   Required for Scraping / Read commands.
 - `GOLOGIN_TOKEN`
-  Required for `gologin-web-access open` and for profile validation in `gologin-web-access doctor`.
+  Required for `gologin-web-access open`, GoLogin API helper commands, and profile validation in `gologin-web-access doctor`.
 - `GOLOGIN_DEFAULT_PROFILE_ID`
   Optional default profile for browser flows.
 - `GOLOGIN_DAEMON_PORT`
@@ -287,6 +307,20 @@ gologin-web-access current
 gologin-web-access close
 ```
 
+### Manage Profiles And Proxies
+
+```bash
+export GOLOGIN_TOKEN="gl_..."
+
+gologin-web-access cloud-usage --profile profile_123
+gologin-web-access profile-proxy add-gologin profile_123 --country us --type residential
+gologin-web-access profile-proxy traffic
+gologin-web-access profile-cookies export profile_123 --output ./cookies.json
+gologin-web-access profile-fingerprint refresh profile_123
+gologin-web-access profile-ua latest --os mac
+gologin-web-access profile-ua update profile_123
+```
+
 ### Search In A Real Browser
 
 ```bash
@@ -305,6 +339,7 @@ gologin-web-access snapshot -i
 - `batch-extract` reuses the same extraction path across many URLs and returns one structured result per URL, including request and fallback metadata. Add `--output <path>` to save the full array directly.
 - `scrape-json` now returns both a flat `headings` array and `headingsByLevel` buckets for `h1` through `h6`.
 - `scrape-json --fallback browser` is available for JS-heavy pages where stateless extraction returns weak heading data.
+- `scrape-json` now also classifies the page outcome as `ok`, `empty`, `incomplete`, `authwall`, `challenge`, `blocked`, or `cookie_wall`, and includes `nextActionHint` when the result is weak or gated.
 - `scrape`, `scrape-markdown`, `scrape-text`, `scrape-json`, and `batch-scrape` accept `--retry`, `--backoff-ms`, and `--timeout-ms`.
 - `batch-scrape --only-main-content` lets markdown, text, and html batch runs use the same readable-content isolation path as `read`.
 - `crawl --only-main-content` uses the same readable-fragment extraction strategy for html, markdown, and text crawl output, but stays on the stateless unlocker path.
@@ -312,6 +347,7 @@ gologin-web-access snapshot -i
 - `batch-scrape` now returns exit code `0` on partial success by default and only fails the command when every URL failed. Add `--strict` if any single failed URL should make the whole batch exit non-zero.
 - `batch-scrape --output <path>` writes the full JSON to disk so shells and agent consoles cannot truncate a large payload silently.
 - `batch-scrape --format json` now returns the same structured scrape envelope as `scrape-json`, including `renderSource`, `fallbackAttempted`, `fallbackUsed`, and `request.attemptCount/retryCount/attempts`.
+- `batch-scrape --only-main-content` now propagates `outcome`, `outcomeReason`, `nextActionHint`, and fallback metadata per URL so agents can tell "weak page" from "gated page" without scraping log text.
 - `scrape-json` now surfaces explicit `BLOCKED_PAGE` failures when structured output clearly matches a challenge or block page, instead of silently looking like a valid empty result.
 - `search` now returns `requestedLimit`, `returnedCount`, `warnings`, `cacheTtlMs`, and per-result `position`.
 - `search` may return fewer results than the requested `--limit` when the upstream SERP contains fewer valid results; inspect `returnedCount`, `warnings`, and `attempts`.

package/dist/cli.js

@@ -30,6 +30,7 @@ const find_1 = require("./commands/find");
 const focus_1 = require("./commands/focus");
 const forward_1 = require("./commands/forward");
 const get_1 = require("./commands/get");
+const gologinApi_1 = require("./commands/gologinApi");
 const hover_1 = require("./commands/hover");
 const jobs_1 = require("./commands/jobs");
 const map_1 = require("./commands/map");
@@ -67,7 +68,7 @@ const wait_1 = require("./commands/wait");
 const doctor_1 = require("./doctor");
 const errors_1 = require("./lib/errors");
 const output_1 = require("./lib/output");
-const CLI_VERSION = "0.3.0";
+const CLI_VERSION = "0.3.3";
 async function main() {
     const program = new commander_1.Command();
     program
@@ -137,6 +138,12 @@ async function main() {
     program.addCommand((0, close_1.buildCloseCommand)());
     program.addCommand((0, sessions_1.buildSessionsCommand)());
     program.addCommand((0, current_1.buildCurrentCommand)());
+    program.addCommand((0, gologinApi_1.buildCloudUsageCommand)());
+    program.addCommand((0, gologinApi_1.buildProfileCloudCommand)());
+    program.addCommand((0, gologinApi_1.buildProfileCookiesCommand)());
+    program.addCommand((0, gologinApi_1.buildProfileFingerprintCommand)());
+    program.addCommand((0, gologinApi_1.buildProfileProxyCommand)());
+    program.addCommand((0, gologinApi_1.buildProfileUaCommand)());
     program
         .command("doctor")
         .description("Inspect both recommended keys, profile configuration, and local daemon health.")
@@ -163,6 +170,7 @@ Quick picks:
 Command groups:
   Scraping: gologin-web-access scrape|read|scrape-markdown|scrape-text|scrape-json|batch-scrape|batch-extract|search|map|crawl|crawl-start|crawl-status|crawl-result|crawl-errors|extract|change-track|batch-change-track|parse-document
   Browser:  gologin-web-access open|search-browser|scrape-screenshot|tabs|tabopen|tabfocus|tabclose|snapshot|click|dblclick|focus|type|fill|hover|select|check|uncheck|press|scroll|scrollintoview|wait|get|back|forward|reload|find|cookies|cookies-import|cookies-clear|storage-export|storage-import|storage-clear|eval|upload|pdf|screenshot|close|sessions|current
+  GoLogin API: gologin-web-access cloud-usage|profile-cloud|profile-cookies|profile-fingerprint|profile-proxy|profile-ua
   Agent:    gologin-web-access run|batch|jobs|job
 
 Key model:

package/dist/commands/batchScrape.js

@@ -47,7 +47,16 @@ function buildBatchScrapeCommand() {
                     url,
                     ok: true,
                     format,
-                    output,
+                    output: output.output,
+                    outcome: output.outcome,
+                    outcomeReason: output.outcomeReason,
+                    nextActionHint: output.nextActionHint,
+                    renderSource: output.renderSource,
+                    fallbackAttempted: output.fallbackAttempted,
+                    fallbackUsed: output.fallbackUsed,
+                    fallbackReason: output.fallbackReason,
+                    warning: output.warning,
+                    request: output.request,
                 };
             }
             catch (error) {
@@ -59,6 +68,8 @@ function buildBatchScrapeCommand() {
                     error: error instanceof Error ? error.message : "Unknown error",
                     code: extractErrorCode(error),
                     status: extractStatusCode(error),
+                    outcome: extractOutcome(error),
+                    nextActionHint: extractNextActionHint(error),
                     request,
                 };
             }
@@ -97,31 +108,67 @@ async function formatOutput(url, config, apiKey, format, requestOptions, fallbac
         };
         switch (format) {
             case "html":
-                return (await (0, readSource_1.readHtmlContent)(url, config, apiKey, readOptions)).content;
+                return mapReadableBatchResult(await (0, readSource_1.readHtmlContent)(url, config, apiKey, readOptions));
             case "markdown":
-                return (await (0, readSource_1.readMarkdownContent)(url, config, apiKey, readOptions)).content;
+                return mapReadableBatchResult(await (0, readSource_1.readMarkdownContent)(url, config, apiKey, readOptions));
             case "text":
-                return (await (0, readSource_1.readTextContent)(url, config, apiKey, readOptions)).content;
+                return mapReadableBatchResult(await (0, readSource_1.readTextContent)(url, config, apiKey, readOptions));
             default:
                 break;
         }
     }
     switch (format) {
         case "html":
-            return (await (0, unlocker_1.scrapeRenderedHtml)(url, apiKey, requestOptions)).content;
+            return {
+                output: (await (0, unlocker_1.scrapeRenderedHtml)(url, apiKey, requestOptions)).content,
+            };
         case "markdown":
-            return (await (0, unlocker_1.scrapeMarkdown)(url, apiKey, requestOptions)).markdown;
+            return {
+                output: (await (0, unlocker_1.scrapeMarkdown)(url, apiKey, requestOptions)).markdown,
+            };
         case "text":
-            return (await (0, unlocker_1.scrapeText)(url, apiKey, requestOptions)).text;
+            return {
+                output: (await (0, unlocker_1.scrapeText)(url, apiKey, requestOptions)).text,
+            };
         case "json":
-            return await (0, structuredScrape_1.scrapeStructuredJson)(url, config, apiKey, {
+            return mapStructuredBatchResult(await (0, structuredScrape_1.scrapeStructuredJson)(url, config, apiKey, {
                 fallback,
                 request: requestOptions,
-            });
+            }));
         default:
-            return (await (0, unlocker_1.scrapeRenderedHtml)(url, apiKey, requestOptions)).content;
+            return {
+                output: (await (0, unlocker_1.scrapeRenderedHtml)(url, apiKey, requestOptions)).content,
+            };
     }
 }
+function mapReadableBatchResult(result) {
+    return {
+        output: result.content,
+        outcome: result.outcome,
+        outcomeReason: result.outcomeReason,
+        nextActionHint: result.nextActionHint,
+        renderSource: result.renderSource,
+        fallbackAttempted: result.fallbackAttempted,
+        fallbackUsed: result.fallbackUsed,
+        fallbackReason: result.fallbackReason,
+        warning: result.warning,
+        request: result.request,
+    };
+}
+function mapStructuredBatchResult(result) {
+    return {
+        output: result,
+        outcome: result.outcome,
+        outcomeReason: result.outcomeReason,
+        nextActionHint: result.nextActionHint,
+        renderSource: result.renderSource,
+        fallbackAttempted: result.fallbackAttempted,
+        fallbackUsed: result.fallbackUsed,
+        fallbackReason: result.fallbackReason,
+        warning: result.warning,
+        request: result.request,
+    };
+}
 async function mapWithConcurrency(items, concurrency, mapper) {
     const results = new Array(items.length);
     let nextIndex = 0;
@@ -180,3 +227,21 @@ function extractErrorCode(error) {
     }
     return undefined;
 }
+function extractOutcome(error) {
+    if (typeof error === "object" &&
+        error !== null &&
+        "outcome" in error &&
+        typeof error.outcome === "string") {
+        return error.outcome;
+    }
+    return undefined;
+}
+function extractNextActionHint(error) {
+    if (typeof error === "object" &&
+        error !== null &&
+        "nextActionHint" in error &&
+        typeof error.nextActionHint === "string") {
+        return error.nextActionHint;
+    }
+    return undefined;
+}

package/dist/commands/gologinApi.js

@@ -0,0 +1,324 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCloudUsageCommand = buildCloudUsageCommand;
+exports.buildProfileCloudCommand = buildProfileCloudCommand;
+exports.buildProfileCookiesCommand = buildProfileCookiesCommand;
+exports.buildProfileFingerprintCommand = buildProfileFingerprintCommand;
+exports.buildProfileProxyCommand = buildProfileProxyCommand;
+exports.buildProfileUaCommand = buildProfileUaCommand;
+const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
+const commander_1 = require("commander");
+const config_1 = require("../config");
+const cloudApi_1 = require("../lib/cloudApi");
+const errors_1 = require("../lib/errors");
+const output_1 = require("../lib/output");
+async function getCloudToken() {
+    const config = await (0, config_1.loadConfig)();
+    return (0, config_1.requireCloudToken)(config);
+}
+function parseDays(value) {
+    const days = value ? Number(value) : 7;
+    if (!Number.isInteger(days) || days < 1 || days > 30) {
+        throw new errors_1.CliError("--days must be an integer from 1 to 30.");
+    }
+    return days;
+}
+function parsePage(value) {
+    if (!value) {
+        return undefined;
+    }
+    const page = Number(value);
+    if (!Number.isInteger(page) || page < 1) {
+        throw new errors_1.CliError("--page must be a positive integer.");
+    }
+    return page;
+}
+function normalizeCountryCode(value) {
+    const countryCode = value.toLowerCase();
+    if (!/^[a-z]{2}$/.test(countryCode)) {
+        throw new errors_1.CliError("--country must be a 2-letter country code, for example us.");
+    }
+    return countryCode;
+}
+function normalizeProxyType(value) {
+    const type = value ?? "residential";
+    if (type === "mobile") {
+        return { isMobile: true, label: "mobile" };
+    }
+    if (type === "dc" || type === "datacenter") {
+        return { isDC: true, label: "datacenter" };
+    }
+    if (type === "residential") {
+        return { label: "residential" };
+    }
+    throw new errors_1.CliError("--type must be one of residential, mobile, or dc.");
+}
+function detectHostOs() {
+    if (process.platform === "darwin") {
+        return "mac";
+    }
+    if (process.platform === "win32") {
+        return "win";
+    }
+    return "lin";
+}
+function normalizeOs(value) {
+    const os = value ?? detectHostOs();
+    if (!["lin", "mac", "win", "android", "android-cloud"].includes(os)) {
+        throw new errors_1.CliError("--os must be one of lin, mac, win, android, or android-cloud.");
+    }
+    return os;
+}
+async function readJsonFile(targetPath) {
+    const absolutePath = path_1.default.resolve(targetPath);
+    try {
+        return JSON.parse(await fs_1.promises.readFile(absolutePath, "utf8"));
+    }
+    catch (error) {
+        throw new errors_1.CliError(`Failed to read JSON file ${absolutePath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+async function writeJsonFile(targetPath, payload) {
+    const absolutePath = path_1.default.resolve(targetPath);
+    await fs_1.promises.mkdir(path_1.default.dirname(absolutePath), { recursive: true });
+    await fs_1.promises.writeFile(absolutePath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+    return absolutePath;
+}
+function buildCloudUsageCommand() {
+    return new commander_1.Command("cloud-usage")
+        .description("Read GoLogin Cloud Browser usage statistics.")
+        .option("--profile <profileId>", "Profile ID to inspect")
+        .option("--workspace <workspaceId>", "Workspace ID to inspect")
+        .option("--days <days>", "Workspace stats range from 1 to 30 days", "7")
+        .option("--json", "Print JSON output")
+        .action(async (options) => {
+        if (options.profile && options.workspace) {
+            throw new errors_1.CliError("Use either --profile or --workspace, not both.");
+        }
+        const token = await getCloudToken();
+        if (options.profile) {
+            const payload = await (0, cloudApi_1.gologinApiRequest)(token, "GET", `/cloud-usage/profile/${options.profile}/stats`);
+            if (options.json) {
+                (0, output_1.printJson)(payload);
+                return;
+            }
+            (0, output_1.printText)(`profile=${options.profile} usage=${JSON.stringify(payload)}`);
+            return;
+        }
+        if (!options.workspace) {
+            throw new errors_1.CliError("Usage: gologin-web-access cloud-usage --profile <profileId> | --workspace <workspaceId> [--days <1-30>] [--json]");
+        }
+        const days = parseDays(options.days);
+        const payload = await (0, cloudApi_1.gologinApiRequest)(token, "GET", "/cloud-usage/stats", {
+            query: { workspaceId: options.workspace, days },
+        });
+        if (options.json) {
+            (0, output_1.printJson)(payload);
+            return;
+        }
+        (0, output_1.printText)(`workspace=${options.workspace} days=${days} usage=${JSON.stringify(payload)}`);
+    });
+}
+function buildProfileCloudCommand() {
+    const command = new commander_1.Command("profile-cloud").description("Start or stop a GoLogin profile in Cloud Browser.");
+    command
+        .command("start")
+        .argument("<profileId>", "Profile ID")
+        .option("--json", "Print JSON output")
+        .action(async (profileId, options) => {
+        const token = await getCloudToken();
+        const payload = await (0, cloudApi_1.gologinApiRequest)(token, "POST", `/browser/${profileId}/web`, { body: {} });
+        if (options.json) {
+            (0, output_1.printJson)(payload ?? { profileId, started: true });
+            return;
+        }
+        const value = (0, cloudApi_1.asObjectPayload)(payload);
+        const remoteUrl = typeof value.remoteOrbitaUrl === "string" ? ` remote=${value.remoteOrbitaUrl}` : "";
+        (0, output_1.printText)(`profile=${profileId} cloud=started${remoteUrl}`);
+    });
+    command
+        .command("stop")
+        .argument("<profileId>", "Profile ID")
+        .option("--json", "Print JSON output")
+        .action(async (profileId, options) => {
+        const token = await getCloudToken();
+        await (0, cloudApi_1.gologinApiRequest)(token, "DELETE", `/browser/${profileId}/web`);
+        if (options.json) {
+            (0, output_1.printJson)({ profileId, stopped: true });
+            return;
+        }
+        (0, output_1.printText)(`profile=${profileId} cloud=stopped`);
+    });
+    return command;
+}
+function buildProfileCookiesCommand() {
+    const command = new commander_1.Command("profile-cookies").description("Export or import cookies from the GoLogin profile database.");
+    command
+        .command("export")
+        .argument("<profileId>", "Profile ID")
+        .option("--output <path>", "Write cookies JSON to a file")
+        .option("--json", "Print JSON output with profile metadata")
+        .action(async (profileId, options) => {
+        const token = await getCloudToken();
+        const cookies = await (0, cloudApi_1.gologinApiRequest)(token, "GET", `/browser/${profileId}/cookies`);
+        if (options.output) {
+            (0, output_1.printText)(await writeJsonFile(options.output, cookies));
+            return;
+        }
+        (0, output_1.printJson)(options.json ? { profileId, cookies } : cookies);
+    });
+    command
+        .command("import")
+        .argument("<profileId>", "Profile ID")
+        .argument("<cookiesJson>", "Cookie JSON file")
+        .option("--clean", "Clear existing cookies before importing")
+        .option("--json", "Print JSON output")
+        .action(async (profileId, cookiesJson, options) => {
+        const cookies = await readJsonFile(cookiesJson);
+        if (!Array.isArray(cookies)) {
+            throw new errors_1.CliError("Cookie import file must contain a JSON array.");
+        }
+        const token = await getCloudToken();
+        await (0, cloudApi_1.gologinApiRequest)(token, "POST", `/browser/${profileId}/cookies`, {
+            query: { fromUser: true, cleanCookies: options.clean || undefined },
+            body: cookies,
+        });
+        if (options.json) {
+            (0, output_1.printJson)({ profileId, imported: cookies.length, cleanCookies: options.clean === true });
+            return;
+        }
+        (0, output_1.printText)(`profile=${profileId} importedCookies=${cookies.length}${options.clean ? " clean=true" : ""}`);
+    });
+    return command;
+}
+function buildProfileFingerprintCommand() {
+    const command = new commander_1.Command("profile-fingerprint").description("Refresh fingerprints for one or more GoLogin profiles.");
+    command
+        .command("refresh")
+        .argument("<profileIds...>", "Profile IDs")
+        .option("--json", "Print JSON output")
+        .action(async (profileIds, options) => {
+        const token = await getCloudToken();
+        const payload = await (0, cloudApi_1.gologinApiRequest)(token, "PATCH", "/browser/fingerprints", {
+            body: { browsersIds: profileIds },
+        });
+        if (options.json) {
+            (0, output_1.printJson)(payload);
+            return;
+        }
+        (0, output_1.printText)(`refreshedFingerprints=${profileIds.length} profiles=${profileIds.join(",")}`);
+    });
+    return command;
+}
+function buildProfileProxyCommand() {
+    const command = new commander_1.Command("profile-proxy").description("Manage GoLogin proxies through the REST API.");
+    command
+        .command("list")
+        .option("--page <page>", "Page number", "1")
+        .option("--json", "Print JSON output")
+        .action(async (options) => {
+        const token = await getCloudToken();
+        const payload = await (0, cloudApi_1.gologinApiRequest)(token, "GET", "/proxy/v2", {
+            query: { page: parsePage(options.page) },
+        });
+        if (options.json) {
+            (0, output_1.printJson)(payload);
+            return;
+        }
+        const value = (0, cloudApi_1.asObjectPayload)(payload);
+        const proxies = Array.isArray(value.proxies) ? value.proxies : [];
+        (0, output_1.printText)(`proxies=${proxies.length} hasMore=${value.hasMore === true}`);
+    });
+    command
+        .command("traffic")
+        .description("Read GoLogin managed proxy traffic balance/usage.")
+        .action(async () => {
+        const token = await getCloudToken();
+        (0, output_1.printJson)(await (0, cloudApi_1.gologinApiRequest)(token, "GET", "/users-proxies/geolocation/traffic"));
+    });
+    command
+        .command("add-gologin")
+        .argument("<profileId>", "Profile ID to link the managed proxy to")
+        .requiredOption("--country <cc>", "2-letter country code, for example us")
+        .option("--city <city>", "Optional city name")
+        .option("--type <type>", "residential, mobile, or dc", "residential")
+        .option("--name <name>", "Custom proxy name")
+        .option("--json", "Print JSON output")
+        .action(async (profileId, options) => {
+        const token = await getCloudToken();
+        const countryCode = normalizeCountryCode(options.country);
+        const proxyType = normalizeProxyType(options.type);
+        const body = {
+            countryCode,
+            profileIdToLink: profileId,
+            customName: options.name ?? `gologin-${countryCode}-${profileId.slice(0, 6)}`,
+        };
+        if (options.city) {
+            body.city = options.city;
+        }
+        if (proxyType.isMobile !== undefined) {
+            body.isMobile = proxyType.isMobile;
+        }
+        if (proxyType.isDC !== undefined) {
+            body.isDC = proxyType.isDC;
+        }
+        const payload = await (0, cloudApi_1.gologinApiRequest)(token, "POST", "/users-proxies/mobile-proxy", { body });
+        if (options.json) {
+            (0, output_1.printJson)(payload ?? { profileId, countryCode, type: proxyType.label });
+            return;
+        }
+        (0, output_1.printText)(`profile=${profileId} proxy=gologin:${countryCode} type=${proxyType.label}`);
+    });
+    return command;
+}
+function buildProfileUaCommand() {
+    const command = new commander_1.Command("profile-ua").description("Read latest GoLogin user agent or update profile UA.");
+    command
+        .command("latest")
+        .option("--os <os>", "lin, mac, win, android, or android-cloud")
+        .option("--json", "Print JSON output")
+        .action(async (options) => {
+        const os = normalizeOs(options.os);
+        const token = await getCloudToken();
+        const payload = await (0, cloudApi_1.gologinApiRequest)(token, "GET", "/browser/latest-useragent", {
+            query: { os },
+        });
+        if (options.json) {
+            (0, output_1.printJson)(payload);
+            return;
+        }
+        (0, output_1.printText)(`os=${os} latestUserAgent=${typeof payload === "string" ? payload : JSON.stringify(payload)}`);
+    });
+    command
+        .command("update")
+        .argument("[profileIds...]", "Profile IDs")
+        .option("--all-profiles", "Update all profiles in the current workspace")
+        .option("--workspace <id>", "Current workspace ID")
+        .option("--json", "Print JSON output")
+        .action(async (profileIds, options) => {
+        if (profileIds.length === 0 && !options.allProfiles) {
+            throw new errors_1.CliError("Usage: gologin-web-access profile-ua update <profileId...> [--all-profiles] [--workspace <id>] [--json]");
+        }
+        const token = await getCloudToken();
+        const payload = await (0, cloudApi_1.gologinApiRequest)(token, "PATCH", "/browser/update_ua_to_new_browser_v", {
+            query: { currentWorkspace: options.workspace },
+            body: {
+                browserIds: profileIds,
+                updateUaToNewBrowserV: true,
+                updateAllProfiles: options.allProfiles === true,
+            },
+        });
+        if (options.json) {
+            (0, output_1.printJson)(payload ?? { updated: true, profileIds, allProfiles: options.allProfiles === true });
+            return;
+        }
+        (0, output_1.printText)(options.allProfiles
+            ? "updatedUserAgent=allProfiles"
+            : `updatedUserAgentProfiles=${profileIds.length} profiles=${profileIds.join(",")}`);
+    });
+    return command;
+}

package/dist/commands/read.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildReadCommand = buildReadCommand;
 const commander_1 = require("commander");
 const config_1 = require("../config");
+const pageOutcome_1 = require("../lib/pageOutcome");
 const readSource_1 = require("../lib/readSource");
 const output_1 = require("../lib/output");
 const shared_1 = require("./shared");
@@ -27,7 +28,7 @@ function buildReadCommand() {
             : format === "markdown"
                 ? await (0, readSource_1.readMarkdownContent)(url, config, apiKey, readOptions)
                 : await (0, readSource_1.readTextContent)(url, config, apiKey, readOptions);
-        emitReadNotice(result.fallbackAttempted, result.fallbackUsed, result.fallbackReason);
+        emitReadNotice(result);
         (0, output_1.printText)(result.content);
     })));
 }
@@ -37,15 +38,24 @@ function normalizeReadFormat(value) {
     }
     throw new Error(`Unsupported read format: ${value}`);
 }
-function emitReadNotice(fallbackAttempted, fallbackUsed, fallbackReason) {
-    if (!fallbackAttempted) {
-        return;
+function emitReadNotice(result) {
+    if (result.fallbackAttempted) {
+        if (result.fallbackUsed) {
+            process.stderr.write(`JS-rendered page detected, retrying with browser. ${result.fallbackReason ?? ""}\n`);
+        }
+        else if (result.fallbackReason) {
+            process.stderr.write(`${result.fallbackReason}\n`);
+        }
+    }
+    if (result.outcome !== "ok") {
+        process.stderr.write(`Outcome: ${result.outcome}\n`);
     }
-    if (fallbackUsed) {
-        process.stderr.write(`JS-rendered page detected, retrying with browser. ${fallbackReason ?? ""}\n`);
+    if (result.warning) {
+        process.stderr.write(`${result.warning}\n`);
         return;
     }
-    if (fallbackReason) {
-        process.stderr.write(`${fallbackReason}\n`);
+    const hint = (0, pageOutcome_1.describeNextActionHint)(result.nextActionHint);
+    if (hint && result.outcome !== "ok") {
+        process.stderr.write(`${hint}\n`);
     }
 }