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
npm install danube
Quick Start
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:// 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
import { DanubeClient } from 'danube';
const client = new DanubeClient({ apiKey: 'dk_your_api_key' });
API Reference
Services
// 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
// 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
// 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
// Get user identity
const identity = await client.identity.get();
console.log(`Profile: ${JSON.stringify(identity.profile)}`);
console.log(`Contacts: ${identity.contacts.length}`);
Workflows
// 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
// 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
// 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
// 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:// 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: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 |
const client = new DanubeClient({
apiKey: 'dk_...',
baseUrl: 'https://api.danubeai.com',
timeout: 60,
maxRetries: 5,
});
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 |
