npm package: @pobuca/pobuca-ai-web-sdk
Description: JavaScript SDK for embedding Pobuca AI chat on any website
Author: Pobuca
Latest version: 1.0.1

# Pobuca AI Web SDK

JavaScript SDK for embedding Pobuca AI chat widget on any website. Works with vanilla JavaScript, TypeScript, React, Vue, Angular, and any other web framework.

## Installation

### NPM

```bash
npm install @pobuca/pobuca-ai-web-sdk
```

### CDN (Coming Soon)

```html
<script src="https://cdn.pobuca.com/ai-web-sdk/latest/pobuca-ai-web-sdk.js"></script>
```

## Usage

### Vanilla JavaScript

```html
<!DOCTYPE html>
<html>
<head>
  <title>My Website</title>
</head>
<body>
  <h1>Welcome to my website</h1>
  
  <!-- Include the SDK -->
  <script src="node_modules/@pobuca/pobuca-ai-web-sdk/dist/pobuca-ai-web-sdk.js"></script>
  
  <!-- Initialize and show the chat badge -->
  <script>
    const client = new PobucaAIClient({
      apiKey: 'your-api-key-here'
    });
    
    client.showBadge();
  </script>
</body>
</html>
```

### TypeScript / ES Modules

```typescript
import { PobucaAIClient } from '@pobuca/pobuca-ai-web-sdk';

const client = new PobucaAIClient({
  apiKey: 'your-api-key-here',
  serviceUrl: 'https://ai.pobuca.com' // Optional, defaults to https://ai.pobuca.com
});

client.showBadge();
```

### React

```tsx
import { useEffect, useRef } from 'react';
import { PobucaAIClient } from '@pobuca/pobuca-ai-web-sdk';

function App() {
  const clientRef = useRef<PobucaAIClient | null>(null);
  
  useEffect(() => {
    clientRef.current = new PobucaAIClient({
      apiKey: 'your-api-key-here'
    });
    
    clientRef.current.showBadge();
    
    // Cleanup on unmount
    return () => {
      if (clientRef.current) {
        clientRef.current.destroy();
      }
    };
  }, []);
  
  return (
    <div>
      <h1>My React App</h1>
    </div>
  );
}

export default App;
```

**💡 See full React demo**: Check the `demo-react/` folder for a complete working example with TypeScript!

### Vue 3

```vue
<template>
  <div>
    <h1>My Vue App</h1>
  </div>
</template>

<script setup>
import { onMounted, onUnmounted } from 'vue';
import { PobucaAIClient } from '@pobuca/pobuca-ai-web-sdk';

let client;

onMounted(() => {
  client = new PobucaAIClient({
    apiKey: 'your-api-key-here'
  });
  
  client.showBadge();
});

onUnmounted(() => {
  if (client) {
    client.destroy();
  }
});
</script>
```

### Angular

```typescript
import { Component, OnInit, OnDestroy } from '@angular/core';
import { PobucaAIClient } from '@pobuca/pobuca-ai-web-sdk';

@Component({
  selector: 'app-root',
  template: '<h1>My Angular App</h1>'
})
export class AppComponent implements OnInit, OnDestroy {
  private client?: PobucaAIClient;
  
  ngOnInit() {
    this.client = new PobucaAIClient({
      apiKey: 'your-api-key-here'
    });
    
    this.client.showBadge();
  }
  
  ngOnDestroy() {
    if (this.client) {
      this.client.destroy();
    }
  }
}
```

## API Reference

### `PobucaAIClient`

#### Constructor Options

```typescript
interface PobucaAIClientOptions {
  apiKey: string;        // Required: Your Pobuca AI API key
  serviceUrl?: string;   // Optional: Custom service URL (defaults to 'https://ai.pobuca.com')
}
```

#### Methods

##### `showBadge()`

Displays the chat badge in the bottom-right corner of the page. If the badge is already shown, this method does nothing.

```typescript
client.showBadge();
```

##### `hideBadge()`

Hides the chat badge without removing it from the DOM. The badge can be shown again by calling `showBadge()`.

```typescript
client.hideBadge();
```

##### `destroy()`

Completely removes the chat badge from the DOM and cleans up all resources. After calling this method, you'll need to create a new instance to show the badge again.

```typescript
client.destroy();
```

## Demos

### Interactive Demos Included

