gologin-agent-browser-cli 0.1.0

package/dist/lib/types.d.ts

@@ -0,0 +1,301 @@
+import type { Browser, BrowserContext, Page } from "playwright";
+export type TransportKind = "socket" | "http";
+export type SnapshotKind = "heading" | "paragraph" | "link" | "button" | "input" | "checkbox" | "radio" | "textarea" | "select";
+export interface AgentConfig {
+    token?: string;
+    defaultProfileId?: string;
+    connectBase: string;
+    daemonPort: number;
+    daemonHost: string;
+    socketPath: string;
+    configPath: string;
+    logPath: string;
+    navigationTimeoutMs: number;
+    actionTimeoutMs: number;
+}
+export interface ResolvedTransport {
+    kind: TransportKind;
+    socketPath?: string;
+    host?: string;
+    port?: number;
+}
+export interface SessionSummary {
+    sessionId: string;
+    profileId?: string;
+    url: string;
+    active: boolean;
+    hasSnapshot: boolean;
+    staleSnapshot: boolean;
+    liveViewUrl?: string;
+    proxy?: ProxySummary;
+    createdAt?: string;
+    lastActivityAt?: string;
+    idleTimeoutMs?: number;
+    lastScreenshotPath?: string;
+    lastPdfPath?: string;
+}
+export type ProxyMode = "gologin" | "http" | "socks4" | "socks5";
+export interface ProxyConfig {
+    mode: ProxyMode;
+    country?: string;
+    host?: string;
+    port?: number;
+    username?: string;
+    password?: string;
+}
+export interface ProxySummary {
+    mode: string;
+    country?: string;
+    host?: string;
+    port?: number;
+    username?: string;
+}
+export interface RefDescriptor {
+    ref: string;
+    kind: SnapshotKind;
+    tag: string;
+    role?: string;
+    text?: string;
+    accessibleName?: string;
+    ariaLabel?: string;
+    placeholder?: string;
+    inputType?: string;
+    name?: string;
+    href?: string;
+    nth?: number;
+    checked?: boolean;
+    disabled?: boolean;
+    selectedText?: string;
+}
+export interface SnapshotItem {
+    ref: string;
+    kind: SnapshotKind;
+    text: string;
+    role?: string;
+    flags?: string[];
+}
+export interface SnapshotResponse {
+    sessionId: string;
+    url: string;
+    items: SnapshotItem[];
+}
+export interface SessionRecord {
+    sessionId: string;
+    profileId?: string;
+    autoCreatedProfile: boolean;
+    connectUrl: string;
+    browser: Browser;
+    context: BrowserContext;
+    page: Page;
+    currentUrl: string;
+    hasSnapshot: boolean;
+    staleSnapshot: boolean;
+    liveViewUrl?: string;
+    proxy?: ProxySummary;
+    createdAt: string;
+    lastActivityAt: string;
+    idleTimeoutMs?: number;
+    lastScreenshotPath?: string;
+    lastPdfPath?: string;
+}
+export interface OpenSessionRequest {
+    url: string;
+    profileId?: string;
+    sessionId?: string;
+    proxy?: ProxyConfig;
+    idleTimeoutMs?: number;
+}
+export interface OpenSessionResponse {
+    sessionId: string;
+    profileId?: string;
+    url: string;
+    liveViewUrl?: string;
+    proxy?: ProxySummary;
+    idleTimeoutMs?: number;
+}
+export interface TargetRequest {
+    target: string;
+}
+export interface ClickRequest extends TargetRequest {
+}
+export interface ActionResponse {
+    sessionId: string;
+    url: string;
+    staleSnapshot: boolean;
+}
+export interface ClickResponse extends ActionResponse {
+}
+export interface TypeRequest extends TargetRequest {
+    text: string;
+}
+export interface TypeResponse extends ActionResponse {
+}
+export interface FillRequest extends TargetRequest {
+    text: string;
+}
+export interface FillResponse extends ActionResponse {
+}
+export interface HoverRequest extends TargetRequest {
+}
+export interface HoverResponse extends ActionResponse {
+}
+export interface FocusRequest extends TargetRequest {
+}
+export interface FocusResponse extends ActionResponse {
+}
+export interface DoubleClickRequest extends TargetRequest {
+}
+export interface DoubleClickResponse extends ActionResponse {
+}
+export interface SelectRequest extends TargetRequest {
+    value: string;
+}
+export interface SelectResponse extends ActionResponse {
+}
+export interface CheckRequest extends TargetRequest {
+}
+export interface CheckResponse extends ActionResponse {
+}
+export interface UncheckRequest extends TargetRequest {
+}
+export interface UncheckResponse extends ActionResponse {
+}
+export interface PressRequest {
+    key: string;
+    target?: string;
+}
+export interface PressResponse extends ActionResponse {
+}
+export interface ScreenshotRequest {
+    path: string;
+    annotate?: boolean;
+}
+export interface ScreenshotResponse {
+    sessionId: string;
+    path: string;
+    url: string;
+    annotated?: boolean;
+}
+export interface CloseSessionResponse {
+    sessionId: string;
+    closed: true;
+}
+export interface SessionsResponse {
+    activeSessionId?: string;
+    sessions: SessionSummary[];
+}
+export type WaitLoadState = "load" | "domcontentloaded" | "networkidle";
+export interface WaitRequest {
+    target?: string;
+    text?: string;
+    urlPattern?: string;
+    loadState?: WaitLoadState;
+    timeoutMs?: number;
+}
+export interface WaitResponse {
+    sessionId: string;
+    url: string;
+    waitedFor: string;
+}
+export type ScrollDirection = "up" | "down" | "left" | "right";
+export interface ScrollRequest {
+    direction: ScrollDirection;
+    pixels?: number;
+    target?: string;
+}
+export interface ScrollResponse {
+    sessionId: string;
+    url: string;
+    target?: string;
+    direction: ScrollDirection;
+    pixels: number;
+}
+export interface ScrollIntoViewRequest extends TargetRequest {
+}
+export interface ScrollIntoViewResponse extends ActionResponse {
+}
+export interface UploadRequest extends TargetRequest {
+    files: string[];
+}
+export interface UploadResponse extends ActionResponse {
+    files: string[];
+}
+export interface PdfRequest {
+    path: string;
+}
+export interface PdfResponse {
+    sessionId: string;
+    path: string;
+    url: string;
+}
+export type GetKind = "text" | "value" | "html" | "title" | "url";
+export interface GetRequest {
+    kind: GetKind;
+    target?: string;
+}
+export interface GetResponse {
+    sessionId: string;
+    url: string;
+    value: string;
+}
+export type SemanticLocatorStrategy = "role" | "text" | "label" | "placeholder" | "first" | "last" | "nth";
+export interface SemanticLocatorQuery {
+    strategy: SemanticLocatorStrategy;
+    role?: string;
+    name?: string;
+    text?: string;
+    label?: string;
+    placeholder?: string;
+    selector?: string;
+    nth?: number;
+    exact?: boolean;
+}
+export type SemanticFindAction = "click" | "fill" | "type" | "hover" | "text";
+export interface FindRequest {
+    locator: SemanticLocatorQuery;
+    action: SemanticFindAction;
+    value?: string;
+}
+export interface FindResponse extends ActionResponse {
+    value?: string;
+}
+export interface HealthResponse {
+    ok: true;
+    pid: number;
+    transports: TransportKind[];
+}
+export interface DaemonErrorPayload {
+    code: string;
+    message: string;
+    status: number;
+    details?: Record<string, unknown>;
+}
+export interface SnapshotBuildResult {
+    items: SnapshotItem[];
+    refs: RefDescriptor[];
+}
+export interface RawSnapshotCandidate {
+    kind: SnapshotKind;
+    tag: string;
+    role?: string;
+    text?: string;
+    accessibleName?: string;
+    ariaLabel?: string;
+    placeholder?: string;
+    inputType?: string;
+    name?: string;
+    href?: string;
+    checked?: boolean;
+    disabled?: boolean;
+    selectedText?: string;
+}
+export interface DaemonClient {
+    transport: ResolvedTransport;
+    request<TResponse>(method: string, path: string, body?: unknown): Promise<TResponse>;
+}
+export interface CommandContext {
+    client: DaemonClient;
+    stdout: NodeJS.WriteStream;
+    stderr: NodeJS.WriteStream;
+    cwd: string;
+}

