@blocklet/payment-react/docs/guides-utilities.md

Reusable react components for payment kit v2

# 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.

```tsx API Client Usage icon=logos:javascript
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 = { 
    headers: { 'Custom-Header': 'value' }
  };
  const response = await api.put('/api/subscription', data, config);
  return response.data;
};
```

## 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.

```tsx CachedRequest Example icon=logos:javascript
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() {
  await api.post('/api/prices', newPriceData);
  priceRequest.clearCache(); // Or await priceRequest.fetch(true);
}
```

## 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.

```tsx Date Handling with dayjs icon=logos:javascript
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.

```tsx Custom Translator Setup icon=logos:javascript
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.

```tsx Merging Translations icon=logos:javascript
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. |

```tsx Formatting Example icon=logos:javascript
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.

```tsx Postal Code Validation icon=logos:javascript
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');
```