readfetch-client 0.1.11__py3-none-any.whl

readfetch_client/__init__.py

@@ -0,0 +1,51 @@
+"""readfetch x402 REST client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = [
+    "buyer_address",
+    "call",
+    "call_with_meta",
+    "pay",
+    "payment_config",
+    "payment_from_response",
+    "probe",
+    "probe_with_meta",
+    "quote",
+    "readfetch_batch",
+    "readfetch_crawl",
+    "readfetch_crawl_status",
+    "readfetch_diff",
+    "readfetch_fetch",
+    "readfetch_map",
+    "readfetch_pdf",
+    "readfetch_residential",
+    "readfetch_scrape",
+    "readfetch_search",
+    "readfetch_section",
+    "readfetch_screenshot",
+    "readfetch_text",
+    "readfetch_url",
+    "request_id_from_response",
+    "submit_claim",
+    "submit_feedback",
+    "x402_http_client",
+]
+
+
+def __getattr__(name: str) -> Any:
+    if name not in __all__:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    if name in ("payment_config", "buyer_address", "readfetch_url"):
+        from readfetch_client import config as cfg
+
+        return getattr(cfg, name)
+    if name == "payment_from_response":
+        from readfetch_client import payment as pay_mod
+
+        return pay_mod.payment_from_response
+    from readfetch_client import client as impl
+
+    return getattr(impl, name)

readfetch_client/client.py

@@ -0,0 +1,277 @@
+from __future__ import annotations
+
+import hashlib
+import os
+from collections.abc import Mapping
+from typing import Any
+
+import httpx
+from eth_account import Account
+from x402 import x402Client
+from x402.http.clients import x402HttpxClient
+from x402.mechanisms.evm import EthAccountSigner
+from x402.mechanisms.evm.exact.register import register_exact_evm_client
+
+from readfetch_client.config import max_payment_usd, readfetch_base, readfetch_url, require_account_hex, x402_network
+from readfetch_client.endpoints import BY_NAME, endpoint_path
+from readfetch_client.feedback_validation import normalize_feedback
+from readfetch_client.http_json import assert_response_size, json_object_from_response
+from readfetch_client.payment import payment_from_response
+
+_TIMEOUT = 120.0
+
+_x402_clients: dict[tuple[str, str, str], x402Client] = {}
+
+
+def request_id_from_response(response: httpx.Response) -> str | None:
+    return response.headers.get("x-request-id") or response.headers.get("X-Request-Id")
+
+
+def _load_private_key(env: Mapping[str, str] | None = None) -> str:
+    try:
+        return require_account_hex(env)
+    except ValueError as error:
+        raise RuntimeError(str(error)) from error
+
+
+def _x402_client(env: Mapping[str, str] | None = None) -> x402Client:
+    env = os.environ if env is None else env
+    hex_key = _load_private_key(env)
+    fingerprint = hashlib.sha256(hex_key.encode()).hexdigest()
+    network = x402_network(env)
+    cap = max_payment_usd(env)
+    cache_key = (fingerprint, network, cap)
+    cached = _x402_clients.get(cache_key)
+    if cached is not None:
+        return cached
+    client = x402Client().set_spend_controls(
+        {"max_amount_per_payment": f"${cap}"}
+    )
+    account = Account.from_key(hex_key)
+    register_exact_evm_client(client, EthAccountSigner(account), networks=network)
+    _x402_clients[cache_key] = client
+    return client
+
+
+async def _request_json(
+    *,
+    method: str,
+    url: str,
+    body: dict[str, Any] | None,
+    paid: bool,
+    accept: tuple[int, ...],
+    env: Mapping[str, str],
+) -> tuple[dict[str, Any], str | None, httpx.Response]:
+    headers = {"content-type": "application/json"} if method != "GET" else {}
+    if paid:
+        async with x402HttpxClient(_x402_client(env)) as http:
+            if method == "GET":
+                response = await http.get(url, headers=headers, timeout=_TIMEOUT)
+            else:
+                response = await http.post(
+                    url, json=body or {}, headers=headers, timeout=_TIMEOUT
+                )
+            await response.aread()
+    else:
+        async with httpx.AsyncClient(timeout=_TIMEOUT) as http:
+            if method == "GET":
+                response = await http.get(url, headers=headers)
+            else:
+                response = await http.post(url, json=body or {}, headers=headers)
+            await response.aread()
+    if response.status_code not in accept:
+        assert_response_size(response)
+        raise RuntimeError(
+            f"{response.status_code}: {(response.text or '')[:400]}"
+        )
+    data: dict[str, Any] = json_object_from_response(response)
+    return data, request_id_from_response(response), response
+
+
+def x402_http_client(env: Mapping[str, str] | None = None) -> x402HttpxClient:
+    """Paid `httpx` client — signs x402 on 402 and retries (custom URLs)."""
+    return x402HttpxClient(_x402_client(env))
+
+
+async def call(
+    name: str,
+    body: dict[str, Any] | None = None,
+    *,
+    path_params: dict[str, str] | None = None,
+    env: Mapping[str, str] | None = None,
+) -> dict[str, Any]:
+    meta = await call_with_meta(
+        name, body, path_params=path_params, env=env
+    )
+    return meta["data"]
+
+
+async def call_with_meta(
+    name: str,
+    body: dict[str, Any] | None = None,
+    *,
+    path_params: dict[str, str] | None = None,
+    env: Mapping[str, str] | None = None,
+) -> dict[str, Any]:
+    spec = BY_NAME.get(name)
+    if spec is None:
+        raise ValueError(f"unknown endpoint `{name}`")
+    env = os.environ if env is None else env
+    path = endpoint_path(name, path_params)
+    url = readfetch_url(env, path)
+    accept = spec.accept if spec.accept else (200,)
+    data, rid, response = await _request_json(
+        method=spec.method,
+        url=url,
+        body=body,
+        paid=not spec.free,
+        accept=accept,
+        env=env,
+    )
+    return {
+        "data": data,
+        "request_id": rid,
+        "payment": payment_from_response(response),
+    }
+
+
+async def quote(
+    name: str,
+    body: dict[str, Any] | None = None,
+    *,
+    path_params: dict[str, str] | None = None,
+    env: Mapping[str, str] | None = None,
+) -> dict[str, Any]:
+    """402 quote — no wallet. Paid catalog routes only."""
+    spec = BY_NAME.get(name)
+    if spec is None:
+        raise ValueError(f"unknown endpoint `{name}`")
+    if spec.free:
+        raise ValueError(f"`{name}` is free — use call() instead of quote()")
+    env = os.environ if env is None else env
+    path = endpoint_path(name, path_params)
+    url = readfetch_url(env, path)
+    headers = {"content-type": "application/json"} if spec.method != "GET" else {}
+    async with httpx.AsyncClient(timeout=_TIMEOUT) as http:
+        if spec.method == "GET":
+            response = await http.get(url, headers=headers)
+        else:
+            response = await http.post(url, json=body or {}, headers=headers)
+        await response.aread()
+    if response.status_code != 402:
+        assert_response_size(response)
+        raise RuntimeError(
+            f"expected 402 quote, got {response.status_code}: "
+            f"{(response.text or '')[:400]}"
+        )
+    return {
+        "status": 402,
+        "body": json_object_from_response(response),
+        "payment_required": payment_from_response(response)["payment_required"],
+        "request_id": request_id_from_response(response),
+    }
+
+
+async def pay(
+    name: str,
+    body: dict[str, Any] | None = None,
+    *,
+    path_params: dict[str, str] | None = None,
+    env: Mapping[str, str] | None = None,
+) -> dict[str, Any]:
+    """Sign x402 and complete a paid call (alias for `call`)."""
+    return await call(name, body, path_params=path_params, env=env)
+
+
+async def probe(url: str, *, env: Mapping[str, str] | None = None) -> dict:
+    data, _ = await probe_with_meta(url, env=env)
+    return data
+
+
+async def probe_with_meta(
+    url: str, *, env: Mapping[str, str] | None = None
+) -> tuple[dict, str | None]:
+    meta = await call_with_meta("probe", {"url": url}, env=env)
+    return meta["data"], meta["request_id"]
+
+
+async def submit_feedback(
+    request_id: str,
+    category: str,
+    message: str,
+    *,
+    env: Mapping[str, str] | None = None,
+) -> dict:
+    rid, cat, msg = normalize_feedback(request_id, category, message)
+    return await call(
+        "feedback",
+        {"request_id": rid, "category": cat, "message": msg},
+        env=env,
+    )
+
+
+async def submit_claim(
+    claim: dict[str, Any], *, env: Mapping[str, str] | None = None
+) -> dict:
+    return await call("claims", claim, env=env)
+
+
+async def readfetch_text(
+    url: str | dict[str, Any], *, env: Mapping[str, str] | None = None
+) -> dict:
+    body = {"url": url} if isinstance(url, str) else url
+    return await call("text", body, env=env)
+
+
+async def readfetch_map(body: dict[str, Any], *, env: Mapping[str, str] | None = None) -> dict:
+    return await call("map", body, env=env)
+
+
+async def readfetch_scrape(body: dict[str, Any], *, env: Mapping[str, str] | None = None) -> dict:
+    return await call("scrape", body, env=env)
+
+
+async def readfetch_residential(
+    body: dict[str, Any], *, env: Mapping[str, str] | None = None
+) -> dict:
+    return await call("residential", body, env=env)
+
+
+async def readfetch_fetch(body: dict[str, Any], *, env: Mapping[str, str] | None = None) -> dict:
+    return await call("fetch", body, env=env)
+
+
+async def readfetch_batch(body: dict[str, Any], *, env: Mapping[str, str] | None = None) -> dict:
+    return await call("batch", body, env=env)
+
+
+async def readfetch_pdf(body: dict[str, Any], *, env: Mapping[str, str] | None = None) -> dict:
+    return await call("pdf", body, env=env)
+
+
+async def readfetch_section(body: dict[str, Any], *, env: Mapping[str, str] | None = None) -> dict:
+    return await call("section", body, env=env)
+
+
+async def readfetch_diff(body: dict[str, Any], *, env: Mapping[str, str] | None = None) -> dict:
+    return await call("diff", body, env=env)
+
+
+async def readfetch_screenshot(
+    body: dict[str, Any], *, env: Mapping[str, str] | None = None
+) -> dict:
+    return await call("screenshot", body, env=env)
+
+
+async def readfetch_search(body: dict[str, Any], *, env: Mapping[str, str] | None = None) -> dict:
+    return await call("search", body, env=env)
+
+
+async def readfetch_crawl(body: dict[str, Any], *, env: Mapping[str, str] | None = None) -> dict:
+    return await call("crawl", body, env=env)
+
+
+async def readfetch_crawl_status(
+    job_id: str, *, env: Mapping[str, str] | None = None
+) -> dict:
+    return await call("crawl_status", None, path_params={"id": job_id}, env=env)

readfetch_client/config.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import os
+import re
+from urllib.parse import urlparse
+
+from collections.abc import Mapping
+
+_PRODUCTION_HOSTS = frozenset({"readfetch.com", "www.readfetch.com"})
+_DEV_HOSTS = frozenset({"localhost", "127.0.0.1", "[::1]", "::1"})
+
+
+def is_dev_host(hostname: str) -> bool:
+    return _normalize_hostname(hostname) in _DEV_HOSTS
+
+
+_MAX_PAYMENT_RE = re.compile(r"^\d+(\.\d{1,6})?$")
+_HEX_KEY_RE = re.compile(r"^0x[0-9a-fA-F]{64}$")
+
+
+def _normalize_hostname(hostname: str) -> str:
+    return hostname.rstrip(".").lower()
+
+
+def _format_origin(scheme: str, parsed) -> str:
+    host = parsed.hostname
+    if not host:
+        raise ValueError("READFETCH_BASE_URL must include a hostname")
+    host = _normalize_hostname(host)
+    if parsed.port:
+        return f"{scheme}://{host}:{parsed.port}"
+    return f"{scheme}://{host}"
+
+
+def readfetch_base(env: Mapping[str, str] | None = None) -> str:
+    env = os.environ if env is None else env
+    raw = env.get("READFETCH_BASE_URL", "https://readfetch.com").rstrip("/")
+    parsed = urlparse(raw)
+    if parsed.username or parsed.password:
+        raise ValueError("READFETCH_BASE_URL must not include userinfo")
+    if parsed.scheme not in ("http", "https"):
+        raise ValueError("READFETCH_BASE_URL must use http or https")
+    host = _normalize_hostname(parsed.hostname or "")
+    if not host:
+        raise ValueError("READFETCH_BASE_URL must include a hostname")
+    if host in _PRODUCTION_HOSTS:
+        if parsed.scheme != "https":
+            raise ValueError("READFETCH_BASE_URL must use https for readfetch.com")
+        path = parsed.path or ""
+        if path not in ("", "/"):
+            raise ValueError(
+                "READFETCH_BASE_URL must not include a path on readfetch.com"
+            )
+        if parsed.port is not None and parsed.port != 443:
+            raise ValueError(
+                "READFETCH_BASE_URL must use default https port for readfetch.com"
+            )
+        return _format_origin("https", parsed)
+    if env.get("READFETCH_DEV") == "1" and is_dev_host(host):
+        scheme = parsed.scheme or "http"
+        return _format_origin(scheme, parsed)
+    raise ValueError(
+        "READFETCH_BASE_URL must be https://readfetch.com "
+        "(or localhost with READFETCH_DEV=1)"
+    )
+
+
+def readfetch_url(env: Mapping[str, str] | None, path: str) -> str:
+    base = readfetch_base(env)
+    if not path.startswith("/"):
+        raise ValueError("endpoint path must start with /")
+    url = f"{base}{path}"
+    if urlparse(url).netloc != urlparse(base).netloc:
+        raise ValueError("request URL origin must match READFETCH_BASE_URL")
+    return url
+
+
+def max_payment_usd(env: Mapping[str, str] | None = None) -> str:
+    env = os.environ if env is None else env
+    raw = (env.get("READFETCH_MAX_PAYMENT_USD") or "1").strip()
+    if not _MAX_PAYMENT_RE.fullmatch(raw):
+        raise ValueError("READFETCH_MAX_PAYMENT_USD must be a decimal amount")
+    amount = float(raw)
+    if amount <= 0 or amount > 100:
+        raise ValueError("READFETCH_MAX_PAYMENT_USD must be between 0 and 100")
+    return raw
+
+
+def x402_network(env: Mapping[str, str] | None = None) -> str:
+    env = os.environ if env is None else env
+    base = readfetch_base(env)
+    host = _normalize_hostname(urlparse(base).hostname or "")
+    if env.get("READFETCH_DEV") == "1" and is_dev_host(host):
+        return "eip155:84532"
+    return "eip155:8453"
+
+
+def load_account_hex(env: Mapping[str, str] | None = None) -> str | None:
+    """Return normalized key hex, or None if unset or invalid (no raise)."""
+    env = os.environ if env is None else env
+    raw = (env.get("EVM_PRIVATE_KEY") or env.get("X402_BUYER_KEY") or "").strip()
+    if not raw:
+        return None
+    hex_key = raw if raw.startswith("0x") else f"0x{raw}"
+    if not _HEX_KEY_RE.fullmatch(hex_key):
+        return None
+    return hex_key.lower()
+
+
+def require_account_hex(env: Mapping[str, str] | None = None) -> str:
+    """Strict key load for paid calls — raises if missing or malformed."""
+    hex_key = load_account_hex(env)
+    if hex_key is None:
+        env = os.environ if env is None else env
+        if not (env.get("EVM_PRIVATE_KEY") or env.get("X402_BUYER_KEY") or "").strip():
+            raise ValueError("Set EVM_PRIVATE_KEY (Base wallet with USDC)")
+        raise ValueError("EVM_PRIVATE_KEY must be 64 hex bytes (optional 0x prefix)")
+    return hex_key
+
+
+def buyer_address(env: Mapping[str, str] | None = None) -> str | None:
+    hex_key = load_account_hex(env)
+    if not hex_key:
+        return None
+    try:
+        from eth_account import Account
+
+        return Account.from_key(hex_key).address
+    except (ValueError, TypeError):
+        return None
+
+
+def payment_config(env: Mapping[str, str] | None = None) -> dict[str, object]:
+    env = os.environ if env is None else env
+    address = buyer_address(env)
+    return {
+        "base_url": readfetch_base(env),
+        "network": x402_network(env),
+        "max_payment_usd": max_payment_usd(env),
+        "buyer_address": address,
+        "signing_ready": address is not None,
+    }

readfetch_client/endpoints.py

@@ -0,0 +1,77 @@
+"""Published routes — keep in sync with catalog.json (published + integrator)."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Literal
+from urllib.parse import quote
+
+Method = Literal["GET", "POST"]
+_PATH_PARAM = re.compile(r"\{(\w+)\}")
+MAX_PATH_PARAM_LEN = 512
+
+
+@dataclass(frozen=True)
+class EndpointSpec:
+    name: str
+    method: Method
+    path: str
+    free: bool
+    accept: tuple[int, ...] = ()
+
+
+CATALOG_ENDPOINTS: tuple[EndpointSpec, ...] = (
+    EndpointSpec("text", "POST", "/v1/text", False),
+    EndpointSpec("map", "POST", "/v1/map", False),
+    EndpointSpec("scrape", "POST", "/v1/scrape", False),
+    EndpointSpec("residential", "POST", "/v1/scrape/residential", False),
+    EndpointSpec("fetch", "POST", "/v1/fetch", False),
+    EndpointSpec("batch", "POST", "/v1/batch", False),
+    EndpointSpec("pdf", "POST", "/v1/pdf", False),
+    EndpointSpec("section", "POST", "/v1/section", False),
+    EndpointSpec("diff", "POST", "/v1/diff", False),
+    EndpointSpec("screenshot", "POST", "/v1/screenshot", False),
+    EndpointSpec("search", "POST", "/v1/search", False),
+    EndpointSpec("crawl", "POST", "/v1/crawl", False),
+    EndpointSpec("crawl_status", "GET", "/v1/crawl/{id}", True),
+    EndpointSpec("probe", "POST", "/v1/probe", True),
+)
+
+INTEGRATOR_ENDPOINTS: tuple[EndpointSpec, ...] = (
+    EndpointSpec("feedback", "POST", "/v1/feedback", True, (202,)),
+    EndpointSpec("claims", "POST", "/v1/claims", True),
+)
+
+BY_NAME: dict[str, EndpointSpec] = {
+    spec.name: spec for spec in (*CATALOG_ENDPOINTS, *INTEGRATOR_ENDPOINTS)
+}
+
+
+def endpoint_path(name: str, path_params: dict[str, str] | None = None) -> str:
+    spec = BY_NAME.get(name)
+    if spec is None:
+        known = ", ".join(sorted(BY_NAME))
+        raise ValueError(f"unknown endpoint `{name}`; known: {known}")
+    path_params = path_params or {}
+    out = spec.path
+    for key in _PATH_PARAM.findall(spec.path):
+        raw = path_params.get(key)
+        if raw is None:
+            raise ValueError(f"`{name}` requires path_params {key}")
+        value = str(raw).strip()
+        if not value:
+            raise ValueError(f"`{name}` requires path_params {key}")
+        if len(value) > MAX_PATH_PARAM_LEN:
+            raise ValueError(
+                f"`{name}` path_params.{key} exceeds {MAX_PATH_PARAM_LEN} characters"
+            )
+        out = out.replace(f"{{{key}}}", quote(value, safe=""))
+    if "{" in out:
+        raise ValueError(f"`{name}` has unresolved path template")
+    return out
+
+
+def export_name(name: str) -> str:
+    parts = name.split("_")
+    return "readfetch" + "".join(part[:1].upper() + part[1:] for part in parts)

