gologin-agent-browser-cli 0.2.0

package/dist/commands/scroll.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext } from "../lib/types";
+export declare function runScrollCommand(context: CommandContext, argv: string[]): Promise<void>;

package/dist/commands/scroll.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runScrollCommand = runScrollCommand;
+const errors_1 = require("../lib/errors");
+const utils_1 = require("../lib/utils");
+const shared_1 = require("./shared");
+const SCROLL_DIRECTIONS = new Set(["up", "down", "left", "right"]);
+async function runScrollCommand(context, argv) {
+    const parsed = (0, utils_1.parseArgs)(argv);
+    const direction = parsed.positional[0];
+    const maybePixels = parsed.positional[1];
+    const target = (0, utils_1.getFlagString)(parsed, "target");
+    const sessionId = (0, utils_1.getFlagString)(parsed, "session");
+    if (!direction || !SCROLL_DIRECTIONS.has(direction)) {
+        throw new errors_1.AppError("BAD_REQUEST", "Usage: gologin-agent-browser scroll <up|down|left|right> [pixels] [--target <target>] [--session <sessionId>]", 400);
+    }
+    if (maybePixels && !(0, utils_1.isNumericToken)(maybePixels)) {
+        throw new errors_1.AppError("BAD_REQUEST", "scroll pixels must be a number", 400);
+    }
+    const pixels = maybePixels ? Number(maybePixels) : undefined;
+    const resolvedSessionId = await (0, shared_1.resolveSessionId)(context, sessionId);
+    const response = await context.client.request("POST", `/sessions/${resolvedSessionId}/scroll`, { direction, pixels, target });
+    const targetSuffix = response.target ? ` target=${response.target}` : "";
+    context.stdout.write(`scrolled direction=${response.direction} pixels=${response.pixels}${targetSuffix} session=${response.sessionId} url=${response.url}\n`);
+}

package/dist/commands/scrollIntoView.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext } from "../lib/types";
+export declare function runScrollIntoViewCommand(context: CommandContext, argv: string[]): Promise<void>;

package/dist/commands/scrollIntoView.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runScrollIntoViewCommand = runScrollIntoViewCommand;
+const errors_1 = require("../lib/errors");
+const utils_1 = require("../lib/utils");
+const shared_1 = require("./shared");
+async function runScrollIntoViewCommand(context, argv) {
+    const parsed = (0, utils_1.parseArgs)(argv);
+    const target = parsed.positional[0];
+    const sessionId = (0, utils_1.getFlagString)(parsed, "session");
+    if (!target) {
+        throw new errors_1.AppError("BAD_REQUEST", "Usage: gologin-agent-browser scrollintoview <target> [--session <sessionId>]", 400);
+    }
+    const resolvedSessionId = await (0, shared_1.resolveSessionId)(context, sessionId);
+    const response = await context.client.request("POST", `/sessions/${resolvedSessionId}/scrollintoview`, { target });
+    (0, shared_1.writeActionResult)(context, "scrolled-into-view", target, response);
+}

package/dist/commands/select.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext } from "../lib/types";
+export declare function runSelectCommand(context: CommandContext, argv: string[]): Promise<void>;

package/dist/commands/select.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSelectCommand = runSelectCommand;
+const errors_1 = require("../lib/errors");
+const utils_1 = require("../lib/utils");
+const shared_1 = require("./shared");
+async function runSelectCommand(context, argv) {
+    const parsed = (0, utils_1.parseArgs)(argv);
+    const target = parsed.positional[0];
+    const value = parsed.positional.slice(1).join(" ");
+    const sessionId = (0, utils_1.getFlagString)(parsed, "session");
+    if (!target || !value) {
+        throw new errors_1.AppError("BAD_REQUEST", "Usage: gologin-agent-browser select <target> <value> [--session <sessionId>]", 400);
+    }
+    const resolvedSessionId = await (0, shared_1.resolveSessionId)(context, sessionId);
+    const response = await context.client.request("POST", `/sessions/${resolvedSessionId}/select`, { target, value });
+    (0, shared_1.writeActionResult)(context, "selected", target, response);
+}

