# ==============================================================================
# Contact Sensor — Issue State Notification (Advanced)
# Home Assistant Blueprint for automations
# ------------------------------------------------------------------------------
# Reusable blueprint that fires push + persistent notifications when a binary
# sensor (or binary_sensor group) sits in an "issue state" (open / triggered /
# unavailable / etc.) longer than a configurable duration. Instantiate it once
# per door / window / motion sensor — the blueprint handles all the wiring
# (trigger, debounce, repeat, clear, custom actions) and you supply the
# specifics per instance.
#
# Features:
#   - Works with a single binary_sensor or a binary_sensor group
#   - Configurable issue state (on or off — open vs closed depending on sensor)
#   - Configurable duration before the alert fires (debounces quick flapping)
#   - Optional gating condition — checked AFTER the trigger fires, BEFORE the
#     notification goes out (e.g., "only alert at night," "only when armed")
#   - Auto-clear the notification when the sensor returns to non-issue state,
#     with a configurable post-clear delay
#   - Multiple notify services via a comma-separated list
#     (notify.mobile_app_phone, notify.mobile_app_tablet, ...)
#   - Configurable title, message, icon, and color (Android)
#   - iOS interruption level (passive / active / time-sensitive / critical)
#   - Optional persistent notification in the HA frontend
#   - Optional repeat reminders while the issue persists, with cadence control
#   - Custom user-defined actions for BOTH entering and leaving the issue state
#     (run a scene, flash lights, log to a notebook — anything)
#
# Install — option A (one-time via the HA UI):
#   1. Home Assistant → Settings → Automations & Scenes → Blueprints
#   2. Click "Import Blueprint" and paste this file's URL:
#      https://magikh0e.pl/pubHomeAutomation/contactSensorIssueState.yaml.txt
#   3. Preview, then Import.
#
# Install — option B (drop the file in place):
#   1. Save this file as:
#      config/blueprints/automation/magikh0e/contactSensorIssueState.yaml
#      (note: .yaml NOT .yaml.txt when saving locally)
#   2. Restart Home Assistant (or reload blueprints from the UI).
#
# Use:
#   1. Settings → Automations & Scenes → "+ Create Automation"
#   2. "Create from Blueprint" → "Contact Sensor — Issue State Notification"
#   3. Configure the trigger entity, friendly name, notify service IDs,
#      duration, and any optional fields. Save.
#
# Repeat step 2/3 for each sensor or group you want monitored — each
# instance is its own independent automation.
# ==============================================================================


blueprint:
  name: Contact Sensor — Issue State Notification (Advanced)
  description: >
    Notifies when a binary sensor (or binary_sensor group) has been in an "issue state"
    for a configurable duration. Supports optional gating condition, repeat reminders,
    auto-clearing when resolved, persistent notifications, iOS interruption levels,
    icon/color, and custom actions for both entering and leaving the issue state.
  domain: automation
  source_url: https://magikh0e.pl/pubHomeAutomation/contactSensorIssueState.yaml.txt
  input:

    # ---------- Sensor ----------
    sensor_section:
      name: Sensor
      icon: mdi:motion-sensor
      input:
        trigger_entity:
          name: Trigger Entity
          description: Binary sensor or binary_sensor group to monitor.
          selector:
            entity:
              filter:
                - domain: binary_sensor
                - domain: group

        friendly_name:
          name: Friendly Name
          description: >
            Human-readable name used in notification messages
            (e.g. "Front Door"). Available as `{{ name }}` in templates.
          default: "Sensor"
          selector:
            text:

        issue_state:
          name: Issue State
          description: Which state represents the issue.
          default: "on"
          selector:
            select:
              options:
                - label: "On (open / triggered / detected / unavailable)"
                  value: "on"
                - label: "Off (closed / clear / not detected)"
                  value: "off"

        duration_issue_state:
          name: Duration Before Alert
          description: How long the entity must remain in the issue state before alerting.
          default:
            hours: 0
            minutes: 0
            seconds: 30
          selector:
            duration:

        trigger_condition:
          name: Additional Condition (optional)
          description: >
            Optional condition checked after the duration trigger fires,
            before sending the notification. Leave empty to skip.
          default: []
          selector:
            condition:

    # ---------- Clearing ----------
    clear_section:
      name: Auto-Clear
      icon: mdi:bell-off-outline
      input:
        clear_when_not_issue:
          name: Clear Notification When Resolved
          description: Dismiss the notification when the entity leaves the issue state.
          default: true
          selector:
            boolean:

        clear_delay:
          name: Clear Delay
          description: Time after leaving the issue state before clearing the alert.
          default:
            hours: 0
            minutes: 0
            seconds: 0
          selector:
            duration:

    # ---------- Notification ----------
    notification_section:
      name: Notification
      icon: mdi:bell
      input:
        notify_services_string:
          name: Notify Services
          description: >
            Comma-separated notify services
            (e.g. `notify.mobile_app_phone, notify.mobile_app_tablet`).
          default: ""
          selector:
            text:

        notification_title:
          name: Notification Title
          default: "Sensor Alert"
          selector:
            text:

        notification_message:
          name: Notification Message
          description: Use `{{ name }}` to insert the friendly name.
          default: "{{ name }} is in the issue state."
          selector:
            text:
              multiline: true

        notification_icon:
          name: Notification Icon (Android)
          default: mdi:alert
          selector:
            icon:

        notification_color:
          name: Notification Color (Android)
          description: Hex color string, e.g. `#ff0000`.
          default: "#ff0000"
          selector:
            text:

        persistent_notification:
          name: Create Persistent (HA UI) Notification
          description: Also create a sticky notification in the HA frontend.
          default: false
          selector:
            boolean:

        ios_interruption_level:
          name: iOS Interruption Level
          default: active
          selector:
            select:
              options:
                - passive
                - active
                - time-sensitive
                - critical

        repeat_notification:
          name: Repeat Notification
          description: Resend the notification while the entity remains in the issue state.
          default: false
          selector:
            boolean:

        time_between_repeat_notification:
          name: Time Between Repeats
          default:
            hours: 0
            minutes: 10
            seconds: 0
          selector:
            duration:

    # ---------- Custom Actions ----------
    actions_section:
      name: Custom Actions
      icon: mdi:cog-outline
      input:
        custom_action_issue_state:
          name: Custom Action — Entered Issue State
          description: Runs once when the alert is first triggered.
          default: []
          selector:
            action:

        custom_action_from_issue_state:
          name: Custom Action — Left Issue State
          description: Runs once when the entity returns to a non-issue state.
          default: []
          selector:
            action:

mode: restart
max_exceeded: silent

variables:
  notify_services_string: !input notify_services_string
  notify_services: >-
    {{ notify_services_string.split(',') | map('trim') | reject('eq', '') | list }}
  name: !input friendly_name
  trigger_entity: !input trigger_entity
  issue_state_var: !input issue_state
  notification_title: !input notification_title
  notification_message_raw: !input notification_message
  notification_icon: !input notification_icon
  notification_color: !input notification_color
  ios_interruption_level: !input ios_interruption_level
  persistent: !input persistent_notification
  repeat_enabled: !input repeat_notification
  clear_enabled: !input clear_when_not_issue
  notif_tag: "bp_issue_{{ trigger_entity | replace('.', '_') }}"

trigger:
  - platform: state
    entity_id: !input trigger_entity
    to: !input issue_state
    for: !input duration_issue_state
    id: entered_issue
  - platform: state
    entity_id: !input trigger_entity
    from: !input issue_state
    id: left_issue

condition: []

action:
  - choose:

      # ===== ENTERED ISSUE STATE =====
      - conditions:
          - condition: trigger
            id: entered_issue
          - condition: !input trigger_condition
        sequence:

          # 1. Send to all configured notify services
          - repeat:
              for_each: "{{ notify_services }}"
              sequence:
                - service: "{{ repeat.item }}"
                  data:
                    title: "{{ notification_title }}"
                    message: "{{ notification_message_raw }}"
                    data:
                      tag: "{{ notif_tag }}"
                      group: "blueprint_issue_alerts"
                      notification_icon: "{{ notification_icon }}"
                      color: "{{ notification_color }}"
                      push:
                        interruption-level: "{{ ios_interruption_level }}"

          # 2. Persistent UI notification (optional)
          - if:
              - condition: template
                value_template: "{{ persistent }}"
            then:
              - action: persistent_notification.create
                data:
                  notification_id: "{{ notif_tag }}"
                  title: "{{ notification_title }}"
                  message: "{{ notification_message_raw }}"

          # 3. Custom user-defined action
          - choose: []
            default: !input custom_action_issue_state

          # 4. Repeat loop while entity stays in issue state
          - if:
              - condition: template
                value_template: "{{ repeat_enabled }}"
            then:
              - repeat:
                  while:
                    - condition: state
                      entity_id: !input trigger_entity
                      state: !input issue_state
                  sequence:
                    - delay: !input time_between_repeat_notification
                    - condition: state
                      entity_id: !input trigger_entity
                      state: !input issue_state
                    - repeat:
                        for_each: "{{ notify_services }}"
                        sequence:
                          - service: "{{ repeat.item }}"
                            data:
                              title: "{{ notification_title }}"
                              message: "{{ notification_message_raw }}"
                              data:
                                tag: "{{ notif_tag }}"
                                group: "blueprint_issue_alerts"
                                notification_icon: "{{ notification_icon }}"
                                color: "{{ notification_color }}"
                                push:
                                  interruption-level: "{{ ios_interruption_level }}"

      # ===== LEFT ISSUE STATE =====
      - conditions:
          - condition: trigger
            id: left_issue
        sequence:

          # 1. Wait the configured clear delay
          - delay: !input clear_delay

          # 2. Clear the mobile notification(s) if enabled
          - if:
              - condition: template
                value_template: "{{ clear_enabled }}"
            then:
              - repeat:
                  for_each: "{{ notify_services }}"
                  sequence:
                    - service: "{{ repeat.item }}"
                      data:
                        message: "clear_notification"
                        data:
                          tag: "{{ notif_tag }}"

              # Dismiss persistent notification (if it was created)
              - if:
                  - condition: template
                    value_template: "{{ persistent }}"
                then:
                  - action: persistent_notification.dismiss
                    data:
                      notification_id: "{{ notif_tag }}"

          # 3. Custom user-defined action
          - choose: []
            default: !input custom_action_from_issue_state