gologin-web-access 0.3.2 → 0.3.3

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

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.2";
+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/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/config.js

@@ -100,7 +100,7 @@ function requireWebUnlockerKey(config) {
 }
 function requireCloudToken(config) {
     if (!config.cloudToken) {
-        throw new errors_1.MissingCredentialError(exports.ENV_NAMES.cloudToken, "browser commands like `gologin-web-access open`");
+        throw new errors_1.MissingCredentialError(exports.ENV_NAMES.cloudToken, "browser and GoLogin API commands like `gologin-web-access open` or `gologin-web-access profile-proxy`");
     }
     return config.cloudToken;
 }

package/dist/lib/cloudApi.js

@@ -1,9 +1,70 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.gologinApiRequest = gologinApiRequest;
+exports.asObjectPayload = asObjectPayload;
 exports.validateCloudToken = validateCloudToken;
 exports.getProfile = getProfile;
 const errors_1 = require("./errors");
 const GOLOGIN_API_BASE_URL = "https://api.gologin.com";
+function buildApiUrl(path, query) {
+    const url = new URL(path.startsWith("http") ? path : `${GOLOGIN_API_BASE_URL}${path}`);
+    for (const [key, value] of Object.entries(query ?? {})) {
+        if (value !== undefined) {
+            url.searchParams.set(key, String(value));
+        }
+    }
+    return url.toString();
+}
+async function readPayload(response) {
+    const text = await response.text();
+    if (!text) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function formatApiErrorDetail(payload) {
+    if (!payload) {
+        return undefined;
+    }
+    if (typeof payload === "string") {
+        return payload.slice(0, 500);
+    }
+    if (typeof payload === "object") {
+        const value = payload;
+        for (const key of ["message", "error", "reason"]) {
+            if (typeof value[key] === "string" && value[key].length > 0) {
+                return value[key].slice(0, 500);
+            }
+        }
+        return JSON.stringify(value).slice(0, 500);
+    }
+    return String(payload).slice(0, 500);
+}
+async function gologinApiRequest(token, method, path, options = {}) {
+    const hasBody = options.body !== undefined;
+    const response = await fetch(buildApiUrl(path, options.query), {
+        method,
+        headers: {
+            Authorization: `Bearer ${token}`,
+            ...(hasBody ? { "Content-Type": "application/json" } : {}),
+        },
+        body: hasBody ? JSON.stringify(options.body) : undefined,
+    });
+    const payload = await readPayload(response);
+    if (!response.ok) {
+        const detail = formatApiErrorDetail(payload);
+        throw new errors_1.HttpError(`GoLogin API ${method} ${path} failed with status ${response.status}.`, response.status, detail);
+    }
+    return payload;
+}
+function asObjectPayload(value) {
+    return value && typeof value === "object" ? value : {};
+}
 async function validateCloudToken(token) {
     const response = await fetch(`${GOLOGIN_API_BASE_URL}/browser/v2`, {
         headers: {

package/dist/lib/output.js

@@ -16,7 +16,7 @@ function printText(value) {
     write(process.stdout, value);
 }
 function printJson(value) {
-    printText(JSON.stringify(value, null, 2));
+    printText(JSON.stringify(value ?? null, null, 2));
 }
 function printError(error) {
     if (error.message) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gologin-web-access",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Unified web access CLI for developers and AI agents to read and interact with the web using Gologin Web Unlocker and Cloud Browser.",
   "main": "dist/cli.js",
   "bin": {