@zenrows/mcp 2.1.2 → 2.2.2

package/README.md

@@ -41,7 +41,7 @@ https://mcp.zenrows.com/mcp
 
 **Transport:** Streamable HTTP
 
-**Authentication:** OAuth-based. Pass your Zenrows API key as a Bearer token in the `Authorization` header on every request.
+**Authentication:** OAuth or API key as Bearer token. Pass your Zenrows API key in the `Authorization` header on every request (or complete OAuth in clients that support it).
 
 ```
 Authorization: Bearer YOUR_ZENROWS_API_KEY
@@ -49,6 +49,8 @@ Authorization: Bearer YOUR_ZENROWS_API_KEY
 
 Most MCP clients accept this through an `authorization` shorthand field on the tool config and forward it as the Bearer token automatically. Some clients use a free-form `headers` field instead. Either approach works.
 
+> Remote MCP does **not** auto-create accounts. Use OAuth “Create Free account” in the client, or pass an existing API key.
+
 #### Example: OpenAI Responses API
 
 ```python
@@ -84,11 +86,15 @@ Use the local stdio configuration when your MCP client runs the server as a loca
 
 **Package:** [`@zenrows/mcp`](https://www.npmjs.com/package/@zenrows/mcp) on npm
 
-**Authentication:** API key via the `ZENROWS_API_KEY` environment variable.
+**Authentication:**
+
+1. `ZENROWS_API_KEY` environment variable, or
+2. Key previously stored in `~/.zenrows/secrets.json`, or
+3. **Auto-signup** (default): if neither is set, stdio provisions a Free plan account via `POST /api/agent/signup`, persists the key + claim metadata under `~/.zenrows/` (`secrets.json` + `account.json`, mode `0600`), and prints a claim URL on stderr. Opt out with `ZENROWS_AUTO_SIGNUP=false`.
 
 **Requirements:** [Node.js](https://nodejs.org/) installed (for `npx` to work).
 
-**Configuration:**
+**Configuration (with your own key):**
 
 ```json
 {
@@ -104,16 +110,33 @@ Use the local stdio configuration when your MCP client runs the server as a loca
 }
 ```
 
+**Zero-config (auto-signup):**
+
+```json
+{
+  "mcpServers": {
+    "zenrows": {
+      "command": "npx",
+      "args": ["-y", "@zenrows/mcp"]
+    }
+  }
+}
+```
+
 The exact location of this config varies by client. See the [per-client setup guides](https://docs.zenrows.com/mcp/overview#per-client-setup-guides) for the file path for your client.
 
 ---
 
 ## Tools
 
-The Zenrows MCP exposes two families of tools:
+The Zenrows MCP exposes these tool families:
 
-- **`scrape`**: single-request fetch returning Markdown, plain text, HTML, JSON, PDF, or screenshot. Backed by [Fetch](https://docs.zenrows.com/fetch/api-reference).
-- **`browser_*`**: 30+ tools for full browser automation including navigation, clicks, form fills, JavaScript execution, cookies, tabs, and persistent sessions. Backed by [Browser Sessions](https://docs.zenrows.com/browser-sessions/introduction).
+| Tool | Purpose |
+|------|---------|
+| **`scrape`** | Full-page content → Markdown, plain text, HTML, PDF, or screenshot (plus helper outputs). |
+| **`extract`** | Structured JSON (`extract=auto`, autoparse, or `css_extractor`) + optional stealth flags. `extract=auto` is open beta (currently free; billing may apply later). |
+| **`batch_create` / `batch_status` / `batch_results` / `batch_cancel` / `batch_wait`** | Cloud Batch API fan-out (`async.api.zenrows.com`). Beta; may return `BATCH_ACCESS_DENIED`. Not `browser_batch`. |
+| **`browser_*`** | 30+ tools for full browser automation (navigation, clicks, forms, JS, cookies, tabs, sessions). |
 
 The AI selects the right tool from your prompt. You don't call tools directly in code.
 
@@ -127,7 +150,7 @@ See the [full tool reference](https://docs.zenrows.com/mcp/overview#tools) for e
 git clone https://github.com/ZenRows/zenrows-mcp
 cd zenrows-mcp
 npm install
-cp .env.example .env   # Add your API key
+cp .env.example .env   # Optional: add your API key (stdio can auto-signup)
 npm run dev            # Run with .env loaded (requires Node.js 20.6+)
 npm run build          # Compile to dist/
 npm run inspect        # Open the MCP inspector UI

package/dist/auth/claim-hint.d.ts

@@ -0,0 +1,16 @@
+export declare function isQuotaOrPlanError(opts?: {
+    status?: number;
+    body?: string;
+    code?: string;
+    message?: string;
+}): boolean;
+/**
+ * If the local agent account is still unclaimed and this looks like a quota/plan
+ * failure, append the claim URL so agents can nudge the user.
+ */
+export declare function appendClaimHint(text: string, opts?: {
+    status?: number;
+    body?: string;
+    code?: string;
+    message?: string;
+}): string;

package/dist/auth/claim-hint.js

@@ -0,0 +1,71 @@
+/**
+ * Append a claim-account nudge when an unclaimed Free agent hits quota/plan limits.
+ */
+import { readAccount } from "./ensure-key.js";
+const CLAIM_NUDGE = "Claim your Free account to keep usage and upgrade: ";
+/**
+ * Codes that are not an allowance problem, so a claim nudge would be noise.
+ *
+ * AUTH006 is the concurrency limit, and is belt-and-braces: it comes back as 429, so it
+ * would not reach the 402 branch below in the first place. It is listed to keep the
+ * intent legible rather than because anything depends on it.
+ *
+ * AUTH004 used to be listed here on the belief that it
+ * was concurrency too — it is not. AUTH004 is "Usage Exceeded": the allowance itself is
+ * spent (docs `api-error-codes#AUTH004`; gateway logs carry `err: "usage exceeded"`,
+ * `msg: "user allowance failure"`). Skipping it suppressed the nudge at the one moment it
+ * is worth the most — an unclaimed Free agent that has just run through its allowance and
+ * would otherwise lose the account along with its usage history.
+ */
+const SKIP_CODES = new Set(["AUTH006"]);
+function extractCode(body, code) {
+    if (code && typeof code === "string")
+        return code;
+    if (!body)
+        return undefined;
+    try {
+        const j = JSON.parse(body);
+        if (typeof j.code === "string")
+            return j.code;
+        const m = typeof j.error === "string" ? j.error.match(/\((AUTH\d+)\)/) : null;
+        return m?.[1];
+    }
+    catch {
+        const m = body.match(/\b(AUTH\d+|BATCH_QUOTA_EXCEEDED)\b/);
+        return m?.[1];
+    }
+}
+export function isQuotaOrPlanError(opts = {}) {
+    const code = extractCode(opts.body, opts.code);
+    if (code && SKIP_CODES.has(code))
+        return false;
+    if (opts.status === 402)
+        return true;
+    if (code === "BATCH_QUOTA_EXCEEDED")
+        return true;
+    const hay = `${opts.message ?? ""} ${opts.body ?? ""} ${code ?? ""}`;
+    if (/\bHTTP\s*402\b/i.test(hay) || /\berror\s+402\b/i.test(hay))
+        return true;
+    return /\b(no credit|credits?\s+(exhausted|exceeded|available)|quota exceeded|subscription has no credit)\b/i.test(hay);
+}
+/**
+ * If the local agent account is still unclaimed and this looks like a quota/plan
+ * failure, append the claim URL so agents can nudge the user.
+ */
+export function appendClaimHint(text, opts = {}) {
+    const probe = {
+        status: opts.status,
+        body: opts.body ?? text,
+        code: opts.code,
+        message: opts.message ?? text,
+    };
+    if (!isQuotaOrPlanError(probe))
+        return text;
+    const acct = readAccount();
+    if (!acct?.unclaimed || !acct.claimUrl)
+        return text;
+    const hint = `${CLAIM_NUDGE}${acct.claimUrl}`;
+    if (text.includes(acct.claimUrl) || text.includes(CLAIM_NUDGE.trim()))
+        return text;
+    return `${text}\n\n${hint}`;
+}

package/dist/auth/ensure-key.d.ts

@@ -0,0 +1,59 @@
+export declare const ENV_KEY = "ZENROWS_API_KEY";
+export declare const AUTO_SIGNUP_ENV = "ZENROWS_AUTO_SIGNUP";
+export declare const SIGNUP_URL_ENV = "ZENROWS_AGENT_SIGNUP_URL";
+export declare const DISCOVERY_URL_ENV = "ZENROWS_DISCOVERY_URL";
+export declare const AGENT_SIGNUP_API_URL = "https://app.zenrows.com/api/agent/signup";
+export declare const WELL_KNOWN_PROTECTED_RESOURCE = "/.well-known/oauth-protected-resource";
+export interface AgentAccount {
+    accountId: string;
+    unclaimed: boolean;
+    claimUrl: string;
+    createdAt: string;
+}
+export interface SignupResponse {
+    apiKey: string;
+    accountId: string;
+    claimUrl: string;
+}
+export declare class AuthError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}
+/** Override home for tests / custom installs (absolute path to the `.zenrows` dir parent, or the dir itself if it ends with `.zenrows`). */
+export declare const ZENROWS_HOME_ENV = "ZENROWS_HOME";
+/** Test-only: clear discovery cache between cases. */
+export declare function _resetDiscoveryCache(): void;
+export declare function getZenrowsDir(): string;
+export declare function readStoredApiKey(): string | undefined;
+export declare function readAccount(): AgentAccount | null;
+export declare function saveApiKey(apiKey: string): void;
+export declare function writeAccount(acct: AgentAccount): void;
+/** Resolve key: env → ~/.zenrows/secrets.json. Does not signup. */
+export declare function resolveApiKey(): {
+    key?: string;
+    source: "env" | "secrets-file" | "none";
+};
+export declare function autoSignupEnabled(): boolean;
+export declare function discoverSignupUrl(opts?: {
+    fetchImpl?: typeof fetch;
+}): Promise<string | null>;
+export declare function signupCandidates(opts?: {
+    fetchImpl?: typeof fetch;
+}): Promise<string[]>;
+export declare function signupAgent(opts?: {
+    url?: string;
+    fetchImpl?: typeof fetch;
+    userAgent?: string;
+}): Promise<SignupResponse>;
+/**
+ * Ensure an API key is available for stdio.
+ * Returns the key and optional claim metadata when a new account was provisioned.
+ */
+export declare function ensureApiKey(opts?: {
+    fetchImpl?: typeof fetch;
+    userAgent?: string;
+    onProvision?: (a: AgentAccount) => void;
+}): Promise<{
+    apiKey: string;
+    provisioned?: AgentAccount;
+}>;

package/dist/auth/ensure-key.js

@@ -0,0 +1,184 @@
+/**
+ * Resolve-or-provision the Zenrows API key for stdio MCP.
+ *
+ * Persistence lives under ~/.zenrows/ (secrets.json + account.json, mode 0600).
+ * Remote HTTP transport must NOT call this — Bearer/OAuth only.
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export const ENV_KEY = "ZENROWS_API_KEY";
+export const AUTO_SIGNUP_ENV = "ZENROWS_AUTO_SIGNUP";
+export const SIGNUP_URL_ENV = "ZENROWS_AGENT_SIGNUP_URL";
+export const DISCOVERY_URL_ENV = "ZENROWS_DISCOVERY_URL";
+export const AGENT_SIGNUP_API_URL = "https://app.zenrows.com/api/agent/signup";
+export const WELL_KNOWN_PROTECTED_RESOURCE = "/.well-known/oauth-protected-resource";
+export class AuthError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "AuthError";
+        this.code = code;
+    }
+}
+/** Override home for tests / custom installs (absolute path to the `.zenrows` dir parent, or the dir itself if it ends with `.zenrows`). */
+export const ZENROWS_HOME_ENV = "ZENROWS_HOME";
+function zenrowsDir() {
+    const override = process.env[ZENROWS_HOME_ENV]?.trim();
+    if (override) {
+        return override.endsWith(".zenrows") ? override : join(override, ".zenrows");
+    }
+    return join(homedir(), ".zenrows");
+}
+/** Test-only: clear discovery cache between cases. */
+export function _resetDiscoveryCache() {
+    discoveredSignupUrl = undefined;
+}
+export function getZenrowsDir() {
+    return zenrowsDir();
+}
+function secretsPath() {
+    return join(zenrowsDir(), "secrets.json");
+}
+function accountPath() {
+    return join(zenrowsDir(), "account.json");
+}
+function ensureDir() {
+    const dir = zenrowsDir();
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+function readJsonFile(file) {
+    if (!existsSync(file))
+        return null;
+    try {
+        return JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function writeJsonSecure(file, data) {
+    ensureDir();
+    writeFileSync(file, JSON.stringify(data, null, 2) + "\n", { mode: 0o600 });
+    try {
+        chmodSync(file, 0o600);
+    }
+    catch {
+        // best-effort on platforms without POSIX permissions
+    }
+}
+export function readStoredApiKey() {
+    const stored = readJsonFile(secretsPath());
+    const key = stored?.apiKey?.trim();
+    return key || undefined;
+}
+export function readAccount() {
+    return readJsonFile(accountPath());
+}
+export function saveApiKey(apiKey) {
+    writeJsonSecure(secretsPath(), { apiKey: apiKey.trim() });
+}
+export function writeAccount(acct) {
+    writeJsonSecure(accountPath(), acct);
+}
+/** Resolve key: env → ~/.zenrows/secrets.json. Does not signup. */
+export function resolveApiKey() {
+    const env = process.env[ENV_KEY]?.trim();
+    if (env)
+        return { key: env, source: "env" };
+    const stored = readStoredApiKey();
+    if (stored)
+        return { key: stored, source: "secrets-file" };
+    return { source: "none" };
+}
+export function autoSignupEnabled() {
+    return process.env[AUTO_SIGNUP_ENV] !== "false";
+}
+let discoveredSignupUrl;
+export async function discoverSignupUrl(opts = {}) {
+    try {
+        const base = process.env[DISCOVERY_URL_ENV]?.trim() || new URL(AGENT_SIGNUP_API_URL).origin;
+        const url = base.replace(/\/$/, "") + WELL_KNOWN_PROTECTED_RESOURCE;
+        const doFetch = opts.fetchImpl ?? fetch;
+        const res = await doFetch(url, {
+            method: "GET",
+            headers: { Accept: "application/json", "User-Agent": "zenrows/mcp" },
+        });
+        if (!res.ok)
+            return null;
+        const json = (await res.json());
+        const endpoint = json?.agent_auth?.signup_endpoint;
+        if (typeof endpoint === "string" && endpoint.trim())
+            return endpoint.trim();
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function signupCandidates(opts = {}) {
+    const fromEnv = process.env[SIGNUP_URL_ENV];
+    if (fromEnv && fromEnv.trim())
+        return [fromEnv.trim()];
+    if (discoveredSignupUrl === undefined) {
+        discoveredSignupUrl = await discoverSignupUrl(opts);
+    }
+    const urls = [];
+    if (discoveredSignupUrl && discoveredSignupUrl !== AGENT_SIGNUP_API_URL) {
+        urls.push(discoveredSignupUrl);
+    }
+    urls.push(AGENT_SIGNUP_API_URL);
+    return urls;
+}
+export async function signupAgent(opts = {}) {
+    const urls = opts.url ? [opts.url] : await signupCandidates({ fetchImpl: opts.fetchImpl });
+    const doFetch = opts.fetchImpl ?? fetch;
+    const headers = {
+        "content-type": "application/json",
+        "User-Agent": opts.userAgent ?? "zenrows/mcp",
+        "X-ZR-Source": "mcp",
+    };
+    let lastMessage = "No signup endpoint was reachable.";
+    for (const url of urls) {
+        let res;
+        try {
+            res = await doFetch(url, { method: "POST", headers });
+        }
+        catch (err) {
+            lastMessage = err instanceof Error ? err.message : String(err);
+            continue;
+        }
+        if (res.status === 201)
+            return (await res.json());
+        const body = await res.text();
+        if (res.status === 429) {
+            throw new AuthError("SIGNUP_RATE_LIMITED", "Zenrows blocked auto-signup: too many new accounts from this network. Wait and retry, or set ZENROWS_API_KEY.");
+        }
+        lastMessage = `HTTP ${res.status}: ${body.slice(0, 240)}`;
+    }
+    throw new AuthError("SIGNUP_FAILED", `Automatic account provisioning failed. ${lastMessage}`);
+}
+/**
+ * Ensure an API key is available for stdio.
+ * Returns the key and optional claim metadata when a new account was provisioned.
+ */
+export async function ensureApiKey(opts = {}) {
+    const existing = resolveApiKey();
+    if (existing.key)
+        return { apiKey: existing.key };
+    if (!autoSignupEnabled()) {
+        throw new AuthError("AUTH_MISSING", "ZENROWS_API_KEY is required (auto-signup disabled via ZENROWS_AUTO_SIGNUP=false).");
+    }
+    const res = await signupAgent({ fetchImpl: opts.fetchImpl, userAgent: opts.userAgent });
+    saveApiKey(res.apiKey);
+    const account = {
+        accountId: res.accountId,
+        unclaimed: true,
+        claimUrl: res.claimUrl,
+        createdAt: new Date().toISOString(),
+    };
+    writeAccount(account);
+    opts.onProvision?.(account);
+    return { apiKey: res.apiKey, provisioned: account };
+}

package/dist/batch-api.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Client for the Zenrows Batch API (https://async.api.zenrows.com/v1).
+ * Auth via X-API-Key header. Errors are application/problem+json (RFC 7807).
+ */
+export declare const DEFAULT_BATCH_API_BASE = "https://async.api.zenrows.com/v1";
+export declare const BATCH_API_BASE_ENV = "ZENROWS_BATCH_API_BASE";
+export declare function batchBase(): string;
+export interface JobStats {
+    total: number;
+    completed: number;
+    successful: number;
+    failed: number;
+}
+export interface JobRun {
+    status: string;
+    stats: JobStats;
+    run_id?: string;
+    [k: string]: unknown;
+}
+export interface Job {
+    job_id: string;
+    latest_run: JobRun;
+    [k: string]: unknown;
+}
+export interface ResultRow {
+    external_id?: string;
+    task_id: string;
+    status?: string;
+    result_url?: string;
+    [k: string]: unknown;
+}
+export interface ResultsPage {
+    results: ResultRow[];
+    next_cursor: string | null;
+}
+export interface ProblemJson {
+    type?: string;
+    title?: string;
+    status?: number;
+    detail?: string;
+    code?: string;
+    invalid_tasks?: Array<{
+        index: number;
+        reason: string;
+    }>;
+}
+export declare const TERMINAL_STATUSES: ReadonlySet<string>;
+export declare class BatchError extends Error {
+    code: string;
+    status?: number;
+    detail?: string;
+    constructor(opts: {
+        code: string;
+        message: string;
+        status?: number;
+        detail?: string;
+    });
+    toJSON(): {
+        code: string;
+        message: string;
+        status?: number;
+        detail?: string;
+    };
+}
+interface RequestOpts {
+    apiKey: string;
+    body?: unknown;
+    query?: Record<string, string | undefined>;
+    timeoutMs?: number;
+    userAgent?: string;
+    fetchImpl?: typeof fetch;
+}
+export declare function batchRequest<T>(method: string, path: string, opts: RequestOpts): Promise<T>;
+interface CallOpts {
+    apiKey: string;
+    timeoutMs?: number;
+    userAgent?: string;
+    fetchImpl?: typeof fetch;
+}
+export declare function createJob(body: unknown, opts: CallOpts): Promise<Job>;
+export declare function getJob(id: string, opts: CallOpts): Promise<Job>;
+export declare function stopJob(id: string, opts: CallOpts): Promise<Job>;
+export declare function listResults(id: string, opts: CallOpts & {
+    status?: "successful" | "failed" | "all";
+}): Promise<ResultRow[]>;
+export declare function waitForJob(id: string, opts: CallOpts & {
+    pollTimeoutMs?: number;
+}): Promise<Job>;
+export {};

package/dist/batch-api.js

@@ -0,0 +1,182 @@
+/**
+ * Client for the Zenrows Batch API (https://async.api.zenrows.com/v1).
+ * Auth via X-API-Key header. Errors are application/problem+json (RFC 7807).
+ */
+export const DEFAULT_BATCH_API_BASE = "https://async.api.zenrows.com/v1";
+export const BATCH_API_BASE_ENV = "ZENROWS_BATCH_API_BASE";
+export function batchBase() {
+    const env = process.env[BATCH_API_BASE_ENV];
+    const base = env && env.trim() ? env.trim() : DEFAULT_BATCH_API_BASE;
+    return base.replace(/\/+$/, "");
+}
+export const TERMINAL_STATUSES = new Set(["completed", "stopped", "deleted"]);
+export class BatchError extends Error {
+    code;
+    status;
+    detail;
+    constructor(opts) {
+        super(opts.message);
+        this.name = "BatchError";
+        this.code = opts.code;
+        this.status = opts.status;
+        this.detail = opts.detail;
+    }
+    toJSON() {
+        return { code: this.code, message: this.message, status: this.status, detail: this.detail };
+    }
+}
+export async function batchRequest(method, path, opts) {
+    const url = new URL(batchBase() + path);
+    for (const [k, v] of Object.entries(opts.query ?? {})) {
+        if (v !== undefined && v !== null)
+            url.searchParams.set(k, v);
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), opts.timeoutMs ?? 60_000);
+    const headers = {
+        "X-API-Key": opts.apiKey,
+        Accept: "application/json",
+        "User-Agent": opts.userAgent ?? "zenrows/mcp",
+    };
+    if (opts.body !== undefined)
+        headers["Content-Type"] = "application/json";
+    const doFetch = opts.fetchImpl ?? fetch;
+    let res;
+    try {
+        res = await doFetch(url.toString(), {
+            method,
+            headers,
+            body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        clearTimeout(timeout);
+        throw new BatchError({
+            code: "BACKEND_UNAVAILABLE",
+            message: `Could not reach the Zenrows Batch API: ${err instanceof Error ? err.message : String(err)}`,
+        });
+    }
+    clearTimeout(timeout);
+    const text = await res.text();
+    if (res.status < 200 || res.status >= 300) {
+        throw problemToError(res.status, text, method, path);
+    }
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new BatchError({
+            code: "BATCH_FAILED",
+            message: "The Batch API response was not valid JSON.",
+            detail: text.slice(0, 240),
+        });
+    }
+}
+function problemToError(status, body, method, path) {
+    let problem = {};
+    try {
+        problem = JSON.parse(body);
+    }
+    catch {
+        // non-JSON — fall through
+    }
+    const serverCode = problem.code ?? "";
+    const detail = problem.detail || problem.title || body.slice(0, 240) || `HTTP ${status}`;
+    const cause = `HTTP ${status}${serverCode ? ` (${serverCode})` : ""} for ${method} ${path}: ${detail}`;
+    if (status === 403) {
+        return new BatchError({
+            code: "BATCH_ACCESS_DENIED",
+            message: "The Batch API rejected this request (access denied). The Batch API is in beta and this account does not have beta access. Request access from Zenrows, or fan out with scrape/extract per URL.",
+            status,
+            detail: cause,
+        });
+    }
+    if (status === 401) {
+        return new BatchError({
+            code: "AUTH_INVALID",
+            message: "Zenrows rejected the API key for the Batch API.",
+            status,
+            detail: cause,
+        });
+    }
+    if (status === 404) {
+        return new BatchError({
+            code: "BATCH_NOT_FOUND",
+            message: "Batch job, run, or task not found.",
+            status,
+            detail: cause,
+        });
+    }
+    if (status === 429) {
+        return new BatchError({
+            code: "BATCH_QUOTA_EXCEEDED",
+            message: "Batch quota exceeded (e.g. max concurrent active jobs). Wait for an in-flight job to finish or cancel one, then retry.",
+            status,
+            detail: cause,
+        });
+    }
+    if (status === 402) {
+        return new BatchError({
+            code: "BATCH_QUOTA_EXCEEDED",
+            message: "Subscription has no credit available for the Batch API.",
+            status,
+            detail: cause,
+        });
+    }
+    const invalid = problem.invalid_tasks?.length
+        ? ` invalid_tasks: ${problem.invalid_tasks
+            .slice(0, 10)
+            .map((t) => `#${t.index}: ${t.reason}`)
+            .join("; ")}`
+        : "";
+    return new BatchError({
+        code: "BATCH_FAILED",
+        message: `Batch request failed (HTTP ${status}).${invalid}`,
+        status,
+        detail: cause,
+    });
+}
+export function createJob(body, opts) {
+    return batchRequest("POST", "/jobs", { ...opts, body });
+}
+export function getJob(id, opts) {
+    return batchRequest("GET", `/jobs/${encodeURIComponent(id)}`, opts);
+}
+export function stopJob(id, opts) {
+    return batchRequest("POST", `/jobs/${encodeURIComponent(id)}/stop`, opts);
+}
+export async function listResults(id, opts) {
+    const all = [];
+    let cursor;
+    do {
+        const page = await batchRequest("GET", `/jobs/${encodeURIComponent(id)}/results`, {
+            ...opts,
+            query: { status: opts.status, cursor },
+        });
+        if (page?.results)
+            all.push(...page.results);
+        cursor = page?.next_cursor ?? undefined;
+    } while (cursor);
+    return all;
+}
+export async function waitForJob(id, opts) {
+    const deadline = Date.now() + (opts.pollTimeoutMs ?? opts.timeoutMs ?? 600_000);
+    let delay = 2000;
+    for (;;) {
+        const job = await getJob(id, opts);
+        if (job.latest_run && TERMINAL_STATUSES.has(job.latest_run.status))
+            return job;
+        if (Date.now() > deadline) {
+            throw new BatchError({
+                code: "BATCH_FAILED",
+                message: `Timed out waiting for batch job ${id} to finish.`,
+                detail: `The run did not reach a terminal state within ${Math.round((opts.pollTimeoutMs ?? opts.timeoutMs ?? 600_000) / 1000)}s.`,
+            });
+        }
+        await new Promise((r) => setTimeout(r, delay));
+        delay = Math.min(delay * 1.5, 15_000);
+    }
+}