boostgpt

v3.5.0

Published

a month ago

BoostGPT client library for nodejs.

0High
0Medium
0Low

davmixcool

vector search gpt chatgpt boostgpt openai anthropic embeddings customgpt llm xai gemini agi ai esm es6 modules

Features

Full ES Modules (ESM) and CommonJS (CJS) support
Complete API coverage for all BoostGPT endpoints
Bot/Agent management (create, read, update, delete)
Chat operations with streaming support
Memory source/training management
User memory management (per-user semantic, episodic, procedural memories)
Workflows (create, run, and monitor multi-step automations)
Heartbeats (scheduled autonomous agent runs with cron support)
Workspaces (sandbox file system — read, write, publish)
Email inbox management (read, reply, configure)
CRM (contacts, custom fields, pipelines, deals, tasks)
MCP connector management (deploy from catalog, OpenAPI, or Postman)
Tools management (MCP server integration)
Message voting and feedback
Subscriber management
Comprehensive analytics and statistics
TypeScript-friendly (type definitions coming soon)

Requirements

Node.js >= 12.20.0
For ES Modules: Node.js >= 14.0.0 recommended
BoostGPT API Key

Installation

npm install boostgpt

Usage

ES Modules (Recommended)

import { BoostGPT } from 'boostgpt';

const client = new BoostGPT({
    project_id: 'your-project-id',
    key: 'your-api-key'
});

// Create a bot
const botResponse = await client.createBot({
    name: 'My Bot',
    model: 'gpt-4o-min',
    instruction: 'You are a helpful assistant',
    max_reply_tokens: 1000,
    status: 1
});

if (botResponse.err) {
    console.error('Error:', botResponse.err);
} else {
    console.log('Bot created:', botResponse.response);
}

// Chat with the bot
const chatResponse = await client.chat({
    bot_id: 'bot-id',
    message: 'Hello, how are you?'
});

console.log('Response:', chatResponse.response);

CommonJS (Legacy Support)

const { BoostGPT } = require('boostgpt');

const client = new BoostGPT({
    project_id: 'your-project-id',
    key: 'your-api-key'
});

// Use async/await or promises
(async () => {
    const botResponse = await client.createBot({
        name: 'My Bot',
        model: 'gpt-4o-min',
        instruction: 'You are a helpful assistant'
    });
    
    console.log(botResponse.response);
})();

API Reference

Constructor

const client = new BoostGPT({
    project_id: 'your-project-id',  // Required
    key: 'your-api-key'              // Required
});

Bot Management

Create Bot

await client.createBot({
    name: 'Bot Name',
    model: 'gpt-4o-min',
    instruction: 'System instruction',
    max_reply_tokens: 1000,
    status: 1
});

Fetch Bot

await client.fetchBot(bot_id);

Fetch All Bots

await client.fetchBots({
    page: 1,
    per_page: 10
});

Update Bot

await client.updateBot({
    bot_id: 'bot-id',
    name: 'Updated Name',
    model: 'gpt-5.1',
    instruction: 'Updated instruction',
    max_reply_tokens: 1500,
    status: "0" // 1 = online, 0 = offline
});

Reset Bot

await client.resetBot(bot_id);

Delete Bot

await client.deleteBot(bot_id);

Chat Operations

Send Chat Message

await client.chat({
    bot_id: 'bot-id',
    model: 'gpt-4o-min',  //Optional
    provider_key: 'optional-provider-key', //Optional
    provider_host: 'optionl-provider-host', // Only needed and required when using ollama models
    instruction: 'Optional override instruction',
    reasoning_mode: 'optional-reasoning-mode', //Default to standard
    source_ids: ['source1', 'source2'], //Optional
    message: 'Your message here',
    max_reply_tokens: 1000,  //Optional
    chat_id: 'optional-chat-id',
    stream: false,  //Optional
    memory: false // Optional: Disables the agents memory
});

Search

await client.search({
    bot_id: 'bot-id',
    source_ids: ['source1', 'source2'],
    keywords: 'search terms'
});

Fetch Chat

await client.fetchChat({
    bot_id: 'bot-id',
    chat_id: 'chat-id',
    page: 1,
    per_page: 10
});

