nonecap 0.1.0__py3-none-any.whl

nonecap/__init__.py

@@ -0,0 +1,66 @@
+"""Official Python client for the NoneCap hCaptcha solving API.
+
+>>> from nonecap import NoneCap
+>>> nc = NoneCap(api_key="nc_live_...")
+>>> solve = nc.solve(type="hcaptcha", sitekey="...", url="https://example.com")
+>>> solve.token
+'P1_...'
+"""
+
+from ._client import AsyncNoneCap, NoneCap
+from ._errors import (
+    APIConnectionError,
+    APIError,
+    APITimeoutError,
+    AuthenticationError,
+    ConflictError,
+    InsufficientCreditsError,
+    NoneCapError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    SolveFailedError,
+    SolveTimeoutError,
+    ValidationError,
+)
+from ._types import (
+    TERMINAL_STATUSES,
+    Account,
+    Proxy,
+    Solve,
+    SolveError,
+    SolvePage,
+    SolveStatus,
+    SolveType,
+)
+from ._version import __version__
+
+__all__ = [
+    "__version__",
+    # clients
+    "NoneCap",
+    "AsyncNoneCap",
+    # types
+    "Solve",
+    "SolveError",
+    "SolvePage",
+    "Account",
+    "Proxy",
+    "SolveType",
+    "SolveStatus",
+    "TERMINAL_STATUSES",
+    # errors
+    "NoneCapError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "InsufficientCreditsError",
+    "ValidationError",
+    "NotFoundError",
+    "ConflictError",
+    "RateLimitError",
+    "APIError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "SolveFailedError",
+    "SolveTimeoutError",
+]

nonecap/_client.py

