@arcblock/did-connect-react 3.1.40 → 3.1.42

package/docs/advanced.zh-TW.md

@@ -0,0 +1,95 @@
+# 進階主題
+
+當您熟悉 `SessionProvider` 和 `DidConnect` 等核心元件後，就可以探索 `@arcblock/did-connect-react` 程式庫更強大、更靈活的功能。本節涵蓋了進階主題，讓您能夠建構更複雜、更健全且更方便使用者使用的去中心化身分應用程式。
+
+我們將探討三個主要領域：
+
+1.  **替代驗證方法**：超越預設的 QR code 掃描，整合流行的登入方法，如 OAuth（社交登入）、Passkeys（無密碼）和统一登录站点群。
+2.  **公用程式函式**：利用一套輔助函式來處理常見任務，例如 URL 編碼、建立 API 用戶端和管理彈出視窗。
+3.  **錯誤處理**：學習如何優雅地處理常見錯誤，從被封鎖的彈出視窗到 WebAuthn API 失敗，確保流暢的使用者體驗。
+
+---
+
+## 驗證方法
+
+雖然 DID Connect 是主要的驗證方法，但該程式庫提供了與其他流行登入流程的無縫整合。這讓您可以為使用者提供多種登入方式，以滿足不同的偏好和安全等級。
+
+<x-card data-title="探索驗證方法" data-icon="lucide:key-round" data-href="/advanced/authentication-methods" data-cta="了解更多">
+深入了解在您的應用程式中實作 OAuth（社交登入）、Passkeys（無密碼）和统一登录站点群的詳細指南。
+</x-card>
+
+## 公用程式
+
+該程式庫匯出一系列公用程式函式，旨在簡化您應用程式中的常見任務並減少樣板程式碼。這些輔助工具涵蓋了從資料編碼和密碼學操作到管理驗證流程的瀏覽器彈出視窗等所有內容。
+
+<x-card data-title="瀏覽公用程式函式" data-icon="lucide:wrench" data-href="/advanced/utilities" data-cta="檢視參考">
+探索所有輔助函式的綜合參考，包括 URL 操作、API 用戶端建立、資料加密等範例。
+</x-card>
+
+## 錯誤處理
+
+建構一個健全的應用程式需要優雅的錯誤處理。`@arcblock/did-connect-react` 程式庫提供了特定的錯誤類型和輔助函式，使此過程更加容易。
+
+### 彈出視窗錯誤
+
+當使用需要彈出視窗的驗證方法（如 OAuth）時，瀏覽器的彈出視窗攔截器可能會干擾。如果 `openPopup` 函式無法開啟視窗，它將拋出 `NotOpenError`。您應該捕獲此錯誤並向使用者提供適當的回饋。
+
+```javascript 處理彈出視窗錯誤 icon=logos:javascript
+import { openPopup, runPopup } from '@arcblock/did-connect-react/lib/utils';
+import { NotOpenError } from '@arcblock/did-connect-react/lib/error';
+
+async function startOAuthFlow(url) {
+  try {
+    const popup = openPopup(url);
+    const result = await runPopup({ popup });
+    console.log('OAuth 成功：', result);
+  } catch (err) {
+    if (err instanceof NotOpenError) {
+      alert('彈出視窗被封鎖。請允許本網站的彈出視窗，然後再試一次。');
+    } else {
+      alert(`發生錯誤：${err.message}`);
+    }
+  }
+}
+```
+
+### API 和 WebAuthn 錯誤
+
+對於與後端服務或 WebAuthn API（由 Passkeys 使用）的互動，該程式庫提供了輔助函式，可將複雜的錯誤物件解析為方便使用者閱讀的訊息。
+
+- `getApiErrorMessage(err, defaultMessage)`：從 Axios 錯誤回應中提取錯誤訊息。
+- `getWebAuthnErrorMessage(err, defaultMessage, t)`：處理 WebAuthn 特定錯誤（例如，使用者取消、不支援的瀏覽器）並提供可翻譯、方便使用者閱讀的訊息。
+
+```javascript 處理 WebAuthn 錯誤 icon=logos:javascript
+import { usePasskey } from '@arcblock/did-connect-react';
+import { getWebAuthnErrorMessage } from '@arcblock/did-connect-react/lib/utils';
+
+function PasskeyLoginButton() {
+  const { loginWithPasskey } = usePasskey();
+
+  const handleLogin = async () => {
+    try {
+      await loginWithPasskey();
+      // 處理成功登入
+    } catch (err) {
+      // 使用公用程式以取得方便使用者閱讀的訊息
+      const friendlyMessage = getWebAuthnErrorMessage(err, '發生未知錯誤。');
+      alert(friendlyMessage);
+    }
+  };
+
+  return <button onClick={handleLogin}>使用 Passkey 登入</button>;
+}
+```
+
+透過實作適當的錯誤處理，您可以在事情未按計劃進行時顯著改善使用者體驗。
+
+---
+
+## 後續步驟
+
+現在您已對進階功能有了概覽，可以更深入地探討與您的專案最相關的主題。
+
+- **[驗證方法](./advanced-authentication-methods.md)**：為您的使用者實作新的登入方式。
+- **[公用程式](./advanced-utilities.md)**：使用我們的輔助函式簡化您的程式碼。
+- **[API 參考](./api-reference.md)**：全面、詳細地了解所有元件、掛鉤和函式。

package/docs/advanced.zh.md

