Skip to main content

Type Definitions

The Blocklet SDK is strongly typed to help you write more robust and maintainable code. This section provides a reference for the most common TypeScript types and interfaces you'll encounter when working with user sessions, notifications, events, and blocklet configurations. Understanding these types will help ensure type safety and leverage your IDE's autocompletion features effectively.

Session & User Types

These types are fundamental for managing user authentication and identity within your application.

SessionUser

The SessionUser object is attached to the request object (as req.user) by the session middleware. It contains essential information about the currently logged-in user.

SessionUser Type Definition

typescript
export type SessionUser = {
  did: string;
  role: string | undefined;
  provider: string;
  fullName: string;
  walletOS: string;
  emailVerified?: boolean;
  phoneVerified?: boolean;
  method?: AuthMethod;
  kyc?: number;
  [key: string]: any;
};
  • did string (required) — The user's Decentralized Identifier (DID).
  • role string | undefined — The role assigned to the user (e.g., 'admin', 'owner', 'guest').
  • provider string (required) — The authentication provider used for login (e.g., 'wallet').
  • fullName string (required) — The user's full name.
  • walletOS string (required) — The operating system of the user's wallet.
  • emailVerified boolean — Indicates if the user's email has been verified.
  • phoneVerified boolean — Indicates if the user's phone has been verified.
  • method AuthMethod — The authentication method used. Common values are 'loginToken', 'componentCall', 'signedToken', 'accessKey'.
  • kyc number — A numeric representation of the user's KYC status.

TUserInfo

The TUserInfo type provides a comprehensive view of a user's profile, including their identity, contact information, login history, and associated security credentials.

  • did string (required) — The user's Decentralized Identifier (DID).
  • pk string (required) — The user's public key.
  • role string (required) — The primary role of the user.
  • avatar string (required) — URL to the user's avatar image.
  • fullName string (required) — The user's full name.
  • email string (required) — The user's email address.
  • approved boolean (required) — Indicates if the user account has been approved.
  • createdAt number (required) — Timestamp of when the user was created.
  • lastLoginAt number (required) — Timestamp of the user's last login.
  • passports TPassport[] (required) — An array of passports issued to the user.
  • connectedAccounts TConnectedAccount[] (required) — A list of external accounts linked to the user's profile.

Notification Types

When using the Notification Service, you will work with these types to construct and send messages to users.

TNotification

This is the main interface for defining a notification. It includes all the necessary fields to control the content, appearance, and behavior of a notification.

  • id string — A unique identifier for the notification.
  • title string — The main title of the notification.
  • body string — The main content or message of the notification.
  • type 'notification' | 'connect' | 'feed' | 'hi' | 'passthrough' — The type of notification, which can affect its handling and presentation.
  • severity 'normal' | 'success' | 'error' | 'warning' — The severity level, often used to color-code the notification.
  • actions TNotificationAction[] — An array of interactive action buttons to include in the notification.
  • attachments TNotificationAttachment[] — An array of rich content attachments, such as images, text blocks, or links.
  • activity TNotificationActivity — Describes a social activity, like a comment or follow, that triggered the notification.
  • url string — A URL to navigate to when the notification is clicked.

TNotificationAttachment

Attachments allow you to add rich, structured content to your notifications.

  • type 'asset' | 'vc' | 'token' | 'text' | 'image' | 'divider' | 'transaction' | 'dapp' | 'link' | 'section' (required) — The type of content to display.
  • data any — The data payload for the attachment, which varies depending on the type. For example, an 'image' type would have an object with a url property.
  • fields any — Additional fields to display within the attachment, often used for 'section' types.

Example: Image Attachment

json
{
  "type": "image",
  "data": {
    "url": "https://path.to/your/image.png",
    "alt": "Descriptive text for the image"
  }
}

TNotificationAction

Actions are interactive buttons that can be added to a notification, allowing users to respond directly.

  • name string (required) — The name of the action, often used as an identifier.
  • title string — The text displayed on the button. Defaults to name if not provided.
  • link string — The URL to navigate to when the button is clicked.
  • color string — The text color of the button.
  • bgColor string — The background color of the button.

Event Types

When working with the event bus, events are structured using the TEvent interface.

TEvent

This interface defines the structure for events emitted and consumed within the Blocklet ecosystem.

  • id string (required) — A unique identifier for the event instance.
  • type string (required) — The event type name (e.g., 'user', 'post').
  • time Date (required) — The timestamp when the event occurred.
  • source unknown (required) — The source or originator of the event.
  • spec_version string (required) — The CloudEvents specification version.
  • object_id string — The ID of the object that the event pertains to.
  • object_type string — The type of the object that the event pertains to.
  • data object (required) — The payload of the event, containing details about what happened.

Configuration & State Types

These types define the structure of configuration objects and state information for your blocklet.

WindowBlocklet

On the client-side, the window.blocklet object provides essential context about the running blocklet. This object is typed as WindowBlocklet.

  • did string (required) — The DID of the blocklet instance.
  • appId string (required) — The application ID.
  • appName string (required) — The display name of the application.
  • appUrl string (required) — The public URL of the application.
  • webWalletUrl string (required) — The URL of the associated web wallet.
  • isComponent boolean (required) — true if the blocklet is running as a component of another blocklet.
  • prefix string (required) — The URL prefix for the blocklet's routes.
  • theme TTheme (required) — The current theme settings for the UI.
  • navigation TNavigationItem[] (required) — An array of navigation items for the application menu.

TBlockletState

This type represents the complete state of a blocklet instance on the server, including its metadata, status, configuration, and relationship with other components.

  • meta TBlockletMeta — The metadata of the blocklet, from its blocklet.yml file.
  • status enum_pb.BlockletStatusMap (required) — The current running status of the blocklet (e.g., 'running', 'stopped').
  • port number (required) — The port the blocklet is running on.
  • appDid string (required) — The DID of the blocklet instance.
  • children TComponentState[] (required) — An array of component states if this blocklet has children.
  • settings TBlockletSettings — The user-configured settings for the blocklet.
  • environments TConfigEntry[] (required) — A list of environment variables configured for the blocklet.