@blocklet/payment-react 1.20.15 → 1.20.17

package/docs/components-history-credit-transactions-list.zh.md

@@ -0,0 +1,106 @@
+# CreditTransactionsList
+
+`CreditTransactionsList` 组件渲染了一个包含所有信用额度交易的详细分页表格，提供了信用额度使用和调整的清晰日志。它非常适合在客户门户或管理仪表板中使用，以跟踪信用额度的授予和消耗情况。
+
+该组件会自动处理数据获取、分页和格式化，提供了一种显示交易历史的简单方法。
+
+## 属性
+
+| 属性 | 类型 | 描述 | 默认值 |
+| --- | --- | --- | --- |
+| `customer_id` | `string` | 要显示的交易记录所属客户的 ID。如果未提供，则默认为来自 `PaymentProvider` 上下文的当前登录用户的 DID。 | `session.user.did` |
+| `subscription_id` | `string` | 将交易记录筛选到特定的订阅。 | `undefined` |
+| `credit_grant_id` | `string` | 将交易记录筛选到特定的信用额度授予。 | `undefined` |
+| `pageSize` | `number` | 每页显示的交易数量。 | `10` |
+| `onTableDataChange` | `(data, prevData) => void` | 当表格数据被获取或更新时触发的回调函数。 | `() => {}` |
+| `showAdminColumns` | `boolean` | 如果为 `true` 且用户是管理员，则会显示额外的列，例如 'Meter Event'。 | `false` |
+| `showTimeFilter` | `boolean` | 如果为 `true`，则会显示一个日期范围选择器，以允许按日期筛选交易记录。 | `false` |
+| `source` | `string` | 一个可选的源字符串，用于筛选交易记录。 | `''` |
+| `mode` | `'dashboard' \| 'portal'` | 决定相关项目（如信用额度授予）的链接结构。对管理视图使用 `'dashboard'`，对面向客户的视图使用 `'portal'`。 | `'portal'` |
+
+## 客户门户的基本用法
+
+此示例展示了如何显示当前登录用户的信用额度交易历史。当 `customer_id` 被省略时，该组件会自动使用来自 `PaymentProvider` 上下文的用户的 DID。
+
+```jsx MyCreditHistoryPage.tsx icon=logos:react
+import React from 'react';
+import { CreditTransactionsList, PaymentProvider } from '@blocklet/payment-react';
+import { useSessionContext } from '../hooks/session-context'; // 你的会话上下文钩子
+
+function MyCreditHistoryPage() {
+  const { session, connectApi } = useSessionContext();
+
+  if (!session || !connectApi) {
+    return <div>正在加载会话...</div>;
+  }
+
+  return (
+    <PaymentProvider session={session} connectApi={connectApi}>
+      <h2>我的信用额度交易</h2>
+      <CreditTransactionsList />
+    </PaymentProvider>
+  );
+}
+
+export default MyCreditHistoryPage;
+```
+
+## 带筛选功能的管理视图
+
+对于管理仪表板，你可以传递一个特定的 `customer_id`，并启用管理列和时间筛选器，以提供用户交易历史的更强大和详细的视图。
+
+```jsx CustomerDetailsPage.tsx icon=logos:react
+import React from 'react';
+import { CreditTransactionsList, PaymentProvider } from '@blocklet/payment-react';
+import { useSessionContext } from '../hooks/session-context'; // 你的会话上下文钩子
+
+function CustomerDetailsPage({ customerId }) {
+  const { session, connectApi } = useSessionContext();
+
+  if (!session || !connectApi) {
+    return <div>正在加载会话...</div>;
+  }
+
+  return (
+    <PaymentProvider session={session} connectApi={connectApi}>
+      <h3>{customerId} 的交易历史</h3>
+      <CreditTransactionsList
+        customer_id={customerId}
+        showAdminColumns={true}
+        showTimeFilter={true}
+        pageSize={20}
+        mode="dashboard"
+      />
+    </PaymentProvider>
+  );
+}
+
+export default CustomerDetailsPage;
+```
+
+## 显示特定信用额度授予的交易记录
+
+要显示特定信用额度授予的消耗详情日志，请传递 `credit_grant_id`。这对于显示单个信用额度授予详情的页面非常有用。
+
+```jsx CreditGrantDetailsPage.tsx icon=logos:react
+import React from 'react';
+import { CreditTransactionsList, PaymentProvider } from '@blocklet/payment-react';
+import { useSessionContext } from '../hooks/session-context'; // 你的会话上下文钩子
+
+function CreditGrantDetailsPage({ grantId }) {
+  const { session, connectApi } = useSessionContext();
+
+  if (!session || !connectApi) {
+    return <div>正在加载会话...</div>;
+  }
+
+  return (
+    <PaymentProvider session={session} connectApi={connectApi}>
+      <h4>授权 {grantId} 的使用详情</h4>
+      <CreditTransactionsList credit_grant_id={grantId} />
+    </PaymentProvider>
+  );
+}
+
+export default CreditGrantDetailsPage;
+```

package/docs/components-history-invoice-list.ja.md

@@ -0,0 +1,110 @@
+# CustomerInvoiceList
+
+`CustomerInvoiceList` コンポーネントは、顧客の請求履歴をレンダリングするために設計されています。支払いサービスから請求書データを取得して表示し、2つの異なるレイアウトを提供します：無限スクロールを備えた日付でグループ化されたシンプルなリストと、詳細なページ分割テーブルです。このコンポーネントが正しく機能するためには、`PaymentProvider` 内で使用する必要があります。
+
+## プロパティ
+
+| プロパティ | 型 | 説明 | デフォルト |
+| --- | --- | --- | --- |
+| `customer_id` | `string` | 請求書を表示する顧客のID。 | `''` |
+| `subscription_id` | `string` | 特定のサブスクリプションIDで請求書を絞り込みます。 | `''` |
+| `currency_id` | `string` | 特定の通貨IDで請求書を絞り込みます。 | `''` |
+| `include_staking` | `boolean` | `true` の場合、ステーキング関連の請求書をリストに含めます。 | `false` |
+| `include_return_staking` | `boolean` | `true` の場合、返還ステーキングの請求書を含めます。 | `false` |
+| `include_recovered_from` | `boolean` | `true` の場合、以前の残高から回収された請求書を含めます。 | `false` |
+| `status` | `string` | 表示する請求書のステータスをカンマ区切りで指定した文字列（例：`'open,paid,uncollectible'`）。 | `'open,paid,uncollectible'` |
+| `pageSize` | `number` | 1ページあたりに取得する請求書の数。 | `10` |
+| `target` | `string` | 請求書リンクの `target` 属性（例：`'_self'`、`'_blank'`）。 | `'_self'` |
+| `action` | `string` | 特定の請求書に対するコールトゥアクションを定義します。`'pay'` に設定すると、未払いの請求書に支払いボタンが表示されます。 | `''` |
+| `type` | `'list' \| 'table'` | 請求書リストの表示モード。 | `'list'` |
+| `onTableDataChange` | `Function` | 請求書データが変更されたときにトリガーされるコールバック関数。 | `() => {}` |
+| `relatedSubscription` | `boolean` | `table` モードで `true` の場合、関連するサブスクリプションへのリンクを含む列を表示します。 | `false` |
+
+## 基本的な使い方（リストビュー）
+
+デフォルトのビュー（`type="list"`）では、日付でグループ化された請求書のシンプルなリストが表示され、無限スクロール機能で項目を追加読み込みします。
+
+```tsx CustomerInvoiceListPage.tsx icon=logos:react
+import { PaymentProvider, CustomerInvoiceList } from '@blocklet/payment-react';
+
+function InvoiceHistoryPage() {
+  // customerIdが利用可能であると仮定します（例：セッションまたはpropsから）
+  const customerId = 'cus_xxxxxxxxxxxxxx';
+
+  return (
+    <PaymentProvider>
+      <CustomerInvoiceList customer_id={customerId} />
+    </PaymentProvider>
+  );
+}
+```
+
+## テーブルビュー
+
+より詳細で構造化された表示には、`type="table"` を設定します。このモードでは、ソート可能な列を持つページ分割されたテーブルに請求書が表示されます。
+
+```tsx CustomerInvoiceTablePage.tsx icon=logos:react
+import { PaymentProvider, CustomerInvoiceList } from '@blocklet/payment-react';
+
+function InvoiceHistoryTable() {
+  const customerId = 'cus_xxxxxxxxxxxxxx';
+
+  return (
+    <PaymentProvider>
+      <CustomerInvoiceList
+        customer_id={customerId}
+        type="table"
+        relatedSubscription={true} // 関連サブスクリプションの列を表示
+        pageSize={5}
+      />
+    </PaymentProvider>
+  );
+}
+```
+
+この例では、`relatedSubscription` プロパティを有効にして、各請求書に関連付けられたサブスクリプションに直接リンクする列を追加しています。これはサブスクリプションベースのサービスに役立ちます。
+
+## 請求書のフィルタリング
+
+さまざまなプロパティを使用して、表示される請求書をフィルタリングできます。例えば、ステーキングに関連する支払い済みの請求書のみを表示するには、次のようにします：
+
+```tsx FilteredInvoiceListPage.tsx icon=logos:react
+import { PaymentProvider, CustomerInvoiceList } from '@blocklet/payment-react';
+
+function FilteredInvoiceList() {
+  const customerId = 'cus_xxxxxxxxxxxxxx';
+
+  return (
+    <PaymentProvider>
+      <CustomerInvoiceList
+        customer_id={customerId}
+        type="table"
+        status="paid" // 支払い済みの請求書のみ表示
+        include_staking={true} // ステーキング取引も含む
+      />
+    </PaymentProvider>
+  );
+}
+```
+
+## 未払い請求書の支払いを有効にする
+
+`action` プロパティを `'pay'` に設定すると、ステータスが `open` または `uncollectible` の請求書に「支払う」ボタンを追加できます。このボタンをクリックすると、`PaymentProvider` の `connect` インスタンスを使用して支払いフローが開始されます。
+
+```tsx PayableInvoiceListPage.tsx icon=logos:react
+import { PaymentProvider, CustomerInvoiceList } from '@blocklet/payment-react';
+
+function PayableInvoiceList() {
+  const customerId = 'cus_xxxxxxxxxxxxxx';
+
+  return (
+    <PaymentProvider>
+      <CustomerInvoiceList
+        customer_id={customerId}
+        status="open,uncollectible" // 支払いが必要な請求書のみ表示
+        action="pay" // 「支払う」ボタンを追加
+      />
+    </PaymentProvider>
+  );
+}
+```

package/docs/components-history-invoice-list.zh-TW.md

@@ -0,0 +1,110 @@
+# CustomerInvoiceList
+
+`CustomerInvoiceList` 元件旨在呈現客戶的發票歷史記錄。它會從支付服務中擷取並顯示發票資料，提供兩種不同的版面配置：一種是簡單的、按日期分組的無限滾動列表，另一種是詳細的、分頁的表格。此元件必須在 `PaymentProvider` 中使用才能正常運作。
+
+## Props
+
+| Prop | 類型 | 說明 | 預設值 |
+| --- | --- | --- | --- |
+| `customer_id` | `string` | 要顯示其發票的客戶 ID。 | `''` |
+| `subscription_id` | `string` | 按特定訂閱 ID 篩選發票。 | `''` |
+| `currency_id` | `string` | 按特定貨幣 ID 篩選發票。 | `''` |
+| `include_staking` | `boolean` | 如果為 `true`，則在列表中包含與質押相關的發票。 | `false` |
+| `include_return_staking` | `boolean` | 如果為 `true`，則包含返還質押的發票。 | `false` |
+| `include_recovered_from` | `boolean` | 如果為 `true`，則包含從先前餘額中恢復的發票。 | `false` |
+| `status` | `string` | 要顯示的發票狀態的逗號分隔字串（例如：`'open,paid,uncollectible'`）。 | `'open,paid,uncollectible'` |
+| `pageSize` | `number` | 每頁要擷取的發票數量。 | `10` |
+| `target` | `string` | 發票連結的目標屬性（例如：`'_self'`、`'_blank'`）。 | `'_self'` |
+| `action` | `string` | 為某些發票定義行動呼籲。設定為 `'pay'` 以顯示未付款發票的支付按鈕。 | `''` |
+| `type` | `'list' \| 'table'` | 發票列表的顯示模式。 | `'list'` |
+| `onTableDataChange` | `Function` | 當發票資料變更時觸發的回呼函式。 | `() => {}` |
+| `relatedSubscription` | `boolean` | 在表格模式下，如果為 `true`，則顯示一個包含相關訂閱連結的欄位。 | `false` |
+
+## 基本用法（列表視圖）
+
+預設視圖 (`type="list"`) 會呈現一個按日期分組的簡單發票列表，並具有無限滾動機制以載入更多項目。
+
+```tsx CustomerInvoiceListPage.tsx icon=logos:react
+import { PaymentProvider, CustomerInvoiceList } from '@blocklet/payment-react';
+
+function InvoiceHistoryPage() {
+  // 假設 customerId 可用，例如，來自會話或 props
+  const customerId = 'cus_xxxxxxxxxxxxxx';
+
+  return (
+    <PaymentProvider>
+      <CustomerInvoiceList customer_id={customerId} />
+    </PaymentProvider>
+  );
+}
+```
+
+## 表格視圖
+
+若要進行更詳細和結構化的呈現，您可以設定 `type="table"`。此模式會在具有可排序欄位的分頁表格中顯示發票。
+
+```tsx CustomerInvoiceTablePage.tsx icon=logos:react
+import { PaymentProvider, CustomerInvoiceList } from '@blocklet/payment-react';
+
+function InvoiceHistoryTable() {
+  const customerId = 'cus_xxxxxxxxxxxxxx';
+
+  return (
+    <PaymentProvider>
+      <CustomerInvoiceList
+        customer_id={customerId}
+        type="table"
+        relatedSubscription={true} // 顯示相關訂閱的欄位
+        pageSize={5}
+      />
+    </PaymentProvider>
+  );
+}
+```
+
+在此範例中，啟用了 `relatedSubscription` prop 來新增一個直接連結到每張發票相關訂閱的欄位，這對於基於訂閱的服務非常有用。
+
+## 篩選發票
+
+您可以使用各種 props 來篩選顯示的發票。例如，若要僅顯示與質押相關的已付款發票：
+
+```tsx FilteredInvoiceListPage.tsx icon=logos:react
+import { PaymentProvider, CustomerInvoiceList } from '@blocklet/payment-react';
+
+function FilteredInvoiceList() {
+  const customerId = 'cus_xxxxxxxxxxxxxx';
+
+  return (
+    <PaymentProvider>
+      <CustomerInvoiceList
+        customer_id={customerId}
+        type="table"
+        status="paid" // 僅顯示已付款發票
+        include_staking={true} // 同時包含質押交易
+      />
+    </PaymentProvider>
+  );
+}
+```
+
+## 為未付款發票啟用支付功能
+
+透過將 `action` prop 設定為 `'pay'`，您可以為任何狀態為 `open` 或 `uncollectible` 的發票新增一個「支付」按鈕。點擊此按鈕將使用來自 `PaymentProvider` 的 `connect` 實例啟動支付流程。
+
+```tsx PayableInvoiceListPage.tsx icon=logos:react
+import { PaymentProvider, CustomerInvoiceList } from '@blocklet/payment-react';
+
+function PayableInvoiceList() {
+  const customerId = 'cus_xxxxxxxxxxxxxx';
+
+  return (
+    <PaymentProvider>
+      <CustomerInvoiceList
+        customer_id={customerId}
+        status="open,uncollectible" // 僅顯示需要支付的發票
+        action="pay" // 新增「支付」按鈕
+      />
+    </PaymentProvider>
+  );
+}
+```

