client: Log and test demo restriction messages in API responses

- Added `_log_demo_restriction_messages` to log when API responses include
  demo mode restriction messages in specific fields (`message`, `warning`,
  `keyMessage`) for both sync and async clients.
- Introduced `_is_demo_restriction_message` utility to identify demo-related
  restriction messages based on known patterns.
- Updated documentation in `getting-started.md` with examples of these
  log messages and how to configure logging for monitoring.
- Created new test cases to validate the detection and logging of demo
  restriction messages:
  - Tests ensure messages are logged once even if duplicated across fields.
  - Verified async and sync clients handle and log these cases consistently.

Assisted-by: Codex

Author: datalogics-kam

docs/getting-started.md

@@ -90,13 +90,19 @@ When a replacement happens, the SDK logs a warning in this format:
 
 `Demo value <val> detected in <field-name>; replaced with <replacement>`
 
+When the API returns a demo restriction body message (for example the free-tier
+"watermarked or redacted" notice in `message`), the SDK also logs:
+
+`Demo mode restriction message in response <METHOD URL> field=<field>: <message>`
+
 To see these warnings in your app, configure Python logging (example):
 
 ```python
 import logging
 
 logging.basicConfig(level=logging.WARNING)
 logging.getLogger("pdfrest.models").setLevel(logging.WARNING)
+logging.getLogger("pdfrest.client").setLevel(logging.WARNING)
 ```
 
 ## 3. Add a short example program

src/pdfrest/client.py

@@ -192,6 +192,7 @@
 BACKOFF_JITTER_SECONDS = 0.1
 RETRYABLE_STATUS_CODES = {408, 425, 429, 499}
 _SUCCESSFUL_DELETION_MESSAGE = "successfully deleted"
+_DEMO_RESTRICTION_MESSAGE_FIELDS = ("message", "warning", "keyMessage")
 
 
 HttpMethod = Literal["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"]
@@ -263,6 +264,17 @@ def _parse_retry_after_header(header_value: str | None) -> float | None:
     return seconds if seconds > 0 else 0.0
 
 
+def _is_demo_restriction_message(value: str) -> bool:
+    normalized = value.strip().casefold()
+    if not normalized:
+        return False
+    return (
+        "watermarked or redacted" in normalized
+        and "free account" in normalized
+        and "upgrade your plan" in normalized
+    )
+
+
 FileContent = IO[bytes] | bytes | str
 FileTuple2 = tuple[str | None, FileContent]
 FileTuple3 = tuple[str | None, FileContent, str | None]
@@ -836,11 +848,13 @@ def _handle_response(self, response: httpx.Response) -> Any:
             f"{getattr(request, 'method', 'UNKNOWN')} {getattr(request, 'url', '')}"
         )
         if response.is_success:
+            payload = self._decode_json(response)
+            self._log_demo_restriction_messages(payload, request_label)
             if self._logger.isEnabledFor(logging.DEBUG):
                 self._logger.debug(
                     "Response %s status=%s", request_label, response.status_code
                 )
-            return self._decode_json(response)
+            return payload
 
         message, error_payload = self._extract_error_details(response)
         retry_after = _parse_retry_after_header(response.headers.get("Retry-After"))
@@ -888,6 +902,30 @@ def _decode_json(self, response: httpx.Response) -> Any:
                 response_content=response.text,
             ) from exc
 
