credit_card_validations 9.0.0 → 10.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d26fc84c0dd18fbfcacaeead238fe16ecefe51486e4122e63c3dcf4836fd4ce6
-  data.tar.gz: a1bad2adea7168439991cf98bb68a25a2d62c4372602cbe54743f23eda12c11e
+  metadata.gz: b16ea3c34b40baacacb68877a244e7c30710323e7949b6b626e5b327156198aa
+  data.tar.gz: 596b070c9b31cefa5aacde43cff367ac609237ccea747cd20e9e2e8c9f6a95ac
 SHA512:
-  metadata.gz: 14d43e6661c30034f8f52f4bf0558eb4704843ad048dfb79943a0822f4f1d6b221d31a98bd1b73dd23cd3a6d76904fdc88b6758abfb5ea1a701da001e938b73a
-  data.tar.gz: c41da3b3de8f45d93413a41c4fe88c8e543eea2c8e149ea8500d594ee1c40802c2554cb7f72f87e732d600b7aded5d69478f9ff4a9acebea9bbed85edc35873f
+  metadata.gz: 7bd5c35081bc1085c11232c7c13d14befed6edb45b7b4faca8ac27b8b0b39b5bacd61e3ed8e4ecda977c34e50b0546f2904883602c12ea35a7d82adc942d1260
+  data.tar.gz: 9b8df4c6df565cf26f7084683a0eb68bc40e2dfbf06b86131103f92360b681772aa938d72e7389821463789bdf90bfec95713b2aef82c5cec8a7cf4540dc7670

data/README.md

@@ -77,7 +77,7 @@ Everything else is detected only when its plugin is explicitly required. Plugins
 
 |    Name   |    Key     | Status |
 ---------------------   | ------------| ------|