package/docs/components-history-invoice-list.zh.md

@@ -0,0 +1,110 @@
+# CustomerInvoiceList
+
+`CustomerInvoiceList` 组件用于渲染客户的发票历史记录。它会从支付服务中获取并显示发票数据，并提供两种不同的布局：一种是按日期分组的简单列表，支持无限滚动；另一种是详细的分页表格。此组件必须在 `PaymentProvider` 内部使用才能正常工作。
+
+## Props
+
+| Prop | Type | Description | Default |
+| --- | --- | --- | --- |
+| `customer_id` | `string` | 要显示其发票的客户 ID。 | `''` |
+| `subscription_id` | `string` | 按特定订阅 ID 筛选发票。 | `''` |
+| `currency_id` | `string` | 按特定货币 ID 筛选发票。 | `''` |
+| `include_staking` | `boolean` | 如果为 `true`，则在列表中包含与质押相关的发票。 | `false` |
+| `include_return_staking` | `boolean` | 如果为 `true`，则包含返还质押的发票。 | `false` |
+| `include_recovered_from` | `boolean` | 如果为 `true`，则包含从先前余额中恢复的发票。 | `false` |
+| `status` | `string` | 一个逗号分隔的发票状态字符串，用于显示（例如，`'open,paid,uncollectible'`）。 | `'open,paid,uncollectible'` |
+| `pageSize` | `number` | 每页要获取的发票数量。 | `10` |
+| `target` | `string` | 发票链接的目标属性（例如，`'_self'`，`'_blank'`）。 | `'_self'` |
+| `action` | `string` | 为某些发票定义一个行动号召。设置为 `'pay'` 以显示待支付发票的支付按钮。 | `''` |
+| `type` | `'list' \| 'table'` | 发票列表的显示模式。 | `'list'` |
+| `onTableDataChange` | `Function` | 当发票数据更改时触发的回调函数。 | `() => {}` |
+| `relatedSubscription` | `boolean` | 在 `table` 模式下，如果为 `true`，则显示一个包含相关订阅链接的列。 | `false` |
+
+## 基本用法（列表视图）
+
+默认视图 (`type="list"`) 会渲染一个按日期分组的简单发票列表，并带有无限滚动机制来加载更多项目。
+
+```tsx CustomerInvoiceListPage.tsx icon=logos:react
+import { PaymentProvider, CustomerInvoiceList } from '@blocklet/payment-react';
+
+function InvoiceHistoryPage() {
+  // 假设 customerId 可用，例如，从 session 或 props 中获取
+  const customerId = 'cus_xxxxxxxxxxxxxx';
+
+  return (
+    <PaymentProvider>
+      <CustomerInvoiceList customer_id={customerId} />
+    </PaymentProvider>
+  );
+}
+```
+
+## 表格视图
+
+若要获得更详细、结构化的展示，您可以设置 `type="table"`。此模式会在一个带有可排序列的分页表格中显示发票。
+
+```tsx CustomerInvoiceTablePage.tsx icon=logos:react
+import { PaymentProvider, CustomerInvoiceList } from '@blocklet/payment-react';
+
+function InvoiceHistoryTable() {
+  const customerId = 'cus_xxxxxxxxxxxxxx';
+
+  return (
+    <PaymentProvider>
+      <CustomerInvoiceList
+        customer_id={customerId}
+        type="table"
+        relatedSubscription={true} // 显示相关订阅的列
+        pageSize={5}
+      />
+    </PaymentProvider>
+  );
+}
+```
+
+在此示例中，启用了 `relatedSubscription` 属性来添加一列，该列直接链接到与每张发票关联的订阅，这对于基于订阅的服务非常有用。
+
+## 筛选发票
+
+您可以使用各种属性来筛选所显示的发票。例如，要仅显示与质押相关的已支付发票：
+
+```tsx FilteredInvoiceListPage.tsx icon=logos:react
+import { PaymentProvider, CustomerInvoiceList } from '@blocklet/payment-react';
+
+function FilteredInvoiceList() {
+  const customerId = 'cus_xxxxxxxxxxxxxx';
+
+  return (
+    <PaymentProvider>
+      <CustomerInvoiceList
+        customer_id={customerId}
+        type="table"
+        status="paid" // 仅显示已支付的发票
+        include_staking={true} // 同时包括质押交易
+      />
+    </PaymentProvider>
+  );
+}
+```
+
+## 为待支付发票启用支付功能
+
+通过将 `action` 属性设置为 `'pay'`，您可以为任何状态为 `open` 或 `uncollectible` 的发票添加一个“支付”按钮。点击此按钮将使用 `PaymentProvider` 中的 `connect` 实例来启动支付流程。
+
+```tsx PayableInvoiceListPage.tsx icon=logos:react
+import { PaymentProvider, CustomerInvoiceList } from '@blocklet/payment-react';
+
+function PayableInvoiceList() {
+  const customerId = 'cus_xxxxxxxxxxxxxx';
+
+  return (
+    <PaymentProvider>
+      <CustomerInvoiceList
+        customer_id={customerId}
+        status="open,uncollectible" // 仅显示需要支付的发票
+        action="pay" // 添加“支付”按钮
+      />
+    </PaymentProvider>
+  );
+}
+```

