Merge branch 'fix/codecov-ci-configuration' into main

Fix CI configuration and integration test strategy:
- Fix Codecov action parameter (file → files)
- Enhance integration test conditions to run on push events, same-repo PRs, and manual triggers
- Add automated feedback for fork PRs explaining security limitations
- Fix test data issues by adding multi-page PDF
- Improve file handling with better position management
- Add validation improvements for Direct API methods

This ensures integration tests run properly while maintaining security for fork PRs.

Author: jdrhyne

.github/workflows/ci.yml

@@ -1,10 +1,20 @@
 name: CI
 
+# Integration Test Strategy:
+# - Fork PRs: Cannot access secrets, so integration tests are skipped with informative feedback
+# - Same-repo PRs: Have access to secrets, integration tests run normally  
+# - Push to main/develop: Integration tests always run to catch any issues after merge
+# - Manual trigger: Allows maintainers to run integration tests on demand
+#
+# This ensures security while still validating integration tests before release
+
 on:
   push:
     branches: [ main, develop ]
   pull_request:
     branches: [ main, develop ]
+  # Run integration tests after PR is merged
+  workflow_dispatch:  # Allow manual trigger for integration tests
 
 jobs:
   test:
@@ -47,25 +57,32 @@ jobs:
       run: python -m pytest tests/unit/ -v --cov=nutrient_dws --cov-report=xml --cov-report=term
 
     - name: Upload coverage to Codecov
-      uses: codecov/codecov-action@v4
+      uses: codecov/codecov-action@v5
       with:
         token: ${{ secrets.CODECOV_TOKEN }}
-        file: ./coverage.xml
+        files: ./coverage.xml
         flags: unittests
         name: codecov-umbrella
         fail_ci_if_error: false
 
   integration-test:
     runs-on: ubuntu-latest
-    if: github.event_name == 'pull_request'
+    # Run on: pushes to main/develop, PRs from same repo, and manual triggers
+    if: |
+      github.event_name == 'push' ||
+      github.event_name == 'workflow_dispatch' ||
+      (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository)
+    strategy:
+      matrix:
+        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12']
 
     steps:
     - uses: actions/checkout@v4
 
-    - name: Set up Python 3.12
+    - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v5
       with:
-        python-version: '3.12'
+        python-version: ${{ matrix.python-version }}
 
     - name: Cache pip dependencies
       uses: actions/cache@v4
@@ -80,7 +97,29 @@ jobs:
         python -m pip install --upgrade pip
         pip install -e ".[dev]"
 
+    - name: Check for API key availability
+      run: |
+        if [ -z "${{ secrets.NUTRIENT_DWS_API_KEY }}" ]; then
+          echo "::warning::NUTRIENT_DWS_API_KEY secret not found, skipping integration tests"
+          echo "skip_tests=true" >> $GITHUB_ENV
+          
+          # Provide context about why this might be happening
+          if [ "${{ github.event_name }}" == "pull_request" ]; then
+            if [ "${{ github.event.pull_request.head.repo.full_name }}" != "${{ github.repository }}" ]; then
+              echo "::notice::This appears to be a PR from a fork. Secrets are not available for security reasons."
+            else
+              echo "::error::This is a PR from the same repository but the API key is missing. Please check repository secrets configuration."
+            fi
+          else
+            echo "::error::Running on ${{ github.event_name }} event but API key is missing. Please configure NUTRIENT_DWS_API_KEY secret."
+          fi
+        else
+          echo "::notice::API key found, integration tests will run"
+          echo "skip_tests=false" >> $GITHUB_ENV
+        fi
+
     - name: Create integration config with API key
+      if: env.skip_tests != 'true'
       run: |
         python -c "
         import os
@@ -91,8 +130,58 @@ jobs:
         NUTRIENT_DWS_API_KEY: ${{ secrets.NUTRIENT_DWS_API_KEY }}
 
     - name: Run integration tests
+      if: env.skip_tests != 'true'
       run: python -m pytest tests/integration/ -v
 
