@datatamer/data-tamer-sdk

v2.8.2

Published

3 months ago

TypeScript SDK for Data Tamer Dashboard API

Downloads

0High
0Medium
0Low

datatamer

data-tamer api sdk typescript

Data Tamer Dashboard SDK

A comprehensive TypeScript SDK for the Data Tamer Dashboard API, providing easy access to all platform features including workspaces, topics, datasources, tamed data, AI conversations, billing, and real-time events.

Documentation

📖 Complete API Reference - Comprehensive documentation of all SDK methods, parameters, return types, and examples.

Installation

npm install @datatamer/data-tamer-sdk

Quick Start

import DataTamerSDK from '@datatamer/data-tamer-sdk';

// Initialize the SDK
const sdk = new DataTamerSDK({
  baseUrl: 'https://app.datatamer.ai/api',
  apiKey: 'your-api-token', // Use API token for authentication
  timeout: 30000
});

// Use the SDK
async function example() {
  // List workspaces (new module name)
  const workspaces = await sdk.workspaces.listWorkspaces();
  
  // Create a topic (new module name)
  const topic = await sdk.topics.createTopic({
    name: 'My Topic',
    description: 'A sample topic',
    organizationId: workspaces[0].id
  });
  
  // Start real-time connection
  await sdk.realtime.connect({}, {
    onMessage: (data) => console.log('Real-time event:', data),
    onOpen: () => console.log('Connected to real-time stream')
  });
}

Authentication

The SDK supports multiple authentication methods:

API Token (Recommended)

Create an API token in your account settings and use it for authentication:

const sdk = new DataTamerSDK({
  baseUrl: 'https://app.datatamer.ai/api',
  apiKey: 'your-api-token' // Get this from your account settings
});

Session Token (Browser sessions)

For browser-based applications using session cookies:

const sdk = new DataTamerSDK({
  baseUrl: 'https://app.datatamer.ai/api',
  sessionToken: 'your-session-token'
});

External API Key Integration

For external integrations using the EXTERNAL_API_KEY_INTEGRATION, you can manage tokens on behalf of other users:

// Initialize SDK with external API key
const sdk = new DataTamerSDK({
  baseUrl: 'https://app.datatamer.ai/api',
  apiKey: 'your-external-api-key' // EXTERNAL_API_KEY_INTEGRATION token
});

// Lookup user ID by email (EXTERNAL_API_KEY_INTEGRATION only)
const user = await sdk.users.getUserByEmail('[email protected]');
const userId = user.id;

// Or use known user ID
// const userId = 'ext_1703123456789_abc123def';

// List user's API tokens
const tokens = await sdk.users.listApiTokens(userId);

// Create API token for user
const newToken = await sdk.users.createApiToken({
  name: 'Mobile App Integration',
  user_id: userId
});

// Delete user's API token
await sdk.users.deleteApiToken('token-id', userId);

Server Configuration

The SDK supports flexible server configuration through environment variables and explicit settings. This makes it easy to switch between different DataTamer instances (production, development, local) without changing your code.

Environment Variables (Recommended)

Set environment variables to automatically configure the server:

# Direct URL (highest priority)
export DATA_TAMER_URL="http://localhost:8444"
export DATA_TAMER_URL="https://your-custom-instance.com"

# Server environment name
export DATA_TAMER_SERVER="production"     # → https://app.datatamer.ai
export DATA_TAMER_SERVER="development"    # → https://dev-app.datatamer.ai
export DATA_TAMER_SERVER="local"          # → http://localhost:3000

# Auto-detection from NODE_ENV (lowest priority)
export NODE_ENV="production"              # → https://app.datatamer.ai
export NODE_ENV="development"             # → https://dev-app.datatamer.ai

Automatic Configuration

Use the configuration builder for automatic server detection:

import { DataTamerSDK, DataTamerConfig } from '@datatamer/data-tamer-sdk';

// Auto-configure based on environment variables
const config = DataTamerConfig.create({
  apiKey: process.env.DATA_TAMER_API_KEY
});

const sdk = new DataTamerSDK(config);

// Debug: See what configuration was resolved
const info = DataTamerConfig.getConfigInfo();
console.log('Using server:', info.resolvedUrl);
console.log('Configuration source:', info.source);

