@blocklet/payment-react 1.20.5 → 1.20.7

package/docs/components-business-overdue-invoice-payment.md

@@ -1,205 +1,186 @@
 # OverdueInvoicePayment
 
-The `OverdueInvoicePayment` component is designed to handle the payment of overdue invoices for a specific customer or subscription. It can operate in two modes: a default dialog mode that presents a pre-built UI for payment, or a custom mode that provides data and a payment handler to build a custom user interface.
+The `OverdueInvoicePayment` component is a specialized tool designed to handle the payment of overdue invoices for a specific customer or subscription. It simplifies the process by automatically fetching overdue invoices and presenting users with a clear interface to settle their outstanding payments.
 
-This component streamlines the process of collecting late payments by summarizing amounts by currency and initiating a batch payment process through the user's DID Wallet.
+This component can operate in two modes: a default mode that displays a pre-built dialog for quick integration, and a custom mode that provides the flexibility to build a unique user interface using a render prop.
 
-## When to Use
+## How It Works
 
-Use this component in your application's subscription management or customer billing sections to:
+The component orchestrates the entire overdue payment process, from fetching data to handling the final transaction confirmation.
 
-- Prompt users to pay for a subscription that has fallen into a `past_due` status.
-- Allow customers to clear all outstanding invoices across multiple subscriptions in a single operation.
+```d2 Overdue Payment Flow
+direction: down
 
-## Component Logic Flow
+User: { 
+  shape: c4-person 
+}
+
+Client-App: {
+  label: "Client Application"
+  shape: rectangle
 
-The component follows a clear sequence to manage overdue payments:
+  OverdueInvoicePayment-Component: {
+    label: "OverdueInvoicePayment Component"
+    shape: rectangle
+  }
+}
 
-```d2
-shape: sequence_diagram
+Payment-Backend: {
+  label: "Payment Backend"
+  shape: cylinder
+}
 
-User: "User"
-App: "Your Application"
-OIP: "OverdueInvoicePayment"
-PaymentProvider: "PaymentProvider"
-API: "Payment Service API"
+DID-Wallet: {
+  label: "DID Wallet"
+  icon: "https://www.arcblock.io/image-bin/uploads/37198ddc4a0b9e91e5c1c821ab895a34.svg"
+}
 
-User -> App: "Views page with overdue invoices"
-App -> OIP: "Renders with subscriptionId or customerId"
-OIP -> API: "GET /overdue/invoices"
-API -> OIP: "Returns summary & invoices list"
+User -> Client-App.OverdueInvoicePayment-Component: "1. Renders the component"
+Client-App.OverdueInvoicePayment-Component -> Payment-Backend: "2. Fetch overdue invoices"
+Payment-Backend -> Client-App.OverdueInvoicePayment-Component: "3. Return invoice summary"
+Client-App.OverdueInvoicePayment-Component -> User: "4. Display payment dialog"
+User -> Client-App.OverdueInvoicePayment-Component: "5. Clicks 'Pay Now'"
+Client-App.OverdueInvoicePayment-Component -> DID-Wallet: "6. Opens connect session (collect-batch)"
+User -> DID-Wallet: "7. Approves payment"
+DID-Wallet -> Client-App.OverdueInvoicePayment-Component: "8. Sends success callback"
+Payment-Backend -> Client-App.OverdueInvoicePayment-Component: "9. WebSocket event (invoice.paid)"
+Client-App.OverdueInvoicePayment-Component -> User: "10. Update UI (e.g., close dialog)"
 
