@blocklet/payment-react 1.20.16 → 1.20.17

package/docs/providers-donate-provider.zh.md

@@ -0,0 +1,153 @@
+# DonateProvider
+
+`DonateProvider` 是一个关键的上下文提供程序，用于管理应用程序中所有与捐赠相关的组件的状态和设置。它负责从后端获取配置、为提高性能而缓存配置，并将其提供给像 `CheckoutDonate` 这样的组件。
+
+要使用任何捐赠功能，您必须用 `DonateProvider` 包装您的组件。此提供程序还必须嵌套在 [`PaymentProvider`](./providers-payment-provider.md) 中，以确保能访问必要的支付上下文和会话信息。
+
+## 工作原理
+
+`DonateProvider` 执行以下几个关键功能：
+
+1.  **获取设置**：在挂载时，它会调用一个 API 端点来检索与唯一的 `mountLocation` prop 关联的捐赠设置。这些设置决定了子捐赠组件的行为。
+2.  **缓存数据**：为了提高性能并减少网络请求，获取的设置会存储在 `localStorage` 中。缓存会在后续加载时自动使用，并可在需要时手动清除。
+3.  **提供上下文**：它使用 React 的 Context API 将设置和控制函数（`refresh`、`updateSettings`）传递给任何需要它们的后代组件。
+4.  **启用捐赠**：对于管理用户（“owner”或“admin”），如果捐赠实例处于非活动状态但设置了 `enableDonate` prop，提供程序将渲染一个 UI 来激活它。
+
+## Props
+
+`DonateProvider` 接受以下 props 来配置其行为：
+
+| Prop              | Type                               | Required | Description                                                                                                                              |
+| ----------------- | ---------------------------------- | :------: | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `mountLocation`   | `string`                           |   是    | 此特定捐赠实例的唯一字符串标识符。它用作获取、缓存和更新设置的键。        |
+| `description`     | `string`                           |   是    | 一个人类可读的描述，以帮助在系统后端或日志中识别此捐赠实例。                                      |
+| `children`        | `ReactNode`                        |   是    | 将在提供程序内部渲染的子组件，通常包括 `CheckoutDonate`。                                       |
+| `defaultSettings` | `DonateConfigSettings`             |    否    | 如果在后端找不到设置，则应用此默认设置对象。有关可用选项，请参见下面的类型定义。 |
+| `active`          | `boolean`                          |    否    | 首次创建捐赠实例时，设置其初始活动状态。默认为 `true`。                                   |
+| `enableDonate`    | `boolean`                          |    否    | 如果为 `true`，则允许管理员用户在捐赠实例当前处于非活动状态时从 UI 中启用它。默认为 `false`。               |
+
+### DonateConfigSettings 类型
+
+这是 `defaultSettings` 对象的结构：
+
+```typescript DonateConfigSettings type
+export interface DonateConfigSettings {
+  amount?: {
+    presets?: string[]; // 例如 ['1', '5', '10']
+    preset?: string; // 默认选择的预设金额
+    custom: boolean; // 允许用户输入自定义金额
+    minimum?: string; // 最小自定义金额
+    maximum?: string; // 最大自定义金额
+  };
+  btnText?: string; // 主捐赠按钮的文本，例如“捐赠”
+  historyType?: 'table' | 'avatar'; // 如何显示支持者列表
+}
+```
+
+## 使用示例
+
+这是一个在页面上设置捐赠部分的完整示例。它展示了如何使用 `DonateProvider` 和 `PaymentProvider` 包装 `CheckoutDonate`。
+
+```tsx App.tsx icon=logos:react
+import {
+  PaymentProvider,
+  DonateProvider,
+  CheckoutDonate,
+} from '@blocklet/payment-react';
+import { useSessionContext } from './hooks/use-session'; // 您的自定义会话钩子
+
+function DonationSection() {
+  const { session, connectApi } = useSessionContext();
+
+  // 如果用户未通过身份验证，则不渲染任何内容或显示登录提示
+  if (!session?.user) {
+    return <div>请登录以进行捐赠。</div>;
+  }
+
+  return (
+    <PaymentProvider session={session} connect={connectApi}>
+      <DonateProvider
+        mountLocation="support-our-blog-post-123"
+        description="为文章《React 入门》捐赠"
+        defaultSettings={{
+          btnText: '支持作者',
+          amount: {
+            presets: ['1', '5', '10'],
+            custom: true,
+            minimum: '1',
+          },
+        }}>
+        <CheckoutDonate
+          settings={{
+            target: 'post-123', // 捐赠目标的唯一标识符
+            title: '支持作者',
+            description: '如果您觉得这篇文章有帮助，欢迎请我喝杯咖啡。',
+            reference: 'https://your-site.com/posts/123',
+            beneficiaries: [
+              {
+                address: 'z8iZ75n8fWJ2aL1c9a9f4c3b2e1a0d9f8e7d6c5b4a392817',
+                share: '100',
+              },
+            ],
+          }}
+        />
+      </DonateProvider>
+    </PaymentProvider>
+  );
+}
+```
+
+## Hooks 和实用工具
+
+该库还导出了几个辅助函数，用于对捐赠上下文和缓存进行高级控制。
+
+### `useDonateContext`
+
+一个 React 钩子，用于从 `DonateProvider` 的任何子组件直接访问捐赠上下文。
+
+```tsx
+import { useDonateContext } from '@blocklet/payment-react';
+
+function CustomDonationInfo() {
+  const { settings, refresh } = useDonateContext();
+
+  return (
+    <div>
+      <p>捐赠功能当前为{settings.active ? '启用' : '禁用'}状态。</p>
+      <button onClick={() => refresh(true)}>刷新设置</button>
+    </div>
+  );
+}
+```
+
+### `clearDonateCache`
+
+此函数从 `localStorage` 中手动删除特定 `mountLocation` 的缓存设置。当您知道服务器上的设置已更改并希望在下一次组件渲染时强制刷新时，这非常有用。
+
+```javascript
+import { clearDonateCache } from '@blocklet/payment-react';
+
+// 当您需要使缓存失效时调用此函数
+clearDonateCache('support-our-blog-post-123');
+```
+
+### `clearDonateSettings`
+
+此函数向后端 API 发送一个 `DELETE` 请求，以永久删除给定 `mountLocation` 的设置。它还会清除该位置的本地缓存。
+
+```javascript
+import { clearDonateSettings } from '@blocklet/payment-react';
+
+async function deleteDonationInstance() {
+  try {
+    await clearDonateSettings('support-our-blog-post-123');
+    console.log('捐赠设置已被删除。');
+  } catch (error) {
+    console.error('删除设置失败：', error);
+  }
+}
+```
+
+配置好 `DonateProvider` 后，您现在可以实现各种捐赠功能。下一步是探索用于显示捐赠 UI 的主组件。
+
+➡️ 接下来，学习如何使用 [`CheckoutDonate`](./components-checkout-checkout-donate.md) 组件来渲染捐赠小部件。

