AgentDB JavaScript/TypeScript SDK

A lightweight JavaScript/TypeScript SDK for the AgentDB database service. This SDK provides a simple interface for listing databases and executing SQL statements against SQLite and DuckDB databases.

Features

- Fetch-only: Uses only the native fetch API, no external dependencies
- Async/Await: Modern promise-based API
- Error Handling: Comprehensive error handling with custom exception types
- Full TypeScript Support: Written in TypeScript with complete type definitions
- Dual Module Support: Supports both ES modules and CommonJS
- Multi-Database: Supports both SQLite and DuckDB databases
- Vector Support: Built-in utilities for vector operations and embeddings
- Template Management: Create, manage, and apply database templates
- Natural Language to SQL: Convert natural language queries to SQL
- MCP Integration: Create and manage MCP server URL slugs
- Debug Mode: Built-in debug logging with server-side debug information

Installation

``bash
npm install @agentdb/sdk
`

Quick Start

$3

`javascript
import { DatabaseService } from '@agentdb/sdk';

// Create a service instance
const service = new DatabaseService('https://api.agentdb.dev', 'your-api-key');

// List databases for a token
const databases = await service.listDatabases('your-uuid-token');
console.log('Available databases:', databases);

// Create a connection
const connection = service.connect('your-uuid-token', 'my-database', 'sqlite');

// Execute SQL statements
const result = await connection.execute([
{
sql: 'CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)',
params: []
},
{
sql: 'INSERT INTO users (name) VALUES (?)',
params: ['John Doe']
}
]);

console.log('Execution result:', result);
`

$3

`typescript
import { DatabaseService, DatabaseInfo, ExecuteResult } from '@agentdb/sdk';

// Create a service instance with full type safety
const service = new DatabaseService('https://api.agentdb.dev', 'your-api-key');

// List databases with typed response
const databases: DatabaseInfo[] = await service.listDatabases('your-uuid-token');
console.log('Available databases:', databases);

// Create a connection
const connection = service.connect('your-uuid-token', 'my-database', 'sqlite');

// Execute SQL statements with typed results
const result: ExecuteResult = await connection.execute([
{
sql: 'CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)',
params: []
},
{
sql: 'INSERT INTO users (name) VALUES (?)',
params: ['John Doe']
}
]);

console.log('Execution result:', result);
`

$3

`javascript
const { DatabaseService } = require('@agentdb/sdk');

// Create a service instance
const service = new DatabaseService('https://api.agentdb.dev', 'your-api-key');

