# Claritee Publisher for WordPress

Publish designs from Claritee directly to WordPress page builders with one click.

## Features

- 🚀 **One-Click Publishing** - Publish from Claritee directly to WordPress
- 🎨 **Elementor Support** - Full Elementor page builder integration (more builders coming soon)
- 🖼️ **Automatic Image Import** - Images are automatically downloaded to your media library
- 🔐 **Secure API Keys** - Simple and secure API key authentication
- 📱 **Responsive** - Maintains responsive breakpoints and settings
- 🎯 **Draft or Publish** - Choose to publish directly or save as draft
- 📊 **Usage Tracking** - Monitor API key usage and last access time

## Requirements

- WordPress 5.8 or higher
- PHP 7.4 or higher
- Elementor 3.0.0 or higher (for Elementor support)

## Installation

1. Download the `claritee-design-importer.zip` file
2. Go to **WordPress Admin → Plugins → Add New → Upload Plugin**
3. Upload the ZIP file and click **Install Now**
4. Click **Activate Plugin**

### Manual Installation

1. Unzip the plugin files
2. Upload the `claritee-design-importer` folder to `/wp-content/plugins/`
3. Activate the plugin through the **Plugins** menu in WordPress

## Setup

### 1. Generate API Key

After activating the plugin:

1. Go to **WordPress Admin → Claritee → API Keys**
2. Enter a name for your key (e.g., "Production")
3. Click **Generate New API Key**
4. **Copy the key immediately** - you won't be able to see it again!

### 2. Connect Claritee to WordPress

In your Claritee workspace:

1. Go to **Settings → Integrations → WordPress**
2. Enter your WordPress details:
   - **Site URL:** `https://your-site.com`
   - **API Key:** Paste the key you generated
3. Click **Test Connection** to verify
4. Save the settings

## Usage

### Publishing a Page

1. Design your page in Claritee
2. Click **Publish → WordPress (Elementor)**
3. Configure options:
   - **Page Title**
   - **Page Slug** (URL)
   - **Status** (Draft or Publish)
4. Click **Publish**
5. You'll receive links to:
   - View the live page
   - Edit in Elementor
   - Preview the draft

### API Endpoint

The plugin creates a REST API endpoint that Claritee uses:

```
POST /wp-json/claritee/v1/publish
```

#### Request Headers

```
X-Claritee-API-Key: your_api_key_here
```

Or alternatively:

```
Authorization: Bearer your_api_key_here
```

#### Request Body

```json
{
  "page_builder": "elementor",
  "title": "My New Page",
  "slug": "my-new-page",
  "status": "draft",
  "content_data": {
    // Elementor JSON structure
  },
  "images": [
    {
      "url": "https://claritee.io/images/image1.jpg",
      "id": "claritee-img-123",
      "alt": "Image description"
    }
  ]
}
```

#### Response

```json
{
  "id": 123,
  "url": "https://your-site.com/my-new-page",
  "edit_url": "https://your-site.com/wp-admin/post.php?post=123&action=elementor",
  "preview_url": "https://your-site.com/?page_id=123&preview=true",
  "status": "draft",
  "builder": "elementor",
  "images_imported": 3
}
```

### Authentication

All requests must include the API key in the header:

**Option 1: Custom Header (Recommended)**
```bash
curl -X POST https://your-site.com/wp-json/claritee/v1/publish \
  -H "X-Claritee-API-Key: claritee_abc123..." \
  -H "Content-Type: application/json" \
  -d @payload.json
```

**Option 2: Bearer Token**
```bash
curl -X POST https://your-site.com/wp-json/claritee/v1/publish \
  -H "Authorization: Bearer claritee_abc123..." \
  -H "Content-Type: application/json" \
  -d @payload.json
```

### Health Check

Test if the plugin is working:

```bash
curl https://your-site.com/wp-json/claritee/v1/health
```

Response:

