# 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