Core Utilities and Helpers

This page focuses on core utilities and helpers that are used across various aspects of Limio development. These tools are designed to simplify common tasks and provide consistent functionality.

LimioAppSettings

LimioAppSettings is an object that provides access to global application settings. It offers getter methods for retrieving configured settings within components.

Available Methods

• getDateFormat(): Retrieves the configured date format.

Usage

import { LimioAppSettings } from "@limio/sdk";

const dateFormat = LimioAppSettings.getDateFormat();

Limio Component Props

Limio provides a hook and a helper function for managing component props.

useComponentProps

A hook that takes an object of optional default props and makes them available throughout the component.

getPropsFromPackageJson

A helper function that retrieves default values from the package.json file.

Usage

import package from "./package.json";
import { useComponentProps, getPropsFromPackageJson } from "@limio/sdk";

export function useComponentStaticProps() {
  const defaultComponentProps = getPropsFromPackageJson(package);
  const componentProps = useComponentProps(defaultComponentProps);
  return componentProps;
}

function Component() {
  const { title } = useComponentStaticProps();
  // Use title in your component
}

External Libraries

Limio exports some external libraries for common tasks:

• DateTime from Luxon: For date handling

If you need additional exports, please contact Limio support.

sanitiseHTML

An HTML sanitisation function that should be used whenever injecting content from offers into the DOM. It uses DOMPurify under the hood with an HTML profile and automatically adds security attributes to links (e.g. rel="noopener noreferrer" on target="_blank" links).

Important: Always use sanitiseHTML when rendering user-controlled or offer-sourced HTML content with dangerouslySetInnerHTML or similar patterns. This prevents XSS attacks from malicious content in offer attributes.

Function Signature

function sanitiseHTML(dirty?: string): string

Parameters

• dirty (optional): string - The HTML string to sanitise. Defaults to "".

Returns

• string - The sanitised HTML string, safe for DOM insertion.

Usage

import { sanitiseHTML } from "@limio/sdk"

const OfferFeatures = ({ offer }) => {
  const featuresHtml = offer.data.attributes.offer_features__limio

  return (
    <div dangerouslySetInnerHTML={{ __html: sanitiseHTML(featuresHtml) }} />
  )
}

Behaviour Notes

1. Strips all non-HTML-safe tags and attributes.

2. Preserves the target attribute on links.

3. Automatically adds rel="noopener noreferrer" to links with target="_blank", and rel="noopener" to links with other target values.

4. Throws an error if called in a non-browser environment without DOM support (a Node.js version is available internally for SSR).

ErrorBoundary

A React error boundary component that catches JavaScript errors in its child component tree and displays a fallback UI. Errors are automatically reported to Sentry.

Limio wraps individual components in an error boundary as part of the build step, so it is not necessary to use at the top level. However, ErrorBoundary is useful for wrapping specific children that may error where the parent component should remain functional.

Props

• children: React.ReactNode - The component tree to wrap.

• ErrorUI (optional): React.ComponentType<{ error: Error }> - A custom component to render when an error is caught. Defaults to a built-in error display.

Usage

import { ErrorBoundary } from "@limio/sdk"

const ParentComponent = ({ offer }) => {
  return (
    <div>
      <h1>This will always render</h1>
      <ErrorBoundary>
        <ChildThatMayError offer={offer} />
      </ErrorBoundary>
    </div>
  )
}

With a custom error UI:

import { ErrorBoundary } from "@limio/sdk"

const MyErrorFallback = ({ error }) => (
  <p>Something went wrong: {error.message}</p>
)

const Component = () => (
  <ErrorBoundary ErrorUI={MyErrorFallback}>
    <RiskyComponent />
  </ErrorBoundary>
)

Behaviour Notes

1. Catches errors during rendering, in lifecycle methods, and in constructors of child components.

2. Does not catch errors in event handlers — use try/catch for those.

3. Logs all caught errors to Sentry with component stack info.

4. A HOC version is also available: withErrorBoundary(Component, ErrorUI).

Formatters

Limio provides utility functions for formatting data:

formatDate

Formats an ISO date string into a human-readable date format based on the specified format type or the default Limio app locale settings.

import { formatDate } from "@limio/sdk/date";

const date = "2023-12-14T11:19:29.442Z";
const format = "DATE_EN";

const formattedDate = formatDate(date, format);

