igny8/INDICATOR_STATUS_LOGIC.md

Integration Status Indicator Logic

Three States

1. Not Configured ⚪ (Gray)

Color: bg-gray-300
Text: "Not configured"

When shown:

• No API key exists, OR
• Integration toggle is disabled, OR
• No integration record exists

What it means:

• User needs to generate API key or enable integration toggle

---

2. Configured 🔵 (Brand/Primary Color)

Color: bg-brand-500 (Blue)
Text: "Configured" or "Testing..." (while authenticating)

When shown:

• ✅ API key exists
• ✅ Integration toggle is enabled
• ⏳ Authentication test is in progress OR failed

What it means:

• Basic setup is complete
• System is testing authentication with WordPress
• If auth test fails, stays in this state (doesn't downgrade to "not configured")

---

3. Connected 🟢 (Green)

Color: bg-green-500
Text: "Connected"

When shown:

• ✅ API key exists
• ✅ Integration toggle is enabled
• ✅ Authentication test passed (test_connection API returned success: true)

What it means:

• Full authentication successful
• WordPress credentials are valid
• Plugin can communicate with IGNY8

---

Flow Diagram

User generates API key + Enables toggle
    ↓
⚪ Not Configured → 🔵 Configured (shows "Testing...")
    ↓
API test: /v1/integration/integrations/{id}/test_connection/
    ↓
    ├─ Success → 🟢 Connected
    └─ Failed  → 🔵 Configured (stays blue, not green)

---

Code Logic

// Step 1: Check basic configuration
if (wordPressIntegration && wordPressIntegration.is_active && site?.wp_api_key) {
  setIntegrationStatus('configured'); // Show BLUE
  testAuthentication(); // Start auth test
} else {
  setIntegrationStatus('not_configured'); // Show GRAY
}

// Step 2: Test authentication
const testAuthentication = async () => {
  const resp = await fetchAPI(`/v1/integration/integrations/${id}/test_connection/`);
  
  if (resp && resp.success) {
    setIntegrationStatus('connected'); // Show GREEN
  } else {
    setIntegrationStatus('configured'); // Stay BLUE
  }
};

---

Visual States

State	Indicator	Text	Meaning
Not Configured	⚪ Gray circle	"Not configured"	No API key or toggle off
Configured	🔵 Blue circle	"Configured" or "Testing..."	Setup complete, testing auth
Connected	🟢 Green circle	"Connected"	Fully authenticated

---

Benefits

1. Progressive Feedback:

   • Users see blue immediately when setup is complete
   • Don't have to wait for green to know basic config is done

2. Clear States:

   • Gray = Need to configure
   • Blue = Configured but not verified
   • Green = Fully working

3. No False Negatives:

   • If auth test fails temporarily, stays blue (not gray)
   • Doesn't make users think they need to reconfigure

4. Automatic Testing:

   • Runs automatically when integration is enabled
   • No manual "refresh" button needed

---

Authentication Test

The authentication test calls:

POST /v1/integration/integrations/{id}/test_connection/

This backend endpoint checks:

1. WordPress REST API is reachable
2. Credentials are valid (username + app_password)
3. IGNY8 plugin is installed (optional)
4. Plugin has API key configured (optional)
5. Bidirectional communication works (optional)

Success criteria: Endpoint returns { success: true }

Note: The indicator shows "Connected" (green) only if authentication succeeds. Partial success (WordPress reachable but no plugin) keeps it as "Configured" (blue).