package/docs/components-history-payment-list.ja.md

@@ -0,0 +1,44 @@
+# CustomerPaymentList
+
+`CustomerPaymentList`コンポーネントは、顧客の支払い履歴の詳細をレンダリングします。データの取得、無限スクロールによるページネーション、日付ごとの支払いのグループ化を自動的に処理し、ユーザーの取引履歴を明確かつ整理されたビューで提供します。
+
+このコンポーネントは、顧客が過去の取引を確認する必要があるユーザーダッシュボードやアカウントページに最適です。
+
+## Props
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `customer_id` | `string` | はい | 支払い履歴を表示したい顧客の一意の識別子（例：ユーザーのDID）。 |
+
+## 使用例
+
+`CustomerPaymentList`を使用するには、`PaymentProvider`でラップし、必須の`customer_id`を提供する必要があります。
+
+```tsx Customer Payment History icon=logos:react
+import { PaymentProvider, CustomerPaymentList } from '@blocklet/payment-react';
+import { useSessionContext } from './hooks/useSessionContext'; // セッションコンテキストフックへのパスを調整してください
+
+export default function CustomerDashboard() {
+  const { session, connectApi } = useSessionContext();
+
+  // ユーザーがログインしていることを確認してDIDを取得
+  if (!session?.user?.did) {
+    return <div>支払い履歴を表示するにはログインしてください。</div>;
+  }
+
+  return (
+    <PaymentProvider session={session} connect={connectApi}>
+      <h2>私の支払い履歴</h2>
+      <CustomerPaymentList customer_id={session.user.did} />
+    </PaymentProvider>
+  );
+}
+```
+
+## 機能
+
+- **自動データ取得**: コンポーネントはAPIエンドポイント`/api/payment-intents`から支払いインテントを取得します。
+- **無限スクロール**: ユーザーが要求すると自動的により多くの支払いを読み込み、長い支払い履歴に対しても効率的なデータ処理を保証します。
+- **日付によるグループ化**: 支払いは日付ごとに視覚的にグループ化され、リストを簡単に確認できます。
+- **詳細情報**: 各支払いについて、作成時間、金額、ステータス、説明、および利用可能な場合はブロックチェーン取引へのリンクを表示します。
+- **読み込み中および空の状態**: データ取得中に読み込みインジケーターを含み、顧客に支払い履歴がない場合はユーザーフレンドリーなメッセージを表示します。

