asd
This commit is contained in:
alorig
396
igy8-wp-plugin/docs/README.md
Normal file
396
igy8-wp-plugin/docs/README.md
Normal file
@@ -0,0 +1,396 @@
|
||||
# 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
|
||||
|
||||
Reference in New Issue
Block a user