Skip to main content

Types

This section provides a detailed reference for the core TypeScript types and interfaces exported by the @blocklet/js-sdk. Using these types in your pr

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.

  • did string (required) — The decentralized identifier (DID) of the Blocklet.
  • appId string (required) — The application ID, which is also the main component's DID.
  • appPk string (required) — The public key associated with the application.
  • appIds string[] — A list of associated application IDs, used in a Federated Login Group.
  • appPid string (required) — The process ID for the application.
  • appName string (required) — The human-readable name of the application.
  • appDescription string (required) — A short description of the application.
  • appLogo string (required) — URL to the application's logo (square).
  • appLogoRect string (required) — URL to the application's logo (rectangular).
  • appUrl string (required) — The primary URL where the application is hosted.
  • domainAliases string[] — Alternative domain names for the application.
  • isComponent boolean (required) — Indicates if the Blocklet is a component of another Blocklet.
  • prefix string (required) — The URL prefix for the Blocklet's routes.
  • groupPrefix string (required) — The URL prefix for the Federated Login Group.
  • pageGroup string (required) — The group this page belongs to.
  • version string (required) — The version of the Blocklet.
  • mode string (required) — 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.
  • status string (required) — The current running status of the Blocklet.
  • serverDid string (required) — 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.
  • updatedAt number (required) — 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.

  • session object (required) — Session configuration.
    • ttl number (required) — Session time-to-live in seconds.
    • cacheTtl number (required) — Cache time-to-live in seconds.
  • federated object (required) — Federated Login Group configuration.
    • master object (required) — Information about the master application in the group.
      • appId string (required) — Master application ID.
      • appPid string (required) — Master application process ID.
      • appName string (required) — Master application name.
      • appDescription string (required) — Master application description.
      • appUrl string (required) — Master application URL.
      • appLogo string (required) — Master application logo URL.
      • version string (required) — Master application version.
    • config Record<string, any> (required) — Additional configuration for the federated group.
  • 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.

  • avatar string (required) — URL of the user's avatar image.
  • did string (required) — The user's decentralized identifier (DID).
  • fullName string (required) — The user's full name.
  • 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.

  • webhooks Webhook[] — An array of configured webhooks.
  • notifications object — Channel-specific notification settings.
    • email boolean — Enable or disable email notifications.
    • wallet boolean — Enable or disable DID Wallet notifications.
    • phone boolean — Enable or disable phone notifications.

Webhook

Defines the structure for a single webhook configuration.

  • type 'slack' | 'api' (required) — The type of the webhook endpoint.
  • url string (required) — 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.

  • [key] boolean (required) — 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.

  • did string (required) — The DID of the space gateway.
  • name string (required) — The name of the space gateway.
  • url string (required) — The public URL of the space gateway.
  • endpoint string (required) — 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.

  • appName string (required) — Name of the application for the session.
  • appPid string (required) — Process ID of the application for the session.
  • extra object (required) — Additional metadata about the session.
    • walletOS 'android' | 'ios' | 'web' (required) — The operating system of the wallet used for login.
  • id string (required) — 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.
  • ua string (required) — The User-Agent string of the client.
  • createdAt string — ISO string timestamp of when the session was created.
  • updatedAt string (required) — ISO string timestamp of the last session activity.
  • status string — The current status of the session (e.g., 'online', 'expired').
  • user UserSessionUser — Detailed information about the user associated with the session.
  • userDid string (required) — The DID of the user.
  • visitorId string (required) — A unique identifier for the device/browser.

UserSessionUser

Contains detailed user information associated with a UserSession.

  • avatar string (required) — URL of the user's avatar image.
  • did string (required) — The user's decentralized identifier (DID).
  • email string (required) — The user's email address.
  • fullName string (required) — The user's full name.
  • pk string (required) — The user's public key.
  • remark string — An optional remark or note about the user.
  • role string (required) — The role of the user (e.g., 'owner', 'admin').
  • roleTitle string (required) — 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.
  • paging object (required) — Pagination information.
    • page number (required) — The current page number.
    • pageSize number (required) — The number of items per page.
    • total number (required) — The total number of sessions available.

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.

  • appId string (required) — The application ID.
  • appPid string (required) — The application process ID.
  • appName string (required) — The application name.
  • appDescription string (required) — The application description.
  • apiPrefix string (required) — The prefix for backend API routes.
  • baseUrl string (required) — 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.

TypeScript Definition

typescript
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.

  • nextToken string (required) — The new session token.
  • nextRefreshToken string (required) — The new refresh token.

RequestParams

Defines common parameters that can be used when making requests with the SDK's API helpers.

  • lazy boolean — If true, the request may be debounced or delayed.
  • lazyTime number — The delay time in milliseconds for a lazy request.
  • componentDid string — The DID of the component to target with the request.