# `TypeSafeAPI.Result`
[🔗](https://github.com/typesend/typesafe_ai/blob/v0.1.0-alpha.3/lib/typesafe_api/result.ex#L1)

A fully decoded response: every answer keyed by the caller's own question
ids, plus usage and the raw decoded body for anything this layer doesn't
expose yet.

Decoding is strict about the envelope (`model` must be present and a string,
every question must have an answer, every answer must agree with its
question) but permissive in two places: an answer the caller never asked for
is dropped from `answers` and stays reachable through `raw`, and a missing or
malformed `usage` decodes to a `TypeSafeAPI.Usage` with `nil` counts rather
than failing a complete set of answers. The spec marks `usage` required with
both token counts required, so the tolerance is defensive, not permission.

`retry_count` is how many retries the call burned before this response (0 when
the first attempt succeeded). `request_id` is the `x-typesafe-request-id` response header, the value
TypeSafe support asks for. `TypeSafeAPI.Error` carries the same field for
failed calls, including for a body that failed to decode here.

`raw` holds the whole decoded body, so a result carries a second copy of
everything `answers` already holds. `inspect/1` elides it: read
`result.raw` directly when you want it.

# `t`

```elixir
@type t() :: %TypeSafeAPI.Result{
  answers: %{required(TypeSafeAPI.Keys.key()) => TypeSafeAPI.Answer.t()},
  model: String.t(),
  raw: map(),
  request_id: String.t() | nil,
  retry_count: non_neg_integer(),
  usage: TypeSafeAPI.Usage.t()
}
```

# `decode`

```elixir
@spec decode(
  map(),
  [{TypeSafeAPI.Keys.key(), TypeSafeAPI.Question.t()}],
  TypeSafeAPI.Keys.t(),
  String.t() | nil
) :: {:ok, t()} | {:error, TypeSafeAPI.Error.t()}
```

Decodes a response body against the questions that were sent.

`questions` is the normalized `[{id, question}]` list (see
`TypeSafeAPI.Question.normalize/1`) and `keys` is the `TypeSafeAPI.Keys` built
from it, so answers come back keyed and valued under the caller's own ids.

`request_id` is the `x-typesafe-request-id` header of the response being
decoded. It lands on the `TypeSafeAPI.Result` on success and on the
`TypeSafeAPI.Error` on failure, so a decode mismatch — the one failure that
needs a support ticket — can be quoted. `decode/3` passes `nil`.

---

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