@ceki/sdk 1.12.0 → 1.13.0

package/README.md

@@ -111,24 +111,41 @@ await browser.profile.import(saved);
 
 ## Human Mode
 
-Browser actions include human-like timing by default — delays before/after actions and per-character typing with jitter.
+Behavioral humanization is **ON by default** in both `main` and `incognito` profile modes:
+
+- **Typing** — per-character keystrokes with natural inter-key cadence + jitter (extension-side, `Ceki.typeText`).
+- **Mouse** — clicks are preceded by a bezier mousemove trajectory (8–35 intermediate `mouseMoved` events), so the page sees a real pointer trail instead of a teleport.
+
+Fingerprint Tier-2 (UA / timezone / WebGL overrides) stays OFF in `main` mode to preserve the provider's identity — separate from behavioral humanization.
 
 ```typescript
-// Default: natural profile (enabled by default)
+// Default: behavioral humanizer ON (natural profile)
 const browser = await client.rent(scheduleId);
 
 // Explicit profile
 const browser = await client.rent(scheduleId, { human: 'careful' });
 
-// Disable humanization
+// Disable session-wide humanization
 const browser = await client.rent(scheduleId, { human: null });
 ```
 
+### Per-call disable
+
+Pass `{ human: false }` to flatten **just one call**, without leaking jitter to siblings:
+
+```typescript
+await browser.type('user@example.com', { human: false });   // flat keystrokes
+await browser.click(120, 240, { human: false });            // straight pointer jump
+await browser.scroll({ deltaY: -300, human: false });
+```
+
+The CLI equivalent is `--no-human` / `--raw` on `type`, `click`, `scroll`, `navigate`. Both flags mean "this call only".
+
 ### Environment overrides
 
 - `CEKI_HUMAN_PROFILE` — Override default profile name (`careful`)
 - `CEKI_HUMAN_PROFILE_PATH` — Path to custom JSON profile file
-- `CEKI_HUMAN_DISABLE=1` — Disable humanization entirely
+- `CEKI_HUMAN_DISABLE=1` — **Global kill-switch**: disable humanization for every call regardless of per-call `human:` arguments or CLI flags
 
 ## Error Classes
 
@@ -194,10 +211,10 @@ The CLI persists session state locally — after `rent` it saves the session ID
 
 | Command | Description |
 |---|---|
-| `navigate SID URL` | Open URL |
-| `click SID X Y` | Click at viewport coordinates |
-| `type SID TEXT [--natural]` | Type text into focused element |
-| `scroll SID X Y DY` | Scroll from (X, Y) by `DY` pixels |
+| `navigate SID URL [--no-human\|--raw]` | Open URL (humanized by default; `--no-human` skips pre/post delays) |
+| `click SID X Y [--no-human\|--raw]` | Click at viewport coordinates (mousemove trail ON by default; `--no-human` for direct jump) |
+| `type SID TEXT [--selector CSS] [--no-human\|--raw]` | Type text (humanized by default; `--no-human` for flat keystrokes) |
+| `scroll SID X Y DY [--no-human\|--raw]` | Scroll from (X, Y) by `DY` pixels (eased by default; `--no-human` for raw CDP wheel) |
 | `screenshot SID -o FILE [--format png\|jpeg] [--full]` | Save screenshot |
 | `snapshot SID -o FILE` | Screenshot + new chat messages |
 | `switch-tab SID` | Switch active tab |

package/dist/cli.js

@@ -654,27 +654,39 @@ var Browser = class _Browser {
       this._sendRaw(msg);
     });
   }
-  async navigate(url, timeout = 3e4) {
-    if (this._humanizer) await this._humanizer.before("navigate");
+  // task 427 — per-call kill-switch. human=false bypasses humanizer timings
+  // AND tells the extension to skip mouse-jitter via the `_ceki_raw` marker
+  // (see cdp.ts). human=true forces humanizer; human undefined = session
+  // default. Global env CEKI_HUMAN_DISABLE=1 nulls this._humanizer in the
+  // constructor so all paths become raw.
+  _humanizeForCall(human) {
+    if (human === false) return null;
+    return this._humanizer;
+  }
+  async navigate(url, timeout = 3e4, opts) {
+    const h = this._humanizeForCall(opts?.human);
+    if (h) await h.before("navigate");
     const result = await this.send({ method: "Page.navigate", params: { url } }, timeout);
-    if (this._humanizer) await this._humanizer.after("navigate");
+    if (h) await h.after("navigate");
     return {
       url: String(result?.url ?? url),
       frameId: result?.frameId ? String(result.frameId) : void 0
     };
   }
-  async click(x, y) {
-    if (this._humanizer) await this._humanizer.before("click");
+  async click(x, y, opts) {
+    const h = this._humanizeForCall(opts?.human);
+    if (h) await h.before("click");
+    const rawFlag = h === null ? { _ceki_raw: true } : {};
     await this.send({
       method: "Input.dispatchMouseEvent",
-      params: { type: "mousePressed", x, y, button: "left", clickCount: 1 }
+      params: { type: "mousePressed", x, y, button: "left", clickCount: 1, ...rawFlag }
     });
     await this.send({
       method: "Input.dispatchMouseEvent",
       params: { type: "mouseReleased", x, y, button: "left", clickCount: 1 }
     });
     this._lastPointer = [x, y];
-    if (this._humanizer) await this._humanizer.after("click");
+    if (h) await h.after("click");
   }
   async _sendKeystroke(char) {
     const mapping = keymapForChar(char);
@@ -720,9 +732,10 @@ var Browser = class _Browser {
       });
     }
   }