+    def _log_demo_restriction_messages(self, payload: Any, request_label: str) -> None:
+        if not isinstance(payload, Mapping):
+            return
+
+        typed_payload = cast(Mapping[str, Any], payload)
+        emitted_messages: set[str] = set()
+        for field_name in _DEMO_RESTRICTION_MESSAGE_FIELDS:
+            value = typed_payload.get(field_name)
+            if not isinstance(value, str):
+                continue
+            message = value.strip()
+            if not _is_demo_restriction_message(message):
+                continue
+            normalized_message = message.casefold()
+            if normalized_message in emitted_messages:
+                continue
+            emitted_messages.add(normalized_message)
+            self._logger.warning(
+                "Demo mode restriction message in response %s field=%s: %s",
+                request_label,
+                field_name,
+                message,
+            )
+
     @staticmethod
     def _extract_error_details(
         response: httpx.Response,

tests/test_client.py

@@ -25,6 +25,11 @@
 VALID_API_KEY = "12345678-1234-1234-1234-123456789abc"
 ANOTHER_VALID_API_KEY = "abcdefab-cdef-abcd-efab-cdefabcdef12"
 ASYNC_API_KEY = "fedcba98-7654-3210-fedc-ba9876543210"
+DEMO_RESTRICTION_MESSAGE = (
+    "Output has been watermarked or redacted. This API request was processed "
+    "with a free account. Visit https://pdfrest.com/pricing/ to upgrade your "
+    "plan and receive outputs without watermarks or redactions."
+)
 
 
 def _build_up_response() -> dict[str, Any]:
@@ -709,6 +714,107 @@ def handler(_: httpx.Request) -> httpx.Response:
     assert exc.value.response_content == "not-json"
 
 
+def test_client_logs_demo_restriction_message_warning(
+    monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
+) -> None:
+    monkeypatch.setenv("PDFREST_API_KEY", VALID_API_KEY)
+    caplog.set_level("WARNING", logger="pdfrest.client")
+
+    def handler(_: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            200,
+            json={**_build_up_response(), "message": DEMO_RESTRICTION_MESSAGE},
+        )
+
+    transport = httpx.MockTransport(handler)
+    with PdfRestClient(transport=transport) as client:
+        _ = client.up()
+
+    assert "Demo mode restriction message in response" in caplog.text
+    assert "field=message" in caplog.text
+    assert DEMO_RESTRICTION_MESSAGE in caplog.text
+
+
+@pytest.mark.parametrize(
+    ("field_name", "body_value"),
+    [
+        pytest.param("message", DEMO_RESTRICTION_MESSAGE, id="message"),
+        pytest.param("warning", DEMO_RESTRICTION_MESSAGE, id="warning"),
+        pytest.param("keyMessage", DEMO_RESTRICTION_MESSAGE, id="key-message"),
+    ],
+)
+def test_client_logs_demo_restriction_message_warning_all_fields(
+    monkeypatch: pytest.MonkeyPatch,
+    caplog: pytest.LogCaptureFixture,
+    field_name: str,
+    body_value: str,
+) -> None:
+    monkeypatch.setenv("PDFREST_API_KEY", VALID_API_KEY)
+    caplog.set_level("WARNING", logger="pdfrest.client")
+
+    def handler(_: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            200,
+            json={**_build_up_response(), field_name: body_value},
+        )
+
+    transport = httpx.MockTransport(handler)
+    with PdfRestClient(transport=transport) as client:
+        _ = client.up()
+
+    assert "Demo mode restriction message in response" in caplog.text
+    assert f"field={field_name}" in caplog.text
+    assert DEMO_RESTRICTION_MESSAGE in caplog.text
+
+
+def test_client_logs_demo_restriction_message_once_when_duplicated(
+    monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
+) -> None:
+    monkeypatch.setenv("PDFREST_API_KEY", VALID_API_KEY)
+    caplog.set_level("WARNING", logger="pdfrest.client")
+
+    def handler(_: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            200,
+            json={
+                **_build_up_response(),
+                "message": DEMO_RESTRICTION_MESSAGE,
+                "warning": DEMO_RESTRICTION_MESSAGE,
+                "keyMessage": DEMO_RESTRICTION_MESSAGE,
+            },
+        )
+
+    transport = httpx.MockTransport(handler)
+    with PdfRestClient(transport=transport) as client:
+        _ = client.up()
+
+    demo_logs = [
+        record.message
+        for record in caplog.records
+        if "Demo mode restriction message in response" in record.message
+    ]
+    assert len(demo_logs) == 1
+
+
+def test_client_does_not_log_non_demo_key_message_warning(
+    monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
+) -> None:
+    monkeypatch.setenv("PDFREST_API_KEY", VALID_API_KEY)
+    caplog.set_level("WARNING", logger="pdfrest.client")
+
+    def handler(_: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            200,
+            json={**_build_up_response(), "keyMessage": "This is a test key"},
+        )
+
+    transport = httpx.MockTransport(handler)
+    with PdfRestClient(transport=transport) as client:
+        _ = client.up()
+
+    assert "Demo mode restriction message in response" not in caplog.text
+
+
 @pytest.mark.asyncio
 async def test_async_client_raises_for_non_json_success_response(
     monkeypatch: pytest.MonkeyPatch,
@@ -728,6 +834,61 @@ def handler(_: httpx.Request) -> httpx.Response:
     assert exc.value.response_content == "not-json"
 
 
+@pytest.mark.asyncio
+async def test_async_client_logs_demo_restriction_message_warning(
+    monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
+) -> None:
+    monkeypatch.setenv("PDFREST_API_KEY", ASYNC_API_KEY)
+    caplog.set_level("WARNING", logger="pdfrest.client")
+
+    def handler(_: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            200,
+            json={**_build_up_response(), "message": DEMO_RESTRICTION_MESSAGE},
+        )
+
+    transport = httpx.MockTransport(handler)
+    async with AsyncPdfRestClient(transport=transport) as client:
+        _ = await client.up()
+
+    assert "Demo mode restriction message in response" in caplog.text
+    assert "field=message" in caplog.text
+    assert DEMO_RESTRICTION_MESSAGE in caplog.text
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    ("field_name", "body_value"),
+    [
+        pytest.param("message", DEMO_RESTRICTION_MESSAGE, id="message"),
+        pytest.param("warning", DEMO_RESTRICTION_MESSAGE, id="warning"),
+        pytest.param("keyMessage", DEMO_RESTRICTION_MESSAGE, id="key-message"),
+    ],
+)
+async def test_async_client_logs_demo_restriction_message_warning_all_fields(
+    monkeypatch: pytest.MonkeyPatch,
+    caplog: pytest.LogCaptureFixture,
+    field_name: str,
+    body_value: str,
+) -> None:
+    monkeypatch.setenv("PDFREST_API_KEY", ASYNC_API_KEY)
+    caplog.set_level("WARNING", logger="pdfrest.client")
+
+    def handler(_: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            200,
+            json={**_build_up_response(), field_name: body_value},
+        )
+
+    transport = httpx.MockTransport(handler)
+    async with AsyncPdfRestClient(transport=transport) as client:
+        _ = await client.up()
+
+    assert "Demo mode restriction message in response" in caplog.text
+    assert f"field={field_name}" in caplog.text
+    assert DEMO_RESTRICTION_MESSAGE in caplog.text
+
+
 def test_client_uses_text_for_non_json_error_payload(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None: