# WPForms to Mailjet Automation Plugin - Build Instructions

## Directory Structure

```
wpforms-mailjet-automation/
├── wpforms-mailjet-automation.php  (Main plugin file)
├── uninstall.php                   (Cleanup on uninstall)
├── index.php                       (Silence is golden)
├── BUILD-INSTRUCTIONS.md           (This file)
├── package.json                    (Node.js dependencies - create this)
├── includes/
│   ├── index.php
│   ├── class-wpfmj-activator.php
│   ├── class-wpfmj-deactivator.php
│   ├── class-wpfmj-loader.php
│   ├── class-wpfmj-core.php
│   ├── class-wpfmj-cpt.php
│   ├── class-wpfmj-encryption.php
│   ├── class-wpfmj-mailjet-api.php
│   ├── class-wpfmj-form-handler.php
│   └── class-wpfmj-error-logger.php
├── admin/
│   ├── index.php
│   ├── class-wpfmj-admin.php
│   ├── class-wpfmj-dashboard.php
│   ├── css/
│   │   ├── index.php
│   │   └── wpfmj-admin.css
│   └── js/
│       ├── index.php
│       ├── wpfmj-wizard.js         (Built React bundle - will be generated)
│       └── wpfmj-wizard.asset.php  (Dependency file)
└── assets/
    ├── index.php
    └── src/
        ├── index.php
        └── wizard/
            ├── index.php
            ├── App.jsx              (Main React component)
            ├── components/
            │   ├── index.php
            │   ├── StepOne.jsx
            │   ├── StepTwo.jsx
            │   ├── StepThree.jsx
            │   ├── StepFour.jsx
            │   ├── StepFive.jsx
            │   └── StepSix.jsx
            └── utils/
                ├── index.php
                └── api.js
```

## Building the React Application

### Step 1: Install Node.js Dependencies

Create a `package.json` file in the plugin root directory:

```json
{
  "name": "wpforms-mailjet-automation",
  "version": "1.0.0",
  "description": "WPForms to Mailjet automation plugin",
  "scripts": {
    "build": "wp-scripts build assets/src/wizard/App.jsx --output-path=admin/js",
    "start": "wp-scripts start assets/src/wizard/App.jsx --output-path=admin/js"
  },
  "devDependencies": {
    "@wordpress/scripts": "^26.0.0"
  },
  "dependencies": {
    "@wordpress/element": "^5.0.0",
    "@wordpress/components": "^25.0.0",
    "@wordpress/i18n": "^4.0.0"
  }
}
```

Then run:
```bash
npm install
```

### Step 2: Build the React Bundle

Run the build command:
```bash
npm run build
```

This will compile all React components into `admin/js/wpfmj-wizard.js` and generate `admin/js/wpfmj-wizard.asset.php` with dependency information.

### Step 3: Development Mode (Optional)

For development with hot reload:
```bash
npm run start
```

## Installation

1. Upload the entire `wpforms-mailjet-automation` folder to `/wp-content/plugins/`
2. Activate the plugin through the 'Plugins' menu in WordPress
3. Ensure WPForms is installed and activated
4. (Optional) Copy `wpfmj-config-sample.php` to `wpfmj-config.php` and customize settings
5. Navigate to 'Mailjet Automations' in the WordPress admin menu

## Requirements

- WordPress 5.8 or higher
- PHP 7.4 or higher
- WPForms plugin (any version)
- Node.js 14+ and npm (for building only)

## Plugin Features

### Core Functionality
- ✅ React-based wizard interface using @wordpress/components
- ✅ 6-step automation setup process
- ✅ Custom post type for storing automations
- ✅ Encrypted API key storage
- ✅ Field mapping (email, firstname, lastname)
- ✅ Trigger field selection (checkbox, radio, dropdown, multi-select)
- ✅ Answer-to-list mapping with unique list constraints
- ✅ Automatic retry logic (3 attempts with exponential backoff)
- ✅ Email notifications on persistent failures
- ✅ Error logging with custom database table
- ✅ Dashboard for managing automations
- ✅ Pause/activate/edit/delete automations
- ✅ Error count display per automation