// Use the same API as ES modules
const databases = await service.listDatabases('your-uuid-token');
console.log('Available databases:', databases);
`

API Reference

$3

The main service class for listing databases and creating connections.

#### Constructor

`javascript
new DatabaseService(baseUrl, apiKey, debug = false)
`

- baseUrl (string): The base URL of the AgentDB service
- apiKey (string): Your API key for authentication
- debug (boolean, optional): Enable debug logging (default: false)

#### Methods

##### listDatabases(token)

Lists all databases for a given token.

- token (string): The UUID token for database access
- Returns: Promise - Array of database objects

`javascript
const databases = await service.listDatabases('uuid-token');
// Returns: [{ name: 'db1', type: 'sqlite', fileName: 'db1.sqlite', size: 8192, modified: '2024-01-01T00:00:00.000Z' }]
`

##### connect(token, dbName, dbType)

Creates a new database connection.

- token (string): The UUID token for database access
- dbName (string): The name of the database
- dbType (string): The type of database ('sqlite' or 'duckdb', defaults to 'sqlite')
- Returns: DatabaseConnection - A new connection instance

`javascript
const connection = service.connect('uuid-token', 'my-database', 'sqlite');
`

##### deleteDatabase(token, dbName, dbType)

Deletes a database permanently.

- token (string): The UUID token for database access
- dbName (string): The name of the database to delete
- dbType (string): The type of database ('sqlite' or 'duckdb', defaults to 'sqlite')
- Returns: Promise - Deletion result with success message

`javascript
await service.deleteDatabase('uuid-token', 'old-database', 'sqlite');
`

##### renameDatabase(token, oldDbName, newDbName, dbType)

Renames a database.

- token (string): The UUID token for database access
- oldDbName (string): The current name of the database
- newDbName (string): The new name for the database
- dbType (string): The type of database ('sqlite' or 'duckdb', defaults to 'sqlite')
- Returns: Promise - Rename result with success message

`javascript
await service.renameDatabase('uuid-token', 'old-name', 'new-name', 'sqlite');
`

##### copyDatabase(sourceToken, sourceDbName, sourceDbType, destToken, destDbName)

Copies a database from one location to another.

- sourceToken (string): The UUID token for the source database
- sourceDbName (string): The name of the source database
- sourceDbType (string): The type of the source database ('sqlite' or 'duckdb')
- destToken (string): The UUID token for the destination
- destDbName (string): The name for the destination database
- Returns: Promise - Copy result with success message

`javascript
await service.copyDatabase('source-token', 'source-db', 'sqlite', 'dest-token', 'dest-db');
`

##### getUploadUrl(token, dbName, dbType)

Gets a presigned URL for uploading a database file.

- token (string): The UUID token for database access
- dbName (string): The name for the database
- dbType (string): The type of file ('sqlite', 'duckdb', or 'csv' - CSV files are converted to SQLite, defaults to 'sqlite')
- Returns: Promise - Upload URL information with uploadUrl, fileName, and expiresIn

`javascript
const { uploadUrl, fileName } = await service.getUploadUrl('uuid-token', 'my-db', 'sqlite');
`

##### getDownloadUrl(token, dbName, dbType)

Gets a presigned URL for downloading a database file.

- token (string): The UUID token for database access
- dbName (string): The name of the database
- dbType (string): The type of database ('sqlite' or 'duckdb', defaults to 'sqlite')
- Returns: Promise - Download URL information with downloadUrl, fileName, and expiresIn

`javascript
const { downloadUrl, fileName } = await service.getDownloadUrl('uuid-token', 'my-db', 'sqlite');
`

##### createTemplate(templateName, initializationSql, description)

Creates a new database template.

- templateName (string): The name for the template
- initializationSql (Array): Array of SQL statements to initialize the template
- description (string): Description of the template
- Returns: Promise - Created template information

`javascript
const template = await service.createTemplate(
'my-template',
['CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)'],
'A simple user table template'
);
`

##### listTemplates()

Lists all available templates.

- Returns: Promise - Array of template objects

`javascript
const templates = await service.listTemplates();
`

##### getTemplate(templateName)

Gets a specific template by name.

- templateName (string): The name of the template to retrieve
- Returns: Promise - Template information

`javascript
const template = await service.getTemplate('my-template');
`

##### updateTemplate(templateName, initializationSql, description)

Updates an existing template.

- templateName (string): The name of the template to update
- initializationSql (Array): Array of SQL statements to initialize the template
- description (string): Description of the template
- Returns: Promise - Update result with success message and old template info

`javascript
const result = await service.updateTemplate(
'my-template',
['CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)'],
'Updated user table template with email'
);
`

##### deleteTemplate(templateName)

Deletes a template.

- templateName (string): The name of the template to delete
- Returns: Promise - Deletion result with success message

`javascript
await service.deleteTemplate('my-template');
`

##### getTemplateInfo(templateName, token, dbName, dbType)

Gets template information for a specific database.

- templateName (string): The name of the template
- token (string): The UUID token for database access
- dbName (string): The name of the database
- dbType (string): The type of database ('sqlite' or 'duckdb', defaults to 'sqlite')
- Returns: Promise - Template info including schema and application status

`javascript
const info = await service.getTemplateInfo('my-template', 'uuid-token', 'my-db', 'sqlite');
`

##### getAppliedTemplates(token, dbName, dbType)

Gets applied templates for a database.

- token (string): The UUID token for database access
- dbName (string): The name of the database
- dbType (string): The type of database ('sqlite' or 'duckdb', defaults to 'sqlite')
- Returns: Promise - Applied templates information

`javascript
const applied = await service.getAppliedTemplates('uuid-token', 'my-db', 'sqlite');
`

##### uploadAndCreateTemplate(token, filePath, options)

Uploads a file (or multiple files) and automatically creates a database with an AI-generated template. This is a complete workflow that handles file upload, database analysis, AI description generation, template creation, and application.

Parameters:
- token (string): The UUID token for database access
- filePath (string|string[]|File|File[]): Path to the file(s) to upload (Node.js) or File object (browser)
- options (Object): Optional configuration
- options.dbName (string): Custom database name (must be unique - will fail if already exists)
- options.templateName (string): Custom template name (must be unique - will fail if already exists)
- options.onProgress (Function): Progress callback function(step, message)

Returns: Promise with the following properties:
- success (boolean): Whether the operation completed successfully
- dbName (string): Name of the created database
- templateName (string): Name of the created template
- description (string): AI-generated description of the database
- tableCount (number): Number of tables in the database
- message (string): Success message

Supported file types: CSV (converted to SQLite), SQLite

Naming Behavior:
- Auto-generated names: When no custom names are provided, the SDK automatically generates unique names:
- Database names use the filename (sanitized): customers.csv -> customers, customers1, customers2, etc.
- Template names append _template with uniqueness validation: customers_template, customers_template1, etc.
- Custom names: When you specify custom dbName or templateName, they must be unique:
- If a database/template with that name already exists, the operation will fail
- No automatic conflict resolution is performed for custom names

`javascript
// Upload from file path (Node.js) with auto-generated names
const result = await service.uploadAndCreateTemplate(
'uuid-token',
'./data/customers.csv',
{
onProgress: (step, message) => console.log(Step ${step}/6: ${message})
}
);