package/dist/lib/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/lib/utils.d.ts

@@ -0,0 +1,27 @@
+import http from "node:http";
+import type { DaemonErrorPayload, ProxySummary, RefDescriptor, ResolvedTransport, SessionSummary, SnapshotItem } from "./types";
+export type ParsedArgs = {
+    positional: string[];
+    flags: Record<string, string | boolean>;
+};
+export declare function parseArgs(argv: string[]): ParsedArgs;
+export declare function getFlagString(parsed: ParsedArgs, name: string): string | undefined;
+export declare function getFlagBoolean(parsed: ParsedArgs, name: string): boolean;
+export declare function generateSessionId(existingIds: Iterable<string>): string;
+export declare function ensureAbsolutePath(baseDir: string, targetPath: string): string;
+export declare function isRefTarget(target: string): boolean;
+export declare function isNumericToken(token: string): boolean;
+export declare function formatSnapshotItem(item: SnapshotItem): string;
+export declare function formatProxyLabel(proxy?: ProxySummary): string | undefined;
+export declare function formatSessionLine(session: SessionSummary): string;
+export declare function formatCurrentLine(session: SessionSummary): string;
+export declare function writeJsonResponse(response: http.ServerResponse, statusCode: number, payload: unknown): void;
+export declare function readJsonBody(request: http.IncomingMessage): Promise<unknown>;
+export declare function appendLog(logPath: string, line: string): void;
+export declare function buildRefDisplayText(descriptor: RefDescriptor): string;
+export declare function makeTransportLabel(transport: ResolvedTransport): string;
+export declare function isDaemonErrorResponse(payload: unknown): payload is DaemonErrorPayload & {
+    code: string;
+    message: string;
+    status: number;
+};

