@zenrows/cli 1.6.2 → 1.8.0

package/dist/src/core/browser-api.js

@@ -12,6 +12,7 @@
  * them (`closeSession`) — the `browser run` command does so in a `finally`.
  */
 import { ToolkitError, isKeyCapReached, keyCapReached, quotaExhausted } from "./errors.js";
+import { storedClaimHint } from "./claim-link.js";
 import { readAccount } from "./agent-account.js";
 import { registerSecret } from "./logger.js";
 import { CLI_USER_AGENT } from "./config.js";
@@ -116,7 +117,7 @@ export function browserProblemToError(status, body, method, path) {
     if (status === 402) {
         // Out of credits — same exhausted state as the scraper/batch 402.
         const acct = readAccount();
-        return quotaExhausted(`${method} ${path}`, acct?.unclaimed ? acct.claimUrl : undefined, {
+        return quotaExhausted(`${method} ${path}`, storedClaimHint(acct), {
             status: 402,
             detail: parsed.error || parsed.detail || parsed.title || undefined,
         });

package/dist/src/core/claim-link.js

@@ -0,0 +1,237 @@
+import { randomBytes } from "node:crypto";
+import { linkSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { accountPath, fetchAccountStatus, isZenrowsHttpsUrl, readAccount, requestClaimLink, writeAccount } from "./agent-account.js";
+import { resolveApiKey } from "./auth.js";
+import { CLAIM_LINK_REFRESH, CLAIM_NEXT_ACTION_PREFIX, ToolkitError, quotaNextAction } from "./errors.js";
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** The backend's claim-link lifetime. A link this old no longer works. */
+export const CLAIM_LINK_TTL_MS = 30 * DAY_MS;
+/** Ask for a fresh link once the held one is this old, before it lapses. */
+export const CLAIM_LINK_REFRESH_AGE_MS = 25 * DAY_MS;
+/** On error paths, check claim status at most this often. */
+export const CLAIM_CHECK_THROTTLE_MS = 6 * 60 * 60 * 1000;
+/** Each claim request gives up after this long, so an error is never held up for long. */
+const CLAIM_REQUEST_TIMEOUT_MS = 5000;
+/** Only an https link on zenrows.com (or a subdomain), with no userinfo, is shown or opened. */
+export function isTrustedClaimUrl(value) {
+    return isZenrowsHttpsUrl(value);
+}
+/** Age of the held link in ms, or Infinity when its issue time is unknown. */
+function linkAgeMs(acct, now) {
+    const issued = new Date(acct.claimUrlIssuedAt ?? acct.createdAt).getTime();
+    return Number.isNaN(issued) ? Infinity : now.getTime() - issued;
+}
+/** The held link if it is trusted and not yet expired, else undefined. No network. */
+export function usableClaimUrl(acct, now = new Date()) {
+    if (!isTrustedClaimUrl(acct.claimUrl))
+        return undefined;
+    return linkAgeMs(acct, now) < CLAIM_LINK_TTL_MS ? acct.claimUrl : undefined;
+}
+/** The claim hint for an error from local state alone. No network. */
+export function storedClaimHint(acct, now = new Date()) {
+    if (!acct?.unclaimed)
+        return undefined;
+    return usableClaimUrl(acct, now) ?? CLAIM_LINK_REFRESH;
+}
+/**
+ * Bring the stored claim state up to date, as far as the network allows, and
+ * report it. Steps: ask whether the account was claimed; if not, and the held
+ * link is missing, untrusted or 25+ days old, mint a fresh one and store it.
+ * Network failures are swallowed: the held link is still offered while it is
+ * under 30 days old. Unless `force` is set, the network is skipped entirely
+ * when the last check was under 6 hours ago. Throws only for a forced call
+ * whose fresh-link request failed with no usable link to fall back on.
+ */
+export async function refreshClaimState(opts = {}) {
+    const { projectRoot } = opts;
+    const now = opts.now ?? new Date();
+    const first = readAccount(projectRoot);
+    if (!first)
+        return { status: "none" };
+    if (!first.unclaimed)
+        return { status: "claimed" };
+    if (!opts.force && throttled(first, now))
+        return offlineState(first, now);
+    const key = opts.apiKey ?? resolveApiKey(projectRoot).key;
+    if (!key)
+        return offlineState(first, now);
+    // Several `zenrows` processes can hit a 402 at once. Only the one holding the
+    // lock talks to the claim endpoints; the others use what is stored.
+    const release = acquireClaimLock(projectRoot);
+    if (!release)
+        return offlineState(readAccount(projectRoot) ?? first, now);
+    try {
+        return await refreshLocked(key, opts, now);
+    }
+    finally {
+        release();
+    }
+}
+async function refreshLocked(key, opts, now) {
+    const { projectRoot } = opts;
+    // Re-read under the lock: another process may have just finished a refresh.
+    let acct = readAccount(projectRoot);
+    if (!acct)
+        return { status: "none" };
+    if (!acct.unclaimed)
+        return { status: "claimed" };
+    if (!opts.force && throttled(acct, now))
+        return offlineState(acct, now);
+    // Take the 6-hour slot before any network call, so a failing backend is not
+    // retried by every command that follows.
+    acct = { ...acct, lastClaimCheckAt: now.toISOString() };
+    writeAccount(acct, projectRoot);
+    const base = opts.fetchImpl ?? fetch;
+    const fetchImpl = ((url, init) => base(url, { ...init, signal: AbortSignal.timeout(CLAIM_REQUEST_TIMEOUT_MS) }));
+    try {
+        const remote = await fetchAccountStatus(key, { url: opts.accountUrl, fetchImpl, projectRoot });
+        if (remote.claimed === true)
+            return markClaimed(acct, projectRoot);
+    }
+    catch {
+        // Status unknown: carry on and judge the held link on its own.
+    }
+    // Re-read before minting: minting replaces the link everyone else holds.
+    acct = readAccount(projectRoot) ?? acct;
+    if (!acct.unclaimed)
+        return { status: "claimed" };
+    if (!needsNewLink(acct, now))
+        return offlineState(acct, now);
+    let fresh;
+    try {
+        fresh = await requestClaimLink(key, { url: opts.claimUrl, fetchImpl, projectRoot });
+    }
+    catch (err) {
+        if (opts.force && !usableClaimUrl(acct, now)) {
+            if (err instanceof ToolkitError)
+                throw err;
+            throw new ToolkitError({
+                code: "BACKEND_UNAVAILABLE",
+                message: "Could not reach Zenrows to get a fresh claim link.",
+                likely_cause: err instanceof Error ? err.message : String(err),
+                next_action: "The stored claim link has expired. Check connectivity and run `zenrows account claim` again.",
+                suggested_commands: ["zenrows account claim"],
+            });
+        }
+        return offlineState(acct, now);
+    }
+    // Both 409s are final: a person owns the account, so there is nothing to claim.
+    if (fresh.status === "claimed" || fresh.status === "not_agent")
+        return markClaimed(acct, projectRoot);
+    if (!isTrustedClaimUrl(fresh.claimUrl)) {
+        if (opts.force && !usableClaimUrl(acct, now)) {
+            throw new ToolkitError({
+                code: "FETCH_FAILED",
+                message: "The claim-link endpoint returned a URL outside zenrows.com; it was not used.",
+                likely_cause: "The signup/claim endpoint override points at an unexpected server.",
+                next_action: "Check ZENROWS_AGENT_SIGNUP_URL / `signupUrl` in the zenrows config, then retry.",
+            });
+        }
+        return offlineState(acct, now);
+    }
+    const latest = readAccount(projectRoot) ?? acct;
+    writeAccount({ ...latest, claimUrl: fresh.claimUrl, claimUrlIssuedAt: now.toISOString() }, projectRoot);
+    return { status: "unclaimed", claimUrl: fresh.claimUrl, refreshed: true };
+}
+function throttled(acct, now) {
+    if (!acct.lastClaimCheckAt)
+        return false;
+    const last = new Date(acct.lastClaimCheckAt).getTime();
+    return !Number.isNaN(last) && now.getTime() - last < CLAIM_CHECK_THROTTLE_MS;
+}
+function needsNewLink(acct, now) {
+    return !isTrustedClaimUrl(acct.claimUrl) || linkAgeMs(acct, now) >= CLAIM_LINK_REFRESH_AGE_MS;
+}
+function offlineState(acct, now) {
+    if (!acct.unclaimed)
+        return { status: "claimed" };
+    return { status: "unclaimed", claimUrl: usableClaimUrl(acct, now), refreshed: false };
+}
+/** A lock older than this is from a process that died mid-refresh. */
+const CLAIM_LOCK_STALE_MS = 60 * 1000;
+/**
+ * Create `account.json.lock` exclusively, holding a random token. Returns a
+ * release function, or null when another live process holds the lock.
+ *
+ * A lock older than CLAIM_LOCK_STALE_MS is taken over by renaming it aside
+ * first (only one process can rename it away). If what was renamed turns out
+ * to be live, it is put back and this process gives up. Release deletes the
+ * lock only while it still holds this process's token.
+ */
+function acquireClaimLock(projectRoot) {
+    const lock = `${accountPath(projectRoot)}.lock`;
+    const token = randomBytes(16).toString("hex");
+    const release = () => {
+        try {
+            if (readFileSync(lock, "utf8") === token)
+                unlinkSync(lock);
+        }
+        catch {
+        }
+    };
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            writeFileSync(lock, token, { flag: "wx", mode: 0o600 });
+            return readFileSync(lock, "utf8") === token ? release : null;
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                return null;
+            try {
+                if (Date.now() - statSync(lock).mtimeMs < CLAIM_LOCK_STALE_MS)
+                    return null;
+                const aside = `${lock}.${token}.stale`;
+                renameSync(lock, aside);
+                if (Date.now() - statSync(aside).mtimeMs < CLAIM_LOCK_STALE_MS) {
+                    // Another process replaced the stale lock between our checks: restore it.
+                    try {
+                        linkSync(aside, lock);
+                    }
+                    catch {
+                    }
+                    unlinkSync(aside);
+                    return null;
+                }
+                unlinkSync(aside);
+            }
+            catch {
+                return null;
+            }
+        }
+    }
+    return null;
+}
+/** Test-only: the lock path, so tests can simulate other processes. */
+export function _claimLockPath(projectRoot) {
+    return `${accountPath(projectRoot)}.lock`;
+}
+function markClaimed(acct, projectRoot) {
+    writeAccount({ ...acct, unclaimed: false }, projectRoot);
+    return { status: "claimed" };
+}
+/** The error hint for a refreshed state. */
+export function claimHintFor(state) {
+    if (state.status !== "unclaimed")
+        return undefined;
+    return state.claimUrl ?? CLAIM_LINK_REFRESH;
+}
+/**
+ * Bring a quota error's claim advice up to date before it is shown. Errors are
+ * built synchronously from `account.json`; this runs the throttled refresh and
+ * rewrites `next_action` if the account was claimed or the link changed. Never
+ * throws: on any failure the error is returned as it was.
+ */
+export async function refreshClaimAdvice(err, opts = {}) {
+    try {
+        if (!(err instanceof ToolkitError) || !err.next_action.startsWith(CLAIM_NEXT_ACTION_PREFIX))
+            return err;
+        const state = await refreshClaimState({ ...opts, force: false });
+        const next = quotaNextAction(claimHintFor(state));
+        if (next === err.next_action)
+            return err;
+        return new ToolkitError({ ...err.toJSON(), next_action: next });
+    }
+    catch {
+        return err;
+    }
+}

package/dist/src/core/config.js

@@ -14,7 +14,7 @@ export const CONFIG_VERSION = "0.1.0";
  * entrypoint) so core modules — telemetry, signup provenance — can read it
  * without an import cycle. `VERSION` in `cli/index.ts` re-exports this.
  */
-export const CLI_VERSION = "1.6.2"; // x-release-please-version
+export const CLI_VERSION = "1.8.0"; // x-release-please-version
 /** The User-Agent on every request to a Zenrows API. The gateway reads the version from it. */
 export const CLI_USER_AGENT = `zenrows-cli/${CLI_VERSION}`;
 /** Env var to override the Fetch and Extract API base (local/staging testing). */

package/dist/src/core/crawl-api.js

@@ -15,6 +15,7 @@
  */
 import { Readable } from "node:stream";
 import { ToolkitError, isKeyCapReached, keyCapReached, quotaExhausted } from "./errors.js";
+import { storedClaimHint } from "./claim-link.js";
 import { readAccount } from "./agent-account.js";
 import { registerSecret } from "./logger.js";
 import { CLI_USER_AGENT, loadConfig } from "./config.js";
@@ -245,7 +246,7 @@ function classifyProblem(status, problem, body, request, serverCode, retryAfter)
             return new ToolkitError({ ...keyCapReached(request, { status, detail }).toJSON(), code: "CRAWL_KEY_CAP_REACHED" });
         }
         const acct = readAccount();
-        const quota = quotaExhausted(request, acct?.unclaimed ? acct.claimUrl : undefined, { status, detail });
+        const quota = quotaExhausted(request, storedClaimHint(acct), { status, detail });
         return new ToolkitError({ ...quota.toJSON(), code: "CRAWL_INSUFFICIENT_CREDITS" });
     }
     if (status === 409) {

package/dist/src/core/ensure-key.js

@@ -15,6 +15,7 @@ export async function ensureApiKey(policy, opts = {}) {
         claimUrl: res.claimUrl,
         createdAt: new Date().toISOString(),
     };
+    account.claimUrlIssuedAt = account.createdAt;
     writeAccount(account, opts.projectRoot);
     opts.onProvision?.(account);
     return res.apiKey;

package/dist/src/core/errors.js

@@ -13,6 +13,8 @@ export class ToolkitError extends Error {
     suggested_commands;
     server_code;
     crawl_id;
+    job_id;
+    idempotency_key;
     retry_after;
     constructor(shape) {
         super(shape.message);
@@ -23,6 +25,8 @@ export class ToolkitError extends Error {
         this.suggested_commands = shape.suggested_commands ?? [];
         this.server_code = shape.server_code;
         this.crawl_id = shape.crawl_id;
+        this.job_id = shape.job_id;
+        this.idempotency_key = shape.idempotency_key;
         this.retry_after = shape.retry_after;
     }
     toJSON() {
@@ -34,6 +38,8 @@ export class ToolkitError extends Error {
             suggested_commands: this.suggested_commands,
             ...(this.server_code ? { server_code: this.server_code } : {}),
             ...(this.crawl_id ? { crawl_id: this.crawl_id } : {}),
+            ...(this.job_id ? { job_id: this.job_id } : {}),
+            ...(this.idempotency_key ? { idempotency_key: this.idempotency_key } : {}),
             ...(this.retry_after !== undefined ? { retry_after: this.retry_after } : {}),
         };
     }
@@ -49,26 +55,36 @@ export class ToolkitError extends Error {
  * credits stopped: its status call succeeded, so there is no HTTP error to cite,
  * only `url` (the crawl).
  */
-export function quotaExhausted(url, claimUrl, opts = {}) {
-    // Say that the allowance comes back. Without it this reads as a permanent paywall,
-    // which is how the API's own AUTH004 text reads ("Purchase a new subscription to
-    // continue") and why exhausted clients retry-loop instead of waiting or upgrading —
-    // one account spent seven days at ~3 req/s against this wall. `zenrows usage` prints
-    // the exact `period_ends_at`, so the date is one command away rather than guessed here.
-    const renewLine = "Credits renew at the end of the billing period — run `zenrows usage` for the date.";
-    const claimLine = claimUrl
-        ? `You are on the Zenrows Free plan. Claim your account to keep your usage and add credits: ${claimUrl}. ${renewLine}`
-        : `You are out of Zenrows credits. ${renewLine} To carry on now, add a credit pack (${BILLING_TOPUP_URL} opens the purchase directly) or upgrade your plan: ${PLANS_URL}`;
+export function quotaExhausted(url, claim, opts = {}) {
     const detail = opts.detail ? `${opts.detail.replace(/\.\s*$/, "")}. ` : "";
     const where = opts.status === null ? `Stopped ${url}` : `HTTP ${opts.status ?? 429} for ${url}`;
     return new ToolkitError({
         code: "POLICY_MAX_CREDITS_EXCEEDED",
         message: "Zenrows request quota exhausted.",
         likely_cause: `${detail}${where}`,
-        next_action: claimLine,
+        next_action: quotaNextAction(claim),
         suggested_commands: ["zenrows usage"],
     });
 }
+export const CLAIM_LINK_REFRESH = Symbol("claim-link-refresh");
+/** Start of `next_action` on a quota error for an unclaimed account. */
+export const CLAIM_NEXT_ACTION_PREFIX = "You are on the Zenrows Free plan.";
+/** The `next_action` of a quota error for the given claim state. */
+export function quotaNextAction(claim) {
+    // Say that the allowance comes back. Without it this reads as a permanent paywall,
+    // which is how the API's own AUTH004 text reads ("Purchase a new subscription to
+    // continue") and why exhausted clients retry-loop instead of waiting or upgrading.
+    // `zenrows usage` prints the exact `period_ends_at`, so the date is one command away
+    // rather than guessed here.
+    const renewLine = "Credits renew at the end of the billing period — run `zenrows usage` for the date.";
+    if (claim === CLAIM_LINK_REFRESH) {
+        return `${CLAIM_NEXT_ACTION_PREFIX} Claim your account to keep your usage and add credits: run \`zenrows account claim\` for a fresh claim link. ${renewLine}`;
+    }
+    if (claim) {
+        return `${CLAIM_NEXT_ACTION_PREFIX} Claim your account to keep your usage and add credits: ${claim}. ${renewLine}`;
+    }
+    return `You are out of Zenrows credits. ${renewLine} To carry on now, add a credit pack (${BILLING_TOPUP_URL} opens the purchase directly) or upgrade your plan: ${PLANS_URL}`;
+}
 /** Where an account manages its API keys and their credit caps. */
 export const API_KEYS_SETTINGS_URL = "https://app.zenrows.com/settings/api-keys";
 /**

package/dist/src/core/http.js

@@ -6,6 +6,7 @@
  * from any logged URL.
  */
 import { ToolkitError, isKeyCapReached, keyCapReached, quotaExhausted } from "./errors.js";
+import { storedClaimHint, usableClaimUrl } from "./claim-link.js";
 import { readAccount } from "./agent-account.js";
 import { ENV_KEY, resolveApiKey } from "./auth.js";
 import { registerSecret } from "./logger.js";
@@ -143,7 +144,7 @@ export async function scrape(apiBase, apiKey, params, opts = {}) {
                     message: "The auto-provisioned Free plan key was rejected by the Zenrows API.",
                     likely_cause: `${cause}. The signup endpoint issued this key, but the scraping API did not accept it.`,
                     next_action: "If you are testing against a local/staging backend, ensure `apiBase` (zenrows config) points at the same environment that issued the key. Otherwise re-provision with `zenrows signup --agent`, or claim the account: " +
-                        acct.claimUrl,
+                        (usableClaimUrl(acct) ?? "run `zenrows account claim` for a link"),
                     suggested_commands: ["zenrows status", "zenrows signup --agent"],
                 });
             }
@@ -184,7 +185,7 @@ export async function scrape(apiBase, apiKey, params, opts = {}) {
         // out of credits. This is NOT scraped content — surface it as a credits
         // error (claim link for an unclaimed Free plan, dashboard/upgrade otherwise).
         const acct = readAccount();
-        throw quotaExhausted(redacted, acct?.unclaimed ? acct.claimUrl : undefined, {
+        throw quotaExhausted(redacted, storedClaimHint(acct), {
             status: 402,
             detail: zrErrorDetail(body) ?? undefined,
         });
@@ -196,7 +197,7 @@ export async function scrape(apiBase, apiKey, params, opts = {}) {
         // limit; otherwise advise a brief retry.
         if (isQuotaError(body)) {
             const acct = readAccount();
-            throw quotaExhausted(redacted, acct?.unclaimed ? acct.claimUrl : undefined);
+            throw quotaExhausted(redacted, storedClaimHint(acct));
         }
         const detail = zrErrorDetail(body) ?? snippet(body);
         throw new ToolkitError({

package/dist/src/core/nudge.js

@@ -1,5 +1,6 @@
 import { readAccount, writeAccount } from "./agent-account.js";
 import { resolveApiKey } from "./auth.js";
+import { usableClaimUrl } from "./claim-link.js";
 import { log } from "./logger.js";
 import { fetchUsage } from "./usage.js";
 /** How high usage must be (percent) before we nudge. */
@@ -15,7 +16,8 @@ export function nudgeMessage(account, usagePercent, _now) {
     if (!account.unclaimed)
         return null;
     if (typeof usagePercent === "number" && usagePercent >= USAGE_NUDGE_PERCENT) {
-        return `You've used ${usagePercent}% of your Zenrows Free plan — claim your account to keep your usage & history: ${account.claimUrl}`;
+        const link = usableClaimUrl(account, _now) ?? "run `zenrows account claim` for a claim link";
+        return `You've used ${usagePercent}% of your Zenrows Free plan — claim your account to keep your usage & history: ${link}`;
     }
     return null;
 }

package/dist/src/core/policy.js

@@ -1,9 +1,16 @@
 import { ToolkitError } from "./errors.js";
 import { findWorkspace, readJson, workspacePaths, writeJson } from "./workspace.js";
+/**
+ * Safe defaults. The per-run caps let a default run submit up to 10,000 URLs
+ * in any mode: an Adaptive Stealth Mode task is estimated at its 25-credit
+ * upper bound, so 10,000 of them estimate at 250,000 credits. Larger runs
+ * (the Batch API takes up to 100,000 tasks per job) need the caps raised
+ * explicitly with `zenrows policy set`.
+ */
 export function defaultPolicy() {
     return {
-        max_credits_per_run: 10000,
-        max_pages_per_run: 1000,
+        max_credits_per_run: 250_000,
+        max_pages_per_run: 10_000,
         max_concurrency: 20,
         allow_browser: true,
         allow_experimental: false,
@@ -94,8 +101,8 @@ export function assertWithinLimits(requested, policy, context = "run") {
             code: "POLICY_LIMIT_EXCEEDED",
             message: `This ${context} submits ${requested.pages} page(s), over the policy cap of ${policy.max_pages_per_run}.`,
             likely_cause: "policy.max_pages_per_run bounds how many URLs a single run may submit.",
-            next_action: `Split the job into runs of ≤${policy.max_pages_per_run} page(s), or raise max_pages_per_run in policy.json.`,
-            suggested_commands: ["zenrows policy show"],
+            next_action: `Split the job into runs of at most ${policy.max_pages_per_run} page(s), or raise the cap: \`zenrows policy set max_pages_per_run ${requested.pages}\` (default ${defaultPolicy().max_pages_per_run}).`,
+            suggested_commands: [`zenrows policy set max_pages_per_run ${requested.pages}`, "zenrows policy show"],
         });
     }
     if (requested.credits !== undefined && requested.credits > policy.max_credits_per_run) {
@@ -103,8 +110,8 @@ export function assertWithinLimits(requested, policy, context = "run") {
             code: "POLICY_LIMIT_EXCEEDED",
             message: `This ${context} is estimated at ${requested.credits} credit(s), over the policy cap of ${policy.max_credits_per_run}.`,
             likely_cause: "policy.max_credits_per_run bounds the estimated credit cost of a single run.",
-            next_action: "Reduce the job size or per-task cost (e.g. drop premium_proxy/js_render), or raise max_credits_per_run in policy.json.",
-            suggested_commands: ["zenrows policy show"],
+            next_action: `Reduce the job size or per-task cost (e.g. drop premium_proxy/js_render), or raise the cap: \`zenrows policy set max_credits_per_run ${requested.credits}\` (default ${defaultPolicy().max_credits_per_run}). The estimate is an upper bound: an Adaptive Stealth Mode task counts 25 credits, and is billed 1 to 25.`,
+            suggested_commands: [`zenrows policy set max_credits_per_run ${requested.credits}`, "zenrows policy show"],
         });
     }
 }

package/dist/src/core/provenance.js

@@ -10,17 +10,25 @@
 function hasPrefix(env, prefix) {
     return Object.keys(env).some((k) => k.startsWith(prefix));
 }
+/**
+ * Variables the agent itself sets in the shells it runs commands in, so they
+ * mean the agent is driving this command (the same signals as agent-client.ts).
+ * Variables that only show the agent is installed or configured (CODEX_HOME,
+ * ANTHROPIC_API_KEY, OPENAI_API_KEY, other CLAUDE_* settings) are not used.
+ */
+const CLAUDE_VARS = ["CLAUDECODE", "CLAUDE_CODE_ENTRYPOINT", "CLAUDE_CODE_CHILD_SESSION"];
+const CODEX_VARS = ["CODEX_SANDBOX", "CODEX_SANDBOX_NETWORK_DISABLED", "CODEX_THREAD_ID"];
 /** Detect the host agent brand + runtime, best-effort, from env vars. */
 export function detectClient(env = process.env) {
     const term = env.TERM_PROGRAM;
     let client = "unknown";
-    if (env.CLAUDECODE || hasPrefix(env, "CLAUDE_CODE") || hasPrefix(env, "CLAUDE_")) {
+    if (CLAUDE_VARS.some((v) => env[v])) {
         client = "claude-code";
     }
     else if (env.CURSOR_TRACE_ID || hasPrefix(env, "CURSOR_") || term === "cursor") {
         client = "cursor";
     }
-    else if (hasPrefix(env, "OPENAI_") || hasPrefix(env, "CODEX_")) {
+    else if (CODEX_VARS.some((v) => env[v])) {
         client = "openai-codex";
     }
     else if (hasPrefix(env, "WINDSURF")) {

package/dist/src/core/usage.js

@@ -7,6 +7,7 @@
  * safe to poll. The API key is registered as a secret so it is redacted in logs.
  */
 import { ToolkitError, quotaExhausted } from "./errors.js";
+import { storedClaimHint } from "./claim-link.js";
 import { isQuotaError, zrErrorDetail } from "./http.js";
 import { readAccount } from "./agent-account.js";
 import { ENV_KEY, resolveApiKey } from "./auth.js";
@@ -63,7 +64,7 @@ export async function fetchUsage(apiBase, apiKey, opts = {}) {
         // scraper 402. Surface it as a credits error (claim link for an unclaimed
         // Free plan account, dashboard/upgrade otherwise) instead of a generic "retry".
         const acct = readAccount();
-        throw quotaExhausted(url, acct?.unclaimed ? acct.claimUrl : undefined, {
+        throw quotaExhausted(url, storedClaimHint(acct), {
             status: res.status,
             detail: zrErrorDetail(body) ?? undefined,
         });

package/dist/src/core/workspace.js

@@ -5,7 +5,7 @@
  * assets, traces, and logs. Secrets live in `.zenrows/secrets.json`, which is
  * gitignored and never written into run artifacts.
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 export const WORKSPACE_DIRNAME = ".zenrows";
 /** Subdirectories created inside `.zenrows/`. */
@@ -96,3 +96,31 @@ export function writeJson(file, value) {
     mkdirSync(dirname(file), { recursive: true });
     writeFileSync(file, JSON.stringify(value, null, 2) + "\n");
 }
+/**
+ * Write a file only its owner may read (secrets, account metadata). The data
+ * goes to a temp file created 0600 and is renamed into place, so the target is
+ * never readable by others, not even for a moment, and a reader never sees a
+ * half-written file. A directory this creates is 0700.
+ */
+export function writePrivateJson(file, value) {
+    mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+    const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        writeFileSync(tmp, JSON.stringify(value, null, 2) + "\n", { mode: 0o600, flag: "wx" });
+        try {
+            chmodSync(tmp, 0o600); // the umask can only remove bits, but be explicit
+        }
+        catch {
+            // best-effort on platforms without POSIX permissions
+        }
+        renameSync(tmp, file);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+        }
+        throw err;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zenrows/cli",
-  "version": "1.6.2",
+  "version": "1.8.0",
   "description": "Open-source CLI, MCP, skills, templates, workflows, recipes, and evals layer for giving AI agents reliable access to protected web data through Zenrows cloud infrastructure.",
   "type": "module",
   "license": "MIT",

package/recipes/batch-estimate/RECIPE.md

@@ -23,11 +23,14 @@ zenrows batch estimate jobs.jsonl
 ```
 
 Swap `jobs.jsonl` for your own spec. Per-line keys (`js_render`,
-`premium_proxy`, `proxy_country`, `mode`, `autoparse`, `external_id`) tune each
-URL; cost multipliers are basic 1x / JS 5x / proxy 10x / both 25x.
+`premium_proxy`, `proxy_country`, `mode`, `autoparse`, `external_id`,
+`metadata`, `method`, `body`) tune each URL; cost multipliers are basic 1x / JS
+5x / proxy 10x / both 25x, and Adaptive Stealth Mode costs 1x to 25x. Pass
+`create`'s job-level flags (`--premium-proxy`, `--js-render`, `--manual`) to
+`estimate` to price the same request.
 
 Once the spec is clean, submit it:
 ```
-zenrows batch create jobs.jsonl --wait
+zenrows batch create jobs.jsonl --follow
 ```
 See [[batch-jobs]] for the full cloud flow.