package/docs/providers-payment-provider.ja.md

@@ -0,0 +1,191 @@
+# PaymentProvider
+
+`PaymentProvider`は、`@blocklet/payment-react`ライブラリの基盤です。これはコンテキストプロバイダーとして機能し、アプリケーションまたは関連する支払いコンポーネントをラップする必要があります。重要な設定の取得、アプリケーションの状態管理、ヘルパー関数とAPIクライアントのすべての子コンポーネントへの提供を担当します。
+
+このライブラリのほぼすべてのコンポーネントとフックは、正しく機能するために`PaymentProvider`内にネストされている必要があります。
+
+## 仕組み
+
+このプロバイダーは、マウント時にPayment Kitのバックエンドから設定データを初期化して取得します。このデータは、ユーザーのセッションやその他のユーティリティとともに、`usePaymentContext`フックを介してすべての子孫コンポーネントで利用可能になります。このパターンにより、支払いコンポーネントはプロップのバケツリレー（prop drilling）なしで、常に必要なコンテキストにアクセスできるようになります。
+
+```d2
+direction: down
+
+Your-Application: {
+  label: "あなたのアプリケーション"
+  shape: rectangle
+
+  PaymentProvider: {
+    label: "PaymentProvider"
+    style.fill: "#d1e7dd"
+  }
+
+  Payment-Components: {
+    label: "支払いコンポーネント\n(例: CheckoutForm)"
+    shape: rectangle
+    style.fill: "#cfe2ff"
+  }
+}
+
+Payment-Kit-API: {
+  label: "Payment Kit API"
+  shape: cylinder
+}
+
+Your-Application.PaymentProvider -> Payment-Kit-API: "1. 設定とメソッドを取得"
+Your-Application.PaymentProvider -> Your-Application.Payment-Components: "2. コンテキストを提供 (セッション、設定、APIクライアント)"
+Your-Application.Payment-Components -> Payment-Kit-API: "3. APIコールを作成 (例: チェックアウト作成)"
+
+```
+
+## セットアップと使用法
+
+`PaymentProvider`を使用するには、アプリケーションの認証コンテキストから`session`と`connect`オブジェクトを提供する必要があります。このドキュメントでは、アプリの認証ロジックを表すためにカスタムフック`useSessionContext`を使用します。以下は、このようなフックの典型的な実装例です。
+
+```typescript SessionContext.tsx icon=logos:react
+import React, { createContext, useContext } from 'react';
+import { SessionProvider, useSessionContext as useDidSessionContext } from '@arcblock/did-connect-react';
+
+// 独自のコンテキストを作成するか、既存のコンテキストを使用できます
+const AppContext = createContext({});
+
+export function AppProvider({ children }) {
+  return (
+    <SessionProvider>
+      <AppContext.Provider value={{}}>
+        {children}
+      </AppContext.Provider>
+    </SessionProvider>
+  );
+}
+
+// このカスタムフックは、sessionとconnectApiをPaymentProviderに提供します
+export function useSessionContext() {
+  const { session, connect } = useDidSessionContext();
+  return { session, connectApi: connect };
+}
+```
+
+セッション管理を実装したら、メインのアプリケーションコンポーネントを`PaymentProvider`でラップします。
+
+```tsx App.tsx icon=logos:react
+import { PaymentProvider } from '@blocklet/payment-react';
+import { useSessionContext } from './SessionContext'; // あなたのセッションコンテキストフック
+import MyPaymentPage from './MyPaymentPage';
+
+function App() {
+  const { session, connectApi } = useSessionContext();
+
+  return (
+    <PaymentProvider session={session} connect={connectApi}>
+      <MyPaymentPage />
+    </PaymentProvider>
+  );
+}
+
+export default App;
+```
+
+## Props
+
+`PaymentProvider`コンポーネントは、次のpropsを受け入れます。
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `session` | `Session` | はい | 認証コンテキストからのユーザーセッションオブジェクト（例：`@arcblock/did-connect-react`）。 |
+| `connect` | `Connect` | はい | DID Connect操作に使用される、認証コンテキストからの `connect` API関数。 |
+| `children` | `React.ReactNode` | はい | 支払いコンテキストにアクセスできるようになる子コンポーネント。 |
+| `baseUrl` | `string` | いいえ | Payment Kit blockletのベースURL。異なるオリジン（クロスオリジン）から支払いコンポーネントを統合する場合にのみ必要です。 |
+| `authToken` | `string` | いいえ | APIリクエスト用の特定の認証トークン。提供された場合、セッションベースの認証の代わりに使用されます。 |
+
+
+## コンテキストの値
+
+`PaymentProvider`内のコンポーネントは、`usePaymentContext`フックを使用して次の値にアクセスできます。
+
+```typescript MyComponent.tsx icon=logos:react
+import { usePaymentContext } from '@blocklet/payment-react';
+
+function MyComponent() {
+  const { settings, livemode, setLivemode } = usePaymentContext();
+
+  return (
+    <div>
+      <p>Base Currency: {settings.baseCurrency?.name}</p>
+      <p>Mode: {livemode ? 'Live' : 'Test'}</p>
+      <button onClick={() => setLivemode(!livemode)}>Toggle Mode</button>
+    </div>
+  );
+}
+```
+
+利用可能なコンテキスト値の完全なリストは次のとおりです。
+
+| Key | Type | Description |
+| --- | --- | --- |
+| `session` | `object` | 認証済みユーザーのセッション。ユーザー詳細を含みます。 |
+| `connect` | `function` | DID Walletとの対話を開始するための `connect` 関数。 |
+| `livemode` | `boolean` | コンテキストがライブモード（`true`）かテストモード（`false`）かを示します。 |
+| `setLivemode` | `(livemode: boolean) => void` | ライブモードとテストモードを切り替えるための関数。これにより、設定の再取得がトリガーされます。 |
+| `settings` | `Settings` | バックエンドから取得した `paymentMethods` と `baseCurrency` の設定を含むオブジェクト。 |
+| `refresh` | `(forceRefresh?: boolean) => void` | 設定データを手動で再取得するための関数。 |
+| `getCurrency` | `(id: string) => TPaymentCurrency` | IDによって特定の通貨の詳細を取得するためのヘルパー関数。 |
+| `getMethod` | `(id: string) => TPaymentMethodExpanded` | IDによって特定の支払い方法の詳細を取得するためのヘルパー関数。 |
+| `api` | `AxiosInstance` | Payment Kitバックエンドに対して認証済みAPIコールを行うための、事前設定済みのAxiosインスタンス。 |
+| `prefix` | `string` | blockletのURLプレフィックス。 |
+| `payable` | `boolean` | 支払いアクションの可用性を制御するために使用できる状態。 |
+| `setPayable` | `(status: boolean) => void` | `payable` ステータスを更新するための関数。 |
+
+
+## 高度なシナリオ
+
+### クロスオリジン統合
+
+アプリケーションとPayment Kit blockletが異なるドメインでホストされている場合は、`baseUrl` propを使用する必要があります。これにより、`PaymentProvider`はPayment Kit APIを正しく特定し、通信できるようになります。
+
+```tsx CrossOriginApp.tsx icon=logos:react
+import { PaymentProvider } from '@blocklet/payment-react';
+import { useSessionContext } from './SessionContext';
+
+function CrossOriginApp() {
+  const { session, connectApi } = useSessionContext();
+
+  return (
+    <PaymentProvider 
+      session={session} 
+      connect={connectApi}
+      baseUrl="https://payment-kit.another-domain.com"
+    >
+      {/* あなたの支払いコンポーネント */}
+    </PaymentProvider>
+  );
+}
+```
+
+### カスタム認証トークン
+
+デフォルトのセッションベース認証の代わりに特定のAPIトークンを使用する必要があるシナリオ（例：サーバー間通信や特定のアクセス権の付与）では、`authToken` propを渡すことができます。
+
+```tsx TokenAuthApp.tsx icon=logos:react
+import { PaymentProvider } from '@blocklet/payment-react';
+import { useSessionContext } from './SessionContext';
+
+function TokenAuthApp() {
+  const { session, connectApi } = useSessionContext();
+  const myCustomAuthToken = 'sk_xxxxxx'; // あなたの秘密トークン
+
+  return (
+    <PaymentProvider 
+      session={session} 
+      connect={connectApi}
+      authToken={myCustomAuthToken}
+    >
+      {/* コンポーネントはAPIコールに提供されたauthTokenを使用します */}
+    </PaymentProvider>
+  );
+}
+```
+
+---
+
+`PaymentProvider`のセットアップが完了したら、支払いコンポーネントをアプリケーションに統合する準備が整いました。次のステップとして、[CheckoutForm](./components-checkout-checkout-form.md)コンポーネントを使用して支払いフローを作成する方法を確認することをお勧めします。

