docpdf 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a534da9974aa240254b1ae28fefb29de094cfff9209ca162259b62c63eb517a5
+  data.tar.gz: 3ab77722e521e913cb5dc574ebbc7af2a0436abaf5040c6399e10f2d51311367
+SHA512:
+  metadata.gz: 4c3552cec9c8a2b92f730ec784a3f0117f4eb0a1f6190b4b38c1dfe0bc1e3c7a7a6f7234b57c1d1e59f4d095f52cff99249a586b7402aaccb278240e7da3fb58
+  data.tar.gz: cd32abba539b7dea911026697fb62ca3ff56c936306a2850058a926dda7bbaab9bfc54d7f5a2b4732493428a2342a0b8f8a3233f2951b1340c3c7aa19a114c50

data/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+## [0.1.0] - 2026-04-03
+
+Initial release.
+
+### Added
+- Multi-format document-to-PDF conversion via LibreOffice:
+  - Word (.doc, .docx)
+  - Excel (.xls, .xlsx)
+  - PowerPoint (.ppt, .pptx)
+  - OpenDocument (.odt, .ods, .odp)
+  - CSV, HTML, RTF
+- Plain text to PDF via Prawn or HexaPDF
+- Image to PDF via RMagick or MiniMagick (JPEG, PNG, HEIC, WebP)
+- PDF passthrough
+- PDF watermarking with image and text stamps
+  - Image stamps with configurable width, height (proportional if omitted), and opacity
+  - Text stamps with configurable font, font_size, color, and rotation
+  - Text auto-scales to fit page when font size would cause overflow
+  - Rotated text uses correct bounding box for edge/corner positioning
+  - Position grid: `:center`, `:top`, `:bottom`, `:left`, `:right`, `:top_left`, `:top_right`, `:bottom_left`, `:bottom_right`
+  - Stamp page matches source PDF page size
+  - Per-stamp offsets (`offset_x`, `offset_y`) for precise placement
+  - Per-stamp page targeting: `:all`, `:first`, `:last`, `:odd`, `:even`, specific page numbers, arrays, and ranges
+  - Multiple stamps per call (image and text can be mixed)
+- Chainable API: `DocPDF.convert("file.docx").watermark({ text: "DRAFT", opacity: 0.1 })`
+- Pluggable adapter architecture with zero hard dependencies
+  - **Converter adapters**: Soffice, Prawn, HexaPDF, RMagick, MiniMagick, Passthrough, Fallback
+  - **Stamper adapters**: HexaPDF, CombinePDF (with Prawn)
+  - Auto-detected at runtime based on MIME type and gem availability
+  - Extensible via `ConverterResolver.register` and `StamperResolver.register`
+- Flexible input: file path, Pathname, IO object, raw binary data
+- Works with Dragonfly, Active Storage, CarrierWave, Shrine, and Rails UploadedFile
+- `DocPDF::Result` returned from both `convert` and `watermark` with `.data` and `.filename`
+- Extension-based MIME type detection
+- Grouped configuration: `text_options` for plain text conversion, `watermark_options` for text watermark defaults
+- Consistent error wrapping across all adapters via `DocPDF::ConversionError`
+- Soffice stderr captured in `ConversionError` messages for diagnostics
+- Ruby 3.3, 3.4, and 4.0 support
+- Tested with Appraisal across 6 adapter configurations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Velocity Labs, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,327 @@
+# DocPDF
+
+Convert documents from any common format to PDF, with optional watermarking. Zero hard dependencies; bring your own PDF library.
+
+## Supported Formats
+
+| Input Format | Conversion Tool | Ruby Gem Required |
+|-------------|----------------|-------------------|
+| PDF | Passthrough | None |
+| Word (.doc, .docx) | LibreOffice | None (system dep) |
+| Excel (.xls, .xlsx) | LibreOffice | None (system dep) |
+| PowerPoint (.ppt, .pptx) | LibreOffice | None (system dep) |
+| OpenDocument (.odt, .ods, .odp) | LibreOffice | None (system dep) |
+| CSV, HTML, RTF | LibreOffice | None (system dep) |
+| Plain text | Prawn or HexaPDF | `prawn` or `hexapdf` |
+| JPEG, PNG | RMagick or MiniMagick | `rmagick` or `mini_magick` |
+| HEIC, WebP | RMagick or MiniMagick | `rmagick` or `mini_magick` |
+
+> **Note:** PDF and Word/RTF conversion work with zero gem dependencies. You only need adapter gems for text, image, and watermarking features. If you try to use a feature without the required gem, you'll get a clear error telling you which gem to add.
+
+## Installation
+
+```ruby
+gem "docpdf"
+```
+
+Then pick the adapters you need:
+
+```ruby
+# Minimum for text + watermarking (one gem covers both):
+gem "hexapdf"
+
+# Or use two separate gems:
+gem "prawn"       # text-to-PDF conversion + watermark stamp generation
+gem "combine_pdf" # PDF watermark stamping
+
+# For image conversion (pick one):
+gem "rmagick"     # full ImageMagick bindings (handles HEIC, WebP, JPEG, PNG)
+gem "mini_magick" # lighter shell wrapper (same format support)
+```
+
+**System dependencies:**
+
+- **Ruby >= 3.3**
+- **LibreOffice** for Word/RTF conversion. `soffice` must be on PATH.
+- **ImageMagick** + **Ghostscript** required by RMagick/MiniMagick for image conversion.
+
+## Usage
+
+### Convert files
+
+```ruby
+# From a file path (format is detected automatically)
+result = DocPDF.convert("document.docx")     # Word -> PDF via LibreOffice
+result = DocPDF.convert("spreadsheet.xlsx")  # Excel -> PDF via LibreOffice
+result = DocPDF.convert("slides.pptx")       # PowerPoint -> PDF via LibreOffice
+result = DocPDF.convert("document.odt")      # OpenDocument -> PDF via LibreOffice
+result = DocPDF.convert("data.csv")          # CSV -> PDF via LibreOffice
+result = DocPDF.convert("page.html")         # HTML -> PDF via LibreOffice
+result = DocPDF.convert("notes.txt")         # Text -> PDF via Prawn/HexaPDF
+result = DocPDF.convert("scan.heic")         # Image -> PDF via RMagick/MiniMagick
+result = DocPDF.convert("existing.pdf")      # PDF passthrough
+
+# From an IO object (Rails UploadedFile, Tempfile, StringIO, etc.)
+result = DocPDF.convert(params[:file])
+
+# From raw binary data
+result = DocPDF.convert(data: file_contents, mime_type: "image/png", filename: "photo.png")
+```
+
+The result is a `DocPDF::Result` with `data` (binary string) and `filename` (suggested output name).
+
+### Watermark PDFs
+
+Pass one or more stamp hashes. Each stamp uses either `image:` or `text:`.
+
+```ruby
+# Image watermark
+result = DocPDF.watermark("report.pdf",
+  { image: "logo.png", opacity: 0.06, position: :center })
+
+# Text watermark (e.g., "DRAFT" diagonally across the page)
+result = DocPDF.watermark("report.pdf",
+  { text: "DRAFT", opacity: 0.1, position: :center, rotation: 45 })
+
+# Mix image and text stamps with page targeting
+result = DocPDF.watermark("report.pdf",
+  { text: "CONFIDENTIAL", opacity: 0.1, position: :center, font_size: 60, rotation: 45 },
+  { image: "logo.png", opacity: 0.3, position: :top_right, width: 80, pages: :first })
+
+# Chain onto a conversion
+result = DocPDF.convert("document.docx")
+  .watermark({ text: "DRAFT", opacity: 0.1 })
+```
+
+Both `convert` and `watermark` return a `DocPDF::Result`, so you can chain them. `watermark` accepts file paths, IO objects, raw bytes, or a `Result` from a prior call.
+
+Text watermarks auto-scale to fit the page when the font size would cause overflow.
+
+#### Image stamp options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `image` | | Path to the image file |
+| `opacity` | `0.1` | Transparency (0.0 = invisible, 1.0 = opaque) |
+| `position` | `:center` | Anchor point on the page (see below) |
+| `width` | `250` | Image width in points |
+| `height` | proportional | Image height in points (scales proportionally if omitted) |
+| `offset_x` | `0` | Horizontal nudge from anchor (positive = right, negative = left) |
+| `offset_y` | `0` | Vertical nudge from anchor (positive = up, negative = down) |
+| `pages` | `:all` | Which pages to stamp (see below) |
+
+#### Text stamp options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `text` | | The text to render |
+| `opacity` | `0.1` | Transparency (0.0 = invisible, 1.0 = opaque) |
+| `position` | `:center` | Anchor point on the page (see below) |
+| `font` | `"Helvetica"` | Font name (configurable via `watermark_options`) |
+| `font_size` | `72` | Font size in points (configurable via `watermark_options`) |
+| `color` | `"AAAAAA"` | Hex color string (configurable via `watermark_options`) |
+| `rotation` | `45` | Degrees counter-clockwise (configurable via `watermark_options`) |
+| `offset_x` | `0` | Horizontal nudge from anchor |
+| `offset_y` | `0` | Vertical nudge from anchor |
+| `pages` | `:all` | Which pages to stamp (see below) |
+
+#### Positions
+
+Stamps are centered on the anchor point, not placed by their corner.
+
+| Position | Anchor |
+|----------|--------|
+| `:center` | Center of page |
+| `:top` | Top center |
+| `:bottom` | Bottom center |
+| `:left` | Left center |
+| `:right` | Right center |
+| `:top_left` | Top-left corner |
+| `:top_right` | Top-right corner |
+| `:bottom_left` | Bottom-left corner |
+| `:bottom_right` | Bottom-right corner |
+
+#### Page targeting
+
+| Value | Pages stamped |
+|-------|---------------|
+| `:all` | Every page (default) |
+| `:first` | First page only |
+| `:last` | Last page only |
+| `:odd` | Odd pages (1, 3, 5...) |
+| `:even` | Even pages (2, 4, 6...) |
+| `3` | Specific page (1-indexed) |
+| `[1, 3, 5]` | Array of page numbers |
+| `2..5` | Range of page numbers |
+
+### Rails integration
+
+DocPDF works with file upload and attachment libraries out of the box:
+
+```ruby
+# ActionDispatch::Http::UploadedFile
+result = DocPDF.convert(params[:document])
+
+# Dragonfly
+result = DocPDF.convert(record.document, filename: "output.pdf")
+
+# Active Storage
+result = DocPDF.convert(user.document)
+
+# CarrierWave / Shrine
+result = DocPDF.convert(record.file)
+```
+
+MIME type and filename are auto-extracted from each library's metadata. Use `filename:` to set the output name without affecting format detection.
+
+## Configuration
+
+All configuration is optional. DocPDF works out of the box with sensible defaults.
+
+```ruby
+DocPDF.configure do |config|
+  # LibreOffice binary path (default: "soffice", found via PATH)
+  config.soffice_path = "/usr/bin/soffice"
+
+  # Stamper adapter for watermarking (default: nil, auto-detects hexapdf then combine_pdf)
+  config.stamper = :hexapdf  # or :combine_pdf
+
+  # Page size (default: "LETTER")
+  config.page_size = "A4"
+
+  # Plain text file conversion defaults
+  config.text_options = {
+    font: "Helvetica",          # default: "Courier"
+    font_size: 12,              # default: 10
+    margins: [72, 72, 72, 72],  # default: [50, 50, 50, 50] (points: top, right, bottom, left)
+    color: "000000",            # default: "333333" (hex)
+  }
+
+  # Text watermark defaults (per-stamp options override these)
+  config.watermark_options = {
+    font: "Times",       # default: "Helvetica"
+    font_size: 96,       # default: 72
+    color: "FF0000",     # default: "AAAAAA" (hex)
+    rotation: 30,        # default: 45 (degrees counter-clockwise)
+  }
+end
+```
+
+Converter adapters (for format-to-PDF conversion) are auto-detected based on MIME type and gem availability. The first available adapter wins, in registration order:
+
+- **text/plain**: Prawn, then HexaPDF
+- **image/\***: RMagick, then MiniMagick
+- **Office formats**: LibreOffice (always available if installed)
+- **application/pdf**: Passthrough (returned unchanged)
+- **Unknown formats**: Fallback (tries LibreOffice, then returns raw data)
+
+## Adapters
+
+DocPDF has two types of adapters:
+
+**Converter adapters** convert input data to PDF:
+
+| Adapter | Gem | Formats |
+|---------|-----|---------|
+| Soffice | None (system) | Word, Excel, PowerPoint, ODF, CSV, HTML, RTF |
+| Prawn | `prawn` | Plain text |
+| HexaPDF | `hexapdf` | Plain text |
+| RMagick | `rmagick` | JPEG, PNG, HEIC, WebP |
+| MiniMagick | `mini_magick` | JPEG, PNG, HEIC, WebP |
+| Passthrough | None | PDF (returned unchanged) |
+| Fallback | None | Unknown formats (tries LibreOffice, then raw data) |
+
+**Stamper adapters** apply watermarks to PDFs:
+
+| Adapter | Gem(s) | Notes |
+|---------|--------|-------|
+| HexaPDF | `hexapdf` | All-in-one, handles both stamp generation and overlay |
+| CombinePDF | `combine_pdf` + `prawn` | Prawn generates the stamp page, CombinePDF overlays it |
+
+### Custom adapters
+
+Register your own converter or stamper:
+
+```ruby
+# Custom converter for a specific MIME type
+DocPDF::ConverterResolver.register(:my_converter,
+  require_name: "my_gem",
+  mime_types: %w[application/x-custom],
+  loader: -> { require "docpdf/adapters/converters/my_converter"; MyConverter })
+
+# Custom stamper
+DocPDF::StamperResolver.register(:my_stamper,
+  loader: -> { require "my_stamper"; MyStamper })
+```
+
+## Error Handling
+
+All errors inherit from `DocPDF::Error`, so you can catch everything with one rescue or handle specific cases:
+
+```ruby
+begin
+  result = DocPDF.convert("file.docx")
+rescue DocPDF::Error => e
+  # Catch any docpdf error
+end
+```
+
+Specific error classes:
+
+| Error | When |
+|-------|------|
+| `DocPDF::ConversionError` | Conversion failed (message includes adapter name and details) |
+| `DocPDF::SofficeNotFoundError` | LibreOffice not installed or not on PATH |
+| `DocPDF::AdapterNotFoundError` | Required gem not installed (message tells you which to add) |
+
+## Deployment Notes
+
+### ImageMagick policy.xml
+
+Most Linux distributions ship ImageMagick with PDF conversion disabled for security. If image-to-PDF conversion fails with a permission error, find your ImageMagick `policy.xml` file (commonly at `/etc/ImageMagick-6/policy.xml` or `/etc/ImageMagick-7/policy.xml`) and change the PDF coder policy from `rights="none"` to `rights="read|write"`.
+
+### LibreOffice on Heroku
+
+Use the [LibreOffice buildpack](https://github.com/heroku/heroku-buildpack-apt) or AppImage approach.
+
+### LibreOffice on Docker
+
+```dockerfile
+RUN apt-get update && apt-get install -y libreoffice-writer
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub](https://github.com/velocity-labs/docpdf).
+
+1. Fork the repo
+2. Create your feature branch (`git checkout -b my-feature`)
+3. Make your changes with tests
+4. Ensure all tests pass (`bundle exec rake test`)
+5. Commit and push
+6. Open a pull request
+
+## Testing
+
+```bash
+# Install dependencies
+bundle install
+
+# Run the full test suite
+bundle exec rake test
+
+# Run tests for a specific adapter configuration
+bundle exec appraisal hexapdf-only rake test
+bundle exec appraisal no-adapters rake test
+
+# Run all appraisals
+bundle exec appraisal rake test
+```
+
+Available appraisals: `all`, `hexapdf-only`, `prawn-combine-pdf`, `rmagick`, `mini-magick`, `no-adapters`.
+
+Tests require LibreOffice and ImageMagick installed locally.
+
+## License
+
+Copyright (c) 2026 Velocity Labs, LLC. Released under the [MIT License](LICENSE.txt).

data/lib/docpdf/adapters/converters/base.rb

@@ -0,0 +1,15 @@
+module DocPDF
+  module Adapters
+    module Converters
+      class Base
+        MIME_TYPES = [].freeze
+
+        class << self
+          def convert(data, source_filename)
+            raise NotImplementedError, "#{name} must implement .convert(data, source_filename)"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/docpdf/adapters/converters/fallback.rb

@@ -0,0 +1,45 @@
+require_relative "base"
+
+module DocPDF
+  module Adapters
+    module Converters
+      # Fallback converter for unrecognized mime types. Tries three strategies
+      # in order:
+      #
+      # 1. If the source filename has a known image extension, detect its mime
+      #    type and delegate to the appropriate image converter.
+      # 2. Attempt conversion via LibreOffice (soffice), which can handle many
+      #    formats not explicitly registered.
+      # 3. If soffice is unavailable or fails, return the raw data unchanged.
+      class Fallback < Base
+        IMAGE_EXTENSIONS = %w[.heic .heif .webp .jpg .jpeg .png].freeze
+
+        class << self
+          def convert(data, source_filename)
+            convert_by_extension(data, source_filename) ||
+              convert_with_soffice(data, source_filename) ||
+              data
+          end
+
+          private
+
+          def convert_by_extension(data, source_filename)
+            ext = source_filename ? File.extname(source_filename).downcase : nil
+            return unless ext && IMAGE_EXTENSIONS.include?(ext)
+
+            mime_type = MimeDetector.detect(source_filename)
+            return unless mime_type
+
+            ConverterResolver.resolve(mime_type).convert(data, source_filename)
+          end
+
+          def convert_with_soffice(data, source_filename)
+            Soffice.convert(data, source_filename)
+          rescue SofficeNotFoundError, ConversionError
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/docpdf/adapters/converters/hexapdf.rb

@@ -0,0 +1,69 @@
+require "hexapdf"
+require_relative "base"
+
+module DocPDF
+  module Adapters
+    module Converters
+      class Hexapdf < Base
+        MIME_TYPES = %w[text/plain].freeze
+
+        HEXAPDF_PAGE_SIZES = {
+          "LETTER" => :Letter, "LEGAL" => :Legal, "TABLOID" => :Tabloid,
+          "A0" => :A0, "A1" => :A1, "A2" => :A2, "A3" => :A3, "A4" => :A4,
+          "A5" => :A5, "A6" => :A6, "B0" => :B0, "B1" => :B1, "B2" => :B2,
+          "B3" => :B3, "B4" => :B4, "B5" => :B5, "B6" => :B6,
+        }.freeze
+
+        class << self
+          def convert(data, _source_filename)
+            config = DocPDF.configuration
+            opts = config.text_options
+            content = data.dup.force_encoding("UTF-8")
+            page_size = normalize_page_size(config.page_size)
+
+            doc = HexaPDF::Document.new
+            page = doc.pages.add(page_size)
+            canvas = page.canvas
+
+            canvas.font(opts[:font], size: opts[:font_size])
+            canvas.fill_color(opts[:color])
+
+            margins = opts[:margins]
+            y = page.box.height - margins[0]
+            line_height = opts[:font_size] * 1.4
+
+            content.each_line do |line|
+              if y < margins[2]
+                page = doc.pages.add(page_size)
+                canvas = page.canvas
+                canvas.font(opts[:font], size: opts[:font_size])
+                canvas.fill_color(opts[:color])
+                y = page.box.height - margins[0]
+              end
+              canvas.text(line.chomp, at: [margins[3], y])
+              y -= line_height
+            end
+
+            write_to_string(doc)
+          rescue HexaPDF::Error => e
+            raise ConversionError, "HexaPDF failed to render text to PDF: #{e.message}"
+          end
+
+          private
+
+          def normalize_page_size(size)
+            return size if size.is_a?(Symbol)
+
+            HEXAPDF_PAGE_SIZES[size.to_s.upcase] || size.to_sym
+          end
+
+          def write_to_string(doc)
+            io = StringIO.new
+            doc.write(io)
+            io.string
+          end
+        end
+      end
+    end
+  end
+end

data/lib/docpdf/adapters/converters/mini_magick.rb

@@ -0,0 +1,31 @@
+require "mini_magick"
+require_relative "base"
+
+module DocPDF
+  module Adapters
+    module Converters
+      class MiniMagick < Base
+        MIME_TYPES = %w[image/jpeg image/png image/heic image/heif image/webp].freeze
+
+        class << self
+          def convert(data, filename)
+            img = nil
+            Tempfile.create(["docpdf", File.extname(filename || ".tmp")]) do |tempfile|
+              tempfile.binmode
+              tempfile.write(data)
+              tempfile.rewind
+
+              img = ::MiniMagick::Image.open(tempfile.path)
+              img.format("pdf")
+              img.to_blob
+            end
+          rescue ::MiniMagick::Error => e
+            raise ConversionError, "MiniMagick failed to convert #{filename || 'image'} to PDF: #{e.message}"
+          ensure
+            img&.destroy!
+          end
+        end
+      end
+    end
+  end
+end

data/lib/docpdf/adapters/converters/passthrough.rb

@@ -0,0 +1,17 @@
+require_relative "base"
+
+module DocPDF
+  module Adapters
+    module Converters
+      class Passthrough < Base
+        MIME_TYPES = %w[application/pdf].freeze
+
+        class << self
+          def convert(data, _source_filename)
+            data
+          end
+        end
+      end
+    end
+  end
+end

data/lib/docpdf/adapters/converters/prawn.rb

@@ -0,0 +1,26 @@
+require "prawn"
+require_relative "base"
+
+module DocPDF
+  module Adapters
+    module Converters
+      class Prawn < Base
+        MIME_TYPES = %w[text/plain].freeze
+
+        class << self
+          def convert(data, _source_filename)
+            config = DocPDF.configuration
+            opts = config.text_options
+            content = data.dup.force_encoding("UTF-8")
+            pdf = ::Prawn::Document.new(page_size: config.page_size, margin: opts[:margins])
+            pdf.font(opts[:font], size: opts[:font_size])
+            pdf.text content, color: opts[:color]
+            pdf.render
+          rescue ::Prawn::Errors::UnknownFont, ::Prawn::Errors::CannotFit => e
+            raise ConversionError, "Prawn failed to render text to PDF: #{e.message}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/docpdf/adapters/converters/rmagick.rb

@@ -0,0 +1,30 @@
+require "rmagick"
+require_relative "base"
+
+module DocPDF
+  module Adapters
+    module Converters
+      class Rmagick < Base
+        MIME_TYPES = %w[image/jpeg image/png image/heic image/heif image/webp].freeze
+
+        class << self
+          def convert(data, filename)
+            img = nil
+            Tempfile.create(["docpdf", File.extname(filename || ".tmp")]) do |tempfile|
+              tempfile.binmode
+              tempfile.write(data)
+              tempfile.rewind
+
+              img = Magick::Image.read(tempfile.path).first
+              img.to_blob { |attrs| attrs.format = "PDF" }
+            end
+          rescue Magick::ImageMagickError => e
+            raise ConversionError, "RMagick failed to convert #{filename || 'image'} to PDF: #{e.message}"
+          ensure
+            img&.destroy!
+          end
+        end
+      end
+    end
+  end
+end