package/dist/lib/utils.js

@@ -0,0 +1,165 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseArgs = parseArgs;
+exports.getFlagString = getFlagString;
+exports.getFlagBoolean = getFlagBoolean;
+exports.generateSessionId = generateSessionId;
+exports.ensureAbsolutePath = ensureAbsolutePath;
+exports.isRefTarget = isRefTarget;
+exports.isNumericToken = isNumericToken;
+exports.formatSnapshotItem = formatSnapshotItem;
+exports.formatProxyLabel = formatProxyLabel;
+exports.formatSessionLine = formatSessionLine;
+exports.formatCurrentLine = formatCurrentLine;
+exports.writeJsonResponse = writeJsonResponse;
+exports.readJsonBody = readJsonBody;
+exports.appendLog = appendLog;
+exports.buildRefDisplayText = buildRefDisplayText;
+exports.makeTransportLabel = makeTransportLabel;
+exports.isDaemonErrorResponse = isDaemonErrorResponse;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const errors_1 = require("./errors");
+function parseArgs(argv) {
+    const positional = [];
+    const flags = {};
+    const booleanFlags = new Set(["interactive", "exact", "annotate"]);
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === "-i") {
+            flags.interactive = true;
+            continue;
+        }
+        if (!token.startsWith("--")) {
+            positional.push(token);
+            continue;
+        }
+        const flagName = token.slice(2);
+        if (booleanFlags.has(flagName)) {
+            flags[flagName] = true;
+            continue;
+        }
+        const next = argv[index + 1];
+        if (!next || next.startsWith("--")) {
+            throw new errors_1.AppError("BAD_REQUEST", `Missing value for ${token}`, 400);
+        }
+        flags[flagName] = next;
+        index += 1;
+    }
+    return { positional, flags };
+}
+function getFlagString(parsed, name) {
+    const value = parsed.flags[name];
+    return typeof value === "string" ? value : undefined;
+}
+function getFlagBoolean(parsed, name) {
+    return parsed.flags[name] === true;
+}
+function generateSessionId(existingIds) {
+    const existing = new Set(existingIds);
+    let counter = 1;
+    while (existing.has(`s${counter}`)) {
+        counter += 1;
+    }
+    return `s${counter}`;
+}
+function ensureAbsolutePath(baseDir, targetPath) {
+    return node_path_1.default.isAbsolute(targetPath) ? targetPath : node_path_1.default.resolve(baseDir, targetPath);
+}
+function isRefTarget(target) {
+    return /^@e\d+$/.test(target);
+}
+function isNumericToken(token) {
+    return /^-?\d+$/.test(token);
+}
+function formatSnapshotItem(item) {
+    const flags = item.flags && item.flags.length > 0 ? ` ${item.flags.map((flag) => `[${flag}]`).join(" ")}` : "";
+    return `- ${item.kind} "${item.text}"${flags} [ref=${item.ref}]`;
+}
+function formatProxyLabel(proxy) {
+    if (!proxy) {
+        return undefined;
+    }
+    if (proxy.mode === "none") {
+        return undefined;
+    }
+    if (proxy.mode === "gologin") {
+        return proxy.country ? `gologin:${proxy.country}` : "gologin";
+    }
+    if (proxy.host && proxy.port) {
+        return `${proxy.mode}:${proxy.host}:${proxy.port}`;
+    }
+    return proxy.mode;
+}
+function formatSessionLine(session) {
+    const prefix = session.active ? "*" : "-";
+    const profile = session.profileId ? ` profile=${session.profileId}` : "";
+    const snapshotState = session.hasSnapshot ? (session.staleSnapshot ? "stale" : "fresh") : "none";
+    const proxy = formatProxyLabel(session.proxy);
+    const proxyToken = proxy ? ` proxy=${proxy}` : "";
+    const idleTimeout = session.idleTimeoutMs !== undefined ? ` idleTimeoutMs=${session.idleTimeoutMs}` : "";
+    const liveView = session.liveViewUrl ? ` liveview=${session.liveViewUrl}` : "";
+    const screenshot = session.lastScreenshotPath ? ` shot=${session.lastScreenshotPath}` : "";
+    const pdf = session.lastPdfPath ? ` pdf=${session.lastPdfPath}` : "";
+    return `${prefix} session=${session.sessionId}${profile} url=${session.url} snapshot=${snapshotState}${proxyToken}${idleTimeout}${liveView}${screenshot}${pdf}`;
+}
+function formatCurrentLine(session) {
+    const profile = session.profileId ? ` profile=${session.profileId}` : "";
+    const snapshotState = session.hasSnapshot ? (session.staleSnapshot ? "stale" : "fresh") : "none";
+    const proxy = formatProxyLabel(session.proxy);
+    const proxyToken = proxy ? ` proxy=${proxy}` : "";
+    const idleTimeout = session.idleTimeoutMs !== undefined ? ` idleTimeoutMs=${session.idleTimeoutMs}` : "";
+    const liveView = session.liveViewUrl ? ` liveview=${session.liveViewUrl}` : "";
+    const screenshot = session.lastScreenshotPath ? ` shot=${session.lastScreenshotPath}` : "";
+    const pdf = session.lastPdfPath ? ` pdf=${session.lastPdfPath}` : "";
+    return `session=${session.sessionId}${profile} url=${session.url} snapshot=${snapshotState}${proxyToken}${idleTimeout}${liveView}${screenshot}${pdf}`;
+}
+function writeJsonResponse(response, statusCode, payload) {
+    response.statusCode = statusCode;
+    response.setHeader("content-type", "application/json; charset=utf-8");
+    response.end(JSON.stringify(payload));
+}
+function readJsonBody(request) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        request.on("data", (chunk) => chunks.push(chunk));
+        request.on("end", () => {
+            if (chunks.length === 0) {
+                resolve(undefined);
+                return;
+            }
+            try {
+                resolve(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+            }
+            catch {
+                reject(new errors_1.AppError("BAD_REQUEST", "Request body must be valid JSON", 400));
+            }
+        });
+        request.on("error", reject);
+    });
+}
+function appendLog(logPath, line) {
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(logPath), { recursive: true });
+    node_fs_1.default.appendFileSync(logPath, `${new Date().toISOString()} ${line}\n`, "utf8");
+}
+function buildRefDisplayText(descriptor) {
+    return descriptor.accessibleName ?? descriptor.text ?? descriptor.placeholder ?? descriptor.name ?? "";
+}
+function makeTransportLabel(transport) {
+    if (transport.kind === "socket") {
+        return `socket:${transport.socketPath}`;
+    }
+    return `http://${transport.host}:${transport.port}`;
+}
+function isDaemonErrorResponse(payload) {
+    if (!payload || typeof payload !== "object") {
+        return false;
+    }
+    const value = payload;
+    return (typeof value.code === "string" &&
+        typeof value.message === "string" &&
+        typeof value.status === "number");
+}

