@blocklet/payment-react 1.20.16 → 1.20.18

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

@@ -0,0 +1,190 @@
+# ResumeSubscription
+
+`ResumeSubscription` 元件為使用者提供了一個簡單明瞭的使用者介面，以便恢復已取消的訂閱。它會渲染一個對話方塊，引導使用者完成確認過程，並在訂閱需要時自動處理重新質押等複雜情境。
+
+此元件必須在 `PaymentProvider` 中使用，才能存取處理錢包互動所需的必要上下文。
+
+## 工作流程
+
+下圖說明了使用者恢復訂閱時的流程，包括重新質押的條件邏輯。
+
+```d2
+shape: sequence_diagram
+
+User: { shape: c4-person }
+ResumeSubscription: { label: "ResumeSubscription 元件" }
+PaymentAPI: { label: "Payment API" }
+DIDWallet: { label: "DID 錢包" }
+
+User -> ResumeSubscription: "1. 觸發恢復"
+ResumeSubscription -> PaymentAPI: "2. GET /recover-info"
+PaymentAPI -> ResumeSubscription: "3. 返回狀態\n(例如：needStake: true)"
+
+ResumeSubscription.t1 -> User: "4. 顯示確認對話方塊"
+User -> ResumeSubscription.t1: "5. 確認"
+
+alt "需要重新質押" {
+  ResumeSubscription.t1 -> DIDWallet: "6a. 開啟重新質押會話"
+  User -> DIDWallet: "7a. 批准"
+  DIDWallet -> ResumeSubscription.t1: "8a. 成功回呼"
+}
+
+alt "無需質押" {
+  ResumeSubscription.t1 -> PaymentAPI: "6b. PUT /recover"
+  PaymentAPI -> ResumeSubscription.t1: "7b. 成功"
+}
+
+ResumeSubscription.t1 -> PaymentAPI: "9. 取得更新後的訂閱"
+PaymentAPI -> ResumeSubscription.t1: "10. 返回訂閱"
+ResumeSubscription.t1 -> User: "11. 呼叫 onResumed() 並關閉對話方塊"
+
+```
+
+
+## Props
+
+| Prop             | Type                                                     | Required | Description                                                                                                                              |
+| ---------------- | -------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `subscriptionId` | `string`                                                 | 是      | 要恢復的訂閱的唯一識別碼。                                                                                                             |
+| `onResumed`      | `(subscription: Subscription) => void`                   | 否       | 訂閱成功恢復後觸發的回呼函式。它會收到更新後的訂閱物件作為參數。                                                                   |
+| `dialogProps`    | `object`                                                 | 否       | 用於自訂底層 Material-UI Dialog 的 props。您可以控制其狀態（`open`、`onClose`）和外觀（`title`）。                                          |
+| `successToast`   | `boolean`                                                | 否       | 如果為 `true`，成功恢復後會顯示成功通知吐司。預設為 `true`。                                                                     |
+| `authToken`      | `string`                                                 | 否       | 用於 API 請求的可選身份驗證權杖。這對於跨來源或伺服器到伺服器的整合場景很有用。                                                            |
+
+## 使用範例
+
+### 基本用法
+
+這是使用該元件最簡單的方法。預設情況下，它會渲染一個開啟的對話方塊。
+
+```tsx Basic ResumeSubscription Example icon=logos:react
+import { ResumeSubscription } from '@blocklet/payment-react';
+
+function ResumePage({ subscriptionId }) {
+  // 此元件必須在 PaymentProvider 內渲染
+  return <ResumeSubscription subscriptionId={subscriptionId} />;
+}
+```
+
+### 處理結果
+
+使用 `onResumed` 回呼來接收更新後的訂閱資料並刷新您的應用程式狀態。
+
+```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('訂閱已成功恢復：', updatedSubscription);
+    setSubscription(updatedSubscription);
+    // 您也可以顯示確認訊息或將使用者重新導向。
+  };
+
+  return (
+    <div>
+      {/* 根據 `subscription` 狀態顯示訂閱詳情 */}
+      <ResumeSubscription
+        subscriptionId={subscription.id}
+        onResumed={handleSubscriptionResumed}
+      />
+    </div>
+  );
+}
+```
+
+### 控制對話方塊
+
+為了更實用的整合，請從父元件控制對話方塊的可見性。這讓您可以響應使用者操作（例如點擊按鈕）來開啟它。
+
+```tsx Triggering ResumeSubscription with a Button icon=logos:react
+import { ResumeSubscription } from '@blocklet/payment-react';
+import { useState } from 'react';
+import { Button } from '@mui/material';
+
+function SubscriptionActions({ subscriptionId }) {
+  const [isModalOpen, setIsModalOpen] = useState(false);
+
+  const handleResumed = () => {
+    setIsModalOpen(false);
+    // 重新取得訂閱資料以更新 UI
+    alert('訂閱已恢復！');
+  };
+
+  return (
+    <>
+      <Button variant="contained" onClick={() => setIsModalOpen(true)}>
+        恢復訂閱
+      </Button>
+
+      {isModalOpen && (
+        <ResumeSubscription
+          subscriptionId={subscriptionId}
+          onResumed={handleResumed}
+          dialogProps={{
+            open: isModalOpen,
+            title: '確認續訂',
+            onClose: () => setIsModalOpen(false),
+          }}
+        />
+      )}
+    </>
+  );
+}
+```
+
+## 完整整合範例
+
+這是一個完整的範例，展示如何在必要的 `PaymentProvider` 中整合 `ResumeSubscription`。
+
+```tsx Complete Integration Example icon=logos:react
+import { PaymentProvider, ResumeSubscription } from '@blocklet/payment-react';
+import { useSessionContext } from 'path/to/your/session/context'; // 您的應用程式的 session context
+import { useState } from 'react';
+import { Button, Card, CardContent, Typography } from '@mui/material';
+
+function SubscriptionManagementPage({ subscription }) {
+  const { session, connect } = useSessionContext();
+  const [isResumeOpen, setIsResumeOpen] = useState(false);
+
+  const handleResumed = (updatedSubscription) => {
+    console.log('訂閱已更新：', updatedSubscription);
+    setIsResumeOpen(false);
+    // 理想情況下，您會在此處觸發資料重新取得來更新整個頁面。
+  };
+
+  return (
+    <PaymentProvider session={session} connect={connect}>
+      <Card>
+        <CardContent>
+          <Typography variant="h5">管理您的訂閱</Typography>
+          <Typography color="text.secondary">狀態：{subscription.status}</Typography>
+
+          {subscription.status === 'canceled' && (
+            <Button
+              variant="contained"
+              color="primary"
+              sx={{ mt: 2 }}
+              onClick={() => setIsResumeOpen(true)}>
+              恢復訂閱
+            </Button>
+          )}
+        </CardContent>
+      </Card>
+
+      {isResumeOpen && (
+        <ResumeSubscription
+          subscriptionId={subscription.id}
+          onResumed={handleResumed}
+          dialogProps={{
+            open: isResumeOpen,
+            onClose: () => setIsResumeOpen(false),
+          }}
+        />
+      )}
+    </PaymentProvider>
+  );
+}
+```

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