Explicit Server Selection

Choose a specific server environment:

import { DataTamerConfig } from '@datatamer/data-tamer-sdk';

// Production server
const prodConfig = DataTamerConfig.forServer('production', {
  apiKey: 'your-api-key'
});

// Development server  
const devConfig = DataTamerConfig.forServer('development', {
  apiKey: 'your-api-key'
});

// Local server
const localConfig = DataTamerConfig.forServer('local', {
  apiKey: 'your-api-key'
});

// Custom URL
const customConfig = DataTamerConfig.forUrl('http://localhost:8444', {
  apiKey: 'your-api-key'
});

Quick Helpers

Use convenience functions for common configurations:

import { 
  createDataTamerConfig,     // Auto-configuration
  createProductionConfig,    // Production server
  createDevelopmentConfig,   // Development server
  createLocalConfig          // Local server
} from '@datatamer/data-tamer-sdk';

const config = createDevelopmentConfig({
  apiKey: process.env.DATA_TAMER_API_KEY,
  timeout: 60000
});

const sdk = new DataTamerSDK(config);

IoT Dashboard Integration Example

For IoT dashboard integration with a local DataTamer service:

// Set environment variable
process.env.DATA_TAMER_URL = 'http://localhost:8444';

// Or use explicit configuration
const iotConfig = DataTamerConfig.forUrl('http://localhost:8444', {
  apiKey: process.env.EXTERNAL_API_KEY_INTEGRATION
});

const sdk = new DataTamerSDK(iotConfig);

Module Naming

The SDK provides both legacy and new module names for better semantic clarity:

Legacy: sdk.organizations → New: sdk.workspaces
Legacy: sdk.projects → New: sdk.topics

Both naming conventions work and provide identical functionality. The legacy names are maintained for backward compatibility.

// New naming (recommended)
const workspaces = await sdk.workspaces.listWorkspaces();
const topics = await sdk.topics.listTopics(workspaceId);

// Legacy naming (still works)
const workspaces = await sdk.organizations.listWorkspaces();
const topics = await sdk.projects.listTopics(workspaceId);

Modules

Workspaces

Manage workspaces, users, roles, and billing.

// List workspaces (using new module name)
const workspaces = await sdk.workspaces.listWorkspaces();

// Legacy support (still works)
const workspaces_legacy = await sdk.organizations.listWorkspaces();

// Create workspace
const newWorkspace = await sdk.workspaces.createWorkspace({
  name: 'My Company',
  description: 'Company workspace'
});

// Get dashboard data
const dashboard = await sdk.workspaces.getWorkspaceDashboard(workspaceId);

// Add user to workspace
await sdk.workspaces.addUserToWorkspace(workspaceId, '[email protected]');

// Change user role
await sdk.workspaces.changeUserRoleInWorkspace(workspaceId, userId, 'admin');

// Manage billing
const billing = await sdk.workspaces.getBillingHistory(workspaceId);
await sdk.workspaces.topUpCredits(workspaceId, 100);

Topics

Manage topics, users, and actions.

// List topics (using new module name)
const topics = await sdk.topics.listTopics(workspaceId);

// Legacy support (still works)
const topics_legacy = await sdk.projects.listTopics(workspaceId);

// Create topic
const topic = await sdk.topics.createTopic({
  name: 'Data Analysis Topic',
  description: 'Analyzing customer data',
  organizationId: workspaceId
});

// Topic chat
const chatResponse = await sdk.topics.chatInTopic(
  topicId, 
  'Help me analyze this data',
  { context: 'customer_data' }
);

// Manage topic users
const users = await sdk.topics.listTopicUsers(topicId);
await sdk.topics.addUserToTopic(topicId, '[email protected]', 'member');

// Topic actions
const actions = await sdk.topics.listTopicActions(topicId);
await sdk.topics.addTopicAction(topicId, {
  name: 'Data Validation',
  description: 'Validate data quality',
  actionType: 'validation',
  parameters: { threshold: 0.95 }
});

Datasources

Manage data sources and connections.

// List datasources
const datasources = await sdk.datasources.listForWorkspace(workspaceId);