Fetch All Chats

await client.fetchChats({
    bot_id: 'bot-id',
    page: 1,
    per_page: 10
});

Delete Chat

await client.deleteChat({
    chat_id: 'chat-id',
    bot_id: 'bot-id'
});

Execute Tool

await client.executeTool({
    bot_id: 'bot-id',
    chat_id: 'chat-id',
    tool_calls: [
        {
            tool_name: 'calculator',
            parameters: { operation: 'add', a: 5, b: 3 }
        }
    ]
});

Vote on Message

await client.voteMessage({
    bot_id: 'bot-id',
    message_id: 'message-id',
    voter_id: 'user-id',
    voter_type: 'member',
    vote_type: 'upvote' // or 'downvote'
});

Fetch Vote Status

await client.fetchVoteStatus({
    bot_id: 'bot-id',
    message_id: 'message-id',
    voter_id: 'user-id',
    voter_type: 'member'
});

Delete Message

await client.deleteMessage({
    bot_id: 'bot-id',
    chat_id: 'chat-id',
    message_id: 'message-id'
});

Training/Source Management

Start Training

await client.startTraining({
    bot_id: 'bot-id',
    type: 'text',
    source: 'Training content here'
});

Fetch Training

await client.fetchTraining({
    source_id: 'source-id',
    bot_id: 'bot-id'
});

Fetch All Trainings

await client.fetchTrainings({
    bot_id: 'bot-id',
    page: 1,
    per_page: 10
});

Update Training

await client.updateTraining({
    source_id: 'source-id',
    bot_id: 'bot-id',
    type: 'text',
    source: 'Updated content'
});

Delete Training

await client.deleteTraining({
    source_id: 'source-id',
    bot_id: 'bot-id'
});

Tools Management

Fetch Tools

await client.fetchTools({
    bot_id: 'bot-id',
    page: 1,
    per_page: 10,
    filter: { type: 'mcp' } // Optional filter
});

Create Tool

await client.createTool({
    bot_id: 'bot-id',
    name: 'My Tool',
    description: 'Tool description',
    config: {
        url: 'https://api.example.com',
        auth: 'bearer_token'
    },
    type: 'mcp'
});

Fetch Tool

await client.fetchTool({
    tool_id: 'tool-id',
    bot_id: 'bot-id'
});

Update Tool

await client.updateTool({
    tool_id: 'tool-id',
    bot_id: 'bot-id',
    name: 'Updated Tool Name',
    description: 'Updated description',
    config: { /* updated config */ },
    type: 'mcp'
});

Delete Tool

await client.deleteTool({
    tool_id: 'tool-id',
    bot_id: 'bot-id'
});

Configure Tools

await client.configureTools({
    tool_id: 'tool-id',
    bot_id: 'bot-id',
    settings: {
        enabled: true,
        timeout: 30000
    }
});

Refresh Tools

await client.refreshTools({
    tool_id: 'tool-id',
    bot_id: 'bot-id'
});

Toggle Tool

await client.toggleTool({
    tool_id: 'tool-id',
    bot_id: 'bot-id',
    tool_name: 'specific-tool',
    active: true
});

Test Tool Connection

await client.testToolConnection({
    tool_id: 'tool-id',
    bot_id: 'bot-id'
});

User Memory

List Memories

await client.fetchMemories({
    bot_id: 'bot-id',
    user_uuid: 'user-uuid',  // optional: filter by user
    type: 'semantic',         // optional: 'semantic' | 'episodic' | 'procedural' | 'all'
    page: 1,
    per_page: 50
});

Count Memories

await client.countMemories({
    bot_id: 'bot-id',
    user_uuid: 'user-uuid'
});

Delete a Memory

await client.deleteMemory({
    bot_id: 'bot-id',
    memory_id: 'mem-uuid'
});

Workflows

Fetch Workflow Catalog

await client.fetchWorkflowCatalog({ bot_id: 'bot-id' });

List Workflows

await client.fetchWorkflows({ bot_id: 'bot-id' });

Get a Workflow

await client.fetchWorkflow({ bot_id: 'bot-id', workflow_id: 'wf-id' });

Create a Workflow

