docpdf 0.1.0

data/lib/docpdf/watermarker.rb

@@ -0,0 +1,164 @@
+module DocPDF
+  class Watermarker
+    POSITIONS = %i[center top bottom left right top_left top_right bottom_left bottom_right].freeze
+
+    STAMP_DEFAULTS = {
+      opacity: 0.1,
+      position: :center,
+      width: 250,
+      offset_x: 0,
+      offset_y: 0,
+      pages: :all,
+    }.freeze
+
+    class << self
+      def calculate_position(position, page_w, page_h, img_w, img_h, offset_x, offset_y)
+        x, y = case position
+                when :center       then [(page_w - img_w) / 2, (page_h - img_h) / 2]
+                when :top          then [(page_w - img_w) / 2, page_h - img_h]
+                when :bottom       then [(page_w - img_w) / 2, 0]
+                when :left         then [0, (page_h - img_h) / 2]
+                when :right        then [page_w - img_w, (page_h - img_h) / 2]
+                when :top_left     then [0, page_h - img_h]
+                when :top_right    then [page_w - img_w, page_h - img_h]
+                when :bottom_left  then [0, 0]
+                when :bottom_right then [page_w - img_w, 0]
+                else                    [(page_w - img_w) / 2, (page_h - img_h) / 2]
+                end
+        [x + offset_x, y + offset_y]
+      end
+
+      def call(source = nil, *stamps, filename: nil, **input_options)
+        pdf_bytes, resolved_filename = resolve_input(source, filename, input_options)
+
+        if stamps.empty?
+          return Result.new(data: pdf_bytes, filename: resolved_filename)
+        end
+
+        normalized = stamps.map { |s| normalize_stamp(s) }
+        stamped = new(pdf_bytes, normalized).call
+        Result.new(data: stamped, filename: resolved_filename)
+      end
+
+      private
+
+      def normalize_stamp(stamp)
+        merged = STAMP_DEFAULTS.merge(stamp)
+        if merged[:text]
+          wm = DocPDF.configuration.watermark_options
+          { font: wm[:font], font_size: wm[:font_size], color: wm[:color], rotation: wm[:rotation] }.merge(merged)
+        else
+          merged
+        end
+      end
+
+      def resolve_input(source, filename, input_options)
+        case source
+        when Result
+          [source.data, filename || source.filename]
+        when Pathname
+          [File.binread(source.to_s), filename || File.basename(source.to_s)]
+        when String
+          if !source.match?(/[\x00-\x08]/) && File.exist?(source)
+            [File.binread(source), filename || File.basename(source)]
+          else
+            [source, filename]
+          end
+        when nil
+          if input_options[:io]
+            io = input_options[:io]
+            resolved_filename = filename || (io.respond_to?(:original_filename) && io.original_filename) || nil
+            [io.read, resolved_filename]
+          elsif input_options[:data]
+            [input_options[:data], filename]
+          else
+            raise ArgumentError, "Provide a file path, IO object, Result, or data:"
+          end
+        else
+          if source.respond_to?(:read)
+            resolved_filename = filename || (source.respond_to?(:original_filename) && source.original_filename) || nil
+            [source.read, resolved_filename]
+          else
+            raise ArgumentError, "Cannot read PDF from #{source.class}. Provide a file path, IO object, Result, or data:"
+          end
+        end
+      end
+    end
+
+    def initialize(pdf_bytes, stamps)
+      @pdf_bytes = pdf_bytes
+      @stamps = stamps
+    end
+
+    def call
+      stamper = StamperResolver.resolve
+
+      if all_stamps_target_all_pages?
+        stamper.stamp(@pdf_bytes, @stamps)
+      else
+        stamp_per_page(stamper)
+      end
+    end
+
+    private
+
+    def all_stamps_target_all_pages?
+      @stamps.all? { |s| s[:pages] == :all }
+    end
+
+    def build_page_stamp_map(page_count)
+      per_page = Array.new(page_count) { [] }
+
+      @stamps.each do |stamp|
+        target_pages(stamp[:pages], page_count).each do |idx|
+          per_page[idx] << stamp
+        end
+      end
+
+      groups = {}
+      per_page.each_with_index do |stamps, idx|
+        next if stamps.empty?
+        groups[stamps] ||= []
+        groups[stamps] << idx
+      end
+
+      groups.map { |stamps, indices| [indices, stamps] }
+    end
+
+    def pdf_page_count
+      if defined?(CombinePDF)
+        CombinePDF.parse(@pdf_bytes).pages.length
+      elsif defined?(HexaPDF)
+        doc = HexaPDF::Document.new(io: StringIO.new(@pdf_bytes))
+        doc.pages.count
+      else
+        @pdf_bytes.scan(/\/Type\s*\/Page[^s]/).length
+      end
+    end
+
+    def stamp_per_page(stamper)
+      page_count = pdf_page_count
+      result = @pdf_bytes
+
+      build_page_stamp_map(page_count).each do |page_indices, stamps_for_pages|
+        result = stamper.stamp(result, stamps_for_pages, page_indices: page_indices)
+      end
+
+      result
+    end
+
+    def target_pages(pages_option, page_count)
+      case pages_option
+      when :all    then (0...page_count).to_a
+      when :first  then [0]
+      when :last   then [page_count - 1]
+      when :odd    then (0...page_count).select { |i| i.even? }
+      when :even   then (0...page_count).select { |i| i.odd? }
+      when Integer then [pages_option - 1]
+      when Array   then pages_option.map { |p| p - 1 }
+      when Range   then pages_option.map { |p| p - 1 }
+      else              (0...page_count).to_a
+      end
+    end
+  end
+end

