@latimer-woods-tech/wordis-bond

Typed TypeScript client for the Word Is Bond voice-agent testing API (https://api.wordis-bond.com). Point a synthetic caller at a voice agent you run and get back a scored transcript, a pass/fail verdict, and per-turn latency / word-error-rate / barge-in metrics.

• Zero runtime dependencies — uses the platform global fetch (Node ≥ 18, Workers, Deno, the browser).
• Authenticates with your wb_live_… API key.
• Unwraps the { data, error } envelope and throws WordIsBondError on a non-2xx response.
• Fully typed against the live OpenAPI 3.1 spec.

You only ever test systems you control. This client wraps the testing surface — there is no outbound-to-strangers capability.

Install

npm install @latimer-woods-tech/wordis-bond

Get a key

Sign up at studio.wordis-bond.com (the free Starter plan needs no card), then create a key — the raw token is shown once:

// with a signed-in session, or via the Studio UI:
const { token } = await wb.createApiKey('my agent');

Plans and prices are served live (never hard-coded) — read them with wb.getPlans() or see GET /api/billing/plans.

Quickstart

import { WordIsBond } from '@latimer-woods-tech/wordis-bond';

const wb = new WordIsBond({ apiKey: process.env.WB_API_KEY });

// 1. First scored result in ~60s — no target of your own needed:
const demo = await wb.runDemo();
console.log(demo.score, demo.passed, demo.reportUrl);

// 2. Score a captured transcript against a goal:
const run = await wb.runTest({
  transcript: 'Caller: I need a cleaning. Agent: Sure — Tuesday at 10 works, $89.',
  scenarioGoal: 'Book a cleaning and quote the price.',
});
console.log(run); // completed, scored TestRun

// 3. Drive a live synthetic call against an agent you run (direct = SIP/WebRTC):
const live = await wb.runTest({
  targetAgent: { transport: 'webrtc' },
  goal: 'Ask for opening hours and confirm the address.',
  persona: { description: 'a first-time caller in a hurry' },
});
// A direct run hands back a tokenized mediaWebSocketUrl per run to dial from your harness.

// 4. Watch for drift:
const trends = await wb.getTrends({ days: 30 });
console.log(trends.totals.passRate, trends.totals.regressions);

Suites

const suite = await wb.createSuite({
  name: 'Front desk — booking',
  targetAgent: { transport: 'webrtc' },
  scenarios: [{ persona: 'a new patient', goal: 'Book a cleaning and get the price.' }],
  schedule: 'daily', // plan-gated
});
const series = await wb.getSuiteTrends(suite.id);

Error handling

import { WordIsBondError } from '@latimer-woods-tech/wordis-bond';

try {
  await wb.runTest({ targetAgent: { transport: 'pstn', toNumber: '+15551234567' }, goal: 'x' });
} catch (err) {
  if (err instanceof WordIsBondError) {
    console.error(err.status, err.code, err.message); // e.g. 402 — PSTN needs a paid plan
  }
}

API surface

| Method | Endpoint | |---|---| | health() | GET /health | | getPlans() | GET /api/billing/plans (no key) | | getSubscription() | GET /api/billing/subscription | | listApiKeys() / createApiKey(name) / revokeApiKey(id) | …/api/api-keys | | runDemo(input?) | POST /api/tests/demo | | runTest(input) | POST /api/tests/run | | rescoreRun(id, input?) | POST /api/tests/{id}/score | | runCanary() | POST /api/tests/canary | | getRun(id) / listRuns() | GET /api/tests/{id} · GET /api/tests | | listSuites() / createSuite(input) / getSuite(id) | …/api/tests/suites | | getSuiteTrends(id) / getTrends({days}) | …/trends | | getReportLink(id) | GET /api/reports/{id}/link |

Also available: Remote MCP server

Agents can use the same capability over the Model Context Protocol without this SDK: https://api.wordis-bond.com/mcp (Streamable HTTP). See /llms.txt.

Develop

npm install
npm run typecheck
npm test
npm run build   # → dist/ (ESM + .d.ts)

Release

Publication is automated. Push a tag sdk/v<version> on main; the .github/workflows/publish-sdk.yml workflow builds, verifies the tag matches packages/sdk/package.json, and publishes to npmjs.org with a Sigstore provenance attestation.

License

MIT — see LICENSE.