# `ExWapp.Pairing.LinkCode`
[🔗](https://github.com/elchemista/ex_wapp/blob/v0.1.5/lib/ex_wapp/pairing/link_code.ex#L1)

Implements WhatsApp's phone-number (link-code) companion pairing protocol.

The request side wraps a fresh companion ephemeral public key with the
eight-character pairing code. The finish side unwraps the primary phone's
ephemeral key, derives the authenticated key bundle, rotates the ADV secret,
and persists enough account state for the reconnect/login that follows.

# `finish_result`

```elixir
@type finish_result() :: %{
  jid: String.t(),
  node: ExWapp.Binary.Node.t(),
  adv_secret: binary(),
  data: map()
}
```

# `request_result`

```elixir
@type request_result() :: %{
  code: String.t(),
  jid: String.t(),
  request_id: String.t(),
  node: ExWapp.Binary.Node.t()
}
```

# `crockford_encode`

```elixir
@spec crockford_encode(binary()) :: String.t()
```

Encodes bytes with WhatsApp's Crockford alphabet.

# `derive_pairing_code_key`

```elixir
@spec derive_pairing_code_key(binary(), binary()) :: binary()
```

Derives the AES key used to wrap link-code ephemeral public keys.

# `finish`

```elixir
@spec finish(ExWapp.Store.t(), ExWapp.Binary.Node.t()) ::
  {:ok, finish_result()} | {:error, term()}
```

Completes a pending link-code pairing from a server notification.

The returned `node` is the `companion_finish` IQ that must be sent before the
server's expected reconnect. Credential persistence is completed before this
function returns.

# `request`

```elixir
@spec request(ExWapp.Store.t(), String.t(), keyword(), map()) ::
  {:ok, request_result()} | {:error, term()}
```

Starts a link-code pairing request and persists its ephemeral credentials.

A custom code follows the upstream contract: it must be exactly eight bytes.
When omitted, five random bytes are encoded with WhatsApp's Crockford
alphabet, producing an eight-character code.

---

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