@globalpayments/js 1.8.4 → 1.8.6

package/README.md

@@ -33,25 +33,38 @@ This plugin allows you to use online payments (eCommerce) features of a variety
 
 #### Options
 
-##### `publicApiKey` - `string`
+##### `publicApiKey` - `string` (Optional)
 
-> Note: Applies to Heartland eCommerce only.
+> Note: Applies to Heartland Online Payments only.
 
 The public API key associated with the merchant account. This API key is tied to a specific merchant/teminal account combination at Heartland and requires a matching secret API key to consume this value.
 
-##### `merchantId` - `string`
+##### `binCheck` - `object` (Optional)
 
-> Note: Applies to Global Payments eCommerce only.
+> Note: Applies to Heartland Online Payments only.
+
+Enables a BIN check for various capabilities.
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `hsaFsa` | `boolean` | `false` | Determines if the supplied card is for healthcare use (HSA/FSA). |
+| `surcharge` | `boolean` | `false` | Deterimines if the supplied card can be surcharged. |
+
+##### `merchantId` - `string` (Optional)
+
+> Note: Applies to Global Payments eCommerce and GP API only.
 
-The merchant ID value supplied by Global Payments eCommerce.
+For Global Payments eCommerce integrations, the merchant ID value supplied for the account.
 
-##### `account` - `string`
+For GP API integrations using multi-merchant support, the merchant ID value for a specific merchant account supported by the partner.
+
+##### `account` - `string` (Optional)
 
 > Note: Applies to Global Payments eCommerce only.
 
 The account ID value supplied by Global Payments eCommerce.
 
-##### `env` - `string`
+##### `env` - `string` (Optional)
 
 Supported values:
 
@@ -60,7 +73,7 @@ Supported values:
 
 > Note: For Heartland eCommerce, this value is inferred from the configured `publicApiKey`.
 
-##### `hash` - `(object) => Promise<object>`
+##### `hash` - `(object) => Promise<object>` (Optional)
 
 > Note: Applies to Global Payments eCommerce only.
 
@@ -141,6 +154,14 @@ The target API version. Default is `2020-10-22`.
 
 The transaction reference for the tokenization request. If not provided, a GUID is created and sent in the request.
 
+##### `enableAutocomplete` - `boolean` (Optional)
+
+Enables autocomplete / autofill features. Default is `false`.
+
+##### `language` - `string` (Optional)
+
+Value for the `html` element's `lang` attribute within the iframes. Default is `en`.
+
 #### Examples
 
 ##### Heartland eCommerce

package/bin/update-version.js

