# 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') |