Check the inner status envelope, not only the outer

The API answers with two envelopes: body.status reports that the request
reached the instance, body.data.status reports whether the instance carried
the action out. The inner one is authoritative.

Only the outer was checked, so a malformed chatId -- {"status": "success",
"data": {"status": "error", "message": "incorrect chatId format."}} --
returned as a successful send. Nothing was delivered and the caller had no way
to know.

Verified against the live API on send-message, download-media,
get-message-by-id, send-seen, get-profile-pic-url and fetch-messages: all six
report input errors this way. A data array, which several actions return, has
no status and passes the check untouched.

Author: WaAPIapp

README.md

@@ -51,10 +51,18 @@ async with AsyncWaAPI(token="YOUR_API_TOKEN", instance_id=123) as client:
 
 ## Errors
 
-A successful HTTP exchange is not proof the message was sent. The API answers
-`200` with `{"status": "error"}` when, for example, the instance is not
-connected — so the SDK raises on that too, rather than handing back a body that
-looks like success.
+A successful HTTP exchange is not proof the message was sent. The API carries
+two envelopes:
+
+| Field | Answers |
+|---|---|
+| `status` | did the request reach the instance |
+| `data.status` | did the instance carry the action out |
+
+**The inner one is authoritative.** A malformed chat ID comes back as
+`{"status": "success", "data": {"status": "error", …}}` — nothing was sent. The
+SDK raises `FailedActionError` on either envelope, so neither case reaches you
+looking like success.
 
 ```python
 from waapi import WaAPI, FailedActionError, AuthenticationError, RateLimitError

src/waapi/_http.py

@@ -73,20 +73,33 @@ def interpret(response: httpx.Response, *, check_body_status: bool = True) -> An
     if not 200 <= status < 300:
         raise WaAPIError(f"WaAPI returned HTTP {status}: {_brief(body)}")
 
-    # A 2xx is not proof the action happened. The API answers 200 with
-    # {"status": "error"} when, for example, the instance is not connected.
+    # Two envelopes, and the inner one is the authoritative answer:
+    #
+    #   body.status        did the request reach the instance
+    #   body.data.status   did the instance carry the action out
+    #
+    # A malformed chatId comes back as {"status": "success", "data":
+    # {"status": "error", "message": "incorrect chatId format."}} -- nothing
+    # was sent. Checking only the outer envelope reports that as delivered,
+    # which is the exact failure this class exists to prevent, one level down.
     if check_body_status and isinstance(body, Mapping):
-        envelope = body.get("status")
-        if envelope is not None and envelope != "success":
-            raise FailedActionError(
-                "WaAPI accepted the request but did not carry the action out: "
-                + _brief(body),
-                body,
-            )
+        for envelope in (_inner_status(body), body.get("status")):
+            if envelope is not None and envelope != "success":
+                raise FailedActionError(
+                    "WaAPI accepted the request but did not carry the action out: "
+                    + _brief(body),
+                    body,
+                )
 
     return body
 
 
+def _inner_status(body: Mapping[str, Any]) -> Any:
+    """``body.data.status`` when the response wraps a client action."""
+    data = body.get("data")
+    return data.get("status") if isinstance(data, Mapping) else None
+
+
 def _brief(body: Any, limit: int = 400) -> str:
     text = body if isinstance(body, str) else _json.dumps(body, ensure_ascii=False)
     return text if len(text) <= limit else text[:limit] + "..."

tests/test_client.py

@@ -212,3 +212,26 @@ def test_the_generated_surface_is_not_empty():
 
     methods = {n for n in vars(GeneratedActions) if not n.startswith("_")}
     assert len(methods) > 100, f"only {len(methods)} generated methods"
+
+
+def test_the_inner_status_is_the_authoritative_one():
+    """A request can reach the instance and still not be carried out.
+
+    The outer envelope reports delivery to the instance; the inner one reports
+    whether the instance did the thing. A malformed chatId produces
+    success-outside, error-inside — and was reported as sent until the check
+    looked one level down.
+    """
+    client = client_returning(200, {
+        "status": "success",
+        "data": {"status": "error", "message": "incorrect chatId format."},
+    })
+    with pytest.raises(FailedActionError) as excinfo:
+        client.send_message(chat_id="bogus", message="must not count as sent")
+    assert "did not carry the action out" in str(excinfo.value)
+
+
+def test_a_data_array_does_not_trip_the_inner_check():
+    """Plenty of actions return a list in `data`, which has no status at all."""
+    client = client_returning(200, {"status": "success", "data": [{"id": 1}, {"id": 2}]})
+    assert client.get_chats()["data"] == [{"id": 1}, {"id": 2}]