package/dist/commands/sessions.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext } from "../lib/types";
+export declare function runSessionsCommand(context: CommandContext, argv: string[]): Promise<void>;

package/dist/commands/sessions.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSessionsCommand = runSessionsCommand;
+const utils_1 = require("../lib/utils");
+async function runSessionsCommand(context, argv) {
+    (0, utils_1.parseArgs)(argv);
+    const response = await context.client.request("GET", "/sessions");
+    if (response.sessions.length === 0) {
+        context.stdout.write("no sessions\n");
+        return;
+    }
+    for (const session of response.sessions) {
+        context.stdout.write(`${(0, utils_1.formatSessionLine)(session)}\n`);
+    }
+}

package/dist/commands/shared.d.ts

@@ -0,0 +1,7 @@
+import type { ActionResponse, CommandContext, StorageScope } from "../lib/types";
+export declare function resolveSessionId(context: CommandContext, explicitSessionId?: string): Promise<string>;
+export declare function writeActionResult(context: CommandContext, verb: string, target: string, response: ActionResponse): void;
+export declare function parseStorageScope(value: string | undefined): StorageScope | undefined;
+export declare function readJsonFile<T>(context: CommandContext, targetPath: string): T;
+export declare function writeJsonFile(context: CommandContext, targetPath: string, payload: unknown): string;
+export declare function writeJsonStdout(context: CommandContext, payload: unknown): void;

package/dist/commands/shared.js

@@ -0,0 +1,51 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveSessionId = resolveSessionId;
+exports.writeActionResult = writeActionResult;
+exports.parseStorageScope = parseStorageScope;
+exports.readJsonFile = readJsonFile;
+exports.writeJsonFile = writeJsonFile;
+exports.writeJsonStdout = writeJsonStdout;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const errors_1 = require("../lib/errors");
+const utils_1 = require("../lib/utils");
+async function resolveSessionId(context, explicitSessionId) {
+    if (explicitSessionId) {
+        return explicitSessionId;
+    }
+    return (await context.client.request("GET", "/sessions/current")).sessionId;
+}
+function writeActionResult(context, verb, target, response) {
+    context.stdout.write(`${verb} target=${target} session=${response.sessionId} url=${response.url} snapshot=${response.staleSnapshot ? "stale" : "fresh"}\n`);
+}
+function parseStorageScope(value) {
+    if (!value) {
+        return undefined;
+    }
+    if (value === "local" || value === "session" || value === "both") {
+        return value;
+    }
+    throw new errors_1.AppError("BAD_REQUEST", "--scope must be one of local, session, or both", 400);
+}
+function readJsonFile(context, targetPath) {
+    const absolutePath = (0, utils_1.ensureAbsolutePath)(context.cwd, targetPath);
+    try {
+        return JSON.parse(node_fs_1.default.readFileSync(absolutePath, "utf8"));
+    }
+    catch (error) {
+        throw new errors_1.AppError("BAD_REQUEST", `Failed to read JSON file ${absolutePath}: ${error instanceof Error ? error.message : String(error)}`, 400);
+    }
+}
+function writeJsonFile(context, targetPath, payload) {
+    const absolutePath = (0, utils_1.ensureAbsolutePath)(context.cwd, targetPath);
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(absolutePath), { recursive: true });
+    node_fs_1.default.writeFileSync(absolutePath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+    return absolutePath;
+}
+function writeJsonStdout(context, payload) {
+    context.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+}

package/dist/commands/snapshot.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext } from "../lib/types";
+export declare function runSnapshotCommand(context: CommandContext, argv: string[]): Promise<void>;