1. **Vanilla JavaScript Demo**: `demo.html` - Full-featured interactive demo
2. **React + TypeScript Demo**: `demo-react/` - Complete React application with Vite

To run the React demo:
```bash
# From the web-sdk folder
npm run demo-react

# Or manually
cd demo-react
npm install
npm run dev
```

See `demo-react/LAUNCH.md` for detailed instructions.

## Customization

The chat badge appears as a floating button in the bottom-right corner of your website. When clicked, it opens a chat window with your Pobuca AI agent.

### Positioning

The badge is positioned at:
- Desktop: 20px from bottom and right
- Mobile: 10px from bottom and right
- Small mobile: Full screen when opened

### Styling

The widget uses Shadow DOM to prevent style conflicts with your website. The badge has a purple gradient background and smooth animations.

## Browser Support

- Chrome/Edge (latest 2 versions)
- Firefox (latest 2 versions)
- Safari (latest 2 versions)
- Mobile browsers (iOS Safari, Chrome Mobile)

## Development

### Building from Source

```bash
# Install dependencies
npm install

# Build the SDK
npm run build

# Start development server
npm start
```

### Project Structure

```
web-sdk/
├── src/
│   ├── client.ts              # Main client class
│   ├── badge.component.ts     # Angular badge component
│   ├── badge.component.html   # Badge template
│   ├── badge.component.scss   # Badge styles
│   ├── main.ts                # Angular Elements bootstrap
│   └── index.ts               # Public API exports
├── demo-react/                # React + TypeScript demo
├── dist/                      # Built files
│   ├── pobuca-ai-web-sdk.js  # Bundled JavaScript
│   └── index.d.ts            # TypeScript definitions
└── package.json
```

## Features

- ✅ **Framework Agnostic** - Works with any JavaScript framework or vanilla JS
- ✅ **TypeScript Support** - Full type definitions included
- ✅ **Lightweight** - Only ~51KB gzipped
- ✅ **Responsive** - Mobile-first design with full-screen mobile support
- ✅ **Style Isolation** - Uses Shadow DOM to prevent CSS conflicts
- ✅ **Easy Integration** - Just 3 lines of code to get started
- ✅ **Modern UI** - Beautiful gradient design with smooth animations

## Configuration Options

The SDK accepts the following options:

| Option | Type | Required | Default | Description |
|--------|------|----------|---------|-------------|
| `apiKey` | `string` | Yes | - | Your Pobuca AI API key |
| `serviceUrl` | `string` | No | `'https://ai.pobuca.com'` | Custom service URL for self-hosted instances |

## Advanced Usage

### Controlling Badge Visibility

```typescript
const client = new PobucaAIClient({ apiKey: 'your-api-key' });

// Show badge when user clicks a button
document.getElementById('openChat').addEventListener('click', () => {
  client.showBadge();
});

// Hide badge programmatically
document.getElementById('closeChat').addEventListener('click', () => {
  client.hideBadge();
});

// Destroy badge completely (cleanup)
document.getElementById('removeChat').addEventListener('click', () => {
  client.destroy();
});
```

### Conditional Loading

```typescript
// Only show chat for logged-in users
if (user.isLoggedIn) {
  const client = new PobucaAIClient({
    apiKey: user.apiKey
  });
  client.showBadge();
}
```

### Self-Hosted Instance

```typescript
const client = new PobucaAIClient({
  apiKey: 'your-api-key',
  serviceUrl: 'https://your-domain.com'
});
client.showBadge();
```

## Troubleshooting

### Badge doesn't appear

1. Check browser console for errors
2. Verify your API key is correct
3. Ensure the script is loaded: `console.log(window.PobucaAIClient)`
4. Check if there are any CSP (Content Security Policy) restrictions

### Iframe content doesn't load

1. Verify the `serviceUrl` is accessible
2. Check browser console for CORS errors
3. Ensure your API key has proper permissions

### TypeScript errors

Make sure the type definitions are properly installed:
```bash
npm install --save-dev @types/node
```

## File Size

- **Uncompressed**: 168 KB
- **Gzipped**: 51 KB
- **Brotli**: ~45 KB (estimated)

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history and updates.

## License

MIT

## Support

For support, please contact support@pobuca.com or visit https://pobuca.com

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Roadmap

- [ ] Additional customization options (colors, position, size)
- [ ] Event system for tracking chat interactions
- [ ] Offline support
- [ ] Pre-chat forms
- [ ] File upload support
- [ ] Multi-language support