package/docs/components-history-payment-list.zh-TW.md

@@ -0,0 +1,44 @@
+# CustomerPaymentList
+
+`CustomerPaymentList` 元件可呈現客戶付款的詳細歷史記錄。它會自動處理擷取、透過無限滾動實現分頁以及按日期將付款分組，從而提供清晰、有條理的使用者交易歷史記錄檢視。
+
+此元件非常適合用於使用者儀表板或帳戶頁面，客戶可以在其中查看過去的交易。
+
+## Props
+
+| Prop | 類型 | 必填 | 說明 |
+|---|---|---|---|
+| `customer_id` | `string` | 是 | 客戶的唯一識別碼（例如，使用者的 DID），您想要顯示其付款歷史記錄。 |
+
+## 使用範例
+
+若要使用 `CustomerPaymentList`，您必須將其包裝在 `PaymentProvider` 中，並提供必要的 `customer_id`。
+
+```tsx Customer Payment History icon=logos:react
+import { PaymentProvider, CustomerPaymentList } from '@blocklet/payment-react';
+import { useSessionContext } from './hooks/useSessionContext'; // 調整到您的 session context hook 的路徑
+
+export default function CustomerDashboard() {
+  const { session, connectApi } = useSessionContext();
+
+  // 確保使用者已登入以取得其 DID
+  if (!session?.user?.did) {
+    return <div>請登入以查看您的付款歷史記錄。</div>;
+  }
+
+  return (
+    <PaymentProvider session={session} connect={connectApi}>
+      <h2>我的付款歷史記錄</h2>
+      <CustomerPaymentList customer_id={session.user.did} />
+    </PaymentProvider>
+  );
+}
+```
+
+## 功能
+
+- **自動資料擷取**：該元件從 API 端點 `/api/payment-intents` 擷取付款意圖。
+- **無限滾動**：當使用者請求時，它會自動載入更多付款，確保對長付款歷史記錄進行有效的資料處理。
+- **日期分組**：付款會按日期進行視覺分組，使清單易於瀏覽。
+- **詳細資訊**：對於每筆付款，它會顯示建立時間、金額、狀態、說明以及區塊鏈交易連結（如果有的話）。
+- **載入中和空白狀態**：它在資料擷取期間包含一個載入指示器，並在客戶沒有付款歷史記錄時顯示一個使用者友善的訊息。