@@ -0,0 +1,190 @@
+# ResumeSubscription
+
+`ResumeSubscription` 组件为用户提供了一个简单的 UI，用于恢复已取消的订阅。它会渲染一个对话框，引导用户完成确认过程，并自动处理需要重新质押等复杂场景。
+
+该组件必须在 `PaymentProvider` 内部使用，以访问处理钱包交互所需的上下文。
+
+## 工作流程
+
+下图说明了用户恢复订阅时的流程，包括重新质押的条件逻辑。
+
+```d2
+shape: sequence_diagram
+
+User: { shape: c4-person }
+ResumeSubscription: { label: "ResumeSubscription 组件" }
+PaymentAPI: { label: "Payment API" }
+DIDWallet: { label: "DID Wallet" }
+
+User -> ResumeSubscription: "1. 触发恢复"
+ResumeSubscription -> PaymentAPI: "2. GET /recover-info"
+PaymentAPI -> ResumeSubscription: "3. 返回状态\n(例如，needStake: true)"
+
+ResumeSubscription.t1 -> User: "4. 显示确认对话框"
+User -> ResumeSubscription.t1: "5. 确认"
+
+alt "需要重新质押" {
+  ResumeSubscription.t1 -> DIDWallet: "6a. 打开重新质押会话"
+  User -> DIDWallet: "7a. 批准"
+  DIDWallet -> ResumeSubscription.t1: "8a. 成功回调"
+}
+
+alt "无需质押" {
+  ResumeSubscription.t1 -> PaymentAPI: "6b. PUT /recover"
+  PaymentAPI -> ResumeSubscription.t1: "7b. 成功"
+}
+
+ResumeSubscription.t1 -> PaymentAPI: "9. 获取更新后的订阅"
+PaymentAPI -> ResumeSubscription.t1: "10. 返回订阅"
+ResumeSubscription.t1 -> User: "11. 调用 onResumed() 并关闭对话框"
+
+```
+
+
+## Props
+
+| Prop             | Type                                                     | Required | Description                                                                                                                              |
+| ---------------- | -------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `subscriptionId` | `string`                                                 | Yes      | 要恢复的订阅的唯一标识符。                                                                                                               |
+| `onResumed`      | `(subscription: Subscription) => void`                   | No       | 订阅成功恢复后触发的回调函数。它会接收更新后的订阅对象作为参数。                                                                         |
+| `dialogProps`    | `object`                                                 | No       | 用于自定义底层 Material-UI Dialog 的 Props。您可以控制其状态（`open`、`onClose`）和外观（`title`）。                                      |
+| `successToast`   | `boolean`                                                | No       | 如果为 `true`，则在成功恢复时显示成功通知 toast。默认为 `true`。                                                                         |
+| `authToken`      | `string`                                                 | No       | 用于 API 请求的可选身份验证令牌。这对于跨域或服务器到服务器的集成场景很有用。                                                           |
+
+## 使用示例
+
+### 基本用法
+
+这是使用该组件最简单的方式。默认情况下，它将渲染一个打开的对话框。
+
+```tsx Basic ResumeSubscription Example icon=logos:react
+import { ResumeSubscription } from '@blocklet/payment-react';
+
+function ResumePage({ subscriptionId }) {
+  // 该组件必须在 PaymentProvider 内部渲染
+  return <ResumeSubscription subscriptionId={subscriptionId} />;
+}
+```
+
+### 处理结果
+
+使用 `onResumed` 回调接收更新后的订阅数据并刷新您的应用程序状态。
+
+```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('订阅已成功恢复:', updatedSubscription);
+    setSubscription(updatedSubscription);
+    // 您还可以显示确认消息或重定向用户。
+  };
+
+  return (
+    <div>
+      {/* 根据 `subscription` 状态显示订阅详情 */}
+      <ResumeSubscription
+        subscriptionId={subscription.id}
+        onResumed={handleSubscriptionResumed}
+      />
+    </div>
+  );
+}
+```
+
+### 控制对话框
+
+为了更实用的集成，可以从父组件控制对话框的可见性。这允许您响应用户操作（如点击按钮）来打开它。
+
+```tsx Triggering ResumeSubscription with a Button icon=logos:react
+import { ResumeSubscription } from '@blocklet/payment-react';
+import { useState } from 'react';
+import { Button } from '@mui/material';
+
+function SubscriptionActions({ subscriptionId }) {
+  const [isModalOpen, setIsModalOpen] = useState(false);
+
+  const handleResumed = () => {
+    setIsModalOpen(false);
+    // 重新获取订阅数据以更新 UI
+    alert('订阅已恢复！');
+  };
+
+  return (
+    <>
+      <Button variant="contained" onClick={() => setIsModalOpen(true)}>
+        恢复订阅
+      </Button>
+
+      {isModalOpen && (
+        <ResumeSubscription
+          subscriptionId={subscriptionId}
+          onResumed={handleResumed}
+          dialogProps={{
+            open: isModalOpen,
+            title: '确认续订',
+            onClose: () => setIsModalOpen(false),
+          }}
+        />
+      )}
+    </>
+  );
+}
+```
+
+## 完整集成示例
+
+这是一个完整的示例，展示了如何在所需的 `PaymentProvider` 中集成 `ResumeSubscription`。
+
+```tsx Complete Integration Example icon=logos:react
+import { PaymentProvider, ResumeSubscription } from '@blocklet/payment-react';
+import { useSessionContext } from 'path/to/your/session/context'; // 您的应用的会话上下文
+import { useState } from 'react';
+import { Button, Card, CardContent, Typography } from '@mui/material';
+
+function SubscriptionManagementPage({ subscription }) {
+  const { session, connect } = useSessionContext();
+  const [isResumeOpen, setIsResumeOpen] = useState(false);
+
+  const handleResumed = (updatedSubscription) => {
+    console.log('订阅已更新:', updatedSubscription);
+    setIsResumeOpen(false);
+    // 理想情况下，您应在此处触发数据重新获取以更新整个页面。
+  };
+
+  return (
+    <PaymentProvider session={session} connect={connect}>
+      <Card>
+        <CardContent>
+          <Typography variant="h5">管理您的订阅</Typography>
+          <Typography color="text.secondary">状态: {subscription.status}</Typography>
+
+          {subscription.status === 'canceled' && (
+            <Button
+              variant="contained"
+              color="primary"
+              sx={{ mt: 2 }}
+              onClick={() => setIsResumeOpen(true)}>
+              恢复订阅
+            </Button>
+          )}
+        </CardContent>
+      </Card>
+
+      {isResumeOpen && (
+        <ResumeSubscription
+          subscriptionId={subscription.id}
+          onResumed={handleResumed}
+          dialogProps={{
+            open: isResumeOpen,
+            onClose: () => setIsResumeOpen(false),
+          }}
+        />
+      )}
+    </PaymentProvider>
+  );
+}
+```

