zenrows 2.0.2 → 2.1.1

package/dist/index.d.ts

@@ -1,12 +1,776 @@
 import * as fetch_retry from 'fetch-retry';
 import fastq from 'fastq';
 
+/**
+ * A server-extensible string enum: the listed values autocomplete, but the server may
+ * return values not listed (the Batch API marks these `x-extensible-enum`). Response fields
+ * use `Extensible<...>`, so callers must handle an unknown value. The named types stay closed
+ * so they keep working as request input.
+ */
+type Extensible<T extends string> = T | (string & {});
+type JobType = "regular" | "scheduled";
+type JobStatus = "open" | "closed" | "deleted";
+type ScheduleState = "active" | "paused";
+type RunStatus = "pending" | "running" | "completed" | "failed" | "stopped" | "deleted";
+type TaskStatus = "pending" | "processing" | "successful" | "failed";
+type PauseState = "active" | "paused";
+type IngestStatus = "pending" | "done";
+type ExportStatus = "pending" | "running" | "completed" | "failed";
+/**
+ * Why a run auto-failed (`status == "failed"`).
+ * - `insufficient_credits` — the account is out of credits.
+ * - `subscription_inactive` — the subscription is not active.
+ * - `api_key_cap_reached` — the job's API key reached one of its credit caps; resolves when
+ *   that cap's window resets or the cap is raised. `Run.failure_detail` says which.
+ */
+type RunFailureReason = "insufficient_credits" | "subscription_inactive" | "api_key_cap_reached";
+interface Spend {
+    credits: number;
+    cost: number;
+}
+interface TaskSpend {
+    total: Spend;
+    last_attempt: Spend;
+}
+interface RunStats {
+    total: number;
+    completed: number;
+    successful: number;
+    failed: number;
+    failure_reasons?: Record<string, number>;
+    spend?: Spend;
+}
+interface WebhookConfig {
+    url: string;
+    signature: boolean;
+}
+interface JobSchedule {
+    at?: string;
+    rate?: {
+        every: number;
+        unit: "minute" | "hour" | "day";
+    };
+    calendar?: {
+        times_of_day: string[];
+        cadence: {
+            daily?: object;
+            weekly?: {
+                days: string[];
+            };
+            monthly?: {
+                days: number[];
+            };
+        };
+    };
+    timezone?: string;
+}
+interface Run {
+    run_id: string;
+    job_id: string;
+    run_sequence: number;
+    status: Extensible<RunStatus>;
+    stats: RunStats;
+    last_batch_received?: boolean;
+    pause_state?: PauseState;
+    ingest_status?: Extensible<IngestStatus>;
+    failure_reason?: Extensible<RunFailureReason>;
+    /** Human-readable explanation of `failure_reason` (e.g. which cap, and when it resets, UTC). */
+    failure_detail?: string | null;
+    created_at?: string;
+    updated_at?: string;
+}
+interface Job {
+    job_id: string;
+    type: JobType;
+    status: Extensible<JobStatus>;
+    format?: string;
+    zenrows_params?: Record<string, string>;
+    external_id?: string;
+    name?: string;
+    metadata?: Record<string, string>;
+    schedule?: JobSchedule;
+    next_scheduled_run?: string;
+    schedule_state?: ScheduleState;
+    webhook?: WebhookConfig;
+    latest_run?: Run;
+    created_at?: string;
+    updated_at?: string;
+}
+interface ListJobsResponse {
+    jobs: Job[];
+    next_cursor?: string;
+}
+interface ListJobRunsResponse {
+    runs: Run[];
+    next_cursor?: string;
+}
+interface SubmitJobResponse {
+    job_id: string;
+    status: Extensible<JobStatus>;
+    latest_run?: Run;
+    accepted_tasks: number;
+    webhook?: WebhookConfig;
+}
+interface AddTasksResponse {
+    accepted_tasks: number;
+    job_status: Extensible<JobStatus>;
+    latest_run: Run;
+}
+interface RerunJobResponse {
+    job_id: string;
+    status: Extensible<JobStatus>;
+    latest_run: Run;
+    rerun_of?: string;
+    retried_tasks: number;
+    inherited_tasks: number;
+}
+interface ProblemJson {
+    type?: string;
+    title?: string;
+    status?: number;
+    code?: string;
+    detail?: string;
+    instance?: string;
+}
+interface TaskResult {
+    task_id: string;
+    external_id?: string;
+    run_id: string;
+    url: string;
+    metadata?: Record<string, string>;
+    method?: "GET" | "POST";
+    status: Extensible<TaskStatus>;
+    type?: string;
+    result_url?: string;
+    error?: ProblemJson;
+    source_run_id?: string;
+    spend?: TaskSpend;
+}
+interface ListResultsResponse {
+    results: TaskResult[];
+    next_cursor?: string;
+}
+interface TaskHistoryEvent {
+    started_at: string;
+    ended_at: string;
+    attempt: number;
+    error?: ProblemJson;
+    spend?: Spend;
+}
+interface TaskHistoryResponse {
+    events: TaskHistoryEvent[];
+}
+interface StartExportResponse {
+    export_id: string;
+    status: Extensible<ExportStatus>;
+    created_at: string;
+    expires_at: string;
+}
+interface Export {
+    export_id: string;
+    status: Extensible<ExportStatus>;
+    error?: string;
+    download_url?: string;
+    created_at: string;
+    expires_at: string;
+}
+interface FileInputUploadTarget {
+    method: "PUT";
+    url: string;
+    headers?: Record<string, string>;
+    expires_at: string;
+}
+interface CreateJobInputResponse {
+    file_input_id: string;
+    upload: FileInputUploadTarget;
+    expires_at: string;
+}
+interface HMACKeyMeta {
+    kid: string;
+    created_at: string;
+}
+interface HMACKeyList {
+    active?: HMACKeyMeta;
+    candidate?: HMACKeyMeta;
+}
+interface HMACKeyCreated {
+    kid: string;
+    secret: string;
+    created_at: string;
+}
+interface HMACKeyFinalized {
+    active_kid: string;
+    created_at: string;
+}
+interface TestWebhookResponse {
+    delivered: boolean;
+    event_id: string;
+    status_code?: number;
+    error?: string;
+    elapsed_ms: number;
+}
+
+declare const DEFAULT_MAX_FILES = 100000;
+declare const DEFAULT_MAX_BYTES_PER_FILE: number;
+declare const DEFAULT_MAX_COUNT_IN_MEMORY = 10000;
+declare const DEFAULT_MAX_TOTAL_BYTES_IN_MEMORY: number;
+interface DownloadedResult {
+    taskId: string;
+    externalId?: string;
+    url: string;
+    body: Buffer;
+}
+interface DownloadToDirOptions {
+    status?: string;
+    nameFn?: (task: TaskResult) => string;
+    useExternalId?: boolean;
+    concurrency?: number;
+    maxFiles?: number;
+    maxBytesPerFile?: number;
+}
+/** Write every task body in `results` to `targetDir`, one file per task. */
+declare function downloadToDir(results: AsyncIterable<TaskResult>, targetDir: string, { nameFn, useExternalId, concurrency, maxFiles, maxBytesPerFile, }?: DownloadToDirOptions): Promise<number>;
+interface DownloadToMemoryOptions {
+    concurrency?: number;
+    maxCount?: number;
+    maxTotalBytes?: number;
+    maxBytesPerFile?: number;
+}
+/** Load every task body in `results` into memory. */
+declare function downloadToMemory(results: AsyncIterable<TaskResult>, { concurrency, maxCount, maxTotalBytes, maxBytesPerFile, }?: DownloadToMemoryOptions): Promise<DownloadedResult[]>;
+declare function downloadTaskToFile(task: TaskResult, target: string): Promise<void>;
+declare function downloadTaskToMemory(task: TaskResult): Promise<Buffer>;
+
+/**
+ * Client-side cost estimation, mirroring the Python SDK's rate card exactly. Pure — no
+ * network call. Prices a job assuming every task succeeds once; `mode=auto` is billed
+ * dynamically post-factum and is reported as a [1, 25] credit range, everything else is exact.
+ */
+declare const BASE_CREDITS = 1;
+declare const JS_CREDITS = 5;
+declare const PREMIUM_PROXY_CREDITS = 10;
+declare const JS_AND_PROXY_CREDITS = 25;
+declare const AUTO_MIN_CREDITS = 1;
+declare const AUTO_MAX_CREDITS = 25;
+type Tier = "base" | "js_render" | "premium_proxy" | "js_render+premium_proxy" | "auto";
+type ParamValue = string | boolean | number | Record<string, string>;
+type ParamMap = Record<string, ParamValue>;
+interface EstimateTask {
+    zenrows_params?: ParamMap;
+}
+type TaskLike = string | EstimateTask | Record<string, unknown>;
+interface CostLine {
+    tier: Tier;
+    count: number;
+    unitMin: number;
+    unitMax: number;
+}
+interface CostEstimate {
+    taskCount: number;
+    min: number;
+    max: number;
+    breakdown: CostLine[];
+    exact: boolean;
+}
+/**
+ * Estimate the credit cost of a job before submitting it. `tasks` accepts the same shapes
+ * `submitRegular` does: bare URL strings or task objects. Per-task `zenrows_params` override
+ * the job-level `zenrowsParams` on key collision (task wins), matching the worker's merge.
+ */
+declare function estimateCost(tasks: Iterable<TaskLike>, zenrowsParams?: ParamMap): CostEstimate;
+
+declare const DAYS_OF_WEEK: readonly ["mon", "tue", "wed", "thu", "fri", "sat", "sun"];
+type DayOfWeek = (typeof DAYS_OF_WEEK)[number];
+/**
+ * One-shot fire at a specific wall-clock time. `at` must be tz-naive: a plain ISO string
+ * with no `Z`/offset suffix, or a `Date` — in which case its LOCAL getters (not UTC) are
+ * read as the intended wall-clock time. `timezone` is the single authoritative interpreter,
+ * which is what keeps DST transitions deterministic; passing a `Date` does NOT mean "this
+ * instant" — it means "this wall-clock reading, in whatever zone `timezone` names."
+ */
+declare class At {
+    readonly at: string;
+    readonly timezone: string;
+    constructor(at: string | Date, timezone: string);
+    toRequestBody(): JobSchedule;
+}
+/** Interval-based fire policy — every N units, no alignment to wall clock. */
+declare class Rate {
+    readonly every: number;
+    readonly unit: "minute" | "hour" | "day";
+    constructor(every: number, unit: "minute" | "hour" | "day");
+    toRequestBody(): JobSchedule;
+}
+/** Fire every day. No knobs. */
+declare class Daily {
+}
+/** Fire on specific days of the week. `days` must be non-empty, lower-case 3-letter names. */
+declare class Weekly {
+    readonly days: DayOfWeek[];
+    constructor(days: DayOfWeek[]);
+}
+/** Fire on specific days of the month (1-31); days that don't exist in a given month are skipped. */
+declare class Monthly {
+    readonly days: number[];
+    constructor(days: number[]);
+}
+type Cadence = Daily | Weekly | Monthly;
+/** Calendar-style fire policy: a list of times-of-day on a daily/weekly/monthly cadence. */
+declare class Calendar {
+    readonly timesOfDay: string[];
+    readonly cadence: Cadence;
+    readonly timezone: string;
+    constructor(timesOfDay: string[], cadence: Cadence, timezone: string);
+    toRequestBody(): JobSchedule;
+}
+type Schedule = At | Rate | Calendar;
+
+interface BatchTaskLike {
+    url: string;
+    external_id?: string;
+    metadata?: Record<string, unknown>;
+    zenrows_params?: Record<string, unknown>;
+}
+/** A reference to a specific run by `(jobId, runId)`. No pause/stop — only the CURRENT run supports those. */
+declare class RunRef {
+    #private;
+    readonly jobId: string;
+    readonly runId: string;
+    constructor(client: ZenRowsBatchClient, jobId: string, runId: string);
+    load(): Promise<RunHandle>;
+    delete(): Promise<void>;
+    results(options?: {
+        status?: string;
+    }): AsyncGenerator<TaskResult>;
+    taskHistory(taskId: string): Promise<TaskHistoryResponse>;
+    downloadToDir(targetDir: string, options?: DownloadToDirOptions & {
+        status?: string;
+    }): Promise<number>;
+    downloadToMemory(options?: DownloadToMemoryOptions & {
+        status?: string;
+    }): Promise<DownloadedResult[]>;
+    downloadTaskToFile(task: TaskResult, target: string): Promise<void>;
+    downloadTaskToMemory(task: TaskResult): Promise<Buffer>;
+    wait(options?: {
+        targetStatuses?: Set<string>;
+        failureStatuses?: Set<string>;
+        timeout?: number;
+        pollInterval?: number;
+    }): Promise<RunHandle>;
+    startExport(): Promise<ExportRef>;
+    export(exportId: string): ExportRef;
+    downloadAllResults(targetPath: string, options?: {
+        waitTimeout?: number;
+        pollInterval?: number;
+    }): Promise<string>;
+}
+declare class RunHandle extends RunRef {
+    readonly data: Run;
+    constructor(client: ZenRowsBatchClient, jobId: string, runId: string, data: Run);
+    get status(): Extensible<RunStatus>;
+    get stats(): RunStats;
+}
+declare class ExportRef {
+    #private;
+    readonly jobId: string;
+    readonly runId: string;
+    readonly exportId: string;
+    readonly startResponse?: StartExportResponse | undefined;
+    constructor(client: ZenRowsBatchClient, jobId: string, runId: string, exportId: string, startResponse?: StartExportResponse | undefined);
+    load(): Promise<ExportHandle>;
+    wait(options?: {
+        targetStatuses?: Set<string>;
+        timeout?: number;
+        pollInterval?: number;
+    }): Promise<ExportHandle>;
+    /** Stream the export zip to `targetPath`. The export must already be `completed`. */
+    downloadToPath(targetPath: string): Promise<string>;
+}
+declare class ExportHandle extends ExportRef {
+    readonly data: Export;
+    constructor(client: ZenRowsBatchClient, jobId: string, runId: string, exportId: string, data: Export, startResponse?: StartExportResponse);
+    get status(): Extensible<ExportStatus>;
+}
+/** Operations on a job's CURRENT run, reached via `job.run`. */
+declare class CurrentRun {
+    #private;
+    readonly jobId: string;
+    constructor(client: ZenRowsBatchClient, jobId: string);
+    private currentRunId;
+    load(): Promise<RunHandle>;
+    pause(): Promise<RunHandle>;
+    resume(): Promise<RunHandle>;
+    stop(): Promise<RunHandle>;
+    cancel(): Promise<RunHandle>;
+    wait(options?: {
+        targetStatuses?: Set<string>;
+        failureStatuses?: Set<string>;
+        timeout?: number;
+        pollInterval?: number;
+    }): Promise<RunHandle>;
+    results(options?: {
+        status?: string;
+    }): AsyncGenerator<TaskResult>;
+    taskHistory(taskId: string): Promise<TaskHistoryResponse>;
+    downloadToDir(targetDir: string, options?: DownloadToDirOptions & {
+        status?: string;
+    }): Promise<number>;
+    downloadToMemory(options?: DownloadToMemoryOptions & {
+        status?: string;
+    }): Promise<DownloadedResult[]>;
+    downloadTaskToFile(task: TaskResult, target: string): Promise<void>;
+    downloadTaskToMemory(task: TaskResult): Promise<Buffer>;
+    startExport(): Promise<ExportRef>;
+    downloadAllResults(targetPath: string, options?: {
+        waitTimeout?: number;
+        pollInterval?: number;
+    }): Promise<string>;
+}
+/** Operations on a scheduled job's schedule, reached via `job.schedule`. Scheduled jobs only — regular jobs 409. */
+declare class ScheduleControls {
+    #private;
+    readonly jobId: string;
+    constructor(client: ZenRowsBatchClient, jobId: string);
+    pause(): Promise<JobHandle>;
+    resume(): Promise<JobHandle>;
+    update(schedule: Schedule): Promise<JobHandle>;
+}
+/** A reference to a job by id — job-template operations, plus `run`/`schedule` sub-facets. */
+declare class JobRef {
+    #private;
+    readonly jobId: string;
+    readonly submitResponse?: SubmitJobResponse | undefined;
+    private runFacet?;
+    private scheduleFacet?;
+    constructor(client: ZenRowsBatchClient, jobId: string, submitResponse?: SubmitJobResponse | undefined);
+    /** Operations on the CURRENT run — pause/resume/stop/wait/results/downloads/startExport. */
+    get run(): CurrentRun;
+    /** Operations on the schedule — pause/resume/update (scheduled jobs only). */
+    get schedule(): ScheduleControls;
+    /** The job status from the submit response — only known on refs from a `submit*` call. */
+    get status(): Extensible<JobStatus> | undefined;
+    get acceptedTasks(): number | undefined;
+    load(): Promise<JobHandle>;
+    close(): Promise<JobHandle>;
+    delete(): Promise<void>;
+    rerun(options?: {
+        status?: string | string[];
+        idempotencyKey?: string;
+    }): Promise<RunHandle>;
+    /** Shortcut for `rerun({ status: "failed" })` (or `"failed,pending"` with `includePending`). */
+    retryFailed(options?: {
+        includePending?: boolean;
+        idempotencyKey?: string;
+    }): Promise<RunHandle>;
+    addTasks(tasks: BatchTaskLike[], options?: {
+        lastBatch?: boolean;
+    }): Promise<{
+        accepted_tasks: number;
+        job_status: Extensible<JobStatus>;
+        latest_run: Run;
+    }>;
+    runs(pageSize?: number): AsyncGenerator<RunHandle>;
+    addFileInput(data: Uint8Array | string, options: {
+        fields: {
+            url: string | number;
+            external_id?: string | number;
+        };
+        header?: boolean;
+        delimiter?: string;
+        quote?: string;
+    }): Promise<string>;
+    getWebhook(): Promise<WebhookConfig>;
+    setWebhook(url: string, signature: boolean): Promise<WebhookConfig>;
+    deleteWebhook(): Promise<void>;
+    /** Block until the current run's async-carrier ingestion has finished writing task rows. */
+    waitForIngest(options?: {
+        timeout?: number;
+        pollInterval?: number;
+        maxPollInterval?: number;
+    }): Promise<JobHandle>;
+}
+declare class JobHandle extends JobRef {
+    readonly data: Job;
+    constructor(client: ZenRowsBatchClient, jobId: string, data: Job, submitResponse?: SubmitJobResponse);
+    get status(): Extensible<JobStatus>;
+}
+
+interface BatchClientConfig {
+    /** Override the Batch API base URL. Matches the Go/Python batch clients' base-URL override. */
+    baseURL?: string;
+    /** Retries for transient failures (429/502/503/504 + network errors) on idempotent requests. Default 3. */
+    retries?: number;
+}
+interface BatchTask {
+    url: string;
+    external_id?: string;
+    metadata?: Record<string, unknown>;
+    zenrows_params?: Record<string, unknown>;
+}
+interface BatchWebhookConfig {
+    url: string;
+    signature?: boolean;
+}
+interface SubmitJobOptions {
+    type?: JobType;
+    status?: JobStatus;
+    zenrows_params?: Record<string, unknown>;
+    tasks?: BatchTask[];
+    file_input_id?: string;
+    external_id?: string;
+    name?: string;
+    metadata?: Record<string, unknown>;
+    webhook?: BatchWebhookConfig;
+    idempotencyKey?: string;
+    /** Block until ingestion finishes for a large (202) submission — see `JobRef.waitForIngest`. */
+    waitForIngest?: boolean;
+}
+interface SubmitTypedOptions {
+    zenrowsParams?: ParamMap;
+    externalId?: string;
+    name?: string;
+    metadata?: Record<string, string>;
+    webhook?: BatchWebhookConfig;
+    idempotencyKey?: string;
+    waitForIngest?: boolean;
+}
+interface ListJobsOptions {
+    status?: JobStatus;
+    type?: JobType;
+    limit?: number;
+    cursor?: string;
+}
+interface GetResultsOptions {
+    runId?: string;
+    cursor?: string;
+    limit?: number;
+    status?: string;
+}
+interface WaitForRunOptions {
+    runId?: string;
+    /**
+     * Statuses that resolve the wait. Defaults to every terminal status (`completed`,
+     * `stopped`, `failed`, `deleted`), so an auto-failed run resolves with its
+     * `failure_reason` / `failure_detail` instead of polling until `timeout`.
+     */
+    targetStatuses?: Set<string>;
+    /**
+     * Statuses that reject with `WaiterFailureError`. Takes precedence over `targetStatuses`,
+     * so `new Set(["failed"])` makes a failed run throw. Empty by default.
+     */
+    failureStatuses?: Set<string>;
+    timeout?: number;
+    pollInterval?: number;
+    maxPollInterval?: number;
+}
+type TaskInput = string | {
+    url: string;
+    external_id?: string;
+    metadata?: Record<string, unknown>;
+    /** Per-task scrape params, merged over the job-level `zenrowsParams` (task wins). */
+    zenrows_params?: Record<string, unknown>;
+};
+/**
+ * Client for the Zenrows Batch API (async, job/run/task model). Usable standalone
+ * (`new ZenRowsBatchClient(apiKey)`, matching the Go and Python SDKs' batch clients) or via
+ * the `client.batch` convenience property on a `ZenRows` instance.
+ *
+ * The **main pattern** is resource-style: `job(id)` / `submit*` return a `JobRef` (id-only,
+ * no network); `getJob()` / `iterJobs()` return a loaded `JobHandle` with `.data`. Mutating
+ * operations (`close`, `run.stop`, …) return a FRESH handle carrying the server's updated
+ * state rather than mutating in place.
+ */
+declare class ZenRowsBatchClient {
+    readonly apiKey: string;
+    private readonly transport;
+    constructor(apiKey: string, config?: BatchClientConfig);
+    submitJob(options?: SubmitJobOptions): Promise<JobRef>;
+    /** Submit a one-shot scraping job (closed, all tasks known upfront). */
+    submitRegular(urls?: TaskInput[], fileInputId?: string, opts?: SubmitTypedOptions): Promise<JobRef>;
+    /** Submit a streaming-style job that stays open for more tasks via `JobRef.addTasks`. */
+    submitOpen(urls?: TaskInput[], opts?: SubmitTypedOptions): Promise<JobRef>;
+    /** Submit a scheduled job. `schedule` is one of the `At`/`Rate`/`Calendar` builders. */
+    submitScheduled(schedule: Schedule, urls?: TaskInput[], fileInputId?: string, opts?: SubmitTypedOptions): Promise<JobRef>;
+    estimateCost(tasks: Iterable<TaskLike>, zenrowsParams?: ParamMap): CostEstimate;
+    /** A `JobRef` for an existing job with no network call — prefer this to act on a known id. */
+    job(jobId: string): JobRef;
+    getJob(jobId: string): Promise<JobHandle>;
+    listJobs(options?: ListJobsOptions): Promise<ListJobsResponse>;
+    iterJobs(options?: Omit<ListJobsOptions, "cursor">): AsyncGenerator<JobHandle>;
+    /** A `RunRef` for an existing run with no network call. */
+    run(jobId: string, runId: string): RunRef;
+    getRun(jobId: string, runId: string): Promise<RunHandle>;
+    listRuns(jobId: string, options?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<ListJobRunsResponse>;
+    iterRuns(jobId: string, pageSize?: number): AsyncGenerator<RunHandle>;
+    getResults(jobId: string, options?: GetResultsOptions): Promise<ListResultsResponse>;
+    iterResults(jobId: string, options?: {
+        runId?: string;
+        status?: string;
+    }): AsyncGenerator<TaskResult>;
+    /** Returns the scraped page's raw content as-is (HTML/text, not JSON). */
+    getTaskContent(jobId: string, taskId: string, options?: {
+        runId?: string;
+    }): Promise<string>;
+    getTaskHistory(jobId: string, taskId: string, options?: {
+        runId?: string;
+    }): Promise<TaskHistoryResponse>;
+    downloadToDir(jobId: string, runId: string | undefined, targetDir: string, opts?: DownloadToDirOptions): Promise<number>;
+    downloadToMemory(jobId: string, runId: string | undefined, opts?: DownloadToMemoryOptions & {
+        status?: string;
+    }): Promise<DownloadedResult[]>;
+    downloadTaskToFile(task: TaskResult, target: string): Promise<void>;
+    downloadTaskToMemory(task: TaskResult): Promise<Buffer>;
+    getJobWebhook(jobId: string): Promise<WebhookConfig>;
+    putJobWebhook(jobId: string, config: BatchWebhookConfig): Promise<WebhookConfig>;
+    deleteJobWebhook(jobId: string): Promise<void>;
+    testWebhook(config: BatchWebhookConfig): Promise<TestWebhookResponse>;
+    listHmacKeys(): Promise<HMACKeyList>;
+    /** Capture the returned `secret` HERE — it is not revealed again. */
+    rotateHmacKey(): Promise<HMACKeyCreated>;
+    finalizeHmacKey(): Promise<HMACKeyFinalized>;
+    cancelHmacRotation(): Promise<void>;
+    createJobInput(body: {
+        type: "csv";
+        csv: {
+            delimiter?: string;
+            quote?: string;
+            header?: boolean;
+            fields: {
+                url: string | number;
+                external_id?: string | number;
+            };
+        };
+    }): Promise<CreateJobInputResponse>;
+    /** Allocate a CSV slot + PUT the body. Returns the `file_input_id` to pass to `submitJob`. */
+    uploadCsv(data: Uint8Array | string, options: {
+        fields: {
+            url: string | number;
+            external_id?: string | number;
+        };
+        header?: boolean;
+        delimiter?: string;
+        quote?: string;
+    }): Promise<string>;
+    startResultsExport(jobId: string, runId: string): Promise<ExportRef>;
+    getResultsExport(jobId: string, runId: string, exportId: string): Promise<ExportHandle>;
+    waitForExport(jobId: string, runId: string, exportId: string, options?: {
+        targetStatuses?: Set<string>;
+        timeout?: number;
+        pollInterval?: number;
+        maxPollInterval?: number;
+    }): Promise<Export>;
+    /** Start an export, wait for it, and save the zip to `targetPath`. Capped at 1 GiB per run. */
+    downloadAllResults(jobId: string, runId: string, targetPath: string, options?: {
+        waitTimeout?: number;
+        pollInterval?: number;
+    }): Promise<string>;
+    waitForRun(jobId: string, options?: WaitForRunOptions): Promise<Run>;
+    /** @internal */
+    _getJobData(jobId: string): Promise<Job>;
+    /** @internal */
+    _getRunData(jobId: string, runId: string): Promise<Run>;
+    /** @internal */
+    _postClose(jobId: string): Promise<Job>;
+    /** @internal */
+    _postStop(jobId: string): Promise<Run>;
+    /** @internal */
+    _postPause(jobId: string): Promise<Run>;
+    /** @internal */
+    _postResume(jobId: string): Promise<Run>;
+    /** @internal */
+    _delete(jobId: string): Promise<void>;
+    /** @internal */
+    _deleteRun(jobId: string, runId: string): Promise<void>;
+    /** @internal */
+    _postRerun(jobId: string, options?: {
+        status?: string | string[];
+        idempotencyKey?: string;
+    }): Promise<RerunJobResponse>;
+    /** @internal */
+    _putSchedule(jobId: string, schedule: JobSchedule): Promise<Job>;
+    /** @internal */
+    _postScheduleState(jobId: string, state: "paused" | "active"): Promise<Job>;
+    /** @internal */
+    _postTasks(jobId: string, tasks: BatchTask[], options?: {
+        lastBatch?: boolean;
+    }): Promise<AddTasksResponse>;
+    /** @internal */
+    _postExportStart(jobId: string, runId: string): Promise<StartExportResponse>;
+    /** @internal */
+    _getExport(jobId: string, runId: string, exportId: string): Promise<Export>;
+    /** @internal */
+    _waitForRunRaw(jobId: string, options: WaitForRunOptions): Promise<Run>;
+    /** @internal */
+    _waitForIngestRaw(jobId: string, options?: {
+        timeout?: number;
+        pollInterval?: number;
+        maxPollInterval?: number;
+    }): Promise<Job>;
+}
+
+/**
+ * A non-2xx response from the Batch API, decoded as RFC 7807 `application/problem+json`
+ * where possible. `code` is the stable Problem `code` member (e.g. `file_input_not_found`) —
+ * safe to branch on; defaults to `"internal"` when the body wasn't valid Problem JSON.
+ */
+declare class ZenRowsBatchError extends Error {
+    readonly status: number;
+    readonly problem: ProblemJson | undefined;
+    readonly code: string;
+    readonly extras: Record<string, unknown> | undefined;
+    constructor(status: number, problem: ProblemJson | undefined, extras?: Record<string, unknown>);
+}
+/**
+ * Parse a Problem+JSON error body. Tolerant of non-JSON bodies (production servers
+ * occasionally return a raw error page, e.g. from an edge proxy) — degrades to
+ * `undefined` rather than throwing.
+ */
+declare function parseProblem(response: Response): Promise<{
+    problem: ProblemJson | undefined;
+    extras: Record<string, unknown> | undefined;
+}>;
+
+/** Raised when a waiter's `timeout` elapsed before the target state was reached. */
+declare class WaiterTimeoutError extends Error {
+    constructor(message: string);
+}
+/** Raised when the resource entered one of the caller's `isFailure` states. */
+declare class WaiterFailureError extends Error {
+    constructor(message: string);
+}
+interface PollUntilOptions<T> {
+    isDone(value: T): boolean;
+    isFailure?(value: T): boolean;
+    timeout?: number;
+    initialInterval?: number;
+    maxInterval?: number;
+    backoff?: number;
+    jitter?: number;
+}
+/**
+ * Generic poll loop. Calls `fetch()` repeatedly until `isDone(value)` (returns the value),
+ * `isFailure(value)` (throws `WaiterFailureError`), or `timeout` seconds elapse (throws
+ * `WaiterTimeoutError`). The wait between calls starts at `initialInterval`, multiplies by
+ * `backoff` each iteration, caps at `maxInterval`, and is jittered by ±`jitter` fraction so
+ * concurrent waiters don't synchronise into thundering-herd patterns against the API.
+ */
+declare function pollUntil<T>(fetch: () => Promise<T> | T, { isDone, isFailure, timeout, initialInterval, maxInterval, backoff, jitter, }: PollUntilOptions<T>): Promise<T>;
+
 type HttpMethods = "GET" | "POST" | "PUT";
+/** Extract mode — see https://docs.zenrows.com for what each mode returns. */
+type ExtractMode = "auto" | "native" | "standard";
 interface ClientConfig {
     concurrency?: number;
     retries?: number;
 }
 interface ZenRowsConfig {
+    /** Set to "auto" to enable Adaptive Stealth Mode — Zenrows starts with the cheapest
+     * viable request configuration and escalates to js_render/premium_proxy only when the
+     * target needs it, billing only for the configuration that succeeds. */
+    mode?: "auto";
     autoparse?: boolean;
     css_extractor?: string;
     js_render?: boolean;
@@ -36,8 +800,41 @@ declare class ZenRows {
         data?: unknown;
     }, Response>;
     readonly fetchWithRetry: (input: string | URL | Request, init?: (RequestInit & fetch_retry.RequestInitRetryParams<typeof fetch>) | undefined) => Promise<Response>;
+    /** Client for the Batch API (async job/run/task model) — see `./batch.ts`. */
+    readonly batch: ZenRowsBatchClient;
     constructor(apiKey: string, clientConfig?: ClientConfig);
-    get(url: string, config?: ZenRowsConfig, { headers }?: {
+    /**
+     * Fetch a URL through Zenrows — the main page-scraping product. This is the primary entry
+     * point; `get()` remains as a deprecated alias for existing callers.
+     */
+    fetch(url: string, config?: ZenRowsConfig, { headers }?: {
+        headers?: Headers;
+    }): Promise<Response>;
+    /** @deprecated Use `fetch()` instead. Kept for backward compatibility. */
+    get(url: string, config?: ZenRowsConfig, opts?: {
+        headers?: Headers;
+    }): Promise<Response>;
+    /**
+     * Fetch a URL and run it through Extract — Zenrows' AI-powered structured extraction
+     * (beta). `mode` defaults to `"auto"`; pass `"native"` or `"standard"` to pick a
+     * different extraction contract. This is a thin, typed wrapper over `fetch()` with the
+     * `extract` param set — no separate endpoint or auth.
+     *
+     * Also sends Adaptive Stealth Mode (`mode: "auto"`) by default, so a target that needs
+     * `js_render`/`premium_proxy` gets escalated automatically instead of failing with
+     * REQS002 — pass `adaptiveStealth: false` to disable that and set `js_render`/
+     * `premium_proxy` yourself.
+     *
+     * `extract=auto` is a domain-gated open beta: when the target domain isn't enabled yet,
+     * the API returns a 402 with `code: "AUTH010"`. By default this method catches that and
+     * retries once with `autoparse: true` instead of returning the error response — pass
+     * `fallbackToAutoparse: false` to disable that and get the raw AUTH010 response back.
+     */
+    extract(url: string, config?: ZenRowsConfig & {
+        extract?: ExtractMode;
+        fallbackToAutoparse?: boolean;
+        adaptiveStealth?: boolean;
+    }, opts?: {
         headers?: Headers;
     }): Promise<Response>;
     post(url: string, config?: ZenRowsConfig, { headers, data }?: {
@@ -47,4 +844,4 @@ declare class ZenRows {
     private worker;
 }
 
-export { ZenRows, type ZenRowsConfig };
+export { AUTO_MAX_CREDITS, AUTO_MIN_CREDITS, type AddTasksResponse, At, BASE_CREDITS, type BatchClientConfig, type BatchTask, type BatchWebhookConfig, type Cadence, Calendar, type CostEstimate, type CostLine, type CreateJobInputResponse, CurrentRun, DEFAULT_MAX_BYTES_PER_FILE, DEFAULT_MAX_COUNT_IN_MEMORY, DEFAULT_MAX_FILES, DEFAULT_MAX_TOTAL_BYTES_IN_MEMORY, Daily, type DownloadToDirOptions, type DownloadToMemoryOptions, type DownloadedResult, type EstimateTask, type Export, ExportHandle, ExportRef, type ExportStatus, type Extensible, type ExtractMode, type FileInputUploadTarget, type GetResultsOptions, type HMACKeyCreated, type HMACKeyFinalized, type HMACKeyList, type HMACKeyMeta, type IngestStatus, JS_AND_PROXY_CREDITS, JS_CREDITS, type Job, JobHandle, JobRef, type JobSchedule, type JobStatus, type JobType, type ListJobRunsResponse, type ListJobsOptions, type ListJobsResponse, type ListResultsResponse, Monthly, PREMIUM_PROXY_CREDITS, type ParamMap, type ParamValue, type PauseState, type PollUntilOptions, type ProblemJson, Rate, type RerunJobResponse, type Run, type RunFailureReason, RunHandle, RunRef, type RunStats, type RunStatus, type Schedule, type ScheduleState, type Spend, type StartExportResponse, type SubmitJobOptions, type SubmitJobResponse, type SubmitTypedOptions, type TaskHistoryEvent, type TaskHistoryResponse, type TaskLike, type TaskResult, type TaskSpend, type TaskStatus, type TestWebhookResponse, type Tier, type WaitForRunOptions, WaiterFailureError, WaiterTimeoutError, type WebhookConfig, Weekly, ZenRows, ZenRowsBatchClient, ZenRowsBatchError, type ZenRowsConfig, downloadTaskToFile, downloadTaskToMemory, downloadToDir, downloadToMemory, estimateCost, parseProblem, pollUntil };