@optima-chat/browser-cli 0.6.1 → 0.7.0

package/dist/index.js

@@ -98,6 +98,16 @@ var BrowserAPIError = class extends Error {
     this.name = "BrowserAPIError";
   }
 };
+function toAPIError(status, statusText, body) {
+  const detail = body.detail ?? body;
+  if (typeof detail === "string") {
+    return new BrowserAPIError(status, "http_error", `HTTP ${status}: ${detail}`);
+  }
+  if (detail?.message) {
+    return new BrowserAPIError(status, detail.error ?? "unknown", detail.message);
+  }
+  return new BrowserAPIError(status, "unknown", `HTTP ${status}: ${statusText}`);
+}
 async function request(path, options = {}) {
   const url = `${BROWSER_API_URL}${path}`;
   let response;
@@ -126,8 +136,7 @@ async function request(path, options = {}) {
         `HTTP ${response.status}: ${response.statusText}`
       );
     }
-    const detail = body.detail || body;
-    throw new BrowserAPIError(response.status, detail.error, detail.message);
+    throw toAPIError(response.status, response.statusText, body);
   }
   if (response.status === 204) {
     return void 0;
@@ -159,20 +168,20 @@ async function requestBinary(path) {
         `HTTP ${response.status}: ${response.statusText}`
       );
     }
