npm package: @ilkli/fields
Description: *Fields* provide a hosted solution for collecting Credit Card data, reducing your PCI scope and requirements.  Fields can be styled to match your current look and feel while actually handling sensitive info outside your site.
Author: Josh Pomazal
Latest version: 1.0.2

# Fields by ilkli
*Fields* provide a hosted solution for collecting Credit Card data, reducing your PCI scope and requirements.  Fields can be styled to match your current look and feel while actually handling sensitive info outside your site.

## How it works?
![Fields Demo](https://code.ilkli.com/fields/ilkli_demo.png)

*Fields* creates an `<iframe>` sourced by a ilkli hosted page that renders the input field you requested. When you submit your form, you can request a token from ilkli or an authorization.

**Note**: The diagram is truncated as we actually send credit card info to a trusted third-party gateway instead of to ilkli servers, however ilkli does host the forms.


## Installation
The preferred method is to use NPM to include it into your client side code.

```bash
npm i --save @ilkli/fields
```

You can also include the script directly into your HTML.

```html
<script src="https://code.ilkli.com/fields/fields.v1.js"></script>
```


## Usage
In your HTML:
```html
    <form id="form">
      <label>Some Field: <input type="text" name="field"></label>
      <label>CC #: <div id="cc-number"></div></label>
      <label>CC Exp: <div id="cc-exp"></div></label>
      <label>CC CVV: <div id="cc-cvv"></div></label>
      <input type="hidden" id="cc-token" name="cc-token">
      <button type="submit">Submit</button>
    </form>
```

In your JavaScript:

```javascript
    // Create your ilkli object
    const ilkli = new Ilkli({
        apiKey: MY_ISOLATE_APP_AUTH_TOKEN,
        merchantMatch: MY_MERCHANT_IDENTIFIER,
        //or
        merchantId: MY_MERCHANT_ID
    })
    // Shared styles for fields
    const style = {
                  lineHeight: '30px',
                  borderRadius: '5px',
                  borderWidth: '1px',
                  borderColor: '#DDD',
                  padding: '0 10px'
              }
    ilkli.createField(document.getElementById('cc-number'), {style: style, type: 'number'})
    ilkli.createField(document.getElementById('cc-exp'), {style: style, type: 'ex'})
    ilkli.createField(document.getElementById('cc-cvv'), {style: style, type: 'cvv'})

    const form = document.getElementById('form')

    form.addEventListener('submit', e => {
        e.preventDefault()
        //if you want to use a token
        // myCustomerData() is your function to gather customer details, look at API section for more.
        ilkli.tokenize(myCustomerData()).then(token => {
          document.getElementById('cc-token').value = token
          //do the rest of your form
          form.submit()
        }).catch(err =>{
          //handle error
        })
        //OR if you want to start a transaction, required to utilize CVV codes
        ilkli.authorize(myOrderTotal, myCustomerData())
        .then(transactionRef => {
          //You'll use this to call "capture" on the server side and complete the transaction.
          document.getElementById('cc-trans-id').value = transactionRef
          //do the rest of your form
          form.submit()
        }).catch(err =>{
          //handle error
        })
        return false
    })    

```

## Styling
You may use any of the following style properties.  The properties are filtered using RegExp to make sure they are clean and valid.

```javascript
    const ALLOWED_STYLES = {
        fontFamily: /^[a-z\-"',]+$/i,
        fontSize: /^(\d+(%|px|em|rem)?\s*)+$/,
        fontWeight:/^[0-9a-z]+$/,
        width: /^(\d+(%|px|em|rem)?\s*)+$/,
        height: /^(\d+(%|px|em|rem)?\s*)+$/,
        lineHeight: /^(\d+(%|px|em|rem)?\s*)+$/,
        color: /^([a-z-]+|#[a-f0-9]{6}|#[a-f0-9]{3}|rgb\((\d{1,3}),\s*(\d{1,3}),\s*(\d{1,3})\)|rgba\((\d{1,3}),\s*(\d{1,3}),\s*(\d{1,3}),\s*(\d*(?:\.\d+)?)\))$/i,
        backgroundColor: /^([a-z-]+|#[a-f0-9]{6}|#[a-f0-9]{3}|rgb\((\d{1,3}),\s*(\d{1,3}),\s*(\d{1,3})\)|rgba\((\d{1,3}),\s*(\d{1,3}),\s*(\d{1,3}),\s*(\d*(?:\.\d+)?)\))$/i,
        borderStyle: /^(none|hidden|dotted|dashed|solid|double|groove|ridge|inset|outset|initial|inherit)$/i,
        borderRadius: /^(\d+(%|px|em|rem)?\s*)+$/,
        borderWidth: /^(\d+(%|px|em|rem)?\s*)+$/,
        borderColor: /^([a-z-]+|#[a-f0-9]{6}|#[a-f0-9]{3}|rgb\((\d{1,3}),\s*(\d{1,3}),\s*(\d{1,3})\)|rgba\((\d{1,3}),\s*(\d{1,3}),\s*(\d{1,3}),\s*(\d*(?:\.\d+)?)\))$/i,
        outlineStyle: /^(none|hidden|dotted|dashed|solid|double|groove|ridge|inset|outset|initial|inherit)$/i,
        outlineWidth: /^(\d+(%|px|em|rem)?\s*)+$/,
        outlineColor: /^([a-z-]+|#[a-f0-9]{6}|#[a-f0-9]{3}|rgb\((\d{1,3}),\s*(\d{1,3}),\s*(\d{1,3})\)|rgba\((\d{1,3}),\s*(\d{1,3}),\s*(\d{1,3}),\s*(\d*(?:\.\d+)?)\))$/i,
        padding: /^(\d+(%|px|em|rem)?\s*)+$/,
        margin: /^(\d+(%|px|em|rem)?\s*)+$/
    }
```

## API
<a name="Ilkli"></a>

## Ilkli
Primary class for interacting with the Fields API

**Kind**: global class  

* [Ilkli](#Ilkli)
    * [new Ilkli(options)](#new_Ilkli_new)
    * [.on(event, listener)](#Ilkli+on) ⇒ [<code>Ilkli</code>](#Ilkli)
    * [.createField(element, config)](#Ilkli+createField) ⇒ <code>Field</code>
    * [.tokenize([info])](#Ilkli+tokenize) ⇒ <code>Promise.&lt;tokenString, Error&gt;</code>
    * [.authorize(amount, [info])](#Ilkli+authorize) ⇒ <code>Promise.&lt;transactionRefString, Error&gt;</code>

<a name="new_Ilkli_new"></a>

### new Ilkli(options)

| Param | Type | Description |
| --- | --- | --- |
| options | <code>object</code> |  |
| options.apiKey | <code>string</code> | Your Isolate App Token |
| [options.merchantId] | <code>string</code> | Your Isolate Merchant ID |
| [options.merchantMatch] | <code>string</code> | A string to match using the "identifiers" on your Isolate Merchant |

<a name="Ilkli+on"></a>

### ilkli.on(event, listener) ⇒ [<code>Ilkli</code>](#Ilkli)
Add an event listener. The events are:
  token: (token)=>
  auth: (transactionId)=>
  error: (error)=>

**Kind**: instance method of [<code>Ilkli</code>](#Ilkli)  

| Param | Type | Description |
| --- | --- | --- |
| event | <code>string</code> | Name of the event |
| listener | <code>function</code> | The listener function |

<a name="Ilkli+createField"></a>

### ilkli.createField(element, config) ⇒ <code>Field</code>
This creates a Field inside the container element.

**Kind**: instance method of [<code>Ilkli</code>](#Ilkli)  

| Param | Type | Description |
| --- | --- | --- |
| element | <code>HTMLElement</code> | The container element |
| config | <code>object</code> | The configuration object |
| config.type | <code>string</code> | The field type: **number**, **cvv** or **ex** |
| [config.style] | <code>object</code> | Style object, see style guide |

<a name="Ilkli+tokenize"></a>

### ilkli.tokenize([info]) ⇒ <code>Promise.&lt;tokenString, Error&gt;</code>
This starts a tokenization process.

**Kind**: instance method of [<code>Ilkli</code>](#Ilkli)  

| Param | Type | Description |
| --- | --- | --- |
| [info] | <code>object</code> | Optional values to add to the token. |
| [info.customerName] | <code>string</code> | The billing name of the customer |
| [info.address1] | <code>string</code> | Billing address line |
| [info.city] | <code>string</code> | Billing city |
| [info.state] | <code>string</code> | Billing state, provence or administrative region |
| [info.zip] | <code>string</code> | Billing zip or post code |
| [info.country] | <code>string</code> | Billing country code |

<a name="Ilkli+authorize"></a>

### ilkli.authorize(amount, [info]) ⇒ <code>Promise.&lt;transactionRefString, Error&gt;</code>
**Kind**: instance method of [<code>Ilkli</code>](#Ilkli)  

| Param | Type | Description |
| --- | --- | --- |
| amount | <code>number</code> | The authorization amount, you will still use capture for the final amount on the     server-side. |
| [info] | <code>object</code> | Additional info to attach to the CC auth, it is recommended to include all of these. |
| [info.customerName] | <code>string</code> | The billing name of the customer |
| [info.address1] | <code>string</code> | Billing address line |
| [info.city] | <code>string</code> | Billing city |
| [info.state] | <code>string</code> | Billing state, provence or administrative region |
| [info.zip] | <code>string</code> | Billing zip or post code |
| [info.country] | <code>string</code> | Billing country code |