ibandit 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 53b3af5d1ef9ac7b61de43b1cc268380af1e1242
-  data.tar.gz: 751d53c25ff31c8a44f7cd334f76dac3389d8c0e
+  metadata.gz: 0bc26110597f8350ef5b91b0b2fbee330c21bc7b
+  data.tar.gz: 3b1d66ea7ceb6b58f275d164e4e873c34416ddd4
 SHA512:
-  metadata.gz: a8c6fa27a0efa6909f0783d5257bcce17ade3e21a1030078056854e8f3638e27568c61fe27485ab594f17bb9a0ce818206b521a463821e45f711fb23a50d1af8
-  data.tar.gz: bf770b81e770a5ed0037ae3b8ef810e84043f9355eadef160fe8cfcde8fd8321c34a8d2be3392a39dc97ebdb15fd879b4907fef7196571a5523b691ec4d1cc79
+  metadata.gz: 32ad174ca626b5f73fff4472fc42699146b57d194a871b480cd30765efe7b74d7c918f9f92e75500b2367243521f128282730220818369d6105482ef257f8360
+  data.tar.gz: 9440bd30011a7d61f2dd2beec9ee115ab27c0ca9af6cea75b2022d48ac3e25dfc49e3bfcdeb44665e2c0fe3ce1c3978494e9cd4233c80d25a51c280e596938ee

data/.rubocop.yml

@@ -12,7 +12,7 @@ LineLength:
   Max: 80
 
 ClassLength:
-  Max: 300
+  Max: 400
 
 # Avoid single-line methods.
 SingleLineMethods:
@@ -39,5 +39,9 @@ Style/AsciiComments:
 Metrics/MethodLength:
   Max: 25
 
+# Configuration parameters: CountComments.
+Metrics/ModuleLength:
+  Max: 400
+
 Style/DotPosition:
   EnforcedStyle: 'trailing'

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.8.0 - August 14, 2015
+- Return local details for Sweden
+- Introduce pseudo-IBANs for Sweden
+
 ## 0.7.0 - August 11, 2015
 - Remove all unused `CheckDigit` methods
 

data/README.md

@@ -97,13 +97,13 @@ county combines them:
 `check_digits`
 :    Two digits calculated using part of the ISO/IEC 7064:2003 standard
 
-`bank_code`
+`swift_bank_code`
 :    The SWIFT identifier for the bank to which the IBAN refers
 
-`branch_code`
+`swift_branch_code`
 :    The SWIFT identifer for the branch to which the IBAN refers (not used in all countries)
 
-`account_number`
+`swift_account_number`
 :    The account number for the account
 
 `iban_national_id`
@@ -116,9 +116,9 @@ iban = Ibandit::IBAN.new("GB82 WEST 1234 5698 7654 32")
 
 iban.country_code              # => "GB"
 iban.check_digits              # => "82"
-iban.bank_code                 # => "WEST"
-iban.branch_code               # => "123456"
-iban.account_number            # => "98765432"
+iban.swift_bank_code           # => "WEST"
+iban.swift_branch_code         # => "123456"
+iban.swift_account_number      # => "98765432"
 iban.iban_national_id          # => "WEST123456"
 ```
 
@@ -131,6 +131,23 @@ iban = Ibandit::IBAN.new("ES12 1234 5678 9112 3456 7890")
 iban.local_check_digits        # => "91"
 ```
 
+In some countries, the SWIFT-defined details differ from the local details that
+customers are familiar with.  For this reason, there are also `bank_code`,
+`branch_code` and `account_number` methods on an `IBAN` object.  At present,
+these only differ from the `swift_` equivalents for Swedish bank accounts.
+
+```ruby
+iban = Ibandit::IBAN.new(
+  country_code: 'SE',
+  account_number: '7507-1211203'
+)
+iban.swift_account_number      # => "75071211203"
+iban.account_number            # => "1211203"
+
+iban.swift_branch_code         # => nil
+iban.branch_code               # => "7507"
+```
+
 ### Initializing Ibandit
 
 The UK and Ireland both use part of the BIC as the `bank_code` in their IBANs.