+    - name: Cleanup integration config
+      if: always()
+      run: rm -f tests/integration/integration_config.py
+
+  # Provide feedback for fork PRs where integration tests can't run
+  integration-test-fork-feedback:
+    runs-on: ubuntu-latest
+    if: |
+      github.event_name == 'pull_request' && 
+      github.event.pull_request.head.repo.full_name != github.repository
+    steps:
+    - name: Comment on PR about integration tests
+      uses: actions/github-script@v7
+      with:
+        github-token: ${{ secrets.GITHUB_TOKEN }}
+        script: |
+          const issue_number = context.issue.number;
+          const owner = context.repo.owner;
+          const repo = context.repo.repo;
+          
+          // Check if we've already commented
+          const comments = await github.rest.issues.listComments({
+            owner,
+            repo,
+            issue_number,
+          });
+          
+          const botComment = comments.data.find(comment => 
+            comment.user.type === 'Bot' && 
+            comment.body.includes('Integration tests are skipped for pull requests from forks')
+          );
+          
+          if (!botComment) {
+            await github.rest.issues.createComment({
+              owner,
+              repo,
+              issue_number,
+              body: `## Integration Tests Status\n\n` +
+                    `Integration tests are skipped for pull requests from forks due to security restrictions. ` +
+                    `These tests will run automatically after the PR is merged.\n\n` +
+                    `**What this means:**\n` +
+                    `- Unit tests, linting, and type checking have passed ✅\n` +
+                    `- Integration tests require API credentials that aren't available to fork PRs\n` +
+                    `- A maintainer will review your changes and merge if appropriate\n` +
+                    `- Integration tests will run on the main branch after merge\n\n` +
+                    `Thank you for your contribution! 🙏`
+            });
+          }
+
   build:
     runs-on: ubuntu-latest
     needs: test
@@ -120,4 +209,4 @@ jobs:
       uses: actions/upload-artifact@v4
       with:
         name: dist
-        path: dist/
+        path: dist/

pyproject.toml

@@ -22,7 +22,6 @@ keywords = ["nutrient", "pdf", "document", "processing", "api", "client"]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
-    "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.10",
@@ -53,10 +52,10 @@ docs = [
 ]
 
 [project.urls]
-Homepage = "https://github.com/jdrhyne/nutrient-dws-client-python"
+Homepage = "https://github.com/PSPDFKit/nutrient-dws-client-python"
 Documentation = "https://nutrient-dws-client-python.readthedocs.io"
-Repository = "https://github.com/jdrhyne/nutrient-dws-client-python"
-"Bug Tracker" = "https://github.com/jdrhyne/nutrient-dws-client-python/issues"
+Repository = "https://github.com/PSPDFKit/nutrient-dws-client-python"
+"Bug Tracker" = "https://github.com/PSPDFKit/nutrient-dws-client-python/issues"
 
 [tool.setuptools.package-data]
 nutrient_dws = ["py.typed"]

src/nutrient_dws/api/direct.py

