Utilities

The @blocklet/payment-react library exports a suite of utility functions and classes designed to simplify common tasks such as making API requests, managing cache, handling dates, formatting prices, and setting up internationalization. These tools are built to work seamlessly with the library's components and providers.

API Client#

The library provides a pre-configured Axios instance for making API requests to your payment backend. It automatically handles base URLs and other necessary configurations.

API Client Usage

import { api } from '@blocklet/payment-react';

// Basic GET request
const getPayments = async () => {
  const response = await api.get('/api/payments');
  return response.data;
};

// POST request with a payload
const createCheckout = async (amount) => {
  const data = await api.post('/api/checkout', { amount });
  return data;
};

// GET request with query parameters
const getPaidInvoices = async () => {
  const results = await api.get('/api/invoices', { 
    params: { status: 'paid' } 
  });
  return results.data;
};

// PUT request with additional configuration
const updateSubscription = async (data) => {
  const config = {

See all 5 lines

CachedRequest#

To optimize performance and reduce redundant network requests, you can use the CachedRequest class. It provides a simple way to cache data with configurable strategies and time-to-live (TTL).

Configuration Options#

When creating a CachedRequest instance, you can provide the following options:

Option

Type

Description

Default

strategy

'session' | 'local' | 'memory'

The storage mechanism for the cache.

'session'

ttl

number

The cache's time-to-live in milliseconds. A value of 0 means no expiration.

0

Usage Example#

Here’s how to create and use a cached request to fetch product prices.

CachedRequest Example

import { CachedRequest, api } from '@blocklet/payment-react';

// 1. Create a cached request instance
const priceRequest = new CachedRequest(
  'product-prices', 
  () => api.get('/api/prices'),
  {
    strategy: 'session',  // Cache data in sessionStorage
    ttl: 5 * 60 * 1000   // Cache for 5 minutes
  }
);

// 2. Use the cached request in your component
async function fetchPrices() {
  // This will use the cache if it's available and not expired
  const prices = await priceRequest.fetch();
  
  // To bypass the cache and force a fresh data fetch
  const freshPrices = await priceRequest.fetch(true);
  
  return prices;
}

// 3. Clear the cache when data changes
async function updatePrices() {

See all 3 lines

Date Handling#

The library re-exports a pre-configured dayjs instance with useful plugins like relativeTime, utc, and timezone already included. You can use this for any date and time manipulation needs.

Date Handling with dayjs

import { dayjs } from '@blocklet/payment-react';

// Format the current date
const formattedDate = dayjs().format('YYYY-MM-DD HH:mm');

// Parse a timestamp
const dateFromTimestamp = dayjs(1672531200000);
const unixTimestamp = dateFromTimestamp.unix();

// Calculate relative time
const fiveMinutesAgo = dayjs().subtract(5, 'minute');
const relativeTime = dayjs().from(fiveMinutesAgo); // "5 minutes ago"

Internationalization (i18n)#

@blocklet/payment-react includes built-in support for i18n. You can create your own translator or merge your translations with the library's defaults.

Creating a Translator#

Use the createTranslator function to set up your own translation instance.

Custom Translator Setup

import { createTranslator } from '@blocklet/payment-react';

const myTranslations = {
  en: { 
    checkout: { title: 'Complete Payment' }
  },
  zh: { 
    checkout: { title: '完成支付' }
  }
};

const translator = createTranslator({ fallbackLocale: 'en' }, myTranslations);

translator('checkout.title', 'zh'); // '完成支付'

Merging with Library Translations#

To leverage the library's built-in translations for components while adding your own, you can merge them together.

Merging Translations

import { translations as paymentTranslations } from '@blocklet/payment-react';
import merge from 'lodash/merge';

// Your application's translations
import en from './locales/en';
import zh from './locales/zh';

export const translations = merge(
  {
    en,
    zh,
  },
  paymentTranslations
);

Formatting Utilities#

Several helper functions are available to format data for display.

Function

Description

formatPrice

Formats a price object into a human-readable string, considering recurring intervals.

formatRecurring

Formats a recurring object into strings like "monthly" or "every 3 months".

formatBNStr

Formats a BigNumber string from a base unit into a token value with specified precision.

formatNumber

Formats a number or string with thousand separators and precision.

formatError

Parses various error formats (GraphQL, Joi, Axios) into a readable string.

Formatting Example

import { formatNumber, formatRecurring } from '@blocklet/payment-react';

// Format a number
const formatted = formatNumber('1234567.89123', 2); // "1,234,567.89"

// Format a recurring interval
const monthly = formatRecurring({ interval: 'month', interval_count: 1 }); // "per month"
const quarterly = formatRecurring({ interval: 'month', interval_count: 3 }); // "Quarterly"

Validation Utilities#

The library also includes helpers for form validation.

validatePostalCode#

Checks if a given postal code is valid for a specific country.

Postal Code Validation

import { validatePostalCode } from '@blocklet/payment-react';

// Returns true
const isValidUS = validatePostalCode('90210', 'US');

// Returns false
const isInvalidUS = validatePostalCode('ABC-123', 'US');

// Returns true for a UK postal code
const isValidGB = validatePostalCode('SW1A 0AA', 'GB');
Theming
Hooks