@gr4vy/secure-fields 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# v0.1.0 (Fri Aug 12 2022)
+
+#### 🚀 Enhancement
+
+- ci: add npm publish config [#22](https://github.com/gr4vy/secure-fields/pull/22) ([@douglaseggleton](https://github.com/douglaseggleton))
+
+#### 🐛 Bug Fix
+
+- ci: add npm release configuration [#16](https://github.com/gr4vy/secure-fields/pull/16) ([@douglaseggleton](https://github.com/douglaseggleton))
+- fix: removing share constant [#15](https://github.com/gr4vy/secure-fields/pull/15) ([@douglaseggleton](https://github.com/douglaseggleton))
+- feat: add field [#13](https://github.com/gr4vy/secure-fields/pull/13) ([@luca-gr4vy](https://github.com/luca-gr4vy))
+- Ta 2262 secure fields frame [#8](https://github.com/gr4vy/secure-fields/pull/8) ([@douglaseggleton](https://github.com/douglaseggleton))
+- feat: utility getters [#4](https://github.com/gr4vy/secure-fields/pull/4) ([@luca-gr4vy](https://github.com/luca-gr4vy))
+- feat: main events class getter [#3](https://github.com/gr4vy/secure-fields/pull/3) ([@luca-gr4vy](https://github.com/luca-gr4vy))
+- task: add base test / lint / scan CI jobs [#2](https://github.com/gr4vy/secure-fields/pull/2) ([@luca-gr4vy](https://github.com/luca-gr4vy))
+- feat: project setup [#1](https://github.com/gr4vy/secure-fields/pull/1) ([@luca-gr4vy](https://github.com/luca-gr4vy))
+
+#### Authors: 2
+
+- Douglas Eggleton ([@douglaseggleton](https://github.com/douglaseggleton))
+- Luca Allievi ([@luca-gr4vy](https://github.com/luca-gr4vy))
+
+---
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Gr4vy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,199 @@
+# Secure Fields
+
+![NPM Version](https://img.shields.io/npm/v/@gr4vy/secure-fields?color=green)
+[![GitHub license](https://img.shields.io/github/license/Naereen/StrapDown.js.svg)](https://github.com/gr4vy/secure-fields/blob/main/LICENSE)
+
+Load Secure Fields in your Node app.
+
+Use [`@gr4vy/secure-fields-react`](../secure-fields-react) in a React application or [`@gr4vy/secure-fields-cdn`](../secure-fields-cdn) in a regular web application.
+
+## Usage
+
+Via the command line, install this package as follows.
+
+```bash
+npm install @gr4vy/secure-fields --save-prod
+# yarn add @gr4vy/secure-fields --save
+```
+
+## Get started
+
+To use Secure Fields, you first need a form with placeholder elements that will be replaced by secure fields (`iframe`s), each with a specific `id` attribute. Get a session id by making a request to the Session API, passing one or more accepted `targetOrigins` (urls that host your form).
+
+```html
+<form id="cc-form">
+  <label for="cc-holder-name">Name</label>
+  <input
+    id="cc-holder-name"
+    class="form-control"
+    placeholder="Name on the card"
+  />
+  <label for="cc-number">Card Number</label>
+  <input id="cc-number" class="form-control" />
+  <label for="cc-security-code">Security Code</label>
+  <input id="cc-security-code" class="form-control" />
+  <label for="cc-expiration-date">Expiration date</label>
+  <input id="cc-expiration-date" class="form-control" />
+  <button id="pay-button">Pay now</button>
+</form>
+```
+
+Import the library and call the class constructor to create an instance. Pass the session id returned by the Session API.
+
+```js
+const { SecureFields } = require(`@gr4vy/secure-fields`)
+// import { SecureFields } from (`@gr4vy/secure-fields`)
+
+const secureFields = new SecureFields([SESSION_ID])
+
+> **Note**: Replace `[SESSION_ID]` with the session id.
+```
+
+Call methods to add fields, set flags, and attach event listeners. Call `submit` to capture the data and send it to Gr4vy, passing an optional callback to handle other UI interactions.
+
+```js
+secureFields.setDebug(true)
+
+const cardNumber = secureFields.addCardNumber('#cc-number', {
+  placeholder: 'Enter card number',
+  styles: {
+    base: {
+      color: 'black',
+      fontSize: '18px',
+    },
+  },
+})
+
+secureFields.addEventListener(
+  SecureFields.Events.CARD_VAULT_SUCCESS,
+  (data) => {
+    console.log(data) // data.card.number, data.card.type...
+  }
+)
+
+const form = document.getElementById('cc-form')
+form.addEventListener('submit', (e) => {
+  e.preventDefault()
+  secureFields.submit((err, data) => {
+    if (err) {
+      throw new Error(err)
+    }
+
+    console.log(`Got tokenized data`, data)
+  })
+})
+```
+
+### Styles
+
+The outer styling (any containers around fields, etc) is completely in the your control. SecureFields will also generate a set of so-called managed CSS classes and attach them to the outer iframe containers, so you can target them with your own CSS. Finally, an object of CSS rules can be passed to the `addField` options to style elements inside the iframe(s).
+
+```
+const styles = {
+  // Default styles
+  base: { ... },
+  // Rules applied when the field has its value autofilled by a browser / extension
+  autofill: { ... },
+  // Rules applied when the field is hovered
+  hover: { ... },
+  // Rules applied when the field is focused
+  focus: { ... },
+  // Rules applied when the field is disabled
+  disabled: { ... },
+  // Rules applied when the field is valid
+  valid: { ... },
+  // Rules applied when the field is invalid
+  invalid: { ... },
+  // Rules applied to the field placeholder
+  placeholder: { ... },
+}
+```
+
+We only allow the following CSS properties:
+
+```
+backgroundColor
+caretColor
+color
+colorScheme
+cursor
+font
+fontFamily
+fontFeatureSettings
+fontKerning
+fontSize
+fontSizeAdjust
+fontStretch
+fontStyle
+fontVariant
+fontVariantAlternates
+fontVariantCaps
+fontVariantEastAsian
+fontVariantLigatures
+fontVariantNumeric
+fontVariationSettings
+fontWeight
+letterSpacing
+lineHeight
+opacity
+textAlign
+textShadow
+textRendering
+transition
+MozOsxFontSmoothing
+WebkitFontSmoothing
+```
+
+Here are the managed classes generated by Secure Fields:
+
+```
+/* Applied to the (form) container */
+.secure-fields {}
+/* Applied to each field */
+.secure-fields__field {}
+/* Applied to a disabled field */
+.secure-fields__field--disabled {}
+/* Applied to a focused field */
+.secure-fields__field--focused {}
+/* Applied to a valid field */
+.secure-fields__field--valid {}
+/* Applied to an invalid field */
+.secure-fields__field--invalid {}
+/* Applied to a autofilled field */
+.secure-fields__field--autofilled {}
+```
+
+### Events
+
+You can call the `addEventListener` on a Secure Fields instance or on fields, passing one of the supported events and a callback. Here are the events you can listen to on an instance:
+
+| Name                 | Description                                                     |
+| -------------------- | --------------------------------------------------------------- |
+| `CARD_VAULT_SUCCESS` | Triggered when the card is successfully vaulted.                |
+| `CARD_VAULT_FAILURE` | Triggered when the card vaulting fails.                         |
+| `READY`              | Triggered when the SecureFields is loaded and ready to be used. |
+
+For actual fields, you can subscribe to default events and have access to more useful data (bin, validation status, etc). For example, the change event on a card number input might include `{ valid: true, complete: true, ... }`. You can expect to be able to listen to events such as `blur`, `focus`, `change`, `input`...
+
+### API reference
+
+#### Getters
+
+| Name      | Description                                                                     |
+| --------- | ------------------------------------------------------------------------------- |
+| `Events`  | Gives access to the supported events. <br /><br />`SecureFields.Events.READY`   |
+| `version` | Returns the current version of the instance. <br /><br />`SecureFields.version` |
+
+#### Methods
+
+| Name                     | Description                                                                                                                                                                                                                                                                                                                                                        |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `constructor`            | Instantiates SecureFields with a session id. <br /><br />`new SecureFields('...')`                                                                                                                                                                                                                                                                                 |
+| `addCardNumberField`     | Injects a secure field of type `cardNumber`. <br /><br />`secureFields.addCardNumberField('#cc-number', { placeholder: 'Enter card number', ... })`                                                                                                                                                                                                                |
+| `addSecurityCodeField`   | Injects a secure field of type `securityCode`. <br /><br />`secureFields.addSecurityCodeField('#cc-security-code', { placeholder: 'Enter security code', ... })`                                                                                                                                                                                                   |
+| `addExpirationDateField` | Injects a secure field of type `expirationDate`. <br /><br />`secureFields.addExpirationDateField('#cc-expiration-date', { placeholder: 'Enter expiration date', ... })`                                                                                                                                                                                           |
+| `addEventListener`       | Attaches an event handler to the SecureFields instance or to a secure field in order to listen to specific events. Requires one of the events supported and a callback. <br /><br />`secureFields.addEventListener(SecureFields.Events.READY, (data) => { ... })` <br /><br />`cardNumber.element.addEventListener(SecureFields.Events.CHANGE, (data) => { ... })` |
+| `removeEventListener`    | Removes a previously attached event handler.                                                                                                                                                                                                                                                                                                                       |
+| `submit`                 | Calls the Vault API to tokenize and store the card data. Returns an error with invalid fields or the tokenized data in case everything went fine. <br /><br />`secureFields.submit((err, data) => { ... }`                                                                                                                                                         |
+| `setDebug`               | Enable / disable debug mode. When the debug mode is enabled, SecureFields logs information to the console. <br /><br />`secureFields.setDebug(true)`                                                                                                                                                                                                               |
+| `isFormValid`            | Return the state of the card form validation at any time. <br /><br />`secureFields.isFormValid()`                                                                                                                                                                                                                                                                 |

package/esm/index.js

@@ -0,0 +1 @@
+export { SecureFields } from '../lib/index.js'

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/lib/constants.d.ts

@@ -0,0 +1,12 @@
+export declare enum Events {
+    CARD_VAULT_SUCCESS = "card-vault-success",
+    CARD_VAULT_FAILURE = "card-vault-failure",
+    READY = "ready"
+}
+export declare enum FieldAttributes {
+    AUTOFILLED = "data-secure-fields-autofilled",
+    DISABLED = "data-secure-fields-disabled",
+    FOCUSED = "data-secure-fields-focused",
+    VALID = "data-secure-fields-valid"
+}
+export declare const MESSAGE_CHANNEL = "secure-fields";

package/lib/index.d.ts

@@ -0,0 +1,45 @@
+import { Events } from './constants';
+import type { Config, Field } from './types';
+declare class SecureFields {
+    config: Config;
+    controller: HTMLIFrameElement;
+    frameUrl: string;
+    apiUrl: string;
+    parentOrigin: string;
+    /**
+     * CARD_VAULT_SUCCESS: Triggered when the card is successfully vaulted.
+     *
+     * CARD_VAULT_FAILURE: Triggered when the card vaulting fails.
+     *
+     * READY: Triggered when the SecureFields is loaded and ready to be used.
+     */
+    static get Events(): typeof Events;
+    static get version(): string;
+    constructor(config: Config);
+    private _addField;
+    addCardNumberField(element: string | HTMLElement, options: Omit<Field, 'element' | 'type'>): {
+        element: HTMLElement;
+        type: "number" | "securityCode" | "expirationDate";
+        placeholder?: string;
+        styles?: import("./types").Styles;
+    };
+    addSecurityCodeField(element: string | HTMLElement, options: Omit<Field, 'element' | 'type'>): {
+        element: HTMLElement;
+        type: "number" | "securityCode" | "expirationDate";
+        placeholder?: string;
+        styles?: import("./types").Styles;
+    };
+    addExpirationDateField(element: string | HTMLElement, options: Omit<Field, 'element' | 'type'>): {
+        element: HTMLElement;
+        type: "number" | "securityCode" | "expirationDate";
+        placeholder?: string;
+        styles?: import("./types").Styles;
+    };
+    addEventListener(event: keyof typeof Events, callback: () => void): void;
+    removeEventListener(event: keyof typeof Events, callback: () => void): void;
+    submit(callback: (error: string) => void): void;
+    setDebug(debug: boolean): void;
+    isFormValid(): void;
+}
+export { SecureFields };
+export type { Field } from './types';

package/lib/index.js

@@ -0,0 +1 @@
+!function(e,t){if("object"==typeof exports&&"object"==typeof module)module.exports=t();else if("function"==typeof define&&define.amd)define([],t);else{var n=t();for(var r in n)("object"==typeof exports?exports:e)[r]=n[r]}}(this,(()=>(()=>{"use strict";var e,t,n={d:(e,t)=>{for(var r in t)n.o(t,r)&&!n.o(e,r)&&Object.defineProperty(e,r,{enumerable:!0,get:t[r]})},o:(e,t)=>Object.prototype.hasOwnProperty.call(e,t),r:e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})}},r={};function o(e,t){for(var n=0;n<t.length;n++){var r=t[n];r.enumerable=r.enumerable||!1,r.configurable=!0,"value"in r&&(r.writable=!0),Object.defineProperty(e,r.key,r)}}function i(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function c(e){for(var t=1;t<arguments.length;t++){var n=null!=arguments[t]?arguments[t]:{},r=Object.keys(n);"function"==typeof Object.getOwnPropertySymbols&&(r=r.concat(Object.getOwnPropertySymbols(n).filter((function(e){return Object.getOwnPropertyDescriptor(n,e).enumerable})))),r.forEach((function(t){i(e,t,n[t])}))}return e}function a(e,t){return t=null!=t?t:{},Object.getOwnPropertyDescriptors?Object.defineProperties(e,Object.getOwnPropertyDescriptors(t)):function(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);n.push.apply(n,r)}return n}(Object(t)).forEach((function(n){Object.defineProperty(e,n,Object.getOwnPropertyDescriptor(t,n))})),e}n.r(r),n.d(r,{SecureFields:()=>s}),function(e){e.CARD_VAULT_SUCCESS="card-vault-success",e.CARD_VAULT_FAILURE="card-vault-failure",e.READY="ready"}(e||(e={})),function(e){e.AUTOFILLED="data-secure-fields-autofilled",e.DISABLED="data-secure-fields-disabled",e.FOCUSED="data-secure-fields-focused",e.VALID="data-secure-fields-valid"}(t||(t={}));var s=function(){function n(e){!function(e,t){if(!(e instanceof t))throw new TypeError("Cannot call a class as a function")}(this,n),this.config=c({environment:"production"},e);var t="sandbox"===this.config.environment?"sandbox.":"";this.frameUrl=process.env.SECURE_FIELDS_FRAME_URL||"https://secure-fields.".concat(t).concat(this.config.gr4vyId,".gr4vy.app"),this.parentOrigin=window.location.origin,this.controller=document.createElement("iframe"),this.controller.src="".concat(this.frameUrl,"/controller.html?parentOrigin=").concat(this.parentOrigin,"&sessionId=").concat(this.config.sessionId,"&gr4vyId=").concat(this.config.gr4vyId,"&environment=").concat(this.config.environment),this.controller.style.position="absolute",this.controller.style.left="-9999999px",document.body.appendChild(this.controller)}var r,i,s=n.prototype;return s._addField=function(e,n){var r=this;e="string"==typeof e?document.querySelector(e):e;var o=document.createElement("iframe");o.id=n.type,o.src="".concat(this.frameUrl,"/input.html?parentOrigin=").concat(this.parentOrigin,"&placeholder=").concat(n.placeholder,"&type=").concat(n.type),o.style.height="48px",o.style.border="none",o.style.width="100%";var i=document.createElement("div");return i.appendChild(o),e.parentNode.replaceChild(i,e),window.addEventListener("message",(function(e){if(e.origin===r.frameUrl&&e.data.data.id===n.type)switch(e.data.type){case"blur":i.removeAttribute(t.FOCUSED);break;case"focus":i.setAttribute(t.FOCUSED,"")}})),a(c({},n),{element:e})},s.addCardNumberField=function(e,t){return this._addField(e,a(c({},t),{type:"number"}))},s.addSecurityCodeField=function(e,t){return this._addField(e,a(c({},t),{type:"securityCode"}))},s.addExpirationDateField=function(e,t){return this._addField(e,a(c({},t),{type:"expirationDate"}))},s.addEventListener=function(e,t){console.log(e,t)},s.removeEventListener=function(e,t){console.log(e,t)},s.submit=function(e){var t=this,n=function(r){if(r.origin===t.frameUrl&&"secure-fields"===r.data.channel){switch(r.data.type){case"success":e(null);break;case"error":e("Failed to update checkout session")}window.removeEventListener("message",n)}};window.addEventListener("message",n),this.controller.contentWindow.postMessage("submit",this.frameUrl)},s.setDebug=function(e){console.log(e)},s.isFormValid=function(){},r=n,i=[{key:"Events",get:function(){return e}},{key:"version",get:function(){}}],null&&o(r.prototype,null),i&&o(r,i),n}();return r})()));

package/lib/types.d.ts

@@ -0,0 +1,18 @@
+import type * as CSS from 'csstype';
+export declare type Config = {
+    environment?: 'sandbox' | 'production';
+    gr4vyId: string;
+    sessionId: string;
+};
+export declare type Field = {
+    type: 'number' | 'securityCode' | 'expirationDate';
+    placeholder?: string;
+    styles?: Styles;
+};
+export declare type Styles = {
+    [key in 'base' | 'autofill' | 'hover' | 'focus' | 'disabled' | 'valid' | 'invalid' | 'placeholder']: Pick<CSS.Properties, 'backgroundColor' | 'caretColor' | 'color' | 'colorScheme' | 'cursor' | 'font' | 'fontFamily' | 'fontFeatureSettings' | 'fontKerning' | 'fontSize' | 'fontSizeAdjust' | 'fontStretch' | 'fontStyle' | 'fontVariant' | 'fontVariantAlternates' | 'fontVariantCaps' | 'fontVariantEastAsian' | 'fontVariantLigatures' | 'fontVariantNumeric' | 'fontVariationSettings' | 'fontWeight' | 'letterSpacing' | 'lineHeight' | 'opacity' | 'textAlign' | 'textShadow' | 'textRendering' | 'transition' | 'MozOsxFontSmoothing' | 'WebkitFontSmoothing'>;
+};
+export declare type VaultSessionResponse = {
+    type: 'vault-session';
+    id: string;
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@gr4vy/secure-fields",
+  "version": "0.1.0",
+  "description": "Gr4vy-hosted secure fields offering advanced theming, PCI compliance, event handling, and more.",
+  "main": "lib/index",
+  "types": "lib/index",
+  "author": "Gr4vy <code@gr4vy.com>",
+  "license": "MIT",
+  "repository": "https://github.com/gr4vy/secure-fields/tree/main/packages/secure-fields",
+  "homepage": "https://gr4vy.com",
+  "exports": {
+    "require": "./lib/index.js",
+    "import": "./esm/index.js"
+  },
+  "files": [
+    "esm",
+    "lib",
+    "LICENSE",
+    "README",
+    "CHANGELOG.md"
+  ],
+  "nx": {
+    "targets": {
+      "build": {
+        "outputs": [
+          "{projectRoot}/lib"
+        ]
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsc && webpack --config webpack.prod.js",
+    "clean": "rm -rf lib *.tgz",
+    "dev": "webpack serve --config webpack.dev.js",
+    "docs": "typedoc --plugin typedoc-plugin-missing-exports",
+    "lint": "eslint src --ext .ts",
+    "prebuild": "yarn clean",
+    "prepack": "yarn build",
+    "test": "jest --colors"
+  },
+  "devDependencies": {
+    "csstype": "^3.1.0",
+    "typedoc": "^0.23.5",
+    "typedoc-plugin-missing-exports": "^0.23.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "gitHead": "c8e8a5d43d547fe325b18e2e294862ae1b29f6e1"
+}