Add standalone PDF engine operations (flatten, rotate, split, encrypt, metadata)

Introduce PdfEngineRequest base class and concrete request types:
FlattenPdfRequest, RotatePdfRequest, SplitPdfRequest, EncryptPdfRequest,
ReadMetadataRequest, WriteMetadataRequest. Each maps to a standalone
/forms/pdfengines/* route.

Add PdfEngineBuilders static factory with fluent builder creation for
each operation. Add ExecutePdfEngineAsync and ReadPdfMetadataAsync
methods to GotenbergSharpClient.

Include RotationAngle, PageRanges, and SplitMode value objects for
domain validation. Add PdfEngineOperations example and README section.

Author: Jaben

README.md

@@ -492,6 +492,34 @@ public async Task<Stream> FastConversion()
 }
 ```
 
+### Standalone PDF Engine Operations
+*Flatten, rotate, encrypt, and manipulate existing PDFs:*
+
+```csharp
+// Flatten form fields
+var flattenResult = await _sharpClient.ExecutePdfEngineAsync(
+    PdfEngineBuilders.Flatten().WithPdfs(a => a.AddItem("form.pdf", pdfBytes)));
+
+// Rotate pages 90 degrees
+var rotateResult = await _sharpClient.ExecutePdfEngineAsync(
+    PdfEngineBuilders.Rotate(90, "1-3").WithPdfs(a => a.AddItem("doc.pdf", pdfBytes)));
+
+// Encrypt with passwords
+var encrypted = await _sharpClient.ExecutePdfEngineAsync(
+    PdfEngineBuilders.Encrypt("reader123", "admin456").WithPdfs(a => a.AddItem("doc.pdf", pdfBytes)));
+
+// Read metadata (returns JSON)
+var metadataJson = await _sharpClient.ReadPdfMetadataAsync(
+    PdfEngineBuilders.ReadMetadata().WithPdfs(a => a.AddItem("doc.pdf", pdfBytes)));
+
+// Write metadata
+var result = await _sharpClient.ExecutePdfEngineAsync(
+    PdfEngineBuilders.WriteMetadata(new Dictionary<string, object>
+    {
+        { "Author", "John Doe" }, { "Title", "My Document" }
+    }).WithPdfs(a => a.AddItem("doc.pdf", pdfBytes)));
+```
+
 ### Custom Page Properties
 *Fine-tune page dimensions and properties:*
 

examples/PdfEngineOperations/PdfEngineOperations.csproj

@@ -0,0 +1,2 @@
+<Project Sdk="Microsoft.NET.Sdk">
+</Project>

examples/PdfEngineOperations/Program.cs

@@ -0,0 +1,103 @@
+using Gotenberg.Sharp.API.Client;
+using Gotenberg.Sharp.API.Client.Domain.Builders;
+using Gotenberg.Sharp.API.Client.Domain.ValueObjects;
+using Gotenberg.Sharp.API.Client.Domain.Settings;
+using Gotenberg.Sharp.API.Client.Infrastructure.Pipeline;
+
+using Microsoft.Extensions.Configuration;
+using Newtonsoft.Json.Linq;
+
+var config = new ConfigurationBuilder()
+    .SetBasePath(AppContext.BaseDirectory)
+    .AddJsonFile("appsettings.json")
+    .Build();
+
+var options = new GotenbergSharpClientOptions();
+config.GetSection(nameof(GotenbergSharpClient)).Bind(options);
+
+var destinationDirectory = args.Length > 0 ? args[0] : Path.Combine(Directory.GetCurrentDirectory(), "output");
+Directory.CreateDirectory(destinationDirectory);
+
+var sharpClient = CreateClient(options);
+
+// First generate a test PDF
+Console.WriteLine("Generating test PDF...");
+var pdfBytes = await GenerateTestPdf(sharpClient);
+
+// Flatten
+Console.WriteLine("Flattening PDF...");
+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(
+    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(
+    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(
+    PdfEngineBuilders.WriteMetadata(new Dictionary<string, object>
+    {
+        { "Author", "GotenbergSharpApiClient" },
+        { "Title", "PDF Engine Demo" }
+    }).WithPdfs(a => a.AddItem("test.pdf", pdfBytes)));
+await SaveStream(writeResult, destinationDirectory, "WithMetadata.pdf");
+
+// Read metadata
+Console.WriteLine("Reading metadata...");
+var metadataJson = await sharpClient.ReadPdfMetadataAsync(
+    PdfEngineBuilders.ReadMetadata().WithPdfs(a => a.AddItem("test.pdf", pdfBytes)));
+var parsed = JObject.Parse(metadataJson);
+Console.WriteLine($"Metadata: {parsed.ToString(Newtonsoft.Json.Formatting.Indented)}");
+
+Console.WriteLine($"\nAll output saved to: {destinationDirectory}");
+
+static async Task<byte[]> GenerateTestPdf(GotenbergSharpClient client)
+{
+    var builder = new HtmlRequestBuilder()
+        .AddDocument(doc => doc.SetBody(@"
+            <html><body>
+                <h1>PDF Engine Operations Demo</h1>
+                <p>This PDF is used to demonstrate standalone PDF engine operations.</p>
+                <form><input type='text' name='field1' value='Form field (will be flattened)'/></form>
+            </body></html>"));
+
+    var stream = await client.HtmlToPdfAsync(builder);
+    using var ms = new MemoryStream();
+    await stream.CopyToAsync(ms);
+    return ms.ToArray();
+}
+
+static async Task SaveStream(Stream stream, string directory, string filename)
+{
+    var path = Path.Combine(directory, $"{Path.GetFileNameWithoutExtension(filename)}-{DateTime.Now:yyyyMMddHHmmss}{Path.GetExtension(filename)}");
+    await using var file = File.Create(path);
+    await stream.CopyToAsync(file);
+    Console.WriteLine($"  Saved: {path}");
+}
+
+static GotenbergSharpClient CreateClient(GotenbergSharpClientOptions options)
+{
+    var handler = new HttpClientHandler();
+    HttpMessageHandler effectiveHandler = handler;
+
+    if (!string.IsNullOrWhiteSpace(options.BasicAuthUsername) && !string.IsNullOrWhiteSpace(options.BasicAuthPassword))
+        effectiveHandler = new BasicAuthHandler(options.BasicAuthUsername, options.BasicAuthPassword) { InnerHandler = handler };
+
+    var httpClient = new HttpClient(effectiveHandler)
+    {
+        BaseAddress = options.ServiceUrl,
+        Timeout = options.TimeOut
+    };
+
+    return new GotenbergSharpClient(httpClient);
+}

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

@@ -0,0 +1,152 @@
+// Copyright 2019-2026 Chris Mohan, Jaben Cargman
+//  and GotenbergSharpApiClient Contributors
+//
+//  Licensed under the Apache License, Version 2.0 (the "License");
+//  you may not use this file except in compliance with the License.
+//  You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+//  Unless required by applicable law or agreed to in writing, software
+//  distributed under the License is distributed on an "AS IS" BASIS,
+//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+//  See the License for the specific language governing permissions and
+//  limitations under the License.
+
+using Gotenberg.Sharp.API.Client.Domain.ValueObjects;
+
+using Newtonsoft.Json.Linq;
+
+namespace Gotenberg.Sharp.API.Client.Domain.Builders;
+
+/// <summary>
+/// Builds standalone PDF engine requests. Use the static factory methods to create
+/// builders for specific operations (flatten, rotate, split, encrypt, metadata).
+/// </summary>
+public sealed class PdfEngineBuilder<TRequest>
+    : BaseBuilder<TRequest, PdfEngineBuilder<TRequest>>
+    where TRequest : PdfEngineRequest
+{
+    internal PdfEngineBuilder(TRequest request) : base(request)
+    {
+    }
+
+    /// <summary>
+    /// Adds PDF files to process.
+    /// </summary>
+    public PdfEngineBuilder<TRequest> WithPdfs(Action<AssetBuilder> action)
+    {
+        if (action == null) throw new ArgumentNullException(nameof(action));
+
+        action(new AssetBuilder(this.Request.Assets ??= new AssetDictionary()));
+
+        return this;
+    }
+
+    /// <summary>
+    /// Adds PDF files asynchronously.
+    /// </summary>
+    public PdfEngineBuilder<TRequest> WithPdfsAsync(Func<AssetBuilder, Task> asyncAction)
+    {
+        if (asyncAction == null) throw new ArgumentNullException(nameof(asyncAction));
+
+        this.BuildTasks.Add(asyncAction(new AssetBuilder(this.Request.Assets ??= new AssetDictionary())));
+
+        return this;
+    }
+}
+
+/// <summary>
+/// Static factory for creating PDF engine builders for specific operations.
+/// </summary>
+public static class PdfEngineBuilders
+{
+    /// <summary>
+    /// Creates a builder for flattening PDF form fields into static content.
+    /// </summary>
+    public static PdfEngineBuilder<FlattenPdfRequest> Flatten()
+    {
+        return new PdfEngineBuilder<FlattenPdfRequest>(new FlattenPdfRequest());
+    }
+
+    /// <summary>
+    /// Creates a builder for rotating PDF pages.
+    /// </summary>
+    public static PdfEngineBuilder<RotatePdfRequest> Rotate(RotationAngle angle, PageRanges? pages = null)
+    {
+        var request = new RotatePdfRequest
+        {
+            RotateAngle = angle ?? throw new ArgumentNullException(nameof(angle)),
+            RotatePages = pages
+        };
+        return new PdfEngineBuilder<RotatePdfRequest>(request);
+    }
+
+    /// <summary>
+    /// Creates a builder for rotating PDF pages.
+    /// </summary>
+    public static PdfEngineBuilder<RotatePdfRequest> Rotate(int angleDegrees, string? pages = null)
+    {
+        return Rotate(
+            RotationAngle.Create(angleDegrees),
+            pages != null ? PageRanges.Create(pages) : null);
+    }
+
+    /// <summary>
+    /// Creates a builder for splitting PDFs.
+    /// </summary>
+    public static PdfEngineBuilder<SplitPdfRequest> Split(SplitMode mode, string span, bool unify = false)
+    {
+        var request = new SplitPdfRequest
+        {
+            Mode = mode,
+            Span = span ?? throw new ArgumentNullException(nameof(span)),
+            Unify = unify
+        };
+        return new PdfEngineBuilder<SplitPdfRequest>(request);
+    }
+
+    /// <summary>
+    /// Creates a builder for encrypting PDFs with passwords.
+    /// </summary>
+    public static PdfEngineBuilder<EncryptPdfRequest> Encrypt(string userPassword, string? ownerPassword = null)
+    {
+        if (string.IsNullOrWhiteSpace(userPassword))
+            throw new ArgumentException("User password is required.", nameof(userPassword));
+
+        var request = new EncryptPdfRequest
+        {
+            UserPassword = userPassword,
+            OwnerPassword = ownerPassword
+        };
+        return new PdfEngineBuilder<EncryptPdfRequest>(request);
+    }
+
+    /// <summary>
+    /// Creates a builder for reading metadata from PDFs. Returns JSON.
+    /// </summary>
+    public static PdfEngineBuilder<ReadMetadataRequest> ReadMetadata()
+    {
+        return new PdfEngineBuilder<ReadMetadataRequest>(new ReadMetadataRequest());
+    }
+
+    /// <summary>
+    /// Creates a builder for writing metadata to PDFs.
+    /// </summary>
+    public static PdfEngineBuilder<WriteMetadataRequest> WriteMetadata(JObject metadata)
+    {
+        var request = new WriteMetadataRequest
+        {
+            Metadata = metadata ?? throw new ArgumentNullException(nameof(metadata))
+        };
+        return new PdfEngineBuilder<WriteMetadataRequest>(request);
+    }
+
+    /// <summary>
+    /// Creates a builder for writing metadata to PDFs.
+    /// </summary>
+    public static PdfEngineBuilder<WriteMetadataRequest> WriteMetadata(IDictionary<string, object> metadata)
+    {
+        return WriteMetadata(JObject.FromObject(metadata));
+    }
+}

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

@@ -0,0 +1,34 @@
+// Copyright 2019-2026 Chris Mohan, Jaben Cargman
+//  and GotenbergSharpApiClient Contributors
+//
+//  Licensed under the Apache License, Version 2.0
+
+namespace Gotenberg.Sharp.API.Client.Domain.Requests;
+
+public sealed class EncryptPdfRequest : PdfEngineRequest
+{
+    protected override string ApiPath => Constants.Gotenberg.PdfEngines.ApiPaths.Encrypt;
+
+    public string? UserPassword { get; set; }
+
+    public string? OwnerPassword { get; set; }
+
+    protected override void Validate()
+    {
+        if (string.IsNullOrWhiteSpace(this.UserPassword))
+            throw new InvalidOperationException("User password is required for encryption.");
+
+        base.Validate();
+    }
+
+    protected override IEnumerable<HttpContent> ToHttpContent()
+    {
+        yield return CreateFormDataItem(this.UserPassword!, "userPassword");
+
+        if (!string.IsNullOrWhiteSpace(this.OwnerPassword))
+            yield return CreateFormDataItem(this.OwnerPassword, "ownerPassword");
+
+        foreach (var content in base.ToHttpContent())
+            yield return content;
+    }
+}

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

@@ -0,0 +1,11 @@
+// Copyright 2019-2026 Chris Mohan, Jaben Cargman
+//  and GotenbergSharpApiClient Contributors
+//
+//  Licensed under the Apache License, Version 2.0
+
+namespace Gotenberg.Sharp.API.Client.Domain.Requests;
+
+public sealed class FlattenPdfRequest : PdfEngineRequest
+{
+    protected override string ApiPath => Constants.Gotenberg.PdfEngines.ApiPaths.Flatten;
+}

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

@@ -0,0 +1,55 @@
+// Copyright 2019-2026 Chris Mohan, Jaben Cargman
+//  and GotenbergSharpApiClient Contributors
+//
+//  Licensed under the Apache License, Version 2.0 (the "License");
+//  you may not use this file except in compliance with the License.
+//  You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+//  Unless required by applicable law or agreed to in writing, software
+//  distributed under the License is distributed on an "AS IS" BASIS,
+//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+//  See the License for the specific language governing permissions and
+//  limitations under the License.
+
+namespace Gotenberg.Sharp.API.Client.Domain.Requests;
+
+/// <summary>
+/// Base class for standalone PDF engine operations (flatten, rotate, split, encrypt,
+/// watermark, stamp, metadata). Each takes PDF files as input and returns processed output.
+/// </summary>
+public abstract class PdfEngineRequest : BuildRequestBase
+{
+    protected override void Validate()
+    {
+        if (this.Assets == null || !this.Assets.Any())
+            throw new InvalidOperationException("At least one PDF file is required.");
+
+        base.Validate();
+    }
+
+    protected override IEnumerable<HttpContent> ToHttpContent()
+    {
+        foreach (var item in this.Assets.IfNullEmpty().Where(item => item.IsValid()))
+        {
+            var contentItem = item.Value.ToHttpContentItem();
+
+            contentItem.Headers.ContentDisposition =
+                new ContentDispositionHeaderValue(Constants.HttpContent.Disposition.Types.FormData)
+                {
+                    Name = Constants.Gotenberg.SharedFormFieldNames.Files, FileName = item.Key
+                };
+
+            contentItem.Headers.ContentType = new MediaTypeHeaderValue(Constants.HttpContent.MediaTypes.ApplicationPdf);
+
+            yield return contentItem;
+        }
+
+        foreach (var item in this.Config.IfNullEmptyContent())
+            yield return item;
+
+        foreach (var content in base.ToHttpContent())
+            yield return content;
+    }
+}