"""Switch Capability - Wireless Button/Switch (read-only).

This module defines the SwitchState model for wireless switches/buttons.
These devices report action events (e.g., button presses) and are read-only devices.

Capability Version: switch@1.0.0
"""

from datetime import datetime
from typing import Annotated

from pydantic import BaseModel, Field


# Capability metadata
CAP_VERSION = "switch@1.0.0"
DISPLAY_NAME = "Switch"


class SwitchState(BaseModel):
    """State model for wireless switches/buttons.
    
    Wireless switches are read-only devices that report button actions such as
    single press, double press, long press, etc. They typically also report 
    battery level and signal quality.
    
    Attributes:
        action: Action type (e.g., "single", "double", "long", "hold", etc.)
        battery: Battery level percentage (0-100), optional
        linkquality: MQTT link quality indicator, optional
        voltage: Battery voltage in mV, optional
        ts: Timestamp of the action event, optional
    
    Examples:
        >>> SwitchState(action="single")
        SwitchState(action='single', battery=None, ...)
        
        >>> SwitchState(action="double", battery=95, linkquality=87)
        SwitchState(action='double', battery=95, linkquality=87, ...)
    """
    
    action: str = Field(
        ...,
        description="Action type: 'single', 'double', 'long', 'hold', etc."
    )
    
    battery: Annotated[int, Field(ge=0, le=100)] | None = Field(
        None,
        description="Battery level in percent (0-100)"
    )
    
    linkquality: int | None = Field(
        None,
        description="Link quality indicator (typically 0-255)"
    )
    
    voltage: int | None = Field(
        None,
        description="Battery voltage in millivolts"
    )
    
    ts: datetime | None = Field(
        None,
        description="Timestamp of the action event"
    )


# Public API
__all__ = ["SwitchState", "CAP_VERSION", "DISPLAY_NAME"]