Skip to main content

Blocklet Service

The BlockletService is a powerful client that acts as the primary interface for your blocklet to interact with the underlying ABT Node services. It simplifies tasks like user management, session handling, role-based access control (RBAC), and retrieving blocklet metadata by wrapping complex GraphQL queries and HTTP requests into a clean, promise-based JavaScript API.

This service is essential for building secure and feature-rich applications that leverage the full power of the Blocklet platform. Before diving into this service, it's helpful to understand the concepts covered in our Authentication guide.

How It Works

The BlockletService client within your application communicates with the blocklet-service running on the ABT Node. All requests are automatically authenticated using the blocklet's credentials, ensuring secure access to core functionalities.

The following diagram illustrates the communication flow between your blocklet, the Blocklet Service API, and the core services on the ABT Node:

Blocklet Service

Getting Started

To use the service, simply import and instantiate it. The client will automatically configure itself based on the environment variables provided by the Blocklet Server.

Getting Started

javascript
import BlockletService from '@blocklet/sdk/service/blocklet';

const client = new BlockletService();

async function main() {
  const { user } = await client.getOwner();
  console.log('Blocklet owner:', user.fullName);
}

main();

Session Management

login

Authenticates a user and starts a session.

Parameters

  • params object (required) — Login credentials or data.

Returns

  • Promise Promise<object> — An object containing the session and user info.
    • user object — The authenticated user's profile.
    • token string — The access token for the session.
    • refreshToken string — The refresh token to extend the session.
    • visitorId string — A unique identifier for the visitor/device.

refreshSession

Refreshes an expired session using a refresh token.

Parameters

  • refreshToken string (required) — The refresh token from a previous session.
  • visitorId string — The unique identifier for the visitor/device.

Returns

  • Promise Promise<object> — An object containing the new session and user info.
    • user object — The authenticated user's profile.
    • token string — The new access token.
    • refreshToken string — The new refresh token.
    • provider string — The login provider (e.g., 'wallet').

switchProfile

Updates a user's profile information.

Parameters

  • did string (required) — The DID of the user to update.
  • profile object (required) — An object with the profile fields to update.
    • avatar string — New avatar URL.
    • email string — New email address.
    • fullName string — New full name.

Returns

  • ResponseUser Promise<object> — An object containing the updated user profile.

User Management

getUser

Retrieves a single user's profile by their DID.

Parameters

  • did string (required) — The unique DID of the user to retrieve.
  • options object — Optional configuration for the query.
    • enableConnectedAccount boolean — If true, includes details about the user's connected accounts (e.g., OAuth providers).
    • includeTags boolean — If true, includes any tags associated with the user.

Returns

  • ResponseUser Promise<object> — An object containing the user's profile.
    • user object — The user profile object.

getUsers

Retrieves a paginated list of users, with support for filtering and sorting.

Parameters

  • args object — An object containing query, sorting, and pagination options.
    • paging object — Pagination options.
      • page number — The page number to retrieve.
      • pageSize number — The number of users per page.
    • query object — Filtering criteria.
      • role string — Filter by user role.
      • approved boolean — Filter by approval status.
      • search string — A search string to match against user fields.
    • sort object — Sorting criteria.
      • updatedAt number — Sort by update timestamp. 1 for ascending, -1 for descending.
      • createdAt number — Sort by creation timestamp. 1 for ascending, -1 for descending.
      • lastLoginAt number — Sort by last login timestamp. 1 for ascending, -1 for descending.

Returns

  • ResponseUsers Promise<object> — A paginated list of user objects.
    • users TUserInfo[] — An array of user profile objects.
    • paging object — Pagination information.
      • total number — Total number of users.
      • pageSize number — Number of users per page.
      • page number — Current page number.

getUsersCount

Gets the total number of users.

Returns

  • ResponseGetUsersCount Promise<object> — An object containing the total user count.
    • count number — The total number of users.

getUsersCountPerRole

Gets the count of users for each role.

Returns

  • ResponseGetUsersCountPerRole Promise<object> — An object containing user counts per role.
    • counts TKeyValue[] — An array of objects, where each object has a key (role name) and value (user count).

getOwner

Retrieves the profile of the blocklet owner.

Returns

  • ResponseUser Promise<object> — An object containing the owner's user profile.

