npm package: @lakimi/widget-assistant
Description: > **@lakimi/widget-assistant** is a web components library for integrating an interactive assistant into your web applications. It provides two main usage modes (full container and floating widget), support for custom components, and client-side tools.
Latest version: 0.1.5

# @lakimi/widget-assistant

> **@lakimi/widget-assistant** is a web components library for integrating an interactive assistant into your web applications. It provides two main usage modes (full container and floating widget), support for custom components, and client-side tools.

## ✨ Key Features

- 🚀 **Two integration modes**: Full container or floating widget
- 🔌 **Custom components**: Extensible web components system
- 🛠️ **Client tools**: Registration and handling of client-side tools
- 💬 **Real-time communication**: WebSocket connection for fluid chat
- 🎤 **Voice interaction**: Native support for voice commands
- 🎨 **Customizable**: CSS variables and modifiable styles

---

## 📦 Installation

```bash
npm install @lakimi/widget-assistant
```

### Import

```javascript
// Import web components and managers
import "@lakimi/widget-assistant";

// If you need to use managers programmatically
import { ComponentManager, ClientToolsManager } from "@lakimi/widget-assistant";
```

---

## 🚀 Quick Start

### 1. 📱 Container Mode

Renders a complete assistant interface:

```html
<lakimi-assistant data-client-id="my-client-id" data-id="my-assistant">
</lakimi-assistant>
```

### 2. 💬 Widget Mode

Floating widget that opens in a modal:

```html
<lakimi-assistant-widget
  data-client-id="my-client-id"
  data-assistant="my-assistant"
>
</lakimi-assistant-widget>
```

### 3. 🧩 Custom Component

Register and use your own web components:

```javascript
// Define your web component
class MyButton extends HTMLElement {
  connectedCallback() {
    this.innerHTML = `<button onclick="alert('Hello!')">My Button</button>`;
  }
}
customElements.define("x-button", MyButton);

// Register the component
const componentManager = ComponentManager.getInstance();
componentManager.registerComponent({
  tagName: 'x-button',
  name: "my-button",
  description: "A custom button",
  properties: {<JSON Schema for properties>},
});
```

### 4. 🛠️ Client Tools

Allow the assistant to execute functions in the browser:

```javascript
const clientToolsManager = ClientToolsManager.getInstance();

clientToolsManager.registerTool(
  "navigate",
  {
    description: "Navigate to a specific route",
    parameters: {
      type: "object",
      properties: {
        path: { type: "string", description: "Destination path" },
      },
      required: ["path"],
    },
  },
  async (params) => {
    window.location.href = params.path;
    return new Promise((resolve) =>
      setTimeout(
        () => resolve({ success: true, message: "Navigation completed" }),
        100
      )
    );
  }
);
```

### 5. 🎨 Style Customization

Override CSS variables:

```css
:root {
  --lakimi-primary-color: #007bff;
  --lakimi-bg-primary: #ffffff;
  --lakimi-text-primary: #212529;
  --lakimi-border-radius: 8px;
}

/* Dark theme */
[data-theme="dark"] {
  --lakimi-bg-primary: #1a1a1a;
  --lakimi-text-primary: #ffffff;
}
```

---

## ⚙️ Configuration

### Container attributes (`lakimi-assistant`)

- **`data-id` (required)**: Unique identifier for the assistant
- **`data-auth`**: Authentication token
- **`data-api-endpoint`**: API endpoint (default: `https://api.lakimi.io`)
- **`data-language`**: Assistant language (default: `es`)

### Widget attributes (`lakimi-assistant-widget`)

- **`data-assistant` (required)**: Unique identifier for the assistant
- **`data-token`**: Authentication token
- **`data-api-endpoint`**: API endpoint (default: `https://api.lakimi.io`)
- **`data-language`**: Assistant language (default: `es`)

---

## 🔗 API Reference

### ComponentManager

- `registerComponent(metadata)`: Register a new component
- `unregisterComponent(name)`: Unregister a component
- `hasComponent(name)`: Check if a component exists

### ClientToolsManager

- `registerTool(name, definition, handler)`: Register a new tool
- `unregisterTool(name)`: Unregister a tool
- `hasTool(name)`: Check if a tool exists

---

## 📝 License

ISC © 2025 Lakimi Solutions S.L.