<?php

namespace App\Support\Drivers;

use App\Models\Device;
use App\Models\Entity;

/**
 * Protocol-agnostic device control contract. v1 implements ShellyMqttDriver; every other
 * integration is a later driver behind this same interface — this is what keeps the system
 * usable "for all products". The UI never talks to a driver directly (H1) — it goes through
 * DeviceCommandService.
 */
interface DeviceDriver
{
    public function turnOn(Entity $entity): void;

    public function turnOff(Entity $entity): void;

    /** Apply a desired state (e.g. ['on' => true]). */
    public function setState(Entity $entity, array $state): void;

    /** Set a light: ['on' => bool, 'brightness' => 0-100, 'rgb' => [r,g,b]]. */
    public function setLight(Entity $entity, array $params): void;

    /** Reboot the whole device. */
    public function reboot(Device $device): void;

    /** Entity types this driver can control. */
    public function capabilities(): array;
}