SpaceClient | ArcBlock

The SpaceClient is the primary interface for interacting with the DID Space API. It's the main entry point for the SDK, responsible for handling configuration, authentication, and dispatching commands to your DID Space.

Constructor

To begin, you need to create an instance of the SpaceClient. The constructor accepts a single options object to configure its behavior, including authentication credentials and endpoint details.

Client Initialization

import { SpaceClient } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';

const wallet = getWallet();

const client = new SpaceClient({
  auth: {
    wallet: wallet,
    endpoint: 'https://www.didspaces.com/app/api/space/...',
  },
});

Options (SpaceClientOptions)

The constructor accepts an object with the following properties:

auth object — The recommended way to provide authentication credentials. It can be one of several types.
- EndpointAuth object — Authentication using a wallet and a specific space endpoint.
  - wallet WalletObject (required) — The wallet object for signing requests, typically from '@blocklet/sdk/lib/wallet'.
  - endpoint string (required) — The full API endpoint for your DID Space application.
- AuthorizationAuth object — Authentication using a pre-generated authorization token.
  - authorization string (required) — The authorization token.
- AccessKeyAuth object — Authentication using a secret key.
  - secretKey string (required) — The secret access key.
wallet WalletObject (deprecated) — The wallet object. It is recommended to use the auth object instead.
endpoint string (deprecated) — The DID Space endpoint URL. It is recommended to use the auth object instead.
url string (default: https://www.didspaces.com) — The base URL for the DID Spaces service. The client automatically resolves the correct application mount point.
delegation string — A JWT token that certifies the requester is authorized to access the space.
componentDid string — The DID of the component making the request.
abortController AbortController — An AbortController instance to cancel in-flight requests.

Methods

send

The send method is the universal way to execute any command against your DID Space. You pass an instance of a command object, and it returns a promise that resolves with the command's output.

Sending a Command

import { SpaceClient, PutNftObjectCommand } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';
import { fileURLToPath } from 'url';
import path from 'path';
import fs from 'fs';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

async function uploadNft() {
  const wallet = getWallet();
  const client = new SpaceClient({
    auth: {
      wallet: wallet,
      endpoint: 'https://www.didspaces.com/app/api/space/...',
    },
  });

  const filePath = path.join(__dirname, 'my-nft-image.png');
  const fileStream = fs.createReadStream(filePath);
  const fileStat = fs.statSync(filePath);

  const command = new PutNftObjectCommand({
    name: 'My First NFT',
    description: 'This is a description of my NFT.',
    body: fileStream,
    contentLength: fileStat.size,
    contentType: 'image/png',
  });

  const output = await client.send(command);

  if (output.statusCode === 200) {
    console.log('NFT uploaded successfully!', output.data);
  } else {
    console.error('Upload failed:', output.statusMessage);
  }
}

uploadNft();

Parameters

command CommandProtocol<Input, Output> (required) — An instance of a command class, such as PutObjectCommand or ListObjectsCommand.

Returns

A Promise that resolves to the command's output object.

Output Promise<CommandOutput> — The result of the command execution.
- statusCode number (required) — The HTTP status code of the response (e.g., 200 for success).
- statusMessage string — An error message if the request failed.
- stack string — The stack trace if an error occurred.
- data any (required) — The data returned by the command, which varies depending on the command executed.

Static Methods

These are utility functions available directly on the SpaceClient class.

getBaseUrl

Extracts the base URL of a DID Space from a full endpoint URL.

import { SpaceClient } from '@blocklet/did-space-js';

const endpoint = 'https://.../app/api/space/z3T.../app/zNK.../object/';
const baseUrl = await SpaceClient.getBaseUrl(endpoint);
console.log(baseUrl); // 'https://.../app'

getDisplayUrl

Constructs a public-facing URL to view an object within a DID Space.

import { SpaceClient } from '@blocklet/did-space-js';

const endpoint = 'https://.../app/api/space/z3T.../app/zNK.../object/';
const objectDid = 'z3T...'; // The DID of the object
const displayUrl = await SpaceClient.getDisplayUrl(endpoint, objectDid);
console.log(displayUrl);
// 'https://.../app/resolve/z3T.../display'

getSpaceEndpointContext

Parses a full endpoint URL to extract contextual information like the Space DID and Application DID.

import { SpaceClient } from '@blocklet/did-space-js';

const endpoint =
  'https://.../api/space/z3T6WZD3dBtaVUgwb3rtBey8BartrJDTLrmQr/app/zNKsSUmUVJntiVdAPpg8vYtEgnFvSppYLf4F/object/';
const context = await SpaceClient.getSpaceEndpointContext(endpoint);

console.log(context.spaceDid); // 'z3T6WZD3dBtaVUgwb3rtBey8BartrJDTLrmQr'
console.log(context.appDid); // 'zNKsSUmUVJntiVdAPpg8vYtEgnFvSppYLf4F'

Returns

A Promise resolving to a SpaceEndpointContext object.

context Promise<SpaceEndpointContext> — Contextual information parsed from the endpoint.
baseUrl string (required) — The base URL of the space.
spaceDid string (required) — The DID of the space.
appDid string (required) — The DID of the application within the space.

Next Steps

Now that you know how to initialize the client and send commands, you can explore the available commands for interacting with your space:

Object Commands

Learn how to perform CRUD operations on individual files (objects).

Sync Commands

Discover high-level commands for synchronizing local and remote folders.