ir-ecom-core-web

Installation & Setup

npm install

Building

npm run build

IREcomCore

IREcomCore serves as the public interface to the ir-ecom-core-web package. It's main responsiblies are:

1. Handles all websocket communications with the middleware
2. Handles Cart CRUD operations
3. Provides fine-grained interfaces for chatbot messages & Products, as well as interfaces for Cart operations
4. Provides a Logging facility (remoting logging TBD)

Usage

In order to get a reference to the core, use the shared instance accessor: IREcomCore.shared

Imports

import {
    IREcomCore
} from '@ir-engine/ir-ecom-core-web';

Setting the Environment

IREcomCore.shared.environment

import {
    IREcomCore, 
    EcomEnvironment
} from '@ir-engine/ir-ecom-core-web';

For this setting, you can use one of the presets:

• EcomLocal
• EcomDev
• EcomQA
• EcomProd

Optionally, you can define your own environment using the interface IEcomEnvironment

Setting the LogType

IREcomCore.shared.logLevel

import {
    IREcomCore, 
    Logger,
    LogType
} from '@ir-engine/ir-ecom-core-web';

Available ILogType's include:

• TRACE
• VERBOSE
• DEBUG
• INFO
• WARN
• ERROR

Assigning Callbacks

Note: ProductDTO is only required for onProducts

import {
    IREcomCore, 
    ProductDTO
} from '@ir-engine/ir-ecom-core-web';

onChatToken

type OnChatToken = (token: string) => void

Passes a token string to the handler.

onEndOfChatResponse

type OnEndOfChatResponse = () => void

Invoked when the end of a token stream has been reached.

onProducts

type OnProducts = (products: Array<ProductDTO>) => void

Invoked when a list of ProductDTO's has been received by the core.

Starting the core!

Before any communication with the chatbot or any Cart operations can be performed, the API Consumer must first start the core. This can be achieved by invoking the following function:

public start(shopifyStoreFrontId: string,
        host: string,
        onComplete: (storeFrontAndShopDTO: StoreFrontAndShopDTO, featuredCollection: Array<ProductDTO>) => void,
        onError: (error: Error) => void) : void

Upon a successful start, the onComplete closure will be invoked by the core and passed a StoreFronAndShopDTO, along with a list of the "featured" Products. The StoreFrontAndShopDTO contains data used to help initialize the API Consumer. The list of ProductDTO's is a list of "featured" Products that the API Consumer can use to populate populate an initial Prodcuts display (grid).

If any error should occur during startup, the onError closure will be invoked and passed the cause of the failure.

Communicating with the Chatbot

The core provides 1 function and 2 callbacks to facilitate communications with the Chatbot.

Sending a Message

In order to send a message to the Chatbot, the core provides a simple function which allows for a text message to be sent. To send a message, use the function sendMessage(text: string) : void If a message send fails, the API Consumer will be notified via the onError callback.

Receiving message tokens

Messages from the Chatbot are recieved in the form of tokens (parts of a whole message). They are received on the onChatToken callback in the form of Strings.

End of tokens stream

When a message stream has been exhausted, the API Consumer will be notified via the onEndOfChatResponse callback.

Shopping Cart Management

The core provides basic CRUD operations for managing a User's Shopping Cart.

Adding a Product Variant

Adds a desired quantity of a Product's Variant to the User's Cart.

public addProductToCart(productId: string,  
                        productVariantId: string, 
                        quantity: number) : void

NOTE: if a variant already exits in the cart, an update will be fired

Updating a Product Variant's Quantity

Updates the quantity of a Product Variant in a User's Cart.

public updateProductQuantity(productVarientId: string, quantity: number) : void

Removing a Product Variant

Removed a Product Variant from a User's Cart.

public removeProductFromCart(productVariantId: string) : void

IShoppingCartManagerListener

The API Consumer can listen for callbacks on any Cart operation via the IShoppingCartManagerListener. Listener instances can be added via: addShoppingCartManagerListener and removed via: removeShoppingCartManagerLister The interface provides the following functions:

onCartCreated(shoppingCart: IShoppingCart): void
Invoked when a remote Shopping Cart has been created.

onCartCreateFailed(error: Error): void
Invoked when a remote Shopping Cart creation failure occurs.

onAddedToCart(productId: string, productVariantId: string, quantity: number, cartLineId: string): void
Invoked when a Product (Variant) was successfully added to the remote Shopping Cart.

onAddToCartFailed(productId: string, productVariantId: string, quantity: number, error: Error): void
Invoked when a Product (Variant) failed to get added to the remote Shopping Cart.

onRemovedFromCart(productId: string, productVariantId: string, cartLineId: string): void
Invoked when a Product (Variant) has successfully been removed from the remote Shopping Cart.

onRemoveFromCartFailed(productId?: string | null, productVariantId?: string | null, error?: Error): void
Invoked when a Product (Variant) failed to get removed from the remote Shopping Cart.

onUpdateCart(productId: string, productVariantId: string, quantity: number, cartLineId: string): void
Invoked when a Product (Variant) quantity was successfully updated.

onUpdateCartFailed(productId?: string | null, productVariantId?: string | null, quantity?: number, error?: Error): void
Invoked when a Product (Variant) quantity failed to update.

onCheckout(checkoutUrl: string): void
Callback that returns the checkout URL. This function will be called when a checkout is received from middleware.

Get Cart Products

The core provides an API to obtain the current Products that a user has in their Shopping Cart. This (local) cart is a replica of what exists in the remote Shopping Cart.

public getCartProducts() : Array<ShoppingCartProductDTO>

The getCartProducts() function returns a list of ShoppingCartProductDTO. A ShoppingCartProductDTO contains all the data that the API Consumer will need to render a cart in a UI.

Checkout URL

The Cart checkout URL can be obtained at any time via the getCheckoutUrl() function.
Note, this url is also passed back to the IShoppingCartManagerListener.onCheckout() function, as well as when a Cart has been created and passed back.