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.


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

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<object>
Promise<object>
An object containing the session and user info.
4 subfields

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<object>
Promise<object>
An object containing the new session and user info.
4 subfields

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.
3 subfields

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.
2 subfields

Returns

ResponseUser
Promise<object>
An object containing the user's profile.
1 subfields

getUsers#

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

Parameters

args
object
An object containing query, sorting, and pagination options.
3 subfields

Returns

ResponseUsers
Promise<object>
A paginated list of user objects.
2 subfields

getUsersCount#

Gets the total number of users.

Returns

ResponseGetUsersCount
Promise<object>
An object containing the total user count.
1 subfields

getUsersCountPerRole#

Gets the count of users for each role.

Returns

ResponseGetUsersCountPerRole
Promise<object>
An object containing user counts per role.
1 subfields

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
2 subfields

Returns

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

updateUserExtra#

Updates the extra metadata for a user.

Parameters

args
object
required
3 subfields

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.
1 subfields

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.
2 subfields
options
object
required
Request options including headers.
1 subfields

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.
2 subfields

Returns

ResponseUserSessions
Promise<object>
A paginated list of user sessions.
2 subfields

getUserSessionsCount#

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

Parameters

args
object
An object containing query options.
1 subfields

Returns

ResponseUserSessionsCount
Promise<object>
An object containing the session count.
1 subfields

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.
2 subfields
options
object
required
Request options including headers.
1 subfields

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.
2 subfields
options
object
required
Request options including headers.
1 subfields

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.
1 subfields
options
object
required
Request options including headers.
1 subfields

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
2 subfields

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
2 subfields

Returns

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

unfollowUser#

Makes one user unfollow another.

Parameters

args
object
required
2 subfields

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.
2 subfields
options
object
required
Request options including headers.
1 subfields

Returns

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

Tag Management#

getTags#

Retrieves a list of all available user tags.

Parameters

args
object
1 subfields

Returns

ResponseTags
Promise<object>
A paginated list of tag objects.
2 subfields

createTag#

Creates a new user tag.

Parameters

args
object
required
1 subfields

Returns

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

updateTag#

Updates an existing user tag.

Parameters

args
object
required
1 subfields

Returns

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

deleteTag#

Deletes a user tag.

Parameters

args
object
required
1 subfields

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.
1 subfields

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
3 subfields

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.
2 subfields

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.
1 subfields

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
2 subfields

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
1 subfields

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.
1 subfields

Passport Management#

issuePassportToUser#

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

Parameters

args
object
required
2 subfields

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
2 subfields

Returns

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

revokeUserPassport#

Revokes a user's passport.

Parameters

args
object
required
2 subfields

Returns

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

removeUserPassport#

Permanently removes a user's passport.

Parameters

args
object
required
2 subfields

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
1 subfields

Returns

ResponseClearCache
Promise<object>
An object containing a list of removed cache keys.
1 subfields

Access Key Management#

createAccessKey#

Creates a new access key for programmatic access.

Parameters

params
object
required
2 subfields

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
1 subfields

Returns

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

getAccessKeys#

Retrieves a list of access keys.

Parameters

params
object
1 subfields

Returns

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

verifyAccessKey#

Verifies if an access key is valid.

Parameters

params
object
required
1 subfields

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.

Services
Notification Service