Client
The SpaceClient serves as the primary interface for developers to interact with DID Spaces. It simplifies operations by managing configuration, handling command execution, and standardizing error responses. This section details how to initialize the SpaceClient and utilize its core send method to perform various operations.
For an overview of the foundational SDK components, refer to Core Concepts. For a comprehensive guide on all available operations, see the Commands Reference.
Client Overview#
At its core, the SpaceClient acts as an orchestrator, taking your desired operations (commands) and executing them securely against your configured DID Space endpoint. It ensures that all requests are properly formatted, authenticated, and that responses are consistently handled.
Initializing the Client#
To begin interacting with DID Spaces, you must first create an instance of the SpaceClient. The constructor requires an options object of type SpaceClientOptions.
Parameters for SpaceClientOptions
Name | Type | Description | Required |
|---|---|---|---|
|
| The wallet object used for signing requests, typically a Blocklet Wallet instance. | Yes |
|
| The URL of your DID Space endpoint. Example: | Yes |
|
| An optional JWT token that certifies the requester is authorized to access the space. | No |
|
| An optional component DID for specific scenarios. | No |
|
| An optional | No |
Example: Initializing SpaceClient
import { SpaceClient } from '@arcblock/did-spaces-client';
import { Wallet } from '@ocap/wallet'; // Assuming @ocap/wallet is used for WalletObject
// Replace with your actual DID Space endpoint and wallet details
const WALLET_SK = '...your_wallet_secret_key...';
const SPACE_ENDPOINT = 'https://your-space.did.abtnet.io/app/api/space/spaceDid/app/appDid/';
const wallet = new Wallet({ sk: WALLET_SK });
const client = new SpaceClient({
wallet,
endpoint: SPACE_ENDPOINT,
// delegation: 'optional_delegation_token',
// componentDid: 'optional_component_did',
});
console.log('SpaceClient initialized successfully.');This example demonstrates how to create a new SpaceClient instance using a WalletObject and your DID Space endpoint. Ensure you replace the placeholder values with your actual secret key and endpoint.
Sending Commands with send()#
The send method is the primary way to execute any operation against DID Spaces. It takes a CommandProtocol instance as an argument, which encapsulates the specific input and context for the desired operation.
Parameters
Name | Type | Description |
|---|---|---|
|
| An instance of a command class (e.g., |
Returns
Name | Type | Description |
|---|---|---|
|
| The HTTP status code of the response. |
|
| A message describing the status, typically present on errors. |
|
| The error stack trace, typically present on errors. |
|
| The payload of the response, varying by command. |
|
| The raw |
Example: Sending PutNftObjectCommand
import { SpaceClient } from '@arcblock/did-spaces-client';
import { PutNftObjectCommand } from '@arcblock/did-spaces-client/commands/nft';
import { Wallet } from '@ocap/wallet';
import { readFileSync } from 'fs';
import path from 'path';
const WALLET_SK = '...your_wallet_secret_key...';
const SPACE_ENDPOINT = 'https://your-space.did.abtnet.io/app/api/space/spaceDid/app/appDid/';
const wallet = new Wallet({ sk: WALLET_SK });
const client = new SpaceClient({ wallet, endpoint: SPACE_ENDPOINT });
async function uploadNftObject() {
try {
const filePath = path.resolve(__dirname, './my-nft-image.png'); // Path to your NFT image
const fileContent = readFileSync(filePath);
const command = new PutNftObjectCommand({
key: '/nfts/my-first-nft.png', // The path within your DID Space
data: fileContent,
mimeType: 'image/png',
metadata: { description: 'My first NFT image on DID Space' },
});
const result = await client.send(command);
console.log('NFT object uploaded successfully:', result.data);
console.log('Status Code:', result.statusCode);
} catch (error) {
console.error('Error uploading NFT object:', error.message);
}
}
uploadNftObject();This example demonstrates using the send method to upload an NFT object to your DID Space. It initializes a PutNftObjectCommand with the object's key, data, MIME type, and optional metadata, then executes it via the SpaceClient.
:::caution Deprecated Method
Previously, some specific operations like putNftObject were directly exposed on the SpaceClient. These methods are now deprecated. Always use the generic send method with the appropriate command class for future compatibility and a consistent API experience.
:::
Endpoint Utilities#
The SpaceClient also provides static helper methods to work with DID Space endpoints. These utilities can help in parsing and normalizing endpoint URLs.
SpaceClient.getBaseUrl(endpoint: string): Returns the base URL of the DID Space endpoint.SpaceClient.getDisplayUrl(endpoint: string, did: string = ''): Constructs a display URL for a given DID within the space.SpaceClient.getSpaceEndpointContext(endpoint: string): Extracts structured context (base URL, space DID, app DID) from an endpoint.
Example: Using Endpoint Utilities
import { SpaceClient } from '@arcblock/did-spaces-client';
const SPACE_ENDPOINT = 'https://example-space.did.abtnet.io/app/api/space/z3T6WZD3dBtaVUgwb3rtBey8BartrJDTLrmQr/app/zNKsSUmUVJntiVdAPpg8vYtEgnFvSppYLf4F/object/';
async function demonstrateEndpointUtilities() {
try {
const baseUrl = await SpaceClient.getBaseUrl(SPACE_ENDPOINT);
console.log('Base URL:', baseUrl); // Expected: https://example-space.did.abtnet.io/app
const displayUrl = await SpaceClient.getDisplayUrl(SPACE_ENDPOINT, 'did:abt:zNKsSUmUVJntiVdAPpg8vYtEgnFvSppYLf4F');
console.log('Display URL:', displayUrl); // Expected: https://example-space.did.abtnet.io/app/resolve/did:abt:zNKsSUmUVJntiVdAPpg8vYtEgnFvSppYLf4F/display
const context = await SpaceClient.getSpaceEndpointContext(SPACE_ENDPOINT);
console.log('Space Endpoint Context:', context);
// Expected: { baseUrl: 'https://example-space.did.abtnet.io/app', spaceDid: 'z3T6WZD3dBtaVUgwb3rtBey8BartrJDTLrmQr', appDid: 'zNKsSUmUVJntiVdAPpg8vYtEgnFvSppYLf4F' }
} catch (error) {
console.error('Error using endpoint utilities:', error.message);
}
}
demonstrateEndpointUtilities();These utilities help developers programmatically extract and construct various URLs related to a DID Space endpoint, useful for dynamic application scenarios.
This section provided a detailed overview of the SpaceClient, its initialization, and the core send method for interacting with DID Spaces. You are now equipped to set up the client and begin executing commands. Proceed to the Commands Reference to explore the full range of operations available.