README revisions

Author: jondavidjohn

CONTRIBUTING.md

@@ -20,6 +20,14 @@ problem is before you spend your valuable time trying to fix it.
 Again, guard your time and effort.  Make sure that you don't spend a lot
 of time on an improvement without talking through it first.
 
+## Getting to work
+
+```sh
+npm install
+npm run build
+npm test
+```
+
 ## Pull Requests
 
 **Make sure to send pull requests to `develop`.**

README.md

@@ -7,29 +7,7 @@
 
 A general purpose library for building credit card forms, validating inputs, and formatting numbers.
 
-Available via **NPM** (Node or Browserify) and **Bower**.  Supports IE8+.
-
-For example, you can make a input act like a credit card field (with number formatting and length restriction):
-
-``` javascript
-var input = document.getElementById('ccnum');
-payform.cardNumberInput(input);
-```
-
-Then, when the payment form is submitted, you can validate the card number on the client-side (or server-side):
-
-``` javascript
-var valid = payform.validateCardNumber(input.value);
-
-if (!valid) {
-  alert('Your card is not valid!');
-  return false;
-}
-```
-
-You can find a [demo here](http://jondavidjohn.github.io/payform).
-
-Supported card types are:
+Supported card types:
 
 * Visa
 * MasterCard
@@ -43,11 +21,58 @@ Supported card types are:
 * Forbrugsforeningen
 * Dankort
 
-(Additional card types are supported by extending the [`payform.cards`](#payformcards) array.)
+(Custom card types are [supported](#custom-cards))
+
+Works in IE8+ and all other modern browsers.
+
+[**Demo**](http://jondavidjohn.github.io/payform)
+
+## Installation / Usage
+
+### NPM (Node and Browserify)
+
+```sh
+npm install payform --save
+```
+
+```javascript
+var payform = require('payform');
+
+// Validate a credit card number
+payform.validateCardNumber('4242 4242 4242 4242'); //=> true
+
+// Get card type from number
+payform.parseCardType('4242 4242 4242 4242'); //=> 'visa'
+```
+
+[Full API Doc](#api)
+
+### Direct script include / Bower
+
+Optionally via bower (or simply via download)
+```
+bower install payform --save
+```
+
+```html
+<script src="dist/payform.js"></script>
+<script>
+  // Validate a credit card number
+  payform.validateCardNumber('4242 4242 4242 4242'); //=> true
+
+  // Get card type from number
+  payform.parseCardType('4242 4242 4242 4242'); //=> 'visa'
+</script>
+```
+
+[Full API Doc](#api)
+
 
 ## API
 
-### payform.validateCardNumber(number)
+### General Formatting and Validation
+
+#### payform.validateCardNumber(number)
 
 Validates a card number:
 
@@ -61,7 +86,7 @@ Example:
 payform.validateCardNumber('4242 4242 4242 4242'); //=> true
 ```
 
-### payform.validateCardExpiry(month, year)
+#### payform.validateCardExpiry(month, year)
 
 Validates a card expiry:
 
@@ -77,7 +102,7 @@ payform.validateCardExpiry('05', '2015'); //=> true
 payform.validateCardExpiry('05', '05'); //=> false
 ```
 
-### payform.validateCardCVC(cvc, type)
+#### payform.validateCardCVC(cvc, type)
 
 Validates a card CVC:
 
@@ -93,7 +118,7 @@ payform.validateCardCVC('1234', 'amex'); //=> true
 payform.validateCardCVC('12344'); //=> false
 ```
 
-### payform.parseCardType(number)
+#### payform.parseCardType(number)
 
 Returns a card type. Either:
 
@@ -115,9 +140,10 @@ Example:
 
 ``` javascript
 payform.parseCardType('4242 4242 4242 4242'); //=> 'visa'
+payform.parseCardType('hello world?'); //=> null
 ```
 
-### payform.parseCardExpiry(string)
+#### payform.parseCardExpiry(string)
 
 Parses a credit card expiry in the form of MM/YYYY, returning an object containing the `month` and `year`. Shorthand years, such as `13` are also supported (and converted into the longhand, e.g. `2013`).
 
@@ -128,35 +154,11 @@ payform.parseCardExpiry('05 / 04'); //=> {month: 5, year: 2004}
 
 This function doesn't perform any validation of the month or year; use `payform.validateCardExpiry(month, year)` for that.
 
-### payform.cards
-
-Array of objects that describe valid card types. Each object should contain the following fields:
-
-``` javascript
-{
-  // Card type, as returned by payform.parseCardType.
-  type: 'mastercard',
-  // Regex used to identify the card type. For the best experience, this should be
-  // the shortest pattern that can guarantee the card is of a particular type.
-  pattern: /^5[0-5]/,
-  // Array of valid card number lengths.
-  length: [16],
-  // Array of valid card CVC lengths.
-  cvcLength: [3],
-  // Boolean indicating whether a valid card number should satisfy the Luhn check.
-  luhn: true,
-  // Regex used to format the card number. Each match is joined with a space.
-  format: /(\d{1,4})/g
-}
-```
-
-When identifying a card type, the array is traversed in order until the card number matches a `pattern`. For this reason, patterns with higher specificity should appear towards the beginning of the array.
-
-## Browser `<input>` Helpers
+### Browser `<input>` formatting helpers
 
 These methods are specifically for use in the browser to attach `<input>` formatters.
 
-### payform.cardNumberInput(input)
+#### payform.cardNumberInput(input)
 
 Formats card numbers:
 
@@ -172,7 +174,7 @@ var input = document.getElementById('ccnum');
 payform.cardNumberInput(input);
 ```
 
-### payform.expiryInput(input)
+#### payform.expiryInput(input)
 
 Formats card expiry:
 
@@ -183,11 +185,11 @@ Formats card expiry:
 Example:
 
 ``` javascript
-var input = document.getElementById('ccnum');
+var input = document.getElementById('expiry');
 payform.expiryInput(input);
 ```
 
-### payform.cvcInput(input)
+#### payform.cvcInput(input)
 
 Formats card CVC:
 
@@ -197,17 +199,39 @@ Formats card CVC:
 Example:
 
 ``` javascript
-var input = document.getElementById('ccnum');
+var input = document.getElementById('cvc');
 payform.cvcInput(input);
 ```
 
-## Building
+### Custom Cards
+
+#### payform.cards
 
-Run `npm run build`
+Array of objects that describe valid card types. Each object should contain the following fields:
+
+``` javascript
+{
+  // Card type, as returned by payform.parseCardType.
+  type: 'mastercard',
+  // Regex used to identify the card type. For the best experience, this should be
+  // the shortest pattern that can guarantee the card is of a particular type.
+  pattern: /^5[0-5]/,
+  // Array of valid card number lengths.
+  length: [16],
+  // Array of valid card CVC lengths.
+  cvcLength: [3],
+  // Boolean indicating whether a valid card number should satisfy the Luhn check.
+  luhn: true,
+  // Regex used to format the card number. Each match is joined with a space.
+  format: /(\d{1,4})/g
+}
+```
+
+When identifying a card type, the array is traversed in order until the card number matches a `pattern`. For this reason, patterns with higher specificity should appear towards the beginning of the array.
 
-## Running tests
+## Development
 
-Run `npm test`
+Please see [CONTRIBUTING.md](https://github.com/jondavidjohn/payform/blob/develop/CONTRIBUTING.md).
 
 ## Autocomplete recommendations