<?php

declare( strict_types=1 );

namespace AcezSeo\Data;

if ( ! defined( 'ABSPATH' ) )
{
	exit;
}

interface AiSettingsRepositoryInterface
{
	public function get_active_provider(): string;

	public function set_active_provider( string $provider_id ): bool;

	public function get_model( string $provider_id ): string;

	/**
	 * Decrypted API key for the given provider — only call this right before
	 * making a request, never log or echo the result.
	 */
	public function get_api_key( string $provider_id ): string;

	public function has_api_key( string $provider_id ): bool;

	/**
	 * @param array{api_key?: string, model?: string} $settings api_key is
	 *   plaintext in, encrypted before storage; omit it to leave the stored
	 *   key untouched (so re-saving the model doesn't require re-entering the key).
	 */
	public function update_provider( string $provider_id, array $settings ): bool;

	/**
	 * Erases the provider's stored API key, model and "tested" flag so no
	 * trace remains in the database. If the provider was the active one,
	 * clears the active provider too.
	 */
	public function disconnect_provider( string $provider_id ): bool;

	/**
	 * Per-task model overrides (M36), e.g. a cheap model for alt texts and a
	 * stronger one for schema nodes. Empty value = the provider's own model.
	 *
	 * @return array<string, string> task => model
	 */
	public function get_task_models(): array;

	/**
	 * Merge-safe: tasks absent from $map keep their stored model.
	 *
	 * @param array<string, string> $map task => model
	 */
	public function update_task_models( array $map ): bool;

	/** Monthly soft limit of AI calls; 0 = no limit. */
	public function get_monthly_limit(): int;

	public function set_monthly_limit( int $limit ): bool;

	/**
	 * Marks which task the CURRENT request is for — get_model() then prefers
	 * that task's override. Set by AiGenerationService right before calling
	 * the provider, cleared right after (null).
	 */
	public function set_task_context( ?string $task ): void;

	/** Whether the provider's saved credentials passed a connection test. */
	public function is_tested( string $provider_id ): bool;

	public function mark_tested( string $provider_id, bool $tested ): bool;

	/**
	 * AI is "ready" when an active provider is selected, has an API key and
	 * passed a connection test — the gate for the Dashboard AI toggle.
	 */
	public function is_ready(): bool;
}