package/docs/components-history-payment-list.zh.md

@@ -0,0 +1,44 @@
+# CustomerPaymentList
+
+`CustomerPaymentList` 组件呈现客户付款的详细历史记录。它通过无限滚动自动处理获取、分页和按日期对付款进行分组，为用户的交易历史提供清晰有序的视图。
+
+此组件非常适用于用户仪表板或客户需要查看其过去交易的账户页面。
+
+## Props
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `customer_id` | `string` | 是 | 客户的唯一标识符（例如，用户的 DID），用于显示其付款历史。 |
+
+## 使用示例
+
+要使用 `CustomerPaymentList`，您必须将其包装在 `PaymentProvider` 中，并提供所需的 `customer_id`。
+
+```tsx Customer Payment History icon=logos:react
+import { PaymentProvider, CustomerPaymentList } from '@blocklet/payment-react';
+import { useSessionContext } from './hooks/useSessionContext'; // 调整到您的会话上下文钩子的路径
+
+export default function CustomerDashboard() {
+  const { session, connectApi } = useSessionContext();
+
+  // 确保用户已登录以获取其 DID
+  if (!session?.user?.did) {
+    return <div>请登录以查看您的付款历史。</div>;
+  }
+
+  return (
+    <PaymentProvider session={session} connect={connectApi}>
+      <h2>我的付款历史</h2>
+      <CustomerPaymentList customer_id={session.user.did} />
+    </PaymentProvider>
+  );
+}
+```
+
+## 功能特性
+
+- **自动数据获取**：该组件从 API 端点 `/api/payment-intents` 获取付款意图。
+- **无限滚动**：当用户请求时，它会自动加载更多付款，从而确保对长付款历史进行高效的数据处理。
+- **日期分组**：付款按日期进行视觉分组，使列表易于浏览。
+- **详细信息**：对于每笔付款，它会显示创建时间、金额、状态、描述以及可用的区块链交易链接。
+- **加载和空状态**：它在数据获取期间包含一个加载指示器，并在客户没有付款历史时显示用户友好的消息。