updateUserApproval

Approves or revokes a user's access to the blocklet.

Parameters

  • did string (required) — The DID of the user to update.
  • approved boolean (required) — Set to true to approve, false to revoke.

Returns

  • ResponseUser Promise<object> — An object containing the updated user profile.

updateUserTags

Updates the tags associated with a user.

Parameters

  • args object (required)
    • did string (required) — The DID of the user.
    • tags number[] (required) — An array of tag IDs to associate with the user.

Returns

  • ResponseUser Promise<object> — An object containing the updated user profile.

updateUserExtra

Updates the extra metadata for a user.

Parameters

  • args object (required)
    • did string (required) — The DID of the user.
    • remark string — A remark or note about the user.
    • extra string — A JSON string for storing custom data.

Returns

  • ResponseUser Promise<object> — An object containing the updated user profile.

updateUserInfo

Updates a user's general information. Requires a valid user session cookie.

Parameters

  • userInfo object (required) — An object with the user fields to update. Must include the user's did.
  • options object (required) — Request options including headers.
    • headers object (required)
      • cookie string (required) — The user's session cookie.

Returns

  • ResponseUser Promise<object> — An object containing the updated user profile.

updateUserAddress

Updates a user's physical address. Requires a valid user session cookie.

Parameters

  • args object (required) — An object with the user's DID and address details.
    • did string (required) — The DID of the user.
    • address object — The user's address.
      • country string — Country
      • province string — State/Province
      • city string — City
      • postalCode string — Postal Code
      • line1 string — Address line 1
      • line2 string — Address line 2
  • options object (required) — Request options including headers.
    • headers object (required)
      • cookie string (required) — The user's session cookie.

Returns

  • ResponseUser Promise<object> — An object containing the updated user profile.

User Sessions

getUserSessions

Retrieves a list of active sessions for a user.

Parameters

  • args object — An object containing query and pagination options.
    • paging object — Pagination options.
    • query object — Filtering criteria.
      • userDid string — Filter by user DID.
      • status string — Filter by session status.

Returns

  • ResponseUserSessions Promise<object> — A paginated list of user sessions.
    • list TUserSession[] — An array of session objects.
    • paging object — Pagination information.

getUserSessionsCount

Gets the total count of user sessions, with optional filtering.

Parameters

  • args object — An object containing query options.
    • query object — Filtering criteria.
      • userDid string — Filter by user DID.

Returns

  • ResponseUserSessionsCount Promise<object> — An object containing the session count.
    • count number — The total number of sessions.

Social & Community

getUserFollowers

Retrieves a list of users who are following a specific user. Requires a valid user session cookie.

Parameters

  • args object (required) — Query options.
    • userDid string (required) — The DID of the user whose followers are to be retrieved.
    • paging object — Pagination options.
  • options object (required) — Request options including headers.
    • headers object (required)
      • cookie string (required) — The user's session cookie.

Returns

  • ResponseUserFollows Promise<object> — A paginated list of follower users.

getUserFollowing

Retrieves a list of users that a specific user is following. Requires a valid user session cookie.

Parameters

  • args object (required) — Query options.
    • userDid string (required) — The DID of the user whose following list is to be retrieved.
    • paging object — Pagination options.
  • options object (required) — Request options including headers.
    • headers object (required)
      • cookie string (required) — The user's session cookie.

Returns

  • ResponseUserFollows Promise<object> — A paginated list of users being followed.

getUserFollowStats

Gets the number of followers and following for a user. Requires a valid user session cookie.

Parameters

  • args object (required) — Query options.
    • userDids string[] (required) — An array of user DIDs.
  • options object (required) — Request options including headers.
    • headers object (required)
      • cookie string (required) — The user's session cookie.

Returns

  • ResponseUserRelationCount Promise<object> — An object with follower and following counts.

checkFollowing

Checks if a user is following one or more other users.

Parameters

  • args object (required)
    • followerDid string (required) — The DID of the potential follower.
    • userDids string[] (required) — An array of user DIDs to check against.

Returns

  • ResponseCheckFollowing Promise<object> — An object where keys are user DIDs and values are booleans indicating the follow status.

followUser

Makes one user follow another.

Parameters

  • args object (required)
    • followerDid string (required) — The DID of the user who is following.
    • userDid string (required) — The DID of the user to be followed.

