swiss_qr 0.1.0

data/lib/swiss_qr/bill.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module SwissQr
+  # A parsed Swiss QR-bill payload. Immutable.
+  #
+  # [version, coding_type] "0200" and "1"
+  # [iban]                 IBAN or QR-IBAN, without spaces, upper case
+  # [qr_iban]              true when +iban+ is a QR-IBAN (also #qr_iban?)
+  # [creditor]             Address
+  # [ultimate_creditor]    Address or nil (reserved by SIX, must be empty)
+  # [amount]               BigDecimal, or nil when the payer fills in the amount
+  # [currency]             "CHF" or "EUR"
+  # [debtor]               Address or nil
+  # [reference_type]       :qrr, :scor or :non
+  # [reference]            QR or creditor reference as given, or nil
+  # [unstructured_message] free text or nil
+  # [trailer]              "EPD"
+  # [raw_billing_information] billing information as given (line 32) or nil
+  # [billing_information]     the billing information parsed (BillingInformation)
+  #                        when it uses the Swico S1 syntax, else nil
+  # [alternative_procedures] up to two strings (e.g. "eBill/B/...")
+  # [errors, warnings]     Arrays of Problem
+  # [raw]                  the payload as given
+  Bill = Data.define(
+    :version, :coding_type, :iban, :qr_iban, :creditor, :ultimate_creditor,
+    :amount, :currency, :debtor, :reference_type, :reference, :unstructured_message,
+    :trailer, :raw_billing_information, :billing_information, :alternative_procedures,
+    :errors, :warnings, :raw
+  ) do
+    def qr_iban? = qr_iban
+
+    # True when the payload satisfied every rule.
+    def valid? = errors.empty?
+
+    # True for a "DO NOT USE FOR PAYMENT" notification (amount 0.00).
+    def notification? = !amount.nil? && amount.zero?
+
+    # True when the payer has to fill in the amount.
+    def open_amount? = amount.nil?
+
+    def formatted_iban = iban && Iban.format(iban)
+
+    def formatted_reference = reference && Reference.format(reference, reference_type)
+
+    # Amount with two decimals ("1949.75"), or nil.
+    def formatted_amount = amount && Bill.amount_string(amount)
+
+    def self.amount_string(value)
+      units, decimals = value.round(2).to_s("F").split(".")
+      "#{units}.#{decimals.to_s.ljust(2, "0")}"
+    end
+
+    # Plain Ruby hash; nested value objects become hashes too.
+    def to_h(&)
+      hash = super().merge(
+        creditor: creditor&.to_h,
+        ultimate_creditor: ultimate_creditor&.to_h,
+        debtor: debtor&.to_h,
+        billing_information: billing_information&.to_h,
+        errors: errors.map(&:to_h),
+        warnings: warnings.map(&:to_h)
+      )
+      block_given? ? hash.to_h(&) : hash
+    end
+
+    # JSON-ready hash: only strings, numbers, booleans, nil, arrays and
+    # hashes (amount as "50.00", symbols and dates as strings).
+    def as_json(*)
+      to_h.transform_keys(&:to_s).merge(
+        "amount" => formatted_amount,
+        "creditor" => creditor&.as_json,
+        "ultimate_creditor" => ultimate_creditor&.as_json,
+        "debtor" => debtor&.as_json,
+        "reference_type" => reference_type&.to_s,
+        "billing_information" => billing_information&.as_json,
+        "errors" => errors.map(&:as_json),
+        "warnings" => warnings.map(&:as_json)
+      )
+    end
+
+    def to_json(*args)
+      require "json"
+      as_json.to_json(*args)
+    end
+  end
+end

