@blocklet/payment-react 1.20.5 → 1.20.6

package/docs/components-business-resume-subscription.md

@@ -1,176 +1,189 @@
 # ResumeSubscription
 
-The `ResumeSubscription` component provides a user interface for resuming a canceled subscription. It handles the necessary logic, including prompting the user to re-stake funds if required, and appears as a modal dialog by default.
+The `ResumeSubscription` component provides a straightforward UI for users to resume a canceled subscription. It renders a dialog that guides the user through the confirmation process and automatically handles complex scenarios like re-staking if the subscription requires it.
 
-This component must be used within a [`PaymentProvider`](./providers-payment-provider.md) to access the required payment context.
+This component must be used within a `PaymentProvider` to access the necessary context for handling wallet interactions.
 
-## How It Works
+## Workflow
 
-The component streamlines the subscription recovery process. When rendered, it first checks if the subscription requires a new stake to be resumed. Based on this information, it presents one of two flows:
-
-1.  **Direct Resume**: If no new stake is needed, the user can confirm to directly reactivate the subscription.
-2.  **Resume with Re-Stake**: If a stake is required, the component will initiate a wallet connection flow, asking the user to approve the staking transaction to resume their subscription.
+The following diagram illustrates the process flow when a user resumes a subscription, including the conditional logic for re-staking.
 
 ```d2
 shape: sequence_diagram
 
-User
-"React App"
-"ResumeSubscription"
-"Payment API"
-"DID Wallet"
+User: { shape: c4-person }
+ResumeSubscription: { label: "ResumeSubscription Component" }
+PaymentAPI: { label: "Payment API" }
+DIDWallet: { label: "DID Wallet" }
 
-User -> "React App": "Clicks 'Resume Subscription'"
-"React App" -> "ResumeSubscription": "Renders with subscriptionId"
+User -> ResumeSubscription: "1. Triggers resume"
+ResumeSubscription -> PaymentAPI: "2. GET /recover-info"
+PaymentAPI -> ResumeSubscription: "3. Return status\n(e.g., needStake: true)"
 
-"ResumeSubscription" -> "Payment API": "GET /recover-info"
-"Payment API" --> "ResumeSubscription": "{ needStake }"
+ResumeSubscription.t1 -> User: "4. Show confirmation dialog"
+User -> ResumeSubscription.t1: "5. Confirm"
 
-alt "Direct Resume (needStake is false)" {
-  "ResumeSubscription" -> "Payment API": "PUT /recover"
-  "Payment API" --> "ResumeSubscription": "{ subscription }"
+alt "Re-Staking Required" {
+  ResumeSubscription.t1 -> DIDWallet: "6a. Open re-stake session"
+  User -> DIDWallet: "7a. Approve"
+  DIDWallet -> ResumeSubscription.t1: "8a. Success callback"
 }
 
-alt "Re-Stake Required (needStake is true)" {
-  "ResumeSubscription" -> "DID Wallet": "Opens connect for 're-stake'"
-  User -> "DID Wallet": "Approves transaction"
-  "DID Wallet" --> "ResumeSubscription": "onSuccess()"
+alt "No Staking Required" {
+  ResumeSubscription.t1 -> PaymentAPI: "6b. PUT /recover"
+  PaymentAPI -> ResumeSubscription.t1: "7b. Success"
 }
 
-"ResumeSubscription" -> "Payment API": "GET /subscriptions/:id (on success)"
-"Payment API" --> "ResumeSubscription": "Updated subscription data"
-"ResumeSubscription" -> "React App": "onResumed(subscription)"
-"React App" -> User: "UI is updated"
+ResumeSubscription.t1 -> PaymentAPI: "9. Fetch updated subscription"
+PaymentAPI -> ResumeSubscription.t1: "10. Return subscription"
+ResumeSubscription.t1 -> User: "11. Call onResumed() & close dialog"
+
 ```
 
+
 ## Props
 