package/dist/commands/snapshot.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSnapshotCommand = runSnapshotCommand;
+const utils_1 = require("../lib/utils");
+async function runSnapshotCommand(context, argv) {
+    const parsed = (0, utils_1.parseArgs)(argv);
+    const sessionId = (0, utils_1.getFlagString)(parsed, "session");
+    const interactive = (0, utils_1.getFlagBoolean)(parsed, "interactive");
+    const resolvedSessionId = sessionId ??
+        (await context.client.request("GET", "/sessions/current")).sessionId;
+    const response = await context.client.request("POST", `/sessions/${resolvedSessionId}/snapshot`, interactive ? { interactive: true } : {});
+    context.stdout.write(`session=${response.sessionId} url=${response.url}\n`);
+    for (const item of response.items) {
+        context.stdout.write(`${(0, utils_1.formatSnapshotItem)(item)}\n`);
+    }
+}

package/dist/commands/storageClear.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext } from "../lib/types";
+export declare function runStorageClearCommand(context: CommandContext, argv: string[]): Promise<void>;

package/dist/commands/storageClear.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runStorageClearCommand = runStorageClearCommand;
+const utils_1 = require("../lib/utils");
+const shared_1 = require("./shared");
+async function runStorageClearCommand(context, argv) {
+    const parsed = (0, utils_1.parseArgs)(argv);
+    const sessionId = (0, utils_1.getFlagString)(parsed, "session");
+    const scope = (0, shared_1.parseStorageScope)((0, utils_1.getFlagString)(parsed, "scope"));
+    const resolvedSessionId = await (0, shared_1.resolveSessionId)(context, sessionId);
+    const response = await context.client.request("POST", `/sessions/${resolvedSessionId}/storage-clear`, { scope });
+    context.stdout.write(`origin=${response.origin} scope=${response.scope} session=${response.sessionId} url=${response.url} snapshot=${response.staleSnapshot ? "stale" : "fresh"}\n`);
+}

package/dist/commands/storageExport.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext } from "../lib/types";
+export declare function runStorageExportCommand(context: CommandContext, argv: string[]): Promise<void>;

package/dist/commands/storageExport.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runStorageExportCommand = runStorageExportCommand;
+const utils_1 = require("../lib/utils");
+const shared_1 = require("./shared");
+async function runStorageExportCommand(context, argv) {
+    const parsed = (0, utils_1.parseArgs)(argv);
+    const sessionId = (0, utils_1.getFlagString)(parsed, "session");
+    const outputPath = parsed.positional[0];
+    const json = (0, utils_1.getFlagBoolean)(parsed, "json");
+    const scope = (0, shared_1.parseStorageScope)((0, utils_1.getFlagString)(parsed, "scope"));
+    const resolvedSessionId = await (0, shared_1.resolveSessionId)(context, sessionId);
+    const response = await context.client.request("POST", `/sessions/${resolvedSessionId}/storage-export`, { scope });
+    if (outputPath) {
+        const savedPath = (0, shared_1.writeJsonFile)(context, outputPath, response.state);
+        context.stdout.write(`${savedPath}\n`);
+        return;
+    }
+    if (json) {
+        (0, shared_1.writeJsonStdout)(context, response.state);
+        return;
+    }
+    context.stdout.write(`${JSON.stringify(response.state, null, 2)}\n`);
+}

package/dist/commands/storageImport.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext } from "../lib/types";
+export declare function runStorageImportCommand(context: CommandContext, argv: string[]): Promise<void>;

package/dist/commands/storageImport.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runStorageImportCommand = runStorageImportCommand;
+const errors_1 = require("../lib/errors");
+const utils_1 = require("../lib/utils");
+const shared_1 = require("./shared");
+async function runStorageImportCommand(context, argv) {
+    const parsed = (0, utils_1.parseArgs)(argv);
+    const sessionId = (0, utils_1.getFlagString)(parsed, "session");
+    const storagePath = parsed.positional[0];
+    const scope = (0, shared_1.parseStorageScope)((0, utils_1.getFlagString)(parsed, "scope"));
+    const clear = (0, utils_1.getFlagBoolean)(parsed, "clear");
+    if (!storagePath) {
+        throw new errors_1.AppError("BAD_REQUEST", "Usage: gologin-agent-browser storage-import <storage.json> [--scope <local|session|both>] [--clear] [--session <sessionId>]", 400);
+    }
+    const state = (0, shared_1.readJsonFile)(context, storagePath);
+    const resolvedSessionId = await (0, shared_1.resolveSessionId)(context, sessionId);
+    const response = await context.client.request("POST", `/sessions/${resolvedSessionId}/storage-import`, { state, scope, clear });
+    context.stdout.write(`origin=${response.origin} localKeys=${response.localKeys} sessionKeys=${response.sessionKeys} session=${response.sessionId} url=${response.url} snapshot=${response.staleSnapshot ? "stale" : "fresh"}\n`);
+}

