# TypeScript SDK

The official TypeScript SDK provides type-safe access to the Chaser API for session management, workspaces, command execution, file operations, browser CDP, accounts, billing, webhooks, audit, and jobs.

## Install

```bash
npm install chaser-sdk
```

## Create a client

```typescript
import { ChaserClient } from "chaser-sdk";

const client = new ChaserClient({
  apiKey: process.env.CHASER_API_KEY,
  account: "personal"  // or an organization name
});
```

The `account` parameter maps to the `X-Chaser-Account` header, so one client can target a personal or organization context.

## Sessions

```typescript
// Create a browser session
const browser = await client.sessions.create({
  session_type: "browser",
  ephemeral: true
});

// Create a sandbox session with a workspace
const sandbox = await client.sessions.create({
  session_type: "sandbox",
  workspace: "my-project"
});

// Wait for the session to be ready
await client.sessions.waitUntilReady(sandbox.id);

// Runtime self-test
const diagnostics = await client.sessions.selfTest(sandbox.id);
console.log(diagnostics.runtime.tools.node);
```

## Command execution

```typescript
// Run in an existing session
const result = await client.exec.inSession(sandbox.id, {
  command: "npm ci && npm test",
  cwd: "/workspace"
});

// Run with auto-provisioned ephemeral sandbox
const result = await client.exec.run({
  ephemeral: true,
  image: "node:20-bookworm",
  command: "node -e \"console.log(42)\""
});

console.log(result.output);
```

## Workspaces

```typescript
// Create a workspace
const workspace = await client.workspaces.create({
  name: "frontend-app",
  session_type: "sandbox",
  image: "ghcr.io/example/dev:latest"
});

// Create a snapshot
await client.workspaces.snapshots.create("frontend-app", {
  name: "before-upgrade"
});

// Clone from a template
await client.workspaces.create({
  clone_from: "frontend-app",
  name: "frontend-app-feature"
});
```

## Files

```typescript
await client.files.uploadText(session.id, "/workspace/hello.txt", "hello");
const text = await client.files.downloadText(session.id, "/workspace/hello.txt");
```

## Port forwarding

```typescript
const url = client.sessions.forwardUrl(session.id, 3000);
// => https://<session_id>.chaser.sh/forward/3000/
```

## Browser CDP

```typescript
const browser = await client.sessions.create({
  session_type: "browser",
  ephemeral: true
});

const cdp = await client.browser.connect(browser.id);
await cdp.send("Browser.getVersion");
cdp.close();
```

`client.browser.connect()` waits for readiness, fetches `/json/version`, and opens a WebSocket CDP connection.

## Organizations and service accounts

```typescript
const orgClient = client.withAccount("Acme Engineering");

const sa = await orgClient.accounts.serviceAccounts.create("ci-bot");
const key = await orgClient.accounts.serviceAccounts.keys.create(sa.id, {
  name: "ci-key",
  scopes: ["sessions.read", "workspaces.write", "exec.write"]
});
```

## Scope

The SDK covers the core Chaser API surface. It does not include CHASM assistant management or act as an MCP transport wrapper. For MCP usage, call `POST /v1/mcp` directly.