// Upload from File object (browser)
const fileInput = document.querySelector('input[type="file"]');
const result = await service.uploadAndCreateTemplate(
'uuid-token',
fileInput.files[0],
{
onProgress: (step, message) => console.log(Step ${step}/6: ${message})
}
);

// Upload with custom names (must be unique)
const result2 = await service.uploadAndCreateTemplate(
'uuid-token',
'./data/sales.sqlite',
{
dbName: 'sales_data', // Will fail if 'sales_data' already exists
templateName: 'sales_template', // Will fail if 'sales_template' already exists
onProgress: (step, message) => console.log(Step ${step}: ${message})
}
);

console.log('Database created:', result.dbName);
console.log('Template created:', result.templateName);
console.log('Description:', result.description);
`

##### createMcpSlug(queryParams)

Creates a permanent URL slug for MCP server endpoints.

- queryParams (Object): Query parameters for the MCP endpoint
- Returns: Promise - Created slug information with slug and full URL

`javascript
const slug = await service.createMcpSlug({
key: 'your-api-key',
token: 'uuid-token',
dbName: 'my-db',
template: 'my-template' // optional
});
`

##### getMcpSlug(slug)

Gets MCP slug information.

- slug (string): The slug identifier
- Returns: Promise - Slug information and query parameters

`javascript
const slugInfo = await service.getMcpSlug('abc123');
`

$3

A connection to a specific database for executing SQL statements.

#### Constructor

`javascript
new DatabaseConnection(baseUrl, apiKey, token, dbName, dbType)
`

Typically created via DatabaseService.connect() rather than directly.

#### Methods

##### execute(statements)

Executes one or more SQL statements.

- statements (Array|Object): Array of statement objects or single statement object
- Returns: Promise - Execution results

Each statement object should have:
- sql (string): The SQL statement to execute
- params (Array, optional): Parameters for the SQL statement

`javascript
// Single statement
const result = await connection.execute({
sql: 'SELECT * FROM users WHERE id = ?',
params: [1]
});

