@arcblock/did-connect-react 3.1.40 → 3.1.42

package/docs/advanced-authentication-methods.zh-TW.md

@@ -0,0 +1,261 @@
+# 驗證方法
+
+雖然 DID 錢包是主要且最安全的驗證方法，但 `@arcblock/did-connect-react` 仍為多種替代登入方法提供了強大的支援，以提供靈活性並滿足不同使用者的偏好。本節詳細介紹如何將 OAuth (社群登入)、Passkeys (無密碼驗證) 和统一登录站点群登入整合到您的應用程式中。
+
+這些方法透過特定的 React Context Providers 啟用，並透過相應的 hooks 存取，這些 hooks 應巢狀嵌套在主 `SessionProvider` 中。
+
+---
+
+## OAuth (社群登入)
+
+整合 Google、GitHub 或 Apple 等熱門社群登入供應商，讓使用者能用現有帳號登入。此功能由 `OAuthProvider` 和 `useOAuth` hook 管理。
+
+### 1. 使用 `OAuthProvider` 設定
+
+若要啟用 OAuth 功能，請用 `OAuthProvider` 包裹您的元件樹。通常會將其放置在 `SessionProvider` 內部。
+
+```jsx OAuthProvider Setup icon=logos:react
+import { SessionProvider } from '@arcblock/did-connect-react';
+import { OAuthProvider } from '@arcblock/did-connect-react/lib/OAuth';
+
+function App() {
+  return (
+    <SessionProvider>
+      <OAuthProvider
+        onBindOAuth={(provider) => console.log(`${provider.provider} 已綁定！`)}
+        onUnbindOAuth={(account) => console.log(`${account.provider} 已解除綁定！`)}>
+        {/* 您的應用程式元件 */}
+      </OAuthProvider>
+    </SessionProvider>
+  );
+}
+```
+
+**`OAuthProvider` 的 Props**
+
+<x-field-group>
+  <x-field data-name="children" data-type="ReactNode" data-required="true" data-desc="將有權存取 OAuth context 的子元件。"></x-field>
+  <x-field data-name="locale" data-type="string" data-default="en" data-desc="用於 UI 訊息和提示的語言。"></x-field>
+  <x-field data-name="onBindOAuth" data-type="function" data-desc="使用者成功綁定 OAuth 帳號後觸發的回呼函式。"></x-field>
+  <x-field data-name="onUnbindOAuth" data-type="function" data-desc="使用者成功解除綁定 OAuth 帳號後觸發的回呼函式。"></x-field>
+  <x-field data-name="onSwitchPassport" data-type="function" data-desc="使用者切換 passport 後觸發的回呼函式。"></x-field>
+  <x-field data-name="session" data-type="object" data-desc="目前的使用者 session 物件，passport 切換 UI 需要。"></x-field>
+</x-field-group>
+
+### 2. 使用 `useOAuth` Hook
+
+`useOAuth` hook 提供了與 OAuth 驗證流程互動的函式。
+
+```jsx useOAuth Hook icon=logos:react
+import { useOAuth } from '@arcblock/did-connect-react/lib/OAuth';
+
+function SocialLoginButtons() {
+  const { loginOAuth, getOAuthConfigList, bindAuthLoading } = useOAuth();
+  const [providers, setProviders] = React.useState([]);
+
+  React.useEffect(() => {
+    getOAuthConfigList().then(setProviders);
+  }, [getOAuthConfigList]);
+
+  const handleLogin = async (provider) => {
+    try {
+      const result = await loginOAuth({ provider: provider.provider });
+      console.log('登入成功：', result);
+      // 處理登入結果，例如更新 session
+    } catch (error) {
+      console.error('登入失敗：', error.message);
+    }
+  };
+
+  if (providers.length === 0) {
+    return <p>未設定第三方登入方式。</p>;
+  }
+
+  return (
+    <div>
+      {providers.map((p) => (
+        <button key={p.provider} onClick={() => handleLogin(p)} disabled={bindAuthLoading}>
+          使用 {p.provider} 登入
+        </button>
+      ))}
+    </div>
+  );
+}
+```
+
+### 核心函式
+
+- **`loginOAuth({ provider }, { action, ... })`**: 為特定供應商啟動登入流程。將會開啟一個彈出視窗供使用者驗證。
+- **`bindOAuth({ session, oauthItem })`**: 將一個新的社群帳號綁定到目前登入的使用者。
+- **`unbindOAuth({ session, connectedAccount })`**: 從目前使用者解除綁定一個社群帳號。
+- **`getOAuthConfigList()`**: 非同步地取得在 Blocklet 設定中設定的已啟用 OAuth 供應商列表。
+- **`switchOAuthPassport(user)`**: 開啟一個對話方塊，用於在與同一 OAuth 身分相關聯的不同使用者帳號 (passports) 之間切換。
+
+---
+
+## Passkeys (無密碼)
+
+使用基於 WebAuthn 標準的 Passkeys，啟用現代、安全且無密碼的驗證。這讓使用者可以使用生物辨識 (指紋、臉部 ID)、裝置 PIN 碼或安全金鑰登入。
+
+### 1. 使用 `PasskeyProvider` 設定
+
+使用 `PasskeyProvider` 包裹您的應用程式以啟用 Passkey 功能。
+
+```jsx PasskeyProvider Setup icon=logos:react
+import { SessionProvider } from '@arcblock/did-connect-react';
+import { PasskeyProvider } from '@arcblock/did-connect-react/lib/Passkey';
+
+function App() {
+  return (
+    <SessionProvider>
+      <PasskeyProvider
+        onAddPasskey={(result) => console.log('Passkey 已新增！', result)}
+        onRemovePasskey={(result) => console.log('Passkey 已移除！', result)}>
+        {/* 您的應用程式元件 */}
+      </PasskeyProvider>
+    </SessionProvider>
+  );
+}
+```
+
+**`PasskeyProvider` 的 Props**
+
+<x-field-group>
+  <x-field data-name="children" data-type="ReactNode" data-required="true" data-desc="將有權存取 Passkey context 的子元件。"></x-field>
+  <x-field data-name="locale" data-type="string" data-default="en" data-desc="用於 UI 訊息和提示的語言。"></x-field>
+  <x-field data-name="onAddPasskey" data-type="function" data-desc="使用者成功新增 Passkey 後觸發的回呼函式。"></x-field>
+  <x-field data-name="onRemovePasskey" data-type="function" data-desc="使用者成功移除 Passkey 後觸發的回呼函式。"></x-field>
+  <x-field data-name="onSwitchPassport" data-type="function" data-desc="使用者切換 passport 後觸發的回呼函式。"></x-field>
+  <x-field data-name="session" data-type="object" data-desc="目前的使用者 session 物件，passport 切換 UI 需要。"></x-field>
+</x-field-group>
+
+### 2. 使用 `usePasskey` Hook
+
+`usePasskey` hook 提供了 Passkey 註冊和驗證所需的所有函式。
+
+```jsx usePasskey Hook icon=logos:react
+import { usePasskey } from '@arcblock/did-connect-react/lib/Passkey';
+import { useSession } from '@arcblock/did-connect-react';
+
+function PasskeyAuth() {
+  const { loginPasskey, connectPasskey, connecting } = usePasskey();
+  const { session } = useSession();
+
+  const handleLogin = async () => {
+    try {
+      const result = await loginPasskey();
+      console.log('Passkey 登入成功：', result);
+      // 處理登入結果
+    } catch (error) {
+      console.error('Passkey 登入失敗：', error.message);
+    }
+  };
+
+  const handleConnect = async () => {
+    // 這應該在使用者已經登入時呼叫
+    // 並且想要在他們的個人資料設定中新增一個 passkey。
+    if (!session.user) {
+      alert('您必須登入才能新增 passkey。');
+      return;
+    }
+    try {
+      await connectPasskey();
+    } catch (error) {
+      console.error('連接 passkey 失敗：', error.message);
+    }
+  };
+
+  return (
+    <div>
+      <button onClick={handleLogin}>使用 Passkey 登入</button>
+      {session.user && (
+        <button onClick={handleConnect} disabled={connecting}>
+          {connecting ? '連接中...' : '新增 Passkey'}
+        </button>
+      )}
+    </div>
+  );
+}
+```
+
+### 核心函式
+- **`loginPasskey({ action, ... })`**: 啟動 Passkey 驗證流程 (也稱為 assertion)。這用於登入現有使用者。
+- **`connectPasskey(extraParams)`**: 一個高階函式，用於建立一個新的 Passkey 並將其綁定到目前使用者的帳號。它處理完整的註冊儀式。
+- **`disconnectPasskey({ session, connectedAccount })`**: 在成功驗證後，從目前使用者的帳號中移除一個 Passkey。
+- **`createPasskey(params)`**: 啟動 WebAuthn 註冊過程的較低階函式。`connectPasskey` 在內部使用此函式。
+- **`verifyPasskey(params)`**: 啟動 WebAuthn 驗證過程的較低階函式。`loginPasskey` 和 `disconnectPasskey` 在內部使用此函式。
+- **`switchPassport(user)`**: 開啟一個對話方塊，用於在可能共享 Passkeys 的不同使用者帳號 (passports) 之間切換。
+
+---
+
+## 统一登录站点群登入
+
+统一登录站点群登入允許一組關聯的 Blocklet 應用程式 (一個「统一登录站点群」) 共享單一登入 session。當使用者登入指定的「主」站點時，他們可以在任何「成員」站點上自動進行驗證，無需再次登入。
+
+### 1. 概念與設定
+
+此功能依賴於您 Blocklet 設定中的主從站點設定。需要 `FederatedProvider` 元件來處理此功能在現代瀏覽器中運作所需的跨網域通訊，特別是用於管理第三方 cookie 的存取。
+
+與其他 provider 一樣，`FederatedProvider` 應包含在您的元件樹中，通常位於 `SessionProvider` 內部。
+
+```jsx FederatedProvider Setup icon=logos:react
+import { SessionProvider } from '@arcblock/did-connect-react';
+import { FederatedProvider } from '@arcblock/did-connect-react/lib/Federated';
+
+function App() {
+  return (
+    <SessionProvider>
+      <FederatedProvider>
+        {/* 您的應用程式元件 */}
+      </FederatedProvider>
+    </SessionProvider>
+  );
+}
+```
+
+### 2. 使用方法
+
+统一登录站点群登入邏輯直接整合到 session 管理中。您可以使用 `useSession` 回傳的 `session` 物件上的 `loginFederated` 函式來觸發它。
+
+`loginFederated` 支援兩種模式：
+- **`auto`**: 如果使用者在主站點上有活動的 session，則嘗試靜默登入使用者。這非常適合在頁面載入時進行檢查。
+- **`manual`**: 啟動標準的 DID Connect 登入流程。成功登入後，它也會與主站點建立统一登录站点群 session。
+
+```jsx Federated Login Example icon=logos:react
+import { useSession } from '@arcblock/did-connect-react';
+import React from 'react';
+
+function FederatedLogin() {
+  const { session } = useSession();
+  const { federatedEnabled, loginFederated } = session;
+
+  // 在元件掛載時嘗試自動登入
+  React.useEffect(() => {
+    if (federatedEnabled) {
+      loginFederated((err) => {
+        if (err) {
+          console.warn('自動统一登录站点群登入失敗：', err);
+        } else {
+          console.log('自動统一登录站点群登入成功！');
+        }
+      }, { mode: 'auto' });
+    }
+  }, [federatedEnabled, loginFederated]);
+
+  const handleManualLogin = () => {
+    loginFederated((err) => {
+      if (err) console.error('手動统一登录站点群登入失敗：', err);
+    }, { mode: 'manual' });
+  };
+
+  if (!federatedEnabled) {
+    return <p>未啟用统一登录站点群登入。</p>;
+  }
+
+  return (
+    <button onClick={handleManualLogin}>
+      使用主站點帳號登入
+    </button>
+  );
+}
+```

