# `Lather.Soap.Header`
[🔗](https://github.com/awksedgreep/lather/blob/v1.0.49/lib/lather/soap/header.ex#L1)

SOAP header utilities.

Provides functionality for creating and managing SOAP headers,
including authentication headers and custom header elements.

# `custom`

```elixir
@spec custom(String.t(), map() | String.t(), map()) :: map()
```

Creates a custom header element.

## Parameters

* `name` - Header element name
* `content` - Header content (map or string)
* `attributes` - Element attributes

## Examples

    iex> Header.custom("MyHeader", %{"value" => "test"}, %{"xmlns" => "http://example.com"})
    %{"MyHeader" => %{"@xmlns" => "http://example.com", "value" => "test"}}

# `merge_headers`

```elixir
@spec merge_headers([map()]) :: map()
```

Merges multiple header elements into a single header map.

## Parameters

* `headers` - List of header maps to merge

## Examples

    iex> header1 = Header.session("session_123")
    iex> header2 = Header.custom("MyApp", "v1.0")
    iex> Header.merge_headers([header1, header2])
    %{"SessionId" => "session_123", "MyApp" => "v1.0"}

# `session`

```elixir
@spec session(
  String.t(),
  keyword()
) :: map()
```

Creates a session header for maintaining session state.

## Parameters

* `session_id` - The session ID
* `options` - Additional options
  * `:header_name` - Custom header name (default: "SessionId")
  * `:namespace` - Custom namespace

## Examples

    iex> Header.session("session_12345")
    %{"SessionId" => "session_12345"}

# `timestamp`

```elixir
@spec timestamp(keyword()) :: map()
```

Creates a WS-Security timestamp header.

## Parameters

* `options` - Options for the timestamp
  * `:ttl` - Time to live in seconds (default: 300)

## Examples

    iex> Header.timestamp()
    %{
      "wsse:Security" => %{
        "wsu:Timestamp" => %{...}
      }
    }

# `username_token`

```elixir
@spec username_token(String.t(), String.t(), keyword()) :: map()
```

Creates a WS-Security UsernameToken header.

## Parameters

* `username` - Username for authentication
* `password` - Password for authentication
* `options` - Header options

## Options

* `:password_type` - `:text` or `:digest` (default: `:text`)
* `:include_nonce` - Whether to include a nonce (default: `true` for digest)
* `:include_created` - Whether to include timestamp (default: `true`)

## Examples

    iex> Header.username_token("user", "pass")
    %{
      "wsse:Security" => %{
        "@xmlns:wsse" => "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd",
        "wsse:UsernameToken" => %{...}
      }
    }

# `username_token_with_timestamp`

```elixir
@spec username_token_with_timestamp(String.t(), String.t(), keyword()) :: map()
```

Creates a combined WS-Security header with both UsernameToken and Timestamp.

## Parameters

* `username` - Username for authentication
* `password` - Password for authentication
* `options` - Combined options for both UsernameToken and Timestamp

## Examples

    iex> Header.username_token_with_timestamp("user", "pass")
    %{
      "wsse:Security" => %{
        "wsse:UsernameToken" => %{...},
        "wsu:Timestamp" => %{...}
      }
    }

---

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