@boldcommerce/checkout-frontend-library v0.55.0

Checkout Frontend Library

Description

The Checkout Frontend Library is a Bold Javascript library, which contains reusable methods to help accomplish the following:

• Call Bold's Headless Checkout APIs
• Control request retry
• Communicate to the PIGI API
• Get useful types and constants to avoid defining interfaces

Installation

Install with Yarn

yarn add "@boldcommerce/checkout-frontend-library"

Install a specific version

yarn add "@boldcommerce/checkout-frontend-library"@1.0.0

(replace "1.0.0" with the version number that you want)

Install with NPM

npm install "@boldcommerce/checkout-frontend-library"

Install a specific version

npm install "@boldcommerce/checkout-frontend-library"@1.0.0

(replace "1.0.0" with the version number that you want)

Methods Reference

Initialize

Initialize library

▸ initialize(initData, shopIdentifier, environment): Promise <IApiReturnObject>

Initialize the library with order data and environment variables. The library needs to be initialized with required data before using any other functionality.

 const response: IApiReturnObject = await initialize(initData, shopIdentifier, environment);

Parameters

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

Address

Set Shipping Address

▸ setShippingAddress(shippingAddress, numOfRetries?): Promise <IApiReturnObject>

Set the shipping address on the order. If a shipping address already exists, the existing address is overwritten.

 const response: IApiReturnObject = await setShippingAddress(_shipping, API_RETRY);

Parameters

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

Update Shipping Address

▸ updateShippingAddress(shippingAddress, numOfRetries?): Promise <IApiReturnObject>

Updates the shipping address on the order.

 const response: IApiReturnObject = await updateShippingAddress(_shipping, API_RETRY);

Parameters

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

Delete Shipping Address

▸ deleteShippingAddress(numOfRetries?): Promise <IApiReturnObject>

Deletes the shipping address from the order.

 const response: IApiReturnObject = await deleteShippingAddress(API_RETRY);

Parameters

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

Set Billing Address

▸ setBillingAddress(billingAddress, numOfRetries?): Promise <IApiReturnObject>

Set the billing address on the order. If a billing address already exists, the existing address is overwritten.

 const response: IApiReturnObject = await setBillingAddress(_billing, API_RETRY);

Parameters:

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

Update Billing Address

▸ updateBillingAddress(billingAddress, numOfRetries?): Promise <IApiReturnObject>

Updates the billing address on the order.

 const response: IApiReturnObject = await updateBillingAddress(_billing, API_RETRY);

Parameters

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

Delete Billing Address

▸ deleteBillingAddress(numOfRetries?): Promise <IApiReturnObject>

Deletes the billing address from the order.

 const response: IApiReturnObject = await deleteBillingAddress(API_RETRY);

Parameters

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

Customer

Add Guest customer

▸ addGuestCustomer(firstName, lastName, email, acceptsMarketing?, numOfRetries?): Promise <IApiReturnObject>

Adds the guest customer details to the order. This method returns an error if a customer already exists on the order.

 const response: IApiReturnObject = await addGuestCustomer(first_name, last_name, email_address, accepts_marketing, API_RETRY);

Parameters

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

Delete customer

▸ deleteCustomer(numOfRetries?): Promise <IApiReturnObject>

Deletes the customer from the order.

 const response: IApiReturnObject = await deleteCustomer(API_RETRY);

Parameters

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

Update customer

▸ updateCustomer(firstName, lastName, email, acceptsMarketing, numOfRetries?): Promise <IApiReturnObject>

Updates the customer on the order.

 const response: IApiReturnObject = await updateCustomer(first_name, last_name, email_address, accepts_marketing, API_RETRY);

Parameters

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

Validate customer email address

▸ validateEmail(email, numOfRetries?): Promise <IApiReturnObject>

Validates the customer email address.

 const response: IApiReturnObject = await validateEmail(email_address, API_RETRY);

Parameters

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

Discounts

Add Discount Code

▸ addDiscount(code,numOfRetries?): Promise <IApiReturnObject>

