@latimer-woods-tech/wordis-bond 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Latimer Woods Tech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,133 @@
+# @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](https://api.wordis-bond.com/openapi.json).
+
+> **You only ever test systems you control.** This client wraps the testing surface —
+> there is no outbound-to-strangers capability.
+
+## Install
+
+```sh
+npm install @latimer-woods-tech/wordis-bond
+```
+
+## Get a key
+
+Sign up at [studio.wordis-bond.com](https://studio.wordis-bond.com) (the free Starter
+plan needs no card), then create a key — the raw token is shown once:
+
+```ts
+// 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`](https://api.wordis-bond.com/api/billing/plans).
+
+## Quickstart
+
+```ts
+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
+
+```ts
+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
+
+```ts
+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`](https://wordis-bond.com/llms.txt).
+
+## Develop
+
+```sh
+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`](./LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,330 @@
+/**
+ * @latimer-woods-tech/wordis-bond — typed client for the Word Is Bond voice-agent
+ * testing API (https://api.wordis-bond.com).
+ *
+ * A thin, dependency-free wrapper over the live REST surface: it uses the platform
+ * global `fetch`, authenticates with your `wb_live_…` API key, unwraps the
+ * `{ data, error }` envelope, and throws {@link WordIsBondError} on a non-2xx response.
+ *
+ * Prices/quotas are never baked in here — read them live with {@link WordIsBond.getPlans}.
+ * This client wraps a testing surface: you only ever test voice agents you run.
+ */
+/** The public production API origin. */
+declare const DEFAULT_BASE_URL = "https://api.wordis-bond.com";
+/** Client options. */
+interface WordIsBondOptions {
+    /** Your API key (`wb_live_…`). Required for every endpoint except {@link WordIsBond.getPlans} and {@link WordIsBond.health}. */
+    apiKey?: string;
+    /** Override the API origin (e.g. a staging URL). Defaults to {@link DEFAULT_BASE_URL}. */
+    baseUrl?: string;
+    /** Inject a custom fetch (defaults to the global `fetch`). */
+    fetch?: typeof fetch;
+}
+/** Thrown when the API returns a non-2xx response. Carries the status and parsed error. */
+declare class WordIsBondError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    readonly body: unknown;
+    constructor(status: number, message: string, opts?: {
+        code?: string;
+        body?: unknown;
+    });
+}
+type Plan = 'starter' | 'pro' | 'enterprise';
+type Transport = 'pstn' | 'webrtc' | 'direct' | 'sip';
+type RunStatus = 'queued' | 'running' | 'completed' | 'failed';
+/** The voice agent under test — a system you run. */
+interface TargetAgent {
+    transport: Transport;
+    /** E.164 number to dial (required for a `pstn` target). */
+    toNumber?: string;
+    /** Hosted-agent id, e.g. `wb-demo-dental`. */
+    peerId?: string;
+    [k: string]: unknown;
+}
+interface Scorecard {
+    score: number;
+    passed: boolean;
+    summary?: string;
+    sentiment?: number;
+    taskCompletion?: number;
+    layers?: Array<{
+        name: string;
+        score: number;
+        passed: boolean;
+        rationale: string;
+        assertions: unknown[];
+    }>;
+}
+interface RunMetrics {
+    latencyMs?: {
+        p50: number;
+        p95: number;
+        max: number;
+    };
+    wer?: number | null;
+    bargeInCount?: number;
+    turnCount?: number;
+    taskCompletion?: number;
+    sentiment?: number;
+}
+interface TestRun {
+    id: string;
+    accountId?: string;
+    suiteId?: string | null;
+    status: RunStatus;
+    transport?: string;
+    language?: string;
+    persona?: unknown;
+    targetAgent?: TargetAgent | null;
+    score?: number | null;
+    passed?: boolean | null;
+    scorecard?: Scorecard | null;
+    metrics?: RunMetrics | null;
+    transcript?: string | null;
+    /** Only on a live `direct` run — the tokenized WS your agent-side harness dials. */
+    mediaWebSocketUrl?: string;
+    reportUrl?: string;
+    peerId?: string;
+    startedAt?: string | null;
+    endedAt?: string | null;
+    createdAt?: string;
+    [k: string]: unknown;
+}
+interface Scenario {
+    persona?: string | {
+        name?: string;
+        description?: string;
+    };
+    goal?: string;
+    expected?: string[];
+}
+interface TestSuite {
+    id: string;
+    accountId?: string;
+    name: string;
+    targetAgent: TargetAgent;
+    language?: string;
+    scenarios?: Scenario[];
+    schedule?: string | null;
+    createdAt?: string;
+    updatedAt?: string;
+}
+interface PlanView {
+    plan: Plan;
+    priceUsdPerMonth: number;
+    purchasable?: boolean;
+    lookupKey?: string | null;
+    callMinutesPerMonth: number;
+    allowedTransports: Array<'direct' | 'pstn'>;
+    overageUsdPerMinute?: {
+        pstn: number | null;
+        direct: number | null;
+    };
+    ttsCharsPerMonth?: number;
+    concurrentCalls?: number;
+    scheduledRuns?: {
+        cadence: 'weekly' | 'daily' | 'hourly';
+        maxSuites: number | null;
+    };
+    apiKeys?: number | null;
+    requiresCard?: boolean;
+}
+interface PlansResponse {
+    plans: PlanView[];
+    currency: string;
+}
+interface Subscription {
+    plan: Plan;
+    hasBillingAccount: boolean;
+    usage: {
+        callMinutes: number;
+        ttsChars: number;
+    };
+    entitlements: PlanView;
+}
+interface ApiKeySummary {
+    id: string;
+    name: string;
+    keyPrefix: string;
+    lastUsedAt?: string | null;
+    createdAt?: string;
+}
+/** A newly-created key — `token` is present exactly once and never retrievable again. */
+interface CreatedApiKey extends ApiKeySummary {
+    token: string;
+}
+interface TrendPoint {
+    runId: string;
+    score: number | null;
+    passed: boolean | null;
+    at: string | null;
+}
+interface RegressionPoint {
+    runId: string;
+    at: string | null;
+    reason: 'pass_to_fail' | 'score_drop';
+    from: number | null;
+    to: number | null;
+}
+interface SuiteTrend {
+    suiteId: string;
+    name: string | null;
+    runs: number;
+    passed: number;
+    failed: number;
+    passRate: number | null;
+    avgScore: number | null;
+    regressions: number;
+}
+interface SuiteTrendSeries {
+    suiteId: string;
+    name: string | null;
+    points: TrendPoint[];
+    regressions: RegressionPoint[];
+    summary: SuiteTrend;
+}
+interface AccountTrends {
+    window: string;
+    totals: {
+        suites: number;
+        runs: number;
+        passed: number;
+        failed: number;
+        passRate: number | null;
+        avgScore: number | null;
+        regressions: number;
+    };
+    suites: SuiteTrend[];
+}
+/** Body for the offline transcript-scoring path of {@link WordIsBond.runTest}. */
+interface ScoreTranscriptInput {
+    transcript?: string;
+    turns?: Array<{
+        role: 'agent' | 'caller';
+        text: string;
+    }>;
+    scenarioGoal?: string;
+    assertions?: string[];
+    suiteId?: string | null;
+    language?: string;
+    transport?: 'pstn' | 'webrtc';
+}
+/** Body for the live synthetic-call path of {@link WordIsBond.runTest}. */
+interface LiveRunInput {
+    targetAgent: TargetAgent;
+    goal?: string;
+    persona?: {
+        name?: string;
+        description: string;
+    };
+    suiteId?: string | null;
+    transport?: 'pstn' | 'webrtc';
+    language?: string;
+    concurrency?: number;
+    expected?: string[];
+    bargeIn?: boolean;
+}
+/** Result of a live run: either a single completed run or a batch with per-run entries. */
+type RunTestResult = TestRun | {
+    runs: TestRun[];
+    concurrency?: number;
+    transport?: string;
+};
+interface DemoInput {
+    persona?: {
+        description: string;
+    };
+    goal?: string;
+    language?: string;
+    expected?: string[];
+    bargeIn?: boolean;
+}
+interface CreateSuiteInput {
+    name: string;
+    targetAgent: TargetAgent;
+    language?: string;
+    scenarios?: Scenario[];
+    schedule?: string;
+}
+/**
+ * Typed client for the Word Is Bond testing API.
+ *
+ * @example
+ * ```ts
+ * const wb = new WordIsBond({ apiKey: process.env.WB_API_KEY });
+ * const run = await wb.runDemo();
+ * console.log(run.score, run.passed, run.reportUrl);
+ * ```
+ */
+declare class WordIsBond {
+    private readonly apiKey?;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(options?: WordIsBondOptions);
+    /** Service health (no auth). */
+    health(): Promise<{
+        status: string;
+        worker?: string;
+        env?: string;
+    }>;
+    /** The plan + entitlement table (no auth). The single source of truth for pricing. */
+    getPlans(): Promise<PlansResponse>;
+    /** Your current plan, usage, and entitlements. */
+    getSubscription(): Promise<Subscription>;
+    /** List your active (non-revoked) API keys. */
+    listApiKeys(): Promise<ApiKeySummary[]>;
+    /** Create an API key. The returned `token` is shown once — store it securely. */
+    createApiKey(name: string): Promise<CreatedApiKey>;
+    /** Revoke an API key. */
+    revokeApiKey(id: string): Promise<{
+        revoked: boolean;
+    }>;
+    /**
+     * Run the hosted demo voice agent end-to-end and get a real, fully-scored result —
+     * no target of your own required. Returns the run plus a shareable report URL.
+     */
+    runDemo(input?: DemoInput): Promise<TestRun>;
+    /**
+     * Run a test against a voice agent you control. Pass a {@link ScoreTranscriptInput}
+     * to score a captured transcript offline (returns a completed {@link TestRun}), or a
+     * {@link LiveRunInput} to drive a live synthetic call (returns a run or a batch).
+     */
+    runTest(input: ScoreTranscriptInput | LiveRunInput): Promise<RunTestResult>;
+    /** (Re)score a run's transcript with the judge. */
+    rescoreRun(id: string, input?: {
+        scenarioGoal?: string;
+        assertions?: string[];
+        transcript?: string;
+    }): Promise<TestRun>;
+    /** Trigger the hosted self-test now and publish a public report. */
+    runCanary(): Promise<{
+        runId: string;
+        score: number | null;
+        passed: boolean | null;
+        reportUrl: string;
+    }>;
+    /** Fetch one run — poll here for the terminal scored state of a live run. */
+    getRun(id: string): Promise<TestRun>;
+    /** List your most recent runs (up to 100). */
+    listRuns(): Promise<TestRun[]>;
+    /** List your reusable test suites. */
+    listSuites(): Promise<TestSuite[]>;
+    /** Create a reusable test suite. */
+    createSuite(input: CreateSuiteInput): Promise<TestSuite>;
+    /** Fetch one suite. */
+    getSuite(id: string): Promise<TestSuite>;
+    /** Per-suite time series + run-to-run regression flags. */
+    getSuiteTrends(id: string): Promise<SuiteTrendSeries>;
+    /** Account-wide pass-rate, average score, and regressions over a window (default 90 days). */
+    getTrends(opts?: {
+        days?: number;
+    }): Promise<AccountTrends>;
+    /** Get the shareable public report URL for one of your runs. */
+    getReportLink(id: string): Promise<{
+        url: string;
+    }>;
+    private request;
+}
+
+export { type AccountTrends, type ApiKeySummary, type CreateSuiteInput, type CreatedApiKey, DEFAULT_BASE_URL, type DemoInput, type LiveRunInput, type Plan, type PlanView, type PlansResponse, type RegressionPoint, type RunMetrics, type RunStatus, type RunTestResult, type Scenario, type ScoreTranscriptInput, type Scorecard, type Subscription, type SuiteTrend, type SuiteTrendSeries, type TargetAgent, type TestRun, type TestSuite, type Transport, type TrendPoint, WordIsBond, WordIsBondError, type WordIsBondOptions, WordIsBond as default };