@@ -0,0 +1,696 @@
+"""Sync and async clients for the NoneCap API.
+
+Both clients expose the same surface:
+
+- ``client.solve(...)`` — submit a captcha and wait for the token (the
+  convenient path; long-polls under the hood).
+- ``client.solves.create / retrieve / cancel / list / list_all`` — the raw
+  resource methods, mapping one to one to the REST API.
+- ``client.me()`` — account info and credit balance.
+
+``rqdata`` is required for ``type="hcaptcha_enterprise"`` and optional for
+``type="hcaptcha"``; the ``@overload`` signatures enforce that in mypy and
+pyright, and a runtime check backs it up for untyped callers.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import AsyncIterator, Iterator
+from typing import (
+    Any,
+    Literal,
+    Optional,
+    Union,
+    overload,
+)
+
+import httpx
+
+from ._errors import (
+    APIConnectionError,
+    APIError,
+    APITimeoutError,
+    SolveFailedError,
+    SolveTimeoutError,
+    ValidationError,
+    error_from_response,
+)
+from ._types import Account, Proxy, Solve, SolvePage, SolveStatus, SolveType
+from ._version import __version__
+
+DEFAULT_BASE_URL = "https://api.nonecap.com"
+DEFAULT_REQUEST_TIMEOUT = 100.0
+"""Per-request timeout (seconds): just above the API's 90s long-poll window."""
+DEFAULT_SOLVE_TIMEOUT = 180.0
+"""Default overall budget (seconds) for the ``solve()`` helper."""
+_MAX_WAIT_SECONDS = 90
+"""The API caps server-side long-poll at 90 seconds."""
+
+_USER_AGENT = f"nonecap-python/{__version__}"
+
+
+def _wait_seconds(deadline: float) -> int:
+    """The ``wait`` value for the next long-poll: whole seconds until
+    ``deadline``, clamped to the server's 1-90 window. The floor of 1 keeps
+    the param valid, so callers must decide whether the deadline has passed
+    with the clock, not with this return value."""
+    remaining = int(deadline - time.monotonic()) + 1
+    return max(1, min(_MAX_WAIT_SECONDS, remaining))
+
+
+def _request_timeout_for_wait(wait: Optional[int], default: float) -> float:
+    """Give the socket a margin beyond the server's long-poll window."""
+    if wait is None:
+        return default
+    return float(wait) + 15.0
+
+
+def _build_solve_body(
+    *,
+    type: SolveType,
+    sitekey: str,
+    url: str,
+    rqdata: Optional[str],
+    user_agent: Optional[str],
+    proxy: Union[Proxy, str, None],
+    webhook_url: Optional[str],
+) -> dict[str, Any]:
+    if type == "hcaptcha_enterprise" and not rqdata:
+        raise ValidationError(
+            "rqdata is required for hcaptcha_enterprise solves.",
+            code="validation_error",
+            param="rqdata",
+        )
+    body: dict[str, Any] = {"type": type, "sitekey": sitekey, "url": url}
+    if rqdata is not None:
+        body["rqdata"] = rqdata
+    if user_agent is not None:
+        body["user_agent"] = user_agent
+    if proxy is not None:
+        body["proxy"] = proxy
+    if webhook_url is not None:
+        body["webhook_url"] = webhook_url
+    return body
+
+
+def _list_params(
+    *,
+    limit: Optional[int],
+    starting_after: Optional[str],
+    status: Optional[SolveStatus],
+    type: Optional[SolveType],
+) -> dict[str, Any]:
+    params: dict[str, Any] = {}
+    if limit is not None:
+        params["limit"] = limit
+    if starting_after is not None:
+        params["starting_after"] = starting_after
+    if status is not None:
+        params["status"] = status
+    if type is not None:
+        params["type"] = type
+    return params
+
+
+def _process_response(response: httpx.Response) -> Any:
+    """Parse a response, mapping non-2xx envelopes to typed errors.
+
+    202 is a success here: the API returns it for a solve that is still
+    pending/solving, with the solve resource as the body.
+    """
+    try:
+        payload = response.json() if response.content else None
+    except ValueError:
+        raise APIError(
+            f"Unexpected non-JSON response (HTTP {response.status_code}): "
+            f"{response.text[:200]}",
+            status=response.status_code,
+        ) from None
+
+    if response.status_code < 400:
+        return payload
+
+    error = (payload or {}).get("error") if isinstance(payload, dict) else None
+    error = error if isinstance(error, dict) else {}
+    raise error_from_response(
+        response.status_code,
+        error.get("code"),
+        error.get("message") or f"HTTP {response.status_code}",
+        error.get("param"),
+    )
+
+
+class _BaseClient:
+    def __init__(self, *, api_key: str, base_url: Optional[str], timeout: float) -> None:
+        if not api_key:
+            raise ValueError(
+                "A NoneCap API key is required. Pass it as NoneCap(api_key=...)."
+            )
+        self._api_key = api_key
+        self._base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self._timeout = timeout
+
+    def _url(self, path: str) -> str:
+        return self._base_url + path
+
+    @property
+    def _headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self._api_key}",
+            "Accept": "application/json",
+            "User-Agent": _USER_AGENT,
+        }
+
+
+# ---------------------------------------------------------------------------
+# Sync
+# ---------------------------------------------------------------------------
+
+
+class Solves:
+    """Operations on solves (sync). Reached as ``client.solves``."""
+
+    def __init__(self, client: NoneCap) -> None:
+        self._client = client
+
+    @overload
+    def create(
+        self,
+        *,
+        type: Literal["hcaptcha"],
+        sitekey: str,
+        url: str,
+        rqdata: Optional[str] = None,
+        user_agent: Optional[str] = None,
+        proxy: Union[Proxy, str, None] = None,
+        webhook_url: Optional[str] = None,
+        wait: Optional[int] = None,
+    ) -> Solve: ...
+
+    @overload
+    def create(
+        self,
+        *,
+        type: Literal["hcaptcha_enterprise"],
+        sitekey: str,
+        url: str,
+        rqdata: str,
+        user_agent: Optional[str] = None,
+        proxy: Union[Proxy, str, None] = None,
+        webhook_url: Optional[str] = None,
+        wait: Optional[int] = None,
+    ) -> Solve: ...
+
+    def create(
+        self,
+        *,
+        type: SolveType,
+        sitekey: str,
+        url: str,
+        rqdata: Optional[str] = None,
+        user_agent: Optional[str] = None,
+        proxy: Union[Proxy, str, None] = None,
+        webhook_url: Optional[str] = None,
+        wait: Optional[int] = None,
+    ) -> Solve:
+        """Submit a solve. Pass ``wait`` (1-90 seconds) to hold the connection
+        open until it finishes instead of returning a pending solve."""
+        body = _build_solve_body(
+            type=type,
+            sitekey=sitekey,
+            url=url,
+            rqdata=rqdata,
+            user_agent=user_agent,
+            proxy=proxy,
+            webhook_url=webhook_url,
+        )
+        payload = self._client._request(
+            "POST",
+            "/v1/solves",
+            params={"wait": wait} if wait is not None else None,
+            json=body,
+            wait=wait,
+        )
+        return Solve._from_dict(payload)
+
+    def retrieve(self, solve_id: str, *, wait: Optional[int] = None) -> Solve:
+        """Fetch a solve by id. Pass ``wait`` to long-poll until it finishes."""
+        payload = self._client._request(
+            "GET",
+            f"/v1/solves/{solve_id}",
+            params={"wait": wait} if wait is not None else None,
+            wait=wait,
+        )
+        return Solve._from_dict(payload)
+
+    def cancel(self, solve_id: str) -> Solve:
+        """Cancel a pending or in-flight solve. Cancelled solves are never charged."""
+        payload = self._client._request("DELETE", f"/v1/solves/{solve_id}")
+        return Solve._from_dict(payload)
+
+    def list(
+        self,
+        *,
+        limit: Optional[int] = None,
+        starting_after: Optional[str] = None,
+        status: Optional[SolveStatus] = None,
+        type: Optional[SolveType] = None,
+    ) -> SolvePage:
+        """Fetch one page of solves, newest first."""
+        payload = self._client._request(
+            "GET",
+            "/v1/solves",
+            params=_list_params(
+                limit=limit, starting_after=starting_after, status=status, type=type
+            ),
+        )
+        return SolvePage._from_dict(payload)
+
+    def list_all(
+        self,
+        *,
+        limit: Optional[int] = None,
+        status: Optional[SolveStatus] = None,
+        type: Optional[SolveType] = None,
+    ) -> Iterator[Solve]:
+        """Iterate every solve across pages, newest first.
+
+        >>> for solve in client.solves.list_all():
+        ...     print(solve.id, solve.status)
+        """
+        cursor: Optional[str] = None
+        while True:
+            page = self.list(limit=limit, starting_after=cursor, status=status, type=type)
+            yield from page.data
+            if not page.has_more or not page.data:
+                return
+            cursor = page.data[-1].id
+
+
+class NoneCap(_BaseClient):
+    """The NoneCap API client (sync).
+
+    >>> from nonecap import NoneCap
+    >>> nc = NoneCap(api_key="nc_live_...")
+    >>> solve = nc.solve(type="hcaptcha", sitekey="...", url="https://example.com")
+    >>> solve.token
+    'P1_...'
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_REQUEST_TIMEOUT,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        super().__init__(api_key=api_key, base_url=base_url, timeout=timeout)
+        self._http = http_client or httpx.Client()
+        self._owns_http = http_client is None
+        self.solves = Solves(self)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[dict[str, Any]] = None,
+        json: Optional[dict[str, Any]] = None,
+        wait: Optional[int] = None,
+    ) -> Any:
+        try:
+            response = self._http.request(
+                method,
+                self._url(path),
+                params=params,
+                json=json,
+                headers=self._headers,
+                timeout=_request_timeout_for_wait(wait, self._timeout),
+            )
+        except httpx.TimeoutException as exc:
+            raise APITimeoutError(f"Request to {path} timed out: {exc}") from exc
+        except httpx.HTTPError as exc:
+            raise APIConnectionError(
+                f"Could not reach the NoneCap API at {self._base_url}: {exc}"
+            ) from exc
+        return _process_response(response)
+
+    @overload
+    def solve(
+        self,
+        *,
+        type: Literal["hcaptcha"],
+        sitekey: str,
+        url: str,
+        rqdata: Optional[str] = None,
+        user_agent: Optional[str] = None,
+        proxy: Union[Proxy, str, None] = None,
+        webhook_url: Optional[str] = None,
+        timeout: float = DEFAULT_SOLVE_TIMEOUT,
+    ) -> Solve: ...
+
+    @overload
+    def solve(
+        self,
+        *,
+        type: Literal["hcaptcha_enterprise"],
+        sitekey: str,
+        url: str,
+        rqdata: str,
+        user_agent: Optional[str] = None,
+        proxy: Union[Proxy, str, None] = None,
+        webhook_url: Optional[str] = None,
+        timeout: float = DEFAULT_SOLVE_TIMEOUT,
+    ) -> Solve: ...
+
+    def solve(
+        self,
+        *,
+        type: SolveType,
+        sitekey: str,
+        url: str,
+        rqdata: Optional[str] = None,
+        user_agent: Optional[str] = None,
+        proxy: Union[Proxy, str, None] = None,
+        webhook_url: Optional[str] = None,
+        timeout: float = DEFAULT_SOLVE_TIMEOUT,
+    ) -> Solve:
+        """Submit a solve and wait for it to finish, returning the solved solve.
+
+        Uses the server's long-poll under the hood and keeps polling until the
+        solve is terminal or ``timeout`` seconds elapse. Raises
+        :class:`SolveFailedError` if the solve fails/expires/is cancelled, or
+        :class:`SolveTimeoutError` on timeout.
+        """
+        deadline = time.monotonic() + timeout
+        # Build the body directly rather than dispatching through the
+        # overloaded create(): the union-typed passthrough args defeat
+        # overload resolution, and the runtime rqdata check lives in
+        # _build_solve_body either way.
+        body = _build_solve_body(
+            type=type,
+            sitekey=sitekey,
+            url=url,
+            rqdata=rqdata,
+            user_agent=user_agent,
+            proxy=proxy,
+            webhook_url=webhook_url,
+        )
+        wait = _wait_seconds(deadline)
+        payload = self._request(
+            "POST", "/v1/solves", params={"wait": wait}, json=body, wait=wait
+        )
+        solve = Solve._from_dict(payload)
+        while not solve.is_terminal:
+            if time.monotonic() >= deadline:
+                raise SolveTimeoutError(
+                    f"Solve {solve.id} did not finish within {timeout:g}s "
+                    f"(last status: {solve.status})."
+                )
+            solve = self.solves.retrieve(solve.id, wait=_wait_seconds(deadline))
+        if solve.status != "solved":
+            raise SolveFailedError(solve)
+        return solve
+
+    def me(self) -> Account:
+        """Fetch your account, including the current credit balance."""
+        return Account._from_dict(self._request("GET", "/v1/me"))
+
+    def close(self) -> None:
+        """Close the underlying HTTP client (only if this client created it)."""
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> NoneCap:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+
+# ---------------------------------------------------------------------------
+# Async
+# ---------------------------------------------------------------------------
+
+
+class AsyncSolves:
+    """Operations on solves (async). Reached as ``client.solves``."""
+
+    def __init__(self, client: AsyncNoneCap) -> None:
+        self._client = client
+
+    @overload
+    async def create(
+        self,
+        *,
+        type: Literal["hcaptcha"],
+        sitekey: str,
+        url: str,
+        rqdata: Optional[str] = None,
+        user_agent: Optional[str] = None,
+        proxy: Union[Proxy, str, None] = None,
+        webhook_url: Optional[str] = None,
+        wait: Optional[int] = None,
+    ) -> Solve: ...
+
+    @overload
+    async def create(
+        self,
+        *,
+        type: Literal["hcaptcha_enterprise"],
+        sitekey: str,
+        url: str,
+        rqdata: str,
+        user_agent: Optional[str] = None,
+        proxy: Union[Proxy, str, None] = None,
+        webhook_url: Optional[str] = None,
+        wait: Optional[int] = None,
+    ) -> Solve: ...
+
+    async def create(
+        self,
+        *,
+        type: SolveType,
+        sitekey: str,
+        url: str,
+        rqdata: Optional[str] = None,
+        user_agent: Optional[str] = None,
+        proxy: Union[Proxy, str, None] = None,
+        webhook_url: Optional[str] = None,
+        wait: Optional[int] = None,
+    ) -> Solve:
+        """Submit a solve. Pass ``wait`` (1-90 seconds) to hold the connection
+        open until it finishes instead of returning a pending solve."""
+        body = _build_solve_body(
+            type=type,
+            sitekey=sitekey,
+            url=url,
+            rqdata=rqdata,
+            user_agent=user_agent,
+            proxy=proxy,
+            webhook_url=webhook_url,
+        )
+        payload = await self._client._request(
+            "POST",
+            "/v1/solves",
+            params={"wait": wait} if wait is not None else None,
+            json=body,
+            wait=wait,
+        )
+        return Solve._from_dict(payload)
+
+    async def retrieve(self, solve_id: str, *, wait: Optional[int] = None) -> Solve:
+        """Fetch a solve by id. Pass ``wait`` to long-poll until it finishes."""
+        payload = await self._client._request(
+            "GET",
+            f"/v1/solves/{solve_id}",
+            params={"wait": wait} if wait is not None else None,
+            wait=wait,
+        )
+        return Solve._from_dict(payload)
+
+    async def cancel(self, solve_id: str) -> Solve:
+        """Cancel a pending or in-flight solve. Cancelled solves are never charged."""
+        payload = await self._client._request("DELETE", f"/v1/solves/{solve_id}")
+        return Solve._from_dict(payload)
+
+    async def list(
+        self,
+        *,
+        limit: Optional[int] = None,
+        starting_after: Optional[str] = None,
+        status: Optional[SolveStatus] = None,
+        type: Optional[SolveType] = None,
+    ) -> SolvePage:
+        """Fetch one page of solves, newest first."""
+        payload = await self._client._request(
+            "GET",
+            "/v1/solves",
+            params=_list_params(
+                limit=limit, starting_after=starting_after, status=status, type=type
+            ),
+        )
+        return SolvePage._from_dict(payload)
+
+    async def list_all(
+        self,
+        *,
+        limit: Optional[int] = None,
+        status: Optional[SolveStatus] = None,
+        type: Optional[SolveType] = None,
+    ) -> AsyncIterator[Solve]:
+        """Iterate every solve across pages, newest first.
+
+        >>> async for solve in client.solves.list_all():
+        ...     print(solve.id, solve.status)
+        """
+        cursor: Optional[str] = None
+        while True:
+            page = await self.list(
+                limit=limit, starting_after=cursor, status=status, type=type
+            )
+            for solve in page.data:
+                yield solve
+            if not page.has_more or not page.data:
+                return
+            cursor = page.data[-1].id
+
+
+class AsyncNoneCap(_BaseClient):
+    """The NoneCap API client (async).
+
+    >>> from nonecap import AsyncNoneCap
+    >>> async with AsyncNoneCap(api_key="nc_live_...") as nc:
+    ...     solve = await nc.solve(type="hcaptcha", sitekey="...", url="https://example.com")
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_REQUEST_TIMEOUT,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        super().__init__(api_key=api_key, base_url=base_url, timeout=timeout)
+        self._http = http_client or httpx.AsyncClient()
+        self._owns_http = http_client is None
+        self.solves = AsyncSolves(self)
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[dict[str, Any]] = None,
+        json: Optional[dict[str, Any]] = None,
+        wait: Optional[int] = None,
+    ) -> Any:
+        try:
+            response = await self._http.request(
+                method,
+                self._url(path),
+                params=params,
+                json=json,
+                headers=self._headers,
+                timeout=_request_timeout_for_wait(wait, self._timeout),
+            )
+        except httpx.TimeoutException as exc:
+            raise APITimeoutError(f"Request to {path} timed out: {exc}") from exc
+        except httpx.HTTPError as exc:
+            raise APIConnectionError(
+                f"Could not reach the NoneCap API at {self._base_url}: {exc}"
+            ) from exc
+        return _process_response(response)
+
+    @overload
+    async def solve(
+        self,
+        *,
+        type: Literal["hcaptcha"],
+        sitekey: str,
+        url: str,
+        rqdata: Optional[str] = None,
+        user_agent: Optional[str] = None,
+        proxy: Union[Proxy, str, None] = None,
+        webhook_url: Optional[str] = None,
+        timeout: float = DEFAULT_SOLVE_TIMEOUT,
+    ) -> Solve: ...
+
+    @overload
+    async def solve(
+        self,
+        *,
+        type: Literal["hcaptcha_enterprise"],
+        sitekey: str,
+        url: str,
+        rqdata: str,
+        user_agent: Optional[str] = None,
+        proxy: Union[Proxy, str, None] = None,
+        webhook_url: Optional[str] = None,
+        timeout: float = DEFAULT_SOLVE_TIMEOUT,
+    ) -> Solve: ...
+
+    async def solve(
+        self,
+        *,
+        type: SolveType,
+        sitekey: str,
+        url: str,
+        rqdata: Optional[str] = None,
+        user_agent: Optional[str] = None,
+        proxy: Union[Proxy, str, None] = None,
+        webhook_url: Optional[str] = None,
+        timeout: float = DEFAULT_SOLVE_TIMEOUT,
+    ) -> Solve:
+        """Submit a solve and wait for it to finish, returning the solved solve.
+
+        Uses the server's long-poll under the hood and keeps polling until the
+        solve is terminal or ``timeout`` seconds elapse. Raises
+        :class:`SolveFailedError` if the solve fails/expires/is cancelled, or
+        :class:`SolveTimeoutError` on timeout.
+        """
+        deadline = time.monotonic() + timeout
+        # Same shape as the sync client: build the body directly instead of
+        # dispatching through the overloaded create() with union-typed args.
+        body = _build_solve_body(
+            type=type,
+            sitekey=sitekey,
+            url=url,
+            rqdata=rqdata,
+            user_agent=user_agent,
+            proxy=proxy,
+            webhook_url=webhook_url,
+        )
+        wait = _wait_seconds(deadline)
+        payload = await self._request(
+            "POST", "/v1/solves", params={"wait": wait}, json=body, wait=wait
+        )
+        solve = Solve._from_dict(payload)
+        while not solve.is_terminal:
+            if time.monotonic() >= deadline:
+                raise SolveTimeoutError(
+                    f"Solve {solve.id} did not finish within {timeout:g}s "
+                    f"(last status: {solve.status})."
+                )
+            solve = await self.solves.retrieve(solve.id, wait=_wait_seconds(deadline))
+        if solve.status != "solved":
+            raise SolveFailedError(solve)
+        return solve
+
+    async def me(self) -> Account:
+        """Fetch your account, including the current credit balance."""
+        return Account._from_dict(await self._request("GET", "/v1/me"))
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client (only if this client created it)."""
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncNoneCap:
+        return self
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        await self.close()

nonecap/_errors.py

@@ -0,0 +1,112 @@
+"""The error tree. Catch :class:`NoneCapError` for everything this library
+throws, or a subclass for one specific failure."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from ._types import Solve
+
+
+class NoneCapError(Exception):
+    """Base class for every error raised by this library."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: Optional[str] = None,
+        status: Optional[int] = None,
+        param: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        """Machine-readable error code from the API envelope, when there is one."""
+        self.status = status
+        """HTTP status, when the error came from a response."""
+        self.param = param
+        """The request field that was rejected, for validation errors."""
+
+
+class AuthenticationError(NoneCapError):
+    """401 — the API key is missing, malformed, or revoked."""
+
+
+class PermissionDeniedError(NoneCapError):
+    """403 — the key is valid but not allowed to do this (scope or locked account)."""
+
+
+class InsufficientCreditsError(NoneCapError):
+    """402 — the account is out of credits."""
+
+
+class ValidationError(NoneCapError):
+    """422 / 400 — the request was rejected. ``param`` names the offending field."""
+
+
+class NotFoundError(NoneCapError):
+    """404 — no such resource."""
+
+
+class ConflictError(NoneCapError):
+    """409 — the solve is already in a terminal state."""
+
+
+class RateLimitError(NoneCapError):
+    """429 — too many concurrent solves, or rate limited. Back off and retry."""
+
+
+class APIError(NoneCapError):
+    """5xx, or a response that was not the expected shape."""
+
+
+class APIConnectionError(NoneCapError):
+    """The request never reached the API (DNS, TCP, TLS, offline)."""
+
+
+class APITimeoutError(APIConnectionError):
+    """A single HTTP request exceeded its timeout."""
+
+
+class SolveTimeoutError(NoneCapError):
+    """Raised by ``solve()`` when the overall timeout elapses first."""
+
+
+class SolveFailedError(NoneCapError):
+    """Raised by ``solve()`` when a solve reaches a terminal state without a
+    token: ``failed``, ``expired``, or ``cancelled``. The full solve is attached
+    as ``.solve`` so you can inspect ``solve.error`` and the timings."""
+
+    def __init__(self, solve: Solve) -> None:
+        detail = f"{solve.error.code}: {solve.error.message}" if solve.error else solve.status
+        super().__init__(f"Solve {solve.id} {solve.status} ({detail})")
+        self.solve = solve
+
+
+def error_from_response(
+    status: int,
+    code: Optional[str],
+    message: str,
+    param: Optional[str],
+) -> NoneCapError:
+    """Map an API error envelope (plus HTTP status) to the right subclass."""
+    cls: type[NoneCapError]
+    if code == "unauthorized":
+        cls = AuthenticationError
+    elif code in ("forbidden", "account_locked"):
+        cls = PermissionDeniedError
+    elif code == "insufficient_credits":
+        cls = InsufficientCreditsError
+    elif code in ("invalid_request", "validation_error"):
+        cls = ValidationError
+    elif code == "not_found":
+        cls = NotFoundError
+    elif code == "conflict":
+        cls = ConflictError
+    elif code in ("rate_limited", "concurrency_limit_exceeded", "ext_daily_limit"):
+        cls = RateLimitError
+    else:
+        cls = APIError
+    return cls(message, code=code, status=status, param=param)

nonecap/_types.py

@@ -0,0 +1,127 @@
+"""Wire types for the NoneCap API.
+
+Field names are snake_case and mirror the JSON on the wire exactly, so what
+you read in the docs is what you access in code. Parsers pick known keys and
+ignore unknown ones, so new server-side fields never break old clients.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal, Optional, TypedDict
+
+SolveType = Literal["hcaptcha", "hcaptcha_enterprise"]
+"""Captcha type a solve targets."""
+
+SolveStatus = Literal["pending", "solving", "solved", "failed", "cancelled", "expired"]
+"""Lifecycle of a solve. ``solved``/``failed``/``cancelled``/``expired`` are terminal."""
+
+TERMINAL_STATUSES: frozenset[str] = frozenset({"solved", "failed", "cancelled", "expired"})
+"""The statuses a solve can never leave."""
+
+
+class Proxy(TypedDict, total=False):
+    """A proxy the solve should egress through."""
+
+    scheme: str
+    host: str
+    port: str | int
+    username: str
+    password: str
+
+
+@dataclass(frozen=True)
+class SolveError:
+    """The error attached to a solve that did not succeed."""
+
+    code: str
+    message: str
+
+
+@dataclass(frozen=True)
+class Solve:
+    """A solve resource, exactly as the API returns it."""
+
+    id: str
+    object: str
+    type: SolveType
+    status: SolveStatus
+    sitekey: str
+    url: str
+    token: Optional[str]
+    """The captcha token once ``status == "solved"``, otherwise None."""
+    error: Optional[SolveError]
+    """Set when the solve did not succeed, otherwise None."""
+    credits_charged: Optional[int]
+    """Credits charged for this solve. Only successful solves are charged."""
+    proxy_bytes: Optional[int]
+    """Bytes that egressed through the metered proxy, or None if none was used."""
+    created_at: str
+    started_at: Optional[str]
+    finished_at: Optional[str]
+    queue_ms: Optional[int]
+    """Milliseconds the solve waited in the queue before a worker picked it up."""
+    resolve_ms: Optional[int]
+    """Milliseconds of actual solving."""
+
+    @property
+    def is_terminal(self) -> bool:
+        """Whether the solve has reached a final state."""
+        return self.status in TERMINAL_STATUSES
+
+    @classmethod
+    def _from_dict(cls, data: dict[str, Any]) -> Solve:
+        raw_error = data.get("error")
+        return cls(
+            id=data["id"],
+            object=data.get("object", "solve"),
+            type=data["type"],
+            status=data["status"],
+            sitekey=data.get("sitekey", ""),
+            url=data.get("url", ""),
+            token=data.get("token"),
+            error=SolveError(code=raw_error["code"], message=raw_error["message"])
+            if raw_error
+            else None,
+            credits_charged=data.get("credits_charged"),
+            proxy_bytes=data.get("proxy_bytes"),
+            created_at=data.get("created_at", ""),
+            started_at=data.get("started_at"),
+            finished_at=data.get("finished_at"),
+            queue_ms=data.get("queue_ms"),
+            resolve_ms=data.get("resolve_ms"),
+        )
+
+
+@dataclass(frozen=True)
+class SolvePage:
+    """One page of solves, newest first."""
+
+    data: list[Solve]
+    has_more: bool
+
+    @classmethod
+    def _from_dict(cls, payload: dict[str, Any]) -> SolvePage:
+        return cls(
+            data=[Solve._from_dict(item) for item in payload.get("data", [])],
+            has_more=bool(payload.get("has_more", False)),
+        )
+
+
+@dataclass(frozen=True)
+class Account:
+    """Your account, including the current credit balance."""
+
+    id: str
+    email: str
+    credits_balance: int
+    created_at: str
+
+    @classmethod
+    def _from_dict(cls, data: dict[str, Any]) -> Account:
+        return cls(
+            id=data["id"],
+            email=data.get("email", ""),
+            credits_balance=int(data.get("credits_balance", 0)),
+            created_at=data.get("created_at", ""),
+        )