// Create SQL datasource
// Note: SDK interface uses organizationId/datasourceType/configuration,
// but API expects activeOrganization/dataType/settings
const sqlDatasource = await sdk.datasources.create({
  name: 'Customer Database',
  description: 'Main customer data',
  organizationId: workspaceId,     // SDK maps to API's activeOrganization
  datasourceType: 'SQL' as const, // SDK maps to API's dataType (use 'as const' for TypeScript)
  configuration: {                 // SDK maps to API's settings
    host: 'db.company.com',
    port: 5432,
    database: 'customers',
    username: 'readonly',
    password: 'secret'
  }
});

// Create STREAM datasource (for real-time data)
const streamDatasource = await sdk.datasources.create({
  name: 'IoT Camera Stream',
  description: 'Real-time AI camera data stream',
  organizationId: workspaceId,         // SDK maps to API's activeOrganization
  datasourceType: 'STREAM' as const,  // SDK maps to API's dataType (use 'as const' for TypeScript)
  configuration: {                     // SDK maps to API's settings
    streamType: 'camera',
    deviceSerial: 'CAMERA001',
    deviceType: 'CAMERA1'
  }
});

// Test connections
const sqlTest = await sdk.datasources.testSqlConnection({
  host: 'db.company.com',
  port: 5432,
  database: 'customers',
  username: 'readonly',
  password: 'secret'
});

const gitTest = await sdk.datasources.testGitConnection({
  repositoryUrl: 'https://github.com/company/data-repo',
  branch: 'main',
  accessToken: 'github-token'
});

// Process datasources
await sdk.datasources.rebuild(datasourceId);
await sdk.datasources.stop(datasourceId);

// Stream data
await sdk.datasources.stream(datasourceId, {
  content: { temperature: 25.5, humidity: 60 },
  metadata: { sensor: 'office-1' },
  timestamp: new Date().toISOString()
});

Users

Manage user accounts and API tokens.

// Get current user information
const user = await sdk.users.getCurrentUser();

// Lookup user by email (EXTERNAL_API_KEY_INTEGRATION only)
const userByEmail = await sdk.users.getUserByEmail('[email protected]');
console.log(`Found user: ${userByEmail.firstName} ${userByEmail.lastName} (ID: ${userByEmail.id})`);

// Update user profile
await sdk.users.updateProfile({
  firstName: 'John',
  lastName: 'Doe'
});

// Change password
await sdk.users.changePassword('new-secure-password');

// API Token Management
// List current user's API tokens
const tokens = await sdk.users.listApiTokens();

// Create new API token
const newToken = await sdk.users.createApiToken({
  name: 'My Integration Token'
});
console.log('Token (store securely):', newToken.token);

// Delete an API token
await sdk.users.deleteApiToken('token-id');

// External API Key Integration - manage tokens for other users
const userId = 'ext_1703123456789_abc123def';

// List specific user's tokens (requires EXTERNAL_API_KEY_INTEGRATION)
const userTokens = await sdk.users.listApiTokens(userId);

// Create token for specific user (requires EXTERNAL_API_KEY_INTEGRATION)
const userToken = await sdk.users.createApiToken({
  name: 'User Integration',
  user_id: userId
});

// Delete token for specific user (requires EXTERNAL_API_KEY_INTEGRATION)
await sdk.users.deleteApiToken('token-id', userId);

// Admin functions (require admin privileges)
const inactiveUsers = await sdk.users.listInactiveUsers();
await sdk.users.activateUser('user-id');
await sdk.users.updateUserEmail('user-id', '[email protected]');

Tamed Data

Manage processed data and API keys.

// Create tamed data
// Note: SDK interface uses dataType/configuration,
// but API expects data_type (no configuration parameter)
const tamedData = await sdk.tamedData.create({
  name: 'Processed Customer Data',
  description: 'Cleaned and validated customer data',
  projectId: topicId,        // API maps directly to projectId
  datasourceId: datasourceId, // API maps directly to datasourceId
  dataType: 'tabular',       // SDK maps to API's data_type
  configuration: { format: 'parquet' } // Note: API doesn't support configuration
});

// Create with wire connections
const tamedDataWithWires = await sdk.tamedData.createWithWires({
  name: 'Connected Data',
  description: 'Data with relationships',
  projectId: topicId,        // API maps directly to projectId
  datasourceId: datasourceId, // API maps directly to datasourceId
  dataType: 'relational'     // SDK maps to API's data_type
}, [
  {
    originTable: 'customers',
    originField: 'id',
    destinationTable: 'orders',
    destinationField: 'customer_id'
  }
]);