package/docs/components-history.ja.md

@@ -0,0 +1,67 @@
+# 履歴コンポーネント
+
+`@blocklet/payment-react`ライブラリは、ユーザーが過去のアクティビティを明確かつ詳細に確認できるように設計された一連の履歴コンポーネントを提供します。これらのコンポーネントは、ユーザーが請求、支払い、クレジットの使用状況を追跡する必要がある顧客ポータル、アカウントダッシュボード、および管理インターフェースの構築に不可欠です。
+
+これらのコンポーネントは、支払いサービスから直接データを取得して表示するため、複雑なデータ取得およびレンダリングロジックをゼロから構築することなく、履歴情報をシームレスに提示できます。
+
+<x-cards data-columns="2">
+  <x-card data-title="CustomerInvoiceList" data-icon="lucide:receipt-text" data-href="/components/history/invoice-list">
+    顧客の請求書リストまたはテーブルをレンダリングし、ステータス、金額、作成日の詳細を含みます。
+  </x-card>
+  <x-card data-title="CustomerPaymentList" data-icon="lucide:credit-card" data-href="/components/history/payment-list">
+    顧客の完全な支払い履歴を表示し、取引詳細、支払い方法、ステータスを含みます。
+  </x-card>
+  <x-card data-title="CreditGrantsList" data-icon="lucide:award" data-href="/components/history/credit-grants-list">
+    顧客のすべてのクレジット付与のリストを表示し、ステータス、残額、有効日を詳述します。
+  </x-card>
+  <x-card data-title="CreditTransactionsList" data-icon="lucide:history" data-href="/components/history/credit-transactions-list">
+    個々のすべてのクレジット取引をリスト表示し、クレジットの使用状況と経時的な調整の詳細なログを提供します。
+  </x-card>
+</x-cards>
+
+## 一般的なユースケース
+
+一般的なユースケースは、ユーザーのアカウントページに「請求履歴」セクションを作成することです。タブ付きインターフェースを使用して、請求書、支払い、クレジットなどの異なる履歴ビューを切り替えることができます。
+
+以下は、そのようなページを構成する方法の概念的な例です。
+
+```jsx MyBillingPage.tsx icon=lucide:user
+import React from 'react';
+import { CustomerInvoiceList, CustomerPaymentList } from '@blocklet/payment-react';
+
+// セッションまたはコンテキストから顧客IDを取得していると仮定します
+const customerId = 'cus_xxxxxxxxxxxxxx';
+
+export default function MyBillingPage() {
+  // 実際のアプリケーションでは、stateを使用してアクティブなタブを管理します
+  const [activeTab, setActiveTab] = React.useState('invoices');
+
+  return (
+    <div>
+      <h1>Billing History</h1>
+      <nav>
+        <button onClick={() => setActiveTab('invoices')}>Invoices</button>
+        <button onClick={() => setActiveTab('payments')}>Payments</button>
+      </nav>
+
+      <div style={{ marginTop: '20px' }}>
+        {activeTab === 'invoices' && (
+          <CustomerInvoiceList 
+            customer_id={customerId} 
+            type="table" 
+          />
+        )}
+        {activeTab === 'payments' && (
+          <CustomerPaymentList 
+            customer_id={customerId} 
+          />
+        )}
+      </div>
+    </div>
+  );
+}
+```
+
+この例は、履歴コンポーネントを簡単に埋め込むことで、包括的なセルフサービスの請求情報をユーザーに提供する方法を示しています。各コンポーネントは、独自のデータ取得、ページネーション、および表示ロジックを処理します。
+
+各コンポーネントの詳細なドキュメントを参照して、その特定のプロパティとカスタマイズオプションを理解してください。