prawn-swiss_qr_bill 0.4.2 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 427079ece5871b80503cf648e5f855d3ff1a0862e120fcf7ce9b125f641aaf0b
-  data.tar.gz: f0a5e3e4e28ce8ef24b4888e56d06bf48ed0c98a23890c5b642195a6a92a275f
+  metadata.gz: 38df96b8ac1e36c19b8e887a1704dc3af8494bec29fa2cbd99f4e7d536079b09
+  data.tar.gz: a996978e775f4a7cbbdefce2ebec4b2e6fc1ba12d3916da6b6ee9eed22b4a754
 SHA512:
-  metadata.gz: 7f1bf0ea06f6a9cf152763d0cf0f721efd403b066fd27bba3a4dde2635e72a2426708f799daa45f46eff49027435211f6b916ce08acba407786e186580b205a9
-  data.tar.gz: 7408f2208b8c129392ce77233c32666eb283a39cd86af927aa66c12e79cd093d06147c64de30bba81b1f6e5ebaad5abee88556fd29b6d4f548cfa01f81a62a45
+  metadata.gz: b5f1530805035de0d2a744f1ac3ed83520710dfc4de4bb3b0b01fcaf430f41fbe3fb86720c0f1dcb41cfbdfeedf9be6bdf9d28bf9bb7fe2a4c90ed32f982d48a
+  data.tar.gz: d2b5985d953531ad271585cdd6f7bc8f4a223a764254c5b558c87de7f9adb2035e64450410d9d100a7ed0056eb3ef676e9db22c3e7fad79ba968502b56b93828

data/README.md

@@ -30,7 +30,7 @@ Define the relevant information for the Swiss QR-bill and render it inside the P
 require 'prawn'
 require 'prawn/swiss_qr_bill'
 
