# KriyaOS Chat Widget

Production-ready embeddable chat widget for websites and web apps.

Package: @kanhaiyamark/kriyaos-chat-widget

## Features

- Lightweight ESM and CJS bundles
- Session persistence with localStorage
- Quick action chips for faster conversations
- Typing animation and streaming response support
- KriyaOS API support via workspaceId and agentId
- Works with plain HTML, React, and Next.js client components

## Installation

Install from npm:

```bash
npm install @kanhaiyamark/kriyaos-chat-widget
```

## Quick Start

To use the default chatbot launcher icon, place your GIF at `public/assets/kriyaos-chat-wadget.gif`. You can override it any time with `theme.logoUrl`.

### Plain HTML / Vanilla JS

```html
<script type="module">
  import ChatWidget from "@kanhaiyamark/kriyaos-chat-widget";

  ChatWidget.init({
    workspaceId: "your-workspace-id",
    agentId: "your-agent-id",
    title: "Support Assistant",
    theme: {
      primaryColor: "#0f766e",
      logoUrl: "https://app.kriyaos.com/favicon.ico",
      welcomeMessage: "Hi! Ask me anything.",
      fontSizeMode: "small"
    }
  });
</script>
```

### React

```tsx
import { useEffect } from "react";
import ChatWidget from "@kanhaiyamark/kriyaos-chat-widget";

export default function App() {
  useEffect(() => {
    ChatWidget.init({
      workspaceId: "your-workspace-id",
      agentId: "your-agent-id"
    });
  }, []);

  return null;
}
```

### Next.js (App Router)

Use this only in a client component because the widget uses window, document, and localStorage.

```tsx
"use client";

import { useEffect } from "react";
import ChatWidget from "@kanhaiyamark/kriyaos-chat-widget";

export default function ChatWidgetLoader() {
  useEffect(() => {
    ChatWidget.init({
      workspaceId: "your-workspace-id",
      agentId: "your-agent-id"
    });
  }, []);

  return null;
}
```

## API

Call:

```ts
ChatWidget.init(config)
```

### Config Reference

| Field | Type | Required | Description |
|---|---|---|---|
| workspaceId | string | Yes | KriyaOS workspace id |
| agentId | string | Yes | KriyaOS agent id |
| apiBaseUrl | string | No | Base URL for KriyaOS API |
| headers | Record<string, string> | No | Additional request headers |
| storageKey | string | No | Namespace seed for localStorage keys |
| title | string | No | Header title in widget |
| quickActions | string[] | No | Starter quick-action chips |
| theme.primaryColor | string | No | Primary color (hex or gradient) |
| theme.logoUrl | string | No | Logo URL shown in widget header |
| theme.welcomeMessage | string | No | First assistant message |
| theme.fontSizeMode | "small" \| "medium" \| "large" | No | UI text scaling |

You can get `workspaceId` and `agentId` from your KriyaOS workspace dashboard.

## Request and Response Formats

### KriyaOS format

Request body:

```json
{
  "messages": [
    {
      "role": "user",
      "parts": [{ "type": "text", "text": "Hello" }]
    }
  ]
}
```

Expected response shape:

```json
{
  "message": {
    "parts": [{ "type": "text", "text": "Hi, how can I help?" }]
  },
  "session": { "id": "session-id" }
}
```

Streaming (SSE) is supported using text/event-stream.

## Production Notes

- Initialize the widget once per page load
- Always run in browser context only
- Configure CORS allow-list for your frontend origin
- Use HTTPS endpoints in production
- If your backend requires auth, pass headers in config

## Troubleshooting

- CORS error in widget: allow your website origin on API side
- Nothing appears after install in Next.js: confirm component has "use client"
- Duplicate widgets: ensure init is called only once

## License

MIT

## Author

KriyaOS

Website: https://www.kriyaos.com/