-  async type(text) {
-    if (this._humanizer) {
-      await this._humanizer.before("type");
+  async type(text, opts) {
+    const h = this._humanizeForCall(opts?.human);
+    if (h) {
+      await h.before("type");
       if (this._lastPointer) {
         const [px, py] = this._lastPointer;
         await this.send({
@@ -735,10 +748,10 @@ var Browser = class _Browser {
         });
       }
     }
-    const human = this._humanizer ? ["natural", "careful"].includes(this._humanizer.profile.name) ? this._humanizer.profile.name : "natural" : null;
+    const human = h ? ["natural", "careful"].includes(h.profile.name) ? h.profile.name : "natural" : null;
     await this.send({ method: "Ceki.typeText", params: { text, human } });
-    if (this._humanizer) {
-      await this._humanizer.after("type");
+    if (h) {
+      await h.after("type");
     }
   }
   async scroll(opts) {
@@ -746,13 +759,14 @@ var Browser = class _Browser {
     const y = opts?.y ?? 0;
     const deltaX = opts?.deltaX ?? 0;
     const deltaY = opts?.deltaY ?? -300;
-    if (this._humanizer) await this._humanizer.before("scroll");
+    const h = this._humanizeForCall(opts?.human);
+    if (h) await h.before("scroll");
     await this.send({
       method: "Input.dispatchMouseEvent",
       params: { type: "mouseWheel", x, y, deltaX, deltaY }
     });
     this._lastPointer = [x, y];
-    if (this._humanizer) await this._humanizer.after("scroll");
+    if (h) await h.after("scroll");
   }
   async screenshot(opts) {
     const format = opts?.format ?? "base64";
@@ -2149,32 +2163,38 @@ async function cmdSnapshot(sid, args) {
     await closeClient(client);
   }
 }
+function parseNoHuman(args) {
+  return args.includes("--no-human") || args.includes("--raw");
+}
 async function cmdNavigate(sid, args) {
-  const url = args[0];
+  const url = args.find((a) => !a.startsWith("--"));
   if (!url) {
     err("URL is required", "args");
     process.exit(1);
   }
+  const raw = parseNoHuman(args);
   const apiKey = getApiKey();
   const [client, browser] = await resumeBrowser(apiKey, sid);
   try {
-    await browser.navigate(url);
+    await browser.navigate(url, 3e4, raw ? { human: false } : void 0);
     out({ ok: true });
   } finally {
     await closeClient(client);
   }
 }
 async function cmdClick(sid, args) {
-  const x = parseInt(args[0], 10);
-  const y = parseInt(args[1], 10);
+  const positional = args.filter((a) => !a.startsWith("--"));
+  const x = parseInt(positional[0], 10);
+  const y = parseInt(positional[1], 10);
   if (isNaN(x) || isNaN(y)) {
     err("x and y coordinates are required", "args");
     process.exit(1);
   }
+  const raw = parseNoHuman(args);
   const apiKey = getApiKey();
   const [client, browser] = await resumeBrowser(apiKey, sid);
   try {
-    await browser.click(x, y);
+    await browser.click(x, y, raw ? { human: false } : void 0);
     out({ ok: true, pointer: [x, y] });
   } finally {
     await closeClient(client);
@@ -2182,41 +2202,42 @@ async function cmdClick(sid, args) {
 }
 async function cmdType(sid, args) {
   let text = "";
-  let natural = false;
+  let raw = false;
   for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--natural") natural = true;
-    else if (!text) text = args[i];
+    if (args[i] === "--no-human" || args[i] === "--raw") raw = true;
+    else if (args[i] === "--natural") {
+    } else if (!text) text = args[i];
   }
   if (!text) {
     err("text is required", "args");
     process.exit(1);
   }
   const apiKey = getApiKey();
-  const human = natural ? "natural" : null;
   const client = await connect(apiKey, connectOptions());
   try {
-    const browser = await client.resume(sid, { human });
-    if (!natural) {
-      browser._humanizer = null;
-    }
-    await browser.type(text);
+    const browser = await client.resume(sid);
+    await browser.type(text, raw ? { human: false } : void 0);
     out({ ok: true });
   } finally {
     await closeClient(client);
   }
 }
 async function cmdScroll(sid, args) {
-  const x = parseInt(args[0], 10);
-  const y = parseInt(args[1], 10);
-  const dy = parseInt(args[2], 10);
+  const positional = args.filter((a) => !a.startsWith("--"));
+  const x = parseInt(positional[0], 10);
+  const y = parseInt(positional[1], 10);
+  const dy = parseInt(positional[2], 10);
   if (isNaN(x) || isNaN(y) || isNaN(dy)) {
     err("x, y, dy are required", "args");
     process.exit(1);
   }
+  const raw = parseNoHuman(args);
   const apiKey = getApiKey();
   const [client, browser] = await resumeBrowser(apiKey, sid);
   try {
-    await browser.scroll({ x, y, deltaY: dy });
+    const scrollOpts = { x, y, deltaY: dy };
+    if (raw) scrollOpts.human = false;
+    await browser.scroll(scrollOpts);
     out({ ok: true });
   } finally {
     await closeClient(client);
@@ -2529,10 +2550,10 @@ Commands:
   search [--limit N] [--filter k=v]...
   snapshot <sid> -o PATH
   screenshot <sid> -o PATH [--full]
-  navigate <sid> <url>
-  click <sid> <x> <y>
-  type <sid> "<text>" [--natural]
-  scroll <sid> <x> <y> <dy>
+  navigate <sid> <url> [--no-human|--raw]
+  click <sid> <x> <y> [--no-human|--raw]
+  type <sid> "<text>" [--no-human|--raw]   (humanized by default)
+  scroll <sid> <x> <y> <dy> [--no-human|--raw]
   switch-tab <sid>
   configure <sid> [--masking-mode true|false] [--fingerprint true|false]
   cdp <sid> --method <M> [--params JSON]