Fix add_page positioning logic and validation (#13)

* Fix add_page positioning logic and validation

BREAKING CHANGE: Correct insert_after_page parameter behavior:
- insert_after_page=-1 now inserts at END of document (not beginning)
- insert_after_page=0 inserts after first page
- insert_after_page=N inserts after page N
- Negative values < -1 are now rejected with ValueError

Changes:
- Update method documentation and examples
- Add validation for invalid negative positions
- Fix logic for -1 (end insertion) vs specific page positions
- Add comprehensive test for invalid position errors
- Rename test methods to reflect correct behavior

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

Co-Authored-By: Claude <noreply@anthropic.com>

* Implement correct insertion index logic for add_page method

BREAKING CHANGE: Redesign add_page to use proper insertion index semantics:

Parameter changes:
- insert_after_page → insert_index (renamed parameter)
- insert_index=0: Insert before first page (at beginning)
- insert_index=1: Insert before second page (after first page)
- insert_index=-1: Insert after last page (at end)

Implementation changes:
- Completely rewrite positioning logic for insertion index semantics
- Update method documentation and examples
- Rename and update all test cases to match new behavior
- Add validation for invalid negative positions (< -1)
- Fix API parts construction for correct page insertion

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

Co-Authored-By: Claude <noreply@anthropic.com>

* Fix line length in test_client.py after rebase

Breaking up long json_data parameter in mock assertion call to meet
line length requirements.

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

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: msch-nutrient

src/nutrient_dws/api/direct.py

@@ -609,22 +609,22 @@ def merge_pdfs(
     def add_page(
         self,
         input_file: FileInput,
-        insert_after_page: int,
+        insert_index: int,
         page_count: int = 1,
         page_size: str = "A4",
         orientation: str = "portrait",
         output_path: str | None = None,
     ) -> bytes | None:
         """Add blank pages to a PDF document.
 
-        Inserts blank pages at the specified position in the document.
-        The new pages will be inserted after the specified page index.
+        Inserts blank pages at the specified insertion index in the document.
 
         Args:
             input_file: Input PDF file.
-            insert_after_page: Page index to insert after (0-based).
-                              Use -1 to insert at the beginning.
-                              For end insertion, use the last page index (page count - 1).
+            insert_index: Position to insert pages (0-based insertion index).
+                         0 = insert before first page (at beginning)
+                         1 = insert before second page (after first page)
+                         -1 = insert after last page (at end)
             page_count: Number of blank pages to add (default: 1).
             page_size: Page size for new pages. Common values: "A4", "Letter",
                       "Legal", "A3", "A5" (default: "A4").
@@ -638,25 +638,26 @@ def add_page(
         Raises:
             AuthenticationError: If API key is missing or invalid.
             APIError: For other API errors.
-            ValueError: If page_count is less than 1.
+            ValueError: If page_count is less than 1 or if insert_index is
+                       a negative number other than -1.
 
         Examples:
-            # Add a single blank page after page 2
-            result = client.add_page("document.pdf", insert_after_page=2)
+            # Add a single blank page at the beginning
+            result = client.add_page("document.pdf", insert_index=0)
 
-            # Add multiple pages at the beginning
+            # Add multiple pages at the end
             result = client.add_page(
                 "document.pdf",
-                insert_after_page=-1,  # Insert at beginning
+                insert_index=-1,  # Insert at end
                 page_count=3,
                 page_size="Letter",
                 orientation="landscape"
             )
 
-            # Add pages at the end and save to file
+            # Add pages before third page and save to file
             client.add_page(
                 "document.pdf",
-                insert_after_page=5,  # Insert after last page (for 6-page doc)
+                insert_index=2,  # Insert before third page
                 page_count=2,
                 output_path="with_blank_pages.pdf"
             )
@@ -666,6 +667,8 @@ def add_page(
         # Validate inputs
         if page_count < 1:
             raise ValueError("page_count must be at least 1")
+        if insert_index < -1:
+            raise ValueError("insert_index must be -1 (for end) or a non-negative insertion index")
 
         # Prepare file for upload
         file_field, file_data = prepare_file_for_upload(input_file, "file")
@@ -674,37 +677,34 @@ def add_page(
         # Build parts array
         parts: list[dict[str, Any]] = []
 
-        if insert_after_page == -1:
+        # Create new page part
+        new_page_part = {
+            "page": "new",
+            "pageCount": page_count,
+            "layout": {
+                "size": page_size,
+                "orientation": orientation,
+            },
+        }
+
+        if insert_index == -1:
+            # Insert at end: add all original pages first, then new pages
+            parts.append({"file": "file"})
+            parts.append(new_page_part)
+        elif insert_index == 0:
             # Insert at beginning: add new pages first, then all original pages
-            new_page_part = {
-                "page": "new",
-                "pageCount": page_count,
-                "layout": {
-                    "size": page_size,
-                    "orientation": orientation,
-                },
-            }
             parts.append(new_page_part)
             parts.append({"file": "file"})
         else:
-            # Insert after a specific page:
-            # First add pages from start to insertion point (inclusive)
-            parts.append({"file": "file", "pages": {"start": 0, "end": insert_after_page + 1}})
+            # Insert at specific position: split original document
+            # Add pages from start up to insertion point (0 to insert_index-1)
+            parts.append({"file": "file", "pages": {"start": 0, "end": insert_index}})
 
             # Add new blank pages
-            new_page_part = {
-                "page": "new",
-                "pageCount": page_count,
-                "layout": {
-                    "size": page_size,
-                    "orientation": orientation,
-                },
-            }
             parts.append(new_page_part)
 
-            # Add remaining pages after insertion point (if any)
-            # Only add this part if there are pages after the insertion point
-            parts.append({"file": "file", "pages": {"start": insert_after_page + 1}})
+            # Add remaining pages from insertion point to end
+            parts.append({"file": "file", "pages": {"start": insert_index}})
 
         # Build instructions for adding pages
         instructions = {"parts": parts, "actions": []}

tests/integration/test_live_api.py

@@ -386,10 +386,10 @@ def test_convert_to_pdf_from_pdf_passthrough(self, client, sample_pdf_path):
         # Verify result is a valid PDF
         assert_is_pdf(result)
 
-    def test_add_page_basic(self, client, sample_pdf_path):
-        """Test add_page method with basic page addition."""
-        # Test adding a single blank page after first page
-        result = client.add_page(sample_pdf_path, insert_after_page=0)
+    def test_add_page_at_beginning(self, client, sample_pdf_path):
+        """Test add_page method inserting at the beginning."""
+        # Test inserting at beginning (insert_index=0)
+        result = client.add_page(sample_pdf_path, insert_index=0)
 
         assert isinstance(result, bytes)
         assert len(result) > 0
@@ -399,30 +399,30 @@ def test_add_page_basic(self, client, sample_pdf_path):
 
     def test_add_page_multiple_pages(self, client, sample_pdf_path):
         """Test add_page method with multiple pages."""
-        # Test adding multiple blank pages
-        result = client.add_page(sample_pdf_path, insert_after_page=1, page_count=3)
+        # Test adding multiple blank pages before second page
+        result = client.add_page(sample_pdf_path, insert_index=1, page_count=3)
 
         assert isinstance(result, bytes)
         assert len(result) > 0
 
         # Verify result is a valid PDF
         assert_is_pdf(result)
 
-    def test_add_page_at_beginning(self, client, sample_pdf_path):
-        """Test add_page method inserting at the beginning."""
-        # Test inserting at beginning using -1
-        result = client.add_page(sample_pdf_path, insert_after_page=-1, page_count=2)
+    def test_add_page_at_end(self, client, sample_pdf_path):
+        """Test add_page method inserting at the end."""
+        # Test inserting at end using -1
+        result = client.add_page(sample_pdf_path, insert_index=-1, page_count=2)
 
         assert isinstance(result, bytes)
         assert len(result) > 0
 
         # Verify result is a valid PDF
         assert_is_pdf(result)
 
-    def test_add_page_at_end(self, client, sample_pdf_path):
-        """Test add_page method inserting at the end."""
-        # Test inserting at end (sample PDF has 6 pages, so insert after page 4)
-        result = client.add_page(sample_pdf_path, insert_after_page=4, page_count=1)
+    def test_add_page_before_specific_page(self, client, sample_pdf_path):
+        """Test add_page method inserting before a specific page."""
+        # Test inserting before page 3 (insert_index=2)
+        result = client.add_page(sample_pdf_path, insert_index=2, page_count=1)
 
         assert isinstance(result, bytes)
         assert len(result) > 0
@@ -432,10 +432,10 @@ def test_add_page_at_end(self, client, sample_pdf_path):
 
     def test_add_page_custom_size_orientation(self, client, sample_pdf_path):
         """Test add_page method with custom page size and orientation."""
-        # Test adding Letter-sized landscape pages
+        # Test adding Letter-sized landscape pages at beginning
         result = client.add_page(
             sample_pdf_path,
-            insert_after_page=0,
+            insert_index=0,
             page_size="Letter",
             orientation="landscape",
             page_count=2,
@@ -453,7 +453,7 @@ def test_add_page_with_output_file(self, client, sample_pdf_path, tmp_path):
 
         # Test adding pages and saving to file
         result = client.add_page(
-            sample_pdf_path, insert_after_page=1, page_count=2, output_path=output_path
+            sample_pdf_path, insert_index=1, page_count=2, output_path=output_path
         )
 
         # Should return None when saving to file
@@ -470,7 +470,7 @@ def test_add_page_different_page_sizes(self, client, sample_pdf_path):
         page_sizes = ["A4", "Letter", "Legal", "A3", "A5"]
 
         for page_size in page_sizes:
-            result = client.add_page(sample_pdf_path, insert_after_page=0, page_size=page_size)
+            result = client.add_page(sample_pdf_path, insert_index=0, page_size=page_size)
 
             assert isinstance(result, bytes)
             assert len(result) > 0
@@ -480,8 +480,17 @@ def test_add_page_invalid_page_count_error(self, client, sample_pdf_path):
         """Test add_page method with invalid page_count raises error."""
         # Test zero page count
         with pytest.raises(ValueError, match="page_count must be at least 1"):
-            client.add_page(sample_pdf_path, insert_after_page=0, page_count=0)
+            client.add_page(sample_pdf_path, insert_index=0, page_count=0)
 
         # Test negative page count
         with pytest.raises(ValueError, match="page_count must be at least 1"):
-            client.add_page(sample_pdf_path, insert_after_page=0, page_count=-1)
+            client.add_page(sample_pdf_path, insert_index=0, page_count=-1)
+
+    def test_add_page_invalid_position_error(self, client, sample_pdf_path):
+        """Test add_page method with invalid insert_index raises error."""
+        # Test invalid negative position (anything below -1)
+        with pytest.raises(ValueError, match="insert_index must be -1"):
+            client.add_page(sample_pdf_path, insert_index=-2, page_count=1)
+
+        with pytest.raises(ValueError, match="insert_index must be -1"):
+            client.add_page(sample_pdf_path, insert_index=-5, page_count=1)

tests/unit/test_client.py

@@ -169,7 +169,11 @@ def test_set_page_label_valid_config():
         mock_http_client.post.assert_called_once_with(
             "/build",
             files={"file": ("filename.pdf", b"mock_file_data", "application/pdf")},
-            json_data={"parts": [{"file": "file"}], "actions": [], "output": {"labels": expected_normalized_labels}},
+            json_data={
+                "parts": [{"file": "file"}],
+                "actions": [],
+                "output": {"labels": expected_normalized_labels},
+            },
         )
 
         # Verify result