await client.createWorkflow({
    bot_id: 'bot-id',
    name: 'Lead Qualification',
    trigger: 'webhook',
    steps: [/* step objects */]
});

Update a Workflow

await client.updateWorkflow({
    bot_id: 'bot-id',
    workflow_id: 'wf-id',
    enabled: true
});

Delete a Workflow

await client.deleteWorkflow({ bot_id: 'bot-id', workflow_id: 'wf-id' });

Run a Workflow

await client.runWorkflow({ bot_id: 'bot-id', workflow_id: 'wf-id' });

Fetch Workflow Logs

await client.fetchWorkflowLogs({ bot_id: 'bot-id' });

Heartbeats

Create / Update a Heartbeat

await client.createHeartbeat({
    bot_id: 'bot-id',
    prompt: 'Check for new support tickets and summarize urgent ones',
    cron_pattern: '0 9 * * 1-5',   // weekdays at 9am
    enabled: true,
    timezone: 'America/New_York',
    credit_budget: 100,
    max_consecutive_errors: 5
});

Get a Heartbeat

await client.fetchHeartbeat({ bot_id: 'bot-id', heartbeat_id: 'hb-id' });

List Heartbeats

await client.fetchHeartbeats({ bot_id: 'bot-id' });

Enable / Disable

await client.enableHeartbeat({ bot_id: 'bot-id', heartbeat_id: 'hb-id' });
await client.disableHeartbeat({ bot_id: 'bot-id', heartbeat_id: 'hb-id' });

Trigger Manually

await client.triggerHeartbeat({ bot_id: 'bot-id', heartbeat_id: 'hb-id' });

Delete a Heartbeat

await client.deleteHeartbeat({ bot_id: 'bot-id', heartbeat_id: 'hb-id' });

Fetch Logs & Stats

await client.fetchHeartbeatLogs({ bot_id: 'bot-id' });
await client.fetchHeartbeatStats({ bot_id: 'bot-id' });

Workspaces

List Workspaces

await client.fetchWorkspaces({ bot_id: 'bot-id' });

Create / Delete Workspace

await client.createWorkspace({ bot_id: 'bot-id', name: 'My Workspace' });
await client.deleteWorkspace({ bot_id: 'bot-id', workspace_uuid: 'ws-uuid' });

File Operations

// List files
await client.fetchFiles({ bot_id: 'bot-id', workspace_uuid: 'ws-uuid' });

// Read a file
await client.readFile({ bot_id: 'bot-id', workspace_uuid: 'ws-uuid', file_uuid: 'file-uuid' });

// Create a file
await client.createFile({
    bot_id: 'bot-id',
    workspace_uuid: 'ws-uuid',
    file_path: '/src/app.js',
    content: 'console.log("hello");',
    language: 'javascript'
});

// Update a file
await client.updateFile({
    bot_id: 'bot-id',
    workspace_uuid: 'ws-uuid',
    file_uuid: 'file-uuid',
    content: '// updated content'
});

// Rename / move a file
await client.renameFile({
    bot_id: 'bot-id',
    workspace_uuid: 'ws-uuid',
    old_path: '/src/app.js',
    new_path: '/src/main.js'
});

// Delete a file
await client.deleteFile({ bot_id: 'bot-id', workspace_uuid: 'ws-uuid', file_uuid: 'file-uuid' });

// Download workspace as ZIP
await client.downloadWorkspace({ bot_id: 'bot-id', workspace_uuid: 'ws-uuid' });

Publishing

await client.suggestSubdomain({ bot_id: 'bot-id', workspace_uuid: 'ws-uuid' });
await client.publishWorkspace({ bot_id: 'bot-id', workspace_uuid: 'ws-uuid', subdomain: 'my-app' });
await client.unpublishWorkspace({ bot_id: 'bot-id', workspace_uuid: 'ws-uuid' });

// Custom domain
await client.addCustomDomain({ bot_id: 'bot-id', workspace_uuid: 'ws-uuid', domain: 'app.example.com' });
await client.removeCustomDomain({ bot_id: 'bot-id', workspace_uuid: 'ws-uuid' });
await client.refreshDomainStatus({ bot_id: 'bot-id', workspace_uuid: 'ws-uuid' });
await client.getDomainInfo({ bot_id: 'bot-id', workspace_uuid: 'ws-uuid' });

