Node & Blocklet Management

This section provides a detailed reference for mutations related to managing the lifecycle and configuration of the Blocklet Server node and the blocklets running on it. These operations allow you to programmatically install, start, stop, configure, and upgrade both individual blocklets and the node itself.
Blocklet Lifecycle#These mutations control the fundamental lifecycle of a blocklet, from installation to removal.
installBlocklet#Installs a new blocklet onto the node from various sources like a store, a URL, or a local file.
Parameters
input
object
required
The input object for the installBlocklet mutation.
11 subfields
Example: Install from Store
Install from Store
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function installMyBlocklet() {
  try {
    const { blocklet } = await client.installBlocklet({
      input: {
        did: 'z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf',
        storeUrl: 'https://store.blocklet.dev',
        startImmediately: true,
      },
    });
    console.log(`Blocklet '${blocklet.meta.title}' installed successfully.`);
  } catch (error) {
    console.error('Failed to install blocklet:', error);
  }
}

installMyBlocklet();
Example Response
Response
{
  "code": "ok",
  "blocklet": {
    "meta": {
      "did": "z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf",
      "name": "@blocklet/did-wallet-adapter",
      "version": "1.16.111",
      "title": "DID Wallet Adapter"
    },
    "status": "installed",
    "appDid": "z12A1B...",
    "appPid": "z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf"
  }
}
This example installs the DID Wallet Adapter blocklet from the official store and starts it immediately. The response contains the complete state object of the newly installed blocklet.
startBlocklet#Starts one or more components of a blocklet that are currently in a stopped or error state.
Parameters
input
object
required
The input object for the startBlocklet mutation.
2 subfields
Example
Start a Blocklet
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();
const blockletDid = 'z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf';

async function startMyBlocklet() {
  try {
    const { blocklet } = await client.startBlocklet({
      input: { did: blockletDid },
    });
    console.log(`Blocklet '${blocklet.meta.title}' is now ${blocklet.status}.`);
  } catch (error) {
    console.error('Failed to start blocklet:', error);
  }
}

startMyBlocklet();
Example Response
Response
{
  "code": "ok",
  "blocklet": {
    "meta": {
      "did": "z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf"
    },
    "status": "running"
    // ... other properties
  }
}
stopBlocklet#Stops one or more running components of a blocklet.
Parameters
input
object
required
The input object for the stopBlocklet mutation.
2 subfields
Example
Stop a Blocklet
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();
const blockletDid = 'z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf';

async function stopMyBlocklet() {
  try {
    const { blocklet } = await client.stopBlocklet({
      input: { did: blockletDid },
    });
    console.log(`Blocklet '${blocklet.meta.title}' is now ${blocklet.status}.`);
  } catch (error) {
    console.error('Failed to stop blocklet:', error);
  }
}

stopMyBlocklet();
Example Response
Response
{
  "code": "ok",
  "blocklet": {
    "meta": {
      "did": "z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf"
    },
    "status": "stopped"
    // ... other properties
  }
}
reloadBlocklet#Reloads one or more running components of a blocklet, applying any code changes without a full restart. This is often faster than a restart.
Parameters
input
object
required
The input object for the reloadBlocklet mutation.
2 subfields
Example
Reload a Blocklet
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();
const blockletDid = 'z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf';

async function reloadMyBlocklet() {
  try {
    const { blocklet } = await client.reloadBlocklet({
      input: { did: blockletDid },
    });
    console.log(`Blocklet '${blocklet.meta.title}' has been reloaded.`);
  } catch (error) {
    console.error('Failed to reload blocklet:', error);
  }
}

reloadMyBlocklet();
Example Response
Response
{
  "code": "ok",
  "blocklet": {
    "meta": {
      "did": "z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf"
    },
    "status": "running"
    // ... other properties
  }
}
restartBlocklet#Restarts one or more components of a blocklet. This is equivalent to stopping and then starting them.
Parameters
input
object
required
The input object for the restartBlocklet mutation.
2 subfields
Example
Restart a Blocklet
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();
const blockletDid = 'z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf';

async function restartMyBlocklet() {
  try {
    const { blocklet } = await client.restartBlocklet({
      input: { did: blockletDid },
    });
    console.log(`Blocklet '${blocklet.meta.title}' has been restarted.`);
  } catch (error) {
    console.error('Failed to restart blocklet:', error);
  }
}

restartMyBlocklet();
Example Response
Response
{
  "code": "ok",
  "blocklet": {
    "meta": {
      "did": "z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf"
    },
    "status": "running"
    // ... other properties
  }
}
deleteBlocklet#Permanently removes a blocklet and its components from the node.
Parameters
input
object
required
The input object for the deleteBlocklet mutation.
2 subfields
Example
Delete a Blocklet
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();
const blockletDid = 'z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf';

