nonecap 0.2.0__tar.gz → 0.4.0__tar.gz

{nonecap-0.2.0 → nonecap-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nonecap
-Version: 0.2.0
+Version: 0.4.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
@@ -52,7 +52,7 @@ 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:
+Grab an API key from [dashboard.nonecap.com](https://dashboard.nonecap.com/signup?utm_source=pypi&utm_medium=sdk-readme), then:
 
 ```python
 from nonecap import NoneCap
@@ -128,6 +128,22 @@ async with AsyncNoneCap(api_key="nc_live_...") as nc:
 
 Cancelled solves are never charged, and a solve you simply abandon expires uncharged at the server deadline — nothing is billed unless a solve actually succeeds. So `cancel()` is for cleanup and early-stop, not cost protection.
 
+### Cleaning up after a `solve()` timeout
+
+`solve()` blocks until the solve settles, so it gives you no handle to cancel a solve while it's still running — for that, use `solves.start()` above. The one thing the `solve()` path offers is cleanup *after* a timeout: when `solve()` raises `SolveTimeoutError`, the error usually carries the in-flight `solve_id` (and last-known `solve`), so you can cancel the solve the wait gave up on. Guard on `solve_id` being present — if the very first submission times out at the transport level, no id has been assigned yet, so `solve_id` is `None`.
+
+```python
+from nonecap import SolveTimeoutError
+
+try:
+    nc.solve(type="hcaptcha", sitekey=sitekey, url=url)
+except SolveTimeoutError as err:
+    if err.solve_id is not None:
+        nc.solves.cancel(err.solve_id)
+    else:
+        raise
+```
+
 ## Handling failures
 
 Every error this library raises extends `NoneCapError`, so you can catch the whole family or pick out the one you care about.
@@ -181,6 +197,42 @@ nc.solve(
 )
 ```
 
+## Reporting token acceptance
+
+A token that hCaptcha blessed can still be refused by the site you send it to. Tell us what happened and we tune minting against your real acceptance rate — it's free, and it's the fastest way to get a regression on your sitekey noticed.
+
+Keep the `solve_id` next to the token you submit downstream, then report the verdict:
+
+```python
+solve = nc.solve(type="hcaptcha", sitekey=sitekey, url=url)
+ok = submit_to_the_site_you_are_automating(solve.token)
+
+nc.feedback.report(
+    solve.id,
+    outcome="accepted" if ok else "rejected",
+    reason=None if ok else "session invalidated",  # optional, the code your target returned
+    context=None if ok else "3rd retry, rotating residential pool",  # optional, anything you think would help us diagnose it
+)
+```
+
+At volume, buffer the verdicts and flush them in one call. Reports over 500 are split across requests for you:
+
+```python
+batch = nc.feedback.report_many([
+    {"solve_id": "solve_01J...", "outcome": "accepted"},
+    {"solve_id": "solve_01J...", "outcome": "rejected", "reason": "...", "context": "..."},
+])
+
+# Items resolve independently, so the call succeeds even when some are
+# rejected — check `failed` rather than relying on a raised error.
+if batch.failed:
+    print([r for r in batch.results if r.status == "error"])
+```
+
+`outcome` is one of `accepted`, `rejected`, `unknown` (submitted, verdict unclear), `unused` (never submitted), or `error` (downstream broke for a non-token reason). Only `accepted` and `rejected` count toward the acceptance rate.
+
+Reporting the same solve again corrects the earlier verdict, so retries and late fixes are safe. You can report any of your own solved solves within ~30 days of the solve; corrections to something you already reported are never cut off by that window. On `AsyncNoneCap` both methods are coroutines.
+
 ## 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:

{nonecap-0.2.0 → nonecap-0.4.0}/README.md

@@ -21,7 +21,7 @@ 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:
+Grab an API key from [dashboard.nonecap.com](https://dashboard.nonecap.com/signup?utm_source=pypi&utm_medium=sdk-readme), then:
 
 ```python
 from nonecap import NoneCap
@@ -97,6 +97,22 @@ async with AsyncNoneCap(api_key="nc_live_...") as nc:
 
 Cancelled solves are never charged, and a solve you simply abandon expires uncharged at the server deadline — nothing is billed unless a solve actually succeeds. So `cancel()` is for cleanup and early-stop, not cost protection.
 
+### Cleaning up after a `solve()` timeout
+
+`solve()` blocks until the solve settles, so it gives you no handle to cancel a solve while it's still running — for that, use `solves.start()` above. The one thing the `solve()` path offers is cleanup *after* a timeout: when `solve()` raises `SolveTimeoutError`, the error usually carries the in-flight `solve_id` (and last-known `solve`), so you can cancel the solve the wait gave up on. Guard on `solve_id` being present — if the very first submission times out at the transport level, no id has been assigned yet, so `solve_id` is `None`.
+
+```python
+from nonecap import SolveTimeoutError
+
+try:
+    nc.solve(type="hcaptcha", sitekey=sitekey, url=url)
+except SolveTimeoutError as err:
+    if err.solve_id is not None:
+        nc.solves.cancel(err.solve_id)
+    else:
+        raise
+```
+
 ## Handling failures
 
 Every error this library raises extends `NoneCapError`, so you can catch the whole family or pick out the one you care about.
@@ -150,6 +166,42 @@ nc.solve(
 )
 ```
 
+## Reporting token acceptance
+
+A token that hCaptcha blessed can still be refused by the site you send it to. Tell us what happened and we tune minting against your real acceptance rate — it's free, and it's the fastest way to get a regression on your sitekey noticed.
+
+Keep the `solve_id` next to the token you submit downstream, then report the verdict:
+
+```python
+solve = nc.solve(type="hcaptcha", sitekey=sitekey, url=url)
+ok = submit_to_the_site_you_are_automating(solve.token)
+
+nc.feedback.report(
+    solve.id,
+    outcome="accepted" if ok else "rejected",
+    reason=None if ok else "session invalidated",  # optional, the code your target returned
+    context=None if ok else "3rd retry, rotating residential pool",  # optional, anything you think would help us diagnose it
+)
+```
+
+At volume, buffer the verdicts and flush them in one call. Reports over 500 are split across requests for you:
+
+```python
+batch = nc.feedback.report_many([
+    {"solve_id": "solve_01J...", "outcome": "accepted"},
+    {"solve_id": "solve_01J...", "outcome": "rejected", "reason": "...", "context": "..."},
+])
+
+# Items resolve independently, so the call succeeds even when some are
+# rejected — check `failed` rather than relying on a raised error.
+if batch.failed:
+    print([r for r in batch.results if r.status == "error"])
+```
+
+`outcome` is one of `accepted`, `rejected`, `unknown` (submitted, verdict unclear), `unused` (never submitted), or `error` (downstream broke for a non-token reason). Only `accepted` and `rejected` count toward the acceptance rate.
+
+Reporting the same solve again corrects the earlier verdict, so retries and late fixes are safe. You can report any of your own solved solves within ~30 days of the solve; corrections to something you already reported are never cut off by that window. On `AsyncNoneCap` both methods are coroutines.
+
 ## 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:

{nonecap-0.2.0 → nonecap-0.4.0}/src/nonecap/__init__.py

@@ -7,7 +7,13 @@
 'P1_...'
 """
 
-from ._client import AsyncNoneCap, AsyncSolveHandle, NoneCap, SolveHandle
+from ._client import (
+    FEEDBACK_BATCH_MAX,
+    AsyncNoneCap,
+    AsyncSolveHandle,
+    NoneCap,
+    SolveHandle,
+)
 from ._errors import (
     APIConnectionError,
     APIError,
@@ -26,6 +32,13 @@ from ._errors import (
 from ._types import (
     TERMINAL_STATUSES,
     Account,
+    Feedback,
+    FeedbackBatch,
+    FeedbackItemError,
+    FeedbackOutcome,
+    FeedbackReport,
+    FeedbackResult,
+    FeedbackStatus,
     Proxy,
     Solve,
     SolveError,
@@ -52,6 +65,14 @@ __all__ = [
     "SolveType",
     "SolveStatus",
     "TERMINAL_STATUSES",
+    "Feedback",
+    "FeedbackReport",
+    "FeedbackBatch",
+    "FeedbackResult",
+    "FeedbackItemError",
+    "FeedbackOutcome",
+    "FeedbackStatus",
+    "FEEDBACK_BATCH_MAX",
     # errors
     "NoneCapError",
     "AuthenticationError",

{nonecap-0.2.0 → nonecap-0.4.0}/src/nonecap/_client.py

@@ -6,6 +6,8 @@ Both clients expose the same surface:
   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.feedback.report / report_many`` — tell us whether the tokens we
+  minted were accepted downstream.
 - ``client.me()`` — account info and credit balance.
 
 ``rqdata`` is required for ``type="hcaptcha_enterprise"`` and optional for
@@ -17,7 +19,8 @@ from __future__ import annotations
 
 import asyncio
 import time
-from collections.abc import AsyncIterator, Iterator
+from collections.abc import AsyncIterator, Iterator, Sequence
+from datetime import datetime
 from typing import (
     Any,
     Literal,
@@ -38,7 +41,18 @@ from ._errors import (
     ValidationError,
     error_from_response,
 )
-from ._types import Account, Proxy, Solve, SolvePage, SolveStatus, SolveType
+from ._types import (
+    Account,
+    Feedback,
+    FeedbackBatch,
+    FeedbackOutcome,
+    FeedbackReport,
+    Proxy,
+    Solve,
+    SolvePage,
+    SolveStatus,
+    SolveType,
+)
 from ._version import __version__
 
 DEFAULT_BASE_URL = "https://api.nonecap.com"
@@ -48,6 +62,8 @@ 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."""
+FEEDBACK_BATCH_MAX = 500
+"""The API caps one ``POST /v1/feedback`` call at 500 items."""
 
 _USER_AGENT = f"nonecap-python/{__version__}"
 
@@ -115,6 +131,55 @@ def _list_params(
     return params
 
 
+def _feedback_fields(
+    outcome: FeedbackOutcome,
+    reason: Optional[str],
+    context: Optional[str],
+    reported_at: Union[str, datetime, None],
+) -> dict[str, Any]:
+    """The body of one report. A ``datetime`` is sent as an ISO string; pass a
+    timezone-aware one, since the server reads a naive timestamp as its own."""
+    body: dict[str, Any] = {"outcome": outcome}
+    if reason is not None:
+        body["reason"] = reason
+    if context is not None:
+        body["context"] = context
+    if reported_at is not None:
+        body["reported_at"] = (
+            reported_at.isoformat() if isinstance(reported_at, datetime) else reported_at
+        )
+    return body
+
+
+def _feedback_chunks(reports: Sequence[FeedbackReport]) -> Iterator[list[dict[str, Any]]]:
+    """Split reports into request-sized batches, preserving order."""
+    for start in range(0, len(reports), FEEDBACK_BATCH_MAX):
+        yield [
+            {
+                "solve_id": report["solve_id"],
+                **_feedback_fields(
+                    report["outcome"],
+                    report.get("reason"),
+                    report.get("context"),
+                    report.get("reported_at"),
+                ),
+            }
+            for report in reports[start : start + FEEDBACK_BATCH_MAX]
+        ]
+
+
+def _merged_batch(parts: list[FeedbackBatch]) -> FeedbackBatch:
+    """Fold the replies to a chunked ``report_many`` into one result."""
+    return FeedbackBatch(
+        object="feedback_batch",
+        recorded=sum(part.recorded for part in parts),
+        updated=sum(part.updated for part in parts),
+        unchanged=sum(part.unchanged for part in parts),
+        failed=sum(part.failed for part in parts),
+        results=[result for part in parts for result in part.results],
+    )
+
+
 def _process_response(response: httpx.Response) -> Any:
     """Parse a response, mapping non-2xx envelopes to typed errors.
 
@@ -427,6 +492,77 @@ class SolveHandle:
         return solve
 
 
+class Feedbacks:
+    """Reporting what your downstream target did with the tokens we minted
+    (sync). Reached as ``client.feedback``.
+
+    Feedback is free, own-solves-only, and idempotent per solve id: reporting
+    the same solve again corrects the earlier verdict. Only solves that
+    produced a token can be reported, and only within the API's reporting
+    window (~30 days from the solve); a correction to something you already
+    reported is never cut off by that window.
+    """
+
+    def __init__(self, client: NoneCap) -> None:
+        self._client = client
+
+    def report(
+        self,
+        solve_id: str,
+        *,
+        outcome: FeedbackOutcome,
+        reason: Optional[str] = None,
+        context: Optional[str] = None,
+        reported_at: Union[str, datetime, None] = None,
+    ) -> Feedback:
+        """Report one solve's downstream outcome and return what was recorded.
+
+        Unlike :meth:`report_many`, a rejected report raises:
+        :class:`NotFoundError` if the solve is not yours or never minted a
+        token, :class:`ValidationError` if a field is wrong or the reporting
+        window has closed.
+
+        >>> nc.feedback.report(solve.id, outcome="rejected", reason="...")
+        """
+        payload = self._client._request(
+            "POST",
+            f"/v1/solves/{solve_id}/feedback",
+            json=_feedback_fields(outcome, reason, context, reported_at),
+        )
+        return Feedback._from_dict(payload)
+
+    def report_many(self, reports: Sequence[FeedbackReport]) -> FeedbackBatch:
+        """Report many verdicts at once — the path to use at volume. Buffer
+        verdicts as you learn them and flush them here.
+
+        The call succeeds even when individual items are rejected: each is
+        resolved on its own so one stale id never discards the rest. Check
+        ``batch.failed`` rather than relying on a raised error.
+
+        More than ``FEEDBACK_BATCH_MAX`` reports are split across sequential
+        requests and merged into one result, in request order. An empty
+        sequence is a no-op that returns an empty batch without a request.
+
+        >>> batch = nc.feedback.report_many(
+        ...     [{"solve_id": "solve_01J...", "outcome": "accepted"}]
+        ... )
+        >>> [r for r in batch.results if r.status == "error"]
+        []
+        """
+        # Chunks go in order and the server upserts last-write-wins, so a solve
+        # reported twice still ends at its last value. Duplicates split across a
+        # chunk boundary each get written, though, so the earlier one reports
+        # "recorded"/"updated" where a single request would say "unchanged".
+        return _merged_batch(
+            [
+                FeedbackBatch._from_dict(
+                    self._client._request("POST", "/v1/feedback", json={"feedback": chunk})
+                )
+                for chunk in _feedback_chunks(reports)
+            ]
+        )
+
+
 class NoneCap(_BaseClient):
     """The NoneCap API client (sync).
 
@@ -449,6 +585,7 @@ class NoneCap(_BaseClient):
         self._http = http_client or httpx.Client()
         self._owns_http = http_client is None
         self.solves = Solves(self)
+        self.feedback = Feedbacks(self)
 
     def _request(
         self,
@@ -856,6 +993,65 @@ class AsyncSolveHandle:
         return solve
 
 
+class AsyncFeedbacks:
+    """Reporting what your downstream target did with the tokens we minted
+    (async). Reached as ``client.feedback``.
+
+    Feedback is free, own-solves-only, and idempotent per solve id: reporting
+    the same solve again corrects the earlier verdict. Only solves that
+    produced a token can be reported, and only within the API's reporting
+    window (~30 days from the solve); a correction to something you already
+    reported is never cut off by that window.
+    """
+
+    def __init__(self, client: AsyncNoneCap) -> None:
+        self._client = client
+
+    async def report(
+        self,
+        solve_id: str,
+        *,
+        outcome: FeedbackOutcome,
+        reason: Optional[str] = None,
+        context: Optional[str] = None,
+        reported_at: Union[str, datetime, None] = None,
+    ) -> Feedback:
+        """Report one solve's downstream outcome and return what was recorded.
+
+        Unlike :meth:`report_many`, a rejected report raises:
+        :class:`NotFoundError` if the solve is not yours or never minted a
+        token, :class:`ValidationError` if a field is wrong or the reporting
+        window has closed.
+        """
+        payload = await self._client._request(
+            "POST",
+            f"/v1/solves/{solve_id}/feedback",
+            json=_feedback_fields(outcome, reason, context, reported_at),
+        )
+        return Feedback._from_dict(payload)
+
+    async def report_many(self, reports: Sequence[FeedbackReport]) -> FeedbackBatch:
+        """Report many verdicts at once — the path to use at volume. Buffer
+        verdicts as you learn them and flush them here.
+
+        The call succeeds even when individual items are rejected: each is
+        resolved on its own so one stale id never discards the rest. Check
+        ``batch.failed`` rather than relying on a raised error.
+
+        More than ``FEEDBACK_BATCH_MAX`` reports are split across sequential
+        requests and merged into one result, in request order. An empty
+        sequence is a no-op that returns an empty batch without a request.
+        """
+        # Same last-write-wins caveat across a chunk boundary as the sync client.
+        parts = []
+        for chunk in _feedback_chunks(reports):
+            payload = await self._client._request(
+                "POST", "/v1/feedback", json={"feedback": chunk}
+            )
+            parts.append(FeedbackBatch._from_dict(payload))
+        return _merged_batch(parts)
+
+
 class AsyncNoneCap(_BaseClient):
     """The NoneCap API client (async).
 
@@ -876,6 +1072,7 @@ class AsyncNoneCap(_BaseClient):
         self._http = http_client or httpx.AsyncClient()
         self._owns_http = http_client is None
         self.solves = AsyncSolves(self)
+        self.feedback = AsyncFeedbacks(self)
 
     async def _request(
         self,

{nonecap-0.2.0 → nonecap-0.4.0}/src/nonecap/_errors.py

@@ -116,15 +116,20 @@ def error_from_response(
         cls = AuthenticationError
     elif code in ("forbidden", "account_locked"):
         cls = PermissionDeniedError
-    elif code == "insufficient_credits":
+    elif code in ("insufficient_credits", "key_credit_limit_exceeded"):
         cls = InsufficientCreditsError
-    elif code in ("invalid_request", "validation_error"):
+    elif code in ("invalid_request", "validation_error", "expired_window"):
         cls = ValidationError
-    elif code == "not_found":
+    elif code in ("not_found", "not_eligible"):
         cls = NotFoundError
     elif code == "conflict":
         cls = ConflictError
-    elif code in ("rate_limited", "concurrency_limit_exceeded", "ext_daily_limit"):
+    elif code in (
+        "rate_limited",
+        "concurrency_limit_exceeded",
+        "ext_daily_limit",
+        "sitekey_rate_limited",
+    ):
         cls = RateLimitError
     else:
         cls = APIError

nonecap-0.4.0/src/nonecap/_types.py

@@ -0,0 +1,265 @@
+"""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 datetime import datetime
+from typing import Any, Literal, Optional, TypedDict, Union
+
+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."""
+
+    object: str
+    data: list[Solve]
+    has_more: bool
+
+    @classmethod
+    def _from_dict(cls, payload: dict[str, Any]) -> SolvePage:
+        return cls(
+            object=payload.get("object", "list"),
+            data=[Solve._from_dict(item) for item in payload.get("data", [])],
+            has_more=bool(payload.get("has_more", False)),
+        )
+
+
+FeedbackOutcome = Literal["accepted", "rejected", "unknown", "unused", "error"]
+"""What the downstream target did with a solve's token.
+
+``accepted`` and ``rejected`` are the quality signal and the only two that
+count toward the acceptance rate. ``unknown`` (submitted, verdict
+undetermined), ``unused`` (never submitted — expired, aborted, deduped) and
+``error`` (downstream broke for a non-token reason) are recorded but kept out
+of the denominator, so a client-side outage can't look like a regression.
+"""
+
+FeedbackStatus = Literal["recorded", "updated", "unchanged", "error"]
+"""What happened to one reported item: first report, overwrote an earlier one,
+identical to what was stored (no write), or rejected."""
+
+
+class _FeedbackReportRequired(TypedDict):
+    solve_id: str
+    outcome: FeedbackOutcome
+
+
+class FeedbackReport(_FeedbackReportRequired, total=False):
+    """One verdict to report, as passed to ``client.feedback.report_many``.
+
+    ``solve_id`` is the id from ``solves.create`` / ``solve()``, and must be
+    your own solve that produced a token. ``reason`` is the code or message your
+    target gave you when it refused the token (e.g. ``"invalid-response"``),
+    truncated to 512 chars server-side. ``context`` is optional free text with no
+    schema — anything about the attempt you think would help us diagnose it,
+    truncated to 2000 chars. Neither is parsed; they are what a human reads when
+    you raise a ticket, and they carry the half of a rejection NoneCap cannot
+    observe on its own. ``reported_at`` is advisory only — the server stamps its
+    own timestamps.
+    """
+
+    reason: Optional[str]
+    context: Optional[str]
+    reported_at: Union[str, datetime, None]
+
+
+@dataclass(frozen=True)
+class Feedback:
+    """A recorded feedback resource."""
+
+    object: str
+    solve_id: str
+    outcome: FeedbackOutcome
+    reason: Optional[str]
+    context: Optional[str]
+    reported_at: Optional[str]
+    report_count: int
+    """How many times this solve's verdict has been written. 1 on first report."""
+    created_at: str
+    updated_at: str
+
+    @classmethod
+    def _from_dict(cls, data: dict[str, Any]) -> Feedback:
+        return cls(
+            object=data.get("object", "feedback"),
+            solve_id=data["solve_id"],
+            outcome=data["outcome"],
+            reason=data.get("reason"),
+            context=data.get("context"),
+            reported_at=data.get("reported_at"),
+            report_count=int(data.get("report_count", 1)),
+            created_at=data.get("created_at", ""),
+            updated_at=data.get("updated_at", ""),
+        )
+
+
+@dataclass(frozen=True)
+class FeedbackItemError:
+    """Why one item of a batch was rejected."""
+
+    code: str
+    message: str
+    param: Optional[str]
+
+
+@dataclass(frozen=True)
+class FeedbackResult:
+    """One item's result, in the same position as the report you sent."""
+
+    solve_id: str
+    status: FeedbackStatus
+    error: Optional[FeedbackItemError]
+    """Set only when ``status == "error"``."""
+
+    @classmethod
+    def _from_dict(cls, data: dict[str, Any]) -> FeedbackResult:
+        raw_error = data.get("error")
+        return cls(
+            solve_id=data.get("solve_id", ""),
+            status=data["status"],
+            error=FeedbackItemError(
+                code=raw_error.get("code", ""),
+                message=raw_error.get("message", ""),
+                param=raw_error.get("param"),
+            )
+            if raw_error
+            else None,
+        )
+
+
+@dataclass(frozen=True)
+class FeedbackBatch:
+    """The result of ``client.feedback.report_many``.
+
+    Items are resolved independently, so one bad solve id never discards the
+    rest — which also means a broken integration reports zero failures at the
+    HTTP level. Check ``failed`` (or scan ``results``), not just the absence of
+    a raised error.
+    """
+
+    object: str
+    recorded: int
+    updated: int
+    unchanged: int
+    failed: int
+    results: list[FeedbackResult]
+    """One entry per report you sent, in request order."""
+
+    @classmethod
+    def _from_dict(cls, payload: dict[str, Any]) -> FeedbackBatch:
+        return cls(
+            object=payload.get("object", "feedback_batch"),
+            recorded=int(payload.get("recorded", 0)),
+            updated=int(payload.get("updated", 0)),
+            unchanged=int(payload.get("unchanged", 0)),
+            failed=int(payload.get("failed", 0)),
+            results=[FeedbackResult._from_dict(item) for item in payload.get("results", [])],
+        )
+
+
+@dataclass(frozen=True)
+class Account:
+    """Your account, including the current credit balance."""
+
+    object: str
+    id: str
+    email: str
+    credits_balance: int
+    created_at: str
+
+    @classmethod
+    def _from_dict(cls, data: dict[str, Any]) -> Account:
+        return cls(
+            object=data.get("object", "account"),
+            id=data["id"],
+            email=data.get("email", ""),
+            credits_balance=int(data.get("credits_balance", 0)),
+            created_at=data.get("created_at", ""),
+        )

nonecap-0.4.0/src/nonecap/_version.py

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

nonecap-0.4.0/tests/test_feedback.py

@@ -0,0 +1,227 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+import httpx
+import pytest
+
+from nonecap import (
+    FEEDBACK_BATCH_MAX,
+    AsyncNoneCap,
+    FeedbackReport,
+    NoneCap,
+    NotFoundError,
+    ValidationError,
+)
+
+from .conftest import Script, error_payload
+
+
+def client_for(script: Script) -> NoneCap:
+    return NoneCap(api_key="nc_test", http_client=httpx.Client(transport=script.transport))
+
+
+def async_client_for(script: Script) -> AsyncNoneCap:
+    return AsyncNoneCap(
+        api_key="nc_test", http_client=httpx.AsyncClient(transport=script.transport)
+    )
+
+
+def feedback_payload(**overrides: Any) -> dict[str, Any]:
+    base: dict[str, Any] = {
+        "object": "feedback",
+        "solve_id": "solve_1",
+        "outcome": "accepted",
+        "reason": None,
+        "context": None,
+        "reported_at": None,
+        "report_count": 1,
+        "created_at": "2026-08-01T00:00:00Z",
+        "updated_at": "2026-08-01T00:00:00Z",
+    }
+    base.update(overrides)
+    return base
+
+
+def batch_payload(request: httpx.Request) -> httpx.Response:
+    """Reply to a batch request with every item recorded."""
+    import json
+
+    items = json.loads(request.content)["feedback"]
+    return httpx.Response(
+        200,
+        json={
+            "object": "feedback_batch",
+            "recorded": len(items),
+            "updated": 0,
+            "unchanged": 0,
+            "failed": 0,
+            "results": [
+                {"solve_id": item["solve_id"], "status": "recorded", "error": None}
+                for item in items
+            ],
+        },
+    )
+
+
+class TestReport:
+    def test_posts_to_the_solves_feedback_path(self) -> None:
+        script = Script((200, feedback_payload(outcome="rejected", context="3rd retry")))
+        nc = client_for(script)
+        result = nc.feedback.report(
+            "solve_1", outcome="rejected", reason="invalid-response", context="3rd retry"
+        )
+
+        assert script.requests[0].method == "POST"
+        assert script.requests[0].url.path == "/v1/solves/solve_1/feedback"
+        assert script.body_of(0) == {
+            "outcome": "rejected",
+            "reason": "invalid-response",
+            "context": "3rd retry",
+        }
+        assert result.outcome == "rejected"
+        assert result.context == "3rd retry"
+
+    def test_omits_fields_the_caller_left_unset(self) -> None:
+        script = Script((200, feedback_payload()))
+        client_for(script).feedback.report("solve_1", outcome="accepted")
+        assert script.body_of(0) == {"outcome": "accepted"}
+
+    def test_sends_an_empty_context(self) -> None:
+        # `if context:` would drop an empty string, which is a deliberate "I have
+        # nothing to add" rather than an omission. Only None means unset.
+        script = Script((200, feedback_payload(context="")))
+        client_for(script).feedback.report("solve_1", outcome="accepted", context="")
+        assert script.body_of(0) == {"outcome": "accepted", "context": ""}
+
+    def test_serializes_a_datetime_reported_at(self) -> None:
+        script = Script((200, feedback_payload()))
+        client_for(script).feedback.report(
+            "solve_1",
+            outcome="accepted",
+            reported_at=datetime(2026, 8, 1, 14, 3, tzinfo=timezone.utc),
+        )
+        assert script.body_of(0)["reported_at"] == "2026-08-01T14:03:00+00:00"
+
+    def test_raises_not_found_for_an_unreportable_solve(self) -> None:
+        script = Script((404, error_payload("not_found", "solve not found or not reportable")))
+        with pytest.raises(NotFoundError):
+            client_for(script).feedback.report("solve_x", outcome="accepted")
+
+    def test_raises_validation_error_once_the_window_closed(self) -> None:
+        script = Script(
+            (422, error_payload("expired_window", "solve is too old", param="solve_id"))
+        )
+        with pytest.raises(ValidationError) as excinfo:
+            client_for(script).feedback.report("solve_old", outcome="accepted")
+        assert excinfo.value.code == "expired_window"
+        assert excinfo.value.param == "solve_id"
+
+
+class TestReportMany:
+    def test_posts_one_batch_under_the_wire_format(self) -> None:
+        script = Script(batch_payload)
+        batch = client_for(script).feedback.report_many(
+            [
+                {"solve_id": "solve_1", "outcome": "accepted"},
+                {"solve_id": "solve_2", "outcome": "rejected", "context": "3rd retry"},
+            ]
+        )
+
+        assert len(script.requests) == 1
+        assert script.requests[0].url.path == "/v1/feedback"
+        assert script.body_of(0) == {
+            "feedback": [
+                {"solve_id": "solve_1", "outcome": "accepted"},
+                {"solve_id": "solve_2", "outcome": "rejected", "context": "3rd retry"},
+            ]
+        }
+        assert batch.recorded == 2
+        assert [r.solve_id for r in batch.results] == ["solve_1", "solve_2"]
+
+    def test_empty_sequence_makes_no_request(self) -> None:
+        script = Script((500, {}))
+        batch = client_for(script).feedback.report_many([])
+        assert script.requests == []
+        assert (batch.recorded, batch.updated, batch.unchanged, batch.failed) == (0, 0, 0, 0)
+        assert batch.results == []
+
+    def test_splits_over_the_batch_cap_and_merges_in_order(self) -> None:
+        reports: list[FeedbackReport] = [
+            {"solve_id": f"solve_{i}", "outcome": "accepted"}
+            for i in range(FEEDBACK_BATCH_MAX + 3)
+        ]
+        script = Script(batch_payload)
+        batch = client_for(script).feedback.report_many(reports)
+
+        assert len(script.requests) == 2
+        assert len(script.body_of(0)["feedback"]) == FEEDBACK_BATCH_MAX
+        assert len(script.body_of(1)["feedback"]) == 3
+        assert batch.recorded == FEEDBACK_BATCH_MAX + 3
+        assert [r.solve_id for r in batch.results] == [r["solve_id"] for r in reports]
+
+    def test_does_not_raise_when_individual_items_fail(self) -> None:
+        script = Script(
+            (
+                200,
+                {
+                    "object": "feedback_batch",
+                    "recorded": 1,
+                    "updated": 0,
+                    "unchanged": 0,
+                    "failed": 1,
+                    "results": [
+                        {"solve_id": "solve_1", "status": "recorded", "error": None},
+                        {
+                            "solve_id": "solve_x",
+                            "status": "error",
+                            "error": {
+                                "code": "not_eligible",
+                                "message": "solve not found or not reportable",
+                                "param": "solve_id",
+                            },
+                        },
+                    ],
+                },
+            )
+        )
+        batch = client_for(script).feedback.report_many(
+            [
+                {"solve_id": "solve_1", "outcome": "accepted"},
+                {"solve_id": "solve_x", "outcome": "accepted"},
+            ]
+        )
+        assert batch.failed == 1
+        assert batch.results[1].error is not None
+        assert batch.results[1].error.code == "not_eligible"
+
+
+class TestAsyncFeedback:
+    async def test_report(self) -> None:
+        script = Script((200, feedback_payload(outcome="unused")))
+        async with async_client_for(script) as nc:
+            result = await nc.feedback.report("solve_1", outcome="unused")
+        assert script.requests[0].url.path == "/v1/solves/solve_1/feedback"
+        assert script.body_of(0) == {"outcome": "unused"}
+        assert result.outcome == "unused"
+
+    async def test_report_many_splits_over_the_batch_cap(self) -> None:
+        reports: list[FeedbackReport] = [
+            {"solve_id": f"solve_{i}", "outcome": "accepted"}
+            for i in range(FEEDBACK_BATCH_MAX + 1)
+        ]
+        script = Script(batch_payload)
+        async with async_client_for(script) as nc:
+            batch = await nc.feedback.report_many(reports)
+
+        assert len(script.requests) == 2
+        assert batch.recorded == FEEDBACK_BATCH_MAX + 1
+        assert [r.solve_id for r in batch.results] == [r["solve_id"] for r in reports]
+
+    async def test_report_many_empty_makes_no_request(self) -> None:
+        script = Script((500, {}))
+        async with async_client_for(script) as nc:
+            batch = await nc.feedback.report_many([])
+        assert script.requests == []
+        assert batch.results == []

{nonecap-0.2.0 → nonecap-0.4.0}/tests/typing_assertions.py

@@ -15,6 +15,9 @@ from typing import Optional
 from nonecap import (
     AsyncNoneCap,
     AsyncSolveHandle,
+    Feedback,
+    FeedbackBatch,
+    FeedbackReport,
     NoneCap,
     Solve,
     SolveHandle,
@@ -51,6 +54,27 @@ async def positive_cases_async() -> None:
     _c: Solve = await handle.cancel()
 
 
+def feedback_cases() -> None:
+    _f: Feedback = nc.feedback.report("solve_1", outcome="accepted")
+    nc.feedback.report("solve_1", outcome="rejected", reason="why", context="ctx")
+    reports: list[FeedbackReport] = [
+        {"solve_id": "solve_1", "outcome": "accepted"},
+        {"solve_id": "solve_2", "outcome": "rejected", "reason": "why", "context": "ctx"},
+    ]
+    _b: FeedbackBatch = nc.feedback.report_many(reports)
+    # An unknown outcome must not type-check.
+    nc.feedback.report("solve_1", outcome="maybe")  # type: ignore[arg-type]
+    # A report missing `outcome` must not type-check.
+    _bad: FeedbackReport = {"solve_id": "solve_1"}  # type: ignore[typeddict-item]
+
+
+async def feedback_cases_async() -> None:
+    _f: Feedback = await anc.feedback.report("solve_1", outcome="unused")
+    _b: FeedbackBatch = await anc.feedback.report_many(
+        [{"solve_id": "solve_1", "outcome": "accepted"}]
+    )
+
+
 def negative_cases() -> None:
     # Enterprise without rqdata must not type-check.
     nc.solve(type="hcaptcha_enterprise", sitekey="s", url="u")  # type: ignore[call-overload]

nonecap-0.2.0/src/nonecap/_types.py

@@ -1,131 +0,0 @@
-"""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."""
-
-    object: str
-    data: list[Solve]
-    has_more: bool
-
-    @classmethod
-    def _from_dict(cls, payload: dict[str, Any]) -> SolvePage:
-        return cls(
-            object=payload.get("object", "list"),
-            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."""
-
-    object: str
-    id: str
-    email: str
-    credits_balance: int
-    created_at: str
-
-    @classmethod
-    def _from_dict(cls, data: dict[str, Any]) -> Account:
-        return cls(
-            object=data.get("object", "account"),
-            id=data["id"],
-            email=data.get("email", ""),
-            credits_balance=int(data.get("credits_balance", 0)),
-            created_at=data.get("created_at", ""),
-        )

nonecap-0.2.0/src/nonecap/_version.py

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