@blocklet/payment-react 1.18.6 → 1.18.8

package/README.md

@@ -1,13 +1,32 @@
-# Payment Kit Components
+# @blocklet/payment-react
 
-## Quick Start
+[![npm version](https://img.shields.io/npm/v/@blocklet/payment-react)](https://www.npmjs.com/package/@blocklet/payment-react)
+
+A React component library for building payment flows, subscriptions, and donation systems in Blocklet applications. Seamlessly integrated with Blocklet's payment infrastructure.
+
+## Features
+
+- 🛠️ **Pre-built UI Components**: Includes checkout forms, pricing tables, donation widgets, and more
+- 🎨 **Customizable Themes**: Full control over styling via Material-UI themes
+- 🌍 **i18n Support**: Built-in localization for global audiences
+- 🧩 **Lazy Loading**: Optimize bundle size with dynamic imports
+- 💳 **Payment Operations**: Handle subscriptions, refunds, invoices, and metered billing
+
+## Related Links
+
+- [Payment Kit Documentation](https://www.arcblock.io/docs/arcblock-payment-kit/en/start-payment-react) - Official documentation with detailed guides and API references
+- [Example Implementation](https://github.com/blocklet/payment-kit/blob/master/blocklets/example/src/pages/checkout.jsx) - Complete example showing how to integrate the payment components
+
+## Installation
 
-### 1. Installation
 ```bash
-npm install @blocklet/payment-react @mui/material @emotion/react @emotion/styled
+npm install @blocklet/payment-react 
 ```
 
-### 2. Basic Setup
+## Quick Start
+
+### Basic Integration
+
 ```tsx
 import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
 
@@ -15,314 +34,428 @@ function App() {
   return (
     <PaymentProvider session={session} connect={connectApi}>
       <CheckoutForm 
-        id="plink_xxx"
-        mode="inline"
+        id="plink_xxx" // Payment Link ID
+        mode="inline"  // Embed directly in your UI
         showCheckoutSummary={true}
-        onChange={(state) => console.log(state)}
+        onChange={(state) => console.log('Checkout State:', state)}
       />
     </PaymentProvider>
   );
 }
 ```
 
-## Component Usage
+## Available Components & Utilities
 
 ### Core Components
+- `CheckoutForm` - Payment form for checkout sessions and payment links
+- `CheckoutTable` - Pricing table display
+- `CheckoutDonate` - Donation widget
+- `OverdueInvoicePayment` - Handle overdue invoice payments
 
-```tsx
-import { CheckoutForm, CheckoutTable, CheckoutDonate, PaymentProvider } from '@blocklet/payment-react';
-
-// Checkout with session
-<CheckoutForm 
-  id="cs_xxx"
-  mode="inline"
-  showCheckoutSummary={true}
-  onChange={(state) => console.log(state)}
-/>
+### Form Components
+- `FormInput` - Base form input component
+- `PhoneInput` - Phone number input with validation
+- `AddressForm` - Complete address form
+- `StripeForm` - Stripe payment form
+- `CurrencySelector` - Currency selection dropdown
+- `CountrySelect` - Country selection dropdown
 
-// Checkout with payment link
-<CheckoutForm 
-  id="plink_xxx"
-  mode="inline"
-/>
+### Display Components
+- `Status` - Status indicator
+- `Livemode` - Test mode indicator
+- `Switch` - Toggle switch
+- `ConfirmDialog` - Confirmation dialog
+- `Amount` - Amount display with formatting
+- `TruncatedText` - Text truncation
+- `Link` - Safe navigation link
 
-// Pricing table
-<CheckoutTable 
-  id="prctbl_xxx"
-  mode="inline"
-/>
+### UI Components
 
-// Donation form
-<CheckoutDonate
-  mode="inline"
-  settings={{
-    target: 'donation-target',
-    title: 'Support Us',
-    description: 'Help us continue our work',
-    beneficiaries: [{
-      address: 'wallet_address',
-      share: '100'
-    }],
-    amount: {
-      minimum: '0.01',
-      maximum: '1',
-      custom: true
+```tsx
+// Loading Button with state management
+import { LoadingButton } from '@blocklet/payment-react';
+
+function PaymentButton() {
+  const [loading, setLoading] = useState(false);
+  
+  const handlePayment = async () => {
+    setLoading(true);
+    try {
+      await processPayment();
+    } finally {
+      setLoading(false);
     }
-  }}
-/>
-```
+  };
 
-### Form Components
+  return (
+    <LoadingButton
+      loading={loading}
+      onClick={handlePayment}
+      variant="contained"
+      color="primary"
+    >
+      Pay Now
+    </LoadingButton>
+  );
+}
+```
 
-```tsx
-import { 
-  FormInput,
-  PhoneInput,
-  AddressForm,
-  CurrencySelector,
-  CountrySelect
-} from '@blocklet/payment-react';
+### Transaction Components
+- `TxLink` - Transaction link
+- `TxGas` - Gas fee display
+- `PaymentBeneficiaries` - Payment beneficiaries list
 
-// Phone input with validation
-<PhoneInput
-  name="phone"
-  countryFieldName="billing_address.country"
-/>
+### History Components
+- `CustomerInvoiceList` - Invoice history list
+- `CustomerPaymentList` - Payment history list
 
-// Address form
-<AddressForm
-  mode="required"
-  stripe={false}
-  sx={{}}
-/>
+### Context Providers
+- `PaymentProvider` - Payment context provider
+- `DonateProvider` - Donation context provider
+- `PaymentThemeProvider` - Theme provider
 
-// Currency selector
-<CurrencySelector
-  value={0}
-  onChange={(index) => {}}
-  currencies={[
-    {
-      id: 'currency_id',
-      symbol: '$',
-      logo: 'currency_logo_url',
-      name: 'USD',
-      method: { name: 'Payment Method' }
-    }
-  ]}
-/>
+### Hooks
+- `useSubscription` - event socket callback
+- `useMobile` - Mobile detection
 
-// Country select
-<CountrySelect
-  value="us"
-  onChange={(value: CountryIso2) => {}}
-  name="country"
-  sx={{}}
-/>
-```
-
-### Display Components
+### Utilities
 
+#### API Client
 ```tsx
-import {
-  PricingItem,
-  TruncatedText,
-  TxGas,
-  TxLink,
-  ProductSkeleton,
-} from '@blocklet/payment-react';
+import { api } from '@blocklet/payment-react';
 
-// Display pricing information
-<PricingItem 
-  productId="prod_xxx"
-  quantity={1}
-  priceId="price_xxx"
->
-  {(pricing, product) => (
-    <div>
-      <div>Total: {pricing.totalPrice}</div>
-      <div>Product: {product?.name}</div>
-    </div>
-  )}
-</PricingItem>
-
-// Display transaction gas fee
-<TxGas 
-  details={paymentDetails}
-  method={paymentMethod}
-/>
-
-// Display transaction link
-<TxLink 
-  details={paymentDetails}
-  method={paymentMethod}
-  mode="dashboard"
-  align="left"
-/>
+// Basic usage
+const response = await api.get('/api/payments');
+const data = await api.post('/api/checkout', { amount: 100 });
 
-// Loading skeleton
-<ProductSkeleton />
+// With query parameters
+const results = await api.get('/api/invoices', { 
+  params: { status: 'paid' } 
+});
 
-// Truncate long text
-<TruncatedText 
-  text="Very long text..." 
-  maxLength={20} 
-/>
+// With request config
+const config = { 
+  headers: { 'Custom-Header': 'value' }
+};
+const response = await api.put('/api/subscription', data, config);
 ```
 
-### Donation Components
+#### Cached Request
+```tsx
+import { CachedRequest } from '@blocklet/payment-react';
+
+// Create a cached request
+const priceRequest = new CachedRequest(
+  'product-prices', 
+  () => api.get('/api/prices'),
+  {
+    strategy: 'session',  // 'session' | 'local' | 'memory'
+    ttl: 5 * 60 * 1000   // Cache for 5 minutes
+  }
+);
+
+// Use the cached request
+async function fetchPrices() {
+  // Will use cache if available and not expired
+  const prices = await priceRequest.fetch();
+  
+  // Force refresh cache
+  const freshPrices = await priceRequest.fetch(true);
+  
+  return prices;
+}
+```
 
+#### Date Handling
 ```tsx
-import { CheckoutDonate } from '@blocklet/payment-react';
+import { dayjs } from '@blocklet/payment-react';
 
-// Basic usage
-<CheckoutDonate
-  mode="default"  // 'default' | 'inline' | 'custom'
-  settings={{
-    target: 'donation-target',
-    title: 'Support Us',
-    description: 'Help us continue our work',
-    beneficiaries: [{
-      address: 'wallet_address',
-      share: '100'
-    }],
-    amount: {
-      minimum: '0.01',
-      maximum: '100',
-      custom: true
-    },
-    appearance: {
-      button: {
-        text: 'Donate Now',
-        icon: <FavoriteIcon />,
-        size: 'large',
-        color: 'primary',
-        variant: 'contained'
-      },
-      history: {
-        variant: 'avatar'  // 'avatar' | 'table'
-      }
-    }
-  }}
-/>
+// Format dates
+const formatted = dayjs().format('YYYY-MM-DD');
 
-// Custom render mode
-<CheckoutDonate
-  mode="custom"
-  settings={{
-    target: 'custom-donation',
-    // ... other settings
-  }}
->
-  {(openDonate, totalAmount, supporters, loading) => (
-    <div>
-      {loading && <div>Loading...</div>}
-      <button onClick={openDonate}>
-        Support Us
-      </button>
-      <div>Total Donations: {totalAmount}</div>
-      <div>Supporters: {supporters.supporters.length}</div>
-      {supporters.supporters.map(supporter => (
-        <div key={supporter.id}>
-          <img src={supporter.customer?.avatar} alt={supporter.customer?.name} />
-          <span>{supporter.customer?.name}</span>
-          <span>{formatAmount(supporter.amount_total, supporters.currency.decimal)} {supporters.currency.symbol}</span>
-        </div>
-      ))}
-    </div>
-  )}
-</CheckoutDonate>
+// Parse timestamps
+const date = dayjs(timestamp);
+const unix = date.unix();
+
+// Relative time
+const relative = dayjs().from(date);
 ```
 
-### Lazy Loading Components
+#### i18n Setup
+```tsx
+// use your own translator
+import { createTranslator } from '@blocklet/payment-react';
+
+const translator = createTranslator({
+  en: { 
+    checkout: { title: 'Complete Payment' }
+  },
+  zh: { 
+    checkout: { title: '完成支付' }
+  }
+});
 
-The SDK provides `createLazyComponent` for optimizing bundle size by loading components and their dependencies on demand:
+// use payment-react locales
+import { translations as extraTranslations } from '@blocklet/payment-react';
+import merge from 'lodash/merge';
 
+import en from './en';
+import zh from './zh';
+
+export const translations = merge(
+  {
+    zh,
+    en,
+  },
+  extraTranslations
+);
+```
+
+#### Lazy Loading
 ```tsx
 import { createLazyComponent } from '@blocklet/payment-react';
 
-// 1. Create lazy component with dependencies
 const LazyComponent = createLazyComponent(async () => {
-  // Load dependencies in parallel
-  const [dep1, dep2] = await Promise.all([
-    import('heavy-dependency-1'),
-    import('heavy-dependency-2')
+  const [{ Component }, { useHook }] = await Promise.all([
+    import('./Component'),
+    import('./hooks')
   ]);
+  
+  globalThis.__DEPENDENCIES__ = { useHook };
+  return Component;
+});
+```
 
-  // Store dependencies for reuse
-  const dependencies = {
-    Component1: dep1.Component1,
-    Component2: dep1.Component2,
-    useHook1: dep2.useHook1,
-    useHook2: dep2.useHook2,
-  };
+## Complete Examples
 
-  // Make dependencies available to child components
-  globalThis.__DEPENDENCIES__ = dependencies;
+### Donation Page Example
 
-  // Load and return the actual component that uses these dependencies
-  const { default: Component } = await import('./MyComponent');
-  return Component;
-});
+```tsx
+import { 
+  DonateProvider, 
+  CheckoutDonate,
+  PaymentProvider 
+} from '@blocklet/payment-react';
+import { useEffect, useState } from 'react';
+
+function DonationPage() {
+  const [session, setSession] = useState(null);
 
-// 2. Use dependencies in your component
-// Access loaded dependencies
-const { 
-  Component1, 
-  Component2,
-  useHook1,
-  useHook2 
-} = globalThis.__DEPENDENCIES__;
-function MyComponent(props) {
-  // Use hooks from dependencies
-  const hook1Result = useHook1();
-  const hook2Result = useHook2();
+  useEffect(() => {
+    // Get session from your auth system
+    const getSession = async () => {
+      const userSession = await fetchSession();
+      setSession(userSession);
+    };
+    getSession();
+  }, []);
 
   return (
-    <div>
-      <Component1 {...hook1Result} />
-      <Component2 {...hook2Result} />
-    </div>
+    <PaymentProvider session={session} connect={connectApi}>
+      <DonateProvider 
+        mountLocation="your-unique-donate-instance"
+        description="Help locate this donation instance"
+        defaultSettings={{
+          btnText: 'Like',
+        }}
+      >
+        <CheckoutDonate
+          settings={{
+            target: "post-123", // required, unique identifier for the donation instance
+            title: "Support Author", // required, title of the donation modal
+            description: "If you find this article helpful, feel free to buy me a coffee", // required, description of the donation 
+            reference: "https://your-site.com/posts/123", // required, reference link of the donation 
+            beneficiaries: [
+              {
+                address: "tip user did", // required, address of the beneficiary
+                share: "100",  // required, percentage share
+              },
+            ],
+          }}
+        />
+
+        {/* Custom donation history display */}
+        <CheckoutDonate
+          mode="custom"
+          settings={{
+            target: "post-123", // required, unique identifier for the donation instance
+            title: "Support Author", // required, title of the donation modal
+            description: "If you find this article helpful, feel free to buy me a coffee", // required, description of the donation 
+            reference: "https://your-site.com/posts/123", // required, reference link of the donation 
+            beneficiaries: [
+              {
+                address: "tip user did", // required, address of the beneficiary
+                share: "100",  // required, percentage share
+              },
+            ],
+          }}
+        >
+          {(openDonate, totalAmount, supporters, loading, settings) => (
+            <div>
+              <h2>Our Supporters</h2>
+              {loading ? (
+                <CircularProgress />
+              ) : (
+                <div>
+                  <div>
+                    Total Donations: {totalAmount} {supporters.currency?.symbol}
+                  </div>
+                  <div>
+                    {supporters.supporters.map(supporter => (
+                      <div key={supporter.id}>
+                        <span>{supporter.customer?.name}</span>
+                        <span>{supporter.amount_total} {supporters.currency?.symbol}</span>
+                      </div>
+                    ))}
+                  </div>
+                </div>
+              )}
+            </div>
+          )}
+        </CheckoutDonate>
+      </DonateProvider>
+    </PaymentProvider>
   );
 }
+```
 
-// 3. Use the lazy component
-function App() {
+### Subscription Management Example
+
+- `OverdueInvoicePayment` component
+  - Display overdue invoices for a subscription, and support batch payment
+  - props:
+    - `subscriptionId`: [required] The subscription ID
+    - `onPaid`: [optional] Callback function called after successful payment
+    - `mode`: [optional] Component mode, `default` or `custom` (default is `default`)
+    - `dialogProps`: [optional] Dialog properties, default is `{ open: true }`
+    - `children`: [optional] Custom rendering with payment data when `mode` is `custom`
+  - Custom mode:
+    - `children` will receive two parameters:
+      - `handlePay`: Function to start the
+
+ payment process
+      - `data`: Payment data (includes `subscription`, `summary`, `invoices`, `subscriptionUrl`)
+```tsx
+import {
+  PaymentProvider,
+  OverdueInvoicePayment,
+  CustomerInvoiceList,
+  Amount
+} from '@blocklet/payment-react';
+
+function SubscriptionPage({ subscriptionId }) {
   return (
-    <LazyComponent 
-      prop1="value1"
-      prop2="value2"
-      onEvent={() => {}}
-    />
+    <PaymentProvider session={session}>
+      {/* Handle overdue payments */}
+      <OverdueInvoicePayment
+        subscriptionId={subscriptionId}
+        onPaid={() => {
+          // Refresh subscription status
+          refetchSubscription();
+        }}
+      />
+
+      {/* Custom Overdue Invoice Payment */}
+      <OverdueInvoicePayment
+        subscriptionId={subscriptionId}
+        onPaid={() => {
+          refetchSubscription();
+        }}
+        mode="custom"
+      >
+        {(handlePay, { subscription, summary, invoices }) => (
+          <Card>
+            <CardHeader title="Overdue Payments" />
+            <CardContent>
+              <Stack spacing={2}>
+                {Object.entries(summary).map(([currencyId, info]) => (
+                  <div key={currencyId}>
+                    <Typography>
+                      Due Amount: 
+                      <Amount
+                        amount={info.amount}
+                      />
+                      {info.currency?.symbol}
+                    </Typography>
+                    <Button
+                      onClick={() => handlePay(info)}
+                      variant="contained"
+                    >
+                      Pay Now
+                    </Button>
+                  </div>
+                ))}
+              </Stack>
+            </CardContent>
+          </Card>
+        )}
+      </OverdueInvoicePayment>
+
+      {/* Display invoice history */}
+      <CustomerInvoiceList
+        subscription_id={subscriptionId}
+        type="table"
+        include_staking
+        status="open,paid,uncollectible,void"
+      />
+    </PaymentProvider>
   );
 }
 ```
 
-Key features:
-- 🚀 Loads dependencies on demand
-- 📦 Reduces initial bundle size
-- 🌐 Provides global access to loaded dependencies
-- ⚡️ Supports parallel loading
-- 🔄 Handles async initialization
-- ❌ Built-in error handling
+## Best Practices
 
-## Theme Customization
+### Cache Management
+```tsx
+// 1. Choose appropriate cache strategy
+const shortLivedCache = new CachedRequest('key', fetchData, {
+  strategy: 'memory',
+  ttl: 60 * 1000 // 1 minute
+});
 
-Since version 1.14.22, the component includes a built-in theme provider. If you need to modify the styles of internal components, you need to pass the `theme` property to override or inherit the external theme.
+const persistentCache = new CachedRequest('key', fetchData, {
+  strategy: 'local',
+  ttl: 24 * 60 * 60 * 1000 // 1 day
+});
 
-| option | description |
-| --- | --- |
-| default [default value] | wrapped with built-in PaymentThemeProvider |
-| inherit | use the parent component's themeProvider |
-| PaymentThemeOptions | override some styles of PaymentThemeProvider |
+// 2. Clear cache when data changes
+async function updateData() {
+  await api.post('/api/data', newData);
+  await cache.fetch(true); // Force refresh
+}
 
-```ts
-export type PaymentThemeOptions = ThemeOptions & {
-  sx?: SxProps;
-};
+// 3. Handle cache errors
+try {
+  const data = await cache.fetch();
+} catch (err) {
+  console.error('Cache error:', err);
+  // Fallback to fresh data
+  const fresh = await cache.fetch(true);
+}
 ```
 
+### Bundle Optimization
+- Use lazy loading for non-critical components
+- Import only required components
+- Leverage code splitting with dynamic imports
+
+### Theme Consistency
+- Maintain consistent styling across components
+- Use theme provider for global style changes
+- Override styles at component level when needed
+
+### Theme Customization
+
+Since version 1.14.22, the component includes a built-in theme provider. If you need to modify the styles of internal components, pass the `theme` property to override or inherit the external theme.
+
+| Option | Description |
+| --- | --- |
+| default | Wrapped with built-in `PaymentThemeProvider` |
+| inherit | Use the parent component's themeProvider |
+| PaymentThemeOptions | Override some styles of `PaymentThemeProvider` |
+
 ```tsx
-// 1. use themeOptions
+// 1. Use themeOptions
 <CheckoutForm
   id="plink_xxx"
   onChange={console.info}
@@ -343,7 +476,7 @@ export type PaymentThemeOptions = ThemeOptions & {
   }}
 />
 
-// 2. use theme sx
+// 2. Use theme sx
 <CheckoutForm
   id="plink_xxx"
   showCheckoutSummary={false}
@@ -362,73 +495,6 @@ export type PaymentThemeOptions = ThemeOptions & {
 />
 ```
 
-## I18n Support
-
-```tsx
-import { createTranslator, translations as extraTranslations } from '@blocklet/payment-react';
-import merge from 'lodash/merge';
-
-import en from './en';
-import zh from './zh';
-
-export const translations = merge({ zh, en }, extraTranslations);
-```
-
-## Recent Updates
-
-### v1.14.23
-We recommend using `showCheckoutSummary={false}` instead of `mode=inline-minimal` for better semantics:
-
-```tsx
-// Recommended
-<CheckoutForm
-  id="plink_xxx"
-  showCheckoutSummary={false}
-  onChange={console.info}
-/>
-
-// Not recommended
-<CheckoutForm
-  id="plink_xxx"
-  mode="inline-minimal"
-  onChange={console.info}
-/>
-```
-
-### v1.16.4
-
-- Add `OverdueInvoicePayment` component
-  - display all overdue invoices of a subscription, and support batch payment
-  - props:
-    - `subscriptionId`: [required] the id of the subscription
-    - `onPaid`: [optional] a callback function that will be called when the payment is successful
-    - `mode`: [optional] the mode of the component, `default` or `custom`, default is `default`
-    - `dialogProps`: [optional] the props of the dialog, default is `{ open: true }`
-    - `children`: [optional] a function that will be called with the payment data, if `mode` is `custom`, otherwise, the default dialog will be displayed
-  - custom mode:
-    - the `children` will receive two parameters:
-      - `handlePay`: a function that starts the payment process
-      - `data`: the payment data
-        - `subscription`: the subscription data
-        - `summary`: the summary of the payment, the key is the `currencyId`, the value includes `amount`, `currency`, `method`
-        - `invoices`: the list of invoices
-        - `subscriptionUrl`: the url of the subscription
-```tsx
-<OverdueInvoicePayment subscriptionId={data.id} onPaid={() => { console.log('paid') }} />
-
-// custom mode
-<OverdueInvoicePayment subscriptionId={data.id} onPaid={() => { console.log('paid') }} mode="custom">
-  {(handlePay, { subscription, summary, invoices, subscriptionUrl }) => (
-    <div>custom content</div>
-    <p>Subscription: {subscription.name}</p>
-    <p>Current currency Total: {summary[currencyId].amount}</p>
-    <p>Invoices: {invoices.length}</p>
-    <p>Subscription URL: {subscriptionUrl}</p>
-    <button onClick={() => handlePay(summary[currencyId])}>Pay</button>
-  )}
-</OverdueInvoicePayment>
-```
-
 ### Status & Utility Components
 ```tsx
 import { 
@@ -447,33 +513,20 @@ import {
   sx={{ margin: 1 }}
 />
 
-// Live/Test mode indicator
-<Livemode livemode={false} />
+// Test mode indicator
+<Livemode />
 
 // Custom switch button
 <Switch
   checked={true}
   onChange={(checked) => console.log('Switched:', checked)}
-  size="small"
-  color="primary"
 />
 
 // Safe navigation link
-<Link
-  href="https://example.com"
-  confirmBeforeNavigate={true}
-  confirmMessage="Are you sure to leave?"
-  target="_blank"
-/>
+<Link to="/demo" />
+
+
+## License
+
+Apache-2.0
 
-// Amount display with formatting
-<Amount
-  value={1000}
-  currency={{
-    symbol: '$',
-    decimal: 2
-  }}
-  variant="body1"
-  color="primary"
-/>
-```