397 lines
9.7 KiB
Markdown
397 lines
9.7 KiB
Markdown
# IGNY8 WordPress Bridge Plugin
|
|
|
|
**Version**: 1.0.0
|
|
**Last Updated**: 2025-10-17
|
|
**Requires**: WordPress 5.0+, PHP 7.4+
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
The IGNY8 WordPress Bridge Plugin is a **lightweight synchronization interface** that connects WordPress sites to the IGNY8 API. This plugin acts as a bridge, not a content management system, using WordPress native structures (taxonomies, post meta) to sync data bidirectionally with IGNY8.
|
|
|
|
### Key Principles
|
|
|
|
- ✅ **No Custom Database Tables** - Uses WordPress native taxonomies and post meta
|
|
- ✅ **Lightweight Bridge** - Minimal code, maximum efficiency
|
|
- ✅ **Two-Way Sync** - WordPress ↔ IGNY8 API synchronization
|
|
- ✅ **WordPress Native** - Leverages existing WordPress structures
|
|
- ✅ **API-First** - IGNY8 API is the source of truth
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
### Core Functionality
|
|
|
|
1. **API Authentication**
|
|
- Secure token management
|
|
- Automatic token refresh
|
|
- Encrypted credential storage
|
|
|
|
2. **Two-Way Synchronization**
|
|
- WordPress → IGNY8: Post status changes sync to IGNY8 tasks
|
|
- IGNY8 → WordPress: Content published from IGNY8 creates WordPress posts
|
|
|
|
3. **Taxonomy Mapping**
|
|
- WordPress taxonomies → IGNY8 Sectors/Clusters
|
|
- Hierarchical taxonomies map to IGNY8 Sectors
|
|
- Taxonomy terms map to IGNY8 Clusters
|
|
|
|
4. **Post Meta Integration**
|
|
- `_igny8_task_id` - Links WordPress posts to IGNY8 tasks
|
|
- `_igny8_cluster_id` - Links posts to IGNY8 clusters
|
|
- `_igny8_sector_id` - Links posts to IGNY8 sectors
|
|
- `_igny8_keyword_ids` - Links posts to IGNY8 keywords
|
|
|
|
5. **Site Data Collection**
|
|
- Automatic collection of WordPress posts, taxonomies, products
|
|
- Semantic mapping to IGNY8 structure
|
|
- WooCommerce integration support
|
|
|
|
6. **Status Mapping**
|
|
- WordPress post status → IGNY8 task status
|
|
- Automatic sync on post save/publish/status change
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
### Requirements
|
|
|
|
- WordPress 5.0 or higher
|
|
- PHP 7.4 or higher
|
|
- WordPress REST API enabled
|
|
- IGNY8 API account credentials
|
|
|
|
### Installation Steps
|
|
|
|
1. **Download/Clone Plugin**
|
|
```bash
|
|
git clone [repository-url]
|
|
cd igny8-ai-os
|
|
```
|
|
|
|
2. **Install in WordPress**
|
|
- Copy the `igny8-ai-os` folder to `/wp-content/plugins/`
|
|
- Or create a symlink for development
|
|
|
|
3. **Activate Plugin**
|
|
- Go to WordPress Admin → Plugins
|
|
- Activate "IGNY8 WordPress Bridge"
|
|
|
|
4. **Configure API Connection**
|
|
- Go to Settings → IGNY8 API
|
|
- Enter your IGNY8 email and password
|
|
- Click "Connect to IGNY8"
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
### API Settings
|
|
|
|
Navigate to **Settings → IGNY8 API** to configure:
|
|
|
|
- **Email**: Your IGNY8 account email
|
|
- **Password**: Your IGNY8 account password
|
|
- **Site ID**: Your IGNY8 site ID (auto-detected after connection)
|
|
|
|
### WordPress Integration
|
|
|
|
The plugin automatically:
|
|
|
|
1. **Registers Taxonomies** (if needed):
|
|
- `sectors` - Maps to IGNY8 Sectors
|
|
- `clusters` - Maps to IGNY8 Clusters
|
|
|
|
2. **Registers Post Meta Fields**:
|
|
- `_igny8_task_id`
|
|
- `_igny8_cluster_id`
|
|
- `_igny8_sector_id`
|
|
- `_igny8_keyword_ids`
|
|
- `_igny8_content_id`
|
|
|
|
3. **Sets Up WordPress Hooks**:
|
|
- `save_post` - Syncs post changes to IGNY8
|
|
- `publish_post` - Updates keywords on publish
|
|
- `transition_post_status` - Handles status changes
|
|
|
|
---
|
|
|
|
## Usage
|
|
|
|
### Basic Workflow
|
|
|
|
#### 1. Connect to IGNY8 API
|
|
|
|
```php
|
|
// Automatically handled via Settings page
|
|
// Or programmatically:
|
|
$api = new Igny8API();
|
|
$api->login('your@email.com', 'password');
|
|
```
|
|
|
|
#### 2. Sync WordPress Site Data
|
|
|
|
```php
|
|
// Collect and send site data to IGNY8
|
|
$site_id = get_option('igny8_site_id');
|
|
igny8_send_site_data_to_igny8($site_id);
|
|
```
|
|
|
|
#### 3. WordPress → IGNY8 Sync
|
|
|
|
When you save/publish a WordPress post:
|
|
|
|
1. Plugin checks for `_igny8_task_id` in post meta
|
|
2. If found, syncs post status to IGNY8 task
|
|
3. If published, updates related keywords to 'mapped' status
|
|
|
|
#### 4. IGNY8 → WordPress Sync
|
|
|
|
When content is published from IGNY8:
|
|
|
|
1. IGNY8 triggers webhook (or scheduled sync)
|
|
2. Plugin creates WordPress post via `wp_insert_post()`
|
|
3. Post meta saved with `_igny8_task_id`
|
|
4. IGNY8 task updated with WordPress post ID
|
|
|
|
---
|
|
|
|
## WordPress Structures Used
|
|
|
|
### Taxonomies
|
|
|
|
- **`sectors`** (hierarchical)
|
|
- Maps to IGNY8 Sectors
|
|
- Can be created manually or synced from IGNY8
|
|
|
|
- **`clusters`** (hierarchical)
|
|
- Maps to IGNY8 Clusters
|
|
- Can be created manually or synced from IGNY8
|
|
|
|
- **Native Taxonomies**
|
|
- `category` - Can map to IGNY8 Sectors
|
|
- `post_tag` - Can be used for keyword extraction
|
|
|
|
### Post Meta Fields
|
|
|
|
All stored in WordPress `wp_postmeta` table:
|
|
|
|
- `_igny8_task_id` (integer) - IGNY8 task ID
|
|
- `_igny8_cluster_id` (integer) - IGNY8 cluster ID
|
|
- `_igny8_sector_id` (integer) - IGNY8 sector ID
|
|
- `_igny8_keyword_ids` (array) - Array of IGNY8 keyword IDs
|
|
- `_igny8_content_id` (integer) - IGNY8 content ID
|
|
- `_igny8_last_synced` (datetime) - Last sync timestamp
|
|
|
|
### Post Status Mapping
|
|
|
|
| WordPress Status | IGNY8 Task Status |
|
|
|------------------|-------------------|
|
|
| `publish` | `completed` |
|
|
| `draft` | `draft` |
|
|
| `pending` | `pending` |
|
|
| `private` | `completed` |
|
|
| `trash` | `archived` |
|
|
| `future` | `scheduled` |
|
|
|
|
---
|
|
|
|
## API Reference
|
|
|
|
### Main Classes
|
|
|
|
#### `Igny8API`
|
|
|
|
Main API client class for all IGNY8 API interactions.
|
|
|
|
```php
|
|
$api = new Igny8API();
|
|
|
|
// Login
|
|
$api->login('email@example.com', 'password');
|
|
|
|
// Get keywords
|
|
$response = $api->get('/planner/keywords/');
|
|
|
|
// Create task
|
|
$response = $api->post('/writer/tasks/', $data);
|
|
|
|
// Update task
|
|
$response = $api->put('/writer/tasks/123/', $data);
|
|
```
|
|
|
|
#### `Igny8WordPressSync`
|
|
|
|
Handles two-way synchronization between WordPress and IGNY8.
|
|
|
|
```php
|
|
$sync = new Igny8WordPressSync();
|
|
// Automatically hooks into WordPress post actions
|
|
```
|
|
|
|
#### `Igny8SiteIntegration`
|
|
|
|
Manages site data collection and semantic mapping.
|
|
|
|
```php
|
|
$integration = new Igny8SiteIntegration($site_id);
|
|
$result = $integration->full_site_scan();
|
|
```
|
|
|
|
### Main Functions
|
|
|
|
- `igny8_login($email, $password)` - Authenticate with IGNY8
|
|
- `igny8_sync_post_status_to_igny8($post_id, $post, $update)` - Sync post to IGNY8
|
|
- `igny8_collect_site_data()` - Collect all WordPress site data
|
|
- `igny8_send_site_data_to_igny8($site_id)` - Send site data to IGNY8
|
|
- `igny8_map_site_to_semantic_strategy($site_id, $site_data)` - Map to semantic structure
|
|
|
|
### Site Metadata Endpoint (Plugin)
|
|
|
|
The plugin exposes a discovery endpoint that your IGNY8 app can call to learn which WordPress post types and taxonomies exist and how many items each contains.
|
|
|
|
- Endpoint: `GET /wp-json/igny8/v1/site-metadata/`
|
|
- Auth: Plugin-level connection must be enabled and authenticated (plugin accepts stored API key or access token)
|
|
- Response: IGNY8 unified response format (`success`, `data`, `message`, `request_id`)
|
|
|
|
Example response:
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"post_types": {
|
|
"post": { "label": "Posts", "count": 123 },
|
|
"page": { "label": "Pages", "count": 12 }
|
|
},
|
|
"taxonomies": {
|
|
"category": { "label": "Categories", "count": 25 },
|
|
"post_tag": { "label": "Tags", "count": 102 }
|
|
},
|
|
"generated_at": 1700553600
|
|
},
|
|
"message": "Site metadata retrieved",
|
|
"request_id": "550e8400-e29b-41d4-a716-446655440000"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## File Structure
|
|
|
|
```
|
|
igny8-ai-os/
|
|
├── igny8-bridge.php # Main plugin file
|
|
├── README.md # This file
|
|
├── docs/ # Documentation hub
|
|
│ ├── README.md # Index of available docs
|
|
│ ├── WORDPRESS-PLUGIN-INTEGRATION.md
|
|
│ ├── wp-bridge-implementation-plan.md
|
|
│ ├── missing-saas-api-endpoints.md
|
|
│ ├── STATUS_SYNC_DOCUMENTATION.md
|
|
│ └── STYLE_GUIDE.md
|
|
├── includes/
|
|
│ ├── class-igny8-api.php # API client class
|
|
│ ├── class-igny8-sync.php # Sync handler class
|
|
│ ├── class-igny8-site.php # Site integration class
|
|
│ └── functions.php # Helper functions
|
|
├── admin/
|
|
│ ├── class-admin.php # Admin interface
|
|
│ ├── settings.php # Settings page
|
|
│ └── assets/
|
|
│ ├── css/
|
|
│ └── js/
|
|
├── sync/
|
|
│ ├── hooks.php # WordPress hooks
|
|
│ ├── post-sync.php # Post synchronization
|
|
│ └── taxonomy-sync.php # Taxonomy synchronization
|
|
├── data/
|
|
│ ├── site-collection.php # Site data collection
|
|
│ └── semantic-mapping.php # Semantic mapping
|
|
└── uninstall.php # Uninstall handler
|
|
```
|
|
|
|
---
|
|
|
|
## Development
|
|
|
|
### Code Standards
|
|
|
|
- Follow WordPress Coding Standards
|
|
- Use WordPress native functions
|
|
- No custom database tables
|
|
- All data in WordPress native structures
|
|
|
|
### Testing
|
|
|
|
```bash
|
|
# Run WordPress unit tests
|
|
phpunit
|
|
|
|
# Test API connection
|
|
wp eval 'var_dump((new Igny8API())->login("test@example.com", "password"));'
|
|
```
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Authentication Issues
|
|
|
|
**Problem**: Cannot connect to IGNY8 API
|
|
|
|
**Solutions**:
|
|
1. Verify email and password are correct
|
|
2. Check API endpoint is accessible
|
|
3. Check WordPress REST API is enabled
|
|
4. Review error logs in WordPress debug log
|
|
|
|
### Sync Issues
|
|
|
|
**Problem**: Posts not syncing to IGNY8
|
|
|
|
**Solutions**:
|
|
1. Verify `_igny8_task_id` exists in post meta
|
|
2. Check API token is valid (not expired)
|
|
3. Review WordPress hooks are firing
|
|
4. Check error logs
|
|
|
|
### Token Expiration
|
|
|
|
**Problem**: Token expires frequently
|
|
|
|
**Solution**: Plugin automatically refreshes tokens. If issues persist, check token refresh logic.
|
|
|
|
---
|
|
|
|
## Support
|
|
|
|
- **Documentation**: See `WORDPRESS-PLUGIN-INTEGRATION.md`
|
|
- **API Documentation**: https://api.igny8.com/docs
|
|
- **Issues**: [GitHub Issues](repository-url/issues)
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
[Your License Here]
|
|
|
|
---
|
|
|
|
## Changelog
|
|
|
|
### 1.0.0 - 2025-10-17
|
|
- Initial release
|
|
- API authentication
|
|
- Two-way sync
|
|
- Site data collection
|
|
- Semantic mapping
|
|
|
|
---
|
|
|
|
**Last Updated**: 2025-10-17
|
|
|