Returns

  • GeneralResponse Promise<object> — A general response object indicating success or failure.

unfollowUser

Makes one user unfollow another.

Parameters

  • args object (required)
    • followerDid string (required) — The DID of the user who is unfollowing.
    • userDid string (required) — The DID of the user to be unfollowed.

Returns

  • GeneralResponse Promise<object> — A general response object indicating success or failure.

getUserInvites

Retrieves a list of users invited by a specific user. Requires a valid user session cookie.

Parameters

  • args object (required) — Query options.
    • userDid string (required) — The DID of the inviter.
    • paging object — Pagination options.
  • options object (required) — Request options including headers.
    • headers object (required)
      • cookie string (required) — The user's session cookie.

Returns

  • ResponseUsers Promise<object> — A paginated list of invited users.

Tag Management

getTags

Retrieves a list of all available user tags.

Parameters

  • args object
    • paging object — Pagination options.

Returns

  • ResponseTags Promise<object> — A paginated list of tag objects.
    • tags TTag[] — An array of tag objects.
    • paging object — Pagination information.

createTag

Creates a new user tag.

Parameters

  • args object (required)
    • tag object (required)
      • title string (required) — The title of the tag.
      • description string — A description for the tag.
      • color string — A hex color code for the tag.

Returns

  • ResponseTag Promise<object> — An object containing the newly created tag.

updateTag

Updates an existing user tag.

Parameters

  • args object (required)
    • tag object (required)
      • id number (required) — The ID of the tag to update.
      • title string — The new title.
      • description string — The new description.
      • color string — The new color.

Returns

  • ResponseTag Promise<object> — An object containing the updated tag.

deleteTag

Deletes a user tag.

Parameters

  • args object (required)
    • tag object (required)
      • id number (required) — The ID of the tag to delete.

Returns

  • ResponseTag Promise<object> — An object containing the deleted tag.

Role-Based Access Control (RBAC)

getRoles

Retrieves a list of all available roles.

Returns

  • ResponseRoles Promise<object> — An object containing a list of roles.
    • roles TRole[] — An array of role objects.

getRole

Retrieves a single role by its name.

Parameters

  • name string (required) — The unique name of the role.

Returns

  • ResponseRole Promise<object> — An object containing the role details.

createRole

Creates a new role.

Parameters

  • args object (required)
    • name string (required) — A unique identifier for the role (e.g., editor).
    • title string (required) — A human-readable title (e.g., Content Editor).
    • description string — A brief description of the role's purpose.

Returns

  • ResponseRole Promise<object> — An object containing the newly created role.

updateRole

Updates an existing role.

Parameters

  • name string (required) — The name of the role to update.
  • updates object (required) — An object with the fields to update.
    • title string — The new title.
    • description string — The new description.

Returns

  • ResponseRole Promise<object> — An object containing the updated role.

deleteRole

Deletes a role.

Parameters

  • name string (required) — The name of the role to delete.

Returns

  • GeneralResponse Promise<object> — A general response object indicating success or failure.

getPermissions

Retrieves a list of all available permissions.

Returns

  • ResponsePermissions Promise<object> — An object containing a list of permissions.
    • permissions TPermission[] — An array of permission objects.

getPermissionsByRole

Retrieves all permissions granted to a specific role.

Parameters

  • role string (required) — The name of the role.

Returns

  • ResponsePermissions Promise<object> — An object containing the list of permissions for the role.

createPermission

Creates a new permission.

Parameters

  • args object (required)
    • name string (required) — A unique name for the permission (e.g., post:create).
    • description string — A description of what the permission allows.

Returns

  • ResponsePermission Promise<object> — An object containing the newly created permission.

updatePermission

Updates an existing permission.

Parameters

  • name string (required) — The name of the permission to update.
  • updates object (required)
    • description string — The new description for the permission.

Returns

  • ResponsePermission Promise<object> — An object containing the updated permission.

deletePermission

Deletes a permission.

Parameters

  • name string (required) — The name of the permission to delete.

Returns

  • GeneralResponse Promise<object> — A general response object indicating success or failure.

grantPermissionForRole

Assigns a permission to a role.

Parameters

  • role string (required) — The name of the role.
  • permission string (required) — The name of the permission to grant.

