feat(client): route parse() via DWS Extract key and reject text+spatial

DWS Extract is a separate product from DWS Processor with its own API key
and credit pool. Calling /extraction/parse with the Processor key returns
403. Add an optional extract_api_key constructor parameter (str or async
callable) that parse() prefers over api_key when set; non-parse methods
keep using api_key. Falling back to api_key keeps a single-key setup
working once tenants get global DWS keys.

Also reject mode='text' + output_format='spatial' before the request goes
out — the text mode only produces markdown, so the combination would 502
on the server side. Surface it as a ValidationError with guidance.

Addresses PR #47 review feedback from HungKNguyen.

Author: nickwinder

README.md

@@ -94,6 +94,15 @@ For a complete list of available methods with examples, see the [Methods Documen
 **content-extraction workflows** where you need to feed document content into a
 downstream pipeline rather than render or transform the document itself:
 
+> **Heads up — separate API key.** DWS Extract is a different product from
+> DWS Processor and has its own API key. Pass it as
+> `NutrientClient(api_key=..., extract_api_key=...)`; the Extract key is
+> used only for `parse()`, while every other method continues to use the
+> Processor key. Using the Processor key against `/extraction/parse`
+> returns `403`. If `extract_api_key` is omitted, `parse()` falls back to
+> the main `api_key` — that path works once your tenant moves to global
+> DWS API keys.
+
 - **RAG (retrieval-augmented generation) pipelines** — pull a clean Markdown
   representation of a document for chunking, embedding, and indexing in a
   vector store.
@@ -114,14 +123,21 @@ downstream pipeline rather than render or transform the document itself:
 | `markdown`        | RAG, search indexing, content migration — anywhere structured text beats spatial data | One whole-document Markdown string at `response['output']['markdown']` |
 | `spatial` (default) | Form/invoice extraction, layout reconstruction, flows that need per-element confidence | Flat list of typed elements at `response['output']['elements']`        |
 
+Spatial output requires an OCR-capable mode (`structure`, `understand`, or
+`agentic`); `mode='text'` is markdown-only and the client rejects the
+`text` + `spatial` combination before the request goes out.
+
 ### Quick start
 
 ```python
 import asyncio
 from nutrient_dws import NutrientClient
 
 async def main():
-    client = NutrientClient(api_key='your_api_key')
+    client = NutrientClient(
+        api_key='your_processor_key',
+        extract_api_key='your_extract_key',
+    )
 
     # Spatial elements (default) — paragraphs, tables, formulas, pictures, etc.
     response = await client.parse('contract.pdf', mode='understand')

src/nutrient_dws/client.py

@@ -117,26 +117,47 @@ async def get_token():
 
         client = NutrientClient(api_key=get_token)
         ```
+
+        Data Extraction requires a separate DWS Extract API key — supply it
+        alongside the Processor key:
+
+        ```python
+        client = NutrientClient(
+            api_key='your_processor_key',
+            extract_api_key='your_extract_key',
+        )
+        ```
     """
 
     def __init__(
         self,
         api_key: str | Callable[[], str | Awaitable[str]],
         base_url: str | None = None,
         timeout: int | None = None,
+        extract_api_key: str | Callable[[], str | Awaitable[str]] | None = None,
     ) -> None:
         """Create a new NutrientClient instance.
 
         Args:
-            api_key: API key or API key getter
+            api_key: API key or API key getter for the DWS Processor product
+                (used by every method except `parse()`).
             base_url: DWS Base url
             timeout: DWS request timeout
+            extract_api_key: Optional API key or getter for the DWS Extract
+                product. Required by `parse()` because DWS Extract is a
+                separate product with its own credit pool and API key — using
+                the Processor key will return 403. If omitted, `parse()`
+                falls back to `api_key`, which works once DWS rolls out
+                global API keys.
 
         Raises:
             ValidationError: If options are invalid
         """
         options = NutrientClientOptions(
-            apiKey=api_key, baseUrl=base_url, timeout=timeout
+            apiKey=api_key,
+            baseUrl=base_url,
+            timeout=timeout,
+            extractApiKey=extract_api_key,
         )
         self._validate_options(options)
         self.options = options
@@ -166,6 +187,14 @@ def _validate_options(self, options: NutrientClientOptions) -> None:
         if base_url is not None and not isinstance(base_url, str):
             raise ValidationError("Base URL must be a string")
 
+        extract_api_key = options.get("extractApiKey")
+        if extract_api_key is not None and not (
+            isinstance(extract_api_key, str) or callable(extract_api_key)
+        ):
+            raise ValidationError(
+                "Extract API key must be a string or a function that returns a string"
+            )
+
     async def get_account_info(self) -> AccountInfo:
         """Get account information for the current API key.
 
@@ -784,6 +813,11 @@ async def parse(
         See the README's Data Extraction section for worked recipes (RAG
         ingestion, form extraction) and per-mode positioning.
 
+        DWS Extract is a separate product from DWS Processor and uses its own
+        API key. Pass it via `NutrientClient(extract_api_key=...)`. If omitted
+        the method falls back to the main `api_key`, which only succeeds when
+        the key is a global DWS key.
+
         The Data Extraction API is billed against **extraction credits**, which
         are a separate billing bucket from the **processor API credits**
         consumed by `/build`, `/sign`, OCR, and other Processor API endpoints.
@@ -803,7 +837,9 @@ async def parse(
 
         - `spatial` (default): `output.elements` — typed elements (paragraph,
           table, formula, picture, keyValueRegion, handwriting) with bounds,
-          confidence, and reading order.
+          confidence, and reading order. Requires an OCR-capable mode
+          (`structure`, `understand`, or `agentic`); `text` mode does not
+          produce spatial output.
         - `markdown`: `output.markdown` — a whole-document Markdown string,
           well suited for RAG / search indexing pipelines.
 
@@ -822,12 +858,17 @@ async def parse(
                 to `"structure"`.
             output_format: Output shape — `"spatial"` for typed elements or
                 `"markdown"` for a Markdown document. Defaults to
-                `"spatial"`.
+                `"spatial"`. `mode="text"` is incompatible with
+                `output_format="spatial"`.
 
         Returns:
             The full parse response envelope, including `output`, `metrics`,
             `usage` (the extraction-credit accounting), and `configuration`.
 
+        Raises:
+            ValidationError: If `mode="text"` is combined with
+                `output_format="spatial"`.
+
         Example:
             ```python
             # Spatial elements with full layout analysis (9 extraction credits / page)
@@ -848,6 +889,13 @@ async def parse(
                   f"(remaining: {usage['remainingCredits']})")
             ```
         """
+        if mode == "text" and output_format == "spatial":
+            raise ValidationError(
+                "mode='text' is not supported with output_format='spatial'. "
+                "Use output_format='markdown', or choose mode='structure' / "
+                "'understand' / 'agentic' for spatial elements."
+            )
+
         # Multipart-only endpoint; only local file inputs are supported.
         normalized_file = await process_file_input(file)
 
@@ -861,14 +909,22 @@ async def parse(
             "instructions": instructions,
         }
 
+        # DWS Extract uses a separate API key. Route the request via a
+        # per-call options copy so the rest of the client (which talks to
+        # the Processor API) keeps using the main key.
+        parse_options = self.options.copy()
+        extract_key = parse_options.get("extractApiKey")
+        if extract_key is not None:
+            parse_options["apiKey"] = extract_key
+
         response: Any = await send_request(
             {
                 "method": "POST",
                 "endpoint": "/extraction/parse",
                 "data": request_data,
                 "headers": None,
             },
-            self.options,
+            parse_options,
         )
         return cast("ParseResponse", response["data"])
 

src/nutrient_dws/http.py

@@ -190,6 +190,9 @@ class NutrientClientOptions(TypedDict):
     apiKey: str | Callable[[], str | Awaitable[str]]
     baseUrl: str | None
     timeout: int | None
+    # DWS Extract is a separate product with its own API key; parse() prefers
+    # this when set, otherwise falls back to apiKey.
+    extractApiKey: NotRequired[str | Callable[[], str | Awaitable[str]] | None]
 
 
 async def resolve_api_key(api_key: str | Callable[[], str | Awaitable[str]]) -> str:

tests/conftest.py

@@ -1,9 +1,11 @@
 from unittest.mock import AsyncMock
 
 import pytest
+
 from nutrient_dws import NutrientClient
 from tests.helpers import TestDocumentGenerator
 
+
 @pytest.fixture
 def mock_workflow_instance():
     """Create a mock workflow instance for testing."""
@@ -40,7 +42,12 @@ def mock_workflow_instance():
 @pytest.fixture
 def valid_client_options():
     """Valid client options for testing."""
-    return {"apiKey": "test-api-key", "baseUrl": "https://api.test.com/v1", "timeout": None}
+    return {
+        "apiKey": "test-api-key",
+        "baseUrl": "https://api.test.com/v1",
+        "timeout": None,
+        "extractApiKey": None,
+    }
 
 @pytest.fixture
 def unit_client():

tests/unit/test_client.py

@@ -65,7 +65,12 @@ def test_create_workflow_instance(
 
     @patch("nutrient_dws.client.StagedWorkflowBuilder")
     def test_pass_client_options_to_workflow(self, mock_staged_workflow_builder):
-        custom_options = {"apiKey": "custom-key", "baseUrl": "https://custom.api.com", "timeout": None}
+        custom_options = {
+            "apiKey": "custom-key",
+            "baseUrl": "https://custom.api.com",
+            "timeout": None,
+            "extractApiKey": None,
+        }
         client = NutrientClient(api_key=custom_options["apiKey"], base_url=custom_options["baseUrl"])
 
         client.workflow()

tests/unit/test_parse.py

@@ -167,6 +167,97 @@ def test_prepare_request_body_omits_instructions_when_absent(self) -> None:
         assert "data" not in prepared
 
 
+class TestParseClientSideValidation:
+    """Combinations rejected before any network round-trip."""
+
+    @pytest.mark.asyncio
+    async def test_text_mode_with_spatial_output_raises(
+        self, parse_client: NutrientClient
+    ) -> None:
+        with patch("nutrient_dws.client.send_request", new_callable=AsyncMock) as send:
+            with pytest.raises(ValidationError, match="mode='text'"):
+                await parse_client.parse(
+                    b"%PDF-1.7", mode="text", output_format="spatial"
+                )
+            send.assert_not_called()
+
+
+class TestParseApiKeyRouting:
+    """`/extraction/parse` is served by DWS Extract, which uses a separate
+    API key from DWS Processor. When `extract_api_key` is set we route via
+    that key; otherwise we fall back to the main `api_key`.
+    """
+
+    @pytest.mark.asyncio
+    async def test_parse_uses_extract_api_key_when_set(self) -> None:
+        client = NutrientClient(
+            api_key="processor-key",
+            extract_api_key="extract-key",
+        )
+        with patch("nutrient_dws.client.send_request", new_callable=AsyncMock) as send:
+            send.return_value = _make_response(
+                {"status": 200, "requestId": "r", "output": {"elements": []}}
+            )
+
+            await client.parse(b"%PDF-1.7", mode="structure")
+
+            sent_options = send.call_args[0][1]
+
+        assert sent_options["apiKey"] == "extract-key"
+        # The client's own options are untouched — other methods still see the
+        # processor key.
+        assert client.options["apiKey"] == "processor-key"
+
+    @pytest.mark.asyncio
+    async def test_parse_falls_back_to_main_api_key_when_extract_key_unset(
+        self, parse_client: NutrientClient
+    ) -> None:
+        with patch("nutrient_dws.client.send_request", new_callable=AsyncMock) as send:
+            send.return_value = _make_response(
+                {"status": 200, "requestId": "r", "output": {"elements": []}}
+            )
+
+            await parse_client.parse(b"%PDF-1.7", mode="structure")
+
+            sent_options = send.call_args[0][1]
+
+        assert sent_options["apiKey"] == "pdf_test_unit"
+
+    @pytest.mark.asyncio
+    async def test_non_parse_methods_keep_processor_key(self) -> None:
+        """A sibling endpoint (`/account/info`) must not see the Extract
+        key — only `parse()` swaps.
+        """
+        client = NutrientClient(
+            api_key="processor-key",
+            extract_api_key="extract-key",
+        )
+        with patch("nutrient_dws.client.send_request", new_callable=AsyncMock) as send:
+            send.return_value = _make_response({"subscriptionType": "live"})
+
+            await client.get_account_info()
+
+            sent_options = send.call_args[0][1]
+
+        assert sent_options["apiKey"] == "processor-key"
+
+    def test_invalid_extract_api_key_type_raises(self) -> None:
+        with pytest.raises(
+            ValidationError,
+            match="Extract API key must be a string or a function that returns a string",
+        ):
+            NutrientClient(api_key="processor-key", extract_api_key=123)  # type: ignore[arg-type]
+
+    def test_async_extract_api_key_callable_accepted(self) -> None:
+        async def get_extract_key() -> str:
+            return "async-extract-key"
+
+        client = NutrientClient(
+            api_key="processor-key", extract_api_key=get_extract_key
+        )
+        assert callable(client.options["extractApiKey"])
+
+
 class TestParseResponseHandling:
     """Verify the client returns the raw response envelope to the caller."""
 
@@ -315,7 +406,9 @@ async def test_authentication_error_propagates(
             )
 
             with pytest.raises(AuthenticationError) as exc_info:
-                await parse_client.parse(b"%PDF-1.7", mode="text")
+                await parse_client.parse(
+                    b"%PDF-1.7", mode="text", output_format="markdown"
+                )
 
         assert exc_info.value.status_code == 401
         assert (exc_info.value.details or {}).get("requestId") == "req_e_401"
@@ -342,7 +435,10 @@ async def test_validation_error_propagates(
 
             with pytest.raises(ValidationError) as exc_info:
                 await parse_client.parse(
-                    b"%PDF-1.7", mode="text"  # mode is fine; server-side fail
+                    # client-side validation passes; failure is the mocked server response
+                    b"%PDF-1.7",
+                    mode="text",
+                    output_format="markdown",
                 )
 
         details = exc_info.value.details or {}