stablebrowse (TypeScript)

TypeScript / JavaScript client for the stablebrowse browser agent API.

Install

From npm:

npm install @stablebrowse/client

From source (for local development):

cd sdks/typescript
npm install
npm run build
# Then in the consuming project:
npm install /path/to/stablebrowse-agent/sdks/typescript

Requires Node 18+ (uses native fetch). Works in any fetch-capable runtime — Node, Deno, Cloudflare Workers, Bun, modern browsers.

Quick start

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

// Bearer token comes from either the constructor or the
// STABLEBROWSE_API_KEY environment variable.
const client = new Stablebrowse({ apiKey: "sb_live_..." });

// (Optional) upload per-end-user social creds.
await client.endUsers("alice").credentials.set({
  twitterAuthToken: "...",
  twitterCt0: "...",
});

// Sync-feeling submit. Polls internally until the task terminates.
const result = await client.tasks.run({
  endUserId: "alice",
  task: "find the top AI tweets today",
});
console.log(result.result);

Async primitives

If you want to drive the poll loop yourself:

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

Multi-turn conversations

Pass the returned sessionId back on subsequent calls to continue a thread:

const first = await client.tasks.run({ endUserId: "alice", task: "who's trending on X?" });
const follow = await client.tasks.run({
  endUserId: "alice",
  task: "what about in music specifically?",
  sessionId: first.sessionId,
});

End users and credentials

const alice = client.endUsers("alice");

await alice.credentials.set({
  tiktokSessionId: "...",
  tiktokCsrfToken: "...",
});

const status = await alice.credentials.get();
// status.platforms = { twitter: false, reddit: false, tiktok: true, instagram: false }

// Clear everything:
await alice.credentials.delete();
// Or a subset:
await alice.credentials.delete(["twitterAuthToken", "twitterCt0"]);

API key management

Create and revoke keys in the dashboard under Settings → API Keys. Key lifecycle is dashboard-only by design — a leaked key can't mint more.

Errors

Every exception extends StablebrowseError:

• TaskFailed — run() saw the task finish with status=failed. Access the failed Task via .task.
• TaskTimeout — the poll deadline expired before the task terminated. The still-running Task is on .task, so you can keep polling.
• StablebrowseError — every other HTTP or transport error. .statusCode and .body are populated when the server returned JSON.

Configuration

Environment variables the constructor reads if not passed explicitly:

• STABLEBROWSE_API_KEY — bearer token
• STABLEBROWSE_BASE_URL — API base override (beta / local gateway)

Timeout defaults:

| Option | Default | Notes | | ----------------- | -------- | ---------------------------------------- | | timeoutMs | 30_000 | per-HTTP-request | | pollIntervalMs | 2_000 | tasks.run() poll cadence | | pollTimeoutMs | 300_000 | tasks.run() total wait |