client: Add demo fallback handling for 404 file-info lookups

- Introduced `_is_demo_fallback_file_id` and `_build_demo_fallback_file`
  to detect and return placeholder metadata for missing demo fallback files.
- Updated `file_info` and `async_file_info` methods to return fallback data
  when a 404 error is encountered with a demo fallback file ID.
- Improved logging to notify users when fallback data is being returned.

tests: Add coverage for demo fallback file handling

- Added tests to validate sync and async handling of demo fallback files.
- Verified proper logging when returning placeholder metadata for 404 cases.

Assisted-by: Codex

Author: datalogics-kam

src/pdfrest/client.py

@@ -187,6 +187,11 @@
 RETRYABLE_STATUS_CODES = {408, 425, 429, 499}
 _SUCCESSFUL_DELETION_MESSAGE = "successfully deleted"
 _DEMO_RESTRICTION_MESSAGE_FIELDS = ("message", "warning", "keyMessage")
+_DEMO_FALLBACK_FILE_ID = "00000000-0000-4000-8000-000000000000"
+_DEMO_FALLBACK_FILE_URL = "https://pdfrest.com/demo-redacted"
+_DEMO_FALLBACK_MIME_TYPE = "application/octet-stream"
+_DEMO_FALLBACK_FILE_NAME = "demo-redacted.bin"
+_DEMO_FALLBACK_FILE_SIZE = 1
 
 
 HttpMethod = Literal["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"]
@@ -314,6 +319,23 @@ def _extract_uploaded_file_ids(payload: Any) -> list[str]:
     return file_ids
 
 
+def _is_demo_fallback_file_id(file_id: str) -> bool:
+    return file_id.strip().lower() == _DEMO_FALLBACK_FILE_ID
+
+
+def _build_demo_fallback_file(file_id: str) -> PdfRestFile:
+    return PdfRestFile.model_validate(
+        {
+            "id": file_id,
+            "name": _DEMO_FALLBACK_FILE_NAME,
+            "url": _DEMO_FALLBACK_FILE_URL,
+            "type": _DEMO_FALLBACK_MIME_TYPE,
+            "size": _DEMO_FALLBACK_FILE_SIZE,
+            "modified": datetime.now(timezone.utc),
+        }
+    )
+
+
 def _handle_deletion_failures(response: PdfRestDeletionResponse) -> None:
     failures: list[PdfRestDeleteError] = []
     for file_id, result in response.deletion_responses.items():
@@ -1193,7 +1215,17 @@ def fetch_file_info(
             extra_headers=extra_headers,
             timeout=timeout,
         )
-        payload = self._send_request(request)
+        try:
+            payload = self._send_request(request)
+        except PdfRestApiError as exc:
+            if exc.status_code == 404 and _is_demo_fallback_file_id(file_id):
+                self._logger.warning(
+                    "Demo fallback file id %s was not found during file-info lookup; "
+                    "returning placeholder metadata.",
+                    file_id,
+                )
+                return _build_demo_fallback_file(file_id)
+            raise
         return PdfRestFile.model_validate(payload)
 
 
@@ -1468,7 +1500,17 @@ async def fetch_file_info(
             extra_headers=extra_headers,
             timeout=timeout,
         )
-        payload = await self._send_request(request)
+        try:
+            payload = await self._send_request(request)
+        except PdfRestApiError as exc:
+            if exc.status_code == 404 and _is_demo_fallback_file_id(file_id):
+                self._logger.warning(
+                    "Demo fallback file id %s was not found during file-info lookup; "
+                    "returning placeholder metadata.",
+                    file_id,
+                )
+                return _build_demo_fallback_file(file_id)
+            raise
         return PdfRestFile.model_validate(payload)
 
 

tests/test_unzip_file.py

@@ -357,3 +357,94 @@ def handler(request: httpx.Request) -> httpx.Response:
         "Demo value XXXXXXXXX-XXXXXXXXX-XXXX-XXXXXXXXXXXX detected in id; "
         "replaced with 00000000-0000-4000-8000-000000000000" in caplog.text
     )
+
+
+def test_unzip_file_demo_fallback_file_info_on_404(
+    monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
+) -> None:
+    monkeypatch.delenv("PDFREST_API_KEY", raising=False)
+    caplog.set_level(logging.WARNING, logger="pdfrest.client")
+    zip_file = make_zip_file(str(PdfRestFileID.generate()))
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        if request.method == "POST" and request.url.path == "/unzip":
+            return httpx.Response(
+                200,
+                json={
+                    "inputId": [zip_file.id],
+                    "files": [
+                        {
+                            "name": "inner.txt",
+                            "id": DEMO_REPLACEMENT_ID,
+                            "outputUrl": None,
+                        }
+                    ],
+                },
+            )
+        if (
+            request.method == "GET"
+            and request.url.path == f"/resource/{DEMO_REPLACEMENT_ID}"
+        ):
+            return httpx.Response(404, json={"error": "The file does not exist."})
+        msg = f"Unexpected request {request.method} {request.url}"
+        raise AssertionError(msg)
+
+    transport = httpx.MockTransport(handler)
+    with PdfRestClient(api_key=VALID_API_KEY, transport=transport) as client:
+        response = client.unzip_file(zip_file)
+
+    assert response.output_file.id == DEMO_REPLACEMENT_ID
+    assert response.output_file.name == "demo-redacted.bin"
+    assert str(response.output_file.url) == "https://pdfrest.com/demo-redacted"
+    assert response.output_file.type == "application/octet-stream"
+    assert response.output_file.size == 1
+    assert (
+        "Demo fallback file id 00000000-0000-4000-8000-000000000000 was not found "
+        "during file-info lookup; returning placeholder metadata." in caplog.text
+    )
+
+
+@pytest.mark.asyncio
+async def test_async_unzip_file_demo_fallback_file_info_on_404(
+    monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
+) -> None:
+    monkeypatch.delenv("PDFREST_API_KEY", raising=False)
+    caplog.set_level(logging.WARNING, logger="pdfrest.client")
+    zip_file = make_zip_file(str(PdfRestFileID.generate()))
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        if request.method == "POST" and request.url.path == "/unzip":
+            return httpx.Response(
+                200,
+                json={
+                    "inputId": [zip_file.id],
+                    "files": [
+                        {
+                            "name": "inner-async.txt",
+                            "id": DEMO_REPLACEMENT_ID,
+                            "outputUrl": None,
+                        }
+                    ],
+                },
+            )
+        if (
+            request.method == "GET"
+            and request.url.path == f"/resource/{DEMO_REPLACEMENT_ID}"
+        ):
+            return httpx.Response(404, json={"error": "The file does not exist."})
+        msg = f"Unexpected request {request.method} {request.url}"
+        raise AssertionError(msg)
+
+    transport = httpx.MockTransport(handler)
+    async with AsyncPdfRestClient(api_key=ASYNC_API_KEY, transport=transport) as client:
+        response = await client.unzip_file(zip_file)
+
+    assert response.output_file.id == DEMO_REPLACEMENT_ID
+    assert response.output_file.name == "demo-redacted.bin"
+    assert str(response.output_file.url) == "https://pdfrest.com/demo-redacted"
+    assert response.output_file.type == "application/octet-stream"
+    assert response.output_file.size == 1
+    assert (
+        "Demo fallback file id 00000000-0000-4000-8000-000000000000 was not found "
+        "during file-info lookup; returning placeholder metadata." in caplog.text
+    )