// API key management
const apiKey = await sdk.tamedData.generateApiKey(tamedDataId);

// Stream API integration
const streamData = await sdk.tamedData.getStreamData(tamedDataId, apiKey.apiKey);
await sdk.tamedData.sendToStream(tamedDataId, apiKey.apiKey, {
  content: { processed: true, records: 1000 },
  metadata: { batch: '2024-01-01' }
});

// Search stream data
const searchResults = await sdk.tamedData.searchRag(tamedDataId, apiKey.apiKey, {
  question: 'Find all processed data from January 1st to January 2nd',
  limit: 100
});

AI Conversations

Manage AI conversations and prompts.

// Start new conversation
const { conversation, response } = await sdk.conversations.startConversation(
  workspaceId,
  topicId,
  'Analyze the customer churn data and provide insights',
  'Customer Churn Analysis'
);

// Continue conversation
const nextResponse = await sdk.conversations.continueConversation(
  conversation.id,
  'What are the main factors contributing to churn?'
);

// Get conversation history
const history = await sdk.conversations.getHistory(workspaceId, topicId);

// Get full conversation
const fullConversation = await sdk.conversations.getFullConversation(conversationId);

// Conversation management
await sdk.conversations.editTitle(conversationId, 'Updated Analysis');
const stats = await sdk.conversations.getStats(workspaceId, topicId);

Stream Alerts

Manage and monitor stream alerts with advanced filtering and pagination capabilities. New in v2.8.0: Enhanced date filtering, improved pagination, and severity mapping fixes.

// Basic alert retrieval
const alerts = await sdk.streamAlerts.list({
  limit: 50,
  offset: 0
});

// Filter by severity (automatically maps 'critical' to 'error' in database)
const criticalAlerts = await sdk.streamAlerts.getCritical({ limit: 10 });
const warningAlerts = await sdk.streamAlerts.getBySeverity('warning', { limit: 20 });

// NEW: Date-based filtering (v2.8.0)
const todayAlerts = await sdk.streamAlerts.getToday({ limit: 50 });
const lastWeekAlerts = await sdk.streamAlerts.getLastWeek({ limit: 100 });
const customRangeAlerts = await sdk.streamAlerts.getByDateRange('2024-01-01', '2024-01-31', {
  severity: 'critical'
});

// NEW: Enhanced pagination with total counts (v2.8.0)
const paginatedResult = await sdk.streamAlerts.getPaginated(1, 25, {
  severity: 'warning',
  date_from: '2024-12-01',
  date_to: '2024-12-31'
});

console.log(`Page ${paginatedResult.pagination.page} of ${paginatedResult.pagination.totalPages}`);
console.log(`Total alerts: ${paginatedResult.pagination.total}`);
console.log(`Has more: ${paginatedResult.pagination.hasMore}`);

// Advanced filtering with multiple criteria
const complexFilter = await sdk.streamAlerts.list({
  severity: 'critical',
  datasource_id: 'your-datasource-id',
  date_from: '2024-12-01',
  date_to: '2024-12-31',
  limit: 50
});

// Get alerts with images (for visual context)
const imageAlerts = await sdk.streamAlerts.getAlertsWithImages({
  date_from: '2024-12-01',
  limit: 20
});

// Alert statistics and analytics
const stats = await sdk.streamAlerts.getStatistics({
  date_from: '2024-11-01', // Last month
  datasource_id: 'specific-datasource'
});

console.log(`Total: ${stats.total}, Critical: ${stats.critical}, Unread: ${stats.unread}`);

// Transform to enhanced alert objects (for compatibility with RulesEditor)
const alertObjects = await sdk.streamAlerts.getAlertObjects({
  severity: 'critical',
  limit: 10
});

// Real-time monitoring example
const interval = setInterval(async () => {
  const newCritical = await sdk.streamAlerts.getCritical({ 
    date_from: new Date().toISOString().split('T')[0] // today
  });
  
  if (newCritical.length > 0) {
    console.log(`🚨 ${newCritical.length} critical alerts today`);
  }
}, 30000); // Check every 30 seconds

Billing

