# 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，則使用 WebSockets 進行即時狀態更新。"></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="定義在驗證過程中如何處理通行密鑰（Passkeys）。"></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 code 的大小（以像素為單位）。"></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 code 的說明文字。"></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="已驗證的使用者物件。如果沒有使用者登入，則為 Undefined。"></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="用於 Passkey 整合的掛鉤。"></x-field>
  <x-field data-name="PasskeyProvider" data-type="Function" data-desc="用於 Passkey 上下文的提供者元件。"></x-field>
  <x-field data-name="PasskeyConsumer" data-type="Function" data-desc="用於 Passkey 上下文的消費者元件。"></x-field>
  <x-field data-name="PasskeyContext" data-type="object" data-desc="用於 Passkey 的 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>

### 核心資料類型

這些是在各種其他介面中使用的基本字串聯合類型。

| Type | Description | Possible Values |
| --- | --- | --- |
| `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'） |