package/docs/advanced-authentication-methods.zh.md

@@ -0,0 +1,261 @@
+# 身份验证方法
+
+`DID Wallet` 是主要且最安全的身份验证方法，但 `@arcblock/did-connect-react` 也为多种替代登录方法提供了强大的支持，以提供灵活性并满足不同用户的偏好。本节详细介绍如何将 OAuth（社交登录）、Passkeys（无密码身份验证）和统一登录集成到您的应用程序中。
+
+这些方法通过特定的 React Context Provider 启用，并通过相应的 Hook 进行访问，它们应嵌套在主 `SessionProvider` 内部。
+
+---
+
+## OAuth（社交登录）
+
+集成 Google、GitHub 或 Apple 等流行的社交登录提供商，允许用户使用其现有帐户登录。此功能由 `OAuthProvider` 和 `useOAuth` Hook 管理。
+
+### 1. 使用 OAuthProvider 进行设置
+
+要启用 OAuth 功能，请使用 `OAuthProvider` 包裹您的组件树。通常将其放置在 `SessionProvider` 内部。
+
+```jsx OAuthProvider Setup icon=logos:react
+import { SessionProvider } from '@arcblock/did-connect-react';
+import { OAuthProvider } from '@arcblock/did-connect-react/lib/OAuth';
+
+function App() {
+  return (
+    <SessionProvider>
+      <OAuthProvider
+        onBindOAuth={(provider) => console.log(`${provider.provider} bound!`)}
+        onUnbindOAuth={(account) => console.log(`${account.provider} unbound!`)}>
+        {/* Your application components */}
+      </OAuthProvider>
+    </SessionProvider>
+  );
+}
+```
+
+**OAuthProvider 的 Props**
+
+<x-field-group>
+  <x-field data-name="children" data-type="ReactNode" data-required="true" data-desc="将有权访问 OAuth 上下文的子组件。"></x-field>
+  <x-field data-name="locale" data-type="string" data-default="en" data-desc="用于 UI 消息和提示的语言。"></x-field>
+  <x-field data-name="onBindOAuth" data-type="function" data-desc="用户成功绑定 OAuth 帐户后触发的回调函数。"></x-field>
+  <x-field data-name="onUnbindOAuth" data-type="function" data-desc="用户成功解绑 OAuth 帐户后触发的回调函数。"></x-field>
+  <x-field data-name="onSwitchPassport" data-type="function" data-desc="用户切换通行证后触发的回调函数。"></x-field>
+  <x-field data-name="session" data-type="object" data-desc="当前用户会话对象，切换通行证 UI 时需要。"></x-field>
+</x-field-group>
+
+### 2. 使用 useOAuth Hook
+
+`useOAuth` Hook 提供了与 OAuth 身份验证流程交互的函数。
+
+```jsx useOAuth Hook icon=logos:react
+import { useOAuth } from '@arcblock/did-connect-react/lib/OAuth';
+
+function SocialLoginButtons() {
+  const { loginOAuth, getOAuthConfigList, bindAuthLoading } = useOAuth();
+  const [providers, setProviders] = React.useState([]);
+
+  React.useEffect(() => {
+    getOAuthConfigList().then(setProviders);
+  }, [getOAuthConfigList]);
+
+  const handleLogin = async (provider) => {
+    try {
+      const result = await loginOAuth({ provider: provider.provider });
+      console.log('Login successful:', result);
+      // Handle login result, e.g., update session
+    } catch (error) {
+      console.error('Login failed:', error.message);
+    }
+  };
+
+  if (providers.length === 0) {
+    return <p>No third-party login methods configured.</p>;
+  }
+
+  return (
+    <div>
+      {providers.map((p) => (
+        <button key={p.provider} onClick={() => handleLogin(p)} disabled={bindAuthLoading}>
+          Login with {p.provider}
+        </button>
+      ))}
+    </div>
+  );
+}
+```
+
+### 核心函数
+
+- **`loginOAuth({ provider }, { action, ... })`**：为特定提供商启动登录流程。将打开一个弹出窗口供用户进行身份验证。
+- **`bindOAuth({ session, oauthItem })`**：将新的社交帐户绑定到当前登录的用户。
+- **`unbindOAuth({ session, connectedAccount })`**：从当前用户解绑社交帐户。
+- **`getOAuthConfigList()`**：异步获取在 Blocklet 设置中配置的已启用 OAuth 提供商列表。
+- **`switchOAuthPassport(user)`**：打开一个对话框，用于在与同一 OAuth 身份关联的不同用户帐户（通行证）之间切换。
+
+---
+
+## Passkeys（无密码）
+
+使用基于 WebAuthn 标准的 Passkeys 启用现代、安全且无密码的身份验证。这允许用户通过生物识别（指纹、面部 ID）、设备 PIN 或安全密钥登录。
+
+### 1. 使用 PasskeyProvider 进行设置
+
+使用 `PasskeyProvider` 包裹您的应用程序以启用 Passkey 功能。
+
+```jsx PasskeyProvider Setup icon=logos:react
+import { SessionProvider } from '@arcblock/did-connect-react';
+import { PasskeyProvider } from '@arcblock/did-connect-react/lib/Passkey';
+
+function App() {
+  return (
+    <SessionProvider>
+      <PasskeyProvider
+        onAddPasskey={(result) => console.log('Passkey added!', result)}
+        onRemovePasskey={(result) => console.log('Passkey removed!', result)}>
+        {/* Your application components */}
+      </PasskeyProvider>
+    </SessionProvider>
+  );
+}
+```
+
+**PasskeyProvider 的 Props**
+
+<x-field-group>
+  <x-field data-name="children" data-type="ReactNode" data-required="true" data-desc="将有权访问 Passkey 上下文的子组件。"></x-field>
+  <x-field data-name="locale" data-type="string" data-default="en" data-desc="用于 UI 消息和提示的语言。"></x-field>
+  <x-field data-name="onAddPasskey" data-type="function" data-desc="用户成功添加 Passkey 后触发的回调函数。"></x-field>
+  <x-field data-name="onRemovePasskey" data-type="function" data-desc="用户成功移除 Passkey 后触发的回调函数。"></x-field>
+  <x-field data-name="onSwitchPassport" data-type="function" data-desc="用户切换通行证后触发的回调函数。"></x-field>
+  <x-field data-name="session" data-type="object" data-desc="当前用户会话对象，切换通行证 UI 时需要。"></x-field>
+</x-field-group>
+
+### 2. 使用 usePasskey Hook
+
+`usePasskey` Hook 提供了 Passkey 注册和身份验证所需的所有必要函数。
+
+```jsx usePasskey Hook icon=logos:react
+import { usePasskey } from '@arcblock/did-connect-react/lib/Passkey';
+import { useSession } from '@arcblock/did-connect-react';
+
+function PasskeyAuth() {
+  const { loginPasskey, connectPasskey, connecting } = usePasskey();
+  const { session } = useSession();
+
+  const handleLogin = async () => {
+    try {
+      const result = await loginPasskey();
+      console.log('Passkey login successful:', result);
+      // Handle login result
+    } catch (error) {
+      console.error('Passkey login failed:', error.message);
+    }
+  };
+
+  const handleConnect = async () => {
+    // This should be called when a user is already logged in
+    // and wants to add a passkey in their profile settings.
+    if (!session.user) {
+      alert('You must be logged in to add a passkey.');
+      return;
+    }
+    try {
+      await connectPasskey();
+    } catch (error) {
+      console.error('Failed to connect passkey:', error.message);
+    }
+  };
+
+  return (
+    <div>
+      <button onClick={handleLogin}>Login with Passkey</button>
+      {session.user && (
+        <button onClick={handleConnect} disabled={connecting}>
+          {connecting ? 'Connecting...' : 'Add a Passkey'}
+        </button>
+      )}
+    </div>
+  );
+}
+```
+
+### 核心函数
+- **`loginPasskey({ action, ... })`**：启动 Passkey 身份验证流程（也称为断言）。这用于登录现有用户。
+- **`connectPasskey(extraParams)`**：一个高级函数，用于创建新的 Passkey 并将其绑定到当前用户的帐户。它处理完整的注册过程。
+- **`disconnectPasskey({ session, connectedAccount })`**：成功验证后，从当前用户的帐户中移除一个 Passkey。
+- **`createPasskey(params)`**：启动 WebAuthn 注册过程的底层函数。`connectPasskey` 内部使用此函数。
+- **`verifyPasskey(params)`**：启动 WebAuthn 身份验证过程的底层函数。`loginPasskey` 和 `disconnectPasskey` 内部使用此函数。
+- **`switchPassport(user)`**：打开一个对话框，用于在可能共享 Passkeys 的不同用户帐户（通行证）之间切换。
+
+---
+
+## 统一登录
+
+统一登录允许一组关联的 Blocklet 应用程序（一个“统一登录站点群”）共享同一个登录会话。当用户登录到指定的“主”站点时，他们可以在任何“成员”站点上被自动验证，而无需再次登录。
+
+### 1. 概念与设置
+
+此功能依赖于您 Blocklet 设置中的主-成员站点配置。`FederatedProvider` 组件是处理此功能在现代浏览器中正常工作所需的跨域通信所必需的，特别是在管理第三方 Cookie 访问方面。
+
+与其他 Provider 一样，`FederatedProvider` 应包含在您的组件树中，通常位于 `SessionProvider` 内部。
+
+```jsx FederatedProvider Setup icon=logos:react
+import { SessionProvider } from '@arcblock/did-connect-react';
+import { FederatedProvider } from '@arcblock/did-connect-react/lib/Federated';
+
+function App() {
+  return (
+    <SessionProvider>
+      <FederatedProvider>
+        {/* Your application components */}
+      </FederatedProvider>
+    </SessionProvider>
+  );
+}
+```
+
+### 2. 使用方法
+
+统一登录逻辑直接集成在会话管理中。您可以使用 `useSession` 返回的 `session` 对象上的 `loginFederated` 函数来触发它。
+
+`loginFederated` 支持两种模式：
+- **`auto`**：如果用户在主站点上拥有活动会话，则尝试静默登录用户。这非常适合在页面加载时进行检查。
+- **`manual`**：启动标准的 DID Connect 登录流程。成功登录后，它还会与主站点建立统一登录会话。
+
+```jsx Federated Login Example icon=logos:react
+import { useSession } from '@arcblock/did-connect-react';
+import React from 'react';
+
+function FederatedLogin() {
+  const { session } = useSession();
+  const { federatedEnabled, loginFederated } = session;
+
+  // Attempt auto-login on component mount
+  React.useEffect(() => {
+    if (federatedEnabled) {
+      loginFederated((err) => {
+        if (err) {
+          console.warn('Auto federated login failed:', err);
+        } else {
+          console.log('Auto federated login successful!');
+        }
+      }, { mode: 'auto' });
+    }
+  }, [federatedEnabled, loginFederated]);
+
+  const handleManualLogin = () => {
+    loginFederated((err) => {
+      if (err) console.error('Manual federated login failed:', err);
+    }, { mode: 'manual' });
+  };
+
+  if (!federatedEnabled) {
+    return <p>Federated login is not enabled.</p>;
+  }
+
+  return (
+    <button onClick={handleManualLogin}>
+      Login with Master Site Account
+    </button>
+  );
+}
+```

package/docs/advanced-utilities.ja.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)` | `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);
+    // ログイン成功時の処理
+  } catch (error) {
+    console.error('Authentication failed:', error.message);
+    // ポップアップが閉じられた、またはタイムアウトした場合の処理
+  }
+};
+```
+
+## セッションと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';
+
+// 'authResponse'がログインAPIから返されたオブジェクトであると仮定します
+function persistSession(authResponse) {
+  const connectedInfo = getConnectedInfo(authResponse);
+  updateConnectedInfo(connectedInfo, true);
+  console.log('セッション情報がCookieに保存されました。');
+}
+```
+
+## 暗号化ユーティリティ
+
+クライアントサイドでの暗号化または復号化が必要な高度なシナリオのために、ライブラリは`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, 'データの取得に失敗しました。');
+    alert(message);
+  }
+}
+```
+
+---
+
+これらのユーティリティを活用することで、より複雑でカスタマイズされた認証体験を構築できます。エクスポートされたすべてのメンバーとその型の完全なリストについては、[APIリファレンス](./api-reference.md)を参照してください。