Boltic SDK

Boltic SDK is an open-source TypeScript library, developed by Fynd, for integrating with the Boltic platform. Manage databases, tables, records, run SQL queries, and execute workflow integrations to build robust, modern applications.

Documentation

• Boltic SDK Documentation - Complete SDK documentation

Features

• 🔧 Full TypeScript Support: Comprehensive type definitions and IntelliSense
• 🚀 Modern Architecture: ES modules and CommonJS support
• 🔐 Built-in Authentication: Integrated API key management
• 📊 Database Operations: Complete table and column management
• 📝 Record Operations: Full CRUD operations with advanced querying
• 🌐 Multi-Region Support: Asia Pacific and US Central regions
• 🔍 Advanced Filtering: Comprehensive query operators
• 🛠️ Helper Classes: Schema and column creation utilities
• 🎯 Vector Support: AI/ML vector fields with multiple precisions
• Workflow Operations — Execute integration activities, poll for results, manage credentials
• Multi-Region Support — Asia Pacific and US Central regions

Prerequisites

• Node.js: >=18.0.0
• NPM: >=8.0.0

Installation

npm install @boltic/sdk

Quick Start

import { createClient } from '@boltic/sdk';

// Initialize the client
const client = createClient('your-api-key', {
  region: 'asia-south1', // 'asia-south1' or 'us-central1'
  debug: false,
});

// Database operations
const tables = client.tables;
const columns = client.columns;
const records = client.records;

// Workflow operations
const workflow = client.workflow;

Authentication

API Key Setup

You can get your API key from boltic.io.

1. Log into your Boltic account
2. Go to Settings → PAT Tokens
3. Generate and copy your API key

import { createClient } from '@boltic/sdk';

const client = createClient('your-api-key-here', {
  region: 'asia-south1',
});

Environment Variables

import dotenv from 'dotenv';
import { createClient } from '@boltic/sdk';

dotenv.config();

const client = createClient(process.env.BOLTIC_API_KEY!, {
  region: process.env.BOLTIC_REGION || 'asia-south1',
  debug: process.env.DEBUG === 'true',
});

Configuration Options

interface ClientOptions {
  region?: 'asia-south1' | 'us-central1';
  retryAttempts?: number;
  retryDelay?: number;
  maxRetries?: number;
  timeout?: number;
  debug?: boolean;
}

const client = createClient('your-api-key', {
  region: 'asia-south1',
  debug: true,
  retryAttempts: 3,
  retryDelay: 1000,
  maxRetries: 3,
  timeout: 30000,
});

Run your file to create client:

npx tsx create-client.ts

Database Context

The client automatically uses a default database context for all operations:

// Get current database context
const currentDb = client.getCurrentDatabase();
console.log('Current database:', currentDb);

Custom Databases

By default, all tables, columns, records, indexes, and sql operations run against your default Boltic Cloud database. You can create additional databases and switch between them using client.databases + client.useDatabase().

Creating a Database

const { data: database, error } = await client.databases.create({
  db_name: 'My Custom Database',
  // db_internal_name: 'my_custom_db', // optional; auto-derived if omitted
  // resource_id: 'boltic' // optional (default). For custom resources, use a connector id starting with 'btb-'
});

if (error) {
  console.error('Failed to create database:', error.message);
} else {
  console.log('Created database:', database.db_internal_name);
}

Listing Databases

const { data: databases, error } = await client.databases.findAll({
  page: { page_no: 1, page_size: 10 },
  sort: [{ field: 'db_name', direction: 'asc' }],
  // connector_id: 'btb-abc123xyz', // optional: list databases for a custom resource
});

if (!error) {
  databases.forEach((db) =>
    console.log(`${db.db_name} (${db.db_internal_name})`)
  );
}

Getting a Database (or Default Database)

const { data: db, error } = await client.databases.findOne('my_custom_db');
const { data: defaultDb } = await client.databases.getDefault();

Updating a Database (Display Name)

