besper-frontend-toolkit-dev-8786/README.md

Professional B-esper Frontend Toolkit - Modular bot integration for WordPress plugins and web applications

# Besper Frontend Toolkit - Development

Development version of the Besper Frontend Toolkit with debugging features and source maps included.

## Installation

```bash
npm install besper-frontend-toolkit-dev-8786
```

## Package Information

- **Package Name**: `besper-frontend-toolkit-dev-8786`
- **Environment**: Development
- **API Endpoint**: https://apimdev8786public.azure-api.net
- **Version**: 1.1.4-0

## Quick Start

```javascript
import { init_b_esper_bot } from 'besper-frontend-toolkit-dev-8786';

// Initialize chat bot with UI-based data policy
const bot = await init_b_esper_bot('your-bot-id', {
  environment: '',
  containerId: 'my-chat-container',
  width: '100%',
  height: '600px',
});
```

## Core API Functions

### `init_b_esper_bot(botId, options)`

**Main API function** - Initialize B-esper bot with session token generation and UI-based data policy.

**Parameters:**

- `botId` (string, required) - The unique identifier for your Azure Bot
- `options` (Object, optional) - Configuration options

**Options:**

- `environment` (string) - Environment segment for the API URL (defaults to 'dev' for this package)
- `containerId` (string) - Container element ID for embedded chat
- `width` (string) - Chat container width (default: '100%')
- `height` (string) - Chat container height (default: '500px')

**Returns:** `Promise<Object>` - Bot instance with type ('widget' | 'embedded') and sessionData

**Example:**

```javascript
import { init_b_esper_bot } from 'besper-frontend-toolkit-dev-8786';

// Embedded chat implementation
const bot = await init_b_esper_bot('your-bot-id', {
  environment: '',
  containerId: 'chat-container',
  width: '100%',
  height: '600px',
});

console.log('Bot type:', bot.type); // 'widget' or 'embedded'
console.log('Session data:', bot.sessionData);
```

---

### `init_b_esper_portal(purchaseId, purchaseSecret, options)`

**Main API function** - Initialize B-esper portal with purchase authentication for administrative tasks.

**Parameters:**

- `purchaseId` (string, required) - The purchase ID for authentication
- `purchaseSecret` (string, required) - The purchase secret for authentication
- `options` (Object, optional) - Configuration options

**Returns:** `Promise<Object>` - Portal instance

**Example:**

```javascript
import { init_b_esper_portal } from 'besper-frontend-toolkit-dev-8786';

try {
  const portal = await init_b_esper_portal(
    'your-purchase-id',
    'your-purchase-secret',
    {
      environment: 'dev',
    }
  );

  console.log('Portal initialized:', portal);
  console.log('Authentication verified:', portal.authenticationVerified);
} catch (error) {
  console.error('Portal initialization failed:', error);
}
```

## Advanced Chat Class

### `BesperChat`

Advanced chat interface with full conversation management, streaming support, and GDPR compliance.

**Static Methods:**

```javascript
import { BesperChat } from 'besper-frontend-toolkit-dev-8786';

// Initialize with configuration
const config = {
  botId: 'your-bot-id',
  api_endpoint: 'https://apimdev8786public.azure-api.net',
  environment: '',
  // Additional configuration options
};

const chat = await BesperChat.init(config);
```

**Instance Methods:**

- `sendMessage(message)` - Send message to bot
- `downloadConversation(format)` - Download conversation history
- `deleteConversation()` - Delete conversation (GDPR compliance)
- `restartConversation()` - Restart conversation with new session

**Example:**

```javascript
// Complete conversation lifecycle
const chat = await BesperChat.init({
  botId: 'your-bot-id',
  api_endpoint: 'https://apimdev8786public.azure-api.net',
});

// Send messages
await chat.sendMessage('Hello, how can you help me?');

// Download conversation
await chat.downloadConversation('json'); // or 'txt'

// Restart conversation
await chat.restartConversation();

// Delete conversation (GDPR)
await chat.deleteConversation();
```

## Embedded Chat Component

### `BesperEmbeddedChat`

A complete embedded chat interface with modern UI and full feature support.

**Features:**

- Real-time messaging with WebSocket and streaming support
- Conversation download (JSON/TXT formats)
- GDPR-compliant conversation deletion
- Multi-language support with i18n
- Customizable styling via APIM
- Data policy integration
- Accessibility features

**Constructor:**

```javascript
import { BesperEmbeddedChat } from 'besper-frontend-toolkit-dev-8786';

const chat = new BesperEmbeddedChat({
  botId: 'your-bot-id',
  environment: '',
  containerId: 'chat-container',
  width: '100%',
  height: '500px',
  bot_name: 'Assistant',
  welcomeMessage: 'Hello! How can I help you today?',
  dataPolicyUrl: 'https://example.com/privacy',
});

await chat.init();
```

**Methods:**

- `init()` - Initialize the chat interface
- `sendMessage(message)` - Send a message with streaming support
- `destroy()` - Clean up and destroy the chat instance
- `downloadConversation()` - Download conversation with format selection
- `deleteConversation()` - GDPR-compliant conversation deletion

## Utility Functions

### Style Management

#### `get_standard_styles(styleType, options)`

Get standard CSS styles for widget and portal implementations from APIM.

**Parameters:**

- `styleType` (string, required) - Type of styles ('widget', 'portal', 'chat')
- `options` (Object, optional) - Configuration options
  - `environment` (string) - Environment for API endpoint (defaults to 'dev' for this package)
  - `version` (string) - Style version to retrieve (default: 'latest')

**Returns:** `Promise<Object>` - JSON object containing style configurations

**Example:**

```javascript
import { get_standard_styles } from 'besper-frontend-toolkit-dev-8786';

// Get widget styles
const widgetStyles = await get_standard_styles('widget', {
  environment: 'dev',
});

// Get chat styles
const chatStyles = await get_standard_styles('chat', { environment: 'dev' });

// Get portal styles with specific version
const portalStyles = await get_standard_styles('portal', {
  environment: 'dev',
  version: 'v2.0',
});
```

### Logging Utilities

BesperJS provides comprehensive logging for debugging and monitoring:

```javascript
import {
  enableBesperLogging,
  downloadBesperLogs,
  getBesperLogs,
  clearBesperLogs,
  getBesperLogsSummary,
  exportBesperLogsAsText,
} from 'besper-frontend-toolkit-dev-8786';

// Enable centralized logging
enableBesperLogging(true);

// Get all captured logs
const logs = getBesperLogs();

// Get error summary
const summary = getBesperLogsSummary();

// Download logs as JSON file
downloadBesperLogs('debug-logs.json');

// Export logs as formatted text
const textLogs = exportBesperLogsAsText();

// Clear all logs
clearBesperLogs();
```

## Widget Implementation

### `BesperWidget`

Advanced widget functionality with customizable UI and behavior.

```javascript
import { BesperWidget } from 'besper-frontend-toolkit-dev-8786';

const widget = new BesperWidget({
  botId: 'your-bot-id',
  environment: '',
  // Additional widget configuration
});

await widget.init();
```

## Utility Classes

### `Logger`

Centralized logging utility for debugging and monitoring.

```javascript
import { Logger } from 'besper-frontend-toolkit-dev-8786';

Logger.info('Information message');
Logger.warn('Warning message');
Logger.error('Error message');
Logger.debug('Debug message');
```

### `ApiClient`

HTTP client for API interactions with streaming support.

```javascript
import { ApiClient } from 'besper-frontend-toolkit-dev-8786';

// Stream bot responses
const stream = await ApiClient.streamBotResponse(
  sessionToken,
  message,
  options
);

// Generate session tokens
const sessionData = await ApiClient.generateSessionToken(botId, environment);

// Download conversations
const result = await ApiClient.downloadConversation(
  sessionToken,
  format,
  environment
);

// Delete conversations
const deleteResult = await ApiClient.deleteConversation(
  sessionToken,
  environment
);
```

### `Validator`

Input validation utilities for secure data handling.

```javascript
import { Validator } from 'besper-frontend-toolkit-dev-8786';

// Validate API endpoints
const isValidEndpoint = Validator.validateApiEndpoint(endpoint);

// Validate purchase credentials
const isValidPurchaseId = Validator.isValidPurchaseId(purchaseId);
const isValidSecret = Validator.isValidSecret(secret);
```

### `I18n`

Internationalization support for multi-language interfaces.

```javascript
import { I18n } from 'besper-frontend-toolkit-dev-8786';

const i18n = new I18n.I18n();

// Get localized text
const text = i18n.t('button_label');

// Get localized data policy URL
const localizedUrl = i18n.getLocalizedDataPolicyUrl(baseUrl);
```

### `EventEmitter`

Event management for custom event handling.

```javascript
import { EventEmitter } from 'besper-frontend-toolkit-dev-8786';

const emitter = new EventEmitter();
emitter.on('custom-event', data => {
  console.log('Event received:', data);
});
emitter.emit('custom-event', { message: 'Hello' });
```

## Environment-Specific Features

This is the **development** version of the package. It includes source maps for debugging and connects to the development API environment. Use this version for local development and testing.

### API Endpoints

This package is configured to use the following API endpoints:

- **Base URL**: https://apimdev8786public.azure-api.net
- **Session Management**: `https://apimdev8786public.azure-api.net/bot-operations`
- **Style Management**: `https://apimdev8786public.azure-api.net/styles`
- **WebSocket**: `wss://apimdev8786public.azure-api.net`

### Streaming Support

The Development environment supports real-time streaming responses:

```javascript
const chat = new BesperEmbeddedChat({
  botId: 'your-bot-id',
  environment: '',
  // Streaming is automatically enabled
});

await chat.init();
await chat.sendMessage('Tell me about your capabilities');
// Response will stream in real-time
```

### GDPR Compliance

Full conversation management with GDPR-compliant data deletion:

```javascript
// Download before deletion (optional)
await chat.downloadConversation('json');

// GDPR-compliant deletion
await chat.deleteConversation();
```

## Complete Integration Examples

### Embedded Chat with Full Features

```html
<!DOCTYPE html>
<html>
  <head>
    <title>Besper Bot Integration</title>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
  </head>
  <body>
    <div id="chat-container"></div>

    <script type="module">
      import { init_b_esper_bot } from 'besper-frontend-toolkit-dev-8786';

      // Initialize with full feature set
      const bot = await init_b_esper_bot('your-bot-id', 'dev', {
        containerId: 'chat-container',
        width: '100%',
        height: '600px',
        welcomeMessage: 'Hello! How can I assist you today?',
        dataPolicyUrl: 'https://example.com/privacy',
      });

      // Handle events
      document.addEventListener('embedded-chat:initialized', event => {
        console.log('Chat initialized:', event.detail);
      });

      document.addEventListener('session:deleted', event => {
        console.log('Conversation deleted:', event.detail);
      });

      console.log('Bot initialized:', bot);
    </script>
  </body>
</html>
```

### Advanced Configuration

```javascript
import {
  init_b_esper_bot,
  enableBesperLogging,
  get_standard_styles,
} from 'besper-frontend-toolkit-dev-8786';

// Enable logging for debugging
enableBesperLogging(true);

// Get custom styles
const customStyles = await get_standard_styles('chat', {
  environment: '',
  version: 'latest',
});

// Initialize with advanced configuration
const bot = await init_b_esper_bot('your-bot-id', {
  environment: '',
  containerId: 'advanced-chat',
  width: '400px',
  height: '700px',
  chatStyles: customStyles.classes,
  welcomeMessage: 'Welcome to our advanced support chat!',
  dataPolicyUrl: 'https://example.com/privacy-policy',
  // Additional custom options
  enableStreaming: true,
  enableDownloads: true,
  enableDeletion: true,
});
```

## Development and Testing

### Environment Configuration

For development and testing, use the appropriate environment:

```javascript
// Development environment
const devBot = await init_b_esper_bot('dev-bot-id', {
  environment: 'dev', // Uses development API endpoints
});

// Integration testing
const testBot = await init_b_esper_bot('test-bot-id', {
  environment: 'int', // Uses integration API endpoints
});

// Production deployment
const prodBot = await init_b_esper_bot('prod-bot-id', {
  environment: 'prod', // Uses production API endpoints
});
```

### Debugging Support

```javascript
import {
  enableBesperLogging,
  getBesperLogsSummary,
  downloadBesperLogs,
} from 'besper-frontend-toolkit-dev-8786';

// Enable detailed logging
enableBesperLogging(true);

// Your application code...

// Get debugging information
const summary = getBesperLogsSummary();
console.log('Errors found:', summary.errorCount);
console.log('Warnings found:', summary.warningCount);

// Download logs for analysis
downloadBesperLogs('application-debug.json');
```

## Browser Compatibility

- **Modern Browsers**: Chrome 88+, Firefox 85+, Safari 14+, Edge 88+
- **Features**: ES2020, WebSocket, Fetch API, CSS Grid
- **Polyfills**: Not required for supported browsers

## Performance Considerations

- **Bundle Size**: Optimized for development builds, source maps, and debugging tools
- **Streaming**: Real-time response processing
- **Caching**: Automatic style and configuration caching
- **Memory**: Efficient conversation history management

## Support

For support and documentation, please refer to the main repository at [https://github.com/wsperger/BAF](https://github.com/wsperger/BAF).

### Additional Resources

- **API Documentation**: Available in the repository docs folder
- **Integration Examples**: See the examples directory
- **Testing Suite**: Comprehensive test coverage included
- **Developer Guide**: Detailed development instructions

---

_This package was built for the Development environment and includes development builds, source maps, and debugging tools._

**Latest Features:**

- Real-time streaming responses
- GDPR-compliant conversation management
- Multi-language support (i18n)
- Comprehensive logging and debugging
- Advanced styling via APIM integration
- WebSocket and HTTP fallback support
- Accessibility features and keyboard navigation
- Mobile-responsive design