package/docs/providers-payment-provider.zh-TW.md

@@ -0,0 +1,191 @@
+# PaymentProvider
+
+`PaymentProvider` 是 `@blocklet/payment-react` 函式庫的基石。它作為一個上下文提供者，必須包裝您的應用程式或相關的支付元件。它負責取得必要的設定、管理應用程式狀態，並為其所有子元件提供輔助函式和 API 客戶端。
+
+此函式庫中幾乎每個元件和掛鉤都需要嵌套在 `PaymentProvider` 內才能正常運作。
+
+## 運作方式
+
+該提供者在掛載時會初始化並從 Payment Kit 後端取得設定資料。這些資料，連同使用者的 session 和其他工具，會透過 `usePaymentContext` 掛鉤提供給任何後代元件。這種模式確保您的支付元件始終能夠存取必要的上下文，而無需透過屬性傳遞。
+
+```d2
+direction: down
+
+Your-Application: {
+  label: "您的應用程式"
+  shape: rectangle
+
+  PaymentProvider: {
+    label: "PaymentProvider"
+    style.fill: "#d1e7dd"
+  }
+
+  Payment-Components: {
+    label: "支付元件\n(例如 CheckoutForm)"
+    shape: rectangle
+    style.fill: "#cfe2ff"
+  }
+}
+
+Payment-Kit-API: {
+  label: "Payment Kit API"
+  shape: cylinder
+}
+
+Your-Application.PaymentProvider -> Payment-Kit-API: "1. 取得設定與方法"
+Your-Application.PaymentProvider -> Your-Application.Payment-Components: "2. 提供上下文 (session、設定、API 客戶端)"
+Your-Application.Payment-Components -> Payment-Kit-API: "3. 發起 API 呼叫 (例如建立結帳)"
+
+```
+
+## 設定與使用
+
+若要使用 `PaymentProvider`，您需要從應用程式的驗證上下文中為其提供 `session` 和 `connect` 物件。在整個文件中，我們將使用一個自訂掛鉤 `useSessionContext` 來代表您應用程式的驗證邏輯。以下是此類掛鉤的典型實作：
+
+```typescript SessionContext.tsx icon=logos:react
+import React, { createContext, useContext } from 'react';
+import { SessionProvider, useSessionContext as useDidSessionContext } from '@arcblock/did-connect-react';
+
+// 您可以建立自己的上下文或使用現有的上下文
+const AppContext = createContext({});
+
+export function AppProvider({ children }) {
+  return (
+    <SessionProvider>
+      <AppContext.Provider value={{}}>
+        {children}
+      </AppContext.Provider>
+    </SessionProvider>
+  );
+}
+
+// 這個自訂掛鉤為 PaymentProvider 提供 session 和 connectApi
+export function useSessionContext() {
+  const { session, connect } = useDidSessionContext();
+  return { session, connectApi: connect };
+}
+```
+
+一旦您的 session 管理就緒，就用 `PaymentProvider` 包裝您的主應用程式元件。
+
+```tsx App.tsx icon=logos:react
+import { PaymentProvider } from '@blocklet/payment-react';
+import { useSessionContext } from './SessionContext'; // 您的 session 上下文掛鉤
+import MyPaymentPage from './MyPaymentPage';
+
+function App() {
+  const { session, connectApi } = useSessionContext();
+
+  return (
+    <PaymentProvider session={session} connect={connectApi}>
+      <MyPaymentPage />
+    </PaymentProvider>
+  );
+}
+
+export default App;
+```
+
+## Props
+
+`PaymentProvider` 元件接受以下 props：
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `session` | `Session` | 是 | 來自您的驗證上下文的使用者 session 物件 (例如 `@arcblock/did-connect-react`)。 |
+| `connect` | `Connect` | 是 | 來自您的驗證上下文的 `connect` API 函式，用於 DID Connect 操作。 |
+| `children` | `React.ReactNode` | 是 | 將有權存取支付上下文的子元件。 |
+| `baseUrl` | `string` | 否 | Payment Kit blocklet 的基礎 URL。僅在從不同來源 (跨來源) 整合支付元件時才需要。 |
+| `authToken` | `string` | 否 | 用於 API 請求的特定驗證令牌。如果提供，它將取代基於 session 的驗證。 |
+
+
+## 上下文值
+
+`PaymentProvider` 內的元件可以使用 `usePaymentContext` 掛鉤存取以下值。
+
+```typescript MyComponent.tsx icon=logos:react
+import { usePaymentContext } from '@blocklet/payment-react';
+
+function MyComponent() {
+  const { settings, livemode, setLivemode } = usePaymentContext();
+
+  return (
+    <div>
+      <p>基礎貨幣： {settings.baseCurrency?.name}</p>
+      <p>模式： {livemode ? '正式' : '測試'}</p>
+      <button onClick={() => setLivemode(!livemode)}>切換模式</button>
+    </div>
+  );
+}
+```
+
+以下是可用上下文值的完整列表：
+
+| Key | Type | Description |
+| --- | --- | --- |
+| `session` | `object` | 經過驗證的使用者 session，包含使用者詳細資訊。 |
+| `connect` | `function` | 用於啟動 DID Wallet 互動的 `connect` 函式。 |
+| `livemode` | `boolean` | 表示上下文是處於正式 (`true`) 模式還是測試 (`false`) 模式。 |
+| `setLivemode` | `(livemode: boolean) => void` | 一個在正式和測試模式之間切換的函式。這將觸發重新取得設定。 |
+| `settings` | `Settings` | 一個包含從後端取得的 `paymentMethods` 和 `baseCurrency` 設定的物件。 |
+| `refresh` | `(forceRefresh?: boolean) => void` | 一個手動觸發重新取得設定資料的函式。 |
+| `getCurrency` | `(id: string) => TPaymentCurrency` | 一個輔助函式，可透過 ID 取得特定貨幣的詳細資訊。 |
+| `getMethod` | `(id: string) => TPaymentMethodExpanded` | 一個輔助函式，可透過 ID 取得特定支付方式的詳細資訊。 |
+| `api` | `AxiosInstance` | 一個預先設定的 Axios 實例，用於向 Payment Kit 後端發出經過驗證的 API 呼叫。 |
+| `prefix` | `string` | blocklet 的 URL 前綴。 |
+| `payable` | `boolean` | 一個可用於控制支付操作可用性的狀態。 |
+| `setPayable` | `(status: boolean) => void` | 一個更新 `payable` 狀態的函式。 |
+
+
+## 進階情境
+
+### 跨來源整合
+
+如果您的應用程式和 Payment Kit blocklet 託管在不同的網域上，您必須使用 `baseUrl` prop。這讓 `PaymentProvider` 能夠正確地定位並與 Payment Kit API 通訊。
+
+```tsx CrossOriginApp.tsx icon=logos:react
+import { PaymentProvider } from '@blocklet/payment-react';
+import { useSessionContext } from './SessionContext';
+
+function CrossOriginApp() {
+  const { session, connectApi } = useSessionContext();
+
+  return (
+    <PaymentProvider 
+      session={session} 
+      connect={connectApi}
+      baseUrl="https://payment-kit.another-domain.com"
+    >
+      {/* 您的支付元件 */}
+    </PaymentProvider>
+  );
+}
+```
+
+### 自訂驗證令牌
+
+在您需要使用特定的 API 令牌而不是預設的基於 session 的驗證的情境下 (例如，用於伺服器對伺服器通訊或特定的存取授權)，您可以傳遞 `authToken` prop。
+
+```tsx TokenAuthApp.tsx icon=logos:react
+import { PaymentProvider } from '@blocklet/payment-react';
+import { useSessionContext } from './SessionContext';
+
+function TokenAuthApp() {
+  const { session, connectApi } = useSessionContext();
+  const myCustomAuthToken = 'sk_xxxxxx'; // 您的秘密令牌
+
+  return (
+    <PaymentProvider 
+      session={session} 
+      connect={connectApi}
+      authToken={myCustomAuthToken}
+    >
+      {/* 元件將使用提供的 authToken 進行 API 呼叫 */}
+    </PaymentProvider>
+  );
+}
+```
+
+---
+
+設定好 `PaymentProvider` 後，您現在可以開始將支付元件整合到您的應用程式中。一個好的下一步是探索如何使用 [CheckoutForm](./components-checkout-checkout-form.md) 元件來建立支付流程。