// Multiple statements
const result = await connection.execute([
{
sql: 'INSERT INTO users (name) VALUES (?)',
params: ['Alice']
},
{
sql: 'INSERT INTO users (name) VALUES (?)',
params: ['Bob']
}
]);
`

##### executeFailFast(statements, options)

Executes a batch of SQL statements but stops at the first failure. The response mirrors execute but also returns metadata describing what succeeded and where execution stopped.

- statements (Array|Object): Array of statement objects or single statement object
- options (Object, optional): Additional parameters such as { templateName: 'crm' }
- Returns: Promise - Execution results with fail-fast metadata

Each statement object should have:
- sql (string): The SQL statement to execute
- params (Array, optional): Parameters for the SQL statement

`javascript
const result = await connection.executeFailFast([
{ sql: 'INSERT INTO tasks (title) VALUES (?)', params: ['First task'] },
{ sql: 'INSERT INTO tasks (title) VALUES (?)', params: ['Second task'] },
{ sql: 'INSERT INTO tasks (title, status) VALUES (?, ?)', params: ['Third task', 'done'] }
]);

if (result.metadata.status === 'partial') {
console.log('Failed at statement', result.metadata.failedStatementIndex);
console.log('Error message:', result.metadata.failedStatement?.error);
console.log('Completed statements:', result.metadata.successfulStatements);
}
`

##### naturalLanguageToSql(query, conversationHistory, templateName)

Converts natural language to SQL and optionally executes it.

- query (string): The natural language query
- conversationHistory (Array, optional): Optional conversation history for context
- templateName (string, optional): Optional template name for schema context
- Returns: Promise - Natural language conversion results with generated SQL and optional execution results

`javascript
// Simple natural language query
const result = await connection.naturalLanguageToSql('show me all users');
console.log('Generated SQL:', result.sql);
console.log('Results:', result.results);

// With conversation history for context
const conversationHistory = [
{
query: 'show me all users',
sql: 'SELECT * FROM users',
results: [{ rows: [{ id: 1, name: 'John' }] }]
}
];

const result2 = await connection.naturalLanguageToSql(
'how many are there?',
conversationHistory
);

// With template for schema context
const result3 = await connection.naturalLanguageToSql(
'show me customer orders',
null,
'crm-template'
);
`

Error Handling

The SDK provides specific error types for different scenarios:

`javascript
import {
AgentDBError,
AuthenticationError,
ValidationError,
DatabaseError,
createVectorBuffer
} from '@agentdb/sdk';

try {
const result = await connection.execute({
sql: 'SELECT * FROM users',
params: []
});
} catch (error) {
if (error instanceof AuthenticationError) {
console.error('Authentication failed:', error.message);
} else if (error instanceof ValidationError) {
console.error('Invalid request:', error.message);
} else if (error instanceof DatabaseError) {
console.error('Database error:', error.message);
} else if (error instanceof AgentDBError) {
console.error('AgentDB error:', error.message);
} else {
console.error('Unexpected error:', error.message);
}
}
`

Examples

$3

`javascript
import { DatabaseService } from '@agentdb/sdk';

const service = new DatabaseService('https://api.agentdb.dev', 'your-api-key');
const connection = service.connect('your-token', 'users-db', 'sqlite');

// Create table
await connection.execute({
sql: CREATE TABLE IF NOT EXISTS users (
id INTEGER PRIMARY KEY AUTOINCREMENT,
name TEXT NOT NULL,
email TEXT UNIQUE,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
),
params: []
});

// Insert data
await connection.execute({
sql: 'INSERT INTO users (name, email) VALUES (?, ?)',
params: ['John Doe', 'john@example.com']
});

// Query data
const result = await connection.execute({
sql: 'SELECT * FROM users WHERE email = ?',
params: ['john@example.com']
});

console.log('User data:', result.results[0].rows);
`

$3

`javascript
// Insert multiple records in a single request
const users = [
['Alice Smith', 'alice@example.com'],
['Bob Johnson', 'bob@example.com'],
['Carol Williams', 'carol@example.com']
];