Returns

  • GeneralResponse Promise<object> — A general response object indicating success or failure.

revokePermissionFromRole

Revokes a permission from a role.

Parameters

  • role string (required) — The name of the role.
  • permission string (required) — The name of the permission to revoke.

Returns

  • GeneralResponse Promise<object> — A general response object indicating success or failure.

updatePermissionsForRole

Replaces all existing permissions for a role with a new set.

Parameters

  • role string (required) — The name of the role.
  • permissions string[] (required) — An array of permission names to set for the role.

Returns

  • ResponseRole Promise<object> — An object containing the updated role.

hasPermission

Checks if a role has a specific permission.

Parameters

  • role string (required) — The name of the role to check.
  • permission string (required) — The name of the permission to verify.

Returns

  • BooleanResponse Promise<object> — An object with a boolean result property.
    • result boolean — true if the role has the permission, otherwise false.

Passport Management

issuePassportToUser

Issues a new passport to a user, assigning them a role.

Parameters

  • args object (required)
    • userDid string (required) — The DID of the user receiving the passport.
    • role string (required) — The role to assign with this passport.

Returns

  • ResponseUser Promise<object> — An object containing the updated user profile, including the new passport.

enableUserPassport

Enables a previously revoked passport for a user.

Parameters

  • args object (required)
    • userDid string (required) — The DID of the user.
    • passportId string (required) — The ID of the passport to enable.

Returns

  • ResponseUser Promise<object> — An object containing the updated user profile.

revokeUserPassport

Revokes a user's passport.

Parameters

  • args object (required)
    • userDid string (required) — The DID of the user.
    • passportId string (required) — The ID of the passport to revoke.

Returns

  • ResponseUser Promise<object> — An object containing the updated user profile.

removeUserPassport

Permanently removes a user's passport.

Parameters

  • args object (required)
    • userDid string (required) — The DID of the user.
    • passportId string (required) — The ID of the passport to remove.

Returns

  • GeneralResponse Promise<object> — A general response object indicating success or failure.

Blocklet & Component Info

getBlocklet

Retrieves the metadata and state for the current blocklet.

Parameters

  • attachRuntimeInfo boolean (default: false) — If true, includes runtime information like CPU and memory usage.
  • useCache boolean (default: true) — If false, bypasses the cache to fetch the latest data.

Returns

  • ResponseBlocklet Promise<object> — An object containing the blocklet's state and metadata.

getComponent

Retrieves the state of a specific component within the current blocklet by its DID.

Parameters

  • did string (required) — The DID of the component to retrieve.

Returns

  • ComponentState Promise<object> — An object containing the component's state and metadata.

getTrustedDomains

Retrieves a list of trusted domains for federated login.

Returns

  • string[] Promise<string[]> — An array of trusted domain URLs.

getVault

Retrieves and verifies the blocklet's vault information.

Returns

  • vault Promise<string> — The vault string if verification is successful.

clearCache

Clears cached data on the node based on a pattern.

Parameters

  • args object
    • pattern string — A pattern to match cache keys for removal.

Returns

  • ResponseClearCache Promise<object> — An object containing a list of removed cache keys.
    • removed string[] — An array of keys that were removed from the cache.

Access Key Management

createAccessKey

Creates a new access key for programmatic access.

Parameters

  • params object (required)
    • remark string — A description for the access key.
    • passport string — The role/passport to associate with the key. Defaults to 'guest'.

Returns

  • ResponseCreateAccessKey Promise<object> — An object containing the newly created access key and secret.

getAccessKey

Retrieves details for a single access key.

Parameters

  • params object (required)
    • accessKeyId string (required) — The ID of the access key to retrieve.

Returns

  • ResponseAccessKey Promise<object> — An object containing the access key details.

getAccessKeys

Retrieves a list of access keys.

Parameters

  • params object
    • paging object — Pagination options.

Returns

  • ResponseAccessKeys Promise<object> — A paginated list of access key objects.

verifyAccessKey

Verifies if an access key is valid.

Parameters

  • params object (required)
    • accessKeyId string (required) — The ID of the access key to verify.

Returns

  • ResponseAccessKey Promise<object> — An object containing the access key details if valid.

After mastering the BlockletService, you might want to explore how to send messages to your users. Head over to the Notification Service guide to learn more.