<?php
/**
 * AI Client Interface
 *
 * @package PackshotPhotoAI
 */

namespace PackshotPhotoAI\API;

defined('ABSPATH') || exit;

/**
 * Interface for AI providers (Gemini, OpenAI, etc.)
 */
interface ClientInterface {

    /**
     * Test API connection
     *
     * @return array{success: bool, message: string}
     */
    public function test_connection(): array;

    /**
     * Generate SEO description for media file
     *
     * @param string $file_path Absolute path to file
     * @param string $mime_type MIME type
     * @param int    $post_id   Optional attachment ID to get original filename
     * @param string $language  Optional target language override
     * @return array{success: bool, message?: string, data?: array}
     */
    public function generate_seo_description(string $file_path, string $mime_type, int $post_id = 0, string $language = '', string $image_context = ''): array;

    /**
     * Summarize site context from homepage text
     *
     * @param string $text     Homepage text content
     * @param string $language Optional target language override
     * @return array{success: bool, message?: string, data?: string}
     */
    public function summarize_site_context(string $text, string $language = ''): array;
}
