Skip to main content

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

  • response Promise<BlockletServerClient.ResponseGetNodeInfo> — A promise that resolves to an object containing the node's state information.

Example

javascript
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

json
{
  "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

  • response Promise<BlockletServerClient.ResponseGetNodeEnv> — A promise that resolves to an object containing the node's environment information.

Example

javascript
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

json
{
  "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

  • response Promise<BlockletServerClient.ResponseCheckNodeVersion> — A promise that resolves to an object containing the latest available version, if any.

Example

javascript
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

json
{
  "code": "ok",
  "version": "1.7.1"
}

getNodeRuntimeHistory

Fetches historical runtime data, including CPU and memory usage, for the node over a specified period.

Parameters

  • input object (required)
    • hours number (required) — The number of past hours for which to retrieve history.

Returns

  • response Promise<BlockletServerClient.ResponseNodeRuntimeHistory> — A promise that resolves to an array of historical data points.

Example

javascript
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

json
{
  "code": "ok",
  "history": [
    {
      "date": 1672531200000,
      "cpu": 15.5,
      "mem": 2048.5
    }
    // ... other NodeHistoryItem data points
  ]
}

getDelegationState

Retrieves the delegation state of the node.

Returns

  • response Promise<BlockletServerClient.ResponseDelegationState> — A promise that resolves to an object containing the delegation state.

Example

javascript
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

json
{
  "code": "ok",
  "state": {
    "delegated": true
  }
}

resetNodeStatus

Resets the status of the node.

Returns

  • response Promise<BlockletServerClient.ResponseGetNodeInfo> — A promise that resolves to an object containing the node's updated state information.

Example

javascript
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

json
{
  "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

  • input object (required)
    • did string (required) — The DID of the blocklet to retrieve.
    • attachRuntimeInfo boolean — If true, includes real-time CPU and memory usage. Defaults to false.
    • attachDiskInfo boolean — If true, includes disk usage information. Defaults to false.

Returns

  • response Promise<BlockletServerClient.ResponseBlocklet> — A promise that resolves to an object containing the blocklet's state.

Example

javascript
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 DID

Example Response

json
{
  "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

  • input object
    • includeRuntimeInfo boolean — If true, includes runtime info for each blocklet. Defaults to true.

Returns

  • response Promise<BlockletServerClient.ResponseGetBlocklets> — A promise that resolves to an object containing a list of all installed blocklets.

Example

javascript
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

json
{
  "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

  • input object (required)
    • did string (required) — The DID of the blocklet.
    • storeUrl string (required) — The URL of the blocklet store to query.

Returns

  • response Promise<BlockletServerClient.ResponseBlockletMeta> — A promise that resolves to an object containing the blocklet's metadata.

Example

javascript
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 DID

getBlockletMetaFromUrl

Fetches blocklet metadata directly from a registry URL. This is useful for inspecting a blocklet before installation.

Parameters

  • input object (required)
    • url string (required) — The registry URL of the blocklet metadata.

Returns

  • response Promise<BlockletServerClient.ResponseBlockletMetaFromUrl> — A promise that resolves to an object containing the metadata and other store-related info.

Example

javascript
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

  • input object (required)
    • did string (required) — The DID of the blocklet.
    • hours number (required) — The number of past hours to retrieve history for.

Returns

  • response Promise<BlockletServerClient.ResponseBlockletRuntimeHistory> — A promise that resolves to an array of historical data points.

Example

javascript
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 DID

getBlockletDiff

Compares local blocklet files with a provided hash list to identify added, changed, or deleted files. This is useful for incremental updates.

Parameters

  • input object (required)
    • did string (required) — The DID of the blocklet.
    • hashFiles HashFileInput[] (required) — An array of objects, each containing a file path and its hash.
    • rootDid string — The root blocklet DID if the target is a component.

Returns

  • response Promise<BlockletServerClient.ResponseBlockletDiff> — A promise that resolves to an object detailing the differences.

Example

javascript
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

  • input object (required)
    • url string (required) — The URL to fetch dynamic component metadata from.

Returns

  • response Promise<BlockletServerClient.ResponseGetDynamicComponents> — A promise that resolves to a list of dynamic components.

Example

javascript
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

  • response Promise<BlockletServerClient.ResponseBlockletsFromBackup> — A promise that resolves to a list of blocklets available in the backup.

Example

javascript
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

  • input object (required)
    • teamDid string (required) — The DID of the team/blocklet.

Returns

  • response Promise<BlockletServerClient.ResponseBlockletInfo> — A promise that resolves to an object containing basic blocklet information.

Example

javascript
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

json
{
  "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.