<?php
declare(strict_types=1);
// ==================================================
// Nuclear Fancy Pants Edition™ — NUCLEAR+++
// File: /home/ploi/automarketer-ai.com/public/wp-content/plugins/automarketer-ai/includes/module-interface.php
// Description: Contract for all AutoMarketer AI modules (AI providers and future premium modules) - NUCLEAR+++
// Last Edited: 2026-04-12
// ==================================================
namespace AutoMarketerAI;
if (!defined('ABSPATH')) {
    exit('No direct script access allowed.');
}
interface ModuleInterface
{
    // Unique slug — e.g. 'ai-claude', 'ai-gemini'
    public function get_id(): string;

    // Human-readable name — e.g. 'Claude', 'Gemini'
    public function get_name(): string;

    // Short description shown on the modules page
    public function get_description(): string;

    // Absolute URL to the provider logo
    public function get_logo_url(): string;

    // Category — 'AI' for providers, future: 'Premium', etc.
    public function get_category(): string;

    // Number of available models (used for display only)
    public function get_model_count(): int;

    // Map of model_id => human label
    public function get_available_models(): array;

    // Optional notice shown when the provider only has one model
    public function get_single_model_notice(): string;

    // API key prefix used for client-side validation hint — e.g. 'sk-ant-'
    public function get_api_key_prefix(): string;

    // Validate a raw API key — must make a real HTTP check
    public function validate_api_key(string $key): bool;

    // Hook any WP actions needed (e.g. admin_footer for activation modal)
    public function register(): void;

    // Send a free-form prompt to the provider and return the raw text response.
    // Returns an empty string on any failure — callers must handle gracefully.
    // $model must be a valid model ID for this provider.
    public function generate_raw(string $prompt, string $api_key, string $model): string;
}