quantumproxies 0.1.0__tar.gz

quantumproxies-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+# Build artifacts / archives — never commit to git
+landing.tar.gz
+chrome-extension.zip
+paypal-update.tar.gz
+*.tar.gz
+
+# OS / editor
+.DS_Store
+.cursor/
+.claude/
+
+# Upstream study clone — do not commit (see OpenSERP local study plan)
+openserp/
+
+# SERP cookie-farm runtime state — real Google cookie jars, never commit
+scraper-service/.jar-store/
+scraper-service/.jars/
+
+# Dipendenze installate — mai in git (2.302 file al 2026-08-21)
+node_modules/
+
+# Segreti reali. Gli .env.example restano tracciati apposta.
+.env
+.env.*
+!.env.example
+!.env.*.example
+blog-tools/.env.neon
+
+# Materiale CA del web unlocker: chiave privata + certificato, mai in git
+scraper-service/.unlock-ca/
+
+# Stato runtime dei job/dataset del servizio
+scraper-service/.job-store/
+scraper-service/.dataset-files/

quantumproxies-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QuantumProxies
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

quantumproxies-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.5
+Name: quantumproxies
+Version: 0.1.0
+Summary: Official Python SDK for the QuantumProxies API — web scraping to Markdown, SERP search, crawl/map, 74 ready-made Collectors and residential/mobile/datacenter proxy generation.
+Project-URL: Homepage, https://quantumproxies.io
+Project-URL: Documentation, https://quantumproxies.io/data-api
+Project-URL: Repository, https://github.com/quantumproxies/quantumproxies-python
+Author-email: QuantumProxies <support@quantumproxies.io>
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,crawler,data-extraction,google-search,proxy,quantumproxies,residential-proxies,scraper,serp,web-scraping
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.25
+Description-Content-Type: text/markdown
+
+# quantumproxies — Python SDK for the QuantumProxies API
+
+Scrape any page to clean Markdown, run structured Google/Bing/DuckDuckGo
+searches, crawl and map whole sites, run 74 ready-made Collectors
+(Amazon, Google Maps, LinkedIn jobs, app stores…), build datasets from a
+plain-language prompt — everything through QuantumProxies' residential
+proxy network with real-browser TLS fingerprints. Pay per successful call;
+blocked pages cost nothing.
+
+```bash
+pip install quantumproxies
+```
+
+## Quickstart
+
+```python
+from quantumproxies import QuantumProxies
+
+client = QuantumProxies()  # reads QUANTUMPROXIES_API_KEY from the environment
+
+page = client.scrape("https://example.com")
+print(page["title"], page["engine"])
+print(page["content"])          # the page as clean Markdown
+```
+
+Get a free API key at [quantumproxies.io](https://quantumproxies.io) — every
+account includes free monthly usage, no card required. Set it once:
+
+```bash
+export QUANTUMPROXIES_API_KEY=qp_live_your_key_here
+```
+
+## What's in the box
+
+Every REST endpoint, one method each — responses come back with the API
+envelope already unwrapped:
+
+```python
+# Structured search — 3 engines, 17 verticals, SerpApi-compatible JSON
+serp = client.search("best espresso machine", country="us", num=20)
+for r in serp["organic"]:
+    print(r["rank"], r["title"], r["link"])
+
+# SERP → citation-ready Markdown context for an AI prompt
+ctx = client.search_and_read("latest EU AI act status", top_n=3)
+
+# Map a site's URLs in seconds (sitemaps + homepage links)
+urls = client.map("https://stripe.com", search="/blog")
+
+# Async crawl — wait=True polls until it settles and returns the pages
+job = client.crawl("https://docs.python.org", limit=30, depth=2, wait=True)
+
+# Batch-scrape known URLs
+job = client.batch(["https://a.example", "https://b.example"], wait=True)
+
+# CSS/AI extraction on one page
+data = client.scrape(
+    "https://books.toscrape.com",
+    extract={"titles": {"selector": "h3 a", "attr": "title", "all": True}},
+)
+
+# Learn selectors once with an LLM, then scrape the same layout for free
+parser = client.generate_parser(
+    "https://news.ycombinator.com",
+    fields={"titles": "every story title, as a list"},
+)
+
+# 74 ready-made Collectors — semantic input instead of URLs
+places = client.run_collector(
+    "google_maps_places", keyword="dentist", location="Austin, TX", max_results=20
+)
+
+# Dataset from a prompt (validated rows, budget-capped)
+ds = client.create_dataset(
+    "coffee roasters in Portland with email and phone",
+    limits={"max_rows": 50, "max_cost_usd": 2},
+    wait=True,
+)
+
+# Proxy endpoints of every type — residential, mobile, datacenter, ISP, IPv6
+plans = client.list_proxies(active=True)
+proxies = client.generate_proxies(plans["proxies"][0]["orderId"], country="us", quantity=5)
+```
+
+## Errors and retries
+
+Failures raise `QuantumProxiesError` with `.status`, `.message` and
+`.payload`. Connection errors and HTTP 429 are retried with backoff;
+billable calls are never re-sent after a response was received, so nothing
+gets double-billed behind your back.
+
+```python
+from quantumproxies import QuantumProxies, QuantumProxiesError
+
+try:
+    QuantumProxies(api_key="qp_live_wrong").scrape("https://example.com")
+except QuantumProxiesError as err:
+    print(err.status, err.message)
+```
+
+## Also available
+
+- **MCP server** for Claude, Cursor and any MCP client:
+  [`npx -y quantumproxies-mcp`](https://www.npmjs.com/package/quantumproxies-mcp)
+  exposes the same 25 tools to AI agents.
+- **REST reference**: [quantumproxies.io/data-api](https://quantumproxies.io/data-api)
+
+MIT licensed.

quantumproxies-0.1.0/README.md

@@ -0,0 +1,108 @@
+# quantumproxies — Python SDK for the QuantumProxies API
+
+Scrape any page to clean Markdown, run structured Google/Bing/DuckDuckGo
+searches, crawl and map whole sites, run 74 ready-made Collectors
+(Amazon, Google Maps, LinkedIn jobs, app stores…), build datasets from a
+plain-language prompt — everything through QuantumProxies' residential
+proxy network with real-browser TLS fingerprints. Pay per successful call;
+blocked pages cost nothing.
+
+```bash
+pip install quantumproxies
+```
+
+## Quickstart
+
+```python
+from quantumproxies import QuantumProxies
+
+client = QuantumProxies()  # reads QUANTUMPROXIES_API_KEY from the environment
+
+page = client.scrape("https://example.com")
+print(page["title"], page["engine"])
+print(page["content"])          # the page as clean Markdown
+```
+
+Get a free API key at [quantumproxies.io](https://quantumproxies.io) — every
+account includes free monthly usage, no card required. Set it once:
+
+```bash
+export QUANTUMPROXIES_API_KEY=qp_live_your_key_here
+```
+
+## What's in the box
+
+Every REST endpoint, one method each — responses come back with the API
+envelope already unwrapped:
+
+```python
+# Structured search — 3 engines, 17 verticals, SerpApi-compatible JSON
+serp = client.search("best espresso machine", country="us", num=20)
+for r in serp["organic"]:
+    print(r["rank"], r["title"], r["link"])
+
+# SERP → citation-ready Markdown context for an AI prompt
+ctx = client.search_and_read("latest EU AI act status", top_n=3)
+
+# Map a site's URLs in seconds (sitemaps + homepage links)
+urls = client.map("https://stripe.com", search="/blog")
+
+# Async crawl — wait=True polls until it settles and returns the pages
+job = client.crawl("https://docs.python.org", limit=30, depth=2, wait=True)
+
+# Batch-scrape known URLs
+job = client.batch(["https://a.example", "https://b.example"], wait=True)
+
+# CSS/AI extraction on one page
+data = client.scrape(
+    "https://books.toscrape.com",
+    extract={"titles": {"selector": "h3 a", "attr": "title", "all": True}},
+)
+
+# Learn selectors once with an LLM, then scrape the same layout for free
+parser = client.generate_parser(
+    "https://news.ycombinator.com",
+    fields={"titles": "every story title, as a list"},
+)
+
+# 74 ready-made Collectors — semantic input instead of URLs
+places = client.run_collector(
+    "google_maps_places", keyword="dentist", location="Austin, TX", max_results=20
+)
+
+# Dataset from a prompt (validated rows, budget-capped)
+ds = client.create_dataset(
+    "coffee roasters in Portland with email and phone",
+    limits={"max_rows": 50, "max_cost_usd": 2},
+    wait=True,
+)
+
+# Proxy endpoints of every type — residential, mobile, datacenter, ISP, IPv6
+plans = client.list_proxies(active=True)
+proxies = client.generate_proxies(plans["proxies"][0]["orderId"], country="us", quantity=5)
+```
+
+## Errors and retries
+
+Failures raise `QuantumProxiesError` with `.status`, `.message` and
+`.payload`. Connection errors and HTTP 429 are retried with backoff;
+billable calls are never re-sent after a response was received, so nothing
+gets double-billed behind your back.
+
+```python
+from quantumproxies import QuantumProxies, QuantumProxiesError
+
+try:
+    QuantumProxies(api_key="qp_live_wrong").scrape("https://example.com")
+except QuantumProxiesError as err:
+    print(err.status, err.message)
+```
+
+## Also available
+
+- **MCP server** for Claude, Cursor and any MCP client:
+  [`npx -y quantumproxies-mcp`](https://www.npmjs.com/package/quantumproxies-mcp)
+  exposes the same 25 tools to AI agents.
+- **REST reference**: [quantumproxies.io/data-api](https://quantumproxies.io/data-api)
+
+MIT licensed.

quantumproxies-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "quantumproxies"
+version = "0.1.0"
+description = "Official Python SDK for the QuantumProxies API — web scraping to Markdown, SERP search, crawl/map, 74 ready-made Collectors and residential/mobile/datacenter proxy generation."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "QuantumProxies", email = "support@quantumproxies.io" }]
+requires-python = ">=3.9"
+dependencies = ["requests>=2.25"]
+keywords = [
+  "web-scraping",
+  "scraper",
+  "serp",
+  "proxy",
+  "residential-proxies",
+  "crawler",
+  "google-search",
+  "quantumproxies",
+  "data-extraction",
+  "ai-agents",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Internet :: WWW/HTTP",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://quantumproxies.io"
+Documentation = "https://quantumproxies.io/data-api"
+Repository = "https://github.com/quantumproxies/quantumproxies-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/quantumproxies"]

quantumproxies-0.1.0/src/quantumproxies/__init__.py

@@ -0,0 +1,32 @@
+"""Official Python SDK for the QuantumProxies API — scrape, search, map and
+crawl the web through residential proxies, run the 74 ready-made Collectors,
+build datasets from a prompt, and generate proxy endpoints of every type.
+
+Quickstart::
+
+    from quantumproxies import QuantumProxies
+
+    client = QuantumProxies()  # reads QUANTUMPROXIES_API_KEY
+    page = client.scrape("https://example.com")
+    print(page["content"])
+"""
+
+__version__ = "0.1.0"
+
+from ._client import (  # noqa: E402
+    DEFAULT_BASE_URL,
+    QuantumProxies,
+    QuantumProxiesError,
+)
+
+Client = QuantumProxies
+ApiError = QuantumProxiesError
+
+__all__ = [
+    "QuantumProxies",
+    "QuantumProxiesError",
+    "Client",
+    "ApiError",
+    "DEFAULT_BASE_URL",
+    "__version__",
+]

quantumproxies-0.1.0/src/quantumproxies/_client.py

@@ -0,0 +1,559 @@
+"""HTTP client for the QuantumProxies API.
+
+Thin by design: every method maps 1:1 onto a REST endpoint, request bodies are
+plain dicts, responses are the API envelope's ``payload`` already unwrapped.
+The only sugar is ``wait=True`` on the async job starters, which polls the
+job's status endpoint until it settles.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from typing import Any, Dict, List, Optional, Union
+
+import requests
+
+from . import __version__
+
+DEFAULT_BASE_URL = "https://api.quantumproxies.io/v1"
+ENV_API_KEY = "QUANTUMPROXIES_API_KEY"
+ENV_API_BASE = "QUANTUMPROXIES_API_BASE"
+
+# Job statuses after which polling stops (jobs report e.g. done/completed on
+# success, failed/error on failure; partial results are still in the payload).
+_TERMINAL_STATUSES = {"done", "completed", "failed", "error", "cancelled"}
+
+_JOB_ID_FIELDS = ("jobId", "job_id", "run_id", "runId", "id")
+
+
+class QuantumProxiesError(Exception):
+    """Raised when the API answers with the error envelope or transport fails.
+
+    Attributes:
+        message: human-readable reason from the API's ``message`` field.
+        status:  HTTP status code, when a response was received.
+        payload: the error envelope's ``payload``, when present.
+    """
+
+    def __init__(self, message: str, status: Optional[int] = None, payload: Any = None):
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.payload = payload
+
+
+class QuantumProxies:
+    """Client for the QuantumProxies API.
+
+    Args:
+        api_key: your ``qp_live_…`` key; falls back to ``QUANTUMPROXIES_API_KEY``.
+        base_url: API base, default ``https://api.quantumproxies.io/v1``
+            (override with ``QUANTUMPROXIES_API_BASE``).
+        timeout: per-request timeout in seconds (default 90, matching the
+            slowest render-tier scrapes).
+        max_retries: extra attempts on connection errors and HTTP 429. Billable
+            calls are never retried after a response was received, so a
+            successful-but-lost call is not silently re-billed.
+        session: optional ``requests.Session`` to reuse connections.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = 90.0,
+        max_retries: int = 2,
+        session: Optional[requests.Session] = None,
+    ):
+        self.api_key = api_key or os.environ.get(ENV_API_KEY, "")
+        if not self.api_key:
+            raise QuantumProxiesError(
+                f"No API key. Pass api_key=... or set {ENV_API_KEY}. "
+                "Get a free key at https://quantumproxies.io"
+            )
+        self.base_url = (base_url or os.environ.get(ENV_API_BASE, DEFAULT_BASE_URL)).rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._session = session or requests.Session()
+        self._session.headers.update(
+            {
+                "Authorization": f"Bearer {self.api_key}",
+                "User-Agent": f"quantumproxies-python/{__version__}",
+            }
+        )
+
+    # ── transport ───────────────────────────────────────────────────────────
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        url = f"{self.base_url}{path}"
+        attempt = 0
+        while True:
+            try:
+                resp = self._session.request(
+                    method,
+                    url,
+                    json=body if method != "GET" else None,
+                    params=params,
+                    timeout=self.timeout,
+                )
+            except requests.RequestException as exc:
+                if attempt < self.max_retries:
+                    attempt += 1
+                    time.sleep(min(2**attempt, 8))
+                    continue
+                raise QuantumProxiesError(f"Cannot reach the QuantumProxies API at {url}: {exc}") from exc
+
+            if resp.status_code == 429 and attempt < self.max_retries:
+                attempt += 1
+                retry_after = resp.headers.get("Retry-After")
+                time.sleep(float(retry_after) if retry_after else min(2**attempt, 8))
+                continue
+
+            ctype = resp.headers.get("content-type", "")
+            if "json" not in ctype:
+                # CSV exports and other text endpoints pass through verbatim.
+                if resp.ok:
+                    return resp.text
+                raise QuantumProxiesError(
+                    resp.text[:500] or f"Request failed (HTTP {resp.status_code})",
+                    status=resp.status_code,
+                )
+
+            try:
+                doc = resp.json()
+            except ValueError:
+                raise QuantumProxiesError(
+                    f"Non-JSON response (HTTP {resp.status_code})", status=resp.status_code
+                )
+
+            if not resp.ok or (isinstance(doc, dict) and doc.get("type") == "error"):
+                message = doc.get("message") if isinstance(doc, dict) else None
+                raise QuantumProxiesError(
+                    message or f"Request failed (HTTP {resp.status_code})",
+                    status=resp.status_code,
+                    payload=doc.get("payload") if isinstance(doc, dict) else None,
+                )
+            if isinstance(doc, dict) and "payload" in doc:
+                return doc["payload"]
+            return doc
+
+    @staticmethod
+    def _clean(mapping: Dict[str, Any]) -> Dict[str, Any]:
+        return {k: v for k, v in mapping.items() if v is not None}
+
+    # ── jobs: shared polling ───────────────────────────────────────────────
+
+    @staticmethod
+    def _job_id(payload: Any) -> Optional[str]:
+        if not isinstance(payload, dict):
+            return None
+        for field in _JOB_ID_FIELDS:
+            value = payload.get(field)
+            if isinstance(value, str) and value:
+                return value
+        return None
+
+    def _wait(self, poll, job_id: str, poll_interval: float, timeout: float, final=None) -> Any:
+        deadline = time.monotonic() + timeout
+        while True:
+            payload = poll(job_id)
+            status = payload.get("status") if isinstance(payload, dict) else None
+            if status in _TERMINAL_STATUSES:
+                return final(job_id) if final is not None else payload
+            if time.monotonic() >= deadline:
+                raise QuantumProxiesError(
+                    f"Job {job_id} still '{status}' after {timeout:.0f}s — poll it yourself later",
+                    payload=payload,
+                )
+            time.sleep(poll_interval)
+
+    # ── scraping ────────────────────────────────────────────────────────────
+
+    def scrape(self, url: Optional[str] = None, **options: Any) -> Any:
+        """Scrape one page to Markdown/HTML/text through a residential proxy.
+
+        Accepts every parameter of ``POST /scraper/extract`` as keyword
+        arguments (``format``, ``content_mode``, ``engine``, ``render``,
+        ``country``, ``extract``, ``ai_prompt``, ``actions``, ``cookies``,
+        ``query``, ``max_tokens`` …). Two ergonomic aliases:
+
+        - ``preset_id="…"`` runs a stored parser preset.
+        - ``fetch_resource="regex"`` returns the first matching network
+          response's body instead of the page.
+        """
+        body = self._clean({"url": url, **options})
+        preset_id = body.pop("preset_id", None)
+        if preset_id:
+            body["presetId"] = preset_id
+        fetch_resource = body.pop("fetch_resource", None)
+        if fetch_resource:
+            actions = list(body.get("actions") or [])
+            actions.append({"fetchResource": {"pattern": fetch_resource}})
+            body["actions"] = actions
+        return self._request("POST", "/scraper/extract", body)
+
+    def batch(
+        self,
+        urls: List[str],
+        *,
+        wait: bool = False,
+        poll_interval: float = 3.0,
+        wait_timeout: float = 600.0,
+        **options: Any,
+    ) -> Any:
+        """Scrape many URLs asynchronously (``POST /scraper/batch``).
+
+        Returns the job payload (with its job id). With ``wait=True`` polls
+        until the job settles and returns the finished job including content.
+        """
+        payload = self._request("POST", "/scraper/batch", self._clean({"urls": urls, **options}))
+        if not wait:
+            return payload
+        job_id = self._job_id(payload)
+        if not job_id:
+            return payload
+        return self._wait(
+            lambda j: self.batch_status(j),
+            job_id,
+            poll_interval,
+            wait_timeout,
+            final=lambda j: self.batch_status(j, include_content=True),
+        )
+
+    def batch_status(
+        self,
+        job_id: str,
+        *,
+        since: Optional[int] = None,
+        include_content: bool = False,
+    ) -> Any:
+        """Poll a batch job; pass the previous ``nextCursor`` as ``since``."""
+        params = self._clean({"since": since, "include_content": "true" if include_content else None})
+        return self._request("GET", f"/scraper/batch/{job_id}", params=params)
+
+    def crawl(
+        self,
+        url: str,
+        *,
+        wait: bool = False,
+        poll_interval: float = 3.0,
+        wait_timeout: float = 600.0,
+        **options: Any,
+    ) -> Any:
+        """Start an async BFS crawl (``POST /scraper/crawl``); options include
+        ``limit``, ``depth``, ``content_mode``, ``include``, ``exclude``,
+        ``country``. With ``wait=True`` returns the finished job with content.
+        """
+        payload = self._request("POST", "/scraper/crawl", self._clean({"url": url, **options}))
+        if not wait:
+            return payload
+        job_id = self._job_id(payload)
+        if not job_id:
+            return payload
+        return self._wait(
+            lambda j: self.crawl_status(j),
+            job_id,
+            poll_interval,
+            wait_timeout,
+            final=lambda j: self.crawl_status(j, include_content=True),
+        )
+
+    def crawl_status(
+        self,
+        job_id: str,
+        *,
+        since: Optional[int] = None,
+        include_content: bool = False,
+    ) -> Any:
+        """Poll a crawl job; content is omitted unless ``include_content=True``."""
+        params = {"include_content": "true" if include_content else "false"}
+        if since is not None:
+            params["since"] = since
+        return self._request("GET", f"/scraper/crawl/{job_id}", params=params)
+
+    def map(self, url: str, **options: Any) -> Any:
+        """Discover a site's URLs fast (``POST /scraper/map``): sitemaps +
+        homepage links, with ``search`` substring filter and ``group_by="path"``.
+        """
+        return self._request("POST", "/scraper/map", self._clean({"url": url, **options}))
+
+    def seo_audit(self, url: str, **options: Any) -> Any:
+        """Audit a URL twice — no-JS bot view and rendered view — plus the diff
+        (``POST /scraper/seo-audit``). ``no_render=True`` for the cheap pass.
+        """
+        return self._request("POST", "/scraper/seo-audit", self._clean({"url": url, **options}))
+
+    # ── search ──────────────────────────────────────────────────────────────
+
+    def search(self, query: Optional[str] = None, **options: Any) -> Any:
+        """Structured Google/Bing/DuckDuckGo search (``POST /scraper/serp``).
+
+        Every SERP API parameter is accepted as a keyword argument:
+        ``engine``, ``search_type`` (17 verticals), ``country``, ``lang``,
+        ``num``, ``page``, ``location``, ``uule``, ``device`` … ID-addressed
+        verticals (``place_details``, ``product``, ``flights``, ``reviews``)
+        take their ids the same way.
+        """
+        return self._request("POST", "/scraper/serp", self._clean({"query": query, **options}))
+
+    def search_and_read(self, query: str, **options: Any) -> Any:
+        """Search the web and return the top pages as citation-ready Markdown
+        context (``POST /ai/search``). Options: ``top_n``, ``max_tokens``,
+        ``engine``, ``country``, ``lang``, ``fetch_content``.
+        """
+        return self._request("POST", "/ai/search", self._clean({"query": query, **options}))
+
+    def search_bulk(
+        self,
+        query: str,
+        *,
+        wait: bool = False,
+        poll_interval: float = 3.0,
+        wait_timeout: float = 600.0,
+        **options: Any,
+    ) -> Any:
+        """Paginate one query across many result pages asynchronously
+        (``POST /scraper/serp/bulk``). Options: ``max_pages``, ``engine``,
+        ``search_type``, ``country``, ``render``, ``webhook`` …
+        """
+        payload = self._request("POST", "/scraper/serp/bulk", self._clean({"query": query, **options}))
+        if not wait:
+            return payload
+        job_id = self._job_id(payload)
+        if not job_id:
+            return payload
+        return self._wait(lambda j: self.search_bulk_status(j), job_id, poll_interval, wait_timeout)
+
+    def search_bulk_status(self, job_id: str, *, since: Optional[int] = None) -> Any:
+        """Poll a bulk search job; pass the previous ``nextCursor`` as ``since``."""
+        return self._request("GET", f"/scraper/serp/bulk/{job_id}", params=self._clean({"since": since}))
+
+    # ── parsers ─────────────────────────────────────────────────────────────
+
+    def generate_parser(self, url: Optional[str] = None, **options: Any) -> Any:
+        """Learn CSS selectors for a page layout once with an LLM
+        (``POST /scraper/parser/generate``), then reuse them for free via
+        ``scrape(extract=…)`` or a saved preset. Options: ``fields``,
+        ``prompt``, ``html``, ``render``, ``country``.
+        """
+        return self._request("POST", "/scraper/parser/generate", self._clean({"url": url, **options}))
+
+    def save_parser_preset(
+        self,
+        name: str,
+        parser: Dict[str, Any],
+        *,
+        source_url: Optional[str] = None,
+        fields: Optional[Dict[str, str]] = None,
+        render: Optional[bool] = None,
+        auto_heal: Optional[bool] = None,
+    ) -> Any:
+        """Store a parser under a name (``POST /scraper/parser/presets``);
+        give ``source_url`` so it can self-heal when the site changes.
+        """
+        return self._request(
+            "POST",
+            "/scraper/parser/presets",
+            self._clean(
+                {
+                    "name": name,
+                    "parser": parser,
+                    "sourceUrl": source_url,
+                    "fields": fields,
+                    "render": render,
+                    "autoHeal": auto_heal,
+                }
+            ),
+        )
+
+    def list_parser_presets(self) -> Any:
+        """List stored parser presets with version, health and changelog."""
+        return self._request("GET", "/scraper/parser/presets")
+
+    def parser_preset_stats(self, preset_id: str) -> Any:
+        """Per-field success rate and decay verdict for one preset."""
+        return self._request("GET", f"/scraper/parser/presets/{preset_id}/stats")
+
+    def heal_parser_preset(self, preset_id: str, *, force: bool = False) -> Any:
+        """Regenerate a preset's selectors now; adopted only if they extract
+        more than the current ones (a no-better heal is not billed).
+        """
+        return self._request("POST", f"/scraper/parser/presets/{preset_id}/heal", {"force": force})
+
+    # ── datasets ────────────────────────────────────────────────────────────
+
+    def create_dataset(
+        self,
+        prompt: str,
+        *,
+        wait: bool = False,
+        poll_interval: float = 5.0,
+        wait_timeout: float = 1800.0,
+        **options: Any,
+    ) -> Any:
+        """Build a validated dataset from a plain-language prompt
+        (``POST /scraper/datasets``). Options: ``columns``, ``country``,
+        ``sources``, ``limits`` (incl. ``max_cost_usd``), ``webhook``.
+        """
+        payload = self._request("POST", "/scraper/datasets", self._clean({"prompt": prompt, **options}))
+        if not wait:
+            return payload
+        job_id = self._job_id(payload)
+        if not job_id:
+            return payload
+        return self._wait(
+            lambda j: self.dataset_status(j, mode="summary"),
+            job_id,
+            poll_interval,
+            wait_timeout,
+            final=lambda j: self.dataset_status(j),
+        )
+
+    def dataset_status(
+        self,
+        job_id: str,
+        *,
+        since: Optional[int] = None,
+        mode: Optional[str] = None,
+    ) -> Any:
+        """Poll a dataset job. ``mode="summary"`` omits rows (light poll);
+        a completed job includes signed CSV/JSON download URLs.
+        """
+        return self._request(
+            "GET", f"/scraper/datasets/{job_id}", params=self._clean({"since": since, "mode": mode})
+        )
+
+    # ── collectors ──────────────────────────────────────────────────────────
+
+    def list_collectors(self, category: Optional[str] = None) -> Any:
+        """Catalog of the 74 ready-made Collectors with schemas, examples,
+        prices and health (``GET /scraper/collectors``, free).
+        """
+        return self._request("GET", "/scraper/collectors", params=self._clean({"category": category}))
+
+    def run_collector(
+        self,
+        slug: str,
+        input: Optional[Dict[str, Any]] = None,
+        *,
+        wait: bool = False,
+        poll_interval: float = 3.0,
+        wait_timeout: float = 900.0,
+        **input_kwargs: Any,
+    ) -> Any:
+        """Run a Collector by slug with its semantic input, e.g.::
+
+            client.run_collector("google_maps_places",
+                                 keyword="dentist", location="Austin, TX")
+
+        Short runs return rows inline; long runs return a ``run_id`` — with
+        ``wait=True`` the client polls it for you. Billed per delivered row.
+        """
+        body = dict(input or {})
+        body.update(input_kwargs)
+        payload = self._request("POST", f"/scraper/collectors/{slug}/run", body)
+        run_id = self._job_id(payload) if isinstance(payload, dict) else None
+        if wait and run_id and isinstance(payload, dict) and payload.get("status") not in _TERMINAL_STATUSES:
+            return self._wait(lambda r: self.collector_run_status(r), run_id, poll_interval, wait_timeout)
+        return payload
+
+    def collector_run_status(self, run_id: str, *, format: Optional[str] = None) -> Any:
+        """Fetch a Collector run: status, cost and rows. ``format="csv"``
+        returns the rows as CSV text.
+        """
+        return self._request(
+            "GET", f"/scraper/collectors/runs/{run_id}", params=self._clean({"format": format})
+        )
+
+    # ── proxies ─────────────────────────────────────────────────────────────
+
+    def list_proxies(
+        self,
+        *,
+        active: Optional[bool] = None,
+        plan_type: Optional[str] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> Any:
+        """List the account's proxy services of every type, with the
+        ``orderId`` to pass to :meth:`generate_proxies`.
+        """
+        return self._request(
+            "GET",
+            "/public/proxies",
+            params=self._clean(
+                {
+                    "active": None if active is None else str(active).lower(),
+                    "planType": plan_type,
+                    "limit": limit,
+                    "offset": offset,
+                }
+            ),
+        )
+
+    def generate_proxies(self, order_id: str, **options: Any) -> Any:
+        """Generate ready-to-use proxy endpoint strings from an active service
+        (``POST /public/proxies/generate``). Options: ``protocol``, ``format``,
+        ``quantity``, ``country``/``state``/``city``, ``rotation``,
+        ``sessionTime``, ``isp``, ``asn`` … The strings plug straight into any
+        HTTP client (``curl -x``, ``requests``' ``proxies=``).
+        """
+        return self._request(
+            "POST", "/public/proxies/generate", self._clean({"orderId": order_id, **options})
+        )
+
+    def proxy_locations(
+        self,
+        plan_type: str,
+        *,
+        level: str = "countries",
+        country: Optional[str] = None,
+        state: Optional[str] = None,
+    ) -> Any:
+        """Valid geo-targeting values for a plan type: ``countries`` (default),
+        ``states``, ``cities``, ``asns``, or ``tree`` for the full
+        country→region→city→ISP tree with slugs.
+        """
+        if level == "tree":
+            if plan_type in ("residentialpremium", "resiprivate"):
+                path = "/public/generator/residential-premium/targeting-options"
+            elif plan_type in ("mobile", "mobile_v2"):
+                path = "/public/generator/mobile/targeting-options"
+            else:
+                path = "/public/generator/datacenter/targeting-options"
+            return self._request("GET", path)
+        segment = "cities" if level == "cities" else level
+        return self._request(
+            "GET",
+            f"/public/geo/{segment}",
+            params=self._clean({"planType": plan_type, "country": country, "state": state}),
+        )
+
+    def whitelist_ip(
+        self,
+        action: str,
+        order_id: str,
+        ip: Optional[str] = None,
+        **options: Any,
+    ) -> Any:
+        """Manage IP-auth whitelisting on a proxy service: ``action`` is
+        ``"list"``, ``"add"`` or ``"remove"`` (mobile ``add`` also accepts
+        ``ports_count``, ``protocol``, ``country``, ``sticky``, ``ttl`` …).
+        """
+        if action == "list":
+            return self._request("GET", "/public/proxies/whitelist-ip", params={"orderId": order_id})
+        if not ip:
+            raise QuantumProxiesError("`ip` is required for add/remove")
+        if action == "remove":
+            return self._request("DELETE", "/public/proxies/whitelist-ip", {"orderId": order_id, "ip": ip})
+        return self._request(
+            "POST", "/public/proxies/whitelist-ip", self._clean({"orderId": order_id, "ip": ip, **options})
+        )