<?php
/**
 * BookiFlex Core
 *
 * @package    BookiFlex
 * @subpackage Core
 * @author     BookiFlex
 * @copyright  Copyright (c) 2025 BookiFlex
 * @license    GPL-2.0-or-later
 *
 * @link       https://bookiflex.com
 */

declare(strict_types=1);

namespace BookiFlex\Core\Contract;

defined('ABSPATH') || exit;

/**
 * Interface for extension activators
 *
 * Extensions implement this interface to provide their own activation logic
 * and database schemas during plugin activation/deactivation.
 *
 * Methods are divided into two categories:
 * - CODE-DEPENDENT: Called when codebase changes (WP activation, code upgrade/downgrade)
 * - LICENSE-DEPENDENT: Called when license state changes (can happen without code change)
 */
interface ExtensionActivatorInterface
{
	// =========================================================================
	// CODE-DEPENDENT METHODS
	// Called when codebase physically changes
	// =========================================================================

	/**
	 * Get extension-specific database schemas
	 *
	 * Returns array of Schema class names that should be registered
	 * during table creation/migration.
	 *
	 * @return array<class-string> Array of schema class names
	 */
	public function getSchemas(): array;

	/**
	 * First installation of the system
	 *
	 * Called ONLY ONCE when BookiFlex is installed for the first time.
	 * Use for one-time setup: default options, initial data seeding.
	 *
	 * Note: Roles and capabilities are handled by the main activator.
	 */
	public function install(): void;

	/**
	 * Complete uninstallation
	 *
	 * Called when plugin is being completely removed.
	 * Use for cleanup: drop tables, remove options.
	 */
	public function uninstall(): void;

	// =========================================================================
	// LICENSE-DEPENDENT METHODS
	// Called when license state changes (premium features access)
	// =========================================================================

	/**
	 * Enable runtime resources
	 *
	 * Called when extension should be active (premium license valid).
	 * Use for: registering AS jobs, webhooks, external subscriptions.
	 *
	 * MUST be idempotent - safe to call multiple times.
	 */
	public function enableRuntimeResources(): void;

	/**
	 * Disable runtime resources
	 *
	 * Called when extension should be inactive (no premium license).
	 * Use for: canceling AS jobs, removing webhooks.
	 *
	 * MUST be idempotent - safe to call multiple times.
	 */
	public function disableRuntimeResources(): void;
}
