#:########################################################################################:#
# Alexa TP-Link Guest Wi-Fi Package                                                      #
#:########################################################################################:#
#
# TITLE:
#   Alexa TP-Link Guest Wi-Fi
#
# FILE:
#   packages/alexa_tplink_actions.yaml
#
# VERSION:
#   V1.1 2026-07-20
#
# VERSION HISTORY:
#   V1.1 2026-07-20
#     - Added structured documentation and automation descriptions.
#
#   V1.0
#     - Initial Alexa-mediated TP-Link guest-network controls.
#
# PURPOSE:
#   Enables or disables the TP-Link guest Wi-Fi network by sending custom Alexa
#   requests through the kitchen Echo Show.
#
# DEPENDENCIES:
#   - input_boolean.wifi_guest_network is a UI-managed helper that represents
#     the requested guest-network state.
#   - media_player.view_rd_kitchen_echo_show must be available through the Alexa
#     Media Player integration.
#   - The Alexa account must have a working, linked TP-Link skill.
#
# ALEXA REQUESTS:
#   - On:  ask t.p.link to enable guest network
#   - Off: ask t.p.link to disable guest network
#
# OPERATION NOTES:
#   - The helper records requested state; it does not confirm router state.
#   - If Alexa or the TP-Link skill fails, the helper can disagree with the
#     actual guest-network state.
#   - After the helper remains on for two hours, it is turned off. That state
#     change then sends the Alexa disable request.
#   - The two-hour state-trigger period does not persist through a Home Assistant
#     restart or automation reload.
#
#:########################################################################################:#

automation:
  - alias: "Turn on the Wifi Guest Network"
    description: "Asks the linked TP-Link Alexa skill to enable the guest Wi-Fi network."
    mode: single
    triggers:
      - trigger: state
        entity_id: input_boolean.wifi_guest_network
        to: "on"
    actions:
      - action: media_player.play_media
        target:
          entity_id: media_player.view_rd_kitchen_echo_show
        data:
          media_content_type: custom
          media_content_id: ask t.p.link to enable guest network

  - alias: "Turn off the Wifi Guest Network"
    description: "Asks the linked TP-Link Alexa skill to disable the guest Wi-Fi network."
    mode: single
    triggers:
      - trigger: state
        entity_id: input_boolean.wifi_guest_network
        to: "off"
    actions:
      - action: media_player.play_media
        target:
          entity_id: media_player.view_rd_kitchen_echo_show
        data:
          media_content_type: custom
          media_content_id: ask t.p.link to disable guest network

  - alias: "Switch guest network off after time"
    description: "Turns off the guest-network helper after it remains on for two hours."
    mode: single
    triggers:
      - trigger: state
        entity_id: input_boolean.wifi_guest_network
        from: "off"
        to: "on"
        for: "02:00:00"
    conditions: []
    actions:
      - action: input_boolean.turn_off
        target:
          entity_id: input_boolean.wifi_guest_network