@arcblock/did-connect-react 3.1.40 → 3.1.42

package/docs/advanced-utilities.md

@@ -0,0 +1,132 @@
+# Utilities
+
+The `@arcblock/did-connect-react` library exports a collection of utility functions designed to simplify common tasks related to authentication flows, data handling, and API communication. While the core components and hooks handle most use cases, these utilities offer granular control for advanced integrations or custom implementations.
+
+## API Client
+
+### createAxios
+
+This function is a factory for creating a pre-configured `axios` instance. It automatically includes essential headers like `x-did-connect-version` and `x-blocklet-visitor-id`, ensuring proper communication with Blocklet-based services. It's the recommended way to create API clients in your application.
+
+**Parameters**
+
+<x-field-group>
+  <x-field data-name="options" data-type="object" data-required="false" data-desc="Standard Axios configuration object."></x-field>
+  <x-field data-name="lazyOptions" data-type="object" data-required="false" data-desc="Configuration for lazy sending.">
+    <x-field data-name="lazy" data-type="boolean" data-default="false" data-desc="Whether to enable lazy sending."></x-field>
+    <x-field data-name="lazyTime" data-type="number" data-default="300" data-desc="The debounce time in milliseconds for lazy sending."></x-field>
+  </x-field>
+</x-field-group>
+
+**Returns**
+
+<x-field data-name="axiosInstance" data-type="AxiosInstance" data-desc="A configured instance of Axios."></x-field>
+
+**Example**
+
+```javascript apiClient.js icon=logos:javascript
+import { createAxios } from '@arcblock/did-connect-react/lib/utils';
+
+const apiClient = createAxios({
+  baseURL: '/api',
+});
+
+export default apiClient;
+```
+
+## URL and Popup Handling
+
+These functions help manage the URLs and popup windows used during the DID Connect authentication process.
+
+| Function | Description |
+| :--- | :--- |
+| `encodeConnectUrl(url)` | Encodes a URL to be safely passed as a `__connect_url__` query parameter. |
+| `decodeConnectUrl(encoded)` | Decodes a URL that was encoded with `encodeConnectUrl`. |
+| `parseTokenFromConnectUrl(connectUrl)` | Extracts the session token (`_t_`) from a DID Connect URL. |
+| `openPopup(url, options)` | Opens a new, centered popup window. It's used internally by the `DidConnect` component to display the wallet connection interface. Throws a `NotOpenError` if the popup is blocked. |
+| `runPopup(config)` | A promise-based wrapper that manages the lifecycle of a popup created with `openPopup`. It listens for `message` events from the popup, handles timeouts, and resolves when the authentication flow is complete. |
+| `decodeUrlParams()` | Parses custom `__did-connect__` parameters from the current window's URL. |
+
+**Example: Custom Popup Flow**
+
+```javascript customAuthButton.js icon=logos:javascript
+import { openPopup, runPopup } from '@arcblock/did-connect-react/lib/utils';
+
+const handleCustomLogin = async () => {
+  const authUrl = 'https://your-auth-service.com/connect';
+  try {
+    const popup = openPopup(authUrl);
+    const result = await runPopup({ popup, timeoutInSeconds: 600 });
+    console.log('Authentication successful:', result);
+    // Handle successful login
+  } catch (error) {
+    console.error('Authentication failed:', error.message);
+    // Handle popup closed or timeout
+  }
+};
+```
+
+## Session and Cookie Management
+
+These helpers are used to read and write user connection information to cookies, enabling session persistence across page loads.
+
+| Function | Description |
+| :--- | :--- |
+| `getConnectedInfo(data)` | Formats the raw response data from a connection request into a standardized object suitable for cookie storage. |
+| `updateConnectedInfo(info, parsed)` | Sets the necessary cookies (`connected_did`, `connected_pk`, `connected_app`) after a successful connection. This allows the library to optimize subsequent authentication checks. |
+| `getVisitorId()` | Retrieves the unique visitor ID from cookies. |
+| `setVisitorId(id)` | Sets the unique visitor ID in cookies. |
+
+**Example**
+
+```javascript sessionManager.js icon=logos:javascript
+import { getConnectedInfo, updateConnectedInfo } from '@arcblock/did-connect-react/lib/utils';
+
+// Assuming 'authResponse' is the object returned from your login API
+function persistSession(authResponse) {
+  const connectedInfo = getConnectedInfo(authResponse);
+  updateConnectedInfo(connectedInfo, true);
+  console.log('Session info saved to cookies.');
+}
+```
+
+## Encryption Utilities
+
+For advanced scenarios requiring client-side encryption or decryption, the library exposes helpers that wrap the `tweetnacl-sealedbox-js` library.
+
+| Function | Description |
+| :--- | :--- |
+| `encodeKey(key)` | Base64URL encodes a key for transmission. |
+| `decodeKey(str)` | Decodes a Base64URL string into a `Uint8Array` key. |
+| `encrypt(value, encryptKey)` | Encrypts a string value using a public key. |
+| `decrypt(value, encryptKey, decryptKey)` | Decrypts a base64 string using the corresponding public and private keys. |
+
+## Error Handling
+
+To provide better feedback to users, you can use these functions to parse technical error objects into human-readable messages.
+
+| Function | Description |
+| :--- | :--- |
+| `getApiErrorMessage(err, defaultMessage)` | Extracts a user-friendly error message from an `axios` error object. |
+| `getWebAuthnErrorMessage(err, defaultMessage, t)` | Handles WebAuthn/Passkey specific errors (e.g., user cancellation, browser not supported) and returns localized, user-friendly messages. |
+
+**Example**
+
+```javascript errorHandling.js icon=logos:javascript
+import { getApiErrorMessage } from '@arcblock/did-connect-react/lib/utils';
+import apiClient from './apiClient';
+
+async function fetchData() {
+  try {
+    const response = await apiClient.get('/data');
+    return response.data;
+  } catch (error) {
+    const message = getApiErrorMessage(error, 'Failed to fetch data.');
+    alert(message);
+  }
+}
+```
+
+---
+
+By leveraging these utilities, you can build more complex and customized authentication experiences. For a complete list of all exported members and their types, please refer to the [API Reference](./api-reference.md).

package/docs/advanced-utilities.zh-TW.md

@@ -0,0 +1,132 @@
+# 工具程式
+
+`@arcblock/did-connect-react` 函式庫匯出了一系列工具函式，旨在簡化與身份驗證流程、資料處理和 API 通訊相關的常見任務。雖然核心元件和掛鉤（hooks）處理了大多數使用情境，但這些工具程式為進階整合或自訂實作提供了精細的控制。
+
+## API 客戶端
+
+### createAxios
+
+此函式是一個用於建立預先設定的 `axios` 實例的工廠。它會自動包含必要的標頭，如 `x-did-connect-version` 和 `x-blocklet-visitor-id`，以確保與基於 Blocklet 的服務正常通訊。這是您應用程式中建立 API 客戶端的建議方法。
+
+**參數**
+
+<x-field-group>
+  <x-field data-name="options" data-type="object" data-required="false" data-desc="標準的 Axios 設定物件。"></x-field>
+  <x-field data-name="lazyOptions" data-type="object" data-required="false" data-desc="延遲發送的設定。">
+    <x-field data-name="lazy" data-type="boolean" data-default="false" data-desc="是否啟用延遲發送。"></x-field>
+    <x-field data-name="lazyTime" data-type="number" data-default="300" data-desc="延遲發送的去抖動時間（毫秒）。"></x-field>
+  </x-field>
+</x-field-group>
+
+**回傳值**
+
+<x-field data-name="axiosInstance" data-type="AxiosInstance" data-desc="一個已設定的 Axios 實例。"></x-field>
+
+**範例**
+
+```javascript apiClient.js icon=logos:javascript
+import { createAxios } from '@arcblock/did-connect-react/lib/utils';
+
+const apiClient = createAxios({
+  baseURL: '/api',
+});
+
+export default apiClient;
+```
+
+## URL 和彈出視窗處理
+
+這些函式有助於管理在 DID Connect 身份驗證過程中使用的 URL 和彈出視窗。
+
+| 函式 | 說明 |
+| :--- | :--- |
+| `encodeConnectUrl(url)` | 將 URL 編碼，以便安全地作為 `__connect_url__` 查詢參數傳遞。 |
+| `decodeConnectUrl(encoded)` | 解碼由 `encodeConnectUrl` 編碼的 URL。 |
+| `parseTokenFromConnectUrl(connectUrl)` | 從 DID Connect URL 中提取會話權杖 (`_t_`)。 |
+| `openPopup(url, options)` | 開啟一個新的、置中的彈出視窗。`DidConnect` 元件內部使用它來顯示錢包連接介面。如果彈出視窗被阻擋，則會拋出 `NotOpenError`。 |
+| `runPopup(config)` | 一個基於 promise 的包裝器，用於管理由 `openPopup` 建立的彈出視窗的生命週期。它監聽來自彈出視窗的 `message` 事件，處理超時，並在身份驗證流程完成時解析。 |
+| `decodeUrlParams()` | 從當前視窗的 URL 中解析自訂的 `__did-connect__` 參數。 |
+
+**範例：自訂彈出視窗流程**
+
+```javascript customAuthButton.js icon=logos:javascript
+import { openPopup, runPopup } from '@arcblock/did-connect-react/lib/utils';
+
+const handleCustomLogin = async () => {
+  const authUrl = 'https://your-auth-service.com/connect';
+  try {
+    const popup = openPopup(authUrl);
+    const result = await runPopup({ popup, timeoutInSeconds: 600 });
+    console.log('Authentication successful:', result);
+    // Handle successful login
+  } catch (error) {
+    console.error('Authentication failed:', error.message);
+    // Handle popup closed or timeout
+  }
+};
+```
+
+## 會話和 Cookie 管理
+
+這些輔助函式用於將使用者連接資訊讀寫到 Cookie，從而實現跨頁面載入的會話持久性。
+
+| 函式 | 說明 |
+| :--- | :--- |
+| `getConnectedInfo(data)` | 將來自連接請求的原始回應資料格式化為適合 Cookie 儲存的標準化物件。 |
+| `updateConnectedInfo(info, parsed)` | 在成功連接後設定必要的 Cookie (`connected_did`, `connected_pk`, `connected_app`)。這讓函式庫可以優化後續的身份驗證檢查。 |
+| `getVisitorId()` | 從 Cookie 中檢索唯一訪客 ID。 |
+| `setVisitorId(id)` | 在 Cookie 中設定唯一訪客 ID。 |
+
+**範例**
+
+```javascript sessionManager.js icon=logos:javascript
+import { getConnectedInfo, updateConnectedInfo } from '@arcblock/did-connect-react/lib/utils';
+
+// Assuming 'authResponse' is the object returned from your login API
+function persistSession(authResponse) {
+  const connectedInfo = getConnectedInfo(authResponse);
+  updateConnectedInfo(connectedInfo, true);
+  console.log('Session info saved to cookies.');
+}
+```
+
+## 加密工具
+
+對於需要客戶端加密或解密的進階情境，該函式庫公開了包裝 `tweetnacl-sealedbox-js` 函式庫的輔助函式。
+
+| 函式 | 說明 |
+| :--- | :--- |
+| `encodeKey(key)` | 將金鑰進行 Base64URL 編碼以便傳輸。 |
+| `decodeKey(str)` | 將 Base64URL 字串解碼為 `Uint8Array` 金鑰。 |
+| `encrypt(value, encryptKey)` | 使用公鑰加密字串值。 |
+| `decrypt(value, encryptKey, decryptKey)` | 使用對應的公鑰和私鑰解密 base64 字串。 |
+
+## 錯誤處理
+
+為了向使用者提供更好的回饋，您可以使用這些函式將技術性錯誤物件解析為人類可讀的訊息。
+
+| 函式 | 說明 |
+| :--- | :--- |
+| `getApiErrorMessage(err, defaultMessage)` | 從 `axios` 錯誤物件中提取使用者友善的錯誤訊息。 |
+| `getWebAuthnErrorMessage(err, defaultMessage, t)` | 處理 WebAuthn/Passkey 特定錯誤（例如，使用者取消、瀏覽器不支援），並回傳本地化的、使用者友善的訊息。 |
+
+**範例**
+
+```javascript errorHandling.js icon=logos:javascript
+import { getApiErrorMessage } from '@arcblock/did-connect-react/lib/utils';
+import apiClient from './apiClient';
+
+async function fetchData() {
+  try {
+    const response = await apiClient.get('/data');
+    return response.data;
+  } catch (error) {
+    const message = getApiErrorMessage(error, 'Failed to fetch data.');
+    alert(message);
+  }
+}
+```
+
+---
+
+透過利用這些工具程式，您可以建立更複雜和自訂的身份驗證體驗。有關所有匯出成員及其類型的完整列表，請參閱 [API 參考](./api-reference.md)。

package/docs/advanced-utilities.zh.md

@@ -0,0 +1,132 @@
+# 工具函数
+
+`@arcblock/did-connect-react` 库导出了一系列工具函数，旨在简化与身份验证流程、数据处理和 API 通信相关的常见任务。虽然核心组件和钩子处理了大多数用例，但这些工具为高级集成或自定义实现提供了精细的控制。
+
+## API 客户端
+
+### createAxios
+
+该函数是一个用于创建预配置 `axios` 实例的工厂。它会自动包含必要的头信息，如 `x-did-connect-version` 和 `x-blocklet-visitor-id`，以确保与基于 Blocklet 的服务正常通信。这是在你的应用程序中创建 API 客户端的推荐方法。
+
+**参数**
+
+<x-field-group>
+  <x-field data-name="options" data-type="object" data-required="false" data-desc="标准的 Axios 配置对象。"></x-field>
+  <x-field data-name="lazyOptions" data-type="object" data-required="false" data-desc="懒发送的配置。">
+    <x-field data-name="lazy" data-type="boolean" data-default="false" data-desc="是否启用懒发送。"></x-field>
+    <x-field data-name="lazyTime" data-type="number" data-default="300" data-desc="懒发送的防抖时间（毫秒）。"></x-field>
+  </x-field>
+</x-field-group>
+
+**返回值**
+
+<x-field data-name="axiosInstance" data-type="AxiosInstance" data-desc="一个已配置的 Axios 实例。"></x-field>
+
+**示例**
+
+```javascript apiClient.js icon=logos:javascript
+import { createAxios } from '@arcblock/did-connect-react/lib/utils';
+
+const apiClient = createAxios({
+  baseURL: '/api',
+});
+
+export default apiClient;
+```
+
+## URL 和弹窗处理
+
+这些函数帮助管理在 DID Connect 身份验证过程中使用的 URL 和弹窗。
+
+| 函数 | 描述 |
+| :--- | :--- |
+| `encodeConnectUrl(url)` | 对 URL 进行编码，以便安全地作为 `__connect_url__` 查询参数传递。 |
+| `decodeConnectUrl(encoded)` | 解码由 `encodeConnectUrl` 编码的 URL。 |
+| `parseTokenFromConnectUrl(connectUrl)` | 从 DID Connect URL 中提取会话令牌 (`_t_`)。 |
+| `openPopup(url, options)` | 打开一个新的、居中的弹窗。它由 `DidConnect` 组件内部使用，以显示钱包连接界面。如果弹窗被阻止，则会抛出 `NotOpenError`。 |
+| `runPopup(config)` | 一个基于 Promise 的包装器，用于管理由 `openPopup` 创建的弹窗的生命周期。它监听来自弹窗的 `message` 事件，处理超时，并在身份验证流程完成时解析。 |
+| `decodeUrlParams()` | 从当前窗口的 URL 中解析自定义的 `__did-connect__` 参数。 |
+
+**示例：自定义弹窗流程**
+
+```javascript customAuthButton.js icon=logos:javascript
+import { openPopup, runPopup } from '@arcblock/did-connect-react/lib/utils';
+
+const handleCustomLogin = async () => {
+  const authUrl = 'https://your-auth-service.com/connect';
+  try {
+    const popup = openPopup(authUrl);
+    const result = await runPopup({ popup, timeoutInSeconds: 600 });
+    console.log('Authentication successful:', result);
+    // Handle successful login
+  } catch (error) {
+    console.error('Authentication failed:', error.message);
+    // Handle popup closed or timeout
+  }
+};
+```
+
+## 会话和 Cookie 管理
+
+这些辅助函数用于向 Cookie 读写用户连接信息，从而实现跨页面加载的会话持久性。
+
+| 函数 | 描述 |
+| :--- | :--- |
+| `getConnectedInfo(data)` | 将连接请求的原始响应数据格式化为适合 Cookie 存储的标准化对象。 |
+| `updateConnectedInfo(info, parsed)` | 在成功连接后设置必要的 Cookie (`connected_did`, `connected_pk`, `connected_app`)。这使得库可以优化后续的身份验证检查。 |
+| `getVisitorId()` | 从 Cookie 中检索唯一访客 ID。 |
+| `setVisitorId(id)` | 在 Cookie 中设置唯一访客 ID。 |
+
+**示例**
+
+```javascript sessionManager.js icon=logos:javascript
+import { getConnectedInfo, updateConnectedInfo } from '@arcblock/did-connect-react/lib/utils';
+
+// Assuming 'authResponse' is the object returned from your login API
+function persistSession(authResponse) {
+  const connectedInfo = getConnectedInfo(authResponse);
+  updateConnectedInfo(connectedInfo, true);
+  console.log('Session info saved to cookies.');
+}
+```
+
+## 加密工具
+
+对于需要客户端加密或解密的高级场景，该库公开了包装 `tweetnacl-sealedbox-js` 库的辅助函数。
+
+| 函数 | 描述 |
+| :--- | :--- |
+| `encodeKey(key)` | 对密钥进行 Base64URL 编码以便传输。 |
+| `decodeKey(str)` | 将 Base64URL 字符串解码为 `Uint8Array` 密钥。 |
+| `encrypt(value, encryptKey)` | 使用公钥加密字符串值。 |
+| `decrypt(value, encryptKey, decryptKey)` | 使用相应的公钥和私钥解密 base64 字符串。 |
+
+## 错误处理
+
+为了向用户提供更好的反馈，你可以使用这些函数将技术性错误对象解析为人类可读的消息。
+
+| 函数 | 描述 |
+| :--- | :--- |
+| `getApiErrorMessage(err, defaultMessage)` | 从 `axios` 错误对象中提取用户友好的错误消息。 |
+| `getWebAuthnErrorMessage(err, defaultMessage, t)` | 处理 WebAuthn/Passkey 特定错误（例如，用户取消、浏览器不支持），并返回本地化的、用户友好的消息。 |
+
+**示例**
+
+```javascript errorHandling.js icon=logos:javascript
+import { getApiErrorMessage } from '@arcblock/did-connect-react/lib/utils';
+import apiClient from './apiClient';
+
+async function fetchData() {
+  try {
+    const response = await apiClient.get('/data');
+    return response.data;
+  } catch (error) {
+    const message = getApiErrorMessage(error, 'Failed to fetch data.');
+    alert(message);
+  }
+}
+```
+
+---
+
+通过利用这些工具，你可以构建更复杂和定制化的身份验证体验。有关所有导出成员及其类型的完整列表，请参阅 [API 参考](./api-reference.md)。