const result = await client.databases.update('my_custom_db', {
  db_name: 'Updated Database Name',
});

Deleting a Database (Async) + Polling Status

const { data: job, error } = await client.databases.delete('old_db_slug');

if (error) {
  console.error('Failed to delete database:', error.message);
} else {
  console.log('Deletion job started:', job.job_id);

  const { data: status } = await client.databases.pollDeleteStatus(job.job_id);
  console.log('Deletion status:', status.status, '-', status.message);
}

Listing Database Jobs

const { data: jobs } = await client.databases.listJobs({
  deleted_by_me: true,
  page: { page_no: 1, page_size: 20 },
  sort: [{ field: 'created_at', direction: 'desc' }],
});

Switching Database Context

// Switch to a custom database (by internal name / slug)
await client.useDatabase('my_custom_db');

// All subsequent operations target this database
await client.tables.findAll();
await client.records.findAll('users');

// Inspect current context (null means default database)
console.log(client.getCurrentDatabase());

// Switch back to default database
await client.useDatabase();

Table Operations

Reserved Columns

The following columns are automatically added to all tables and cannot be modified or deleted:

• id: Primary key field (uuid type, unique, not nullable)
• created_at: Timestamp when the record was created
• updated_at: Timestamp when the record was last updated

These columns are managed by the system and provide essential functionality for record identification and tracking.

Creating Tables

// Create a table with schema
const tableResult = await client.tables.create({
  name: 'users',
  description: 'User management table',
  fields: [
    {
      name: 'name',
      type: 'text',
      is_nullable: false,
      description: 'User name',
    },
    {
      name: 'email',
      type: 'email',
      is_nullable: false,
      is_unique: true,
      description: 'User email',
    },
    {
      name: 'age',
      type: 'number',
      decimals: '0.00',
      description: 'User age',
    },
    {
      name: 'salary',
      type: 'currency',
      currency_format: 'USD',
      decimals: '0.00',
      description: 'User salary',
    },
    {
      name: 'is_active',
      type: 'checkbox',
      default_value: true,
      description: 'User status',
    },
    {
      name: 'role',
      type: 'dropdown',
      selectable_items: ['Admin', 'User', 'Guest'],
      multiple_selections: false,
      description: 'User role',
    },
  ],
});

// Note: The following columns are automatically added to all tables:
// - 'id': Primary key (text, unique, not nullable)
// - 'created_at': Timestamp when record was created
// - 'updated_at': Timestamp when record was last updated

if (tableResult.error) {
  console.error('Table creation failed:', tableResult.error);
} else {
  console.log('Table created:', tableResult.data);
}

Listing and Filtering Tables

// List all tables
const allTables = await client.tables.findAll();

// Filter tables by name
const filteredTables = await client.tables.findAll({
  where: { name: 'users' },
});

// Get a specific table
const table = await client.tables.findOne({
  where: { name: 'users' },
});

// Get table by name
const tableByName = await client.tables.findByName('users');

Updating Tables

// Update table properties
const updateResult = await client.tables.update('users', {
  name: 'updated_users',
  description: 'Updated description',
});

// Rename table
const renameResult = await client.tables.rename('users', 'new_users');

Deleting Tables

// Delete table by name
const deleteResult = await client.tables.delete('users');

Column Operations

Creating Columns

// Create different types of columns
const columnTypes = [
  {
    name: 'description',
    type: 'long-text',
    description: 'User description',
  },
  {
    name: 'age',
    type: 'number',
    decimals: '0.00',
    description: 'User age',
  },
  {
    name: 'salary',
    type: 'currency',
    currency_format: 'USD',
    decimals: '0.00',
    description: 'User salary',
  },
  {
    name: 'is_active',
    type: 'checkbox',
    default_value: true,
    description: 'User status',
  },
  {
    name: 'role',
    type: 'dropdown',
    selectable_items: ['Admin', 'User', 'Guest'],
    multiple_selections: false,
    description: 'User role',
  },
  {
    name: 'phone',
    type: 'phone-number',
    phone_format: '+91 123 456 7890',
    description: 'Phone number',
  },
  {
    name: 'embedding',
    type: 'vector',
    vector_dimension: 1536,
    description: 'Text embedding vector',
  },
];

