Skip to main content

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.
    • showQuickConnect boolean (default: true) — If true, shows the quick connect option for saved sessions.
  • 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.
    • openMode 'redirect' | 'window' | 'popup' (default: popup) — Determines how the DID Connect window is opened.
    • requirements object — Specifies the requirements for the session.
      • login boolean (default: true) — If true, requires the user to be logged in.
      • bindWallet boolean (default: true) — If true, requires the user to have a DID Wallet account bound.
      • bindDidSpaces false | 'read' | 'full' (default: false) — Specifies if DID Spaces binding is required, and what level of access is needed.
    • baseUrl string — The base URL for API requests.
    • locale BaseLocale — The language for the UI ('en' or 'zh').

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.

TypeDescriptionPossible Values
WalletProviderIdentifies the authentication method or provider.wallet, auth0, apple, github, google, passkey
WalletOSRepresents the operating system of the DID Wallet.web, android, ios, '' (empty string)
UserRoleDefines the role of a user within the application.guest, member, admin, owner, or any string
BaseLocaleThe base set of supported languages.en, zh
UserLocaleThe user's locale, can be a base locale or a more specific one.en, zh, or any string (e.g., 'en-US')