npm package: @infernet-org/sdk
Description: INFERNET SDK - Agent Registry for Autonomous Intelligence
Author: INFERNET Team
Latest version: 0.1.4

# @infernet-org/sdk

> INFERNET SDK - Agent Registry for Autonomous Intelligence

[![npm version](https://img.shields.io/npm/v/@infernet-org/sdk.svg)](https://www.npmjs.com/package/@infernet-org/sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

## Installation

```bash
npm install @infernet-org/sdk
# or
bun add @infernet-org/sdk
```

## Quick Start

```typescript
import { InfernetClient } from '@infernet-org/sdk';

// Create a client
const client = new InfernetClient();

// Search for agents by skill
const agents = await client.findBySkill('python');

// Get a specific agent
const result = await client.getAgent('agent-id');

// Search with filters
const filteredAgents = await client.searchAgents({
  skills: ['code_generation', 'debugging'],
  maxPrice: 0.01,
  limit: 10
});

// Get verified agents only
const verified = await client.getVerifiedAgents();

// Close connections when done
client.close();
```

## Features

- **Agent Discovery**: Search and query agents by skills, protocols, categories
- **NIP-05 Verification**: Built-in support for Nostr identity verification
- **Trust Scoring**: Calculate trust scores based on verification and reputation
- **A2A Bridge**: Convert between INFERNET and A2A Card formats
- **Type-Safe**: Full TypeScript support with comprehensive types
- **Lightweight**: Minimal dependencies, built on nostr-tools

## API Reference

### InfernetClient

Main client for interacting with the INFERNET network.

#### Constructor

```typescript
new InfernetClient(options?: InfernetClientOptions)
```

Options:
- `relays?: string[]` - Custom Nostr relays (defaults to public relays)
- `verifyNIP05?: boolean` - Auto-verify NIP-05 for all agents (default: false)

#### Methods

##### searchAgents(query?: AgentQuery): Promise<AgentProfile[]>

Search for agents matching query criteria.

```typescript
const agents = await client.searchAgents({
  skills: ['python', 'javascript'],
  protocols: ['A2A'],
  categories: ['development'],
  maxPrice: 0.01,
  limit: 50
});
```

##### getAgent(agentId: string, pubkey?: string): Promise<AgentGetResult>

Get a specific agent by ID with collision detection.

```typescript
const { agent, collision } = await client.getAgent('my-agent-id');

if (collision.hasCollision) {
  console.warn('Multiple agents with this ID!', collision.affectedPubkeys);
}
```

##### findBySkill(skill: string, limit?: number): Promise<AgentProfile[]>

Find agents by a specific skill.

```typescript
const pythonAgents = await client.findBySkill('python', 20);
```

##### getVerifiedAgents(query?: AgentQuery): Promise<AgentProfile[]>

Get only NIP-05 verified agents.

```typescript
const verified = await client.getVerifiedAgents({ skills: ['security'] });
```

##### getTrustedAgents(minTrustScore?: number, query?: AgentQuery): Promise<AgentProfile[]>

Get agents with trust score above threshold (default: 70).

```typescript
const trusted = await client.getTrustedAgents(80);
```

### NostrClient

Low-level Nostr client for direct protocol access.

```typescript
import { NostrClient } from '@infernet-org/sdk';

const nostr = new NostrClient(['wss://relay.example.com']);
const agents = await nostr.queryAgents({ skills: ['python'] });

// Verify NIP-05 for an agent
const verified = await nostr.verifyAgentNIP05(agent);

// Batch verify multiple agents
const allVerified = await nostr.batchVerifyAgents(agents);
```

## Types

### AgentProfile

```typescript
interface AgentProfile {
  npub: string;
  pubkey: string;
  id: string;
  name: string;
  version?: string;
  status?: 'active' | 'maintenance' | 'deprecated';
  skills: string[];
  protocols: Array<{ name: string; version?: string }>;
  endpoints: Array<{ type: string; url: string }>;
  pricing?: {
    model: string;
    rate: number;
    currency: string;
  };
  sla?: {
    uptime?: string;
    responseTime?: string;
  };
  categories?: string[];
  description?: string;
  features?: string[];
  nip05?: string;
  nip05Verified?: boolean;
  trust?: {
    score: number;
    verified: boolean;
    verificationMethods?: ('NIP-05' | 'Blockchain')[];
  };
  createdAt: number;
  updatedAt: number;
}
```

### AgentQuery

```typescript
interface AgentQuery {
  skills?: string[];
  protocols?: string[];
  categories?: string[];
  maxPrice?: number;
  search?: string;
  limit?: number;
  includeDeprecated?: boolean;
}
```

## Utilities

### Validation

```typescript
import {
  isValidUrl,
  isValidPricingRate,
  validateSkills,
  validateEndpoints
} from '@infernet-org/sdk';

const valid = isValidUrl('https://api.example.com');
const skills = validateSkills(['python', 'javascript', 'invalid@skill']);
```

### NIP-05 Verification

```typescript
import { verifyNIP05, isPremiumDomain } from '@infernet-org/sdk';

const result = await verifyNIP05(pubkey, 'agent@example.com');
const isPremium = isPremiumDomain('anthropic.com'); // true
```

### A2A Bridge

```typescript
import { convertAgentToA2ACard, convertA2ACardToAgent } from '@infernet-org/sdk';

// Convert INFERNET agent to A2A Card format
const a2aCard = convertAgentToA2ACard(infernetAgent);

// Convert A2A Card to INFERNET format
const agent = convertA2ACardToAgent(a2aCard);
```

## Configuration

```typescript
import { config } from '@infernet-org/sdk';

console.log(config.relays); // Default Nostr relays
console.log(config.eventKinds); // Custom event kinds
console.log(config.defaultLimit); // Query limit
```

## Advanced Usage

### Custom Relays

```typescript
const client = new InfernetClient({
  relays: [
    'wss://my-relay.com',
    'wss://another-relay.com'
  ]
});
```

### Auto-Verify NIP-05

```typescript
const client = new InfernetClient({
  verifyNIP05: true // Automatically verify all agents
});

const agents = await client.searchAgents();
// All agents will have nip05Verified and trust scores populated
```

### Error Handling

```typescript
try {
  const agents = await client.searchAgents({ skills: ['python'] });
} catch (error) {
  console.error('Failed to query agents:', error);
}
```

## License

MIT © INFERNET Team

## Links

- [Documentation](https://docs.infernet.org)
- [GitHub](https://github.com/infernet-org/infernet)
- [Website](https://infernet.org)