npm package: @japfa/jarvis-sdk
Description: Official Node.js SDK for Genesis AI JAPFA
Author: JAPFA
Latest version: 1.0.3

# @japfa/jarvis-sdk

[![npm version](https://img.shields.io/npm/v/@japfa/jarvis-sdk.svg)](https://www.npmjs.com/package/@japfa/jarvis-sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)

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

```bash
npm install @japfa/jarvis-sdk
```

## 📚 Table of Contents

- [Quick Start](#-quick-start)
- [Usage](#-usage)
- [Configuration](#-configuration)
- [API Reference](#-api-reference)
- [Examples](#-examples)
- [Error Handling](#-error-handling)
- [Tables Created](#-tables-created)
- [Contributing](#-contributing)
- [License](#-license)

## 🚀 Quick Start

### Using Fluent API (Recommended)

```javascript
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)

```javascript
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](./docs/QUICKSTART.md).

## 💻 Usage

### Initialize Database

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

#### Using DatabaseTypes Enum (Recommended)

```javascript
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)

```javascript
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

```javascript
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

```javascript
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

```javascript
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:

```javascript
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](./docs/API.md#migration-system).

## 📖 Examples

Check out the [examples](./examples/) directory for complete working examples:

- [PostgreSQL Example](./examples/initialize-postgres.js)
- [MySQL Example](./examples/initialize-mysql.js)
- [Oracle Example](./examples/initialize-oracle.js)
- [Using Enum](./examples/initialize-with-enum.js)
- [Validation Example](./examples/validate-database-type.js)

## 🔧 Troubleshooting

### Connection Issues

```javascript
// 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](https://oracle.github.io/node-oracledb/INSTALL.html).

## 📚 Documentation

- [Quick Start Guide](./docs/QUICKSTART.md)
- [API Documentation](./docs/API.md)
- [Contributing Guide](./CONTRIBUTING.md)
- [Changelog](./CHANGELOG.md)

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details.

### Development

```bash
# 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: support@japfa.com
- 🐛 Issues: [GitHub Issues](https://github.com/japfa/jarvis-sdk/issues)
- 📖 Docs: [Documentation](./docs/)

---

Made with ❤️ by JAPFA