for (const columnData of columnTypes) {
  const result = await client.columns.create('users', columnData);
  if (result.error) {
    console.error(`Failed to create ${columnData.type} column:`, result.error);
  } else {
    console.log(`Created ${columnData.type} column:`, result.data);
  }
}

Listing and Filtering Columns

// List all columns in a table
const allColumns = await client.columns.findAll('users');

// Filter columns by type
const textColumns = await client.columns.findAll('users', {
  where: { type: 'text' },
});

// Get a specific column
const column = await client.columns.findOne('users', {
  where: { name: 'email' },
});

// Get column by UUID
const columnById = await client.columns.findById('users', 'column-id');

Updating Columns

// Update column properties
const updateResult = await client.columns.update('users', 'description', {
  description: 'Updated user description',
});

Deleting Columns

// Delete a column
const deleteResult = await client.columns.delete('users', 'description');

Record Operations

Inserting Records

// Insert a single record
const recordData = {
  name: 'John Doe',
  email: '[email protected]',
  age: 30,
  salary: 75000,
  is_active: true,
  role: 'Admin',
};

const insertResult = await client.records.insert('users', recordData);

if (insertResult.error) {
  console.error('Record insertion failed:', insertResult.error);
} else {
  console.log('Record inserted:', insertResult.data);
}

// Insert multiple records using insertMany() for better performance
const multipleRecords = [
  {
    name: 'Jane Smith',
    email: '[email protected]',
    age: 28,
    salary: 65000,
    is_active: true,
    role: 'User',
  },
  {
    name: 'Bob Johnson',
    email: '[email protected]',
    age: 35,
    salary: 70000,
    is_active: true,
    role: 'Admin',
  },
];

// Bulk insert with validation (default)
const bulkResult = await client.records.insertMany('users', multipleRecords);

if (bulkResult.error) {
  console.error('Bulk insertion failed:', bulkResult.error);
} else {
  console.log(`Successfully inserted ${bulkResult.data.insert_count} records`);
  console.log('Inserted records:', bulkResult.data.records);
}

// Bulk insert without validation
const bulkNoValidationResult = await client.records.insertMany(
  'users',
  multipleRecords,
  { validation: false }
);

Note:

• Unlike single insert(), insertMany() requires complete records. All required fields must be provided in insertMany() call.

Querying Records

// Find all records
const allRecords = await client.records.findAll('users');

// Find records with pagination
const paginatedRecords = await client.records.findAll('users', {
  page: {
    page_no: 1,
    page_size: 10,
  },
});

// Find records with filters (API format)
const filteredRecords = await client.records.findAll('users', {
  filters: [
    { field: 'age', operator: '>=', values: [25] },
    { field: 'is_active', operator: '=', values: [true] },
    { field: 'role', operator: 'IN', values: ['Admin', 'User'] },
  ],
});

// Find records with sorting
const sortedRecords = await client.records.findAll('users', {
  sort: [
    { field: 'age', order: 'desc' },
    { field: 'name', order: 'asc' },
  ],
});

// Find a specific record
const specificRecord = await client.records.findOne('users', 'record-id');

// Find one record with filters
const filteredRecord = await client.records.findAll('users', {
  filters: [
    { field: 'email', operator: '=', values: ['[email protected]'] },
  ],
});

Advanced Filtering

The SDK supports comprehensive filtering with various operators:

// Text field filters
const textFilters = [
  { field: 'name', operator: '=', values: ['John'] }, // Equals
  { field: 'name', operator: '!=', values: ['Admin'] }, // Not equals
  { field: 'name', operator: 'LIKE', values: ['%John%'] }, // Contains (case sensitive)
  { field: 'name', operator: 'ILIKE', values: ['%john%'] }, // Contains (case insensitive)
  { field: 'name', operator: 'STARTS WITH', values: ['J'] }, // Starts with
  { field: 'name', operator: 'IN', values: ['John', 'Jane'] }, // Is one of
  { field: 'name', operator: 'IS EMPTY', values: [false] }, // Is not empty
];

// Number field filters
const numberFilters = [
  { field: 'age', operator: '>', values: [30] }, // Greater than
  { field: 'age', operator: '>=', values: [30] }, // Greater than or equal
  { field: 'age', operator: '<', values: [35] }, // Less than
  { field: 'age', operator: '<=', values: [35] }, // Less than or equal
  { field: 'age', operator: 'BETWEEN', values: [25, 35] }, // Between
  { field: 'age', operator: 'IN', values: [25, 30, 35] }, // Is one of
];

// Boolean field filters
const booleanFilters = [
  { field: 'is_active', operator: '=', values: [true] }, // Is true
  { field: 'is_active', operator: '=', values: [false] }, // Is false
];

// Date field filters
const dateFilters = [
  { field: 'created_at', operator: '>', values: ['2024-01-01T00:00:00Z'] },
  {
    field: 'created_at',
    operator: 'BETWEEN',
    values: ['2024-01-01T00:00:00Z', '2024-12-31T23:59:59Z'],
  },
  { field: 'created_at', operator: 'WITHIN', values: ['last-30-days'] },
];

// Array/dropdown field filters
const arrayFilters = [
  { field: 'tags', operator: '@>', values: [['tag1']] }, // Array contains
  { field: 'tags', operator: 'ANY', values: ['tag1'] }, // Any element matches
  { field: 'category', operator: 'IS ONE OF', values: ['tech', 'business'] },
];

// Vector field filters
const vectorFilters = [
  { field: 'embedding', operator: '!=', values: [null] }, // Not null
  { field: 'embedding', operator: '<->', values: ['[0.1,0.2,0.3]'] }, // Euclidean distance
  { field: 'embedding', operator: '<=>', values: ['[0.1,0.2,0.3]'] }, // Cosine distance
];

// Multiple conditions (AND logic)
const multipleFilters = await client.records.findAll('users', {
  filters: [
    { field: 'age', operator: '>=', values: [25] },
    { field: 'is_active', operator: '=', values: [true] },
    { field: 'salary', operator: '>', values: [50000] },
  ],
});

Updating Records

// Update records by filters
const updateResult = await client.records.update('users', {
  set: { is_active: false },
  filters: [{ field: 'role', operator: '=', values: ['Guest'] }],
});

// Update record by ID
const updateByIdResult = await client.records.updateById(
  'users',
  'record-id-here',
  {
    salary: 80000,
  }
);

Deleting Records

// Delete records by filters
const deleteResult = await client.records.delete('users', {
  filters: [{ field: 'is_active', operator: '=', values: [false] }],
});

// Delete records by IDs
const deleteByIdsResult = await client.records.delete('users', {
  record_ids: ['id1', 'id2', 'id3'],
});

// Delete with multiple filter conditions
const deleteWithFilters = await client.records.delete('users', {
  filters: [{ field: 'is_active', operator: '=', values: [false] }],
});

Bulk Insert Operations

The SDK provides an efficient insertMany() method for inserting multiple records in a single API call:

// Bulk insert with validation (default behavior)
const records = [
  { name: 'User 1', email: '[email protected]', age: 25 },
  { name: 'User 2', email: '[email protected]', age: 30 },
  { name: 'User 3', email: '[email protected]', age: 35 },
];

const result = await client.records.insertMany('users', records);

if (result.error) {
  console.error('Bulk insertion failed:', result.error);
} else {
  console.log(`Successfully inserted ${result.data.insert_count} records`);
  console.log('Response:', result.data);
}

// Bulk insert without validation (faster, less safe)
const resultNoValidation = await client.records.insertMany('users', records, {
  validation: false,
});

