This section provides a detailed reference for the core TypeScript types and interfaces exported by the @blocklet/js-sdk. Using these types in your project can help you leverage TypeScript's static analysis and autocompletion for a better development experience.
Core Blocklet Types#
These types define the fundamental structure of a Blocklet application and its components.
Blocklet#
Represents the complete metadata and configuration for a Blocklet. This object is typically available globally as window.blocklet when the application is running within the Blocklet Server environment.
The decentralized identifier (DID) of the Blocklet.
The application ID, which is also the main component's DID.
The public key associated with the application.
A list of associated application IDs, used in a Federated Login Group.
The process ID for the application.
The human-readable name of the application.
appDescription
string
required
A short description of the application.
URL to the application's logo (square).
appLogoRect
string
required
URL to the application's logo (rectangular).
The primary URL where the application is hosted.
Alternative domain names for the application.
isComponent
boolean
required
Indicates if the Blocklet is a component of another Blocklet.
The URL prefix for the Blocklet's routes.
groupPrefix
string
required
The URL prefix for the Federated Login Group.
The group this page belongs to.
The version of the Blocklet.
The running mode of the Blocklet (e.g., 'development', 'production').
tenantMode
'single' | 'multiple'
required
The tenancy mode of the Blocklet.
theme
BlockletTheme
required
The theme configuration for the Blocklet.
navigation
BlockletNavigation[]
required
An array of navigation items for the Blocklet's UI.
preferences
Record<string, any>
required
User-configurable preferences.
languages
{ code: string; name: string }[]
required
A list of supported languages.
passportColor
string
required
The primary color used in the DID Wallet passport.
componentMountPoints
BlockletComponent[]
required
A list of child components mounted by this Blocklet.
alsoKnownAs
string[]
required
A list of alternative identifiers.
trustedFactories
string[]
required
A list of trusted factory DIDs.
The current running status of the Blocklet.
The DID of the Blocklet Server instance.
serverVersion
string
required
The version of the Blocklet Server.
componentId
string
required
The ID of the component.
webWalletUrl
string
required
The URL of the web-based DID Wallet.
Timestamp of the last update.
settings
BlockletSettings
required
Detailed settings for the Blocklet.
BlockletSettings#
Contains various settings for the Blocklet, including session management, Federated Login Group configurations, and OAuth provider details.
Federated Login Group configuration.
oauth
Record<string, { enabled: boolean; [x: string]: any }>
required
OAuth provider configurations, keyed by provider name.
BlockletComponent#
Describes a component that is mounted within a parent Blocklet. It inherits properties from TComponentInternalInfo.
status
keyof typeof BlockletStatus
required
The running status of the component (e.g., 'running', 'stopped').
User and Authentication Types#
These types are used by the AuthService to manage user profiles, settings, and authentication-related data.
UserPublicInfo#
Represents the basic public profile information of a user.
URL of the user's avatar image.
The user's decentralized identifier (DID).
sourceAppPid
string | null
required
The process ID of the application where the user originated, if applicable.
NotificationConfig#
Defines a user's notification preferences, including webhook configurations and notification channels.
An array of configured webhooks.
Channel-specific notification settings.
Webhook#
Defines the structure for a single webhook configuration.
type
'slack' | 'api'
required
The type of the webhook endpoint.
The URL to which the webhook notification will be sent.
PrivacyConfig#
An object representing a user's privacy settings, where keys correspond to specific privacy options.
A dynamic key representing a privacy setting, with a boolean value indicating if it's enabled.
SpaceGateway#
Defines the properties of a DID Space gateway.
The DID of the space gateway.
The name of the space gateway.
The public URL of the space gateway.
The API endpoint of the space gateway.
Session Management Types#
These types are used by the UserSessionService to manage user login sessions across different devices and applications.
UserSession#
Represents a single user login session, containing details about the device, application, and user.
Name of the application for the session.
Process ID of the application for the session.
Additional metadata about the session.
The unique identifier for the session.
lastLoginIp
string
required
The IP address of the last login.
passportId
string | null
required
The ID of the passport used for login.
The User-Agent string of the client.
ISO string timestamp of when the session was created.
ISO string timestamp of the last session activity.
The current status of the session (e.g., 'online', 'expired').
Detailed information about the user associated with the session.
A unique identifier for the device/browser.
UserSessionUser#
Contains detailed user information associated with a UserSession.
URL of the user's avatar image.
The user's decentralized identifier (DID).
The user's email address.
An optional remark or note about the user.
The role of the user (e.g., 'owner', 'admin').
The display title for the user's role.
sourceAppPid
string | null
required
The process ID of the application where the user originated.
sourceProvider
'wallet' | 'auth0' | 'nft'
required
The original provider used for authentication.
UserSessionList#
A paginated response object for a list of user sessions.
list
UserSession[]
required
An array of user session objects.
Global & Environment Types#
These types define globally available objects and server environment configurations.
ServerEnv#
Represents server-side environment variables that are often exposed to the client-side as window.env.
The application process ID.
appDescription
string
required
The application description.
The prefix for backend API routes.
The base URL of the application.
Global Window Declarations#
The SDK relies on certain global variables being present in the window object when running in a browser environment.
declare global {
interface Window {
blocklet: Blocklet;
env?: ServerEnv;
}
}
Utility Types#
Helper types used for API requests and token management.
TokenResult#
Represents the successful result of a token refresh operation.
nextRefreshToken
string
required
The new refresh token.
RequestParams#
Defines common parameters that can be used when making requests with the SDK's API helpers.
If true, the request may be debounced or delayed.
The delay time in milliseconds for a lazy request.
The DID of the component to target with the request.