package/docs/components-business.ja.md

@@ -0,0 +1,21 @@
+# ビジネスロジックコンポーネント
+
+ビジネスロジックコンポーネントは、サブスクリプションと請求書管理に関連する複雑でステートフルな操作を処理するために設計された、特殊なReactコンポーネントです。これらのコンポーネントは、延滞請求書の支払いやキャンセルされたサブスクリプションの再開など、ユーザーフロー全体をカプセル化し、最小限のセットアップで高度な機能をアプリケーションに簡単に統合できるようにします。
+
+これらはコアライブラリの機能を基盤に構築されており、多くの場合、支払いサービスAPIと対話してアクションを実行し、状態の変更を反映します。
+
+<x-cards data-columns="2">
+  <x-card data-title="OverdueInvoicePayment" data-icon="lucide:file-warning" data-href="/components/business/overdue-invoice-payment">
+    特定の顧客またはサブスクリプションの延滞請求書の支払いを処理するコンポーネントで、支払いオプション付きのダイアログを表示します。
+  </x-card>
+  <x-card data-title="ResumeSubscription" data-icon="lucide:play-circle" data-href="/components/business/resume-subscription">
+    ユーザーがキャンセルされたサブスクリプションを再開できるようにします。必要に応じて、必要なAPI呼び出しと再ステーキングロジックを処理します。
+  </x-card>
+  <x-card data-title="Auto-Topup Components" data-icon="lucide:zap" data-href="/components/business/auto-topup">
+    表示カードや設定モーダルを含む、自動クレジットトップアップを管理および設定するための一連のコンポーネントです。
+  </x-card>
+</x-cards>
+
+### 次のステップ
+
+これらのビジネスロジックコンポーネントを統合した後、ユーザーに履歴データを表示したい場合があるでしょう。[履歴コンポーネント](./components-history.md)セクションに進み、請求書、支払い、およびクレジットトランザクションを一覧表示する方法を学びましょう。