data/lib/docpdf.rb

@@ -0,0 +1,116 @@
+require "docpdf/version"
+require "docpdf/configuration"
+require "docpdf/errors"
+require "docpdf/result"
+require "docpdf/input_normalizer"
+require "docpdf/mime_detector"
+require "docpdf/converter_resolver"
+require "docpdf/stamper_resolver"
+require "docpdf/converter"
+require "docpdf/watermarker"
+
+# Multi-format document-to-PDF converter with pluggable adapters and optional
+# watermarking. Supports Word, Excel, PowerPoint, OpenDocument, CSV, HTML, RTF,
+# plain text, images, and PDF passthrough.
+#
+#   result = DocPDF.convert("report.docx")
+#   result = DocPDF.convert(uploaded_file, filename: "report.pdf")
+#   result = DocPDF.convert("report.docx").watermark({ image: "logo.png", opacity: 0.1 })
+module DocPDF
+  class << self
+    # Returns the global Configuration instance.
+    #
+    #   DocPDF.configuration.soffice_path # => "soffice"
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Yields the global Configuration instance for modification.
+    #
+    # Options:
+    #   soffice_path      - Path to the LibreOffice binary (default: "soffice")
+    #   stamper           - Stamper adapter: :hexapdf, :combine_pdf, or nil for auto-detect (default: nil)
+    #   page_size         - Page size for text rendering: "LETTER", "A4", etc. (default: "LETTER")
+    #   text_options      - Hash of plain text conversion settings:
+    #                         font: "Courier", font_size: 10, margins: [50, 50, 50, 50], color: "333333"
+    #   watermark_options - Hash of text watermark defaults:
+    #                         font: "Helvetica", font_size: 72, color: "AAAAAA", rotation: 45
+    #
+    #   DocPDF.configure do |c|
+    #     c.soffice_path = "/usr/bin/soffice"
+    #     c.stamper = :hexapdf
+    #     c.page_size = "A4"
+    #     c.text_options = { font: "Helvetica", font_size: 12, margins: [72, 72, 72, 72], color: "000000" }
+    #     c.watermark_options = { font: "Times", font_size: 96, color: "FF0000", rotation: 30 }
+    #   end
+    def configure
+      yield(configuration)
+    end
+
+    # Converts a document to PDF. Accepts a file path, Pathname, IO object,
+    # Active Storage attachment, Dragonfly attachment, or raw binary data.
+    # Returns a Result with the PDF bytes and filename.
+    #
+    # Options:
+    #   io        - An IO object to read from (alternative to positional source)
+    #   data      - Raw binary string to convert (alternative to positional source)
+    #   filename  - Output filename override (default: derived from source)
+    #   mime_type - MIME type override (default: detected from filename extension)
+    #
+    #   result = DocPDF.convert("report.docx")
+    #   result = DocPDF.convert(upload)
+    #   result = DocPDF.convert(data: raw_bytes, mime_type: "image/png", filename: "photo.png")
+    #
+    #   result.data     # => PDF binary string
+    #   result.filename # => "report.pdf"
+    def convert(source = nil, **options)
+      Converter.call(source, **options)
+    end
+
+    # Resets configuration to defaults. Primarily used in tests.
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    # Applies watermark stamps to a PDF. Accepts the same source types as
+    # .convert, plus a Result object. Returns a Result.
+    #
+    # Each stamp is a Hash with either an :image or :text key:
+    #
+    # Image stamp keys:
+    #   image    - Path to the watermark image file
+    #   opacity  - Transparency level, 0.0 to 1.0 (default: 0.1)
+    #   position - Placement on the page (default: :center)
+    #              One of: :center, :top, :bottom, :left, :right, :top_left, :top_right, :bottom_left, :bottom_right
+    #   width    - Image width in points (default: 250)
+    #   height   - Image height in points (default: proportional to width)
+    #   offset_x - Horizontal offset in points (default: 0)
+    #   offset_y - Vertical offset in points (default: 0)
+    #   pages    - Which pages to stamp (default: :all)
+    #              One of: :all, :first, :last, :odd, :even, Integer, Array, or Range
+    #
+    # Text stamp keys:
+    #   text      - The text to render (e.g., "DRAFT", "CONFIDENTIAL")
+    #   opacity   - Transparency level, 0.0 to 1.0 (default: 0.1)
+    #   position  - Placement on the page (default: :center)
+    #   font      - Font name (default from watermark_options: "Helvetica")
+    #   font_size - Font size in points (default from watermark_options: 72)
+    #   color     - Hex color string (default from watermark_options: "AAAAAA")
+    #   rotation  - Rotation in degrees, counter-clockwise (default from watermark_options: 45)
+    #   offset_x  - Horizontal offset in points (default: 0)
+    #   offset_y  - Vertical offset in points (default: 0)
+    #   pages     - Which pages to stamp (default: :all)
+    #
+    # Text is auto-scaled to fit the page when the font size would cause overflow.
+    #
+    #   result = DocPDF.watermark("doc.pdf",
+    #     { image: "logo.png", opacity: 0.1, position: :top_right, width: 80 },
+    #     { text: "DRAFT", opacity: 0.1, position: :center, rotation: 45 })
+    #
+    # Chainable from a convert result:
+    #   DocPDF.convert("report.docx").watermark({ text: "DRAFT", opacity: 0.1 })
+    def watermark(source = nil, *stamps, **options)
+      Watermarker.call(source, *stamps, **options)
+    end
+  end
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: docpdf
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Velocity Labs, LLC
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Multi-format document-to-PDF converter with pluggable adapters and zero
+  hard dependencies. Supports Word, Excel, PowerPoint, OpenDocument, CSV, HTML, RTF,
+  plain text, images, and PDF passthrough. Optional watermarking with position grid,
+  offsets, and per-page targeting.
+email:
+- admin@velocitylabs.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/docpdf.rb
+- lib/docpdf/adapters/converters/base.rb
+- lib/docpdf/adapters/converters/fallback.rb
+- lib/docpdf/adapters/converters/hexapdf.rb
+- lib/docpdf/adapters/converters/mini_magick.rb
+- lib/docpdf/adapters/converters/passthrough.rb
+- lib/docpdf/adapters/converters/prawn.rb
+- lib/docpdf/adapters/converters/rmagick.rb
+- lib/docpdf/adapters/converters/soffice.rb
+- lib/docpdf/adapters/stampers/base.rb
+- lib/docpdf/adapters/stampers/combine_pdf.rb
+- lib/docpdf/adapters/stampers/hexapdf.rb
+- lib/docpdf/configuration.rb
+- lib/docpdf/converter.rb
+- lib/docpdf/converter_resolver.rb
+- lib/docpdf/errors.rb
+- lib/docpdf/input_normalizer.rb
+- lib/docpdf/mime_detector.rb
+- lib/docpdf/result.rb
+- lib/docpdf/stamper_resolver.rb
+- lib/docpdf/version.rb
+- lib/docpdf/watermarker.rb
+homepage: https://github.com/velocity-labs/docpdf
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/velocity-labs/docpdf
+  source_code_uri: https://github.com/velocity-labs/docpdf
+  changelog_uri: https://github.com/velocity-labs/docpdf/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Convert documents (Word, Excel, PowerPoint, images) to PDF with optional
+  watermarking
+test_files: []