From 25fbea205ff62f35d738884a73fd145b1a9618a6 Mon Sep 17 00:00:00 2001
From: TekH <h.tek@digitaldata.works>
Date: Tue, 21 Jul 2026 12:27:52 +0200
Subject: [PATCH] feat(infrastructure): Add IPdfProcessor.AddAnnotationAsync
 interface

- Add AddAnnotationAsync method with 8 parameters
- Support Stream-based PDF input (Position=0 required)
- Accept annotation type, page number, rectangle coordinates
- Optional parameters: content, author, color (hex), textMarkupStyle
- Returns annotated PDF as byte array
---
 .../Common/Interfaces/IPdfProcessor.cs        | 29 +++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/DocumentOperator.Application/Common/Interfaces/IPdfProcessor.cs b/DocumentOperator.Application/Common/Interfaces/IPdfProcessor.cs
index 667c07b..d3aad79 100644
--- a/DocumentOperator.Application/Common/Interfaces/IPdfProcessor.cs
+++ b/DocumentOperator.Application/Common/Interfaces/IPdfProcessor.cs
@@ -76,4 +76,33 @@ public interface IPdfProcessor
     /// or page range format is invalid
     /// </exception>
     Task<byte[]> MergePdfsAsync(IReadOnlyList<Stream> pdfStreams, IReadOnlyList<string?>? pageRanges = null);
+
+    /// <summary>
+    /// Adds an annotation to a PDF document at the specified page and rectangle.
+    /// </summary>
+    /// <param name="pdfStream">
+    /// PDF document stream. Must be readable and positioned at the beginning (Position = 0).
+    /// Non-seekable streams are supported. Caller is responsible for disposal.
+    /// </param>
+    /// <param name="annotationType">Type of annotation to add (TextMarkup, FreeText, StickyNote, Circle, Square)</param>
+    /// <param name="pageNumber">Page number (1-based) where annotation should be added</param>
+    /// <param name="rectangle">Annotation bounding rectangle (X1, Y1, X2, Y2) in PDF coordinates</param>
+    /// <param name="content">Annotation content/comment text (required for FreeText and StickyNote)</param>
+    /// <param name="author">Optional author name</param>
+    /// <param name="color">Optional annotation color in RGB format (hex string like "FF0000" for red)</param>
+    /// <param name="textMarkupStyle">Text markup style (Highlight, Underline, Strikeout) - only for TextMarkup type</param>
+    /// <returns>Annotated PDF as byte array</returns>
+    /// <exception cref="Domain.Common.Exceptions.BadRequestException">
+    /// Thrown when stream is empty/invalid/not at Position=0, page number out of range, 
+    /// rectangle invalid, or content missing for types that require it
+    /// </exception>
+    Task<byte[]> AddAnnotationAsync(
+        Stream pdfStream,
+        Domain.Models.ValueObjects.AnnotationType annotationType,
+        int pageNumber,
+        (double X1, double Y1, double X2, double Y2) rectangle,
+        string? content = null,
+        string? author = null,
+        string? color = null,
+        Domain.Models.ValueObjects.TextMarkupStyle? textMarkupStyle = null);
 }
\ No newline at end of file