-@qr_data = {
+@bill_data = {
   creditor: {
     iban: 'CH08 3080 8004 1110 4136 9',
     address: {
@@ -43,13 +43,15 @@ require 'prawn/swiss_qr_bill'
   amount: 9.90,
   currency: 'CHF',
   reference: '00 00000 00000 02202 20202 99991',
-  reference_type: 'QRR'
+  reference_type: 'QRR',
+  unstructured_message: 'Bill number 2202.20202.9999',
+  bill_information: '//S1/10/2202202029999/11/220819'
 }
 
 Prawn::Document.generate('output.pdf', page_size: 'A4') do
   text 'A Swiss QR bill'
 
-  swiss_qr_bill(@qr_data)
+  swiss_qr_bill(@bill_data)
 end
 ```
 
@@ -57,13 +59,13 @@ This will render the Swiss QR-bill at the bottom of the page:
 
 ![Swiss QR-bill Example, PDF](./images/sqb_example_01.png)
 
-### Options
+### Bill data structure
 
-The following options are available:
+The following data structure for the bill can be specified:
 
 ```ruby
 # *: mandatory
-@qr_data = {
+@bill_data = {
   creditor: {
     iban: '<iban>',                 # *
     address: {                      # *
@@ -96,9 +98,37 @@ The following options are available:
 
 If `debtor` or `amount` amount is not given, a box will be printed.
 
+### Options
+
+Calling `swiss_qr_bill()` method with options:
+
+```ruby
+# ...
+Prawn::Document.generate('output.pdf', page_size: 'A4') do
+  # ...
+
+  # raises InvalidIBANError when @bill_data[:creditor][:iban] is invalid
+  swiss_qr_bill(@bill_data, validate: true)
+end
+```
+
+Available options:
+
+| Option | Data type | Description | Default |
+| --- | --- | --- | --- |
+| `validate` | boolean | Validates IBAN and Reference Number and raises several errors | `false` |
+
+Errors which can be raised during validation:
+
+* `MissingIBANError`: When IBAN is missing.
+* `InvalidIBANError`: When IBAN is invalid. It checks for CH-IBAN only.
+* `InvalidReferenceError`: When reference is invalid. It checks for a valid QRR or SCOR reference
+
 ## Important
 
-This library does not validate (yet) IBAN, reference or the given QR data.
+This library can validate IBAN (switzerland only) and reference number (types QRR and SCOR).
+It does not however validate, if the given data is fully valid according to the implementation guidelines.
+
 Please refer to the implementation guidelines and the Swiss QR-bill validaton
 portal by SIX below.
 

data/lib/prawn/swiss_qr_bill/bill.rb

@@ -6,16 +6,17 @@ module Prawn
     class Bill
       FONT_DIR = File.expand_path("#{__dir__}/../../../assets/fonts")
 
-      def initialize(document, data)
+      def initialize(document, data, options = {})
         @doc = document
         @data = data
+        @options = options || {}
       end
 
       def draw
         set_font
 
         @doc.canvas do
-          Sections.draw_all(@doc, @data)
+          Sections.draw_all(@doc, @data, @options)
           CuttingLines.new(@doc).draw
         end
       end

data/lib/prawn/swiss_qr_bill/corner_box.rb

@@ -3,6 +3,8 @@
 module Prawn
   module SwissQRBill
     # Draws a box with corner ticks
+    #
+    # OPTIMIZE: rewrite @document to accessor, like the others
     class CornerBox
       TICK_SIZE = 3.mm
 

data/lib/prawn/swiss_qr_bill/extension.rb

@@ -4,8 +4,8 @@ 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
+      def swiss_qr_bill(data, options = {})
+        Prawn::SwissQRBill::Bill.new(self, data, options).draw
       end
 
       def swiss_qr_bill_sections

data/lib/prawn/swiss_qr_bill/qr/data.rb

@@ -3,21 +3,24 @@
 module Prawn
   module SwissQRBill
     module QR
+      class MissingIBANError < StandardError; end
+      class InvalidIBANError < StandardError; end
+      class InvalidReferenceError < StandardError; end
+
       # The data of the Swiss QR-bill
       #
       # References:
       # https://www.paymentstandards.ch/dam/downloads/ig-qr-bill-en.pdf
       # * Chapter 4, Page 25
-      #
-      # TODO: implement skippable (alt schemas, bill info. fields after trailer)
-      # TODO: check if addr-type has to be mentioned if not given?
-      # OPTIMIZE: implement non-changable?
       class Data
-        # Simple field structure:
+        # Field structure:
         # * :default => default value to be set, if key is not given
         # * :format  => Proc to call when generating output
         # * :skippable  => Do not output in QR data if not given
-        Field = Struct.new(:default, :format, :skippable)
+        # * :validation => Proc or symbol for validation
+        #   * if Proc given: will be called with value as argument
+        #   * if symbol given: method "#{:symbol}_validator" will be called with value as argument
+        Field = Struct.new(:default, :format, :skippable, :validation)
 
         # Available fields of the QR code data, ordered.
         FIELDS = {
@@ -26,9 +29,7 @@ module Prawn
           version: Field.new('0200'),
           # fixed: 1
           coding: Field.new('1'),
-          # TODO: check for valid iban
-          # iban: Field.new(nil, ->(value) { value.delete(' ') }),
-          iban: Field.new,
+          iban: Field.new(nil, nil, false, :iban),
           # enum: S, K
           creditor_address_type: Field.new('K'),
           creditor_address_name: Field.new,
@@ -59,22 +60,20 @@ module Prawn
           debtor_address_country: Field.new,
           # enum: QRR, SCOR, NON
           reference_type: Field.new('NON'),
-          reference: Field.new(nil, ->(value) { value && value.delete(' ') }),
+          reference: Field.new(nil, ->(v) { v && v.delete(' ') }, false, :reference),
           unstructured_message: Field.new,
           # fixed: EPD
           trailer: Field.new('EPD'),
-
-          # additional:
-
           bill_information: Field.new(nil, nil, true),
           # key-value pairs:
           alternative_parameters: Field.new(nil, nil, true)
         }.freeze
 
-        # TODO: check if all fields can be changed by user?
         attr_accessor(*FIELDS.keys)
 
-        def initialize(fields = {})
+        def initialize(fields = {}, options = {})
+          @options = options || {}
+
           # set defaults
           FIELDS.each_key do |field|
             instance_variable_set("@#{field}", FIELDS[field].default)
@@ -87,18 +86,79 @@ module Prawn
         end
 
         def generate
+          validate if @options[:validate]
+
           stack = []
-          FIELDS.keys.map do |k|
+          FIELDS.each_key do |k|
             var = instance_variable_get("@#{k}")
 
+            # TODO: fix possible wrong format if alt parameters (last one) is given
             next if FIELDS[k][:skippable] && var.nil?
 
+            # TODO: use #process; generate method should only call validate, then process, then render as string
             var = FIELDS[k][:format].call(var) if FIELDS[k][:format].is_a?(Proc)
 
             stack << var
           end
           stack.join("\r\n")
         end
+
+        def process
+          FIELDS.each_key do |k|
+            var = instance_variable_get("@#{k}")
+
+            instance_variable_set("@#{k}", FIELDS[k][:format].call(var)) if FIELDS[k][:format].is_a?(Proc)
+          end
+        end
+
+        def validate
+          FIELDS.each_key do |k|
+            next unless FIELDS[k][:validation]
+
+            var = instance_variable_get("@#{k}")
+
+            call_validator(FIELDS[k][:validation], var)
+          end
+
+          true
+        end
+
+        private
+
+        def call_validator(validator, value)
+          case validator
+          when Proc
+            # NOTE: currently not in use
+            # :nocov:
+            validator.call(value)
+            # :nocov:
+          when Symbol
+            send("#{validator}_validator", value)
+          end
+        end
+
+        def iban_validator(value)
+          # IBAN must be given
+          raise MissingIBANError, 'IBAN is missing' if value.nil? || value.empty?
+
+          # IBAN must be valid
+          iban = IBAN.new(value)
+          raise InvalidIBANError, "IBAN #{iban.prettify} is invalid" unless iban.valid?
+
+          true
+        end
+
+        def reference_validator(value)
+          reference = Reference.new(value, reference_type)
+
+          unless %w[QRR SCOR].include?(reference_type)
+            raise InvalidReferenceError, "Reference Type #{reference_type} invalid. Allowed: QRR, SCOR"
+          end
+
+          raise InvalidReferenceError, "Reference #{value} is invalid" unless reference.valid?
+
+          true
+        end
       end
     end
   end

data/lib/prawn/swiss_qr_bill/reference.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Prawn
+  module SwissQRBill
+    # Check validity of reference number
+    #
+    # QRR reference:
+    # Refer to the implementation guides of SIX: https://www.paymentstandards.ch/dam/downloads/ig-qr-bill-en.pdf
+    class Reference
+      MODULO_TABLE = [
+        [0, 9, 4, 6, 8, 2, 7, 1, 3, 5],
+        [9, 4, 6, 8, 2, 7, 1, 3, 5, 0],
+        [4, 6, 8, 2, 7, 1, 3, 5, 0, 9],
+        [6, 8, 2, 7, 1, 3, 5, 0, 9, 4],
+        [8, 2, 7, 1, 3, 5, 0, 9, 4, 6],
+        [2, 7, 1, 3, 5, 0, 9, 4, 6, 8],
+        [7, 1, 3, 5, 0, 9, 4, 6, 8, 2],
+        [1, 3, 5, 0, 9, 4, 6, 8, 2, 7],
+        [3, 5, 0, 9, 4, 6, 8, 2, 7, 1],
+        [5, 0, 9, 4, 6, 8, 2, 7, 1, 3]
+      ].freeze
+
+      def initialize(reference, type = 'QRR')
+        @type = type
+        @reference = standardize(reference)
+      end
+
+      # Number without check digit
+      def number
+        case @type
+        when 'QRR'
+          @reference[0...-1]
+        when 'SCOR'
+          @reference[4..-1]
+        end
+      end
+
+      # QRR: Last number, the check digit
+      # SCOR: 2 numbers after RF
+      def check_digits
+        case @type
+        when 'QRR'
+          @reference[-1].to_i
+        when 'SCOR'
+          @reference[2..3]
+        end
+      end
+
+      def valid?
+        valid_check_digits? && valid_length?
+      end
+
+      def valid_check_digits?
+        case @type
+        when 'QRR'
+          check_digits == Reference.modulo10_recursive(number)
+        when 'SCOR'
+          scor_to_i % 97 == 1
+        end
+      end
+
+      # NOTE: for SCOR only
+      def scor_to_i
+        "#{number}RF#{check_digits}".gsub(/[A-Z]/) { |c| c.ord - 55 }.to_i
+      end
+
+      # According to the payment standards (PDF, Annex B):
+      # The QR reference consists of 27 positions and is numerical.
+      def valid_length?
+        case @type
+        when 'QRR'
+          @reference.length <= 27
+        when 'SCOR'
+          @reference.length <= 25
+        end
+      end
+
+      # Generate a check digit with modulo 10 recursive:
+      #
+      # Can be used as an instance method:
+      #
+      #   Prawn::SwissQRBill::Reference.modulo10_recursive("2202202029999")
+      #   # will return 1
+      def self.modulo10_recursive(reference)
+        numbers = reference.to_s.chars.map(&:to_i)
+        report = numbers.inject(0) { |memo, c| MODULO_TABLE[memo][c] }
+
+        (10 - report) % 10
+      end
+
+      private
+
+      def standardize(reference)
+        reference.to_s.strip.gsub(/\s+/, '').upcase
+      end
+    end
+  end
+end

data/lib/prawn/swiss_qr_bill/sections/payment_information.rb

@@ -13,7 +13,7 @@ module Prawn
           box do
             draw_payable_to
             draw_reference if @data.key?(:reference)
-            draw_additional_information if @data.key?(:additional_information)
+            draw_additional_information if @data.key?(:unstructured_message) || @data.key?(:bill_information)
             draw_payable_by
           end
         end
@@ -37,7 +37,7 @@ module Prawn
 
         def draw_additional_information
           label I18n.t('additional_info', scope: i18n_scope)
-          content @data[:additional_information]
+          content [@data[:unstructured_message], @data[:bill_information]].join(' ')
 
           line_spacing
         end

data/lib/prawn/swiss_qr_bill/sections/qr_code.rb

@@ -11,8 +11,6 @@ module Prawn
       #
       # swiss_cross.png =>   166px ~>  7.mm
       # QR-code:            1090px <~ 46.mm
-      #
-      # TODO: iban check -> raise exception if configured
       class QRCode < Section
         KEY = 'payment.qr_code'
 
@@ -26,6 +24,7 @@ module Prawn
           creditor_address_line1: %i[creditor address line1],
           creditor_address_line2: %i[creditor address line2],
           creditor_address_postal_code: %i[creditor address postal_code],
+          creditor_address_city: %i[creditor address city],
           creditor_address_country: %i[creditor address country],
           debtor_address_type: %i[debtor address type],
           debtor_address_name: %i[debtor address name],
@@ -37,7 +36,9 @@ module Prawn
           amount: [:amount],
           currency: [:currency],
           reference: [:reference],
-          reference_type: [:reference_type]
+          reference_type: [:reference_type],
+          unstructured_message: [:unstructured_message],
+          bill_information: [:bill_information]
         }.freeze
 
         def draw
@@ -71,16 +72,17 @@ module Prawn
         end
 
         def generate_qr_data(data)
-          options = {}
+          flat_data = {}
           MAPPING.each_key do |key|
-            # check if the exists
+            # check if the key exists
             next unless deep_key?(data, MAPPING[key])
 
-            options[key] = data.dig(*MAPPING[key])
+            flat_data[key] = data.dig(*MAPPING[key])
           end
 
           iban = IBAN.new(data[:creditor][:iban])
-          qr_data = QR::Data.new(options.merge(iban: iban.code))
+
+          qr_data = QR::Data.new(flat_data.merge(iban: iban.code), validate: @options[:validate])
           qr_data.generate
         end
 

data/lib/prawn/swiss_qr_bill/sections/section.rb

@@ -19,13 +19,14 @@ module Prawn
         # specifications for subclass' section, @see Specification for details
         attr_accessor :specs
 
-        def initialize(document, data)
+        def initialize(document, data, options = {})
           unless self.class.const_defined?(:KEY)
             raise NotImplementedError, "constant KEY not defined in class #{self.class}"
           end
 
           @doc = document
           @data = data
+          @options = options || {}
 
           load_specs
         end

data/lib/prawn/swiss_qr_bill/sections.rb

@@ -19,9 +19,9 @@ module Prawn
       ].freeze
 
       # Draw all sections in the right order.
-      def self.draw_all(document, data)
+      def self.draw_all(document, data, options = {})
         SECTION_CLASSES.each do |klass|
-          klass.new(document, data).draw
+          klass.new(document, data, options).draw
         end
       end
     end

data/lib/prawn/swiss_qr_bill/specifications.rb

@@ -26,6 +26,7 @@ module Prawn
       }.freeze
 
       def initialize
+        # OPTIMIZE: unnessecary assignement
         @specs = load_specs
       end
 

data/lib/prawn/swiss_qr_bill/version.rb

@@ -2,6 +2,6 @@
 
 module Prawn
   module SwissQRBill
-    VERSION = '0.4.2'
+    VERSION = '0.5.2'
   end
 end

data/lib/prawn/swiss_qr_bill.rb

@@ -17,6 +17,7 @@ require 'prawn/swiss_qr_bill/helpers/box_helper'
 
 require 'prawn/swiss_qr_bill/qr/data'
 require 'prawn/swiss_qr_bill/iban'
+require 'prawn/swiss_qr_bill/reference'
 require 'prawn/swiss_qr_bill/padded_box'
 require 'prawn/swiss_qr_bill/corner_box'
 require 'prawn/swiss_qr_bill/cutting_lines'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: prawn-swiss_qr_bill
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.5.2
 platform: ruby
 authors:
 - Mischa Schindowski
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-02-22 00:00:00.000000000 Z
+date: 2022-08-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: i18n
@@ -179,6 +179,7 @@ files:
 - lib/prawn/swiss_qr_bill/iban.rb
 - lib/prawn/swiss_qr_bill/padded_box.rb
 - lib/prawn/swiss_qr_bill/qr/data.rb
+- lib/prawn/swiss_qr_bill/reference.rb
 - lib/prawn/swiss_qr_bill/sections.rb
 - lib/prawn/swiss_qr_bill/sections/payment_amount.rb
 - lib/prawn/swiss_qr_bill/sections/payment_further_information.rb
@@ -214,7 +215,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3.1
+rubygems_version: 3.2.32
 signing_key: 
 specification_version: 4
 summary: Swiss QR-Bill PDFs in Ruby with Prawn