@blocklet/payment-react 1.20.16 → 1.20.17

package/docs/providers-payment-provider.zh.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>
+  );
+}
+
+// 这个自定义钩子为 PaymentProvider 提供会话和 connectApi
+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 | 类型 | 必需 | 描述 |
+| --- | --- | --- | --- |
+| `session` | `Session` | 是 | 来自您的身份验证上下文（例如，`@arcblock/did-connect-react`）的用户会话对象。 |
+| `connect` | `Connect` | 是 | 来自您的身份验证上下文的 `connect` API 函数，用于 DID Connect 操作。 |
+| `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>
+  );
+}
+```
+
+以下是可用的上下文值的完整列表：
+
+| 键 | 类型 | 描述 |
+| --- | --- | --- |
+| `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` | 一个预先配置的 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 令牌而不是默认的基于会话的身份验证（例如，用于服务器到服务器的通信或特定的访问授权），您可以传递 `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) 组件来创建支付流程。

package/docs/providers.ja.md

@@ -0,0 +1,42 @@
+# プロバイダー
+
+Context Provider は `@blocklet/payment-react` の中心的な概念です。これらはアプリケーションの一部をラップする役割を果たし、React の Context API を使用して、ネストされたすべてのコンポーネントに重要なデータと機能を渡します。これにより、コンポーネントツリーの多くのレベルを通じて手動でプロップを渡す必要がなくなります。
+
+このライブラリのほとんどのコンポーネントを使用するには、アプリケーションまたは関連ページを適切なプロバイダーでラップする必要があります。
+
+```d2 基本的なプロバイダー構造 icon=graph:flowchart
+direction: down
+
+あなたのアプリケーション: {
+  shape: rectangle
+
+  PaymentProvider: {
+    label: "PaymentProvider"
+    shape: rectangle
+
+    CheckoutForm: {
+      label: "CheckoutForm"
+    }
+    CustomerInvoiceList: {
+      label: "CustomerInvoiceList"
+    }
+  }
+}
+
+あなたのアプリケーション -> PaymentProvider: "ラップする"
+PaymentProvider -> CheckoutForm: "コンテキストを提供"
+PaymentProvider -> CustomerInvoiceList: "コンテキストを提供"
+```
+
+このライブラリは、それぞれ異なる目的を果たす2つの主要なプロバイダーを提供しています。ニーズに合ったものを選択してください。
+
+<x-cards>
+  <x-card data-title="PaymentProvider" data-icon="lucide:package" data-href="/providers/payment-provider">
+    ほぼすべての支払い関連操作に必要な基本的なプロバイダーです。支払い方法、通貨設定、ユーザーセッション情報を管理し、事前設定されたAPIクライアントを提供します。
+  </x-card>
+  <x-card data-title="DonateProvider" data-icon="lucide:heart" data-href="/providers/donate-provider">
+    寄付機能のための専門プロバイダーです。CheckoutDonateコンポーネントで実装されたような寄付ウィジェットの設定と状態を処理します。
+  </x-card>
+</x-cards>
+
+上のプロバイダーをクリックすると、必須のプロップや設定例など、詳細なドキュメントが表示されます。

package/docs/providers.zh-TW.md

@@ -0,0 +1,42 @@
+# 提供者
+
+Context Provider 是 `@blocklet/payment-react` 的一個核心概念。它們作為您應用程式部分的包裝器，使用 React 的 Context API 將必要的資料和函式傳遞給所有嵌套在其中的元件。這避免了需要手動將 props 透過多層元件樹向下傳遞。
+
+要使用此函式庫中的大多數元件，您必須用適當的 provider 包裝您的應用程式或相關頁面。
+
+```d2 基本 Provider 結構 icon=graph:flowchart
+direction: down
+
+Your-Application: {
+  shape: rectangle
+
+  PaymentProvider: {
+    label: "PaymentProvider"
+    shape: rectangle
+
+    CheckoutForm: {
+      label: "CheckoutForm"
+    }
+    CustomerInvoiceList: {
+      label: "CustomerInvoiceList"
+    }
+  }
+}
+
+Your-Application -> PaymentProvider: "包裝"
+PaymentProvider -> CheckoutForm: "提供 context"
+PaymentProvider -> CustomerInvoiceList: "提供 context"
+```
+
+此函式庫提供兩個主要的 provider，每個都有不同的用途。請選擇適合您需求的 provider。
+
+<x-cards>
+  <x-card data-title="PaymentProvider" data-icon="lucide:package" data-href="/providers/payment-provider">
+    幾乎所有與支付相關的操作都需要的基礎 provider。它管理支付方式、貨幣設定、使用者工作階段資訊，並提供一個預先設定的 API 用戶端。
+  </x-card>
+  <x-card data-title="DonateProvider" data-icon="lucide:heart" data-href="/providers/donate-provider">
+    一個專為捐贈功能設計的 provider。它處理捐贈小工具的設定和狀態，例如使用 CheckoutDonate 元件實作的那些。
+  </x-card>
+</x-cards>
+
+點擊上方的 provider 以查看其詳細文件，包括必要的 props 和設定範例。

package/docs/providers.zh.md

@@ -0,0 +1,42 @@
+# 提供者
+
+Context 提供者是 `@blocklet/payment-react` 的一个核心概念。它们充当您应用程序部分的包装器，使用 React 的 Context API 将必要的数据和函数传递给嵌套在其中的所有组件。这避免了需要通过组件树的多个层级手动向下传递 props。
+
+要使用此库中的大多数组件，您必须使用适当的提供者来包装您的应用程序或相关页面。
+
+```d2 Basic Provider Structure icon=graph:flowchart
+direction: down
+
+您的应用程序: {
+  shape: rectangle
+
+  PaymentProvider: {
+    label: "PaymentProvider"
+    shape: rectangle
+
+    CheckoutForm: {
+      label: "CheckoutForm"
+    }
+    CustomerInvoiceList: {
+      label: "CustomerInvoiceList"
+    }
+  }
+}
+
+您的应用程序 -> PaymentProvider: "包装"
+PaymentProvider -> CheckoutForm: "提供上下文"
+PaymentProvider -> CustomerInvoiceList: "提供上下文"
+```
+
+该库提供了两个主要的提供者，每个都有不同的用途。选择适合您需求的一个。
+
+<x-cards>
+  <x-card data-title="PaymentProvider" data-icon="lucide:package" data-href="/providers/payment-provider">
+    这是几乎所有支付相关操作所需的基础提供者。它管理支付方式、货币设置、用户会话信息，并提供一个预配置的 API 客户端。
+  </x-card>
+  <x-card data-title="DonateProvider" data-icon="lucide:heart" data-href="/providers/donate-provider">
+    一个用于捐赠功能的专用提供者。它处理捐赠小部件的配置和状态，例如使用 CheckoutDonate 组件实现的那些小部件。
+  </x-card>
+</x-cards>
+
+点击上方的提供者以查看其详细文档，包括所需的 props 和设置示例。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blocklet/payment-react",
-  "version": "1.20.16",
+  "version": "1.20.17",
   "description": "Reusable react components for payment kit v2",
   "keywords": [
     "react",
@@ -94,7 +94,7 @@
     "@babel/core": "^7.27.4",
     "@babel/preset-env": "^7.27.2",
     "@babel/preset-react": "^7.27.1",
-    "@blocklet/payment-types": "1.20.16",
+    "@blocklet/payment-types": "1.20.17",
     "@storybook/addon-essentials": "^7.6.20",
     "@storybook/addon-interactions": "^7.6.20",
     "@storybook/addon-links": "^7.6.20",
@@ -125,5 +125,5 @@
     "vite-plugin-babel": "^1.3.1",
     "vite-plugin-node-polyfills": "^0.23.0"
   },
-  "gitHead": "ebf0677dd4414d4abc4129d6663a7e9ddb415281"
+  "gitHead": "20e9d7519327cb4df0c93375ff85783303fc99d6"
 }