data/lib/swiss_qr/billing_information.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "date"
+
+module SwissQr
+  # Structured billing information in the SIX/Swico "S1" syntax
+  # (QR-bill line 32, starting with "//S1/").
+  #
+  #   //S1/10/10201409/11/190512/20/1400.000-53/30/106017086/31/180508/32/7.7/40/2:10;0:30
+  #
+  # Tags: /10/ invoice number, /11/ invoice date, /20/ customer reference,
+  # /30/ VAT number (UID without "CHE"), /31/ VAT date or period, /32/ VAT
+  # rate(s), /33/ VAT on imports, /40/ payment conditions. A literal "/" in
+  # a value is written "\/", a literal "\" as "\\". Unknown tags are kept
+  # in +unknown_tags+. Problems never make the bill invalid (billing
+  # information has status A in the IG); they are collected in +warnings+.
+  BillingInformation = Data.define(
+    :raw, :invoice_number, :invoice_date, :customer_reference, :vat_number,
+    :vat_dates, :vat_details, :vat_import_taxes, :payment_conditions,
+    :unknown_tags, :warnings
+  ) do
+    def self.prefix = "//S1/"
+
+    # True when +text+ uses the S1 syntax.
+    def self.s1?(text) = text.is_a?(String) && text.start_with?(prefix)
+
+    # Parses an S1 billing-information string. Raises ArgumentError unless
+    # it starts with "//S1/".
+    def self.parse(text)
+      raise ArgumentError, "S1 billing information must start with #{prefix.inspect}" unless s1?(text)
+
+      self::S1Parser.new(text).parse
+    end
+
+    # Decimal for JSON: "7.7", "100", "12.5".
+    def self.decimal_string(value)
+      return nil if value.nil?
+
+      string = value.to_s("F")
+      string.end_with?(".0") ? string[0..-3] : string
+    end
+
+    def to_h(&)
+      hash = super().merge(
+        vat_details: vat_details&.map(&:to_h),
+        vat_import_taxes: vat_import_taxes&.map(&:to_h),
+        payment_conditions: payment_conditions&.map(&:to_h),
+        warnings: warnings.map(&:to_h)
+      )
+      block_given? ? hash.to_h(&) : hash
+    end
+
+    def as_json(*)
+      {
+        "raw" => raw,
+        "invoice_number" => invoice_number,
+        "invoice_date" => invoice_date&.iso8601,
+        "customer_reference" => customer_reference,
+        "vat_number" => vat_number,
+        "vat_dates" => vat_dates&.map(&:iso8601),
+        "vat_details" => vat_details&.map(&:as_json),
+        "vat_import_taxes" => vat_import_taxes&.map(&:as_json),
+        "payment_conditions" => payment_conditions&.map(&:as_json),
+        "unknown_tags" => unknown_tags,
+        "warnings" => warnings.map(&:as_json)
+      }
+    end
+  end
+
+  class BillingInformation
+    # One VAT rate in percent and the amount it applies to (/32/: net
+    # amount, or nil when one rate covers the whole bill; /33/: VAT amount).
+    VatRate = Data.define(:rate, :amount) do
+      def as_json(*)
+        { "rate" => BillingInformation.decimal_string(rate), "amount" => BillingInformation.decimal_string(amount) }
+      end
+    end
+
+    # Discount in percent when paid within +days+ days of the invoice date
+    # (+discount+ 0 = net payment term).
+    PaymentCondition = Data.define(:discount, :days) do
+      def as_json(*)
+        { "discount" => BillingInformation.decimal_string(discount), "days" => days }
+      end
+    end
+
+    # Tokenizer and value parser behind BillingInformation.parse.
+    # @api private
+    class S1Parser
+      FIELD = :billing_information
+      KNOWN_TAGS = %w[10 11 20 30 31 32 33 40].freeze
+      DECIMAL = /\A\d+(?:\.\d+)?\z/
+
+      def initialize(text)
+        @text = text
+        @warnings = []
+      end
+
+      def parse
+        values = collect_tags
+        BillingInformation.new(
+          raw: @text.dup.freeze,
+          invoice_number: values["10"],
+          invoice_date: values["11"] && parse_dates(values["11"], "/11/ invoice date", max: 1)&.first,
+          customer_reference: values["20"],
+          vat_number: values["30"] && parse_uid(values["30"]),
+          vat_dates: values["31"] && parse_dates(values["31"], "/31/ VAT date", max: 2),
+          vat_details: values["32"] && parse_vat_details(values["32"]),
+          vat_import_taxes: values["33"] && parse_pairs(values["33"], "/33/ VAT on imports"),
+          payment_conditions: values["40"] && parse_conditions(values["40"]),
+          unknown_tags: values.except(*KNOWN_TAGS).freeze,
+          warnings: @warnings.freeze
+        )
+      end
+
+      private
+
+      def warn(message)
+        @warnings << Problem.new(field: FIELD, message: message)
+        nil
+      end
+
+      # Splits on unescaped "/" and unescapes "\/" and "\\".
+      def tokens
+        result = [+""]
+        chars = @text[(BillingInformation.prefix.length - 1)..].each_char
+        loop do
+          char = chars.next
+          if char == "\\"
+            following = begin
+              chars.next
+            rescue StopIteration
+              ""
+            end
+            result.last << (%w[/ \\].include?(following) ? following : "\\#{following}")
+          elsif char == "/"
+            result << +""
+          else
+            result.last << char
+          end
+        end
+        result.drop(1)
+      end
+
+      def collect_tags
+        values = {}
+        previous = nil
+        tokens.each_slice(2) do |tag, value|
+          next if tag.empty? && value.nil?
+          next unless valid_tag?(tag, previous)
+
+          previous = tag
+          if values.key?(tag)
+            warn("tag /#{tag}/ appears more than once; the first value is used")
+          elsif !value.nil? && !value.empty?
+            values[tag] = value.freeze
+          end
+        end
+        values
+      end
+
+      def valid_tag?(tag, previous)
+        unless tag.match?(/\A\d{2}\z/)
+          warn("#{tag.inspect} is not a two-digit S1 tag")
+          return false
+        end
+        warn("tag /#{tag}/ is not one of #{KNOWN_TAGS.join(", ")}; kept in unknown_tags") unless KNOWN_TAGS.include?(tag)
+        warn("tag /#{tag}/ after /#{previous}/: S1 tags must be in ascending order") if previous && tag <= previous
+        true
+      end
+
+      def parse_dates(value, label, max:)
+        unless value.match?(/\A(?:\d{6}){1,#{max}}\z/)
+          return warn("#{label} must be #{max == 1 ? "YYMMDD" : "YYMMDD or YYMMDDYYMMDD"} (got #{value.inspect})")
+        end
+
+        dates = value.scan(/\d{6}/).map do |yymmdd|
+          Date.new(2000 + yymmdd[0, 2].to_i, yymmdd[2, 2].to_i, yymmdd[4, 2].to_i)
+        rescue Date::Error
+          return warn("#{label} #{yymmdd} is not a calendar date")
+        end
+        dates.freeze
+      end
+
+      def parse_uid(value)
+        warn("/30/ VAT number should be the 9 UID digits without CHE (got #{value.inspect})") unless value.match?(/\A\d{9}\z/)
+        value
+      end
+
+      # "/32/7.7" (one rate for the whole amount) or "8:1000;2.5:51.80".
+      def parse_vat_details(value)
+        return [BillingInformation::VatRate.new(rate: BigDecimal(value), amount: nil)].freeze if value.match?(DECIMAL)
+
+        parse_pairs(value, "/32/ VAT details")
+      end
+
+      def parse_pairs(value, label)
+        pairs = split_pairs(value, label)
+        pairs&.map do |rate, amount|
+          return warn("#{label}: #{rate}:#{amount} is not rate:amount") unless rate.match?(DECIMAL) && amount.match?(DECIMAL)
+
+          BillingInformation::VatRate.new(rate: BigDecimal(rate), amount: BigDecimal(amount))
+        end&.freeze
+      end
+
+      def parse_conditions(value)
+        pairs = split_pairs(value, "/40/ payment conditions")
+        pairs&.map do |discount, days|
+          unless discount.match?(DECIMAL) && days.match?(/\A\d+\z/)
+            return warn("/40/ payment conditions: #{discount}:#{days} is not discount:days")
+          end
+
+          BillingInformation::PaymentCondition.new(discount: BigDecimal(discount), days: days.to_i)
+        end&.freeze
+      end
+
+      def split_pairs(value, label)
+        pairs = value.split(";").map { |item| item.split(":", -1) }
+        return pairs unless pairs.empty? || pairs.any? { |pair| pair.size != 2 }
+
+        warn("#{label} must be a list of a:b pairs separated by \";\" (got #{value.inspect})")
+      end
+    end
+  end
+end

data/lib/swiss_qr/checksum.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module SwissQr
+  # Check-digit algorithms used by IBANs and payment references.
+  module Checksum
+    # Carry table of the modulo-10 recursive algorithm (IG QR-bill Annex B).
+    MOD10_TABLE = [0, 9, 4, 6, 8, 2, 7, 1, 3, 5].freeze
+
+    module_function
+
+    # Check digit (0-9) of a digit string, modulo 10 recursive.
+    def mod10_recursive(digits)
+      carry = digits.each_char.reduce(0) { |c, d| MOD10_TABLE[(c + d.to_i) % 10] }
+      (10 - carry) % 10
+    end
+
+    # ISO 7064 MOD 97-10 remainder as used by IBAN (ISO 13616) and the
+    # creditor reference (ISO 11649): the first four characters move to the
+    # end and letters become 10..35. The value is valid when the result is 1.
+    # +value+ must consist of A-Z and 0-9 only.
+    def mod97(value)
+      rearranged = value[4..] + value[0, 4]
+      rearranged.each_char.reduce(0) do |rem, char|
+        number = char.to_i(36)
+        ((rem * (number > 9 ? 100 : 10)) + number) % 97
+      end
+    end
+  end
+end

data/lib/swiss_qr/cli.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require_relative "../swiss_qr"
+
+module SwissQr
+  # The +swiss_qr+ command: reads QR-bills from images/PDFs (or a payload
+  # from standard input) and prints them as JSON. Not loaded by
+  # <tt>require "swiss_qr"</tt>.
+  #
+  # Exit status: 0 when every input held at least one QR-bill and all of
+  # them were valid, 1 when an input held no QR-bill or an invalid one, 2 on
+  # usage errors, unreadable files or a missing QR code reader.
+  class CLI
+    OK = 0
+    INVALID = 1
+    FAILURE = 2
+
+    def initialize(stdin: $stdin, stdout: $stdout, stderr: $stderr)
+      @stdin = stdin
+      @stdout = stdout
+      @stderr = stderr
+      @strict = true
+      @text = false
+      @lines = false
+      @status = OK
+    end
+
+    # Runs the command with the given arguments; returns the exit status.
+    def run(argv)
+      catch(:exit) do
+        files = parser.parse(argv)
+        next usage_error("--text reads the payload from standard input; give no files") if @text && files.any?
+        next usage_error("no input given") if !@text && files.empty?
+
+        print_json(@text ? read_text : files.flat_map { |file| read_file(file) })
+        @status
+      end
+    rescue OptionParser::ParseError => e
+      usage_error(e.message)
+    rescue ReaderUnavailable => e
+      @stderr.puts "swiss_qr: #{e.message}"
+      FAILURE
+    end
+
+    private
+
+    def parser
+      OptionParser.new do |opts|
+        opts.banner = <<~BANNER
+          Usage: swiss_qr [options] FILE...
+                 swiss_qr --text [options] < payload.txt
+
+          Prints the Swiss QR-bills found in images or PDFs (FILE "-" reads the
+          image from standard input) as a JSON array, one object per bill.
+        BANNER
+        opts.separator ""
+        opts.on("-t", "--text", "Parse a QR-bill payload (text) from standard input") { @text = true }
+        opts.on("--[no-]strict", "With --no-strict invalid bills are printed with their errors (exit status stays 1)") do |value|
+          @strict = value
+        end
+        opts.on("-l", "--lines", "Print one compact JSON object per line instead of an array") { @lines = true }
+        opts.on("-v", "--version", "Print the version") do
+          @stdout.puts "swiss_qr #{VERSION}"
+          throw :exit, OK
+        end
+        opts.on("-h", "--help", "Print this help") do
+          @stdout.puts opts
+          throw :exit, OK
+        end
+      end
+    end
+
+    def read_text
+      [parse("-", @stdin.binmode.read.force_encoding(Encoding::UTF_8))].compact
+    end
+
+    def read_file(file)
+      input = file == "-" ? @stdin.binmode : file
+      texts = Reader.adapt(SwissQr.reader).decode_all(input).select { |text| SwissQr.looks_like_qr_bill?(text) }
+      problem(INVALID, file, "no QR-bill found") if texts.empty?
+      texts.filter_map { |text| parse(file, text) }
+    rescue ReaderUnavailable
+      raise
+    rescue StandardError => e
+      problem(FAILURE, file, "#{e.message} (#{e.class})")
+      []
+    end
+
+    # The bill as a JSON-ready hash, or nil when it is not printed.
+    def parse(file, text)
+      bill = SwissQr.parse(text, strict: false)
+      unless bill.valid?
+        problem(INVALID, file, "invalid QR-bill: #{bill.errors.join("; ")}")
+        return if @strict
+      end
+      { "file" => file }.merge(bill.as_json)
+    rescue InvalidPayload => e
+      problem(INVALID, file, e.message)
+      nil
+    end
+
+    def print_json(bills)
+      if @lines
+        bills.each { |bill| @stdout.puts JSON.generate(bill) }
+      else
+        @stdout.puts JSON.pretty_generate(bills)
+      end
+    end
+
+    def problem(status, file, message)
+      @stderr.puts "swiss_qr: #{file}: #{message}"
+      @status = [@status, status].max
+    end
+
+    def usage_error(message)
+      @stderr.puts "swiss_qr: #{message}"
+      @stderr.puts parser.banner.lines.first(2).join
+      FAILURE
+    end
+  end
+end

data/lib/swiss_qr/countries.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module SwissQr
+  # Country codes for the address checks. Addresses carry a "two-digit
+  # country code according to ISO 3166-1" (IG 4.2.2, Ctry).
+  module Countries
+    # ISO 3166-1 alpha-2 (249 officially assigned codes, as in Debian's
+    # iso-codes 3166-1 list), plus XK (Kosovo): user-assigned, but used by
+    # SWIFT, the IBAN registry and the EU for Kosovo.
+    ISO_3166_1 = <<~CODES.split.to_h { |code| [code.freeze, true] }.freeze
+      AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ BA BB BD BE
+      BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY BZ CA CC CD
+      CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ DE DJ DK DM
+      DO DZ EC EE EG EH ER ES ET FI FJ FK FM FO FR GA GB GD GE GF
+      GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU
+      ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN
+      KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME
+      MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA
+      NC NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM
+      PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SG SH SI
+      SJ SK SL SM SN SO SR SS ST SV SX SY SZ TC TD TF TG TH TJ TK
+      TL TM TN TO TR TT TV TW TZ UA UG UM US UY UZ VA VC VE VG VI
+      VN VU WF WS YE YT ZA ZM ZW
+      XK
+    CODES
+
+    # International vehicle codes that are not ISO alpha-2 codes but appear
+    # as postal-code prefixes ("D-78462", "FL-9490", "A-6900").
+    VEHICLE_CODES = {
+      "A" => "AT", "B" => "BE", "D" => "DE", "E" => "ES", "F" => "FR", "H" => "HU", "I" => "IT",
+      "L" => "LU", "M" => "MT", "N" => "NO", "P" => "PT", "S" => "SE", "V" => "VA",
+      "FL" => "LI", "UK" => "GB", "AND" => "AD", "BIH" => "BA", "CDN" => "CA", "EST" => "EE",
+      "FIN" => "FI", "IRL" => "IE", "MNE" => "ME", "NMK" => "MK", "RKS" => "XK", "RSM" => "SM",
+      "RUS" => "RU", "SLO" => "SI", "SRB" => "RS", "USA" => "US"
+    }.freeze
+
+    # Countries whose official postal code format starts with the country
+    # code ("LV-1050", "LT-01100", "MD-2001").
+    PREFIXED_POSTAL_CODES = %w[LT LV MD].freeze
+
+    module_function
+
+    # True for an (upper-case) ISO 3166-1 alpha-2 code.
+    def iso?(code)
+      ISO_3166_1.key?(code)
+    end
+  end
+end

data/lib/swiss_qr/errors.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module SwissQr
+  # Base class of every error raised by this gem.
+  class Error < StandardError; end
+
+  # One violation of the QR-bill rules.
+  #
+  # +field+ is a Symbol naming the offending element, e.g. +:iban+,
+  # +:"creditor.name"+, +:reference+ or +:payload+ (for problems with the
+  # payload as a whole: size, line count, separators, encoding).
+  Problem = Data.define(:field, :message) do
+    def initialize(field:, message:)
+      super(field: field.to_sym, message: message.to_s.dup.freeze)
+    end
+
+    # True when this problem concerns +name+ or an element nested in it
+    # (+problem.about?(:creditor)+ matches +:"creditor.name"+).
+    def about?(name)
+      name = name.to_s
+      field.to_s == name || field.to_s.start_with?("#{name}.")
+    end
+
+    def to_s = "#{field}: #{message}"
+
+    def as_json(*) = { "field" => field.to_s, "message" => message }
+  end
+
+  # Raised when a payload is not a valid Swiss QR-bill.
+  #
+  # With <tt>strict: true</tt> it is raised for any rule violation; with
+  # <tt>strict: false</tt> only when the payload is not even structurally a
+  # QR-bill (wrong QR type, fewer than 31 lines). #bill holds the partially
+  # parsed bill when there is one.
+  class InvalidPayload < Error
+    attr_reader :errors, :bill
+
+    def initialize(errors, bill: nil)
+      @errors = Array(errors).freeze
+      @bill = bill
+      super(build_message)
+    end
+
+    private
+
+    def build_message
+      return "invalid QR-bill payload" if errors.empty?
+
+      shown = errors.first(3).map(&:to_s)
+      shown << "#{errors.size - 3} more" if errors.size > 3
+      "invalid QR-bill payload: #{shown.join("; ")}"
+    end
+  end
+
+  # Raised when no QR code reader is configured and the default one, the
+  # +qr_reader+ gem, cannot be loaded.
+  class ReaderUnavailable < Error; end
+end

data/lib/swiss_qr/iban.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module SwissQr
+  # IBAN helpers. A QR-bill account is a Swiss (CH) or Liechtenstein (LI)
+  # IBAN of exactly 21 characters; a QR-IBAN is one whose institution
+  # identification (positions 5-9) lies in 30000..31999.
+  module Iban
+    # Shape of any IBAN (country, check digits, 11-30 character BBAN).
+    PATTERN = /\A[A-Z]{2}\d{2}[A-Z0-9]{11,30}\z/
+    # Shape of a CH/LI IBAN: country, check digits, 5-digit IID, 12-character account.
+    QR_BILL_PATTERN = /\A(?:CH|LI)\d{2}\d{5}[A-Z0-9]{12}\z/
+    QR_IID_RANGE = (30_000..31_999)
+    COUNTRIES = %w[CH LI].freeze
+
+    module_function
+
+    # Removes all whitespace and upcases ASCII letters (only those: "ſ" must
+    # not turn into "S").
+    def normalize(iban)
+      iban.to_s.gsub(/[[:space:]]/, "").upcase(:ascii)
+    end
+
+    # True for any IBAN with a valid structure and MOD 97-10 check digits.
+    # Spaces and lower case are tolerated.
+    def valid?(iban)
+      value = normalize(iban)
+      value.match?(PATTERN) && Checksum.mod97(value) == 1
+    end
+
+    # True for a valid IBAN of the Swiss payment area (CH or LI), the only
+    # accounts a QR-bill may name (QR-IBAN or ordinary).
+    def ch_or_li?(iban)
+      value = normalize(iban)
+      value.match?(QR_BILL_PATTERN) && Checksum.mod97(value) == 1
+    end
+
+    # True for a valid CH/LI QR-IBAN (institution id 30000..31999).
+    def qr_iban?(iban)
+      ch_or_li?(iban) && qr_iid?(normalize(iban))
+    end
+
+    # True when a CH/LI-shaped IBAN carries a QR-IID; check digits are not
+    # verified.
+    def qr_iid?(iban)
+      value = normalize(iban)
+      value.match?(QR_BILL_PATTERN) && QR_IID_RANGE.cover?(value[4, 5].to_i)
+    end
+
+    # The institution identification (positions 5-9) of a CH/LI IBAN.
+    def iid(iban)
+      value = normalize(iban)
+      value[4, 5] if value.match?(QR_BILL_PATTERN)
+    end
+
+    # Groups of four for display: "CH44 3199 9123 0008 8901 2".
+    def format(iban)
+      normalize(iban).scan(/.{1,4}/).join(" ")
+    end
+  end
+end