@@ -0,0 +1,95 @@
+# 高级主题
+
+当您熟悉 `SessionProvider` 和 `DidConnect` 等核心组件后，就可以开始探索 `@arcblock/did-connect-react` 库更强大、更灵活的功能了。本节将介绍一些高级主题，帮助您构建更复杂、更健壮、更用户友好的去中心化身份应用。
+
+我们将探讨三个主要领域：
+
+1.  **替代身份验证方法**：超越默认的二维码扫描方式，集成 OAuth（社交登录）、Passkeys（无密码登录）和统一登录等流行的登录方法。
+2.  **实用工具函数**：利用一套辅助函数来处理常见任务，如 URL 编码、创建 API 客户端和管理弹出窗口。
+3.  **错误处理**：学习如何优雅地处理常见错误，从弹出窗口被阻止到 WebAuthn API 失败，以确保流畅的用户体验。
+
+---
+
+## 身份验证方法
+
+虽然 DID Connect 是主要的身份验证方法，但该库也无缝集成了其他流行的登录流程。这使您可以为用户提供多种登录方式，以满足不同的偏好和安全级别。
+
+<x-card data-title="探索身份验证方法" data-icon="lucide:key-round" data-href="/advanced/authentication-methods" data-cta="了解更多">
+深入了解在您的应用中实现 OAuth（社交登录）、Passkeys（无密码登录）和统一登录的详细指南。
+</x-card>
+
+## 实用工具
+
+该库导出了一系列实用工具函数，旨在简化常见任务并减少应用程序中的样板代码。这些辅助工具涵盖了从数据编码和加密操作到管理身份验证流程的浏览器弹出窗口等所有方面。
+
+<x-card data-title="浏览实用工具函数" data-icon="lucide:wrench" data-href="/advanced/utilities" data-cta="查看参考">
+查看所有辅助函数的综合参考，包括 URL 操作、API 客户端创建、数据加密等示例。
+</x-card>
+
+## 错误处理
+
+构建一个健壮的应用程序需要优雅的错误处理。`@arcblock/did-connect-react` 库提供了特定的错误类型和辅助函数，使这个过程更容易。
+
+### 弹出窗口错误
+
+当使用需要弹出窗口的身份验证方法（如 OAuth）时，浏览器的弹出窗口拦截器可能会造成干扰。如果 `openPopup` 函数无法打开窗口，它将抛出一个 `NotOpenError`。您应该捕获此错误并向用户提供适当的反馈。
+
+```javascript 处理弹出窗口错误 icon=logos:javascript
+import { openPopup, runPopup } from '@arcblock/did-connect-react/lib/utils';
+import { NotOpenError } from '@arcblock/did-connect-react/lib/error';
+
+async function startOAuthFlow(url) {
+  try {
+    const popup = openPopup(url);
+    const result = await runPopup({ popup });
+    console.log('OAuth 成功:', result);
+  } catch (err) {
+    if (err instanceof NotOpenError) {
+      alert('弹出窗口被阻止。请允许此站点的弹出窗口并重试。');
+    } else {
+      alert(`发生错误: ${err.message}`);
+    }
+  }
+}
+```
+
+### API 和 WebAuthn 错误
+
+对于与后端服务或 WebAuthn API（由 Passkeys 使用）的交互，该库提供了辅助函数，可将复杂的错误对象解析为用户友好的消息。
+
+- `getApiErrorMessage(err, defaultMessage)`：从 Axios 错误响应中提取错误消息。
+- `getWebAuthnErrorMessage(err, defaultMessage, t)`：处理 WebAuthn 特定错误（例如，用户取消、浏览器不支持）并提供可翻译的用户友好消息。
+
+```javascript 处理 WebAuthn 错误 icon=logos:javascript
+import { usePasskey } from '@arcblock/did-connect-react';
+import { getWebAuthnErrorMessage } from '@arcblock/did-connect-react/lib/utils';
+
+function PasskeyLoginButton() {
+  const { loginWithPasskey } = usePasskey();
+
+  const handleLogin = async () => {
+    try {
+      await loginWithPasskey();
+      // 处理成功登录
+    } catch (err) {
+      // 使用该实用工具获取用户友好的消息
+      const friendlyMessage = getWebAuthnErrorMessage(err, '发生未知错误。');
+      alert(friendlyMessage);
+    }
+  };
+
+  return <button onClick={handleLogin}>使用 Passkey 登录</button>;
+}
+```
+
+通过实施适当的错误处理，您可以在出现意外情况时显著改善用户体验。
+
+---
+
+## 后续步骤
+
+既然您已经对高级功能有了大致了解，您可以更深入地研究与您的项目最相关的主题。
+
+- **[身份验证方法](./advanced-authentication-methods.md)**：为您的用户实现新的登录方式。
+- **[实用工具](./advanced-utilities.md)**：使用我们的辅助函数简化您的代码。
+- **[API 参考](./api-reference.md)**：全面、详细地了解所有组件、钩子和函数。

package/docs/api-reference.ja.md