console.log(formattedDate); // Output: "14 Dec 2023"

Parameters:

• date: string An ISO 8601 date string (e.g., "2023-12-14T11:19:29.442Z") that represents the date and time to be formatted.

• format (optional): string A string representing the desired date format. Supported formats include:

  • "DATE_EN": "14 Dec 2023"

  • "DATE_FULL": "December 14, 2023"

  • "DATE_SHORT": "14/12/2023"

  • "DATE_MED": "Dec 14, 2023"

If not provided, the function defaults to the Limio app locale settings.

formatDisplayPrice

Formats a string by replacing placeholders with corresponding values from a given price object, allowing dynamic price information to be displayed in a consistent and customisable format.

import { formatDisplayPrice } from "@limio/sdk/price";

const priceString = "The price is {{currencySymbol}}{{amount}}.";
const offerPrice = [{ currencyCode: "USD", value: "10.99" }];

const formattedPrice = formatDisplayPrice(priceString, offerPrice);

console.log(formattedPrice); // Output: "The price is $10.99."

Parameters:

• string: string A template string containing placeholders (e.g., {{currencyCode}}, {{amount}}) to be replaced with values from the offerPrice object.

• offerPrice: Array<LimioPrice> An array of price objects, with the first element being used to extract pricing information.

formatCurrency

Formats a currency amount with the specified currency code.

import { formatCurrency } from "@limio/sdk";

const formattedAmount = formatCurrency(invoice.amount, subscriptionCurrency);

console.log(formattedAmount)  // Output: "$10.99"

Parameters:

• amount: string The amount to format

• currencyCode: string The currency code (e.g., 'USD', 'EUR')

• locality (optional): string Specifies the locale for formatting

formatCurrencyForCurrentLocale

Formats a currency amount using the user's current locale, determined from the limio-country cookie. This is a convenience wrapper around formatCurrency that automatically resolves the locale — use this when you want locale-aware formatting without manually specifying a locale.

import { formatCurrencyForCurrentLocale } from "@limio/sdk"

const PriceDisplay = ({ amount, currency }) => {
  const formatted = formatCurrencyForCurrentLocale(amount, currency)
  return <span>{formatted}</span>
}

// For a UK user: formatCurrencyForCurrentLocale(10.99, "GBP") → "£10.99"
// For a US user: formatCurrencyForCurrentLocale(10.99, "USD") → "$10.99"

Parameters:

• amount: number | string The amount to format.

• currency: string The ISO 4217 currency code (e.g., "GBP", "USD", "EUR").

Returns:

• A formatted currency string using the browser's Intl.NumberFormat API.

Use formatCurrency (documented above) if you need to specify a locale explicitly.

formatCountry

Converts an alpha-2 country code into the full name of the corresponding country. Useful for displaying country information in a user interface.

import { formatCountry } from "@limio/sdk/address";

const countryName = formatCountry("GB");

console.log(countryName); // Output: "United Kingdom"

Parameters:

• country: string (required) An alpha-2 country code (e.g., "GB" for the United Kingdom).

Returns:

• A string of the full name of the country corresponding to the provided alpha-2 country code. If the country code is not found, the return value might be undefined or an empty string.

addressSummary

Takes a Limio address object and returns a string consisting of the populated values. If no address values are found, the helper returns N/A.

import { addressSummary } from "@limio/sdk/address";

const addressString = addressSummary(customerDetails.deliveryAddress);
console.log(addressString); // Output: "123 John Street, London, EC1 25X"

Parameters:

• address: LimioAddressObject An object containing the address details.

Returns:

• A string representation of the address (e.g., "123 John Street, London, EC1 25X"), or "N/A" if no address values are found.

Address Helpers

Limio provides address helpers functions for retrieving address specific data, for all countries in the Limio Country list.

getAddressMetadata

Retrieves address metadata based on the provided alpha-2 country code, determining which address fields are required and which fields should be rendered in a form. Useful for creating dynamic forms that adjust input fields according to the selected country.

import { getAddressMetadata } from "@limio/sdk/address";

const { requiredAddressFields, addressFieldsToRender } = getAddressMetadata("CA");

console.log(requiredAddressFields) // Output: ["address1", "state", "postalCode", "country"]
console.log(addressFieldsToRender) // Output: ["address1", "address2", "city", "state", "postalCode", "country"]

Parameters:

• country: string An alpha-2 country code (e.g., "CA" for Canada). This code is used to look up country-specific address metadata.

Returns:

• AddressMetadata An object containing:

  • requiredAddressFields: string[]: Required fields (e.g., "address1", "city", "postalCode", "state", "country").

  • addressFieldsToRender: string[]: Fields to render in the form (e.g., "address1", "address2", "city", "state", "postalCode", "country").

getCountryMetadata

Retrieves and returns metadata related to a specific country based on the provided alpha-2 country code. Useful for accessing country-specific information such as the full country name, telephone country code, and more.

import { getCountryMetadata } from "@limio/sdk/address";

const countrySpecificMetadata = getCountryMetadata("GB");

Parameters:

• country: string An alpha-2 country code (e.g., "GB" for the United Kingdom).

Returns:

• CountryMetadataType An object containing metadata such as:

  • name: string: The full name of the country (e.g., "United Kingdom").

  • alpha-2: string: The alpha-2 country code (e.g., "GB").

  • alpha-3: string: The alpha-3 country code (e.g., "GBR").

  • country-code: string: The numeric country code (e.g., "826").

Example Output:

{
  "name": "United Kingdom",
  "alpha-2": "GB",
  "alpha-3": "GBR",
  "country-code": "826"
}

Offer Helpers

useOfferInfo

A small utility hook that extracts a few commonly needed fields from an offer object into a flat structure. Useful for avoiding repetitive deep property access on offer attributes.

Function Signature

function useOfferInfo(offer: LimioObject<Offer>): OfferInfo

Parameters

• offer: LimioObject<Offer> - The offer object to extract info from.

Returns

An OfferInfo object with the following fields:

Field	Type	Source
allowMultibuy	boolean	allow_multibuy__limio attribute
offerDescription	string	mma_description__limio attribute
hasRecurringCharge	boolean	true if any price has type: "recurring"
isDelivery	boolean	true if any product has has_delivery__limio
productNames	string[]	Array of product names
isAutoRenew	boolean	autoRenew__limio attribute
offerImage	Attachment	First image attachment
usesExternalPrice	boolean	use_external_price from first price
isGift	boolean	is_redeem_gift__limio attribute
displayName	string	Product display name, or offer group label as fallback

Usage

import { useOfferInfo } from "@limio/sdk"

const OfferCard = ({ offer }) => {
  const { displayName, hasRecurringCharge, isDelivery, productNames } = useOfferInfo(offer)

  return (
    <div>
      <h2>{displayName}</h2>
      <p>Products: {productNames.join(", ")}</p>
      {isDelivery && <p>Includes delivery</p>}
      {hasRecurringCharge && <p>Recurring subscription</p>}
    </div>
  )
}

checkActiveOffers

Filters an array of offers to return only those that are currently active based on their start and end dates. Offers are sorted by start date.

Function Signature

function checkActiveOffers(
  offers?: LimioObject<Offer>[],
  includeFuture?: boolean
): LimioObject<Offer>[]

Parameters

• offers (optional): LimioObject<Offer>[] - Array of offers to filter. Defaults to [].

• includeFuture (optional): boolean - When true, includes offers with a future start date. Defaults to false.

Returns

• LimioObject<Offer>[] - Filtered array of currently active offers, sorted by start date.

Filtering Logic

An offer is considered active when:

1. It has no end date, OR its end date is on or after the current date.

2. If includeFuture is false (default), the offer's start date must also be on or before the current date.

Usage

import { checkActiveOffers, useCampaign } from "@limio/sdk"

const ActiveOffers = () => {
  const { offers } = useCampaign()
  const activeOffers = checkActiveOffers(offers)

  return (
    <section>
      {activeOffers.map(offer => (
        <OfferCard key={offer.id} offer={offer} />
      ))}
    </section>
  )
}

Including future-dated offers (e.g. for showing upcoming subscription terms):

const allActiveAndFuture = checkActiveOffers(offers, true)

Fetchers

Limio provides wrapper functions for fetching data from external services.

LimioFetchers.invoiceFetch

Fetches invoice data from Zuora.

import { LimioFetchers } from "@limio/sdk";
import { useUser } from "@limio/sdk";

function fetchInvoice(id) {
  const { token } = useUser();
  const invoiceBlob = LimioFetchers.invoiceFetch(`api/plugins/zuora/invoices/file/${id}`, token);
  // Process the invoiceBlob
}