DocumentService/DocumentOperator.API/Controllers/PdfOperationsController.cs

using DocumentOperator.Application.AddAnnotation;
using DocumentOperator.Application.MergePdfs;
using DocumentOperator.Domain.Common.Exceptions;
using DocumentOperator.Domain.Models.ValueObjects;
using MediatR;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;

namespace DocumentOperator.API.Controllers;

/// <summary>
/// Controller for PDF operations (merge, stamp, annotate).
/// </summary>
[ApiController]
[Route("api/pdf/operations")]
public class PdfOperationsController(IMediator mediator) : ControllerBase
{
    /// <summary>
    /// Merges multiple PDF files into a single PDF.
    /// Supports multipart/form-data file upload.
    /// </summary>
    /// <param name="files">PDF files to merge (minimum 2 required)</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>Merged PDF file</returns>
    /// <response code="200">PDFs merged successfully - returns merged PDF</response>
    /// <response code="400">Invalid input (fewer than 2 files, corrupted PDF)</response>
    /// <response code="500">Internal server error during PDF processing</response>
    [HttpPost("merge", Name = "MergeFromFiles")]
    [Consumes("multipart/form-data")]
    [ProducesResponseType(typeof(FileContentResult), StatusCodes.Status200OK)]
    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]
    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status500InternalServerError)]
    public async Task<IActionResult> MergeFromFiles(
        [FromForm] List<IFormFile> files,
        CancellationToken cancellationToken)
    {
        // Convert IFormFile[] to Stream[] (use OpenReadStream directly - no buffering)
        var streams = files.Select(f => f.OpenReadStream()).ToList();

        // Send command to MediatR (no page ranges for now - multipart binding is complex)
        var command = new MergePdfsCommand 
        { 
            PdfStreams = streams,
            PageRanges = null
        };
        
        byte[] mergedPdf = await mediator.Send(command, cancellationToken);

        // Return merged PDF
        return File(mergedPdf, "application/pdf", "merged.pdf");
    }

    /// <summary>
    /// Merges multiple PDF files into a single PDF.
    /// Supports Base64-encoded PDFs via JSON payload.
    /// </summary>
    /// <param name="request">Request containing Base64-encoded PDFs and optional page ranges</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>Merged PDF file</returns>
    /// <response code="200">PDFs merged successfully - returns merged PDF</response>
    /// <response code="400">Invalid input (Base64 format error, fewer than 2 files, corrupted PDF, invalid page range)</response>
    /// <response code="500">Internal server error during PDF processing</response>
    [HttpPost("merge", Name = "MergeFromBase64")]
    [Consumes("application/json")]
    [ProducesResponseType(typeof(FileContentResult), StatusCodes.Status200OK)]
    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]
    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status500InternalServerError)]
    public async Task<IActionResult> MergeFromBase64(
        [FromBody] MergePdfsBase64Request request,
        CancellationToken cancellationToken)
    {
        // Convert Base64[] to MemoryStream[]
        List<Stream> streams = [];
        try
        {
            foreach (var base64Pdf in request.Base64Pdfs)
            {
                byte[] pdfBytes = Convert.FromBase64String(base64Pdf);
                streams.Add(new MemoryStream(pdfBytes));
            }
        }
        catch (FormatException ex)
        {
            // Dispose opened streams on error
            foreach (var stream in streams) stream.Dispose();
            throw new BadRequestException("Invalid Base64 format: " + ex.Message);
        }

        var command = new MergePdfsCommand 
        { 
            PdfStreams = streams,
            PageRanges = request.PageRanges
        };
        
        byte[] mergedPdf = await mediator.Send(command, cancellationToken);

        // Cleanup streams (important for MemoryStreams we created)
        foreach (var stream in streams) stream.Dispose();

        return File(mergedPdf, "application/pdf", "merged.pdf");
    }

    /// <summary>
    /// Adds an annotation to a PDF document.
    /// Supports multipart/form-data file upload.
    /// </summary>
    /// <param name="request">Multipart form data containing PDF file and annotation parameters</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>Annotated PDF file</returns>
    /// <response code="200">Annotation added successfully - returns annotated PDF</response>
    /// <response code="400">Invalid input (invalid page number, missing required parameters)</response>
    /// <response code="500">Internal server error during PDF processing</response>
    [HttpPost("annotate", Name = "AnnotateFromFile")]
    [Consumes("multipart/form-data")]
    [ProducesResponseType(typeof(FileContentResult), StatusCodes.Status200OK)]
    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]
    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status500InternalServerError)]
    public async Task<IActionResult> AnnotateFromFile(
        [FromForm] AddAnnotationMultipartRequest request,
        CancellationToken cancellationToken)
    {
        var command = new AddAnnotationCommand
        {
            PdfStream = request.File.OpenReadStream(),
            AnnotationType = request.AnnotationType,
            PageNumber = request.PageNumber,
            Rectangle = (request.X1, request.Y1, request.X2, request.Y2),
            Content = request.Content,
            Author = request.Author,
            Color = request.Color,
            TextMarkupStyle = request.TextMarkupStyle
        };

        byte[] annotatedPdf = await mediator.Send(command, cancellationToken);

        return File(annotatedPdf, "application/pdf", "annotated.pdf");
    }

    /// <summary>
    /// Adds an annotation to a PDF document.
    /// Supports Base64-encoded PDF via JSON payload.
    /// </summary>
    /// <param name="command">Command containing all annotation parameters (including Base64 PDF)</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>Annotated PDF file</returns>
    /// <response code="200">Annotation added successfully - returns annotated PDF</response>
    /// <response code="400">Invalid input (Base64 format error, invalid page number, missing required parameters)</response>
    /// <response code="500">Internal server error during PDF processing</response>
    [HttpPost("annotate", Name = "AnnotateFromBase64")]
    [Consumes("application/json")]
    [ProducesResponseType(typeof(FileContentResult), StatusCodes.Status200OK)]
    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]
    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status500InternalServerError)]
    public async Task<IActionResult> AnnotateFromBase64(
        [FromBody] AddAnnotationBase64Command command,
        CancellationToken cancellationToken)
    {
        // Convert Base64 to MemoryStream
        Stream pdfStream;
        try
        {
            byte[] pdfBytes = Convert.FromBase64String(command.Base64Pdf);
            pdfStream = new MemoryStream(pdfBytes);
        }
        catch (FormatException ex)
        {
            throw new BadRequestException("Invalid Base64 format: " + ex.Message);
        }

        var annotationCommand = new AddAnnotationCommand
        {
            PdfStream = pdfStream,
            AnnotationType = command.AnnotationType,
            PageNumber = command.PageNumber,
            Rectangle = (command.X1, command.Y1, command.X2, command.Y2),
            Content = command.Content,
            Author = command.Author,
            Color = command.Color,
            TextMarkupStyle = command.TextMarkupStyle
        };

        byte[] annotatedPdf = await mediator.Send(annotationCommand, cancellationToken);

        // Cleanup stream
        pdfStream.Dispose();

        return File(annotatedPdf, "application/pdf", "annotated.pdf");
    }
}

