protect-group-pulse-react

Protect Group Pulse React Component

This component is designed to place our Refundable Content (served via our dynamic api) on your React app, and allow you to also send transactions into our platform using a simple hook.

Installation

npm i --save protect-group-pulse-react

Usage

RefundableProvider

Add the provider somewhere near the root of your application

import {
	RefundableOptions,
	RefundableProvider
} from 'protect-group-pulse-react'

function MyApp() {
	const options: RefundableOptions = {
        currencyCode: 'GBP',
        environment: 'test',
        languageCode: 'en',
        vendorCode: '<YOUR-VENDOR-CODE>',
        eventDateFormat: 'DD/MM/YYYY', // optional
        containerSize: 'medium', //optional
        useSaleAction: true, // optional, set this to false if you intend to call our sale endpoint manually
        nonce: '[nonce code for the inline script, if you have a CSP set up on your site]', //optional
        salesTax: 10 // optional, apply sales tax to the refundable booking cost
    }

	return (
		<RefundableProvider options={options}>
			<TheRestOfYourApp/>
		</RefundableProvider>
	)
}

updateQuoteData

The useRefudableActions hook provides a function to update the quote data at any point on your app

import {useRefundableActions} from 'protect-group-pulse-react'

function MyTicketTypeSelector(){
  const {updateQuoteData} = useRefundableActions()
  const {myInternalState} = useMyInternalStateContext()
  
  useEffect(() => {
    const {bookingCost, numberOfTickets, eventDate} = myInternalState
    updateQuoteData({
      totalValue: bookingCost, 
      numberOfTickets, 
      eventTravelDateTime: eventDate,
      nonce: '[nonce code can also be provided here, if required]'
    })
  }, [myInternalState])
  
  const handleChange = event => updateQuoteData({
    totalValue: myInternalState.bookingCost,
    numberOfTickets: myInternalState.numberOfTickets,
    eventTravelDateTime: myInternalState.eventDate,
    ticketType: event.target.value,
    nonce: '[nonce code can also be provided here, if required]',
    salesTax: 5 // sales tax can also be applied here, if required
  })
  
  return (
    <div>
      <label>Select a ticket type</label>
      <select onChange={handleChange}>
        <option value="standard">Standard</option>
        <option value="premium">Premium</option>
        <option value="vip">VIP</option>
      </select>
    </div>
  )
}

RefundableContent

Add the RefundableContent component where you would like our Refundable Content to be placed on your page. Use the writeSale function on the useRefundableActions hook to write a transaction into our platform. Use the useChangeEventArgs hook to listen for changes to the components internal state

import {
	ApiRequestFailedEventArgs,
	RefudableContent,
	SaleData,
	useChangeEventArgs,
	useRefundableActions
} from 'protect-group-pulse-react'

function MyCheckoutPage() {
	const {writeSale} = useRefundableActions()
	const args = useChangeEventArgs()

	useEffect(() => {
		// Do something with the args
	}, [args])

	const handleApiError = (args: ApiRequestFailedEventArgs) => {
		// Maybe some invalid data was supplied?
	}

	const handleMakePayment = async () => {
		// Do your sale thing

		const request: SaleData = {
			bookingReference: '<YOUR-BOOKING-REFERENCE>',
			customers: [
				{
					email: '[e-mail]',
					firstName: 'Test',
					lastName: 'Test',
					telephone: '[phone]'
				}
			],
			flights: [
				{
					arrivalCode: 'LHR',
					class: 'Economy',
					departureCode: 'LBA',
					departureDate: '01/01/2000', // the configured date format
					flightNumber: 'PP1'
				}
			]
		}

		try {
			const response = await writeSale(request)
			// Do something with the response
		} catch (e: any) {
			const {data: {error}} = e
			// Something went wrong
		}
	}

	return (
		<MyPageWrapper>
			//some components
			<RefundableContent
				onApiError={handleApiError}
			/>
			//some components
			<MakePaymentButton onClick={handleMakePayment}></MakePaymentButton>
		</MyPageWrapper>
	)
}

Types

• Environment - 'test' | 'prod'
• ContainerSize - 'small' | 'medium' | 'large'

RefundableProvider Props

Property	Type	Required?	Default	Description
autoQuoteOnProductSelection	boolean	no	true	When Protect Plus products are enabled, some of them may be covered as part of our Refund Protect offering. This means selecting one of these products could require a subsequent call to the quote api. This will happen automatically if this prop is set to true
containerSize	ContainerSize	no	'large'	Display a mobile/tablet layout on a desktop by specifying either 'small' or 'medium'. This is useful if our refundable content is in a smaller area on your desktop layout. Downward media queries are still observed
currencyCode	string	yes		A valid currency code
eventDateFormat	string	no		Our api expects a date format of ISO 861 yyyy-MM-ddTHH:mm:ss.FFFFFzzz. If you are unable to supply a date in this format you can optionally configure the format here. The format you supply must match a javascript date format from the moment.js library
environment	Environment	yes		Send requests to either our test or production api. Should be either 'test' or 'prod'
languageCode	string	yes		A valid language code. Currently supported languages are en, ar, de, es, fr, it, ja, ko, pt, ru, tr, zh-CH, zh-TW
nonce	string	no		The html has a small script block that fires custom events when a CTA is clicked. There is a placeholder for a nonce code if your site has a Content Security Policy set up which would block the script execution
salesTax	number	no		Sales tax can be applied to the refundable booking cost, to save you having to calculate it afterwards
useSaleAction	boolean	no		If you intend to call our sale endpoint at a later time via your back end, set this to false. The change event args will then have two other properties set. quoteId, and products
vendorCode	string	yes		Your vendor code supplied by our commercial team. Please ensure the correct vendor code is supplied for the environment

