TypeScript SDK

npm install @stablebrowse/client

import { Stablebrowse } from "@stablebrowse/client";

// Explicit
const client = new Stablebrowse({ apiKey: "sb_live_..." });

// Or read from env (Node only):
//   STABLEBROWSE_API_KEY   — the bearer token
//   STABLEBROWSE_BASE_URL  — override API base
const client = new Stablebrowse();

const result = await client.tasks.run({
  endUserId: "alice",
  task: "Give me the top 3 Show HN posts from today",
});
console.log(result.result);

const submission = await client.tasks.submit({
  endUserId: "alice",
  task: "...",
});
while (true) {
  const task = await client.tasks.get(submission.taskId);
  if (["completed", "failed", "cancelled"].includes(task.status)) break;
  await new Promise(r => setTimeout(r, 2000));
}
console.log(task.result);

const result = await client.tasks.run({
  endUserId: "alice",
  task: "Summarize this article",
  sessionId: "s_abc...",                // continue existing session
  startUrl: "https://example.com/x",    // skip URL-discovery
  schema: { type: "object" /* ... */ }, // structured output
  maxSteps: 10,                         // ≤ 25, server-clamped
  includeHtmlDump: true,                // return raw HTML
  pollIntervalMs: 2000,
  pollTimeoutMs: 300_000,
});

const first = await client.tasks.run({
  endUserId: "alice",
  task: "Who's trending on HN?",
});
const follow = await client.tasks.run({
  endUserId: "alice",
  task: "What's the score on the top one?",
  sessionId: first.sessionId,
});

const session = await client.sessions.get(first.sessionId!);
for (const t of session.tasks) {
  console.log(t.status, t.task);
}

const task = await client.design.run({
  url: "https://www.figma.com/",
  endUserId: "alice",
  extractors: ["colors", "fonts", "logo"], // omit to run all six
  enableIpRotation: true,                  // optional
});
console.log(task.design?.results.colors);

const submission = await client.design.submit({
  url: "https://www.figma.com/",
  endUserId: "alice",
  enableIpRotation: true,
});
// ... later — design tasks ride the same task record as agent tasks
const task = await client.tasks.get(submission.taskId);
if (task.status === "completed") console.log(task.design);

const task = await client.design.run({
  url: "https://www.figma.com/",
  endUserId: "alice",
  extractors: ["images", "fonts", "colors", "icons", "tokens", "logo"],
  enableIpRotation: true,
  pollIntervalMs: 2000,
  pollTimeoutMs: 300_000,
});

// Upload — only platforms you pass are touched
await client.endUsers("alice").credentials.set({
  twitterAuthToken: "...",
  twitterCt0: "...",
});

// Status (never returns secrets)
const status = await client.endUsers("alice").credentials.get();
// status.platforms.twitter === true

// Clear
await client.endUsers("alice").credentials.delete(["twitterAuthToken", "twitterCt0"]);
await client.endUsers("alice").credentials.delete();  // wipe all

import { StablebrowseError, TaskFailed, TaskTimeout } from "@stablebrowse/client";

try {
  const result = await client.tasks.run({ endUserId: "alice", task: "..." });
} catch (e) {
  if (e instanceof TaskFailed) {
    console.log("Agent reported failure:", e.task.error);
  } else if (e instanceof TaskTimeout) {
    console.log("Poll deadline reached, task still", e.task.status);
  } else if (e instanceof StablebrowseError) {
    console.log("HTTP/transport error:", e.statusCode, e.body);
  } else {
    throw e;
  }
}

const task = await client.tasks.get(taskId);
task.status;                // typed
task.result;                // typed
(task.raw as any).someNewField;  // future-proof

// package.json
"dependencies": {
  "@stablebrowse/client": "^0.1.2"  // patches only
}