-alt "Invoices exist"
-  OIP -> App: "Renders payment UI (dialog/custom)"
-  User -> OIP: "Clicks 'Pay Now'"
-  OIP -> PaymentProvider: "Calls connect.open()"
-  PaymentProvider -> User: "Shows DID Wallet connect modal"
-  User -> PaymentProvider: "Scans & confirms payment"
-  PaymentProvider -> API: "Processes batch payment"
-  API -> PaymentProvider: "Payment successful"
-  PaymentProvider -> OIP: "Triggers onSuccess"
-  OIP -> OIP: "Refreshes invoice data"
-  OIP -> App: "Calls onPaid() & closes UI"
-else "No overdue invoices"
-  OIP -> App: "Displays success/empty message"
-end
 ```
 
 ## Props
 
+The `OverdueInvoicePayment` component accepts the following props to customize its behavior:
+
 | Prop | Type | Description |
-| --- | --- | --- |
-| `subscriptionId` | `string` | Optional. The ID of the subscription to check for overdue invoices. Either `subscriptionId` or `customerId` must be provided. |
-| `customerId` | `string` | Optional. The customer's ID (or DID) to check for all overdue invoices across their subscriptions. |
-| `mode` | `'default' \| 'custom'` | Optional. The rendering mode. `'default'` displays a pre-built dialog. `'custom'` uses a render prop for a custom UI. Defaults to `'default'`. |
-| `onPaid` | `(id, currencyId, type) => void` | Optional. A callback function executed after all overdue invoices are paid. It receives the source ID (`subscriptionId` or `customerId`), the currency ID, and the source type (`'subscription'` or `'customer'`). |
-| `dialogProps` | `object` | Optional. Props to pass to the underlying Material-UI `Dialog` component in `default` mode. Can be used to control its `open` state, `title`, and `onClose` behavior. |
-| `detailLinkOptions` | `object` | Optional. An object to configure the "view details" link in the default dialog. Shape: `{ enabled?: boolean, onClick?: (e) => void, title?: string }`. |
-| `successToast` | `boolean` | Optional. If `true`, a success toast notification is shown upon successful payment. Defaults to `true`. |
-| `alertMessage` | `string` | Optional. A custom message to append to the default alert text when checking by `customerId`. |
-| `children` | `function` | Optional. A render prop function used only when `mode="custom"`. It receives `handlePay` and `data` as arguments. |
-| `authToken` | `string` | Optional. An authentication token for API requests, useful for cross-origin scenarios where session cookies are not available. |
+|---|---|---|
+| `subscriptionId` | `string` | The ID of the subscription to check for overdue invoices. Either `subscriptionId` or `customerId` must be provided. |
+| `customerId` | `string` | The ID or DID of the customer. Use this to handle all overdue invoices for a customer. |
+| `mode` | `'default'` \| `'custom'` | The rendering mode. `'default'` shows a pre-built dialog. `'custom'` uses the `children` render prop for a custom UI. Defaults to `'default'`. |
+| `onPaid` | `(id, currencyId, type) => void` | An optional callback function that is triggered after payment is successfully completed. `id` will be the `subscriptionId` or `customerId`, `type` will be `'subscription'` or `'customer'`. |
+| `dialogProps` | `object` | Optional props to pass to the underlying Material-UI `Dialog` component in `default` mode. e.g., `{ open: true, title: 'Custom Title', onClose: handleClose }`. |
+| `detailLinkOptions` | `object` | Optional settings for the "View Details" link. Can be used to disable the link, change its text, or provide a custom `onClick` handler. Format: `{ enabled?: boolean, onClick?: function, title?: string }`. |
+| `successToast` | `boolean` | If `true`, a success toast notification is shown upon successful payment. Defaults to `true`. |
+| `alertMessage` | `string` | An optional message to append to the default title text when in customer mode. |
+| `children` | `(handlePay, data) => React.ReactNode` | A render prop function used only when `mode` is `'custom'`. It receives a `handlePay` function and a `data` object. |
+| `authToken` | `string` | An optional authentication token for API requests, useful for server-to-server or cross-origin scenarios. |
 
-## Usage
+### `children` Render Prop
 
-> All examples assume you have set up `PaymentProvider` and a `useSessionContext` hook to provide session data. The `useSessionContext` hook is a local utility to access your application's session context. For a complete guide on this setup, please refer to the [PaymentProvider documentation](./providers-payment-provider.md).
+When using `mode="custom"`, the `children` function receives two arguments:
 
-### Default Mode Usage
+1.  **`handlePay(item: SummaryItem)`**: A function to initiate the payment process for a specific currency group. The `item` object comes from the `data.summary` object.
+2.  **`data`**: An object containing the fetched payment information:
+    *   `subscription?: Subscription`: The subscription details, if `subscriptionId` was provided.
+    *   `summary: { [key: string]: SummaryItem }`: An object where each key is a currency ID and the value contains the total amount, currency details, and payment method.
+    *   `invoices: Invoice[]`: An array of all overdue invoice objects.
+    *   `subscriptionCount?: number`: The number of subscriptions with overdue invoices (for customer mode).
+    *   `detailUrl: string`: The URL to view detailed invoice information.
 
-In its default mode, the component renders a dialog that summarizes the overdue payments and prompts the user to pay. This is the quickest way to implement overdue payment handling.
+## Usage Examples
 
-#### Handling a Single Subscription's Overdue Invoices
+All examples assume you have `PaymentProvider` set up in your application.
 
-Provide the `subscriptionId` to target a specific subscription. A dialog will appear if there are any overdue invoices.
+### 1. Default Mode for a Subscription
 
-```tsx
-import { PaymentProvider, OverdueInvoicePayment } from '@blocklet/payment-react';
-// This is a local utility to get session info from your app's context.
-// See the PaymentProvider docs for setup details.
-import { useSessionContext } from 'src/hooks/session';
+This is the simplest way to handle overdue payments for a specific subscription. The component will automatically render a dialog if any overdue invoices are found.
 