package/docs/components-business.zh-TW.md

@@ -0,0 +1,21 @@
+# 業務邏輯元件
+
+業務邏輯元件是專為處理訂閱和發票管理相關的複雜、具狀態性操作而設計的特殊 React 元件。這些元件封裝了完整的用戶流程，例如支付逾期發票或恢復已取消的訂閱，讓您能以最少的設定輕鬆地將進階功能整合至您的應用程式中。
+
+它們建立在核心函式庫功能的基礎上，並經常與支付服務 API 互動以執行操作並反映狀態變更。
+
+<x-cards data-columns="2">
+  <x-card data-title="OverdueInvoicePayment" data-icon="lucide:file-warning" data-href="/components/business/overdue-invoice-payment">
+    一個用於處理特定客戶或訂閱的逾期發票支付的元件，會呈現一個帶有付款選項的對話方塊。
+  </x-card>
+  <x-card data-title="ResumeSubscription" data-icon="lucide:play-circle" data-href="/components/business/resume-subscription">
+    允許用戶恢復已取消的訂閱。它會處理必要的 API 呼叫，並在需要時處理重新質押的邏輯。
+  </x-card>
+  <x-card data-title="Auto-Topup Components" data-icon="lucide:zap" data-href="/components/business/auto-topup">
+    一組用於管理和設定自動點數儲值的元件，包含一個顯示卡片和一個設定彈出視窗。
+  </x-card>
+</x-cards>
+
+### 後續步驟
+
+整合這些業務邏輯元件後，您可能會想向用戶顯示歷史資料。請前往 [歷史元件](./components-history.md) 章節，以了解如何列出發票、付款和點數交易。

package/docs/components-business.zh.md

@@ -0,0 +1,21 @@
+# 业务逻辑组件
+
+业务逻辑组件是专门设计的 React 组件，用于处理与订阅和发票管理相关的复杂、有状态的操作。这些组件封装了完整的用户流程，例如支付逾期发票或恢复已取消的订阅，让您可以通过最少的设置轻松地将高级功能集成到您的应用程序中。
+
+它们基于核心库功能构建，并经常与支付服务 API 交互以执行操作并反映状态变化。
+
+<x-cards data-columns="2">
+  <x-card data-title="OverdueInvoicePayment" data-icon="lucide:file-warning" data-href="/components/business/overdue-invoice-payment">
+    一个用于处理特定客户或订阅的逾期发票支付的组件，会呈现一个带有支付选项的对话框。
+  </x-card>
+  <x-card data-title="ResumeSubscription" data-icon="lucide:play-circle" data-href="/components/business/resume-subscription">
+    允许用户恢复已取消的订阅。如果需要，它会处理必要的 API 调用和重新质押逻辑。
+  </x-card>
+  <x-card data-title="自动充值组件" data-icon="lucide:zap" data-href="/components/business/auto-topup">
+    一组用于管理和配置自动信用额度充值的组件，包括一个显示卡和一个配置模态框。
+  </x-card>
+</x-cards>
+
+### 后续步骤
+
+集成这些业务逻辑组件后，您可能希望向用户显示历史数据。请继续阅读 [历史组件](./components-history.md) 部分，以了解如何列出发票、付款和信用交易。