Manage subscriptions and billing.

// Get subscription status
const subscription = await sdk.billing.getSubscription();
const status = await sdk.billing.getSubscriptionStatus();

// Create subscription
const newSub = await sdk.billing.createSubscription('pro-plan', workspaceId);

// Manage subscription
await sdk.billing.cancelSubscriptionAtPeriodEnd(subscriptionId);
await sdk.billing.resumeSubscription(subscriptionId);

// Token checkout
const checkout = await sdk.billing.createTokenCheckout(workspaceId, 'token-pack-100');

// Billing analytics
const spending = await sdk.billing.getTotalSpending(workspaceId);
const monthly = await sdk.billing.getMonthlySpending(workspaceId, 2024, 1);
const attention = await sdk.billing.needsAttention();

Real-time Events

Connect to server-sent events for real-time updates.

// Basic connection
await sdk.realtime.connect({
  reconnect: true,
  maxReconnectAttempts: 5,
  reconnectInterval: 3000
}, {
  onMessage: (data) => console.log('Event:', data),
  onOpen: () => console.log('Connected'),
  onError: (error) => console.error('Error:', error)
});

// Subscribe to specific events
const unsubscribe = sdk.realtime.onNotifications((notification) => {
  console.log('New notification:', notification);
});

// Datasource updates
sdk.realtime.onDatasourceUpdates((update) => {
  console.log('Datasource updated:', update);
});

// AI responses
sdk.realtime.onAIResponses((response) => {
  console.log('AI response:', response);
});

// Filter all events
const unsubscribeAll = sdk.realtime.onAllEvents(
  (eventType, data) => eventType.includes('error'),
  (eventType, data) => console.log('Error event:', eventType, data)
);

// Auto-reconnect with exponential backoff
sdk.realtime.enableAutoReconnect(1000, 30000, 10);

// Cleanup
unsubscribe();
sdk.realtime.disconnect();

Error Handling

The SDK throws DataTamerError instances with detailed information:

import { DataTamerError } from '@datatamer/data-tamer-sdk';

try {
  await sdk.workspaces.createWorkspace({ name: '', description: '' });
} catch (error) {
  if (error instanceof DataTamerError) {
    console.error(`API Error (${error.status}): ${error.message}`);
    console.error('Details:', error.details);
  }
}

Configuration Options

const sdk = new DataTamerSDK({
  baseUrl: 'https://app.datatamer.ai/api', // Required
  apiKey: 'your-api-token',                 // API token (recommended)
  sessionToken: 'session-token',            // Session token (optional)
  timeout: 30000                            // Optional (default: 30000ms)
});

TypeScript Support

The SDK is written in TypeScript and provides full type definitions:

import { 
  Organization, 
  Project, 
  Datasource, 
  TamedData,
  Conversation,
  DataTamerError 
} from '@datatamer/data-tamer-sdk';

// All API responses are properly typed
const workspaces: Organization[] = await sdk.workspaces.listWorkspaces();
const topic: Project = await sdk.topics.getTopic(topicId);

Advanced Usage

Batch Operations

// Create multiple datasources
const datasources = [
  { name: 'DB1', description: 'Database 1', /* ... */ },
  { name: 'DB2', description: 'Database 2', /* ... */ }
];

const results = await Promise.all(
  datasources.map(ds => sdk.datasources.create(ds))
);

Waiting for Status Changes

// Wait for datasource to be active
const activeDatasource = await sdk.datasources.waitForStatus(
  datasourceId, 
  'ACTIVE', 
  60000 // 60 second timeout
);

Streaming with Retries

// Send stream data with automatic retries
await sdk.tamedData.sendToStreamWithRetry(
  tamedDataId,
  apiKey,
  { content: data },
  3,    // max retries
  1000  // retry delay
);

Health Monitoring

// Check SDK health
const health = await sdk.healthCheck();
console.log('SDK Status:', health.status);
console.log('Service Status:', health.services);

Examples

See the /examples directory for complete working examples:

Basic Usage - Complete SDK overview with all modules
Real-time Dashboard - Live event monitoring
API Token Management - Token creation and security
AI Conversation - Interactive AI conversations
Complete Workflow - End-to-end workflow from login to RAG search

Support

For support, please check:

License

MIT License - see LICENSE for details.