blackroad-operating-system/sdk/typescript

BlackRoad OS TypeScript SDK

Official TypeScript/JavaScript SDK for the BlackRoad Operating System - a decentralized platform for AI agents and blockchain integration.

Features

• 🔒 Type-Safe: Full TypeScript support with comprehensive type definitions
• 🌐 Universal: Works in Node.js and browser environments
• ⚡ Modern: Built with async/await and ES6+
• 🔄 Resilient: Automatic retry logic and error handling
• 📦 Flexible: Supports both ESM and CommonJS
• 🔐 Secure: Built-in authentication (API keys, JWT)
• 📖 Well-Documented: Comprehensive JSDoc comments and examples

Installation

npm install @blackroad/sdk

Or with yarn:

yarn add @blackroad/sdk

Or with pnpm:

pnpm add @blackroad/sdk

Quick Start

import { BlackRoadClient } from '@blackroad/sdk';

// Initialize the client
const client = new BlackRoadClient({
  apiKey: 'your-api-key',
  baseURL: 'https://api.blackroad.io',
});

// Create an AI agent
const agent = await client.agents.create({
  name: 'My AI Agent',
  type: 'autonomous',
  capabilities: ['reasoning', 'execution'],
});

// Interact with the blockchain
const transaction = await client.blockchain.sendTransaction({
  to: '0x...',
  amount: 100,
  asset: 'BRD',
});

Authentication

The SDK supports multiple authentication methods:

API Key

const client = new BlackRoadClient({
  apiKey: 'your-api-key',
});

JWT Token

const client = new BlackRoadClient({
  token: 'your-jwt-token',
});

Custom Headers

const client = new BlackRoadClient({
  headers: {
    'X-Custom-Auth': 'your-custom-auth',
  },
});

Usage Examples

Working with AI Agents

// Create an agent
const agent = await client.agents.create({
  name: 'Data Analyzer',
  type: 'autonomous',
  capabilities: ['data_analysis', 'visualization'],
});

// Get agent details
const agentDetails = await client.agents.get(agent.id);

// List all agents
const agents = await client.agents.list({
  limit: 10,
  offset: 0,
});

// Execute agent task
const result = await client.agents.execute(agent.id, {
  task: 'analyze_dataset',
  parameters: {
    dataset: 'sales_data_2024',
  },
});

// Update agent
await client.agents.update(agent.id, {
  name: 'Advanced Data Analyzer',
});

// Delete agent
await client.agents.delete(agent.id);

Blockchain Operations

// Get wallet balance
const balance = await client.blockchain.getBalance('0x...');

// Send transaction
const tx = await client.blockchain.sendTransaction({
  to: '0x...',
  amount: 100,
  asset: 'BRD',
  memo: 'Payment for services',
});

// Get transaction status
const status = await client.blockchain.getTransactionStatus(tx.hash);

// List transactions
const transactions = await client.blockchain.listTransactions({
  address: '0x...',
  limit: 50,
});

// Create smart contract
const contract = await client.blockchain.deployContract({
  code: contractCode,
  constructor_args: [],
});

User Management

// Get current user
const user = await client.auth.getCurrentUser();

// Update profile
await client.auth.updateProfile({
  display_name: 'John Doe',
  avatar_url: 'https://example.com/avatar.jpg',
});

// Refresh token
const newToken = await client.auth.refreshToken();

Configuration Options

interface BlackRoadClientConfig {
  /** API key for authentication */
  apiKey?: string;

  /** JWT token for authentication */
  token?: string;

  /** Base URL for the API (default: https://api.blackroad.io) */
  baseURL?: string;

  /** Request timeout in milliseconds (default: 30000) */
  timeout?: number;

  /** Number of retry attempts for failed requests (default: 3) */
  maxRetries?: number;

  /** Custom headers to include in all requests */
  headers?: Record<string, string>;

  /** Enable debug logging (default: false) */
  debug?: boolean;
}

Error Handling

The SDK provides custom error classes for better error handling:

import {
  BlackRoadError,
  AuthenticationError,
  ValidationError,
  NetworkError
} from '@blackroad/sdk';

try {
  await client.agents.create({ name: 'My Agent' });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Authentication failed:', error.message);
  } else if (error instanceof ValidationError) {
    console.error('Validation error:', error.errors);
  } else if (error instanceof NetworkError) {
    console.error('Network error:', error.message);
  } else if (error instanceof BlackRoadError) {
    console.error('BlackRoad error:', error.message);
  }
}

TypeScript Support

The SDK is written in TypeScript and provides full type definitions:

import type {
  Agent,
  AgentCreateParams,
  Transaction,
  User
} from '@blackroad/sdk';

// All types are fully typed
const createAgent = async (params: AgentCreateParams): Promise<Agent> => {
  return await client.agents.create(params);
};

Browser Support

The SDK works in modern browsers with support for:

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+

<script type="module">
  import { BlackRoadClient } from '@blackroad/sdk';

  const client = new BlackRoadClient({
    apiKey: 'your-api-key',
  });

  // Use the client
</script>

Development

Building

npm run build

This will create:

• dist/cjs/ - CommonJS build
• dist/esm/ - ESM build
• dist/types/ - TypeScript declarations

Testing

npm test

Linting

npm run lint

Formatting

npm run format

Examples

Check out the examples/ directory for more comprehensive examples:

• quickstart.ts - Basic usage
• agents-example.ts - Working with AI agents
• blockchain-example.ts - Blockchain operations

API Reference

For detailed API documentation, visit https://docs.blackroad.io

Support

• Documentation: https://docs.blackroad.io
• Issues: GitHub Issues
• Discord: BlackRoad Community

License

MIT

Contributing

Contributions are welcome! Please read our Contributing Guide for details.