/// <summary>
/// Request DTO for multipart/form-data annotation operation
/// </summary>
public class AddAnnotationMultipartRequest
{
    /// <summary>
    /// PDF file to annotate
    /// </summary>
    public required IFormFile File { get; set; }

    /// <summary>
    /// Type of annotation (TextMarkup, FreeText, StickyNote, Circle, Square)
    /// </summary>
    public required AnnotationType AnnotationType { get; set; }

    /// <summary>
    /// Target page number (1-indexed)
    /// </summary>
    public required int PageNumber { get; set; }

    /// <summary>
    /// Rectangle X1 coordinate
    /// </summary>
    public required double X1 { get; set; }

    /// <summary>
    /// Rectangle Y1 coordinate
    /// </summary>
    public required double Y1 { get; set; }

    /// <summary>
    /// Rectangle X2 coordinate
    /// </summary>
    public required double X2 { get; set; }

    /// <summary>
    /// Rectangle Y2 coordinate
    /// </summary>
    public required double Y2 { get; set; }

    /// <summary>
    /// Annotation content (required for FreeText/StickyNote)
    /// </summary>
    public string? Content { get; set; }

    /// <summary>
    /// Author name (optional)
    /// </summary>
    public string? Author { get; set; }

    /// <summary>
    /// Hex color (6 digits, e.g., "FF0000" for red)
    /// </summary>
    public string? Color { get; set; }

