# `Snodo.Elicitation`
[🔗](https://github.com/joshrotenberg/snodo/blob/v0.1.0/lib/snodo/elicitation.ex#L1)

Builds and validates embedded `elicitation/create` requests for MRTR.

`form/2` and `url/2` return bare input requests, without JSON-RPC envelopes.
Use `response/3` on a retried request to read only the named input response.
It does not bind a response to a user or persist state: applications must do
that using authenticated context and verified, request-specific state.

Form schemas support the protocol's flat primitive fields and single/multiple
selection enums, including titled enums and legacy `enumNames`. Unsupported
schema keywords are rejected rather than silently ignored. Validation uses
`Snodo.Schema.Validator.Basic` for common constraints and explicitly validates
enum composition and formats. Formats receive syntactic checks, not exhaustive
RFC validation: email checks address structure, URI requires an absolute URI,
and date/date-time use ISO calendar parsing with an RFC 3339-shaped timestamp.
No DNS, URL fetching, or email verification occurs.

Form mode must never request passwords, API keys, tokens, or payment secrets.
URL mode accepts HTTP(S) navigation URLs; use HTTPS outside development and
never put secrets, personal data, or pre-authenticated access in the URL.
An accepted URL response means consent to navigate, **not** completion of the
out-of-band interaction. Check completion independently on every retry.

# `request`

```elixir
@type request() :: %{required(String.t()) => term()}
```

# `response_result`

```elixir
@type response_result() :: :missing | {:ok, map()} | {:error, Snodo.Error.t()}
```

# `form`

```elixir
@spec form(String.t(), map()) :: request()
```

Builds a form input request, raising `ArgumentError` for an invalid schema.

# `response`

```elixir
@spec response(Snodo.Context.t() | map(), String.t(), request()) :: response_result()
```

Reads and validates the named response, ignoring unrelated response IDs.

Invalid responses return a generic invalid-params error without submitted data.
Missing form `content` is validated as an empty object. Content on a URL,
decline, or cancel response is checked for its flat wire shape but not used.
Additional JSON fields are preserved and ignored.
This helper does not authenticate content or trust client-echoed request state.

# `supported?`

```elixir
@spec supported?(term(), term()) :: boolean()
```

Checks the requested mode against this request's client capabilities.

# `url`

```elixir
@spec url(String.t(), String.t()) :: request()
```

Builds an HTTP(S) URL input request, raising `ArgumentError` when invalid.

# `validate_request`

```elixir
@spec validate_request(term()) :: :ok | {:error, String.t()}
```

Validates one bare elicitation input request.

---

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