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>',
			customerServiceEmail: '<AN OPTIONAL CUSTOMER SERIVCE EMAIL ADDRESS>',
			customers: [
				{
					email: '[email protected]',
					firstName: 'Test',
					lastName: 'Test',
					telephone: '+44123456'
				}
			],
			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
	customerServiceEmail?: 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 Locale {
	currencyCode?: string
	languageCode?: string
}

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
	setLocale: (data: Locale) => void
	updateQuoteData: (data: QuoteData) => void
	writeSale: (request: SaleData) => Promise<SaleResult>
}

RefundableActions.saleComplete

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
	sourcePriceTruncated?: number
	value: number
	valueNet: number
	valueTax: number
}

The sourcePriceTruncated property will be populated if the quote value is above the allowed limit, and your account has been configured to allow overlimit requests, truncating the amount covered. The value will be the amount that can be protected.

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, Delayed Baggage, Lounge Access 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).

Lounge Access requires at least a departure airport code

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

Multiple Quote Price Values

The quote api can accept multiple values, instead of the current number of tickets and total value fields. This is useful in scenarios where different items in a basket may have different sales taxes. The response will return a breakdown of each price in a productData array.

const quoteRequest: QuoteData = {
	eventTravelDateTime: '',
	values: [
		{
			numberOfTickets: 1,
			reference: 'Ticket 1',
			salesTax: 10,
			value: 10
		},
		{
			numberOfTickets: 4,
			reference: 'Other Tickets',
			salesTax: 20,
			value: 400
		}
	]
}

The event arguments will contain the price breakdowns, as well as the combined totals at the root level

{
    "bookingCost": 500,
    "formattedBookingCost": "$500.00",
    "formattedProductValue": "$59.00",
    "formattedTotalValue": "$559.00",
    "products": [
        {
            "formattedValue": "$59.00",
            "formattedValueNet": "$50.00",
            "formattedValueTax": "$9.00",
            "label": null,
            "productCode": "TKT",
            "productData": [
                {
                    "productPrice": 5.5,
                    "reference": "Ticket 1",
                    "sourcePrice": 100,
                    "totalProductPrice": 11,
                    "totalProductPriceNet": 10,
                    "totalProductPriceTax": 1
                },
                {
                    "productPrice": 24,
                    "reference": "Other Tickets",
                    "sourcePrice": 400,
                    "totalProductPrice": 48,
                    "totalProductPriceNet": 40,
                    "totalProductPriceTax": 8
                }
            ],
            "productId": 16,
            "reference": null,
            "sold": true,
            "sourcePriceTruncated": null,
            "value": 59,
            "valueNex": 50,
            "valueTax": 9
        }
    ],
    "productValue": 59,
    "quoteId": "q_5_639071099835229691",
    "totalValue": 559
}

Release Notes

Version 1.0.1

• Initial release

Version 1.0.2

• Additional price validation
• Added setLocale function to hook

Version 1.0.3

• Added customerServiceEmail field to sale request
• Removed exports of internal context hooks

Version 2.0.1

• Upgrade to React 19
• Still supports React 18 apps

Version 2.1.1

• Upgrade axios version
• Added support for supplying multiple values in a quote request