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.

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

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 strinf 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"
}

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
}