# Side Convo Plugin

A WordPress plugin that provides a robust initial setup for an external widget with React admin interface and comprehensive security features.

## Features

- **React Admin Interface**: Modern React-based settings page in WordPress admin
- **Hash Key Validation**: Client-side and server-side validation for security (supports UUID format with hyphens)
- **Configurable Base URL**: Environment-specific base URL configuration via plugin constants
- **Conditional Widget Loading**: Widget only loads when properly configured
- **Security Dashboard**: Comprehensive security monitoring with automated scans
- **Quick Access**: Settings link directly on WordPress plugins page
- **Manual Save**: Explicit save functionality for configuration changes
- **WordPress Integration**: Full WordPress Settings API integration
- **REST API**: Custom REST endpoints for React-WordPress communication
- **Security Features**: Rate limiting, security headers, SSL validation, and event logging

## Plugin Structure

```
wp-scbc-plugin/
├── wp-scbc-plugin.php     # Main plugin file
├── plugin-constants.php        # Environment configuration (auto-generated)
├── admin/
│   └── admin.php               # Admin menu and pages
├── inc/                        # Includes directory
│   ├── settings/
│   │   └── settings.php        # Settings and localization
│   └── routes/
│       └── settings-routes.php # REST API routes
├── assets/                     # Built assets directory
│   └── build/                  # WordPress @wordpress/scripts build output
│       ├── settings.js         # Main admin JavaScript
│       ├── settings.css        # Admin styles
│       ├── settings.asset.php  # Asset dependencies
│       └── style-settings.css  # Additional styles
├── README.md                   # This file
├── developer-guide.md          # Developer documentation
└── documentation.md            # Technical documentation
```

## Installation

1. **Upload Plugin**: Place the plugin folder in `/wp-content/plugins/`
2. **Activate Plugin**: Activate through WordPress admin
3. **Configure Environment**: Update `plugin-constants.php` with your base URL if needed
4. **Built Assets**: Plugin comes with pre-built assets in `assets/build/` directory

## Admin Interface

Access the settings page via **Side Convo** in the WordPress admin main menu, or click the **Settings** link on the WordPress Plugins page.

### Configuration Fields

1. **Site Hash Key**: Required alphanumeric key with optional hyphens (25-40 characters)
   - Supports UUID format (e.g., `d4af9870-a67b-41dc-a763-62e79cac9a92`)
   - Pattern: `/^[a-zA-Z0-9\-]{25,40}$/`
   - Validated in real-time
   - Required to enable widget
2. **Widget Toggle**: Enable/disable widget (requires valid Site ID)
   - Toggle shows as "on"/"off" in settings
3. **Save Button**: Manual save functionality for all configuration changes

### Security Dashboard

Access comprehensive security monitoring via the plugin's security dashboard:
- **Security Statistics**: Total events, blocked attacks, rate limit hits
- **Event Log**: Detailed security event logging with timestamps
- **Automated Scans**: Hourly security scans with manual scan option
- **Security Alerts**: Email notifications for critical security events

## Frontend Integration

The plugin automatically enqueues the widget script when:
- Widget is enabled (`show_widget` is "on")
- Valid Site ID is provided

### Generated Script URL Pattern
```
{BASE_URL}/client/{SITE_ID}/script.js
```

**Current Base URL**: `https://dev.client.sideconvo.ai` (configured in `plugin-constants.php`)

Example:
```
https://dev.client.sideconvo.ai/client/ca615c2b63185da33d775d957/script.js
```

## PHP Code Structure

### Main Plugin Class: `SideconvoPlugin`

**Key Methods:**
- `enqueue_admin_scripts()`: Loads React admin interface
- `enqueue_frontend_scripts()`: Conditionally loads widget
- `register_rest_routes()`: Creates API endpoints
- `security_dashboard_callback()`: Security monitoring interface
- `run_security_scan()`: Automated security scanning

### Settings Management

**WordPress Options:**
- `SCBC_settings`: Main settings array containing:
  - `site_id`: Site ID 
  - `show_widget`: Widget enable/disable status ("on"/"off")
- `scbc_security_log`: Security event logging
- Various security-related transients for rate limiting

### Hash Key Validation

**PHP Regex Pattern:**
```php
'/^[a-zA-Z0-9\-]{25,40}$/'
```

### REST API Endpoints

- `POST /wp-json/scbc/v1/update-settings` - Update plugin settings
  - Permission: `edit_others_pages` capability required
  - Updates `SCBC_settings` option with site_id and show_widget values

## React Application

### Built with WordPress Scripts

The admin interface is built using `@wordpress/scripts` build system:
- **Entry Point**: WordPress handles React loading
- **Asset Management**: Uses WordPress asset management system
- **Styling**: Integrated with WordPress admin design system

### State Management

The admin interface manages:
- Site ID input and validation
- Widget toggle state  
- Save functionality with success/error feedback
- Loading states during API calls

## Development

### Building Assets

The plugin uses WordPress's official `@wordpress/scripts` build system:

```bash
# Install dependencies (if needed)
npm install

# Development build with watch
npm run start

# Production build
npm run build
```

**Build Output**: Assets are generated in `assets/build/` directory

### WordPress Hooks Used

- `init`: Initialize settings
- `admin_menu`: Add admin page
- `admin_enqueue_scripts`: Load admin assets
- `wp_enqueue_scripts`: Load frontend widget
- `rest_api_init`: Register API endpoints
- `plugin_action_links_{basename}`: Add Settings link to plugins page

### Security Features

- **Rate Limiting**: 30 requests per minute per user
- **Security Headers**: Content-Type-Options, X-Frame-Options, XSS-Protection, CSP
- **Input Sanitization**: All user inputs sanitized before storage
- **Capability Checks**: `edit_others_pages` permission required
- **Security Logging**: Comprehensive event logging and monitoring
- **SSL Validation**: Base URL SSL certificate validation
- **Malicious URL Blocking**: Protection against malicious URL patterns

## Customization

### Modifying Hash Key Validation

Edit the regex pattern in `is_valid_site_id()` method:

```php
private function is_valid_site_id($site_id) {
    return preg_match('/^[a-zA-Z0-9\-]{25,40}$/', $site_id);
}
```

### Base URL Configuration

The base URL is configured via `plugin-constants.php` file (auto-generated):

```php
define("SCBC_PLUGIN_BASE_URL", "https://dev.client.sideconvo.ai");
```

**Important**: This file is auto-generated and should not be manually edited. Update your deployment process to generate this file with the appropriate environment URL.

## Troubleshooting

### Common Issues

1. **Admin interface not loading**: Check if built assets exist in `assets/build/` directory
2. **Settings not saving**: Check user permissions (`edit_others_pages` capability required)
3. **Widget not appearing**: Verify Site ID is valid and widget toggle is "on"
4. **Invalid Site ID**: Ensure format matches `/^[a-zA-Z0-9\-]{25,40}$/` pattern
5. **Security events**: Check security dashboard for rate limiting or blocked requests
6. **Script not loading**: Verify base URL in `plugin-constants.php` is accessible

### Debug Mode

Enable WordPress debug mode to see detailed error messages:

```php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
```

## Browser Support

- Modern browsers with ES6+ support
- React 18 compatible
- WordPress 5.0+ required