-[Diners Club US](http://en.wikipedia.org/wiki/Diners_Club_International#MasterCard_alliance) | `:diners_us` | Merged into Discover for US routing in 2008 |
+[Diners Club US](http://en.wikipedia.org/wiki/Diners_Club_International#MasterCard_alliance) | `:diners_us` | Issued on MasterCard BINs since 2004 |
 [EnRoute](https://en.wikipedia.org/wiki/EnRoute_(credit_card)) | `:en_route` | Withdrawn 1989 |
 [Laser](https://en.wikipedia.org/wiki/Laser_%28debit_card%29) | `:laser` | Withdrawn 2014 |
 [Solo](https://en.wikipedia.org/wiki/Solo_(debit_card)) | `:solo` | Withdrawn 2011 |
@@ -93,30 +93,78 @@ require 'credit_card_validations/plugins/hipercard'
 # ... whichever brands the app actually accepts
 ```
 
-## Migrating from v8.x → v9.0
-
-Seven brands moved from the default brand set to opt-in plugins in v9.0. The auto-require shim keeps existing code working for one major version with a one-time deprecation warning per brand.
+## Migrating from v9.x → v10.0 (unreleased)
 
-| Brand | Status | Auto-loaded until |
-|---|---|---|
-| `:dankort` | Active (Denmark) | v10.0 |
-| `:elo` | Active (Brazil) | v10.0 |
-| `:hipercard` | Active (Brazil) | v10.0 |
-| `:mir` | Active (Russia) | v10.0 |
-| `:rupay` | Active (India) | v10.0 |
-| `:solo` | Withdrawn 2011 | v10.0 |
-| `:switch` | Withdrawn 2002 | v10.0 |
+On `master`, ahead of the v10.0 release, the auto-require shim is gone. In v9.0 the seven brands below moved out of the
+default set, and referencing one of them still worked — the plugin was loaded
+for you and a deprecation warning was printed once. v10.0 removes that.
 
-If your code references any of these brands by symbol, add the matching `require` to your initializer to silence the warning and survive v10:
+If your code names any of these brands, add the matching `require`:
 
 ```ruby
 # config/initializers/credit_card_validations.rb
 require 'credit_card_validations/plugins/mir'
 require 'credit_card_validations/plugins/elo'
-# ...
+# ... whichever brands the app actually accepts
+```
+
+Without it the brand is simply unknown. **Nothing warns** — the v9 deprecation
+warning is gone too — and the read-only paths stay quiet, so a missing
+`require` will not announce itself where you are most likely to notice it:
+
+```ruby
+Detector.new('2202 1234 1234 1234').brand                #=> nil
+Detector.new('2202 1234 1234 1234').valid?(:mir)         #=> false
+Detector.new('2202 1234 1234 1234').brand_name           #=> nil
+Detector.new('2202 1234 1234 1234').possible_brands      #=> []
+Detector.brand_name(:mir)                                #=> nil
+Detector.valid_cvv?('123', :mir)                         #=> false
+Detector.has_luhn_check_rule?(:mir)                      #=> true  (nothing opted out)
+'2202 1234 1234 1234'.credit_card_brand                  #=> nil
+'2202 1234 1234 1234'.credit_card_brand_name             #=> nil
+'2202 1234 1234 1234'.valid_credit_card_brand?(:mir)     #=> false
 ```
 
-When v10 lands, the auto-load disappears. Code that names these brands without a matching `require` will see them as unknown — `Detector#brand` returns `nil`, predicate methods (`mir?`, `elo?`, …) are not defined, and `valid?(:mir)` returns false.
+Four paths do raise, because there is nothing sensible to return:
+
+```ruby
+Detector.new(pan).mir?                  # NoMethodError — the predicate is never defined
+CreditCardValidations::Factory.random(:mir)   # CreditCardValidations::Error: Unsupported brand
+Detector.add_rule(:mir, 16, ['2202'])         # CreditCardValidations::Error: brand mir is undefined
+Detector::LEGACY_PLUGIN_BRANDS                # NameError — see below
+```
+
+ActiveModel validators never raise on a missing plugin; the record is just
+invalid. Which means a PAN field restricted to a plugin brand **rejects every
+number you give it**, including a valid card of that brand:
+
+```ruby
+validates :number, credit_card_number: { brands: [:mir] }   # nothing passes
+validates :cvv,    credit_card_cvv:    { brand: :mir }      # nothing passes
+```
+
+`Detector::LEGACY_PLUGIN_BRANDS` was a public constant in v9 and is gone. An
+app that read it to build its own require list now gets `NameError`; replace it
+with a literal list of the brands you accept.
+
+So check the brand list against your initializer rather than waiting for an
+error — in the paths an app exercises most, there will not be one.
+
+| Brand | Status |
+|---|---|
+| `:dankort` | Active (Denmark) |
+| `:elo` | Active (Brazil) |
+| `:hipercard` | Active (Brazil) |
+| `:mir` | Active (Russia) |
+| `:rupay` | Active (India) |
+| `:solo` | Withdrawn 2011 |
+| `:switch` | Withdrawn 2002 |
+
+## Migrating from v8.x → v9.0
+
+Seven brands moved from the default brand set to opt-in plugins in v9.0. Up to
+v9.x an auto-require shim kept existing code working with a one-time
+deprecation warning per brand; it is removed on master for v10.0, see above.
 
 ### Other breaking changes in v9.0
 
@@ -234,6 +282,38 @@ detector.possible_brands                # => [:visa]   (during live input)
 detector.valid_cvv?('123')              # => true
 ```
 
+### Detecting against a fixed brand list
+
+`#valid?` and `#brand` take a brand list per call. `with_brands` holds that
+list instead, and applies it to the methods that take no brand list of their
+own — `possible_brands`, `brand_name`, `formatted`, `valid_cvv?`:
+
+```ruby
+set = CreditCardValidations.with_brands(:visa, :mastercard)
+
+set.brands                                 # => [:visa, :mastercard]
+set.detect('4111111111111111').brand       # => :visa
+set.detect('348051773827666').brand        # => nil
+set.detect('348051773827666').valid?       # => false
+set.detect('34').possible_brands           # => []
+```
+
+`detect` returns a `Detector`, so the whole instance API works on it.
+
+Keys are brand keys, as symbols or strings, in any case. An unknown key raises
+`CreditCardValidations::Error` rather than being dropped, since a dropped brand
+would mean a valid card is quietly rejected; an empty list raises for the same
+reason.
+
+A set narrows which brands are considered, not what they are — definitions
+are read from `Detector.brands` at every lookup, so `add_brand`, `add_rule`,
+`delete_brand` and a replaced brand source all apply to an existing set.
+
+Which predicate methods exist stays global: `add_brand` defines them on
+`Detector`, so a detector from a visa-only set still responds to
+`mastercard?` (with `false`), and `delete_brand(:mastercard)` undefines it
+everywhere. Use `valid?(:mastercard)` where that matters.
+
 ### Adding a custom brand at runtime
 
 ```ruby
@@ -241,6 +321,31 @@ CreditCardValidations.add_brand(:voyager, { length: 15, prefixes: '86' })
 CreditCardValidations::Detector.new('869926275400212').voyager?  # => true
 ```
 
+A prefix is the literal digits it spells — list a range out (`%w[51 52 53]`),
+rather than writing `5[1-3]`, which would only ever match that text.
+
+`add_brand` adds; it does not redefine. A brand that is already registered
+raises `CreditCardValidations::Error`, because the call replaces the whole
+entry — the rules, and with them the brand's name, CVV size, segments and
+`skip_luhn` opt-out — so a call that only meant to change the rules used to
+leave a brand that no longer detected its own cards.
+
+To widen a registered brand, add a rule:
+
+```ruby
+CreditCardValidations::Detector.add_rule(:visa, 16, ['9'])
+```
+
+Keys are converted to symbols, so `add_brand`, `add_rule` and `delete_brand`
+all take `:visa` or `"visa"` alike.
+
+To replace one, remove it first:
+
+```ruby
+CreditCardValidations::Detector.delete_brand(:visa)
+CreditCardValidations.add_brand(:visa, { length: 16, prefixes: '9' })
+```
+
 ### Removing a brand at runtime
 
 ```ruby
@@ -255,15 +360,43 @@ CreditCardValidations::Detector.new(number).valid_luhn?
 CreditCardValidations::Luhn.valid?(number)
 ```
 
-### Generating Luhn-valid test numbers
+### Generating test numbers and test cards
+
+```ruby
+CreditCardValidations::Factory.random_number(:visa)  #=> "4012888888881881"
+
+card = CreditCardValidations::Factory.random_card(:amex)
+card.valid?              #=> true
+card.brand               #=> :amex
+card.verification_value  #=> "8812"   (4 for Amex, 3 for the other bundled brands)
+```
+
+`random_number` returns a Luhn-valid PAN the detector accepts for the brand,
+including for brands that declare `skip_luhn` — that flag means detection
+tolerates a missing check digit, not that real cards lack one, and a computed
+digit passes either way. `Factory.random` is kept as an alias of
+`random_number`.
+
+**Breaking:** the low-level `Factory.number(prefix, length, skip_luhn)` lost
+its third argument and is now `number(prefix, length)`. The argument only
+selected the behaviour described above, so there is nothing for it to mean.
+
+`random_card` returns a [`Card`](#creditcardvalidationscard) with a number, an
+expiration 1-60 months out and a verification value. The number comes from the
+requested brand's rules; the CVV is sized from the brand the PAN **detects**
+as, since that is the one `Card` validates against. Where ranges overlap those
+are not the same brand, and `card.brand` reports the detected one.
+
+Called with no brand, `random_card` draws only among brands that declare a
+`:code`:
 
 ```ruby
-CreditCardValidations::Factory.random(:amex)
-# => "348051773827666"
-CreditCardValidations::Factory.random(:maestro)
-# => "6010430241237266856"
+CreditCardValidations::Factory.random_card.valid?  #=> true
 ```
 
+`random_card` needs the brand to declare a `:code` size, and raises
+`CreditCardValidations::Error` otherwise.
+
 ## Configuration
 
 To override the default brand source, copy [the bundled `brands.yaml`](https://github.com/didww/credit_card_validations/blob/master/lib/data/brands.yaml), edit it, and point the gem at it in a Rails initializer:

data/lib/credit_card_validations/brand_set.rb

@@ -0,0 +1,63 @@
+module CreditCardValidations
+  # A fixed list of brands to detect against, so the list is named once
+  # instead of being repeated at every call site.
+  #
+  #   set = CreditCardValidations.with_brands(:visa, :mastercard)
+  #   set.detect(pan).brand          # same as Detector.new(pan).brand(:visa, :mastercard)
+  #   set.detect(pan).possible_brands # ...but this one has no per-call form
+  #
+  # Build one with CreditCardValidations.with_brands.
+  #
+  # A set narrows *which* brands are considered. It does not copy *what* they
+  # are: the definitions are read from Detector.brands on every lookup, so a
+  # set never disagrees with the rest of the process about what a Visa number
+  # looks like. Two objects giving different answers for one card would be a
+  # worse failure than the stale global registry a snapshot would protect
+  # against.
+  class BrandSet
+
+    def initialize(keys)
+      raise Error, 'with_brands needs at least one brand' if keys.empty?
+
+      # Brand keys only, in any case: a list of brands usually arrives as
+      # strings from a config file or an environment variable.
+      @brands = keys.map { |key| key.to_s.downcase.to_sym }.freeze
+      missing = @brands - Detector.brands.keys
+      unless missing.empty?
+        raise Error, "unknown brand(s) #{missing.map(&:inspect).join(', ')}; " \
+                     "registered: #{Detector.brands.keys.map(&:inspect).join(', ')}" \
+                     ' (a plugin brand needs its plugin required first)'
+      end
+
+      # A Detector subclass whose registry is the global one, narrowed to this
+      # set. class_attribute gives every subclass its own `brands`, and every
+      # lookup in Detector -- the class methods and the instance ones alike --
+      # goes through it, so the whole API scopes with nothing added to
+      # Detector itself. The reader is a method rather than a stored hash so
+      # that it stays live.
+      scoped_keys = @brands
+      @detector_class = Class.new(Detector)
+      @detector_class.define_singleton_method(:brands) do
+        # Registry order, not the order the set was built with: Hash#slice
+        # answers in argument order, Array#& in the receiver's.
+        registry = Detector.brands
+        registry.slice(*(registry.keys & scoped_keys))
+      end
+    end
+
+    # Keys of the brands in this set, in the order they were requested.
+    # Frozen: this is the set's own list, not a copy to edit.
+    attr_reader :brands
+
+    # A Detector that sees only this set's brands. It is a Detector, so the
+    # whole instance API works on it.
+    def detect(number)
+      detector_class.new(number)
+    end
+
+    private
+
+    attr_reader :detector_class
+
+  end
+end

data/lib/credit_card_validations/card.rb

@@ -23,7 +23,14 @@ module CreditCardValidations
   class Card
     include ActiveModel::Model
 
-    attr_accessor :number, :month, :year, :verification_value, :name
+    attr_reader :number
+    attr_accessor :month, :year, :verification_value, :name
+
+    def number=(value)
+      @number = value
+      @detector = nil
+      value
+    end
 
     validates :number, credit_card_number: true
     validates :verification_value, credit_card_cvv: { brand_from: :number }

data/lib/credit_card_validations/detector.rb

@@ -9,13 +9,6 @@ module CreditCardValidations
     class_attribute :brands
     self.brands = {}
 
-    # Brands that were part of the default set up to v8.x and moved to
-    # opt-in plugins in v9.0. The shim below auto-loads the plugin on first
-    # reference and emits a one-time deprecation warning. To be removed in
-    # v10.0 — users should add explicit `require` statements by then.
-    LEGACY_PLUGIN_BRANDS = %i[mir rupay elo dankort hipercard solo switch].freeze
-    @@legacy_autoloaded = {}
-
     attr_reader :number
 
     def initialize(number)
@@ -32,20 +25,32 @@ module CreditCardValidations
       valid_number?(*keys)
     end
 
+    # The brand with the longest matched prefix, or nil if none matches.
+    #
+    # Among equal matched lengths the brand that was registered first wins --
+    # the comparison below is strictly greater, so a later brand never
+    # displaces an earlier one. That order is not arbitrary: the default
+    # brands are always in the registry before any plugin, since a plugin
+    # cannot be required before the gem itself, and add_brand appends after
+    # both. So a plugin never takes a PAN away from a default brand on a tie,
+    # and your own brand never takes one away from a shipped one.
     def valid_number?(*keys)
       selected_brands = keys.blank? ? self.brands : resolve_keys(*keys)
-      if selected_brands.any?
-        matched_brands = []
-        selected_brands.each do |key, brand|
-          match_data = matches_brand?(brand)
-          matched_brands << {brand: key, matched_prefix_length: match_data.to_s.length} if match_data
-        end
-
-        if matched_brands.present?
-          return matched_brands.sort{|a, b| a[:matched_prefix_length] <=> b[:matched_prefix_length]}.last[:brand]
-        end
+      best_brand = nil
+      # Below zero, not zero: a brand registered with an empty prefix matches
+      # with length zero, and that still has to beat "nothing matched".
+      best_length = -1
+
+      selected_brands.each do |key, brand|
+        match_data = matches_brand?(brand)
+        next unless match_data
+        next unless match_data.to_s.length > best_length
+
+        best_brand = key
+        best_length = match_data.to_s.length
       end
-      nil
+
+      best_brand
     end
 
     #check if luhn valid
@@ -121,50 +126,51 @@ module CreditCardValidations
         end
         el.downcase
       end
-      brand_keys.each { |k| autoload_legacy_plugin(k) }
-      self.brands.slice(*brand_keys)
-    end
-
-    def autoload_legacy_plugin(key)
-      return unless LEGACY_PLUGIN_BRANDS.include?(key)
-      return if self.class.brands.key?(key)
-      return if @@legacy_autoloaded[key]
-      @@legacy_autoloaded[key] = true
-
-      Warning.warn(
-        "[credit_card_validations] :#{key} was moved to a plugin in v9.0. " \
-        "Auto-loading 'credit_card_validations/plugins/#{key}' for backward " \
-        "compatibility. Add `require 'credit_card_validations/plugins/#{key}'` " \
-        "to your initializer to silence; auto-load is removed in v10.\n"
-      )
-      load "credit_card_validations/plugins/#{key}.rb"
+      # Hash#slice returns its keys in the order of its arguments, which would
+      # hand valid_number? the caller's order and let that decide a tie. Array#&
+      # answers in the receiver's order, so intersecting the registry's own keys
+      # first puts them back in registry order -- and keeps the lookup O(keys)
+      # rather than scanning the whole registry.
+      registry = self.brands
+      registry.slice(*(registry.keys & brand_keys))
     end
 
+    # The longest match among the brand's rules, or false. add_brand takes a
+    # list of rules and more than one can accept the same length, so returning
+    # the first match let an earlier short prefix hide a later long one -- and
+    # the brand then lost a comparison it should have won.
     def matches_brand?(brand)
-      rules = brand.fetch(:rules)
       options = brand.fetch(:options, {})
+      return false unless options[:skip_luhn] || valid_luhn?
 
-      rules.each do |rule|
-        if (options[:skip_luhn] || valid_luhn?) &&
-            rule[:length].include?(number.length) &&
-            match_data = number.match(rule[:regexp])
-          return match_data
-        end
+      longest = false
+      brand.fetch(:rules).each do |rule|
+        next unless rule[:length].include?(number.length)
+        next unless (match_data = number.match(rule[:regexp]))
+        next if longest && match_data.to_s.length <= longest.to_s.length
+
+        longest = match_data
       end
-      false
+      longest
     end
 
     class << self
 
+      # :skip_luhn is an opt-out, so anything without one -- including a brand
+      # the registry does not know -- is Luhn-checked.
       def has_luhn_check_rule?(key)
-        !brands[key].fetch(:options, {}).fetch(:skip_luhn, false)
+        !brands.dig(key, :options, :skip_luhn)
       end
 
       # Class-level CVV check: validates a code against an explicit brand,
       # without needing a Detector instance. Useful when only the brand is
       # known (form input bound to a brand select, separate CVV field, etc.).
+      # An unknown brand -- including a plugin brand whose file was never
+      # required -- is false, not an error. A brand that *is* registered but
+      # declares no :code raises, since that is registry data the caller owns.
       def valid_cvv?(code, brand)
         return false if code.nil? || brand.nil? || !code.to_s.match?(/\A\d+\z/)
+        return false unless brands.key?(brand)
         spec = brands.dig(brand, :options, :code)
         raise Error, "brand #{brand.inspect} has no :code option" if spec.nil?
         code.to_s.length == spec[:size]
@@ -176,17 +182,34 @@ module CreditCardValidations
       #   CreditCardValidations.add_brand(:en_route, {length: 15, prefixes: ['2014', '2149']}, {skip_luhn: true}) #skip luhn
       #
       def add_brand(key, rules, options = {})
-        # Mark legacy plugin brands as handled so the v9 auto-require shim
-        # never re-loads them after the user takes any explicit action
-        # (require, add_brand, or a later delete_brand).
-        @@legacy_autoloaded[key] = true if LEGACY_PLUGIN_BRANDS.include?(key)
+        # The registry is keyed by symbol, and delete_brand converts. Without
+        # the same conversion here a string key passed the check below and
+        # wrote a second entry that resolve_keys could not detect with and
+        # delete_brand could not remove.
+        key = key.to_sym
 
-        brands[key] = {rules: [], options: options || {}}
+        # Adds a brand; it does not redefine one. The write below replaces the
+        # whole entry, so redefining dropped everything the call did not
+        # mention -- the brand's name, CVV size, segments and skip_luhn
+        # opt-out -- and the brand stopped detecting its own cards, silently.
+        # Use add_rule to widen a registered brand, or delete_brand first to
+        # replace it on purpose.
+        if brands.key?(key)
+          raise Error.new("brand #{key.inspect} is already registered; " \
+                          'use add_rule to widen it, or delete_brand first to replace it')
+        end
 
+        entry = {rules: [], options: options || {}}
         Array.wrap(rules).each do |rule|
-          add_rule(key, rule[:length], rule[:prefixes])
+          length, prefixes = Array(rule[:length]), Array(rule[:prefixes])
+          entry[:rules] << {length: length, regexp: compile_regexp(prefixes), prefixes: prefixes}
         end
 
+        # One reference assignment, after the entry is complete: a reader
+        # iterating the old hash never sees a half-built brand and never
+        # trips Hash's "can't add a new key during iteration" guard.
+        self.brands = brands.merge(key => entry)
+
         define_brand_method(key)
 
       end
@@ -210,16 +233,19 @@ module CreditCardValidations
       def delete_brand(key)
         key = key.to_sym
         undef_brand_method(key)
-        brands.reject! { |k, _| k == key }
+        self.brands = brands.except(key)
       end
 
       #create rule for detecting brand
       def add_rule(key, length, prefixes)
+        key = key.to_sym
         unless brands.has_key?(key)
           raise Error.new("brand #{key} is undefined, please use #add_brand method")
         end
         length, prefixes = Array(length), Array(prefixes)
-        brands[key][:rules] << {length: length, regexp: compile_regexp(prefixes), prefixes: prefixes}
+        rule = {length: length, regexp: compile_regexp(prefixes), prefixes: prefixes}
+        entry = brands[key].merge(rules: brands[key][:rules] + [rule])
+        self.brands = brands.merge(key => entry)
       end
 
       protected
@@ -235,9 +261,26 @@ module CreditCardValidations
         undef_method "#{key}?".to_sym if method_defined? "#{key}?".to_sym
       end
 
-      #create regexp by array of prefixes
+      # Regexp by array of prefixes, longest first.
+      #
+      # Alternation is first-match, left-to-right, not longest-match: in
+      # ^((677)|(6771)) a 6771... PAN matches "677", so the brand reports a
+      # shorter prefix than the one it declares and loses comparisons it
+      # should win. Ordering by length makes the match the longest prefix the
+      # brand actually declares, which is what valid_number? compares.
+      #
+      # The index keeps the order total, so the same prefix list always
+      # compiles to the same regexp -- sort_by alone is not stable.
       def compile_regexp(prefixes)
-        Regexp.new("^((#{prefixes.join(")|(")}))")
+        ordered = prefixes.each_with_index.sort_by { |prefix, i| [-prefix.to_s.length, i] }.map(&:first)
+        # Escaped, so a prefix is the literal digits it looks like. Without it
+        # a prefix could carry regexp syntax, its matched length would stop
+        # equalling its own length, and the ordering above -- which exists to
+        # report the longest match -- would rank by the wrong number.
+        # possible_brands compares prefixes as plain strings, so this also
+        # brings the two closer together.
+        pattern = ordered.map { |prefix| Regexp.escape(prefix.to_s) }.join(')|(')
+        Regexp.new("^((#{pattern}))")
       end
 
     end

data/lib/credit_card_validations/factory.rb

@@ -1,40 +1,86 @@
 # == CreditCardValidations Factory
-# Generates card number that passes validation
+# Generates cards and card numbers that pass validation
 #
-# #random
-#   CreditCardValidations::Factory.random
+# #random_number
+#   CreditCardValidations::Factory.random_number
 # #or particular brand
-#   CreditCardValidations::Factory.random(:maestro) # "6010430241237266856"
+#   CreditCardValidations::Factory.random_number(:maestro) # "6010430241237266856"
 #
+# #random_card
+#   CreditCardValidations::Factory.random_card(:amex) # #<CreditCardValidations::Card>
 #
 #
 module CreditCardValidations
   class Factory
     class << self
-      def random(brand = nil)
+      def random_number(brand = nil)
         brand = Detector.brands.keys.sample if brand.nil?
-        if Detector.brands[brand].nil?
+        spec = Detector.brands[brand]
+        if spec.nil?
           raise Error.new('Unsupported brand')
         end
-        generate(Detector.brands[brand][:rules].sample)
+        generate(spec[:rules].sample)
+      end
+
+      # Released as the only generator up to v9; keep it working.
+      alias_method :random, :random_number
+
+      # Whole test card, not just a PAN: valid number, expiration 1-60 months out
+      # and a verification value of the size the brand declares.
+      #
+      #   card = CreditCardValidations::Factory.random_card(:amex)
+      #   card.valid?             # => true
+      #   card.verification_value # => "8812"
+      #
+      # Needs the brand to declare a :code size and raises
+      # CreditCardValidations::Error otherwise.
+      def random_card(brand = nil)
+        if brand.nil?
+          brand = Detector.brands.keys.select { |key| cvv_size(key) }.sample
+          raise Error.new('no registered brand declares a :code size') if brand.nil?
+        end
+
+        # Saying a brand has no :code option would imply it is registered.
+        raise Error.new('Unsupported brand') if Detector.brands[brand].nil?
+        raise Error.new("brand #{brand.inspect} has no :code option") if cvv_size(brand).nil?
+
+        # Card checks the CVV against the brand *detected* from the PAN, not the
+        # one we asked for, so the size has to come from there. Which brand wins
+        # an overlap is Detector's business, not the factory's.
+        number = random_number(brand)
+        detected = Detector.new(number).brand
+        size = cvv_size(detected)
+        if size.nil?
+          raise Error.new("the number generated for #{brand.inspect} detects as " \
+                          "#{detected.inspect}, which has no :code option")
+        end
+
+        # One month out at least: a card is live through the last day of its
+        # stated month, so zero would mean "about to expire".
+        expires_on = Date.today.next_month(rand(1..60))
+        Card.new(number: number,
+                 month: expires_on.month,
+                 year: expires_on.year,
+                 verification_value: Array.new(size) { rand(10) }.join)
+      end
+
+      def cvv_size(brand)
+        Detector.brands.dig(brand, :options, :code, :size)
       end
 
       def generate(rule)
-        number(rule[:prefixes].sample, rule[:length].sample, rule.fetch(:options, {})[:skip_luhn])
+        number(rule[:prefixes].sample, rule[:length].sample)
       end
 
-      def number(prefix, length, skip_luhn = false)
+      # Computes the check digit for skip_luhn brands too. That flag says
+      # detection *tolerates* a missing check digit, not that real cards lack
+      # one -- all 55 UnionPay PANs in the fixtures carry a valid one.
+      def number(prefix, length)
         number = prefix.dup
         1.upto(length - (prefix.length + 1)) do
-          number << "#{rand(9)}"
-        end
-        #if skip luhn
-        if skip_luhn
-          number += "#{rand(9)}"
-        else
-          number += last_digit(number).to_s
+          number << "#{rand(10)}"
         end
-        number
+        number + last_digit(number).to_s
       end
 
       #extracted from darkcoding-credit-card

data/lib/credit_card_validations/version.rb

@@ -1,3 +1,3 @@
 module CreditCardValidations
-  VERSION = '9.0.0'
+  VERSION = '10.0.0'
 end

data/lib/credit_card_validations.rb

@@ -18,6 +18,7 @@ module CreditCardValidations
   autoload :Mmi, 'credit_card_validations/mmi'
   autoload :Expiration, 'credit_card_validations/expiration'
   autoload :Card, 'credit_card_validations/card'
+  autoload :BrandSet, 'credit_card_validations/brand_set'
 
   attr_accessor :configuration
 
@@ -38,6 +39,15 @@ module CreditCardValidations
     Detector.add_brand(key, rules, options)
   end
 
+  # Detect against a fixed list of brands, named once instead of repeated at
+  # every call site. See BrandSet.
+  #
+  #   set = CreditCardValidations.with_brands(:visa, :mastercard)
+  #   set.detect('4111 1111 1111 1111').brand  #=> :visa
+  def self.with_brands(*keys)
+    BrandSet.new(keys.flatten)
+  end
+
   def self.source
     configuration.source || File.join(File.join(File.dirname(__FILE__)), 'data', 'brands.yaml')
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: credit_card_validations
 version: !ruby/object:Gem::Version
-  version: 9.0.0
+  version: 10.0.0
 platform: ruby
 authors:
 - Igor
@@ -15,28 +15,28 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '8.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '8.0'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '8.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '8.0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -106,6 +106,7 @@ files:
 - lib/active_model/credit_card_expiration_validator.rb
 - lib/active_model/credit_card_number_validator.rb
 - lib/credit_card_validations.rb
+- lib/credit_card_validations/brand_set.rb
 - lib/credit_card_validations/card.rb
 - lib/credit_card_validations/configuration.rb
 - lib/credit_card_validations/detector.rb
@@ -142,7 +143,7 @@ files:
 - lib/credit_card_validations/string.rb
 - lib/credit_card_validations/version.rb
 - lib/data/brands.yaml
-homepage: http://didww.github.io/credit_card_validations/
+homepage: https://github.com/didww/credit_card_validations
 licenses:
 - MIT
 metadata:
@@ -156,7 +157,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="