skyflow-js 1.3.0 → 1.7.0

package/CHANGELOG.md

@@ -1,6 +1,36 @@
 # Changelog
 
 All notable changes to this project will be documented in this file.
+## [1.7.0] - 2021-11-24
+### Added
+- `validations` option in `CollectElementInput` that takes an array of validation rules
+- `REGEX_MATCH_RULE`, `LENGTH_MATCH_RULE` & `ELEMENT_MATCH_RULE` Validation rules types
+- `PIN` Element type
+
+### Fixed
+- Card Number validation
+
+
+## [1.6.0] - 2021-11-16
+
+### Added
+- `enableCardIcon` option to configure Card Icon visibility
+- `INPUT_FIELD` Element type for custom UI elements
+- `unmount` method to reset collect element to initial state
+
+### Changed
+- New VISA Card Icon with updated Logo
+
+## [1.5.0] - 2021-11-10
+
+### Changed
+- Renamed invokeGateway to invokeConnection
+- Renamed gatewayURL to connectionURL
+## [1.4.0] - 2021-10-26
+
+### Added
+
+Detecting card type and displaying icon in the card number element
 
 ## [1.3.0] - 2021-10-19
 

package/README.md

@@ -8,7 +8,7 @@ Skyflow’s Javascript SDK can be used to securely collect, tokenize, and reveal
 - [**Initializing Skyflow.js**](#Initializing-Skyflowjs)
 - [**Securely collecting data client-side**](#Securely-collecting-data-client-side)
 - [**Securely revealing data client-side**](#Securely-revealing-data-client-side)
-- [**Securely invoking gateway client-side**](#Securely-invoking-gateway-client-side)
+- [**Securely invoking Connections client-side**](#Securely-invoking-Connections-client-side)
 
 ---
 
@@ -125,13 +125,14 @@ For `env` parameter, there are 2 accepted values in Skyflow.Env
 # Securely collecting data client-side
 -  [**Inserting data into the vault**](#inserting-data-into-the-vault)
 -  [**Using Skyflow Elements to collect data**](#using-skyflow-elements-to-collect-data)
+-  [**Using validations on Collect Elements**](#validations)
 -  [**Event Listener on Collect Elements**](#event-listener-on-collect-elements)
 ## Inserting data into the vault
 
 To insert data into the vault from the browser, use the `insert(records, options?)` method of the Skyflow client. The `records` parameter takes a JSON object of the records to be inserted in the below format. The `options` parameter takes a dictionary of optional parameters for the insertion. See below: 
 
 ```javascript
-var records = {
+const records = {
   "records": [
   	{
       table: "string", //table into which record should be inserted
@@ -144,7 +145,7 @@ var records = {
   ]
 }
 
-var options = {
+const options = {
   tokens: true  //indicates whether or not tokens should be returned for the inserted data. Defaults to 'true'  
 }
 
@@ -199,7 +200,7 @@ const container = skyflowClient.container(Skyflow.ContainerType.COLLECT)
 A Skyflow collect Element is defined as shown below: 
 
 ```javascript
-var collectElement =  {
+const collectElement =  {
    table: "string",             //optional, the table this data belongs to
    column: "string",            //optional, the column into which this data should be inserted
    type: Skyflow.ElementType,   //Skyflow.ElementType enum
@@ -209,11 +210,12 @@ var collectElement =  {
    label: "string",             //optional label for the form element
    placeholder: "string",       //optional placeholder for the form element
    altText: "string"            //optional string that acts as an initial value for the collect element
+   validations:[]               // optional array of validation rules
 }
 ```
 The `table` and `column` fields indicate which table and column in the vault the Element corresponds to. **Note**: 
 -  Use dot delimited strings to specify columns nested inside JSON fields (e.g. `address.street.line1`)
--  `table` and `column` are optional only if the element is being used in invokeGateway()
+-  `table` and `column` are optional only if the element is being used in invokeConnection()
 
 The `inputStyles` field accepts a style object which consists of CSS properties that should be applied to the form element in the following states:
 - `base`: all other variants inherit from these styles
@@ -272,16 +274,20 @@ errorTextStyles: {
 }
 ```
 
-Finally, the `type` field takes a Skyflow ElementType. Each type applies the appropriate regex and validations to the form element. There are currently 4 types:
+Finally, the `type` field takes a Skyflow ElementType. Each type applies the appropriate regex and validations to the form element. There are currently 5 types:
 - `CARDHOLDER_NAME`
 - `CARD_NUMBER`
 - `EXPIRATION_DATE`
 - `CVV`
+- `INPUT_FIELD`
+- `PIN`
+
+The `INPUT_FIELD` type is a custom UI element without any built-in validations.  See the section on [validations](#validations) for more information on validations.
 
 Once the Element object has been defined, add it to the container using the `create(element, options)` method as shown below. The `element` param takes a Skyflow Element object as defined above and the `options` parameter takes a dictionary of optional parameters as described below: 
 
 ```javascript
-var collectElement =  {
+const collectElement =  {
    table: "string",             //the table this data belongs to
    column: "string",            //the column into which this data should be inserted
    type: Skyflow.ElementType,   //Skyflow.ElementType enum
@@ -291,10 +297,12 @@ var collectElement =  {
    label: "string",             //optional label for the form element
    placeholder: "string",       //optional placeholder for the form element
    altText: "string"            //optional string that acts as an initial value for the collect element
+   validations:[]               // optional array of validation rules
 }
 
-var options = {
-  required: false  //indicates whether the field is marked as required. Defaults to 'false'
+const options = {
+  required: false,  //indicates whether the field is marked as required. Defaults to 'false'
+  enableCardIcon: true // indicates whether card icon should be enabled (only for CARD_NUMBER type Element)
 }
 
 const element = container.create(collectElement, options)
@@ -322,7 +330,10 @@ Now, when the `mount(domElement)` method of the Element is called, the Element w
 ```javascript
 element.mount("#cardNumber")
 ```
-
+you can use the `unmount` method to reset any collect element to it's initial state.
+```javascript
+element.unmount();
+```
 
 ### Step 4: Collect data from Elements
 
@@ -332,7 +343,7 @@ When the form is ready to be submitted, call the `collect(options?)` method on t
 - `additionalFields`: Non-PCI elements data to be inserted into the vault which should be in the `records` object format as described in the above [Inserting data into vault](#inserting-data-into-the-vault) section.
 
 ```javascript
-var options = {
+const options = {
   tokens: true  //optional, indicates whether tokens for the collected data should be returned. Defaults to 'true'
   additionalFields: {  
     records: [
@@ -421,7 +432,126 @@ container.collect({
 }
 ```
 
+### Validations
+
+Skyflow-JS provides two types of validations on Collect Elements
+
+#### 1. Default Validations:
+Every Collect Element except of type `INPUT_FIELD` has a set of default validations listed below:
+- `CARD_NUMBER`: Card number validation with checkSum algorithm(Luhn algorithm), available card lengths for defined card types
+- `CARD_HOLDER_NAME`: Name should be 2 or more symbols, valid characters should match pattern -  `^([a-zA-Z\\ \\,\\.\\-\\']{2,})$`
+- `CVV`: Card CVV can have 3-4 digits
+- `EXPIRATION_DATE`: Any date starting from current month. By default valid expiration date should be in short year format - `MM/YYYY`
+- `PIN`: Can have 4-12 digits
+
+#### 2. Custom Validations:
+Custom validations can be added to any element which will be checked after the default validations have passed. The following Custom validation rules are currently supported:
+- `REGEX_MATCH_RULE`: You can use this rule to specify any Regular Expression to be matched with the input field value
+
+```javascript
+const regexMatchRule = {
+  type: Skyflow.ValidationRuleType.REGEX_MATCH_RULE,
+  params: {
+    regex: RegExp,
+    error: string // optional, default error is "VALIDATION FAILED"
+  }
+}
+```
+
+- `LENGTH_MATCH_RULE`: You can use this rule to set the minimum and maximum permissible length of the input field value
+
+```javascript
+const lengthMatchRule = {
+  type: Skyflow.ValidationRuleType.LENGTH_MATCH_RULE,
+  params: {
+    min : number, // optional
+    max : number, // optional 
+    error: string // optional, default error is "VALIDATION FAILED"
+  }
+}
+```
+
+- `ELEMENT_VALUE_MATCH_RULE`: You can use this rule to match the value of one element with another element
+
+```javascript
+const elementValueMatchRule = {
+  type: Skyflow.ValidationRuleType.ELEMENT_VALUE_MATCH_RULE,
+  params: {
+    element: CollectElement,
+    error: string // optional, default error is "VALIDATION FAILED"
+  }
+}
+```
+
+The Sample code snippet for using custom validations:
+
+```javascript
+/*
+  A simple example that illustrates custom validations.
+  Adding REGEX_MATCH_RULE , LENGTH_MATCH_RULE to collect element.
+*/
+
+// this rule allows 1 or more alphabets
+const alphabetsOnlyRegexRule = {
+  type: Skyflow.ValidationRuleType.REGEX_MATCH_RULE,
+  params:{
+    regex: /^[A-Za-z]+$/,
+    error: "Only alphabets are allowed"
+  }
+}; 
+
+// this rule allows input length between 4 and 6 characters
+const lengthRule = {
+  type: Skyflow.ValidationRuleType.LENGTH_MATCH_RULE,
+  params:{
+    min: 4,
+    max: 6,
+    error: "Must be between 4 and 6 alphabets"
+  }
+}; 
+
+ const cardHolderNameElement = collectContainer.create({
+      table: "pii_fields",
+      column: "first_name",
+      ...collectStylesOptions,
+      label: "Card Holder Name",
+      placeholder: "cardholder name",
+      type: Skyflow.ElementType.INPUT_FIELD,
+      validations: [alphabetsOnlyRegexRule, lengthRule]
+    });
+
+/*
+  Reset PIN - A simple example that illustrates custom validations.
+  The below code shows an example of ELEMENT_VALUE_MATCH_RULE
+*/
+
+// for the PIN element
+const pinElement = collectContainer.create({
+  label: "PIN",
+  placeholder: "****",
+  type: Skyflow.ElementType.PIN,
+});
+
+// this rule allows to match the value with pinElement
+let elementMatchRule = {
+  type: Skyflow.ValidationRuleType.ELEMENT_VALUE_MATCH_RULE,
+  params:{
+    element: pinElement,
+    error: "PIN doesn't match"
+  }
+}
+const confirmPinElement = collectContainer.create({
+  label: "Confirm PIN",
+  placeholder: "****",
+  type: Skyflow.ElementType.PIN,
+  validations: [elementMatchRule]
+});
 
+// mount elements on screen - errors will be shown if any of the validaitons fail
+pinElement.mount("#collectPIN");
+confirmPinElement.mount("#collectConfirmPIN");
+
+```
 ### Event Listener on Collect Elements
 
 
@@ -526,7 +656,7 @@ For non-PCI use-cases, retrieving data from the vault and revealing it in the br
     For retrieving using tokens, use the `detokenize(records)` method. The records parameter takes a JSON object that contains `records` to be fetched as shown below.
 
 ```javascript
-var records = {
+const records = {
   "records": [
       {
         token: "string",                    // token for the record to be fetched
@@ -645,7 +775,7 @@ const container = skyflowClient.container(Skyflow.ContainerType.REVEAL)
 Then define a Skyflow Element to reveal data as shown below. 
 
 ```javascript
-var revealElement = {
+const revealElement = {
   token: "string",                    //optional, token of the data being revealed 
   inputStyles: {},                    //optional styles to be applied to the element
   labelStyles: {},                    //optional, styles to be applied to the label of the reveal element
@@ -655,7 +785,7 @@ var revealElement = {
 }
 ```
 `Note`: 
-- `token` is optional only if it is being used in invokeGateway()
+- `token` is optional only if it is being used in invokeConnection()
 
 The `inputStyles`, `labelStyles` and  `errorTextStyles` parameters accepts a styles object as described in the [previous section](#step-2-create-a-collect-element) for collecting data but only a single variant is available i.e. base. 
 
@@ -693,7 +823,7 @@ errorTextStyles: {
 Once you've defined a Skyflow Element, you can use the `create(element)` method of the container to create the Element as shown below: 
 
 ```javascript
-const element = container.create(revealElement, options={})
+const element = container.create(revealElement)
 ```
 
 ### Step 3: Mount Elements to the DOM
@@ -792,12 +922,12 @@ The response below shows that some tokens assigned to the reveal elements get re
 }
 ```
 
-# Securely invoking gateway client-side
-Using Skyflow gateway, end-user applications can integrate checkout/card issuance flow without any of their apps/systems touching the PCI compliant fields like cvv, card number. To invoke gateway, use the `invokeGateway(gatewayConfig)` method of the Skyflow client.
+# Securely invoking Connections client-side
+Using Skyflow Connections, end-user applications can integrate checkout/card issuance flow without any of their apps/systems touching the PCI compliant fields like cvv, card number. To invoke Connections, use the `invokeConnection(connectionConfig)` method of the Skyflow client.
 
 ```javascript
-const gatewayConfig = {
-  gatewayURL: string, // gateway url recevied when creating a skyflow gateway integration
+const connectionConfig = {
+  connectionURL: string, // connection url recevied when creating a skyflow Connection integration
   methodName: Skyflow.RequestMethod,
   pathParams: any,	// optional
   queryParams: any,	// optional
@@ -806,7 +936,7 @@ const gatewayConfig = {
   responseBody: any	// optional
 }
 
-const response =  skyflowClient.invokeGateway(gatewayConfig);
+const response =  skyflowClient.invokeConnection(connectionConfig);
 ```
 `methodName` supports the following methods:
 
@@ -816,14 +946,14 @@ const response =  skyflowClient.invokeGateway(gatewayConfig);
 - PATCH
 - DELETE
 
-**pathParams, queryParams, requestHeader, requestBody** are the JSON objects that will be sent through the gateway integration url.
+**pathParams, queryParams, requestHeader, requestBody** are the JSON objects that will be sent through the Connection integration url.
 
 The values in the above parameters can contain collect elements, reveal elements or actual values. When elements are provided inplace of values, they get replaced with the value entered in the collect elements or value present in the reveal elements
 
 **responseBody**:  
 It is a JSON object that specifies where to render the response in the UI. The values in the responseBody can contain collect elements or reveal elements. 
 
-Sample use-cases on using invokeGateway():
+Sample use-cases on using invokeConnection():
 
 ###  Sample use-case 1:
 
@@ -852,8 +982,8 @@ const cvvElement = collectContainer.create({
 cvvElement.mount("#cvv")
 
 // step 4
-const gatewayConfig = { 
-  gatewayURL: "https://area51.gateway.skyflow.com/v1/gateway/inboundRoutes/abc-1213/v2/pay”,
+const connectionConfig = { 
+  connectionURL: <connection_url>,
   methodName: Skyflow.RequestMethod.POST,
   requestBody: {
    card_number: cardNumberElement, //it can be skyflow element(collect or reveal) or actual value
@@ -861,7 +991,7 @@ const gatewayConfig = {
   }
 }
 
-const response =  skyflowClient.invokeGateway(gatewayConfig);
+const response =  skyflowClient.invokeConnection(connectionConfig);
 ```
 
 Sample Response:
@@ -875,7 +1005,7 @@ In the above example,  CVV is being collected from the user input at the time of
 
 `Note:`  
 - card_number can be either container element or plain text value (tokens or actual value)
-- `table` and `column` names are not required for creating collect element, if it is used for invokeGateway method, since they will not be stored in the vault
+- `table` and `column` names are not required for creating collect element, if it is used for invokeConnection method, since they will not be stored in the vault
 
  ### Sample use-case 2:
  
@@ -904,8 +1034,8 @@ const expiryDateElement = collectContainer.create({
 expiryDateElement.mount("#expirationDate")
 
 //step 4
-const gatewayConfig = { 
-  gatewayURL: "https://area51.gateway.skyflow.com/v1/gateway/inboundRoutes/abc-1213/cards/{card_number}/cvv2generation",
+const connectionConfig = { 
+  connectionURL: <connection_url>,
   methodName: Skyflow.RequestMethod.POST,
   pathParams: {
      card_number: "0905-8672-0773-0628"	//it can be skyflow element(collect/reveal) or token or actual value
@@ -915,13 +1045,13 @@ const gatewayConfig = {
  },
  responseBody: {
      resource: {
-         cvv2: cvvElement   // pass the element where the cvv response from the gateway will be mounted
+         cvv2: cvvElement   // pass the element where the cvv response from the Connection will be mounted
        }
      }  
    }
 }
 
-const response = skyflowClient.invokeGateway(gatewayConfig);
+const response = skyflowClient.invokeConnection(connectionConfig);
 ```
 
 Sample Response:
@@ -933,5 +1063,5 @@ Sample Response:
 ```
 
 `Note`:
-- `token` is optional for creating reveal element, if it is used for invokeGateway
-- responseBody contains collect or reveal elements to render the response from the gateway on UI 
+- `token` is optional for creating reveal element, if it is used for invokeConnection
+- responseBody contains collect or reveal elements to render the response from the Connection on UI