-| Prop             | Type                                                     | Description                                                                                                                                                                                                                                                            |
-| :--------------- | :------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `subscriptionId` | `string`                                                 | **Required.** The ID of the subscription to be resumed.                                                                                                                                                                                                                |
-| `onResumed`      | `(sub: Subscription \| TSubscriptionExpanded) => void` | Optional. A callback function that is executed after the subscription has been successfully resumed. It receives the updated subscription object as an argument.                                                                                                        |
-| `dialogProps`    | `object`                                                 | Optional. Props to customize the underlying Material-UI Dialog component. Default: `{ open: true }`. Key properties include:<br />- `open`: `boolean`, controls visibility.<br />- `onClose`: `() => void`, a callback for when the dialog is closed.<br />- `title`: `string`, overrides the default dialog title. | 
-| `successToast`   | `boolean`                                                | Optional. If `true`, a success toast notification is shown upon successful resumption. Defaults to `true`.                                                                                                                                                                  |
-| `authToken`      | `string`                                                 | Optional. An authentication token to be included in API requests. This is useful for cross-origin requests or when the application manages authentication separately.                                                                                                |
+| Prop             | Type                                                     | Required | Description                                                                                                                              |
+| ---------------- | -------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `subscriptionId` | `string`                                                 | Yes      | The unique identifier of the subscription to be resumed.                                                                                 |
+| `onResumed`      | `(subscription: Subscription) => void`                   | No       | A callback function that is triggered after the subscription is successfully resumed. It receives the updated subscription object as an argument. |
+| `dialogProps`    | `object`                                                 | No       | Props to customize the underlying Material-UI Dialog. You can control its state (`open`, `onClose`) and appearance (`title`).            |
+| `successToast`   | `boolean`                                                | No       | If `true`, a success notification toast is displayed upon successful resumption. Defaults to `true`.                                   |
+| `authToken`      | `string`                                                 | No       | An optional authentication token for API requests. This is useful for cross-origin or server-to-server integration scenarios.            |
 
 ## Usage Examples
 
-<div class="lead">All examples require the component to be wrapped in a `PaymentProvider`. The `session` and `connect` props are obtained using a custom `useSessionContext` hook, which represents your application's authentication state. For detailed setup instructions, please refer to the <a href="/providers/payment-provider">PaymentProvider documentation</a>.</div>
-
 ### Basic Usage
 
-This example shows the simplest way to use `ResumeSubscription`. The dialog will be open by default, and a success toast will appear upon completion.
+This is the simplest way to use the component. It will render an open dialog by default.
 
-```tsx
-import React from 'react';
-import { PaymentProvider, ResumeSubscription } from '@blocklet/payment-react';
+```tsx Basic ResumeSubscription Example icon=logos:react
+import { ResumeSubscription } from '@blocklet/payment-react';
 
