credit_card_validations 8.1.0 → 10.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ea48b31cccd9e050dd0e59cdd71bb784cf319d355dfa2eb0a185635308b1b81
-  data.tar.gz: 3c0358bce72eeb6f265ffb0130dc3a5a843dbf326ef989c118d827c025b8e0c3
+  metadata.gz: b16ea3c34b40baacacb68877a244e7c30710323e7949b6b626e5b327156198aa
+  data.tar.gz: 596b070c9b31cefa5aacde43cff367ac609237ccea747cd20e9e2e8c9f6a95ac
 SHA512:
-  metadata.gz: 62586d60302f937ec7f47a98440d89767fba557506a5568733e498e2c41d491d5d8f283923590808abc4f1ab3ebe3466dcadb8fbd4a21b721d07337ea4e34133
-  data.tar.gz: 366c5f5239778f08035b207b9d1e88e2f3c5f747913b3d86c79b1555fd571a640d16eca7121e78b62fe93f87298a05b9bb9161c7acfe1dcdad2e6a6b100662b2
+  metadata.gz: 7bd5c35081bc1085c11232c7c13d14befed6edb45b7b4faca8ac27b8b0b39b5bacd61e3ed8e4ecda977c34e50b0546f2904883602c12ea35a7d82adc942d1260
+  data.tar.gz: 9b8df4c6df565cf26f7084683a0eb68bc40e2dfbf06b86131103f92360b681772aa938d72e7389821463789bdf90bfec95713b2aef82c5cec8a7cf4540dc7670

data/README.md

