Quick Start
This guide will walk you through the initial setup of the DID Spaces SDK, from installation to executing your first command. For a broader understanding of the SDK's capabilities, refer to the Overview or delve deeper into its foundational elements in Core Concepts.
Installation#
To begin, install the @blocklet/did-space-js package using your preferred package manager:
npm install @blocklet/did-space-js
# yarn add @blocklet/did-space-js
# pnpm add @blocklet/did-space-jsClient Initialization#
The core of interacting with DID Spaces is the SpaceClient. Initialize it with your DID Wallet and the DID Space endpoint. The SpaceClient constructor accepts an options object to configure its behavior.
Parameters for SpaceClientOptions
Name | Type | Description |
|---|---|---|
|
| Required. Your DID Wallet object, used for signing requests to authenticate with the DID Space. |
|
| Required. The base URL of your DID Space application service. Example: |
|
| Optional. A JWT token that certifies the requester is authorized to access the space on behalf of another DID. |
|
| Optional. The DID of the component interacting with the DID Space. |
|
| Optional. An |
Example: Initialize SpaceClient
import { SpaceClient } from '@blocklet/did-space-js';
import { createRandomWallet } from '@ocap/wallet'; // Example: create a random wallet for demonstration
// Replace with your actual wallet and DID Space endpoint
const wallet = createRandomWallet();
const endpoint = 'https://your-did-space-url/app/api/space/your-space-did/app/your-app-did/';
const spaceClient = new SpaceClient({
wallet,
endpoint,
});
console.log('SpaceClient initialized successfully.');Executing Your First Command: Put Object#
The SpaceClient.send() method is the primary way to execute operations against your DID Space. It takes a CommandProtocol instance, which encapsulates the specific operation (e.g., uploading an object, listing files, creating backups).
Let's demonstrate by uploading a simple text file using the PutObjectCommand.
Parameters for PutObjectCommandInput
Name | Type | Description |
|---|---|---|
|
| Required. The path of the object within the DID Space. Can be a filename or a folder path (ending with |
|
| Optional. The content of the file to be uploaded. Can be a string, Node.js |
|
| Optional. The hash value of the object, expected to be an IPFS CIDv1 hash. |
|
| Optional. A record of key-value pairs for custom metadata associated with the object. |
Returns for PutObjectCommandOutput
Name | Type | Description |
|---|---|---|
|
| The HTTP status code of the operation (e.g., |
|
| An optional message, typically present if an error occurred. |
|
| This command returns no specific data on success. |
Example: Upload a File to DID Space
import { SpaceClient, PutObjectCommand } from '@blocklet/did-space-js';
import { createRandomWallet } from '@ocap/wallet';
import { Buffer } from 'buffer'; // Node.js Buffer for content
async function uploadFile() {
const wallet = createRandomWallet();
// IMPORTANT: Replace with your actual DID Space endpoint
const endpoint = 'https://your-did-space-url/app/api/space/your-space-did/app/your-app-did/';
const spaceClient = new SpaceClient({
wallet,
endpoint,
});
const fileContent = 'Hello, DID Spaces! This is my first file.';
const fileKey = '/my-first-file.txt'; // Path within your DID Space
try {
const command = new PutObjectCommand({
key: fileKey,
data: Buffer.from(fileContent, 'utf-8'), // Content as a Buffer
metadata: {
contentType: 'text/plain',
uploadedBy: wallet.address,
},
});
const result = await spaceClient.send(command);
if (result.statusCode === 200) {
console.log(`Successfully uploaded '${fileKey}' to DID Space.`);
} else {
console.error(`Failed to upload '${fileKey}': ${result.statusMessage || 'Unknown error'}`);
}
} catch (error) {
console.error('An error occurred during file upload:', error);
}
}
uploadFile();This example initializes the SpaceClient and then uses the PutObjectCommand to upload a simple text file named /my-first-file.txt with some associated metadata. The send method executes the command and returns a CommandOutput containing the operation's status.
Next Steps#
You have successfully set up the DID Spaces SDK and executed your first command. To explore more advanced features and commands, refer to the Commands Reference.