> ## Documentation Index
> Fetch the complete documentation index at: https://docs.danubeai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> Official TypeScript/JavaScript SDK for Danube AI

# TypeScript SDK

The official TypeScript SDK for Danube AI provides a fully-typed interface for accessing services, tools, workflows, skills, sites, and more through the Danube platform. Works with both TypeScript and JavaScript in Node.js environments.

## Installation

```bash theme={null}
npm install danube
```

## Quick Start

```typescript theme={null}
import { DanubeClient } from 'danube';

// Initialize with API key (or set DANUBE_API_KEY environment variable)
const client = new DanubeClient({ apiKey: 'dk_...' });

// List available services
const services = await client.services.list({ limit: 5 });
for (const service of services) {
  console.log(`${service.name}: ${service.toolCount} tools`);
}

// Search for tools
const tools = await client.tools.search('send email');

// Execute a tool
const result = await client.tools.execute({
  toolName: 'Gmail - Send Email',
  parameters: {
    to: 'user@example.com',
    subject: 'Hello from Danube!',
  },
});

if (result.success) {
  console.log(result.result);
} else {
  console.log(`Error: ${result.error}`);
}

// Clean up when done
client.close();
```

## Authentication

The SDK uses your Danube API key for authentication. You can provide it in two ways:

<CodeGroup>
  ```typescript Environment Variable theme={null}
  // Set DANUBE_API_KEY in your environment
  // export DANUBE_API_KEY=dk_your_api_key

  import { DanubeClient } from 'danube';
  const client = new DanubeClient(); // Uses DANUBE_API_KEY automatically
  ```

  ```typescript Constructor Parameter theme={null}
  import { DanubeClient } from 'danube';
  const client = new DanubeClient({ apiKey: 'dk_your_api_key' });
  ```
</CodeGroup>

