SpaceClient | ArcBlock

SpaceClient 是與 DID Space API 互動的主要介面。它是 SDK 的主要入口點，負責處理設定、身份驗證以及向您的 DID Space 發送命令。

建構函式

首先，您需要建立一個 SpaceClient 的實例。建構函式接受一個 options 物件來設定其行為，包括身份驗證憑證和端點詳細資訊。

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/...',
  },
});

選項 (SpaceClientOptions)

建構函式接受一個具有以下屬性的物件：

auth object — 提供身份驗證憑證的建議方式。它可以是多種類型之一。
- EndpointAuth object — 使用錢包和特定空間端點進行身份驗證。
  - wallet WalletObject (required) — 用於簽署請求的錢包物件，通常來自 '@blocklet/sdk/lib/wallet'。
  - endpoint string (required) — 您的 DID Space 應用程式的完整 API 端點。
- AuthorizationAuth object — 使用預先產生的授權權杖進行身份驗證。
  - authorization string (required) — 授權權杖。
- AccessKeyAuth object — 使用密鑰進行身份驗證。
  - secretKey string (required) — 秘密存取金鑰。
wallet WalletObject (deprecated) — 錢包物件。建議改用 auth 物件。
endpoint string (deprecated) — DID Space 端點 URL。建議改用 auth 物件。
url string (default: https://www.didspaces.com) — DID Spaces 服務的基礎 URL。客戶端會自動解析正確的應用程式掛載點。
delegation string — 一個 JWT 權杖，證明請求者有權存取該空間。
componentDid string — 發出請求的元件的 DID。
abortController AbortController — 一個 AbortController 實例，用於取消進行中的請求。

方法

send

send 方法是針對您的 DID Space 執行任何命令的通用方式。您傳入一個命令物件的實例，它會傳回一個 promise，該 promise 會解析為命令的輸出。

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();

參數

command CommandProtocol<Input, Output> (required) — 一個命令類別的實例，例如 PutObjectCommand 或 ListObjectsCommand。

傳回值

一個解析為命令輸出物件的 Promise。

Output Promise<CommandOutput> — 命令執行的結果。
- statusCode number (required) — 回應的 HTTP 狀態碼（例如，200 代表成功）。
- statusMessage string — 如果請求失敗，則為錯誤訊息。
- stack string — 如果發生錯誤，則為堆疊追蹤。
- data any (required) — 命令傳回的資料，其內容因執行的命令而異。

靜態方法

這些是可直接在 SpaceClient 類別上使用的工具函式。

getBaseUrl

從完整的端點 URL 中提取 DID Space 的基礎 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

建構一個公開的 URL，用於在 DID Space 中查看物件。

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

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

getSpaceEndpointContext

解析完整的端點 URL，以提取上下文資訊，例如 Space DID 和 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'

傳回值

一個解析為 SpaceEndpointContext 物件的 Promise。

context Promise<SpaceEndpointContext> — 從端點解析出的上下文資訊。
baseUrl string (required) — 空間的基礎 URL。
spaceDid string (required) — 空間的 DID。
appDid string (required) — 空間內應用程式的 DID。

後續步驟

現在您已了解如何初始化客戶端並傳送命令，可以探索可用於與您的空間互動的命令：

物件命令

了解如何對單個檔案（物件）執行 CRUD 操作。

同步命令

探索用於同步本地和遠端資料夾的高階命令。