-    const detail = body.detail || body;
-    throw new BrowserAPIError(response.status, detail.error, detail.message);
+    throw toAPIError(response.status, response.statusText, body);
   }
   const arrayBuffer = await response.arrayBuffer();
   return Buffer.from(arrayBuffer);
 }
 var BrowserAPI = class {
-  async createSession(url, profileId, force, connector, ziniaoProfileId) {
+  async createSession(url, profileId, force, connector, ziniaoProfileId, bitbrowserProfileId) {
     const body = {};
     if (url) body.url = url;
     if (profileId) body.profile_id = profileId;
     if (force) body.force = true;
     if (connector) body.connector = connector;
     if (ziniaoProfileId) body.ziniao_profile_id = ziniaoProfileId;
+    if (bitbrowserProfileId) body.bitbrowser_profile_id = bitbrowserProfileId;
     return request("/api/sessions", {
       method: "POST",
       body: JSON.stringify(body)
@@ -201,6 +210,9 @@ var BrowserAPI = class {
   async getZiNiaoProfiles() {
     return request("/api/user/ziniao-profiles");
   }
+  async getBitBrowserProfiles() {
+    return request("/api/user/bitbrowser-profiles");
+  }
   async closeSession(sessionId) {
     await request(`/api/sessions/${sessionId}`, { method: "DELETE" });
   }
@@ -246,6 +258,22 @@ var BrowserAPI = class {
   async getScreenshot(sessionId) {
     return requestBinary(`/api/sessions/${sessionId}/screenshot`);
   }
+  async runRecipeScript(name, params, pollMs = 2e3) {
+    const started = await request(`/api/scripts/${name}/run`, {
+      method: "POST",
+      body: JSON.stringify({ params })
+    });
+    for (; ; ) {
+      const task = await request(
+        `/api/script-tasks/${started.id}`
+      );
+      if (task.status === "completed") return task.output;
+      if (task.status === "failed" || task.status === "needs_fallback") {
+        throw new Error(task.error || `recipe ${task.status}`);
+      }
+      await new Promise((r) => setTimeout(r, pollMs));
+    }
+  }
   async search(sessionId, pattern) {
     return request(`/api/sessions/${sessionId}/search`, {
       method: "POST",
@@ -300,9 +328,11 @@ var BrowserAPI = class {
   async deleteScript(name) {
     await request(`/api/scripts/${encodeURIComponent(name)}`, { method: "DELETE" });
   }
-  async runScript(scriptName, params = {}, profileId) {
+  async runScript(scriptName, params = {}, profileId, connector, bitbrowserProfileId) {
     const payload = { params };
     if (profileId) payload.profile_id = profileId;
+    if (connector) payload.connector = connector;
+    if (bitbrowserProfileId) payload.bitbrowser_profile_id = bitbrowserProfileId;
     return request(`/api/scripts/${encodeURIComponent(scriptName)}/run`, {
       method: "POST",
       body: JSON.stringify(payload)
@@ -404,6 +434,9 @@ function formatFind(result) {
   }
   return lines.join("\n");
 }
+function formatDesktopNotConnected(result) {
+  return result.message ?? "\u684C\u9762\u5E94\u7528\u672A\u8FDE\u63A5\uFF0C\u8BF7\u5148\u5B89\u88C5\u5E76\u542F\u52A8\u684C\u9762\u5E94\u7528\u540E\u91CD\u8BD5\u3002";
+}
 function formatError(err) {
   if (err instanceof Error) {
     return `\u2717 Error: ${err.message}`;
@@ -430,9 +463,9 @@ function formatProfileDelete(profileId) {
 
 // src/commands/lifecycle.ts
 function registerLifecycleCommands(program2) {
-  program2.command("launch").description("Launch a browser session").option("--url <url>", "Navigate to URL after launch").option("--profile <id>", "Use a named browser profile").option("--force", "Close existing session before launching").option("--connector <type>", "Browser connector: chrome or ziniao").option("--ziniao-profile <id>", "ZiNiao browser profile ID").action(async (opts) => {
+  program2.command("launch").description("Launch a browser session").option("--url <url>", "Navigate to URL after launch").option("--profile <id>", "Use a named browser profile").option("--force", "Close existing session before launching").option("--connector <type>", "Browser connector: chrome, ziniao, or bitbrowser").option("--ziniao-profile <id>", "ZiNiao browser profile ID").option("--bitbrowser-profile <id>", "BitBrowser profile ID").action(async (opts) => {
     try {
-      const state = await api.createSession(opts.url, opts.profile, opts.force, opts.connector, opts.ziniaoProfile);
+      const state = await api.createSession(opts.url, opts.profile, opts.force, opts.connector, opts.ziniaoProfile, opts.bitbrowserProfile);
       saveSessionId(state.session_id);
       console.log(formatLaunch(state));
     } catch (err) {
@@ -748,7 +781,7 @@ function registerScriptCommands(program2) {
       process.exit(1);
     }
   });
-  program2.command("runscript").argument("<name>", "Script name").description("Run a script (polls until complete)").option("--param <params...>", "Parameters as key=value").option("--profile <id>", "Use a named browser profile").option("--no-poll", "Return immediately without polling").action(async (name, opts) => {
+  program2.command("runscript").argument("<name>", "Script name").description("Run a script (polls until complete)").option("--param <params...>", "Parameters as key=value").option("--profile <id>", "Use a named browser profile").option("--connector <type>", "Browser connector: chrome, ziniao, or bitbrowser").option("--bitbrowser-profile <id>", "BitBrowser profile ID (with --connector bitbrowser)").option("--no-poll", "Return immediately without polling").action(async (name, opts) => {
     try {
       const params = {};
       if (opts.param) {
@@ -758,7 +791,7 @@ function registerScriptCommands(program2) {
         }
       }
       clearSessionId();
-      const task = await api.runScript(name, params, opts.profile);
+      const task = await api.runScript(name, params, opts.profile, opts.connector, opts.bitbrowserProfile);
       console.log(`Script started (task: ${task.id})`);
       if (!opts.poll) {
         console.log(`Poll with: browser-cli script-task ${task.id}`);
@@ -820,6 +853,105 @@ function registerProfileCommands(program2) {
   });
 }
 
+// src/ziniao-doctor.ts
+var ZINIAO_WEBDRIVER_DOC_URL = "https://open.ziniao.com/docSupport?docId=99#%E7%AC%AC%E4%B8%80%E6%AD%A5%EF%BC%9A%E7%99%BB%E5%BD%95%E5%BC%80%E6%94%BE%E5%B9%B3%E5%8F%B0%E6%8E%A7%E5%88%B6%E5%8F%B00";
+var BOSS_GUIDANCE = [
+  "\u9700\u8981\u7D2B\u9E1F BOSS \u8D26\u53F7\u5B8C\u6210\u5F00\u901A\uFF08\u4E00\u6B21\u6027\u914D\u7F6E\uFF09\uFF1A",
+  "  1. \u767B\u5F55\u7D2B\u9E1F\u5F00\u653E\u5E73\u53F0\u63A7\u5236\u53F0\uFF0C\u5F00\u901A Webdriver \u6743\u9650\uFF1B",
+  "  2. \u521B\u5EFA\u4E13\u7528\u81EA\u52A8\u5316\u6210\u5458\u8D26\u53F7\uFF08robot\uFF09\uFF0C\u89D2\u8272\u9700\u542B\u300C\u67E5\u770B\u8D26\u53F7\u300D\u6743\u9650\uFF1B",
+  "  3. \u4E3A\u8BE5\u8D26\u53F7\u6388\u6743\u9700\u8981\u64CD\u4F5C\u7684\u5E97\u94FA\u3002",
+  `\u53C2\u8003\u6587\u6863: ${ZINIAO_WEBDRIVER_DOC_URL}`
+].join("\n");
+function ziniaoErrorHint(message) {
+  if (/webdriver|开通|权限|permission/i.test(message)) {
+    return `\u7591\u4F3C\u672A\u5F00\u901A Webdriver \u6743\u9650\u6216\u8D26\u53F7\u6743\u9650\u4E0D\u8DB3\u3002${BOSS_GUIDANCE}`;
+  }
+  if (/错误次数太多/.test(message)) {
+    return "\u7D2B\u9E1F\u98CE\u63A7\u5DF2\u4E34\u65F6\u9501\u5B9A\uFF0C\u8BF7\u7B49\u5F85\u7EA6 10 \u5206\u949F\u540E\u91CD\u8BD5\uFF08\u7EE7\u7EED\u5931\u8D25\u4F1A\u5EF6\u957F\u9501\u5B9A\uFF09\u3002";
+  }
+  if (/用户名或密码错误|密码错误/.test(message)) {
+    return "\u8BF7\u6838\u5BF9\u51ED\u636E\uFF08company=\u4F01\u4E1A\u540D\u79F0\uFF0Cusername/password=\u6210\u5458\u8D26\u53F7\uFF0C\u63A8\u8350 robot \u8D26\u53F7\uFF09\uFF0C\u7136\u540E\u7528 browser-cli ziniao set \u91CD\u65B0\u914D\u7F6E\u3002";
+  }
+  return null;
+}
+async function runZiNiaoDoctor(client) {
+  const checks = [];
+  const done = () => ({ checks, ok: checks.every((c) => c.ok === true) });
+  let cfg;
+  try {
+    cfg = await client.getZiNiaoConfig();
+  } catch (err) {
+    checks.push({
+      name: "\u540E\u7AEF\u8FDE\u63A5",
+      ok: false,
+      detail: err.message,
+      hint: "\u786E\u8BA4 browser-backend \u6B63\u5728\u8FD0\u884C\uFF0C\u4E14 BROWSER_API_URL \u6307\u5411\u6B63\u786E\u5730\u5740\u3002"
+    });
+    return done();
+  }
+  checks.push({ name: "\u540E\u7AEF\u8FDE\u63A5", ok: true });
+  if (!cfg.configured) {
+    checks.push({
+      name: "\u7D2B\u9E1F\u51ED\u636E",
+      ok: false,
+      hint: "browser-cli ziniao set --company <\u4F01\u4E1A\u540D\u79F0> --username <\u6210\u5458\u8D26\u53F7> --password <\u5BC6\u7801>\uFF08\u63A8\u8350\u4F7F\u7528\u4E13\u7528 robot \u6210\u5458\u8D26\u53F7\uFF09"
+    });
+    return done();
+  }
+  checks.push({ name: "\u7D2B\u9E1F\u51ED\u636E", ok: true, detail: `${cfg.company} / ${cfg.username}` });
+  try {
+    const r = await client.getZiNiaoProfiles();
+    if (!r.connected) {
+      checks.push({
+        name: "\u684C\u9762\u5E94\u7528",
+        ok: false,
+        detail: r.message,
+        hint: `\u8BF7\u542F\u52A8 Optima \u684C\u9762\u5E94\u7528\u5E76\u5B8C\u6210\u8FDE\u63A5\u3002${r.download_url ? `\u4E0B\u8F7D: ${r.download_url}` : ""}`.trim()
+      });
+      return done();
+    }
+    checks.push({ name: "\u684C\u9762\u5E94\u7528", ok: true });
+    if (!r.ziniao_available) {
+      checks.push({
+        name: "\u7D2B\u9E1F\u5BA2\u6237\u7AEF",
+        ok: false,
+        hint: "\u684C\u9762\u7AEF\u672A\u68C0\u6D4B\u5230\u53EF\u7528\u7684\u7D2B\u9E1F\uFF1A\u786E\u8BA4\u672C\u673A\u5DF2\u5B89\u88C5\u7D2B\u9E1F\u5BA2\u6237\u7AEF\uFF0C\u4E14\u51ED\u636E\u5DF2\u540C\u6B65\u5230\u684C\u9762\uFF08\u91CD\u542F\u684C\u9762\u5E94\u7528\u53EF\u89E6\u53D1\u540C\u6B65\uFF09\u3002"
+      });
+      return done();
+    }
+    checks.push({ name: "\u7D2B\u9E1F\u5BA2\u6237\u7AEF", ok: true });
+    if (r.profiles.length === 0) {
+      checks.push({
+        name: "\u5E97\u94FA\u5217\u8868",
+        ok: "warn",
+        detail: "\u767B\u5F55\u6210\u529F\uFF0C\u4F46\u5E97\u94FA\u5217\u8868\u4E3A\u7A7A",
+        hint: `robot \u8D26\u53F7\u7684\u89D2\u8272\u53EF\u80FD\u7F3A\u300C\u67E5\u770B\u8D26\u53F7\u300D\u6743\u9650\uFF0C\u6216\u5C1A\u672A\u6388\u6743\u4EFB\u4F55\u5E97\u94FA\u3002${BOSS_GUIDANCE}`
+      });
+      return done();
+    }
+    checks.push({ name: "\u5E97\u94FA\u5217\u8868", ok: true, detail: `${r.profiles.length} \u4E2A\u5E97\u94FA\u53EF\u7528` });
+  } catch (err) {
+    checks.push({
+      name: "\u7D2B\u9E1F Webdriver \u901A\u9053",
+      ok: false,
+      detail: err.message,
+      hint: ziniaoErrorHint(err.message ?? "") ?? void 0
+    });
+  }
+  return done();
+}
+function formatDoctorReport(checks) {
+  const lines = [];
+  for (const c of checks) {
+    const mark = c.ok === true ? "\u2713" : c.ok === "warn" ? "\u26A0" : "\u2717";
+    lines.push(`${mark} ${c.name}${c.detail ? `: ${c.detail}` : ""}`);
+    if (c.hint) {
+      lines.push(...c.hint.split("\n").map((l) => `    ${l}`));
+    }
+  }
+  return lines.join("\n");
+}
+
 // src/commands/ziniao.ts
 function registerZiNiaoCommands(program2) {
   const ziniao = program2.command("ziniao").description("Manage ZiNiao browser credentials");
@@ -851,15 +983,17 @@ function registerZiNiaoCommands(program2) {
     try {
       const result = await api.getZiNiaoProfiles();
       if (!result.connected) {
-        console.log("Desktop app not connected. Start Optima Browser Operator first.");
+        console.log(formatDesktopNotConnected(result));
         process.exit(1);
       }
       if (!result.ziniao_available) {
         console.log("ZiNiao not available on Desktop app. Start ZiNiao WebDriver mode first.");
+        console.log("Run: browser-cli ziniao doctor  \uFF08\u9010\u9879\u6392\u67E5\u7D2B\u9E1F\u901A\u9053\uFF09");
         process.exit(1);
       }
       if (result.profiles.length === 0) {
         console.log("No ZiNiao profiles found.");
+        console.log("Run: browser-cli ziniao doctor  \uFF08\u9010\u9879\u6392\u67E5\u7D2B\u9E1F\u901A\u9053\uFF0C\u5E38\u89C1\u539F\u56E0\uFF1Arobot \u8D26\u53F7\u7F3A\u300C\u67E5\u770B\u8D26\u53F7\u300D\u6743\u9650\u6216\u672A\u6388\u6743\u5E97\u94FA\uFF09");
         return;
       }
       console.log(`ZiNiao profiles (${result.profiles.length}):
@@ -870,9 +1004,16 @@ function registerZiNiaoCommands(program2) {
       console.log("\nUse: browser-cli launch --connector ziniao --ziniao-profile <id> --url <url>");
     } catch (err) {
       console.error(formatError(err));
+      const hint = ziniaoErrorHint(err?.message ?? "");
+      if (hint) console.error(hint);
       process.exit(1);
     }
   });
+  ziniao.command("doctor").description("Diagnose the ZiNiao Webdriver chain (credentials / desktop / permission / stores)").action(async () => {
+    const { checks, ok } = await runZiNiaoDoctor(api);
+    console.log(formatDoctorReport(checks));
+    if (!ok) process.exit(1);
+  });
   ziniao.command("clear").description("Remove ZiNiao credentials").action(async () => {
     try {
       await api.deleteZiNiaoConfig();
@@ -884,6 +1025,50 @@ function registerZiNiaoCommands(program2) {
   });
 }
 
+// src/commands/recipes.ts
+import { writeFileSync as writeFileSync3 } from "fs";
+function registerRecipeCommands(program2) {
+  program2.command("export-ad-report").description("Export TikTok Shop last-7-days video ad data into the session workspace").requiredOption("--ziniao-profile <id>", "ZiNiao browser profile ID").option("--out <path>", "Output CSV path", "./tt_video_ad_7d.csv").action(async (opts) => {
+    try {
+      const out = await api.runRecipeScript("tiktok_video_ad_export", {
+        ziniao_profile_id: opts.ziniaoProfile
+      });
+      writeFileSync3(opts.out, Buffer.from(out.content_b64, "base64"));
+      console.log(`Saved ${out.filename} -> ${opts.out} (${out.size} bytes)`);
+    } catch (err) {
+      console.error(formatError(err));
+      process.exit(1);
+    }
+  });
+}
+
+// src/commands/bitbrowser.ts
+function registerBitBrowserCommands(program2) {
+  const bitbrowser = program2.command("bitbrowser").description("Manage BitBrowser (\u6BD4\u7279\u6D4F\u89C8\u5668) anti-detect browser");
+  bitbrowser.command("profiles").description("List BitBrowser profiles (requires Desktop app online + BitBrowser running)").action(async () => {
+    try {
+      const result = await api.getBitBrowserProfiles();
+      if (!result.connected) {
+        console.log(formatDesktopNotConnected(result));
+        process.exit(1);
+      }
+      if (result.profiles.length === 0) {
+        console.log("No BitBrowser profiles found. Is BitBrowser running with its local API enabled?");
+        return;
+      }
+      console.log(`BitBrowser profiles (${result.profiles.length}):
+`);
+      for (const p of result.profiles) {
+        console.log(`  ${p.id}  ${p.name}`);
+      }
+      console.log("\nUse: browser-cli launch --connector bitbrowser --bitbrowser-profile <id> --url <url>");
+    } catch (err) {
+      console.error(formatError(err));
+      process.exit(1);
+    }
+  });
+}
+
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
@@ -903,4 +1088,6 @@ registerTabCommands(program);
 registerScriptCommands(program);
 registerProfileCommands(program);
 registerZiNiaoCommands(program);
+registerRecipeCommands(program);
+registerBitBrowserCommands(program);
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optima-chat/browser-cli",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "type": "module",
   "main": "./dist/index.js",
   "bin": {