neochat-widget/README.md

Universal JavaScript SDK and Widget for NeoChat AI Assistant

# NeoChat Widget

A lightweight, customizable chat widget for integrating NeoChat's AI assistant into any website or web application.

## Features

- **Universal Integration**: Works with any website or web app
- **Multiple Frameworks**: React, Vue, Angular, or vanilla JS
- **Fully Customizable**: Match your brand's look and feel
- **Responsive Design**: Works on all device sizes
- **Easy Setup**: Just a few lines of code to get started

## Installation

### NPM (Recommended for React, Vue, Angular, etc.)

```bash
npm install @neochat/widget
# or
yarn add @neochat/widget
```

### CDN (For simple HTML websites)

```html
<!-- Add this to your HTML -->
<div id="neochat"></div>
<script src="https://cdn.jsdelivr.net/npm/@neochat/widget@latest/dist/neochat.umd.min.js"></script>
```

## Usage

### Vanilla JavaScript / HTML

```html
<!-- Add this to your HTML -->
<div id="neochat"></div>

<!-- Include the script -->
<script src="https://cdn.jsdelivr.net/npm/@neochat/widget@latest/dist/neochat.umd.min.js"></script>

<!-- Initialize the widget -->
<script>
  NeoChat.init({
    apiKey: 'your-api-key',
    businessId: 'your-business-id',
    containerId: 'neochat',
    position: 'bottom-right', // or 'bottom-left', 'top-right', 'top-left'
    autoOpen: false,
    // Optional: Customize the appearance
    theme: {
      primaryColor: '#4f46e5',
      headerBackground: '#4f46e5',
      headerTextColor: '#ffffff',
      // ... more theme options
    }
  });
</script>
```

### Using data attributes (no JavaScript required)

```html
<div 
  id="neochat" 
  data-neochat-widget
  data-api-key="your-api-key"
  data-business-id="your-business-id"
  data-position="bottom-right"
  data-auto-open="false"
></div>

<!-- Include the script -->
<script src="https://cdn.jsdelivr.net/npm/@neochat/widget@latest/dist/neochat.umd.min.js"></script>
```

### React / Vue / Angular

```jsx
import { useEffect } from 'react';
import { NeoChat } from '@neochat/widget';

function App() {
  useEffect(() => {
    const chat = new NeoChat({
      apiKey: 'your-api-key',
      businessId: 'your-business-id',
      // ... other options
    });

    // Optional: Listen to events
    chat.on('message', (message) => {
      console.log('New message:', message);
    });

    // Clean up on unmount
    return () => {
      chat.destroy();
    };
  }, []);

  return (
    <div className="app">
      <h1>My App with NeoChat</h1>
      <div id="neochat"></div>
    </div>
  );
}
```

## Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `apiKey` | string | **Required** | Your NeoChat API key |
| `businessId` | string | **Required** | Your business/workspace ID |
| `containerId` | string | `'neochat'` | ID of the container element |
| `position` | string | `'bottom-right'` | Position of the chat widget (`'bottom-right'`, `'bottom-left'`, `'top-right'`, `'top-left'`) |
| `autoOpen` | boolean | `false` | Whether the chat should open automatically |
| `theme` | object | `{}` | Customize colors and styling (see below) |
| `user` | object | `{}` | User information to pre-fill in the chat |

### Theme Options

Customize the appearance of the widget:

```javascript
{
  primaryColor: '#4f46e5',
  headerBackground: '#4f46e5',
  headerTextColor: '#ffffff',
  messageBackground: '#ffffff',
  messageTextColor: '#1f2937',
  userMessageBackground: '#4f46e5',
  userMessageTextColor: '#ffffff',
  // ... more theme options
}
```

## Methods

After initializing the widget, you can control it programmatically:

```javascript
const chat = NeoChat.init({ /* config */ });

// Open the chat
chat.open();

// Close the chat
chat.close();

// Toggle chat visibility
chat.toggle();

// Send a message
chat.sendMessage('Hello, world!');

// Update configuration
chat.updateConfig({
  theme: { primaryColor: '#ff0000' }
});

// Destroy the widget
chat.destroy();
```

## Events

Listen to chat events:

```javascript
const chat = NeoChat.init({ /* config */ });

chat.on('message', (message) => {
  console.log('New message:', message);
});

chat.on('open', () => {
  console.log('Chat opened');
});

chat.on('close', () => {
  console.log('Chat closed');
});

chat.on('error', (error) => {
  console.error('Chat error:', error);
});

// Remove event listener
chat.off('message', messageHandler);
```

## Platform-Specific Guides

### WordPress

1. Install the NeoChat WordPress plugin
2. Go to Settings > NeoChat
3. Enter your API Key and Business ID
4. The chat widget will be automatically added to your site

### Shopify

1. In your Shopify admin, go to Online Store > Themes
2. Click "Actions" > "Edit code"
3. Add this to your `theme.liquid` just before the closing `</body>` tag:

```liquid
<div id="neochat"></div>
<script>
  window.NeoChatConfig = {
    apiKey: '{{ settings.neochat_api_key }}',
    businessId: '{{ settings.neochat_business_id }}'
  };
</script>
<script src="https://cdn.jsdelivr.net/npm/@neochat/widget@latest/dist/neochat.umd.min.js"></script>
```

4. Add theme settings in your `settings_schema.json`:

```json
{
  "name": "NeoChat",
  "settings": [
    {
      "type": "header",
      "content": "NeoChat Settings"
    },
    {
      "type": "text",
      "id": "neochat_api_key",
      "label": "API Key"
    },
    {
      "type": "text",
      "id": "neochat_business_id",
      "label": "Business ID"
    }
  ]
}
```

### Wix / Squarespace

1. Add a new "Embed" or "HTML" element to your page
2. Paste the following code:

```html
<div id="neochat" 
  data-neochat-widget
  data-api-key="YOUR_API_KEY"
  data-business-id="YOUR_BUSINESS_ID"
  data-position="bottom-right"
  data-auto-open="false">
</div>
<script src="https://cdn.jsdelivr.net/npm/@neochat/widget@latest/dist/neochat.umd.min.js"></script>
```

## Development

1. Clone the repository
2. Install dependencies: `npm install`
3. Start development server: `npm run dev`
4. Build for production: `npm run build`

## License

MIT