package/docs/advanced.ja.md

@@ -0,0 +1,95 @@
+# 高度なトピック
+
+`SessionProvider`や`DidConnect`のようなコアコンポーネントに慣れたら、`@arcblock/did-connect-react`ライブラリのより強力で柔軟な機能を探索する準備が整います。このセクションでは、より洗練され、堅牢で、ユーザーフレンドリーな分散型アイデンティティアプリケーションを構築するための高度なトピックを扱います。
+
+3つの主要な分野を探求します：
+
+1.  **代替認証方法**：デフォルトのQRコードスキャンを超えて、OAuth（ソーシャルログイン）、パスキー（パスワードレス）、およびフェデレーションログインなどの一般的なログイン方法を統合します。
+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（ソーシャルログイン）、パスキー（パスワードレス）、およびフェデレーションログインを実装するための詳細なガイドに飛び込みます。
+</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（パスキーで使用）とのやり取りのために、このライブラリは複雑なエラーオブジェクトをユーザーフレンドリーなメッセージに解析するためのヘルパー関数を提供します。
+
+- `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}>パスキーでログイン</button>;
+}
+```
+
+適切なエラーハンドリングを実装することで、計画通りに進まなかった場合のユーザーエクスペリエンスを大幅に向上させることができます。
+
+---
+
+## 次のステップ
+
+高度な機能の概要を理解したところで、あなたのプロジェクトに最も関連のあるトピックをさらに深く掘り下げることができます。
+
+- **[認証方法](./advanced-authentication-methods.md)**：ユーザーがログインするための新しい方法を実装します。
+- **[ユーティリティ](./advanced-utilities.md)**：ヘルパー関数でコードを効率化します。
+- **[APIリファレンス](./api-reference.md)**：すべてのコンポーネント、フック、関数の完全で詳細な情報を取得します。

