npm package: @irisidea/kalrav-ai
Description: Kalrav AI chatbot widget for React, Next.js, Vue, Angular, and Vanilla JavaScript/TypeScript applications
Author: Kalrav AI
Latest version: 1.0.13

# Kalrav AI

> **AI-powered chatbot widget for React, Next.js, Vue, and Angular**

Kalrav AI is a cross-framework chatbot widget that seamlessly integrates into your web applications. Install once, use everywhere.

[![npm version](https://img.shields.io/npm/v/@irisidea/kalrav-ai.svg)](https://www.npmjs.com/package/@irisidea/kalrav-ai)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

## ✨ Features

- 🚀 **Multi-Framework Support**: React, Next.js, Vue 3, Angular, and Vanilla JS
- 📦 **Tiny Bundle Size**: Optimized for performance
- 🎨 **Customizable**: Match your brand with custom colors
- 🔒 **Type-Safe**: Full TypeScript support
- 💛 **JavaScript First**: Works perfectly with plain JavaScript
- ⚡ **SSR Compatible**: Works with Next.js server-side rendering
- 🎯 **Zero Config**: Works out of the box

## 📦 Installation

```bash
npm install @irisidea/kalrav-ai
# or
yarn add @irisidea/kalrav-ai
# or
pnpm add @irisidea/kalrav-ai
```

> **Works with both JavaScript and TypeScript!** All examples below work in `.js`, `.jsx`, `.ts`, and `.tsx` files.

## 🎯 How It Works

**Only 2 required props**: `apiKey` and `agentId`

Everything else is automatically fetched from your agent's dashboard configuration:
- ✅ Agent name and logo
- ✅ Custom colors (layout, user input, bot response, icons, fonts)
- ✅ Default questions and placeholder text
- ✅ Feature toggles (file uploads, audio recording, text-to-speech, download chat)
- ✅ Language settings
- ✅ Feedback questions


## 🚀 Quick Start

### React

**TypeScript:**
```tsx
import { KalravWidget } from '@irisidea/kalrav-ai/react';

function App() {
  return (
    <div>
      <h1>My App</h1>
      <KalravWidget 
        apiKey="your-api-key"
        agentId="your-agent-id"
      />
    </div>
  );
}
```

**JavaScript:**
```jsx
import { KalravWidget } from '@irisidea/kalrav-ai/react';

function App() {
  return (
    <div>
      <h1>My App</h1>
      <KalravWidget 
        apiKey="your-api-key"
        agentId="your-agent-id"
      />
    </div>
  );
}
```

**Programmatic Control:**

```jsx
import { useKalrav } from '@irisidea/kalrav-ai/react';

function ChatButton() {
  const kalrav = useKalrav({
    apiKey: 'your-api-key',
    agentId: 'your-agent-id',
  });

  return (
    <button onClick={() => kalrav?.open()}>
      Open Chat
    </button>
  );
}
```

---

### Next.js

**App Router** (`app/layout.js` or `app/layout.tsx`):

```javascript
import { KalravWidget } from '@irisidea/kalrav-ai/nextjs';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <KalravWidget 
          apiKey="your-api-key"
          agentId="your-agent-id"
        />
      </body>
    </html>
  );
}
```

**Pages Router** (`pages/_app.js` or `pages/_app.tsx`):

```tsx
import { KalravWidget } from '@irisidea/kalrav-ai/nextjs';

function MyApp({ Component, pageProps }) {
  return (
    <>
      <Component {...pageProps} />
      <KalravWidget 
        apiKey="your-api-key"
        agentId="your-agent-id"
      />
    </>
  );
}
```

**Programmatic Control:**

```tsx
'use client';

import { useKalrav } from '@irisidea/kalrav-ai/nextjs';

function ChatButton() {
  const kalrav = useKalrav({
    apiKey: 'your-api-key',
    agentId: 'your-agent-id',
  });

  return (
    <button onClick={() => kalrav?.open()}>
      Open Chat
    </button>
  );
}
```

---

### Vue 3

```vue
<template>
  <div>
    <h1>My App</h1>
    <KalravWidget 
      api-key="your-api-key"
      agent-id="your-agent-id"
      primary-color="#4F46E5"
    />
  </div>
</template>

<script setup>
import { KalravWidget } from '@irisidea/kalrav-ai/vue';
</script>
```

**Programmatic Control:**

```vue
<template>
  <button @click="kalrav?.open()">
    Open Chat
  </button>
</template>

<script setup>
import { useKalrav } from '@irisidea/kalrav-ai/vue';

const kalrav = useKalrav({
  apiKey: 'your-api-key',
  agentId: 'your-agent-id',
});
</script>
```

---

### Angular

**Module Import** (`app.module.ts`):

```typescript
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { KalravModule } from '@irisidea/kalrav-ai/angular';
import { AppComponent } from './app.component';

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    KalravModule
  ],
  bootstrap: [AppComponent]
})
export class AppModule {}
```

**Component Usage** (`app.component.ts`):

```typescript
import { Component } from '@angular/core';

@Component({
  selector: 'app-root',
  template: `
    <h1>My App</h1>
    <kalrav-widget 
      [apiKey]="'your-api-key'"
      [agentId]="'your-agent-id'"
      [primaryColor]="'#4F46E5'">
    </kalrav-widget>
  `
})
export class AppComponent {}
```

**Programmatic Control with Service:**

```typescript
import { Component } from '@angular/core';
import { KalravService } from '@irisidea/kalrav-ai/angular';

@Component({
  selector: 'app-chat-button',
  template: '<button (click)="openChat()">Open Chat</button>'
})
export class ChatButtonComponent {
  constructor(private kalrav: KalravService) {
    // Initialize the service
    this.kalrav.initialize({
      apiKey: 'your-api-key',
      agentId: 'your-agent-id'
    });
  }

  openChat() {
    this.kalrav.open();
  }
}
```

---

### Vanilla JavaScript

**No framework? No problem!** Use it in any HTML page:

```html
<!DOCTYPE html>
<html>
<head>
  <title>My Site</title>
</head>
<body>
  <h1>Welcome</h1>
  <button id="chatBtn">Chat with us</button>

  <script type="module">
    import { createKalrav } from 'https://cdn.jsdelivr.net/npm/@irisidea/kalrav-ai@latest/dist/index.mjs';
    
    const kalrav = createKalrav({
      apiKey: 'your-api-key',
      agentId: 'your-agent-id',
    });

    document.getElementById('chatBtn').onclick = () => kalrav.open();
  </script>
</body>
</html>
```

**With npm/bundler:**
```javascript
import { createKalrav } from '@irisidea/kalrav-ai';

const kalrav = createKalrav({
  apiKey: 'your-api-key',
  agentId: 'your-agent-id',
  primaryColor: '#4F46E5',
});

kalrav.open();
```

📖 **[See full Vanilla JS guide](examples/vanilla-js-example.md)** for CDN, module, and script tag examples.

---

## ⚙️ Configuration Options

| Option | Type | Required | Default | Description |
|--------|------|----------|---------|-------------|
| `apiKey` | `string` | ✅ Yes | - | Your Kalrav API key |
| `agentId` | `string` | ✅ Yes | - | Your agent/bot ID |
| `primaryColor` | `string` | No | `#4F46E5` | Primary color for the widget |
| `autoLoad` | `boolean` | No | `true` | Auto-load widget on mount |

---

## 🎯 API Methods

All widget instances expose the following methods:

### `load(): Promise<void>`
Manually load the widget script.

```typescript
await kalrav.load();
```

### `unload(): void`
Remove the widget from the page.

```typescript
kalrav.unload();
```

### `open(): void`
Open the chat widget.

```typescript
kalrav.open();
```

### `close(): void`
Close the chat widget.

```typescript
kalrav.close();
```

### `isLoaded(): boolean`
Check if the widget is loaded.

```typescript
if (kalrav.isLoaded()) {
  console.log('Widget is ready!');
}
```

### `call(method: string, ...args: any[]): void`
Call custom widget methods.

```typescript
kalrav.call('customMethod', arg1, arg2);
```

---

## 🔧 Advanced Usage

### Vanilla JavaScript/TypeScript

You can also use the core library without any framework. Perfect for static sites, legacy apps, or projects without build tools!

**JavaScript:**
```javascript
import { createKalrav } from '@irisidea/kalrav-ai';

const kalrav = createKalrav({
  apiKey: 'your-api-key',
  agentId: 'your-agent-id',
  primaryColor: '#4F46E5',
  autoLoad: true
});

// Control the widget
kalrav.open();
kalrav.close();
```

**TypeScript:**
```typescript
import { createKalrav } from '@irisidea/kalrav-ai';
import type { KalravConfig } from '@irisidea/kalrav-ai';

const config: KalravConfig = {
  apiKey: 'your-api-key',
  agentId: 'your-agent-id',
  primaryColor: '#4F46E5',
  autoLoad: true
};

const kalrav = createKalrav(config);

// Control the widget
kalrav.open();
kalrav.close();
```

### Custom Widget URL

If you're self-hosting the widget script:

```tsx
<KalravWidget 
  apiKey="your-api-key"
  agentId="your-agent-id"
  widgetUrl="https://your-domain.com/widget.js"
/>
```

### Lazy Loading

Disable auto-load and manually control when to load:

```tsx
const kalrav = useKalrav({
  apiKey: 'your-api-key',
  agentId: 'your-agent-id',
  autoLoad: false
});

// Load later
useEffect(() => {
  kalrav?.load();
}, [someCondition]);
```

---

## 🔐 Environment Variables

For better security, store credentials in environment variables:

**React / Next.js**

```bash
# .env.local
NEXT_PUBLIC_KALRAV_API_KEY=your-api-key
NEXT_PUBLIC_KALRAV_AGENT_ID=your-agent-id
```

```tsx
<KalravWidget 
  apiKey={process.env.NEXT_PUBLIC_KALRAV_API_KEY!}
  agentId={process.env.NEXT_PUBLIC_KALRAV_AGENT_ID!}
/>
```

**Vue / Vite**

```bash
# .env
VITE_KALRAV_API_KEY=your-api-key
VITE_KALRAV_AGENT_ID=your-agent-id
```

```vue
<KalravWidget 
  :api-key="import.meta.env.VITE_KALRAV_API_KEY"
  :agent-id="import.meta.env.VITE_KALRAV_AGENT_ID"
/>
```

---

## 📝 TypeScript Support

Kalrav AI is written in TypeScript and provides full type definitions out of the box.

```typescript
import type { KalravConfig, KalravWidget } from '@irisidea/kalrav-ai/react';

const config: KalravConfig = {
  apiKey: 'your-api-key',
  agentId: 'your-agent-id',
  primaryColor: '#4F46E5'
};
```

---

## 🌐 Browser Support

- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)

---

##  License

MIT © [Kalrav AI](https://kalrav.ai)

---

## 🤝 Support

- 📧 Email: support@kalrav.ai
- 🌐 Website: [kalrav.ai](https://kalrav.ai)
- 📚 Documentation: [docs.kalrav.ai](https://docs.kalrav.ai)

---

## 🎉 Credits

Made with ❤️ by the Kalrav AI team