clearcote 0.33.0 → 0.35.0

package/README.md

@@ -5,7 +5,8 @@ open, reproducible, anti-fingerprint Chromium build. `launch()` returns a standa
 `Browser`, so migrating is a one-line import change.
 
 The verified Clearcote binary is **auto-downloaded and SHA-256 checked** on first use, then cached —
-you don't manage zips or paths.
+you don't manage zips or paths. Or run the same code on a hosted Clearcote browser with
+`launch({ cloud: true })`: see [Local or cloud](#local-or-cloud).
 
 > **Platform:** Clearcote ships **Windows x64** and **Linux x64** binaries; `launch()` runs on both
 > and the SDK auto-downloads the right one for your OS. On Linux the persona is Linux-native (Linux
@@ -134,6 +135,7 @@ npx clearcote login [key]      # validates the key, saves it to ~/.clearcote/lic
 npx clearcote logout
 npx clearcote clear-cache
 npx clearcote serve [--port 9222] ...
+npx clearcote cloud run|sessions|stop|events|recording|profile sync|webhooks ...   # the hosted API, see Local or cloud
 ```
 
 `info` never downloads: it reports the SDK, the cached builds, which engine features the binary supports, a launch test (skipped with `--quick`), licence seats, fonts and missing system libraries.
@@ -305,6 +307,109 @@ don't set `acceptLanguage` explicitly. See the
 [collector README](../../tools/fingerprint-collect/README.md) for the full schema and what each
 field drives.
 
+## Local or cloud
+
+The same `launch()` runs the browser on this machine or on Clearcote's servers. One flag picks which,
+and both resolve to the same Playwright `Browser`:
+
+```ts
+import { launch } from "clearcote";
+
+const browser = await launch({ cloud: true, country: "us", identity: "acct-1", humanize: true });
+const page = await browser.newPage();
+await page.goto("https://example.com");
+await browser.close();               // disconnects and ends the hosted session
+```
+
+Leave `cloud` unset and set `CLEARCOTE_CLOUD=1` to move existing code to the cloud without editing
+it. The API key comes from `apiKey` or `CLEARCOTE_API_KEY`, and `CLEARCOTE_API_URL` points the SDK at
+another server (https only: plain `http://` is accepted for `127.0.0.1`, `::1` and `localhost` alone,
+so the key never crosses a network unencrypted).
+
+What changes in the cloud:
+
+- **Options** keep the API's names: `fingerprint`, `identity`, `platform`, `brand`, `timezone`,
+  `locale` (or `acceptLanguage`), `geoip`, `headless`, `lightStealth`, `proxy` (`"managed"`, a URL, or
+  `{ server, username, password }`), `country`/`state`/`city`, `proxySession`, `timeoutSec`,
+  `idleTimeoutSec`, `maxGb`, `version`, `profile`, `url`, `adblock`, `keepAlive`, `record`, `note`,
+  `worker`. `humanize` and `showCursor` run in the SDK, exactly as for a local browser.
+- **Local-only options are refused, by name.** `executablePath`, `args`, `userDataDir`, `extensions`,
+  `ignoreDefaultArgs`, the finer persona switches (`gpuVendor`, `webrtcIp`, ...) and the licence
+  options throw `<name> is not available for cloud browsers` before anything starts.
+- **Profiles are cloud profiles.** `profile: "acct-1"` loads the cookies of a named cloud profile, and
+  `launchPersistentContext({ cloud: true, profile: "acct-1" })` resolves to a context that also saves
+  them back when it closes. Fill one from a browser you are logged in to with `profiles.sync` (below).
+- **The session.** `cloudSessionOf(browser)` (also `browser.cloudSession`) holds its `id`, `worker` and
+  `expiresAt`. `close()` disconnects and ends the session; a `keepAlive: true` session is left running
+  (stop it with `cloud.browsers.stop(id)`).
+
+### The Cloud client
+
+Everything else the hosted API does is on `Cloud`:
+
+```ts
+import { Cloud } from "clearcote";
+
+const cloud = new Cloud();                        // CLEARCOTE_API_KEY
+
+// An agent run: a task in, JSON out
+const run = await cloud.runs.create("Log in with {{password}} and read the current plan's price", {
+  url: "https://example.com/login",
+  schema: { type: "object", properties: { price: { type: "string" } } },
+  secrets: { password: { value: "s3cret", domains: ["example.com"] } },   // the model never sees it
+});
+console.log(run.status, run.result.output, run.costEur.total);
+
+// Copy a logged-in state into a cloud profile: only the cookies a browser would use on the domains you
+// name (theirs, their subdomains', and parent-domain ones such as .example.com for www.example.com)
+await cloud.profiles.sync("acct-1", { loginUrl: "https://example.com/login", domains: ["example.com"] });
+
+// Recordings, the event timeline, hand-off to a person
+const s = await cloud.browsers.create({ record: true });
+await cloud.browsers.events(s.id);                // { events: [...], next }
+await cloud.browsers.downloadRecording(s.id, "session.mp4");
+```
+
+- `browsers`: `create(options)`, `get(id)`, `list({ status, note, limit, before })`, `stop(id)`,
+  `live(id, { control })`, `share(id, { control, minutes, recording })`,
+  `handoff(id, { reason, timeoutSec })`, `handoffDone(id)`, `waitHandoff(id, { timeout, poll })`,
+  `events(id, { after, limit })`, `recordingUrl(id)`, `downloadRecording(id, path)`.
+  `waitHandoff` on a session with no hand-off rejects with `CloudError` (code `NO_HANDOFF`).
+- `runs`: `create(task, { url, schema, secrets, wait = true, timeout, poll = 1.5, onUpdate, ...options })`
+  (the browser options above plus `maxSteps`, `handoff`, `handoffTimeoutSec`), `get(id)`,
+  `list({ limit, before })`, `cancel(id)`, `wait(id, { timeout, poll, onUpdate })`. A run that pauses
+  for a person (`waiting_for_human`) is not finished: `onUpdate` hears about it, and without one the
+  live link is printed to stderr. `timeout` and `poll` are in seconds, as in the Python SDK.
+- `profiles`: `list()`, `get(name)`, `delete(name)`, `importCookies(name, cookies, { mode })`,
+  `sync(name, { fromProfile | fromCdp | fromFile | loginUrl, domains | allDomains, replace })`. `sync`
+  refuses to run without `domains` or `allDomains: true`.
+- `webhooks`: `create(url, { events, description })` (the answer carries the `secret`, shown once),
+  `list()`, `delete(id)`, `test(id)`
+
+Every method resolves to the parsed JSON of its endpoint. An API refusal rejects with `CloudError`
+(`status`, `code` such as `"PROFILE_IN_USE"`, and the server's own `message`); a wait that runs out
+rejects with `CloudTimeoutError`, whose `last` holds the last view (the run carries on on the server).
+
+Check a webhook delivery with the raw request body and the `Clearcote-Signature` header:
+
+```ts
+import { verifyWebhook } from "clearcote";
+
+const event = verifyWebhook(rawBody, req.headers["clearcote-signature"], "whsec_..."); // throws if forged or stale
+```
+
+The same from the command line (`--json` for machine-readable output):
+
+```bash
+npx clearcote cloud run "Read the price of the Pro plan" --url https://example.com/pricing --schema price.json
+npx clearcote cloud run "Open my account page" --country us --profile acct-1 --persist-profile --max-steps 20
+npx clearcote cloud sessions
+npx clearcote cloud events bs_123
+npx clearcote cloud recording bs_123 -o session.mp4
+npx clearcote cloud profile sync acct-1 --login https://example.com/login --domain example.com
+npx clearcote cloud webhooks add https://hooks.example.com/clearcote --event run.finished
+```
+
 ## Fingerprint options
 
 All optional. Anything not listed here is passed straight through to Playwright
@@ -404,8 +509,9 @@ Profiles are JSON at `~/.clearcote/profiles/<name>.json` (set `CLEARCOTE_PROFILE
 
 ## API
 
-- `launch(options?)` → `Promise<Browser>` — launch and get a Playwright `Browser`. Pass `profile` (a name, path, or `Profile`) to launch a saved persona.
-- `launchPersistentContext(userDataDir, options?)` → `Promise<BrowserContext>`.
+- `launch(options?)` → `Promise<Browser>` — launch and get a Playwright `Browser`. Pass `profile` (a name, path, or `Profile`) to launch a saved persona; `cloud: true` for a hosted browser ([Local or cloud](#local-or-cloud)).
+- `launchPersistentContext(userDataDir, options?)` → `Promise<BrowserContext>`; `launchPersistentContext({ cloud: true, profile: "name" })` for a cloud profile.
+- `new Cloud({ apiKey, baseUrl })` — the hosted API (`browsers`, `runs`, `profiles`, `webhooks`); `CloudError`, `CloudTimeoutError`, `verifyWebhook(rawBody, signatureHeader, secret, toleranceSec = 300)`, `cloudSessionOf(browser)`.
 - `serve(options?)` → `Promise<Server>` — a standing, stealthy CDP endpoint (`.cdpUrl` / `.wsUrl()` / `.close()`) any Playwright/Puppeteer/CDP client attaches to via `connectOverCDP`.
 - `executablePath(options?)` → `Promise<string>` — resolve (download/verify if needed) the chrome.exe path, e.g. for raw `chromium.launch({ executablePath })`.
 - `download(options?)` → `Promise<string>` — pre-fetch + verify the binary without launching.

package/dist/cli-commands.d.ts

@@ -1,5 +1,8 @@
 import { type SessionSeats } from "./index.js";
+import { type Json } from "./cloud.js";
 export declare const USAGE: string;
+/** `clearcote cloud --help`. Kept byte-identical to CLOUD_USAGE in the Python SDK's _commands.py. */
+export declare const CLOUD_USAGE = "clearcote cloud -- the hosted Clearcote API from the command line.\n\nUSAGE\n  clearcote cloud run <task> [--url <url>] [--schema <file.json>] [--secret <name>=<value>]...\n                      [--secret-domain <name>=<host>]... [--handoff] [--record] [--json]\n                      [--country <cc>] [--state <s>] [--city <c>] [--proxy managed|<url>]\n                      [--profile <name> [--persist-profile]] [--fingerprint <seed>]\n                      [--timeout-sec <n>] [--max-steps <n>] [--note <text>]\n  clearcote cloud sessions [--json]\n  clearcote cloud stop <id> [--json]\n  clearcote cloud events <id> [--json]\n  clearcote cloud recording <id> [-o <file.mp4>] [--json]\n  clearcote cloud profile sync <name> (--from-profile <dir> | --from-cdp <url> | --from-file <state.json>\n                      | --login <url>) (--domain <domain>... | --all-domains) [--replace] [--json]\n  clearcote cloud webhooks add <url> [--event <type>]... [--json]\n  clearcote cloud webhooks list [--json]\n  clearcote cloud webhooks rm <id> [--json]\n  clearcote cloud webhooks test <id> [--json]\n\n  run waits for the result and exits 0 only when the run succeeded. profile sync uploads only the\n  cookies of the --domain names you list (subdomains included); --all-domains uploads every cookie.\n\nENVIRONMENT\n  CLEARCOTE_API_KEY (required), CLEARCOTE_API_URL (default https://www.clearcotelabs.com)";
 /** What `info` reports. Also the `--json` shape. */
 export interface InfoReport {
     sdk: {
@@ -53,6 +56,16 @@ export declare function buildInfo(flags: {
     proxy?: string;
 }): Promise<InfoReport>;
 export declare function main(argv?: string[]): Promise<void>;
+/** The human summary `clearcote cloud run` prints. */
+export declare function formatRun(run: Json): string[];
+/** --secret name=value and --secret-domain name=host as the API's `secrets` object: a plain string,
+ * or { value, domains } once a domain is given for that name. */
+export declare function cloudSecrets(secretArgs?: string[], domainArgs?: string[]): Record<string, unknown>;
+/** The browser and run options of `clearcote cloud run` (unset ones left out). --profile NAME loads a
+ * cloud profile; with --persist-profile the run also saves it back. */
+export declare function cloudRunOptions(v: Record<string, Json>): Record<string, unknown>;
+/** `clearcote cloud …`: resolves to the exit code (0 ok, 1 failed, 2 usage). Never exits itself. */
+export declare function cloudMain(argv: string[]): Promise<number>;
 /** `--proxy scheme://user:pass@host:port` as a launch proxy option with the credentials split out. */
 export declare function proxyOption(url: string): {
     server: string;

package/dist/cli-commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-commands.d.ts","sourceRoot":"","sources":["../src/cli-commands.ts"],"names":[],"mappings":"AAiBA,OAAO,EAcL,KAAK,YAAY,EAClB,MAAM,YAAY,CAAC;AAcpB,eAAO,MAAM,KAAK,QAqBiF,CAAC;AAWpG,oDAAoD;AACpD,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IACzD,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,YAAY,CAAA;KAAE,CAAC;IAChE,MAAM,EAAE;QACN,MAAM,EAAE,kBAAkB,GAAG,OAAO,GAAG,MAAM,CAAC;QAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,KAAK,CAAC;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAC7C,UAAU,EAAE,MAAM,CAAC;QACnB,cAAc,EAAE,MAAM,CAAC;KACxB,CAAC;IACF,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,MAAM,CAAC,EAAE;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,EAAE,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACtH,KAAK,CAAC,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C,KAAK,EAAE;QAAE,cAAc,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE;YAAE,MAAM,CAAC,EAAE,MAAM,CAAC;YAAC,OAAO,CAAC,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;YAAC,cAAc,CAAC,EAAE,MAAM,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;CAC7J;AAYD,wBAAsB,SAAS,CAAC,KAAK,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAkE/F;AAyDD,wBAAsB,IAAI,CAAC,IAAI,WAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CA0HtE;AAED,sGAAsG;AACtG,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAKjG"}
+{"version":3,"file":"cli-commands.d.ts","sourceRoot":"","sources":["../src/cli-commands.ts"],"names":[],"mappings":"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"}

package/dist/cli-commands.js

@@ -7,6 +7,7 @@
 //   clearcote login   [key]                                 save a licence key (validated first)
 //   clearcote logout                                        remove the saved key
 //   clearcote serve   [--port 9222] [--idle-timeout 300] …  multi-identity CDP endpoint
+//   clearcote cloud   run|sessions|stop|events|recording|profile sync|webhooks …  the hosted API
 //
 // `info` never downloads: it reports what is already cached and what a launch would resolve to.
 import { parseArgs } from "node:util";
@@ -19,6 +20,7 @@ import { defaultCacheRoot, listCachedBuilds } from "./download.js";
 import { geoCacheRoot } from "./geoip.js";
 import { GATED_ENGINE_SWITCHES } from "./launchopts.js";
 import { toProxySpec } from "./net.js";
+import { Cloud, CloudError, announceHandoff } from "./cloud.js";
 const SDK_VERSION = (() => {
     try {
         return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
@@ -40,6 +42,10 @@ USAGE
                   [--max-browsers 16] [--allow-origin <origin>]... [--allow-host <name>]... [--headed]
                   [--fingerprint <seed>] [--platform <os>] [--proxy <url>] [--timezone <tz>]
                   [--accept-language <l>] [--geoip]
+  clearcote cloud run <task> [--url <url>] [--schema <file.json>] [--secret <name>=<value>]... [--json]
+  clearcote cloud sessions | stop <id> | events <id> | recording <id> [-o <file.mp4>]
+  clearcote cloud profile sync <name> (--from-profile <dir> | --from-cdp <url> | --from-file <file> | --login <url>)
+  clearcote cloud webhooks add <url> | list | rm <id> | test <id>      (all flags: clearcote cloud --help)
 
 INFO FLAGS
   --quick          skip everything that needs the network or a launch (seat count, launch test)
@@ -48,7 +54,33 @@ INFO FLAGS
 
 ENVIRONMENT
   CLEARCOTE_LICENSE_KEY, CLEARCOTE_RELEASE_CHANNEL, CLEARCOTE_GEOIP_TIMEOUT_SECONDS,
-  CLEARCOTE_LICENSE_THROUGH_PROXY, CLEARCOTE_BINARY, CLEARCOTE_CACHE, CLEARCOTE_SERVE_IDLE_TIMEOUT`;
+  CLEARCOTE_LICENSE_THROUGH_PROXY, CLEARCOTE_BINARY, CLEARCOTE_CACHE, CLEARCOTE_SERVE_IDLE_TIMEOUT,
+  CLEARCOTE_API_KEY, CLEARCOTE_API_URL, CLEARCOTE_CLOUD`;
+/** `clearcote cloud --help`. Kept byte-identical to CLOUD_USAGE in the Python SDK's _commands.py. */
+export const CLOUD_USAGE = `clearcote cloud -- the hosted Clearcote API from the command line.
+
+USAGE
+  clearcote cloud run <task> [--url <url>] [--schema <file.json>] [--secret <name>=<value>]...
+                      [--secret-domain <name>=<host>]... [--handoff] [--record] [--json]
+                      [--country <cc>] [--state <s>] [--city <c>] [--proxy managed|<url>]
+                      [--profile <name> [--persist-profile]] [--fingerprint <seed>]
+                      [--timeout-sec <n>] [--max-steps <n>] [--note <text>]
+  clearcote cloud sessions [--json]
+  clearcote cloud stop <id> [--json]
+  clearcote cloud events <id> [--json]
+  clearcote cloud recording <id> [-o <file.mp4>] [--json]
+  clearcote cloud profile sync <name> (--from-profile <dir> | --from-cdp <url> | --from-file <state.json>
+                      | --login <url>) (--domain <domain>... | --all-domains) [--replace] [--json]
+  clearcote cloud webhooks add <url> [--event <type>]... [--json]
+  clearcote cloud webhooks list [--json]
+  clearcote cloud webhooks rm <id> [--json]
+  clearcote cloud webhooks test <id> [--json]
+
+  run waits for the result and exits 0 only when the run succeeded. profile sync uploads only the
+  cookies of the --domain names you list (subdomains included); --all-domains uploads every cookie.
+
+ENVIRONMENT
+  CLEARCOTE_API_KEY (required), CLEARCOTE_API_URL (default https://www.clearcotelabs.com)`;
 function out(line = "") {
     process.stdout.write(line + "\n");
 }
@@ -111,7 +143,8 @@ export async function buildInfo(flags) {
     }
     else {
         try {
-            const b = await launch({ executablePath: pick.path, headless: true, quiet: true, ephemeralProfile: false });
+            // cloud: false — this tests the LOCAL install, whatever CLEARCOTE_CLOUD says.
+            const b = await launch({ executablePath: pick.path, headless: true, quiet: true, ephemeralProfile: false, cloud: false });
             const version = b.version();
             await b.close();
             report.launch = { tested: true, ok: true, version };
@@ -197,6 +230,12 @@ export async function main(argv = process.argv.slice(2)) {
         out(SDK_VERSION);
         return;
     }
+    if (cmd === "cloud") {
+        const code = await cloudMain(rest);
+        if (code)
+            process.exitCode = code;
+        return;
+    }
     if (cmd === "info" || cmd === "doctor") {
         const { values } = parseArgs({ args: rest, options: { quick: { type: "boolean" }, "no-launch": { type: "boolean" }, json: { type: "boolean" }, proxy: { type: "string" } } });
         const report = await buildInfo({ quick: !!(values.quick || values["no-launch"]), proxy: values.proxy });
@@ -317,6 +356,308 @@ export async function main(argv = process.argv.slice(2)) {
     }
     fail(`unknown command '${cmd}'. Run \`clearcote --help\`.`, 2);
 }
+// ── clearcote cloud ────────────────────────────────────────────────────────────────────────────────
+// Output is part of the contract: the Python SDK's tests/test_parity_cloud_cli.py runs this CLI and
+// the Python one against the same fake API and compares stdout byte for byte. Change a line here,
+// change it in _commands.py too.
+/** A usage error inside `clearcote cloud`: message already on stderr, exit with `code`. */
+class CloudCliExit extends Error {
+    code;
+    constructor(code) {
+        super(`exit ${code}`);
+        this.code = code;
+    }
+}
+function cloudFail(msg, code = 1) {
+    process.stderr.write(`clearcote: ${msg}\n`);
+    throw new CloudCliExit(code);
+}
+const dump = (obj) => out(JSON.stringify(obj, null, 2));
+const str = (v) => (v === null || v === undefined ? "-" : String(v));
+const eur = (v, places) => (typeof v === "number" ? `€${v.toFixed(places)}` : "-");
+/** The human summary `clearcote cloud run` prints. */
+export function formatRun(run) {
+    const lines = [`run ${str(run?.id)} ${str(run?.status)}`];
+    const r = run?.result ?? {};
+    if (r.status)
+        lines.push(`result  ${r.status}${r.detail ? `: ${r.detail}` : ""}`);
+    if (r.url)
+        lines.push(`url     ${r.url}`);
+    if (r.title)
+        lines.push(`title   ${r.title}`);
+    if (r.outputError)
+        lines.push(`output  error: ${r.outputError}`);
+    else if (r.output !== undefined && r.output !== null)
+        lines.push(`output  ${JSON.stringify(r.output, null, 2)}`);
+    const cost = run?.costEur;
+    if (cost && typeof cost === "object" && cost.total !== undefined && cost.total !== null)
+        lines.push(`cost    ${eur(cost.total, 4)}`);
+    return lines;
+}
+function sessionLine(s) {
+    const line = `${str(s?.id)}  ${str(s?.status)}  ${str(s?.createdAt)}  ${eur(s?.costEur, 4)}`;
+    return line + (s?.note ? `  ${s.note}` : "");
+}
+// A --secret argument is never echoed back, not even a malformed one: it may be the bare secret.
+const SECRET_SHAPE = "--secret wants <name>=<value> (the argument given is not shown: it may hold the secret)";
+function parsePairs(values, flag) {
+    return (values ?? []).map((raw) => {
+        const i = raw.indexOf("=");
+        const name = i < 0 ? "" : raw.slice(0, i).trim();
+        const value = i < 0 ? "" : raw.slice(i + 1);
+        if (!name || !value)
+            cloudFail(flag === "--secret" ? SECRET_SHAPE : `${flag} wants <name>=<value>, got '${raw}'`, 2);
+        return [name, value];
+    });
+}
+/** --secret name=value and --secret-domain name=host as the API's `secrets` object: a plain string,
+ * or { value, domains } once a domain is given for that name. */
+export function cloudSecrets(secretArgs, domainArgs) {
+    const secrets = new Map(parsePairs(secretArgs, "--secret"));
+    const domains = new Map();
+    for (const [name, host] of parsePairs(domainArgs, "--secret-domain")) {
+        if (!secrets.has(name))
+            cloudFail(`--secret-domain ${name}: there is no --secret ${name}=...`, 2);
+        domains.set(name, [...(domains.get(name) ?? []), host.trim().toLowerCase()]);
+    }
+    return Object.fromEntries([...secrets].map(([n, v]) => [n, domains.has(n) ? { value: v, domains: domains.get(n) } : v]));
+}
+// `clearcote cloud run` browser/run options that take a value, mapped to the Runs.create option of the
+// same meaning (the Python launch kwargs): --timeout-sec -> timeoutSec, --max-steps -> maxSteps, ...
+const RUN_OPTION_FLAGS = ["country", "state", "city", "proxy", "profile", "fingerprint", "timeout-sec", "max-steps", "note"];
+function whole(value, flag) {
+    if (value === undefined)
+        return undefined;
+    if (!/^[0-9]+$/.test(value))
+        cloudFail(`${flag} wants a whole number, got '${value}'`, 2);
+    return Number(value);
+}
+/** The browser and run options of `clearcote cloud run` (unset ones left out). --profile NAME loads a
+ * cloud profile; with --persist-profile the run also saves it back. */
+export function cloudRunOptions(v) {
+    if (v["persist-profile"] && !v.profile)
+        cloudFail("--persist-profile needs --profile <name>", 2);
+    const opts = {
+        country: v.country, state: v.state, city: v.city, proxy: v.proxy,
+        profile: v.profile ? (v["persist-profile"] ? { name: v.profile, persist: true } : v.profile) : undefined,
+        fingerprint: v.fingerprint, timeoutSec: whole(v["timeout-sec"], "--timeout-sec"),
+        maxSteps: whole(v["max-steps"], "--max-steps"), note: v.note,
+        handoff: v.handoff ? true : undefined, record: v.record ? true : undefined,
+    };
+    return Object.fromEntries(Object.entries(opts).filter(([, x]) => x !== undefined));
+}
+function runProgress(view) {
+    if (view?.status === "waiting_for_human")
+        announceHandoff(view);
+    else
+        process.stderr.write(`[clearcote] run ${view?.id}: ${view?.status}\n`);
+}
+function parse(args, options, positionals, what) {
+    let r;
+    try {
+        r = parseArgs({ args, options: { ...options, json: { type: "boolean" } }, allowPositionals: true, strict: true });
+    }
+    catch (e) {
+        cloudFail(e.message, 2);
+    }
+    if (positionals >= 0 ? r.positionals.length !== positionals : r.positionals.length < 1) {
+        cloudFail(`\`clearcote cloud ${what}\`: wrong arguments. Run \`clearcote cloud --help\`.`, 2);
+    }
+    return { values: r.values, pos: r.positionals };
+}
+/** `clearcote cloud …`: resolves to the exit code (0 ok, 1 failed, 2 usage). Never exits itself. */
+export async function cloudMain(argv) {
+    try {
+        return await cloudCommand(argv);
+    }
+    catch (e) {
+        if (e instanceof CloudCliExit)
+            return e.code;
+        if (e instanceof CloudError) {
+            process.stderr.write(`clearcote: ${e.message}${e.status ? ` (HTTP ${e.status}${e.code ? `, ${e.code}` : ""})` : ""}\n`);
+            return 1;
+        }
+        process.stderr.write(`clearcote: ${e?.message ?? String(e)}\n`);
+        return 1;
+    }
+}
+async function cloudCommand(argv) {
+    const [cmd, ...rest] = argv;
+    if (!cmd || cmd === "-h" || cmd === "--help" || cmd === "help") {
+        out(CLOUD_USAGE);
+        return 0;
+    }
+    if (!["run", "sessions", "stop", "events", "recording", "profile", "webhooks"].includes(cmd)) {
+        cloudFail(`unknown cloud command '${cmd}'. Run \`clearcote cloud --help\`.`, 2);
+    }
+    if ((cmd === "profile" || cmd === "webhooks") && !rest[0]) {
+        cloudFail(`\`clearcote cloud ${cmd}\` needs a subcommand. Run \`clearcote cloud --help\`.`, 2);
+    }
+    if (cmd === "run") {
+        const { values: v, pos } = parse(rest, {
+            url: { type: "string" }, schema: { type: "string" }, secret: { type: "string", multiple: true },
+            "secret-domain": { type: "string", multiple: true }, handoff: { type: "boolean" }, record: { type: "boolean" },
+            ...Object.fromEntries(RUN_OPTION_FLAGS.map((f) => [f, { type: "string" }])),
+            "persist-profile": { type: "boolean" },
+        }, -1, "run");
+        const secrets = cloudSecrets(v.secret, v["secret-domain"]);
+        const runOptions = cloudRunOptions(v);
+        let schema;
+        if (v.schema) {
+            try {
+                schema = JSON.parse(readFileSync(v.schema, "utf8"));
+            }
+            catch (e) {
+                cloudFail(`--schema ${v.schema}: ${e.message}`, 2);
+            }
+        }
+        const cloud = new Cloud();
+        const run = await cloud.runs.create(pos.join(" "), {
+            url: v.url, schema, secrets: Object.keys(secrets).length ? secrets : undefined,
+            ...runOptions, onUpdate: runProgress,
+        });
+        if (v.json)
+            dump(run);
+        else
+            formatRun(run).forEach((l) => out(l));
+        return run?.status === "succeeded" ? 0 : 1;
+    }
+    if (cmd === "sessions") {
+        const { values: v } = parse(rest, {}, 0, "sessions");
+        const data = (await new Cloud().browsers.list()) ?? {};
+        if (v.json) {
+            dump(data);
+            return 0;
+        }
+        const sessions = data.sessions ?? [];
+        for (const s of sessions)
+            out(sessionLine(s));
+        if (!sessions.length)
+            out("no sessions");
+        if (data.balanceEur !== undefined && data.balanceEur !== null)
+            out(`balance ${eur(data.balanceEur, 2)}`);
+        return 0;
+    }
+    if (cmd === "stop") {
+        const { values: v, pos } = parse(rest, {}, 1, "stop");
+        const view = await new Cloud().browsers.stop(pos[0]);
+        if (v.json)
+            dump(view);
+        else
+            out(`stopped ${pos[0]} (${str(view?.status)})`);
+        return 0;
+    }
+    if (cmd === "events") {
+        const { values: v, pos } = parse(rest, {}, 1, "events");
+        const cloud = new Cloud();
+        const events = [];
+        let after = 0;
+        for (;;) {
+            const page = (await cloud.browsers.events(pos[0], { after })) ?? {};
+            const batch = page.events ?? [];
+            events.push(...batch);
+            const next = page.next;
+            if (!batch.length || next === null || next === undefined || next === after)
+                break;
+            after = next;
+        }
+        if (v.json) {
+            dump({ events });
+            return 0;
+        }
+        for (const e of events) {
+            const data = e?.data;
+            const extra = data && Object.keys(data).length ? `  ${JSON.stringify(data)}` : "";
+            out(`${str(e?.seq)}  ${str(e?.at)}  ${str(e?.type)}${extra}`);
+        }
+        if (!events.length)
+            out("no events");
+        return 0;
+    }
+    if (cmd === "recording") {
+        const { values: v, pos } = parse(rest, { output: { type: "string", short: "o" } }, 1, "recording");
+        const path = v.output || `${pos[0]}.mp4`;
+        await new Cloud().browsers.downloadRecording(pos[0], path);
+        const size = statSync(path).size;
+        if (v.json)
+            dump({ path, bytes: size });
+        else
+            out(`saved ${path} (${size} bytes)`);
+        return 0;
+    }
+    if (cmd === "profile") {
+        if (rest[0] !== "sync")
+            cloudFail(`unknown profile command '${rest[0]}'. Run \`clearcote cloud --help\`.`, 2);
+        const { values: v, pos } = parse(rest.slice(1), {
+            "from-profile": { type: "string" }, "from-cdp": { type: "string" }, "from-file": { type: "string" },
+            login: { type: "string" }, domain: { type: "string", multiple: true }, "all-domains": { type: "boolean" },
+            replace: { type: "boolean" },
+        }, 1, "profile sync");
+        const sources = [v["from-profile"], v["from-cdp"], v["from-file"], v.login].filter(Boolean);
+        if (sources.length !== 1)
+            cloudFail("profile sync needs exactly one of --from-profile, --from-cdp, --from-file or --login", 2);
+        if (v.domain?.length && v["all-domains"])
+            cloudFail("pass --domain or --all-domains, not both", 2);
+        if (!v.domain?.length && !v["all-domains"]) {
+            cloudFail("refusing to upload every cookie: pass --domain <domain> (repeatable, subdomains included) or --all-domains", 2);
+        }
+        const res = (await new Cloud().profiles.sync(pos[0], {
+            fromProfile: v["from-profile"], fromCdp: v["from-cdp"], fromFile: v["from-file"], loginUrl: v.login,
+            domains: v.domain, allDomains: !!v["all-domains"], replace: !!v.replace,
+        })) ?? {};
+        if (v.json) {
+            dump(res);
+            return 0;
+        }
+        out(`imported ${str(res.imported)} cookies into profile ${res.name || pos[0]} (${str(res.cookies)} in total)`);
+        if (res.domains?.length)
+            out(`domains  ${res.domains.join(", ")}`);
+        return 0;
+    }
+    // webhooks
+    const action = rest[0];
+    if (action === "add") {
+        const { values: v, pos } = parse(rest.slice(1), { event: { type: "string", multiple: true } }, 1, "webhooks add");
+        const res = (await new Cloud().webhooks.create(pos[0], { events: v.event })) ?? {};
+        if (v.json) {
+            dump(res);
+            return 0;
+        }
+        out(`webhook ${str(res.id)} -> ${str(res.url)}`);
+        out(`events  ${(res.events ?? []).join(", ") || "all except ping"}`);
+        out(`secret  ${str(res.secret)}`);
+        out("store the secret now: it is not shown again");
+        return 0;
+    }
+    if (action === "list") {
+        const { values: v } = parse(rest.slice(1), {}, 0, "webhooks list");
+        const data = (await new Cloud().webhooks.list()) ?? {};
+        if (v.json) {
+            dump(data);
+            return 0;
+        }
+        const hooks = data.webhooks ?? [];
+        for (const h of hooks) {
+            const ld = h?.lastDelivery;
+            const last = ld ? `  last ${str(ld.status)} ${str(ld.at)}` : "";
+            out(`${str(h?.id)}  ${str(h?.url)}  ${(h?.events ?? []).join(",") || "all"}${last}`);
+        }
+        if (!hooks.length)
+            out("no webhooks");
+        return 0;
+    }
+    if (action === "rm" || action === "test") {
+        const { values: v, pos } = parse(rest.slice(1), {}, 1, `webhooks ${action}`);
+        const cloud = new Cloud();
+        const res = action === "rm" ? await cloud.webhooks.delete(pos[0]) : await cloud.webhooks.test(pos[0]);
+        if (v.json)
+            dump(res);
+        else
+            out(action === "rm" ? `removed ${pos[0]}` : `sent a ping to ${pos[0]}`);
+        return 0;
+    }
+    return cloudFail(`unknown webhooks command '${action}'. Run \`clearcote cloud --help\`.`, 2);
+}
 /** `--proxy scheme://user:pass@host:port` as a launch proxy option with the credentials split out. */
 export function proxyOption(url) {
     let spec;