@insightlabai.dev/sdk

@insightlabai.dev/sdk

Find UX bugs before your users do — from your own code. A typed client for the InsightLab API: point synthetic users at a URL, have them attempt a task, and get back severity-ranked findings. Works in any Node 20+ codebase or test suite, ESM or CommonJS, zero runtime dependencies.

npm install @insightlabai.dev/sdk

Setup

Create an API key at insightlabai.dev/demo. The client reads INSIGHTLAB_API_KEY from the environment, or you can pass it in.

Run a test

import { InsightLab } from "@insightlabai.dev/sdk";

const insightlab = new InsightLab(); // reads INSIGHTLAB_API_KEY

const { findings } = await insightlab.run({
  url: "https://staging.acme.com",
  task: "sign up and reach the dashboard",
  audience: "first-time users, low patience",
  agents: 5,
});

for (const f of findings) {
  console.log(`[${f.severity}] ${f.observation} — ${f.recommendation}`);
}

run() starts the test and waits for it to finish (a few minutes). Findings come back in idiomatic camelCase, ranked Critical, Major, or Minor.

Gate a test suite or CI job

import { InsightLab, hasFindingAtOrAbove } from "@insightlabai.dev/sdk";

test("checkout has no critical usability issues", async () => {
  const { findings } = await new InsightLab().run({
    url: process.env.PREVIEW_URL!,
    task: "complete checkout",
  });
  expect(hasFindingAtOrAbove(findings, "Critical")).toBe(false);
});

Control the polling yourself

const { runId } = await insightlab.startRun({ url, task: "find the search bar" });

// …do other work, then check whenever you like
const snapshot = await insightlab.getRun(runId);
// snapshot.findings is null until the run finishes — null means "not done", not "no problems".

run() also takes options:

await insightlab.run(input, {
  pollIntervalMs: 5000,
  timeoutMs: 15 * 60_000,
  signal: controller.signal,               // stop waiting (the run keeps going server-side)
  onProgress: ({ completed, total }) => console.log(`${completed}/${total} agents`),
});

Configuration

new InsightLab({
  apiKey: "il_live_...",                     // default: process.env.INSIGHTLAB_API_KEY
  baseUrl: "https://insightlabai.dev",       // default: process.env.INSIGHTLAB_API_URL, else this
  fetch: customFetch,                        // default: global fetch
});

Errors

Every error extends InsightLabError, so one catch covers them all:

Class	When
AuthError	The API key is missing or rejected.
RateLimitError	You are being rate limited.
RunFailedError	The run itself failed server-side.
TimeoutError	run() hit its timeout before the run finished.

Types

Finding, RunResult, RunSnapshot, RunInput, RunOptions, Severity, and SEVERITY_ORDER are all exported.