@blocklet/payment-react 1.20.4 → 1.20.6

package/docs/components-business-auto-topup.md

@@ -1,113 +1,175 @@
 # Auto-Topup Components
 
-The auto-topup feature allows users to automatically recharge their credit balance when it falls below a specified threshold, ensuring uninterrupted service. This functionality is primarily managed through two components: `AutoTopup` and `AutoTopupModal`.
+The auto-topup feature ensures uninterrupted service by automatically recharging a user's credit balance when it falls below a specified threshold. This is managed through two primary components: `AutoTopup`, which displays the current configuration, and `AutoTopupModal`, which provides the interface for setting it up.
 
-It is highly recommended to use the `AutoTopup` component directly. It provides a complete UI for displaying the configuration status and internally manages the `AutoTopupModal`, offering a simplified and seamless integration experience.
+## Auto-Topup Workflow
 
-> **Note on Session Management:** All examples in this section use a custom hook `useSessionContext()` to retrieve `session` and `connectApi`. This is a placeholder for your application's own authentication context. For detailed instructions on setting up the required `PaymentProvider` and session context, please refer to the [PaymentProvider documentation](./providers-payment-provider.md).
+The diagram below illustrates the typical user flow for configuring the auto-topup feature. The user interacts with the `AutoTopup` display component, which launches the `AutoTopupModal` for making changes. The modal then communicates with the backend API to save the configuration.
+
+```d2
+direction: down
+
+User: { 
+  shape: c4-person 
+}
+
+Application-UI: {
+  label: "Application UI"
+  shape: rectangle
+
+  AutoTopup-Card: {
+    label: "AutoTopup Component"
+    shape: rectangle
+  }
+
+  AutoTopup-Modal: {
+    label: "AutoTopupModal"
+    shape: rectangle
+  }
+}
+
+Payment-API: {
+  label: "Payment API"
+  shape: cylinder
+}
+
+User -> Application-UI.AutoTopup-Card: "1. Views auto-topup status"
+Application-UI.AutoTopup-Card -> Application-UI.AutoTopup-Modal: "2. Clicks 'Configure' to open modal"
+User -> Application-UI.AutoTopup-Modal: "3. Adjusts settings & saves"
+Application-UI.AutoTopup-Modal -> Payment-API: "4. Submit configuration" 
+Payment-API -> Payment-API: "5. Save configuration"
+Payment-API -> Application-UI.AutoTopup-Modal: "6. Return success"
+Application-UI.AutoTopup-Modal -> Application-UI.AutoTopup-Card: "7. Calls onSuccess, UI updates"
+
+```
 
 ## AutoTopup
 
-The `AutoTopup` component is the primary entry point for this feature. It serves as a display card for the current auto-recharge settings and handles the presentation of the configuration modal. It supports several rendering modes to fit different UI needs.
+The `AutoTopup` component is a display card that shows the current auto-recharge status for a specific currency and provides an entry point for configuration. It supports multiple rendering modes for flexibility.
+
+### Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `currencyId` | `string` | **Required.** The ID of the credit currency to manage. |
+| `onConfigChange` | `(config: AutoRechargeConfig) => void` | Optional. Callback function triggered when the configuration is successfully updated. |
+| `mode` | `'default' \| 'simple' \| 'custom'` | Optional. The rendering mode. Defaults to `'default'`.<br/>- `default`: A fully expanded card showing all details.<br/>- `simple`: A compact, collapsed view with a button to expand details.<br/>- `custom`: Renders a custom UI using the `children` render prop. |
+| `sx` | `SxProps` | Optional. Custom MUI styles to apply to the component. |
+| `children` | `(openModal, config, paymentData, loading) => React.ReactNode` | Optional. A render prop function used only when `mode` is `'custom'`. It receives the tools needed to build a custom interface. |
 
 ### Usage
 
-The component can be rendered in three different modes: `'default'`, `'simple'`, and `'custom'`.
+#### Simple Mode
 
