@blocklet/payment-react/docs/providers-payment-provider.ja.md

Reusable react components for payment kit v2

# PaymentProvider

`PaymentProvider`は、`@blocklet/payment-react`ライブラリの基盤です。これはコンテキストプロバイダーとして機能し、アプリケーションまたは関連する支払いコンポーネントをラップする必要があります。重要な設定の取得、アプリケーションの状態管理、ヘルパー関数とAPIクライアントのすべての子コンポーネントへの提供を担当します。

このライブラリのほぼすべてのコンポーネントとフックは、正しく機能するために`PaymentProvider`内にネストされている必要があります。

## 仕組み

このプロバイダーは、マウント時にPayment Kitのバックエンドから設定データを初期化して取得します。このデータは、ユーザーのセッションやその他のユーティリティとともに、`usePaymentContext`フックを介してすべての子孫コンポーネントで利用可能になります。このパターンにより、支払いコンポーネントはプロップのバケツリレー（prop drilling）なしで、常に必要なコンテキストにアクセスできるようになります。

<!-- DIAGRAM_IMAGE_START:architecture:16:9 -->
![PaymentProvider](assets/diagram/payment-provider-diagram-0.jpg)
<!-- DIAGRAM_IMAGE_END -->

## セットアップと使用法

`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)コンポーネントを使用して支払いフローを作成する方法を確認することをお勧めします。