package/dist/commands/tabClose.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext } from "../lib/types";
+export declare function runTabCloseCommand(context: CommandContext, argv: string[]): Promise<void>;

package/dist/commands/tabClose.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runTabCloseCommand = runTabCloseCommand;
+const errors_1 = require("../lib/errors");
+const utils_1 = require("../lib/utils");
+const shared_1 = require("./shared");
+async function runTabCloseCommand(context, argv) {
+    const parsed = (0, utils_1.parseArgs)(argv);
+    const sessionId = (0, utils_1.getFlagString)(parsed, "session");
+    const rawIndex = parsed.positional[0];
+    let index;
+    if (rawIndex !== undefined) {
+        index = Number(rawIndex);
+        if (!Number.isInteger(index) || index <= 0) {
+            throw new errors_1.AppError("BAD_REQUEST", "tab index must be a positive integer", 400);
+        }
+    }
+    const resolvedSessionId = await (0, shared_1.resolveSessionId)(context, sessionId);
+    const response = await context.client.request("POST", `/sessions/${resolvedSessionId}/tabclose`, { index });
+    context.stdout.write(`closedTab=${response.closedTabIndex} activeTab=${response.activeTabIndex} session=${response.sessionId} url=${response.url} snapshot=${response.staleSnapshot ? "stale" : "fresh"}\n`);
+}

package/dist/commands/tabFocus.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext } from "../lib/types";
+export declare function runTabFocusCommand(context: CommandContext, argv: string[]): Promise<void>;

package/dist/commands/tabFocus.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runTabFocusCommand = runTabFocusCommand;
+const errors_1 = require("../lib/errors");
+const utils_1 = require("../lib/utils");
+const shared_1 = require("./shared");
+async function runTabFocusCommand(context, argv) {
+    const parsed = (0, utils_1.parseArgs)(argv);
+    const sessionId = (0, utils_1.getFlagString)(parsed, "session");
+    const rawIndex = parsed.positional[0];
+    if (!rawIndex) {
+        throw new errors_1.AppError("BAD_REQUEST", "Usage: gologin-agent-browser tabfocus <index> [--session <sessionId>]", 400);
+    }
+    const index = Number(rawIndex);
+    if (!Number.isInteger(index) || index <= 0) {
+        throw new errors_1.AppError("BAD_REQUEST", "tab index must be a positive integer", 400);
+    }
+    const resolvedSessionId = await (0, shared_1.resolveSessionId)(context, sessionId);
+    const response = await context.client.request("POST", `/sessions/${resolvedSessionId}/tabfocus`, { index });
+    context.stdout.write(`tab=${response.tabIndex} session=${response.sessionId} url=${response.url} snapshot=${response.staleSnapshot ? "stale" : "fresh"}\n`);
+}

package/dist/commands/tabOpen.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext } from "../lib/types";
+export declare function runTabOpenCommand(context: CommandContext, argv: string[]): Promise<void>;

package/dist/commands/tabOpen.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runTabOpenCommand = runTabOpenCommand;
+const utils_1 = require("../lib/utils");
+const shared_1 = require("./shared");
+async function runTabOpenCommand(context, argv) {
+    const parsed = (0, utils_1.parseArgs)(argv);
+    const sessionId = (0, utils_1.getFlagString)(parsed, "session");
+    const url = parsed.positional[0];
+    const resolvedSessionId = await (0, shared_1.resolveSessionId)(context, sessionId);
+    const response = await context.client.request("POST", `/sessions/${resolvedSessionId}/tabopen`, { url });
+    context.stdout.write(`tab=${response.tabIndex} session=${response.sessionId} url=${response.url} snapshot=${response.staleSnapshot ? "stale" : "fresh"}\n`);
+}