-// Placeholder for your application's session context hook.
-// See the PaymentProvider documentation for setup details.
-import { useSessionContext } from '../hooks/use-session-context';
+function ResumePage({ subscriptionId }) {
+  // This component must be rendered within a PaymentProvider
+  return <ResumeSubscription subscriptionId={subscriptionId} />;
+}
+```
 
-function SubscriptionManagementPage({ subscriptionId, refetchSubscription }) {
-  // session and connect are derived from your application's auth service.
-  const { session, connect } = useSessionContext();
+### Handling the Result
 
-  if (!session) {
-    return <div>Loading session...</div>;
-  }
+Use the `onResumed` callback to receive the updated subscription data and refresh your application's state.
+
+```tsx Handling the onResumed Callback icon=logos:react
+import { ResumeSubscription } from '@blocklet/payment-react';
+import { useState } from 'react';
+
+function SubscriptionDetails({ initialSubscription }) {
+  const [subscription, setSubscription] = useState(initialSubscription);
+
+  const handleSubscriptionResumed = (updatedSubscription) => {
+    console.log('Subscription has been successfully resumed:', updatedSubscription);
+    setSubscription(updatedSubscription);
+    // You can also show a confirmation message or redirect the user.
+  };
 
   return (
-    <PaymentProvider session={session} connect={connect}>
+    <div>
+      {/* Display subscription details based on the `subscription` state */}
       <ResumeSubscription
-        subscriptionId={subscriptionId}
-        onResumed={(subscription) => {
-          console.log('Subscription resumed:', subscription);
-          // Update your application's state here.
-          refetchSubscription();
-        }}
+        subscriptionId={subscription.id}
+        onResumed={handleSubscriptionResumed}
       />
-    </PaymentProvider>
+    </div>
   );
 }
 ```
 
 ### Controlling the Dialog
 
-You can manage the dialog's visibility from a parent component by passing its state down through `dialogProps`.
+For a more practical integration, control the dialog's visibility from a parent component. This allows you to open it in response to a user action, like clicking a button.
 
-```tsx
-import React, { useState } from 'react';
+```tsx Triggering ResumeSubscription with a Button icon=logos:react
+import { ResumeSubscription } from '@blocklet/payment-react';
+import { useState } from 'react';
 import { Button } from '@mui/material';
-import { PaymentProvider, ResumeSubscription } from '@blocklet/payment-react';
 
-// Placeholder for your application's session context hook.
-// See the PaymentProvider documentation for setup details.
-import { useSessionContext } from '../hooks/use-session-context';
+function SubscriptionActions({ subscriptionId }) {
+  const [isModalOpen, setIsModalOpen] = useState(false);
 
-function SubscriptionDetails({ subscriptionId, refetchSubscription }) {
-  const [isResumeDialogOpen, setResumeDialogOpen] = useState(false);
-  const { session, connect } = useSessionContext();
-
-  const handleCloseDialog = () => {
-    setResumeDialogOpen(false);
+  const handleResumed = () => {
+    setIsModalOpen(false);
+    // Refetch subscription data to update UI
+    alert('Subscription resumed!');
   };
 
-  if (!session) {
-    return <div>Loading session...</div>;
-  }
-
   return (
-    <PaymentProvider session={session} connect={connect}>
-      <Button onClick={() => setResumeDialogOpen(true)}>
+    <>
+      <Button variant="contained" onClick={() => setIsModalOpen(true)}>
         Resume Subscription
       </Button>
 
-      {isResumeDialogOpen && (
+      {isModalOpen && (
         <ResumeSubscription
           subscriptionId={subscriptionId}
-          onResumed={() => {
-            console.log('Subscription has been resumed.');
-            handleCloseDialog();
-            refetchSubscription(); // Refresh subscription data in parent component.
-          }}
+          onResumed={handleResumed}
           dialogProps={{
-            open: isResumeDialogOpen,
-            onClose: handleCloseDialog,
+            open: isModalOpen,
             title: 'Confirm Subscription Renewal',
+            onClose: () => setIsModalOpen(false),
           }}
         />
       )}
-    </PaymentProvider>
+    </>
   );
 }
 ```
 
-### Usage with an Authentication Token
+## Full Integration Example
 
-If your API requests require an authentication token, provide it using the `authToken` prop. This is useful for secure communication between different services or Blocklets.
+Here is a complete example showing how to integrate `ResumeSubscription` within the required `PaymentProvider`.
 
-```tsx
-import React from 'react';
+```tsx Complete Integration Example icon=logos:react
 import { PaymentProvider, ResumeSubscription } from '@blocklet/payment-react';
+import { useSessionContext } from 'path/to/your/session/context'; // Your app's session context
+import { useState } from 'react';
+import { Button, Card, CardContent, Typography } from '@mui/material';
 