Adds discount code to the order.

 const response: IApiReturnObject = await addDiscount(code, API_RETRY);

Parameters

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

Delete Discount Code

▸ deleteDiscount(code,numOfRetries?): Promise <IApiReturnObject>

Deletes a discount code from the order.

 const response: IApiReturnObject = await deleteDiscount(code, API_RETRY);

Parameters

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

Validate Discount Code

▸ validateDiscount(code,numOfRetries?): Promise <IApiReturnObject>

Validates the given discount code against the current order state. This method does not add discount code to the order.

 const response: IApiReturnObject = await validateDiscount(code, API_RETRY);

Parameters

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

Items

Update Line Item Quantity

▸ updateLineItemQuantity(lineItemKey, quantity ,numOfRetries?): Promise <IApiReturnObject>

Updates the quantity of a line item on the order.

 const response: IApiReturnObject = await updateLineItemQuantity(lineItemKey, quantity, API_RETRY);

Parameters

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

Shipping Lines

Change Shipping Line

▸ changeShippingLine(index ,numOfRetries?): Promise <IApiReturnObject>

Adds or updates the shipping line on the order.

 const response: IApiReturnObject = await changeShippingLine(index, API_RETRY);

Parameters

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

Get Shipping Lines

▸ getShippingLines(numOfRetries?): Promise <IApiReturnObject>

Get all the available shipping lines.

 const response: IApiReturnObject = await getShippingLines(API_RETRY);

Parameters

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

Taxes

Set Taxes

▸ setTaxes(numOfRetries?): Promise <IApiReturnObject>

Calculates and applies taxes to the order. Taxes are not automatically recalculated, so you must call this method after you make any changes to the shipping address.

 const response: IApiReturnObject = await setTaxes(API_RETRY);

Parameters

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

Order

Check Inventory

▸ checkInventory(stage,numOfRetries?): Promise <IApiReturnObject>

Performs an inventory check on the items of the order.

 const response: IApiReturnObject = await checkInventory(stage, API_RETRY);

Parameters

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

Process Order

▸ processOrder(numOfRetries?): Promise <IApiReturnObject>

Processes the order.

 const response: IApiReturnObject = await processOrder(API_RETRY);

Parameters

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

Get Application State

▸ getRefreshedApplicationState(numOfRetries?): Promise <IApiReturnObject>

Gets a refreshed copy of the application state.

 const response: IApiReturnObject = await getRefreshedApplicationState(API_RETRY);

Parameters

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

Payment

Add Payment

▸ addPayment(payment,numOfRetries?): Promise <IApiReturnObject>

Adds a new payment to the order.

 const response: IApiReturnObject = await addPayment(payment, API_RETRY);

Parameters

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

Delete Payment

▸ deletePayment(payment,numOfRetries?): Promise <IApiReturnObject>

Removes the payment by token.

 const response: IApiReturnObject = await deletePayment(payment, API_RETRY);

Parameters

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

Update Payment

▸ updatePayment(payment,numOfRetries?): Promise <IApiReturnObject>

Updates the value of the payment. Only the amount of payment can be changed.

 const response: IApiReturnObject = await updatePayment(payment, API_RETRY);

Parameters

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

List Payments

▸ getPaymentList(numOfRetries?): Promise <IApiReturnObject>

Lists the payments that have been applied to the order.

 const response: IApiReturnObject = await getPaymentList(API_RETRY);

Parameters

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

Remove Gift Card

▸ deleteGiftCardPayment(id,numOfRetries?): Promise <IApiReturnObject>

Removes a gift card payment by id.

 const response: IApiReturnObject = await getPaymentList(API_RETRY);

Parameters

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

Payment Iframe

Get Payment Iframe

▸ getPaymentIframeUrl(): Promise <IApiReturnObject>

Retrieve the Payment Isolation Gateway Interface (PIGI) url.

 const response: IApiReturnObject = await getPaymentIframeUrl();

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

CSS Styling for PIGI