readfetch_client/feedback_validation.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+FEEDBACK_CATEGORIES = frozenset({"integration", "docs", "site", "other"})
+MAX_FEEDBACK_REQUEST_ID_LEN = 256
+
+
+def normalize_feedback(
+    request_id: str, category: str, message: str
+) -> tuple[str, str, str]:
+    rid = (request_id or "").strip()
+    cat = (category or "").strip()
+    msg = (message or "").strip()
+    if not rid:
+        raise ValueError("request_id is required")
+    if len(rid) > MAX_FEEDBACK_REQUEST_ID_LEN:
+        raise ValueError(
+            f"request_id exceeds {MAX_FEEDBACK_REQUEST_ID_LEN} characters"
+        )
+    if cat not in FEEDBACK_CATEGORIES:
+        raise ValueError("category must be integration, docs, site, or other")
+    if not msg or len(msg) > 500:
+        raise ValueError("message is required (max 500 characters)")
+    return rid, cat, msg

readfetch_client/http_json.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+MAX_JSON_RESPONSE_BYTES = 16 * 1024 * 1024
+
+
+def assert_response_size(response: httpx.Response) -> None:
+    raw = response.headers.get("content-length")
+    if raw:
+        try:
+            n = int(raw)
+        except ValueError:
+            n = -1
+        if n > MAX_JSON_RESPONSE_BYTES:
+            raise RuntimeError(
+                f"{response.status_code}: content-length {n} exceeds "
+                f"{MAX_JSON_RESPONSE_BYTES} bytes"
+            )
+    if response.content and len(response.content) > MAX_JSON_RESPONSE_BYTES:
+        raise RuntimeError(
+            f"{response.status_code}: response body exceeds "
+            f"{MAX_JSON_RESPONSE_BYTES} bytes"
+        )
+
+
+def json_object_from_response(response: httpx.Response) -> dict[str, Any]:
+    assert_response_size(response)
+    if not response.content:
+        return {}
+    try:
+        parsed = response.json()
+    except Exception as error:
+        raise RuntimeError(
+            f"{response.status_code}: {(response.text or '')[:400]} (invalid JSON)"
+        ) from error
+    if not isinstance(parsed, dict):
+        raise RuntimeError(
+            f"{response.status_code}: expected JSON object, got {type(parsed).__name__}"
+        )
+    return parsed

