igny8/igny8-wp-plugin

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

   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

// Automatically handled via Settings page
// Or programmatically:
$api = new Igny8API();
$api->login('your@email.com', 'password');

2. Sync WordPress Site Data

// 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.

$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.

$sync = new Igny8WordPressSync();
// Automatically hooks into WordPress post actions

Igny8SiteIntegration

Manages site data collection and semantic mapping.

$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:

{
  "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

# 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

---

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