-// Placeholder for your application's session context hook.
-// See the PaymentProvider documentation for setup details.
-import { useSessionContext } from '../hooks/use-session-context';
-
-function SecureSubscriptionResume({ subscriptionId, token }) {
+function SubscriptionManagementPage({ subscription }) {
   const { session, connect } = useSessionContext();
+  const [isResumeOpen, setIsResumeOpen] = useState(false);
 
-  if (!session) {
-    return <div>Loading session...</div>;
-  }
+  const handleResumed = (updatedSubscription) => {
+    console.log('Subscription updated:', updatedSubscription);
+    setIsResumeOpen(false);
+    // Ideally, you would trigger a data refetch here to update the entire page.
+  };
 
   return (
     <PaymentProvider session={session} connect={connect}>
-      <ResumeSubscription
-        subscriptionId={subscriptionId}
-        authToken={token}
-        onResumed={(subscription) => {
-          console.log('Subscription resumed securely:', subscription.id);
-        }}
-      />
+      <Card>
+        <CardContent>
+          <Typography variant="h5">Manage Your Subscription</Typography>
+          <Typography color="text.secondary">Status: {subscription.status}</Typography>
+
+          {subscription.status === 'canceled' && (
+            <Button
+              variant="contained"
+              color="primary"
+              sx={{ mt: 2 }}
+              onClick={() => setIsResumeOpen(true)}>
+              Resume Subscription
+            </Button>
+          )}
+        </CardContent>
+      </Card>
+
+      {isResumeOpen && (
+        <ResumeSubscription
+          subscriptionId={subscription.id}
+          onResumed={handleResumed}
+          dialogProps={{
+            open: isResumeOpen,
+            onClose: () => setIsResumeOpen(false),
+          }}
+        />
+      )}
     </PaymentProvider>
   );
 }

package/docs/components-business.md

@@ -1,45 +1,21 @@
 # Business Logic Components
 
-Business logic components are specialized React components designed to handle complex, high-level user flows related to subscription and invoice management. These components encapsulate API calls, state management, and user interactions for common scenarios, allowing you to integrate sophisticated features with minimal effort.
+Business Logic Components are specialized React components designed to handle complex, stateful operations related to subscription and invoice management. These components encapsulate entire user flows, such as paying overdue invoices or resuming a canceled subscription, making it easy to integrate advanced functionalities into your application with minimal setup.
 
-These components are ready to be integrated into your application to address specific business needs, such as recovering revenue from failed payments or improving user retention.
+They are built on top of the core library features and often interact with the Payment Service API to perform actions and reflect state changes.
 
-```d2
-direction: down
-
-"User Application": {
-  shape: cloud
-}
-
-"Business Logic Components": {
-  shape: package
-  "OverdueInvoicePayment"
-  "ResumeSubscription"
-  "Auto-Topup Components"
-}
-
-"Payment Service API": {
-  shape: database
-}
-
-"User Application" -> "Business Logic Components": "Integrates"
-"Business Logic Components.OverdueInvoicePayment" -> "Payment Service API": "Pays for overdue invoices"
-"Business Logic Components.ResumeSubscription" -> "Payment Service API": "Reactivates subscription"
-"Business Logic Components.Auto-Topup Components" -> "Payment Service API": "Configures auto-recharge"
-```
-
-This section provides an overview of the available business logic components. For detailed API references and usage examples, select a component below.
-
-<x-cards data-columns="3">
-  <x-card data-title="OverdueInvoicePayment" data-icon="lucide:alert-circle" data-href="/components/business/overdue-invoice-payment">
-    A component that provides a complete UI flow for handling overdue invoices for a subscription or an entire customer account.
+<x-cards data-columns="2">
+  <x-card data-title="OverdueInvoicePayment" data-icon="lucide:file-warning" data-href="/components/business/overdue-invoice-payment">
+    A component to handle the payment of overdue invoices for a specific customer or subscription, presenting a dialog with payment options.
   </x-card>
-  <x-card data-title="ResumeSubscription" data-icon="lucide:refresh-cw" data-href="/components/business/resume-subscription">
-    A component that facilitates resuming a previously canceled subscription, including handling complex scenarios like re-staking.
+  <x-card data-title="ResumeSubscription" data-icon="lucide:play-circle" data-href="/components/business/resume-subscription">
+    Allows a user to resume a canceled subscription. It handles the necessary API calls and re-staking logic if required.
   </x-card>
-  <x-card data-title="Auto-Topup Components" data-icon="lucide:battery-charging" data-href="/components/business/auto-topup">
-    A set of components for managing automatic credit top-ups when a user's balance falls below a configured threshold.
+  <x-card data-title="Auto-Topup Components" data-icon="lucide:zap" data-href="/components/business/auto-topup">
+    A set of components for managing and configuring automatic credit top-ups, including a display card and a configuration modal.
   </x-card>
 </x-cards>
 
-After handling these business-specific tasks, you may want to display the results to the user. Proceed to the [History Components](./components-history.md) section to learn how to display lists of invoices, payments, and credit transactions.
+### Next Steps
+
+After integrating these business logic components, you might want to display historical data to your users. Proceed to the [History Components](./components-history.md) section to learn how to list invoices, payments, and credit transactions.