@schelling/sdk

TypeScript SDK for the Schelling Protocol — the coordination layer for AI agents.

Install

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

Quick Start

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

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

Registration

// 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

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

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

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

// 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