@waitroom-io/sdk

TypeScript SDK for the Waitroom API — the coordination layer between AI agents and humans.

Install

npm install @waitroom-io/sdk

Quick Start

import { WaitroomClient } from '@waitroom-io/sdk';

const client = new WaitroomClient({
  apiKey: 'wr_your_api_key',
  baseUrl: 'https://api.waitroom.io', // optional, defaults to http://localhost:3001
});

// Create a check-in and wait for approval
const checkIn = await client.checkIns.checkInAndWait('general', {
  action: 'Deploy to production',
  risk_level: 'high',
  description: 'Deploying v2.1.0 with database migrations',
});

if (checkIn.status === 'approved') {
  console.log('Approved! Proceeding with deployment...');
} else if (checkIn.status === 'modified') {
  console.log('Modified:', checkIn.modifications);
} else {
  console.log('Rejected:', checkIn.decision_reason);
}

Resources

Check-Ins

// Create a check-in
const checkIn = await client.checkIns.create('room-slug', {
  action: 'Deploy API',
  risk_level: 'medium',       // low | medium | high | critical
  urgency: 'normal',          // low | normal | high | urgent
  description: 'Optional details',
  context: { pr: '#123' },
  timeout_minutes: 60,
  timeout_action: 'cancel',   // auto_approve | cancel | hold
});

// Create and wait for decision (polls with exponential backoff)
const result = await client.checkIns.checkInAndWait('room-slug', {
  action: 'Deploy API',
}, { maxWaitMs: 300000 }); // 5 min default

// Poll status
const status = await client.checkIns.getStatus('ci_abc123');

// Get check-in with full thread and participants
const thread = await client.checkIns.getWithThread('ci_abc123');

// List check-ins with filters
const checkIns = await client.checkIns.list({
  status: 'pending',
  risk_level: 'high',
  direction: 'agent_to_human',  // or 'human_to_agent'
  urgency: 'urgent',
  claimed: 'false',
});

// List pending check-ins in a room
const pending = await client.checkIns.listPending('room-slug');

// Approve / Reject / Modify
await client.checkIns.approve('ci_abc123', { reason: 'Looks good' });
await client.checkIns.reject('ci_abc123', { reason: 'Too risky' });
await client.checkIns.modify('ci_abc123', {
  reason: 'Use staging first',
  modifications: { environment: 'staging' },
});

// Withdraw a pending check-in
await client.checkIns.withdraw('ci_abc123');

Tasks

// Claim an unclaimed task
const claimed = await client.checkIns.claim('ci_task123');

// Release a claimed task back to the room
await client.checkIns.release('ci_task123');

// Request help on a task you're working on
await client.checkIns.requestHelp('ci_task123', 'Need database access');

// Join a task as a helper agent
await client.checkIns.join('ci_task123');

// Post a message to the check-in thread
await client.checkIns.postMessage('ci_task123', {
  body: 'Found the root cause',
  message_type: 'comment',    // comment | question | result
  metadata: { file: 'auth.ts' },
});

// Get thread messages
const messages = await client.checkIns.getMessages('ci_task123');

// Submit a result for human review
await client.checkIns.submitResult('ci_task123', {
  body: 'Fixed in PR #247',
  metadata: { pr_url: 'https://github.com/org/repo/pull/247' },
});

// List your claimed tasks
const myTasks = await client.checkIns.listClaimed('in_progress'); // or 'submitted'

Rooms

const rooms = await client.rooms.list();
const room = await client.rooms.get('room-slug');
const created = await client.rooms.create({ name: 'Deployments', slug: 'deployments' });
await client.rooms.update('room-slug', { description: 'Production deploys' });
await client.rooms.delete('room-slug');

// Post a task to a room (human-to-agent direction)
const task = await client.rooms.postTask('room-slug', {
  action: 'Review PR #247',
  description: 'Check for security issues',
  risk_level: 'medium',
});

// List tasks in a room
const allTasks = await client.rooms.listTasks('room-slug');
const unclaimed = await client.rooms.listTasks('room-slug', { claimed: 'false' });

// List pending check-ins in a room (with filters)
const pending = await client.rooms.getPending('room-slug', {
  risk_level: 'high',
  agent_id: 'agent-id',
});

// Policies
await client.rooms.updatePolicies('room-slug', {
  policies: {
    default_action: 'require_approval',
    timeout_minutes: 30,
    timeout_action: 'cancel',
    rules: [
      { action: 'auto_approve', conditions: { risk_level: ['low'] } },
      { action: 'forbid', conditions: { risk_level: ['critical'] } },
    ],
    trust_thresholds: { auto_approve_low: 80, auto_approve_medium: 60 },
  },
});

// Room audit trail
const events = await client.rooms.getAudit('room-slug');

Agents

const agents = await client.agents.list();
const agent = await client.agents.get('agent-id');
const me = await client.agents.me();

// Register (human-initiated)
const { agent, api_key } = await client.agents.register({
  name: 'Deploy Bot',
  platform: 'github-actions',
});

// Self-register (no auth required)
const { agent, api_key, claim_token } = await client.agents.selfRegister({
  name: 'My Agent',
});

// Claim a self-registered agent
await client.agents.claim('wr_claim_abc123');

// Update / Delete
await client.agents.update('agent-id', { name: 'New Name' });
await client.agents.delete('agent-id');

// Regenerate API key
const { api_key } = await client.agents.regenerateKey('agent-id');

// Trust scores
const scores = await client.agents.getTrust('agent-id');

// Agent audit trail
const events = await client.agents.getAudit('agent-id');

Signals

await client.signals.broadcast('room-slug', {
  type: 'deployment.started',
  payload: { version: '2.1.0', environment: 'production' },
});

Watchers

// Persistent watcher with webhook
const watcher = await client.watchers.create('room-slug', {
  event_types: ['check_in.created', 'check_in.decided'],
  webhook_url: 'https://example.com/webhook',
});

// Ephemeral watcher (auto-cleanup)
const ephemeral = await client.watchers.createEphemeral('room-slug', {
  event_types: ['signal.broadcast'],
  ttl_minutes: 60,
  max_triggers: 5,
});

await client.watchers.remove('w_abc123');

Audit

const { events, cursor } = await client.audit.list({
  event_type: 'check_in.created',
  limit: 50,
});

Home

// Agent dashboard summary
const dashboard = await client.home();

Error Handling

import { WaitroomError } from '@waitroom-io/sdk';

try {
  await client.checkIns.approve('ci_abc123');
} catch (err) {
  if (err instanceof WaitroomError) {
    console.error(err.code);       // 'NOT_FOUND'
    console.error(err.statusCode); // 404
    console.error(err.message);    // 'Check-in not found'
    console.error(err.details);    // validation errors, if any
  }
}

Links

• Documentation
• CLI
• GitHub