# `Espex.HomeAssistantStates.Subscription`
[🔗](https://github.com/bbangert/espex/blob/main/lib/espex/home_assistant_states/subscription.ex#L1)

One Home Assistant entity (or one of its attributes) the device asks
Home Assistant to send the state of.

  * `entity_id` — the Home Assistant entity, such as `"sun.sun"`:
    1 to 255 bytes, containing a `.`.
  * `attribute` — an attribute of that entity, such as `"elevation"`,
    up to 255 bytes, or `nil` for the entity's state.
  * `once` — `true` asks Home Assistant for the current value only,
    instead of every change. It is a hint to the client: espex passes
    every matching state to `c:Espex.HomeAssistantStates.handle_state/3`
    either way.

Build one with `new/1` or `new!/1`, which check the fields:

    iex> Espex.HomeAssistantStates.Subscription.new!(entity_id: "sun.sun", attribute: "elevation")
    %Espex.HomeAssistantStates.Subscription{entity_id: "sun.sun", attribute: "elevation", once: false}

A wizard input link (see `Espex.Wizard.Input`) is a subscription with
`entity_id: nil`; the input's value fills it in.

# `t`
*since 0.12.0* 

```elixir
@type t() :: %Espex.HomeAssistantStates.Subscription{
  attribute: String.t() | nil,
  entity_id: String.t() | nil,
  once: boolean()
}
```

# `new`
*since 0.12.0* 

```elixir
@spec new(keyword() | map() | t()) :: {:ok, t()} | {:error, :invalid_subscription}
```

Build a subscription from a keyword list, a map, or a subscription
built by hand, checking each field.

An empty `attribute` is the same as `nil`. Returns
`{:error, :invalid_subscription}` for an unknown key or a bad value.

# `new!`
*since 0.12.0* 

```elixir
@spec new!(keyword() | map() | t()) :: t()
```

Like `new/1`, but raises `ArgumentError` naming the bad field.

---

*Consult [api-reference.md](api-reference.md) for complete listing*