npm package: @norialabs/aria-chat-sdk
Description: Embeddable AI chat widget SDK by Noria Labs
Author: Noria Labs
Latest version: 0.1.0

# Aria Chat SDK

A fully customizable, embeddable AI chat widget by Noria Labs. Drop it into any website with just a few lines of code.

## Features

- 🎨 **Fully Customizable** - Colors, fonts, positions, texts, and behaviors
- 💬 **AI-Powered** - Connects to Aria AI for intelligent conversations
- 📱 **Responsive** - Works on desktop, tablet, and mobile
- 🌙 **Dark Mode** - Automatic or forced dark mode support
- 💾 **Persistent Sessions** - Conversations survive page refreshes
- ♿ **Accessible** - WCAG compliant with keyboard navigation
- 📊 **Analytics Ready** - Built-in Google Analytics support
- 🔌 **Framework Agnostic** - Works with any website or framework

## Installation

### Build from Source

```bash
# Navigate to the SDK directory
cd packages/aria-chat-sdk

# Install dependencies
pnpm install

# Build the SDK
pnpm build
```

This generates three files in the `dist/` folder:

- `aria-chat.iife.js` - For direct script tags
- `aria-chat.umd.js` - For AMD/CommonJS loaders
- `aria-chat.esm.js` - For ES module bundlers

### Self-Host (Script Tag)

After building, host the files on your server or CDN:

```html
<!-- Self-hosted -->
<script src="/assets/aria-chat.iife.js"></script>

<!-- Initialize the widget -->
<script>
  AriaChat.init({
    api: {
      baseUrl: 'https://your-aria-api.com',
      tenantId: 'your-tenant-id',
    },
  });
</script>
```

### NPM (After Publishing)

Once published to npm:

```bash
npm install @norialabs/aria-chat-sdk
```

Then use via CDN:

```html
<!-- unpkg -->
<script src="https://unpkg.com/@norialabs/aria-chat-sdk/dist/aria-chat.iife.js"></script>

<!-- jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/@norialabs/aria-chat-sdk/dist/aria-chat.iife.js"></script>
```

Or import in your bundler:

```javascript
import AriaChat from '@norialabs/aria-chat-sdk';

AriaChat.init({
  api: {
    baseUrl: 'https://api.aria.norialabs.com',
    tenantId: 'your-tenant-id',
  },
});
```

## Configuration

The SDK accepts a comprehensive configuration object:

```javascript
AriaChat.init({
  // Required: API configuration
  api: {
    baseUrl: 'https://api.aria.norialabs.com',
    tenantId: 'your-tenant-id',
    channel: 'webchat', // Optional, default: 'webchat'
    timeout: 15000, // Optional, default: 15000ms
  },

  // Theme customization
  theme: {
    primaryColorFrom: '#2563eb', // Gradient start
    primaryColorTo: '#0891b2', // Gradient end
    fontFamily: 'system-ui, sans-serif',
    borderRadius: '16px',
    widgetBg: '#ffffff',
    botMessageBg: '#f3f4f6',
    botMessageText: '#1f2937',
  },

  // Branding options
  branding: {
    agentName: 'Aria AI Agent',
    agentAvatarUrl: '/path/to/avatar.png',
    companyName: 'Your Company',
    greetingMessage: 'Hello! How can I help you today?',
    welcomeTitle: 'Welcome to Support',
    welcomeSubtitle: 'Enter your email to start chatting.',
    poweredByText: 'Powered by Noria Labs',
    poweredByUrl: 'https://norialabs.com',
  },

  // Position settings
  position: {
    horizontal: 'right', // 'left' | 'right'
    vertical: 'bottom', // 'top' | 'bottom'
    offset: 24, // Pixels from edge
    zIndex: 9999,
  },

  // Behavior settings
  behavior: {
    autoOpenDelay: 0, // Auto-open after ms (0 = disabled)
    showHint: true, // Show hint bubble
    hintDelay: 1200, // Hint appears after ms
    hintMessage: 'Need help? Click to chat!',
    allowExpand: true, // Allow fullscreen mode
    persistConversation: true,
    maxMessageLength: 2000,
    enableSound: false,
    showClearButton: true,
    requireEmail: true,
  },

  // Event callbacks
  callbacks: {
    onOpen: () => console.log('Chat opened'),
    onClose: () => console.log('Chat closed'),
    onMessageSent: (msg) => console.log('Sent:', msg),
    onMessageReceived: (msg) => console.log('Received:', msg),
    onSessionStart: (data) => console.log('Session started:', data),
    onSessionEnd: () => console.log('Session ended'),
    onError: (err) => console.error('Error:', err),
    onReady: () => console.log('Widget ready'),
  },

  // Analytics
  analytics: {
    enabled: true,
    googleAnalyticsId: 'G-XXXXXXXXXX',
    trackEvent: (name, data) => {
      // Custom analytics handler
    },
  },

  // Text customization (i18n)
  texts: {
    inputPlaceholder: 'Type a message...',
    sendButtonLabel: 'Send',
    clearButtonText: 'Clear Conversation',
    emailPlaceholder: 'your@email.com',
    startChatButton: 'Start Chat',
    loadingHistoryText: 'Loading...',
    connectionErrorText: 'Connection failed. Try again.',
    sessionExpiredText: 'Session expired. Please reconnect.',
    onlineStatusText: 'Online',
    offlineStatusText: 'Offline',
  },

  // Container (optional - defaults to body)
  container: '#chat-container', // or HTMLElement

  // Debug mode
  debug: false,
});
```