@@ -0,0 +1,178 @@
+# APIリファレンス
+
+このセクションでは、`@arcblock/did-connect-react` ライブラリ全体で使用される主要なTypeScript型すべてに関する包括的なリファレンスを提供します。これらのデータ構造を理解することは、`SessionProvider`のようなコンポーネントや`useConnect`のようなフックを効果的に使用する上で非常に重要です。
+
+## 接続タイプ
+
+これらのタイプは、主にDID Connectモーダルの設定や操作時に使用されます。
+
+### ConnectProps
+
+これは、`useConnect`フックの`open`関数またはセッションコンテキストの`openDidConnect`関数に渡される主要な設定オブジェクトです。これにより、接続フローの動作と外観を広範囲にカスタマイズできます。
+
+<x-field-group>
+  <x-field data-name="action" data-type="string" data-required="true" data-desc="接続の主要なアクション。例: 'login'。"></x-field>
+  <x-field data-name="containerEl" data-type="Element" data-required="false" data-desc="接続モーダルを追加するDOM要素。"></x-field>
+  <x-field data-name="prefix" data-type="string" data-default="/api/did" data-required="false" data-desc="DID ConnectサービスのAPIエンドポイントプレフィックス。"></x-field>
+  <x-field data-name="locale" data-type="'en' | 'zh'" data-default="en" data-required="false" data-desc="UIで使用される言語。"></x-field>
+  <x-field data-name="popup" data-type="boolean" data-default="false" data-required="false" data-desc="trueの場合、接続UIはモーダルの代わりにポップアップウィンドウで表示されます。"></x-field>
+  <x-field data-name="checkInterval" data-type="number" data-default="2000" data-required="false" data-desc="セッションステータスをチェックする間隔（ミリ秒）。"></x-field>
+  <x-field data-name="checkTimeout" data-type="number" data-default="300000" data-required="false" data-desc="セッションチェックプロセス全体タイムアウト（ミリ秒）（5分）。"></x-field>
+  <x-field data-name="closeTimeout" data-type="number" data-default="2000" data-required="false" data-desc="接続成功後にモーダルを閉じるまでの遅延時間（ミリ秒）。"></x-field>
+  <x-field data-name="extraParams" data-type="object" data-default="{}" data-required="false" data-desc="接続リクエストと共に送信される追加のパラメータ。"></x-field>
+  <x-field data-name="tokenKey" data-type="string" data-default="_t_" data-required="false" data-desc="セッショントークンを保存するために使用されるキー。"></x-field>
+  <x-field data-name="encKey" data-type="string" data-default="_ek_" data-required="false" data-desc="暗号化に使用されるキー。"></x-field>
+  <x-field data-name="baseUrl" data-type="string" data-default="''" data-required="false" data-desc="APIリクエストのベースURL。"></x-field>
+  <x-field data-name="messages" data-type="ConnectMessages" data-required="false" data-desc="接続UIに表示されるテキストをカスタマイズするためのオブジェクト。"></x-field>
+  <x-field data-name="autoConnect" data-type="boolean" data-default="true" data-required="false" data-desc="trueの場合、保存されたセッションを使用して自動的に接続を試みます。"></x-field>
+  <x-field data-name="forceConnected" data-type="boolean | string" data-default="true" data-required="false" data-desc="接続が確立されたものとして強制的に扱います。"></x-field>
+  <x-field data-name="saveConnect" data-type="boolean" data-default="true" data-required="false" data-desc="trueの場合、成功した接続セッションはautoConnectのために保存されます。"></x-field>
+  <x-field data-name="useSocket" data-type="boolean" data-default="true" data-required="false" data-desc="trueの場合、リアルタイムのステータス更新にWebSocketを使用します。"></x-field>
+  <x-field data-name="allowWallet" data-type="boolean" data-default="true" data-required="false" data-desc="trueの場合、DID Wallet経由での接続を許可します。"></x-field>
+  <x-field data-name="passkeyBehavior" data-type="'none' | 'both' | 'only-existing' | 'only-new'" data-default="true" data-required="false" data-desc="認証プロセス中にパスキーをどのように処理するかを定義します。"></x-field>
+  <x-field data-name="provider" data-type="'wallet' | 'auth0' | ''" data-default="wallet" data-required="false" data-desc="認証プロバイダーを指定します。"></x-field>
+  <x-field data-name="qrcodeSize" data-type="number" data-default="160" data-required="false" data-desc="QRコードのサイズ（ピクセル単位）。"></x-field>
+  <x-field data-name="showDownload" data-type="boolean" data-default="true" data-required="false" data-desc="trueの場合、DID Walletのダウンロードリンクを表示します。"></x-field>
+  <x-field data-name="webWalletUrl" data-type="string" data-default="https://web.abtwallet.io" data-required="false" data-desc="ウェブベースのDID WalletのURL。"></x-field>
+  <x-field data-name="enabledConnectTypes" data-type="Array<'web' | 'mobile' | 'auth0' | 'github' | 'apple' | 'google' | 'passkey'>" data-default='["web", "mobile", "github", "apple", "google", "auth0", "passkey"]' data-required="false" data-desc="UIで有効にする接続方法の配列。"></x-field>
+  <x-field data-name="extraContent" data-type="any" data-required="false" data-desc="接続モーダル内にレンダリングされるカスタムコンテンツ。"></x-field>
+  <x-field data-name="loadingEle" data-type="any" data-required="false" data-desc="表示するカスタムローディング要素。"></x-field>
+  <x-field data-name="disableSwitchApp" data-type="boolean" data-default="false" data-required="false" data-desc="trueの場合、モバイルデバイスでの自動アプリ切り替えを無効にします。"></x-field>
+  <x-field data-name="hideCloseButton" data-type="boolean" data-default="false" data-required="false" data-desc="trueの場合、モーダルの閉じるボタンを非表示にします。"></x-field>
+  <x-field data-name="options" data-type="object" data-default="{}" data-required="false">
+    <x-field-desc markdown>追加の設定オプション。</x-field-desc>
+    <x-field data-name="showQuickConnect" data-type="boolean" data-default="true" data-required="false" data-desc="trueの場合、保存されたセッションのクイック接続オプションを表示します。"></x-field>
+  </x-field>
+  <x-field data-name="onRecreateSession" data-type="Function" data-required="false" data-desc="セッションが再作成されたときに実行されるコールバック関数。"></x-field>
+  <x-field data-name="checkFn" data-type="() => boolean" data-required="false" data-desc="接続ステータスをチェックするためのカスタム関数。"></x-field>
+  <x-field data-name="onSuccess" data-type="(result: object) => void" data-required="false" data-desc="接続が成功したときに実行されるコールバック関数。"></x-field>
+  <x-field data-name="onError" data-type="(error: any) => void" data-required="false" data-desc="エラーが発生したときに実行されるコールバック関数。"></x-field>
+  <x-field data-name="onClose" data-type="Function" data-required="false" data-desc="接続モーダルが閉じられたときに実行されるコールバック関数。"></x-field>
+</x-field-group>
+
+### ConnectMessages
+
+DID Connect UI内に表示されるテキストをカスタマイズするためのオブジェクト。
+
+<x-field-group>
+  <x-field data-name="title" data-type="string" data-required="true" data-desc="接続モーダルのメインタイトル。"></x-field>
+  <x-field data-name="scan" data-type="string" data-required="true" data-desc="QRコードをスキャンするための指示テキスト。"></x-field>
+  <x-field data-name="success" data-type="ReactNode" data-required="true" data-desc="接続成功時に表示されるメッセージまたはコンポーネント。"></x-field>
+  <x-field data-name="confirm" data-type="string" data-required="false" data-desc="ユーザーにウォレットでのアクションの確認を促すテキスト。"></x-field>
+  <x-field data-name="error" data-type="string" data-required="false" data-desc="表示するカスタムエラーメッセージ。"></x-field>
+</x-field-group>
+
+### OpenDidConnect
+
+この関数型は、高度な要件でDID Connectフローを開くためのシグネチャを定義します。これはしばしばプログレッシブ認証に使用されます。
+
+<x-field-group>
+  <x-field data-name="params" data-type="ConnectProps" data-required="true" data-desc="標準の接続プロパティ。"></x-field>
+  <x-field data-name="options" data-type="object" data-required="false" data-desc="接続モードを制御し、要件を指定するための追加オプション。">
+    <x-field data-name="openMode" data-type="'redirect' | 'window' | 'popup'" data-default="popup" data-required="false" data-desc="DID Connectウィンドウの開き方を決定します。"></x-field>
+    <x-field data-name="requirements" data-type="object" data-required="false" data-desc="セッションの要件を指定します。">
+      <x-field data-name="login" data-type="boolean" data-default="true" data-required="false" data-desc="trueの場合、ユーザーがログインしている必要があります。"></x-field>
+      <x-field data-name="bindWallet" data-type="boolean" data-default="true" data-required="false" data-desc="trueの場合、ユーザーがDID Walletアカウントをバインドしている必要があります。"></x-field>
+      <x-field data-name="bindDidSpaces" data-type="false | 'read' | 'full'" data-default="false" data-required="false" data-desc="DID Spacesのバインドが必要かどうか、およびどのレベルのアクセスが必要かを指定します。"></x-field>
+    </x-field>
+    <x-field data-name="baseUrl" data-type="string" data-required="false" data-desc="APIリクエストのベースURL。"></x-field>
+    <x-field data-name="locale" data-type="BaseLocale" data-required="false" data-desc="UIの言語（'en' または 'zh'）。"></x-field>
+  </x-field>
+</x-field-group>
+
+## セッションとユーザーのタイプ
+
+これらのタイプは、`SessionProvider`によって管理されるユーザーとセッションデータの構造を定義します。
+
+### SessionProps
+
+`useSession`フックを介してアクセス可能なメインセッションオブジェクト。ユーザーの状態、セッション情報、およびセッションを管理するためのメソッドが含まれています。
+
+<x-field-group>
+  <x-field data-name="action" data-type="string" data-desc="現在実行中のアクション（例: 'login'）。"></x-field>
+  <x-field data-name="error" data-type="string" data-desc="セッション管理中に発生したエラーメッセージ。"></x-field>
+  <x-field data-name="initialized" data-type="boolean" data-desc="セッションが初期化されている場合はtrue。"></x-field>
+  <x-field data-name="loading" data-type="boolean" data-desc="セッションが現在ローディング状態の場合はtrue。"></x-field>
+  <x-field data-name="open" data-type="boolean" data-desc="DID Connectモーダルが現在開いている場合はtrue。"></x-field>
+  <x-field data-name="walletOS" data-type="WalletOS" data-desc="接続されたウォレットのオペレーティングシステム（'web'、'android'、'ios'）。"></x-field>
+  <x-field data-name="user" data-type="User" data-desc="認証されたユーザーオブジェクト。ユーザーがログインしていない場合は未定義。"></x-field>
+  <x-field data-name="locale" data-type="UserLocale" data-desc="ユーザーの現在のロケール。"></x-field>
+  <x-field data-name="provider" data-type="WalletProvider" data-desc="現在のセッションで使用されているプロバイダー。"></x-field>
+  <x-field data-name="baseUrl" data-type="string" data-desc="API呼び出しに使用されるベースURL。"></x-field>
+  <x-field data-name="federatedMaster" data-type="object" data-desc="フェデレーションログイングループのマスターサイトに関する情報。"></x-field>
+  <x-field data-name="login" data-type="LoginSessionFn" data-desc="ログインプロセスを開始する関数。"></x-field>
+  <x-field data-name="logout" data-type="LogoutSessionFn" data-desc="ユーザーをログアウトさせる関数。"></x-field>
+  <x-field data-name="switch" data-type="Function" data-desc="異なるユーザーアカウントを切り替える関数。"></x-field>
+  <x-field data-name="switchDid" data-type="CommonSessionFn" data-desc="ユーザーのアクティブなDIDを切り替える関数。"></x-field>
+  <x-field data-name="autoSwitchDid" data-type="Function" data-desc="DIDを自動的に切り替える関数。"></x-field>
+  <x-field data-name="switchProfile" data-type="CommonSessionFn" data-desc="ユーザープロファイルを切り替える関数。"></x-field>
+  <x-field data-name="switchPassport" data-type="CommonSessionFn" data-desc="異なるパスポートを切り替える関数。"></x-field>
+  <x-field data-name="bindWallet" data-type="CommonSessionFn" data-desc="ウォレットのバインドプロセスを開始する関数。"></x-field>
+  <x-field data-name="refresh" data-type="Function" data-desc="セッションデータを手動で更新する関数。"></x-field>
+  <x-field data-name="updateConnectedInfo" data-type="(data: object) => void" data-desc="接続情報を更新する関数。"></x-field>
+  <x-field data-name="openDidConnect" data-type="OpenDidConnect" data-desc="高度な要件でDID Connectモーダルを開く関数。"></x-field>
+  <x-field data-name="useOAuth" data-type="Function" data-desc="OAuth統合のためのフック。"></x-field>
+  <x-field data-name="OAuthProvider" data-type="Function" data-desc="OAuthコンテキストのプロバイダーコンポーネント。"></x-field>
+  <x-field data-name="OAuthConsumer" data-type="Function" data-desc="OAuthコンテキストのコンシューマーコンポーネント。"></x-field>
+  <x-field data-name="OAuthContext" data-type="object" data-desc="OAuth用のReactコンテキストオブジェクト。"></x-field>
+  <x-field data-name="usePasskey" data-type="Function" data-desc="パスキー統合のためのフック。"></x-field>
+  <x-field data-name="PasskeyProvider" data-type="Function" data-desc="パスキーコンテキストのプロバイダーコンポーネント。"></x-field>
+  <x-field data-name="PasskeyConsumer" data-type="Function" data-desc="パスキーコンテキストのコンシューマーコンポーネント。"></x-field>
+  <x-field data-name="PasskeyContext" data-type="object" data-desc="パスキー用のReactコンテキストオブジェクト。"></x-field>
+  <x-field data-name="useDid" data-type="(options: { session: Session }) => void" data-desc="DID情報を扱うためのユーティリティフック。"></x-field>
+  <x-field data-name="WrapDid" data-type="Function" data-desc="DID機能に関連するラッパーコンポーネント。"></x-field>
+  <x-field data-name="getUserSessions" data-type="() => Promise<UserSession[]>" data-desc="現在のユーザーのすべてのアクティブなセッションを取得する関数。"></x-field>
+</x-field-group>
+
+### User
+
+認証されたユーザーの詳細なプロファイルを表します。
+
+<x-field-group>
+  <x-field data-name="did" data-type="string" data-required="true" data-desc="ユーザーの分散型識別子（DID）。"></x-field>
+  <x-field data-name="pk" data-type="string" data-required="true" data-desc="ユーザーの公開鍵。"></x-field>
+  <x-field data-name="avatar" data-type="string" data-required="true" data-desc="ユーザーのアバターのURL。"></x-field>
+  <x-field data-name="fullName" data-type="string" data-required="true" data-desc="ユーザーのフルネーム。"></x-field>
+  <x-field data-name="email" data-type="string" data-required="true" data-desc="ユーザーのメールアドレス。"></x-field>
+  <x-field data-name="role" data-type="UserRole" data-required="true" data-desc="アプリケーション内でのユーザーの役割（例: 'guest'、'member'、'admin'）。"></x-field>
+  <x-field data-name="locale" data-type="UserLocale" data-required="true" data-desc="ユーザーの優先言語。"></x-field>
+  <x-field data-name="connectedAccounts" data-type="ConnectAccount[]" data-required="true" data-desc="ユーザーのDIDに接続されているアカウントのリスト。"></x-field>
+  <x-field data-name="passports" data-type="Passport[]" data-required="true" data-desc="ユーザーに関連付けられたパスポートのリスト。"></x-field>
+  <x-field data-name="permissions" data-type="any[]" data-required="true" data-desc="ユーザーに付与された権限のリスト。"></x-field>
+  <x-field data-name="didSpace" data-type="object" data-required="false" data-desc="ユーザーのDID Spaceに関する情報。"></x-field>
+  <x-field data-name="approved" data-type="boolean" data-required="true" data-desc="ユーザーが承認されているかどうかを示します。"></x-field>
+  <x-field data-name="remark" data-type="string" data-required="false" data-desc="ユーザーに関するオプションの備考またはメモ。"></x-field>
+  <x-field data-name="createdAt" data-type="string" data-required="true" data-desc="ユーザーアカウントが作成されたときのタイムスタンプ。"></x-field>
+  <x-field data-name="updatedAt" data-type="string" data-required="true" data-desc="ユーザーアカウントが最後に更新されたときのタイムスタンプ。"></x-field>
+  <x-field data-name="firstLoginAt" data-type="string" data-required="false" data-desc="ユーザーの初回ログイン時のタイムスタンプ。"></x-field>
+  <x-field data-name="lastLoginAt" data-type="string" data-required="false" data-desc="ユーザーの最終ログイン時のタイムスタンプ。"></x-field>
+  <x-field data-name="lastLoginIp" data-type="string" data-required="false" data-desc="ユーザーの最終ログイン時のIPアドレス。"></x-field>
+</x-field-group>
+
+### UserSession
+
+ユーザーの単一のアクティブなセッションを表し、通常は`getUserSessions`から取得されます。
+
+<x-field-group>
+  <x-field data-name="id" data-type="string" data-required="true" data-desc="セッションの一意の識別子。"></x-field>
+  <x-field data-name="appName" data-type="string" data-required="true" data-desc="このセッションのアプリケーション名。"></x-field>
+  <x-field data-name="appPid" data-type="string" data-required="true" data-desc="アプリケーションのパスポートID。"></x-field>
+  <x-field data-name="updatedAt" data-type="string" data-required="true" data-desc="セッションが最後に更新されたときのタイムスタンプ。"></x-field>
+  <x-field data-name="userDid" data-type="string" data-required="true" data-desc="このセッションのユーザーのDID。"></x-field>
+  <x-field data-name="visitorId" data-type="string" data-required="true" data-desc="セッションに関連付けられたビジターID。"></x-field>
+  <x-field data-name="extra" data-type="object" data-required="true" data-desc="セッションに関連付けられた追加データ。"></x-field>
+  <x-field data-name="user" data-type="SessionUser" data-required="true" data-desc="セッション用の簡略化されたユーザーオブジェクト。"></x-field>
+  <x-field data-name="passportId" data-type="string" data-required="false" data-desc="このセッションで使用されたパスポートのID。"></x-field>
+</x-field-group>
+
+### コアデータ型
+
+これらは、他のさまざまなインターフェースで使用される基本的な文字列共用体型です。
+
+| タイプ | 説明 | 可能な値 |
+| --- | --- | --- |
+| `WalletProvider` | 認証方法またはプロバイダーを識別します。 | `wallet`, `auth0`, `apple`, `github`, `google`, `passkey` |
+| `WalletOS` | DID Walletのオペレーティングシステムを表します。 | `web`, `android`, `ios`, `''` (空文字列) |
+| `UserRole` | アプリケーション内でのユーザーの役割を定義します。 | `guest`, `member`, `admin`, `owner`, または任意の `string` |
+| `BaseLocale` | サポートされている言語の基本セット。 | `en`, `zh` |
+| `UserLocale` | ユーザーのロケール。基本ロケールまたはより具体的なロケールを指定できます。 | `en`, `zh`, または任意の `string` (例: 'en-US') |

