zevairouter 1.0.34 → 1.0.36

package/src/lib/oauth/services/codebuddyCnBulkImportManager.js

@@ -0,0 +1,1004 @@
+/**
+ * CodeBuddy CN (Tencent Cloud Code Assistant) Bulk Import Manager.
+ *
+ * Extends KiroBulkImportManager to provide bulk phone-number auto-registration
+ * for CodeBuddy CN accounts via the 5sim.net SMS verification service.
+ *
+ * Unlike the global CodeBuddy manager (which uses Google/GSuite login), this
+ * manager registers accounts using virtual phone numbers:
+ *   1. Order a phone number from 5sim (default region: Hong Kong / +852)
+ *   2. Drive Playwright to complete phone registration at www.codebuddy.cn
+ *   3. After registration, initiate device-code OAuth in the same session
+ *   4. Capture the OAuth token and save the provider connection
+ *
+ * Token-capture sequencing (key difference from global):
+ *   The device-code flow is initiated AFTER phone registration completes
+ *   (the browser must hold a logged-in session before navigating to the
+ *   device authorization URL).
+ */
+
+import { randomUUID } from "crypto";
+import {
+  KiroBulkImportManager,
+  buildLookupResponse,
+  createFreshContext,
+  createLogEntry,
+  clampConcurrency,
+  nowIso,
+  KIRO_BULK_IMPORT_DEFAULT_CONCURRENCY,
+  KIRO_BULK_IMPORT_MAX_CONCURRENCY,
+  KIRO_BULK_IMPORT_MIN_CONCURRENCY,
+} from "./kiroBulkImportManager.js";
+import { getProxyPools, getProxyPoolById } from "../../../models/index.js";
+import { getSettings } from "../../localDb.js";
+import { getOptimalWorkerCount, isAutoConcurrencyValue } from "../../systemSpecs.js";
+import { CODEBUDDY_CN_CONFIG } from "../constants/oauth.js";
+import { FiveSimClient, FiveSimTimeoutError } from "./fiveSimClient.js";
+import { runCodeBuddyCnPhoneRegistration } from "./codebuddyCnPhoneAutomation.js";
+import {
+  defaultRequestDeviceCode,
+  defaultPollForToken,
+  fetchCodeBuddyLoginAccount,
+} from "./codebuddyBulkImportManager.js";
+
+const CODEBUDDY_CN_PROVIDER_ID = "codebuddy-cn";
+const CODEBUDDY_CN_LABEL = "CodeBuddy CN";
+const CODEBUDDY_CN_DOMAIN = "www.codebuddy.cn";
+
+// Override default concurrency to 2 (5sim rating system — keep buys conservative)
+const CODEBUDDY_CN_DEFAULT_CONCURRENCY = 2;
+const CODEBUDDY_CN_MAX_CONCURRENCY = 8;
+const CODEBUDDY_CN_MIN_CONCURRENCY = 1;
+
+// Cap on count per job (bound cost/rate)
+const CODEBUDDY_CN_MAX_COUNT = 200;
+
+// Device-code poll timeout (15 min — same as global)
+const CODEBUDDY_CN_POLL_TIMEOUT_MS = 15 * 60_000;
+
+// SMS OTP timeout — if no SMS code arrives within 90s, ban the number immediately.
+// 90s = 60s target + 30s buffer for automation overhead (navigate, select country,
+// input phone, click send code takes ~15-20s before SMS is actually requested).
+const CODEBUDDY_CN_SMS_TIMEOUT_MS = 90_000;
+
+// Supported 5sim regions
+const SUPPORTED_REGIONS = new Set(["hongkong", "china", "any"]);
+const DEFAULT_REGION = "hongkong";
+
+// Hard rule: each account buys exactly ONE 5sim number.
+// No prefix cancel/re-order loops — those burned balance when inventory
+// returned non-[52,54,57] prefixes (historically up to 15 buys per account).
+
+/**
+ * Default phone formatter: strip the leading "+" for forms that expect
+ * the number without the international prefix symbol.
+ * The form may want just digits or the local portion; this can be overridden
+ * via the `phoneFormatter` constructor option.
+ */
+function defaultPhoneFormatter(phone) {
+  // 5sim returns "+852XXXXXXXX" — keep the full E.164 format; the automation
+  // module's parsePhoneNumber() will split it into country code + local number.
+  return String(phone || "").trim();
+}
+
+function clampCnConcurrency(value) {
+  if (isAutoConcurrencyValue(value)) {
+    const optimal = getOptimalWorkerCount();
+    return Math.min(CODEBUDDY_CN_MAX_CONCURRENCY, Math.max(CODEBUDDY_CN_MIN_CONCURRENCY, optimal));
+  }
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed)) return CODEBUDDY_CN_DEFAULT_CONCURRENCY;
+  return Math.min(CODEBUDDY_CN_MAX_CONCURRENCY, Math.max(CODEBUDDY_CN_MIN_CONCURRENCY, parsed));
+}
+
+/**
+ * Save a CodeBuddy CN provider connection to the database.
+ */
+async function defaultSaveCodeBuddyCnConnection({ apiKey, phone, region, fiveSimOrderId, account }) {
+  const { createProviderConnection } = await import("../../../models/index.js");
+
+  const providerSpecificData = {
+    domain: CODEBUDDY_CN_DOMAIN,
+    phoneNumber: phone,
+    fiveSimOrderId,
+    region,
+    automation: "5sim-phone-bulk",
+  };
+
+  const connectionData = {
+    provider: CODEBUDDY_CN_PROVIDER_ID,
+    // Must be "apikey" (no hyphen) — quotaService only treats that as usage-eligible.
+    authType: "apikey",
+    apiKey,
+    accessToken: apiKey,
+    // Prefer name so provider list shows the phone (email alone is often hidden).
+    name: phone || `5sim-${fiveSimOrderId}`,
+    email: phone || `5sim-${fiveSimOrderId}`,
+    providerSpecificData,
+    testStatus: "active",
+  };
+
+  const connection = await createProviderConnection(connectionData);
+  return { connection };
+}
+
+/**
+ * CodeBuddy CN Bulk Import Manager.
+ *
+ * @extends KiroBulkImportManager
+ */
+export class CodeBuddyCnBulkImportManager extends KiroBulkImportManager {
+  constructor({
+    browserLauncher,
+    requestDeviceCodeFn = defaultRequestDeviceCode,
+    pollToken = defaultPollForToken,
+    fetchLoginAccountFn = fetchCodeBuddyLoginAccount,
+    saveConnection = defaultSaveCodeBuddyCnConnection,
+    fiveSimClientFactory = defaultFiveSimClientFactory,
+    phoneAutomation = runCodeBuddyCnPhoneRegistration,
+    phoneFormatter = defaultPhoneFormatter,
+    pollIntervalMs = CODEBUDDY_CN_CONFIG.pollInterval,
+    storageName = "codebuddy-cn-bulk-import",
+  } = {}) {
+    // Camoufox needs proxy on browser launch (not context-only). Headed small
+    // window so operator can watch like other bulk automations (not fullscreen).
+    const cnBrowserLauncher = browserLauncher || (async (job) => {
+      const { launchBulkImportBrowser } = await import("./bulkImportBrowserEngine.js");
+      const proxyUrl = Array.isArray(job?.proxyUrls) && job.proxyUrls.length
+        ? job.proxyUrls[0]
+        : null;
+      return launchBulkImportBrowser({
+        engine: job?.engine || "camoufox",
+        proxyUrl,
+        headless: false,
+        windowSize: { width: 900, height: 700 },
+      });
+    });
+    super({ browserLauncher: cnBrowserLauncher, storageName });
+    this.requestDeviceCode = requestDeviceCodeFn;
+    this.pollToken = pollToken;
+    this.fetchLoginAccount = fetchLoginAccountFn;
+    this.saveConnection = saveConnection;
+    this.fiveSimClientFactory = fiveSimClientFactory;
+    this.phoneAutomation = phoneAutomation;
+    this.phoneFormatter = phoneFormatter;
+    this.pollIntervalMs = pollIntervalMs;
+  }
+
+  /**
+   * Override startJob to accept count-based input instead of email:password list.
+   *
+   * @param {object} opts
+   * @param {number} opts.count             Number of accounts to register
+   * @param {string|number} opts.concurrency
+   * @param {string} opts.engine            Browser engine (chromium/camoufox)
+   * @param {string} opts.proxyPoolMode     none|all|single
+   * @param {string} [opts.proxyPoolId]
+   * @param {string} [opts.region]          5sim region (hongkong|china|any)
+   */
+  async startJob({ count, concurrency, engine, proxyPoolMode, proxyPoolId, region }) {
+    // Validate count
+    const countNum = Number.parseInt(count, 10);
+    if (!Number.isFinite(countNum) || countNum < 1) {
+      throw Object.assign(new Error("At least one account is required (count >= 1)"), {
+        error: "At least one account is required (count >= 1)",
+      });
+    }
+    if (countNum > CODEBUDDY_CN_MAX_COUNT) {
+      throw Object.assign(new Error(`Count exceeds maximum of ${CODEBUDDY_CN_MAX_COUNT}`), {
+        error: `Count exceeds maximum of ${CODEBUDDY_CN_MAX_COUNT}`,
+      });
+    }
+
+    // Block concurrent jobs — double Start / overlapping runs = multiple 5sim buys.
+    const activeJob = [...this.jobs.values()].find((j) =>
+      j && (j.status === "running" || j.status === "queued" || j.status === "needs_manual") && !j.cancelRequested
+    );
+    if (activeJob) {
+      throw Object.assign(
+        new Error(`Another CodeBuddy CN job is still active (${activeJob.jobId}). Cancel it or wait before starting again.`),
+        { error: `Another CodeBuddy CN job is still active (${activeJob.jobId}). Cancel it or wait before starting again.` },
+      );
+    }
+
+    // Validate region
+    const resolvedRegion = SUPPORTED_REGIONS.has(region) ? region : DEFAULT_REGION;
+
+    // Resolve proxy pool URLs for round-robin assignment (copy from base)
+    let proxyUrls = [];
+    if (proxyPoolMode === "all") {
+      const pools = await getProxyPools({ isActive: true });
+      proxyUrls = pools.map((p) => p.proxyUrl).filter(Boolean);
+    } else if (proxyPoolMode === "single" && proxyPoolId) {
+      const pool = await getProxyPoolById(proxyPoolId);
+      if (pool?.isActive && pool?.proxyUrl) {
+        proxyUrls = [pool.proxyUrl];
+      }
+    }
+
+    const jobId = randomUUID();
+    const createdAt = nowIso();
+    const { normalizeBulkImportEngine } = await import("./bulkImportBrowserEngine.js");
+    // Live probe: Camoufox + residential CN proxy is what completes Keycloak login;
+    // Chromium more often lands on 账号访问受限 after OTP.
+    const resolvedEngine = engine ? normalizeBulkImportEngine(engine) : "camoufox";
+
+    const job = {
+      jobId,
+      status: "running",
+      concurrency: clampCnConcurrency(concurrency),
+      engine: resolvedEngine,
+      proxyPoolMode: proxyPoolMode || "none",
+      proxyUrls,
+      region: resolvedRegion,
+      createdAt,
+      startedAt: createdAt,
+      finishedAt: null,
+      error: null,
+      cancelRequested: false,
+      browser: null,
+      nextIndex: 0,
+      manualFollowups: new Set(),
+      persistPromise: Promise.resolve(),
+      lastPreview: null,
+      lastPreviewCapturedAt: 0,
+      accounts: Array.from({ length: countNum }, (_, index) => ({
+        line: index + 1,
+        region: resolvedRegion,
+        phone: null,
+        fiveSimOrderId: null,
+        fiveSimActivationId: null,
+        proxyUrl: null,
+        abortController: new AbortController(),
+        status: "queued",
+        error: null,
+        connectionId: null,
+        workerId: null,
+        manualSession: null,
+        runtimeSession: null,
+        currentStep: "queued",
+        updatedAt: createdAt,
+        logs: [createLogEntry("queued", "Queued and waiting for an available worker")],
+      })),
+    };
+
+    this.jobs.set(jobId, job);
+    this.latestJobId = jobId;
+    await this.persistJobSnapshot(job, { forcePreview: false });
+    // Note: we skip persistResumeBlob (encrypted vault) since there are no
+    // static credentials to resume — each account gets a fresh 5sim number.
+    void this.runJob(jobId);
+    return sanitizeCnJob(job);
+  }
+
+  // Base sanitizeJob only keeps email — CN accounts need phone/order fields in API responses.
+  getJob(jobId) {
+    const job = this.jobs.get(jobId);
+    return job ? sanitizeCnJob(job) : null;
+  }
+
+  async getJobWithPreview(jobId) {
+    const job = this.jobs.get(jobId);
+    if (!job) return null;
+    await this.persistJobSnapshot(job, { forcePreview: false });
+    return sanitizeCnJob(job, { preview: job.lastPreview || null });
+  }
+
+  /**
+   * Override processAccount — the core phone-registration + device-code-token flow.
+   */
+  async processAccount(job, account, workerId) {
+    if (job.cancelRequested || !job.browser) {
+      this.finalizeAccount(account, "cancelled", { error: "Job cancelled" });
+      return;
+    }
+
+    let fiveSimClient = null;
+    let fiveSimOrderId = null;
+    let smsReceived = false;
+    let context = null;
+
+    try {
+      // Step 1: Get 5sim API key from settings
+      this.setAccountStep(account, "reading_settings", "Reading 5sim API key from settings");
+      await this.persistJobSnapshot(job, { forcePreview: true });
+
+      const settings = await getSettings();
+      const fiveSimApiKey = settings.fiveSimApiKey;
+      if (!fiveSimApiKey || !fiveSimApiKey.trim()) {
+        this.finalizeAccount(account, "failed", {
+          error: "5sim API key not configured. Set it in the automation modal or dashboard settings.",
+          step: "failed",
+          message: "5sim API key not configured",
+        });
+        await this.persistJobSnapshot(job, { forcePreview: true });
+        return;
+      }
+
+      // 5sim API must be direct — China residential proxy often cannot reach 5sim.net.
+      // Proxy is only for the Playwright browser session (codebuddy.cn geo).
+      fiveSimClient = this.fiveSimClientFactory({ apiKey: fiveSimApiKey, proxyOptions: null });
+
+      // Step 2: Create browser context FIRST — if proxy/browser fails, we never buy a number.
+      this.setAccountStep(account, "creating_browser", "Creating browser context (before 5sim order)");
+      await this.persistJobSnapshot(job, { forcePreview: true });
+      const freshContext = await createFreshContext(job.browser, account.proxyUrl);
+      context = freshContext.context;
+      const page = freshContext.page;
+      account.runtimeSession = { context, page };
+
+      if (job.cancelRequested) {
+        throw new Error("Job cancelled before ordering phone number");
+      }
+
+      // Step 3–5: Navigate form FIRST, then buy number, then poll SMS after send-code.
+      // This prevents the two balance-burners:
+      //  1) Order then fail on proxy/nav → wasted number
+      //  2) Start 90s SMS timer before send-code → false sms_timeout after slow nav
+      this.setAccountStep(account, "registering", "Running phone registration on CodeBuddy CN");
+      await this.persistJobSnapshot(job, { forcePreview: true });
+
+      const automationResult = await this.phoneAutomation({
+        page,
+        resolvePhone: async () => {
+          if (job.cancelRequested) {
+            throw new Error("Job cancelled before ordering phone number");
+          }
+          this.setAccountStep(
+            account,
+            "ordering_number",
+            `Form ready — ordering ${job.region} phone from 5sim (single buy)`,
+          );
+          await this.persistJobSnapshot(job, { forcePreview: true });
+
+          const numberData = await fiveSimClient.buyNumber({
+            country: job.region,
+            product: "codebuddy",
+            allowProductFallback: false,
+          });
+          fiveSimOrderId = numberData.id;
+          account.phone = numberData.phone;
+          account.fiveSimOrderId = numberData.id;
+          account.fiveSimActivationId = numberData.id;
+          this.setAccountStep(
+            account,
+            "number_ordered",
+            `Phone number ordered: ${numberData.phone} (1 buy, no re-order)`,
+          );
+          await this.persistJobSnapshot(job, { forcePreview: true });
+          return numberData.phone;
+        },
+        waitForSms: async () => {
+          if (!fiveSimOrderId) {
+            throw new Error("Cannot poll SMS — no 5sim order id");
+          }
+          this.setAccountStep(
+            account,
+            "sms_poll_started",
+            `SMS poll started (full ${CODEBUDDY_CN_SMS_TIMEOUT_MS / 1000}s window after send-code)`,
+          );
+          await this.persistJobSnapshot(job, { forcePreview: false });
+          const code = await fiveSimClient.pollCode(fiveSimOrderId, {
+            timeoutMs: CODEBUDDY_CN_SMS_TIMEOUT_MS,
+            signal: account.abortController?.signal,
+          });
+          smsReceived = true;
+          return code;
+        },
+        onStep: (step, message) => {
+          this.setAccountStep(account, step, message);
+          void this.persistJobSnapshot(job, { forcePreview: false });
+        },
+        phoneFormatter: this.phoneFormatter,
+      });
+
+      // Step 6: Try API key capture only if automation reached at least the submit step.
+      // If automation failed early (e.g. page.goto timeout), the session won't be logged in
+      // and API key creation will 401 — so don't waste time. Only try bypass if automation
+      // reported "success" or "needs_manual" (meaning submit happened).
+      if (automationResult.status === "failed") {
+        // Automation failed before submit — no point trying API key
+        const errorMsg = automationResult.error || "Phone registration failed before submit";
+        this.finalizeAccount(account, "failed", {
+          error: errorMsg,
+          step: "failed",
+          message: errorMsg,
+        });
+        // Only touch 5sim if we actually bought a number (order is deferred until form ready)
+        if (fiveSimClient && fiveSimOrderId) {
+          if (smsReceived) {
+            await fiveSimClient.finishOrder(fiveSimOrderId);
+          } else {
+            await fiveSimClient.cancelOrder(fiveSimOrderId);
+          }
+        }
+        account.runtimeSession = null;
+        await context.close().catch(() => null);
+        await this.persistJobSnapshot(job, { forcePreview: true });
+        return;
+      }
+
+      // Automation reached submit (success or needs_manual) — try API key bypass
+      await this.captureApiKey(job, account, context, page, fiveSimClient, fiveSimOrderId);
+      return;
+    } catch (error) {
+      // SMS timeout (60s, no OTP) → BAN the number (bad number that doesn't receive CodeBuddy SMS)
+      const isSmsTimeout = error instanceof FiveSimTimeoutError;
+      const failReason = isSmsTimeout
+        ? `SMS OTP not received within ${CODEBUDDY_CN_SMS_TIMEOUT_MS / 1000}s — number banned`
+        : (error.message || "Unexpected CodeBuddy CN bulk import failure");
+
+      this.finalizeAccount(account, "failed", {
+        error: failReason,
+        step: isSmsTimeout ? "sms_timeout" : "failed",
+        message: failReason,
+      });
+      // 5sim hygiene on error
+      if (fiveSimClient && fiveSimOrderId) {
+        if (smsReceived) {
+          await fiveSimClient.finishOrder(fiveSimOrderId);
+        } else if (isSmsTimeout) {
+          // BAN: number didn't receive CodeBuddy SMS within 60s — it's a bad/burned number
+          await fiveSimClient.banOrder(fiveSimOrderId);
+        } else {
+          await fiveSimClient.cancelOrder(fiveSimOrderId);
+        }
+      }
+      account.runtimeSession = null;
+      if (context) await context.close().catch(() => null);
+      await this.persistJobSnapshot(job, { forcePreview: true });
+    }
+  }
+
+  /**
+   * Complete the device-code OAuth capture after phone registration succeeds.
+   *
+   * Steps 7-12: request device code → navigate to authUrl → poll token → save.
+   */
+  /**
+   * Capture API key after phone registration succeeds.
+   *
+   * The browser is now logged in to codebuddy.cn. Navigate to /profile/keys
+   * and POST to /console/api/client/v1/api-keys to create an API key.
+   * Save the key as a provider connection.
+   */
+  async captureApiKey(job, account, context, page, fiveSimClient, fiveSimOrderId) {
+    const PERSONAL_ENTERPRISE_ID = "personal-edition-user-id";
+
+    try {
+      // Functional session establishment — do NOT hard-require KEYCLOAK_IDENTITY.
+      // Live failures show OTP can succeed with AUTH_SESSION_ID + session + qcloud_uid
+      // while KEYCLOAK_IDENTITY never appears (mid-OIDC). What matters is whether
+      // /console/accounts and api-keys accept the browser cookies.
+      this.setAccountStep(account, "waiting_session", "Establishing CodeBuddy console session (probe APIs, not just cookies)");
+      await this.persistJobSnapshot(job, { forcePreview: true });
+
+      const cookieSnapshot = async () => {
+        const cookies = await context.cookies().catch(() => []);
+        return {
+          cookies,
+          names: new Set(cookies.map((c) => c.name)),
+          list: cookies.map((c) => c.name),
+        };
+      };
+
+      const hasStrongKeycloak = (names) =>
+        names.has("KEYCLOAK_IDENTITY")
+        || names.has("KEYCLOAK_SESSION")
+        || names.has("KEYCLOAK_IDENTITY_LEGACY")
+        || names.has("KEYCLOAK_SESSION_LEGACY");
+
+      const hasSoftSession = (names) =>
+        names.has("AUTH_SESSION_ID")
+        || names.has("session")
+        || names.has("qcloud_uid")
+        || names.has("qcmainCSRFToken");
+
+      const probeConsoleAccounts = async () => page.evaluate(async () => {
+        try {
+          const res = await fetch("/console/accounts", {
+            credentials: "include",
+            headers: {
+              Accept: "application/json, text/plain, */*",
+              "x-requested-with": "XMLHttpRequest",
+              "X-Domain": window.location.hostname || "www.codebuddy.cn",
+            },
+          });
+          const data = await res.json().catch(() => null);
+          return { status: res.status, data };
+        } catch (error) {
+          return { status: 0, error: error?.message || String(error) };
+        }
+      }).catch(() => null);
+
+      const extractAccountList = (probe) =>
+        probe?.data?.data?.accounts || probe?.data?.accounts || [];
+
+      // Navigate sequence to finish OIDC handoff when only AUTH_SESSION_ID is present.
+      const oIDCNudgePaths = [
+        "https://www.codebuddy.cn/",
+        "https://www.codebuddy.cn/login/",
+        "https://www.codebuddy.cn/console",
+        "https://www.codebuddy.cn/profile",
+        "https://www.codebuddy.cn/profile/keys",
+      ];
+
+      let accountList = [];
+      let accountsProbe = null;
+      let sessionReady = false;
+
+      for (let attempt = 0; attempt < 18; attempt += 1) {
+        if (job.cancelRequested) {
+          throw new Error("Job cancelled while establishing session");
+        }
+
+        const snap = await cookieSnapshot();
+        const strong = hasStrongKeycloak(snap.names);
+        const soft = hasSoftSession(snap.names);
+
+        // Progressive navigation to complete half-finished Keycloak login
+        const path = oIDCNudgePaths[Math.min(attempt, oIDCNudgePaths.length - 1)];
+        if (attempt === 0 || attempt === 2 || attempt === 5 || attempt === 8 || attempt === 12) {
+          this.setAccountStep(
+            account,
+            "waiting_session",
+            `OIDC handoff attempt ${attempt + 1}/18 → ${path} (cookies: ${strong ? "KEYCLOAK" : soft ? "soft-session" : "weak"})`,
+          );
+          await this.persistJobSnapshot(job, { forcePreview: false });
+          await page.goto(path, { waitUntil: "domcontentloaded", timeout: 45_000 }).catch(() => null);
+          await page.waitForTimeout(2_500);
+
+          // If Keycloak login iframe reappears, user session is not complete —
+          // don't treat blank SPA as success; keep probing.
+        } else {
+          await page.waitForTimeout(1_500);
+        }
+
+        // Prefer landing on console for the API probe
+        if (attempt >= 3 && !String(page.url() || "").includes("/console")) {
+          await page.goto("https://www.codebuddy.cn/console", {
+            waitUntil: "domcontentloaded",
+            timeout: 45_000,
+          }).catch(() => null);
+          await page.waitForTimeout(1_500);
+        }
+
+        accountsProbe = await probeConsoleAccounts();
+        accountList = extractAccountList(accountsProbe);
+        if (accountsProbe?.status === 200 && Array.isArray(accountList) && accountList.length > 0) {
+          sessionReady = true;
+          this.setAccountStep(
+            account,
+            "session_ready",
+            `Console session accepted (HTTP 200, ${accountList.length} account(s)${strong ? ", KEYCLOAK ok" : ", soft session"})`,
+          );
+          await this.persistJobSnapshot(job, { forcePreview: true });
+          break;
+        }
+
+        this.setAccountStep(
+          account,
+          "resolving_enterprise",
+          `Console not ready (HTTP ${accountsProbe?.status || 0}) — retry ${attempt + 1}/18`,
+        );
+        await this.persistJobSnapshot(job, { forcePreview: false });
+      }
+
+      if (!sessionReady || !Array.isArray(accountList) || accountList.length === 0) {
+        const snap = await cookieSnapshot();
+        throw new Error(
+          `Console accounts unavailable after login (HTTP ${accountsProbe?.status || 0}; cookies: ${snap.list.slice(0, 18).join(",") || "(none)"}) — session not accepted for API key`,
+        );
+      }
+
+      let userEnterpriseId = PERSONAL_ENTERPRISE_ID;
+      const preferred = accountList.find((entry) => entry?.lastLogin) || accountList[0];
+      if (preferred?.type && preferred.type !== "personal" && preferred.enterpriseId) {
+        userEnterpriseId = preferred.enterpriseId;
+      }
+
+      // Create API key — CN requires user_enterprise_id (400 code 12505 without it).
+      this.setAccountStep(account, "creating_api_key", `Creating API key (enterprise=${userEnterpriseId})`);
+      await this.persistJobSnapshot(job, { forcePreview: true });
+
+      const createKeyOnPage = async (enterpriseId) => page.evaluate(async ({ enterpriseId: entId }) => {
+        const res = await fetch("/console/api/client/v1/api-keys", {
+          method: "POST",
+          credentials: "include",
+          headers: {
+            "Content-Type": "application/json",
+            Accept: "application/json, text/plain, */*",
+            "x-requested-with": "XMLHttpRequest",
+            "X-Domain": window.location.hostname || "www.codebuddy.cn",
+            "X-Product": "SaaS",
+          },
+          body: JSON.stringify({
+            name: `zevai-router-${Date.now()}`,
+            expire_in_days: 365,
+            user_enterprise_id: entId,
+          }),
+        });
+        const data = await res.json().catch(() => null);
+        return { ok: res.ok, status: res.status, data };
+      }, { enterpriseId });
+
+      let apiKeyResult = await createKeyOnPage(userEnterpriseId).catch(() => null);
+
+      // Retry from keys page if console path was not enough.
+      if (!apiKeyResult || !apiKeyResult.ok) {
+        this.setAccountStep(account, "retrying_api_key", "Retrying API key creation from profile/keys");
+        await this.persistJobSnapshot(job, { forcePreview: true });
+        await page.goto("https://www.codebuddy.cn/profile/keys", {
+          waitUntil: "domcontentloaded",
+          timeout: 45_000,
+        }).catch(() => null);
+        await page.waitForTimeout(2_500);
+        apiKeyResult = await createKeyOnPage(userEnterpriseId).catch(() => null);
+      }
+
+      // Last resort: personal edition id explicitly.
+      if ((!apiKeyResult || !apiKeyResult.ok) && userEnterpriseId !== PERSONAL_ENTERPRISE_ID) {
+        apiKeyResult = await createKeyOnPage(PERSONAL_ENTERPRISE_ID).catch(() => null);
+      }
+
+      // One more full nudge cycle if key creation returned 401/403 (session half-baked)
+      const status = apiKeyResult?.status;
+      if (!apiKeyResult?.ok && (status === 401 || status === 403 || status === 0 || !apiKeyResult)) {
+        this.setAccountStep(account, "retrying_api_key", "API key 401/403 — re-running OIDC handoff then retry");
+        await this.persistJobSnapshot(job, { forcePreview: true });
+        for (const path of ["https://www.codebuddy.cn/login/", "https://www.codebuddy.cn/", "https://www.codebuddy.cn/console", "https://www.codebuddy.cn/profile/keys"]) {
+          await page.goto(path, { waitUntil: "domcontentloaded", timeout: 45_000 }).catch(() => null);
+          await page.waitForTimeout(2_000);
+        }
+        apiKeyResult = await createKeyOnPage(PERSONAL_ENTERPRISE_ID).catch(() => null);
+      }
+
+      const businessCode = apiKeyResult?.data?.code;
+      const businessOk = businessCode === 0 || businessCode === 200 || typeof businessCode === "undefined";
+      if (!apiKeyResult || !apiKeyResult.ok || !apiKeyResult.data || !businessOk) {
+        throw new Error(
+          `API key creation failed (HTTP ${apiKeyResult?.status ?? "no-response"}, code=${businessCode ?? "n/a"}): ${JSON.stringify(apiKeyResult?.data ?? null).slice(0, 200)}`,
+        );
+      }
+
+      // Extract the API key from the response — CodeBuddy wraps secrets under data.*
+      const payload = apiKeyResult.data?.data || apiKeyResult.data;
+      const apiKey =
+        payload?.apiKey ||
+        payload?.key ||
+        payload?.token ||
+        payload?.secret ||
+        payload?.api_key ||
+        (typeof payload === "string" ? payload : null) ||
+        apiKeyResult.data.apiKey ||
+        apiKeyResult.data.key ||
+        apiKeyResult.data.token ||
+        apiKeyResult.data.secret;
+
+      if (!apiKey || typeof apiKey !== "string") {
+        throw new Error(
+          `API key response did not contain a key field: ${JSON.stringify(apiKeyResult.data).slice(0, 300)}`,
+        );
+      }
+
+      this.setAccountStep(account, "api_key_created", `API key created successfully`);
+      await this.persistJobSnapshot(job, { forcePreview: true });
+
+      // Step 9: Save connection
+      this.setAccountStep(account, "saving_connection", "Saving CodeBuddy CN connection");
+      await this.persistJobSnapshot(job, { forcePreview: true });
+
+      const { connection } = await this.saveConnection({
+        apiKey,
+        phone: account.phone,
+        region: account.region,
+        fiveSimOrderId,
+        account,
+      });
+
+      // Step 10: Finish 5sim order + finalize
+      await fiveSimClient.finishOrder(fiveSimOrderId);
+
+      this.finalizeAccount(account, "success", {
+        connectionId: connection.id,
+        step: "connection_saved",
+        message: `CodeBuddy CN connection saved (phone: ${account.phone})`,
+      });
+      account.runtimeSession = null;
+      await context.close().catch(() => null);
+      await this.persistJobSnapshot(job, { forcePreview: true });
+    } catch (error) {
+      // If API key capture fails after registration, the account is registered
+      // but we don't have a key. Surface as needs_manual so the operator can
+      // create the key manually in the opened browser — number is NOT re-bought.
+      this.finalizeAccount(account, "needs_manual", {
+        error: `Registration succeeded but API key capture failed: ${error.message}`,
+        step: "awaiting_manual",
+        message: `Registration done, API key capture failed: ${error.message}`,
+      });
+      // The 5sim order was successful (SMS received) — finish it (no re-order)
+      await fiveSimClient.finishOrder(fiveSimOrderId).catch(() => null);
+      await this.persistJobSnapshot(job, { forcePreview: true });
+
+      // Start manual followup for API key capture (reuse same browser session)
+      await this.runCnManualFollowup(job, account, account.workerId, context, page, fiveSimClient, fiveSimOrderId);
+    }
+  }
+
+  /**
+   * Manual followup — operator completes registration/captcha/API-key creation in a
+   * headed browser. We wait for the operator to finish, then try to capture the API key.
+   */
+  async runCnManualFollowup(job, account, workerId, context, page, fiveSimClient, fiveSimOrderId) {
+    const followupPromise = (async () => {
+      const closeManualResources = async () => {
+        const ms = account.manualSession;
+        const ctx = ms?.context || context;
+        const headed = ms?.headedBrowser || null;
+        if (ctx) await ctx.close().catch(() => null);
+        if (headed) await headed.close().catch(() => null);
+      };
+
+      try {
+        this.setAccountStep(account, "manual_waiting", "Waiting for operator to complete in headed browser");
+        await this.persistJobSnapshot(job, { forcePreview: true });
+
+        // Wait for the operator to complete — poll for the API keys page being loaded
+        // and an API key being available. Give them up to 15 minutes.
+        const deadline = Date.now() + 15 * 60_000;
+        let apiKey = null;
+
+        while (Date.now() < deadline && !job.cancelRequested) {
+          await new Promise((r) => setTimeout(r, 10_000)); // Check every 10s
+
+          // Check if the operator has navigated to the keys page and we can create a key
+          try {
+            const currentUrl = page.url();
+            if (!currentUrl.includes("codebuddy.cn")) continue;
+
+            // Try to create an API key via the console API (include enterprise id)
+            const result = await page.evaluate(async () => {
+              const res = await fetch("/console/api/client/v1/api-keys", {
+                method: "POST",
+                headers: {
+                  "Content-Type": "application/json",
+                  Accept: "application/json, text/plain, */*",
+                  "x-requested-with": "XMLHttpRequest",
+                  "X-Domain": window.location.hostname || "www.codebuddy.cn",
+                  "X-Product": "SaaS",
+                },
+                credentials: "include",
+                body: JSON.stringify({
+                  name: "zevai-router-manual-" + Date.now(),
+                  expire_in_days: 365,
+                  user_enterprise_id: "personal-edition-user-id",
+                }),
+              });
+              const data = await res.json().catch(() => null);
+              return { ok: res.ok, status: res.status, data };
+            });
+
+            if (result?.ok && result.data) {
+              const payload = result.data?.data || result.data;
+              apiKey =
+                payload?.apiKey ||
+                payload?.key ||
+                payload?.token ||
+                payload?.secret ||
+                payload?.api_key ||
+                (typeof payload === "string" ? payload : null);
+              if (apiKey && typeof apiKey === "string") break;
+            }
+          } catch {
+            // Operator might still be completing — keep waiting
+          }
+        }
+
+        if (job.cancelRequested) {
+          this.finalizeAccount(account, "cancelled", {
+            error: "Job cancelled",
+            step: "cancelled",
+            message: "Job cancelled while waiting for manual completion",
+          });
+          await this.persistJobSnapshot(job, { forcePreview: true });
+          return;
+        }
+
+        if (!apiKey) {
+          throw new Error("Manual assist timed out — could not capture API key");
+        }
+
+        // Save connection
+        this.setAccountStep(account, "saving_connection", "Saving CodeBuddy CN connection (manual)");
+        await this.persistJobSnapshot(job, { forcePreview: true });
+
+        const { connection } = await this.saveConnection({
+          apiKey,
+          phone: account.phone,
+          region: account.region,
+          fiveSimOrderId,
+          account,
+        });
+
+        this.finalizeAccount(account, "success", {
+          connectionId: connection.id,
+          step: "connection_saved",
+          message: `CodeBuddy CN connection saved via manual assist (phone: ${account.phone || "N/A"})`,
+        });
+        await this.persistJobSnapshot(job, { forcePreview: true });
+      } catch (error) {
+        if (job.cancelRequested) {
+          this.finalizeAccount(account, "cancelled", {
+            error: "Job cancelled",
+            step: "cancelled",
+            message: "Job cancelled while waiting for manual completion",
+          });
+        } else {
+          this.finalizeAccount(account, "failed", {
+            error: error.message || "Manual assist flow failed",
+            step: "failed",
+            message: error.message || "Manual assist flow failed",
+          });
+        }
+        await this.persistJobSnapshot(job, { forcePreview: true });
+      } finally {
+        await closeManualResources();
+        account.manualSession = null;
+        account.runtimeSession = null;
+        job.manualFollowups.delete(followupPromise);
+        await this.persistJobSnapshot(job, { forcePreview: true });
+      }
+    })();
+
+    job.manualFollowups.add(followupPromise);
+  }
+
+  /**
+   * Override cancelJob to abort in-flight 5sim polls and clean up orders.
+   */
+  cancelJob(jobId) {
+    const job = this.jobs.get(jobId);
+    if (!job) return null;
+
+    job.cancelRequested = true;
+
+    // Abort in-flight 5sim polls for all running accounts
+    for (const account of job.accounts) {
+      if (account.abortController && !account.abortController.signal.aborted) {
+        account.abortController.abort();
+      }
+    }
+
+    if (job.status === "queued") {
+      job.status = "cancelled";
+      job.finishedAt = nowIso();
+      job.accounts.forEach((account) => {
+        if (account.status === "queued") account.status = "cancelled";
+      });
+    }
+    return job;
+  }
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────
+
+function defaultFiveSimClientFactory({ apiKey, proxyOptions }) {
+  return new FiveSimClient({ apiKey, proxyOptions });
+}
+
+/**
+ * Sanitize a job for API response (strip non-serializable fields like
+ * AbortController, runtimeSession, etc.).
+ */
+function buildCnSummary(accounts = []) {
+  const summary = {
+    total: accounts.length,
+    queued: 0,
+    running: 0,
+    completed: 0,
+    success: 0,
+    failed: 0,
+    needs_manual: 0,
+    cancelled: 0,
+  };
+  for (const account of accounts) {
+    const status = account.status || "queued";
+    if (status === "success") {
+      summary.success += 1;
+      summary.completed += 1;
+    } else if (status === "failed" || status === "failed_exchange") {
+      summary.failed += 1;
+      summary.completed += 1;
+    } else if (status === "needs_manual") {
+      summary.needs_manual += 1;
+    } else if (status === "cancelled") {
+      summary.cancelled += 1;
+      summary.completed += 1;
+    } else if (status === "running") {
+      summary.running += 1;
+    } else {
+      summary.queued += 1;
+    }
+  }
+  return summary;
+}
+
+function sanitizeCnJob(job, extras = {}) {
+  if (!job) return null;
+  return {
+    jobId: job.jobId,
+    status: job.status,
+    summary: buildCnSummary(job.accounts),
+    concurrency: job.concurrency,
+    engine: job.engine,
+    proxyPoolMode: job.proxyPoolMode,
+    region: job.region,
+    createdAt: job.createdAt,
+    startedAt: job.startedAt,
+    finishedAt: job.finishedAt,
+    error: job.error,
+    cancelRequested: job.cancelRequested,
+    accounts: (job.accounts || []).map((account) => ({
+      line: account.line,
+      region: account.region,
+      phone: account.phone,
+      fiveSimOrderId: account.fiveSimOrderId,
+      proxyUrl: account.proxyUrl ? maskProxyUrl(account.proxyUrl) : null,
+      status: account.status,
+      error: account.error,
+      connectionId: account.connectionId,
+      workerId: account.workerId,
+      manualSessionAvailable: !!account.manualSession,
+      currentStep: account.currentStep,
+      updatedAt: account.updatedAt,
+      logs: account.logs || [],
+    })),
+    preview: extras.preview !== undefined ? extras.preview : (job.lastPreview || null),
+    ...extras,
+  };
+}
+
+function maskProxyUrl(url) {
+  if (!url) return null;
+  try {
+    const parsed = new URL(url);
+    if (parsed.password) {
+      parsed.password = "***";
+    }
+    return parsed.toString();
+  } catch {
+    return url;
+  }
+}
+
+// ─── Singleton ────────────────────────────────────────────────────────────
+
+function getSingletonStore() {
+  if (!globalThis.__codeBuddyCnBulkImportSingleton) {
+    globalThis.__codeBuddyCnBulkImportSingleton = {
+      manager: new CodeBuddyCnBulkImportManager(),
+    };
+  }
+  return globalThis.__codeBuddyCnBulkImportSingleton;
+}
+
+export function getCodeBuddyCnBulkImportManager() {
+  return getSingletonStore().manager;
+}
+
+export {
+  buildLookupResponse,
+  CODEBUDDY_CN_DEFAULT_CONCURRENCY,
+  CODEBUDDY_CN_MAX_CONCURRENCY,
+  CODEBUDDY_CN_MIN_CONCURRENCY,
+  CODEBUDDY_CN_MAX_COUNT,
+  SUPPORTED_REGIONS,
+  DEFAULT_REGION,
+};
+
+export const __test__ = {
+  clampCnConcurrency,
+  sanitizeCnJob,
+  defaultPhoneFormatter,
+  defaultSaveCodeBuddyCnConnection,
+};