repsapi 0.1.0__py3-none-any.whl

repsapi/_client.py

@@ -0,0 +1,769 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import math
+import os
+import random
+import re
+import time
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+from typing import Any, Callable, Dict, List, Literal, Mapping, Optional, Sequence, Tuple, Union, cast, overload
+from urllib.parse import urlsplit
+
+import httpx
+
+from ._errors import (
+    APIConnectionError,
+    APIError,
+    APITimeoutError,
+    AuthenticationError,
+    BadRequestError,
+    InternalServerError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    RepsApiError,
+    UnprocessableEntityError,
+)
+from ._version import __version__
+from .types import (
+    Agent,
+    ChangelogResponse,
+    ConvertResponse,
+    Dimensions,
+    HaulItemInput,
+    HaulResponse,
+    HealthResponse,
+    LocalizedChangelogResponse,
+    LookupResponse,
+    Platform,
+    QcResponse,
+    RatesResponse,
+    ShippingCountriesResponse,
+    ShippingEstimateResponse,
+    TrackingResponse,
+    UsageResponse,
+)
+
+__all__ = ["RepsApi", "AsyncRepsApi", "RateLimitInfo", "AGENTS", "DEFAULT_BASE_URL"]
+
+DEFAULT_BASE_URL = "https://repsapi.pl/v1"
+DEFAULT_TIMEOUT = 60.0
+# hauls and link-based shipping estimates look up every item first
+SLOW_TIMEOUT = 180.0
+DEFAULT_MAX_RETRIES = 2
+# a 429 asking us to wait longer than this (e.g. the daily quota) raises at once
+DEFAULT_MAX_RETRY_WAIT = 60.0
+
+#: Every agent ``convert()`` builds links for, in the API's order.
+AGENTS: Tuple[Agent, ...] = (
+    "kakobuy", "cnfans", "acbuy", "mulebuy", "hoobuy", "oopbuy", "cnshopper", "ootdbuy",
+    "ponybuy", "superbuy", "sugargoo", "loongbuy", "cssbuy", "usfans", "litbuy",
+)
+
+_USER_AGENT = f"repsapi-python/{__version__}"
+_KEY_CHARS = re.compile(r"[\x21-\x7e]+")
+_LOCAL_HOSTS = {"localhost", "127.0.0.1", "::1"}
+_RETRY_STATUSES = {500, 502, 503, 504}
+_NOT_JSON = object()
+
+
+@dataclass(frozen=True)
+class RateLimitInfo:
+    """Per-minute limit from the last response that carried one."""
+
+    limit: int
+    remaining: int
+    reset: datetime
+
+
+@dataclass
+class _Call:
+    method: str
+    path: str
+    query: Optional[Dict[str, Any]] = None
+    body: Optional[Dict[str, Any]] = None
+    # send the API key (public endpoints never get it)
+    auth: bool = True
+    default_timeout: Optional[float] = None
+    # error answers to hand back anyway (health while the API is down)
+    accept: Optional[Callable[[int, Any], bool]] = None
+
+
+# --------------------------------------------------------------------------
+# validation helpers
+# --------------------------------------------------------------------------
+
+def _clean_key(key: Any) -> Optional[str]:
+    if key is None:
+        return None
+    if not isinstance(key, str):
+        raise RepsApiError("api_key must be a string.")
+    cleaned: str = key.strip()
+    if not cleaned:
+        return None
+    if not _KEY_CHARS.fullmatch(cleaned):
+        raise RepsApiError("api_key contains spaces, line breaks or other invalid characters. Copy it again from the dashboard.")
+    return cleaned
+
+
+def _clean_base_url(raw: Any) -> str:
+    if not isinstance(raw, str):
+        raise RepsApiError("base_url must be a string.")
+    try:
+        parts = urlsplit(raw.strip())
+        host = parts.hostname or ""
+        _ = parts.port  # raises on a malformed port
+    except ValueError:
+        raise RepsApiError(f"base_url is not a valid URL: {raw}") from None
+    if not parts.netloc:
+        raise RepsApiError(f"base_url is not a valid URL: {raw}")
+    if not (parts.scheme == "https" or (parts.scheme == "http" and host in _LOCAL_HOSTS)):
+        raise RepsApiError(
+            "base_url must start with https:// so your API key is never sent unencrypted "
+            "(http:// is only allowed for localhost)."
+        )
+    if parts.username or parts.password or parts.query or parts.fragment:
+        raise RepsApiError("base_url must not contain credentials, a query string or a fragment.")
+    return f"{parts.scheme}://{parts.netloc}{parts.path.rstrip('/')}"
+
+
+def _non_negative(value: Any, name: str) -> float:
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value) or value < 0:
+        raise RepsApiError(f"{name} must be a non-negative number.")
+    return float(value)
+
+
+def _timeout(value: Any) -> float:
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value) or value <= 0:
+        raise RepsApiError("timeout must be a positive number of seconds.")
+    return float(value)
+
+
+def _text(value: Any, what: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise RepsApiError(f"{what} must be a non-empty string.")
+    return value.strip()
+
+
+def _item_query(url: Optional[str], platform: Optional[str], id: Optional[Union[str, int]], method: str) -> Dict[str, Any]:
+    if url is not None:
+        if platform is not None or id is not None:
+            raise RepsApiError(f"{method}(): pass either a product link or platform and id, not both.")
+        return {"url": _text(url, f"{method}(): the product link")}
+    if platform is None or id is None:
+        raise RepsApiError(f"{method}(): pass a product link, or platform and id.")
+    return {"platform": _text(platform, f"{method}(): platform"), "id": _text(str(id), f"{method}(): id")}
+
+
+def _flags(body: Dict[str, Any], **flags: Any) -> None:
+    for name, value in flags.items():
+        if value is not None:
+            body[name] = value
+
+
+def _retry_after(value: Optional[str]) -> Optional[float]:
+    if not value:
+        return None
+    try:
+        seconds = float(value)
+        return seconds if math.isfinite(seconds) and seconds >= 0 else None
+    except ValueError:
+        pass
+    try:
+        at = parsedate_to_datetime(value)
+    except (TypeError, ValueError, IndexError):
+        return None
+    if at.tzinfo is None:
+        at = at.replace(tzinfo=timezone.utc)
+    return max(0.0, (at - datetime.now(timezone.utc)).total_seconds())
+
+
+def _backoff(attempt: int) -> float:
+    """0.5 s, 1 s, 2 s ... (max 8 s) with jitter"""
+    return min(8.0, 0.5 * 2.0 ** attempt) * (0.75 + random.random() * 0.5)
+
+
+def _to_error(status: int, data: Any, text: str, headers: httpx.Headers) -> APIError:
+    type_ = "server_error" if status >= 500 else "error"
+    message = f"The API answered {status}. Try again in a moment." if status >= 500 else f"HTTP {status}"
+    details: Dict[str, Any] = {}
+    if isinstance(data, dict):
+        # fields next to "error" too, e.g. the resolved items of a failed shipping estimate
+        siblings = {k: v for k, v in data.items() if k != "error"}
+        err = data.get("error")
+        if isinstance(err, dict):
+            if isinstance(err.get("type"), str):
+                type_ = err["type"]
+            if isinstance(err.get("message"), str):
+                message = err["message"]
+            details = {**siblings, **{k: v for k, v in err.items() if k not in ("type", "message")}}
+        elif isinstance(err, str):
+            # request-body validation: {"error": "Invalid request body.", "fields": {...}}
+            message = err
+            type_ = {413: "payload_too_large", 415: "unsupported_media_type"}.get(status, "bad_request")
+            details = siblings
+    body = text[:2000] if data is _NOT_JSON else data
+
+    if status == 429:
+        return RateLimitError(status, type_, message, details, body, _retry_after(headers.get("retry-after")))
+    cls = {
+        401: AuthenticationError,
+        403: PermissionDeniedError,
+        404: NotFoundError,
+        422: UnprocessableEntityError,
+    }.get(status, InternalServerError if status >= 500 else BadRequestError)
+    return cls(status, type_, message, details, body)
+
+
+# --------------------------------------------------------------------------
+# request builders, shared by the sync and async clients
+# --------------------------------------------------------------------------
+
+def _tracking(tracking_number: str) -> _Call:
+    return _Call("GET", "/tracking", {"num": _text(tracking_number, "tracking(): the tracking number")})
+
+
+def _qc(url: Optional[str], platform: Optional[str], id: Optional[Union[str, int]]) -> _Call:
+    return _Call("GET", "/qc", _item_query(url, platform, id, "qc"))
+
+
+def _lookup(url: Optional[str], platform: Optional[str], id: Optional[Union[str, int]], currency: Optional[str], agent: Optional[str]) -> _Call:
+    return _Call("GET", "/lookup", {**_item_query(url, platform, id, "lookup"), "currency": currency, "agent": agent})
+
+
+def _convert(url: str, agents: Optional[Union[str, Sequence[str]]]) -> _Call:
+    query: Dict[str, Any] = {"url": _text(url, "convert(): the product link")}
+    if agents is not None:
+        names = [a.strip() for a in agents.split(",")] if isinstance(agents, str) else list(agents)
+        if not names or not all(isinstance(a, str) and a for a in names):
+            raise RepsApiError("convert(): agents must be a non-empty list of agent names, or None for all agents.")
+        query["agents"] = ",".join(names)
+    return _Call("GET", "/convert", query)
+
+
+def _shipping_estimate(
+    country: str,
+    weight: Optional[float],
+    dimensions: Optional[Mapping[str, object]],
+    urls: Optional[Union[str, Sequence[str]]],
+    currency: Optional[str],
+    battery: Optional[bool],
+    brands: Optional[bool],
+    liquids: Optional[bool],
+) -> _Call:
+    body: Dict[str, Any] = {"country": _text(country, "shipping_estimate(): country")}
+    if weight is not None:
+        body["weight"] = weight
+    if dimensions is not None:
+        if not isinstance(dimensions, Mapping):
+            raise RepsApiError('shipping_estimate(): dimensions must be {"length": ..., "width": ..., "height": ...} in cm.')
+        for side in ("length", "width", "height"):
+            body[side] = dimensions.get(side)
+    link_list = [urls] if isinstance(urls, str) else list(urls or [])
+    if link_list:
+        body["urls"] = link_list
+    _flags(body, currency=currency, battery=battery, brands=brands, liquids=liquids)
+    return _Call("POST", "/shipping/estimate", body=body, default_timeout=SLOW_TIMEOUT if link_list else None)
+
+
+def _haul(
+    items: Sequence[HaulItemInput],
+    country: str,
+    currency: Optional[str],
+    battery: Optional[bool],
+    brands: Optional[bool],
+    liquids: Optional[bool],
+) -> _Call:
+    if isinstance(items, (str, bytes)) or not isinstance(items, Sequence) or not items:
+        raise RepsApiError('haul() expects items=[{"url": ..., "quantity": ...}, ...].')
+    clean: List[Dict[str, Any]] = []
+    for i, item in enumerate(items):
+        if not isinstance(item, Mapping):
+            raise RepsApiError(f'haul(): items[{i}] must be {{"url": ..., "quantity": ...}}.')
+        entry: Dict[str, Any] = {"url": _text(item.get("url"), f"haul(): items[{i}]['url']")}
+        if item.get("quantity") is not None:
+            entry["quantity"] = item["quantity"]
+        clean.append(entry)
+    body: Dict[str, Any] = {"items": clean, "country": _text(country, "haul(): country")}
+    _flags(body, currency=currency, battery=battery, brands=brands, liquids=liquids)
+    return _Call("POST", "/haul", body=body, default_timeout=SLOW_TIMEOUT)
+
+
+def _health(days: Optional[int]) -> _Call:
+    return _Call(
+        "GET",
+        "/health",
+        {"days": days},
+        auth=False,
+        accept=lambda status, data: status == 503 and isinstance(data, dict) and isinstance(data.get("services"), dict),
+    )
+
+
+# --------------------------------------------------------------------------
+# shared client core
+# --------------------------------------------------------------------------
+
+class _BaseClient:
+    def __init__(
+        self,
+        api_key: Optional[str],
+        base_url: str,
+        timeout: Optional[float],
+        max_retries: int,
+        max_retry_wait: float,
+    ) -> None:
+        self._api_key = _clean_key(api_key if api_key is not None else os.environ.get("REPSAPI_KEY"))
+        self.base_url = _clean_base_url(base_url)
+        self.timeout = None if timeout is None else _timeout(timeout)
+        self.max_retries = int(_non_negative(max_retries, "max_retries"))
+        self.max_retry_wait = _non_negative(max_retry_wait, "max_retry_wait")
+        self._rate_limit: Optional[RateLimitInfo] = None
+
+    def __repr__(self) -> str:
+        # never print the key
+        return f"{type(self).__name__}(base_url={self.base_url!r}, api_key={'***' if self._api_key else None})"
+
+    @property
+    def rate_limit(self) -> Optional[RateLimitInfo]:
+        """Per-minute limit from the last response that carried one (None on plans without it)."""
+        return self._rate_limit
+
+    def _prepare(self, call: _Call, timeout: Optional[float], max_retries: Optional[int]) -> Dict[str, Any]:
+        if call.auth and not self._api_key:
+            raise RepsApiError("Missing API key. Pass it to RepsApi(api_key=...) or set the REPSAPI_KEY environment variable.")
+        headers = {"Accept": "application/json", "User-Agent": _USER_AGENT}
+        if call.auth:
+            headers["Authorization"] = f"Bearer {self._api_key}"
+        content: Optional[bytes] = None
+        if call.body is not None:
+            headers["Content-Type"] = "application/json"
+            try:
+                content = json.dumps(call.body, allow_nan=False, ensure_ascii=False).encode("utf-8")
+            except (TypeError, ValueError) as exc:
+                raise RepsApiError(f"The request can't be sent as JSON: {exc}") from None
+        params = {k: str(v) for k, v in (call.query or {}).items() if v is not None and v != ""}
+        seconds = _timeout(timeout) if timeout is not None else (self.timeout or call.default_timeout or DEFAULT_TIMEOUT)
+        retries = self.max_retries if max_retries is None else int(_non_negative(max_retries, "max_retries"))
+        return {
+            "request": {
+                "method": call.method,
+                "url": self.base_url + call.path,
+                "params": params,
+                "headers": headers,
+                "content": content,
+                "timeout": httpx.Timeout(seconds),
+                # never follow redirects: the Authorization header must not travel to another host
+                "follow_redirects": False,
+            },
+            "seconds": seconds,
+            "retries": retries,
+        }
+
+    def _handle(self, response: httpx.Response, call: _Call) -> Tuple[Optional[Dict[str, Any]], Optional[APIError]]:
+        self._remember_rate_limit(response.headers)
+        status = response.status_code
+        if 300 <= status < 400:
+            return None, APIError(
+                status,
+                "unexpected_redirect",
+                "The API answered with a redirect, which this client never follows so your key stays on repsapi.pl. Check base_url.",
+            )
+        text = response.text
+        try:
+            data: Any = json.loads(text) if text else _NOT_JSON
+        except ValueError:
+            data = _NOT_JSON
+        if 200 <= status < 300 or (call.accept is not None and call.accept(status, data)):
+            if not isinstance(data, dict):
+                return None, APIError(status, "invalid_response", "The API sent a response that isn't JSON.", {}, text[:2000])
+            return data, None
+        return None, _to_error(status, data, text, response.headers)
+
+    def _retry_wait(self, error: APIError, attempt: int) -> Optional[float]:
+        if isinstance(error, RateLimitError):
+            if error.retry_after is None:
+                return _backoff(attempt)
+            return error.retry_after + random.random() * 0.25 if error.retry_after <= self.max_retry_wait else None
+        if error.status in _RETRY_STATUSES:
+            return _backoff(attempt)
+        return None
+
+    def _remember_rate_limit(self, headers: httpx.Headers) -> None:
+        try:
+            limit = int(headers["x-ratelimit-limit"])
+            remaining = int(headers["x-ratelimit-remaining"])
+            reset = datetime.fromtimestamp(int(headers["x-ratelimit-reset"]), tz=timezone.utc)
+        except (KeyError, ValueError, OverflowError, OSError):
+            return
+        self._rate_limit = RateLimitInfo(limit, remaining, reset)
+
+
+# --------------------------------------------------------------------------
+# sync client
+# --------------------------------------------------------------------------
+
+class RepsApi(_BaseClient):
+    """RepsApi.pl client.
+
+    >>> api = RepsApi()  # reads REPSAPI_KEY
+    >>> parcel = api.tracking("YT2530998211074512")
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: Optional[float] = None,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        max_retry_wait: float = DEFAULT_MAX_RETRY_WAIT,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        """
+        :param api_key: your key (rk_live_...); defaults to the REPSAPI_KEY environment variable
+        :param base_url: defaults to https://repsapi.pl/v1
+        :param timeout: seconds per attempt (default 60; hauls 180)
+        :param max_retries: retries after a network error, a 5xx or a short 429 (default 2)
+        :param max_retry_wait: longest Retry-After (seconds) a 429 may ask for before we raise instead of waiting
+        :param http_client: your own httpx.Client (proxies, custom TLS); you close it yourself
+        """
+        super().__init__(api_key, base_url, timeout, max_retries, max_retry_wait)
+        self._owns_client = http_client is None
+        self._client = http_client if http_client is not None else httpx.Client()
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> "RepsApi":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def _request(self, call: _Call, timeout: Optional[float], max_retries: Optional[int]) -> Dict[str, Any]:
+        prepared = self._prepare(call, timeout, max_retries)
+        attempt = 0
+        while True:
+            try:
+                response = self._client.request(**prepared["request"])
+            except httpx.TimeoutException as exc:
+                if attempt >= prepared["retries"]:
+                    raise APITimeoutError(f"No response from the API within {prepared['seconds']:g} s.") from exc
+            except httpx.TransportError as exc:
+                if attempt >= prepared["retries"]:
+                    raise APIConnectionError("Could not reach the API. Check your connection.") from exc
+            else:
+                data, error = self._handle(response, call)
+                if error is None:
+                    return cast(Dict[str, Any], data)
+                wait = self._retry_wait(error, attempt) if attempt < prepared["retries"] else None
+                if wait is None:
+                    raise error
+                time.sleep(wait)
+                attempt += 1
+                continue
+            time.sleep(_backoff(attempt))
+            attempt += 1
+
+    # ------------------------------ endpoints ------------------------------
+
+    def tracking(self, tracking_number: str, *, timeout: Optional[float] = None, max_retries: Optional[int] = None) -> TrackingResponse:
+        """Where is my parcel? Merged events from forwarders and last-mile carriers."""
+        return cast(TrackingResponse, self._request(_tracking(tracking_number), timeout, max_retries))
+
+    def qc(
+        self,
+        url: Optional[str] = None,
+        *,
+        platform: Optional[Platform] = None,
+        id: Optional[Union[str, int]] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+    ) -> QcResponse:
+        """Warehouse QC photos for a product: a link, or platform + id."""
+        return cast(QcResponse, self._request(_qc(url, platform, id), timeout, max_retries))
+
+    def lookup(
+        self,
+        url: Optional[str] = None,
+        *,
+        platform: Optional[Platform] = None,
+        id: Optional[Union[str, int]] = None,
+        currency: Optional[str] = None,
+        agent: Optional[Agent] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+    ) -> LookupResponse:
+        """Everything about a product. ``currency`` adds prices in e.g. PLN, EUR or USD."""
+        return cast(LookupResponse, self._request(_lookup(url, platform, id, currency, agent), timeout, max_retries))
+
+    def convert(
+        self,
+        url: str,
+        *,
+        agents: Optional[Sequence[Agent]] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+    ) -> ConvertResponse:
+        """The same product as a link on every agent (or only ``agents``)."""
+        return cast(ConvertResponse, self._request(_convert(url, agents), timeout, max_retries))
+
+    def shipping_estimate(
+        self,
+        country: str,
+        *,
+        weight: Optional[float] = None,
+        dimensions: Optional[Dimensions] = None,
+        urls: Optional[Sequence[str]] = None,
+        currency: Optional[str] = None,
+        battery: Optional[bool] = None,
+        brands: Optional[bool] = None,
+        liquids: Optional[bool] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+    ) -> ShippingEstimateResponse:
+        """Shipping lines for a parcel: ``weight`` in grams, or up to 10 product ``urls``."""
+        call = _shipping_estimate(country, weight, dimensions, urls, currency, battery, brands, liquids)
+        return cast(ShippingEstimateResponse, self._request(call, timeout, max_retries))
+
+    def shipping_countries(self, *, timeout: Optional[float] = None, max_retries: Optional[int] = None) -> ShippingCountriesResponse:
+        """Destination countries for shipping estimates and hauls (no key needed)."""
+        call = _Call("GET", "/shipping/countries", auth=False)
+        return cast(ShippingCountriesResponse, self._request(call, timeout, max_retries))
+
+    def haul(
+        self,
+        items: Sequence[HaulItemInput],
+        country: str,
+        *,
+        currency: Optional[str] = None,
+        battery: Optional[bool] = None,
+        brands: Optional[bool] = None,
+        liquids: Optional[bool] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+    ) -> HaulResponse:
+        """A whole haul: per-item prices and weights, totals and every shipping line."""
+        call = _haul(items, country, currency, battery, brands, liquids)
+        return cast(HaulResponse, self._request(call, timeout, max_retries))
+
+    def usage(self, *, timeout: Optional[float] = None, max_retries: Optional[int] = None) -> UsageResponse:
+        """Your plan, today's usage and the remaining quota (doesn't count toward it)."""
+        return cast(UsageResponse, self._request(_Call("GET", "/usage"), timeout, max_retries))
+
+    def rates(self, base: str = "CNY", *, timeout: Optional[float] = None, max_retries: Optional[int] = None) -> RatesResponse:
+        """Exchange rates (no key needed)."""
+        call = _Call("GET", "/rates", {"base": _text(base, "rates(): base")}, auth=False)
+        return cast(RatesResponse, self._request(call, timeout, max_retries))
+
+    def health(self, *, days: Optional[int] = None, timeout: Optional[float] = None, max_retries: Optional[int] = None) -> HealthResponse:
+        """API status (no key needed). Also returned, not raised, while the API is down."""
+        return cast(HealthResponse, self._request(_health(days), timeout, max_retries))
+
+    @overload
+    def changelog(
+        self, *, limit: Optional[int] = None, lang: None = None, timeout: Optional[float] = None, max_retries: Optional[int] = None
+    ) -> ChangelogResponse: ...
+
+    @overload
+    def changelog(
+        self, *, limit: Optional[int] = None, lang: Literal["en", "pl"], timeout: Optional[float] = None, max_retries: Optional[int] = None
+    ) -> LocalizedChangelogResponse: ...
+
+    def changelog(
+        self,
+        *,
+        limit: Optional[int] = None,
+        lang: Optional[Literal["en", "pl"]] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+    ) -> Union[ChangelogResponse, LocalizedChangelogResponse]:
+        """Release notes (no key needed)."""
+        call = _Call("GET", "/changelog", {"limit": limit, "lang": lang}, auth=False)
+        return cast(ChangelogResponse, self._request(call, timeout, max_retries))
+
+
+# --------------------------------------------------------------------------
+# async client
+# --------------------------------------------------------------------------
+
+class AsyncRepsApi(_BaseClient):
+    """Async RepsApi.pl client (for discord.py, FastAPI, aiohttp apps ...).
+
+    >>> async with AsyncRepsApi() as api:
+    ...     parcel = await api.tracking("YT2530998211074512")
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: Optional[float] = None,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        max_retry_wait: float = DEFAULT_MAX_RETRY_WAIT,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        """Same options as :class:`RepsApi`; ``http_client`` is an httpx.AsyncClient."""
+        super().__init__(api_key, base_url, timeout, max_retries, max_retry_wait)
+        self._owns_client = http_client is None
+        self._client = http_client if http_client is not None else httpx.AsyncClient()
+
+    async def close(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncRepsApi":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.close()
+
+    async def _request(self, call: _Call, timeout: Optional[float], max_retries: Optional[int]) -> Dict[str, Any]:
+        prepared = self._prepare(call, timeout, max_retries)
+        attempt = 0
+        while True:
+            try:
+                response = await self._client.request(**prepared["request"])
+            except httpx.TimeoutException as exc:
+                if attempt >= prepared["retries"]:
+                    raise APITimeoutError(f"No response from the API within {prepared['seconds']:g} s.") from exc
+            except httpx.TransportError as exc:
+                if attempt >= prepared["retries"]:
+                    raise APIConnectionError("Could not reach the API. Check your connection.") from exc
+            else:
+                data, error = self._handle(response, call)
+                if error is None:
+                    return cast(Dict[str, Any], data)
+                wait = self._retry_wait(error, attempt) if attempt < prepared["retries"] else None
+                if wait is None:
+                    raise error
+                await asyncio.sleep(wait)
+                attempt += 1
+                continue
+            await asyncio.sleep(_backoff(attempt))
+            attempt += 1
+
+    # ------------------------------ endpoints ------------------------------
+
+    async def tracking(self, tracking_number: str, *, timeout: Optional[float] = None, max_retries: Optional[int] = None) -> TrackingResponse:
+        """Where is my parcel? Merged events from forwarders and last-mile carriers."""
+        return cast(TrackingResponse, await self._request(_tracking(tracking_number), timeout, max_retries))
+
+    async def qc(
+        self,
+        url: Optional[str] = None,
+        *,
+        platform: Optional[Platform] = None,
+        id: Optional[Union[str, int]] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+    ) -> QcResponse:
+        """Warehouse QC photos for a product: a link, or platform + id."""
+        return cast(QcResponse, await self._request(_qc(url, platform, id), timeout, max_retries))
+
+    async def lookup(
+        self,
+        url: Optional[str] = None,
+        *,
+        platform: Optional[Platform] = None,
+        id: Optional[Union[str, int]] = None,
+        currency: Optional[str] = None,
+        agent: Optional[Agent] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+    ) -> LookupResponse:
+        """Everything about a product. ``currency`` adds prices in e.g. PLN, EUR or USD."""
+        return cast(LookupResponse, await self._request(_lookup(url, platform, id, currency, agent), timeout, max_retries))
+
+    async def convert(
+        self,
+        url: str,
+        *,
+        agents: Optional[Sequence[Agent]] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+    ) -> ConvertResponse:
+        """The same product as a link on every agent (or only ``agents``)."""
+        return cast(ConvertResponse, await self._request(_convert(url, agents), timeout, max_retries))
+
+    async def shipping_estimate(
+        self,
+        country: str,
+        *,
+        weight: Optional[float] = None,
+        dimensions: Optional[Dimensions] = None,
+        urls: Optional[Sequence[str]] = None,
+        currency: Optional[str] = None,
+        battery: Optional[bool] = None,
+        brands: Optional[bool] = None,
+        liquids: Optional[bool] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+    ) -> ShippingEstimateResponse:
+        """Shipping lines for a parcel: ``weight`` in grams, or up to 10 product ``urls``."""
+        call = _shipping_estimate(country, weight, dimensions, urls, currency, battery, brands, liquids)
+        return cast(ShippingEstimateResponse, await self._request(call, timeout, max_retries))
+
+    async def shipping_countries(self, *, timeout: Optional[float] = None, max_retries: Optional[int] = None) -> ShippingCountriesResponse:
+        """Destination countries for shipping estimates and hauls (no key needed)."""
+        call = _Call("GET", "/shipping/countries", auth=False)
+        return cast(ShippingCountriesResponse, await self._request(call, timeout, max_retries))
+
+    async def haul(
+        self,
+        items: Sequence[HaulItemInput],
+        country: str,
+        *,
+        currency: Optional[str] = None,
+        battery: Optional[bool] = None,
+        brands: Optional[bool] = None,
+        liquids: Optional[bool] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+    ) -> HaulResponse:
+        """A whole haul: per-item prices and weights, totals and every shipping line."""
+        call = _haul(items, country, currency, battery, brands, liquids)
+        return cast(HaulResponse, await self._request(call, timeout, max_retries))
+
+    async def usage(self, *, timeout: Optional[float] = None, max_retries: Optional[int] = None) -> UsageResponse:
+        """Your plan, today's usage and the remaining quota (doesn't count toward it)."""
+        return cast(UsageResponse, await self._request(_Call("GET", "/usage"), timeout, max_retries))
+
+    async def rates(self, base: str = "CNY", *, timeout: Optional[float] = None, max_retries: Optional[int] = None) -> RatesResponse:
+        """Exchange rates (no key needed)."""
+        call = _Call("GET", "/rates", {"base": _text(base, "rates(): base")}, auth=False)
+        return cast(RatesResponse, await self._request(call, timeout, max_retries))
+
+    async def health(
+        self, *, days: Optional[int] = None, timeout: Optional[float] = None, max_retries: Optional[int] = None
+    ) -> HealthResponse:
+        """API status (no key needed). Also returned, not raised, while the API is down."""
+        return cast(HealthResponse, await self._request(_health(days), timeout, max_retries))
+
+    @overload
+    async def changelog(
+        self, *, limit: Optional[int] = None, lang: None = None, timeout: Optional[float] = None, max_retries: Optional[int] = None
+    ) -> ChangelogResponse: ...
+
+    @overload
+    async def changelog(
+        self, *, limit: Optional[int] = None, lang: Literal["en", "pl"], timeout: Optional[float] = None, max_retries: Optional[int] = None
+    ) -> LocalizedChangelogResponse: ...
+
+    async def changelog(
+        self,
+        *,
+        limit: Optional[int] = None,
+        lang: Optional[Literal["en", "pl"]] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+    ) -> Union[ChangelogResponse, LocalizedChangelogResponse]:
+        """Release notes (no key needed)."""
+        call = _Call("GET", "/changelog", {"limit": limit, "lang": lang}, auth=False)
+        return cast(ChangelogResponse, await self._request(call, timeout, max_retries))