▸ cssStylingPaymentIframe(body,numOfRetries?): Promise <IApiReturnObject>

Styles the Payment Isolation Gateway Interface (PIGI) using CSS and media queries.

 const response: IApiReturnObject = await cssStylingPaymentIframe(body, API_RETRY);

Parameters

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

PIGI Actions

Set PIGI Listener

▸ setPigiListener(iFrameId, callback): void

Sets the callback function that will receive all action responses from PIGI. The callback function is executed when the parent receives any response from PIGI. You can also implement PIGI event driven responses in the callback function.

const handlePigiMessage = (e) => {
    const {responseType, payload} = e.data as IPigiResponseData;
    // Implement all action responses by responseType
}

setPigiListener(IframeId, handlePigiMessage);

Parameters

Add Payment Action

▸ sendAddPaymentAction(): IApiReturnObject ▸ sendAddPaymentActionAsync(): Promise <IPigiResponseType>

The Add payment PIGI action requests that PIGI adds the payment token to the order after customer enters the payment information.

 const response: IApiReturnObject = sendAddPaymentAction();
 const responseAsync: IPigiResponseType = await sendAddPaymentActionAsync();

Returns

IApiReturnObject | Promise<IPigiResponseType>

An API response or promise that resolve the PIGI response.

Clear PIGI Error Action

▸ sendClearErrorMessageAction(): IApiReturnObject ▸ sendClearErrorMessageActionAsync(): Promise <IPigiResponseType>

The Clear PIGI error action removes all errors from the PIGI user interface.

 const response: IApiReturnObject = sendClearErrorMessageAction();
 const responseAsync: IPigiResponseType = await sendClearErrorMessageActionAsync();

Returns

IApiReturnObject | Promise<IPigiResponseType>

An API response or promise that resolve the PIGI response.

Display Error Message

▸ sendDisplayErrorMessageAction(message, subType): IApiReturnObject ▸ sendDisplayErrorMessageActionAsync(message, subType): Promise <IPigiResponseType>

The Display error message action displays an error message in the PIGI user interface.

 const response: IApiReturnObject = sendDisplayErrorMessageAction(message, subType);
 const responseAsync: IPigiResponseType = await sendDisplayErrorMessageActionAsync(message, subType);

Parameters

Returns

IApiReturnObject | Promise<IPigiResponseType>

An API response or promise that resolve the PIGI response.

Handle SCA Action

▸ sendHandleScaAction(clientSecretToken?): IApiReturnObject ▸ sendHandleScaActionAsync(clientSecretToken?): Promise <IPigiResponseType>

The Handle SCA action requests that PIGI handles SCA/3DS.

 const response: IApiReturnObject = sendHandleScaAction(clientSecretToken);
 const responseAsync: IApiReturnObject = await sendHandleScaAction(clientSecretToken);

Parameters

Returns

IApiReturnObject | Promise<IPigiResponseType>

An API response or promise that resolve the PIGI response.

Refresh Order Action

▸ sendRefreshOrderAction(): IApiReturnObject ▸ sendRefreshOrderActionAsync(): Promise <IPigiResponseType>

The Refresh Order action updates the order state in PIGI.

 const response: IApiReturnObject = sendRefreshOrderAction();
 const responseAsync: IPigiResponseType = await sendRefreshOrderActionAsync();

Returns

IApiReturnObject | Promise<IPigiResponseType>

An API response or promise that resolve the PIGI response.

Select Payment Action

▸ sendSelectPaymentMethodAction(payload): IApiReturnObject ▸ sendSelectPaymentMethodActionAsync(payload): Promise <IPigiResponseType>

The Select Payment Method action selects the customer's choice of payment.

 const response: IApiReturnObject = sendSelectPaymentMethodAction(payload);
 const responseAsync: IPigiResponseType = await sendSelectPaymentMethodActionAsync(payload);

Parameters

Returns

IApiReturnObject | Promise<IPigiResponseType>

An API response or promise that resolve the PIGI response.

Update Language Action