Get your API key from the [Danube Dashboard](https://danubeai.com/dashboard/api-keys).

## API Reference

### Services

```typescript theme={null}
// List/search services
const services = await client.services.list({ query: 'github', limit: 10 });

// Get a specific service
const service = await client.services.get('service-uuid');

// Get tools for a service
const result = await client.services.getTools('service-uuid');
if (result.needsConfiguration) {
  console.log('Service needs credential configuration');
} else {
  for (const tool of result.tools) {
    console.log(tool.name);
  }
}
```

### Tools

```typescript theme={null}
// Search for tools
const tools = await client.tools.search('send email', { serviceId: 'optional-filter' });

// Get a specific tool
const tool = await client.tools.get('tool-uuid');

// Execute by ID (faster)
const result = await client.tools.execute({
  toolId: 'tool-uuid',
  parameters: { key: 'value' },
});

// Execute by name (searches first)
const result = await client.tools.execute({
  toolName: 'Gmail - Send Email',
  parameters: { to: 'user@example.com' },
});

// Check result
if (result.success) {
  console.log(result.result);
  console.log(`Took ${result.durationMs}ms`);
} else {
  console.log(`Error: ${result.error}`);
}

// Batch execute (up to 10 calls)
const results = await client.tools.batchExecute([
  { toolId: 'tool-uuid-1', toolInput: { city: 'San Francisco' } },
  { toolId: 'tool-uuid-2', toolInput: { city: 'New York' } },
]);
for (const r of results) {
  console.log(`${r.toolId}: ${r.success ? 'ok' : r.error}`);
}
```

### Skills

```typescript theme={null}
// Search for skills
const skills = await client.skills.search('pdf processing');

// Get full skill content by ID
const skill = await client.skills.get({ skillId: 'skill-uuid' });
// or by name
const skill = await client.skills.get({ skillName: 'pdf-processing' });

console.log(`Instructions:\n${skill.skillMd}`);

for (const script of skill.scripts) {
  console.log(`Script: ${script.name}`);
  console.log(script.content);
}
```

### Identity

```typescript theme={null}
// Get user identity
const identity = await client.identity.get();
console.log(`Profile: ${JSON.stringify(identity.profile)}`);
console.log(`Contacts: ${identity.contacts.length}`);
```

### Workflows

```typescript theme={null}
// List public workflows
const workflows = await client.workflows.list({ query: 'data pipeline', limit: 10 });

// Get a specific workflow
const workflow = await client.workflows.get('workflow-uuid');

// Execute a workflow with inputs
const execution = await client.workflows.execute('workflow-uuid', {
  query: 'latest news',
});
console.log(`Status: ${execution.status}`);

for (const step of execution.stepResults) {
  console.log(`Step ${step.stepNumber}: ${step.status}`);
}

// Get a past execution result
const past = await client.workflows.getExecution('execution-uuid');
console.log(`Completed in ${past.executionTimeMs}ms`);

// Create a workflow
const created = await client.workflows.create({
  name: 'My Pipeline',
  steps: [
    {
      stepNumber: 1,
      toolId: 'tool-uuid',
      toolName: 'Weather - Get Forecast',
      description: 'Fetch forecast',
      inputMapping: { city: '{{inputs.city}}' },
    },
  ],
  visibility: 'private',
  tags: ['weather'],
});

// Update a workflow
const updated = await client.workflows.update('workflow-uuid', {
  name: 'Renamed Pipeline',
});

// Delete a workflow
await client.workflows.delete('workflow-uuid');
```

### Sites

```typescript theme={null}
// Search the agent-friendly site directory
const sites = await client.sites.search({ query: 'payments', limit: 10 });

// Get a site by ID
const site = await client.sites.get('site-uuid');
console.log(`${site.domain}: ${site.status}`);

// Get a site by domain
const site = await client.sites.getByDomain('stripe.com');
if (site.components.pricing) {
  console.log(`Pricing: ${JSON.stringify(site.components.pricing)}`);
}
```

### Credentials

```typescript theme={null}
// Store a credential for a service
const stored = await client.credentials.store({
  serviceId: 'service-uuid',
  credentialType: 'api_key',
  credentialValue: 'sk-...',
});
console.log(`Stored for ${stored.serviceName}: ${stored.success}`);
```

### Wallet

```typescript theme={null}
// Get wallet balance
const balance = await client.wallet.getBalance();
console.log(`Balance: $${balance.balanceDollars}`);

// Get transaction history
const transactions = await client.wallet.getTransactions({ limit: 20 });
for (const tx of transactions) {
  console.log(`${tx.type}: ${tx.amountCents} cents`);
}
```

### Agents

Register autonomous agents with their own API keys and USDC wallets:

```typescript theme={null}
// Register a new autonomous agent
const agent = await client.agents.register({
  name: 'MyBot',
  operatorEmail: 'operator@example.com',
});
console.log(`Agent ID: ${agent.agentId}`);
console.log(`API Key: ${agent.apiKey}`);

// Get agent info (requires agent's API key)
const info = await client.agents.getInfo();

// Fund the agent's wallet
const funding = await client.agents.fundWallet({
  method: 'card_checkout',
  amountCents: 10000,
});
if (funding.checkoutUrl) {
  console.log(`Complete payment: ${funding.checkoutUrl}`);
}
```

## Error Handling

The SDK provides specific error types for different error conditions:

```typescript theme={null}
import { DanubeClient, AuthenticationError, NotFoundError, ExecutionError, RateLimitError, ConfigurationRequiredError } from 'danube';

const client = new DanubeClient();

try {
  const result = await client.tools.execute({ toolId: 'invalid-id' });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.log('Invalid API key');
  } else if (error instanceof NotFoundError) {
    console.log(`Not found: ${error.resource} ${error.identifier}`);
  } else if (error instanceof ExecutionError) {
    console.log(`Execution failed: ${error.message}`);
  } else if (error instanceof ConfigurationRequiredError) {
    console.log(`Configure credentials for service: ${error.serviceId}`);
  } else if (error instanceof RateLimitError) {
    if (error.retryAfter) {
      console.log(`Rate limited. Retry in ${error.retryAfter}s`);
    }
  }
}
```

### Error Types

| Error                        | Status Code | Description                    |
| ---------------------------- | ----------- | ------------------------------ |
| `AuthenticationError`        | 401         | Invalid or missing API key     |
| `AuthorizationError`         | 403         | Permission denied              |
| `ConfigurationRequiredError` | 403         | Service needs credential setup |
| `NotFoundError`              | 404         | Resource not found             |
| `ValidationError`            | 400         | Invalid request parameters     |
| `RateLimitError`             | 429         | Rate limit exceeded            |
| `ExecutionError`             | 500         | Tool execution failure         |
| `DanubeConnectionError`      | 503         | Cannot connect to API          |
| `DanubeTimeoutError`         | 504         | Request timed out              |

## Configuration Options

| Parameter    | Environment Variable | Default                    | Description               |
| ------------ | -------------------- | -------------------------- | ------------------------- |
| `apiKey`     | `DANUBE_API_KEY`     | (required)                 | Your Danube API key       |
| `baseUrl`    | `DANUBE_API_URL`     | `https://api.danubeai.com` | API base URL              |
| `timeout`    | `DANUBE_TIMEOUT`     | `30`                       | Request timeout (seconds) |
| `maxRetries` | `DANUBE_MAX_RETRIES` | `3`                        | Max retry attempts        |

```typescript theme={null}
const client = new DanubeClient({
  apiKey: 'dk_...',
  baseUrl: 'https://api.danubeai.com',
  timeout: 60,
  maxRetries: 5,
});
```

The SDK automatically retries failed requests with exponential backoff on rate limits (429) and server errors (502, 503, 504).

## Models

### Service

| Field         | Type    | Description                                           |
| ------------- | ------- | ----------------------------------------------------- |
| `id`          | string  | Service UUID                                          |
| `name`        | string  | Service name                                          |
| `description` | string  | Service description                                   |
| `serviceType` | string  | `"mcp_server"`, `"api"`, `"internal"`, or `"website"` |
| `toolCount`   | number  | Number of available tools                             |
| `isConnected` | boolean | Whether MCP service is connected                      |

### Tool

| Field         | Type   | Description           |
| ------------- | ------ | --------------------- |
| `id`          | string | Tool UUID             |
| `name`        | string | Tool name             |
| `description` | string | Tool description      |
| `serviceId`   | string | Parent service ID     |
| `parameters`  | object | Parameter definitions |

### ToolResult

| Field        | Type    | Description                 |
| ------------ | ------- | --------------------------- |
| `success`    | boolean | Whether execution succeeded |
| `result`     | unknown | Execution result            |
| `error`      | string  | Error message (if failed)   |
| `toolName`   | string  | Name of executed tool       |
| `durationMs` | number  | Execution time              |

### Workflow

| Field             | Type      | Description               |
| ----------------- | --------- | ------------------------- |
| `id`              | string    | Workflow UUID             |
| `name`            | string    | Workflow name             |
| `description`     | string    | Workflow description      |
| `stepCount`       | number    | Number of steps           |
| `visibility`      | string    | `"public"` or `"private"` |
| `tags`            | string\[] | Workflow tags             |
| `totalExecutions` | number    | Total execution count     |

### WorkflowExecution

| Field             | Type                  | Description                                          |
| ----------------- | --------------------- | ---------------------------------------------------- |
| `id`              | string                | Execution UUID                                       |
| `workflowId`      | string                | Parent workflow ID                                   |
| `status`          | string                | `"pending"`, `"running"`, `"success"`, or `"failed"` |
| `inputs`          | object                | Input values provided                                |
| `stepResults`     | WorkflowStepResult\[] | Per-step results                                     |
| `error`           | string                | Error message (if failed)                            |
| `executionTimeMs` | number                | Total execution time                                 |

### AgentSite

| Field        | Type           | Description                                          |
| ------------ | -------------- | ---------------------------------------------------- |
| `id`         | string         | Site UUID                                            |
| `domain`     | string         | Site domain                                          |
| `url`        | string         | Full URL                                             |
| `status`     | string         | `"pending"`, `"crawling"`, `"analyzed"`, or `"live"` |
| `components` | SiteComponents | Structured site data (contact, pricing, docs, etc.)  |
| `category`   | string         | Site category                                        |
| `tags`       | string\[]      | Site tags                                            |

## Source Code

The SDK is open source and available on GitHub:

* [GitHub Repository](https://github.com/danubeai/danube-ts)
* [npm Package](https://www.npmjs.com/package/danube)