package/dist/commands/tabs.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext } from "../lib/types";
+export declare function runTabsCommand(context: CommandContext, argv: string[]): Promise<void>;

package/dist/commands/tabs.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runTabsCommand = runTabsCommand;
+const utils_1 = require("../lib/utils");
+const shared_1 = require("./shared");
+async function runTabsCommand(context, argv) {
+    const parsed = (0, utils_1.parseArgs)(argv);
+    const sessionId = (0, utils_1.getFlagString)(parsed, "session");
+    const resolvedSessionId = await (0, shared_1.resolveSessionId)(context, sessionId);
+    const response = await context.client.request("GET", `/sessions/${resolvedSessionId}/tabs`);
+    context.stdout.write(`session=${response.sessionId} tabs=${response.tabs.length}\n`);
+    for (const tab of response.tabs) {
+        const prefix = tab.active ? "*" : "-";
+        const title = tab.title ? ` title=${JSON.stringify(tab.title)}` : "";
+        context.stdout.write(`${prefix} tab=${tab.index} url=${tab.url}${title}\n`);
+    }
+}

package/dist/commands/type.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext } from "../lib/types";
+export declare function runTypeCommand(context: CommandContext, argv: string[]): Promise<void>;

package/dist/commands/type.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runTypeCommand = runTypeCommand;
+const errors_1 = require("../lib/errors");
+const utils_1 = require("../lib/utils");
+const shared_1 = require("./shared");
+async function runTypeCommand(context, argv) {
+    const parsed = (0, utils_1.parseArgs)(argv);
+    const target = parsed.positional[0];
+    const text = parsed.positional.slice(1).join(" ");
+    const sessionId = (0, utils_1.getFlagString)(parsed, "session");
+    if (!target || !text) {
+        throw new errors_1.AppError("BAD_REQUEST", 'Usage: gologin-agent-browser type <target> <text> [--session <sessionId>]', 400);
+    }
+    const resolvedSessionId = await (0, shared_1.resolveSessionId)(context, sessionId);
+    const response = await context.client.request("POST", `/sessions/${resolvedSessionId}/type`, { target, text });
+    (0, shared_1.writeActionResult)(context, "typed", target, response);
+}

package/dist/commands/uncheck.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext } from "../lib/types";
+export declare function runUncheckCommand(context: CommandContext, argv: string[]): Promise<void>;

package/dist/commands/uncheck.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runUncheckCommand = runUncheckCommand;
+const errors_1 = require("../lib/errors");
+const utils_1 = require("../lib/utils");
+const shared_1 = require("./shared");
+async function runUncheckCommand(context, argv) {
+    const parsed = (0, utils_1.parseArgs)(argv);
+    const target = parsed.positional[0];
+    const sessionId = (0, utils_1.getFlagString)(parsed, "session");
+    if (!target) {
+        throw new errors_1.AppError("BAD_REQUEST", "Usage: gologin-agent-browser uncheck <target> [--session <sessionId>]", 400);
+    }
+    const resolvedSessionId = await (0, shared_1.resolveSessionId)(context, sessionId);
+    const response = await context.client.request("POST", `/sessions/${resolvedSessionId}/uncheck`, { target });
+    (0, shared_1.writeActionResult)(context, "unchecked", target, response);
+}

package/dist/commands/upload.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext } from "../lib/types";
+export declare function runUploadCommand(context: CommandContext, argv: string[]): Promise<void>;

