# `TelemetryDeck.Signal`
[🔗](https://github.com/boldflight/telemetry-deck-elixir/blob/v0.1.0/lib/telemetry_deck/signal.ex#L1)

Builds TelemetryDeck Ingest API v2 signals.

Payload values must be flat JSON primitives. Atom payload values are converted
to strings, and nil values are omitted.

# `primitive`
*since 0.1.0* 

```elixir
@type primitive() :: String.t() | number() | boolean()
```

Flat JSON primitive accepted in a TelemetryDeck payload.

# `t`
*since 0.1.0* 

```elixir
@type t() :: %TelemetryDeck.Signal{
  client_user: String.t(),
  float_value: nil | number(),
  payload: %{optional(String.t()) => primitive()},
  session_id: nil | String.t(),
  type: String.t()
}
```

TelemetryDeck Ingest API v2 signal.

# `new`
*since 0.1.0* 

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

Builds a `TelemetryDeck.Signal`.

Required options are `:type` and `:client_user`. Optional values are
`:session_id`, `:float_value`, and `:payload`.

## Examples

    iex> {:ok, signal} =
    ...>   TelemetryDeck.Signal.new(
    ...>     type: "App.User.signedIn",
    ...>     client_user: "user-hash",
    ...>     payload: %{"App.Plan.name" => :pro, ignored: nil}
    ...>   )
    iex> signal.payload
    %{"App.Plan.name" => "pro"}

    iex> TelemetryDeck.Signal.new(type: "App.User.signedIn", client_user: "user-hash", payload: %{"App.Data" => %{nested: true}})
    {:error, %{payload: "must be a flat map of primitive values"}}

# `new!`
*since 0.1.0* 

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

Builds a `TelemetryDeck.Signal` or raises `ArgumentError`.

# `to_map`
*since 0.1.0* 

```elixir
@spec to_map(
  t(),
  keyword()
) :: map()
```

Converts a `TelemetryDeck.Signal` to an Ingest API v2 JSON map.

## Examples

    iex> signal = TelemetryDeck.Signal.new!(type: "App.started", client_user: "user-hash")
    iex> map = TelemetryDeck.Signal.to_map(signal, app_id: "APP-ID", is_test_mode: true)
    iex> {map["appID"], map["clientUser"], map["type"], map["isTestMode"]}
    {"APP-ID", "user-hash", "App.started", true}

---

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