TypeScript SDK

The official TypeScript/JavaScript SDK for smarts.bio. Works in Node.js 18+ and modern browsers. Uses native fetch with no runtime dependencies.

Installation

npm install @smartsbio/sdk

Requires Node.js 18+ (for native fetch andAsyncGenerator) or a modern browser. Fully typed — no @types package needed.

Quick start

import { SmartsBio } from '@smartsbio/sdk';

const client = new SmartsBio({ apiKey: 'sk_live_...' });

// Discover your workspaces
const workspaces = await client.workspaces.list();
const wsId = workspaces[0].id;

// Run a query
const response = await client.query.run({
    prompt: 'Find BRCA1 variants associated with hereditary breast cancer',
    workspaceId: wsId,
});
console.log(response.content);

Streaming

Use client.query.stream() which returns anAsyncGenerator<StreamChunk>. Works in both Node.js and the browser.

import { SmartsBio } from '@smartsbio/sdk';

const client = new SmartsBio({ apiKey: 'sk_live_...' });

for await (const chunk of client.query.stream({
    prompt: 'Perform a comprehensive variant analysis on the uploaded VCF',
    workspaceId: 'ws_abc123',
})) {
    if (chunk.type === 'status') {
        process.stdout.write(`[\033[33m${chunk.content}\033[0m]\n`);
    } else if (chunk.type === 'content') {
        process.stdout.write(chunk.content ?? '');
    } else if (chunk.type === 'done') {
        process.stdout.write('\n');
    }
}

StreamChunk types

type	content	Description
'status'	string	Agent status message (e.g., "Searching databases...")
'content'	string	Streamed response text fragment
'tool_use'	object	Agent invoked a tool — contains tool name and input
'done'	undefined	Stream complete

Tools, files, and conversations

// List available tools
const tools = await client.tools.list();
tools.forEach(t => console.log(`${t.id}: ${t.description}`));

// Run a tool directly
const result = await client.tools.run('ncbi_search', {
    input: { database: 'pubmed', query: 'CRISPR off-target', maxResults: 10 },
});
console.log(result);

Error handling

import {
    SmartsBio,
    AuthenticationError,
    PermissionDeniedError,
    RateLimitError,
    APIError,
} from '@smartsbio/sdk';

const client = new SmartsBio({ apiKey: 'sk_live_...' });

try {
    const response = await client.query.run({ prompt: 'Analyze...' });
    console.log(response.content);
} catch (err) {
    if (err instanceof AuthenticationError) {
        console.error('Invalid or revoked API key');
    } else if (err instanceof PermissionDeniedError) {
        console.error('Key lacks required scope:', err.message);
    } else if (err instanceof RateLimitError) {
        console.error(`Rate limited — retry after ${err.retryAfter}s`);
    } else if (err instanceof APIError) {
        console.error(`API error ${err.statusCode}: ${err.message}`);
    } else {
        throw err;
    }
}

Configuration options

import { SmartsBio } from '@smartsbio/sdk';

const client = new SmartsBio({
    apiKey: 'sk_live_...',                 // or set SMARTSBIO_API_KEY env var
    baseUrl: 'https://api.smarts.bio',     // default
    timeout: 120_000,                       // ms (default: 120,000)
    maxRetries: 3,                          // retries on 5xx (default: 3)
});

Exported types

import type {
    SmartsBioOptions,
    QueryParams,
    QueryResponse,
    StreamChunk,
    Tool,
    Workspace,
    Conversation,
    WorkspaceFile,
    ListFilesParams,
} from '@smartsbio/sdk';