<?php

namespace WeDevs\AppBridge\Core\Contracts;

/**
 * License backend transport contract.
 *
 * Abstracts WHERE a license is validated (Appsero SaaS vs. a self-hosted
 * EDD Software Licensing store) so each integration can pick the backend
 * that matches the store its product is actually sold from.
 *
 * Implementations talk to the remote service and persist the normalised
 * stored-license shape under the manager's option key:
 *
 *   [
 *     'key'              => string,
 *     'status'           => 'activate' | 'deactivate',
 *     'remaining'        => int|null,
 *     'activation_limit' => int|null,
 *     'expiry_days'      => int|false|null,   // false = perpetual/lifetime
 *     'title'            => string,
 *     'source_id'        => string,
 *     'recurring'        => bool,
 *   ]
 *
 * Admin notices, caching and the mobile-app verification filters live in
 * {@see \WeDevs\AppBridge\Core\AbstractLicenseManager} and are
 * backend-agnostic.
 */
interface LicenseBackend {

	/**
	 * Activate a license key against the remote service and persist the result.
	 *
	 * @return array{success: bool, message: string}
	 */
	public function activate( string $license_key ): array;

	/**
	 * Deactivate the stored license against the remote service and clear it.
	 *
	 * @return array{success: bool, message: string}
	 */
	public function deactivate( string $license_key ): array;

	/**
	 * Whether the stored license is currently valid.
	 */
	public function is_valid(): bool;

	/**
	 * Return the raw stored license array (normalised shape, or [] if none).
	 *
	 * @return array
	 */
	public function get_license(): array;
}