RefundableContent Props

Property	Type	Required?	Default	Description
onApiError	function			Function that is invoked if a quote api call fails for whatever reason

interface ProtectionChangeEventArgs {
    bookingCost: number
    formattedBookingCost: string
    formattedProtectionValue: string
	formattedProtectionValueNet: string
	formattedProtectionValueTax: string
    formattedTotalValue: string
    products?: ChangeEventProduct[] // only populated when useSaleAction is set to false
    protectionSelected?: boolean
    protectionValue: number
	protectionValueNet: number
	protectionValueTax: number
    quoteId?: string // only populated when useSaleAction is set to false
    totalValue: number
}

interface ChangeEventProduct {
	formattedValue: string
	formattedValueNet: string
	formattedValueTax: string
	label: string
	productCode: string
	productId: number
	sold?: boolean
	sourcePriceTruncated?: number
	value: number
	valueNex: number
	valueTax: number
}

quoteId and products will only be set when you set the useSaleAction value to false. These two values are what's required for you to manually make a request to our sale endpoint. You will also need credentials to call our api, which can be provided by your commercial manager.

Types

type ContainerSize = 'small' | 'medium' | 'large'

interface QuoteData {
	client?: string
	containerSize?: ContainerSize
	eventTravelDateTime: string
	fields?: Record<string, any>
	flights?: Flight[]
	nonce?: string
	numberOfTickets: number
	quoteId?: string
	salesTax?: number
	totalValue: number
}

export interface Flight {
	arrivalCode: string
	class: string
	departureCode: string
	departureDate: string
	flightNumber: string
	terminal?: string
}

interface Customer {
	email?: string // required for protect plus products
	firstName: string
	lastName: string
	telephone?: string // required for protect plus products and should be in the format +(prefix)(number)
}

interface SaleData {
	bookingReference: string
	customers: Customer[]
	flights?: Flight[]
}

interface PatchSaleData extends SaleData {
	quoteId: string
	products: SaleProduct[]
}

interface SaleResult {
	data: SaleResponse
	error: any
}

interface SaleResponse {
	saleId: string
	refundableLink?: string // Only returned on a refundable booking
	refundableConfirmationHtml?: string // Only returned on a refunable booking
}

interface RefundableActions {
	cancelSale: (saleId: string) => Promise<any>
	holdSale: (saleId: string) => Promise<any> // saleId can be either our sale id, from the original sale response OR your booking refernce
	patchSale: (request: PatchSaleData) => Promise<SaleResponse>
	saleComplete: () => void
	updateQuoteData: (data: QuoteData) => void
	writeSale: (request: SaleData) => Promise<SaleResult>
}

RefundableActions.reset

This function is for partners who set the useSaleAction prop to false. It's designed to be used after a customer has completed a booking, to clear the session data, which would normally happen automatically during the writeSale process

useChangeEventArgs

import {useChangeEventArgs} from 'protect-group-pulse-react'

function MyBasketComponent() {
	const eventArgs = useChangeEventArgs()

	return (
		<div>
			{
				eventArgs.products.map(product => (
					<div>{product.label}: {product.formattedValue}</div>
				))
			}
		</div>
	)
}

ChangeEventArgs

export interface ProductChangeEventArgs {
	bookingCost: number
	formattedBookingCost: string
	formattedProductValue: string
	formattedTotalValue: string
	products?: ChangeEventProduct[]
	productValue: number
	quoteId?: string
	totalValue: number
}

export interface ChangeEventProduct {
	formattedValue: string
	formattedValueNet: string
	formattedValueTax: string
	label: string
	productCode: string
	productId: number
	sold?: boolean
	value: number
	valueNet: number
	valueTax: number
}

The label property on each product can be used to display our selected products in your basket. This is entirely configurable on our platform and is also translated into the supplied language.

Protect Plus

If you have opted in to our new product range, displaying them is as simple as placing the new ProductContent component on your page.

There are no props required on this component, everything is taken care of internally.

import {ProductContent, RefundableProvider} from 'protect-group-pulse-react'

function RootOfYourPage() {
	return (
		<RefundableProvider>
			<SomePartOfYourApp/>
		</RefundableProvider>
	)
}

function SomePartOfYourApp() {
	return (
		<div>
			...other things on your page
			<ProductContent/>
			...other things on your page
		</div>
	)
}

Flight Data

Some of our new products are based around flights e.g. Carbon Offset, Lost Baggage and Flight Disruption

For Carbon Offset, flight data is required up front on a quote request, as the product price is calculated in real time. Either arrival and departure airport codes OR flight data are supported for this product (flight number is not required).

For Flight Disruption and Lost Baggage, we only need flight data on a sale request. Only flight data is supported for these products (flight number is required)

Release Notes

Version 1.0.1

• Initial release