# AuraSEO - API Documentation

## Overview

AuraSEO provides a professional interface for managing AI-powered SEO meta tag generation. This document covers the plugin's architecture and implementation details.

## Plugin Structure

```
auraseo/
├── auraseo.php          # Main plugin file with core class
├── assets/
│   ├── css/style.css        # Admin UI styling
│   └── js/script.js         # Admin interactions and AJAX
├── languages/               # Internationalization support
├── docs/                    # Documentation files
├── src/                     # Future core classes
├── LICENSE                  # GPLv2+ License
├── CHANGELOG.md            # Version history
├── INSTALLATION.md         # Setup guide
├── CONTRIBUTING.md         # Contribution guidelines
└── README.md               # Project overview
```

## Core Class: AutoMeta_AI_Core

### Constructor
```php
public function __construct()
```
Registers all hooks, actions, and AJAX handlers.

### Public Methods

#### register_menu()
Creates the admin menu page for the plugin interface.

#### load_assets($hook)
Enqueues CSS and JavaScript files with proper versioning.

Parameters:
- $hook (string): Current admin page hook

#### download_sample_csv()
Provides a CSV template for users with proper nonce verification.

#### render_ui()
Displays the main admin interface with multiple tabs.

#### uninstall_plugin()
Cleanup function called on plugin uninstallation.

## AJAX Handlers

### amai_check_connection
Action: wp_ajax_amai_check_connection

Verifies API key validity with the selected AI provider.

Parameters:
- key (string): API key to verify
- security (string): Nonce token

Response:
```json
{
  "success": true/false,
  "data": "Status message"
}
```

### amai_check_model
Action: wp_ajax_amai_check_model

Verifies that the selected AI model is accessible.

Parameters:
- key (string): API key
- model (string): Model name
- security (string): Nonce token

### amai_generate_meta
Action: wp_ajax_amai_generate_meta

Generates metadata for a single page URL using AI.

Parameters:
- page_url (string): URL to analyze
- temp_key (string): API key
- temp_model (string): AI model name
- security (string): Nonce token

Response:
```json
{
  "success": true/false,
  "data": {
    "title": "Generated Meta Title",
    "desc": "Generated Meta Description",
    "key": "focus_keyword"
  }
}
```

### amai_save_meta
Action: wp_ajax_amai_save_meta

Saves generated metadata to WordPress post using Yoast/Rank Math.

Parameters:
- page_url (string): Post URL
- img_url (string): Feature image URL
- title (string): Meta title
- desc (string): Meta description
- key (string): Focus keyword
- security (string): Nonce token

## Constants

```php
AUTOMETA_AI_VERSION    // Plugin version
AUTOMETA_AI_PATH       // Plugin directory path
AUTOMETA_AI_URL        // Plugin directory URL
```

## Database Options

The plugin uses WordPress options for configuration:

| Option Name | Type | Description |
|---|---|---|
| amai_homepage_context | string | Brand context for AI |
| amai_provider | string | Selected AI provider (gemini/openai) |
| amai_api_key | string | Encrypted API key |
| amai_gemini_model | string | Selected Gemini model |

## Hooks & Filters

### Actions
- admin_menu - Register menu
- admin_enqueue_scripts - Load assets
- admin_init - Initialize admin
- wp_ajax_* - AJAX handlers

### Nonce
- Name: amai_ajax_nonce
- Life: 12 hours (default)
- Used in: All AJAX requests

## Security Implementation

### Sanitization
```php
sanitize_text_field()  // Text inputs
wp_kses_post()         // HTML content
intval()               // Integer values
```

### Validation
```php
wp_verify_nonce()      // Verify nonce tokens
check_admin_referer()  // Form verification
current_user_can()     // Capability checks
```

## Future Extensibility

### Planned Core Classes
- AI_Provider - Base AI provider interface
- CSV_Handler - CSV processing
- Meta_Generator - Meta tag generation
- Yoast_Integration - Yoast SEO handler
- RankMath_Integration - Rank Math handler

### Hooks for Extensions
- autometa_ai_before_generation
- autometa_ai_after_generation
- autometa_ai_custom_providers

## Development Tips

1. Local Testing: Use WP CLI for quick testing
2. Debug Mode: Enable WP_DEBUG in wp-config.php
3. Browser Console: Check for JavaScript errors in DevTools
4. Network Tab: Monitor AJAX requests and responses
5. Database: Use phpMyAdmin to inspect options

## Support

For questions or issues:
- Check INSTALLATION.md
- Visit GitHub Issues
- Create a Discussion