@@ -420,6 +437,31 @@ iban = Ibandit::IBAN.new(
 iban.iban                     # => "GB60BARC20000055779911"
 ```
 
+### Pseudo-IBANs
+
+In some countries, it is not possible to recover local banking details from an
+IBAN.  For this reason, Ibandit has a concept of a *pseudo-IBAN*.  This is a
+string with a similar structure to an IBAN that can be decomposed into local
+banking details.  Pseudo-IBANs can be recognized by the fact that they have `ZZ`
+as the third and fourth characters (these would be check digits for a regular
+IBAN).
+
+```
+iban = Ibandit::IBAN.new(
+  country_code: 'SE',
+  branch_code: '7507',
+  account_number: '1211203'
+)
+iban.pseudo_iban              # => "SEZZX7507XXX1211203"
+
+iban = Ibandit::IBAN.new('SEZZX7507XXX1211203')
+iban.country_code             # => "SE"
+iban.branch_code              # => "7507"
+iban.account_number           # => "1211203"
+```
+
+At present, pseudo-IBANs are only available for Swedish bank accounts.
+
 ## Other libraries
 
 Another gem, [iban-tools](https://github.com/alphasights/iban-tools), also

data/data/raw/structure_additions.yml

@@ -76,6 +76,10 @@ QA:
 SA:
   :bank_code_format: \d{2}
   :account_number_format: '[A-Z0-9]{18}'
+SE:
+  :pseudo_iban_bank_code_length: 0
+  :pseudo_iban_branch_code_length: 5
+  :pseudo_iban_account_number_length: 10
 SI:
   :bank_code_format: \d{5}
   :account_number_format: \d{8}\d{2}

data/data/structures.yml

@@ -736,6 +736,9 @@ SE:
   :bban_format: \d{3}\d{16}\d{1}
   :bank_code_format: \d{3}
   :account_number_format: \d{16}\d{1}
+  :pseudo_iban_bank_code_length: 0
+  :pseudo_iban_branch_code_length: 5
+  :pseudo_iban_account_number_length: 10
 SI:
   :bank_code_position: 5
   :bank_code_length: 5

data/ibandit.gemspec

@@ -1,10 +1,10 @@
 require File.expand_path('../lib/ibandit/version', __FILE__)
 
 Gem::Specification.new do |gem|
-  gem.add_development_dependency 'rspec',           '~> 3.1'
-  gem.add_development_dependency 'rspec-its',       '~> 1.1'
-  gem.add_development_dependency 'rubocop',         '~> 0.30.1'
-  gem.add_development_dependency 'sax-machine',     '~> 1.1'
+  gem.add_development_dependency 'rspec',           '~> 3.3'
+  gem.add_development_dependency 'rspec-its',       '~> 1.2'
+  gem.add_development_dependency 'rubocop',         '~> 0.33.0'
+  gem.add_development_dependency 'sax-machine',     '~> 1.3'
   gem.add_development_dependency 'nokogiri',        '~> 1.6'
 
   gem.add_runtime_dependency 'i18n', '~> 0.7.0'

data/lib/ibandit.rb

@@ -1,11 +1,14 @@
 require 'i18n'
 require 'ibandit/version'
 require 'ibandit/errors'
+require 'ibandit/constants'
 require 'ibandit/iban'
 require 'ibandit/german_details_converter'
 require 'ibandit/swedish_details_converter'
 require 'ibandit/iban_splitter'
 require 'ibandit/iban_assembler'
+require 'ibandit/pseudo_iban_assembler'
+require 'ibandit/pseudo_iban_splitter'
 require 'ibandit/local_details_cleaner'
 require 'ibandit/check_digit'
 

data/lib/ibandit/constants.rb

@@ -0,0 +1,10 @@
+module Ibandit
+  module Constants
+    SUPPORTED_COUNTRY_CODES = %w(AT BE BG CY CZ DE DK EE ES FI FR GB GR HR HU IE
+                                 IS IT LT LU LV MC MT NL NO PL PT RO SE SI SK
+                                 SM).freeze
+
+    PSEUDO_IBAN_COUNTRY_CODES = %w(SE).freeze
+    PSEUDO_IBAN_CHECK_DIGITS = 'ZZ'.freeze
+  end
+end

data/lib/ibandit/iban.rb

@@ -2,13 +2,21 @@ require 'yaml'
 
 module Ibandit
   class IBAN
-    attr_reader :errors, :iban,  :country_code, :check_digits, :bank_code,
-                :branch_code, :account_number
+    attr_reader :errors, :iban, :country_code, :check_digits, :bank_code,
+                :branch_code, :account_number, :swift_bank_code,
+                :swift_branch_code, :swift_account_number
 
     def initialize(argument)
       if argument.is_a?(String)
-        @iban = argument.to_s.gsub(/\s+/, '').upcase
-        extract_local_details_from_iban!
+        input = argument.to_s.gsub(/\s+/, '').upcase
+
+        if pseudo_iban?(input)
+          local_details = PseudoIBANSplitter.new(input).split
+          build_iban_from_local_details(local_details)
+        else
+          @iban = input
+          extract_swift_details_from_iban!
+        end
       elsif argument.is_a?(Hash)
         build_iban_from_local_details(argument)
       else
@@ -33,8 +41,8 @@ module Ibandit
     def iban_national_id
       return unless decomposable?
 
-      national_id = bank_code.to_s
-      national_id += branch_code.to_s
+      national_id = swift_bank_code.to_s
+      national_id += swift_branch_code.to_s
       national_id.slice(0, structure[:iban_national_id_length])
     end
 
@@ -51,6 +59,15 @@ module Ibandit
       iban[4..-1] unless iban.nil?
     end
 
+    def pseudo_iban
+      @pseudo_iban ||= PseudoIBANAssembler.new(
+        country_code: country_code,
+        bank_code: bank_code,
+        branch_code: branch_code,
+        account_number: account_number
+      ).assemble
+    end
+
     ###############
     # Validations #
     ###############
@@ -115,12 +132,12 @@ module Ibandit
     def valid_bank_code_length?
       return unless valid_country_code?
 
-      if bank_code.nil? || bank_code.length == 0
+      if swift_bank_code.nil? || swift_bank_code.length == 0
         @errors[:bank_code] = Ibandit.translate(:is_required)
         return false
       end
 
-      return true if bank_code.length == structure[:bank_code_length]
+      return true if swift_bank_code.length == structure[:bank_code_length]
 
       @errors[:bank_code] =
         Ibandit.translate(:wrong_length, expected: structure[:bank_code_length])
@@ -129,12 +146,14 @@ module Ibandit
 
     def valid_branch_code_length?
       return unless valid_country_code?
-      return true if branch_code.to_s.length == structure[:branch_code_length]
+      if swift_branch_code.to_s.length == structure[:branch_code_length]
+        return true
+      end
 
       if structure[:branch_code_length] == 0
         @errors[:branch_code] = Ibandit.translate(:not_used_in_country,
                                                   country_code: country_code)
-      elsif branch_code.nil? || branch_code.length == 0
+      elsif swift_branch_code.nil? || swift_branch_code.length == 0
         @errors[:branch_code] = Ibandit.translate(:is_required)
       else
         @errors[:branch_code] =
@@ -147,12 +166,14 @@ module Ibandit
     def valid_account_number_length?
       return unless valid_country_code?
 
-      if account_number.nil?
+      if swift_account_number.nil?
         @errors[:account_number] = Ibandit.translate(:is_required)
         return false
       end
 
-      return true if account_number.length == structure[:account_number_length]
+      if swift_account_number.length == structure[:account_number_length]
+        return true
+      end
 
       @errors[:account_number] =
         Ibandit.translate(:wrong_length,
@@ -187,7 +208,7 @@ module Ibandit
     def valid_bank_code_format?
       return unless valid_bank_code_length?
 
-      if bank_code =~ Regexp.new(structure[:bank_code_format])
+      if swift_bank_code =~ Regexp.new(structure[:bank_code_format])
         true
       else
         @errors[:bank_code] = Ibandit.translate(:is_invalid)
@@ -199,7 +220,7 @@ module Ibandit
       return unless valid_branch_code_length?
       return true unless structure[:branch_code_format]
 
-      if branch_code =~ Regexp.new(structure[:branch_code_format])
+      if swift_branch_code =~ Regexp.new(structure[:branch_code_format])
         true
       else
         @errors[:branch_code] = Ibandit.translate(:is_invalid)
@@ -210,7 +231,7 @@ module Ibandit
     def valid_account_number_format?
       return unless valid_account_number_length?
 
-      if account_number =~ Regexp.new(structure[:account_number_format])
+      if swift_account_number =~ Regexp.new(structure[:account_number_format])
         true
       else
         @errors[:account_number] = Ibandit.translate(:is_invalid)
@@ -242,8 +263,8 @@ module Ibandit
       begin
         GermanDetailsConverter.convert(
           country_code: country_code,
-          bank_code: bank_code,
-          account_number: account_number
+          bank_code: swift_bank_code,
+          account_number: swift_account_number
         )
         true
       rescue UnsupportedAccountDetails
@@ -255,7 +276,10 @@ module Ibandit
     def valid_swedish_details?
       return true unless country_code == 'SE'
 
-      bank_details = { bank_code: bank_code, account_number: account_number }
+      bank_details = {
+        bank_code: swift_bank_code,
+        account_number: swift_account_number
+      }
 
       unless SwedishDetailsConverter.valid_bank_code?(bank_details)
         bank_code_field = bank_code.nil? ? :account_number : :bank_code
@@ -279,28 +303,41 @@ module Ibandit
     private
 
     def decomposable?
-      [iban, country_code, bank_code, account_number].none?(&:nil?)
+      [iban, country_code, swift_bank_code, swift_account_number].none?(&:nil?)
     end
 
     def build_iban_from_local_details(details_hash)
       local_details = LocalDetailsCleaner.clean(details_hash)
 
-      @country_code   = try_dup(local_details[:country_code])
-      @account_number = try_dup(local_details[:account_number])
-      @branch_code    = try_dup(local_details[:branch_code])
-      @bank_code      = try_dup(local_details[:bank_code])
-      @iban           = IBANAssembler.assemble(local_details)
-      @check_digits   = @iban.slice(2, 2) unless @iban.nil?
+      @country_code         = try_dup(local_details[:country_code])
+      @account_number       = try_dup(local_details[:account_number])
+      @branch_code          = try_dup(local_details[:branch_code])
+      @bank_code            = try_dup(local_details[:bank_code])
+
+      @swift_account_number = try_dup(local_details[:swift_account_number])
+      @swift_branch_code    = try_dup(local_details[:swift_branch_code])
+      @swift_bank_code      = try_dup(local_details[:swift_bank_code])
+
+      @iban                 = IBANAssembler.assemble(swift_details)
+      @check_digits         = @iban.slice(2, 2) unless @iban.nil?
     end
 
-    def extract_local_details_from_iban!
-      local_details = IBANSplitter.split(@iban)
+    def extract_swift_details_from_iban!
+      swift_details = IBANSplitter.split(@iban)
+
+      @country_code         = swift_details[:country_code]
+      @check_digits         = swift_details[:check_digits]
 
-      @country_code   = local_details[:country_code]
-      @check_digits   = local_details[:check_digits]
-      @bank_code      = local_details[:bank_code]
-      @branch_code    = local_details[:branch_code]
-      @account_number = local_details[:account_number]
+      @swift_bank_code      = swift_details[:bank_code]
+      @swift_branch_code    = swift_details[:branch_code]
+      @swift_account_number = swift_details[:account_number]
+
+      return if Constants::PSEUDO_IBAN_COUNTRY_CODES.
+                include?(@country_code)
+
+      @bank_code      = swift_details[:bank_code]
+      @branch_code    = swift_details[:branch_code]
+      @account_number = swift_details[:account_number]
     end
 
     def try_dup(object)
@@ -339,5 +376,18 @@ module Ibandit
         :bank_code
       end
     end
+
+    def swift_details
+      {
+        country_code: @country_code,
+        account_number: @swift_account_number,
+        branch_code: @swift_branch_code,
+        bank_code: @swift_bank_code
+      }
+    end
+
+    def pseudo_iban?(input)
+      input.slice(2, 2) == Constants::PSEUDO_IBAN_CHECK_DIGITS
+    end
   end
 end

data/lib/ibandit/iban_assembler.rb

@@ -1,9 +1,5 @@
 module Ibandit
   module IBANAssembler
-    SUPPORTED_COUNTRY_CODES = %w(AT BE BG CY CZ DE DK EE ES FI FR GB GR HR HU IE
-                                 IS IT LT LU LV MC MT NL NO PL PT RO SE SI SK
-                                 SM).freeze
-
     EXCEPTION_COUNTRY_CODES = %w(IT SM BE).freeze
 
     def self.assemble(local_details)
@@ -67,8 +63,11 @@ module Ibandit
     ##################
 
     def self.can_assemble?(local_details)
-      SUPPORTED_COUNTRY_CODES.include?(local_details[:country_code]) &&
-        valid_arguments?(local_details)
+      supported_country_code?(local_details) && valid_arguments?(local_details)
+    end
+
+    def self.supported_country_code?(local_details)
+      Constants::SUPPORTED_COUNTRY_CODES.include?(local_details[:country_code])
     end
 
     def self.valid_arguments?(local_details)

data/lib/ibandit/local_details_cleaner.rb

@@ -1,12 +1,12 @@
 module Ibandit
   module LocalDetailsCleaner
-    SUPPORTED_COUNTRY_CODES = %w(AT BE BG CY CZ DE DK EE ES FI FR GB GR HR HU IE
-                                 IS IT LT LU LV MC MT NL NO PL PT RO SE SI SK
-                                 SM).freeze
-
     def self.clean(local_details)
       country_code = local_details[:country_code]
 
+      unless explicit_swift_details?(country_code)
+        local_details = swift_details_for(local_details).merge(local_details)
+      end
+
       return local_details unless can_clean?(country_code, local_details)
 
       local_details.merge(
@@ -18,10 +18,14 @@ module Ibandit
     ###########
 
     def self.can_clean?(country_code, local_details)
-      SUPPORTED_COUNTRY_CODES.include?(country_code) &&
+      Constants::SUPPORTED_COUNTRY_CODES.include?(country_code) &&
         fields_for?(country_code, local_details)
     end
 
+    def self.explicit_swift_details?(country_code)
+      Constants::PSEUDO_IBAN_COUNTRY_CODES.include?(country_code)
+    end
+
     def self.fields_for?(country_code, opts)
       required_fields(country_code).all? { |argument| opts[argument] }
     end
@@ -149,7 +153,7 @@ module Ibandit
 
       {
         bank_code:      bank_code.rjust(4, '0'),
-        account_number: account_number.gsub('-', '').rjust(10, '0')
+        account_number: account_number.delete('-').rjust(10, '0')
       }
     end
 
@@ -437,14 +441,19 @@ module Ibandit
     end
 
     def self.clean_se_details(local_details)
-      converted_details =
-        SwedishDetailsConverter.convert(local_details[:account_number])
+      converted_details = SwedishDetailsConverter.new(
+        branch_code: local_details[:branch_code],
+        account_number: local_details[:account_number]
+      ).convert
 
-      bank_code = local_details[:bank_code] || converted_details[:bank_code]
+      bank_code = local_details[:bank_code] ||
+                  converted_details[:swift_bank_code]
 
       {
-        bank_code:      bank_code,
-        account_number: converted_details[:account_number]
+        account_number:       converted_details[:account_number],
+        branch_code:          converted_details[:branch_code],
+        swift_bank_code:      bank_code,
+        swift_account_number: converted_details[:swift_account_number]
       }
     end
 
@@ -477,5 +486,14 @@ module Ibandit
       hufo + reikningsnumer + kennitala
     end
     private_class_method :pad_is_account_number
+
+    def self.swift_details_for(local_details)
+      {
+        swift_bank_code:      local_details[:bank_code],
+        swift_branch_code:    local_details[:branch_code],
+        swift_account_number: local_details[:account_number]
+      }
+    end
+    private_class_method :swift_details_for
   end
 end