igny8/igny8-wp-plugin/docs/STATUS_SYNC_DOCUMENTATION.md

# Status Sync & Content ID Documentation

**Last Updated**: 2025-10-17

---

## Overview

This document explains how the plugin handles status synchronization and content_id tracking between IGNY8 and WordPress.

---

## Status Mapping

### IGNY8 → WordPress

When content arrives from IGNY8, status is mapped as follows:

| IGNY8 Status | WordPress Status | Description |
|--------------|------------------|-------------|
| `completed` | `publish` | Content is published |
| `draft` | `draft` | Content is draft |
| `pending` | `pending` | Content pending review |
| `scheduled` | `future` | Content scheduled |
| `archived` | `trash` | Content archived |

### WordPress → IGNY8

When WordPress post status changes, it's mapped back to IGNY8:

| WordPress Status | IGNY8 Status | Description |
|------------------|--------------|-------------|
| `publish` | `completed` | Post is published |
| `draft` | `draft` | Post is draft |
| `pending` | `pending` | Post pending review |
| `private` | `completed` | Post is private (published) |
| `trash` | `archived` | Post is deleted |
| `future` | `scheduled` | Post is scheduled |

---

## Content ID Tracking

### Storage

The plugin stores IGNY8 `content_id` in post meta:
- **Meta Key**: `_igny8_content_id`
- **Type**: Integer
- **REST API**: Available via `/wp-json/wp/v2/posts?meta_key=_igny8_content_id&meta_value=123`

### Task ID Tracking

The plugin also stores IGNY8 `task_id`:
- **Meta Key**: `_igny8_task_id`
- **Type**: Integer
- **REST API**: Available via `/wp-json/wp/v2/posts?meta_key=_igny8_task_id&meta_value=456`

---

## Response to IGNY8

When content is created/updated in WordPress, the plugin responds to IGNY8 with:

```json
{
  "assigned_post_id": 123,
  "post_url": "https://example.com/post/",
  "wordpress_status": "publish",
  "status": "completed",
  "synced_at": "2025-10-17 12:00:00",
  "post_type": "post",
  "content_type": "post",
  "content_id": 789
}
```

### Response Fields

- **`assigned_post_id`**: WordPress post ID
- **`post_url`**: Full URL to the post
- **`wordpress_status`**: Actual WordPress status (publish/pending/draft)
- **`status`**: IGNY8 mapped status (completed/pending/draft)
- **`synced_at`**: Timestamp of sync
- **`post_type`**: WordPress post type
- **`content_type`**: IGNY8 content type
- **`content_id`**: IGNY8 content ID (if provided)

---

## REST API Endpoints

The plugin provides REST API endpoints for IGNY8 to query WordPress:

### 1. Get Post by Content ID

**Endpoint**: `GET /wp-json/igny8/v1/post-by-content-id/{content_id}`

**Response**:
```json
{
  "success": true,
  "data": {
    "post_id": 123,
    "title": "Post Title",
    "status": "publish",
    "wordpress_status": "publish",
    "igny8_status": "completed",
    "url": "https://example.com/post/",
    "post_type": "post",
    "content_id": 789,
    "task_id": 456,
    "last_synced": "2025-10-17 12:00:00"
  }
}
```

### 2. Get Post by Task ID

**Endpoint**: `GET /wp-json/igny8/v1/post-by-task-id/{task_id}`

**Response**: Same format as above

### 3. Get Post Status by Content ID

**Endpoint**: `GET /wp-json/igny8/v1/post-status/{content_id}`

**Response**:
```json
{
  "success": true,
  "data": {
    "post_id": 123,
    "wordpress_status": "publish",
    "igny8_status": "completed",
    "status_mapping": {
      "publish": "completed",
      "draft": "draft",
      "pending": "pending",
      "private": "completed",
      "trash": "archived",
      "future": "scheduled"
    },
    "content_id": 789,
    "url": "https://example.com/post/",
    "last_synced": "2025-10-17 12:00:00"
  }
}
```

---

## Status Flow

### When Content Arrives from IGNY8

1. **Receive** content with `content_type`, `status`, `content_id`, `task_id`
2. **Map** IGNY8 status to WordPress status
3. **Create** WordPress post with mapped status
4. **Store** `content_id` and `task_id` in post meta
5. **Respond** to IGNY8 with:
   - WordPress post ID
   - WordPress actual status
   - IGNY8 mapped status
   - Post URL
   - Content ID

### When WordPress Status Changes

1. **Detect** status change via `save_post` or `transition_post_status` hook
2. **Get** `task_id` and `content_id` from post meta
3. **Map** WordPress status to IGNY8 status
4. **Update** IGNY8 task with:
   - WordPress actual status
   - IGNY8 mapped status
   - Post URL
   - Content ID (if available)
   - Sync timestamp

---

## Available Meta Fields

All fields are available for IGNY8 to read via REST API:

- `_igny8_task_id` - IGNY8 task ID
- `_igny8_content_id` - IGNY8 content ID
- `_igny8_cluster_id` - IGNY8 cluster ID
- `_igny8_sector_id` - IGNY8 sector ID
- `_igny8_keyword_ids` - Array of keyword IDs
- `_igny8_wordpress_status` - WordPress post status
- `_igny8_last_synced` - Last sync timestamp

---

## Query Examples

### Via WordPress REST API

```bash
# Get post by content_id
GET /wp-json/wp/v2/posts?meta_key=_igny8_content_id&meta_value=123

# Get post by task_id
GET /wp-json/wp/v2/posts?meta_key=_igny8_task_id&meta_value=456

# Get all IGNY8 posts
GET /wp-json/wp/v2/posts?meta_key=_igny8_task_id
```

### Via IGNY8 REST API Endpoints

```bash
# Get post by content_id (with status info)
GET /wp-json/igny8/v1/post-by-content-id/123

# Get post status only
GET /wp-json/igny8/v1/post-status/123

# Get post by task_id
GET /wp-json/igny8/v1/post-by-task-id/456
```

---

## Authentication

REST API endpoints require:
- IGNY8 API authentication (access token)
- Authorization header: `Bearer {access_token}`

Or internal use when IGNY8 is connected.

---

## Status Flags Available

✅ **Task ID** - Stored and queryable  
✅ **Content ID** - Stored and queryable  
✅ **WordPress Status** - Stored and sent to IGNY8  
✅ **IGNY8 Status** - Mapped and sent to IGNY8  
✅ **Post Type** - Stored and sent to IGNY8  
✅ **Content Type** - Stored and sent to IGNY8  
✅ **Sync Timestamp** - Stored and sent to IGNY8  
✅ **Post URL** - Sent to IGNY8  

---

**All status information is available for IGNY8 to read and query!**