Email Inbox

Get Email Address

await client.fetchEmailAddress({ bot_id: 'bot-id' });

Update Settings

await client.updateEmailSettings({
    bot_id: 'bot-id',
    auto_reply: true,
    signature: 'Best, Support Team'
});

Stats, List, Read, Reply, Delete

await client.fetchEmailStats({ bot_id: 'bot-id' });

await client.fetchEmails({ bot_id: 'bot-id', page: 1, per_page: 20 });

await client.fetchEmail({ bot_id: 'bot-id', email_id: 'email-uuid' });

await client.replyToEmail({
    bot_id: 'bot-id',
    email_id: 'email-uuid',
    content: 'Thanks for reaching out!'
});

await client.deleteEmail({ bot_id: 'bot-id', email_id: 'email-uuid' });

CRM

Contacts

// List / search
await client.fetchContacts({ bot_id: 'bot-id', page: 1, per_page: 20, status: 'lead' });
await client.searchContacts({ bot_id: 'bot-id', query: 'jane', limit: 10 });
await client.fetchContactStatuses({ bot_id: 'bot-id' });

// CRUD
await client.createContact({
    bot_id: 'bot-id',
    email: '[email protected]',
    status: 'lead',
    fields: { first_name: 'Jane', company: 'Acme' }
});
await client.fetchContact({ bot_id: 'bot-id', contact_id: 'con-id' });
await client.updateContact({ bot_id: 'bot-id', contact_id: 'con-id', status: 'customer' });
await client.deleteContact({ bot_id: 'bot-id', contact_id: 'con-id' });           // soft delete
await client.deleteContact({ bot_id: 'bot-id', contact_id: 'con-id', permanent: true }); // hard delete

// Export & notes
await client.exportContacts({ bot_id: 'bot-id' });
await client.addContactNote({ bot_id: 'bot-id', contact_id: 'con-id', content: 'Called.', type: 'call' });

Custom Fields

await client.fetchCRMFields({ bot_id: 'bot-id' });
await client.createCRMField({ bot_id: 'bot-id', label: 'Company Size', field_type: 'select', options: ['1-10', '11-50'] });
await client.updateCRMField({ bot_id: 'bot-id', field_id: 'fld-id', label: 'Headcount' });
await client.deleteCRMField({ bot_id: 'bot-id', field_id: 'fld-id' });

Setup & Templates

await client.fetchCRMSetup({ bot_id: 'bot-id' });
await client.fetchCRMTemplates({ bot_id: 'bot-id' });
await client.applyCRMTemplate({ bot_id: 'bot-id', template_key: 'sales', name: 'Q3 Pipeline' });

Pipelines

await client.fetchPipelines({ bot_id: 'bot-id' });
await client.createPipeline({ bot_id: 'bot-id', name: 'Enterprise', default_currency: 'USD' });
await client.updatePipeline({ bot_id: 'bot-id', pipeline_id: 'pipe-id', is_default: true });
await client.deletePipeline({ bot_id: 'bot-id', pipeline_id: 'pipe-id' });
await client.fetchPipelineBoard({ bot_id: 'bot-id', pipeline_id: 'pipe-id' });

// Stages
await client.createPipelineStage({ bot_id: 'bot-id', name: 'Proposal', pipeline_id: 'pipe-id' });
await client.updatePipelineStage({ bot_id: 'bot-id', stage_id: 'stg-id', closed_status: 'won' });
await client.deletePipelineStage({ bot_id: 'bot-id', stage_id: 'stg-id', move_deals_to_stage_id: 'stg-other' });

Deals

await client.fetchDeals({ bot_id: 'bot-id', status: 'open', pipeline_id: 'pipe-id' });
await client.createDeal({ bot_id: 'bot-id', title: 'Acme Corp — Pro', status: 'open' });
await client.updateDeal({ bot_id: 'bot-id', deal_id: 'deal-id', status: 'won' });
await client.deleteDeal({ bot_id: 'bot-id', deal_id: 'deal-id' });

