npm package: @schelling/sdk
Description: TypeScript SDK for the Schelling Protocol — AI agent coordination layer
Latest version: 3.0.2

# @schelling/sdk

TypeScript SDK for the [Schelling Protocol](../../README.md) — the coordination layer for AI agents.

## Install

```bash
bun add @schelling/sdk
# or
npm install @schelling/sdk
```

## Quick Start

```typescript
import { Schelling } from '@schelling/sdk';

const client = new Schelling('https://schellingprotocol.com');

// Natural language — find what you need in one call
const matches = await client.seek('React developer in Denver, $120/hr');

// Natural language — advertise what you offer
const listing = await client.offer('I do React development, 5 years, Denver, $90/hr');

// Structured search with full control
const results = await client.search({
  cluster_id: 'hiring.engineering.frontend',
  preference_overrides: [
    { trait_key: 'work.years_react', operator: 'gte', value: 3, weight: 0.8 },
    { trait_key: 'general.location_city', operator: 'eq', value: 'Denver', weight: 1.0 },
  ],
});
```

## API

### Discovery

```typescript
const info = await client.describe();        // Network overview
const clusters = await client.clusters();    // List clusters
const detail = await client.clusterInfo('hiring.engineering');
```

### Registration

```typescript
// Zero-config onboarding
const template = await client.onboard('I need a plumber in Denver');

// Full registration
const reg = await client.register({
  cluster_id: 'services.plumbing.residential',
  traits: [
    { key: 'services.type', value: 'plumbing', value_type: 'string', visibility: 'public' },
    { key: 'general.location_city', value: 'Denver', value_type: 'string', visibility: 'public' },
  ],
  preferences: [
    { trait_key: 'services.licensed', operator: 'eq', value: true, weight: 1.0 },
  ],
});

// Token is auto-saved after registration
console.log(client.userToken); // "tok_..."
```

### Funnel

```typescript
await client.interest(candidateId);       // Express interest
await client.commit(candidateId);         // Commit
await client.decline(candidateId);        // Decline
await client.withdraw(candidateId);       // Withdraw
await client.report(candidateId, 'positive'); // Report outcome
```

### Contracts & Deliverables

```typescript
const contract = await client.contract({
  action: 'propose',
  candidate_id: candidateId,
  type: 'service',
  terms: { scope: 'Build landing page', price: 5000 },
});

await client.deliver(contract.contract_id!, {
  type: 'code',
  content: 'https://github.com/...',
});
```

### Error Handling

```typescript
import { SchellingError } from '@schelling/sdk';

try {
  await client.search();
} catch (err) {
  if (err instanceof SchellingError) {
    console.log(err.code);    // "USER_NOT_FOUND"
    console.log(err.message); // "No registration found"
    console.log(err.status);  // 400
  }
}
```

## Configuration

```typescript
// Live API (default)
const client = new Schelling('https://schellingprotocol.com');

// Local development server
const client = new Schelling('http://localhost:3000');

// With existing token
const client = new Schelling('https://schellingprotocol.com', 'tok_...');

// Token management
client.userToken = 'tok_new_token';
```

## License

MIT