    /// <summary>
    /// Markup style (Highlight/Underline/Strikeout, required for TextMarkup)
    /// </summary>
    public TextMarkupStyle? TextMarkupStyle { get; set; }
}

/// <summary>
/// Request DTO for Base64-encoded PDF merge operation (API layer only - converts to MergePdfsCommand)
/// </summary>
public record MergePdfsBase64Request
{
    /// <summary>
    /// Array of Base64-encoded PDF files (minimum 2 required)
    /// </summary>
    /// <example>["JVBERi0xLjQK...", "JVBERi0xLjQK..."]</example>
    public required List<string> Base64Pdfs { get; init; }

    /// <summary>
    /// Optional page ranges per PDF (null = all pages). 
    /// Format: "1-3,5" means pages 1, 2, 3, and 5.
    /// If provided, array length must match Base64Pdfs length.
    /// </summary>
    /// <example>["1-2", "1,3,5", null]</example>
    public List<string?>? PageRanges { get; init; }
}

/// <summary>
/// Request DTO for Base64-encoded PDF annotation (API layer only - converts to AddAnnotationCommand)
/// </summary>
public record AddAnnotationBase64Command
{
    /// <summary>
    /// Base64-encoded PDF file
    /// </summary>
    /// <example>"JVBERi0xLjQK..."</example>
    public required string Base64Pdf { get; init; }

    /// <summary>
    /// Type of annotation to add
    /// </summary>
    /// <example>TextMarkup</example>
    public required AnnotationType AnnotationType { get; init; }

    /// <summary>
    /// Target page number (1-indexed)
    /// </summary>
    /// <example>1</example>
    public required int PageNumber { get; init; }

    /// <summary>
    /// Rectangle X1 coordinate
    /// </summary>
    /// <example>100.0</example>
    public required double X1 { get; init; }

    /// <summary>
    /// Rectangle Y1 coordinate
    /// </summary>
    /// <example>100.0</example>
    public required double Y1 { get; init; }

    /// <summary>
    /// Rectangle X2 coordinate
    /// </summary>
    /// <example>200.0</example>
    public required double X2 { get; init; }

    /// <summary>
    /// Rectangle Y2 coordinate
    /// </summary>
    /// <example>120.0</example>
    public required double Y2 { get; init; }

    /// <summary>
    /// Annotation content (required for FreeText and StickyNote)
    /// </summary>
    /// <example>"Important text to highlight"</example>
    public string? Content { get; init; }

    /// <summary>
    /// Author name (optional)
    /// </summary>
    /// <example>"John Doe"</example>
    public string? Author { get; init; }

    /// <summary>
    /// Hex color (6 digits, e.g., "FF0000" for red). Optional - defaults vary by annotation type.
    /// </summary>
    /// <example>"FFFF00"</example>
    public string? Color { get; init; }

    /// <summary>
    /// Text markup style (Highlight, Underline, or Strikeout). Required for TextMarkup annotations.
    /// </summary>
    /// <example>Highlight</example>
    public TextMarkupStyle? TextMarkupStyle { get; init; }
}