@@ -1,6 +1,7 @@
 const replace = require('replace-in-file');
 const options = {
   files: [
+    'src/assets/artifactVersion.txt',
     'src/lib/version.ts',
     'README.md',
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@globalpayments/js",
-  "version": "1.8.4",
+  "version": "1.8.6",
   "author": "Heartland Developer Portal <developers@heartland.us>",
   "license": "GPL-2.0",
   "repository": {
@@ -26,11 +26,11 @@
     "test:serve": "serve -p 7777"
   },
   "dependencies": {
-    "globalpayments-lib": "^1.8.4"
+    "globalpayments-lib": "^1.8.6"
   },
   "devDependencies": {
     "rimraf": "*",
     "rollup": "*"
   },
-  "gitHead": "09776fcfe6140ce5b1ea8fc55fb4867b15565f1d"
+  "gitHead": "515ab8c7ccf4d644af66c3aeb166d3041ede513b"
 }

package/types/credit-card/index.d.ts

@@ -1,4 +1,20 @@
 import UIForm, { IUIFormOptions } from "../ui/form";
 export declare const defaultOptions: IUIFormOptions;
+/**
+ * Allows integrators to create a standard drop-in form for
+ * accepting credit card data.
+ *
+ * @param target Target element to contain the drop-in form
+ * @param formOptions Options for the drop-in form
+ * @returns
+ */
 export declare function form(target: string | HTMLElement, formOptions?: IUIFormOptions): UIForm;
+/**
+ * Allows integrators to create a drop-in form for accepting
+ * track data from a human interface device (HID).
+ *
+ * @param target Target element to contain the drop-in form
+ * @param formOptions Options for the drop-in form
+ * @returns
+ */
 export declare function trackReaderForm(target: string | HTMLElement, formOptions?: IUIFormOptions): UIForm;

package/types/echeck/index.d.ts

@@ -1,3 +1,11 @@
 import UIForm, { IUIFormOptions } from "../ui/form";
 export declare const defaultOptions: IUIFormOptions;
+/**
+ * Allows integrators to create a standard drop-in form for
+ * accepting eCheck / ACH data.
+ *
+ * @param target Target element to contain the drop-in form
+ * @param formOptions Options for the drop-in form
+ * @returns
+ */
 export declare function form(target: string | HTMLElement, formOptions?: IUIFormOptions): UIForm;

package/types/gift-and-loyalty/index.d.ts

@@ -1,3 +1,11 @@
 import UIForm, { IUIFormOptions } from "../ui/form";
 export declare const defaultOptions: IUIFormOptions;
+/**
+ * Allows integrators to create a standard drop-in form for
+ * accepting gift and loyalty card data.
+ *
+ * @param target Target element to contain the drop-in form
+ * @param formOptions Options for the drop-in form
+ * @returns
+ */
 export declare function form(target: string | HTMLElement, formOptions?: IUIFormOptions): UIForm;

package/types/internal/lib/events.d.ts

@@ -1,3 +1,6 @@
+/**
+ * Provides integrators helper functions for working with events.
+ */
 export default class Events {
     /**
      * addHandler

package/types/lib/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "1.8.4";
+declare const _default: "1.8.6";
 export default _default;

package/types/payment-request/complete.d.ts

@@ -1,2 +1,8 @@
 declare const _default: (status: PaymentComplete) => void;
+/**
+ * Completes a payment via the PaymentRequest API after
+ * the server-side authorization request is performed
+ *
+ * @param data Payment status: "fail", "success", "unknown"
+ */
 export default _default;

package/types/payment-request/setup.d.ts

@@ -5,4 +5,22 @@ export declare class PaymentRequestEmitter extends EventEmitter {
     constructor(iframe: IframeField);
     on(event: string, listener: IEventListener): void;
 }
+/**
+ * Initiates a payment card via the PaymentRequest API
+ * to leverage card data stored in a cardholder's
+ * browser, tokenizing it via the configured gateway
+ * implementation. This is triggered in the parent
+ * window, but the PaymentRequest functionality and
+ * data only exists within the hosted field.
+ *
+ * @param selector Selector for the target element.
+ * @param details PaymentRequest details. Default includes
+ *          no details.
+ * @param instruments PaymentRequest instruments to allow.
+ *          Default includes a single instrument for
+ *          `basic-card`.
+ * @param options Additional PaymentRequest options
+ * @param startOnLoad If true, the payment card will be
+ *          shown once the hosted field loads
+ */
 export default function (selector: string, details?: PaymentDetailsInit, instruments?: PaymentMethodData[], options?: PaymentOptions, startOnLoad?: boolean): void | PaymentRequestEmitter;

package/types/tools/configure.d.ts

@@ -1,13 +1,16 @@
 import { IDictionary } from "../internal/lib/util";
-export interface IConfiguration {
-    [key: string]: any;
+/**
+ * Defines expected configuration properties for using the
+ * library with the supported gateway implementations.
+ */
+export interface IConfiguration extends IDictionary {
+    enableAutocomplete?: boolean;
+    language?: string;
+    publicApiKey?: string;
     binCheck?: {
         hsaFsa?: boolean;
         surcharge?: boolean;
     };
-    enableAutocomplete?: boolean;
-    language?: string;
-    publicApiKey?: string;
     merchantId?: string;
     account?: string;
     hash?: (data: IDictionary) => Promise<IDictionary>;
@@ -26,4 +29,9 @@ export interface IConfiguration {
     reference?: string;
 }
 declare const _default: (options: IConfiguration) => void;
+/**
+ * Allows integrators to configure the library with their
+ * desired merchant account configuration and any global
+ * library flags.
+ */
 export default _default;

package/types/ui/form/index.d.ts

@@ -44,7 +44,9 @@ export declare const fieldStyles: () => {
             border: string;
             "box-sizing": string;
             color: string;
-            cursor: string;
+            cursor: string; /**
+             * Represents logic surrounding a group of hosted fields.
+             */
             display: string;
             "font-family": string;
             "font-size": string;
@@ -425,7 +427,12 @@ export declare const parentStyles: () => {
             color: string;
             overflow: string;
             "background-size": string;
-            background: string;
+            background: string; /**
+             * Sets a special-case event listener that fires when all hosted
+             * fields in a form have registered / loaded
+             *
+             * @param fn The listener function
+             */
         };
         ".secure-payment-form .tooltip-content": {
             visibility: string;
@@ -540,15 +547,48 @@ export declare const frameFieldTypes: string[];
 export interface IUIFormFields {
     [key: string]: IUIFormField;
 }
+/**
+ * Represents logic surrounding a group of hosted fields.
+ */
 export default class UIForm {
     frames: IFrameCollection;
     fields: IUIFormFields;
     styles: object;
     private totalNumberOfFields;
+    /**
+     * Instantiates a new UIForm object for a group of hosted fields
+     *
+     * @param fields Hosted field configuration
+     * @param styles Custom CSS configuration
+     */
     constructor(fields: IUIFormFields, styles: object);
-    on(type: string, event: string | IEventListener, listener?: IEventListener): this | undefined;
+    /**
+     * Sets an event listener for an event type
+     *
+     * @param fieldTypeOrEventName The field type on which the listener should
+     *          be applied, or the type of event that should trigger the listener
+     * @param eventNameOrListener The type of event that should trigger the
+     *          listener, or the listener function
+     * @param listener The listener function when both field type and event type
+     *          are provided
+     */
+    on(fieldTypeOrEventName: string, eventNameOrListener: string | IEventListener, listener?: IEventListener): this | undefined;
+    /**
+     * Appends additional CSS rules to the group of hosted fields
+     *
+     * @param json New CSS rules
+     */
     addStylesheet(json: IDictionary): this | undefined;
+    /**
+     * Sets a special-case event listener that fires when all hosted
+     * fields in a form have registered / loaded
+     *
+     * @param fn The listener function
+     */
     ready(fn: (fields: IFrameCollection) => void): void;
+    /**
+     * Deletes all hosted fields within the form
+     */
     dispose(): void;
     private createFrames;
     private requestDataFromAll;

package/types/ui/iframe-field/action-accumulate-data-and-tokenize.d.ts

@@ -1,3 +1,9 @@
 import { IDictionary } from "../../internal/lib/util";
 declare const _default: (id: string, type: string, data: IDictionary) => void;
+/**
+ * Once data is accumulated from the other hosted fields,
+ * the `card-number` / `account-number` hosted field initiates
+ * the tokenization request with the configured gateway.
+ *
+ */
 export default _default;

package/types/ui/iframe-field/action-card-track-button-click.d.ts

@@ -1,2 +1,8 @@
 declare const _default: (id: string) => void;
+/**
+ * Once initiated, the hosted field accepts track data via a
+ * human input device (HID) into a hidden text field
+ *
+ * @param id ID of the hosted field
+ */
 export default _default;

package/types/ui/iframe-field/action-get-cvv.d.ts

@@ -1,2 +1,9 @@
 declare const _default: (id: string, type: string) => void;
+/**
+ * Gets the value of the `card-cvv` hosted field
+ *
+ * @param id ID of the hosted field
+ * @param type Field type of the hosted field
+ * @returns
+ */
 export default _default;

package/types/ui/iframe-field/action-payment-request-complete.d.ts

@@ -1,3 +1,13 @@
 import { IDictionary } from "../../internal/lib/util";
 declare const _default: (id: string, data: IDictionary) => Promise<void>;
+/**
+ * Completes a payment via the PaymentRequest API
+ * after the integrator performs the server-side
+ * authorization request. This is triggered in the parent
+ * window, but the PaymentRequest functionality and
+ * data only exists within the hoted field.
+ *
+ * @param id ID of the hosted field
+ * @param data Payment status from the integrator
+ */
 export default _default;

package/types/ui/iframe-field/action-payment-request-start.d.ts

@@ -1,3 +1,14 @@
 import { IDictionary } from "../../internal/lib/util";
 declare const _default: (id: string, data: IDictionary) => Promise<void>;
+/**
+ * Initiates a payment card via the PaymentRequest API
+ * to leverage card data stored in a cardholder's
+ * browser, tokenizing it via the configured gateway
+ * implementation. This is triggered in the parent
+ * window, but the PaymentRequest functionality and
+ * data only exists within the hosted field.
+ *
+ * @param id ID of the hosted field
+ * @param data PaymentRequest details
+ */
 export default _default;

package/types/ui/iframe-field/action-request-data.d.ts

@@ -1,3 +1,12 @@
 import { IDictionary } from "../../internal/lib/util";
 declare const _default: (id: string, type: string, data: IDictionary) => void;
+/**
+ * Causes the hosted field to send its data to the `card-number`
+ * field for tokenization when triggered by the
+ * `ui:iframe-field:request-data` event.
+ *
+ * @param id ID of the hosted field
+ * @param type Field type of the hosted field
+ * @param data Information about the recipient hosted field
+ */
 export default _default;

package/types/ui/iframe-field/action-set-card-type.d.ts

@@ -1,2 +1,11 @@
 declare const _default: (cardType?: string | undefined) => void;
+/**
+ * Sets the class list of a hosted field to include
+ * the card type inferred from the `card-number` field
+ * emitting the `ui:iframe-field:card-type` through
+ * the parent window.
+ *
+ * @param cardType The inferred card type
+ * @returns
+ */
 export default _default;

package/types/ui/iframe-field/action-set-focus.d.ts

@@ -1,2 +1,5 @@
 declare const _default: () => void;
+/**
+ * Sets input focus on the hosted field
+ */
 export default _default;

package/types/ui/iframe-field/action-set-label.d.ts

@@ -1,2 +1,7 @@
 declare const _default: (text: string) => void;
+/**
+ * Sets the label of a hosted field
+ *
+ * @param text The desired input label
+ */
 export default _default;

package/types/ui/iframe-field/action-set-placeholder.d.ts

@@ -1,2 +1,7 @@
 declare const _default: (placeholder: string) => void;
+/**
+ * Sets the placeholder text of a hosted field
+ *
+ * @param placeholder The desired palceholder text
+ */
 export default _default;

package/types/ui/iframe-field/action-set-text.d.ts

@@ -1,2 +1,7 @@
 declare const _default: (text: string) => void;
+/**
+ * Sets the text content of a hosted field
+ *
+ * @param text The desired text value
+ */
 export default _default;

package/types/ui/iframe-field/action-set-value.d.ts

@@ -1,2 +1,7 @@
 declare const _default: (text: string) => void;
+/**
+ * Sets the value of a hosted field
+ *
+ * @param text The desired input value
+ */
 export default _default;

package/types/ui/iframe-field/index.d.ts

@@ -12,8 +12,28 @@ export interface IUIFormField {
     value?: string;
 }
 export declare const fieldTypeAutocompleteMap: IDictionary;
+/**
+ * Represents logic surrounding individual hosted fields.
+ *
+ * Static methods are ran within the iframe / child window.
+ *
+ * Instance methods are ran within the parent window.
+ */
 export declare class IframeField extends EventEmitter {
+    /**
+     * Sets up the hosted field's iframe for further
+     * processing, and registers the hosted field
+     * with the parent window.
+     *
+     * @param type Field type of the hosted field
+     */
     static register(type: string): void;
+    /**
+     * Sets the hosted field's `lang` attribute on the `html` element
+     * with the globally configured value.
+     *
+     * @param lang The configured language code
+     */
     static setHtmlLang(lang: string): void;
     /**
      * Creates the inner field within the iframe window and sets
@@ -49,11 +69,17 @@ export declare class IframeField extends EventEmitter {
      * Sets the iframe window's postMessage handler in order to
      * react to parent/sibling events.
      *
-     * @param id Field ID
-     * @param type Field type
+     * @param id ID of the hosted field
+     * @param type Field type of the hosted field
      * @param targetOrigin Parent window's origin
      */
     static addMessageListener(id: string, type: string, targetOrigin: string): void;
+    /**
+     * Triggers a resize of the hosted field's iframe element
+     * within the parent window.
+     *
+     * @param id ID of the hosted field
+     */
     static triggerResize(id: string): void;
     container: Element | null;
     frame: HTMLIFrameElement;
@@ -61,14 +87,65 @@ export declare class IframeField extends EventEmitter {
     targetNode: any;
     type: "button" | "input";
     url: string;
+    /**
+     * Instantiates a new IframeField object for a hosted field
+     *
+     * @param type Field type of the hosted field
+     * @param opts Options for creating the iframe / hosted field
+     * @param src URL for the hosted field's iframe
+     */
     constructor(type: string, opts: IUIFormField, src: string);
+    /**
+     * Appends additional CSS rules to the hosted field
+     *
+     * @param json New CSS rules
+     */
     addStylesheet(json: IDictionary): void;
+    /**
+     * Gets the CVV value from the `card-cvv` hosted field.
+     *
+     * Used by gateway implementations that do not store the CVV
+     * with the token value:
+     *
+     * - TransIT (tsep)
+     * - Heartland Bill pay (billpay)
+     *
+     * @returns A promise that resolves with the CVV value
+     */
     getCvv(): Promise<unknown>;
+    /**
+     * Sets input focus on the hosted field
+     */
     setFocus(): void;
+    /**
+     * Sets the placeholder text of a hosted field
+     *
+     * @param placeholder The desired palceholder text
+     */
     setPlaceholder(placeholder: string): void;
+    /**
+     * Sets the text content of a hosted field
+     *
+     * @param text The desired text value
+     */
     setText(text: string): void;
+    /**
+     * Sets the value of a hosted field
+     *
+     * @param value The desired input value
+     */
     setValue(value: string): void;
+    /**
+     * Sets the label of a hosted field
+     *
+     * @param label The desired input label
+     */
     setLabel(label: string): void;
+    /**
+     * Sets the title of a hosted field
+     *
+     * @param title The desired title
+     */
     setTitle(title: string): void;
     private makeFrame;
 }

package/types/ui/index.d.ts

@@ -1,3 +1,10 @@
 import UIForm from "./form";
 export * from "./iframe-field";
+/**
+ * Allows integrators to custom payment data entry forms for credit
+ * card, eCheck / ACH, or gift and loyalty cards.
+ *
+ * @param options Form options.
+ * @returns
+ */
 export declare function form(options: any): UIForm;