swiss_qr 0.1.0

data/lib/swiss_qr/validation.rb

@@ -0,0 +1,380 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module SwissQr
+  # Field rules of the SIX "Swiss Implementation Guidelines for the QR-bill"
+  # (IG 2.3, with IG 2.2 rules for the legacy combined address type "K").
+  # See docs/SPEC_NOTES.md for the sources of every rule.
+  #
+  # Mixed into Parser; every rule records a Problem via #error or #warning.
+  module Validation
+    QR_TYPE = "SPC"
+    VERSION = "0200"
+    CODING_TYPE = "1"
+    TRAILER = "EPD"
+    CURRENCIES = %w[CHF EUR].freeze
+    REFERENCE_TYPES = { "QRR" => :qrr, "SCOR" => :scor, "NON" => :non }.freeze
+
+    MIN_LINES = 31
+    MAX_LINES = 34
+    MAX_PAYLOAD_LENGTH = 997
+    MAX_INPUT_BYTES = 4096
+    MAX_MESSAGE_LENGTH = 140 # unstructured message + billing information together
+    MAX_ALTERNATIVE_PROCEDURE_LENGTH = 100
+
+    # Permitted characters since IG 2.3: Basic Latin, Latin-1 Supplement,
+    # Latin Extended-A, Ș ș Ț ț and the euro sign.
+    INVALID_CHARACTER = /[^ -~ -ſȘ-ț€]/
+    AMOUNT = /\A(?:0|[1-9]\d{0,8})\.\d{2}\z/
+
+    # Texts that turn a bill with amount 0.00 into a "DO NOT USE FOR PAYMENT"
+    # notification (IG 4.4; Romansh added in IG 2.4).
+    NOTIFICATION_TEXTS = [
+      "NICHT ZUR ZAHLUNG VERWENDEN",
+      "NE PAS UTILISER POUR LE PAIEMENT",
+      "NON UTILIZZARE PER IL PAGAMENTO",
+      "DO NOT USE FOR PAYMENT",
+      "BETG DUVRAR PER IL PAJAMENT"
+    ].freeze
+
+    # Elements with a fixed format, where blanks are never part of the value.
+    FIXED_FORMAT_FIELDS = %i[header version coding_type iban amount currency reference_type reference
+                             trailer].freeze
+
+    STRUCTURED_FIELDS = %i[type name street building_number postal_code town country].freeze
+    COMBINED_FIELDS = %i[type name address_line1 address_line2 postal_code town country].freeze
+
+    private
+
+    def error(field, message)
+      @errors << Problem.new(field: field, message: message)
+      nil
+    end
+
+    def warning(field, message)
+      @warnings << Problem.new(field: field, message: message)
+      nil
+    end
+
+    # A QR code holds at most 2953 bytes, so a longer text cannot have come
+    # from one; it is rejected before any line is looked at.
+    def check_input_size!(text)
+      return if text.bytesize <= MAX_INPUT_BYTES
+
+      message = "payload is #{text.bytesize} bytes; a QR code holds at most 2953 and a QR-bill at most " \
+                "#{MAX_PAYLOAD_LENGTH} characters"
+      raise InvalidPayload, @errors + [Problem.new(field: :payload, message: message)]
+    end
+
+    def check_length(field, value, max, label)
+      return if value.nil? || value.length <= max
+
+      error(field, "#{label} longer than #{max} characters (#{value.length})")
+    end
+
+    # Records a character-set problem in a raw (unstripped) line. Problems in
+    # status A lines (billing information, alternative procedures) are
+    # warnings because the IG forbids rejecting a bill for them.
+    def check_characters(field, line, status_a: false)
+      bad = line.scan(INVALID_CHARACTER).uniq
+      return if bad.empty?
+
+      listed = bad.first(3).map { |c| "#{c.inspect} (U+#{c.ord.to_s(16).upcase.rjust(4, "0")})" }.join(", ")
+      kind = if bad.all? do |c|
+        c.match?(/[[:cntrl:]]/)
+      end
+               "control character not permitted"
+             else
+               "characters outside the permitted Latin character set"
+             end
+      status_a ? warning(field, "#{kind}: #{listed}") : error(field, "#{kind}: #{listed}")
+    end
+
+    # "It is not permitted to fill in the elements with blanks" (IG 4.1.3).
+    # Blanks around a fixed-format element (header, IBAN, amount, codes,
+    # reference, country), and a line of blanks instead of an empty line, are
+    # errors. Around free text (names, street, town, message) they are only
+    # warnings, because SIX's own Style Guide samples have a trailing blank
+    # after a street name. Status A lines only ever get warnings.
+    def check_padding(field, line, value, status_a:)
+      if status_a
+        warning(field, "leading or trailing blanks removed")
+      elsif value.empty?
+        error(field, "blanks instead of an empty line are not permitted (IG 4.1.3)")
+      elsif fixed_format?(field)
+        error(field, "leading or trailing blanks are not permitted (IG 4.1.3; got #{line.inspect})")
+      else
+        warning(field, "leading or trailing blanks removed (IG 4.1.3 does not permit padding)")
+      end
+    end
+
+    def fixed_format?(field)
+      FIXED_FORMAT_FIELDS.include?(field) || field.end_with?(".type", ".country")
+    end
+
+    def check_header(version, coding_type)
+      if version != VERSION
+        detail = if version.to_s.match?(/\A02\d\d\z/)
+                   %(only "#{VERSION}" is permitted in master version 02)
+                 else
+                   %(version must be "#{VERSION}")
+                 end
+        error(:version, "#{detail} (got #{version.inspect})")
+      end
+      error(:coding_type, %(coding type must be "#{CODING_TYPE}" (got #{coding_type.inspect}))) if coding_type != CODING_TYPE
+    end
+
+    def check_iban(raw, iban)
+      return error(:iban, "IBAN is mandatory") if raw.nil?
+
+      error(:iban, "IBAN must be given without spaces") if raw.match?(/[[:space:]]/)
+      return error(:iban, "IBAN may only contain letters and digits") if raw.match?(/[^A-Za-z0-9[:space:]]/)
+
+      warning(:iban, "IBAN should be in upper case") if raw.match?(/[a-z]/)
+      if !iban.match?(/\A[A-Z0-9]+\z/)
+        error(:iban, "IBAN may only contain letters and digits")
+      elsif iban.match?(/\A[A-Z]{2}/) && !Iban::COUNTRIES.include?(iban[0, 2])
+        error(:iban, "only CH and LI IBANs are permitted (got #{iban[0, 2]})")
+      elsif iban.length != 21
+        error(:iban, "IBAN must be exactly 21 characters (got #{iban.length})")
+      elsif !iban.match?(Iban::QR_BILL_PATTERN)
+        error(:iban, "malformed CH/LI IBAN: country, 2 check digits, 5-digit institution id, 12-character account")
+      elsif Checksum.mod97(iban) != 1
+        error(:iban, "IBAN check digits are wrong (mod 97 != 1)")
+      end
+    end
+
+    def address_fields(group, code)
+      fields = code == "K" ? COMBINED_FIELDS : STRUCTURED_FIELDS
+      fields.map { |attr| :"#{group}.#{attr}" }
+    end
+
+    # Validates and builds an address from its seven stripped lines.
+    def build_address(group, values, required:)
+      if values.all?(&:nil?)
+        error(group, "the #{group} (address type, name, postal code, town, country) is mandatory") if required
+        return nil
+      end
+
+      code, name, line1, line2, postal_code, town, country = values
+      field = ->(attr) { :"#{group}.#{attr}" }
+      check_address_type(field[:type], code)
+      error(field[:name], "name is mandatory") if name.nil?
+      check_length(field[:name], name, 70, "name")
+      if code == "K"
+        check_combined_lines(field, line1, line2, postal_code, town)
+      else
+        check_structured_lines(field, line1, line2, postal_code, town)
+        check_postal_code_prefix(field[:postal_code], postal_code, country) if postal_code
+      end
+      check_country(field[:country], country)
+      Address.from_lines(values)
+    end
+
+    def check_address_type(field, code)
+      case code
+      when "S" then nil
+      when "K"
+        warning(field, 'address type "K" (combined address) was removed in IG 2.3 (Nov 2025); ' \
+                       'only structured addresses ("S") are permitted')
+      when nil then error(field, 'address type is mandatory ("S")')
+      else error(field, %(address type must be "S" (or legacy "K"), got #{code.inspect}))
+      end
+    end
+
+    def check_structured_lines(field, street, building_number, postal_code, town)
+      check_length(field[:street], street, 70, "street")
+      check_length(field[:building_number], building_number, 16, "building number")
+      error(field[:postal_code], "postal code is mandatory for a structured address") if postal_code.nil?
+      check_length(field[:postal_code], postal_code, 16, "postal code")
+      error(field[:town], "town is mandatory for a structured address") if town.nil?
+      check_length(field[:town], town, 35, "town")
+    end
+
+    # "The postal code must be provided without a country" (IG 4.2.2): a
+    # country code or international vehicle code followed by "-" or a blank
+    # ("CH-8000", "D-78462", "FL 9490") is an error, except where the
+    # prefix is part of the country's official format ("LV-1050"). Other
+    # letter prefixes followed by "-" are only suspicious.
+    def check_postal_code_prefix(field, postal_code, country)
+      match = postal_code.match(/\A([A-Za-z]{1,3})([- ])(?=\d)/)
+      return unless match
+
+      prefix = match[1].upcase
+      separator = match[2]
+      return if prefix == country&.upcase && Countries::PREFIXED_POSTAL_CODES.include?(prefix)
+
+      if Countries.iso?(prefix) || Countries::VEHICLE_CODES.key?(prefix)
+        error(field, "postal code must be given without a country prefix (got #{postal_code.inspect})")
+      elsif separator == "-"
+        warning(field, "postal code looks like it has a country prefix (#{postal_code.inspect})")
+      end
+    end
+
+    # IG 2.2 rules for address type "K".
+    def check_combined_lines(field, line1, line2, postal_code, town)
+      check_length(field[:address_line1], line1, 70, "address line 1")
+      error(field[:address_line2], "combined address (K) requires address line 2 (postal code and town)") if line2.nil?
+      check_length(field[:address_line2], line2, 70, "address line 2")
+      error(field[:postal_code], "combined address (K) must not fill postal code (it belongs in address line 2)") if postal_code
+      error(field[:town], "combined address (K) must not fill town (it belongs in address line 2)") if town
+    end
+
+    def check_country(field, country)
+      if country.nil?
+        error(field, "country is mandatory")
+      elsif !Countries.iso?(country.upcase(:ascii))
+        error(field, "country must be a two-letter ISO 3166-1 code (got #{country.inspect})")
+      elsif country.match?(/[a-z]/)
+        error(field, "country code must be upper case (got #{country.inspect})")
+      end
+    end
+
+    def build_ultimate_creditor(values)
+      return nil if values.all?(&:nil?)
+
+      error(:ultimate_creditor, "the ultimate creditor group is reserved for future use and must be empty")
+      Address.from_lines(values)
+    end
+
+    def parse_amount(value)
+      return nil if value.nil?
+
+      error(:amount, amount_problem(value)) unless value.match?(AMOUNT)
+      return nil unless value.match?(/\A-?\d+(?:[.,]\d+)?\z/)
+
+      BigDecimal(value.tr(",", "."))
+    end
+
+    def amount_problem(value)
+      case value
+      when /,/ then %(decimal separator must be "." (got #{value.inspect}))
+      when /\A-/ then "amount must not be negative (got #{value.inspect})"
+      when /\A0\d/ then "amount must not have leading zeroes (got #{value.inspect})"
+      when /\A\d+(?:\.\d?|\.\d{3,})?\z/ then "amount must have exactly two decimal places (got #{value.inspect})"
+      when /\A\d{10,}\.\d{2}\z/ then "amount above the maximum 999999999.99 (got #{value.inspect})"
+      else "amount must be a decimal such as 1949.75 (got #{value.inspect})"
+      end
+    end
+
+    def check_notification(amount, message)
+      return unless amount&.zero?
+      return if NOTIFICATION_TEXTS.include?(message)
+
+      error(:amount, "amount must be at least 0.01; 0.00 is only permitted for a notification whose message is " \
+                     "one of #{NOTIFICATION_TEXTS.map(&:inspect).join(", ")} (IG 4.4)")
+    end
+
+    def check_currency(currency)
+      if currency.nil?
+        error(:currency, "currency is mandatory (CHF or EUR)")
+      elsif !CURRENCIES.include?(currency)
+        error(:currency, "only CHF and EUR are permitted (got #{currency})")
+      end
+    end
+
+    def parse_reference_type(value)
+      return error(:reference_type, "reference type is mandatory (QRR, SCOR or NON)") if value.nil?
+
+      REFERENCE_TYPES.fetch(value) do
+        error(:reference_type, "unknown reference type #{value.inspect} (QRR, SCOR or NON)")
+      end
+    end
+
+    # QR-IBAN requires QRR; an ordinary IBAN forbids it.
+    def check_iban_reference_type(iban, qr_iban, reference_type, currency)
+      return if reference_type.nil? || iban.nil? || !iban.match?(Iban::QR_BILL_PATTERN)
+
+      if qr_iban && reference_type != :qrr
+        error(:reference_type, "a QR-IBAN requires reference type QRR (got #{reference_type.to_s.upcase})")
+      elsif !qr_iban && reference_type == :qrr
+        error(:reference_type, "reference type QRR requires a QR-IBAN (institution id 30000-31999); " \
+                               "#{iban} is an ordinary IBAN")
+      elsif reference_type == :qrr && currency == "EUR"
+        warning(:currency, "from IG 2.4 (in force 14 Nov 2026) a QR-IBAN with QR reference may only be used for CHF")
+      end
+    end
+
+    def check_reference(type, reference)
+      case type
+      when :qrr then check_qrr(reference)
+      when :scor then check_scor(reference)
+      when :non
+        error(:reference, "reference type NON must have an empty reference (got #{reference.inspect})") if reference
+      end
+    end
+
+    def check_qrr(reference)
+      return error(:reference, "reference type QRR requires a reference") if reference.nil?
+      return error(:reference, "QR reference must not contain spaces") if reference.match?(/[[:space:]]/)
+      return error(:reference, "QR reference must be numeric") unless reference.match?(/\A\d+\z/)
+      return error(:reference, "QR reference must be 27 digits (got #{reference.length})") if reference.length != 27
+      return error(:reference, "QR reference must not consist only of zeros") if reference.match?(/\A0+\z/)
+
+      expected = Checksum.mod10_recursive(reference[0, 26])
+      return if expected == reference[26].to_i
+
+      error(:reference, "QR reference check digit (modulo 10 recursive) is wrong: expected #{expected}, got #{reference[26]}")
+    end
+
+    def check_scor(reference)
+      problem = scor_problem(reference)
+      error(:reference, problem) if problem
+    end
+
+    def scor_problem(reference)
+      if reference.nil? then "reference type SCOR requires a creditor reference"
+      elsif reference.match?(/[[:space:]]/) then "creditor reference must not contain spaces"
+      elsif !reference.match?(/\A[A-Za-z0-9]+\z/) then "creditor reference may only contain letters and digits"
+      elsif !(5..25).cover?(reference.length) then "creditor reference must be 5 to 25 characters (got #{reference.length})"
+      elsif !reference.match?(/\ARF\d{2}/i) then 'creditor reference must start with "RF" and two check digits'
+      elsif Checksum.mod97(reference.upcase) != 1 then "creditor reference (ISO 11649) check digits are wrong"
+      end
+    end
+
+    def check_additional_information(message, billing_information)
+      if message && message.length > MAX_MESSAGE_LENGTH
+        check_length(:unstructured_message, message, MAX_MESSAGE_LENGTH, "unstructured message")
+      elsif message.to_s.length + billing_information.to_s.length > MAX_MESSAGE_LENGTH
+        error(:unstructured_message,
+              "unstructured message (#{message.to_s.length}) and billing information " \
+              "(#{billing_information.to_s.length}) together exceed #{MAX_MESSAGE_LENGTH} characters")
+      end
+    end
+
+    def check_trailer(trailer)
+      return if trailer == TRAILER
+
+      detail = trailer.nil? ? "line 31 is empty" : "got #{trailer.inspect}"
+      error(:trailer, %(trailer must be "#{TRAILER}" (#{detail}); a line may be missing or extra))
+    end
+
+    # Billing information is status A: problems are warnings only.
+    def parse_billing_information(value)
+      return nil if value.nil?
+
+      unless value.start_with?("//")
+        warning(:billing_information, 'billing information should start with "//" and a syntax identifier such as "S1"')
+      end
+      return nil unless BillingInformation.s1?(value)
+
+      info = BillingInformation.parse(value)
+      @warnings.concat(info.warnings)
+      info
+    end
+
+    # Alternative procedures are status A: problems are warnings only.
+    def check_alternative_procedures(values)
+      values.each_with_index do |value, index|
+        if value.nil?
+          warning(:alternative_procedures, "alternative procedure #{index + 1} is empty")
+        elsif value.length > MAX_ALTERNATIVE_PROCEDURE_LENGTH
+          warning(:alternative_procedures,
+                  "alternative procedure #{index + 1} longer than #{MAX_ALTERNATIVE_PROCEDURE_LENGTH} characters " \
+                  "(#{value.length})")
+        end
+      end
+    end
+  end
+end

data/lib/swiss_qr/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SwissQr
+  VERSION = "0.1.0"
+end

data/lib/swiss_qr.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "swiss_qr/version"
+require_relative "swiss_qr/errors"
+require_relative "swiss_qr/checksum"
+require_relative "swiss_qr/iban"
+require_relative "swiss_qr/countries"
+require_relative "swiss_qr/reference"
+require_relative "swiss_qr/address"
+require_relative "swiss_qr/billing_information"
+require_relative "swiss_qr/bill"
+require_relative "swiss_qr/validation"
+require_relative "swiss_qr/parser"
+# SwissQr.read, .read_all and .reader; does not load the qr_reader gem.
+require_relative "swiss_qr/reader"
+
+# Parser for the payload of Swiss QR-bills ("QR-Rechnung", SIX Swiss
+# Implementation Guidelines for the QR-bill: header "SPC", version "0200",
+# coding type "1", trailer "EPD").
+#
+#   bill = SwissQr.parse(payload)
+#   bill.iban          # => "CH4431999123000889012"
+#   bill.amount           # => 0.194975e4 (BigDecimal)
+#   bill.creditor.name    # => "Max Muster & Söhne"
+#   bill.billing_information&.invoice_number
+#
+#   SwissQr.read("invoice.pdf")      # first QR-bill in an image or PDF (needs a reader,
+#                                    # by default the qr_reader gem)
+module SwissQr
+  module_function
+
+  # Parses a QR-bill payload into a Bill.
+  #
+  # With <tt>strict: true</tt> (the default) any rule violation raises
+  # InvalidPayload, whose #errors lists every Problem. With
+  # <tt>strict: false</tt> the Bill is returned with its #errors filled in;
+  # InvalidPayload is still raised when the text is not structurally a
+  # QR-bill (QR type other than "SPC", fewer than 31 lines).
+  def parse(payload, strict: true)
+    Parser.parse(payload, strict: strict)
+  end
+
+  # True when +payload+ is a QR-bill without any rule violation (warnings
+  # are allowed).
+  def valid?(payload)
+    parse(payload, strict: false).valid?
+  rescue InvalidPayload, TypeError
+    false
+  end
+
+  # Cheap check whether +text+ looks like a QR-bill payload at all, e.g. to
+  # skip other QR codes on the same page. Does not validate.
+  def looks_like_qr_bill?(text)
+    Parser.looks_like_qr_bill?(text)
+  end
+end

data/sig/manifest.yaml

@@ -0,0 +1,2 @@
+dependencies:
+  - name: date

data/sig/swiss_qr.rbs

@@ -0,0 +1,226 @@
+module SwissQr
+  VERSION: String
+
+  def self.parse: (String payload, ?strict: bool) -> Bill
+  def self.valid?: (untyped payload) -> bool
+  def self.looks_like_qr_bill?: (untyped text) -> bool
+
+  # Anything with decode_all(input) -> Array[String], or a callable returning
+  # a String, an Array of Strings (or objects with #text), or nil.
+  type reader = _DecodeAll | _CallReader
+
+  interface _DecodeAll
+    def decode_all: (untyped input) -> Array[untyped]
+  end
+
+  interface _CallReader
+    def call: (untyped input) -> (String | Array[untyped] | nil)
+  end
+
+  def self.reader: () -> reader
+  def self.reader=: (reader? reader) -> reader?
+  def self.read: (untyped input, ?reader: reader?, ?strict: bool) -> Bill?
+  def self.read_all: (untyped input, ?reader: reader?, ?strict: bool) -> Array[Bill]
+
+  module Reader
+    INSTALL_HINT: String
+
+    class QrReaderAdapter
+      NO_IMAGES: String
+
+      attr_reader options: Hash[Symbol, untyped]
+
+      def initialize: (**untyped options) -> void
+      def decode_all: (untyped input) -> Array[String]
+      def each_text: (untyped input) { (String text) -> void } -> untyped
+    end
+
+    class Adapter
+      attr_reader reader: reader
+
+      def initialize: (reader reader) -> void
+      def decode_all: (untyped input) -> Array[String]
+      def each_text: (untyped input) { (String text) -> void } -> untyped
+    end
+
+    def self.reader?: (untyped reader) -> bool
+    def self.adapt: (reader? reader) -> Adapter
+    def self.texts: (untyped result) -> Array[String]
+    def self.text: (untyped item) -> String?
+  end
+
+  class CLI
+    OK: Integer
+    INVALID: Integer
+    FAILURE: Integer
+
+    def initialize: (?stdin: IO | StringIO, ?stdout: IO | StringIO, ?stderr: IO | StringIO) -> void
+    def run: (Array[String] argv) -> Integer
+  end
+
+  class Error < StandardError
+  end
+
+  class InvalidPayload < Error
+    attr_reader errors: Array[Problem]
+    attr_reader bill: Bill?
+
+    def initialize: (Array[Problem] errors, ?bill: Bill?) -> void
+  end
+
+  class ReaderUnavailable < Error
+  end
+
+  class Problem < Data
+    attr_reader field: Symbol
+    attr_reader message: String
+
+    def initialize: (field: Symbol | String, message: String) -> void
+    def about?: (Symbol | String name) -> bool
+    def as_json: (*untyped) -> Hash[String, String]
+  end
+
+  type address_type = :structured | :combined
+  type reference_type = :qrr | :scor | :non
+
+  class Address < Data
+    attr_reader type: address_type?
+    attr_reader name: String?
+    attr_reader street: String?
+    attr_reader building_number: String?
+    attr_reader postal_code: String?
+    attr_reader town: String?
+    attr_reader address_line1: String?
+    attr_reader address_line2: String?
+    attr_reader country: String?
+
+    def self.type_for: (String? code) -> address_type?
+    def self.from_lines: (Array[String?] lines) -> Address
+    def structured?: () -> bool
+    def combined?: () -> bool
+    def lines: () -> Array[String]
+    def as_json: (*untyped) -> Hash[String, String?]
+  end
+
+  class BillingInformation < Data
+    class VatRate < Data
+      attr_reader rate: BigDecimal
+      attr_reader amount: BigDecimal?
+
+      def as_json: (*untyped) -> Hash[String, String?]
+    end
+
+    class PaymentCondition < Data
+      attr_reader discount: BigDecimal
+      attr_reader days: Integer
+
+      def as_json: (*untyped) -> Hash[String, untyped]
+    end
+
+    attr_reader raw: String
+    attr_reader invoice_number: String?
+    attr_reader invoice_date: Date?
+    attr_reader customer_reference: String?
+    attr_reader vat_number: String?
+    attr_reader vat_dates: Array[Date]?
+    attr_reader vat_details: Array[VatRate]?
+    attr_reader vat_import_taxes: Array[VatRate]?
+    attr_reader payment_conditions: Array[PaymentCondition]?
+    attr_reader unknown_tags: Hash[String, String]
+    attr_reader warnings: Array[Problem]
+
+    def self.prefix: () -> String
+    def self.s1?: (untyped text) -> bool
+    def self.parse: (String text) -> BillingInformation
+    def self.decimal_string: (BigDecimal? value) -> String?
+    def as_json: (*untyped) -> Hash[String, untyped]
+  end
+
+  class Bill < Data
+    attr_reader version: String?
+    attr_reader coding_type: String?
+    attr_reader iban: String?
+    attr_reader qr_iban: bool
+    attr_reader creditor: Address?
+    attr_reader ultimate_creditor: Address?
+    attr_reader amount: BigDecimal?
+    attr_reader currency: String?
+    attr_reader debtor: Address?
+    attr_reader reference_type: reference_type?
+    attr_reader reference: String?
+    attr_reader unstructured_message: String?
+    attr_reader trailer: String?
+    attr_reader raw_billing_information: String?
+    attr_reader billing_information: BillingInformation?
+    attr_reader alternative_procedures: Array[String]
+    attr_reader errors: Array[Problem]
+    attr_reader warnings: Array[Problem]
+    attr_reader raw: String
+
+    def self.amount_string: (BigDecimal value) -> String
+    def qr_iban?: () -> bool
+    def valid?: () -> bool
+    def notification?: () -> bool
+    def open_amount?: () -> bool
+    def formatted_iban: () -> String?
+    def formatted_reference: () -> String?
+    def formatted_amount: () -> String?
+    def as_json: (*untyped) -> Hash[String, untyped]
+    def to_json: (*untyped) -> String
+  end
+
+  module Checksum
+    MOD10_TABLE: Array[Integer]
+
+    def self.mod10_recursive: (String digits) -> Integer
+    def self.mod97: (String value) -> Integer
+  end
+
+  module Iban
+    PATTERN: Regexp
+    QR_BILL_PATTERN: Regexp
+    QR_IID_RANGE: Range[Integer]
+    COUNTRIES: Array[String]
+
+    def self.normalize: (String? iban) -> String
+    def self.valid?: (String? iban) -> bool
+    def self.ch_or_li?: (String? iban) -> bool
+    def self.qr_iban?: (String? iban) -> bool
+    def self.qr_iid?: (String? iban) -> bool
+    def self.iid: (String? iban) -> String?
+    def self.format: (String? iban) -> String
+  end
+
+  module Countries
+    ISO_3166_1: Hash[String, true]
+    VEHICLE_CODES: Hash[String, String]
+    PREFIXED_POSTAL_CODES: Array[String]
+
+    def self.iso?: (String code) -> bool
+  end
+
+  module Reference
+    QRR_PATTERN: Regexp
+    SCOR_PATTERN: Regexp
+
+    def self.normalize: (String? reference) -> String
+    def self.valid_qrr?: (String? reference) -> bool
+    def self.valid_scor?: (String? reference) -> bool
+    def self.build_qrr: (String digits) -> String
+    def self.build_scor: (String payload) -> String
+    def self.format_qrr: (String reference) -> String
+    def self.format_scor: (String reference) -> String
+    def self.format: (String? reference, ?reference_type? type) -> String?
+  end
+
+  class Parser
+    BOM: String
+    MISTAGGED_ENCODINGS: Array[Encoding]
+    HEADER: Regexp
+
+    def self.parse: (String payload, ?strict: bool) -> Bill
+    def self.looks_like_qr_bill?: (untyped text) -> bool
+    def initialize: (String payload) -> void
+    def parse: (?strict: bool) -> Bill
+  end
+end