## API Methods

```javascript
// Get the widget instance
const chat = AriaChat.getInstance();

// Open/close the widget
AriaChat.open();
AriaChat.close();
AriaChat.toggle();

// Send a message programmatically
await chat.sendMessage('Hello!');

// Clear the conversation
chat.clearConversation();

// Get all messages
const messages = chat.getMessages();

// Check if open
const isOpen = chat.isOpen();

// Get session info
const session = chat.getSession();
// { customerId: '...', email: '...', conversationId: '...' }

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

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

## Custom Styling

The widget uses CSS custom properties that can be overridden:

```css
:root {
  --aria-primary-from: #2563eb;
  --aria-primary-to: #0891b2;
  --aria-widget-bg: #ffffff;
  --aria-border-color: #e5e7eb;
  --aria-bot-msg-bg: #f3f4f6;
  --aria-bot-msg-text: #1f2937;
  --aria-font-family: system-ui, sans-serif;
  --aria-border-radius: 16px;
  --aria-z-index: 9999;
  --aria-offset: 24px;
}
```

## Examples

### Minimal Setup

```html
<!-- Self-hosted after building -->
<script src="/path/to/aria-chat.iife.js"></script>
<script>
  AriaChat.init({
    api: {
      baseUrl: 'https://your-aria-api.com',
      tenantId: 'your-tenant-id',
    },
  });
</script>
```

### Custom Branding

```javascript
AriaChat.init({
  api: {
    baseUrl: 'https://api.aria.norialabs.com',
    tenantId: 'your-tenant-id',
  },
  theme: {
    primaryColorFrom: '#7c3aed',
    primaryColorTo: '#a855f7',
  },
  branding: {
    agentName: 'SupportBot',
    companyName: 'Acme Inc',
    greetingMessage: "Hi there! I'm SupportBot. How can I assist you?",
    agentAvatarUrl: '/logo.png',
  },
});
```

### Left-positioned with Auto-open

```javascript
AriaChat.init({
  api: {
    baseUrl: 'https://api.aria.norialabs.com',
    tenantId: 'your-tenant-id',
  },
  position: {
    horizontal: 'left',
    vertical: 'bottom',
  },
  behavior: {
    autoOpenDelay: 5000, // Open after 5 seconds
    showHint: false,
  },
});
```

### With Analytics

```javascript
AriaChat.init({
  api: {
    baseUrl: 'https://api.aria.norialabs.com',
    tenantId: 'your-tenant-id',
  },
  analytics: {
    enabled: true,
    googleAnalyticsId: 'G-XXXXXXXXXX',
    trackEvent: (name, data) => {
      // Send to your analytics platform
      mixpanel.track(name, data);
    },
  },
});
```

### React Integration

```jsx
import { useEffect } from 'react';
import AriaChat from '@norialabs/aria-chat-sdk';

function App() {
  useEffect(() => {
    const chat = AriaChat.init({
      api: {
        baseUrl: process.env.REACT_APP_ARIA_API_URL,
        tenantId: process.env.REACT_APP_ARIA_TENANT_ID,
      },
      callbacks: {
        onSessionStart: (data) => {
          // Track in your analytics
        },
      },
    });

    return () => {
      AriaChat.destroy();
    };
  }, []);

  return <div>Your App</div>;
}
```

### Vue Integration

```vue
<script setup>
import { onMounted, onUnmounted } from 'vue';
import AriaChat from '@norialabs/aria-chat-sdk';

onMounted(() => {
  AriaChat.init({
    api: {
      baseUrl: import.meta.env.VITE_ARIA_API_URL,
      tenantId: import.meta.env.VITE_ARIA_TENANT_ID,
    },
  });
});

onUnmounted(() => {
  AriaChat.destroy();
});
</script>
```

## Browser Support

- Chrome 80+
- Firefox 75+
- Safari 13+
- Edge 80+

## License

MIT © Noria Labs