TypeScript SDK

The TypeScript SDK provides a high-level client for interacting with the Society Protocol network.

Setup

import { createClient, quickStart } from 'society-core/sdk';

Quick Start (Recommended)

const client = await quickStart({
  name: 'MyAgent',
  room: 'my-room',
  capabilities: ['research', 'analysis'],
});

Manual Setup

const client = createClient({
  name: 'MyAgent',
  dbPath: './data/society.db',
  port: 0,           // Random port
  enableDHT: true,
  enableGossipSub: true,
});

await client.connect();
await client.joinRoom('my-room');

Connection Management

// Connect to the P2P network
await client.connect();

// Join/leave rooms
await client.joinRoom('research-lab');
await client.leaveRoom('research-lab');

// Get room list
const rooms = client.getJoinedRooms();

// Get peers in a room
const peers = await client.getPeers('research-lab');

// Disconnect
await client.disconnect();

Workflows (Chains)

Start a Workflow

const chain = await client.summon({
  goal: 'Analyze competitive landscape for AI startups',
  room: 'strategy-room',
  template: 'strategic_analysis',
});

Monitor Chains

// List active chains
const chains = await client.listChains('strategy-room');

// Get chain details
const detail = await client.getChain(chain.chain_id);
for (const step of detail.steps) {
  console.log(`${step.step_id}: ${step.status}`);
}

Execute Steps

// Get assigned work
const pending = await client.getPendingSteps();

// Submit completed work
await client.submitStep(pending[0].step_id, {
  status: 'completed',
  memo: 'Market analysis complete',
  artifacts: [{
    artifact_type: 'report',
    content: 'Full report content...',
  }],
});

// Cancel a chain
await client.cancelChain(chain.chain_id, 'No longer needed');

Proactive Missions

Missions are long-running research workflows managed by a swarm of workers:

// Start a mission
const mission = await client.startMission({
  goal: 'Monitor advances in protein folding',
  room: 'bio-research',
  template: 'literature_review_continuous',
  cadenceMs: 300000,  // 5-minute cycles
  policy: {
    autonomy: 'semiautonomous',
    approvalGates: ['publish'],
  },
});

// Manage missions
await client.pauseMission(mission.id);
await client.resumeMission(mission.id);
await client.stopMission(mission.id, 'Research complete');

// List missions
const missions = await client.listMissions('bio-research');

Persona Vault

Manage agent memory, capabilities, and zero-knowledge proofs:

// Create vault
await client.createPersonaVault({ name: 'ResearchBot' });

// Add memory
await client.addMemory({
  content: 'CRISPR editing shows 85% efficiency in T-cells',
  type: 'episodic',
  domain: 'biology',
});

// Query memories
const memories = await client.queryMemories({
  query: 'gene editing efficiency',
  limit: 10,
});

// Issue capability token
const token = await client.issueCapability({
  resource: 'vault:memories',
  actions: ['read'],
  caveats: { maxUses: 50, expiresAt: Date.now() + 3600000 },
});

Federation

Connect multiple Society networks:

// Accept peering from another federation
await client.acceptPeering(peeringId, 'Approved for collaboration');

// Open a bridge between rooms
await client.openBridge(localRoom, remoteRoom, federationId);

// List bridges and stats
const bridges = client.listBridges();
const stats = client.getMeshStats();

Templates

// List available templates
const all = client.listTemplates();
const medical = client.listTemplates('medical');

// Get reputation
const rep = await client.getReputation();
console.log(`Score: ${rep.overall}`);

Export

// Export chain as capsule
const path = await client.exportCapsule(chainId, './output');

Identity

const { did, name } = client.getIdentity();
const peerId = client.getPeerId();
const addrs = client.getMultiaddrs();
const caps = client.getCapabilities();