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.
- type string — The installation type. Can be 'store', 'url', or 'upload'.
- did string — The DID of the blocklet to install (required for store installations).
- storeUrl string — The URL of the Blocklet Store.
- url string — The URL to the blocklet's meta file or bundle (required for URL installations).
- file Upload — The blocklet bundle file to upload.
- diffVersion string — The version to apply a diff against during an upgrade.
- deleteSet string[] — A list of files to delete during a diff-based upgrade.
- title string — A custom title for the new blocklet instance.
- description string — A custom description for the new blocklet instance.
- startImmediately boolean — If true, the blocklet will be started automatically after installation.
- downloadTokenList DownloadTokenInput[] — A list of download tokens for private components.
  - did string (required) — The DID of the component requiring a token.
  - token string (required) — The download token.

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.
- did string (required) — The root DID of the blocklet.
- componentDids string[] — An optional array of component DIDs to start. If omitted, all components will be started.

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.
- did string (required) — The root DID of the blocklet.
- componentDids string[] — An optional array of component DIDs to stop. If omitted, all running components will be stopped.

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.
- did string (required) — The root DID of the blocklet.
- componentDids string[] — An optional array of component DIDs to reload. If omitted, all reloadable components will be reloaded.

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.
- did string (required) — The root DID of the blocklet.
- componentDids string[] — An optional array of component DIDs to restart. If omitted, all components will be restarted.

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.
- did string (required) — The root DID of the blocklet to delete.
- keepData boolean (default: false) — If true, the blocklet's data directory will be preserved.

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.
- did string (required) — The root DID of the blocklet whose download should be canceled.

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.
- rootDid string (required) — The root DID of the parent blocklet.
- mountPoint string (required) — The path where the component will be mounted.
- url string — The URL to the component's meta file or bundle.
- did string — The DID of the component to install.
- title string — A custom title for the component.
- configs ConfigEntryInput[] — An array of initial configuration values for the component.

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.
- did string (required) — The DID of the component to delete.
- rootDid string (required) — The root DID of the parent blocklet.
- keepData boolean (default: false) — If true, the component's data will be preserved.

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.
- did string (required) — The root DID of the blocklet to check for updates.

Returns

preUpdateInfo object — Information about available updates.
- updateId string — A unique ID for this update session.
- updateList UpdateList[] — A list of components with available updates.
  - id string — The DID of the component.
  - meta BlockletMeta — The metadata of the new version.

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.
- updateId string (required) — The update session ID from checkComponentsForUpdates.
- rootDid string (required) — The root DID of the blocklet.
- selectedComponents string[] (required) — An array of component DIDs to upgrade.

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.
- did string[] (required) — An array containing the root DID and optionally a component DID.
- configs ConfigEntryInput[] (required) — An array of configuration objects to update.
  - key string (required) — The environment variable name.
  - value string (required) — The new value for the variable.

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.
- did string (required) — The DID of the blocklet to update.
- enableSessionHardening boolean — Enable or disable session hardening for enhanced security.
- invite InviteSettingsInput — Settings related to user invitations.
  - enabled boolean — Enable or disable the invitation feature.
- gateway BlockletGatewayInput — Configuration for the blocklet's gateway, including rate limiting and security policies.
- aigne AigneConfigInput — Configuration for the AIGNE service integration.

updateAutoBackup

Enables or disables the automatic backup feature for a blocklet.

Parameters

input object (required) — The input object for the updateAutoBackup mutation.
- did string (required) — The DID of the blocklet.
- autoBackup AutoBackupInput (required) — The auto-backup configuration.
  - enabled boolean (required) — Set to true to enable automatic backups, false to disable.

updateAutoCheckUpdate

Enables or disables the automatic check for updates feature for a blocklet.

Parameters

input object (required) — The input object for the updateAutoCheckUpdate mutation.
- did string (required) — The DID of the blocklet.
- autoCheckUpdate AutoCheckUpdateInput (required) — The auto-check-update configuration.
  - enabled boolean (required) — Set to true to enable automatic update checks, false to disable.

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.
- name string — The new name for the node.
- description string — The new description for the node.
- autoUpgrade boolean — Enable or disable automatic node upgrades.
- enableWelcomePage boolean — Enable or disable the welcome page.
- webWalletUrl string — The URL of the web wallet to be used with the node.
- enableBetaRelease boolean — Enable or disable the beta release channel for updates.

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.
- sessionId string — An optional session ID for tracking the upgrade process.

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.
- owner boolean — Reset the node owner.
- blocklets boolean — Delete all installed blocklets.
- webhooks boolean — Delete all webhooks.
- certificates boolean — Delete all SSL certificates.
- accessKeys boolean — Delete all access keys.
- routingRules boolean — Delete all routing rules.
- users boolean — Delete all users except the owner.
- invitations boolean — Delete all pending invitations.

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"
}