@@ -5,9 +5,9 @@
 ![Coverage](https://didww.github.io/credit_card_validations/badge.svg)
 
 
-Gem adds validator  to check whether or not a given number actually falls within the ranges of possible numbers prior to performing such verification, and, as such, CreditCardValidations simply verifies that the credit card number provided is well-formed.
+Gem adds a validator to check whether a given number actually falls within the ranges of possible numbers prior to performing verification — `CreditCardValidations` verifies that the credit card number provided is well-formed.
 
-More info about card BIN numbers http://en.wikipedia.org/wiki/Bank_card_number
+More info about card BIN numbers: http://en.wikipedia.org/wiki/Bank_card_number
 
 ## Installation
 
@@ -29,158 +29,383 @@ Or install it yourself as:
 $ gem install credit_card_validations
 ```
 
-## Usage
+## Default brands
 
+These brands are detected out of the box. They are the international majors that most acquirers, gateways, and payment forms care about:
 
-The following issuing institutes are accepted:
-    
-|    Name   |    Key     | 
----------------------   | ------------| 
-[American Express](http://en.wikipedia.org/wiki/American_Express) | :amex
-[China UnionPay](http://en.wikipedia.org/wiki/China_UnionPay)    | :unionpay 
-[Dankort](http://en.wikipedia.org/wiki/Dankort)      | :dankort
-[Diners Club](http://en.wikipedia.org/wiki/Diners_Club_International)  | :diners   
-[Elo](https://pt.wikipedia.org/wiki/Elo_Participa%C3%A7%C3%B5es_S/A)      | :elo
-[Discover](http://en.wikipedia.org/wiki/Discover_Card) | :discover   
-[Hipercard](http://pt.wikipedia.org/wiki/Hipercard) | :hipercard  
-[JCB](http://en.wikipedia.org/wiki/Japan_Credit_Bureau)  | :jcb
-[Maestro](http://en.wikipedia.org/wiki/Maestro_%28debit_card%29)    | :maestro
-[MasterCard](http://en.wikipedia.org/wiki/MasterCard)  |   :mastercard
-[MIR](http://www.nspk.ru/en/cards-mir/)  |   :mir
-[Rupay](http://en.wikipedia.org/wiki/RuPay) |   :rupay 
-[Solo](http://en.wikipedia.org/wiki/Solo_(debit_card))     | :solo
-[Switch](http://en.wikipedia.org/wiki/Switch_(debit_card)) | :switch 
-[Visa](http://en.wikipedia.org/wiki/Visa_Inc.)      | :visa  
+|    Name   |    Key     |
+---------------------   | ------------|
+[American Express](http://en.wikipedia.org/wiki/American_Express) | `:amex`
+[China UnionPay](http://en.wikipedia.org/wiki/China_UnionPay) | `:unionpay`
+[Diners Club](http://en.wikipedia.org/wiki/Diners_Club_International) | `:diners`
+[Discover](http://en.wikipedia.org/wiki/Discover_Card) | `:discover`
+[JCB](http://en.wikipedia.org/wiki/Japan_Credit_Bureau) | `:jcb`
+[Maestro](http://en.wikipedia.org/wiki/Maestro_%28debit_card%29) | `:maestro`
+[MasterCard](http://en.wikipedia.org/wiki/MasterCard) | `:mastercard`
+[Visa](http://en.wikipedia.org/wiki/Visa_Inc.) | `:visa`
 
+## Opt-in plugins
 
+Everything else is detected only when its plugin is explicitly required. Plugins add no startup cost, no API surface, and no chance of misdetection to apps that don't accept the brand.
 
-The following are supported with plugins
+### Active regional and specialty networks
 
 |    Name   |    Key     |
 ---------------------   | ------------|
-[Cabal](https://en.wikipedia.org/wiki/Cabal_(debit_card)) | :cabal
-[DinaCard](https://en.wikipedia.org/wiki/DinaCard) | :dinacard
-[Diners Club US](http://en.wikipedia.org/wiki/Diners_Club_International#MasterCard_alliance)  | :diners_us
-[EnRoute](https://en.wikipedia.org/wiki/EnRoute_(credit_card)) | :en_route
-[Girocard](https://en.wikipedia.org/wiki/Girocard) | :girocard
-[Hiper](https://en.wikipedia.org/wiki/Itau_Unibanco) | :hiper
-[Humo](https://en.wikipedia.org/wiki/Humo_(payment_system)) | :humocard
-[Laser](https://en.wikipedia.org/wiki/Laser_%28debit_card%29)      | :laser
-[Troy](https://en.wikipedia.org/wiki/Troy_(payment_system)) | :troy
-[UATP](https://en.wikipedia.org/wiki/Universal_Air_Travel_Plan) | :uatp
-[Uzcard](https://en.wikipedia.org/wiki/Uzcard) | :uzcard
-[V Pay](https://en.wikipedia.org/wiki/V_Pay) | :vpay
-[Verve](https://en.wikipedia.org/wiki/Verve_(payment_card)) | :verve
-[Voyager](https://en.wikipedia.org/wiki/Voyager_card) | :voyager
+[Cabal](https://en.wikipedia.org/wiki/Cabal_(debit_card)) | `:cabal`
+[Carnet](https://en.wikipedia.org/wiki/Carnet_(card)) | `:carnet`
+[Cartes Bancaires](https://en.wikipedia.org/wiki/Cartes_Bancaires) | `:cartes_bancaires`
+[Dankort](http://en.wikipedia.org/wiki/Dankort) | `:dankort`
+[DinaCard](https://en.wikipedia.org/wiki/DinaCard) | `:dinacard`
+[Elo](https://pt.wikipedia.org/wiki/Elo_Participa%C3%A7%C3%B5es_S/A) | `:elo`
+[Girocard](https://en.wikipedia.org/wiki/Girocard) | `:girocard`
+[Hiper](https://en.wikipedia.org/wiki/Itau_Unibanco) | `:hiper`
+[Hipercard](http://pt.wikipedia.org/wiki/Hipercard) | `:hipercard`
+[Humo](https://en.wikipedia.org/wiki/Humo_(payment_system)) | `:humocard`
+[Mada](https://en.wikipedia.org/wiki/Mada_(payment_system)) | `:mada`
+[MIR](http://www.nspk.ru/en/cards-mir/) | `:mir`
+[Naranja](https://en.wikipedia.org/wiki/Tarjeta_Naranja) | `:naranja`
+[RuPay](http://en.wikipedia.org/wiki/RuPay) | `:rupay`
+[Troy](https://en.wikipedia.org/wiki/Troy_(payment_system)) | `:troy`
+[UATP](https://en.wikipedia.org/wiki/Universal_Air_Travel_Plan) | `:uatp`
+[Uzcard](https://en.wikipedia.org/wiki/Uzcard) | `:uzcard`
+[V Pay](https://en.wikipedia.org/wiki/V_Pay) | `:vpay`
+[Verve](https://en.wikipedia.org/wiki/Verve_(payment_card)) | `:verve`
+[Voyager](https://en.wikipedia.org/wiki/Voyager_card) | `:voyager`
+
+### Legacy / withdrawn networks
+
+|    Name   |    Key     | Status |
+---------------------   | ------------| ------|
+[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 |
+[Switch](https://en.wikipedia.org/wiki/Switch_(debit_card)) | `:switch` | Withdrawn 2002 |
+
+### Loading plugins
+
+```ruby
+# in an initializer or before first use
+require 'credit_card_validations/plugins/mir'
+require 'credit_card_validations/plugins/elo'
+require 'credit_card_validations/plugins/hipercard'
+# ... whichever brands the app actually accepts
+```
 
+## Migrating from v9.x → v10.0 (unreleased)
 
+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.
 
-### Examples using string monkey patch
+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
+```
+
+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
+
+- **`Hipercard` cleaned up.** Length changed from 19 to 16 (which is the issued length); legacy `637*` prefixes that actually belong to Hiper were dropped. If you used Hipercard before, your detection now matches the brand's real spec.
+- **`Discover` cleaned up.** Diners-only prefixes (`300-305, 3095, 36, 38, 39`) were dropped from Discover. Diners cards now correctly detect as `:diners` instead of `:discover`. Apps that branched on `:discover` for routing should branch on `[:diners, :discover]`.
+- **`Luhn.valid?` is now strict.** It accepts a digit-only string and returns `false` for `nil`, empty input, or any non-digit character. User-facing input handling moved into `Detector#initialize`, which strips whitespace and dashes before delegating.
+- **Brand YAML is loaded via `YAML.safe_load_file`.** Custom brand sources may need to declare `permitted_classes: [Symbol]` if they relied on extra Ruby objects.
+
+## Usage
+
+### String monkey patch
 
 ```ruby
 require 'credit_card_validations/string'
-'5274 5763 9425 9961'.credit_card_brand   #=> :mastercard
-'5274 5763 9425 9961'.credit_card_brand_name   #=> "MasterCard"
-'5274 5763 9425 9961'.valid_credit_card_brand?(:mastercard, :visa) #=> true
-'5274 5763 9425 9961'.valid_credit_card_brand?(:amex) #=> false
-'5274 5763 9425 9961'.valid_credit_card_brand?('MasterCard') #=> true
+'5274 5763 9425 9961'.credit_card_brand                                #=> :mastercard
+'5274 5763 9425 9961'.credit_card_brand_name                           #=> "MasterCard"
+'5274 5763 9425 9961'.valid_credit_card_brand?(:mastercard, :visa)     #=> true
+'5274 5763 9425 9961'.valid_credit_card_brand?(:amex)                  #=> false
+'5274 5763 9425 9961'.valid_credit_card_brand?('MasterCard')           #=> true
 ```
 
-### ActiveModel support
+### ActiveModel validators
 
-only for certain brands
+Restrict to a brand list:
 
 ```ruby
 class CreditCardModel
   attr_accessor :number
   include ActiveModel::Validations
-  validates :number, credit_card_number: {brands: [:amex, :maestro]}
+  validates :number, credit_card_number: { brands: [:amex, :maestro] }
 end
 ```
 
-for all known brands
+Accept any known brand:
 
 ```ruby
 validates :number, presence: true, credit_card_number: true
 ```
 
-### Examples using CreditCardValidations::Detector class
+### CVV validator
+
+CVV against a brand pulled from another attribute (the PAN):
+
+```ruby
+class Payment
+  include ActiveModel::Validations
+  attr_accessor :card_number, :cvv
+
+  validates :card_number, credit_card_number: true
+  validates :cvv,         credit_card_cvv: { brand_from: :card_number }
+end
+```
+
+CVV against a literal brand:
 
 ```ruby
-number = "4111111111111111"
+validates :cvv, credit_card_cvv: { brand: :amex }
+```
+
+### Expiration validator
+
+A single string attribute (`MM/YY`, `MM/YYYY`, `MMYY`, ...):
+
+```ruby
+validates :expiration, credit_card_expiration: true
+```
+
+Two separate fields (typical month + year dropdowns) — use the `Expiration` class in a `validate` block:
+
+```ruby
+class Payment
+  attr_accessor :exp_month, :exp_year
+
+  validate do
+    exp = CreditCardValidations::Expiration.new(exp_month, exp_year)
+    errors.add(:exp_month, :invalid) unless exp.valid?
+  end
+end
+```
+
+### `CreditCardValidations::Card`
+
+A composite model wrapping `Detector` and `Expiration` behind a single ActiveModel-aware object:
+
+```ruby
+card = CreditCardValidations::Card.new(
+  number: '4111 1111 1111 1111',
+  month: 12, year: 2027,
+  verification_value: '123',
+  name: 'John Smith'
+)
+card.valid?            # => true
+card.brand             # => :visa
+card.display_number    # => "************1111"
+card.last_digits       # => "1111"
+card.expired?          # => false
+card.formatted_number  # => "4111 1111 1111 1111"
+```
+
+### Using `Detector` directly
+
+```ruby
+number   = '4111111111111111'
 detector = CreditCardValidations::Detector.new(number)
-detector.brand #:visa
-detector.visa? #true
-detector.valid?(:mastercard,:maestro) #false
-detector.valid?(:visa, :mastercard) #true
-detector.issuer_category  #"Banking and financial"
+
+detector.brand                          # => :visa
+detector.visa?                          # => true
+detector.valid?(:mastercard, :maestro)  # => false
+detector.valid?(:visa, :mastercard)     # => true
+detector.issuer_category                # => "Banking and financial"
+detector.last4                          # => "1111"
+detector.masked                         # => "************1111"
+detector.formatted                      # => "4111 1111 1111 1111"
+detector.possible_brands                # => [:visa]   (during live input)
+detector.valid_cvv?('123')              # => true
 ```
 
-### Also You can add your own brand rules to detect other credit card brands/types
-passing name,length(integer/array of integers) and prefix(string/array of strings)
-Example
+### 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
-CreditCardValidations.add_brand(:voyager, {length: 15, prefixes: '86'})
-voyager_test_card_number = '869926275400212'
-CreditCardValidations::Detector.new(voyager_test_card_number).brand #:voyager
-CreditCardValidations::Detector.new(voyager_test_card_number).voyager? #true
+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           # => []
 ```
 
-### Remove brands also supported
+`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
-CreditCardValidations::Detector.delete_brand(:maestro)
+CreditCardValidations.add_brand(:voyager, { length: 15, prefixes: '86' })
+CreditCardValidations::Detector.new('869926275400212').voyager?  # => true
 ```
 
-### Check luhn
+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
-CreditCardValidations::Detector.new(@credit_card_number).valid_luhn?
-#or
-CreditCardValidations::Luhn.valid?(@credit_card_number)
+CreditCardValidations::Detector.delete_brand(:maestro)
 ```
 
-### Generate credit card numbers that pass validation
+### Luhn check
 
 ```ruby
-CreditCardValidations::Factory.random(:amex)
-# => "348051773827666"
-CreditCardValidations::Factory.random(:maestro)
-# => "6010430241237266856"
+CreditCardValidations::Detector.new(number).valid_luhn?
+# or, on a clean digit string:
+CreditCardValidations::Luhn.valid?(number)
 ```
 
-### Plugins
+### Generating test numbers and test cards
 
 ```ruby
-require 'credit_card_validations/plugins/en_route'
-require 'credit_card_validations/plugins/laser'
-require 'credit_card_validations/plugins/diners_us'
+CreditCardValidations::Factory.random_number(:visa)  #=> "4012888888881881"
 
-require 'credit_card_validations/plugins/cabal'
-require 'credit_card_validations/plugins/dinacard'
-require 'credit_card_validations/plugins/girocard'
-require 'credit_card_validations/plugins/hiper'
-require 'credit_card_validations/plugins/humocard'
-require 'credit_card_validations/plugins/troy'
-require 'credit_card_validations/plugins/uatp'
-require 'credit_card_validations/plugins/uzcard'
-require 'credit_card_validations/plugins/verve'
-require 'credit_card_validations/plugins/voyager'
-require 'credit_card_validations/plugins/vpay'
+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.
 
-### Configuration
+`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.
 
-In order to override default data source you can copy [original one](https://github.com/didww/credit_card_validations/blob/master/lib/data/brands.yaml) , change it and configure during rails initializer
+Called with no brand, `random_card` draws only among brands that declare a
+`:code`:
 
 ```ruby
- CreditCardValidations.configure do |config|
-      config.source = '/path/to/my_brands.yml'
- end
+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:
+
+```ruby
+CreditCardValidations.configure do |config|
+  config.source = '/path/to/my_brands.yml'
+end
+```
 
 ## Contributing
 
@@ -188,7 +413,4 @@ In order to override default data source you can copy [original one](https://git
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
-
-
-
+5. Open a Pull Request

data/lib/active_model/credit_card_cvv_validator.rb

@@ -0,0 +1,35 @@
+# == ActiveModel CreditCardCvvValidator
+#
+# Validates a card verification value (CVV / CVC / CID) against either a
+# brand passed explicitly, or a brand derived from another attribute.
+#
+#   class Payment
+#     include ActiveModel::Validations
+#     attr_accessor :card_number, :cvv
+#
+#     validates :cvv, credit_card_cvv: { brand_from: :card_number }
+#   end
+#
+#   class Payment
+#     validates :cvv, credit_card_cvv: { brand: :amex }
+#   end
+#
+module ActiveModel
+  module Validations
+    class CreditCardCvvValidator < EachValidator
+      def validate_each(record, attribute, value)
+        brand = resolve_brand(record)
+        return if brand && CreditCardValidations::Detector.valid_cvv?(value, brand)
+        record.errors.add(attribute, options[:message] || :invalid)
+      end
+
+      private
+
+      def resolve_brand(record)
+        return options[:brand] if options[:brand]
+        pan = record.public_send(options[:brand_from]).to_s if options[:brand_from]
+        CreditCardValidations::Detector.new(pan).brand if pan
+      end
+    end
+  end
+end

data/lib/active_model/credit_card_expiration_validator.rb

@@ -0,0 +1,26 @@
+# == ActiveModel CreditCardExpirationValidator
+#
+# Validates a card expiration date held in a single attribute as a parseable
+# string (MM/YY, MM/YYYY, MMYY, ...).
+#
+#   class Payment
+#     include ActiveModel::Validations
+#     attr_accessor :expiration
+#
+#     validates :expiration, credit_card_expiration: true
+#   end
+#
+# For forms with separate month + year fields, use the Expiration class
+# directly in a plain validate block (see README).
+#
+module ActiveModel
+  module Validations
+    class CreditCardExpirationValidator < EachValidator
+      def validate_each(record, attribute, value)
+        expiration = CreditCardValidations::Expiration.parse(value)
+        return if expiration && expiration.valid?
+        record.errors.add(attribute, options[:message] || :invalid)
+      end
+    end
+  end
+end

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