Getting Started

Welcome to the DID Space Client SDK! This guide will walk you through the essential steps to get the SDK installed, configured, and to perform your first file upload. You'll be up and running in just a few minutes.

Prerequisites#

Before you begin, ensure you have the following:

Step 1: Install the SDK#

First, add the @blocklet/did-space-js package to your project using your preferred package manager.

Install with npm

npm install @blocklet/did-space-js

Install with yarn

yarn add @blocklet/did-space-js

Step 2: Initialize the SpaceClient#

The SpaceClient is the main entry point for interacting with the SDK. To initialize it, you need to provide authentication credentials. In a Blocklet environment, the easiest way is to use the current Blocklet's wallet and your space endpoint.

Initialize Client

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

// This retrieves the wallet managed by the Blocklet environment.
const wallet = getWallet();

// Replace with your actual DID Space endpoint.
const endpoint = 'https://your-space-endpoint.did.abtnet.io/api/space/...';

const spaceClient = new SpaceClient({
  auth: {
    wallet,
    endpoint,
  },
});

Step 3: Upload a File#

With the client initialized, you can now send commands. We'll use the PutObjectCommand to upload a simple text file.

Commands follow a consistent pattern: you create an instance of the command with its required input, then pass it to the spaceClient.send() method.

The send method returns an output object containing the status of the request. A statusCode of 200 indicates success.

Upload a File

import { PutObjectCommand } from '@blocklet/did-space-js';
import { Buffer } from 'buffer';

async function uploadFile() {
  const command = new PutObjectCommand({
    // The name of the file (or object key) in your DID Space.
    key: 'greeting.txt',
    // The content of the file. It's best to use a Buffer.
    data: Buffer.from('Hello from the DID Space SDK!'),
  });

  const output = await spaceClient.send(command);

  if (output.statusCode === 200) {
    console.log('Success! Your file has been uploaded.');
  } else {
    console.error(`Upload failed with status ${output.statusCode}: ${output.statusMessage}`);
  }
}

uploadFile();

Complete Example#

Here is a complete, ready-to-run example that combines all the steps above. You can place this code inside an async function in your Blocklet project.

Full Example

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

async function run() {
  // 1. Initialize the client
  const wallet = getWallet();
  const endpoint = 'https://your-space-endpoint.did.abtnet.io/api/space/...'; // TODO: Replace with your endpoint

  const spaceClient = new SpaceClient({
    auth: {
      wallet,
      endpoint,
    },
  });

  console.log('Client initialized. Preparing to upload file...');

  // 2. Create and send the upload command
  const command = new PutObjectCommand({
    key: 'greeting.txt',
    data: Buffer.from('Hello from the DID Space SDK!'),
  });

  const output = await spaceClient.send(command);

See all 11 lines

After running this code, you should see the greeting.txt file in your DID Space.

Next Steps#

Congratulations! You've successfully uploaded your first file using the DID Space Client SDK.

Now that you have the basics down, you can explore more advanced topics:

Overview
Core Concepts