-function SubscriptionDetailsPage({ subscriptionId }) {
-  const { session, connect: connectApi } = useSessionContext();
+```tsx SubscriptionOverdue.tsx icon=logos:react
+import { OverdueInvoicePayment, PaymentProvider } from '@blocklet/payment-react';
+import { useSessionContext } from './hooks/session'; // Your custom session hook
 
-  const handlePaymentSuccess = () => {
-    console.log('All overdue invoices for the subscription have been paid.');
-    // You can refresh the subscription status here
-  };
+function SubscriptionPage({ subscriptionId }) {
+  const { session, connect } = useSessionContext();
 
-  if (!session || !connectApi) {
-    return <div>Loading session...</div>;
-  }
+  const handlePaymentSuccess = (id, currencyId, type) => {
+    console.log(`Payment successful for ${type} ${id} with currency ${currencyId}`);
+    // You can refetch subscription data here to update its status
+  };
 
   return (
-    <PaymentProvider session={session} connect={connectApi}>
+    <PaymentProvider session={session} connect={connect}>
+      {/* This component will be null if there are no overdue invoices */}
       <OverdueInvoicePayment
         subscriptionId={subscriptionId}
         onPaid={handlePaymentSuccess}
       />
+      {/* Other subscription details can be rendered here */}
     </PaymentProvider>
   );
 }
 ```
 
-#### Handling All of a Customer's Overdue Invoices
+### 2. Default Mode for a Customer
 
-Provide the `customerId` (which can be the user's DID) to consolidate all overdue invoices from all of their subscriptions into a single payment flow.
+Use this to create a centralized place for a customer to pay all their overdue invoices across multiple subscriptions.
 
-```tsx
-import { PaymentProvider, OverdueInvoicePayment } from '@blocklet/payment-react';
-// This is a local utility to get session info from your app's context.
-// See the PaymentProvider docs for setup details.
-import { useSessionContext } from 'src/hooks/session';
+```tsx CustomerDashboard.tsx icon=logos:react
+import { OverdueInvoicePayment, PaymentProvider } from '@blocklet/payment-react';
+import { useSessionContext } from './hooks/session'; // Your custom session hook
 
 function CustomerDashboard() {
-  const { session, connect: connectApi } = useSessionContext();
-
-  if (!session?.user?.did || !connectApi) {
-    return <div>Loading session...</div>;
-  }
+  const { session, connect } = useSessionContext();
 
   return (
-    <PaymentProvider session={session} connect={connectApi}>
+    <PaymentProvider session={session} connect={connect}>
+      <h2>Payment Center</h2>
+      <p>Please settle any outstanding payments to ensure uninterrupted service.</p>
       <OverdueInvoicePayment
         customerId={session.user.did}
         onPaid={() => {
-          console.log("All of the customer's overdue invoices are paid.");
-          // Refresh customer data or redirect
-        }}
-        dialogProps={{
-          title: 'Outstanding Payments',
+          console.log('All customer overdue invoices paid for a currency!');
+          // Refresh customer account status
         }}
       />
+      {/* The rest of the customer dashboard */}
     </PaymentProvider>
   );
 }
 ```
 
-### Custom Mode Usage
-
-For full control over the user interface, set `mode="custom"`. This allows you to build a completely custom component for handling overdue payments using the `children` render prop.
-
-The render prop receives two arguments:
-1.  `handlePay`: A function to trigger the payment process. It takes a `SummaryItem` object as an argument.
-2.  `data`: An object containing all the necessary information about the overdue invoices.
+### 3. Custom UI Mode
 
-#### Building a Custom UI
+For full control over the user experience, use `mode="custom"`. This allows you to integrate the payment functionality directly into your existing UI instead of using a dialog.
 
-Here is an example of creating a custom card to display overdue payment information and trigger payments.
-
-```tsx
-import {
-  PaymentProvider,
-  OverdueInvoicePayment,
-  Amount,
-} from '@blocklet/payment-react';
+```tsx CustomOverdueUI.tsx icon=logos:react
+import { OverdueInvoicePayment, PaymentProvider, Amount } from '@blocklet/payment-react';
+import { useSessionContext } from './hooks/session'; // Your custom session hook
 import { Card, CardContent, Typography, Button, Stack } from '@mui/material';
-// This is a local utility to get session info from your app's context.
-// See the PaymentProvider docs for setup details.
-import { useSessionContext } from 'src/hooks/session';
 
 function CustomOverdueUI({ subscriptionId }) {
-  const { session, connect: connectApi } = useSessionContext();
-
-  if (!session || !connectApi) {
-    return <div>Loading session...</div>;
-  }
+  const { session, connect } = useSessionContext();
 
   return (
-    <PaymentProvider session={session} connect={connectApi}>
+    <PaymentProvider session={session} connect={connect}>
       <OverdueInvoicePayment
         subscriptionId={subscriptionId}
         mode="custom"
-        onPaid={() => console.log('Paid!')}>
-        {(handlePay, { summary, invoices, subscription }) => {
-          if (!invoices || invoices.length === 0) {
-            return <Typography>No overdue payments. All good!</Typography>;
+        onPaid={() => console.log('Custom UI payment successful!')}
+      >
+        {(handlePay, { summary, invoices }) => {
+          const summaryList = Object.values(summary);
+          if (invoices.length === 0) {
+            return <Typography>No overdue payments. All clear!</Typography>;
           }
 
           return (
             <Card variant="outlined">
               <CardContent>
-                <Typography variant="h6" gutterBottom>
-                  Action Required for {subscription?.description}
-                </Typography>
-                <Typography color="error" gutterBottom>
+                <Typography variant="h6" color="error" gutterBottom>
                   You have {invoices.length} overdue invoice(s).
                 </Typography>
-                <Stack spacing={2} sx={{ mt: 2 }}>
-                  {Object.values(summary).map((info) => (
-                    <Stack
-                      key={info.currency.id}
-                      direction="row"
-                      justifyContent="space-between"
-                      alignItems="center">
+                <Stack spacing={2} mt={2}>
+                  {summaryList.map((item) => (
+                    <Stack key={item.currency.id} direction="row" justifyContent="space-between" alignItems="center">
                       <Typography>
-                        Total Due: <Amount amount={info.amount} decimal={info.currency.decimal} symbol={info.currency.symbol} />
+                        Total Due: <Amount amount={item.amount} decimal={item.currency.decimal} symbol={item.currency.symbol} />
                       </Typography>
                       <Button
-                        onClick={() => handlePay(info)}
                         variant="contained"
-                        color="primary">
-                        Pay Now
+                        color="primary"
+                        onClick={() => handlePay(item)}
+                      >
+                        Pay with {item.currency.symbol}
                       </Button>
                     </Stack>
                   ))}
@@ -213,19 +194,3 @@ function CustomOverdueUI({ subscriptionId }) {
   );
 }
 ```
-
-#### Custom Mode `data` Object
-
-The `data` object passed to the `children` render prop contains the following fields:
-
-| Field | Type | Description |
-| --- | --- | --- |
-| `subscription` | `Subscription` | The full subscription object, if `subscriptionId` was provided. |
-| `summary` | `{ [key: string]: SummaryItem }` | An object summarizing the total amount due, grouped by currency ID. Each `SummaryItem` contains `amount`, `currency`, and `method`. |
-| `invoices` | `Invoice[]` | An array of the raw overdue invoice objects. |
-| `subscriptionCount` | `number` | The number of subscriptions with overdue payments, if `customerId` was provided. |
-| `detailUrl` | `string` | A pre-generated URL to the detailed invoice or subscription page. |
-
-### Note on Payment Methods
-
-The batch payment flow initiated by this component currently supports wallet-based payments (like ArcBlock, Ethereum). It does not support batch payments via Stripe. If an overdue invoice's payment method is Stripe, the component will guide the user to a page where they can pay manually.