@japfa/jarvis-sdk

Official Node.js SDK for JAPFA Jarvis - AI-powered knowledge base with multi-database support.

✨ Features

• 🗄️ Multi-Database Support - PostgreSQL, MySQL, and Oracle
• 🔄 Automatic Migrations - Create tables automatically on initialization
• 🛡️ Type-Safe - TypeScript definitions included
• ✅ Validated - Input validation with clear error messages
• 📦 Zero Config - Works out of the box with sensible defaults
• 🚀 Production Ready - Battle-tested and optimized for production use

📋 Requirements

• Node.js >= 18.0.0
• One of: PostgreSQL, MySQL, or Oracle database

📦 Installation

npm install @japfa/jarvis-sdk

📚 Table of Contents

• Quick Start
• Usage
• Configuration
• API Reference
• Examples
• Error Handling
• Tables Created
• Contributing
• License

🚀 Quick Start

Using Fluent API (Recommended)

const Jarvis = require('@japfa/jarvis-sdk');
const { DatabaseTypes } = require('@japfa/jarvis-sdk');

async function main() {
  // Create instance
  const jarvis = new Jarvis();
  
  // Connect
  await jarvis.connect({
    type: DatabaseTypes.POSTGRES,
    host: 'localhost',
    database: 'jarvis',
    user: 'postgres',
    password: 'your_password'
  });

  // Use agents API
  const agents = await jarvis.agents.findAll();
  console.log('Agents:', agents.data);

  // Create agent
  await jarvis.agents.create({
    agent_name: 'My Bot',
    agent_description: 'AI Assistant'
  });

  // Close connection
  await jarvis.close();
}

main();

Using Initialize (For Migrations Only)

const { initialize, DatabaseTypes } = require('@japfa/jarvis-sdk');

const result = await initialize({
  type: DatabaseTypes.POSTGRES,
  host: 'localhost',
  database: 'jarvis',
  user: 'postgres',
  password: 'your_password'
});

await result.adapter.close();

For more details, see the Quick Start Guide.

💻 Usage

Initialize Database

The SDK provides an initialize function to automatically create required tables in your database.

Using DatabaseTypes Enum (Recommended)

const { initialize, DatabaseTypes } = require('@japfa/jarvis-sdk');

async function setup() {
  const result = await initialize({
    type: DatabaseTypes.POSTGRES, // Safe from typos!
    host: 'localhost',
    port: 5432,
    database: 'jarvis',
    user: 'postgres',
    password: 'your_password'
  });

  console.log('Initialized:', result.success);
  await result.adapter.close();
}

setup();

Using String (Also Supported)

const initialize = require('@japfa/jarvis-sdk');

async function setup() {
  const result = await initialize({
    type: 'postgres', // String juga bisa, akan divalidasi
    host: 'localhost',
    port: 5432,
    database: 'jarvis',
    user: 'postgres',
    password: 'your_password'
  });

  console.log('Initialized:', result.success);
  await result.adapter.close();
}

setup();

MySQL

const initialize = require('@japfa/jarvis-sdk');

async function setup() {
  const result = await initialize({
    type: 'mysql',
    host: 'localhost',
    port: 3306,
    database: 'jarvis',
    user: 'root',
    password: 'your_password'
  });

  console.log('Initialized:', result.success);
  await result.adapter.close();
}

setup();

Oracle

const initialize = require('@japfa/jarvis-sdk');

async function setup() {
  const result = await initialize({
    type: 'oracle',
    host: 'localhost',
    port: 1521,
    database: 'ORCL',
    user: 'jarvis',
    password: 'your_password'
  });

  console.log('Initialized:', result.success);
  await result.adapter.close();
}

setup();

Configuration

Database Config

| Property | Type | Required | Description | |----------|------|----------|-------------| | type | string or DatabaseTypes | Yes | Database type: postgres, mysql, or oracle (or use enum) | | host | string | Yes | Database host | | port | number | No | Database port (default: 5432 for postgres, 3306 for mysql, 1521 for oracle) | | database | string | Yes | Database name | | user | string | Yes | Database user | | password | string | Yes | Database password |

DatabaseTypes Enum

const { DatabaseTypes } = require('@japfa/jarvis-sdk');

console.log(DatabaseTypes.POSTGRES);    // 'postgres'
console.log(DatabaseTypes.POSTGRESQL);  // 'postgresql' (alias)
console.log(DatabaseTypes.PG);          // 'pg' (alias)
console.log(DatabaseTypes.MYSQL);       // 'mysql'
console.log(DatabaseTypes.ORACLE);      // 'oracle'

Validation & Error Handling

The SDK validates database type and configuration:

const { initialize, getSupportedDatabaseTypes } = require('@japfa/jarvis-sdk');

// Get list of supported types
console.log(getSupportedDatabaseTypes()); // ['postgres', 'mysql', 'oracle']

// Invalid type will throw error
try {
  await initialize({
    type: 'mongodb', // ❌ Not supported
    host: 'localhost',
    database: 'jarvis',
    user: 'test',
    password: 'test'
  });
} catch (error) {
  console.error(error.message);
  // Error: Invalid database type: "mongodb". Supported types: postgres, postgresql, pg, mysql, oracle
}

// Missing required fields will throw error
try {
  await initialize({
    type: 'postgres'
    // ❌ Missing host, database, user, password
  });
} catch (error) {
  console.error(error.message);
  // Error: Missing required configuration fields: host, database, user, password
}

📊 Tables Created

The initialize function creates the following tables:

1. jarvis_agent

Stores AI agent configurations with settings for temperature, top-k, similarity thresholds, and more.

2. jarvis_knowledgebase_file

Stores metadata for uploaded files including name, type, size, and path.

3. jarvis_knowledgebase_embedding

Stores vector embeddings for semantic search with support for multiple embedding models.

For detailed schema information, see API Documentation.

📖 Examples

Check out the examples directory for complete working examples:

• PostgreSQL Example
• MySQL Example
• Oracle Example
• Using Enum
• Validation Example

🔧 Troubleshooting

Connection Issues

// Check if database is accessible
const { initialize } = require('@japfa/jarvis-sdk');

try {
  await initialize({ ... });
} catch (error) {
  if (error.message.includes('ECONNREFUSED')) {
    console.error('Database is not running or not accessible');
  } else if (error.message.includes('authentication failed')) {
    console.error('Invalid credentials');
  } else {
    console.error('Error:', error.message);
  }
}

PostgreSQL Vector Extension

For PostgreSQL, the SDK automatically enables the vector extension for embedding storage. Make sure your PostgreSQL user has permission to create extensions.

Oracle Client

For Oracle, you need to install Oracle Instant Client. See node-oracledb installation guide.

📚 Documentation

• Quick Start Guide
• API Documentation
• Contributing Guide
• Changelog

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development

# Clone the repository
git clone https://github.com/japfa/jarvis-sdk.git
cd jarvis-sdk

# Install dependencies
npm install

# Run examples
npm run example:postgres
npm run example:mysql
npm run example:oracle

📄 License

MIT © JAPFA

👥 Authors

• JAPFA Development Team

🙏 Acknowledgments

• PostgreSQL team for pgvector extension
• Node.js database driver maintainers
• Contributors and users of this SDK

📞 Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 📖 Docs: Documentation

Made with ❤️ by JAPFA