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.

action
string
required
The primary action for the connection, e.g., 'login'.
containerEl
Element
The DOM element to which the connection modal should be appended.
prefix
string
default:/api/did
The API endpoint prefix for DID Connect services.
locale
'en' | 'zh'
default:en
The language to be used for the UI.
popup
boolean
default:false
If true, the connection UI will be displayed in a popup window instead of a modal.
checkInterval
number
default:2000
The interval in milliseconds to check the session status.
checkTimeout
number
default:300000
The timeout in milliseconds for the entire session check process (5 minutes).
closeTimeout
number
default:2000
The delay in milliseconds before closing the modal after a successful connection.
extraParams
object
default:{}
Any extra parameters to be sent with the connection request.
tokenKey
string
default:_t_
The key used to store the session token.
encKey
string
default:_ek_
The key used for encryption.
baseUrl
string
default:''
The base URL for API requests.
messages
ConnectMessages
An object to customize the text displayed in the connection UI.
autoConnect
boolean
default:true
If true, automatically attempts to connect using a saved session.
forceConnected
boolean | string
default:true
Forces the connection to be treated as established.
saveConnect
boolean
default:true
If true, the successful connection session will be saved for autoConnect.
useSocket
boolean
default:true
If true, uses WebSockets for real-time status updates.
allowWallet
boolean
default:true
If true, allows connection via DID Wallet.
passkeyBehavior
'none' | 'both' | 'only-existing' | 'only-new'
default:true
Defines how Passkeys are handled during the authentication process.
provider
'wallet' | 'auth0' | ''
default:wallet
Specifies the authentication provider.
qrcodeSize
number
default:160
The size of the QR code in pixels.
showDownload
boolean
default:true
If true, shows download links for the DID Wallet.
webWalletUrl
string
default:https://web.abtwallet.io
The URL for the web-based DID Wallet.
enabledConnectTypes
Array<'web' | 'mobile' | 'auth0' | 'github' | 'apple' | 'google' | 'passkey'>
default:["web", "mobile", "github", "apple", "google", "auth0", "passkey"]
An array of connection methods to enable in the UI.
extraContent
any
Custom content to be rendered within the connection modal.
loadingEle
any
A custom loading element to display.
disableSwitchApp
boolean
default:false
If true, disables the automatic app switching on mobile devices.
hideCloseButton
boolean
default:false
If true, hides the close button in the modal.
options
object
default:{}

Additional configuration options.

1 subfields
onRecreateSession
Function
Callback function executed when a session is recreated.
checkFn
() => boolean
A custom function to check the connection status.
onSuccess
(result: object) => void
Callback function executed upon a successful connection.
onError
(error: any) => void
Callback function executed when an error occurs.
onClose
Function
Callback function executed when the connection modal is closed.

ConnectMessages#

Object to customize the text displayed within the DID Connect UI.

title
string
required
The main title of the connect modal.
scan
string
required
The instruction text for scanning the QR code.
success
ReactNode
required
The message or component displayed upon successful connection.
confirm
string
The text prompting the user to confirm the action in their wallet.
error
string
A custom error message to display.

OpenDidConnect#

This function type defines the signature for opening the DID Connect flow with advanced requirements, often used for progressive authorization.

params
ConnectProps
required
The standard connection properties.
options
object
Additional options to control the connection mode and specify requirements.
4 subfields

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.

action
string
The current action being performed (e.g., 'login').
error
string
Any error message that occurred during the session management.
initialized
boolean
True if the session has been initialized.
loading
boolean
True if the session is currently in a loading state.
open
boolean
True if the DID Connect modal is currently open.
walletOS
WalletOS
The operating system of the connected wallet ('web', 'android', 'ios').
user
User
The authenticated user object. Undefined if no user is logged in.
locale
UserLocale
The current locale for the user.
provider
WalletProvider
The provider used for the current session.
baseUrl
string
The base URL used for API calls.
federatedMaster
object
Information about the master site in a Federated Login group.
login
LoginSessionFn
Function to initiate the login process.
logout
LogoutSessionFn
Function to log the user out.
switch
Function
Function to switch between different user accounts.
switchDid
CommonSessionFn
Function to switch the user's active DID.
autoSwitchDid
Function
Function to automatically switch DIDs.
switchProfile
CommonSessionFn
Function to switch user profiles.
switchPassport
CommonSessionFn
Function to switch between different passports.
bindWallet
CommonSessionFn
Function to initiate the wallet binding process.
refresh
Function
Function to manually refresh the session data.
updateConnectedInfo
(data: object) => void
Function to update connection information.
openDidConnect
OpenDidConnect
Function to open the DID Connect modal with advanced requirements.
useOAuth
Function
Hook for OAuth integration.
OAuthProvider
Function
Provider component for OAuth context.
OAuthConsumer
Function
Consumer component for OAuth context.
OAuthContext
object
The React context object for OAuth.
usePasskey
Function
Hook for Passkey integration.
PasskeyProvider
Function
Provider component for Passkey context.
PasskeyConsumer
Function
Consumer component for Passkey context.
PasskeyContext
object
The React context object for Passkey.
useDid
(options: { session: Session }) => void
A utility hook to work with DID information.
WrapDid
Function
A wrapper component related to DID functionality.
getUserSessions
() => Promise<UserSession[]>
Function to fetch all active sessions for the current user.

User#

Represents the detailed profile of an authenticated user.

did
string
required
The user's Decentralized Identifier (DID).
pk
string
required
The user's public key.
avatar
string
required
URL of the user's avatar.
fullName
string
required
The user's full name.
email
string
required
The user's email address.
role
UserRole
required
The role of the user within the application (e.g., 'guest', 'member', 'admin').
locale
UserLocale
required
The user's preferred language.
connectedAccounts
ConnectAccount[]
required
A list of accounts connected to the user's DID.
passports
Passport[]
required
A list of passports associated with the user.
permissions
any[]
required
A list of permissions granted to the user.
didSpace
object
Information about the user's DID Space.
approved
boolean
required
Indicates if the user has been approved.
remark
string
An optional remark or note about the user.
createdAt
string
required
Timestamp of when the user account was created.
updatedAt
string
required
Timestamp of the last update to the user account.
firstLoginAt
string
Timestamp of the user's first login.
lastLoginAt
string
Timestamp of the user's last login.
lastLoginIp
string
IP address from the user's last login.

UserSession#

Represents a single active session for a user, typically retrieved from getUserSessions.

id
string
required
The unique identifier for the session.
appName
string
required
The name of the application for this session.
appPid
string
required
The application's Passport ID.
updatedAt
string
required
Timestamp of the last session update.
userDid
string
required
The DID of the user for this session.
visitorId
string
required
The visitor ID associated with the session.
extra
object
required
Any extra data associated with the session.
user
SessionUser
required
A simplified user object for the session.
passportId
string
The ID of the passport used for this session.

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

Utilities