Refactor SEO automation into unified CLI application

Major refactoring to create a clean, integrated CLI application: ### New Features: - Unified CLI executable (./seo) with simple command structure - All commands accept optional CSV file arguments - Auto-detection of latest files when no arguments provided - Simplified output directory structure (output/ instead of output/reports/) - Cleaner export filename format (all_posts_YYYY-MM-DD.csv) ### Commands: - export: Export all posts from WordPress sites - analyze [csv]: Analyze posts with AI (optional CSV input) - recategorize [csv]: Recategorize posts with AI - seo_check: Check SEO quality - categories: Manage categories across sites - approve [files]: Review and approve recommendations - full_pipeline: Run complete workflow - analytics, gaps, opportunities, report, status ### Changes: - Moved all scripts to scripts/ directory - Created config.yaml for configuration - Updated all scripts to use output/ directory - Deprecated old seo-cli.py in favor of new ./seo - Added AGENTS.md and CHANGELOG.md documentation - Consolidated README.md with updated usage ### Technical: - Added PyYAML dependency - Removed hardcoded configuration values - All scripts now properly integrated - Better error handling and user feedback Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
2026-02-16 14:24:44 +01:00
parent 3b51952336
commit 8c7cd24685
57 changed files with 16095 additions and 560 deletions
--- a/wordpress-plugins/rank-math-api-manager/docs/troubleshooting.md
+++ b/wordpress-plugins/rank-math-api-manager/docs/troubleshooting.md
@@ -0,0 +1,607 @@
+# Troubleshooting Guide - Rank Math API Manager Plugin
+
+## 📋 Overview
+
+This guide helps you identify and resolve common issues with the Rank Math API Manager plugin. Follow the troubleshooting steps to diagnose and fix problems quickly.
+
+## 🔍 Quick Diagnostic Checklist
+
+Before diving into specific issues, run through this checklist:
+
+- ✅ **Plugin is activated** in WordPress admin
+- ✅ **Rank Math SEO plugin** is installed and active
+- ✅ **WordPress REST API** is accessible
+- ✅ **Application Password** is correctly configured
+- ✅ **User has `edit_posts` permissions**
+- ✅ **Post ID exists** and is published
+- ✅ **HTTPS is enabled** (recommended for security)
+
+## 🚨 Common Error Codes
+
+### 401 Unauthorized
+
+**Error Message**: `"Sorry, you are not allowed to do that."`
+
+#### Possible Causes:
+
+1. **Invalid credentials**
+2. **Missing Application Password**
+3. **Incorrect username**
+4. **User lacks permissions**
+
+#### Solutions:
+
+**Step 1: Verify Application Password**
+
+```bash
+# Test with cURL
+curl -X POST "https://your-site.com/wp-json/rank-math-api/v1/update-meta" \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -H "Authorization: Basic [your-base64-credentials]" \
+  -d "post_id=123&rank_math_title=Test"
+```
+
+**Step 2: Check User Permissions**
+
+1. Go to **Users → All Users**
+2. Find your user account
+3. Verify role has `edit_posts` capability
+4. Check if user is active
+
+**Step 3: Regenerate Application Password**
+
+1. Go to **Users → Profile**
+2. Scroll to "Application Passwords"
+3. Delete existing password
+4. Create new Application Password
+5. Update your integration
+
+**Step 4: Verify Base64 Encoding**
+
+```bash
+# Test encoding
+echo -n "username:application_password" | base64
+```
+
+### 404 Not Found
+
+**Error Message**: `"No route was found matching the URL and request method"`
+
+#### Possible Causes:
+
+1. **Plugin not activated**
+2. **WordPress REST API disabled**
+3. **Incorrect endpoint URL**
+4. **Permalink structure issues**
+
+#### Solutions:
+
+**Step 1: Check Plugin Status**
+
+1. Go to **Plugins → Installed Plugins**
+2. Verify "Rank Math API Manager" is **Active**
+3. Check for any error messages
+
+**Step 2: Test REST API**
+
+```bash
+# Test WordPress REST API
+curl -X GET "https://your-site.com/wp-json/wp/v2/posts"
+```
+
+**Step 3: Check Permalinks**
+
+1. Go to **Settings → Permalinks**
+2. Select any option other than "Plain"
+3. Save changes
+
+**Step 4: Verify Endpoint URL**
+
+```bash
+# Test endpoint availability
+curl -X GET "https://your-site.com/wp-json/rank-math-api/v1/update-meta"
+```
+
+Expected response: 404 (confirms endpoint exists but requires POST)
+
+### 400 Bad Request
+
+**Error Message**: `"No metadata was updated"`
+
+#### Possible Causes:
+
+1. **Missing `post_id`**
+2. **Invalid post ID**
+3. **No SEO fields provided**
+4. **Invalid data format**
+
+#### Solutions:
+
+**Step 1: Verify Post ID**
+
+```bash
+# Check if post exists
+curl -X GET "https://your-site.com/wp-json/wp/v2/posts/123"
+```
+
+**Step 2: Check Request Format**
+
+```bash
+# Ensure proper form data
+curl -X POST "https://your-site.com/wp-json/rank-math-api/v1/update-meta" \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -H "Authorization: Basic [credentials]" \
+  -d "post_id=123&rank_math_title=Test Title"
+```
+
+**Step 3: Verify Post Status**
+
+1. Go to **Posts → All Posts**
+2. Find the post by ID
+3. Ensure status is "Published"
+
+### 500 Internal Server Error
+
+**Error Message**: Various server error messages
+
+#### Possible Causes:
+
+1. **PHP memory limit exceeded**
+2. **Plugin conflicts**
+3. **Server configuration issues**
+4. **Database connection problems**
+
+#### Solutions:
+
+**Step 1: Enable Debug Mode**
+
+```php
+// Add to wp-config.php
+define('WP_DEBUG', true);
+define('WP_DEBUG_LOG', true);
+define('WP_DEBUG_DISPLAY', false);
+```
+
+**Step 2: Check Error Logs**
+
+```bash
+# Check WordPress debug log
+tail -f wp-content/debug.log
+
+# Check server error logs
+tail -f /var/log/apache2/error.log
+# or
+tail -f /var/log/nginx/error.log
+```
+
+**Step 3: Increase Memory Limit**
+
+```php
+// Add to wp-config.php
+define('WP_MEMORY_LIMIT', '256M');
+```
+
+**Step 4: Test Plugin Conflicts**
+
+1. Deactivate all plugins except Rank Math SEO and Rank Math API Manager
+2. Test the API endpoint
+3. Reactivate plugins one by one to identify conflicts
+
+## 🔧 Integration-Specific Issues
+
+### n8n Integration Problems
+
+#### Issue: Authentication Fails in n8n
+
+**Symptoms**: 401 errors in n8n workflow
+
+**Solutions**:
+
+1. **Check Credential Configuration**
+
+   - Verify username and Application Password
+   - Ensure no extra spaces or characters
+   - Test credentials manually first
+
+2. **Update n8n Node Configuration**
+
+```json
+{
+  "authentication": "httpBasicAuth",
+  "username": "your_username",
+  "password": "your_application_password"
+}
+```
+
+3. **Test with Simple Request**
+
+```json
+{
+  "method": "POST",
+  "url": "https://your-site.com/wp-json/rank-math-api/v1/update-meta",
+  "contentType": "form-urlencoded",
+  "bodyParameters": {
+    "post_id": "123",
+    "rank_math_title": "Test Title"
+  }
+}
+```
+
+#### Issue: Data Mapping Errors
+
+**Symptoms**: Missing or incorrect data in API calls
+
+**Solutions**:
+
+1. **Add Data Validation Node**
+
+```javascript
+// Add Code node before HTTP Request
+const postId = $("Previous Node").first().json.post_id;
+const seoTitle = $("Previous Node").first().json.seo_title;
+
+if (!postId || !seoTitle) {
+  throw new Error("Missing required data");
+}
+
+return {
+  post_id: postId,
+  rank_math_title: seoTitle,
+  rank_math_description: $("Previous Node").first().json.seo_description || "",
+  rank_math_focus_keyword: $("Previous Node").first().json.focus_keyword || "",
+};
+```
+
+2. **Add Error Handling**
+
+```javascript
+// Add Code node after HTTP Request
+const response = $("HTTP Request").first().json;
+
+if (response.error) {
+  throw new Error(`API Error: ${response.error}`);
+}
+
+return {
+  success: true,
+  data: response,
+};
+```
+
+### Zapier Integration Problems
+
+#### Issue: Code Action Fails
+
+**Symptoms**: JavaScript errors in Zapier
+
+**Solutions**:
+
+1. **Add Error Handling**
+
+```javascript
+try {
+  const response = await fetch(
+    "https://your-site.com/wp-json/rank-math-api/v1/update-meta",
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Authorization: "Basic " + btoa("username:application_password"),
+      },
+      body: new URLSearchParams({
+        post_id: inputData.post_id,
+        rank_math_title: inputData.seo_title,
+        rank_math_description: inputData.seo_description,
+        rank_math_focus_keyword: inputData.focus_keyword,
+      }),
+    }
+  );
+
+  const result = await response.json();
+
+  if (!response.ok) {
+    throw new Error(
+      `HTTP ${response.status}: ${result.message || "Unknown error"}`
+    );
+  }
+
+  return { success: true, data: result };
+} catch (error) {
+  return { success: false, error: error.message };
+}
+```
+
+2. **Validate Input Data**
+
+```javascript
+// Validate required fields
+if (!inputData.post_id) {
+  throw new Error("Post ID is required");
+}
+
+if (!inputData.seo_title) {
+  throw new Error("SEO title is required");
+}
+```
+
+### Python Integration Problems
+
+#### Issue: SSL Certificate Errors
+
+**Symptoms**: SSL verification failures
+
+**Solutions**:
+
+```python
+import requests
+import urllib3
+
+# Disable SSL warnings (not recommended for production)
+urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
+
+# Make request with SSL verification disabled
+response = requests.post(url, headers=headers, data=data, verify=False)
+```
+
+#### Issue: Connection Timeouts
+
+**Symptoms**: Request timeouts
+
+**Solutions**:
+
+```python
+import requests
+
+# Set timeout
+response = requests.post(url, headers=headers, data=data, timeout=30)
+
+# Retry logic
+from requests.adapters import HTTPAdapter
+from requests.packages.urllib3.util.retry import Retry
+
+session = requests.Session()
+retry = Retry(connect=3, backoff_factor=0.5)
+adapter = HTTPAdapter(max_retries=retry)
+session.mount('http://', adapter)
+session.mount('https://', adapter)
+
+response = session.post(url, headers=headers, data=data)
+```
+
+## 🛠️ Advanced Troubleshooting
+
+### Debug Mode Setup
+
+**Step 1: Enable WordPress Debug**
+
+```php
+// Add to wp-config.php
+define('WP_DEBUG', true);
+define('WP_DEBUG_LOG', true);
+define('WP_DEBUG_DISPLAY', false);
+define('WP_DEBUG_DISPLAY', false);
+define('SCRIPT_DEBUG', true);
+```
+
+**Step 2: Add Plugin Debug Logging**
+
+```php
+// Add to your theme's functions.php or a custom plugin
+add_action('rest_api_init', function() {
+    error_log('REST API initialized');
+});
+
+add_action('wp_rest_server_class', function($class) {
+    error_log('REST server class: ' . $class);
+});
+```
+
+**Step 3: Monitor API Requests**
+
+```php
+// Add to your theme's functions.php
+add_action('rest_api_init', function() {
+    add_filter('rest_pre_dispatch', function($result, $server, $request) {
+        error_log('API Request: ' . $request->get_route());
+        error_log('API Method: ' . $request->get_method());
+        error_log('API Params: ' . json_encode($request->get_params()));
+        return $result;
+    }, 10, 3);
+});
+```
+
+### Performance Issues
+
+#### Issue: Slow API Responses
+
+**Solutions**:
+
+1. **Optimize Database Queries**
+
+```php
+// Add to wp-config.php
+define('SAVEQUERIES', true);
+```
+
+2. **Check Server Resources**
+
+```bash
+# Monitor server resources
+htop
+free -h
+df -h
+```
+
+3. **Enable Caching**
+
+```php
+// Add caching headers
+add_action('rest_api_init', function() {
+    add_filter('rest_post_dispatch', function($response, $handler, $request) {
+        $response->header('Cache-Control', 'public, max-age=300');
+        return $response;
+    }, 10, 3);
+});
+```
+
+### Security Issues
+
+#### Issue: Unauthorized Access Attempts
+
+**Solutions**:
+
+1. **Implement Rate Limiting**
+
+```php
+// Add rate limiting
+add_action('rest_api_init', function() {
+    add_filter('rest_pre_dispatch', function($result, $server, $request) {
+        $ip = $_SERVER['REMOTE_ADDR'];
+        $key = 'api_rate_limit_' . $ip;
+        $count = get_transient($key);
+
+        if ($count && $count > 100) {
+            return new WP_Error('rate_limit_exceeded', 'Rate limit exceeded', ['status' => 429]);
+        }
+
+        set_transient($key, ($count ? $count + 1 : 1), 3600);
+        return $result;
+    }, 10, 3);
+});
+```
+
+2. **Log Security Events**
+
+```php
+// Log failed authentication attempts
+add_action('rest_authentication_errors', function($result) {
+    if ($result !== null) {
+        error_log('Failed API authentication attempt from IP: ' . $_SERVER['REMOTE_ADDR']);
+    }
+    return $result;
+});
+```
+
+## 📊 Monitoring and Logging
+
+### Set Up Monitoring
+
+**Step 1: Create Health Check Endpoint**
+
+```php
+// Add to your plugin
+add_action('rest_api_init', function() {
+    register_rest_route('rank-math-api/v1', '/health', [
+        'methods' => 'GET',
+        'callback' => function() {
+            return [
+                'status' => 'healthy',
+                'timestamp' => current_time('mysql'),
+                'version' => '1.0.6'
+            ];
+        },
+        'permission_callback' => '__return_true'
+    ]);
+});
+```
+
+**Step 2: Monitor API Usage**
+
+```php
+// Track API usage
+add_action('rest_api_init', function() {
+    add_filter('rest_post_dispatch', function($response, $handler, $request) {
+        if (strpos($request->get_route(), 'rank-math-api') !== false) {
+            $usage = get_option('rank_math_api_usage', []);
+            $date = date('Y-m-d');
+            $usage[$date] = ($usage[$date] ?? 0) + 1;
+            update_option('rank_math_api_usage', $usage);
+        }
+        return $response;
+    }, 10, 3);
+});
+```
+
+### Log Analysis
+
+**Step 1: Parse WordPress Debug Log**
+
+```bash
+# Find API-related errors
+grep "rank-math-api" wp-content/debug.log
+
+# Find authentication errors
+grep "authentication" wp-content/debug.log
+
+# Find recent errors
+tail -n 100 wp-content/debug.log | grep "ERROR"
+```
+
+**Step 2: Monitor Server Logs**
+
+```bash
+# Apache error logs
+tail -f /var/log/apache2/error.log | grep "your-domain.com"
+
+# Nginx error logs
+tail -f /var/log/nginx/error.log | grep "your-domain.com"
+```
+
+## 🆘 Getting Help
+
+### Before Contacting Support
+
+1. **Collect Information**:
+
+   - WordPress version
+   - Plugin version
+   - PHP version
+   - Server environment
+   - Complete error messages
+   - Request/response data
+
+2. **Test with Minimal Setup**:
+
+   - Deactivate other plugins
+   - Switch to default theme
+   - Test with basic cURL request
+
+3. **Check Known Issues**:
+   - Review GitHub issues
+   - Check documentation
+   - Search community forums
+
+### Contact Information
+
+- **GitHub Issues**: [Create an issue](https://github.com/devora-as/rank-math-api-manager/issues)
+- **Email Support**: [devora.no](https://devora.no)
+- **Documentation**: [docs/](docs/)
+
+### Required Information for Support
+
+When contacting support, include:
+
+```
+WordPress Version: X.X.X
+Plugin Version: X.X.X
+PHP Version: X.X.X
+Server: Apache/Nginx
+Error Message: [Complete error message]
+Request Data: [API request details]
+Response Data: [API response details]
+Steps to Reproduce: [Detailed steps]
+Environment: [Local/Staging/Production]
+```
+
+---
+
+**Related Documentation**:
+
+- [Installation Guide](installation.md)
+- [API Documentation](api-documentation.md)
+- [Integration Guide](integration-guide.md)
+
+---
+
+**Last Updated**: July 2025  
+**Version**: 1.0.6