▸ sendUpdateLanguageAction(languageCode): IApiReturnObject ▸ sendUpdateLanguageActionAsync(languageCode): Promise <IPigiResponseType>

The Update Language action changes the display language of PIGI.

 const response: IApiReturnObject = sendUpdateLanguageAction(languageCode);
 const responseAsync: IPigiResponseType = await sendUpdateLanguageActionAsync(languageCode);

Parameters

Returns

IApiReturnObject | Promise<IPigiResponseType>

An API response or promise that resolve the PIGI response.

Update Media Match Action

▸ sendUpdateMediaMatchAction(conditionText, matches): IApiReturnObject ▸ sendUpdateMediaMatchActionAsync(conditionText, matches): Promise <IPigiResponseType>

The Update Media Match action changes the CSS styling of PIGI.

 const response: IApiReturnObject = sendUpdateMediaMatchAction(conditionText, matches);
 const responseAsync: IPigiResponseType = await sendUpdateMediaMatchActionAsync(conditionText, matches);

Parameters

Returns

IApiReturnObject | Promise<IPigiResponseType>

An API response or promise that resolve the PIGI response.

State

The Bold Checkout Frontend Library keeps a local copy of the most up-to-date application state, which is updated after every API call. Use the methods in this section to retrieve certain information about your order. To see the latest order status, you can also call the Get Application State endpoint.

Get Addresses

▸ getAddresses(): IAddressType

Get the latest shipping and billing address from the Checkout Frontend Library local state management.

 const addresses: IAddressType = await getAddresses();

Get Application State

▸ getApplicationState(): IApplicationState

Get the latest application state from the Checkout Frontend Library local state management.

 const app: IApplicationState = await getApplicationState();

Get Billing Address

▸ getBillingAddress(): IAddress

Get the latest billing address from the Checkout Frontend Library local state management.

 const billing: IAddress = await getBillingAddress();

Get Currency details

▸ getCurrency(): ICurrency

Gets the order currency details from the Checkout Frontend Library local state management.

 const currency: ICurrency = await getCurrency();

Get Customer details

▸ getCustomer(): ICustomer

Gets the customer details from the Checkout Frontend Library local state management.

 const customer: ICustomer = await getCustomer();

Get Discount List

▸ getDiscounts(): Array<IDiscount>

Gets all the discounts applied to the order from the Checkout Frontend Library local state management.

 const discounts: Array<IDiscount> = await getDiscounts();

Get Fees Information

▸ getFees(): Array<IFees>

Gets all the fees applied to the order from the Checkout Frontend Library local state management.

 const fees: Array<IFees> = await getFees();

Get Line Items

▸ getLineItems(): Array<ILineItem>

Gets all the line items in the cart from the Checkout Frontend Library local state management.

 const ILineItems: Array<ILineItem> = await getLineItems();

Get initial Order Data

▸ getOrderInitialData(): IOrderInitialData

Gets the initial data on the order from the Checkout Frontend Library local state management.

 const initData: IOrderInitialData = await getOrderInitialData();

Get Order Metadata

▸ getOrderMetaData(): IOrderMetaData

Gets the order metadata from the Checkout Frontend Library local state management.

 const initData: IOrderMetaData = await getOrderMetaData();

Get Payment Details

▸ getPayments(): Array<IPayment>

Gets all the payment details applied to the order from the Checkout Frontend Library local state management.

 const payments: Array<IPayment> = await getPayments();

Get Shipping Lines Details

▸ getShipping(): IShipping

Gets the shipping lines details from the Checkout Frontend Library local state management.

 const shippingLines: IShipping = await getShipping();

Get Shipping Address

▸ getShippingAddress(): IAddress

Gets the shipping address information from the Checkout Frontend Library local state management.

 const shipping: IAddress = await getShippingAddress();

Get Taxes

▸ getTaxes(): Array<ITax>

Gets all the applied taxes from the Checkout Frontend Library local state management.

 const taxes: Array<ITax> = await getTaxes();