package/docs/advanced.md

@@ -0,0 +1,95 @@
+# Advanced Topics
+
+Once you are comfortable with the core components like `SessionProvider` and `DidConnect`, you're ready to explore the more powerful and flexible features of the `@arcblock/did-connect-react` library. This section covers advanced subjects that allow you to build more sophisticated, robust, and user-friendly decentralized identity applications.
+
+We will explore three main areas:
+
+1.  **Alternative Authentication Methods**: Go beyond the default QR code scan and integrate popular login methods like OAuth (social login), Passkeys (passwordless), and Federated Login.
+2.  **Utility Functions**: Leverage a suite of helper functions to handle common tasks such as URL encoding, creating API clients, and managing popups.
+3.  **Error Handling**: Learn how to gracefully handle common errors, from blocked popups to WebAuthn API failures, ensuring a smooth user experience.
+
+---
+
+## Authentication Methods
+
+While DID Connect is the primary authentication method, the library provides seamless integration with other popular login flows. This allows you to offer users multiple ways to sign in, catering to different preferences and security levels.
+
+<x-card data-title="Explore Authentication Methods" data-icon="lucide:key-round" data-href="/advanced/authentication-methods" data-cta="Learn More">
+Dive into detailed guides for implementing OAuth (social login), Passkeys (passwordless), and Federated Login within your application.
+</x-card>
+
+## Utilities
+
+The library exports a collection of utility functions designed to simplify common tasks and reduce boilerplate code in your application. These helpers cover everything from data encoding and cryptographic operations to managing browser popups for authentication flows.
+
+<x-card data-title="Browse Utility Functions" data-icon="lucide:wrench" data-href="/advanced/utilities" data-cta="View Reference">
+Discover a comprehensive reference for all helper functions, including examples for URL manipulation, API client creation, data encryption, and more.
+</x-card>
+
+## Error Handling
+
+Building a robust application requires graceful error handling. The `@arcblock/did-connect-react` library provides specific error types and helper functions to make this process easier.
+
+### Popup Errors
+
+When using authentication methods that require a popup window (like OAuth), the browser's popup blocker might interfere. The `openPopup` function will throw a `NotOpenError` if it fails to open the window. You should catch this error and provide appropriate feedback to the user.
+
+```javascript Handling Popup Errors 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 successful:', result);
+  } catch (err) {
+    if (err instanceof NotOpenError) {
+      alert('Popup was blocked. Please allow popups for this site and try again.');
+    } else {
+      alert(`An error occurred: ${err.message}`);
+    }
+  }
+}
+```
+
+### API and WebAuthn Errors
+
+For interactions with backend services or WebAuthn APIs (used by Passkeys), the library provides helper functions to parse complex error objects into user-friendly messages.
+
+- `getApiErrorMessage(err, defaultMessage)`: Extracts an error message from an Axios error response.
+- `getWebAuthnErrorMessage(err, defaultMessage, t)`: Handles WebAuthn-specific errors (e.g., user cancellation, unsupported browser) and provides translatable, user-friendly messages.
+
+```javascript Handling WebAuthn Errors 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();
+      // Handle successful login
+    } catch (err) {
+      // Use the utility to get a user-friendly message
+      const friendlyMessage = getWebAuthnErrorMessage(err, 'An unknown error occurred.');
+      alert(friendlyMessage);
+    }
+  };
+
+  return <button onClick={handleLogin}>Login with Passkey</button>;
+}
+```
+
+By implementing proper error handling, you can significantly improve the user experience when things don't go as planned.
+
+---
+
+## Next Steps
+
+Now that you have an overview of the advanced capabilities, you can dive deeper into the topics that are most relevant to your project.
+
+- **[Authentication Methods](./advanced-authentication-methods.md)**: Implement new ways for your users to log in.
+- **[Utilities](./advanced-utilities.md)**: Streamline your code with our helper functions.
+- **[API Reference](./api-reference.md)**: Get a complete, detailed look at all components, hooks, and functions.