--   **default**: Renders a fully expanded card with all details visible.
--   **simple**: Renders a collapsed card that can be expanded by the user to view details.
--   **custom**: Provides a render prop for complete control over the UI, allowing you to build a custom display.
+This is the most common use case, providing a compact display that users can expand for more details.
 
-```tsx
-import { AutoTopup, PaymentProvider } from '@blocklet/payment-react';
-import { useSessionContext } from '../hooks/session'; // Your custom session hook
+```tsx CreditManagement.tsx icon=logos:react
+import { PaymentProvider, AutoTopup } from '@blocklet/payment-react';
 
-function CreditManagementPage({ currencyId }) {
-  const { session, connectApi } = useSessionContext();
+function CreditManagement({ session, currencyId }) {
+  const handleConfigChange = (config) => {
+    console.log('Auto-topup config updated:', config);
+    // You might want to refresh the user's balance here
+  };
 
   return (
-    <PaymentProvider session={session} connect={connectApi}>
-      {/* Default mode - fully expanded */}
-      <AutoTopup
-        currencyId={currencyId}
-        onConfigChange={(config) => {
-          console.log('Auto-topup config updated:', config);
-        }}
-      />
-
-      {/* Simple mode - collapsed by default */}
+    <PaymentProvider session={session}>
       <AutoTopup
         currencyId={currencyId}
         mode="simple"
-        onConfigChange={(config) => {
-          console.log('Config updated:', config);
-        }}
+        onConfigChange={handleConfigChange}
+        sx={{ mt: 2 }}
       />
+    </PaymentProvider>
+  );
+}
+```
 
-      {/* Custom mode - full control over rendering */}
-      <AutoTopup
-        currencyId={currencyId}
-        mode="custom"
-      >
-        {(openModal, config, paymentData, loading) => (
-          <div>
-            {loading ? (
-              <div>Loading...</div>
-            ) : (
-              <div>
-                <h3>Auto Recharge Status: {config?.enabled ? 'Active' : 'Inactive'}</h3>
-                <button onClick={openModal}>Configure</button>
-              </div>
-            )}
-          </div>
-        )}
+#### Custom Mode
+
+For full control over the UI, use `custom` mode with a render prop. This allows you to integrate the auto-topup status and configuration trigger into your existing layout seamlessly.
+
+```tsx CustomAutoTopupDisplay.tsx icon=logos:react
+import { PaymentProvider, AutoTopup } from '@blocklet/payment-react';
+import { Button, Card, CardContent, Typography } from '@mui/material';
+
+function CustomAutoTopupDisplay({ session, currencyId }) {
+  return (
+    <PaymentProvider session={session}>
+      <AutoTopup currencyId={currencyId} mode="custom">
+        {(openModal, config, paymentData, loading) => {
+          if (loading) return <div>Loading configuration...</div>;
+
+          return (
+            <Card variant="outlined">
+              <CardContent>
+                <Typography variant="h6">Smart Auto-Recharge</Typography>
+                {config?.enabled ? (
+                  <Typography color="success.main">
+                    Status: Active
+                  </Typography>
+                ) : (
+                  <Typography color="text.secondary">
+                    Status: Inactive
+                  </Typography>
+                )}
+                <Button onClick={openModal} variant="contained" sx={{ mt: 2 }}>
+                  {config?.enabled ? 'Modify Settings' : 'Setup Now'}
+                </Button>
+              </CardContent>
+            </Card>
+          );
+        }}
       </AutoTopup>
     </PaymentProvider>
   );
 }
 ```
 
+## AutoTopupModal
+
+The `AutoTopupModal` is a dialog component that allows users to enable, disable, and configure all aspects of the auto-topup feature, including the trigger threshold, purchase amount, and payment method.
+
 ### Props
 
 | Prop | Type | Description |
 | --- | --- | --- |
-| `currencyId` | `string` | **Required.** The ID of the credit currency to configure auto-recharge for. |
-| `onConfigChange` | `(config: AutoRechargeConfig) => void` | Optional. A callback function that is triggered when the auto-recharge configuration is changed. |
-| `mode` | `'default' \| 'simple' \| 'custom'` | Optional. The rendering mode of the component. Defaults to `'default'`. |
-| `sx` | `SxProps` | Optional. Custom styles to be applied to the component using the MUI `sx` prop. |
-| `children` | `(openModal, config, paymentData, loading) => ReactNode` | Optional. A render prop function used only when `mode` is set to `'custom'`. It provides access to the modal trigger, configuration data, payment data, and loading state. |
-
-## AutoTopupModal
-
-The `AutoTopupModal` is a dialog component that allows users to enable, disable, and configure their auto-recharge settings. While it is integrated within the `AutoTopup` component, it can be used as a standalone component if you need to trigger the configuration from a custom UI element.
+| `open` | `boolean` | **Required.** Controls whether the modal is visible. |
+| `onClose` | `() => void` | **Required.** Callback function to close the modal. |
+| `currencyId` | `string` | **Required.** The ID of the credit currency being configured. |
+| `customerId` | `string` | Optional. The customer's DID. Defaults to the user from the `PaymentProvider` session. |
+| `onSuccess` | `(config: AutoRechargeConfig) => void` | Optional. Callback triggered after the configuration is successfully saved. |
+| `onError` | `(error: any) => void` | Optional. Callback triggered if an error occurs during submission. |
+| `defaultEnabled` | `boolean` | Optional. If `true`, the 'Enable Auto-Topup' switch will be on by default when the modal opens for a new configuration. |
 
 ### Usage
 
-You control the visibility of the modal using the `open` and `onClose` props. The `onSuccess` callback is fired when the configuration is saved successfully.
+Here is a complete example of how to manage the `AutoTopupModal`'s state and handle its callbacks.
 
-```tsx
-import { AutoTopupModal, PaymentProvider } from '@blocklet/payment-react';
+```tsx AutoRechargeSettings.tsx icon=logos:react
+import { PaymentProvider, AutoTopupModal } from '@blocklet/payment-react';
 import { useState } from 'react';
-import { useSessionContext } from '../hooks/session'; // Your custom session hook
+import { Button } from '@mui/material';
 
-function AutoRechargeSettings({ currencyId }) {
-  const { session, connectApi } = useSessionContext();
+function AutoRechargeSettings({ session, currencyId }) {
   const [isModalOpen, setModalOpen] = useState(false);
 
   const handleSuccess = (config) => {
-    console.log('Auto-recharge configured:', config);
+    console.log('Configuration saved successfully:', config);
     setModalOpen(false);
+    // Optionally, show a success toast or refresh data
   };
 
   const handleError = (error) => {
-    console.error('Configuration failed:', error);
+    console.error('Failed to save configuration:', error);
+    // Optionally, show an error message to the user
   };
 
   return (
-    <PaymentProvider session={session} connect={connectApi}>
-      <button onClick={() => setModalOpen(true)}>
-        Setup Auto-Recharge
-      </button>
+    <PaymentProvider session={session}>
+      <Button variant="contained" onClick={() => setModalOpen(true)}>
+        Configure Auto-Recharge
+      </Button>
 
       <AutoTopupModal
         open={isModalOpen}
@@ -115,124 +177,11 @@ function AutoRechargeSettings({ currencyId }) {
         currencyId={currencyId}
         onSuccess={handleSuccess}
         onError={handleError}
-        defaultEnabled={true} // Optionally, have the toggle enabled by default
+        defaultEnabled={true}
       />
     </PaymentProvider>
   );
 }
 ```
 
-### Props
-
-| Prop | Type | Description |
-| --- | --- | --- |
-| `open` | `boolean` | **Required.** Controls whether the modal is visible. |
-| `onClose` | `() => void` | **Required.** A callback function to close the modal. |
-| `currencyId` | `string` | **Required.** The ID of the credit currency to configure. |
-| `customerId` | `string` | Optional. The customer ID. Defaults to the user from the current session. |
-| `onSuccess` | `(config: AutoRechargeConfig) => void` | Optional. A callback function executed on successful configuration. |
-| `onError` | `(error: any) => void` | Optional. A callback function executed if an error occurs. |
-| `defaultEnabled` | `boolean` | Optional. Sets the initial state of the 'enable' switch in the modal. Useful for quick-setup flows. |
-
-### Configuration Flow
-
-The following diagram illustrates the process of configuring auto-topup, including the authorization step required for payment methods.
-
-```d2
-shape: sequence_diagram
-
-User: "User"
-AutoTopupCard: "AutoTopup Component"
-AutoTopupModal: "Configuration Modal"
-BackendAPI: "Backend API"
-
-User -> AutoTopupCard: "Clicks 'Configure' or 'Setup'"
-AutoTopupCard -> AutoTopupModal: "Opens modal"
-User -> AutoTopupModal: "Fills in threshold, amount, etc."
-User -> AutoTopupModal: "Clicks 'Save'"
-AutoTopupModal -> BackendAPI: "POST /api/auto-recharge-configs/submit"
-
-auth: {
-  label: "Authorization Required"
-  BackendAPI -> AutoTopupModal: "Returns auth data (e.g., Stripe client_secret)"
-  AutoTopupModal -> User: "Renders payment form (e.g., StripeForm)"
-  User -> AutoTopupModal: "Completes payment authorization"
-  AutoTopupModal -> BackendAPI: "Confirms authorization"
-}
-
-BackendAPI -> AutoTopupModal: "Returns success response with new config"
-AutoTopupModal -> AutoTopupCard: "Fires onSuccess callback"
-AutoTopupModal -> User: "Closes modal"
-AutoTopupCard -> BackendAPI: "Refreshes configuration data"
-AutoTopupCard -> User: "Displays updated status"
-```
-
-## Complete Integration Example
-
-Here is a complete example of a credit management dashboard that integrates the `AutoTopup` component to manage multiple credit currencies. This demonstrates the recommended approach of letting `AutoTopup` handle the modal's presentation.
-
-```tsx
-import {
-  PaymentProvider,
-  AutoTopup,
-  CustomerInvoiceList,
-  Amount
-} from '@blocklet/payment-react';
-import { useState, useEffect } from 'react';
-import { Grid, Card, CardContent, Typography } from '@mui/material';
-import { useSessionContext } from '../hooks/session'; // Your custom session hook
-
-function CreditDashboard() {
-  const { session, connectApi } = useSessionContext();
-  const [creditCurrencies, setCreditCurrencies] = useState([]);
-
-  useEffect(() => {
-    // In a real app, you would fetch the user's available credit currencies
-    const fetchCurrencies = async () => {
-      const currencies = await fetchCreditCurrencies(); // Your API call
-      setCreditCurrencies(currencies);
-    };
-    
-    if (session.user) {
-      fetchCurrencies();
-    }
-  }, [session.user]);
-
-  const handleAutoTopupChange = (currencyId, config) => {
-    console.log(`Auto-topup updated for ${currencyId}:`, config);
-    // You might want to refetch currency data here
-  };
-
-  return (
-    <PaymentProvider session={session} connect={connectApi}>
-      <Grid container spacing={3}>
-        {creditCurrencies.map((currency) => (
-          <Grid item xs={12} md={6} key={currency.id}>
-            <Card>
-              <CardContent>
-                <Typography variant="h6">{currency.name} Balance</Typography>
-                <Typography variant="h4" color="primary">
-                  <Amount
-                    amount={currency.balance}
-                    decimal={currency.decimal}
-                    symbol={currency.symbol}
-                  />
-                </Typography>
-                
-                <AutoTopup
-                  currencyId={currency.id}
-                  mode="simple"
-                  onConfigChange={(config) => handleAutoTopupChange(currency.id, config)}
-                  sx={{ mt: 2 }}
-                />
-              </CardContent>
-            </Card>
-          </Grid>
-        ))}
-      </Grid>
-    </PaymentProvider>
-  );
-}
-```
-
-This setup provides a robust and user-friendly interface for managing credit balances and auto-recharge settings within your application.
+This setup provides a robust way to manage auto-recharge functionality, giving users control while ensuring a smooth experience for maintaining their service credits.