Skip to main content

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
Get your API key from the Danube Dashboard.

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

ErrorStatus CodeDescription
AuthenticationError401Invalid or missing API key
AuthorizationError403Permission denied
ConfigurationRequiredError403Service needs credential setup
NotFoundError404Resource not found
ValidationError400Invalid request parameters
RateLimitError429Rate limit exceeded
ExecutionError500Tool execution failure
DanubeConnectionError503Cannot connect to API
DanubeTimeoutError504Request timed out

Configuration Options

ParameterEnvironment VariableDefaultDescription
apiKeyDANUBE_API_KEY(required)Your Danube API key
baseUrlDANUBE_API_URLhttps://api.danubeai.comAPI base URL
timeoutDANUBE_TIMEOUT30Request timeout (seconds)
maxRetriesDANUBE_MAX_RETRIES3Max retry attempts
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

FieldTypeDescription
idstringService UUID
namestringService name
descriptionstringService description
serviceTypestring"mcp_server", "api", "internal", or "website"
toolCountnumberNumber of available tools
isConnectedbooleanWhether MCP service is connected

Tool

FieldTypeDescription
idstringTool UUID
namestringTool name
descriptionstringTool description
serviceIdstringParent service ID
parametersobjectParameter definitions

ToolResult

FieldTypeDescription
successbooleanWhether execution succeeded
resultunknownExecution result
errorstringError message (if failed)
toolNamestringName of executed tool
durationMsnumberExecution time

Workflow

FieldTypeDescription
idstringWorkflow UUID
namestringWorkflow name
descriptionstringWorkflow description
stepCountnumberNumber of steps
visibilitystring"public" or "private"
tagsstring[]Workflow tags
totalExecutionsnumberTotal execution count

WorkflowExecution

FieldTypeDescription
idstringExecution UUID
workflowIdstringParent workflow ID
statusstring"pending", "running", "success", or "failed"
inputsobjectInput values provided
stepResultsWorkflowStepResult[]Per-step results
errorstringError message (if failed)
executionTimeMsnumberTotal execution time

AgentSite

FieldTypeDescription
idstringSite UUID
domainstringSite domain
urlstringFull URL
statusstring"pending", "crawling", "analyzed", or "live"
componentsSiteComponentsStructured site data (contact, pricing, docs, etc.)
categorystringSite category
tagsstring[]Site tags

Source Code

The SDK is open source and available on GitHub: