Address CodeRabbit review feedback (round 2)

Author: Jaben

examples/PdfEngineOperations/Program.cs

@@ -26,25 +26,25 @@
 
 // Flatten
 Console.WriteLine("Flattening PDF...");
-var flattenResult = await sharpClient.ExecutePdfEngineAsync(
+using var flattenResult = await sharpClient.ExecutePdfEngineAsync(
     PdfEngineBuilders.Flatten().WithPdfs(a => a.AddItem("test.pdf", pdfBytes)));
 await SaveStream(flattenResult, destinationDirectory, "Flattened.pdf");
 
 // Rotate 90 degrees
 Console.WriteLine("Rotating PDF 90 degrees...");
-var rotateResult = await sharpClient.ExecutePdfEngineAsync(
+using var rotateResult = await sharpClient.ExecutePdfEngineAsync(
     PdfEngineBuilders.Rotate(90).WithPdfs(a => a.AddItem("test.pdf", pdfBytes)));
 await SaveStream(rotateResult, destinationDirectory, "Rotated.pdf");
 
 // Encrypt
 Console.WriteLine("Encrypting PDF...");
-var encryptResult = await sharpClient.ExecutePdfEngineAsync(
+using var encryptResult = await sharpClient.ExecutePdfEngineAsync(
     PdfEngineBuilders.Encrypt("reader123", "admin456").WithPdfs(a => a.AddItem("test.pdf", pdfBytes)));
 await SaveStream(encryptResult, destinationDirectory, "Encrypted.pdf");
 
 // Write metadata
 Console.WriteLine("Writing metadata...");
-var writeResult = await sharpClient.ExecutePdfEngineAsync(
+using var writeResult = await sharpClient.ExecutePdfEngineAsync(
     PdfEngineBuilders.WriteMetadata(new Dictionary<string, object>
     {
         { "Author", "GotenbergSharpApiClient" },
@@ -71,7 +71,7 @@ static async Task<byte[]> GenerateTestPdf(GotenbergSharpClient client)
                 <form><input type='text' name='field1' value='Form field (will be flattened)'/></form>
             </body></html>"));
 
-    var stream = await client.HtmlToPdfAsync(builder);
+    using var stream = await client.HtmlToPdfAsync(builder);
     using var ms = new MemoryStream();
     await stream.CopyToAsync(ms);
     return ms.ToArray();

src/Gotenberg.Sharp.Api.Client/Domain/Builders/PdfEngineBuilder.cs

@@ -100,7 +100,7 @@ public static PdfEngineBuilder<SplitPdfRequest> Split(SplitMode mode, string spa
         var request = new SplitPdfRequest
         {
             Mode = mode,
-            Span = span ?? throw new ArgumentNullException(nameof(span)),
+            Span = !string.IsNullOrWhiteSpace(span) ? span : throw new ArgumentException("Span must not be null or whitespace.", nameof(span)),
             Unify = unify
         };
         return new PdfEngineBuilder<SplitPdfRequest>(request);

src/Gotenberg.Sharp.Api.Client/Domain/Requests/EncryptPdfRequest.cs

@@ -16,7 +16,7 @@ public sealed class EncryptPdfRequest : PdfEngineRequest
     protected override void Validate()
     {
         if (string.IsNullOrWhiteSpace(this.UserPassword))
-            throw new InvalidOperationException("User password is required for encryption.");
+            throw new ArgumentException("User password is required for encryption.");
 
         base.Validate();
     }

src/Gotenberg.Sharp.Api.Client/Domain/Requests/FlattenPdfRequest.cs

@@ -5,6 +5,9 @@
 
 namespace Gotenberg.Sharp.API.Client.Domain.Requests;
 
+/// <summary>
+/// Flattens PDF form fields into static content.
+/// </summary>
 public sealed class FlattenPdfRequest : PdfEngineRequest
 {
     protected override string ApiPath => Constants.Gotenberg.PdfEngines.ApiPaths.Flatten;

src/Gotenberg.Sharp.Api.Client/Domain/Requests/WriteMetadataRequest.cs

@@ -27,7 +27,7 @@ protected override void Validate()
     protected override IEnumerable<HttpContent> ToHttpContent()
     {
         var metadataContent = new StringContent(this.Metadata!.ToString());
-        metadataContent.Headers.ContentType = new MediaTypeHeaderValue(Constants.HttpContent.MediaTypes.TextHtml);
+        metadataContent.Headers.ContentType = new MediaTypeHeaderValue(Constants.HttpContent.MediaTypes.ApplicationJson);
         metadataContent.Headers.ContentDisposition =
             new ContentDispositionHeaderValue(Constants.HttpContent.Disposition.Types.FormData)
             {

src/Gotenberg.Sharp.Api.Client/Domain/ValueObjects/PageRanges.cs

@@ -51,6 +51,33 @@ public static PageRanges Create(string ranges)
                 $"Invalid page range format: '{ranges}'. Expected format: '1-3,5,8-10'.",
                 nameof(ranges));
 
+        // Semantic validation: verify page numbers are >= 1 and range start <= end
+        foreach (var segment in trimmed.Split(','))
+        {
+            var parts = segment.Trim().Split('-');
+            if (parts.Length == 1)
+            {
+                var page = int.Parse(parts[0].Trim());
+                if (page < 1)
+                    throw new ArgumentException(
+                        $"Page number must be >= 1, but got {page} in '{ranges}'.",
+                        nameof(ranges));
+            }
+            else if (parts.Length == 2)
+            {
+                var start = int.Parse(parts[0].Trim());
+                var end = int.Parse(parts[1].Trim());
+                if (start < 1 || end < 1)
+                    throw new ArgumentException(
+                        $"Page numbers must be >= 1, but got range '{start}-{end}' in '{ranges}'.",
+                        nameof(ranges));
+                if (start > end)
+                    throw new ArgumentException(
+                        $"Range start must be <= end, but got '{start}-{end}' in '{ranges}'.",
+                        nameof(ranges));
+            }
+        }
+
         return new PageRanges(trimmed);
     }
 

src/Gotenberg.Sharp.Api.Client/Infrastructure/Constants.cs

@@ -32,6 +32,8 @@ public static class MediaTypes
             public const string TextHtml = "text/html";
 
             public const string ApplicationPdf = "application/pdf";
+
+            public const string ApplicationJson = "application/json";
         }
 
         public static class MultipartData

test/GotenbergSharpClient.Tests/PdfEngineOperationsTests.cs

@@ -123,7 +123,7 @@ public async Task FlattenPdf_Succeeds()
         var builder = PdfEngineBuilders.Flatten()
             .WithPdfs(a => a.AddItem("test.pdf", pdfBytes));
 
-        var result = await client.ExecutePdfEngineAsync(builder);
+        using var result = await client.ExecutePdfEngineAsync(builder);
 
         result.Should().NotBeNull();
         result.Length.Should().BeGreaterThan(0);
@@ -139,7 +139,7 @@ public async Task RotatePdf_Succeeds()
         var builder = PdfEngineBuilders.Rotate(90)
             .WithPdfs(a => a.AddItem("test.pdf", pdfBytes));
 
-        var result = await client.ExecutePdfEngineAsync(builder);
+        using var result = await client.ExecutePdfEngineAsync(builder);
 
         result.Should().NotBeNull();
         result.Length.Should().BeGreaterThan(0);
@@ -155,7 +155,7 @@ public async Task EncryptPdf_Succeeds()
         var builder = PdfEngineBuilders.Encrypt("user123", "owner456")
             .WithPdfs(a => a.AddItem("test.pdf", pdfBytes));
 
-        var result = await client.ExecutePdfEngineAsync(builder);
+        using var result = await client.ExecutePdfEngineAsync(builder);
 
         result.Should().NotBeNull();
         result.Length.Should().BeGreaterThan(0);
@@ -175,7 +175,7 @@ public async Task WriteMetadata_Succeeds()
             })
             .WithPdfs(a => a.AddItem("test.pdf", pdfBytes));
 
-        var result = await client.ExecutePdfEngineAsync(builder);
+        using var result = await client.ExecutePdfEngineAsync(builder);
 
         result.Should().NotBeNull();
         result.Length.Should().BeGreaterThan(0);
@@ -220,7 +220,7 @@ private static async Task<byte[]> GenerateTestPdf(Gotenberg.Sharp.API.Client.Got
         var builder = new HtmlRequestBuilder()
             .AddDocument(doc => doc.SetBody("<html><body><h1>Test PDF</h1></body></html>"));
 
-        var stream = await client.HtmlToPdfAsync(builder);
+        using var stream = await client.HtmlToPdfAsync(builder);
 
         using var ms = new MemoryStream();
         await stream.CopyToAsync(ms);