Merge pull request #75 from ChangemakerStudios/feature/standalone-pdf-operations

Add standalone PDF engine operations

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...");
+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...");
+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...");
+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...");
+using 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>"));
+
+    using 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 = !string.IsNullOrWhiteSpace(span) ? span : throw new ArgumentException("Span must not be null or whitespace.", 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 ArgumentException("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,14 @@
+// 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;
+
+/// <summary>
+/// Flattens PDF form fields into static content.
+/// </summary>
+public sealed class FlattenPdfRequest : PdfEngineRequest
+{
+    protected override string ApiPath => Constants.Gotenberg.PdfEngines.ApiPaths.Flatten;
+}