PIQ-2907: Click To Pay integration

CHANGES.md

@@ -1,3 +1,8 @@
+#### 1.3.0
+- Add ClickToPay integration support
+- Provide high-level types with index.d.ts ([Issue 21](https://github.com/devcode-git/hosted-fields-sdk/issues/21))
+- Make onLoadCallback optional ([Issue 22](https://github.com/devcode-git/hosted-fields-sdk/issues/21))
+
 #### 1.2.8
 - Add onCardBrandChangeCallback
 

README.md

@@ -75,10 +75,12 @@ Expiry: `cc-exp`
 
 
 #### HostedFields
-HostedFields in turn will expose three functions
+HostedFields in turn will expose these functions
 * setup
 * get
 * reset
+* setClickToPayTransactionAmount
+* clickToPayCheckout
 
 **setup**
 
@@ -96,7 +98,21 @@ Setup is the first function you will call. It takes a config-object as its only
     autoFocusNext: true,
     onLoadCallback: () => someFunction,
     onCardBrandChangeCallback: ({ cardBrand: string }) => unknown,
-    el = A domElement to render the hosted fields in
+    el: A domElement to render the hosted fields in,
+    // Set the config from below if need to integrate ClickToPay
+    // The full list of attributes can be seen here: https://srci-docs.prod.srci.cloud.netcetera.com/sdk-config-properties
+    // You can override only these attributes in Hosted Fields. These are the default values:
+    clickToPayAttributes: {
+        locale: "en_US",
+        sandbox: "true", // Make sure to set it "false" in production
+    },
+    // See the full config here: https://srci-docs.prod.srci.cloud.netcetera.com/sdk-config-guide#scheme-specific-configuration
+    clickToPayConfig: "<ClickToPayConfig>", 
+    onRequestIframeExpandCallback: (recommendedHeight: number) => unknown,  
+    onCancelIframeExpandCallback: () => unkown, 
+    // Response type here: https://srci-docs.prod.srci.cloud.netcetera.com/sdk-checkout-respons
+    onClickToPayCheckoutSuccessCallback: (response) => uknown, 
+    onClickToPayCheckoutErrorCallback: (error) => unkown, 
 }
 ````
 
@@ -128,6 +144,27 @@ and will return the detected **cardBrand**(e.g. visa, mastercard, etc.).
 
 This is usually used for dynamic credit card flow handling based on the card brand(e.g. for ClickToPay).
 
+**clickToPayAattributes**
+The attributes passed to the ClickToPay instance.
+
+**clickToPayConfig**
+The config passed to the ClickToPay instance.
+
+**onRequestIframeExpandCallback**
+This callback is triggered when the clickToPayCheckout call is performed to inform the integrator that 
+the iframe height should be changed to the **recommendedHeight** and hide all the other visible UI elements 
+to make room for the ClickToPay iframe to expand.
+
+**onCancelIframeExpandCallback**
+This callback is triggered when the ClickToPay checkout has finised to inform the integrator that 
+the iframe height should be restored and show all the other previously hidden UI elements.
+
+**onClickToPayCheckoutSuccessCallback**
+The callback triggered when receive a success response after a ClickToPay checkout.
+
+**onClickToPayCheckoutErrorCallback**
+The callback triggered when receive an error after a ClickToPay cehckout.
+
 **Possible values for hostedfieldsurl:**
 
 For test environments use: `'https://test-hostedpages.paymentiq.io/1.0.51/index.html'`.
@@ -178,6 +215,22 @@ var container = document.querySelector(el);
 ````
 Lastly eventListener are registered to the iframe so that it picks up postMessage events.
 
+
+**setClickToPayTransactionAmount** *(used for ClickToPay integration)*
+
+It's used when the transaction amount should be dynamically changed.
+
+Set ClickToPay transaction amount according to:  
+https://srci-docs.prod.srci.cloud.netcetera.com/sdk-config-guide
+
+
+**clickToPayCheckout** *(used for ClickToPay integration)*
+
+Perform ClickToPay checkout according to:  
+https://srci-docs.prod.srci.cloud.netcetera.com/sdk-checkout-api
+
+
+
 ## Styling
 Styling will mainly be handled buy the application using the hosted-fields. Each field will have some basic styling but the layout will have to be supplied.
 

index.d.ts

@@ -0,0 +1,134 @@
+declare module "hosted-fields-sdk" {
+  export interface HostedFieldsConfig {
+    [key: string]: any;
+  }
+
+  export interface ClickToPayPayload {
+    [key: string]: any;
+  }
+
+  export interface ClickToPayTransactionAmount {
+    /**
+     * The transaction amount as a string.(e.g., "10")
+     */
+    amount: string;
+    /**
+     * The currency code in ISO 4217 format. (e.g., "USD")
+     */
+    currencyCode: string; 
+  }
+
+  export interface HostedFields {
+    /**
+     * Initializes hosted fields with the provided configuration.
+     */
+    setup(config: HostedFieldsConfig): void;
+
+    /**
+     * If you want to get the encrypted values from the fields you can call this method.
+     * This will trigger the supplied callback-function registered in HostedFields.setup() to be called with the values for each field.
+     */
+    get(): void;
+
+    /**
+     * If you wish to reset the currently rendered iframes (fields) you can call HostedFields.reset() before running a new setup().
+     * This can be required if your page that contains the fields gets re-rendered. In that case you will have registered duplicates of the fields. 
+     * So it's a good idea to call HostedFields.reset() on a beforeDestroy-hook if you are using Vue or React.
+     */
+    reset(): void;
+
+    /**
+     * Updates the Click to Pay transaction amount.
+     */
+    setClickToPayTransactionAmount(transactionAmount: any): void;
+
+    /**
+     * Initiates a Click to Pay checkout flow.
+     */
+    clickToPayCheckout(payload: ClickToPayPayload): void;
+  }
+
+  /**
+   * Main HostedFields singleton/object exposed by the SDK.
+   */
+  export const HostedFields: HostedFields;
+
+  /**
+   * The supported field types.
+   */
+  export const FieldTypes: {
+    readonly TEXT: "TEXT";
+    readonly NUMBER: "NUMBER";
+    readonly CVV: "CVV";
+    readonly CREDITCARD_NUMBER: "CREDITCARD_NUMBER";
+    readonly EXPIRY_MM_YYYY: "EXPIRY_MM_YYYY";
+  };
+
+  /**
+   * Represents a single hosted field configuration.
+   */
+  export class Field {
+    /**
+     * The type of the field (e.g., TEXT, NUMBER, etc.).
+     */
+    type: keyof typeof FieldTypes;
+
+    /**
+     * The HTML id of the field.
+     */
+    id: string;
+
+    /**
+     * The name of the field (used as a key when retrieving hosted field data).
+     */
+    name: string;
+
+    /**
+     * The label text of the field.
+     */
+    label: string;
+
+    /**
+     * Placeholder text to display inside the field.
+     */
+    helpKey: string;
+
+    /**
+     * Error message to display if the field has validation issues.
+     */
+    error: string;
+
+    /**
+     * Whether the field should be visible (default: true).
+     */
+    visible: boolean;
+
+    /**
+     * Whether the field is required (default: true).
+     */
+    required: boolean;
+
+    /**
+     * For backward compatibility: set to true to enable autofill (disables value formatting).
+     */
+    noAttributeValueFormatting: boolean;
+
+    /**
+     * What autofill value the field should use (e.g., "cc-number", "cc-csc", "cc-exp").
+     */
+    autocomplete: string;
+
+    constructor(
+      type: keyof typeof FieldTypes,
+      id: string,
+      name: string,
+      label: string,
+      helpKey?: string,
+      errorKey?: string,
+      visible?: boolean,
+      required?: boolean,
+      noAttributeValueFormatting?: boolean,
+      autocomplete?: string
+    );
+  }
+}