package/dist/commands/upload.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runUploadCommand = runUploadCommand;
+const errors_1 = require("../lib/errors");
+const utils_1 = require("../lib/utils");
+const shared_1 = require("./shared");
+async function runUploadCommand(context, argv) {
+    const parsed = (0, utils_1.parseArgs)(argv);
+    const target = parsed.positional[0];
+    const files = parsed.positional.slice(1).map((file) => (0, utils_1.ensureAbsolutePath)(context.cwd, file));
+    const sessionId = (0, utils_1.getFlagString)(parsed, "session");
+    if (!target || files.length === 0) {
+        throw new errors_1.AppError("BAD_REQUEST", "Usage: gologin-agent-browser upload <target> <file...> [--session <sessionId>]", 400);
+    }
+    const resolvedSessionId = await (0, shared_1.resolveSessionId)(context, sessionId);
+    const response = await context.client.request("POST", `/sessions/${resolvedSessionId}/upload`, { target, files });
+    context.stdout.write(`uploaded files=${response.files.length} target=${target} session=${response.sessionId} url=${response.url} snapshot=${response.staleSnapshot ? "stale" : "fresh"}\n`);
+}

package/dist/commands/wait.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext } from "../lib/types";
+export declare function runWaitCommand(context: CommandContext, argv: string[]): Promise<void>;

package/dist/commands/wait.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runWaitCommand = runWaitCommand;
+const errors_1 = require("../lib/errors");
+const utils_1 = require("../lib/utils");
+const shared_1 = require("./shared");
+async function runWaitCommand(context, argv) {
+    const parsed = (0, utils_1.parseArgs)(argv);
+    const first = parsed.positional[0];
+    const sessionId = (0, utils_1.getFlagString)(parsed, "session");
+    const text = (0, utils_1.getFlagString)(parsed, "text");
+    const urlPattern = (0, utils_1.getFlagString)(parsed, "url");
+    const loadState = (0, utils_1.getFlagString)(parsed, "load");
+    const body = {};
+    if (first) {
+        if ((0, utils_1.isNumericToken)(first)) {
+            body.timeoutMs = Number(first);
+        }
+        else {
+            body.target = first;
+        }
+    }
+    if (text) {
+        body.text = text;
+    }
+    if (urlPattern) {
+        body.urlPattern = urlPattern;
+    }
+    if (loadState === "load" || loadState === "domcontentloaded" || loadState === "networkidle") {
+        body.loadState = loadState;
+    }
+    else if (loadState) {
+        throw new errors_1.AppError("BAD_REQUEST", "wait --load must be load, domcontentloaded, or networkidle", 400);
+    }
+    if (!body.target && !body.text && !body.urlPattern && !body.loadState && body.timeoutMs === undefined) {
+        throw new errors_1.AppError("BAD_REQUEST", "Usage: gologin-agent-browser wait <target|ms> [--text <text>] [--url <pattern>] [--load <state>] [--session <sessionId>]", 400);
+    }
+    const resolvedSessionId = await (0, shared_1.resolveSessionId)(context, sessionId);
+    const response = await context.client.request("POST", `/sessions/${resolvedSessionId}/wait`, body);
+    context.stdout.write(`waited session=${response.sessionId} url=${response.url} for=${response.waitedFor}\n`);
+}

package/dist/daemon/browser.d.ts