const statements = users.map(([name, email]) => ({
sql: 'INSERT INTO users (name, email) VALUES (?, ?)',
params: [name, email]
}));

await connection.execute(statements);
`

$3

`javascript
const analyticsConnection = service.connect('your-token', 'analytics', 'duckdb');

// Create analytics table
await analyticsConnection.execute({
sql: CREATE TABLE IF NOT EXISTS events (
id UUID DEFAULT gen_random_uuid(),
timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
event_type VARCHAR(50),
user_id VARCHAR(50),
properties JSON
),
params: []
});

// Aggregate query
const result = await analyticsConnection.execute({
sql: SELECT
event_type,
COUNT(*) as total_events,
COUNT(DISTINCT user_id) as unique_users
FROM events
WHERE timestamp >= CURRENT_DATE - INTERVAL '7 days'
GROUP BY event_type
ORDER BY total_events DESC,
params: []
});

console.log('Weekly analytics:', result.results[0].rows);
`

$3

`javascript
import { DatabaseService } from '@agentdb/sdk';

const service = new DatabaseService('https://api.agentdb.dev', 'your-api-key');
const token = 'your-uuid-token';

// Delete a database
await service.deleteDatabase(token, 'old-database', 'sqlite');

// Rename a database
await service.renameDatabase(token, 'current-name', 'new-name', 'sqlite');

// Copy a database between tokens
await service.copyDatabase(
'source-token', 'source-db', 'sqlite',
'dest-token', 'backup-db'
);
`

$3

The SDK provides utilities for working with vector embeddings and similarity search:

`javascript
import { DatabaseService, createVectorBuffer } from '@agentdb/sdk';

const service = new DatabaseService('https://api.agentdb.dev', 'your-api-key');
const connection = service.connect('your-token', 'documents-db', 'sqlite');

// Create a table with vector embeddings
await connection.execute({
sql: CREATE TABLE IF NOT EXISTS documents (
id INTEGER PRIMARY KEY,
content TEXT,
embedding BLOB
),
params: []
});

// Insert documents with vector embeddings
const documents = [
{ content: 'Machine learning basics', embedding: [0.1, 0.2, 0.3, 0.4] },
{ content: 'Database fundamentals', embedding: [0.5, 0.6, 0.7, 0.8] },
{ content: 'Vector search techniques', embedding: [0.2, 0.3, 0.4, 0.5] }
];

for (const doc of documents) {
await connection.execute({
sql: 'INSERT INTO documents (content, embedding) VALUES (?, ?)',
params: [doc.content, createVectorBuffer(doc.embedding)]
});
}

// Perform vector similarity search
const queryEmbedding = createVectorBuffer([0.1, 0.2, 0.3, 0.4]);
const searchResult = await connection.execute({
sql: SELECT
id,
content,
vec_distance_cosine(embedding, ?) as similarity
FROM documents
ORDER BY similarity
LIMIT 5,
params: [queryEmbedding]
});

console.log('Similar documents:', searchResult.results[0].rows);

// You can also use arrays directly (they will be automatically converted)
const directArrayResult = await connection.execute({
sql: SELECT id, content, vec_distance_cosine(embedding, ?) as similarity
FROM documents ORDER BY similarity LIMIT 5,
params: [[0.1, 0.2, 0.3, 0.4]] // Array will be processed server-side
});
`

For a complete vector operations example, see examples/vector-operations.js.

$3

`javascript
// Get upload URL and upload a file
const { uploadUrl } = await service.getUploadUrl(token, 'imported-db', 'sqlite');

// Upload file using the presigned URL
const file = new File([fileData], 'database.sqlite');
await fetch(uploadUrl, {
method: 'PUT',
body: file,
headers: { 'Content-Type': 'application/octet-stream' }
});

// Get download URL and download a file
const { downloadUrl, fileName } = await service.getDownloadUrl(token, 'my-db', 'sqlite');