### Security Features
- ✅ AES-256-CBC encryption for API credentials
- ✅ Nonce verification on all AJAX requests
- ✅ Capability checks (manage_options)
- ✅ Input sanitization and validation
- ✅ Prepared SQL statements

### Compatibility
- ✅ WooCommerce HPOS compatibility declared
- ✅ No conflicts with WPForms
- ✅ No conflicts with WooCommerce
- ✅ No conflicts with LearnDash
- ✅ No conflicts with Wordfence
- ✅ Safe database schema with proper indexes

### Performance
- ✅ No excessive AJAX calls (dashboard loads once per page view)
- ✅ Efficient database queries with proper indexing
- ✅ Automatic cleanup of old error logs (90 days)
- ✅ Minimal overhead on form submissions
- ✅ Set-and-forget architecture

## File-by-File Placement

### Root Files
- `wpforms-mailjet-automation.php` - Root directory
- `uninstall.php` - Root directory
- `index.php` - Root directory
- `package.json` - Root directory (create from template above)

### Includes Files (includes/)
- `index.php`
- `class-wpfmj-activator.php`
- `class-wpfmj-deactivator.php`
- `class-wpfmj-loader.php`
- `class-wpfmj-core.php`
- `class-wpfmj-cpt.php`
- `class-wpfmj-encryption.php`
- `class-wpfmj-mailjet-api.php`
- `class-wpfmj-form-handler.php`
- `class-wpfmj-error-logger.php`

### Admin Files (admin/)
- `index.php`
- `class-wpfmj-admin.php`
- `class-wpfmj-dashboard.php`

### Admin CSS (admin/css/)
- `index.php`
- `wpfmj-admin.css`

### Admin JS (admin/js/)
- `index.php`
- `wpfmj-wizard.asset.php`
- `wpfmj-wizard.js` (will be generated by build process)

### React Source Files (assets/src/wizard/)
- `index.php`
- `App.jsx`

### React Components (assets/src/wizard/components/)
- `index.php`
- `StepOne.jsx`
- `StepTwo.jsx`
- `StepThree.jsx`
- `StepFour.jsx`
- `StepFive.jsx`
- `StepSix.jsx`

### React Utils (assets/src/wizard/utils/)
- `index.php`
- `api.js`

## Testing Checklist

### Before Production
- [ ] Test with fresh WordPress installation
- [ ] Test with WPForms Lite and Pro
- [ ] Test form submission triggers automation
- [ ] Test with checkbox fields (multiple selections)
- [ ] Test with radio/dropdown fields (single selection)
- [ ] Test API connection with valid/invalid credentials
- [ ] Test saving as draft vs. activating
- [ ] Test editing existing automation
- [ ] Test pausing/activating automation
- [ ] Test deleting automation
- [ ] Verify email notifications on API failures
- [ ] Check error log table creation
- [ ] Verify encryption/decryption of API keys
- [ ] Test with WooCommerce active (HPOS enabled)
- [ ] Test uninstall cleanup

### Performance Testing
- [ ] No infinite loops detected
- [ ] No memory leaks during form submission
- [ ] Dashboard loads without excessive queries
- [ ] No AJAX polling in background

### Security Testing
- [ ] SQL injection attempts blocked
- [ ] XSS attempts blocked
- [ ] CSRF protected with nonces
- [ ] Capability checks enforced
- [ ] API credentials properly encrypted

## Common Issues and Solutions

### Issue: React bundle not loading
**Solution:** Run `npm run build` to generate the JavaScript bundle

### Issue: "WPForms required" error
**Solution:** Install and activate WPForms plugin

### Issue: API connection fails
**Solution:** Verify API credentials in Mailjet account under Account Settings > REST API

### Issue: Automation not triggering
**Solution:** Check that automation status is "Active" (not "Paused")

### Issue: Missing form fields
**Solution:** Ensure the selected form has been saved with fields in WPForms

## Support

For issues, questions, or feature requests, please contact the plugin author.

## License

GPL-2.0+