@@ -414,8 +414,9 @@ def delete_pdf_pages(
 
         Args:
             input_file: Input PDF file.
-            page_indexes: List of page indexes to delete (0-based).
-                         Negative indexes are supported (-1 for last page).
+            page_indexes: List of page indexes to delete (0-based). 0 = first page.
+                         Must be unique, sorted in ascending order.
+                         Negative indexes are NOT supported.
             output_path: Optional path to save the output file.
 
         Returns:
@@ -424,13 +425,13 @@ def delete_pdf_pages(
         Raises:
             AuthenticationError: If API key is missing or invalid.
             APIError: For other API errors.
-            ValueError: If page_indexes is empty.
+            ValueError: If page_indexes is empty or contains negative indexes.
 
         Examples:
-            # Delete first and last pages
+            # Delete first and last pages (Note: negative indexes not supported)
             result = client.delete_pdf_pages(
                 "document.pdf",
-                page_indexes=[0, -1]
+                page_indexes=[0, 2]  # Delete pages 1 and 3
             )
 
             # Delete specific pages (2nd and 4th pages)
@@ -452,13 +453,17 @@ def delete_pdf_pages(
         if not page_indexes:
             raise ValueError("page_indexes cannot be empty")
 
+        # Check for negative indexes
+        if any(idx < 0 for idx in page_indexes):
+            negative_indexes = [idx for idx in page_indexes if idx < 0]
+            raise ValueError(
+                f"Negative page indexes not yet supported for deletion: {negative_indexes}"
+            )
+
         # Prepare file for upload
         file_field, file_data = prepare_file_for_upload(input_file, "file")
         files = {file_field: file_data}
 
-        # Convert negative indexes to positive (we need to get document info first)
-        # For now, we'll create the parts structure and let the API handle negative indexes
-
         # Sort page indexes to handle ranges efficiently
         sorted_indexes = sorted(set(page_indexes))  # Remove duplicates and sort
 
@@ -470,13 +475,6 @@ def delete_pdf_pages(
         current_page = 0
 
         for delete_index in sorted_indexes:
-            # Handle negative indexes by letting API process them
-            if delete_index < 0:
-                # For negative indexes, we can't easily calculate ranges without knowing total pages
-                # We'll use a different approach - create parts for everything and let API handle it
-                # This is a simplified approach that may need refinement
-                continue
-
             # Add range from current_page to delete_index (exclusive)
             if current_page < delete_index:
                 parts.append(
@@ -487,39 +485,9 @@ def delete_pdf_pages(
             current_page = delete_index + 1
 
         # Add remaining pages from current_page to end
-        if current_page >= 0:  # Always add remaining pages unless we handled negative indexes
+        if current_page >= 0:  # Always add remaining pages
             parts.append({"file": "file", "pages": {"start": current_page}})
 
-        # Handle case where we have negative indexes - use a simpler approach
-        if any(idx < 0 for idx in page_indexes):
-            # If we have negative indexes, we need a different strategy
-            # For now, we'll create a request that includes all positive ranges
-            # and excludes negative ones - this is a limitation that would need
-            # API documentation clarification
-            parts = []
-
-            # Positive indexes only for now
-            positive_indexes = [idx for idx in sorted_indexes if idx >= 0]
-            if positive_indexes:
-                current_page = 0
-                for delete_index in positive_indexes:
-                    if current_page < delete_index:
-                        parts.append(
-                            {"file": "file", "pages": {"start": current_page, "end": delete_index}}
-                        )
-                    current_page = delete_index + 1
-
-                # Add remaining pages
-                parts.append({"file": "file", "pages": {"start": current_page}})
-
-            # Handle negative indexes separately by including a warning
-            if any(idx < 0 for idx in page_indexes):
-                # For now, raise an error for negative indexes as they need special handling
-                negative_indexes = [idx for idx in page_indexes if idx < 0]
-                raise ValueError(
-                    f"Negative page indexes not yet supported for deletion: {negative_indexes}"
-                )
-
         # If no parts (edge case), raise error
         if not parts:
             raise ValueError("No valid pages to keep after deletion")
@@ -667,6 +635,8 @@ def add_page(
         # Validate inputs
         if page_count < 1:
             raise ValueError("page_count must be at least 1")
+        if page_count > 100:
+            raise ValueError("page_count cannot exceed 100 pages")
         if insert_index < -1:
             raise ValueError("insert_index must be -1 (for end) or a non-negative insertion index")
 

src/nutrient_dws/file_handler.py

@@ -1,5 +1,6 @@
 """File handling utilities for input/output operations."""
 
+import contextlib
 import io
 import os
 from collections.abc import Generator
@@ -40,11 +41,30 @@ def prepare_file_input(file_input: FileInput) -> tuple[bytes, str]:
             return file_input, "document"
         case _ if hasattr(file_input, "read"):
             # Handle file-like objects
+            # Save current position if seekable
+            current_pos = None
+            if hasattr(file_input, "seek") and hasattr(file_input, "tell"):
+                try:
+                    current_pos = file_input.tell()
+                    file_input.seek(0)  # Read from beginning
+                except (OSError, io.UnsupportedOperation):
+                    pass
+
             content = file_input.read()
             if isinstance(content, str):
                 content = content.encode()
+
+            # Restore position if we saved it
+            if current_pos is not None:
+                with contextlib.suppress(OSError, io.UnsupportedOperation):
+                    file_input.seek(current_pos)
+
             filename = getattr(file_input, "name", "document")
-            if hasattr(filename, "__fspath__") or isinstance(filename, str | bytes):
+            if hasattr(filename, "__fspath__"):
+                filename = os.path.basename(os.fspath(filename))
+            elif isinstance(filename, bytes):
+                filename = os.path.basename(filename.decode())
+            elif isinstance(filename, str):
                 filename = os.path.basename(filename)
             return content, str(filename)
         case _:
@@ -102,6 +122,10 @@ def prepare_file_for_upload(
         case _ if hasattr(file_input, "read"):
             filename = getattr(file_input, "name", "document")
             if hasattr(filename, "__fspath__"):
+                filename = os.path.basename(os.fspath(filename))
+            elif isinstance(filename, bytes):
+                filename = os.path.basename(filename.decode())
+            elif isinstance(filename, str):
                 filename = os.path.basename(filename)
             return field_name, (str(filename), file_input, content_type)  # type: ignore[return-value]
         case _:
@@ -158,7 +182,10 @@ def get_file_size(file_input: FileInput) -> int | None:
     Returns:
         File size in bytes, or None if size cannot be determined.
     """
-    if isinstance(file_input, str):
+    if isinstance(file_input, Path):
+        if file_input.exists():
+            return file_input.stat().st_size
+    elif isinstance(file_input, str):
         path = Path(file_input)
         if path.exists():
             return path.stat().st_size