prawn-swiss_qr_bill 0.4.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: faa2f8fb8c38ea2681890f7573bb42ab424cadb413d57699e0e64145088c8911
+  data.tar.gz: 2fa0db096bc0d9fb4060858dd0fe88ba187c20a54ae36babcb66848c6a102a33
+SHA512:
+  metadata.gz: e1d30550f53e1ed3dc74a0256d826a25fa2290f06a9b4e282e8529dabeaf334907b87613e6babd52667ee3cf248098464dd9381743e4883014a7a85c8783c97d
+  data.tar.gz: 536068e41ad5d54e70dcebe9deeeb19a1984eb52b4bee5e020e5644bbdcf4e7c66453b449ae3e811b523f37dc2b3fc1a2dcaacd51c072562a1628b0b3ef509ea

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'http://rubygems.org'
+
+gemspec

data/README.md

@@ -0,0 +1,124 @@
+# Prawn::SwissQRBill
+
+A Ruby library for creating Swiss QR-bill payment slips inside a PDF. It is
+built as a [Prawn](https://github.com/prawnpdf/prawn) extension.
+
+## Installation
+
+Add the following line to your `Gemfile`:
+
+```ruby
+gem 'prawn-swiss_qr_bill'
+```
+
+or install it manually:
+
+```bash
+gem install prawn-swiss_qr_bill
+```
+
+## Basic Usage
+
+Define the relevant information for the Swiss QR-bill and render it inside the Prawn block:
+
+```ruby
+require 'prawn'
+require 'prawn/swiss_qr_bill'
+
+@qr_data = {
+  creditor: {
+    iban: 'CH08 3080 8004 1110 4136 9',
+    address: {
+      name: 'Mischa Schindowski',
+      line1: 'Schybenächerweg 553',
+      line2: '5324 Full-Reuenthal',
+      country: 'CH'
+    }
+  },
+  amount: 9.90,
+  currency: 'CHF',
+  reference: '00 00000 00000 02202 20202 99991',
+  reference_type: 'QRR'
+}
+
+Prawn::Document.generate('output.pdf', page_size: 'A4') do
+  text 'A Swiss QR bill'
+
+  swiss_qr_bill(@qr_data)
+end
+```
+
+This will render the Swiss QR-bill at the bottom of the page:
+
+![Swiss QR-bill Example, PDF](./images/sqb_example_01.png)
+
+### Options
+
+The following options are available:
+
+```ruby
+# *: mandatory
+@qr_data = {
+  creditor: {
+    iban: '<iban>',                 # *
+    address: {                      # *
+      type: '<K|S>',                # default: K
+      name: '<name>',               # *
+      line1: '<street> <nr>',       # *
+      line2: '<line 2>',
+      postal_code: '<postal code>',
+      city: '<city>',
+      country: '<country>'          # *
+    }
+  },
+  debtor: {
+    address: {
+      type: '<K|S>',                # default: nil
+      name: '<name>',
+      line1: '<street> <nr>',
+      line2: '<line 2>',
+      postal_code: '<postal_code>',
+      city: '<city>',
+      country: '<country>'
+    }
+  },
+  amount: 9.90,
+  currency: '<CHF|EUR>',            # *
+  reference: '<ref nr>',
+  reference_type: '<QRR|SCOR|NON>'  # default: NON
+}
+```
+
+If `debtor` or `amount` amount is not given, a box will be printed.
+
+## Important
+
+This library does not validate (yet) IBAN, reference or the given QR data.
+Please refer to the implementation guidelines and the Swiss QR-bill validaton
+portal by SIX below.
+
+## Contributing
+
+If you miss a feature or you've found a bug, please [open a GitHub issue](https://github.com/mitosch/prawn-swiss_qr_bill/issues).
+
+Pull requests are highly welcome:
+
+* Fork the project
+* Make your changes
+* Send the pull request
+
+## Authors
+
+Original author: Mischa Schindowski
+
+## Resources
+
+* [Prawn](https://github.com/prawnpdf/prawn): Fast, Nimble PDF Generation For Ruby
+* [Swiss QR-bill Validation Portal](https://validation.iso-payments.ch/qrrechnung)
+* [Swiss Payment Standards](https://www.paymentstandards.ch):
+  * [Style Guide QR-bill](https://www.paymentstandards.ch/dam/downloads/style-guide-en.pdf)
+  * [Implementation Guidelines QR-bill](https://www.paymentstandards.ch/dam/downloads/ig-qr-bill-en.pdf)
+
+## Copyright
+
+MIT License (http://www.opensource.org/licenses/mit-license.html)

data/config/locales/de.yml

@@ -0,0 +1,15 @@
+de:
+  swiss_qr_bill:
+    payment: Zahlteil
+    creditor: Konto / Zahlbar an
+    reference: Referenz
+    additional_info: Zusätzliche Informationen
+    further_info: Weitere Informationen
+    currency: Währung
+    amount: Betrag
+    receipt: Empfangsschein
+    acceptance: Annahmestelle
+    separate: Vor der Einzahlung abzutrennen
+    debtor: Zahlbar durch
+    debtor_blank: Zahlbar durch (Name/Adresse)
+    debtor_favour: Zugunsten

data/config/locales/en.yml

@@ -0,0 +1,15 @@
+en:
+  swiss_qr_bill:
+    payment: Payment part
+    creditor: Account / Payable to
+    reference: Reference
+    additional_info: Additional information
+    further_info: Further information
+    currency: Currency
+    amount: Amount
+    receipt: Receipt
+    acceptance: Acceptance point
+    separate: Separate before paying in
+    debtor: Payable by
+    debtor_blank: Payable by (name/address)
+    debtor_favour: In favour of

data/config/locales/fr.yml

@@ -0,0 +1,15 @@
+fr:
+  swiss_qr_bill:
+    payment: Section paiement
+    creditor: Compte / Payable à
+    reference: Référence
+    additional_info: Informations supplémentaires
+    further_info: Informations additionnelles
+    currency: Monnaie
+    amount: Montant
+    receipt: Récépissé
+    acceptance: Point de dépôt
+    separate: A détacher avant le versement
+    debtor: Payable par
+    debtor_blank: Payable par (nom/adresse)
+    debtor_favour: En faveur de

data/config/locales/it.yml

@@ -0,0 +1,15 @@
+it:
+  swiss_qr_bill:
+    payment: Sezione pagamento
+    creditor: Conto / Pagabile a
+    reference: Riferimento
+    additional_info: Informazioni supplementari
+    further_info: Informazioni aggiuntive
+    currency: Valuta
+    amount: Importo
+    receipt: Ricevuta
+    acceptance: Punto di accettazione
+    separate: Da staccare prima del versamento
+    debtor: Pagabile da
+    debtor_blank: Pagabile da (nome/indirizzo)
+    debtor_favour: A favore di

data/lib/prawn/swiss_qr_bill/bill.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Prawn
+  module SwissQRBill
+    # Bill renders the Swiss QR-bill at the bottom of a page
+    class Bill
+      def initialize(document, data)
+        @doc = document
+        @data = data
+      end
+
+      def draw
+        @doc.canvas do
+          Sections.draw_all(@doc, @data)
+          CuttingLines.new(@doc).draw
+        end
+      end
+    end
+  end
+end

data/lib/prawn/swiss_qr_bill/corner_box.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Prawn
+  module SwissQRBill
+    # Draws a box with corner ticks
+    class CornerBox
+      TICK_SIZE = 3.mm
+
+      LINE_WIDTH = 0.75
+
+      def initialize(document, point, options)
+        unless options.key?(:width) && options.key?(:height)
+          raise ArgumentError,
+                'corner_box needs the :width and :height option to be set'
+        end
+
+        @document = document
+        @point = point
+        @width = options[:width]
+        @height = options[:height]
+
+        @brain = {}
+      end
+
+      def draw
+        set_styles
+        draw_lines
+        reset_styles
+      end
+
+      private
+
+      def set_styles
+        @brain[:line_width] = @document.line_width
+        @document.line_width = LINE_WIDTH
+      end
+
+      def reset_styles
+        @document.line_width = @brain[:line_width]
+      end
+
+      def draw_lines
+        point_x, point_y = @point
+
+        @document.stroke do
+          draw_horizontal_lines(point_x, point_y)
+          draw_vertical_lines(point_x, point_y)
+        end
+      end
+
+      def draw_horizontal_lines(point_x, point_y)
+        # upper lines
+        @document.horizontal_line point_x, point_x + TICK_SIZE,
+                                  at: point_y
+        @document.horizontal_line point_x + @width, point_x + @width - TICK_SIZE,
+                                  at: point_y
+        # lower lines
+        @document.horizontal_line point_x, point_x + TICK_SIZE,
+                                  at: point_y - @height
+        @document.horizontal_line point_x + @width, point_x + @width - TICK_SIZE,
+                                  at: point_y - @height
+      end
+
+      def draw_vertical_lines(point_x, point_y)
+        # upper lines
+        @document.vertical_line point_y, point_y - TICK_SIZE,
+                                at: point_x
+        @document.vertical_line point_y, point_y - TICK_SIZE,
+                                at: point_x + @width
+
+        # lower lines
+        @document.vertical_line point_y - @height, point_y - @height + TICK_SIZE,
+                                at: point_x
+        @document.vertical_line point_y - @height, point_y - @height + TICK_SIZE,
+                                at: point_x + @width
+      end
+    end
+  end
+end

data/lib/prawn/swiss_qr_bill/cutting_lines.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Prawn
+  module SwissQRBill
+    # Horizontal and vertical cutting lines with a scissor symbol
+    class CuttingLines
+      SCISSOR_FILE = File.expand_path("#{__dir__}/images/scissor.png")
+
+      SCISSOR_WIDTH = 5.mm
+      SCISSOR_HEIGHT = 3.mm
+
+      PAD_LEFT = 5.mm
+      PAD_TOP = 1.mm
+
+      attr_reader :doc, :receipt_width, :receipt_height
+
+      def initialize(document)
+        @doc = document
+
+        @brain = {}
+
+        load_specs
+      end
+
+      def draw
+        set_styles
+
+        draw_strokes
+        draw_scissors
+
+        reset_styles
+      end
+
+      private
+
+      def load_specs
+        specs = Specifications.new
+        @receipt_height = specs.get('receipt.height').mm
+        @receipt_width = specs.get('receipt.width').mm
+      end
+
+      def set_styles
+        @brain[:line_width] = doc.line_width
+
+        doc.line_width 0.5
+        doc.dash 2, space: 2
+      end
+
+      def draw_strokes
+        doc.stroke { doc.line [0, receipt_height], [doc.bounds.right, receipt_height] }
+        doc.stroke { doc.line [receipt_width, receipt_height], [receipt_width, doc.bounds.bottom] }
+      end
+
+      def draw_scissors
+        doc.bounding_box([doc.bounds.left + PAD_LEFT, receipt_height + (SCISSOR_HEIGHT / 2)],
+                         width: SCISSOR_WIDTH, height: SCISSOR_HEIGHT) do
+          doc.image SCISSOR_FILE, width: SCISSOR_WIDTH
+        end
+
+        doc.bounding_box([receipt_width - (SCISSOR_HEIGHT / 2), receipt_height - PAD_TOP],
+                         width: SCISSOR_WIDTH, height: SCISSOR_HEIGHT) do
+          doc.rotate(270, origin: [0, 0]) do
+            doc.image SCISSOR_FILE, width: SCISSOR_WIDTH
+          end
+        end
+      end
+
+      def reset_styles
+        doc.line_width = @brain[:line_width]
+        doc.undash
+      end
+    end
+  end
+end

data/lib/prawn/swiss_qr_bill/debug_section.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Prawn
+  module SwissQRBill
+    # Draws a blue debug section.
+    #
+    # Reference:
+    # https://www.paymentstandards.ch/dam/downloads/style-guide-en.pdf
+    #
+    # OPTIMIZE: move several general styling functions to helpers (bb-helper)
+    class DebugSection
+      SECTIONS = [
+        'receipt',
+        'receipt.title',
+        'receipt.information',
+        'receipt.amount',
+        'receipt.acceptance',
+        'payment',
+        'payment.title',
+        'payment.information',
+        'payment.qr_code',
+        'payment.qr_cross',
+        'payment.amount',
+        'payment.further_information'
+      ].freeze
+
+      attr_reader :doc, :properties
+
+      def initialize(document)
+        @doc = document
+
+        @brain = { font: {}, border: { color: nil, width: nil } }
+
+        @spec = Prawn::SwissQRBill::Specifications.new
+      end
+
+      def draw
+        SECTIONS.each do |section|
+          name = @spec.get(section)['name']
+          specs = @spec.get_specs(section)
+          point = specs.point
+          options = { width: specs.width, height: specs.height }.merge(
+            text: name,
+            background: false, border: true, font_size: 10
+          )
+
+          draw_debug_box(point, options)
+        end
+      end
+
+      private
+
+      # Draws a box like in the style guide.
+      #
+      # NOTE: Background removed for simplicity, color was: D4EDFC
+      def draw_debug_box(*args)
+        position = args[0]
+        text = args[1].delete(:text)
+        border_style = { color: '71C4E9', width: 0.75 } if args[1][:border]
+        debug_box_opts = args[1].merge(padding: 1.mm,
+                                       border: border_style,
+                                       font: { size: args[1][:font_size] })
+
+        draw_padded_box(position, debug_box_opts) do
+          doc.text text, color: '71C4E9'
+        end
+      end
+
+      def draw_padded_box(*args, &block)
+        padding = args[1].delete(:padding) || 0
+
+        doc.bounding_box(*args) do
+          height = doc.bounds.height
+          width = doc.bounds.width
+
+          ensure_styles(args[1])
+
+          doc.bounding_box([padding, height - padding],
+                           width: width - (2 * padding),
+                           height: height - (2 * padding)) { yield block }
+        end
+
+        reset_styles
+      end
+
+      # ensures setting the styles by meaningful options:
+      #
+      # {
+      #   border: { color: '123456', width: 2 },
+      #   font: { size: 10 }
+      # }
+      def ensure_styles(opts)
+        stroke_style(opts[:border])
+        font_style(opts[:font])
+      end
+
+      def stroke_style(opts)
+        return unless opts
+
+        remember_style(:border)
+
+        doc.line_width opts[:width]
+        doc.stroke_color opts[:color]
+        doc.stroke_bounds
+      end
+
+      def font_style(opts)
+        return unless opts
+
+        remember_style(:font)
+        doc.font_size opts[:size]
+      end
+
+      def remember_style(style_type)
+        case style_type
+        when :font
+          @brain[:font][:size] = doc.font_size
+        when :border
+          @brain[:border][:color] = doc.line_width
+          @brain[:border][:width] = doc.stroke_color
+        end
+      end
+
+      def reset_styles
+        reset_style(:font)
+        reset_style(:border)
+      end
+
+      def reset_style(style_type)
+        case style_type
+        when :font
+          doc.font_size @brain[:font][:size]
+        when :border
+          doc.line_width @brain[:border][:color]
+          doc.stroke_color @brain[:border][:width]
+        end
+      end
+    end
+  end
+end

data/lib/prawn/swiss_qr_bill/extension.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Prawn
+  module SwissQRBill
+    # Extend prawn with *swiss_qr_bill* methods
+    module Extension
+      def swiss_qr_bill(data)
+        Prawn::SwissQRBill::Bill.new(self, data).draw
+      end
+
+      def swiss_qr_bill_sections
+        canvas do
+          Prawn::SwissQRBill::DebugSection.new(self).draw
+        end
+      end
+    end
+  end
+end

data/lib/prawn/swiss_qr_bill/helpers/box_helper.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Prawn
+  module SwissQRBill
+    module Helpers
+      # Helpers for drawing boxes
+      module BoxHelper
+        def corner_box(doc, point, options)
+          Prawn::SwissQRBill::CornerBox.new(doc, point, options).draw
+        end
+      end
+    end
+  end
+end

data/lib/prawn/swiss_qr_bill/helpers/number_helper.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Prawn
+  module SwissQRBill
+    module Helpers
+      # Helpers to format numbers
+      module NumberHelper
+        def format_with_delimiter(number)
+          left, right = format('%.2f', number).split('.')
+          left.gsub!(/(\d)(?=(\d\d\d)+(?!\d))/) { |d| "#{d} " }
+          [left, right].compact.join('.')
+        end
+      end
+    end
+  end
+end

data/lib/prawn/swiss_qr_bill/iban.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Prawn
+  module SwissQRBill
+    # Check validity of IBAN.
+    #
+    # NOTE: *For Switzerland only*
+    #
+    # Simple implementation according to
+    # https://en.wikipedia.org/wiki/International_Bank_Account_Number#Algorithms
+    #
+    # TODO: validate QR-iban
+    class IBAN
+      attr_reader :code
+
+      def initialize(code)
+        @code = standardize(code)
+      end
+
+      def country_code
+        @code[0..1]
+      end
+
+      def check_digits
+        @code[2..3]
+      end
+
+      def bban
+        @code[4..-1]
+      end
+
+      # Convert Alpha-Numeric IBAN to numeric values (incl. rearrangement)
+      #
+      # Reference:
+      # https://en.wikipedia.org/wiki/International_Bank_Account_Number#Validating_the_IBAN
+      def to_i
+        "#{bban}#{country_code}#{check_digits}".gsub(/[A-Z]/) { |c| c.ord - 55 }.to_i
+      end
+
+      def prettify
+        @code.gsub(/(.{4})/, '\1 ').strip
+      end
+
+      # valid IBAN:
+      # CH77 8080 8004 1110 4136 9
+      #
+      # valid QR-IBAN:
+      # CH08 3080 8004 1110 4136 9
+      def valid?
+        valid_check_digits? && valid_swiss_length? && valid_country?
+      end
+
+      def valid_check_digits?
+        to_i % 97 == 1
+      end
+
+      # NOTE: Only the length for Switzerland is implemented because it is Swiss QR-bill specific
+      def valid_length?
+        valid_swiss_length?
+      end
+
+      def valid_swiss_length?
+        @code.length == 21
+      end
+
+      def valid_country?
+        country_code == 'CH'
+      end
+
+      private
+
+      # Make the given string standard:
+      #
+      # CH21 2345 2123 5543 5554
+      # ch21 2345 2123 5543 5554
+      # " ch21 2345  2123 5543  5554 "
+      #
+      # => CH212345212355435554
+      def standardize(code)
+        code.to_s.strip.gsub(/\s+/, '').upcase
+      end
+    end
+  end
+end