Node & Blocklet Management
This section provides a detailed reference for GraphQL queries used to manage and retrieve information about the Blocklet Server node and the blocklets it runs. These queries allow you to monitor status, fetch configuration, and access lifecycle information.
For operations that modify state, such as installing or starting a blocklet, refer to the Mutations > Node & Blocklet Management documentation.
Node Information Queries#
These queries provide information about the Blocklet Server instance itself.
getNodeInfo#
Fetches comprehensive state information about the current Blocklet Server node, including its DID, version, status, and configuration.
Returns
A promise that resolves to an object containing the node's state information.
Example
import BlockletServerClient from '@blocklet/server-js';
const client = new BlockletServerClient();
async function fetchNodeInfo() {
try {
const response = await client.getNodeInfo();
console.log('Node Info:', response.info);
} catch (error) {
console.error('Error fetching node info:', error);
}
}
fetchNodeInfo();Example Response
{
"code": "ok",
"info": {
"did": "z1v7.....",
"pk": "...",
"version": "1.7.0",
"name": "My ABT Node",
"description": "This is my personal Blocklet Server.",
"initialized": true,
"autoUpgrade": true
// ... other NodeState properties
}
}getNodeEnv#
Retrieves environment details of the Blocklet Server, such as the operating system, IP addresses, Docker status, and available blocklet engines.
Returns
A promise that resolves to an object containing the node's environment information.
Example
async function fetchNodeEnv() {
try {
const response = await client.getNodeEnv();
console.log('Node Environment:', response.info);
} catch (error) {
console.error('Error fetching node environment:', error);
}
}
fetchNodeEnv();Example Response
{
"code": "ok",
"info": {
"ip": {
"externalV4": "192.0.2.1"
},
"os": "linux",
"docker": true,
"blockletEngines": [
{
"name": "node",
"version": "18.17.0",
"available": true
}
]
// ... other NodeEnvInfo properties
}
}checkNodeVersion#
Checks if a newer version of the Blocklet Server software is available for upgrade.
Returns
A promise that resolves to an object containing the latest available version, if any.
Example
async function checkForUpdates() {
try {
const response = await client.checkNodeVersion();
console.log('Latest available version:', response.version);
} catch (error) {
console.error('Error checking for updates:', error);
}
}
checkForUpdates();Example Response
{
"code": "ok",
"version": "1.7.1"
}getNodeRuntimeHistory#
Fetches historical runtime data, including CPU and memory usage, for the node over a specified period.
Parameters
Returns
A promise that resolves to an array of historical data points.
Example
async function fetchNodeHistory() {
try {
const response = await client.getNodeRuntimeHistory({ input: { hours: 24 } });
console.log('Node runtime history for the last 24 hours:', response.history);
} catch (error) {
console.error('Error fetching node runtime history:', error);
}
}
fetchNodeHistory();Example Response
{
"code": "ok",
"history": [
{
"date": 1672531200000,
"cpu": 15.5,
"mem": 2048.5
}
// ... other NodeHistoryItem data points
]
}getDelegationState#
Retrieves the delegation state of the node.
Returns
A promise that resolves to an object containing the delegation state.
Example
async function fetchDelegationState() {
try {
const response = await client.getDelegationState();
console.log('Delegation State:', response.state);
} catch (error) {
console.error('Error fetching delegation state:', error);
}
}
fetchDelegationState();Example Response
{
"code": "ok",
"state": {
"delegated": true
}
}resetNodeStatus#
Resets the status of the node.
Returns
A promise that resolves to an object containing the node's updated state information.
Example
async function resetStatus() {
try {
const response = await client.resetNodeStatus();
console.log('Node status reset:', response.info);
} catch (error) {
console.error('Error resetting node status:', error);
}
}
resetStatus();Example Response
{
"code": "ok",
"info": {
"did": "z1v7.....",
"pk": "...",
"version": "1.7.0",
"name": "My ABT Node",
"status": 0
// ... other NodeState properties
}
}Blocklet Information Queries#
These queries are used to fetch information about individual or multiple blocklets.
getBlocklet#
Retrieves the detailed state and metadata for a specific blocklet using its DID.
Parameters
Returns
A promise that resolves to an object containing the blocklet's state.
Example
async function fetchBlockletDetails(blockletDid) {
try {
const response = await client.getBlocklet({
input: {
did: blockletDid,
attachRuntimeInfo: true,
},
});
console.log('Blocklet Details:', response.blocklet);
} catch (error) {
console.error('Error fetching blocklet details:', error);
}
}
fetchBlockletDetails('z8ia...'); // Replace with a valid blocklet DIDExample Response
{
"code": "ok",
"blocklet": {
"meta": {
"did": "z8ia...",
"name": "my-awesome-blocklet",
"version": "1.0.0",
"title": "My Awesome Blocklet"
},
"status": "running",
"appDid": "z1s...",
"runtimeInfo": {
"cpuUsage": 5.2,
"memoryUsage": 128.7
}
// ... other BlockletState properties
}
}getBlocklets#
Fetches a list of all blocklets installed on the node.
Parameters
Returns
A promise that resolves to an object containing a list of all installed blocklets.
Example
async function listAllBlocklets() {
try {
const response = await client.getBlocklets();
console.log(`Found ${response.blocklets.length} blocklets.`);
response.blocklets.forEach(b => console.log(`- ${b.meta.title}`));
} catch (error) {
console.error('Error listing blocklets:', error);
}
}
listAllBlocklets();Example Response
{
"code": "ok",
"blocklets": [
{
"meta": { "did": "z8ia...", "title": "My Awesome Blocklet" },
"status": "running"
},
{
"meta": { "did": "z8ib...", "title": "Another Blocklet" },
"status": "stopped"
}
// ... other blocklets
]
}getBlockletMeta#
Retrieves blocklet metadata from a specified blocklet store using the blocklet's DID.
Parameters
Returns
A promise that resolves to an object containing the blocklet's metadata.
Example
async function fetchBlockletMeta(blockletDid) {
try {
const response = await client.getBlockletMeta({
input: {
did: blockletDid,
storeUrl: 'https://store.blocklet.dev',
},
});
console.log('Blocklet Metadata:', response.meta);
} catch (error) {
console.error('Error fetching blocklet metadata:', error);
}
}
fetchBlockletMeta('z8ia...'); // Replace with a valid blocklet DIDgetBlockletMetaFromUrl#
Fetches blocklet metadata directly from a registry URL. This is useful for inspecting a blocklet before installation.
Parameters
Returns
A promise that resolves to an object containing the metadata and other store-related info.
Example
async function fetchMetaFromUrl() {
try {
const response = await client.getBlockletMetaFromUrl({
input: { url: 'https://store.blocklet.dev/api/blocklets/z8ia...' },
});
console.log('Metadata from URL:', response.meta);
} catch (error) {
console.error('Error fetching metadata from URL:', error);
}
}
fetchMetaFromUrl();getBlockletRuntimeHistory#
Fetches historical runtime data (CPU and memory usage) for a specific blocklet.
Parameters
Returns
A promise that resolves to an array of historical data points.
Example
async function fetchBlockletHistory(blockletDid) {
try {
const response = await client.getBlockletRuntimeHistory({
input: { did: blockletDid, hours: 12 },
});
console.log('Blocklet runtime history:', response.historyList);
} catch (error) {
console.error('Error fetching blocklet runtime history:', error);
}
}
fetchBlockletHistory('z8ia...'); // Replace with a valid blocklet DIDgetBlockletDiff#
Compares local blocklet files with a provided hash list to identify added, changed, or deleted files. This is useful for incremental updates.
Parameters
Returns
A promise that resolves to an object detailing the differences.
Example
async function checkBlockletDiff(blockletDid) {
try {
const response = await client.getBlockletDiff({
input: {
did: blockletDid,
hashFiles: [
{ file: 'index.js', hash: '...' },
{ file: 'style.css', hash: '...' }
]
}
});
console.log('Blocklet Diff:', response.blockletDiff);
} catch (error) {
console.error('Error checking blocklet diff:', error);
}
}
checkBlockletDiff('z8ia...');getDynamicComponents#
Retrieves metadata for dynamic components from a given URL.
Parameters
Returns
A promise that resolves to a list of dynamic components.
Example
async function fetchDynamicComponents(registryUrl) {
try {
const response = await client.getDynamicComponents({ input: { url: registryUrl } });
console.log('Dynamic Components:', response.components);
} catch (error) {
console.error('Error fetching dynamic components:', error);
}
}
fetchDynamicComponents('https://store.blocklet.dev/api/components');getBlockletsFromBackup#
Lists available blocklets from a backup source.
Returns
A promise that resolves to a list of blocklets available in the backup.
Example
async function listBlockletsFromBackup() {
try {
const response = await client.getBlockletsFromBackup();
console.log('Blocklets from backup:', response.backups);
} catch (error) {
console.error('Error listing blocklets from backup:', error);
}
}
listBlockletsFromBackup();getBlockletBaseInfo#
Retrieves basic information for a blocklet, including user counts, passport stats, and the latest backup status.
Parameters
Returns
A promise that resolves to an object containing basic blocklet information.
Example
async function fetchBaseInfo(blockletDid) {
try {
const response = await client.getBlockletBaseInfo({ input: { teamDid: blockletDid } });
console.log('Base Info:', response);
} catch (error) {
console.error('Error fetching base info:', error);
}
}
fetchBaseInfo('z8ia...');Example Response
{
"user": {
"users": 10,
"approvedUsers": 8
},
"passport": {
"passports": 12,
"activePassports": 10
},
"backup": {
"appPid": "z8ia...",
"status": 1,
"updatedAt": 1672531200
}
}Now that you know how to query node and blocklet information, you can explore how to manage users and permissions in the User & Access Management section.