Add comprehensive integration tests for set_page_label method (#12)

* Add comprehensive integration tests for set_page_label method

- Add 6 new integration tests covering various scenarios:
  * Basic page labeling with output file
  * Returning bytes without output file
  * Multiple page ranges with different labels
  * Single page labeling
  * Error handling for empty labels list
  * Error handling for invalid label configurations

- Fix page range normalization to ensure 'end' field is always present
- Update page range handling to avoid overlapping ranges in tests
- Add comprehensive unit tests for validation logic
- Add Builder API support for set_page_labels method with chaining
- Update documentation with examples and usage patterns

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

* Fix unit test to expect normalized labels with 'end' field

The set_page_label implementation normalizes label configurations to ensure
the 'end' field is always present (defaulting to -1 for end of document).
Updated the unit test to expect the normalized format rather than the
original input format.

* Fix mypy type errors in tests

- Add type ignore comment for intentionally invalid test data
- Add explicit type annotations for module-level variables that can be None

* Add future annotations import for Python 3.10+ compatibility

The union syntax (str | None) requires from __future__ import annotations
for Python versions before 3.10 where it became the default.

---------

Co-authored-by: Claude <[email protected]>

Author: msch-nutrient

SUPPORTED_OPERATIONS.md

@@ -256,6 +256,40 @@ client.delete_pdf_pages(
 )
 ```
 
+### 11. `set_page_label(input_file, labels, output_path=None)`
+Sets custom labels/numbering for specific page ranges in a PDF.
+
+**Parameters:**
+- `input_file`: PDF file to process
+- `labels`: List of label configurations. Each dict must contain:
+  - `pages`: Page range dict with `start` (required) and optionally `end`
+  - `label`: String label to apply to those pages
+  - Page ranges use 0-based indexing where `end` is exclusive.
+- `output_path`: Optional path to save the output file
+
+**Returns:**
+- Processed PDF as bytes, or None if `output_path` provided
+
+**Example:**
+```python
+# Set labels for different page ranges
+client.set_page_label(
+    "document.pdf",
+    labels=[
+        {"pages": {"start": 0, "end": 3}, "label": "Introduction"},
+        {"pages": {"start": 3, "end": 10}, "label": "Chapter 1"},
+        {"pages": {"start": 10}, "label": "Appendix"}
+    ],
+    output_path="labeled_document.pdf"
+)
+
+# Set label for single page
+client.set_page_label(
+    "document.pdf",
+    labels=[{"pages": {"start": 0, "end": 1}, "label": "Cover Page"}]
+)
+```
+
 ## Builder API
 
 The Builder API allows chaining multiple operations. Like the Direct API, it automatically converts Office documents to PDF when needed:
@@ -279,6 +313,15 @@ client.build(input_file="report.docx") \
     .add_step("watermark-pdf", {"text": "CONFIDENTIAL", "width": 300, "height": 150}) \
     .add_step("flatten-annotations") \
     .execute(output_path="watermarked_report.pdf")
+
+# Setting page labels with Builder API
+client.build(input_file="document.pdf") \
+    .add_step("rotate-pages", {"degrees": 90}) \
+    .set_page_labels([
+        {"pages": {"start": 0, "end": 3}, "label": "Introduction"},
+        {"pages": {"start": 3}, "label": "Content"}
+    ]) \
+    .execute(output_path="labeled_document.pdf")
 ```
 
 ### Supported Builder Actions
@@ -289,6 +332,22 @@ client.build(input_file="report.docx") \
 4. **watermark-pdf** - Parameters: `text` or `image_url`, `width`, `height`, `opacity`, `position`
 5. **apply-redactions** - No parameters required
 
+### Builder Output Options
+
+The Builder API also supports setting output options:
+
+- **set_output_options()** - General output configuration (metadata, optimization, etc.)
+- **set_page_labels()** - Set page labels for specific page ranges
+
+Example:
+```python
+client.build("document.pdf") \
+    .add_step("rotate-pages", {"degrees": 90}) \
+    .set_output_options(metadata={"title": "My Document"}) \
+    .set_page_labels([{"pages": {"start": 0}, "label": "Chapter 1"}]) \
+    .execute("output.pdf")
+```
+
 ## API Limitations
 
 The following operations are **NOT** currently supported by the API:

src/nutrient_dws/api/direct.py

@@ -723,3 +723,106 @@ def add_page(
             return None
         else:
             return result  # type: ignore[no-any-return]
+
+    def set_page_label(
+        self,
+        input_file: FileInput,
+        labels: list[dict[str, Any]],
+        output_path: str | None = None,
+    ) -> bytes | None:
+        """Set labels for specific pages in a PDF.
+
+        Assigns custom labels/numbering to specific page ranges in a PDF document.
+        Each label configuration specifies a page range and the label text to apply.
+
+        Args:
+            input_file: Input PDF file.
+            labels: List of label configurations. Each dict must contain:
+                   - 'pages': Page range dict with 'start' (required) and optionally 'end'
+                   - 'label': String label to apply to those pages
+                   Page ranges use 0-based indexing where 'end' is exclusive.
+            output_path: Optional path to save the output file.
+
+        Returns:
+            Processed PDF as bytes, or None if output_path is provided.
+
+        Raises:
+            AuthenticationError: If API key is missing or invalid.
+            APIError: For other API errors.
+            ValueError: If labels list is empty or contains invalid configurations.
+
+        Examples:
+            # Set labels for different page ranges
+            client.set_page_label(
+                "document.pdf",
+                labels=[
+                    {"pages": {"start": 0, "end": 3}, "label": "Introduction"},
+                    {"pages": {"start": 3, "end": 10}, "label": "Chapter 1"},
+                    {"pages": {"start": 10}, "label": "Appendix"}
+                ],
+                output_path="labeled_document.pdf"
+            )
+
+            # Set label for single page
+            client.set_page_label(
+                "document.pdf",
+                labels=[{"pages": {"start": 0, "end": 1}, "label": "Cover Page"}]
+            )
+        """
+        from nutrient_dws.file_handler import prepare_file_for_upload, save_file_output
+
+        # Validate inputs
+        if not labels:
+            raise ValueError("labels list cannot be empty")
+
+        # Normalize labels to ensure proper format
+        normalized_labels = []
+        for i, label_config in enumerate(labels):
+            if not isinstance(label_config, dict):
+                raise ValueError(f"Label configuration {i} must be a dictionary")
+
+            if "pages" not in label_config:
+                raise ValueError(f"Label configuration {i} missing required 'pages' key")
+
+            if "label" not in label_config:
+                raise ValueError(f"Label configuration {i} missing required 'label' key")
+
+            pages = label_config["pages"]
+            if not isinstance(pages, dict) or "start" not in pages:
+                raise ValueError(f"Label configuration {i} 'pages' must be a dict with 'start' key")
+
+            # Normalize pages to ensure 'end' is present
+            normalized_pages = {"start": pages["start"]}
+            if "end" in pages:
+                normalized_pages["end"] = pages["end"]
+            else:
+                # If no end is specified, use -1 to indicate "to end of document"
+                normalized_pages["end"] = -1
+
+            normalized_labels.append({"pages": normalized_pages, "label": label_config["label"]})
+
+        # Prepare file for upload
+        file_field, file_data = prepare_file_for_upload(input_file, "file")
+        files = {file_field: file_data}
+
+        # Build instructions with page labels in output configuration
+        instructions = {
+            "parts": [{"file": "file"}],
+            "actions": [],
+            "output": {"labels": normalized_labels},
+        }
+
+        # Make API request
+        # Type checking: at runtime, self is NutrientClient which has _http_client
+        result = self._http_client.post(  # type: ignore[attr-defined]
+            "/build",
+            files=files,
+            json_data=instructions,
+        )
+
+        # Handle output
+        if output_path:
+            save_file_output(result, output_path)
+            return None
+        else:
+            return result  # type: ignore[no-any-return]

src/nutrient_dws/builder.py

@@ -78,6 +78,30 @@ def set_output_options(self, **options: Any) -> "BuildAPIWrapper":
         self._output_options.update(options)
         return self
 
+    def set_page_labels(self, labels: list[dict[str, Any]]) -> "BuildAPIWrapper":
+        """Set page labels for the final document.
+
+        Assigns custom labels/numbering to specific page ranges in the output PDF.
+
+        Args:
+            labels: List of label configurations. Each dict must contain:
+                   - 'pages': Page range dict with 'start' (required) and optionally 'end'
+                   - 'label': String label to apply to those pages
+                   Page ranges use 0-based indexing where 'end' is exclusive.
+
+        Returns:
+            Self for method chaining.
+
+        Example:
+            >>> builder.set_page_labels([
+        ...     {"pages": {"start": 0, "end": 3}, "label": "Introduction"},
+        ...     {"pages": {"start": 3, "end": 10}, "label": "Chapter 1"},
+        ...     {"pages": {"start": 10}, "label": "Appendix"}
+        ... ])
+        """
+        self._output_options["labels"] = labels
+        return self
+
     def execute(self, output_path: str | None = None) -> bytes | None:
         """Execute the workflow.
 

tests/integration/test_live_api.py

@@ -3,16 +3,18 @@
 These tests require a valid API key configured in integration_config.py.
 """
 
+from __future__ import annotations
+
 import pytest
 
 from nutrient_dws import NutrientClient
 
 try:
     from . import integration_config  # type: ignore[attr-defined]
 
-    API_KEY = integration_config.API_KEY
-    BASE_URL = getattr(integration_config, "BASE_URL", None)
-    TIMEOUT = getattr(integration_config, "TIMEOUT", 60)
+    API_KEY: str | None = integration_config.API_KEY
+    BASE_URL: str | None = getattr(integration_config, "BASE_URL", None)
+    TIMEOUT: int = getattr(integration_config, "TIMEOUT", 60)
 except ImportError:
     API_KEY = None
     BASE_URL = None
@@ -158,6 +160,74 @@ def test_split_pdf_single_page_default(self, client, sample_pdf_path):
         # Verify result is a valid PDF
         assert_is_pdf(result[0])
 
+    def test_set_page_label_integration(self, client, sample_pdf_path, tmp_path):
+        """Test set_page_label method with live API."""
+        labels = [{"pages": {"start": 0, "end": 1}, "label": "Cover"}]
+
+        output_path = str(tmp_path / "labeled.pdf")
+
+        # Try to set page labels
+        result = client.set_page_label(sample_pdf_path, labels, output_path=output_path)
+
+        # If successful, verify output
+        assert result is None  # Should return None when output_path provided
+        assert (tmp_path / "labeled.pdf").exists()
+        assert_is_pdf(output_path)
+
+    def test_set_page_label_return_bytes(self, client, sample_pdf_path):
+        """Test set_page_label method returning bytes."""
+        labels = [{"pages": {"start": 0, "end": 1}, "label": "i"}]
+
+        # Test getting bytes back
+        result = client.set_page_label(sample_pdf_path, labels)
+
+        assert isinstance(result, bytes)
+        assert len(result) > 0
+        assert_is_pdf(result)
+
+    def test_set_page_label_multiple_ranges(self, client, sample_pdf_path):
+        """Test set_page_label method with multiple page ranges."""
+        labels = [
+            {"pages": {"start": 0, "end": 1}, "label": "i"},
+            {"pages": {"start": 1, "end": 2}, "label": "intro"},
+            {"pages": {"start": 2, "end": 3}, "label": "final"},
+        ]
+
+        result = client.set_page_label(sample_pdf_path, labels)
+
+        assert isinstance(result, bytes)
+        assert len(result) > 0
+        assert_is_pdf(result)
+
+    def test_set_page_label_single_page(self, client, sample_pdf_path):
+        """Test set_page_label method with single page label."""
+        labels = [{"pages": {"start": 0, "end": 1}, "label": "Cover Page"}]
+
+        result = client.set_page_label(sample_pdf_path, labels)
+
+        assert isinstance(result, bytes)
+        assert len(result) > 0
+        assert_is_pdf(result)
+
+    def test_set_page_label_empty_labels_error(self, client, sample_pdf_path):
+        """Test set_page_label method with empty labels raises error."""
+        with pytest.raises(ValueError, match="labels list cannot be empty"):
+            client.set_page_label(sample_pdf_path, labels=[])
+
+    def test_set_page_label_invalid_label_config_error(self, client, sample_pdf_path):
+        """Test set_page_label method with invalid label configuration raises error."""
+        # Missing 'pages' key
+        with pytest.raises(ValueError, match="missing required 'pages' key"):
+            client.set_page_label(sample_pdf_path, labels=[{"label": "test"}])
+
+        # Missing 'label' key
+        with pytest.raises(ValueError, match="missing required 'label' key"):
+            client.set_page_label(sample_pdf_path, labels=[{"pages": {"start": 0}}])
+
+        # Invalid pages format
+        with pytest.raises(ValueError, match="'pages' must be a dict with 'start' key"):
+            client.set_page_label(sample_pdf_path, labels=[{"pages": "invalid", "label": "test"}])
+
     def test_duplicate_pdf_pages_basic(self, client, sample_pdf_path):
         """Test duplicate_pdf_pages method with basic duplication."""
         # Test duplicating first page twice

tests/unit/test_builder.py

@@ -48,6 +48,40 @@ def test_builder_set_output_options():
     assert builder._output_options["optimize"] is True
 
 
+def test_builder_set_page_labels():
+    """Test setting page labels."""
+    builder = BuildAPIWrapper(None, "test.pdf")
+
+    labels = [
+        {"pages": {"start": 0, "end": 3}, "label": "Introduction"},
+        {"pages": {"start": 3, "end": 10}, "label": "Chapter 1"},
+        {"pages": {"start": 10}, "label": "Appendix"},
+    ]
+
+    result = builder.set_page_labels(labels)
+
+    assert result is builder  # Should return self for chaining
+    assert builder._output_options["labels"] == labels
+
+
+def test_builder_set_page_labels_chaining():
+    """Test page labels can be chained with other operations."""
+    builder = BuildAPIWrapper(None, "test.pdf")
+
+    labels = [{"pages": {"start": 0, "end": 1}, "label": "Cover"}]
+
+    result = (
+        builder.add_step("rotate-pages", options={"degrees": 90})
+        .set_page_labels(labels)
+        .set_output_options(metadata={"title": "Test"})
+    )
+
+    assert result is builder
+    assert len(builder._actions) == 1
+    assert builder._output_options["labels"] == labels
+    assert builder._output_options["metadata"]["title"] == "Test"
+
+
 def test_builder_execute_requires_client():
     """Test that execute requires a client."""
     builder = BuildAPIWrapper(None, "test.pdf")