refactor(types): extract ExtractionCredits to dedicated module

The extraction-credits accounting shape (cost + remainingCredits) will
surface on every future endpoint billed against the extraction-credits
bucket, not just /extraction/parse. Factor it out of types/parse.py into
its own module so other endpoints can import it without pulling in the
whole parse type tree.

Also clarify ParseBounds: document that (x, y) is the top-left corner
and that bounds share a coordinate space with the page dimensions in
ParsePageRef.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: nickwinder

src/nutrient_dws/__init__.py

@@ -19,6 +19,7 @@
     process_file_input,
     validate_file_input,
 )
+from nutrient_dws.types.extraction_credits import ExtractionCredits
 from nutrient_dws.types.parse import (
     FormulaElement,
     HandwritingElement,
@@ -42,6 +43,7 @@
 __all__ = [
     "APIError",
     "AuthenticationError",
+    "ExtractionCredits",
     "FileInput",
     "FormulaElement",
     "HandwritingElement",

src/nutrient_dws/types/extraction_credits.py

@@ -0,0 +1,21 @@
+"""Shared types for the DWS **extraction credits** billing bucket.
+
+Extraction credits are billed separately from the processor API credits
+consumed by `/build`, `/sign`, OCR, etc. The types in this module are
+intentionally endpoint-agnostic so they can be reused by any future
+endpoint that surfaces extraction-credit accounting in its response.
+"""
+
+from typing import TypedDict
+
+
+class ExtractionCredits(TypedDict, total=False):
+    """Credit accounting for one request against the extraction-credits bucket.
+
+    `cost` is the number of **extraction credits** debited by the request
+    (NOT processor API credits). `remainingCredits` is the post-debit
+    balance in the same bucket.
+    """
+
+    cost: float
+    remainingCredits: float

src/nutrient_dws/types/parse.py

@@ -14,6 +14,8 @@
 
 from typing_extensions import TypedDict
 
+from nutrient_dws.types.extraction_credits import ExtractionCredits
+
 # ---- Request types --------------------------------------------------------
 
 ParseMode = Literal["text", "structure", "understand", "agentic"]
@@ -58,7 +60,14 @@ class ParseInstructions(TypedDict, total=False):
 
 
 class ParseBounds(TypedDict):
-    """Axis-aligned bounding box, in the page's coordinate space."""
+    """Axis-aligned bounding box on the page.
+
+    `(x, y)` is the **top-left corner** of the box. The page's coordinate
+    origin is the top-left, with `x` increasing to the right and `y`
+    increasing downward. Units are pixels in the same canvas described by
+    `ParsePageRef.width` and `ParsePageRef.height` (i.e. element bounds and
+    the page dimensions share one coordinate space).
+    """
 
     x: float
     y: float
@@ -285,26 +294,18 @@ class ParseConfiguration(TypedDict, total=False):
     outputFormat: ParseOutputFormat
 
 
-class ParseExtractionCredits(TypedDict, total=False):
-    """Credit accounting for this request.
-
-    `cost` is in **extraction credits** (NOT processor API credits) and
-    `remainingCredits` is the remaining balance in the same bucket.
-    """
-
-    cost: float
-    remainingCredits: float
-
-
 class ParseUsage(TypedDict, total=False):
     """Wraps the extraction-credit accounting under its wire key.
 
     The server uses the snake_case key `data_extraction_credits` here even
     though every other field in the response is camelCase; the TypedDict
-    mirrors the wire format verbatim.
+    mirrors the wire format verbatim. The inner `ExtractionCredits` type
+    lives in `nutrient_dws.types.extraction_credits` because the same
+    credit-accounting shape will surface on future endpoints that bill
+    against the extraction-credits bucket.
     """
 
-    data_extraction_credits: ParseExtractionCredits
+    data_extraction_credits: ExtractionCredits
 
 
 class ParseFailingPath(TypedDict, total=False):

tests/unit/test_parse.py

@@ -1,8 +1,7 @@
 """Unit tests for `NutrientClient.parse()`.
 
 These tests stub `send_request` so they exercise the request-shape and
-response-handling logic of `parse()` without making a real HTTP call. The
-live smoke check is `examples/src/smoke_parse.py`.
+response-handling logic of `parse()` without making a real HTTP call.
 """
 
 import json