# `Tink.AuthToken`
[🔗](https://github.com/iamkanishka/tink.ex/blob/v0.1.1/lib/tink/auth_token.ex#L1)

Token expiration and management utilities.

Provides functions for:
- Checking token expiration
- Calculating time until expiration
- Token caching

## Examples

    iex> expires_at = DateTime.add(DateTime.utc_now(), 3600)
    iex> Tink.AuthToken.expired?(expires_at)
    false

    iex> Tink.AuthToken.expires_soon?(expires_at)
    false

    iex> Tink.AuthToken.time_until_expiration(expires_at)
    {:ok, 3600}

# `buffer_seconds`

```elixir
@spec buffer_seconds() :: 300
```

Gets the buffer period in seconds.

## Examples

    iex> Tink.AuthToken.buffer_seconds()
    300

# `calculate_expiration`

```elixir
@spec calculate_expiration(integer()) :: DateTime.t()
```

Calculates expiration time from expires_in seconds.

## Examples

    iex> Tink.AuthToken.calculate_expiration(3600)
    %DateTime{...}  # ~1 hour from now

# `expired?`

```elixir
@spec expired?(DateTime.t() | nil) :: boolean()
```

Checks if a token has expired.

Returns `true` if the token is expired or will expire within the buffer period.

## Examples

    iex> future = DateTime.add(DateTime.utc_now(), 3600)
    iex> Tink.AuthToken.expired?(future)
    false

    iex> past = DateTime.add(DateTime.utc_now(), -60)
    iex> Tink.AuthToken.expired?(past)
    true

    iex> Tink.AuthToken.expired?(nil)
    true

# `expires_soon?`

```elixir
@spec expires_soon?(DateTime.t() | nil) :: boolean()
```

Checks if a token will expire soon (within buffer period).

## Examples

    iex> soon = DateTime.add(DateTime.utc_now(), 200)
    iex> Tink.AuthToken.expires_soon?(soon)
    true

    iex> later = DateTime.add(DateTime.utc_now(), 3600)
    iex> Tink.AuthToken.expires_soon?(later)
    false

# `parse_expiration`

```elixir
@spec parse_expiration(map()) :: DateTime.t() | nil
```

Parses a token response and extracts expiration time.

## Examples

    iex> response = %{"expires_in" => 3600, "access_token" => "token"}
    iex> Tink.AuthToken.parse_expiration(response)
    %DateTime{...}

# `time_until_expiration`

```elixir
@spec time_until_expiration(DateTime.t() | nil) :: {:ok, integer()} | {:error, atom()}
```

Returns the number of seconds until token expiration.

## Examples

    iex> future = DateTime.add(DateTime.utc_now(), 3600)
    iex> {:ok, seconds} = Tink.AuthToken.time_until_expiration(future)
    iex> seconds > 3500
    true

    iex> Tink.AuthToken.time_until_expiration(nil)
    {:error, :no_expiration}

---

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