nonecap/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

nonecap-0.1.0.dist-info/METADATA

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: nonecap
+Version: 0.1.0
+Summary: Official Python client for the NoneCap hCaptcha solving API.
+Project-URL: Homepage, https://nonecap.com
+Project-URL: Documentation, https://nonecap.com/api-reference
+Project-URL: Repository, https://github.com/nonecap/nonecap-py
+Project-URL: Issues, https://github.com/nonecap/nonecap-py/issues
+Author: Lunium
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-client,captcha,captcha-solver,hcaptcha,hcaptcha-solver,nonecap,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+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: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<h1 align="center">nonecap</h1>
+
+<p align="center">
+  <a href="https://github.com/nonecap/nonecap-py/actions/workflows/ci.yml"><img src="https://github.com/nonecap/nonecap-py/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://pypi.org/project/nonecap/"><img src="https://img.shields.io/pypi/v/nonecap.svg" alt="PyPI"></a>
+  <a href="https://pypi.org/project/nonecap/"><img src="https://img.shields.io/pypi/pyversions/nonecap.svg" alt="Python versions"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
+</p>
+
+<p align="center">Official Python client for the <a href="https://nonecap.com">NoneCap</a> hCaptcha solving API.</p>
+
+Submit a captcha, get back a token. The client handles the polling, the timeouts, and the error cases so you don't write the request loop yourself. Sync and async, fully typed.
+
+## Install
+
+```sh
+pip install nonecap
+```
+
+Python 3.9+. The only dependency is [httpx](https://www.python-httpx.org/).
+
+## Quick start
+
+Grab an API key from [dashboard.nonecap.com](https://dashboard.nonecap.com), then:
+
+```python
+from nonecap import NoneCap
+
+nc = NoneCap(api_key="nc_live_...")
+
+solve = nc.solve(
+    type="hcaptcha",
+    sitekey="10000000-ffff-ffff-ffff-000000000001",
+    url="https://example.com/login",
+)
+
+print(solve.token)  # the hCaptcha token, ready to submit
+```
+
+`solve()` submits the captcha and waits until it's done, using the API's long-poll so you aren't hammering it with requests. It returns the solved solve, or raises if the solve fails or your timeout runs out.
+
+## Async
+
+Same surface, `await`ed. Use it as an async context manager so the connection pool gets cleaned up:
+
+```python
+import asyncio
+from nonecap import AsyncNoneCap
+
+async def main() -> None:
+    async with AsyncNoneCap(api_key="nc_live_...") as nc:
+        solve = await nc.solve(type="hcaptcha", sitekey="...", url="https://example.com")
+        print(solve.token)
+
+asyncio.run(main())
+```
+
+## Handling failures
+
+Every error this library raises extends `NoneCapError`, so you can catch the whole family or pick out the one you care about.
+
+```python
+from nonecap import (
+    NoneCap,
+    SolveFailedError,
+    InsufficientCreditsError,
+    RateLimitError,
+)
+
+try:
+    solve = nc.solve(type="hcaptcha", sitekey=sitekey, url=url)
+except SolveFailedError as err:
+    print("Could not solve it:", err.solve.error.code if err.solve.error else "?")
+except InsufficientCreditsError:
+    print("Out of credits. Top up at dashboard.nonecap.com")
+except RateLimitError:
+    print("Too many solves in flight, back off and retry")
+```
+
+The subclasses are `AuthenticationError` (401), `PermissionDeniedError` (403), `InsufficientCreditsError` (402), `ValidationError` (422/400, with a `param` naming the bad field), `NotFoundError` (404), `ConflictError` (409), `RateLimitError` (429), `APIError` (5xx), `APIConnectionError` and `APITimeoutError` (the request never landed), and `SolveTimeoutError` (your `solve()` budget ran out). `SolveFailedError` carries the full `solve` so you can read the underlying error code and the timings.
+
+## Enterprise captchas
+
+For `hcaptcha_enterprise`, `rqdata` is required. The `@overload` signatures enforce that in mypy and pyright, so leaving it out fails your type check, and a runtime check backs it up before any network call:
+
+```python
+solve = nc.solve(
+    type="hcaptcha_enterprise",
+    sitekey=sitekey,
+    url=url,
+    rqdata="...",  # required for enterprise
+)
+```
+
+## Proxies
+
+Pass a proxy as a dict or a URL string. The solve runs through it, and the bytes are metered back on the solve.
+
+```python
+nc.solve(
+    type="hcaptcha",
+    sitekey=sitekey,
+    url=url,
+    proxy={"scheme": "http", "host": "1.2.3.4", "port": 8080, "username": "u", "password": "p"},
+    # or: proxy="http://u:p@1.2.3.4:8080"
+)
+```
+
+## Lower-level API
+
+`solve()` is the convenient path. When you want control over submission and polling, the resource methods map one to one to the REST API:
+
+```python
+# Submit without waiting: returns immediately with a pending solve
+pending = nc.solves.create(type="hcaptcha", sitekey=sitekey, url=url)
+
+# Submit and hold the connection up to 30s for it to finish
+maybe_done = nc.solves.create(type="hcaptcha", sitekey=sitekey, url=url, wait=30)
+
+# Poll one solve, long-polling up to 30s
+solve = nc.solves.retrieve(pending.id, wait=30)
+
+# Cancel a pending or in-flight solve
+nc.solves.cancel(pending.id)
+
+# List a page of solves
+page = nc.solves.list(limit=50, status="solved")
+
+# Or iterate every solve, newest first
+for s in nc.solves.list_all():
+    print(s.id, s.status)
+
+# Your account and credit balance
+me = nc.me()
+print(me.credits_balance)
+```
+
+On `AsyncNoneCap` the same methods are coroutines, and `list_all()` is an async iterator (`async for s in nc.solves.list_all()`).
+
+## Configuration
+
+```python
+NoneCap(
+    api_key="nc_live_...",              # required
+    base_url="https://api.nonecap.com", # override if you need to
+    timeout=100.0,                      # per HTTP request, seconds
+    http_client=my_httpx_client,        # inject your own httpx.Client
+)
+```
+
+`solve()` takes its own `timeout` (seconds, default 180) for the overall wait.
+
+## Typing
+
+The package ships a `py.typed` marker and full inline annotations. Solves come back as frozen dataclasses with the exact field names the API uses (`solve.token`, `solve.credits_charged`, `solve.queue_ms`), so what you read in the [API reference](https://nonecap.com/api-reference) is what you get in code.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

nonecap-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+nonecap/__init__.py,sha256=y5acaR3Vuo7M2XTlwIUr0RiXoDVUb6vokkpDtkLEy-w,1331
+nonecap/_client.py,sha256=7wsFElFydzgPF6EB9GBCz63nMPr1ONHush9whXRYwKw,22313
+nonecap/_errors.py,sha256=iebsKERVgKmt03KvWzsXRPQZGVM4EvH3qJTdIYK4fiY,3476
+nonecap/_types.py,sha256=YdFXAY-R4KIWybO5PjSdPdApgeLgNgUDOgrQZQPQgxg,3873
+nonecap/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+nonecap/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+nonecap-0.1.0.dist-info/METADATA,sha256=3Hw0Tub5tJxixETEdSsTejvSzq2BYL_pkHW_SHa37T0,6812
+nonecap-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+nonecap-0.1.0.dist-info/licenses/LICENSE,sha256=u5uegtPBAfHVIaKG03gcXYSOhKo8MI2_LwnxSTnZI38,1063
+nonecap-0.1.0.dist-info/RECORD,,

nonecap-0.1.0.dist-info/WHEEL

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

nonecap-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lunium
+
+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.