Tasks

await client.fetchTasks({ bot_id: 'bot-id', status: 'todo' });
await client.createTask({ bot_id: 'bot-id', title: 'Follow up with Jane', priority: 'high' });
await client.updateTask({ bot_id: 'bot-id', task_id: 'tsk-id', status: 'done' });
await client.snoozeTask({ bot_id: 'bot-id', task_id: 'tsk-id' });
await client.deleteTask({ bot_id: 'bot-id', task_id: 'tsk-id' });
await client.fetchCRMReport({ bot_id: 'bot-id' });

MCP Connectors

Connector Catalog

// List all available connectors
await client.fetchConnectors();

// Get connector details (auth requirements, tools)
await client.fetchConnector('jamendo');

Deploy MCP Servers

// From a pre-built connector
await client.createMcpFromPredefined({
    name: 'My Jamendo Server',
    connectorName: 'jamendo',
    credentials: { client_id: 'your_client_id' }
});

// From an OpenAPI spec
await client.createMcpFromOpenApi({
    name: 'My API Server',
    openApiSpec: { /* OpenAPI 3.0 object */ },
    credentials: { api_key: 'sk-xxx' }
});

// From a Postman collection
await client.createMcpFromPostman({
    name: 'My Postman Server',
    postmanCollection: { /* Postman Collection v2.1 */ }
});

Manage Servers

await client.fetchMcpServers();
await client.fetchMcpServer('server-uuid');
await client.updateMcpServer({ id: 'server-uuid', name: 'Renamed' });
await client.cloneMcpServer({ id: 'server-uuid', name: 'Clone' });
await client.deleteMcpServer('server-uuid');
await client.fetchMcpUsage('server-uuid');

Validate Specs

await client.validateOpenApi({ spec: openApiObject });
await client.validatePostman({ collection: postmanObject });

Subscribers

Fetch Subscribers

await client.fetchSubscribers({
    page: 1,
    per_page: 10
});

Analytics

Fetch Vote Statistics

await client.fetchVoteStats({
    bot_id: 'bot-id'
});

Fetch Summary Statistics

await client.fetchSummaryStats({
    bot_id: 'bot-id'
});

Fetch Dashboard Statistics

await client.fetchDashboardStats({
    bot_id: 'bot-id'
});

Fetch Tool Usage Statistics

await client.fetchToolUsageStats({
    bot_id: 'bot-id'
});

Fetch Workflow Statistics

await client.fetchWorkflowStats({
    bot_id: 'bot-id'
});

Fetch Performance Metrics

await client.fetchPerformanceMetrics({
    bot_id: 'bot-id'
});

Fetch User Behavior Statistics

await client.fetchBehaviorStats({
    bot_id: 'bot-id'
});

Fetch Error Analysis

await client.fetchErrorAnalysis({
    bot_id: 'bot-id'
});

Fetch Reasoning Summary

await client.fetchReasoningSummary({
    bot_id: 'bot-id'
});

Response Format

All methods return a BoostGPTResponse object:

{
    err: null | Error,        // Error object if request failed
    response: null | Object   // Response data if request succeeded
}

Example error handling:

const result = await client.createBot({ name: 'My Bot' });

if (result.err) {
    console.error('Request failed:', result.err.message);
} else {
    console.log('Success:', result.response);
}

Development

Building the Package

# Install dependencies
npm install

# Build CommonJS files from ESM source
npm run build

The build process converts the ES Module source files in src/ to CommonJS in dist/.

Project Structure

src/ - ES Module source code (edit these files)
dist/ - Generated CommonJS build (don't edit, auto-generated)
build.js - Build script that transpiles ESM to CJS
package.json - Configured with "type": "module" and dual exports

Making Changes

Edit files in src/ (ESM format)
Run npm run build to generate CJS in dist/
Test both ESM and CJS usage
The prepublishOnly script automatically builds before publishing

TypeScript Support

While this package is written in JavaScript, it works with TypeScript. Type definitions may be added in a future release.

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Make your changes in src/
Run npm run build
Test both ESM and CJS usage
Submit a Pull Request

License

MIT

Support

For support, please visit the GitHub Issues page.