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

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

# B-esper Frontend Toolkit - Developer Guide

## Overview

The B-esper Frontend Toolkit is a professional, modular NPM package designed for seamless integration into WordPress plugins, web applications, and various platforms. It provides comprehensive bot functionality through a well-architected system.

**Main Functions:**

1. **bsp_init_b_esperbot** - Chat widget for bot interaction
2. **bsp_manage_b_esperbot** - Professional management interface for bot configuration
3. **bsp_demo_b_esperbot** - Demo interface showcasing bot capabilities

## Professional Package Architecture

### Modern Modular Structure

```
src/
├── index.js                    # Main entry point with exported functions
├── types/                      # TypeScript definitions
│   ├── index.d.ts             # Main type definitions
│   ├── config.types.ts        # Configuration interfaces
│   ├── api.types.ts           # API-related types
│   └── components.types.ts    # Component interfaces
│
├── core/                       # Core functionality (future)
│   ├── BesperKnowledge.ts     # Knowledge management core
│   ├── EventEmitter.ts        # Event handling system
│   ├── StateManager.ts        # State management
│   └── Router.ts              # Internal routing
│
├── components/                 # UI Components
│   ├── base/                  # Base component classes
│   │   ├── Component.ts       # Abstract base component
│   │   ├── Modal.ts           # Modal component
│   │   └── Button.ts          # Button component
│   │
│   ├── layout/                # Layout components (future)
│   │   ├── Sidebar.ts
│   │   ├── Header.ts
│   │   ├── Content.ts
│   │   └── Breadcrumb.ts
│   │
│   ├── navigation/            # Navigation components (future)
│   │   ├── NavItem.ts
│   │   ├── NavGroup.ts
│   │   └── StorageIndicator.ts
│   │
│   ├── documents/             # Document management (future)
│   │   ├── DocumentList.ts
│   │   ├── DocumentItem.ts
│   │   ├── DocumentUpload.ts
│   │   └── TextEditor.ts
│   │
│   ├── websites/              # Website management (future)
│   │   ├── WebsiteList.ts
│   │   ├── WebsiteItem.ts
│   │   ├── WebsiteDetails.ts
│   │   └── WebsiteStats.ts
│   │
│   ├── charts/                # Analytics charts (future)
│   │   ├── Sparkline.ts
│   │   └── UsageChart.ts
│   │
│   ├── chat-widget.js         # Current chat widget
│   ├── b-esper-bot-management.js # Professional bot management
│   └── demo-widget.js         # Demo interface
│
├── services/                  # API and data services
│   └── api.js                 # API endpoints and utilities
│
├── utils/                     # Professional utilities
│   ├── constants.ts           # Application constants
│   ├── dom.ts                 # DOM manipulation utilities
│   ├── validators.ts          # Validation functions
│   ├── formatters.ts          # Data formatting utilities
│   └── helpers.ts             # General helper functions
│
└── styles/                    # SCSS architecture
    ├── index.scss             # Main entry point
    ├── variables.scss         # SCSS variables
    ├── mixins.scss            # SCSS mixins
    ├── base/
    │   ├── reset.scss         # CSS reset
    │   └── typography.scss    # Typography styles
    ├── components/            # Component styles (future)
    │   ├── widget.scss
    │   ├── modal.scss
    │   ├── button.scss
    │   ├── form.scss
    │   ├── card.scss
    │   ├── sidebar.scss
    │   ├── header.scss
    │   ├── navigation.scss
    │   └── sparkline.scss
    └── themes/                # Theme variations (future)
        ├── default.scss
        └── dark.scss
```

### Professional Development Features

#### TypeScript Support

- Complete type definitions for all components and APIs
- Interfaces for configuration, credentials, and data structures
- Type-safe development experience

#### Modern Build System

- Rollup.js for optimized bundling
- Environment-specific builds (dev, integration, production)
- ES modules and CommonJS support
- TypeScript compilation ready

#### Professional Styling Architecture

- SCSS-based styling system
- Modular component styles
- Theme support with CSS custom properties
- Responsive design utilities
- Professional design tokens

#### Component Architecture

- Abstract base classes for consistent development
- Proper lifecycle management
- Event handling system
- State management
- Modular and reusable components

## API Infrastructure

### APIM Instance Locations

- **Development**: `https://b-esper-apim-dev.azure-api.net/api/`
- **Integration**: `https://b-esper-apim.azure-api.net/int/api/`
- **Production**: `https://b-esper-apim.azure-api.net/api/`

### Backend References

- **Main Function App**: `function_app.py` (root directory)
- **API Products**: `api_products/` directory containing:
  - `session_auth/` - Session authentication and management
  - `cosmos_db/` - Database operations
  - `foundry/` - AI/ML operations
  - `knowledge_management/` - Document and knowledge base management

## Usage Examples

### 1. Chat Widget (Enhanced)

```javascript
// Initialize with professional options
const widget = await bsp_init_b_esperbot('your-bot-id', {
  environment: 'prod',
  position: 'bottom-right',
  theme: 'auto', // light, dark, or auto
});

// Access widget API
widget.show();
widget.hide();
widget.destroy();
```

### 2. B-esper Bot Management (Professional Interface)

```javascript
// Initialize professional management interface
const management = await bsp_manage_b_esperbot(
  {
    botId: 'your-bot-id',
    managementId: 'your-management-id',
    managementSecret: 'your-management-secret',
  },
  {
    environment: 'prod',
    theme: 'light',
  }
);

// Professional API access
management.switchTab('knowledge');
management.loadAnalytics();
management.exportConfiguration();
management.destroy();
```

### 3. Demo Interface (Enhanced)

```javascript
// Initialize with enhanced demo capabilities
const demo = await bsp_demo_b_esperbot('your-bot-id', {
  environment: 'prod',
  showKnowledgePanel: true,
  autoHideOnMobile: true,
});
```

## WordPress Plugin Integration

### Ready for Professional Integration

```javascript
// WordPress plugin example
(function ($) {
  'use strict';

  $(document).ready(function () {
    // Initialize B-esper management in WordPress admin
    if (window.besperConfig) {
      bsp_manage_b_esperbot(window.besperConfig.credentials, {
        environment: window.besperConfig.environment,
        container: '#besper-admin-container',
      });
    }

    // Initialize chat widget on frontend
    if (window.besperWidgetConfig) {
      bsp_init_b_esperbot(window.besperWidgetConfig.botId, {
        environment: window.besperWidgetConfig.environment,
        position: window.besperWidgetConfig.position,
      });
    }
  });
})(jQuery);
```

## Professional Development

### Build Commands

```bash
npm run clean              # Clean dist directory
npm run build:dev          # Development build
npm run build:int          # Integration build
npm run build:prod         # Production build
npm run build              # Build all environments
```

### Code Quality

```bash
npm run lint               # ESLint checking
npm run format             # Prettier formatting
npm run validate           # Complete validation
npm test                   # Jest testing
```

### Professional Standards

- **Code Style**: ESLint + Prettier configuration
- **Type Safety**: TypeScript definitions for all APIs
- **Testing**: Jest test framework ready
- **Documentation**: Comprehensive JSDoc comments
- **Accessibility**: WCAG 2.1 AA compliance ready

## Configuration Schema

### Professional Bot Configuration

```typescript
interface BotConfiguration {
  name: string;
  bot_title: string;
  styling: {
    primary_color: string;
    secondary_color: string;
    user_message_color: string;
    bot_message_color: string;
    font_family: string;
  };
  welcome_messages: { [language: string]: string };
  data_policy_url: string;
  ai_settings: {
    system_instructions: string;
  };
  features: {
    analytics: boolean;
    file_upload: boolean;
    web_search: boolean;
    multi_language: boolean;
  };
}
```

## Framework Integration Examples

### React Integration

```typescript
import { useEffect, useState } from 'react';
import { bsp_manage_b_esperbot, BesperBotManagement } from 'besper-frontend-toolkit';

const BotManagement: React.FC = () => {
  const [management, setManagement] = useState<BesperBotManagement | null>(null);

  useEffect(() => {
    const initManagement = async () => {
      const mgmt = await bsp_manage_b_esperbot(credentials, options);
      setManagement(mgmt);
    };

    initManagement();

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

  return <div id="besper-management-container" />;
};
```

### Vue Integration

```vue
<template>
  <div id="besper-management-container" />
</template>

<script>
import { bsp_manage_b_esperbot } from 'besper-frontend-toolkit';

export default {
  name: 'BotManagement',
  async mounted() {
    this.management = await bsp_manage_b_esperbot(
      this.credentials,
      this.options
    );
  },
  beforeUnmount() {
    this.management?.destroy();
  },
};
</script>
```

### Angular Integration

```typescript
import { Component, OnInit, OnDestroy } from '@angular/core';
import {
  bsp_manage_b_esperbot,
  BesperBotManagement,
} from 'besper-frontend-toolkit';

@Component({
  selector: 'app-bot-management',
  template: '<div id="besper-management-container"></div>',
})
export class BotManagementComponent implements OnInit, OnDestroy {
  private management: BesperBotManagement | null = null;

  async ngOnInit() {
    this.management = await bsp_manage_b_esperbot(credentials, options);
  }

  ngOnDestroy() {
    this.management?.destroy();
  }
}
```

## Future Enhancements Ready

The professional architecture supports:

- **Advanced Analytics**: Timeline graphs with usage metadata
- **Multi-language Support**: Internationalization system
- **Theme System**: Custom themes and branding
- **Plugin Architecture**: Extensible plugin system
- **Advanced Knowledge Management**: File analysis and insights
- **Real-time Collaboration**: Multi-user management
- **API Documentation**: Auto-generated API docs
- **E2E Testing**: Playwright test automation

## Migration Guide

### From Previous Version

1. **No Breaking Changes**: Existing `bsp_init_b_esperbot` remains unchanged
2. **Enhanced Types**: New TypeScript definitions available
3. **Professional Management**: Use new `bsp_manage_b_esperbot` function
4. **Improved Styling**: SCSS architecture for customization

## Support & Documentation

- **API Reference**: Complete TypeScript definitions
- **Component Documentation**: JSDoc comments throughout
- **Integration Examples**: React, Vue, Angular examples
- **WordPress Integration**: Ready-to-use plugin templates
- **Professional Support**: Enterprise-ready architecture