package/examples/agent-flow.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ -z "${GOLOGIN_TOKEN:-}" ]]; then
+  echo "GOLOGIN_TOKEN is required" >&2
+  exit 1
+fi
+
+node dist/cli.js open https://example.com --idle-timeout-ms 300000
+node dist/cli.js snapshot -i
+node dist/cli.js current
+node dist/cli.js get title
+node dist/cli.js find text "Learn more" click
+node dist/cli.js scroll down 400
+node dist/cli.js wait 1000
+node dist/cli.js sessions
+node dist/cli.js pdf examples/example-page.pdf
+node dist/cli.js screenshot examples/example-page.png --annotate
+node dist/cli.js close

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "gologin-agent-browser-cli",
+  "version": "0.1.0",
+  "description": "Agent-native cloud browser automation CLI for GoLogin",
+  "main": "dist/cli.js",
+  "types": "dist/lib/types.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "examples/agent-flow.sh"
+  ],
+  "bin": {
+    "gologin-agent-browser": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "dev:cli": "tsx src/cli.ts",
+    "dev:daemon": "tsx src/daemon/server.ts",
+    "test": "tsx --test tests/**/*.test.ts",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/easync/agent-browser.git"
+  },
+  "homepage": "https://gitlab.com/easync/agent-browser",
+  "bugs": {
+    "url": "https://gitlab.com/easync/agent-browser/-/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "gologin",
+    "agent",
+    "cli",
+    "cloud-browser",
+    "anti-detect",
+    "fingerprint",
+    "proxy",
+    "playwright",
+    "browser"
+  ],
+  "author": "GoLogin",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "playwright": "^1.58.2"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2"
+  }
+}