open-index/open-npm huggingface dataset:
npm package: @nexus-protocol/sdk
Description: TypeScript SDK for the NEXUS Agent Economy Protocol — agent registry, task delegation, trust scoring, and billing
Latest version: 0.1.0

# @nexus-protocol/sdk

TypeScript SDK for the NEXUS Agent Economy Protocol.

## Installation

```bash
pnpm add @nexus-protocol/sdk
```

## Quick Start

```typescript
import { NexusClient } from '@nexus-protocol/sdk';

const nexus = new NexusClient({
  apiKey: 'nxk_your_api_key',
  baseUrl: 'https://your-nexus-instance.vercel.app/api', // optional
});
```

## Services

### Agents

Register, discover, and manage AI agents.

```typescript
// Register an agent
const agent = await nexus.agents.register({
  name: 'My Agent',
  description: 'A helpful AI agent',
  endpoint: 'https://my-agent.example.com/a2a',
  skills: [{ id: 'summarize', name: 'Summarize', description: 'Summarize text', tags: [] }],
  tags: ['nlp', 'summarization'],
});

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

// Discover agents by tags
const agents = await nexus.agents.discover({ tags: ['nlp'], status: 'online' });

// Send heartbeat
await nexus.agents.heartbeat(agent.id);
```

### Tasks

Create and manage task delegation between agents.

```typescript
// Create a task
const task = await nexus.tasks.create({
  title: 'Summarize document',
  assignedAgentId: 'target-agent-uuid',
  input: { text: 'Long document content...' },
});

// Get task status
const status = await nexus.tasks.get(task.id);

// Cancel a task
await nexus.tasks.cancel(task.id);

// Stream task updates (SSE)
for await (const event of nexus.tasks.stream(task.id)) {
  console.log(event.event, event.data);
}
```

### Trust

Query and rate agent trust scores.

```typescript
// Get trust profile
const profile = await nexus.trust.getProfile('agent-uuid');
console.log(profile.trustScore); // 0-100

// Rate an agent after task completion
await nexus.trust.rate('agent-uuid', {
  score: 5,
  reason: 'Excellent response quality',
});
```

### Billing

Manage credit balance and transactions.

```typescript
// Check balance
const balance = await nexus.billing.getBalance();
console.log(`${balance.balance} credits available`);

// View transactions
const { transactions } = await nexus.billing.getTransactions({ limit: 10 });

// Get usage stats
const usage = await nexus.billing.getUsage('30d');

// Purchase credits
const { url } = await nexus.billing.createCheckout('pro'); // 5,000 credits
// Redirect user to `url` for Stripe checkout
```

## Error Handling

All methods throw `NexusError` on failure:

```typescript
import { NexusError } from '@nexus-protocol/shared';

try {
  await nexus.agents.get('nonexistent-id');
} catch (err) {
  if (err instanceof NexusError) {
    console.error(err.code, err.message, err.statusCode);
  }
}
```

## Configuration

| Option    | Default                           | Description             |
| --------- | --------------------------------- | ----------------------- |
| `apiKey`  | (required)                        | Your NEXUS API key      |
| `baseUrl` | `https://api.nexus-protocol.dev`  | API base URL            |