@@ -0,0 +1,67 @@
+import { type Locator, type Page } from "playwright";
+import type { AgentConfig, BrowserCookie, CookiesResponse, EvalResponse, GetKind, ProxyConfig, ProxySummary, RefDescriptor, ScrollDirection, SemanticFindAction, SemanticLocatorQuery, SessionRecord, StorageScope, StorageState, TabSummary, WaitLoadState } from "../lib/types";
+export declare function buildConnectUrl(config: AgentConfig, token: string, profileId?: string): string;
+export declare function toPlaywrightCdpUrl(connectUrl: string): string;
+export declare function createQuickProfile(token: string, sessionId: string): Promise<string>;
+export declare function createManagedProfile(token: string, sessionId: string, proxy?: ProxyConfig): Promise<{
+    profileId: string;
+    proxy?: ProxySummary;
+}>;
+export declare function deleteProfile(token: string, profileId: string): Promise<void>;
+export declare function getCloudLiveViewUrl(token: string, profileId: string): Promise<string | undefined>;
+export declare function getCloudProfileProxy(token: string, profileId: string): Promise<ProxySummary | undefined>;
+export declare function connectToBrowser(config: AgentConfig, token: string, profileId?: string): Promise<Pick<SessionRecord, "browser" | "context" | "page" | "connectUrl">>;
+export declare function navigatePage(page: Page, url: string, timeoutMs: number): Promise<string>;
+export declare function resolveDescriptorLocator(page: Page, descriptor: RefDescriptor): Promise<Locator>;
+export declare function resolveSelectorLocator(page: Page, selector: string, timeoutMs: number): Promise<Locator>;
+export declare function resolveSemanticLocator(page: Page, query: SemanticLocatorQuery, timeoutMs: number): Promise<Locator>;
+export declare function performLocatorAction(page: Page, locator: Locator, action: SemanticFindAction | "focus" | "dblclick" | "select" | "check" | "uncheck", timeoutMs: number, value?: string): Promise<string | undefined>;
+export declare function actionMutatesSnapshot(action: SemanticFindAction): boolean;
+export declare function pressKey(page: Page, key: string, timeoutMs: number): Promise<void>;
+export declare function waitForTarget(locator: Locator, timeoutMs: number): Promise<void>;
+export declare function waitForPageText(page: Page, text: string, timeoutMs: number, exact?: boolean): Promise<void>;
+export declare function waitForPageUrl(page: Page, urlPattern: string, timeoutMs: number): Promise<void>;
+export declare function waitForPageLoad(page: Page, state: WaitLoadState, timeoutMs: number): Promise<void>;
+export declare function readLocatorValue(locator: Locator, kind: GetKind, timeoutMs: number): Promise<string>;
+export declare function scrollPage(page: Page, direction: ScrollDirection, pixels: number): Promise<void>;
+export declare function scrollElement(locator: Locator, direction: ScrollDirection, pixels: number): Promise<void>;
+export declare function scrollLocatorIntoView(locator: Locator, timeoutMs: number): Promise<void>;
+export declare function uploadFiles(locator: Locator, files: string[], timeoutMs: number): Promise<void>;
+export declare function savePdf(page: Page, targetPath: string): Promise<void>;
+export declare function captureScreenshot(page: Page, targetPath: string, timeoutMs: number): Promise<void>;
+export declare function listTabs(session: SessionRecord): Promise<TabSummary[]>;
+export declare function openTab(session: SessionRecord, url: string | undefined, timeoutMs: number): Promise<{
+    page: Page;
+    tabIndex: number;
+}>;
+export declare function focusTab(session: SessionRecord, index: number): Promise<{
+    page: Page;
+    tabIndex: number;
+}>;
+export declare function closeTab(session: SessionRecord, index?: number): Promise<{
+    page: Page;
+    closedTabIndex: number;
+    activeTabIndex: number;
+}>;
+export declare function navigateHistory(page: Page, direction: "back" | "forward" | "reload", timeoutMs: number): Promise<string>;
+export declare function readCookies(session: SessionRecord): Promise<CookiesResponse["cookies"]>;
+export declare function importCookies(session: SessionRecord, cookies: BrowserCookie[]): Promise<number>;
+export declare function clearCookies(session: SessionRecord): Promise<number>;
+export declare function exportStorageState(page: Page, scope?: StorageScope): Promise<StorageState>;
+export declare function importStorageState(page: Page, state: StorageState, scope?: StorageScope, clear?: boolean): Promise<{
+    origin: string;
+    localKeys: number;
+    sessionKeys: number;
+}>;
+export declare function clearStorageState(page: Page, scope?: StorageScope): Promise<{
+    origin: string;
+    scope: StorageScope;
+}>;
+export declare function evaluateExpression(page: Page, expression: string): Promise<EvalResponse["value"]>;
+export declare function annotatePageWithRefs(page: Page, refs: Array<{
+    ref: string;
+    x: number;
+    y: number;
+}>): Promise<void>;
+export declare function clearPageAnnotations(page: Page): Promise<void>;
+export declare function closeSessionHandles(session: SessionRecord): Promise<void>;