upskill-event-manager/docs/API-REFERENCE.md

# HVAC Plugin API Reference

## Table of Contents
- [PHP Classes](#php-classes)
- [JavaScript APIs](#javascript-apis)
- [WordPress Hooks](#wordpress-hooks)
- [AJAX Endpoints](#ajax-endpoints)
- [Shortcodes](#shortcodes)
- [Database Schema](#database-schema)

## PHP Classes

### HVAC_Plugin

Main plugin initialization class.

```php
class HVAC_Plugin {
    /**
     * Get plugin instance (Singleton)
     * @return HVAC_Plugin
     */
    public static function instance()
    
    /**
     * Initialize plugin components
     * @return void
     */
    public function init()
}
```

### HVAC_Event_Manager

Manages event creation and manipulation.

```php
class HVAC_Event_Manager {
    /**
     * Create a new event
     * @param array $event_data Event information
     * @return int|WP_Error Event ID or error
     */
    public static function create_event($event_data)
    
    /**
     * Get trainer events
     * @param int $trainer_id Trainer user ID
     * @param array $args Query arguments
     * @return array Array of event objects
     */
    public static function get_trainer_events($trainer_id, $args = array())
    
    /**
     * Update event
     * @param int $event_id Event ID
     * @param array $data Event data to update
     * @return bool Success status
     */
    public static function update_event($event_id, $data)
}
```

### HVAC_Certificate_Generator

Handles PDF certificate generation.

```php
class HVAC_Certificate_Generator {
    /**
     * Generate certificate for attendee
     * @param int $event_id Event ID
     * @param array $attendee Attendee data
     * @return string|WP_Error PDF file path or error
     */
    public function generate_certificate($event_id, $attendee)
    
    /**
     * Generate bulk certificates
     * @param int $event_id Event ID
     * @param array $attendees Array of attendee data
     * @return array Results array with successes and failures
     */
    public function generate_bulk_certificates($event_id, $attendees)
}
```

### HVAC_Trainer_Profile

Manages trainer profile functionality.

```php
class HVAC_Trainer_Profile {
    /**
     * Get trainer profile data
     * @param int $trainer_id User ID
     * @return array Profile data
     */
    public static function get_profile($trainer_id)
    
    /**
     * Update trainer profile
     * @param int $trainer_id User ID
     * @param array $data Profile data
     * @return bool Success status
     */
    public static function update_profile($trainer_id, $data)
    
    /**
     * Get trainer statistics
     * @param int $trainer_id User ID
     * @return array Statistics data
     */
    public static function get_statistics($trainer_id)
}
```

### HVAC_Menu_System

Handles navigation menu rendering.

```php
class HVAC_Menu_System {
    /**
     * Render trainer navigation menu
     * @return void Outputs HTML
     */
    public function render_trainer_menu()
    
    /**
     * Get menu structure for current user
     * @return array Menu items array
     */
    private function get_menu_structure()
}
```

## JavaScript APIs

### Global Objects

```javascript
// Main HVAC object
window.HVAC = {
    // Initialize components
    init: function() {},
    
    // Event management
    events: {
        create: function(data) {},
        update: function(eventId, data) {},
        delete: function(eventId) {}
    },
    
    // Profile management
    profile: {
        load: function(userId) {},
        save: function(data) {},
        uploadPhoto: function(file) {}
    },
    
    // Utilities
    utils: {
        showMessage: function(message, type) {},
        confirm: function(message, callback) {},
        formatDate: function(date) {}
    }
};

// AJAX helper
window.hvacAjax = {
    post: function(action, data, success, error) {},
    get: function(action, data, success, error) {}
};
```

### jQuery Plugins

```javascript
// Dashboard initialization
jQuery(document).ready(function($) {
    // Initialize date pickers
    $('.hvac-datepicker').datepicker({
        dateFormat: 'yy-mm-dd'
    });
    
    // Initialize form validation
    $('.hvac-form').validate({
        rules: {
            event_title: 'required',
            event_date: 'required'
        }
    });
});
```

## WordPress Hooks

### Actions

```php
// Plugin lifecycle
do_action('hvac_plugin_activated');
do_action('hvac_plugin_deactivated');
do_action('hvac_plugin_updated', $old_version, $new_version);

// Page creation
do_action('hvac_before_create_pages');
do_action('hvac_after_create_pages', $page_ids);

// Event management
do_action('hvac_before_event_save', $event_data);
do_action('hvac_after_event_save', $event_id, $event_data);
do_action('hvac_event_deleted', $event_id);

// Certificate generation
do_action('hvac_before_certificate_generate', $event_id, $attendee);
do_action('hvac_after_certificate_generate', $certificate_path);

// User profile
do_action('hvac_profile_updated', $user_id, $profile_data);
do_action('hvac_trainer_registered', $user_id);
```

### Filters

```php
// Capability checks
apply_filters('hvac_user_can_manage_event', $can_manage, $user_id, $event_id);
apply_filters('hvac_user_can_generate_certificates', $can_generate, $user_id);

// Data manipulation
apply_filters('hvac_event_data', $event_data, $event_id);
apply_filters('hvac_certificate_data', $certificate_data, $event_id, $attendee);
apply_filters('hvac_profile_fields', $fields, $user_id);

// Display filters
apply_filters('hvac_menu_items', $menu_items, $user_role);
apply_filters('hvac_dashboard_widgets', $widgets, $user_id);
apply_filters('hvac_date_format', $format);

// Query filters
apply_filters('hvac_events_query_args', $args, $context);
apply_filters('hvac_trainers_query_args', $args);
```

## Template System

### HVAC_Community_Events Template Loading

The plugin uses a custom template loading system via the `template_include` filter.

```php
class HVAC_Community_Events {
    /**
     * Load custom templates for HVAC pages
     * @param string $template Current template path
     * @return string Modified template path
     */
    public function load_custom_templates($template)
}
```

**Template Mappings:**
```php
// Certificate pages use full page templates
'trainer/certificate-reports' => 'templates/page-certificate-reports.php'
'trainer/generate-certificates' => 'templates/page-generate-certificates.php'

// Dashboard pages
'trainer/dashboard' => 'templates/template-hvac-dashboard.php'
'master-trainer/master-dashboard' => 'templates/template-hvac-master-dashboard.php'

// Other pages
'trainer/event/manage' => 'templates/page-manage-event.php'  // Event management with creation guide
'trainer/profile' => 'templates/page-trainer-profile.php'
```

**Template Structure Requirements:**
All HVAC page templates must include:
```php
// Define constant to indicate page template context
define('HVAC_IN_PAGE_TEMPLATE', true);

get_header(); // Required: WordPress header
?>
<div class="hvac-page-wrapper">
    <?php
    // Navigation menu
    if (class_exists('HVAC_Menu_System')) {
        HVAC_Menu_System::instance()->render_trainer_menu();
    }
    
    // Breadcrumbs
    if (class_exists('HVAC_Breadcrumbs')) {
        echo HVAC_Breadcrumbs::instance()->render_breadcrumbs();
    }
    ?>
    
    <div class="container">
        <?php echo do_shortcode('[hvac_shortcode_name]'); ?>
    </div>
</div>
<?php
get_footer(); // Required: WordPress footer
```

### Astra Theme Integration

```php
class HVAC_Astra_Integration {
    /**
     * Disable Astra breadcrumbs for HVAC pages
     */
    public function disable_astra_breadcrumbs($enabled)
    public function disable_breadcrumb_option($option)
    public function disable_breadcrumb_position($position)
    
    /**
     * Force full-width layout for HVAC pages
     */
    public function force_hvac_page_layout($layout)
    public function force_hvac_content_layout($layout)
}
```

**Common Template Issues & Solutions:**

1. **Pages showing only shortcode content:**
   - Ensure `load_custom_templates()` uses page templates, not content templates
   - Verify `get_header()` and `get_footer()` are called

2. **Duplicate breadcrumbs:**
   - Add Astra breadcrumb disable filters
   - Check theme breadcrumb settings

3. **Missing navigation:**
   - Remove `HVAC_NAV_RENDERED` constant checks
   - Ensure Menu System is properly initialized

## AJAX Endpoints

### CSV Import System

#### `hvac_run_enhanced_import`

**Description:** Execute enhanced CSV import from actual file with comprehensive field mapping

**Method:** POST  
**Permissions:** `hvac_master_trainer` or `administrator`  
**Nonce:** `hvac_ajax_nonce`

**Request:**
```javascript
jQuery.post(hvac_ajax.ajax_url, {
    action: 'hvac_run_enhanced_import',
    nonce: hvac_ajax.nonce
});
```

**Response:**
```json
{
    "success": true,
    "data": {
        "total_rows": 43,
        "users_created": 0,
        "users_updated": 43,
        "profiles_created": 0,
        "profiles_updated": 43,
        "taxonomies_assigned": 43,
        "venues_created": 15,
        "organizers_created": 20,
        "errors": 0,
        "details": ["Row 2: Processed email@example.com successfully", ...],
        "start_time": "2025-08-04 09:30:00",
        "end_time": "2025-08-04 09:31:15"
    }
}
```

**Features:**
- Reads `CSV_Trainers_Import_1Aug2025.csv` file directly
- Imports all 19 available CSV fields
- Creates/updates users and trainer profiles
- Assigns taxonomy terms (business_type, training_audience)
- Auto-creates venues and organizers based on CSV flags
- Comprehensive error handling and progress tracking

**Imported Fields:**
- Contact: Name, Email, Phone, Website
- Professional: Company, Role, Certification details
- Location: Country, State, City
- Taxonomies: Business Type, Training Audience
- Meta: Application Details, User ID, Creation Flags

### Event Management

```javascript
// Create event
{
    action: 'hvac_create_event',
    nonce: hvac_ajax.nonce,
    event_data: {
        title: 'Event Title',
        start_date: '2025-08-15',
        venue_id: 123,
        capacity: 50
    }
}

// Update event
{
    action: 'hvac_update_event',
    nonce: hvac_ajax.nonce,
    event_id: 456,
    event_data: {
        title: 'Updated Title'
    }
}

// Delete event
{
    action: 'hvac_delete_event',
    nonce: hvac_ajax.nonce,
    event_id: 456
}
```

### Profile Management

```javascript
// Get profile data
{
    action: 'hvac_get_profile',
    nonce: hvac_ajax.nonce,
    user_id: 789 // Optional, defaults to current user
}

// Update profile
{
    action: 'hvac_update_profile',
    nonce: hvac_ajax.nonce,
    profile_data: {
        bio: 'Updated bio',
        certifications: ['NATE', 'EPA'],
        website: 'https://example.com'
    }
}

// Upload profile photo
{
    action: 'hvac_upload_photo',
    nonce: hvac_ajax.nonce,
    photo: File // File object from input
}
```

### Certificate Generation

```javascript
// Generate single certificate
{
    action: 'hvac_generate_certificate',
    nonce: hvac_ajax.nonce,
    event_id: 456,
    attendee_id: 789
}

// Generate bulk certificates
{
    action: 'hvac_generate_bulk_certificates',
    nonce: hvac_ajax.nonce,
    event_id: 456,
    attendee_ids: [789, 790, 791]
}
```

## Shortcodes

### Display Shortcodes

```php
// Trainer dashboard
[hvac_trainer_dashboard]

// Event list
[hvac_event_list trainer_id="123" limit="10" status="upcoming"]

// Profile view
[hvac_trainer_profile_view user_id="123"]

// Profile edit form
[hvac_trainer_profile_edit]

// Certificate reports
[hvac_certificate_reports]

// Event creation form
[hvac_event_form]

// Venue management
[hvac_venue_list]
[hvac_venue_form]

// Organizer management
[hvac_organizer_list]
[hvac_organizer_form]
```

### Shortcode Parameters

```php
// Event list parameters
[hvac_event_list 
    trainer_id=""      // Trainer ID (default: current user)
    limit="10"         // Number of events
    status="upcoming"  // upcoming|past|all
    orderby="date"     // date|title|capacity
    order="ASC"        // ASC|DESC
]

// Profile view parameters
[hvac_trainer_profile_view 
    user_id=""         // User ID (default: current user)
    show_stats="true"  // Show statistics
    show_events="true" // Show event list
]
```

## Database Schema

### Post Meta (Events)

```sql
-- Event-specific meta keys
_EventStartDate         -- Event start datetime
_EventEndDate          -- Event end datetime
_EventVenueID          -- Venue post ID
_EventOrganizerID      -- Organizer post ID
_EventTrainerID        -- Trainer user ID
_EventCapacity         -- Maximum attendees
_EventRegisteredCount  -- Current registration count
_EventCertificateTemplate -- Certificate template ID
```

### User Meta (Trainers)

```sql
-- Profile information
role                   -- User's HVAC industry role (technician, installer, etc.)
hvac_bio               -- Trainer biography
hvac_certifications    -- Serialized array of certifications
hvac_trainer_photo     -- Attachment ID of profile photo
hvac_website           -- Trainer website URL
hvac_location          -- Trainer location
hvac_phone             -- Contact phone

-- Certification information (admin/master trainer editable only)
date_certified         -- Date when trainer was certified (YYYY-MM-DD)
certification_type     -- Type of certification ('Certified measureQuick Trainer', 'Certified measureQuick Champion')
certification_status   -- Current certification status ('Active', 'Expired', 'Pending', 'Disabled')

-- Training preferences
hvac_training_formats  -- Serialized array of formats
hvac_training_audience -- Target audience
hvac_training_topics   -- Specialized topics

-- Statistics (cached)
hvac_total_events      -- Total events created
hvac_total_students    -- Total students trained
hvac_total_revenue     -- Total revenue generated
```

### Options Table

```sql
-- Plugin settings
hvac_plugin_version    -- Current plugin version
hvac_settings          -- Serialized settings array
hvac_email_templates   -- Email template configurations
hvac_certificate_settings -- Certificate generation settings

-- Feature flags
hvac_enable_zoho       -- Zoho CRM integration
hvac_enable_analytics  -- Analytics tracking
hvac_maintenance_mode  -- Maintenance mode flag
```

## Manual Geocoding API Endpoints

### Trigger Manual Geocoding
**Endpoint**: `hvac_trigger_geocoding`  
**Method**: POST (AJAX)  
**Permissions**: `hvac_master_trainer` or `administrator`

Manually triggers geocoding for all trainer profiles using Google Maps API.

**Parameters**: None (uses AJAX nonce for security)

**Response**:
```json
{
  "success": true,
  "data": {
    "total_profiles": 53,
    "geocoded_count": 45,
    "skipped_count": 7,
    "error_count": 1,
    "api_key_valid": true,
    "start_time": "2025-08-01 20:34:36",
    "end_time": "2025-08-01 20:34:36",
    "duration": 21600,
    "details": [
      {
        "id": 5868,
        "title": "William Ramsey - Trainer Profile",
        "status": "already_geocoded",
        "coordinates": {"lat": 33.9532531, "lng": -84.5499358}
      }
    ]
  }
}
```

**Status Values**:
- `geocoded` - Successfully geocoded in this operation
- `already_geocoded` - Profile already has valid coordinates
- `no_address` - Profile missing location data
- `error` - Geocoding failed with error
- `failed` - Google Maps API returned no results

### Enhanced CSV Import
**Endpoint**: `hvac_run_enhanced_import`  
**Method**: POST (AJAX)  
**Permissions**: `hvac_master_trainer` or `administrator`

Imports trainer location data from embedded CSV data with field mapping.

**Parameters**: None (uses embedded CSV data)

**Response**:
```json
{
  "success": true,
  "data": {
    "total_rows": 43,
    "users_created": 0,
    "users_updated": 43,
    "profiles_created": 0,
    "profiles_updated": 43,
    "errors": 0,
    "geocoding_scheduled": 43,
    "session_id": "enhanced_2025-08-02_02-33-53",
    "import_log_saved": true,
    "start_time": "2025-08-01 19:12:36",
    "end_time": "2025-08-01 19:12:36",
    "duration": 0
  }
}
```

### Get Geocoding Statistics
**Endpoint**: `hvac_get_geocoding_stats`  
**Method**: POST (AJAX)  
**Permissions**: `hvac_trainer`, `hvac_master_trainer`, or `administrator`

Retrieves current geocoding coverage and statistics.

**Parameters**: None

**Response**:
```json
{
  "success": true,
  "data": {
    "total_profiles": "53",
    "geocoded_profiles": "45",
    "public_profiles": "53",
    "sync_issues": 0
  }
}
```

## Trainer Profile Sharing API

### HVAC_QR_Generator Class

Handles QR code generation and profile sharing functionality.

```php
class HVAC_QR_Generator {
    /**
     * Generate QR code URL using QR Server API
     * @param string $data Data to encode in QR code
     * @param int $size QR code size in pixels (default: 200)
     * @param string $error_correction Error correction level (L, M, Q, H)
     * @return string QR code image URL
     */
    public function generate_qr_url($data, $size = 200, $error_correction = 'M')
    
    /**
     * Generate QR code for trainer profile
     * @param int $profile_id Trainer profile ID
     * @param int $size QR code size in pixels
     * @return string|false QR code URL or false on error
     */
    public function generate_trainer_profile_qr($profile_id, $size = 200)
    
    /**
     * Get shareable trainer profile URL
     * @param int $profile_id Trainer profile ID
     * @return string|false Profile URL or false on error
     */
    public function get_trainer_profile_share_url($profile_id)
    
    /**
     * Get trainer profile data for sharing
     * @param int $profile_id Trainer profile ID
     * @return array|false Profile data or false on error
     */
    public function get_trainer_share_data($profile_id)
    
    /**
     * Generate profile card HTML for sharing
     * @param int $profile_id Trainer profile ID
     * @param array $options Display options
     * @return string|false HTML content or false on error
     */
    public function generate_profile_card_html($profile_id, $options = [])
}
```

### Profile Sharing AJAX Endpoint

#### `hvac_get_profile_share_data`

**Description:** Retrieve trainer profile sharing data including QR code URL

**Method:** POST  
**Permissions:** Any logged-in user  
**Nonce:** `hvac_profile_sharing`

**Request:**
```javascript
jQuery.post(hvac_sharing.ajax_url, {
    action: 'hvac_get_profile_share_data',
    profile_id: 5840,
    nonce: hvac_sharing.nonce
});
```

**Response:**
```json
{
    "success": true,
    "data": {
        "profile_id": 5840,
        "user_id": 123,
        "trainer_name": "John Smith",
        "business_name": "HVAC Pro Services",
        "trainer_city": "Atlanta",
        "trainer_state": "GA",
        "certification_type": "Certified measureQuick Trainer",
        "profile_image": "https://example.com/uploads/profile.jpg",
        "share_url": "https://example.com/find-a-trainer/profile/5840/",
        "qr_code_url": "https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=https%3A//example.com/find-a-trainer/profile/5840/&ecc=M"
    }
}
```

**QR Code API Details:**
- **Service:** QR Server API (https://api.qrserver.com/v1/create-qr-code/)
- **Format:** PNG image
- **Default Size:** 200x200 pixels
- **Error Correction:** M (Medium, ~15% damage recovery)
- **Encoding:** URL-encoded profile share URL

**Share URL Structure:**
- **Pattern:** `/find-a-trainer/profile/{profile_id}/`
- **Rewrite Rule:** `^find-a-trainer/profile/([0-9]+)/?$`
- **Query Var:** `trainer_profile_id`
- **Requirements:** Must include trailing slash for WordPress rewrite rules

**JavaScript Integration:**
```javascript
// Profile sharing object
var ProfileSharing = {
    // Open share modal
    openShareModal: function(profileId) {},
    
    // Load share data via AJAX
    loadShareData: function(profileId) {},
    
    // Create profile card HTML
    createProfileCardHtml: function(data) {},
    
    // Copy URL to clipboard
    copyShareUrl: function() {}
};

// Localized variables required
hvac_sharing.ajax_url    // WordPress AJAX URL
hvac_sharing.nonce      // Security nonce
hvac_sharing.strings    // UI messages
```

**Profile Card Features:**
- Professional trainer photo or initial placeholder
- measureQuick certification badge overlay
- Business name and location display
- QR code for instant sharing
- Responsive design (600x300px default)
- Professional styling with rounded corners

## Error Codes

### Geocoding Errors
- `GEOCODING_INVALID_NONCE` - Security nonce verification failed
- `GEOCODING_INSUFFICIENT_PERMISSIONS` - User lacks required capabilities
- `GEOCODING_API_KEY_INVALID` - Google Maps API key missing or invalid
- `GEOCODING_NO_PROFILES` - No trainer profiles found to geocode
- `GEOCODING_ADDRESS_FAILED` - Address could not be geocoded
- `GEOCODING_API_ERROR` - Google Maps API returned an error

### CSV Import Errors
- `IMPORT_INVALID_NONCE` - Security nonce verification failed
- `IMPORT_INSUFFICIENT_PERMISSIONS` - User lacks required capabilities
- `IMPORT_NO_DATA` - No CSV data available to import
- `IMPORT_USER_NOT_FOUND` - CSV email doesn't match any WordPress user
- `IMPORT_PROFILE_NOT_FOUND` - User doesn't have a trainer profile
- `IMPORT_UPDATE_FAILED` - Failed to update profile metadata

### Event Errors
- `HVAC001` - Invalid event data
- `HVAC002` - Event not found
- `HVAC003` - Insufficient permissions to manage event
- `HVAC004` - Event capacity exceeded

### User Errors
- `HVAC101` - User not found
- `HVAC102` - Invalid user role
- `HVAC103` - Insufficient permissions
- `HVAC104` - Profile update failed

### Certificate Errors
- `HVAC201` - Certificate generation failed
- `HVAC202` - Invalid attendee data
- `HVAC203` - Template not found
- `HVAC204` - PDF library error

### System Errors
- `HVAC901` - Database connection error
- `HVAC902` - File system error
- `HVAC903` - Third-party API error
- `HVAC904` - Unknown error

## Response Formats

### Success Response
```json
{
    "success": true,
    "data": {
        "id": 123,
        "message": "Operation completed successfully",
        "additional_data": {}
    }
}
```

### Error Response
```json
{
    "success": false,
    "data": {
        "code": "HVAC001",
        "message": "Invalid event data",
        "details": {
            "field": "event_date",
            "error": "Date must be in the future"
        }
    }
}
```