async function deleteMyBlocklet() {
  try {
    await client.deleteBlocklet({ input: { did: blockletDid } });
    console.log('Blocklet deleted successfully.');
  } catch (error) {
    console.error('Failed to delete blocklet:', error);
  }
}

deleteMyBlocklet();
Example Response
Response
{
  "code": "ok",
  "blocklet": {
    "meta": {
      "did": "z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf"
    },
    "status": "deleted"
    // ... other properties
  }
}
cancelDownloadBlocklet#Cancels an in-progress blocklet download.
Parameters
input
object
required
The input object for the cancelDownloadBlocklet mutation.
1 subfields
Example
Cancel a Download
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();
const blockletDid = 'z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf';

async function cancelDownload() {
  try {
    const { blocklet } = await client.cancelDownloadBlocklet({ input: { did: blockletDid } });
    console.log(`Download for blocklet '${blocklet.meta.title}' cancelled.`);
  } catch (error) {
    console.error('Failed to cancel download:', error);
  }
}

cancelDownload();
Component Management#These mutations are used to manage the components within a blocklet, including installation, upgrades, and configuration changes.
installComponent#Installs a new component into an existing blocklet.
Parameters
input
object
required
The input object for the installComponent mutation.
6 subfields
Example
Install a Component
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();
const rootBlockletDid = 'z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf';

async function installNewComponent() {
  try {
    const { blocklet } = await client.installComponent({
      input: {
        rootDid: rootBlockletDid,
        mountPoint: '/new-component',
        did: 'z8ibCciF3uW9i9f9tQ5A7n9e3s2W4f8Y6z1x',
        title: 'My New Component',
      },
    });
    console.log('Component installed successfully.');
  } catch (error) {
    console.error('Failed to install component:', error);
  }
}

installNewComponent();
deleteComponent#Permanently removes a component from a blocklet.
Parameters
input
object
required
The input object for the deleteComponent mutation.
3 subfields
Example
Delete a Component
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();
const rootBlockletDid = 'z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf';
const componentDid = 'z8ibCciF3uW9i9f9tQ5A7n9e3s2W4f8Y6z1x';

async function deleteMyComponent() {
  try {
    await client.deleteComponent({
      input: { did: componentDid, rootDid: rootBlockletDid },
    });
    console.log('Component deleted successfully.');
  } catch (error) {
    console.error('Failed to delete component:', error);
  }
}

deleteMyComponent();
checkComponentsForUpdates#Checks for available updates for the components within a blocklet.
Parameters
input
object
required
The input object for the checkComponentsForUpdates mutation.
1 subfields
Returns
preUpdateInfo
object
Information about available updates.
2 subfields
Example
Check for Updates
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();
const blockletDid = 'z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf';

async function checkUpdates() {
  try {
    const { preUpdateInfo } = await client.checkComponentsForUpdates({ input: { did: blockletDid } });
    if (preUpdateInfo.updateList.length > 0) {
      console.log('Updates available:', preUpdateInfo.updateList);
    } else {
      console.log('All components are up to date.');
    }
  } catch (error) {
    console.error('Failed to check for updates:', error);
  }
}

checkUpdates();
upgradeComponents#Upgrades selected components to their latest versions based on an updateId from checkComponentsForUpdates.
Parameters
input
object
required
The input object for the upgradeComponents mutation.
3 subfields
Example
Upgrade Components
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();
const updateId = '...'; // from checkComponentsForUpdates
const rootDid = 'z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf';
const componentsToUpgrade = ['z8ibCciF3uW9i9f9tQ5A7n9e3s2W4f8Y6z1x'];

async function performUpgrade() {
  try {
    await client.upgradeComponents({
      input: {
        updateId,
        rootDid,
        selectedComponents: componentsToUpgrade,
      },
    });
    console.log('Components upgraded successfully.');
  } catch (error) {
    console.error('Failed to upgrade components:', error);
  }
}

performUpgrade();
updateComponentTitle#Updates the display title of a specific component within a blocklet.
Parameters
did
string
required
The DID of the component to update.
rootDid
string
required
The root DID of the parent blocklet.
title
string
required
The new title for the component.
updateComponentMountPoint#Changes the URL path (mount point) for a specific component within a blocklet.
Parameters
did
string
required
The DID of the component to update.
rootDid
string
required
The root DID of the parent blocklet.
mountPoint
string
required
The new mount point for the component (e.g., '/new-path').
Configuration & Settings#These mutations handle the dynamic configuration of blocklets and the node.
configBlocklet#Updates the configuration (environment variables) for a blocklet or one of its components.
Parameters
input
object
required
The input object for the configBlocklet mutation.
2 subfields
Example
Configure a Blocklet
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();
const blockletDid = 'z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf';