SQL Operations

The Boltic SDK provides powerful SQL capabilities including natural language to SQL conversion and direct SQL query execution.

Text-to-SQL Conversion

Convert natural language descriptions into SQL queries using AI:

// Basic text-to-SQL conversion (streaming)
const sqlStream = await client.sql.textToSQL(
  'Find all active users who registered this year'
);

// Collect the streaming response
let generatedSQL = '';
for await (const chunk of sqlStream) {
  process.stdout.write(chunk); // Real-time output
  generatedSQL += chunk;
}

console.log('\nGenerated SQL:', generatedSQL);

SQL Query Refinement

Refine existing SQL queries with additional instructions:

// Start with a base query
const baseQuery = `SELECT * FROM "users" WHERE "created_at" > '2024-01-01'`;

// Refine it with additional instructions
const refinedStream = await client.sql.textToSQL(
  'Add sorting by registration date and limit to 10 results',
  {
    currentQuery: baseQuery,
  }
);

// Process the refined query
let refinedSQL = '';
for await (const chunk of refinedStream) {
  refinedSQL += chunk;
}

console.log('Refined SQL:', refinedSQL);

SQL Query Execution

Execute SQL queries directly with built-in safety measures:

// Execute a simple SQL query
const result = await client.sql.executeSQL(
  `SELECT "name", "email" FROM "users" WHERE "is_active" = true`
);

if (result.error) {
  console.error('SQL execution failed:', result.error);
} else {
  // Extract data from Boltic API Response Structure
  const [resultRows, metadata] = result.data;

  console.log('Query results:', resultRows);
  console.log('Metadata:', metadata);

  if (result.pagination) {
    console.log('Total records:', result.pagination.total_count);
    console.log('Current page:', result.pagination.current_page);
  }
}

UUID Casting in Joins

The id field uses PostgreSQL's UUID type. When joining or comparing id with text columns, cast with ::text:

const result = await client.sql.executeSQL(`
  SELECT u.name, p.title 
  FROM "users" u
  JOIN "posts" p ON u.id::text = p.user_id
`);

// Multi-table joins with UUID casting
const complex = await client.sql.executeSQL(`
  SELECT u.name, p.title, c.content
  FROM "users" u
  JOIN "posts" p ON u.id::text = p.user_id
  JOIN "comments" c ON p.id::text = c.post_id
  WHERE u.id::text IN ('uuid1', 'uuid2')
`);

Why UUID Casting is Required:

• The id field uses PostgreSQL's UUID type internally
• When comparing UUIDs with text columns (like foreign key references), PostgreSQL requires explicit type casting
• The ::text operator converts the UUID to its string representation for comparison
• This applies to all system-generated id fields (id, and potentially foreign key references)

SQL Error Handling

try {
  const result = await client.sql.executeSQL(
    'SELECT * FROM "non_existent_table"'
  );

  if (result.error) {
    console.error('SQL Error:', result.error);

    // Access detailed error information
    console.log('Error code:', result.error.code);
    console.log('Error details:', result.error.details);
  }
} catch (error) {
  console.error('SQL execution exception:', error);
}

Workflow Operations

The SDK provides workflow integration capabilities — execute activities against third-party integrations, poll for results, browse available integrations, and fetch form schemas.

Executing an Integration Activity

Execute an activity and automatically poll until completion:

const result = await client.workflow.executeIntegration({
  data: {
    type: 'apiActivity',
    name: 'api1',
    properties: {
      method: 'get',
      endpoint: 'https://dummyjson.com/products',
      query_params: {},
      headers: {},
      body: null,
      body_type: 'none',
      api_timeout: 30000,
      maximum_timeout: 60000,
      integration_slug: 'blt-int.api',
    },
  },
});

if (result.error) {
  console.error('Execution failed:', result.error);
} else {
  console.log('Execution result:', result.data);
}

Fire-and-Forget Execution

Return immediately after triggering the activity without waiting for completion:

const result = await client.workflow.executeIntegration({
  data: {
    type: 'apiActivity',
    name: 'api1',
    properties: {
      method: 'get',
      endpoint: 'https://dummyjson.com/products',
      integration_slug: 'blt-int.api',
    },
  },
  executeOnly: true,
});

if (!result.error) {
  const executionId = result.data.execution_id;
  console.log('Execution started:', executionId);
}

Getting Execution Result by ID

Retrieve the result of a previously triggered execution:

const result = await client.workflow.getIntegrationExecuteById('execution-id-here');

if (!result.error) {
  console.log('Execution data:', result.data);
}

Listing Available Integrations

const result = await client.workflow.getIntegrations();

if (!result.error) {
  console.log('Integrations:', result.data);
}

Getting Credentials for an Integration

const result = await client.workflow.getCredentials({
  entity: 'asana',
});

if (!result.error) {
  console.log('Credentials:', result.data);
}

Getting Integration Resource Schema

Fetch the available resources and operations for an integration:

const result = await client.workflow.getIntegrationResource({
  integration_slug: 'blt-int.asana',
});

if (!result.error) {
  console.log('Resources & operations:', result.data);
}

Getting Integration Form Schema

Fetch the input form fields for a specific integration resource and operation. Returns default values by default, or a JSON Schema when asJsonSchema: true:

// Get default values for each field
const defaults = await client.workflow.getIntegrationForm({
  integration_slug: 'blt-int.asana',
  resource: 'project',
  operation: 'create',
  secret: 'credential-secret-here',
});

// Get JSON Schema describing the expected input shape
const schema = await client.workflow.getIntegrationForm({
  integration_slug: 'blt-int.asana',
  resource: 'project',
  operation: 'create',
  secret: 'credential-secret-here',
  asJsonSchema: true,
});

Advanced Features

Vector Columns for AI/ML

// Create vector columns for AI/ML applications
const vectorColumns = [
  {
    name: 'embedding',
    type: 'vector',
    vector_dimension: 1536,
    description: 'Text embedding vector',
  },
  {
    name: 'half_embedding',
    type: 'halfvec',
    vector_dimension: 768,
    description: 'Half precision vector',
  },
  {
    name: 'sparse_features',
    type: 'sparsevec',
    vector_dimension: 5,
    description: 'Sparse vector features (example: {1:1,3:2,5:3}/5)',
  },
];

// Sparse Vector Format Example:
// {1:1,3:2,5:3}/5 represents a 5-dimensional vector where:
// - Position 1 has value 1
// - Position 3 has value 2
// - Position 5 has value 3
// - Positions 2 and 4 are implicitly 0

for (const vectorColumn of vectorColumns) {
  await client.columns.create('vectors', vectorColumn);
}

Configuration Management

// Update API key
client.updateApiKey('new-api-key');

// Update configuration
client.updateConfig({
  debug: true,
  timeout: 45000,
});

// Get current configuration
const config = client.getConfig();
console.log('Current config:', config);

Error Handling

The SDK provides comprehensive error handling with detailed error objects:

try {
  const result = await client.tables.create({
    name: 'test-table',
    fields: [{ name: 'id', type: 'text' }],
  });

  if (result.error) {
    console.error('Operation failed:', result.error);

    // Handle specific error cases
    if (
      result.error.message &&
      result.error.message.includes('already exists')
    ) {
      console.log('Table already exists, continuing...');
    }

    // Access error details
    console.log('Error code:', result.error.code);
    console.log('Error details:', result.error.details);
    console.log('Error message:', result.error.message);
  } else {
    console.log('Success:', result.data);
  }
} catch (error) {
  console.error('API Error:', error.message);
}

Error Object Structure

interface ErrorResponse {
  error: {
    message: string; // Human-readable error message
    code?: string; // Specific error code
    details?: string[]; // Additional details
  };
  data?: null;
}

Regions

The SDK supports multiple regions for global deployment:

• asia-south1 (default): Asia Pacific (Mumbai) region
• us-central1: US Central (Iowa) region

Each region has its own API endpoints and environment configurations.

Module Formats

The SDK supports both ES modules and CommonJS:

// ES Modules / TypeScript (recommended)
import { createClient } from '@boltic/sdk';

// CommonJS
const { createClient } = require('@boltic/sdk');

API Reference

Core Client

• createClient(apiKey: string, options?: ClientOptions): Initialize the Boltic client
• client.useDatabase(dbInternalName?: string): Switch the active database context (omit/reset to use default database)
• client.getCurrentDatabase(): Get the current database context (null means default database)

Databases (Custom Databases)

• client.databases.create(data): Create a new database
• client.databases.findAll(options?): List active databases with optional pagination/sorting/filtering
• client.databases.findOne(dbInternalName, options?): Get a database by internal name (slug)
• client.databases.getDefault(): Get the default database
• client.databases.update(dbInternalName, data): Update database display name
• client.databases.delete(dbInternalName): Delete a database (starts an async job; default database cannot be deleted)
• client.databases.listJobs(options?): List database jobs (primarily deletion jobs)
• client.databases.pollDeleteStatus(jobId): Poll status of an async deletion job

Tables

• client.tables.create(data): Create a new table
• client.tables.findAll(options?): List tables with optional filtering
• client.tables.findOne(options): Get a specific table
• client.tables.findByName(name): Get table by name
• client.tables.update(identifier, data): Update table properties
• client.tables.rename(oldName, newName): Rename a table
• client.tables.delete(name): Delete a table by name

Columns

• client.columns.create(tableName, data): Create a new column
• client.columns.findAll(tableName, options?): List columns with optional filtering
• client.columns.findOne(tableName, options): Get a specific column
• client.columns.findById(tableName, columnId): Get column by ID
• client.columns.update(tableName, columnName, data): Update column properties
• client.columns.delete(tableName, columnName): Delete a column

Records

• client.records.insert(tableName, data): Insert a new record
• client.records.insertMany(tableName, records, options?): Insert multiple records in bulk
• client.records.findAll(tableName, options?): List records with optional filtering
• client.records.findOne(tableName, idOrOptions): Get a specific record
• client.records.update(tableName, options): Update records by filters
• client.records.updateById(tableName, options): Update record by ID
• client.records.delete(tableName, options): Delete records by filters or IDs

SQL Operations

• client.sql.textToSQL(prompt, options?): Convert natural language to SQL query (streaming)
• client.sql.executeSQL(query): Execute SQL query with safety measures

Workflow Operations

• client.workflow.executeIntegration(params): Execute an integration activity. Polls until completion by default; set executeOnly: true to return immediately.
• client.workflow.getIntegrationExecuteById(executionId): Get the result of a workflow execution by run ID
• client.workflow.getIntegrations(params?): List available integrations with optional pagination
• client.workflow.getCredentials(params): Fetch credentials for an integration entity
• client.workflow.getIntegrationResource(params): Fetch the resource/operation schema for an integration
• client.workflow.getIntegrationForm(params): Fetch form field schema for a specific resource + operation. Returns default values or JSON Schema (asJsonSchema: true).

Examples and Demos

Check out the comprehensive demo files for complete usage examples:

• Database Operations Demo — Tables, columns, records, indexes, filters, bulk ops
• SQL Operations Demo — Text-to-SQL conversion and SQL query execution
• Workflow Integration Demo — Execute activities, poll results, list integrations, fetch form schemas

Run any example:

npx tsx src/services/workflows/examples/workflow-test.ts all
npx tsx src/services/databases/examples/basic/comprehensive-database-operations-demo.ts

Development

# Install dependencies
npm install

# Build the package
npm run build

# Run tests
npm test

# Type checking
npm run type-check

# Linting
npm run lint

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Support

For support, email [email protected] or create an issue on GitHub.

License

This project is licensed under the MIT License - see the LICENSE file for details.