models: Add location validation for new signature configurations

- Updated `_PdfSignatureConfigurationModel` to enforce location
  requirements for `type="new"` via a model validator.
- Extended `type` field to include `"existing"` in both the model and
  the public `PdfSignatureConfiguration` type.
- Added tests to verify:
  - Validation error is raised when `type="new"` and location is missing.
  - `type="existing"` does not require location fields.

Assisted-by: Codex

Author: datalogics-kam

src/pdfrest/models/_internal.py

@@ -630,16 +630,19 @@ class _PdfSignatureDisplayModel(BaseModel):
 
 
 class _PdfSignatureConfigurationModel(BaseModel):
-    type: Literal["new"]
+    type: Literal["new", "existing"]
     name: str | None = None
     logo_opacity: Annotated[float | None, Field(ge=0, le=1, default=None)] = None
     location: _PdfSignatureLocationModel | None = None
     display: _PdfSignatureDisplayModel | None = None
 
     @model_validator(mode="after")
-    def _validate_location_for_new_type(self) -> _PdfSignatureConfigurationModel:
+    def _validate_location_requirements(self) -> _PdfSignatureConfigurationModel:
         if self.type == "new" and self.location is None:
-            msg = "Missing location information for a new digital signature field."
+            msg = (
+                "Missing location information for a new digital signature field. "
+                "See documentation for required fields."
+            )
             raise ValueError(msg)
         return self
 

src/pdfrest/types/public.py

@@ -162,7 +162,7 @@ class PdfSignatureDisplay(TypedDict, total=False):
 
 
 class PdfSignatureConfiguration(TypedDict, total=False):
-    type: Required[Literal["new"]]
+    type: Required[Literal["new", "existing"]]
     location: Required[PdfSignatureLocation]
     name: str
     logo_opacity: float

tests/test_sign_pdf.py

@@ -305,3 +305,36 @@ def handler(request: httpx.Request) -> httpx.Response:
         assert all(pytest.approx(0.5) == value for value in timeout_value.values())
     else:
         assert timeout_value == pytest.approx(0.5)
+
+
+def test_sign_payload_requires_location_when_type_new() -> None:
+    input_file = make_pdf_file(PdfRestFileID.generate())
+    pfx_file = make_pfx_file(str(PdfRestFileID.generate()))
+    passphrase_file = make_passphrase_file(str(PdfRestFileID.generate()))
+
+    with pytest.raises(
+        ValidationError,
+        match=r"Missing location information for a new digital signature field",
+    ):
+        PdfSignPayload.model_validate(
+            {
+                "files": [input_file],
+                "signature_configuration": {"type": "new", "name": "sig"},
+                "credentials": {"pfx": pfx_file, "passphrase": passphrase_file},
+            }
+        )
+
+
+def test_sign_payload_allows_existing_without_location() -> None:
+    input_file = make_pdf_file(PdfRestFileID.generate())
+    pfx_file = make_pfx_file(str(PdfRestFileID.generate()))
+    passphrase_file = make_passphrase_file(str(PdfRestFileID.generate()))
+
+    payload = PdfSignPayload.model_validate(
+        {
+            "files": [input_file],
+            "signature_configuration": {"type": "existing", "name": "sig"},
+            "credentials": {"pfx": pfx_file, "passphrase": passphrase_file},
+        }
+    )
+    assert payload.signature_configuration.type == "existing"