async function updateConfiguration() {
  try {
    await client.configBlocklet({
      input: {
        did: [blockletDid],
        configs: [
          { key: 'API_ENDPOINT', value: 'https://api.new.com' },
          { key: 'API_KEY', value: 'new-secret-key' },
        ],
      },
    });
    console.log('Blocklet configuration updated.');
  } catch (error) {
    console.error('Failed to configure blocklet:', error);
  }
}

updateConfiguration();
updateBlockletSettings#Updates various settings for a specific blocklet, such as gateway policies, invite settings, and AI service configurations.
Parameters
input
object
required
The input object for the updateBlockletSettings mutation.
5 subfields
updateAutoBackup#Enables or disables the automatic backup feature for a blocklet.
Parameters
input
object
required
The input object for the updateAutoBackup mutation.
2 subfields
updateAutoCheckUpdate#Enables or disables the automatic check for updates feature for a blocklet.
Parameters
input
object
required
The input object for the updateAutoCheckUpdate mutation.
2 subfields
Node Management#These mutations are used to manage the Blocklet Server node itself.
updateNodeInfo#Updates the general information and settings for the Blocklet Server node.
Parameters
input
object
required
The input object for the updateNodeInfo mutation.
6 subfields
Example
Configure Node
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function configureNode() {
  try {
    const { info } = await client.updateNodeInfo({
      input: {
        name: 'My Production Node',
        autoUpgrade: true,
      },
    });
    console.log(`Node name updated to: ${info.name}`);
  } catch (error) {
    console.error('Failed to update node info:', error);
  }
}

configureNode();
Example Response
Response
{
  "code": "ok",
  "info": {
    "did": "z12A1B...",
    "name": "My Production Node",
    "autoUpgrade": true
    // ... other properties
  }
}
upgradeNodeVersion#Initiates an upgrade of the Blocklet Server to the next available version.
Parameters
input
object
The input object for the upgradeNodeVersion mutation.
1 subfields
Example
Upgrade Node
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function upgradeMyNode() {
  try {
    const { sessionId } = await client.upgradeNodeVersion({});
    console.log(`Node upgrade started with session ID: ${sessionId}`);
  } catch (error) {
    console.error('Failed to start node upgrade:', error);
  }
}

upgradeMyNode();
Example Response
Response
{
  "code": "ok",
  "sessionId": "unique-session-id-for-upgrade"
}
restartServer#Restarts the Blocklet Server daemon. This will temporarily interrupt all running blocklets and services.
Example
Restart Server
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function restartMyServer() {
  try {
    const { sessionId } = await client.restartServer();
    console.log(`Server restart initiated with session ID: ${sessionId}`);
  } catch (error) {
    console.error('Failed to restart server:', error);
  }
}

restartMyServer();
Example Response
Response
{
  "code": "ok",
  "sessionId": "unique-session-id-for-restart"
}
resetNode#Resets various parts of the node's configuration and data. This is a destructive operation and should be used with caution.
Parameters
input
object
required
The input object for the resetNode mutation.
8 subfields
Example
Reset Node Data
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function resetNodeData() {
  try {
    await client.resetNode({
      input: {
        blocklets: true,
        users: true,
      },
    });
    console.log('Node blocklets and users have been reset.');
  } catch (error) {
    console.error('Failed to reset node:', error);
  }
}

resetNodeData();
Example Response
Response
{
  "code": "ok"
}
restartAllContainers#Restarts all running Docker containers managed by the Blocklet Server. This is useful for applying system-wide changes that affect the Docker environment.
Example
Restart All Containers
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function restartContainers() {
  try {
    const { sessionId } = await client.restartAllContainers();
    console.log(`Restarting all containers with session ID: ${sessionId}`);
  } catch (error) {
    console.error('Failed to restart containers:', error);
  }
}

restartContainers();
Example Response
Response
{
  "code": "ok",
  "sessionId": "unique-session-id-for-restart-all"
}
Overview

Getting Started

Authentication

API Reference

Advanced Usage

Node & Blocklet Management

Blocklet Lifecycle#

installBlocklet#

startBlocklet#

stopBlocklet#

reloadBlocklet#

restartBlocklet#

deleteBlocklet#

cancelDownloadBlocklet#

Component Management#

installComponent#

deleteComponent#

checkComponentsForUpdates#

upgradeComponents#

updateComponentTitle#

updateComponentMountPoint#

Configuration & Settings#

configBlocklet#

updateBlockletSettings#

updateAutoBackup#

updateAutoCheckUpdate#

Node Management#

updateNodeInfo#

upgradeNodeVersion#

restartServer#

resetNode#

restartAllContainers#

Mutations

User & Access Management
