<?php

namespace Formatrica\License;

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

/**
 * The license mutation surface — activate / refresh / deactivate.
 *
 * Only the Pro package ships an implementation (License_Service). Core REST and
 * admin code checks `instanceof License_Mutator_Interface` to decide whether the
 * mutating license endpoints are available, so core never names a Pro class and
 * the endpoints degrade to 404 on Free. Read-only state lives on the separate
 * License_Manager_Interface, which both Free (Null) and Pro implement.
 *
 * Each method returns an outcome array:
 *   array{success:bool, code:?string, message:?string, summary:array<string,mixed>}
 * where `summary` is the redacted License_State (never the raw key or token).
 */
interface License_Mutator_Interface
{
    /**
     * @return array{success:bool,code:?string,message:?string,summary:array<string,mixed>}
     */
    public function activate(string $license_key): array;

    /**
     * @return array{success:bool,code:?string,message:?string,summary:array<string,mixed>}
     */
    public function refresh(): array;

    /**
     * @return array{success:bool,code:?string,message:?string,summary:array<string,mixed>}
     */
    public function deactivate(): array;

    /**
     * Masked license key for display (never the raw key), or null when none.
     */
    public function masked_key(): ?string;
}