package/docs/api-reference.md

@@ -0,0 +1,178 @@
+# API Reference
+
+This section provides a comprehensive reference for all the major TypeScript types used throughout the `@arcblock/did-connect-react` library. Understanding these data structures is crucial for effectively using components like `SessionProvider` and hooks like `useConnect`.
+
+## Connection Types
+
+These types are primarily used when configuring and interacting with the DID Connect modal.
+
+### ConnectProps
+
+This is the main configuration object passed to the `open` function from the `useConnect` hook or the `openDidConnect` function from the session context. It allows for extensive customization of the connection flow's behavior and appearance.
+
+<x-field-group>
+  <x-field data-name="action" data-type="string" data-required="true" data-desc="The primary action for the connection, e.g., 'login'."></x-field>
+  <x-field data-name="containerEl" data-type="Element" data-required="false" data-desc="The DOM element to which the connection modal should be appended."></x-field>
+  <x-field data-name="prefix" data-type="string" data-default="/api/did" data-required="false" data-desc="The API endpoint prefix for DID Connect services."></x-field>
+  <x-field data-name="locale" data-type="'en' | 'zh'" data-default="en" data-required="false" data-desc="The language to be used for the UI."></x-field>
+  <x-field data-name="popup" data-type="boolean" data-default="false" data-required="false" data-desc="If true, the connection UI will be displayed in a popup window instead of a modal."></x-field>
+  <x-field data-name="checkInterval" data-type="number" data-default="2000" data-required="false" data-desc="The interval in milliseconds to check the session status."></x-field>
+  <x-field data-name="checkTimeout" data-type="number" data-default="300000" data-required="false" data-desc="The timeout in milliseconds for the entire session check process (5 minutes)."></x-field>
+  <x-field data-name="closeTimeout" data-type="number" data-default="2000" data-required="false" data-desc="The delay in milliseconds before closing the modal after a successful connection."></x-field>
+  <x-field data-name="extraParams" data-type="object" data-default="{}" data-required="false" data-desc="Any extra parameters to be sent with the connection request."></x-field>
+  <x-field data-name="tokenKey" data-type="string" data-default="_t_" data-required="false" data-desc="The key used to store the session token."></x-field>
+  <x-field data-name="encKey" data-type="string" data-default="_ek_" data-required="false" data-desc="The key used for encryption."></x-field>
+  <x-field data-name="baseUrl" data-type="string" data-default="''" data-required="false" data-desc="The base URL for API requests."></x-field>
+  <x-field data-name="messages" data-type="ConnectMessages" data-required="false" data-desc="An object to customize the text displayed in the connection UI."></x-field>
+  <x-field data-name="autoConnect" data-type="boolean" data-default="true" data-required="false" data-desc="If true, automatically attempts to connect using a saved session."></x-field>
+  <x-field data-name="forceConnected" data-type="boolean | string" data-default="true" data-required="false" data-desc="Forces the connection to be treated as established."></x-field>
+  <x-field data-name="saveConnect" data-type="boolean" data-default="true" data-required="false" data-desc="If true, the successful connection session will be saved for autoConnect."></x-field>
+  <x-field data-name="useSocket" data-type="boolean" data-default="true" data-required="false" data-desc="If true, uses WebSockets for real-time status updates."></x-field>
+  <x-field data-name="allowWallet" data-type="boolean" data-default="true" data-required="false" data-desc="If true, allows connection via DID Wallet."></x-field>
+  <x-field data-name="passkeyBehavior" data-type="'none' | 'both' | 'only-existing' | 'only-new'" data-default="true" data-required="false" data-desc="Defines how Passkeys are handled during the authentication process."></x-field>
+  <x-field data-name="provider" data-type="'wallet' | 'auth0' | ''" data-default="wallet" data-required="false" data-desc="Specifies the authentication provider."></x-field>
+  <x-field data-name="qrcodeSize" data-type="number" data-default="160" data-required="false" data-desc="The size of the QR code in pixels."></x-field>
+  <x-field data-name="showDownload" data-type="boolean" data-default="true" data-required="false" data-desc="If true, shows download links for the DID Wallet."></x-field>
+  <x-field data-name="webWalletUrl" data-type="string" data-default="https://web.abtwallet.io" data-required="false" data-desc="The URL for the web-based DID Wallet."></x-field>
+  <x-field data-name="enabledConnectTypes" data-type="Array<'web' | 'mobile' | 'auth0' | 'github' | 'apple' | 'google' | 'passkey'>" data-default='["web", "mobile", "github", "apple", "google", "auth0", "passkey"]' data-required="false" data-desc="An array of connection methods to enable in the UI."></x-field>
+  <x-field data-name="extraContent" data-type="any" data-required="false" data-desc="Custom content to be rendered within the connection modal."></x-field>
+  <x-field data-name="loadingEle" data-type="any" data-required="false" data-desc="A custom loading element to display."></x-field>
+  <x-field data-name="disableSwitchApp" data-type="boolean" data-default="false" data-required="false" data-desc="If true, disables the automatic app switching on mobile devices."></x-field>
+  <x-field data-name="hideCloseButton" data-type="boolean" data-default="false" data-required="false" data-desc="If true, hides the close button in the modal."></x-field>
+  <x-field data-name="options" data-type="object" data-default="{}" data-required="false">
+    <x-field-desc markdown>Additional configuration options.</x-field-desc>
+    <x-field data-name="showQuickConnect" data-type="boolean" data-default="true" data-required="false" data-desc="If true, shows the quick connect option for saved sessions."></x-field>
+  </x-field>
+  <x-field data-name="onRecreateSession" data-type="Function" data-required="false" data-desc="Callback function executed when a session is recreated."></x-field>
+  <x-field data-name="checkFn" data-type="() => boolean" data-required="false" data-desc="A custom function to check the connection status."></x-field>
+  <x-field data-name="onSuccess" data-type="(result: object) => void" data-required="false" data-desc="Callback function executed upon a successful connection."></x-field>
+  <x-field data-name="onError" data-type="(error: any) => void" data-required="false" data-desc="Callback function executed when an error occurs."></x-field>
+  <x-field data-name="onClose" data-type="Function" data-required="false" data-desc="Callback function executed when the connection modal is closed."></x-field>
+</x-field-group>
+
+### ConnectMessages
+
+Object to customize the text displayed within the DID Connect UI.
+
+<x-field-group>
+  <x-field data-name="title" data-type="string" data-required="true" data-desc="The main title of the connect modal."></x-field>
+  <x-field data-name="scan" data-type="string" data-required="true" data-desc="The instruction text for scanning the QR code."></x-field>
+  <x-field data-name="success" data-type="ReactNode" data-required="true" data-desc="The message or component displayed upon successful connection."></x-field>
+  <x-field data-name="confirm" data-type="string" data-required="false" data-desc="The text prompting the user to confirm the action in their wallet."></x-field>
+  <x-field data-name="error" data-type="string" data-required="false" data-desc="A custom error message to display."></x-field>
+</x-field-group>
+
+### OpenDidConnect
+
+This function type defines the signature for opening the DID Connect flow with advanced requirements, often used for progressive authorization.
+
+<x-field-group>
+  <x-field data-name="params" data-type="ConnectProps" data-required="true" data-desc="The standard connection properties."></x-field>
+  <x-field data-name="options" data-type="object" data-required="false" data-desc="Additional options to control the connection mode and specify requirements.">
+    <x-field data-name="openMode" data-type="'redirect' | 'window' | 'popup'" data-default="popup" data-required="false" data-desc="Determines how the DID Connect window is opened."></x-field>
+    <x-field data-name="requirements" data-type="object" data-required="false" data-desc="Specifies the requirements for the session.">
+      <x-field data-name="login" data-type="boolean" data-default="true" data-required="false" data-desc="If true, requires the user to be logged in."></x-field>
+      <x-field data-name="bindWallet" data-type="boolean" data-default="true" data-required="false" data-desc="If true, requires the user to have a DID Wallet account bound."></x-field>
+      <x-field data-name="bindDidSpaces" data-type="false | 'read' | 'full'" data-default="false" data-required="false" data-desc="Specifies if DID Spaces binding is required, and what level of access is needed."></x-field>
+    </x-field>
+    <x-field data-name="baseUrl" data-type="string" data-required="false" data-desc="The base URL for API requests."></x-field>
+    <x-field data-name="locale" data-type="BaseLocale" data-required="false" data-desc="The language for the UI ('en' or 'zh')."></x-field>
+  </x-field>
+</x-field-group>
+
+## Session and User Types
+
+These types define the structure of the user and session data managed by `SessionProvider`.
+
+### SessionProps
+
+The main session object, accessible via the `useSession` hook. It contains the user's state, session information, and methods to manage the session.
+
+<x-field-group>
+  <x-field data-name="action" data-type="string" data-desc="The current action being performed (e.g., 'login')."></x-field>
+  <x-field data-name="error" data-type="string" data-desc="Any error message that occurred during the session management."></x-field>
+  <x-field data-name="initialized" data-type="boolean" data-desc="True if the session has been initialized."></x-field>
+  <x-field data-name="loading" data-type="boolean" data-desc="True if the session is currently in a loading state."></x-field>
+  <x-field data-name="open" data-type="boolean" data-desc="True if the DID Connect modal is currently open."></x-field>
+  <x-field data-name="walletOS" data-type="WalletOS" data-desc="The operating system of the connected wallet ('web', 'android', 'ios')."></x-field>
+  <x-field data-name="user" data-type="User" data-desc="The authenticated user object. Undefined if no user is logged in."></x-field>
+  <x-field data-name="locale" data-type="UserLocale" data-desc="The current locale for the user."></x-field>
+  <x-field data-name="provider" data-type="WalletProvider" data-desc="The provider used for the current session."></x-field>
+  <x-field data-name="baseUrl" data-type="string" data-desc="The base URL used for API calls."></x-field>
+  <x-field data-name="federatedMaster" data-type="object" data-desc="Information about the master site in a Federated Login group."></x-field>
+  <x-field data-name="login" data-type="LoginSessionFn" data-desc="Function to initiate the login process."></x-field>
+  <x-field data-name="logout" data-type="LogoutSessionFn" data-desc="Function to log the user out."></x-field>
+  <x-field data-name="switch" data-type="Function" data-desc="Function to switch between different user accounts."></x-field>
+  <x-field data-name="switchDid" data-type="CommonSessionFn" data-desc="Function to switch the user's active DID."></x-field>
+  <x-field data-name="autoSwitchDid" data-type="Function" data-desc="Function to automatically switch DIDs."></x-field>
+  <x-field data-name="switchProfile" data-type="CommonSessionFn" data-desc="Function to switch user profiles."></x-field>
+  <x-field data-name="switchPassport" data-type="CommonSessionFn" data-desc="Function to switch between different passports."></x-field>
+  <x-field data-name="bindWallet" data-type="CommonSessionFn" data-desc="Function to initiate the wallet binding process."></x-field>
+  <x-field data-name="refresh" data-type="Function" data-desc="Function to manually refresh the session data."></x-field>
+  <x-field data-name="updateConnectedInfo" data-type="(data: object) => void" data-desc="Function to update connection information."></x-field>
+  <x-field data-name="openDidConnect" data-type="OpenDidConnect" data-desc="Function to open the DID Connect modal with advanced requirements."></x-field>
+  <x-field data-name="useOAuth" data-type="Function" data-desc="Hook for OAuth integration."></x-field>
+  <x-field data-name="OAuthProvider" data-type="Function" data-desc="Provider component for OAuth context."></x-field>
+  <x-field data-name="OAuthConsumer" data-type="Function" data-desc="Consumer component for OAuth context."></x-field>
+  <x-field data-name="OAuthContext" data-type="object" data-desc="The React context object for OAuth."></x-field>
+  <x-field data-name="usePasskey" data-type="Function" data-desc="Hook for Passkey integration."></x-field>
+  <x-field data-name="PasskeyProvider" data-type="Function" data-desc="Provider component for Passkey context."></x-field>
+  <x-field data-name="PasskeyConsumer" data-type="Function" data-desc="Consumer component for Passkey context."></x-field>
+  <x-field data-name="PasskeyContext" data-type="object" data-desc="The React context object for Passkey."></x-field>
+  <x-field data-name="useDid" data-type="(options: { session: Session }) => void" data-desc="A utility hook to work with DID information."></x-field>
+  <x-field data-name="WrapDid" data-type="Function" data-desc="A wrapper component related to DID functionality."></x-field>
+  <x-field data-name="getUserSessions" data-type="() => Promise<UserSession[]>" data-desc="Function to fetch all active sessions for the current user."></x-field>
+</x-field-group>
+
+### User
+
+Represents the detailed profile of an authenticated user.
+
+<x-field-group>
+  <x-field data-name="did" data-type="string" data-required="true" data-desc="The user's Decentralized Identifier (DID)."></x-field>
+  <x-field data-name="pk" data-type="string" data-required="true" data-desc="The user's public key."></x-field>
+  <x-field data-name="avatar" data-type="string" data-required="true" data-desc="URL of the user's avatar."></x-field>
+  <x-field data-name="fullName" data-type="string" data-required="true" data-desc="The user's full name."></x-field>
+  <x-field data-name="email" data-type="string" data-required="true" data-desc="The user's email address."></x-field>
+  <x-field data-name="role" data-type="UserRole" data-required="true" data-desc="The role of the user within the application (e.g., 'guest', 'member', 'admin')."></x-field>
+  <x-field data-name="locale" data-type="UserLocale" data-required="true" data-desc="The user's preferred language."></x-field>
+  <x-field data-name="connectedAccounts" data-type="ConnectAccount[]" data-required="true" data-desc="A list of accounts connected to the user's DID."></x-field>
+  <x-field data-name="passports" data-type="Passport[]" data-required="true" data-desc="A list of passports associated with the user."></x-field>
+  <x-field data-name="permissions" data-type="any[]" data-required="true" data-desc="A list of permissions granted to the user."></x-field>
+  <x-field data-name="didSpace" data-type="object" data-required="false" data-desc="Information about the user's DID Space."></x-field>
+  <x-field data-name="approved" data-type="boolean" data-required="true" data-desc="Indicates if the user has been approved."></x-field>
+  <x-field data-name="remark" data-type="string" data-required="false" data-desc="An optional remark or note about the user."></x-field>
+  <x-field data-name="createdAt" data-type="string" data-required="true" data-desc="Timestamp of when the user account was created."></x-field>
+  <x-field data-name="updatedAt" data-type="string" data-required="true" data-desc="Timestamp of the last update to the user account."></x-field>
+  <x-field data-name="firstLoginAt" data-type="string" data-required="false" data-desc="Timestamp of the user's first login."></x-field>
+  <x-field data-name="lastLoginAt" data-type="string" data-required="false" data-desc="Timestamp of the user's last login."></x-field>
+  <x-field data-name="lastLoginIp" data-type="string" data-required="false" data-desc="IP address from the user's last login."></x-field>
+</x-field-group>
+
+### UserSession
+
+Represents a single active session for a user, typically retrieved from `getUserSessions`.
+
+<x-field-group>
+  <x-field data-name="id" data-type="string" data-required="true" data-desc="The unique identifier for the session."></x-field>
+  <x-field data-name="appName" data-type="string" data-required="true" data-desc="The name of the application for this session."></x-field>
+  <x-field data-name="appPid" data-type="string" data-required="true" data-desc="The application's Passport ID."></x-field>
+  <x-field data-name="updatedAt" data-type="string" data-required="true" data-desc="Timestamp of the last session update."></x-field>
+  <x-field data-name="userDid" data-type="string" data-required="true" data-desc="The DID of the user for this session."></x-field>
+  <x-field data-name="visitorId" data-type="string" data-required="true" data-desc="The visitor ID associated with the session."></x-field>
+  <x-field data-name="extra" data-type="object" data-required="true" data-desc="Any extra data associated with the session."></x-field>
+  <x-field data-name="user" data-type="SessionUser" data-required="true" data-desc="A simplified user object for the session."></x-field>
+  <x-field data-name="passportId" data-type="string" data-required="false" data-desc="The ID of the passport used for this session."></x-field>
+</x-field-group>
+
+### Core Data Types
+
+These are fundamental string union types used across various other interfaces.
+
+| Type | Description | Possible Values |
+| --- | --- | --- |
+| `WalletProvider` | Identifies the authentication method or provider. | `wallet`, `auth0`, `apple`, `github`, `google`, `passkey` |
+| `WalletOS` | Represents the operating system of the DID Wallet. | `web`, `android`, `ios`, `''` (empty string) |
+| `UserRole` | Defines the role of a user within the application. | `guest`, `member`, `admin`, `owner`, or any `string` |
+| `BaseLocale` | The base set of supported languages. | `en`, `zh` |
+| `UserLocale` | The user's locale, can be a base locale or a more specific one. | `en`, `zh`, or any `string` (e.g., 'en-US') |