Add Add Image methods

Assisted-by: Codex

Author: datalogics-cgreen

src/pdfrest/client.py

@@ -82,6 +82,7 @@
     JpegPdfRestPayload,
     OcrPdfPayload,
     PdfAddAttachmentPayload,
+    PdfAddImagePayload,
     PdfCompressPayload,
     PdfFlattenAnnotationsPayload,
     PdfFlattenFormsPayload,
@@ -2500,6 +2501,42 @@ def apply_redactions(
             timeout=timeout,
         )
 
+    def add_image_to_pdf(
+        self,
+        file: PdfRestFile | Sequence[PdfRestFile],
+        *,
+        image: PdfRestFile | Sequence[PdfRestFile],
+        x: int,
+        y: int,
+        page: int,
+        output: str | None = None,
+        extra_query: Query | None = None,
+        extra_headers: AnyMapping | None = None,
+        extra_body: Body | None = None,
+        timeout: TimeoutTypes | None = None,
+    ) -> PdfRestFileBasedResponse:
+        """Insert an image into a single page of a PDF."""
+
+        payload: dict[str, Any] = {
+            "files": file,
+            "image": image,
+            "x": x,
+            "y": y,
+            "page": page,
+        }
+        if output is not None:
+            payload["output"] = output
+
+        return self._post_file_operation(
+            endpoint="/pdf-with-added-image",
+            payload=payload,
+            payload_model=PdfAddImagePayload,
+            extra_query=extra_query,
+            extra_headers=extra_headers,
+            extra_body=extra_body,
+            timeout=timeout,
+        )
+
     def split_pdf(
         self,
         file: PdfRestFile | Sequence[PdfRestFile],
@@ -3522,6 +3559,42 @@ async def apply_redactions(
             timeout=timeout,
         )
 
+    async def add_image_to_pdf(
+        self,
+        file: PdfRestFile | Sequence[PdfRestFile],
+        *,
+        image: PdfRestFile | Sequence[PdfRestFile],
+        x: int,
+        y: int,
+        page: int,
+        output: str | None = None,
+        extra_query: Query | None = None,
+        extra_headers: AnyMapping | None = None,
+        extra_body: Body | None = None,
+        timeout: TimeoutTypes | None = None,
+    ) -> PdfRestFileBasedResponse:
+        """Asynchronously insert an image into a PDF."""
+
+        payload: dict[str, Any] = {
+            "files": file,
+            "image": image,
+            "x": x,
+            "y": y,
+            "page": page,
+        }
+        if output is not None:
+            payload["output"] = output
+
+        return await self._post_file_operation(
+            endpoint="/pdf-with-added-image",
+            payload=payload,
+            payload_model=PdfAddImagePayload,
+            extra_query=extra_query,
+            extra_headers=extra_headers,
+            extra_body=extra_body,
+            timeout=timeout,
+        )
+
     async def up(
         self,
         *,

src/pdfrest/models/_internal.py

@@ -1021,6 +1021,53 @@ def _validate_profile_dependency(self) -> PdfCompressPayload:
         return self
 
 
+class PdfAddImagePayload(BaseModel):
+    """Adapt caller options into a pdfRest-ready add-image request payload."""
+
+    files: Annotated[
+        list[PdfRestFile],
+        Field(
+            min_length=1,
+            max_length=1,
+            validation_alias=AliasChoices("file", "files"),
+            serialization_alias="id",
+        ),
+        BeforeValidator(_ensure_list),
+        AfterValidator(
+            _allowed_mime_types("application/pdf", error_msg="Must be a PDF file")
+        ),
+        PlainSerializer(_serialize_as_first_file_id),
+    ]
+    image: Annotated[
+        list[PdfRestFile],
+        Field(
+            min_length=1,
+            max_length=1,
+            validation_alias=AliasChoices("image", "images", "image_file", "image_id"),
+            serialization_alias="image_id",
+        ),
+        BeforeValidator(_ensure_list),
+        AfterValidator(
+            _allowed_mime_types(
+                "image/jpeg",
+                "image/png",
+                "image/tiff",
+                "image/gif",
+                error_msg="Image must be JPEG, PNG, TIFF, or GIF",
+            )
+        ),
+        PlainSerializer(_serialize_as_first_file_id),
+    ]
+    x: Annotated[int, Field(serialization_alias="x")]
+    y: Annotated[int, Field(serialization_alias="y")]
+    page: Annotated[int, Field(serialization_alias="page", ge=1)]
+    output: Annotated[
+        str | None,
+        Field(serialization_alias="output", min_length=1, default=None),
+        AfterValidator(_validate_output_prefix),
+    ] = None
+
+
 class PdfXfaToAcroformsPayload(BaseModel):
     """Adapt caller options into a pdfRest-ready XFA-to-AcroForms request payload."""