readfetch_client/payment.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+import httpx
+
+
+def payment_from_response(response: httpx.Response) -> dict[str, str | None]:
+    """Headers after a successful paid call (200) or on 402 quote."""
+    return {
+        "receipt": response.headers.get("receipt") or response.headers.get("RECEIPT"),
+        "payment_response": (
+            response.headers.get("payment-response")
+            or response.headers.get("PAYMENT-RESPONSE")
+            or response.headers.get("x-payment-response")
+            or response.headers.get("X-PAYMENT-RESPONSE")
+        ),
+        "payment_required": (
+            response.headers.get("payment-required")
+            or response.headers.get("PAYMENT-REQUIRED")
+        ),
+        "credit_applied": response.headers.get("x-credit-applied")
+        or response.headers.get("X-CREDIT-APPLIED"),
+    }

readfetch_client-0.1.11.dist-info/METADATA

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: readfetch-client
+Version: 0.1.11
+Summary: x402 REST client for readfetch.com (probe, text, …)
+Project-URL: Homepage, https://readfetch.com
+Project-URL: Repository, https://github.com/readfetch/client-py
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: eth-account>=0.13
+Requires-Dist: httpx>=0.27
+Requires-Dist: x402[evm,httpx]>=2.0
+Description-Content-Type: text/markdown
+
+# readfetch-client
+
+Python x402 REST client for [readfetch.com](https://readfetch.com) — all published catalog routes plus feedback and claims.
+
+Checkout: `tools/client-py`. GitHub: `./scripts/publish-client-py.sh`.
+
+## Install
+
+```bash
+pip install readfetch-client
+```
+
+## Use
+
+```bash
+export EVM_PRIVATE_KEY=0x…   # paid routes only
+```
+
+```python
+import asyncio
+from readfetch_client import (
+    call,
+    probe_with_meta,
+    readfetch_text,
+    readfetch_map,
+    readfetch_crawl_status,
+    submit_feedback,
+    submit_claim,
+)
+
+async def main():
+    check, request_id = await probe_with_meta("https://example.com")
+    if not check.get("challenge"):
+        await readfetch_text("https://example.com")
+    await readfetch_map({"url": "https://example.com", "max_urls": 20})
+    job = await call("crawl", {"url": "https://example.com", "max_pages": 3})
+    await readfetch_crawl_status(job["id"])
+    if request_id:
+        await submit_feedback(request_id, "integration", "…")
+
+asyncio.run(main())
+```
+
+Named helpers: `readfetch_text`, `readfetch_map`, `readfetch_scrape`, `readfetch_residential`, `readfetch_fetch`, `readfetch_batch`, `readfetch_pdf`, `readfetch_section`, `readfetch_diff`, `readfetch_screenshot`, `readfetch_search`, `readfetch_crawl`, `readfetch_crawl_status`. Generic: `await call("search", {"query": "…"})`.
+
+## Payment (x402)
+
+Paid routes use **`x402` + `x402HttpxClient`**: on **402**, the client signs and retries. No key is required for quotes.
+
+```python
+from readfetch_client import (
+    payment_config,
+    quote,
+    call_with_meta,
+    x402_http_client,
+)
+
+print(payment_config())  # base_url, network, max_payment_usd, buyer_address, signing_ready
+
+q = await quote("text", {"url": "https://example.com"})  # 402 + payment_required
+
+meta = await call_with_meta("text", {"url": "https://example.com"})
+# meta["data"], meta["request_id"], meta["payment"] (receipt, payment_response, …)
+
+async with x402_http_client() as http:
+    ...
+```
+
+`pay(name, body)` aliases `call()` for paid endpoints.
+
+## Environment
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `EVM_PRIVATE_KEY` / `X402_BUYER_KEY` | — | Required before paid calls |
+| `READFETCH_BASE_URL` | `https://readfetch.com` | Production host only unless dev |
+| `READFETCH_MAX_PAYMENT_USD` | `1` | Per-payment spend cap |
+| `READFETCH_DEV=1` | off | Allow local base URL for integration tests |
+
+MCP: [@readfetch/mcp-x402-proxy](https://github.com/readfetch/mcp-x402-proxy). Feedback: [docs#feedback](https://readfetch.com/docs#feedback).

readfetch_client-0.1.11.dist-info/RECORD

@@ -0,0 +1,10 @@
+readfetch_client/__init__.py,sha256=fKvq2YvObqgpF6SsYYhKVqyIggjtZqWngtnpsXoiYgA,1231
+readfetch_client/client.py,sha256=3mjgJSH7VD1znZKn4p4M89R2rB9Ok2bVXBweXLDkSPU,9104
+readfetch_client/config.py,sha256=vYnZLN-x2AHfUoH4qRyX4HqJQBlyF7M-N6pSPbs_aC8,5129
+readfetch_client/endpoints.py,sha256=YBNOqSVpBuQ58CRWBdDge8g-uGNRAY01u8DG8BVUDj4,2695
+readfetch_client/feedback_validation.py,sha256=zorLvLX0AfHtu83z_knpfwtjw4XyRWACQlWDIs0UfeY,823
+readfetch_client/http_json.py,sha256=31wamfukcPWH5sFIM1ATUpYZQCulva6Y3PFAcO42Zk0,1303
+readfetch_client/payment.py,sha256=_PQspdrRIuyoBDBgJy25tDbcx_hjVdr4ahL1_Kf3x7M,841
+readfetch_client-0.1.11.dist-info/METADATA,sha256=8NtMdVotn_vls4H98y3S-yjWHAuQOvH5Bxl92YkFEkc,2972
+readfetch_client-0.1.11.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+readfetch_client-0.1.11.dist-info/RECORD,,

readfetch_client-0.1.11.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any