// Download the file
const response = await fetch(downloadUrl);
const blob = await response.blob();

// Create download link
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = fileName;
a.click();
URL.revokeObjectURL(url);
`

$3

The SDK provides a streamlined method to upload files and automatically create AI-powered templates:

`javascript
import { DatabaseService } from '@agentdb/sdk';

const service = new DatabaseService('https://api.agentdb.dev', 'your-api-key');
const token = 'your-uuid-token';

// Upload a CSV file with progress tracking
const result = await service.uploadAndCreateTemplate(
token,
'./data/sales-data.csv',
{
onProgress: (step, message) => {
console.log(Step ${step}/6: ${message});
}
}
);

console.log('✅ Upload completed!');
console.log(Database: ${result.dbName});
console.log(Template: ${result.templateName});
console.log(Description: ${result.description});

// Now you can use the database with the template
const connection = service.connect(token, result.dbName, 'sqlite');

// Execute queries with template context for better AI understanding
const nlResult = await connection.naturalLanguageToSql(
'show me the top 10 sales by amount',
null,
result.templateName
);

console.log('Generated SQL:', nlResult.sql);
console.log('Results:', nlResult.results);
`

Workflow Steps:
1. File upload - Uploads file to cloud storage
2. Database analysis - Waits for file processing and database creation
3. AI description - Generates intelligent description and schema analysis
4. Template creation - Creates reusable template with the AI-generated content
5. Template application - Applies template to database for enhanced querying
6. Verification - Ensures everything is set up correctly

Error Handling:
- Automatic cleanup of partially created resources on failure
- Detailed error messages for troubleshooting
- Retry logic for transient failures during database processing

Naming Conflicts:
`javascript
// This will fail if 'my_database' already exists
try {
const result = await service.uploadAndCreateTemplate(
token,
'./data.csv',
{ dbName: 'my_database' }
);
} catch (error) {
if (error.message.includes('already exists')) {
console.log('Database name conflict - choose a different name');
}
}

// This will automatically find a unique name (data, data1, data2, etc.)
const result = await service.uploadAndCreateTemplate(
token,
'./data.csv'
// No custom dbName - automatic conflict resolution
);
`

Debug Mode

The SDK supports debug mode for troubleshooting and development. When enabled, it provides detailed logging of requests, responses, and server-side debug information.

`javascript
// Enable debug mode
const service = new DatabaseService('https://api.agentdb.dev', 'your-api-key', true);

// Debug logs will be shown in console
const databases = await service.listDatabases('your-token');

// Connections inherit debug mode from service
const connection = service.connect('your-token', 'my-db', 'sqlite');

// Execute with debug information
const result = await connection.execute({
sql: 'SELECT * FROM users',
params: []
});

// Access server-side debug logs from response
if (result.debugLogs) {
console.log('Server debug logs:', result.debugLogs);
}
`

For detailed debug mode documentation, see DEBUG_USAGE.md.

API Reference

$3

Creates a Float32 buffer from an array of numbers for use as vector parameters in SQL queries.

Parameters:
- values (number[]): Array of numeric values to convert to a vector buffer

Returns:
- Buffer|Uint8Array: Buffer containing the vector data as Float32 values

Throws:
- ValidationError: If values is not an array, is empty, or contains non-numeric values

Example:
`javascript
import { createVectorBuffer } from '@agentdb/sdk';

// Create a vector buffer
const embedding = createVectorBuffer([0.1, 0.2, 0.3, 0.4]);

// Use in a query
const result = await connection.execute({
sql: 'SELECT * FROM documents WHERE vec_distance_cosine(embedding, ?) < 0.5',
params: [embedding]
});
`

Notes:
- Each number is stored as a 32-bit float (4 bytes)
- The resulting buffer length will be values.length × 4 bytes
- Works in both Node.js and browser environments
- For simple use cases, you can pass arrays directly to params` and they will be processed server-side

Requirements

- Node.js 18.0.0 or higher
- Modern browser with fetch API support

License

MIT