```json
{
  "status": "ok",
  "version": "1.0.0",
  "supported_builders": {
    "elementor": {
      "name": "Elementor",
      "class": "\\Claritee\\PageBuilders\\ElementorBuilder"
    }
  }
}
```

## API Key Management

### Generating Keys

- Go to **Claritee → API Keys** in WordPress admin
- Click **Generate New API Key**
- Give it a descriptive name
- Copy the key immediately

### Revoking Keys

- Find the key in the Active API Keys table
- Click **Revoke** to disable it (can be restored if needed later)
- Click **Delete** to permanently remove it

### Key Information

Each API key shows:
- **Name** - Friendly identifier
- **Key** - Partial key display (first 20 and last 8 characters)
- **Created** - When it was generated
- **Last Used** - Most recent usage timestamp
- **Usage Count** - Total number of API calls made

### Security Best Practices

1. **Never share your API keys** publicly or in version control
2. **Use different keys** for production, staging, and development
3. **Revoke unused keys** regularly
4. **Rotate keys periodically** for enhanced security
5. **Monitor usage** to detect unauthorized access

## Extensibility

The plugin is designed to support multiple page builders. Developers can add support for additional builders:

### Adding a New Page Builder

1. Create a new class in `includes/PageBuilders/` that implements `PageBuilderInterface`

```php
<?php
namespace Claritee\PageBuilders;

class BricksBuilder implements PageBuilderInterface {

    public function is_available() {
        return defined('BRICKS_VERSION');
    }

    public function get_availability_message() {
        return __('Bricks is available', 'claritee-design-importer');
    }

    public function create_page($data) {
        // Implementation
    }

    public function get_name() {
        return 'Bricks';
    }

    public function get_min_version() {
        return '1.5.0';
    }
}
```

2. Register the builder using the filter:

```php
add_filter('claritee_supported_builders', function($builders) {
    $builders['bricks'] = [
        'name'  => 'Bricks',
        'class' => '\\Claritee\\PageBuilders\\BricksBuilder',
    ];
    return $builders;
});
```

## Troubleshooting

### "API key is required"

- Verify you're sending the API key in the header
- Use either `X-Claritee-API-Key` or `Authorization: Bearer` header

### "Invalid or revoked API key"

- Check that the API key hasn't been revoked
- Generate a new key if needed
- Ensure you copied the full key correctly

### "Permission denied"

- Verify the user associated with the API key has `publish_pages` capability
- Check that the user is an Administrator or Editor

### "Elementor is not installed or activated"

- Install and activate Elementor plugin
- Minimum version required: 3.0.0

### "A page with slug already exists"

- Choose a different slug
- Or delete/rename the existing page

### Images not importing

- Verify image URLs are publicly accessible
- Check WordPress media upload limits (php.ini: `upload_max_filesize`, `post_max_size`)
- Review error logs in **Tools → Site Health → Info → Server**

### Plugin not appearing

- Check PHP version (7.4+ required)
- Check WordPress version (5.8+ required)
- Look for errors in **Plugins → Installed Plugins**

## Security

- Uses secure API key authentication with `random_bytes()`
- API keys are 40+ characters long with unique prefix
- Validates user permissions (`publish_pages` capability required)
- Sanitizes all inputs
- Checks for duplicate slugs
- Only allows specific post statuses
- Keys can be revoked instantly
- Usage tracking for audit trails

## Changelog

### 1.0.0 (2025-01-XX)

- Initial release
- Elementor page builder support
- Image import functionality
- API key authentication system
- WordPress admin settings page
- Usage tracking and monitoring
- REST API endpoint
- Health check endpoint
- Extensible architecture for future builders

## Support

For issues or questions:

- Visit: https://help.claritee.io
- Email: support@claritee.io
- GitHub: https://github.com/claritee/claritee-design-importer

## License

GPL v2 or later

## Credits

Developed by Claritee
https://claritee.io