package/dist/index.js

@@ -0,0 +1,162 @@
+// src/index.ts
+var DEFAULT_BASE_URL = "https://api.wordis-bond.com";
+var WordIsBondError = class extends Error {
+  status;
+  code;
+  body;
+  constructor(status, message, opts = {}) {
+    super(message);
+    this.name = "WordIsBondError";
+    this.status = status;
+    this.code = opts.code;
+    this.body = opts.body;
+  }
+};
+var WordIsBond = class {
+  apiKey;
+  baseUrl;
+  fetchImpl;
+  constructor(options = {}) {
+    this.apiKey = options.apiKey;
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    const f = options.fetch ?? globalThis.fetch;
+    if (!f) {
+      throw new Error("No fetch implementation available \u2014 pass one via the `fetch` option.");
+    }
+    this.fetchImpl = f;
+  }
+  // ── Meta ─────────────────────────────────────────────────────────────────
+  /** Service health (no auth). */
+  health() {
+    return this.request("GET", "/health", { auth: false });
+  }
+  // ── Billing (source of truth for pricing) ─────────────────────────────────
+  /** The plan + entitlement table (no auth). The single source of truth for pricing. */
+  getPlans() {
+    return this.request("GET", "/api/billing/plans", { auth: false });
+  }
+  /** Your current plan, usage, and entitlements. */
+  getSubscription() {
+    return this.request("GET", "/api/billing/subscription");
+  }
+  // ── API keys ──────────────────────────────────────────────────────────────
+  /** List your active (non-revoked) API keys. */
+  listApiKeys() {
+    return this.request("GET", "/api/api-keys");
+  }
+  /** Create an API key. The returned `token` is shown once — store it securely. */
+  createApiKey(name) {
+    return this.request("POST", "/api/api-keys", { body: { name } });
+  }
+  /** Revoke an API key. */
+  revokeApiKey(id) {
+    return this.request("DELETE", `/api/api-keys/${encodeURIComponent(id)}`);
+  }
+  // ── Testing ────────────────────────────────────────────────────────────────
+  /**
+   * Run the hosted demo voice agent end-to-end and get a real, fully-scored result —
+   * no target of your own required. Returns the run plus a shareable report URL.
+   */
+  runDemo(input = {}) {
+    return this.request("POST", "/api/tests/demo", { body: input });
+  }
+  /**
+   * Run a test against a voice agent you control. Pass a {@link ScoreTranscriptInput}
+   * to score a captured transcript offline (returns a completed {@link TestRun}), or a
+   * {@link LiveRunInput} to drive a live synthetic call (returns a run or a batch).
+   */
+  runTest(input) {
+    return this.request("POST", "/api/tests/run", { body: input });
+  }
+  /** (Re)score a run's transcript with the judge. */
+  rescoreRun(id, input = {}) {
+    return this.request("POST", `/api/tests/${encodeURIComponent(id)}/score`, { body: input });
+  }
+  /** Trigger the hosted self-test now and publish a public report. */
+  runCanary() {
+    return this.request("POST", "/api/tests/canary");
+  }
+  /** Fetch one run — poll here for the terminal scored state of a live run. */
+  getRun(id) {
+    return this.request("GET", `/api/tests/${encodeURIComponent(id)}`);
+  }
+  /** List your most recent runs (up to 100). */
+  listRuns() {
+    return this.request("GET", "/api/tests");
+  }
+  // ── Suites ───────────────────────────────────────────────────────────────
+  /** List your reusable test suites. */
+  listSuites() {
+    return this.request("GET", "/api/tests/suites");
+  }
+  /** Create a reusable test suite. */
+  createSuite(input) {
+    return this.request("POST", "/api/tests/suites", { body: input });
+  }
+  /** Fetch one suite. */
+  getSuite(id) {
+    return this.request("GET", `/api/tests/suites/${encodeURIComponent(id)}`);
+  }
+  // ── Trends ───────────────────────────────────────────────────────────────
+  /** Per-suite time series + run-to-run regression flags. */
+  getSuiteTrends(id) {
+    return this.request("GET", `/api/tests/suites/${encodeURIComponent(id)}/trends`);
+  }
+  /** Account-wide pass-rate, average score, and regressions over a window (default 90 days). */
+  getTrends(opts = {}) {
+    const q = opts.days ? `?days=${Math.trunc(opts.days)}` : "";
+    return this.request("GET", `/api/tests/trends${q}`);
+  }
+  // ── Reports ──────────────────────────────────────────────────────────────
+  /** Get the shareable public report URL for one of your runs. */
+  getReportLink(id) {
+    return this.request("GET", `/api/reports/${encodeURIComponent(id)}/link`);
+  }
+  // ── Internal ─────────────────────────────────────────────────────────────
+  async request(method, path, opts = {}) {
+    const auth = opts.auth !== false;
+    const headers = { accept: "application/json" };
+    if (auth) {
+      if (!this.apiKey) {
+        throw new WordIsBondError(0, `${method} ${path} requires an API key \u2014 construct the client with { apiKey }.`);
+      }
+      headers["authorization"] = `Bearer ${this.apiKey}`;
+    }
+    if (opts.body !== void 0) headers["content-type"] = "application/json";
+    let res;
+    try {
+      res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+        method,
+        headers,
+        body: opts.body !== void 0 ? JSON.stringify(opts.body) : void 0
+      });
+    } catch (err) {
+      throw new WordIsBondError(0, `Network error calling ${method} ${path}: ${err.message}`);
+    }
+    const text = await res.text();
+    let json;
+    try {
+      json = text ? JSON.parse(text) : void 0;
+    } catch {
+      json = void 0;
+    }
+    if (!res.ok) {
+      const err = json?.error;
+      const message = typeof err === "string" ? err : err && typeof err === "object" && "message" in err ? String(err.message) : `Request failed with status ${res.status}`;
+      const code = err && typeof err === "object" && "code" in err ? String(err.code) : void 0;
+      throw new WordIsBondError(res.status, message, { code, body: json ?? text });
+    }
+    if (json && typeof json === "object" && "data" in json) {
+      return json.data;
+    }
+    return json;
+  }
+};
+var index_default = WordIsBond;
+export {
+  DEFAULT_BASE_URL,
+  WordIsBond,
+  WordIsBondError,
+  index_default as default
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * @latimer-woods-tech/wordis-bond — typed client for the Word Is Bond voice-agent\n * testing API (https://api.wordis-bond.com).\n *\n * A thin, dependency-free wrapper over the live REST surface: it uses the platform\n * global `fetch`, authenticates with your `wb_live_…` API key, unwraps the\n * `{ data, error }` envelope, and throws {@link WordIsBondError} on a non-2xx response.\n *\n * Prices/quotas are never baked in here — read them live with {@link WordIsBond.getPlans}.\n * This client wraps a testing surface: you only ever test voice agents you run.\n */\n\n/** The public production API origin. */\nexport const DEFAULT_BASE_URL = 'https://api.wordis-bond.com';\n\n/** Client options. */\nexport interface WordIsBondOptions {\n  /** Your API key (`wb_live_…`). Required for every endpoint except {@link WordIsBond.getPlans} and {@link WordIsBond.health}. */\n  apiKey?: string;\n  /** Override the API origin (e.g. a staging URL). Defaults to {@link DEFAULT_BASE_URL}. */\n  baseUrl?: string;\n  /** Inject a custom fetch (defaults to the global `fetch`). */\n  fetch?: typeof fetch;\n}\n\n/** Thrown when the API returns a non-2xx response. Carries the status and parsed error. */\nexport class WordIsBondError extends Error {\n  readonly status: number;\n  readonly code?: string;\n  readonly body: unknown;\n  constructor(status: number, message: string, opts: { code?: string; body?: unknown } = {}) {\n    super(message);\n    this.name = 'WordIsBondError';\n    this.status = status;\n    this.code = opts.code;\n    this.body = opts.body;\n  }\n}\n\n// ── Domain types (mirror docs/openapi.json; see the OpenAPI spec for full detail) ──\n\nexport type Plan = 'starter' | 'pro' | 'enterprise';\nexport type Transport = 'pstn' | 'webrtc' | 'direct' | 'sip';\nexport type RunStatus = 'queued' | 'running' | 'completed' | 'failed';\n\n/** The voice agent under test — a system you run. */\nexport interface TargetAgent {\n  transport: Transport;\n  /** E.164 number to dial (required for a `pstn` target). */\n  toNumber?: string;\n  /** Hosted-agent id, e.g. `wb-demo-dental`. */\n  peerId?: string;\n  [k: string]: unknown;\n}\n\nexport interface Scorecard {\n  score: number;\n  passed: boolean;\n  summary?: string;\n  sentiment?: number;\n  taskCompletion?: number;\n  layers?: Array<{ name: string; score: number; passed: boolean; rationale: string; assertions: unknown[] }>;\n}\n\nexport interface RunMetrics {\n  latencyMs?: { p50: number; p95: number; max: number };\n  wer?: number | null;\n  bargeInCount?: number;\n  turnCount?: number;\n  taskCompletion?: number;\n  sentiment?: number;\n}\n\nexport interface TestRun {\n  id: string;\n  accountId?: string;\n  suiteId?: string | null;\n  status: RunStatus;\n  transport?: string;\n  language?: string;\n  persona?: unknown;\n  targetAgent?: TargetAgent | null;\n  score?: number | null;\n  passed?: boolean | null;\n  scorecard?: Scorecard | null;\n  metrics?: RunMetrics | null;\n  transcript?: string | null;\n  /** Only on a live `direct` run — the tokenized WS your agent-side harness dials. */\n  mediaWebSocketUrl?: string;\n  reportUrl?: string;\n  peerId?: string;\n  startedAt?: string | null;\n  endedAt?: string | null;\n  createdAt?: string;\n  [k: string]: unknown;\n}\n\nexport interface Scenario {\n  persona?: string | { name?: string; description?: string };\n  goal?: string;\n  expected?: string[];\n}\n\nexport interface TestSuite {\n  id: string;\n  accountId?: string;\n  name: string;\n  targetAgent: TargetAgent;\n  language?: string;\n  scenarios?: Scenario[];\n  schedule?: string | null;\n  createdAt?: string;\n  updatedAt?: string;\n}\n\nexport interface PlanView {\n  plan: Plan;\n  priceUsdPerMonth: number;\n  purchasable?: boolean;\n  lookupKey?: string | null;\n  callMinutesPerMonth: number;\n  allowedTransports: Array<'direct' | 'pstn'>;\n  overageUsdPerMinute?: { pstn: number | null; direct: number | null };\n  ttsCharsPerMonth?: number;\n  concurrentCalls?: number;\n  scheduledRuns?: { cadence: 'weekly' | 'daily' | 'hourly'; maxSuites: number | null };\n  apiKeys?: number | null;\n  requiresCard?: boolean;\n}\n\nexport interface PlansResponse {\n  plans: PlanView[];\n  currency: string;\n}\n\nexport interface Subscription {\n  plan: Plan;\n  hasBillingAccount: boolean;\n  usage: { callMinutes: number; ttsChars: number };\n  entitlements: PlanView;\n}\n\nexport interface ApiKeySummary {\n  id: string;\n  name: string;\n  keyPrefix: string;\n  lastUsedAt?: string | null;\n  createdAt?: string;\n}\n\n/** A newly-created key — `token` is present exactly once and never retrievable again. */\nexport interface CreatedApiKey extends ApiKeySummary {\n  token: string;\n}\n\nexport interface TrendPoint {\n  runId: string;\n  score: number | null;\n  passed: boolean | null;\n  at: string | null;\n}\nexport interface RegressionPoint {\n  runId: string;\n  at: string | null;\n  reason: 'pass_to_fail' | 'score_drop';\n  from: number | null;\n  to: number | null;\n}\nexport interface SuiteTrend {\n  suiteId: string;\n  name: string | null;\n  runs: number;\n  passed: number;\n  failed: number;\n  passRate: number | null;\n  avgScore: number | null;\n  regressions: number;\n}\nexport interface SuiteTrendSeries {\n  suiteId: string;\n  name: string | null;\n  points: TrendPoint[];\n  regressions: RegressionPoint[];\n  summary: SuiteTrend;\n}\nexport interface AccountTrends {\n  window: string;\n  totals: {\n    suites: number;\n    runs: number;\n    passed: number;\n    failed: number;\n    passRate: number | null;\n    avgScore: number | null;\n    regressions: number;\n  };\n  suites: SuiteTrend[];\n}\n\n/** Body for the offline transcript-scoring path of {@link WordIsBond.runTest}. */\nexport interface ScoreTranscriptInput {\n  transcript?: string;\n  turns?: Array<{ role: 'agent' | 'caller'; text: string }>;\n  scenarioGoal?: string;\n  assertions?: string[];\n  suiteId?: string | null;\n  language?: string;\n  transport?: 'pstn' | 'webrtc';\n}\n\n/** Body for the live synthetic-call path of {@link WordIsBond.runTest}. */\nexport interface LiveRunInput {\n  targetAgent: TargetAgent;\n  goal?: string;\n  persona?: { name?: string; description: string };\n  suiteId?: string | null;\n  transport?: 'pstn' | 'webrtc';\n  language?: string;\n  concurrency?: number;\n  expected?: string[];\n  bargeIn?: boolean;\n}\n\n/** Result of a live run: either a single completed run or a batch with per-run entries. */\nexport type RunTestResult = TestRun | { runs: TestRun[]; concurrency?: number; transport?: string };\n\nexport interface DemoInput {\n  persona?: { description: string };\n  goal?: string;\n  language?: string;\n  expected?: string[];\n  bargeIn?: boolean;\n}\n\nexport interface CreateSuiteInput {\n  name: string;\n  targetAgent: TargetAgent;\n  language?: string;\n  scenarios?: Scenario[];\n  schedule?: string;\n}\n\ninterface Envelope<T> {\n  data: T | null;\n  error: unknown;\n}\n\n/**\n * Typed client for the Word Is Bond testing API.\n *\n * @example\n * ```ts\n * const wb = new WordIsBond({ apiKey: process.env.WB_API_KEY });\n * const run = await wb.runDemo();\n * console.log(run.score, run.passed, run.reportUrl);\n * ```\n */\nexport class WordIsBond {\n  private readonly apiKey?: string;\n  private readonly baseUrl: string;\n  private readonly fetchImpl: typeof fetch;\n\n  constructor(options: WordIsBondOptions = {}) {\n    this.apiKey = options.apiKey;\n    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\\/$/, '');\n    const f = options.fetch ?? (globalThis.fetch as typeof fetch | undefined);\n    if (!f) {\n      throw new Error('No fetch implementation available — pass one via the `fetch` option.');\n    }\n    this.fetchImpl = f;\n  }\n\n  // ── Meta ─────────────────────────────────────────────────────────────────\n\n  /** Service health (no auth). */\n  health(): Promise<{ status: string; worker?: string; env?: string }> {\n    return this.request('GET', '/health', { auth: false });\n  }\n\n  // ── Billing (source of truth for pricing) ─────────────────────────────────\n\n  /** The plan + entitlement table (no auth). The single source of truth for pricing. */\n  getPlans(): Promise<PlansResponse> {\n    return this.request('GET', '/api/billing/plans', { auth: false });\n  }\n\n  /** Your current plan, usage, and entitlements. */\n  getSubscription(): Promise<Subscription> {\n    return this.request('GET', '/api/billing/subscription');\n  }\n\n  // ── API keys ──────────────────────────────────────────────────────────────\n\n  /** List your active (non-revoked) API keys. */\n  listApiKeys(): Promise<ApiKeySummary[]> {\n    return this.request('GET', '/api/api-keys');\n  }\n\n  /** Create an API key. The returned `token` is shown once — store it securely. */\n  createApiKey(name: string): Promise<CreatedApiKey> {\n    return this.request('POST', '/api/api-keys', { body: { name } });\n  }\n\n  /** Revoke an API key. */\n  revokeApiKey(id: string): Promise<{ revoked: boolean }> {\n    return this.request('DELETE', `/api/api-keys/${encodeURIComponent(id)}`);\n  }\n\n  // ── Testing ────────────────────────────────────────────────────────────────\n\n  /**\n   * Run the hosted demo voice agent end-to-end and get a real, fully-scored result —\n   * no target of your own required. Returns the run plus a shareable report URL.\n   */\n  runDemo(input: DemoInput = {}): Promise<TestRun> {\n    return this.request('POST', '/api/tests/demo', { body: input as Record<string, unknown> });\n  }\n\n  /**\n   * Run a test against a voice agent you control. Pass a {@link ScoreTranscriptInput}\n   * to score a captured transcript offline (returns a completed {@link TestRun}), or a\n   * {@link LiveRunInput} to drive a live synthetic call (returns a run or a batch).\n   */\n  runTest(input: ScoreTranscriptInput | LiveRunInput): Promise<RunTestResult> {\n    return this.request('POST', '/api/tests/run', { body: input as Record<string, unknown> });\n  }\n\n  /** (Re)score a run's transcript with the judge. */\n  rescoreRun(\n    id: string,\n    input: { scenarioGoal?: string; assertions?: string[]; transcript?: string } = {},\n  ): Promise<TestRun> {\n    return this.request('POST', `/api/tests/${encodeURIComponent(id)}/score`, { body: input });\n  }\n\n  /** Trigger the hosted self-test now and publish a public report. */\n  runCanary(): Promise<{ runId: string; score: number | null; passed: boolean | null; reportUrl: string }> {\n    return this.request('POST', '/api/tests/canary');\n  }\n\n  /** Fetch one run — poll here for the terminal scored state of a live run. */\n  getRun(id: string): Promise<TestRun> {\n    return this.request('GET', `/api/tests/${encodeURIComponent(id)}`);\n  }\n\n  /** List your most recent runs (up to 100). */\n  listRuns(): Promise<TestRun[]> {\n    return this.request('GET', '/api/tests');\n  }\n\n  // ── Suites ───────────────────────────────────────────────────────────────\n\n  /** List your reusable test suites. */\n  listSuites(): Promise<TestSuite[]> {\n    return this.request('GET', '/api/tests/suites');\n  }\n\n  /** Create a reusable test suite. */\n  createSuite(input: CreateSuiteInput): Promise<TestSuite> {\n    return this.request('POST', '/api/tests/suites', { body: input as unknown as Record<string, unknown> });\n  }\n\n  /** Fetch one suite. */\n  getSuite(id: string): Promise<TestSuite> {\n    return this.request('GET', `/api/tests/suites/${encodeURIComponent(id)}`);\n  }\n\n  // ── Trends ───────────────────────────────────────────────────────────────\n\n  /** Per-suite time series + run-to-run regression flags. */\n  getSuiteTrends(id: string): Promise<SuiteTrendSeries> {\n    return this.request('GET', `/api/tests/suites/${encodeURIComponent(id)}/trends`);\n  }\n\n  /** Account-wide pass-rate, average score, and regressions over a window (default 90 days). */\n  getTrends(opts: { days?: number } = {}): Promise<AccountTrends> {\n    const q = opts.days ? `?days=${Math.trunc(opts.days)}` : '';\n    return this.request('GET', `/api/tests/trends${q}`);\n  }\n\n  // ── Reports ──────────────────────────────────────────────────────────────\n\n  /** Get the shareable public report URL for one of your runs. */\n  getReportLink(id: string): Promise<{ url: string }> {\n    return this.request('GET', `/api/reports/${encodeURIComponent(id)}/link`);\n  }\n\n  // ── Internal ─────────────────────────────────────────────────────────────\n\n  private async request<T>(\n    method: string,\n    path: string,\n    opts: { body?: Record<string, unknown>; auth?: boolean } = {},\n  ): Promise<T> {\n    const auth = opts.auth !== false;\n    const headers: Record<string, string> = { accept: 'application/json' };\n    if (auth) {\n      if (!this.apiKey) {\n        throw new WordIsBondError(0, `${method} ${path} requires an API key — construct the client with { apiKey }.`);\n      }\n      headers['authorization'] = `Bearer ${this.apiKey}`;\n    }\n    if (opts.body !== undefined) headers['content-type'] = 'application/json';\n\n    let res: Response;\n    try {\n      res = await this.fetchImpl(`${this.baseUrl}${path}`, {\n        method,\n        headers,\n        body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,\n      });\n    } catch (err) {\n      throw new WordIsBondError(0, `Network error calling ${method} ${path}: ${(err as Error).message}`);\n    }\n\n    const text = await res.text();\n    let json: Envelope<T> | undefined;\n    try {\n      json = text ? (JSON.parse(text) as Envelope<T>) : undefined;\n    } catch {\n      json = undefined;\n    }\n\n    if (!res.ok) {\n      const err = json?.error;\n      const message =\n        typeof err === 'string'\n          ? err\n          : err && typeof err === 'object' && 'message' in err\n            ? String((err as { message: unknown }).message)\n            : `Request failed with status ${res.status}`;\n      const code = err && typeof err === 'object' && 'code' in err ? String((err as { code: unknown }).code) : undefined;\n      throw new WordIsBondError(res.status, message, { code, body: json ?? text });\n    }\n\n    // Successful responses are the { data, error } envelope; hand back `data`.\n    if (json && typeof json === 'object' && 'data' in json) {\n      return json.data as T;\n    }\n    return json as unknown as T;\n  }\n}\n\nexport default WordIsBond;\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@latimer-woods-tech/wordis-bond",
+  "version": "0.1.0",
+  "description": "Typed TypeScript client for the Word Is Bond voice-agent testing API.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Adrian Perry <aperry@latwoodtech.com>",
+  "homepage": "https://github.com/Latimer-Woods-Tech/wordis-bond/tree/main/packages/sdk",
+  "bugs": {
+    "url": "https://github.com/Latimer-Woods-Tech/wordis-bond/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Latimer-Woods-Tech/wordis-bond.git",
+    "directory": "packages/sdk"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "keywords": [
+    "voice-agent",
+    "voice-agent-testing",
+    "testing",
+    "wordis-bond",
+    "api-client",
+    "sdk",
+    "mcp",
+    "typescript",
+    "esm"
+  ],
+  "devDependencies": {
+    "tsup": "^8.3.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.2.6"
+  }
+}